@thebassclef/lite 0.1.2 → 1.0.0

package/substrate/standards/lite-manifest-schema-changes.md

@@ -1,135 +0,0 @@
----
-tier: lite
-description: Chronological ledger of every lite-manifest schema change. Adopters read this before sync to know what shifted.
----
-
-# Lite-manifest schema changes
-
-This ledger records every change to `standards/lite-manifest.schema.json` and to the shape of `<tier>-manifest.json` output. Adopters that consume the manifest read this file before every `bassclef-sync` run that crosses a version boundary. Each entry names the change type, the version bumps, the recommended downstream cure, and any retirement timeline.
-
-Sister to `standards/file-renames.json` (which tracks file-level renames). Same discipline shape at a different surface. Per `.claude/rules/lite-manifest-schema-change-discipline.md`.
-
-## Format
-
-Every entry follows this shape. Entries are newest-first for ease of scan.
-
-```
-### <SHORT TITLE> (<manifest_version bump>, <YYYY-MM-DD>)
-
-- **Change type:** field-add | field-remove | field-rename | content-remove | content-add | policy-change
-- **Fields:** <field names — comma-separated>
-- **Version bump:** vX.Y.Z → vA.B.C (reason)
-- **Rationale:** <link to issue / PR / body of the change>
-- **Downstream cure:** <what adopters need to do — usually nothing if optional-add; sometimes a code change if content shape shifts>
-- **Old shape retired:** <immediately | date | never (compat shim kept)>
-```
-
-Adopters MAY grep for the change type they care about. Adopter tooling MAY parse the ledger as flat markdown.
-
-## Retention
-
-Every entry stays in this file for the life of the manifest. Never pruned. When entries grow past ~30, split by year into archive files under `standards/lite-manifest-schema-changes-archive/YYYY.md` (not shipped yet — first split due when the year rolls over).
-
----
-
-## Entries (newest first)
-
-### Tier alignment cure batch 6 + arc (73 flips + 21 source scrubs + adopter-doc rewrite) (v1.5.6 → v1.5.7, 2026-09-11)
-
-- **Change type:** content-add + content-normalization
-- **Fields:** manifest entry list gains 79 files across two waves. Batch 6 (2026-09-10, PR #1596) added 6 adopter-facing files flipped standard → lite. The 3-PR tier walk cleanup arc (2026-09-10 through 2026-09-11) added 73 more flipped files (PR #1599) plus 1 promoted from upstream → standard (`.claude/rules/sibling-smoke-after-substrate-change.md`). The arc also shifted `content_hash` on ~15 already-present entries whose bodies were edited during PR #1600 source-body scrubs and PR #1601 README + CONTRIBUTING rewrites. Notable entries added at lite tier: `.claude/rules/we-dont-break-adopters.md`, `.claude/rules/api-conventions.md`, `.claude/rules/schema-management.md`, `.claude/rules/hook-wire-on-author.md`, `.claude/rules/defensive-bash.md`, `.claude/rules/deferred-actions.md`, `.claude/rules/turn-estimate-grounding.md`, `.claude/rules/visual-hierarchy.md`, `.claude/rules/option-label-discipline.md`, `.claude/rules/pr-title-shape.md`, `.claude/rules/reserved-skill-names.md`, `.claude/rules/marker-enrichment-discipline.md`, `.claude/rules/new-dependency-check.md`, `.claude/rules/prototype-workflow.md`, `.claude/rules/longrun-prep-plan-doc-compression.md`, `.claude/rules/skill-procedure-step-list.md`, `.claude/rules/substrate-config-schema.md`, `.claude/rules/test-sufficiency.md`, `.claude/rules/wu-sequencing-compounds.md`, `.claude/rules/compounding-sequence-fresh-analysis.md`, `.claude/rules/iteration-bet-brief-completeness.md`, plus 4 luminaries (glenford-myers, hunt-thomas, vaughn-vernon, w-edwards-deming), 6 skills (chronicle, clean-artifacts, feynman, journal, visual-review, whats-the-plan), and 22 standards.
-- **Version bump:** v1.5.6 → v1.5.7 (patch; content-only add + content-normalization on ~15 pre-existing entries whose bodies were edited; no schema shape shift)
-- **Rationale:** Tier walk cleanup arc (parent ticket bassclef-upstream#1595). The arc followed the persona-grounded cleanup grid classified via `/extract-intent` (0.92 confidence) + fork classifier during session 2026-09-10e. Grid split 185 walker edges into three cures: PR A `#1599` shipped 73 tier flips + 1 promotion; PR B `#1600` shipped 21 source-body scrubs across 15 files (5 DROP + 12 BACKTICK + 3 REWRITE + 1 auto); PR C `#1601` rewrote README + CONTRIBUTING for adopter audience without naming operator-only file paths. Batch 6 `#1596` shipped separately the day before under the same parent. Walker delta across the arc: 114 → 112 lite alignment violations (net; 109 explicit closures across the arc; residual 107 exposed by transitive walk during the flip stage; final 112 approaches the ~73-edge irreducible substrate machinery floor).
-- **Downstream cure:** No adopter code change needed. Adopters that sync will receive 79 new files in their lite manifest bundle plus fresh `content_hash` on ~15 previously-present files. Consumers reading `.entries[].path` see a longer list. Consumers using `.entries[].content_hash` for change detection see hashes shift on modified files (expected behavior; that field records live file state). Consumers pinning `~1.5` stay green (patch-level compatible). `manifest_version` field type unchanged; no field added, removed, or renamed.
-- **Old shape retired:** Never. Files existed before at higher tier; only tier tag changed for adds. For content-normalization on the ~15 modified entries, the field shape stayed the same; only the body content shifted (which is what `content_hash` is for).
-- **Related tickets:** bassclef-upstream#1595 (parent tier walk arc). Merged PRs: #1596 (batch 6), #1599 (arc PR A), #1600 (arc PR B), #1601 (arc PR C admin-merged as e31d25bc).
-
-### Tier alignment cure batch 5 — 15 adopter-facing rules + standards flipped to lite (v1.5.5 → v1.5.6, 2026-09-09)
-
-- **Change type:** content-add
-- **Fields:** manifest entry list gains 15 files that flipped tier tags to lite. High-confidence flips (9): `.claude/rules/accessor-library-discipline.md` (state accessor rules), `standards/reserved-skill-names.md` (skill authoring gate), `standards/substrate-config-schema.md` (adopter config schema), `standards/hook-install-class.md` (hook install class declarations), `standards/bash-hook-safety.md` (bash hook safety rules), `.claude/rules/pattern-annotation.md` (`@pattern` annotation contract), `.claude/rules/mobile-ephemeral-session.md` (mobile session discipline), `.claude/rules/loop-discipline.md` (per-PR six-step cycle), `.claude/rules/cold-adopter-harness-discipline.md` (adopter harness discipline). Judgment-call flips (6): `.claude/rules/stuck-signal-diagnostic.md` (diagnostic pattern for repeated warnings), `.claude/rules/skill-composition-declarations.md` (`composes_with` + `depends_on` fields), `.claude/rules/plan-enumeration-needs-value-props.md` (plan doc format discipline), `standards/velocity-and-appetite.md` (planning discipline), `standards/composer-prerequisites.md` (chain composition rules), `standards/code-safety-principles.md` (universal code discipline).
-- **Version bump:** v1.5.5 → v1.5.6 (patch; content-only add, no schema shape shift)
-- **Rationale:** Batch 5 of the tier alignment cure sequence (parent ticket bassclef-upstream#1568). Every target is a rule or standard adopters need to make their lite skills, hooks, and state accessors work correctly. Loop-discipline was previously `tier: upstream`; flipped to lite alongside the standard-tier group per same rationale — adopters run PRs, so per-PR discipline is adopter-facing.
-- **Downstream cure:** No adopter code change needed. Adopters that sync will now receive these 15 files in their lite manifest bundle. Consumers reading manifest entries see 15 new paths. No field shape change. No content change on unchanged entries.
-- **Old shape retired:** Never. Files existed before at higher tier; only tier tag changed.
-- **Related tickets:** bassclef-upstream#1568 (parent tier graph walk audit). Sister PRs same session: #1573 (batch 1) + #1576 (batch 1b) + #1577 (batch 2) + #1578 (batch 3) + #1579 (batch 4).
-
-### Tier alignment cure batch 4 — 7 adopter-facing rules + Hyrum luminary flipped to lite (v1.5.4 → v1.5.5, 2026-09-09)
-
-- **Change type:** content-add
-- **Fields:** manifest entry list gains 7 files that flipped tier tags from standard to lite. All 7 are files adopters need to make their lite skills work. Rules: `testing-tier-config.md` (which tier of test per path), `github-issue-flash-tweet.md` (issue body format for `gh issue create`), `test-list-discipline.md` (Beck test-list authoring), `skill-description-clarity.md` (authoring skill descriptions), `bootstrap-pair-discipline.md` (every substrate building block ships paired), `adr-discipline.md` (ADR authoring per Nygard lifecycle). Luminary: `hyrum-wright.md` (design lens for observable behavior — sister to Hoare from batch 3).
-- **Version bump:** v1.5.4 → v1.5.5 (patch; content-only add, no schema shape shift)
-- **Rationale:** Batch 4 of the tier alignment cure sequence (parent ticket bassclef-upstream#1568). Shape e ADVISORY reported 38 alignment warnings where lite skills cited these 7 targets. Every target is adopter-facing: adopters test their own code (testing-tier-config, test-list-discipline), file issues (github-issue-flash-tweet), author skills (skill-description-clarity, bootstrap-pair-discipline), and author ADRs (adr-discipline). Hyrum luminary is cited from lite skills as a design lens the same way Hoare was in batch 3.
-- **Downstream cure:** No adopter code change needed. Adopters that sync will now receive these 7 files in their lite manifest bundle. Consumers reading manifest entries see 7 new paths. No field shape change. No content change on unchanged entries.
-- **Old shape retired:** Never. Files existed before at higher tier; only tier tag changed.
-- **Related tickets:** bassclef-upstream#1568 (parent tier graph walk audit). Sister PRs same session: #1573 (batch 1) + #1576 (batch 1b) + #1577 (batch 2) + #1578 (batch 3).
-
-### Tier alignment cure batch 3 — chronicle template + Hoare luminary flipped to lite (v1.5.3 → v1.5.4, 2026-09-09)
-
-- **Change type:** content-add
-- **Fields:** manifest entry list gains 2 files that flipped tier tags from higher to lite. `templates/chronicle-template.md` flipped from `tier: upstream` to `tier: lite`; adopters use it via session-end and session-log skills to write their own session logs. `.claude/luminaries/tony-hoare.md` flipped from `tier: standard` to `tier: lite`; cited by 16 lite-tier sources (skills + rules + hooks) as a design lens for pre/postcondition contracts.
-- **Version bump:** v1.5.3 → v1.5.4 (patch; content-only add, no schema shape shift)
-- **Rationale:** Batch 3 of the tier alignment cure sequence (parent ticket bassclef-upstream#1568; sister PRs #1573 + #1576 + #1577 in the same session). Shape e ADVISORY reported 21 alignment violations where lite skills cited these two standard-or-higher targets. Both targets are files adopters need — chronicle template ships as adopter session-artifact scaffolding; Hoare luminary ships as a design lens the lite skill catalog references. Flipping targets down cures the 21 violations without touching source semantics.
-- **Downstream cure:** No adopter code change needed. Adopters that sync will now receive the chronicle template + Hoare luminary in their lite manifest bundle. Consumers reading manifest entries see 2 new paths (`templates/chronicle-template.md` + `.claude/luminaries/tony-hoare.md`). No field shape change. No content change on unchanged entries.
-- **Old shape retired:** Never. Both files existed before; only tier tag changed.
-- **Related tickets:** bassclef-upstream#1568 (parent tier graph walk audit). Sister PRs same session: #1573 (batch 1 — 74 files) + #1576 (batch 1b — 10 sister-path files) + #1577 (batch 2 — 2 straggler tests).
-
-### Em-dash encoding normalized + content jargon cleanup (v1.5.2 → v1.5.3, 2026-09-08)
-
-- **Change type:** content-normalization + content-refresh
-- **Fields:** every string field (`description` + `problem` + `value`) that carried a `—` YAML escape in SKILL.md source. 20 lines in v1.5.2 lite manifest carried the raw `—` shape; all 84 em-dashes now emit as literal `—` character in JSON. Content refresh: /personas + /interpret-input SKILL.md body prose drops internal ticket refs (`#200` + `#1427`); descriptions updated to plain English.
-- **Version bump:** v1.5.2 → v1.5.3 (patch; content-only normalization and refresh, no schema shape shift)
-- **Rationale:** Downstream bassclef-web renderer at PR #274 writes manifest strings verbatim into MDX pages. Fields with the `—` escape rendered as raw 6-character text on docs.bassclef.dev instead of the em-dash glyph. Extractor now calls `normalize_em_dash` on every extracted YAML string; jq encodes uniformly. Peirce option a from ticket body. Content refresh addresses jargon leakage in SKILL bodies — adopters reading docs see plain sentences instead of internal ticket numbers.
-- **Downstream cure:** No adopter code change needed. Consumers reading strings via `JSON.parse` see em-dash character consistently. Adopters that pinned exact description strings (unlikely) get updated content. Intent-drift check: /personas cosine 0.9924, /interpret-input cosine 0.9823 — both above the 0.90 threshold, intent preserved.
-- **Old shape retired:** Never. Content shape stable; only normalization + prose refresh applied.
-- **Related tickets:** bassclef-upstream#1548 (em-dash bug — this bump). bassclef-web#264 fold (content jargon cleanup — this bump). Sister ticket bassclef-web#275 covers the downstream renderer for `composes_with` + `depends_on` (extractor already emits both; renderer catch-up is the actual gap).
-
-### Content backfill: 96 skills gain curated descriptions (v1.5.1 → v1.5.2, 2026-09-07)
-
-- **Change type:** content-add
-- **Fields:** `description` on 34 lite + 62 standard SKILL.md files (96 total; lite manifest ships 34 populated). No schema change; the `description` field has always existed.
-- **Version bump:** v1.5.1 → v1.5.2 (patch; content-only change, no schema shape shift)
-- **Rationale:** Extends v0.37.1 four-field backfill with the 5th field. bassclef-web launch on 2026-09-09 renders `description` alongside `problem` + `value` + `inputs` + `outputs`. Prior descriptions passed skill-description-clarity discipline but 5 exceeded the 280-char ceiling and others missed inline mode/size names. Ogilvy discipline applied — verb-first, ≤270 chars, name modes inline, grade 8-9.
-- **Downstream cure:** No adopter code change needed. Renderers that already project the description field see updated content. Same pin-update guidance as v0.37.1 — loosen exact string pins to a semver range.
-- **Old shape retired:** Never. Field shape stays. Content is fresher.
-- **Related tickets:** bassclef-upstream#1533 (description class — this bump cures the skill surface; non-skill types still deferred until extractor extends).
-
-### Content backfill: 96 skills gain problem + value + inputs + outputs (v1.5.0 → v1.5.1, 2026-09-07)
-
-- **Change type:** content-add
-- **Fields:** `problem`, `value`, `inputs`, `outputs` on 34 lite + 62 standard SKILL.md files (96 total; lite manifest ships 34 populated). Non-skill entries continue to omit these fields per Hoare H5 skill-surface guard.
-- **Version bump:** v1.5.0 → v1.5.1 (patch; content-only change, no schema shape shift)
-- **Rationale:** bassclef-web launches 2026-09-09 with a docs page that renders four new columns per skill card. Upstream fields shipped OPTIONAL in v0.37.0; this release ships the curated content. Extractor uses naive comma-split, so items avoid embedded commas by design (use "or"/"and" as connectors).
-- **Downstream cure:** No adopter code change needed. Renderers that already project the 4 fields (bassclef-web PR #271) now see populated content. Renderers that ignore unknown keys continue working. This release does not shift the schema — schema stays v1.6.0 in title description; manifest content version 1.5.0 → 1.5.1.
-- **Old shape retired:** Never. Non-skill entries continue to omit the 4 fields.
-- **Related tickets:** bassclef-upstream#1544 (also fixed same PR — /substrate-check symlink→file rewrite for npm-copy reality), bassclef-web#268 + #269 (closed downstream via v0.37.0 refresh).
-
-### 4-field add: inputs + outputs + problem + value (v1.5.0 → v1.6.0, 2026-09-07)
-
-- **Change type:** field-add
-- **Fields:** `inputs`, `outputs`, `problem`, `value` (all on entry — skill surface only)
-- **Version bump:** v1.5.0 → v1.6.0 (minor; adding OPTIONAL fields is backward-compatible per schema title description)
-- **Rationale:** bassclef-web#268 acceptance (docs.bassclef.dev needs 4 scan-anchors per lite skill card). Extractor upgrade in goal 2026-09-07c per `docs/iteration-bets/2026-09-07c-lite-manifest-schema-plus-extractor-plus-backfill-plus-ledger.md`. Fields ship OPTIONAL per Hoare H2 pre-mortem cure.
-- **Downstream cure:** No adopter code change needed. Parsers that ignore unknown keys continue working. Parsers that pin to exact `v1.5.0` string should loosen to a semver range like `>=1.5.0 <2.0.0` before v0.37.0 sync.
-- **Old shape retired:** Never. All prior entries stay valid (fields are OPTIONAL, not required).
-
-### upstream_commit content removed (v1.4.x → v1.5.0, 2026-09-06)
-
-- **Change type:** content-remove
-- **Fields:** `upstream_commit` (was at manifest top level, alongside `manifest_version` + `generated_at`)
-- **Version bump:** v1.4.x → v1.5.0 (minor; field removed at top level, not from entry shape)
-- **Rationale:** upstream sunj-labs/bassclef-upstream#1508 removed the field from manifest content because the value drifted between release cascade steps. Fix at commit `d20c0652` on main.
-- **Downstream cure:** bassclef-web scripts that read `upstream_commit` crashed at v0.36.0 sync (3 scripts). Cure at bassclef-web commit `c9a9da7` — derive the commit locally from `git -C <upstream> rev-parse HEAD` when the value is needed. bassclef-cli sync path had the same class; check for reads of `upstream_commit` before v0.37.0 pull.
-- **Old shape retired:** Immediately (field was removed with no compat shim). This retroactive entry documents the class that motivated the ledger discipline (per bassclef-web#269).
-
-## Related files
-
-- `standards/lite-manifest.schema.json` — the schema this ledger tracks
-- `standards/file-renames.json` — sister ledger at the file-rename surface
-- `.claude/rules/lite-manifest-schema-change-discipline.md` — methodology layer that enforces this ledger
-- `.claude/rules/we-dont-break-adopters.md` — ADR-031 parent discipline
-- `scripts/release-to-bassclef.sh` — release script that pre-flight-checks this ledger
-
-## Retirement condition
-
-This ledger retires only if bassclef stops shipping a lite manifest. Adopter count and schema change cadence may evolve; the discipline of documenting every change persists.

package/substrate/standards/luminary-matching.md

@@ -1,105 +0,0 @@
----
-tier: lite
-description: Bassclef core picks luminaries for variant generation via a single LLM call to the configured model provider.
----
-
-# Luminary Matching — Bassclef Core LLM Pick
-
-Bassclef core picks luminaries for variant generation via a **single LLM call** to the configured model provider. The model reads the operator's intent paragraph plus a compact catalog summary (slug + primary domain + name) and returns N slugs whose perspective fits the UX + interaction patterns the intent implies.
-
-No separate embedding vendor. No second-stage judge. One call, one provider, one model key — the same key the consumer is already using for everything else.
-
-Adopters running the optional two-repo pattern (per `standards/operator-private-discipline.md`) who want richer signal (embedding shortlist + LLM judge) layer their own `/extract-intent` skill in their operator-private sibling via `additionalDirectories`. When loaded, that skill takes precedence and bassclef core stays oblivious.
-
-## Rule
-
-Bassclef core's luminary picker uses:
-
-- The operator's intent text (from `InputArtifact.intent` or a paragraph supplied at dispatch)
-- The catalog at `state/luminary-implementations/*.json` (slug + primary_domain + name only)
-- The configured model provider (`config/model-routing.yaml`)
-
-It does NOT use:
-
-- Separate embedding APIs
-- Keyword/regex/grep scoring as the primary path
-- Pre-computed embeddings cache
-
-## When matching fires
-
-Any composer or skill that needs to ground variant generation in named luminaries:
-
-- `/launch` Phase 3.5 — variants pre-grounded
-- `/stage` Phase 3.5 — same
-- `/riff-prototypes` — when invoked standalone (no upstream grounding artifact)
-- `/luminary recommend` — when LLM picker is available
-
-The picker fires once per intent. Variant generation in Phase 4 reads its output and assigns luminaries to the N luminary-driven variants. The Anthropic baseline always lands regardless.
-
-## Adapter — `lib/luminary-pick.sh`
-
-The adapter exposes:
-
-```bash
-luminary_pick "<intent text>" <N> <output_json_path>   # full pipeline
-luminary_pick_status                                   # report LIVE or OFFLINE
-```
-
-Output JSON shape:
-
-```json
-{
-  "matched_luminaries": ["alan-cooper", "edward-tufte", "jakob-nielsen"],
-  "rationale": "Cooper for goal-directed flows; Tufte for data density; Nielsen for findability.",
-  "picker_version": "bassclef-llm-pick-1.0"
-}
-```
-
-## Modes
-
-| Mode | Trigger | Behavior |
-|---|---|---|
-| **LIVE** | `ANTHROPIC_API_KEY` set | Single LLM call; returns matched slugs |
-| **OFFLINE** | Key missing or LLM call fails | Picker refuses; downstream falls back to `/luminary recommend` signal scoring |
-
-## Fallback path
-
-If the LLM picker refuses or errors:
-
-1. Composer logs the refusal
-2. Falls back to `/luminary recommend` signal scoring (keyword + Garrett-plane + primary-domain coverage)
-3. Continues with variant generation against the signal-scored picks
-
-Operator can also opt into the signal-scoring path explicitly via `/riff-prototypes --use-signal-scoring` to skip the LLM call entirely.
-
-## Operator-private override (optional two-repo pattern)
-
-Adopters running the optional two-repo pattern (per `standards/operator-private-discipline.md`) can layer their own `/extract-intent` skill — operator-private substrate that ships richer signal (embedding shortlist + LLM judge) — via `additionalDirectories` injection. When that skill is present:
-
-- `/launch`, `/stage`, `/riff-prototypes` prefer the operator-private `extracted_intent_grounding.matched_luminaries`
-- bassclef-core's `/pick-luminaries` becomes a fallback path
-- bassclef core stays oblivious to whether the operator-private override is loaded
-
-This is the SENTINEL_bassclef_pattern: the operator-private sibling is a superset of bassclef-core. Operators load both and get the upgraded experience; cold adopters load only bassclef and get the LLM-pick default.
-
-## Composes with
-
-- `lib/luminary-pick.sh` — the adapter
-- `.claude/skills/pick-luminaries/SKILL.md` — operator-callable wrapper
-- `state/luminary-implementations/*.json` — catalog manifest
-- `config/model-routing.yaml` — provider selection
-- `/launch` Phase 3.5 + `/stage` Phase 3.5 + `/riff-prototypes` — consumers
-
-## Override + escape hatches
-
-- `/riff-prototypes --luminaries=<slug1>,<slug2>,...` — operator pin (skips picker entirely)
-- `/riff-prototypes --use-signal-scoring` — skip LLM pick; use `/luminary recommend` signal scoring
-- `LUMINARY_PICK_MODEL=<id>` — override the default Haiku-4-5 model
-
-## Sources read
-
-- bassclef#476 LR8.10/8.11 — luminary catalog + traceability
-- bassclef#944 — Voyage matcher excision; replaces ADR-017's two-vendor pipeline with this LLM-pick approach
-- docs/iteration-bets/2026-06-13a-cold-adopter-unboxing-arc.md — parent goal (WU-3)
-- `standards/model-routing-discipline.md` — provider selection mechanism this adapter uses
-