@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/standards/state-spine-contract.md

@@ -0,0 +1,255 @@
+---
+tier: lite
+description: "The interface contract for lib/state.sh — the typed accessor library over bassclef's state spine."
+---
+
+# State Spine Accessor Contract
+
+The interface contract for `lib/state.sh` — the typed accessor library
+over bassclef's state spine. Repository pattern (Fowler PoEAA): hides
+storage backend (JSON-on-git for v0; cxdb for opt-in adopters per
+bassclef#300) from consumers via a stable accessor surface.
+
+This standard is the contract. The implementation is `lib/state.sh`.
+Adapter discipline (per canvas Stage 3 §"Adapter discipline") preserves
+the swap surface — when cxdb adoption ships, the implementation changes
+but this contract does not.
+
+## Sources read
+
+- `docs/iteration-bets/2026-04-27-state-spine-v0.md` §"WU-2 Typed accessor library" — procedure + acceptance
+- `strategy/canvases/2026-04-26-state-spine.md` v4 — accessor discipline (replay-determinism); pattern-set (Repository/Facade); cxdb-adapter exit criteria
+- `architecture/decisions/ADR-015-state-schema-format.md` — JSON Schema only for v0 (no Zod runtime)
+- `standards/state-spine.md` — entity catalog (17 v0 + Persona); storage shapes (3 — A/B/C); replay-determinism rule; write-once-immutability rule
+- All 18 v0 entity schemas in `standards/state-spine/schemas/` — define what each accessor returns
+- `.claude/luminaries/martin-fowler.md` — Repository pattern + Strangler Fig
+- `.claude/rules/diagnosis.md` — error-shape conventions (return non-zero + stderr message; never silent failure)
+
+## What I'm NOT reading (with reason)
+
+- cxdb / Dolt vendor docs — out of v0 scope (Track B)
+- `extract-session-telemetry.sh` line-by-line — WU-5's pre-read; this contract defines the surface telemetry will consume, not telemetry itself
+
+## Naming convention
+
+```
+state_<entity>_<verb>[_<modifier>]
+```
+
+- **entity** — kebab-case entity name from state-spine.md (e.g., `whereami`, `iteration_bet`, `deferred_action`, `chronicle`, `marker`)
+- **verb** — operation (bassclef set below)
+- **modifier** — optional qualifier for special-purpose accessors
+
+Examples:
+- `state_whereami_get` — get the singleton
+- `state_iteration_bet_list` — list all bets
+- `state_marker_count` — count markers (with optional filter args)
+- `state_chronicle_gate_evidence` — special-purpose: extract gates_fired from a chronicle
+- `state_deferred_action_pending` — special-purpose: list pending actions matching capabilities
+
+## Verb vocabulary
+
+Stable set. Extend via this contract (with a paired schema-side rationale).
+
+| Verb | Semantics | Allowed for |
+|---|---|---|
+| `get` | Single entity by id; returns JSON to stdout, 1 to stderr if not found | All entities |
+| `list` | Collection (optional filter args); returns JSON array to stdout (empty array `[]` if none) | All entities |
+| `count` | Counter (optional filter args); returns integer to stdout | All entities |
+| `add` | Append a new entity; takes JSON on stdin, writes file, returns id to stdout | Write-many entities (Marker, Chronicle, Decomposition, InputArtifact, Session, Gate, InboxWorkItem, TemplateInstance, DeferredAction) |
+| `set` | Update field on singleton; takes field + value, validates against schema, writes | Singletons only (Whereami, SubstrateConfig, PreviewState, BassclefPlatform) |
+| `update_status` | Change status field; validates new value against entity's status enum | Mutable-status entities (IterationBet, Step, InboxWorkItem, DeferredAction) |
+| `render` | Generate operator-readable markdown from JSON authoritative source | Singletons (Whereami, SubstrateConfig, PreviewState) |
+
+Forbidden verbs: any mutation on Markers, Chronicles, Discoveries,
+Sessions (write-once-immutable per Helland — see canvas §"Accessor
+discipline"). Updates produce NEW records; readers consider the latest
+non-superseded record per business-key.
+
+## Return semantics
+
+| Outcome | Stdout | Stderr | Exit code |
+|---|---|---|---|
+| Success (single entity) | JSON object | (empty) | 0 |
+| Success (list) | JSON array (possibly empty) | (empty) | 0 |
+| Success (count) | integer | (empty) | 0 |
+| Success (add) | new id | (empty) | 0 |
+| Not found | (empty) | (empty) | 1 |
+| Invalid input | (empty) | error message | 2 |
+| Schema validation failed | (empty) | jq/ajv error | 3 |
+| File system error | (empty) | error message | 4 |
+| Unsupported entity / verb | (empty) | error message | 5 |
+
+Consumers check exit code; non-zero is failure. Never silent — error
+messages always go to stderr per `.claude/rules/diagnosis.md`
+("Step 0 — Reproduce" requires the failure to surface).
+
+## Replay-determinism rule (canvas v4 SWF mining)
+
+Counters and computed state derived from history on every call. **Never
+cache derived values as side state.**
+
+Concretely:
+- `state_marker_count [category] [since-N-sessions]` reads the Marker
+  collection + computes; no `latest_count` field stored anywhere
+- `state_chronicle_gate_evidence <id>` derives from session's marker
+  history at chronicle write time, not maintained out-of-band
+- `state_whereami_recompute` regenerates the Whereami singleton from
+  collection state; the JSON sidecar at `docs/whereami.json` is a
+  cache, not authority
+
+This is the bassclef analog of SWF's "decider must be idempotent on
+replay." Same input history → same output, deterministically. Failing
+at this is what produced bassclef#296 (compliance counter floor-lift).
+
+## Write-once-immutability rule (Helland)
+
+Markers, Chronicles, Discoveries, Sessions are write-once. Once
+committed:
+- Filename never changes (UUID for Markers; ID-based for others)
+- Body content never changes
+- Updates produce NEW records that supersede the prior (via
+  `supersedes` field per the Marker schema)
+
+Accessors that mutate (`add`) write atomic — file lands or fails. No
+partial writes. Use temp-file + rename pattern.
+
+Accessors that don't mutate (`get`, `list`, `count`, `update_status`)
+operate on whatever's on disk; consumers responsible for any
+serializability they need (out of v0 scope; cxdb upgrade addresses for
+concurrent fanout).
+
+## Storage-shape extraction (per state-spine.md §"Storage format")
+
+The accessor handles all three on-disk shapes via entity-type-aware
+extraction:
+
+### Shape A entities (singleton JSON authoritative + markdown rendered)
+
+```bash
+state_whereami_get() { cat docs/whereami.json; }
+state_whereami_set <field> <value>  # jq update + atomic rename
+state_whereami_render               # JSON → markdown (with auto-generated banner)
+```
+
+### Shape B entities (markdown + YAML frontmatter + body)
+
+```bash
+state_iteration_bet_get <slug> {
+  # Extract YAML frontmatter, convert to JSON
+  awk '/^---$/{c++; next} c==1' docs/iteration-bets/$slug.md | yq2json
+}
+```
+
+`yq2json` is implemented as `python3 -c "import sys,yaml,json; print(json.dumps(yaml.safe_load(sys.stdin), default=str))"` (yaml + json stdlib, available everywhere).
+
+### Shape C entities (pure JSON)
+
+```bash
+state_marker_get <uuid> {
+  # Find by UUID across category dirs
+  find state/markers -name "${uuid}.json" -type f -print -quit | xargs cat
+}
+```
+
+### Shape D entities (pure YAML at sibling-repo root) — added bassclef#462
+
+```bash
+state_platform_get [dot.path.key] {
+  # Resolves file via BASSCLEF_PLATFORM_CONFIG_PATH env or default
+  # ~/src/sunj-labs/platform-config/bassclef-platform.yml; converts
+  # YAML to JSON; if a key is given, jq-walks the path.
+  python3 -c "import yaml,json; print(json.dumps(yaml.safe_load(open('$path'))))" \
+    | jq -r --arg key "$key" 'getpath($key | split("."))'
+}
+state_platform_path  # returns the resolved file path (no read)
+```
+
+## Special-purpose accessors (v0 hot-path consumers)
+
+Beyond generic verbs, the following exist for known v0 consumers:
+
+| Accessor | Returns | Consumer |
+|---|---|---|
+| `state_marker_count [category] [since-days]` | int | `extract-session-telemetry.sh` (WU-5); `40-gate-compliance.sh` (WU-6). v0 since-days = mtime-based; v1 will redefine as session-boundary-mapped per canvas v4 SWF mining. Accepts both `.json` (spine) and `.marker` (legacy verify-markers) extensions. |
+| `state_chronicle_list [--recent N]` | newline-separated chronicle IDs (lex order) | `extract-session-telemetry.sh` (WU-5); `/sprint`, `/chronicle` (WU-7). Tries `chronicle/` then `docs/chronicle/`. |
+| `state_chronicle_gate_evidence <id>` | JSON of `gates_fired` frontmatter array | `extract-session-telemetry.sh` (WU-5) — frontmatter-only. Legacy chronicles with body-table Gate Evidence return `[]`; consumers may parse markdown body directly per `accessor-library-discipline.md` §"What this rule allows". |
+| `state_session_recent <N>` | JSON array of recent N sessions | `/sprint`, `/chronicle` (WU-7) |
+| `state_step_for_branch <branch-name>` | JSON of Step | status checks; `/longrun checkpoint` |
+| `state_deferred_action_pending [requires-capability...]` | JSON array of resolvable entries (capability-filtered) | `60-deferred-actions.sh` (WU-6) |
+| `state_deferred_action_list [pending\|completed\|all]` | JSON array of all entries in scope (no capability filter) | `/state` skill (WU-8); ad-hoc inspection |
+| `state_iteration_bet_active` | JSON of currently-active bet (or empty if none) | `/sprint` (WU-7) |
+| `state_iteration_bet_list` | JSON array of all bets (lexicographic order) | `/state` skill (WU-8) |
+| `state_reference_get <type> <id>` | JSON of referenced entity (resolves typed cross-refs) | validator (WU-3); render (WU-7) |
+| `state_reference_check <type> <id>` | exit 0 if exists, 1 if dangling | validator (WU-3) |
+| `state_validate <path>` | empty stdout on success; BLOCK message on stderr if schema violation | `/state` skill (WU-8); ad-hoc operator validation |
+| `state_roadmap_get <slug>` | JSON of roadmap frontmatter | `/sprint`, `/longrun` first-turn orientation (bassclef#337 WU-4) |
+| `state_roadmap_next_pending <slug>` | JSON of next claimable WU (depends_on satisfied + status=pending) | claim_wu's default arg path |
+| `state_platform_get [dot.path]` | JSON object (whole file) or scalar (when dot-path given) | `/provision-deploy-host` (bassclef#457), `/secrets-bootstrap` (bassclef#461), `/scaffold-stack` (bassclef#460), `/bind-subdomain` (existing — V2 reads zone via this rather than per-repo substrate.config); reads sibling-repo `bassclef-platform.yml` |
+| `state_platform_path` | filesystem path string | tooling that displays where state_platform_get reads from without reading |
+| `state_roadmap_claim_wu <slug> [wu-slug] [session-id]` | JSON of claimed WU; advances `last_event` with `task-claimed` (bassclef#349 tail-1) | distributed agent coordination — atomic claim via flock |
+| `state_roadmap_release_wu <slug> <wu-slug> [event] [refs-json]` | JSON of new `last_event`; advances `last_event` with completion | distributed agent coordination — completion |
+| `state_roadmap_abandon_wu <slug> <wu-slug> [reason] [--terminal]` | JSON of new `last_event`; advances `last_event` with `task-abandoned` (bassclef#349 tail-2) | scope-change exit path; default returns to pending, `--terminal` marks abandoned |
+| `state_roadmap_add_task <slug> <wu-slug> <issue> <wu-id> <title> [depends_on-json]` | JSON of new task; advances `last_event` with `task-added` (bassclef#349 tail-3) | proper accessor entry point for populating roadmap task list — replaces hand-edits per `accessor-library-discipline.md` |
+
+## Adapter discipline — preserved swap surface
+
+Per canvas Stage 3 §"Adapter discipline" (7 exit criteria):
+
+1. **Accessor library is the ONLY consumer of storage backend APIs.**
+   No skill/hook/rule/script invokes `cat docs/whereami.json` directly
+   when an accessor exists. Enforced via `accessor-library-discipline.md`
+   rule (paired with this contract; ships in same PR as `lib/state.sh`).
+2. **Accessor surface exposes only operations expressible in BOTH
+   backends** (JSON-on-git AND cxdb). No JSON-on-git-specific features
+   (e.g., `find`-based glob queries, jq paths in public surface) leak
+   into the contract. cxdb-adopter would re-implement these accessors
+   against Turn DAG + Blob CAS; surface stays unchanged.
+3. **JSON spine remains writable from cxdb.** When cxdb adoption ships,
+   `state_marker_add` etc. continue to write JSON files (cxdb is a
+   read-side projection); JSON files in git are still authoritative.
+4. **Contract is schema-first, not implementation-first.** Entity
+   definitions live in `standards/state-spine/schemas/`. cxdb's Type
+   Registry would be loaded FROM bassclef's schema, not derived.
+5. **A working cxdb fork is maintained** when adopted. (Out of v0 scope.)
+6. **Migration tooling (cxdb → Dolt) is designable from the entity
+   model.** (Out of v0 scope; ADR bassclef#300 placeholder.)
+7. **Dolt-as-fallback design is sketched in the cxdb ADR.** (Out of
+   v0 scope.)
+
+For v0: criteria 1-4 apply now. They constrain `lib/state.sh` design
+even though only criterion 1 is enforceable in v0 (the rule).
+
+## Test coverage requirement
+
+≥95% test coverage on `lib/state.sh` per step-2 acceptance. Test scaffold
+at `scripts/tests/state.test.sh` per existing bassclef bash-test
+pattern (`scripts/tests/bind-subdomain.test.sh`).
+
+Each accessor has at minimum:
+- Happy path (successful return)
+- Not-found path (exit 1, empty stdout)
+- Invalid-input path (exit 2, stderr message)
+- Schema-validation path where applicable (exit 3)
+
+## Versioning
+
+Accessor surface versioned via this standard. Breaking changes
+(removing accessors, changing return shapes, changing exit codes) are
+v1 changes — ship as `state_v1.sh` alongside `state.sh` during
+deprecation window per Fowler expand-and-contract.
+
+Adding new accessors is non-breaking; can land in v0 patches.
+
+## Relationship to other standards
+
+- `standards/state-spine.md` — entity catalog + storage shapes; this
+  contract operates on
+- `standards/branch-stacking.md` — Stack entity uses retarget protocol;
+  WU-2 PR will need this on merge
+- `.claude/rules/state-schema-validation.md` (paired with WU-3) — write-time
+  validation; this contract's `add`/`set`/`update_status` accessors invoke
+  the validator before writing
+- `.claude/rules/accessor-library-discipline.md` (paired with this
+  standard) — enforces "no skill/hook/rule reads state directly; all
+  access goes through `lib/state.sh`"

package/substrate/standards/steering-hints/kiss-words.md

@@ -0,0 +1,11 @@
+---
+tier: lite
+hint_id: kiss-words
+priority: high
+boundaries: [prompt-submit, skill-end, state-write]
+token_budget: 50
+refresh_interval_turns: 5
+description: Write at grade 8. Cap grade 10. Short sentences. Subject-verb-object. Drop bassclef-only words per standards/bassclef-internal-jargon.md. Keep standard tech words (API, hook, PR, schema).
+---
+
+Write at grade 8. Cap grade 10. Short sentences. Subject-verb-object. Drop bassclef-only words per standards/bassclef-internal-jargon.md. Keep standard tech words (API, hook, PR, schema).

package/substrate/standards/substrate-config-schema.md

@@ -0,0 +1,267 @@
+---
+tier: lite
+description: substrate.config.md is the single source of truth for external resource references in any bassclef-substrate repo.
+---
+
+# Substrate Config Schema
+
+`substrate.config.md` is the **single source of truth** for external
+resource references in any bassclef-substrate repo. Functionally, it
+is to bassclef what `.env` is to runtime code — the one place agents
+look for "where is X" without guessing, without consulting memory, and
+without hardcoding.
+
+## Why this exists
+
+Before this standard: resource references lived in three places —
+`substrate.config.md`, project memory, and hardcoded in skills. Agents
+had to check all three, confused them routinely, and produced wrong
+pushes (drafts pushed to corpus doc, etc.).
+
+Single-source-of-truth eliminates the ambiguity. Skills read only from
+`substrate.config.md`. Memory references resources only by field name,
+never by raw ID.
+
+## Typed suffix convention
+
+Every resource field in `substrate.config.md` uses a typed suffix so
+the agent never has to interpret the value:
+
+| Suffix | Meaning | Examples |
+|--------|---------|----------|
+| `*_doc_id` | Google Doc ID (a string that goes after `/document/d/`) | `journal_doc_id`, `changelog_doc_id`, `brand_corpus_doc_id` |
+| `*_sheet_id` | Google Sheets ID | `metrics_sheet_id` |
+| `*_url` | Full URL (http/https) | `staging_url`, `grafana_url`, `langfuse_url` |
+| `*_host` | Host without scheme | `db_host`, `redis_host` |
+| `*_repo` | GitHub repo reference (`owner/name`) | `parent_repo`, `deploy_repo` |
+| `*_repos` | Comma-separated list of GitHub repo references | `bassclef_evolution_child_repos` |
+| `*_path` | Filesystem path (absolute preferred) | `shared_artifacts_path` |
+| `*_channel_id` | Slack/Discord channel | `alerts_channel_id` |
+| `*_project_id` | Linear/Jira/Asana project | `linear_project_id` |
+| `*_token_name` | **Name of env var** holding a secret (never the secret itself) | `gh_token_name`, `anthropic_key_name` |
+| `*_reviewers` | GitHub usernames (comma-separated) for approval gates | `prod_approval_reviewers` |
+| `*_topology` | Architectural choice per `deployment-topology.md` | `staging_topology` |
+
+**Secrets NEVER in `substrate.config.md`.** That file is committed to
+git. Secrets live in `.env` (gitignored) or a secret manager. The
+convention stores the *name* of the env var (e.g.,
+`gh_token_name: GH_TOKEN`) so agents know which variable to read at
+runtime.
+
+**Secret lifecycle is tracked separately** in `substrate.secrets.md`
+(schema: `standards/state-spine/schemas/substrate-secrets.schema.json`;
+purpose: `standards/secrets-lifecycle.md`). That file holds rotation
+cadence, expiry dates, runbook paths, and health-check commands —
+references and metadata only, never values. The two files cross-reference
+each other; `substrate.config.md` answers *where* a resource lives,
+`substrate.secrets.md` answers *when* a credential expires and *how* to
+rotate it.
+
+## Single-source-of-truth rule
+
+1. **External resource IDs live ONLY in `substrate.config.md`.** Any
+   Google Doc ID, URL, repo reference, or similar pointer is a field
+   in this file.
+2. **Project memory references resources ONLY by field name**, never
+   by raw value. `brand_corpus_doc_id` is a valid memory reference;
+   `1gps7mmEYBCud...` is not.
+3. **Skills and hooks read ONLY from `substrate.config.md`** for
+   resource lookups. No hardcoded IDs in skill files, hook scripts,
+   or agent definitions.
+4. **If an agent needs a resource that isn't in
+   `substrate.config.md`**, the agent prompts the operator to add it
+   with a typed field name. Do not hardcode. Do not cache in memory.
+5. **Scaffolding on new repos prompts for each known field** during
+   `/autonomous start` setup.
+
+## Known fields (extensible)
+
+These fields are recognized by bassclef skills. Not all are required;
+uncommented defaults shown.
+
+```yaml
+# === Artifacts ===
+journal_doc_id: [per-repo draft Google Doc — pushes from /journal + session-end]
+changelog_doc_id: [per-repo weekly changelog Google Doc — pushes from /release-notes]
+brand_corpus_doc_id: [cross-repo brand team corpus — pushes from /journal-export]
+
+# === Environments ===
+deploy_targets:
+  local: true                  # always available
+  staging: false               # URL when configured
+  prod: false                  # URL when configured (hard gate — human-approved)
+
+# === Integrations (optional, per-project) ===
+langfuse_url: [tracing dashboard URL, if used]
+grafana_url: [metrics dashboard URL, if used]
+linear_project_id: [Linear project for ticket sync, if used]
+
+# === Bassclef substrate (bassclef repo only) ===
+# Consumer repos scanned by session-reflection for bassclef-evolution
+# issues. Keep in sync with .github/workflows/bassclef-template-sync.yml
+# matrix. Fallback when field absent: poa only.
+bassclef_evolution_child_repos: [comma-separated list of owner/name]
+
+# === Budget ===
+budget:
+  session_ceiling: [API burst $/session]
+  iteration_ceiling: [API burst $/iteration]
+  warning_threshold: 75%
+
+# === Secret references (names only, not values) ===
+anthropic_key_name: ANTHROPIC_API_KEY   # env var name, not the key
+gh_token_name: GH_TOKEN                  # env var name, not the token
+
+# === Hosting platform (REQUIRED in any consumer that ships a UI) ===
+#
+# Drives which deploy_* fields apply AND which adapter `/bind-subdomain`
+# loads. Every consumer running `/preview-build` or shipping production
+# UI MUST set this — the bassclef default is `amplify` per ADR-008
+# (frontend-stack) + POA + quorum precedent (single-provider portfolio
+# reduces operator cognitive load; AWS-native; cheap port to existing
+# AWS auth).
+#
+# Enum values (all five are valid; not all have shipped adapters yet):
+# - amplify:         use amplify_app_id + amplify_region + amplify_branch
+#                    (bassclef-recommended default; adapters live)
+# - ec2-tailscale:   use deploy_host + deploy_user + deploy_path (POA pattern)
+# - vercel:          adapter not yet shipped — schema reserves the slot
+# - netlify:         adapter not yet shipped — schema reserves the slot
+# - cloudflare-pages: adapter not yet shipped — schema reserves the slot
+# - none:            consumer explicitly opts out of preview/prototype
+#                    deployment. `/bind-subdomain` and `/launch-preview`
+#                    refuse on `none` unless --override given. Use for
+#                    docs-only repos (e.g., bassclef itself) or repos
+#                    that ship no UI surface.
+hosting_platform: amplify   # bassclef default; pick from enum above
+
+# --- Production tier (optional; declare when production differs from prototype) ---
+#
+# Per-tier hosting was added in bassclef#458 to resolve the POA case:
+# POA's prototypes deploy to amplify, but POA's production runs on
+# ec2-tailscale (per ADR-009) and predates the prototype pipeline.
+# Without `production_hosting_platform`, hosting_platform=amplify
+# implies POA's whole app is on amplify — wrong.
+#
+# `production_hosting_platform` is DECLARATIVE. /launch-preview and
+# /bind-subdomain operate on the prototype tier only and do not read
+# this field. It documents the production tier so operators (and
+# future tooling) know the production deploy is a separate concern.
+#
+# When unset, production tier inherits hosting_platform.
+production_hosting_platform: ec2-tailscale   # only set when production differs from prototype
+
+# --- Amplify-specific (when hosting_platform=amplify) ---
+#
+# `amplify_app_id` is the provisioning-indicator field (bassclef#523).
+# Set by `/provision-deploy-host` on success when the Amplify app is
+# created. Composer pre-flight (lib/composer-preflight.sh Check 6) reads
+# this field to verify provisioning happened — when missing or set to a
+# bracketed placeholder shape, /preview-build is BLOCKED with three-path
+# remediation (run /provision-deploy-host inline / re-dispatch with
+# --no-launch / explicit defer). Replaces the silent-defer-bind class
+# that caused POA's 2026-05-05 mobile session to merge variants but
+# never bind a subdomain.
+amplify_app_id: [e.g., d154l5usyc80nk]
+amplify_region: [e.g., eu-north-1]
+amplify_branch: [branch bound to domain, default: main]
+
+# --- EC2 + Tailscale-specific (when hosting_platform=ec2-tailscale) ---
+# See standards/deployment-topology.md for the SENTINEL_bassclef_pattern.
+#
+# `deploy_host` is the provisioning-indicator field (bassclef#523) —
+# Composer pre-flight Check 6 reads it to verify provisioning happened
+# (parallel to amplify_app_id for amplify). Same three-path remediation
+# applies when missing.
+deploy_host: [Tailscale hostname of prod box]
+deploy_user: [SSH user on prod box]
+deploy_path: [absolute path on box, e.g., /opt/poa]
+staging_deploy_host: [same or different Tailscale host]
+staging_deploy_path: [absolute path, e.g., /opt/poa-staging]
+staging_topology: same-box | separate-box    # Option A or B
+tailscale_tag: [CI tag, e.g., tag:ci]
+backup_path: [absolute path, e.g., /opt/backups]
+prod_approval_reviewers: [GitHub usernames comma-separated]
+
+# === Domain + DNS (when app binds a friendly URL) ===
+# See standards/domain-and-dns.md. Optional — skip if using platform
+# default URL (e.g., *.amplifyapp.com). Binding is automated via the
+# /bind-subdomain skill.
+subdomain: [e.g., myapp.apps.example.com]
+dns_provider: [cloudflare | route53]      # v1 supports cloudflare
+dns_zone: [e.g., example.com]
+cloudflare_token_env: [env var name holding CF API token, e.g., CLOUDFLARE_API_TOKEN]
+```
+
+## Migration from anti-patterns
+
+### Anti-pattern 1: raw IDs in project memory
+
+**Before**:
+```markdown
+# memory/reference_brand_corpus.md
+The brand team corpus lives at 1gps7mmEYBCud462Pn_DNf2mXa5Bj58NMjXUUDqWGIh0.
+```
+
+**After**:
+```markdown
+# memory/reference_brand_corpus.md
+The brand team corpus is configured as `brand_corpus_doc_id` in
+substrate.config.md. Agents should always read from there, never
+reference the raw ID directly.
+```
+
+### Anti-pattern 2: hardcoded IDs in skills
+
+**Before** (in `.claude/skills/journal-export/SKILL.md`):
+```bash
+npx tsx scripts/push-to-gdoc.ts \
+  --file docs/journal-corpus/corpus.md \
+  --doc-id 1gps7mmEYBCud462Pn_DNf2mXa5Bj58NMjXUUDqWGIh0
+```
+
+**After**:
+```bash
+DOC_ID=$(grep "^brand_corpus_doc_id:" substrate.config.md | awk '{print $2}')
+npx tsx scripts/push-to-gdoc.ts \
+  --file docs/journal-corpus/corpus.md \
+  --doc-id "$DOC_ID"
+```
+
+Or equivalently, skills document the field name in prose and require
+the agent to look it up at runtime:
+
+```markdown
+## Step 7: Push to Google Docs
+
+Push to `brand_corpus_doc_id` from `substrate.config.md`:
+
+\`\`\`bash
+npx tsx scripts/push-to-gdoc.ts --file docs/journal-corpus/corpus.md \
+  --doc-id $(grep "^brand_corpus_doc_id:" substrate.config.md | awk '{print $2}')
+\`\`\`
+```
+
+### Anti-pattern 3: scattered fields
+
+If an app repo adds a new resource (e.g., a Retool dashboard URL)
+and stores it in a README comment, an inline skill comment, or a
+hook variable — that's the anti-pattern. All such values go in
+`substrate.config.md` with the typed suffix.
+
+## Related rules
+
+- `.claude/rules/substrate-config-schema.md` — enforces this standard
+  at agent behavior level (read from config, don't hardcode, don't
+  cache in memory)
+- `.claude/skills/autonomous/SKILL.md` — prompts for each known field
+  during scaffold
+- `.claude/skills/substrate-check/SKILL.md` — validates substrate.config.md
+  has required fields for the repo type
+
+## Versioning
+
+When bassclef adds a new known field type, the schema here is the
+authoritative list. App repos update their `substrate.config.md` to
+add the new field during next `/autonomous start` scaffold pass (the
+skill surfaces missing fields and prompts for values).

package/substrate/standards/tier-dependency-analysis.md

@@ -144,7 +144,7 @@ Bucket 2 outputs from single-tier and combined-tier agree for that tier's legit
 - Consumed by `.claude/skills/tier-dependency-audit/SKILL.md` — user-invocable wrapper
 - Composed with `scripts/release-to-bassclef.sh` — the ACTUAL set comes from `--dry-run`
 - Composed with `.claude/rules/we-dont-break-adopters.md` (ADR-031) — the audit surfaces adopter-observable classes for careful handling
-- Composed with `.claude/rules/mechanism-fidelity.md` — the subsystem IS the mechanism paired with tier-tag-schema
+- Composed with `.claude/rules/mechanism-fidelity.md` (standard tier) — the subsystem IS the mechanism paired with tier-tag-schema
 
 ## Anchor luminaries
 

package/substrate/standards/tier-tag-schema.md

@@ -117,7 +117,7 @@ Prior default-ship rule for non-md/sh files (superseded by this table 2026-08-20
 
 Files whose path matches an entry in `standards/path-exclusion-registry.json` are excluded from every release regardless of any inner `tier:` value. The path wins. Consumers (release script, audit tools) read the registry as the single source of truth for path-based exclusion classes: `session-runtime`, `operator-private`, `test-only`, `operator-internal-rd`, `prototype`, `config-per-repo`, `ephemeral-transient`.
 
-See `standards/path-exclusion-registry.md` for classes + rationale per entry + how to add a new exclusion.
+The path exclusion registry (operator-only) tracks classes + rationale per entry + how to add a new exclusion.
 
 The path-exclusion registry supersedes the prior inline `case` statement in `scripts/release-to-bassclef.sh` L415-460. The refactor to read the registry ships as a separate PR after this schema amendment.
 

package/substrate/standards/two-layer-config.md

@@ -0,0 +1,99 @@
+---
+tier: lite
+description: "Bassclef's config splits into two layers."
+---
+
+# Two-Layer Config — Shared vs Operator
+
+Bassclef's config splits into two layers. The **shared layer** is committed and identity-agnostic — every adopter sees it. The **operator layer** is gitignored and per-person — never committed, never shipped to adopters.
+
+This standard exists because the line between "what bassclef needs" and "what one operator has set up" was blurry before the 2026-05-23 cold-adopter run. Operator-specific paths, allow lists, and preferences leaked into shared config. Adopters would have inherited the operator's identity on first clone.
+
+## The two layers
+
+### Shared layer (committed)
+
+- `.claude/settings.json`
+- `CLAUDE.md`
+- `README.md`
+- All skills, hooks, rules, standards under `.claude/` and root dirs
+- All ADRs, decompositions, design docs
+
+**Rules for the shared layer:**
+
+1. Identity-agnostic. No absolute paths to specific home directories.
+2. No personal allow-list entries (broad npm grants, macOS process control, etc.).
+3. No "sunj-labs" references except in attribution.
+4. Tested against cold-adopter personas (`strategy/personas/`) before publication.
+
+### Operator layer (gitignored)
+
+- `.claude/settings.local.json`
+- `CLAUDE.local.md` (optional, if operator wants per-machine context)
+- `.env.local`
+- Anything ending in `.local`
+
+**Rules for the operator layer:**
+
+1. Holds operator-specific allow lists, machine paths, personal aliases.
+2. Never committed. `.gitignore` enforces this by listing the files explicitly.
+3. Each contributor creates their own. The shared `.gitignore` block tells them which files to create.
+4. Where convenience accumulates — broad `Bash(rm *)` grants, machine-specific paths, etc.
+
+## Mechanical enforcement
+
+`.claude/hooks/pre-commit-gate.sh` includes a CCF-3 absolute-path guard. It runs on every `git commit` and BLOCKs when any staged non-exempt file contains `/Users/<name>` or `/home/<name>` patterns.
+
+**Exempt paths** (where these patterns are legitimate — documentation, audits, test fixtures):
+
+- `.claude/rules/`, `.claude/hooks/`, `.claude/skills/`, `.claude/luminaries/`, `.claude/agents/`
+- `standards/`, `architecture/`, `design/`
+- `docs/` (all subdirs)
+- `chronicle/`, `strategy/`
+- `scripts/tests/`
+
+**Non-exempt** (where the guard fires): everything else. Most importantly `.claude/settings.json`, top-level configs, source code under `src/` or `lib/`.
+
+When the guard fires, it points to `.claude/settings.local.json` as the right home for the offending entry.
+
+## Override
+
+`SKIP_OPERATOR_PATHS=1 git commit` — logged via `trace-helper.sh`. Use only for genuine cases where the absolute path must live in the shared layer (rare). Document the rationale in the commit message.
+
+## What this fixes
+
+Before this standard:
+
+- `.claude/settings.json` shipped `Bash(rm /Users/<operator>/src/<org>/bassclef/*)` — F70 in the 2026-05-23 cold-adopter run. Every public clone would have inherited that operator-identity line.
+- Allow-list entries reflected operator workflow rather than adopter safety — F73 in the same run.
+
+After this standard:
+
+- F70 is removed from the committed `.claude/settings.json`.
+- The hook prevents the class from recurring.
+- New operator-convenience entries go to `.claude/settings.local.json`.
+
+## When to add a new field to the operator layer
+
+Any of these signals mean it belongs in `settings.local.json`, not `settings.json`:
+
+- Contains an absolute path matching `/Users/<name>` or `/home/<name>`.
+- Grants a broad permission (`Bash(rm *)`, `Bash(npm*)`, `Bash(pkill*)`) that an adopter on a first session would not be expected to want.
+- References operator-specific tools or paths (`/Applications/Tailscale.app/...`).
+- Encodes machine-specific config (hostnames, ports tied to a specific dev setup).
+
+When in doubt, default to the operator layer. It's cheaper to promote a setting from `settings.local.json` to `settings.json` later than to ship operator identity to every adopter.
+
+## Sources read
+
+- `docs/adoption-runs/2026-05-23-cold-adopter-1.md` — the cold-adopter run record (PR #735)
+- Operator handoff CCF-3 + Step 5 Issue 4 — the policy specification
+- F70 (operator path leak in committed `.claude/settings.json`)
+- F73 (allow-list grants reflect operator workflow rather than adopter safety)
+- `.claude/hooks/pre-commit-gate.sh` — the mechanical enforcement
+- `.claude/rules/blocked-items.md` — the resolve-or-defer protocol the BLOCKED signal slots into
+
+## Closes
+
+- bassclef#740 (CCF-3 — two-layer config policy)
+- bassclef#738 (Pre-launch cleanup — F70 instance)