cclaw-cli 0.5.10 → 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();
@@ -242,7 +258,16 @@ export async function lintArtifact(projectRoot, stage) {
     }
     const raw = await fs.readFile(absFile, "utf8");
     const sections = extractH2Sections(raw);
+    const isTrivialOverride = schema.trivialOverrideSections &&
+        schema.trivialOverrideSections.length > 0 &&
+        /trivial.change|mini.design|escape.hatch/iu.test(raw);
+    const overrideSet = isTrivialOverride
+        ? new Set(schema.trivialOverrideSections.map((s) => normalizeHeadingTitle(s).toLowerCase()))
+        : null;
     for (const v of schema.artifactValidation) {
+        const effectiveRequired = overrideSet
+            ? overrideSet.has(normalizeHeadingTitle(v.section).toLowerCase()) ? true : false
+            : v.required;
         const hasHeading = headingPresent(sections, v.section);
         const body = hasHeading ? sectionBodyByName(sections, v.section) : null;
         const validation = body === null
@@ -251,7 +276,7 @@ export async function lintArtifact(projectRoot, stage) {
         const found = hasHeading && validation.ok;
         findings.push({
             section: v.section,
-            required: v.required,
+            required: effectiveRequired,
             rule: v.validationRule,
             found,
             details: found

package/dist/content/examples.js

@@ -180,12 +180,34 @@ Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Q
 | 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 |
 
+### Test Strategy
+
+- **Unit:** validator functions, dedupe-key logic, event schema factories — target 90%+ line coverage.
+- **Integration:** publisher → outbox → read-model pipeline via in-memory DB; SSE reconnect with simulated drops.
+- **E2E:** one happy-path browser test (publish → feed visible) and one degraded-path test (SSE down → REST fallback + banner).
+
+### Performance Budget
+
+| Critical path | Metric | Target | Measurement method |
+| --- | --- | --- | --- |
+| Publish → visible in feed | p95 latency | ≤ 5 s | Integration test with deterministic clock + production Datadog SLO |
+| Feed snapshot load | p99 response time | ≤ 200 ms | Load test with 1 000 items per user |
+| SSE reconnect | Time to first event after drop | ≤ 3 s | Simulated disconnect in integration suite |
+
 ### 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.
 
+### Parallelization Strategy
+
+| Module | Depends on | Parallel lane | Conflict risk |
+| --- | --- | --- | --- |
+| Notification schema (T1) | — | Lane A | None |
+| Publisher + outbox (T2) | T1 | Lane A | None |
+| Client feed + SSE (T3) | T1, T2 | Lane B (after T1) | Shared event type definitions |
+
 ### Unresolved Decisions
 
 | Decision | Status | Options | Missing info | Default if unanswered |
@@ -212,75 +234,86 @@ Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Q
 ### 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.`,
-    spec: `### Acceptance criteria (Given / When / Then)
+    spec: `### Acceptance Criteria
 
-**Criterion 1 — delivery**
+| 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 |
 
-- **Given** a signed-in user with an active session
-- **When** the server publishes a new notification event for that user
-- **Then** the client feed shows the new item within 5 seconds without a full page reload
+### Edge Cases
 
-**Criterion 2 — idempotency**
+| Criterion ID | Boundary case | Error case |
+| --- | --- | --- |
+| AC-1 | Notification published during client reconnect window (boundary: \u2264 5 s delivery still holds after reconnect). | Server publish fails mid-write — client never receives event; REST snapshot fills gap. |
+| AC-2 | Two events with identical dedupe key arrive within same SSE frame (boundary: only one row rendered). | Dedupe-key field missing — reject event at publisher and log error. |
+| AC-3 | SSE disconnects after exactly 30 s heartbeat timeout (boundary: banner appears within 1 s of timeout). | REST snapshot endpoint returns 500 — panel shows "unable to load" with retry button. |
 
-- **Given** the same logical notification is published twice with the same dedupe key
-- **When** the client processes the stream
-- **Then** the feed contains exactly one visible item for that key
+### Constraints and Assumptions
 
-**Criterion 3 — failure visibility**
+- **Constraints:** Max feed size 1 000 items per user. SSE heartbeat interval 30 s (server-side). REST snapshot p99 \u2264 200 ms. No new runtime dependencies.
+- **Assumptions:** Users have a single active session at a time for v1. Existing auth middleware provides user context. Event publisher is single-writer per user.
 
-- **Given** the live connection is unavailable
-- **When** the user opens the notifications panel
-- **Then** the UI shows a non-blocking degraded state and still loads the latest snapshot via REST
+### Testability Map
 
-### Non-testable → fixed (comparison)
+| Criterion ID | Verification approach | Command/manual steps |
+| --- | --- | --- |
+| AC-1 | Integration test: publish event \u2192 assert feed contains item within 5 s (deterministic clock). | \`pnpm vitest run tests/integration/notification-delivery.test.ts\` |
+| AC-2 | Unit test: publish same dedupe key twice \u2192 assert single row in feed store. | \`pnpm vitest run tests/unit/dedupe-feed.test.ts\` |
+| AC-3 | E2E test: kill SSE transport \u2192 assert banner visible + REST snapshot loads. | \`pnpm playwright test tests/e2e/degraded-mode.spec.ts\` |
 
-| Vague (non-testable) | Fixed (observable + testable) |
-| --- | --- |
-| “Notifications should be fast.” | “p95 time from publish to visible feed update ≤ 5s under steady load.” |
-| “The system should handle errors gracefully.” | “If SSE is down, panel renders REST snapshot within 2s and shows ‘live updates paused’.” |
-| “Users should not see duplicates.” | “For dedupe key K, repeated publishes produce exactly one row with key K.” |
+### Approval
 
-### Test doubles / fixtures (planning notes)
+- Approved by: user
+- Date: 2026-04-14`,
+    plan: `### Dependency Graph
 
-- Use a deterministic clock for the “within 5 seconds” criterion in automated tests.
-- Use a fake transport for SSE in unit tests; reserve browser-level tests for one happy path + one degraded path.
+\`\`\`
+T-1 ──▶ T-2 ──▶ T-3
+ │               ▲
+ └───────────────┘
+\`\`\`
 
-### Traceability reminder
+Parallel opportunity: T-1 is a prerequisite for both T-2 and T-3 (T-3 also needs T-2).
 
-Every criterion should map to **at least one automated check** (unit/integration/e2e) before the work is considered “specified enough” to start TDD in earnest.`,
-    plan: `### Task breakdown (sample)
+### Dependency Waves
 
-| 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 |
+#### Wave 1 (foundation)
+- Task IDs: T-1
+- Verification gate: schema tests pass, dedupe key fixtures validated
 
-### Dependency graph (ASCII)
+#### 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 ──▶ T2 ──▶ T3
- │            ▲
- └────────────┘
-\`\`\`
+#### 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
 
-### Acceptance mapping (sample)
+Execution rule: complete and verify each wave before starting the next wave.
 
-| 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 |
+### Task List
 
-### Sequencing rationale (sample)
+| 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\`\`\` |
 
-- **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.
+### Acceptance Mapping
 
-### Risk note
+| 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.d.ts

@@ -71,6 +71,8 @@ export interface StageSchema {
     decisionRecordFormat?: string;
     /** When true, stage skill includes wave auto-execute guidance (tdd). */
     waveExecutionAllowed?: boolean;
+    /** Sections that remain required even when the trivial-change escape hatch is active (design only). */
+    trivialOverrideSections?: string[];
     /** Agent names that MUST be dispatched (or waived) before stage transition — derived from mandatory auto-subagent rows. */
     mandatoryDelegations: string[];
 }

package/dist/content/stage-schema.js

@@ -412,7 +412,8 @@ const 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."
+        "When the user's proposed architecture is suboptimal, say so directly. Offer the alternative with concrete trade-offs, do not bury criticism in praise.",
+        "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity."
     ],
     process: [
         "Read upstream artifacts (brainstorm, scope).",
@@ -514,7 +515,8 @@ const DESIGN = {
         { 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?" }
+        { 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?" },
+        { 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: [
         {
@@ -578,17 +580,23 @@ const DESIGN = {
         traceabilityRule: "Every architecture decision must trace to a scope boundary. Every downstream spec requirement must trace to a design decision."
     },
     artifactValidation: [
+        { section: "Codebase Investigation", required: true, validationRule: "Must list blast-radius files with current responsibilities and discovered patterns." },
+        { section: "Search Before Building", required: true, validationRule: "For each technical choice: Layer 1 (exact match), Layer 2 (partial match), Layer 3 (inspiration), EUREKA labels with reuse-first default." },
         { 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: "Performance Budget", required: true, validationRule: "For each critical path: metric name, target threshold, and measurement method." },
         { 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: "Interface Contracts", required: false, validationRule: "If present: for each module boundary list produces (outputs) and consumes (inputs) with data types." },
+        { section: "Patterns to Mirror", required: false, validationRule: "If present: list discovered codebase patterns to follow, with file references and rationale for each." },
         { 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')." }
     ],
+    trivialOverrideSections: ["Architecture Boundaries", "NOT in scope", "Completion Dashboard"],
     namedAntiPattern: {
         title: "Architecture Will Emerge While Coding",
         description: "Emergent architecture is a myth for non-trivial systems. What actually emerges is accidental complexity, incompatible module boundaries, and tech debt that costs 10x to fix later. Lock architecture explicitly before writing code."
@@ -636,7 +644,8 @@ const SPEC = {
         "Resolve ambiguity before moving to plan. Challenge vague language.",
         "Capture assumptions explicitly, not implicitly.",
         "Require user confirmation on the written spec. **STOP.** Do NOT proceed to plan until user approves.",
-        "For each criterion, ask: how would you test this? If the answer is unclear, rewrite."
+        "For each criterion, ask: how would you test this? If the answer is unclear, rewrite.",
+        "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity."
     ],
     process: [
         "Define measurable acceptance criteria.",
@@ -705,9 +714,33 @@ const SPEC = {
     cognitivePatterns: [
         { name: "Observable Over Descriptive", description: "Requirements describe what can be observed, not what should feel like. Replace every adjective with a measurement." },
         { name: "Boundary Precision", description: "Every acceptance criterion has boundary conditions. What is the minimum valid input? Maximum? What happens at the edges?" },
-        { 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: "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: [
+        {
+            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
+        }
     ],
-    reviewSections: [],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
         readsFrom: [".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
@@ -715,12 +748,19 @@ const SPEC = {
         traceabilityRule: "Every acceptance criterion must trace to a design decision. Every downstream plan task must trace to a spec criterion."
     },
     artifactValidation: [
-        { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable." },
+        { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable. Table should include a Design Decision Ref column tracing back to design artifact." },
         { 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." },
+        { 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." }
-    ]
+    ],
+    namedAntiPattern: {
+        title: "Implementation Will Clarify Requirements",
+        description: "Unclear specs do not become clear during coding — they become contradictory implementations, rework, and scope creep. If a requirement cannot be stated in observable, testable terms right now, it is not ready for implementation. Rewrite it until it is falsifiable."
+    }
 };
 // ---------------------------------------------------------------------------
 // PLAN
@@ -824,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"],
@@ -836,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

@@ -162,6 +162,11 @@ export const ARTIFACT_TEMPLATES = {
 - Integration:
 - E2E:
 
+## Performance Budget
+| Critical path | Metric | Target | Measurement method |
+|---|---|---|---|
+|  |  |  |  |
+
 ## NOT in scope
 - 
 
@@ -169,6 +174,16 @@ export const ARTIFACT_TEMPLATES = {
 - Parallel lanes:
 - Conflict risks:
 
+## Patterns to Mirror
+| Pattern | Source file | Rationale |
+|---|---|---|
+|  |  |  |
+
+## Interface Contracts
+| Module | Produces | Consumes |
+|---|---|---|
+|  |  |  |
+
 ## Unresolved Decisions
 | Decision | Missing info | Owner | Default |
 |---|---|---|---|
@@ -188,9 +203,9 @@ export const ARTIFACT_TEMPLATES = {
     "04-spec.md": `# Specification Artifact
 
 ## Acceptance Criteria
-| ID | Criterion (observable/measurable/falsifiable) |
-|---|---|
-| AC-1 |  |
+| ID | Criterion (observable/measurable/falsifiable) | Design Decision Ref |
+|---|---|---|
+| AC-1 |  |  |
 
 ## Edge Cases
 | Criterion ID | Boundary case | Error case |
@@ -206,6 +221,21 @@ 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 |
+|---|---|---|
+|  |  |  |
+
 ## Approval
 - Approved by:
 - Date:
@@ -234,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.10",
+  "version": "0.5.12",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {