@thebassclef/lite 0.0.1 → 0.1.2

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.

package/substrate/CONTRIBUTING.md

@@ -0,0 +1,177 @@
+---
+tier: lite
+description: Bassclef is a framework for guiding AI agents through software development — skills, rules, hooks, and standards that compose into an opinionated SDLC substrate.
+---
+# Contributing to Bassclef
+
+Bassclef is a framework for guiding AI agents through software development — skills, rules, hooks, and standards that compose into an opinionated SDLC substrate. This guide is for contributors extending it.
+
+If you're adopting bassclef (not extending it), start with [`docs/bassclef-mental-model.md`](docs/bassclef-mental-model.md) — the 5-minute primer.
+
+## Before you start
+
+Read these three, in order:
+
+1. **[`docs/bassclef-mental-model.md`](docs/bassclef-mental-model.md)** — the shape of the framework in 5 minutes
+2. **[`docs/philosophy.md`](docs/philosophy.md)** — the nine threads of influence bassclef embeds and why
+3. **[`.claude/rules/context-engineering.md`](.claude/rules/context-engineering.md)** — the foundational rule. Every skill, rule, and hook is improved by this lens.
+
+Then browse the catalogs for the surface you're touching:
+
+- [`docs/skills-catalog.md`](docs/skills-catalog.md) — all skills
+- [`docs/hooks-catalog.md`](docs/hooks-catalog.md) — all hooks
+- [`docs/rules-catalog.md`](docs/rules-catalog.md) — all rules
+- [`docs/glossary.md`](docs/glossary.md) — the vocabulary
+
+## The contribution model
+
+Bassclef's substrate is **markdown + bash + git**. No proprietary runtime. Contributing means editing markdown files and bash scripts, then opening a PR.
+
+Four surfaces you can contribute to:
+
+| Surface | Where | What it is |
+|---|---|---|
+| **Skill** | `.claude/skills/<name>/SKILL.md` | A named workflow the agent invokes |
+| **Rule** | `.claude/rules/<name>.md` | A methodology constraint auto-loaded every session |
+| **Hook** | `.claude/hooks/<name>.sh` | Mechanical enforcement firing on tool-use events |
+| **Standard** | `standards/<name>.md` | A reference document |
+
+Not sure which surface fits? The `/skill` skill runs a taxonomy gate (skill / rule / hook?) before scaffolding. Use it.
+
+### Operator-private vs adopter-facing
+
+The `docs/operator-private/` directory in your clone contains only a README placeholder. That's intentional — operator-private substrate (internal deliberation, strategy notes) lives in a separate private repo. Contributors don't need to populate or interact with it. The discipline: strategy artifacts stay private; only reference substrate (rules, hooks, standards) ships to the public bassclef repo.
+
+If you're the bassclef maintainer (operator), `scripts/operator-setup.sh` sets up the symlink workflow when the private repo is cloned at the expected sibling location. The script is idempotent + a no-op for adopter clones; adopters can ignore it.
+
+## How to contribute a change
+
+### 1. Open an issue first
+
+Every branch ties to an issue. The issue body opens with a flash (≤180 chars) + tweet (≤280 chars) + `---` + detail, per [`.claude/rules/github-issue-flash-tweet.md`](.claude/rules/github-issue-flash-tweet.md). Operators scan flash → tweet → decide.
+
+### 2. Branch from main
+
+```
+feature/ISSUE-NNN-short-description
+fix/ISSUE-NNN-short-description
+```
+
+Trunk-based. Main is always deployable. No branches older than 5 days — break large work into a stack.
+
+### 3. Follow the rules that fire on your surface
+
+Rules auto-load every session. The ones you'll feel most when contributing:
+
+- **`context-engineering.md`** — every "DON'T do X" instruction needs a paired "INSTEAD do Y." The stateless model can't act on negation alone.
+- **`skill-description-clarity.md`** — skill descriptions ≤280 chars, verb-first, no jargon. The `substrate-clarity-gate` hook BLOCKs violations.
+- **`plain-english-discipline.md`** — grade-10 vocabulary. Keep standard tech terms; drop framework-internal jargon.
+- **`artifact-ingestion.md`** — read every referenced artifact before producing output. State "Sources read" upfront.
+- **`pr-strategy.md`** — stacked atomic branches by default; one work-unit per PR.
+
+The full set: [`docs/rules-catalog.md`](docs/rules-catalog.md).
+
+### 4. Hooks will check your work
+
+When you edit a skill or rule, the `substrate-clarity-gate` hook validates description length + verb-first opener + paired-discipline INSTEAD-blocks. When you write a state-spine file, `state-validate` checks it against the JSON schema. These BLOCK the write if you've drifted — read the stderr, adjust, retry.
+
+The full set: [`docs/hooks-catalog.md`](docs/hooks-catalog.md).
+
+### 5. Commit conventions
+
+```
+<type>: <description>
+```
+
+Types: `feat`, `fix`, `docs`, `refactor`, `test`, `ci`, `chore`, `security`. Imperative mood, lowercase, no period, ≤72 chars. The body explains *why* — the diff shows *what*.
+
+### 6. Open the PR
+
+PR title becomes the squash-merge commit. PR body opens with flash + tweet, same as issues. Include a test plan.
+
+### 7. CI runs
+
+The PR triggers three blocking substrate-coherence checks (bassclef#739):
+
+- **Rule 1 — Jargon enforcement** — blocks PR body containing bassclef-internal jargon (composer, primitive, tier-preset, load-bearing, blast radius, compose-with, scope-bounded, operationalize). Override via `bassclef-internal-prose-ok` label for intentional exceptions.
+- **Rule 3 — Operator-private path enforcement** — blocks persona-review-shaped, canvas-shaped, or proposal-shaped artifacts outside `docs/operator-private/`. Same label override.
+- **Rule 4 — PR-body scrub** — blocks operator-private path citations + operator-strategic deliberation framing in PR body. Same label override.
+
+Plus an advisory body-clarity check (does not block; flags long sentences + jargon for review). Address failures before requesting review.
+
+## Branch-stacking discipline
+
+When work splits into multiple dependent PRs, follow the mandatory protocol per [`standards/branch-stacking.md`](standards/branch-stacking.md):
+
+- Each PR ships one work unit; revertable independently
+- **Retarget-before-merge is mandatory when dependents exist** — retarget dependent PRs to `main` via `gh pr edit <PR> --base main` BEFORE merging the parent with `--delete-branch`. Skipping retarget causes GitHub to auto-close dependents (rebase-after-merge fallback is recovery, not first-class choice).
+- Pre-merge audit: `scripts/check-stack-dependents.sh <PR>` lists open dependents before you trigger the merge
+
+## Plain-language discipline
+
+All operator-facing prose (PR bodies, chronicle entries, ticket bodies, summary tables) passes through `/kiss words` by default. See [`standards/operator-facing-prose-discipline.md`](standards/operator-facing-prose-discipline.md) for the three Tweet rules:
+
+1. **Fit in 280 chars** (bassclef#785)
+2. **Keep scoping qualifiers** — "deferred within Tier 1" not just "deferred" (bassclef#805)
+3. **Lead with the goal**, then say what was done (bassclef#831)
+
+Shorthand references (WU-N, F-X.Y, ADR-NNN, #NNN) carry a plain-language gloss at first mention per response.
+
+## Writing a new skill
+
+`/skill` composes a new skill from idea to conforming `SKILL.md`. It runs the taxonomy gate first, generates a verb-first plain-language description, scaffolds the frame, and pre-validates against the live clarity gate before writing.
+
+Skill frontmatter requirements:
+
+- `name` — matches the directory name; not a reserved Claude Code built-in (see [`standards/reserved-skill-names.md`](standards/reserved-skill-names.md))
+- `description` — ≤280 chars, verb-first, names any `modes:` declared
+- `user_invocable` + `disable_model_invocation` — the invocation contract
+
+A skill is **composite** (hands-off-execution — returns a clickable artifact) or **atomic** (hands-off-planning — drives a thinking-and-decision loop). Know which you're building. See [`docs/skills-catalog.md`](docs/skills-catalog.md).
+
+## Writing a new rule
+
+Rules are methodology constraints. They auto-load every session via `additionalDirectories` — the agent doesn't invoke them.
+
+A good rule:
+
+- States the constraint, then **Why** (the reason, often a past incident), then **How to apply** (when/where it fires)
+- Pairs every "DON'T" with an "INSTEAD" (the foundational `context-engineering.md` discipline)
+- Names its enforcement — methodology-level, or which hook BLOCKs it
+- Names its override path (most rules have a `SKIP_*` env var; methodology-level rules don't)
+
+## Writing a new hook
+
+Hooks are mechanical enforcement. They fire on tool-use events (PreToolUse, PostToolUse, SessionStart, Stop, UserPromptSubmit).
+
+A good hook:
+
+- Has a header comment — what it fires on, what it checks, why it exists
+- Is **idempotent** — running it twice with the same input produces the same result (see [`standards/hook-idempotency.md`](standards/hook-idempotency.md))
+- Provides a `SKIP_*` override env var, logged via `trace-helper`
+- Has test coverage in `.claude/hooks/tests/`
+
+## Promoting a pattern back to bassclef
+
+If you're using bassclef in your own repo and discover a pattern worth sharing, the `/promote` skill files a `bassclef-evolution` issue. Patterns discovered in projects compound into the substrate.
+
+## What bassclef is NOT
+
+- **Not a code generator.** It guides the agent through the SDLC; the agent writes the code.
+- **Not a CI tool.** It runs locally + via hooks. CI surfaces show its outputs but it doesn't replace your CI.
+- **Not opinionated about your stack.** Works with any language / framework / cloud.
+- **Not greenfield-only.** Bassclef drops onto an existing repo. The substrate goes in `.claude/`; your code stays in `src/`.
+
+## Code of conduct
+
+Be direct, be kind, assume good faith. Bassclef is opinionated by design — disagreement about the opinions is welcome, expressed as a reasoned issue, not a drive-by. The substrate evolves through `/promote` and reasoned PRs, not through unilateral rewrites of essential rules.
+
+A formal `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1) is planned for the open-source launch. Until it lands, the above guidance applies.
+
+## Questions
+
+Open an issue with the `question` label. For "how do I use bassclef" questions, the mental-model primer + glossary answer most of them first.
+
+---
+
+*Bassclef is markdown + bash + git. If you can read a file and run a script, you can contribute.*

package/substrate/README.md

@@ -0,0 +1,173 @@
+---
+tier: lite
+description: A shared substrate for working with AI coding agents.
+---
+# Bassclef
+
+> **If you are new — start here.** Three short reads in this order:
+> 1. The [Mental Model](https://github.com/sunj-labs/bassclef/wiki/Mental-Model) — one page; what bassclef is and what it isn't.
+> 2. The [Skill lifecycle diagram](https://github.com/sunj-labs/bassclef/wiki/Diagrams) — one image; the full skill catalog at a glance.
+> 3. The [Getting Started](https://github.com/sunj-labs/bassclef/wiki/Getting-Started) page — three commands; substrate live in your repo.
+>
+> Then read the rest of this README as background. About 10 minutes total.
+
+**A shared substrate for working with AI coding agents.** Install it once into your repo, and every Claude Code session starts loaded: 76 skills, 53 rules, 16 agents, 32 practitioner profiles, 27 hooks, 67 standards, and 27 ADRs that wire them together. The agent reads your rules, knows the catalog, handles failure cleanly, and ships with discipline. You stop re-explaining your conventions every session — the difference between an assistant you brief and a band that already knows the set.
+
+It is not a product. It is not a SaaS. It's a public framework, Apache 2.0: clone the repo, run the install script, own your stack.
+
+**Two install paths.** [Curl install](docs/getting-started.md) — one command per project, works once bassclef is public and your network allows `raw.githubusercontent.com`. [Clone install](docs/install-from-clone.md) — one clone of bassclef, wire many projects against it as siblings, one place to `git pull` for updates. Pre-launch adopters and multi-project operators pick the clone path.
+
+## Who this is for
+
+**Solo system / app / portfolio operators.** The person running multiple software projects in parallel — apps, internal systems, side bets, family operations — around a day job, around family, around the other things that don't pause. Real deadlines, real stakes, no headcount. Other audiences may benefit; this is the one SENTINEL_bassclef_commits to.
+
+## Why this exists
+
+A kid of immigrant entrepreneurs becomes one in his 20s with a hundred ideas and two hands. Every idea needed a team; teams needed money; money needed the ideas to work. Most entrepreneurship dies in that loop. Twenty-five years later — after launching the Alexa Skills Kit and building enterprise collaboration tools before their time — I hit the loop again. I hold power of attorney for my parents and run their affairs alongside acquiring small businesses on their behalf. Real deadlines, real stakes, no headcount. So I built the band I couldn't hire.
+
+That origin is why bassclef is shaped the way it is:
+
+- **Apache 2.0, no SaaS** — a capital bypass has to be free. Anthropic's 81k-person global study found entrepreneurship-with-AI resonates most where funding is scarcest; this is for the operator with ideas and no budget line.
+- **Cheap by design** — small models route mechanical work; hard cost ceilings cap every run. Built by one person paying his own bills.
+- **Local-first** — it works without expensive infrastructure, because mine had to.
+- **Discipline as substrate** — rules, skills, and practitioner profiles load at session start because a solo operator can't afford to re-explain conventions, and an agent without a chart is a session musician with no memory of the band.
+
+The acceptance test for v1 wasn't a demo — it was a live ticket from my parents' actual work. When it closed, the repo opened.
+
+## What's actually shipped
+
+Not theoretical. Bassclef runs today across eight repos in active use:
+
+- **A private sibling repo for strategy notes** — canvases, audits, and locked decisions. Adopters replicate the pattern with a separate private repo cloned alongside their bassclef checkout.
+- **Seven application repos in daily use** — from a power-of-attorney tracker for my family to a collaborative travel planner to a recipe database. Each one is code I use myself, not a demo.
+
+The pattern: build the apps on the go, each repo's friction feeds back into bassclef as evolution tickets, the substrate hardens with every shipped feature.
+
+**4,650 commits and 3,409 merged PRs to date** across the portfolio. The substrate you'd adopt is the one already smoke-tested across seven repos in production.
+
+## Full documentation
+
+The complete adopter docs live in the bassclef wiki: **[github.com/sunj-labs/bassclef/wiki](https://github.com/sunj-labs/bassclef/wiki)**.
+
+Start there for [Getting Started](https://github.com/sunj-labs/bassclef/wiki/Getting-Started) (3-step fast path), [First-use sequence](https://github.com/sunj-labs/bassclef/wiki/First-Use-Sequence) (what bassclef actually does end-to-end), [Install paths](https://github.com/sunj-labs/bassclef/wiki/Install), [FAQ](https://github.com/sunj-labs/bassclef/wiki/FAQ), [Architecture Overview](https://github.com/sunj-labs/bassclef/wiki/Architecture-Overview), [Glossary](https://github.com/sunj-labs/bassclef/wiki/Glossary), and the [Luminary catalog](https://github.com/sunj-labs/bassclef/wiki/Luminary-Catalog).
+
+## Before you start
+
+Bassclef assumes a few things already work on your machine. Five minutes of setup before the build path:
+
+| You need | How to check | If missing |
+|---|---|---|
+| A GitHub account | sign in to github.com | create one — free |
+| `gh` CLI installed + authenticated | `gh auth status` | `brew install gh && gh auth login` |
+| Claude Code installed | `command -v claude` | follow [code.claude.com](https://code.claude.com) install steps |
+| `ANTHROPIC_API_KEY` set | `echo $ANTHROPIC_API_KEY` (non-empty) | get a key at [console.anthropic.com](https://console.anthropic.com) and `export` it |
+| `git` installed | `git --version` | install from [git-scm.com](https://git-scm.com) |
+| `python3` installed | `python3 --version` | macOS: pre-installed. Linux: `apt install python3`. Required by bassclef hooks (per [ADR-028](https://github.com/sunj-labs/bassclef/blob/main/architecture/decisions/ADR-028-python3-as-substrate-runtime.md)) |
+
+Once those check out, pick a path.
+
+## Two paths in
+
+### Path A — Cold adopter (paragraph in, working preview out)
+
+You have an idea. You don't have an issue tracker yet. You just want to see something real on your screen.
+
+| Step | What | Time |
+|---|---|---|
+| 1 | `/onboard-repo` — installs substrate + asks "what is this repo for?"; auto-chains `/launch --local` with your paragraph | 60s |
+| 2 | Wait — bassclef extracts intent, picks practitioner profiles, generates 4 variant directions | 4 min |
+| 3 | Walk the variant gallery on your phone or laptop; say "I like variant 2" (or "none of these — try X instead") | 3 min |
+| 4 | Wait — bassclef writes the formal artifacts (use case, user stories, IA, interaction design, spec, migration plan) for the chosen direction only | 5 min |
+| 5 | `/build <bet-slug>` — dispatches per-work-unit feature branches with tests + PRs | continues asynchronously |
+
+**Total to first variant pick: ~7 min.** Per-WU PRs land as `/build` works through the stack. You merge as they pass review.
+
+This is the "I just want to build something" path. No tickets to file. No roadmap to maintain. The substrate handles the chain.
+
+### Path B — Existing repo with open work
+
+You have a repo with open issues, an iteration bet in flight, a roadmap. You want bassclef to help you execute against existing work, not invent new scope.
+
+| Step | What | Time |
+|---|---|---|
+| 1 | `/onboard-repo` — installs substrate; closing handoff defers (no auto-chain in operator mode) | 60s |
+| 2 | `/sprint` + `/whereami` — orient to project state + open issues + active iteration bet | 90s |
+| 3 | Pick work from open issues / iteration bet; create a feature branch | 30s |
+| 4 | `/stage quick "<scope>"` (variants) **OR** `/launch medium "<scope>"` (full plan) **OR** direct edits | 3-5 min |
+| 5 | `/verify` — runs the test path matched to your change type | 60s |
+| 6 | `git commit` + `git push` — pre-commit gate + scrub hooks fire automatically | 90s |
+| 7 | `/session-end` — chronicle entry + whereami update + clean close | 90s |
+
+**Total: ~12 min.** Operator opens a PR via GitHub UI or `gh pr create`.
+
+Requires existing open issues, an iteration bet, or a roadmap. Without those, `/sprint` will surface "nothing in flight" and recommend Path A. Operator-mode is the sustained-work path; Path A is the first-contact path.
+
+## What you can do with it
+
+- **Dispatch a paragraph from your phone** → returns as a working preview on localhost
+- **Run a long autonomous session** that paces itself, checkpoints at phase boundaries, and closes with a chronicle + retrospective
+- **Combine skills** across the full SDLC (shape → spec → design → build → verify → deploy)
+- **Audit the substrate against itself** via hooks + rules + the context-engineering rule that catches drift
+
+## Substrate at a glance
+
+| Component | Count | Where | Catalog |
+|-----------|------:|-------|---------|
+| Skills | 75 | `.claude/skills/*/SKILL.md` | [skills catalog](https://github.com/sunj-labs/bassclef/blob/main/docs/skills-catalog.md) |
+| Hooks | 25 | `.claude/hooks/*.sh` | [hooks catalog](https://github.com/sunj-labs/bassclef/blob/main/docs/hooks-catalog.md) |
+| Rules | 48 | `.claude/rules/*.md` | [rules catalog](https://github.com/sunj-labs/bassclef/blob/main/docs/rules-catalog.md) |
+| Agents | 13 | `.claude/agents/*.md` | — |
+| Practitioner profiles | 31 | `.claude/luminaries/*.md` (plus 1 TEMPLATE.md scaffold for new entries) | [wiki Luminary catalog](https://github.com/sunj-labs/bassclef/wiki/Luminary-Catalog) |
+| Standards | 65 | `standards/` | — |
+| ADRs | 26 | `architecture/decisions/` | — |
+
+Browse interactively: `/skills`, `/hooks`. Past the build path, adopters pick up additional skills from the catalogs as needs surface.
+
+## Team adopters
+
+The substrate is shaped for solo operators, not teams. Teams will still find value: the state spine, the test + verify chain, and the auto-loading rules translate to team contexts (engineer A pairs Monday → `/sprint` surfaces context for engineer B Wednesday). Methodology evolution will favor solo-operator concerns; team adopters who borrow the substrate accepting that constraint do well.
+
+Total team cost to adopt: about 3 engineer-days for a 5-person team in week 1.
+
+## Foundations
+
+Bassclef is context engineering applied to the full software development lifecycle. The discipline has a name and a literature:
+
+- **[Karpathy — context engineering](https://x.com/karpathy/status/1937902205765607626)**: "LLM is the CPU, context window is RAM." Prompts as filling a finite working-memory buffer.
+- **[Willison — stateless tool framing](https://fedi.simonwillison.net/@simon/114757992443676572)**: every conversation starts cold; the model knows what it knows only via what's in the prompt.
+- **[Anthropic — Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)**: vendor-validated principles for context budgeting, persistence, and tool design.
+
+Bassclef builds on eight more threads — distributed state management, multi-agent coordination, methodology (Shape Up, DDD), strategy canvases (Strategyzer, Lean Canvas, PR/FAQ), Jobs-to-be-Done, use-case design (Cockburn), red/green/refactor testing (Beck), and rapid prototyping (IDEO, design thinking). Each thread, who it comes from, and where it lives in the substrate: [philosophy](https://github.com/sunj-labs/bassclef/wiki/Philosophy).
+
+## Start here
+
+| Doc | What it is |
+|---|---|
+| [Mental Model](https://github.com/sunj-labs/bassclef/wiki/Mental-Model) | 5-minute primer — where things live, which skills to invoke, brownfield retrofit |
+| [Glossary](https://github.com/sunj-labs/bassclef/wiki/Glossary) | The vocabulary — iteration bet, work unit, stack, marker, BLOCKED, and more |
+| [Philosophy](https://github.com/sunj-labs/bassclef/wiki/Philosophy) | Nine threads of influence bassclef embeds and where each lives |
+| [Overview](https://github.com/sunj-labs/bassclef/wiki/Overview) | Long-form — what bassclef is, how it works, where it's going |
+| [Contributing](https://github.com/sunj-labs/bassclef/blob/main/CONTRIBUTING.md) | How to extend bassclef — four surfaces, contribution flow, per-surface guides |
+
+## License + sustainability
+
+Apache 2.0. Single-operator project today; the substrate is markdown + bash + git, so adopters retain everything that ships even if maintainer velocity changes. Business model is community-open — no commercial-pivot pressure on your adoption.
+
+## Contributing
+
+Bassclef is markdown + bash + git. If you can read a file and run a script, you can contribute. See [CONTRIBUTING](https://github.com/sunj-labs/bassclef/blob/main/CONTRIBUTING.md) — four surfaces (skill, rule, hook, standard), a 7-step contribution flow, per-surface authoring guides.
+
+## Key files
+
+- [Mental Model](https://github.com/sunj-labs/bassclef/wiki/Mental-Model) — 5-minute adopter primer
+- [Glossary](https://github.com/sunj-labs/bassclef/wiki/Glossary) — the vocabulary
+- [Philosophy](https://github.com/sunj-labs/bassclef/wiki/Philosophy) — eight threads of influence
+- [Skills catalog](https://github.com/sunj-labs/bassclef/blob/main/docs/skills-catalog.md) · [Hooks catalog](https://github.com/sunj-labs/bassclef/blob/main/docs/hooks-catalog.md) · [Rules catalog](https://github.com/sunj-labs/bassclef/blob/main/docs/rules-catalog.md) — substrate catalogs
+- [Context engineering framing](https://github.com/sunj-labs/bassclef/blob/main/design/bassclef-as-context-engineering.md) — substrate-truth framing
+- [Context engineering rule](https://github.com/sunj-labs/bassclef/blob/main/.claude/rules/context-engineering.md) — the foundational rule
+- Agent choreography — multi-agent operational guide (operator substrate)
+- whereami — current project state (operator substrate)
+
+## Operator-private substrate
+
+The `docs/operator-private/` directory contains only a README placeholder in adopter clones. Operator-private substrate (internal deliberation, strategy notes) lives in a separate private repo cloned alongside bassclef.

package/substrate/SECURITY.md

@@ -0,0 +1,19 @@
+---
+tier: lite
+description: "Please report security vulnerabilities privately via GitHub's security advisory system:"
+---
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security vulnerabilities privately via GitHub's security advisory system:
+
+**https://github.com/sunj-labs/bassclef/security/advisories/new**
+
+Do not report security issues via public GitHub issues, discussions, or pull requests.
+
+We aim to acknowledge reports within 72 hours and provide an initial response within 7 days.
+
+## Supported versions
+
+Bassclef is pre-1.0. Security fixes apply to the current main branch. Once tagged releases ship, this policy will be updated with version support details.

package/substrate/architecture/decisions/ADR-029-release-pipeline.md

@@ -0,0 +1,79 @@
+---
+tier: lite
+adr: ADR-029
+title: Release pipeline — tier-filtered export from bassclef-upstream to public bassclef
+status: accepted
+date: 2026-06-21
+description: bassclef-upstream is the upstream experimental source-of-truth (WU-0).
+---
+<!-- andon-allow: operator-private -->
+<!-- andon-allow: bassclef-upstream -->
+<!-- andon-allow: locked-decisions -->
+
+# ADR-029 — Release pipeline (bassclef-upstream → public bassclef)
+
+## Context
+
+bassclef-upstream is the upstream experimental source-of-truth (WU-0). Public bassclef is the downstream release mirror. One operator, two repos, one direction of flow per the simplified Linux-kernel model (ADR-022 established the rename-in-place rationale that made this split sustainable).
+
+Without a defined release pipeline, every release is either manual cherry-pick (slow, error-prone) or an unfiltered rsync (catastrophic — operator-private content ships). Neither is acceptable.
+
+## Decision
+
+Implement `scripts/release-to-bassclef.sh` with the following discipline:
+
+1. **Tier-tagged frontmatter filter.** Each substrate file carries a `tier:` field with value `private | basic | premium | public` (per ADR + `standards/tier-tag-schema.md`). The script ships `basic` + `public`, excludes `private` + `premium`. Untagged legacy files default to `public`.
+
+2. **Andon scan (jidoka stop-the-line).** Before any cross-repo write, grep the filtered file set for operator-private patterns (`operator-private`, `bassclef-upstream`, `locked-decisions`, plus any BLOCK-tier term in `standards/bassclef-internal-jargon.md`). Any match → STOP, surface file+line, refuse to push. Per-file override via `# andon-allow: <term>` header. Process-wide override via `SKIP_ANDON=1` (logged; never in prod).
+
+3. **PR-based, never direct push.** Script rsyncs into the target repo working tree, commits on a `release-YYYY-MM-DD-<sha>` branch, pushes, and opens a PR against public bassclef main. Operator merges after review. No direct main-branch writes.
+
+4. **Source tag for rollback.** Every release tags bassclef-upstream with `release-YYYY-MM-DD-<sha>` before any external action. Rollback = revert the PR + delete the tag; the source state is recoverable.
+
+5. **Operator-fired cadence.** No cron. Operator runs `/release` when they want to ship. Conway lens — one operator IS the cadence signal; automated cadence would manufacture artificial release rhythm.
+
+## Alternatives considered
+
+| Alternative | Why rejected |
+|---|---|
+| Manual cherry-pick per file | Slow + error-prone + invites operator to skip the andon scan |
+| Cron-scheduled auto-release | One-operator org doesn't need automated cadence (Conway); manufactures rhythm |
+| Path-allowlist filter without tier | Too coarse for the iterative basic→premium graduation operator wanted (per session's plan-mode decision) |
+| Direct push to public main | Branch protection on public main makes this impossible; PR-based works in both modes |
+| Bidirectional sync (git subtree / submodule) | Adopter-PR merge to public would diverge; next `--delete` rsync would obliterate silently. PR cherry-pick into private preserves credit (per ADR-030) |
+
+## Luminary rationale
+
+- **Taiichi Ohno (jidoka)** — andon scan is the stop-the-line mechanism. Any operator-private term in shipped content trips the cord; release halts; operator diagnoses before resuming. No silent ship.
+- **Vaughn Vernon (bounded contexts)** — the release script IS the explicit context map between the private-experimental and public-hardened bounded contexts. Every cross-context translation runs through one channel.
+- **Melvin Conway (one source-of-truth)** — single release valve, single direction of flow, single operator firing it. Reject Linus's distributed subsystem-maintainer ceremony as overkill for one operator.
+
+## Consequences
+
+**Positive:**
+- Operator gets one-command release with confidence (tier counts + andon clean before any cross-repo write)
+- Iterative releases possible per feature (basic → premium graduation)
+- Operator-private content cannot ship through this channel by accident
+- PR-based release preserves review surface + rollback posture
+
+**Negative / accepted trade-offs:**
+- Operator must remember to fire `/release` (no automated cadence)
+- Untagged legacy files default to public — if operator wanted them private, they must explicitly tier-tag (defense in depth via `docs/operator-private/**` path exclusion covers most cases)
+- First-run risk: if the andon scan has a bug, operator-private content could ship. Mitigated by WU-4 verification gates including an intentional-leak andon trip test before Doors Open
+- Tag clutter: each release creates a tag. After N releases, `git tag | grep release` is noisy. Acceptable for the cadence we expect (~weekly)
+
+## Status
+
+Accepted 2026-06-21. Implementation in commits shipping under WU-2 (#7). Verified by WU-4 (#10) before Doors Open.
+
+## See also
+
+- ADR-022 — rename-in-place (the move that made one-source-of-truth feasible)
+- ADR-030 — adopter inbox flow (the complementary ingestion direction)
+- ADR-032 — adopter-sync dispatcher architecture (what the release ships into adopter repos via `install.sh` — see `#1330`)
+- `standards/tier-tag-schema.md` — the field definition this script consumes
+- `scripts/release-to-bassclef.sh` — the implementation
+- `.claude/skills/release/SKILL.md` — operator-invocable wrapper
+- `architecture/tier-system-and-release-flow.md` § "Subsystem 4 — Release pipeline" + § "Subsystem 5 — Cold-adopter install bootstrap" — end-to-end view of tier + registry + manifest + release + install
+- WU-2 (#7), WU-4 (#10) — work units shipping + verifying this pipeline
+- bassclef-upstream `#1330` — cold-adopter install.sh missing (release ships install.sh once it lands; see architecture doc Subsystem 5)

package/substrate/architecture/decisions/ADR-031-non-breaking-changes-adopter-discipline.md

@@ -0,0 +1,139 @@
+---
+tier: lite
+adr: ADR-031
+title: Non-breaking changes to adopters — substrate stability discipline
+status: accepted
+date: 2026-06-21
+description: bassclef positions itself as an open substrate for Claude Code.
+---
+
+# ADR-031 — Non-breaking changes to adopters
+
+## Context
+
+bassclef positions itself as an open substrate for Claude Code. Once public adopters exist (and they will, per the morning's Doors Open arc), every breaking change costs adopter trust. The discipline that protects that trust must be Tier 1, on par with ADR-029 (release pipeline) and ADR-030 (adopter inbox).
+
+Tonight (2026-06-21 evening) demonstrated the failure mode concretely. A single filesystem rename — `mv ~/src/sunj-labs/canonical ~/src/sunj-labs/bassclef` — silently broke every adopter repo on the operator's machine. poa, twoDo, family-recipe-2, eugene-supplements, and quorum each had 30+ symlinks pointing through `../canonical/.claude/hooks/`. Every Bash tool call across every adopter emitted 6+ PreToolUse errors. Non-blocking but noisy, and masks any real failure signal.
+
+The rename was reasonable: the GitHub repo had been renamed weeks earlier; the local folder was finally catching up. The architectural defect was the lack of any compatibility-shim discipline. The rename should have shipped with the shim in the same atomic action.
+
+Two prior ADRs touched the edges of this concern but neither named it:
+
+- **ADR-024 (Forward-port registry)** — handles internal content rewrites (chronicles, ADRs, iteration-bets) via Strategy A-clean (replace, no grace period). It does not handle adopter-observable surfaces.
+- **ADR-019 (Reference vs vendor distribution)** — names the two adopter binding shapes (reference fetches latest; vendor freezes at pull-time) but does not name the stability guarantee bassclef makes to either.
+
+The architecture document `architecture/dual-repo-flow.md` covers steady-state operation (release pipeline + adopter inbox) but is silent on substrate evolution. The gap surfaced clearly on 2026-06-21 evening and demands explicit decision.
+
+## Decision
+
+bassclef adopts **"we don't break adopters"** as a Tier 1 architectural discipline, with the same essential weight that Linus Torvalds's "we don't break userspace" carries for the Linux kernel. Hyrum's Law is the theoretical foundation: with enough adopters, every observable behavior is a contract whether bassclef declared it or not.
+
+The discipline is operationalized through:
+
+1. **A rule** at `.claude/rules/we-dont-break-adopters.md` that fires on any change to an adopter-observable surface. Methodology layer.
+
+2. **Two luminaries** — Linus Torvalds (`linus-torvalds.md`) as the anchor; Hyrum Wright (`hyrum-wright.md`) as the theoretical foundation. Cited by the rule and by the architecture doc.
+
+3. **A new section in `architecture/dual-repo-flow.md`** — "Non-breaking changes to adopters" — between the up-flow (ADR-030) and the "what ships, what doesn't" sections. Enumerates adopter-observable surfaces and the rename-with-compat-shim procedure.
+
+4. **Migration manifest discipline** — `docs/operator-private/forward-port-registry/migrations/<date>-<change>.md` is required for every change touching an adopter-observable surface. Documents the change, the shim, the deprecation window, and the retirement condition for the shim.
+
+5. **Phase 2 mechanical layer** (tracked at bassclef#1360, separate work) — pre-rename CI test that clones a representative adopter and validates their sync hook against the proposed bassclef HEAD; versioned sync protocol; redirect registry.
+
+The rule supersedes ADR-024's Strategy A-clean default **for adopter-observable surfaces**. Operator-internal rewrites (chronicles, ADRs, iteration-bets) keep Strategy A-clean per ADR-024. The line between the two is the adopter-observable boundary.
+
+## What counts as adopter-observable
+
+Enumerated in the rule (`.claude/rules/we-dont-break-adopters.md`). Summary:
+
+- Filesystem paths under `~/src/sunj-labs/` that adopter symlinks resolve through
+- Symlink targets inside `<adopter>/.claude/hooks/` and `<adopter>/.claude/skills/`
+- Filenames referenced by adopter `.claude/settings.json`
+- Schema shape of state-spine files
+- `settings.json` field conventions
+- Repo names + `.bassclef-source.json` schema
+- Hook filenames, agent names, skill directory names referenced by adopter automation
+
+## What this requires of every substrate change
+
+1. **Identify adopter-observable surfaces touched.** Required analysis before the change ships.
+2. **Build compatibility shim FIRST.** Symlink, alias, forwarding stub, schema accommodation. Old surface keeps working.
+3. **Write migration manifest.** Documents the shim + retirement condition.
+4. **Adopter changelog entry.** /release PR body Summary names the rename, the shim, when the shim retires.
+5. **Deprecation period.** Minimum one /release cycle between deprecation announcement and shim removal. Three cycles for high-blast-radius surfaces.
+6. **Test against real adopter.** Clone a representative adopter; run their sync hook; confirm no observable change. This becomes Phase 2 CI-mechanical.
+
+## Alternatives considered
+
+| Alternative | Why rejected |
+|---|---|
+| Status quo (rely on operator's judgment per rename) | Tonight proved the operator's judgment is insufficient — we don't enumerate adopter dependencies before substrate changes. Need explicit discipline. |
+| SemVer-only (no shim discipline; just bump major version on breaks) | Adopters don't auto-update; SemVer signals don't stop the cascade. Shim is the essential piece. |
+| Strategy A-clean everywhere (per ADR-024 default) | Worked for chronicles. Doesn't work for filesystem paths and symlink targets adopters depend on. |
+| Pre-announcement only (announce 2 weeks before rename) | Linus's response: "Announcements aren't shims. Did the old name keep working? No? You broke userspace." Announcements are necessary but insufficient. |
+| Reference-only distribution (force every adopter to fetch via HTTP API) | Adopters with vendor bindings (the most stable adopter shape) would all need to migrate first. Worse trade than the discipline itself. |
+
+The selected approach is the strictest discipline that's still operationally feasible for a one-operator substrate. Compat shims cost minutes per substrate change; the alternative is an angry adopter trail.
+
+## Consequences
+
+**Positive:**
+
+- Adopters can pin a bassclef version and never have their existing setup break across upstream changes
+- The discipline scales as adopter count grows (more adopters = more value from the shim)
+- The substrate gets to refactor internal naming with adopter-cost-of-zero (the shim absorbs it)
+- The "we don't break adopters" framing aligns bassclef philosophically with the most respected substrate evolutions in software history (Linux, POSIX, the Web)
+
+**Negative:**
+
+- Every substrate-rename costs more (one extra symlink + one manifest + one changelog entry)
+- The substrate accumulates permanent compatibility code (shims that outlive their original purpose)
+- Some clean-rename opportunities become uneconomic (Brooks's conceptual-integrity tax)
+- Operator discipline required at every substrate change — easy to skip when tired
+
+**Neutral:**
+
+- Phase 2 mechanical layer is substantial work (pre-rename CI test, versioned protocol, redirect registry). Tracked as deferred. Discipline holds at methodology layer until Phase 2 ships.
+
+## Implementation
+
+Phase 1 (this session, 2026-06-21 evening):
+
+- `.claude/rules/we-dont-break-adopters.md` — methodology rule
+- `.claude/luminaries/linus-torvalds.md` + `.claude/luminaries/hyrum-wright.md` — discipline anchors
+- This ADR (ADR-031)
+- `architecture/dual-repo-flow.md` — new section "Non-breaking changes to adopters"
+- `docs/operator-private/forward-port-registry/migrations/2026-06-21-local-canonical-to-bassclef-folder.md` — manifest for tonight's rename
+- `~/src/sunj-labs/canonical → ~/src/sunj-labs/bassclef` — the rescue shim (already in place at time of authoring)
+
+Phase 2 (separate session, bassclef#1360):
+
+- Pre-rename CI test workflow
+- bassclef-sync.sh extension that detects + auto-migrates stale references
+- `.bassclef-source-redirect.json` registry
+- Versioned sync protocol with breaking-change markers
+
+## Eat-our-own-dogfood
+
+This ADR was authored within minutes of the rule's first violation (the canonical→bassclef rename cascade). The shim was applied. The migration manifest names the substrate-rename retroactively. Future renames cite ADR-031 explicitly in their commit messages and /release PR bodies.
+
+## References
+
+- @luminary linus-torvalds
+- @luminary hyrum-wright
+- @luminary michael-nygard — circuit-breaker pattern (sister discipline)
+- @luminary vaughn-vernon — anticorruption layer (the architectural pattern)
+- @luminary frederick-brooks — conceptual integrity vs migration cost
+- ADR-024 — forward-port registry (this ADR extends/scopes ADR-024 for adopter-observable surfaces)
+- ADR-019 — reference vs vendor distribution (sets the two binding shapes this ADR protects)
+- ADR-029 — release pipeline (every /release that breaks an adopter-observable surface MUST include migration-manifest reference)
+- ADR-030 — adopter inbox (adopter-filed silent-break issues are now defect signals, not acceptable channel)
+- `.claude/rules/we-dont-break-adopters.md` — operational methodology
+- `architecture/dual-repo-flow.md` — architecture doc with the new section
+- bassclef#1360 — Phase 2 mechanical layer
+- poa#1251 — sister adopter-side migration ticket
+- 2026-06-21 chronicle — the canonical→bassclef cascade + rescue + ADR authoring
+
+## Retirement condition
+
+This ADR retires only if bassclef stops having adopters. Phase 2 mechanical layer may reduce the methodology cost; it does not retire the decision. Adopter stability is a forever commitment.