cclaw-cli 6.2.0 → 6.3.0

package/dist/content/hooks.js

@@ -191,7 +191,7 @@ 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=...] [--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;

package/dist/content/skills.js

@@ -389,6 +389,7 @@ function completionParametersBlock(schema, track) {
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
 - Record mandatory delegation lifecycle in \`${RUNTIME_ROOT}/state/delegation-log.json\` and append proof events to \`${RUNTIME_ROOT}/state/delegation-events.jsonl\`; the ledger is current state, the event log is audit proof.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""} If proactive delegations were intentionally skipped, rerun only with \`--accept-proactive-waiver\` (optionally \`--accept-proactive-waiver-reason="<why safe>"\`) after explicit user approval.
 - Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If a helper fails, report a one-line human-readable failure plus fenced JSON diagnostics; never echo the invoking command line or apply a manual state workaround.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.
 - Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;
 }

package/dist/content/stage-schema.js

@@ -498,7 +498,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             runPhase: "post-elicitation",
             when: "When repository, market, docs, or prior-art context changes the approach set. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Provide search-before-read summaries and context-readiness evidence before large reads or decisions.",
-            requiresUserGate: false
+            requiresUserGate: false,
+            dependsOnInternalRepoSignals: true
         }
     ],
     scope: [
@@ -535,7 +536,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             runPhase: "post-elicitation",
             when: "When churn, prior attempts, reference patterns, or external constraints may change scope boundaries. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Summarize search/context findings before the scope contract locks accepted/rejected/deferred ideas.",
-            requiresUserGate: false
+            requiresUserGate: false,
+            dependsOnInternalRepoSignals: true
         },
         {
             agent: "product-discovery",

package/dist/content/stages/schema-types.d.ts

@@ -53,6 +53,12 @@ export interface StageAutoSubagentDispatch {
     returnSchema?: StageSubagentReturnSchema;
     /** Optional skill folder the dispatched agent should load as additional context. */
     skill?: string;
+    /**
+     * When true, proactive trace requirements for this row may be skipped on an
+     * empty/sparse repo (see `ensureProactiveDelegationTrace`). Used for
+     * `researcher` on early elicitation stages in deep discovery mode.
+     */
+    dependsOnInternalRepoSignals?: boolean;
 }
 export type StageComplexityTier = "lightweight" | "standard" | "deep";
 export interface StagePhilosophy {

package/dist/content/start-command.js

@@ -87,6 +87,8 @@ ${conversationLanguagePolicyMarkdown()}
    > \`Choose discovery mode: Lean / Guided / Deep\`.
    > \`Lean\` = compact shaping, \`Guided\` = recommended default with enough questions and key specialists before drafting, \`Deep\` = stronger probing and broader specialist/research passes.
    > Mention the internal track recommendation only as context, not as the primary decision. Offer track override only when reset, contradiction, or reclassification evidence makes the internal recommendation suspect.
+   Normalize the user's answer before calling the start helper: \`trim\`, lower-case, map UI labels to \`lean\` / \`guided\` / \`deep\` only; if the answer is not one of those three, re-ask the same question once with the compact definitions. In \`flow-state.json\`, persist only the canonical lowercase token (never \`Deep\`/\`Guided\` casing).
+   If the user prompt is one short line (at most 12 words) and the workspace matches an empty-repo signal set — either \`flow-state.repoSignals\` from the last successful \`start-flow\` shows \`fileCount < 5\` with \`hasReadme\` and \`hasPackageManifest\` both false, OR (before any \`start-flow\` yet) a shallow scan finds no root \`README.md\`, no root \`package.json\`/\`pyproject.toml\`/\`Cargo.toml\`, and fewer than five relevant files excluding \`node_modules\`/\`.git\` — recommend \`guided\` and ask for explicit confirmation before defaulting to \`deep\`.
    If the harness's native ask tool is available (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` / \`request_user_input\`), send exactly ONE question; on schema error, fall back to a plain-text lettered list.
 10. Start the tracked flow only through the managed helper:
    \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --discovery-mode=<lean|guided|deep> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`
@@ -188,8 +190,10 @@ ${conversationLanguagePolicyMarkdown()}
    - On conflict, prefer \`standard\` over \`medium\`, and \`medium\` over \`quick\`.
    - Always state the recommendation as a one-line reason citing matched triggers and a high/medium/low track selection confidence. Clarify that the heuristic is advisory until the managed helper writes state; after that, \`/cc\` follows the selected track. Include override guidance: switch to standard when architecture, schema, migration, security, or unclear scope appears; switch to medium when product framing is needed but architecture is known.
 8. Ask for the single explicit start choice: \`Lean / Guided / Deep\`. Use \`Guided\` as the recommended default unless the user clearly wants compact shaping or unusually deep probing. Keep track internal unless contradiction/reset/reclassification requires surfacing an override.
+   Normalize the answer (\`trim\`, lower-case) to exactly \`lean\` / \`guided\` / \`deep\` before invoking the start helper; re-ask once if the reply is not one of those. Pass only canonical lowercase tokens to \`--discovery-mode\`.
+   If the prompt is one short line (at most 12 words) and the workspace matches an empty-repo signal set — either persisted \`repoSignals\` has \`fileCount < 5\` with \`hasReadme\` and \`hasPackageManifest\` false, OR a shallow scan before the first \`start-flow\` shows the same — recommend \`guided\` and confirm before defaulting to \`deep\`.
 9. Run the managed start helper: \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --discovery-mode=<lean|guided|deep> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, including \`discoveryMode\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP, report one human-readable failure line from the JSON \`error\` field, and include the helper JSON payload in a fenced \`json\` block; do not echo the invoking command line, and do not manually edit flow state.
-9. Load and execute the **first stage skill of the chosen track** (\`brainstorm\` for medium/standard, \`spec\` for quick) plus its matching command file.
+10. Load and execute the **first stage skill of the chosen track** (\`brainstorm\` for medium/standard, \`spec\` for quick) plus its matching command file.
 
 ### Reclassification on discovery
 

package/dist/content/templates.d.ts

@@ -7,5 +7,5 @@ export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n-
  * (premature draft, premature subagent dispatch, command-line echo to chat).
  */
 export declare const CURSOR_GUIDELINES_RULE_MDC = "---\ndescription: cclaw zero-install behavior baseline (always-on)\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-guidelines-rule -->\n\n# Cclaw Baseline Guidelines\n\nThese three rules apply to every Cursor agent session in this project,\nregardless of whether stage skills loaded.\n\n## 1. Q&A floor before drafting (brainstorm/scope/design)\n\nBefore drafting any `.cclaw/artifacts/01-brainstorm-*.md`,\n`02-scope-*.md`, or `03-design-*.md`, verify that the artifact's\n`## Q&A Log` table demonstrates Ralph-Loop convergence: every\nforcing-question topic id is tagged `[topic:<id>]` on at least one row\n(see the stage's forcing-questions checklist for the id list), the last\n2 turns produce no new decision-changing impact, OR an explicit user\nstop-signal row is recorded. Walk the stage forcing questions one at a\ntime via the `AskQuestion` tool. If you find yourself proposing a\ndraft after 1-2 questions while forcing topic ids remain untagged, STOP\nand continue the loop.\n\nThe `qa_log_unconverged` linter rule will block `stage-complete` when\nconvergence has not been reached. Wave 24 (v6.0.0) made `[topic:<id>]`\ntagging mandatory; the English keyword fallback was removed because it\nmis-reported convergence on RU/UA Q&A logs.\n\n## 2. Mandatory subagents run after Q&A approval\n\nFor brainstorm / scope / design, mandatory subagents (\n`product-discovery`, `critic`, `planner`, `architect`,\n`test-author`) run **only AFTER the user approves the elicitation\noutcome**, never before the Q&A loop converges. Dispatching them early\npreempts the user dialogue and violates the elicitation contract \u2014 the\nlinter will block stage-complete.\n\nSee each stage's \"Run Phase: post-elicitation\" rows in the materialized\nAutomatic Subagent Dispatch table.\n\n## 3. Never echo cclaw command lines to chat\n\nThe user does not run cclaw helpers (`node .cclaw/hooks/...`) manually.\nNEVER paste full command lines, `--evidence-json '{...}'` payloads,\n`--waive-delegation=...`, or shell hash commands (`shasum`,\n`sha256sum`, `Get-FileHash`, `certutil`, etc.) into chat. Run the\nhelper via the tool layer and report only the resulting summary. On\nfailure, report a compact human-readable summary plus the helper JSON in\na single fenced `json` block.\n";
-export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive through closeout via `/cc` or cancel early via `node .cclaw/hooks/cancel-run.mjs`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool \u2014 `AskQuestion` in Cursor). Walk the stage forcing-questions list one-by-one. **Tag each Q&A Log row's `Decision impact` cell with `[topic:<id>]`** (the id is given in the stage's forcing-questions checklist) so the linter can verify coverage in any natural language. Do NOT batch and do NOT defer to a single approval gate at the end. The `qa_log_unconverged` linter rule will block `stage-complete` when convergence is not reached (forcing topic ids untagged AND last 2 turns still produce decision-changing rows AND no stop-signal).\n- **For other stages** (spec/plan/tdd/build/review/ship): ask user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization), not for routine progress updates.\n- If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP \u2014 go back to the forcing-questions list and continue.\n- Mandatory subagents in brainstorm/scope/design run only AFTER the user approves the elicitation outcome (see each stage's \"Run Phase: post-elicitation\" rows). Dispatching them before the Q&A loop converges violates the contract.\n- Never echo cclaw command lines (`node .cclaw/hooks/...`, `--evidence-json '{...}'`) to chat \u2014 the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
+export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Stage completion claim requires `stage-complete` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive through closeout via `/cc` or cancel early via `node .cclaw/hooks/cancel-run.mjs`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool \u2014 `AskQuestion` in Cursor). Walk the stage forcing-questions list one-by-one. **Tag each Q&A Log row's `Decision impact` cell with `[topic:<id>]`** (the id is given in the stage's forcing-questions checklist) so the linter can verify coverage in any natural language. Do NOT batch and do NOT defer to a single approval gate at the end. The `qa_log_unconverged` linter rule will block `stage-complete` when convergence is not reached (forcing topic ids untagged AND last 2 turns still produce decision-changing rows AND no stop-signal).\n- **For other stages** (spec/plan/tdd/build/review/ship): ask user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization), not for routine progress updates.\n- If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP \u2014 go back to the forcing-questions list and continue.\n- Mandatory subagents in brainstorm/scope/design run only AFTER the user approves the elicitation outcome (see each stage's \"Run Phase: post-elicitation\" rows). Dispatching them before the Q&A loop converges violates the contract.\n- Never echo cclaw command lines (`node .cclaw/hooks/...`, `--evidence-json '{...}'`) to chat \u2014 the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -1565,6 +1565,7 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 ## Verification Discipline
 
 - No completion claim without fresh command evidence in this turn.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.
 - Do not mark gates passed from memory.
 - Keep evidence in \`.cclaw/artifacts/\`; archive through closeout via \`/cc\` or cancel early via \`node .cclaw/hooks/cancel-run.mjs\`.
 

package/dist/flow-state.d.ts

@@ -1,6 +1,13 @@
 import type { DiscoveryMode, FlowStage, FlowTrack, TransitionRule } from "./types.js";
 export declare const TRANSITION_RULES: TransitionRule[];
 export declare const FLOW_STATE_SCHEMA_VERSION = 1;
+/** Snapshot from `collectRepoSignals` at last successful `start-flow` (optional on older states). */
+export interface RepoSignals {
+    fileCount: number;
+    hasReadme: boolean;
+    hasPackageManifest: boolean;
+    capturedAt: string;
+}
 export interface StageGateState {
     required: string[];
     recommended: string[];
@@ -104,6 +111,8 @@ export interface FlowState {
     retro: RetroState;
     /** Ship → post_ship_review → archive substate for resumable closeout. */
     closeout: CloseoutState;
+    /** Repo shape signals captured at last successful start-flow (omit on legacy files). */
+    repoSignals?: RepoSignals;
 }
 export interface StageInteractionHint {
     skipQuestions?: boolean;

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

@@ -434,6 +434,19 @@ export async function runAdvanceStage(projectRoot, args, io) {
         extraStageFlags: args.skipQuestions ? ["--skip-questions"] : undefined
     });
     if (!validation.ok) {
+        const delegationFailureCount = validation.delegation.missing.length +
+            validation.delegation.missingEvidence.length +
+            validation.delegation.missingDispatchProof.length +
+            validation.delegation.legacyInferredCompletions.length +
+            validation.delegation.corruptEventLines.length +
+            validation.delegation.staleWorkers.length;
+        const gatesFailureCount = validation.gates.issues.length;
+        const closureFailureCount = validation.completedStages.issues.length;
+        const failureCounts = {
+            delegation: delegationFailureCount,
+            gates: gatesFailureCount,
+            closure: closureFailureCount
+        };
         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(() => "");
@@ -482,6 +495,7 @@ export async function runAdvanceStage(projectRoot, args, io) {
                 command: "advance-stage",
                 stage: args.stage,
                 kind: "validation-failed",
+                failureCounts,
                 delegation: validation.delegation,
                 gates: validation.gates,
                 completedStages: validation.completedStages,
@@ -493,7 +507,7 @@ export async function runAdvanceStage(projectRoot, args, io) {
                 nextActions
             })}\n`);
         }
-        io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}".\n`);
+        io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}" (delegation=${failureCounts.delegation}, gates=${failureCounts.gates}, closure=${failureCounts.closure}).\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`);
@@ -531,7 +545,8 @@ export async function runAdvanceStage(projectRoot, args, io) {
     const proactiveTrace = await ensureProactiveDelegationTrace(projectRoot, args.stage, {
         acceptWaiver: args.acceptProactiveWaiver,
         waiverReason: args.acceptProactiveWaiverReason,
-        discoveryMode: flowState.discoveryMode
+        discoveryMode: flowState.discoveryMode,
+        repoSignals: flowState.repoSignals
     });
     if (proactiveTrace.missingRules.length > 0) {
         const missingSummary = proactiveTrace.missingRules

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

@@ -248,10 +248,11 @@ export function parseStartFlowArgs(tokens) {
         }
         if (token === "--discovery-mode" || token.startsWith("--discovery-mode=")) {
             const raw = readValue("--discovery-mode").trim();
-            if (!isDiscoveryMode(raw)) {
+            const normalized = raw.toLowerCase();
+            if (!isDiscoveryMode(normalized)) {
                 throw new Error(`--discovery-mode must be one of: lean, guided, deep.`);
             }
-            discoveryMode = raw;
+            discoveryMode = normalized;
             continue;
         }
         if (token === "--class" || token.startsWith("--class=")) {

package/dist/internal/advance-stage/proactive-delegation-trace.d.ts

@@ -1,5 +1,6 @@
 import { type StageAutoSubagentDispatch } from "../../content/stage-schema.js";
 import type { DiscoveryMode, FlowStage } from "../../types.js";
+import type { RepoSignals } from "../../flow-state.js";
 export interface ProactiveDelegationTraceResult {
     missingRules: StageAutoSubagentDispatch[];
 }
@@ -16,4 +17,5 @@ export declare function ensureProactiveDelegationTrace(projectRoot: string, stag
     acceptWaiver: boolean;
     waiverReason?: string;
     discoveryMode: DiscoveryMode;
+    repoSignals?: RepoSignals;
 }): Promise<ProactiveDelegationTraceResult>;

package/dist/internal/advance-stage/proactive-delegation-trace.js

@@ -3,6 +3,20 @@ import { stageAutoSubagentDispatch } from "../../content/stage-schema.js";
 function isEarlyElicitationStage(stage) {
     return stage === "brainstorm" || stage === "scope" || stage === "design";
 }
+function isSparseRepoForResearcherSkip(repoSignals) {
+    if (!repoSignals)
+        return false;
+    return repoSignals.fileCount < 5 && !repoSignals.hasReadme && !repoSignals.hasPackageManifest;
+}
+function skipRepoDependentProactiveRule(rule, stage, discoveryMode, repoSignals) {
+    if (discoveryMode !== "deep")
+        return false;
+    if (stage !== "brainstorm" && stage !== "scope")
+        return false;
+    if (!rule.dependsOnInternalRepoSignals)
+        return false;
+    return isSparseRepoForResearcherSkip(repoSignals);
+}
 /**
  * Ensure every proactive dispatch rule for the stage has a ledger row for the
  * active run, or an explicit user-flag waiver.
@@ -16,7 +30,9 @@ export async function ensureProactiveDelegationTrace(projectRoot, stage, options
     if (isEarlyElicitationStage(stage) && (options.discoveryMode === "lean" || options.discoveryMode === "guided")) {
         return { missingRules: [] };
     }
-    const proactiveRules = stageAutoSubagentDispatch(stage).filter((rule) => rule.mode === "proactive");
+    const proactiveRules = stageAutoSubagentDispatch(stage)
+        .filter((rule) => rule.mode === "proactive")
+        .filter((rule) => !skipRepoDependentProactiveRule(rule, stage, options.discoveryMode, options.repoSignals));
     if (proactiveRules.length === 0)
         return { missingRules: [] };
     const ledger = await readDelegationLedger(projectRoot);

package/dist/internal/advance-stage/start-flow.d.ts

@@ -1,10 +1,12 @@
-import { type FlowState } from "../../flow-state.js";
+import { type FlowState, type RepoSignals } from "../../flow-state.js";
 import type { StartFlowArgs } from "./parsers.js";
 import type { Writable } from "node:stream";
 interface InternalIo {
     stdout: Writable;
     stderr: Writable;
 }
+/** One-pass repo snapshot (max ~200 files, skips `node_modules`/`.git`). */
+export declare function collectRepoSignals(projectRoot: string): Promise<RepoSignals>;
 export declare function discoverStartFlowContext(projectRoot: string): Promise<string[]>;
 export declare function appendIdeaArtifact(projectRoot: string, args: StartFlowArgs, previous?: FlowState): Promise<void>;
 export declare function runStartFlow(projectRoot: string, args: StartFlowArgs, io: InternalIo): Promise<number>;

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

@@ -13,6 +13,68 @@ function resolveTaskClass(className, fallback) {
     }
     return fallback;
 }
+const REPO_SIGNAL_SKIP_DIRS = new Set(["node_modules", ".git"]);
+/** One-pass repo snapshot (max ~200 files, skips `node_modules`/`.git`). */
+export async function collectRepoSignals(projectRoot) {
+    const capturedAt = new Date().toISOString();
+    const cap = 200;
+    let fileCount = 0;
+    async function visit(absDir, depth) {
+        if (fileCount >= cap)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (fileCount >= cap)
+                return;
+            const name = ent.name;
+            if (REPO_SIGNAL_SKIP_DIRS.has(name))
+                continue;
+            const abs = path.join(absDir, name);
+            if (ent.isFile()) {
+                fileCount += 1;
+                continue;
+            }
+            if (ent.isDirectory() && depth < 1) {
+                await visit(abs, depth + 1);
+            }
+        }
+    }
+    let hasReadme = false;
+    let hasPackageManifest = false;
+    for (const fname of ["README.md", "readme.md", "Readme.md"]) {
+        try {
+            const st = await fs.stat(path.join(projectRoot, fname));
+            if (st.isFile())
+                hasReadme = true;
+        }
+        catch {
+            // ignore
+        }
+    }
+    for (const manifest of ["package.json", "pyproject.toml", "Cargo.toml"]) {
+        try {
+            const st = await fs.stat(path.join(projectRoot, manifest));
+            if (st.isFile())
+                hasPackageManifest = true;
+        }
+        catch {
+            // ignore
+        }
+    }
+    try {
+        await visit(projectRoot, 0);
+    }
+    catch {
+        fileCount = Math.min(fileCount, cap);
+    }
+    return { fileCount, hasReadme, hasPackageManifest, capturedAt };
+}
 export async function discoverStartFlowContext(projectRoot) {
     const lines = [];
     const seedFiles = (await listFilesUnder(projectRoot, path.join(RUNTIME_ROOT, "seeds"), 10))
@@ -145,6 +207,8 @@ export async function runStartFlow(projectRoot, args, io) {
             }
         };
     }
+    const repoSignals = await collectRepoSignals(projectRoot);
+    nextState = { ...nextState, repoSignals };
     await writeFlowState(projectRoot, nextState, { allowReset: true });
     await appendIdeaArtifact(projectRoot, args, current);
     if (!args.quiet) {

package/dist/run-persistence.js

@@ -163,7 +163,32 @@ function coerceTrack(value) {
     return isFlowTrack(value) ? value : "standard";
 }
 function coerceDiscoveryMode(value) {
-    return isDiscoveryMode(value) ? value : "guided";
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (isDiscoveryMode(normalized))
+            return normalized;
+    }
+    return "guided";
+}
+function coerceRepoSignals(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const typed = value;
+    const fileCountRaw = typed.fileCount;
+    const fileCount = typeof fileCountRaw === "number" && Number.isFinite(fileCountRaw) && fileCountRaw >= 0
+        ? Math.min(Math.floor(fileCountRaw), 1_000_000)
+        : undefined;
+    const capturedAt = typeof typed.capturedAt === "string" ? typed.capturedAt.trim() : "";
+    if (fileCount === undefined || !capturedAt) {
+        return undefined;
+    }
+    return {
+        fileCount,
+        hasReadme: typed.hasReadme === true,
+        hasPackageManifest: typed.hasPackageManifest === true,
+        capturedAt
+    };
 }
 /**
  * Wave 24 follow-up (v6.1.1) — preserve `flow-state.json#taskClass`
@@ -385,6 +410,7 @@ function coerceFlowState(parsed) {
         ? activeRunIdRaw.trim()
         : next.activeRunId;
     const taskClass = coerceTaskClass(parsed.taskClass);
+    const repoSignals = coerceRepoSignals(parsed.repoSignals);
     const state = {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         activeRunId,
@@ -395,6 +421,7 @@ function coerceFlowState(parsed) {
         track,
         discoveryMode,
         ...(taskClass !== undefined ? { taskClass } : {}),
+        ...(repoSignals ? { repoSignals } : {}),
         skippedStages: sanitizeSkippedStages(parsed.skippedStages, track),
         staleStages: sanitizeStaleStages(parsed.staleStages),
         rewinds: sanitizeRewinds(parsed.rewinds),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {