@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/rules/whereami-load-bearing.md

@@ -0,0 +1,184 @@
+---
+tier: lite
+description: docs/whereami.md is the authoritative project-state snapshot in every bassclef-substrate repo.
+---
+
+# Whereami Load-Bearing
+
+`docs/whereami.md` is the authoritative project-state snapshot in
+every bassclef-substrate repo. This rule establishes its load-bearing
+obligations: session-start read, session-end write, and protocol when
+the artifact is missing or stale.
+
+## Protocol
+
+### Session-start read (MUST)
+
+Every session's orientation pass reads `docs/whereami.md` BEFORE
+consulting iteration-bets or chronicles for project-state questions.
+Downstream skills (`/sprint`, `/substrate-check`) use whereami as
+primary source, not fallback.
+
+If the artifact is missing or stale (per freshness rules below), the
+`bassclef-sync.sh` session-start hook fires BLOCKED (per
+`blocked-items.md`). The session does not proceed with substantive
+work until resolved or explicitly deferred.
+
+### Session-end write (MUST)
+
+Every `/session-end` execution updates `docs/whereami.md`:
+
+- Bump `last_updated` to current UTC timestamp
+- Set `session:` field to the chronicle filename just written
+- Update any field that materially changed during the session:
+  - `phase:` if project phase transitioned
+  - `iteration_bet:` if bet opened or closed
+  - `iteration_phase:` if WS advanced
+  - Subsystem row if subsystem moved
+  - Gate progress checkboxes if any toggled
+
+Same tier as chronicle — non-negotiable session artifact.
+
+### Freshness rules
+
+Hook checks two signals: `last_updated` field age **AND** commits-since-
+last-whereami-update (computed via `git log -1 --format=%H -- docs/whereami.md`
++ `git rev-list --count <commit>..HEAD`). Both signals together close the
+"idle consumer" false-positive loop where calendar age alone fired BLOCKED
+on repos that hadn't done any work since the last update (bassclef#514).
+
+| Age | Commits since whereami | Signal | Session behavior |
+|-----|------------------------|--------|-----------------|
+| <3 days | any | Green | Proceed normally |
+| 3–7 days | any | Warning | Warning surfaced; session proceeds |
+| ≥7 days | 0 (idle) | **INFO** | Friendly note that repo's idle; session proceeds |
+| ≥7 days | >0 (work happened) | BLOCKED | Session halts on substantive work until refreshed |
+| Missing file | n/a | BLOCKED | Session halts; create from template |
+
+The idle-as-INFO downgrade matters because bassclef-substrate consumers
+get session-start hook output even when they're not actively iterating.
+A consumer paused for two weeks should get a "you're idle" note, not a
+gate that interrupts the next time someone opens the repo.
+
+Operator may override with explicit "skip whereami this session" per
+`blocked-items.md` deferral rules. Silence is not deferral. INFO does
+not require deferral (it's not a gate).
+
+### On session-start BLOCKED
+
+When the hook surfaces a whereami-stale BLOCKED block, the agent:
+
+1. Echo the BLOCKED block verbatim to the operator (same pattern as
+   `bassclef-hook-drift-blocker.md`)
+2. Offer two paths:
+   - **Refresh now**: run `/session-end`-style whereami update step
+     at session-start as the first action
+   - **Defer**: operator explicitly says "skip whereami"
+3. Do NOT start other substantive work until one of the paths is
+   taken
+
+### On missing file
+
+Fresh consumer repo scenario. `bassclef-sync.sh` surfaces BLOCKED:
+"docs/whereami.md missing; create from templates/whereami-template.md"
+
+Agent proposes to copy the template and fill minimal fields
+(phase, iteration — or "none — new repo"). Operator approves or
+overrides.
+
+## What counts as a material change (session-end trigger)
+
+Anything that changed the answer to "where are we?":
+
+- Phase transition (Inception → Elaboration, etc.)
+- Iteration opened, closed, or re-shaped
+- WS within active goal advanced (WS-1 → WS-2)
+- Subsystem row's phase or "last iteration" date changed
+- Gate progress checkbox toggled
+- Active agents changed (sequential→multi-agent or vice versa)
+
+What does NOT trigger: just timestamp refresh without any field change
+is still a valid update (keeps freshness meter green). The obligation
+is to bump `last_updated` every session; field changes are additive.
+
+## Who reads whereami (and relies on it being fresh)
+
+- `/sprint` — primary source for orientation (step 1, not step 4
+  fallback)
+- `bassclef-sync.sh` — freshness check only
+- `/substrate-check` — presence + schema validation
+- Operator — ad-hoc project-state eyeballing
+- Chronicle writer — phase context for retrospective
+
+## Live vs archive split (per bassclef-upstream#1080)
+
+`docs/whereami.md` is the LIVE file — carries frontmatter + recap blocks from the last 7 days. Older recap blocks move to `docs/whereami-archive/YYYY-MM.md` — one file per calendar month, appended chronologically.
+
+The split exists because `docs/whereami.md` grew past the `Read` tool's 256KB ceiling on 2026-08-04. Session-start Step 0.4 mandatory read broke. Rotation restores the Read path; archive preserves history.
+
+**Contract:**
+
+- Live keeps the last 7 days of `operator_recap_*` blocks (default; override via `scripts/rotate-whereami.py --days N`)
+- Archive holds older blocks grouped by month
+- Live carries an `archive_dir:` field in frontmatter naming the archive location
+- Session-start freshness signal reads live only — archive is read-only historical
+- Rotation runs on SessionStart when live file exceeds 250KB via `.claude/hooks/session-reflection.d/36-whereami-size-check.sh`. Fires with `--days 3` (tighter than the 7-day default) because dense session weeks fill 7 days past the Read tool 256KB ceiling per bassclef-upstream#1284. Operator can run manually anytime with `--days N`; the script is idempotent (re-runs do not duplicate).
+
+**What reads from archive:**
+
+- Operator when they need >7 day historical context
+- `/journal` when writing session narratives that span the rotation boundary
+- Explicit follow-up queries (e.g., "what happened in 2026-07?")
+
+**What reads from live only:**
+
+- Session-start freshness signals (per this rule)
+- `/sprint` orientation (primary source)
+- `/substrate-check` (presence + schema validation)
+- Chronicle writer at session-end (updates live only)
+
+## What whereami is NOT
+
+Artifacts adjacent to whereami have distinct roles. Don't conflate:
+
+- **Iteration bet** (scope contract) — whereami references it by path
+- **Chronicle** (retrospective narrative) — whereami is current-state
+  snapshot
+- **substrate.config.md** (external resources) — different concern
+  (where is X vs. where are we)
+- **Risk register** — separate artifact; whereami points to it
+
+## Override paths
+
+- `SKIP_WHEREAMI=1 <command>` — per-command override (logged to trace)
+- Operator statement: "skip whereami this session" — verbatim deferral
+  per `blocked-items.md`
+- `substrate.config.md: whereami_freshness_days: N` — per-repo
+  threshold override (if N=0, freshness check disabled, but presence
+  still required)
+
+## Relationship to other rules
+
+- `blocked-items.md` — BLOCKED protocol; whereami staleness fires it
+- `session-artifacts.md` — chronicle + journal-entry obligations; whereami
+  joins this tier
+- `bassclef-hook-drift-blocker.md` — same hook-fired BLOCKED pattern;
+  whereami BLOCKED mirrors its shape
+- `sdlc-gates.md` — session-start orientation is where whereami fires
+  in the gate ordering
+- `artifact-ingestion.md` — whereami is one of the "prior artifacts" a
+  session-start orientation MUST read before producing
+
+## Enforcement
+
+- Hook: `bassclef-sync.sh` section emits BLOCKED on stale/missing
+  (added `BASSCLEF_SYNC_VERSION` bump in WS-3 of bet 2026-04-16c)
+- Skill: `/session-end` procedure includes whereami-update as MUST
+  tier
+- Skill: `/sprint` procedure reads whereami as step 1 primary source
+- Skill: `/substrate-check` validates presence + schema conformance
+- Template: `templates/whereami-template.md` provides start
+  shape; `/autonomous start` creates from template
+
+The rule stands regardless of hook availability. The hook is the
+mechanical backstop; the rule is the reasoning.

package/dist/lite/.claude/rules/writing-craft-discipline.md

@@ -0,0 +1,72 @@
+---
+tier: lite
+description: Plain check. Before I ship any operator-facing prose in this turn, I run the six Ogilvy tests against my draft. If any test fails, I rewrite before I ship.
+---
+
+# Writing-craft discipline
+
+**Plain check.** Before I ship any operator-facing prose in this turn, I run the six Ogilvy tests against my draft. If any test fails, I rewrite before I ship.
+
+---
+
+This rule loads every session. It sits alongside `.claude/rules/plain-english-discipline.md` (grade + vocabulary) and adds writing-craft tests grounded in Ogilvy's 1982 "How to Write" memo plus Roman and Raphaelson's *Writing That Works* (1981). Full reference: `standards/ogilvy-writing-rules.md`. Luminary anchor: `.claude/luminaries/david-ogilvy.md`.
+
+## The six first-person composition tests
+
+Before I write each sentence or paragraph in operator-facing prose, I ask:
+
+**1. Natural voice.** Would a real person say this to a respected peer? If it sounds like corporate throat-clearing ("Please be advised that...", "It has come to my attention..."), I rewrite in natural voice.
+
+**2. Short units.** Is this sentence past 25 words? If yes, I split it. Is this paragraph past 6 sentences? If yes, I split it. Is there a shorter word for what I mean? If yes, I use the shorter word (utilize → use; commence → start; endeavor → try).
+
+**3. Read-aloud.** When I read this passage in my head, does it stumble? Tongue-twisters, long lines with no comma rest, unintentional rhymes, repeated words — any of those means I rewrite until it flows.
+
+**4. Completeness.** What is the ONE thing the reader needs to take from this? Is that thing actually written down, in plain language, somewhere the reader will see it? If the point is implied but not stated, I state it.
+
+**5. Honesty.** Am I saying what I mean or hiding behind softening language? Weasel words ("arguably", "somewhat", "perhaps"), euphemisms ("right-sizing", "reached out"), passive voice hiding the actor ("mistakes were made") — any of these means I rewrite straight.
+
+**6. Facts with context.** For each number, fact, or data point in my draft: does the reader know why it matters? If I have "Revenue was 4.2M" with no interpretation, either I add the interpretation ("up 30 percent year over year") or I drop the fact.
+
+## When this rule fires
+
+Every operator-facing surface:
+
+- Turn prose in agent responses
+- PR body Summary and Test plan sections
+- Ticket body Problem sections
+- Chronicle body sections
+- Journal entries
+- Handoff notes
+- Deferred-action entries
+
+Skips (Ogilvy's rules do not apply, or apply differently):
+
+- Code blocks
+- File paths and function names
+- Structured schema output (JSON, YAML)
+- Backticked terms and API references
+- Test-list blocks in test files (structured audit surface)
+- Frontmatter fields (structured metadata)
+
+## Composes with
+
+- `.claude/rules/plain-english-discipline.md` — grade level + vocabulary substitution table. Composes: this rule covers craft; that rule covers grade + jargon list.
+- `.claude/rules/operator-facing-prose.md` — gloss + `/kiss` meta-discipline at every operator-facing surface
+- `.claude/rules/context-engineering.md` — INSTEAD-block discipline foundational to bassclef's rule writing
+- `standards/ogilvy-writing-rules.md` — full reference with violation patterns and fixes
+- `standards/bassclef-internal-jargon.md` — extended wordlist Rule 3 references
+- `.claude/luminaries/david-ogilvy.md` — luminary anchor
+- `.claude/skills/ogilvy-writing-audit/SKILL.md` — operator-invocable audit (produces severity-tagged violations)
+- `.claude/skills/kiss/SKILL.md` — /kiss words composes with the audit (audit diagnoses, kiss fixes)
+
+## Anti-patterns
+
+**Draft-and-ship without running the six tests.** The rule loads but the agent skips the checks at composition time. Failure mode: prose ships jargon-heavy, long-sentenced, or facts-without-context. Fix: read each sentence against the six tests before I ship the turn.
+
+**Rewriting only on hook flag.** The turn-prose-kiss-check hook fires post-Stop; running the six tests only when the hook flags means catching after the fact. Fix: run at composition time, per the Plain check at the top of this rule.
+
+**Selective application.** Applying the tests to some paragraphs but not others (e.g., only the opener). Failure mode: middle paragraphs drift. Fix: every sentence in every operator-facing paragraph gets the six-test check.
+
+## Override
+
+`SKIP_WRITING_CRAFT=1 <command>` — logged via trace-helper. Use only for quoted external content that must ship verbatim (e.g., quoting Ogilvy's memo in the reference standard).

package/dist/lite/.claude/rules/wu-sequencing-compounds.md

@@ -0,0 +1,119 @@
+---
+tier: lite
+description: WUs within a chosen goal shape ship as compounding builds.
+---
+
+# WU Sequencing — Each WU Compounds With the Next
+
+WUs within a chosen goal shape ship as compounding builds. Each WU declares what it produces that the next WU consumes. The trap: independent step enumeration where each step does its own thing. No WU's output feeds another. The value that compounded at shape-pick time disappears once the shape is picked.
+
+The rule mechanizes the discipline filed at bassclef#1348. The operator caught the gap on 2026-06-20h prep. My first WU proposal sequenced fixes (recursive walk + triage + workflow stand-up) as parallel-safe atomic items. It should have been a chain where each output flowed into the next.
+
+Sister rules cover the INTER-shape layer. bassclef#1299 covers Step 1.5 (the compounding column). bassclef#1302 covers Step 1.6 (the adopter-benefit column). Those two help the operator pick between shapes. This rule disciplines step enumeration WITHIN a chosen shape.
+
+## When this rule fires
+
+- `/longrun prep` Step 1.7 (added in this rule's PR) — when step enumeration goes into the prep output proposal, the table includes a produces/consumes column
+- Bet doc authoring — when the `## Steps` section is written, the table uses the produces/consumes shape
+- `/sprint` next-work proposals — same shape when proposing a multi-step sequence (sister surface; same wordlist)
+- `/build` skill construction-time sequencing — out of scope for V1; separate ticket if surfaced
+
+## Format contract
+
+Every goal doc's `## Steps` section uses one of two table shapes.
+
+### Shape A — three-column (canonical)
+
+```markdown
+| WU | Produces | Consumes (from prior WU) |
+|---|---|---|
+| **0** prep | goal doc + stack manifest + temperance marker | — (session-start) |
+| **1** <ticket> | <what ships> | <what it reads from prior WU> |
+| **2** <ticket> | <what ships> | <what it reads from WU-1> |
+| ... |
+```
+
+### Shape B — six-column (extended per bassclef-upstream#688)
+
+```markdown
+| WU | Problem + value prop | Produces | Consumes (from prior WU) | How this step builds on the prior | Risk |
+|---|---|---|---|---|---|
+| **0** prep | <problem sentence> + <value prop sentence> | goal doc + markers | — (session-start) | — (baseline) | low |
+| **1** <ticket> | <problem sentence> + <value prop sentence> | <what ships> | <what reads from prior WU> | <how it builds> | <low/med/high> |
+```
+
+Shape B mirrors the `/longrun` prep proposal rendering. Prep proposals MUST render six-column so the operator sees per-step sequencing at pick-time. Bet doc `## Steps` sections use EITHER shape; six-column is preferred when the goal doc reuses the prep proposal table verbatim.
+
+Column semantics for Shape B:
+
+- **Problem + value prop** — one cell combining `/state-a-problem brief` output AND `/value-prop flash` output. Do NOT split the two outputs into separate cells. Operator preference confirmed 2026-07-09 (bassclef-upstream#688).
+- **How this step builds on the prior** — one line explaining the sequencing. "Baseline" for WU-0. Parallel-safe WUs state "parallel-safe with WU-N".
+- **Risk** — low / medium / high, matching the step's Step 1.5 risk-class value.
+
+Format rules (both shapes):
+
+- Shape A header exactly: `| WU | Produces | Consumes (from prior WU) |` — greppable by `bet-doc-gate.sh` V2 hook (3-column path)
+- Shape B header exactly: `| WU | Problem + value prop | Produces | Consumes (from prior WU) | How this step builds on the prior | Risk |` — greppable by `bet-doc-gate.sh` V2 hook (6-column path)
+- Each WU's Produces is a concrete artifact (file, decision, label set, marker, output)
+- Each WU's Consumes names what the prior WU produced — by reference, not duplicated description
+- WU-0 prep consumes "session-start" (no prior WU)
+- Final WU (closeout) produces the chronicle + whereami flip; consumes the union of all prior WU outputs
+- When a WU is genuinely parallel-safe (no consumer), state "parallel-safe (no consumer)" or "parallel-safe with WU-N" in the Consumes cell — explicit declaration, not silent
+
+## What this rule requires
+
+The agent runs this check before committing the goal doc OR before posting the `/longrun prep` confirmation surface:
+
+1. Each WU declared in the proposed shape has a Produces cell
+2. Each WU after WU-0 has a Consumes cell that names what the prior WU produced
+3. When a WU's Produces doesn't feed any later WU, the rule fires WARN. Either the step is misplaced (should be its own goal) OR the sequencing is correct but the next-WU consumption is implicit and needs stating.
+4. The goal doc body cites this rule's slug in the `references:` block when sequencing is non-obvious
+
+## Anti-patterns
+
+The following shapes fail this rule:
+
+- **Bare WU list** — `WU-1: fix X. WU-2: fix Y. WU-3: triage Z.` Independent items; no produces/consumes contract
+- **Sequence-implied-by-ordering** — WUs listed in order but the goal doc body doesn't say WHY this order. Order alone is not compounding
+- **All WUs are independent** — every step is parallel-safe. That signal calls for a question: is this one goal or several smaller bets?
+
+The agent picks one path when the rule fires WARN:
+
+- Restructures the step sequence so each step's output is input to the next (preferred)
+- Splits the goal — if WUs are genuinely parallel-safe with no compounding, they belong in separate goals
+- Explicitly justifies why a parallel-safe WU rides with sequenced WUs (e.g., shared review window, operator preference)
+
+## Mechanical layer
+
+V1 ships this rule + the SKILL.md Step 1.7 procedure update.
+
+**V2 (shipped 2026-06-23 per bassclef-upstream#21):** `.claude/hooks/bet-doc-gate.sh` PreToolUse Edit|Write|MultiEdit on `docs/iteration-bets/*.md` performs the substantive Consumes-cell check. Composed with sister #300 thread-walk check in the same hook file. Behaviors:
+
+- **PASS** when Consumes cell contains a concrete artifact reference (backtick-quoted ref, slash-prefixed path, `.sh|.md|.json|.yml` extension) OR explicit literal `"parallel-safe (no consumer)"` OR `"session-start"` (prep) OR `"union of"` (closeout).
+- **WARN** (exit 0 with stderr) when Consumes cell starts with `WU-N` or `WU-N's` followed by vague prose without any concrete artifact reference. Advisory in V2; flips to BLOCK in V3 if observable drift persists.
+- **Silent** on non-matching paths, non-Edit tool calls, or goal docs without a steps table.
+
+Overrides (logged via trace-helper):
+- `SKIP_PRODUCES_CONSUMES_CHECK=1` — bypass P/C only
+- `SKIP_BET_DOC_GATE=1` — bypass both P/C and thread-walk
+
+Per `feedback_hooks_beat_methodology_for_substrate_quality` memory: V2 hook ships ALONGSIDE the methodology — both required.
+
+## Override path
+
+`SKIP_WU_SEQUENCING_COMPOUNDS=1 <command>` (when V2 hook ships) — logged via trace-helper. Use rarely:
+
+- Single-WU bets — no sequencing applies; the column is trivially empty
+- Genuinely parallel atomic WUs that share a review window (declare in goal doc body)
+- Migration scripts authoring many goal docs at once
+
+INSTEAD of overriding for routine work: write the produces/consumes cells. The discipline costs seconds at write-time and compounds across every future thread walking tonight's chronicle for reference.
+
+## Composes with
+
+- `.claude/rules/arc-level-orientation-before-leaf.md` — sister at orientation surface (sister bassclef#1347 fixes one-level walk)
+- `.claude/rules/plan-enumeration-needs-value-props.md` — sister at choice-presentation surface
+- `.claude/rules/blocked-items.md` — BLOCK protocol the V2 hook fires
+- `.claude/skills/longrun/SKILL.md` Step 1.7 — primary surface this rule extends
+- `.claude/skills/sprint/SKILL.md` — sister surface (next-work proposals)
+- standards/branch-stacking.md — stack manifest already declares dependencies between WUs; this rule extends to the goal doc body