@thebassclef/lite 0.1.3 → 1.0.0

package/substrate/architecture/decisions/ADR-032-adopter-sync-dispatcher-architecture.md

@@ -1,192 +0,0 @@
----
-tier: lite
-adr: ADR-032
-title: Adopter sync dispatcher architecture — bootstrap + sync impl two-stage rocket
-status: accepted
-date: 2026-06-22
-deciders: operator + bassclef agent
-references:
-  - {type: issue, id: bassclef-upstream#261, anchor: dispatcher hardening umbrella}
-  - {type: file, id: docs/iteration-bets/2026-06-22b-dispatcher-hardening-rename-orientation.md, anchor: WU-3 Layer 2 two-stage rocket}
-  - {type: adr, id: ADR-031, anchor: non-breaking-changes-adopter-discipline}
-  - {type: adr, id: ADR-019, anchor: reference-vs-vendor-distribution}
-description: "POA's session-start on 2026-06-22 morning fired CANONICAL SYNC FAILED — token env var $CANONICAL_TOKEN not set."
----
-
-# ADR-032 — Adopter sync dispatcher architecture
-
-## Context
-
-POA's session-start on 2026-06-22 morning fired `CANONICAL SYNC FAILED — token env var $CANONICAL_TOKEN not set`. The diagnosis (Five Whys) showed the error was misleading. The actual cause was the substrate rename canonical → bassclef on 2026-06-20 moved a template the vendored dispatcher hardcoded — Path 1 fell through silently; Path 2 fired the auth error as a side effect. ADR-031 (we don't break adopters) was violated.
-
-Every adopter on the operator's machine carries a vendored dispatcher dated May-3 (4.7KB). The current substrate ships a much-evolved dispatcher (`thin-pointer-2026-06-13`, 256 lines, 9.6KB) that fixes the template-name issue and adds plain-language error reporting, auto-sync flag handling, and richer auth. **But the May-3 vintage stays vendored until something refreshes it.** Every substrate-side improvement is invisible to adopters whose dispatcher pre-dates the improvement.
-
-The architecture in `strategy/templates/` already has a two-stage shape implicitly:
-
-- `bassclef-sync.dispatcher.template.sh` (256 lines) — what gets vendored into the adopter
-- `bassclef-sync.template.sh` (1290 lines) — the "big template" that does the actual sync work (skill symlinks, hook wiring, settings.json merge, env-var setup, etc.)
-
-The dispatcher finds the big template (sibling fast-path OR curl fallback) and exec's it. The split exists. What's missing:
-
-1. **No explicit ADR** — the split is implicit in code; new maintainers must read the source to understand the contract
-2. **The dispatcher is still doing too much** — auto_sync flag check, plain-language error printing, and auth handling all evolve with substrate; each evolution requires re-vendoring across every adopter
-3. **No version-detection helper** — Layer 3 self-heal (WU-4 of bet 2026-06-22b) needs a mechanism to detect adopter dispatcher version drift; current parsing is ad-hoc
-4. **Modality coverage isn't documented** — sibling adopters, curl-fallback adopters, mobile-ephemeral sandboxes, and (future) npm-distribution adopters all use the dispatcher differently; the contract should be explicit
-
-This ADR makes the architecture explicit, names the minimum dispatcher responsibilities, and sets up Layer 3 self-heal (WU-4) and future migration to npm distribution (per #266).
-
-## Decision
-
-bassclef adopts a **two-stage rocket** as the essential pattern for adopter sync:
-
-**Stage 1 — Bootstrap (`bassclef-sync.dispatcher.template.sh`)**: vendored into every adopter's `.claude/hooks/bassclef-sync.sh`. Knows only how to find or fetch Stage 2. Almost never changes once stable.
-
-**Stage 2 — Sync impl (`bassclef-sync.template.sh`)**: lives in bassclef-upstream; ships to public bassclef via `/release`. Does all the substrate work — symlink wiring, settings.json merge, hook installation, env-var setup. Evolves freely with the substrate.
-
-The contract between stages:
-
-- Bootstrap reads stdin (Claude Code hook input), finds Stage 2 via the modality-appropriate path, and exec's it with the same stdin piped through
-- Bootstrap is responsible for stage discovery; Stage 2 is responsible for all substrate work
-- Stage 2 changes never require bootstrap updates UNLESS the bootstrap protocol itself changes (rare; same compat-shim discipline as adopter-observable surfaces per ADR-031)
-
-## Bootstrap minimum responsibilities
-
-The bootstrap MUST do exactly these things:
-
-1. Read stdin (JSON from Claude Code hook event); parse `$CWD`
-2. Check sentinel `.no-bassclef-sync` (opt-out) and short-circuit if present
-3. Check `auto_sync` field in `.bassclef-source.json`; short-circuit with one-line note if OFF
-4. **Find Stage 2** via modality-ordered fallback:
-   - **Path 1 — Sibling**: `$CWD/../bassclef/strategy/templates/bassclef-sync.template.sh` (desktop dev, multi-repo workspace)
-   - **Path 2 — Cache**: `~/.cache/bassclef/<version>/bassclef-sync.template.sh` if present and fresh (mobile-ephemeral re-runs within session)
-   - **Path 3 — Fetch from `source_url`** in `.bassclef-source.json` (cloud, CI, fresh sandbox, mobile-ephemeral first-run)
-5. Exec Stage 2 with stdin piped through; return its exit code
-6. On total failure (no path succeeds): emit a plain-language error with three resolution paths (public adopter / local dev / private fork); exit 0 so SessionStart hooks don't crash
-
-The bootstrap MUST NOT do:
-
-- Any substrate work (symlinks, hook wiring, settings.json mutation) — that's Stage 2
-- Schema parsing beyond the minimum needed for path 3 (`source_url`, `auth_method`, `token_env`)
-- Plain-language error printing for any failure mode that Stage 2 could have surfaced
-
-Total target line count: **~80 lines including comments + error message** (down from current 256). The current dispatcher's auto_sync flag handling can stay if it keeps the bootstrap small enough; the elaborate plain-language error printer (~50 lines) is a future-refactor candidate to move into Stage 2.
-
-## Sync impl responsibilities
-
-Stage 2 does all the heavy lifting that currently lives in `bassclef-sync.template.sh`:
-
-- Environment detection (cloud vs desktop vs CI vs mobile-ephemeral)
-- Fetch bassclef tree if not present (sibling > S3 > git clone)
-- Validate tree non-empty
-- Symlink skills / hooks / luminaries / rules / agents / lib into adopter's `.claude/`
-- Wire bassclef-managed PreToolUse hooks into adopter's `.claude/settings.json` (idempotent jq merge)
-- Wire user-level hooks into `~/.claude/` for cloud/CI modality
-- Maintain `.gitignore` block for bassclef symlinks
-- Auto-wire bassclef GitHub Actions workflows
-- Emit session-start banner with status
-
-Stage 2 evolves freely with the substrate. Adopters get the current Stage 2 on every session-start (because the bootstrap finds it fresh each time). No vendoring drift.
-
-## Modality coverage
-
-The bootstrap protocol must serve four adopter modalities:
-
-| Modality | Stage 2 source | Notes |
-|---|---|---|
-| **Sibling-adopter** (desktop dev) | `$CWD/../bassclef/strategy/templates/` | Path 1; fastest; offline-capable; default for operator workstations |
-| **Cloud / CI-adopter** | `source_url` curl-fetch + cache | Path 3; tarball extracted to `~/bassclef-fresh/` (current) or `~/.cache/bassclef/<version>/` (proposed) |
-| **Mobile-ephemeral sandbox** | `source_url` curl-fetch every session | Path 3 only; no sibling; cache survives within session but not across (per `mobile-ephemeral-session.md`); MUST complete in <5 seconds |
-| **npm-adopter** (future, per #266) | `source_url` pointing at npm tarball URL `https://registry.npmjs.org/bassclef/-/bassclef-<version>.tgz` | Path 3 with new URL pattern; bypasses S3; semver-aware; no npm CLI needed (curl-fetch the tarball directly) |
-
-The bootstrap's `source_url` field is provider-agnostic by design. Same code path serves GitHub release tarballs, Azure DevOps, GitLab, S3, and (future) npm tarball URLs. Adopters change providers by editing one field.
-
-## Versioning protocol
-
-Both stages carry an explicit version string near the top:
-
-- Bootstrap: `BASSCLEF_SYNC_VERSION=thin-pointer-YYYY-MM-DD` (e.g., `thin-pointer-2026-06-13`)
-- Sync impl: `BASSCLEF_SYNC_VERSION=YYYY-MM-DD-vN` (e.g., `2026-05-07-v1`)
-
-The bootstrap version is the **bootstrap protocol version** — what shape of contract the bootstrap implements. The sync impl version is the **substrate evolution version**. They evolve on independent cadences:
-
-- Sync impl versions advance every release cycle (often weekly)
-- Bootstrap versions advance only when the bootstrap protocol itself changes (rarely; ideally never after this ADR)
-
-A **version-detection helper** in the bootstrap (added in WU-3) exposes its own version to other code that wants to compare against bassclef's current. Layer 3 self-heal (WU-4) uses this helper to decide whether to refresh an adopter's vendored bootstrap. The helper:
-
-- Bash function `__bassclef_dispatcher_version` returning the version string
-- Greppable from outside: `grep -m1 'BASSCLEF_SYNC_VERSION=' "$VENDORED_PATH" | cut -d= -f2`
-- Comparison logic uses lexicographic ordering on date-stamped strings (YYYY-MM-DD is sortable)
-
-## Consequences
-
-### Easier
-
-- **Substrate evolution is invisible to adopter dispatchers.** Auto_sync flag UX, plain-language error wording, hook-wiring strategies all change in Stage 2 — adopters pick up changes on next session-start without re-vendoring.
-- **Modality migration is one config change.** Moving from S3 to npm is `source_url` edit; adopter dispatcher unchanged.
-- **Mobile-ephemeral is a first-class modality.** Cache strategy in Stage 2 keeps repeat-fetches under <5s budget; bootstrap stays sub-1s.
-- **Layer 3 self-heal becomes mechanical.** Bootstrap version-detection helper exposes a stable interface; self-heal reads + compares + rewrites.
-- **Future renames are non-events.** If `bassclef-sync.template.sh` ever moves or renames, only Stage 2 path changes — bootstrap still finds it via the source_url config.
-
-### Harder
-
-- **Bootstrap protocol changes become expensive.** Any change to the bootstrap interface (new sentinel, new path, new modality) requires version bump + Layer 3 self-heal cycle to propagate. This is the same cost any adopter-observable change carries per ADR-031.
-- **Two-version-string maintenance.** Each release reviews both versions for changes. Tier 0 strict-TDD on the version-detection helper catches drift.
-- **Plain-language errors that surface during fetch failure stay in the bootstrap.** Bootstrap can't ask Stage 2 to format errors when Stage 2 isn't fetchable. The ~50-line error printer is the irreducible price of useful failure messages.
-
-## Implementation status (current → target)
-
-| Capability | Current (thin-pointer-2026-06-13) | Target (post-WU-3) |
-|---|---|---|
-| Path 1 sibling fast-path | ✓ shipped | unchanged |
-| Path 3 curl fallback | ✓ shipped | unchanged |
-| Auto_sync flag check | ✓ shipped (in bootstrap) | Defer move to Stage 2; methodology-acceptable |
-| Plain-language error printer | ✓ shipped (in bootstrap, ~50 lines) | Keep in bootstrap (fetch failure can't reach Stage 2) |
-| Path 2 cache | NOT shipped | Future-refactor; not urgent (mobile-ephemeral fetches every session today) |
-| Version-detection helper | NOT shipped (version string grep-parseable but ad-hoc) | **WU-3 ships this** |
-| npm tarball URL support | NOT shipped (works via source_url naturally; needs documentation) | Document in this ADR; no code change |
-
-**WU-3 ships**: this ADR + version-detection helper in the bootstrap + Tier 0 strict-TDD covering the helper. Aggressive bootstrap refactor (moving auto_sync, moving error printer) is deferred to a future bet; the current shape is stable and working for non-May-3-vintage adopters.
-
-**WU-4 ships**: Layer 3 self-heal extending `migrate-adopter-references.sh` to detect bootstrap version drift via the WU-3 helper and refresh stale vendored bootstraps.
-
-## Alternatives considered
-
-### Alternative 1 — Single fat dispatcher
-
-Keep one ~1500-line script that does everything. Rejected: same vendoring-drift problem we already have; every change requires re-vendoring across every adopter.
-
-### Alternative 2 — Pure HTTP fetcher (no sibling fast-path)
-
-Bootstrap is curl-only; no sibling check. Every session-start fetches from `source_url`. Rejected: breaks offline desktop dev; defeats the speed advantage sibling adopters have; weakens the "bassclef works without internet" property that matters for sustained dev work.
-
-### Alternative 3 — Plugin / dynamic-load architecture
-
-Bootstrap exposes hooks; Stage 2 registers handlers; richer composition. Rejected: bash isn't a plugin runtime; the indirection costs more than the modality-table this ADR ships; over-engineering for the actual problem.
-
-### Alternative 4 — npm-install-only
-
-Bootstrap requires `npm install bassclef` at session-start. Rejected: mobile-ephemeral sandboxes typically don't have npm CLI; would force adopters to install node tooling even for substrate-only use. The curl-the-npm-tarball-URL approach captures npm's CDN + semver benefits without requiring npm CLI.
-
-## Luminaries
-
-- @luminary michael-nygard — **Bulkhead pattern**. Bootstrap failure (can't find Stage 2) doesn't cascade into substrate failure. The bulkhead between vendored adopter code and substrate evolution is the architectural insight.
-- @luminary vaughn-vernon — **Anticorruption Layer**. Bootstrap is the ACL between adopter harness expectations (vendored Bash script in `.claude/hooks/`) and bassclef internal evolution (renames, refactors, new modalities). Adopter harness sees a stable surface; substrate evolves freely behind it.
-- @luminary john-ousterhout — **Deep modules**. Bootstrap has a wide interface (anything Claude Code's hook system can pipe in via stdin) but minimal logic; Stage 2 has a narrow interface (`exec`'d from bootstrap with stdin pipe) but deep functionality. The deep module is the substrate; the shallow exposed surface is the bootstrap.
-- @luminary linus-torvalds — **We don't break userspace**. Bootstrap protocol changes are vanishingly rare; when they happen, they ship with compat shims and version detection (per ADR-031).
-- @luminary hyrum-wright — **All observable behaviors become contracts**. Bootstrap's stdin shape, exit-code semantics, and emitted output are all observable to adopter harnesses. The ADR names them as contracts so future maintainers don't accidentally break them.
-
-## Refs
-
-- bassclef-upstream#261 — dispatcher hardening umbrella ticket
-- bassclef-upstream#266 — npm distribution / S3 deprecation (this ADR explicitly serves)
-- bassclef-upstream#1330 — cold-adopter install.sh missing (the pre-bootstrap step that installs the dispatcher this ADR governs; see architecture doc Subsystem 5)
-- ADR-031 — non-breaking-changes-adopter-discipline (compat shim discipline this ADR composes with)
-- ADR-019 — reference-vs-vendor-distribution (modality coverage)
-- ADR-029 — release pipeline (how Stage 2 ships to public + how install.sh ships once shipped)
-- `strategy/templates/bassclef-sync.dispatcher.template.sh` — current bootstrap (256 lines)
-- `strategy/templates/bassclef-sync.template.sh` — current sync impl (1290 lines)
-- `architecture/tier-system-and-release-flow.md` § "Subsystem 5 — Cold-adopter install bootstrap" — end-to-end view of the pre-dispatcher install step
-- `.claude/rules/we-dont-break-adopters.md` — methodology layer
-- POA 2026-06-22 morning chronicle — failure observation + Five Whys
-- Bet `docs/iteration-bets/2026-06-22b-dispatcher-hardening-rename-orientation.md` (WU-3)

package/substrate/architecture/decisions/ADR-039-release-tagging-scheme.md

@@ -1,145 +0,0 @@
----
-tier: lite
-adr: ADR-039
-title: Release tagging scheme — semver on both upstream and public bassclef
-status: proposed
-date: 2026-07-04
-deciders: operator + bassclef agent
-supersedes: none
-references:
-  - {type: adr, id: ADR-029, anchor: release pipeline contract}
-  - {type: adr, id: ADR-031, anchor: we-don't-break-adopters discipline}
-  - {type: standard, id: standards/release-tagging.md, anchor: the standard this ADR governs}
-  - {type: skill, id: .claude/skills/release/SKILL.md, anchor: the operator surface that cuts tags}
-  - {type: script, id: scripts/release-to-bassclef.sh, anchor: the release pipeline}
-  - {type: issue, id: sunj-labs/bassclef-upstream#614, anchor: filing ticket for the first tag}
-  - {type: bet, id: docs/iteration-bets/2026-07-03b-wave-1-launch-prep.md, anchor: this ADR's parent bet WU-1}
-  - {type: roadmap, id: docs/roadmaps/2026-06-28-early-adopter-launch.md, anchor: Phase XI Batten Down; Wave 1 launch prep}
-luminaries:
-  primary:
-    - linus-torvalds       # kernel version discipline; adopters pin a tag and trust it
-    - frederick-brooks     # conceptual integrity across versions
-  supporting:
-    - michael-nygard       # stability patterns — the release page IS the adopter-facing steady state
-    - hyrum-wright         # every observable version becomes a contract with enough adopters
-description: Bassclef ships from sunj-labs/bassclef-upstream (the source-of-truth repo where all substrate work happens) to sunj-labs/bassclef (the public downstream repo adopters pull from).
----
-
-# ADR-039 — Release tagging on both upstream and public bassclef
-
-## Sources read
-
-- `docs/iteration-bets/2026-07-03b-wave-1-launch-prep.md` L1-80 — parent bet; WU-1 scope names "ADR filed on the bassclef-upstream vs public bassclef tagging split"
-- sunj-labs/bassclef-upstream#614 (ticket body via `gh issue view`) — filing ticket; names four deliverables including this ADR + operator confirmation on the tag name
-- `standards/release-tagging.md` (drafted in this same PR) — the standard this ADR governs
-- `.claude/skills/release/SKILL.md` L1-100 — current release pipeline surface + Step 4 that already tags the source with `release-YYYY-MM-DD-<sha>` marker (distinct from semver tags)
-- `architecture/decisions/ADR-029-release-pipeline.md` — parent architecture (referenced; not re-read tonight since it hasn't changed since prior read on 2026-06-25)
-- `architecture/decisions/ADR-031-non-breaking-changes-adopter-discipline.md` — we-don't-break-adopters; major bumps signal what would otherwise break adopters
-- `architecture/decisions/ADR-035-substrate-as-system-and-hooks-as-steering-surfaces.md` L1-30 — ADR format reference
-- `docs/whereami.md` L1-100 — release pipeline current status (7 commits ahead of public, no open PR)
-
-## What I'm NOT reading (with reason)
-
-- Full ADR-029 body — the pipeline mechanics did not change; this ADR extends with tag cutting, not rewrites the pipeline
-- Public bassclef repo state — deferred to release moment; this ADR is a decision, not a live release
-
-## Context
-
-Bassclef ships from `sunj-labs/bassclef-upstream` (the source-of-truth repo where all substrate work happens) to `sunj-labs/bassclef` (the public downstream repo adopters pull from). The pipeline runs per ADR-029 — `scripts/release-to-bassclef.sh` opens a PR against public bassclef; the operator merges.
-
-Before this ADR the pipeline carried no semver tags. `scripts/release-to-bassclef.sh` cuts a per-release marker tag on upstream (`release-YYYY-MM-DD-<sha>`) that names which SHA a release built from, but the marker tag is not a version adopters can pin, roll back to, or read a changelog against.
-
-Wave 1 adopter dispatch is pending. Adopters need a version anchor for support requests, rollback, and changelog reads. Semver is the widely-known scheme that lets adopters read a version number and know what changed (major = break, minor = new surface, patch = cure).
-
-The question this ADR answers: **do tags cut on bassclef-upstream, public bassclef, or both?**
-
-## Decision
-
-Cut tags on both repos with the same name. `/release` dispatches:
-
-1. Tag `bassclef-upstream` `main` at the source SHA with the semver name (e.g., `v0.1.0`)
-2. Open the `/release` PR against public bassclef (existing pipeline)
-3. Operator merges the PR
-4. Tag `bassclef` `main` at the merged commit with the same semver name (`v0.1.0`)
-
-Both repos carry `v0.1.0` at the release moment. Adopters read the public tag. Operators trace back through the matching upstream tag when investigating "which cut point shipped this rule / hook / skill".
-
-The prior per-release marker tag (`release-YYYY-MM-DD-<sha>`) stays in place on upstream — it serves a different purpose (naming which SHA a release built from) and pre-dates this ADR. Semver tags name what adopters get; marker tags name pipeline mechanics. Both patterns co-exist.
-
-## Alternatives considered
-
-**Alternative A — Tag public bassclef only.** Adopters see one clean version stream; operators lose the ability to trace back to the upstream cut point cheaply.
-
-Rejected because: operators do this trace every time they investigate "when did we ship this rule". `git log` on upstream needs a tag anchor to be cheap.
-
-**Alternative B — Tag bassclef-upstream only.** Operator-facing version stream is complete; adopters have no version to pin against.
-
-Rejected because: adopters pull from public bassclef; their `.bassclef-source.json` `git_ref` field needs a tag on public bassclef, not upstream.
-
-**Alternative C — Different tag names on each repo (e.g., `v0.1.0-upstream` and `v0.1.0-public`).** Names the split explicitly.
-
-Rejected because: adds cognitive load without payoff. Both tags name the same release moment; same name is cleaner.
-
-**Alternative D — Tag both repos with the same name (chosen).** Adopter pull surface and operator trace surface both satisfied. One release moment, one version name, two tags.
-
-## Consequences
-
-### Enables
-
-- Adopters pin `.bassclef-source.json` `git_ref` to a semver tag
-- Rollback: adopters set `git_ref` to a prior tag and re-sync
-- Changelog reads: adopters diff between two tags for what changed
-- Operator trace: `git log v0.1.0..v0.2.0` on upstream lists every PR that shipped between two releases
-- Public bassclef GitHub Releases page renders per-version pages adopters browse
-
-### Requires
-
-- `/release` SKILL amendment — Step 6 adds "cut semver tag on both repos after PR merge"
-- Release notes drafted per `standards/release-tagging.md` grouping
-- Operator confirms tag name at Step 2 (dry-run) — the SKILL surfaces the proposed name; operator confirms or overrides
-
-### Costs
-
-- Two tag-cutting steps per release instead of one — small
-- Release notes drafting adds ~5-10 minutes per release — offset by adopters no longer asking "what changed" questions in support channels
-
-### Risks
-
-- **Tag name collision if `/release` fires twice on the same day** — mitigation: the semver scheme uses monotonic version numbers, not date-based; two same-day releases just bump patch (v0.1.1 then v0.1.2)
-- **Adopter pins the wrong repo's tag** — mitigation: `.bassclef-source.json` schema names `source_url` explicitly pointing at public bassclef; the ADR names public as the adopter-facing tag surface
-
-## Composes with
-
-- `standards/release-tagging.md` — the semver policy + release-notes shape this ADR governs
-- `scripts/release-to-bassclef.sh` — the pipeline that will fire the two tag cuts
-- `.claude/skills/release/SKILL.md` — the operator surface that dispatches
-- ADR-029 release pipeline — the parent architecture
-- ADR-031 we-don't-break-adopters — major bumps signal what would otherwise break adopters
-- `@luminary linus-torvalds` — Linux kernel version discipline; every observable version becomes a contract
-- `@luminary hyrum-wright` — with enough adopters, every version tag becomes load-bearing
-- `@luminary michael-nygard` — the release page is the adopter-facing steady state
-
-## Refs
-
-- sunj-labs/bassclef-upstream#614 — filing ticket
-- sunj-labs/bassclef-upstream#819 — backfill ticket (closed 2026-07-30 per Amendment below)
-- `docs/iteration-bets/2026-07-03b-wave-1-launch-prep.md` — parent bet WU-1
-- `docs/roadmaps/2026-06-28-early-adopter-launch.md` — Phase XI Batten Down
-- ADR-029 release pipeline
-- ADR-031 we-don't-break-adopters
-
-## Amendment 2026-07-30 — pre-split tag boundary
-
-Bassclef-upstream repo was created 2026-06-01 via bulk-import from the older canonical repo (commit `2608a5db`). Public bassclef had already cut tags v0.3.0 through v0.16.0 before that date. Those tags exist only on public bassclef; the upstream repo did not exist yet.
-
-**Decision.** Pre-split tags (v0.3.0 through v0.16.0) are NOT backfilled on upstream. The two histories are distinct. Cutting fake upstream tags at the initial-import commit would misrepresent history.
-
-**Post-split tags** (v0.17.0 onward) ARE backfilled on upstream at the closest matching upstream commit. Backfilled 2026-07-30: v0.17.0 and v0.18.0 at commit `981a84cf`.
-
-**Adopter guidance.** Adopters running early tags (v0.3.0-v0.16.0) reference public bassclef's history for those versions. Upstream tag history starts at v0.17.0. Versions v0.19.0 and later are cut on both repos per the two-tag discipline.
-
-Per #819 Option A chosen 2026-07-30.
-
-## Retirement
-
-This ADR retires only if the two-repo split retires (very unlikely; the split is bassclef's architecture). Semver policy may evolve; the two-tag discipline persists.

package/substrate/architecture/decisions/ADR-040-planning-skill-vocabulary-and-lite-profile.md

@@ -1,155 +0,0 @@
----
-tier: lite
-description: Two adopter-facing signals converged in July 2026 and drove this decision.
----
-
-# ADR-040: Planning-Skill Vocabulary Rewrite and Bassclef-Lite Profile
-
-## Status
-
-ACCEPTED — Decision 4 SUPERSEDED by ADR-044 on 2026-07-19
-
-## Date
-
-2026-07-17
-
-## Supersession note
-
-Decision 4 (SKILL body shape template) is superseded by ADR-044 as of 2026-07-19. Decisions 1, 2, 3, and 5 remain in force. The convergence memo at the operator-private consultation path documents the substrate-clarity gaps ADR-040 D4 left open (INSTEAD-block regression + missing progressive disclosure + missing examples + missing test cases + missing persona-explicit discriminator). Existing SKILL bodies written under ADR-040 D4 read through 2026-10-31 per `.claude/rules/we-dont-break-adopters.md` grace window; new bodies land under ADR-044.
-
-## Context
-
-Two adopter-facing signals converged in July 2026 and drove this decision.
-
-**Signal 1 — jargon leak in planning skill output.** The operator caught bassclef-internal shorthand ("R8 check", "SHOULD-tier gate", "shape a", "bet 16b", "arc walk", "parent chain", "ADR-consult") in three consecutive /longrun prep sessions. The prior cure (bet 2026-07-16b) rewrote /longrun column headers to plain English but left the surrounding prose full of the same shorthand. The vocabulary itself was borrowed from Ryan Singer's Shape Up book — bet, appetite, workunit, parent bet, arc, circuit breaker. Adopters who have not read Shape Up cannot decode the words.
-
-**Signal 2 — adopter architecture review.** An outside architect reviewed the bassclef codebase in July 2026. Findings — bassclef positions as a solo-dev framework but ships enterprise-team complexity. Roughly 120k tokens of rules and guidance load before the user starts working. 70+ skills and 70+ rules where a new user needs only 10-15. Bassclef jargon specifically named — "Temperance, Chronicle, Luminaries, Work Units". Recommended target — under 30k always-loaded context, 60 seconds to first value, 10-15 core capabilities in a light profile.
-
-Twelve luminary consultations plus one adopter usage scan surfaced the decisions this ADR pins.
-
-## Decision
-
-Bassclef ships a lite version alongside the full framework. The rewrite of planning and retrospective skill bodies is the first step. Four rules govern the rewrite. A two-repo release architecture ships the lite version to adopters who want the smaller surface.
-
-### Decision 1 — Vocabulary rename table
-
-Neutral technical terms borrowed from Shape Up rename to plain English. Brand-carrying names stay as skill names but get plain-English descriptions.
-
-| Current | Rename decision | Reason |
-|---|---|---|
-| bet | goal | Cooper (adopter vocabulary); Morville (findability); Singer confirms rename safe (governance meaning is dead code for solo adopters) |
-| appetite | time budget | Singer (preserve fixed-time-variable-scope contract); Norman (plain-English signifier) |
-| workunit | step | Evans/Vernon (adopter's word); Singer confirms not his vocabulary |
-| parent bet | parent goal | Consistency with bet → goal |
-| arc | thread | Cooper (mental model); Morville (findability) |
-| chronicle | ~~session log~~ RETRACTED 2026-08-16 — chronicle preserved as brand-carrying English word per goal 2026-08-16a Louis-lens consult (see Amendment 2026-08-16 below) |
-| circuit breaker (Singer's) | hard stop and re-decide | Names both parts of Singer's mechanism per his file line 61 |
-| shape (as label for operator choices — "shape a", "shape b", "pick shape α") | option (as label — "option a", "option b", "pick option c") | Cooper (keyboard-typeable operator vocabulary); Krug (self-evident label); folds in to `.claude/rules/option-label-discipline.md` |
-| /temperance | **keep as skill name; description reads plain** | Dunford (unique-attribute positioning; produces different behavior than a generic name would) |
-| /luminary | **keep as skill name; description reads plain** | Same reasoning as /temperance |
-| /kiss | **keep as skill name; description reads plain** | Brand-carrying acronym for "keep it simple" |
-
-Terms to keep and gloss plain at first mention per response — fat marker sketch (Singer says the vividness matters), hill chart (metaphor carries meaning), rabbit hole (already plain English).
-
-Old vocabulary keeps working as a compatibility layer through 2026-10-31 grace window per `.claude/rules/we-dont-break-adopters.md`.
-
-### Decision 2 — Reading grade
-
-Grade 10 ceiling for all adopter-facing surfaces. Grade 8-9 aspiration for anything a solo adopter must understand on first read. Grade level is a floor per Norman — a page can pass grade 10 and still fail obvious-on-sight if the words are unfamiliar. Both checks apply.
-
-### Decision 3 — Retire the value-prop "flash" mode
-
-`/value-prop` keeps three modes — tweet, brief, verbose. The flash mode (180-character claim-only output) retires. Per Toulmin, flash carries only the claim and fails the minimum argument shape (claim + evidence + warrant). Per Ousterhout, flash is a shallow interface with no hidden work. Per Beck, the minimum planning artifact is goal + steps + done-markers — not a fragment. The compression discipline (short opening line) folds into brief and verbose modes as the opening sentence.
-
-### Decision 4 — SKILL body shape template (SUPERSEDED by ADR-044 on 2026-07-19)
-
-Every rewritten planning skill body follows this structure per Amazon PR-FAQ, Cooper, Krug, and Beck convergence:
-
-1. H1 with plain-English skill name.
-2. One-paragraph mock announcement — what the reader gets. No bassclef jargon.
-3. One-paragraph "when to use it" — the discriminator.
-4. FAQ section — 4-6 anticipated adopter questions with 2-3 sentence answers.
-5. Details below the fold — protocol for readers who need to run or maintain the skill.
-
-Target length — 200 to 300 lines per skill body. Down from 800-plus in /longrun today.
-
-### Decision 5 — Two-repo release architecture
-
-bassclef-upstream (this repo) stays as the source of truth. Two downstream repos serve two audiences:
-
-- **bassclef** (existing) — full release. Portfolio operators, contributors, adopters who want the whole framework.
-- **bassclef-lite** (new) — curated subset. ~26 core skills grouped by cluster (revised 2026-08-04 per bet 2026-08-04g), ~15 core rules, ~5-10 core hooks, a light CLAUDE.md. For solo devs who want first value in 60 seconds without loading the full framework.
-
-Existing infrastructure supports this — the `lite` tier already exists in the taxonomy per `CLAUDE.md` line 40; the release script at `scripts/release-to-bassclef.sh` already reads and filters by the tier field (lines 275-338). Zero primitives currently carry `tier: lite` (curation has not happened yet). Creating bassclef-lite requires curation plus one release script extension plus a new GitHub repo.
-
-**Skill-count target revision (2026-08-04, bet 2026-08-04g).** The original 10-15 target came from the July 2026 outside architect review — "10-15 core capabilities in a light profile." Cooper walk session 2026-08-02c ran that target through 33 rows of persona-fit judgment. Result: ~26 skills at lite grouped by 5 clusters (3 verbs + 7 discovery + 6 strategy utilities + 5 gates + 3 lifecycle + 2 atomic use-case/user-stories), plus operator Cooper walk overrides that KEEP a few discipline-forward skills (interaction-design, ia-model, ogilvy-writing-audit, pattern-review) at lite via Check 5 discipline. Net range at post-full-reframe: 30-34 skills. Ten of ten luminaries converged on the reframe per canvas `docs/canvases/2026-08-02-porcelain-plumbing-reframe.md` §"Luminary sanity check". Ticket #1050 comment 5160626302 carries operator sign-off on the revised categories. The original 10-15 flat count is superseded by the ~26 clustered count — porcelain-plus-plumbing model gives Sam the same bandwidth relief (3 verbs orient the entry) without paying the discipline cost of dropping named use-case, pre-mortem, and gate skills.
-
-**Ongoing calibration mechanism — `/manifest-align`.** The Cooper walk was a one-time manual pass calibrated by operator judgment. `/manifest-align` (shipped 2026-08-02 per PR #1035) is the ongoing mechanism. It scores every skill against Sam + Louis persona-plus-canvas query vectors using Voyage `voyage-3-lite` cosine embeddings. Runs surface adds and demote candidates in a dated grid at `docs/curation/`. Each run cross-references the current lite-manifest so the ~26 (or 30-34 range) count moves as new adopter personas ship or canvases update. `/manifest-align` runs at ultra tier (needs Voyage keys); results feed operator judgment at the next Cooper walk cycle. The count in this ADR is a snapshot; `/manifest-align` is how it stays honest across the substrate's lifetime.
-
-Adopters point their sync at bassclef OR bassclef-lite via `.bassclef-source.json`.
-
-## Amendment 2026-08-16 — chronicle preserved
-
-Goal `2026-08-16a-786-vocab-root-cures` ran a Louis-only consult (see `docs/personas/2026-07-12-bet11c-louis.md`; consult notes kept operator-internal). Louis reads "chronicle" as familiar English, guesses the skill purpose correctly on first pass, and distrusts rename cascades that touch his repo. The word carries brand voice comparable to `/luminary` and `/kiss`.
-
-**Amendment scope:**
-
-- **Word "chronicle" preserved** in prose. Removed from the Decision 1 rename table above (struck through). Added to `standards/vocabulary-migration.json` `preserved_names` alongside `/luminary`, `/temperance`, `/kiss`.
-- **Directory `chronicle/` stays.** Ticket #1207 (`chronicle/` → `session-log/`) closes as won't-do per Option X of the parent goal decision.
-- **SKILL names unchanged.** Both `/chronicle` and `/session-log` continue to resolve. `/session-log` remains the primary alias per its `SKILL.md` frontmatter; `/chronicle` continues as the compat alias. Either name may be flipped as primary in a future amendment if operator preference shifts.
-- **Wordlist entry removed.** `standards/bassclef-internal-jargon.md` L133 (`chronicle (in prose) | session log | ADVISE`) deleted; new ALLOW row added.
-- **Hook reminder trimmed.** `.claude/hooks/plain-english-steering.sh` L110-121 UserPromptSubmit reminder drops the chronicle rename line. Five D1 renames remain in the reminder: bet → goal, WU → step, parent bet → parent goal, arc → thread, appetite → time budget.
-
-The remaining five D1 renames stay in effect. The parent goal 2026-08-16a ships Option P1 (full commit) on the remaining five via downstream sessions per #841 sweep + wordlist flip + #1142 structural rename.
-
-## Consequences
-
-### Positive
-
-- Adopters get a coherent adopter-release story with plain English AND simple vocabulary AND a light profile in one release cycle
-- Two-tier vocabulary treatment preserves bassclef's opinionated voice at the brand-carrying names (/temperance, /luminary, /kiss) while removing jargon from technical terms
-- The 30k always-loaded context target is reachable via lite curation (drop from 76 rules to ~15 lite-tagged rules)
-- The 60-second first-value target is reachable via Amazon-shape skill bodies (announcement first, protocol below the fold)
-- Adopters who want the full framework keep the current bassclef release; nothing lost
-- Ticket #707 embedding gap (16-18 luminaries without embeddings) does not block lite — lite uses standard-tier LLM matcher which works against files not embeddings
-
-### Negative
-
-- The rewrite is real work — roughly 1200-2100 turns across four tickets (Scope A rewrite, Scope B rewrite, lite curation, lite release infrastructure)
-- Grace window through 2026-10-31 for old vocabulary means bassclef carries dual-vocabulary support cost during migration
-- Two-repo architecture doubles the release workflow surface (bassclef and bassclef-lite both need release runs)
-- Adopters mid-flight who read chronicles from before the rename see the old vocabulary; migration mapping table documents the equivalences
-
-### Risks
-
-- Wrong picks in the lite ~26 could ship a version that fails adopter first-use. Mitigation — POA + twoDo skill-usage scan grounds the pick in real usage data. Post-reframe: Cooper walk 33-row judgment (session 2026-08-02c) plus 10-luminary consensus (canvas 2026-08-02) plus operator sign-off (ticket #1050) triangulate the count.
-- Rewrite drift — new capability might get added during the rewrite (Brooks warning). Mitigation — Tidy First discipline; vocabulary rename ships alone; no new capability
-- Sam persona might not be the primary reader we think they are. Mitigation — feedback from actual first-week adopters of bassclef-lite drives the next iteration
-
-## Alternatives considered
-
-- **Rename Shape Up vocabulary in the SKILL bodies without renaming /temperance and /luminary as skill names** — chose this path per Dunford consultation. Skill names carry brand positioning; renaming loses differentiation.
-- **Keep Shape Up vocabulary and gloss it at first mention** — rejected. Twelve consultations converged on rename. Glossing forever carries reader cost every session.
-- **One rewrite ticket covering all planning skills at once** — rejected. Operator directive to split scope A and scope B into separate tickets. Reduces per-ticket size; preserves feedback opportunities between.
-- **Skip lite version; only rewrite** — rejected. Adam Sharpe's review and the lite profile canvas make the lite version the strategic move; the rewrite is one step of shipping it.
-
-## Sources read
-
-- Twelve luminary consultation notes (operator-private) — phase 1 consolidated proposal, Ryan Singer through Taiichi Ohno round, April Dunford brand voice vs accessibility, POA + twoDo adopter skill-usage scan
-- Strategy notes (operator-private) — outside architect review that set the strategic targets, lite profile canvas, author-time simplicity sister discipline
-- `sunj-labs/bassclef-upstream#738` — parent ticket
-- `sunj-labs/bassclef-upstream#737` — narrow prose-cure ticket (folded into #738)
-- `.claude/rules/plain-english-discipline.md` — master rule the rewrite satisfies
-- `.claude/rules/we-dont-break-adopters.md` — governs the grace window
-- `standards/bassclef-internal-jargon.md` — wordlist source of truth
-- `CLAUDE.md` line 40 — tier taxonomy including `lite`
-- `scripts/release-to-bassclef.sh` lines 275-338 — existing tier-filter infrastructure
-
-## References
-
-- Ticket #738 — parent ticket carrying the phased rewrite
-- Ticket #737 — folded; closed as duplicate of #738
-- Ticket #707 — luminary embedding backfill (does not block lite)
-- ADR-031 — non-breaking-changes-adopter discipline (governs the grace window)
-- ADR-029 — release pipeline (extends to cover bassclef-lite target)
-- Follow-on tickets (to file after this ADR) — Scope B rewrite, lite curation, lite release infrastructure, CLAUDE.md staleness cure