pakem-cli 0.0.0-stage → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +280 -0
  2. package/LICENSE +21 -0
  3. package/README-ID.md +666 -0
  4. package/README.md +665 -2
  5. package/SKILL.md +264 -0
  6. package/adapters/git-worktree/v1/README.md +17 -0
  7. package/adapters/identity/v1/README.md +26 -0
  8. package/adapters/mcp/v1/README.md +56 -0
  9. package/adapters/storage-sqlite/v1/README.md +5 -0
  10. package/assets/banner.svg +275 -0
  11. package/assets/divider.svg +82 -0
  12. package/assets/footer.svg +174 -0
  13. package/assets/templates/BUG-HISTORY.md +18 -0
  14. package/assets/templates/CONTEXT.md +26 -0
  15. package/assets/templates/DECISIONS.md +8 -0
  16. package/assets/templates/MODULE-MAP.md +14 -0
  17. package/assets/templates/POLICY.json +15 -0
  18. package/assets/templates/PROJECT.md +42 -0
  19. package/conformance/v1/README.md +15 -0
  20. package/coordination/v1/README.md +14 -0
  21. package/coordination/v1/board.schema.json +59 -0
  22. package/coordination/v1/event.schema.json +26 -0
  23. package/coordination/v1/status.schema.json +49 -0
  24. package/evals/README.md +63 -0
  25. package/evals/evals.json +276 -0
  26. package/identity/v1/README.md +14 -0
  27. package/identity/v1/agent-identity.schema.json +95 -0
  28. package/identity/v1/identity-registry.schema.json +29 -0
  29. package/identity/v1/signed-payload.schema.json +42 -0
  30. package/intelligence/v1/README.md +19 -0
  31. package/intelligence/v1/dependency-graph.schema.json +82 -0
  32. package/intelligence/v1/impact-analysis.schema.json +51 -0
  33. package/intelligence/v1/reconciliation.schema.json +156 -0
  34. package/npm/bin/pakem.js +272 -0
  35. package/npm/check-version.js +26 -0
  36. package/package.json +58 -4
  37. package/policy/v1/README.md +15 -0
  38. package/policy/v1/policy.schema.json +20 -0
  39. package/protocol/v1/README.md +68 -0
  40. package/protocol/v1/capabilities.schema.json +17 -0
  41. package/protocol/v1/event.schema.json +114 -0
  42. package/protocol/v1/session.schema.json +51 -0
  43. package/references/artifacts.md +96 -0
  44. package/references/conventions.md +83 -0
  45. package/references/reviews.md +44 -0
  46. package/runtime/v1/README.md +21 -0
  47. package/runtime/v1/approval.schema.json +100 -0
  48. package/runtime/v1/checkpoint.schema.json +17 -0
  49. package/runtime/v1/hook-decision.schema.json +34 -0
  50. package/runtime/v1/hook-payload.schema.json +12 -0
  51. package/runtime/v1/task-evidence.schema.json +38 -0
  52. package/runtime/v1/work-report.schema.json +123 -0
  53. package/runtime/v1/workflow.schema.json +21 -0
  54. package/scripts/__pycache__/pakem.cpython-312.pyc +0 -0
  55. package/scripts/pakem.py +4911 -0
  56. package/scripts/pakem_core/__init__.py +3 -0
  57. package/scripts/pakem_core/__pycache__/__init__.cpython-312.pyc +0 -0
  58. package/scripts/pakem_core/__pycache__/coordination.cpython-312.pyc +0 -0
  59. package/scripts/pakem_core/__pycache__/git_worktree.cpython-312.pyc +0 -0
  60. package/scripts/pakem_core/__pycache__/identity.cpython-312.pyc +0 -0
  61. package/scripts/pakem_core/__pycache__/intelligence.cpython-312.pyc +0 -0
  62. package/scripts/pakem_core/__pycache__/mcp_server.cpython-312.pyc +0 -0
  63. package/scripts/pakem_core/__pycache__/protocol.cpython-312.pyc +0 -0
  64. package/scripts/pakem_core/__pycache__/reconcile.cpython-312.pyc +0 -0
  65. package/scripts/pakem_core/__pycache__/runtime.cpython-312.pyc +0 -0
  66. package/scripts/pakem_core/coordination.py +977 -0
  67. package/scripts/pakem_core/git_worktree.py +265 -0
  68. package/scripts/pakem_core/identity.py +494 -0
  69. package/scripts/pakem_core/intelligence.py +684 -0
  70. package/scripts/pakem_core/mcp_server.py +308 -0
  71. package/scripts/pakem_core/protocol.py +61 -0
  72. package/scripts/pakem_core/reconcile.py +119 -0
  73. package/scripts/pakem_core/runtime.py +457 -0
  74. package/scripts/run_evals.py +289 -0
  75. package/storage/v1/README.md +14 -0
  76. package/storage/v1/team-storage.schema.json +27 -0
package/README-ID.md ADDED
@@ -0,0 +1,666 @@
1
+ <div align="center">
2
+
3
+ <img src="assets/banner.svg" alt="Pakem: Agent boleh ganti; pakem tetap." width="100%">
4
+
5
+ <br>
6
+
7
+ ![protocol](https://img.shields.io/badge/protocol-v1.0-d4af37?style=flat-square&labelColor=0b0a14)
8
+ ![python](https://img.shields.io/badge/python-3.10+-c9a7ff?style=flat-square&labelColor=0b0a14)
9
+ ![deps](https://img.shields.io/badge/core-stdlib_only-ffb3d9?style=flat-square&labelColor=0b0a14)
10
+ ![license](https://img.shields.io/badge/license-MIT-f3dd9a?style=flat-square&labelColor=0b0a14)
11
+
12
+ **Bahasa: [Bahasa Indonesia](README-ID.md) | [English](README.md)**
13
+
14
+ <a href="https://github.com/Matsumiko/pakem">
15
+ <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=20&pause=1200&color=FF8FB1&center=true&vCenter=true&width=700&lines=%E2%9C%A6+Lapisan+disiplin+kerja+untuk+agent+coding+%E2%9C%A6;Bukan+library%2C+bukan+framework.;Agent+boleh+ganti%3B+pakem+tetap.+%F0%9F%8C%B8" alt="animasi mengetik" />
16
+ </a>
17
+
18
+ <br>
19
+
20
+ Pakem bikin kerja agent **konsisten** 🌙, **bisa dilanjut** 🔁, dan **bisa dibuktikan selesai** ✅.
21
+
22
+ </div>
23
+
24
+ <img src="assets/divider.svg" alt="" width="100%">
25
+
26
+ ## 📖 Daftar Isi
27
+
28
+ | Arc | Bab |
29
+ |---|---|
30
+ | 🌅 **Prolog** | [Masalah yang diselesaikan](#-prolog-masalah-yang-diselesaikan) |
31
+ | ⚔️ **Arc 1: Kebangkitan** | [Pasang](#-arc-1--kebangkitan-pasang) · [Pemakaian harian](#-arc-2--ritual-harian-pemakaian-harian) |
32
+ | 🔮 **Arc 2: Protokol** | [Protokol & antarmuka mesin](#-arc-3--protokol--antarmuka-mesin) · [Protokol stabil](#-protokol-operasi-stabil-pakem-10) · [MCP](#-adapter-mcp-mcp-2026-07-28) |
33
+ | 🛡️ **Arc 3: Penjaga** | [Worktree](#-isolasi-git-worktree) · [Runtime](#-runtime-otonom-v1-080) · [Peringatan perubahan aturan](#-peringatan-perubahan-aturan) |
34
+ | 📜 **Arc 4: Gulungan** | [Konfigurasi](#-konfigurasi-pakemprojectmd) · [Spec & plan](#-spec--plan-opsional) · [Sumber kebenaran](#-sumber-kebenaran-biar-tidak-duplikat) |
35
+ | 🔍 **Arc 5: Ujian** | [Audit](#-audit-artefak-pakem-audit) · [Gate](#-gate-pakem-finish-dan-pakem-check) · [Bukti](#-bukti----strict) |
36
+ | 🌌 **Arc 6: Kenaikan** | [Fondasi 1.1.0](#-fondasi-orkestrasi-produksi-110) · [Multi-agent](#-koordinasi-multi-agent-v090) |
37
+ | 🌙 **Epilog** | [Batasan](#-batasan-jujur) · [Peta jalan](#-peta-jalan) · [Lisensi](#-lisensi--distribusi) |
38
+
39
+ <img src="assets/divider.svg" alt="" width="100%">
40
+
41
+ ## 🌅 Prolog: Masalah yang diselesaikan
42
+
43
+ > *Setiap pahlawan punya titik lemah. Ini yang dihadapi agent, dan apa yang Pakem pasang.* (◕‿◕)♡
44
+
45
+ | 💢 Masalah nyata | ✨ Yang Pakem pasang |
46
+ |---|---|
47
+ | Agent lupa konvensi project tiap sesi baru | `CONTEXT.md` (routing) + `PROJECT.md` |
48
+ | Kerja terputus di tengah jalan, besok mulai dari nol | `.pakem/sessions/*.json` dengan `lastPosition` + `nextStep` |
49
+ | Agent bilang "selesai" tapi belum tentu | `pakem finish`: gate yang bisa gagal (exit code 1) |
50
+ | Bug sama diperbaiki berkali-kali | `BUG-HISTORY.md` |
51
+ | Keputusan arsitektur diperdebatkan ulang | `DECISIONS.md` + `docs/adr/` |
52
+ | Claude, Cursor, Codex punya aturan beda-beda | adapter yang digenerate dari satu sumber |
53
+ | File project masih penuh placeholder | gate placeholder |
54
+ | Dokumen modul basi, menyebut file yang sudah dihapus | gate drift |
55
+ | Bingung file/dokumen apa yang perlu ada | `pakem audit`: REQUIRED / RECOMMENDED / NOT NEEDED, tanpa membuat file kosong |
56
+ | Agent langsung ngoding tanpa spec yang disetujui | `pakem spec` + `spec --approve`; gate `spec` |
57
+ | Pekerjaan besar tidak terpecah dan mudah melenceng | `pakem plan`: task 2–5 menit + files + verify; gate `plan` |
58
+ | Agent melebar: mengubah file di luar rencana | `pakem reconcile` + gate `scope` (kode di luar scope gagal; dokumentasi/config dilaporkan) |
59
+ | Spec "approved" padahal kriteria penerimaan belum terbukti | gate `acceptance` (saat `finish`) menolak kotak yang belum dicentang |
60
+ | Agent/tool perlu kontrak kerja yang sama | Pakem Protocol v1.0 + JSON Schema |
61
+ | Agent perlu konteks workflow tanpa parsing Markdown | `pakem context --json` |
62
+ | Gate bisa dijalankan CLI yang sudah diubah agent | manifest `pakem.py` + `pakem_core/*` dipin saat `start`; `pakem integrity` + `finish --strict` |
63
+ | Kunci seal hanya ada di satu host | `--key` / `PAKEM_SEAL_KEY` + `identity import` untuk host tanpa private key |
64
+ | HANDOVER.md terisi tapi isinya dari commit lama | cap HEAD + gate `handover`, `--check`/`--stamp` |
65
+ | Worktree menumpuk setelah task selesai | `plan done` membersihkan worktree yang merged & bersih, sisanya dilaporkan |
66
+ | Tidak ada angka kerja yang bisa dipertanggungjawabkan | `pakem report`: durasi, step, task, bukti verify, status ledger |
67
+ | Catatan sesi bisa disunting tanpa jejak | rantai hash (`events --verify`) + seal Ed25519 (`events --sign`) |
68
+ | Perubahan lintas modul sulit dipetakan | `pakem graph` + `pakem impact` |
69
+ | Riwayat lifecycle sulit diaudit lintas tool | event ledger append-only JSONL + `pakem events` |
70
+ | Workflow agent sulit distandarkan dan dipulihkan | `pakem runtime`: state machine, checkpoint, recovery metadata |
71
+ | Aksi berisiko perlu dibatasi lintas agent | `POLICY.json`, approval satu kali, lifecycle hooks |
72
+ | Beberapa agent mengerjakan proyek yang sama tanpa koordinasi | `pakem team`: task dependency, lease, handoff, shared board, independent review |
73
+ | Integrasi tool/model berubah-ubah | Pakem Protocol v1.0 stabil + negosiasi capability |
74
+ | Agent perlu tool interface universal | adapter MCP stateless stdio; default read-only, write tool diikat ke agent host |
75
+ | Agent mengubah file yang sama dari working tree bersama | isolasi Git worktree per task/agent; tanpa merge/push implisit |
76
+ | Agent melebar di dalam worktree, lalu di-merge | gate `worktree` + `pakem worktree scope` membandingkan diff worktree dengan scope task |
77
+ | Identitas agent hanya berupa ID metadata | identitas publik Ed25519, attestation bertanda tangan, revocation, dan delegation token ber-scope |
78
+ | Board/event lokal butuh transaksi state+audit yang atomik | Backend SQLite lokal dengan transaksi board+event dan backup online |
79
+ | Implementasi protocol perlu bukti kompatibilitas berulang | Pakem Conformance Profile v1 dengan test regresi |
80
+
81
+ <img src="assets/divider.svg" alt="" width="100%">
82
+
83
+ ## ⚔️ Arc 1 · Kebangkitan (Pasang)
84
+
85
+ Folder ini adalah sebuah skill. Taruh sebagai `pakem/` di folder skill agent kamu (mis. `.claude/skills/pakem/` atau `~/.claude/skills/pakem/`). Untuk agent lain, cukup jalankan CLI-nya langsung.
86
+
87
+ Dengan Node 18+, paket npm memasang skill-nya untuk kamu (Pakem sendiri tetap butuh Python 3.10+). Di terminal ia membuka picker; flag membuatnya non-interaktif:
88
+
89
+ ```bash
90
+ npx pakem-cli # interactive picker
91
+ npx pakem-cli install --yes # non-interactive, global default
92
+ npx pakem-cli install --project # ./.claude/skills/pakem
93
+ npx pakem-cli install --dir ~/.agents/skills/pakem
94
+ ```
95
+
96
+ Paket ini hanya menyalin skill; tidak menambah dependency npm ke proyekmu. Argumen lain diteruskan ke CLI Python bawaan paket (`npx pakem-cli init --type app`).
97
+
98
+ Butuh **Python 3.10+**. CLI/Core dasar hanya memakai standard library. Operasi identitas Ed25519 opsional dan memerlukan `python -m pip install cryptography`.
99
+
100
+ ```bash
101
+ cd proyek-kamu
102
+ python3 /path/ke/pakem/scripts/pakem.py init --type app
103
+ ```
104
+
105
+ `--type`: `app` (default), `library`, `oneoff`, `research`.
106
+ Tambahan: `--verify "npm test && npm run lint"`, `--adapter claude,codex,cursor,gemini,copilot` (atau `none`), `--hook`.
107
+
108
+ Setelah init, CLI dan modul Pakem Core disalin ke `.pakem/` sehingga proyek mandiri. Modul Core dipisah dari CLI agar kemampuan intelligence bisa dipakai runtime lain.
109
+
110
+ <img src="assets/divider.svg" alt="" width="100%">
111
+
112
+ ## 🍡 Arc 2 · Ritual Harian (Pemakaian harian)
113
+
114
+ ```bash
115
+ python3 .pakem/pakem.py start "build a todo web app" # or resume an interrupted session
116
+ python3 .pakem/pakem.py step "model done" --next "build the endpoint"
117
+ python3 .pakem/pakem.py adr "Choose SQLite" # when an architecture decision appears
118
+ python3 .pakem/pakem.py bug "Crash on empty input" --symptom "..." --cause "..." --fix "..." --prevent "..."
119
+ python3 .pakem/pakem.py spec "Export feature" # fill, then: pakem spec --approve
120
+ python3 .pakem/pakem.py plan add "write the parser" --files "src/parser.ts,tests/parser.test.ts" --verify "npm test -- parser"
121
+ python3 .pakem/pakem.py plan done T1 # runs the task verify + stores evidence
122
+ python3 .pakem/pakem.py audit # which files/docs are worth having (read-only)
123
+ python3 .pakem/pakem.py finish --summary "todo CRUD works, tests pass" # add --fixed-bug / --strict when needed
124
+ ```
125
+
126
+ **🗡️ Perintah lain:** `status`, `context --json`, `events --json`, `graph [--json]`, `impact --files FILE...`, `protocol info`, `protocol negotiate --peer-version 1.0`, `protocol validate-event FILE`, `protocol validate-session FILE`, `mcp serve`, `worktree create/list/scope/remove`, `events --verify/--sign`, `report [--json] [--session ID] [--limit N]`, `handover [--stamp] [--check]`, `integrity [--re-pin --reason ...]`, `worktree cleanup [--dry-run]`, `identity create/list/sign/verify/issue/rotate/revoke`, `team storage info/migrate/backup`, `check [--skip-verify]`, `audit [--json] [--strict]`, `spec`, `plan`, `handover`, `doctor`, `prune`, `ci`, `upgrade`, `adapt`, `hook install`, `runtime`, `policy`, `team`.
127
+
128
+ > 🪟 **Windows:** ganti `python3` dengan `python` atau `py -3`. Adapter dan `CONTEXT.md` sudah menjelaskan ini ke agent, dan git hook mencari interpreter yang benar-benar jalan. Dukungan Windows ditulis dengan hati-hati tapi **belum diuji di Windows**.
129
+
130
+ <img src="assets/divider.svg" alt="" width="100%">
131
+
132
+ ## 🔮 Arc 3 · Protokol & Antarmuka Mesin
133
+
134
+ Pakem Protocol v1.0 memisahkan kontrak workflow dari CLI, model AI, bahasa, dan transport. Event envelope serta kompatibilitas session v1.0 dibekukan; fitur tambahan dinegosiasikan melalui capability. Spesifikasi dan JSON Schema ada di `.pakem/protocol/v1/`; source distribusi ada di `protocol/v1/`.
135
+
136
+ ```bash
137
+ python3 .pakem/pakem.py protocol info
138
+ python3 .pakem/pakem.py protocol negotiate --peer-version 1.0 --capability events.v1 --capability context.snapshot.v1 --capability coordination.v1 --json
139
+ python3 .pakem/pakem.py context --json # compact snapshot for agents/tools
140
+ python3 .pakem/pakem.py events --json # structured event history
141
+ python3 .pakem/pakem.py events --verify # verify the ledger hash chain
142
+ python3 .pakem/pakem.py events --sign --identity backend # seal the ledger with Ed25519
143
+ python3 .pakem/pakem.py report --json # roll-up of sessions, tasks, evidence, ledger
144
+ python3 .pakem/pakem.py events --session <session-id>
145
+ python3 .pakem/pakem.py protocol validate-event event.json
146
+ python3 .pakem/pakem.py protocol validate-session session.json
147
+
148
+ # Intelligent Core: dependency graph and change impact
149
+ python3 .pakem/pakem.py graph --json
150
+ python3 .pakem/pakem.py graph --json --output .pakem/dependency-graph.json
151
+ python3 .pakem/pakem.py impact --files src/auth.py tests/test_auth.py --json
152
+ python3 .pakem/pakem.py impact --base main --json
153
+ python3 .pakem/pakem.py impact --staged --strict --json
154
+ ```
155
+
156
+ ### 🕸️ Graph & Dampak
157
+
158
+ `pakem graph` membuat graph statis dari import lokal, termasuk alias `paths`/`baseUrl` di `tsconfig.json`/`jsconfig.json` (mengikuti `extends`, komentar JSONC diabaikan). Import yang tidak bisa di-resolve muncul di `unresolved_imports` beserta alasannya, dan siklus dependensi muncul di `circular_dependencies`. `pakem impact` menelusuri dependent langsung/transitif, test yang mungkin terdampak, dan sinyal risiko.
159
+
160
+ Analisisnya advisory dan best-effort: dynamic import, reflection, framework routing, code generation, dan runtime wiring bisa luput. `impact` menyertakan `graph_health`: kalau ada import yang tak ter-resolve, hasilnya ditandai belum lengkap dan rekomendasinya menyuruh memeriksa alias/baseUrl atau verifikasi manual. `--strict` mengembalikan exit 1 saat heuristik risiko HIGH; perintah ini tidak menjalankan test dan tidak menggantikan review atau verifikasi sebenarnya. Scanner bersifat read-only kecuali `graph --output` diminta eksplisit.
161
+
162
+ ### 📼 Ledger Event
163
+
164
+ Lifecycle sesi dan task otomatis dicatat sebagai JSONL di `.pakem/events/` (lokal, di-gitignore secara default). Event dicatat append-only dan diserialisasi dengan lock Pakem. Ledger memudahkan audit/handover, tetapi **belum ditandatangani secara kriptografis** dan bukan bukti bahwa pekerjaan benar; hasil verify tetap disimpan terpisah sebagai evidence.
165
+
166
+ ### 🧿 Snapshot Konteks
167
+
168
+ `context --json` memberikan project metadata, sesi aktif, progres spec/plan, hasil gate read-only (tanpa menjalankan verify), blocker, rekomendasi langkah berikutnya, dan status runtime/policy bila terpasang. Ia tidak mengirim isi source code, perintah verify, atau secret.
169
+
170
+ <img src="assets/divider.svg" alt="" width="100%">
171
+
172
+ ## 🌠 Protokol Operasi Stabil (Pakem 1.0+)
173
+
174
+ Pakem Protocol v1.0 adalah kontrak stabil yang terpisah dari versi CLI, MCP, model, bahasa, dan provider. Bentuk event envelope serta aturan kompatibilitas session v1.0 dibekukan. Fitur baru dinyatakan melalui capability negotiation; capability bukan otorisasi untuk melakukan side effect.
175
+
176
+ ```bash
177
+ python3 .pakem/pakem.py protocol info
178
+ python3 .pakem/pakem.py protocol negotiate --peer-version 1.0 \
179
+ --capability events.v1 --capability context.snapshot.v1 --capability coordination.v1 --json
180
+ ```
181
+
182
+ > ⚠️ `actor.name`, ID agent pada team board, dan MCP `clientInfo` adalah metadata atribusi. Ketiganya tidak membuktikan identitas. Host runtime wajib mengikat caller ke identitas tepercaya melalui boundary proses/credential/transport yang sesuai.
183
+
184
+ <img src="assets/divider.svg" alt="" width="100%">
185
+
186
+ ## 🔌 Adapter MCP (MCP 2026-07-28)
187
+
188
+ Pakem menyertakan MCP server melalui stdio tanpa dependency eksternal. Adapter menargetkan MCP modern stateless: versi protokol dan client capabilities dikirim pada setiap request melalui `params._meta`; `server/discover` mengiklankan versi/capability, sedangkan `tools/list` dan `tools/call` menyediakan fungsi Pakem.
189
+
190
+ ```bash
191
+ # Read-only, default
192
+ python3 .pakem/pakem.py mcp serve
193
+
194
+ # Board mutation only when the host explicitly grants agent binding and write access
195
+ python3 .pakem/pakem.py mcp serve --agent-id backend --allow-write
196
+ ```
197
+
198
+ Read-only tools: context, Protocol info, team status/events, graph, impact, dan policy check. Mode write mengekspos claim, heartbeat, submit, review, dan assign sesuai role agent yang terdaftar. ID actor berasal dari `--agent-id` server, bukan argumen tool. Tool tidak menjalankan arbitrary shell, deployment, merge, push, atau policy change.
199
+
200
+ > ⚠️ `clientInfo` MCP adalah self-reported; keamanan binding hanya berlaku kalau host tepercaya meluncurkan proses dengan identitas dan hak akses yang benar. Jangan expose stdio server sebagai network service tanpa authz/authn tambahan.
201
+
202
+ <img src="assets/divider.svg" alt="" width="100%">
203
+
204
+ ## 🌿 Isolasi Git Worktree
205
+
206
+ ```bash
207
+ python3 .pakem/pakem.py worktree create T1 --agent backend --base main
208
+ python3 .pakem/pakem.py worktree list --json
209
+ python3 .pakem/pakem.py worktree scope T1--backend --strict
210
+ python3 .pakem/pakem.py worktree remove .pakem/worktrees/T1--backend
211
+ ```
212
+
213
+ `worktree scope` membandingkan isi worktree (commit di branch, perubahan belum commit, dan file untracked) dengan `<task>` pada namanya. Gate `worktree` menjalankan pemeriksaan yang sama untuk semua worktree aktif saat `check`/`finish`; kode di luar scope di sana akan masuk ke branch yang nanti di-merge, jadi gate ini yang menutup celah "isolasi = aman".
214
+
215
+ Worktree diletakkan di `.pakem/worktrees/` dan branch bernama `pakem/<task>/<agent>`. Removal menolak worktree dirty kecuali `--force`; branch tidak dihapus otomatis. Fitur ini mengisolasi working tree, bukan melakukan task assignment, verification, merge, push, atau conflict resolution otomatis — pemeriksaan scope per worktree ada di `worktree scope`/gate `worktree`, sisanya tetap tanggung jawab operator.
216
+
217
+ <img src="assets/divider.svg" alt="" width="100%">
218
+
219
+ ## 🤖 Runtime Otonom v1 (0.8.0)
220
+
221
+ `pakem init` memasang `.pakem/POLICY.json`, Runtime/Policy schemas, dan modul Core runtime. State workflow lokal disimpan di `.pakem/runtime/` dan diabaikan Git secara default.
222
+
223
+ ```bash
224
+ # Start and monitor the runtime workflow
225
+ python3 .pakem/pakem.py runtime init "implementasi OAuth"
226
+ python3 .pakem/pakem.py runtime status --json
227
+ python3 .pakem/pakem.py runtime transition ready --reason "spec dan plan disetujui"
228
+ python3 .pakem/pakem.py runtime transition executing --task-id T1
229
+
230
+ # Checkpoint and recovery metadata
231
+ python3 .pakem/pakem.py runtime checkpoint --label "sebelum refactor" --json
232
+ python3 .pakem/pakem.py runtime recover --json
233
+
234
+ # Lifecycle hooks and policy
235
+ python3 .pakem/pakem.py runtime hook task.before --payload-file action.json --json
236
+ python3 .pakem/pakem.py policy show --json
237
+ python3 .pakem/pakem.py policy check --category deploy --risk high --target staging --json
238
+ python3 .pakem/pakem.py policy approve --category deploy --risk high --target staging --reason "user approved staging"
239
+ ```
240
+
241
+ State machine membatasi transisi ilegal. Checkpoint menyimpan metadata workflow dan snapshot HEAD/status Git. `recover` hanya mengembalikan metadata workflow ke state `recovering`; ia **tidak** melakukan checkout, reset, revert, atau mengubah source code. Selalu tinjau Git diff sebelum melanjutkan.
242
+
243
+ **🎚️ Mode policy**
244
+
245
+ | Mode | Perilaku |
246
+ |---|---|
247
+ | `manual` | meminta approval untuk semua aksi selain read |
248
+ | `assisted` | mengizinkan edit biasa, tetapi meminta approval untuk command medium/high dan kategori sensitif |
249
+ | `guarded_autonomous` | mengizinkan aksi hingga `maxAutonomousRisk`, kecuali kategori yang selalu memerlukan approval |
250
+
251
+ `deniedCategories` tetap ditolak meskipun ada approval.
252
+
253
+ Approval lokal bersifat satu kali, kedaluwarsa, dan terikat pada workflow, kategori, tingkat risiko, serta target. Ini **bukan autentikasi manusia yang aman**: CLI tidak dapat membuktikan siapa yang menjalankan `policy approve`. Host agent wajib menghentikan aksi dan meminta konfirmasi user melalui kanal tepercaya; agent tidak boleh menyetujui dirinya sendiri. Jangan memasukkan secret atau perintah lengkap ke target/payload hook.
254
+
255
+ **🪝 Hook standar:** `session.start`, `task.before`, `task.after`, `verification.before`, `session.finish`, `handover`. `runtime hook` mengembalikan `allow`, `require_approval`, atau `deny` dan mencatat receipt tanpa menyimpan payload mentah. Host runtime wajib menegakkan keputusan ini; Pakem tidak mengeksekusi command, deploy, atau agent.
256
+
257
+ <img src="assets/divider.svg" alt="" width="100%">
258
+
259
+ ## 🚨 Peringatan perubahan aturan
260
+
261
+ Gate bisa dilewati kalau agent diam-diam melonggarkan aturannya. Karena itu `start` menyimpan potret `rule.*`, `verify`, `sensitive`, `exposure`, `deploy`, `handover`, dan manifest hash `.pakem/pakem.py` beserta seluruh `.pakem/pakem_core/*.py`. Di `check`, `finish`, dan `audit`, perubahan setelahnya muncul sebagai:
262
+
263
+ ```
264
+ [WARN] rules-changed: rule.tests relaxed: required -> skip
265
+ [WARN] rules-changed: verify changed: 'npm test' -> 'true'
266
+ [WARN] rules-changed: exposure downgraded: public -> private
267
+ [WARN] rules-changed: deploy downgraded: production -> none
268
+ [WARN] rules-changed: .pakem/pakem.py modified during this session
269
+ ```
270
+
271
+ `finish` juga mencetak gap berisiko menurut flag:
272
+
273
+ ```
274
+ [WARN] risk: deploy=production but no CI yet
275
+ [WARN] risk: deploy=production but no RUNBOOK.md yet
276
+ WARNING: 2 risks unresolved (advisory, non-blocking).
277
+ ```
278
+
279
+ Ini tidak memblokir (kadang perubahan memang diminta user), tapi tercatat di sesi dan agent diwajibkan melaporkannya. Pakem membuat pelonggaran *kelihatan*; ia tidak bisa mencegah agent yang bertekad menipu.
280
+
281
+ <img src="assets/divider.svg" alt="" width="100%">
282
+
283
+ ## 🧭 Cek kondisi repo saat resume
284
+
285
+ Di setiap `start` dan `step`, Pakem mencatat commit HEAD dan daftar file yang berubah (di luar `.pakem/`). Saat `start` menemukan sesi terputus, ia membandingkan dengan kondisi sekarang:
286
+
287
+ ```
288
+ CHECK: repo state changed since the last record:
289
+ - HEAD changed (2 new commits)
290
+ - changed since the last record: M src/api.py; ?? scratch.txt
291
+ ```
292
+
293
+ Jadi `nextStep` yang basi atau kerja yang belum sempat dicatat langsung terlihat. Hanya aktif di repo git.
294
+
295
+ File sesi ditulis atomik (tulis ke file sementara, `fsync`, lalu rename), sehingga listrik mati di tengah penulisan tidak meninggalkan JSON setengah. Semua tulisan `.pakem/*.md`/ADR/BUG-HISTORY juga memakai jalur atomik, dan mutasi sesi/dokumen dikunci antar-proses (`pakem_lock`). Kalau tetap ada file sesi yang korup, `status`/`start`/`check`/`finish` menampilkan `[WARN] corrupt session ignored: ...` — tidak lagi hilang diam-diam.
296
+
297
+ <img src="assets/divider.svg" alt="" width="100%">
298
+
299
+ ## 🏯 Apa yang dibuat `init`
300
+
301
+ ```
302
+ .pakem/
303
+ ├── CONTEXT.md entry point + routing: read this first
304
+ ├── PROJECT.md config (verify, rule.*) + stack + conventions
305
+ ├── MODULE-MAP.md module map (app/library)
306
+ ├── DECISIONS.md decision index (app/library/research)
307
+ ├── BUG-HISTORY.md bug history (app/library)
308
+ ├── pakem.py standalone CLI per project
309
+ ├── POLICY.json autonomy and approval policy (project-managed)
310
+ ├── pakem_core/ Core modules (intelligence + autonomous runtime)
311
+ ├── protocol/v1/ event/session contract
312
+ ├── intelligence/v1/ graph/impact output schemas
313
+ ├── runtime/v1/ workflow/checkpoint/lifecycle hook schemas
314
+ ├── policy/v1/ policy schema
315
+ ├── sessions/ per-session JSON (gitignored by default)
316
+ ├── events/ local event ledger (gitignored by default)
317
+ └── runtime/ workflow, checkpoints, approvals, hook receipts (gitignored)
318
+ docs/adr/ only when the adr rule is active (new project)
319
+ tests/ only when tests rule = required (new project)
320
+ CLAUDE.md, AGENTS.md, .cursor/rules/pakem.mdc adapters (marked blocks, existing content preserved)
321
+ ```
322
+
323
+ **Scaffolding bersyarat:** `oneoff` hanya dapat `CONTEXT.md` dan `PROJECT.md`. Repo yang sudah ada terdeteksi otomatis dan **tidak dirombak**; hanya `.pakem/` dan adapter yang ditambah.
324
+
325
+ <img src="assets/divider.svg" alt="" width="100%">
326
+
327
+ ## 📜 Konfigurasi (`.pakem/PROJECT.md`)
328
+
329
+ Bagian atas file berisi konfigurasi, satu `key: value` per baris:
330
+
331
+ ```
332
+ type: app
333
+ sensitive: false
334
+ exposure: private
335
+ deploy: none
336
+ handover: false
337
+ verify: npm test && npm run lint
338
+ rule.tests: required
339
+ rule.adr: when-decision
340
+ rule.research: skip
341
+ reason.research: stack sudah ditentukan user, tidak ada eksplorasi
342
+ rule.modular: required
343
+ ```
344
+
345
+ Nilai `rule.*`: `required`, `skip`, `when-decision`, `when-needed`. Setiap `skip` **wajib** punya `reason.*`. Gate tidak gagal karena folder tidak ada, tapi gagal kalau aturan dilewati diam-diam.
346
+
347
+ **🚩 Flag risiko** (dibaca `pakem audit`, bukan gate):
348
+
349
+ | Flag | Nilai | Efek pada audit |
350
+ |---|---|---|
351
+ | `exposure` | `private` / `public` | publik → saran LICENSE, CONTRIBUTING, SECURITY, template PR/issue |
352
+ | `deploy` | `none` / `staging` / `production` | deploy → saran CI, DEPLOYMENT, RUNBOOK |
353
+ | `handover` | `true` / `false` | true → saran HANDOVER, akses, known issues, tech debt |
354
+ | `sensitive` | `true` / `false` | true → saran SECURITY, threat model, secret scan |
355
+
356
+ `start` memotret keempat flag ini; menurunkannya saat sesi berjalan memunculkan `[WARN] rules-changed`. Audit tetap read-only dan tidak pernah membuat file.
357
+
358
+ <img src="assets/divider.svg" alt="" width="100%">
359
+
360
+ ## 📝 Spec & plan (opsional)
361
+
362
+ Untuk fitur/perubahan multi-file, jangan langsung ngoding. Untuk typo atau edit satu file, lewati.
363
+
364
+ ```bash
365
+ python3 .pakem/pakem.py spec "Export feature" # create .pakem/SPEC.md
366
+ # fill Problem / Non-goals / Acceptance / Approach
367
+ python3 .pakem/pakem.py spec --approve # all [FILL] placeholders must be filled
368
+
369
+ python3 .pakem/pakem.py plan add "write the parser" \
370
+ --files "src/parser.ts,tests/parser.test.ts" \
371
+ --verify "npm test -- parser"
372
+ python3 .pakem/pakem.py plan list
373
+ python3 .pakem/pakem.py plan done T1 # runs the task verify + stores evidence
374
+ python3 .pakem/pakem.py plan drop T2 --reason "no longer relevant"
375
+ ```
376
+
377
+ - 📄 `SPEC.md` berstatus `draft` sampai `spec --approve`; selama draft, `check`/`finish` gagal di gate `spec`.
378
+ - 🗒️ Setiap task berisi `files` dan `verify`; selama ada `[ ]`, `check`/`finish` gagal di gate `plan`. `plan drop` menandai task selesai dengan alasan.
379
+ - ✅ Bagian Acceptance `SPEC.md` harus dicentang (`- [x]`) sebelum `finish` lolos gate `acceptance`; `check` hanya menagih approval, karena spec disetujui sebelum kerja dimulai.
380
+ - 🧾 Setiap task `[x]` harus punya bukti verify yang masih berlaku: `plan done` menjalankan `--verify` task itu dan mencatat exit code, hash output, serta sidik file scope di `.pakem/verify/tasks.json`. Kalau file scope berubah setelah verify, gate `task-verify` menolak sampai bukti diperbarui. Pengecualian harus eksplisit: `--no-verify --reason "..."`, dan waiver itu selalu disebut di baris gate. Task yang di-drop tidak diklaim selesai, jadi tidak menuntut bukti.
381
+ - 🎯 Perubahan **kode** di luar `--files` seluruh task menggagalkan gate `scope`; file non-kode (dokumen, config, lockfile) hanya dilaporkan. Patokannya HEAD saat sesi `start`, jadi perubahan yang sudah di-commit dan file yang dihapus tetap terlihat — `git diff HEAD` saja tidak cukup. `pakem reconcile` memperlihatkan keduanya sebelum `finish`.
382
+ - 🌿 Gate `worktree` mengulang pemeriksaan itu untuk tiap worktree terkelola: diff branch + perubahan belum commit + file untracked dibandingkan dengan scope task pada nama worktree, dan task tanpa scope file juga dilaporkan.
383
+ - ⏱️ Target task: 2–5 menit, satu perubahan kecil yang bisa diverifikasi.
384
+ - 👀 `start`/`status` menampilkan status spec dan progres plan; `doctor` memperingatkan kalau masih draft/pending.
385
+
386
+ <img src="assets/divider.svg" alt="" width="100%">
387
+
388
+ ## 🗝️ Sumber kebenaran (biar tidak duplikat)
389
+
390
+ | File | Peran | Jangan taruh |
391
+ |---|---|---|
392
+ | `PROJECT.md` | fakta + config proyek (`verify`, `rule.*`, flag) | riwayat task |
393
+ | `CONTEXT.md` | routing: baca apa dulu; protokolnya digenerate | spesifikasi fitur |
394
+ | `SPEC.md` | kenapa/apa + acceptance untuk satu pekerjaan | daftar task |
395
+ | `PLAN.md` | urutan task (how) untuk pekerjaan itu | masalah/non-goal |
396
+ | session JSON | apa yang benar-benar terjadi (`steps`, `nextStep`) | niat/rencana |
397
+ | `MODULE-MAP.md` | struktur modul | status pekerjaan |
398
+ | `DECISIONS.md` + `docs/adr/` | index + detail keputusan | bug/riwayat kerja |
399
+ | `BUG-HISTORY.md` | bug yang sudah diperbaiki | bug yang masih terbuka |
400
+ | `HANDOVER.md` | snapshot akhir: akses, kontak, sisa kerja, risiko | password/secret |
401
+ | `references/` | panduan generik | fakta spesifik proyek |
402
+
403
+ Aturan: **jangan menyalin isi**, tunjuk file sumbernya. `CONTEXT.md` dan adapter memakai protokol yang digenerate dari satu sumber; `pakem upgrade` menyinkronkan bloknya, `doctor` memperingatkan kalau basi.
404
+
405
+ | Perintah | Peran |
406
+ |---|---|
407
+ | `status` | ringkasan read-only |
408
+ | `check` | gate yang bisa gagal |
409
+ | `reconcile` | laporan read-only: perubahan Git vs scope task (plan/board) vs acceptance (`--json`, `--strict`) |
410
+ | `finish` | gate + bukti verify + tutup sesi |
411
+ | `audit` | inventaris artefak, advisory |
412
+ | `doctor` | diagnosis setup (config/git/hook/adapter/sesi) |
413
+ | `spec` / `plan` | state workflow, bukan gate verifikasi |
414
+
415
+ <img src="assets/divider.svg" alt="" width="100%">
416
+
417
+ ## 🔍 Audit artefak (`pakem audit`)
418
+
419
+ Pakem tidak mengejar kelengkapan file. `audit` memilah artefak berdasarkan `type`, `exposure`, `deploy`, `handover`, `sensitive`, dan isi repo:
420
+
421
+ ```
422
+ AUDIT your-project
423
+ configuration: type=app exposure=private deploy=none handover=false sensitive=false
424
+
425
+ REQUIRED - continuity & verification
426
+ [ok] README.md
427
+ [gap] verify — fill in the test/lint/build command
428
+ [gap] tests/ — logic needs tests run by verify
429
+
430
+ RECOMMENDED - risk-based; may be deferred with a reason
431
+ [gap] .env.example — code reads the environment
432
+ ...
433
+
434
+ NOT NEEDED - do not create just for completeness
435
+ [-] LICENSE — private repo; change exposure: public if it will be released
436
+ [-] docs/decisions/ — canonical: docs/adr/ — do not keep both
437
+ ...
438
+ ```
439
+
440
+ - 👁️ `audit` **read-only**: tidak membuat file, tidak mengubah konfigurasi.
441
+ - 🤖 `--json` untuk agent; `--strict` exit 1 bila ada REQUIRED yang kurang.
442
+ - 🕰️ Yang RECOMMENDED boleh ditunda dengan alasan jujur; jangan membuat file kosong.
443
+ - 🎬 `init` langsung mencetak ringkasan rencana artefak.
444
+ - ⚠️ `finish` mencetak `[WARN] risk: ...` untuk gap yang flag-nya aktif (mis. `deploy=production but no RUNBOOK.md yet`). Ini **advisory**: tidak mengubah exit code, tapi wajib dilaporkan.
445
+ - 📦 `pakem handover` membuat **satu** `HANDOVER.md` (status, akses tanpa password, kontak, sisa kerja, risiko). Placeholder-nya ikut ditolak gate sampai diisi; jangan memecahnya menjadi `ACCESS` + `KNOWN_ISSUES` + `TECH_DEBT` + `HANDOVER` yang cepat basi.
446
+ - 📚 Detail per mode kegagalan, pilihan kanonik (mis. `docs/adr/` bukan `docs/decisions/`), dan daftar yang tidak boleh dibuat otomatis: `references/artifacts.md`.
447
+
448
+ <img src="assets/divider.svg" alt="" width="100%">
449
+
450
+ ## 🩺 Diagnosis & perawatan
451
+
452
+ ```bash
453
+ python3 .pakem/pakem.py doctor # check config, placeholders, git, hooks, adapters, sessions
454
+ python3 .pakem/pakem.py doctor --verify # also run the verify command
455
+ python3 .pakem/pakem.py prune # dry-run: show old sessions that can be pruned
456
+ python3 .pakem/pakem.py prune --yes # delete; active sessions and the newest N are kept
457
+ python3 .pakem/pakem.py ci # create .github/workflows/ci.yml
458
+ # Run the newest CLI from the skill install, from the project root (including upgrades from 0.6.x)
459
+ python3 /path/ke/pakem/scripts/pakem.py upgrade --dry-run
460
+ python3 /path/ke/pakem/scripts/pakem.py upgrade
461
+ ```
462
+
463
+ - 🩹 `doctor` exit 1 bila ada **FAIL** (config rusak, verify kosong, placeholder tersisa, sesi korup); WARN hanya saran. `--json` untuk agent. Ia juga memperingatkan SPEC draft dan PLAN yang masih punya task terbuka.
464
+ - 🧹 `prune` default `--keep 20 --days 90`; sesi aktif tidak pernah dihapus, sesi korup tidak disentuh.
465
+ - 🏗️ `ci` mendeteksi Node (npm/pnpm/yarn), Python, Go, atau Rust lalu menjalankan `pakem check` — jadi `verify` tetap satu sumber kebenaran. `--force` menimpa workflow yang sudah ada.
466
+ - ⬆️ `upgrade` memperbarui CLI, modul Core, schema protocol/intelligence, flag baru, `.gitignore`, dan adapter. Isi manual dokumen proyek (termasuk `MODULE-MAP.md`/ADR) dipertahankan; hanya blok protokol Pakem yang memang ditandai di `CONTEXT.md`/adapter disinkronkan. Jalankan `--dry-run` dulu dan gunakan CLI terbaru dari instalasi skill.
467
+
468
+ <img src="assets/divider.svg" alt="" width="100%">
469
+
470
+ ## 🧪 Bukti & `--strict`
471
+
472
+ `finish` menyimpan bukti verify di sesi (`verifyEvidence`): perintah, exit code, durasi, hash output, dan hash `.pakem/pakem.py`; saat dijalankan ia mencetak:
473
+
474
+ ```
475
+ [EVIDENCE] verify: pass exit=0 hash=4355a46b19d348dc
476
+ ```
477
+
478
+ Default `finish` tetap advisory: gap audit REQUIRED muncul sebagai `[WARN] required: ...`. Tambah `--strict` bila ingin sesi **gagal** ketika aturan/CLI berubah, `verify` bukan `pass`, atau ada gap audit REQUIRED. Ini yang membuat "selesai" lebih sulit dibohongi, bukan sekadar exit 0.
479
+
480
+ <img src="assets/divider.svg" alt="" width="100%">
481
+
482
+ ## 👓 Lensa review
483
+
484
+ `references/reviews.md` memuat lensa frontend (konsistensi komponen/token, state loading/empty/error, responsif, a11y) dan backend (otorisasi server-side, validasi batas, query parameterized, secret, PII, fail closed). Dibaca sebelum `finish` bila proyek punya UI atau `sensitive: true`; bukan gate, dan tidak menggantikan review manusia.
485
+
486
+ <img src="assets/divider.svg" alt="" width="100%">
487
+
488
+ ## 🚪 Gate (`pakem finish` dan `pakem check`)
489
+
490
+ | Gate | Gagal bila |
491
+ |---|---|
492
+ | session | (hanya `finish`) tidak ada sesi aktif atau `--summary` kosong |
493
+ | bug | (hanya `finish --fixed-bug`) belum ada entri `pakem bug` di sesi ini |
494
+ | rules | `required` tak terpenuhi, atau `skip` tanpa alasan |
495
+ | placeholder | sisa `[FILL`, `[ISI` (lama), `{{...}}`, `TODO` di `.pakem/*.md` dan `docs/adr/*.md` |
496
+ | spec | `.pakem/SPEC.md` ada tapi belum `approved` |
497
+ | plan | `.pakem/PLAN.md` ada tapi masih ada task `[ ]` |
498
+ | drift | path di backtick pada MODULE-MAP/DECISIONS tidak ada di repo |
499
+ | verify | perintah `verify` exit non-nol, atau kosong tanpa `reason.verify` |
500
+
501
+ Exit code 1 bila ada yang gagal. Gate verify menjalankan test/lint/build **milik proyek kamu**: Pakem tidak menggantikan test, ia memaksa test dijalankan. `[WARN] risk:` dari audit tidak mengubah exit code.
502
+
503
+ <img src="assets/divider.svg" alt="" width="100%">
504
+
505
+ ## 🛡️ Enforcement
506
+
507
+ - **Git pre-commit:** `python3 .pakem/pakem.py hook install` (tambah `--skip-verify` bila test terlalu lambat untuk tiap commit). Hook dipasang di folder yang benar-benar dibaca git, jadi `core.hooksPath` dan worktree ikut didukung.
508
+ - **Agent:** adapter menyuntikkan protokol ke `CLAUDE.md`, `AGENTS.md`, dll. Untuk Claude Code kamu juga bisa memasang hook Stop yang menjalankan `check`; cek dokumentasi versi yang kamu pakai untuk format terbarunya.
509
+
510
+ <img src="assets/divider.svg" alt="" width="100%">
511
+
512
+ ## 🧫 Tes
513
+
514
+ Suite penuh butuh dua dependency opsional (dipakai satu modul tes untuk Ed25519 dan satu untuk validasi JSON Schema):
515
+
516
+ ```bash
517
+ python3 -m pip install -r requirements-dev.txt
518
+ python3 -m unittest discover -s tests -v
519
+ ```
520
+
521
+ Tanpa dependency itu suite tetap jalan dan hijau; 14 tes melompat dengan alasan yang terlihat di output.
522
+
523
+ Eval perilaku skill (bukan kode) dicek terpisah:
524
+
525
+ ```bash
526
+ python3 scripts/run_evals.py --validate # struktur evals.json
527
+ python3 scripts/run_evals.py --list # 24 eval
528
+ ```
529
+
530
+ Menjalankan eval butuh perintah agent dan perintah judge; kontraknya di `evals/README.md`.
531
+
532
+ <img src="assets/divider.svg" alt="" width="100%">
533
+
534
+ ## 🌌 Fondasi Orkestrasi Produksi (1.1.0)
535
+
536
+ Pakem 1.1 menambahkan dua fondasi untuk koordinasi yang lebih kuat. Keduanya opt-in dan menjaga kompatibilitas default versi sebelumnya.
537
+
538
+ ### 🔑 Identitas agent Ed25519
539
+
540
+ Public key identitas disimpan dan bisa dibagikan lewat `.pakem/identity/registry.json` (metadata publik); private key disimpan di direktori konfigurasi user (`$XDG_CONFIG_HOME/pakem/identities/` pada Linux/macOS atau `%APPDATA%/Pakem/identities/` pada Windows), bukan di repository. File private key ditulis dengan permission owner-only bila OS mendukung.
541
+
542
+ ```bash
543
+ # Needs the optional dependency: python -m pip install cryptography
544
+ python3 .pakem/pakem.py identity create backend
545
+ python3 .pakem/pakem.py identity list --json
546
+ python3 .pakem/pakem.py identity sign backend --file receipt.json --output receipt.signed.json
547
+ python3 .pakem/pakem.py identity verify receipt.signed.json
548
+ python3 .pakem/pakem.py identity rotate backend --reason "scheduled key rotation"
549
+
550
+ # Delegation tokens are limited by audience, action, and lifetime (30 seconds–24 hours)
551
+ python3 .pakem/pakem.py identity issue backend \
552
+ --audience pakem-host://worker-01 \
553
+ --action team.claim --action team.submit --ttl-seconds 900 > delegation.json
554
+ python3 .pakem/pakem.py identity verify delegation.json \
555
+ --audience pakem-host://worker-01 --action team.claim
556
+
557
+ python3 .pakem/pakem.py identity revoke backend --reason "agent retired"
558
+ ```
559
+
560
+ `identity rotate` membuat keypair baru dan mempertahankan public metadata key lama sebagai retired; signature lama tidak lagi diterima sebagai identitas aktif. Signature memverifikasi bahwa payload tidak berubah dan ditandatangani oleh private key yang cocok dengan public registry. Delegation token memeriksa subject, audience, action, expiry, dan revocation.
561
+
562
+ > ⚠️ **Ini bukan autentikasi transport atau sandbox**: token tetap bearer credential dan dapat di-replay selama masih valid. Host harus mengikat token ke koneksi/proses caller, membatasi audience/actions, mengatur anti-replay, menjaga waktu sistem, serta melindungi registry dan private key. Mengganti project path akan menghasilkan namespace private-key yang berbeda; provisioning key untuk host lain harus dilakukan melalui kanal aman.
563
+
564
+ ### 🗄️ Backend koordinasi SQLite
565
+
566
+ JSON board + JSONL tetap menjadi default agar project lama tidak berubah. Migrasi hanya dilakukan dengan tindakan eksplisit:
567
+
568
+ ```bash
569
+ python3 .pakem/pakem.py team storage info
570
+ python3 .pakem/pakem.py team storage migrate --to sqlite
571
+ python3 .pakem/pakem.py team storage info --json
572
+ python3 .pakem/pakem.py team storage backup --output backups/pakem-team.sqlite3
573
+ ```
574
+
575
+ SQLite menyimpan board dan event ledger; setiap mutasi memperbarui keduanya dalam satu transaksi. File `board.json` dan `events.jsonl` asli dipertahankan sebagai backup dan tidak diperbarui lagi setelah SQLite menjadi authoritative. Backup online memakai SQLite backup API agar menghasilkan snapshot konsisten.
576
+
577
+ **Batas backend:** SQLite ini tetap lokal ke project directory dan bergantung pada locking SQLite/filesystem yang benar. Jangan mengandalkannya sebagai distributed database atau menaruh WAL database pada filesystem jaringan yang tidak menjamin locking. Koordinasi multi-host membutuhkan service backend terautentikasi tersendiri, yang belum disediakan release ini.
578
+
579
+ ### 📋 Profil conformance
580
+
581
+ `conformance/v1/README.md` mendefinisikan kewajiban implementasi dan batas klaim conformance. Test executable ada di `tests/test_release_110.py`. Kelulusan test tidak membuktikan transport authentication, process isolation, distributed consensus, atau kebenaran hasil kerja agent.
582
+
583
+ <img src="assets/divider.svg" alt="" width="100%">
584
+
585
+ ## 👥 Koordinasi Multi-Agent (v0.9.0+)
586
+
587
+ Pakem dapat mengelola shared task board untuk agent kooperatif: registrasi role/capability, task yang sadar dependency, assignment, lease eksklusif yang kedaluwarsa, heartbeat, release, handoff, submission dengan evidence reference, dan review independen. State disimpan di `.pakem/team/`; lock file menserialisasi operasi lintas proses pada filesystem lokal.
588
+
589
+ ```bash
590
+ pakem team init
591
+ pakem team register lead --role lead
592
+ pakem team register backend --role worker --capability python --capability api
593
+ pakem team register reviewer --role reviewer
594
+ pakem team add T1 --title "Implement API" --files src/api.py tests/test_api.py --risk medium --capability python
595
+ pakem team assign T1 --agent backend --by lead
596
+ pakem team claim T1 --agent backend
597
+ pakem team heartbeat T1 --agent backend
598
+ pakem team submit T1 --agent backend --summary "API implemented and tested" --evidence tests/test_api.py --evidence commit:abc123
599
+ pakem team review T1 --reviewer reviewer --decision approve
600
+ pakem team status --json
601
+
602
+ # optional: bind the action to an Ed25519 identity and prove the board was not altered
603
+ pakem team submit T1 --agent backend --summary "API implemented" --evidence tests/test_api.py --sign
604
+ pakem team review T1 --reviewer reviewer --decision approve --sign
605
+ pakem team verify --json
606
+ ```
607
+
608
+ Task tetap di `review` sampai reviewer lain menyetujuinya. Dependency baru bisa di-claim setelah task induknya `done`. Claim yang kedaluwarsa bisa diambil ulang. ID/role agent adalah metadata kooperatif, bukan autentikasi; host tepercaya harus mengikat identitas caller yang terautentikasi ke `--agent`.
609
+
610
+ Dengan identitas Ed25519 terpasang, `team register` mengikat fingerprint-nya ke board, `--sign` menyegel setiap payload submission dan review, dan `pakem team verify` memeriksa signature, status revocation, serta apakah board masih cocok dengan yang ditandatangani: tamper-evident, bukan autentikasi transport. Pakem tidak spawn agent, menjalankan command, mem-sandbox scope file, merge branch, atau menyediakan distributed consensus. Event ledger koordinasi adalah receipt audit, bukan bukti bahwa evidence sudah diverifikasi secara independen. Lihat `.pakem/coordination/v1/README.md` untuk lifecycle dan batas kepercayaan.
611
+
612
+ <img src="assets/divider.svg" alt="" width="100%">
613
+
614
+ ## 🌙 Batasan jujur
615
+
616
+ > *Bahkan protagonis terkuat punya batas. Lebih baik tahu lebih awal.* (´・ω・`)
617
+
618
+ - Bukan pengganti test: gate memaksa test jalan, bukan menjamin test-nya bagus.
619
+ - Bukan sandbox: agent tetap bisa mengabaikan instruksi. Hook dan exit code mempersempit celahnya, tidak menutupnya.
620
+ - Bukan memori semantik/vector: ini file terstruktur yang bisa dibaca dan di-diff.
621
+ - Koordinasi multi-agent bersifat lokal: Pakem menyediakan shared board, lease, handoff, dan independent review, tetapi belum spawn agent, menjalankan command, merge branch, atau menyediakan distributed consensus. Isolasi direktori kerja tersedia lewat `pakem worktree` (Git worktree lokal); merge/push tetap tanggung jawab operator.
622
+ - Pakem Protocol v1.0 menyediakan JSON/JSONL contract, CLI validator, dan MCP stdio adapter lokal (read-only secara default); transport remote dan SDK lintas bahasa tidak disediakan.
623
+ - Event ledger bersifat append-only pada jalur CLI, tetapi bukan storage immutable: pengguna dengan akses filesystem tetap dapat mengubahnya.
624
+ - Gate drift hanya memeriksa path di backtick; bukan analisis kode. Dependency graph/impact menambah analisis import statis, tetapi belum mencakup seluruh hubungan runtime.
625
+ - `audit` menilai keberadaan artefak dan flag risiko, bukan kualitas isinya. Deteksi env/CI/lockfile berbasis pola file, bukan analisis mendalam.
626
+ - Bukti `verifyEvidence` membuktikan perintah dijalankan dan exit/hash-nya, bukan bahwa test-nya cukup atau benar.
627
+ - Lock antar-proses bergantung pada `flock`/`msvcrt`; perilaku di NFS, container read-only, dan Windows belum diuji.
628
+ - `SPEC.md` dan `PLAN.md` adalah penanda lokal: `spec --approve` / `plan done` bisa diubah agent. Pakem membuatnya terlihat dan digate, bukan menandatanganinya secara kriptografis.
629
+ - Pakem menyediakan wadah spec dan aturan bertanya; ia bukan interviewer otomatis yang menanyakan satu per satu bagian spec.
630
+
631
+ <img src="assets/divider.svg" alt="" width="100%">
632
+
633
+ ## 🌸 Peta jalan
634
+
635
+ - [ ] Runtime lifecycle hooks universal (Stop/AfterTool sesuai kemampuan host agent)
636
+ - [ ] Context retrieval yang memanfaatkan graph, MODULE-MAP, symbol index, dan hasil pekerjaan sebelumnya
637
+ - [ ] Impact analysis lebih dalam (AST/symbol-level, framework routing, path alias, generated code) dan pemicu otomatis dari workflow hooks
638
+ - [ ] Evidence ledger yang dapat diverifikasi/ditandatangani dan provenance perubahan
639
+ - [ ] Policy engine + guarded autonomy dengan approval untuk operasi berisiko
640
+ - [ ] MCP HTTP transport dan SDK referensi untuk Python/TypeScript
641
+ - [ ] Authenticated agent identity, remote coordination adapter/database backend, dan conflict-aware merge orchestration
642
+ - [ ] Documentation drift dan audit lebih dalam untuk API/DB/infra
643
+ - [ ] Template CI untuk GitLab/CircleCI selain GitHub Actions
644
+
645
+ <img src="assets/divider.svg" alt="" width="100%">
646
+
647
+ ## 📦 Lisensi & distribusi
648
+
649
+ MIT — lihat `LICENSE`.
650
+
651
+ Struktur mengikuti format Agent Skills/skill-creator: `SKILL.md`, `assets/templates/`, `references/`, `scripts/`, `evals/`, dan `tests/`. Isi `evals/` dijalankan dengan `python3 scripts/run_evals.py` (lihat `evals/README.md`). Validasi dan paket:
652
+
653
+ ```bash
654
+ python3 ~/.agents/skills/skill-creator/scripts/quick_validate.py .
655
+ python3 ~/.agents/skills/skill-creator/scripts/package_skill.py . dist
656
+ ```
657
+
658
+ Hasil paket: `dist/pakem.zip` (di-ignore git).
659
+
660
+ <img src="assets/divider.svg" alt="" width="100%">
661
+
662
+ <div align="center">
663
+
664
+ <img src="assets/footer.svg" alt="Terima kasih sudah membaca, petualang. Agent boleh ganti; pakem tetap." width="100%">
665
+
666
+ </div>