@thebassclef/lite 0.1.0 → 0.1.3

package/substrate/standards/frontmatter-schema.md

@@ -0,0 +1,154 @@
+---
+tier: lite
+description: Schema for the YAML frontmatter that opens substrate files — .claude/skills/<name>/SKILL.md and .claude/rules/<name>.md.
+---
+
+# Frontmatter Schema
+
+Schema for the YAML frontmatter that opens substrate files — `.claude/skills/<name>/SKILL.md` and `.claude/rules/<name>.md`. Validated by `.claude/hooks/substrate-clarity-gate.sh` on Edit / Write (bassclef#862 Gap 1; WU-3 of bet 2026-06-18a).
+
+Without write-time validation, `tech_stack_match:` declarations from WU-8 + WU-9, future `composes_with:` + `depends_on:` declarations from WU-15, and ordinary skill description fields ship with typos or missing required fields and only surface in adopter sessions. This schema closes the gap at the authoring surface.
+
+## When the hook fires
+
+On any Edit / Write to:
+
+- `.claude/skills/<name>/SKILL.md`
+- `.claude/rules/<name>.md`
+
+Other substrate surfaces (luminaries, chronicles, iteration goals, decompositions, journal entries) keep their existing validation rules and do not gain frontmatter-schema enforcement in WU-3.
+
+## What the hook validates
+
+Three checks fire in order. The first to fail returns the exit code; further checks do not run.
+
+| Check | Outcome | Exit |
+|---|---|---|
+| Frontmatter present at top of file (starts with `---`) | Required for files NOT on allowlist; missing → BLOCK | 2 |
+| YAML parses cleanly | Malformed YAML → BLOCK | 2 |
+| Required fields present + non-empty | Missing required → BLOCK | 2 |
+| All field names are recognized | Unknown field → WARN; written to stderr | 0 |
+
+The hook continues running existing checks (description length, INSTEAD-block, jargon ladder) after the schema pass.
+
+## Skill schema
+
+Frontmatter required for every `.claude/skills/<name>/SKILL.md`.
+
+**Required fields:**
+
+- `name` — the skill's slash-command alias. Lowercase, hyphens, no spaces.
+- `description` — operator-readable one-liner. Length + verb-first + plain-language checks per `.claude/rules/skill-description-clarity.md`.
+
+**Recognized optional fields:**
+
+| Field | Used by | Type |
+|---|---|---|
+| `args` | skill body (operator-visible args reference) | string |
+| `authoring_luminaries` | skills that declare which luminary lenses shaped their design; picked via `/extract-intent` Voyage matching or `/pick-luminaries` | object (primary: list, supporting: list) |
+| `composes_baseline` | `/launch`, `/riff-prototypes`, `/frontend-design`, `/visual-review` | list[string] (luminary slugs) |
+| `composes_with` | future — WU-15 (bassclef#862 Gap 3) | list[string] (skill slugs) |
+| `depends_on` | future — WU-15 (bassclef#862 Gap 3) | list[string] (skill slugs) |
+| `deprecated` | retirement metadata | bool |
+| `deprecated_decision` | retirement metadata | string |
+| `deprecated_in_favor_of` | retirement metadata | string |
+| `disable_friction_check` | `/promote`-skip discipline | bool |
+| `disable_model_invocation` | Claude Code harness routing | bool |
+| `maturity` | skills declaring lifecycle stage — `alpha`, `beta`, `stable`, `hardened` per ADR-043 | string |
+| `model_tier` | per-agent LLM tier routing | string |
+| `modes` | mode-bearing skills (e.g., `/longrun`) | list[string] |
+| `no_user_modes` | mode-bearing-skill opt-out | bool |
+| `prereqs` | runtime prerequisites — richer shape per bassclef-web#94 | object (see prereqs schema below) |
+| `requires` | runtime prerequisites — older simpler shape | object (cli + network) |
+| `reserved_name_override` | reserved-name-shadow allow path | string |
+| `sizes` | size-bearing skills (e.g., `/value-prop`) | list[string] |
+| `tech_stack_match` | future — stack-bound skills | object |
+| `tiers` | tier-bearing skills (e.g., `/shape`) | list[string] |
+| `user_invocable` | Claude Code harness routing | bool |
+
+Unknown fields surface as WARN — adopter-authored fields might appear here; the warning surfaces the new field but does not block.
+
+## Prereqs schema (bassclef-web#94)
+
+The `prereqs:` block splits runtime prerequisites into required + optional buckets so docs sites can render a signifier per bucket. Skills without a `prereqs:` block still work — docs render a generic "check the skill body" fallback.
+
+```yaml
+prereqs:
+  required:
+    cli: [git, gh]
+    env: [ANTHROPIC_API_KEY]
+    network: true
+  optional:
+    cli: [jq]
+    env: [VOYAGE_API_KEY]
+    note: "VOYAGE_API_KEY enables semantic ranking; grep-only fallback works without."
+```
+
+Design rules per ticket:
+
+- Optional. Skills without the block still work.
+- 4-8 lines typical; 12 lines max. Docs sites render as a collapsed `<details>` block by default (progressive disclosure per Cooper).
+- Uses tool names adopters already know — `git`, `gh`, `python3`, `jq`, `curl`. No bassclef vocabulary.
+- Zero prereqs beyond "you have Claude Code running" — skip the block entirely.
+
+Relationship to `requires:`:
+
+- `requires:` is the older simpler shape (cli + network only). Existing skills that use it keep working.
+- `prereqs:` is the newer richer shape (required / optional split + env vars + note). Preferred for new lite skills.
+- No migration required. Both fields are recognized. Adopters pick per skill.
+
+Docs render logic is out of scope for bassclef — docs sites (Fumadocs or similar) read the manifest and render the signifier block. Bassclef's job is to define the schema and apply it as an exemplar.
+
+## Rule schema
+
+Frontmatter is OPTIONAL for `.claude/rules/<name>.md`. Many existing rules carry no frontmatter and start with the body directly. When frontmatter IS present, it must conform.
+
+**Required fields (when frontmatter is present):**
+
+- `description` — one-line operator-readable description of what the rule enforces.
+
+**Recognized optional fields:**
+
+| Field | Used by | Type |
+|---|---|---|
+| `composes_with` | future — WU-15 (bassclef#862 Gap 3) | list[string] |
+| `depends_on` | future — WU-15 (bassclef#862 Gap 3) | list[string] |
+| `globs` | rule-routing (which file paths the rule applies to) | list[string] |
+| `model_tier` | per-rule LLM tier routing | string |
+| `tech_stack_match` | per-stack rule routing (WU-8 + WU-9; future Phase 2 work) | object — admits `lang`, `frontend`, `backend`, `orm`, `pkg_manager`, `deploy` per `standards/tech-stack-config.md` |
+
+Unknown fields surface as WARN.
+
+Rules with NO frontmatter pass through validation entirely (the schema applies only when frontmatter is present). Authors adding frontmatter to legacy rules pick the required + optional fields as appropriate.
+
+## Allowlist baseline
+
+`.claude/hooks/substrate-frontmatter-allowlist.txt` grandfathers files that fail validation today with a 60-day grace window. Same shape as `testing-tier-enforce-allowlist.txt` per bassclef#1037.
+
+Format: `<repo-relative-path>|<grace-until ISO 8601>`.
+
+At WU-3 ship, the allowlist is empty — current files (75 skills + 19 rules with frontmatter + 33 rules without) all pass. The file ships with its header explaining the shape so future violators can be added with grace if/when they surface.
+
+## What this schema does NOT do
+
+- Does not enforce field VALUE shape beyond presence + non-empty. `tech_stack_match` content is not validated against the `tech-stack.schema.json` ranges shipped in WU-2. That richer validation lives in the consumer-side hooks that USE the field (future Phase 3 work).
+- Does not require frontmatter on legacy rules without one. 33 rules ship with no frontmatter today; the schema applies only when frontmatter IS present.
+- Does not validate luminary, chronicle, iteration-bet, decomposition, or journal-entry frontmatter. Those surfaces have their own checks in the same hook.
+- Does not catch description-quality issues — that's the existing `.claude/rules/skill-description-clarity.md` rule.
+
+## Override path
+
+`SKIP_SUBSTRATE_CLARITY=1` — same env var as the rest of the hook's checks. Logged via trace-helper. Use sparingly.
+
+## Refs
+
+- bassclef#862 Gap 1 — this schema closes it.
+- bassclef#382 — substrate-clarity-gate hook (parent of this validation pass).
+- WU-3 of bet `docs/iteration-bets/2026-06-18a-public-adopter-leverage-longrun.md` — ships the validation.
+- Sister WU-15 (bassclef#862 Gap 3) — adds `composes_with` + `depends_on` field schemas + targets-exist validation.
+- Pairs with `standards/tech-stack-config.md` (WU-2) — tech_stack_match values map to that schema's enums.
+- Sister discipline: `.claude/rules/testing-tier-config.md` (bassclef#1037) — allowlist baseline pattern.
+
+## Retirement condition
+
+This schema retires only if bassclef migrates off YAML frontmatter as a substrate convention. Field set evolves as new substrate fields ship (e.g., WU-15 introduces composes_with + depends_on into the recognized set).

package/substrate/standards/hook-injection-discipline.md

@@ -0,0 +1,202 @@
+---
+tier: lite
+status: live
+date: 2026-06-27
+authority: ADR-035
+references:
+  - {type: adr, id: ADR-035, anchor: hooks as steering surfaces}
+  - {type: rule, id: .claude/rules/cold-adopter-harness-discipline.md, anchor: per-PR harness gate}
+  - {type: rule, id: .claude/rules/testing-tier-config.md, anchor: Tier 0 strict-TDD on .claude/hooks/*.sh}
+  - {type: rule, id: .claude/rules/bootstrap-pair-discipline.md, anchor: hook ships with paired test + settings entry}
+  - {type: standard, id: standards/hook-install-class.md, anchor: install-class header pairs with this discipline}
+  - {type: standard, id: standards/mechanism-fidelity.md, anchor: audit verifies injection hooks fire correctly}
+  - {type: external, id: code.claude.com/docs/en/hooks, anchor: hook event taxonomy as of 2026-06-27}
+luminaries:
+  primary: [hyrum-wright, tony-hoare]
+  supporting: [john-ousterhout, kent-beck, michael-nygard]
+description: - ADR-035 (just shipped, 8632d15) — 9-surface hook taxonomy + block-vs-inject menu; this standard names the contract for the inject side - code.claude.com/docs/en/hooks (WebFetch 2026-06-27) — additionalContext injection JSON shape; 10K char limit…
+---
+
+# Hook injection discipline
+
+> **Anthropic docs reference:** Cites code.claude.com/docs/en/hooks as of 2026-06-27. Hook events and capabilities evolve. Before authoring a new injection hook, verify the event taxonomy and `additionalContext` capability against the current docs. The 10,000-character limit + JSON envelope shape + per-event injection support documented here may shift in future Claude Code releases.
+
+## Sources read
+
+- ADR-035 (just shipped, `8632d15`) — 9-surface hook taxonomy + block-vs-inject menu; this standard names the contract for the inject side
+- `code.claude.com/docs/en/hooks` (WebFetch 2026-06-27) — `additionalContext` injection JSON shape; 10K char limit; six events that support injection
+- `.claude/hooks/turn-prose-kiss-check.sh` (existing pattern) — example of a Stop hook that emits stderr (block) but does not yet inject `additionalContext`
+- `.claude/hooks/pr-body-scrub-check.sh` (sibling pattern) — example of structured stderr + exit code 2
+- `standards/bash-hook-safety.md` (sibling standard) — seven defensive disciplines for bash hooks
+
+## What this standard covers
+
+The contract for hooks that **inject context** into Claude's working memory rather than **block** a tool call. Six of nine Anthropic hook events accept an `additionalContext` field that becomes a system reminder attached to the agent's next turn. Bassclef has used hooks mostly as blockers; this standard names the contract for the other shape.
+
+Companion standards:
+- `standards/hook-install-class.md` — every hook declares whether it installs operator-class (`$HOME`) or project-class (`$CLAUDE_PROJECT_DIR`); injection hooks honor the declaration
+- `standards/mechanism-fidelity.md` — the audit method that verifies an injection hook actually fires + produces observable effect
+- `standards/bash-hook-safety.md` — seven defensive bash disciplines that injection hooks follow
+
+## When to inject vs block
+
+Per ADR-035 decision menu:
+
+| Discipline shape | Output mechanism | Hook event |
+|---|---|---|
+| **Refuse** the tool call (the gate must have authority) | `exit 2` | PreToolUse (also Stop for post-write rewrite) |
+| **Steer** the agent (rule sits at recency edge of context) | `additionalContext` injection | UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolBatch, Stop, SubagentStop, SessionStart |
+| **Verify** the hook works | Tier 0 strict-TDD per `testing-tier-config.md` | n/a — applies to all hook types |
+| **End-to-end test** the hook's stated effect | cold-adopter harness check class | n/a — applies to all hook types |
+
+Pick block when the gate's job is to refuse. Pick inject when the gate's job is to remind, prime, or shape the next generation step. Use both when both apply (block + inject in the same hook).
+
+## JSON envelope contract
+
+Every injection hook returns valid JSON on stdout with this shape:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "<EventName>",
+    "additionalContext": "<text that becomes a system reminder>"
+  }
+}
+```
+
+Event-specific fields (per Anthropic docs):
+
+| Event | Additional fields allowed |
+|---|---|
+| `SessionStart` | `sessionTitle`, `initialUserMessage`, `watchPaths`, `reloadSkills` |
+| `UserPromptSubmit` | `decision: "block"`, `reason` |
+| `UserPromptExpansion` | `decision: "block"`, `reason` |
+| `PreToolUse` | `permissionDecision`, `permissionDecisionReason`, `updatedInput` |
+| `PostToolUse` | `updatedToolOutput`, `decision: "block"` |
+| `PostToolBatch` | `decision: "block"` |
+| `Stop` | `decision: "block"` (the special pattern that lets the rewrite turn continue) |
+| `SubagentStop` | `decision: "block"` |
+
+When in doubt, verify against the latest Anthropic docs. The verify-latest header at the top of this standard names the reference.
+
+## 10,000-character rule
+
+`additionalContext` is capped at 10,000 characters by Anthropic. Excess is saved to file with a preview shown to the agent. For a hook that injects a wordlist + reminder text, this is ample (a 30-term wordlist + per-term gloss + 2-3 sentences of framing typically lands under 2,000 chars).
+
+If a hook's intended injection exceeds the cap, restructure rather than truncate — either inject the index + write the full content to a file the agent can Read, OR split across multiple injection surfaces (SessionStart for full wordlist; UserPromptSubmit for compressed reminder).
+
+## Marker-driven injection
+
+When a hook should fire injection only on specific surfaces (e.g., turn-prose check only on /longrun-dispatched surfaces), it reads a marker file from `state/markers/<surface-type>/<surface-name>.marker`. Marker presence = the surface applies; marker absence = pass-through silently.
+
+Two marker conventions:
+
+- **Persistent markers** (per session or across sessions) — committed to git. Examples: `state/markers/temperance/`, `state/markers/luminary/`, `state/markers/arc-walk/`, `state/markers/adr/`, `state/markers/reviewer/`. These form audit trail.
+- **Transient markers** (per turn or per surface, expire after the hook reads) — gitignored. Examples: `state/markers/turn-prose-surface/`. These signal the NEXT hook firing only and must not persist in committed state. Persisting them breaks tests that assume clean repo state (see bet 2026-06-27c WU-1 chronicle for the live failure example).
+
+Per `standards/hook-install-class.md`, the marker location is consistent across install classes: hooks read from `$CLAUDE_PROJECT_DIR/state/markers/` if the dir exists, falling back to `$HOME/state/markers/` for operator-class hooks.
+
+## Fail-soft contract
+
+Every injection hook fails soft on missing prerequisites. Order of fallback (per ADR-035 Class A cure pattern):
+
+1. Read project-relative path (`$CLAUDE_PROJECT_DIR/<resource>`) — preferred
+2. Read env-var override (`$<HOOK_PREFIX>_<RESOURCE>` — e.g., `KISS_STANDARDS_FILE`)
+3. Read user-level path (`$HOME/.claude/<resource>`) — operator-class fallback
+4. Use inline defaults — last resort
+
+If all four fail, the hook still exits 0 (silent pass) but emits a structured stderr message describing the fallback chain that failed. Adopters running the cold-adopter harness see the stderr in the harness output; the harness check class catches silent fallbacks per `standards/mechanism-fidelity.md`.
+
+The shared helper library `lib/hook-inject.sh` (lands in WU-3 of bet 2026-06-27c) implements this fallback chain so individual hooks call `resolve_<resource>_path` rather than repeating the logic.
+
+## Tier 0 testing requirement
+
+Per `.claude/rules/testing-tier-config.md`, every hook in `.claude/hooks/*.sh` lands Tier 0 strict TDD. For injection hooks specifically, the test asserts:
+
+1. **JSON output validity** — stdout parses as JSON
+2. **Event name correctness** — `hookSpecificOutput.hookEventName` matches the wired event
+3. **Injection content presence** — `additionalContext` non-empty when expected
+4. **Fail-soft behavior** — missing inputs produce exit 0 + structured stderr (not exit 2)
+5. **Both install classes** — test runs under project-class install layout AND operator-class install layout (per `standards/hook-install-class.md`)
+6. **10,000-char ceiling** — injection content does not exceed the cap
+
+The cold-adopter harness `hook-end-to-end-smoke` check class (lands in WU-5 of bet 2026-06-27c) re-runs steps 1-5 in adopter-shaped fixtures so the contract holds end-to-end.
+
+## Worked example
+
+A hypothetical UserPromptSubmit hook that injects the BLOCK wordlist on every operator turn (the cure pattern for bassclef-upstream#1027 / #1051):
+
+```bash
+#!/bin/bash
+# tier: standard
+# install-class: dual
+# user-prompt-submit-kiss-prime.sh — inject BLOCK wordlist as additionalContext
+set -euo pipefail
+
+# Source the shared helper
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/_lib/hook-inject.sh" 2>/dev/null \
+  || source "${CLAUDE_PROJECT_DIR:-}/lib/hook-inject.sh" 2>/dev/null \
+  || { echo "lib/hook-inject.sh missing" >&2; exit 0; }
+
+# Resolve wordlist path (project → env → user → inline defaults)
+WORDLIST=$(resolve_standards_path "bassclef-internal-jargon.md") || exit 0
+
+# Build the injection
+TERMS=$(extract_block_terms "$WORDLIST")
+INJECTION="REMINDER: scan your draft against these BLOCK terms before posting:
+${TERMS}
+Substitute per the grade-10 plain-English table. Reserved-name allowlist: substrate, bassclef, cameo, Studio, Band, bandleader."
+
+# Emit the JSON envelope (10K char-safe; structured stderr on failure)
+emit_additional_context "UserPromptSubmit" "$INJECTION"
+exit 0
+```
+
+Tier 0 test asserts the hook produces valid JSON envelope + non-empty `additionalContext` + exit 0 under both install layouts.
+
+## Anti-patterns
+
+### Inject when you should block
+
+If a discipline genuinely requires refusing the action (e.g., destructive-command-guard), inject is wrong. The agent reads the injection and can still proceed. INSTEAD use PreToolUse exit 2.
+
+### Block when you should inject
+
+If a discipline benefits from steering the agent's generation rather than refusing the action (e.g., remind about the wordlist before the agent drafts a PR body), block is wrong — the agent sees the block AFTER drafting; the draft is already in transcript. INSTEAD use UserPromptSubmit injection so the rule sits at the recency edge BEFORE generation.
+
+### Read project resources via SCRIPT_DIR/../.. under operator-class install
+
+Per the Class A cure pattern (`turn-prose-kiss-check.sh` live failure example), a hook authored with project-relative reads but wired at `$HOME` resolves paths to `~/standards/` (nonexistent). INSTEAD use `lib/hook-inject.sh`'s resolve-helpers which honor declared install-class.
+
+### Inject without test
+
+A hook that injects but has no Tier 0 test isn't verified to produce its claimed effect. Per ADR-035 substrate-as-system tenet, this is legacy code. INSTEAD: ship the Tier 0 test in the same PR as the hook.
+
+### Persist a transient marker
+
+Committing a `state/markers/turn-prose-surface/*.marker` to git makes the hook see a marker that should expire per-turn. Tests that check "no marker → no advisory" break. INSTEAD: per the gitignore convention in `.gitignore`, transient marker directories are excluded.
+
+## Composes with
+
+- `standards/hook-install-class.md` — every injection hook declares install-class header; `lib/hook-inject.sh` honors it
+- `standards/mechanism-fidelity.md` — audit verifies injection hooks fire + produce observable effect
+- `standards/bash-hook-safety.md` — seven defensive bash disciplines that injection hooks follow
+- `standards/cold-adopter-harness.md` — `hook-end-to-end-smoke` check class re-verifies injection contract
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD on `.claude/hooks/*.sh`
+- `.claude/rules/bootstrap-pair-discipline.md` — every hook ships with paired test + settings.json entry
+- `.claude/rules/blocked-items.md` — protocol when an injection hook surfaces a `BLOCKED:` condition
+
+## Refs
+
+- ADR-035 — hooks-as-steering-surfaces decision
+- bassclef-upstream#417 — umbrella tracking for bet 2026-06-27c
+- bassclef-upstream#1027 / #1051 / #1304 — prior lineage of turn-prose-kiss-check (Class B steering layer)
+- `code.claude.com/docs/en/hooks` — Anthropic hook reference
+- Michael Nygard — *Release It!* (stability patterns; fail-soft framing)
+- Tony Hoare — pre/postcondition contract programming
+- Hyrum Wright — Hyrum's Law (observable behavior becomes contract)
+
+## Retirement condition
+
+This standard retires only if Claude Code's hook event surface changes shape enough that `additionalContext` is no longer the injection mechanism. The verify-latest header is the cue: every reader checks the Anthropic reference before authoring; if the surface has shifted, the standard amends or supersedes.

package/substrate/standards/hook-install-class.md

@@ -0,0 +1,215 @@
+---
+tier: lite
+status: live
+date: 2026-06-27
+authority: ADR-035
+references:
+  - {type: adr, id: ADR-035, anchor: substrate-as-system tenet + hooks as steering surfaces}
+  - {type: adr, id: ADR-032, anchor: adopter sync dispatcher architecture}
+  - {type: adr, id: ADR-034, anchor: operator-class two-stage bootstrap}
+  - {type: standard, id: standards/hook-injection-discipline.md, anchor: injection hooks honor install-class}
+  - {type: standard, id: standards/cold-adopter-harness.md, anchor: harness verifies install-class matches actual wiring}
+  - {type: rule, id: .claude/rules/bootstrap-pair-discipline.md, anchor: new hook ships with install-class declaration}
+  - {type: rule, id: .claude/rules/cold-adopter-harness-discipline.md, anchor: per-PR harness gate}
+luminaries:
+  primary: [john-ousterhout, linus-torvalds]
+  supporting: [hyrum-wright, frederick-brooks]
+description: "- ADR-035 — names the install-class declaration as a foundational invariant (# install-class: operator | project | dual header) - ADR-032 — adopter sync dispatcher architecture (operator-class hooks wired at $HOME; project-class hooks wired at…"
+---
+
+# Hook install class
+
+> **Anthropic docs reference:** This standard does not depend on a specific Anthropic surface — it is a bassclef convention layered over the Claude Code hook system. The convention applies regardless of future Claude Code hook event additions.
+
+## Sources read
+
+- ADR-035 — names the install-class declaration as a foundational invariant (`# install-class: operator | project | dual` header)
+- ADR-032 — adopter sync dispatcher architecture (operator-class hooks wired at `$HOME`; project-class hooks wired at `$CLAUDE_PROJECT_DIR`)
+- ADR-034 — extends ADR-032 to operator's own machine; both hook types now exist
+- `.claude/hooks/turn-prose-kiss-check.sh` — the live Class A failure: code reads `$SCRIPT_DIR/../..` (project-relative); wiring at `$HOME` (operator-class); paths resolve to nonexistent locations
+- `presence/install/bassclef-sync.template.sh` — the install template that copies hooks; will read install-class headers to decide where each goes
+- `scripts/cold-adopter-harness-sync.sh` — runs structural checks today; will gain `hook-path-resolution-under-install-class` check class in WU-5
+
+## What this standard covers
+
+Every hook in `.claude/hooks/*.sh` declares its install class via a header line:
+
+```bash
+# install-class: operator | project | dual
+```
+
+The install class tells the install template (`presence/install/bassclef-sync.template.sh`) where to install the hook + tells the hook's code which path resolution layout to use + tells the cold-adopter harness which install layout to verify against.
+
+This standard exists because the 2026-06-27 /diagnose of `turn-prose-kiss-check.sh` surfaced the Class A failure: hook authored project-relative reads but wired operator-class. Declared install-class makes the mismatch a declarative property the harness can verify rather than a latent bug.
+
+## Install classes
+
+### `operator`
+
+The hook lives at `$HOME/.claude/hooks/<name>.sh` and is invoked by the operator's user-level Claude Code settings. Examples (current):
+
+- `bassclef-sync.sh` — adopter sync engine; operator runs it; updates ride to adopters via the install template
+- `session-end.sh` — session lifecycle; operator-scope
+- `bug-diagnosis.sh` — diagnosis trigger; operator-scope
+- `tool-failure-diagnosis.sh` — failure trigger; operator-scope
+- `deploy-guard.sh` — deploy gate; operator-scope
+- `memory-write-audit.sh` — memory write trigger; operator-scope
+
+Operator-class hooks resolve project resources via the fallback chain (per `standards/hook-injection-discipline.md` fail-soft contract):
+1. `$CLAUDE_PROJECT_DIR/<resource>` — when the active session has a project
+2. Env-var override
+3. `$HOME/.claude/<resource>` — operator-scope fallback
+4. Inline defaults
+
+Operator-class hooks MUST NOT read via `$SCRIPT_DIR/../../<project-resource>` because under `$HOME` install layout, that resolves to `~/<project-resource>` (nonexistent).
+
+### `project`
+
+The hook lives at `$CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh` and is invoked by the project's `.claude/settings.json`. Examples (current):
+
+- `artifact-ingestion-gate.sh` — fires on Edit/Write of generative artifacts in the project
+- `atomic-pr-check.sh` — fires on `git push` for this project
+- `bet-doc-gate.sh` — fires on Edit/Write of `docs/iteration-bets/*.md`
+- `destructive-command-guard.sh` — fires on Bash for destructive commands
+- `pre-build-gate.sh` — fires on Edit/Write before first edit per branch
+- `pre-commit-gate.sh` — fires on Bash matching git commit
+- `pre-gh-pr-body-scrub.sh` — fires on Bash matching gh pr create
+- `pre-gh-pr-title-scrub.sh` — fires on same
+- `pre-git-commit-msg-scrub.sh` — fires on git commit messages
+- `reviewer-dispatch-check.sh` — fires at Stop event
+- `session-reflection.sh` — fires at SessionStart for the project
+- `state-validate.sh` — fires on Edit/Write of state-spine entities
+- `temperance-gate.sh` — fires per-branch
+- `testing-tier-enforce.sh` — fires on Edit/Write of substrate-internal paths
+
+Project-class hooks can use `$SCRIPT_DIR/../..` to reach project resources because under `$CLAUDE_PROJECT_DIR` install layout, that resolves correctly to the project root.
+
+### `dual`
+
+The hook works correctly under both install classes. Either:
+- Code uses `lib/hook-inject.sh` resolve-helpers (preferred — always works regardless of install layout)
+- Code reads only its own directory + env-var overrides + inline defaults (no project-resource reads)
+
+Examples that should be `dual`:
+- `turn-prose-kiss-check.sh` — needs to fire at Stop for operator-class scenarios (Stop is session-level) AND for project-class scenarios (cure work in follow-on goal)
+- Future injection hooks that ship to adopters
+
+## Header convention
+
+Position: top of file, after the shebang + tier declaration, before the description.
+
+```bash
+#!/bin/bash
+# tier: standard
+# install-class: dual
+# <one-line description>
+#
+# <rest of header comment>
+```
+
+The header is parseable by simple grep:
+
+```bash
+INSTALL_CLASS=$(grep -m1 '^# install-class:' .claude/hooks/<name>.sh | sed 's/^# install-class: *//')
+```
+
+If the header is missing, the hook is treated as `project` (current default).
+
+## Install template enforcement
+
+The install template (`presence/install/bassclef-sync.template.sh`) reads the install-class header at sync time. For each hook in the source tree:
+
+| Declared install-class | Action |
+|---|---|
+| `operator` | Copy to `$HOME/.claude/hooks/<name>.sh`. Refuse to copy into `$CLAUDE_PROJECT_DIR/.claude/hooks/`. |
+| `project` | Refuse to copy into `$HOME/.claude/hooks/`. Project-class hooks land via bassclef-sync's project file resolution, not via copy. |
+| `dual` | Copy to `$HOME` AND make available under `$CLAUDE_PROJECT_DIR`. |
+| `missing` | Treat as `project` (backwards-compatible default). |
+
+This enforcement closes the failure mode where an operator-class hook copy + project-relative reads produce silent fallbacks.
+
+(The actual template amendment lands in a follow-on goal; the standard documents the contract now so future authors honor it from the start.)
+
+## Cold-adopter harness verification
+
+The cold-adopter harness check class `hook-path-resolution-under-install-class` (lands in WU-5 of bet 2026-06-27c) verifies that declared install-class matches actual behavior. Per hook:
+
+1. Read declared install-class from header
+2. Install the hook fresh under the declared layout (operator-class → `$HOME`; project-class → `$CLAUDE_PROJECT_DIR`; dual → both)
+3. Run the hook against a fixture trigger
+4. Assert all path resolutions succeed (no `falls back to defaults` warnings in stderr)
+5. Fail the check if any path lookup misses
+
+This is the mechanical layer that catches future instances of the Class A failure at PR time.
+
+## Worked example
+
+### Operator-class hook (existing)
+
+```bash
+#!/bin/bash
+# tier: standard
+# install-class: operator
+# bassclef-sync.sh — adopter sync engine; invoked by user-level Claude Code settings.
+# ...
+```
+
+### Project-class hook (existing)
+
+```bash
+#!/bin/bash
+# tier: standard
+# install-class: project
+# bet-doc-gate.sh — PreToolUse Edit/Write on docs/iteration-bets/*.md.
+# Fires arc-walk + produces/consumes checks per goal doc discipline.
+# ...
+```
+
+### Dual hook (the cure for turn-prose-kiss-check.sh in follow-on goal)
+
+```bash
+#!/bin/bash
+# tier: standard
+# install-class: dual
+# turn-prose-kiss-check.sh — Stop hook that scans assistant prose against
+# BLOCK wordlist. Uses lib/hook-inject.sh resolve-helpers so path resolution
+# works under both operator-class wiring at $HOME and project-class wiring
+# at $CLAUDE_PROJECT_DIR.
+# ...
+```
+
+## Anti-patterns
+
+### Author project-relative reads + wire operator-class
+
+The Class A failure pattern from bet 2026-06-27c /diagnose. INSTEAD: declare `# install-class: dual` + use `lib/hook-inject.sh` resolve-helpers.
+
+### Decline to declare install-class
+
+A hook without the header defaults to `project` and the install template refuses to copy it to `$HOME`. INSTEAD: pick `operator` / `project` / `dual` deliberately at author time.
+
+### Mix install-class with hard-coded `$HOME` or `$CLAUDE_PROJECT_DIR` references
+
+Defeats the abstraction. INSTEAD: source `lib/hook-inject.sh` + call its resolve-helpers; the helpers do the install-class-aware lookup.
+
+## Composes with
+
+- `standards/hook-injection-discipline.md` — injection hooks honor install-class via the fallback chain
+- `standards/cold-adopter-harness.md` (standard tier) — `hook-path-resolution-under-install-class` check class verifies declared header matches actual behavior
+- `presence/install/bassclef-sync.template.sh` — install template reads the header to decide install path
+- `.claude/rules/bootstrap-pair-discipline.md` — new hook ships with install-class header in its bootstrap pair
+- `.claude/rules/cold-adopter-harness-discipline.md` — per-PR harness gate runs the verification
+
+## Refs
+
+- ADR-035 — names install-class as a foundational invariant
+- ADR-032 — adopter sync dispatcher architecture (operator-class vs project-class distinction)
+- ADR-034 — operator-class two-stage bootstrap (where the operator-class hooks fold in)
+- bassclef-upstream#417 — umbrella tracking for bet 2026-06-27c
+- `architecture/audits/2026-06-27-mechanism-fidelity.md` (lands in WU-6) — first audit run will classify each hook by install-class + flag Class A mismatches
+- @luminary john-ousterhout — deep modules: declared install-class is the small interface that hides path-resolution complexity
+- @luminary linus-torvalds — we-don't-break-adopters: install-class declaration prevents a hook from silently breaking under adopter install layout
+
+## Retirement condition
+
+This standard retires only if bassclef stops distinguishing operator-class vs project-class hooks. The `dual` class may become the default if all future hooks are authored to use `lib/hook-inject.sh` resolve-helpers from the start, but the discipline of declaring install-class persists as audit trail.