@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/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/dist/lite/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/dist/lite/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.

package/dist/lite/standards/mobile-ephemeral-session.md

@@ -0,0 +1,167 @@
+---
+tier: lite
+description: Autonomous sessions running in ephemeral environments — claude.ai/code mobile sandbox, CI runners executing agentic work, temporary dev containers — have different state-continuity constraints than desktop sessions.
+---
+
+# Mobile / Ephemeral Session Standard
+
+Autonomous sessions running in ephemeral environments — claude.ai/code
+mobile sandbox, CI runners executing agentic work, temporary dev
+containers — have different state-continuity constraints than desktop
+sessions. This standard defines what must be true for ephemeral
+sessions to produce reviewable, recoverable work.
+
+## The core constraint
+
+Ephemeral sandbox state is destroyed when the session ends. Any
+artifact not committed AND pushed before exit is lost.
+
+This is different from desktop: desktop auto-save commits locally and
+pushes "when convenient." Ephemeral has no "later" — exit is terminal.
+
+## Detection
+
+**Primary (required for certainty)**: operator sets `CLAUDE_EPHEMERAL=1`
+as the first command in the session. No heuristics beat explicit
+opt-in.
+
+**Fallback heuristics** (if operator doesn't set the flag):
+- `pwd` doesn't start with `/Users/`
+- `hostname` doesn't match known machines
+- `$HOME` isn't the operator's real home
+- Tailscale CLI not installed at `/Applications/Tailscale.app/Contents/MacOS/Tailscale`
+- Fresh-clone reflog (very short history)
+
+≥2 heuristics firing → treat as ephemeral with surfaced warning.
+Single heuristic → surface but don't switch modes automatically.
+
+**Refine over time**: after the first few mobile sessions, update
+these heuristics based on actual claude.ai/code sandbox environment.
+
+## Rules (MUST)
+
+### 1. All session artifacts round-trip through git
+
+Chronicles, handoff docs, state files, diagnosis output, decomposition
+artifacts — everything MUST be committed AND pushed before the session
+naturally or unnaturally ends. Auto-save hooks in ephemeral mode must
+`git push` after every commit, not batch-push at exit.
+
+### 2. No filesystem-only markers
+
+Desktop hooks use `/tmp/claude-verify-[branch]` and similar markers.
+These are lost on sandbox death. Every filesystem marker MUST have a
+git-tracked equivalent that the hook also writes and reads. When
+running in ephemeral mode, the git-tracked form is authoritative.
+
+| Desktop | Ephemeral-compatible |
+|---------|---------------------|
+| `/tmp/claude-verify-[branch]` | `state/markers/verify/[branch]` (git-tracked, committed by /verify) |
+| Session lock at `.claude/SESSION_LOCK` | Same, but with ISO timestamp + TTL — stale locks auto-clear with ≥30min age |
+| Iteration state in `.claude/iteration-state` | Committed to repo, not gitignored |
+| Agent memory at `~/.claude/projects/...` | Either: (a) commit a memory export to `memory/` in repo, OR (b) accept per-session memory loss, rely on chronicles as context substitute |
+
+### 3. Auto-save pushes every commit
+
+Hook must:
+- Detect ephemeral mode (env var, hostname pattern, or explicit flag)
+- After each auto-save commit, invoke `git push origin HEAD` with
+  reasonable backoff on failure
+- Coalesce commits within the last 10 min to avoid thrashing git
+  history
+- If push fails (network, auth, conflict): retry once, then log
+  failure visibly — operator sees it in session output
+
+### 4. Session-lock TTL + ephemeral-safe
+
+Session locks must be:
+- Timestamp-bearing (ISO 8601 in UTC)
+- Stale-clearable (locks ≥30 min old are cleared with an announcement)
+- Git-committed if ephemeral (lives in the repo so other sessions
+  can see it)
+
+Stale-lock clearing rule: agent reads lock file, checks timestamp, if
+age > TTL, clears lock and announces in session output. No polling;
+one-shot check at session start.
+
+### 5. No credential-bearing tools in ephemeral
+
+Ephemeral sessions MUST NOT carry long-lived credentials:
+- No SSH keys for prod/staging boxes
+- No AWS access keys
+- No Tailscale auth tokens
+- No long-lived PATs (use fine-grained PATs with short TTL or
+  GitHub App installation tokens only)
+
+Agents in ephemeral sessions work at the git layer — clone, branch,
+commit, push, open PR. Deploy work happens in CI after PR merge,
+never from the ephemeral sandbox directly.
+
+### 6. Session-end rigor is absolute
+
+Ephemeral sessions MUST invoke `/session-end` explicitly before exit.
+Stop hook may not fire; operator may close the tab; sandbox may time
+out. Relying on shutdown hooks is the failure mode. Explicit
+session-end at natural stopping points is the rule.
+
+Session-end in ephemeral mode:
+1. Write chronicle (commit + push)
+2. Update whereami if changed (commit + push)
+3. Write any LinkedIn drafts (commit + push)
+4. Confirm working tree clean
+5. Confirm HEAD matches origin
+6. Exit only after verification
+
+## Rules (SHOULD)
+
+### 7. Recent-chronicle read at session start
+
+If project memory isn't available (no MCP memory server, no memory
+repo), read the last 2-3 chronicles at session start as context
+substitute. Substantial enough to recover current iteration state,
+open threads, and recent decisions.
+
+### 8. Conservative auto-mode in ephemeral
+
+Ephemeral sessions default to operator-gated even if orchestrator-
+gated was requested. The ephemeral constraint adds risk that deserves
+confirmation at decision points. Override with explicit
+`orchestrator-gated --ephemeral-ok` flag.
+
+### 9. Recipe for "hello world" mobile session
+
+First mobile session on any repo should be trivial: chronicle edit,
+doc fix, skill tweak, README update. Not a feature build. Validates
+the end-to-end loop (auth → clone → edit → commit → push → PR)
+before testing anything complex.
+
+## Rationale
+
+Mobile autonomous is valuable because it compresses the feedback
+loop for idea-to-artifact work (operator has an insight on phone;
+captures it via agent; agent produces artifact; operator reviews on
+desktop). The tax is state continuity — easy to lose work to
+sandbox death.
+
+The rules here make state continuity a build-time property of the
+substrate, not a run-time discipline the operator has to remember.
+Every hook, every skill, every rule that already exists keeps working
+as long as it respects these constraints.
+
+## Relationship to other standards
+
+- `standards/substrate-config-schema.md` — no secrets in
+  substrate.config.md (already required); ephemeral just makes
+  this more critical
+- `standards/deployment-topology.md` — deploy work happens in CI
+  post-PR, never from ephemeral session
+- `.claude/rules/blocked-items.md` — BLOCKED: protocol continues to
+  work in ephemeral; silence is not deferral in either mode
+
+## Enforcement
+
+Hook layer enforces what it can (auto-save push, marker git-tracking,
+session lock TTL). Agent behavior enforces the rest (explicit
+session-end, no credential tools, conservative auto-mode).
+Self-test skill could validate hook configuration when run in
+ephemeral mode.

package/dist/lite/standards/model-routing-discipline.md

@@ -0,0 +1,160 @@
+---
+tier: lite
+description: - ADR-021 — anchor catalog selection (cameo engine model context, now operator-internal) - bassclef#853 Sub-bet 16 + Sub-bet 19 — model routing substrate primitive - bassclef#944 — Voyage matcher excision (operator-internal pinning moved to…
+---
+
+# Model routing discipline
+
+## Sources read
+
+- ADR-021 — anchor catalog selection (cameo engine model context, now operator-internal)
+- bassclef#853 Sub-bet 16 + Sub-bet 19 — model routing substrate primitive
+- bassclef#944 — Voyage matcher excision (operator-internal pinning moved to bassclef-upstream)
+- `.claude/agents/*.md` existing tier declarations (Opus / Sonnet / Haiku across 13 agents)
+- Operator spec: provider-agnostic routing supporting 10+ providers
+
+## What this is
+
+Model routing is how bassclef's agents, skills, and subagents pick which LLM to call at dispatch time. The substrate names four capability tiers — `cheap-fast`, `balanced`, `capable`, `embedding`. Each provider maps its concrete models to those tiers in `config/model-routing.yaml`.
+
+Agents declare a tier in frontmatter. Skills can override per invocation. The substrate resolves the concrete model at dispatch time from the active provider + tier mapping.
+
+## Why this exists
+
+Three problems the old shape didn't solve:
+
+1. Agent frontmatter pinned vendor-specific model IDs (`claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`). Switching providers meant editing every agent file.
+2. Adopters using OpenAI, Gemini, Bedrock, etc. couldn't reuse bassclef's agent definitions without rewriting model declarations.
+3. Per-skill or per-call model selection had no clean override path. Operator env vars worked but weren't documented.
+
+This primitive fixes all three: agents declare a tier, not a vendor. Adopters edit `config/model-routing.yaml` to pick their provider. Per-invocation overrides cascade through a clear precedence stack.
+
+## The four capability tiers
+
+| Tier | When to use |
+|---|---|
+| **cheap-fast** | High-frequency, low-complexity, structured output. Checklist eval, file navigation, simple extraction, automation, runbook execution. |
+| **balanced** | Default for most agents. Code edits, planning, analysis, design, strategic reasoning. |
+| **capable** | High-complexity reasoning, architectural decisions, problem framing, synthesis across many docs. |
+| **embedding** | Vector embeddings for retrieval (semantic search, anchor matching). Not a chat model. |
+
+Tiers describe capability, not vendor. The same tier maps to different concrete models per provider.
+
+### Tiers are vocabulary, not benchmark
+
+The four tier names describe **intent**, not measured cross-provider equivalence. A `capable` model on one provider is not strictly equal to a `capable` model on another — output quality, latency, cost, and context window all vary. The tier abstraction picks the right shape of model for a workload; adopters validate the concrete mapping against their own workloads before pinning a provider.
+
+INSTEAD of treating tiers as benchmark guarantees: read them as design intent. "Use capable" means "this work needs the strongest reasoning the provider ships." Whether that's Claude Opus, GPT-o1, Gemini 2.0 Pro, or Mistral Large 2 depends on the provider's roadmap — and on what the adopter measures against their own jobs.
+
+This framing prevents the cross-provider semantic-equivalence misread: tiers are a coordination mechanism, not a quality contract.
+
+## How to declare
+
+### In an agent definition
+
+```yaml
+---
+name: Closer
+model_tier: cheap-fast
+description: Administrative gate evaluation; checklists; retros.
+---
+```
+
+### In a skill (optional per-call override)
+
+```yaml
+---
+name: example-skill
+model_tier: capable  # overrides invoking agent's tier
+---
+```
+
+### In substrate.config.md (per-repo provider default)
+
+```markdown
+## Model routing
+
+# Default provider for this repo. Tier-to-model mapping comes from
+# bassclef's config/model-routing.yaml unless overridden here.
+model_provider: anthropic
+```
+
+## Override precedence
+
+When resolving a model at dispatch, the substrate walks this stack from highest to lowest priority:
+
+| Priority | Source | Notes |
+|---|---|---|
+| 1 | `CLAUDE_MODEL_OVERRIDE` env var | Direct vendor model ID; bypasses tier resolution |
+| 2 | Per-invocation flag (skill arg) | `--model gpt-4o` style override |
+| 3 | Skill-level `model_tier:` declaration | Skill frontmatter |
+| 4 | Agent-level `model_tier:` declaration | Agent frontmatter |
+| 5 | Per-repo `model_provider:` in substrate.config.md | Repo default; pairs with tier above |
+| 6 | Substrate default in `config/model-routing.yaml` | `default_provider:` field |
+
+INSTEAD of hardcoding vendor model IDs in agent definitions: declare a tier; let the resolution stack pick the concrete model. The override path stays open at every layer for genuine reasons (vendor pinning, per-call experimentation, operator emergency override).
+
+## How adopters extend
+
+Adopters use any LLM provider — Anthropic, OpenAI, Google Gemini, AWS Bedrock, Azure OpenAI, Mistral, Cohere, DeepSeek, xAI, local LLaMA, or any future provider.
+
+To add a new provider:
+
+1. Edit `config/model-routing.yaml`. Add a provider block under `providers:` with tier mappings.
+2. Set `default_provider:` to the new provider (or leave the default and set per-repo).
+3. The agents work unchanged.
+
+No agent edits. No skill edits. The tier abstraction does the work.
+
+## What the substrate ships
+
+`config/model-routing.yaml` ships defaults for ten providers:
+
+- **Anthropic** — Claude family (Opus 4.7, Sonnet 4.6, Haiku 4.5)
+- **OpenAI** — GPT family
+- **Google Gemini** — Gemini family
+- **AWS Bedrock** — Bedrock-hosted Anthropic models
+- **Azure OpenAI** — Azure-hosted GPT
+- **Mistral** — Mistral family
+- **Cohere** — Command family + embed models
+- **DeepSeek** — DeepSeek-V3 / DeepSeek-Coder
+- **xAI** — Grok family
+- **local-llama** — Self-hosted Llama 3
+
+The defaults are starting points. Operator can pin specific versions, swap models within a tier, or add new providers via config edit.
+
+## How adopter-internal primitives reference this
+
+Operator-internal pinning decisions (anchor catalog model choices, embedding-vendor selection) stay in `bassclef-upstream/docs/operator-private/adrs/` per Tier 1 substrate. The pins reference this routing primitive: operator-internal substrate calls `state_routing_resolve(tier='embedding', purpose='<purpose>')` which reads the operator-internal config to pick the concrete embedding model.
+
+Adopters don't need the operator-internal pinning decisions. The substrate primitive gives them the tier abstraction; their config picks the concrete model.
+
+## What this primitive does NOT do
+
+- Does not choose a tier for you. Agent definitions declare the tier.
+- Does not call the LLM. The harness does that with the resolved model ID.
+- Does not handle rate limits, retries, or fallbacks. Those are runtime concerns (separate primitive — see bassclef#853 Sub-bet 20 parallel-dispatch ceiling).
+- Does not move secrets. Provider API keys live in `substrate.secrets.md` per `standards/secrets-lifecycle.md`. This primitive only routes between providers; the secrets layer authenticates each call.
+
+## Composes with
+
+- ADR-021 — anchor catalog selection (operator-internal; references this primitive)
+- ADR-023 — dependency-aware pre-flight dispatch (Sub-bet 13)
+- ADR-025 — atomic write-claim (Sub-bet 9)
+- bassclef#853 Sub-bet 17 — subagent isolation (different concern; both fire pre-dispatch)
+- bassclef#853 Sub-bet 18 — session marker handoff (different concern; both fire pre-dispatch)
+- bassclef#853 Sub-bet 20 — parallel-dispatch ceiling (caps concurrent agents per plan capacity)
+- `standards/vendor-bindings.md` — this primitive is the SENTINEL_bassclef_answer to "how do we stay portable across LLM vendors"
+- `standards/secrets-lifecycle.md` — provider API keys live there
+
+## Override path
+
+`SKIP_MODEL_ROUTING=1 <command>` — bypasses tier resolution entirely. Logged via trace-helper. Use only when debugging a routing bug or when a one-off vendor model is needed for a specific call that isn't worth a permanent config entry.
+
+## Retirement condition
+
+This primitive retires only if the harness ships a built-in tier abstraction that supersedes it. Until then, this discipline holds across all bassclef-substrate agents + skills + subagents.
+
+## Closes
+
+bassclef#853 Sub-bet 16 (model routing substrate primitive) + Sub-bet 19 (provider-agnostic extension across 10+ providers).