cclaw-cli 0.5.6 → 0.5.8

package/dist/content/examples.js

@@ -49,8 +49,46 @@ Carry the no-new-dependency constraint and hard-block behavior directly into sco
     scope: `### Scope contract
 
 **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).
 
-**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.
+### Prime Directives (applied)
+
+- 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.
+
+### 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.
+
+### Dream State Mapping
+
+| 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. |
+
+### Implementation Alternatives
+
+| 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 |
+
+### Temporal Interrogation
+
+| 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
 
@@ -60,23 +98,40 @@ Carry the no-new-dependency constraint and hard-block behavior directly into sco
 | **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
+
+- Checklist findings: 9/9 complete (complex path)
+- Resolved decisions count: 7
+- Unresolved decisions: None
 
-- No “infinite history” guarantee in v1; retention policy can be time-bounded.
-- No cross-tenant fan-out optimizations until multi-tenant load tests exist.
+### Scope Summary
 
-### Owners & checkpoints
+- 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: `### Codebase Investigation (blast-radius files)
+
+| File | Current responsibility | Patterns discovered |
+| --- | --- | --- |
+| \`src/api/routes/user.ts\` | User CRUD endpoints | Express router, Zod validation, throws \`AppError\` |
+| \`src/services/event-bus.ts\` | In-process pub/sub | EventEmitter wrapper, typed channels, no persistence |
+| \`src/middleware/auth.ts\` | JWT verification | Extracts user from token, attaches to \`req.context\` |
+| \`tests/integration/user.test.ts\` | User route tests | Supertest, factory helpers, \`beforeEach\` DB reset |
 
-- **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.`,
-    design: `### Search Before Building (sample result)
+Discovery: existing EventEmitter-based bus has no durability — notifications must add persistence layer on top, not replace the bus.
+
+### Search Before Building (sample result)
 
 | Layer | Label | What to reuse first |
 | --- | --- | --- |
@@ -84,7 +139,7 @@ Carry the no-new-dependency constraint and hard-block behavior directly into sco
 | Layer 2 | existing codebase | Existing auth middleware, existing API client wrapper, existing feature flags helper |
 | Layer 3 | npm | A small, well-maintained SSE helper (only if Layer 1–2 cannot cover framing/reconnect ergonomics) |
 
-### Minimal component diagram (ASCII)
+### Architecture Diagram (mandatory)
 
 \`\`\`
 ┌─────────────┐      ┌──────────────┐      ┌────────────────┐
@@ -98,18 +153,54 @@ Carry the no-new-dependency constraint and hard-block behavior directly into sco
                      └──────────────┘
 \`\`\`
 
-### Unresolved Decision (sample entry)
+Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Queue (persist) → Read Model (project).
+
+### What Already Exists
+
+| Sub-problem | Existing code/library | Layer | Reuse decision |
+| --- | --- | --- | --- |
+| Auth context extraction | \`src/middleware/auth.ts\` | Layer 1 | Reuse as-is |
+| Event fan-out | \`src/services/event-bus.ts\` | Layer 2 | Wrap with persistence adapter |
+| SSE framing | None | Layer 3 | Evaluate \`better-sse\` npm package |
+| Notification schema | None | — | New: define in \`src/schemas/notification.ts\` |
+
+### Failure Mode Table
+
+| Failure | Trigger | Detection | Mitigation | User impact |
+| --- | --- | --- | --- | --- |
+| SSE connection drop | Network interruption | Client heartbeat timeout (30s) | Auto-reconnect with exponential backoff + snapshot fallback | Brief delay (≤10s), no data loss |
+| Duplicate publish | Retry after timeout | Dedupe key check in outbox | Upsert with idempotency key | None (transparent) |
+| Queue backpressure | Spike >1000 events/s | Queue depth metric alarm | Back-pressure signal to publisher, shed non-critical events | Delayed delivery of low-priority notifications |
+
+### NOT in scope
 
-- **Decision:** Should the feed be modeled as append-only events or as CRUD “notification rows”?
-- **Status:** OPEN
-- **Options:** (A) append-only event log + projection, (B) mutable rows with status fields, (C) hybrid with compaction job
-- **Deadline:** Decide before implementation of persistence migrations (end of week)
+- Outbound channels (email, push, SMS) — deferred to v2.
+- Admin notification management UI — separate workstream.
+- Notification preferences / mute rules — requires user settings redesign.
+
+### Unresolved Decisions
+
+| Decision | Status | Options | Missing info | Default if unanswered |
+| --- | --- | --- | --- | --- |
+| Feed storage model | OPEN | (A) append-only event log, (B) mutable rows, (C) hybrid | Load testing results on read patterns | (A) append-only — safest for audit trail |
 
 ### Interface sketch (non-binding)
 
 - **Client → server:** \`GET /api/me/notifications/snapshot?limit=50\` plus optional cursor parameters (if adopted).
 - **Server → client:** \`GET /api/me/notifications/stream\` as SSE with periodic heartbeats.
 
+### Completion Dashboard
+
+| Review Section | Status | Issues |
+| --- | --- | --- |
+| Architecture Review | issues-found-resolved | Decided on outbox pattern over direct pub/sub |
+| Code Quality Review | clear | — |
+| Test Review | issues-found-resolved | Added integration test gap for SSE reconnect |
+| Performance Review | clear | — |
+| Distribution & Delivery Review | clear | — |
+
+**Decisions made:** 4 | **Unresolved:** 1 (feed storage model)
+
 ### Quality bar for this stage
 
 Design output should be **reviewable by someone who did not attend brainstorming**: they can trace from constraints → components → open decisions without reading code.`,

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

@@ -48,8 +48,10 @@ const BRAINSTORM = {
     ],
     interactionProtocol: [
         "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.",
-        "Each question should change a concrete design decision. If a question only gathers trivia, skip it.",
+        "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.",
@@ -136,7 +138,8 @@ const BRAINSTORM = {
         { 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: "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"],
@@ -180,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.",
@@ -200,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: [
@@ -226,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"
     ],
@@ -249,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." },
@@ -327,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: {
@@ -361,28 +385,35 @@ const DESIGN = {
         "Implementation has already started and requires review instead of design lock"
     ],
     checklist: [
+        "Trivial-Change Escape Hatch — If scope artifact shows ≤3 files, zero new interfaces, and no cross-module data flow, skip full review sections. Produce a mini-design: one paragraph of rationale, list of changed files, one risk to watch. Proceed to spec.",
         "Design Doc Check — read existing design docs, scope artifact, brainstorm artifact. If a design doc exists that covers this area, check for 'Supersedes:' and use the latest. Use upstream artifacts as source of truth.",
+        "Codebase Investigation — Before any design decision, read the actual code in the blast radius. List every file that will be touched, its current responsibilities, and existing patterns (error handling, naming, test style). Design must conform to discovered patterns, not impose new ones without justification.",
         "Step 0: Scope Challenge — what existing code solves sub-problems? Minimum change set? Complexity check: 8+ files or 2+ new services = complexity smell → flag for possible scope reduction.",
         "Search Before Building — For each technical choice (library, pattern, architecture), search for existing solutions. Label findings: Layer 1 (exact match), Layer 2 (partial match, needs adaptation), Layer 3 (inspiration only), EUREKA (unexpected perfect solution). Default to existing before custom.",
-        "Architecture Review — system design, component boundaries, data flow, scaling, security architecture. For each new codepath: one realistic production failure scenario.",
+        "Architecture Review — system design, component boundaries, data flow, scaling, security architecture. For each new codepath: one realistic production failure scenario. **Mandatory:** produce at least one architecture diagram (ASCII, Mermaid, or tool-generated) showing component boundaries and data flow direction.",
         "Code Quality Review — code organization, DRY violations, error handling patterns, over/under-engineering assessment.",
         "Test Review — diagram every new flow, data path, error path. For each: what test type covers it? Does one exist? What is the gap? Produce test plan artifact.",
         "Performance Review — N+1 queries, memory concerns, caching opportunities, slow code paths. What breaks at 10x load? At 100x?",
         "Parallelization Strategy — If multiple independent modules, produce dependency table: which can be built in parallel? Where are conflict risks? Flag shared-state modules.",
         "Unresolved Decisions — List any design decisions that could not be resolved in this session. For each: what information is missing? Who can provide it? What is the default if no answer comes?",
-        "Distribution Check — If the plan creates new artifact types (packages, CLI tools, configs), document the build/publish story. How does it reach the user?"
+        "Distribution Check — If the plan creates new artifact types (packages, CLI tools, configs), document the build/publish story. How does it reach the user?",
+        "Deferred Items Cross-Reference — Collect every item explicitly deferred during design review. Each must appear in the Unresolved Decisions table or in the upstream scope artifact's deferred list. No deferred item may exist only in conversation — it must be written down."
     ],
     interactionProtocol: [
         "Review architecture decisions section-by-section.",
         "For EACH issue found in a review section, present it ONE AT A TIME. Do NOT batch multiple issues.",
-        "For each issue: use the Decision Protocol — describe concretely with file/line references, present labeled options (A/B/C) 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 each issue: use the Decision Protocol — 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). 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.",
         "Only proceed to the next review section after ALL issues in the current section are resolved.",
         "If a section has no issues, say 'No issues found' and move on.",
         "Do not skip failure-mode mapping.",
-        "For design baseline approval: present the full baseline. **STOP.** Do NOT proceed until user explicitly approves the design."
+        "For design baseline approval: present the full baseline. **STOP.** Do NOT proceed until user explicitly approves the design.",
+        "Take a firm position on every recommendation. Do NOT hedge with 'it depends' or 'you could do either'. State your opinion, then justify it.",
+        "Use pushback patterns for weak framing: if the user says 'it's just a small change', respond with 'small changes to shared interfaces have outsized blast radius — let's map it'. If 'we'll refactor later', respond with 'later never comes — show me the refactor ticket or do it now'.",
+        "When the user's proposed architecture is suboptimal, say so directly. Offer the alternative with concrete trade-offs, do not bury criticism in praise."
     ],
     process: [
         "Read upstream artifacts (brainstorm, scope).",
+        "Investigate codebase: read files in blast radius, catalogue current patterns and responsibilities.",
         "Run Step 0 scope challenge: existing code leverage, minimum change set, complexity check.",
         "Walk through each review section interactively.",
         "Define architecture boundaries and ownership.",
@@ -390,9 +421,11 @@ const DESIGN = {
         "Map failure modes and recovery strategy.",
         "Define test coverage strategy and performance budget.",
         "Produce required outputs: NOT-in-scope section, What-already-exists section, diagrams, failure mode table.",
+        "Produce completion dashboard: list every review section with status (clear / issues-found-resolved / issues-open), count of decisions made, and list of unresolved items.",
         "Write design lock artifact for downstream spec/plan."
     ],
     requiredGates: [
+        { id: "design_codebase_investigated", description: "Blast-radius files read and current patterns catalogued." },
         { id: "design_scope_challenge_done", description: "Step 0 scope challenge completed with existing-code mapping." },
         { id: "design_architecture_locked", description: "Architecture boundaries are explicit and approved." },
         { id: "design_data_flow_mapped", description: "Data/state flow includes edge-case paths." },
@@ -404,7 +437,8 @@ const DESIGN = {
         "Failure-mode table exists with mitigations.",
         "Test strategy includes unit/integration/e2e expectations.",
         "NOT-in-scope section produced.",
-        "What-already-exists section produced."
+        "What-already-exists section produced.",
+        "Completion dashboard lists every review section status, decision count, and unresolved items (or 'None')."
     ],
     inputs: ["scope contract", "system constraints", "non-functional requirements"],
     requiredContext: [
@@ -417,7 +451,8 @@ const DESIGN = {
         "risk and failure map",
         "test and performance baseline",
         "NOT-in-scope section",
-        "What-already-exists section"
+        "What-already-exists section",
+        "design completion dashboard"
     ],
     blockers: [
         "architecture ambiguity remains",
@@ -428,6 +463,7 @@ const DESIGN = {
         "design baseline approved",
         "all review sections completed",
         "required gates marked satisfied",
+        "completion dashboard present with all review-section statuses",
         "artifact complete for spec handoff"
     ],
     antiPatterns: [
@@ -435,20 +471,26 @@ const DESIGN = {
         "Missing data-flow edge cases",
         "No performance budget for critical path",
         "Batching multiple design issues into one question",
-        "Skipping review sections because plan seems simple"
+        "Skipping review sections because plan seems simple",
+        "Agreeing with user's architecture choice without evaluating alternatives",
+        "Hedging every recommendation with 'it depends' instead of taking a position"
     ],
     rationalizations: [
         { claim: "Architecture can emerge incrementally while coding.", reality: "Unplanned architecture decisions cause incompatible module boundaries." },
         { claim: "Failure modes are edge cases we can ignore for now.", reality: "Production incidents usually come from unplanned edge paths." },
         { claim: "Performance can be optimized after launch.", reality: "Missing performance budgets make regressions invisible until late." },
-        { claim: "This is a strategy doc so implementation sections do not apply.", reality: "Implementation details are where strategy breaks down. Every section must be evaluated." }
+        { claim: "This is a strategy doc so implementation sections do not apply.", reality: "Implementation details are where strategy breaks down. Every section must be evaluated." },
+        { claim: "The user preferred approach A, so we should go with it.", reality: "User preference is an input, not a conclusion. Evaluate on engineering merit. If approach B is objectively better, recommend B with evidence." },
+        { claim: "Both options are roughly equivalent.", reality: "Options are never equivalent once you quantify effort (S/M/L/XL) and risk (Low/Med/High). If you cannot distinguish them, you have not investigated deeply enough." }
     ],
     redFlags: [
         "No explicit architecture boundary section",
         "No failure recovery strategy",
         "No defined test/perf baseline",
         "Review sections skipped or condensed",
-        "No NOT-in-scope output section"
+        "No NOT-in-scope output section",
+        "No What-already-exists output section",
+        "Design decisions made without reading the actual code first"
     ],
     policyNeedles: [
         "Architecture",
@@ -466,7 +508,10 @@ const DESIGN = {
         { name: "Essential vs Accidental Complexity", description: "Before adding anything: is this solving a real problem or one we created? Distinguish essential complexity from accidental." },
         { name: "Blast Radius Instinct", description: "Every decision evaluated through: what is the worst case and how many systems/people does it affect?" },
         { name: "Completeness Push", description: "AI effort is cheap. Push for completeness in plans: cover all files in blast radius, all edge cases in touched code, all affected tests. Favor doing it now over creating a TODO." },
-        { name: "Owner Preference Alignment", description: "Every recommendation must align with project conventions (DRY, test style, minimal diff, edge-case rigor). Read existing patterns before recommending new ones." }
+        { name: "Owner Preference Alignment", description: "Every recommendation must align with project conventions (DRY, test style, minimal diff, edge-case rigor). Read existing patterns before recommending new ones." },
+        { name: "Failure Is Information", description: "A design that fails fast and visibly is better than one that silently degrades. Map every failure mode and make it observable. Undetected failures compound." },
+        { name: "Search Breadth Before Depth", description: "Before committing to a design path, survey the full solution space: stdlib, existing code, open-source, prior art. A 30-minute search can save a 30-hour custom build." },
+        { name: "Outside Voice", description: "When confidence is high and options seem obvious, that is exactly when to seek contradiction. Ask: what would a skeptical reviewer challenge here? What assumption am I not questioning?" }
     ],
     reviewSections: [
         {
@@ -531,12 +576,15 @@ const DESIGN = {
     },
     artifactValidation: [
         { section: "Architecture Boundaries", required: true, validationRule: "Must list component boundaries with ownership." },
+        { section: "Architecture Diagram", required: true, validationRule: "At least one diagram (ASCII, Mermaid, or image) showing component boundaries and data flow direction." },
         { section: "Data Flow", required: true, validationRule: "Must include happy path, nil input, empty input, upstream error paths." },
         { section: "Failure Mode Table", required: true, validationRule: "Each failure mode has: trigger, detection, mitigation, user impact." },
         { section: "Test Strategy", required: true, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },
+        { section: "What Already Exists", required: true, validationRule: "For each sub-problem: existing code/library found (Layer 1-3/EUREKA label), reuse decision, and adaptation needed." },
         { section: "NOT in scope", required: true, validationRule: "Work considered and explicitly deferred with one-line rationale." },
         { section: "Parallelization Strategy", required: false, validationRule: "If multi-module: dependency table, parallel lanes, conflict flags." },
-        { section: "Unresolved Decisions", required: false, validationRule: "If any: what info is missing, who provides it, default if unanswered." }
+        { section: "Unresolved Decisions", required: false, validationRule: "If any: what info is missing, who provides it, default if unanswered." },
+        { section: "Completion Dashboard", required: true, validationRule: "Lists every review section with status (clear / issues-found-resolved / issues-open), decision count, and unresolved items (or 'None')." }
     ],
     namedAntiPattern: {
         title: "Architecture Will Emerge While Coding",

package/dist/content/templates.js

@@ -49,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
@@ -63,6 +84,9 @@ export const ARTIFACT_TEMPLATES = {
 ### Out of Scope
 - 
 
+## Discretion Areas
+- (or \`None\`)
+
 ## Deferred Items
 | Item | Rationale |
 |---|---|
@@ -73,6 +97,11 @@ export const ARTIFACT_TEMPLATES = {
 |---|---|---|---|
 |  |  |  |  |
 
+## Completion Dashboard
+- Checklist findings:
+- Resolved decisions count:
+- Unresolved decisions (or \`None\`):
+
 ## Scope Summary
 - Selected mode:
 - Accepted scope:
@@ -81,11 +110,34 @@ export const ARTIFACT_TEMPLATES = {
 `,
     "03-design.md": `# Design Artifact
 
+## Codebase Investigation
+| File | Current responsibility | Patterns discovered |
+|---|---|---|
+|  |  |  |
+
+## Search Before Building
+| Layer | Label | What to reuse first |
+|---|---|---|
+| Layer 1 |  |  |
+| Layer 2 |  |  |
+| Layer 3 |  |  |
+
 ## Architecture Boundaries
 | Component | Responsibility | Owner |
 |---|---|---|
 |  |  |  |
 
+## Architecture Diagram
+
+\\\`\\\`\\\`
+(ASCII, Mermaid, or tool-generated diagram showing component boundaries and data flow direction)
+\\\`\\\`\\\`
+
+## What Already Exists
+| Sub-problem | Existing code/library | Layer | Reuse decision |
+|---|---|---|---|
+|  |  |  |  |
+
 ## Data Flow
 - Happy path:
 - Nil/empty input path:
@@ -113,6 +165,17 @@ export const ARTIFACT_TEMPLATES = {
 | Decision | Missing info | Owner | Default |
 |---|---|---|---|
 |  |  |  |  |
+
+## Completion Dashboard
+| Review Section | Status | Issues |
+|---|---|---|
+| Architecture Review |  |  |
+| Code Quality Review |  |  |
+| Test Review |  |  |
+| Performance Review |  |  |
+| Distribution & Delivery Review |  |  |
+
+**Decisions made:** 0 | **Unresolved:** 0
 `,
     "04-spec.md": `# Specification Artifact
 

package/package.json

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