@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/standards/architect-review-discipline.md

@@ -0,0 +1,222 @@
+---
+tier: lite
+status: live
+date: 2026-06-27
+authority: ADR-035
+references:
+  - {type: adr, id: ADR-035, anchor: substrate-as-system tenet + verification lenses}
+  - {type: standard, id: standards/mechanism-fidelity.md, anchor: audit method for substrate sibling}
+  - {type: standard, id: standards/cold-adopter-harness.md, anchor: per-PR mechanism-fidelity check class}
+  - {type: skill, id: .claude/skills/architect-review/SKILL.md, anchor: the SKILL that composes this framework}
+  - {type: skill, id: .claude/skills/audit-rule-mechanism-fidelity/SKILL.md, anchor: substrate sibling's verification skill (tier upstream)}
+  - {type: rule, id: .claude/rules/architect-review-discipline.md, anchor: companion rule (lands in WU-9.5)}
+  - {type: external, id: Working Effectively with Legacy Code — Michael Feathers, anchor: characterization tests — universal principle}
+  - {type: external, id: A Philosophy of Software Design — John Ousterhout, anchor: red flag — comment-driven design + deep modules}
+  - {type: external, id: The Mythical Man-Month — Frederick Brooks, anchor: conceptual integrity}
+luminaries:
+  primary: [michael-feathers, w-edwards-deming, kaoru-ishikawa]
+  supporting: [saltzer-schroeder, tony-hoare, kent-beck, hyrum-wright, linus-torvalds, frederick-brooks, john-ousterhout]
+description: "- ADR-035 — names the substrate-as-system tenet + the lens-gap that bet 24c surfaced - architecture/audits/2026-06-24-closeout.md — the audit that missed the mechanism-fidelity class; informs the universal framework's mandatory verification step -…"
+---
+
+# Architect-review discipline — universal framework
+
+> **Anthropic docs reference:** This standard is the UNIVERSAL framework that ships to adopters. It does not depend on Anthropic's hook surface. The framework names the lenses + the method; per-stack siblings (under `standards/architect-review-discipline/<stack>.md`) hold the stack-specific verification mechanisms. Adopters loading the framework get the universal principle; siblings load per declared `tech_stack.kind` in `.claude/bassclef-configs.jsonc`.
+
+## Sources read
+
+- ADR-035 — names the substrate-as-system tenet + the lens-gap that bet 24c surfaced
+- `architecture/audits/2026-06-24-closeout.md` — the audit that missed the mechanism-fidelity class; informs the universal framework's mandatory verification step
+- `.claude/skills/architect-review/SKILL.md` — the existing SKILL; WU-9.5 amends to call this framework
+- `.claude/rules/api-conventions.md` + `standards/api-conventions/nextjs.md` — Path A sibling pattern exemplar (ARCH-T0 bassclef-upstream#1133)
+- `.claude/rules/schema-management.md` + `standards/migration-discipline/<orm>.md` — sister Path A pattern
+- `.claude/rules/new-dependency-check.md` + `standards/dependency-discipline/<pm>.md` — sister Path A pattern
+- bassclef-upstream#1127 — `tech_stack.kind` vocabulary that drives sibling loading
+
+## What this standard covers
+
+The universal framework that every architect-review applies — regardless of project stack. The framework names:
+
+- Universal lens set (comprehension + verification — both required)
+- Universal procedure (static method + dynamic method — both required)
+- The per-stack sibling pointer (loaded from `.claude/bassclef-configs.jsonc` `tech_stack.kind`)
+
+Adopters running `/architect-review` on a Next.js app get the universal lenses + framework + a clean "your stack sibling isn't authored yet — file `/promote` to draft it" surface if no sibling exists. Adopters never see bassclef-internal vocabulary or paths.
+
+The substrate sibling (`standards/architect-review-discipline/substrate.md` — for bassclef-upstream itself, tech_stack.kind = substrate) defines verification specific to substrate work — the mechanism-fidelity audit + the cold-adopter harness check classes.
+
+## Universal principle
+
+> Every project is a system. Every claim it makes (function signatures, API endpoints, schema fields, documented behaviors, configuration contracts) is a contract. Per @luminary michael-feathers, untested contracts are legacy code by definition. Per @luminary kent-beck, tests pin contracts. Architect-review verifies — for the stack at hand — that the project's claims hold end-to-end. The verification method is stack-specific; the principle is universal.
+
+This sentence appears verbatim in `.claude/luminaries/michael-feathers.md` (anchor cite), in `.claude/rules/substrate-as-system.md` (auto-loaded reminder), in every per-stack sibling's opener, and in ADR-035 (the foundational tenet section). Future ADRs cite this principle by name (`per ADR-035 substrate-as-system tenet`).
+
+## Universal lens set
+
+Every architect-review applies BOTH halves: comprehension lenses to organize findings + verification lenses to verify claims hold.
+
+### Comprehension lenses (organize findings)
+
+- @luminary w-edwards-deming — Act phase; corrective action from findings
+- @luminary kaoru-ishikawa — 6M fishbone (Man / Machine / Method / Material / Measurement / Mother Nature) to categorize causes
+- @luminary linus-torvalds — adopter-compat: does the change break existing adopters or users
+- @luminary frederick-brooks — conceptual integrity: does the system match its design
+
+### Verification lenses (verify claims hold)
+
+- @luminary michael-feathers — characterization tests: code without tests is legacy code by definition
+- @luminary kent-beck — TDD: tests pin contracts
+- @luminary tony-hoare — pre/postcondition: do the contracts hold against the implementation
+- @luminary saltzer-schroeder — complete mediation: every claim verified empirically, not nominally
+- @luminary hyrum-wright — observable behavior: every documented claim becomes a contract with users / adopters
+- @luminary john-ousterhout — deep modules: does the API match its internal complexity, or does the API lie
+
+Bet 2026-06-24c architect-review anchored on comprehension lenses only; the audit could not catch a class that only verification lenses surface (mechanism-fidelity). This universal framework requires both halves.
+
+## Universal procedure (mandatory steps)
+
+Every architect-review runs all six steps:
+
+```
+1. Read the previous architect-review at docs/architecture/reviews/<latest>.md
+   to compare against (delta-driven; surface only changes since last review)
+2. Explore the codebase — C4 Context + Container + Component diagrams
+3. Apply comprehension lenses to organize findings — Ishikawa 6M categorization
+4. Apply verification lenses — for every documented claim, verify it holds end-to-end
+   per the per-stack sibling
+5. Apply Deming's Act phase — each finding either filed as ticket OR
+   closed in this PR OR explicitly deferred with rationale
+6. Produce the report at docs/architecture/reviews/<YYYY-MM-DD>.md
+```
+
+Step 4 is the mandatory verification step that bet 24c skipped. Implementation per the per-stack sibling.
+
+## Per-stack sibling lookup
+
+Adopters declare their stack in `.claude/bassclef-configs.jsonc`:
+
+```jsonc
+"tech_stack": {
+  "kind": "<substrate | nextjs | python | rails | go | none>",
+  "orm": "<prisma | sqlalchemy | alembic | active-record | gorm | none>",
+  "pkg_manager": "<npm | pnpm | yarn | pip | poetry | cargo | gem | go-mod | none>"
+}
+```
+
+Architect-review SKILL reads `tech_stack.kind` and loads the matching sibling:
+
+| tech_stack.kind | Sibling path | What verification = |
+|---|---|---|
+| `substrate` | `standards/architect-review-discipline/substrate.md` | Run `/audit-rule-mechanism-fidelity`; check rule-mechanism-claim-fidelity per `standards/mechanism-fidelity.md`; verify cold-adopter harness check classes pass per `standards/cold-adopter-harness.md` |
+| `nextjs` | `standards/architect-review-discipline/nextjs.md` *(future — file `/promote` per bassclef-upstream#418)* | Playwright + smoke coverage for every API route; characterization tests for every Server Action; load test for every public endpoint |
+| `python` | `standards/architect-review-discipline/python.md` *(future)* | pytest integration coverage per module; contract tests for every public API; characterization tests around legacy modules |
+| `rails` | `standards/architect-review-discipline/rails.md` *(future)* | RSpec request specs; system specs for critical flows; characterization tests for legacy controllers |
+| `go` | `standards/architect-review-discipline/go.md` *(future)* | Table-driven tests; integration tests via httptest; fuzz tests for inputs |
+| `none` or unset | universal framework only | Operator picks verification method per finding; framework's universal lenses + procedure still apply |
+
+When the matching sibling does not exist, the universal procedure applies; verification step surfaces "no sibling for this stack" + cites bassclef-upstream#418 as the place to file `/promote` for sibling authoring.
+
+## Path A pattern
+
+This standard follows the per-stack sibling pattern established by:
+
+- `standards/api-conventions/<stack>.md` (sister; api-conventions universal + per-stack)
+- `standards/migration-discipline/<orm>.md` (sister; schema-management universal + per-orm)
+- `standards/dependency-discipline/<pkg-manager>.md` (sister; new-dependency-check universal + per-pm)
+
+The pattern was established under ARCH-T0 bassclef-upstream#1133 (stack-leakage audit) — universal framework lives in the parent rule + standard; stack-specific specifics live in siblings; loader reads `tech_stack` from configs.
+
+## When the framework is invoked
+
+The architect-review SKILL invokes this framework whenever `/architect-review` is invoked. Per memory + ADR convention, that is at least:
+
+- Every 10 commits OR before any launch (per current SKILL description)
+- After any substrate-evolution bet closeout (operator preference)
+- After any P0 substrate-defect surfaces (defensive)
+- Operator-invoked ad-hoc
+
+## Output (every architect-review report)
+
+The report at `docs/architecture/reviews/<YYYY-MM-DD>.md` includes:
+
+```
+## Lenses applied
+- Comprehension: <list>
+- Verification: <list>
+
+## Findings (Ishikawa 6M categorized)
+| Bone | Findings |
+|---|---|
+| Man | ... |
+| Machine | ... |
+| Method | ... |
+| Material | ... |
+| Measurement | ... |
+| Mother Nature | ... |
+
+## Verification per stack
+Stack: <kind>
+Sibling loaded: <path or "none — file /promote">
+Verification results: <pass/fail per claim category>
+
+## Act phase (Deming)
+- Filed: <ticket numbers>
+- Closed in this PR: <list>
+- Explicitly deferred: <list with rationale>
+```
+
+Reports without the verification section are non-conformant — the framework refuses to consider an architect-review "complete" without it.
+
+## Anti-patterns
+
+### Run architect-review with comprehension lenses only
+
+The bet 2026-06-24c failure mode. INSTEAD: include verification-side lenses + run the per-stack sibling's verification step. Framework refuses non-conforming reports.
+
+### Hardcode bassclef-internal verification into the universal SKILL
+
+Breaks adopter-safety (adopters running `/architect-review` on their app would hit substrate-specific paths). INSTEAD: substrate verification lives in `standards/architect-review-discipline/substrate.md`; SKILL references the sibling by `tech_stack.kind` lookup.
+
+### Skip the verification step because no sibling exists for the adopter's stack
+
+A missing sibling is a `/promote` opportunity, not an excuse. INSTEAD: surface "no sibling for `<stack>` — file `/promote` per bassclef-upstream#418" + apply universal framework's lens + procedure to whatever can be verified manually.
+
+### Architect-review without comparing against the previous review
+
+Drift goes uncaught when each review starts fresh. INSTEAD: step 1 mandates reading the prior review + surfacing the delta.
+
+## Composes with
+
+- `standards/mechanism-fidelity.md` — the audit method that the substrate sibling invokes
+- `standards/cold-adopter-harness.md` — the harness extension that runs verification per PR
+- `standards/hook-injection-discipline.md` + `standards/hook-install-class.md` — substrate verification covers hooks per these standards
+- `.claude/skills/architect-review/SKILL.md` — the SKILL that composes this framework (WU-9.5 amends to call it)
+- `.claude/rules/architect-review-discipline.md` (lands in WU-9.5) — the rule that enforces this framework
+- `.claude/rules/bootstrap-pair-discipline.md` — paired ship discipline that verification verifies post-merge
+- `.claude/rules/blocked-items.md` — findings file `/promote substrate-defect` per the protocol
+
+## Refs
+
+- ADR-035 — substrate-as-system tenet + hooks-as-steering-surfaces
+- bassclef-upstream#417 — umbrella tracking for bet 2026-06-27c
+- bassclef-upstream#418 — follow-on: per-stack siblings (Next.js, Python, Rails, Go) + adopter configs UI
+- bassclef-upstream#320 — substrate-architect-review umbrella (bet 24c)
+- bassclef-upstream#1133 — ARCH-T0 stack-leakage audit (Path A pattern established)
+- bassclef-upstream#1127 — `tech_stack` vocabulary
+- `architecture/audits/2026-06-24-closeout.md` — bet 24c closeout (the audit this framework retroactively learns from)
+- `architecture/audits/2026-06-27-mechanism-fidelity.md` (lands in WU-6) — first substrate-sibling audit run
+- `architecture/audits/2026-06-27-audit-method-blind-spot.md` (lands in WU-7.5) — recursive Ishikawa + Deming on bet 24c method
+- @luminary michael-feathers — *Working Effectively with Legacy Code*: universal characterization-tests principle
+- @luminary kent-beck — *Test-Driven Development By Example*: tests pin contracts
+- @luminary w-edwards-deming — Plan-Do-Check-Act: comprehension + corrective action
+- @luminary kaoru-ishikawa — fishbone: comprehension categorization
+- @luminary saltzer-schroeder — complete mediation: verification empirically
+- @luminary tony-hoare — pre/postcondition: contract holds against implementation
+- @luminary hyrum-wright — observable behavior becomes contract for users / adopters
+- @luminary linus-torvalds — we-don't-break-userspace: adopter contract
+- @luminary frederick-brooks — conceptual integrity: system matches design
+- @luminary john-ousterhout — deep modules: API matches internal complexity
+
+## Retirement condition
+
+This standard retires only if architect-review itself ceases to be a bassclef SKILL. The universal framework may evolve (new lenses surface; new verification mechanisms appear) but the two-method requirement (comprehension + verification) persists.

package/dist/lite/standards/bassclef-platform.md

@@ -0,0 +1,249 @@
+---
+tier: lite
+description: The agent-native platform-engineering primitive.
+---
+
+# bassclef-platform.yml — Org-Baseline Platform Manifest
+
+The agent-native platform-engineering primitive. One flat YAML, in a
+sibling repo, that names every org-level infrastructure assumption
+bassclef's provisioning skills need at dispatch-time.
+
+## Sources read
+
+- `strategy/canvases/2026-05-03-bassclef-platform-primitive.md` — Stage 2 PR/FAQ + Stage 3 Phase 1 acceptance criteria
+- `docs/iteration-bets/2026-05-04-bassclef-platform-foundation.md` — bet that ships this primitive
+- `standards/state-spine/schemas/bassclef-platform.schema.json` — the SHAPE contract this standard documents semantics for
+- `standards/state-spine.md` — Shape D entity placement (added bassclef#462)
+- `standards/substrate-config-schema.md` — sibling per-repo concern; this is the org-baseline concern
+- `architecture/decisions/ADR-008-full-typescript-stack.md` — `stack.default_*` references this
+- `architecture/decisions/ADR-009-deploy-and-operations.md` — `deploy_tiers.*` references this
+- `standards/domain-and-dns.md` — `dns.*` field semantics
+
+## What I'm NOT reading (with reason)
+
+- Backstage source code or plugin docs — this standard references Backstage for positioning only, not for technical adaptation
+- Pulumi / Terraform / OpenTofu docs — sibling IaC tools; bassclef-platform.yml is declarative-READ, not declarative-IaC; orthogonal concerns
+
+## Why this exists — the agent-native equivalent of Backstage
+
+Backstage gave developers a service-catalog portal: a Node app + database +
+plugins, days-to-weeks to deploy, that lets engineers find services, run
+templates, and read system metadata. It works because *developers read
+the portal*.
+
+Agentic SDLC has a different problem. **Agents don't read portals.** Agents
+read files. When a bassclef provisioning skill (`/provision-deploy-host`,
+`/secrets-bootstrap`, `/scaffold-stack`) needs to know "what's our AWS
+account, what's our DNS zone, which platform do we deploy prototypes to" —
+it needs that information in a flat file at dispatch-time, not behind a
+REST endpoint behind an auth-handshake behind a portal-deployment.
+
+`bassclef-platform.yml` is that file. One YAML. Sibling repo. Edit and go.
+
+| Primitive | Format | Setup cost | Agent-native? | Market position |
+|-----------|--------|-----------|---------------|-----------------|
+| Backstage `catalog-info.yaml` + portal | YAML + Node + DB + plugins | days-to-weeks | needs adapter | dominant for IDP, but heavyweight |
+| Pulumi stack config | TS/HCL + runtime | Pulumi installed everywhere | no — IaC-native | strong for IaC; orthogonal to "agent-discovery" |
+| Terraform `workspace.yaml` | HCL + Terraform Cloud | Terraform install + state mgmt | no — IaC-native | dominant IaC; orthogonal |
+| **bassclef-platform.yml** | **flat YAML** | **`touch` + edit** | **yes — agent-first** | **uncontested for agent-native IDP** |
+
+Position bassclef's substrate when pitching to PE / boards / CIOs:
+
+> bassclef is the agent-native equivalent of Backstage for organizations
+> adopting agentic SDLC. Same primitives — service catalog, infrastructure
+> declarations, policy-as-data — but consumed by AGENTS at dispatch-time
+> rather than developers at portal-time. Result: provisioning that's
+> normally days of clickops or hours of Terraform becomes one dispatch
+> plus one PR merge.
+
+## Where the file lives
+
+**Sibling repo, not bassclef.** Default convention:
+
+```
+~/src/<github_org>/platform-config/bassclef-platform.yml
+```
+
+For sunj-labs, the resolved path is:
+
+```
+~/src/sunj-labs/platform-config/bassclef-platform.yml
+```
+
+Why a sibling repo, not bassclef's repo:
+
+1. **Adopters fork platform-config without forking bassclef.** A CIO
+   evaluating bassclef for their org doesn't fork the methodology repo;
+   they fork the platform-config repo, edit values, point their consumer
+   repos' `.bassclef-source.json` at upstream bassclef. Bassclef stays
+   one upstream; platform-config is per-tenant.
+2. **Multi-tenant capable from V1.** A 4-BU enterprise checks out 4
+   platform-config repos, points each consumer repo's thin-pointer at
+   the right one. Single-tenant deployed in V1; multi-tenant is just
+   "more sibling repos" — no schema change.
+3. **Org-level facts don't belong in methodology.** Bassclef is the
+   rulebook; platform-config is the runtime configuration. Different
+   change cadences, different review surfaces, different audit trails.
+
+## Resolution order
+
+`state_platform_get` resolves the file path in this order:
+
+1. **`BASSCLEF_PLATFORM_CONFIG_PATH` env var** — explicit override. Used
+   by tests and unusual deployment topologies.
+2. **`~/src/<github_org>/platform-config/bassclef-platform.yml`** — the
+   default convention. `<github_org>` resolves from substrate.config.md
+   or, in V1, hardcodes to `sunj-labs`. (V2 reads it from the consumer
+   repo's substrate.config.md `github_org` field.)
+3. **Thin-pointer field `platform_config_source` in `.bassclef-source.json`** —
+   V2 extension. When bassclef-sync ships the field, consumer repos
+   declare which platform-config repo to consume; resolution chases the
+   declared path. Until V2: option 2 is the only fallback.
+
+## What lives in this file vs. substrate.config.md
+
+| Concern | Where |
+|---------|-------|
+| Org name, GitHub org, AWS account ID | bassclef-platform.yml (org-baseline) |
+| Default DNS zone, DNS provider, token env-var name | bassclef-platform.yml |
+| Default stack (frontend / backend / db) | bassclef-platform.yml |
+| Per-tier deploy-host defaults (prototype / production) | bassclef-platform.yml |
+| Provisioning behavior switches (CLI vs console-pivot) | bassclef-platform.yml |
+| Secrets storage type default (env / 1password / vault) | bassclef-platform.yml |
+| Audit-trail policy | bassclef-platform.yml |
+| **THIS REPO**'s deploy URL, app ID, branch | substrate.config.md (per-repo) |
+| **THIS REPO**'s subdomain | substrate.config.md |
+| **THIS REPO**'s environment-specific overrides | substrate.config.md |
+
+The line: **anything sunj-labs configures once across all repos** lives
+in bassclef-platform.yml. **Anything that varies per repo** lives in that
+repo's substrate.config.md.
+
+If a field needs to vary per repo, it's a substrate.config.md field, not
+a bassclef-platform.yml field. The schema enforces this division.
+
+## Provider adapter pattern
+
+`hosting_platform` is a discriminator enum. Provider-specific subfields
+live under namespaced top-level keys (`amplify.*`, `vercel.*`,
+`ec2_tailscale.*`).
+
+Provisioning skills dispatch through an adapter:
+
+```
+/provision-deploy-host reads bassclef-platform.yml deploy_tiers.<tier>.hosting_platform
+  → "amplify" → loads amplify adapter, reads top-level amplify.* fields
+  → "vercel"  → loads vercel adapter, reads top-level vercel.* fields
+  → "ec2-tailscale" → loads ec2 adapter, reads top-level ec2_tailscale.* fields
+  → "none"    → no-op (docs-only repos)
+```
+
+Same shape as `/bind-subdomain`'s DNS-provider adapter pattern. The first
+time a consumer needs Vercel, it's an adapter file added under
+`scripts/adapters/`, not a schema rewrite.
+
+## Per-tier deploy-host split
+
+`deploy_tiers.prototype` and `deploy_tiers.production` are independent.
+Different provider, different region, different config.
+
+This resolves the POA gotcha (POA's existing `ec2-tailscale` production
+deploy must coexist with `amplify` prototype hosting). Without the split,
+bassclef-platform.yml could only carry one `hosting_platform` per org —
+which would force POA to either give up production-on-ec2 or give up
+prototypes-on-amplify. The split says "both, indexed by tier."
+
+## Secrets storage type
+
+`secrets.storage_default` is a discriminator. Per-secret entries in
+`substrate.secrets.md` may override.
+
+V1 ships the `env` adapter only — secrets live in
+`~/.config/bassclef/secrets.env` (XDG-conformant), sourced by `.zshrc`.
+
+V2 stubs:
+- `1password` — `op read op://<vault>/<item>/<field>`
+- `aws-sm` — `aws secretsmanager get-secret-value`
+- `vault` — `vault kv get`
+
+Each adapter is a script under `scripts/secrets-adapters/` — same shape
+as the DNS-provider adapters. Schema is unchanged when V2 lands; only
+adapter scripts ship.
+
+## Audit-trail primitive
+
+`audit.enabled = true` (default) makes every `/provision-*` skill write
+a row to `state/audit/<utc>-<skill>-<short-hash>.json` per dispatch.
+
+Each row captures:
+- env vars consulted (names only, never values)
+- API calls made (method + endpoint + status, never body if it contains secrets)
+- ARNs / IDs created
+- Operator dispatch context (session id, branch, intent string)
+
+CIO evaluations ask "what did the agent do, on what authority, with what
+credentials" in week 1. This primitive answers that without retrofit.
+
+`audit.retention_days = 365` (default) — adopters tighten or loosen per
+compliance regime.
+
+## Validation
+
+Schema: `standards/state-spine/schemas/bassclef-platform.schema.json` —
+JSON Schema draft-2020-12.
+
+`state-validate.sh` PreToolUse hook validates on Edit/Write. Pattern:
+`*/bassclef-platform.yml` triggers entity detection.
+
+Required fields (the minimum for a bassclef-platform.yml to be
+considered onboard-able):
+
+- `org.name`
+- `org.github_org`
+- `dns.primary_zone`
+
+Everything else has documented defaults. The schema's `additionalProperties: true`
+on the root means orgs can extend the schema without it rejecting their
+edits — but the documented fields are what bassclef's skills consume.
+
+## Schema versioning
+
+`schema_version: v0` — documentary; required-field set is loose.
+
+`v1` will tighten property typing once empirical adoption surfaces real
+divergence between sunj-labs's shape and the next adopter's shape.
+Migration path: same as bassclef's other schemas — paired PR amends
+schema + bumps `schema_version` field; old files migrate via a one-shot
+script.
+
+## /scaffold-platform-yml mini-skill (Phase 2 follow-on)
+
+When bassclef#462 closes, the operator runs `/scaffold-platform-yml`
+once to backfill values from existing AWS + GitHub state via API
+probes:
+
+- `aws sts get-caller-identity` → `org.aws_account_id`
+- `gh api /user/installations` → `provisioning.github_app_installation_id`
+- `aws iam list-roles` (filter `amplify`) → `amplify.service_role_arn`
+- `aws amplify list-apps` (per region) → `amplify.default_region`
+
+Skill ships in bassclef#462 sub-goal 1.1 of the platform foundation bet
+(deferred follow-on; not critical-path for V1). Operator-edit is the
+fallback for fields the API can't probe.
+
+## Relationship to other standards
+
+- `standards/substrate-config-schema.md` — sibling per-repo concern
+- `standards/secrets-lifecycle.md` — per-secret rotation tracking; storage_default discriminator added by bassclef#461
+- `standards/state-spine.md` — Shape D placement
+- `standards/state-spine-contract.md` — `state_platform_get` accessor surface
+- `standards/domain-and-dns.md` — DNS conventions referenced by `dns.*`
+- ADR-008 (TypeScript stack) — `stack.default_*` references this
+- ADR-009 (deploy operations) — `deploy_tiers.*` references this
+
+## Enforcement
+
+- **Hook**: `state-validate.sh` validates on Edit/Write to `*/bassclef-platform.yml`
+- **Methodology**: this standard loads via bassclef-sync; all consumer repos read it
+- **Test coverage**: `.claude/hooks/tests/state-validate.test.sh` (bassclef-platform Shape D cases added in bassclef#462)

package/dist/lite/standards/bassclef-test-repos.md

@@ -0,0 +1,97 @@
+---
+tier: lite
+description: "Two dedicated repos exist as bassclef's validation surface — separate from operator product work (POA, TwoDo, Ops, Pruneguice, Quorum)."
+---
+
+# Bassclef Test Repos
+
+Two dedicated repos exist as bassclef's validation surface — separate from operator product work (POA, TwoDo, Ops, Pruneguice, Quorum).
+
+This is the pattern bassclef uses to validate substrate changes without polluting the repos where real product work happens. Surfaced 2026-05-11 during the TwoDo cross-repo execution boundary discussion (bassclef#639); test ground established 2026-05-12 (bassclef#642).
+
+## The two test repos
+
+### `sunj-labs/dokuwiki-bassclef-test` — brownfield validation target
+
+**Source**: fork of `dokuwiki/dokuwiki` (open-source PHP wiki, flat-file storage, no DB)
+
+**Why DokuWiki**:
+- Already on GitHub (direct `gh repo fork` works)
+- PHP/flat-file stack ≠ bassclef's TypeScript default — exercises vendor-bindings coverage on a different stack
+- Mature codebase representative of real brownfield-adoption shapes
+- GPL-2.0 license; fork is welcome with attribution preserved
+- Smaller than alternatives (BookStack/MediaWiki) — faster validation cycles
+
+**Visibility**: PUBLIC (inherited from upstream)
+
+**What bassclef tests against it**:
+- Retroactive adoption — adding bassclef-sync + rules + hooks to an EXISTING codebase that didn't start with bassclef conventions
+- Vendor-bindings (PHP/no-DB stack vs bassclef's TypeScript default)
+- Brownfield file-structure migration questions (where do bassclef artifacts land in a non-bassclef layout?)
+
+### `sunj-labs/foobar` — minimal greenfield consumer
+
+**Source**: created empty via `gh repo create`
+
+**Why "foobar"**:
+- Placeholder by design. Not a product. Not a demo target. Just a thing that adopts bassclef via bassclef-sync.
+
+**Visibility**: PRIVATE
+
+**What bassclef tests against it**:
+- Greenfield adoption — bassclef conventions from day zero
+- Minimal-app smoke validation — bassclef-sync runs cleanly on a fresh Next.js skeleton
+- Future substrate changes — first integration test target
+
+**What foobar is NOT**:
+- NOT a product. No domain model, no auth, no features beyond "Next.js skeleton + bassclef adoption."
+- NOT the Hey-Alexa demo target (Phase V). The demo creates whatever Alex speaks into existence at runtime; it's a separate concern.
+- NOT a long-term bassclef product. If bassclef eventually wants its own product surface, that's separate scope.
+
+## How they fit bassclef's interaction model (ADR-018)
+
+Both repos are **Consumer** objects per the runtime-interaction model. They consume bassclef's substrate via bassclef-sync, same as POA/TwoDo/Ops/Pruneguice/Quorum.
+
+The distinction:
+- **Operator product consumers** — POA, TwoDo, Ops, Pruneguice, Quorum. Real product work. Bassclef-session writes to these repos = bassclef#639 boundary violation.
+- **Bassclef test consumers** — dokuwiki-bassclef-test, foobar. Designed-as-test-ground. Bassclef-session-driven git operations (clone + edit + push) are the EXPECTED use case.
+
+Per bassclef#639's stated principle: "bassclef session must NOT execute hooks or scripts on consumer-repo filesystems." Standard git operations on cloned test repos don't trigger this — no consumer-side hook execution involved.
+
+If future ambiguity surfaces, file substrate-defect to clarify the boundary.
+
+## Validation cadence
+
+Test repos receive bassclef-sync runs at any time. Recommended:
+- After substantive bassclef-sync template changes
+- Before opening bassclef to new adopters (bassclef#637 readiness audit)
+- When vendor-bindings catalog (bassclef#629) ships new abstractions
+
+Test results land in `docs/sibling-validations/YYYY-MM-DD-<test-repo>-<concern>.md`.
+
+## Distinct from
+
+- `standards/vendor-plugins/` — third-party skills bassclef adopts (e.g., Anthropic community skills). Not test repos.
+- `standards/bassclef-platform.md` — org-level infra surface. Not test repos.
+- `standards/vendor-bindings.md` — external-service binding catalog. Test repos exercise the catalog; they don't define it.
+
+## When to retire / replace
+
+This standard retires if:
+- DokuWiki upstream becomes inactive + we need a new brownfield target
+- foobar gets product features (at which point it's no longer a test consumer)
+- bassclef evolves a different test-ground pattern (e.g., ephemeral test consumers, sandboxed runs)
+
+Until then, both repos stay live + receive periodic bassclef-sync runs as validation surface.
+
+## Sources read
+
+- bassclef#642 (test-repos parent ticket)
+- bassclef#639 (cross-repo execution boundary; this standard names the legitimate exception)
+- `architecture/decisions/ADR-018-bassclef-interaction-model.md` (Consumer object definition)
+- `docs/iteration-bets/2026-05-12-test-repos-dokuwiki-foobar.md` (active bet)
+- `docs/stacks/2026-05-12-test-repos-dokuwiki-foobar.md` (active manifest)
+
+## Closes
+
+bassclef#642 WU-1. WU-3 + WU-5 follow with bassclef-adoption on each repo.

package/dist/lite/standards/bassclef-wiring-manifest.json

@@ -2,7 +2,7 @@
   "tier": "standard",
   "$id": "https://bassclef.sunj-labs/bassclef-wiring-manifest/v1",
   "$schema": "https://bassclef.sunj-labs/state-spine/v0/schemas/bassclef-wiring-manifest.schema.json",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "hooks": {
     "SessionStart": [
       {
@@ -159,6 +159,12 @@
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-gh-release-body-scrub.sh",
             "timeout": 5,
             "tier": "standard"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-commit-identifier-leak-scrub.sh",
+            "timeout": 10,
+            "tier": "lite"
           }
         ]
       },
@@ -290,6 +296,12 @@
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/vocabulary-migration-check.sh",
             "timeout": 10,
             "tier": "lite"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/persona-name-scrub-check.sh",
+            "timeout": 10,
+            "tier": "lite"
           }
         ]
       }
@@ -397,6 +409,18 @@
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-assertion-shape-scan.sh",
             "timeout": 10,
             "tier": "standard"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/longrun-prep-render-check.sh",
+            "timeout": 10,
+            "tier": "lite"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-step-list-check.sh",
+            "timeout": 10,
+            "tier": "lite"
           }
         ]
       }