cclaw-cli 0.5.5 → 0.5.7

package/dist/content/examples.js

@@ -1,74 +1,94 @@
 const STAGE_EXAMPLES = {
-    brainstorm: `### Route selection
+    brainstorm: `### Context
 
-- **Route:** Complex Route
-- **Why:** touches CI behavior, release checks, and CLI flow across multiple components.
+- **Project state:** Monorepo with CI pipeline using custom release scripts. Release checks are scattered across shell scripts with no shared validation logic.
+- **Relevant existing code/patterns:** \`scripts/pre-publish.sh\` does metadata checks. \`src/release/\` has partial validation helpers.
 
-### Round 1 grounding
+### Problem
 
-- **Grounding summary:** "We are improving release reliability for the platform team. Success means invalid release preconditions are caught before publish with explicit operator feedback."
-- **User confirmation:** confirmed.
+- **What we're solving:** release checks are fragile and inconsistent between CI and local runs. Invalid metadata sometimes reaches npm publish.
+- **Success criteria:** invalid release preconditions are caught before publish with explicit operator feedback, in both CI and local workflows.
+- **Constraints:** no new runtime dependencies; must work within existing CI pipeline structure.
 
-### Round 2 forcing questions (boundaries/constraints)
+### Clarifying Questions
 
-**Q1:** "If release metadata is invalid, do we block publishing hard or only warn?"  
-**A1:** "Block hard."
-
-**Decision impact:** release checks become mandatory gates with no warning-only fallback.
+| # | Question | Answer | Decision impact |
+| --- | --- | --- | --- |
+| 1 | If release metadata is invalid, should we block publishing hard or only warn? | Block hard. | Validation becomes a mandatory gate — no warning-only fallback. |
+| 2 | Should the validation logic live in a reusable module or stay as shell scripts? | Reusable module. | Architecture: shared TypeScript module imported by CI and local tooling, not duplicated shell scripts. |
+| 3 | For v1, prioritize rapid delivery or maximum configurability? | Rapid delivery. | Minimal deterministic validation surface; defer plugin/config system to v2. |
 
-**Q2:** "Do we allow new runtime dependencies for speed, or keep runtime dependency set unchanged?"  
-**A2:** "Keep runtime dependencies unchanged."
+### Approaches
 
-**Decision impact:** implementation should reuse existing tooling and built-in capabilities.
+| Approach | Architecture | Trade-offs | Recommendation |
+| --- | --- | --- | --- |
+| A: Reusable validation module | Shared TS module with typed validators, imported by CI scripts and local CLI. Existing \`pre-publish.sh\` calls the module. | Medium upfront effort, high reuse. Requires test coverage for the module. | **Recommended** — best balance of reuse and delivery speed. |
+| B: Hardened shell scripts | Keep existing script approach, add stricter checks and error messages. | Lowest effort. Weak reuse, CI/local divergence risk grows over time. | Viable fallback if TS module is blocked. |
+| C: Full release framework | New release orchestrator with plugin system, config files, rollback commands. | Maximum flexibility. High risk, delivery delay, over-engineered for current needs. | Not recommended for v1. |
 
-### Grounding checkpoint after Round 2
+### Selected Direction
 
-- **Fixed:** hard-block behavior, no new runtime dependencies.
-- **Unknown:** rollback command details and status reporting format.
+- **Approach:** A — Reusable validation module
+- **Rationale:** shared TS module gives consistent behavior in CI and local, avoids script duplication, and stays within the no-new-dependency constraint.
+- **Approval:** approved
 
-### Round 3 forcing questions (trade-offs)
+### Design
 
-**Q3:** "For v1, prioritize rapid delivery or maximum configurability?"  
-**A3:** "Rapid delivery."
+- **Architecture:** single \`release-validator\` module in \`src/release/\` exporting typed check functions. CI script and local CLI both import and run the same checks.
+- **Key components:** \`validateMetadata()\`, \`validateChangelog()\`, \`validateVersion()\` — each returns a typed result with error details. A \`runAll()\` orchestrator runs checks and exits non-zero on any failure.
+- **Data flow:** package.json + CHANGELOG.md → validator module → structured result → CI/CLI renders human-readable report.
 
-**Decision impact:** choose a minimal deterministic validation surface; defer advanced configuration.
+### Assumptions and Open Questions
 
-### Options comparison
+- **Assumptions:** CI remains the primary execution path; existing release metadata files remain the source of truth; v1 prioritizes determinism over customization.
+- **Open questions:** What exact rollback sequence for failed publish? Should status output include machine-readable JSON alongside markdown?
 
-| Option | Pros | Cons | Effort | Recommendation |
-| --- | --- | --- | --- | --- |
-| Script-only checks | Lowest implementation cost | Weak reuse and long-term maintainability | Low | Useful fallback, not preferred |
-| Reusable validation module | Reusable across CI and local runs | Slightly higher upfront design effort | Medium | **Recommended** |
-| Full release framework rewrite | Highest long-term flexibility | High risk and delivery delay | High | Not recommended for v1 |
+### Notes for the next stage
 
-### Approved Direction
+Carry the no-new-dependency constraint and hard-block behavior directly into scope in/out boundaries.`,
+    scope: `### Scope contract
 
-We will implement a **reusable release validation module** used by CI and local tooling, aligned with hard-block safety and no-new-runtime-dependency constraints.
+**Mode selected:** SELECTIVE EXPANSION
+**Default heuristic used:** feature enhancement -> selective
+**Mode-specific analysis result:** hold-scope baseline accepted first; one expansion accepted (degraded-state UX), one deferred (real-time channel upgrade).
 
-### Open Questions
+### Prime Directives (applied)
 
-- What exact rollback command sequence should be documented for failed publish attempts?
-- Should status output include machine-readable JSON in addition to markdown?
+- Zero silent failures: every delivery failure maps to a visible degraded state.
+- Named error surfaces: stream disconnect, auth drift, and publisher timeout are explicit.
+- Four-path data flow mapped: happy, nil payload, empty payload, upstream publish error.
+- Interaction edge cases in scope: double-open panel, reconnect after sleep, stale tab state.
+- Observability in scope: stream error counter, publish-to-visible lag metric, and alert threshold.
 
-### Assumptions (explicit)
+### Premise challenge result
 
-- CI remains the primary execution path; local flow mirrors CI checks.
-- Existing release metadata files remain the source of truth.
-- v1 prioritizes deterministic behavior over broad customization.
+The original premise (“add notifications”) was reframed to **“ensure users know when an action requires follow-up”**, which expands the solution space beyond toast spam to include durable inbox items, empty states, and recovery paths when delivery fails.
 
-### Constraints
+### Dream State Mapping
 
-- No additional runtime dependencies in validation path.
-- Validation overhead should remain acceptable for routine CI execution.
+| Stage | Statement |
+| --- | --- |
+| **CURRENT STATE** | Users miss time-sensitive follow-ups because alerts are ephemeral and not recoverable. |
+| **THIS PLAN** | Introduce durable in-app feed + live updates + explicit degraded mode fallback. |
+| **12-MONTH IDEAL** | Unified notification center with reliable multi-channel fan-out and user-level routing preferences. |
+| **Alignment verdict** | Aligned: this scope builds the durability foundation without prematurely committing to channel expansion. |
 
-### Notes for the next stage
+### Implementation Alternatives
 
-Carry fixed trade-off decisions directly into scope in/out boundaries and deferred list.`,
-    scope: `### Scope contract
+| Option | Summary | Effort (S/M/L/XL) | Risk | Pros | Cons | Reuses |
+| --- | --- | --- | --- | --- | --- | --- |
+| **A (minimum viable)** | Polling-only feed with no live stream | S | Low | Fastest ship, low infra risk | Weaker UX, delayed visibility | Existing REST snapshot endpoint |
+| **B (recommended)** | SSE live updates + REST fallback snapshot | M | Med | Better timeliness, graceful degradation | Requires reconnect handling | Existing event publisher + REST path |
+| **C (ideal architecture)** | Event bus + WebSocket channel + feed projection | XL | High | Strong long-term scalability | Overbuilt for current demand | Partial reuse of publisher only |
 
-**Mode selected:** SELECTIVE EXPANSION
+### Temporal Interrogation
 
-**Premise challenge result:** The original premise (“add notifications”) was reframed to **“ensure users know when an action requires follow-up”**, which expands the solution space beyond toast spam to include durable inbox items, empty states, and recovery paths when delivery fails.
+| Time slice | Likely decision pressure | Lock now or defer? | Reason |
+| --- | --- | --- | --- |
+| **HOUR 1 (foundations)** | Canonical event schema and dedupe key policy | **Lock now** | Prevent downstream rework in storage and UI merge behavior |
+| **HOUR 2-3 (core logic)** | Retry/backoff semantics for stream loss | **Lock now** | Impacts both backend signaling and client state machine |
+| **HOUR 4-5 (integration)** | Handling gaps between snapshot and stream cursor | **Lock now** | Prevent silent data loss during reconnect windows |
+| **HOUR 6+ (polish/tests)** | Banner copy tone and polling cadence tuning | **Defer** | Safe to iterate after baseline reliability is proven |
 
 ### In scope / out of scope / deferred
 
@@ -78,22 +98,28 @@ Carry fixed trade-off decisions directly into scope in/out boundaries and deferr
 | **Out of scope** | Email/SMS/push providers; marketing campaigns; per-user notification preferences beyond on/off |
 | **Deferred** | WebSocket channel; rich media attachments in notifications; full-text search across historical events |
 
+### Discretion Areas
+
+- Client-side badge rendering strategy (optimistic vs server-confirmed) is implementation discretion.
+- Polling fallback backoff curve is implementation discretion if degraded-state UX remains explicit.
+
 ### Error & Rescue Registry (sample entry)
 
 | Capability | Failure mode | Detection | Fallback |
 | --- | --- | --- | --- |
 | Event delivery | SSE connection drops mid-session | Client \`EventSource\` error event + heartbeat timeout | Fall back to REST polling every 30s until SSE reconnect succeeds; show subtle “live updates paused” banner |
 
-### Non-goals (guardrails)
+### Completion Dashboard
 
-- No “infinite history” guarantee in v1; retention policy can be time-bounded.
-- No cross-tenant fan-out optimizations until multi-tenant load tests exist.
+- Checklist findings: 9/9 complete (complex path)
+- Resolved decisions count: 7
+- Unresolved decisions: None
 
-### Owners & checkpoints
+### Scope Summary
 
-- **Product:** confirms reframed premise and acceptance of deferred items.
-- **Engineering:** confirms SSE + REST snapshot split is feasible behind current gateway.
-- **Checkpoint:** scope sign-off happens before detailed component design changes land in the repo.`,
+- Accepted scope: durable feed + SSE + explicit degraded UX.
+- Deferred: WebSocket channel and rich-media/search enhancements.
+- Explicitly excluded: outbound channels and marketing workflows for v1.`,
     design: `### Search Before Building (sample result)
 
 | Layer | Label | What to reuse first |

package/dist/content/skills.js

@@ -24,7 +24,7 @@ function reviewSectionsBlock(stage) {
     const sections = schema.reviewSections.map((sec) => {
         const points = sec.evaluationPoints.map((p) => `- ${p}`).join("\n");
         const stop = sec.stopGate
-            ? "\n\n**STOP.** For each issue found in this section, present it ONE AT A TIME. Describe the problem concretely, present 2-3 options, state your recommendation, and explain WHY. Only proceed to the next section after ALL issues in this section are resolved."
+            ? "\n\n**STOP.** Present the most important question from this section to the user, even if your recommendation is clear. If no issues are found, state your assessment in one sentence and ask the user to confirm before moving on. If issues exist, present them ONE AT A TIME: describe the problem concretely, present 2-3 options, state your recommendation, and explain WHY."
             : "";
         return `### ${sec.title}\n\nEvaluate:\n${points}${stop}`;
     }).join("\n\n");

package/dist/content/stage-schema.js

@@ -22,9 +22,9 @@ const BRAINSTORM = {
     stage: "brainstorm",
     skillFolder: "brainstorming",
     skillName: "brainstorming",
-    skillDescription: "Design-first stage. Route request complexity, run phased forcing questions, and lock an approved direction before scope/design work.",
+    skillDescription: "Design-first stage. Explore context, understand intent through collaborative dialogue, propose distinct approaches, and lock an approved direction before scope/design work.",
     hardGate: "Do NOT invoke implementation skills, write code, scaffold projects, or mutate product behavior until a concrete direction is approved by the user.",
-    purpose: "Turn an initial idea into an approved direction through routing, phased grounding, and decision-forcing questions.",
+    purpose: "Turn an initial idea into an approved design direction through natural collaborative dialogue — understanding the problem before proposing solutions.",
     whenToUse: [
         "Starting a new feature or behavior change",
         "Requirements are ambiguous or trade-offs are unclear",
@@ -36,52 +36,51 @@ const BRAINSTORM = {
         "The task is retrospective only (post-ship audit with no new solution choices)"
     ],
     checklist: [
-        "Principles (one line): one decision-forcing question at a time, grounding summary between rounds, and no implementation before approval.",
-        "Route the work: classify as Simple Route (single-surface, low-risk) or Complex Route (multi-surface, high-uncertainty); explain why.",
-        "Round 1 grounding: restate the problem, desired outcome, and success signal in your own words; get confirmation before deeper questioning.",
-        "Round 2 forcing questions: ask one decision-forcing question per turn about boundaries and constraints; each answer must change a concrete design decision.",
-        "Grounding checkpoint: summarize what is fixed vs still unknown after Round 2; confirm this summary before moving to solution options.",
-        "Round 3 forcing questions: ask trade-off questions that force prioritization (for example speed vs flexibility), then lock assumptions.",
-        "Propose multiple viable approaches with real trade-offs and one explicit recommendation tied to the forced decisions.",
-        "Write `.cclaw/artifacts/01-brainstorm.md` with route, grounding checkpoints, forcing-question log, options, and approved direction; run a contradiction pass.",
-        "Ask the user to review the written artifact and explicitly approve or request changes; only then complete stage and point to `/cc-next`."
+        "**Explore project context** — check files, docs, recent commits to understand what already exists.",
+        "**Assess scope** — if the request covers multiple independent subsystems, flag it and help decompose before deep-diving. Each sub-project gets its own brainstorm cycle.",
+        "**Ask clarifying questions** — one at a time, understand purpose, constraints, and success criteria. Prefer multiple choice when possible. Each question should change what we build, not just gather trivia.",
+        "**Propose 2-3 architecturally distinct approaches** — with real trade-offs and your recommendation. Lead with the recommended option and explain why.",
+        "**Present design by sections** — scale each section to its complexity. Ask after each section whether it looks right so far. Cover: architecture, key components, data flow.",
+        "**Write artifact** to `.cclaw/artifacts/01-brainstorm.md`.",
+        "**Self-review** — scan for placeholders/TODOs, check internal consistency, verify scope is focused, resolve any ambiguity.",
+        "**User reviews artifact** — ask the user to review the written artifact and explicitly approve or request changes.",
+        "**Handoff** — only then complete stage and point to `/cc-next`."
     ],
     interactionProtocol: [
-        "Start with routing (Simple Route vs Complex Route) so question depth matches real complexity.",
-        "Use phased questioning: Round 1 grounding -> Round 2 constraints/boundaries -> grounding checkpoint -> Round 3 trade-off forcing.",
-        "Ask exactly one decision-forcing question per turn; avoid bundled or purely informational questions.",
-        "After each round, publish a short grounding summary (fixed decisions vs unknowns) before continuing.",
-        "Use the Decision Protocol for option selection, with explicit recommendation and rationale.",
+        "Explore what exists before asking what to build — check project files first.",
+        "If the idea is vague or could mean many different things, your FIRST question narrows to a specific kind of project. Do not ask detail questions until the project type is clear.",
+        "Ask exactly one question per turn. Prefer multiple choice. No bundled questions.",
+        "After 2-3 questions, summarize your emerging understanding before continuing so the user can correct course early.",
+        "Each question should change a concrete design decision. Litmus test: if the two most likely answers do not lead to different architectures, make the choice yourself and state it.",
+        "Present design in sections scaled to their complexity — a few sentences for simple aspects, detailed for nuanced ones. Get approval after each section.",
+        "When proposing approaches, lead with your recommendation and explain why.",
         "State explicitly what is being approved when requesting approval.",
-        "Run a brief contradiction and ambiguity pass before handoff.",
+        "Run a brief self-review (placeholders, contradictions, scope, ambiguity) before presenting the artifact.",
         "**STOP.** Wait for explicit user approval after writing the artifact. Do NOT auto-advance."
     ],
     process: [
-        "Route request complexity (Simple Route or Complex Route) and capture rationale.",
-        "Round 1 grounding: restate problem, outcome, and success signal; confirm alignment.",
-        "Round 2 forcing questions: boundaries and constraints one question at a time.",
-        "Grounding checkpoint: summarize fixed decisions and remaining unknowns.",
-        "Round 3 forcing questions: trade-offs and priorities; lock explicit assumptions.",
-        "Offer multiple approaches with recommendation and rationale.",
-        "Capture approved direction in `.cclaw/artifacts/01-brainstorm.md`.",
-        "Run contradiction/ambiguity pass and request explicit user approval.",
+        "Explore project context: check files, docs, recent activity.",
+        "Assess scope: flag if request is too broad, help decompose first.",
+        "Ask clarifying questions one at a time — focus on purpose, constraints, success criteria.",
+        "Propose 2-3 architecturally distinct approaches with trade-offs and a recommendation.",
+        "Present design sections incrementally, get approval after each.",
+        "Write approved direction to `.cclaw/artifacts/01-brainstorm.md`.",
+        "Self-review: placeholder scan, internal consistency, scope check, ambiguity check.",
+        "Request explicit user approval of the artifact.",
         "Handoff to scope only after approval is explicit."
     ],
     requiredGates: [
-        { id: "brainstorm_route_selected", description: "Simple vs Complex route was selected with explicit rationale." },
-        { id: "brainstorm_round1_grounded", description: "Round 1 grounding (problem, outcome, success signal) was confirmed by the user." },
-        { id: "brainstorm_round2_forcing_questions", description: "Round 2 forcing questions captured boundaries and constraints that changed real decisions." },
-        { id: "brainstorm_round3_tradeoff_decisions", description: "Round 3 forcing questions locked explicit trade-off priorities and assumptions." },
-        { id: "brainstorm_options_compared", description: "Multiple solution approaches were compared with real trade-offs and a recommendation." },
+        { id: "brainstorm_context_explored", description: "Project context (files, docs, existing patterns) was checked before asking questions." },
+        { id: "brainstorm_idea_understood", description: "Agent and user share the same understanding of the problem, constraints, and success criteria." },
+        { id: "brainstorm_approaches_compared", description: "2-3 architecturally distinct approaches were compared with real trade-offs and a recommendation." },
         { id: "brainstorm_direction_approved", description: "User approved a concrete direction and what exactly was approved is stated." },
         { id: "brainstorm_artifact_reviewed", description: "User reviewed the written brainstorm artifact and confirmed readiness." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/01-brainstorm.md`.",
-        "Routing decision (`simple` or `complex`) with rationale is recorded.",
-        "Grounding checkpoints between rounds are recorded (fixed decisions vs unknowns).",
-        "Forcing-question log captures question, answer, and decision impact.",
-        "Approaches and recommendation are recorded with explicit trade-offs.",
+        "Project context was explored (files, docs, or recent activity referenced).",
+        "Clarifying questions and their answers are captured.",
+        "2-3 approaches with trade-offs and recommendation are recorded.",
         "Approved direction and approval marker are present.",
         "Assumptions and open questions are captured (or explicitly marked as none)."
     ],
@@ -99,7 +98,7 @@ const BRAINSTORM = {
     blockers: [
         "no explicit approval",
         "critical ambiguity unresolved",
-        "route cannot be determined due to missing context"
+        "project context not explored"
     ],
     exitCriteria: [
         "approved design direction documented",
@@ -108,58 +107,59 @@ const BRAINSTORM = {
         "artifact reviewed by user"
     ],
     antiPatterns: [
-        "Skipping route selection and treating all requests with the same question depth",
-        "Asking non-forcing or bundled questions",
-        "Skipping grounding checkpoints between rounds",
+        "Asking questions without exploring existing project context first",
+        "Asking bundled or purely informational questions that don't change decisions",
+        "Proposing cosmetic option variants instead of architecturally distinct approaches",
         "Jumping directly into implementation",
         "Requesting approval without stating what decision is being approved"
     ],
     rationalizations: [
-        { claim: "This is straightforward so routing is unnecessary.", reality: "Explicit routing prevents under-questioning complex work and over-questioning simple work." },
-        { claim: "Any question is useful context.", reality: "Only forcing questions that change decisions improve design quality." },
-        { claim: "Grounding summaries slow us down.", reality: "Grounding checkpoints prevent hidden drift and reduce expensive rework later." }
+        { claim: "I already know what to build, so exploration is unnecessary.", reality: "Checking files and context catches wrong assumptions that waste hours later." },
+        { claim: "Any question is useful context.", reality: "Only questions whose answers change what we build improve the design." },
+        { claim: "Two options that differ only in tooling count as distinct approaches.", reality: "Distinct means different architecture, not different libraries for the same approach." }
     ],
     redFlags: [
-        "Route is missing or unjustified",
-        "No grounding checkpoint between question rounds",
-        "Questions do not force concrete decisions",
+        "No project context exploration before questions",
+        "Questions that only gather preferences without design impact",
+        "Options that are variants of one approach, not distinct alternatives",
         "Approval requested without explicit decision context"
     ],
     policyNeedles: [
-        "Simple Route / Complex Route",
-        "One forcing question per message",
-        "Grounding checkpoint between rounds",
-        "Multiple approaches with trade-offs",
+        "Explore project context",
+        "One question at a time",
+        "2-3 architecturally distinct approaches",
         "State what is being approved",
+        "Self-review before handoff",
         "Do NOT implement, scaffold, or modify behavior"
     ],
     artifactFile: "01-brainstorm.md",
     next: "scope",
     cognitivePatterns: [
-        { name: "Route Before Depth", description: "Choose question depth using simple-vs-complex routing before diving into details." },
-        { name: "Forcing Question Discipline", description: "Each question must force a concrete decision, not just gather trivia." },
-        { name: "Grounding Cadence", description: "After each question round, re-ground on fixed decisions vs unknowns before continuing." },
-        { name: "Diverge Then Commit", description: "Explore multiple viable options first, then commit only after explicit approval." }
+        { name: "Context Before Questions", description: "Understand what exists before asking what to build." },
+        { name: "Depth Matches Complexity", description: "Brief design for simple tasks, thorough exploration for complex ones." },
+        { name: "Diverge Then Commit", description: "Explore multiple architecturally distinct options first, commit only after explicit approval." },
+        { name: "Question Quality Over Quantity", description: "Each question should change what we build, not just gather trivia." },
+        { name: "Know When To Move On", description: "Stop asking when problem, constraints, and success criteria are clear enough to compare approaches." }
     ],
     reviewSections: [],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
         readsFrom: [],
         writesTo: [".cclaw/artifacts/01-brainstorm.md"],
-        traceabilityRule: "Scope and design decisions must trace back to routed question rounds and approved brainstorm direction."
+        traceabilityRule: "Scope and design decisions must trace back to explored context and approved brainstorm direction."
     },
     artifactValidation: [
-        { section: "Problem Framing", required: true, validationRule: "Must define the user problem, desired outcome, and success signal." },
-        { section: "Routing Decision", required: true, validationRule: "Must state simple vs complex route and explain why." },
-        { section: "Grounding Checkpoints", required: true, validationRule: "Must capture fixed decisions and remaining unknowns between rounds." },
-        { section: "Forcing Questions Log", required: true, validationRule: "Must capture question, answer, and decision impact for each forcing question." },
-        { section: "Options Comparison", required: true, validationRule: "Must compare multiple distinct options with real trade-offs and recommendation." },
-        { section: "Approved Direction", required: true, validationRule: "Must include explicit approval marker and what was approved." },
+        { section: "Context", required: true, validationRule: "Must reference project state and relevant existing code or patterns." },
+        { section: "Problem", required: true, validationRule: "Must define what we're solving, success criteria, and constraints." },
+        { section: "Clarifying Questions", required: true, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
+        { section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs and recommendation." },
+        { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, rationale, and explicit approval marker." },
+        { section: "Design", required: true, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
         { section: "Assumptions and Open Questions", required: true, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }
     ],
     namedAntiPattern: {
-        title: "This Is Too Simple To Brainstorm",
-        description: "Skipping routing and forcing questions because a task looks simple creates silent assumption debt. Even simple-route work needs explicit grounding and approval."
+        title: "This Is Too Simple To Need A Design",
+        description: "Every project goes through this process. Simple projects are where unexamined assumptions cause the most wasted work. The design can be short, but you MUST present it and get approval."
     }
 };
 // ---------------------------------------------------------------------------
@@ -183,18 +183,23 @@ const SCOPE = {
         "The work is a pure implementation or debugging pass within existing scope"
     ],
     checklist: [
-        "Prime Directives — Zero silent failures (every failure mode visible). Every error has a name (not 'handle errors' — name the exception). Every data flow has four paths: happy, nil input, upstream error, downstream timeout. Observability is a scope deliverable, not a post-launch add-on.",
-        "Premise Challenge — Is this the right problem? Could a different framing yield a simpler or more impactful solution? What happens if we do nothing? What are we optimizing for — speed, quality, cost, user experience?",
-        "Existing Code Leverage — Map every sub-problem to existing code. Run searches (grep, codebase exploration) BEFORE deciding to build new. If built-in or library solutions exist, default to them.",
-        "Dream State Mapping — Describe the ideal end state 12 months from now. Does this plan move toward that state or away from it?",
-        "Implementation Alternatives (MANDATORY) — Produce 2-3 distinct approaches. One must be 'minimal viable', one must be 'ideal architecture'. Include effort/risk/reversibility for each.",
-        "Temporal Interrogation — Think in time slices: HOUR 1 (foundation, what must exist first), HOURS 2-3 (core logic, what builds on foundation), HOURS 4-5 (integration, what connects the pieces), HOUR 6+ (polish, what can wait). What decisions must be locked NOW vs deferred to implementation?",
-        "Mode Selection with Default Heuristic — Present four options: SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials). Suggest default: greenfield → EXPANSION, bug/hotfix → HOLD, >15 files touched → suggest REDUCTION. Once selected, commit fully.",
-        "Error & Rescue Registry — For every new capability in scope: what breaks if it fails? How is the failure detected? What is the fallback? This is scope, not design — decide WHAT to protect, not HOW."
+        "**Assess complexity** — Read the brainstorm artifact. If project is simple (single component, clear architecture, personal/prototype), run light-touch scope: mode selection, 3-5 key in/out boundaries, deferred items. Skip Dream State Mapping and Temporal Interrogation. If project is complex (multi-component, team delivery, production), run the full checklist.",
+        "**Prime Directives** — Zero silent failures. For each in-scope capability, name concrete failure modes, the exact error surface, and trace all four data-flow paths (happy, nil, empty, upstream error). Include interaction edge cases (double-click, navigate-away, stale state), observability commitments, and explicit deferred-item logging.",
+        "**Premise Challenge** — Is this the right problem? What if we do nothing? What are we optimizing for?",
+        "**Existing Code Leverage** — Search for existing solutions before deciding to build new.",
+        "**Dream State Mapping** — (complex projects only) describe the ideal state 12 months out using `CURRENT STATE -> THIS PLAN -> 12-MONTH IDEAL`, then verify this scope moves toward that target.",
+        "**Implementation Alternatives** — Produce 2-3 distinct approaches. For each: Name, Summary, Effort (S/M/L/XL), Risk (Low/Med/High), 2-3 Pros, 2-3 Cons, and explicit Reuses. One option must be minimal viable, one must be ideal architecture.",
+        "**Temporal Interrogation** — (complex projects only) simulate implementation timeline: HOUR 1 foundations, HOUR 2-3 core logic, HOUR 4-5 integration surprises, HOUR 6+ polish/tests. Decide what must be locked now vs safely deferred.",
+        "**Mode Selection** — Present expand/selective/hold/reduce with recommendation and default heuristic: greenfield -> expand, feature enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius (>15 files or multi-team impact) -> reduce.",
+        "**Mode-Specific Analysis** — After mode is selected, run the matching analysis: EXPAND (10x and delight opportunities), SELECTIVE (hold-scope rigor then cherry-picked expansions), HOLD (minimum-change-set hardening), REDUCE (ruthless cuts and follow-up split).",
+        "**Error and Rescue Registry** — For each capability: what breaks, how detected, what fallback."
     ],
     interactionProtocol: [
-        "For scope mode selection: use the Decision Protocol — present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended). If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "For scope mode selection: use the Decision Protocol — present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended). Base your recommendation on default heuristics: greenfield -> expand, enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius -> reduce. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "Walk through the scope checklist interactively. Each checklist item that surfaces a decision should be presented to the user as a question, not as a monologue. Do not dump all items at once.",
         "Challenge premise and verify the problem framing before anything else.",
+        "Take a position on every scope decision. Avoid hedging phrases like 'this could work' or 'there are many ways'; state your recommendation and one concrete condition that would change it.",
+        "Use pushback patterns when framing is weak: vague scope -> force a specific user/problem, platform vision -> force a narrowest viable wedge, social proof -> demand behavioral evidence.",
         "Present one structural scope issue at a time for decision. Do NOT batch. Use structured options for each scope boundary question.",
         "Record explicit in-scope and out-of-scope contract.",
         "Once the user accepts or rejects a recommendation, commit fully. Do not re-argue.",
@@ -203,25 +208,29 @@ const SCOPE = {
     ],
     process: [
         "Run premise challenge and existing-solution leverage check.",
-        "Produce 2-3 scope alternatives (minimum viable + ideal included).",
+        "Produce 2-3 scope alternatives in a structured format (Name, Summary, Effort, Risk, Pros, Cons, Reuses) with minimum viable and ideal architecture options included.",
         "Choose scope mode with user approval.",
+        "Run mode-specific analysis that matches the selected scope mode.",
         "Walk through scope review sections one at a time.",
-        "Write explicit scope contract and deferred items.",
-        "Produce scope summary with mode, in-scope, out-of-scope, and deferred."
+        "Write explicit scope contract, discretion areas, and deferred items.",
+        "Produce scope summary plus completion dashboard (checklist findings, number of resolved decisions, unresolved items or `None`)."
     ],
     requiredGates: [
         { id: "scope_premise_challenged", description: "Problem framing and assumptions were challenged." },
-        { id: "scope_alternatives_produced", description: "At least 2 implementation alternatives with effort/risk evaluated." },
+        { id: "scope_alternatives_produced", description: "At least 2 implementation alternatives were evaluated with explicit effort/risk and reuse fields." },
         { id: "scope_mode_selected", description: "One scope mode was explicitly selected." },
         { id: "scope_contract_written", description: "In-scope/out-of-scope contract is documented." },
+        { id: "scope_discretion_documented", description: "Discretion areas are documented (or explicitly marked as none)." },
         { id: "scope_user_approved", description: "User approved the final scope direction." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/02-scope.md`.",
         "In-scope and out-of-scope lists are explicit.",
+        "Discretion areas are explicit (or marked as `None`).",
         "Selected mode and rationale are documented.",
         "Premise challenge findings documented.",
-        "Deferred items list with one-line rationale for each."
+        "Deferred items list with one-line rationale for each.",
+        "Completion dashboard lists checklist findings, decision count, and unresolved items (or `None`)."
     ],
     inputs: ["brainstorm artifact", "timeline constraints", "product priorities"],
     requiredContext: [
@@ -229,22 +238,27 @@ const SCOPE = {
         "existing capabilities and reusable components",
         "delivery deadlines and risk tolerance"
     ],
-    outputs: ["scope mode decision", "scope contract", "deferred scope list", "scope summary"],
+    outputs: ["scope mode decision", "scope contract", "discretion areas list", "deferred scope list", "scope summary", "scope completion dashboard"],
     blockers: [
         "scope mode not selected",
         "in/out boundaries ambiguous",
+        "discretion areas undefined",
         "critical premise disagreement unresolved"
     ],
     exitCriteria: [
         "scope contract approved by user",
+        "discretion areas recorded explicitly",
         "required gates marked satisfied",
         "deferred list recorded explicitly",
+        "completion dashboard produced",
         "scope summary produced"
     ],
     antiPatterns: [
         "Scope silently expanded during discussion",
         "No explicit out-of-scope section",
         "Premise accepted without challenge",
+        "Sycophantic agreement without evidence-based pushback",
+        "Hedged recommendations that avoid taking a position",
         "Batching multiple scope issues into one question",
         "Re-arguing for smaller scope after user rejects reduction"
     ],
@@ -252,19 +266,23 @@ const SCOPE = {
         { claim: "Scope can be finalized during implementation.", reality: "Late scope decisions create architecture churn and missed deadlines." },
         { claim: "Mode selection is unnecessary overhead.", reality: "Mode selection makes trade-offs explicit and prevents silent drift." },
         { claim: "Out-of-scope is obvious.", reality: "Unwritten exclusions return later as hidden requirements." },
-        { claim: "We do not need alternatives for a clear request.", reality: "Even clear requests benefit from a minimal-viable vs ideal comparison." }
+        { claim: "We do not need alternatives for a clear request.", reality: "Even clear requests benefit from a minimal-viable vs ideal comparison." },
+        { claim: "Pushback risks sounding confrontational, so I should stay neutral.", reality: "Respectful pushback catches framing errors before they become expensive implementation mistakes." }
     ],
     redFlags: [
         "No selected mode in artifact",
+        "Mode selected without heuristic justification",
+        "No discretion section (or explicit `None`) in artifact",
         "No deferred/not-in-scope section",
         "No user approval marker",
         "Premise challenge missing or superficial",
         "No implementation alternatives evaluated"
     ],
-    policyNeedles: ["Scope mode", "In Scope", "Out of Scope", "NOT in scope", "Premise Challenge"],
+    policyNeedles: ["Scope mode", "In Scope", "Out of Scope", "Discretion Areas", "NOT in scope", "Premise Challenge"],
     artifactFile: "02-scope.md",
     next: "design",
     cognitivePatterns: [
+        { name: "Depth Matches Complexity", description: "Scale each section to project complexity: concise for simple prototypes, deep for production systems." },
         { name: "Classification Instinct", description: "Categorize every decision by reversibility x magnitude. Most things are two-way doors — move fast. Only slow down for irreversible + high-magnitude decisions." },
         { name: "Inversion Reflex", description: "For every 'how do we win?' also ask 'what would make us fail?' Map failure modes before committing to scope." },
         { name: "Focus as Subtraction", description: "Primary value-add is what to NOT do. Default: do fewer things, better. Every feature must earn its place." },
@@ -330,12 +348,15 @@ const SCOPE = {
         traceabilityRule: "Every scope boundary must be traceable to a brainstorm decision. Every downstream design choice must stay within the scope contract."
     },
     artifactValidation: [
-        { section: "Prime Directives", required: true, validationRule: "Named error modes for each capability. Four paths per data flow." },
+        { section: "Prime Directives", required: true, validationRule: "For each scoped capability: named failure modes, explicit error surface, four data-flow paths, interaction edge cases, observability expectations, and deferred-item handling." },
         { section: "Premise Challenge", required: true, validationRule: "Must contain explicit answers to: right problem? direct path? what if nothing?" },
+        { section: "Implementation Alternatives", required: true, validationRule: "2-3 options with Name, Summary, Effort, Risk, Pros, Cons, and Reuses. Must include minimal viable and ideal architecture options." },
         { section: "Scope Mode", required: true, validationRule: "Must state selected mode and rationale with default heuristic justification." },
         { section: "In Scope / Out of Scope", required: true, validationRule: "Two separate explicit lists. Out-of-scope must not be empty." },
+        { section: "Discretion Areas", required: true, validationRule: "Explicit list of implementer decision zones, or 'None' if scope is fully locked." },
         { section: "Deferred Items", required: true, validationRule: "Each item has one-line rationale. If empty, state 'None' explicitly." },
         { section: "Error & Rescue Registry", required: true, validationRule: "Each scoped capability has: failure mode, detection method, fallback decision." },
+        { section: "Completion Dashboard", required: true, validationRule: "Lists checklist findings, count of resolved decisions, and unresolved decisions (or 'None')." },
         { section: "Scope Summary", required: true, validationRule: "Clean summary: mode, strongest challenges, recommended path, accepted scope, deferred, excluded." }
     ],
     namedAntiPattern: {

package/dist/content/templates.js

@@ -3,46 +3,35 @@ import { orderedStageSchemas } from "./stage-schema.js";
 export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `# Brainstorm Artifact
 
-## Problem Framing
-- **User problem:**
-- **Desired outcome:**
-- **Success signal:**
-
-## Routing Decision
-- **Route:** simple | complex
-- **Reasoning:**
-
-## Grounding Checkpoints
-### Round 1 grounding
-- **What is fixed now:**
-- **What is still unknown:**
-
-### Round 2 grounding
-- **What is fixed now:**
-- **What is still unknown:**
-
-### Round 3 grounding
-- **What is fixed now:**
-- **What is still unknown:**
-
-## Forcing Questions Log
-| Round | Question | User answer | Decision impact |
+## Context
+- **Project state:**
+- **Relevant existing code/patterns:**
+
+## Problem
+- **What we're solving:**
+- **Success criteria:**
+- **Constraints:**
+
+## Clarifying Questions
+| # | Question | Answer | Decision impact |
 |---|---|---|---|
-| 2 |  |  |  |
-| 2 |  |  |  |
-| 3 |  |  |  |
+| 1 |  |  |  |
 
-## Options Comparison
-| Option | Summary | Trade-offs | Recommendation |
+## Approaches
+| Approach | Architecture | Trade-offs | Recommendation |
 |---|---|---|---|
 | A |  |  |  |
 | B |  |  |  |
 
-## Approved Direction
-- **Selected option:**
-- **Why selected:**
-- **What was approved:**
-- **Approval marker:**
+## Selected Direction
+- **Approach:**
+- **Rationale:**
+- **Approval:** pending
+
+## Design
+- **Architecture:**
+- **Key components:**
+- **Data flow:**
 
 ## Assumptions and Open Questions
 - **Assumptions:**
@@ -60,6 +49,27 @@ export const ARTIFACT_TEMPLATES = {
 - Why this path?
 - What if we do nothing?
 
+## Dream State Mapping
+- CURRENT STATE:
+- THIS PLAN:
+- 12-MONTH IDEAL:
+- Alignment verdict:
+
+## Implementation Alternatives
+| Option | Summary | Effort (S/M/L/XL) | Risk (Low/Med/High) | Pros | Cons | Reuses |
+|---|---|---|---|---|---|---|
+| A (minimum viable) |  |  |  |  |  |  |
+| B (ideal architecture) |  |  |  |  |  |  |
+| C (optional) |  |  |  |  |  |  |
+
+## Temporal Interrogation
+| Time slice | Likely decision pressure | Lock now or defer? | Reason |
+|---|---|---|---|
+| HOUR 1 (foundations) |  |  |  |
+| HOUR 2-3 (core logic) |  |  |  |
+| HOUR 4-5 (integration) |  |  |  |
+| HOUR 6+ (polish/tests) |  |  |  |
+
 ## Scope Mode
 - [ ] expand
 - [ ] selective
@@ -74,6 +84,9 @@ export const ARTIFACT_TEMPLATES = {
 ### Out of Scope
 - 
 
+## Discretion Areas
+- (or \`None\`)
+
 ## Deferred Items
 | Item | Rationale |
 |---|---|
@@ -84,6 +97,11 @@ export const ARTIFACT_TEMPLATES = {
 |---|---|---|---|
 |  |  |  |  |
 
+## Completion Dashboard
+- Checklist findings:
+- Resolved decisions count:
+- Unresolved decisions (or \`None\`):
+
 ## Scope Summary
 - Selected mode:
 - Accepted scope:

package/package.json

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