@thebassclef/lite 0.1.0 → 0.1.3

package/substrate/standards/input-handler-interface.md

@@ -0,0 +1,152 @@
+---
+tier: lite
+description: "The interface contract between operator inputs (text / URL / image / repo / transcript / napkin / mixed) and the cameo pipeline's extraction layer."
+---
+
+# Input Handler Interface
+
+The interface contract between operator inputs (text / URL / image /
+repo / transcript / napkin / mixed) and the cameo pipeline's
+extraction layer. `/interpret-input` produces a normalized `InputArtifact`
+from any input shape; downstream skills (`/objectory-decompose`,
+`/value-prop`, `/personas`) consume the normalized artifact, never raw
+operator input.
+
+This standard is the contract. The implementation is
+`.claude/skills/interpret-input/SKILL.md` + `scripts/interpret-input.sh`.
+Schema lives at `standards/state-spine/schemas/input-artifact.schema.json`.
+
+## Why this exists
+
+Without an input-handler interface, every input shape requires its own
+extraction code path. Adding a new input mode (e.g., PowerPoint slides,
+PRD documents) means re-shaping the entire chain. The interface lets us:
+
+- Implement extractors as ADAPTERS to the same downstream contract
+- Test each extractor independently against the same schema
+- Add new extractors without changing core extraction semantics
+- Validate inputs structurally at the boundary
+
+Per parent bet's amendment 2026-04-26c: original Phase B baked text-only
+into `/objectory-decompose --text`, deferring abstraction to Phase C.
+This forced a Phase B → Phase C refactor. The current shape establishes
+the interface from day one with text as the first extractor implementation.
+
+## Sources read
+
+- `docs/iteration-bets/2026-04-25-example-pipeline.md` Phase B amendment 2026-04-26c — interface-establishing rationale
+- `docs/iteration-bets/2026-04-27d-example-pipeline-phase-b-mvp.md` WU-A — implementation scope
+- `standards/state-spine/schemas/input-artifact.schema.json` — schema this contract references
+- `standards/state-spine.md` §"Storage format" — InputArtifact is Shape C (pure JSON at `docs/input-artifacts/<slug>.json`)
+- `.claude/luminaries/martin-fowler.md` — Adapter pattern (each extractor adapts a source shape to the InputArtifact contract)
+
+## Auto-detection heuristic
+
+When `--type` is `auto` (default), `/interpret-input` infers type from
+the source string:
+
+| Pattern | Detected type |
+|---|---|
+| `^https?://` (URL prefix) | `url` |
+| `\.(png\|jpg\|jpeg\|gif\|webp\|svg)$` (image extension) | `image` |
+| `\.git$` or `github\.com` (repo URL/path) | `repo` |
+| (default) | `text` |
+
+Operator overrides by passing `--type=transcript` / `--type=napkin` /
+`--type=mixed` explicitly. Auto-detection cannot distinguish a typed
+transcript from prose, nor a hand-drawn napkin from a regular image —
+both default to `text` and `image` respectively without explicit override.
+
+## Extractor responsibilities
+
+Each extractor implements one input type. Common responsibilities:
+
+| Step | What | Required |
+|---|---|---|
+| 1. Receive raw input | Accept `source` argument verbatim | yes |
+| 2. Validate / normalize | Trim, decode, check existence (for paths) | yes |
+| 3. Populate `extracted_text` | Produce normalized prose for downstream | yes |
+| 4. Populate `structural_hints` | Extract type-specific signals when available | optional |
+| 5. Populate `external_urls` | URL regex matches in source / extracted text | optional |
+| 6. Schema validate | Output must conform to InputArtifact schema | yes |
+
+`extracted_text` is the load-bearing output — `/objectory-decompose`
+operates on it. `structural_hints` are best-effort enrichment.
+
+## Phase B vs Phase C scope
+
+**Phase B (this MVP, WU-A)**: text mode is fully implemented. Other
+modes return stub `InputArtifact` with:
+
+- `type: <name>` (correct)
+- `source: <input>` (correct)
+- `extracted_text: "deferred to Phase C"` (sentinel value)
+- All structural_hints empty
+- `external_urls: []`
+
+This lets downstream skills (`/objectory-decompose`, `/preview`)
+exercise the interface against any input type without breaking on
+"extractor not implemented." Stub artifacts are still schema-valid.
+
+**Phase C (follow-up goal)**: implements remaining extractors as ADAPTERS
+against this contract. No core extraction changes; only new extractor
+implementations.
+
+| Type | Extractor approach | Phase |
+|---|---|---|
+| text | Identity (extracted_text = source); URL regex for external_urls | B (this MVP) |
+| url | Fetch + readable-text scrape; cite references | C |
+| image | Vision-based UI-element extraction → boundary_objects | C |
+| repo | Read README + top-level structure + open issues | C |
+| transcript | Speaker-tagged actor → verb mapping | C |
+| napkin | Hand-drawn diagram → entities + boundary_objects | C |
+| mixed | Compose multiple extractors over multi-source input | C |
+
+## Storage shape
+
+InputArtifact is Shape C (pure JSON) per `standards/state-spine.md`
+§"Storage format":
+
+```
+docs/input-artifacts/<slug>.json
+```
+
+Validated at write by `state-validate.sh` PreToolUse hook against
+`input-artifact.schema.json`. Operator-readable narrative belongs in
+chronicles + decompositions, not in InputArtifact bodies.
+
+## Slug convention
+
+```
+<YYYY-MM-DD>-<type>-<6-char-hash-of-source>
+```
+
+Examples:
+- `2026-04-27-text-3a1b2c` (text input from operator paragraph)
+- `2026-04-27-url-9f8e7d` (URL extraction)
+- `2026-04-27-repo-1a2b3c` (repo extraction)
+
+Operator may override via `--slug=<custom>` for memorable fixtures
+(e.g., `2026-04-27-poa-five-pandas-rework`).
+
+## Naming convention
+
+Skills using InputArtifacts read via `state_reference_get input-artifact <slug>`
+per `standards/state-spine-contract.md`. Direct `cat docs/input-artifacts/<slug>.json`
+is forbidden by `accessor-library-discipline.md`.
+
+## Relationship to other standards
+
+- `standards/state-spine.md` §"Storage format" — InputArtifact is Shape C
+- `standards/state-spine/schemas/input-artifact.schema.json` — formal schema
+- `standards/state-spine-contract.md` — accessor surface for reading
+- `.claude/rules/accessor-library-discipline.md` — read-discipline applies
+- `.claude/skills/interpret-input/SKILL.md` — the skill that produces InputArtifacts
+- `.claude/skills/objectory-decompose/SKILL.md` — primary downstream consumer
+- `.claude/skills/preview/SKILL.md` — composer that orchestrates the chain
+
+## Versioning
+
+This contract is v0. New extractor additions are non-breaking (additive).
+Schema changes (new required fields, removed properties) are v1; ship as
+parallel `input-artifact-v1.schema.json` per Fowler expand-and-contract.

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

@@ -34,6 +34,66 @@ Every entry stays in this file for the life of the manifest. Never pruned. When
 
 ## 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

package/substrate/standards/luminary-matching.md

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

package/substrate/standards/migration-discipline/active-record.md

@@ -0,0 +1,50 @@
+---
+tier: lite
+description: The ActiveRecord sibling of .claude/rules/schema-management.md.
+---
+
+# ActiveRecord (Rails) — migration discipline
+
+The ActiveRecord sibling of `.claude/rules/schema-management.md`. Loads when adopter's `tech_stack.orm` is `active-record`.
+
+## Non-negotiable rule
+
+**NEVER edit `db/schema.rb` (or `db/structure.sql`) by hand.** Those files are derived artifacts — Rails regenerates them after every migration. Hand-editing them ships drift the moment another developer runs `rails db:migrate`.
+
+## Workflow
+
+1. Generate the migration: `rails generate migration DescriptiveName field:type field:type`
+2. Review the generated file in `db/migrate/` — Rails generators are good but not infallible; manual edits often required for:
+   - Foreign keys + cascading deletes
+   - Add-index on large tables (`algorithm: :concurrently` for Postgres)
+   - Compound conditions on `add_column` (`null: false, default: ...`)
+3. Apply locally: `rails db:migrate`
+4. Commit the migration file AND the regenerated `db/schema.rb` (or `db/structure.sql`)
+5. On deploy, CI runs `rails db:migrate`
+
+## After DB reset
+
+1. `rails db:setup` (runs migrations + seeds)
+2. Or `rails db:create db:migrate db:seed`
+
+## After merging a branch with schema changes
+
+1. `rails db:migrate` — apply pending migrations
+2. Restart the Rails server — ActiveRecord caches schema metadata at boot
+3. Run the test suite (`bundle exec rspec` or `rails test`) — schema-coupled tests catch missed migrations
+
+## Drift check
+
+`rails db:migrate:status` lists every migration + its applied/pending state. Pending migrations = drift.
+
+## Common pitfalls
+
+- **`change_column` is one-way unless you write a reversible block** — manual `up` + `down` methods needed for non-reversible changes
+- **Large-table migrations block writes** — use `strong_migrations` gem to lint; index changes especially need `add_index :table, :col, algorithm: :concurrently` on Postgres
+- **`rake db:reset` in dev hides production migrations** — only re-runs from schema.rb; doesn't re-test migration files end-to-end
+
+## Sources
+
+- Rails Guides — Active Record Migrations (https://guides.rubyonrails.org/active_record_migrations.html)
+- strong_migrations gem (https://github.com/ankane/strong_migrations)
+- Rails discipline ported from Prisma shape; ActiveRecord's auto-regenerated schema.rb is the Ruby-ecosystem equivalent of Prisma client regeneration.

package/substrate/standards/migration-discipline/alembic.md

@@ -0,0 +1,43 @@
+---
+tier: lite
+description: The Alembic sibling of .claude/rules/schema-management.md for adopters using Alembic without SQLAlchemy ORM models (raw SQL migrations against a Python codebase).
+---
+
+# Alembic (standalone) — migration discipline
+
+The Alembic sibling of `.claude/rules/schema-management.md` for adopters using Alembic **without** SQLAlchemy ORM models (raw SQL migrations against a Python codebase). Loads when adopter's `tech_stack.orm` is `alembic`.
+
+For Alembic + SQLAlchemy autogen, see `sqlalchemy.md`.
+
+## Non-negotiable rule
+
+**NEVER apply DDL outside an Alembic revision.** Direct `psql` / `mysql` / `sqlite3` DDL in production bypasses the migration audit trail.
+
+## Workflow
+
+1. Author a migration: `alembic revision -m "descriptive_name"` (no `--autogenerate` — you write the SQL by hand)
+2. Edit the generated file in `versions/` — populate `upgrade()` + `downgrade()` with `op.execute(text("..."))` or `op.create_table(...)` calls
+3. Apply locally: `alembic upgrade head`
+4. Test the downgrade path: `alembic downgrade -1`, then `alembic upgrade head`
+5. Commit the migration file
+6. On deploy, CI runs `alembic upgrade head`
+
+## After merging a branch with schema changes
+
+1. `alembic upgrade head` — apply pending migrations locally
+2. Verify DB shape matches expectations (Alembic doesn't model anything; the schema lives in DDL)
+
+## Drift check
+
+Alembic doesn't auto-detect drift in standalone mode. The session-start hook compares `alembic current` against the latest revision in `versions/`. If they diverge, prompt to upgrade.
+
+## Common pitfalls
+
+- **Writing migrations that read application data** — migrations should be idempotent and avoid coupling to app-side queries; data backfills go in separate scripts
+- **Skipping downgrade implementation** — rollback path is mandatory for prod-grade work
+- **Out-of-order revisions** — when parallel branches both create revisions from the same parent, merge with `alembic merge`
+
+## Sources
+
+- Alembic docs (https://alembic.sqlalchemy.org/en/latest/)
+- Standalone-Alembic discipline adapted from Prisma migration shape; the universal commitments are the same.

package/substrate/standards/migration-discipline/gorm.md

@@ -0,0 +1,50 @@
+---
+tier: lite
+description: The GORM (Go ORM) sibling of .claude/rules/schema-management.md.
+---
+
+# GORM — migration discipline
+
+The GORM (Go ORM) sibling of `.claude/rules/schema-management.md`. Loads when adopter's `tech_stack.orm` is `gorm`.
+
+## Non-negotiable rule
+
+**NEVER use `db.AutoMigrate()` in production.** AutoMigrate is a development convenience — in production, it silently makes additive schema changes without an audit trail and refuses to drop columns or constraints, leaving stale columns forever.
+
+Use an explicit migration tool — `golang-migrate`, `goose`, `atlas`, or `bun`'s migration layer.
+
+## Workflow (with `golang-migrate`)
+
+1. Edit the GORM model in `models/` (struct tags carry the schema intent)
+2. Author the migration: `migrate create -ext sql -dir db/migrations -seq descriptive_name`
+3. Populate `up.sql` and `down.sql` by hand — GORM doesn't generate SQL for you
+4. Apply locally: `migrate -path db/migrations -database "$DB_URL" up`
+5. Commit both the model change AND the migration files
+6. On deploy, CI runs `migrate -path db/migrations -database "$PROD_DB_URL" up`
+
+## After DB reset
+
+1. Re-run all pending migrations: `migrate up`
+2. Run seed scripts if any
+
+## After merging a branch with schema changes
+
+1. `migrate up` — apply pending migrations
+2. Restart the Go binary — GORM model definitions are compiled in; rebuild + restart
+3. Run integration tests against the new schema
+
+## Drift check
+
+`migrate version` reports the currently applied version. Compare against the highest numeric revision in `db/migrations/` directory. If they diverge, run `migrate up` before further work.
+
+## Common pitfalls
+
+- **GORM struct tags drifting from migration SQL** — GORM does not enforce them; the migration SQL is source of truth for the DB shape
+- **Postgres enum changes** — Postgres enums are quirky; `golang-migrate` requires custom SQL for ALTER TYPE ... ADD VALUE
+- **Forgetting `down.sql`** — rollback path is mandatory; an empty down.sql is a footgun
+
+## Sources
+
+- golang-migrate docs (https://github.com/golang-migrate/migrate)
+- GORM docs (https://gorm.io)
+- Go-ecosystem discipline ported from Prisma shape.

package/substrate/standards/migration-discipline/prisma.md

@@ -0,0 +1,53 @@
+---
+tier: lite
+description: The Prisma sibling of .claude/rules/schema-management.md.
+---
+
+# Prisma — migration discipline
+
+The Prisma sibling of `.claude/rules/schema-management.md`. Loads when adopter's `tech_stack.orm` is `prisma`. Preserves the operator's existing Prisma discipline verbatim.
+
+## Non-negotiable rule
+
+**NEVER use `prisma db push`. Always use `prisma migrate dev`.**
+
+`db push` applies changes without creating migration files — this causes schema drift where prod and local databases diverge silently. When the local DB is reset, unmigrated changes are lost, breaking functionality.
+
+## Workflow
+
+1. Edit `prisma/schema.prisma`
+2. Run `npx prisma migrate dev --name descriptive_name`
+3. This creates a migration file AND applies it locally
+4. Commit the migration file with the schema change
+5. On deploy, CI runs `npx prisma migrate deploy`
+
+## After DB reset
+
+- `npx prisma generate` — regenerate client
+- Run any seed scripts
+- Test auth by signing in
+
+## After merging a branch with schema changes (MUST — not optional)
+
+1. `npx prisma generate` — regenerate client from new schema
+2. Restart dev server — cached Prisma client won't pick up new models
+3. If DB was reset: run seed scripts for new entities
+4. Verify: new model is accessible via `prisma.[model].findMany()`
+5. If the merge includes new entities: seed test data (factories, not hardcoded — see `standards/data-management.md`)
+
+This is a **MUST gate**. Skipping `prisma generate` after a schema merge causes runtime crashes: `Cannot read properties of undefined (reading 'findMany')`. The Prisma client literally does not know the model exists.
+
+## Drift check
+
+The session-start hook checks for schema drift. If detected, create the missing migration before writing code.
+
+```bash
+npx prisma migrate status
+```
+
+A non-zero exit indicates pending migrations that have not been applied locally — drift signal.
+
+## Sources
+
+- This sibling is verbatim of the prior `.claude/rules/schema-management.md` content. Path A split (bassclef#1133 WU-5) preserves operator's discipline for the Prisma case.
+- POA (sole Prisma consumer in the sunj-labs portfolio as of 2026-06-18) reads this sibling unchanged.

package/substrate/standards/migration-discipline/sqlalchemy.md

@@ -0,0 +1,51 @@
+---
+tier: lite
+description: The SQLAlchemy sibling of .claude/rules/schema-management.md.
+---
+
+# SQLAlchemy + Alembic — migration discipline
+
+The SQLAlchemy sibling of `.claude/rules/schema-management.md`. Loads when adopter's `tech_stack.orm` is `sqlalchemy`. For standalone Alembic (non-SQLAlchemy use), see `alembic.md`.
+
+## Non-negotiable rule
+
+**NEVER edit production schema directly via `Base.metadata.create_all()` or DB-side DDL.** SQLAlchemy's autogenerate is the migration source; bypassing it ships drift.
+
+## Workflow (Alembic via SQLAlchemy autogen)
+
+1. Edit the SQLAlchemy model in `models.py` (or wherever the adopter keeps declarative bases)
+2. Generate the migration: `alembic revision --autogenerate -m "descriptive_name"`
+3. **Review the generated migration before committing** — autogen misses many cases:
+   - Server-side defaults (`server_default=`) are detected only with explicit `compare_server_default=True` in env.py
+   - Enum changes need manual handling on Postgres
+   - Index renames are usually drop+create (data loss risk)
+   - Custom types (JSONB, ARRAY) need explicit handling
+4. Apply locally: `alembic upgrade head`
+5. Commit the migration file with the model change
+6. On deploy, CI runs `alembic upgrade head` against prod
+
+## After merging a branch with schema changes (MUST — not optional)
+
+1. `alembic upgrade head` — apply pending migrations locally
+2. Restart dev server — SQLAlchemy ORM models reload from source, but DB session connections may cache stale schema metadata
+3. If DB was reset: re-run seed / fixture scripts
+
+## Drift check
+
+```bash
+alembic current
+alembic history --indicate-current
+```
+
+If `alembic check` (Alembic 1.9+) reports model-vs-DB divergence, generate the missing migration.
+
+## Common pitfalls
+
+- **Autogen comparing on outdated metadata** — make sure `target_metadata = Base.metadata` in `env.py` reflects the latest import path
+- **Multiple heads** after parallel branches — resolve via `alembic merge` before further development
+- **`alembic stamp head`** is a footgun — only use it when you know the DB is already at that state; otherwise you skip migrations silently
+
+## Sources
+
+- Alembic docs (https://alembic.sqlalchemy.org/en/latest/)
+- SQLAlchemy migration discipline ports the operator's Prisma rule shape to the Python ecosystem.