cclaw-cli 6.1.1 → 6.3.0

package/README.md

@@ -68,7 +68,7 @@ Legacy `.cclaw/runs/` directories are only auto-removed when empty. If the direc
 
 That gives you:
 
-- **One path** from idea to ship, with `quick`, `medium`, and `standard` tracks.
+- **One path** from idea to ship, with one user-chosen discovery mode (`lean`, `guided`, `deep`) and internal `quick` / `medium` / `standard` tracks.
 - **Real gates** for evidence, tests, review, delegation, stale-stage recovery, and closeout.
 - **Subagents with accountability**: controller owns state, workers do bounded tasks, overseers validate, evidence lands in `delegation-log.json`.
 - **Recovery instead of confusion**: `npx cclaw-cli sync` tells you blockers and next fixes.
@@ -101,7 +101,7 @@ medium    brainstorm -> spec -> plan -> tdd -> review -> ship
 standard  brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship
 ```
 
-Track selection is **model-guided and advisory** during `/cc`. Runtime enforcement begins after state is written: subsequent `/cc` turns follow the selected track, required gates, delegation rules, stale-stage markers, and `closeout.shipSubstate`.
+At `/cc <idea>`, the user picks **one discovery mode** (`lean`, `guided`, `deep`) for upstream shaping. Track selection remains **model-guided and advisory** during start-up; runtime enforcement begins after state is written: subsequent `/cc` turns follow the selected internal track, persisted `discoveryMode`, required gates, delegation rules, stale-stage markers, and `closeout.shipSubstate`.
 
 ## When Blocked
 

package/dist/artifact-linter/brainstorm.js

@@ -20,7 +20,7 @@ export async function lintBrainstormStage(ctx) {
     });
     if (!brainstormShortCircuitActivated) {
         const skipQuestions = ctx.activeStageFlags.includes("--skip-questions");
-        const floor = evaluateQaLogFloor(qaLogBody, track, "brainstorm", { skipQuestions });
+        const floor = evaluateQaLogFloor(qaLogBody, track, "brainstorm", { discoveryMode: ctx.discoveryMode, skipQuestions });
         findings.push({
             section: "qa_log_unconverged",
             required: !floor.skipQuestionsAdvisory,
@@ -53,7 +53,7 @@ export async function lintBrainstormStage(ctx) {
         const ok = hasDecisionLine;
         findings.push({
             section: "Approach Tier Classification",
-            required: true,
+            required: false,
             rule: "Approach Tier must explicitly classify depth as one of `lite` (a.k.a. `Lightweight`), `Standard`, or `Deep`.",
             found: ok,
             details: ok
@@ -77,14 +77,14 @@ export async function lintBrainstormStage(ctx) {
         });
         findings.push({
             section: "Approaches Role/Upside Taxonomy",
-            required: true,
+            required: false,
             rule: "Approaches table must use canonical Role and Upside enum values.",
             found: approachesTaxonomy.roleUpsideOk,
             details: approachesTaxonomy.details
         });
         findings.push({
             section: "Challenger Alternative Enforcement",
-            required: true,
+            required: false,
             rule: "Approaches must include one challenger option with explicit high/higher upside.",
             found: approachesTaxonomy.challengerOk,
             details: approachesTaxonomy.details
@@ -96,7 +96,7 @@ export async function lintBrainstormStage(ctx) {
         const orderOk = reactionIndex >= 0 && reactionIndex < directionIndex;
         findings.push({
             section: "Approach Reaction Ordering",
-            required: true,
+            required: false,
             rule: "Approach Reaction must appear before Selected Direction (propose -> react -> recommend).",
             found: orderOk,
             details: orderOk
@@ -151,7 +151,7 @@ export async function lintBrainstormStage(ctx) {
         const hasStatus = statusValue.length > 0;
         findings.push({
             section: "Short-Circuit Status",
-            required: true,
+            required: false,
             rule: "Short-Circuit Decision must include a `Status:` line (`activated` or `bypassed`).",
             found: hasStatus,
             details: hasStatus
@@ -187,7 +187,7 @@ export async function lintBrainstormStage(ctx) {
         const selfReview = validateCalibratedSelfReview(selfReviewBody);
         findings.push({
             section: "Calibrated Self-Review Format",
-            required: true,
+            required: false,
             rule: "When Self-Review Notes are present, they must use the calibrated review prompt output shape.",
             found: selfReview.ok,
             details: selfReview.details
@@ -197,7 +197,7 @@ export async function lintBrainstormStage(ctx) {
     if (criticPredictions !== null) {
         findings.push({
             section: "critic.predictions_missing",
-            required: true,
+            required: false,
             rule: "[P2] critic.predictions_missing — pre-commitment predictions block missing or empty",
             found: criticPredictions.found,
             details: criticPredictions.details
@@ -227,7 +227,7 @@ export async function lintBrainstormStage(ctx) {
         const ok = tokenMatches.size === 1 && !isPlaceholder;
         findings.push({
             section: "Mode Block Token",
-            required: true,
+            required: false,
             rule: "Mode Block must declare exactly one mode token: STARTUP, BUILDER, ENGINEERING, OPS, or RESEARCH.",
             found: ok,
             details: ok
@@ -246,7 +246,7 @@ export async function lintBrainstormStage(ctx) {
         /^RECOMMENDATION:/imu.test(raw)) {
         findings.push({
             section: "Approach Detail Cards",
-            required: true,
+            required: false,
             rule: "Approach Detail Cards must include ≥2 `#### APPROACH <letter>` blocks each with Summary/Effort/Risk/Pros/Cons/Reuses.",
             found: cardCount >= 2,
             details: cardCount >= 2
@@ -257,7 +257,7 @@ export async function lintBrainstormStage(ctx) {
         const hasRecommendation = recommendationLine !== null && recommendationLine[1] !== undefined && recommendationLine[1].trim().length > 0;
         findings.push({
             section: "Approach Recommendation Marker",
-            required: true,
+            required: false,
             rule: "Approach Detail Cards must conclude with a single `RECOMMENDATION:` line citing the chosen letter and rationale.",
             found: hasRecommendation,
             details: hasRecommendation
@@ -272,7 +272,7 @@ export async function lintBrainstormStage(ctx) {
         const optedOut = /\bnot used\b|\bn\/a\b|\bnone\b/iu.test(outsideVoiceBody);
         findings.push({
             section: "Outside Voice Slot Shape",
-            required: true,
+            required: false,
             rule: "Outside Voice section must either declare opt-out (`not used`/`none`) or include `source:`, `prompt:`, `tension:`, `resolution:`.",
             found: optedOut || missing.length === 0,
             details: optedOut || missing.length === 0
@@ -337,7 +337,7 @@ export async function lintBrainstormStage(ctx) {
         const waveDriftAddressed = hasCarryForwardSection && hasCarryForwardContent && hasDriftAuditMarkers;
         findings.push({
             section: "wave.drift_unaddressed",
-            required: true,
+            required: false,
             rule: "[P1] wave.drift_unaddressed — when `.cclaw/wave-plans/` has >=2 entries, brainstorm must include `## Wave Carry-forward` with carry-forward and drift audit markers.",
             found: waveDriftAddressed,
             details: waveDriftAddressed

package/dist/artifact-linter/design.js

@@ -284,7 +284,7 @@ export async function lintDesignStage(ctx) {
     });
     {
         const skipQuestions = activeStageFlags.includes("--skip-questions");
-        const floor = evaluateQaLogFloor(qaLogBody, track, "design", { skipQuestions });
+        const floor = evaluateQaLogFloor(qaLogBody, track, "design", { discoveryMode: ctx.discoveryMode, skipQuestions });
         findings.push({
             section: "qa_log_unconverged",
             required: !floor.skipQuestionsAdvisory,
@@ -297,7 +297,7 @@ export async function lintDesignStage(ctx) {
     if (criticPredictions !== null) {
         findings.push({
             section: "critic.predictions_missing",
-            required: true,
+            required: false,
             rule: "[P2] critic.predictions_missing — pre-commitment predictions block missing or empty",
             found: criticPredictions.found,
             details: criticPredictions.details
@@ -390,7 +390,7 @@ export async function lintDesignStage(ctx) {
         const ack = markdownFieldRegex("Iron rule acknowledged", "yes|true|y").test(regressionBody);
         findings.push({
             section: "Regression Iron Rule Acknowledgement",
-            required: true,
+            required: false,
             rule: "Regression Iron Rule section must affirm `Iron rule acknowledged: yes`.",
             found: ack,
             details: ack
@@ -409,7 +409,7 @@ export async function lintDesignStage(ctx) {
         const ok = isEmpty || validRows.length >= 1;
         findings.push({
             section: "Calibrated Finding Format",
-            required: true,
+            required: false,
             rule: "Calibrated Findings must either declare `None this stage` or contain at least one finding in the form `[P1|P2|P3] (confidence: <n>/10) <path>[:<line>] — <description>`.",
             found: ok,
             details: isEmpty
@@ -423,7 +423,7 @@ export async function lintDesignStage(ctx) {
     if (layeredDocumentReview !== null) {
         findings.push({
             section: "Document Reviewer Structured Findings",
-            required: true,
+            required: false,
             rule: "When Layered review references coherence-reviewer/scope-guardian-reviewer/feasibility-reviewer, include explicit reviewer status plus calibrated finding lines.",
             found: layeredDocumentReview.missingStructured.length === 0,
             details: layeredDocumentReview.missingStructured.length === 0

package/dist/artifact-linter/scope.js

@@ -23,7 +23,7 @@ export async function lintScopeStage(ctx) {
     });
     {
         const skipQuestions = activeStageFlags.includes("--skip-questions");
-        const floor = evaluateQaLogFloor(qaLogBody, track, "scope", { skipQuestions });
+        const floor = evaluateQaLogFloor(qaLogBody, track, "scope", { discoveryMode: ctx.discoveryMode, skipQuestions });
         findings.push({
             section: "qa_log_unconverged",
             required: !floor.skipQuestionsAdvisory,
@@ -94,7 +94,7 @@ export async function lintScopeStage(ctx) {
     if (criticPredictions !== null) {
         findings.push({
             section: "critic.predictions_missing",
-            required: true,
+            required: false,
             rule: "[P2] critic.predictions_missing — pre-commitment predictions block missing or empty",
             found: criticPredictions.found,
             details: criticPredictions.details
@@ -139,7 +139,7 @@ export async function lintScopeStage(ctx) {
         }
         findings.push({
             section: "Locked Decisions ID Integrity",
-            required: true,
+            required: false,
             rule: "Locked Decisions section must list each decision with a unique stable D-XX ID. (D-XX IDs replaced the legacy LD#<sha8> hash anchors in Wave 22.)",
             found: issues.length === 0,
             details: issues.length === 0

package/dist/artifact-linter/shared.d.ts

@@ -1,4 +1,4 @@
-import { type FlowStage, type FlowTrack } from "../types.js";
+import { type DiscoveryMode, type FlowStage, type FlowTrack } from "../types.js";
 /**
  * Stages that run adaptive elicitation. The `qa_log_unconverged` rule
  * only fires for these. Other stages may still record a Q&A Log but no
@@ -20,6 +20,7 @@ export interface ForcingQuestionTopic {
     topic: string;
 }
 export interface QaLogFloorOptions {
+    discoveryMode?: DiscoveryMode;
     /**
      * When true, downgrades the finding to advisory (`required: false`).
      * Set when `--skip-questions` was persisted to the active stage flags.
@@ -97,25 +98,22 @@ export declare function extractForcingQuestions(stage: FlowStage): ForcingQuesti
  * design artifact. Returns ok=true when convergence is reached or any
  * escape hatch fires.
  *
- * Convergence sources (any one is sufficient):
- * - All forcing-question topics from the stage checklist appear addressed
- *   in `## Q&A Log` (substring keyword match in question/answer columns).
- * - The Ralph-Loop convergence detector reports the last 2 substantive
- *   rows have decision_impact marking `skip`/`continue`/`no-change`/`done`
- *   (i.e. the dialogue is no longer producing decision-changing rows).
- * - Q&A Log contains a stop-signal row (existing
- *   `QA_LOG_STOP_SIGNAL_PATTERNS` keep working).
- * - `--skip-questions` flag was persisted to the active stage flags
- *   (`options.skipQuestions=true`); finding downgrades to advisory.
- * - The stage checklist exposes no forcing-questions row (e.g. simple
- *   refactor) AND the artifact has at least one substantive row — treat
- *   as converged because there is nothing left to force.
+ * Convergence sources (any one can set ok=true — see also
+ * `adaptiveElicitationSkillMarkdown`):
+ * - Every forcing-question topic id from the stage checklist is tagged
+ *   `[topic:<id>]` on at least one `## Q&A Log` row.
+ * - Ralph-Loop path: last 2 substantive rows read as no-new-decisions,
+ *   substantive count ≥ max(2, questionBudgetHint(discoveryMode, stage).min),
+ *   and not (guided/deep discovery with pending forcing-topic ids).
+ * - Stop-signal row (`QA_LOG_STOP_SIGNAL_PATTERNS`).
+ * - `--skip-questions` (`options.skipQuestions`): ok remains false but
+ *   `skipQuestionsAdvisory` is true (linter treats as non-blocking).
+ * - No forcing-questions row in the checklist and ≥1 substantive row.
  *
- * Wave 23 (v5.0.0) replaces the count-based `qa_log_below_min` rule with
- * `qa_log_unconverged`. The fixed count constant (10 for standard) and
- * the `CCLAW_ELICITATION_FLOOR=advisory` env override were removed. The
- * `min` and `liteShortCircuit` fields on the result are retained for
- * harness UI compatibility but are always 0/false.
+ * Wave 23 retired the fixed English-only count floor; Wave 24 made
+ * `[topic:<id>]` mandatory for topic coverage. The `min` and
+ * `liteShortCircuit` fields stay for harness compatibility (min is always 0;
+ * liteShortCircuit false).
  */
 export declare function evaluateQaLogFloor(qaLogBody: string | null, track: FlowTrack, stage: FlowStage, options?: QaLogFloorOptions): QaLogFloorResult;
 export interface LintFinding {
@@ -448,6 +446,7 @@ export interface StageLintContext {
     projectRoot: string;
     stage: FlowStage;
     track: FlowTrack;
+    discoveryMode: DiscoveryMode;
     raw: string;
     absFile: string;
     sections: H2SectionMap;

package/dist/artifact-linter/shared.js

@@ -207,25 +207,22 @@ function lastTwoRowsAllNoDecision(substantiveRows) {
  * design artifact. Returns ok=true when convergence is reached or any
  * escape hatch fires.
  *
- * Convergence sources (any one is sufficient):
- * - All forcing-question topics from the stage checklist appear addressed
- *   in `## Q&A Log` (substring keyword match in question/answer columns).
- * - The Ralph-Loop convergence detector reports the last 2 substantive
- *   rows have decision_impact marking `skip`/`continue`/`no-change`/`done`
- *   (i.e. the dialogue is no longer producing decision-changing rows).
- * - Q&A Log contains a stop-signal row (existing
- *   `QA_LOG_STOP_SIGNAL_PATTERNS` keep working).
- * - `--skip-questions` flag was persisted to the active stage flags
- *   (`options.skipQuestions=true`); finding downgrades to advisory.
- * - The stage checklist exposes no forcing-questions row (e.g. simple
- *   refactor) AND the artifact has at least one substantive row — treat
- *   as converged because there is nothing left to force.
+ * Convergence sources (any one can set ok=true — see also
+ * `adaptiveElicitationSkillMarkdown`):
+ * - Every forcing-question topic id from the stage checklist is tagged
+ *   `[topic:<id>]` on at least one `## Q&A Log` row.
+ * - Ralph-Loop path: last 2 substantive rows read as no-new-decisions,
+ *   substantive count ≥ max(2, questionBudgetHint(discoveryMode, stage).min),
+ *   and not (guided/deep discovery with pending forcing-topic ids).
+ * - Stop-signal row (`QA_LOG_STOP_SIGNAL_PATTERNS`).
+ * - `--skip-questions` (`options.skipQuestions`): ok remains false but
+ *   `skipQuestionsAdvisory` is true (linter treats as non-blocking).
+ * - No forcing-questions row in the checklist and ≥1 substantive row.
  *
- * Wave 23 (v5.0.0) replaces the count-based `qa_log_below_min` rule with
- * `qa_log_unconverged`. The fixed count constant (10 for standard) and
- * the `CCLAW_ELICITATION_FLOOR=advisory` env override were removed. The
- * `min` and `liteShortCircuit` fields on the result are retained for
- * harness UI compatibility but are always 0/false.
+ * Wave 23 retired the fixed English-only count floor; Wave 24 made
+ * `[topic:<id>]` mandatory for topic coverage. The `min` and
+ * `liteShortCircuit` fields stay for harness compatibility (min is always 0;
+ * liteShortCircuit false).
  */
 export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
     const rows = qaLogBody !== null ? getMarkdownTableRows(qaLogBody) : [];
@@ -233,6 +230,7 @@ export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
     const count = substantiveRows.length;
     const hasStopSignal = detectStopSignal(rows);
     const skipQuestionsAdvisory = options.skipQuestions === true;
+    const discoveryMode = options.discoveryMode ?? (track === "quick" ? "lean" : "guided");
     const forcingTopics = (options.forcingQuestions ?? extractForcingQuestions(stage)).map((entry) => (typeof entry === "string" ? { id: entry, topic: entry } : entry));
     const forcingCovered = [];
     const forcingPending = [];
@@ -242,9 +240,13 @@ export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
         else
             forcingPending.push(topic.id);
     }
+    const budget = questionBudgetHint(discoveryMode, stage);
     const noNewDecisions = lastTwoRowsAllNoDecision(substantiveRows);
     const allForcingCovered = forcingTopics.length > 0 ? forcingPending.length === 0 : count >= 1;
-    const ok = allForcingCovered || noNewDecisions || hasStopSignal;
+    const minimumRowsReached = count >= Math.max(2, budget.min);
+    const riskEscalationNeeded = forcingPending.length > 0 && /^(guided|deep)$/u.test(discoveryMode);
+    const noNewDecisionConverged = noNewDecisions && minimumRowsReached && !riskEscalationNeeded;
+    const ok = allForcingCovered || noNewDecisionConverged || hasStopSignal;
     const pendingIdsBracket = forcingPending.length > 0
         ? `[${forcingPending.join(", ")}]`
         : "[none]";
@@ -256,10 +258,10 @@ export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
         else if (allForcingCovered) {
             details = `Q&A Log converged: stage exposes no forcing-questions row and ${count} substantive entry recorded.`;
         }
-        else if (noNewDecisions) {
+        else if (noNewDecisionConverged) {
             const remaining = forcingPending.length > 0
-                ? ` ${forcingPending.length} forcing topic IDs still pending: ${pendingIdsBracket} (Ralph-Loop convergence overrode coverage).`
-                : " Ralph-Loop convergence detector says no new decision-changing rows in the last 2 turns.";
+                ? ` ${forcingPending.length} forcing topic IDs still pending: ${pendingIdsBracket} after the minimum ${budget.min}-row discovery pass.`
+                : ` Ralph-Loop convergence detector says no new decision-changing rows in the last 2 turns after the minimum ${budget.min}-row discovery pass.`;
             details = `Q&A Log converged via no-new-decisions detector at ${count} row(s).${remaining}`;
         }
         else {
@@ -269,27 +271,28 @@ export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
     else if (skipQuestionsAdvisory) {
         details = `Q&A Log unconverged at ${count} row(s); --skip-questions flag downgraded the finding to advisory. Forcing topic IDs pending: ${pendingIdsBracket}.`;
     }
+    else if (noNewDecisions && !minimumRowsReached) {
+        details = `Q&A Log still below the minimum ${budget.min}-row ${discoveryMode} discovery pass (${count} substantive row(s)). Forcing topic IDs pending: ${pendingIdsBracket}. Continue asking decision-changing questions before drafting.`;
+    }
+    else if (riskEscalationNeeded && noNewDecisions) {
+        details = `Q&A Log cannot converge via Ralph-Loop yet because ${discoveryMode} mode keeps pending forcing topic IDs blocking: ${pendingIdsBracket}. Cover the remaining topics or record an explicit stop-signal row.`;
+    }
     else {
-        details = `Q&A Log unconverged at ${count} row(s). Forcing topic IDs pending: ${pendingIdsBracket}. Tag each Q&A row with \`[topic:<id>]\` to mark coverage, append a no-new-decisions pair, or record an explicit user stop-signal row.`;
+        details = `Q&A Log unconverged at ${count} row(s). Forcing topic IDs pending: ${pendingIdsBracket}. Tag each Q&A row with \`[topic:<id>]\` to mark coverage, complete the minimum ${budget.min}-row ${discoveryMode} discovery pass, or record an explicit user stop-signal row.`;
     }
-    // Surface advisory budget hint for harness UI without re-introducing a
-    // blocking count. `recommended` is the soft budget per track/stage.
-    const advisoryBudget = questionBudgetHint(track, stage).recommended;
+    const advisoryBudget = budget.recommended;
     return {
         ok,
         count,
-        // Wave 23: floor no longer enforces a count. Surfacing 0 keeps the
-        // QaLogFloorSignal shape stable for harness consumers; harness UIs
-        // may show `recommended` from `questionBudgetHint` separately.
         min: 0,
         hasStopSignal,
         liteShortCircuit: false,
         skipQuestionsAdvisory,
         forcingCovered,
         forcingPending,
-        noNewDecisions,
+        noNewDecisions: noNewDecisionConverged,
         details: advisoryBudget > 0
-            ? `${details} (advisory budget for ${track}/${stage}: ~${advisoryBudget} Q&A turns)`
+            ? `${details} (advisory budget for ${discoveryMode}/${stage}: ~${advisoryBudget} Q&A turns)`
             : details
     };
 }

package/dist/artifact-linter.js

@@ -114,6 +114,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
     // Same flow-state read powers the post-loop demotion + audit log
     // below; we cache the result here to avoid two disk reads.
     let activeStageFlags = [];
+    let discoveryMode = "guided";
     let taskClass = null;
     let activeRunId = null;
     try {
@@ -121,11 +122,13 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         const hint = flowState.interactionHints?.[stage];
         if (hint?.skipQuestions === true)
             activeStageFlags.push("--skip-questions");
+        discoveryMode = flowState.discoveryMode ?? "guided";
         taskClass = flowState.taskClass ?? null;
         activeRunId = flowState.activeRunId ?? null;
     }
     catch {
         activeStageFlags = [];
+        discoveryMode = "guided";
         taskClass = null;
         activeRunId = null;
     }
@@ -195,6 +198,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         projectRoot,
         stage,
         track,
+        discoveryMode,
         raw,
         absFile,
         sections,

package/dist/content/hooks.js

@@ -185,13 +185,13 @@ void main();
 `;
 }
 export function startFlowScript() {
-    return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]", { defaultQuietEnvVar: "CCLAW_START_FLOW_QUIET" });
+    return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--discovery-mode=<lean|guided|deep>] [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]", { defaultQuietEnvVar: "CCLAW_START_FLOW_QUIET" });
 }
 export function cancelRunScript() {
     return internalHelperScript("cancel-run", "cancel-run", "Usage: node " + RUNTIME_ROOT + "/hooks/cancel-run.mjs --reason=<text> [--disposition=<cancelled|abandoned>] [--name=<slug>]");
 }
 export function stageCompleteScript() {
-    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--accept-proactive-waiver] [--accept-proactive-waiver-reason=...] [--skip-questions] [--json]", {
+    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--accept-proactive-waiver] [--accept-proactive-waiver-reason=\"<why safe>\"] [--skip-questions] [--json]", {
         positionalArgName: "stage",
         positionalArgRequired: true,
         defaultQuietEnvVar: "CCLAW_STAGE_COMPLETE_QUIET"
@@ -296,6 +296,7 @@ function usage() {
     "Usage:",
     "  node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--json]",
     "  node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--json]",
+    "  node .cclaw/hooks/delegation-record.mjs --repair --span-id=<id> --repair-reason=\"<why>\" [--json]",
     "",
     "Allowed --dispatch-surface values:",
     "  " + VALID_DISPATCH_SURFACES.join(", "),
@@ -496,10 +497,161 @@ async function runRerecord(args, json) {
   process.stdout.write(JSON.stringify({ ok: true, event, rerecord: true }, null, 2) + "\\n");
 }
 
+const LIFECYCLE_PHASES = ["scheduled", "launched", "acknowledged", "completed"];
+
+function mergeSpanTemplate(spanEvents) {
+  const base = {};
+  const keys = [
+    "stage",
+    "agent",
+    "mode",
+    "runId",
+    "dispatchId",
+    "dispatchSurface",
+    "agentDefinitionPath",
+    "workerRunId",
+    "fulfillmentMode",
+    "schemaVersion",
+    "parentSpanId",
+    "evidenceRefs",
+    "waiverReason"
+  ];
+  for (const e of spanEvents) {
+    if (!e || typeof e !== "object") continue;
+    for (const k of keys) {
+      if (base[k] === undefined && e[k] !== undefined) {
+        base[k] = e[k];
+      }
+    }
+  }
+  return base;
+}
+
+function repairFulfillmentMode(base) {
+  if (base.fulfillmentMode) return base.fulfillmentMode;
+  if (base.dispatchSurface === "role-switch") return "role-switch";
+  if (base.dispatchSurface === "cursor-task" || base.dispatchSurface === "generic-task") {
+    return "generic-dispatch";
+  }
+  return "isolated";
+}
+
+async function runRepair(args, json) {
+  const problems = [];
+  if (!args["span-id"]) problems.push("repair mode requires --span-id");
+  if (!args["repair-reason"] || String(args["repair-reason"]).trim().length === 0) {
+    problems.push("repair mode requires --repair-reason=<text>");
+  }
+  if (problems.length > 0) {
+    emitProblems(problems, json, 2);
+    return;
+  }
+  const spanId = args["span-id"];
+  const repairedReason = String(args["repair-reason"]).trim();
+  const root = await detectRoot();
+  const events = await readDelegationEvents(root);
+  const spanEvents = events.filter(
+    (e) => e && e.spanId === spanId && typeof e.event === "string" && LIFECYCLE_PHASES.includes(e.event)
+  );
+  if (spanEvents.length === 0) {
+    emitProblems(
+      ["repair refused: no lifecycle delegation-events.jsonl rows found for --span-id=" + spanId],
+      json,
+      2
+    );
+    return;
+  }
+  const present = new Set(spanEvents.map((e) => e.event));
+  const base = mergeSpanTemplate(spanEvents);
+  if (!base.stage || !base.agent || !base.mode) {
+    emitProblems(["repair refused: span events missing stage/agent/mode to clone"], json, 2);
+    return;
+  }
+  const runId =
+    typeof base.runId === "string" && base.runId.length > 0 ? base.runId : await readRunId(root);
+  const fulfillmentMode = repairFulfillmentMode(base);
+  const schemaVersion =
+    typeof base.schemaVersion === "number" && base.schemaVersion > 0
+      ? base.schemaVersion
+      : LEDGER_SCHEMA_VERSION;
+  const evidenceRefs = Array.isArray(base.evidenceRefs)
+    ? base.evidenceRefs.filter((r) => typeof r === "string" && r.trim().length > 0)
+    : [];
+  const now = new Date().toISOString();
+  const appended = [];
+
+  for (const status of LIFECYCLE_PHASES) {
+    if (present.has(status)) continue;
+    if (status === "completed" && base.dispatchSurface !== "role-switch") {
+      if (!base.dispatchId || !base.dispatchSurface || !base.agentDefinitionPath) {
+        emitProblems(
+          [
+            "repair refused: cannot synthesize completed row without dispatchId, dispatchSurface, and agentDefinitionPath on span " +
+              spanId
+          ],
+          json,
+          2
+        );
+        return;
+      }
+    }
+    if (status === "completed" && base.dispatchSurface === "role-switch" && evidenceRefs.length === 0) {
+      emitProblems(
+        ["repair refused: role-switch completed synthesis requires evidenceRefs on span " + spanId],
+        json,
+        2
+      );
+      return;
+    }
+    const launchedTs =
+      status === "launched" || status === "acknowledged" || status === "completed" ? now : undefined;
+    const ackTs = status === "acknowledged" || status === "completed" ? now : undefined;
+    const completedTs = status === "completed" ? now : undefined;
+    const endTs = status === "completed" ? now : undefined;
+    const row = {
+      stage: base.stage,
+      agent: base.agent,
+      mode: base.mode,
+      status,
+      spanId,
+      dispatchId: base.dispatchId,
+      workerRunId: base.workerRunId,
+      dispatchSurface: base.dispatchSurface,
+      agentDefinitionPath: base.agentDefinitionPath,
+      fulfillmentMode,
+      evidenceRefs,
+      runId,
+      startTs: now,
+      ts: now,
+      launchedTs,
+      ackTs,
+      completedTs,
+      endTs,
+      schemaVersion
+    };
+    const clean = Object.fromEntries(Object.entries(row).filter(([, value]) => value !== undefined));
+    const event = { ...clean, event: status, eventTs: now, repairedAt: now, repairedReason };
+    await persistEntry(root, runId, clean, event);
+    present.add(status);
+    appended.push(status);
+  }
+
+  if (json) {
+    process.stdout.write(
+      JSON.stringify({ ok: true, repair: true, spanId, appended, repairedAt: now, repairedReason }, null, 2) + "\\n"
+    );
+  }
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const json = args.json !== undefined;
 
+  if (args.repair) {
+    await runRepair(args, json);
+    return;
+  }
+
   if (args.rerecord) {
     await runRerecord(args, json);
     return;