god-prompt-mcp 1.1.1 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -27,9 +27,19 @@ 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
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
 
41
+ **Version 1.2.1:** All seventeen public MCP tools are available, including the eight engineering-quality functions introduced in v1.2.0. This patch refines code-review signal precision, requirement-conflict detection and duplicate CI-check blocking without adding permissions or storage. 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
+
33
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.
@@ -42,7 +52,7 @@ GitHub can be read directly or from a **sanitized snapshot produced with an exis
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
 
@@ -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.1"
302
+ droid mcp add god-prompt "npx -y god-prompt-mcp@1.2.1"
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.1. 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.1"
328
+ goose session --with-extension "npx -y god-prompt-mcp@1.2.1"
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.1. 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.1"]
393
+ "args": ["-y", "god-prompt-mcp@1.2.1"]
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.1. 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.1
412
+ openclaw mcp add god-prompt --command npx --arg -y --arg god-prompt-mcp@1.2.1
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.1. 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.1"]
433
+ "args": ["-y", "god-prompt-mcp@1.2.1"]
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.1. 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.1. 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.1` as a local stdio MCP server, including the nine tools available in v1.1.1. 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.1` 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.1. Node.js 22+ is required for the MCP server.
502
512
 
503
513
  ### Cursor
504
514
 
@@ -9,8 +9,13 @@ 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
  }
@@ -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
+ }
@@ -0,0 +1,149 @@
1
+ export const CODEXIFY_BUNDLE_SCHEMA = "godprompt.evidence_bundle.v1";
2
+ function record(value) {
3
+ return value !== null && typeof value === "object" && !Array.isArray(value)
4
+ ? value : null;
5
+ }
6
+ export function validateWorkContractEnvelope(contract) {
7
+ const data = record(contract);
8
+ if (data?.schema !== "godprompt.work_contract.v1" ||
9
+ typeof data.contract_id !== "string" ||
10
+ !/^sha256:[a-f0-9]{64}$/.test(data.contract_id) ||
11
+ !Array.isArray(data.verification_commands) ||
12
+ !Array.isArray(data.allowed_paths) ||
13
+ !Array.isArray(data.success_criteria)) {
14
+ throw new Error("Expected a complete v1 GodPrompt contract");
15
+ }
16
+ return contract;
17
+ }
18
+ async function digestShort(data) {
19
+ const payload = new TextEncoder().encode(JSON.stringify(data));
20
+ const digest = await crypto.subtle.digest("SHA-256", payload);
21
+ return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, 16);
22
+ }
23
+ function hasToolError(receipt, response, result) {
24
+ // MCP errors must override misleading nested exit_code:0 values.
25
+ // Treat malformed error flags and explicit failure statuses conservatively.
26
+ // A present JSON-RPC error object is a failure even without isError.
27
+ const nested = record(result?.upstream_result);
28
+ return [receipt, response, result, nested,
29
+ record(response?.structuredContent), record(result?.structuredContent)].some((data) => data !== null && ((Object.hasOwn(data, "isError") && data.isError !== false) ||
30
+ (Object.hasOwn(data, "success") && data.success !== true) ||
31
+ (typeof data.status === "string" &&
32
+ /^(error|failed|failure|cancelled|canceled|timeout|timed_out|aborted|interrupted|rejected|pending|running)$/i.test(data.status.trim())) ||
33
+ (data.error !== undefined && data.error !== null)));
34
+ }
35
+ export async function codexifyEvidence({ contract, exportData, }) {
36
+ validateWorkContractEnvelope(contract);
37
+ const source = record(exportData);
38
+ if (!source)
39
+ throw new Error("Codexify export must be an object");
40
+ const changedFiles = source.changed_files;
41
+ if (!Array.isArray(changedFiles) || changedFiles.length > 150 ||
42
+ changedFiles.some((value) => typeof value !== "string")) {
43
+ throw new Error("Codexify export needs a bounded changed_files array");
44
+ }
45
+ const rawChecks = source.checks;
46
+ if (!Array.isArray(rawChecks) || rawChecks.length > 100) {
47
+ throw new Error("Codexify export needs a bounded checks array");
48
+ }
49
+ const receipts = rawChecks.map((raw) => {
50
+ const receipt = record(raw);
51
+ if (!receipt || typeof receipt.id !== "string" ||
52
+ typeof receipt.command !== "string") {
53
+ throw new Error("Malformed Codexify receipt");
54
+ }
55
+ return receipt;
56
+ });
57
+ const hostIndices = receipts.flatMap((receipt, index) => Object.hasOwn(receipt, "host_audit_ref") ? [index] : []);
58
+ const hostMatches = new Map();
59
+ if (hostIndices.length > 0) {
60
+ const path = process.env.GODPROMPT_CODEXIFY_AUDIT_FILE;
61
+ const conversation_id = process.env.GODPROMPT_CODEXIFY_AUDIT_CONVERSATION_ID;
62
+ const project_id = process.env.GODPROMPT_CODEXIFY_AUDIT_PROJECT_ID;
63
+ if (path && conversation_id && project_id) {
64
+ const { correlateCodexifyAuditBatch } = await import("./codexify-host-audit.js");
65
+ const matched = await correlateCodexifyAuditBatch({
66
+ path, conversation_id, project_id,
67
+ not_before: process.env.GODPROMPT_CODEXIFY_AUDIT_NOT_BEFORE,
68
+ checks: hostIndices.map((index) => ({
69
+ ref: receipts[index].host_audit_ref,
70
+ expected_command: receipts[index].command,
71
+ })),
72
+ });
73
+ hostIndices.forEach((index, i) => hostMatches.set(index, matched[i] ?? null));
74
+ }
75
+ }
76
+ const gaps = [];
77
+ const checks = await Promise.all(receipts.map(async (receipt, index) => {
78
+ const response = record(receipt.response);
79
+ const result = record(response?.upstream_result);
80
+ const hostAuditRequested = Object.hasOwn(receipt, "host_audit_ref");
81
+ const hostAudit = hostAuditRequested ? hostMatches.get(index) ?? null : null;
82
+ // Never fall back to a caller-pasted success envelope if an explicit
83
+ // host-audit reference is absent, incomplete, stale, or mismatched.
84
+ // A host-linked command is still suspect when the enclosing MCP result
85
+ // explicitly reports an error (or names a different tool). Fail closed
86
+ // rather than letting a valid audit ID mask contradictory input.
87
+ // Error flags are expected for a genuine host-observed nonzero process
88
+ // exit: preserve its exit code for VERIFICATION_FAILED. They remain
89
+ // contradictory and disqualifying when the host observed exit_code=0.
90
+ const hostReceiptError = (hostAudit?.exit_code === 0 &&
91
+ hasToolError(receipt, response, result)) ||
92
+ (receipt.tool !== undefined && receipt.tool !== "mcp__God_v5__exec_command");
93
+ const code = hostAuditRequested
94
+ ? hostReceiptError ? null : hostAudit?.exit_code ?? null :
95
+ receipt.tool === "mcp__God_v5__exec_command" &&
96
+ !hasToolError(receipt, response, result) &&
97
+ Number.isInteger(result?.exit_code) && Number(result?.exit_code) >= 0
98
+ ? Number(result?.exit_code) : null;
99
+ if (code === null)
100
+ gaps.push((hostAuditRequested ? "HOST_AUDIT_MISSING_OR_MISMATCH:" :
101
+ "NO_STRUCTURED_CODEXIFY_RECEIPT:") + receipt.id);
102
+ return {
103
+ id: receipt.id,
104
+ command: receipt.command,
105
+ exit_code: code,
106
+ source: code === null ? "self_report" : "tool_output",
107
+ evidence_excerpt: code === null
108
+ ? "No matching local host audit or successful Codexify command envelope."
109
+ : hostAuditRequested
110
+ ? "Local Codexify audit-correlated command: exit_code=" + code +
111
+ "; exact command and scoped host events matched; raw output withheld."
112
+ : "Codexify exec_command exported envelope: exit_code=" + code +
113
+ "; result_sha256=" + await digestShort(result) + "; raw output withheld.",
114
+ };
115
+ }));
116
+ for (const required of contract.verification_commands) {
117
+ if (!checks.some((entry) => entry.id === required.id)) {
118
+ gaps.push("VERIFICATION_MISSING:" + required.id);
119
+ }
120
+ }
121
+ gaps.push("CHANGED_FILE_LIST_IS_CALLER_SUPPLIED");
122
+ gaps.push("ACCEPTANCE_REQUIRES_INDEPENDENT_EVIDENCE");
123
+ const rawOperations = source.operations_performed;
124
+ if (rawOperations !== undefined &&
125
+ (!Array.isArray(rawOperations) || rawOperations.length > 100 ||
126
+ rawOperations.some((value) => typeof value !== "string" ||
127
+ value.trim().length < 3 || value.length > 500))) {
128
+ throw new Error("Codexify export needs a bounded operations_performed array");
129
+ }
130
+ const operations = rawOperations === undefined ? [] : rawOperations;
131
+ return {
132
+ schema: CODEXIFY_BUNDLE_SCHEMA,
133
+ adapter: "codexify_receipts",
134
+ provenance: { provider: "codexify_export", claimed_receipts: checks.length },
135
+ review_input: {
136
+ contract,
137
+ changed_files: changedFiles,
138
+ operations_performed: operations,
139
+ checks,
140
+ acceptance: [],
141
+ observations: [],
142
+ human_review_reported: false,
143
+ },
144
+ gaps: [...new Set(gaps)],
145
+ independently_verified: false,
146
+ completion_authorized: false,
147
+ warning: "Caller-supplied receipts are not authenticated execution proof. Diff, output, acceptance, and approvals require independent review. Do not send private evidence to the public MCP.",
148
+ };
149
+ }