cclaw-cli 1.0.0 → 2.0.0

package/dist/content/skills.js

@@ -148,11 +148,12 @@ function contextLoadingBlock(stage, trace, executionModel) {
 
 Before execution:
 1. Read \`.cclaw/state/flow-state.json\`.
+   - If the file is missing, do **not** invent an active run — this is normal for fresh init. Route to \`/cc <idea>\` first.
 2. Load active artifacts from \`.cclaw/artifacts/\`.
 3. Load upstream artifacts required by this stage:
 ${readLines}
 4. Read the state contract from \`.cclaw/templates/state-contracts/<stage>.json\` for required fields, taxonomies, and derived markdown path.
-5. Read the canonical artifact template at \`${artifactTemplatePath}\` and reuse its exact section layout — per-row tables with stable column order, calibrated review block; do not invent layouts.
+5. Read the canonical artifact template at \`${artifactTemplatePath}\` to preserve heading/per-row tables contracts (stable section names and column order) plus calibrated review block scaffolding. Preserve existing substantive bullets/rows already in the artifact; never overwrite the artifact wholesale from the template — patch only sections you author this turn.
 6. Extract upstream decisions, constraints, and open questions into the current artifact's \`Upstream Handoff\` section when present.
 7. Confirm context readiness: upstream artifact freshness, required context, canonical template shape, relevant in-repo/reference patterns, and unresolved blockers are known. If any item is missing, load it or stop before drafting.
 8. Before doing stage work, give a compact user-facing drift preamble: "Carrying forward: <1-3 bullets>. Drift since upstream: None / <specific drift>. Recommendation: continue / re-scope."
@@ -376,7 +377,7 @@ function completionParametersBlock(schema, track) {
 - \`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).
 - 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 the helper fails, stop and report the exact command/output instead of applying a manual state workaround.
+- 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.
 - Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;
 }
@@ -636,10 +637,11 @@ CLI commands, using existing \`cclaw run resume\` and \`internal verify-current-
 ## Process
 
 1. **Wave Start**: author wave plan as \`.cclaw/wave-plans/<wave-n>.md\` referencing previous wave's ship artifact.
-2. **Carry-forward Audit**: at brainstorm of the next wave, re-read previous wave ship artifact and explicitly record:
-   - Carrying forward: <locked decisions still valid>
+2. **Carry-forward Audit**: at brainstorm of the next wave, re-read previous wave ship artifact and explicitly record in the existing \`## Wave Carry-forward\` section:
+   - Carrying forward: <scope LD# hash references still valid>
    - Drift detected: <decisions no longer valid + reason>
    - Re-scope needed: <yes/no>
+   - Never create a second \`## Locked Decisions\` heading in brainstorm; reference prior LD# hashes inline.
 3. **Resume Path**: if a wave was interrupted mid-stage, \`cclaw run resume\` restores state. Run \`internal verify-current-state\` before continuing.
 4. **Wave End**: at ship, architect cross-stage verification runs from dispatch matrix. If \`DRIFT_DETECTED\`, fix before ship.
 5. **Next Wave Trigger**: launch new \`/cc <topic>\` for next wave and reference previous wave ship artifact in upstream handoff.

package/dist/content/stages/brainstorm.js

@@ -37,14 +37,16 @@ export const BRAINSTORM = {
     executionModel: {
         checklist: [
             "**Explore project context** — inspect existing files/docs/recent activity before asking what to build; capture matching files/patterns/seeds in `Context > Discovered context` so downstream stages don't redo discovery.",
+            "**Adaptive elicitation loop (shared skill)** — load `.cclaw/skills/adaptive-elicitation/SKILL.md` and run one decision-changing question at a time via harness-native question tools. After each answer, append one row to `## Q&A Log` (`Turn | Question | User answer (1-line) | Decision impact`). Continue until context is clear or user signals to proceed.",
+            "**Brainstorm forcing questions (must be covered or explicitly waived)** — what pain are we solving, what is the direct path, what happens if we do nothing, who is the first operator/user affected, and what no-go boundaries are non-negotiable.",
             "**Classify stage depth** — choose `lite` for clear low-risk tasks, `standard` for normal engineering/product changes, or `deep` for ambiguity, architecture, external dependency, security/data risk, or explicit think-bigger requests.",
             "**Write the Problem Decision Record** — pick a free-form `Frame type` label that names how this work is framed (examples: product, technical-maintenance, research-spike, ops-incident, infrastructure), then fill the universal Framing fields: affected user/role/operator, current state/failure mode/opportunity, desired observable outcome, evidence/signal, why now, do-nothing consequence, and non-goals.",
             "**Premise check (one pass)** — answer the three gstack-style questions in the artifact body: *Right problem? Direct path? What if we do nothing?* Take a position; do not hedge.",
             "**Reframe with How Might We** — write a single `How Might We …?` line that names the user/operator, the desired outcome, and the constraint. This is the altitude check before approaches.",
             "**Run Clarity Gate** — record ambiguity score (0.00-1.00), decision boundaries, reaffirmed non-goals, and residual-risk handoff before locking recommendations. If ambiguity remains high (>0.40), ask one decision-changing question before recommending.",
             "**Sharpening question discipline** — ask one decision-changing question at a time. Do not default to 3-5 batched questions; record only questions that changed the direction or a critical stop decision.",
-            "**Use compact discovery for low-risk asks** — for concrete bounded requests, do one context pass, compare one baseline and one challenger, then ask for one explicit approval; do not drag the user through a full workshop.",
-            "**Early-exit concrete asks** — for unambiguous implementation-only requests, write a compact Problem Decision Record plus short-circuit handoff (context, approved intent, constraints, assumptions, next-stage risks) and ask for one explicit approval.",
+            "**Use compact discovery for low-risk asks** — for concrete bounded requests, do one context pass, compare one baseline and one challenger, and move to draft once context is sufficient; do not drag the user through a full workshop.",
+            "**Early-exit concrete asks** — for unambiguous implementation-only requests, write a compact Problem Decision Record plus short-circuit handoff (context, approved intent, constraints, assumptions, next-stage risks) and request explicit approval when the draft is ready.",
             "**Ask only decision-changing questions** — one at a time; if answers would not change approach and are non-critical preference/default assumptions, state the assumption and continue; STOP on scope, architecture, security, data loss, public API, migration, auth/pricing, or user approval uncertainty.",
             "**Compare 2-3 distinct approaches with stable Role/Upside columns** — Role values are `baseline` | `challenger` | `wild-card`; Upside is `low` | `modest` | `high` | `higher`; include real trade-offs, reuse notes, and reference-pattern source/disposition when a known pattern influenced the option; include exactly one challenger with explicit `high` or `higher` upside.",
             "**Collect reaction before recommending** — ask which option feels closest and what concern remains, then recommend based on that reaction.",
@@ -52,14 +54,16 @@ export const BRAINSTORM = {
             "**Run early Ralph loop discipline** — after each producer iteration, append a `Critic Pass` JSONL row to `.cclaw/state/early-loop-log.jsonl`, refresh `.cclaw/state/early-loop.json`, and iterate until open concerns clear or convergence guard escalates.",
             "**Embedded Grill (post-pick)** — after `Selected Direction` is named, run 3-5 sharp checks on hidden constraints, reversibility/rollback, scope boundaries, existing-pattern conformance, and domain-language fit; record each question with recommended answer and disposition (accept/refine/reject).",
             "**Self-review before user approval** — re-read the artifact and patch contradictions, weak trade-offs, placeholders, ambiguity, and weak handoff language. Record the result in `Self-Review Notes` using the calibrated review format: `- Status: Approved` (or `Issues Found`), `- Patches applied:` with inline note or sub-bullets, `- Remaining concerns:` with inline note or sub-bullets. Use `Patches applied: None` and `Remaining concerns: None` when there is nothing to record.",
-            "**Request explicit approval** — state exactly what direction is being approved; do not advance without approval and artifact review.",
+            "**Request explicit approval to close the stage** — state exactly what direction is being approved after the adaptive elicitation loop converges; do not advance without approval and artifact review.",
             "**Handoff packet** — only after approval, produce a scope handoff packet with selected direction, why rejected options were rejected, explicit non-goals, unresolved questions, risk hints, and explicit drift from the initial ask so scope starts from locked upstream decisions instead of rediscovering intent."
         ],
         interactionProtocol: [
+            "\"If something is unclear, stop. Name what's confusing. Ask.\"",
             "Start from observed project context; if the idea is vague, first narrow the project type with **one** structured question, then keep going.",
             "Select depth explicitly: `lite`, `standard`, or `deep`; keep lite concise, but escalate when risk/ambiguity changes decisions.",
             "Lead with the premise check (right problem / direct path / what if nothing) and the `How Might We` reframing before approaches; both go in the artifact, not just the chat.",
             "Ask at most one question per turn, only when decision-changing; if using a structured question tool, send exactly one question object, not a multi-question form.",
+            "Run the shared adaptive elicitation cycle from `.cclaw/skills/adaptive-elicitation/SKILL.md`, including stop-signal handling (RU/EN/UA), smart-skip, conditional grilling triggers, and append-only `## Q&A Log` updates.",
             "Only non-critical preference/default assumptions may continue inline. STOP and ask when uncertainty affects scope, architecture, security, data loss, public API, migration, auth/pricing, or user approval.",
             "For simple low-risk greenfield work, present a compact A/B choice with one recommended path and one higher-upside challenger; keep the artifact concise but structurally complete (Context, Premise, How Might We, Sharpening Questions, Approaches, Reaction, Selected Direction, Not Doing).",
             "Show approaches before the recommendation; include a higher-upside challenger and gather reaction first.",

package/dist/content/stages/design.js

@@ -40,6 +40,8 @@ export const DESIGN = {
     },
     executionModel: {
         checklist: [
+            "**Adaptive elicitation loop (shared skill)** — load `.cclaw/skills/adaptive-elicitation/SKILL.md` and run one decision-changing question per turn via harness-native tools. After each answer, append one row to `## Q&A Log` (`Turn | Question | User answer (1-line) | Decision impact`). Continue until architecture context is clear or user signals to proceed.",
+            "**Design forcing questions (must be covered or explicitly waived)** — what is the end-to-end data flow, where are seams/ownership boundaries, which invariants must hold, and what will explicitly NOT be refactored now.",
             "Compact design lock — design does not decide what to build; it decides how the approved scope works. For simple slices, produce a tight lock: upstream handoff, existing fit, architecture boundary, one labeled diagram, data/state flow, critical path, failure/rescue, trust boundaries, test/perf expectations, rollout/rollback, rejected alternative, and spec handoff.",
             "Trivial-Change Escape Hatch — for <=3 files, no new interfaces, and no cross-module data flow, produce a mini-design (rationale, changed files, one risk) and proceed to spec.",
             "Tiered Research — for simple/medium work, do compact inline codebase/research synthesis in `Research Fleet Synthesis`; write `.cclaw/artifacts/02a-research.md` and run the full fleet only for deep/high-risk work or when external framework/architecture uncertainty exists.",
@@ -55,8 +57,10 @@ export const DESIGN = {
             "Capture leftovers — seed high-upside deferred ideas, list unresolved decisions with defaults, document distribution for new artifact types, and cross-reference deferred items to scope or unresolved decisions."
         ],
         interactionProtocol: [
+            "\"Constrain, don't micromanage - enforce invariants, separate the doer from the checker.\"",
             "Review section-by-section: investigator first, critic second, then reconcile. For simple apps, collapse this into one compact design lock with explicit risks and a single approval stop.",
             "Present each issue one at a time; do not batch issues or move sections until current issues are resolved.",
+            "Run the shared adaptive elicitation cycle from `.cclaw/skills/adaptive-elicitation/SKILL.md`, including stop-signal handling (RU/EN/UA), smart-skip, conditional grilling triggers, and append-only `## Q&A Log` updates.",
             decisionProtocolInstruction("each issue", "describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, effort estimate (S/M/L/XL), risk level (Low/Med/High), and mark one as (recommended)", "recommend the option that closes the issue with the smallest blast radius and clearest verification path"),
             "If a section has no issues, say 'No issues found' and move on.",
             "Do not skip failure-mode mapping; use Method/Exception/Rescue/UserSees and treat silent user impact without rescue as critical.",

package/dist/content/stages/scope.js

@@ -45,10 +45,12 @@ export const SCOPE = {
     },
     executionModel: {
         checklist: [
+            "**Adaptive elicitation loop (shared skill)** — load `.cclaw/skills/adaptive-elicitation/SKILL.md` and run one decision-changing question per turn via harness-native tools. After each answer, append one row to `## Q&A Log` (`Turn | Question | User answer (1-line) | Decision impact`). Continue until scope clarity is sufficient or user signals to proceed.",
+            "**Scope forcing questions (must be covered or explicitly waived)** — what is definitely in/out, which upstream decisions are locked, and what rollback path protects users if scope assumptions fail.",
             "**Scope contract first** — read brainstorm handoff, name upstream decisions used, explicit drift, confidence, unresolved questions, and next-stage risk hints; draft the in-scope/out-of-scope/deferred/discretion contract before any design choice.",
             "**Premise and leverage check** — answer in the artifact: *Right problem? Direct path? What if nothing? Where can we leverage existing code? What is the reversibility cost?* Take a position; do not hedge.",
             "**Conditional 10-star boundary** — for deep/high-risk/product-strategy work, show what would make the product meaningfully better, then explicitly choose what ships now, what is deferred, and what is excluded without vague `later/for now` placeholders. Skip this for straightforward repair work and record `not needed: compact scope`.",
-            "**Pick one operational mode with the user** — HOLD SCOPE preserves focus; SELECTIVE EXPANSION cherry-picks high-leverage reference ideas; SCOPE EXPANSION explores ambitious alternatives; SCOPE REDUCTION cuts to the essential wedge. Recommend one, state why and what signal would change it, then STOP for approval.",
+            "**Pick one operational mode with the user** — HOLD SCOPE preserves focus; SELECTIVE EXPANSION cherry-picks high-leverage reference ideas; SCOPE EXPANSION explores ambitious alternatives; SCOPE REDUCTION cuts to the essential wedge. Recommend one, state why and what signal would change it, then keep elicitation focused until the user either approves or asks to proceed with draft boundaries.",
             "**Run mode-specific analysis only to needed depth** — lite keeps the selected-mode row compact; standard adds requirements/locked decisions/discretion; deep may add Landscape Check, Taste Calibration, Reference Pattern Registry, Reference Pull, Ambitious Alternatives, and Ruthless Minimum Slice evidence when mode/risk warrants it.",
             "**Decision-driver contract** — list weighted decision drivers (value, risk, reversibility, effort, timeline) and score candidate scope moves so the selected mode and boundaries are evidence-backed, not preference-led.",
             "**Compare implementation alternatives** — include minimum viable, product-grade, and ideal architecture options with effort (S/M/L/XL), risk (Low/Med/High), pros, cons, and reuses. Recommend one and tie it to mode.",
@@ -58,9 +60,11 @@ export const SCOPE = {
             "**Write the scope contract after approval** — include selected mode, in scope, out of scope, requirements, locked decisions, discretion areas, deferred ideas, accepted/rejected reference ideas, success definition, design handoff, completion dashboard, and explicit approval evidence."
         ],
         interactionProtocol: [
+            "\"Strong success criteria let you loop independently. Weak criteria require constant clarification.\"",
             decisionProtocolInstruction("scope mode selection", "present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended)", "recommend the option that best covers the prime-directive failure modes, four data-flow paths, observability, and deferred handling for the in-scope set with the smallest blast radius. Base your recommendation on default heuristics: greenfield -> expand, enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius -> reduce"),
+            "Run the shared adaptive elicitation cycle from `.cclaw/skills/adaptive-elicitation/SKILL.md`, including stop-signal handling (RU/EN/UA), smart-skip, conditional grilling triggers, and append-only `## Q&A Log` updates.",
             "Do not walk the full checklist by default. Lead with a proposed scope contract, selected depth (`lite`/`standard`/`deep`), and the one decision that matters most; label the mode as recommended, not selected, until the user answers.",
-            "For low-risk concrete asks, keep the proposal compact but still explicit: recommend (do not auto-select) one mode, show exact in/out/deferred boundaries, and STOP for one explicit approval before finalizing the artifact or completing the stage.",
+            "For low-risk concrete asks, keep the proposal compact but still explicit: recommend (do not auto-select) one mode, show exact in/out/deferred boundaries, and request explicit approval before finalizing the artifact or completing the stage.",
             "Challenge premise first, take a firm position, and name one concrete condition that would change it.",
             "Push back on weak framing: vague scope needs a specific user/problem, platform vision needs a narrow wedge, social proof needs behavioral evidence.",
             "Resolve one structural scope issue at a time. Only non-critical preference/default assumptions may continue; STOP on uncertainty about scope boundary, architecture commitment, security, data loss, public API, migration, auth/pricing, or required user approval.",

package/dist/content/start-command.js

@@ -90,7 +90,7 @@ ${conversationLanguagePolicyMarkdown()}
    If the harness's native ask tool is available (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` / \`request_user_input\`), send exactly ONE question; on schema error, fall back to a plain-text lettered list.
 10. Start the tracked flow only through the managed helper:
    \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`
-   If this helper fails, STOP and report the exact command/output. Do **not** manually edit \`${flowPath}\`.
+   If this helper fails, STOP. Report one human-readable failure line from the JSON \`error\` field, include the helper JSON payload in a fenced \`json\` block, and never echo the invoking command line. Do **not** manually edit \`${flowPath}\`.
 11. The helper persists \`${flowPath}\`, computes \`skippedStages\`, sets the first stage for the track, resets the gate catalog, and writes \`.cclaw/artifacts/00-idea.md\`.
 12. Load the **first-stage skill for the chosen track** and its command file:
     - quick → \`.cclaw/skills/spec/SKILL.md\`
@@ -105,7 +105,7 @@ If during any stage the agent discovers evidence that contradicts the initial Ph
 1. Surface the new evidence in plain text.
 2. Propose the updated \`Class\` + \`Track\` with a one-line reason.
 3. Use the Decision Protocol to let the user accept, override, or cancel.
-4. On acceptance: run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`. The helper appends a \`Reclassification:\` entry to \`00-idea.md\` and updates flow state atomically. If it fails, STOP and report the exact output; do NOT manually edit \`flow-state.json\`.
+4. On acceptance: run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`. The helper appends a \`Reclassification:\` entry to \`00-idea.md\` and updates flow state atomically. If it fails, STOP and report one human-readable line plus the helper JSON payload in a fenced \`json\` block; never echo the invoking command line. Do NOT manually edit \`flow-state.json\`.
 
 ### Without prompt (\`/cc\`)
 
@@ -187,12 +187,12 @@ ${conversationLanguagePolicyMarkdown()}
 
    - On conflict, prefer \`standard\` over \`medium\`, and \`medium\` over \`quick\`.
    - Always state the recommendation as a one-line reason citing matched triggers and a high/medium/low track selection confidence. Clarify that the heuristic is advisory until the managed helper writes state; after that, \`/cc\` follows the selected track. Include override guidance: switch to standard when architecture, schema, migration, security, or unclear scope appears; switch to medium when product framing is needed but architecture is known.
-8. Run the managed start helper: \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP and report the exact command/output; do not manually edit flow state.
+8. Run the managed start helper: \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP, report one human-readable failure line from the JSON \`error\` field, and include the helper JSON payload in a fenced \`json\` block; do not echo the invoking command line, and do not manually edit flow state.
 9. Load and execute the **first stage skill of the chosen track** (\`brainstorm\` for medium/standard, \`spec\` for quick) plus its matching command file.
 
 ### Reclassification on discovery
 
-If mid-stage evidence contradicts the initial Class/Track decision (the "trivial" change needs a migration, the "quick" bug fix needs architecture work, an origin doc multiplies scope), STOP and re-classify using the Decision Protocol. On acceptance, run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`; the helper records \`Reclassification:\` in \`00-idea.md\` and updates state atomically. Do NOT rewrite prior artifacts or manually edit flow-state.
+If mid-stage evidence contradicts the initial Class/Track decision (the "trivial" change needs a migration, the "quick" bug fix needs architecture work, an origin doc multiplies scope), STOP and re-classify using the Decision Protocol. On acceptance, run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`; the helper records \`Reclassification:\` in \`00-idea.md\` and updates state atomically. If it fails, report one human-readable line plus the helper JSON payload in a fenced \`json\` block, never echo the invoking command line, and do not rewrite prior artifacts or manually edit flow-state.
 
 ### Path B: \`/cc\` (no arguments)
 

package/dist/content/templates.js

@@ -76,6 +76,13 @@ export const ARTIFACT_TEMPLATES = {
 |---|---|---|---|
 | 1 |  |  |  |
 
+## Q&A Log
+| Turn | Question | User answer (1-line) | Decision impact |
+|---|---|---|---|
+| 1 |  |  |  |
+
+> Append-only by turn. Add one row after each user answer; do not rewrite prior rows.
+
 ## Approach Tier
 - Tier: lite | standard | deep
 - Why this tier:
@@ -192,6 +199,13 @@ ${MARKDOWN_CODE_FENCE}
 - Open questions:
 - Drift from upstream (or \`None\`):
 
+## Q&A Log
+| Turn | Question | User answer (1-line) | Decision impact |
+|---|---|---|---|
+| 1 |  |  |  |
+
+> Append-only by turn. Add one row after each user answer; do not rewrite prior rows.
+
 ## Pre-Scope System Audit
 | Check | Command | Findings |
 |---|---|---|
@@ -427,6 +441,13 @@ ${MARKDOWN_CODE_FENCE}
 - Open questions:
 - Drift from upstream (or \`None\`):
 
+## Q&A Log
+| Turn | Question | User answer (1-line) | Decision impact |
+|---|---|---|---|
+| 1 |  |  |  |
+
+> Append-only by turn. Add one row after each user answer; do not rewrite prior rows.
+
 ## Codebase Investigation
 | File | Current responsibility | Patterns discovered | Existing fit / reuse candidate |
 |---|---|---|---|

package/dist/flow-state.d.ts

@@ -82,11 +82,18 @@ export interface FlowState {
     staleStages: Partial<Record<FlowStage, StaleStageMarker>>;
     /** Chronological rewind operations for the active run. */
     rewinds: RewindRecord[];
+    /** Optional per-stage interaction hints carried from prior stage transitions. */
+    interactionHints?: Partial<Record<FlowStage, StageInteractionHint>>;
     /** Mandatory retrospective gate status before archive. */
     retro: RetroState;
     /** Ship → post_ship_review → archive substate for resumable closeout. */
     closeout: CloseoutState;
 }
+export interface StageInteractionHint {
+    skipQuestions?: boolean;
+    sourceStage?: FlowStage;
+    recordedAt?: string;
+}
 export interface InitialFlowStateOptions {
     activeRunId?: string;
     track?: FlowTrack;

package/dist/flow-state.js

@@ -90,6 +90,7 @@ export function createInitialFlowState(activeRunIdOrOptions = {}, maybeTrack) {
         skippedStages,
         staleStages: {},
         rewinds: [],
+        interactionHints: {},
         retro: {
             required: false,
             completedAt: undefined,

package/dist/hook-schemas/claude-hooks.v1.json

@@ -2,12 +2,11 @@
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "cclaw://hooks/claude/v1",
     "harness": "claude",
-    "schemaVersion": 1,
+    "schemaVersion": 2,
     "requiredEvents": [
         "SessionStart",
         "PreToolUse",
         "PostToolUse",
-        "Stop",
-        "PreCompact"
+        "Stop"
     ]
 }

package/dist/hook-schemas/codex-hooks.v1.json

@@ -2,7 +2,7 @@
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "cclaw://hooks/codex/v1",
     "harness": "codex",
-    "schemaVersion": 1,
+    "schemaVersion": 2,
     "requiredEvents": [
         "SessionStart",
         "UserPromptSubmit",

package/dist/hook-schemas/cursor-hooks.v1.json

@@ -2,7 +2,7 @@
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "cclaw://hooks/cursor/v1",
     "harness": "cursor",
-    "schemaVersion": 1,
+    "schemaVersion": 2,
     "requiredEvents": [
         "sessionStart",
         "sessionResume",

package/dist/install.js

@@ -20,6 +20,7 @@ import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildR
 import { STATE_CONTRACTS } from "./content/state-contracts.js";
 import { REVIEW_PROMPTS } from "./content/review-prompts.js";
 import { stageSkillFolder, stageSkillMarkdown, executingWavesSkillMarkdown } from "./content/skills.js";
+import { adaptiveElicitationSkillMarkdown } from "./content/skills-elicitation.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LANGUAGE_RULE_PACK_GENERATORS, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./content/utility-skills.js";
 import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { SUBAGENT_CONTEXT_SKILLS } from "./content/subagent-context-skills.js";
@@ -490,6 +491,7 @@ async function writeSkills(projectRoot, config) {
     await writeFileSafe(runtimePath(projectRoot, "skills", "session", "SKILL.md"), sessionHooksSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "iron-laws", "SKILL.md"), ironLawsSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "executing-waves", "SKILL.md"), executingWavesSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "adaptive-elicitation", "SKILL.md"), adaptiveElicitationSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", META_SKILL_NAME, "SKILL.md"), usingCclawSkillMarkdown());
     // In-thread research procedures (no YAML frontmatter, not delegated personas).
     for (const [fileName, markdown] of Object.entries(RESEARCH_PLAYBOOKS)) {
@@ -1080,8 +1082,13 @@ async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
     }
 }
 async function writeState(projectRoot, config, forceReset = false) {
+    // Fresh init no longer materializes flow-state.json. The first managed
+    // `/cc <idea>` start-flow call creates the state file.
+    if (!forceReset) {
+        return;
+    }
     const statePath = runtimePath(projectRoot, "state", "flow-state.json");
-    if (!forceReset && (await exists(statePath))) {
+    if (await exists(statePath)) {
         return;
     }
     const state = createInitialFlowState({ track: config.defaultTrack ?? "standard" });
@@ -1294,7 +1301,9 @@ export async function initCclaw(options) {
     // and only appear in the on-disk file when the user sets them explicitly
     // or a non-default value was detected (e.g. languageRulePacks).
     await writeConfig(options.projectRoot, config, { mode: "minimal" });
-    await materializeRuntime(options.projectRoot, config, true, "init");
+    // Init should scaffold runtime surfaces but leave flow-state creation to the
+    // first managed start-flow invocation.
+    await materializeRuntime(options.projectRoot, config, false, "init");
 }
 export async function syncCclaw(projectRoot, options = {}) {
     if (options.harnesses !== undefined && options.harnesses.length === 0) {
@@ -1418,7 +1427,7 @@ function isManagedRuntimeHookCommand(command) {
     // (e.g. `node .cclaw\hooks\run-hook.mjs ...`) still round-trip through
     // sync without being duplicated alongside freshly generated entries.
     const normalized = command.trim().replace(/\s+/gu, " ").replace(/\\/gu, "/");
-    if (/(^|\s)(?:node\s+)?(?:"|')?(?:\.\/)?\.cclaw\/hooks\/run-hook\.(?:mjs|cmd)(?:"|')?\s+(?:session-start|stop-handoff|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor|verify-current-state)(?:\s|$)/u.test(normalized)) {
+    if (/(^|\s)(?:node\s+)?(?:"|')?(?:\.\/)?\.cclaw\/hooks\/run-hook\.(?:mjs|cmd)(?:"|')?\s+(?:session-start|stop-handoff|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|pre-tool-pipeline|prompt-pipeline|context-monitor|verify-current-state)(?:\s|$)/u.test(normalized)) {
         return true;
     }
     // Codex UserPromptSubmit non-blocking state nudge.

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

@@ -40,6 +40,23 @@ function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGu
     }
     return natural;
 }
+function nextInteractionHints(flowState, args, successor) {
+    const hints = { ...(flowState.interactionHints ?? {}) };
+    delete hints[args.stage];
+    if (successor) {
+        if (args.skipQuestions) {
+            hints[successor] = {
+                skipQuestions: true,
+                sourceStage: args.stage,
+                recordedAt: new Date().toISOString()
+            };
+        }
+        else {
+            delete hints[successor];
+        }
+    }
+    return hints;
+}
 export async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track, selectedGateIds, evidenceByGate) {
     const gateId = AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage];
     if (!gateId)
@@ -243,6 +260,7 @@ export async function runAdvanceStage(projectRoot, args, io) {
                 mode: "mandatory",
                 status: "waived",
                 waiverReason,
+                runId: flowState.activeRunId,
                 fulfillmentMode: "role-switch",
                 ts: new Date().toISOString()
             });
@@ -452,10 +470,12 @@ export async function runAdvanceStage(projectRoot, args, io) {
         : flowState.completedStages.includes(args.stage)
             ? [...flowState.completedStages]
             : [...flowState.completedStages, args.stage];
+    const interactionHints = nextInteractionHints(flowState, args, successor);
     const finalState = {
         ...candidateState,
         completedStages,
-        currentStage: successor ?? args.stage
+        currentStage: successor ?? args.stage,
+        interactionHints
     };
     await writeFlowState(projectRoot, finalState);
     if (!args.quiet) {
@@ -466,6 +486,7 @@ export async function runAdvanceStage(projectRoot, args, io) {
             nextStage: successor,
             currentStage: finalState.currentStage,
             completedStages: finalState.completedStages,
+            skipQuestionsHint: args.skipQuestions,
             learnings: {
                 parsed: learningsHarvest.parsedEntries,
                 appended: learningsHarvest.appendedEntries,

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

@@ -8,6 +8,7 @@ export interface AdvanceStageArgs {
     waiverReason?: string;
     acceptProactiveWaiver: boolean;
     acceptProactiveWaiverReason?: string;
+    skipQuestions: boolean;
     quiet: boolean;
     json: boolean;
 }

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

@@ -12,6 +12,7 @@ export function parseAdvanceStageArgs(tokens) {
     let waiverReason;
     let acceptProactiveWaiver = false;
     let acceptProactiveWaiverReason;
+    let skipQuestions = false;
     let quiet = false;
     let json = false;
     for (let i = 0; i < flagTokens.length; i += 1) {
@@ -80,6 +81,10 @@ export function parseAdvanceStageArgs(tokens) {
             acceptProactiveWaiver = true;
             continue;
         }
+        if (token === "--skip-questions") {
+            skipQuestions = true;
+            continue;
+        }
         if (token === "--accept-proactive-waiver-reason") {
             if (!nextToken || nextToken.startsWith("--")) {
                 throw new Error("--accept-proactive-waiver-reason requires a text value.");
@@ -102,6 +107,7 @@ export function parseAdvanceStageArgs(tokens) {
         waiverReason,
         acceptProactiveWaiver,
         acceptProactiveWaiverReason,
+        skipQuestions,
         quiet,
         json
     };

package/dist/run-persistence.d.ts

@@ -42,5 +42,5 @@ export declare function flowStateLockPathFor(projectRoot: string): string;
 interface EnsureRunSystemOptions {
     createIfMissing?: boolean;
 }
-export declare function ensureRunSystem(projectRoot: string, _options?: EnsureRunSystemOptions): Promise<FlowState>;
+export declare function ensureRunSystem(projectRoot: string, options?: EnsureRunSystemOptions): Promise<FlowState>;
 export {};

package/dist/run-persistence.js

@@ -232,6 +232,31 @@ function sanitizeRewinds(value) {
     }
     return out;
 }
+function sanitizeInteractionHints(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    const out = {};
+    for (const [stage, raw] of Object.entries(value)) {
+        if (!isFlowStage(stage))
+            continue;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const typed = raw;
+        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) {
+            continue;
+        }
+        out[stage] = {
+            ...(skipQuestions ? { skipQuestions } : {}),
+            ...(sourceStage ? { sourceStage } : {}),
+            ...(recordedAt ? { recordedAt } : {})
+        };
+    }
+    return out;
+}
 function sanitizeRetroState(value) {
     const fallback = {
         required: false,
@@ -328,6 +353,7 @@ function coerceFlowState(parsed) {
         skippedStages: sanitizeSkippedStages(parsed.skippedStages, track),
         staleStages: sanitizeStaleStages(parsed.staleStages),
         rewinds: sanitizeRewinds(parsed.rewinds),
+        interactionHints: sanitizeInteractionHints(parsed.interactionHints),
         retro: sanitizeRetroState(parsed.retro),
         closeout: sanitizeCloseoutState(parsed.closeout)
     };
@@ -432,12 +458,13 @@ export async function writeFlowState(projectRoot, state, options = {}) {
 export function flowStateLockPathFor(projectRoot) {
     return flowStateLockPath(projectRoot);
 }
-export async function ensureRunSystem(projectRoot, _options = {}) {
+export async function ensureRunSystem(projectRoot, options = {}) {
     await ensureDir(archiveRoot(projectRoot));
     await ensureDir(activeArtifactsPath(projectRoot));
     const statePath = flowStatePath(projectRoot);
     const state = await readFlowState(projectRoot);
-    if (!(await exists(statePath))) {
+    const createIfMissing = options.createIfMissing !== false;
+    if (createIfMissing && !(await exists(statePath))) {
         await writeFlowState(projectRoot, state, { allowReset: true });
     }
     return state;