@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/.claude/rules/compounding-sequence-fresh-analysis.md

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

package/substrate/.claude/rules/defensive-bash.md

@@ -0,0 +1,68 @@
+---
+tier: lite
+description: Every bash hook + script in bassclef follows standards/bash-hook-safety.md.
+---
+
+# Defensive Bash — Methodology Pointer
+
+Every bash hook + script in bassclef follows `standards/bash-hook-safety.md`. This rule is the auto-loaded reminder; the standard is the full reference.
+
+## When this rule fires
+
+Any edit / write to:
+
+- `.claude/hooks/*.sh` (hook files)
+- `scripts/*.sh` (scripts)
+- `lib/*.sh` (shared bash libraries)
+- New bash files anywhere in the repo (`.sh` extension OR `#!/bin/bash` shebang)
+
+## The seven disciplines (one-line each)
+
+1. **Strict mode at the top** — `set -euo pipefail` is mandatory
+2. **Quote every variable** — `"$var"` always inside string contexts; bare `$var` inside strings causes word-splitting + glob-expansion
+3. **`local` in functions** — every function-scope variable declared `local`
+4. **Trap EXIT for cleanup** — temp files / locks / background processes get `trap '...' EXIT`
+5. **Explicit return codes** — every termination point ends with `exit N`
+6. **Glob-tolerance** — `shopt -s nullglob` or array-with-length-check
+7. **Audit emission at every exit** — `trace_record` before exit
+
+Full reference: `standards/bash-hook-safety.md` (each discipline has anti-pattern + INSTEAD pair + worked example).
+
+## Saltzer & Schroeder anchor
+
+The seven disciplines instantiate `@luminary saltzer-schroeder`'s 8 protection-mechanism principles for the bash layer. The stack-translation table in `.claude/luminaries/saltzer-schroeder.md` maps each principle to its bash discipline.
+
+INSTEAD of inventing bassclef-specific bash rules: this rule + standard chain to the 50-year-stable Saltzer & Schroeder authority. The chain is: principle (luminary) → discipline (standard) → reminder (this rule).
+
+## Mechanical enforcement
+
+| Layer | Mechanism | When |
+|---|---|---|
+| Methodology | This rule (auto-loaded) | Every session |
+| Tier 0 TDD | `testing-tier-enforce.sh` hook | Edit/Write on `.claude/hooks/*.sh` (test mtime ≤ source mtime) |
+| Shellcheck baseline | `.github/workflows/shellcheck.yml` (Phase X-4) | PR open + push |
+| Strict-mode self-check | Reviewer + `/security-review` skill | PR review |
+
+INSTEAD of relying on agent self-discipline alone: mechanical layers fire at the moment of failure. This rule is the methodology layer that coexists with the mechanical layers.
+
+## Override
+
+`SKIP_DEFENSIVE_BASH=1 <command>` — for one-shot scripts that will not ship into the substrate (e.g., ad-hoc data inspection). Logged via trace-helper.
+
+INSTEAD of overriding when scope is tight: split the work — the throwaway script bypasses; the substrate-bound hook keeps the discipline. Mixing the two leaves substrate code with weakened safety.
+
+## Refs
+
+- `standards/bash-hook-safety.md` — full reference
+- `standards/code-safety-principles.md` — language-agnostic principles this rule instantiates
+- `@luminary saltzer-schroeder` — anchor
+- `@luminary john-ousterhout` — Deep modules framing for hook design
+- `@luminary kent-beck` — TDD anchor; Tier 0 strict-TDD applies
+- `.claude/rules/security.md` — sibling rule for web-layer source
+- `.claude/rules/destructive-operations.md` — agent self-assessment companion
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD discipline
+- docs/iteration-bets/2026-06-17a-secure-coding-foundations-longrun.md — goal authoring this rule
+
+## Retirement
+
+This rule retires only if bassclef migrates off bash for hooks. See `standards/bash-hook-safety.md` § Retirement.

package/substrate/.claude/rules/deferred-actions.md

@@ -0,0 +1,233 @@
+---
+tier: lite
+globs: ["**/*"]
+description: Deferred-actions manifest — capability-routed handoff across session modalities. Sessions write entries when capabilities don't satisfy an action; capable future sessions pick them up.
+---
+
+# Deferred Actions — Session Handoff Protocol
+
+`docs/deferred-actions/*.md` is the capability-routed handoff primitive.
+When a session produces work it cannot deliver (missing credentials,
+ephemeral sandbox, abrupt stop), it writes a deferred-action entry that
+a capable future session picks up at session-start.
+
+See `standards/deferred-actions-schema.md` for the full schema, field
+reference, capability vocabulary, and lifecycle. This rule governs
+*agent behavior* — when to write, when to resolve, how to prioritize.
+
+## When to write a deferred-action entry
+
+Any time the session has produced artifacts or state the current
+environment cannot deliver, and a future session with different
+capabilities could.
+
+Specifically:
+
+1. **External delivery gap** — skill produced output that pushes to an
+   external service (Google Doc, memory file, remote tag) but the
+   session lacks the capability. Examples:
+   - `/release-notes` in ephemeral-mobile — missing `gcloud-auth`
+   - `/journal` in cloud-web — missing `network` + `gcloud-auth`
+   - `/deploy-prod` retroactive `git tag` — ephemeral session without `git-tag`
+2. **Memory proposal** — mobile / cloud-web session identifies a memory
+   entry worth adding, but cannot write to `~/.claude/projects/.../memory/`.
+   Write a `*-memory.md` entry with the proposed content; next desktop
+   session reviews and applies.
+3. **Session rescue (abrupt stop)** — Stop hook fires in danger mode
+   (context exhausted, OS interruption). Write a `*-session-rescue.md`
+   entry enumerating unfinished MUST/SHOULD obligations (chronicle
+   backfill, whereami update, journal entry). Next session picks them
+   up as `BLOCKED:` items.
+4. **Skill explicitly defers** — any skill that encounters a missing
+   capability mid-run should self-detect and write the entry rather
+   than silently skipping. Silent skip is a rule violation (per
+   `session-artifacts.md` — silence is not deferral).
+
+## How to write
+
+Copy `templates/deferred-action-template.md` to
+`docs/deferred-actions/<ISO-ts>-<slug>.md`. Fill every required field
+per the schema. Commit as part of the session's normal artifact flow.
+
+```bash
+# example one-liner for skills
+TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
+SLUG="release-notes-gdoc-push"
+cp templates/deferred-action-template.md \
+   "docs/deferred-actions/${TS}-${SLUG}.md"
+# ...then edit the frontmatter + body in-place
+```
+
+The file must commit successfully — if `git add` / `git commit` fails
+in the current session, the entry will not propagate. Surface the
+failure visibly; do not silently drop.
+
+## When to resolve
+
+At session-start, `60-deferred-actions.sh` scans entries and emits
+`BLOCKED:` for capability-matched entries (this session can resolve)
+or `INFORM:` for capability-missed entries (visible, not actionable).
+
+Protocol for `BLOCKED:` entries mirrors `blocked-items.md`:
+
+1. Surface the `BLOCKED:` block verbatim to the operator (agent's
+   mandatory response format handles this automatically).
+2. Each blocked deferred-action entry MUST be either:
+   - **Resolved** in this session (run the entry's "Command to execute",
+     verify "On completion", apply Pattern A or Pattern B per below), OR
+   - **Explicitly deferred** by operator ("skip `<id>` this session")
+3. Silence is not deferral. Default is resolve.
+
+### Two resolution patterns — Pattern A and Pattern B
+
+Resolution shape depends on whether the entry's work was actually done OR routed elsewhere. Picking the wrong pattern is a real substrate failure. The eager mv to `completed/` mistake compounds across consumer sessions if not caught.
+
+**Pattern B (mv to completed/) — work was done:**
+
+The entry's `Command to execute` ran successfully; the entry's `On
+completion` checks pass; the work the entry described is finished.
+
+```bash
+git mv "docs/deferred-actions/<id>.md" \
+       "docs/deferred-actions/completed/<id>.md"
+git commit -m "chore: resolve <id>"
+```
+
+The filename never changes; git tracks the move so audit trail is
+preserved.
+
+**Pattern A (keep alive in active dir, flip status, surface as INFORM)
+— work was routed elsewhere:**
+
+The entry can't run as written because the substrate needs the current session cannot deliver. Examples: operator decisions, infra not yet provisioned, schema not yet shipped. The work moves to a GitHub issue in the consumer repo with the prereq spec. Bassclef issues get cross-referenced in a comment. The deferred-action file stays **in the active dir** with status flipped to `blocked-on-issue:#NNN`.
+
+Procedure:
+1. File a GitHub issue in the consumer repo with the prereq
+   specification.
+2. Cross-reference relevant bassclef issues in a comment on that
+   issue.
+3. **Leave** the deferred-action file in `docs/deferred-actions/`
+   (active dir).
+4. Edit the entry's frontmatter: set `status: blocked-on-issue:#NNN`.
+5. When bassclef#434 (`/defer-to-issue` skill) ships, the skill will
+   automate steps 1-4 and surface the entry as `INFORM` instead of
+   `BLOCKED` at session-start.
+
+Why Pattern A: deferred actions stay a visible signal until the substrate work behind them ships. Moving to `completed/` makes them disappear from the BLOCKED/INFORM pipeline. That is correct only when the work itself was done (Pattern B). Not when it was routed elsewhere.
+
+### Picking between A and B
+
+```mermaid
+stateDiagram-v2
+  [*] --> Active: entry written
+
+  Active --> RanCommand: agent runs Command to execute
+  RanCommand --> CheckOnCompletion: command succeeded
+  CheckOnCompletion --> CompletedB: On completion check passes (work done)
+  CheckOnCompletion --> RanCommand: check fails — retry
+
+  Active --> FoundFalsePositive: hook fired but work was already done
+  FoundFalsePositive --> CompletedB: mv to completed/ with body note
+
+  Active --> NeedsPrereqs: work needs prereqs current session cannot deliver
+  NeedsPrereqs --> FiledIssue: file GitHub issue with prereq spec
+  FiledIssue --> BlockedOnIssueA: leave in active dir, flip status to blocked-on-issue:#NNN
+
+  CompletedB --> [*]: archived in completed/ dir
+  BlockedOnIssueA --> Active: prereqs land, retry
+  BlockedOnIssueA --> CompletedB: re-routed work satisfied elsewhere
+```
+
+The state machine. Pattern B archives via `git mv` to `completed/`. Pattern A keeps the entry in `active/` and flips its status. Picking wrong compounds across consumer sessions. The wrong pick is: eager mv to `completed/` when the work was routed elsewhere.
+
+Ask: did the entry's `Command to execute` run successfully and does
+its `On completion` check pass?
+
+- **Yes** → Pattern B (mv to completed/)
+- **No, because the work needs prereqs the current session can't
+  deliver** → Pattern A (file issue, flip status, leave in active dir)
+- **No, because the entry was a hook false-positive (the work was
+  already done elsewhere)** → Pattern B (mv to completed/) with a
+  body note in the resolution commit explaining the false-positive
+  reason
+
+Mid-session, if you are tempted to mv a deferred-action to `completed/` because "we decided not to do it tonight" — STOP. That is Pattern A territory. File the issue. Comment with cross-refs. Leave the file alone. If you have already mv'd, revert. Push the revert to the same branch the file lives on.
+
+### Source incidents
+
+- TwoDo session 2026-05-02 (`docs/chronicle/2026-05-02-bind-subdomain-deferred-action-triage.md`): bind-subdomain deferred-action filed by cloud `/launch` dispatch (TwoDo PR #269) needed deploy-host provisioning the session couldn't do. First pass mv'd to `completed/` (commit `b4db506`); operator caught it and reverted (`b566d6c`) so bassclef#434 (when shipped) can route through Pattern A.
+- bassclef session 2026-05-03 /longrun pre-flight: `2026-05-01T11-51-24Z-session-rescue` had its hook-flagged obligations satisfied across subsequent sessions (chronicles written daily, whereami fresh) — Pattern B mv to completed/ correct here (work satisfied via natural session flow, not structurally re-routed).
+
+### Reference
+
+- bassclef#434 — `/defer-to-issue` skill (automates Pattern A)
+- bassclef#437 — deferred-action schema extension (adds the
+  `blocked-on-issue:#NNN` status field referenced above)
+
+## When to surface INFORM
+
+`INFORM:` entries are visible at session-start but not actionable in
+the current modality. Agent behavior:
+
+- Acknowledge the count in the session plan ("3 deferred entries require
+  capabilities this session doesn't have — next desktop session picks
+  them up")
+- Do NOT attempt to resolve them. Doing so wastes turns and may corrupt
+  the entry (partial resolution with wrong capabilities).
+- Do NOT delete or archive them. They wait for a capable session.
+
+## Priority handling
+
+Entries have `priority: high | medium | low` in frontmatter. Resolution
+order within a session:
+
+1. All `high` entries first (integrity-critical — missing chronicle,
+   orphan memory proposal)
+2. All `medium` entries (delivery gaps with downstream cost)
+3. `low` entries (nice-to-have) only if time budget allows
+
+If a session has 5+ resolvable entries, batch by priority and surface a
+resolution plan to the operator before running through them.
+
+## What NOT to write as a deferred action
+
+- **Tasks the operator hasn't asked for** — deferred actions are for
+  already-produced work, not proactive task proposals. Use GitHub
+  issues for that.
+- **Debug state or scratch notes** — chronicle footnotes, commit
+  messages, and scratch branches cover these.
+- **Information the resolver can re-derive** — if the work can be
+  re-produced by running the skill again, just cite the skill in a
+  chronicle and let the next session re-run it.
+
+## Relationship to other rules
+
+- `blocked-items.md` — deferred actions fire through the same
+  BLOCKED/resolve/explicit-defer protocol; this rule adds the
+  capability-routing layer
+- `mobile-ephemeral-session.md` — modality detection + the rule that
+  markers go git-tracked (not `/tmp`); deferred actions are the
+  mechanism for modality-bridging
+- `session-artifacts.md` — chronicle + journal-entry tier obligations;
+  session-rescue entries cover the abrupt-stop case
+- `artifact-ingestion.md` — resolving a deferred action counts as
+  "reading prior artifact"; the entry itself is the source to cite
+
+## Override paths
+
+- **Skip this session**: operator explicit "skip `<id>`" — entry stays
+  in place, next session surfaces it again
+- **Reject as not-needed**: operator explicit "reject `<id>`" — the
+  resolving session `git mv`'s to `completed/` with a body note
+  explaining rejection rationale (audit trail preserved)
+- **Re-scope mid-resolution**: if the entry's command no longer applies,
+  amend the entry body to describe the new path; do not delete
+
+## Enforcement
+
+Methodology-level. The session-reflection hook surfaces entries; the
+rule governs disposition. Mechanical enforcement (hook blocks session
+on unresolved high-priority entries) could be added if methodology
+alone proves insufficient.
+
+Override per-session: `SKIP_DEFERRED_ACTIONS=1 <command>` (logged to trace).

package/substrate/.claude/rules/github-issue-flash-tweet.md

@@ -0,0 +1,156 @@
+---
+tier: lite
+description: "Every GitHub issue body opens with Problem (≤500 chars): + --- + technical detail."
+---
+
+# GitHub Issue Body — Problem-Section Discipline
+
+Every GitHub issue body opens with `**Problem (≤500 chars):**` + `---` + technical detail. Operators on mobile read the title, then the Problem statement, then decide whether to scroll into the body. Detail comes AFTER the problem framing, not before.
+
+This rule closes the missing-surface gap: bassclef already enforces a clean opener at three other surfaces (skill descriptions per bassclef#377, plan enumerations per bassclef#339, autonomous-run output per bassclef#357). bassclef#484 originally adopted Flash + Tweet at the issue surface; bassclef#1178 retires that pairing in favor of a single problem-grounded section drafted by `/state-a-problem brief` — same shape, better orientation, fewer chars for the operator to scan.
+
+## Why this rule exists
+
+Operator feedback during /longrun 2026-05-04d closeout: "we were supposed to be ensuring that we were having value propositions and keep it simple (i.e., KISS-type skill and GitHub issue organizing). I'm not sure we're doing that consistently."
+
+Tickets bassclef#479 + bassclef#480 (filed during the same session) both had multi-section technical bodies with no opener. Operator on mobile reads title + scrolls past. Agent reading the ticket later has to re-scan to extract the 1-line claim. Both tickets DEMONSTRATE the gap; this rule closes it.
+
+V1 (bassclef#484) shipped Flash + Tweet. Operator observation 2026-06-18 surfaced that Flash + Tweet was solution-framed twice — neither stated user pain. bassclef#1178 retires Flash + Tweet at the issue surface in favor of a single problem-grounded opener. Same eat-our-own-dogfood: this rule, amended for bassclef#1178, opens its own related tickets with the new shape.
+
+## Format contract
+
+Every issue body MUST open with:
+
+```markdown
+**Problem (≤500 chars):** <Who + What + When + Why now + Outcome — framework implicit; drafted by /state-a-problem brief>
+
+---
+
+## <first detail section>
+```
+
+Format rules:
+
+- **Problem label is bold and enclosed in `**`** — visual scan handle, not body prose
+- **Length limit enforced** — Problem ≤500 chars (matches `/state-a-problem brief` mode cap)
+- **Plain language** — no bassclef jargon ("primitive", "load-bearing") in the Problem section. The Problem section is the FIRST place a reader meets the work; jargon here destroys orientation. `/state-a-problem` runs `/kiss --grade10` inline by default so this rule is hard to violate
+- **Horizontal rule** (`---`) separates Problem from technical detail
+- **Implicit framework** — Who/What/When/Why-now/Outcome carried in 3-4 sentences; labels NOT in the output
+- **No leading whitespace or code blocks before Problem** — must be the literal first content of the body
+
+## What NOT to do
+
+- **Don't open with a section header** (`## Summary`, `## Context`, etc.) before Problem. INSTEAD: Problem is the headline; section headers come after the `---` rule.
+- **Don't fall back to Flash + Tweet** because the `/state-a-problem` skill is not at hand. INSTEAD: hand-roll the Problem section using the implicit framework (Who/What/When/Why-now/Outcome in 3-4 sentences). The shape contract holds even when the mechanical layer is not running.
+- **Don't bury the claim in a "## Why this is needed" section.** INSTEAD: the claim IS the Problem opener; the rest of "why" belongs in detail.
+- **Don't use jargon walls in Problem.** INSTEAD: substitute plain English per `standards/bassclef-internal-jargon.md` and the `/kiss --grade10` table.
+- **Don't skip Problem because "the title says it."** INSTEAD: titles are search-truncated to ~70 chars; the Problem section gives the operator full context without needing to load the body.
+
+## Trivial-fix exception
+
+Bug-report or quick-fix tickets MAY skip the Problem section if the scope is one file AND no methodology change is implied (e.g., "typo in line 42 of X"). The shape contract still requires a clear first detail section in that case.
+
+## When this rule fires
+
+Every NEW GitHub issue body filed via:
+
+- `/promote` SKILL.md output — must include Problem section at top
+- `gh issue create` direct dispatch — agent self-checks before writing; local pre-author scrub fires via bassclef#1177 (PR #1180)
+- Manual operator filing via GitHub web UI — issue templates updated to show Problem shape
+
+Existing tickets are NOT retroactively backfilled. Forward-only enforcement keeps the discipline visible at the ticket-creation surface where it lands.
+
+## Mechanical enforcement
+
+V1 shipped methodology + `/promote` SKILL composition update (bassclef#484). V2 shipped local pre-author body scrub via bassclef#1177 (PR #1180 merged 2026-06-18). V3 (this bassclef#1178 amendment) ships:
+
+- Shape contract enforces Problem opener at substantive issue bodies
+- `/state-a-problem brief` skill drafts the section (runs `/kiss --grade10` inline by default)
+- `/promote` SKILL output gains the Problem-section shape
+
+## Override path
+
+`SKIP_ISSUE_PROBLEM_SHAPE=1 <command>` — for genuinely-not-issue-body cases (e.g., bug reports filed directly by external users where bassclef doesn't control the format). Logged.
+
+INSTEAD of overriding for tight scope: write the Problem section. Three sentences carrying the framework cost less than reviewer re-derivation.
+
+## Worked examples
+
+### Anti-pattern (what NOT to do — bassclef#479 + #480 demonstrate this)
+
+```markdown
+## Summary
+
+Add `/roadmap-reconcile` — a bassclef skill that updates roadmap surfaces...
+
+## Why this is needed
+
+Observed pattern (2026-05-04 sessions, captured during /longrun prep 2026-05-04d):
+
+1. Operator ideation surfaces a load-bearing detour mid-session...
+2. The detour reshapes downstream LR-N sequencing, but the canvases that hold...
+```
+
+Operator on mobile reads title, then "Summary" header, then has to read 3 paragraphs to get the claim. The claim is buried; user pain stays implicit.
+
+### Anti-pattern (V1 Flash + Tweet — superseded by bassclef#1178)
+
+```markdown
+**Flash (≤180 chars):** /roadmap-reconcile automates LR4 WU-0's manual canvas reconciliation — diffs canvas LR-N tables against shipping reality, surfaces drift via dry-run, applies edits with --apply.
+
+**Tweet (≤280 chars):** Stale-canvas trap closes: every future /longrun prep auto-reconciles before scope commit. Skill detects status mismatch, sequencing mismatch, and reference rot.
+```
+
+Better than no shape, but solution-framed twice. Reader still does not know WHY this work exists — only WHAT it does.
+
+### Conformant pattern (bassclef#1178 — Problem opener)
+
+```markdown
+**Problem (≤500 chars):** Today canvas LR-N tables and shipping reality drift apart across long sessions — operators returning to a canvas after a /longrun see stale status, wrong sequencing, and reference rot. The drift compounds across iterations until someone manually reconciles. The change we want is automated reconciliation at every /longrun prep so canvas tables and shipping reality stay aligned without manual cycles.
+
+---
+
+## Goal
+
+Add `/roadmap-reconcile` — a bassclef skill that...
+```
+
+Operator gets user pain → solution → diff in <60 seconds. Detail follows for those who want depth.
+
+## Composes with
+
+- `/state-a-problem` skill (brief mode, ≤500 chars) — drafts the Problem section; runs `/kiss --grade10` inline by default
+- `/promote` SKILL.md — composes Problem section at the top of every filed issue body
+- `/kiss` skill (words mode) — applies plain-English substitution to body's technical detail
+- `.claude/rules/pr-body-shape.md` (bassclef#906, amended by bassclef#1178) — sister discipline at PR-body surface
+- `.claude/rules/skill-description-clarity.md` (bassclef#377) — sibling discipline at description surface
+- `.claude/rules/plan-enumeration-needs-value-props.md` (bassclef#339) — sibling discipline at choice-presentation surface
+
+## Distinct from
+
+- `commit-conventions.md` — commit messages have separate format; this rule applies to issue BODIES, not commits
+- `iteration-bet-brief-completeness.md` — that's about delegation briefs (handoff content); this is about ticket-creation surface
+- `pattern-annotation.md` — that's source-code annotation discipline; orthogonal
+
+## Sources read
+
+- bassclef#484 (this rule's V1 parent ticket — filed at LR4 closeout) — operator framing
+- bassclef#1178 — V3 amendment (Problem section + `/state-a-problem` skill) — replaces Flash + Tweet at this surface
+- bassclef#377 (`.claude/rules/skill-description-clarity.md`) — sibling discipline at description surface
+- bassclef#339 (`.claude/rules/plan-enumeration-needs-value-props.md`) — sibling discipline at enumeration surface
+- bassclef#357 (autonomous-run flash + kiss) — sibling discipline at output surface
+- bassclef#1176 + bassclef#1177 — local pre-author body scrub hooks
+- `.claude/skills/value-prop/SKILL.md` — Flash + Tweet modes kept for chronicle / journal entry surfaces (just not PR + issue)
+- `.claude/skills/state-a-problem/SKILL.md` — replaces Flash + Tweet at this surface
+- `.claude/skills/promote/SKILL.md` — composition surface this rule integrates with
+- NN/g, UX Design Institute, OpinionX problem-statement frameworks — the templates `/state-a-problem` synthesizes
+
+## Closes
+
+- V1 of bassclef#484 — Flash + Tweet at issue body opener (WU-3 of LR5)
+- V2 of bassclef#484 — local pre-author scrub (bassclef#1176 + bassclef#1177)
+- V3 of bassclef#484 — Problem section opener replacing Flash + Tweet (bassclef#1178 — this amendment)
+
+## Retirement condition
+
+If observed across 6 months with zero operator corrections of issue opener formatting + `/promote` SKILL output consistently Problem-first, this rule is calibrated. If operator stops asking "what does this ticket buy me?" entirely, the rule has done its job.