@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/rules/whereami-load-bearing.md

@@ -0,0 +1,202 @@
+---
+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.
+
+## Why this rule exists
+
+Whereami existed as an optional artifact and rotted because nothing
+demanded its maintenance. Evidence observed 2026-04-16:
+
+- Bassclef's own whereami dated same day but field said "Active
+  agents: None" during active mid-session work — stale by default
+- POA (first app consumer) has no whereami at all — `/sprint` has
+  to reconstruct state from iteration-bets + chronicles + git log
+- `/sprint` skill's own procedure (step 4) phrased whereami as
+  conditional ("if docs/whereami.md exists") — treating it as a
+  nice-to-have reinforced its rot
+
+Load-bearing means: the artifact is required input for at least one
+skill, required output for at least one other, hook-enforced fresh,
+and operator-visible when it goes stale. This rule establishes all
+four.
+
+## 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/substrate/.claude/rules/writing-craft-discipline.md

@@ -0,0 +1,92 @@
+---
+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)
+
+## Distinct from
+
+- **plain-english-discipline** — that rule targets grade 8-9 (grade 8 after ticket #935 lands) and enforces the jargon list. This rule targets craft — natural voice, short units, read-aloud, completeness, honesty, facts-with-context. The two fire together at every surface.
+- **operator-facing-prose** — that rule is the meta-discipline (gloss shorthand, /kiss pass on SKILL.md edits). This rule is the compose-time check.
+
+## 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).
+
+## Refs
+
+- Ticket #934 — this rule's filing (Ogilvy skill + luminary + rule + standard)
+- Sister rule `plain-english-discipline.md` (bassclef#790)
+- Sister rule `operator-facing-prose.md` (bassclef#790)
+- Parent /diagnose #833 (why /kiss drifts)
+- Standard `standards/ogilvy-writing-rules.md`
+- Luminary `.claude/luminaries/david-ogilvy.md`
+- Ogilvy — "How to Write" memo (1982)
+- Roman + Raphaelson — *Writing That Works* (Harper and Row, 1981)
+
+## Retirement condition
+
+This rule retires only if bassclef stops shipping operator-facing prose. Specific tests may evolve; the discipline of prose-as-craft persists.