@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/rules/blocked-items.md

@@ -0,0 +1,146 @@
+---
+tier: lite
+description: "Session-start hook output may contain lines prefixed with BLOCKED:."
+---
+
+# Blocked Items — Mandatory Resolution
+
+Session-start hook output may contain lines prefixed with `BLOCKED:`.
+These are not suggestions. They are mandatory scope.
+
+## Protocol
+
+1. **Before proposing any new work**, scan session-start output for
+   `BLOCKED:` lines.
+2. Each blocked item MUST be either:
+   - **Resolved** in this session (run the command, write the artifact), OR
+   - **Explicitly deferred** by the operator ("skip metrics this session")
+3. If the operator says nothing about blocked items, the default is
+   **resolve them**. Silence is not deferral.
+4. Propose blocked items as the FIRST items in your session plan.
+   New iteration work comes AFTER blocked items, not instead of them.
+
+## What counts as resolution
+
+- `BLOCKED: release-notes` → run /release-notes, commit the output
+- `BLOCKED: metrics` → run the metrics script, commit the output
+- `BLOCKED: chronicle` → write the missing chronicle, commit
+- `BLOCKED: architect-review` → run /architect-review
+
+## What counts as explicit deferral
+
+The operator must say one of:
+- "skip [item]" / "defer [item]" / "not this session"
+- Acknowledging the item exists is NOT deferral
+- "okay" or "got it" is NOT deferral — it means resolve it
+
+## Friction during chained dispatches (bassclef#400)
+
+The `post-skill-friction-check.sh` hook fires on PostToolUse Skill for
+major composer skills (/stage (formerly /preview), /launch (formerly /preview-build), /build, /shape full,
+/longrun, /decompose, /spec, /architect-review, /interpret-input, etc.).
+It classifies output:
+
+- **Unambiguous friction** (`deferred to Phase X`, `stub return`,
+  `Error:`, `not yet implemented`) → log + recommend `/promote
+  substrate-defect` inline. Don't defer to closeout; file at the
+  boundary.
+- **Borderline friction** (`Lorem ipsum`, `XXX`, `FIXME`, partial
+  output) → log only; operator triages on return.
+- **No friction** → silent.
+
+The friction log lives at `docs/session-friction-log.md`. Operators
+returning from unattended runs read the log first; promote what's
+worth promoting.
+
+Per-skill opt-out: add `disable_friction_check: true` to skill
+frontmatter (rare; for skills whose stub returns are intended).
+Per-call override: `SKIP_FRICTION_CHECK=1 <command>` (logged).
+
+## When resolution reveals a substrate defect
+
+Sometimes resolving a BLOCKED item surfaces the real cause: the hook's
+detection path is wrong, a state file rotted, a marker format changed,
+or the compliance calculation reads a location the writer stopped
+using. The nominal work was done; the signal kept firing because the
+mechanism is broken.
+
+When this happens, resolution MUST include firing `/promote` with the
+`substrate-defect` classifier. Fix the local instance AND promote the
+mechanism fix — otherwise every consumer repo keeps hitting the same
+broken hook.
+
+### Trigger (any of)
+
+1. **Stuck signal resolved** — the signal was stuck per
+   `stuck-signal-diagnostic.md`, mechanism-read found a defect, defect
+   is now fixed. `/promote` fires automatically on this path.
+2. **Hook false-positive** — the banner fired even though the
+   underlying work was already done, and the fix was editing the hook,
+   not doing the work.
+3. **Counter miscount** — the number in the banner was wrong
+   (off-by-one, wrong window, stale cache), and the fix was editing
+   the counting mechanism.
+4. **Marker location rot** — a gate marker was written to a path the
+   reader no longer checks (e.g., `/tmp` sandbox teardown), and the
+   fix was dual-writing or relocating the marker.
+
+### Protocol
+
+1. **Resolve the local instance.** Land the substrate edit (hook fix,
+   rule update, path correction) in the current branch.
+2. **Fire `/promote`** — use the substrate-defect template in
+   `promote/SKILL.md`. The /promote issue cites:
+   - Signal observed (banner text + chronicle dates showing the loop)
+   - Mechanism file read (path + what was wrong)
+   - Fix applied (PR or commit ref)
+   - Propagation requirement (which consumer repos inherit; what
+     breaks if they don't pick up the fix)
+3. **Classify** as `agent-self-proposed` + `substrate-defect` (see
+   `promote/SKILL.md` label table). These don't need operator prompt —
+   agent-discovered defects file automatically because the trigger
+   condition (stuck signal + mechanism fix) is unambiguous.
+4. **Cite in the session's chronicle** with explicit "substrate defect
+   promoted: #NNN" line so retrospectives can audit the promotion
+   path worked.
+
+### Why mandatory (not MUST-try)
+
+`bassclef-evolution.md` already describes /promote as the promotion
+path. The gap being closed: when an agent finds a substrate defect
+mid-session and fixes only the local instance, the decision to
+promote becomes "nice to have" and rots. Three sessions in April 2026
+fixed local substrate drift without firing /promote; the same drift
+resurfaced in consumer repos two weeks later (POA inherited broken
+hook paths).
+
+Making /promote mandatory on the `resolution-revealed-defect` branch
+removes the decision. The agent doesn't choose whether to promote;
+the trigger fires it.
+
+### What doesn't trigger /promote
+
+- BLOCKED items resolved by doing the nominal work (running
+  `/release-notes`, writing the chronicle) — the mechanism was fine,
+  the work just wasn't done. No defect to promote.
+- Operator-overridden deferrals — the operator chose to skip; no
+  mechanism analysis happened.
+- One-off bugs in the agent's session (typo in commit message,
+  missed file) — those aren't substrate.
+
+The trigger is specifically "mechanism was broken, mechanism got
+fixed" — not "work was slow, work got faster."
+
+## Why this rule exists
+
+Agents consistently acknowledge hook warnings and then skip them.
+Three instances in 6 weeks: DORA metrics, metrics dashboard, release
+notes. The hook detects the problem correctly — the agent chooses to
+ignore it. This rule removes that choice.
+
+## Infrastructure note
+
+This is a methodology rule, not a hook. It works regardless of whether
+enforcement comes from bash hooks, Managed Agents outcome preconditions,
+or any other infrastructure. The hook produces the signal; this rule
+defines the response.

package/substrate/.claude/rules/branching.md

@@ -0,0 +1,28 @@
+---
+tier: lite
+globs: ["*"]
+description: Trunk-based development — branch naming and flow
+---
+
+Model: trunk-based development (solo variant). `main` is always deployable.
+
+Branch naming:
+- `feature/ISSUE-NNN-short-description`
+- `fix/ISSUE-NNN-short-description`
+- `spike/ISSUE-NNN-short-description`
+
+Every branch ties to a GitHub Issue. No branch without an issue.
+
+Flow: issue → branch from main → work → PR → CI passes → squash merge → delete branch
+
+Rules:
+- Broken main = drop everything
+- No branches older than 5 days — break it up
+- Force push on feature branches is fine, never on main
+- Semantic versioning tags for releases: v0.1.0, v0.2.0
+
+Multi-branch work (autonomous/multi-step sessions):
+- See `standards/branch-stacking.md` for stacked atomic branches
+- Stack manifest declares branches, dependencies, parallel-safety
+- Naming: `feature/ISSUE-NNN-stack-N-short-description`
+- Each branch is independently reviewable and revertable

package/substrate/.claude/rules/commit-conventions.md

@@ -0,0 +1,22 @@
+---
+tier: lite
+globs: ["*"]
+description: Commit message format — Conventional Commits
+---
+
+Format: `<type>: <description>`
+
+Types: feat, fix, docs, refactor, test, ci, chore, security
+
+Rules:
+- Imperative mood, lowercase, no period, max 72 chars
+- Body: explain WHY not what — the diff shows what
+- Footer: `Closes #NNN` or `Ref #NNN`
+- PR titles become squash commit messages — make them clean
+- One commit per PR on main (squash merge)
+
+## Forbidden prefixes
+
+Don't use `substrate-defect:` as a prefix. INSTEAD: use `fix:` per the type list above. Substrate bugs are bugs — the bassclef-internal `substrate-defect:` prefix duplicates the conventional `fix:` category without adding signal. See bassclef#1241 § "Wordlist amendment from 2026-06-19 dispatch session" for the decision.
+
+Don't invent one-off prefixes outside the 8 types listed above. INSTEAD: request additions via `/promote bassclef-evolution` so the type list grows by amendment rather than drift.

package/substrate/.claude/rules/context-engineering.md

@@ -0,0 +1,202 @@
+---
+tier: lite
+description: The single most leverage-y discipline in bassclef.
+---
+
+# Context Engineering
+
+The single most leverage-y discipline in bassclef.
+
+When you write a skill, rule, hook, luminary, or agent definition, you
+are writing instructions for a model that has specific epistemic
+constraints. The model can only act on information physically present
+in its current context window. Cross-session memory, knowledge of
+past generations, imagined norms, and unstated operator intent are
+NOT accessible.
+
+Every instruction must be actionable from information the agent has
+in this conversation. If the instruction depends on information the
+model can't see, it is a no-op at best, a footgun at worst.
+
+## Sources read
+
+Four anchors. Read them; this rule is the bassclef-substrate
+distillation, not a substitute.
+
+- **Andrej Karpathy — context engineering** ([X post, June 2025](https://x.com/karpathy/status/1937902205765607626)). The CPU/RAM mental model: "LLM is the CPU, context window is RAM." Reframes prompts as filling a finite working-memory buffer.
+- **Simon Willison — stateless tool framing** ([Mastodon thread](https://fedi.simonwillison.net/@simon/114757992443676572)). Endorsed and popularized "context engineering"; recurring theme in his blog: every conversation starts cold, training-cutoff dates are load-bearing, the model knows what it knows only via what's in the prompt.
+- **Anthropic — Effective context engineering for AI agents** ([anthropic.com/engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)). The model vendor's own articulation. Covers context window management, persistence patterns, tool design for agents. The **INSTEAD-block** specificity pattern is one application: every "DON'T do X" instruction needs a paired "INSTEAD do Y" the model can verify in its current context.
+
+For the broader 30-year canon of influences across distributed systems, methodology, strategy canvases, JTBD, use-case design, TDD, and rapid prototyping that bassclef embeds, see [`docs/philosophy.md`](../../docs/philosophy.md).
+
+## What the model has access to
+
+- Current conversation history (this session only)
+- Files in working directory (only when explicitly Read)
+- Tool results (when tools fire and return)
+- System prompt + loaded rules (whatever the harness injects, including the contents of `.claude/rules/` via `additionalDirectories`)
+- Memory directory (only if memory file is read this conversation)
+
+## What the model does NOT have access to
+
+- Previous conversations (unless that conversation's chronicle is loaded)
+- Prior generations of the same prompt (unless surfaced as text in current context)
+- What other agents are doing in parallel sessions (without state-spine reads)
+- Imagined "norms" or "averages" — the model can't compare against itself
+- Operator intent beyond what's been typed in this conversation
+- Prior commits / git log (without an explicit `git log` tool call)
+- Time / date awareness (the harness must surface today's date)
+
+## The INSTEAD-block pattern
+
+The rule's mechanical output, derived from Anthropic's context-engineering
+treatment. Every "NEVER" / "DON'T" / "AVOID" instruction is paired with an
+actionable substitute the model can verify in its current context.
+
+**Anti-pattern (unactionable):**
+
+```
+NEVER converge on common choices across generations.
+```
+
+→ Claude can't see other generations. Instruction has no in-context
+referent. No-op.
+
+**INSTEAD-block (actionable):**
+
+```
+INSTEAD: For each generation, deliberately commit to one bold
+direction from this list: [bold/saturated, moody/restrained,
+high-contrast/minimal, lo-fi/zine, handcrafted]. Pick a different
+direction than the obvious default for the input.
+```
+
+→ Model has the list in current context. Can pick. Actionable.
+
+**Format for bassclef instructions:**
+
+When writing a skill/rule/luminary, every "NEVER" / "DON'T" / "AVOID"
+gets paired:
+
+```
+NEVER do X.
+INSTEAD: <specific in-context action that produces the desired outcome>.
+```
+
+If you can't write the INSTEAD substitute, the original NEVER was
+unactionable — rewrite the whole instruction.
+
+## How bassclef operationalizes context engineering
+
+This is what bassclef IS. Every load-bearing component exists
+because the model is stateless. Map:
+
+| Stateless problem | Bassclef's answer |
+|---|---|
+| Agent forgets prior conversations | Chronicles (narrative log; written at session-end, read at session-start) |
+| Agent forgets project state | whereami (point-in-time snapshot; MUST-read at session start) |
+| Agent forgets goal scope | Iteration-bets (scope contract; MUST-read at iteration start) |
+| Parallel agents share no memory | State spine v0 (`lib/state.sh` accessors over JSON-on-git; flock-protected) |
+| Agent can't see prior generations | Champion-challenger pattern (alternative variants surfaced in same context) |
+| Gate evidence rots between sessions | Markers (`state/markers/` files; agent reads them, doesn't remember firing) |
+| Operator preferences drift | Memory system (`memory/` files; MEMORY.md index loaded each conversation) |
+| Recent decisions get lost | "Sources read" block (every artifact MUST cite what was Read) |
+| Compaction kills context | Survival kit (explicit re-read paths after compaction per `context-management.md`) |
+| Composer drifts from components | Section-heading contracts (bassclef#367 — pinned exact strings) |
+| Builder drifts from intent | Iteration-bet-brief-completeness rule (every artifact in handoff brief) |
+
+Without statelessness as the constraint, none of these would exist.
+That's not a feature — it's the substrate's purpose.
+
+## How to apply this rule
+
+### When writing a skill
+
+Ask, for every instruction:
+1. Does this reference information the model has in current context?
+2. If it references state that needs to be loaded — am I telling the model HOW to load it (Read X, run Y)?
+3. If it has a "DON'T" — is there an INSTEAD-block?
+4. Does it assume the model remembers something? If yes, am I providing the memory file path or instructing a Read?
+
+### When writing a rule
+
+Same checks plus:
+- Will this rule be loaded automatically (`additionalDirectories`)? If yes, the model has the rule body in context every conversation.
+- Or is it referenced by file path? If yes, I must explicitly tell the agent to Read it.
+
+### When writing a luminary
+
+The luminary file becomes context if invoked via `/luminary <slug>` or referenced in a skill that Reads it. Every "channel this luminary's discipline" instruction must produce concrete in-context actions, not aspirational adjectives.
+
+### When writing a hook
+
+Hooks fire at specific events and inject text into the agent's
+session output. The injected text IS context the model now has.
+Don't tell the model "remember this for next time."
+INSTEAD: write to a state file the next session reads.
+
+## What this rule does NOT cover
+
+- Cognitive-science research on "Theory of Mind in LLMs" (Kosinski, Bos et al.). That research tests whether LLMs *model human minds* — opposite direction from this rule. Cite this rule as "context engineering" (industry standard term) when discussing externally.
+- Tool design for agents (Anthropic's doc covers this in depth)
+- Memory systems beyond what bassclef implements
+
+## Common violations to grep for
+
+- `"don't repeat"` / `"don't drift"` / `"avoid converging"` — without INSTEAD substitutes
+- `"remember to"` / `"keep in mind"` — model has no persistence; you mean "Read X first" or "check Y"
+- `"based on prior sessions"` — the model can't see them; you must instruct chronicle Reads
+- `"the way you usually do"` — there is no usually; pin the specific pattern
+- `"use your judgment"` — what context does the model judge against? Specify or remove
+
+If `git grep -niE 'don.?t|never|avoid|remember to|keep in mind' .claude/skills .claude/rules .claude/luminaries` surfaces matches, audit each for INSTEAD-block discipline.
+
+## Relationship to other rules
+
+- `artifact-ingestion.md` — concrete instance of context engineering (Read before producing)
+- `iteration-bet-brief-completeness.md` — concrete instance (every artifact in brief, because receiver has no other state)
+- `mobile-ephemeral-session.md` — context engineering under the most extreme stateless conditions
+- `context-management.md` — operational guidance for context-window budgeting (companion at the runtime layer)
+- `bassclef#357` (autonomous-run flash + kiss) — output-side discipline; this rule is the input-side discipline
+- `bassclef#367` (section-heading standardization) — concrete instance of "if the parser greps for X, X must be in the producer's output")
+- `bassclef#382` (substrate-clarity-gate hook) — mechanical enforcement of skill-description clarity + rule/luminary INSTEAD-block discipline; closes the methodology+mechanism gap (rules prescribe; hook fires at PreToolUse Edit|Write)
+
+## Why this rule is the highest-leverage rule we have
+
+Most rules govern WHAT the agent should do (gates, checks, ceremonies). This rule governs HOW WE WRITE every other artifact. Meta-rule.
+
+Every future skill, rule, luminary, hook, and agent definition we add
+or modify is improved by this lens. Every existing artifact we audit
+against this lens is a candidate for cleanup.
+
+That's the leverage: one rule, applied retroactively + prospectively
+to the entire substrate.
+
+## Audit cadence
+
+- **Every new artifact** must pass the INSTEAD-block check before merge (PR-time gate, methodology-level)
+- **Quarterly substrate audit** — sample 10 artifacts at random, score against this rule, file findings
+- **Every `/promote`** — the promoting session checks the candidate against this rule before filing the issue
+
+## What this rule will NOT fix
+
+- Genuinely smart-but-vague creative direction ("make it beautiful") — context engineering catches *unactionable* instructions; whether the actionable substitute is *good* is a separate quality question handled by luminary-driven design + visual-review
+- Hook bugs (mechanical) — context engineering is methodology; hooks are mechanical enforcement
+- Operator-side ambiguity — if the operator's request is unclear, no amount of model-context discipline fixes it; that's a clarification gate
+
+## Override
+
+There is no override. Context engineering is the model's actual
+constraint, not a discipline we choose to follow. Violating it
+produces drift (silent or noisy), not "exceptional cases."
+
+If a rule or skill seems to require a context-engineering violation,
+the rule or skill is wrong. Rewrite.
+
+## Closes
+
+Filed in iteration-bet 2026-05-01-context-engineering-foundations
+(WU-1). First load-bearing application: WU-2 (Anthropic-frontend-
+design luminary written with INSTEAD discipline) + WU-5 (skill-
+description-clarity rule embeds the same pattern at the
+description-surface).

package/substrate/.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/substrate/.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/substrate/.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/substrate/.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