@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/.claude/rules/cold-adopter-harness-discipline.md

@@ -0,0 +1,93 @@
+---
+tier: lite
+description: Substrate changes that touch any adopter-observable surface MUST pass the cold-adopter harness before merge.
+---
+
+# Cold-Adopter Harness Discipline
+
+Substrate changes that touch any adopter-observable surface MUST pass the cold-adopter harness before merge. The harness lives at `scripts/cold-adopter-harness-sync.sh` and runs as a PR-blocking job in `.github/workflows/bassclef-pr-ci.yml`. This rule is the methodology layer; the CI job is the mechanical layer; both load-bearing together close the audit gap that surfaced 2026-06-25 (harness existed but no rule required substrate evolution to drive a check).
+
+## When this rule fires
+
+Any PR that touches a path in the adopter-observable surface set:
+
+- `.claude/hooks/*.sh` — hook scripts adopters symlink into their `.claude/` dirs
+- `.claude/skills/*/SKILL.md` — skill definitions adopters discover by name
+- `.claude/rules/*.md` — rules adopters inherit via `additionalDirectories`
+- `.claude/agents/*.md` — agent definitions adopters dispatch by role
+- `.claude/luminaries/*.md` — luminaries adopters reference in goal docs
+- `lib/*.sh` — shared accessor libraries adopters source from
+- `standards/*.md` — standards adopters cite as reference
+- `standards/state-spine/schemas/*.json` — schemas adopters validate against
+- `presence/install/bassclef-sync.*.sh` — sync templates adopters vendor
+- `architecture/decisions/ADR-*.md` — ADRs adopters read for architecture context
+- `.github/workflows/bassclef-*.yml` — workflows adopters extend (when the change affects shared workflow shape)
+- `scripts/*.sh` — scripts adopters invoke (when classified as adopter-facing per `.claude/rules/testing-tier-config.md`)
+- Any other path under `~/src/sunj-labs/` that adopter sync hooks resolve through
+
+The rule passes through (does not fire) on:
+
+- Operator content (chronicles, journals, deferred-actions, `docs/operator-private/**`)
+- Documentation edits that stay clear of adopter-observable surface (typo in a chronicle)
+- Test edits where the source under test is not adopter-observable
+- Bug fixes where the harness already covers the change class (the harness IS the regression test in that case)
+
+## What the rule requires
+
+When a PR touches an adopter-observable path, the agent OR operator MUST:
+
+1. **Local pre-push run** — execute `bash scripts/cold-adopter-harness-sync.sh --mode sync --target .` from the bassclef-upstream root. Confirm exit 0 (all checks pass) OR explicitly document why a check failure is acceptable.
+2. **CI confirmation** — the `cold-adopter-harness` PR-blocking job in `.github/workflows/bassclef-pr-ci.yml` runs the same command on the PR head. Job must pass before merge.
+3. **PR body acknowledgement** — when the PR body's `Test plan` section is authored, include a line confirming the harness was run locally OR cite the CI job that runs it.
+
+The mechanical layer (CI job) is the load-bearing enforcement. The methodology layer (this rule + the local pre-push step) closes the gap between commit time and CI-fire time.
+
+## What this rule does NOT require
+
+- Running the harness on every commit (only on substrate-affecting paths; the path matcher above is the trigger)
+- Running the harness on operator content (chronicles, journals — pass-through)
+- Re-running the harness when CI already ran it cleanly and no substrate-affecting paths changed in a follow-up commit
+- A separate harness for adopter-facing scripts (the same `scripts/cold-adopter-harness-sync.sh` covers all surfaces)
+- Pre-commit-time enforcement (deferred to follow-on; bet 25g closes the CI + methodology layers; pre-commit hook is Gap 4 follow-on)
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Substrate change shipped without running the harness locally.** Author edited `.claude/hooks/<name>.sh`, ran the test suite, pushed. CI catches it but the round-trip cost is one PR cycle wasted.
+
+INSTEAD: run `bash scripts/cold-adopter-harness-sync.sh --mode sync --target .` before pushing. Catches the same class of failure locally; saves the CI round-trip.
+
+**Substrate change shipped + CI green + harness still fails.** The CI job ran but produced a stale result because the harness was not extended to cover the new check class. The author's PR ships; an adopter cloning fresh hits the failure.
+
+INSTEAD: extend the harness check classes in the same PR that introduces the new surface. Per `.claude/rules/bootstrap-pair-discipline.md` — when a new substrate primitive ships, its bootstrap pair includes the harness check class that validates it.
+
+**Author overrides the harness CI job to merge faster.** Operator-merge mode with `SKIP_COLD_ADOPTER_HARNESS=1` set in the workflow environment.
+
+INSTEAD: fix the harness failure OR document the explicit deferral in the PR body's `Out of scope` section with a follow-on ticket reference. Silence is not deferral.
+
+**Adopter-observable change disguised as operator-internal change.** Author edits `presence/install/bassclef-sync.template.sh` (adopter-observable) but commits it as a `chore:` claiming it is internal-only.
+
+INSTEAD: the path-matcher determines adopter-observable status, not the commit message. `presence/install/*` IS adopter-observable; the harness fires.
+
+## Override path
+
+`SKIP_COLD_ADOPTER_HARNESS=1` env var — logged via trace-helper per existing bassclef hook idiom. Use only for:
+
+- One-shot migration scripts that bootstrap state and intentionally produce a harness failure during the migration window (the migration itself fixes the failure)
+- Emergency rescue when the harness itself is broken (substrate-defect recovery; harness must be fixed before next PR)
+- Explicitly-deferred work where the PR body documents the override + cites a follow-on ticket that closes the deferred check
+
+For routine work, run the harness. The cost is ~30 seconds on `--target .` (no live network fetch). The discipline holds across every PR.
+
+## Composes with
+
+- `@luminary saltzer-schroeder` — complete-mediation principle (every adopter-observable surface validated by the harness; the rule names which surfaces are observable)
+- `@luminary hyrum-wright` — observable behavior becomes load-bearing (the harness pins the observable contract; this rule formalizes that pinning)
+- `@luminary linus-torvalds` — adopter-trust ceiling (CI gate IS the operational form of the adopter-compatibility stance; rule names the discipline)
+- `@luminary michael-feathers` — characterization tests at the adopter boundary (the harness IS the characterization test; this rule mandates the test fires)
+- `.claude/rules/we-dont-break-adopters.md` — sister discipline; this rule is the test-side of the discipline that rule defines
+- `.claude/rules/bootstrap-pair-discipline.md` — sister rule; this rule's "harness check class" IS one of bootstrap-pair's required pairs for adopter-observable primitives
+- `.claude/rules/testing-tier-config.md` — Tier 0 paths the harness validates; sister rule for per-path test enforcement
+- `.claude/rules/loop-discipline.md` — the per-PR cycle this rule fires within (loop's final-validation step composes the harness check)
+- `.claude/rules/blocked-items.md` — BLOCK protocol the CI job fires when the harness fails

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

@@ -0,0 +1,22 @@
+---
+tier: lite
+globs: ["*"]
+description: Commit message format — Conventional Commits
+---
+
+Format: `<type>: <description>`
+
+Types: feat, fix, docs, refactor, test, ci, chore, security
+
+Rules:
+- Imperative mood, lowercase, no period, max 72 chars
+- Body: explain WHY not what — the diff shows what
+- Footer: `Closes #NNN` or `Ref #NNN`
+- PR titles become squash commit messages — make them clean
+- One commit per PR on main (squash merge)
+
+## Forbidden prefixes
+
+Don't use `substrate-defect:` as a prefix. INSTEAD: use `fix:` per the type list above. Substrate bugs are bugs — the bassclef-internal `substrate-defect:` prefix duplicates the conventional `fix:` category without adding signal. See bassclef#1241 § "Wordlist amendment from 2026-06-19 dispatch session" for the decision.
+
+Don't invent one-off prefixes outside the 8 types listed above. INSTEAD: request additions via `/promote bassclef-evolution` so the type list grows by amendment rather than drift.

package/dist/lite/.claude/rules/compounding-axis-fresh-analysis.md

@@ -0,0 +1,173 @@
+---
+tier: lite
+description: "When /longrun prep proposes scope shapes, each shape's compounding-sequence row comes from fresh analysis."
+---
+
+# Compounding-Axis Fresh Analysis
+
+When `/longrun` prep proposes scope shapes, each shape's compounding-sequence row comes from fresh analysis. Hand-off documents do not satisfy Step 1.5 of the `/longrun` SKILL. That includes `docs/whereami.md`'s `next_longrun_queue` recommended order, an audit doc's `next_pending`, and a prior chronicle's pickup suggestion. Each shape gets its own row from the agent's own analysis at prep time.
+
+This rule is the methodology layer. The mechanical layer is `.claude/hooks/longrun-prep-compounding-sequence-check.sh`. That Stop hook is wired in `.claude/settings.json`. Tests at `.claude/hooks/tests/longrun-prep-compounding-sequence-check.test.sh`.
+
+The hook scans the latest assistant message when `state/markers/turn-prose-surface/longrun_prep_proposal.marker` is touched. It BLOCKs the stop (exit 2) when the compounding-sequence column headers are missing. Hook accepts EITHER shape per PR #1591 (bassclef#1555 PR-1): the new 6-axis frame (default, per plan doc `docs/next-session-plan-2026-09-09-compounding-axis-refactor.md`) OR the legacy 5-axis frame (grace window through 2026-10-31 per ADR-031). Backward compat opt-out: `COMPOUNDING_AXIS_TOGGLE=advisory` reverts to V1 (finding to stderr; exit 0).
+
+**V2 strict landed 2026-06-30.** The first `/longrun` prep after V1 ship surfaced only 3 of 5 columns at the operator-facing table. The hook caught the miss as designed. But it emitted ADVISORY to stderr. The agent could not see its own advisory in conversation. The operator could not see it on mobile. The operator asked "compounding sequence miss intact from the last substrate fix?" — that proved the visibility gap. The hook ships V2 strict as the next calibration step per ADR-035 (substrate-as-system — the mechanism must close the loop).
+
+## When this rule fires
+
+Every `/longrun` prep that proposes scope shapes:
+
+- `/longrun prep` (operator types) — Step 1.5 compounding-sequence analysis per shape candidate
+- `/sprint` next-work proposals when scope-shape options are surfaced (sister surface; same shape contract)
+- Bet doc authoring — when the goal doc's `## Steps` section enumerates a per-shape table, the same axis applies
+
+The rule does NOT fire on:
+
+- Single-shape continuation prep where the operator has already confirmed scope (no shape PICK happening; per-shape compounding still applies per memory `feedback-compounding-sequence-mandatory-every-prep-surface`)
+- WU-sequencing inside a chosen shape (covered by sister rule `.claude/rules/wu-sequencing-compounds.md` for Step 1.7 INTRA-shape)
+
+## What the rule requires
+
+Before the operator picks a scope shape:
+
+1. **Touch the surface marker FIRST** — `mkdir -p state/markers/turn-prose-surface && touch state/markers/turn-prose-surface/longrun_prep_proposal.marker` BEFORE writing the proposal. The marker tells the Stop hook the next message is a prep proposal subject to the column-presence check.
+2. **Per-option compounding row** — each option candidate carries 6 axes per `/longrun` SKILL Step 1.5 (new default per bassclef#1555). Per `#1193` cure, Step 1.5 prescribes the `### Compounding value — recommended only` section (old anchor `### Compounding value per option` still accepted through 2026-10-31 grace window per ADR-031). The 6 axes read as practical decision fields for Sam (Saturday evaluator) and Louis (context switcher) per plan doc `docs/next-session-plan-2026-09-09-compounding-axis-refactor.md` L36-45.
+
+   The 6-axis default (new; per bassclef#1555 PR-2):
+
+   | Axis | Source | Standard values |
+   |---|---|---|
+   | Deliverable | Plain sentence | What ships when this option lands |
+   | Problem | `/state-a-problem brief` | ≤500 chars; framework implicit |
+   | Value prop | `/value-prop tweet` | ≤280 chars; claim + sharpener |
+   | Turns | Grounded range | Cite past goal actuals per `.claude/rules/turn-estimate-grounding.md` |
+   | Risk | `🟢/🟡/🔴 <severity> — <failure mode>` | Bands (Klein blast radius): 🟢 fix-forward CI, no adopter impact, rework < 15 min · 🟡 rebuild cycle, local rollback, rework < 2h · 🔴 adopter-visible drift or compat shim, rework > 2h |
+   | Shipping priority | P1 / P2 / P3 / P4 or blank | Blank prompts `Run /eisenhower to prioritize?`. Distinct from Eisenhower Q1-Q4 (importance × urgency); P-prefix matches bassclef `p1` GitHub label |
+
+   The 5-axis legacy (grace window through 2026-10-31 per ADR-031; hook accepts both shapes):
+
+   | Plain-English (preferred per ADR-040 D4) | Compressed (grace only) | Standard values |
+   |---|---|---|
+   | Where the payoff shows up | Compounding surface | per-PR / per-release / per-session / per-adopter / per-quarter |
+   | How often it fires | Compounding rate | continuous / frequent / per-session / per-adopter / per-quarter |
+   | What must be true first | Foundation prerequisites | none / specific goal / ticket / config flag |
+   | Does this teach a shape later work reuses | Inverse-dependency | yes (names the later work) / no |
+   | What breaks if we ship this half-done | Risk class | One line: severity glyph + failure mode + detection. Bands per 6-axis Risk row above. |
+
+   R8 catch preservation: Deliverable + Problem + Value prop force fresh per-option analysis. `/state-a-problem` and `/value-prop` are themselves cognitive tools that resist copy-paste. The distinct-values check per option (bassclef#564) applies to whichever shape the prep uses.
+3. **Fresh analysis** — the column values come from the agent's reading of the shape itself, not from a hand-off doc's recommended order. If the agent reads a hand-off doc and the order matches its own analysis, the row matches by coincidence, not by copy. If the order DOESN'T match, the rule surfaces the conflict to the operator.
+4. **Recommended shape rationale** cites the compounding sequence + adopter-benefit mechanism (per sister rule for Step 1.6 bassclef-upstream#1302) explicitly.
+5. **Remove the surface marker AFTER scope confirmation** — once the prep proposal has landed AND the operator has confirmed scope (or the proposal is being abandoned), remove `state/markers/turn-prose-surface/longrun_prep_proposal.marker`. The marker's purpose is satisfied. Leaving it present makes every post-prep Stop event block under V2 strict default. Most subsequent turns (status updates, commit summaries, WU work) do not carry a shape proposal table.
+
+   ```bash
+   rm -f state/markers/turn-prose-surface/longrun_prep_proposal.marker
+   ```
+
+   This step is mandatory at the prep→execution handoff. Hook auto-cleanup deferred to a follow-on (substrate-evolution ticket) — the rule names the discipline; the agent removes the marker today.
+
+## Postcondition contract (per Hoare)
+
+Per bassclef-upstream#564 + luminary consultation (Ousterhout / Hoare / Feathers / Saltzer-Schroeder / Beck):
+
+**Precondition:** the /longrun prep proposes 2+ candidate shapes, each with a distinct scope.
+
+**Postcondition:** for every option O in the candidate set, for every axis A in the axis list of the shape the prep uses (6-axis default OR 5-axis legacy), the prep output contains a non-empty value V(O, A). The rendering satisfies the postcondition in one of two accepted shapes (per bassclef-upstream#1376):
+
+- **Per-option shape (pre-existing default).** V(O, A) renders under O's section as bullets or table rows. Each option gets a full section. Not only in a header row shared across options.
+- **Per-recommended-only shape (bassclef-upstream#1376 addition).** The prep opens with `**Recommend:** Option X`. V(recommended, A) renders under the recommended option's section as bullets. V(other, A) renders as scan-table row cells — one cell per axis per non-recommended option. Reader lands the recommended card fast; other options stay auditable from the scan-table row.
+
+The 6-axis default is: Deliverable, Problem, Value prop, Turns, Risk, Shipping priority. The 5-axis legacy (grace window through 2026-10-31) is: Where the payoff shows up, How often it fires, What must be true first, Does this teach a shape later work reuses, What breaks if we ship this half-done. Hook accepts either shape per PR #1591.
+
+The postcondition is stronger than the message-level check V2 ships. V2 verifies that the column names appear anywhere in the message. V3 (bassclef-upstream#564; ships with this rule amendment) verifies that each option section carries all axes of the chosen shape as distinct values. A single header row with axis names but no per-option values fails the postcondition. That is the R8 pattern this cure closes.
+
+Per `#1193` cure — the hook regex accepts both `Shape a-c` and `Option a-e` for the per-shape check during the grace window through 2026-10-31 per `.claude/rules/we-dont-break-adopters.md`. After that date only `Option [a-z]` matches. SKILL `#830` renamed the label; the rule postcondition applies equally to both vocabularies.
+
+**When shapes legitimately share an axis value** (e.g., all three shapes have `Risk class: low` because the work is small), the values still render per shape — same text under three sections. Rendering satisfies the postcondition. The check does not flag legitimate convergence.
+
+### Per-preset axis sets (added bassclef-upstream#1598)
+
+The 6-axis default applies when prep runs in the FULL ceremony path — no plan doc, no preset picker fired, agent authoring option candidates from scratch.
+
+When the preset picker fires (mechanism ships under bassclef-upstream#1598 goal Step 2 — not present yet at PR 1 land), the axis set adjusts to fit the picked preset. The Stop hook reads a preset marker under `state/markers/longrun-preset/` to know which axis set to apply. This rule extension is methodology-only until the picker hook lands in the sister PR of the same goal:
+
+| Preset | Axis set the hook checks for | Rationale |
+|---|---|---|
+| **converged** | Deliverable, Problem, Value prop, Turns, Risk in the top block. Per-row: Scope, Turns, Risk. | Plan doc carries the depth. Prep shows the pick at the top, table stays lean. |
+| **exploratory** | Per-row: Scope, One-line description, Turns, Risk. Recommend row marked. | Operator hasn't converged; light shape helps scanning. |
+| **reversible-small** | One line per option carrying scope + risk. Recommend line + action line. | Small scope needs no ceremony. |
+| **no marker present** | Fall back to 6-axis default (legacy behavior). Grace window preserves. | Existing prep discipline holds when picker did not run. |
+
+The postcondition applies per axis set. The hook fires ADVISORY when a preset marker exists but the checked axes are missing from the message. The hook fires BLOCK when the 6-axis default is expected but missing (unchanged existing behavior).
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Agent ships scope shapes WITHOUT compounding-sequence columns.** Tonight's failure (caught by operator). Cure: include the columns; touch the marker BEFORE the proposal.
+
+**Agent ships scope shapes with columns COPIED from whereami's `next_longrun_queue` or an audit's `next_pending`.** The columns are present but the fresh-analysis precondition is violated (R2 Hoare — mechanically unverifiable from output). Cure: re-analyze each shape independently; surface conflict if hand-off order disagrees with fresh order.
+
+**Agent touches the surface marker AFTER writing the proposal.** Tonight's failure mode. The hook fires at the next Stop event with the marker-touch message as the latest assistant message — not the proposal. Cure: touch marker BEFORE proposal.
+
+**Agent leaves the surface marker present after scope confirmation.** Under V2 strict default this blocks every subsequent Stop event because the hook scans every assistant message and most post-prep turns do not carry a shape proposal table. Cure: remove the marker at the prep→execution handoff per step 5 above.
+
+**Agent labels a "risk ledger" / "decomposition" / "audit" / "sources-read" without doing the underlying work (R8 underlying pattern).** The label is the assertion; the work that produces it is the data the assertion claims. Tonight's risk-ledger catch by operator. Cure: cite the file path of the produced artifact in agent output; not just the label.
+
+INSTEAD of any of these: do the work first; touch the marker; write the proposal with the compounding row populated from fresh analysis; cite produced artifacts by file path.
+
+## Hand-off documents that do NOT satisfy
+
+These all carry useful context but do not substitute for fresh analysis:
+
+- `docs/whereami.md` `next_longrun_queue` — operator + prior session's pickup suggestion; not compounding-derived
+- audit doc `next_pending` field — sequenced by audit author; may not match current compounding priorities
+- prior chronicle's "next pickup" suggestion — operator-facing handoff narrative; not analysis
+- prior goal doc's `next_bet` field — sequencing intent; not analysis
+- memory entry `feedback_*` — prior discipline; relevant context but not a substitute for the per-shape row
+
+Agent reads all of these for context. Agent then writes fresh compounding analysis per shape. The two activities are distinct.
+
+## Override
+
+`SKIP_COMPOUNDING_AXIS_CHECK=1 <command>` — bypass the hook for one call (already exists; logged via trace-helper). The rule's methodology layer has no override — fresh analysis is the precondition; without it, the proposal is incomplete.
+
+For trivial single-shape continuation prep where the operator has already confirmed scope: the rule applies but cost is small (one row in the goal doc); no override needed.
+
+## Composes with
+
+- `.claude/rules/wu-sequencing-compounds.md` — sister at Step 1.7 INTRA-shape (per-step produces/consumes)
+- `.claude/rules/operator-facing-prose.md` Rule 3 — marker touch BEFORE the named surface (this rule's mechanism precondition)
+- `.claude/rules/blocked-items.md` — BLOCKED protocol the hook fires under V2 strict
+- `.claude/rules/substrate-as-system.md` — every rule has a mechanism + every mechanism has a rule; this rule pairs the existing `longrun-prep-compounding-sequence-check.sh` mechanism with its rule body
+- `.claude/hooks/longrun-prep-compounding-sequence-check.sh` — the mechanical layer
+- `.claude/hooks/tests/longrun-prep-compounding-sequence-check.test.sh` — Tier 0 tests pinning the hook
+- `.claude/skills/longrun/SKILL.md` Step 1.5 — the procedure surface the rule serves
+- `@luminary jerome-saltzer-and-michael-schroeder` — complete mediation principle
+- `@luminary tony-hoare` — pre/postcondition contracts (R2 fresh-analysis is precondition, mechanically unverifiable)
+- `@luminary michael-feathers` — characterization tests pin REAL prep prose (R3 follow-on)
+- `@luminary kent-beck` — Tier 0 strict TDD on the hook (R4 follow-on covers each umbrella ticket instance)
+
+## Deferred to follow-on
+
+The bet 30b risk ledger named these add-to-scope dispositions for WU-E; they ship in a follow-on goal:
+
+- **R3 (Feathers)** — extend Tier 0 tests with 3 characterization tests against REAL `/longrun` prep messages (tonight's + 2 from prior goal prep chronicles)
+- **R4 (Beck)** — extend Tier 0 tests with cases for each instance under umbrella #540 (release recommendation skip, cleanup proposal skip, visual-compare skip, session-orientation skip)
+- **R6 (Linus)** — cold-adopter harness check for session-reflection.d/05-active-bet.sh fragment presence (sister to WU-B)
+- **R7 (Norman)** — extend `longrun-prep-compounding-sequence-check.sh` to ALSO scan for proof-of-read line from `/longrun` Step 0.4 (sister to WU-B cure 3)
+
+The rule body is complete without these; the hook coverage extension is a separate ship vehicle.
+
+## Per-WU coverage (bassclef-upstream#597 extension)
+
+Per-WU compounding-sequence rendering carries the same 5 axes at the step layer, alongside the produces/consumes table.
+
+When a `/longrun` prep proposal contains 2+ WU rows in the produces/consumes table (per Step 1.7), the proposal MUST also carry per-step compounding-sequence rendering — either a `## Compounding value per step` section OR per-step 5-axis bullets under each step.
+
+Anti-pattern that fails: shape-level 5 axes rendered per Step 1.5, WU produces/consumes rendered per Step 1.7, per-step compounding-sequence skipped. This shape passed as convention for weeks. It got displaced when PR #567 tightened Step 1.5 to per-shape distinct values, which shifted agent attention to shape-level. INSTEAD of trusting convention: mechanize the per-step coverage so sibling discipline tightening does not crowd it out.
+
+Correct shape: same 5 axes rendered per step with distinct values — plain-English names preferred per ADR-040 D4 (Where the payoff shows up / How often it fires / What must be true first / Does this teach a shape later work reuses / What breaks if we ship this half-done). Compressed forms accepted during the grace window through 2026-10-31.
+
+Mechanical layer: `.claude/hooks/longrun-prep-compounding-sequence-check.sh` extended with per-step check (V1 strict — BLOCK on missing per-step axes when 2+ WU rows present). Toggle `COMPOUNDING_AXIS_TOGGLE=advisory` retains backward-compat.
+
+Sister to Step 1.5 per-shape check (bassclef-upstream#564). Same discipline shape at a different layer.

package/dist/lite/.claude/rules/compounding-sequence-fresh-analysis.md

@@ -0,0 +1,173 @@
+---
+tier: lite
+description: "When /longrun prep proposes scope shapes, each shape's compounding-sequence row comes from fresh analysis."
+---
+
+# Compounding-Axis Fresh Analysis
+
+When `/longrun` prep proposes scope shapes, each shape's compounding-sequence row comes from fresh analysis. Hand-off documents do not satisfy Step 1.5 of the `/longrun` SKILL. That includes `docs/whereami.md`'s `next_longrun_queue` recommended order, an audit doc's `next_pending`, and a prior chronicle's pickup suggestion. Each shape gets its own row from the agent's own analysis at prep time.
+
+This rule is the methodology layer. The mechanical layer is `.claude/hooks/longrun-prep-compounding-sequence-check.sh`. That Stop hook is wired in `.claude/settings.json`. Tests at `.claude/hooks/tests/longrun-prep-compounding-sequence-check.test.sh`.
+
+The hook scans the latest assistant message when `state/markers/turn-prose-surface/longrun_prep_proposal.marker` is touched. It BLOCKs the stop (exit 2) when the compounding-sequence column headers are missing. Hook accepts EITHER shape per PR #1591 (bassclef#1555 PR-1): the new 6-axis frame (default, per plan doc `docs/next-session-plan-2026-09-09-compounding-axis-refactor.md`) OR the legacy 5-axis frame (grace window through 2026-10-31 per ADR-031). Backward compat opt-out: `COMPOUNDING_AXIS_TOGGLE=advisory` reverts to V1 (finding to stderr; exit 0).
+
+**V2 strict landed 2026-06-30.** The first `/longrun` prep after V1 ship surfaced only 3 of 5 columns at the operator-facing table. The hook caught the miss as designed. But it emitted ADVISORY to stderr. The agent could not see its own advisory in conversation. The operator could not see it on mobile. The operator asked "compounding sequence miss intact from the last substrate fix?" — that proved the visibility gap. The hook ships V2 strict as the next calibration step per ADR-035 (substrate-as-system — the mechanism must close the loop).
+
+## When this rule fires
+
+Every `/longrun` prep that proposes scope shapes:
+
+- `/longrun prep` (operator types) — Step 1.5 compounding-sequence analysis per shape candidate
+- `/sprint` next-work proposals when scope-shape options are surfaced (sister surface; same shape contract)
+- Bet doc authoring — when the goal doc's `## Steps` section enumerates a per-shape table, the same axis applies
+
+The rule does NOT fire on:
+
+- Single-shape continuation prep where the operator has already confirmed scope (no shape PICK happening; per-shape compounding still applies per memory `feedback-compounding-sequence-mandatory-every-prep-surface`)
+- WU-sequencing inside a chosen shape (covered by sister rule `.claude/rules/wu-sequencing-compounds.md` for Step 1.7 INTRA-shape)
+
+## What the rule requires
+
+Before the operator picks a scope shape:
+
+1. **Touch the surface marker FIRST** — `mkdir -p state/markers/turn-prose-surface && touch state/markers/turn-prose-surface/longrun_prep_proposal.marker` BEFORE writing the proposal. The marker tells the Stop hook the next message is a prep proposal subject to the column-presence check.
+2. **Per-option compounding row** — each option candidate carries 6 axes per `/longrun` SKILL Step 1.5 (new default per bassclef#1555). Per `#1193` cure, Step 1.5 prescribes the `### Compounding value — recommended only` section (old anchor `### Compounding value per option` still accepted through 2026-10-31 grace window per ADR-031). The 6 axes read as practical decision fields for Sam (Saturday evaluator) and Louis (context switcher) per plan doc `docs/next-session-plan-2026-09-09-compounding-axis-refactor.md` L36-45.
+
+   The 6-axis default (new; per bassclef#1555 PR-2):
+
+   | Axis | Source | Standard values |
+   |---|---|---|
+   | Deliverable | Plain sentence | What ships when this option lands |
+   | Problem | `/state-a-problem brief` | ≤500 chars; framework implicit |
+   | Value prop | `/value-prop tweet` | ≤280 chars; claim + sharpener |
+   | Turns | Grounded range | Cite past goal actuals per `.claude/rules/turn-estimate-grounding.md` |
+   | Risk | `🟢/🟡/🔴 <severity> — <failure mode>` | Bands (Klein blast radius): 🟢 fix-forward CI, no adopter impact, rework < 15 min · 🟡 rebuild cycle, local rollback, rework < 2h · 🔴 adopter-visible drift or compat shim, rework > 2h |
+   | Shipping priority | P1 / P2 / P3 / P4 or blank | Blank prompts `Run /eisenhower to prioritize?`. Distinct from Eisenhower Q1-Q4 (importance × urgency); P-prefix matches bassclef `p1` GitHub label |
+
+   The 5-axis legacy (grace window through 2026-10-31 per ADR-031; hook accepts both shapes):
+
+   | Plain-English (preferred per ADR-040 D4) | Compressed (grace only) | Standard values |
+   |---|---|---|
+   | Where the payoff shows up | Compounding surface | per-PR / per-release / per-session / per-adopter / per-quarter |
+   | How often it fires | Compounding rate | continuous / frequent / per-session / per-adopter / per-quarter |
+   | What must be true first | Foundation prerequisites | none / specific goal / ticket / config flag |
+   | Does this teach a shape later work reuses | Inverse-dependency | yes (names the later work) / no |
+   | What breaks if we ship this half-done | Risk class | One line: severity glyph + failure mode + detection. Bands per 6-axis Risk row above. |
+
+   R8 catch preservation: Deliverable + Problem + Value prop force fresh per-option analysis. `/state-a-problem` and `/value-prop` are themselves cognitive tools that resist copy-paste. The distinct-values check per option (bassclef#564) applies to whichever shape the prep uses.
+3. **Fresh analysis** — the column values come from the agent's reading of the shape itself, not from a hand-off doc's recommended order. If the agent reads a hand-off doc and the order matches its own analysis, the row matches by coincidence, not by copy. If the order DOESN'T match, the rule surfaces the conflict to the operator.
+4. **Recommended shape rationale** cites the compounding sequence + adopter-benefit mechanism (per sister rule for Step 1.6 bassclef-upstream#1302) explicitly.
+5. **Remove the surface marker AFTER scope confirmation** — once the prep proposal has landed AND the operator has confirmed scope (or the proposal is being abandoned), remove `state/markers/turn-prose-surface/longrun_prep_proposal.marker`. The marker's purpose is satisfied. Leaving it present makes every post-prep Stop event block under V2 strict default. Most subsequent turns (status updates, commit summaries, WU work) do not carry a shape proposal table.
+
+   ```bash
+   rm -f state/markers/turn-prose-surface/longrun_prep_proposal.marker
+   ```
+
+   This step is mandatory at the prep→execution handoff. Hook auto-cleanup deferred to a follow-on (substrate-evolution ticket) — the rule names the discipline; the agent removes the marker today.
+
+## Postcondition contract (per Hoare)
+
+Per bassclef-upstream#564 + luminary consultation (Ousterhout / Hoare / Feathers / Saltzer-Schroeder / Beck):
+
+**Precondition:** the /longrun prep proposes 2+ candidate shapes, each with a distinct scope.
+
+**Postcondition:** for every option O in the candidate set, for every axis A in the axis list of the shape the prep uses (6-axis default OR 5-axis legacy), the prep output contains a non-empty value V(O, A). The rendering satisfies the postcondition in one of two accepted shapes (per bassclef-upstream#1376):
+
+- **Per-option shape (pre-existing default).** V(O, A) renders under O's section as bullets or table rows. Each option gets a full section. Not only in a header row shared across options.
+- **Per-recommended-only shape (bassclef-upstream#1376 addition).** The prep opens with `**Recommend:** Option X`. V(recommended, A) renders under the recommended option's section as bullets. V(other, A) renders as scan-table row cells — one cell per axis per non-recommended option. Reader lands the recommended card fast; other options stay auditable from the scan-table row.
+
+The 6-axis default is: Deliverable, Problem, Value prop, Turns, Risk, Shipping priority. The 5-axis legacy (grace window through 2026-10-31) is: Where the payoff shows up, How often it fires, What must be true first, Does this teach a shape later work reuses, What breaks if we ship this half-done. Hook accepts either shape per PR #1591.
+
+The postcondition is stronger than the message-level check V2 ships. V2 verifies that the column names appear anywhere in the message. V3 (bassclef-upstream#564; ships with this rule amendment) verifies that each option section carries all axes of the chosen shape as distinct values. A single header row with axis names but no per-option values fails the postcondition. That is the R8 pattern this cure closes.
+
+Per `#1193` cure — the hook regex accepts both `Shape a-c` and `Option a-e` for the per-shape check during the grace window through 2026-10-31 per `.claude/rules/we-dont-break-adopters.md`. After that date only `Option [a-z]` matches. SKILL `#830` renamed the label; the rule postcondition applies equally to both vocabularies.
+
+**When shapes legitimately share an axis value** (e.g., all three shapes have `Risk class: low` because the work is small), the values still render per shape — same text under three sections. Rendering satisfies the postcondition. The check does not flag legitimate convergence.
+
+### Per-preset axis sets (added bassclef-upstream#1598)
+
+The 6-axis default applies when prep runs in the FULL ceremony path — no plan doc, no preset picker fired, agent authoring option candidates from scratch.
+
+When the preset picker fires (mechanism ships under bassclef-upstream#1598 goal Step 2 — not present yet at PR 1 land), the axis set adjusts to fit the picked preset. The Stop hook reads a preset marker under `state/markers/longrun-preset/` to know which axis set to apply. This rule extension is methodology-only until the picker hook lands in the sister PR of the same goal:
+
+| Preset | Axis set the hook checks for | Rationale |
+|---|---|---|
+| **converged** | Deliverable, Problem, Value prop, Turns, Risk in the top block. Per-row: Scope, Turns, Risk. | Plan doc carries the depth. Prep shows the pick at the top, table stays lean. |
+| **exploratory** | Per-row: Scope, One-line description, Turns, Risk. Recommend row marked. | Operator hasn't converged; light shape helps scanning. |
+| **reversible-small** | One line per option carrying scope + risk. Recommend line + action line. | Small scope needs no ceremony. |
+| **no marker present** | Fall back to 6-axis default (legacy behavior). Grace window preserves. | Existing prep discipline holds when picker did not run. |
+
+The postcondition applies per axis set. The hook fires ADVISORY when a preset marker exists but the checked axes are missing from the message. The hook fires BLOCK when the 6-axis default is expected but missing (unchanged existing behavior).
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Agent ships scope shapes WITHOUT compounding-sequence columns.** Tonight's failure (caught by operator). Cure: include the columns; touch the marker BEFORE the proposal.
+
+**Agent ships scope shapes with columns COPIED from whereami's `next_longrun_queue` or an audit's `next_pending`.** The columns are present but the fresh-analysis precondition is violated (R2 Hoare — mechanically unverifiable from output). Cure: re-analyze each shape independently; surface conflict if hand-off order disagrees with fresh order.
+
+**Agent touches the surface marker AFTER writing the proposal.** Tonight's failure mode. The hook fires at the next Stop event with the marker-touch message as the latest assistant message — not the proposal. Cure: touch marker BEFORE proposal.
+
+**Agent leaves the surface marker present after scope confirmation.** Under V2 strict default this blocks every subsequent Stop event because the hook scans every assistant message and most post-prep turns do not carry a shape proposal table. Cure: remove the marker at the prep→execution handoff per step 5 above.
+
+**Agent labels a "risk ledger" / "decomposition" / "audit" / "sources-read" without doing the underlying work (R8 underlying pattern).** The label is the assertion; the work that produces it is the data the assertion claims. Tonight's risk-ledger catch by operator. Cure: cite the file path of the produced artifact in agent output; not just the label.
+
+INSTEAD of any of these: do the work first; touch the marker; write the proposal with the compounding row populated from fresh analysis; cite produced artifacts by file path.
+
+## Hand-off documents that do NOT satisfy
+
+These all carry useful context but do not substitute for fresh analysis:
+
+- `docs/whereami.md` `next_longrun_queue` — operator + prior session's pickup suggestion; not compounding-derived
+- audit doc `next_pending` field — sequenced by audit author; may not match current compounding priorities
+- prior chronicle's "next pickup" suggestion — operator-facing handoff narrative; not analysis
+- prior goal doc's `next_bet` field — sequencing intent; not analysis
+- memory entry `feedback_*` — prior discipline; relevant context but not a substitute for the per-shape row
+
+Agent reads all of these for context. Agent then writes fresh compounding analysis per shape. The two activities are distinct.
+
+## Override
+
+`SKIP_COMPOUNDING_AXIS_CHECK=1 <command>` — bypass the hook for one call (already exists; logged via trace-helper). The rule's methodology layer has no override — fresh analysis is the precondition; without it, the proposal is incomplete.
+
+For trivial single-shape continuation prep where the operator has already confirmed scope: the rule applies but cost is small (one row in the goal doc); no override needed.
+
+## Composes with
+
+- `.claude/rules/wu-sequencing-compounds.md` — sister at Step 1.7 INTRA-shape (per-step produces/consumes)
+- `.claude/rules/operator-facing-prose.md` Rule 3 — marker touch BEFORE the named surface (this rule's mechanism precondition)
+- `.claude/rules/blocked-items.md` — BLOCKED protocol the hook fires under V2 strict
+- `.claude/rules/substrate-as-system.md` — every rule has a mechanism + every mechanism has a rule; this rule pairs the existing `longrun-prep-compounding-sequence-check.sh` mechanism with its rule body
+- `.claude/hooks/longrun-prep-compounding-sequence-check.sh` — the mechanical layer
+- `.claude/hooks/tests/longrun-prep-compounding-sequence-check.test.sh` — Tier 0 tests pinning the hook
+- `.claude/skills/longrun/SKILL.md` Step 1.5 — the procedure surface the rule serves
+- `@luminary jerome-saltzer-and-michael-schroeder` — complete mediation principle
+- `@luminary tony-hoare` — pre/postcondition contracts (R2 fresh-analysis is precondition, mechanically unverifiable)
+- `@luminary michael-feathers` — characterization tests pin REAL prep prose (R3 follow-on)
+- `@luminary kent-beck` — Tier 0 strict TDD on the hook (R4 follow-on covers each umbrella ticket instance)
+
+## Deferred to follow-on
+
+The bet 30b risk ledger named these add-to-scope dispositions for WU-E; they ship in a follow-on goal:
+
+- **R3 (Feathers)** — extend Tier 0 tests with 3 characterization tests against REAL `/longrun` prep messages (tonight's + 2 from prior goal prep chronicles)
+- **R4 (Beck)** — extend Tier 0 tests with cases for each instance under umbrella #540 (release recommendation skip, cleanup proposal skip, visual-compare skip, session-orientation skip)
+- **R6 (Linus)** — cold-adopter harness check for session-reflection.d/05-active-bet.sh fragment presence (sister to WU-B)
+- **R7 (Norman)** — extend `longrun-prep-compounding-sequence-check.sh` to ALSO scan for proof-of-read line from `/longrun` Step 0.4 (sister to WU-B cure 3)
+
+The rule body is complete without these; the hook coverage extension is a separate ship vehicle.
+
+## Per-WU coverage (bassclef-upstream#597 extension)
+
+Per-WU compounding-sequence rendering carries the same 5 axes at the step layer, alongside the produces/consumes table.
+
+When a `/longrun` prep proposal contains 2+ WU rows in the produces/consumes table (per Step 1.7), the proposal MUST also carry per-step compounding-sequence rendering — either a `## Compounding value per step` section OR per-step 5-axis bullets under each step.
+
+Anti-pattern that fails: shape-level 5 axes rendered per Step 1.5, WU produces/consumes rendered per Step 1.7, per-step compounding-sequence skipped. This shape passed as convention for weeks. It got displaced when PR #567 tightened Step 1.5 to per-shape distinct values, which shifted agent attention to shape-level. INSTEAD of trusting convention: mechanize the per-step coverage so sibling discipline tightening does not crowd it out.
+
+Correct shape: same 5 axes rendered per step with distinct values — plain-English names preferred per ADR-040 D4 (Where the payoff shows up / How often it fires / What must be true first / Does this teach a shape later work reuses / What breaks if we ship this half-done). Compressed forms accepted during the grace window through 2026-10-31.
+
+Mechanical layer: `.claude/hooks/longrun-prep-compounding-sequence-check.sh` extended with per-step check (V1 strict — BLOCK on missing per-step axes when 2+ WU rows present). Toggle `COMPOUNDING_AXIS_TOGGLE=advisory` retains backward-compat.
+
+Sister to Step 1.5 per-shape check (bassclef-upstream#564). Same discipline shape at a different layer.

package/dist/lite/.claude/rules/context-engineering.md

@@ -0,0 +1,155 @@
+---
+tier: lite
+description: The single most leverage-y discipline in bassclef.
+---
+
+# Context Engineering
+
+The single most leverage-y discipline in bassclef.
+
+When you write a skill, rule, hook, luminary, or agent definition, you
+are writing instructions for a model that has specific epistemic
+constraints. The model can only act on information physically present
+in its current context window. Cross-session memory, knowledge of
+past generations, imagined norms, and unstated operator intent are
+NOT accessible.
+
+Every instruction must be actionable from information the agent has
+in this conversation. If the instruction depends on information the
+model can't see, it is a no-op at best, a footgun at worst.
+
+## What the model has access to
+
+- Current conversation history (this session only)
+- Files in working directory (only when explicitly Read)
+- Tool results (when tools fire and return)
+- System prompt + loaded rules (whatever the harness injects, including the contents of `.claude/rules/` via `additionalDirectories`)
+- Memory directory (only if memory file is read this conversation)
+
+## What the model does NOT have access to
+
+- Previous conversations (unless that conversation's chronicle is loaded)
+- Prior generations of the same prompt (unless surfaced as text in current context)
+- What other agents are doing in parallel sessions (without state-spine reads)
+- Imagined "norms" or "averages" — the model can't compare against itself
+- Operator intent beyond what's been typed in this conversation
+- Prior commits / git log (without an explicit `git log` tool call)
+- Time / date awareness (the harness must surface today's date)
+
+## The INSTEAD-block pattern
+
+The rule's mechanical output, derived from Anthropic's context-engineering
+treatment. Every "NEVER" / "DON'T" / "AVOID" instruction is paired with an
+actionable substitute the model can verify in its current context.
+
+**Anti-pattern (unactionable):**
+
+```
+NEVER converge on common choices across generations.
+```
+
+→ Claude can't see other generations. Instruction has no in-context
+referent. No-op.
+
+**INSTEAD-block (actionable):**
+
+```
+INSTEAD: For each generation, deliberately commit to one bold
+direction from this list: [bold/saturated, moody/restrained,
+high-contrast/minimal, lo-fi/zine, handcrafted]. Pick a different
+direction than the obvious default for the input.
+```
+
+→ Model has the list in current context. Can pick. Actionable.
+
+**Format for bassclef instructions:**
+
+When writing a skill/rule/luminary, every "NEVER" / "DON'T" / "AVOID"
+gets paired:
+
+```
+NEVER do X.
+INSTEAD: <specific in-context action that produces the desired outcome>.
+```
+
+If you can't write the INSTEAD substitute, the original NEVER was
+unactionable — rewrite the whole instruction.
+
+## How to apply this rule
+
+### When writing a skill
+
+Ask, for every instruction:
+1. Does this reference information the model has in current context?
+2. If it references state that needs to be loaded — am I telling the model HOW to load it (Read X, run Y)?
+3. If it has a "DON'T" — is there an INSTEAD-block?
+4. Does it assume the model remembers something? If yes, am I providing the memory file path or instructing a Read?
+
+### When writing a rule
+
+Same checks plus:
+- Will this rule be loaded automatically (`additionalDirectories`)? If yes, the model has the rule body in context every conversation.
+- Or is it referenced by file path? If yes, I must explicitly tell the agent to Read it.
+
+### When writing a luminary
+
+The luminary file becomes context if invoked via `/luminary <slug>` or referenced in a skill that Reads it. Every "channel this luminary's discipline" instruction must produce concrete in-context actions, not aspirational adjectives.
+
+### When writing a hook
+
+Hooks fire at specific events and inject text into the agent's
+session output. The injected text IS context the model now has.
+Don't tell the model "remember this for next time."
+INSTEAD: write to a state file the next session reads.
+
+## What this rule does NOT cover
+
+- Cognitive-science research on "Theory of Mind in LLMs" (Kosinski, Bos et al.). That research tests whether LLMs *model human minds* — opposite direction from this rule. Cite this rule as "context engineering" (industry standard term) when discussing externally.
+- Tool design for agents (Anthropic's doc covers this in depth)
+- Memory systems beyond what bassclef implements
+
+## Common violations to grep for
+
+- `"don't repeat"` / `"don't drift"` / `"avoid converging"` — without INSTEAD substitutes
+- `"remember to"` / `"keep in mind"` — model has no persistence; you mean "Read X first" or "check Y"
+- `"based on prior sessions"` — the model can't see them; you must instruct chronicle Reads
+- `"the way you usually do"` — there is no usually; pin the specific pattern
+- `"use your judgment"` — what context does the model judge against? Specify or remove
+
+If `git grep -niE 'don.?t|never|avoid|remember to|keep in mind' .claude/skills .claude/rules .claude/luminaries` surfaces matches, audit each for INSTEAD-block discipline.
+
+## Relationship to other rules
+
+- `artifact-ingestion.md` — concrete instance of context engineering (Read before producing)
+- `iteration-bet-brief-completeness.md` — concrete instance (every artifact in brief, because receiver has no other state)
+- `mobile-ephemeral-session.md` — context engineering under the most extreme stateless conditions
+- `context-management.md` — operational guidance for context-window budgeting (companion at the runtime layer)
+- `bassclef#357` (autonomous-run flash + kiss) — output-side discipline; this rule is the input-side discipline
+- `bassclef#367` (section-heading standardization) — concrete instance of "if the parser greps for X, X must be in the producer's output")
+- `bassclef#382` (substrate-clarity-gate hook) — mechanical enforcement of skill-description clarity + rule/luminary INSTEAD-block discipline; closes the methodology+mechanism gap (rules prescribe; hook fires at PreToolUse Edit|Write)
+
+## Why this rule is the highest-leverage rule we have
+
+Most rules govern WHAT the agent should do (gates, checks, ceremonies). This rule governs HOW WE WRITE every other artifact. Meta-rule.
+
+Every future skill, rule, luminary, hook, and agent definition we add
+or modify is improved by this lens. Every existing artifact we audit
+against this lens is a candidate for cleanup.
+
+That's the leverage: one rule, applied retroactively + prospectively
+to the entire substrate.
+
+## What this rule will NOT fix
+
+- Genuinely smart-but-vague creative direction ("make it beautiful") — context engineering catches *unactionable* instructions; whether the actionable substitute is *good* is a separate quality question handled by luminary-driven design + visual-review
+- Hook bugs (mechanical) — context engineering is methodology; hooks are mechanical enforcement
+- Operator-side ambiguity — if the operator's request is unclear, no amount of model-context discipline fixes it; that's a clarification gate
+
+## Override
+
+There is no override. Context engineering is the model's actual
+constraint, not a discipline we choose to follow. Violating it
+produces drift (silent or noisy), not "exceptional cases."
+
+If a rule or skill seems to require a context-engineering violation,
+the rule or skill is wrong. Rewrite.