@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/.claude/rules/skill-description-clarity.md

@@ -0,0 +1,247 @@
+---
+tier: lite
+description: "Every skill's frontmatter description field must be parseable by an engineer with no bassclef context in under 60 seconds."
+---
+
+# Skill-Description Clarity
+
+Every skill's frontmatter `description` field must be parseable by an
+engineer with no bassclef context in under 60 seconds. Outcome-first.
+≤280 chars. Plain language. INSTEAD-block discipline.
+
+This rule sits at the entry surface. It parallels bassclef#357 (which governs autonomous-run output). It applies `.claude/rules/context-engineering.md` at the description field: write for what the model can access. For this rule, that means write what a fresh engineer can read in 60 seconds.
+
+**Mechanical enforcement**: `.claude/hooks/substrate-clarity-gate.sh` fires at PreToolUse Edit|Write on substrate paths. It BLOCKs skill descriptions past 280 chars or without verb-first openers. The rule + luminary INSTEAD-block check runs ADVISORY today. It flips to BLOCK once the rule + luminary audits ship (tracked under bassclef-upstream#303). The allowlist at `.claude/hooks/substrate-clarity-allowlist.txt` grandfathers existing violators during the grace window. Per bassclef#382.
+
+## The bar
+
+Anthropic's frontend-design description (per Welch's revision):
+
+> "Create distinctive, production-grade frontend interfaces with
+> high design quality. Avoids generic AI aesthetics."
+
+That's the bar. Outcome ("create distinctive interfaces"), one-line
+how ("with high design quality"), one-line why-distinct ("avoids
+generic AI aesthetics"). 117 chars. Engineer reads it; knows what
+the skill produces; knows when to use it.
+
+Compare to bassclef's pre-rule descriptions (representative):
+
+> "BUILD-tier composer (Construction transition). Chains the
+> prototype pipeline (input → variants → gallery → bind-subdomain)
+> PLUS the buildable-spec pipeline (use-case → user-stories →
+> ia-model → interaction-design → decompose → spec → ux-migration)."
+
+571 chars. Methodology-laden. Requires knowing what every named
+component is. Engineer can't grok in 60 seconds.
+
+## Format
+
+Every skill's frontmatter `description` field follows:
+
+```
+<verb> <outcome>. <one-line how>. <one-line why-distinct>.
+```
+
+- **Verb**: imperative — "Create," "Generate," "Run," "Compose," "Audit"
+- **Outcome**: what the skill PRODUCES (not how it works internally)
+- **One-line how**: the most distinguishing mechanism, in plain language
+- **One-line why-distinct**: what makes it different from adjacent skills (or what it specifically AVOIDS)
+
+Total ≤280 chars including spaces.
+
+## INSTEAD-block discipline
+
+Every "DON'T" / "AVOID" / "NEVER" in the description gets paired with
+the actionable substitute, per `.claude/rules/context-engineering.md`.
+
+INSTEAD of bare negation: state the actionable substitute the engineer
+or model can verify in their current context. Bare "DON'T X" without
+"INSTEAD: Y" is a no-op for a stateless reader.
+
+In a description, this shows up in the why-distinct clause:
+
+- **Anti**: "Don't use this for short prompts."
+- **INSTEAD**: "Use for prompts ≥3 sentences; for one-liners, see /value-prop flash."
+
+The negation lives in context (when not to use). The substitute names the actionable path (which skill to use instead).
+
+## Plain language (per /kiss words)
+
+Grade-10 reading level. Common substitutions bassclef-substrate writers should make:
+
+| Replace | With |
+|---|---|
+| "composer" | "runs" / "chains" / "combines" |
+| "primitive" | "building block" |
+| "tier-preset" | "preset" / "size" |
+| "operationalize" | "do" / "ship" |
+| "load-bearing" | "required" / "must work" |
+| "blast radius" | "impact" / "what it can break" |
+| "substrate" | "system" / "framework" |
+| "bassclef" (in description body) | use sparingly; prefer "the framework" |
+| "compose-with" | "uses" / "builds on" |
+| "scope-bounded" | "small" / "tight" |
+
+If the description still uses bassclef jargon after substitution,
+the description was assuming context the engineer doesn't have.
+Rewrite further.
+
+## What MUST NOT appear in a description
+
+- References to other skills the engineer hasn't read yet (skill names OK; methodology references aren't)
+- Methodology chains ("X → Y → Z → ...")
+- Tier specifications without explaining what the tier does
+- Citations to bassclef issues (those go in the body)
+- Dates / versions / "renamed from X on Y" (those go in the body)
+- Assumed pipeline knowledge ("Phase 14 of the buildable-spec chain")
+
+## What MUST appear in a description
+
+- The verb-outcome opener
+- A concrete sense of what the user gets back
+- A distinguishing characteristic vs. adjacent skills
+- **Modes / tiers / sizes named inline when frontmatter declares them** (bassclef#535) — see next section
+
+## Description-mirrors-modes (bassclef#535)
+
+When a skill's frontmatter declares structured `modes:` / `tiers:` / `sizes:` (per bassclef#515), the description **text** MUST name each declared value inline. Operators see Claude Code's type-ahead BEFORE invoking `/skills`; type-ahead reads only the `description` field. Frontmatter `modes:` is machine-readable for bassclef's audit + render pipeline but invisible to type-ahead.
+
+**The discipline:**
+
+- If frontmatter has `modes: [scope, words]`, description must contain "scope" AND "words" (typically as "Two modes — scope ... and words ..." or similar)
+- If frontmatter has `tiers: [quick, light, medium, full]`, description must name all four
+- If frontmatter has `sizes: [flash, tweet, brief, verbose]`, description must name all four
+- Skills with `no_user_modes: true` (opt-out) are exempt
+- The 280-char ceiling still applies — naming N modes that won't fit means the description is over-claiming; collapse the verbiage around them
+
+**Why mirror, not auto-render?**
+
+Type-ahead reads `description`. bassclef doesn't control the harness; we control the data we put in `description`. Mirroring is the cheap fix that makes type-ahead useful for mode-bearing skills today. Frontmatter `modes:` stays machine-readable for `/skills` catalog rendering + audit + future structured uses; description text stays human-readable for type-ahead.
+
+**Conformance examples (all 7 skills with modes today):**
+
+| Skill | Frontmatter | Description names them? |
+|---|---|---|
+| `/value-prop` | `sizes: [flash, tweet, brief, verbose]` | ✓ "Four sizes — flash ... tweet ... brief ... verbose" |
+| `/kiss` | `modes: [scope, words]` | ✓ "Two modes — scope ... and words ..." |
+| `/stage` | `sizes: [quick, light]` | ✓ "Two sizes: quick ... and light ..." |
+| `/launch` | `sizes: [medium, full]` | ✓ "Two sizes: medium ... and full ..." |
+| `/shape` | `tiers: [quick, light, medium, full]` | ✓ "four sizes — quick, light, medium, full" |
+| `/longrun` | `modes: [prep, checkpoint, closeout]` | ✓ "three modes — prep, checkpoint, closeout" (after bassclef#535) |
+| `/interpret-input` | `modes: [text, url, image, repo, transcript, napkin, mixed]` | ✓ types listed in parens |
+| `/onboard-repo` | `modes: [default, --with-deploy-host, --with-secrets, --full]` | ❌ pending — fold into LR8.6 PR #526 amendment |
+
+**Mechanical enforcement (deferred follow-on):**
+
+- `scripts/audit-skills-modes.sh` (bassclef#515 PR #519) extends with `description-doesnt-mirror-modes` finding type
+- `.claude/hooks/substrate-clarity-gate.sh` extends with the same check at PreToolUse Edit/Write time
+- Both gated behind bassclef#515 + bassclef#382 landing first; until then, this rule is methodology-level + the operator runs the audit manually
+
+**Override:**
+
+`SKIP_DESCRIPTION_MIRRORS_MODES=1` per-call override (logged via trace-helper). Use only when the frontmatter declares modes that are too numerous to mention inline (>5) AND a higher-level grouping description suffices.
+
+## Worked examples — applying the rule
+
+### /sprint (before)
+
+> "Show current iteration goal, open issues by priority, and proposed next sprint. Quick orientation for any session."
+
+132 chars. Decent — verb opener, outcome named. Could be tighter on
+why-distinct. **Score: B+. Acceptable.**
+
+### /sprint (after)
+
+> "Show what's in flight and what's next. Reads project state, open issues, and the active iteration goal; proposes the next sprint. Run at session start to orient."
+
+161 chars. Verb-outcome stronger. Why-distinct (when to use) explicit. **Score: A.**
+
+### /longrun (before)
+
+> "Self-checkpointing long-session lifecycle (prep / checkpoint / closeout). Orchestrator-gated sequential by default. Use when ≥2 active goals OR estimated >50 turns OR session crosses compaction. Composes /temperance, /retro, /promote, /session-end. Replaces manual mid-session reflection that defeats fire-and-forget intent."
+
+322 chars. Methodology-laden. "Orchestrator-gated sequential" is jargon. Composes-list dumps internal references. **Score: D.**
+
+### /longrun (after)
+
+> "Run a long autonomous session that paces itself — prepares scope, checkpoints at phase boundaries, closes with chronicle + journal entry + retro. Use for sessions over 50 turns or with multiple bets. Replaces mid-session manual reflection."
+
+249 chars. Outcome-first. Plain language. When-to-use explicit. **Score: A-.**
+
+### /launch (formerly /preview-build) (before)
+
+> "BUILD-tier composer (Construction transition). Chains the prototype pipeline (input → variants → gallery → bind-subdomain) PLUS the buildable-spec pipeline (use-case → user-stories → ia-model → interaction-design → decompose → spec → ux-migration). Tiers: medium (~1 day, 3 variants + buildable spec + INVEST stories + GRASP matrix) and full..."
+
+571 chars (truncated). Methodology dump. Tier specs without context.
+**Score: F.**
+
+### /launch (after)
+
+> "Turn an idea into a buildable plan. Produces a clickable mock gallery PLUS the spec, decomposition, and migration plan needed to actually build the chosen direction. Two sizes: medium (~1 day) and full (~audit-grade). Operator dispatches when ready to ship."
+
+275 chars. Outcome-first. The "PLUS" makes the differentiator vs.
+/stage (formerly /preview) clear. Tiers framed by time budget, not internal methodology.
+**Score: A.**
+
+## Application
+
+### Per skill (rewrites)
+
+1. Read existing description
+2. Score against rule (Verb? Outcome? ≤280 chars? Jargon? Plain language?)
+3. Rewrite if score < B
+4. Test the rewrite: would a senior engineer with no bassclef context understand it in 60 seconds?
+
+### Per longrun (audit)
+
+The audit issue (bassclef#375 + sister WU-3 issues) tracks
+per-skill rewrites. WU-6 of this longrun ships top-7 (data + judgment
+based) as in-scope examples; rest filed as follow-up.
+
+### Per new skill
+
+Every new skill's description goes through this rule before merge.
+Test: paste the description into a Slack DM to a senior engineer
+without bassclef context. If they ask "what does this DO?" you
+violated the rule.
+
+INSTEAD of testing against a bassclef-savvy reader: test against
+a fresh reader who carries no internal vocabulary. That's the
+audience the description has to serve.
+
+## Relationship to other rules
+
+- `.claude/rules/context-engineering.md` — the foundational rule; this is one application
+- bassclef#357 (autonomous-run flash + kiss) — sibling discipline at output surface; this rule is at description surface
+- bassclef#367 (section-heading standardization) — sibling specificity discipline
+- bassclef#339 (plan-enumeration-needs-value-props) — sibling at choice-presentation surface
+
+## Override
+
+There is no override. Skill descriptions are an entry surface for
+engineers and operators. Violating the rule means engineers won't
+adopt the skill, regardless of how good the skill itself is.
+
+If you can't write the description per the rule, the skill's job
+isn't clear enough — clarify the skill before clarifying the
+description.
+
+## Audit pattern
+
+```bash
+# Find skills whose descriptions exceed 280 chars
+grep -r "^description:" .claude/skills/*/SKILL.md | awk -F: '{ if (length($0) > 280) print $0 }'
+
+# Find skills whose descriptions use bassclef jargon
+git grep -niE 'composer|primitive|tier-preset|operationalize|load-bearing|blast radius|compose-with' .claude/skills/*/SKILL.md | grep -E '^.*:description:'
+```
+
+## Sources read
+
+- `.claude/rules/context-engineering.md` (bassclef#371) — foundational rule
+- bassclef#357 — sibling output-surface rule
+- bassclef#367 — sibling specificity rule
+- `.claude/skills/value-prop/SKILL.md` — flash mode (≤180 chars analog)
+- `.claude/skills/kiss/SKILL.md` — words mode (plain-language analog)
+- Anthropic `frontend-design` skill description — direct exemplar; bassclef declares this as baseline-composes-with in `/frontend-design`, `/riff-prototypes`, `/launch`, `/visual-review` skill frontmatter rather than carrying it as a luminary entry

package/substrate/.claude/rules/skill-procedure-step-list.md

@@ -0,0 +1,137 @@
+---
+tier: lite
+description: Before executing any SKILL procedure, I write the numbered step list into the response.
+---
+
+# Skill-procedure step-list
+
+Before executing any SKILL procedure, I write the numbered step list into the response. Each step is marked `[x]` executed with source cited OR `[~]` explicitly deferred with reason. No `[ ]` unchecked lines ship at output time. Silence is not deferral.
+
+This rule extends `.claude/rules/assert-only-after-verify.md` from the assertion surface to the SKILL-procedure surface. It is the methodology layer. The mechanical layer is `.claude/hooks/skill-step-list-check.sh` — Stop hook that scans the transcript for a Skill dispatch followed by an assistant response without a step-list block.
+
+## Why this rule exists
+
+Session 2026-08-05a dispatched `/roadmap-reconcile --dry-run` during `/longrun` prep. The SKILL procedure names 5 steps. I ran Step 1 (enumerate surfaces), skipped Step 2 (read shipping reality), and jumped to Step 3 (build a diff). I substituted whereami queue narrative for the actual `gh pr view` + `gh issue view` cross-check Step 2 requires. Four stale drift rows shipped. Operator caught the class in one turn — three closed tickets (#1050, #1051, #1054) shown as pending because whereami queue said so and no cross-check verified.
+
+Memory alone catches nothing at write time. Two existing rule + hook pairs prove the pattern holds at scale — `.claude/rules/assert-only-after-verify.md` + `.claude/hooks/assert-verify-steering.sh`, and `.claude/rules/plain-english-discipline.md` + `.claude/hooks/turn-prose-kiss-check.sh`. This rule is the third pair, at the SKILL-procedure surface.
+
+## When this rule fires
+
+Every SKILL dispatch. Agents self-check before writing the response. Hook fires at Stop event as the write-time backstop.
+
+Fires on:
+
+- Any Skill tool dispatch in the current turn
+- Any SKILL body whose procedure names 2+ steps
+
+Passes through on:
+
+- Non-Skill tool calls (Bash, Read, Edit, Write, Grep, etc.) — those follow their own discipline rules
+- SKILL body procedures with 0 or 1 step (no list needed)
+- Tool-output relays (test output, git output) that carry no assertions of their own
+
+## What the rule requires
+
+Before shipping any response following a SKILL dispatch:
+
+1. **Read the SKILL body Procedure section.** Enumerate the numbered steps.
+2. **Write the step list at the top of the response.** Format: `Step N — <name>` followed by a status marker.
+3. **Execute each step.** Cite the source inline as it runs.
+4. **Mark each step's status:**
+   - `[x]` executed with source cited
+   - `[~]` explicitly deferred with reason (silence is not deferral)
+   - Do not ship `[ ]` unchecked at output time.
+     INSTEAD: mark every step `[x]` or `[~]` before the response ships. Unchecked shipped equals silent skip.
+5. **Loaded context is a hint, not a substitute for a source read named by a step.** The context feels full. That is when the skip is easiest and the drift is worst.
+   INSTEAD: cite the source per the SKILL step. Loaded context is a hint, not a substitute.
+
+## Format contract
+
+Each step line matches one of these shapes:
+
+- `Step N — <name> — [x] <source cited>`
+- `Step N — <name> — [~] <deferral reason>`
+
+Or a block header + list format:
+
+```
+Steps:
+- Step 1 — <name> — [x] <source>
+- Step 2 — <name> — [~] <reason>
+```
+
+The hook scans for two markers together: the token `Step\s+\d+` AND either `[x]` or `[~]` bracketed. Both must appear in the assistant text following a Skill dispatch.
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Dispatch skill; write results with no step list.** The response ships without any `Step N` markers. Hook fires ADVISORY (or BLOCK under strict toggle).
+INSTEAD: enumerate the SKILL procedure steps at the top of the response before running them.
+
+**Silent skip.** A step gets no `[x]` and no `[~]` line — the response simply omits it.
+INSTEAD: every step from the SKILL procedure appears in the response, either done or explicitly deferred with reason.
+
+**Context as substitute.** Loaded context carries a plausible answer. Skip the SKILL step; use the context.
+INSTEAD: cite the source per the SKILL step. Loaded context is a hint, not a substitute for the read the step names.
+
+**Half-written list.** Some steps carry markers; others do not.
+INSTEAD: every step marked before response ships. Half-written lists cause reviewer confusion + trigger the hook.
+
+## When this rule does NOT fire
+
+- Tool-output relays (test output, git output) — no assertion of the agent's own
+- SKILL body with 0 or 1 step — no list needed
+- Skill invoked purely for its output display (e.g., `/whereami` for a status snapshot)
+- Chat responses that do not follow a Skill dispatch
+
+## Override
+
+`SKIP_SKILL_STEP_LIST=1 <command>` — per-call bypass, logged via trace-helper. Use rarely:
+
+- One-shot migration scripts that dispatch many SKILLs at once
+- Emergency rescue when the hook itself misbehaves
+- Explicitly-deferred rework where the step list ships in a follow-up response
+
+For routine SKILL dispatches, write the step list. The cost is small; the audit trail compounds.
+
+## Toggle
+
+The hook reads `SKILL_STEP_LIST_TOGGLE` from env OR `skill_step_list.toggle` from `.claude/bassclef-configs.jsonc`:
+
+- `true` (default) — advisory (exit 0, findings to stderr)
+- `strict` — strict (exit 2, blocks the stop event, forces a rewrite)
+- `false` — silent (exit 0, no scan)
+
+V1 ships advisory. V2 may flip to strict after a calibration cycle observes drift stays under 10%.
+
+## Anchor luminaries
+
+- `.claude/luminaries/saltzer-schroeder.md` (Saltzer & Schroeder 1975, IEEE 63(9)) — complete mediation. Every access to protected state is checked. Whereami narrative was a cached authorization. Rule + hook forces mediation at every SKILL dispatch.
+- `.claude/luminaries/tony-hoare.md` (Hoare 1969, CACM 12(10)) — pre/postcondition triple. Each step's postcondition is the next step's precondition. Skip breaks the chain.
+- `.claude/luminaries/michael-feathers.md` (Feathers 2004) — characterization tests. Pin actual behavior via source of record before naming it.
+- `.claude/luminaries/kent-beck.md` (Beck 2002) — list-before-execute. Sister discipline at test surface applied to SKILL surface.
+
+## Composes with
+
+- `.claude/rules/assert-only-after-verify.md` — parent discipline at claim surface; this rule extends to SKILL-procedure surface
+- `.claude/rules/bootstrap-pair-discipline.md` — pair-shape pattern (rule + hook + Tier 0 test)
+- `.claude/rules/substrate-as-system.md` — ADR-035 tenet
+- `.claude/rules/test-list-discipline.md` — Beck's list-before-execute sister rule at test surface
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict TDD on hook + tests
+- `.claude/rules/we-dont-break-adopters.md` — V1 ADVISORY default preserves adopter behavior
+- `.claude/rules/blocked-items.md` — BLOCK protocol the hook fires under strict toggle
+- `.claude/hooks/skill-step-list-check.sh` — mechanical implementation
+- `.claude/hooks/tests/skill-step-list-check.test.sh` — Tier 0 test coverage (10 tests)
+
+## Refs
+
+- sunj-labs/bassclef-upstream#1119 — parent ticket
+- Session 2026-08-05a `/diagnose` output — root cause named (SKILL step skip + context-as-substitute)
+- Memory `feedback_skill_procedure_step_list_before_execute` — evidence anchor
+- Goal doc `docs/iteration-bets/2026-08-05a-skill-step-list-plus-whereami-hygiene.md` — bet frame
+- Sister ticket sunj-labs/bassclef-upstream#1121 — in-turn error stream subsystem (broader observability)
+
+## Retirement condition
+
+This rule retires only if SKILL dispatch stops being the primary agent-to-substrate composition path. The mechanical layer may evolve (additional detection heuristics, integration with error-stream subsystem #1121). The discipline of write-time step verification persists.

package/substrate/.claude/rules/stuck-signal-diagnostic.md

@@ -0,0 +1,140 @@
+---
+tier: lite
+description: "When a hook emits the same BLOCKED signal across ≥3 consecutive sessions and the underlying state counter hasn't moved, the signal is stuck."
+---
+
+# Stuck-Signal Diagnostic
+
+When a hook emits the same BLOCKED signal across ≥3 consecutive sessions
+and the underlying state counter hasn't moved, the signal is stuck.
+A stuck signal is evidence of a **substrate defect**, not operator
+error — the hook is correctly detecting a condition the fix path
+cannot clear. Continuing to fire the same banner without reading the
+mechanism that produces it reproduces the acknowledge-and-skip loop
+`blocked-items.md` was built to close.
+
+## When this rule fires
+
+Any BLOCKED banner whose underlying counter / state has not advanced
+across ≥3 sessions. Observable shapes:
+
+- `BLOCKED: verify-compliance — X%` where X is identical 3 sessions running
+- `BLOCKED: temperance-compliance — X%` where X is identical 3 sessions running
+- `BLOCKED: metrics — DORA stale` with identical staleness counts
+- `BLOCKED: release-notes — last entry N days ago` where N grows but no
+  release is written
+- Any hook-surfaced BLOCKED whose associated counter/timestamp/state
+  is numerically or categorically unchanged across the last 3 chronicles
+
+The operator does not need to flag the staleness. The agent must
+self-detect by comparing current banner text against the prior
+session's banner text (visible in chronicles or `/sprint` output).
+
+## Mandatory mechanism-read
+
+When stuck-signal is detected, the agent MUST:
+
+1. **Stop addressing the symptom.** Do not propose running the usual
+   fix (e.g., "let me run /verify more diligently this session"). The
+   fix has been tried and the counter hasn't moved. That's the signal.
+
+2. **Read the mechanism files named in the banner.** The hook banner
+   names the exact paths. Follow the paths. Read every one.
+
+3. **Trace the counter's update path.** From mechanism-file read,
+   answer:
+   - Where is the counter computed?
+   - What state does the counter consume?
+   - What action updates that state?
+   - Is the update actually landing, or landing to a surface the
+     counter doesn't read?
+
+4. **Fire /diagnose on the mechanism.** Treat the stuck signal as a
+   substrate failure per `diagnosis.md`. Is/Is-Not + Five Whys +
+   Hypothesis applied to the hook + state-file + update path — not to
+   the surface behavior.
+
+5. **Resolve via substrate edit or escalate.** The fix is almost
+   always in the mechanism: wrong path, stale regex, counter reading
+   a location the writer stopped using, `/tmp` marker lost across
+   sandbox teardown. Edit the substrate, commit, verify the counter
+   advances. If substrate-read reveals no defect, escalate — the
+   counter is correct and the work is genuinely undone; `blocked-items.md`
+   default (resolve) applies.
+
+## Post-resolution obligation: mandatory /promote
+
+When mechanism-read reveals a substrate defect (hook path wrong,
+state file rotted, marker format changed, compliance calc broken),
+resolution MUST include firing `/promote` with the `substrate-defect`
+classifier. See `blocked-items.md` §"When resolution reveals a
+substrate defect" for the full protocol and `promote/SKILL.md` for
+the template.
+
+Fixing the local instance without promoting means the same defect
+keeps firing in consumer repos — which is exactly the
+acknowledge-and-skip loop at a different layer.
+
+## Why this rule exists
+
+2026-04-20 session end + 2026-04-21 session start (the loop that
+motivated bet `2026-04-21a-blocked-signal-integrity`): session-rescue
+hook fired 15 times in ≤4 hours, each session acknowledging the
+deferred-actions BLOCKED block, resolving the nominal entry, and
+shipping — only for the next stop to write a fresh rescue entry.
+
+The counter ("15 deferred-action entries resolvable") stayed stuck
+because resolution lived in the local session but the hook's
+detection path rotted during `/tmp` sandbox teardown. The mechanism
+file (`session-end.sh`) had a calendar-date chronicle check that fired
+even when a fresh chronicle existed with a different date pattern —
+a substrate defect that `/verify`-more-carefully could not clear.
+
+Root cause: the agent kept "resolving" the surface while the
+mechanism produced fresh false-positives. Three sessions of identical
+banner text. The signal was stuck. Nobody read `session-end.sh`.
+
+This rule removes the option to "try harder" when the counter hasn't
+moved. If the counter is stuck, the fix is in the mechanism, not in
+the work.
+
+## Relationship to other rules
+
+- `blocked-items.md` — the base BLOCKED-resolve-or-explicit-defer
+  protocol; stuck-signal is a specific escalation branch
+- `diagnosis.md` — Is/Is-Not + Five Whys applies to the mechanism
+  when the signal is stuck
+- `sdlc-gates.md` — observed failure → temperance → diagnose chain;
+  stuck-signal is an observed failure in the meta-signal layer
+- `artifact-ingestion.md` — "read the file before producing" extends
+  to "read the mechanism before resolving"
+- Post-resolution `/promote` obligation: `blocked-items.md` §"When
+  resolution reveals a substrate defect"
+
+## Enforcement
+
+Methodology-level. The compliance-counter hooks
+(`session-reflection.d/40-gate-compliance.sh` and siblings) name
+mechanism paths in their BLOCKED banners so the agent has the
+literal file paths to read — no guessing about what "mechanism"
+means. If stuck-signal recurs without mechanism-read in the next 6
+months, upgrade to hook-enforced: refuse session advance until an
+Edit tool call lands on the named mechanism path.
+
+## Override
+
+There is no override. Stuck-signal is the condition under which
+"proceed and try again" is the failure mode. If the counter is
+stuck, the agent reads the mechanism. Full stop.
+
+Operator may still explicitly defer the underlying BLOCKED item per
+`blocked-items.md` deferral syntax ("skip metrics this session") —
+but the mechanism-read obligation still fires the next session unless
+the operator also defers that (rare, e.g., "mechanism-read next
+week, I'm unblocking you manually this time").
+
+## Retirement condition
+
+If counter-stuck incidents fall to zero for 12 months with no
+operator-flagged false-negatives, this rule has done its job.
+Retirement candidate — the methodology-layer habit is durable.

package/substrate/.claude/rules/substrate-config-schema.md

@@ -0,0 +1,98 @@
+---
+tier: lite
+globs: ["substrate.config.md", "substrate.secrets.md", ".claude/skills/**/*.md", ".claude/hooks/**/*", "standards/**/*.md"]
+description: Substrate config + secrets schemas — single source of truth for external resource references and secret lifecycle
+---
+
+# Substrate Config + Secrets Schema (rule)
+
+Two paired files; each owns one concern:
+
+| File | Owns | Standard |
+|------|------|----------|
+| `substrate.config.md` | External resource *references* (Google Doc IDs, URLs, repo refs, env-var names) | `standards/substrate-config-schema.md` |
+| `substrate.secrets.md` | Secret *lifecycle* (rotation cadence, expiry, runbooks, health checks) | `standards/secrets-lifecycle.md` |
+
+Both are read at session-start; agents always source from these files.
+
+INSTEAD of memory or hardcoded values: read at session-start from
+`substrate.config.md` (resources) and `substrate.secrets.md` (lifecycle).
+
+## Agent behavior rules
+
+1. **Read resources only from `substrate.config.md`.** When a skill
+   or hook needs a doc ID, URL, or similar reference, the agent
+   reads it from this file at runtime. Don't hardcode. Don't cache.
+
+   INSTEAD: read at runtime from `substrate.config.md`. Field name is
+   the interface; raw value is implementation detail that can change.
+
+2. **Reference by field name, not by raw value.** In project memory,
+   in chronicles, in commit messages: say `brand_corpus_doc_id`, not
+   `1gps7mmEYBCud...`. The raw value is an implementation detail;
+   the field name is the interface.
+
+3. **When a resource is missing**, prompt the operator to add it to
+   `substrate.config.md` with a typed field name. Use the suffix
+   convention: `*_doc_id`, `*_url`, `*_repo`, `*_path`, `*_token_name`,
+   etc. (full list in the standard).
+
+4. **No raw secrets in `substrate.config.md`.** That file is
+   committed to git. Store the *name* of the env var holding the
+   secret (`anthropic_key_name: ANTHROPIC_API_KEY`).
+
+   INSTEAD of inlining the secret value: keep values in their
+   authoritative storage (1Password / GitHub Actions Secrets /
+   AWS Secrets Manager / `.env`); the config file points by name.
+
+5. **Secret *lifecycle* belongs in `substrate.secrets.md`**, not
+   `substrate.config.md`. References go in config; rotation cadence,
+   expiry dates, runbook paths, and health-check commands go in
+   secrets. Each file owns its concern.
+
+   INSTEAD of mixing concerns: lifecycle metadata (last_rotated,
+   expiry_at, rotation_procedure) lives in `substrate.secrets.md`;
+   resource references (doc IDs, URLs, env-var names) live in
+   `substrate.config.md`. Cross-reference between the two files.
+
+6. **No secret VALUES anywhere in the repo.** `substrate.secrets.md`
+   tracks references and metadata only — values stay in their
+   authoritative storage (1Password / GitHub Actions Secrets / `.env`
+   / AWS Secrets Manager). The session-start hook
+   (`.claude/hooks/session-reflection.d/90-secrets-expiry.sh`) surfaces
+   BLOCKED when any secret is within `alert_threshold_days`; resolve
+   per the entry's `rotation_procedure` runbook.
+
+7. **When migrating old code**, replace hardcoded IDs with
+   `substrate.config.md` lookups. Grep for the raw ID value across
+   `.claude/`, `standards/`, `strategy/`, and the raw content of
+   project memory. Replace with field-name reference.
+
+## Why this rule exists
+
+Before this rule (learned 2026-04-12):
+- Brand corpus doc ID lived in project memory
+- Hardcoded in `/journal-export` skill
+- Also referenced indirectly in other places
+- Agent pushed to wrong doc, operator caught the mismatch, hours of
+  confusion and re-pushing followed
+
+After: one place. Typed. Skills read at runtime. Memory points by
+name. Agents can't confuse which doc is which because there's only
+one source.
+
+## Bootstrap path for new repos
+
+When `/autonomous start` scaffolds a new repo's `substrate.config.md`,
+it prompts for every known resource field (per the standard's "Known
+fields" section). Operators can skip (defaults apply), but each known
+field is surfaced once so nothing gets stored in memory or hardcoded
+by accident.
+
+## Related
+
+- `standards/substrate-config-schema.md` — full standard
+- `.claude/skills/autonomous/SKILL.md` — scaffold prompts for
+  each known field
+- `.claude/skills/substrate-check/SKILL.md` — can validate config schema
+  compliance in a repo