cclaw-cli 0.5.10 → 0.5.11

package/dist/artifact-linter.js

@@ -242,7 +242,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 +260,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,42 +234,39 @@ 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**
-
-- **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
-
-**Criterion 2 — idempotency**
-
-- **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
+| 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. |
 
-**Criterion 3 — failure visibility**
+### Edge Cases
 
-- **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
+| 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. |
 
-### Non-testable → fixed (comparison)
+### Constraints and Assumptions
 
-| 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.” |
+- **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.
 
-### Test doubles / fixtures (planning notes)
+### Testability Map
 
-- 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.
+| 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\` |
 
-### Traceability reminder
+### Approval
 
-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.`,
+- Approved by: user
+- Date: 2026-04-14`,
     plan: `### Task breakdown (sample)
 
 | ID | Title | depends_on | acceptance_criteria | estimated_effort |

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,7 +714,8 @@ 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: [],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
@@ -715,12 +725,17 @@ 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: "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

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,11 @@ export const ARTIFACT_TEMPLATES = {
 |---|---|---|
 | AC-1 |  |  |
 
+## Interface Contracts
+| Module | Produces | Consumes |
+|---|---|---|
+|  |  |  |
+
 ## Approval
 - Approved by:
 - Date:

package/package.json

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