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.
Files changed (76) hide show
  1. package/CHANGELOG.md +271 -0
  2. package/LICENSE +21 -0
  3. package/README-ID.md +665 -0
  4. package/README.md +664 -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 +150 -0
  35. package/npm/check-version.js +26 -0
  36. package/package.json +55 -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/SKILL.md ADDED
@@ -0,0 +1,264 @@
1
+ ---
2
+ name: pakem
3
+ description: "Pakem: agent work discipline with finish gates."
4
+ license: MIT
5
+ compatibility: Python 3.10+; Linux/macOS tested, Windows best-effort
6
+ metadata:
7
+ version: "1.2.1"
8
+ ---
9
+
10
+ # Pakem
11
+
12
+ Pakem makes agent work **consistent, resumable, and provably done**, in any agent and in any session. Agents may change; pakem stays.
13
+
14
+ Pakem **does not chase file completeness**. Only artifacts that support continuity and verification are required; the rest are chosen by risk through `pakem audit`, not created to make the repo look complete.
15
+
16
+ Pakem is not a sandbox and not a replacement for tests. From 0.8.0, Pakem provides a workflow runtime, policy decisions, lifecycle hooks, checkpoint, and recovery metadata. From 0.9.0, Pakem adds a shared task board, leases, handoff, and independent review for multi-agent coordination. From 1.0.0, Pakem Protocol v1.0 is frozen as a stable contract with capability negotiation, an MCP stateless stdio adapter, and Git worktree isolation. From 1.1.0, Pakem adds Ed25519 agent identity/signed delegation and an opt-in local SQLite coordination backend. From 1.1.1, README is no longer REQUIRED for `oneoff` projects, the reviewer role requirement on `team review` is documented, and per-task `--verify` preserves shell pipes. From 1.1.2, every schema `$id` uses `urn:pakem:...` so validation does not depend on any domain. From 1.1.3, `approvals.json` has a schema (`runtime/v1/approval.schema.json`), `evals/` has a runner (`scripts/run_evals.py`), and the skill `description` is shortened so its trigger is visible in the agent index. From 1.2.0, the `scope` gate compares actual changes against task scope (PLAN.md and board), the `worktree` gate does the same for each managed worktree, the `acceptance` gate (`finish` only) rejects unchecked boxes, `pakem reconcile` reports scope and acceptance read-only (`--json` for tools), and `team submit`/`team review --sign` + `team verify` bind board actions to Ed25519 identities. The runtime does not execute commands, orchestrate model processes, or guarantee OS/process identity; the host agent/runtime must still enforce policy and mediate approval through a trusted channel.
17
+
18
+ The CLI lives in `scripts/pakem.py` (Python 3.10+, standard library). Ed25519 operations need the optional `cryptography` dependency; other features work without extra dependencies. After `init`, a copy lives in `.pakem/pakem.py` and that is what you use day to day.
19
+
20
+ Below, `pakem` means `python3 .pakem/pakem.py`. On Windows, replace `python3` with `python` or `py -3`.
21
+
22
+ ## When to use
23
+
24
+ - Starting a new project, or joining a project that already has `.pakem/`.
25
+ - Continuing multi-session work, or recovering a session interrupted after another agent stopped midway.
26
+ - Choosing project documents/structure, or when the user asks "what files need to exist".
27
+ - Multi-file work that needs an approved spec, a plan, and completion evidence that can fail.
28
+ - When the user says "pakem" or ".pakem".
29
+ - **Do not** use it for short questions or a trivial single-file edit.
30
+
31
+ ## Ed25519 identity and delegation (1.1.0)
32
+
33
+ - `pakem identity create <agent>` creates an Ed25519 keypair. The public key and revocation metadata live in `.pakem/identity/registry.json`; the private key is stored in the user config directory, not the repository.
34
+ - Never copy the private key into the source tree, commits, logs, transcripts, or shared output.
35
+ - `pakem identity sign <agent> --file payload.json` creates a signed envelope; `pakem identity verify` must use the project's trusted public registry. Use `identity rotate` to rotate keys and `identity revoke` to revoke an agent.
36
+ - Delegation tokens must be scoped by audience, action, and TTL. The host must check the signature, subject, audience, action, expiry, and revocation, and bind the token to the correct caller.
37
+ - Tokens are bearer credentials and can be replayed before they expire. The host must provide anti-replay, rate limiting, and secure token storage.
38
+ - A signature proves possession of the private key at signing time and payload integrity; it does not prove the claims are true, that the agent process is secure, or that the transport is authenticated.
39
+ - Identity operations need the optional `cryptography` package. A failure of this dependency must not disrupt other Pakem workflows.
40
+
41
+ ## Coordination storage (1.1.0)
42
+
43
+ - JSON/JSONL stays the default, backward-compatible backend.
44
+ - SQLite is used only after the operator explicitly runs `pakem team storage migrate --to sqlite`.
45
+ - Migration keeps `board.json` and `events.jsonl` as read-only backups; SQLite becomes authoritative once the backend configuration changes.
46
+ - Create a consistent snapshot with `pakem team storage backup --output <file>`.
47
+ - The SQLite backend is local-only and depends on reliable filesystem locking/WAL. Do not use it as a distributed coordination service or assume it is safe on arbitrary network filesystems.
48
+ - Do not claim multi-host consensus or automatic agent spawning; those features need a trusted server backend and a separate orchestration host.
49
+
50
+ ## Flow A - project does NOT have `.pakem/` yet
51
+
52
+ 1. **Classify** the project (see table). If unsure or the requirements are ambiguous, ask the user one short question; do not guess.
53
+ 2. Install: `python3 <lokasi-skill>/scripts/pakem.py init --type <jenis>`
54
+ - An existing repo automatically enters "follow the existing pattern" mode: no folder is created or reshaped.
55
+ - Add `--hook` to install a git pre-commit hook that runs `check`.
56
+ 3. **Fill every `[FILL: ...]`** in `.pakem/*.md` with real project facts (not guesses), and make sure `verify` in `.pakem/PROJECT.md` contains the correct test/lint/build commands. While placeholders remain, the gate refuses.
57
+ 4. For `oneoff`, README is RECOMMENDED: a `verify` that proves the output is enough. Decide the risk flags at the top of `PROJECT.md`: `exposure` (private/public), `deploy` (none/staging/production), `handover` (true/false), `sensitive` (true/false). Then run `pakem audit` to see which artifacts are worth it. **Do not** create everything recommended; do what is REQUIRED, defer RECOMMENDED with a reason, skip NOT NEEDED.
58
+ 5. Continue to Flow B.
59
+
60
+ | Type | Examples | Default rules |
61
+ |---|---|---|
62
+ | `oneoff` | make a PDF, convert data, automation script | no tests/adr/modular; `verify` = a command that proves real output |
63
+ | `app` | web app, API, bot, service | tests required, ADR when there is a decision, modular required |
64
+ | `library` | SDK, package, CLI tool | like `app`, plus a public API contract |
65
+ | `research` | compare technologies, prototype | `docs/research/` required, tests skipped |
66
+
67
+ Folders are created only when the rules demand it: `tests/` for projects with logic, `docs/adr/` for decisions with real alternatives (`pakem adr "judul"`), `docs/research/` for exploration whose results get reused. For simple scripts, do not force it.
68
+
69
+ ## Autonomous Runtime and Policy (0.8.0)
70
+
71
+ After `init`, every project gets `.pakem/POLICY.json` with the default mode `assisted`. The workflow runtime is optional and can be started with:
72
+
73
+ ```bash
74
+ pakem runtime init "<goal>"
75
+ pakem runtime status --json
76
+ pakem runtime transition ready --reason "spec dan plan disetujui"
77
+ pakem runtime transition executing --task-id T1
78
+ pakem runtime checkpoint --label "sebelum perubahan berisiko"
79
+ ```
80
+
81
+ Before running an action, the host agent can call the hook: `pakem runtime hook task.before --payload-file action.json --json`. Continue only when the decision is `allow`; `require_approval` must request user consent from a trusted host channel; `deny` stops the action. The agent must not call `policy approve` to approve its own actions.
82
+
83
+ Policy modes: `manual` asks for approval on every action except reads; `assisted` allows ordinary edits, but asks for approval on medium/high commands and sensitive categories; `guarded_autonomous` allows commands/actions up to `maxAutonomousRisk`, except sensitive categories, which always ask for approval. `deniedCategories` categories are still denied.
84
+
85
+ `pakem runtime recover` only restores workflow metadata to `recovering`. It does not restore source code or change the Git working tree. The agent must inspect `git status`/diff before continuing. The runtime provides decisions and receipts; it does not execute commands, deploy, or run agents.
86
+
87
+ ## Pakem Protocol v1.0 Stable Contract (1.0.0)
88
+
89
+ The session Protocol v1.0 event envelope and compatibility rules are frozen. Additional features are negotiated as capabilities, not by silently changing the shape of v1 events.
90
+
91
+ ```bash
92
+ python3 .pakem/pakem.py protocol info
93
+ python3 .pakem/pakem.py protocol negotiate --peer-version 1.0 \
94
+ --capability events.v1 --capability context.snapshot.v1 --capability coordination.v1 --json
95
+ ```
96
+
97
+ The Pakem protocol version is independent of the MCP, CLI, model, and implementation-language versions. A capability signals contract support, not permission to run side effects. Actor name, local agent ID, and MCP `clientInfo` are attribution metadata, not proof of authentication.
98
+
99
+ ## MCP Adapter (modern stateless stdio)
100
+
101
+ Pakem provides an MCP stdio adapter without external dependencies. The implementation targets MCP `2026-07-28`: every request carries `protocolVersion` and `clientCapabilities` in `params._meta`, and the server provides `server/discover`, `tools/list`, and `tools/call`.
102
+
103
+ ```bash
104
+ # Read-only adalah default
105
+ python3 .pakem/pakem.py mcp serve
106
+
107
+ # Mutasi task board hanya untuk identitas tetap yang diberikan host tepercaya
108
+ python3 .pakem/pakem.py mcp serve --agent-id backend --allow-write
109
+ ```
110
+
111
+ Read-only tools cover context, Protocol info, team status/events, dependency graph, impact analysis, and policy check. Team mutation tools are exposed only when `--allow-write` and `--agent-id` are used; claim/heartbeat/submit use the server-bound identity, not an ID passed as a tool argument. Reviewers and leads get the tools their board role allows. MCP `clientInfo` is not authenticated by MCP; the host must bind the process to the right agent. Do not expose the stdio adapter as a network service without additional authentication and authorization.
112
+
113
+ The adapter does not open arbitrary shell execution, raw file writes, deployment, merge, push, or policy edits. stdout carries JSON-RPC only; diagnostics go to stderr.
114
+
115
+ ## Git Worktree Isolation
116
+
117
+ To isolate the working directory per task/agent, Pakem can create a Git worktree in `.pakem/worktrees/` with the branch `pakem/<task>/<agent>`.
118
+
119
+ ```bash
120
+ python3 .pakem/pakem.py worktree create T1 --agent backend --base main
121
+ python3 .pakem/pakem.py worktree list --json
122
+ python3 .pakem/pakem.py worktree scope T1--backend --strict
123
+ python3 .pakem/pakem.py worktree remove .pakem/worktrees/T1--backend
124
+ python3 .pakem/pakem.py worktree cleanup [T1] [--dry-run]
125
+ ```
126
+
127
+ `worktree scope` compares the worktree content (commits on the branch + uncommitted changes + untracked files) against the task scope recorded in its name. `--strict` exits 1 if there is code outside the scope. The `worktree` gate runs the same check for all active worktrees at `check`/`finish`, so scope creep inside isolation does not vanish when the branch is merged.
128
+
129
+ `worktree cleanup` removes safe worktrees: clean (no uncommitted changes) and with commits already part of HEAD. A worktree with unmerged commits or uncommitted files is left alone and reported — that is unfinished work, not garbage. `plan done <id>` runs this cleanup for that task and prints `[WT ] ... deleted` or `[WARN] worktree ... left as is: <reason>`.
130
+
131
+ Removal refuses a dirty worktree unless `--force` is explicit. Branches are not deleted automatically (except by `cleanup`, which uses `git branch -D` only after the worktree is removed). Worktree isolation does not automatically assign tasks, run tests, merge, push, or prove the changes are safe. Merge/conflict orchestration remains the responsibility of the review workflow and the Git operator.
132
+
133
+ ## Flow B - project ALREADY has `.pakem/` (every session)
134
+
135
+ 1. Read `.pakem/CONTEXT.md`, then only the files its routing points to.
136
+ 2. `pakem start "<goal>"`. If a session was interrupted, this command shows it along with a **repo condition check** (new commits or changed files since the last note). Read the `CHECK` section, verify briefly, then **continue from `nextStep`**; do not start from zero. If the note no longer matches the repo, record the correction through `step`.
137
+ 3. Work step by step. At every reasonable stopping point:
138
+ `pakem step "<yang baru selesai>" --next "<langkah berikutnya>"`
139
+ 4. While working, keep the documents alive:
140
+ - module structure changes → update `MODULE-MAP.md`
141
+ - new tests go into the existing test folder; do not create both `test/` and `tests/`
142
+ - choosing a library/pattern/architecture → `pakem adr "<judul>"` then fill in the ADR
143
+ - fixing a bug → check `BUG-HISTORY.md` first, then `pakem bug "<judul>" --symptom ... --cause ... --fix ... --prevent ...` (empty fields become placeholders and are rejected by the gate)
144
+ 5. When you need to choose documents/structure (before a release, a handover, or when the user asks "what files need to exist"): `pakem audit`. Do what is **REQUIRED**; **RECOMMENDED** may be deferred with a reason; **NOT NEEDED** must not be created.
145
+ 6. Finish: `pakem finish --summary "<apa yang selesai + bagaimana dibuktikan>"`. Add `--fixed-bug` if this work fixes a bug; the bug gate requires a `pakem bug` entry from this session. `finish` prints `[EVIDENCE] verify: ...` (status/exit/hash) and `[WARN] required:` for audit gaps. Add `--strict` if you want this to fail the session (rules/CLI changed, verify not a pass, or a REQUIRED gap). `finish` also prints `[WARN] risk:` for gaps matching the flags (`deploy`/`sensitive`/`exposure`/`handover`); report them, but they do not block. Before that, `pakem reconcile` shows which files changed outside the plan scope and which acceptance criteria are still unchecked.
146
+ 7. **Do not say "done" to the user before `finish` exits 0.** If it fails, honestly report which gate failed and fix it.
147
+ 8. **Report every `[WARN]` line to the user** as-is (see "Rule change warnings").
148
+
149
+ Other commands: `status` (summary), `check [--skip-verify]` (gates without closing the session), `reconcile [--json] [--strict]` (changes vs plan scope vs acceptance, read-only), `audit [--json] [--strict]` (sort artifacts, read-only), `spec`/`plan` (spec + small tasks), `handover` (create one `HANDOVER.md`), `doctor` (setup diagnosis), `prune` (prune old sessions), `ci` (create a CI workflow), `upgrade` (update CLI/flags/adapters without touching documents), `adapt` (regenerate adapters), `hook install`, `team` (multi-agent coordination).
150
+
151
+ ## Spec & plan (non-trivial work)
152
+
153
+ For multi-file features/changes, do not start coding immediately. This is optional: for a typo/single-file edit, skip it.
154
+
155
+ 1. **Spec**: `pakem spec "<title>"` creates `.pakem/SPEC.md` (problem, non-goals, acceptance, approach). Fill every `[FILL: ...]`, then `pakem spec --approve`. While the status is still `draft`, `check`/`finish` fail at the `spec` gate.
156
+ 2. **Plan**: split the work into 2–5 minute tasks:
157
+ `pakem plan add "tulis parser" --files "src/parser.ts,tests/parser.test.ts" --verify "npm test -- parser"`
158
+ ```text
159
+ - [ ] T1 - tulis parser | files: src/parser.ts,tests/parser.test.ts | verify: npm test -- parser
160
+ ```
161
+ 3. **Work the task**, then `pakem plan done T1` — that command runs the task's `--verify` and stores evidence (exit code, output hash, scope file fingerprints). If verify fails, the task stays open. For exceptions: `pakem plan done T1 --no-verify --reason "..."` (recorded as a waiver, visible at the gate). If a task turns out to be irrelevant: `pakem plan drop T1 --reason "..."`.
162
+ 4. `pakem plan list` / `pakem status` show progress. `finish` fails at the `plan` gate while any `[ ]` task remains. Tick `- [ ]` → `- [x]` in the `SPEC.md` Acceptance section only when the criterion is actually proven; `finish` fails at the `acceptance` gate while any box is unchecked (`check` does not demand it, because approval happens before work starts).
163
+ 5. One task = one small verifiable change. Do not put 10 files in one task.
164
+ 6. Per-task `--verify` is a record, not an execution: only `verify` in `PROJECT.md` is actually run by `check`/`finish`. Write the command as-is; shell pipes are preserved.
165
+
166
+ ## Source of truth
167
+
168
+ Do not duplicate content:
169
+ - `PROJECT.md` = project facts/config; `CONTEXT.md` = routing; `SPEC.md` = why/what + acceptance; `PLAN.md` = task order; session = what actually happened.
170
+ - `references/` = generic guidance, not project facts.
171
+ - The protocol in `CONTEXT.md` and the adapters are generated from one source; do not edit by hand. `pakem upgrade` syncs them, `doctor` warns about stale blocks.
172
+ - `DECISIONS.md` is an index; the details live in `docs/adr/`.
173
+ - `BUG-HISTORY.md` for bugs already fixed; still-open risks go into `HANDOVER.md`.
174
+
175
+ ## Project artifacts
176
+
177
+ `pakem audit` is read-only and sorts artifacts by `type`, `exposure`, `deploy`, `handover`, `sensitive`, and repo content:
178
+
179
+ | Verdict | Meaning |
180
+ |---|---|
181
+ | **REQUIRED** | without it the next session guesses, or "done" cannot be proven |
182
+ | **RECOMMENDED** | the risk is real, but it may be deferred with an honest reason |
183
+ | **NOT NEEDED** | do not create it just for completeness |
184
+
185
+ Do the REQUIRED ones first. For RECOMMENDED ones, defer while recording the reason; do not create empty files. Create conditional artifacts when their trigger appears (first deploy, public release, first incident, first handover, first personal data). `init` prints the artifact plan; `finish` prints `[WARN] risk:` for gaps whose flags are active. At handover, create **one** `HANDOVER.md` via `pakem handover` (status, access, contacts, remaining work, risks) — do not split it into five files that go stale fast. Per-failure-mode detail and canonical choices: `references/artifacts.md`.
186
+
187
+ ## Universal protocol and machine interface
188
+
189
+ Pakem Protocol v1.0 is the tool/model-independent contract in `.pakem/protocol/v1/`. At the start of a session, read `CONTEXT.md`, then `pakem context --json` before choosing the next step. Do not assume all agents use the same adapter format; use the JSON contract for integration.
190
+
191
+ - `pakem context --json` — read the project/session/spec/plan snapshot and the recommended next step before deciding on an action.
192
+ - `pakem graph --json` — map local imports/dependencies before cross-module changes or a refactor. Aliases `paths`/`baseUrl` from `tsconfig.json`/`jsconfig.json` (including `extends` and JSONC comments) are read as well; imports that fail to resolve are recorded in `unresolved_imports` with a reason (`relative`/`alias`/`baseUrl`) instead of being dropped, and dependency cycles are reported in `circular_dependencies`.
193
+ - `pakem impact --files FILE... --json` — analyze direct/transitive dependents, possibly affected tests, and risk signals before choosing verification scope. Alternative: `--base REF` or `--staged`. The `graph_health` block states whether the graph used is complete; `complete: false` means there are unresolved imports and dependents may be missed.
194
+ - `pakem events --json` — read the event ledger; use `--session ID` to limit to one session.
195
+ - `pakem events --verify [--json] [--session ID] [--expect-head HEX]` — check the hash chain: a modified event, an event missing in the middle, or a chain rewritten after sealing will fail.
196
+ - `pakem handover [--force] [--stamp] [--check]` — create or update `HANDOVER.md`. The document carries the stamp `<!-- pakem:handover head=<sha> at=<iso> -->`; `--check` (exit 1) and the `handover` gate reject a stamp that does not match HEAD, because a stale handover is more dangerous than none. At `check` this mismatch is only `WARN` — an actively committing repo will always be one commit past the stamp, and a gate that keeps firing gets ignored; at `finish` it becomes `FAIL`. After changing the content, run `--stamp`.
197
+ - `pakem integrity [--json] [--re-pin --reason "..."]` — compare the hash of `pakem.py` + every `pakem_core/*.py` against what was pinned at `start`. Exit 1 if anything was changed, removed, or added. Re-pinning requires a reason and is recorded as an `integrity.repinned` event. `check` reports it as `[WARN] rules-changed`, `finish --strict` fails on it.
198
+ - `pakem report [--json] [--session ID] [--limit N]` — roll-up: sessions (wall-clock duration, steps, events, status), tasks from PLAN.md with verify evidence status, and ledger status. Exit 1 if the ledger chain is broken.
199
+ - `pakem events --sign --identity <id> [--key PATH] [--session ID]` — seal the ledger with Ed25519. The signature binds the chain hash at seal time, so rewriting the whole chain is still caught. `--key` (or the `PAKEM_SEAL_KEY` env) uses a private key outside the host config directory — 32 raw bytes or PEM PKCS8 — so CI can seal with a mounted secret without ever putting the key in the repo. Verification only needs the public key from the registry: `pakem identity import <id> --public-key <base64>` registers it on a host that does not hold the key.
200
+ - `pakem protocol info` — see the version and the list of supported events.
201
+ - `pakem protocol validate-event FILE` — validate a single JSON event against the v1.0 envelope.
202
+ - `pakem protocol validate-session FILE` — validate session structure, while still accepting old sessions without `schemaVersion`.
203
+
204
+ Event lifecycle is recorded automatically to `.pakem/events/*.jsonl`. Events are a trail of activity, not proof of quality; check `verifyEvidence` and the gate results before declaring done. Since 1.2.0 every event carries the hash chain `integrity: {prev, hash}`, and `events --sign` adds an Ed25519 seal over the chain head. The chain detects edits and deletions in the middle; the seal detects rewriting the whole chain. What neither can detect: truncation of the last event — for that, record `head=<hash>` from the `ledger` gate outside the repo and compare it with `--expect-head`.
205
+
206
+ `pakem report` is the only summary you may quote as work numbers: the reported duration is session wall-clock time (not agent compute time), and `totals.unproven_done` counts `[x]` tasks that have no valid verify evidence. If the numbers look bad, that is what the ledger says.
207
+
208
+ Dependency graph and impact analysis are static read-only heuristics; `graph_health.unresolved_imports > 0` means the result is definitely incomplete, not merely "maybe". Use the results to prioritize inspection/tests, not as proof that undetected areas are safe or unaffected. Still run the project's real verify and review the changes.
209
+
210
+ ## Diagnosis & maintenance
211
+
212
+ - `pakem identity create <id> [--key-out PATH]` — the private key defaults to the user config (`~/.config/pakem/identities/<hash-proyek>/`), not the repo; `--key-out` puts it at an explicit path such as a CI secret directory.
213
+ - `pakem doctor [--verify] [--json]` — check config, placeholders, `.pakem/pakem.py`, Pakem Core, git, hooks, adapters, corrupt sessions, and REQUIRED gaps. Exit 1 on any FAIL; WARN does not block. When run from the skill-install CLI, `doctor` also compares the project's version and `pakem_core/*` hashes with the skill — a hand-modified Core shows up as WARN instead of staying silent.
214
+ - `pakem prune [--keep N] [--days D] [--yes]` — dry-run by default. Active sessions are never deleted; corrupt sessions are not touched.
215
+ - `pakem ci` — create `.github/workflows/ci.yml`: `pakem check` (including `verify`), `doctor`, `audit --strict`, and `events --verify`, with setup steps matching the detected stack. `doctor` catches a broken install; `audit --strict` catches REQUIRED gaps; `events --verify` catches an edited ledger.
216
+ - Upgrade from the project root using the latest CLI in the skill install: `python3 <lokasi-skill>/scripts/pakem.py upgrade --dry-run`, then repeat without `--dry-run`. **Do not use the 0.6.x `.pakem/pakem.py` CLI to start the upgrade**, because the old version does not know how to install Core modules and Intelligence schemas. Upgrade syncs the CLI, Core, flags, `.gitignore`, schemas, and adapters without overwriting the manual content of project documents; only marked Pakem protocol blocks are synced.
217
+
218
+ ## Gates run by `finish`
219
+
220
+ | Gate | Fails when |
221
+ |---|---|
222
+ | session | no active session, or `--summary` is empty/too short |
223
+ | bug | (only with `--fixed-bug`) there is no `pakem bug` entry in this session yet |
224
+ | rules | `required` is not met (e.g. no test file yet) or `skip` without `reason.*` |
225
+ | placeholder | `[FILL`, `[ISI` (legacy), `{{...}}`, or `TODO` still in `.pakem/*.md`, `docs/adr/*.md`, `HANDOVER.md`, and `docs/HANDOVER.md` |
226
+ | spec | `.pakem/SPEC.md` exists but `Status` is not `approved` |
227
+ | acceptance | (only at `finish`) `- [ ]` still in the `SPEC.md` Acceptance section |
228
+ | plan | `.pakem/PLAN.md` exists but has `[ ]` tasks (or no tasks yet) |
229
+ | scope | **code files** changed outside the `--files` scope of all tasks, in the plan and the board (non-code files such as documentation/config are only reported, not failed). The anchor is HEAD at session `start`: committed changes and deleted files are checked too |
230
+ | task-verify | an `[x]` task has no verify evidence, its verify failed, or files in its scope changed after verify (stale evidence). An explicit waiver (`--no-verify --reason`) passes but is always named on the gate line; a dropped task is not claimed done, so it does not demand evidence |
231
+ | worktree | a worktree in `.pakem/worktrees/` has code changes outside its task scope, or the task has not declared a file scope |
232
+ | drift | a backticked path in MODULE-MAP/DECISIONS does not exist in the repo (add a `pakem:ignore` comment on the line that is intentionally hypothetical) |
233
+ | handover | `HANDOVER.md` exists but its HEAD stamp does not match the current HEAD (the content can mislead the receiver), or `handover=true` without the file. At `check` this is `WARN`, at `finish` it becomes `FAIL`. After updating the content: `pakem handover --stamp` |
234
+ | ledger | the event ledger hash chain is broken: content changed, an event missing in the middle, or the chain rewritten after sealing. This gate prints `head=...` as an anchor you can record outside the repo |
235
+ | verify | the `verify` command in PROJECT.md exits non-zero, or is empty without `reason.verify` |
236
+
237
+ ## Rule change warnings
238
+
239
+ `start` stores a snapshot of `rule.*`, `verify`, `sensitive`, `exposure`, `deploy`, `handover`, and a manifest hash of `.pakem/pakem.py` plus every `.pakem/pakem_core/*.py`. If any of them changes during `check`/`finish`/`audit`, the line `[WARN] rules-changed: ...` appears (e.g. `rule.tests relaxed: required -> skip`, `verify changed`, `exposure downgraded: public -> private`, `deploy downgraded: production -> none`, `.pakem/pakem.py modified`). This **does not block**, but it is recorded in the session and you must report it to the user. If the change was requested by the user, say so; if not, revert it.
240
+
241
+ `finish` also emits `[WARN] required: ...` for REQUIRED audit gaps (advisory; `--strict` fails it), `[WARN] risk: ...` for gaps whose flags are active, and `[EVIDENCE] verify: ...` which records the status/exit/hash of the evidence. All of them must be reported; do not claim done just because of exit 0 without reading the evidence.
242
+
243
+ ## Prohibitions
244
+
245
+ - Do not edit `scripts/pakem.py`, `.pakem/pakem.py`, or weaken `rule.*`/`verify` just to make `finish` pass. Fix the root cause. Such changes are detected and reported.
246
+ - Bypass a legitimate rule only with an honest and specific `skip` + `reason.*` in `PROJECT.md`. Reasons like "not needed" are not enough.
247
+ - Do not guess ambiguous requirements. Ask the user, or record the assumption through `step` so it is visible and correctable.
248
+ - Do not create empty files/documents to make the structure look complete. If it is not needed yet, do not create it; record the reason.
249
+ - Do not lower `sensitive`, `exposure`, `deploy`, or `handover` while a session is running just to make the audit/gates looser. That is detected and reported.
250
+ - Do not reshape an old repo structure unless asked. Follow the existing pattern.
251
+ - Do not put secrets in code or in `.pakem/`.
252
+
253
+ ## References
254
+
255
+ For modularization details, when to write an ADR, the BUG-HISTORY format, the security checklist (`sensitive: true` projects), and the definition of done per project type, read `references/conventions.md` only when needed. For choosing project artifacts/documents proportionally, read `references/artifacts.md` when `pakem audit` shows gaps or at handover. For the frontend review lens (consistency, state, a11y) and the backend review lens (authorization, validation, secrets), read `references/reviews.md` before `finish` if the project has a UI or `sensitive: true`.
256
+
257
+ To run this skill's own behavioral evals: `python3 scripts/run_evals.py --validate`, then `--agent-cmd "<perintah agent>" --judge-cmd "<perintah penilai>"`. The agent and judge contracts are in `evals/README.md`.
258
+
259
+
260
+ ## Multi-agent coordination (v0.9.0)
261
+
262
+ Use `pakem team status --json` to read the coordination board when the project uses several agents. Register each agent with `pakem team register ID --role worker|reviewer|lead|coordinator`; capabilities can be added with `--capability`. Create small tasks through `pakem team add ID --title ...`, include `--depends-on`, `--files`, `--risk`, and the required capabilities. The lead/coordinator does `team assign`; workers do `team claim` and `team heartbeat` while working. Release a claim with `team release`, or hand it over explicitly with `team handoff`.
263
+
264
+ Results do not become `done` immediately: the worker must `team submit` with a summary and evidence reference, then a different reviewer must run `team review --decision approve`. `team review` requires two things: a registered reviewer role (`--role reviewer`, `lead`, or `coordinator`) **and** an identity different from the implementer. Register reviewers from the start (`pakem team register qa --role reviewer`); without that the task stays stuck in `review` state forever. `rework` returns the task to open. Dependencies are ready only when all parents are done. Leases prevent concurrent claims on a shared local filesystem; a lease is not a distributed lock for network filesystems or multi-host servers. ID/role is not authentication: the host runtime must ensure the caller cannot forge `--agent`. If an agent has an identity (`pakem identity create <id>`), `team register` binds its fingerprint to the board; `team submit --sign` and `team review --sign` sign the action payload, and `pakem team verify` checks the signature, identity revocation, and whether the board content still matches what was signed. This makes the board tamper-evident, not a replacement for transport authentication. The coordination board/events are not a replacement for project `verify`, security review, or the final `pakem finish`. Do not store secrets in task title, description, notes, summary, or evidence.
@@ -0,0 +1,17 @@
1
+ # Pakem Git Worktree Adapter v1
2
+
3
+ Pakem provides explicit, local Git worktree isolation for multi-agent tasks.
4
+ It creates branches named `pakem/<task-id>/<agent-id>` under
5
+ `.pakem/worktrees/<task-id>--<agent-id>`.
6
+
7
+ ```bash
8
+ pakem worktree create T1 --agent backend --base main
9
+ pakem worktree list --json
10
+ pakem worktree remove .pakem/worktrees/T1--backend
11
+ ```
12
+
13
+ Only worktrees under `.pakem/worktrees/` can be removed by this adapter.
14
+ Removal refuses dirty worktrees unless `--force` is explicitly provided.
15
+ Force removal can discard uncommitted work. Branches are never deleted
16
+ implicitly. Creating worktrees does not assign a Pakem task, run tests, merge,
17
+ push, or prove the changes correct.
@@ -0,0 +1,26 @@
1
+ # Ed25519 Identity Adapter v1
2
+
3
+ Create and manage public identities:
4
+
5
+ ```bash
6
+ pakem identity create backend
7
+ pakem identity list --json
8
+ pakem identity rotate backend --reason "scheduled key rotation"
9
+ pakem identity revoke backend --reason "agent retired"
10
+ ```
11
+
12
+ Sign a JSON payload and verify it against the project registry:
13
+
14
+ ```bash
15
+ pakem identity sign backend --file receipt.json --output receipt.signed.json
16
+ pakem identity verify receipt.signed.json
17
+ ```
18
+
19
+ Issue a short-lived action-scoped delegation token:
20
+
21
+ ```bash
22
+ pakem identity issue backend --audience pakem-host://worker-01 --action team.claim --action team.submit --ttl-seconds 900
23
+ pakem identity verify delegation.json --audience pakem-host://worker-01 --action team.claim
24
+ ```
25
+
26
+ Private keys are not copied into `.pakem/` and are not included in ZIP release artifacts. Install `cryptography` only if Ed25519 identity operations are needed.
@@ -0,0 +1,56 @@
1
+ # Pakem MCP Adapter v1
2
+
3
+ Pakem 1.0.0 ships a dependency-free MCP server over stdio, targeting the modern
4
+ stateless MCP specification `2026-07-28`.
5
+
6
+ ## Start
7
+
8
+ Read-only (default):
9
+
10
+ ```bash
11
+ python3 .pakem/pakem.py mcp serve
12
+ ```
13
+
14
+ Bound multi-agent worker (host must launch this process for the authenticated
15
+ agent identity):
16
+
17
+ ```bash
18
+ python3 .pakem/pakem.py mcp serve --agent-id backend --allow-write
19
+ ```
20
+
21
+ The modern MCP client must put these fields inside `params._meta` on **every
22
+ request**:
23
+
24
+ - `io.modelcontextprotocol/protocolVersion`: `2026-07-28`
25
+ - `io.modelcontextprotocol/clientCapabilities`: object
26
+ - `io.modelcontextprotocol/clientInfo`: recommended object
27
+
28
+ The server implements `server/discover`, `tools/list`, and `tools/call`.
29
+ Messages are newline-delimited JSON-RPC 2.0 on stdin/stdout. Stdout is reserved
30
+ for protocol messages; diagnostics go to stderr.
31
+
32
+ ## Tools
33
+
34
+ Read-only tools: `pakem.context`, `pakem.protocol.info`, `pakem.team.status`,
35
+ `pakem.team.events`, `pakem.graph`, `pakem.impact`, and `pakem.policy.check`.
36
+
37
+ With both `--agent-id` and `--allow-write`: `pakem.session.start`,
38
+ `pakem.session.step`, `pakem.session.finish`, `pakem.team.claim`,
39
+ `pakem.team.heartbeat`, `pakem.team.submit`, `pakem.team.review`, and
40
+ `pakem.team.assign`. The session tools call the project's own CLI (`start`/`step`/`finish`), so
41
+ they record events, run task verify, and return gate output — a failed `finish` is a normal result
42
+ (`ok: false`, `exit: 1`, gate lines), not a protocol error. Mutation tools bind the acting agent to the server's fixed
43
+ `--agent-id`; callers cannot pass an alternate agent ID as a tool argument.
44
+
45
+ ## Trust boundary
46
+
47
+ MCP `clientInfo` is self-reported and is not authentication. `--agent-id` is
48
+ also only a process configuration value. It is trustworthy only when a trusted
49
+ host/supervisor launches the server with the correct identity and protects its
50
+ process environment and project access. Do not expose this stdio server as a
51
+ network service without a separate authenticated transport and authorization
52
+ layer.
53
+
54
+ The adapter does not expose arbitrary shell execution, deployment, raw file
55
+ writes, merge, push, or policy modification. Policy decisions are advisory
56
+ records; the host still enforces permissions and human approvals.
@@ -0,0 +1,5 @@
1
+ # SQLite Coordination Adapter v1
2
+
3
+ Use `pakem team storage info` to inspect the current backend. Migrate explicitly with `pakem team storage migrate --to sqlite`.
4
+
5
+ The migration is one-way in this release. JSON board/event files are retained unchanged for manual backup or inspection; once `storage.json` selects SQLite, subsequent team operations use SQLite as the authoritative source. Back up `.pakem/team/` before migration. SQLite coordination is local-only and is not a multi-host lock service.