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); ini adalah referensi mandiri yang dikirim bersama repo yang dipublikasikan. Dasar pemikiran arsitektural dicatat di ADR-0003.

1. Mengapa Jamak

Sebuah permukaan rekayasa modern disentuh oleh banyak runtime asisten-pengkodean — konsol chat, mesin autolengkap dalam-IDE, pendamping pemrograman berpasangan, dan peninjau pull request. Masing-masing membaca file konfigurasi kanoniknya sendiri. Jika proyek hanya mengirim satu file semacam itu, runtime lainnya secara diam-diam berimprovisasi terhadap konvensi yang tak dinyatakan; memori dalam-repo yang hilang langsung bocor.

Biaya dari permukaan yang hilang adalah drift senyap pada kode yang dihasilkan mesin — jenis cacat terburuk karena terakumulasi tanpa terlihat. Setiap artefak yang dihasilkan mesin memperparah perbedaan; pada saat peninjau manusia melihat kontradiksi, basis kode sudah membawa berminggu-minggu konvensi yang tak konsisten.

Konfigurasi runtime pengkodean bersifat jamak menurut realitas deployment. Ekosistem yang dipublikasikan HARUS mengirim file memori-perilaku untuk runtime konsol-chat DAN file instruksi bercakupan-repo untuk runtime autolengkap dalam-IDE. Kedua permukaan itu HARUS saling koheren — tanpa kontradiksi, tanpa drift — dan HARUS bersama-sama mengkodekan disiplin yang sama.

2. Kontrak Koherensi

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

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

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

Kedua (atau lebih) permukaan itu adalah kanal berbeda yang mengekspresikan satu spesifikasi. Bagian bersama HARUS cocok — secara semantik dan, di mana mungkin, secara leksikal — di seluruh permukaan. Bagian khusus-permukaan TIDAK BOLEH bertentangan dengan bagian bersama.

3. Permukaan dalam Cakupan

Untuk keterlibatan ini operator opt-in ke permukaan asisten opsional yang dicatat oleh fixture. Konfigurasi akar khusus-vendor yang tak terpakai sengaja absen; file konfigurasi khusus-tool ditambahkan hanya ketika tool tersebut menjadi permukaan penyuntingan aktif untuk repositori ini.

4. Daftar Bagian untuk File Instruksi Dalam-IDE

File instruksi bercakupan-repo di bawah .github/ HARUS memuat, dalam urutan ini, bagian-bagian berikut (masing-masing dengan teks judul persis di bawah; isi bagian ditulis sendiri, bukan distempel-template, tetapi masing-masing HARUS mencakup klaim yang terdaftar):

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

3. File Headers — setiap file yang dihasilkan runtime HARUS dimulai dengan baris tunggal kanonik SPDX-License-Identifier: MIT per site/content/docs/reference/authorship-header.mdx, dalam varian komentar yang cocok dengan tipe file. 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 plans global lainnya. Artefak perencanaan masuk ke <project-root>/.apothem/plans/ (pohon <project-root>/.plans/ lama dimutakhirkan via apothem migrate-workspace) per site/content/docs/reference/plans-discipline.mdx.
5. Structured Inquiry Behavior — ketika runtime tidak pasti, ia TIDAK BOLEH secara diam-diam mengarang. Sebagai gantinya ia menyisipkan blok klarifikasi yang ditandai jelas (mis., komentar # TODO(clarify): <question>) dan memunculkan pertanyaan di chat di mana permukaan mengizinkan. Tanpa API yang dikarang, tanpa nama model yang dikarang, tanpa jalur file yang dikarang.
6. Forbidden Patterns — larangan eksplisit: tanpa kata sifat pemasaran, tanpa pengisi yang mengelak, tanpa sampah debug console.log, tanpa jalur absolut hard-coded ke home pengguna, tanpa commit rahasia, tanpa commit file di bawah .apothem/plans/ (atau .plans/ lama), tanpa bertentangan dengan file instruksi proyek kanonik.
7. Output Format — kode/prosa yang dihasilkan sesuai dengan konvensi keluaran percakapan terpadu: ketegasan, pembagian-bagian seragam, kepadatan, disiplin ringkasan, sitasi. Untuk kode: permukaan publik terdokumentasi, bertipe di mana bahasa mendukung tipe, teruji di mana scaffolding pengujian ada.
8. Review Checklist — apa yang HARUS diverifikasi peninjau (manusia atau runtime dalam mode tinjauan-PR) sebelum menyetujui: header ada, penamaan patuh, tanpa tulisan ke .apothem/plans/, tanpa kontradiksi dengan file 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, schemas/, dan CONTRIBUTING.md.

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

File instruksi 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 file instruksi dalam-IDE disuarakan untuk runtime autolengkap-kode dalam-editor yang memancarkan saran yang diterima atau ditolak pengembang. Informasi-nya (disiplin, konvensi, anti-pola) identik; pembingkaian-nya berbeda.

5. Referensi Daftar Klaim

Fixture di tests/fixtures/multi-surface-claims.yaml menyebutkan 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 authorship-header banner per site/content/docs/reference/authorship-header.mdx."
  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-permukaan setiap klaim (via hierarki judul + ekstraksi kata kunci isi), dan gagal pada setiap kelewatan atau kontradiksi.

6. Aturan Rekonsiliasi

Ketika dua permukaan terdeteksi bertentangan pada klaim bersama, rekonsiliasi default adalah:

AGENTS.md adalah suara proyek kanonik. Permukaan apa pun yang bertentangan ditulis ulang untuk mencerminkan semantik AGENTS.md dalam pembingkaian yang sesuai-permukaan.

Penimpaan khusus-permukaan diizinkan hanya dengan penanda dalam-file eksplisit <!-- coherence-override: <claim-id> --> yang menunjuk ke ADR yang menjelaskan perbedaan yang disengaja. 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 kanonik, dan setiap cermin harness aktif tetap setara secara semantik.

7. Validator

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)

• Yang pertama menegaskan file instruksi dalam-IDE ada, terurai, memuat setiap bagian kanonik yang disebut dalam §4, dan dimulai dengan banner kepengarangan kanonik.
• Yang kedua mengurai bagian-bagian kanonik tiap permukaan; menegaskan bagian bersama saling konsisten di bawah komparator yang dinormalisasi (tak peka-huruf, toleran-spasi, mengizinkan parafrase leksikal tetapi mensyaratkan kesetaraan semantik pada daftar klaim yang didefinisikan-fixture).
• Yang ketiga menegaskan baris hak cipta LICENSE dan baris "Copyright (c)" banner kanonik menyebut penulis yang sama.

8. Daur Hidup Permukaan

• Tambah permukaan. Operator opt-in via kanal kueri terstruktur atau via make surfaces-add <name> berikutnya. Generator menulis permukaan terhadap daftar klaim, menjalankan validator, mengajukan ADR jika diperlukan penimpaan khusus-permukaan.
• Hapus permukaan. Kueri terstruktur mengonfirmasi penghapusan, ADR mencatat dasar pemikiran, daftar required-in validator diubah.
• Deteksi drift. Setiap commit yang menyimpang dari daftar klaim ditolak oleh pre-commit / CI; penulis commit menulis ulang permukaan untuk memulihkan koherensi.

Lihat Juga

• 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 Claude Code.
• site/content/docs/reference/plans-discipline.mdx — referensi kanonik klaim bersama Disiplin Plans.
• site/content/docs/reference/authorship-header.mdx — referensi kanonik klaim bersama Header Kepengarangan.
• Spesifikasi proyek §0.6 + §2.8 + §4.7 — teks kanonik penuh yang dicerminkan di sini.