cclaw-cli 6.2.0 → 6.4.0

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

@@ -385,6 +385,9 @@ export interface LearningsParseResult {
     errors: string[];
     details: string;
 }
+/** Multiline block used by linter + learnings harvest stderr (identical text). */
+export declare function formatLearningsErrorsBullets(errors: string[]): string;
+export declare function learningsParseFailureHumanSummary(artifactRelPath: string, errors: string[]): string;
 export declare const LEARNING_TYPE_SET: Set<LearningEntryType>;
 export declare const LEARNING_CONFIDENCE_SET: Set<LearningConfidence>;
 export declare const LEARNING_SEVERITY_SET: Set<LearningSeverity>;

package/dist/artifact-linter/shared.js

@@ -1501,6 +1501,16 @@ export function hasVerificationLadderTableRow(sectionBody) {
     }
     return false;
 }
+/** Multiline block used by linter + learnings harvest stderr (identical text). */
+export function formatLearningsErrorsBullets(errors) {
+    if (errors.length === 0) {
+        return "Errors:\n  - Learnings section could not be parsed.";
+    }
+    return `Errors:\n${errors.map((error) => `  - ${error}`).join("\n")}`;
+}
+export function learningsParseFailureHumanSummary(artifactRelPath, errors) {
+    return `learnings harvest failed for \`${artifactRelPath}\`.\n${formatLearningsErrorsBullets(errors)}`;
+}
 export const LEARNING_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
 export const LEARNING_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
 export const LEARNING_SEVERITY_SET = new Set(["critical", "important", "suggestion"]);

package/dist/artifact-linter.d.ts

@@ -1,7 +1,7 @@
 import type { FlowStage, FlowTrack } from "./types.js";
 import { type LintResult } from "./artifact-linter/shared.js";
 export { validateReviewArmy, checkReviewVerdictConsistency, checkReviewSecurityNoChangeAttestation, checkReviewTddNoCrossArtifactDuplication, type ReviewVerdictConsistencyResult, type ReviewSecurityNoChangeAttestationResult, type ReviewTddDuplicationConflict, type ReviewTddDuplicationResult } from "./artifact-linter/review-army.js";
-export { type LintFinding, type LintResult, type LearningEntryType, type LearningConfidence, type LearningSeverity, type LearningSource, type LearningSeedEntry, type LearningsParseResult, extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
+export { type LintFinding, type LintResult, type LearningEntryType, type LearningConfidence, type LearningSeverity, type LearningSource, type LearningSeedEntry, type LearningsParseResult, formatLearningsErrorsBullets, learningsParseFailureHumanSummary, extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
 export interface LintArtifactOptions {
     /**
      * Stage-level flags supplied by the caller (typically `advance-stage`)

package/dist/artifact-linter.js

@@ -3,7 +3,7 @@ import { resolveArtifactPath as resolveStageArtifactPath } from "./artifact-path
 import { exists } from "./fs-utils.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { readFlowState } from "./run-persistence.js";
-import { duplicateH2Headings, extractH2Sections, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody } from "./artifact-linter/shared.js";
+import { duplicateH2Headings, extractH2Sections, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody, formatLearningsErrorsBullets } from "./artifact-linter/shared.js";
 import { shouldDemoteArtifactValidationByTrack } from "./content/stage-schema.js";
 import { recordArtifactValidationDemotedByTrack } from "./delegation.js";
 import { lintBrainstormStage } from "./artifact-linter/brainstorm.js";
@@ -15,7 +15,7 @@ import { lintTddStage } from "./artifact-linter/tdd.js";
 import { lintReviewStage } from "./artifact-linter/review.js";
 import { lintShipStage } from "./artifact-linter/ship.js";
 export { validateReviewArmy, checkReviewVerdictConsistency, checkReviewSecurityNoChangeAttestation, checkReviewTddNoCrossArtifactDuplication } from "./artifact-linter/review-army.js";
-export { extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
+export { formatLearningsErrorsBullets, learningsParseFailureHumanSummary, extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
 const FRONTMATTER_REQUIRED_KEYS = [
     "stage",
     "schema_version",
@@ -117,6 +117,8 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
     let discoveryMode = "guided";
     let taskClass = null;
     let activeRunId = null;
+    let completedStagesForAudit = [];
+    let completedStageMetaForAudit;
     try {
         const flowState = await readFlowState(projectRoot);
         const hint = flowState.interactionHints?.[stage];
@@ -125,12 +127,16 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         discoveryMode = flowState.discoveryMode ?? "guided";
         taskClass = flowState.taskClass ?? null;
         activeRunId = flowState.activeRunId ?? null;
+        completedStagesForAudit = flowState.completedStages;
+        completedStageMetaForAudit = flowState.completedStageMeta;
     }
     catch {
         activeStageFlags = [];
         discoveryMode = "guided";
         taskClass = null;
         activeRunId = null;
+        completedStagesForAudit = [];
+        completedStageMetaForAudit = undefined;
     }
     for (const extra of options.extraStageFlags ?? []) {
         if (typeof extra === "string" && extra.length > 0 && !activeStageFlags.includes(extra)) {
@@ -186,14 +192,56 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         const meaningfulStageNoneWarning = learnings.ok && learnings.none && ["design", "tdd", "review"].includes(stage)
             ? " Warning: design/tdd/review usually produce reusable decisions, test patterns, or review lessons; keep `None this stage` only for truly mechanical work."
             : "";
+        const learningsErrorBlock = !learnings.ok && learnings.errors.length > 0
+            ? `\n${formatLearningsErrorsBullets(learnings.errors)}`
+            : "";
         findings.push({
             section: "Learnings",
             required: requireLearnings,
             rule: "`## Learnings` must contain either a single `- None this stage.` bullet or JSON bullets compatible with knowledge.jsonl fields (type/trigger/action/confidence required).",
             found: learnings.ok,
-            details: `${learnings.details}${meaningfulStageNoneWarning}`
+            details: `${learnings.details}${learningsErrorBlock}${meaningfulStageNoneWarning}`
         });
     }
+    for (const doneStage of completedStagesForAudit) {
+        const completionIso = completedStageMetaForAudit?.[doneStage]?.completedAt;
+        if (!completionIso)
+            continue;
+        const completedMs = Date.parse(completionIso);
+        if (!Number.isFinite(completedMs))
+            continue;
+        try {
+            const resolvedDone = await resolveStageArtifactPath(doneStage, {
+                projectRoot,
+                track,
+                intent: "read"
+            });
+            if (!(await exists(resolvedDone.absPath)))
+                continue;
+            const artifactStat = await fs.stat(resolvedDone.absPath);
+            if (artifactStat.mtimeMs <= completedMs)
+                continue;
+            const priorRaw = await fs.readFile(resolvedDone.absPath, "utf8");
+            const priorSections = extractH2Sections(priorRaw);
+            const amendBody = sectionBodyByName(priorSections, "Amendments");
+            const trimmedAmend = amendBody === null
+                ? ""
+                : amendBody.replace(/<!--[\s\S]*?-->/gu, "").replace(/\s+/gu, " ").trim();
+            if (trimmedAmend.length > 0)
+                continue;
+            findings.push({
+                section: "stage_artifact_post_closure_mutation",
+                required: false,
+                rule: "stage_artifact_post_closure_mutation — substantive post-closure edit without `## Amendments` (advisory)",
+                found: false,
+                details: `Completed stage "${doneStage}" snapshot closed at ${completionIso}, but ${resolvedDone.relPath} has a newer mtime without nonempty \`## Amendments\`. ` +
+                    "Append dated bullets describing each drift fix, or restore the archived copy."
+            });
+        }
+        catch {
+            continue;
+        }
+    }
     const stageContext = {
         projectRoot,
         stage,

package/dist/content/closeout-guidance.js

@@ -19,9 +19,9 @@ export function closeoutSubstateProtocolBullets() {
     return `When \`currentStage === "ship"\`, route by **${closeoutSubstateInline()}**:
   - \`"idle"\` or missing -> outcome: initialize closeout by setting
     ${closeoutSubstateInline()} = \`"post_ship_review"\`, then continue \`/cc\`
-    into the in-stage retro protocol (draft + one structured accept/edit/skip ask).
+    into the in-stage retro protocol (draft + one structured accept/edit/no changes ask).
   - \`"post_ship_review"\` -> outcome: execute the unified post-ship closeout leg
-    (retro acceptance/edit/skip + in-stage compound scan, not \`ce:compound\`)
+    (retro acceptance/edit/no changes + in-stage compound scan, not \`ce:compound\`)
     and advance toward archive readiness:
     read \`.cclaw/state/compound-readiness.json\` plus the relevant tail of
     \`.cclaw/knowledge.jsonl\`, assess overlap before adding duplicate knowledge,
@@ -30,8 +30,8 @@ export function closeoutSubstateProtocolBullets() {
     guidance in place instead of introducing extra lineage metadata. Optionally ask
     whether to scan Cursor/Claude/Codex
     session transcripts for matching historical learnings; only do it after opt-in.
-    Ask **one** structured question (apply / skip) per candidate cluster or a
-    single accept-all / skip choice, then advance substate.
+    Ask **one** structured question (apply / no changes) per candidate cluster or a
+    single accept-all / no-changes choice, then advance substate.
   - \`"ready_to_archive"\` -> outcome: continue \`/cc\` so the runtime archive step
     executes, snapshots, and resets active state.
   - \`"archived"\` (transient) -> outcome: report "run archived" and stop (flow complete).`;

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-elicitation.js

@@ -46,6 +46,7 @@ These behaviors are the exact reason this skill exists. The linter will block yo
 - Ask exactly one question per turn and wait for the answer before asking the next one.
 - Use harness-native question tools first; prose fallback is allowed only when the tool is unavailable.
 - Keep a running Q&A trace in the active artifact under \`## Q&A Log\` in \`${RUNTIME_ROOT}/artifacts/\` as append-only rows.
+- **Early-loop ledger discipline**: Never append \`.cclaw/state/early-loop-log.jsonl\` rows whose \`iteration\` exceeds the active \`maxIterations\`. If the cap fired, escalate or accept convergence outcomes—do not bump the iteration counter afterward. \`deriveEarlyLoopStatus\` clamps persistence, but the log source should stay honest too.
 - **Convergence floor**: do NOT advance the stage (do NOT call \`stage-complete.mjs\`) until Q&A converges. The machine contract matches \`evaluateQaLogFloor\` in \`src/artifact-linter/shared.ts\` (rule \`qa_log_unconverged\`). Pass when ANY holds: (a) every forcing-question topic id is tagged \`[topic:<id>]\` on at least one \`## Q&A Log\` row; (b) the Ralph-Loop detector fires (last 2 substantive rows are non-decision-changing: \`skip\`/\`continue\`/\`no-change\`/\`done\`/etc.) **and** the log has at least \`max(2, questionBudgetHint(discoveryMode, stage).min)\` substantive rows — **unless** \`discoveryMode\` is \`guided\` or \`deep\` with pending forcing-topic ids (then Ralph-Loop alone cannot pass until topics are tagged, a stop-signal is recorded, or \`--skip-questions\` downgrades the finding to advisory); (c) an explicit user stop-signal row; or (d) \`--skip-questions\` was persisted (unconverged is advisory only). Wave 24 (v6.0.0) made \`[topic:<id>]\` mandatory (no English keyword fallback).
 - **NEVER run shell hash commands** (\`shasum\`, \`sha256sum\`, \`md5sum\`, \`Get-FileHash\`, \`certutil\`, etc.) to compute artifact hashes. If a linter ever asks you for a hash, that is a linter bug — report failure and stop, do not auto-fix in bash.
 - **NEVER paste cclaw command lines into chat** (e.g. \`node .cclaw/hooks/stage-complete.mjs ... --evidence-json '{...}'\`). Run them via the tool layer; report only the resulting summary. The user does not run cclaw manually and seeing the command line is noise.
@@ -85,6 +86,8 @@ Treat these as stop-and-draft signals:
 - EN: "enough", "skip", "just draft it", "stop asking", "move on", "no more questions"
 - UA: "досить", "вистачить", "давай драфт", "рухаємось далі"
 
+Label disambiguation: The word **skip** is a valid stop phrase during brainstorm/scope/design Q&A. In ship closeout retros, compound clustering, or any structured retro ask, expose **no changes** / **accept as-is** for the passive option instead of wording it as "skip" so agents do not mix elicitation stop-signals with closeout choreography.
+
 When detected:
 - Append a Q&A Log row exactly like: \`Turn N | (stop-signal) | <user quote> | stop-and-draft\` — this row satisfies the linter floor escape hatch.
 - Do not ask another question in this stage loop.

package/dist/content/skills.js

@@ -387,8 +387,10 @@ function completionParametersBlock(schema, track) {
 - \`completion helper JSON diagnostics\`: append \`--json\` to receive a machine-readable validation failure summary.
 - \`delegation lifecycle proof\`: use the delegation helper recipe in this section with explicit lifecycle rows: \`--status=scheduled\` -> \`--status=launched\` -> \`--status=acknowledged\` -> \`--status=completed\` (completed isolated/generic requires prior ACK for the same span or \`--ack-ts=<iso>\`).
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
+- If you edit any completed-stage artifact after it shipped (\`completedStageMeta\` timestamps exist), append a short \`## Amendments\` section with dated bullets (timestamp + reason) instead of overwriting the archived narrative silently — advisory linter rule \`stage_artifact_post_closure_mutation\` enforces visibility when this trail is missing.
 - 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

@@ -10,6 +10,14 @@ import { trackRenderContext } from "./track-render-context.js";
 // Protocol). They are no longer re-exported from here to avoid duplication
 // and drift. Stage skills cite the meta-skill by path instead.
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Optional artifact appendix (documentation-only — not a tiered gate)
+//
+// `## Amendments` — after a stage is closed, substantive edits SHOULD append dated
+// bullets (ISO timestamp + reason) here instead of silently rewriting history. The
+// linter surfaces advisory `stage_artifact_post_closure_mutation` findings when mtimes
+// move without this trail (`completedStageMeta` must exist).
+// ---------------------------------------------------------------------------
 export const SKILL_ENVELOPE_KINDS = [
     "stage-output",
     "gate-result",
@@ -498,7 +506,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,
+            essentialAcrossModes: true
         }
     ],
     scope: [
@@ -535,7 +544,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,
+            essentialAcrossModes: true
         },
         {
             agent: "product-discovery",
@@ -598,7 +608,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             runPhase: "post-elicitation",
             when: "When framework/library docs, repo graph context, or reference contracts may change the design. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Run search-before-read context synthesis before architecture locks.",
-            requiresUserGate: false
+            requiresUserGate: false,
+            essentialAcrossModes: true
         },
         {
             agent: "security-reviewer",

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

@@ -53,6 +53,11 @@ export interface StageAutoSubagentDispatch {
     returnSchema?: StageSubagentReturnSchema;
     /** Optional skill folder the dispatched agent should load as additional context. */
     skill?: string;
+    /**
+     * When true on a proactive dispatch row for brainstorm/scope/design, the trace
+     * gate keeps this rule even when `discoveryMode` is `lean` or `guided`.
+     */
+    essentialAcrossModes?: 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/subagents.js

@@ -578,6 +578,8 @@ Use this payload when a stage needs context-readiness or search-before-read evid
 ${MARKDOWN_CODE_FENCE}
 You are a researcher subagent.
 
+SCOPE — External plus internal research: search official docs/libraries/prior art and current best practices (use web or package-index tooling whenever it is live; cite URLs or authoritative references). Internally scan the repo for commits, manifests, conventions, migrations, configuration, and latent decisions—even when the workspace is sparse, external benchmarking stays mandatory.
+
 QUESTION: {one falsifiable research question}
 SCOPE: {repo paths, docs, references, providers to inspect}
 CONTEXT READINESS: {graph/search/provider status if known}

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\n## Protocol label hygiene\n\n`skip` wording means different things depending on phase: brainstorm/scope/design Q&A stop-signals may still literal **skip**/enough/move-on wording; structured ship closeout retros and compound clustering prompts should expose **no changes** (or accept-as-is language) rather than labeling the passive path as skip. Keep the verbs aligned with the harness question copy you present to the human.\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,11 @@ 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.
+
+## Protocol label hygiene
+
+\`skip\` wording means different things depending on phase: brainstorm/scope/design Q&A stop-signals may still literal **skip**/enough/move-on wording; structured ship closeout retros and compound clustering prompts should expose **no changes** (or accept-as-is language) rather than labeling the passive path as skip. Keep the verbs aligned with the harness question copy you present to the human.
 - 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/early-loop.d.ts

@@ -23,6 +23,10 @@ export interface EarlyLoopStatus {
     escalationReason?: string;
     lastUpdatedAt: string;
 }
+export declare function clampEarlyLoopStatusForWrite(status: EarlyLoopStatus): {
+    status: EarlyLoopStatus;
+    clampedFrom: number | null;
+};
 export interface EarlyLoopLogConcern {
     id: string;
     severity: EarlyLoopConcernSeverity;

package/dist/early-loop.js

@@ -1,6 +1,18 @@
 import fs from "node:fs/promises";
 import { DEFAULT_EARLY_LOOP_MAX_ITERATIONS } from "./config.js";
 export const EARLY_LOOP_STAGES = ["brainstorm", "scope", "design"];
+export function clampEarlyLoopStatusForWrite(status) {
+    if (status.iteration <= status.maxIterations) {
+        return { status, clampedFrom: null };
+    }
+    return {
+        status: {
+            ...status,
+            iteration: status.maxIterations
+        },
+        clampedFrom: status.iteration
+    };
+}
 const CONCERN_ID_PREFIX = "C-";
 function severityWeight(severity) {
     if (severity === "critical")
@@ -234,11 +246,12 @@ export function deriveEarlyLoopStatus(entries, options) {
         convergenceTripped = true;
         escalationReason = `max iterations ${maxIterations} reached with ${openConcerns.length} open concern(s)`;
     }
+    const iteration = Math.min(currentIteration, maxIterations);
     return {
         schemaVersion: 1,
         stage: options.stage,
         runId: options.runId,
-        iteration: currentIteration,
+        iteration,
         maxIterations,
         openConcerns,
         resolvedConcerns,

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[];
@@ -37,8 +44,8 @@ export interface RetroState {
  * from the correct step even across sessions.
  *
  * - `idle` — ship not complete, or closeout not yet started.
- * - `post_ship_review` — unified closeout leg: retro acceptance/edit/skip
- *   plus compound pass execution (or explicit skip).
+ * - `post_ship_review` — unified closeout leg: retro acceptance/edit/no changes
+ *   plus compound pass execution (or explicit no-additional-changes path).
  * - `ready_to_archive` — retro + compound done; archive is the next
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive
@@ -104,6 +111,16 @@ 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;
+    /**
+     * Best-effort stage completion timestamps (ISO strings) captured as stages
+     * enter `completedStages`. Missing keys behave like legacy flows with no audit
+     * clock for post-closure mutation hints.
+     */
+    completedStageMeta?: Partial<Record<FlowStage, {
+        completedAt: string;
+    }>>;
 }
 export interface StageInteractionHint {
     skipQuestions?: boolean;

package/dist/flow-state.js

@@ -10,8 +10,8 @@ export const FLOW_STATE_SCHEMA_VERSION = 1;
  * from the correct step even across sessions.
  *
  * - `idle` — ship not complete, or closeout not yet started.
- * - `post_ship_review` — unified closeout leg: retro acceptance/edit/skip
- *   plus compound pass execution (or explicit skip).
+ * - `post_ship_review` — unified closeout leg: retro acceptance/edit/no changes
+ *   plus compound pass execution (or explicit no-additional-changes path).
  * - `ready_to_archive` — retro + compound done; archive is the next
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive

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

@@ -3,7 +3,7 @@ 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 { extractMarkdownSectionBody, learningsParseFailureHumanSummary, parseLearningsSection } from "../../artifact-linter.js";
 import { getAvailableTransitions, getTransitionGuards } from "../../flow-state.js";
 import { appendKnowledge } from "../../knowledge-store.js";
 import { readFlowState, writeFlowState } from "../../runs.js";
@@ -262,7 +262,7 @@ export async function harvestStageLearnings(projectRoot, stage, track) {
             parsedEntries: 0,
             appendedEntries: 0,
             skippedDuplicates: 0,
-            details: parsed.details
+            details: learningsParseFailureHumanSummary(resolvedArtifact.relPath, parsed.errors)
         };
     }
     const appendResult = await appendKnowledge(projectRoot, parsed.entries, {
@@ -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
@@ -560,20 +575,28 @@ export async function runAdvanceStage(projectRoot, args, io) {
     }
     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`);
+        io.stderr.write(`cclaw internal advance-stage: ${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.filter((finished) => finished !== args.stage)
         : flowState.completedStages.includes(args.stage)
             ? [...flowState.completedStages]
             : [...flowState.completedStages, args.stage];
+    let completedStageMeta = flowState.completedStageMeta ?? {};
+    if (!blockedReviewRoute && !flowState.completedStages.includes(args.stage)) {
+        completedStageMeta = {
+            ...completedStageMeta,
+            [args.stage]: { completedAt: new Date().toISOString() }
+        };
+    }
     const interactionHints = nextInteractionHints(flowState, args, successor);
     const finalState = {
         ...candidateState,
         completedStages,
+        completedStageMeta,
         currentStage: successor ?? args.stage,
         interactionHints
     };

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[];
 }
@@ -7,13 +8,14 @@ export interface ProactiveDelegationTraceResult {
  * Ensure every proactive dispatch rule for the stage has a ledger row for the
  * active run, or an explicit user-flag waiver.
  *
- * Lean/guided discovery on early elicitation stages intentionally does not
- * require a full proactive trace: specialists run only when triggers warrant
- * them. Deep discovery keeps the blanket trace so mandatory + proactive
- * coverage stays auditably complete before advance.
+ * Lean/guided discovery on brainstorm/scope/design keeps only proactive rules
+ * marked `essentialAcrossModes` (researcher today) so external research stays
+ * auditable without requiring every discretionary proactive lens. Deep
+ * discovery evaluates the full proactive matrix.
  */
 export declare function ensureProactiveDelegationTrace(projectRoot: string, stage: FlowStage, options: {
     acceptWaiver: boolean;
     waiverReason?: string;
     discoveryMode: DiscoveryMode;
+    repoSignals?: RepoSignals;
 }): Promise<ProactiveDelegationTraceResult>;

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

@@ -3,20 +3,25 @@ import { stageAutoSubagentDispatch } from "../../content/stage-schema.js";
 function isEarlyElicitationStage(stage) {
     return stage === "brainstorm" || stage === "scope" || stage === "design";
 }
+function proactiveRulesForDiscoveryMode(stage, discoveryMode) {
+    const proactiveRules = stageAutoSubagentDispatch(stage).filter((rule) => rule.mode === "proactive");
+    if (isEarlyElicitationStage(stage) && (discoveryMode === "lean" || discoveryMode === "guided")) {
+        return proactiveRules.filter((rule) => rule.essentialAcrossModes === true);
+    }
+    return proactiveRules;
+}
 /**
  * Ensure every proactive dispatch rule for the stage has a ledger row for the
  * active run, or an explicit user-flag waiver.
  *
- * Lean/guided discovery on early elicitation stages intentionally does not
- * require a full proactive trace: specialists run only when triggers warrant
- * them. Deep discovery keeps the blanket trace so mandatory + proactive
- * coverage stays auditably complete before advance.
+ * Lean/guided discovery on brainstorm/scope/design keeps only proactive rules
+ * marked `essentialAcrossModes` (researcher today) so external research stays
+ * auditable without requiring every discretionary proactive lens. Deep
+ * discovery evaluates the full proactive matrix.
  */
 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");
+    void options.repoSignals;
+    const proactiveRules = proactiveRulesForDiscoveryMode(stage, options.discoveryMode);
     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) {
@@ -157,7 +221,8 @@ export async function runStartFlow(projectRoot, args, io) {
             taskClass: nextState.taskClass ?? null,
             currentStage: nextState.currentStage,
             skippedStages: nextState.skippedStages,
-            activeRunId: nextState.activeRunId
+            activeRunId: nextState.activeRunId,
+            repoSignals
         }, null, 2)}\n`);
     }
     return 0;

package/dist/internal/early-loop-status.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { RUNTIME_ROOT } from "../constants.js";
-import { computeEarlyLoopStatus, formatEarlyLoopStatusLine, isEarlyLoopStage } from "../early-loop.js";
+import { clampEarlyLoopStatusForWrite, computeEarlyLoopStatus, formatEarlyLoopStatusLine, isEarlyLoopStage } from "../early-loop.js";
 import { writeFileSafe } from "../fs-utils.js";
 import { readFlowState } from "../runs.js";
 function parseArgs(tokens) {
@@ -71,7 +71,12 @@ export async function runEarlyLoopStatusCommand(projectRoot, argv, io) {
         return 1;
     }
     const runId = (args.runId ?? flow?.activeRunId ?? "active").trim() || "active";
-    const status = await computeEarlyLoopStatus(stage, runId, path.join(stateDir(projectRoot), "early-loop-log.jsonl"));
+    let status = await computeEarlyLoopStatus(stage, runId, path.join(stateDir(projectRoot), "early-loop-log.jsonl"));
+    const persisted = clampEarlyLoopStatusForWrite(status);
+    if (persisted.clampedFrom !== null) {
+        io.stderr.write(`cclaw internal early-loop-status: early-loop iteration ${persisted.clampedFrom} exceeds maxIterations ${status.maxIterations}; clamping before write.\n`);
+        status = persisted.status;
+    }
     if (args.write) {
         const target = path.join(stateDir(projectRoot), "early-loop.json");
         await writeFileSafe(target, `${JSON.stringify(status, null, 2)}\n`);

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`
@@ -230,6 +255,24 @@ function sanitizeStaleStages(value) {
     }
     return out;
 }
+function sanitizeCompletedStageMeta(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (!isFlowStage(key))
+            continue;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const record = raw;
+        const ca = typeof record.completedAt === "string" ? record.completedAt.trim() : "";
+        if (ca.length > 0) {
+            out[key] = { completedAt: ca };
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function sanitizeRewinds(value) {
     if (!Array.isArray(value)) {
         return [];
@@ -385,6 +428,8 @@ function coerceFlowState(parsed) {
         ? activeRunIdRaw.trim()
         : next.activeRunId;
     const taskClass = coerceTaskClass(parsed.taskClass);
+    const repoSignals = coerceRepoSignals(parsed.repoSignals);
+    const completedStageMeta = sanitizeCompletedStageMeta(parsed.completedStageMeta);
     const state = {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         activeRunId,
@@ -395,6 +440,8 @@ function coerceFlowState(parsed) {
         track,
         discoveryMode,
         ...(taskClass !== undefined ? { taskClass } : {}),
+        ...(repoSignals ? { repoSignals } : {}),
+        ...(completedStageMeta ? { completedStageMeta } : {}),
         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.4.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {