pakem-cli 0.0.0-stage → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +280 -0
  2. package/LICENSE +21 -0
  3. package/README-ID.md +666 -0
  4. package/README.md +665 -2
  5. package/SKILL.md +264 -0
  6. package/adapters/git-worktree/v1/README.md +17 -0
  7. package/adapters/identity/v1/README.md +26 -0
  8. package/adapters/mcp/v1/README.md +56 -0
  9. package/adapters/storage-sqlite/v1/README.md +5 -0
  10. package/assets/banner.svg +275 -0
  11. package/assets/divider.svg +82 -0
  12. package/assets/footer.svg +174 -0
  13. package/assets/templates/BUG-HISTORY.md +18 -0
  14. package/assets/templates/CONTEXT.md +26 -0
  15. package/assets/templates/DECISIONS.md +8 -0
  16. package/assets/templates/MODULE-MAP.md +14 -0
  17. package/assets/templates/POLICY.json +15 -0
  18. package/assets/templates/PROJECT.md +42 -0
  19. package/conformance/v1/README.md +15 -0
  20. package/coordination/v1/README.md +14 -0
  21. package/coordination/v1/board.schema.json +59 -0
  22. package/coordination/v1/event.schema.json +26 -0
  23. package/coordination/v1/status.schema.json +49 -0
  24. package/evals/README.md +63 -0
  25. package/evals/evals.json +276 -0
  26. package/identity/v1/README.md +14 -0
  27. package/identity/v1/agent-identity.schema.json +95 -0
  28. package/identity/v1/identity-registry.schema.json +29 -0
  29. package/identity/v1/signed-payload.schema.json +42 -0
  30. package/intelligence/v1/README.md +19 -0
  31. package/intelligence/v1/dependency-graph.schema.json +82 -0
  32. package/intelligence/v1/impact-analysis.schema.json +51 -0
  33. package/intelligence/v1/reconciliation.schema.json +156 -0
  34. package/npm/bin/pakem.js +272 -0
  35. package/npm/check-version.js +26 -0
  36. package/package.json +58 -4
  37. package/policy/v1/README.md +15 -0
  38. package/policy/v1/policy.schema.json +20 -0
  39. package/protocol/v1/README.md +68 -0
  40. package/protocol/v1/capabilities.schema.json +17 -0
  41. package/protocol/v1/event.schema.json +114 -0
  42. package/protocol/v1/session.schema.json +51 -0
  43. package/references/artifacts.md +96 -0
  44. package/references/conventions.md +83 -0
  45. package/references/reviews.md +44 -0
  46. package/runtime/v1/README.md +21 -0
  47. package/runtime/v1/approval.schema.json +100 -0
  48. package/runtime/v1/checkpoint.schema.json +17 -0
  49. package/runtime/v1/hook-decision.schema.json +34 -0
  50. package/runtime/v1/hook-payload.schema.json +12 -0
  51. package/runtime/v1/task-evidence.schema.json +38 -0
  52. package/runtime/v1/work-report.schema.json +123 -0
  53. package/runtime/v1/workflow.schema.json +21 -0
  54. package/scripts/__pycache__/pakem.cpython-312.pyc +0 -0
  55. package/scripts/pakem.py +4911 -0
  56. package/scripts/pakem_core/__init__.py +3 -0
  57. package/scripts/pakem_core/__pycache__/__init__.cpython-312.pyc +0 -0
  58. package/scripts/pakem_core/__pycache__/coordination.cpython-312.pyc +0 -0
  59. package/scripts/pakem_core/__pycache__/git_worktree.cpython-312.pyc +0 -0
  60. package/scripts/pakem_core/__pycache__/identity.cpython-312.pyc +0 -0
  61. package/scripts/pakem_core/__pycache__/intelligence.cpython-312.pyc +0 -0
  62. package/scripts/pakem_core/__pycache__/mcp_server.cpython-312.pyc +0 -0
  63. package/scripts/pakem_core/__pycache__/protocol.cpython-312.pyc +0 -0
  64. package/scripts/pakem_core/__pycache__/reconcile.cpython-312.pyc +0 -0
  65. package/scripts/pakem_core/__pycache__/runtime.cpython-312.pyc +0 -0
  66. package/scripts/pakem_core/coordination.py +977 -0
  67. package/scripts/pakem_core/git_worktree.py +265 -0
  68. package/scripts/pakem_core/identity.py +494 -0
  69. package/scripts/pakem_core/intelligence.py +684 -0
  70. package/scripts/pakem_core/mcp_server.py +308 -0
  71. package/scripts/pakem_core/protocol.py +61 -0
  72. package/scripts/pakem_core/reconcile.py +119 -0
  73. package/scripts/pakem_core/runtime.py +457 -0
  74. package/scripts/run_evals.py +289 -0
  75. package/storage/v1/README.md +14 -0
  76. package/storage/v1/team-storage.schema.json +27 -0
@@ -0,0 +1,272 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+
4
+ /**
5
+ * `npx pakem-cli` installs the Pakem skill; every other argument is delegated
6
+ * to the Python CLI that ships inside this package. Pakem stays Python; npm is
7
+ * only the delivery mechanism.
8
+ *
9
+ * With a terminal it shows an interactive picker (like other skill installers).
10
+ * Without a TTY, or with explicit flags, it installs non-interactively so agents
11
+ * and CI can call it safely.
12
+ */
13
+ const fs = require("fs");
14
+ const os = require("os");
15
+ const path = require("path");
16
+ const { spawnSync } = require("child_process");
17
+
18
+ const ROOT = path.resolve(__dirname, "..", "..");
19
+ const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
20
+ const PY = process.env.PAKEM_PYTHON || (process.platform === "win32" ? "python" : "python3");
21
+ const SKIP = new Set(["npm", "tests", "node_modules", ".git", ".github", "dist",
22
+ "__pycache__", ".venv", "venv"]);
23
+ const SKIP_FILES = new Set([".gitignore", "requirements-dev.txt", "package.json", "package-lock.json"]);
24
+ const HOME = os.homedir();
25
+ const INTERACTIVE = Boolean(process.stdin.isTTY && process.stdout.isTTY);
26
+
27
+ function help() {
28
+ console.log(`Pakem ${PKG.version}
29
+
30
+ Usage:
31
+ npx pakem-cli install the skill (interactive in a terminal)
32
+ npx pakem-cli install [options] same, with options
33
+ npx pakem-cli <command> [args...] run the Pakem CLI (init, check, finish, ...)
34
+
35
+ Install options:
36
+ --dir <path> install into a specific directory
37
+ --project install into ./.claude/skills/pakem
38
+ --force replace an existing installation
39
+ --dry-run show what would be copied
40
+ -y, --yes never prompt (defaults to ~/.claude/skills/pakem)
41
+
42
+ Examples:
43
+ npx pakem-cli
44
+ npx pakem-cli install --dir ~/.agents/skills/pakem
45
+ npx pakem-cli init --type app`);
46
+ }
47
+
48
+ function fail(message) {
49
+ console.error(`pakem: ${message}`);
50
+ process.exit(1);
51
+ }
52
+
53
+ function parseInstallArgs(args) {
54
+ const out = {
55
+ dir: null,
56
+ project: false,
57
+ force: false,
58
+ dryRun: false,
59
+ yes: false,
60
+ interactive: false,
61
+ };
62
+ for (let i = 0; i < args.length; i++) {
63
+ const arg = args[i];
64
+ if (arg === "--dir") {
65
+ if (!args[i + 1]) fail("--dir needs a path");
66
+ out.dir = args[++i];
67
+ } else if (arg === "--project") {
68
+ out.project = true;
69
+ } else if (arg === "--force") {
70
+ out.force = true;
71
+ } else if (arg === "--dry-run") {
72
+ out.dryRun = true;
73
+ } else if (arg === "-y" || arg === "--yes") {
74
+ out.yes = true;
75
+ } else if (arg === "--interactive") {
76
+ out.interactive = true;
77
+ } else if (arg === "--help" || arg === "-h") {
78
+ help();
79
+ process.exit(0);
80
+ } else {
81
+ fail(`unknown install option: ${arg}`);
82
+ }
83
+ }
84
+ return out;
85
+ }
86
+
87
+ function expand(target) {
88
+ return path.resolve(String(target).replace(/^~(?=$|\/|\\)/, HOME));
89
+ }
90
+
91
+ function targetDir(opts) {
92
+ if (opts.dir) return expand(opts.dir);
93
+ if (opts.project) return path.resolve(process.cwd(), ".claude", "skills", "pakem");
94
+ if (process.env.PAKEM_SKILL_DIR) return expand(process.env.PAKEM_SKILL_DIR);
95
+ return path.join(HOME, ".claude", "skills", "pakem");
96
+ }
97
+
98
+ function pythonVersion() {
99
+ const probe = spawnSync(PY, ["-c", "import sys; print('%d.%d' % sys.version_info[:2])"],
100
+ { encoding: "utf8" });
101
+ if (probe.error || probe.status !== 0) return null;
102
+ return probe.stdout.trim();
103
+ }
104
+
105
+ function pythonWarning(py) {
106
+ if (!py) return `${PY} not found; Pakem needs Python 3.10+.`;
107
+ const [major, minor] = py.split(".").map(Number);
108
+ if (major < 3 || (major === 3 && minor < 10)) {
109
+ return `Python ${py} found; Pakem needs 3.10+.`;
110
+ }
111
+ return null;
112
+ }
113
+
114
+ function copySkill(dest, opts) {
115
+ if (fs.existsSync(dest)) {
116
+ const entries = fs.readdirSync(dest);
117
+ if (entries.length && !opts.force) {
118
+ fail(`${dest} already exists. Re-run with --force to replace it.`);
119
+ }
120
+ if (entries.length) fs.rmSync(dest, { recursive: true, force: true });
121
+ }
122
+ fs.mkdirSync(dest, { recursive: true });
123
+
124
+ let copied = 0;
125
+ for (const name of fs.readdirSync(ROOT).sort()) {
126
+ if (SKIP.has(name) || SKIP_FILES.has(name)) continue;
127
+ fs.cpSync(path.join(ROOT, name), path.join(dest, name), {
128
+ recursive: true,
129
+ filter: (from) => !path.basename(from).startsWith("."),
130
+ });
131
+ copied++;
132
+ }
133
+ return copied;
134
+ }
135
+
136
+ function nextSteps(dest) {
137
+ return [
138
+ `restart your agent so it loads SKILL.md`,
139
+ `cd your-project && ${PY} ${path.join(dest, "scripts", "pakem.py")} init --type app`,
140
+ ];
141
+ }
142
+
143
+ function install(opts) {
144
+ const dest = targetDir(opts);
145
+ if (opts.dryRun) {
146
+ console.log(`Would install Pakem ${PKG.version} into ${dest}`);
147
+ for (const name of fs.readdirSync(ROOT).sort()) {
148
+ if (SKIP.has(name) || SKIP_FILES.has(name)) continue;
149
+ console.log(` ${name}`);
150
+ }
151
+ return;
152
+ }
153
+
154
+ const copied = copySkill(dest, opts);
155
+ const py = pythonVersion();
156
+ console.log(`Pakem ${PKG.version} installed in ${dest}`);
157
+ console.log(` ${copied} top-level entries copied`);
158
+ const warning = pythonWarning(py);
159
+ console.log(warning ? ` [WARN] ${warning}` : ` python: ${PY} ${py}`);
160
+ console.log("");
161
+ console.log("Next:");
162
+ for (const line of nextSteps(dest)) console.log(` ${line}`);
163
+ }
164
+
165
+ async function interactiveInstall(seed) {
166
+ const clack = await import("@clack/prompts");
167
+ const { intro, outro, select, text, confirm, spinner, cancel, isCancel } = clack;
168
+
169
+ intro(`Pakem ${PKG.version} · agent work discipline`);
170
+
171
+ const choices = [
172
+ { value: "claude-global", label: "Claude Code (global)", hint: "~/.claude/skills/pakem" },
173
+ { value: "agents-global", label: "Agents / skills.sh (global)", hint: "~/.agents/skills/pakem" },
174
+ { value: "claude-project", label: "This project", hint: "./.claude/skills/pakem" },
175
+ { value: "custom", label: "Custom path", hint: "any skills folder" },
176
+ ];
177
+
178
+ const choice = await select({
179
+ message: "Where should the skill live?",
180
+ options: choices,
181
+ initialValue: seed.dir ? "custom" : seed.project ? "claude-project" : "claude-global",
182
+ });
183
+ if (isCancel(choice)) {
184
+ cancel("Installation cancelled.");
185
+ return;
186
+ }
187
+
188
+ let dest;
189
+ if (choice === "claude-global") dest = path.join(HOME, ".claude", "skills", "pakem");
190
+ else if (choice === "agents-global") dest = path.join(HOME, ".agents", "skills", "pakem");
191
+ else if (choice === "claude-project") dest = path.resolve(process.cwd(), ".claude", "skills", "pakem");
192
+ else {
193
+ const typed = await text({
194
+ message: "Install path",
195
+ placeholder: "~/.agents/skills/pakem",
196
+ initialValue: seed.dir || "",
197
+ validate: (value) => (!value ? "A path is required" : undefined),
198
+ });
199
+ if (isCancel(typed)) {
200
+ cancel("Installation cancelled.");
201
+ return;
202
+ }
203
+ dest = expand(typed);
204
+ }
205
+
206
+ if (fs.existsSync(dest) && fs.readdirSync(dest).length) {
207
+ if (!seed.force) {
208
+ const replace = await confirm({
209
+ message: `${dest} already exists. Replace it?`,
210
+ initialValue: false,
211
+ });
212
+ if (isCancel(replace) || !replace) {
213
+ cancel("Installation cancelled.");
214
+ return;
215
+ }
216
+ seed.force = true;
217
+ }
218
+ }
219
+
220
+ const spin = spinner();
221
+ spin.start(`Installing into ${dest}`);
222
+ try {
223
+ const copied = copySkill(dest, seed);
224
+ spin.stop(`Installed ${copied} top-level entries`);
225
+ } catch (error) {
226
+ spin.stop("Installation failed");
227
+ throw error;
228
+ }
229
+
230
+ const py = pythonVersion();
231
+ const warning = pythonWarning(py);
232
+ if (warning) outro(`Installed, but ${warning}`);
233
+ else outro(`Installed · python ${py}`);
234
+ console.log("");
235
+ console.log("Next:");
236
+ for (const line of nextSteps(dest)) console.log(` ${line}`);
237
+ }
238
+
239
+ function runCli(args) {
240
+ const cli = path.join(ROOT, "scripts", "pakem.py");
241
+ if (!fs.existsSync(cli)) fail(`CLI not found in this package: ${cli}`);
242
+ const result = spawnSync(PY, [cli, ...args], { stdio: "inherit", cwd: process.cwd() });
243
+ if (result.error) fail(`cannot run ${PY}: ${result.error.message}`);
244
+ process.exit(result.status === null ? 1 : result.status);
245
+ }
246
+
247
+ async function main() {
248
+ const args = process.argv.slice(2);
249
+ if (args.length === 0) {
250
+ const opts = parseInstallArgs([]);
251
+ if (INTERACTIVE) return interactiveInstall(opts);
252
+ return install(opts);
253
+ }
254
+ if (args[0] === "install") {
255
+ const opts = parseInstallArgs(args.slice(1));
256
+ const explicit = Boolean(opts.dir || opts.project || opts.yes || opts.dryRun);
257
+ if (opts.interactive || (INTERACTIVE && !explicit)) return interactiveInstall(opts);
258
+ return install(opts);
259
+ }
260
+ if (["--dir", "--project", "--force", "--dry-run", "-y", "--yes"].includes(args[0])) {
261
+ return install(parseInstallArgs(args));
262
+ }
263
+ if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
264
+ help();
265
+ return;
266
+ }
267
+ return runCli(args);
268
+ }
269
+
270
+ main().catch((error) => {
271
+ fail(error && error.message ? error.message : String(error));
272
+ });
@@ -0,0 +1,26 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+
4
+ /** Refuse to publish an npm package whose version drifted from the Python CLI. */
5
+ const fs = require("fs");
6
+ const path = require("path");
7
+
8
+ const root = path.resolve(__dirname, "..");
9
+ const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
10
+ const cli = fs.readFileSync(path.join(root, "scripts", "pakem.py"), "utf8");
11
+ const match = cli.match(/^VERSION = "([^"]+)"$/m);
12
+
13
+ if (!match) {
14
+ console.error("pakem: VERSION not found in scripts/pakem.py");
15
+ process.exit(1);
16
+ }
17
+ if (match[1] !== pkg.version) {
18
+ console.error(`pakem: package.json ${pkg.version} != scripts/pakem.py ${match[1]}`);
19
+ console.error("Bump both before publishing.");
20
+ process.exit(1);
21
+ }
22
+ if (!fs.existsSync(path.join(root, "SKILL.md"))) {
23
+ console.error("pakem: SKILL.md missing from the package root");
24
+ process.exit(1);
25
+ }
26
+ console.log(`pakem: version ${pkg.version} in sync`);
package/package.json CHANGED
@@ -1,6 +1,60 @@
1
1
  {
2
2
  "name": "pakem-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.3.0",
4
+ "description": "Agent work discipline with verifiable finish gates: sessions, plans, specs, and gates that can fail.",
5
+ "bin": {
6
+ "pakem": "npm/bin/pakem.js"
7
+ },
8
+ "files": [
9
+ "SKILL.md",
10
+ "README.md",
11
+ "README-ID.md",
12
+ "CHANGELOG.md",
13
+ "LICENSE",
14
+ "assets/",
15
+ "scripts/",
16
+ "references/",
17
+ "adapters/",
18
+ "protocol/",
19
+ "intelligence/",
20
+ "runtime/",
21
+ "policy/",
22
+ "coordination/",
23
+ "identity/",
24
+ "storage/",
25
+ "conformance/",
26
+ "evals/",
27
+ "npm/"
28
+ ],
29
+ "scripts": {
30
+ "prepack": "node npm/check-version.js"
31
+ },
32
+ "engines": {
33
+ "node": ">=18"
34
+ },
35
+ "keywords": [
36
+ "agent",
37
+ "coding-agent",
38
+ "skill",
39
+ "claude",
40
+ "codex",
41
+ "cursor",
42
+ "workflow",
43
+ "verification"
44
+ ],
45
+ "license": "MIT",
46
+ "publishConfig": {
47
+ "access": "public"
48
+ },
49
+ "repository": {
50
+ "type": "git",
51
+ "url": "git+https://github.com/Matsumiko/pakem.git"
52
+ },
53
+ "homepage": "https://github.com/Matsumiko/pakem",
54
+ "bugs": {
55
+ "url": "https://github.com/Matsumiko/pakem/issues"
56
+ },
57
+ "dependencies": {
58
+ "@clack/prompts": "^1.9.0"
59
+ }
60
+ }
@@ -0,0 +1,15 @@
1
+ # Pakem Policy v1
2
+
3
+ `POLICY.json` controls what a compatible host runtime may allow automatically.
4
+
5
+ - `autonomy`: `manual`, `assisted`, or `guarded_autonomous`.
6
+ - `maxAutonomousRisk`: highest risk level that may proceed without an approval when no category-specific rule requires one.
7
+ - `approvalRequiredFor`: categories that always require explicit approval.
8
+ - `deniedCategories`: categories the runtime must deny.
9
+ - `approvalTtlSeconds`: lifetime for a one-use, workflow-bound approval (30–86400 seconds).
10
+
11
+ Categories: `read`, `write`, `command`, `destructive`, `deploy`, `security`, `policy_change`, `gate_change`.
12
+
13
+ Approval is an auditable local record, not cryptographic identity or a secure human-authentication mechanism. A host agent/runtime MUST mediate `policy approve` through a genuine user-confirmation channel and MUST NOT let the agent self-approve. The CLI cannot prove who invoked it. Approval is one-use, bound to workflow ID, category, risk, and target, and expires.
14
+
15
+ The policy engine does not execute commands, edit source code, deploy, or start agents. It returns `allow`, `require_approval`, or `deny`; the host runtime remains responsible for enforcing the decision.
@@ -0,0 +1,20 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:pakem:policy:v1",
4
+ "title": "Pakem Policy v1",
5
+ "type": "object",
6
+ "required": ["schemaVersion", "autonomy", "maxAutonomousRisk", "approvalRequiredFor", "deniedCategories", "approvalTtlSeconds"],
7
+ "properties": {
8
+ "schemaVersion": {"const": 1},
9
+ "autonomy": {"enum": ["manual", "assisted", "guarded_autonomous"]},
10
+ "maxAutonomousRisk": {"enum": ["low", "medium", "high", "critical"]},
11
+ "approvalRequiredFor": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/category"}},
12
+ "deniedCategories": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/category"}},
13
+ "approvalTtlSeconds": {"type": "integer", "minimum": 30, "maximum": 86400},
14
+ "description": {"type": "string"}
15
+ },
16
+ "$defs": {
17
+ "category": {"enum": ["read", "write", "command", "destructive", "deploy", "security", "policy_change", "gate_change"]}
18
+ },
19
+ "additionalProperties": false
20
+ }
@@ -0,0 +1,68 @@
1
+ # Pakem Protocol v1.0 — Stable Contract
2
+
3
+ Pakem Protocol is the tool-, model-, language-, and transport-independent
4
+ contract for project workflow state and events. Version **1.0 is frozen** for
5
+ its event envelope and session compatibility rules. Future optional features
6
+ are discovered through capability negotiation; they do not silently alter the
7
+ v1 event envelope.
8
+
9
+ ## Compatibility
10
+
11
+ - `protocol` is always `pakem`; `protocol_version` is `1.0`.
12
+ - Event records are append-only JSON objects, one per line (JSONL).
13
+ - Unknown session fields may be preserved. Existing sessions without
14
+ `schemaVersion` remain valid.
15
+ - The event envelope is strict. Event-specific extensions belong inside
16
+ `payload` until a later protocol version defines otherwise.
17
+ - One exception is reserved and additive: `integrity: {prev, hash}` (capability
18
+ `events.integrity.v1`). It is optional on every event; readers that ignore it
19
+ still parse the ledger, and events written before 1.2.0 remain valid. Strict
20
+ validators must use the current `event.schema.json`. Chain verification and
21
+ sealing are local CLI features, not a new protocol version: `prev` links to the
22
+ previous event's `hash`, and a `ledger.sealed` event carries an Ed25519 envelope
23
+ over the chain head at that point.
24
+ - Timestamps are ISO 8601 with an explicit UTC offset.
25
+ - `session_id` may be null for project-level events.
26
+ - Capability support is not authorization to perform side effects.
27
+
28
+ ## Capability negotiation
29
+
30
+ `pakem protocol negotiate --peer-version 1.0 --capability events.v1` returns
31
+ whether the peer is compatible and the intersection of supported capabilities.
32
+ Supported capabilities include `events.v1`, `sessions.v1`,
33
+ `context.snapshot.v1`, `runtime.v1`, `intelligence.graph.v1`,
34
+ `intelligence.impact.v1`, `coordination.v1`, `coordination.review.v1`,
35
+ `git.worktree.v1`, `mcp.stdio.2026-07-28`, `identity.ed25519.v1`,
36
+ `identity.delegation.v1`, `coordination.sqlite.v1`, `events.integrity.v1`, and
37
+ `conformance.v1`. See
38
+ `capabilities.schema.json`. Unknown optional capabilities do not invalidate
39
+ an otherwise compatible protocol version; they are reported separately.
40
+
41
+ ## Event envelope
42
+
43
+ See `event.schema.json`. Every event contains `protocol`, `protocol_version`,
44
+ `event_id`, `event`, `occurred_at`, `session_id`, `actor`, and `payload`.
45
+
46
+ ## Session data
47
+
48
+ See `session.schema.json`. Unknown fields are preserved for forward-compatible
49
+ session metadata. Session state is not proof of task correctness.
50
+
51
+ ## Trust and identity
52
+
53
+ `actor.type` and `actor.name` are attribution fields, not credentials. Agent
54
+ IDs in a local coordination board are cooperative metadata, not authenticated
55
+ identities. Pakem 1.1 can register Ed25519 public identities and verify signed
56
+ attestations/delegation tokens. A host runtime must still bind a verified token
57
+ to the actual caller, enforce audience/actions/expiry/revocation, and provide
58
+ anti-replay protection. Private keys stay outside the project; public registry
59
+ integrity must be rooted in a trusted checkout/commit. MCP `clientInfo` is
60
+ self-reported and must not be used for authorization.
61
+
62
+ ## Runtime boundary
63
+
64
+ Pakem stores workflow state and provides policy decisions. Agent execution,
65
+ model selection, deployment, and external side effects belong to the host
66
+ agent/runtime and its permission system. `session.finished`, a submitted event,
67
+ or an approval receipt does not by itself prove correctness or authorize a
68
+ side effect. Verification evidence must be attached to relevant results.
@@ -0,0 +1,17 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:pakem:protocol:v1:capabilities",
4
+ "title": "Pakem Protocol v1 Capabilities",
5
+ "type": "object",
6
+ "required": ["protocol", "version", "capabilities"],
7
+ "properties": {
8
+ "protocol": {"const": "pakem"},
9
+ "version": {"const": "1.0"},
10
+ "capabilities": {
11
+ "type": "array",
12
+ "items": {"type": "string", "minLength": 1},
13
+ "uniqueItems": true
14
+ }
15
+ },
16
+ "additionalProperties": false
17
+ }
@@ -0,0 +1,114 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:pakem:protocol:v1:event",
4
+ "title": "Pakem Protocol v1 Event",
5
+ "description": "A portable, append-only workflow event emitted by a Pakem-compatible agent or runtime.",
6
+ "type": "object",
7
+ "required": [
8
+ "protocol",
9
+ "protocol_version",
10
+ "event_id",
11
+ "event",
12
+ "occurred_at",
13
+ "session_id",
14
+ "actor",
15
+ "payload"
16
+ ],
17
+ "properties": {
18
+ "protocol": {
19
+ "const": "pakem"
20
+ },
21
+ "protocol_version": {
22
+ "const": "1.0"
23
+ },
24
+ "event_id": {
25
+ "type": "string",
26
+ "minLength": 1
27
+ },
28
+ "event": {
29
+ "type": "string",
30
+ "enum": [
31
+ "bug.recorded",
32
+ "decision.recorded",
33
+ "handover.created",
34
+ "integrity.repinned",
35
+ "policy.approval.granted",
36
+ "policy.decision",
37
+ "runtime.checkpoint.created",
38
+ "runtime.hook.dispatched",
39
+ "runtime.recovered",
40
+ "runtime.state.transitioned",
41
+ "runtime.workflow.initialized",
42
+ "session.abandoned",
43
+ "session.finish_blocked",
44
+ "session.finished",
45
+ "session.resumed",
46
+ "session.started",
47
+ "session.step_recorded",
48
+ "spec.approved",
49
+ "task.added",
50
+ "task.completed",
51
+ "task.dropped",
52
+ "verification.completed",
53
+ "team.agent.registered",
54
+ "team.task.created",
55
+ "team.task.assigned",
56
+ "team.task.claimed",
57
+ "team.task.heartbeat",
58
+ "team.task.released",
59
+ "team.task.handed_off",
60
+ "team.task.submitted",
61
+ "team.task.reviewed",
62
+ "team.task.blocked",
63
+ "team.task.unblocked",
64
+ "ledger.sealed"
65
+ ]
66
+ },
67
+ "occurred_at": {
68
+ "type": "string",
69
+ "format": "date-time"
70
+ },
71
+ "session_id": {
72
+ "type": [
73
+ "string",
74
+ "null"
75
+ ]
76
+ },
77
+ "actor": {
78
+ "type": "object",
79
+ "required": [
80
+ "type",
81
+ "name"
82
+ ],
83
+ "properties": {
84
+ "type": {
85
+ "type": "string",
86
+ "enum": [
87
+ "agent",
88
+ "user",
89
+ "system"
90
+ ]
91
+ },
92
+ "name": {
93
+ "type": "string",
94
+ "minLength": 1
95
+ }
96
+ },
97
+ "additionalProperties": false
98
+ },
99
+ "integrity": {
100
+ "description": "Additive hash chain (1.2.0). Older events without this field remain valid; a new chain starts after the last event that has no integrity data.",
101
+ "type": "object",
102
+ "required": ["prev", "hash"],
103
+ "properties": {
104
+ "prev": {"type": ["string", "null"]},
105
+ "hash": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
106
+ },
107
+ "additionalProperties": false
108
+ },
109
+ "payload": {
110
+ "type": "object"
111
+ }
112
+ },
113
+ "additionalProperties": false
114
+ }
@@ -0,0 +1,51 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:pakem:protocol:v1:session",
4
+ "title": "Pakem Session v1",
5
+ "description": "Portable baseline for a Pakem session. Additional properties are allowed for forward-compatible extensions.",
6
+ "type": "object",
7
+ "required": [
8
+ "id",
9
+ "goal",
10
+ "status",
11
+ "startedAt",
12
+ "steps"
13
+ ],
14
+ "properties": {
15
+ "schemaVersion": {
16
+ "type": "integer",
17
+ "minimum": 1
18
+ },
19
+ "id": {
20
+ "type": "string",
21
+ "minLength": 1
22
+ },
23
+ "goal": {
24
+ "type": "string",
25
+ "minLength": 1
26
+ },
27
+ "status": {
28
+ "type": "string",
29
+ "enum": [
30
+ "active",
31
+ "finished",
32
+ "abandoned"
33
+ ]
34
+ },
35
+ "startedAt": {
36
+ "type": "string",
37
+ "format": "date-time"
38
+ },
39
+ "finishedAt": {
40
+ "type": "string",
41
+ "format": "date-time"
42
+ },
43
+ "nextStep": {
44
+ "type": "string"
45
+ },
46
+ "steps": {
47
+ "type": "array"
48
+ }
49
+ },
50
+ "additionalProperties": true
51
+ }