cclaw-cli 6.3.0 → 6.5.0

package/dist/artifact-linter/scope.js

@@ -43,11 +43,11 @@ export async function lintScopeStage(ctx) {
         const skipByTrack = shouldDemoteArtifactValidationByTrack(track, taskClass);
         if (skipByTrack) {
             findings.push({
-                section: "Expansion Strategist Delegation",
+                section: "Product Discovery Delegation (Strategist Mode)",
                 required: false,
                 rule: "When Scope Summary selects SCOPE EXPANSION or SELECTIVE EXPANSION, a completed `product-discovery` delegation for the active run with non-empty evidenceRefs is required.",
                 found: true,
-                details: `Expansion Strategist delegation requirement skipped for track="${track}"` +
+                details: `Product-discovery delegation requirement skipped for track="${track}"` +
                     (taskClass ? `, taskClass="${taskClass}"` : "") +
                     ` (Wave 25: lite-tier escape; selectedMode=${selectedScopeMode}).`
             });
@@ -78,12 +78,12 @@ export async function lintScopeStage(ctx) {
             const hasCompleted = discoveryRows.length > 0;
             const hasEvidence = discoveryRows.some((entry) => Array.isArray(entry.evidenceRefs) && entry.evidenceRefs.length > 0);
             findings.push({
-                section: "Expansion Strategist Delegation",
+                section: "Product Discovery Delegation (Strategist Mode)",
                 required: true,
                 rule: "When Scope Summary selects SCOPE EXPANSION or SELECTIVE EXPANSION, a completed `product-discovery` delegation for the active run with non-empty evidenceRefs is required.",
                 found: hasCompleted && hasEvidence,
                 details: !hasCompleted
-                    ? `Scope mode ${selectedScopeMode} requires a completed product-discovery delegation row for active run ${delegationLedger.runId}.`
+                    ? `Scope mode ${selectedScopeMode} requires a completed product-discovery delegation row for active run ${delegationLedger.runId}. In SELECTIVE EXPANSION / SCOPE EXPANSION, run product-discovery (mode=proactive) BEFORE stage-complete.`
                     : hasEvidence
                         ? `product-discovery delegation satisfied for mode ${selectedScopeMode}.`
                         : "product-discovery delegation exists but evidenceRefs is empty; add at least one artifact/code evidence reference."

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,
@@ -319,7 +367,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
  *  - `Architecture Diagram` — sync/async + failure-edge enforcement
  *  - `Data Flow` — Interaction Edge Case mandatory rows
  *  - `Stale Diagram Drift Check` — blast-radius file mtime audit
- *  - `Expansion Strategist Delegation` — product-discovery delegation
+ *  - `Product Discovery Delegation (Strategist Mode)` — product-discovery delegation
  *
  * Findings remain in the result so the caller can surface them as
  * advisory hints; only `required` flips to `false`.
@@ -328,5 +376,5 @@ const ARTIFACT_VALIDATION_LITE_DEMOTE_SECTIONS = new Set([
     "Architecture Diagram",
     "Data Flow",
     "Stale Diagram Drift Check",
-    "Expansion Strategist Delegation"
+    "Product Discovery Delegation (Strategist Mode)"
 ]);

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

@@ -380,6 +380,47 @@ function buildRow(args, status, runId, now) {
   };
 }
 
+async function acquireDelegationLogLock(stateDir) {
+  const lockDir = path.join(stateDir, "delegation-log.json.lock");
+  const maxWaitMs = 3000;
+  const startMs = Date.now();
+  let delayMs = 25;
+  while (true) {
+    try {
+      await fs.mkdir(lockDir, { recursive: false });
+      return lockDir;
+    } catch (err) {
+      const code = err && typeof err === "object" && "code" in err ? err.code : "";
+      if (code !== "EEXIST") throw err;
+      if (Date.now() - startMs >= maxWaitMs) {
+        process.stderr.write(
+          "[cclaw] delegation-record: timeout waiting for delegation-log.json.lock (max " + maxWaitMs + "ms)\\n"
+        );
+        process.exit(2);
+      }
+      const jitter = Math.floor(Math.random() * 25);
+      await new Promise((resolve) => setTimeout(resolve, delayMs + jitter));
+      delayMs = Math.min(delayMs * 2, 200);
+    }
+  }
+}
+
+async function releaseDelegationLogLock(lockDir) {
+  try {
+    await fs.rm(lockDir, { recursive: true, force: true });
+  } catch {
+    // best-effort release
+  }
+}
+
+async function writeDelegationLedgerAtomic(ledgerPath, ledger) {
+  const dir = path.dirname(ledgerPath);
+  const tmp =
+    path.join(dir, ".delegation-log.json." + process.pid + "." + Date.now() + "." + Math.random().toString(16).slice(2) + ".tmp");
+  await fs.writeFile(tmp, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+  await fs.rename(tmp, ledgerPath);
+}
+
 async function persistEntry(root, runId, clean, event, options = {}) {
   const stateDir = path.join(root, RUNTIME_ROOT, "state");
   await fs.mkdir(stateDir, { recursive: true });
@@ -387,29 +428,34 @@ async function persistEntry(root, runId, clean, event, options = {}) {
 
   const ledgerPath = path.join(stateDir, "delegation-log.json");
   let ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
+  const lockDir = await acquireDelegationLogLock(stateDir);
   try {
-    ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
-    if (!Array.isArray(ledger.entries)) ledger.entries = [];
-  } catch {
-    ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
-  }
-
-  // Rerecord semantics: replace any pre-existing row with the same spanId
-  // (regardless of its status) so the legacy v1/v2 row is upgraded to v3
-  // shape on disk. The append path keeps the historical dedup semantics:
-  // an exact (spanId, status) duplicate is dropped to keep retried hooks
-  // idempotent.
-  if (options.replaceBySpanId) {
-    ledger.entries = ledger.entries.filter((entry) => entry.spanId !== clean.spanId);
-    ledger.entries.push(clean);
-    ledger.runId = runId;
-    ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
-    await fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
-  } else if (!ledger.entries.some((entry) => entry.spanId === clean.spanId && entry.status === clean.status)) {
-    ledger.entries.push(clean);
-    ledger.runId = runId;
-    ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
-    await fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+    try {
+      ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
+      if (!Array.isArray(ledger.entries)) ledger.entries = [];
+    } catch {
+      ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
+    }
+
+    // Rerecord semantics: replace any pre-existing row with the same spanId
+    // (regardless of its status) so the legacy v1/v2 row is upgraded to v3
+    // shape on disk. The append path keeps the historical dedup semantics:
+    // an exact (spanId, status) duplicate is dropped to keep retried hooks
+    // idempotent.
+    if (options.replaceBySpanId) {
+      ledger.entries = ledger.entries.filter((entry) => entry.spanId !== clean.spanId);
+      ledger.entries.push(clean);
+      ledger.runId = runId;
+      ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
+      await writeDelegationLedgerAtomic(ledgerPath, ledger);
+    } else if (!ledger.entries.some((entry) => entry.spanId === clean.spanId && entry.status === clean.status)) {
+      ledger.entries.push(clean);
+      ledger.runId = runId;
+      ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
+      await writeDelegationLedgerAtomic(ledgerPath, ledger);
+    }
+  } finally {
+    await releaseDelegationLogLock(lockDir);
   }
 
   const active = ledger.entries.filter((entry) => ["scheduled", "launched", "acknowledged"].includes(entry.status));

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

@@ -192,7 +192,7 @@ function autoSubagentDispatchBlock(stage, track) {
 |---|---|---|---|---|---|---|---|
 ${rows}
 Mandatory: ${mandatoryList}. Record lifecycle rows in \`${delegationLogRel}\` and append-only \`${delegationEventsRel}\` before completion.${runPhaseLegend}
-### Harness Dispatch Contract — use true harness dispatch: Claude Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\` via Task/@agent, Codex \`.codex/agents/<agent>.toml\`. Do not collapse OpenCode or Codex to role-switch by default. Worker ACK Contract: ACK must include \`spanId\`, \`dispatchId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and \`ackTs\`; never claim \`fulfillmentMode: "isolated"\` without matching lifecycle proof. Helper: \`.cclaw/hooks/delegation-record.mjs --status=<status> --span-id=<spanId> --dispatch-id=<dispatchId> --dispatch-surface=<surface> --agent-definition-path=<path> --json\`. Exact recipe: scheduled -> launched -> acknowledged -> completed with the same span; completed isolated/generic rows require a prior ACK event for that span or \`--ack-ts=<iso>\`.
+### Harness Dispatch Contract — use true harness dispatch: Claude Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\` via Task/@agent, Codex \`.codex/agents/<agent>.toml\`. Do not collapse OpenCode or Codex to role-switch by default. Worker ACK Contract: ACK must include \`spanId\`, \`dispatchId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and \`ackTs\`; never claim \`fulfillmentMode: "isolated"\` without matching lifecycle proof. Canonical helper (same flags as \`delegation-record.mjs --help\`): \`node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|...> --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--evidence-ref=<ref>] --json\`. Lifecycle order: \`scheduled → launched → acknowledged → completed\` on one span (reuse the same span id); completed isolated/generic rows require a prior ACK event for that span or \`--ack-ts=<iso>\`. For a partial audit trail, \`--repair --span-id=<id> --repair-reason="<why>"\` appends missing phases (see \`--help\`) instead of inventing shortcuts.
 
 ${perHarnessLifecycleRecipeBlock()}`;
 }
@@ -387,9 +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.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the single-line success JSON exactly as printed to stdout (for example \`{"ok":true,"command":"stage-complete",...}\` including \`completedStages\` / \`currentStage\` / \`runId\`); do not paraphrase. Do not infer success from empty stdout or from skipped retries (quiet mode always emits one JSON line on success).
 - Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;
 }
@@ -411,7 +412,7 @@ ${completionBlock}
 - **NEVER paste the \`--evidence-json\` payload into chat.** It is structured data for the helper, not for the user. The same evidence already lives in the artifact section.
 - On failure, report a compact human-readable summary based on the helper's JSON \`findings\` array — list failing section names only (one line each), include the full helper JSON in a single fenced \`json\` block. Do not echo the invoking command.
 - **NEVER run shell hash commands** (\`shasum\`, \`sha256sum\`, \`md5sum\`, \`Get-FileHash\`, \`certutil\`, etc.) for hash compute. If the linter ever asks for a hash, that is a linter bug — report failure and stop, do not auto-fix in bash.
-- The helper defaults to quiet success (\`CCLAW_STAGE_COMPLETE_QUIET=1\`); rely on the resulting JSON, not stdout chatter.
+- The helper defaults to quiet (\`CCLAW_STAGE_COMPLETE_QUIET=1\`): no pretty-printed chatter, but **stdout still prints exactly one line** of machine-readable success JSON (same contract as \`start-flow\` in quiet mode).
 `;
 }
 function quickStartBlock(stage, track) {

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",
@@ -499,7 +507,7 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             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,
-            dependsOnInternalRepoSignals: true
+            essentialAcrossModes: true
         }
     ],
     scope: [
@@ -537,7 +545,7 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             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,
-            dependsOnInternalRepoSignals: true
+            essentialAcrossModes: true
         },
         {
             agent: "product-discovery",
@@ -600,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

@@ -54,11 +54,10 @@ export interface StageAutoSubagentDispatch {
     /** 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.
+     * When true on a proactive dispatch row for brainstorm/scope/design, the trace
+     * gate keeps this rule even when `discoveryMode` is `lean` or `guided`.
      */
-    dependsOnInternalRepoSignals?: boolean;
+    essentialAcrossModes?: boolean;
 }
 export type StageComplexityTier = "lightweight" | "standard" | "deep";
 export interface StagePhilosophy {

package/dist/content/stages/scope.js

@@ -52,6 +52,7 @@ export const SCOPE = {
             "**Premise carry-forward (do NOT re-author)** — brainstorm OWNS the premise check (right problem / direct path / what if nothing). Cite brainstorm's `## Premise Check` section in `## Upstream Handoff > Decisions carried forward`. Add a row to `## Premise Drift` only when the scope-stage Q&A surfaced NEW evidence that materially changes the brainstorm answer (e.g. new constraint, new user signal). Otherwise mark `Premise Drift: None` — do not duplicate the brainstorm premise table.",
             "**Conditional 10-star boundary** — for deep/high-risk/product-strategy work, show what would make the product meaningfully better, then explicitly choose what ships now, what is deferred, and what is excluded without vague `later/for now` placeholders. Skip this for straightforward repair work and record `not needed: compact scope`.",
             "**Pick one operational mode with the user** — HOLD SCOPE preserves focus; SELECTIVE EXPANSION cherry-picks high-leverage reference ideas; SCOPE EXPANSION explores ambitious alternatives; SCOPE REDUCTION cuts to the essential wedge. Recommend one, state why and what signal would change it, then keep elicitation focused until the user either approves or asks to proceed with draft boundaries.",
+            "**Product-discovery is REQUIRED for SELECTIVE / SCOPE EXPANSION (hard gate)** — If the resolved scope mode is SELECTIVE EXPANSION or SCOPE EXPANSION, run \`product-discovery\` in proactive mode **after** adaptive elicitation converges and **before** \`stage-complete\`. Do not complete this stage until the delegation ledger shows \`product-discovery\` as \`completed\` with non-empty \`evidenceRefs\` pointing at this scope artifact. HOLD SCOPE and SCOPE REDUCTION do not require this row.",
             "**Run mode-specific analysis only to needed depth** — lean discovery keeps the selected-mode row compact; guided adds the standard contract rows; deep may add Landscape Check, Taste Calibration, Reference Pattern Registry, Reference Pull, Ambitious Alternatives, and Ruthless Minimum Slice evidence when mode/risk warrants it.",
             "**Decision-driver contract** — list weighted decision drivers (value, risk, reversibility, effort, timeline) and score candidate scope moves so the selected mode and boundaries are evidence-backed, not preference-led.",
             "**Architecture handoff (do NOT pick architecture tier here)** — design OWNS architecture choice (minimum-viable / product-grade / ideal). Scope only picks the SCOPE MODE (HOLD/SELECTIVE/EXPAND/REDUCE) and boundary; record in `## Scope Contract > Design handoff` what design must decide (e.g. `architecture-tier`, `framework`, `data-model`). Do NOT enumerate Implementation Alternatives in scope.",

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- 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 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 single-line success JSON printed to stdout (e.g. `{\"ok\":true,\"command\":\"stage-complete\",...}`); do not paraphrase, do not infer success from empty stdout or 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,7 +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.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the single-line success JSON printed to stdout (e.g. \`{"ok":true,"command":"stage-complete",...}\`); do not paraphrase, do not infer success from empty stdout or 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

@@ -44,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
@@ -113,6 +113,14 @@ export interface FlowState {
     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, {
@@ -575,25 +575,43 @@ 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
     };
     await writeFlowState(projectRoot, finalState);
-    if (!args.quiet) {
+    if (args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "stage-complete",
+            stage: args.stage,
+            completedStages: finalState.completedStages,
+            currentStage: finalState.currentStage,
+            runId: finalState.activeRunId
+        })}\n`);
+    }
+    else {
         io.stdout.write(`${JSON.stringify({
             ok: true,
             command: "advance-stage",

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

@@ -8,10 +8,10 @@ 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;

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

@@ -3,36 +3,25 @@ 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);
+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")
-        .filter((rule) => !skipRepoDependentProactiveRule(rule, stage, options.discoveryMode, options.repoSignals));
+    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.js

@@ -211,18 +211,31 @@ export async function runStartFlow(projectRoot, args, io) {
     nextState = { ...nextState, repoSignals };
     await writeFlowState(projectRoot, nextState, { allowReset: true });
     await appendIdeaArtifact(projectRoot, args, current);
-    if (!args.quiet) {
+    const successPayload = {
+        ok: true,
+        command: "start-flow",
+        reclassify: args.reclassify,
+        track: nextState.track,
+        discoveryMode: nextState.discoveryMode,
+        taskClass: nextState.taskClass ?? null,
+        currentStage: nextState.currentStage,
+        skippedStages: nextState.skippedStages,
+        activeRunId: nextState.activeRunId,
+        repoSignals
+    };
+    if (args.quiet) {
         io.stdout.write(`${JSON.stringify({
             ok: true,
             command: "start-flow",
-            reclassify: args.reclassify,
-            track: nextState.track,
-            discoveryMode: nextState.discoveryMode,
-            taskClass: nextState.taskClass ?? null,
-            currentStage: nextState.currentStage,
-            skippedStages: nextState.skippedStages,
-            activeRunId: nextState.activeRunId
-        }, null, 2)}\n`);
+            track: successPayload.track,
+            discoveryMode: successPayload.discoveryMode,
+            currentStage: successPayload.currentStage,
+            activeRunId: successPayload.activeRunId,
+            repoSignals: successPayload.repoSignals
+        })}\n`);
+    }
+    else {
+        io.stdout.write(`${JSON.stringify(successPayload, 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

@@ -255,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 [];
@@ -411,6 +429,7 @@ function coerceFlowState(parsed) {
         : 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,
@@ -422,6 +441,7 @@ function coerceFlowState(parsed) {
         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.3.0",
+  "version": "6.5.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {