god-prompt-mcp 1.1.0 → 1.2.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/README.md CHANGED
@@ -27,22 +27,32 @@ To buy the review, use the [US$49 one-time GitHub Sponsors tier](https://github.
27
27
  | `get_version` | Version info and server metadata |
28
28
  | `create_work_contract` | Create a portable, fingerprinted task contract with explicit scope, acceptance criteria and required verification commands |
29
29
  | `review_work_evidence` | Fail-closed review of reported changed paths, verification receipts, acceptance results and forbidden actions |
30
+ | `review_code_change` | Inspect a supplied unified diff for file/line-anchored review signals; no repository access or semantic correctness claim (v1.2.0+) |
31
+ | `audit_requirements` | Audit supplied requirements for missing acceptance scenarios, duplication and ambiguous criteria (v1.2.0+) |
32
+ | `build_test_matrix` | Draft positive, negative, boundary and regression cases linked to supplied requirements; does not run tests (v1.2.0+) |
33
+ | `get_tailored_guidance` | Retrieve bounded protocol/quality guidance for a task type and phase instead of loading complete reference files (v1.2.0+) |
34
+ | `diagnose_failure` | Classify caller-supplied symptoms into testable hypotheses without echoing raw logs or asserting root cause (v1.2.0+) |
35
+ | `assess_release_readiness` | Find blockers in reported CI, artifact provenance, rollback, migrations and approvals; never authorizes deployment (v1.2.0+) |
36
+ | `create_context_handoff` | Produce bounded cross-chat/agent state with best-effort secret redaction and explicit verification limitations (v1.2.0+) |
37
+ | `compare_evaluation_runs` | Compare caller-supplied paired cases and observed pass rates, durations and costs with sample-size warnings (v1.2.0+) |
30
38
 
31
- > **Version 1.1.0:** `create_work_contract` and `review_work_evidence` expand the seven original MCP tools to nine. Older hosted or version-pinned installations may still expose only the original seven until separately updated. Both tools remain stateless and read-only, and neither independently authenticates caller-supplied evidence. See the [task-contract workflow and security limitations](docs/task-contracts.md).
39
+ > **Version 1.1.1:** `create_work_contract` and `review_work_evidence` expand the seven original MCP tools to nine. Older hosted or version-pinned installations may still expose only the original seven until separately updated. Both tools remain stateless and read-only, and neither independently authenticates caller-supplied evidence. See the [task-contract workflow and security limitations](docs/task-contracts.md).
32
40
 
33
- ### Optional local proof bridge (from v1.1.0)
41
+ **Version 1.2.0:** Eight additional read-only engineering-quality tools expand the public MCP surface from nine to seventeen. The Codexify checkpoint remains an optional **stdio-only** eighteenth tool. Install a versioned MCP package or inspect the hosted `tools/list` response to determine which functions your client actually receives. None of the tools independently execute tests, inspect external repositories or authorize deployment. See the [toolkit QA and limitations](docs/qa/godprompt-public-toolkit-20261120.md). The OpenAI marketplace distribution remains a separate, Skill-only integration until its eventual dedicated upgrade.
42
+
43
+ ### Optional local proof bridge (from v1.1.1)
34
44
 
35
45
  The new **godprompt-proof** CLI (Node 22+, **no additional dependencies**) can normalize pinned GitHub CI checks and exported Codexify command receipts into inputs for the existing GodPrompt evidence reviewer. It also supports an optional **single 256 KiB local JSONL feedback file** for project-scoped generic lessons, **on-demand read-only metrics**, and **versioned workflow previews** from that same file (no telemetry or automatic rule changes). No database server, GPU, background worker or global telemetry is involved.
36
46
 
37
47
  GitHub can be read directly or from a **sanitized snapshot produced with an existing GitHub connector**, with no new token required for that offline path. Codexify is **client-orchestrated**: the authorized coding agent produces a receipt export, not a direct remote connection from the public Worker. The hosted MCP has **no access** to any user's local feedback file. No automatic uploads, training or rule promotion occur.
38
48
 
39
- **The optional CLI ships with v1.1.0**, but it is not installed or enabled automatically on a user's computer. The hosted MCP cannot read local files. See [local proof bridge setup, limitations, and examples](docs/local-proof-bridge.md). The CLI is optional; the MCP server continues to work without it.
49
+ **The optional CLI ships with v1.1.1**, but it is not installed or enabled automatically on a user's computer. The hosted MCP cannot read local files. See [local proof bridge setup, limitations, and examples](docs/local-proof-bridge.md). The CLI is optional; the MCP server continues to work without it.
40
50
 
41
51
  **ChatGPT publishing and storage:** The public hosted MCP remains **stateless** and does **not** create personal memory or store a JSONL file for ChatGPT users. Per-project learning is an **explicitly enabled local CLI**, not a hosted MCP feature. See [the hosting, privacy, local installation and release checklist](docs/chatgpt-local-first.md). Cloud sync is **not** included.
42
52
 
43
53
  ## Progressive Disclosure
44
54
 
45
- For minimum context usage, start with `get_core_skill`, then load `get_protocols`, `get_gates`, or `get_anti_patterns` only when the task requires deeper guidance. Use `get_god_prompt` when you want everything in one shot.
55
+ For minimum context usage in **v1.2.0 and later**, route the task with `classify_task`, then call `get_tailored_guidance` for just its current phase. Load `get_core_skill` when the full core workflow is necessary, and `get_protocols`, `get_gates`, or `get_anti_patterns` only for deeper guidance. Existing released MCP installations can continue starting with `get_core_skill` until their tool catalogs are updated. Use `get_god_prompt` only when the complete single-file text is actually needed.
46
56
 
47
57
  ## Example queries
48
58
 
@@ -118,11 +128,11 @@ For MCP clients that can launch a local process, the [public GHCR image](https:/
118
128
  ```json
119
129
  {
120
130
  "command": "docker",
121
- "args": ["run", "--rm", "-i", "ghcr.io/akzar1el/god-prompt-mcp:1.1.0"]
131
+ "args": ["run", "--rm", "-i", "ghcr.io/akzar1el/god-prompt-mcp:1.1.1"]
122
132
  }
123
133
  ```
124
134
 
125
- Keep `-i` so the MCP client can exchange JSON-RPC over standard input/output; do not add `-t` (a TTY changes the stdio stream). The version tag selects the verified v1.1.0 image; update it deliberately for future releases rather than silently following the moving `latest` tag. The image is Linux/amd64 and runs as non-root user `10001:10001`. If Docker is unavailable, use the [hosted remote endpoint](#hosted-remote-no-nodejs-required) instead.
135
+ Keep `-i` so the MCP client can exchange JSON-RPC over standard input/output; do not add `-t` (a TTY changes the stdio stream). The version tag selects the verified v1.1.1 image; update it deliberately for future releases rather than silently following the moving `latest` tag. The image is Linux/amd64 and runs as non-root user `10001:10001`. If Docker is unavailable, use the [hosted remote endpoint](#hosted-remote-no-nodejs-required) instead.
126
136
 
127
137
  ### Glama
128
138
 
@@ -289,7 +299,7 @@ npx -y skills@latest add AKzar1el/god-prompt-mcp --skill god-prompt --agent droi
289
299
  Droid discovers compatible project skills under `.agents/skills/`. To add the callable GodPrompt tools as a local stdio MCP server, use Droid's native MCP command with the published version pinned:
290
300
 
291
301
  ```bash
292
- droid mcp add god-prompt "npx -y god-prompt-mcp@1.1.0"
302
+ droid mcp add god-prompt "npx -y god-prompt-mcp@1.2.0"
293
303
  ```
294
304
 
295
305
  Open `/mcp` in Droid to verify the server and available tools. The Agent Skill supplies the reusable workflow while MCP exposes GodPrompt's read-only task and protocol tools. Node.js 22+ is required for the MCP server.
@@ -302,7 +312,7 @@ Warp can use GodPrompt as both an Agent Skill and a local MCP server. Install th
302
312
  npx -y skills@latest add AKzar1el/god-prompt-mcp --skill god-prompt --agent warp --copy -y
303
313
  ```
304
314
 
305
- Warp discovers project skills from `.agents/skills/` and `.warp/skills/`. For MCP tools, add a CLI-based MCP server in Warp with command `npx` and arguments `-y`, `god-prompt-mcp`; Warp's Oz CLI can also receive MCP configuration through `oz agent run --mcp`. The skill supplies the reusable workflow while MCP exposes GodPrompt's seven progressive-disclosure tools. Node.js 22+ is required for the MCP server.
315
+ Warp discovers project skills from `.agents/skills/` and `.warp/skills/`. For MCP tools, add a CLI-based MCP server in Warp with command `npx` and arguments `-y`, `god-prompt-mcp`; Warp's Oz CLI can also receive MCP configuration through `oz agent run --mcp`. The skill supplies the reusable workflow while MCP exposes GodPrompt's seventeen public tools in v1.2.0. Node.js 22+ is required for the MCP server.
306
316
 
307
317
  ### Goose
308
318
 
@@ -315,10 +325,10 @@ npx -y skills@latest add AKzar1el/god-prompt-mcp --skill god-prompt --agent goos
315
325
  Goose discovers the copied skill under `.goose/skills/god-prompt/`. To expose GodPrompt's callable tools for a session, start Goose with the published MCP package as an external stdio extension:
316
326
 
317
327
  ```bash
318
- goose session --with-extension "npx -y god-prompt-mcp@1.1.0"
328
+ goose session --with-extension "npx -y god-prompt-mcp@1.2.0"
319
329
  ```
320
330
 
321
- Goose currently treats Agent Skills and MCP extensions as separate native surfaces, so this path does not depend on Agent Plugins support. The skill supplies the reusable workflow while MCP exposes GodPrompt's seven progressive-disclosure tools. Node.js 22+ is required for the MCP server.
331
+ Goose currently treats Agent Skills and MCP extensions as separate native surfaces, so this path does not depend on Agent Plugins support. The skill supplies the reusable workflow while MCP exposes GodPrompt's seventeen public tools in v1.2.0. Node.js 22+ is required for the MCP server.
322
332
 
323
333
  ### Zed
324
334
 
@@ -380,13 +390,13 @@ The Trae target installs the skill under `.trae/skills/god-prompt/`, where TraeC
380
390
  "mcpServers": {
381
391
  "god-prompt": {
382
392
  "command": "npx",
383
- "args": ["-y", "god-prompt-mcp@1.1.0"]
393
+ "args": ["-y", "god-prompt-mcp@1.2.0"]
384
394
  }
385
395
  }
386
396
  }
387
397
  ```
388
398
 
389
- TraeCode also supports the portable `.agents/skills/` convention when **Enable .agents Skills Directory** is turned on in its import settings. Treat project MCP configuration as executable workspace configuration and enable it only in repositories you trust. The Agent Skill supplies the reusable workflow while MCP exposes GodPrompt's seven progressive-disclosure tools. Node.js 22+ is required for the MCP server.
399
+ TraeCode also supports the portable `.agents/skills/` convention when **Enable .agents Skills Directory** is turned on in its import settings. Treat project MCP configuration as executable workspace configuration and enable it only in repositories you trust. The Agent Skill supplies the reusable workflow while MCP exposes GodPrompt's seventeen public tools in v1.2.0. Node.js 22+ is required for the MCP server.
390
400
 
391
401
  ### OpenClaw
392
402
 
@@ -399,11 +409,11 @@ npx -y skills@latest add AKzar1el/god-prompt-mcp --skill god-prompt --agent open
399
409
  The copied skill lands under `.agents/skills/god-prompt/`, one of OpenClaw's documented project skill roots. To expose GodPrompt's callable tools to OpenClaw-managed agent runtimes as well, register the published stdio server:
400
410
 
401
411
  ```bash
402
- openclaw mcp add god-prompt --command npx --arg -y --arg god-prompt-mcp@1.1.0
412
+ openclaw mcp add god-prompt --command npx --arg -y --arg god-prompt-mcp@1.2.0
403
413
  openclaw mcp probe god-prompt
404
414
  ```
405
415
 
406
- `mcp probe` opens a live MCP connection and reports the discovered capabilities, making it a direct verification step after registration. The Agent Skill supplies the reusable workflow while MCP exposes GodPrompt's seven progressive-disclosure tools. Node.js 22+ is required for the MCP server.
416
+ `mcp probe` opens a live MCP connection and reports the discovered capabilities, making it a direct verification step after registration. The Agent Skill supplies the reusable workflow while MCP exposes GodPrompt's seventeen public tools in v1.2.0. Node.js 22+ is required for the MCP server.
407
417
 
408
418
  ### Qoder
409
419
 
@@ -420,13 +430,13 @@ The Qoder target installs the skill under `.qoder/skills/god-prompt/`, where Qod
420
430
  "mcpServers": {
421
431
  "god-prompt": {
422
432
  "command": "npx",
423
- "args": ["-y", "god-prompt-mcp@1.1.0"]
433
+ "args": ["-y", "god-prompt-mcp@1.2.0"]
424
434
  }
425
435
  }
426
436
  }
427
437
  ```
428
438
 
429
- Qoder requires approval before using project-level MCP servers by default. After adding or changing the server, start a new session or run `/mcp reload`, then use `/mcp` to verify the connection. The Agent Skill supplies the reusable workflow while MCP exposes GodPrompt's seven progressive-disclosure tools. Node.js 22+ is required for the MCP server.
439
+ Qoder requires approval before using project-level MCP servers by default. After adding or changing the server, start a new session or run `/mcp reload`, then use `/mcp` to verify the connection. The Agent Skill supplies the reusable workflow while MCP exposes GodPrompt's seventeen public tools in v1.2.0. Node.js 22+ is required for the MCP server.
430
440
 
431
441
  ### Qwen Code
432
442
 
@@ -449,7 +459,7 @@ This installs GodPrompt under `.qwen/skills/god-prompt/`, where Qwen Code can di
449
459
  }
450
460
  ```
451
461
 
452
- Restart Qwen Code after changing MCP configuration, then open `/mcp` to verify the server. The Agent Skill provides the reusable workflow while MCP exposes GodPrompt's seven progressive-disclosure tools. Node.js 22+ is required for the MCP server.
462
+ Restart Qwen Code after changing MCP configuration, then open `/mcp` to verify the server. The Agent Skill provides the reusable workflow while MCP exposes GodPrompt's seventeen public tools in v1.2.0. Node.js 22+ is required for the MCP server.
453
463
 
454
464
  ### Kimi Code
455
465
 
@@ -460,7 +470,7 @@ Kimi Code CLI can install GodPrompt as one native custom plugin containing the e
460
470
  /reload
461
471
  ```
462
472
 
463
- The Kimi manifest points at `skills/`, so the `god-prompt` skill remains available through Kimi's normal relevance-based skill loading instead of being forced into every session. The same manifest exposes `god-prompt-mcp@1.1.0` as a local stdio MCP server, including the nine tools available in v1.1.0. The explicit `tree/main` URL matters because Kimi's bare GitHub-repository install form prefers the latest GitHub release; using `main` makes the current plugin manifest available without forcing a documentation-only npm/MCP Registry release. Node.js 22+ is required for the MCP server.
473
+ The Kimi manifest points at `skills/`, so the `god-prompt` skill remains available through Kimi's normal relevance-based skill loading instead of being forced into every session. The same manifest exposes `god-prompt-mcp@1.2.0` as a local stdio MCP server, including the seventeen public tools available in v1.2.0. The explicit `tree/main` URL matters because Kimi's bare GitHub-repository install form prefers the latest GitHub release; using `main` makes the current plugin manifest available without forcing a documentation-only npm/MCP Registry release. Node.js 22+ is required for the MCP server.
464
474
 
465
475
  ### JetBrains AI Assistant
466
476
 
@@ -498,7 +508,7 @@ If you only want the portable skill, place the complete skill directory at `.age
498
508
  devin mcp add god-prompt -- npx -y god-prompt-mcp
499
509
  ```
500
510
 
501
- Run `devin mcp list` to verify the direct server registration. The Agent Skill provides the reusable workflow while MCP exposes GodPrompt's seven progressive-disclosure tools. Node.js 22+ is required for the MCP server.
511
+ Run `devin mcp list` to verify the direct server registration. The Agent Skill provides the reusable workflow while MCP exposes GodPrompt's seventeen public tools in v1.2.0. Node.js 22+ is required for the MCP server.
502
512
 
503
513
  ### Cursor
504
514
 
@@ -5,12 +5,17 @@
5
5
  */
6
6
  import { createHash } from "node:crypto";
7
7
  import { constants } from "node:fs";
8
- import { mkdir, open, readFile, lstat } from "node:fs/promises";
8
+ import { mkdir, open, readFile, lstat, realpath } from "node:fs/promises";
9
9
  import { homedir } from "node:os";
10
10
  import { dirname, isAbsolute, join, resolve } from "node:path";
11
11
  import { fileURLToPath } from "node:url";
12
+ import {
13
+ codexifyEvidence, validateWorkContractEnvelope, CODEXIFY_BUNDLE_SCHEMA,
14
+ } from "../dist/codexify-evidence.js";
12
15
 
13
- export const BUNDLE_SCHEMA = "godprompt.evidence_bundle.v1";
16
+ export { codexifyEvidence };
17
+
18
+ export const BUNDLE_SCHEMA = CODEXIFY_BUNDLE_SCHEMA;
14
19
  const MAX_JSON_BYTES = 256 * 1024;
15
20
  const MAX_FEEDBACK_BYTES = 256 * 1024;
16
21
  const MAX_PAGES = 3;
@@ -21,14 +26,6 @@ function sha256(text) {
21
26
  function fail(message) {
22
27
  throw new Error(message);
23
28
  }
24
- function checkContract(contract) {
25
- if (!contract || contract.schema !== "godprompt.work_contract.v1" ||
26
- !/^sha256:[a-f0-9]{64}$/.test(contract.contract_id || "") ||
27
- !Array.isArray(contract.verification_commands) ||
28
- !Array.isArray(contract.allowed_paths) ||
29
- !Array.isArray(contract.success_criteria)) fail("Expected a complete v1 GodPrompt contract");
30
- return contract;
31
- }
32
29
  export async function readSmallJson(filename) {
33
30
  const bytes = await readFile(filename);
34
31
  if (bytes.length > MAX_JSON_BYTES) fail("Input JSON exceeds the 256 KiB limit");
@@ -85,7 +82,7 @@ async function githubJson(url, fetchImpl) {
85
82
  }
86
83
  export async function githubEvidence({ repo, sha, contract, mapping = {}, pr = null, fetchImpl = fetch }) {
87
84
  validateRepo(repo, sha);
88
- checkContract(contract);
85
+ validateWorkContractEnvelope(contract);
89
86
  if (!mapping || typeof mapping !== "object" || Array.isArray(mapping)) fail("Expected a VC-ID-to-check-name JSON map");
90
87
  const base = "https://api.github.com/repos/" + repo;
91
88
  const gaps = [];
@@ -218,53 +215,6 @@ export async function githubSnapshotEvidence({ repo, sha, contract, mapping = {}
218
215
  bundle.gaps.push("CONNECTOR_SNAPSHOT_PROVENANCE_NOT_AUTHENTICATED");
219
216
  return bundle;
220
217
  }
221
- export function codexifyEvidence({ contract, exportData }) {
222
- checkContract(contract);
223
- if (!exportData || typeof exportData !== "object" || Array.isArray(exportData)) fail("Codexify export must be an object");
224
- const rawFiles = exportData.changed_files;
225
- if (!Array.isArray(rawFiles) || rawFiles.length > 150 || rawFiles.some((v) => typeof v !== "string")) {
226
- fail("Codexify export needs a bounded changed_files array");
227
- }
228
- const rawChecks = exportData.checks;
229
- if (!Array.isArray(rawChecks) || rawChecks.length > 100) fail("Codexify export needs a bounded checks array");
230
- const gaps = [];
231
- const checks = rawChecks.map((receipt) => {
232
- if (!receipt || typeof receipt !== "object" || typeof receipt.id !== "string" || typeof receipt.command !== "string") {
233
- fail("Malformed Codexify receipt");
234
- }
235
- // Only a pasted structured exec_command envelope is attributed to tool output.
236
- // An ordinary claimed numeric exit_code is never promoted to tool provenance.
237
- const result = receipt.tool === "mcp__God_v5__exec_command" &&
238
- receipt.response && typeof receipt.response === "object" ? receipt.response.upstream_result : null;
239
- const code = Number.isInteger(result?.exit_code) && result.exit_code >= 0 ? result.exit_code : null;
240
- const attributed = code !== null;
241
- if (!attributed) gaps.push("NO_STRUCTURED_CODEXIFY_RECEIPT:" + receipt.id);
242
- return {
243
- id: receipt.id,
244
- command: receipt.command,
245
- exit_code: code,
246
- source: attributed ? "tool_output" : "self_report",
247
- evidence_excerpt: attributed
248
- ? "Codexify exec_command exported envelope: exit_code=" + code + "; result_sha256=" + sha256(JSON.stringify(result)).slice(0, 16) + "; raw output withheld."
249
- : "No structured Codexify exec_command tool result; self-report only.",
250
- };
251
- });
252
- for (const required of contract.verification_commands) {
253
- if (!checks.some((c) => c.id === required.id)) gaps.push("VERIFICATION_MISSING:" + required.id);
254
- }
255
- gaps.push("CHANGED_FILE_LIST_IS_CALLER_SUPPLIED");
256
- gaps.push("ACCEPTANCE_REQUIRES_INDEPENDENT_EVIDENCE");
257
- const bundle = makeBundle("codexify_receipts", contract, rawFiles, checks, gaps, {
258
- provider: "codexify_export",
259
- claimed_receipts: checks.length,
260
- });
261
- if (Array.isArray(exportData.operations_performed) &&
262
- exportData.operations_performed.length <= 100 &&
263
- exportData.operations_performed.every((v) => typeof v === "string" && v.length <= 500)) {
264
- bundle.review_input.operations_performed = exportData.operations_performed;
265
- }
266
- return bundle;
267
- }
268
218
  function filePath(env = process.env) {
269
219
  if (env.GODPROMPT_FEEDBACK_FILE) {
270
220
  if (!isAbsolute(env.GODPROMPT_FEEDBACK_FILE)) fail("GODPROMPT_FEEDBACK_FILE must be an absolute path");
@@ -573,7 +523,7 @@ export async function cli(argv = process.argv.slice(2)) {
573
523
  return githubEvidence({
574
524
  repo: opts.repo,
575
525
  sha: opts.sha,
576
- contract: checkContract(await readSmallJson(opts.contract)),
526
+ contract: validateWorkContractEnvelope(await readSmallJson(opts.contract)),
577
527
  mapping: opts.map ? await readSmallJson(opts.map) : {},
578
528
  pr: opts.pr ? Number(opts.pr) : null,
579
529
  });
@@ -583,7 +533,7 @@ export async function cli(argv = process.argv.slice(2)) {
583
533
  return githubSnapshotEvidence({
584
534
  repo: opts.repo,
585
535
  sha: opts.sha,
586
- contract: checkContract(await readSmallJson(opts.contract)),
536
+ contract: validateWorkContractEnvelope(await readSmallJson(opts.contract)),
587
537
  mapping: opts.map ? await readSmallJson(opts.map) : {},
588
538
  pr: opts.pr ? Number(opts.pr) : null,
589
539
  snapshot: await readSmallJson(opts.snapshot),
@@ -592,7 +542,7 @@ export async function cli(argv = process.argv.slice(2)) {
592
542
  if (command === "codexify") {
593
543
  if (!opts.contract || !opts.export) fail("codexify requires --contract --export");
594
544
  return codexifyEvidence({
595
- contract: checkContract(await readSmallJson(opts.contract)),
545
+ contract: validateWorkContractEnvelope(await readSmallJson(opts.contract)),
596
546
  exportData: await readSmallJson(opts.export),
597
547
  });
598
548
  }
@@ -622,7 +572,24 @@ export async function cli(argv = process.argv.slice(2)) {
622
572
  if (!opts.project) fail("lessons requires --project");
623
573
  return localLessons(opts.project);
624
574
  }
625
- const invokedAsScript = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
575
+ // npm's Windows launcher can invoke through an nvm/NTFS symlink while Node
576
+ // canonicalizes import.meta.url. Compare physical paths so the CLI actually
577
+ // runs instead of silently exiting 0 from its module-import guard.
578
+ async function isDirectInvocation() {
579
+ if (!process.argv[1]) return false;
580
+ try {
581
+ const [entry, modulePath] = await Promise.all([
582
+ realpath(resolve(process.argv[1])),
583
+ realpath(fileURLToPath(import.meta.url)),
584
+ ]);
585
+ return process.platform === "win32"
586
+ ? entry.toLowerCase() === modulePath.toLowerCase()
587
+ : entry === modulePath;
588
+ } catch {
589
+ return false;
590
+ }
591
+ }
592
+ const invokedAsScript = await isDirectInvocation();
626
593
  if (invokedAsScript) {
627
594
  cli().then((result) => {
628
595
  process.stdout.write((typeof result === "string" ? result : JSON.stringify(result, null, 2)) + "\n");
@@ -0,0 +1,220 @@
1
+ import * as z from "zod/v4";
2
+ import { codexifyEvidence } from "./codexify-evidence.js";
3
+ import { reviewWorkEvidence } from "./work-contract.js";
4
+ /**
5
+ * The single phase-aware checkpoint engine for local GodPrompt and the legacy
6
+ * Codexify pilot. The public Worker never imports or registers this module.
7
+ */
8
+ const STAGES = ["plan", "implementation", "verification", "handoff"];
9
+ const STAGE_SET = new Set(STAGES);
10
+ const SUMMARY_STATUSES = new Set([
11
+ "CONTINUE_WITH_PENDING_ITEMS", "RECHECK", "HOLD",
12
+ "REPORTED_READY_FOR_INDEPENDENT_REVIEW",
13
+ ]);
14
+ const DEFERRED_BEFORE_CHECKS = new Set([
15
+ "MISSING_VERIFICATION", "ACCEPTANCE_NOT_MET",
16
+ "ACCEPTANCE_EVIDENCE_MISSING", "REVIEW_REQUIRED",
17
+ ]);
18
+ const DEFERRED_UNTIL_HANDOFF = new Set([
19
+ "ACCEPTANCE_NOT_MET", "ACCEPTANCE_EVIDENCE_MISSING", "REVIEW_REQUIRED",
20
+ ]);
21
+ const GUIDANCE = Object.freeze({
22
+ CONTRACT_DRIFT: "Restore the original task contract and review any approved change.",
23
+ TASK_TYPE_UNCLASSIFIED: "Classify the task before implementation.",
24
+ SCOPE_UNDEFINED: "Define the exact allowed paths.",
25
+ ACCEPTANCE_UNDEFINED: "Define observable acceptance criteria.",
26
+ VERIFICATION_UNDEFINED: "Specify the real commands that must run.",
27
+ DUPLICATE_SCOPE_PATH: "Remove duplicate allowed scope entries.",
28
+ DUPLICATE_VERIFICATION: "Remove duplicate verification commands.",
29
+ INVALID_CHANGED_PATH: "Recheck the changed-file list for unsafe relative paths.",
30
+ OUT_OF_SCOPE_CHANGE: "Inspect the diff and reconcile files outside the approved scope.",
31
+ PROHIBITED_ACTION_REPORTED: "Inspect the operation record and stop prohibited actions.",
32
+ DUPLICATE_CHECK_RECEIPT: "Deduplicate reported check receipts.",
33
+ DUPLICATE_ACCEPTANCE_RECEIPT: "Deduplicate reported acceptance records.",
34
+ DUPLICATE_OBSERVATION: "Deduplicate reported observations.",
35
+ UNEXPECTED_CHECK_RECEIPT: "Reconcile the check ID with the task contract.",
36
+ UNEXPECTED_ACCEPTANCE_RECEIPT: "Reconcile the criterion ID with the task contract.",
37
+ MISSING_VERIFICATION: "Run the required verification and capture its real structured receipt.",
38
+ COMMAND_MISMATCH: "Re-run the exact contracted verification command.",
39
+ VERIFICATION_FAILED: "Fix the failure, then re-run the contracted verification.",
40
+ SELF_REPORTED_CHECK: "Provide actual structured tool output instead of a self-report.",
41
+ EVIDENCE_EXCERPT_MISSING: "Capture a bounded, redacted summary of the verification output.",
42
+ HOST_AUDIT_MISSING_OR_MISMATCH: "Check local host audit availability, exact command, conversation/project scope and tool exit event. Never replace it with a pasted success claim.",
43
+ ACCEPTANCE_NOT_MET: "Check each acceptance criterion and record its result.",
44
+ ACCEPTANCE_EVIDENCE_MISSING: "Link the acceptance claim to supplied check or observation evidence.",
45
+ REVIEW_REQUIRED: "Obtain separately authorized human review for high-risk work.",
46
+ });
47
+ const inputSchema = z.object({
48
+ stage: z.enum(STAGES),
49
+ contract: z.record(z.string(), z.unknown()),
50
+ codexify_export: z.object({
51
+ changed_files: z.array(z.string().max(240)).max(150),
52
+ operations_performed: z.array(z.string().max(500)).max(100).optional(),
53
+ checks: z.array(z.unknown()).max(100),
54
+ }).strict(),
55
+ acceptance: z.array(z.unknown()).max(100).optional(),
56
+ observations: z.array(z.unknown()).max(100).optional(),
57
+ human_review_reported: z.boolean().optional(),
58
+ }).strict();
59
+ export const CODEXIFY_CHECKPOINT_INSTRUCTIONS = "LOCAL OPT-IN ONLY: use create_work_contract before authorized edits, then deliberately call review_codexify_checkpoint at plan, after implementation, after verification, and before handoff. " +
60
+ "Also treat a Codexify rollout_checkpoint_required notice as a reminder trigger: fulfill the host-required rollout_update first, then review the current contract and available redacted evidence with review_codexify_checkpoint before resuming substantive work. Never fabricate missing receipts or a missing contract. " +
61
+ "For codexify_export.checks, pass real Codexify host envelopes: {id, command, tool:'mcp__God_v5__exec_command', response:{upstream_result:{exit_code:0}}}; never copy flat review_work_evidence receipts into this adapter. " +
62
+ "For optional host audit correlation, a locally configured audit source and conversation/project scope must match the host's start, worker-exit and finish events; caller-pasted success cannot replace a missing audit match. " +
63
+ "The separate opt-in audit observer can initiate advisory reviews on host activity, but cannot interrupt or authorize actions. RECHECK means reconcile and repeat; HOLD means do not report ready. Missing evidence may be pending only before its due stage. The tool is advisory, not a host interrupt or an approval mechanism. Never infer permission to merge, deploy, spend, publish or claim independently verified completion.";
64
+ function uniqueHints(issues) {
65
+ const seen = new Set();
66
+ const hints = [];
67
+ for (const issue of issues) {
68
+ const code = issue.code;
69
+ if (!/^[A-Z_]{3,64}$/.test(code)) {
70
+ throw new Error("Reviewer returned an unexpected issue code");
71
+ }
72
+ if (seen.has(code))
73
+ continue;
74
+ seen.add(code);
75
+ hints.push({
76
+ code,
77
+ next_action: GUIDANCE[code] ?? "Review this unrecognized issue before continuing.",
78
+ });
79
+ }
80
+ return hints;
81
+ }
82
+ export function cloudSafeCheckpointSummary(result) {
83
+ if (!result || !STAGE_SET.has(result.stage) || !SUMMARY_STATUSES.has(result.status) ||
84
+ !Array.isArray(result.recheck) || !Array.isArray(result.pending) ||
85
+ result.recheck.length > 100 || result.pending.length > 100) {
86
+ throw new Error("Invalid checkpoint summary");
87
+ }
88
+ const codes = (items) => items.map(({ code }) => {
89
+ if (typeof code !== "string" || !Object.hasOwn(GUIDANCE, code)) {
90
+ throw new Error("Unknown issue code cannot cross the storage boundary");
91
+ }
92
+ return code;
93
+ });
94
+ const numeric = (key) => {
95
+ const value = result.counts?.[key];
96
+ if (!Number.isInteger(value) || value < 0 || value > 100) {
97
+ throw new Error("Invalid checkpoint count");
98
+ }
99
+ return value;
100
+ };
101
+ return {
102
+ schema: "godprompt.checkpoint_summary.v1",
103
+ stage: result.stage,
104
+ status: result.status,
105
+ recheck_codes: codes(result.recheck),
106
+ pending_codes: codes(result.pending),
107
+ counts: {
108
+ required_checks: numeric("required_checks"),
109
+ supplied_checks: numeric("supplied_checks"),
110
+ required_criteria: numeric("required_criteria"),
111
+ supplied_criteria: numeric("supplied_criteria"),
112
+ },
113
+ independently_verified: false,
114
+ completion_authorized: false,
115
+ };
116
+ }
117
+ export async function evaluateCheckpoint(raw) {
118
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
119
+ throw new Error("Checkpoint input must be one JSON object");
120
+ }
121
+ const allowed = new Set([
122
+ "stage", "contract", "codexify_export", "acceptance",
123
+ "observations", "human_review_reported",
124
+ ]);
125
+ if (Object.keys(raw).some((key) => !allowed.has(key))) {
126
+ throw new Error("Unexpected checkpoint field; only known review inputs are accepted");
127
+ }
128
+ if (!STAGE_SET.has(raw.stage ?? "")) {
129
+ throw new Error("stage must be plan, implementation, verification or handoff");
130
+ }
131
+ const input = inputSchema.parse(raw);
132
+ const bundle = await codexifyEvidence({
133
+ contract: input.contract,
134
+ exportData: input.codexify_export,
135
+ });
136
+ const reviewerArgs = {
137
+ ...bundle.review_input,
138
+ acceptance: (input.acceptance ?? []),
139
+ observations: (input.observations ?? []),
140
+ human_review_reported: input.human_review_reported === true,
141
+ };
142
+ const review = await reviewWorkEvidence(reviewerArgs);
143
+ const defer = input.stage === "plan" || input.stage === "implementation"
144
+ ? DEFERRED_BEFORE_CHECKS
145
+ : input.stage === "verification" ? DEFERRED_UNTIL_HANDOFF : new Set();
146
+ const hostAuditIssues = bundle.gaps.some((gap) => gap.startsWith("HOST_AUDIT_MISSING_OR_MISMATCH:"))
147
+ ? [{ code: "HOST_AUDIT_MISSING_OR_MISMATCH" }] : [];
148
+ const recheck = uniqueHints([
149
+ ...review.issues.filter(({ code }) => !defer.has(code)),
150
+ ...hostAuditIssues,
151
+ ]);
152
+ const pending = uniqueHints(review.issues.filter(({ code }) => defer.has(code)));
153
+ const status = recheck.length
154
+ ? (input.stage === "handoff" ? "HOLD" : "RECHECK")
155
+ : input.stage === "handoff"
156
+ ? (review.status === "REPORTED_READY_FOR_INDEPENDENT_REVIEW"
157
+ ? "REPORTED_READY_FOR_INDEPENDENT_REVIEW" : "HOLD")
158
+ : "CONTINUE_WITH_PENDING_ITEMS";
159
+ return {
160
+ schema: "godprompt.codexify_checkpoint_preview.v1",
161
+ stage: input.stage,
162
+ status,
163
+ recheck,
164
+ pending,
165
+ counts: {
166
+ required_checks: review.required_checks,
167
+ supplied_checks: review.supplied_check_receipts,
168
+ required_criteria: review.required_acceptance_criteria,
169
+ supplied_criteria: review.supplied_acceptance_receipts,
170
+ },
171
+ independently_verified: false,
172
+ completion_authorized: false,
173
+ next_step: recheck.length
174
+ ? "Review the issues and repeat this checkpoint after the missing work is corrected."
175
+ : input.stage === "handoff"
176
+ ? "Inspect original source output, diff, checks and approvals independently before claiming completion."
177
+ : "Continue only with separately authorized work; rerun at the next checkpoint.",
178
+ warning: "All exports and acceptance reports are caller-supplied. This tool cannot interrupt Codexify automatically and never permits deployment or completion.",
179
+ };
180
+ }
181
+ export function registerCodexifyCheckpointTool(server) {
182
+ server.registerTool("review_codexify_checkpoint", {
183
+ title: "Review Codexify task checkpoint",
184
+ description: "Local opt-in, read-only milestone review. At plan, implementation, verification and handoff, check reported contract, scope, tool errors, verification and acceptance. Unlike review_work_evidence, codexify_export.checks[] requires a real host envelope: {id:'VC-01', command:'the exact contracted command', tool:'mcp__God_v5__exec_command', response:{upstream_result:{exit_code:0,output:'...'}}}. The response.upstream_result.exit_code is read from the actual Codexify call; a flat exit_code/source/evidence_excerpt receipt is NOT sufficient. Optional checks[].host_audit_ref can correlate exact execution events against an owner-configured local Codexify audit file and pinned conversation/project scope, failing closed on missing matches. This is not an execution permission, signed attestation or independent proof.",
185
+ // The SDK echoes Zod validation errors, including unexpected field names.
186
+ // Preserve the detailed public schema, but hand invalid input to our
187
+ // redacted error handler instead of letting the SDK echo private data.
188
+ inputSchema: inputSchema.catch(() => ({
189
+ stage: "plan", contract: {}, codexify_export: { changed_files: [], checks: [] },
190
+ })),
191
+ annotations: {
192
+ readOnlyHint: true, destructiveHint: false,
193
+ idempotentHint: true, openWorldHint: false,
194
+ },
195
+ }, async (args) => {
196
+ if (new TextEncoder().encode(JSON.stringify(args)).byteLength > 256 * 1024) {
197
+ return {
198
+ isError: true,
199
+ content: [{ type: "text",
200
+ text: "Checkpoint input exceeds 256 KiB. Supply redacted, bounded receipts." }],
201
+ };
202
+ }
203
+ try {
204
+ const result = await evaluateCheckpoint(args);
205
+ const cloud_storage_preview = cloudSafeCheckpointSummary(result);
206
+ const safe = { ...result, cloud_storage_preview };
207
+ return {
208
+ structuredContent: safe,
209
+ content: [{ type: "text", text: JSON.stringify(safe) }],
210
+ };
211
+ }
212
+ catch {
213
+ return {
214
+ isError: true,
215
+ content: [{ type: "text",
216
+ text: "Invalid checkpoint input; inspect the contract schema and redacted export locally." }],
217
+ };
218
+ }
219
+ });
220
+ }