@thebassclef/lite 0.1.0 → 0.1.3

package/substrate/.claude/skills/whats-the-plan/SKILL.md

@@ -0,0 +1,202 @@
+---
+tier: lite
+name: whats-the-plan
+description: "Declare the chain of skills you intend to run for the current task or next stretch of work. Invokable at any natural response point. Composes with /temperance (scope) and /sprint (ticket-level) \u2014 dispatch-path level."
+problem: "Multi-skill chains dispatch without declaring the plan. Operator can't audit mid-flight."
+value: "Declares the chain of skills you intend to run. Invokable before you start."
+inputs: [Current task or scope description]
+outputs: [Ordered skill chain, Rationale per step, Alternative chains]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# What's the Plan
+
+Declare the sequence of skills, tool calls, and artifacts you intend
+to produce for the current task. Stated **before** execution, not
+retrospectively. Re-declared when the plan changes materially.
+
+## When to Invoke
+
+- **Operator asks**: "what's the plan?", "how are you going to tackle this?", "show me the chain"
+- **Operator types**: `/whats-the-plan`
+- **Self-invoke** (before a non-trivial chain): when the next stretch of
+  work involves ≥3 skills OR touches production code OR spans ≥1 hour.
+  This is the analogue of `/temperance` firing on the first edit — but
+  for sequencing, not scope
+- **Plan change mid-task**: when a skill output forces a swap (new
+  interface surfaces, test fails, operator redirects) — re-declare
+  with a `was → now` delta
+
+## What this skill is NOT
+
+| Skill | Operates at | Time | Output |
+|-------|-------------|------|--------|
+| `/sprint` | Ticket/scope level | Session start | Issues + time budget + iteration name |
+| `/temperance` | Approach/scope | Before edit | Right-thing + right-way questions |
+| `/whats-the-plan` | **Dispatch path** | **Any natural response point** | **Ordered skill chain + swap-points** |
+| `/chronicle` | Narrative | Session end | Retrospective log |
+
+The four compose. A typical session:
+
+```
+/sprint             → "next: finish iteration X, ~60 turns"
+/temperance         → "building Y; right thing because Z; simplest path is W"
+/whats-the-plan     → "chain: /decompose → build → /verify → commit"
+[execute]
+/chronicle          → "what happened, decisions, open threads"
+```
+
+## Procedure
+
+### 1. Read inputs
+
+Before declaring, know:
+
+- **Current task** — the thing operator just asked for, or the next
+  scope in the active iteration goal
+- **Active iteration goal** — `docs/iteration-bets/` (latest) — governs
+  what's in-scope and what stop-points exist
+- **Applicable gates** — any of: `/temperance`, `/diagnose`, `/verify`,
+  `/visual-review`, `/decompose` (per `sdlc-gates.md` and
+  `oo-ad-entry-point.md`)
+- **Relevant rules** — `artifact-ingestion.md` dictates sources-read
+  block; `design-direction.md` dictates approval-respect; other rules
+  may insert steps (e.g., `prototype-workflow.md` inserts render +
+  confirm before commit for prototype edits)
+
+### 2. Enumerate the chain
+
+List skills, tool calls, and artifact writes in execution order. Use
+`→` between steps. Group by phase if the chain crosses phases.
+
+### 3. Name swap-points
+
+A swap-point is a conditional fork: "if skill X produces finding Y,
+insert skill Z before the next step." Swap-points are where the plan
+may branch based on outputs you don't have yet.
+
+List the top 2–3 swap-points the chain is sensitive to. More than 3
+signals the chain is under-specified and needs shaping first.
+
+### 4. State stop conditions
+
+Where does this chain end? Options:
+- **Operator review point** — "stop before PR open"
+- **Gate** — "stop at /verify output; commit blocks on green"
+- **Natural boundary** — "one WS complete; next WS is separate chain"
+- **Time budget limit** — "stop at 20 turns; re-shape if incomplete"
+
+### 5. State what's NOT in this chain
+
+Adjacent work you're deliberately excluding. This is the sequencing
+analogue of `/temperance`'s "what you're NOT doing" question.
+
+## Output format
+
+```
+## Plan (YYYY-MM-DD HH:MM UTC)
+
+**Task**: [one-line description]
+**Iteration**: [goal name, or "none — ad-hoc"]
+
+**Chain**:
+1. /temperance — gate scope + approach
+2. /decompose — identify interfaces (if Construction)
+3. [build step] — edit [paths]
+4. /verify — match change type to verification
+5. commit — conventional message
+
+**Swap-points**:
+- If /decompose surfaces new cross-cutting concern → insert /pattern-review before build
+- If /verify fails visual → insert /visual-review before commit
+- If operator redirects scope → re-run /whats-the-plan with delta
+
+**Stops at**: [operator review point / gate / natural boundary]
+**Appetite**: ~N turns, ~M min
+**Not in this chain**: [adjacent work excluded]
+```
+
+## Re-declare format
+
+When the plan changes materially mid-task, emit a delta (not a full
+re-print). Material change = new skill inserted, skill removed, or
+stop-point moved. Trivial reordering within the declared chain does
+not trigger re-declare.
+
+```
+## Plan update (YYYY-MM-DD HH:MM UTC)
+
+**Was**:  /temperance → /decompose → build → /verify → commit
+**Now**:  /temperance → /decompose → /pattern-review → build → /verify → /visual-review → commit
+
+**Why**: /decompose surfaced [specific interface] — triggers
+/pattern-review swap-point. /verify scope now includes UI, pulling
+/visual-review in per post-build gate.
+```
+
+## Rules
+
+- **Declare before execute**, not after. A plan declared after the
+  chain ran is a log entry, not a plan.
+- **One plan per coherent task**, not one per turn. Multi-turn
+  execution under a single declared plan is the common case.
+- **Re-declare on material change only**, not on every adjustment.
+  Chain chatter reduces the signal.
+- **Plan must reference sources** (per `artifact-ingestion.md`) if the
+  chain involves producing a canvas, spec, ADR, or prototype. The
+  plan itself is a lightweight produce-ahead-of-execution artifact.
+- **Skill chain steps presented to operator MUST follow
+  `.claude/rules/plan-enumeration-needs-value-props.md`** — each step
+  in the chain carries a tweet (claim + why-it-matters), not a bare
+  skill name. Bare "/temperance → /diagnose → /verify" is not a plan;
+  each step needs to say what it buys.
+- **Do not declare a plan you know you won't follow**. If the chain is
+  genuinely uncertain, say so: "Plan unclear; running /temperance +
+  /diagnose first to shape." That is itself a valid plan.
+
+## Chronicle integration
+
+When the session chronicle is written, the main-task plan declaration
+SHOULD be linked or quoted. Plan → execution → reference-back is the
+loop that makes plan declaration load-bearing rather than theatrical.
+
+If the plan changed during execution, chronicle notes the delta
+(which swap-points fired, which didn't).
+
+## Operator-facing behavior
+
+When operator types `/whats-the-plan`:
+- If a plan was declared recently (same task, no material change):
+  re-display the current plan
+- If no plan exists or task has shifted: run the procedure and declare
+- If operator asks "what's the plan?" in conversation: same procedure,
+  slight framing adjustment — phrase as response, not bassclef output
+  block, but include the chain + swap-points + stops-at
+
+## Relationship to other rules
+
+- `sdlc-gates.md` — declared plan must include gate skills where
+  applicable; hook-enforced gates are not optional plan steps
+- `artifact-ingestion.md` — plans that will produce generative output
+  must name sources the chain will read
+- `design-direction.md` — plan changes after operator approval require
+  operator reconciliation, not agent-unilateral re-planning
+- `oo-ad-entry-point.md` — Construction chains that edit `src/` must
+  include `/decompose` or explicit trivial-work deferral
+- `iteration-goal-brief-completeness.md` — plans delegated to subagents
+  are briefs; this skill outputs the brief
+
+## Enforcement
+
+V1: methodology-level. Operator invokes or Claude self-invokes based
+on the triggers above.
+
+V2 (future): rule `plan-declaration-required.md` + hook that fires
+BLOCKED when a ≥3-skill chain executes without a preceding
+`/whats-the-plan` output in session. Not in v1 scope — shipping the
+skill first lets us learn where auto-fire helps vs. spams.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/.claude/skills/whereami/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: whereami
-description: "Show project state in one glance — phase, active goal, agents in flight, subsystem progress, gate checklist, freshness. Reads docs/whereami.md. Run at session start before /sprint to orient."
+description: "Show project state in one glance \u2014 phase, active goal, agents in flight, subsystem progress, gate checklist, freshness. Reads docs/whereami.md. Run at session start before /sprint to orient."
 problem: "Project state lives across whereami and iteration goals and chronicles and git. No single-glance view."
 value: "Phase and active goal and agents in flight and gate progress \u2014 one page."
 inputs: [Optional freshness flag]
@@ -41,7 +41,7 @@ Four skills, four altitudes:
 | `/whereami` | Project state | Phase + goal + agents + freshness |
 | `/sprint` | Ticket / scope | Open issues + proposed sprint |
 | `/whats-the-plan` | Dispatch path | Ordered skill chain |
-| `/substrate-check` | Wiring | PASS / WARN / FAIL on symlinks + hooks + CLIs |
+| `/substrate-check` | Wiring | PASS / WARN / FAIL on files + hooks + CLIs |
 
 Session-start order: `/whereami`, then `/sprint`, then `/whats-the-plan`, then execute.
 

package/substrate/CONTRIBUTING.md

@@ -40,7 +40,7 @@ Not sure which surface fits? The `/skill` skill runs a taxonomy gate (skill / ru
 
 ### Operator-private vs adopter-facing
 
-The `docs/operator-private/` directory in your clone contains only a README placeholder. That's intentional — operator-private substrate (internal deliberation, strategy notes) lives in a separate private repo. Contributors don't need to populate or interact with it. See [`standards/operator-private-discipline.md`](standards/operator-private-discipline.md) and [`standards/operator-to-public-flow.md`](standards/operator-to-public-flow.md) for the discipline.
+The `docs/operator-private/` directory in your clone contains only a README placeholder. That's intentional — operator-private substrate (internal deliberation, strategy notes) lives in a separate private repo. Contributors don't need to populate or interact with it. The discipline: strategy artifacts stay private; only reference substrate (rules, hooks, standards) ships to the public bassclef repo.
 
 If you're the bassclef maintainer (operator), `scripts/operator-setup.sh` sets up the symlink workflow when the private repo is cloned at the expected sibling location. The script is idempotent + a no-op for adopter clones; adopters can ignore it.
 

package/substrate/README.md

@@ -19,7 +19,7 @@ It is not a product. It is not a SaaS. It's a public framework, Apache 2.0: clon
 
 ## Who this is for
 
-**Solo system / app / portfolio operators.** The person running multiple software projects in parallel — apps, internal systems, side bets, family operations — around a day job, around family, around the other things that don't pause. Real deadlines, real stakes, no headcount. Other audiences may benefit; this is the one SENTINEL_bassclef_commits to. The full audience commitment lives at [audience commitment](https://github.com/sunj-labs/bassclef/blob/main/strategy/personas/audience-commitment.md).
+**Solo system / app / portfolio operators.** The person running multiple software projects in parallel — apps, internal systems, side bets, family operations — around a day job, around family, around the other things that don't pause. Real deadlines, real stakes, no headcount. Other audiences may benefit; this is the one SENTINEL_bassclef_commits to.
 
 ## Why this exists
 
@@ -38,7 +38,7 @@ The acceptance test for v1 wasn't a demo — it was a live ticket from my parent
 
 Not theoretical. Bassclef runs today across eight repos in active use:
 
-- **A private sibling repo for strategy notes** — canvases, audits, and locked decisions. The pattern adopters can replicate per [`standards/operator-private-discipline.md`](https://github.com/sunj-labs/bassclef/blob/main/standards/operator-private-discipline.md).
+- **A private sibling repo for strategy notes** — canvases, audits, and locked decisions. Adopters replicate the pattern with a separate private repo cloned alongside their bassclef checkout.
 - **Seven application repos in daily use** — from a power-of-attorney tracker for my family to a collaborative travel planner to a recipe database. Each one is code I use myself, not a demo.
 
 The pattern: build the apps on the go, each repo's friction feeds back into bassclef as evolution tickets, the substrate hardens with every shipped feature.
@@ -165,9 +165,9 @@ Bassclef is markdown + bash + git. If you can read a file and run a script, you
 - [Skills catalog](https://github.com/sunj-labs/bassclef/blob/main/docs/skills-catalog.md) · [Hooks catalog](https://github.com/sunj-labs/bassclef/blob/main/docs/hooks-catalog.md) · [Rules catalog](https://github.com/sunj-labs/bassclef/blob/main/docs/rules-catalog.md) — substrate catalogs
 - [Context engineering framing](https://github.com/sunj-labs/bassclef/blob/main/design/bassclef-as-context-engineering.md) — substrate-truth framing
 - [Context engineering rule](https://github.com/sunj-labs/bassclef/blob/main/.claude/rules/context-engineering.md) — the foundational rule
-- [Agent choreography](https://github.com/sunj-labs/bassclef/blob/main/strategy/agent-choreography.md) — multi-agent operational guide
-- [whereami](https://github.com/sunj-labs/bassclef/blob/main/docs/whereami.md) — current project state
+- Agent choreography — multi-agent operational guide (operator substrate)
+- whereami — current project state (operator substrate)
 
 ## Operator-private substrate
 
-The `docs/operator-private/` directory contains only a README placeholder in adopter clones. Operator-private substrate (internal deliberation, strategy notes) lives separately. See [operator-private discipline](https://github.com/sunj-labs/bassclef/blob/main/standards/operator-private-discipline.md).
+The `docs/operator-private/` directory contains only a README placeholder in adopter clones. Operator-private substrate (internal deliberation, strategy notes) lives in a separate private repo cloned alongside bassclef.

package/substrate/lib/prose-scan-boundary.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# lib/prose-scan-boundary.sh
+#
+# Deep module per @luminary john-ousterhout — narrow interface hides
+# the boundary detection and counter file work behind 3 functions.
+#
+# Purpose — every prose scan hook (kiss, appositive, citation)
+# strips fenced or echoed content BEFORE it scans, and writes counter
+# state that plain-english-steering.sh injects into the next prompt.
+#
+# This closes #1443 canonical case — Stop side prose hooks that fire
+# on verbatim BLOCKED banner echoes at session start plus operator
+# picked shorthand labels. 5 rewrite cycles in 20 turns documented
+# the cost during 2026-09-09b prep.
+#
+# Anchor luminaries:
+#   @luminary john-ousterhout — deep module hiding the boundary work
+#   @luminary donald-norman — feedback loop through the counter markers
+#   @luminary tony-hoare — pre and postcondition on each function
+#   @luminary michael-feathers — characterization tests pin behavior
+#
+# Consumers source this lib:
+#   source lib/prose-scan-boundary.sh
+#
+# Tests: lib/tests/prose-scan-boundary.test.sh (Tier 0 strict TDD)
+
+# =========================================================================
+# strip_scan_boundaries — remove content the scan should not read
+# =========================================================================
+# Interface: IProseScanBoundary (Larman)
+# Inputs:  $1 = message text
+# Outputs: stdout — message with fenced or echoed content removed
+# Exit:    0 always
+#
+# Removes:
+#   1. BLOCKED banner blocks (session-start hook echoes; agent cannot rewrite)
+#   2. <!--SCAN_SKIP-->...<!--/SCAN_SKIP--> explicit fence markers
+#   3. Fenced code blocks (``` ... ```)
+#   4. Inline code (`...`)
+strip_scan_boundaries() {
+  local message_text="$1"
+  [ -z "$message_text" ] && return 0
+  # Python does the heavy lifting for regex-safe multiline strip.
+  # Fall back to raw text when python3 missing (fail-soft per Nygard).
+  if command -v python3 >/dev/null 2>&1; then
+    printf '%s' "$message_text" | python3 -c '
+import sys
+import re
+
+text = sys.stdin.read()
+
+# 1. Strip BLOCKED banner blocks. Banner shape:
+#    🛑🛑🛑 BLOCKED 🛑🛑🛑
+#    ────────────
+#    content
+#    ────────────
+#    ACTION: resolve OR ...
+#    Silence is not deferral. ...
+#
+# Match the banner line and content until one of:
+#   - "Silence is not deferral" line followed by newline (canonical end)
+#   - Two consecutive newlines (paragraph break)
+#   - Next banner line
+#   - End of string
+text = re.sub(
+    r"\U0001F6D1\U0001F6D1\U0001F6D1 BLOCKED \U0001F6D1\U0001F6D1\U0001F6D1"
+    r".*?"
+    r"(?:Silence is not deferral\.[^\n]*\n"
+    r"|\n\n(?=\S|\n|$)"
+    r"|(?=\U0001F6D1\U0001F6D1\U0001F6D1)"
+    r"|$)",
+    "",
+    text,
+    flags=re.DOTALL,
+)
+
+# 2. Strip explicit SCAN_SKIP fences
+text = re.sub(
+    r"<!--SCAN_SKIP-->.*?<!--/SCAN_SKIP-->",
+    "",
+    text,
+    flags=re.DOTALL,
+)
+
+# 3. Strip fenced code blocks
+text = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
+
+# 4. Strip inline code
+text = re.sub(r"`[^`]+`", "", text)
+
+sys.stdout.write(text)
+'
+  else
+    # No python — return raw text so consumers still work
+    printf '%s' "$message_text"
+  fi
+  return 0
+}
+
+# =========================================================================
+# write_prose_counter — persist a per-turn counter for the steering hook
+# =========================================================================
+# Interface: IProseCounterWriter (Larman)
+# Inputs:  $1 = counter name (e.g. "kiss_hits", "appositive_hits")
+#          $2 = numeric count
+#          $3 = optional JSON payload (findings, offenders, etc.)
+# Outputs: writes state/markers/turn-prose-counters/<name>.json atomically
+# Exit:    0 always (fail-soft on write error per Nygard)
+write_prose_counter() {
+  local name="$1"
+  local count="$2"
+  local payload="${3:-{\}}"
+  [ -z "$name" ] && return 0
+  [ -z "$count" ] && count=0
+  local repo_root
+  repo_root="$(_prose_scan_repo_root)"
+  local dir="${repo_root}/state/markers/turn-prose-counters"
+  local out_file="${dir}/${name}.json"
+  mkdir -p "$dir" 2>/dev/null || return 0
+  local ts
+  ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "unknown")"
+  # Atomic write via tmp + mv
+  local tmp
+  tmp="$(mktemp "${dir}/.${name}.XXXXXX")" || return 0
+  cat > "$tmp" <<JSON
+{
+  "counter": "${name}",
+  "count": ${count},
+  "updated_at": "${ts}",
+  "payload": ${payload}
+}
+JSON
+  mv "$tmp" "$out_file" 2>/dev/null || rm -f "$tmp"
+  return 0
+}
+
+# =========================================================================
+# read_prose_counter — read a per-turn counter for prompt injection
+# =========================================================================
+# Interface: IProseCounterReader (Larman)
+# Inputs:  $1 = counter name
+# Outputs: stdout — JSON content, or empty when marker missing
+# Exit:    0 always (fail-soft per Nygard)
+read_prose_counter() {
+  local name="$1"
+  [ -z "$name" ] && return 0
+  local repo_root
+  repo_root="$(_prose_scan_repo_root)"
+  local marker="${repo_root}/state/markers/turn-prose-counters/${name}.json"
+  [ -f "$marker" ] || return 0
+  cat "$marker" 2>/dev/null || true
+  return 0
+}
+
+# =========================================================================
+# _prose_scan_repo_root — resolve repo root under both install classes
+# =========================================================================
+# Internal helper. Prefer $CLAUDE_PROJECT_DIR (project install), fall
+# back to lib file's parent (operator install). Per install-class: dual
+# discipline from ADR-035 substrate-as-system tenet.
+_prose_scan_repo_root() {
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+    echo "${CLAUDE_PROJECT_DIR}"
+    return 0
+  fi
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  cd "${script_dir}/.." && pwd
+}

package/substrate/lib/tier-check.sh

@@ -14,7 +14,7 @@
 #
 # Rules governed by:
 # - .claude/rules/testing-tier-config.md (Tier 0 strict TDD)
-# - .claude/rules/mechanism-fidelity.md (interface honored end to end)
+# - mechanism-fidelity rule (standard tier; interface honored end to end)
 #
 # Anchor luminaries: ousterhout (deep module), feathers (probe pin behavior)
 
@@ -117,6 +117,55 @@ except Exception:
 PYEOF
 }
 
+# resolve_file_tier <path>
+#
+# Read a file's tier tag and print it to stdout. Returns empty string if
+# no tag is present. Supported shapes:
+#   - .md         — YAML frontmatter `tier:` field between --- markers
+#   - .sh, .py    — `# tier:` header line in first 10 lines
+#   - .yml, .yaml — `# tier:` comment OR top-level `tier:` field in first 30 lines
+#   - .json       — root-key `"tier"` or `"_tier"` in first 30 lines
+#   - .jsonc      — `// tier:` comment or root-key
+#   - .txt        — first-line `# tier:` convention
+#
+# Mirrors detection shape from .claude/hooks/tier-tag-required-at-write.sh so
+# the reader half and the writer half stay consistent.
+resolve_file_tier() {
+  local path="$1"
+  if [ ! -f "$path" ]; then
+    return 0
+  fi
+
+  local tier=""
+  case "$path" in
+    *.md)
+      # Frontmatter between --- markers, first 30 lines
+      tier=$(awk '
+        /^---/ { in_fm = !in_fm; if (!in_fm) exit; next }
+        in_fm && /^tier:[[:space:]]/ { sub(/^tier:[[:space:]]*/, ""); sub(/[[:space:]]*$/, ""); print; exit }
+        NR > 30 { exit }
+      ' "$path" 2>/dev/null)
+      ;;
+    *.sh|*.py)
+      tier=$(head -10 "$path" 2>/dev/null | grep -E '^#[[:space:]]*tier:[[:space:]]' | head -1 | sed -E 's/^#[[:space:]]*tier:[[:space:]]*//; s/[[:space:]]*$//')
+      ;;
+    *.yml|*.yaml)
+      tier=$(head -30 "$path" 2>/dev/null | grep -E '^#[[:space:]]*tier:[[:space:]]|^tier:[[:space:]]' | head -1 | sed -E 's/^#?[[:space:]]*tier:[[:space:]]*//; s/[[:space:]]*$//')
+      ;;
+    *.json|*.jsonc)
+      tier=$(head -30 "$path" 2>/dev/null | grep -oE '"(_?tier)"[[:space:]]*:[[:space:]]*"[a-z]+"' | head -1 | sed -E 's/.*:[[:space:]]*"([a-z]+)"/\1/')
+      if [ -z "$tier" ]; then
+        tier=$(head -30 "$path" 2>/dev/null | grep -oE '//[[:space:]]*tier:[[:space:]]*[a-z]+' | head -1 | sed -E 's/.*tier:[[:space:]]*//')
+      fi
+      ;;
+    *.txt)
+      tier=$(head -1 "$path" 2>/dev/null | grep -E '^#[[:space:]]*tier:[[:space:]]' | sed -E 's/^#[[:space:]]*tier:[[:space:]]*//; s/[[:space:]]*$//')
+      ;;
+  esac
+
+  echo "$tier"
+}
+
 # tier_at_least <required> [current]
 #
 # Returns 0 if current tier >= required, 1 otherwise.

package/substrate/lib/tier-dependency-audit.sh

@@ -859,11 +859,24 @@ walk_graph_bfs_inbound() {
 compute_kind_coverage() {
   local walk_file="$1"
   local tier="$2"
-  # Enumerate all known REFERENCE_KINDS (plus schema_ref extension)
-  local known_kinds=("composes_with" "source_lib" "additional_directories" \
-    "bash_scripts" "luminary_ref" "standards_ref" "rules_ref" "schema_ref")
+  # Derive known kinds from REFERENCE_KINDS at run time so new
+  # extractor rows automatically appear in coverage. Pre-fix this
+  # list was hardcoded and drifted from REFERENCE_KINDS — hook_ref
+  # existed as a walked kind but was missing from coverage output
+  # (bug 1 per docs/audits/2026-09-10-tier-graph-walk-miss.md).
+  # schema_ref is not in REFERENCE_KINDS but has its own extractor
+  # per _extract_schema_ref; keep it as a static append so schema
+  # coverage still emits.
+  local known_kinds=()
+  local entry name
+  for entry in "${REFERENCE_KINDS[@]}"; do
+    name="${entry%%|*}"
+    known_kinds+=("$name")
+  done
+  known_kinds+=("schema_ref")
+  local kind count
   for kind in "${known_kinds[@]}"; do
-    local count=0
+    count=0
     if [ -s "$walk_file" ]; then
       count="$(awk -F'\t' -v k="$kind" '$1 == k { c++ } END { print c+0 }' "$walk_file")"
     fi
@@ -931,3 +944,145 @@ read_intended_source_1_extended() {
   if [ -n "$out" ]; then echo "$out"; fi
   return 0
 }
+
+# ---------------------------------------------------------------------------
+# G5 extension (goal 2026-09-09b): per-edge tier alignment check
+# Ships in PR-2 alongside Bug 1 fix for coverage reporter. Closes the
+# gap Shape e was designed to catch — SKILL body references to hooks
+# tagged at higher tier than the SKILL itself (broken adopter promise
+# per @luminary linus-torvalds and ADR-043 D1 concentric inclusion).
+# ---------------------------------------------------------------------------
+
+# _tier_rank_full — full 5-tier rank map per ADR-043 D1
+# lite < standard < standard-pro < ultra < upstream
+# Rank 0 for unknown or missing tier (treated as neutral).
+_tier_rank_full() {
+  case "$1" in
+    lite) echo 1 ;;
+    standard) echo 2 ;;
+    standard-pro) echo 3 ;;
+    ultra) echo 4 ;;
+    upstream) echo 5 ;;
+    *) echo 0 ;;
+  esac
+}
+
+# _read_file_tier — extract tier tag from a file
+# Mirrors scripts/release-to-bassclef.sh:read_tier per standards/tier-tag-schema.md
+# Returns tier name on stdout; empty when no tag present.
+_read_file_tier() {
+  local f="$1"
+  [ -f "$f" ] || return 0
+  case "$f" in
+    *.md)
+      awk '
+        BEGIN{infm=0}
+        NR==1 && /^---/ {infm=1; next}
+        infm && /^---/ {exit}
+        infm && /^tier:[[:space:]]/ {sub(/^tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}
+      ' "$f"
+      ;;
+    *.sh|*.py)
+      head -5 "$f" | awk '/^# tier:[[:space:]]/ {sub(/^# tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}'
+      ;;
+    *.yml|*.yaml)
+      head -5 "$f" | awk '
+        /^---/ {next}
+        /^# tier:[[:space:]]/ {sub(/^# tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}
+        /^tier:[[:space:]]/ {sub(/^tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}
+      '
+      ;;
+    *.jsonc)
+      head -5 "$f" | awk '/^\/\/ tier:[[:space:]]/ {sub(/^\/\/ tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}'
+      ;;
+    *.json)
+      head -5 "$f" | awk '
+        /"tier":[[:space:]]*"[^"]+"/ {
+          match($0, /"tier":[[:space:]]*"[^"]+"/); s=substr($0, RSTART, RLENGTH);
+          gsub(/"tier":[[:space:]]*"/, "", s); gsub(/"$/, "", s);
+          print s; exit
+        }
+        /"_tier":[[:space:]]*"[^"]+"/ {
+          match($0, /"_tier":[[:space:]]*"[^"]+"/); s=substr($0, RSTART, RLENGTH);
+          gsub(/"_tier":[[:space:]]*"/, "", s); gsub(/"$/, "", s);
+          print s; exit
+        }
+      '
+      ;;
+    *) : ;;
+  esac
+}
+
+# check_tier_alignment_on_edges — per-edge tier alignment check
+# Interface: ITierAlignmentChecker (per Larman GRASP naming)
+# Inputs:  $1 = walk-with-kinds.tsv path (rows: <kind>\t<from>\t<to>)
+#          $2 = target tier (e.g. "lite")
+#          $3 = optional out-file for violation report (default: stdout)
+# Outputs: writes violations as "<kind>\t<from>\t<from-tier>\t<to>\t<to-tier>"
+# Exit:    0 always. Count of violations on final stderr line.
+# Rule:    ADR-043 D1 concentric inclusion — source tier T guarantees
+#          target tier <= T. When source has target tier AND target
+#          file has HIGHER tier rank, source's tier promise breaks.
+check_tier_alignment_on_edges() {
+  local walk_file="$1"
+  local target_tier="$2"
+  local out_file="${3:-/dev/stdout}"
+  [ -f "$walk_file" ] || { echo "check_tier_alignment_on_edges: walk file missing at $walk_file" >&2; return 1; }
+  local target_rank
+  target_rank="$(_tier_rank_full "$target_tier")"
+  [ "$target_rank" = "0" ] && { echo "check_tier_alignment_on_edges: unknown target tier '$target_tier'" >&2; return 1; }
+  # Optimization: cache tiers per unique file. Then use awk with an
+  # associative array for O(1) lookup during edge walk. Prior shape
+  # ran awk per edge lookup = O(edges * cache) ~ 10M ops on lite tier.
+  # Initialize local var so `set -u` callers do not trip on the trap
+  # when mktemp fails or the local declaration races against the trap.
+  local tier_cache=""
+  tier_cache="$(mktemp)" || tier_cache="/tmp/tier_cache_fallback_$$"
+  # shellcheck disable=SC2064
+  trap "rm -f '${tier_cache}'" RETURN
+  # First pass: collect unique files then read tier per file (bash loop).
+  local file tier
+  while IFS= read -r file; do
+    [ -n "$file" ] || continue
+    tier="$(_read_file_tier "$file" 2>/dev/null || true)"
+    printf "%s\t%s\n" "$file" "${tier:-none}"
+  done < <(awk -F'\t' '{print $2; print $3}' "$walk_file" | sort -u) > "$tier_cache"
+  # Second pass: awk-side associative array; single sweep of walk_file.
+  local violations
+  violations="$(awk -F'\t' \
+    -v target="$target_tier" \
+    -v target_rank="$target_rank" \
+    -v out="$out_file" \
+    -v cache="$tier_cache" '
+    BEGIN {
+      # Preload rank map
+      rank["lite"] = 1; rank["standard"] = 2; rank["standard-pro"] = 3;
+      rank["ultra"] = 4; rank["upstream"] = 5;
+      # Preload tier cache
+      while ((getline line < cache) > 0) {
+        n = split(line, parts, "\t")
+        if (n >= 2) tier_of[parts[1]] = parts[2]
+      }
+      close(cache)
+      v = 0
+      # Truncate out file
+      printf "" > out
+    }
+    {
+      kind = $1; from = $2; to = $3
+      if (kind == "" || from == "" || to == "") next
+      ft = tier_of[from]
+      tt = tier_of[to]
+      if (ft != target) next
+      tr = rank[tt] + 0
+      if (tr == 0) next
+      if (tr > target_rank) {
+        print kind "\t" from "\t" ft "\t" to "\t" tt >> out
+        v++
+      }
+    }
+    END { print v }
+  ' "$walk_file")"
+  echo "check_tier_alignment_on_edges: $violations violations for target_tier=$target_tier" >&2
+  return 0
+}