@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/standards/mechanism-fidelity.md

@@ -0,0 +1,205 @@
+---
+tier: lite
+status: live
+date: 2026-06-27
+authority: ADR-035
+references:
+  - {type: adr, id: ADR-035, anchor: substrate-as-system tenet}
+  - {type: standard, id: standards/hook-injection-discipline.md, anchor: injection hook contract}
+  - {type: standard, id: standards/hook-install-class.md, anchor: install-class declaration}
+  - {type: standard, id: standards/architect-review-discipline.md, anchor: universal architect-review framework that composes this audit}
+  - {type: standard, id: standards/cold-adopter-harness.md, anchor: harness check class that runs this audit per PR}
+  - {type: rule, id: .claude/rules/bootstrap-pair-discipline.md, anchor: hook + test + wiring shipping together}
+  - {type: rule, id: .claude/rules/testing-tier-config.md, anchor: Tier 0 strict-TDD path table}
+  - {type: external, id: Working Effectively with Legacy Code — Michael Feathers, anchor: legacy code = code without tests}
+  - {type: external, id: Test-Driven Development By Example — Kent Beck, anchor: tests pin the contract}
+luminaries:
+  primary: [michael-feathers, kent-beck]
+  supporting: [saltzer-schroeder, tony-hoare, hyrum-wright]
+description: "- ADR-035 — names the substrate-as-system foundational tenet that this standard's audit method verifies - architecture/audits/2026-06-24-closeout.md — bet 24c architect-review that missed this class; this standard's audit fills the lens-gap and…"
+---
+
+# Mechanism fidelity
+
+> **Anthropic docs reference:** This standard does not depend on a specific Anthropic surface — it is a bassclef discipline for verifying the substrate's own catalog claims hold end-to-end. The audit method applies to any bassclef rule, hook, skill, or standard regardless of Anthropic's hook surface evolution.
+
+## Sources read
+
+- ADR-035 — names the substrate-as-system foundational tenet that this standard's audit method verifies
+- `architecture/audits/2026-06-24-closeout.md` — bet 24c architect-review that missed this class; this standard's audit fills the lens-gap and method-gap
+- `chronicle/2026-06-27c-mechanism-fidelity-foundation-longrun.md` (in-flight; lands at WU-12 closeout) — three known instances of the class surfaced during /diagnose
+- `.claude/hooks/turn-prose-kiss-check.sh` (live SILENT-PASS example) — hook fires but reads from nonexistent path; falls back to 8 defaults
+- `.claude/hooks/adr-discipline-check.sh` (live DEAD-LETTER example) — hook file exists but not wired in any settings.json
+- `.claude/skills/build/SKILL.md` + `launch/SKILL.md` + `spec/SKILL.md` + `decompose/SKILL.md` (live METHODOLOGY-ONLY example) — procedure has no "read pinned ADRs" step despite rules saying ADR consultation is required
+- Michael Feathers — *Working Effectively with Legacy Code* (Prentice Hall 2004) — anchor for the substrate-as-system tenet
+- Kent Beck — *Test-Driven Development By Example* (Addison-Wesley 2002) — anchor for tests-pin-contracts
+
+## What this standard covers
+
+The audit method for verifying that every bassclef rule which names a mechanical enforcement mechanism actually has that mechanism wired, firing, and producing the stated effect end-to-end.
+
+Per @luminary michael-feathers — code without characterization tests is legacy code by definition. A bassclef rule that says "mechanism X enforces this discipline" without an end-to-end test of X is legacy code at the catalog-claim layer.
+
+This standard defines:
+- The class — "rule claims mechanism X enforces discipline; mechanism is missing, unwired, or fails silently"
+- The 7 classification labels
+- The scan method (per-rule)
+- The verification chain (5 steps)
+- The output format (markdown findings table)
+- The integration points (the `/audit-rule-mechanism-fidelity` skill that runs the audit; the cold-adopter harness check class that runs it per PR)
+
+## The class
+
+A rule asserts:
+
+> Mechanical enforcement: `<hook-name>.sh` fires at `<event>` matching `<matcher>` and BLOCKs `<condition>`.
+
+The class fires when one or more of these hold:
+
+| Label | What is broken | Example |
+|---|---|---|
+| `DEAD-LETTER` | Hook file exists but no settings.json entry wires it | `adr-discipline-check.sh` (live 2026-06-27) |
+| `UNWIRED` | Hook file missing entirely; rule references a nonexistent path | (none known today) |
+| `PATH-BROKEN` | Hook is wired but its internal path resolution fails under its install layout | `turn-prose-kiss-check.sh` (live 2026-06-27 — Class A) |
+| `SILENT-PASS` | Hook fires but produces no observable signal — fallback to defaults, advisory mode in chat, suppressed stderr | `turn-prose-kiss-check.sh` (same — Class B) |
+| `TEST-MISSING` | Hook works but no Tier 0 test pins its contract; future drift not caught | (audit to surface) |
+| `METHODOLOGY-ONLY` | Rule body claims mechanical enforcement; no hook exists; pure self-discipline | `/build` `/launch` `/spec` `/decompose` `/shape` SKILL procedures lack ADR-read step despite `iteration-bet-brief-completeness.md` requiring ADR cite |
+| `NOT-WIRED-BY-DESIGN-CI` | Hook lives on disk and is referenced from `.github/workflows/*.yml`; settings.json is not the right home for it | `pr-body-scrub-check.sh`, `pr-body-loop-discipline-check.sh` |
+| `NOT-WIRED-BY-DESIGN-LAUNCHD` | Hook is scheduled by macOS launchd (or cron); header comment names the scheduler; settings.json is not the right home | `auto-save-idle.sh` |
+| `NOT-WIRED-BY-DESIGN-LIB` | File is sourced by other hooks (library role); header comment says "sourced by"; settings.json is not the right home | `trace-helper.sh` |
+| `CLEAN` | All chain steps pass | most existing rules (audit will surface count) |
+
+## The 5-step verification chain
+
+For each rule that names a mechanism, run all five steps:
+
+```
+1. Hook file exists at the claimed path?
+2. Hook is wired in project settings.json OR user settings.json per its install-class declaration?
+3. Hook has a Tier 0 test that runs end-to-end (not just unit)?
+4. Hook's path resolution succeeds under its install class (operator | project | dual)?
+5. Smoke-test: install fresh under declared layout + run + assert the rule's claimed
+   block / scan / inject behavior is observable?
+```
+
+Step 5 is the dynamic verification step — the one goal 24c's static-classification audit method skipped. It is what catches `PATH-BROKEN` + `SILENT-PASS` classes that static checks pass over.
+
+## Scan method (per rule)
+
+Per rule file, extract mechanism claims via grep patterns:
+
+```
+"Mechanical enforcement", "hook BLOCKs", "BLOCK at",
+"fires at", "PreToolUse|PostToolUse|Stop|SessionStart|UserPromptSubmit",
+"<hook-name>.sh", "wired in settings"
+```
+
+Extract claimed mechanism (hook path, event, matcher) from the rule body. Apply the 5-step verification chain. Classify per the 10 labels.
+
+The shared helper `lib/mechanism-fidelity.sh` (lands in WU-3 of bet 2026-06-27c) implements:
+
+- `scan_rule_for_mechanism_claims <rule-path>` — extracts claims from rule body
+- `verify_hook_exists <claimed-path>` — step 1
+- `verify_hook_wired <hook-path>` — step 2
+- `verify_path_resolution <hook-path>` — step 4
+- `verify_hook_test_pins_contract <hook-path>` — step 3
+- `smoke_test_hook <hook-path> <fixture>` — step 5
+- `classify_hook_install_pattern <hook-name> [project-root]` — detects install pattern (ci|launchd|lib|standard); bet 29a WU-1
+- `classify_finding <rule-path> <verification-results>` — returns one of 10 labels (accepts `--install-pattern=N` to map DEAD-LETTER → NOT-WIRED-BY-DESIGN-{CI|LAUNCHD|LIB} when the hook correctly lives outside settings.json; bet 29a WU-1)
+
+The library is `tier: upstream` (bassclef-internal). The `/audit-rule-mechanism-fidelity` skill (WU-4) calls it; the cold-adopter harness `rule-mechanism-claim-fidelity` check class (WU-5) calls it on every PR.
+
+## Output format (findings table)
+
+A markdown table with one row per rule × mechanism claim:
+
+```markdown
+| Rule | Claimed mechanism | Classification | Resolution path |
+|---|---|---|---|
+| `.claude/rules/adr-discipline.md` | `adr-discipline-check.sh` fires on Edit/Write of architectural paths; requires ADR marker | DEAD-LETTER | Wire in `.claude/settings.json` PreToolUse |
+| `.claude/rules/operator-facing-prose.md` | `turn-prose-kiss-check.sh` strict mode BLOCKs on Stop | PATH-BROKEN + SILENT-PASS | Refactor to use `lib/hook-inject.sh` resolve-helpers + declare install-class: dual |
+| `.claude/rules/iteration-bet-brief-completeness.md` | brief MUST cite ADRs | METHODOLOGY-ONLY | Author hook OR amend /build /launch /spec /decompose /shape SKILLs to read ADRs |
+| `.claude/rules/state-schema-validation.md` | `state-validate.sh` BLOCKs on Edit/Write of state-spine paths | CLEAN | (per first audit run) |
+| ... |
+```
+
+Per-classification summary at top:
+
+```
+=== Classification summary ===
+CLEAN: N
+DEAD-LETTER: N
+UNWIRED: N
+PATH-BROKEN: N
+SILENT-PASS: N
+NOT-WIRED-BY-DESIGN-CI: N
+NOT-WIRED-BY-DESIGN-LAUNCHD: N
+NOT-WIRED-BY-DESIGN-LIB: N
+TEST-MISSING: N
+METHODOLOGY-ONLY: N
+```
+
+First audit run lands at `architecture/audits/2026-06-27-mechanism-fidelity.md` in WU-6 of bet 2026-06-27c.
+
+## When the audit runs
+
+Three triggers:
+
+1. **Operator-invoked** — `/audit-rule-mechanism-fidelity` skill (user_invocable: true) — operator runs ad-hoc when reviewing substrate state
+2. **Auto-fires at `/architect-review`** — the architect-review SKILL amendment (WU-9.5) makes this audit a mandatory procedure step; no architect-review ships without running it
+3. **Per-PR via cold-adopter harness** — the `rule-mechanism-claim-fidelity` check class (WU-5) fires on every PR touching `.claude/rules/*.md`, `.claude/hooks/*.sh`, `.claude/skills/*/SKILL.md`, `standards/*.md`; blocks PRs that introduce a new instance of the class without paired verification
+
+The three triggers together close the lens-gap (architect-review now includes verification) + the method-gap (audit runs end-to-end) + the per-PR drift gap (harness catches new instances at merge time).
+
+## Override
+
+Per-rule legitimate exception: rule explicitly marked METHODOLOGY-ONLY in its body (with stated reason — operator discretion required; mechanical layer not feasible; etc.) — audit reports METHODOLOGY-ONLY without flagging as defect.
+
+Per-PR override: `SKIP_MECHANISM_FIDELITY_HARNESS=1 <command>` (logged via trace-helper). Used only when a rule ships ahead of its mechanism by design (e.g., methodology layer in this PR; mechanical layer in next bet, with cross-reference cited in the rule body).
+
+## Anti-patterns
+
+### Static-only audit
+
+Counting hooks + classifying as wired-vs-unwired without running the hook end-to-end. INSTEAD: include the 5-step verification chain; step 5 is the dynamic test that catches PATH-BROKEN + SILENT-PASS.
+
+### Audit a single rule in isolation
+
+Hook silent-fail under install-class layout can only be detected by installing fresh under the declared layout. Auditing in the current install layout misses the failure. INSTEAD: cold-adopter harness check class installs each hook fresh per its declared install-class.
+
+### Treat findings as informational
+
+Findings without ticket filings allow the class to persist. INSTEAD: every DEAD-LETTER / PATH-BROKEN / SILENT-PASS / TEST-MISSING finding gets a `/promote substrate-defect` ticket per `.claude/rules/blocked-items.md`.
+
+### Ship a new rule with a mechanism claim that no hook exists for
+
+This creates the METHODOLOGY-ONLY class instance. INSTEAD: either ship the hook in the same PR (bootstrap-pair-discipline per `.claude/rules/bootstrap-pair-discipline.md`) OR mark the rule body explicitly METHODOLOGY-ONLY with rationale.
+
+## Composes with
+
+- `standards/architect-review-discipline.md` — universal architect-review framework calls this audit as a mandatory procedure step
+- `standards/cold-adopter-harness.md` — `rule-mechanism-claim-fidelity` check class fires per PR
+- `standards/hook-injection-discipline.md` + `standards/hook-install-class.md` — both inform the verification chain
+- `standards/bash-hook-safety.md` — defensive bash disciplines that hooks under audit must hold
+- `.claude/rules/bootstrap-pair-discipline.md` — paired ship discipline that this audit verifies post-merge
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD for new hooks; step 3 of the verification chain checks for test presence
+- `.claude/rules/blocked-items.md` — findings file `/promote substrate-defect` per the protocol
+- `.claude/skills/audit-rule-mechanism-fidelity/SKILL.md` (lands in WU-4 of bet 2026-06-27c) — operator-facing dispatch surface for this audit
+
+## Refs
+
+- ADR-035 — substrate-as-system tenet + hooks-as-steering-surfaces
+- bassclef-upstream#417 — umbrella tracking for bet 2026-06-27c
+- bassclef-upstream#320 — substrate-architect-review umbrella (bet 24c — the audit that missed this class)
+- `architecture/audits/2026-06-24-closeout.md` — bet 24c closeout doc
+- `architecture/audits/2026-06-27-mechanism-fidelity.md` (lands in WU-6) — first 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*
+- @luminary kent-beck — *Test-Driven Development By Example*
+- @luminary saltzer-schroeder — complete mediation (empirically verified)
+- @luminary tony-hoare — pre/postcondition (audit checks contract holds against implementation)
+- @luminary hyrum-wright — observable behavior becomes contract for adopters
+
+## Retirement condition
+
+This standard retires only if bassclef stops shipping rules that name mechanical enforcement. The classification labels may evolve (new classes surface as new failure shapes appear); the discipline of empirical verification at the catalog-claim layer persists.

package/dist/lite/standards/operator-private-discipline.md

@@ -0,0 +1,200 @@
+---
+tier: lite
+description: Operator-private substrate (canvases, audits, persona reviews, proposals, strategy, ephemeral content) lives in a separate private repo, not in the public bassclef/bassclef repo.
+---
+
+# Operator-private discipline
+
+Operator-private substrate (canvases, audits, persona reviews, proposals, strategy, ephemeral content) lives in a separate private repo, not in the public bassclef/bassclef repo. The public repo's `docs/operator-private/` directory is a placeholder with a tracked README; everything else is gitignored. Operator workflow symlinks the private repo's content into the public working directory.
+
+This standard documents the two-repo separation, the symlink workflow, the gitignore pattern, the commit-time repo selection, and the reference-leak discipline that keeps operator-private content out of public substrate.
+
+## Why two repos
+
+`.gitignore` alone is a single point of failure. If operator-private content lives only in gitignored paths on a local disk, disk crash + machine theft + accidental `rm -rf` all destroy operator-strategic substrate without recovery. The operator needs:
+
+- Content **gitignored from public bassclef/bassclef** so it never leaks to adopters
+- **Version-controlled + backed up** so changes are recoverable
+- **History-preserved** so deliberation evolution is auditable
+
+A separate private GitHub repo (`sunj-labs/bassclef-upstream`) provides all three. Standard git workflow on a private repo gives version control + GitHub backup + history.
+
+Per `bassclef#811`.
+
+## Two-repo layout
+
+```
+~/src/sunj-labs/
+├── bassclef/                          # public repo (operator's primary working directory)
+│   ├── docs/
+│   │   ├── operator-private/          # real directory; tracked README placeholder
+│   │   │   ├── README.md              # tracked (adopter-facing)
+│   │   │   ├── audits/                # symlink → ../../../bassclef-upstream/docs/operator-private/audits
+│   │   │   ├── canvases/              # symlink → ...
+│   │   │   ├── persona-reviews/       # symlink → ...
+│   │   │   ├── proposals/             # symlink → ...
+│   │   │   ├── strategy/              # symlink → ...
+│   │   │   └── ephemeral/             # symlink → ...
+│   │   ├── proposals/                 # public proposals only (operator-strategic ones live in private repo)
+│   │   └── ...
+│   └── ...
+└── bassclef-upstream/                  # private repo (operator cd's here when authoring private substrate)
+    └── docs/
+        └── operator-private/
+            ├── canvases/
+            ├── audits/
+            ├── persona-reviews/
+            ├── proposals/
+            ├── strategy/
+            └── ephemeral/
+                └── journals/
+```
+
+The symlink discipline is **per-subdirectory** (audits/, canvases/, etc.) rather than the parent directory. The parent `docs/operator-private/` stays as a real directory so the tracked README placeholder can live inside it without symlink resolution issues.
+
+## Repository naming
+
+`bassclef-upstream` matches the public `bassclef` name (which the public bassclef repo renames to per ADR-022). Forward-compatible: when bassclef → bassclef rename completes, both repo names stay aligned (`bassclef` + `bassclef-upstream`).
+
+## Gitignore pattern (public repo)
+
+```
+docs/operator-private/*
+!docs/operator-private/README.md
+```
+
+Ignores everything inside `docs/operator-private/` (including all subdirectory symlinks) except the README placeholder.
+
+## Symlink setup
+
+`scripts/operator-setup.sh` creates the per-subdirectory symlinks. The script is:
+
+- **Idempotent**: re-runs are safe; skips symlinks already pointing at correct targets
+- **Conditional**: no-op if `bassclef-upstream` isn't checked out at the expected sibling location (adopters can ignore the script entirely)
+- **Operator-only**: documented in `CONTRIBUTING.md` as an operator-specific setup step; adopters don't need to run it
+
+To set up symlinks (operator workflow):
+
+```bash
+cd ~/src/sunj-labs/bassclef
+bash scripts/operator-setup.sh
+```
+
+To verify symlinks point at the private repo:
+
+```bash
+ls -la docs/operator-private/
+```
+
+Each subdirectory should show as a symbolic link with a path under `bassclef-upstream/docs/operator-private/`.
+
+## Commit-time repo selection
+
+Operator's working directory determines which repo a commit lands in:
+
+| Authoring | Working directory | Commits land in |
+|---|---|---|
+| Public substrate (skills, hooks, rules, standards, ADRs, public proposals) | `~/src/sunj-labs/bassclef` | Public `bassclef` repo |
+| Operator-private substrate (canvases, audits, persona reviews, internal proposals, strategy, ephemeral) | `~/src/sunj-labs/bassclef-upstream` | Private `bassclef-upstream` repo |
+
+The symlink resolves transparently for reads from the public working directory, but commits should be authored in the repo that owns the content. If an operator edits an operator-private file from inside `bassclef/docs/operator-private/canvases/X.md`, the file system follows the symlink and the edit is actually written to `bassclef-upstream/docs/operator-private/canvases/X.md` — but `git status` in `bassclef/` will show no change (the file is gitignored there). To commit, `cd ~/src/sunj-labs/bassclef-upstream` first.
+
+## Reference-leak discipline
+
+Public substrate (skills, hooks, rules, standards, ADRs, public docs, README, CONTRIBUTING, public proposals) MUST NOT reference operator-private paths.
+
+Examples of leaks to avoid:
+
+- A skill body that cites `docs/operator-private/canvases/X.md` as required reading
+- An ADR that references a persona review file by path
+- A README that mentions specific operator-private artifacts by name
+- A CONTRIBUTING.md that links to `docs/operator-private/strategy/Y.md`
+
+Why this matters: adopters don't have `bassclef-upstream` checked out, so cited paths resolve to nothing (or to the empty `docs/operator-private/` directory). The citation creates a 404 from the adopter's perspective and erodes trust.
+
+The substrate-coherence CI Rule 4 (per `bassclef#739` and `bassclef#787`) lints PR bodies for operator-private path citations. A companion extension (filed separately) should extend Rule 4's surface to public substrate content (skills, hooks, rules, standards, ADRs, README, CONTRIBUTING).
+
+## Adopter experience
+
+Adopters cloning the public bassclef repo see:
+
+```
+bassclef/docs/operator-private/
+└── README.md
+```
+
+That's it. The README explains the directory exists for operator-private substrate (not adopter substrate) and points at `standards/operator-private-discipline.md` for the workflow detail.
+
+Adopters do not run `scripts/operator-setup.sh`. The script's conditional check (does `bassclef-upstream` exist at the sibling location?) makes it a no-op for adopters.
+
+## Substrate-coherence CI compatibility
+
+Rule 3 of bassclef#739 (operator-private path enforcement) lints filenames against operator-private subdirectory location. With the symlink workflow:
+
+- Operator's working tree: persona-review-shaped + canvas-shaped files exist at `docs/operator-private/<subdir>/*` (via symlink). Rule 3 sees them at the operator-private path → PASS.
+- Adopter's working tree: the same files don't exist locally (only README does). Rule 3 has nothing to lint → PASS.
+- PR adding a violating file at a public path (e.g., `docs/persona-reviews/new-review.md`): Rule 3 blocks → expected behavior.
+
+## /promote workflow gap (known limitation)
+
+The `/promote` skill currently files improvement tickets against bassclef/bassclef. Post-this-standard, operator-private improvement tickets may need to land in `bassclef-upstream` instead. The `/promote` skill needs target-repo discipline (`--repo private | public | both`) to distinguish.
+
+Tracked at bassclef#817 (separately filed). Until that ships, operator manually chooses target repo when invoking `/promote`.
+
+## Rationale for Pattern A (per-subdirectory symlinks, real parent directory)
+
+Considered Pattern B (parent `docs/operator-private/` is itself a symlink). Rejected because:
+
+- README placeholder can't live inside a symlink target if we want adopters to see only README (the symlink would resolve to the private repo's content for any reader who has bassclef-upstream cloned at the sibling location)
+- Adopter experience cleaner if `docs/operator-private/` is a real (mostly empty) directory with one tracked file
+
+Pattern A trade-off: operator-setup.sh has to manage N subdirectory symlinks instead of one. Acceptable cost for cleaner adopter experience + simpler tracked-file semantics.
+
+## Backup + recovery
+
+`bassclef-upstream` is a private GitHub repo. Standard git workflow gives:
+
+- **Off-machine backup**: every push to GitHub backs up content
+- **Recovery from disk loss**: `git clone` retrieves full history
+- **Version-controlled history**: every commit is recoverable; deleted content stays in git history
+- **Authentication**: standard GitHub access controls (private repo + operator-only collaborator list)
+
+Operator workflow:
+
+1. Author operator-private substrate in `~/src/sunj-labs/bassclef-upstream`
+2. Commit + push to private remote regularly (same cadence as public bassclef work)
+3. Disk loss recovery: `cd ~/src/sunj-labs && git clone https://github.com/sunj-labs/bassclef-upstream.git && cd bassclef && bash scripts/operator-setup.sh`
+
+Ephemeral content (journal entries, scratch notes, throwaway prompts, persona-brand substrate) lives at `bassclef-upstream/docs/operator-private/ephemeral/` — same repo, same backup, same recovery path. Per `bassclef#823`.
+
+## Relationship to other standards
+
+- `standards/operator-to-public-flow.md` — the deliberation → public-artifact sequence (Pattern 2)
+- `standards/pr-body-discipline.md` — Rule 4 scrub criteria (bassclef#787) compose with reference-leak discipline
+- `standards/operator-facing-prose-discipline.md` — operator-facing prose discipline (bassclef#790) applies to private substrate too
+- `.claude/rules/operator-facing-prose.md` — conversational rule that loads via additionalDirectories
+- `.claude/hooks/operator-private-path-check.sh` — Rule 3 mechanical enforcement (bassclef#739)
+- `.claude/hooks/pr-body-scrub-check.sh` — Rule 1 + Rule 4 mechanical enforcement (bassclef#739)
+
+## Override paths
+
+There is no override path for the two-repo separation itself. The operator can choose to keep some operator-private content in gitignored paths within the public repo (legacy pattern), but that loses backup + recovery + history.
+
+For specific exceptions (e.g., a single operator-private file the operator wants in the public repo for reasons), use commit footer `SKIP_OPERATOR_PRIVATE_PATH=1` (per Rule 3 documented override).
+
+## Surfaced in
+
+- /longrun 2026-06-01 Bet 1 closeout — operator surfaced concern that gitignore-only is a single point of failure for operator-private substrate. Filed bassclef#811.
+- /longrun 2026-06-01 bassclef#811 + bassclef#809 execution — this standard authored end-to-end.
+
+## Refs
+
+- bassclef#811 — parent ticket (this standard documents the implementation)
+- bassclef#823 — ephemeral content relocation tracking
+- bassclef#816 — operator-strategic proposals under operator-private (extends content scope)
+- bassclef#817 — /promote target-repo discipline (known limitation)
+- bassclef#739 — substrate-coherence CI (Rule 3 + Rule 4 enforcement surfaces)
+- bassclef#787 — PR-body scrub discipline (compose with reference-leak)
+- bassclef#790 — operator-facing-prose discipline (gloss + /kiss pass)
+- bassclef#769 — canvas-path discipline (grandparent)
+- bassclef#803 — persona-private path enforcement (sibling closed by Rule 3)

package/dist/lite/standards/operator-to-public-flow.md

@@ -0,0 +1,195 @@
+---
+tier: lite
+description: This standard documents the sequence by which operator-private deliberation (canvases, audits, persona reviews, internal proposals, strategy docs) produces public-facing artifacts (README, CONTRIBUTING, ADRs, public docs, skills, hooks, rules…
+---
+<!-- andon-allow: docs/operator-private/[a-z-]+/20[0-9][0-9]-[0-9]{2} -->
+
+# Operator-to-public flow
+
+This standard documents the sequence by which operator-private deliberation (canvases, audits, persona reviews, internal proposals, strategy docs) produces public-facing artifacts (README, CONTRIBUTING, ADRs, public docs, skills, hooks, rules, standards) without leaking operator-private content into the public surface.
+
+This is Pattern 2 from `bassclef#811`. Companion to `standards/operator-private-discipline.md`.
+
+## Why this flow exists
+
+Operator-private substrate captures deliberation: persona-altitude reviews, scoring matrices, leap-of-faith assumptions, alternative scenarios, strategic-pivot reasoning. Public substrate captures decisions: ADRs, standards, skills, hooks, rules, README, CONTRIBUTING.
+
+Naively writing public substrate "based on" operator-private substrate produces two failure modes:
+
+1. **Path citations leak**: public artifact cites `docs/operator-private/canvases/X.md` as evidence — adopter follows the citation + gets nothing (gitignored, no symlink).
+2. **Deliberation framing leaks**: public artifact reproduces leap-of-faith framing + persona-divergence analysis + strategic-pivot reasoning — adopter reads operator-strategic context instead of decision substance.
+
+Both fail the public surface: adopters see broken evidence trails + over-detailed strategic context that erodes trust.
+
+The flow below keeps deliberation in operator-private and decision substance in public.
+
+## The four-step sequence
+
+### Step 1 — Author private substrate in `bassclef-upstream`
+
+Operator works in `~/src/sunj-labs/bassclef-upstream` for all operator-strategic deliberation:
+
+- Canvases (lean-canvas, value-prop-canvas, chain-of-beliefs)
+- Audits (substrate audits, bootstrap audits)
+- Persona reviews (Sam, Jamie, Morgan — bounce risk, lock-in cost, leadership pitch tests)
+- Internal proposals (scoring matrices, tier rankings, draft pitches)
+- Strategy docs (locked decisions, growth-loop pivot reasoning)
+- Ephemeral content (LinkedIn drafts, scratch notes, throwaway prompts)
+
+Symlinks make these readable from the public `bassclef/docs/operator-private/` working directory, but commits land in `bassclef-upstream`.
+
+### Step 2 — Deliberation produces a decision
+
+Operator-strategic deliberation reaches a conclusion. The decision is concrete and stable: "Apache 2.0 license", "community-open lean", "Tier 0 = 5 luminaries (Garrett, Norman, Krug, Tufte, Fowler)", "growth-loop strategy not IP-protection".
+
+The decision is the load-bearing output. The deliberation is the scaffolding that produced it.
+
+### Step 3 — Author public artifact citing decision substance, not deliberation path
+
+Operator authors the public artifact (ADR, standard, skill, hook, rule, README, CONTRIBUTING, public proposal) in `~/src/sunj-labs/bassclef`. The public artifact:
+
+- States the decision (what we chose + the rationale that matters for adopters)
+- Cites public-tree evidence (other ADRs, standards, public commits, public PRs, public issues)
+- Does NOT cite operator-private paths (`docs/operator-private/canvases/X.md`)
+- Does NOT reproduce operator-strategic framing (leap-of-faith, canvas walk surfaced, persona divergence, riskiest assumption)
+
+Mechanical framing per `standards/pr-body-discipline.md` criteria 1 + 2:
+
+| Avoid | Use |
+|---|---|
+| "Per docs/operator-private/canvases/bassclef-public-launch-lean-canvas.md, growth-loop strategy preferred" | "Per locked strategic decision (2026-05-25): bassclef ships under growth-loop strategy" |
+| "Canvas walk surfaced LF1 (Morgan-as-gatekeeper riskiest assumption); Tier 1 quickstart shape addresses it" | "Tier 1 quickstart shape closes the 15-minute-to-first-PR adopter onboarding path" |
+| "Per persona divergence analysis between Jamie + Morgan, scope-pivot decision is..." | "Scope decision: ... (rationale: aligns with portfolio-operator audience commitment)" |
+
+### Step 4 — Cross-reference works via symlink for operator authoring
+
+When operator authors a public artifact and wants to reference an operator-private artifact for personal context (e.g., to look up exact framing from a canvas walk), the symlink in `bassclef/docs/operator-private/` resolves transparently. Operator reads the private artifact from their `bassclef` working directory without leaving it.
+
+Critical: reading is fine; citing the path in the public artifact is not. The symlink enables operator workflow; the reference-leak discipline keeps the public artifact clean.
+
+## When public substrate IS allowed to reference operator-private
+
+There are exactly two cases:
+
+### Case 1 — Companion standards in `standards/operator-*.md`
+
+This document and `standards/operator-private-discipline.md` reference operator-private substrate by NAME (not by file path) when documenting the workflow. Example: this standard mentions canvases + audits + persona reviews as content types that live in operator-private.
+
+That's allowed because:
+- The reference is to a content category, not a specific file
+- Adopters reading this standard learn what content type the operator keeps private (not what specific file's content)
+- The standard is itself operator-facing infrastructure documentation
+
+### Case 2 — Substrate-defect citations referencing prior private content
+
+When a substrate-defect ticket cites an operator-private artifact as the failure surface (e.g., bassclef#816 cites the WU-6 final-proposal review files), the citation reference is allowed if the citation:
+- Doesn't reproduce the operator-private content body
+- Cites the file as evidence-of-existence (not evidence-of-content)
+- Includes the substrate-coherence framing (the file lives at operator-private path; the ticket extends discipline to that surface)
+
+Pattern: "Per bassclef#816, persona-review files at `docs/operator-private/persona-reviews/*.md` need Rule 3 enforcement."
+
+Counter-pattern (not allowed): "Per Sam's review at `docs/operator-private/persona-reviews/2026-05-24c-final-proposal-sam.md`, the Tier 1 layering proposal needs X" — this cites operator-private content body via path.
+
+## Worked example — Tier 1 layering decision
+
+The Tier 1 layering decision (PR #804 + #812 + #813 + #814) followed this flow:
+
+### Step 1 — Private substrate
+
+Operator authored in `bassclef-upstream`:
+- `canvases/bassclef-public-launch-lean-canvas.md` (operator-strategic positioning)
+- `canvases/bassclef-public-launch-chain-of-beliefs.md` (leap-of-faith analysis)
+- `audits/2026-05-25-bassclef-audit-bootstrap.md` (pre-launch audit findings)
+- `audits/2026-05-25-bassclef-strategic-audit.md` (strategic audit)
+- `strategy/2026-05-25-locked-decisions.md` (Apache 2.0, community-open, Tier 0 luminaries)
+- `proposals/2026-05-24-tier-1-scoring-matrix.md` (73-skill + 32-hook + 45-rule scoring)
+- `proposals/2026-05-24-tier-1-ranking.md` (9 skills + 4 hooks + 3 rules + 2 architectural layers)
+- `proposals/2026-05-24-tier-0-draft.md` (Tier 0 pitch with ADR-flagged decisions)
+- `proposals/2026-05-24-tier-1-quickstart-shape.md` (Sam-altitude 15-min path)
+- `proposals/2026-05-24-tier-1-layering-proposal.md` (consolidated 9-section synthesis)
+- `persona-reviews/2026-05-24c-*-{sam,jamie,morgan}.md` (multi-altitude reviews)
+
+### Step 2 — Decisions reached
+
+- Tier 0 = 5 luminaries (Garrett + Norman + Krug + Tufte + Fowler)
+- Tier 1 = 9 skills + 4 hooks + 3 rules + 2 architectural-commitment layers (state spine + luminary catalog)
+- License = Apache 2.0
+- Business model lean = community-open
+- Audience anchor = portfolio operator
+
+### Step 3 — Public artifacts authored citing decision substance
+
+- `docs/proposals/2026-05-24-tier-1-quickstart-shape.md` (PR #812 — public, lists Tier 1 building blocks + 15-min path)
+- `docs/proposals/2026-05-24-tier-1-layering-proposal.md` (PR #814 — public, consolidates Tier 1 layering for adopters)
+- `docs/proposals/2026-05-24-tier-0-draft.md` (PR #813 — public, Tier 0 pitch + ADR-flagged decisions)
+- ADR-021 (anchor catalog selection)
+- ADR-022 (fresh-repo vs rename-in-place, pending operator decision)
+
+Public artifacts reference decisions + cite other public substrate (ADRs, PRs, standards). They do NOT cite the operator-private canvas walks, audit findings, or persona reviews by path.
+
+Per bassclef#816, the operator-strategic proposals at `docs/operator-private/proposals/` (scoring matrix, ranking, internal pitch drafts) stay private. The public Tier 1 layering proposal is a separately-authored adopter-facing artifact, not a publication of the private deliberation.
+
+### Step 4 — Cross-reference during authoring
+
+When authoring the public Tier 1 layering proposal, the operator can read the private scoring matrix + ranking from their `bassclef/docs/operator-private/proposals/` working directory (via symlink). The public artifact references the decision (9 + 4 + 3 + 2 Tier 1 surfaces), not the private deliberation path.
+
+## Anti-patterns
+
+### Anti-pattern 1 — Authoring public artifacts in private repo
+
+If the operator authors a public-facing artifact (e.g., README rewrite) inside `bassclef-upstream`, the artifact lands in the private repo + isn't visible to adopters. Confusing failure mode.
+
+Discipline: public artifacts always land in the public bassclef repo. Private repo holds only operator-private content.
+
+### Anti-pattern 2 — Authoring private artifacts in public repo
+
+If the operator authors a private artifact (e.g., a draft pitch) directly in `bassclef/docs/operator-private/<subdir>/`, the gitignore catches it (file is gitignored, not tracked). But subtle: the file lives on disk at the public repo's working directory + isn't backed up anywhere.
+
+Discipline: private artifacts always land in the private repo. The symlink lets you cd into a subdirectory that resolves through the symlink — and edits go to the private repo automatically. Verify via `git status` in `bassclef/` (no change visible) + `git status` in `bassclef-upstream/` (change visible at the subdir).
+
+### Anti-pattern 3 — Path citations in public substrate
+
+Already covered in `standards/pr-body-discipline.md` criterion 1. Public substrate (skills, hooks, rules, standards, ADRs, public docs, README, CONTRIBUTING, PR bodies) doesn't cite `docs/operator-private/<...>` paths. The path resolves to nothing for adopters.
+
+### Anti-pattern 4 — Reproducing private framing in public substrate
+
+Already covered in `standards/pr-body-discipline.md` criterion 2. Public substrate doesn't reproduce operator-strategic deliberation framing (leap-of-faith, persona divergence, canvas walk surfaced, riskiest assumption, strategic pivot reasoning). Public substrate states decisions + their adopter-facing rationale.
+
+## Mechanical enforcement
+
+Per `bassclef#739` substrate-coherence CI:
+
+- **Rule 3** (operator-private path enforcement) — blocks PRs adding persona-review-shaped, canvas-shaped, or proposal-shaped files outside `docs/operator-private/`
+- **Rule 4** (PR-body scrub) — blocks PR bodies containing operator-private path citations OR operator-strategic deliberation framing
+
+A companion extension (filed separately) extends Rule 4's surface from PR bodies to public substrate content (skills, hooks, rules, standards, ADRs, README, CONTRIBUTING). When that ships, mechanical enforcement covers the full public surface.
+
+## Relationship to other standards
+
+- `standards/operator-private-discipline.md` — companion (two-repo + symlink workflow detail)
+- `standards/pr-body-discipline.md` — Rule 4 scrub criteria
+- `standards/operator-facing-prose-discipline.md` — operator-facing prose discipline applies to both private and public
+- `.claude/rules/operator-facing-prose.md` — conversational rule
+
+## Override paths
+
+There is no override for the deliberation-to-public-artifact sequence. The flow is the discipline.
+
+For specific path-citation needs (e.g., a substrate-defect ticket that needs to name the violating private file by path as evidence), use the Case 2 framing above — cite as evidence-of-existence, not evidence-of-content.
+
+## Surfaced in
+
+- bassclef#811 implementation — this standard authored end-to-end as part of Part A.
+- bassclef#816 — the proposal relocation that motivated the file-classification gap.
+- Bet 1 closeout — the Tier 1 layering decision worked example.
+
+## Refs
+
+- bassclef#811 — parent ticket (this standard documents the Pattern 2 flow)
+- bassclef#816 — operator-strategic proposals under operator-private (the gap this flow closes)
+- bassclef#739 — substrate-coherence CI (mechanical enforcement)
+- bassclef#787 — PR-body scrub discipline (criteria source)
+- bassclef#790 — operator-facing-prose discipline (companion)
+- bassclef#769 — canvas-path discipline (grandparent)
+- bassclef#823 — ephemeral content relocation (companion)