@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/.claude/rules/we-dont-break-adopters.md

@@ -0,0 +1,126 @@
+---
+tier: lite
+description: "Bassclef adopts Linus Torvalds's rule: we do not break adopters."
+---
+
+# We don't break adopters
+
+Bassclef adopts Linus Torvalds's rule: **we do not break adopters**. Every change to a surface adopters see must keep their existing setup working. When a change would break an adopter, bassclef pays the migration cost. Adopters never pay for bassclef's internal cleanup.
+
+**Adopter-count threshold (per ADR-041, added 2026-07-17):** the mechanism for keeping adopters working scales with adopter count.
+
+- **N ≤ 24 active adopters** (current: 5) — substrate renames ship immediate. Old vocabulary in prior artifacts (session logs, past goal docs, chronicles, closed PRs) reads through `standards/vocabulary-migration.json`. No compat-shim SKILL stubs per rename. No 90-day grace window on prose. The operator Slacks each adopter about renames as they ship.
+- **N ≥ 25 active adopters** — the full compat-shim discipline returns: rename ships with compat alias, fixture, migration manifest, 90-day grace window on prose, adopter changelog entry.
+
+Adopter count read from `standards/bassclef-source-consumers.json` and `.claude/rules/sibling-smoke-after-substrate-change.md` (sibling-smoke rule ships at standard tier). A backlog ticket tracks the counter mechanism (see ADR-041 Decision 4).
+
+**Behavior changes stay under full discipline regardless of adopter count.** API contract changes, schema shape changes, and hook filename changes still ship with compat shims — the translation table cannot help there. Only vocabulary renames (word-for-word substitution) qualify for the translation-table path.
+
+This rule is the methodology layer. The mechanical layer (CI test that clones a representative adopter and verifies their sync hook against the proposed bassclef HEAD; pre-rename validation; the bassclef-source-redirect registry) is Phase 2 work tracked under bassclef#1360.
+
+## When this rule fires
+
+Any change to bassclef-upstream or public bassclef that touches an **adopter-observable surface**:
+
+**Filesystem surfaces:**
+- Filesystem paths under `~/src/sunj-labs/` that adopter repos symlink into (`canonical/`, `bassclef/`, etc.)
+- Symlink targets inside `<adopter>/.claude/hooks/` or `<adopter>/.claude/skills/`
+- Filenames referenced by adopter `.claude/settings.json` (e.g., the bassclef-sync filename (renamed from a former canonical name per ADR-031))
+- Schema shape of state-spine files (entity types, required frontmatter fields, marker formats)
+- `settings.json` `additionalDirectories` path conventions
+- Repo names and sync URLs in `.bassclef-source.json`
+- Hook filenames, agent names, skill directory names that adopter automation invokes
+
+**gh API surfaces (per bassclef-upstream#404):**
+- Label names — rename affects `gh issue list --label X`, `gh pr list --label X`, saved filter URLs, and webhook payloads
+- Label descriptions — visible on hover in GitHub UI + in `gh label list` output; carry brand vocabulary adopters quote
+- Repo description — visible on repo home page + in `gh repo view --json description` + at discovery surfaces
+- Repo topics — discovery + search surface
+- Milestone titles + descriptions — adopters filter by these
+- Project descriptions (gh projects v2) — when used for cross-repo coordination
+
+Use `scripts/migrate-gh-surfaces.sh` (sister to `migrate-adopter-references.sh`) to sweep gh API surfaces during a rename event. Defaults to `--dry-run`; operator runs `--apply` after confirming the proposed diff.
+
+Does NOT fire on:
+- Internal bassclef refactors that don't change any of the above (private/methodology docs, operator-private content)
+- Strict additions (new skills/rules/hooks that don't replace existing surfaces)
+- gh API surfaces internal to a repo (issue body content, PR review comments, individual issue numbers — those have their own discipline)
+
+## What the rule requires
+
+When a substrate change touches an adopter-observable surface:
+
+1. **Compatibility shim** — the old surface must keep working. Filesystem rename → leave a symlink at the old path. Filename rename → keep an alias or a one-line forwarding stub at the old name. Schema field rename → continue accepting both during the deprecation window.
+2. **Migration manifest** — file at `docs/operator-private/forward-port-registry/migrations/<date>-<change-slug>.md` documenting: what changed, what the shim is, when adopters can safely remove it, the path forward.
+3. **Adopter changelog entry** — when /release ships the change to public bassclef, the PR body's Summary section names the rename + the shim + when the shim retires.
+4. **Deprecation period** — minimum one /release cycle between "shim in place + old surface deprecated" and "shim removable / breaking change ships." Documented explicitly per change.
+5. **Override path** — if a breaking change is genuinely unavoidable, file an ADR explaining why, AND add a `**BREAKING:**` section to the next /release's PR body, AND set the deprecation period to ≥3 release cycles for any high-blast-radius surface.
+
+## Anti-patterns
+
+These shapes violate the rule:
+
+- **Silent rename** — old name removed, no shim, adopters discover when they `git pull` and something disappears. (Exactly what tonight's `mv canonical bassclef` did before the rescue symlink.)
+- **"It works on my machine" testing** — substrate-renames tested only against the operator's own setup, not against adopter sync paths.
+- **Breaking change disguised as feature work** — a feat: commit that happens to rename a public schema field; adopters' parsers break silently.
+- **One-shot fallback** — the existing `bassclef-sync.sh` line `if [ -d $CWD/../bassclef ]; then ... else $CWD/../canonical` is a one-shot fallback, NOT a compat shim. It papers over the rename for new clones; it doesn't help adopters who already have stale symlinks.
+
+INSTEAD of any of those: leave the old surface in place as a redirect/symlink/alias; deprecate it explicitly with a date; ship the migration manifest; surface the change in the adopter changelog.
+
+## Why this rule exists
+
+2026-06-21 evening. Operator renamed `~/src/sunj-labs/canonical` → `~/src/sunj-labs/bassclef` on their machine. Every adopter repo on the machine broke. The list: poa, twoDo, family-recipe-2, eugene-supplements, quorum. Each had 30+ broken symlinks pointing through `../canonical/.claude/hooks/<name>.sh`. poa's `/longrun` start emitted 6+ PreToolUse hook errors per Bash tool call. Non-blocking but noisy. Real failures got masked.
+
+The rename was reasonable (the GitHub repo had been renamed canonical → bassclef weeks earlier; the local folder was finally catching up). The lack of compatibility-shim discipline made it cascade.
+
+This is Hyrum's Law in action. Every adopter depended on the observable path `~/src/sunj-labs/canonical/`. Bassclef never named that path in any contract. With enough adopters, every observable behavior becomes essential.
+
+Linus's 30-year rule applies directly. The Linux kernel does not break userspace. Even when userspace depends on something the kernel never promised. The kernel team pays the cost. Bassclef takes the same stance.
+
+## How this composes with existing substrate
+
+- `architecture/decisions/ADR-024-forward-port-registry.md` — Strategy A-clean (replace adopter-facing names, no grace period) was the prior default. **This rule supersedes that for adopter-observable surfaces** — compat shims and grace periods are now required. Operator-internal rewrites (chronicles, ADRs, iteration-bets) keep Strategy A-clean.
+- `architecture/decisions/ADR-019-reference-vs-vendor-distribution.md` — reference-binding adopters (HTTP API, agent-read URLs) need URL-stability; vendor-binding adopters need filesystem-path-stability. This rule covers both.
+- `architecture/decisions/ADR-029-release-pipeline.md` — every /release that touches an adopter-observable surface MUST include a migration-manifest reference in the PR body.
+- `architecture/decisions/ADR-030-adopter-inbox-flow.md` — adopters file issues when something silently breaks; this rule makes those issues a defect signal, not an acceptable channel.
+- `architecture/decisions/ADR-031-non-breaking-changes-adopter-discipline.md` — the architectural decision that adopts this rule as Tier 1.
+- `architecture/dual-repo-flow.md` — contains the "Non-breaking changes to adopters" section that this rule operationalizes.
+
+## Override path
+
+`SKIP_ADOPTER_COMPAT=1 <command>` — for genuinely-exceptional cases. Logged via trace-helper. Use only when:
+
+- The breaking change ships under an explicit ADR with `**BREAKING:**` PR body section
+- Deprecation period ≥3 /release cycles has elapsed since the deprecation announcement
+- A migration manifest exists with documented automated remediation
+
+INSTEAD of overriding for routine work: write the compat shim. The cost is small (one symlink, one alias, one forwarding stub); the adopter trust compounds across every future release.
+
+## Composes with
+
+- `@luminary linus-torvalds` — anchor for the discipline (we don't break userspace)
+- `@luminary hyrum-wright` — theoretical foundation (with enough users, all observable behaviors are depended on)
+- `@luminary michael-nygard` — circuit-breaker / stability-pattern shape
+- `@luminary vaughn-vernon` — anticorruption layer between bassclef-internal renames and adopter-observable state
+- `@luminary frederick-brooks` — conceptual integrity vs migration cost trade-off
+- `.claude/rules/destructive-operations.md` — sister discipline at the local-action layer
+- `.claude/rules/sdlc-gates.md` — temperance gate must fire before any rename touching adopter-observable surfaces
+
+## Refs
+
+- bassclef#1360 — substrate-rename adopter-migration discipline gap (mechanical layer Phase 2)
+- poa#1251 — poa-specific migration sister ticket
+- ADR-031 — non-breaking-change adopter discipline decision
+- ADR-024 — forward-port-registry (this rule extends/supersedes for adopter-observable surfaces)
+- ADR-019 — reference vs vendor distribution
+- 2026-06-21 chronicle — the rename + cascade + rescue
+
+## Retirement condition
+
+This rule retires only if bassclef stops having adopters. The mechanical-layer Phase 2 work may reduce the methodology cost but does not retire the discipline. Every release continues to carry adopter compatibility as Tier 1.
+
+## When the discipline costs more than the rename benefit
+
+Sometimes the migration cost will exceed the rename benefit. That's a signal NOT to do the rename. Adopter compatibility is the constraint that disciplines bassclef-internal refactoring — if a rename can't be made non-breaking, the rename probably isn't worth doing. This is Brooks's conceptual-integrity discipline as a budget, not as a license.
+
+Closes the methodology gap surfaced 2026-06-21. Phase 2 mechanical layer tracked at bassclef#1360.

package/substrate/.claude/rules/wu-sequencing-compounds.md

@@ -0,0 +1,145 @@
+---
+tier: lite
+description: WUs within a chosen goal shape ship as compounding builds.
+---
+
+# WU Sequencing — Each WU Compounds With the Next
+
+WUs within a chosen goal shape ship as compounding builds. Each WU declares what it produces that the next WU consumes. The trap: independent step enumeration where each step does its own thing. No WU's output feeds another. The value that compounded at shape-pick time disappears once the shape is picked.
+
+The rule mechanizes the discipline filed at bassclef#1348. The operator caught the gap on 2026-06-20h prep. My first WU proposal sequenced fixes (recursive walk + triage + workflow stand-up) as parallel-safe atomic items. It should have been a chain where each output flowed into the next.
+
+Sister rules cover the INTER-shape layer. bassclef#1299 covers Step 1.5 (the compounding column). bassclef#1302 covers Step 1.6 (the adopter-benefit column). Those two help the operator pick between shapes. This rule disciplines step enumeration WITHIN a chosen shape.
+
+## When this rule fires
+
+- `/longrun prep` Step 1.7 (added in this rule's PR) — when step enumeration goes into the prep output proposal, the table includes a produces/consumes column
+- Bet doc authoring — when the `## Steps` section is written, the table uses the produces/consumes shape
+- `/sprint` next-work proposals — same shape when proposing a multi-step sequence (sister surface; same wordlist)
+- `/build` skill construction-time sequencing — out of scope for V1; separate ticket if surfaced
+
+## Format contract
+
+Every goal doc's `## Steps` section uses one of two table shapes.
+
+### Shape A — three-column (canonical)
+
+```markdown
+| WU | Produces | Consumes (from prior WU) |
+|---|---|---|
+| **0** prep | goal doc + stack manifest + temperance marker | — (session-start) |
+| **1** <ticket> | <what ships> | <what it reads from prior WU> |
+| **2** <ticket> | <what ships> | <what it reads from WU-1> |
+| ... |
+```
+
+### Shape B — six-column (extended per bassclef-upstream#688)
+
+```markdown
+| WU | Problem + value prop | Produces | Consumes (from prior WU) | How this step builds on the prior | Risk |
+|---|---|---|---|---|---|
+| **0** prep | <problem sentence> + <value prop sentence> | goal doc + markers | — (session-start) | — (baseline) | low |
+| **1** <ticket> | <problem sentence> + <value prop sentence> | <what ships> | <what reads from prior WU> | <how it builds> | <low/med/high> |
+```
+
+Shape B mirrors the `/longrun` prep proposal rendering. Prep proposals MUST render six-column so the operator sees per-step sequencing at pick-time. Bet doc `## Steps` sections use EITHER shape; six-column is preferred when the goal doc reuses the prep proposal table verbatim.
+
+Column semantics for Shape B:
+
+- **Problem + value prop** — one cell combining `/state-a-problem brief` output AND `/value-prop flash` output. Do NOT split the two outputs into separate cells. Operator preference confirmed 2026-07-09 (bassclef-upstream#688).
+- **How this step builds on the prior** — one line explaining the sequencing. "Baseline" for WU-0. Parallel-safe WUs state "parallel-safe with WU-N".
+- **Risk** — low / medium / high, matching the step's Step 1.5 risk-class value.
+
+Format rules (both shapes):
+
+- Shape A header exactly: `| WU | Produces | Consumes (from prior WU) |` — greppable by `bet-doc-gate.sh` V2 hook (3-column path)
+- Shape B header exactly: `| WU | Problem + value prop | Produces | Consumes (from prior WU) | How this step builds on the prior | Risk |` — greppable by `bet-doc-gate.sh` V2 hook (6-column path)
+- Each WU's Produces is a concrete artifact (file, decision, label set, marker, output)
+- Each WU's Consumes names what the prior WU produced — by reference, not duplicated description
+- WU-0 prep consumes "session-start" (no prior WU)
+- Final WU (closeout) produces the chronicle + whereami flip; consumes the union of all prior WU outputs
+- When a WU is genuinely parallel-safe (no consumer), state "parallel-safe (no consumer)" or "parallel-safe with WU-N" in the Consumes cell — explicit declaration, not silent
+
+## What this rule requires
+
+The agent runs this check before committing the goal doc OR before posting the `/longrun prep` confirmation surface:
+
+1. Each WU declared in the proposed shape has a Produces cell
+2. Each WU after WU-0 has a Consumes cell that names what the prior WU produced
+3. When a WU's Produces doesn't feed any later WU, the rule fires WARN. Either the step is misplaced (should be its own goal) OR the sequencing is correct but the next-WU consumption is implicit and needs stating.
+4. The goal doc body cites this rule's slug in the `references:` block when sequencing is non-obvious
+
+## Anti-patterns
+
+The following shapes fail this rule:
+
+- **Bare WU list** — `WU-1: fix X. WU-2: fix Y. WU-3: triage Z.` Independent items; no produces/consumes contract
+- **Sequence-implied-by-ordering** — WUs listed in order but the goal doc body doesn't say WHY this order. Order alone is not compounding
+- **All WUs are independent** — every step is parallel-safe. That signal calls for a question: is this one goal or several smaller bets?
+
+The agent picks one path when the rule fires WARN:
+
+- Restructures the step sequence so each step's output is input to the next (preferred)
+- Splits the goal — if WUs are genuinely parallel-safe with no compounding, they belong in separate goals
+- Explicitly justifies why a parallel-safe WU rides with sequenced WUs (e.g., shared review window, operator preference)
+
+## Eat-own-dogfood
+
+The goal that ships this rule (2026-06-20h-recursive-walk-and-triage-marathon) already uses the produces/consumes table in its own `## Steps` section. The goal doc author's chair is the first place this rule fires.
+
+## Mechanical layer
+
+V1 ships this rule + the SKILL.md Step 1.7 procedure update.
+
+**V2 (shipped 2026-06-23 per bassclef-upstream#21):** `.claude/hooks/bet-doc-gate.sh` PreToolUse Edit|Write|MultiEdit on `docs/iteration-bets/*.md` performs the substantive Consumes-cell check. Composed with sister #300 thread-walk check in the same hook file. Behaviors:
+
+- **PASS** when Consumes cell contains a concrete artifact reference (backtick-quoted ref, slash-prefixed path, `.sh|.md|.json|.yml` extension) OR explicit literal `"parallel-safe (no consumer)"` OR `"session-start"` (prep) OR `"union of"` (closeout).
+- **WARN** (exit 0 with stderr) when Consumes cell starts with `WU-N` or `WU-N's` followed by vague prose without any concrete artifact reference. Advisory in V2; flips to BLOCK in V3 if observable drift persists.
+- **Silent** on non-matching paths, non-Edit tool calls, or goal docs without a steps table.
+
+Overrides (logged via trace-helper):
+- `SKIP_PRODUCES_CONSUMES_CHECK=1` — bypass P/C only
+- `SKIP_BET_DOC_GATE=1` — bypass both P/C and thread-walk
+
+Per `feedback_hooks_beat_methodology_for_substrate_quality` memory: V2 hook ships ALONGSIDE the methodology — both required.
+
+## Override path
+
+`SKIP_WU_SEQUENCING_COMPOUNDS=1 <command>` (when V2 hook ships) — logged via trace-helper. Use rarely:
+
+- Single-WU bets — no sequencing applies; the column is trivially empty
+- Genuinely parallel atomic WUs that share a review window (declare in goal doc body)
+- Migration scripts authoring many goal docs at once
+
+INSTEAD of overriding for routine work: write the produces/consumes cells. The discipline costs seconds at write-time and compounds across every future thread walking tonight's chronicle for reference.
+
+## Composes with
+
+- `.claude/rules/arc-level-orientation-before-leaf.md` — sister at orientation surface (sister bassclef#1347 fixes one-level walk)
+- `.claude/rules/plan-enumeration-needs-value-props.md` — sister at choice-presentation surface
+- `.claude/rules/blocked-items.md` — BLOCK protocol the V2 hook fires
+- `.claude/skills/longrun/SKILL.md` Step 1.7 — primary surface this rule extends
+- `.claude/skills/sprint/SKILL.md` — sister surface (next-work proposals)
+- standards/branch-stacking.md — stack manifest already declares dependencies between WUs; this rule extends to the goal doc body
+
+## Distinct from
+
+- bassclef#1299 (Step 1.5 compounding-sequence) — that's INTER-shape (helps operator pick between shapes); this is INTRA-shape (governs step enumeration within a chosen shape)
+- bassclef#1302 (Step 1.6 adopter-benefit) — that's INTER-shape adopter mechanism; this is intra-shape WU dependency
+- standards/branch-stacking.md — that's about branches + their dependencies (deployment shape); this is about WUs + their produces/consumes (build shape)
+
+## Refs
+
+- bassclef#1348 — this rule's filing ticket
+- bassclef#1299 — sister Step 1.5 INTER-shape compounding column
+- bassclef#1302 — sister Step 1.6 INTER-shape adopter-benefit column
+- bassclef#1347 — sister substrate-defect at orientation surface (both shipped 2026-06-20h)
+- Memory `feedback_hooks_beat_methodology_for_substrate_quality` — pattern pushing V2 mechanical extension
+- 2026-06-20h /longrun prep — the session that surfaced this gap; operator's framing: "where is the sequencing discipline ticket — that you propose /longrun and its components as sequenced builds that compound"
+- @luminary kent-beck — test-list as planning artifact (TDD By Example chs 1-3); analogous shape for step enumeration as compounding-build artifact
+
+## Retirement condition
+
+This rule retires only if WU as a bet-shaping primitive retires. The discipline of declared produces/consumes survives any rename or restructure of the step vocabulary.
+
+Closes bassclef#1348 (V1 methodology + procedure layer; V2 mechanical layer follow-on).

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

@@ -1,7 +1,7 @@
 ---
 tier: lite
 name: build
-description: "Take a buildable plan and ship it. Reads the spec from /launch, dispatches a builder per user story, runs /verify, opens PRs, gates prod deploy on a reviewer. Hard floor: refuses auth, schema, security, tenant, or prod-infra changes. --explain flag narrates the plan first."
+description: "Take a buildable plan and ship it. Reads a spec from /launch. Dispatches a builder per user story. Runs /verify. Opens PRs. Gates prod deploy on a human. Refuses auth, schema, security, and tenant work. --explain narrates first."
 problem: "A buildable plan sits on disk. Nothing ships until someone writes code and PRs and gates prod."
 value: "Reads the plan and ships it. Runs the whole cycle so you can watch instead of type."
 inputs: [A goal slug pointing to a spec on disk]

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

@@ -1,7 +1,7 @@
 ---
 tier: lite
 name: decompose
-description: Pre-build responsibility audit — reads sequence diagrams, assigns responsibilities using GRASP with mandatory interface identification, audits functional and non-functional friction, selects patterns from GoF / Fowler / stack idioms. Bridges design and build.
+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]

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

@@ -1,7 +1,7 @@
 ---
 tier: lite
 name: diagnose
-description: Diagnose a defect before fixing — reproduce the failure (Step 0) + Is/Is Not + Five Whys + Hypothesis. Run before writing any fix code; lazy diagnosis ships brittle fixes.
+description: "Diagnose a defect before fixing. Reproduce the failure first (Step 0), then Is/Is Not, then Five Whys, then a Hypothesis. Run before writing any fix code. Lazy diagnosis ships brittle fixes."
 problem: "Bugs get fixed on guesses. The wrong cause gets patched. The class comes back a week later."
 value: "A short trace from failure to root cause. You fix the class once instead of the instance three times."
 inputs: [A failing test or error log, A bug ticket or screenshot]