@deksden-com/dd-flow-cli 0.8.0-beta.135 → 0.9.0-beta.0

package/dist/schemas/protocol-plan.schema.json

@@ -21,7 +21,7 @@
   },
   "definitions": {
     "semanticSpine": {"type": "object", "additionalProperties": false, "required": ["user_outcome", "component_responsibility", "must_preserve", "non_goals", "acceptance_contribution"], "properties": {"user_outcome": {"type": "string", "minLength": 1}, "component_responsibility": {"type": "string", "minLength": 1}, "must_preserve": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "non_goals": {"type": "array", "items": {"type": "string", "minLength": 1}}, "acceptance_contribution": {"type": "string", "minLength": 1}}},
-    "executionContext": {"type": "object", "additionalProperties": false, "required": ["prompt_profile", "required_read", "discovery_boundary", "write_scope", "checks"], "properties": {"prompt_profile": {"enum": ["documentation_contract", "code_implementation", "verification"]}, "required_read": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "discovery_boundary": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "write_scope": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "checks": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}}},
+    "executionContext": {"type": "object", "additionalProperties": false, "required": ["prompt_profile", "required_read", "discovery_boundary", "planned_write_areas", "checks"], "properties": {"prompt_profile": {"enum": ["documentation_contract", "code_implementation", "verification"]}, "required_read": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "discovery_boundary": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "planned_write_areas": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "Soft concurrent-work coordination hints, never a write allowlist."}, "checks": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}}},
     "verificationContract": {"type": "object", "additionalProperties": false, "required": ["checks", "evidence"], "properties": {"checks": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "evidence": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}}},
     "planItem": {"type": "object", "additionalProperties": false, "required": ["id", "kind", "title", "summary", "depends_on", "owner", "target_stage", "required", "requirements", "semantic_spine", "execution_context", "verification_contract"], "properties": {"id": {"type": "string", "pattern": "^P[0-9]+$"}, "kind": {"type": "string", "minLength": 1}, "title": {"type": "string", "minLength": 1}, "summary": {"type": "string", "minLength": 1}, "details": {"type": "string", "minLength": 1}, "depends_on": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^P[0-9]+$"}}, "owner": {"type": "string", "minLength": 1}, "target_stage": {"enum": ["specify", "plan", "code", "readiness", "merge", "release"]}, "required": {"type": "boolean"}, "requirements": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^SPC-[0-9]{3}@[0-9]+\\.[0-9]+\\.[0-9]+/R-[0-9]+$"}}, "semantic_spine": {"$ref": "#/definitions/semanticSpine"}, "execution_context": {"$ref": "#/definitions/executionContext"}, "verification_contract": {"$ref": "#/definitions/verificationContract"}}},
     "taskAssessment": {"type": "object", "additionalProperties": false, "required": ["scope_breadth", "solution_novelty", "solution_uncertainty", "failure_impact", "plan_floor"], "properties": {"scope_breadth": {"$ref": "#/definitions/assessmentAxis"}, "solution_novelty": {"$ref": "#/definitions/assessmentAxis"}, "solution_uncertainty": {"$ref": "#/definitions/assessmentAxis"}, "failure_impact": {"$ref": "#/definitions/assessmentAxis"}, "plan_floor": {"$ref": "#/definitions/assessmentAxis"}}},

package/dist/schemas/stage-start-response.schema.json

@@ -10,7 +10,7 @@
       "then": {"required": ["plan_ref", "aspect_map_ref"]}
     }
   ],
-  "required": ["schema_id", "run_id", "stage", "attempt_number", "stage_root", "prompt_path", "aliases", "next_command", "worker_prompt_markdown"],
+  "required": ["schema_id", "run_id", "stage", "attempt_number", "stage_root", "prompt_path", "aliases", "resolved_context", "preflight", "worker_prompt_markdown", "next_command"],
   "properties": {
     "schema_id": {"const": "dd-flow/stage-start-response@2"},
     "run_id": {"type": "string", "minLength": 1},
@@ -24,7 +24,9 @@
     "plan_ref": {"type": "string", "pattern": "^\\.memory-bank/protocol/[^/]+/plan\\.json$"},
     "aspect_map_ref": {"type": "string", "minLength": 1},
     "next_command": {"type": "string", "pattern": "^dd-flow stage finish "},
+    "preflight": {"type": "object", "required": ["git", "compatibility", "permissions", "session_binding"], "additionalProperties": true},
+    "worker_prompt_markdown": {"type": "string", "minLength": 1},
     "permission_probe": {"type": "object", "additionalProperties": true},
-    "worker_prompt_markdown": {"type": "string", "minLength": 1}
+    "bootstrap": {"type": "boolean"}
   }
 }

package/dist/schemas/status-report.schema.json

@@ -84,9 +84,85 @@
           }
         }
       }
+    },
+    "engine": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "properties": {
+        "contexts": { "$ref": "#/definitions/compatibilityContexts" }
+      }
     }
   },
   "definitions": {
+    "compatibilityContexts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["project_current", "upgrade_target", "effective_execution"],
+      "properties": {
+        "project_current": { "$ref": "#/definitions/projectCurrentContext" },
+        "upgrade_target": {
+          "anyOf": [
+            { "type": "null" },
+            { "$ref": "#/definitions/upgradeTargetContext" }
+          ]
+        },
+        "effective_execution": { "$ref": "#/definitions/effectiveExecutionContext" }
+      }
+    },
+    "projectCurrentContext": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["name", "canon", "memory_bank_version", "package_name", "required_engine_range", "resolution", "engine_version", "diagnostics"],
+      "properties": {
+        "name": { "const": "project_current" },
+        "canon": { "type": "object", "additionalProperties": true },
+        "memory_bank_version": { "type": ["string", "null"] },
+        "package_name": { "type": "string", "minLength": 1 },
+        "required_engine_range": { "type": ["string", "null"] },
+        "recommended_engine_version": { "type": ["string", "null"] },
+        "resolution": { "type": "string", "minLength": 1 },
+        "engine_version": { "type": ["string", "null"] },
+        "diagnostics": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "upgradeTargetContext": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["name", "canon", "memory_bank_version", "package_name", "required_engine_range", "resolution", "engine_version", "diagnostics"],
+      "properties": {
+        "name": { "const": "upgrade_target" },
+        "canon": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["root", "version", "commit", "compatibility_sha256"],
+          "properties": {
+            "root": { "type": "string", "minLength": 1 },
+            "version": { "type": "string", "minLength": 1 },
+            "commit": { "type": "string", "minLength": 1 },
+            "compatibility_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+          }
+        },
+        "memory_bank_version": { "type": ["string", "null"] },
+        "package_name": { "type": "string", "minLength": 1 },
+        "required_engine_range": { "type": ["string", "null"] },
+        "recommended_engine_version": { "type": ["string", "null"] },
+        "resolution": { "type": "string", "minLength": 1 },
+        "engine_version": { "type": ["string", "null"] },
+        "diagnostics": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "effectiveExecutionContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["operation", "mode", "package_name", "engine_version", "reason"],
+      "properties": {
+        "operation": { "type": "string", "minLength": 1 },
+        "mode": { "type": "string", "minLength": 1 },
+        "package_name": { "type": "string", "minLength": 1 },
+        "engine_version": { "type": ["string", "null"] },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
     "cliCompatibility": {
       "type": "object",
       "additionalProperties": true,

package/dist/schemas/vnext-protocol-plan.schema.json

@@ -1,12 +1,12 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "dd-flow/protocol-plan@5",
+  "$id": "dd-flow/protocol-plan@6",
   "title": "Semantic protocol implementation plan",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_id", "plan_id", "protocol_id", "revision", "title", "summary", "source_refs", "goal", "assessment", "decisions", "document_updates", "checks", "items", "acceptance"],
   "properties": {
-    "schema_id": {"const": "dd-flow/protocol-plan@5"},
+    "schema_id": {"const": "dd-flow/protocol-plan@6"},
     "plan_id": {"type": "string", "pattern": "^PLAN-[A-Za-z0-9][A-Za-z0-9._-]*$"},
     "protocol_id": {"type": "string", "pattern": "^PRT-[A-Za-z0-9][A-Za-z0-9._-]*$"},
     "revision": {"type": "integer", "minimum": 1},
@@ -28,8 +28,8 @@
     "decision": {"type": "object", "additionalProperties": false, "required": ["id", "decision", "rationale", "affected_surfaces"], "properties": {"id": {"type": "string", "minLength": 1}, "decision": {"type": "string", "minLength": 1}, "rationale": {"type": "string", "minLength": 1}, "affected_surfaces": {"$ref": "#/$defs/strings"}, "durable_ref": {"type": "string", "minLength": 1}}},
     "documentUpdate": {"type": "object", "additionalProperties": false, "required": ["path", "action", "owner", "reason"], "properties": {"path": {"type": "string", "minLength": 1}, "action": {"enum": ["create", "update"]}, "owner": {"type": "string", "minLength": 1}, "reason": {"type": "string", "minLength": 1}}},
     "spine": {"type": "object", "additionalProperties": false, "required": ["user_outcome", "component_responsibility", "must_preserve", "non_goals", "acceptance_contribution"], "properties": {"user_outcome": {"type": "string", "minLength": 1}, "component_responsibility": {"type": "string", "minLength": 1}, "must_preserve": {"$ref": "#/$defs/strings"}, "non_goals": {"type": "array", "items": {"type": "string", "minLength": 1}}, "acceptance_contribution": {"type": "string", "minLength": 1}}},
-    "execution": {"type": "object", "additionalProperties": false, "required": ["required_read", "discovery_boundary", "write_scope", "stop_conditions"], "properties": {"required_read": {"$ref": "#/$defs/strings"}, "discovery_boundary": {"$ref": "#/$defs/strings"}, "write_scope": {"$ref": "#/$defs/strings"}, "stop_conditions": {"$ref": "#/$defs/strings"}}},
-    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "pattern": "^P[0-9]+$"}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}]},
+    "execution": {"type": "object", "additionalProperties": false, "required": ["required_read", "discovery_boundary", "planned_write_areas", "stop_conditions"], "properties": {"required_read": {"$ref": "#/$defs/strings", "description": "Mandatory starting sources. This is not a read allowlist."}, "discovery_boundary": {"$ref": "#/$defs/strings", "description": "Likely discovery areas. A worker may inspect other project-local sources when necessary."}, "planned_write_areas": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "Optional file or directory hints used only to coordinate concurrent Works. They never grant or deny write permission."}, "stop_conditions": {"$ref": "#/$defs/strings", "description": "Semantic contradictions or external blockers that require the worker to stop."}}},
+    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "pattern": "^P[0-9]+$"}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}, {"if": {"properties": {"command": {"pattern": "^@check/"}}}, "then": {"required": ["definition"]}}]},
     "verification": {"type": "object", "additionalProperties": false, "required": ["check_refs"], "properties": {"check_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}}}},
     "item": {"type": "object", "additionalProperties": false, "required": ["id", "title", "summary", "details", "depends_on", "requirement_refs", "semantic_spine", "execution_context", "verification"], "properties": {"id": {"type": "string", "pattern": "^P[0-9]+$"}, "title": {"type": "string", "minLength": 1}, "summary": {"type": "string", "minLength": 1}, "details": {"type": "string", "minLength": 1}, "depends_on": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^P[0-9]+$"}}, "requirement_refs": {"$ref": "#/$defs/strings"}, "semantic_spine": {"$ref": "#/$defs/spine"}, "execution_context": {"$ref": "#/$defs/execution"}, "verification": {"$ref": "#/$defs/verification"}}},
     "acceptance": {"type": "object", "additionalProperties": false, "required": ["criterion_id", "plan_item_ids", "changed_surfaces", "path", "environment", "fixtures", "cleanup", "check_refs", "expected_evidence", "proof_limits", "gate"], "properties": {"criterion_id": {"type": "string", "pattern": "^AC-[0-9]+$"}, "plan_item_ids": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "^P[0-9]+$"}}, "changed_surfaces": {"$ref": "#/$defs/strings"}, "path": {"type": "string", "minLength": 1}, "environment": {"type": "string", "minLength": 1}, "fixtures": {"type": "array", "items": {"type": "string", "minLength": 1}}, "cleanup": {"type": "string", "minLength": 1}, "check_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}}, "expected_evidence": {"$ref": "#/$defs/strings"}, "proof_limits": {"$ref": "#/$defs/strings"}, "gate": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}}}

package/dist/services/cli-operation-classifier.js

@@ -133,7 +133,7 @@ function isReadOnlyDiagnostic(family, command, action) {
             (command === "workspace" && action === "check"));
     }
     if (family === "merge")
-        return command === "status";
+        return command === "status" || (command === "request" && action === "status") || (command === "server" && action === "status");
     if (family === "merge-worker")
         return command === "status";
     if (family === "merge-queue")

package/dist/services/code-checks.js

@@ -3,242 +3,159 @@ import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-/**
- * A local CODE gate must not share a mutable database with another checkout.
- * The project command consumes this opaque suffix only for its local/test
- * database target; preview and production-like targets remain unchanged.
- */
-export function codeExecutionEnvironment(workspaceRoot) {
-    const suffix = crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex").slice(0, 12);
-    return { ...process.env, DD_FLOW_LOCAL_DATABASE_SUFFIX: suffix };
+const profileRelativePath = path.join(".memory-bank", "spec", "engineering", "code-check-profile.json");
+export function codeExecutionEnvironment(workspaceRoot) { const suffix = crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex").slice(0, 12); return { ...process.env, DD_FLOW_LOCAL_DATABASE_SUFFIX: suffix }; }
+export function readCodeCheckProfile(workspaceRoot) {
+    const file = path.join(workspaceRoot, profileRelativePath);
+    if (!fs.existsSync(file))
+        return { profile: null, hash: null, file };
+    const bytes = fs.readFileSync(file);
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (value.schema_id !== "dd-flow/code-check-profile@5")
+        throw new AppError("invalid_code_check_profile", "CODE check profile has an unsupported schema", 2, { file, schema_id: value.schema_id ?? null, required: "dd-flow/code-check-profile@5" });
+    if (!isStringRecord(value.aliases) || !isStringRecord(value.require_alias_for) || !isGateRecord(value.mandatory_by_gate))
+        throw new AppError("invalid_code_check_profile", "CODE check profile aliases, require_alias_for and mandatory_by_gate are invalid", 2, { file });
+    for (const [gate, aliases] of Object.entries(value.mandatory_by_gate))
+        for (const alias of aliases ?? [])
+            if (!value.aliases[alias])
+                throw new AppError("invalid_code_check_profile", "A mandatory gate references an unknown alias", 2, { file, gate, alias });
+    return { profile: value, hash: crypto.createHash("sha256").update(bytes).digest("hex"), file };
 }
 export function validateCodeCheckCommands(workspaceRoot, commands) {
-    const file = path.join(workspaceRoot, ".memory-bank", "spec", "engineering", "code-check-profile.json");
-    // Keep one resolved command for every declared check. Two declarations may
-    // deliberately share a command while carrying different acceptance roles.
-    if (!fs.existsSync(file))
+    const { profile, file } = readCodeCheckProfile(workspaceRoot);
+    if (!profile)
         return [...commands];
-    const profile = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (profile.schema_id !== "dd-flow/code-check-profile@4")
-        throw new AppError("invalid_code_check_profile", "CODE check profile has an unsupported schema", 2, { file, schema_id: profile.schema_id ?? null });
-    const aliases = profile.aliases && typeof profile.aliases === "object" && !Array.isArray(profile.aliases)
-        ? profile.aliases
-        : {};
-    const required = profile.require_alias_for && typeof profile.require_alias_for === "object" && !Array.isArray(profile.require_alias_for)
-        ? profile.require_alias_for
-        : {};
-    return commands.map((command) => {
-        if (command.startsWith("@check/")) {
-            const template = aliases[command];
-            if (typeof template !== "string" || !template.trim())
-                throw new AppError("unknown_code_check_alias", "CODE check alias is not defined by the project profile", 2, { alias: command, file });
-            return command;
-        }
-        for (const [prefix, alias] of Object.entries(required)) {
-            if (command === prefix || command.startsWith(`${prefix} `)) {
-                throw new AppError("raw_code_check_forbidden", "CODE check must use the project alias instead of a raw guarded command", 2, { command, required_alias: String(alias), file });
-            }
-        }
+    return commands.map((command) => { if (command.startsWith("@check/")) {
+        if (!profile.aliases[command]?.trim())
+            throw new AppError("unknown_code_check_alias", "CODE check alias is not defined by the project profile", 2, { alias: command, file });
         return command;
-    });
-}
-export function resolveCodeCheckCommands(workspaceRoot, runId, commands) {
-    const validated = validateCodeCheckCommands(workspaceRoot, commands);
-    const file = path.join(workspaceRoot, ".memory-bank", "spec", "engineering", "code-check-profile.json");
-    if (!fs.existsSync(file))
-        return validated;
-    const profile = JSON.parse(fs.readFileSync(file, "utf8"));
-    const aliases = profile.aliases && typeof profile.aliases === "object" && !Array.isArray(profile.aliases)
-        ? profile.aliases
-        : {};
-    return validated.map((command) => command.startsWith("@check/")
-        ? String(aliases[command]).replaceAll("{run_id}", runId)
-        : command);
+    } for (const [prefix, alias] of Object.entries(profile.require_alias_for))
+        if (command === prefix || command.startsWith(`${prefix} `))
+            throw new AppError("raw_code_check_forbidden", "CODE check must use the project alias instead of a raw guarded command", 2, { command, required_alias: alias, file }); return command; });
+}
+export function resolveCodeCheckCommands(workspaceRoot, runId, commands) { const validated = validateCodeCheckCommands(workspaceRoot, commands); const { profile } = readCodeCheckProfile(workspaceRoot); return validated.map((command) => command.startsWith("@check/") ? profile.aliases[command].replaceAll("{run_id}", runId) : command); }
+export function projectPolicyCheckDeclarations(workspaceRoot, gate) {
+    const { profile } = readCodeCheckProfile(workspaceRoot);
+    return (profile?.mandatory_by_gate[gate] ?? []).map((alias) => { const ref = `POLICY/${gate}/${alias.slice(7).replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase()}`; return { id: ref, canonical_ref: ref, source: "project_policy", command: alias, purpose: `Mandatory project ${gate} gate.`, run_at: gate, availability: "available" }; });
+}
+export function effectiveCheckDeclarations(workspaceRoot, declared, gates) { return gates.flatMap((gate) => [...declared.filter((check) => check.run_at === gate), ...projectPolicyCheckDeclarations(workspaceRoot, gate)]); }
+export function aggregateCheckDeclarations(workspaceRoot) { return projectPolicyCheckDeclarations(workspaceRoot, "code"); }
+export function finalCodeCheckDeclarations(workspaceRoot, declared) { return effectiveCheckDeclarations(workspaceRoot, declared, ["code", "readiness"]); }
+export function checksForRunAt(checks, runAt) { return checks.filter((check) => check.run_at === runAt); }
+export function validateCheckPlacement(workspaceRoot, checks) { const { profile } = readCodeCheckProfile(workspaceRoot); const aggregateCommands = new Set(projectPolicyCheckDeclarations(workspaceRoot, "code").flatMap((check) => [check.command, profile?.aliases[check.command] ?? check.command])); for (const check of checks)
+    if (check.run_at === "work" && aggregateCommands.has(check.command))
+        throw new AppError("aggregate_check_requires_code_gate", "A project aggregate check must run at CODE or readiness, not inside one scoped Work", 2, { check_id: check.id, command: check.command, run_at: check.run_at }); }
+export function validateCheckDeclaration(workspaceRoot, check) {
+    if (check.run_at === "external")
+        return;
+    const { profile } = readCodeCheckProfile(workspaceRoot);
+    if (check.availability === "planned" && check.command.startsWith("@check/") && !profile?.aliases[check.command])
+        throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
+    validateCodeCheckCommands(workspaceRoot, [check.command]);
+    if (check.command.startsWith("@check/") && check.definition && profile?.aliases[check.command] !== check.definition)
+        throw new AppError("check_definition_drift", "The accepted check alias definition differs from the current project profile", 2, { check_id: check.id, alias: check.command, expected: check.definition, actual: profile?.aliases[check.command] ?? null });
+    if (check.availability !== "planned")
+        return;
+    if (!check.command.startsWith("@check/"))
+        throw new AppError("planned_check_requires_alias", "A planned CODE check must declare a new @check/... alias", 2, { check_id: check.id, command: check.command });
+    if (!check.definition?.trim())
+        throw new AppError("planned_check_definition_missing", "A planned CODE check must declare its exact alias definition", 2, { check_id: check.id, command: check.command });
+    if (!profile?.aliases[check.command])
+        throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
 }
 export async function runCodeChecks(context, input) {
-    const receipts = [];
     for (const check of input.checks)
         validateCheckDeclaration(input.workspaceRoot, check);
-    const commands = resolveCodeCheckCommands(input.workspaceRoot, input.runId, input.checks.map((check) => check.command));
-    for (let index = 0; index < commands.length; index += 1) {
-        const declaration = input.checks[index];
-        const command = commands[index];
+    const { hash: profileHash } = readCodeCheckProfile(input.workspaceRoot);
+    const resolved = resolveCodeCheckCommands(input.workspaceRoot, input.runId, input.checks.map((check) => check.command));
+    const groups = deduplicate(input.checks, resolved);
+    const receipts = [];
+    for (let index = 0; index < groups.length; index += 1) {
+        const group = groups[index];
         const ordinal = (context.db.get("SELECT COUNT(*) AS count FROM check_receipts WHERE work_id IS ? AND run_id = ?", [input.workId ?? null, input.runId])?.count ?? 0) + 1;
         const localId = `RCP-${String(ordinal).padStart(3, "0")}`;
         const id = `${input.workId ?? input.runId}/${localId}`;
         const directory = path.join(input.runHome, input.artifactDir ?? "05-code", "checks", localId);
-        fs.mkdirSync(directory, { recursive: true });
+        const evidenceDir = path.join(directory, "artifacts");
+        fs.mkdirSync(evidenceDir, { recursive: true });
         const stdoutPath = path.join(directory, "stdout.log");
         const stderrPath = path.join(directory, "stderr.log");
         const receiptPath = path.join(directory, "receipt.json");
-        const evidenceDir = path.join(directory, "artifacts");
-        fs.mkdirSync(evidenceDir, { recursive: true });
+        const before = workspaceState(input.workspaceRoot);
+        const inputHash = crypto.createHash("sha256").update(JSON.stringify({ gate: group.gate, command: group.command, environment: String(codeExecutionEnvironment(input.workspaceRoot).DD_FLOW_LOCAL_DATABASE_SUFFIX), required_artifacts: group.requiredArtifacts })).digest("hex");
+        const epoch = crypto.createHash("sha256").update(`${group.gate}\0${before.fingerprint}`).digest("hex");
         const startedAt = context.now();
-        input.progress?.(`check ${index + 1}/${commands.length} started: ${command}`);
+        input.progress?.(`check ${index + 1}/${groups.length} started: ${group.command}`);
         const stdout = fs.createWriteStream(stdoutPath);
         const stderr = fs.createWriteStream(stderrPath);
-        const result = await runCheck(command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir }, stdout, stderr, (elapsed) => {
-            input.progress?.(`check ${index + 1}/${commands.length} still running (${elapsed}s): ${command}`);
-        });
+        const result = await runCheck(group.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir }, stdout, stderr, (elapsed) => input.progress?.(`check ${index + 1}/${groups.length} still running (${elapsed}s): ${group.command}`));
         await Promise.all([closeStream(stdout), closeStream(stderr)]);
-        const finishedAt = context.now();
-        const exitCode = result.exitCode;
-        const artifacts = collectRequiredArtifacts(evidenceDir, declaration.required_artifacts ?? []);
-        const status = exitCode === 0 && !result.error && artifacts.complete ? "passed" : "failed";
+        const after = workspaceState(input.workspaceRoot);
+        const mutationPaths = changedPaths(before.files, after.files);
+        const artifacts = collectRequiredArtifacts(evidenceDir, group.requiredArtifacts);
         if (!artifacts.complete)
             fs.appendFileSync(stderrPath, `\nmissing required evidence artifacts: ${artifacts.missing.join(", ")}\n`);
         if (result.error)
             fs.appendFileSync(stderrPath, `\n${result.error}\n`);
-        const receipt = {
-            id,
-            local_id: localId,
-            declaration_id: declaration.id,
-            scope: input.scope,
-            work_id: input.workId ?? null,
-            command,
-            status,
-            exit_code: exitCode,
-            stdout_path: stdoutPath,
-            stderr_path: stderrPath,
-            receipt_path: receiptPath,
-            workspace_fingerprint: workspaceFingerprint(input.workspaceRoot),
-            artifacts: artifacts.items,
-            started_at: startedAt,
-            finished_at: finishedAt
-        };
+        if (mutationPaths.length)
+            fs.appendFileSync(stderrPath, `\ncheck mutated project workspace: ${mutationPaths.join(", ")}\n`);
+        const status = result.aborted ? "aborted" : result.exitCode === 0 && !result.error && artifacts.complete && mutationPaths.length === 0 ? "passed" : "failed";
+        const receipt = { id, local_id: localId, declaration_id: group.declarations[0].id, check_refs: group.declarations.map(checkRef), gate: group.gate, scope: input.scope, work_id: input.workId ?? null, command: group.command, input_hash: inputHash, verification_epoch: epoch, status, exit_code: result.exitCode, stdout_path: stdoutPath, stderr_path: stderrPath, receipt_path: receiptPath, workspace_fingerprint: before.fingerprint, before_fingerprint: before.fingerprint, after_fingerprint: after.fingerprint, profile_hash: profileHash, mutation_paths: mutationPaths, artifacts: artifacts.items, started_at: startedAt, finished_at: context.now() };
         fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
-        context.db.run("INSERT INTO check_receipts (id, project_id, run_id, work_id, scope, declaration_id, command, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, artifacts_json, started_at, finished_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [id, input.projectId, input.runId, input.workId ?? null, input.scope, declaration.id, command, status, exitCode, stdoutPath, stderrPath, receiptPath, receipt.workspace_fingerprint, JSON.stringify(receipt.artifacts), startedAt, finishedAt]);
+        context.db.run("INSERT INTO check_receipts (id, project_id, run_id, work_id, scope, declaration_id, check_refs_json, gate, command, input_hash, verification_epoch, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, before_fingerprint, after_fingerprint, profile_hash, mutation_paths_json, artifacts_json, started_at, finished_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [id, input.projectId, input.runId, input.workId ?? null, input.scope, receipt.declaration_id, JSON.stringify(receipt.check_refs), receipt.gate, receipt.command, receipt.input_hash, receipt.verification_epoch, receipt.status, receipt.exit_code, stdoutPath, stderrPath, receiptPath, receipt.workspace_fingerprint, receipt.before_fingerprint, receipt.after_fingerprint, receipt.profile_hash, JSON.stringify(receipt.mutation_paths), JSON.stringify(receipt.artifacts), receipt.started_at, receipt.finished_at]);
         receipts.push(receipt);
-        input.progress?.(`check ${index + 1}/${commands.length} ${status}: ${command}`);
+        input.progress?.(`check ${index + 1}/${groups.length} ${status}: ${group.command}`);
     }
     return receipts;
 }
-export function aggregateCheckDeclarations(workspaceRoot) {
-    const file = path.join(workspaceRoot, ".memory-bank", "spec", "engineering", "code-check-profile.json");
-    if (!fs.existsSync(file))
-        return [];
-    const profile = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (profile.schema_id !== "dd-flow/code-check-profile@4")
-        throw new AppError("invalid_code_check_profile", "CODE check profile has an unsupported schema", 2, { file, schema_id: profile.schema_id ?? null });
-    if (!Array.isArray(profile.aggregate_commands) || !profile.aggregate_commands.every((command) => typeof command === "string" && command.trim()))
-        throw new AppError("invalid_code_check_profile", "aggregate_commands must be an array of commands", 2, { file });
-    return profile.aggregate_commands.map((command, index) => ({ id: `CHK-POLICY-CODE-${String(index + 1).padStart(3, "0")}`, command, purpose: "Mandatory project-wide policy gate.", run_at: "code", availability: "available" }));
-}
-/**
- * A project-wide gate can observe files owned by more than one CODE Work.
- * Keep it at the CODE/readiness fan-in, where the engine can create a repair
- * Work with the failed receipt and the right write scope.
- */
-export function validateCheckPlacement(workspaceRoot, checks) {
-    const aggregate = new Set(aggregateCheckDeclarations(workspaceRoot).map((check) => check.command));
-    for (const check of checks) {
-        if (check.run_at === "work" && check.availability === "available" && aggregate.has(check.command)) {
-            throw new AppError("aggregate_check_requires_code_gate", "A project aggregate check must run at CODE or readiness, not inside one scoped Work", 2, {
-                check_id: check.id,
-                command: check.command,
-                run_at: check.run_at
-            });
-        }
-    }
-}
-export function checksForRunAt(checks, runAt) {
-    return checks.filter((check) => check.run_at === runAt);
-}
-/** One SSOT for the final CODE gate, reused after CODE-REVIEW repairs. */
-export function finalCodeCheckDeclarations(workspaceRoot, declared) {
-    const selected = [...aggregateCheckDeclarations(workspaceRoot), ...declared.filter((check) => check.run_at === "code" || check.run_at === "readiness")];
-    const unique = new Map();
-    for (const check of selected)
-        if (!unique.has(check.id))
-            unique.set(check.id, check);
-    return [...unique.values()];
-}
-/** Prevent an unchanged failed stage gate from rerunning expensive commands. */
-export function unchangedFinalGateFailures(context, input) {
-    const wanted = new Set(input.declarations.map((check) => check.id));
-    const current = workspaceFingerprint(input.workspaceRoot);
-    const latest = new Map();
-    for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId }).filter((item) => item.scope === "aggregate" && wanted.has(item.declaration_id)))
-        latest.set(receipt.declaration_id, receipt);
-    return [...latest.values()].filter((receipt) => receipt.status === "failed" && receipt.workspace_fingerprint === current);
-}
-export function validateCheckDeclaration(workspaceRoot, check) {
-    if (check.availability !== "planned") {
-        validateCodeCheckCommands(workspaceRoot, [check.command]);
-        return;
-    }
-    if (!check.command.startsWith("@check/")) {
-        throw new AppError("planned_check_requires_alias", "A planned CODE check must declare a new @check/... alias", 2, { check_id: check.id, command: check.command });
-    }
-    if (!check.definition?.trim()) {
-        throw new AppError("planned_check_definition_missing", "A planned CODE check must declare its exact alias definition", 2, { check_id: check.id, command: check.command });
-    }
-    const file = path.join(workspaceRoot, ".memory-bank", "spec", "engineering", "code-check-profile.json");
-    const profile = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {};
-    const aliases = profile.aliases && typeof profile.aliases === "object" && !Array.isArray(profile.aliases) ? profile.aliases : {};
-    const actual = aliases[check.command];
-    if (typeof actual !== "string")
-        throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
-    if (check.definition && actual !== check.definition)
-        throw new AppError("planned_check_definition_mismatch", "A planned check alias does not match its declared definition", 2, { check_id: check.id, command: check.command, expected: check.definition, actual });
-}
-function collectRequiredArtifacts(root, required) {
-    const missing = [];
-    const items = required.map((relative) => {
-        if (path.isAbsolute(relative) || relative.split(path.sep).includes(".."))
-            throw new AppError("invalid_evidence_path", "Required evidence paths must be relative to DD_FLOW_EVIDENCE_DIR", 2, { path: relative });
-        const file = path.join(root, relative);
-        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
-            missing.push(relative);
-            return null;
-        }
-        return { path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") };
-    }).filter((item) => item !== null);
-    return { complete: missing.length === 0, missing, items };
-}
-export function workspaceFingerprint(root) {
-    const git = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
-    const listing = git.status === 0 ? git.stdout.split("\0").filter(Boolean).sort() : listFiles(root);
-    const hash = crypto.createHash("sha256");
-    for (const relative of listing) {
-        const file = path.join(root, relative);
-        hash.update(relative).update("\0");
-        hash.update(fs.existsSync(file) && fs.statSync(file).isFile() ? fs.readFileSync(file) : "<missing>");
-        hash.update("\0");
-    }
-    return hash.digest("hex");
-}
-function listFiles(root, current = root) {
-    return fs.readdirSync(current, { withFileTypes: true }).flatMap((entry) => {
-        if ([".git", "node_modules"].includes(entry.name))
-            return [];
-        const absolute = path.join(current, entry.name);
-        return entry.isDirectory() ? listFiles(root, absolute) : [path.relative(root, absolute)];
-    }).sort();
-}
-function runCheck(command, cwd, environment, stdout, stderr, heartbeat) {
-    return new Promise((resolve) => {
-        const started = Date.now();
-        const child = spawn("/bin/sh", ["-lc", command], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"] });
-        child.stdout.pipe(stdout, { end: false });
-        child.stderr.pipe(stderr, { end: false });
-        const progress = setInterval(() => heartbeat(Math.floor((Date.now() - started) / 1000)), 15_000);
-        let timedOut = false;
-        const timeout = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); }, 15 * 60 * 1000);
-        let error = null;
-        child.once("error", (value) => { error = value.message; });
-        child.once("close", (exitCode, signal) => {
-            clearInterval(progress);
-            clearTimeout(timeout);
-            resolve({ exitCode, error: error ?? (timedOut ? "timed out after 900 seconds" : signal ? `terminated by ${signal}` : null) });
-        });
-    });
-}
-function closeStream(stream) {
-    return new Promise((resolve, reject) => stream.end((error) => error ? reject(error) : resolve()));
-}
+export function unchangedFinalGateFailures(context, input) { const wanted = new Set(input.declarations.flatMap((check) => [check.id, checkRef(check)])); const current = workspaceFingerprint(input.workspaceRoot); const latest = new Map(); for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId }).filter((item) => item.scope === "aggregate" && item.check_refs.some((ref) => wanted.has(ref))))
+    for (const ref of receipt.check_refs)
+        latest.set(ref, receipt); return [...new Set(latest.values())].filter((receipt) => receipt.status === "failed" && receipt.before_fingerprint === current); }
 export function checkReceipts(context, input) {
     const where = input.workId ? "project_id = ? AND run_id = ? AND work_id = ?" : "project_id = ? AND run_id = ?";
     const params = input.workId ? [input.projectId, input.runId, input.workId] : [input.projectId, input.runId];
-    return context.db.all(`SELECT id, declaration_id, scope, work_id, command, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, artifacts_json, started_at, finished_at FROM check_receipts WHERE ${where} ORDER BY started_at, id`, params).map((receipt) => ({ ...receipt, local_id: receipt.id.slice(receipt.id.lastIndexOf("/") + 1), artifacts: JSON.parse(receipt.artifacts_json) }));
-}
+    return context.db.all(`SELECT id, declaration_id, check_refs_json, gate, scope, work_id, command, input_hash, verification_epoch, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, before_fingerprint, after_fingerprint, profile_hash, mutation_paths_json, artifacts_json, started_at, finished_at FROM check_receipts WHERE ${where} ORDER BY started_at, id`, params).map((row) => ({ ...row, local_id: row.id.slice(row.id.lastIndexOf("/") + 1), check_refs: parseArray(row.check_refs_json, [row.declaration_id]), mutation_paths: parseArray(row.mutation_paths_json, []), artifacts: JSON.parse(row.artifacts_json) }));
+}
+export function workspaceFingerprint(root) { return workspaceState(root).fingerprint; }
+function deduplicate(checks, commands) { const groups = new Map(); checks.forEach((check, index) => { const artifacts = [...(check.required_artifacts ?? [])].sort(); const key = JSON.stringify([check.run_at, commands[index], artifacts]); const current = groups.get(key); if (current)
+    current.declarations.push(check);
+else
+    groups.set(key, { gate: check.run_at, command: commands[index], declarations: [check], requiredArtifacts: artifacts }); }); return [...groups.values()]; }
+function workspaceState(root) { const git = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }); const listing = git.status === 0 ? git.stdout.split("\0").filter(Boolean).sort() : listFiles(root); const files = new Map(); const hash = crypto.createHash("sha256"); for (const relative of listing) {
+    const file = path.join(root, relative);
+    const content = fs.existsSync(file) && fs.statSync(file).isFile() ? fs.readFileSync(file) : Buffer.from("<missing>");
+    const digest = crypto.createHash("sha256").update(content).digest("hex");
+    files.set(relative, digest);
+    hash.update(relative).update("\0").update(digest).update("\0");
+} return { fingerprint: hash.digest("hex"), files }; }
+function changedPaths(before, after) { return [...new Set([...before.keys(), ...after.keys()])].filter((key) => before.get(key) !== after.get(key)).sort(); }
+function checkRef(check) { return check.canonical_ref ?? check.id; }
+function parseArray(value, fallback) { try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) && parsed.every((item) => typeof item === "string") ? parsed : fallback;
+}
+catch {
+    return fallback;
+} }
+function isStringRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string" && item.trim().length > 0); }
+function isGateRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([gate, aliases]) => ["work", "code", "readiness", "merge", "release", "external"].includes(gate) && Array.isArray(aliases) && aliases.every((item) => typeof item === "string" && item.startsWith("@check/"))); }
+function collectRequiredArtifacts(root, required) { const missing = []; const items = []; for (const relative of required) {
+    if (path.isAbsolute(relative) || relative.split(/[\\/]/).includes(".."))
+        throw new AppError("invalid_evidence_path", "Required evidence paths must be relative to DD_FLOW_EVIDENCE_DIR", 2, { path: relative });
+    const file = path.join(root, relative);
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+        missing.push(relative);
+        continue;
+    }
+    items.push({ path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") });
+} return { complete: missing.length === 0, missing, items }; }
+function listFiles(root, current = root) { return fs.readdirSync(current, { withFileTypes: true }).flatMap((entry) => { if ([".git", "node_modules"].includes(entry.name))
+    return []; const absolute = path.join(current, entry.name); return entry.isDirectory() ? listFiles(root, absolute) : [path.relative(root, absolute)]; }).sort(); }
+function runCheck(command, cwd, environment, stdout, stderr, heartbeat) { return new Promise((resolve) => { const started = Date.now(); const child = spawn("/bin/sh", ["-lc", command], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" }); child.stdout.pipe(stdout, { end: false }); child.stderr.pipe(stderr, { end: false }); const progress = setInterval(() => heartbeat(Math.floor((Date.now() - started) / 1000)), 15_000); let timedOut = false; let error = null; let escalation; const timeout = setTimeout(() => { timedOut = true; terminateProcessGroup(child.pid, "SIGTERM"); escalation = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 5_000); }, 15 * 60 * 1000); child.once("error", (value) => { error = value.message; }); child.once("close", (exitCode, signal) => { clearInterval(progress); clearTimeout(timeout); if (escalation)
+    clearTimeout(escalation); resolve({ exitCode, error: error ?? (timedOut ? "timed out after 900 seconds" : signal ? `terminated by ${signal}` : null), aborted: timedOut || Boolean(signal) || Boolean(error) }); }); }); }
+function terminateProcessGroup(pid, signal) { if (!pid)
+    return; try {
+    process.kill(process.platform === "win32" ? pid : -pid, signal);
+}
+catch { /* already exited */ } }
+function closeStream(stream) { return new Promise((resolve, reject) => stream.end((error) => error ? reject(error) : resolve())); }

package/dist/services/eval-snapshots.js

@@ -61,9 +61,10 @@ export function createEvalRunSnapshot(context, input) {
         assertStageEntry(status.index.stage_runs ?? [], input.stageEntry);
     else
         throw new AppError("usage", "Snapshot requires exactly one of stageEntry or candidate", 2);
+    const allowedCreatedResultSchema = input.stageEntry ? createdWorkSchemaForStage(input.stageEntry) : null;
     const activeChildren = input.candidate
         ? context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND status IN ('created', 'running', 'paused')", [project.id, input.runId])?.count ?? 0
-        : context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND (status IN ('running', 'paused') OR (status = 'created' AND (? <> 'code' OR COALESCE(result_schema, '') NOT LIKE 'dd-flow/code-work-result@%')))", [project.id, input.runId, input.stageEntry])?.count ?? 0;
+        : context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND (status IN ('running', 'paused') OR (status = 'created' AND (? IS NULL OR COALESCE(result_schema, '') NOT LIKE ?)))", [project.id, input.runId, allowedCreatedResultSchema, allowedCreatedResultSchema ? `${allowedCreatedResultSchema}@%` : ""])?.count ?? 0;
     if (activeChildren > 0)
         throw new AppError("snapshot_not_quiescent", `${input.candidate ? "Candidate" : "Stage-entry"} snapshot requires no active child Work`, 1, { run_id: input.runId, active_children: activeChildren });
     const output = path.resolve(input.output);
@@ -106,6 +107,14 @@ export function createEvalRunSnapshot(context, input) {
     writeJson(path.join(output, "snapshot.json"), manifest);
     return { ok: true, snapshot: output, ...manifest };
 }
+/** A not-yet-started Work packet may be part of the target Stage's entry state. */
+function createdWorkSchemaForStage(stage) {
+    if (stage === "code")
+        return "dd-flow/code-work-result";
+    if (stage === "merge")
+        return "dd-flow/merge-result";
+    return null;
+}
 export function restoreEvalRunSnapshot(context, input) {
     const snapshot = path.resolve(input.snapshot);
     const manifest = readManifest(snapshot);