@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/standards/frontmatter-schema.md

@@ -0,0 +1,154 @@
+---
+tier: lite
+description: Schema for the YAML frontmatter that opens substrate files — .claude/skills/<name>/SKILL.md and .claude/rules/<name>.md.
+---
+
+# Frontmatter Schema
+
+Schema for the YAML frontmatter that opens substrate files — `.claude/skills/<name>/SKILL.md` and `.claude/rules/<name>.md`. Validated by `.claude/hooks/substrate-clarity-gate.sh` on Edit / Write (bassclef#862 Gap 1; WU-3 of bet 2026-06-18a).
+
+Without write-time validation, `tech_stack_match:` declarations from WU-8 + WU-9, future `composes_with:` + `depends_on:` declarations from WU-15, and ordinary skill description fields ship with typos or missing required fields and only surface in adopter sessions. This schema closes the gap at the authoring surface.
+
+## When the hook fires
+
+On any Edit / Write to:
+
+- `.claude/skills/<name>/SKILL.md`
+- `.claude/rules/<name>.md`
+
+Other substrate surfaces (luminaries, chronicles, iteration goals, decompositions, journal entries) keep their existing validation rules and do not gain frontmatter-schema enforcement in WU-3.
+
+## What the hook validates
+
+Three checks fire in order. The first to fail returns the exit code; further checks do not run.
+
+| Check | Outcome | Exit |
+|---|---|---|
+| Frontmatter present at top of file (starts with `---`) | Required for files NOT on allowlist; missing → BLOCK | 2 |
+| YAML parses cleanly | Malformed YAML → BLOCK | 2 |
+| Required fields present + non-empty | Missing required → BLOCK | 2 |
+| All field names are recognized | Unknown field → WARN; written to stderr | 0 |
+
+The hook continues running existing checks (description length, INSTEAD-block, jargon ladder) after the schema pass.
+
+## Skill schema
+
+Frontmatter required for every `.claude/skills/<name>/SKILL.md`.
+
+**Required fields:**
+
+- `name` — the skill's slash-command alias. Lowercase, hyphens, no spaces.
+- `description` — operator-readable one-liner. Length + verb-first + plain-language checks per `.claude/rules/skill-description-clarity.md`.
+
+**Recognized optional fields:**
+
+| Field | Used by | Type |
+|---|---|---|
+| `args` | skill body (operator-visible args reference) | string |
+| `authoring_luminaries` | skills that declare which luminary lenses shaped their design; picked via `/extract-intent` Voyage matching or `/pick-luminaries` | object (primary: list, supporting: list) |
+| `composes_baseline` | `/launch`, `/riff-prototypes`, `/frontend-design`, `/visual-review` | list[string] (luminary slugs) |
+| `composes_with` | future — WU-15 (bassclef#862 Gap 3) | list[string] (skill slugs) |
+| `depends_on` | future — WU-15 (bassclef#862 Gap 3) | list[string] (skill slugs) |
+| `deprecated` | retirement metadata | bool |
+| `deprecated_decision` | retirement metadata | string |
+| `deprecated_in_favor_of` | retirement metadata | string |
+| `disable_friction_check` | `/promote`-skip discipline | bool |
+| `disable_model_invocation` | Claude Code harness routing | bool |
+| `maturity` | skills declaring lifecycle stage — `alpha`, `beta`, `stable`, `hardened` per ADR-043 | string |
+| `model_tier` | per-agent LLM tier routing | string |
+| `modes` | mode-bearing skills (e.g., `/longrun`) | list[string] |
+| `no_user_modes` | mode-bearing-skill opt-out | bool |
+| `prereqs` | runtime prerequisites — richer shape per bassclef-web#94 | object (see prereqs schema below) |
+| `requires` | runtime prerequisites — older simpler shape | object (cli + network) |
+| `reserved_name_override` | reserved-name-shadow allow path | string |
+| `sizes` | size-bearing skills (e.g., `/value-prop`) | list[string] |
+| `tech_stack_match` | future — stack-bound skills | object |
+| `tiers` | tier-bearing skills (e.g., `/shape`) | list[string] |
+| `user_invocable` | Claude Code harness routing | bool |
+
+Unknown fields surface as WARN — adopter-authored fields might appear here; the warning surfaces the new field but does not block.
+
+## Prereqs schema (bassclef-web#94)
+
+The `prereqs:` block splits runtime prerequisites into required + optional buckets so docs sites can render a signifier per bucket. Skills without a `prereqs:` block still work — docs render a generic "check the skill body" fallback.
+
+```yaml
+prereqs:
+  required:
+    cli: [git, gh]
+    env: [ANTHROPIC_API_KEY]
+    network: true
+  optional:
+    cli: [jq]
+    env: [VOYAGE_API_KEY]
+    note: "VOYAGE_API_KEY enables semantic ranking; grep-only fallback works without."
+```
+
+Design rules per ticket:
+
+- Optional. Skills without the block still work.
+- 4-8 lines typical; 12 lines max. Docs sites render as a collapsed `<details>` block by default (progressive disclosure per Cooper).
+- Uses tool names adopters already know — `git`, `gh`, `python3`, `jq`, `curl`. No bassclef vocabulary.
+- Zero prereqs beyond "you have Claude Code running" — skip the block entirely.
+
+Relationship to `requires:`:
+
+- `requires:` is the older simpler shape (cli + network only). Existing skills that use it keep working.
+- `prereqs:` is the newer richer shape (required / optional split + env vars + note). Preferred for new lite skills.
+- No migration required. Both fields are recognized. Adopters pick per skill.
+
+Docs render logic is out of scope for bassclef — docs sites (Fumadocs or similar) read the manifest and render the signifier block. Bassclef's job is to define the schema and apply it as an exemplar.
+
+## Rule schema
+
+Frontmatter is OPTIONAL for `.claude/rules/<name>.md`. Many existing rules carry no frontmatter and start with the body directly. When frontmatter IS present, it must conform.
+
+**Required fields (when frontmatter is present):**
+
+- `description` — one-line operator-readable description of what the rule enforces.
+
+**Recognized optional fields:**
+
+| Field | Used by | Type |
+|---|---|---|
+| `composes_with` | future — WU-15 (bassclef#862 Gap 3) | list[string] |
+| `depends_on` | future — WU-15 (bassclef#862 Gap 3) | list[string] |
+| `globs` | rule-routing (which file paths the rule applies to) | list[string] |
+| `model_tier` | per-rule LLM tier routing | string |
+| `tech_stack_match` | per-stack rule routing (WU-8 + WU-9; future Phase 2 work) | object — admits `lang`, `frontend`, `backend`, `orm`, `pkg_manager`, `deploy` per `standards/tech-stack-config.md` |
+
+Unknown fields surface as WARN.
+
+Rules with NO frontmatter pass through validation entirely (the schema applies only when frontmatter is present). Authors adding frontmatter to legacy rules pick the required + optional fields as appropriate.
+
+## Allowlist baseline
+
+`.claude/hooks/substrate-frontmatter-allowlist.txt` grandfathers files that fail validation today with a 60-day grace window. Same shape as `testing-tier-enforce-allowlist.txt` per bassclef#1037.
+
+Format: `<repo-relative-path>|<grace-until ISO 8601>`.
+
+At WU-3 ship, the allowlist is empty — current files (75 skills + 19 rules with frontmatter + 33 rules without) all pass. The file ships with its header explaining the shape so future violators can be added with grace if/when they surface.
+
+## What this schema does NOT do
+
+- Does not enforce field VALUE shape beyond presence + non-empty. `tech_stack_match` content is not validated against the `tech-stack.schema.json` ranges shipped in WU-2. That richer validation lives in the consumer-side hooks that USE the field (future Phase 3 work).
+- Does not require frontmatter on legacy rules without one. 33 rules ship with no frontmatter today; the schema applies only when frontmatter IS present.
+- Does not validate luminary, chronicle, iteration-bet, decomposition, or journal-entry frontmatter. Those surfaces have their own checks in the same hook.
+- Does not catch description-quality issues — that's the existing `.claude/rules/skill-description-clarity.md` rule.
+
+## Override path
+
+`SKIP_SUBSTRATE_CLARITY=1` — same env var as the rest of the hook's checks. Logged via trace-helper. Use sparingly.
+
+## Refs
+
+- bassclef#862 Gap 1 — this schema closes it.
+- bassclef#382 — substrate-clarity-gate hook (parent of this validation pass).
+- WU-3 of bet `docs/iteration-bets/2026-06-18a-public-adopter-leverage-longrun.md` — ships the validation.
+- Sister WU-15 (bassclef#862 Gap 3) — adds `composes_with` + `depends_on` field schemas + targets-exist validation.
+- Pairs with `standards/tech-stack-config.md` (WU-2) — tech_stack_match values map to that schema's enums.
+- Sister discipline: `.claude/rules/testing-tier-config.md` (bassclef#1037) — allowlist baseline pattern.
+
+## Retirement condition
+
+This schema retires only if bassclef migrates off YAML frontmatter as a substrate convention. Field set evolves as new substrate fields ship (e.g., WU-15 introduces composes_with + depends_on into the recognized set).

package/dist/lite/standards/graceful-exit.md

@@ -0,0 +1,227 @@
+---
+tier: lite
+description: Defines how autonomous agent sessions save state, handle interruptions, and enable the next session to resume without data loss or ambiguity.
+---
+
+# Graceful Exit + Checkpointing Standard
+
+Defines how autonomous agent sessions save state, handle interruptions, and
+enable the next session to resume without data loss or ambiguity.
+
+This standard applies in all configurations. In orchestrator-gated mode it is
+enforced. In operator-gated mode it is advisory — the human is steering, but
+the checkpoint format is still useful.
+
+---
+
+## Exit Conditions
+
+Every agent must recognize the following conditions and respond with the
+prescribed action. Do not finish the current task before responding — respond
+immediately when the condition is detected.
+
+| Condition | Trigger | Required action |
+|-----------|---------|----------------|
+| Time budget exhausted | Turn count or duration reaches iteration ceiling | Save state, report progress, write checkpoint, end gracefully |
+| Budget limit reached | Cost ceiling hit (from cost-governance.md) | Save state, surface cost delta, write checkpoint, end |
+| Ambiguity unresolvable | Agent cannot proceed without a human decision that has not been delegated | Save state, write checkpoint with blocker stated, escalate to human |
+| Blocked by external dependency | A required artifact, credential, service, or decision from outside the session is missing | Save state, log blocker in checkpoint, end — do NOT work around |
+| Error after 3 diagnosis attempts | Three Is/Is Not + Five Whys cycles have not resolved the failure | Save state, escalate to Architect (Builder) or human, end |
+| User interrupts | Human interrupts the session at any point | Save state immediately, write checkpoint, report what is done |
+| Session idle timeout | Session has been inactive (platform-level) | Save state before context is lost |
+| Context window pressure ≥ 70% | Active context fills to 70% of limit | Write checkpoint NOW, let compaction run, re-read survival kit after |
+
+### What "save state" means
+
+1. Commit any in-progress work (even if incomplete — use `chore: wip` if needed)
+2. Clean up worktrees (see below)
+3. Write or update `.claude/CHECKPOINT.md` (see format below)
+4. Update `docs/whereami.md` to reflect current reality
+5. Push if network is available
+
+In that order. Steps 2-3 (worktree cleanup + checkpoint) must complete
+before end of session. If steps 4-5 fail, the checkpoint file alone is
+sufficient for recovery.
+
+### Worktree cleanup (MUST — if any worktrees exist)
+
+If the agent created or used worktrees during this session, clean them up
+before writing the checkpoint. See `standards/worktree-management.md` for
+the full protocol. Summary:
+
+1. For each worktree: commit work, push branch, remove worktree
+2. If removal fails (dirty state, locked files): note in checkpoint
+3. Never leave the session with active worktrees if avoidable
+4. The next session's pre-session audit will catch anything missed
+
+This is a MUST gate because stale worktrees cause branch locks, disk
+waste, and confusing state for the next session.
+
+---
+
+## Checkpoint Format
+
+**Location**: `.claude/CHECKPOINT.md`
+
+This file is overwritten on every checkpoint. It contains the latest state
+only — it is not a log. The chronicle is the log.
+
+```markdown
+# Checkpoint
+
+written_at: YYYY-MM-DDTHH:MM:SSZ
+session_id: (same as chronicle entry if one exists)
+exit_reason: (one of: appetite_exhausted | budget_limit | ambiguity | blocked |
+              error_escalation | user_interrupt | idle_timeout | context_pressure |
+              role_transition | phase_transition | periodic)
+
+---
+
+## Agent state
+
+active_agent: Builder
+task: Implementing SearchBar component per spec at docs/specs/crm.md#search
+status: in_progress   # done | in_progress | blocked
+
+### Done this session
+- Implemented DealCard component (commit abc1234)
+- Added unit tests for DealCard (commit def5678)
+- Updated design tokens for card treatment (commit ghi9012)
+
+### In progress
+- SearchBar component — skeleton written, filter logic incomplete
+  - File: src/components/SearchBar.tsx (partially complete)
+  - Blocking decision: none
+  - Estimated remaining: ~15 turns
+
+### Blocked
+(none — or state the blocker)
+
+### Artifacts produced this session
+| Artifact | Path | Commit |
+|----------|------|--------|
+| DealCard component | src/components/DealCard.tsx | abc1234 |
+| DealCard tests | src/components/DealCard.test.tsx | def5678 |
+| Design tokens | docs/design/tokens/card.md | ghi9012 |
+
+### Decision authority exercised
+- Accepted ADR-009 (component library choice) — no violations
+- Spec interpretation: SearchBar debounce = 300ms (inferred from interaction-design)
+
+---
+
+## Iteration state
+
+iteration_bet: docs/iteration-bets/2026-04-07-crm-build.md
+iteration_phase: Construction
+gate_checklist:
+  - [x] Spec exists and is referenced
+  - [x] GitHub issue open (#41)
+  - [x] Branch stack manifest written
+  - [ ] All tasks complete
+  - [ ] Reviewer sign-off
+  - [ ] Designer sign-off
+
+risk_register_changes: none this session
+
+budget:
+  turns_consumed: 14
+  turns_remaining: ~6 (estimate)
+  duration: ~22 minutes
+
+---
+
+## Handoff state
+
+next_agent: Builder (resume) | Reviewer (if all tasks done)
+resume_task: Complete SearchBar filter logic, then /verify, then open PR
+
+### Survival kit (what the next agent MUST read before starting)
+1. docs/iteration-bets/2026-04-07-crm-build.md — scope + acceptance criteria
+2. docs/specs/crm.md — current spec
+3. strategy/agent-choreography.md Section 9 — MUST gates
+4. docs/whereami.md — current phase and subsystem status
+5. docs/branch-stacks/2026-04-07-crm-stack.md — branch dependencies
+6. .claude/agents/builder.md — luminaries + checkpointing rules
+
+### Context the next agent needs
+- SearchBar is branch `feature/41-crm-search`, PR not yet open
+- DealCard PR is open (#38), awaiting Reviewer
+- Design token values are in docs/design/tokens/card.md — read before building
+
+### Blockers for the next agent
+(none — or state them clearly)
+```
+
+---
+
+## Checkpoint Triggers
+
+Checkpoints fire in two modes: event-driven and periodic.
+
+### Event-driven triggers (fire immediately when the event occurs)
+
+| Event | Who triggers |
+|-------|-------------|
+| Any exit condition (see table above) | Active agent |
+| Role transition (any agent hands off to another) | Outgoing agent, before signaling completion |
+| Phase transition (Inception → Elaboration, etc.) | Orchestrator, after gate validation |
+| Context pressure ≥ 70% | Active agent (self-monitored) |
+
+### Periodic trigger
+
+Every 20 turns (configurable in substrate.config.md as `checkpoint_interval`).
+If no `checkpoint_interval` is set, default is 20 turns.
+
+The periodic trigger exists because event-driven triggers rely on the agent
+recognizing the event. Long tasks can drift without triggering any event.
+The periodic checkpoint ensures a recovery point always exists within 20 turns.
+
+### What to skip
+
+Do NOT write a checkpoint for trivial tool calls (read, grep, glob). A
+checkpoint is a meaningful state save — it fires at the granularity of
+"completed or partially completed a task," not at every action.
+
+---
+
+## Recovery Protocol
+
+When a session starts after a previous session ended abnormally (or was
+interrupted), the Orchestrator (or the operator in operator-gated mode) checks for a
+checkpoint before scheduling any work:
+
+1. Check if `.claude/CHECKPOINT.md` exists
+2. If it exists: read it, read `docs/whereami.md`, reconcile any gaps
+3. Present to operator:
+   ```
+   Last session stopped: [exit_reason] at [written_at]
+   Active agent was: [agent] working on [task]
+   Done: [list from checkpoint]
+   In progress: [list from checkpoint]
+   Blocked: [list from checkpoint]
+   Resume from here, or restart from last clean gate?
+   ```
+4. On resume: activate the agent named in `next_agent`, point it at the
+   survival kit files listed in the checkpoint
+5. On restart: operator decides what to keep. Delete checkpoint after restart
+   to avoid stale state
+
+The checkpoint is advisory — the operator always decides whether to resume
+or restart. Never resume silently without presenting the checkpoint summary.
+
+---
+
+## Relationship to Other Standards
+
+| Standard | Relationship |
+|----------|-------------|
+| `strategy/agent-choreography.md` | Sections 10 and 12a define when to checkpoint; this standard defines how |
+| `.claude/rules/guardrails.md` | Exit conditions in guardrails reference this standard for protocol |
+| `.claude/skills/session-end/SKILL.md` | Session-end reads the checkpoint if present; incorporates it into the chronicle |
+| `standards/branch-stacking.md` | Branch stack manifest is part of the survival kit for Construction checkpoints |
+| `docs/whereami.md` | Updated at every checkpoint; the checkpoint and whereami are complementary |
+
+The checkpoint captures **agent-level state** (what this agent was doing, what's
+done, what's next). Phase-state captures **project-level state** (phase, iteration,
+subsystem maturity). Both must be current for a clean recovery.

package/dist/lite/standards/hook-idempotency.md

@@ -0,0 +1,102 @@
+---
+tier: lite
+description: Hooks must be idempotent. If a hook fails partway and reruns, it must not duplicate work, generate false warnings, or corrupt state.
+---
+
+# Hook Idempotency Standard
+
+## Principle
+
+Hooks must be idempotent. If a hook fails partway and reruns, it must
+not duplicate work, generate false warnings, or corrupt state.
+
+## Rules
+
+### 1. No write-then-detect
+
+A hook must not write state and then check for that state in the same
+execution. The classic violation:
+
+```bash
+# BAD: writes SESSION_LOCK, then detects it and warns "another session active"
+echo "$(date)" > .claude/SESSION_LOCK
+if [ -f .claude/SESSION_LOCK ]; then
+  echo "WARNING: another session may be active"
+fi
+```
+
+Fix: check BEFORE writing, or use a lock acquisition pattern:
+
+```bash
+# GOOD: check first, then write
+if [ -f .claude/SESSION_LOCK ]; then
+  echo "WARNING: another session may be active"
+else
+  echo "$(date)" > .claude/SESSION_LOCK
+fi
+```
+
+### 2. Append with dedup
+
+Hooks that append to files (trace logs, artifact lists) must check
+whether the content already exists:
+
+```bash
+# BAD: appends every run, creating duplicates on retry
+echo "gate: temperance" >> docs/sdlc-traces/today.log
+
+# GOOD: check before appending
+grep -q "gate: temperance" docs/sdlc-traces/today.log 2>/dev/null || \
+  echo "gate: temperance" >> docs/sdlc-traces/today.log
+```
+
+### 3. Create-if-missing, not create-always
+
+```bash
+# BAD: overwrites existing file on every run
+echo "# Risk Register" > docs/risk-register.md
+
+# GOOD: only create if missing
+[ -f docs/risk-register.md ] || echo "# Risk Register" > docs/risk-register.md
+```
+
+### 4. Exit codes are meaningful
+
+- Exit 0: hook succeeded, continue
+- Exit non-zero: hook failed, behavior depends on hook type
+  - PreToolUse hooks: non-zero blocks the tool call
+  - PostToolUse/Stop hooks: non-zero is logged but doesn't block
+
+Never swallow errors silently:
+
+```bash
+# BAD: hides failures
+some_command 2>/dev/null || true
+
+# GOOD: log the failure, then decide whether to continue
+some_command 2>&1 || echo "WARNING: some_command failed (non-blocking)"
+```
+
+### 5. Timeout awareness
+
+Stop hooks have limited execution time. If your Stop hook does
+network operations (git push, API calls), put them AFTER local
+operations so that local artifacts are saved even if the hook times out.
+
+```bash
+# Phase 1: Local (always completes)
+write_chronicle
+update_memory
+remove_session_lock
+
+# Phase 2: Remote (may timeout — that's OK)
+git push || echo "WARNING: push failed — run manually"
+push_to_gdoc || echo "WARNING: Google Doc push skipped"
+```
+
+Minimum recommended Stop hook timeout: 30 seconds.
+
+## Verification
+
+The `/substrate-check` skill includes a hook idempotency spot-check (step 8)
+that scans for common violations of these rules.