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.md CHANGED
@@ -1,3 +1,666 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <img src="assets/banner.svg" alt="Pakem: Agents may change; pakem stays." 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
+ **Language: [English](README.md) | [Bahasa Indonesia](README-ID.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+A+working-discipline+layer+for+coding+agents+%E2%9C%A6;Not+a+library%2C+not+a+framework.;Agents+may+change%3B+pakem+stays.+%F0%9F%8C%B8" alt="typing animation" />
16
+ </a>
17
+
18
+ <br>
19
+
20
+ Pakem makes agent work **consistent** 🌙, **resumable** 🔁, and **provably finished** ✅.
21
+
22
+ </div>
23
+
24
+ <img src="assets/divider.svg" alt="" width="100%">
25
+
26
+ ## 📖 Table of Contents
27
+
28
+ | Arc | Chapter |
29
+ |---|---|
30
+ | 🌅 **Prologue** | [Problems it solves](#-prologue-problems-it-solves) |
31
+ | ⚔️ **Arc 1: Awakening** | [Install](#-arc-1--awakening-install) · [Daily usage](#-arc-2--daily-quest-daily-usage) |
32
+ | 🔮 **Arc 2: Protocol** | [Protocol & machine interface](#-arc-3--the-protocol--machine-interface) · [Stable protocol](#-stable-operating-protocol-pakem-10) · [MCP](#-mcp-adapter-mcp-2026-07-28) |
33
+ | 🛡️ **Arc 3: Guardians** | [Worktree](#-git-worktree-isolation) · [Runtime](#-autonomous-runtime-v1-080) · [Rule-change warnings](#-rule-change-warnings) |
34
+ | 📜 **Arc 4: Scrolls** | [Config](#-configuration-pakemprojectmd) · [Spec & plan](#-spec--plan-optional) · [Sources of truth](#-sources-of-truth-so-nothing-is-duplicated) |
35
+ | 🔍 **Arc 5: Trials** | [Audit](#-artifact-audit-pakem-audit) · [Gates](#-gates-pakem-finish-and-pakem-check) · [Evidence](#-evidence-and---strict) |
36
+ | 🌌 **Arc 6: Ascension** | [1.1.0 foundations](#-production-orchestration-foundations-110) · [Multi-agent](#-multi-agent-coordination-v090) |
37
+ | 🌙 **Epilogue** | [Limitations](#-honest-limitations) · [Roadmap](#-roadmap) · [License](#-license-and-distribution) |
38
+
39
+ <img src="assets/divider.svg" alt="" width="100%">
40
+
41
+ ## 🌅 Prologue: Problems it solves
42
+
43
+ > *Every hero has a weakness. These are the ones agents face, and what Pakem puts in place.* (◕‿◕)♡
44
+
45
+ | 💢 Real problem | ✨ What Pakem puts in place |
46
+ |---|---|
47
+ | Agents forget project conventions in every new session | `CONTEXT.md` (routing) + `PROJECT.md` |
48
+ | Work stops mid-way, tomorrow starts from zero | `.pakem/sessions/*.json` with `lastPosition` + `nextStep` |
49
+ | An agent says "done" but it might not be | `pakem finish`: a gate that can fail (exit code 1) |
50
+ | The same bug gets fixed repeatedly | `BUG-HISTORY.md` |
51
+ | Architecture decisions get re-debated | `DECISIONS.md` + `docs/adr/` |
52
+ | Claude, Cursor, Codex each have different rules | adapters generated from one source |
53
+ | Project files are still full of placeholders | placeholder gate |
54
+ | Module docs are stale and mention deleted files | drift gate |
55
+ | Unclear which files/docs should exist | `pakem audit`: REQUIRED / RECOMMENDED / NOT NEEDED, without creating empty files |
56
+ | Agents start coding without an approved spec | `pakem spec` + `spec --approve`; `spec` gate |
57
+ | Large work is not broken down and drifts easily | `pakem plan`: 2–5 minute tasks + files + verify; `plan` gate |
58
+ | Agents drift outside the plan | `pakem reconcile` + `scope` gate (out-of-scope code fails; docs/config are reported) |
59
+ | A spec is "approved" while acceptance criteria are unproven | `acceptance` gate (at `finish`) rejects unchecked boxes |
60
+ | Agents/tools need the same work contract | Pakem Protocol v1.0 + JSON Schema |
61
+ | Agents need workflow context without parsing Markdown | `pakem context --json` |
62
+ | Gates can be run by a CLI the agent has modified | `pakem.py` manifest + `pakem_core/*` pinned at `start`; `pakem integrity` + `finish --strict` |
63
+ | The seal key exists on only one host | `--key` / `PAKEM_SEAL_KEY` + `identity import` for hosts without the private key |
64
+ | HANDOVER.md is filled in but from an old commit | HEAD stamp + `handover` gate, `--check`/`--stamp` |
65
+ | Worktrees pile up after tasks finish | `plan done` cleans up merged, clean worktrees and reports the rest |
66
+ | No work numbers that can be defended | `pakem report`: duration, steps, tasks, verify evidence, ledger status |
67
+ | Session notes can be edited without a trace | hash chain (`events --verify`) + Ed25519 seal (`events --sign`) |
68
+ | Cross-module changes are hard to map | `pakem graph` + `pakem impact` |
69
+ | Lifecycle history is hard to audit across tools | append-only JSONL event ledger + `pakem events` |
70
+ | Agent workflows are hard to standardize and recover | `pakem runtime`: state machine, checkpoints, recovery metadata |
71
+ | Risky actions need limits across agents | `POLICY.json`, one-shot approvals, lifecycle hooks |
72
+ | Several agents work on the same project without coordination | `pakem team`: task dependencies, leases, handover, shared board, independent review |
73
+ | Tool/model integrations keep changing | Pakem Protocol v1.0 stable + capability negotiation |
74
+ | Agents need a universal tool interface | MCP stateless stdio adapter; read-only by default, write tools bound to the host agent |
75
+ | Agents edit the same files from a shared working tree | Git worktree isolation per task/agent; no implicit merge/push |
76
+ | Agents drift inside a worktree and then it gets merged | `worktree` gate + `pakem worktree scope` compares the worktree diff with the task scope |
77
+ | Agent identity is just a metadata ID | Ed25519 public identity, signed attestations, revocation, and scoped delegation tokens |
78
+ | Local board/events need atomic state+audit transactions | local SQLite backend with board+event transactions and online backup |
79
+ | Protocol implementations need repeatable compatibility evidence | Pakem Conformance Profile v1 with regression tests |
80
+
81
+ <img src="assets/divider.svg" alt="" width="100%">
82
+
83
+ ## ⚔️ Arc 1 · Awakening (Install)
84
+
85
+ This folder is a skill. Put it in as `pakem/` inside your agent's skills folder (e.g. `.claude/skills/pakem/` or `~/.claude/skills/pakem/`). For other agents, just run the CLI directly.
86
+
87
+ With Node 18+, the npm package installs the skill for you (Pakem itself still runs on Python 3.10+). In a terminal it opens a picker; flags keep it non-interactive:
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
+ The package only copies the skill; it adds no npm dependency to your project. Any other argument is delegated to the bundled Python CLI (`npx pakem-cli init --type app`).
97
+
98
+ Requires **Python 3.10+**. The base CLI/Core uses only the standard library. Ed25519 identity operations are optional and require `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
+ Extras: `--verify "npm test && npm run lint"`, `--adapter claude,codex,cursor,gemini,copilot` (or `none`), `--hook`.
107
+
108
+ After init, the CLI and the Pakem Core modules are copied into `.pakem/` so the project is self-contained. Core is split from the CLI so other runtimes can use the intelligence capabilities.
109
+
110
+ <img src="assets/divider.svg" alt="" width="100%">
111
+
112
+ ## 🍡 Arc 2 · Daily Quest (Daily usage)
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
+ **🗡️ Other commands:** `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:** replace `python3` with `python` or `py -3`. The adapters and `CONTEXT.md` already explain this to agents, and the git hook looks for an interpreter that actually runs. Windows support is written carefully but **not tested on Windows**.
129
+
130
+ <img src="assets/divider.svg" alt="" width="100%">
131
+
132
+ ## 🔮 Arc 3 · The Protocol & Machine Interface
133
+
134
+ Pakem Protocol v1.0 separates the workflow contract from the CLI, AI model, language, and transport. The event envelope and session v1.0 compatibility are frozen; additional features are negotiated through capabilities. The spec and JSON Schema live in `.pakem/protocol/v1/`; the distribution source lives in `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 & Impact
157
+
158
+ `pakem graph` builds a static graph from local imports, including `paths`/`baseUrl` aliases in `tsconfig.json`/`jsconfig.json` (following `extends`, ignoring JSONC comments). Imports that cannot be resolved appear in `unresolved_imports` with the reason, and dependency cycles appear in `circular_dependencies`. `pakem impact` walks direct/transitive dependents, possibly affected tests, and risk signals.
159
+
160
+ The analysis is advisory and best-effort: dynamic imports, reflection, framework routing, code generation, and runtime wiring can be missed. `impact` includes `graph_health`: if any import is unresolved, the result is marked incomplete and its recommendation says to check aliases/baseUrl or verify manually. `--strict` returns exit 1 when the risk heuristic is HIGH; the command does not run tests and does not replace real review or verification. The scanner is read-only unless `graph --output` is explicitly requested.
161
+
162
+ ### 📼 Event Ledger
163
+
164
+ Session and task lifecycle is recorded automatically as JSONL in `.pakem/events/` (local, gitignored by default). Events are appended and serialized with a Pakem lock. The ledger makes audit/handover easier, but it is **not cryptographically signed** and is not proof that the work is correct; verify results are still stored separately as evidence.
165
+
166
+ ### 🧿 Context Snapshot
167
+
168
+ `context --json` provides project metadata, the active session, spec/plan progress, read-only gate results (without running verify), blockers, recommended next steps, and runtime/policy status when installed. It does not send source code content, verify commands, or secrets.
169
+
170
+ <img src="assets/divider.svg" alt="" width="100%">
171
+
172
+ ## 🌠 Stable Operating Protocol (Pakem 1.0+)
173
+
174
+ Pakem Protocol v1.0 is a stable contract separate from the CLI, MCP, model, language, and provider versions. The event envelope shape and session v1.0 compatibility rules are frozen. New features are declared through capability negotiation; a capability is not authorization to perform side effects.
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`, agent IDs on the team board, and MCP `clientInfo` are attribution metadata. None of them proves identity. Runtime hosts must bind the caller to a trusted identity through an appropriate process/credential/transport boundary.
183
+
184
+ <img src="assets/divider.svg" alt="" width="100%">
185
+
186
+ ## 🔌 MCP Adapter (MCP 2026-07-28)
187
+
188
+ Pakem ships an MCP server over stdio with no external dependencies. The adapter targets modern stateless MCP: protocol version and client capabilities are sent on every request via `params._meta`; `server/discover` advertises version/capabilities, while `tools/list` and `tools/call` expose Pakem functions.
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, and policy check. Write mode exposes claim, heartbeat, submit, review, and assign according to the registered agent's role. The actor ID comes from the server's `--agent-id`, not from a tool argument. Tools do not run arbitrary shell, deployments, merges, pushes, or policy changes.
199
+
200
+ > ⚠️ MCP `clientInfo` is self-reported; binding security only holds if a trusted host launches the process with the right identity and privileges. Do not expose the stdio server as a network service without additional authz/authn.
201
+
202
+ <img src="assets/divider.svg" alt="" width="100%">
203
+
204
+ ## 🌿 Git Worktree Isolation
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` compares the contents of a worktree (committed work on the branch, uncommitted changes, and untracked files) with the `<task>` in its name. The `worktree` gate runs the same check for every active worktree at `check`/`finish`; out-of-scope code there will end up on the branch that later gets merged, so this gate closes the "isolation = safety" gap.
214
+
215
+ Worktrees live in `.pakem/worktrees/` on branches named `pakem/<task>/<agent>`. Removal refuses a dirty worktree unless `--force`; branches are not deleted automatically. The feature isolates the working tree; it does not do task assignment, verification, merge, push, or automatic conflict resolution. Per-worktree scope checks live in `worktree scope`/the `worktree` gate, and everything else remains the operator's responsibility.
216
+
217
+ <img src="assets/divider.svg" alt="" width="100%">
218
+
219
+ ## 🤖 Autonomous Runtime v1 (0.8.0)
220
+
221
+ `pakem init` installs `.pakem/POLICY.json`, the Runtime/Policy schemas, and the Core runtime modules. Local workflow state is stored in `.pakem/runtime/` and gitignored by 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
+ The state machine rejects illegal transitions. A checkpoint stores workflow metadata and a snapshot of git HEAD/status. `recover` only returns workflow metadata to the `recovering` state; it does **not** check out, reset, revert, or modify source code. Always review the git diff before continuing.
242
+
243
+ **🎚️ Policy modes**
244
+
245
+ | Mode | Behavior |
246
+ |---|---|
247
+ | `manual` | requires approval for every action other than read |
248
+ | `assisted` | allows ordinary edits, but requires approval for medium/high commands and sensitive categories |
249
+ | `guarded_autonomous` | allows actions up to `maxAutonomousRisk`, except categories that always require approval |
250
+
251
+ `deniedCategories` are rejected even with approval.
252
+
253
+ Local approvals are one-shot, expire, and are bound to the workflow, category, risk level, and target. This is **not secure human authentication**: the CLI cannot prove who ran `policy approve`. The agent host must stop the action and ask the user for confirmation through a trusted channel; an agent must not approve itself. Do not put secrets or full commands into hook targets/payloads.
254
+
255
+ **🪝 Standard hooks:** `session.start`, `task.before`, `task.after`, `verification.before`, `session.finish`, `handover`. `runtime hook` returns `allow`, `require_approval`, or `deny` and records a receipt without storing the raw payload. The runtime host must enforce this decision; Pakem does not execute commands, deploys, or agents.
256
+
257
+ <img src="assets/divider.svg" alt="" width="100%">
258
+
259
+ ## 🚨 Rule-change warnings
260
+
261
+ Gates can be bypassed if an agent quietly loosens the rules. That is why `start` snapshots `rule.*`, `verify`, `sensitive`, `exposure`, `deploy`, `handover`, and a manifest hash of `.pakem/pakem.py` plus every `.pakem/pakem_core/*.py`. At `check`, `finish`, and `audit`, later changes show up as:
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` also prints risky gaps based on the flags:
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
+ This does not block (sometimes the change was requested by the user), but it is recorded in the session and the agent is required to report it. Pakem makes loosening *visible*; it cannot stop a determined agent from cheating.
280
+
281
+ <img src="assets/divider.svg" alt="" width="100%">
282
+
283
+ ## 🧭 Checking repo state on resume
284
+
285
+ On every `start` and `step`, Pakem records the HEAD commit and the list of changed files (outside `.pakem/`). When `start` finds an interrupted session, it compares that with the current state:
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
+ So a stale `nextStep` or work that never got recorded is immediately visible. Only active in git repos.
294
+
295
+ Session files are written atomically (write to a temp file, `fsync`, then rename), so a power loss mid-write cannot leave half a JSON file. All `.pakem/*.md`/ADR/BUG-HISTORY writes use the atomic path too, and session/document mutations are locked across processes (`pakem_lock`). If a session file is nonetheless corrupt, `status`/`start`/`check`/`finish` print `[WARN] corrupt session ignored: ...`, so no more silent loss.
296
+
297
+ <img src="assets/divider.svg" alt="" width="100%">
298
+
299
+ ## 🏯 What `init` creates
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
+ **Conditional scaffolding:** `oneoff` only gets `CONTEXT.md` and `PROJECT.md`. Existing repos are detected automatically and **not rewritten**; only `.pakem/` and adapters are added.
324
+
325
+ <img src="assets/divider.svg" alt="" width="100%">
326
+
327
+ ## 📜 Configuration (`.pakem/PROJECT.md`)
328
+
329
+ The top of the file holds configuration, one `key: value` per line:
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
+ `rule.*` values: `required`, `skip`, `when-decision`, `when-needed`. Every `skip` **must** have a `reason.*`. Gates do not fail because a folder is missing, but they fail if a rule is skipped silently.
346
+
347
+ **🚩 Risk flags** (read by `pakem audit`, not gates):
348
+
349
+ | Flag | Values | Effect on audit |
350
+ |---|---|---|
351
+ | `exposure` | `private` / `public` | public → suggests LICENSE, CONTRIBUTING, SECURITY, PR/issue templates |
352
+ | `deploy` | `none` / `staging` / `production` | deploy → suggests CI, DEPLOYMENT, RUNBOOK |
353
+ | `handover` | `true` / `false` | true → suggests HANDOVER, access, known issues, tech debt |
354
+ | `sensitive` | `true` / `false` | true → suggests SECURITY, threat model, secret scan |
355
+
356
+ `start` snapshots all four flags; lowering them mid-session produces `[WARN] rules-changed`. Audit remains read-only and never creates files.
357
+
358
+ <img src="assets/divider.svg" alt="" width="100%">
359
+
360
+ ## 📝 Spec & plan (optional)
361
+
362
+ For multi-file features/changes, don't start coding right away. For a typo or a one-file edit, skip it.
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` stays `draft` until `spec --approve`; while it is a draft, `check`/`finish` fail at the `spec` gate.
378
+ - 🗒️ Every task carries `files` and `verify`; while any `[ ]` remains, `check`/`finish` fail at the `plan` gate. `plan drop` marks a task done with a reason.
379
+ - ✅ The Acceptance section of `SPEC.md` must be checked (`- [x]`) before `finish` passes the `acceptance` gate; `check` only requires approval, since the spec is approved before work starts.
380
+ - 🧾 Every `[x]` task needs valid verify evidence: `plan done` runs that task's `--verify` and records the exit code, output hash, and scope-file fingerprint in `.pakem/verify/tasks.json`. If a scope file changes after verification, the `task-verify` gate rejects until the evidence is refreshed. Exceptions must be explicit: `--no-verify --reason "..."`, and the waiver is always named on the gate line. Dropped tasks are not claimed as done, so they require no evidence.
381
+ - 🎯 **Code** changes outside the `--files` of all tasks fail the `scope` gate; non-code files (docs, config, lockfiles) are only reported. The baseline is HEAD at session `start`, so already-committed changes and deleted files remain visible, and `git diff HEAD` alone is not enough. `pakem reconcile` shows both before `finish`.
382
+ - 🌿 The `worktree` gate repeats that check for each managed worktree: branch diff + uncommitted changes + untracked files compared against the task scope in the worktree name, and tasks with no file scope are reported too.
383
+ - ⏱️ Task target: 2–5 minutes, one small change that can be verified.
384
+ - 👀 `start`/`status` show spec status and plan progress; `doctor` warns when either is still draft/pending.
385
+
386
+ <img src="assets/divider.svg" alt="" width="100%">
387
+
388
+ ## 🗝️ Sources of truth (so nothing is duplicated)
389
+
390
+ | File | Role | Don't put here |
391
+ |---|---|---|
392
+ | `PROJECT.md` | project facts + config (`verify`, `rule.*`, flags) | task history |
393
+ | `CONTEXT.md` | routing: what to read first; the protocol block is generated | feature specs |
394
+ | `SPEC.md` | why/what + acceptance for one piece of work | task list |
395
+ | `PLAN.md` | task order (how) for that work | problems/non-goals |
396
+ | session JSON | what actually happened (`steps`, `nextStep`) | intent/plans |
397
+ | `MODULE-MAP.md` | module structure | work status |
398
+ | `DECISIONS.md` + `docs/adr/` | decision index + details | bugs/work history |
399
+ | `BUG-HISTORY.md` | fixed bugs | still-open bugs |
400
+ | `HANDOVER.md` | final snapshot: access, contacts, remaining work, risks | passwords/secrets |
401
+ | `references/` | generic guidance | project-specific facts |
402
+
403
+ Rule: **don't copy content**, point to the source file. `CONTEXT.md` and the adapters use a protocol generated from one source; `pakem upgrade` syncs the blocks, `doctor` warns when they are stale.
404
+
405
+ | Command | Role |
406
+ |---|---|
407
+ | `status` | read-only summary |
408
+ | `check` | gates that can fail |
409
+ | `reconcile` | read-only report: git changes vs task scope (plan/board) vs acceptance (`--json`, `--strict`) |
410
+ | `finish` | gates + verify evidence + close the session |
411
+ | `audit` | artifact inventory, advisory |
412
+ | `doctor` | setup diagnosis (config/git/hook/adapter/session) |
413
+ | `spec` / `plan` | workflow state, not verification gates |
414
+
415
+ <img src="assets/divider.svg" alt="" width="100%">
416
+
417
+ ## 🔍 Artifact audit (`pakem audit`)
418
+
419
+ Pakem does not chase file completeness. `audit` sorts artifacts by `type`, `exposure`, `deploy`, `handover`, `sensitive`, and repo contents:
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` is **read-only**: it creates no files and changes no configuration.
441
+ - 🤖 `--json` for agents; `--strict` exits 1 when any REQUIRED item is missing.
442
+ - 🕰️ RECOMMENDED items may be deferred with an honest reason; do not create empty files.
443
+ - 🎬 `init` immediately prints an artifact plan summary.
444
+ - ⚠️ `finish` prints `[WARN] risk: ...` for gaps whose flags are active (e.g. `deploy=production but no RUNBOOK.md yet`). This is **advisory**: it does not change the exit code, but it must be reported.
445
+ - 📦 `pakem handover` creates **one** `HANDOVER.md` (status, access without passwords, contacts, remaining work, risks). Its placeholders are rejected by the gate until filled; don't split it into `ACCESS` + `KNOWN_ISSUES` + `TECH_DEBT` + `HANDOVER` that go stale fast.
446
+ - 📚 Per-failure-mode details, canonical choices (e.g. `docs/adr/` rather than `docs/decisions/`), and the list of things that must not be created automatically: `references/artifacts.md`.
447
+
448
+ <img src="assets/divider.svg" alt="" width="100%">
449
+
450
+ ## 🩺 Diagnosis and maintenance
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` exits 1 on any **FAIL** (broken config, empty verify, leftover placeholders, corrupt session); WARN is only a suggestion. `--json` for agents. It also warns about draft SPECs and PLANs with open tasks.
464
+ - 🧹 `prune` defaults to `--keep 20 --days 90`; active sessions are never deleted, corrupt sessions are left alone.
465
+ - 🏗️ `ci` detects Node (npm/pnpm/yarn), Python, Go, or Rust and then runs `pakem check`, so `verify` stays the single source of truth. `--force` overwrites an existing workflow.
466
+ - ⬆️ `upgrade` refreshes the CLI, Core modules, protocol/intelligence schemas, new flags, `.gitignore`, and adapters. Manual project-doc content (including `MODULE-MAP.md`/ADRs) is preserved; only the marked Pakem protocol blocks in `CONTEXT.md`/adapters are synced. Run `--dry-run` first and use the newest CLI from the skill install.
467
+
468
+ <img src="assets/divider.svg" alt="" width="100%">
469
+
470
+ ## 🧪 Evidence and `--strict`
471
+
472
+ `finish` stores verify evidence in the session (`verifyEvidence`): command, exit code, duration, output hash, and the hash of `.pakem/pakem.py`; when it runs, it prints:
473
+
474
+ ```
475
+ [EVIDENCE] verify: pass exit=0 hash=4355a46b19d348dc
476
+ ```
477
+
478
+ By default `finish` stays advisory: missing REQUIRED audit items show up as `[WARN] required: ...`. Add `--strict` to make the session **fail** when rules/CLI changed, `verify` is not `pass`, or a REQUIRED audit item is missing. That is what makes "finished" harder to fake, rather than just exit 0.
479
+
480
+ <img src="assets/divider.svg" alt="" width="100%">
481
+
482
+ ## 👓 Review lens
483
+
484
+ `references/reviews.md` contains a frontend lens (component/token consistency, loading/empty/error states, responsiveness, a11y) and a backend lens (server-side authorization, boundary validation, parameterized queries, secrets, PII, fail closed). Read it before `finish` when the project has a UI or `sensitive: true`; it is not a gate and does not replace human review.
485
+
486
+ <img src="assets/divider.svg" alt="" width="100%">
487
+
488
+ ## 🚪 Gates (`pakem finish` and `pakem check`)
489
+
490
+ | Gate | Fails when |
491
+ |---|---|
492
+ | session | (`finish` only) no active session or empty `--summary` |
493
+ | bug | (`finish --fixed-bug` only) no `pakem bug` entry in this session |
494
+ | rules | a `required` rule is unmet, or a `skip` has no reason |
495
+ | placeholder | leftover `[FILL`, `[ISI` (legacy), `{{...}}`, `TODO` in `.pakem/*.md` and `docs/adr/*.md` |
496
+ | spec | `.pakem/SPEC.md` exists but is not `approved` |
497
+ | plan | `.pakem/PLAN.md` exists but tasks are still `[ ]` |
498
+ | drift | a backticked path in MODULE-MAP/DECISIONS does not exist in the repo |
499
+ | verify | the `verify` command exits non-zero, or is empty without `reason.verify` |
500
+
501
+ Exit code 1 when anything fails. The verify gate runs **your project's** tests/lint/build: Pakem does not replace tests, it forces them to run. `[WARN] risk:` lines from audit do not change the 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` (add `--skip-verify` when tests are too slow for every commit). The hook is installed in the folder git actually reads, so `core.hooksPath` and worktrees are supported.
508
+ - **Agents:** adapters inject the protocol into `CLAUDE.md`, `AGENTS.md`, etc. For Claude Code you can also install a Stop hook that runs `check`; check the docs for the version you use for the latest format.
509
+
510
+ <img src="assets/divider.svg" alt="" width="100%">
511
+
512
+ ## 🧫 Tests
513
+
514
+ The full suite needs two optional dependencies (one test module uses them for Ed25519, another for JSON Schema validation):
515
+
516
+ ```bash
517
+ python3 -m pip install -r requirements-dev.txt
518
+ python3 -m unittest discover -s tests -v
519
+ ```
520
+
521
+ Without those dependencies the suite still runs and stays green; 14 tests skip with the reason shown in the output.
522
+
523
+ Skill behavior evals (not code) are checked separately:
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
+ Running the evals needs an agent command and a judge command; the contract is in `evals/README.md`.
531
+
532
+ <img src="assets/divider.svg" alt="" width="100%">
533
+
534
+ ## 🌌 Production Orchestration Foundations (1.1.0)
535
+
536
+ Pakem 1.1 adds two foundations for stronger coordination. Both are opt-in and preserve the default compatibility of previous versions.
537
+
538
+ ### 🔑 Ed25519 agent identity
539
+
540
+ Identity public keys are stored and can be shared via `.pakem/identity/registry.json` (public metadata); private keys live in the user config directory (`$XDG_CONFIG_HOME/pakem/identities/` on Linux/macOS or `%APPDATA%/Pakem/identities/` on Windows), not in the repository. Private key files are written with owner-only permissions where the OS supports it.
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` creates a new keypair and keeps the old key's public metadata as retired; old signatures are no longer accepted as the active identity. Signatures verify that the payload is unchanged and was signed by the private key matching the public registry. Delegation tokens check subject, audience, action, expiry, and revocation.
561
+
562
+ > ⚠️ **This is not transport authentication or a sandbox**: tokens remain bearer credentials and can be replayed while still valid. The host must bind the token to the caller's connection/process, restrict audience/actions, implement anti-replay, keep system time correct, and protect the registry and private keys. Changing the project path yields a different private-key namespace; provisioning keys for other hosts must go through a secure channel.
563
+
564
+ ### 🗄️ SQLite coordination backend
565
+
566
+ JSON board + JSONL remains the default so existing projects do not change. Migration only happens with an explicit action:
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 stores the board and event ledger; every mutation updates both in one transaction. The original `board.json` and `events.jsonl` files are kept as backups and are no longer updated once SQLite becomes authoritative. Online backup uses the SQLite backup API to produce a consistent snapshot.
576
+
577
+ **Backend limits:** this SQLite database remains local to the project directory and depends on correct SQLite/filesystem locking. Do not rely on it as a distributed database or put the database WAL on a network filesystem that does not guarantee locking. Multi-host coordination needs a separate authenticated backend service, which this release does not provide.
578
+
579
+ ### 📋 Conformance profile
580
+
581
+ `conformance/v1/README.md` defines implementation obligations and the limits of conformance claims. Executable tests live in `tests/test_release_110.py`. Passing tests does not prove transport authentication, process isolation, distributed consensus, or the correctness of agent work.
582
+
583
+ <img src="assets/divider.svg" alt="" width="100%">
584
+
585
+ ## 👥 Multi-Agent Coordination (v0.9.0+)
586
+
587
+ Pakem can manage a shared task board for cooperative agents: role/capability registration, dependency-aware tasks, assignment, exclusive expiring leases, heartbeat, release, handover, submission with evidence references, and independent review. State lives in `.pakem/team/`; a lock file serializes cross-process operations on the local filesystem.
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
+ A task stays in `review` until a different reviewer approves it. Dependencies become claimable only after their parent tasks are `done`. Expired claims can be reclaimed. Agent IDs/roles are cooperative metadata, not authentication; a trusted host must bind authenticated caller identity to `--agent`.
609
+
610
+ With an Ed25519 identity installed, `team register` binds its fingerprint to the board, `--sign` seals each submission and review payload, and `pakem team verify` checks the signature, the revocation state, and whether the board still matches what was signed: tamper-evident, not transport authentication. Pakem does not spawn agents, run commands, sandbox file scopes, merge branches, or provide distributed consensus. The coordination event ledger is an audit receipt, not proof that evidence was independently verified. See `.pakem/coordination/v1/README.md` for lifecycle and trust boundaries.
611
+
612
+ <img src="assets/divider.svg" alt="" width="100%">
613
+
614
+ ## 🌙 Honest limitations
615
+
616
+ > *Even the strongest protagonist has limits. Better to know them early.* (´・ω・`)
617
+
618
+ - Not a replacement for tests: gates force tests to run, they do not guarantee the tests are good.
619
+ - Not a sandbox: agents can still ignore instructions. Hooks and exit codes narrow the gap, they do not close it.
620
+ - Not semantic/vector memory: these are structured files that can be read and diffed.
621
+ - Multi-agent coordination is local: Pakem provides a shared board, leases, handover, and independent review, but does not spawn agents, run commands, merge branches, or provide distributed consensus. Working-directory isolation is available via `pakem worktree` (local git worktrees); merge/push remain the operator's responsibility.
622
+ - Pakem Protocol v1.0 provides a JSON/JSONL contract, CLI validators, and a local MCP stdio adapter (read-only by default); remote transport and cross-language SDKs are not provided.
623
+ - The event ledger is append-only along the CLI path, but it is not immutable storage: a user with filesystem access can still edit it.
624
+ - The drift gate only checks backticked paths; it is not code analysis. The dependency graph/impact adds static import analysis, but does not cover every runtime relationship.
625
+ - `audit` judges artifact presence and risk flags, not the quality of their contents. Env/CI/lockfile detection is file-pattern based, not deep analysis.
626
+ - `verifyEvidence` proves the command ran and its exit/hash, not that the tests are sufficient or correct.
627
+ - Cross-process locking depends on `flock`/`msvcrt`; behavior on NFS, read-only containers, and Windows is untested.
628
+ - `SPEC.md` and `PLAN.md` are local markers: `spec --approve` / `plan done` can be changed by an agent. Pakem makes that visible and gated, not cryptographically signed.
629
+ - Pakem provides the spec container and the rule to ask questions; it is not an automatic interviewer that walks through each spec section.
630
+
631
+ <img src="assets/divider.svg" alt="" width="100%">
632
+
633
+ ## 🌸 Roadmap
634
+
635
+ - [ ] Universal runtime lifecycle hooks (Stop/AfterTool according to host agent capabilities)
636
+ - [ ] Context retrieval that uses the graph, MODULE-MAP, symbol index, and prior work results
637
+ - [ ] Deeper impact analysis (AST/symbol-level, framework routing, path aliases, generated code) and automatic triggers from workflow hooks
638
+ - [ ] Verifiable/signable evidence ledger and change provenance
639
+ - [ ] Policy engine + guarded autonomy with approvals for risky operations
640
+ - [ ] MCP HTTP transport and reference SDKs for Python/TypeScript
641
+ - [ ] Authenticated agent identity, remote coordination adapters/database backends, and conflict-aware merge orchestration
642
+ - [ ] Deeper documentation drift and audits for API/DB/infra
643
+ - [ ] CI templates for GitLab/CircleCI besides GitHub Actions
644
+
645
+ <img src="assets/divider.svg" alt="" width="100%">
646
+
647
+ ## 📦 License and distribution
648
+
649
+ MIT, see `LICENSE`.
650
+
651
+ The structure follows the Agent Skills/skill-creator format: `SKILL.md`, `assets/templates/`, `references/`, `scripts/`, `evals/`, and `tests/`. The contents of `evals/` are run with `python3 scripts/run_evals.py` (see `evals/README.md`). Validate and package:
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
+ Packaged output: `dist/pakem.zip` (git-ignored).
659
+
660
+ <img src="assets/divider.svg" alt="" width="100%">
661
+
662
+ <div align="center">
663
+
664
+ <img src="assets/footer.svg" alt="Thank you for reading, adventurer. Agents may change; pakem stays." width="100%">
665
+
666
+ </div>