cclaw-cli 6.3.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/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,6 +387,7 @@ 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.

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/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 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

@@ -1566,6 +1566,10 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 
 - 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

@@ -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,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/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

@@ -221,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

@@ -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.4.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {