cclaw-cli 4.0.0 → 6.0.0

package/dist/content/templates.js

@@ -38,6 +38,13 @@ export const ARTIFACT_TEMPLATES = {
 |---|---|---|---|
 |  |  |  |  |
 
+## Idea Evidence Carry-forward
+> Required only when this brainstorm started from \`/cc-ideate\` (\`flow-state.interactionHints.brainstorm.fromIdeaArtifact\` is set). Skip the section entirely otherwise.
+- Source: \`<.cclaw/ideas/idea-YYYY-MM-DD-slug.md>\`
+- Candidate: \`I-#\`
+- Reused fields: Title, Why-now, Expected impact, Risk, Counter-argument
+- Newly generated: challenger row(s) only — the idea candidate becomes the \`baseline\` row of \`## Approaches\` and the seed of \`## Selected Direction\`; do NOT regenerate divergent + critique + rank work that \`/cc-ideate\` already produced.
+
 ## Problem Decision Record
 - **Depth:** lite | standard | deep
 - **Frame type:** \`<free-form-label>\` (one short token that names how this work is framed; pick whatever fits — examples in commentary only: \`product\`, \`technical-maintenance\`, \`research-spike\`, \`ops-incident\`, \`infrastructure\`, \`library-extraction\`. Do NOT treat the examples as an enum.)
@@ -79,9 +86,10 @@ export const ARTIFACT_TEMPLATES = {
 ## Q&A Log
 | Turn | Question | User answer (1-line) | Decision impact |
 |---|---|---|---|
-| 1 |  |  |  |
+| 1 |  |  | scope-shaping [topic:pain] |
 
 > Append-only by turn. Add one row after each user answer; do not rewrite prior rows.
+> **Topic tag is MANDATORY for forcing-question rows.** Stamp \`[topic:<id>]\` in the \`Decision impact\` cell so the linter can verify coverage in any natural language (RU/EN/UA/etc.). Brainstorm IDs: \`pain\`, \`direct-path\`, \`do-nothing\`, \`operator\`, \`no-go\`. Multiple tags allowed when one answer covers several topics. Stop-signal rows do NOT need a tag. Wave 24 (v6.0.0) removed the English keyword fallback.
 
 ## Approach Tier
 - Tier: lite | standard | deep
@@ -202,9 +210,10 @@ ${MARKDOWN_CODE_FENCE}
 ## Q&A Log
 | Turn | Question | User answer (1-line) | Decision impact |
 |---|---|---|---|
-| 1 |  |  |  |
+| 1 |  |  | scope-shaping [topic:in-out] |
 
 > Append-only by turn. Add one row after each user answer; do not rewrite prior rows.
+> **Topic tag is MANDATORY for forcing-question rows.** Stamp \`[topic:<id>]\` in the \`Decision impact\` cell so the linter can verify coverage in any natural language (RU/EN/UA/etc.). Scope IDs: \`in-out\`, \`locked-upstream\`, \`rollback\`, \`failure-modes\`. Multiple tags allowed when one answer covers several topics. Stop-signal rows do NOT need a tag. Wave 24 (v6.0.0) removed the English keyword fallback.
 
 ## Pre-Scope System Audit
 | Check | Command | Findings |
@@ -219,23 +228,14 @@ ${MARKDOWN_CODE_FENCE}
 - Every error has a name:
 - Four paths per data flow:
 
-## Premise Challenge
-| Question | Answer (take a position) | Evidence / leverage |
-|---|---|---|
-| Right problem? |  |  |
-| Direct path? |  |  |
-| What if we do nothing? |  |  |
-| Existing-code leverage? |  |  |
-| Reversibility cost? |  |  |
-
-## Implementation Alternatives
-| Option | Summary | Effort (S/M/L/XL) | Risk (Low/Med/High) | Pros | Cons | Reuses |
-|---|---|---|---|---|---|---|
-| A (minimum viable) |  |  |  |  |  |  |
-| B (ideal architecture) |  |  |  |  |  |  |
-| C (optional) |  |  |  |  |  |  |
+## Premise Drift
+> Optional. Brainstorm OWNS the premise check. Record \`None\` unless scope-stage Q&A surfaced new evidence (constraint, user signal, regulatory change) that materially changes brainstorm's \`## Premise Check\` answer.
+
+| Brainstorm question | New evidence (scope-stage) | Drift verdict (no-change / shift / reverse) | Action |
+|---|---|---|---|
+| (cite brainstorm Q) |  |  |  |
 
-RECOMMENDATION: <option letter — one-line rationale tying back to premise challenge and existing-code leverage>
+- Default: \`Drift: None — brainstorm Premise Check stands.\`
 
 ## Scope Contract
 - **Selected mode:** HOLD SCOPE | SELECTIVE EXPANSION | SCOPE EXPANSION | SCOPE REDUCTION
@@ -247,8 +247,9 @@ RECOMMENDATION: <option letter — one-line rationale tying back to premise chal
 - **Deferred ideas:**
 - **Accepted reference ideas:**
 - **Rejected reference ideas:**
+- **Constraints (external/regulatory/system/integration):** (spec carries these forward — do NOT restate as assumptions)
 - **Success definition:**
-- **Design handoff:**
+- **Design handoff:** (name what design must decide: architecture-tier, framework, data-model, etc. — design OWNS the architecture choice)
 
 ## Decision Drivers
 | Driver | Weight (1-5) | Option A | Option B | Option C | Notes |
@@ -448,9 +449,10 @@ ${MARKDOWN_CODE_FENCE}
 ## Q&A Log
 | Turn | Question | User answer (1-line) | Decision impact |
 |---|---|---|---|
-| 1 |  |  |  |
+| 1 |  |  | architecture-shaping [topic:data-flow] |
 
 > Append-only by turn. Add one row after each user answer; do not rewrite prior rows.
+> **Topic tag is MANDATORY for forcing-question rows.** Stamp \`[topic:<id>]\` in the \`Decision impact\` cell so the linter can verify coverage in any natural language (RU/EN/UA/etc.). Design IDs: \`data-flow\`, \`seams\`, \`invariants\`, \`not-refactor\`. Multiple tags allowed when one answer covers several topics. Stop-signal rows do NOT need a tag. Wave 24 (v6.0.0) removed the English keyword fallback.
 
 ## Codebase Investigation
 | File | Current responsibility | Patterns discovered | Existing fit / reuse candidate |
@@ -528,8 +530,12 @@ ${MARKDOWN_CODE_FENCE}
 |---|---|---|---|---|
 |  |  |  | clear/stale |  |
 
-## What Already Exists
-| Sub-problem | Existing code/library | Layer | Reuse decision |
+## Blast-radius Diff
+> Diff since scope artifact baseline. Scope OWNS the full repo audit (\`## Pre-Scope System Audit\`); design only diffs touched paths.
+>
+> Suggested command: \`git diff <scope-artifact-head-sha>..HEAD -- <touched-paths>\`
+
+| File | Change since scope (\`git diff\` summary) | Current responsibility | Reuse candidate / existing pattern |
 |---|---|---|---|
 |  |  |  |  |
 
@@ -624,9 +630,6 @@ ${MARKDOWN_CODE_FENCE}
 - Max iterations: 3
 - Unresolved concerns:
 
-## NOT in scope
-- 
-
 ## Parallelization Strategy
 - Standard/Deep add-on when multi-module; omit for compact sequential work.
 - Parallel lanes:
@@ -722,8 +725,10 @@ ${MARKDOWN_CODE_FENCE}
 | AC-1 |  |  |
 
 ## Constraints and Assumptions
-- Constraints:
-- Assumptions:
+> Constraints are CARRIED FORWARD from scope's \`## Scope Contract > Constraints\`. Cite or copy with attribution; do NOT re-author. Spec OWNS testable assumptions in \`## Assumptions Before Finalization\` below.
+
+- **Constraints (carry-forward):** See scope: \`02-scope-<slug>.md#scope-contract\` (or list new spec-stage constraints with citation to the Q&A row that surfaced them).
+- **Assumptions:** See \`## Assumptions Before Finalization\` (spec-only owner).
 
 ## Assumptions Before Finalization
 | Assumption | Source / confidence | Validation path | Disposition |
@@ -1184,9 +1189,14 @@ Execution rule: complete and verify each batch before starting the next batch.
 | AC-1 | PASS/FAIL |  |
 
 ## Layer 2 Findings
+> Wave 23 (v5.0.0): Layer 2 categories OWNED by review = cross-slice correctness, security, dependency/version, observability, external-safety. Performance + architecture findings are CARRY-FORWARD from \`03-design-<slug>.md\` (Performance Budget, ADR) — cite, do NOT re-derive. Single-slice findings stay in \`06-tdd.md > Per-Slice Review\`; review may cite their IDs (severity/disposition must match — cross-artifact-duplication linter blocks otherwise).
+
 | ID | Severity | Category | File:line / no-line reason | Description | Status |
 |---|---|---|---|---|---|
-| R-1 | Critical/Important/Suggestion | correctness/security/performance/architecture/external-safety | path:line |  | open/resolved |
+| R-1 | Critical/Important/Suggestion | cross-slice-correctness/security/dependency-version/observability/external-safety | path:line |  | open/resolved |
+| R-2 | from-design | performance | cite \`03-design-<slug>.md > Performance Budget\` |  | carry-forward |
+| R-3 | from-design | architecture | cite \`03-design-<slug>.md > ADR\` |  | carry-forward |
+| R-4 | from-tdd | from-tdd | cite \`06-tdd.md > Per-Slice Review > F-<n>\` |  | carry-forward |
 - NO_FINDINGS_ATTESTATION: <required when no findings are reported; cite inspected coverage>
 
 ## Lens Coverage
@@ -1477,13 +1487,19 @@ regardless of whether stage skills loaded.
 
 Before drafting any \`.cclaw/artifacts/01-brainstorm-*.md\`,
 \`02-scope-*.md\`, or \`03-design-*.md\`, verify that the artifact's
-\`## Q&A Log\` table contains at least the floor count for the active track
-(see \`questionBudgetHint(track, stage).min\`). Walk the stage forcing
-questions one at a time via the \`AskQuestion\` tool. If you find yourself
-proposing a draft after 1-2 questions, STOP and continue the loop.
-
-The \`qa_log_below_min\` linter rule will block \`stage-complete\` when below
-floor unless an explicit user stop-signal row is recorded.
+\`## Q&A Log\` table demonstrates Ralph-Loop convergence: every
+forcing-question topic id is tagged \`[topic:<id>]\` on at least one row
+(see the stage's forcing-questions checklist for the id list), the last
+2 turns produce no new decision-changing impact, OR an explicit user
+stop-signal row is recorded. Walk the stage forcing questions one at a
+time via the \`AskQuestion\` tool. If you find yourself proposing a
+draft after 1-2 questions while forcing topic ids remain untagged, STOP
+and continue the loop.
+
+The \`qa_log_unconverged\` linter rule will block \`stage-complete\` when
+convergence has not been reached. Wave 24 (v6.0.0) made \`[topic:<id>]\`
+tagging mandatory; the English keyword fallback was removed because it
+mis-reported convergence on RU/UA Q&A logs.
 
 ## 2. Mandatory subagents run after Q&A approval
 
@@ -1555,7 +1571,7 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 ## Delegation And Approvals
 
 - Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.
-- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool — \`AskQuestion\` in Cursor). Walk the stage forcing-questions list one-by-one. Do NOT batch and do NOT defer to a single approval gate at the end. The \`qa_log_below_min\` linter rule will block \`stage-complete\` when below floor.
+- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool — \`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).
 - **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.
 - If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP — go back to the forcing-questions list and continue.
 - 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.

package/dist/delegation.d.ts

@@ -1,4 +1,5 @@
 import { type SubagentFallback } from "./harness-adapters.js";
+import { type MandatoryDelegationTaskClass } from "./content/stage-schema.js";
 import type { FlowStage } from "./types.js";
 export type DelegationMode = "mandatory" | "proactive";
 export type DelegationStatus = "scheduled" | "launched" | "acknowledged" | "completed" | "failed" | "waived" | "stale";
@@ -143,6 +144,13 @@ export declare function appendDelegation(projectRoot: string, entry: DelegationE
 export declare function expectedFulfillmentMode(fallbacks: SubagentFallback[]): DelegationFulfillmentMode;
 export declare function checkMandatoryDelegations(projectRoot: string, stage: FlowStage, options?: {
     repairFeatureSystem?: boolean;
+    /**
+     * Optional task class for the active run. When set to
+     * `"software-bugfix"`, the mandatory delegation gate is skipped
+     * entirely (Wave 24). Callers that don't classify the run leave
+     * this undefined and rely on the track-based skip.
+     */
+    taskClass?: MandatoryDelegationTaskClass | null;
 }): Promise<{
     satisfied: boolean;
     missing: string[];
@@ -160,4 +168,12 @@ export declare function checkMandatoryDelegations(projectRoot: string, stage: Fl
     staleWorkers: string[];
     /** Expected fulfillment mode for the active harness set. */
     expectedMode: DelegationFulfillmentMode;
+    /**
+     * Wave 24 (v6.0.0): true when `mandatoryAgentsFor` returned [] for
+     * this (track, taskClass) combination — i.e. the gate was skipped
+     * entirely on quick track or software-bugfix runs. The skip is also
+     * recorded as a `mandatory_delegations_skipped_by_track` event in
+     * `delegation-events.jsonl` for audit traceability.
+     */
+    skippedByTrack: boolean;
 }>;

package/dist/delegation.js

@@ -7,7 +7,7 @@ import { readConfig } from "./config.js";
 import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
-import { stageSchema } from "./content/stage-schema.js";
+import { mandatoryAgentsFor, stageSchema } from "./content/stage-schema.js";
 const execFileAsync = promisify(execFile);
 const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived", "stale"]);
 export const DELEGATION_DISPATCH_SURFACES = [
@@ -320,6 +320,21 @@ export async function readDelegationLedger(projectRoot) {
         return { runId: activeRunId, entries: [] };
     }
 }
+/**
+ * Wave 24 (v6.0.0) audit-only event types that live in
+ * `delegation-events.jsonl` but do NOT carry a delegation lifecycle
+ * payload (no agent/spanId). The parser must accept them so they
+ * don't show up as corrupt lines.
+ */
+const NON_DELEGATION_AUDIT_EVENTS = new Set([
+    "mandatory_delegations_skipped_by_track"
+]);
+function isAuditEventLine(parsed) {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return false;
+    const evt = parsed.event;
+    return typeof evt === "string" && NON_DELEGATION_AUDIT_EVENTS.has(evt);
+}
 export async function readDelegationEvents(projectRoot) {
     const filePath = delegationEventsPath(projectRoot);
     if (!(await exists(filePath))) {
@@ -338,6 +353,11 @@ export async function readDelegationEvents(projectRoot) {
             if (isDelegationEvent(parsed)) {
                 events.push(parsed);
             }
+            else if (isAuditEventLine(parsed)) {
+                // Wave 24 audit-only row (e.g. mandatory_delegations_skipped_by_track).
+                // Not a delegation lifecycle event but valid audit content.
+                continue;
+            }
             else {
                 corruptLines.push(index + 1);
             }
@@ -451,7 +471,17 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     const flowState = await readFlowState(projectRoot, {
         repairFeatureSystem: options.repairFeatureSystem
     });
-    const mandatory = stageSchema(stage, flowState.track).mandatoryDelegations;
+    const mandatory = mandatoryAgentsFor(stage, flowState.track, options.taskClass ?? null);
+    const skippedByTrack = mandatory.length === 0 &&
+        stageSchema(stage, flowState.track).mandatoryDelegations.length > 0;
+    if (skippedByTrack) {
+        await recordMandatorySkippedByTrack(projectRoot, {
+            stage,
+            track: flowState.track,
+            taskClass: options.taskClass ?? null,
+            runId: flowState.activeRunId
+        });
+    }
     const { activeRunId } = flowState;
     const ledger = await readDelegationLedger(projectRoot);
     const events = await readDelegationEvents(projectRoot);
@@ -553,6 +583,37 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
         legacyInferredCompletions,
         corruptEventLines: events.corruptLines,
         staleWorkers,
-        expectedMode
+        expectedMode,
+        skippedByTrack
     };
 }
+/**
+ * Wave 24 (v6.0.0) — append a non-delegation audit event to
+ * `delegation-events.jsonl` recording that the mandatory delegation
+ * gate was skipped because of the active track / task class. Plays the
+ * same audit role as a `waived` row but does NOT carry an agent —
+ * downstream tooling treats `event === "mandatory_delegations_skipped_by_track"`
+ * lines as informational.
+ *
+ * Failures are swallowed: the audit log is best-effort. Missing the
+ * event must never block stage advance because the gate skip itself is
+ * authoritative.
+ */
+async function recordMandatorySkippedByTrack(projectRoot, params) {
+    const eventsPath = delegationEventsPath(projectRoot);
+    const payload = {
+        event: "mandatory_delegations_skipped_by_track",
+        stage: params.stage,
+        track: params.track,
+        taskClass: params.taskClass,
+        runId: params.runId,
+        ts: new Date().toISOString()
+    };
+    try {
+        await fs.mkdir(path.dirname(eventsPath), { recursive: true });
+        await fs.appendFile(eventsPath, `${JSON.stringify(payload)}\n`, "utf8");
+    }
+    catch {
+        // best-effort audit; never block stage advance.
+    }
+}

package/dist/flow-state.d.ts

@@ -93,6 +93,18 @@ export interface StageInteractionHint {
     skipQuestions?: boolean;
     sourceStage?: FlowStage;
     recordedAt?: string;
+    /**
+     * Wave 23 (v5.0.0) — `/cc-ideate` handoff carry-forward.
+     * When a brainstorm run is started from a `/cc-ideate` recommendation,
+     * `start-flow` records the originating idea artifact so brainstorm can
+     * reuse the divergent + critique + rank work instead of re-generating it.
+     *
+     * `fromIdeaArtifact` is a workspace-relative POSIX path to
+     * `.cclaw/ideas/idea-YYYY-MM-DD-<slug>.md` (or wherever `/cc-ideate`
+     * wrote its artifact). `fromIdeaCandidateId` is the chosen `I-#` row.
+     */
+    fromIdeaArtifact?: string;
+    fromIdeaCandidateId?: string;
 }
 export interface InitialFlowStateOptions {
     activeRunId?: string;

package/dist/gate-evidence.d.ts

@@ -12,11 +12,23 @@ import { type FlowStage } from "./types.js";
 export interface QaLogFloorSignal {
     ok: boolean;
     count: number;
+    /**
+     * Wave 23 (v5.0.0): always 0. The convergence floor no longer enforces
+     * a fixed count. Harness UIs may render `questionBudgetHint(track,
+     * stage).recommended` separately as a soft hint.
+     */
     min: number;
     hasStopSignal: boolean;
+    /** Wave 23: always false. See `min` note above. */
     liteShortCircuit: boolean;
     skipQuestionsAdvisory: boolean;
     blocking: boolean;
+    /** Forcing-question topics deemed addressed in `## Q&A Log`. */
+    forcingCovered: string[];
+    /** Forcing-question topics still pending (no Q&A row matched). */
+    forcingPending: string[];
+    /** Ralph-Loop convergence detector verdict for the last 2 rows. */
+    noNewDecisions: boolean;
 }
 export interface GateEvidenceCheckResult {
     ok: boolean;

package/dist/gate-evidence.js

@@ -471,7 +471,10 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState, opt
             hasStopSignal: floor.hasStopSignal,
             liteShortCircuit: floor.liteShortCircuit,
             skipQuestionsAdvisory: floor.skipQuestionsAdvisory,
-            blocking: !floor.ok && !floor.skipQuestionsAdvisory
+            blocking: !floor.ok && !floor.skipQuestionsAdvisory,
+            forcingCovered: floor.forcingCovered,
+            forcingPending: floor.forcingPending,
+            noNewDecisions: floor.noNewDecisions
         };
     }
     return {

package/dist/harness-adapters.js

@@ -349,7 +349,7 @@ Before responding to a coding request:
 
 Three rules apply to every cclaw stage in this project, regardless of which skills loaded:
 
-1. **Q&A floor before drafting** — for brainstorm / scope / design, walk the stage forcing questions one at a time via the harness-native question tool (Claude \`AskUserQuestion\`, Cursor \`AskQuestion\`, Codex \`request_user_input\`, Gemini \`ask_user\`). The \`qa_log_below_min\` linter rule will block \`stage-complete\` when the artifact's \`## Q&A Log\` is below \`questionBudgetHint(track, stage).min\` unless an explicit user stop-signal row is recorded.
+1. **Q&A convergence before drafting** — for brainstorm / scope / design, walk the stage forcing questions one at a time via the harness-native question tool (Claude \`AskUserQuestion\`, Cursor \`AskQuestion\`, Codex \`request_user_input\`, Gemini \`ask_user\`). The \`qa_log_unconverged\` linter rule will block \`stage-complete\` when convergence has not been reached. Convergence is satisfied when ANY of: (a) every forcing-question topic id is tagged \`[topic:<id>]\` in at least one \`## Q&A Log\` row, (b) the last 2 substantive rows produce no decision-changing impact (Ralph-Loop), or (c) an explicit user stop-signal row is recorded. The fixed count floor (10 for standard) was removed in Wave 23. Wave 24 (v6.0.0) made \`[topic:<id>]\` tagging mandatory (no English keyword fallback) so the gate works in any natural language.
 2. **Subagents run after Q&A approval** — mandatory subagents in brainstorm / scope / design (\`product-discovery\`, \`critic\`, \`planner\`, \`architect\`, \`test-author\`) run only AFTER the user approves the elicitation outcome. See each stage's "Run Phase: post-elicitation" rows in the materialized Automatic Subagent Dispatch table.
 3. **No command-line echo to chat** — the user does not run cclaw helpers manually. Never paste \`node .cclaw/hooks/...\` invocations, \`--evidence-json '{...}'\` payloads, or shell hash commands (\`shasum\`, \`sha256sum\`, \`Get-FileHash\`, \`certutil\`, etc.) into chat. Run helpers via the tool layer; report only the resulting summary.
 

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

@@ -19,6 +19,8 @@ interface InternalValidationReport {
         corruptEventLines: number[];
         staleWorkers: string[];
         expectedMode: string;
+        /** Wave 24: true when mandatoryAgentsFor returned [] for the run's track / taskClass. */
+        skippedByTrack: boolean;
     };
     gates: {
         ok: boolean;

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

@@ -111,7 +111,8 @@ export async function buildValidationReport(projectRoot, flowState, options = {}
             legacyInferredCompletions: delegation.legacyInferredCompletions,
             corruptEventLines: delegation.corruptEventLines,
             staleWorkers: delegation.staleWorkers,
-            expectedMode: delegation.expectedMode
+            expectedMode: delegation.expectedMode,
+            skippedByTrack: delegation.skippedByTrack
         },
         gates: {
             ok: gates.ok,

package/dist/internal/advance-stage/parsers.d.ts

@@ -39,6 +39,14 @@ export interface StartFlowArgs {
     forceReset: boolean;
     reclassify: boolean;
     quiet: boolean;
+    /**
+     * Wave 23 (v5.0.0) — `/cc-ideate` handoff carry-forward.
+     * Workspace-relative POSIX path to `.cclaw/ideas/idea-YYYY-MM-DD-<slug>.md`
+     * (or wherever `/cc-ideate` wrote its artifact).
+     */
+    fromIdeaArtifact?: string;
+    /** Optional `I-#` row id chosen from the idea artifact's ranked list. */
+    fromIdeaCandidateId?: string;
 }
 export interface CancelRunArgs {
     reason: string;

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

@@ -211,6 +211,8 @@ export function parseStartFlowArgs(tokens) {
     let forceReset = false;
     let reclassify = false;
     let quiet = false;
+    let fromIdeaArtifact;
+    let fromIdeaCandidateId;
     for (let i = 0; i < tokens.length; i += 1) {
         const token = tokens[i];
         const nextToken = tokens[i + 1];
@@ -259,12 +261,36 @@ export function parseStartFlowArgs(tokens) {
             stack = readValue("--stack").trim();
             continue;
         }
+        if (token === "--from-idea-artifact" || token.startsWith("--from-idea-artifact=")) {
+            const raw = readValue("--from-idea-artifact").trim();
+            fromIdeaArtifact = raw.length > 0 ? raw : undefined;
+            continue;
+        }
+        if (token === "--from-idea-candidate" || token.startsWith("--from-idea-candidate=")) {
+            const raw = readValue("--from-idea-candidate").trim();
+            fromIdeaCandidateId = raw.length > 0 ? raw : undefined;
+            continue;
+        }
         throw new Error(`Unknown flag for internal start-flow: ${token}`);
     }
     if (!track) {
         throw new Error("internal start-flow requires --track=<standard|medium|quick>.");
     }
-    return { track, className, prompt, reason, stack, forceReset, reclassify, quiet };
+    if (fromIdeaCandidateId && !fromIdeaArtifact) {
+        throw new Error("--from-idea-candidate requires --from-idea-artifact=<path> to be set as well.");
+    }
+    return {
+        track,
+        className,
+        prompt,
+        reason,
+        stack,
+        forceReset,
+        reclassify,
+        quiet,
+        fromIdeaArtifact,
+        fromIdeaCandidateId
+    };
 }
 export function parseCancelRunArgs(tokens) {
     let reason;

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

@@ -119,6 +119,19 @@ export async function runStartFlow(projectRoot, args, io) {
     else {
         nextState = createInitialFlowState({ track: args.track });
     }
+    if (args.fromIdeaArtifact) {
+        const existingHints = nextState.interactionHints ?? {};
+        const existingBrainstorm = existingHints.brainstorm ?? {};
+        nextState.interactionHints = {
+            ...existingHints,
+            brainstorm: {
+                ...existingBrainstorm,
+                fromIdeaArtifact: args.fromIdeaArtifact,
+                ...(args.fromIdeaCandidateId ? { fromIdeaCandidateId: args.fromIdeaCandidateId } : {}),
+                recordedAt: new Date().toISOString()
+            }
+        };
+    }
     await writeFlowState(projectRoot, nextState, { allowReset: true });
     await appendIdeaArtifact(projectRoot, args, current);
     if (!args.quiet) {

package/dist/run-persistence.js

@@ -246,13 +246,25 @@ function sanitizeInteractionHints(value) {
         const skipQuestions = typed.skipQuestions === true ? true : undefined;
         const sourceStage = isFlowStage(typed.sourceStage) ? typed.sourceStage : undefined;
         const recordedAt = typeof typed.recordedAt === "string" ? typed.recordedAt : undefined;
-        if (skipQuestions !== true && !sourceStage && !recordedAt) {
+        const fromIdeaArtifact = typeof typed.fromIdeaArtifact === "string" && typed.fromIdeaArtifact.trim().length > 0
+            ? typed.fromIdeaArtifact.trim()
+            : undefined;
+        const fromIdeaCandidateId = typeof typed.fromIdeaCandidateId === "string" && typed.fromIdeaCandidateId.trim().length > 0
+            ? typed.fromIdeaCandidateId.trim()
+            : undefined;
+        if (skipQuestions !== true &&
+            !sourceStage &&
+            !recordedAt &&
+            !fromIdeaArtifact &&
+            !fromIdeaCandidateId) {
             continue;
         }
         out[stage] = {
             ...(skipQuestions ? { skipQuestions } : {}),
             ...(sourceStage ? { sourceStage } : {}),
-            ...(recordedAt ? { recordedAt } : {})
+            ...(recordedAt ? { recordedAt } : {}),
+            ...(fromIdeaArtifact ? { fromIdeaArtifact } : {}),
+            ...(fromIdeaCandidateId ? { fromIdeaCandidateId } : {})
         };
     }
     return out;

package/package.json

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