Konvensi Harness Multi-Permukaan

Referensi normatif kanonik untuk kontributor hilir. Dokumen ini mencerminkan bagian Konvensi Harness Multi-Permukaan dari spesifikasi proyek (Spec §0.6 + §2.8 + §4.7); dokumen ini adalah referensi mandiri yang dikirimkan bersama repo yang dipublikasikan. Dasar pemikiran arsitekturalnya dicatat di ADR-0003.

1. Mengapa JamakCopy Anchor Link

Permukaan rekayasa modern disentuh oleh beberapa harness — konsol chat, mesin pelengkapan di dalam IDE, pendamping pemrograman berpasangan, dan peninjau pull request. Masing-masing membaca berkas konfigurasi kanoniknya sendiri. Jika proyek hanya mengirimkan satu berkas semacam itu, runtime lainnya diam-diam berimprovisasi terhadap konvensi yang tidak dinyatakan; memori dalam repo yang hilang itu langsung bocor.

Biaya dari permukaan yang hilang adalah penyimpangan senyap pada kode yang dihasilkan mesin — kelas cacat terburuk karena menumpuk tanpa terlihat. Setiap artefak yang dihasilkan mesin memperparah divergensi itu; pada saat peninjau manusia melihat kontradiksinya, basis kode sudah membawa konvensi yang tidak konsisten selama berminggu-minggu.

Konfigurasi runtime harness bersifat jamak karena realitas deployment. Ekosistem yang dipublikasikan HARUS mengirimkan tiga permukaan wajib di §3: AGENTS.md, berkas memori perilaku untuk runtime konsol chat (CLAUDE.md), dan berkas instruksi berlingkup repo untuk runtime pelengkapan di dalam IDE. Permukaan-permukaan itu HARUS saling koheren — tanpa kontradiksi, tanpa penyimpangan — dan HARUS bersama-sama mengodekan disiplin yang sama.

2. Kontrak KoherensiCopy Anchor Link

Setiap permukaan konvensi dalam cakupan (§3) adalah sebuah kanal yang mengekspresikan satu spesifikasi konvensi proyek. Spesifikasi itu diuraikan menjadi:

• Bagian bersama — Disiplin Plan, kueri terstruktur (atau padanannya pada permukaan tersebut), Header Kepengarangan, Penamaan, Anti-Pola, Hierarki Modal. Bagian-bagian ini HARUS muncul di setiap permukaan yang diwajibkan dan HARUS setara secara semantik di semua permukaan.
• Bagian khusus permukaan — pembingkaian kapabilitas, pola pemanggilan tool, perbedaan codegen vs. chat. Bagian-bagian ini BOLEH berbeda antarpermukaan tetapi TIDAK BOLEH bertentangan dengan bagian bersama.

Validator multi-surface-coherence (§7) dijalankan pada setiap eksekusi CI dan pada pre-commit, untuk menegaskan kontrak tersebut.

Permukaan-permukaan itu adalah kanal berbeda yang mengekspresikan satu spesifikasi. Bagian bersama HARUS cocok — secara semantik dan, jika memungkinkan, secara leksikal — di semua permukaan. Bagian khusus permukaan TIDAK BOLEH bertentangan dengan bagian bersama.

3. Permukaan dalam CakupanCopy Anchor Link

Untuk repositori ini, permukaan opt-in adalah permukaan yang dicantumkan fixture daftar klaim (tests/fixtures/multi-surface-claims.yaml) di bawah optional-in. Konfigurasi root khusus vendor yang tidak digunakan sengaja tidak disertakan; berkas konfigurasi khusus tool ditambahkan hanya ketika tool tersebut menjadi permukaan penyuntingan aktif untuk repositori ini.

4. Daftar Bagian untuk Berkas Instruksi di Dalam IDECopy Anchor Link

Berkas instruksi berlingkup repo di bawah .github/ HARUS memuat, dalam urutan ini, bagian-bagian berikut (masing-masing dengan teks heading persis seperti di bawah; isi bagian ditulis, bukan dicap dari templat, tetapi masing-masing HARUS mencakup klaim yang tercantum):

1. Project Context — satu paragraf: apa repositori ini, siapa yang menggunakannya, bentuk tingkat atasnya. Konkret; tanpa bahasa pemasaran.
2. Coding Conventions — penamaan, hierarki modal, frontmatter, gaya markdown, poin gaya khusus bahasa yang berbeda dari default.

3. File Headers — setiap berkas yang dihasilkan runtime HARUS diawali dengan satu baris kanonik SPDX-License-Identifier: MIT sesuai site/content/docs/reference/authorship-header.mdx, dalam varian komentar yang cocok dengan tipe berkas. Penunjuk ke scripts/inject-header.* dan site/content/docs/reference/authorship-header.mdx.

4. Plans Discipline — runtime TIDAK BOLEH menghasilkan kode atau skrip yang menulis ke direktori konfigurasi harness (misalnya ~/.claude/plans/ atau ~/.codex/.plans/) atau lokasi rencana global lainnya. Artefak perencanaan ditempatkan di <project-root>/.apothem/plans/ (pohon <project-root>/.plans/ warisan ditingkatkan melalui apothem migrate-workspace) sesuai site/content/docs/reference/plans-discipline.mdx.
5. Structured Inquiry Behavior — ketika runtime tidak yakin, runtime TIDAK BOLEH diam-diam mengarang. Sebagai gantinya, runtime menyisipkan blok klarifikasi yang ditandai dengan jelas (mis., komentar # TODO(clarify): <question>) dan memunculkan pertanyaan itu di chat jika permukaan tersebut memungkinkan. Tidak ada API yang dikarang, tidak ada nama model yang dikarang, tidak ada jalur berkas yang dikarang.
6. Forbidden Patterns — larangan eksplisit: tanpa kata sifat pemasaran, tanpa pengisi yang mengelak, tanpa sisa debug console.log, tanpa jalur absolut yang di-hardcode ke direktori home pengguna, tanpa meng-commit rahasia, tanpa meng-commit berkas di bawah .apothem/plans/ (atau .plans/ warisan), tanpa bertentangan dengan berkas instruksi proyek kanonik.
7. Output Format — kode/prosa yang dihasilkan mematuhi konvensi keluaran percakapan terpadu: ketegasan, pembagian bagian yang seragam, kepadatan, disiplin ringkasan, sitasi. Untuk kode: permukaan publik terdokumentasi, bertipe jika bahasanya mendukung tipe, teruji jika perancah pengujian tersedia.
8. Review Checklist — apa yang HARUS diverifikasi peninjau (manusia atau runtime dalam mode tinjauan PR) sebelum menyetujui: header ada, penamaan patuh, tidak ada penulisan ke .apothem/plans/, tidak ada kontradiksi dengan berkas instruksi proyek kanonik, validator hijau secara lokal.
9. Pointers — tautan ke AGENTS.md, CLAUDE.md, site/content/docs/reference/plans-discipline.mdx, site/content/docs/reference/authorship-header.mdx, dokumen konvensi ini, src/apothem/schemas/, dan CONTRIBUTING.md.

Berkas ini diawali dengan baris SPDX header kepengarangan kanonik (varian Markdown) sesuai site/content/docs/reference/authorship-header.mdx §2 — terlihat atau tak terlihat sesuai kebijakan visibilitas header yang dipilih proyek.

Berkas instruksi di dalam IDE bukan salinan verbatim dari AGENTS.md atau CLAUDE.md. AGENTS.md adalah permukaan instruksi proyek kanonik, CLAUDE.md mencerminkannya untuk Claude Code, dan berkas instruksi di dalam IDE disuarakan untuk runtime pelengkapan kode di dalam editor yang memancarkan saran untuk diterima atau ditolak pengembang. Informasi-nya (disiplin, konvensi, anti-pola) identik; pembingkaian-nya berbeda.

5. Referensi Daftar KlaimCopy Anchor Link

Fixture di tests/fixtures/multi-surface-claims.yaml mencantumkan setiap klaim bersama. Contoh entri:

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

Validator mengurai setiap permukaan, mencoba menemukan keberadaan setiap klaim pada permukaan itu (melalui hierarki heading + ekstraksi kata kunci dari isi), dan gagal pada setiap klaim yang tidak ditemukan atau kontradiksi apa pun.

6. Aturan RekonsiliasiCopy Anchor Link

Ketika dua permukaan terdeteksi saling bertentangan pada sebuah klaim bersama, rekonsiliasi default-nya adalah:

AGENTS.md adalah suara proyek kanonik. Setiap permukaan yang bertentangan ditulis ulang untuk mencerminkan semantik AGENTS.md dalam pembingkaian yang sesuai dengan permukaannya.

Penimpaan khusus permukaan hanya diizinkan dengan penanda <!-- coherence-override: <claim-id> --> yang eksplisit di dalam berkas dan menunjuk ke ADR yang menjelaskan divergensi yang disengaja itu. Penanda penimpaan itu sendiri tercantum dalam daftar izin validator dan muncul dalam laporan CI.

Untuk repositori ini, strategi rekonsiliasi yang diratifikasi adalah agents-md-wins: AGENTS.md bersifat kanonik, dan setiap cermin harness yang aktif tetap setara secara semantik.

7. ValidatorCopy Anchor Link

Tiga validator bersama-sama mengimplementasikan kontrak koherensi:

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• Validator pertama menegaskan bahwa berkas instruksi di dalam IDE ada, dapat diurai, memuat setiap bagian kanonik yang dicantumkan di §4, dan diawali dengan baris SPDX-License-Identifier: MIT kanonik (varian Markdown).
• Validator kedua mengurai bagian-bagian kanonik setiap permukaan; validator ini menegaskan bahwa bagian bersama saling konsisten menurut komparator yang dinormalisasi (tidak peka huruf besar-kecil, toleran terhadap spasi, mengizinkan parafrase leksikal tetapi mensyaratkan kesetaraan semantik pada daftar klaim yang didefinisikan fixture).
• Validator ketiga hanya menegaskan bahwa LICENSE di root memuat baris Copyright (c) <name> yang dapat diurai. Validator ini tidak membaca header per berkas, yang tidak memuat nama penulis.

8. Siklus Hidup PermukaanCopy Anchor Link

• Menambahkan permukaan. Operator memilih ikut melalui kanal kueri terstruktur. Generator menulis permukaan tersebut berdasarkan daftar klaim, menjalankan validator, dan mengajukan ADR jika diperlukan penimpaan khusus permukaan.
• Menghapus permukaan. Kueri terstruktur mengonfirmasi penghapusan, ADR mencatat dasar pemikirannya, dan daftar required-in milik validator diubah.
• Deteksi penyimpangan. Setiap commit yang menyimpang dari daftar klaim ditolak oleh pre-commit / CI; penulis commit tersebut menulis ulang permukaannya untuk memulihkan koherensi.

Lihat JugaCopy Anchor Link

• ADR-0003 — dasar pemikiran arsitektural, alternatif yang dipertimbangkan.
• tests/fixtures/multi-surface-claims.yaml — fixture daftar klaim kanonik.
• AGENTS.md — suara proyek kanonik.
• CLAUDE.md — cermin untuk Claude Code.
• site/content/docs/reference/plans-discipline.mdx — referensi kanonik untuk klaim bersama Disiplin Plan.
• site/content/docs/reference/authorship-header.mdx — referensi kanonik untuk klaim bersama Header Kepengarangan.
• Spesifikasi proyek §0.6 + §2.8 + §4.7 — teks kanonik lengkap yang dicerminkan di sini.