@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/rules/session-artifacts.md

@@ -0,0 +1,236 @@
+---
+tier: lite
+globs: ["*"]
+description: Session artifacts — chronicle + journal entries at every phase transition and session end
+---
+
+In ALL configurations (operator-gated, orchestrator-gated, sequential, parallel), these artifacts are mandatory.
+They fire regardless of whether /autonomous is active.
+
+## Bassclef-side note — telemetry is local-only (bassclef#1205)
+
+When this rule fires INSIDE bassclef itself (not adopter repos):
+chronicles and state markers are written but NOT git-tracked. The paths
+`chronicle/` and `state/markers/` are gitignored in bassclef's repo
+per bassclef#1205. Iteration telemetry stays on the operator machine
+and is destined for bassclef-upstream long-term per memory
+`project_bassclef_private_to_bassclef_upstream`.
+
+INSTEAD of pushing chronicles + markers to bassclef-public: write
+them locally for operator continuity, commit only artifacts that
+belong in the public substrate (skills, rules, hooks, standards,
+ADRs). The brand-team Google Doc push (per the journal step below)
+preserves shareable content without coupling bassclef's git history
+to specific adopter sessions.
+
+This applies to bassclef's own repo only; adopter repos keep
+chronicles + markers tracked per their own configuration.
+
+## Backfill before current (MUST — applies to all artifacts below)
+
+Before writing ANY session artifact (chronicle, journal entry, release notes):
+1. Check when the last entry was written
+2. Check how many sessions/commits/days are missing since then
+3. If there are gaps: backfill them FIRST, in chronological order (oldest first)
+4. THEN write the current session's artifact
+
+This prevents out-of-order content in append-only destinations (Google Docs)
+and ensures no session is silently skipped.
+
+## Chronicle (MUST — every phase transition + session end)
+
+Before ending any session or completing any phase transition:
+1. Check: when was the last chronicle entry? How many commits since?
+2. If ≥3 commits since last entry: backfill the missing chronicle(s) FIRST
+3. Then write the current session's chronicle
+4. Chronicle location (per `standards/project-directory-layout.md`):
+   - App repos: `docs/chronicle/`
+   - Bassclef: `chronicle/` (root level)
+   - If the directory doesn't exist, create it per the standard.
+5. **Use the bassclef template** — `templates/chronicle-template.md`.
+   Do NOT invent ad-hoc section structures for "narrative closeouts" or
+   similar shapes. The /chronicle and /session-end SKILLs both reference
+   this template; ad-hoc chronicles silently drop the Gate Evidence
+   section (bassclef#298 root cause).
+6. **Populate the Gate Evidence section** — MUST, not optional. This
+   is the authoritative input for the 5-session gate-compliance counter.
+   Auto-populate script is in the template. Skipping it produces the
+   "0% compliance / no data" failure mode that pre-commit-gate.sh now
+   blocks mechanically (bassclef#298). Override only if you have an
+   explicit valid `n/a` reason per `standards/sdlc-compliance.md`
+   §"Gate skip justifications".
+7. Verify the file exists after writing AND `grep -qiE "^## Gate (E|e)vidence"`
+   confirms the section is present.
+
+## journal entries (SHOULD — session start + every notable decision or handoff)
+
+### At session start (SHOULD — backfill before new work)
+
+Before starting any new work, check for journal entry gaps:
+1. Read the most recent draft in `docs/operator-private/journals/`
+2. Read chronicles since that draft date
+3. If any session produced a notable decision, trade-off, or insight:
+   backfill drafts NOW, oldest first, push to Google Doc
+4. Then proceed with session work
+
+This fires at session start, not just session end, because session-end
+is where drafts get dropped — the agent runs out of context, the hook
+times out, or the session dies. Catching it at the START of the next
+session is the safety net.
+
+### At session end and handoffs
+
+At every role handoff, phase transition, or session end, ask:
+"Did this session/phase/handoff produce a notable decision, trade-off,
+or insight worth sharing?"
+
+If yes:
+1. Check for gaps: when was the last journal entry? Are there missed
+   sessions that owed drafts? Backfill those FIRST, oldest to newest.
+2. Create docs/operator-private/journals/ if it doesn't exist
+3. Write draft to docs/operator-private/journals/YYYY-MM-DD.md
+4. Push to Google Doc — push in chronological order (oldest first):
+   Read the Google Doc ID from `substrate.config.md` field `journal_doc_id`.
+   If not configured there, check project memory for the doc ID.
+   If neither exists, skip the push and keep drafts local in docs/operator-private/journals/.
+   When configured — prefer `--dir` for batch pushes (script sorts by filename):
+   npx tsx ~/src/sunj-labs/poa/scripts/push-to-gdoc.ts --dir [drafts dir] --doc-id [ID from substrate.config.md]
+   For single new draft:
+   npx tsx ~/src/sunj-labs/poa/scripts/push-to-gdoc.ts --file [draft path] --doc-id [ID from substrate.config.md]
+   To fix out-of-order doc (clear + re-push sorted):
+   npx tsx ~/src/sunj-labs/poa/scripts/push-to-gdoc.ts --dir [drafts dir] --replace --doc-id [ID from substrate.config.md]
+5. Verify both the local file and Google Doc push succeeded
+
+High-value moments for journal entries:
+- Scope kills (Shaper cutting features)
+- Architecture choices (Architect choosing boring tech)
+- Process insights (what broke, what worked, what surprised)
+- Design pushback (Designer vs PM)
+- Quantified results (N agents, M minutes, K artifacts)
+
+Every draft file MUST include an **audience recommendations table**:
+
+| Post | Primary audience | Hook strength | Publish priority |
+|------|-----------------|--------------|-----------------|
+
+Target audiences: PE partners, executive search leaders, board-level
+operators, CPTOs, technical founders, eng leaders/managers.
+Rate hook strength (weak/medium/strong/very strong/strongest).
+Recommend a publish sequence with rationale.
+Note overlapping posts and recommend which to publish vs hold.
+
+## Wiki-as-we-go discipline (SHOULD — at /longrun closeout, per bassclef#1208)
+
+At every `/longrun closeout`, ask:
+
+> Did this run produce material surface changes that need a wiki refresh?
+
+Discriminator list — any YES means wiki-refresh is owed:
+
+- New, renamed, or retired skill
+- New, renamed, or retired hook
+- New, renamed, or retired rule
+- New, renamed, or retired standard or ADR
+- Changes to `/onboard-repo` Phase 2.x discovery surfaces
+- New entries in `standards/bassclef-internal-jargon.md` (wordlist amendments)
+- New entries in `standards/bassclef-source-consumers.json` (anonymizer registry)
+
+If yes, either:
+
+1. **Add wiki edits to the closeout PR** when the change is small and ships in the same window. Wiki repo is separate; commit + push the wiki-side changes with a cross-ref to the bassclef PR, and note the wiki commit hash in the closeout PR body.
+2. **File a wiki-refresh follow-on ticket** when wiki changes are larger or need separate review. The ticket cites the bassclef PR(s) that introduced the substrate change and the wiki pages that need updating.
+
+If no, note "no wiki refresh owed" in the closeout chronicle so a future reader sees the question was asked.
+
+INSTEAD of letting the wiki drift quietly: ask the discriminator question at every closeout. The wiki is the cold-adopter front door; drift there is the most operator-visible failure mode.
+
+## Session-rescue + memory-proposal (MUST — abrupt stop safety net)
+
+When the Stop hook fires with unfinished MUST-tier obligations,
+`.claude/hooks/session-end.sh` writes a
+`docs/deferred-actions/<ts>-session-rescue.md` entry automatically.
+The next session surfaces it as `BLOCKED: deferred-action` via
+`60-deferred-actions.sh` and resolves per the entry's Command section.
+
+### What the hook checks
+
+Two signals trigger a rescue write (bassclef #239 hardening, 2026-04-21):
+
+1. **Chronicle freshness** — at least one file in `chronicle/` or
+   `docs/chronicle/` has been written or modified within the last 24
+   hours. This is **session-relative**, not UTC-calendar-date-relative:
+   a chronicle dated yesterday written at 23:50 UTC still satisfies
+   the obligation when the next Stop fires at 00:10 the following day.
+2. **Clean working tree** — `git status --porcelain -u` returns empty,
+   OR the only uncommitted paths are session-rescue entries the hook
+   itself wrote on a prior firing (self-output suppression). Real
+   content (any non-rescue path) still fires rescue.
+
+Both signals together close the self-amplifying loop that prior
+shapes produced (UTC calendar-date check + rescue-entry counting as
+uncommitted work → auto-save → Stop → rescue → loop; see
+`chronicle/2026-04-21-session-rescue-loop.md`).
+
+This is additive to the obligations above — chronicle + journal entries
+continue to be first-line duties. Rescue is the safety net for cases
+where those weren't completed (context exhausted, OS interruption,
+sandbox teardown, explicit abort).
+
+### Memory proposals from ephemeral sessions
+
+Mobile and cloud-web sessions cannot write to
+`~/.claude/projects/.../memory/` — the operator's real home is
+unreachable from the sandbox. When such a session identifies a memory
+entry worth adding:
+
+1. Copy `templates/memory-proposal-template.md` to
+   `docs/deferred-actions/<ts>-memory-<topic-slug>.md`
+2. Fill in the target path, proposed frontmatter + body, MEMORY.md
+   index line
+3. Commit with the session's normal artifact flow
+
+Next desktop session sees it as `BLOCKED: deferred-action` (requires
+`memory-write` capability), reviews, applies verbatim or edits first,
+and `git mv`'s to `completed/` per the deferred-actions protocol.
+
+See `.claude/rules/deferred-actions.md` for the full lifecycle.
+
+## Cloud and degraded environments
+
+In cloud (Claude Code web), CI runners, and fresh clones, the Stop hook
+may not fire or may be killed before completing. This is not an excuse
+to skip artifacts — it is a reason to be proactive.
+
+When operating in a cloud or degraded environment:
+
+1. **Do not wait for hooks** — invoke /session-end explicitly before ending
+   the session.
+
+   INSTEAD of assuming the Stop hook will fire: type `/session-end`
+   yourself when the session is at a natural close. Hooks are unreliable
+   in cloud / ephemeral / CI environments.
+2. **Must tier first** — write the chronicle and commit locally before
+   attempting any network operation (push, Google Doc). Network may not
+   be available or may timeout.
+3. **Journal-entry Google Doc push** — requires a service account key that is
+   not available in cloud. Write the draft to `docs/operator-private/journals/` and
+   skip the push step. Note "push pending — service account unavailable"
+   in the draft frontmatter.
+4. **Stop hook timeout** — if the app repo's `settings.json` has a timeout
+   on the Stop hook, it MUST be at least 30 seconds (see session-end SKILL.md).
+   A 5-second timeout will kill `git push` silently.
+
+   INSTEAD of silently accepting a too-short timeout: file a ticket to
+   fix it. If you discover a timeout shorter than 30s, surface it.
+5. **Graceful degradation order**:
+   - Chronicle (local, always possible) → commit checkpoint → git push
+     (may fail) → journal entry local (always possible) → Google Doc push
+     (may fail in cloud)
+   - Phase 1 (local artifacts) MUST complete even if Phase 2 (network) fails
+
+## This rule exists because
+
+Agents forget to write session artifacts in long sessions, especially
+after context compaction. Putting this in rules/ ensures it loads into
+every session at every level. The choreography doc has the full protocol;
+this rule is the reminder that fires regardless of mode.

package/dist/lite/.claude/rules/skill-composition-declarations.md

@@ -0,0 +1,105 @@
+---
+tier: lite
+description: How and when skills declare composes_with (extends another skill) vs depends_on (needs a runtime predecessor) in frontmatter. Closes bassclef#862 Gap 3.
+---
+
+# Skill composition declarations — `composes_with:` and `depends_on:`
+
+Two frontmatter fields make skill relationships explicit and machine-checkable. `composes_with:` names skills the current skill builds on. `depends_on:` names what must exist at runtime before the skill can usefully run.
+
+The substrate-clarity-gate hook reads both fields and catches typos by checking that named targets actually exist on disk. `composes_with:` is strict — a missing target blocks the write. `depends_on:` is advisory in V1.
+
+## When this rule fires
+
+When authoring or editing a skill frontmatter and you need to express:
+
+- "This skill chains with skill X" → `composes_with:`
+- "This skill needs Y to exist or be set first" → `depends_on:`
+
+Either field is optional. Skills that stand alone need neither.
+
+## `composes_with:` — extends another skill's behavior
+
+Use when the current skill builds on another skill's output, runs another skill as a step, or extends another skill's discipline.
+
+Format:
+
+```yaml
+composes_with: [kiss, value-prop]
+```
+
+Each name must match a `.claude/skills/<name>/SKILL.md` file. The hook BLOCKs the write when a name does not resolve.
+
+Examples that qualify:
+
+- `/longrun` composes_with `[temperance, retro, promote, session-end]` — runs these skills at lifecycle points
+- `/launch` composes_with `[interpret-input, stage, spec, use-case]` — chains the buildable-plan pipeline
+- `/diagnose` composes_with `[temperance]` — fires temperance before diagnostic ceremony
+
+When `composes_with:` is wrong, the substrate doesn't know the skill maps to a real chain. INSTEAD of listing rough memory of which skills run: list the exact slugs the skill calls.
+
+## `depends_on:` — required runtime predecessors
+
+Use when the skill assumes a predecessor exists at runtime. The predecessor can be a skill, a rule, or a known config block in `.claude/bassclef-configs.jsonc`.
+
+Format:
+
+```yaml
+depends_on: [tech_stack, personas]
+```
+
+V1 enforcement is advisory. The hook warns when a named target does not resolve as a skill, rule, or known config block, but the write passes. V2 may flip to strict once the vocabulary stabilizes.
+
+Recognized config blocks (V1 list): `tech_stack`, `adopter_defaults`, `plan_tier`, `prose_discipline`, `longrun`, `testing`.
+
+Examples that qualify:
+
+- A skill that reads adopter stack metadata depends_on `[tech_stack]`
+- A skill that requires persona definitions depends_on `[personas]` (the `/personas` skill must have run)
+- A skill that reads adopter overrides depends_on `[adopter_defaults]` (the bassclef-configs block)
+
+When `depends_on:` is wrong, the skill silently produces empty output instead of telling the operator what is missing. INSTEAD of letting the skill discover its preconditions at runtime: declare them up front.
+
+## composes_with vs depends_on — picking one
+
+| If the relationship is... | Use |
+|---|---|
+| The current skill runs the other skill as a step | `composes_with:` |
+| The current skill extends or chains the other skill's output | `composes_with:` |
+| The current skill needs prior session state from another skill | `depends_on:` |
+| The current skill reads a config block at runtime | `depends_on:` |
+| The current skill assumes a rule is in force | `depends_on:` |
+
+INSTEAD of listing the same name in both fields: pick the relationship that fires first. A skill that both runs `/value-prop` AND needs `/personas` from a prior session declares `composes_with: [value-prop]` plus `depends_on: [personas]`.
+
+## What this rule does NOT cover
+
+- Source code patterns and design pattern annotations — see `.claude/rules/pattern-annotation.md`
+- Frontmatter schema fields other than these two — see `standards/frontmatter-schema.md`
+- Adopter onboarding wiring (which adopter-config blocks ship by default) — see `.claude/skills/onboard-repo/SKILL.md`
+- Layer 3 traceability manifests that auto-populate from declared values — Phase 4 of bet 2026-06-18a (WU-17/WU-18/WU-19 deferred follow-on)
+
+## Mechanical enforcement
+
+- `composes_with:` value type must be a YAML list of strings. A non-list type or a non-string item BLOCKs the write.
+- Each name in `composes_with:` must resolve to `<repo>/.claude/skills/<name>/SKILL.md`. A missing target BLOCKs.
+- Each name in `depends_on:` resolves against skills, rules, or known config blocks. A miss emits an ADVISORY notice and passes.
+- Substrate root for path resolution is derived from the file being written (everything before `/.claude/`).
+
+Hook: `.claude/hooks/substrate-clarity-gate.sh` (added in bassclef#862 WU-15).
+Tests: `.claude/hooks/tests/substrate-clarity-gate.test.sh` Tests 27–36.
+
+## Override
+
+`SKIP_SUBSTRATE_CLARITY=1 <command>` bypasses the validation and logs the override via trace-helper. INSTEAD of overriding when a target is genuinely missing: file the missing skill first, then add the composes_with entry.
+
+Override is appropriate when:
+
+- A migration script edits many skills at once and the target skill ships in the same PR
+- Emergency rescue when the hook itself is broken
+
+## Composes with
+
+- `.claude/rules/skill-description-clarity.md` — sister discipline at the frontmatter description surface
+- `.claude/rules/state-schema-validation.md` — sister mechanical check at the state-spine surface
+- `standards/frontmatter-schema.md` — full frontmatter field catalog

package/dist/lite/.claude/rules/skill-description-clarity.md

@@ -0,0 +1,196 @@
+---
+tier: lite
+description: "Every skill's frontmatter description field must be parseable by an engineer with no bassclef context in under 60 seconds."
+---
+
+# Skill-Description Clarity
+
+Every skill's frontmatter `description` field must be parseable by an
+engineer with no bassclef context in under 60 seconds. Outcome-first.
+≤280 chars. Plain language. INSTEAD-block discipline.
+
+This rule sits at the entry surface. It parallels bassclef#357 (which governs autonomous-run output). It applies `.claude/rules/context-engineering.md` at the description field: write for what the model can access. For this rule, that means write what a fresh engineer can read in 60 seconds.
+
+**Mechanical enforcement**: `.claude/hooks/substrate-clarity-gate.sh` fires at PreToolUse Edit|Write on substrate paths. It BLOCKs skill descriptions past 280 chars or without verb-first openers. The rule + luminary INSTEAD-block check runs ADVISORY today. It flips to BLOCK once the rule + luminary audits ship (tracked under bassclef-upstream#303). The allowlist at `.claude/hooks/substrate-clarity-allowlist.txt` grandfathers existing violators during the grace window. Per bassclef#382.
+
+## The bar
+
+Anthropic's frontend-design description (per Welch's revision):
+
+> "Create distinctive, production-grade frontend interfaces with
+> high design quality. Avoids generic AI aesthetics."
+
+That's the bar. Outcome ("create distinctive interfaces"), one-line
+how ("with high design quality"), one-line why-distinct ("avoids
+generic AI aesthetics"). 117 chars. Engineer reads it; knows what
+the skill produces; knows when to use it.
+
+Compare to bassclef's pre-rule descriptions (representative):
+
+> "BUILD-tier composer (Construction transition). Chains the
+> prototype pipeline (input → variants → gallery → bind-subdomain)
+> PLUS the buildable-spec pipeline (use-case → user-stories →
+> ia-model → interaction-design → decompose → spec → ux-migration)."
+
+571 chars. Methodology-laden. Requires knowing what every named
+component is. Engineer can't grok in 60 seconds.
+
+## Format
+
+Every skill's frontmatter `description` field follows:
+
+```
+<verb> <outcome>. <one-line how>. <one-line why-distinct>.
+```
+
+- **Verb**: imperative — "Create," "Generate," "Run," "Compose," "Audit"
+- **Outcome**: what the skill PRODUCES (not how it works internally)
+- **One-line how**: the most distinguishing mechanism, in plain language
+- **One-line why-distinct**: what makes it different from adjacent skills (or what it specifically AVOIDS)
+
+Total ≤280 chars including spaces.
+
+## INSTEAD-block discipline
+
+Every "DON'T" / "AVOID" / "NEVER" in the description gets paired with
+the actionable substitute, per `.claude/rules/context-engineering.md`.
+
+INSTEAD of bare negation: state the actionable substitute the engineer
+or model can verify in their current context. Bare "DON'T X" without
+"INSTEAD: Y" is a no-op for a stateless reader.
+
+In a description, this shows up in the why-distinct clause:
+
+- **Anti**: "Don't use this for short prompts."
+- **INSTEAD**: "Use for prompts ≥3 sentences; for one-liners, see /value-prop flash."
+
+The negation lives in context (when not to use). The substitute names the actionable path (which skill to use instead).
+
+## Plain language (per /kiss words)
+
+Grade-10 reading level. Common substitutions bassclef-substrate writers should make:
+
+| Replace | With |
+|---|---|
+| "composer" | "runs" / "chains" / "combines" |
+| "primitive" | "building block" |
+| "tier-preset" | "preset" / "size" |
+| "operationalize" | "do" / "ship" |
+| "load-bearing" | "required" / "must work" |
+| "blast radius" | "impact" / "what it can break" |
+| "substrate" | "system" / "framework" |
+| "bassclef" (in description body) | use sparingly; prefer "the framework" |
+| "compose-with" | "uses" / "builds on" |
+| "scope-bounded" | "small" / "tight" |
+
+If the description still uses bassclef jargon after substitution,
+the description was assuming context the engineer doesn't have.
+Rewrite further.
+
+## What MUST NOT appear in a description
+
+- References to other skills the engineer hasn't read yet (skill names OK; methodology references aren't)
+- Methodology chains ("X → Y → Z → ...")
+- Tier specifications without explaining what the tier does
+- Citations to bassclef issues (those go in the body)
+- Dates / versions / "renamed from X on Y" (those go in the body)
+- Assumed pipeline knowledge ("Phase 14 of the buildable-spec chain")
+
+## What MUST appear in a description
+
+- The verb-outcome opener
+- A concrete sense of what the user gets back
+- A distinguishing characteristic vs. adjacent skills
+- **Modes / tiers / sizes named inline when frontmatter declares them** (bassclef#535) — see next section
+
+## Description-mirrors-modes (bassclef#535)
+
+When a skill's frontmatter declares structured `modes:` / `tiers:` / `sizes:` (per bassclef#515), the description **text** MUST name each declared value inline. Operators see Claude Code's type-ahead BEFORE invoking `/skills`; type-ahead reads only the `description` field. Frontmatter `modes:` is machine-readable for bassclef's audit + render pipeline but invisible to type-ahead.
+
+**The discipline:**
+
+- If frontmatter has `modes: [scope, words]`, description must contain "scope" AND "words" (typically as "Two modes — scope ... and words ..." or similar)
+- If frontmatter has `tiers: [quick, light, medium, full]`, description must name all four
+- If frontmatter has `sizes: [flash, tweet, brief, verbose]`, description must name all four
+- Skills with `no_user_modes: true` (opt-out) are exempt
+- The 280-char ceiling still applies — naming N modes that won't fit means the description is over-claiming; collapse the verbiage around them
+
+**Why mirror, not auto-render?**
+
+Type-ahead reads `description`. bassclef doesn't control the harness; we control the data we put in `description`. Mirroring is the cheap fix that makes type-ahead useful for mode-bearing skills today. Frontmatter `modes:` stays machine-readable for `/skills` catalog rendering + audit + future structured uses; description text stays human-readable for type-ahead.
+
+**Conformance examples (all 7 skills with modes today):**
+
+| Skill | Frontmatter | Description names them? |
+|---|---|---|
+| `/value-prop` | `sizes: [flash, tweet, brief, verbose]` | ✓ "Four sizes — flash ... tweet ... brief ... verbose" |
+| `/kiss` | `modes: [scope, words]` | ✓ "Two modes — scope ... and words ..." |
+| `/stage` | `sizes: [quick, light]` | ✓ "Two sizes: quick ... and light ..." |
+| `/launch` | `sizes: [medium, full]` | ✓ "Two sizes: medium ... and full ..." |
+| `/shape` | `tiers: [quick, light, medium, full]` | ✓ "four sizes — quick, light, medium, full" |
+| `/longrun` | `modes: [prep, checkpoint, closeout]` | ✓ "three modes — prep, checkpoint, closeout" (after bassclef#535) |
+| `/interpret-input` | `modes: [text, url, image, repo, transcript, napkin, mixed]` | ✓ types listed in parens |
+| `/onboard-repo` | `modes: [default, --with-deploy-host, --with-secrets, --full]` | ❌ pending — fold into LR8.6 PR #526 amendment |
+
+**Mechanical enforcement (deferred follow-on):**
+
+- `scripts/audit-skills-modes.sh` (bassclef#515 PR #519) extends with `description-doesnt-mirror-modes` finding type
+- `.claude/hooks/substrate-clarity-gate.sh` extends with the same check at PreToolUse Edit/Write time
+- Both gated behind bassclef#515 + bassclef#382 landing first; until then, this rule is methodology-level + the operator runs the audit manually
+
+**Override:**
+
+`SKIP_DESCRIPTION_MIRRORS_MODES=1` per-call override (logged via trace-helper). Use only when the frontmatter declares modes that are too numerous to mention inline (>5) AND a higher-level grouping description suffices.
+
+## Application
+
+### Per skill (rewrites)
+
+1. Read existing description
+2. Score against rule (Verb? Outcome? ≤280 chars? Jargon? Plain language?)
+3. Rewrite if score < B
+4. Test the rewrite: would a senior engineer with no bassclef context understand it in 60 seconds?
+
+### Per longrun (audit)
+
+The audit issue (bassclef#375 + sister WU-3 issues) tracks
+per-skill rewrites. WU-6 of this longrun ships top-7 (data + judgment
+based) as in-scope examples; rest filed as follow-up.
+
+### Per new skill
+
+Every new skill's description goes through this rule before merge.
+Test: paste the description into a Slack DM to a senior engineer
+without bassclef context. If they ask "what does this DO?" you
+violated the rule.
+
+INSTEAD of testing against a bassclef-savvy reader: test against
+a fresh reader who carries no internal vocabulary. That's the
+audience the description has to serve.
+
+## Relationship to other rules
+
+- `.claude/rules/context-engineering.md` — the foundational rule; this is one application
+- bassclef#357 (autonomous-run flash + kiss) — sibling discipline at output surface; this rule is at description surface
+- bassclef#367 (section-heading standardization) — sibling specificity discipline
+- bassclef#339 (plan-enumeration-needs-value-props) — sibling at choice-presentation surface
+
+## Override
+
+There is no override. Skill descriptions are an entry surface for
+engineers and operators. Violating the rule means engineers won't
+adopt the skill, regardless of how good the skill itself is.
+
+If you can't write the description per the rule, the skill's job
+isn't clear enough — clarify the skill before clarifying the
+description.
+
+## Audit pattern
+
+```bash
+# Find skills whose descriptions exceed 280 chars
+grep -r "^description:" .claude/skills/*/SKILL.md | awk -F: '{ if (length($0) > 280) print $0 }'
+
+# Find skills whose descriptions use bassclef jargon
+git grep -niE 'composer|primitive|tier-preset|operationalize|load-bearing|blast radius|compose-with' .claude/skills/*/SKILL.md | grep -E '^.*:description:'
+```

package/dist/lite/.claude/rules/skill-procedure-step-list.md

@@ -0,0 +1,119 @@
+---
+tier: lite
+description: Before executing any SKILL procedure, I write the numbered step list into the response.
+---
+
+# Skill-procedure step-list
+
+Before executing any SKILL procedure, I write the numbered step list into the response. Each step is marked `[x]` executed with source cited OR `[~]` explicitly deferred with reason. No `[ ]` unchecked lines ship at output time. Silence is not deferral.
+
+This rule extends `.claude/rules/assert-only-after-verify.md` from the assertion surface to the SKILL-procedure surface. It is the methodology layer. The mechanical layer is `.claude/hooks/skill-step-list-check.sh` — Stop hook that scans the transcript for a Skill dispatch followed by an assistant response without a step-list block.
+
+## When this rule fires
+
+Every SKILL dispatch. Agents self-check before writing the response. Hook fires at Stop event as the write-time backstop.
+
+Fires on:
+
+- Any Skill tool dispatch in the current turn
+- Any SKILL body whose procedure names 2+ steps
+
+Passes through on:
+
+- Non-Skill tool calls (Bash, Read, Edit, Write, Grep, etc.) — those follow their own discipline rules
+- SKILL body procedures with 0 or 1 step (no list needed)
+- Tool-output relays (test output, git output) that carry no assertions of their own
+
+## What the rule requires
+
+Before shipping any response following a SKILL dispatch:
+
+1. **Read the SKILL body Procedure section.** Enumerate the numbered steps.
+2. **Write the step list at the top of the response.** Format: `Step N — <name>` followed by a status marker.
+3. **Execute each step.** Cite the source inline as it runs.
+4. **Mark each step's status:**
+   - `[x]` executed with source cited
+   - `[~]` explicitly deferred with reason (silence is not deferral)
+   - Do not ship `[ ]` unchecked at output time.
+     INSTEAD: mark every step `[x]` or `[~]` before the response ships. Unchecked shipped equals silent skip.
+5. **Loaded context is a hint, not a substitute for a source read named by a step.** The context feels full. That is when the skip is easiest and the drift is worst.
+   INSTEAD: cite the source per the SKILL step. Loaded context is a hint, not a substitute.
+
+## Format contract
+
+Each step line matches one of these shapes:
+
+- `Step N — <name> — [x] <source cited>`
+- `Step N — <name> — [~] <deferral reason>`
+
+Or a block header + list format:
+
+```
+Steps:
+- Step 1 — <name> — [x] <source>
+- Step 2 — <name> — [~] <reason>
+```
+
+The hook scans for two markers together: the token `Step\s+\d+` AND either `[x]` or `[~]` bracketed. Both must appear in the assistant text following a Skill dispatch.
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Dispatch skill; write results with no step list.** The response ships without any `Step N` markers. Hook fires ADVISORY (or BLOCK under strict toggle).
+INSTEAD: enumerate the SKILL procedure steps at the top of the response before running them.
+
+**Silent skip.** A step gets no `[x]` and no `[~]` line — the response simply omits it.
+INSTEAD: every step from the SKILL procedure appears in the response, either done or explicitly deferred with reason.
+
+**Context as substitute.** Loaded context carries a plausible answer. Skip the SKILL step; use the context.
+INSTEAD: cite the source per the SKILL step. Loaded context is a hint, not a substitute for the read the step names.
+
+**Half-written list.** Some steps carry markers; others do not.
+INSTEAD: every step marked before response ships. Half-written lists cause reviewer confusion + trigger the hook.
+
+## When this rule does NOT fire
+
+- Tool-output relays (test output, git output) — no assertion of the agent's own
+- SKILL body with 0 or 1 step — no list needed
+- Skill invoked purely for its output display (e.g., `/whereami` for a status snapshot)
+- Chat responses that do not follow a Skill dispatch
+
+## Override
+
+`SKIP_SKILL_STEP_LIST=1 <command>` — per-call bypass, logged via trace-helper. Use rarely:
+
+- One-shot migration scripts that dispatch many SKILLs at once
+- Emergency rescue when the hook itself misbehaves
+- Explicitly-deferred rework where the step list ships in a follow-up response
+
+For routine SKILL dispatches, write the step list. The cost is small; the audit trail compounds.
+
+## Toggle
+
+The hook reads `SKILL_STEP_LIST_TOGGLE` from env OR `skill_step_list.toggle` from `.claude/bassclef-configs.jsonc`:
+
+- `true` (default) — advisory (exit 0, findings to stderr)
+- `strict` — strict (exit 2, blocks the stop event, forces a rewrite)
+- `false` — silent (exit 0, no scan)
+
+V1 ships advisory. V2 may flip to strict after a calibration cycle observes drift stays under 10%.
+
+## Anchor luminaries
+
+- `.claude/luminaries/saltzer-schroeder.md` (Saltzer & Schroeder 1975, IEEE 63(9)) — complete mediation. Every access to protected state is checked. Whereami narrative was a cached authorization. Rule + hook forces mediation at every SKILL dispatch.
+- `.claude/luminaries/tony-hoare.md` (Hoare 1969, CACM 12(10)) — pre/postcondition triple. Each step's postcondition is the next step's precondition. Skip breaks the chain.
+- `.claude/luminaries/michael-feathers.md` (Feathers 2004) — characterization tests. Pin actual behavior via source of record before naming it.
+- `.claude/luminaries/kent-beck.md` (Beck 2002) — list-before-execute. Sister discipline at test surface applied to SKILL surface.
+
+## Composes with
+
+- `.claude/rules/assert-only-after-verify.md` — parent discipline at claim surface; this rule extends to SKILL-procedure surface
+- `.claude/rules/bootstrap-pair-discipline.md` — pair-shape pattern (rule + hook + Tier 0 test)
+- `.claude/rules/substrate-as-system.md` — ADR-035 tenet
+- `.claude/rules/test-list-discipline.md` — Beck's list-before-execute sister rule at test surface
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict TDD on hook + tests
+- `.claude/rules/we-dont-break-adopters.md` — V1 ADVISORY default preserves adopter behavior
+- `.claude/rules/blocked-items.md` — BLOCK protocol the hook fires under strict toggle
+- `.claude/hooks/skill-step-list-check.sh` — mechanical implementation
+- `.claude/hooks/tests/skill-step-list-check.test.sh` — Tier 0 test coverage (10 tests)