@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/.claude/rules/context-management.md

@@ -0,0 +1,85 @@
+---
+tier: lite
+globs: ["*"]
+description: Context window management — thresholds, compaction strategy, survival kit
+---
+
+# Context Management
+
+Long sessions will hit context limits. This is expected, not a failure.
+Manage proactively.
+
+INSTEAD of waiting for compaction to surprise you: checkpoint at 70%
+context (commit work, write whereami, let compaction run). Re-read the
+survival kit after compaction.
+
+## Thresholds
+
+| Context level | Action |
+|--------------|--------|
+| 0–50% | Normal operation. Read files freely. |
+| 50–70% | Be selective. INSTEAD of full file reads: use Glob/Grep with bounded result sets. Skip re-reading files already in current context. |
+| 70% | **Checkpoint now.** Commit all work. Write whereami. The system will auto-compact prior messages. After compaction, re-read the survival kit. |
+| 80%+ | **Atomic tasks only.** Complete current task, commit, re-read survival kit. Do not start multi-file changes. |
+| 90% | **Finish and stop.** Complete the current atomic unit, commit, update whereami. Write chronicle if at a phase boundary. |
+
+## Survival kit (re-read after ANY compaction)
+
+The survival kit mirrors what `iteration-bet-brief-completeness.md`
+requires in a Builder/Designer/Architect handoff brief — same artifact
+list, one source of truth. Post-compaction re-read is functionally
+identical to a fresh role handoff: the agent needs the same context to
+continue the goal correctly.
+
+**Always re-read:**
+
+1. **Iteration bet** — scope, phase, time budget, acceptance criteria, references block
+2. **Phase-state** — where we are, what's done, what's next
+3. **MUST gates** — sdlc-gates rule + choreography Section 9
+4. **Current agent definition** — role-specific obligations (if multi-agent)
+
+**Re-read when the goal's References cite them (per scope):**
+
+5. **Canvas** — upstream thesis; re-read when spec is thin or scope is
+   product-facing
+6. **Current spec or decomposition artifact** — what's being built; the
+   `/decompose` output carries cross-cutting-concern resolution
+   (interfaces, decorators) that must survive compaction or the
+   Langfuse-inside-HaikuImputer anti-pattern reproduces
+7. **Prototypes** — every prototype path the goal cites; losing these
+   reproduces the cramped-UI-rebuild failure mode
+8. **Pinned ADRs** — architecture constraints the goal calls governing
+9. **Luminary map** — primary pair + extended pairs for surfaces in scope
+10. **Branch stack manifest** — if in Construction with stacked branches
+11. **Risk register (active iteration)** — so mitigations aren't re-forgotten
+
+What you do NOT need to re-read: the 24 bassclef rules, standards in
+`standards/`, and agent choreography. Those inherit via
+`additionalDirectories` and are injected fresh each turn — compaction
+does not drop them.
+
+If you can't recall what you're building, what gates apply, or which
+prototypes/ADRs/luminaries govern the work, you've lost critical
+context. Re-read before continuing.
+
+## Anti-patterns
+
+- **Don't read entire large files** when you only need a section.
+  INSTEAD: use Read with offset/limit, or grep for the section header first.
+- **Don't re-read files** already in the conversation.
+  INSTEAD: check whether the file content is already in your context window.
+- **Don't expand search results** you don't need.
+  INSTEAD: use head_limit on Grep to cap the result set.
+- **Don't keep retrying** failed approaches — each retry consumes context.
+  INSTEAD: diagnose first (Is/Is Not + Five Whys), then fix.
+
+## Sequential mode specifics
+
+In sequential autonomous mode, one session plays all roles. Context
+pressure is highest during Construction after Inception and Elaboration
+have consumed context. At each role transition:
+
+1. Commit all artifacts from the current role
+2. The handoff artifact IS the context for the next role
+3. Let compaction run
+4. Re-read survival kit + next agent definition

package/dist/lite/.claude/rules/defensive-bash.md

@@ -0,0 +1,52 @@
+---
+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.

package/dist/lite/.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/dist/lite/.claude/rules/destructive-operations.md

@@ -0,0 +1,69 @@
+---
+tier: lite
+description: The destructive-command-guard hook catches known patterns mechanically.
+---
+
+# Destructive Operations — Agent Self-Assessment
+
+The destructive-command-guard hook catches known patterns mechanically.
+This rule is the primary gate — your judgment catches what grep cannot.
+
+## Before ANY command that modifies state outside the working directory
+
+Pause and ask three questions:
+
+1. **ROOT CAUSE** — What specific problem requires this action?
+   Not "it's broken." What exactly is wrong? Can you name the error?
+
+2. **SIMPLER FIX** — Is there a targeted alternative that avoids destruction?
+   The simplest fix is almost never the most destructive one.
+
+3. **RECOVERY** — If this goes wrong, can you undo it?
+
+## What counts as "outside the working directory"
+
+- **Databases**: any SQL command, Prisma operation, Redis command, Mongo operation
+- **Containers**: Docker, Kubernetes, compose operations that modify state
+- **Cloud infra**: AWS, GCP, Azure, Terraform, Pulumi operations
+- **Package registries**: npm publish, unpublish, deprecate
+- **Caches**: Redis FLUSHALL, CDN invalidation, build cache clearing
+- **Services**: process kills, daemon restarts, cron modifications
+- **Auth/secrets**: key rotation, token revocation, permission changes
+- **DNS/networking**: record changes, firewall rules, proxy config
+
+## The hook catches these mechanically
+
+Destructive verbs: reset, drop, delete, destroy, purge, prune, wipe,
+clean, truncate, flush, drain, evict, overwrite, revert, rollback,
+format, erase, clear, demolish, discard, abort, terminate, revoke,
+invalidate, expire, uninstall, deregister, detach
+
+Force flags: --force, --hard, -f, -rf, --yes, --no-verify
+
+Amplifiers: CASCADE, --all, --volumes, -r, --recursive, system
+
+## You catch what the hook cannot
+
+The hook is grep. It doesn't understand semantics. These are destructive
+but won't trigger the hook:
+
+- `redis-cli FLUSHALL` — "FLUSHALL" is now caught, but `redis-cli SET key ""` (overwriting data) is not
+- `kubectl apply -f destroy-everything.yaml` — "apply" is not destructive, the file is
+- `curl -X DELETE https://api.example.com/users` — HTTP DELETE is semantic
+- `psql -c "UPDATE users SET role = 'admin'"` — UPDATE isn't a destructive verb but this is dangerous
+- `echo "" > important-config.yaml` — echo and redirect, not a destructive verb
+- Piping data to a command that overwrites: `cat /dev/null > database.db`
+- Any SDK/API call that modifies production state
+
+**Your responsibility**: if the command modifies state that can't be
+trivially recreated, pause and answer the three questions. Don't wait
+for the hook. The hook is the safety net. You are the primary gate.
+
+## Severity guide
+
+| Signal | Action |
+|--------|--------|
+| Modifies local dev data | Pause, assess, proceed if justified |
+| Modifies shared/staging state | Pause, assess, confirm with operator |
+| Modifies production state | **STOP. Always require explicit human approval.** |
+| Irreversible at any level | Pause, verify backup exists, confirm with operator |

package/dist/lite/.claude/rules/diagnosis.md

@@ -0,0 +1,38 @@
+---
+tier: lite
+globs: ["*"]
+description: Three-step diagnosis before writing any fix
+---
+
+When a failure's cause is not immediately obvious, run diagnosis BEFORE writing any fix.
+
+Step 0 — Reproduce (RED anchor):
+  State the minimum repro command / URL / action that triggers the failure.
+  State observed vs expected. State environment. State reproducibility
+  (every time / intermittent / unable).
+
+  Without a repro, "I fixed it" has no counterpart "here's the thing it's not
+  doing anymore." The repro is the surface every subsequent step operates on.
+
+Step 1 — Is/Is Not (2 min):
+  Fill the table. What specific thing fails? What similar thing works?
+  This constrains the hypothesis space before touching code.
+
+Step 2 — Five Whys:
+  Trace to something changeable that prevents the CLASS of failure, not just this instance.
+  A timeout is a symptom. Missing observability is a root cause.
+
+Step 3 — Hypothesis + Test:
+  One sentence hypothesis. Minimum falsifiable check (a test, a log, a query).
+
+Output: diagnosis comment on the ticket BEFORE opening a fix PR.
+
+Skip criteria (all steps):
+
+  Skip full diagnosis ONLY when cause is immediately obvious and reproducible:
+  typo, missing env var, off-by-one. In these cases the repro is implicit in
+  the code change itself; state "Step 0 skipped — [reason]" in output.
+  Silence is not skip.
+
+  When in doubt, run it. Step 0 repro is cheap; the "unable to reproduce"
+  escalation is itself valuable signal.

package/dist/lite/.claude/rules/github-issue-flash-tweet.md

@@ -0,0 +1,114 @@
+---
+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.
+
+## 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.
+
+## 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

package/dist/lite/.claude/rules/guardrails.md

@@ -0,0 +1,73 @@
+---
+tier: lite
+globs: ["*"]
+description: Agent guardrails — behavior boundaries, escalation rules, capability ceilings for autonomous operation
+---
+
+# Agent Guardrails
+
+Formal behavior boundaries for autonomous agents. These are hard constraints,
+not guidelines.
+
+## What agents must NEVER do
+- Push to main without PR review
+- Delete data in production databases
+- Deploy to production without human approval — even in orchestrator-gated mode. This is the hardest guardrail. No exceptions.
+- Deploy to any environment not configured in substrate.config.md deploy_targets
+- Modify auth/security middleware without human approval
+- Expand scope beyond the declared time budget
+- Skip a hard gate (Inception → Elaboration → Construction → Transition)
+- Self-report gate compliance without evidence artifacts
+- Override another agent's decision authority (e.g., Builder overriding Architect on ADRs)
+- Send external communications (emails, Slack, webhooks) without human approval
+- Modify CI/CD pipeline configuration without human approval
+- Create or delete GitHub repos, branches on main, or release tags
+
+## What agents must ALWAYS do
+- Save state before ending (commit, push, LAST_SAVE)
+- Write a chronicle entry at session end
+- Run /temperance before non-trivial implementation
+- Run /verify after each task before committing
+- Flag ambiguity rather than proceeding with assumptions
+- Produce a substrate artifact at every handoff
+- Reference the iteration goal when starting work
+- Check the risk register at iteration start
+
+## Escalation rules
+- Builder → Architect for ADR questions
+- Builder → PM for scope questions
+- Builder → Designer for UX questions
+- Any agent → Orchestrator for sequencing disputes
+- Any agent → Human for: scope expansion, security changes, external communications, budget overruns
+
+## Capability ceilings by role
+- Reviewer: read-only. Cannot modify code.
+- Shaper: cannot implement or deploy.
+- PM: cannot implement or architect.
+- Designer: cannot implement. Validates only.
+- Creative Director: cannot implement. Directs only.
+- Architect: cannot implement in Construction. Designs only.
+- Builder: cannot override ADRs. Implements within constraints.
+- Deployer: cannot write application code. Ships only.
+- Closer: cannot build. Documents and closes only.
+- Orchestrator: cannot override any role's decision authority. Coordinates only.
+
+## Graceful exit conditions
+
+See `standards/graceful-exit.md` for the full exit protocol, checkpoint format,
+checkpoint triggers, and recovery procedure.
+
+Summary of conditions (full protocol in the standard):
+- Time budget exhausted → save state, write checkpoint, report progress, end
+- Budget limit reached → save state, write checkpoint, report, end
+- Ambiguity unresolvable without human → save state, write checkpoint, escalate, end
+- Blocked by external dependency → save state, log blocker in checkpoint, end
+- Error after 3 diagnosis attempts → save state, write checkpoint, escalate, end
+- User interrupts → save state immediately, write checkpoint
+- Context pressure ≥ 70% → write checkpoint, let compaction run, re-read survival kit
+
+## Agent identity in artifacts
+- Every commit by an autonomous agent includes the agent role in the message
+- Every PR created by an agent is labeled with the agent role
+- Chronicle entries note which agent(s) were active
+- This enables audit: who did what, with what authority