cclaw-cli 3.0.0 → 5.0.0

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

@@ -1,5 +1,35 @@
 import type { FlowState, StageGateState } from "./flow-state.js";
 import { type FlowStage } from "./types.js";
+/**
+ * Structured signal for the harness UI describing the adaptive
+ * elicitation Q&A floor for the current stage. Always present on
+ * brainstorm/scope/design verifications; null on other stages.
+ *
+ * Mirrors the `evaluateQaLogFloor` linter helper. Harness can render
+ * `count / min` progress, surface stop-signal/skip-questions hints, and
+ * differentiate between blocking and advisory.
+ */
+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;
     stage: FlowStage;
@@ -18,6 +48,8 @@ export interface GateEvidenceCheckResult {
     missingRecommended: string[];
     /** Triggered conditional gates that are not yet passed. */
     missingTriggeredConditional: string[];
+    /** Q&A floor signal for adaptive elicitation stages, null otherwise. */
+    qaLogFloor: QaLogFloorSignal | null;
 }
 export interface CompletedStagesClosureResult {
     ok: boolean;
@@ -29,7 +61,11 @@ export interface CompletedStagesClosureResult {
         blocked: string[];
     }>;
 }
-export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState): Promise<GateEvidenceCheckResult>;
+export interface VerifyCurrentStageGateEvidenceOptions {
+    /** Extra stage flags propagated from the in-flight CLI args (e.g. `--skip-questions`). */
+    extraStageFlags?: string[];
+}
+export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState, options?: VerifyCurrentStageGateEvidenceOptions): Promise<GateEvidenceCheckResult>;
 export declare function verifyCompletedStagesGateClosure(flowState: FlowState): CompletedStagesClosureResult;
 export interface GateReconciliationResult {
     stage: FlowStage;

package/dist/gate-evidence.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { checkReviewSecurityNoChangeAttestation, checkReviewVerdictConsistency, extractMarkdownSectionBody, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import { ELICITATION_STAGES, evaluateQaLogFloor } from "./artifact-linter/shared.js";
 import { resolveArtifactPath } from "./artifact-paths.js";
 import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
@@ -207,7 +208,7 @@ const DESIGN_RESEARCH_REQUIRED_SECTIONS = [
     "Pitfalls & Risks",
     "Synthesis"
 ];
-export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
+export async function verifyCurrentStageGateEvidence(projectRoot, flowState, options = {}) {
     const stage = flowState.currentStage;
     const schema = stageSchema(stage, flowState.track);
     const catalog = flowState.stageGateCatalog[stage];
@@ -283,7 +284,9 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
     const artifactPresent = await currentStageArtifactExists(projectRoot, stage, flowState.track);
     const shouldValidateArtifact = artifactPresent || catalog.passed.length > 0 || flowState.completedStages.includes(stage);
     if (shouldValidateArtifact) {
-        const lint = await lintArtifact(projectRoot, stage, flowState.track);
+        const lint = await lintArtifact(projectRoot, stage, flowState.track, {
+            extraStageFlags: options.extraStageFlags
+        });
         if (!lint.passed) {
             const failedRequiredFindings = lint.findings
                 .filter((finding) => finding.required && !finding.found);
@@ -444,6 +447,36 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             issues.push(`stage "${stage}" is marked completed but has blocking blocked gates: ${blockingBlocked.join(", ")}.`);
         }
     }
+    let qaLogFloor = null;
+    if (ELICITATION_STAGES.has(stage)) {
+        let qaLogBody = null;
+        try {
+            const stageMd = await readStageArtifactMarkdown(projectRoot, stage, flowState.track);
+            qaLogBody = stageMd
+                ? extractMarkdownSectionBody(stageMd, "Q&A Log")
+                : null;
+        }
+        catch {
+            qaLogBody = null;
+        }
+        const skipQuestionsHint = flowState.interactionHints?.[stage]?.skipQuestions === true ||
+            (options.extraStageFlags ?? []).includes("--skip-questions");
+        const floor = evaluateQaLogFloor(qaLogBody, flowState.track, stage, {
+            skipQuestions: skipQuestionsHint
+        });
+        qaLogFloor = {
+            ok: floor.ok,
+            count: floor.count,
+            min: floor.min,
+            hasStopSignal: floor.hasStopSignal,
+            liteShortCircuit: floor.liteShortCircuit,
+            skipQuestionsAdvisory: floor.skipQuestionsAdvisory,
+            blocking: !floor.ok && !floor.skipQuestionsAdvisory,
+            forcingCovered: floor.forcingCovered,
+            forcingPending: floor.forcingPending,
+            noNewDecisions: floor.noNewDecisions
+        };
+    }
     return {
         ok: issues.length === 0,
         stage,
@@ -457,7 +490,8 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
         complete,
         missingRequired,
         missingRecommended,
-        missingTriggeredConditional
+        missingTriggeredConditional,
+        qaLogFloor
     };
 }
 export function verifyCompletedStagesGateClosure(flowState) {

package/dist/harness-adapters.js

@@ -345,6 +345,14 @@ Before responding to a coding request:
 2. Use \`/cc\` to start, resume, or continue the flow.
 3. If no stage applies, respond normally.
 
+### Cclaw Baseline (always-on)
+
+Three rules apply to every cclaw stage in this project, regardless of which skills loaded:
+
+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) all forcing-question topics are addressed in \`## Q&A Log\`, (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.
+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.
+
 ${ironLawsAgentsMdBlock()}
 
 ### Task Classification (before \`/cc\`)

package/dist/install.js

@@ -16,7 +16,7 @@ import { ironLawsSkillMarkdown } from "./content/iron-laws.js";
 import { stageCompleteScript, startFlowScript, cancelRunScript, runHookCmdScript, delegationRecordScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { nodeHookRuntimeScript } from "./content/node-hooks.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
-import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
+import { ARTIFACT_TEMPLATES, CURSOR_GUIDELINES_RULE_MDC, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
 import { STATE_CONTRACTS } from "./content/state-contracts.js";
 import { REVIEW_PROMPTS } from "./content/review-prompts.js";
 import { stageSkillFolder, stageSkillMarkdown, executingWavesSkillMarkdown } from "./content/skills.js";
@@ -37,6 +37,7 @@ import { CorruptFlowStateError, ensureRunSystem } from "./runs.js";
 import { FLOW_STAGES } from "./types.js";
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 const CURSOR_RULE_REL_PATH = ".cursor/rules/cclaw-workflow.mdc";
+const CURSOR_GUIDELINES_REL_PATH = ".cursor/rules/cclaw-guidelines.mdc";
 const GIT_HOOK_MANAGED_MARKER = "cclaw-managed-git-hook";
 const GIT_HOOK_RUNTIME_REL_DIR = `${RUNTIME_ROOT}/hooks/git`;
 const INIT_SENTINEL_FILE = ".init-in-progress";
@@ -942,17 +943,22 @@ async function writeRulebook(projectRoot) {
 }
 async function writeCursorWorkflowRule(projectRoot, harnesses) {
     const rulePath = path.join(projectRoot, CURSOR_RULE_REL_PATH);
+    const guidelinesPath = path.join(projectRoot, CURSOR_GUIDELINES_REL_PATH);
     if (!harnesses.includes("cursor")) {
-        try {
-            await fs.rm(rulePath, { force: true });
-        }
-        catch {
-            // best-effort cleanup
+        for (const target of [rulePath, guidelinesPath]) {
+            try {
+                await fs.rm(target, { force: true });
+            }
+            catch {
+                // best-effort cleanup
+            }
         }
         return;
     }
     await ensureDir(path.dirname(rulePath));
     await writeFileSafe(rulePath, CURSOR_WORKFLOW_RULE_MDC);
+    await ensureDir(path.dirname(guidelinesPath));
+    await writeFileSafe(guidelinesPath, CURSOR_GUIDELINES_RULE_MDC);
 }
 async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
     const enabled = new Set(harnesses);
@@ -1464,11 +1470,16 @@ export async function uninstallCclaw(projectRoot) {
         }
     }
     await removeManagedOpenCodePluginConfig(projectRoot, OPENCODE_PLUGIN_REL_PATH);
-    try {
-        await fs.rm(path.join(projectRoot, CURSOR_RULE_REL_PATH), { force: true });
-    }
-    catch {
-        // best-effort cleanup
+    for (const target of [
+        path.join(projectRoot, CURSOR_RULE_REL_PATH),
+        path.join(projectRoot, CURSOR_GUIDELINES_REL_PATH)
+    ]) {
+        try {
+            await fs.rm(target, { force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
     }
     const managedDirs = [
         ".claude/hooks",

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

@@ -35,6 +35,7 @@ interface InternalValidationReport {
 export declare function hydrateReviewLoopEvidenceFromArtifact(projectRoot: string, stage: FlowStage, track: FlowState["track"], selectedGateIds: string[], evidenceByGate: Record<string, string>): Promise<void>;
 export declare function buildValidationReport(projectRoot: string, flowState: FlowState, options?: {
     allowBlockedReviewRoute?: boolean;
+    extraStageFlags?: string[];
 }): Promise<InternalValidationReport>;
 interface HarvestLearningsResult {
     ok: boolean;

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

@@ -89,7 +89,9 @@ export async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage,
 }
 export async function buildValidationReport(projectRoot, flowState, options = {}) {
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
-    const gates = await verifyCurrentStageGateEvidence(projectRoot, flowState);
+    const gates = await verifyCurrentStageGateEvidence(projectRoot, flowState, {
+        extraStageFlags: options.extraStageFlags
+    });
     const completedStages = verifyCompletedStagesGateClosure(flowState);
     const blockedReviewRouteComplete = options.allowBlockedReviewRoute === true
         && flowState.currentStage === "review"
@@ -332,7 +334,8 @@ export async function runAdvanceStage(projectRoot, args, io) {
         }
     };
     const validation = await buildValidationReport(projectRoot, candidateState, {
-        allowBlockedReviewRoute: blockedReviewRoute
+        allowBlockedReviewRoute: blockedReviewRoute,
+        extraStageFlags: args.skipQuestions ? ["--skip-questions"] : undefined
     });
     if (!validation.ok) {
         const ledgerForDiag = await readDelegationLedger(projectRoot).catch(() => ({ entries: [] }));

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": "3.0.0",
+  "version": "5.0.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {