@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/.claude/rules/hook-wire-on-author.md

@@ -0,0 +1,103 @@
+---
+tier: lite
+description: Every new bassclef hook (a file under .claude/hooks/*.sh) MUST be added to project .claude/settings.json in the same PR that authors it.
+---
+
+# Hook Wire On Author
+
+Every new bassclef hook (a file under `.claude/hooks/*.sh`) MUST be added to project `.claude/settings.json` in the same PR that authors it. Hooks without settings entries are dead-letter — they exist on disk but stay silent on every tool call. The substrate appears to ship the safety net; in reality, every adopter session runs without it.
+
+INSTEAD of shipping the hook on its own: include the settings entry in the same PR. The cost is one settings.json edit; the work compounds across every adopter session.
+
+This rule closes the substrate-defect class that produced bassclef-upstream#319 (phase-1, closed 2026-06-24) + #376 (phase-2, this rule's filing context).
+
+## Why this rule exists
+
+Audit during PR #318 surfaced 32 of 42 bassclef hooks without settings entries. The defect class: write hook → ship hook → forget the settings entry. No mechanical check existed to flag these at PR-author boundary.
+
+INSTEAD of letting the gap repeat: this rule + the V2 mechanical layer in `pre-commit-gate.sh` close the class at the authoring boundary so phase-3 never has to file.
+
+Phase-1 (#319) shipped a subset of P0 entries during the 2026-06-24 architect-review longrun. Phase-2 (#376) shipped the remaining 11 during the 2026-06-26 ultra-plus thread longrun. Both bets exist because the discipline was methodology-only.
+
+## When this rule fires
+
+Any PR that adds a new `.claude/hooks/*.sh` file. The rule passes through on:
+
+- Edits to existing hooks (only NEW hook files trigger)
+- Test files under `.claude/hooks/tests/`
+- Library scripts under `lib/` (those are sourced; not hooks)
+- Documentation under `.claude/hooks/*.md`
+
+## What the rule requires
+
+When a PR adds a new hook file, the same PR MUST also include an edit to `.claude/settings.json` adding the hook at its correct matcher. The hook's header MUST declare its intended matcher per these conventions:
+
+- `# PreToolUse: <matcher>` — added under `hooks.PreToolUse[].matcher`
+- `# Stop` — added under `hooks.Stop[].hooks`
+- `# PostToolUse: <matcher>` — added under `hooks.PostToolUse[].matcher`
+- `# SessionStart` — added under `hooks.SessionStart[].hooks`
+- `# UserPromptSubmit` — added under `hooks.UserPromptSubmit[].hooks`
+
+The PR body MUST include a `Bootstrap pair shipped` block per `.claude/rules/bootstrap-pair-discipline.md` naming both the hook file AND the settings.json entry line.
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Hook shipped without settings entry.** Author edits `.claude/hooks/foo.sh`, commits, opens PR. Settings.json untouched.
+
+INSTEAD: ship the settings entry in the same PR. The cost is small (one settings.json line); the work compounds across every adopter session.
+
+**Hook references "sourced-only by design" in header.** Hook docstring says "this hook is sourced by other hooks, not connected directly." Phase-1 audit treated this as exempt; phase-2 reshape clarifies: composite/sourced libraries belong under `lib/`, not `.claude/hooks/`.
+
+INSTEAD of marking the hook exempt: move sourced-only libraries to `lib/`. Hooks under `.claude/hooks/` either get a settings entry or get moved.
+
+**Hook shipped at wrong matcher.** Author adds `pre-build-gate.sh` under PreToolUse Bash when its header says PreToolUse Edit|Write|MultiEdit. Hook stays silent.
+
+INSTEAD of guessing the matcher: read the hook's header before adding the entry. The matcher convention is documented above.
+
+## Mechanical layer
+
+**V1.5 (bassclef-upstream#1163 Layer 4, shipped 2026-08-08):** `.claude/hooks/hook-classifier-canary.sh` fires as PreToolUse Edit|Write|MultiEdit against paths under `.claude/hooks/*.sh` (excludes tests dir + fixtures). Detects new hook files that lack any recognized wiring signal (settings.json / .github/workflows / scripts/release-to-bassclef.sh / launchd header / sourced-lib header). Emits ADVISORY to stderr naming 5 remediation paths. Sources `lib/mechanism-fidelity.sh` for the classifier vocabulary. Override: `SKIP_HOOK_CLASSIFIER_CANARY=1`. Tier 0 test at `.claude/hooks/tests/hook-classifier-canary.test.sh` (10 tests).
+
+**V2 (deferred):** flip canary from ADVISORY to BLOCK once one calibration cycle passes with zero operator-reported false positives.
+
+**V3 (deferred to pre-commit sibling):** extend `pre-commit-gate.sh` to scan `git diff --staged --name-only` for new hooks and BLOCK when settings entry absent. Two-layer defense (author-time canary + commit-time gate) closes the class end-to-end.
+
+Defer V3 to a separate goal when V1.5+V2 have shipped through enough PRs that the failure modes are stable.
+
+## Override
+
+`SKIP_HOOK_WIRE_ON_AUTHOR=1 <command>` — logged via trace-helper. Use only when:
+
+- The hook is genuinely "in development" and ships without settings entry with a follow-on ticket filed AND the current PR cites the follow-on
+- Emergency rescue where adding the entry would break the harness
+
+INSTEAD of overriding for routine work: ship the settings entry in the same PR. The cost is small (one settings.json line); the discipline compounds across every adopter session.
+
+## Composes with
+
+- `.claude/rules/bootstrap-pair-discipline.md` — sister discipline (this rule extends the bootstrap-pair contract to hook + settings entry)
+- `.claude/rules/cold-adopter-harness-discipline.md` — sister discipline at adopter-observable boundary (settings.json IS adopter-observable)
+- `.claude/rules/blocked-items.md` — BLOCK protocol the V2 mechanical layer fires
+- `@luminary saltzer-schroeder` — complete mediation (the safety net is connected, not dead-letter)
+- `@luminary michael-nygard` — stability pattern (the settings entry is what makes the safety net real)
+- `@luminary linus-torvalds` — adopter-trust ceiling (bassclef hooks without settings entries equal adopter hooks without settings entries)
+
+## Distinct from
+
+- `.claude/rules/bootstrap-pair-discipline.md` — that rule covers any substrate building block + its pair; this rule covers the specific hook + settings entry case
+- `.claude/rules/testing-tier-config.md` — that rule covers Tier 0 strict TDD on the hook itself; this rule covers the settings entry beyond the test
+- `.claude/rules/cold-adopter-harness-discipline.md` — that rule covers adopter-observable changes broadly; this rule covers the hook-settings slice
+
+## Refs
+
+- bassclef-upstream#376 (parent — V1 ships this rule)
+- bassclef-upstream#319 (phase-1 closed; the sweep that surfaced the discipline gap)
+- bet `docs/iteration-bets/2026-06-26c-hook-wiring-phase-2.md` § WU-3 (this rule)
+- `.claude/rules/bootstrap-pair-discipline.md` (sister)
+- `@luminary saltzer-schroeder` + `@luminary michael-nygard` (anchors)
+
+## Retirement condition
+
+This rule retires only if bassclef migrates off hooks-as-substrate-primitives (very unlikely; hooks are the operational layer for substrate-discipline enforcement). The V2 mechanical extension may absorb the methodology check; the discipline at author time persists.

package/substrate/.claude/rules/iteration-bet-brief-completeness.md

@@ -0,0 +1,54 @@
+---
+tier: lite
+description: When Orchestrator (or any agent) delegates a Construction stack to a subagent (Builder, Designer, Architect), the brief MUST include, verbatim and with file paths, every artifact…
+---
+
+# Iteration Goal Brief Completeness
+
+When Orchestrator (or any agent) delegates a Construction stack to a
+subagent (Builder, Designer, Architect), the brief MUST include, verbatim
+and with file paths, every artifact the iteration goal cites that applies
+to the stack's scope.
+
+## Required in every delegation brief
+
+- Canvas (if scope touches a subsystem covered by the canvas)
+- Spec or decomposition artifact
+- **All prototypes** listed in the goal's References, scoped to which apply per surface
+- ADRs the goal pins as governing constraints
+- Design token file(s) if the scope touches token-governed surfaces
+- Prior PRs that shipped shared primitives the stack should reuse
+- Luminary map (primary pair + any extended pairs tagged to surfaces in scope)
+
+## Checkpoint before spawning the subagent
+
+Before the Task/Agent call, enumerate the goal's reference list and confirm
+each relevant entry is in the brief. Missing entries = re-brief before
+spawn. In sequential mode, same checkpoint applies to the role handoff
+within a single session.
+
+## Operator- vs orchestrator-gated
+
+- **Orchestrator-gated**: Orchestrator constructs the brief and validates
+  completeness before delegation. No operator prompt required.
+- **Operator-gated**: operator may shape or override, but the default is
+  full transmission. Partial briefs require explicit operator choice.
+
+## Why this rule exists
+
+POA iteration #499 (2026-04-12): bet cited an approved prototype under
+Reference artifacts. Orchestrator delegated Stack-1 (Review Queue UI) to
+Builder with decomposition + verbal density guidance but without the
+prototype path. Builder built against decomposition only → cramped UI
+shipped → rebuild required.
+
+The goal was correct. The delegation dropped information. Every bassclef
+repo using the iteration-bet pattern has this exposure.
+
+## Relationship to other rules
+
+- `artifact-ingestion.md` — Builder's obligation to read staged artifacts;
+  this rule is Orchestrator's reciprocal obligation to surface them
+- `design-direction.md` — approvals are load-bearing; bet references
+  carry the approvals and must reach Builder intact
+- `sdlc-gates.md` — pre-build gates; brief completeness is itself a gate

package/substrate/.claude/rules/lite-manifest-schema-change-discipline.md

@@ -9,7 +9,7 @@ Every change to `standards/lite-manifest.schema.json` (schema shape) or to the o
 
 This rule is the methodology layer. The mechanical layer is a pre-flight check in `scripts/release-to-bassclef.sh` (Step 3.6, added in goal 2026-09-07c Step 4). Both required.
 
-Sister discipline to `.claude/rules/file-rename-discipline.md`. Same shape at a different surface — files there, schema fields here.
+Sister discipline at the file-rename surface; same shape at a different surface — files there, schema fields here.
 
 ## Why this exists
 
@@ -68,7 +68,7 @@ INSTEAD of overriding for routine work: write the entry. The cost is small (one
 
 ## Composes with
 
-- `.claude/rules/file-rename-discipline.md` — sister at the file surface
+- file-rename-discipline (standard tier) — sister at the file surface
 - `.claude/rules/we-dont-break-adopters.md` — parent discipline (ADR-031)
 - `.claude/rules/cold-adopter-harness-discipline.md` — sibling smoke fires against ledger entries before release
 - `.claude/rules/bootstrap-pair-discipline.md` — this rule + hook + tests + settings wire ship together
@@ -90,7 +90,7 @@ INSTEAD of overriding for routine work: write the entry. The cost is small (one
 - Root cause: v0.36.0 upstream_commit removal broke 3 bassclef-web scripts (commit `c9a9da7` on bassclef-web repaired downstream)
 - Goal: `docs/iteration-bets/2026-09-07c-lite-manifest-schema-plus-extractor-plus-backfill-plus-ledger.md`
 - Risk ledger: `docs/risk-ledgers/2026-09-07c-lite-manifest-schema-extractor-backfill-ledger.md` Linus L6 + Hoare H6
-- Sister rule: `.claude/rules/file-rename-discipline.md`
+- Sister rule: file-rename-discipline (standard tier)
 - @luminary linus-torvalds — Torvalds's rule at the schema surface
 
 ## Retirement condition

package/substrate/.claude/rules/longrun-prep-plan-doc-compression.md

@@ -0,0 +1,89 @@
+---
+tier: lite
+description: When a plan doc at docs/next-session-plan-*.md (modified within 48 hours) carries a ## Recommended session sequence (or equivalent) section, /longrun prep MUST skip the full Steps…
+---
+
+# /longrun prep — compress when plan doc pre-picks scope
+
+When a plan doc at `docs/next-session-plan-*.md` (modified within 48 hours) carries a `## Recommended session sequence` (or equivalent) section, `/longrun prep` MUST skip the full Steps 1.4c-1.7b option-table ceremony and present the pre-authored sequence directly. This rule closes bassclef-upstream#1307 R1 — the workflow-overhead class where prep re-authors 15-25 turns of ceremony an earlier session already shipped in a plan doc.
+
+This rule is the methodology layer. The mechanism is the /longrun SKILL body Step 0.85 (bassclef-upstream#1307 R1). V2 Stop-hook enforcement is deferred per pre-mortem R5.
+
+## When this rule fires
+
+Every `/longrun prep` dispatch. The SKILL body Step 0.85 checks for a plan doc first. When one is found, the compressed prep path fires. When none matches, the full ceremony holds.
+
+Detection criteria (all three must match):
+
+1. File matching `docs/next-session-plan-*.md` exists at repo root
+2. File was modified within the last 48 hours (`find -mtime -2`)
+3. File body contains one of: `## Recommended session sequence`, `## Recommended sequence`, `## Next-session pickup`
+
+## What the compressed path requires
+
+When the compressed path fires, prep still ships the three-block opener per `.claude/rules/operator-facing-prose.md` Rule 3 (Problem + Value + Evidence). The compression targets Steps 1.4c-1.7b:
+
+- **Skip:** re-authoring the full 5-axis-per-option block for every option (SKILL Step 1.5)
+- **Skip:** re-authoring a full card for every non-recommended option (SKILL Step 1.6)
+- **Skip:** re-authoring step cards + per-step compounding blocks (SKILL Steps 1.7 + 1.7a) for options the plan doc did not recommend
+- **Keep:** scan-table at the top (3-5 rows summarizing the plan doc's items)
+- **Keep:** one card for the recommended item per SKILL Step 1.6
+- **Keep:** step cards + per-step compounding for the recommended item only per SKILL Steps 1.7 + 1.7a
+- **Keep:** recommendation sentence per SKILL Step 1.7b
+- **Add:** plan doc file path cited inline as source
+
+Operators still pick from the scan table. The plan doc's ranking becomes the default, not a mandate.
+
+## Anti-patterns
+
+**Full ceremony fires despite plan doc present.** The exact class #1307 R1 filed. Cure: run the SKILL Step 0.85 detection first.
+
+**Plan doc detection succeeds but prep still authors 5-axis blocks for every option.** Partial compression is not compression. Cure: skip the per-option 5-axis blocks; keep them only for the recommended item's card.
+
+**Compressed prep drops the recommendation sentence.** Operators still need one-line rationale. Cure: keep Step 1.7b.
+
+**Compressed prep skips the three-block opener.** Rule 3 discipline holds regardless of compression. Cure: Problem + Value + Evidence always land before scan-table.
+
+INSTEAD of any of these: check for plan doc first (SKILL Step 0.85 detection); use the recommended sequence verbatim; ask operator to confirm or reshape.
+
+## Override
+
+`SKIP_LONGRUN_COMPRESS=1 <command>` — logged via trace-helper. Use only when the plan doc is out of date and the operator wants a fresh option set. In that case, dispatch full ceremony and note the override reason in the prep opener.
+
+INSTEAD of overriding routinely: update the plan doc. A stale plan doc is a bad plan doc; fixing it upstream compounds across every future prep.
+
+## V2 mechanical layer (deferred)
+
+V1 ships this rule + SKILL body Step 0.85 amendment. V2 (deferred follow-on ticket) will add a Stop hook that:
+
+1. Detects `/longrun prep` output in the assistant's most recent message
+2. Detects presence of a fresh plan doc via `find -mtime -2`
+3. Checks whether the prep output carries 3+ per-option 5-axis blocks (evidence of full ceremony)
+4. Emits ADVISORY finding when full ceremony fires despite plan doc being present
+
+Defer V2 until this rule (V1 methodology) has shipped through 3-5 preps and the mechanical extension has stable heuristics.
+
+## Composes with
+
+- `.claude/skills/longrun/SKILL.md` Step 0.85 — the SKILL amendment this rule prescribes
+- `.claude/rules/operator-facing-prose.md` Rule 3 — three-block opener still fires under compression
+- `.claude/rules/compounding-sequence-fresh-analysis.md` — per-option 5-axis fresh analysis still holds for the recommended item's card
+- `.claude/rules/plan-enumeration-needs-value-props.md` — every option in the compressed scan-table still carries a value-prop cell
+- `.claude/rules/blocked-items.md` — silence is not deferral (plan doc detection reports fire vs skip explicitly)
+- `.claude/rules/bootstrap-pair-discipline.md` — this rule + SKILL amendment ship as paired bootstrap
+- @luminary john-ousterhout — deep module (compression path hides plan-doc detection behind narrow interface)
+- @luminary donald-norman — signifier + feedback (plan doc presence is a signifier; compressed vs full ceremony is user feedback)
+- @luminary frederick-brooks — conceptual integrity (compression preserves the option-table + card + step-card shape; only volume shrinks)
+
+## Refs
+
+- bassclef-upstream#1307 R1 — this rule's filing ticket
+- `docs/next-session-plan-2026-08-20.md` — the plan doc that motivated the R1 class filing
+- operator_recap_2026-08-19e L96 — evidence source (25-40t ceremony vs 5t needed)
+- `.claude/skills/longrun/SKILL.md` Step 0.85 — mechanism this rule prescribes
+
+## Retirement condition
+
+This rule retires only if `/longrun` stops accepting plan docs as pre-authored scope. Until then, the discipline of compressing prep against pre-authored sequences survives.
+
+Closes bassclef-upstream#1307 R1.

package/substrate/.claude/rules/loop-discipline.md

@@ -0,0 +1,81 @@
+---
+tier: lite
+description: Every step that ships code or substrate runs the six-step cycle for shipping code or substrate.
+---
+
+# /loop discipline — methodology layer
+
+Every step that ships code or substrate runs the six-step cycle below. This rule is the methodology layer; the full cycle spec lives with operator substrate.
+
+## When this rule fires
+
+The rule fires when an agent or operator opens a feature branch, commits, opens a PR, runs review, or merges. The discipline applies regardless of work scope — single-issue fix, multi-step /longrun, and substrate-defect filing all run the same six steps.
+
+## What the rule requires
+
+Before merging a PR that touches code or substrate, the agent has done all six main steps plus three sub-steps:
+
+0.5. `/pre-mortem` light fired (3 luminary lenses, 5-8 risks per lens, 30 min per Klein workshop shape) BEFORE Step 1 /temperance. Marker exists at `state/markers/pre-mortem/<branch-slug>.marker` citing the risk ledger path. Strongest concerns fold into the plan before edits begin. Per `.claude/skills/pre-mortem/SKILL.md` light mode.
+1. `/temperance` fired with answers stated (smallest shape, blast radius, brute-force check). Marker exists at `state/markers/temperance/<branch-slug>.marker`.
+2. `/luminary` picked at least one primary lens. Marker exists at `state/markers/luminary/<branch-slug>.marker`. Slugs recorded in the evidence row's `authoring_luminaries` field.
+2a. Marker declares `lead` field naming one primary luminary; `supporting` field lists the others. Lead is the luminary whose lens verifies the ship at Step 5.5. Format mirrors bet-doc frontmatter `authoring_luminaries.primary` and `.supporting`.
+3. Tier 0 strict TDD satisfied where the testing tier requires it. Tests pass. The `testing-tier-enforce` hook has not blocked the commit.
+4. Review run. Findings categorized as red, amber, green, note. CodeReviewer agent dispatched OR inline review with luminary lens applied.
+5. Red and amber findings resolved through one or more iterations. Iteration count recorded. When the change is a SKILL body rewrite (any file under `.claude/skills/*/SKILL.md`), the intent check is measurable — run `scripts/intent-drift-check.sh --skill <slug>`. Cosine at or above 0.90 versus the saved vector at `.claude/embeddings/skills/<slug>.json` passes. Cosine below threshold means intent drifted and the rewrite iterates or reverts. Subjective promise-list checks satisfy the step ONLY when no saved vector exists (new skill). Threshold raised from 0.85 to 0.90 per #790 (2026-07-19) after first-6-cures median landed at 0.987.
+5.5. Lead lens confirms all red and amber findings cleared before Step 6 merge. Marker exists at `state/markers/lead-lens-signoff/<branch-slug>.marker` naming the lead luminary and either "no findings" or the specific finding IDs cleared. Rubber-stamp sign-off is a discipline miss — sign-off must cite finding IDs or state "no findings" with rationale.
+6. PR body carries the structured evidence including the three markers from Steps 0.5, 2a, 5.5. Squash merge. Evidence row status flips to merged.
+
+Silence at any step is not deferral. Explicit deferral with stated rationale is the only acceptable skip.
+
+The three sub-steps (0.5 + 2a + 5.5) close the aggregate-GREEN balancing check gap named in #845 body Cure B. When every gate reports GREEN independently but the fix ships in the wrong shape, the missing signal is a balancing check — a lens that reads the aggregate and asks "does this actually solve the problem." The lead luminary IS the balancing check. Ships per #836.
+
+## What this rule does NOT require
+
+- A specific number of luminaries (one minimum; five maximum per `/luminary` skill ceiling).
+- A specific finding count (red and amber findings should exist; zero on every PR signals shallow review).
+- A specific iteration count (zero is acceptable when first review is clean).
+- The CodeReviewer agent specifically — inline review with luminary lens is acceptable for smaller scope.
+- A standalone evidence document. Tier 1 evidence rows live in PR body sections; tier 0 in standalone files. Both satisfy the rule.
+
+## Skip path with explicit deferral
+
+Some work skips part of the cycle by declaration:
+
+- **Trivial change** — typo, dependency bump, single-line rename. Commit message line `loop: skipped — trivial change, no review surface` records the skip.
+- **Documented emergency** — production incident with operator-approved bypass. PR body carries authorization.
+- **Operator direct merge** — operator authors the change and merges. The discipline applies to the agent work that surfaces it, not to the operator's edit.
+
+Silence is not skip. Default is run the cycle.
+
+## Composes with
+
+- `standards/construction-evidence-discipline.md` — the artifact produced per cycle
+- `.claude/rules/testing-tier-config.md` — step 3 enforcement
+- `.claude/rules/wu-sequencing-compounds.md` — sister discipline at the multi-step bet level
+- `.claude/rules/blocked-items.md` — the protocol for surfacing skipped steps that should have run
+- `.claude/skills/pre-mortem/SKILL.md` — Step 0.5 method; light mode shape (3 lenses, 30 min)
+- `.claude/luminaries/gary-klein.md` — Step 0.5 anchor (pre-mortem originator)
+
+## Mechanical enforcement
+
+V1 ships this rule + the standard. V2 (deferred) extends `pre-commit-gate.sh` to verify both markers exist for the branch before any commit, and adds a PR-open hook that verifies the evidence section is present in the PR body.
+
+Per memory `feedback_hooks_beat_methodology_for_substrate_quality`: V2 hook ships alongside the methodology — both required for the discipline to hold across context boundaries.
+
+## Override path
+
+`SKIP_LOOP_DISCIPLINE=1 <command>` — logged via trace-helper. Use only for migration scripts that author many goal docs at once, or for emergency rescue. Routine skip is not an override target; routine skip is a methodology miss.
+
+## Source dialogue
+
+2026-06-23 overnight bet 23a (discipline mechanization three disciplines). The loop was exercised on every step during the goal; this rule and the companion standard codify what the goal did.
+
+## Refs
+
+- goal doc `docs/iteration-bets/2026-06-23a-discipline-mechanization-three-disciplines.md` — the goal that ran the loop and proved the discipline
+- `.claude/luminaries/kent-beck.md` — primary lineage (red-green-refactor)
+- `.claude/luminaries/gary-klein.md` — Step 0.5 pre-mortem lineage
+- Memory `feedback_hooks_beat_methodology_for_substrate_quality` — pattern for V2 mechanical layer
+- Ticket 836 — parent filing (three sub-steps + hook extension)
+- Ticket 845 — Cure B (aggregate-GREEN balancing check) — Step 5.5 lead-lens sign-off ships that cure
+- Goal doc `docs/iteration-bets/2026-07-24a-ship-836-loop-discipline-extension.md` — ship vehicle for the three sub-steps

package/substrate/.claude/rules/manual-prod-approval.md

@@ -0,0 +1,100 @@
+---
+tier: lite
+globs: [".github/workflows/**/*.yml", ".github/workflows/**/*.yaml"]
+description: Prod deploys require GitHub Environments with required_reviewers — no exceptions
+---
+
+# Manual Prod Approval Rule
+
+Every app repo's production deploy MUST gate on GitHub Environments
+with `required_reviewers` configured. Auto-deploy-to-prod on any
+branch push is a rule violation.
+
+## Why
+
+`guardrails.md` already says: "Deploy to production without human
+approval — even in orchestrator-gated mode. This is the hardest
+guardrail. No exceptions."
+
+This rule specifies the **mechanism** for enforcement: GitHub's
+native Environments feature with reviewer requirements, not agent
+discipline. Agents can and will skip softer forms. Infrastructure-
+enforced gates cannot be skipped.
+
+## What satisfies the rule
+
+A deploy workflow with a job referencing a GitHub Environment that
+has `required_reviewers` configured:
+
+```yaml
+jobs:
+  deploy-prod:
+    environment:
+      name: prod   # ← this environment must exist in repo settings
+                   #   with required_reviewers set
+    steps:
+      - ... actual deploy steps
+```
+
+Repo settings at github.com/[owner]/[repo]/settings/environments
+must show:
+- Environment named `prod`
+- Deployment protection rules enabled
+- Required reviewers populated (at least one operator)
+
+## What violates the rule
+
+- `main` branch push auto-deploys to prod without Environment gating
+- Any workflow job deploying to prod without `environment:` field
+- Environment exists but has no required reviewers (empty list = auto-approved)
+- Reviewers are GitHub bots / service accounts (must be human identity)
+
+## Detection
+
+This rule fires when:
+- A new app repo is scaffolded by `/autonomous start` with
+  `deploy_targets.prod` set to a URL
+- `.github/workflows/deploy.yml` is added or modified
+- Pre-commit-gate hook detects workflow changes touching prod deploy steps
+
+## Enforcement
+
+- Pre-commit-gate hook surfaces a warning if deploy workflow
+  touches prod without Environment reference
+- `/substrate-check` skill validates Environment + reviewer configuration
+  when `deploy_targets.prod` is set
+- `/deploy-prod` skill refuses to run if Environment validation
+  fails
+
+## What agents do when rule is violated
+
+Fire BLOCKED: (per `blocked-items.md`):
+- `BLOCKED: prod deploy without approval gate — configure GitHub
+  Environment 'prod' with required_reviewers before proceeding`
+- Resolve (configure via `gh api` or UI) or explicit defer with
+  rationale. Silence is not deferral.
+
+## Setup commands (one-time per repo)
+
+```bash
+# Get your user ID
+USER_ID=$(gh api user --jq '.id')
+
+# Create prod environment with yourself as reviewer
+gh api repos/$OWNER/$REPO/environments/prod --method PUT -f "wait_timer=0" \
+  -f "deployment_branch_policy[protected_branches]=false" \
+  -f "deployment_branch_policy[custom_branch_policies]=true"
+
+# Add required reviewer
+gh api repos/$OWNER/$REPO/environments/prod \
+  --method PUT \
+  -F "reviewers[][type]=User" \
+  -F "reviewers[][id]=$USER_ID"
+```
+
+## Related
+
+- `.claude/rules/guardrails.md` — prod deploy human-approved
+- `standards/deployment-topology.md` — bassclef deploy pattern
+- `standards/substrate-config-schema.md` — `prod_approval_reviewers`
+  field convention

package/substrate/.claude/rules/marker-enrichment-discipline.md

@@ -0,0 +1,99 @@
+---
+tier: lite
+description: Gate marker files (under state/markers/temperance/, state/markers/luminary/, state/markers/arc-walk/, state/markers/orientation-gate/, state/markers/roadmap-reconcile-gate/) MUST…
+---
+
+# Marker Enrichment Discipline
+
+Gate marker files (under `state/markers/temperance/`, `state/markers/luminary/`, `state/markers/arc-walk/`, `state/markers/orientation-gate/`, `state/markers/roadmap-reconcile-gate/`) MUST carry body content within the same WU or PR that creates them. Touching a marker without body content satisfies the gate's existence check but leaves no audit trail — months later, a reader cannot recover the scope-decision, luminary lens, or thread context that the marker is supposed to record.
+
+This rule is the methodology layer. The mechanical layer is `pre-build-gate.sh` extended with a non-empty-body check on the 5 gate-marker classes (advisory in V1 per the allowlist baseline; BLOCK in V2 after the allowlist is empty).
+
+## Why this rule exists
+
+Bet 27c WU-11 surfaced "marker-enrichment-gap" as candidate substrate-defect 5. The gate hooks (`pre-build-gate.sh`) check marker file EXISTENCE only. An agent satisfies the gate by running `touch state/markers/temperance/<branch>.marker`. The marker exists; the gate clears; substantive work proceeds. Months later, a reader looking at the marker has zero evidence of what scope decision was made.
+
+Bet 27c shipped 13 PRs across the foundation work. Most markers in `state/markers/` are empty files from earlier sessions where the agent satisfied the gate without recording reasoning. The audit trail is missing.
+
+INSTEAD of writing empty markers to clear gates: the WU/PR that creates a marker writes its body content in the same change. Format conventions:
+
+- **Temperance marker** — date + branch + scope-decision (right-thing answer, right-way answer, drift trigger)
+- **Luminary marker** — date + branch + primary lens(es) + supporting lens(es) + one-line rationale per lens
+- **Arc-walk marker** — date + branch + parent_bet chain (recursive walk) + drivers consumed
+- **Orientation-gate marker** — date + branch + thread-level read completion notes
+- **Roadmap-reconcile-gate marker** — date + branch + reconcile result (no drift / drift detected / no roadmap declared)
+
+The bet 28a WU-0 prep + WU-1..5 markers ship as the exemplar pattern.
+
+## When this rule fires
+
+Any session creating a marker file in the 5 gate-marker directories:
+
+- `state/markers/temperance/`
+- `state/markers/luminary/`
+- `state/markers/arc-walk/`
+- `state/markers/orientation-gate/`
+- `state/markers/roadmap-reconcile-gate/`
+
+Does NOT fire on:
+
+- `state/markers/session-timing/` — transient timing data, machine-written
+- `state/markers/diagnose/` — fix-branch evidence (uses different format)
+- `state/markers/adr/` — ADR decision markers (different rule)
+- `state/markers/turn-prose-surface/` — kiss-surface flags (different rule)
+- Markers in the allowlist `state/markers/marker-enrichment-allowlist.txt` (grandfathered baseline; cleared over time)
+
+## What the rule requires
+
+When the step that creates a marker commits:
+
+1. Marker file exists at the expected path
+2. Marker file is non-empty (>0 bytes)
+3. Marker body contains the format conventions above (date + branch + decision-content; advisory check in V1, mechanical in V2)
+
+INSTEAD of `touch state/markers/temperance/<branch>.marker`: use heredoc to write the body inline:
+
+```bash
+cat > state/markers/temperance/<branch>.marker << 'EOF'
+# Temperance marker — <bet> <WU>
+- date: <ISO date>
+- branch: <branch>
+- scope-decision: <right-thing + right-way + drift-trigger>
+EOF
+```
+
+## Mechanical layer (V1 advisory)
+
+`pre-build-gate.sh` extended with `check_marker_non_empty()` function. Fires on existence check; if marker exists but is 0 bytes AND not in the allowlist, emits ADVISORY warning to stderr. Does NOT block in V1.
+
+V2 (deferred to follow-on goal): flip to BLOCK once the allowlist baseline is fully cleared (operator backfills over time).
+
+## Allowlist
+
+`.claude/hooks/marker-enrichment-allowlist.txt` lists existing empty markers as of bet 28a WU-5 land date. Entries grandfathered indefinitely. Operator backfills body content over time; when the allowlist is empty, V2 BLOCK flip becomes eligible.
+
+## Override
+
+`SKIP_MARKER_ENRICHMENT=1 <command>` — for one-shot migration scripts that bootstrap markers from external state. Logged via trace-helper.
+
+INSTEAD of overriding for routine work: write the body. The cost is seconds; the audit trail compounds across every future session reading the marker.
+
+## Composes with
+
+- `.claude/rules/sdlc-gates.md` — temperance + diagnose gate firing semantics
+- `.claude/rules/blocked-items.md` — BLOCK protocol (V2 will use this)
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD on the hook + tests
+- `.claude/rules/mechanism-fidelity.md` — sister mechanical-enforcement discipline
+- `.claude/hooks/pre-build-gate.sh` — the mechanical implementation
+- `@luminary michael-feathers` — characterization tests as cure; existing empty markers are legacy; cure by enriching as touched
+
+## Refs
+
+- bet `docs/iteration-bets/2026-06-28a-mechanism-fidelity-cures-proposal.md` (WU-5)
+- bet 27c WU-11 (substrate-defect candidate 5 identification)
+- Closes bassclef-upstream#438
+- Closes part of bassclef-upstream#440
+
+## Retirement condition
+
+This rule retires only if the gate-marker primitive itself retires. Body-content conventions may evolve; the discipline of marker-as-audit-trail persists.