cclaw-cli 0.5.7 → 0.5.8

package/dist/content/examples.js

@@ -120,7 +120,18 @@ The original premise (“add notifications”) was reframed to **“ensure users
 - 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)
+    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 |
+
+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 |
 | --- | --- | --- |
@@ -128,7 +139,7 @@ The original premise (“add notifications”) was reframed to **“ensure users
 | 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)
 
 \`\`\`
 ┌─────────────┐      ┌──────────────┐      ┌────────────────┐
@@ -142,18 +153,54 @@ The original premise (“add notifications”) was reframed to **“ensure users
                      └──────────────┘
 \`\`\`
 
-### 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 |
 
-- **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)
+### NOT in scope
+
+- 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/stage-schema.js

@@ -385,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.",
@@ -414,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." },
@@ -428,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: [
@@ -441,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",
@@ -452,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: [
@@ -459,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",
@@ -490,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: [
         {
@@ -555,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

@@ -110,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:
@@ -142,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.7",
+  "version": "0.5.8",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {