@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/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/substrate/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).

package/substrate/standards/persona-schema.md

@@ -0,0 +1,229 @@
+---
+tier: lite
+description: Bassclef schema for user personas in sunj-labs repos.
+---
+
+# Persona Schema
+
+Bassclef schema for user personas in sunj-labs repos. The contract the
+`/personas` skill reads and every downstream consumer (`/value-prop-canvas`,
+`/synthetic-user`, `/risk-test-synthetic`, `/user-stories`, `/jtbd-tasks`,
+`/spec`, `/prototype-variants`) composes against.
+
+Template: `templates/persona-template.md`.
+Skill: `.claude/skills/personas/SKILL.md`.
+
+## Why this standard exists
+
+Before this schema, persona shape was implicit and scattered:
+
+- `.claude/skills/jtbd-tasks/SKILL.md` Step 0 defined a "minimum viable
+  persona" with 5 fields (Age, Role, Device, Goal, Jargon comfort)
+- `.claude/skills/synthetic-user/SKILL.md` read personas from
+  `docs/design/personas/` with no schema validation
+- sunj-labs/quorum invented its own richer shape (Pichler + evidence-
+  traceability) for psychographic-mining output — not reflected anywhere
+  in bassclef
+
+Three consumers, three schemas, zero validation. Adding `/value-prop-canvas`
+and `/risk-test-synthetic` without standardizing would have made four.
+
+This standard consolidates around Pichler's template shape, adds evidence-
+traceability as a distinguishing rule, and preserves both prior path
+conventions for backward compat.
+
+## File convention
+
+### Preferred path
+
+`docs/personas/{slug}.md` — one file per persona.
+
+Filename basename MUST match the `slug` field in the file's body. The
+slug is URL-safe: lowercase, hyphens, no spaces.
+
+### Legacy path (accepted)
+
+`docs/design/personas/{slug}.md` — read by `/jtbd-tasks` and `/synthetic-user`
+before this standard existed. Still valid. Consumers read both paths,
+preferring `docs/personas/` when both exist.
+
+New repos SHOULD use `docs/personas/`. Existing repos MAY migrate or
+leave legacy files in place; consolidating bet may follow.
+
+## Required fields
+
+Every persona file MUST have:
+
+| Field | Shape | Example |
+|-------|-------|---------|
+| `slug` | URL-safe identifier, matches filename | `couple-founders` |
+| `name` | Human-readable display name (H1 satisfies) | `Couple Founders` |
+
+Absent any required field → `/personas validate` reports FAIL. Downstream
+skills SHOULD refuse to operate on invalid personas.
+
+The required set is intentionally minimal. `slug` + `name` is enough to
+reference a persona unambiguously; everything else is quality-of-output
+for downstream skills, not a load-bearing contract at the identity level.
+
+## Recommended fields (Pichler shape + outcome framing)
+
+High-value personas carry the full Pichler template plus an explicit
+goal line:
+
+| Field | Purpose |
+|-------|---------|
+| `goal` | One-line "what this persona is trying to accomplish" — verb-first, outcome-oriented |
+| `tasks` | Recurring tasks in pursuit of the goal |
+| `approach` | How they go about it (habits, tools, rhythm) |
+| `context` | Life / business / organizational grounding |
+| `knowledge` | Domain expertise, jargon comfort, technical fluency |
+| `biography` | Background, archetype, formative influences |
+
+Absence produces WARN (not FAIL) in validation. A persona with only the
+required fields is valid but thin — downstream skills will produce
+thinner outputs against it.
+
+**Goal inference fallback:** if a persona omits `goal` but has a
+`## JTBD statements` section, `/personas validate` prints an INFER line
+suggesting a goal derivable from the first JTBD. This is advisory, not
+auto-applied — the operator reviews and edits the file. The rationale:
+downstream skills like `/value-prop-canvas` and `/user-stories` need an
+unambiguous goal, and silent inference produces inconsistent results
+across consumers. Surface the gap once, let the operator resolve it, and
+every downstream read is consistent.
+
+## Evidence-traceability rule
+
+A persona that claims pain points, workflows, or behavior patterns MUST
+cite sources. Claims without source traces are **orphan claims** and
+surface as WARN in `/personas validate`.
+
+### Bassclef citation format
+
+```markdown
+### P1 — Concise pain label
+
+[Paragraph describing the pain.]
+
+> *Source trace: [source-N reference] — "[direct quote or close paraphrase]"*
+```
+
+Acceptable source types:
+
+- Repo-local research document (e.g., `docs/research/reddit-synthesis.md §3`)
+- External URL (articles, interviews, public forum posts)
+- Attributed interview note (`interview/YYYY-MM-DD-name.md §4`)
+- Analytics dashboard reference (product metric + timeframe)
+
+Not acceptable: "common knowledge," "I've seen this before," unattributed
+assertions, operator intuition.
+
+### Why this rule exists
+
+Personas without source traces fail silently. They look plausible, their
+synthesized behaviors read naturally, and downstream skills (VPC,
+synthetic-user) produce plausible-looking artifacts against them. The
+artifacts fail on contact with actual users because the foundational
+persona was a pattern-match on training priors, not evidence.
+
+Parallel to `.claude/rules/artifact-ingestion.md`: read before you
+produce. Cite before you claim.
+
+## Operator-default fallback
+
+Repos without persona files are common — new repos, internal tooling,
+early spikes. `/personas default` emits a minimal operator persona
+derived from:
+
+- `CLAUDE.md` (for goal / context)
+- `substrate.config.md` (for agents / deploy targets)
+- `docs/whereami.md` (for active iteration context)
+- Git `user.email` (for slug derivation)
+
+### When operator-default is appropriate
+
+- New repo; first iteration; no user research yet
+- Internal tooling where the operator IS the user
+- Spike / prototype sessions where user identity is deliberately deferred
+
+### When it's a red flag
+
+Operator-default leaking into these situations means the product is
+being validated against the operator's self-assessment, which is not
+user validation:
+
+- `/synthetic-user` running Tier 3 journeys against operator-default
+- `/value-prop-canvas` built from operator-default (value prop for
+  "you" tells you nothing about fit for real customers)
+- Iteration goal lovability/viability signals tied to operator-default
+
+`/personas validate` surfaces these with a note:
+"Only operator-default persona found; consider adding real personas
+before [downstream skill]."
+
+## Multiple personas — no compression
+
+If three real customer segments exist, three persona files exist. Do NOT
+collapse into a "composite customer" or "typical user" — compression
+loses the fit signal that `/value-prop-canvas` and `/risk-test-synthetic`
+depend on.
+
+VPC is 1:1 with persona. Risk-test matrices are persona × risk × artifact.
+A single merged persona flattens the matrix.
+
+## Validation checklist
+
+`/personas validate` walks every persona file under both bassclef and
+legacy paths and reports:
+
+- [ ] Required fields (slug, name) present — FAIL on absence
+- [ ] Slug matches filename basename — FAIL on mismatch
+- [ ] Pichler recommended fields (goal, tasks, approach, context, knowledge, biography) — WARN on absence
+  - If `goal` is absent but a `## JTBD statements` section exists, emit INFER line with suggested goal derived from first JTBD
+- [ ] Evidence traces present for behavior/pain claims — WARN on orphans
+- [ ] No duplicate slugs across files — FAIL on duplicate
+- [ ] File is readable markdown (parses without error) — FAIL otherwise
+
+Output format:
+
+```markdown
+## Persona validation
+
+**Files scanned**: N in docs/personas/, M in docs/design/personas/
+
+| File | Required | Pichler | Evidence | Slug-match | Status |
+|------|----------|---------|----------|-----------|--------|
+| [file] | ✅/❌ | ✅/⚠️ | ✅/⚠️ | ✅/❌ | PASS/WARN/FAIL |
+
+**Pass**: N | **Warn**: M | **Fail**: K
+```
+
+## Relationship to other standards
+
+| Standard / rule | Connection |
+|-----------------|-----------|
+| `.claude/rules/artifact-ingestion.md` | Evidence-traceability is artifact-ingestion applied to personas specifically |
+| `standards/whereami-schema.md` | Same "schema + template + skill + rule" pattern; different domain |
+| `standards/substrate-config-schema.md` | Operator-default fallback reads substrate.config fields |
+| `.claude/skills/jtbd-tasks/SKILL.md` | Step 0 "minimum viable persona" is a subset view of this schema; valid but thin |
+| `.claude/skills/synthetic-user/SKILL.md` | Existing consumer; reads legacy path; continues to work |
+
+## Future evolution
+
+When `/psychographic-mine` (quorum #54) and `/auto-user-research`
+(quorum #53) promote to bassclef, they produce files conforming to
+this schema with High evidence-quality ratings by construction.
+
+When `/jtbd-tasks` consolidates its Step 0 to delegate to `/personas
+default` or `/personas get`, the "minimum viable persona" variant
+becomes a template preset rather than a parallel shape.
+
+Neither consolidation happens in this bet's scope — both deferred to
+follow-up iterations so this standard ships with a stable contract
+first.
+
+## Closes
+
+- bassclef #200 (companion to quorum #50)
+- Part of iteration `docs/iteration-bets/2026-04-19e-persona-vpc-promotions.md` Stack-1