cclaw-cli 7.7.1 → 8.1.0

package/dist/content/examples.js

@@ -1,471 +1,339 @@
-export const BEHAVIOR_ANCHORS = [
-    {
-        stage: "brainstorm",
-        section: "Problem Decision Record",
-        bad: "Frame the problem broadly and quietly add a second outcome (\"and while we're at it, refresh the dashboard\") that no Q&A row sanctioned.",
-        good: "Name one affected user, one current failure mode, and one observable outcome; record any extra outcome as a separate row in `## Not Doing`.",
-        ruleHint: "Scope creep starts in framing — keep the Problem Decision Record single-target."
-    },
-    {
-        stage: "scope",
-        section: "Scope Contract",
-        bad: "Invent a contract from a hunch: \"I'll let the user choose 3 templates\" with no Q&A row, no user feedback citation, no upstream decision.",
-        good: "Cite the Q&A row or upstream decision (`brainstorm > Selected Direction`) that produced each in/out boundary; refuse to lock without that citation.",
-        ruleHint: "Every scope contract row must trace to a recorded user signal or carried-forward decision."
-    },
-    {
-        stage: "design",
-        section: "Codebase Investigation",
-        bad: "Open with \"Use a queue + worker pool\" before reading any file; the architecture choice precedes the trace and the diagram has no concrete node.",
-        good: "List 1-3 blast-radius files in `Codebase Investigation` with current responsibility and reuse candidate first; only then propose architecture in `ADR`.",
-        ruleHint: "Trace before lock — no architecture decision lands without a codebase citation."
-    },
-    {
-        stage: "spec",
-        section: "Acceptance Criteria",
-        bad: "AC: \"System should be fast and reliable\" — no measurable predicate, no verification approach, no design-decision ref.",
-        good: "AC: \"GET /feed returns ≤ 50 items in < 200 ms p95; verified via integration test `tests/feed.spec.ts` against scope `R-2`.\"",
-        ruleHint: "Every AC carries an observable predicate plus the exact evidence command or path that proves it."
-    },
-    {
-        stage: "plan",
-        section: "Execution Posture",
-        bad: "Posture: \"parallel-safe\" with three units that all edit the same `src/api/router.ts`; no shared interface contract, no boundary map.",
-        good: "Posture: \"parallel-safe\" only when each Implementation Unit owns disjoint files and the shared types live in one cited interface contract entry.",
-        ruleHint: "Parallelization needs disjoint units AND a single shared interface contract — claim otherwise and the next batch deadlocks."
-    },
-    {
-        stage: "tdd",
-        section: "RED Evidence",
-        bad: "Controller edits production code or per-slice prose directly, skips ledger rows, then hand-edits auto-render tables. Slice workers never ran; lint blocks on missing span history.",
-        good: "`Task(\"slice-builder --slice S-1 --paths …\")` when major ≥7; otherwise the historical trio must still log `phase=red|green|doc` rows. Controller records before dispatch; linter mirrors history into auto-render blocks.",
-        ruleHint: "Wave-status first, record-before-dispatch, one delegated worker owns RED→GREEN→REFACTOR→slice doc; controller stays out of production edits."
-    },
-    {
-        stage: "review",
-        section: "Layer 2 Findings",
-        bad: "Slip in a rename of `userSvc` → `userService` and a folder reorg under \"Layer 2: cleanup\"; no acceptance criterion or finding ID demanded the change.",
-        good: "Findings name observed defects with `file:line`; refactors land as a separate slice with their own RED/GREEN, not bundled into the review pass.",
-        ruleHint: "Review surfaces findings; it does not refactor. Drive-by edits go back through TDD."
-    },
-    {
-        stage: "ship",
-        section: "Preflight Results",
-        bad: "Preflight: \"Looks good, tests passed last night\"; no fresh command output, no commit SHA, no exit code.",
-        good: "Preflight: paste the command, the exit code, and the commit SHA from this turn; if the suite was not re-run after the last edit, mark BLOCKED.",
-        ruleHint: "Victory-by-confidence is not a preflight. Re-run, capture, cite SHA — or stay BLOCKED."
-    }
-];
-const BEHAVIOR_ANCHOR_BY_STAGE = new Map(BEHAVIOR_ANCHORS.map((entry) => [entry.stage, entry]));
-export function behaviorAnchorFor(stage) {
-    return BEHAVIOR_ANCHOR_BY_STAGE.get(stage) ?? null;
-}
-/**
- * Render the one-line "Behavior anchor (bad → good)" pointer used at the top
- * of each artifact template (01..08). Templates carry the anchor inline so
- * agents see it before they start filling sections; the prose itself lives
- * only in `BEHAVIOR_ANCHORS` to avoid duplication.
- */
-export function renderBehaviorAnchorTemplateLine(stage) {
-    const anchor = behaviorAnchorFor(stage);
-    if (!anchor)
-        return "";
-    return `> Behavior anchor (bad -> good) — ${anchor.section}: bad: ${anchor.bad} good: ${anchor.good}`;
-}
-const STAGE_EXAMPLES = {
-    brainstorm: `## Context
-
-- Project state: release checks exist but CI/local behavior drifts.
-- Existing anchors: \`scripts/pre-publish.sh\`, \`src/release/\`, incident notes.
-
-## Q&A Log
-
-| Turn | Question | User answer (1-line) | Decision impact |
+const PLAN_SMALL = `---
+slug: approval-pill
+stage: plan
+status: active
+ac:
+  - id: AC-1
+    text: "Approval status pill renders pending/approved/rejected on the dashboard tile."
+    status: pending
+  - id: AC-2
+    text: "Pill shows a tooltip with approver name and request age when status != pending."
+    status: pending
+last_specialist: planner
+refines: null
+shipped_at: null
+ship_commit: null
+review_iterations: 0
+security_flag: false
+---
+
+# approval-pill
+
+Add a status pill on the dashboard's request card so users can spot the approval lifecycle at a glance instead of opening the request modal.
+
+## Context
+
+The dashboard currently lists pending and approved requests in two flat tables. Customer support has been pasting the request id into the modal to read the approver — that workflow is slow. We can keep the existing tables but add a single 56×24 pill that encodes the same information visually.
+
+## Frame
+
+- Already true: \`Request\` model has \`status\`, \`approverId\`, \`requestedAt\`. \`User\` model has \`displayName\`.
+- Not sure: whether designers want the pill to animate on status change. We default to no animation.
+- Out of scope: the modal itself; approver workflows; mobile layout.
+
+## Scope
+
+- **In scope:** \`src/components/dashboard/RequestCard.tsx\`, \`src/components/dashboard/StatusPill.tsx\` (new), \`src/components/dashboard/StatusPill.test.tsx\` (new), \`src/styles/tokens.css\` (3 colour tokens).
+- **Out of scope:** \`src/components/dashboard/RequestModal.tsx\`, mobile breakpoints, dark mode.
+
+## Plan
+
+- Phase 1 — Foundation
+  - Add \`StatusPill\` component with three variants (\`pending\`, \`approved\`, \`rejected\`) — \`src/components/dashboard/StatusPill.tsx\`.
+  - Add the three colour tokens — \`src/styles/tokens.css:42\`.
+- Phase 2 — Wiring
+  - Render \`StatusPill\` inside \`RequestCard\` — \`src/components/dashboard/RequestCard.tsx:88\`.
+  - Surface the tooltip with approver name + relative time — \`src/components/dashboard/RequestCard.tsx:90\`.
+
+## Acceptance Criteria
+
+| id | text | status | commit |
 | --- | --- | --- | --- |
-| 1 | Block invalid releases or only warn? | Block. | Validation is a hard gate. |
-| 2 | Shared module or script-only patch? | Shared module. | Reuse in CI/local. |
-| 3 | (stop-signal) | "достаточно, давай драфт" | stop-and-draft |
+| AC-1 | Approval status pill renders pending/approved/rejected on the dashboard tile. | pending | — |
+| AC-2 | Pill shows a tooltip with approver name and request age when status != pending. | pending | — |
+
+## Topology
+
+- topology: inline
+- parallel slices: none
+
+## Traceability block
+
+- AC-1 → commit pending
+- AC-2 → commit pending
+`;
+const PLAN_PARALLEL_BUILD = `---
+slug: search-overhaul
+stage: plan
+status: active
+ac:
+  - id: AC-1
+    text: "Search index includes ticket comments alongside titles."
+    status: pending
+  - id: AC-2
+    text: "Search ranking uses BM25 instead of plain TF."
+    status: pending
+  - id: AC-3
+    text: "Search UI surfaces a \\"comments matched\\" badge."
+    status: pending
+  - id: AC-4
+    text: "Search API returns matched-comments fixture in integration tests."
+    status: pending
+last_specialist: planner
+refines: null
+shipped_at: null
+ship_commit: null
+review_iterations: 0
+security_flag: false
+---
+
+# search-overhaul
+
+## Topology
+
+- topology: parallel-build
+- parallel slices:
+  - AC-1, AC-2 → slice-builder #1 (backend) — owners: \`src/server/search/*\`, \`src/server/db/migrations/2026-05-07-bm25.sql\`
+  - AC-3 → slice-builder #2 (frontend) — owner: \`src/client/search/Hits.tsx\`
+  - AC-4 → slice-builder #3 (integration tests) — owner: \`tests/integration/search.spec.ts\`
+- integration reviewer: \`reviewer #integration\` after the wave finishes.
+
+(File set per slice is disjoint; AC-3 does not depend on AC-1/AC-2 because the badge is purely presentational and can use a feature flag for the first review pass.)
+
+## Plan
+
+(See per-slice owner files; do not merge them into one log. The integration reviewer reconstructs the picture from \`builds/search-overhaul.md\` after the wave.)
+
+## Acceptance Criteria
+
+| id | text | status | commit |
+| --- | --- | --- | --- |
+| AC-1 | Search index includes ticket comments alongside titles. | pending | — |
+| AC-2 | Search ranking uses BM25 instead of plain TF. | pending | — |
+| AC-3 | Search UI surfaces a "comments matched" badge. | pending | — |
+| AC-4 | Search API returns matched-comments fixture in integration tests. | pending | — |
+
+## Traceability block
 
-## Problem Decision Record
+- AC-1 → commit pending
+- AC-2 → commit pending
+- AC-3 → commit pending
+- AC-4 → commit pending
+`;
+const BUILD_LOG = `---
+slug: approval-pill
+stage: build
+status: active
+build_iterations: 2
+last_commit: 9e2c3a4
+---
 
-- Depth: standard
-- Frame type: \`technical-maintenance\`
-- Affected user / role / operator: release operator
-- Current state / failure mode / opportunity: inconsistent validation paths
-- Desired outcome (observable): one deterministic preflight in CI and local flows
-- Evidence / signal: repeated metadata drift incidents
-- Why now: recurring operational cost on every release
-- Do-nothing consequence: continued publish risk
-- Non-goals: no release framework rewrite
+# Build log — approval-pill
 
-## Clarifying Questions
+## Plan summary
 
-| # | Question | Answer | Decision impact |
+Two AC: pill component + tooltip with approver name. Inline topology, single slice-builder.
+
+## Commits
+
+| AC | commit | files | note |
 | --- | --- | --- | --- |
-| 1 | Block invalid releases or only warn? | Block. | Validation is a hard gate. |
-| 2 | Shared module or script-only patch? | Shared module. | Reuse in CI/local. |
+| AC-1 | a1b2c3d | \`src/components/dashboard/StatusPill.tsx:1-58\`, \`src/components/dashboard/StatusPill.test.tsx:1-44\`, \`src/styles/tokens.css:42-44\` | Three variants, snapshot test for each. |
+| AC-2 | 9e2c3a4 | \`src/components/dashboard/RequestCard.tsx:88-104\`, \`src/components/dashboard/RequestCard.test.tsx:51-72\` | Wires \`StatusPill\` + tooltip. Uses existing \`<Tooltip>\` from \`src/components/Tooltip.tsx\`. |
+
+## Open work
 
-## Approach Tier
+_(none — both AC are committed.)_
 
-- Tier: standard
-- Why this tier: cross-cutting release path change, bounded subsystem
+## Hooks invoked
 
-## Approaches
+- \`commit-helper.mjs --ac=AC-1 --message="Add StatusPill component with three variants"\` → \`a1b2c3d\`
+- \`commit-helper.mjs --ac=AC-2 --message="Wire StatusPill + tooltip into RequestCard"\` → \`9e2c3a4\`
+
+## Notes
 
-| Approach | Role | Upside | Architecture | Trade-offs | Recommendation |
+- \`<Tooltip>\` component already supports a \`delay\` prop; reused the 250 ms token from \`src/styles/tokens.css\` instead of hardcoding.
+- Snapshot tests use \`@testing-library/react\` v15 \`render\` API; same as adjacent tests, no test-config changes needed.
+`;
+const REVIEW_LOG = `---
+slug: approval-pill
+stage: review
+status: active
+review_iterations: 2
+modes_run:
+  - code
+  - text-review
+findings_block:
+  - F-1
+  - F-2
+---
+
+# Review — approval-pill
+
+## Run summary
+
+| iteration | mode | reviewer | result |
+| --- | --- | --- | --- |
+| 1 | code | reviewer | block |
+| 2 | code | reviewer | clear |
+
+## Findings
+
+| id | severity | AC | location | finding | fix |
 | --- | --- | --- | --- | --- | --- |
-| Shared validator module | baseline | high | Typed checks reused by CI/local | Medium effort | **Recommended** |
-| Script hardening only | challenger | high | Keep shell checks | Fast but drift risk remains | Fallback |
+| F-1 | block | AC-1 | \`src/components/dashboard/StatusPill.tsx:23\` | The \`rejected\` variant uses the same red token as warning banners; designers want a separate "muted red" token. | Add \`--color-status-rejected\` to \`src/styles/tokens.css\` and reference it. |
+| F-2 | warn | AC-2 | \`src/components/dashboard/RequestCard.tsx:97\` | Tooltip text uses absolute timestamps; product asked for relative ("2 hours ago"). | Replace with \`formatRelativeTime\` from \`src/lib/time.ts\`. |
 
-## Approach Reaction
+## Five Failure Modes pass
 
-- Closest option: shared validator module
-- Concerns: keep v1 delivery tight; avoid framework creep
-- What changed after reaction: kept module path and added incremental rollout guardrails
+Iteration 1:
 
-## Challenger Alternative Enforcement
+- Hallucinated actions: no.
+- Scope creep: no.
+- Cascading errors: no.
+- Context loss: no — all decisions on display name still hold.
+- Tool misuse: no.
 
-- Challenger alternative: script hardening only.
-- Disposition: rejected for this cycle.
-- Enforcement note: preserve the challenger as a bounded fallback, but do not mix both paths in v1 implementation.
+Iteration 2: same answers, all "no".
 
-## Selected Direction
+## Decision
 
-- Selected approach: shared validator module
-- Approval: approved
-- Rationale: best balance of consistency and delivery speed
-- Scope handoff: carry hard-block policy + module boundary into scope
-`,
-    scope: `## Scope contract
+- Iteration 1: **block** — slice-builder mode=fix-only on F-1 and F-2.
+- Iteration 2: **clear** — both findings resolved; ready for ship.
+`;
+const SHIP_NOTES = `---
+slug: approval-pill
+stage: ship
+status: active
+ship_commit: 9e2c3a4
+push_approved: true
+pr_url: https://github.com/example/web/pull/2317
+---
 
-Mode selected: SELECTIVE EXPANSION
+# Ship notes — approval-pill
 
-## In scope / out of scope / deferred
+## Summary
 
-| Category | Items |
-| --- | --- |
-| In scope | durable in-app feed, SSE path, degraded-state UX |
-| Out of scope | email/SMS/push channels, marketing flows |
-| Deferred | WebSocket migration, rich-media payloads |
+Adds a colour-coded approval status pill to dashboard request cards plus a tooltip exposing the approver's display name and the request age. No backend or schema changes.
 
-## Reference Pattern Registry
+## AC ↔ commit map
 
-| Pattern | Disposition | Rationale |
+| AC | commit | description |
 | --- | --- | --- |
-| Snapshot + stream handoff | accept | Proven consistency model |
-| Queue-backed fan-out rewrite | defer | High cost for current demand |
+| AC-1 | \`a1b2c3d\` | StatusPill component with three variants (pending / approved / rejected). |
+| AC-2 | \`9e2c3a4\` | RequestCard wires StatusPill and tooltip. |
 
-## Requirements
+## Push / PR
 
-| R# | Requirement | Why |
-| --- | --- | --- |
-| R-1 | Feed is queryable for recent window | Baseline usability |
-| R-2 | Live updates are timely and recoverable | Reliability |
-| R-3 | Degraded state is explicit to users | No silent failure |
+- push: approved by user on 2026-04-18T14:21Z.
+- PR: https://github.com/example/web/pull/2317.
 
-## Boundary Stress-Tests
+## Breaking changes / migration
 
-- Stream disconnect while user is active -> banner + fallback path required.
-- Snapshot/stream cursor mismatch -> deterministic recovery required.
-`,
-    design: `## Blast Radius
+None. Public component API unchanged.
 
-| File | Change type | Reason |
-| --- | --- | --- |
-| \`src/services/notifications.ts\` | modify | persistence-aware publish path |
-| \`src/api/routes/notifications.ts\` | modify | snapshot + stream endpoints |
-| \`src/ui/feed.tsx\` | modify | degraded banner + reconnect states |
-| \`tests/integration/notifications.test.ts\` | add/update | consistency + auth coverage |
+## Release notes
 
-## Architecture Diagram
+> Dashboard request cards now display a colour-coded approval status pill with a tooltip showing the approver and the request age. No configuration changes required.
+`;
+const DECISION_RECORD = `---
+slug: approval-pill-tooltips
+stage: plan
+status: active
+decision_count: 1
+---
 
-\`\`\`mermaid
-flowchart LR
-  API --> Service --> Outbox --> Projector --> Feed
-  Service --> Stream
-\`\`\`
+# Decisions — approval-pill-tooltips
 
-## Failure Modes
+## D-1 — Permission check is read-from-cached-claim, not re-checked on render
 
-| Failure | Detection | Mitigation |
-| --- | --- | --- |
-| Stream drops | heartbeat timeout | fallback polling + reconnect |
-| Cursor gap | consistency check | replay snapshot delta |
-| Auth mismatch | auth guard log | terminate stream + refresh |
+- **Context:** the tooltip needs to gate email visibility on the \`view-email\` permission. We can either (A) re-check the permission on every render via a synchronous IAM call, (B) read from the already-cached user claim with a 60 s TTL, or (C) push permission into a render-time React context.
+- **Considered options:**
+  - Option A — re-check on render. Pros: always fresh. Cons: adds 8 ms p99 to dashboard render budget; couples the dashboard to IAM uptime.
+  - Option B — cached claim, 60 s TTL. Pros: zero extra latency on render; same path used by \`view-billing\`. Cons: stale for up to 60 s after permission revoke.
+  - Option C — render-time React context. Pros: makes permission explicit at the call site. Cons: another context provider; redundant with the cached claim path.
+- **Selected:** Option B.
+- **Rationale:** consistent with \`view-billing\` (\`src/lib/permissions.ts:14\`); 60 s TTL is acceptable per the threat model since permission changes already pin a fresh login on next nav; render budget is non-negotiable for the dashboard.
+- **Rejected because:** A — render budget impact unacceptable; C — redundant.
+- **Consequences:** any future permission gate on the dashboard is expected to follow the same pattern. \`view-billing\` and \`view-email\` should be tested together to keep the path single-purpose.
+- **Refs:** \`src/lib/permissions.ts:14\`, AC-1, AC-3, threat model entry from security-reviewer iteration 1.
+`;
+const LEARNING_RECORD = `---
+slug: approval-pill-tooltips
+stage: ship
+status: active
+captured_by: orchestrator
+quality_gate: passed
+signals:
+  hasArchitectDecision: true
+  reviewIterations: 2
+  securityFlag: true
+  userRequestedCapture: false
+---
 
-## Test Strategy
+# Learnings — approval-pill-tooltips
 
-- Unit: merge logic, retry budget, projection idempotency.
-- Integration: snapshot+stream consistency and auth boundaries.
-- E2E: degraded banner and recovery UX.
-`,
-    spec: `## Acceptance Criteria
+## What we believed at the start
 
-| AC ID | Criterion | Requirement ref | Verification approach |
-| --- | --- | --- | --- |
-| AC-1 | Feed returns recent window reliably | R-1 | integration test |
-| AC-2 | Live updates visible within agreed latency | R-2 | perf + integration |
-| AC-3 | Disconnect shows degraded state promptly | R-3 | e2e scenario |
+The simple thing is to call IAM on render whenever the dashboard wants to know whether to show email. That assumption was the original brainstormer frame.
 
-## Notes
+## What turned out to be true
 
-- Criteria are observable, measurable, and falsifiable.
-- Every AC maps to at least one task and one test path in plan/tdd.
-`,
-    plan: `## Dependency Graph
+- \`useCurrentUser\` already caches permission claims. We did not need a new mechanism.
+- Designers' "muted red" complaint from the original \`approval-pill\` slug was still relevant for new pill variants; we should add it to the design tokens skill.
 
-- D1 schema + persistence
-- D2 API snapshot/stream
-- D3 UI degraded-state handling
-- D4 tests + observability
+## What turned out to be wrong
 
-## Tasks
+- The render budget is much tighter than expected — 8 ms is not free in this code path. The architect's feasibility check caught this.
 
-| Task ID | Description | Effort | Minutes |
-| --- | --- | --- | --- |
-| T-1 | schema + migration | M | 90 |
-| T-2 | snapshot/stream API updates | M | 90 |
-| T-3 | UI degraded-state path | M | 70 |
-| T-4 | consistency + auth tests | M | 85 |
+## Decisions worth remembering
 
-## Acceptance Mapping
+- D-1 (cached claim with 60 s TTL).
 
-| AC ID | Task IDs |
-| --- | --- |
-| AC-1 | T-1, T-2, T-4 |
-| AC-2 | T-2, T-4 |
-| AC-3 | T-3, T-4 |
+## Patterns we should keep
+
+- Permission gates at render should reuse \`useCurrentUser\` claim caching unless the threat model says otherwise.
+- Refinement slugs that touch sensitive data should set \`security_flag: true\` even when the diff feels small.
+
+## Anti-patterns we should avoid
+
+- Re-checking permissions on render in a tight UI path without measuring the budget first.
+
+## Follow-ups
 
-## WAIT_FOR_CONFIRM
+- Document the 60 s TTL contract on \`useCurrentUser\` in \`src/lib/auth.ts\` (one-line JSDoc).
+- Consider an \`assertPermission\` helper for non-render paths so the rules are obvious.
+`;
+const COMMIT_HELPER_SESSION = `\`\`\`bash
+$ git status --short
+ M src/components/dashboard/StatusPill.tsx
+ M src/components/dashboard/StatusPill.test.tsx
+ M src/styles/tokens.css
+
+$ git add src/components/dashboard/StatusPill.tsx \\
+          src/components/dashboard/StatusPill.test.tsx \\
+          src/styles/tokens.css
+
+$ node .cclaw/hooks/commit-helper.mjs --ac=AC-1 \\
+       --message="Add StatusPill component with three variants"
+
+[commit-helper] AC-1 committed as a1b2c3d
+\`\`\``;
+export const EXAMPLES = [
+    { id: "plan-small", fileName: "plan-small.md", title: "Plan — small slug", description: "Two AC, inline topology, no specialists invoked.", body: PLAN_SMALL },
+    { id: "plan-parallel-build", fileName: "plan-parallel-build.md", title: "Plan — parallel-build topology", description: "Four AC across three slice owners + integration reviewer.", body: PLAN_PARALLEL_BUILD },
+    { id: "build-log", fileName: "build-log.md", title: "Build log — two AC committed", description: "Commit table with file:line refs and hook invocations.", body: BUILD_LOG },
+    { id: "review-log", fileName: "review-log.md", title: "Review — two iterations to clear", description: "Iteration table, findings, Five Failure Modes pass.", body: REVIEW_LOG },
+    { id: "ship-notes", fileName: "ship-notes.md", title: "Ship notes — approved push + PR", description: "Summary, AC↔commit map, push/PR, release notes.", body: SHIP_NOTES },
+    { id: "decision-permission-cache", fileName: "decision-permission-cache.md", title: "Decision — cached permission claim (D-1)", description: "Considered options, selection, rationale, consequences, refs.", body: DECISION_RECORD },
+    { id: "learning-record", fileName: "learning-record.md", title: "Learnings — gated capture", description: "Belief / outcomes / patterns / antipatterns / follow-ups.", body: LEARNING_RECORD },
+    { id: "commit-helper-session", fileName: "commit-helper-session.md", title: "Commit-helper session", description: "Shell transcript for one AC commit via the hook.", body: `# commit-helper.mjs session\n\n${COMMIT_HELPER_SESSION}\n` }
+];
+export const EXAMPLES_INDEX = `# .cclaw/lib/examples/
 
-Plan is ready to execute after user confirmation.
-`,
-    tdd: `## RED
+Worked artifacts the orchestrator and specialists can study before producing their own. Each file is a real-looking plan / build / review / ship / decision / learning artifact, plus a few orchestrator-prompt transcripts.
 
-| Slice | Failing test evidence |
+| file | what it shows |
 | --- | --- |
-| S-1 feed window | expected 30d window, got 7d |
-| S-2 degraded banner | banner absent after forced disconnect |
-
-## Acceptance & Failure Map
-
-| Slice | Source ID | AC ID | Expected behavior | RED-link |
-| --- | --- | --- | --- | --- |
-| S-1 | SRC-1 | AC-1 | feed window honors 30d cap | spanId:tdd-feed-window-red |
-| S-2 | SRC-2 | AC-3 | degraded banner appears on disconnect | spanId:tdd-banner-red (auto-derived from delegation-events.jsonl) |
-
-## GREEN
-
-- Targeted tests pass.
-- Full suite re-run after fixes.
-
-## REFACTOR
-
-- Reduced reconnect state duplication.
-- Revalidated behavior with regression tests.
-`,
-    review: `## Layer 1 — Spec Compliance
-
-| ID | Severity | Finding | Evidence | Status |
-| --- | --- | --- | --- | --- |
-| R-1 | low | AC mapping remains intact | trace table + tests | closed |
-
-## Layer 2 — Code Quality
-
-| ID | Severity | Finding | Evidence | Status |
-| --- | --- | --- | --- | --- |
-| R-2 | high | auth guard gap in stream query path | curl repro + failing test | open |
-
-## Victory Detector
-
-Victory Detector: pass | fail
-
-- Current verdict: fail (R-2 open)
-`,
-    ship: `## Release Checklist
-
-- version/changelog prepared
-- test/build/preflight passed
-- review blockers resolved or explicitly accepted
-
-## Victory Detector
-
-Victory Detector: pass | fail
-
-- Current verdict: pass
-
-## Rollback Plan
-
-- Trigger: error-rate or latency threshold breach
-- Steps: revert + redeploy prior artifact
-- Verification: key metrics return to baseline
-`
-};
-const GOOD_BAD_EXAMPLES = {
-    brainstorm: [{
-            label: "Problem framing",
-            good: "Names affected role, current failure mode, measurable target, and non-goals.",
-            bad: "Need to improve this area somehow.",
-            lesson: "Concrete framing prevents scope drift in downstream stages."
-        }],
-    scope: [{
-            label: "Boundary clarity",
-            good: "Clear in-scope/out-of-scope/deferred lists with concrete capabilities.",
-            bad: "Add improvements where useful.",
-            lesson: "Scope without hard boundaries becomes hidden commitment."
-        }],
-    design: [{
-            label: "Failure handling",
-            good: "Each failure row includes trigger, detection, and mitigation.",
-            bad: "Could fail, handle later.",
-            lesson: "Actionable design risk must be testable and operationally visible."
-        }],
-    spec: [{
-            label: "AC quality",
-            good: "AC includes measurable signal and explicit verification approach.",
-            bad: "System should work reliably.",
-            lesson: "Observable/falsifiable language is required for meaningful verification."
-        }],
-    plan: [{
-            label: "Task granularity",
-            good: "Tasks have bounded outputs, effort, and AC links.",
-            bad: "Implement feature end-to-end.",
-            lesson: "Execution speed depends on concrete, reviewable task slices."
-        }],
-    tdd: [{
-            label: "RED evidence",
-            good: "Includes failing output tied to one behavior slice.",
-            bad: "Tests failed at first.",
-            lesson: "Without concrete RED evidence, behavior intent is not auditable."
-        }],
-    review: [{
-            label: "Finding quality",
-            good: "Severity + falsifiable claim + evidence + status.",
-            bad: "LGTM with a few comments.",
-            lesson: "Review findings are decisions, not vibes."
-        }],
-    ship: [{
-            label: "Rollback contract",
-            good: "Named trigger, exact rollback steps, and verification condition.",
-            bad: "Revert if something goes wrong.",
-            lesson: "Rollback must be executable under incident pressure."
-        }]
-};
-export function stageGoodBadExamples(stage) {
-    const samples = GOOD_BAD_EXAMPLES[stage];
-    if (!samples || samples.length === 0)
-        return "";
-    const blocks = [
-        "## Good vs Bad (at-a-glance)",
-        "",
-        "Contrasting samples to calibrate quality for this stage.",
-        ""
-    ];
-    samples.forEach((sample, index) => {
-        blocks.push(`### ${index + 1}. ${sample.label}`);
-        blocks.push("");
-        blocks.push("**Good**");
-        blocks.push("");
-        blocks.push("> " + sample.good);
-        blocks.push("");
-        blocks.push("**Bad**");
-        blocks.push("");
-        blocks.push("> " + sample.bad);
-        blocks.push("");
-        blocks.push("**Why it matters:** " + sample.lesson);
-        blocks.push("");
-    });
-    return blocks.join("\n");
-}
-/**
- * Returns the full example artifact body for tests and internal quality checks.
- * Generated user projects keep only short inline shape cues.
- */
-export function stageFullArtifactExampleMarkdown(stage) {
-    const examples = STAGE_EXAMPLES[stage];
-    if (!examples)
-        return null;
-    return [
-        `---`,
-        `stage: ${stage}`,
-        `name: ${stage}-stage-examples`,
-        `description: "Full sample artifact for the ${stage} stage."`,
-        `---`,
-        "",
-        `# ${stage} stage — full artifact sample`,
-        "",
-        `The sample uses H2 headings that mirror the artifact a cclaw session must produce, so the markdown is wrapped in a fence to avoid collapsing into the outline.`,
-        "",
-        "```markdown",
-        examples,
-        "```",
-        ""
-    ].join("\n");
-}
-/**
- * Returns short inline shape cues rendered directly inside the stage skill.
- */
-export function stageExamples(stage) {
-    const examples = STAGE_EXAMPLES[stage];
-    if (!examples)
-        return "";
-    return [
-        "## Examples",
-        "",
-        "Shape cues to follow; do not paste these headings verbatim unless they match the work:",
-        ...exampleSummaryBullets(stage),
-        ""
-    ].join("\n");
-}
-function exampleSummaryBullets(stage) {
-    const headings = STAGE_EXAMPLE_SECTION_HEADINGS[stage] ?? [];
-    if (headings.length === 0)
-        return ["- Full artifact structure."];
-    return headings.map((heading) => `- ${heading}`);
-}
-const STAGE_EXAMPLE_SECTION_HEADINGS = {
-    brainstorm: [
-        "Problem Decision Record (free-form Frame type label + universal framing fields)",
-        "Approaches with explicit trade-offs",
-        "Approach Reaction and Selected Direction"
-    ],
-    scope: [
-        "In-scope / out-of-scope / deferred lists with concrete capabilities",
-        "Reference Pattern Registry with clear dispositions",
-        "Requirements table with stable R# IDs"
-    ],
-    design: [
-        "Blast-radius file list",
-        "Mandatory architecture diagram (Mermaid)",
-        "Failure-mode table with detection + mitigation"
-    ],
-    spec: [
-        "Acceptance-criteria table (observable, measurable, falsifiable)",
-        "Requirement-ref column tying each AC back to an R# from scope",
-        "Verification-approach column"
-    ],
-    plan: [
-        "Dependency graph",
-        "Task list with effort + minutes estimate per task",
-        "Acceptance mapping (every AC -> task IDs)",
-        "WAIT_FOR_CONFIRM marker"
-    ],
-    tdd: [
-        "RED evidence per vertical slice",
-        "Acceptance mapping per slice",
-        "GREEN evidence",
-        "REFACTOR notes with behavior-preservation confirmation"
-    ],
-    review: [
-        "Spec-compliance findings (Layer 1)",
-        "Code-quality findings (Layer 2)",
-        "Severity, evidence, and status per finding",
-        "Victory Detector-backed go / no-go verdict"
-    ],
-    ship: [
-        "Release checklist",
-        "Victory Detector: pass | fail",
-        "Rollback plan with trigger, steps, verification",
-        "Runbook and sign-off"
-    ]
-};
+${EXAMPLES.map((e) => `| \`${e.fileName}\` | ${e.description} |`).join("\n")}
+`;