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

|
|
8
|
+

|
|
9
|
+

|
|
10
|
+

|
|
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¢er=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>
|