cclaw-cli 3.0.0 → 4.0.0

package/dist/content/templates.js

@@ -307,14 +307,18 @@ RECOMMENDATION: <option letter — one-line rationale tying back to premise chal
 > is later dropped, keep the row and mark Priority \`DROPPED\`; if a new one is
 > added mid-flow, append with the next free R-number — do NOT reuse numbers.
 
-## Locked Decisions (LD#hash)
-| Decision Anchor | Decision | Why locked now | Downstream impact |
+## Locked Decisions
+| ID | Decision | Why locked now | Downstream impact |
 |---|---|---|---|
-| LD#<sha8> |  |  |  |
+| D-1 |  |  |  |
 
-> Decision Anchor is \`LD#\` + the first 8 lowercase hex chars of SHA-256 over
-> the normalized \`Decision\` cell (trim, collapse whitespace, lowercase). Downstream
-> design/spec/plan/review artifacts reference these anchors verbatim.
+> Decision IDs are stable \`D-XX\` numbers. Assign once and never renumber across
+> scope/design/spec/plan/review/ship; downstream artifacts reference these IDs
+> verbatim. If a decision is later dropped, keep the row and mark it
+> \`(superseded by D-Y)\`; if a new one is added mid-flow, append with the next
+> free D-number. Wave 22 (v4.0.0) removed the legacy LD#<sha8> hash anchor —
+> existing artifacts with LD# anchors remain valid markdown but the linter only
+> tracks D-XX IDs.
 
 ## In Scope / Out of Scope
 
@@ -478,7 +482,7 @@ ${MARKDOWN_CODE_FENCE}
 > Default path: compact inline synthesis here. Deep/high-risk work may also write \`.cclaw/artifacts/02a-research.md\`.
 
 ## Architecture Boundaries
-| Component | Responsibility | Requirement Refs (R#) | Decision Refs (LD#hash) | Owner |
+| Component | Responsibility | Requirement Refs (R#) | Decision Refs (D-XX) | Owner |
 |---|---|---|---|---|
 |  |  |  |  |  |
 
@@ -540,11 +544,11 @@ ${MARKDOWN_CODE_FENCE}
 ### Interaction Edge Case Matrix
 | Edge case | Handled? | Design response | Deferred item (if not handled) |
 |---|---|---|---|
-| double-click | yes/no |  | None / LD#hash |
-| nav-away-mid-request | yes/no |  | None / LD#hash |
-| 10K-result dataset | yes/no |  | None / LD#hash |
-| background-job abandonment | yes/no |  | None / LD#hash |
-| zombie connection | yes/no |  | None / LD#hash |
+| double-click | yes/no |  | None / D-XX |
+| nav-away-mid-request | yes/no |  | None / D-XX |
+| 10K-result dataset | yes/no |  | None / D-XX |
+| background-job abandonment | yes/no |  | None / D-XX |
+| zombie connection | yes/no |  | None / D-XX |
 
 ## Security & Threat Model
 | Boundary | Threat | Mitigation | Owner |
@@ -699,7 +703,7 @@ ${MARKDOWN_CODE_FENCE}
 - Drift from upstream (or \`None\`):
 
 ## Acceptance Criteria
-| ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref (LD#hash) |
+| ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref (D-XX) |
 |---|---|---|---|
 | AC-1 | R1 |  |  |
 
@@ -845,9 +849,9 @@ Execution rule: complete and verify each batch before starting the next batch.
 - TDD checkpoint plan: RED commit/checkpoint -> GREEN commit/checkpoint -> REFACTOR commit/checkpoint (or deferred because: )
 
 ## Locked Decision Coverage
-| Decision Ref (LD#hash) | Source section | Plan tasks implementing decision | Status |
+| Decision Ref (D-XX) | Source section | Plan tasks implementing decision | Status |
 |---|---|---|---|
-| LD#<sha8> | 02-scope.md > Locked Decisions | T-1 | covered |
+| D-1 | 02-scope.md > Locked Decisions | T-1 | covered |
 
 ## Risk Assessment
 | Task/Batch | Risk | Likelihood | Impact | Mitigation |
@@ -870,7 +874,7 @@ Execution rule: complete and verify each batch before starting the next batch.
   - Create:
   - Modify:
   - Test:
-- **Approach:** (1-3 sentences; cite design decision DD-# or LD#hash)
+- **Approach:** (1-3 sentences; cite design decision DD-# or scope D-XX)
 - **Patterns to follow:** (link existing files/modules to mirror, or \`- None applicable.\`)
 - **Test scenarios:**
   - Happy:
@@ -908,7 +912,7 @@ Execution rule: complete and verify each batch before starting the next batch.
   - Hits: 0 (required for WAIT_FOR_CONFIRM to resolve).
 - Scope reduction language scan:
   - Scanned phrases: \`v1\`, \`for now\`, \`later\`, \`temporary\`, \`placeholder\`, \`mock for now\`, \`hardcoded for now\`, \`will improve later\`.
-  - Hits: 0 (required when Locked Decisions section is non-empty; use LD#hash anchors).
+  - Hits: 0 (required when Locked Decisions section is non-empty; reference D-XX IDs from scope).
 
 ## WAIT_FOR_CONFIRM
 - Status: pending
@@ -1449,6 +1453,60 @@ delegate to a specialized agent or skill if the harness supports it. The primary
 2. Provide focused context (relevant files, the specific concern)
 3. Evaluate the specialist output before acting on it — do not blindly apply recommendations
 `;
+/**
+ * Always-on baseline rule materialized at `.cursor/rules/cclaw-guidelines.mdc`.
+ * Independent of skill activation — kicks in even when the agent skips
+ * loading skills. Three hard rules cover the most common Wave 22 regressions
+ * (premature draft, premature subagent dispatch, command-line echo to chat).
+ */
+export const CURSOR_GUIDELINES_RULE_MDC = `---
+description: cclaw zero-install behavior baseline (always-on)
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+<!-- cclaw-managed-cursor-guidelines-rule -->
+
+# Cclaw Baseline Guidelines
+
+These three rules apply to every Cursor agent session in this project,
+regardless of whether stage skills loaded.
+
+## 1. Q&A floor before drafting (brainstorm/scope/design)
+
+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.
+
+## 2. Mandatory subagents run after Q&A approval
+
+For brainstorm / scope / design, mandatory subagents (
+\`product-discovery\`, \`critic\`, \`planner\`, \`architect\`,
+\`test-author\`) run **only AFTER the user approves the elicitation
+outcome**, never before the Q&A loop converges. Dispatching them early
+preempts the user dialogue and violates the elicitation contract — the
+linter will block stage-complete.
+
+See each stage's "Run Phase: post-elicitation" rows in the materialized
+Automatic Subagent Dispatch table.
+
+## 3. Never echo cclaw command lines to chat
+
+The user does not run cclaw helpers (\`node .cclaw/hooks/...\`) manually.
+NEVER paste full command lines, \`--evidence-json '{...}'\` payloads,
+\`--waive-delegation=...\`, or shell hash commands (\`shasum\`,
+\`sha256sum\`, \`Get-FileHash\`, \`certutil\`, etc.) into chat. Run the
+helper via the tool layer and report only the resulting summary. On
+failure, report a compact human-readable summary plus the helper JSON in
+a single fenced \`json\` block.
+`;
 export const CURSOR_WORKFLOW_RULE_MDC = `---
 description: cclaw workflow guardrails for Cursor agent sessions
 globs:
@@ -1497,7 +1555,11 @@ 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.
-- Ask for user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization).
+- **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 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.
+- Never echo cclaw command lines (\`node .cclaw/hooks/...\`, \`--evidence-json '{...}'\`) to chat — the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.
 - If harness capabilities are partial, record waiver reasons in delegation logs.
 
 ## Routing Source Of Truth

package/dist/gate-evidence.d.ts

@@ -1,5 +1,23 @@
 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;
+    min: number;
+    hasStopSignal: boolean;
+    liteShortCircuit: boolean;
+    skipQuestionsAdvisory: boolean;
+    blocking: boolean;
+}
 export interface GateEvidenceCheckResult {
     ok: boolean;
     stage: FlowStage;
@@ -18,6 +36,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 +49,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,33 @@ 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
+        };
+    }
     return {
         ok: issues.length === 0,
         stage,
@@ -457,7 +487,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 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.
+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/package.json

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