@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/.claude/skills/chronicle/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: chronicle
+description: "Write the session log \u2014 alias for /session-log during the grace window through 2026-10-31. Renamed per ADR-040 Decision 1. Both names resolve to the same behavior; after grace ends, only /session-log resolves."
+problem: "Grace-window sessions still call for /chronicle. New alias for /session-log keeps both live."
+value: "Writes the session log through the grace window. Same output as /session-log."
+inputs: [Optional session or goal ref]
+outputs: [Session log entry at chronicle/*]
+tier: lite
+user_invocable: true
+disable_model_invocation: false
+modes: [default]
+composes_with: [session-log]
+---
+
+# /chronicle (alias — renamed to /session-log)
+
+## What you get
+
+`/chronicle` is the old name for `/session-log`. It still works during the grace window through 2026-10-31 per ADR-031 and `.claude/rules/we-dont-break-adopters.md`. Both names produce the same session log entry with the same shape and the same Gate Evidence table.
+
+The rename is per ADR-040 Decision 1 (planning-skill vocabulary rewrite). "Chronicle" was borrowed from Ryan Singer's Shape Up; "session log" reads plain per Krug and Cooper consultations documented at ADR-040.
+
+## When to use it
+
+Prefer `/session-log`. Existing operator habit or existing scripts that call `/chronicle` still work through the grace window. After 2026-10-31 the alias stops resolving; migrate to `/session-log` before then.
+
+## What this alias does
+
+Runs the same procedure as `/session-log`. See `.claude/skills/session-log/SKILL.md` for the full body. Both files ship the same behavior during the grace window; the pointer in `standards/file-renames.json` records the rename.
+
+## Grace window details
+
+- **Renamed at:** 2026-07-17 per ADR-040
+- **Alias active until:** 2026-10-31
+- **After grace window:** `/chronicle` invocation returns "unknown skill"; only `/session-log` resolves
+- **Registered in:** `standards/file-renames.json`
+- **Fixture test:** `.claude/hooks/tests/fixtures/adopter-2026-07-17-chronicle-rename/` per `.claude/rules/file-rename-discipline.md`
+- **Artifact directory names:** stay as `chronicle/` (bassclef) and `docs/chronicle/` (app repos) during this window. A separate migration handles the directory rename after the SKILL rename settles.
+
+## Composes with
+
+- `/session-log` — canonical name; this file is the alias
+- `/session-end` — the closeout skill that calls the log entry as part of the MUST tier
+
+## Refs
+
+- ADR-040 planning-skill vocabulary and lite profile
+- `.claude/rules/we-dont-break-adopters.md` — grace window discipline
+- `.claude/rules/file-rename-discipline.md` — rename registration
+- `standards/file-renames.json` — this rename registered here
+- `.claude/skills/session-log/SKILL.md` — canonical target
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/.claude/skills/clean-artifacts/SKILL.md

@@ -0,0 +1,249 @@
+---
+tier: lite
+name: clean-artifacts
+description: "Sweep workflow exhaust from the repo (stale verify markers, old Playwright screenshots, expired SDLC traces). Strict allowlist; never touches git-tracked files or critical artifacts. Dry-run by default. Runs standalone or via /session-end."
+problem: "Workflow exhaust piles up \u2014 stale verify markers, old screenshots, expired SDLC traces."
+value: "Sweeps three classes of exhaust from the working tree. Idempotent. Safe by exclusion list."
+inputs: [Optional --dry-run flag]
+outputs: [Files removed by class, Skipped safety-list entries, Total space reclaimed]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /clean-artifacts — Workflow Exhaust Sweeper
+
+Over time, bassclef-substrate repos accumulate workflow exhaust in
+predictable locations:
+
+- `state/markers/verify/` files for merged branches (`/verify` leftovers)
+- `.playwright-mcp/` screenshots from old visual reviews
+- `docs/sdlc-traces/` hook-output logs from prior sessions
+- `/tmp/claude-*` markers belonging to expired sessions
+- `.test-baseline` and similar transient verify outputs at repo root
+
+None of these are load-bearing once their session ends. None are
+git-tracked (all covered by `.gitignore`). But without an explicit
+sweep, they rot in place.
+
+`/clean-artifacts` does the sweep. **Strict allowlist** — only touches
+paths this skill knows about. **Dry-run default** — requires explicit
+`--delete` flag to actually remove anything. **Age-gated** — never
+touches files newer than configurable thresholds (default 7 days).
+
+## When to use
+
+- At session-end (hooked via `/session-end` May tier — see below)
+- Ad-hoc, when repo root feels cluttered
+- Before a long flight / offline period when you want to reduce
+  checkout size
+- After merging many PRs — verify-markers for merged branches pile up
+
+## When NOT to use
+
+- When investigating an issue that might reference recent markers
+  (keep evidence intact until resolved)
+- Immediately after `/verify` — the marker you just wrote is fresh
+  and load-bearing for the pre-commit gate
+- Before `/session-end` runs its Must tier (sweep happens AFTER
+  chronicle + whereami are written, never before)
+
+## Usage
+
+```
+/clean-artifacts                 → dry-run; list what would be removed
+/clean-artifacts dry-run          → same as default
+/clean-artifacts --delete         → actually remove files
+/clean-artifacts --age=3          → override age threshold (default 7 days)
+/clean-artifacts --delete --age=14 → combine flags
+```
+
+## Implementation
+
+As of goal `2026-08-25-tier-consistency-clean-artifacts-inline`, the sweep logic lives in `lib/clean-artifacts-sweep.sh`. The lib is a shared deep module. Both this skill and `/session-end` (lite tier) source it. The skill body wraps the lib with dry-run default plus the operator-facing dispatch surface.
+
+To invoke the lib directly:
+
+```bash
+source lib/clean-artifacts-sweep.sh
+clean_artifacts_sweep                # dry-run
+clean_artifacts_sweep --delete       # remove files
+clean_artifacts_sweep --age=14       # override age threshold
+```
+
+The strict allowlist, safety list, and refusal thresholds live inside the lib. See `docs/decompositions/2026-08-25-clean-artifacts-sweep.md` for the responsibility model + interface contract. See `lib/tests/clean-artifacts-sweep.test.sh` for Tier 0 tests.
+
+## Clean targets (strict allowlist)
+
+The skill NEVER touches anything outside this list.
+
+| Path | What | Age gate | Notes |
+|------|------|----------|-------|
+| `state/markers/verify/*.marker` | `/verify` markers for branches | >7d default | Skip markers matching current branch |
+| `.playwright-mcp/*.png` | Playwright screenshots | >7d default | Skip if referenced by open visual-review |
+| `.playwright-mcp/*.yaml` | Playwright trace snapshots | >7d default | — |
+| `docs/sdlc-traces/*.log` | SDLC hook traces | >30d default | Longer keep for audit |
+| `/tmp/claude-verify-*` | Temp verify markers (machine-local) | any age | Current branch marker excluded |
+| `/tmp/claude-session-timing-*` | Session timing files | >1d | Current session's excluded |
+| `*.test-baseline` (repo root only) | Transient vitest baseline output | any age | Only at root — never in test dirs |
+
+### NEVER touched (safety list — explicit exclusions)
+
+| Path | Why excluded |
+|------|-------------|
+| `.claude/CHECKPOINT.md` | Load-bearing for graceful-exit recovery |
+| `.claude/SESSION_LOCK` | Only removed by save-state.sh or session-end |
+| `.claude/LAST_SAVE` | Referenced by session-start hook |
+| `state/markers/verify/<current-branch>.marker` | Fresh; pre-commit gate depends on it |
+| Any git-tracked file | Git history is authority |
+| `docs/chronicle/**` | Chronicles are permanent record |
+| `docs/whereami.md` | Load-bearing project state |
+| `docs/operator-private/journals/**` | Pending push to Google Doc |
+| `docs/iteration-bets/**` | Active + historical goal records |
+| `docs/decompositions/**` | Decomposition artifacts |
+| `docs/designs/**` | Design docs |
+| `docs/release-notes/**` | Release history |
+| `research/**` | Spike output (ignored by git but kept locally) |
+
+Any target not in the clean-targets table is untouched — no matter
+how old, no matter how unused-looking. Safety before tidiness.
+
+## Procedure
+
+### Step 1: Enumerate candidates
+
+For each clean-target path, glob the matching files. Apply the age
+gate (skip files modified within the threshold). Apply the
+never-touched exclusions.
+
+Emit to stdout:
+
+```
+## Clean-artifacts dry-run — [timestamp]
+
+**Clean targets** (would remove with --delete):
+
+state/markers/verify/ (5 candidates, >7d):
+  feature-150-xxx.marker (12d old)
+  feature-152-xxx.marker (18d old)
+  ...
+
+.playwright-mcp/ (3 candidates, >7d):
+  review-2026-04-05.png (13d old)
+  ...
+
+**Skipped** (protected):
+
+state/markers/verify/feature-176-stack-3-clean-artifacts.marker
+  (current branch marker — protected)
+.claude/CHECKPOINT.md (load-bearing, never cleaned)
+
+**Summary**
+- 8 files would be removed (~240KB)
+- Run with --delete to proceed
+```
+
+### Step 2: Safety checks (if --delete)
+
+Before actually deleting, perform these checks:
+
+1. Confirm current branch marker is in the skip list
+2. Confirm `.claude/CHECKPOINT.md` was not flagged
+3. Count candidates — if >100, refuse and surface a warning
+   ("unexpected volume; inspect clean-targets table before overriding")
+4. Check total size — if >50MB, refuse similarly
+5. If any path outside clean-targets table appears, abort — bug in
+   the skill, not a situation to override
+
+### Step 3: Delete (only if --delete)
+
+Iterate the candidate list, remove each file. Log each removal. On
+any error, stop and report partial state — never continue past an
+unexpected failure.
+
+### Step 4: Report
+
+```
+## Clean-artifacts complete — [timestamp]
+
+Removed: N files (~M KB)
+Skipped: N protected
+Errors: N (details below if any)
+```
+
+## Session-end integration
+
+`/clean-artifacts` is invoked at the end of `/session-end`'s May
+tier — AFTER chronicle, whereami, journal entries, and tag push
+have all completed. Never before.
+
+Rationale: May tier is conditional and best-effort. If `/session-end`
+is in a degraded state (timeout pending, network flaky), skipping the
+sweep is fine. Chronicle + whereami are not.
+
+The `/session-end` SKILL.md May tier should include:
+
+```markdown
+11. **Clean workflow exhaust** (May — conditional)
+   Run /clean-artifacts --delete to sweep stale markers, screenshots,
+   and traces. Dry-run first if session was unusual (spikes, aborts).
+```
+
+## Hook integration (optional, future)
+
+A mechanical helper could live at `.claude/hooks/clean-artifacts.sh`
+that invokes the skill's dry-run logic deterministically without
+requiring the agent. Not required for v1; skill invocation from
+`/session-end` is sufficient.
+
+## Rules
+
+- **Dry-run is the default.** `--delete` must be explicit.
+- **Strict allowlist only.** If a path isn't in the clean-targets
+  table, don't clean it.
+- **Never touch git-tracked files.** Check with `git ls-files` before
+  deleting. Even if a git-tracked file matches a clean-target glob,
+  skip it and report.
+- **Age gate before delete.** Every clean-target has a minimum age;
+  never delete fresh files.
+- **Current-session markers protected.** Current branch's verify
+  marker, current session's timing file, the active `.claude/SESSION_LOCK`.
+- **Report on every sweep.** Even if no candidates found, emit a
+  one-line "nothing to clean" so the operator knows the sweep ran.
+
+## Common pitfalls
+
+- **Running during active verify**: if `/verify` just wrote a marker
+  and you run `/clean-artifacts --delete --age=0`, that marker could
+  disappear before the pre-commit hook reads it. Always respect the
+  age gate.
+- **Expanding the clean-targets table without safety review**: adding
+  a path is a one-way door if files were already deleted. Require a
+  review against the NEVER touched list before expanding.
+- **Running in CI**: CI runs are ephemeral; the checkout is a fresh
+  clone. Sweep is wasted work there. Don't wire this into CI
+  pipelines.
+
+## Relationship to other skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `/session-end` | Composer includes `/clean-artifacts` as May-tier step |
+| `/verify` | Writes markers; `/clean-artifacts` cleans stale ones (different lifetime) |
+| `/substrate-check` | Validates wiring; doesn't clean |
+| `/visual-review` | Writes screenshots; `/clean-artifacts` ages them out |
+
+## Why this skill exists
+
+Observed across multiple bassclef + POA sessions: verify-markers for
+merged branches accumulate indefinitely. Playwright screenshots from
+old visual reviews sit in `.playwright-mcp/` until manually removed.
+SDLC traces grow without bound. Each is individually small; collectively
+they make `git status` noisy and `du` numbers embarrassing.
+
+Codified from `/onboard-repo`'s observation that repo roots in new
+consumer repos start clean but accumulate exhaust rapidly. Rather
+than ask each operator to sweep manually, give them one command.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/.claude/skills/decompose/SKILL.md

@@ -0,0 +1,280 @@
+---
+tier: lite
+name: decompose
+description: "Audit responsibilities before you build. Reads sequence diagrams. Assigns GRASP roles. Identifies interfaces. Audits cross-cutting concerns. Selects patterns from GoF, Fowler, and stack idioms. Bridges design and build."
+problem: "Cross-cutting concerns bolt into implementations. Logging and tracing pile inside business code."
+value: "A responsibility matrix that keeps each concern in its own class. Decorators stay clean."
+inputs: [Sequence diagrams from spec, A decomposition target — feature or defect]
+outputs: [Responsibility matrix, Interface registry, Pattern map for construction]
+user_invocable: true
+disable_model_invocation: false
+composes_with: [spec, ia-model, interaction-design, pattern-review, temperance]
+---
+
+# /decompose
+
+## What you get
+
+A responsibility matrix + interface registry + pattern map for any non-trivial construction work. Three phases — GRASP responsibility assignment with mandatory interface names, coupling / variation / stability audit plus cross-cutting concerns (the -ilities), and pattern selection from GoF / Fowler / DDD / Clean Architecture vocabularies. The output answers "who handles what, through which interfaces, with what cross-cutting concerns" before the Builder writes a line of code.
+
+Key principle: GRASP is applied literally, not conceptually. Every Indirection and Protected Variation assignment MUST produce a named interface. Every cross-cutting concern (observability, testability, extensibility, security, cacheability) MUST be identified in the NFR check and resolved as a Decorator or Proxy wrapping an interface — never bolted inside an implementation.
+
+## When to use it
+
+- **Before any non-trivial build.** If the work touches 2+ layers (UI + API, API + DB, worker + queue), decompose first.
+- **After `/interaction-design`** produces sequence diagrams. Those diagrams are the primary input.
+- **When responsibility is ambiguous.** "Should this logic live in the API route or a service?" — decompose answers that structurally, not by gut feel.
+- **On any Construction branch** (`feature/`, `fix/`) creating changes to `src/` per `.claude/rules/oo-ad-entry-point.md`.
+
+Skip for single-file changes, config updates, docs, simple CRUD with obvious ownership, or pure refactors within one function.
+
+## ADR-consult — fire before scope confirmation (per bassclef-upstream#424)
+
+Read every relevant ADR in `architecture/decisions/` before confirming scope. If your scope deviates from any ADR's decision or constraints, surface the deviation as the first agenda item — the operator decides amend-ADR vs revise-scope.
+
+Per `.claude/rules/adr-discipline.md`. Mechanism: `adr-discipline-check.sh` fires on architectural edits (wired in `.claude/settings.json` since bet 28a WU-1).
+
+## FAQ
+
+### What are the three entry-point states?
+
+- **State 1 — Canvas/greenfield.** Full flow preceded (canvas → spec → ia-model → interaction-design → sequence diagrams). `/decompose` reads sequence diagrams as primary input. If `/use-case` produced fully-dressed cases at `docs/use-cases/UC-NNN-*.md`, those feed in parallel.
+- **State 2 — Epic/defect (no sequence diagrams, spec exists).** Reverse-engineer — read the spec, read current implementation, identify system events from ticket + code, treat current as "as-is" and ticket as "to-be." Phase 2 NFR check becomes especially critical.
+- **State 3 — Bug/hotfix (symptom known, cause unknown).** `/diagnose` already ran per SDLC gates. Read the diagnose output (Is/Is Not, Five Whys, Hypothesis), identify which responsibility is mis-assigned OR which cross-cutting concern is missing (the bug is often a missing interface / decorator, not a logic error). Phase 1 is targeted.
+
+### Why must every Indirection or Protected Variation produce a named interface?
+
+Because "Indirection: adapter wraps provider" without naming `IProviderAdapter` has not completed the decomposition. The interface IS the artifact, not the principle citation. Bet 2026-07-04 experience — the POA session bolted Langfuse tracing inside HaikuImputer because the earlier decomposition named "Indirection" without producing `IAssociationImputer`. Interface name forces the concrete artifact.
+
+### What are the -ilities?
+
+Five cross-cutting concerns Phase 2 audits — observability, testability, extensibility, security, cacheability. Each maps to a Decorator or Proxy wrapping an interface. Missing any -ility from the audit is the same failure mode as skipping tests. If an -ility applies to a responsibility, it MUST appear as its own row with a named interface or wrapper.
+
+### When does a luminary lens influence pattern choice?
+
+Phase 1 (Responsibility Matrix) and Phase 2 (Friction Points + NFR) are luminary-agnostic — they are structural facts about the domain. Phase 3 is the first phase where a luminary POV legitimately influences pattern choice among valid options. A luminary cannot override GRASP or NFR gates; the luminary shapes pattern choice among valid options only.
+
+If the iteration goal declares multiple `primary_luminaries`, each pattern choice in Phase 3 cites which luminary drove it. All-one-name attribution when the goal lists multiple luminaries is the collapse-to-single failure.
+
+### What's the output artifact?
+
+A single Decomposition Summary at `docs/decompositions/[feature-name].md` containing the three-phase output plus an Interface Registry (the primary Builder handoff artifact) plus proposed file structure plus decisions.
+
+The Interface Registry answers "what interfaces do I need to implement?" before any code lands.
+
+### How does /decompose compose with /temperance and /pattern-review?
+
+`/temperance` fires BEFORE `/decompose`. Temperance asks "should we build this?" Decompose asks "how should we structure it?" — different questions, different answers.
+
+`/pattern-review` fires DURING or AFTER build. Decompose selects patterns before code lands; pattern-review validates they were applied per the decomposition.
+
+## Details below the fold
+
+### Position in the chain
+
+```
+/interaction-design (sequence diagrams, state diagrams)
+        ↓
+/decompose (responsibility audit → pattern map)
+        ↓
+Builder implements against the decomposition
+        ↓
+/pattern-review (validates patterns during/after build)
+```
+
+### Phase 1 — Responsibility Matrix (GRASP)
+
+For each system event in the sequence diagrams, assign responsibility using Larman's GRASP principles:
+
+| Principle | Question it answers | Stack translation |
+|---|---|---|
+| **Information Expert** | Who has the data needed to do this? | Prisma model → repository / service. React component with local state → handler stays in component. |
+| **Creator** | Who should create this object? | API route creates via Prisma. Factory if creation varies by type. |
+| **Controller** | Entry point for this system event? | API route (server boundary) or server action. One controller per use case, not per entity. |
+| **Low Coupling** | Does A need to know B's internals? | If yes → introduce indirection (service layer, repository, adapter). |
+| **High Cohesion** | Is this module doing too many unrelated things? | If a route handles validation + business logic + DB + email → extract. |
+| **Pure Fabrication** | No natural home for this logic? | `lib/services/ScoringService.ts`, `lib/repositories/DealRepository.ts`. |
+| **Indirection** | Need to decouple two things? | Middleware, event bus, service layer between route and DB. |
+| **Protected Variations** | What changes? What stays stable? | Interface / adapter around unstable external APIs. Strategy for varying business rules. |
+
+Output — Responsibility Matrix:
+
+```markdown
+| System Event | Controller | Expert | Fabrications | Interfaces | GRASP Justification |
+|---|---|---|---|---|---|
+| User submits deal | `POST /api/deals` | `Deal` (Prisma) | `DealRepository` | `IDealRepository` | Expert: Deal model owns fields. Pure Fabrication: repository isolates query logic from route. |
+| Score recalculates | Server action | `ScoreConfig`, `Deal` | `ScoringService` | `IScoringStrategy` | Expert: ScoreConfig owns dimensions. Protected Variation: scoring rules vary. |
+```
+
+Rules:
+
+- Every row cites at least one GRASP principle.
+- Interfaces column is mandatory. Every Indirection / Protected Variation names its interface.
+- If you cannot name the Expert, the entity model is incomplete — go back to `/ia-model`.
+- If a Controller handles 3+ responsibilities, split it.
+- Names in the matrix match the ubiquitous language of the domain (Evans DDD) — not database schema.
+- Each fabrication is a deep module (Ousterhout) — small interface, complex implementation hidden. A Service passing calls through to a Repository is two shallow modules pretending to be one deep.
+
+### Phase 2 — Coupling, Variation, NFR Audit
+
+Review the Responsibility Matrix. For each row, run four checks:
+
+1. **Coupling check.** Does the Controller reach into the Expert's internals? If yes → introduce a Repository or Service.
+2. **Variation check.** Does behavior vary by type / configuration / context? If yes → Protected Variation.
+3. **Stability check.** Does this touch an external API that could change? If yes → Adapter.
+4. **NFR check** (the -ilities):
+
+| -ility | Question | What it catches |
+|---|---|---|
+| **Observability** | Who traces this? Records latency / cost / input / output? | Missing Decorator — the Langfuse-inside-HaikuImputer mistake. Tracing bolted inside implementation instead of wrapping interface. |
+| **Testability** | Can I test this in isolation? What needs mocking? | Concrete dependencies without interfaces. Cannot swap implementation in a test. |
+| **Extensibility** | What's the next provider / strategy / channel? | Missing interface for Protected Variation. "Add SMS" means editing the email service. |
+| **Security** | Who authenticates / authorizes? Where is tenant context resolved? | Auth wired inside business logic instead of at the boundary. |
+| **Cacheability** | What's read-heavy and stable enough to cache? Where does invalidation live? | Cache logic mixed into business logic instead of isolated as Proxy / Decorator. |
+
+Rule: if an -ility concern applies to a responsibility, it MUST appear as its own row in Friction Points with a named interface or wrapper. "Add observability later" is the same failure as "add tests later."
+
+Output — Friction Points:
+
+```markdown
+| Location | Type | Risk | Resolution |
+|---|---|---|---|
+| `POST /api/deals` → Prisma query | Coupling | Route knows schema shape | Extract `DealRepository` |
+| Scoring dimensions | Variation | Rules vary per deal type | Strategy — `IScoringStrategy` |
+| Association imputation | Observability | Tracing lives inside HaikuImputer; swapping to Gemma loses traces | Decorator — `ObservedImputer(IAssociationImputer)` traces via Langfuse |
+| Association imputation | Testability | Cannot test imputation without LLM call | Interface — `IAssociationImputer` enables stub / mock |
+```
+
+### Phase 3 — Pattern Map
+
+Select concrete patterns from the vocabulary:
+
+**Functional patterns:**
+
+| Friction | Pattern sources |
+|---|---|
+| Variation by type | GoF: Strategy, State. React: polymorphic components, render props. |
+| Complex creation | GoF: Factory Method, Abstract Factory. Prisma: nested create, transaction. |
+| Unstable external API | GoF: Adapter. Next.js: route handler wrapping SDK. |
+| Complex orchestration | GoF: Facade. Next.js: server action composing services. |
+| Event propagation | GoF: Observer. Prisma: middleware hooks. Next.js: revalidation. |
+| Data access isolation | Fowler: Repository, Unit of Work. |
+| State complexity | GoF: State. React: useReducer, state machines (XState). |
+| Caching / memoization | React: useMemo, React.cache. Next.js: ISR, unstable_cache. |
+
+**Cross-cutting patterns (from NFR check):**
+
+| -ility | Pattern sources | Structural principle |
+|---|---|---|
+| Observability | GoF: Decorator, Observer. Langfuse: trace wrapper. OpenTelemetry: span instrumentation. | Decorator wraps the interface, not the implementation. Tracing MUST survive provider swap. |
+| Testability | Interface extraction → stub / mock. Fowler: Test Double. | Cannot swap implementation in a test = coupled to concrete class. |
+| Extensibility | GoF: Strategy, Abstract Factory. Plugin registries. | New provider = new class implementing existing interface. Zero edits to existing code. |
+| Security | Middleware chain. Next.js: middleware.ts. Fowler: Gateway. | Auth resolved at boundary, passed as context. Business logic never checks auth. |
+| Cacheability | GoF: Proxy. React: React.cache. Next.js: ISR. Redis wrapper. | Cache as Proxy / Decorator wrapping interface. Invalidation strategy declared, not bolted on. |
+
+Per @luminary gang-of-four: program to an interface, not an implementation; favor object composition over class inheritance. Cross-cutting concerns wrap interfaces via Decorator — they never live inside the concrete implementation.
+
+### Luminary lens on Phase 3
+
+Read the iteration goal's `primary_luminaries` field (list form) — treat scalar `primary_luminary` as single-element list for backward compat. For each entry, read `.claude/luminaries/[slug].md`.
+
+Multi-luminary handling: each luminary should have a `role` annotation. Phase 3 Pattern Map cites which luminary drove each pattern choice — no "applied the primary" language when 2+ luminaries active. Add an Attribution column to the pattern table.
+
+Stub-depth luminary — emit BLOCKED (per `.claude/rules/blocked-items.md`) and either upgrade the luminary or explicitly defer.
+
+Common preferences:
+
+| Primary luminary | Pattern preferences |
+|---|---|
+| Sophia Prater | Componentized content, progressive disclosure, entity-derived nav; Strategy over Factory when behavior varies by entity type |
+| Don Norman | Explicit affordances, feedback wrappers, constraint-first validation; Decorator for feedback consistency |
+| Edward Tufte | Small-multiples for comparison, sparklines in tables; data-dense patterns over card-based |
+| Dieter Rams / Jony Ive | Minimal API surface on components, removal over addition; Facade to hide complexity |
+| Alan Cooper | Role-based UI variants, primary-persona-optimized Controllers; Strategy per persona-role |
+| @luminary alistair-cockburn | Walking Skeleton as first PR; Hexagonal Architecture with Ports & Adapters — business logic at center, adapters at outside |
+
+### Final Output — Decomposition Summary
+
+Combine all three phases into `docs/decompositions/[feature-name].md`:
+
+```markdown
+# Decomposition: [Feature Name]
+
+**Source**: [sequence diagram reference or entry-point state]
+**Date**: YYYY-MM-DD
+
+## Responsibility Matrix
+[Phase 1 table with Interfaces column]
+
+## Friction Points
+### Functional
+[Phase 2 coupling / variation / stability rows]
+### Non-Functional (-ilities)
+[Phase 2 NFR rows]
+
+## Pattern Map
+### Functional patterns
+[Phase 3 functional table]
+### Cross-cutting patterns
+[Phase 3 cross-cutting table]
+
+## Interface Registry
+| Interface | Purpose | Implementations (known) |
+|---|---|---|
+| `IAssociationImputer` | Abstract LLM provider | `HaikuImputer`, `GemmaImputer` (future) |
+
+## File Structure (proposed)
+src/
+  app/api/[route]/    ← Controllers
+  app/actions/        ← Facades (server actions)
+lib/
+  services/           ← Pure Fabrications
+  repositories/       ← Data access (Fowler Repository)
+  adapters/           ← External API wrappers
+  decorators/         ← Cross-cutting: Observed*, Cached*, Logged*
+  [domain]/
+    types.ts          ← Interface definitions (I* contracts)
+    strategies/       ← Strategy implementations
+
+## Decisions
+- [Why X is a service, not inline in the route]
+- [Why observability is a Decorator, not inline tracing]
+- [Why caching is a Proxy, not inline Redis calls]
+```
+
+### Anti-patterns
+
+- Decomposing trivial work
+- Forcing patterns when the friction table is empty (say "no friction — build directly")
+- Skipping Phase 1 and jumping to "use a Factory"
+- Decomposing without sequence diagrams (State 1) or without spec / current code (State 2)
+- Skipping the NFR check — cross-cutting concerns identified later become bolt-on hacks
+- Naming principles without interfaces — the interface IS the artifact
+- Cross-cutting logic inside implementations — tracing inside HaikuImputer, caching inside DealRepository, auth inside a route handler are all the same mistake
+
+### Composes with
+
+| Skill | Relationship |
+|---|---|
+| `/temperance` | Fires BEFORE. Should we build this at all? |
+| `/interaction-design` | Produces sequence diagrams `/decompose` consumes |
+| `/ia-model` | Produces entity model that informs Information Expert assignments |
+| `/pattern-review` | Validates patterns DURING or AFTER build. Decompose selects BEFORE. |
+| `/spec` | May contain sequence diagrams inline. Decompose reads from spec or standalone artifacts. |
+| `/use-case` | Fully-dressed cases feed Phase 1 in parallel with sequence diagrams |
+
+### Refs
+
+- Craig Larman, *Applying UML and Patterns* — GRASP patterns
+- @luminary gang-of-four — *Design Patterns* — 23 pattern vocabulary
+- @luminary martin-fowler — *Patterns of Enterprise Application Architecture* + *Refactoring* catalog
+- @luminary eric-evans — *Domain-Driven Design* — Ubiquitous Language + Bounded Contexts + Aggregates
+- @luminary alistair-cockburn — *Writing Effective Use Cases* + Hexagonal Architecture (Ports & Adapters)
+- @luminary robert-c-martin — *Clean Architecture* — SOLID + Dependency Rule
+- @luminary john-ousterhout — *A Philosophy of Software Design* — deep modules + comments-as-design
+- `.claude/rules/oo-ad-entry-point.md` — entry-point rule requiring `/decompose` evidence
+- `.claude/rules/adr-discipline.md` — ADR-consult before scope confirmation
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.