cclaw-cli 0.51.30 → 0.55.2

package/dist/internal/advance-stage/advance.js

@@ -0,0 +1,480 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveArtifactPath } from "../../artifact-paths.js";
+import { appendDelegation, checkMandatoryDelegations, readDelegationEvents, readDelegationLedger } from "../../delegation.js";
+import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../../gate-evidence.js";
+import { extractMarkdownSectionBody, parseLearningsSection } from "../../artifact-linter.js";
+import { getAvailableTransitions, getTransitionGuards } from "../../flow-state.js";
+import { appendKnowledge } from "../../knowledge-store.js";
+import { readFlowState, writeFlowState } from "../../runs.js";
+import { stageSchema } from "../../content/stage-schema.js";
+import { extractReviewLoopEnvelopeFromArtifact } from "../../content/review-loop.js";
+import { unique } from "./helpers.js";
+import { AUTO_REVIEW_LOOP_GATE_BY_STAGE, reviewLoopArtifactFixHint, validateGateEvidenceShape } from "./review-loop.js";
+import { ensureProactiveDelegationTrace } from "./verify.js";
+function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGuards, selectedTransitionGuards) {
+    const natural = transitionTargets[0] ?? null;
+    const specialTargets = transitionTargets.filter((target) => target !== natural);
+    for (const target of specialTargets) {
+        const guards = getTransitionGuards(stage, target, track);
+        if (guards.length === 0)
+            continue;
+        const selectedSpecial = guards.some((guard) => selectedTransitionGuards.has(guard));
+        if (!selectedSpecial)
+            continue;
+        if (guards.every((guard) => satisfiedGuards.has(guard))) {
+            return target;
+        }
+    }
+    if (natural) {
+        const guards = getTransitionGuards(stage, natural, track);
+        if (guards.every((guard) => satisfiedGuards.has(guard))) {
+            return natural;
+        }
+    }
+    for (const target of specialTargets) {
+        const guards = getTransitionGuards(stage, target, track);
+        if (guards.every((guard) => satisfiedGuards.has(guard))) {
+            return target;
+        }
+    }
+    return natural;
+}
+export async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track, selectedGateIds, evidenceByGate) {
+    const gateId = AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage];
+    if (!gateId)
+        return;
+    if (!selectedGateIds.includes(gateId))
+        return;
+    const reviewStage = stage === "scope" || stage === "design" ? stage : null;
+    if (!reviewStage)
+        return;
+    const existing = evidenceByGate[gateId];
+    if (typeof existing === "string" && existing.trim().length > 0) {
+        return;
+    }
+    const resolved = await resolveArtifactPath(stage, {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    let raw = "";
+    try {
+        raw = await fs.readFile(resolved.absPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    const envelope = extractReviewLoopEnvelopeFromArtifact(raw, reviewStage, resolved.relPath);
+    if (!envelope)
+        return;
+    evidenceByGate[gateId] = JSON.stringify(envelope);
+}
+export async function buildValidationReport(projectRoot, flowState, options = {}) {
+    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
+    const gates = await verifyCurrentStageGateEvidence(projectRoot, flowState);
+    const completedStages = verifyCompletedStagesGateClosure(flowState);
+    const blockedReviewRouteComplete = options.allowBlockedReviewRoute === true
+        && flowState.currentStage === "review"
+        && typeof flowState.guardEvidence.review_verdict_blocked === "string"
+        && flowState.guardEvidence.review_verdict_blocked.trim().length > 0
+        && !flowState.stageGateCatalog.review.passed.includes("review_criticals_resolved");
+    const ok = delegation.satisfied && gates.ok && (gates.complete || blockedReviewRouteComplete) && completedStages.ok;
+    return {
+        ok,
+        stage: flowState.currentStage,
+        delegation: {
+            satisfied: delegation.satisfied,
+            missing: delegation.missing,
+            waived: delegation.waived,
+            missingEvidence: delegation.missingEvidence,
+            missingDispatchProof: delegation.missingDispatchProof,
+            legacyInferredCompletions: delegation.legacyInferredCompletions,
+            corruptEventLines: delegation.corruptEventLines,
+            staleWorkers: delegation.staleWorkers,
+            expectedMode: delegation.expectedMode
+        },
+        gates: {
+            ok: gates.ok,
+            complete: gates.complete,
+            issues: gates.issues,
+            missingRequired: gates.missingRequired,
+            missingTriggeredConditional: gates.missingTriggeredConditional
+        },
+        completedStages: {
+            ok: completedStages.ok,
+            issues: completedStages.issues
+        }
+    };
+}
+const LEARNINGS_HARVEST_MARKER_PREFIX = "<!-- cclaw:learnings-harvested:";
+export function withLearningsHarvestMarker(artifactMarkdown, appendedEntries, skippedDuplicates) {
+    const suffix = artifactMarkdown.endsWith("\n") ? "" : "\n";
+    return `${artifactMarkdown}${suffix}${LEARNINGS_HARVEST_MARKER_PREFIX}${new Date().toISOString()} appended=${appendedEntries} skipped=${skippedDuplicates} -->\n`;
+}
+export async function harvestStageLearnings(projectRoot, stage, track) {
+    const resolvedArtifact = await resolveArtifactPath(stage, {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    const artifactPath = resolvedArtifact.absPath;
+    let raw = "";
+    try {
+        raw = await fs.readFile(artifactPath, "utf8");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            markerWritten: false,
+            parsedEntries: 0,
+            appendedEntries: 0,
+            skippedDuplicates: 0,
+            details: `Unable to read artifact for learnings harvest (${artifactPath}): ${err instanceof Error ? err.message : String(err)}`
+        };
+    }
+    if (raw.includes(LEARNINGS_HARVEST_MARKER_PREFIX)) {
+        return {
+            ok: true,
+            markerWritten: false,
+            parsedEntries: 0,
+            appendedEntries: 0,
+            skippedDuplicates: 0,
+            details: "Learnings already harvested for this artifact."
+        };
+    }
+    const learningsBody = extractMarkdownSectionBody(raw, "Learnings");
+    if (learningsBody === null) {
+        return {
+            ok: false,
+            markerWritten: false,
+            parsedEntries: 0,
+            appendedEntries: 0,
+            skippedDuplicates: 0,
+            details: 'Artifact is missing required "## Learnings" section.'
+        };
+    }
+    const parsed = parseLearningsSection(learningsBody);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            markerWritten: false,
+            parsedEntries: 0,
+            appendedEntries: 0,
+            skippedDuplicates: 0,
+            details: parsed.details
+        };
+    }
+    const appendResult = await appendKnowledge(projectRoot, parsed.entries, {
+        stage,
+        originStage: stage,
+        originRun: null,
+        project: path.basename(projectRoot)
+    });
+    if (appendResult.invalid > 0) {
+        return {
+            ok: false,
+            markerWritten: false,
+            parsedEntries: parsed.entries.length,
+            appendedEntries: appendResult.appended,
+            skippedDuplicates: appendResult.skippedDuplicates,
+            details: `Learnings append failed schema checks: ${appendResult.errors.join(" | ")}`
+        };
+    }
+    const withMarker = withLearningsHarvestMarker(raw, appendResult.appended, appendResult.skippedDuplicates);
+    await fs.writeFile(artifactPath, withMarker, "utf8");
+    return {
+        ok: true,
+        markerWritten: true,
+        parsedEntries: parsed.entries.length,
+        appendedEntries: appendResult.appended,
+        skippedDuplicates: appendResult.skippedDuplicates,
+        details: parsed.none
+            ? "Learnings section marked none; harvest marker recorded."
+            : `Harvested ${appendResult.appended} learning entr${appendResult.appended === 1 ? "y" : "ies"} (${appendResult.skippedDuplicates} duplicate skipped).`
+    };
+}
+export async function runAdvanceStage(projectRoot, args, io) {
+    const flowState = await readFlowState(projectRoot);
+    if (flowState.currentStage !== args.stage) {
+        io.stderr.write(`cclaw internal advance-stage: current stage is "${flowState.currentStage}", not "${args.stage}".\n`);
+        return 1;
+    }
+    const schema = stageSchema(args.stage, flowState.track);
+    const requiredGateIds = schema.requiredGates
+        .filter((gate) => gate.tier === "required")
+        .map((gate) => gate.id);
+    const transitionTargets = getAvailableTransitions(args.stage, flowState.track).map((rule) => rule.to);
+    const allowedGateIds = new Set(schema.requiredGates.map((gate) => gate.id));
+    const transitionGuardIds = new Set(transitionTargets
+        .flatMap((target) => getTransitionGuards(args.stage, target, flowState.track))
+        .filter((guardId) => !allowedGateIds.has(guardId)));
+    const selectableGateIds = new Set([...allowedGateIds, ...transitionGuardIds]);
+    const selectedGateIds = args.passedGateIds.length > 0
+        ? args.passedGateIds.filter((gateId) => selectableGateIds.has(gateId))
+        : requiredGateIds;
+    const selectedGateIdSet = new Set(selectedGateIds);
+    const selectedTransitionGuards = selectedGateIds.filter((gateId) => transitionGuardIds.has(gateId));
+    const blockedReviewRoute = args.stage === "review" && selectedGateIdSet.has("review_verdict_blocked");
+    const requiredForSelectedRoute = blockedReviewRoute
+        ? requiredGateIds.filter((gateId) => gateId !== "review_criticals_resolved")
+        : requiredGateIds;
+    const missingRequired = requiredForSelectedRoute.filter((gateId) => !selectedGateIdSet.has(gateId));
+    if (missingRequired.length > 0) {
+        io.stderr.write(`cclaw internal advance-stage: required gates not selected as passed: ${missingRequired.join(", ")}.\n`);
+        return 1;
+    }
+    const mandatory = new Set(schema.mandatoryDelegations);
+    for (const agent of args.waiveDelegations) {
+        if (!mandatory.has(agent)) {
+            io.stderr.write(`cclaw internal advance-stage: cannot waive "${agent}" for stage "${args.stage}" (not mandatory).\n`);
+            return 1;
+        }
+    }
+    if (args.waiveDelegations.length > 0) {
+        const waiverReason = args.waiverReason?.trim();
+        if (!waiverReason) {
+            io.stderr.write("cclaw internal advance-stage: --waive-delegation requires an explicit non-empty --waiver-reason.\n");
+            return 1;
+        }
+        for (const agent of args.waiveDelegations) {
+            await appendDelegation(projectRoot, {
+                stage: args.stage,
+                agent,
+                mode: "mandatory",
+                status: "waived",
+                waiverReason,
+                fulfillmentMode: "role-switch",
+                ts: new Date().toISOString()
+            });
+        }
+    }
+    await hydrateReviewLoopEvidenceFromArtifact(projectRoot, args.stage, flowState.track, selectedGateIds, args.evidenceByGate);
+    const catalog = flowState.stageGateCatalog[args.stage];
+    const nextPassed = unique([...catalog.passed, ...selectedGateIds]).filter((gateId) => allowedGateIds.has(gateId));
+    const nextPassedSet = new Set(nextPassed);
+    const nextBlocked = unique(catalog.blocked.filter((gateId) => !nextPassedSet.has(gateId))).filter((gateId) => allowedGateIds.has(gateId));
+    const conditional = new Set(catalog.conditional);
+    const nextTriggered = unique([
+        ...catalog.triggered.filter((gateId) => conditional.has(gateId)),
+        ...nextPassed.filter((gateId) => conditional.has(gateId)),
+        ...nextBlocked.filter((gateId) => conditional.has(gateId))
+    ]);
+    const guardEvidenceGateIds = unique([...nextPassed, ...selectedTransitionGuards]);
+    const missingGuardEvidence = guardEvidenceGateIds.filter((gateId) => {
+        const existing = flowState.guardEvidence[gateId];
+        if (typeof existing === "string" && existing.trim().length > 0) {
+            return false;
+        }
+        const provided = args.evidenceByGate[gateId];
+        return !(typeof provided === "string" && provided.trim().length > 0);
+    });
+    if (missingGuardEvidence.length > 0) {
+        io.stderr.write(`cclaw internal advance-stage: missing --evidence-json entries for passed gates: ${missingGuardEvidence.join(", ")}.\n`);
+        return 1;
+    }
+    const malformedGateEvidence = [];
+    for (const gateId of nextPassed) {
+        const provided = args.evidenceByGate[gateId];
+        const existing = flowState.guardEvidence[gateId];
+        const effectiveEvidence = typeof provided === "string" && provided.trim().length > 0
+            ? provided
+            : typeof existing === "string" && existing.trim().length > 0
+                ? existing
+                : "";
+        const issue = await validateGateEvidenceShape(projectRoot, args.stage, gateId, effectiveEvidence);
+        if (issue) {
+            malformedGateEvidence.push(`${gateId}: ${issue}${reviewLoopArtifactFixHint(args.stage, gateId)}`);
+        }
+    }
+    if (malformedGateEvidence.length > 0) {
+        io.stderr.write(`cclaw internal advance-stage: gate evidence format check failed: ${malformedGateEvidence.join(" | ")}.\n`);
+        return 1;
+    }
+    const nextGuardEvidence = { ...flowState.guardEvidence };
+    for (const gateId of guardEvidenceGateIds) {
+        const provided = args.evidenceByGate[gateId];
+        if (typeof provided === "string" && provided.trim().length > 0) {
+            nextGuardEvidence[gateId] = provided.trim();
+        }
+    }
+    const nextStageCatalog = {
+        required: [...catalog.required],
+        recommended: [...catalog.recommended],
+        conditional: [...catalog.conditional],
+        triggered: nextTriggered,
+        passed: nextPassed,
+        blocked: nextBlocked
+    };
+    const candidateState = {
+        ...flowState,
+        guardEvidence: nextGuardEvidence,
+        stageGateCatalog: {
+            ...flowState.stageGateCatalog,
+            [args.stage]: nextStageCatalog
+        }
+    };
+    const validation = await buildValidationReport(projectRoot, candidateState, {
+        allowBlockedReviewRoute: blockedReviewRoute
+    });
+    if (!validation.ok) {
+        const ledgerForDiag = await readDelegationLedger(projectRoot).catch(() => ({ entries: [] }));
+        const eventsForDiag = await readDelegationEvents(projectRoot).catch(() => ({ events: [], corruptLines: [] }));
+        const ledgerEntriesText = await fs.readFile(path.join(projectRoot, ".cclaw/state/delegation-events.jsonl"), "utf8").catch(() => "");
+        const corruptSnippets = (() => {
+            if (validation.delegation.corruptEventLines.length === 0)
+                return [];
+            const lines = ledgerEntriesText.split(/\r?\n/u);
+            return validation.delegation.corruptEventLines.slice(0, 3).map((lineNo) => {
+                const line = lines[lineNo - 1] ?? "";
+                const sample = line.length > 120 ? `${line.slice(0, 117)}...` : line;
+                return `line ${lineNo}: ${sample}`;
+            });
+        })();
+        const dispatchProofDetails = validation.delegation.missingDispatchProof.flatMap((agent) => {
+            const rows = ledgerForDiag.entries.filter((entry) => entry.agent === agent && entry.status === "completed");
+            return rows.map((row) => `${agent}(spanId=${row.spanId ?? "unknown"})`);
+        });
+        const nextActions = [];
+        if (validation.delegation.missing.length > 0) {
+            nextActions.push(`Run mandatory delegation(s) for stage "${args.stage}": ${validation.delegation.missing.join(", ")}. These roles are required by the stage schema before advance. If dispatch is impossible, use the waiver fallback only with a user-visible reason: \`node .cclaw/hooks/stage-complete.mjs ${args.stage} --waive-delegation=${validation.delegation.missing.join(",")} --waiver-reason="<why safe>"\`.`);
+        }
+        if (validation.delegation.missingEvidence.length > 0) {
+            nextActions.push(`Role-switch fallback completion needs artifact evidenceRefs naming what the role proved; rerun completion with --evidence-ref=<artifact#anchor> or escalate to a real isolated dispatch surface.`);
+        }
+        if (validation.delegation.missingDispatchProof.length > 0) {
+            nextActions.push(`Isolated completion(s) ${dispatchProofDetails.join(", ") || validation.delegation.missingDispatchProof.join(", ")} lack event-log dispatch proof. The ledger says completed, but .cclaw/state/delegation-events.jsonl must show scheduled -> launched -> acknowledged -> completed with --span-id, --dispatch-id, --dispatch-surface, --agent-definition-path, ackTs, and completedTs before advancing.`);
+        }
+        if (validation.delegation.legacyInferredCompletions.length > 0) {
+            nextActions.push(`Pre-v3 ledger entries found: ${validation.delegation.legacyInferredCompletions.join(", ")}. Run \`node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path>\` to upgrade the row to dispatch-proof shape.`);
+        }
+        if (validation.delegation.corruptEventLines.length > 0) {
+            nextActions.push(`delegation-events.jsonl has ${validation.delegation.corruptEventLines.length} corrupt line(s) at ${validation.delegation.corruptEventLines.slice(0, 3).join(", ")}${validation.delegation.corruptEventLines.length > 3 ? ", ..." : ""}; remove or fix them before advancing.`);
+        }
+        if (validation.delegation.staleWorkers.length > 0) {
+            nextActions.push(`Stale scheduled delegations ${validation.delegation.staleWorkers.join(", ")} have no terminal row sharing the same spanId; emit launched/acknowledged/completed (or failed/stale) before advancing.`);
+        }
+        if (validation.gates.issues.length > 0) {
+            nextActions.push("Fix the artifact/gate issue shown in gates.issues, then rerun stage-complete.");
+        }
+        if (validation.completedStages.issues.length > 0) {
+            nextActions.push("Repair previously completed stage gate closure before advancing.");
+        }
+        if (args.json) {
+            io.stdout.write(`${JSON.stringify({
+                ok: false,
+                command: "advance-stage",
+                stage: args.stage,
+                kind: "validation-failed",
+                delegation: validation.delegation,
+                gates: validation.gates,
+                completedStages: validation.completedStages,
+                diagnostics: {
+                    dispatchProofRows: dispatchProofDetails,
+                    corruptEventSamples: corruptSnippets,
+                    unawareEvents: eventsForDiag.corruptLines.length
+                },
+                nextActions
+            })}\n`);
+        }
+        io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}".\n`);
+        if (validation.delegation.missing.length > 0) {
+            io.stderr.write(`- missing delegations: ${validation.delegation.missing.join(", ")}\n`);
+            io.stderr.write(`  next action: run the named agent(s) for this stage, or rerun with --waive-delegation=${validation.delegation.missing.join(",")} --waiver-reason="<why safe>" only when the user accepts the safety trade-off.\n`);
+        }
+        if (validation.delegation.missingEvidence.length > 0) {
+            io.stderr.write(`- role-switch evidence missing: ${validation.delegation.missingEvidence.join(", ")}\n`);
+            io.stderr.write(`  next action: include --evidence-ref=<artifact#anchor> when emitting the completed event so the artifact shows what was reviewed/proved, or escalate to a true isolated dispatch surface.\n`);
+        }
+        if (validation.delegation.missingDispatchProof.length > 0) {
+            io.stderr.write(`- isolated completion lacks dispatch proof: ${dispatchProofDetails.join(", ") || validation.delegation.missingDispatchProof.join(", ")}\n`);
+            io.stderr.write(`  next action: repair the event log proof by emitting scheduled -> launched -> acknowledged -> completed with --span-id, --dispatch-id, --dispatch-surface, --agent-definition-path, ackTs, and completedTs before advancing.\n`);
+        }
+        if (validation.delegation.legacyInferredCompletions.length > 0) {
+            io.stderr.write(`- legacy-inferred completions need rerecord: ${validation.delegation.legacyInferredCompletions.join(", ")}\n`);
+            io.stderr.write(`  next action: \`node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path>\`.\n`);
+        }
+        if (validation.delegation.corruptEventLines.length > 0) {
+            io.stderr.write(`- corrupt delegation-events.jsonl line(s): ${validation.delegation.corruptEventLines.slice(0, 3).join(", ")}${validation.delegation.corruptEventLines.length > 3 ? `, ... (+${validation.delegation.corruptEventLines.length - 3})` : ""}\n`);
+            for (const snippet of corruptSnippets) {
+                io.stderr.write(`    sample: ${snippet}\n`);
+            }
+        }
+        if (validation.delegation.staleWorkers.length > 0) {
+            io.stderr.write(`- stale scheduled delegations: ${validation.delegation.staleWorkers.join(", ")}\n`);
+            io.stderr.write(`  next action: emit a terminal row (completed/failed/stale) for the same span before advancing.\n`);
+        }
+        if (validation.gates.issues.length > 0) {
+            io.stderr.write(`- gate issues: ${validation.gates.issues.join(" | ")}\n`);
+        }
+        if (validation.completedStages.issues.length > 0) {
+            io.stderr.write(`- completed-stage closure issues: ${validation.completedStages.issues.join(" | ")}\n`);
+        }
+        return 1;
+    }
+    const proactiveTrace = await ensureProactiveDelegationTrace(projectRoot, args.stage, {
+        acceptWaiver: args.acceptProactiveWaiver,
+        waiverReason: args.acceptProactiveWaiverReason
+    });
+    if (proactiveTrace.missingRules.length > 0) {
+        const missingSummary = proactiveTrace.missingRules
+            .map((rule) => `${rule.agent} (when: ${rule.when})`)
+            .join(", ");
+        const nextAction = "Run the proactive delegations listed above, or rerun stage-complete with " +
+            "--accept-proactive-waiver [--accept-proactive-waiver-reason=\"<why safe>\"] " +
+            "after explicit user approval.";
+        if (args.json) {
+            io.stdout.write(`${JSON.stringify({
+                ok: false,
+                command: "advance-stage",
+                stage: args.stage,
+                kind: "proactive-delegations-missing",
+                proactiveDelegations: proactiveTrace.missingRules.map((rule) => ({
+                    agent: rule.agent,
+                    when: rule.when,
+                    skill: rule.skill ?? null
+                })),
+                nextActions: [nextAction]
+            })}\n`);
+        }
+        io.stderr.write(`cclaw internal advance-stage: proactive delegation evidence is missing for stage "${args.stage}": ${missingSummary}.\n`);
+        io.stderr.write(`  next action: ${nextAction}\n`);
+        return 1;
+    }
+    const learningsHarvest = await harvestStageLearnings(projectRoot, args.stage, flowState.track);
+    if (!learningsHarvest.ok) {
+        io.stderr.write(`cclaw internal advance-stage: learnings harvest failed for "${schema.artifactFile}". ${learningsHarvest.details}\n`);
+        return 1;
+    }
+    const satisfiedGuards = new Set([...nextPassed, ...selectedTransitionGuards]);
+    const successor = resolveSuccessorTransition(args.stage, flowState.track, transitionTargets, satisfiedGuards, new Set(selectedTransitionGuards));
+    const completedStages = blockedReviewRoute
+        ? flowState.completedStages.filter((stage) => stage !== args.stage)
+        : flowState.completedStages.includes(args.stage)
+            ? [...flowState.completedStages]
+            : [...flowState.completedStages, args.stage];
+    const finalState = {
+        ...candidateState,
+        completedStages,
+        currentStage: successor ?? args.stage
+    };
+    await writeFlowState(projectRoot, finalState);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "advance-stage",
+            stage: args.stage,
+            nextStage: successor,
+            currentStage: finalState.currentStage,
+            completedStages: finalState.completedStages,
+            learnings: {
+                parsed: learningsHarvest.parsedEntries,
+                appended: learningsHarvest.appendedEntries,
+                skippedDuplicates: learningsHarvest.skippedDuplicates,
+                markerWritten: learningsHarvest.markerWritten,
+                details: learningsHarvest.details
+            }
+        }, null, 2)}\n`);
+    }
+    return 0;
+}

package/dist/internal/advance-stage/cancel-run.d.ts

@@ -0,0 +1,8 @@
+import type { CancelRunArgs } from "./parsers.js";
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function runCancelRun(projectRoot: string, args: CancelRunArgs, io: InternalIo): Promise<number>;
+export {};

package/dist/internal/advance-stage/cancel-run.js

@@ -0,0 +1,19 @@
+import { archiveRun } from "../../runs.js";
+export async function runCancelRun(projectRoot, args, io) {
+    const archived = await archiveRun(projectRoot, args.name, {
+        disposition: args.disposition,
+        dispositionReason: args.reason
+    });
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "cancel-run",
+            disposition: archived.disposition,
+            reason: archived.dispositionReason ?? args.reason,
+            archiveId: archived.archiveId,
+            archivePath: archived.archivePath,
+            resetRunId: archived.resetState.activeRunId
+        }, null, 2)}\n`);
+    }
+    return 0;
+}

package/dist/internal/advance-stage/flow-state-coercion.d.ts

@@ -0,0 +1,3 @@
+import { type FlowState } from "../../flow-state.js";
+export declare function parseCandidateGateCatalog(value: unknown, fallback: FlowState["stageGateCatalog"]): FlowState["stageGateCatalog"];
+export declare function coerceCandidateFlowState(raw: unknown, fallback: FlowState): FlowState;

package/dist/internal/advance-stage/flow-state-coercion.js

@@ -0,0 +1,81 @@
+import { FLOW_STAGES } from "../../types.js";
+import { isFlowTrack } from "../../flow-state.js";
+import { emptyGateState, isFlowStageValue, parseGuardEvidence, parseStringList, unique } from "./helpers.js";
+export function parseCandidateGateCatalog(value, fallback) {
+    const next = {};
+    for (const stage of FLOW_STAGES) {
+        // Guard against stale on-disk flow-state files that persisted a partial
+        // stageGateCatalog (missing a stage key). Previously `fallback[stage]`
+        // could be undefined and the spread below would throw at runtime.
+        const base = fallback[stage] ?? emptyGateState();
+        next[stage] = {
+            required: [...base.required],
+            recommended: [...base.recommended],
+            conditional: [...base.conditional],
+            triggered: [...base.triggered],
+            passed: [...base.passed],
+            blocked: [...base.blocked]
+        };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return next;
+    }
+    const rawCatalog = value;
+    for (const stage of FLOW_STAGES) {
+        const rawStage = rawCatalog[stage];
+        if (!rawStage || typeof rawStage !== "object" || Array.isArray(rawStage)) {
+            continue;
+        }
+        const typed = rawStage;
+        const base = fallback[stage] ?? emptyGateState();
+        const allowed = new Set([...base.required, ...base.recommended, ...base.conditional]);
+        const conditional = new Set(base.conditional);
+        const passed = unique(parseStringList(typed.passed)).filter((gateId) => allowed.has(gateId));
+        const blocked = unique(parseStringList(typed.blocked)).filter((gateId) => allowed.has(gateId));
+        const triggered = unique([
+            ...parseStringList(typed.triggered).filter((gateId) => conditional.has(gateId)),
+            ...passed.filter((gateId) => conditional.has(gateId)),
+            ...blocked.filter((gateId) => conditional.has(gateId))
+        ]);
+        next[stage] = {
+            required: [...base.required],
+            recommended: [...base.recommended],
+            conditional: [...base.conditional],
+            triggered,
+            passed,
+            blocked
+        };
+    }
+    return next;
+}
+export function coerceCandidateFlowState(raw, fallback) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return fallback;
+    }
+    const typed = raw;
+    const track = isFlowTrack(typed.track) ? typed.track : fallback.track;
+    const currentStage = isFlowStageValue(typed.currentStage)
+        ? typed.currentStage
+        : fallback.currentStage;
+    const completedStages = unique(parseStringList(typed.completedStages).filter((stage) => isFlowStageValue(stage)));
+    const skippedStagesRaw = parseStringList(typed.skippedStages).filter((stage) => isFlowStageValue(stage));
+    const skippedStages = skippedStagesRaw.length > 0 ? skippedStagesRaw : fallback.skippedStages;
+    // When the candidate payload omits `guardEvidence` entirely we must keep
+    // the on-disk fallback — otherwise a partial update (e.g. a tooling call
+    // that only passes stage + passedGateIds) would silently wipe every
+    // previously recorded evidence string and fail the next
+    // `verifyCurrentStageGateEvidence` check.
+    const candidateEvidence = parseGuardEvidence(typed.guardEvidence);
+    const guardEvidence = typed.guardEvidence === undefined
+        ? { ...fallback.guardEvidence }
+        : candidateEvidence;
+    return {
+        ...fallback,
+        currentStage,
+        completedStages,
+        track,
+        skippedStages,
+        guardEvidence,
+        stageGateCatalog: parseCandidateGateCatalog(typed.stageGateCatalog, fallback.stageGateCatalog)
+    };
+}

package/dist/internal/advance-stage/helpers.d.ts

@@ -0,0 +1,14 @@
+import { type FlowStage } from "../../types.js";
+import { type StageGateState } from "../../flow-state.js";
+export declare function unique<T extends string>(values: T[]): T[];
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+export declare function parseStringList(raw: unknown): string[];
+export declare function isFlowStageValue(value: unknown): value is FlowStage;
+export declare function parseGuardEvidence(value: unknown): Record<string, string>;
+export declare function emptyGateState(): StageGateState;
+export declare function stringifyGateEvidenceValue(value: unknown): string;
+export declare function parseEvidenceByGate(raw: string | undefined): Record<string, string>;
+export declare function parseCsv(raw: string | undefined): string[];
+export declare function pathExists(projectRoot: string, relPath: string): Promise<boolean>;
+export declare function listExistingFiles(projectRoot: string, relPaths: string[]): Promise<string[]>;
+export declare function listFilesUnder(projectRoot: string, relDir: string, limit?: number): Promise<string[]>;