@thebassclef/lite 0.1.0 → 0.1.3

package/substrate/.claude/rules/pr-title-shape.md

@@ -0,0 +1,161 @@
+---
+tier: lite
+description: Sister rule to pr-body-shape.md. Encodes authoring-time discipline for the PR title surface. Titles show in gh pr list, GitHub search, and mobile views — they are the…
+---
+
+# PR Title Shape Contract
+
+Sister rule to `pr-body-shape.md`. Encodes authoring-time discipline for the PR title surface. Titles show in `gh pr list`, GitHub search, and mobile views — they are the highest-visibility surface in the PR-authoring stack.
+
+## Why this rule exists
+
+The `pre-gh-pr-title-scrub.sh` hook catches BLOCK terms in titles per `standards/bassclef-internal-jargon.md`. It does not catch:
+
+- Length over 72 chars (mobile views truncate)
+- Multiple concepts stacked with `+` or `—`
+- `(WU-N of bet YYYY-MM-DDx)` suffix bloat
+- Process narration (`/longrun pre-flight`, `/session-end for X`)
+- Bassclef-internal compound verbs/nouns (`Pattern-B mv`, `review-file pass`, `registry shape`)
+- Ticket-ref bloat with verbose body
+- Conventional-commit prefix mismatch (`chore` for substantive features)
+- Uncommon hyphenated prose compounds in titles
+- Repeating literal filenames across title + body
+- Inconsistent `skillname` vs `/skillname` references
+
+This rule is the methodology that covers the gap. The wordlist hook is the FLOOR; this catalog is the BAR. Apply the catalog at authoring time rather than relying on the hook to catch what slipped past you.
+
+The catalog was drafted from PR-authoring failures observed 2026-06-19. See bassclef#1241 for the source incidents.
+
+## When this rule fires
+
+Any time a PR title is being written via:
+
+- `gh pr create --title ...`
+- `gh pr edit <N> --title ...`
+- Direct REST `curl POST /repos/<o>/<r>/pulls` with a `title` field
+- GitHub web UI (manual operator authoring)
+
+## Format contract
+
+Every PR title is:
+
+- **≤72 characters** (mobile views truncate; squash-merge commit messages prefer short)
+- **One conventional-commit prefix** per `commit-conventions.md` — `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `ci:`, `chore:`, `security:`
+- **One primary change** — sub-concepts go in the body Summary, not the title
+- **Bet/WU reference** as `(WU-N)` only when present; bet ref belongs in body Refs
+
+Recommended shape: `<type>(<scope>): <verb> <object> (<optional WU-N>)`
+
+Examples (all ≤72 chars):
+
+- `feat(#1241): document the pseudonym registry file (WU-4)`
+- `fix(bassclef#1125): jq+set -e fail-soft fix in 2 hooks (WU-8)`
+- `chore: update whereami; close bet 2026-06-19b (WU-5)`
+
+## DON'T / INSTEAD catalog
+
+### Length and structure
+
+| Don't | INSTEAD |
+|---|---|
+| Exceed 72 chars (mobile truncates; squash commit messages prefer short) | Keep under 72; cut to one concept |
+| Stack multiple concepts with `+` or `—` (`carry-forward + housekeeping + roadmap-reconcile`) | Name the ONE primary change; sub-concepts go in body Summary |
+| `(WU-N of bet YYYY-MM-DDx)` suffix bloat | Either drop entirely or `(WU-N)` alone — bet ref belongs in body Refs |
+| Ticket-ref bloat with verbose body (`chore(bassclef#1031): document operator-private-pseudonyms.json registry shape`) | Either prefix `(#NNNN)` OR a full descriptive body — not both |
+
+### Conventional-commit prefix
+
+| Don't | INSTEAD |
+|---|---|
+| Conventional-commit prefix mismatch (`chore` for substantive features) | Match prefix to actual change type per `commit-conventions.md` |
+| Invent bassclef-internal prefixes (`substrate-defect:`, `bet:`, `closeout:` outside of `chore(closeout)`) | Use the 8 standard types only; substrate bugs are `fix:` |
+| Process narration as title (`/longrun pre-flight`, `/session-end for X`) | Name the artifact change (`prep goal doc`, `update whereami`) |
+
+### Plain English
+
+| Don't | INSTEAD |
+|---|---|
+| Bassclef-internal compound verbs/nouns (`Pattern-B mv`, `review-file pass`, `registry shape`) | Plain verb + object (`move`, `run`, `document the file schema`) |
+| Uncommon hyphenated prose compounds (`carry-forward`, `pre-flight` as title prose) | Plain words (`continued`, `prep`); literal filenames + CLI flags + script names preserve as code identifiers |
+| Buzz adjectives in titles (`substantive`, `comprehensive`, `robust`) | Concrete verb + concrete object |
+| Bassclef-internal verbs (`flip`, `Pattern-B'd`, `seed` as noun) | Plain verbs (`update`, `move`, `set up`) |
+
+### Cross-surface consistency
+
+| Don't | INSTEAD |
+|---|---|
+| Repeat literal filenames in both title and body Summary | Plain title; filenames in body where they're grep-anchored to the actual change |
+| Mix `skillname` and `/skillname` for the same skill across titles | Use `/skillname` consistently when referencing the skill; plain filename when referencing the file (e.g., `docs/whereami.md`) |
+
+## Worked examples
+
+### Anti-pattern — multi-concept + bet-ref bloat + bassclef-internal compound
+
+```
+chore(bet): /longrun 2026-06-19b pre-flight — carry-forward + housekeeping + roadmap-reconcile (WU-0 of bet 2026-06-19b)
+```
+
+100 chars. Three stacked concepts. Process narration. Bet ref bloat. Bassclef-internal compound `carry-forward`.
+
+### Conformant pattern
+
+```
+chore(bet): prep 2026-06-19b /longrun continued (WU-0)
+```
+
+53 chars. One primary change. Plain English. `/longrun` slashed consistently. Bet ref dropped from title (lives in body).
+
+### Anti-pattern — buzz adjective + invented compound + filename duplication
+
+```
+chore(bassclef#1031): document operator-private-pseudonyms.json registry shape (WU-4 of bet 2026-06-19b)
+```
+
+104 chars. Invented compound `registry shape`. Filename appears in title AND body Summary.
+
+### Conformant pattern
+
+```
+chore(#1031): document the pseudonym registry file (WU-4)
+```
+
+57 chars. Plain English. Filename moved to body (where the diff is grep-anchored).
+
+## Mechanical enforcement
+
+Wordlist BLOCK terms are caught by `pre-gh-pr-title-scrub.sh` at write time. This rule covers everything else as methodology. Hook extension to catch the additional catalog rows is sibling work tracked at bassclef#1241.
+
+## Override path
+
+`SKIP_PR_TITLE_SHAPE=1 <command>` — logged via trace-helper. Use rarely:
+
+- Quoting an exact phrase from a memory file or external doc that requires verbatim retention
+- One-off automated dispatch where the title is generated by a third-party tool
+
+## Composes with
+
+- `.claude/rules/pr-body-shape.md` — sister rule at the body surface
+- `.claude/rules/commit-conventions.md` — conventional-commit format
+- `.claude/rules/plain-english-discipline.md` — master plain-English rule
+- `.claude/rules/operator-facing-prose.md` — gloss + /kiss meta-discipline
+- `.claude/rules/context-engineering.md` — INSTEAD-block discipline (foundational)
+- `standards/bassclef-internal-jargon.md` — wordlist driving BLOCK substitutions
+- `.claude/hooks/pre-gh-pr-title-scrub.sh` — mechanical floor
+
+## Distinct from
+
+- `commit-conventions.md` — commit message FORMAT (type + scope + body); this rule applies to PR TITLES (which become squash-commit subjects)
+- `pr-body-shape.md` — body section structure + DON'T/INSTEAD catalog for each section
+- `pattern-annotation.md` — source code annotation; orthogonal
+
+## Refs
+
+- bassclef#1241 — `/pr-title` + `/pr-body` skill spec (this rule is the methodology side)
+- bassclef#1239 — pre-gh-*-scrub matcher extension for curl REST fallback (related substrate-defect)
+- bassclef#1178 — Problem-section shape (rule for the body opener)
+- bassclef#1217 — pre-gh-pr-title-scrub hook (the mechanical floor)
+- bassclef#915 — phrase-shaped advisory perimeter
+
+## Retirement condition
+
+If observed across 6 months with title-shape drift consistently below 10% on sampled feature-scope PRs, the rule is correctly calibrated. If drift exceeds 25%, escalate the hook to enforce the catalog rows mechanically. The catalog rows ship without an a-priori retirement condition — they encode discipline that survives any future skill or hook build.

package/substrate/.claude/rules/prototype-workflow.md

@@ -0,0 +1,65 @@
+---
+tier: lite
+description: "Design prototypes (artifacts under docs/prototypes/**) are visual statements to Reviewer (\"this is what we want built\")."
+---
+
+# Prototype Workflow — Visual Confirm Before Commit
+
+Design prototypes (artifacts under `docs/prototypes/**`) are visual
+statements to Reviewer ("this is what we want built"). They MUST NOT
+enter git history until the operator has confirmed the rendered output.
+
+## Protocol for prototype edits
+
+When modifying a file under `docs/prototypes/**/*.{html,css,tsx,jsx}`:
+
+1. **Render** — open the prototype locally (dev server, Playwright MCP, or direct file)
+2. **Screenshot** — save to `.playwright-mcp/prototype-render-<branch>.png` or equivalent
+3. **Share with operator** — show rendered output, wait for explicit confirmation
+4. **Then commit** — only after confirmation
+
+Committing first and sharing after inverts the gate: git history now
+holds unapproved state, and any revert has to serve only as a rule-
+violation record.
+
+## Distinction from production-UI visual review
+
+- **Production UI** (per usability rule #7): Reviewer diffs built surface
+  against prototype before merge
+- **Prototype edits** (this rule): agent confirms rendered prototype
+  against operator intent before commit
+
+The two gates are complementary. Production gate catches drift from
+prototype; this gate catches drift from operator intent.
+
+## When this rule does NOT fire
+
+- Non-visual edits to prototype directory (README, notes, data fixtures)
+- Branch explicitly scoped to "prototype cleanup / lint / formatting"
+  with no visual change (agent must assert no-visual-change)
+
+## Why this rule exists
+
+2026-04-13 incident: agent modified conversational Review Queue
+prototype v5, committed, pushed, reported success — all before showing
+operator the rendered output. Operator reviewed, rejected. Commit +
+revert pair now serves only to satisfy the rule that was violated.
+
+The existing `/verify` "UI component / page" gate runs `/visual-review`
+for production UI. Prototypes fell in a gap: not production (so gate
+doesn't fire) but visual artifacts whose whole purpose is operator
+review. This rule closes the gap.
+
+## Relationship to other rules
+
+- `usability.md` #7 — production UI visual review; this rule's upstream
+- `design-direction.md` — prototype approvals are load-bearing once
+  given; this rule governs HOW to get them
+- `sdlc-gates.md` — post-build gates; prototype confirmation is a
+  pre-commit gate
+
+## Enforcement
+
+Methodology-level today. Future mechanical backstop (proposed): pre-commit
+hook checks paths matching `docs/prototypes/**/*.{html,css}` and requires
+a render artifact newer than the edit plus an operator-confirmation marker.

package/substrate/.claude/rules/reserved-skill-names.md

@@ -0,0 +1,123 @@
+---
+tier: lite
+description: "Bassclef MUST NOT create a skill (.claude/skills/<name>/SKILL.md) with a name Claude Code's harness already claims."
+---
+
+# Reserved Skill Names
+
+Bassclef MUST NOT create a skill (`.claude/skills/<name>/SKILL.md`)
+with a name Claude Code's harness already claims. Collisions are
+silent and behavioral: operator types `/<name>` expecting bassclef's
+skill; harness resolves the built-in first and returns something else.
+
+The authoritative list lives in `standards/reserved-skill-names.md`.
+This file is the **rule** — semantics, enforcement, override path.
+
+## Why this rule exists
+
+2026-04-18 during fix-workflow family shaping: bet originally proposed
+`/investigate` as the postmortem composer. Check of Claude Code's `FEY`
+array revealed `investigate` is a harness built-in (remote investigation
+workflow). Naming the bassclef skill `/investigate` would have meant
+every `/investigate` invocation resolved to the harness, not bassclef —
+the skill would have been unreachable via its own name.
+
+Renamed to `/incident-report`. Filed this rule to prevent future
+collisions reaching PR stage.
+
+## When this rule fires
+
+On any commit (or PR) that stages a new `.claude/skills/<name>/SKILL.md`
+where `<name>` appears in the `standards/reserved-skill-names.md` list.
+
+Does NOT fire on:
+- Edits to existing skill files (only NEW skill directories)
+- Files outside `.claude/skills/`
+- Skills whose name includes a prefix/suffix avoiding collision
+  (e.g., `/docs-generator`, `/review-pr`)
+
+## Enforcement
+
+### Mechanical — pre-commit hook
+
+`.claude/hooks/pre-commit-gate.sh` checks staged skill directories
+against the reserved list. On collision, emits:
+
+```
+BLOCKED: reserved skill name — `<name>` collides with a Claude Code
+built-in. See standards/reserved-skill-names.md. Rename or override
+with SKIP_RESERVED_NAMES=1.
+```
+
+Blocks the commit. Per `blocked-items.md`, the block must be resolved
+(rename) or explicitly deferred (override with rationale) — silence
+is not deferral.
+
+### Methodology — agent self-check
+
+When drafting a new skill, the agent MUST:
+
+1. Read `standards/reserved-skill-names.md` before proposing a skill name
+2. If the proposed name matches, either:
+   - Pick a different name
+   - Justify the override (see Override path below)
+3. Cite the check in the PR body ("Reserved-names check: [name] — no
+   collision" or "collision — override justified by X")
+
+The "Sources read" block per `artifact-ingestion.md` covers this
+citation automatically when a new-skill PR references the standards list.
+
+## Override path
+
+Rare case — bassclef wants to deliberately shadow a harness built-in:
+
+1. Add a note to the skill's SKILL.md frontmatter:
+   `reserved_name_override: "<name> — rationale"`
+2. Commit with `SKIP_RESERVED_NAMES=1 git commit ...`
+3. Call out the override in the PR body
+
+The override exists because rules should be judgeable. But the friction
+is deliberately high — bypassing the hook requires conscious intent.
+
+## What counts as a "collision"
+
+Exact string match, case-insensitive, against the `Name` column of
+`standards/reserved-skill-names.md`. The skill directory name (not the
+slash-command alias, not the frontmatter `name:` field) is what the
+harness resolves; the directory name is what the hook checks.
+
+Prefixes and suffixes break collision:
+
+| Reserved | Bassclef skill | Collides? |
+|----------|----------------|-----------|
+| `docs` | `docs-generator` | No |
+| `docs` | `docs` | **Yes** |
+| `init` | `init-repo` | No |
+| `review` | `review` | **Yes** |
+| `review` | `pr-review` | No |
+
+## How the list gets updated
+
+Process lives in `standards/reserved-skill-names.md` ("Updating this
+list" section). Key constraint: if the list addition would collide
+with an existing bassclef skill, that skill MUST be renamed before
+the list addition merges. No silent shadow.
+
+## Relationship to other rules
+
+- `blocked-items.md` — the hook emits `BLOCKED: reserved skill name`;
+  this rule's semantics slot into the blocked-items protocol
+- `artifact-ingestion.md` — new-skill PRs read the standards list;
+  "Sources read" block cites it
+- `commit-conventions.md` — override commits include `SKIP_RESERVED_NAMES=1`;
+  rationale in body
+- `sdlc-gates.md` — collision check fires at pre-commit, before
+  bassclef-evolution check
+
+## Retirement condition
+
+If Claude Code ships a machine-readable API for the built-in registry
+(e.g., `claude --list-builtins --json`), this rule's mechanical
+enforcement can migrate to a dynamic check. The methodology-level
+rule (agent self-check) stays regardless — it's the first line of
+defense.

package/substrate/.claude/rules/schema-management.md

@@ -0,0 +1,49 @@
+---
+tier: lite
+globs: ["prisma/**", "**/schema.prisma", "**/migration*", "alembic/**", "db/migrate/**", "migrations/**", "**/migrations/**"]
+description: Schema management — never apply schema changes without a migration; loads per-ORM sibling
+---
+
+# Schema Management
+
+Universal principle: **never apply schema changes without a migration file**. Schema drift between local and prod is a load-bearing failure mode for every ORM. When local is reset (rebuild, fresh clone, CI runner spin-up), unmigrated changes vanish silently and prod diverges from local. The failure surfaces hours or days later as a runtime crash with no obvious cause.
+
+The discipline holds across ORMs; the specifics differ. Bassclef's loader reads `tech_stack.orm:` from `.claude/bassclef-configs.jsonc` and loads the matching sibling under `standards/migration-discipline/` for ORM-specific guidance.
+
+## Universal commitments (every ORM)
+
+1. **Never use auto-apply / push tools** that bypass migration files (Prisma `db push`, GORM `AutoMigrate` in production, Django `--fake`, etc.). They feel fast but ship drift.
+2. **Always create a migration file** when changing the schema. The migration is the audit trail; missing migration = missing audit.
+3. **Commit the migration with the schema change.** Splitting them across commits is how reviewers miss the migration entirely.
+4. **Run migrate-deploy in CI**, not `dev` / autogen. Production migrations are explicit, reviewed, and reversible.
+5. **After merging a schema change**, regenerate the client / model bindings + restart the dev process. Cached clients don't know about new fields.
+6. **Migration files are immutable once shipped**. Editing a merged migration corrupts history for every other developer.
+
+## Per-ORM siblings
+
+| Adopter's `tech_stack.orm` | Sibling loaded |
+|---|---|
+| `prisma` | `standards/migration-discipline/prisma.md` |
+| `sqlalchemy` | `standards/migration-discipline/sqlalchemy.md` (Alembic via SQLAlchemy autogen) |
+| `alembic` | `standards/migration-discipline/alembic.md` (standalone Alembic, non-SQLAlchemy) |
+| `gorm` | `standards/migration-discipline/gorm.md` |
+| `active-record` | `standards/migration-discipline/active-record.md` (Rails migrations) |
+| `drizzle` | `standards/migration-discipline/drizzle.md` *(future — file `/promote` to author)* |
+| `none` or unset | Universal commitments only |
+
+When the matching sibling does not exist, the rule fires the universal commitments only and surfaces a `/promote` candidate for the missing sibling.
+
+## Session-start drift check
+
+Each ORM's sibling describes its drift-detection mechanism. The session-start hook reads the adopter's `tech_stack.orm:` and runs the matching check. If drift is detected, the agent creates the missing migration before writing any code.
+
+## Tech stack vocabulary
+
+The loader reads `tech_stack.orm` shipped in bassclef#1127 (WU-2 of bet 2026-06-18a). Adopters set the value at `/onboard-repo` Phase 2.x. When `tech_stack:` block is absent, the universal commitments still apply; ORM-specific guidance is skipped until the operator declares the stack.
+
+## Refs
+
+- Path A pattern from bassclef#1133 (ARCH-T0 stack-leakage audit).
+- WU-5 of bet `docs/iteration-bets/2026-06-18a-public-adopter-leverage-longrun.md` ships this catalog split. Subsumes bassclef#1150 (T18 migration-discipline) — that ticket's scope lands here.
+- Sister Path A: bassclef#1133 WU-10 (new-dependency-check → dependency-discipline catalog, same shape).
+- Reads from bassclef#1127 (tech_stack vocabulary).

package/substrate/.claude/rules/security.md

@@ -0,0 +1,37 @@
+---
+tier: lite
+globs: ["**/*.ts", "**/*.tsx", "**/*.json", ".env*", "Dockerfile*", "docker-compose*"]
+description: Security scanning — loads when touching source, config, or infra files
+---
+
+Three-layer security pipeline. All block merge on failure.
+
+Pipeline order: push → secret scan → lint → typecheck → SAST → dependency audit → test → build → deploy
+
+Layer 1 — Secret Detection (gitleaks):
+  Pre-commit hook + CI. Catches API keys, OAuth tokens, AWS creds, private keys.
+  Never commit .env files, credentials, or API keys.
+
+Layer 2 — Dependency Vulnerabilities (npm audit):
+  CI blocks on high-severity CVEs. Uses audit-ci for strict enforcement.
+
+Layer 3 — SAST (ESLint security plugins + TypeScript compiler):
+  eslint-plugin-security, @typescript-eslint, eslint-plugin-no-secrets.
+  Optional: Semgrep for deeper analysis as complexity grows.
+
+Rules:
+- No secrets in code or logs — use environment variables
+- Validate all user input at system boundaries
+- Use parameterized queries (Prisma handles this)
+- OWASP top 10 awareness: XSS, injection, broken auth, SSRF
+
+Auth matrix (define per project):
+- List every route and its required auth level
+- Protected routes must check session/token
+- Public routes must be explicitly marked as intentionally public
+- API routes that modify data require auth — no exceptions
+
+Tenant isolation (if multi-tenant):
+- Every query on tenant-scoped models must include tenant context
+- No hardcoded tenant IDs, financial thresholds, or tenant-specific logic
+- Tenant context resolved at middleware/boundary, passed through

package/substrate/.claude/rules/skill-composition-declarations.md

@@ -0,0 +1,124 @@
+---
+tier: lite
+description: How and when skills declare composes_with (extends another skill) vs depends_on (needs a runtime predecessor) in frontmatter. Closes bassclef#862 Gap 3.
+---
+
+# Skill composition declarations — `composes_with:` and `depends_on:`
+
+Two frontmatter fields make skill relationships explicit and machine-checkable. `composes_with:` names skills the current skill builds on. `depends_on:` names what must exist at runtime before the skill can usefully run.
+
+The substrate-clarity-gate hook reads both fields and catches typos by checking that named targets actually exist on disk. `composes_with:` is strict — a missing target blocks the write. `depends_on:` is advisory in V1.
+
+## When this rule fires
+
+When authoring or editing a skill frontmatter and you need to express:
+
+- "This skill chains with skill X" → `composes_with:`
+- "This skill needs Y to exist or be set first" → `depends_on:`
+
+Either field is optional. Skills that stand alone need neither.
+
+## `composes_with:` — extends another skill's behavior
+
+Use when the current skill builds on another skill's output, runs another skill as a step, or extends another skill's discipline.
+
+Format:
+
+```yaml
+composes_with: [kiss, value-prop]
+```
+
+Each name must match a `.claude/skills/<name>/SKILL.md` file. The hook BLOCKs the write when a name does not resolve.
+
+Examples that qualify:
+
+- `/longrun` composes_with `[temperance, retro, promote, session-end]` — runs these skills at lifecycle points
+- `/launch` composes_with `[interpret-input, stage, spec, use-case]` — chains the buildable-plan pipeline
+- `/diagnose` composes_with `[temperance]` — fires temperance before diagnostic ceremony
+
+When `composes_with:` is wrong, the substrate doesn't know the skill maps to a real chain. INSTEAD of listing rough memory of which skills run: list the exact slugs the skill calls.
+
+## `depends_on:` — required runtime predecessors
+
+Use when the skill assumes a predecessor exists at runtime. The predecessor can be a skill, a rule, or a known config block in `.claude/bassclef-configs.jsonc`.
+
+Format:
+
+```yaml
+depends_on: [tech_stack, personas]
+```
+
+V1 enforcement is advisory. The hook warns when a named target does not resolve as a skill, rule, or known config block, but the write passes. V2 may flip to strict once the vocabulary stabilizes.
+
+Recognized config blocks (V1 list): `tech_stack`, `adopter_defaults`, `plan_tier`, `prose_discipline`, `longrun`, `testing`.
+
+Examples that qualify:
+
+- A skill that reads adopter stack metadata depends_on `[tech_stack]`
+- A skill that requires persona definitions depends_on `[personas]` (the `/personas` skill must have run)
+- A skill that reads adopter overrides depends_on `[adopter_defaults]` (the bassclef-configs block)
+
+When `depends_on:` is wrong, the skill silently produces empty output instead of telling the operator what is missing. INSTEAD of letting the skill discover its preconditions at runtime: declare them up front.
+
+## composes_with vs depends_on — picking one
+
+| If the relationship is... | Use |
+|---|---|
+| The current skill runs the other skill as a step | `composes_with:` |
+| The current skill extends or chains the other skill's output | `composes_with:` |
+| The current skill needs prior session state from another skill | `depends_on:` |
+| The current skill reads a config block at runtime | `depends_on:` |
+| The current skill assumes a rule is in force | `depends_on:` |
+
+INSTEAD of listing the same name in both fields: pick the relationship that fires first. A skill that both runs `/value-prop` AND needs `/personas` from a prior session declares `composes_with: [value-prop]` plus `depends_on: [personas]`.
+
+## What this rule does NOT cover
+
+- Source code patterns and design pattern annotations — see `.claude/rules/pattern-annotation.md`
+- Frontmatter schema fields other than these two — see `standards/frontmatter-schema.md`
+- Adopter onboarding wiring (which adopter-config blocks ship by default) — see `.claude/skills/onboard-repo/SKILL.md`
+- Layer 3 traceability manifests that auto-populate from declared values — Phase 4 of bet 2026-06-18a (WU-17/WU-18/WU-19 deferred follow-on)
+
+## Mechanical enforcement
+
+- `composes_with:` value type must be a YAML list of strings. A non-list type or a non-string item BLOCKs the write.
+- Each name in `composes_with:` must resolve to `<repo>/.claude/skills/<name>/SKILL.md`. A missing target BLOCKs.
+- Each name in `depends_on:` resolves against skills, rules, or known config blocks. A miss emits an ADVISORY notice and passes.
+- Substrate root for path resolution is derived from the file being written (everything before `/.claude/`).
+
+Hook: `.claude/hooks/substrate-clarity-gate.sh` (added in bassclef#862 WU-15).
+Tests: `.claude/hooks/tests/substrate-clarity-gate.test.sh` Tests 27–36.
+
+## Override
+
+`SKIP_SUBSTRATE_CLARITY=1 <command>` bypasses the validation and logs the override via trace-helper. INSTEAD of overriding when a target is genuinely missing: file the missing skill first, then add the composes_with entry.
+
+Override is appropriate when:
+
+- A migration script edits many skills at once and the target skill ships in the same PR
+- Emergency rescue when the hook itself is broken
+
+## Composes with
+
+- `.claude/rules/skill-description-clarity.md` — sister discipline at the frontmatter description surface
+- `.claude/rules/state-schema-validation.md` — sister mechanical check at the state-spine surface
+- `standards/frontmatter-schema.md` — full frontmatter field catalog
+
+## Refs
+
+- bassclef#862 Gap 3 — declared composition fields
+- WU-15 of `docs/iteration-bets/2026-06-18a-public-adopter-leverage-longrun.md` — ships this rule + hook extension
+- WU-3 of same bet (bassclef PR #1167) — frontmatter schema validation that recognized these fields
+- bassclef#1127 — tech_stack vocabulary; the first recognized config block
+- WU-17 / WU-18 / WU-19 (deferred) — Phase 4 manifests that read declared values to build forward/reverse lookups
+
+## Sources read
+
+- `.claude/hooks/substrate-clarity-gate.sh` — current validation passes
+- `standards/frontmatter-schema.md` — recognized field catalog
+- bassclef#862 issue body — WU-3 + WU-15 framing
+- `docs/iteration-bets/2026-06-18a-public-adopter-leverage-longrun.md` — goal doc with WU-15 spec
+
+## Retirement condition
+
+This rule retires when declared composition fields are no longer in the substrate vocabulary. The fields may evolve (Layer 3 manifests may read them differently) but the discipline of declaring relationships at the frontmatter surface persists.