pakem-cli 0.0.0-stage → 1.2.1
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.
- package/CHANGELOG.md +271 -0
- package/LICENSE +21 -0
- package/README-ID.md +665 -0
- package/README.md +664 -2
- package/SKILL.md +264 -0
- package/adapters/git-worktree/v1/README.md +17 -0
- package/adapters/identity/v1/README.md +26 -0
- package/adapters/mcp/v1/README.md +56 -0
- package/adapters/storage-sqlite/v1/README.md +5 -0
- package/assets/banner.svg +275 -0
- package/assets/divider.svg +82 -0
- package/assets/footer.svg +174 -0
- package/assets/templates/BUG-HISTORY.md +18 -0
- package/assets/templates/CONTEXT.md +26 -0
- package/assets/templates/DECISIONS.md +8 -0
- package/assets/templates/MODULE-MAP.md +14 -0
- package/assets/templates/POLICY.json +15 -0
- package/assets/templates/PROJECT.md +42 -0
- package/conformance/v1/README.md +15 -0
- package/coordination/v1/README.md +14 -0
- package/coordination/v1/board.schema.json +59 -0
- package/coordination/v1/event.schema.json +26 -0
- package/coordination/v1/status.schema.json +49 -0
- package/evals/README.md +63 -0
- package/evals/evals.json +276 -0
- package/identity/v1/README.md +14 -0
- package/identity/v1/agent-identity.schema.json +95 -0
- package/identity/v1/identity-registry.schema.json +29 -0
- package/identity/v1/signed-payload.schema.json +42 -0
- package/intelligence/v1/README.md +19 -0
- package/intelligence/v1/dependency-graph.schema.json +82 -0
- package/intelligence/v1/impact-analysis.schema.json +51 -0
- package/intelligence/v1/reconciliation.schema.json +156 -0
- package/npm/bin/pakem.js +150 -0
- package/npm/check-version.js +26 -0
- package/package.json +55 -4
- package/policy/v1/README.md +15 -0
- package/policy/v1/policy.schema.json +20 -0
- package/protocol/v1/README.md +68 -0
- package/protocol/v1/capabilities.schema.json +17 -0
- package/protocol/v1/event.schema.json +114 -0
- package/protocol/v1/session.schema.json +51 -0
- package/references/artifacts.md +96 -0
- package/references/conventions.md +83 -0
- package/references/reviews.md +44 -0
- package/runtime/v1/README.md +21 -0
- package/runtime/v1/approval.schema.json +100 -0
- package/runtime/v1/checkpoint.schema.json +17 -0
- package/runtime/v1/hook-decision.schema.json +34 -0
- package/runtime/v1/hook-payload.schema.json +12 -0
- package/runtime/v1/task-evidence.schema.json +38 -0
- package/runtime/v1/work-report.schema.json +123 -0
- package/runtime/v1/workflow.schema.json +21 -0
- package/scripts/__pycache__/pakem.cpython-312.pyc +0 -0
- package/scripts/pakem.py +4911 -0
- package/scripts/pakem_core/__init__.py +3 -0
- package/scripts/pakem_core/__pycache__/__init__.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/coordination.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/git_worktree.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/identity.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/intelligence.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/mcp_server.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/protocol.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/reconcile.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/runtime.cpython-312.pyc +0 -0
- package/scripts/pakem_core/coordination.py +977 -0
- package/scripts/pakem_core/git_worktree.py +265 -0
- package/scripts/pakem_core/identity.py +494 -0
- package/scripts/pakem_core/intelligence.py +684 -0
- package/scripts/pakem_core/mcp_server.py +308 -0
- package/scripts/pakem_core/protocol.py +61 -0
- package/scripts/pakem_core/reconcile.py +119 -0
- package/scripts/pakem_core/runtime.py +457 -0
- package/scripts/run_evals.py +289 -0
- package/storage/v1/README.md +14 -0
- package/storage/v1/team-storage.schema.json +27 -0
package/README-ID.md
ADDED
|
@@ -0,0 +1,665 @@
|
|
|
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
|
+

|
|
8
|
+

|
|
9
|
+

|
|
10
|
+

|
|
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¢er=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+):
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
npx pakem # ~/.claude/skills/pakem
|
|
91
|
+
npx pakem install --project # ./.claude/skills/pakem
|
|
92
|
+
npx pakem install --dir ~/.agents/skills/pakem
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Paket ini hanya menyalin skill; tidak menambah dependency npm ke proyekmu. Argumen lain diteruskan ke CLI Python bawaan paket (`npx pakem init --type app`).
|
|
96
|
+
|
|
97
|
+
Butuh **Python 3.10+**. CLI/Core dasar hanya memakai standard library. Operasi identitas Ed25519 opsional dan memerlukan `python -m pip install cryptography`.
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
cd proyek-kamu
|
|
101
|
+
python3 /path/ke/pakem/scripts/pakem.py init --type app
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`--type`: `app` (default), `library`, `oneoff`, `research`.
|
|
105
|
+
Tambahan: `--verify "npm test && npm run lint"`, `--adapter claude,codex,cursor,gemini,copilot` (atau `none`), `--hook`.
|
|
106
|
+
|
|
107
|
+
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.
|
|
108
|
+
|
|
109
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
110
|
+
|
|
111
|
+
## 🍡 Arc 2 · Ritual Harian (Pemakaian harian)
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
python3 .pakem/pakem.py start "build a todo web app" # or resume an interrupted session
|
|
115
|
+
python3 .pakem/pakem.py step "model done" --next "build the endpoint"
|
|
116
|
+
python3 .pakem/pakem.py adr "Choose SQLite" # when an architecture decision appears
|
|
117
|
+
python3 .pakem/pakem.py bug "Crash on empty input" --symptom "..." --cause "..." --fix "..." --prevent "..."
|
|
118
|
+
python3 .pakem/pakem.py spec "Export feature" # fill, then: pakem spec --approve
|
|
119
|
+
python3 .pakem/pakem.py plan add "write the parser" --files "src/parser.ts,tests/parser.test.ts" --verify "npm test -- parser"
|
|
120
|
+
python3 .pakem/pakem.py plan done T1 # runs the task verify + stores evidence
|
|
121
|
+
python3 .pakem/pakem.py audit # which files/docs are worth having (read-only)
|
|
122
|
+
python3 .pakem/pakem.py finish --summary "todo CRUD works, tests pass" # add --fixed-bug / --strict when needed
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**🗡️ 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`.
|
|
126
|
+
|
|
127
|
+
> 🪟 **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**.
|
|
128
|
+
|
|
129
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
130
|
+
|
|
131
|
+
## 🔮 Arc 3 · Protokol & Antarmuka Mesin
|
|
132
|
+
|
|
133
|
+
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/`.
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
python3 .pakem/pakem.py protocol info
|
|
137
|
+
python3 .pakem/pakem.py protocol negotiate --peer-version 1.0 --capability events.v1 --capability context.snapshot.v1 --capability coordination.v1 --json
|
|
138
|
+
python3 .pakem/pakem.py context --json # compact snapshot for agents/tools
|
|
139
|
+
python3 .pakem/pakem.py events --json # structured event history
|
|
140
|
+
python3 .pakem/pakem.py events --verify # verify the ledger hash chain
|
|
141
|
+
python3 .pakem/pakem.py events --sign --identity backend # seal the ledger with Ed25519
|
|
142
|
+
python3 .pakem/pakem.py report --json # roll-up of sessions, tasks, evidence, ledger
|
|
143
|
+
python3 .pakem/pakem.py events --session <session-id>
|
|
144
|
+
python3 .pakem/pakem.py protocol validate-event event.json
|
|
145
|
+
python3 .pakem/pakem.py protocol validate-session session.json
|
|
146
|
+
|
|
147
|
+
# Intelligent Core: dependency graph and change impact
|
|
148
|
+
python3 .pakem/pakem.py graph --json
|
|
149
|
+
python3 .pakem/pakem.py graph --json --output .pakem/dependency-graph.json
|
|
150
|
+
python3 .pakem/pakem.py impact --files src/auth.py tests/test_auth.py --json
|
|
151
|
+
python3 .pakem/pakem.py impact --base main --json
|
|
152
|
+
python3 .pakem/pakem.py impact --staged --strict --json
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### 🕸️ Graph & Dampak
|
|
156
|
+
|
|
157
|
+
`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.
|
|
158
|
+
|
|
159
|
+
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.
|
|
160
|
+
|
|
161
|
+
### 📼 Ledger Event
|
|
162
|
+
|
|
163
|
+
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.
|
|
164
|
+
|
|
165
|
+
### 🧿 Snapshot Konteks
|
|
166
|
+
|
|
167
|
+
`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.
|
|
168
|
+
|
|
169
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
170
|
+
|
|
171
|
+
## 🌠 Protokol Operasi Stabil (Pakem 1.0+)
|
|
172
|
+
|
|
173
|
+
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.
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
python3 .pakem/pakem.py protocol info
|
|
177
|
+
python3 .pakem/pakem.py protocol negotiate --peer-version 1.0 \
|
|
178
|
+
--capability events.v1 --capability context.snapshot.v1 --capability coordination.v1 --json
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
> ⚠️ `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.
|
|
182
|
+
|
|
183
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
184
|
+
|
|
185
|
+
## 🔌 Adapter MCP (MCP 2026-07-28)
|
|
186
|
+
|
|
187
|
+
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.
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
# Read-only, default
|
|
191
|
+
python3 .pakem/pakem.py mcp serve
|
|
192
|
+
|
|
193
|
+
# Board mutation only when the host explicitly grants agent binding and write access
|
|
194
|
+
python3 .pakem/pakem.py mcp serve --agent-id backend --allow-write
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
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.
|
|
198
|
+
|
|
199
|
+
> ⚠️ `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.
|
|
200
|
+
|
|
201
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
202
|
+
|
|
203
|
+
## 🌿 Isolasi Git Worktree
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
python3 .pakem/pakem.py worktree create T1 --agent backend --base main
|
|
207
|
+
python3 .pakem/pakem.py worktree list --json
|
|
208
|
+
python3 .pakem/pakem.py worktree scope T1--backend --strict
|
|
209
|
+
python3 .pakem/pakem.py worktree remove .pakem/worktrees/T1--backend
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
`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".
|
|
213
|
+
|
|
214
|
+
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.
|
|
215
|
+
|
|
216
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
217
|
+
|
|
218
|
+
## 🤖 Runtime Otonom v1 (0.8.0)
|
|
219
|
+
|
|
220
|
+
`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.
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
# Start and monitor the runtime workflow
|
|
224
|
+
python3 .pakem/pakem.py runtime init "implementasi OAuth"
|
|
225
|
+
python3 .pakem/pakem.py runtime status --json
|
|
226
|
+
python3 .pakem/pakem.py runtime transition ready --reason "spec dan plan disetujui"
|
|
227
|
+
python3 .pakem/pakem.py runtime transition executing --task-id T1
|
|
228
|
+
|
|
229
|
+
# Checkpoint and recovery metadata
|
|
230
|
+
python3 .pakem/pakem.py runtime checkpoint --label "sebelum refactor" --json
|
|
231
|
+
python3 .pakem/pakem.py runtime recover --json
|
|
232
|
+
|
|
233
|
+
# Lifecycle hooks and policy
|
|
234
|
+
python3 .pakem/pakem.py runtime hook task.before --payload-file action.json --json
|
|
235
|
+
python3 .pakem/pakem.py policy show --json
|
|
236
|
+
python3 .pakem/pakem.py policy check --category deploy --risk high --target staging --json
|
|
237
|
+
python3 .pakem/pakem.py policy approve --category deploy --risk high --target staging --reason "user approved staging"
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
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.
|
|
241
|
+
|
|
242
|
+
**🎚️ Mode policy**
|
|
243
|
+
|
|
244
|
+
| Mode | Perilaku |
|
|
245
|
+
|---|---|
|
|
246
|
+
| `manual` | meminta approval untuk semua aksi selain read |
|
|
247
|
+
| `assisted` | mengizinkan edit biasa, tetapi meminta approval untuk command medium/high dan kategori sensitif |
|
|
248
|
+
| `guarded_autonomous` | mengizinkan aksi hingga `maxAutonomousRisk`, kecuali kategori yang selalu memerlukan approval |
|
|
249
|
+
|
|
250
|
+
`deniedCategories` tetap ditolak meskipun ada approval.
|
|
251
|
+
|
|
252
|
+
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.
|
|
253
|
+
|
|
254
|
+
**🪝 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.
|
|
255
|
+
|
|
256
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
257
|
+
|
|
258
|
+
## 🚨 Peringatan perubahan aturan
|
|
259
|
+
|
|
260
|
+
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:
|
|
261
|
+
|
|
262
|
+
```
|
|
263
|
+
[WARN] rules-changed: rule.tests relaxed: required -> skip
|
|
264
|
+
[WARN] rules-changed: verify changed: 'npm test' -> 'true'
|
|
265
|
+
[WARN] rules-changed: exposure downgraded: public -> private
|
|
266
|
+
[WARN] rules-changed: deploy downgraded: production -> none
|
|
267
|
+
[WARN] rules-changed: .pakem/pakem.py modified during this session
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
`finish` juga mencetak gap berisiko menurut flag:
|
|
271
|
+
|
|
272
|
+
```
|
|
273
|
+
[WARN] risk: deploy=production but no CI yet
|
|
274
|
+
[WARN] risk: deploy=production but no RUNBOOK.md yet
|
|
275
|
+
WARNING: 2 risks unresolved (advisory, non-blocking).
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
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.
|
|
279
|
+
|
|
280
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
281
|
+
|
|
282
|
+
## 🧭 Cek kondisi repo saat resume
|
|
283
|
+
|
|
284
|
+
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:
|
|
285
|
+
|
|
286
|
+
```
|
|
287
|
+
CHECK: repo state changed since the last record:
|
|
288
|
+
- HEAD changed (2 new commits)
|
|
289
|
+
- changed since the last record: M src/api.py; ?? scratch.txt
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Jadi `nextStep` yang basi atau kerja yang belum sempat dicatat langsung terlihat. Hanya aktif di repo git.
|
|
293
|
+
|
|
294
|
+
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.
|
|
295
|
+
|
|
296
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
297
|
+
|
|
298
|
+
## 🏯 Apa yang dibuat `init`
|
|
299
|
+
|
|
300
|
+
```
|
|
301
|
+
.pakem/
|
|
302
|
+
├── CONTEXT.md entry point + routing: read this first
|
|
303
|
+
├── PROJECT.md config (verify, rule.*) + stack + conventions
|
|
304
|
+
├── MODULE-MAP.md module map (app/library)
|
|
305
|
+
├── DECISIONS.md decision index (app/library/research)
|
|
306
|
+
├── BUG-HISTORY.md bug history (app/library)
|
|
307
|
+
├── pakem.py standalone CLI per project
|
|
308
|
+
├── POLICY.json autonomy and approval policy (project-managed)
|
|
309
|
+
├── pakem_core/ Core modules (intelligence + autonomous runtime)
|
|
310
|
+
├── protocol/v1/ event/session contract
|
|
311
|
+
├── intelligence/v1/ graph/impact output schemas
|
|
312
|
+
├── runtime/v1/ workflow/checkpoint/lifecycle hook schemas
|
|
313
|
+
├── policy/v1/ policy schema
|
|
314
|
+
├── sessions/ per-session JSON (gitignored by default)
|
|
315
|
+
├── events/ local event ledger (gitignored by default)
|
|
316
|
+
└── runtime/ workflow, checkpoints, approvals, hook receipts (gitignored)
|
|
317
|
+
docs/adr/ only when the adr rule is active (new project)
|
|
318
|
+
tests/ only when tests rule = required (new project)
|
|
319
|
+
CLAUDE.md, AGENTS.md, .cursor/rules/pakem.mdc adapters (marked blocks, existing content preserved)
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
**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.
|
|
323
|
+
|
|
324
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
325
|
+
|
|
326
|
+
## 📜 Konfigurasi (`.pakem/PROJECT.md`)
|
|
327
|
+
|
|
328
|
+
Bagian atas file berisi konfigurasi, satu `key: value` per baris:
|
|
329
|
+
|
|
330
|
+
```
|
|
331
|
+
type: app
|
|
332
|
+
sensitive: false
|
|
333
|
+
exposure: private
|
|
334
|
+
deploy: none
|
|
335
|
+
handover: false
|
|
336
|
+
verify: npm test && npm run lint
|
|
337
|
+
rule.tests: required
|
|
338
|
+
rule.adr: when-decision
|
|
339
|
+
rule.research: skip
|
|
340
|
+
reason.research: stack sudah ditentukan user, tidak ada eksplorasi
|
|
341
|
+
rule.modular: required
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
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.
|
|
345
|
+
|
|
346
|
+
**🚩 Flag risiko** (dibaca `pakem audit`, bukan gate):
|
|
347
|
+
|
|
348
|
+
| Flag | Nilai | Efek pada audit |
|
|
349
|
+
|---|---|---|
|
|
350
|
+
| `exposure` | `private` / `public` | publik → saran LICENSE, CONTRIBUTING, SECURITY, template PR/issue |
|
|
351
|
+
| `deploy` | `none` / `staging` / `production` | deploy → saran CI, DEPLOYMENT, RUNBOOK |
|
|
352
|
+
| `handover` | `true` / `false` | true → saran HANDOVER, akses, known issues, tech debt |
|
|
353
|
+
| `sensitive` | `true` / `false` | true → saran SECURITY, threat model, secret scan |
|
|
354
|
+
|
|
355
|
+
`start` memotret keempat flag ini; menurunkannya saat sesi berjalan memunculkan `[WARN] rules-changed`. Audit tetap read-only dan tidak pernah membuat file.
|
|
356
|
+
|
|
357
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
358
|
+
|
|
359
|
+
## 📝 Spec & plan (opsional)
|
|
360
|
+
|
|
361
|
+
Untuk fitur/perubahan multi-file, jangan langsung ngoding. Untuk typo atau edit satu file, lewati.
|
|
362
|
+
|
|
363
|
+
```bash
|
|
364
|
+
python3 .pakem/pakem.py spec "Export feature" # create .pakem/SPEC.md
|
|
365
|
+
# fill Problem / Non-goals / Acceptance / Approach
|
|
366
|
+
python3 .pakem/pakem.py spec --approve # all [FILL] placeholders must be filled
|
|
367
|
+
|
|
368
|
+
python3 .pakem/pakem.py plan add "write the parser" \
|
|
369
|
+
--files "src/parser.ts,tests/parser.test.ts" \
|
|
370
|
+
--verify "npm test -- parser"
|
|
371
|
+
python3 .pakem/pakem.py plan list
|
|
372
|
+
python3 .pakem/pakem.py plan done T1 # runs the task verify + stores evidence
|
|
373
|
+
python3 .pakem/pakem.py plan drop T2 --reason "no longer relevant"
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
- 📄 `SPEC.md` berstatus `draft` sampai `spec --approve`; selama draft, `check`/`finish` gagal di gate `spec`.
|
|
377
|
+
- 🗒️ Setiap task berisi `files` dan `verify`; selama ada `[ ]`, `check`/`finish` gagal di gate `plan`. `plan drop` menandai task selesai dengan alasan.
|
|
378
|
+
- ✅ Bagian Acceptance `SPEC.md` harus dicentang (`- [x]`) sebelum `finish` lolos gate `acceptance`; `check` hanya menagih approval, karena spec disetujui sebelum kerja dimulai.
|
|
379
|
+
- 🧾 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.
|
|
380
|
+
- 🎯 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`.
|
|
381
|
+
- 🌿 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.
|
|
382
|
+
- ⏱️ Target task: 2–5 menit, satu perubahan kecil yang bisa diverifikasi.
|
|
383
|
+
- 👀 `start`/`status` menampilkan status spec dan progres plan; `doctor` memperingatkan kalau masih draft/pending.
|
|
384
|
+
|
|
385
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
386
|
+
|
|
387
|
+
## 🗝️ Sumber kebenaran (biar tidak duplikat)
|
|
388
|
+
|
|
389
|
+
| File | Peran | Jangan taruh |
|
|
390
|
+
|---|---|---|
|
|
391
|
+
| `PROJECT.md` | fakta + config proyek (`verify`, `rule.*`, flag) | riwayat task |
|
|
392
|
+
| `CONTEXT.md` | routing: baca apa dulu; protokolnya digenerate | spesifikasi fitur |
|
|
393
|
+
| `SPEC.md` | kenapa/apa + acceptance untuk satu pekerjaan | daftar task |
|
|
394
|
+
| `PLAN.md` | urutan task (how) untuk pekerjaan itu | masalah/non-goal |
|
|
395
|
+
| session JSON | apa yang benar-benar terjadi (`steps`, `nextStep`) | niat/rencana |
|
|
396
|
+
| `MODULE-MAP.md` | struktur modul | status pekerjaan |
|
|
397
|
+
| `DECISIONS.md` + `docs/adr/` | index + detail keputusan | bug/riwayat kerja |
|
|
398
|
+
| `BUG-HISTORY.md` | bug yang sudah diperbaiki | bug yang masih terbuka |
|
|
399
|
+
| `HANDOVER.md` | snapshot akhir: akses, kontak, sisa kerja, risiko | password/secret |
|
|
400
|
+
| `references/` | panduan generik | fakta spesifik proyek |
|
|
401
|
+
|
|
402
|
+
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.
|
|
403
|
+
|
|
404
|
+
| Perintah | Peran |
|
|
405
|
+
|---|---|
|
|
406
|
+
| `status` | ringkasan read-only |
|
|
407
|
+
| `check` | gate yang bisa gagal |
|
|
408
|
+
| `reconcile` | laporan read-only: perubahan Git vs scope task (plan/board) vs acceptance (`--json`, `--strict`) |
|
|
409
|
+
| `finish` | gate + bukti verify + tutup sesi |
|
|
410
|
+
| `audit` | inventaris artefak, advisory |
|
|
411
|
+
| `doctor` | diagnosis setup (config/git/hook/adapter/sesi) |
|
|
412
|
+
| `spec` / `plan` | state workflow, bukan gate verifikasi |
|
|
413
|
+
|
|
414
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
415
|
+
|
|
416
|
+
## 🔍 Audit artefak (`pakem audit`)
|
|
417
|
+
|
|
418
|
+
Pakem tidak mengejar kelengkapan file. `audit` memilah artefak berdasarkan `type`, `exposure`, `deploy`, `handover`, `sensitive`, dan isi repo:
|
|
419
|
+
|
|
420
|
+
```
|
|
421
|
+
AUDIT your-project
|
|
422
|
+
configuration: type=app exposure=private deploy=none handover=false sensitive=false
|
|
423
|
+
|
|
424
|
+
REQUIRED - continuity & verification
|
|
425
|
+
[ok] README.md
|
|
426
|
+
[gap] verify — fill in the test/lint/build command
|
|
427
|
+
[gap] tests/ — logic needs tests run by verify
|
|
428
|
+
|
|
429
|
+
RECOMMENDED - risk-based; may be deferred with a reason
|
|
430
|
+
[gap] .env.example — code reads the environment
|
|
431
|
+
...
|
|
432
|
+
|
|
433
|
+
NOT NEEDED - do not create just for completeness
|
|
434
|
+
[-] LICENSE — private repo; change exposure: public if it will be released
|
|
435
|
+
[-] docs/decisions/ — canonical: docs/adr/ — do not keep both
|
|
436
|
+
...
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
- 👁️ `audit` **read-only**: tidak membuat file, tidak mengubah konfigurasi.
|
|
440
|
+
- 🤖 `--json` untuk agent; `--strict` exit 1 bila ada REQUIRED yang kurang.
|
|
441
|
+
- 🕰️ Yang RECOMMENDED boleh ditunda dengan alasan jujur; jangan membuat file kosong.
|
|
442
|
+
- 🎬 `init` langsung mencetak ringkasan rencana artefak.
|
|
443
|
+
- ⚠️ `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.
|
|
444
|
+
- 📦 `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.
|
|
445
|
+
- 📚 Detail per mode kegagalan, pilihan kanonik (mis. `docs/adr/` bukan `docs/decisions/`), dan daftar yang tidak boleh dibuat otomatis: `references/artifacts.md`.
|
|
446
|
+
|
|
447
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
448
|
+
|
|
449
|
+
## 🩺 Diagnosis & perawatan
|
|
450
|
+
|
|
451
|
+
```bash
|
|
452
|
+
python3 .pakem/pakem.py doctor # check config, placeholders, git, hooks, adapters, sessions
|
|
453
|
+
python3 .pakem/pakem.py doctor --verify # also run the verify command
|
|
454
|
+
python3 .pakem/pakem.py prune # dry-run: show old sessions that can be pruned
|
|
455
|
+
python3 .pakem/pakem.py prune --yes # delete; active sessions and the newest N are kept
|
|
456
|
+
python3 .pakem/pakem.py ci # create .github/workflows/ci.yml
|
|
457
|
+
# Run the newest CLI from the skill install, from the project root (including upgrades from 0.6.x)
|
|
458
|
+
python3 /path/ke/pakem/scripts/pakem.py upgrade --dry-run
|
|
459
|
+
python3 /path/ke/pakem/scripts/pakem.py upgrade
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
- 🩹 `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.
|
|
463
|
+
- 🧹 `prune` default `--keep 20 --days 90`; sesi aktif tidak pernah dihapus, sesi korup tidak disentuh.
|
|
464
|
+
- 🏗️ `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.
|
|
465
|
+
- ⬆️ `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.
|
|
466
|
+
|
|
467
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
468
|
+
|
|
469
|
+
## 🧪 Bukti & `--strict`
|
|
470
|
+
|
|
471
|
+
`finish` menyimpan bukti verify di sesi (`verifyEvidence`): perintah, exit code, durasi, hash output, dan hash `.pakem/pakem.py`; saat dijalankan ia mencetak:
|
|
472
|
+
|
|
473
|
+
```
|
|
474
|
+
[EVIDENCE] verify: pass exit=0 hash=4355a46b19d348dc
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
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.
|
|
478
|
+
|
|
479
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
480
|
+
|
|
481
|
+
## 👓 Lensa review
|
|
482
|
+
|
|
483
|
+
`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.
|
|
484
|
+
|
|
485
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
486
|
+
|
|
487
|
+
## 🚪 Gate (`pakem finish` dan `pakem check`)
|
|
488
|
+
|
|
489
|
+
| Gate | Gagal bila |
|
|
490
|
+
|---|---|
|
|
491
|
+
| session | (hanya `finish`) tidak ada sesi aktif atau `--summary` kosong |
|
|
492
|
+
| bug | (hanya `finish --fixed-bug`) belum ada entri `pakem bug` di sesi ini |
|
|
493
|
+
| rules | `required` tak terpenuhi, atau `skip` tanpa alasan |
|
|
494
|
+
| placeholder | sisa `[FILL`, `[ISI` (lama), `{{...}}`, `TODO` di `.pakem/*.md` dan `docs/adr/*.md` |
|
|
495
|
+
| spec | `.pakem/SPEC.md` ada tapi belum `approved` |
|
|
496
|
+
| plan | `.pakem/PLAN.md` ada tapi masih ada task `[ ]` |
|
|
497
|
+
| drift | path di backtick pada MODULE-MAP/DECISIONS tidak ada di repo |
|
|
498
|
+
| verify | perintah `verify` exit non-nol, atau kosong tanpa `reason.verify` |
|
|
499
|
+
|
|
500
|
+
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.
|
|
501
|
+
|
|
502
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
503
|
+
|
|
504
|
+
## 🛡️ Enforcement
|
|
505
|
+
|
|
506
|
+
- **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.
|
|
507
|
+
- **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.
|
|
508
|
+
|
|
509
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
510
|
+
|
|
511
|
+
## 🧫 Tes
|
|
512
|
+
|
|
513
|
+
Suite penuh butuh dua dependency opsional (dipakai satu modul tes untuk Ed25519 dan satu untuk validasi JSON Schema):
|
|
514
|
+
|
|
515
|
+
```bash
|
|
516
|
+
python3 -m pip install -r requirements-dev.txt
|
|
517
|
+
python3 -m unittest discover -s tests -v
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
Tanpa dependency itu suite tetap jalan dan hijau; 14 tes melompat dengan alasan yang terlihat di output.
|
|
521
|
+
|
|
522
|
+
Eval perilaku skill (bukan kode) dicek terpisah:
|
|
523
|
+
|
|
524
|
+
```bash
|
|
525
|
+
python3 scripts/run_evals.py --validate # struktur evals.json
|
|
526
|
+
python3 scripts/run_evals.py --list # 24 eval
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
Menjalankan eval butuh perintah agent dan perintah judge; kontraknya di `evals/README.md`.
|
|
530
|
+
|
|
531
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
532
|
+
|
|
533
|
+
## 🌌 Fondasi Orkestrasi Produksi (1.1.0)
|
|
534
|
+
|
|
535
|
+
Pakem 1.1 menambahkan dua fondasi untuk koordinasi yang lebih kuat. Keduanya opt-in dan menjaga kompatibilitas default versi sebelumnya.
|
|
536
|
+
|
|
537
|
+
### 🔑 Identitas agent Ed25519
|
|
538
|
+
|
|
539
|
+
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.
|
|
540
|
+
|
|
541
|
+
```bash
|
|
542
|
+
# Needs the optional dependency: python -m pip install cryptography
|
|
543
|
+
python3 .pakem/pakem.py identity create backend
|
|
544
|
+
python3 .pakem/pakem.py identity list --json
|
|
545
|
+
python3 .pakem/pakem.py identity sign backend --file receipt.json --output receipt.signed.json
|
|
546
|
+
python3 .pakem/pakem.py identity verify receipt.signed.json
|
|
547
|
+
python3 .pakem/pakem.py identity rotate backend --reason "scheduled key rotation"
|
|
548
|
+
|
|
549
|
+
# Delegation tokens are limited by audience, action, and lifetime (30 seconds–24 hours)
|
|
550
|
+
python3 .pakem/pakem.py identity issue backend \
|
|
551
|
+
--audience pakem-host://worker-01 \
|
|
552
|
+
--action team.claim --action team.submit --ttl-seconds 900 > delegation.json
|
|
553
|
+
python3 .pakem/pakem.py identity verify delegation.json \
|
|
554
|
+
--audience pakem-host://worker-01 --action team.claim
|
|
555
|
+
|
|
556
|
+
python3 .pakem/pakem.py identity revoke backend --reason "agent retired"
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
`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.
|
|
560
|
+
|
|
561
|
+
> ⚠️ **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.
|
|
562
|
+
|
|
563
|
+
### 🗄️ Backend koordinasi SQLite
|
|
564
|
+
|
|
565
|
+
JSON board + JSONL tetap menjadi default agar project lama tidak berubah. Migrasi hanya dilakukan dengan tindakan eksplisit:
|
|
566
|
+
|
|
567
|
+
```bash
|
|
568
|
+
python3 .pakem/pakem.py team storage info
|
|
569
|
+
python3 .pakem/pakem.py team storage migrate --to sqlite
|
|
570
|
+
python3 .pakem/pakem.py team storage info --json
|
|
571
|
+
python3 .pakem/pakem.py team storage backup --output backups/pakem-team.sqlite3
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
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.
|
|
575
|
+
|
|
576
|
+
**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.
|
|
577
|
+
|
|
578
|
+
### 📋 Profil conformance
|
|
579
|
+
|
|
580
|
+
`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.
|
|
581
|
+
|
|
582
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
583
|
+
|
|
584
|
+
## 👥 Koordinasi Multi-Agent (v0.9.0+)
|
|
585
|
+
|
|
586
|
+
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.
|
|
587
|
+
|
|
588
|
+
```bash
|
|
589
|
+
pakem team init
|
|
590
|
+
pakem team register lead --role lead
|
|
591
|
+
pakem team register backend --role worker --capability python --capability api
|
|
592
|
+
pakem team register reviewer --role reviewer
|
|
593
|
+
pakem team add T1 --title "Implement API" --files src/api.py tests/test_api.py --risk medium --capability python
|
|
594
|
+
pakem team assign T1 --agent backend --by lead
|
|
595
|
+
pakem team claim T1 --agent backend
|
|
596
|
+
pakem team heartbeat T1 --agent backend
|
|
597
|
+
pakem team submit T1 --agent backend --summary "API implemented and tested" --evidence tests/test_api.py --evidence commit:abc123
|
|
598
|
+
pakem team review T1 --reviewer reviewer --decision approve
|
|
599
|
+
pakem team status --json
|
|
600
|
+
|
|
601
|
+
# optional: bind the action to an Ed25519 identity and prove the board was not altered
|
|
602
|
+
pakem team submit T1 --agent backend --summary "API implemented" --evidence tests/test_api.py --sign
|
|
603
|
+
pakem team review T1 --reviewer reviewer --decision approve --sign
|
|
604
|
+
pakem team verify --json
|
|
605
|
+
```
|
|
606
|
+
|
|
607
|
+
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`.
|
|
608
|
+
|
|
609
|
+
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.
|
|
610
|
+
|
|
611
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
612
|
+
|
|
613
|
+
## 🌙 Batasan jujur
|
|
614
|
+
|
|
615
|
+
> *Bahkan protagonis terkuat punya batas. Lebih baik tahu lebih awal.* (´・ω・`)
|
|
616
|
+
|
|
617
|
+
- Bukan pengganti test: gate memaksa test jalan, bukan menjamin test-nya bagus.
|
|
618
|
+
- Bukan sandbox: agent tetap bisa mengabaikan instruksi. Hook dan exit code mempersempit celahnya, tidak menutupnya.
|
|
619
|
+
- Bukan memori semantik/vector: ini file terstruktur yang bisa dibaca dan di-diff.
|
|
620
|
+
- 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.
|
|
621
|
+
- 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.
|
|
622
|
+
- Event ledger bersifat append-only pada jalur CLI, tetapi bukan storage immutable: pengguna dengan akses filesystem tetap dapat mengubahnya.
|
|
623
|
+
- Gate drift hanya memeriksa path di backtick; bukan analisis kode. Dependency graph/impact menambah analisis import statis, tetapi belum mencakup seluruh hubungan runtime.
|
|
624
|
+
- `audit` menilai keberadaan artefak dan flag risiko, bukan kualitas isinya. Deteksi env/CI/lockfile berbasis pola file, bukan analisis mendalam.
|
|
625
|
+
- Bukti `verifyEvidence` membuktikan perintah dijalankan dan exit/hash-nya, bukan bahwa test-nya cukup atau benar.
|
|
626
|
+
- Lock antar-proses bergantung pada `flock`/`msvcrt`; perilaku di NFS, container read-only, dan Windows belum diuji.
|
|
627
|
+
- `SPEC.md` dan `PLAN.md` adalah penanda lokal: `spec --approve` / `plan done` bisa diubah agent. Pakem membuatnya terlihat dan digate, bukan menandatanganinya secara kriptografis.
|
|
628
|
+
- Pakem menyediakan wadah spec dan aturan bertanya; ia bukan interviewer otomatis yang menanyakan satu per satu bagian spec.
|
|
629
|
+
|
|
630
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
631
|
+
|
|
632
|
+
## 🌸 Peta jalan
|
|
633
|
+
|
|
634
|
+
- [ ] Runtime lifecycle hooks universal (Stop/AfterTool sesuai kemampuan host agent)
|
|
635
|
+
- [ ] Context retrieval yang memanfaatkan graph, MODULE-MAP, symbol index, dan hasil pekerjaan sebelumnya
|
|
636
|
+
- [ ] Impact analysis lebih dalam (AST/symbol-level, framework routing, path alias, generated code) dan pemicu otomatis dari workflow hooks
|
|
637
|
+
- [ ] Evidence ledger yang dapat diverifikasi/ditandatangani dan provenance perubahan
|
|
638
|
+
- [ ] Policy engine + guarded autonomy dengan approval untuk operasi berisiko
|
|
639
|
+
- [ ] MCP HTTP transport dan SDK referensi untuk Python/TypeScript
|
|
640
|
+
- [ ] Authenticated agent identity, remote coordination adapter/database backend, dan conflict-aware merge orchestration
|
|
641
|
+
- [ ] Documentation drift dan audit lebih dalam untuk API/DB/infra
|
|
642
|
+
- [ ] Template CI untuk GitLab/CircleCI selain GitHub Actions
|
|
643
|
+
|
|
644
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
645
|
+
|
|
646
|
+
## 📦 Lisensi & distribusi
|
|
647
|
+
|
|
648
|
+
MIT — lihat `LICENSE`.
|
|
649
|
+
|
|
650
|
+
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:
|
|
651
|
+
|
|
652
|
+
```bash
|
|
653
|
+
python3 ~/.agents/skills/skill-creator/scripts/quick_validate.py .
|
|
654
|
+
python3 ~/.agents/skills/skill-creator/scripts/package_skill.py . dist
|
|
655
|
+
```
|
|
656
|
+
|
|
657
|
+
Hasil paket: `dist/pakem.zip` (di-ignore git).
|
|
658
|
+
|
|
659
|
+
<img src="assets/divider.svg" alt="" width="100%">
|
|
660
|
+
|
|
661
|
+
<div align="center">
|
|
662
|
+
|
|
663
|
+
<img src="assets/footer.svg" alt="Terima kasih sudah membaca, petualang. Agent boleh ganti; pakem tetap." width="100%">
|
|
664
|
+
|
|
665
|
+
</div>
|