@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/skills/verify/SKILL.md

@@ -0,0 +1,160 @@
+---
+tier: lite
+name: verify
+description: Post-build verification gate — run after each task before committing. Matches change type to appropriate verification and writes a marker the pre-commit hook reads.
+problem: "Tests run but scope-drift and missed acceptance and ADR violations slip through."
+value: "Post-build gate that matches change type to check list. Runs before commit not after."
+inputs: [Change type or scope hint]
+outputs: [Check results per gate, Blocking findings, Ready-to-commit signal]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Verify
+
+## What you get
+
+Post-build verification gate. Run `/verify` after any task before committing code. I look at the type of change. I run the matching verification. I confirm the production build passes.
+
+When everything clears, I write a marker at `state/markers/verify/<branch>.marker`. The pre-commit-gate hook reads that marker. Without it, the hook blocks your commit. This is the check between "tests green" and "safe to ship."
+
+## When to use it
+
+After each task, before committing code. Not before you push. Not once per session. Each task.
+
+If you change a pure function, run `/verify`. If you touch a route, run `/verify`. If you edit middleware, run `/verify`. The change-type table maps what you touched to what verification fires. One skipped `/verify` is how broken production builds ship — POA session 2026-04-12 lost hours to 6 CI deploys that broke because someone assumed "tests pass = safe."
+
+Docs-only edits and config edits are the exception. State "docs/config only" in the summary and skip verification.
+
+## FAQ
+
+### What is the marker and why does it matter?
+
+The pre-commit-gate hook reads `state/markers/verify/<branch>.marker`. If the marker is missing or older than 5 minutes, the hook blocks the commit. The hook emits `BLOCKED: /verify` which the blocked-items rule requires you to resolve (run `/verify`) or explicitly defer (with stated rationale — silence is not deferral).
+
+The 5-minute window means re-running `/verify` refreshes the marker. Ephemeral sessions (mobile claude.ai/code) also write to `/tmp/claude-verify-<branch>` for desktop parity.
+
+### Do I need to run tests AND the production build?
+
+Both. Tests can pass while the production build fails. Vitest and Jest are permissive. The production build applies stricter rules — type narrowing catches, tree-shaking issues, bundler-specific module resolution, Next.js route-segment contract violations, strict null checks in inferred unions.
+
+If tests pass but the build fails, `/verify` fails. Do not commit. Do not write the marker.
+
+Evidence why this matters: POA session 2026-04-12 shipped 5 PRs (#480, #486, #488, #490, #492) with all tests passing locally. All 6 resulting CI deploys failed because the production build applied stricter rules. Prod stuck on the old image until hotfix — hours of reversed velocity.
+
+### What about UI changes and visual review?
+
+UI component or page changes MUST run `/visual-review`. The skill screenshots each page via Playwright MCP, evaluates against the usability standard and the complement luminaries, and outputs a report to `docs/visual-reviews/YYYY-MM-DD-<page>.md`. No report = do not commit.
+
+Empty state is NOT verification — seed data first. If Playwright MCP is unavailable, do the manual check and note "manual — no screenshot" in the report.
+
+### What about substrate-affecting changes?
+
+Any staged or recently committed change matching the 12 patterns from `.claude/rules/cold-adopter-harness-discipline.md` § "When this rule fires" — hooks, skills, rules, agents, luminaries, lib, standards, schemas, sync templates, ADRs, workflows, scripts — runs `bash scripts/cold-adopter-harness-sync.sh --mode sync --target .` and reports pass/fail. Exit 0 = pass; exit 2 = at least one check failed; exit 3 = setup failure.
+
+Override: `SKIP_COLD_ADOPTER_HARNESS=1 /verify` (logged via trace-helper). The pre-commit-gate hook and CI workflow fire the same matcher independently. Three layers together give the coverage you need.
+
+### What if I wrote the test after the code?
+
+State so in the summary — "test written after; check for tautology." Reviewer audits the test against Beck's four rules of simple design (all tests pass; code reveals intention; no duplication; fewest elements). A passing suite that reads as pattern-match against the code you already shipped is green but not done.
+
+### What if the change traces to a use case?
+
+If the change implements behavior spec'd in a fully-dressed use case at `docs/use-cases/UC-NNN-*.md`, `/verify` includes a traceability check. Every main-scenario step and every extension line maps to at least one test assertion. State the mapping in the summary: `UC-001:3a → test X, UC-001:3b → test Y`. Missing mappings are gaps; tests without use-case traceability are orphan coverage. Per @luminary alistair-cockburn (*Writing Effective Use Cases*).
+
+**Extended per #1171 — decomposition + interaction-design + IA-model traceability.** If the change traces to a decomposition at `docs/decompositions/*.md`, `/verify` checks the responsibility assignment stays inside the deep-module boundary named in the decomposition body. If the change traces to an interaction design at `docs/interaction-designs/*.md`, `/verify` checks the state or sequence diagram scope. If the change traces to an IA model at `docs/ia-models/*.md`, `/verify` checks the entity + task-flow scope. Deviations surface to operator with accept-or-reshape choice — matching the adr-deviation-challenge.sh hook pattern (matcher extended per #1171 to fire on OOAD artifact edits). Advisory in V1 per adr-deviation-challenge calibration pattern.
+
+## Details below the fold
+
+### Procedure
+
+**Step 1 — Identify change type.**
+
+Pick the row that matches what you just changed:
+
+| Change type | Minimum verification |
+|---|---|
+| Pure function (scoring, parsing) | Unit test passes for that function |
+| Worker / agent / queue | Boot the worker + process at least one real job |
+| API route | Hit the endpoint, verify response shape |
+| Schema migration | Verify column exists in DB, ORM client regenerated |
+| Refactor (same logic, new files) | Run the code path end-to-end |
+| Middleware / auth | Verify protected routes redirect AND existing routes still work |
+| Scraper / data source | Trigger one real scrape, verify data lands in DB |
+| Config / env var | Verify the service picks up the new value |
+| UI component / page | **MUST gate**: run `/visual-review` (see FAQ above) |
+| Substrate-affecting change | **MUST gate**: cold-adopter-harness-sync (see FAQ above) |
+| Lite SKILL body change | **MUST gate**: `bash .claude/hooks/tests/verify-lite-tier-resolution.test.sh` — every lite composes_with target resolves under the lite filter (Task 1.8) |
+| Docs / config only | N/A — state "docs/config only" |
+
+**Step 2 — Run verification.**
+
+Execute the row's command. Show the command and output.
+
+**Step 3 — Test check.**
+
+- New pure function → unit test exists and passes. State the test file.
+- Modified tested code → test suite passes. State the count.
+- No testable logic → state why (docs, config, UI-only).
+
+TDD discipline per @luminary kent-beck (*Test-Driven Development: By Example*): red / green / refactor — write the failing test first, make it pass with the minimum code, refactor with tests as safety net. Tests written after the fact confirm what exists, not what matters.
+
+**Step 4 — Production build check (MUST gate).**
+
+Run the project's production build command. Not just type check. Not just tests. Build commands per stack:
+
+- Next.js: `npm run build` (or `pnpm build`, `yarn build`)
+- Node service: `npm run build` or `tsc --noEmit` with prod tsconfig
+- Library: `npm run build`
+
+If tests pass but the production build fails, `/verify` FAILS. Do not proceed. Do not write the marker.
+
+**Step 5 — Write the marker.**
+
+When `/verify` passes end-to-end, write the marker to both locations:
+
+```bash
+BRANCH_SLUG=$(git branch --show-current | tr '/' '-')
+# Desktop marker (fast; survives session; not machine-ephemeral)
+touch "/tmp/claude-verify-${BRANCH_SLUG}"
+# Ephemeral-safe marker (git-tracked; survives sandbox death)
+mkdir -p state/markers/verify
+date -u +%Y-%m-%dT%H:%M:%SZ > "state/markers/verify/${BRANCH_SLUG}.marker"
+git add "state/markers/verify/${BRANCH_SLUG}.marker"
+```
+
+Re-running `/verify` refreshes both markers. Do NOT write the markers if any step failed. Tests passing but build failing = `/verify` FAILED = no marker.
+
+The git-tracked marker is authoritative in ephemeral sessions. Desktop sessions use either; both are checked by pre-commit-gate with the 5-minute freshness window.
+
+**Step 6 — Write the summary.**
+
+```
+## Post-Build Verification
+- Change type: [from table]
+- Verification performed: [exact commands + output summary]
+- Tests: [file + count, or "no testable logic"]
+- Build: [passes / fails]
+- Result: [PASS / FAIL — if FAIL, do not commit]
+```
+
+### Anti-patterns
+
+- "Unit tests pass" as sufficient for workers, routes, scrapers
+- Batch-verifying 5+ tasks at once
+- Skipping verification because "it's a small change"
+- Treating compilation as verification
+- Writing the marker when the production build failed
+
+### Refs
+
+- `.claude/hooks/pre-commit-gate.sh` — reads the marker; emits `BLOCKED: /verify`
+- `.claude/rules/blocked-items.md` — the resolve-or-defer protocol the block triggers
+- `.claude/rules/cold-adopter-harness-discipline.md` — the 12-pattern matcher for substrate changes
+- `.claude/skills/visual-review/SKILL.md` — the UI gate this skill calls
+- `.claude/luminaries/kent-beck.md` — TDD discipline anchor
+- `.claude/luminaries/alistair-cockburn.md` — use-case traceability anchor
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/.claude/skills/whereami/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: whereami
+description: "Show project state in one glance — phase, active goal, agents in flight, subsystem progress, gate checklist, freshness. Reads docs/whereami.md. Run at session start before /sprint to orient."
+problem: "Project state lives across whereami and iteration goals and chronicles and git. No single-glance view."
+value: "Phase and active goal and agents in flight and gate progress \u2014 one page."
+inputs: [Optional freshness flag]
+outputs: [Current phase and iteration, Active agents, Subsystem status, Gate progress]
+tier: lite
+user_invocable: true
+disable_model_invocation: false
+modes: [default]
+composes_with: [sprint, whats-the-plan]
+---
+
+# /whereami
+
+## What you get
+
+A one-glance answer to "where is the project right now?" read from `docs/whereami.md`. You see phase, goal, agents, subsystems, gates, and freshness. Scannable in about 20 seconds. The skill never writes. `/session-end` owns the writes.
+
+**Tier gate (bassclef#740 Task 1.8).** `/whats-the-plan` ships at `tier: standard`. Lite adopters skip it. Print skip note. Resolve tier via `lib/tier-check.sh`.
+
+## When to use it
+
+Type `/whereami` at session start. Type it when someone drops in cold. Type it when something feels off. Type it before `/whats-the-plan` so the plan cites the active goal.
+
+The skill also fires self-triggered at session start. That is the rule at `.claude/rules/whereami-load-bearing.md`.
+
+## When NOT to use
+
+Do not use `/whereami` for scope at ticket level. That is `/sprint`. Do not use it for dispatch-path planning. That is `/whats-the-plan`. Do not use it for wiring checks. That is `/substrate-check`. Do not use it to modify state. The skill is read-only.
+
+## FAQ
+
+### How does /whereami differ from /sprint, /whats-the-plan, and /substrate-check?
+
+Four skills, four altitudes:
+
+| Skill | Altitude | Output |
+|---|---|---|
+| `/whereami` | Project state | Phase + goal + agents + freshness |
+| `/sprint` | Ticket / scope | Open issues + proposed sprint |
+| `/whats-the-plan` | Dispatch path | Ordered skill chain |
+| `/substrate-check` | Wiring | PASS / WARN / FAIL on symlinks + hooks + CLIs |
+
+Session-start order: `/whereami`, then `/sprint`, then `/whats-the-plan`, then execute.
+
+### What does /whereami read?
+
+<!-- FKGL-EXEMPT: structured accessor spec -->
+Preferred is JSON via the accessor:
+
+```bash
+bash scripts/state.sh get whereami
+# or
+source lib/state.sh && state_whereami_get
+```
+
+Returns parsed JSON. Use this when `docs/whereami.json` exists (spine v0+).
+
+Fallback is markdown at `docs/whereami.md`. Body is operator narrative per `.claude/rules/accessor-library-discipline.md`.
+
+Schema at `standards/whereami-schema.md`. Spine v0 schema at `standards/state-spine/schemas/whereami.schema.json`. If both sources are missing or the session-start hook surfaced whereami-stale BLOCKED, resolve the BLOCKED first. Do not fabricate state.
+<!-- /FKGL-EXEMPT -->
+
+### What are the 8 schema sections?
+
+1. Project phase.
+2. Active goal (path, phase within goal, started date, previous goal, next goal).
+3. Active agents.
+4. Subsystem phases (table).
+5. Gate progress (by SDLC phase).
+6. Risk register pointer.
+7. Last updated (timestamp + session).
+8. Configuration pointer.
+
+### How does /whereami compute freshness?
+
+| Age of `last_updated` | Signal | Behavior |
+|---|---|---|
+| Less than 3 days | Green | Report normally |
+| 3-7 days | Warn | Report + flag refresh at session end |
+| 7 days or more | BLOCKED | Surface BLOCKED; refuse work until resolved |
+| Missing | BLOCKED | Suggest scaffolding from template |
+
+### What is the auto-update footer?
+
+<!-- FKGL-EXEMPT: structured render spec -->
+Reads `.bassclef-source.json` `auto_sync`. Defaults to `false` when the file or field is absent. Renders one:
+
+- "Auto-update: ON — your skills, rules, and agents stay current with bassclef at every session start."
+- "Auto-update: OFF — bassclef isn't pulling its own changes into your repo. Turn on any time by saying 'enable auto-sync' or editing `.bassclef-source.json`."
+
+This is Layer 1 of the Discovery Cascade per bassclef#939. Adopters see the off state on every orientation and opt in when ready.
+<!-- /FKGL-EXEMPT -->
+
+### What is the installed line?
+
+<!-- FKGL-EXEMPT: structured render spec -->
+Reads `.bassclef-source.json` `installed_sha` and `installed_at`. Renders one:
+
+- "Installed: abc1234 (3 days behind today) — 2026-06-13T08:30:00Z"
+- "Installed: abc1234 (up to date) — 2026-06-16T20:35:00Z"
+- "Installed: (no sync recorded — the next successful bassclef-sync will record installed_sha + installed_at)"
+
+Short SHA is the first 7 chars. Delta in days is `floor((now - installed_at) / 86400)`. Adopters see install version + staleness on every orientation.
+<!-- /FKGL-EXEMPT -->
+
+## Details below the fold
+
+<!-- FKGL-EXEMPT: procedure + spec content -->
+
+### Procedure
+
+**Step 1 — Read whereami.** `bash scripts/state.sh get whereami` for spine v0. Falls back to `docs/whereami.md` on pre-spine repos. If both fail or a whereami-stale BLOCKED fired, resolve BLOCKED first per `.claude/rules/blocked-items.md`.
+
+**Step 2 — Extract the 8 sections** listed above.
+
+**Step 3 — Compute freshness** per the FAQ table.
+
+**Step 4 — Report.** Scannable form. 20 seconds. Orientation, not a dump.
+
+### Output format
+
+```
+## Whereami — [repo-name] ([age of last_updated])
+
+**Phase**: [Inception | Elaboration | Construction | Transition]
+**Goal**: [goal name OR "between goals"]
+  ↳ Phase within goal: [Step N | "—"]
+  ↳ Started: [YYYY-MM-DD] | Previous: [goal path]
+**Active agents**: [role on branch OR "None"]
+
+**Subsystems**:
+| Subsystem | Phase | Last goal | Notes (first 6 words) |
+
+**Gate progress**:
+  Inception    ✅ COMPLETE (YYYY-MM-DD)
+  Elaboration  ✅ COMPLETE (YYYY-MM-DD)
+  Construction 🔄 IN PROGRESS ([N of M] items checked)
+  Transition   ⏳ PENDING
+
+**Next goal candidate**: [one-line from whereami next-goal field]
+
+**Last updated**: [ISO] ([N days ago]) — [session filename]
+
+---
+**Auto-update**: ON | OFF — [one-line state]
+
+**Installed**: [short_sha] ([N days behind today] | up to date) — [installed_at ISO date]
+```
+
+### Freshness block (prepended when applicable)
+
+- Warn (3-7 days): `whereami last updated N days ago; refresh at session end (MUST tier).`
+- BLOCKED (7+ days): `whereami-stale; resolve via session-start refresh OR defer explicitly.`
+- BLOCKED (missing): `whereami-missing; resolve by copying templates/whereami-template.md; then fill phase + goal + last_updated.`
+
+### Skipping and aborting
+
+- Read-only. Never modify `docs/whereami.md`.
+- If `last_updated` is unparseable: report WARN. Point at the schema.
+- If no active goal: report "between goals". Include the next-goal candidate from the schema.
+- If a schema section is missing: report WARN. Cite the schema. Do not invent.
+
+### Self-check step
+
+Before posting the report:
+
+1. Touch `state/markers/turn-prose-surface/status_update.marker`.
+2. Read the draft against `standards/bassclef-internal-jargon.md` BLOCK terms.
+3. Rewrite BLOCK matches in plain English.
+4. Post the response.
+
+The Stop hook `.claude/hooks/turn-prose-kiss-check.sh` catches misses.
+
+### Common failure modes
+
+- **Missing file.** No `docs/whereami.md` and no `docs/whereami.json`. Surface BLOCKED. Suggest the template. Operator fills phase + goal + last_updated.
+- **Stale entry.** `last_updated` more than 7 days old. Surface BLOCKED. Refuse work until refresh OR explicit deferral.
+- **Schema drift.** A section is missing or malformed. Report WARN. Cite the schema. Do not invent.
+- **Accessor unavailable.** `bash scripts/state.sh get whereami` fails on pre-spine repo. Fall back to markdown.
+- **Auto-update ambiguous.** `.bassclef-source.json` missing. Default to OFF. Render the opt-in path.
+
+### Grace window on old vocabulary
+
+Old planning-skill vocabulary still works through 2026-10-31. See `standards/vocabulary-migration.json` for the substitution table and `.claude/rules/we-dont-break-adopters.md` for the discipline. Existing schema field names keep working during the grace window; renamed field names ship in a sibling migration.
+
+<!-- /FKGL-EXEMPT -->
+
+## Examples
+
+<!-- FKGL-EXEMPT: sample output -->
+
+**Green orientation (fresh whereami, active goal):**
+
+```
+## Whereami — bassclef-upstream (2 hours ago)
+
+**Phase**: Construction
+**Goal**: 2026-07-19k — Shape e foundation
+  ↳ Phase within goal: WU-3 of 3
+  ↳ Started: 2026-07-19 | Previous: 2026-07-19j
+**Active agents**: Builder on feature/2026-07-19k-wu3-whereami-adr-044-refactor
+
+**Gate progress**: Construction 🔄 IN PROGRESS (7 of 12 items checked)
+
+**Next goal candidate**: #801 Wave 1 expansion (5 remaining Wave 1 skills)
+
+**Last updated**: 2026-07-19T22:15+0100 — 2026-07-19h-goal-19j-adr-044-unified-skill-template.md
+
+---
+**Auto-update**: ON — your skills, rules, and agents stay current with bassclef at every session start.
+
+**Installed**: 2ceb53b7 (up to date) — 2026-07-19T18:10:00Z
+```
+
+**Warn orientation (5 days since update):**
+
+```
+🟡 warn — whereami last updated 5 days ago (warn threshold: 3)
+         Refresh at session-end (MUST tier).
+
+## Whereami — bassclef-upstream (5 days ago)
+[normal output follows]
+```
+
+**BLOCKED orientation (missing file):**
+
+```
+🛑🛑🛑 BLOCKED 🛑🛑🛑
+whereami-missing — docs/whereami.md not found.
+Resolve: cp templates/whereami-template.md docs/whereami.md
+         (then fill phase + goal + last_updated)
+```
+
+<!-- /FKGL-EXEMPT -->
+
+## Anti-patterns and INSTEAD
+
+| Anti-pattern | INSTEAD |
+|---|---|
+| Rebuilding project state from session logs + git log each session | Read `docs/whereami.md` via the accessor |
+| Silencing a stale BLOCKED banner and proceeding | Surface the BLOCKED. Resolve or defer per rule |
+| Filling in plausible state for a missing section | Report WARN. Cite the schema. Do not fabricate |
+| Writing to `docs/whereami.md` from `/whereami` | Read-only. `/session-end` owns writes |
+| Dumping the full whereami content into the response | Scannable 20-second orientation. Reader opens the file for detail |
+
+## Composes with
+
+- `/sprint` — reads whereami as primary source. `/whereami` is the lighter surface.
+- `/whats-the-plan` — cites the goal and phase this skill surfaces.
+- `/session-end` — writes whereami at close. This skill only reads.
+- `/substrate-check` — validates schema conformance. This skill reports state.
+
+## Distinct from
+
+- `/sprint` — scope proposals at ticket level. Runs after `/whereami`.
+- `/whats-the-plan` — dispatch-path plan. Cites `/whereami` as input.
+- `/substrate-check` — wiring PASS / WARN / FAIL. Different question.
+- `/session-end` — writes whereami. `/whereami` never writes.
+
+## Rules
+
+- Orientation in one glance. Scannable, not a dump.
+- Read-only. Never writes. `/session-end` owns writes.
+- Always surface the hook's BLOCKED block. Do not silence stale or missing signals.
+- Composes with `/sprint` and `/whats-the-plan`. Whereami sits upstream.
+- No fabrication. Say so when a section is missing. Do not fill plausible state.
+
+## Test cases
+
+<!-- FKGL-EXEMPT: structured test spec -->
+| ID | Prompt | Expected behavior |
+|---|---|---|
+| T1 | `/whereami` on a fresh whereami (< 3 days) | Green orientation with all 8 sections + auto-update + installed |
+| T2 | `/whereami` when `last_updated` is 5 days old | Warn block prepended; normal output follows |
+| T3 | `/whereami` when `docs/whereami.md` is missing | BLOCKED block; scaffold suggestion; refuses work until resolved |
+| T4 | `/whereami` when a schema section is missing | WARN cite of schema; no invented content |
+| T5 | `/whereami` when `.bassclef-source.json` is absent | Auto-update: OFF default; opt-in path rendered |
+<!-- /FKGL-EXEMPT -->
+
+## Sources read
+
+- `.claude/rules/whereami-load-bearing.md` — session-start read discipline this skill honors
+- `.claude/rules/blocked-items.md` — BLOCKED protocol on stale or missing whereami
+- `.claude/rules/accessor-library-discipline.md` — accessor or direct read policy
+- `.claude/rules/plain-english-discipline.md` — master rule for output prose
+- `.claude/rules/we-dont-break-adopters.md` — vocabulary grace window
+- `standards/whereami-schema.md` — artifact format
+- `standards/state-spine.md` — accessor architecture
+- `standards/state-spine/schemas/whereami.schema.json` — spine v0 schema
+- `templates/whereami-template.md` — scaffolding source
+- `standards/bassclef-internal-jargon.md` — self-check wordlist
+- `.bassclef-source.json` — `auto_sync` and `installed_sha` source of truth
+- bassclef-upstream#939 — Discovery Cascade Layer 1 (auto-update footer)
+- bassclef-upstream#1037 WU-V4 — `installed_sha` + `installed_at` fields
+- ADR-040 planning-skill vocabulary and lite profile
+- ADR-044 unified SKILL body template
+
+## Why this skill exists
+
+Sessions that rebuild project state from session logs plus git log cost 20-40 turns per orientation. They also drift into the wrong active goal. Operators returning after a break need one file, one skill, one 20-second answer. `/whereami` makes that answer invocable. The rule at `.claude/rules/whereami-load-bearing.md` needs a mechanism, not just an obligation. Without `/whereami`, session-start orientation reproduces the archaeology anti-pattern the rule closes.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/AGENTS.md

@@ -0,0 +1,79 @@
+---
+tier: lite
+description: Cross-tool agent context for sunj-labs repos.
+---
+# Agents
+
+Cross-tool agent context for sunj-labs repos. This file is readable by
+Claude Code, Cursor, Copilot, and other AI tools — it's the universal
+agent briefing.
+
+## Active agents (10)
+
+| Agent | Role | Model | Tools | Authority |
+|-------|------|-------|-------|-----------|
+| Orchestrator | Air traffic control | haiku | Read, Write, Glob, Grep, Bash, WebSearch | Sequencing, routing. Cannot override any role's decisions. |
+| Shaper | Problem framing | opus (Inception) / sonnet | Read, Write, Glob, Grep, WebSearch | Scope, appetite, risk register. Cannot implement. |
+| PM | Commercial viability | sonnet | Read, Write, Glob, Grep, WebSearch | Value sequencing, viability hypotheses. Cannot implement or architect. |
+| Creative Director | Visual language | sonnet | Read, Write, Glob, Grep, WebSearch | Brand, tone, design tokens. Cannot implement. |
+| Architect | System design | sonnet | Read, Write, Glob, Grep, WebSearch | ADRs, C4 diagrams. Cannot implement in Construction. |
+| Designer | User experience | sonnet | Read, Write, Glob, Grep, WebSearch | UX judgment, concept validation. Cannot implement. |
+| Builder | Implementation | sonnet | All | Implements within ADR constraints. Cannot override ADRs. |
+| Reviewer | Code review | haiku | Read, Glob, Grep | Approve/block PRs. Read-only — cannot modify code. |
+| Deployer | Release management | haiku | Read, Write, Glob, Grep, Bash | Ships only. Cannot write application code. |
+| Closer | Administrative | haiku | Read, Write, Glob, Grep, Bash | Documents and closes. Cannot build. |
+
+## Restricted-permission agents (3)
+
+These agents have intentionally limited tool access for safety.
+
+### ReadOnly Explorer
+
+```yaml
+name: explorer
+tools: [Read, Glob, Grep]
+purpose: Codebase exploration and research without modification risk
+use_when: "Investigating unfamiliar code, answering questions about architecture, onboarding"
+```
+
+### Security Auditor
+
+```yaml
+name: security-auditor
+tools: [Read, Glob, Grep]
+purpose: Security review — scan for vulnerabilities, secrets, auth gaps
+use_when: "Pre-launch security review, dependency audit, auth matrix check"
+constraints:
+  - Read-only — cannot modify code, only report findings
+  - Checks against OWASP top 10, auth matrix, tenant isolation
+  - Reports to Architect for ADR-level decisions
+```
+
+### Docs Writer
+
+```yaml
+name: docs-writer
+tools: [Read, Write, Glob, Grep]
+purpose: Documentation only — chronicles, specs, release notes, READMEs
+use_when: "Session-end artifacts, backfill missing chronicles, write specs from canvases"
+constraints:
+  - Cannot run Bash commands
+  - Cannot modify source code (only .md files)
+  - Cannot create or modify hooks, skills, or rules
+```
+
+## Agent definitions
+
+Full agent definitions with luminaries, checkpointing rules, and
+persona details are in `.claude/agents/*.md`. This file is the summary
+for cross-tool consumption.
+
+## Guardrails
+
+All agents are bound by `.claude/rules/guardrails.md`:
+- Never push to main without PR review
+- Never deploy to production without human approval
+- Never expand scope beyond declared appetite
+- Never skip a hard gate
+- Save state before ending
+- Flag ambiguity rather than assuming

package/substrate/CLAUDE-lite.md

@@ -0,0 +1,85 @@
+---
+tier: lite
+description: What this is. A trimmed version of bassclef for solo adopters running one project. Ships 14 core skills plus 15 rules for session hygiene, safety, plain English, and PR shape. Full bassclef ships 90 skills and 76 rules for cross-project operators.
+---
+# bassclef-lite
+
+**What this is.** A trimmed version of bassclef for solo adopters running one project. Ships 14 core skills plus 15 rules for session hygiene, safety, plain English, and PR shape. Full bassclef ships 90 skills and 76 rules for cross-project operators.
+
+**How to think about it.** bassclef-lite gives you enough to run a session cleanly — open, orient, gate, do work, ship, close. As you outgrow it, upgrade to standard bassclef (all substrate, no changes needed on your end; just switch the source pointer).
+
+## Substrate (lite)
+
+| Component | Count | Location |
+|---|---|---|
+| Skills | 17 | `.claude/skills/*/SKILL.md` (14 core + 3 supporting: `kiss`, `value-prop`, `luminary`) |
+| Rules | 15 | `.claude/rules/*.md` (auto-loaded via `additionalDirectories`) |
+| Hooks | 14 | `.claude/hooks/*.sh` |
+| Standards | 20 | `standards/*.md` |
+| ADRs | 5 | `architecture/decisions/ADR-*.md` |
+| Agents | 4 | `.claude/agents/*.md` (architect, builder, designer, reviewer) |
+| Luminaries | 4 | `.claude/luminaries/*.md` |
+| Templates | 3 | `templates/*.md` |
+
+## Skills — 14 core
+
+Session lifecycle: `/onboard-repo`, `/whereami`, `/sprint`, `/skills`, `/howdoi`, `/session-end`, `/session-log`.
+Gates: `/temperance` (before work), `/verify` (after work), `/diagnose` (when it breaks).
+Do the work: `/longrun` (long sessions), `/state-a-problem`, `/release`, `/promote`.
+
+Supporting: `/kiss` (plain English), `/value-prop` (flash/tweet/brief), `/luminary` (design lenses).
+
+## Rules — 15 auto-loaded
+
+Session hygiene: `blocked-items`, `sdlc-gates`, `session-artifacts`, `artifact-ingestion`, `whereami-load-bearing`.
+Safety: `destructive-operations`, `state-schema-validation`.
+Composition: `skill-description-clarity`, `skill-composition-declarations`, `pattern-annotation`, `assert-only-after-verify`.
+Plain English: `plain-english-discipline`, `operator-facing-prose`.
+PR shape: `pr-body-shape`, `pr-strategy`.
+
+## SDLC flow
+
+```
+Canvas → Spec → Design → Issue → Branch → PR → CI → Deploy → Observe
+```
+
+Gates run before and after: `/temperance` before a non-trivial change; `/verify` after. `/diagnose` when something breaks.
+
+## Conventions
+
+- Conventional commits: `type: description` (feat, fix, docs, refactor, test, ci, chore, security)
+- One branch per issue; squash merge; delete branch after merge
+- PR titles ≤72 chars; PR bodies open with `**Problem (≤500 chars):**`
+
+## Key files
+
+- `.claude/rules/sdlc-gates.md` — the gate protocol
+- `.claude/rules/blocked-items.md` — BLOCKED: protocol
+- `.claude/rules/session-artifacts.md` — chronicle + journal obligations at session end
+- `standards/tier-tag-schema.md` — `upstream | lite | standard | ultra`
+- `templates/chronicle-template.md` — session log shape
+- `templates/whereami-template.md` — project state file shape
+
+## What NOT to do
+
+- **Don't push to main without PR review**, even solo. Main-protection catches surprise typos.
+- **Don't skip `/temperance` on non-trivial work.** It costs 30 seconds and catches wrong-shape ideas before you code them.
+- **Don't ship code without `/verify`.** The gate reads your change and points you at what you missed.
+- **Don't use bassclef-internal jargon** in operator-facing prose (PR bodies, chronicles, issues). Plain English. Grade 10. Subject-verb-object.
+
+## About prose citations to files not in lite
+
+Lite skills and rules sometimes cite rules or ADRs that ship only in standard bassclef. That is by design (per canvas 2026-07-19-bassclef-lite Q1). The rules that matter at runtime load through `additionalDirectories` — the sync template writes that setting into your `.claude/settings.json`. Governance rules fire when their trigger conditions match. You do not need the file on disk.
+
+Curious lite adopters can read the full standard-tier substrate at github.com/sunj-labs/bassclef. Prose citations point there.
+
+## Upgrading to standard bassclef
+
+When your work spans multiple projects, or you need adopter-QA discipline, or you hit the limits of 14 skills — flip `.bassclef-source.json` to point at the standard bassclef repo. All 90 skills, 76 rules, 61 hooks land at next session-start. No adopter action beyond the pointer flip.
+
+## See also
+
+- `docs/curation/2026-07-17b-lite-curation-notes.md` — how these 14 skills were picked (Voyage embeddings + luminary lens)
+- `docs/curation/2026-07-17b-lite-candidate-pool.md` — the 25-skill cosine shortlist that fed the lens pass
+- ADR-040 — planning skill vocabulary + lite profile (source decision)
+- ADR-041 — adopter-count-based grace-window (when full compat discipline returns)

package/substrate/CODE_OF_CONDUCT.md

@@ -0,0 +1,28 @@
+---
+tier: lite
+description: "We're committed to a welcoming, respectful community for everyone contributing to or using bassclef."
+---
+# Code of Conduct
+
+We're committed to a welcoming, respectful community for everyone contributing to or using bassclef.
+
+## Expected behavior
+
+- Treat others with respect and good faith.
+- Engage constructively with feedback and disagreement.
+- Credit sources for content you contribute.
+
+## Unacceptable behavior
+
+- Harassment, personal attacks, or discriminatory language.
+- Sharing others' private information without consent.
+- Threats or encouragement of violence.
+- Impersonating others or evading enforcement actions.
+
+## Reporting
+
+To report a violation, email conduct@bassclef.dev. Reports are handled privately.
+
+## Scope
+
+This applies to all project spaces — issues, pull requests, discussions, and any official project communication.