@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/.claude/rules/api-conventions.md

@@ -0,0 +1,115 @@
+---
+tier: lite
+description: Universal API design principles — REST conventions, response shapes, status codes, auth, validation. Stack-specific globs + helpers live in per-stack siblings under standards/api-conventions/.
+---
+
+# API Conventions
+
+Universal API design principles for any HTTP API surface. Stack-specific instantiations (Next.js App Router, FastAPI, Rails, Express, Go) live in per-stack siblings under `standards/api-conventions/`. The loader (future ticket) reads adopter's `tech_stack.frontend` + `tech_stack.backend` from `.claude/bassclef-configs.jsonc` and loads the matching sibling.
+
+When no sibling exists for the adopter's stack, the universal principles below still apply.
+
+## Universal principles
+
+These hold regardless of stack.
+
+### Route naming
+
+- RESTful: `/api/[resource]` for collections, `/api/[resource]/[id]` for items
+- Nested resources: `/api/[parent]/[parentId]/[child]`
+- Actions (non-CRUD): `/api/[resource]/[id]/[action]` (e.g., `/api/deals/123/archive`)
+- Lowercase, hyphenated: `/api/deal-pipeline`, not `/api/dealPipeline`
+
+### Response shapes
+
+Standard wrapper for successful single-item responses:
+
+```json
+{
+  "data": { ... },
+  "meta": { "timestamp": "2026-04-05T10:00:00Z" }
+}
+```
+
+Standard wrapper for successful collection responses:
+
+```json
+{
+  "data": [ ... ],
+  "meta": {
+    "total": 42,
+    "page": 1,
+    "pageSize": 20,
+    "timestamp": "2026-04-05T10:00:00Z"
+  }
+}
+```
+
+Standard error shape:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable description",
+    "details": [ ... ]
+  }
+}
+```
+
+### HTTP status codes
+
+| Code | When |
+|------|------|
+| 200 | Success (GET, PUT, PATCH) |
+| 201 | Created (POST) |
+| 204 | No content (DELETE) |
+| 400 | Validation error, bad input |
+| 401 | Not authenticated |
+| 403 | Authenticated but not authorized |
+| 404 | Resource not found |
+| 409 | Conflict (duplicate, stale update) |
+| 500 | Unexpected server error |
+
+### Pagination
+
+Default: cursor-based for lists > 20 items. Offset-based acceptable for admin/internal endpoints.
+
+```
+GET /api/deals?cursor=abc123&pageSize=20
+→ { data: [...], meta: { nextCursor: "def456", hasMore: true } }
+```
+
+### Auth
+
+- Every route that modifies data requires auth — no exceptions
+- Read routes may be public if explicitly marked (e.g., `// PUBLIC: [reason]` comment)
+- Auth check happens at the route boundary, not inside handlers
+- Tenant context resolved at the route boundary, passed through to queries
+
+### Validation
+
+- Validate all input at the route handler boundary
+- Use a schema-validation library (Zod, Pydantic, JSON Schema, etc.) for request body validation
+- Never trust client-provided IDs for authorization decisions
+- Use parameterized queries to prevent injection (every ORM has its own mechanism)
+
+## Per-stack siblings
+
+Per ARCH-T0 #1133 Path A — stack-specific instantiations live in their own files. Loader reads adopter's `tech_stack` from `.claude/bassclef-configs.jsonc`.
+
+| Adopter's `tech_stack.frontend` | Sibling loaded |
+|---|---|
+| `nextjs` | `standards/api-conventions/nextjs.md` |
+| `fastapi` | `standards/api-conventions/fastapi.md` *(future — file `/promote` to author)* |
+| `rails` | `standards/api-conventions/rails.md` *(future)* |
+| `express` | `standards/api-conventions/express.md` *(future)* |
+| `none` or unset | universal principles only |
+
+When the matching sibling does not exist, the universal principles above apply; sibling-specific guidance is skipped until the operator declares the stack and a sibling ships.
+
+## Path A treatment
+
+This rule shipped under ARCH-T0 #1133 Path A — additive, no content removed. Existing Next.js App Router specifics (formerly in this file) moved to `standards/api-conventions/nextjs.md`. Adopters following the rule pre-split keep working: the universal principles match what was already documented; the Next.js specifics are still discoverable via the sibling.
+
+Loader infrastructure that reads sibling per `tech_stack` is a future ticket. Until it ships, the cross-reference table above is the discovery path.

package/dist/lite/.claude/rules/artifact-ingestion.md

@@ -0,0 +1,137 @@
+---
+tier: lite
+description: Before producing any substantive generative output (canvas, prototype, spec, proposal, rubric, ADR, variant), the agent MUST read the referenced artifacts and enumerate them in…
+---
+
+# Artifact Ingestion — Read Before You Produce
+
+Before producing any substantive generative output (canvas, prototype,
+spec, proposal, rubric, ADR, variant), the agent MUST read the
+referenced artifacts and enumerate them in the output.
+
+"Pattern-matched on generic X" is a failure, not a shortcut.
+
+## When this rule fires
+
+Fires on any of the following output types when they reference an
+existing artifact the agent could have read:
+
+- **Canvas / spec / ADR** drafts referencing issues, prior canvases,
+  chronicles, or memory entries
+- **Prototype or variant** builds referencing prior prototypes,
+  design tokens, or luminary files
+- **Iteration proposals** referencing active iteration goals (must
+  enumerate every workstream — see `blocked-items.md` for same
+  anti-skim shape)
+- **Gate evaluations** (`/verify`, `/architect-review`) referencing
+  spec or ADR acceptance criteria
+- **Skills producing derivative content** (`/value-prop` from a ticket,
+  `/decompose` from a spec) — must read source, not just the title
+
+## Required format: "Sources read" block
+
+Every output subject to this rule MUST begin with (or include) a
+block like:
+
+```
+## What I'm NOT reading (with reason)
+
+- [path] — [deliberate exclusion reason, e.g. out of scope, stale]
+```
+
+If no artifacts were read: state "No prior artifacts; producing from
+scratch because [reason]." Silence is not exemption.
+
+## Anti-patterns that fire this rule
+
+Direct quotes from recent failures:
+
+- "I pattern-matched on generic card UI" — built prototype without
+  reading existing Norman/Prater variant files (2026-04-13)
+- "I didn't study the existing variants before building" — same
+  incident
+- Producing a canvas recommending vendor X without reading memory
+  that flagged vendor Y for evaluation (2026-04-13)
+- Proposing iteration scope covering 1 of 4 workstreams without
+  enumerating the ones being dropped (2026-04-12)
+- Skipping BLOCKED hook output in favor of answering the user's
+  direct question (2026-04-12; third instance in six weeks)
+
+Shape across all four: **training priors substituted for explicit
+artifacts the operator had already staged.**
+
+## Verification cue for the agent (self-check before output)
+
+Before producing the output, ask:
+
+1. Did I Read every file path referenced in the prompt or parent
+   artifact?
+2. Did I enumerate every workstream / variant / section of the parent
+   artifact, including the ones I'm deferring?
+3. Did I check memory for prior evaluations, flagged alternatives, or
+   deferred decisions relevant to this output?
+4. Did I consult the active luminary files for guidance (where the
+   skill or agent definition lists luminaries)?
+
+If any answer is "no," stop. Read first. Then produce.
+
+## Session-start branch — read recent strategic artifacts before substantive work
+
+Before any branch creation OR substantive PR work in a session, the
+agent MUST Read every strategic artifact (canvas / spec / iteration-bet
+/ ADR / decomposition / roadmap) authored OR substantively modified
+within the last 7 days.
+
+**Why this branch exists.** The production-time gate (PreToolUse on
+Write/Edit per `artifact-ingestion-gate.sh`) catches artifact-ingestion
+failures at WRITE time. It does NOT catch the case where an agent runs
+`/sprint`, sees a recently-merged commit in `git log`, treats it as
+background context, and proceeds with substantive work for hours
+before reading the artifact itself. That failure mode was demonstrated
+2026-04-26: 5h triage session opened against canvas-v3 commit listed
+in `/sprint` output without anyone reading the canvas; the canvas
+explicitly named the triage fixes as transition methodology being
+superseded by spine v0. Operator caught it; the cost was 4 PRs of
+short-lifetime work.
+
+**Mechanism.** `.claude/hooks/session-reflection.d/70-recent-strategic-artifacts.sh`
+fires at SessionStart, runs `git log --since=7-days --diff-filter=AM`
+restricted to the strategic-artifact path matcher, emits a `🛑 BLOCKED`
+block listing each path + commit date when results are non-empty.
+Window is configurable via `RECENT_STRATEGIC_DAYS` env (default 7);
+0 disables for that session.
+
+**Resolution per `.claude/rules/blocked-items.md`.** The agent MUST
+either Read each listed artifact this session OR explicitly defer
+("skip recent-artifacts this session"). Silence is not deferral. The
+default is Read. The marker pattern from sibling production gates is
+NOT used here because session-reflection.d/* fragments only fire once
+per SessionStart by design — re-fire suppression is unnecessary.
+
+**Override.** `SKIP_RECENT_ARTIFACTS=1 <command>` (logged to trace) or
+operator-explicit deferral statement.
+
+**Strategic-artifact path matcher** (mirrors production-gate matcher
+minus prototypes which have their own approval workflow):
+
+- `strategy/canvases/*.md`
+- `docs/specs/*.md`
+- `docs/iteration-bets/*.md`
+- `architecture/decisions/ADR-*.md`
+- `docs/decompositions/*.md`
+- `docs/roadmaps/*.md`
+
+Prototypes are deliberately excluded — `prototype-workflow.md` and
+`prototype-production-coupling.md` cover that surface separately.
+
+## Relationship to other rules
+
+- `blocked-items.md` — same anti-skim shape; blocked items are a
+  specific case of artifact-ingestion failure (skipping hook-surfaced
+  artifacts)
+- `oo-ad-entry-point.md` — analogous pattern for /decompose
+  (evidence required before Construction)
+- `sdlc-gates.md` — pre-build gates; artifact ingestion is the gate
+  *before* temperance and diagnosis
+- `substrate-config-schema.md` — reading `substrate.config.md` is
+  itself an artifact-ingestion obligation

package/dist/lite/.claude/rules/assert-only-after-verify.md

@@ -0,0 +1,111 @@
+---
+tier: lite
+description: "Plain check: Before I make a claim in this turn, I read the source first and cite it."
+---
+
+# Assert Only After Verify
+
+**Plain check:** Before I make a claim in this turn, I read the source first and cite it. If I cannot cite the source, I do not ship the claim.
+
+---
+
+Every operator-facing assertion carries at minimum three parts: **My claim** (what you are saying), **Evidence** (the source you read, cited inline), and **Why the evidence supports the claim** (one sentence on why the source supports the claim). Two optional parts sharpen the shape: **Qualifier** (confidence + N observations) and **Rebuttal** (what would falsify the claim). Without My claim + Evidence + Why the evidence supports the claim, the assertion does not ship. This rule closes #559 at the class layer — pairs with the UserPromptSubmit hook at `.claude/hooks/assert-verify-steering.sh` per ADR-035 substrate-as-system tenet.
+
+**Vocabulary note (per bet 2026-07-03b WU-4 rename #613):** The working labels are **My claim / Evidence / Why the evidence supports the claim**. Toulmin's original vocabulary (claim / data / warrant) stays as the research citation in `.claude/luminaries/stephen-toulmin.md` — the working vocabulary reads plainer at the moment the operator scans the injected reminder.
+
+## When this rule fires
+
+Every operator-facing assertion the agent authors:
+
+- Audit findings and severity ranks
+- Cure recommendations and root-cause attributions
+- Turn estimates and time budget claims
+- Modal claims (words like "wrong," "broken," "should," "must," "always")
+- Class-level diagnoses ("this is an instance of...")
+- Ticket bodies, PR bodies, commit messages
+- Chronicle entries and journal drafts
+- Scope enumeration from queued tickets (/longrun option composition; /sprint next-work proposals)
+
+Pass-through cases (rule does not add ceremony):
+
+- Direct tool output relayed to the operator (test output, git output). INSTEAD of citing sources for tool relays: preserve the raw output; the tool IS the source.
+- Operator-quoted text preserved verbatim. INSTEAD of citing external sources for quoted operator text: attribution to the operator IS the citation.
+- Small conversational asides that carry no claim ("switching to main now"). INSTEAD of applying the shape to asides: reserve the discipline for assertions carrying a claim.
+
+## What the rule requires
+
+Before shipping any operator-facing assertion:
+
+1. **My claim** — state the assertion in one sentence
+2. **Evidence** — cite the source read inline. Files by path, tickets by number, git commits by SHA, chronicles by filename, standards by section
+3. **Why the evidence supports the claim** — one sentence on why the cited source supports the claim
+
+Optional (sharpen the shape):
+
+4. **Qualifier** — confidence + how many observations back the claim (e.g., "3 catches in one session"; "1 chronicle line"; "grep across 62 rules")
+5. **Rebuttal** — what would falsify the claim (per Popper). A claim that cannot be falsified is steering, not truth
+
+## Anti-patterns
+
+These shapes fail the rule.
+
+**Assertion without cited source.** "The hook is broken." No path, no evidence.
+
+INSTEAD: "The hook at the named path exits 2 when stdin contains no JSON — reproduced with `echo '' | bash <that-hook-path>`." My claim + Evidence + Why the evidence supports the claim.
+
+**Assertion pointing at a source but no warrant.** "Per chronicle 2026-06-30." What in the chronicle? Which line?
+
+INSTEAD: "Per chronicle 2026-06-30d L47 — three catches in one session, all naming R8 pattern." The warrant tells the reader what the source says.
+
+**Severity rank without observation criteria.** "This is a HIGH-severity finding." What was measured? Against what threshold?
+
+INSTEAD: "This is HIGH — audit finding blocks Phase XI Batten Down HIGH-severity discipline per architecture/audits/2026-06-28-adopter-experience.md L23; 2 sibling instances." Evidence + Why the evidence supports the claim.
+
+**Root cause attribution without falsifiability.** "The cause is X."
+
+INSTEAD: "The cause is X — falsified if removing X does not remove the symptom. Test: [name the test]." Rebuttal is Popper's contribution.
+
+**One explanation without alternatives.** "The bug is caused by Y."
+
+INSTEAD: "The bug fits Y (my current explanation), Z (alternative — same symptom, different mechanism), and W (third alternative). Reading source [path] to discriminate." Peirce's contribution — abductive reasoning names multiple candidates before committing.
+
+**Trusting `gh issue view state` as evidence work is undone.** Scope enumeration surfaces (/longrun option tables, /sprint next-work proposals) that read ticket state alone recommend already-done work. Ticket state and shipped state can diverge — work sometimes lands without the ticket getting closed; tickets sometimes stay OPEN as trackers after cures ship.
+
+INSTEAD apply the discipline shape per row of the option table:
+
+1. Read the ticket's acceptance criteria (via `gh issue view <N> --json body`)
+2. Grep or read the source the ticket measures against (the file, the counter, the audit output)
+3. If acceptance criteria are met by the current source — close the ticket in the enumeration itself (do not recommend it as scope)
+4. If not met — proceed with a specific measurement in the option row (what's missing, what's the delta, what's the actual turn cost)
+
+The catch: bet 2026-07-26d /longrun prep surfaced #884 (MEMORY.md prune) as a 20-40 turn scope option; the ticket's acceptance thresholds were already met by the file on disk. Reading `gh issue view state` returned `OPEN`; reading the file measured against the ticket criteria showed all three thresholds already passed. Operator caught the miss. See `feedback_verify_ticket_source_not_just_state.md`.
+
+## The three luminaries anchoring this rule
+
+- **Stephen Toulmin** — argument model. Claim + data + warrant is the minimum shape; qualifier + rebuttal sharpen it. From *The Uses of Argument* (1958)
+- **Karl Popper** — falsifiability. A claim that cannot be falsified is not a scientific claim; it is steering language. From *The Logic of Scientific Discovery* (1959)
+- **Charles Sanders Peirce** — abductive reasoning. Multiple explanations fit the same evidence; naming alternatives before committing catches confirmation bias. From "Deduction, Induction, and Hypothesis" (1878)
+
+Full luminary files ship in bet 2026-07-01b WU-2 at `.claude/luminaries/{stephen-toulmin,karl-popper,charles-sanders-peirce}.md`.
+
+## Composes with
+
+- `.claude/hooks/assert-verify-steering.sh` — the paired UserPromptSubmit hook this rule commits to
+- `.claude/rules/context-engineering.md` — foundational rule; this rule extends context engineering with argument shape
+- `.claude/rules/plain-english-discipline.md` — sister rule at prose surface; both fire per prompt
+- `.claude/rules/artifact-ingestion.md` — "read before produce" is the data-source discipline this rule extends to assertions
+- `.claude/rules/blocked-items.md` — assertions calling something BLOCKED must cite the block-source
+- `.claude/rules/stuck-signal-diagnostic.md` — assertion of "stuck" requires 3-session data
+- `.claude/luminaries/stephen-toulmin.md` — primary anchor (bet 2026-07-01b WU-2)
+- `.claude/luminaries/karl-popper.md` — supporting anchor (bet 2026-07-01b WU-2)
+- `.claude/luminaries/charles-sanders-peirce.md` — supporting anchor (bet 2026-07-01b WU-2)
+- Memory `feedback_verify_ticket_source_not_just_state.md` — the discipline the scope-enumeration anti-pattern encodes; verify tickets against source before scoping, not `gh` state alone
+- `.claude/skills/longrun/SKILL.md` prep — the surface where the scope-enumeration extension fires (Step 1 pre-flight through Step 1.7)
+- `.claude/skills/sprint/SKILL.md` — sister surface (next-work proposals)
+- ADR-035 substrate-as-system — the tenet this rule operationalizes at reasoning boundary
+
+## Override
+
+`SKIP_ASSERT_VERIFY_STEERING=1 <command>` on the hook — logged via trace-helper. The rule itself has no per-call override; the shape is minimum baseline. Use only when quoting verbatim external content that contains an unverified claim.
+
+INSTEAD of overriding for routine work: cite the source. The cost is a filename + one warrant sentence; the discipline compounds across every future assertion in every consumer repo.

package/dist/lite/.claude/rules/blocked-items.md

@@ -0,0 +1,139 @@
+---
+tier: lite
+description: "Session-start hook output may contain lines prefixed with BLOCKED:."
+---
+
+# Blocked Items — Mandatory Resolution
+
+Session-start hook output may contain lines prefixed with `BLOCKED:`.
+These are not suggestions. They are mandatory scope.
+
+## Protocol
+
+1. **Before proposing any new work**, scan session-start output for
+   `BLOCKED:` lines.
+2. Each blocked item MUST be either:
+   - **Resolved** in this session (run the command, write the artifact), OR
+   - **Explicitly deferred** by the operator ("skip metrics this session")
+3. If the operator says nothing about blocked items, the default is
+   **resolve them**. Silence is not deferral.
+4. Propose blocked items as the FIRST items in your session plan.
+   New iteration work comes AFTER blocked items, not instead of them.
+
+## What counts as resolution
+
+- `BLOCKED: release-notes` → run /release-notes, commit the output
+- `BLOCKED: metrics` → run the metrics script, commit the output
+- `BLOCKED: chronicle` → write the missing chronicle, commit
+- `BLOCKED: architect-review` → run /architect-review
+
+## What counts as explicit deferral
+
+The operator must say one of:
+- "skip [item]" / "defer [item]" / "not this session"
+- Acknowledging the item exists is NOT deferral
+- "okay" or "got it" is NOT deferral — it means resolve it
+
+## Friction during chained dispatches (bassclef#400)
+
+The `post-skill-friction-check.sh` hook fires on PostToolUse Skill for
+major composer skills (/stage (formerly /preview), /launch (formerly /preview-build), /build, /shape full,
+/longrun, /decompose, /spec, /architect-review, /interpret-input, etc.).
+It classifies output:
+
+- **Unambiguous friction** (`deferred to Phase X`, `stub return`,
+  `Error:`, `not yet implemented`) → log + recommend `/promote
+  substrate-defect` inline. Don't defer to closeout; file at the
+  boundary.
+- **Borderline friction** (`Lorem ipsum`, `XXX`, `FIXME`, partial
+  output) → log only; operator triages on return.
+- **No friction** → silent.
+
+The friction log lives at `docs/session-friction-log.md`. Operators
+returning from unattended runs read the log first; promote what's
+worth promoting.
+
+Per-skill opt-out: add `disable_friction_check: true` to skill
+frontmatter (rare; for skills whose stub returns are intended).
+Per-call override: `SKIP_FRICTION_CHECK=1 <command>` (logged).
+
+## When resolution reveals a substrate defect
+
+Sometimes resolving a BLOCKED item surfaces the real cause: the hook's
+detection path is wrong, a state file rotted, a marker format changed,
+or the compliance calculation reads a location the writer stopped
+using. The nominal work was done; the signal kept firing because the
+mechanism is broken.
+
+When this happens, resolution MUST include firing `/promote` with the
+`substrate-defect` classifier. Fix the local instance AND promote the
+mechanism fix — otherwise every consumer repo keeps hitting the same
+broken hook.
+
+### Trigger (any of)
+
+1. **Stuck signal resolved** — the signal was stuck per
+   `stuck-signal-diagnostic.md`, mechanism-read found a defect, defect
+   is now fixed. `/promote` fires automatically on this path.
+2. **Hook false-positive** — the banner fired even though the
+   underlying work was already done, and the fix was editing the hook,
+   not doing the work.
+3. **Counter miscount** — the number in the banner was wrong
+   (off-by-one, wrong window, stale cache), and the fix was editing
+   the counting mechanism.
+4. **Marker location rot** — a gate marker was written to a path the
+   reader no longer checks (e.g., `/tmp` sandbox teardown), and the
+   fix was dual-writing or relocating the marker.
+
+### Protocol
+
+1. **Resolve the local instance.** Land the substrate edit (hook fix,
+   rule update, path correction) in the current branch.
+2. **Fire `/promote`** — use the substrate-defect template in
+   `promote/SKILL.md`. The /promote issue cites:
+   - Signal observed (banner text + chronicle dates showing the loop)
+   - Mechanism file read (path + what was wrong)
+   - Fix applied (PR or commit ref)
+   - Propagation requirement (which consumer repos inherit; what
+     breaks if they don't pick up the fix)
+3. **Classify** as `agent-self-proposed` + `substrate-defect` (see
+   `promote/SKILL.md` label table). These don't need operator prompt —
+   agent-discovered defects file automatically because the trigger
+   condition (stuck signal + mechanism fix) is unambiguous.
+4. **Cite in the session's chronicle** with explicit "substrate defect
+   promoted: #NNN" line so retrospectives can audit the promotion
+   path worked.
+
+### Why mandatory (not MUST-try)
+
+`bassclef-evolution.md` already describes /promote as the promotion
+path. The gap being closed: when an agent finds a substrate defect
+mid-session and fixes only the local instance, the decision to
+promote becomes "nice to have" and rots. Three sessions in April 2026
+fixed local substrate drift without firing /promote; the same drift
+resurfaced in consumer repos two weeks later (POA inherited broken
+hook paths).
+
+Making /promote mandatory on the `resolution-revealed-defect` branch
+removes the decision. The agent doesn't choose whether to promote;
+the trigger fires it.
+
+### What doesn't trigger /promote
+
+- BLOCKED items resolved by doing the nominal work (running
+  `/release-notes`, writing the chronicle) — the mechanism was fine,
+  the work just wasn't done. No defect to promote.
+- Operator-overridden deferrals — the operator chose to skip; no
+  mechanism analysis happened.
+- One-off bugs in the agent's session (typo in commit message,
+  missed file) — those aren't substrate.
+
+The trigger is specifically "mechanism was broken, mechanism got
+fixed" — not "work was slow, work got faster."
+
+## Infrastructure note
+
+This is a methodology rule, not a hook. It works regardless of whether
+enforcement comes from bash hooks, Managed Agents outcome preconditions,
+or any other infrastructure. The hook produces the signal; this rule
+defines the response.

package/dist/lite/.claude/rules/bootstrap-pair-discipline.md

@@ -0,0 +1,106 @@
+---
+tier: lite
+description: Every substrate primitive ships with its paired bootstrap discipline.
+---
+
+# Bootstrap-Pair Discipline
+
+Every substrate primitive ships with its paired bootstrap discipline. A primitive without its pair is half-shipped — the substrate appears to ship the feature, but adopters hit the missing half as silent breakage at runtime.
+
+This rule names the failure class, enumerates 5 known instances, and gives the discipline a name so future PRs catch the failure at authoring time instead of at adopter-runtime time.
+
+## When this rule fires
+
+Any PR that adds a substrate primitive to bassclef. "Substrate primitive" means any of these surfaces:
+
+- **Hook** — a new file under `.claude/hooks/*.sh`
+- **Rule** — a new file under `.claude/rules/*.md`
+- **Skill** — a new directory under `.claude/skills/<name>/SKILL.md`
+- **Validator / accessor / library** — a new shell library under `lib/*.sh` or a new validator under `scripts/`
+- **Schema** — a new JSON Schema under `standards/state-spine/schemas/*.schema.json`
+- **Standard** — a new standard under `standards/*.md`
+- **ADR** — a new file under `architecture/decisions/ADR-*.md`
+
+The rule passes through (does not fire) on:
+
+- Operator content (chronicles, journals, deferred-actions)
+- Documentation edits without behavior change
+- Bug fixes that touch existing primitives without adding new ones
+- Test edits (covered by sister rules — `.claude/rules/testing-tier-config.md`, `test-list-discipline.md`)
+
+## The 7 known instances
+
+Each row names the primitive being added, the pair it owes, and the failure mode when the pair is missing.
+
+| Building block added | Bootstrap pair owed | Failure mode when missing |
+|---|---|---|
+| **Hook** under `.claude/hooks/*.sh` | The hook is wired in `.claude/settings.json` OR `presence/install/bassclef-sync.template.sh` for adopters | Hook exists on disk but stays silent (dead-letter) — surfaced 5 times during the 2026-04 substrate audit |
+| **Rule** citing a mechanical hook in `## Mechanical Enforcement` | The cited hook exists on disk AND is wired | Rule promises mechanical layer that stays silent; methodology only — surfaced 11 times in WU-5 of bet 2026-06-24c |
+| **Skill** declaring `modes:` / `tiers:` / `sizes:` in frontmatter | The `description:` field names each declared mode inline (per `.claude/rules/skill-description-clarity.md` description-mirrors-modes) | Type-ahead operator menu shows nothing distinguishing — surfaced 3 times in WU-6 of bet 2026-06-24c |
+| **Accessor library** named in a rule (`lib/state.sh`) | The file exists at the named path | Rule's `accessor-library-discipline.md` references a path that 404s — surfaced via #324 (closed via bet 2026-06-25a) |
+| **Schema** under `standards/state-spine/schemas/*.schema.json` | The write-time validation hook is wired (`state-validate.sh` PreToolUse) AND the entity has a storage-shape entry in `standards/state-spine.md` | Schema ships but the spine permits writes that violate it — surfaced via #319 (partial-close via bet 2026-06-25a WU-3) |
+| **Adopter-observable surface change** — new hook / skill / rule / agent / luminary / standard / ADR / schema / sync-template OR edit to an existing one matching `.claude/rules/cold-adopter-harness-discipline.md` § "When this rule fires" | The cold-adopter harness check class covering the new surface exists in `scripts/cold-adopter-harness-sync.sh` AND the CI job `cold-adopter-harness` in `.github/workflows/bassclef-pr-ci.yml` fires on the PR | Substrate ships a change that breaks adopter-observable surface; harness passes with stale coverage OR harness fails with no CI gate to catch it before merge — surfaced via 2026-06-25 /longrun prep audit (Gap 1 + Gap 2 + Gap 3 of 5; closed via bet 25g) |
+| **Release pipeline path change** (added bet 2026-06-29c WU-5) — any PR that adds a new top-level directory (e.g., new `lib/`, `templates/`, `presence/`) OR moves files between substrate directories (`scripts/`, `presence/`, `lib/`, `standards/`) OR adds a new operator-template at `presence/install/` | The release script's `ALLOWED_PATHS` in `scripts/release-to-bassclef.sh` covers the new top-level directory AND any new template at `presence/install/<name>.template.sh` is handled by the release step that ships templates (e.g., `public-bassclef-settings.template.json` copy step) | Release ships everything except the new directory; adopters get partial substrate; hooks reference files that aren't on the public tree — surfaced 4 release iterations in a row on 2026-06-29 (PRs #1372/#1373/#1374/#1375): PR #318 missed `scripts/`; later PRs missed `lib/` + `templates/`; settings template needed its own release-script step. Three sister cures: (a) extending the cold-adopter harness rule-mechanism-claim scanner to recognize `<name>.template.sh` as evidence the hook ships via install template; (b) refining the operator-private-path check filename pattern so it doesn't false-positive on bassclef's own `-review` rule names (out of scope tonight; tracked as follow-on); (c) auto-applying the `bassclef-internal-prose-ok` label on release PRs so the operator-private-path check passes first time (out of scope tonight; tracked as follow-on). |
+
+## What this rule requires
+
+When a PR adds a substrate primitive, the PR body MUST include a `Bootstrap pair shipped` block in the Summary section naming the pair:
+
+```markdown
+## Bootstrap pair shipped
+
+- Building block: `<path>` (e.g., `.claude/hooks/foo.sh`)
+- Pair: `<wiring location>` (e.g., `.claude/settings.json` PreToolUse Edit|Write|MultiEdit) OR `<rationale for no pair>`
+```
+
+If the primitive type is not in the 5-instance table, the author names the pair in plain English ("the pair this primitive owes is X because Y"). The reviewer's job is to verify the pair actually exists in the PR — not just that the author named it.
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Ship hook without wiring** — the hook lives on disk but no settings.json registers it. The hook is dead-letter; the failure surfaces silently in adopter sessions.
+
+INSTEAD: ship the wiring in the same PR.
+
+**Cite an unwired hook in a rule's Mechanical Enforcement section** — the rule promises mechanical enforcement but the hook is not wired. The rule operates as methodology-only with no agent-side awareness of the gap.
+
+INSTEAD: either wire the hook in the same PR or rephrase the rule to claim methodology-only enforcement.
+
+**Declare skill modes in frontmatter without naming them inline in the description** — the harness type-ahead shows the skill name but no mode disambiguation; operator has to invoke and discover.
+
+INSTEAD: include each declared mode in the description's 280-character budget.
+
+**Name a file path in a rule that does not exist on the substrate** — adopters reading the rule follow the path and 404.
+
+INSTEAD: verify the path resolves on bassclef-upstream before the PR opens.
+
+**Ship a schema without wiring the write-time validator** — writes that violate the schema land in the spine and corrupt state silently.
+
+INSTEAD: wire `state-validate.sh` in `.claude/settings.json` in the same PR as the schema.
+
+## Override path
+
+`SKIP_BOOTSTRAP_PAIR=1 <command>` — for genuine cases where the pair lands in a separate PR by design AND the separate PR is filed AND the current PR's body cites the follow-on. Logged via trace-helper.
+
+INSTEAD of overriding for routine work: ship the pair in the same PR. The cost is small (one hook line, one settings.json entry, one rule citation) and the discipline compounds across every future primitive.
+
+## Mechanical layer (V2 deferred)
+
+V1 of this rule is methodology only. V2 deferred extension: a pre-commit hook that:
+
+1. Detects PRs adding substrate primitives (path matchers per the "When this rule fires" section)
+2. Greps the staged content for the pair (e.g., new hook → grep settings.json staged diff for the hook's path)
+3. BLOCKs when the pair is absent AND the override is absent
+
+Defer to a separate goal when the methodology layer has shipped through enough PRs that the failure modes are stable and the pre-commit logic can mechanize against them confidently.
+
+## Composes with
+
+- `.claude/rules/pr-body-shape.md` — the `Bootstrap pair shipped` block lives in the Summary section per this rule
+- `.claude/rules/we-dont-break-adopters.md` — sister discipline at the adopter-observable surface; this rule extends the discipline to bassclef-internal substrate completeness
+- `.claude/rules/blocked-items.md` — the BLOCK protocol the V2 mechanical layer would fire
+- `.claude/rules/loop-discipline.md` — sister at the construction-cycle level; bootstrap-pair check fires in the per-PR loop discipline
+- `.claude/rules/accessor-library-discipline.md` — the rule that surfaced one instance (#324)
+- `.claude/rules/testing-tier-config.md` — the Tier 0 strict-TDD pattern; the bootstrap pair often IS the test that locks the primitive
+- `architecture/audits/2026-06-24-validator-bootstrap.md` — WU-10 surfaced the 5-instance enumeration

package/dist/lite/.claude/rules/branching.md

@@ -0,0 +1,28 @@
+---
+tier: lite
+globs: ["*"]
+description: Trunk-based development — branch naming and flow
+---
+
+Model: trunk-based development (solo variant). `main` is always deployable.
+
+Branch naming:
+- `feature/ISSUE-NNN-short-description`
+- `fix/ISSUE-NNN-short-description`
+- `spike/ISSUE-NNN-short-description`
+
+Every branch ties to a GitHub Issue. No branch without an issue.
+
+Flow: issue → branch from main → work → PR → CI passes → squash merge → delete branch
+
+Rules:
+- Broken main = drop everything
+- No branches older than 5 days — break it up
+- Force push on feature branches is fine, never on main
+- Semantic versioning tags for releases: v0.1.0, v0.2.0
+
+Multi-branch work (autonomous/multi-step sessions):
+- See `standards/branch-stacking.md` for stacked atomic branches
+- Stack manifest declares branches, dependencies, parallel-safety
+- Naming: `feature/ISSUE-NNN-stack-N-short-description`
+- Each branch is independently reviewable and revertable