@thebassclef/lite 0.1.2 → 1.0.0

package/substrate/.claude/skills/sprint/SKILL.md

@@ -1,392 +0,0 @@
----
-name: sprint
-description: "Show what's in flight and what's next. Reads project state, open issues, and the active goal. Proposes the next sprint at thread level, not just the nearest leaf. Run at session start."
-problem: "Session-start orientation takes a full read of git log and whereami and open PRs. Slow."
-value: "One glance at what's in flight and what's next and what's blocked. Reads project state once."
-inputs: [Optional focus flag]
-outputs: [In-flight goals plus PRs, Next-work proposals, Blocked items surfaced]
-tier: lite
-user_invocable: true
-disable_model_invocation: false
-modes: [default]
-composes_with: [value-prop, kiss, roadmap-reconcile]
----
-
-# /sprint
-
-## What you get
-
-A quick session-start view of the project. Where you are and what to do next.
-
-`/sprint` reads the active goal. It walks the parent-goal thread. It checks the parent roadmap. It lists open issues by tier. It proposes 3-4 shapes with trade-offs.
-
-You see the whole thread. Not just the nearest open ticket. That saves you from picking the wrong work when thread context is hidden.
-
-**Tier gate (bassclef#740 Task 1.8).** `/roadmap-reconcile` ships at `tier: standard`. Lite adopters skip the reconcile dispatch at Step 6.5. Print: "/roadmap-reconcile requires bassclef standard. Skipping drift check." Resolve tier via `lib/tier-check.sh`.
-
-## When to use it
-
-Type `/sprint` at the start of any session where you need to re-orient. Also after a long break. Also after a compaction. Also when you finish a goal and want a next-work menu.
-
-`/sprint` is read-only. It never edits files or opens issues. When you want to start work, `/sprint` points you at `/autonomous start` or `/longrun prep`.
-
-## When NOT to use
-
-Do not use `/sprint` to dispatch work. That is `/autonomous start` or `/longrun prep`. Do not use it to modify state. It is read-only. Do not use it mid-session when the goal is already active. Use `/whereami` for a quick check. Do not use it to reconcile the roadmap. That is `/roadmap-reconcile`.
-
-## FAQ
-
-### Why walk the parent-goal thread?
-
-The active goal has a parent_bet. That parent has its own parent_drivers. A phase may have paused steps, open audit-drop tickets, and sibling goals feeding it.
-
-Picking the nearest open ticket without reading the thread hides that context. `/sprint` walks up first. Active goal. Parent_bet. Parent_roadmap. Parent_drivers. Then it proposes.
-
-### What are the orientation gates and when do they refuse to render?
-
-Two session-start hooks fire on feature branches:
-
-- `state/markers/orientation-gate/<branch-slug>.marker` — confirms the agent read the active goal's parent_drivers. Plus parent_bet. Plus open bassclef-evolution issues.
-- `state/markers/roadmap-reconcile-gate/<branch-slug>.marker` — confirms `/roadmap-reconcile --dry-run` ran. Either no drift, or drift resolved, or explicitly deferred.
-
-When either marker is missing on the current feature branch, `/sprint` refuses to render Step 7 (the proposal). Emit a one-line note pointing at the BLOCKED block. Offer two paths — resolve, or defer per `.claude/rules/blocked-items.md`. Silence is not deferral. On main this step is silent.
-
-### What do the tiers mean in the open-issues list?
-
-- **Tier 1 — Paused steps in the active thread.** The active goal's open acceptance items. Plus the parent goal's open acceptance.
-- **Tier 2 — Audit-drop tickets cited in the thread's parent_drivers.** The upstream clusters this thread is meant to resolve.
-- **Tier 3 — New tickets that match thread scope.** Filed after the goal opened but not yet absorbed.
-- **Tier 4 — Strategic.** Larger scope, next cycle, deliberately deferred.
-
-Tier order reflects the thread, not the label. A bare issue number without a one-line description is an ID, not an option.
-
-### What columns does the proposed options table carry?
-
-<!-- FKGL-EXEMPT: column-catalog enumeration; each parenthetical names the axis pair -->
-At minimum: `Option`, `Scope`, `Compounds` (where the payoff shows up plus how often it fires), `Adopter benefit` (mechanism plus visibility), `Risk`, `Trade-off`.
-<!-- /FKGL-EXEMPT -->
-
-Option names are typeable letters — a, b, c, d. The recommendation is one sentence at the end. It cites the compounding sequence plus risk class.
-
-### What if the release pipeline is stuck?
-
-On bassclef-upstream sessions only, `/sprint` calls the release status accessor. It surfaces the result before proposing next work. A stuck release PR is higher priority than fresh scope.
-
-Rules:
-
-- No open release PR plus no commits ahead — silent.
-- No open PR plus commits ahead — one line: "Substrate is N commits ahead of public. Run /release --supersede when ready."
-- Open PR younger than 24 hours plus green CI — one line: "Release PR #N is fresh. Merge when reviewed."
-- Open PR younger than 24 hours plus red CI — Tier 1 candidate: "Release PR #N CI is red. Diagnose before merging."
-- Open PR older than 24 hours — Tier 1 candidate at the top of the list.
-
-Adopter sessions skip this call entirely.
-
-### What are the rules for the shape proposal?
-
-Every option carries a value-prop per `.claude/rules/plan-enumeration-needs-value-props.md`. Bare issue numbers are IDs. Not options.
-
-<!-- FKGL-EXEMPT: procedure-spec cross-reference block naming axes + memory slugs -->
-Compounding sequence analysis per option carries five axes. Where the payoff shows up. How often it fires. What must be true first. Does it teach a shape later work reuses. What breaks if half-done. Per `/longrun prep` Step 1.5.
-
-Adopter benefit analysis carries three axes per Step 1.6. Mechanism. Visibility. Action.
-
-Option labels are typeable letters per memory `feedback_keyboard_typeable_options`.
-<!-- /FKGL-EXEMPT -->
-
-## Details below the fold
-
-### Procedure
-
-**Step 0** — Lead with a `/value-prop tweet` claim (≤180 chars) plus a `/kiss words` grade-10 summary (2-3 sentences). This is what the operator reads first on mobile. Tables come after.
-
-**Step 1** — Orientation gates. Check `state/markers/orientation-gate/<branch-slug>.marker`. Check `state/markers/roadmap-reconcile-gate/<branch-slug>.marker`. When either is missing on a feature branch, refuse Step 7. Point at the BLOCKED block. On main this step is silent.
-
-**Step 2** — Walk the parent chain before reading leaf state. Read the active goal's parent_drivers via `state_iteration_bet_active`. Walk up to parent_bet when present. Walk further until parent_goal is null. Read parent_roadmap when any goal in the chain has one. Fetch its `last_event` and `next_pending` via `state_roadmap_get`. Surface active goal plus parent goal plus parent roadmap plus combined parent_drivers.
-
-**Step 3** — Read project state via `bash scripts/state.sh get whereami` (spine v0). Falls back to `docs/whereami.md` on pre-spine repos. Extract phase. Active goal. Active agents. Subsystem phases. Gate progress. When a whereami staleness BLOCKED fired, resolve it before continuing. Do not reconstruct state from session logs plus git log. That is the anti-pattern the rule closes.
-
-**Step 3.5** — Release pipeline status (bassclef-upstream only). Source `lib/state.sh`. Call `state_whereami_release_status`. Surface per the rules in the FAQ above. Skip on adopter sessions.
-
-**Step 4** — Read the current goal detail. Follow the `iteration_bet:` path from whereami. Show goal name. Phase. Subsystem. Primary luminary. Time budget remaining (steps you spend at your current pace before cutting scope). Status. Open acceptance criteria (Tier 1 candidates). Items marked out of scope. When whereami says "none — between iterations", suggest `/autonomous start` or the `next_bet` field. When the repo is fully cold, route to Step 7d instead. A fully cold repo has no active goal. It has no `next_bet`. It has no canvas. It has no roadmap.
-
-**Note on time budget:** the number is calibrated to your working pace with your current LLM setup. Bassclef bets file 40-800 steps depending on scope shape. Past goal actuals ground the estimate per `.claude/rules/turn-estimate-grounding.md`.
-
-**Note on shape labels:** the shape labels (a, b, c, d) are typeable letters so you can pick from your phone. Greek and emoji labels are refused per memory `feedback_keyboard_typeable_options`.
-
-**Step 5** — Show open issues by tier. Read `gh issue list --state open --json number,title,labels --limit 30`. Plus any sibling repos listed in `substrate.config.md` under `bassclef_evolution_child_repos`. Present in the four tiers above. Each row: `#NNNN — title — one-line description`. A bare number without description is an ID. Not an option.
-
-**Step 6** — Session context. Commits since last session log. Stale artifacts (session logs, journal entries, architect reviews). Whereami `last_updated` age (surface when older than 3 days but not yet BLOCKED).
-
-**Step 6.5** — Complete lookback. List every open item before you propose shapes. `parent_drivers` names what the parent knew. This step names what is open now. Parity with `/longrun` Step 0.65 per bassclef-upstream#812.
-
-Cover each class:
-
-- Every ticket named in whereami recap sections. The `operator_recap` and `prior_operator_recap` blocks list them by number.
-- Every entry from a grade audit that reads above the ceiling.
-- Every deferred, paused, or stuck item from a prior recap.
-- Every canvas at `docs/canvases/` and curation doc at `docs/curation/`.
-- Every consultation output at `docs/operator-private/consultations/` tied to open threads.
-- Chained skills that lite skills dispatch. Read tier tags of skills the active goal calls. Lite work needs to know which chained skills need inlining or tagging.
-
-Silence on any class is not deferral. Enumerate the items or state which classes are out of scope this session and why.
-
-**Step 6.6** — Read active canvases. List `docs/canvases/*.md`. For each canvas whose frontmatter carries `verification_status: draft` or `accepted`, Read the full body before proposing shapes. Cite the canvas file path plus the Q number that informs each shape. Whereami recap is a summary. Read the canvas file for the source. Closes bassclef-upstream#813.
-
-**Step 7** — Propose next sprint. Present 3-4 options in card + scan-table shape (parity with `/longrun prep` Steps 1.4e + 1.5-1.7). Full spec at `standards/scannable-multi-option-output.md`.
-
-**Step 7a** — Section-anchor rule (Norman + Garrett). Every block ships under a distinct `###` header. One anchor per concern. Between top-level anchors, use at least 2 blank lines OR a horizontal rule.
-
-**Step 7b** — Delta rendering. When operator asks for a refinement, render ONLY the delta. Cite the source anchor by name.
-
-**Step 7c** — Card + scan-table shape (per goal 24e; Tufte + Prater). Output has three parts. First, a compact scan-table (`### Compare options` — columns `Option`, `Scope`, `Turns`, `Compounds`, `Risk`; glyphs 🟢/🟡/🔴 encode risk). Second, one card per option (`### <label> · <scope> · <turns> · <risk>` with **Problem** + **Value** + **Compounds** + **Adopter**). Third, step cards for the recommended option only (progressive disclosure). See `standards/scannable-multi-option-output.md`.
-
-<!-- FKGL-EXEMPT: column-catalog + step-refusal rule enumeration -->
-Table minimum columns: `Option`, `Scope`, `Compounds`, `Adopter benefit`, `Risk`, `Trade-off`. Option labels are typeable letters. Recommendation at the end: one sentence citing compounding sequence plus risk class. Refuse this step when Step 1 gates are open.
-<!-- /FKGL-EXEMPT -->
-
-**Step 7d** — Brownfield fallback (per bassclef-web#93). Fires when the repo is cold — turn-1 for a new adopter who has not authored strategic docs yet. Trigger condition:
-
-- Whereami has no `iteration_bet` field AND no `next_bet` field, AND
-- `docs/canvases/` is empty or missing, AND
-- `docs/roadmaps/` is empty or missing
-
-In this state, the parent-goal walk at Step 2 finds no thread. The active-goal read at Step 4 returns "between goals". The normal `/sprint` proposal has nothing to build on.
-
-Instead of refusing to render, `/sprint` reads three fallback sources:
-
-- `gh issue list --state open --limit 20` — the open work the operator has already filed
-- `git log --oneline -20` — recent commits that signal current focus
-- `README.md` first section — the repo's own self-description
-
-From these sources, propose 3 candidate options in the same card + scan-table shape (Step 7c). Cite the source per option — for example, "From your open issues #NNN + recent commits on `<area>`". The value-prop per option comes from what the source itself says, not from a strategic doc.
-
-End with a plain-English hint pointing the adopter at ways to sharpen future runs:
-
-> Want sharper option proposals next time? Author strategic docs first — `/lean-canvas` (business model), `/spec` (buildable spec), or `/user-stories` (INVEST backlog). These feed `/sprint` on future calls.
-
-The fallback is opt-in on the hint side. The adopter does NOT need to author strategic docs to get value from this call. This mirrors `/onboard-repo` Path B "greenfield-from-intent" — the skill produces useful output on its first fire, and hints at deeper flows without gating on them.
-
-Note per risk ledger R2: production fixture harness for this fallback path uses a brownfield fixture (no canvas, no whereami) so the fallback runs under test. Adding that fixture ships as a follow-on when the fallback surface gets its first Tier 0 test.
-
-### Self-check step — before posting the sprint proposal
-
-Before posting Step 7, I:
-
-1. Touch `state/markers/turn-prose-surface/sprint_proposal.marker`.
-<!-- FKGL-EXEMPT: two-flag description — reference sentence -->
-2. Dispatch `/kiss words --rewrite` on the full draft. Every part passes. Not just the opener. Actual skill call. The two-flag form runs vocabulary substitution AND six heuristic checks. The skill reads `standards/bassclef-internal-jargon.md` per bassclef#907.
-<!-- /FKGL-EXEMPT -->
-3. Apply the rewrite. Accept the pass when /kiss returns no changes.
-4. Cite the dispatched skill inline per `.claude/rules/operator-facing-prose.md` Rule 3.
-5. Post the response.
-
-The Stop hook `.claude/hooks/turn-prose-kiss-check.sh` reads the marker. It runs strict mode for the sprint_proposal surface. This self-check catches misses before you read. The full-draft dispatch closes bassclef-upstream#858. Prior shape called /kiss at the opener only.
-
-### Output format
-
-```
-## Sprint status
-
-[Flash — what the last goal delivered, ≤180 chars, plain language]
-
-[Kiss summary — 2-3 sentences, grade-10 vocabulary]
-
----
-
-### Thread context
-
-Active goal: [slug] — [status]
-Parent goal: [slug or "none"] — [status]
-Parent roadmap: [title or "none"] — last event: [event]
-Parent drivers: [N items]
-
-### Release pipeline (bassclef-upstream only)
-
-[One line per Step 3.5 rules; silent on adopter sessions or clean state]
-
-### Active goal detail
-
-[name] — [status]
-Phase: [phase] | Subsystem: [subsystem]
-Primary luminary: [name or "none"]
-Time budget: [remaining] of [total]
-Acceptance open: [N items]
-
-### Open issues by tier
-
-**Tier 1 — Paused steps in active thread (N)**
-- #NNNN — title — one-line description
-
-**Tier 2 — Audit-drops in thread (N)**
-- #NNNN — title — one-line description
-
-**Tier 3 — New in thread scope (N)**
-- #NNNN — title — one-line description
-
-**Tier 4 — Strategic (N)**
-- #NNNN — title — one-line description
-
-### Proposed shapes
-
-[Table with shape / scope / compounds / adopter benefit / risk / trade-off]
-
-My recommendation: [one sentence citing compounding + risk].
-
-### Session context
-
-Last session log: YYYY-MM-DD (N commits since)
-Stale artifacts: [list or "none"]
-```
-
-### Rules
-
-- Read-only. Never modify files or open issues.
-- Always check GitHub for current issue state. Do not rely on memory.
-- Tier classification is by thread role. Not by label.
-- When the operator wants to start the proposed sprint, suggest `/autonomous start` or `/longrun prep`.
-- Options carry a value-prop per `.claude/rules/plan-enumeration-needs-value-props.md`. Bare issue numbers are IDs. Not options.
-- Orientation gates refuse to render Step 7. Direct the operator to resolve the BLOCKED block from the session-start hook first.
-- SKILL body edits carry a `/kiss` pass on the whole file per `.claude/rules/operator-facing-prose.md` Rule 2.
-
-### Grace window on old vocabulary
-
-Old vocabulary — `bet`, `appetite`, `WU`, `parent bet`, `arc`, `chronicle` — still works through 2026-10-31 per ADR-031 and `.claude/rules/we-dont-break-adopters.md`. The old `/chronicle` skill name still resolves alongside `/session-log`.
-
-Adopters mid-flight who read prior session logs see the old vocabulary. A mapping table at `standards/bassclef-internal-jargon.md` documents the old to new pairs. Both terms mean the same thing during the grace window.
-
-### Common failure modes and how /sprint handles them
-
-- **Whereami is stale.** Session-start hook surfaces BLOCKED. `/sprint` resolves before Step 7, or the operator defers explicitly.
-- **No active goal.** Whereami says "none — between iterations". `/sprint` suggests `/autonomous start` or reads the `next_bet` field.
-- **Cold brownfield repo (turn-1 adopter).** Whereami has no active goal AND no canvas AND no roadmap. Step 7d fires. `/sprint` proposes 3 shapes from open issues + git log + README, plus a hint pointing at `/lean-canvas` and `/spec` for future runs.
-- **Orientation gates missing.** Step 1 refuses to render Step 7. Operator resolves or defers per `.claude/rules/blocked-items.md`.
-- **Release pipeline stuck.** Step 3.5 flags a stuck PR as Tier 1 candidate before other work.
-
-### What /sprint does NOT do
-
-- `/sprint` never modifies files.
-- `/sprint` never opens or closes GitHub issues.
-- `/sprint` never dispatches a `/longrun` on its own. It points you at `/autonomous start` or `/longrun prep` when you want to start work.
-- `/sprint` is not a substitute for `/whereami`. Whereami is a snapshot at a moment. `/sprint` is a menu for the next move.
-- `/sprint` does not read from memory or session summaries. Every fresh call reads the current state from disk and GitHub.
-
-## Examples
-
-<!-- FKGL-EXEMPT: sample /sprint output -->
-
-```
-=== /sprint ===
-Thread: goal 2026-07-19k Shape e (parent: 19j ADR-044)
-Active goal: WU-7 /sprint refactor
-Release pipeline: 4 PRs open (#807-#810), no stuck cures
-
-Open issues by tier:
-  Tier 1 (must fix): #800 FKGL-EXEMPT, #799 ADR-044 gate — both shipped
-  Tier 2 (should fix): #795 auto-regen baselines
-  Tier 3 (nice to have): #804 vocab-registry hooks
-
-Proposed shapes:
-  a. Continue Wave 1 (/longrun deferred)
-  b. Switch to /session-end + closeout
-  c. Start #795 auto-regen mechanism
-```
-
-<!-- /FKGL-EXEMPT -->
-
-## Anti-patterns and INSTEAD
-
-| Anti-pattern | INSTEAD |
-|---|---|
-| Read only the active goal without walking the thread | Walk parent-goal until root; the thread carries context the leaf loses |
-| Skip roadmap-reconcile check before proposing | Run reconcile first; drift changes what "next" means |
-| Propose scope without a value prop per shape | Each shape carries a claim + sharpener per plan-enumeration rule |
-| Ship a proposal without release pipeline status | Stuck cures block downstream work; surface them first |
-| Present bare ticket numbers as options | Options need a value prop; bare numbers are labels, not choices |
-
-## Composes with — cluster shape
-
-`/sprint` sits at the center of a small cluster. Skills around it feed in, close out, or fire mid-verb as helpers.
-
-**Upstream — feed the verb:**
-
-- `/whereami` — reads project state that `/sprint` orients against
-
-**Downstream — where the picked shape goes:**
-
-- `/longrun prep` — the multi-goal dispatch target
-- `/autonomous start` — the dispatch target when operator picks a single-goal shape
-
-**Helpers — fire mid-verb:**
-
-- `/roadmap-reconcile` — dry-run at Step 0.5
-- `/value-prop` — flash claim per shape
-- `/kiss` — applied to proposal prose before post
-
-The verb is porcelain (Git's word for a small user-typed command). Sam or Louis types `/sprint` and the cluster runs itself.
-
-## Distinct from
-
-- `/whereami` — one-glance state snapshot. `/sprint` is scope proposal + shapes.
-- `/whats-the-plan` — dispatch-path plan for the current task. `/sprint` proposes what's next.
-- `/longrun prep` — starts a long autonomous run. `/sprint` shows what to run.
-- `/roadmap-reconcile` — reconciles drift. `/sprint` reads reconciled state.
-
-## Rules
-
-- Do not propose shapes without value props. INSTEAD, each shape carries claim + sharpener.
-- Do not skip the parent-goal thread walk. INSTEAD, walk recursively to root.
-- Do not skip the release pipeline status check on bassclef-upstream. INSTEAD, surface stuck cures.
-- Always run `/roadmap-reconcile --dry-run` before proposing shapes.
-- Always render open issues by tier, not by number.
-
-## Test cases
-
-<!-- FKGL-EXEMPT: structured test spec -->
-| ID | Prompt | Expected behavior |
-|---|---|---|
-| T1 | `/sprint` at session start on a feature branch | Thread walk + active goal + open issues + 3-4 shapes with value props |
-| T2 | `/sprint` when no active goal | Report "between goals"; propose candidate goals from open issues |
-| T3 | `/sprint` when release pipeline has stuck cures | Surface stuck cures at top of the proposal |
-| T4 | `/sprint` when roadmap-reconcile detects drift | Surface drift diff; wait for acknowledgement before proposing shapes |
-| T5 | `/sprint` mid-session with active goal | Return quick check; recommend `/whereami` instead of full proposal |
-| T6 | `/sprint` on cold brownfield repo (no goal, no canvas, no roadmap) | Step 7d fires; 3 shapes proposed from open issues + git log + README; hint at `/lean-canvas` and `/spec` for future runs |
-<!-- /FKGL-EXEMPT -->
-
-## Sources read
-
-<!-- FKGL-EXEMPT: reference list -->
-### Sources list
-
-- ADR-040 planning-skill vocabulary and lite profile
-- `.claude/rules/plain-english-discipline.md`
-- `.claude/rules/we-dont-break-adopters.md`
-- `.claude/rules/plan-enumeration-needs-value-props.md`
-- `.claude/rules/blocked-items.md`
-- `.claude/rules/whereami-load-bearing.md`
-- `.claude/rules/accessor-library-discipline.md`
-- `.claude/rules/operator-facing-prose.md`
-- `standards/bassclef-internal-jargon.md`
-- `docs/iteration-bets/2026-06-20a-longrun-sprint-orientation-cure.md`
-- `.claude/hooks/session-reflection.d/55-orientation-gate.sh`
-- `.claude/hooks/session-reflection.d/56-roadmap-reconcile-gate.sh`
-- `.claude/skills/roadmap-reconcile/SKILL.md`
-- `.claude/skills/longrun/SKILL.md`
-- `.claude/luminaries/don-norman.md` — signifiers + mapping + feedback lens for Steps 7a + 7b (per bassclef-upstream#853)
-- `.claude/luminaries/jesse-james-garrett.md` — five planes lens for section-anchor discipline
-- `.claude/luminaries/sophia-prater.md` — OOUX + progressive disclosure lens for Step 7c card format
-- `.claude/luminaries/edward-tufte.md` — data-ink + glyph-encodes-data lens for scan-table
-- `docs/personas/sam.md` — primary reader (15-30 min budget; bounces on friction)
-- `docs/personas/2026-07-12-bet11c-louis.md` — secondary reader (skims group headings first)
-- `standards/scannable-multi-option-output.md` — full 12 principles + card template + glyph legend
-- bassclef-upstream#853 — parent ticket for the anchor + delta rules
-- bassclef-upstream#830 — Shape to Option rename (applied to lines 61 + 63 + 87 + 130 of this file)
-- bassclef-web#93 — Step 7d fallback for cold brownfield repos
-- `.claude/skills/onboard-repo/SKILL.md` — Path B precedent for skills that work without prior artifacts
-<!-- /FKGL-EXEMPT -->
-
-## Why this skill exists
-
-<!-- FKGL-EXEMPT: rationale prose -->
-Session start without orientation costs 20-40 turns per re-entry. Operators pick the nearest open ticket without thread context. That leads to work that turns out to be blocked or superseded. `/sprint` walks the parent-goal thread, checks release pipeline status, reads reconciled roadmap, and lists open issues by tier. The proposed shapes carry value props per option. Without `/sprint`, session start is archaeology.
-<!-- /FKGL-EXEMPT -->