cclaw-cli 0.5.11 → 0.5.12

package/dist/artifact-linter.js

@@ -201,6 +201,22 @@ function validateSectionBody(sectionBody, rule) {
             }
         }
     }
+    if (/Status:\s*pending\s+until/iu.test(rule)) {
+        const statusLine = bodyLines.find((l) => /^\s*-?\s*Status\s*:/iu.test(l));
+        if (!statusLine) {
+            return { ok: false, details: "WAIT_FOR_CONFIRM section must contain a 'Status:' line." };
+        }
+        const validStatuses = ["pending", "approved"];
+        const statusMatch = /Status\s*:\s*(\S+)/iu.exec(statusLine);
+        const statusValue = statusMatch?.[1]?.toLowerCase();
+        if (!statusValue || !validStatuses.includes(statusValue)) {
+            const foundLabel = statusValue || "(empty)";
+            return {
+                ok: false,
+                details: "WAIT_FOR_CONFIRM Status must be exactly one of: " + validStatuses.join(", ") + ". Found: " + foundLabel + "."
+            };
+        }
+    }
     const keywords = extractRequiredKeywords(rule);
     if (keywords.length > 0) {
         const bodyLower = sectionBody.toLowerCase();

package/dist/content/examples.js

@@ -236,11 +236,11 @@ Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Q
 Design output should be **reviewable by someone who did not attend brainstorming**: they can trace from constraints → components → open decisions without reading code.`,
     spec: `### Acceptance Criteria
 
-| ID | Criterion (observable/measurable/falsifiable) |
-| --- | --- |
-| AC-1 | Given a signed-in user with an active session, when the server publishes a new notification event for that user, the client feed shows the new item within 5 seconds without a full page reload. |
-| AC-2 | Given the same logical notification is published twice with the same dedupe key, when the client processes the stream, the feed contains exactly one visible item for that key. |
-| AC-3 | Given the live connection is unavailable, when the user opens the notifications panel, the UI shows a non-blocking "live updates paused" banner and loads the latest snapshot via REST within 2 seconds. |
+| ID | Criterion (observable/measurable/falsifiable) | Design Decision Ref |
+| --- | --- | --- |
+| AC-1 | Given a signed-in user with an active session, when the server publishes a new notification event for that user, the client feed shows the new item within 5 seconds without a full page reload. | Architecture: SSE delivery path |
+| AC-2 | Given the same logical notification is published twice with the same dedupe key, when the client processes the stream, the feed contains exactly one visible item for that key. | Architecture: dedupe-key in event schema |
+| AC-3 | Given the live connection is unavailable, when the user opens the notifications panel, the UI shows a non-blocking "live updates paused" banner and loads the latest snapshot via REST within 2 seconds. | Architecture: REST fallback + degraded UX |
 
 ### Edge Cases
 
@@ -267,39 +267,53 @@ Design output should be **reviewable by someone who did not attend brainstorming
 
 - Approved by: user
 - Date: 2026-04-14`,
-    plan: `### Task breakdown (sample)
-
-| ID | Title | depends_on | acceptance_criteria | estimated_effort |
-| --- | --- | --- | --- | --- |
-| T1 | Define notification event schema + dedupe key rules | — | Spec criteria 2 satisfied in a written contract + fixtures | S |
-| T2 | Implement publisher + outbox write path | T1 | Spec criterion 1 satisfied in integration test (happy path) | M |
-| T3 | Implement client feed + SSE subscribe + REST fallback | T1, T2 | Spec criteria 1–3 satisfied in e2e-style tests (including degraded mode) | L |
-
-### Dependency graph (ASCII)
+    plan: `### Dependency Graph
 
 \`\`\`
-T1 ──▶ T2 ──▶ T3
- │            ▲
- └────────────┘
+T-1 ──▶ T-2 ──▶ T-3
+ │               ▲
+ └───────────────┘
 \`\`\`
 
-### Acceptance mapping (sample)
+Parallel opportunity: T-1 is a prerequisite for both T-2 and T-3 (T-3 also needs T-2).
 
-| Spec criterion | Tasks that cover it | Notes |
-| --- | --- | --- |
-| Criterion 1 (delivery) | T2, T3 | T2 proves publish path; T3 proves UI subscription path |
-| Criterion 2 (idempotency) | T1, T2 | Schema + publisher tests must include dedupe cases |
-| Criterion 3 (failure visibility) | T3 | Explicit degraded-mode test case |
+### Dependency Waves
+
+#### Wave 1 (foundation)
+- Task IDs: T-1
+- Verification gate: schema tests pass, dedupe key fixtures validated
 
-### Sequencing rationale (sample)
+#### Wave 2 (core logic)
+- Task IDs: T-2
+- Depends on: Wave 1 (T-1 complete)
+- Verification gate: integration test proves publish-to-outbox path
 
-- **T1 first** prevents rework when event keys change mid-build.
-- **T2 before T3** ensures the UI is not built on a mocked publisher that will not match production semantics.
-- **T3 last** integrates transport concerns once contracts are stable.
+#### Wave 3 (integration)
+- Task IDs: T-3
+- Depends on: Wave 2 (T-2 complete)
+- Verification gate: e2e tests pass for delivery, dedupe, and degraded mode
 
-### Risk note
+Execution rule: complete and verify each wave before starting the next wave.
+
+### Task List
+
+| Task ID | Description | Acceptance criterion | Verification command | Effort |
+| --- | --- | --- | --- | --- |
+| T-1 | Define notification event schema + dedupe key rules | AC-1, AC-2: schema contract + fixtures | \`\`\`pnpm vitest run tests/unit/notification-schema.test.ts\`\`\` |
+| T-2 | Implement publisher + outbox write path | AC-1: integration test (happy path publish) | \`\`\`pnpm vitest run tests/integration/publisher.test.ts\`\`\` |
+| T-3 | Implement client feed + SSE subscribe + REST fallback | AC-1, AC-2, AC-3: e2e tests including degraded mode | \`\`\`pnpm playwright test tests/e2e/notification-feed.spec.ts\`\`\` |
+
+### Acceptance Mapping
+
+| Criterion ID | Task IDs |
+| --- | --- |
+| AC-1 (delivery within 5s) | T-2, T-3 |
+| AC-2 (idempotency) | T-1, T-2 |
+| AC-3 (failure visibility) | T-3 |
 
-If T3 grows too large, split “transport” vs “UI state machine” into two tasks while keeping the dependency graph acyclic.`,
+### WAIT_FOR_CONFIRM
+- Status: pending
+- Confirmed by:`,
     tdd: `### RED test (Vitest) — written before production code
 
 \`\`\`typescript

package/dist/content/stage-schema.js

@@ -717,7 +717,30 @@ const SPEC = {
         { name: "Assumption Surfacing", description: "Implicit assumptions are invisible requirements. Force every assumption into an explicit statement. If you cannot name the assumption, you have not found it yet." },
         { name: "Ambiguity Classification", description: "Before resolving any unclear requirement, classify it: (A) Insufficient information — ask the user. (B) Multiple valid interpretations — enumerate and pick with justification. (C) Genuinely unknown — propose hypothesis and validation path. Never treat all ambiguity the same way." }
     ],
-    reviewSections: [],
+    reviewSections: [
+        {
+            title: "Acceptance Criteria Audit",
+            evaluationPoints: [
+                "Is every criterion observable (can you point to evidence of pass/fail)?",
+                "Is every criterion measurable (numeric threshold or boolean outcome)?",
+                "Is every criterion falsifiable (can you describe what failure looks like)?",
+                "Does every criterion trace to a design decision (Design Decision Ref)?",
+                "Are there any vague adjectives (fast, intuitive, robust) without thresholds?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Testability Audit",
+            evaluationPoints: [
+                "Does every criterion have a concrete test description in the Testability Map?",
+                "Does every test specify a verification approach (unit, integration, e2e, manual)?",
+                "Does every test include a runnable command or manual steps?",
+                "Are edge cases (boundary + error) defined for every criterion?",
+                "Can you run every verification command right now and get a meaningful result?"
+            ],
+            stopGate: true
+        }
+    ],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
         readsFrom: [".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
@@ -729,6 +752,8 @@ const SPEC = {
         { section: "Edge Cases", required: true, validationRule: "At least one boundary and one error condition per criterion." },
         { section: "Constraints and Assumptions", required: true, validationRule: "All implicit assumptions surfaced. Constraints have sources." },
         { section: "Testability Map", required: true, validationRule: "Each criterion maps to a concrete test description with verification approach (unit, integration, e2e, manual) and command or manual steps." },
+        { section: "Vague to Fixed", required: false, validationRule: "If present: table with original vague wording and rewritten observable/testable version for each ambiguous requirement." },
+        { section: "Non-Functional Requirements", required: false, validationRule: "If present: performance thresholds, security constraints, scalability limits, reliability targets with measurable values." },
         { section: "Interface Contracts", required: false, validationRule: "If present: for each module boundary list produces (outputs) and consumes (inputs) with data types." },
         { section: "Approval", required: true, validationRule: "Explicit user approval marker present." }
     ],
@@ -839,9 +864,35 @@ const PLAN = {
     cognitivePatterns: [
         { name: "Vertical Slice Thinking", description: "Each task delivers one thin end-to-end slice of value. Horizontal layers (all models, then all controllers) create integration risk. Vertical slices (one feature through all layers) reduce it." },
         { name: "Two-Minute Smell Test", description: "If a competent engineer cannot understand and start a task in two minutes, the task is too large or too vague. Break it down further." },
-        { name: "Make the Change Easy, Then Make the Easy Change", description: "Refactor first, implement second. Never structural + behavioral changes simultaneously. Sequence tasks accordingly." }
+        { name: "Make the Change Easy, Then Make the Easy Change", description: "Refactor first, implement second. Never structural + behavioral changes simultaneously. Sequence tasks accordingly." },
+        { name: "Diagnose Before Fix", description: "Before decomposing work, understand the current state of the codebase. Read existing code, tests, and conventions. Tasks should reference what exists, not assume a blank slate." },
+        { name: "Scrap Signals", description: "If a task description is vague, the acceptance criterion is missing, or the verification command is a placeholder — it is scrap. Either rewrite it or remove it. Half-specified tasks waste more time than no tasks." },
+        { name: "Risk-First Exploration", description: "Sequence the highest-risk or most uncertain tasks first. If wave 1 proves the risky assumption wrong, the rest of the plan can adapt. If the risk is buried in wave 3, you discover failure late." }
+    ],
+    reviewSections: [
+        {
+            title: "Task Decomposition Audit",
+            evaluationPoints: [
+                "Does every task target a single coherent area (vertical slice)?",
+                "Can each task be completed in 2-5 minutes?",
+                "Does every task have an acceptance criterion link and verification command?",
+                "Are there tasks that touch multiple unrelated areas?",
+                "Would a new engineer understand and start each task within two minutes?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Wave Completeness Audit",
+            evaluationPoints: [
+                "Does every task belong to exactly one wave?",
+                "Does each wave have a verification gate?",
+                "Are wave dependencies explicit and acyclic?",
+                "Is the acceptance mapping complete — every spec criterion covered?",
+                "Are there hidden dependencies between tasks in different waves?"
+            ],
+            stopGate: true
+        }
     ],
-    reviewSections: [],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
         readsFrom: [".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
@@ -851,10 +902,15 @@ const PLAN = {
     artifactValidation: [
         { section: "Dependency Graph", required: true, validationRule: "Ordering and parallel opportunities explicit. No circular dependencies." },
         { section: "Dependency Waves", required: true, validationRule: "Every task belongs to a wave. Each wave has an exit gate and dependency statement." },
-        { section: "Task List", required: true, validationRule: "Each task: ID, description, acceptance criterion link, verification command." },
+        { section: "Task List", required: true, validationRule: "Each task: ID, description, acceptance criterion link, verification command, and effort estimate (S/M/L)." },
         { section: "Acceptance Mapping", required: true, validationRule: "Every spec criterion is covered by at least one task." },
+        { section: "Risk Assessment", required: false, validationRule: "If present: per-task or per-wave risk identification with likelihood, impact, and mitigation strategy." },
         { section: "WAIT_FOR_CONFIRM", required: true, validationRule: "Explicit marker present. Status: pending until user approves." }
-    ]
+    ],
+    namedAntiPattern: {
+        title: "Task Details Can Be Finalized During Coding",
+        description: "Underspecified tasks do not become clear during implementation — they become context thrash, broken sequencing, and rework. Every task needs an acceptance criterion, a verification command, and a wave assignment before execution starts. If you cannot describe what 'done' looks like for a task, the task is not ready."
+    }
 };
 // ---------------------------------------------------------------------------
 // TDD — RED → GREEN → REFACTOR cycle (merged test + build)

package/dist/content/templates.js

@@ -221,6 +221,16 @@ export const ARTIFACT_TEMPLATES = {
 |---|---|---|
 | AC-1 |  |  |
 
+## Vague to Fixed
+| Original (vague) | Rewritten (observable/testable) |
+|---|---|
+|  |  |
+
+## Non-Functional Requirements
+| Category | Requirement | Threshold | Measurement |
+|---|---|---|---|
+|  |  |  |  |
+
 ## Interface Contracts
 | Module | Produces | Consumes |
 |---|---|---|
@@ -254,15 +264,20 @@ export const ARTIFACT_TEMPLATES = {
 Execution rule: complete and verify each wave before starting the next wave.
 
 ## Task List
-| Task ID | Description | Acceptance criterion | Verification command |
-|---|---|---|---|
-| T-1 |  |  |  |
+| Task ID | Description | Acceptance criterion | Verification command | Effort |
+|---|---|---|---|---|
+| T-1 |  |  |  |  |
 
 ## Acceptance Mapping
 | Criterion ID | Task IDs |
 |---|---|
 | AC-1 | T-1 |
 
+## Risk Assessment
+| Task/Wave | Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
 ## WAIT_FOR_CONFIRM
 - Status: pending
 - Confirmed by:

package/package.json

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