@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.11

package/dist/services/vnext-code.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
-import { aggregateCheckDeclarations, checkReceipts, codeExecutionEnvironment, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceFingerprint } from "./code-checks.js";
+import { aggregateCheckDeclarations, checkReceipts, codeExecutionEnvironment, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
 import { requireProjectByRoot } from "./projects.js";
 import { appendFlowRunTimelineEvent, advanceFlowRun, attachFlowRunStage, completeFlowRunStage, completeFlowRun, getFlowRunVariables, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
@@ -53,7 +53,8 @@ export async function startVnextCode(context, input) {
         file: batch,
         projectRoot: run.workspace_root,
         ddFlowHome: context.ddFlowHome,
-        runId: input.runId
+        runId: input.runId,
+        runRoot: home
     });
     validateWorkBatchFile(batch);
     const root = path.join(home, stageDir);
@@ -134,9 +135,23 @@ export async function finishVnextCode(context, input) {
         throw new AppError("obligation_coverage_incomplete", "CODE graph does not cover every accepted obligation", 2, { missing });
     }
     // Reject a malformed semantic receipt before running the expensive gate.
-    const verification = verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id });
-    if (verification.verdict !== "passed" || verification.unresolved.length > 0) {
-        throw new AppError("code_verification_incomplete", "CODE verification is not accepted; create or complete the necessary repair Work first", 2, { verification });
+    const verification = verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id, runRoot: home });
+    if (verification.verdict === "blocked") {
+        return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, instruction: "CODE remains running. Resolve the stated external or user-input blocker in this same coordinator session, update code-verification.json, then invoke this same stage finish command again." };
+    }
+    if (verification.verdict === "passed" && verification.unresolved.length > 0) {
+        throw new AppError("verification_contradictory", "A passed CODE verification cannot contain unresolved obligations", 2, { unresolved: verification.unresolved });
+    }
+    if (verification.verdict === "needs_repair") {
+        const repair = addVnextCodeRepair(context, {
+            projectRoot,
+            runId: run.id,
+            originWorkIds: works.filter((work) => work.status === "completed").map((work) => work.work_id),
+            semanticUnresolved: verification.unresolved.length ? verification.unresolved : [verification.summary],
+            verificationPath: input.verificationFile,
+            objective: verification.summary
+        });
+        return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, instruction: "The semantic verification is not accepted. Run the returned repair Work, then update code-verification.json and invoke this same stage finish command again." };
     }
     const checks = finalCodeCheckDeclarations(run.workspace_root, works.flatMap((work) => packet(work)?.checks ?? []));
     const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: checks });
@@ -174,18 +189,26 @@ export async function finishVnextCode(context, input) {
     }
     const allReceipts = checkReceipts(context, { projectId: project.id, runId: run.id });
     const finalReceipts = latestReceiptsByCommand(allReceipts);
+    const projectedVerification = verificationProjection(works, finalReceipts, { historicalReceipts: allReceipts, runId: run.id, runHome: home });
+    const unresolvedAcceptance = (projectedVerification.acceptance ?? []).filter((item) => item.status === "unresolved");
+    if (unresolvedAcceptance.length)
+        throw new AppError("code_acceptance_unresolved", "CODE cannot finish until every due acceptance criterion has current checks and evidence", 2, { unresolved: unresolvedAcceptance });
     const now = context.now();
     const timing = stageTiming(home, stage, now);
-    const changedPaths = [...new Set(works.flatMap((work) => resultPaths(work.result)))];
+    const reportedPaths = [...new Set(works.flatMap((work) => resultPaths(work.result)))];
+    const observedChangedPaths = workspaceChangedPaths(run.workspace_root);
+    const changedPaths = observedChangedPaths ?? reportedPaths;
+    const missingReportedPaths = observedChangedPaths === null ? [] : reportedPaths.filter((item) => !observedChangedPaths.includes(item));
+    if (missingReportedPaths.length)
+        throw new AppError("changed_path_not_materialized", "CODE Work reported paths that are not changed in the accepted workspace", 2, { paths: missingReportedPaths });
     const next = nextAction(run, changedPaths);
-    writeProtocolFlowStatus(run.workspace_root, home, run.id, next === "start_code_review" ? "CODE complete; CODE-REVIEW is next." : next === "start_merge" ? "CODE complete; MERGE is queued." : "CODE complete; this RUN reached its configured terminal boundary.");
     const report = {
         schema_id: "dd-flow/stage-report@1",
         run_id: run.id,
         stage,
         generated_at: now,
         verdict: "done",
-        verification: verificationProjection(works, finalReceipts),
+        verification: projectedVerification,
         semantic: {
             result: `Completed ${works.length} CODE Work item${works.length === 1 ? "" : "s"}; ${finalReceipts.filter((receipt) => receipt.status === "passed").length} current final check receipt${finalReceipts.length === 1 ? "" : "s"} passed.`,
             acceptance: [...expected],
@@ -213,6 +236,10 @@ export async function finishVnextCode(context, input) {
         artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html", summary: "stage-report.md" },
         validation: { permission_scope: "known_targets_only", memory_bank_scope: "changed_files_and_links_only", status: "passed" }
     };
+    // Creating the MERGE request is part of accepting this terminal handoff.
+    // Do it before materialising a terminal stage report or changing RUN state,
+    // so an invalid merge policy leaves CODE safely running and retryable.
+    const mergeRequest = next === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths: changedPaths }) : null;
     writeReport(root, report);
     completeFlowRunStage(context, {
         projectRoot,
@@ -237,7 +264,6 @@ export async function finishVnextCode(context, input) {
     else {
         advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "code_completed", nextAction: next });
     }
-    const mergeRequest = next === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id }) : null;
     return {
         ok: true,
         run_id: run.id,
@@ -255,8 +281,8 @@ export function addVnextCodeRepair(context, input) {
     const home = requireHome(run);
     if (!input.objective.trim())
         throw new AppError("validation", "Repair objective must not be empty", 2);
-    if (!input.checkReceiptId && !input.reviewFindingIds?.length) {
-        throw new AppError("validation", "Repair needs a failed check receipt or CODE-REVIEW finding", 2);
+    if (!input.checkReceiptId && !input.reviewFindings?.length && !input.semanticUnresolved?.length) {
+        throw new AppError("validation", "Repair needs failed check evidence, a CODE-REVIEW finding, or an unresolved CODE verification", 2);
     }
     const receipt = input.checkReceiptId ? context.db.get("SELECT id, declaration_id, run_id, command, status, receipt_path, stdout_path, stderr_path FROM check_receipts WHERE project_id = ? AND id = ?", [
         project.id,
@@ -269,11 +295,19 @@ export function addVnextCodeRepair(context, input) {
     }
     const origins = [...new Set(input.originWorkIds)].map((id) => requireCodeWork(context, project.id, run.id, id));
     const packets = origins.map((work) => packet(work));
-    const invariantPackets = receipt
+    const invariantPackets = receipt || input.semanticUnresolved?.length
         ? codeWorks(context, project.id, run.id).map((work) => packet(work)).filter((value) => !value.repair)
         : packets;
     const first = packets[0];
-    const declaredChecks = finalCodeCheckDeclarations(run.workspace_root, packets.flatMap((value) => value.checks));
+    // A later repair may be caused by any accepted aggregate declaration, not
+    // only the checks copied into its immediate repair parent.  Otherwise a
+    // repair that fixes one failed aggregate check can make a second, already
+    // declared aggregate failure impossible to repair.  The immutable source
+    // of repair eligibility is the original CODE graph.
+    const declaredChecks = finalCodeCheckDeclarations(run.workspace_root, codeWorks(context, project.id, run.id)
+        .map((work) => packet(work))
+        .filter((value) => !value.repair)
+        .flatMap((value) => value.checks));
     const failedCheck = receipt ? declaredChecks.find((check) => check.id === receipt.declaration_id) : undefined;
     if (receipt && !failedCheck) {
         throw new AppError("repair_check_declaration_missing", "Repair receipt is not backed by an accepted CODE check declaration", 2, {
@@ -281,7 +315,8 @@ export function addVnextCodeRepair(context, input) {
             declaration_id: receipt.declaration_id
         });
     }
-    const key = input.reviewFindingIds?.length ? "code-review-repair" : "code-gate-repair";
+    const semanticRepair = Boolean(input.semanticUnresolved?.length);
+    const key = input.reviewFindings?.length ? "code-review-repair" : semanticRepair ? "code-verification-repair" : "code-gate-repair";
     const receiptWriteScope = receipt ? receiptRepairPaths(run.workspace_root, receipt) : [];
     const repair = {
         schema_id: "dd-flow/code-work-packet@5",
@@ -291,22 +326,23 @@ export function addVnextCodeRepair(context, input) {
         repair: {
             origin_work_ids: origins.map((work) => work.work_id),
             ...(receipt ? { check_receipt_id: receipt.id, failure_receipt_path: receipt.receipt_path } : {}),
-            ...(input.reviewFindingIds?.length ? { review_finding_ids: unique(input.reviewFindingIds), review_evidence_refs: unique(input.reviewEvidenceRefs ?? []), review_check_refs: unique(input.reviewCheckRefs ?? (input.reviewChecks ?? []).map((check) => check.id)) } : {})
+            ...(input.reviewFindings?.length ? { review_findings: input.reviewFindings } : {}),
+            ...(semanticRepair ? { semantic_unresolved: unique(input.semanticUnresolved ?? []), verification_path: input.verificationPath } : {})
         },
         task: input.objective,
         semantic_spine: {
-            user_outcome: receipt ? `Restore the accepted behavior after aggregate failure: ${input.objective}` : `Resolve accepted CODE-REVIEW finding: ${input.objective}`,
+            user_outcome: receipt ? `Restore the accepted behavior after aggregate failure: ${input.objective}` : semanticRepair ? `Close the unresolved CODE verification: ${input.objective}` : `Resolve accepted CODE-REVIEW finding: ${input.objective}`,
             component_responsibility: "Diagnose and repair the failed accepted CODE result without changing unrelated behavior.",
             must_preserve: unique(invariantPackets.flatMap((value) => value.semantic_spine.must_preserve)),
             non_goals: unique(invariantPackets.flatMap((value) => value.semantic_spine.non_goals)),
-            acceptance_contribution: receipt ? `Make failed check pass: ${receipt.command}` : `Resolve CODE-REVIEW finding(s): ${input.reviewFindingIds.join(", ")}`
+            acceptance_contribution: receipt ? `Make failed check pass: ${receipt.command}` : semanticRepair ? `Resolve CODE verification gap(s): ${input.semanticUnresolved.join("; ")}` : `Resolve CODE-REVIEW finding(s): ${input.reviewFindings.map((finding) => finding.finding_ref).join(", ")}`
         },
         requirements: uniqueBy(invariantPackets.flatMap((value) => value.requirements), (value) => value.id),
         acceptance: uniqueBy(invariantPackets.flatMap((value) => value.acceptance), (value) => JSON.stringify(value)),
         // A CODE-REVIEW repair changes delivered code/evidence, never the
         // already accepted PLAN or its ownership declaration.
         document_updates: [],
-        required_read: unique([...(receipt ? [receipt.receipt_path] : input.reviewEvidenceRefs ?? []), ...packets.flatMap((value) => value.required_read)]),
+        required_read: unique([...(receipt ? [receipt.receipt_path] : input.reviewFindings?.flatMap((finding) => finding.evidence_refs) ?? []), ...(semanticRepair && input.verificationPath ? [input.verificationPath] : []), ...packets.flatMap((value) => value.required_read)]),
         discovery_boundary: unique(packets.flatMap((value) => value.discovery_boundary)),
         // These are collision-avoidance hints. Receipt paths enrich the coordinator
         // picture but never restrict the repair's project-local edits.
@@ -314,7 +350,7 @@ export function addVnextCodeRepair(context, input) {
         // Receipts record the resolved shell command. A repair must retain the
         // accepted declaration (including its immutable @check alias) and only
         // change when it runs, so work finish can validate it again.
-        checks: selectRepairChecks({ ...(failedCheck ? { failedCheck } : {}), ...(input.reviewChecks ? { reviewChecks: input.reviewChecks } : {}) }),
+        checks: selectRepairChecks({ ...(failedCheck ? { failedCheck } : {}), ...(input.reviewChecks ? { reviewChecks: input.reviewChecks } : {}), ...(semanticRepair ? { semanticChecks: declaredChecks } : {}) }),
         provides_checks: [],
         stop_conditions: unique([
             ...invariantPackets.flatMap((value) => value.stop_conditions),
@@ -339,16 +375,18 @@ export function addVnextCodeRepair(context, input) {
         type: "code_repair_created",
         work_id: id,
         origin_work_ids: input.originWorkIds,
-        ...(receipt ? { check_receipt_id: receipt.id } : { review_finding_ids: input.reviewFindingIds })
+        ...(receipt ? { check_receipt_id: receipt.id } : input.reviewFindings?.length ? { review_finding_ids: input.reviewFindings.map((finding) => finding.finding_ref) } : { semantic_unresolved: input.semanticUnresolved })
     });
     refreshRunWorkProjection(context, project.id, run.id);
     return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work) };
 }
-/** The repair Work runs only the check that motivated it; the stage retains the aggregate gate. */
+/** Retain the causal declaration for worker context; run_at keeps aggregate gates at stage scope. */
 export function selectRepairChecks(input) {
-    const checks = input.failedCheck
-        ? [{ ...input.failedCheck, purpose: "Re-run the failed accepted check.", run_at: "work" }]
-        : (input.reviewChecks ?? []).map((check) => ({ ...check, purpose: `Prove the CODE-REVIEW repair: ${check.purpose}`, run_at: "work" }));
+    // Gate placement belongs to the accepted PLAN. `runCodeChecks` executes only
+    // work-scoped entries, while retaining the aggregate declaration tells the
+    // worker exactly what will be rerun by the coordinator.
+    const candidates = input.failedCheck ? [input.failedCheck] : input.reviewChecks ?? input.semanticChecks ?? [];
+    const checks = candidates.map((check) => ({ ...check, purpose: `${input.semanticChecks ? "Prove the CODE verification repair" : "Prove the CODE-REVIEW repair"}: ${check.purpose}` }));
     return uniqueBy(checks, (check) => check.id);
 }
 function receiptRepairPaths(workspaceRoot, receipt) {
@@ -494,19 +532,35 @@ function processAlive(pid) {
         return false;
     }
 }
-export function verificationProjection(works, receipts) {
+/**
+ * The immutable Work result is a repair history. The stage report is a current
+ * acceptance projection, so a registered receipt from an older check epoch
+ * must never stand in for the receipt that currently proves the declaration.
+ */
+export function verificationProjection(works, receipts, options = {}) {
     const packets = works.map((work) => packet(work)).filter((value) => value !== null);
     const declarations = uniqueBy(packets.flatMap((value) => value.checks), (value) => value.id);
     const receiptByDeclaration = new Map(receipts.flatMap((receipt) => receipt.check_refs.map((ref) => [ref, receipt])));
-    const evidence = new Map();
+    const rawEvidence = new Map();
     for (const work of works) {
         const result = readJsonResult(work.result);
         for (const item of result.evidence ?? [])
             if (item.criterion_id)
-                evidence.set(item.criterion_id, unique([...(evidence.get(item.criterion_id) ?? []), ...(item.refs ?? [])]));
+                rawEvidence.set(item.criterion_id, unique([...(rawEvidence.get(item.criterion_id) ?? []), ...(item.refs ?? [])]));
     }
     const acceptance = uniqueBy(packets.flatMap((value) => value.acceptance), (value) => value.criterion_id);
-    const hasEvidence = (criterionId) => (evidence.get(criterionId)?.length ?? 0) > 0;
+    const historicalReceiptRefs = new Set((options.historicalReceipts ?? receipts).flatMap((receipt) => receiptReferences(receipt, options)));
+    const acceptanceEvidence = new Map(acceptance.map((item) => {
+        const reported = rawEvidence.get(item.criterion_id) ?? [];
+        const current = unique(item.check_refs.flatMap((checkRef) => {
+            const receipt = receiptByDeclaration.get(checkRef);
+            return receipt?.status === "passed" ? [currentReceiptRef(receipt, options)] : [];
+        }));
+        const evidenceRefs = unique([...reported.filter((ref) => !historicalReceiptRefs.has(ref)), ...current]);
+        const historical = reported.filter((ref) => historicalReceiptRefs.has(ref) && !current.includes(ref));
+        return [item.criterion_id, { evidenceRefs, historical }];
+    }));
+    const hasEvidence = (criterionId) => (acceptanceEvidence.get(criterionId)?.evidenceRefs.length ?? 0) > 0;
     const isPassed = (checkId, criterionId) => receiptByDeclaration.get(checkId)?.status === "passed" || (declarations.find((check) => check.id === checkId)?.run_at === "external" && hasEvidence(criterionId));
     return {
         checks: declarations.map((check) => {
@@ -517,10 +571,20 @@ export function verificationProjection(works, receipts) {
         acceptance: acceptance.map((item) => {
             const external = item.check_refs.some((id) => declarations.find((check) => check.id === id)?.run_at === "external");
             const confirmed = item.check_refs.every((id) => isPassed(id, item.criterion_id)) && hasEvidence(item.criterion_id);
-            return { criterion_id: item.criterion_id, gate: item.gate, status: confirmed ? (external ? "confirmed_with_external_evidence" : "confirmed") : ["work", "code", "readiness"].includes(item.gate) ? "unresolved" : "not_due", check_refs: item.check_refs, evidence_refs: evidence.get(item.criterion_id) ?? [] };
+            const evidence = acceptanceEvidence.get(item.criterion_id) ?? { evidenceRefs: [], historical: [] };
+            return { criterion_id: item.criterion_id, gate: item.gate, status: confirmed ? (external ? "confirmed_with_external_evidence" : "confirmed") : ["work", "code", "readiness"].includes(item.gate) ? "unresolved" : "not_due", check_refs: item.check_refs, evidence_refs: evidence.evidenceRefs, ...(evidence.historical.length ? { reported_evidence_refs: evidence.historical } : {}) };
         })
     };
 }
+function currentReceiptRef(receipt, options) {
+    if (!options.runId || !options.runHome)
+        return receipt.receipt_path;
+    const relative = path.relative(options.runHome, receipt.receipt_path).split(path.sep).join("/");
+    return relative && !relative.startsWith("../") ? `run://${options.runId}/${relative}` : receipt.receipt_path;
+}
+function receiptReferences(receipt, options) {
+    return unique([receipt.receipt_path, currentReceiptRef(receipt, options)]);
+}
 function readJsonResult(value) { try {
     const parsed = JSON.parse(value ?? "{}");
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
@@ -572,7 +636,7 @@ function requireRootWork(context, projectId, runId) {
     return work;
 }
 function requireRun(context, projectId, runId) {
-    const run = context.db.get("SELECT id, project_id, run_home_path, workspace_root, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const run = context.db.get("SELECT id, project_id, run_root, workspace_root, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     if (!run)
         throw new AppError("not_found", "RUN is not registered", 1);
     return run;
@@ -630,16 +694,16 @@ function readReadiness(file) {
     }
 }
 function requireHome(run) {
-    if (!run.run_home_path)
-        throw new AppError("runtime_missing", "RUN workspace is unavailable", 1);
-    return run.run_home_path;
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1);
+    return run.run_root;
 }
 function finishCommand(context, runId, projectRoot, verificationFile) {
     return `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`;
 }
 function readVerification(context, input) {
     const file = path.resolve(input.file);
-    validateSchema({ schemaName: "code-verification", file, projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId });
+    validateSchema({ schemaName: "code-verification", file, projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.runRoot });
     return JSON.parse(fs.readFileSync(file, "utf8"));
 }
 function verificationForFinish(context, input) {

package/dist/services/vnext-fanout.js

@@ -7,12 +7,6 @@ import { getFlowRunVariables } from "./runs.js";
 import { listWorks } from "./work-registry.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 export const subagentCapacityKey = "runtime.subagent.available_slots";
-export const capacityProbe = {
-    fanout_size: 15,
-    probe_hold_seconds: 60,
-    cleanup_deadline_seconds: 180,
-    completion_token: "AGENT-NN"
-};
 export function fanoutState(input) {
     if (!input.hasWork)
         return input.dispatch === "none" ? "coordinator_required" : "dispatch_required";
@@ -42,10 +36,10 @@ export function readFanoutDescriptor(stageRoot) {
 export function getVnextFanoutStatus(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
-    const run = context.db.get("SELECT run_home_path FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
-    if (!run?.run_home_path)
-        throw new AppError("not_found", "RUN workspace is unavailable", 1, { run_id: input.runId });
-    const stageRoot = path.join(run.run_home_path, vnextStageDirectory(input.stage));
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+    if (!run?.run_root)
+        throw new AppError("not_found", "RUN artifact root is unavailable", 1, { run_id: input.runId });
+    const stageRoot = path.join(run.run_root, vnextStageDirectory(input.stage));
     const descriptor = readFanoutDescriptor(stageRoot);
     if (!descriptor)
         return { ok: true, run_id: input.runId, stage: input.stage, orchestration: null };
@@ -70,8 +64,7 @@ export function getVnextFanoutStatus(context, input) {
             state: fanoutState({ dispatch: descriptor.dispatch, hasWork, capacityRequired: descriptor.capacity_required, capacityKnown, created: counts.created ?? 0, running: counts.running ?? 0 }),
             capacity: {
                 run_key: subagentCapacityKey,
-                available_slots: capacityKnown ? available : null,
-                ...(descriptor.capacity_required && !capacityKnown ? { probe: capacityProbe } : {})
+                available_slots: capacityKnown ? available : null
             },
             works: { ...counts, ready: ready.works.map((work) => ({ work_id: work.work_id, task: work.task, start_command: work.start_command })) }
         }