@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/standards/frontmatter-schema.md

@@ -1,154 +0,0 @@
----
-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/substrate/standards/graceful-exit.md

@@ -1,227 +0,0 @@
----
-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/substrate/standards/hook-idempotency.md

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