@thebassclef/lite 0.1.3 → 1.0.0

package/substrate/standards/pluggable-luminaries.md

@@ -1,323 +0,0 @@
----
-tier: lite
-description: Each agent in bassclef has a default set of luminaries — thinkers whose principles guide its decisions.
----
-
-# Pluggable Luminaries
-
-Each agent in bassclef has a default set of luminaries — thinkers whose
-principles guide its decisions. App repos that inherit bassclef can
-customize which luminaries are active per agent, per phase, without editing
-bassclef agent definitions directly.
-
-Customization lives in `substrate.config.md`. Bassclef defaults are never
-modified. The merge is computed at runtime by the Orchestrator during boot.
-
----
-
-## File architecture (as of 2026-04-12)
-
-Luminary content lives in **per-luminary files** at `.claude/luminaries/[slug].md`,
-one file per thinker. Agent definitions (`.claude/agents/*.md`) reference
-luminaries by slug and keep a one-line signature; they do NOT duplicate the
-luminary's full content inline.
-
-**Why per-file**: Previously luminary content lived inline inside agent
-definitions, squeezed into whatever space the agent file could spare. This
-produced structural sparsity — Designer at 17 luminaries × 4 lines each
-meant every luminary was a name-drop. Three "data-heavy" prototype variants
-(Prater, Norman, Tufte dominants) blurred together because the luminaries
-themselves blurred. Per-file gives each thinker its own budget (40–80 lines),
-lets multiple agents share a single source of truth (Cockburn spans
-Architect, Builder, Shaper), and makes depth structurally enforceable via
-schema.
-
-**Depth bar** (see `.claude/luminaries/TEMPLATE.md` for full schema):
-
-| Depth | Requirements |
-|-------|-------------|
-| `full` | All schema sections populated — signature, 2–4 named methods, when to channel, stack translation, anti-patterns, worked example, sources, related luminaries. 40–80 lines. |
-| `stub` | Frontmatter + signature + core methods + sources minimum. Lighter entries for luminaries that are legitimate references but don't dominate iteration decisions. |
-
-**Signature distinctiveness test**: If you could swap a luminary's signature
-line for another luminary's and nothing would break, the signature is too
-generic. Rewrite. Garrett's "UX is about people" fails this; "Strategy →
-scope → structure → skeleton → surface — every UX has five planes, skip one
-and the next collapses" passes.
-
-**New luminary protocol**: Copy `TEMPLATE.md` → `[slug].md`. Populate to
-`full` depth if the luminary will dominate iteration decisions; `stub`
-otherwise. Add a one-line reference in each claiming agent's definition
-pointing at the slug.
-
----
-
-## Depth standard (as of 2026-04-12b)
-
-Every luminary file MUST satisfy:
-
-### Required for all depths (full + stub)
-
-1. **Frontmatter** — name, slug (kebab-case matching filename),
-   claimed_by (list of agents), primary_domain, depth.
-2. **Signature** — one to two sentences capturing the distinctive POV.
-   Must pass the **swap test**: if you substituted another luminary's
-   signature, would anything meaningfully change? If no, the signature
-   is too generic. Rewrite.
-3. **Core methods** — 2–4 named, operational methods. Each must be
-   a phrase the agent can invoke by name ("Apply ORCA", "Draw Walking
-   Skeleton"). Vague principles without names ("user-centered thinking")
-   don't count.
-4. **Sources** — primary sources only. Books, seminal talks, bassclef
-   articles by the luminary themselves. No third-party summaries or
-   Medium round-ups.
-
-### Additional for `full` depth
-
-5. **When to channel this luminary** — paragraph-level trigger
-   describing concrete conditions (domain, problem type, stakes) where
-   this POV dominates. Include "Do NOT channel for:" clause with
-   counter-cases.
-6. **Stack translation** — how the POV maps concretely to Next.js +
-   Prisma + React + TypeScript + Tailwind + our SDLC.
-7. **Anti-patterns it prevents** — 3–5 specific failure modes this
-   POV catches. Each must be concrete (not "bad design") and testable.
-8. **Worked example** — paragraph showing the POV applied to a
-   representative problem using our domain entities (Deal, Broker,
-   Seller, etc.).
-9. **Related luminaries** — 3–5 named relationships (complements,
-   contrasts, builds-on).
-
-### Distinctiveness enforcement
-
-When signatures fail the swap test, reject and rewrite. Common
-failures:
-
-| Generic signature (fails swap) | Distinctive signature (passes) |
-|---|---|
-| "UX is about people, not technology." | "Every user experience has five planes: strategy → scope → structure → skeleton → surface. Skip one and the next collapses." (Garrett) |
-| "Good design is simple." | "Material honesty. Resolve every seam. A product is finished when nothing can be removed without breaking it." (Ive) |
-| "Start with the user." | "Personas are precision tools — each a research-grounded behavioral archetype, not a fictional user." (Cooper) |
-
-### Who needs full vs stub
-
-**Full** — luminaries that regularly dominate iteration decisions or
-prototype variants. Priority list evolves with use; current full-depth
-list includes: Prater, Norman, Cooper, Garrett, Lupton, Walter, Tidwell,
-Ive, Rams, Tufte, Morville, Fowler, Evans, Beck, Gang of Four, Robert
-C. Martin, Simon Brown, plus 5–15 others who qualify.
-
-**Stub** — legitimate references that inform but rarely dominate:
-historical figures, field-specific specialists, tool/system-level
-references (Apple HIG, Conventional Commits, DORA Team, etc.).
-Frontmatter + signature + core methods + sources is the minimum bar.
-
-### Review cadence
-
-Luminary files should be reviewed when:
-- A new iteration selects them as primary_luminary (opportunity to
-  upgrade stub → full if used in anger)
-- A POA prototype sprint uses them and the decomposition reveals gaps
-- bassclef/standards changes affect how we describe stack translation
-
-No fixed review cadence; review is event-driven.
-
----
-
----
-
-## Schema
-
-Add a `luminaries` block to `substrate.config.md`:
-
-```markdown
-## Luminaries
-luminaries:
-  add:
-    designer: [Dieter Rams, Massimo Vignelli]
-    builder: [Kent Beck]
-  remove:
-    builder: [Gang of Four]
-  replace:
-    creative-director: [Apple HIG, Dieter Rams]
-```
-
-Agent names match the lowercase agent role: `designer`, `builder`,
-`architect`, `pm`, `shaper`, `reviewer`, `creative-director`, `deployer`,
-`closer`, `orchestrator`.
-
-### Operations
-
-| Operation | Meaning |
-|-----------|---------|
-| `add` | Bassclef defaults + these additional luminaries |
-| `remove` | Bassclef defaults minus these luminaries |
-| `replace` | Ignore bassclef defaults — use only these luminaries |
-
-Operations compose in order: `replace` wins if present, otherwise
-`add` and `remove` both apply to the bassclef defaults. A single
-agent can appear in `add` and `remove` simultaneously — the result is
-`(defaults + add) - remove`.
-
-If no `luminaries` section exists in `substrate.config.md`, bassclef
-defaults are used unchanged.
-
----
-
-## Per-phase overrides (advanced)
-
-An agent's luminary set can differ by phase:
-
-```markdown
-luminaries:
-  add:
-    designer:
-      elaboration: [Sophia Prater]
-      construction: [Apple HIG]
-```
-
-When phase-keyed entries are present, the flat form is not valid for that
-agent — use phase keys consistently for clarity. If an entry for a phase
-is not provided, bassclef defaults apply for that phase.
-
-Per-phase overrides support `add`, `remove`, and `replace` for each phase
-key. The top-level agent name cannot mix flat and phase-keyed forms in the
-same operation:
-
-```markdown
-# Valid — consistent phase keys
-luminaries:
-  add:
-    designer:
-      elaboration: [Sophia Prater]
-      construction: [Apple HIG]
-
-# Invalid — do not mix flat and phase-keyed
-luminaries:
-  add:
-    designer: [Sophia Prater]          # flat
-    designer.construction: [Apple HIG] # phase-keyed — not supported
-```
-
----
-
-## Merge algorithm
-
-The Orchestrator resolves the active luminary set for each agent during
-boot (step 1 of the boot sequence in `strategy/agent-choreography.md`).
-
-```
-function resolve_luminaries(agent, phase, config, bassclef_defaults):
-
-  if config.luminaries is empty:
-    return bassclef_defaults[agent]
-
-  base = bassclef_defaults[agent]
-
-  # Step 1: replace wins
-  if agent in config.luminaries.replace:
-    entries = config.luminaries.replace[agent]
-    if is_phase_keyed(entries):
-      base = entries[phase] if phase in entries else bassclef_defaults[agent]
-    else:
-      base = entries
-    # add/remove do not apply after replace
-    return base
-
-  # Step 2: add
-  if agent in config.luminaries.add:
-    entries = config.luminaries.add[agent]
-    additions = entries[phase] if is_phase_keyed(entries) else entries
-    base = base + additions
-
-  # Step 3: remove
-  if agent in config.luminaries.remove:
-    entries = config.luminaries.remove[agent]
-    removals = entries[phase] if is_phase_keyed(entries) else entries
-    base = [l for l in base if l not in removals]
-
-  return base
-```
-
-The bassclef defaults are the luminary lists defined in each agent
-definition file (`.claude/agents/{role}.md`). These are never modified by
-app-level config.
-
----
-
-## Validation
-
-The Orchestrator warns (does not block) on these conditions:
-
-| Condition | Warning |
-|-----------|---------|
-| A name in `remove` does not match any bassclef default for that agent | `WARN: remove lists "[Name]" for [agent] but it is not in bassclef defaults` |
-| A `replace` set is empty | `WARN: replace for [agent] is empty — agent will have no luminaries` |
-| A phase key in a per-phase override does not match a known phase | `WARN: phase key "[phase]" in luminaries config is not a recognized phase` |
-
-Warnings surface in the boot report. They do not block execution.
-
----
-
-## Boot report surface
-
-At boot (step 8 of `/autonomous start`), the Orchestrator reports the
-resolved luminary set per agent. See `strategy/agent-choreography.md`
-Section 1 for the boot report format.
-
-Format:
-
-```
-Active luminaries:
-  Designer:          Don Norman, Sophia Prater, Apple HIG (+2 from config)
-  Builder:           Martin Fowler, SOLID (-GoF, +Kent Beck from config)
-  Creative Director: Apple HIG, Dieter Rams (replaced from config)
-  Architect:         [bassclef defaults]
-```
-
-Agents using bassclef defaults without modification are shown with
-`[bassclef defaults]` — do not list every luminary for every agent at
-boot. Only show the delta annotation for agents that have overrides.
-
----
-
-## Rationale
-
-Luminaries are not decorative. They determine which principles the agent
-applies when faced with trade-offs. A CRUD-heavy app repo may find GoF
-patterns too heavy for the Builder. A brand-focused creative sprint may
-want Dieter Rams over whatever bassclef defaults. A regulated industry
-repo may want explicit risk-oriented luminaries in the Architect slot.
-
-Bassclef cannot anticipate every project's aesthetic, technical, and
-domain needs. This standard makes the luminary layer composable — app
-repos add their perspective without forking agent definitions.
-
-The merge model (add/remove/replace) was chosen over a full override
-because:
-- Most repos want to tune, not replace, bassclef judgment
-- `replace` exists as an escape hatch for radically different contexts
-- Bassclef defaults remain the stable base — upgrades propagate to all
-  repos that don't override the changed luminary
-
----
-
-## Example: app repo configuration
-
-```markdown
-## Luminaries
-luminaries:
-  add:
-    designer: [Dieter Rams, Massimo Vignelli]
-    builder: [Kent Beck]
-  remove:
-    builder: [Gang of Four]
-  replace:
-    creative-director: [Apple HIG, Dieter Rams]
-```
-
-This configuration:
-- Adds two visual-system thinkers to the Designer for a brand-heavy product
-- Adds Kent Beck's TDD emphasis to the Builder
-- Removes GoF from the Builder (this is a simple CRUD app — patterns overhead is not worth it)
-- Replaces Creative Director's entire luminary set with Apple HIG + Dieter Rams (full override for a minimalist product direction)

package/substrate/standards/pr-body-discipline.md

@@ -1,115 +0,0 @@
----
-tier: lite
-description: PR bodies are public substrate. When bassclef (and bassclef) ship public, PR bodies become permanent public history visible to every adopter, contributor, and reader who follows a commit back to its PR. This standard documents the scrub discipline…
----
-<!-- andon-allow: docs/operator-private/[a-z-]+/20[0-9][0-9]-[0-9]{2} -->
-
-# PR-body discipline — scrub before push
-
-PR bodies are public substrate. When bassclef (and bassclef) ship public, PR bodies become permanent public history visible to every adopter, contributor, and reader who follows a commit back to its PR. This standard documents the scrub discipline that applies to every PR body before push.
-
-## Scope
-
-Every PR opened against bassclef's main branch, regardless of authoring path:
-
-- Operator-direct authoring via `gh pr create`
-- Skill-authored PRs from /longrun, /sprint, /autonomous, /build, /promote, and any future PR-authoring skill
-- Agent-authored PRs in interactive sessions
-
-The discipline applies BEFORE push, not after merge. A PR body that lands public is harder to scrub than a PR body that gets revised before push.
-
-## Three scrub criteria
-
-### Criterion 1 — No operator-private path citations
-
-PR body refs and inline citations must not reference paths under `docs/operator-private/*`. Those paths are gitignored; citations point at files invisible to public readers. The citation tells the reader to consult evidence they cannot access — worse than not citing at all.
-
-Where the PR genuinely needs to cite a private path for completeness, use stub framing:
-
-| Avoid | Use |
-|---|---|
-| `per docs/operator-private/strategy/2026-05-25-locked-decisions.md` | `per internal strategic decision` |
-| `canvas at docs/operator-private/canvases/bassclef-public-launch-lean-canvas.md surfaced X` | `internal canvas walk surfaced X` |
-| `audit finding F-D9.1 at docs/operator-private/audits/2026-05-25-...md` | `audit finding F-D9.1 (audit HIGH)` |
-
-The stub preserves the substantive claim (an internal decision happened; a canvas walk surfaced something; an audit produced a finding) without exposing the specific operator-private path.
-
-### Criterion 2 — No operator-strategic deliberation as PR justification
-
-PR body justification frames mechanically: what the PR does + which acceptance criterion it closes + which downstream work it unblocks. Not: why the operator decided what they decided + the strategic-pivot reasoning + the alternatives considered.
-
-Specifically scrub:
-
-- Strategic pivot reasoning (e.g., "IP-protection-vs-growth-loop", "Tier 1 selection trade-offs")
-- Leap-of-faith framing (e.g., "LF1 Morgan-as-gatekeeper riskiest assumption analysis")
-- Canvas-walk findings exposition (the canvas surfaces what was found; the PR ships the mechanical change, not the canvas analysis)
-- Audit-finding internal reasoning (cite the finding number + the mechanical fix; don't re-expose the audit analysis)
-- Persona-divergence analysis (operator-strategic reasoning belongs in canvas/audit, not PR)
-
-Mechanical framing examples:
-
-| Avoid | Use |
-|---|---|
-| "Why now: the canvas-walk surfaced that ADR-021's framing contradicts the operator's locked growth-loop pivot. The canvas Revenue Streams box names HashiCorp-pattern downstream commercialization paths as option preserved, not roadmap committed — explicitly NOT an IP-protection play." | "Why now: amends language to reflect locked decision per 2026-05-25 strategic call." |
-| "Closes F-D9.1 (audit HIGH from /lean-canvas walk; Jamie reads the README hedge in 'Why this exists' as load-bearing weak signal; Sam adopts 'personal project that grew' mental model)" | "Closes audit finding F-D9.1 (README hedges audience)." |
-
-The reader of the public PR sees what changed + which acceptance criterion it closes. They don't see the operator's strategic deliberation; that deliberation lives in operator-private substrate where it belongs.
-
-### Criterion 3 — Plain-language gloss + /kiss pass per bassclef#790
-
-Apply the gloss-at-first-mention rule per `standards/operator-facing-prose-discipline.md` to all shorthand referenced in the PR body. Apply /kiss vocabulary substitution per `.claude/rules/plain-english-discipline.md` to remove bassclef-internal compound terms.
-
-This criterion composes with criteria 1 and 2: the scrub passes BOTH the operator-private check AND the plain-language check.
-
-## Scrub workflow
-
-Before `gh pr create` or `gh pr edit`:
-
-1. **Read the drafted PR body** as if reading it for the first time as a public adopter
-2. **Apply Criterion 1** — search for `docs/operator-private/` substrings; replace with stub framing or remove
-3. **Apply Criterion 2** — identify strategic-deliberation paragraphs; replace with mechanical framing
-4. **Apply Criterion 3** — gloss + /kiss pass per bassclef#790
-5. **Push the scrubbed body**
-
-The scrub is part of the same authoring cycle, not a separate review pass.
-
-## What this discipline does NOT require
-
-- **Scrubbing commit messages.** Commit messages are also public history but follow `commit-conventions.md` separately. Operator-private path citations in commit messages should also be avoided, but PR-body scrub is the primary surface this standard covers.
-- **Scrubbing operator-private files themselves.** Files under `docs/operator-private/*` stay as-is; they're gitignored. The scrub applies to PR bodies that reference them.
-- **Hiding the existence of operator-private work.** PR bodies can say "internal canvas walk produced this change" — what they can't do is cite the specific path.
-
-## Enforcement layers
-
-| Layer | Mechanism | Status |
-|---|---|---|
-| Methodology | This standard + `.claude/rules/operator-facing-prose.md` (bassclef#790 sibling rule) | Loaded into every session via `additionalDirectories` |
-| Skill-level | /longrun, /sprint, /autonomous SKILL.md cite this standard + run scrub before PR push | Lands in WU-4 + WU-5 of /longrun discipline-as-substrate (2026-05-30) |
-| Authoring discipline | Operator + agent self-scrub before push | Methodology-level |
-| Mechanical | bassclef#739 (substrate-coherence CI) extension lints PR bodies for `docs/operator-private/*` citations | Deferred — methodology-first |
-| /kiss PR-body hook | Advisory today; bassclef#786 decides hard-block vs advisory-with-skill-discipline | Pending operator decision |
-
-## Why this discipline matters
-
-The bassclef launch promise: "operators get a working methodology they can apply to their own products." PR bodies are part of the public substrate adopters read. If PRs cite operator-private paths and expose operator-strategic deliberation, three failure modes:
-
-1. **Adopter encounters broken citations.** "Per docs/operator-private/strategy/..." — adopter clicks through, finds nothing, loses trust in citation discipline elsewhere
-2. **Operator-private strategic context becomes public via PR-body archaeology.** Strategic pivots, leap-of-faith assumptions, alternative scenarios all leak via PR body history even though the source canvas is operator-private
-3. **PR review noise.** Reviewers read multi-paragraph strategic exposition when they need to evaluate a 3-line mechanical change
-
-Scrub discipline at push closes all three.
-
-## Surfaced in
-
-- PR #773 (ADR-021 amendment) — operator caught operator-private path citations + multi-paragraph strategic-pivot exposition in public PR body before merge. Operator manually scrubbed before merging.
-- Pattern recurs across /longrun-authored PRs from 2026-05-29 session; backlog: review prior PR bodies on bassclef for similar leakage.
-
-## Refs
-
-- bassclef#787 — parent ticket
-- bassclef#769 — canvas-path discipline (same principle for canvas file location)
-- bassclef#790 — operator-facing-prose discipline (gloss + /kiss pass; composes with this standard)
-- bassclef#786 — /kiss PR-body hook enforcement decision (mechanical layer for criterion 3)
-- bassclef#739 — substrate-coherence CI (extension surface for mechanical lint)
-- `.claude/rules/plain-english-discipline.md` — master plain-English rule
-- `standards/operator-facing-prose-discipline.md` — gloss rule + /kiss pass on SKILL.md edits

package/substrate/standards/preview-state-schema.md

@@ -1,189 +0,0 @@
----
-tier: lite
-description: docs/preview-state/<slug>.yml is the session-spanning state file for each /preview cycle.
----
-
-# Preview-state Schema
-
-`docs/preview-state/<slug>.yml` is the **session-spanning state file**
-for each `/preview` cycle. One per slug; persists across `/preview quick`
-→ `/preview light` → `/preview medium` escalations and across operator
-sessions. Read + written by every skill in the preview chain
-(`/preview`, `/luminary`, `/prototype-variants`, `/prototype-gallery`,
-`/ux-migration`).
-
-## Why this exists
-
-Without persistent state, the preview chain has no memory between
-operator commands. Operator runs `/preview quick "X"` Monday, picks
-variant B, runs `/preview light base=variant-B` Tuesday — the chain
-needs to know:
-- Which variants exist now
-- Which variant the operator picked
-- What luminaries have been tried (for divergence)
-- What scope was rejected (for the rejection-history → next-attempt feedback loop)
-- Whether we're awaiting a pick, escalating, building, or shipped
-
-Stuffing this into the operator's head doesn't survive context loss.
-Stuffing it into chronicles doesn't survive cross-session reads. A
-typed YAML file at `docs/preview-state/<slug>.yml` does both.
-
-## Schema
-
-YAML format (not Markdown — preview state is structured, not narrative).
-
-### Required fields
-
-```yaml
-slug: <kebab-case-identifier>
-created: <ISO 8601 UTC timestamp>
-current_tier: <pending | quick | light | medium | full>
-status: <pending | awaiting-pick | escalating | migrating | shipped | reset>
-current_variants: [<variant-slug>, ...]   # variants live now (post-current-run)
-luminaries_used: [<name>, ...]            # cumulative across all runs (drives divergence)
-identity_ref: <path/to/design/identity/X.md or null>
-escalation_history: []                    # populated by tier-escalation
-rejection_history: []                     # populated by /preview reset
-```
-
-### Optional fields
-
-```yaml
-selected_variant: <variant-slug or null>  # set on operator pick
-last_run_at: <ISO 8601 UTC>               # bumped per /preview invocation
-notes: <free-form prose, multiline OK>    # operator scratchpad
-```
-
-### Status values (state machine)
-
-| Status | Meaning | Set by |
-|--------|---------|--------|
-| `pending` | New cycle, no variants built yet | `ps_create` |
-| `awaiting-pick` | Variants live at URL, operator hasn't picked | end of `/preview <tier>` |
-| `escalating` | Operator picked + escalation in flight | mid-`/preview` when `base=` set |
-| `migrating` | `/ux-migration` in flight (medium tier) | start of `/ux-migration` step |
-| `shipped` | `/ux-migration` produced build-ready output AND operator approved | end of `/ux-migration` |
-| `reset` | Variants archived; rejection_history populated; awaiting next attempt | `/preview reset <slug>` |
-
-### History entries
-
-`escalation_history` entries:
-
-```yaml
-escalation_history:
-  - from: quick
-    to: light
-    base: variant-b-cooper
-    pick_reason: "goal-flow surfaces 'next deal' immediately"
-    at: 2026-04-25T10:30Z
-```
-
-`rejection_history` entries (populated by `/preview reset`):
-
-```yaml
-rejection_history:
-  - tier_when_rejected: medium
-    variants_archived: [variant-a-tufte, variant-b-cooper, variant-c-prater]
-    rejection_reason: "all three failed the 'broker can scan in 10s' test"
-    at: 2026-04-25T14:00Z
-```
-
-`rejection_reason` is the highest-leverage signal in the file — it
-feeds the next `/preview` attempt as input ("what didn't work").
-
-## Lifecycle
-
-```
-[ps_create]                         status: pending,    no variants
-   │
-   ↓ /preview quick → builds variants
-[after build]                       status: awaiting-pick, variants in current_variants[]
-   │
-   ↓ Operator picks (sets selected_variant)
-   │
-   ├─ Escalate: /preview light base=<picked>
-   │     status: escalating → awaiting-pick (after build)
-   │     escalation_history += entry
-   │
-   ├─ Migrate: /preview medium → /ux-migration
-   │     status: migrating → shipped
-   │
-   └─ Reject all: /preview reset <slug> --reason "..."
-         status: reset
-         rejection_history += entry
-         current_variants archived to docs/prototypes/archive/<slug>/
-         next /preview <tier> reads rejection_history as input
-```
-
-## Operations
-
-The accessor lib `lib/preview-state.sh` exposes:
-
-| Operation | Function | Purpose |
-|-----------|----------|---------|
-| Create | `ps_create <slug>` | Initialize new file with defaults |
-| Read field | `ps_get <slug> <field>` | Scalar fields only (MVP) |
-| Set field | `ps_set <slug> <field> <value>` | Scalar fields only (MVP) |
-| Status | `ps_status <slug>` | Convenience for `ps_get <slug> status` |
-| List | `ps_list` | All known slugs |
-| Archive | `ps_archive <slug>` | Move to `archive/` (timestamped) — used by `/preview kill` |
-| Reset | `ps_reset <slug> <reason>` | Archive variants, populate rejection_history, status: reset |
-| Kill | `ps_kill <slug>` | Hard-archive entire state (rare; requires --confirm at skill level) |
-
-Multi-line / list field manipulation (e.g., appending to
-`current_variants` or `escalation_history`) is added by the consuming
-skill (`/preview` itself) since the shape is operation-specific. The
-lib provides primitives; composition lives in skills.
-
-## Distinction from related artifacts
-
-- **Iteration goal**: scope contract for build work; preview-state is
-  the runtime state of the `/preview` cycle that produced the variants
-- **Stack manifest**: per-bet branch coordination; preview-state is
-  per-slug (one preview cycle = one slug, may span multiple bets)
-- **Whereami**: project-level snapshot; preview-state is cycle-level
-- **Chronicle**: retrospective narrative; preview-state is current state
-
-## Reset is not erasure
-
-`/preview reset` archives variants + records rejection rationale +
-restarts at quick. The rejection_history is the **most valuable signal**
-in the schema — it carries forward "what didn't work" as input to the
-next attempt. Erasing it means re-running the same dead-ends.
-
-Hard erasure is `/preview kill <slug> --confirm`, rare. Use case:
-abandoned product, slug being retired permanently. Hard kill empties
-all history.
-
-## Storage location
-
-`docs/preview-state/<slug>.yml` — one file per active slug.
-`docs/preview-state/archive/<slug>-<timestamp>.yml` — archived
-state-files (post-`ps_archive` or `ps_kill`).
-
-`docs/preview-state/` is git-tracked (durable across sandbox teardown
-per `mobile-ephemeral-session.md`). Schema lives in this standard;
-template lives at `templates/preview-state.yml`.
-
-## Relationship to other standards
-
-- `standards/whereami-schema.md` — sibling state artifact at project level
-- `standards/branch-stacking.md` — preview-state is per-slug; stack
-  manifests are per-bet
-- `standards/artifact-composition.md` — preview-state cross-references
-  bet (consumed by /ux-migration in medium tier) but is not a child of bet
-- `lib/preview-state.sh` (Phase A WS-1) — the typed accessor
-
-## Scrutiny
-
-This standard meets the bar for bassclef inclusion because:
-
-1. `/preview` (Phase B WS-9) consumes it as primary state
-2. `/ux-migration` (Phase D WS-19) consumes `selected_variant` +
-   `current_tier` to gate Construction kickoff
-3. `lib/preview-state.sh` is already in bassclef (WS-1) — schema is
-   the consumer-facing spec for the lib
-4. Multi-session resumability is the load-bearing property; without
-   the schema, resumability is per-slug operator memory
-
-Without all four hooks, this standard would be premature documentation.