@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/standards/reserved-skill-names.md

@@ -0,0 +1,120 @@
+---
+tier: lite
+description: Bassclef MUST NOT create a skill with a name that Claude Code (the harness) already claims.
+---
+
+# Reserved Skill Names
+
+Bassclef MUST NOT create a skill with a name that Claude Code (the
+harness) already claims. Operator typing `/<name>` resolves to the
+harness built-in, not bassclef's skill — producing silent behavioral
+drift.
+
+This file is the **list**. The rule that references it lives at
+`.claude/rules/reserved-skill-names.md`. Separating the two lets the
+list evolve with Claude Code releases without churning the rule.
+
+## Reserved names (as of 2026-04-18)
+
+Source: Claude Code harness built-in skill registry observed in-session.
+
+### Claude Code operational built-ins
+
+These are always resolved by the Claude Code harness and will never
+reach bassclef's skill registry:
+
+| Name | Purpose (per harness) |
+|------|----------------------|
+| `update-config` | Configure Claude Code harness via settings.json |
+| `keybindings-help` | Keyboard shortcut customization |
+| `simplify` | Review changed code for reuse/quality |
+| `fewer-permission-prompts` | Scan transcripts + prioritize allowlist |
+| `loop` | Recurring prompt / slash-command execution |
+| `schedule` | Scheduled remote agents (triggers) |
+| `claude-api` | Build/debug Claude API / SDK apps |
+
+### Claude Code "FEY" remote built-ins
+
+Sourced from `FEY` array in Claude Code `cli.js`:
+
+| Name | Purpose (per harness) |
+|------|----------------------|
+| `autopilot` | Autopilot mode |
+| `bugfix` | Remote bugfix workflow |
+| `dashboard` | Remote dashboard |
+| `docs` | Docs workflow |
+| `investigate` | Investigation workflow |
+
+### Claude Code init/setup
+
+| Name | Purpose (per harness) |
+|------|----------------------|
+| `init` | Initialize a new CLAUDE.md file |
+| `review` | Review a pull request |
+| `security-review` | Security review of pending changes |
+
+## What the rule enforces
+
+Any new `.claude/skills/<name>/SKILL.md` introduced by a PR MUST NOT
+use a name from this list. The pre-commit hook blocks commits that
+add a colliding directory. See `.claude/rules/reserved-skill-names.md`
+for full enforcement semantics.
+
+## Updating this list
+
+Triggers that justify adding a name:
+
+- New Claude Code release adds a slash-command built-in not listed here
+- Observed behavioral drift where a bassclef skill name was silently
+  overridden by the harness
+- Upstream Anthropic documentation announces a reserved prefix or name
+
+Process:
+
+1. Verify the collision exists (type `/<name>` in a clean session,
+   observe the harness responds without reaching bassclef)
+2. Add the row to the table above with purpose description
+3. Bump the date in the heading ("as of YYYY-MM-DD")
+4. File a bassclef issue if any existing bassclef skill uses the
+   newly-colliding name — that skill MUST be renamed before the rule
+   addition merges
+
+## Verification
+
+Test case for the pre-commit hook lives at
+`.claude/hooks/tests/reserved-names-test.sh`. Run via:
+
+```bash
+bash .claude/hooks/tests/reserved-names-test.sh
+```
+
+Tests:
+- Hook blocks commit staging `.claude/skills/docs/SKILL.md` (collision)
+- Hook permits commit staging `.claude/skills/docs-v2/SKILL.md` (no collision)
+- Hook respects `SKIP_RESERVED_NAMES=1` override
+
+## Override
+
+Rare case: bassclef deliberately wants to shadow a harness built-in
+(e.g., wraps or replaces the built-in). Requires:
+
+1. Explicit operator confirmation in PR body
+2. `SKIP_RESERVED_NAMES=1` env var on the commit
+3. Rationale documented in the skill's SKILL.md frontmatter
+
+The override exists because rules should not be unjudgeable — but the
+friction is deliberately high.
+
+## Relationship to other standards
+
+- `standards/substrate-config-schema.md` — external resource reference
+  conventions (orthogonal)
+- `.claude/rules/reserved-skill-names.md` — the rule that reads this list
+- `.claude/hooks/pre-commit-gate.sh` — mechanical enforcement
+
+## When to retire this list
+
+If Claude Code ships a mechanical API to query reserved names at
+runtime (e.g., `claude --list-builtins --json`), this static list can
+be replaced with a dynamic check. Until then, the list is the
+interface.

package/dist/lite/standards/scannable-multi-option-output.md

@@ -0,0 +1,265 @@
+---
+tier: lite
+standard: scannable-multi-option-output
+status: accepted
+authoring_luminaries:
+  primary:
+    - don-norman
+    - sophia-prater
+  supporting:
+    - jesse-james-garrett
+    - edward-tufte
+description: Design principles for skills that render multi-option choice surfaces (e.g.
+---
+
+# Scannable multi-option output
+
+Design principles for skills that render multi-option choice surfaces (e.g. `/longrun prep`, `/sprint` Step 7). The principles below apply when the output stacks 3-5 tables covering options + trade-offs + steps and the operator needs to scan + pick fast.
+
+## Sources read
+
+- `.claude/luminaries/don-norman.md` — signifiers + mapping + feedback + constraints
+- `.claude/luminaries/jesse-james-garrett.md` — five planes of UX (strategy + scope + structure + skeleton + surface)
+- `.claude/luminaries/sophia-prater.md` — OOUX (objects first) + progressive disclosure
+- `.claude/luminaries/edward-tufte.md` — data-ink ratio + small multiples + sparklines + glyph encodes data
+- `docs/personas/sam.md` L33 — "I skim first, dig second, bail third."
+- `docs/personas/2026-07-12-bet11c-louis.md` L25 — "Skims group headings first."
+- Ticket #853 — the filing case for this discipline
+- Bet 24e — this extension adds Tufte + Prater + card template + glyph legend + progressive disclosure
+
+## Readers we design for
+
+Two personas set the bar.
+
+- **Sam** has a 15-30 min Saturday budget. He bounces on friction. He skims, digs, bails.
+- **Louis** skims group headings first. He opens a section only when this week's work needs it.
+
+Both punish output that hides structure or repeats content across tables.
+
+## The Norman + Garrett debate
+
+### Norman on signifiers + feedback
+
+Sam bounces on friction. His scan budget cannot afford re-reading the same table twice. Louis skims headings first. Headings ARE the affordance. No heading means no affordance. Signifiers must be OBVIOUS on first scan.
+
+On a refinement, delta rendering IS the feedback loop. Silent rebuild breaks the loop.
+
+Mapping — one anchor for one concern. Never one anchor for three tables.
+
+### Garrett on the five planes
+
+Stacked tables live at the skeleton plane. That is where things are placed.
+
+A first-cut prep output mixes four planes in one visual block. Strategy plus scope plus structure plus skeleton. Mixed planes break the five-planes rule.
+
+Give each plane its own `###` anchor. Reader scans anchors. Reader opens the one they need.
+
+## The Tufte + Prater debate (bet 24e extension)
+
+### Prater on OOUX
+
+Each option is an object. Each object has attributes — Problem, Value, Compounds, Adopter, Risk. Rendering one attribute per table forces the reader to reassemble the object in their head. Schema-mirror UX. The interface should mirror the reader's mental model.
+
+One card per option. Object first. Attributes inline with bold labels. Progressive disclosure — options at first glance; step detail expands only for the option the reader picks.
+
+### Tufte on data density
+
+The 5-table stack is chartjunk. Every cell repeats option labels + carries one axis. Data-ink ratio is low. Same shape repeated per option is small multiples — belongs in one dense structure.
+
+Glyphs encode data, not decoration. Color IS the data (🟢 low / 🟡 medium / 🔴 high). Sparkline analog — a single glyph beats a cell full of prose.
+
+Progressive disclosure serves data-ink too. Do not render step detail for options the operator will not pick.
+
+## Synthesized principles
+
+Twelve principles the four lenses agreed on. Skills that render multi-option surfaces MUST follow them.
+
+1. **One anchor per concern.** `###` header before each block. Anchor names the plane or concern.
+2. **Bold anchor pattern for sub-blocks.** Where an `###` header would be too heavy, use bold anchor plus blank line.
+3. **Delta rendering on refinements.** When operator asks "add column X", render ONLY the new column with reference to the source anchor by name.
+4. **Horizontal rule between planes.** `---` separates strategy from structure from skeleton. Not between every table.
+5. **Whitespace floor.** At least 2 blank lines OR one HR between top-level anchors.
+6. **Recommendation always at end.** One sentence citing compounding sequence + risk class.
+7. **Compact scan-table first** (Tufte). 4-6 columns, one row per option, glyphs encode risk + compounding rate. Reader scans + picks in 20-30 seconds.
+8. **One card per option** (Prater OOUX). Each card carries Problem + Value + Compounds + Adopter + Risk inline with bold labels.
+9. **Steps rendered only for the recommended option** (Prater + Tufte). Progressive disclosure. Not for all 3 options.
+10. **Problem + Value inline in every option card AND every step card.** Names the user pain the option or step addresses.
+11. **Glyphs encode data, not decoration** (Tufte chartjunk rule). Only glyphs that carry a signal ship.
+12. **Delta rendering as inline callout** — "Added: change class (delta on § Options above)" + small table with only the delta cells.
+
+## Card template
+
+Every option card ships in this shape:
+
+```
+### <label> · <scope> · <turns> · <risk glyph> <risk word>
+
+**Problem** — <one sentence naming the user pain this option addresses>
+**Value** — <one sentence naming what the operator gets>
+**Compounds** — <axis 1> · <axis 2> · <axis 3> · <axis 4> · <axis 5>
+**Adopter** — <mechanism> · <visibility> · <action required>
+**Risk** — <glyph> <severity> — <what could fail; who catches it>
+```
+
+Every step card ships in this shape:
+
+```
+### Step <N> · <slug> · <turns> · <risk glyph> <risk word>
+
+**Problem** — <one sentence naming the pain this step solves>
+**Produces** — <artifact path or decision>
+**Consumes** — <prior step + shared state>
+**Teaches** — <pattern later work reuses>
+**Risk** — <glyph> <severity> — <what could fail; who catches it>
+```
+
+## Glyph legend
+
+Only glyphs that encode data. No decoration.
+
+| Glyph | Meaning |
+|---|---|
+| 🟢 | low risk — CI catches it; no adopter impact; under 15 min to fix |
+| 🟡 | medium risk — needs a rebuild cycle; local rollback; under 2h to fix |
+| 🔴 | high risk — adopter sees the drift; compat shim or release rollback; over 2h to fix |
+| · | axis separator inside an inline value list |
+| § | reference to a named section anchor in delta callouts |
+
+Bands anchor to Klein premortem (imagined failure mode names the risk), Tufte data density (glyph + one line captures severity + cause + detection), and Maurya riskiest-assumption (one risk per option; the biggest one).
+
+Words carry compounding rate — `per-adopter`, `per-session`, `one-time`, `per-quarter`. Arrows and other decorative glyphs stay OUT.
+
+## Progressive disclosure — the rule
+
+Compact scan-table + per-option cards render for ALL options. Step cards render ONLY for the recommended option.
+
+When operator picks a different option, step cards for that option render on the next turn. On operator ask ("show steps for B and C too"), expand for all.
+
+Rationale — data-ink and reader attention are finite. Rendering steps for options the operator will not pick is chartjunk.
+
+## Delta rendering — the anti-pattern and the cure
+
+Silent rebuild:
+
+> Operator — "add a change-class column"
+> Agent — re-renders all 4-5 tables verbatim plus one new column
+
+Named delta:
+
+> Operator — "add a change-class column"
+> Agent — "Adding column to § Options above:"
+> [renders only the new column with the option labels]
+
+Full re-render is correct only when the operator asks for it explicitly ("show me the full picture again") OR the underlying option set changed.
+
+## When to apply this standard
+
+- `/longrun prep` — Steps 1.4c + 1.4d cite this standard
+- `/sprint` Step 7 — Steps 7a + 7b cite this standard
+- Any future skill that renders 3+ option tables with trade-offs
+
+## Canonical example — recommendation-first shape (per bassclef-web#152)
+
+The example below shows the shape the substrate targets. Reader sees the pick in the first 15 lines. Scan table follows. Card for the recommended option only.
+
+### Anti-pattern — decision buried below 5-axis blocks
+
+```
+[Three-block opener — Problem + Value + Evidence]
+
+## Options
+
+| Option | Scope | Turns | Compounds | Risk |
+|---|---|---|---|---|
+| a | Full six-amendment ship | 150-250 | per-session | med |
+| b | Narrow four amendments | 100-150 | per-session | low |
+| c | Adjacent install.sh | 40-80 | per-adopter | med |
+
+## Compounding value per option
+
+**Option a:** [5-axis block, ~10 lines]
+**Option b:** [5-axis block, ~10 lines]
+**Option c:** [5-axis block, ~10 lines]
+
+## Recommended card for Option a
+
+[Card ~15 lines]
+
+## Steps for Option a
+
+[Step cards ~20 lines]
+
+## Recommendation
+
+Recommend Option a because Y.
+
+Reply a, b, or c.
+```
+
+Reader scrolls past ~80 lines of options + axes + cards + steps before reaching the pick.
+
+### Conformant — recommendation first, cards on demand
+
+```
+[Three-block opener — Problem + Value + Evidence]
+
+## Recommendation
+
+**Recommend:** Option a (six-amendment ship · 150-250 turns · risk 🟡) because per-session compounding beats Option c's per-adopter frequency, and Option b defers /build value by one cycle.
+
+## Options
+
+| Option | Scope | Turns | Compounds | Risk | Why not (non-rec.) |
+|---|---|---|---|---|---|
+| a | Full six-amendment ship | 150-250 | per-session | 🟡 | rec |
+| b | Narrow four amendments | 100-150 | per-session | 🟢 | drops /build value |
+| c | Adjacent install.sh | 40-80 | per-adopter | 🟡 | drops baseline branch |
+
+## Compounding value per option
+
+[5-axis block per option — same as anti-pattern; hook postcondition per compounding-sequence-fresh-analysis.md requires per-option coverage today; hook extension to recommended-only lives at follow-on ticket per bassclef-web#152]
+
+## Recommended · full · 150-250t · 🟡
+
+[Card — Problem / Value / Compounds / Adopter — for Option a only]
+
+## Steps for Option a
+
+[Step cards — for Option a only]
+
+Reply a, b, or c. Ask for "cards for B and C" to expand.
+```
+
+Reader sees the pick in the first 8 lines. Scan table follows for context. Cards + step cards on demand for non-recommended.
+
+### Anchor luminaries for the reshape
+
+- **Sophia Prater (OOUX + progressive disclosure)** — recommended card renders by default; non-recommended cards expand on operator ask
+- **Donald Norman (signifier)** — the recommendation sentence IS the signifier for the decision; place it where the eye lands first
+- **Edward Tufte (data-ink)** — glyphs (🟢/🟡/🔴) encode risk in one character per scan-table cell; drops paragraph prose per option
+- **Jason Fried (say less)** — non-recommended options ship rationale in the `Why not` column; no per-option card
+- **Amazon PR/FAQ (decision at top)** — working-backwards discipline; reader sees "we recommend X because Y" first
+
+### Table character class
+
+Scan-table cells contain plain alphanumerics per `.claude/rules/visual-hierarchy.md` Section 12. Avoid em-dashes, backticks, quotes, or Unicode ellipsis in cells — Claude Code TUI falls back to key-value paragraphs when these characters appear. Cure per character in the sister rule catalog.
+
+## Refs
+
+- Ticket #853 — the filing case
+- `.claude/luminaries/don-norman.md`
+- `.claude/luminaries/jesse-james-garrett.md`
+- `.claude/luminaries/sophia-prater.md`
+- `.claude/luminaries/edward-tufte.md`
+- `docs/personas/sam.md`
+- `docs/personas/2026-07-12-bet11c-louis.md`
+- `.claude/skills/longrun/SKILL.md` Steps 1.4c + 1.4d + 1.5-1.7 (card refactor)
+- `.claude/skills/sprint/SKILL.md` Steps 7a + 7b (parity)
+- ADR-040 Decision 4 (SKILL body template shape — this standard offloads the debate content from SKILL bodies to keep template lean)
+- Bet 24d — original filing (principles 1-6)
+- Bet 24e — this extension (principles 7-12 + card template + glyph legend + progressive disclosure)
+- bassclef-web#152 — recommendation-first canonical example (adopter promote landing 2026-08-25)
+
+## Retirement
+
+Retires only if multi-option surfaces cease to be a bassclef output pattern.

package/dist/lite/standards/sdlc-compliance.md

@@ -0,0 +1,286 @@
+---
+tier: lite
+description: "Defines how gate evidence is captured, where it lives, and how it's queried."
+---
+
+# SDLC Compliance Tracking Standard
+
+Defines how gate evidence is captured, where it lives, and how it's queried.
+Replaces the previous trace-log approach (empty action/outcome columns,
+operational problems, now gitignored) with structured compliance data
+embedded in existing artifacts.
+
+---
+
+## Design Decision: Compliance in Chronicles, Not Separate Files
+
+Gate evidence lives **in the chronicle entry**, not in a separate compliance
+report. Rationale:
+
+1. Chronicles already capture what happened — compliance is "did the gates
+   fire during what happened?"
+2. A separate file creates drift — the chronicle says one thing, the
+   compliance report says another
+3. Chronicles are append-only and committed to git — they're auditable
+4. The previous trace-log approach failed because it was a parallel artifact
+   nobody maintained
+
+The trade-off: compliance data is less machine-queryable embedded in
+chronicles than in structured JSON. If machine querying becomes needed,
+extract it from chronicles rather than maintaining a parallel source of truth.
+
+---
+
+## Session Timing Fields
+
+Every chronicle entry includes timing metadata in the frontmatter.
+These fields close the feedback loop between time budget estimates and
+actual session duration, enabling calibration over time.
+
+### Frontmatter timing fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `started_at` | ISO 8601 datetime | SHOULD | Session start — derived from first commit timestamp or conversation start |
+| `ended_at` | ISO 8601 datetime | SHOULD | Session end — current time at chronicle write |
+| `duration_minutes` | integer | SHOULD | Approximate elapsed minutes (ended_at − started_at) |
+| `turns` | integer or `~N` | SHOULD | Approximate conversation turns this session |
+| `closes` | array of strings | MAY | Issues resolved this session, e.g., `["#37", "#42"]` |
+
+All timing fields are optional for backward compatibility — chronicles
+without them are valid historical records. Use `~` prefix for approximate
+values (e.g., `turns: ~40`).
+
+### Deriving timing data
+
+- `started_at`: First commit on the session's work, or conversation start
+  time if available. Approximate is fine — trend data, not billing.
+- `ended_at`: Current timestamp when the chronicle is written.
+- `duration_minutes`: Simple subtraction, rounded to nearest 5 minutes.
+- `turns`: Estimate from conversation length. Exact counting is fragile
+  and not worth the precision.
+
+---
+
+## Gate Evidence Format
+
+Every chronicle entry includes a **Gate Evidence** section after the
+narrative. This section records what gates fired and their outcomes.
+
+```markdown
+## Gate evidence
+
+| Gate | Fired | Evidence | Outcome |
+|------|-------|----------|---------|
+| Temperance | yes | Stated approach before first edit on feature/NNN | Proceeded — scope matched spec |
+| Diagnosis | n/a | Not a fix branch | — |
+| Pre-build spec check | yes | Spec at docs/specs/crm.md, referenced in iteration goal | Current |
+| Tests | yes | 12 unit, 3 integration, all pass | `npm test` exit 0 |
+| Visual review | yes | docs/visual-reviews/2026-04-07-deal-card.md | PASS WITH NOTES |
+| Verify | yes | Ran /verify after each task (3 tasks) | All passed |
+| Architect review | no — not due | Last review: 2026-04-05 (6 commits ago, threshold is 10) | — |
+
+### Gate skip justifications
+- Diagnosis skipped: feature branch, not fix branch (per sdlc-gates rule)
+```
+
+### Required fields
+
+| Field | Description |
+|-------|-------------|
+| Gate | Which gate (from `.claude/rules/sdlc-gates.md`) |
+| Fired | yes / no / n/a (with reason if no or n/a) |
+| Evidence | Where to find proof — file path, commit hash, or inline note |
+| Outcome | Result of the gate check |
+
+### Gate skip justifications
+
+If a gate was skipped, the reason must be stated. Valid reasons:
+
+- **n/a**: Gate doesn't apply (e.g., diagnosis on a feature branch)
+- **Degraded mode**: Infrastructure unavailable (e.g., Playwright MCP missing
+  for visual review) — must note what was done instead
+- **Assessed as trivial**: For diagnosis only — cause was immediately obvious
+  and reproducible. State the cause.
+
+Invalid reasons:
+- "Ran out of time" — gates are non-negotiable
+- "Will do later" — gates fire before commit, not after
+- No reason given — a bare "no" in the Fired column is a compliance failure
+
+---
+
+## Gates to Track
+
+These are the gates defined in `.claude/rules/sdlc-gates.md` and
+`strategy/agent-choreography.md` Section 9:
+
+### Pre-build gates (before writing code)
+
+| Gate | Trigger | Evidence format |
+|------|---------|----------------|
+| Temperance | First edit per branch | "Stated approach: [summary]" |
+| Diagnosis | All fix/ branches | "Is/Is Not completed, root cause: [summary]" or "Assessed as trivial: [cause]" |
+| Spec check | Before Construction | "Spec at [path], current as of [date]" |
+| Issue exists | Before branch creation | "Issue #NNN created/exists" |
+
+### Post-build gates (before committing)
+
+| Gate | Trigger | Evidence format |
+|------|---------|----------------|
+| Tests | Every commit with logic changes | "[N] unit, [M] integration, all pass" |
+| Verify | Every task completion | "Ran /verify — [outcome]" |
+| Visual review | Every UI change | "Report at [path] — [verdict]" |
+| Architect review | Every 10 commits or before launch | "Last review: [date], [N] commits ago" |
+
+### Session gates (phase/session boundaries)
+
+| Gate | Trigger | Evidence format |
+|------|---------|----------------|
+| Chronicle | Phase transition + session end | "Chronicle at [path]" |
+| Checkpoint | Exit conditions per graceful-exit.md | "Checkpoint at .claude/CHECKPOINT.md" |
+| LinkedIn draft | Notable decisions (SHOULD) | "Draft at [path]" or "No notable moments this session" |
+
+---
+
+## Iteration Goal Closeout
+
+When an iteration completes, append a **Closeout** section to the
+iteration goal file. This captures actuals vs time budget and gate compliance
+across the iteration's sessions — the feedback loop that calibrates
+future time budget estimates.
+
+### Closeout format
+
+```markdown
+## Closeout
+
+### Actuals vs appetite
+
+| Metric | Time budget | Actual | Delta |
+|--------|----------|--------|-------|
+| Turns | 40 | 52 | +30% |
+| Duration | ~1 session | 2 sessions (75m + 40m) | +1 session |
+| Issues closed | 3 | 2 | -1 (deferred #NNN) |
+
+### Gate compliance
+
+| Gate | Expected | Fired | Skipped | Notes |
+|------|----------|-------|---------|-------|
+| Temperance | 3 | 3 | 0 | — |
+| Diagnosis | 1 | 1 | 0 | fix branch |
+| Tests | 3 | 2 | 1 | 1 docs-only commit, n/a |
+| Verify | 3 | 3 | 0 | — |
+| Visual review | 0 | 0 | 0 | no UI changes |
+
+### Calibration notes
+
+[What was over/underscoped. Guidance for next similar iteration.
+Example: "Time budget was tight — the extraction script was underscoped.
+Next similar iteration: budget 50 turns."]
+```
+
+### When to write the closeout
+
+- When all acceptance criteria are met (or explicitly deferred)
+- Before writing the final chronicle for the iteration
+- The closeout data comes from the session chronicles' timing fields
+  and gate evidence tables — it's an aggregation, not a separate data source
+
+### Acceptance criteria for closeout
+
+The iteration goal's acceptance criteria checkboxes should be updated
+to reflect actual completion state. Deferred items get a note explaining
+why and a reference to the follow-up issue.
+
+---
+
+## Querying Compliance
+
+### Manual query (current approach)
+
+```bash
+# Find all chronicles with gate evidence
+grep -l "Gate evidence" chronicle/*.md
+
+# Find skipped gates
+grep -A 1 "no —\|no $" chronicle/*.md
+
+# Find visual review failures
+grep "FAIL" chronicle/*.md
+```
+
+### Architect review query
+
+During `/architect-review`, the Architect reads the last 5 chronicles
+and checks:
+
+1. Are all required gates present in each entry?
+2. Are there unexplained skips?
+3. Is there a pattern of degraded mode (infrastructure not available)?
+4. Are gate skip justifications valid?
+
+This is the primary compliance audit mechanism — it runs every 10 commits.
+
+### Future: structured extraction
+
+If machine-queryable compliance becomes needed:
+
+1. Extract gate evidence sections from chronicles into JSON
+2. Script: `scripts/extract-compliance.sh` → `docs/compliance/latest.json`
+3. Run on demand or as part of architect review
+4. The chronicle remains the source of truth; JSON is a derived view
+
+Do not build this until there's a real need. The architect review query
+is sufficient for current scale.
+
+---
+
+## Hook Integration
+
+### Existing hooks that produce gate evidence
+
+| Hook | What it captures | Where |
+|------|-----------------|-------|
+| `pre-build-gate.sh` | Temperance fired, diagnosis fired (fix branches) | Blocks the edit until gate clears |
+| `pre-commit` (if configured) | Tests pass, lint pass | Blocks the commit |
+| `session-end` / Stop hook | Chronicle written, checkpoint written | Fires at session end |
+
+### Agent responsibility
+
+Hooks capture mechanical gates (did the tool run?). The agent captures
+semantic gates (was the outcome meaningful?). Both are needed.
+
+The agent writes the gate evidence table in the chronicle. Hooks provide
+the enforcement that gates fire at all. Neither replaces the other.
+
+---
+
+## Compliance Failures
+
+A compliance failure is a chronicle entry where:
+
+1. A required gate shows "no" without a valid justification
+2. The gate evidence section is missing entirely
+3. Evidence references a file that doesn't exist
+
+### Response to compliance failures
+
+- **At architect review**: Flag the failure, check if it caused actual harm
+  (missed bug, broken deployment, etc.), recommend process fix
+- **At session start**: If the previous chronicle has a compliance failure,
+  note it in the current session's chronicle under "Entry state"
+- **Do NOT retroactively fix chronicles** — they're historical records.
+  Note the gap and prevent recurrence.
+
+---
+
+## Relationship to Other Standards
+
+| Standard | Relationship |
+|----------|-------------|
+| `.claude/rules/sdlc-gates.md` | Defines which gates exist; this standard defines how to track them |
+| `strategy/agent-choreography.md` | Section 9 defines MUST gates; this standard defines evidence format |
+| `standards/graceful-exit.md` | Checkpoint is a tracked gate at session boundaries |
+| `.claude/skills/chronicle/SKILL.md` | Chronicle skill should include gate evidence template |
+| `.claude/skills/architect-review/SKILL.md` | Architect review queries compliance from chronicles |