cclaw-cli 0.5.6 → 0.5.7

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,22 +98,28 @@ 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
 
-- 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

@@ -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: {

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:

package/package.json

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