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/npm/bin/pakem.js
ADDED
|
@@ -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": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|