@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/.claude/skills/session-end/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: session-end
+description: "Close the session cleanly. Writes the session log, pushes artifacts, updates whereami. Run when the Stop hook fails or when you want to end deliberately. Three tiers of obligation: MUST, SHOULD, MAY."
+problem: "Sessions end without writing state. Next session starts cold. Session logs missing."
+value: "Three tiers of close. Must-tier always runs local. Should-tier pushes if network is up."
+inputs: [Optional — run explicitly or fires from Stop hook]
+outputs: [Session log entry, Whereami updated, Push and tag when scoped, Journal draft when notable]
+tier: lite
+user_invocable: true
+disable_model_invocation: false
+modes: [default]
+composes_with: [chronicle, whereami, kiss, journal, retro, clean-artifacts, promote, roadmap-reconcile]
+---
+
+# /session-end
+
+## What you get
+
+A clean session close with three tiers of obligation.
+
+`/session-end` saves state. It writes the session log. It updates whereami. It reconciles the roadmap. It pushes artifacts.
+
+The MUST tier always runs. No network needed. Your session log lands even when the session is dying. SHOULD and MAY tiers depend on network. They fail gracefully.
+
+The Stop hook calls `/session-end` on its own. You also run it directly when the hook fails or when you want to end deliberately.
+
+## When to use it
+
+- The Stop hook failed or timed out.
+- You are ending a session by hand before Stop fires.
+- You want artifacts written before a long pause.
+- You are in a cloud or mobile session where hooks may not fire.
+
+The MUST tier is the safety net. Even when session context is exhausted, `/session-end` writes the session log locally before it stops.
+
+## When NOT to use
+
+Do not run `/session-end` mid-session. It writes closing artifacts. Do not use it for the retrospective. That is `/retro`. Do not use it to reconcile the roadmap alone. That is `/roadmap-reconcile`. Do not use it for adopter-facing entries. That is `/journal`.
+
+## Tier gate (bassclef#740 Task 1.3; amended 2026-08-25)
+
+Steps 5, 11, 12 below dispatch skills at `tier: standard`. Step 15 now sources `lib/clean-artifacts-sweep.sh` inline for every tier — the lib is `tier: lite` and ships to every adopter. Resolve the adopter tier through `lib/tier-check.sh`:
+
+```bash
+source lib/tier-check.sh
+tier=$(resolve_adopter_tier)
+```
+
+Lite adopters skip Steps 5, 11, 12. Print "requires bassclef standard. Skipping." Continue. Steps to skip — `/roadmap-reconcile` (Step 5; lives at standard tier; lite adopters carry no `strategy/canvases/` or `docs/roadmaps/`), `/journal` (Step 11; standard tier), `/visual-review` + `/synthetic-user` (Step 12; standard tier). Step 15 runs for every tier via the shared lib. Standalone `/clean-artifacts` skill stays live for standard adopters. Per canvas Q6 Option E.
+
+## FAQ
+
+### What are the three tiers?
+
+- **MUST** — local. No network. Always possible. Save state. Capture timing. Write session log. Update whereami. Reconcile roadmap. Update memory. Remove session lock. Sweep for skipped obligations. When the session can execute any code at all, these should work.
+- **SHOULD** — network needed. May fail. Auto-tag on goal close. Git push. Journal draft plus corpus push. Readiness sweep for UI changes. Fail gracefully. Do not kill the MUST tier.
+- **MAY** — conditional. Environment-dependent. Danger-mode summary. Release notes. Clean workflow exhaust. Skip without guilt when the environment does not support them.
+
+### What does the MUST tier do, in order?
+
+1. **Explicit save-state.** Run `bash .claude/hooks/save-state.sh`. It commits uncommitted changes. It pushes. It writes `.claude/LAST_SAVE` with timestamp and machine. It removes `.claude/SESSION_LOCK`. The next session-start hook reads `.claude/LAST_SAVE` to surface open threads as BLOCKED badges. When save-state is missing, fall back to `git commit -m "chore: session-end checkpoint" && git push && rm -f .claude/SESSION_LOCK`. Surface the missing-hook gap.
+2. **Capture session timing.** The session-end hook computes started_at, ended_at, and duration_minutes. Use those exact values. Do not estimate. When the hook output is missing, fall back to reading `/tmp/claude-session-timing-*` for started_at. Use `date +"%Y-%m-%dT%H:%M:%S%z"` for ended_at.
+3. **Session log entry.** Start from `templates/chronicle-template.md`. Fill in frontmatter. Fill in body sections — Entry State, Work Done, Decisions, Open Threads, Key Files Changed. Populate the Gate Evidence table using the bash snippet in the template. The pre-commit hook BLOCKS commits missing this section per bassclef#298. Write to `chronicle/` (bassclef) or `docs/chronicle/` (app repos) per the project-directory-layout standard.
+4. **Update `docs/whereami.md`.** Set `last_updated` to current UTC ISO-8601 timestamp. Set `session` to the session log filename just written. Draft an `operator_recap` in three sentences max at grade 10 plain English. Update any field that changed.
+5. **Roadmap reconcile.** Fire `/roadmap-reconcile --apply`. The skill is idempotent. It runs `--dry-run` first internally. When the diff is empty, skip the write. When the diff is non-empty, apply edits to bring roadmap in line with whereami plus session log plus merged PRs. This closes the drift class named at bassclef#776. Failure surfaces a one-line note in the session log's open-threads section and continues.
+6. **Memory update.** Save anything learned this session that future sessions need — preferences discovered, project context that changed, feedback received.
+7. **Remove session lock.** `rm -f .claude/SESSION_LOCK`. Usually handled by save-state.sh.
+8. **Sweep for skipped obligations.** For every MUST or SHOULD step skipped without explicit deferral, write a deferred-action entry so the next session picks it up. Silence is not deferral per `.claude/rules/session-artifacts.md`.
+8a. **Move resolved rescue entries.** When steps 1-7 all pass, move every rescue file under `docs/deferred-actions/*-session-rescue.md` to the `completed/` subdir. The `session-end.sh` hook does this on the same Stop event via `lib/session-rescue.sh`. This step names the discipline in the skill body. Idempotent. See goal 2026-07-31e and `.claude/rules/bootstrap-pair-discipline.md`.
+
+### What does the SHOULD tier do?
+
+9. **Auto-tag on goal close.** When a goal closed this session, bump the patch version tag (e.g., v0.6.0 → v0.7.0). Minor bump when scope was large (5+ issues). Major is manual only. `git tag -a vX.Y.Z -m "[goal name]"` and `git push --tags`. Skip when no goal closed.
+10. **Git push.** `git push || echo "WARNING: push failed — run manually"`.
+11. **Journal draft plus corpus push.** Ask — "Did this session produce a notable decision, trade-off, or insight worth sharing?" When yes, check for gaps. Backfill first when needed. Write to the journal draft path. Push to the journal Google Doc and to the brand-team corpus doc.
+12. **Readiness sweep.** When the session made commits modifying UI surfaces, run `/visual-review` on each changed surface. Both viewports — desktop and mobile. Also run `/synthetic-user` Tier 3 on the primary user journey. Findings roll into the session log's Open Threads section.
+
+### What does the MAY tier do?
+
+13. **Danger-mode summary.** When the session used auto-complete, write to `docs/danger-mode-summaries/YYYY-MM-DD.md`. What was done on its own. What decisions were made without human confirmation. Any risks introduced.
+14. **Release notes.** When user-visible changes deployed, write to `docs/release-notes/YYYY-MM-DD.md`. Plain language for the least technical stakeholder.
+15. **Clean workflow exhaust.** Source `lib/clean-artifacts-sweep.sh`. Call `clean_artifacts_sweep --delete`. The lib sweeps three classes. Stale verify markers. Old Playwright screenshots. Expired SDLC traces. The safety list holds four exclusions. Current branch marker. Current session timing. Files under `.claude/` (CHECKPOINT + SESSION_LOCK + LAST_SAVE). Any git-tracked file. Every tier runs this step now. Lite gains cleanup that used to skip. Standalone `/clean-artifacts` skill stays live for standard adopters.
+
+### What is the checkpoint integration?
+
+When `.claude/CHECKPOINT.md` exists at session end:
+
+1. Read it. Understand what was in progress. Understand what exit condition fired.
+2. Include the checkpoint state in the session log entry. What was done. What was left.
+3. After the session log lands and commits, delete the checkpoint. `rm .claude/CHECKPOINT.md`. The session log is now the permanent record.
+4. When the checkpoint shows uncommitted in-progress work, surface it. "Uncommitted work found — [description]. Review before next session."
+
+See `standards/graceful-exit.md` for the checkpoint format and recovery protocol.
+
+### What are the timeout budgets?
+
+- Minimum Stop hook timeout — **30 seconds** per `standards/hook-idempotency.md`.
+- MUST tier target — complete in under 10 seconds.
+- SHOULD tier target — complete in under 15 seconds.
+- MAY tier target — best-effort in remaining time.
+
+When the total exceeds 30 seconds, the MUST tier is already done. Timeout only loses SHOULD and MAY artifacts. Those recover next session.
+
+## Details below the fold
+
+### Execution order
+
+```
+MUST tier (always runs, no network needed):
+  1. Explicit save-state (bash .claude/hooks/save-state.sh)
+  2. Capture session timing (started_at, ended_at, duration, turns, closes)
+  3. Session log entry (with timing frontmatter + gate evidence table)
+  4. Update docs/whereami.md (last_updated + session + operator_recap + changed fields)
+  5. Roadmap reconcile (/roadmap-reconcile --apply, idempotent)
+  6. Memory update
+  7. Remove session lock (handled by save-state.sh)
+  8. Sweep for skipped obligations
+  ── if any MUST step fails: log error, continue to next MUST step ──
+
+SHOULD tier (network needed, graceful failure):
+  9. Auto-tag on goal close (bump patch, push tag)
+  10. Git push (handled by save-state.sh; retry if needed)
+  11. Journal draft + corpus push (if notable)
+  12. Readiness sweep — /visual-review + /synthetic-user Tier 3 (if UI touched)
+  ── if any SHOULD step fails: warn, continue ──
+
+MAY tier (conditional):
+  13. Danger-mode summary (if applicable)
+  14. Release notes (if deployed)
+  15. Clean workflow exhaust (source lib/clean-artifacts-sweep.sh; runs for every tier)
+  ── if any MAY step fails: skip silently ──
+```
+
+### Hook integration
+
+The Stop hook calls this skill as its primary action:
+
+```bash
+#!/bin/bash
+# .claude/hooks/session-end.sh
+# Minimum timeout: 30 seconds per standards/hook-idempotency.md
+
+# Phase 1: Local artifacts (MUST tier — always runs)
+# If the skill fails to load, at minimum do:
+#   git add -A && git commit -m "chore: auto-save" || true
+#   rm -f .claude/SESSION_LOCK
+
+# Phase 2: The skill handles SHOULD and MAY tiers
+# These can timeout without losing MUST tier artifacts
+```
+
+When the Stop hook times out before completing, the MUST tier artifacts (commit, session log, lock cleanup) should already be written. They execute first. They have no network dependency.
+
+### Self-check step — before writing the session log
+
+Before writing the session log body, I:
+
+1. Touch `state/markers/turn-prose-surface/longrun_closeout.marker` when this closes a `/longrun` session.
+2. Read the draft `operator_recap` against `standards/bassclef-internal-jargon.md` BLOCK terms.
+3. Rewrite any BLOCK matches in plain English.
+4. Write the session log entry.
+
+The Stop hook `.claude/hooks/turn-prose-kiss-check.sh` catches misses.
+
+### Rules
+
+- MUST tier steps never depend on network.
+- MUST tier steps never depend on external services (Google Docs and similar).
+- Each tier runs on its own. A failure in SHOULD does not skip MAY.
+- Log all failures visibly. Do not swallow errors with `2>/dev/null || true`.
+- When invoked by hand, report what was completed and what was skipped.
+- The Gate Evidence table in the session log is required, not optional per bassclef#298.
+
+### Common failure modes and recovery
+
+- **Hook timeout.** MUST tier already ran. SHOULD and MAY artifacts recover on the next session's start-of-session sweep.
+- **Push failed.** MUST tier stored artifacts locally. Next session's save-state retries. `.claude/LAST_SAVE` timestamp signals to the next session that the push is owed.
+- **Session log missing gate evidence.** Pre-commit hook BLOCKS the commit per bassclef#298. Auto-populate via the bash snippet in `templates/chronicle-template.md`.
+- **Journal push failed.** SHOULD tier logs the failure. Draft persists for a manual push next session.
+- **Roadmap reconcile errored.** Note in the session log's open-threads section and continue. Do not block session close on infrastructure failure.
+
+### What /session-end does NOT do
+
+- `/session-end` never dispatches new work. It closes what happened.
+- `/session-end` never modifies git history. It appends artifacts.
+- `/session-end` never runs long-form tasks in the MUST tier. Network work belongs in SHOULD or MAY.
+- `/session-end` never skips the Gate Evidence table. Silence is not deferral.
+- `/session-end` never fabricates timing. Missing hook output falls back to explicit sources. Estimates are marked as such.
+
+### When /session-end is different from /longrun closeout
+
+`/longrun closeout` composes `/session-end`. The `/longrun` mode adds a retrospective. It adds a `/promote` audit. It adds insight extraction on top of what `/session-end` does. When you ran a long session, invoke `/longrun closeout`. When you ran a short session, invoke `/session-end` directly. Both write the session log. Both update whereami.
+
+### Grace window on old vocabulary
+
+Old vocabulary — `bet`, `appetite`, `step`, `chronicle` — still works through 2026-10-31 per ADR-031 and the we-dont-break-adopters rule. Existing skill names like `/chronicle` still resolve alongside new names like `/session-log` during the same window. Templates and hooks accept both terms.
+
+## Examples
+
+<!-- FKGL-EXEMPT: sample close output -->
+
+**MUST tier output (local-only, always runs):**
+
+```
+=== /session-end MUST ===
+- Session log written: chronicle/2026-07-19k-shape-e-foundation.md
+- Whereami updated: docs/whereami.md
+- Deferred actions swept: 0 pending
+- Local commit: 6d0ee38e
+```
+
+**SHOULD tier (network; graceful failure):**
+
+```
+=== /session-end SHOULD ===
+- git push origin feature/2026-07-19k-*: OK
+- Journal draft pushed to Google Doc: OK
+- Wiki refresh: skipped (no material surface change)
+```
+
+<!-- /FKGL-EXEMPT -->
+
+## Anti-patterns and INSTEAD
+
+| Anti-pattern | INSTEAD |
+|---|---|
+| Run `/session-end` mid-session | Wait for the natural close; timing needs both start + end |
+| Skip the MUST tier because network is down | The MUST tier is local-only; it runs regardless |
+| Skip the Gate Evidence table in the log | Copy the template + fill counts from marker files |
+| Silence a MUST tier failure and end anyway | Fix the failure or write a deferred action |
+| Fold retrospective + journal into the log | `/retro` and `/journal` are separate artifacts |
+
+## Composes with
+
+- `/session-log` — writes the session log at MUST tier.
+- `/whereami` — read as input; updated as MUST tier output.
+- `/retro` — reflection at close.
+- `/journal` — writes for external readers at SHOULD tier.
+- `/kiss` — applied to prose before write.
+- `/promote` — audit backstop for missed patterns.
+- `/roadmap-reconcile` — reconciles drift at SHOULD tier.
+
+## Distinct from
+
+- `/longrun closeout` — runs the whole autonomous session close. `/session-end` writes artifacts.
+- `/retro` — reflects on what worked. `/session-end` writes state artifacts.
+- `/journal` — writes for external readers. `/session-end` writes the operator record.
+- `/clean-artifacts` — sweeps workflow exhaust. `/session-end` writes fresh artifacts.
+
+## Rules
+
+- Do not run `/session-end` mid-session. INSTEAD, wait for the natural close.
+- Do not skip the MUST tier. INSTEAD, write local artifacts even when network is down.
+- Do not fold retrospective into the session log. INSTEAD, run `/retro` separately.
+- Always write the session log before pushing to remote.
+- Always update whereami as part of MUST tier output.
+
+## Test cases
+
+<!-- FKGL-EXEMPT: structured test spec -->
+| ID | Prompt | Expected behavior |
+|---|---|---|
+| T1 | `/session-end` at natural session close | MUST tier writes log + whereami; SHOULD tier pushes if network up |
+| T2 | `/session-end` with no network | MUST tier lands; SHOULD tier gracefully degrades |
+| T3 | Stop hook fails; agent invokes `/session-end` | Same artifacts write as if Stop hook fired |
+| T4 | `/session-end` when session-log already exists for today | New file gets letter suffix |
+| T5 | `/session-end` when deferred actions surface | Sweep into `docs/deferred-actions/` and cite in log |
+<!-- /FKGL-EXEMPT -->
+
+## Sources read
+
+<!-- FKGL-EXEMPT: reference list -->
+- ADR-040 planning-skill vocabulary and lite profile
+- `.claude/rules/plain-english-discipline.md`
+- `.claude/rules/we-dont-break-adopters.md`
+- `.claude/rules/whereami-load-bearing.md`
+- `.claude/rules/session-artifacts.md`
+- `standards/sdlc-compliance.md` — Gate Evidence discipline (bassclef#298)
+- `standards/project-directory-layout.md`
+- `standards/graceful-exit.md`
+- `standards/hook-idempotency.md`
+- `templates/chronicle-template.md`
+- `templates/deferred-action-template.md`
+- `.claude/skills/roadmap-reconcile/SKILL.md`
+- `.claude/skills/chronicle/SKILL.md`
+- `standards/bassclef-internal-jargon.md`
+- bassclef-upstream#298 — Gate Evidence table required
+- bassclef-upstream#599 — explicit save-state
+- bassclef-upstream#776 — roadmap-reconcile drift class
+- bassclef-upstream#143 — whereami-load-bearing update discipline
+- bassclef-upstream#226 WS-3 — sweep skipped obligations into deferred actions
+- bassclef-upstream#574 — readiness sweep for UI touches
+- bassclef-upstream#907 — /kiss wordlist source of truth
+- `.claude/skills/journal/SKILL.md` — journal draft plus corpus push
+- `.claude/skills/clean-artifacts/SKILL.md` — sweep workflow exhaust
+- `.claude/skills/visual-review/SKILL.md` — UI surface review
+- `.claude/skills/synthetic-user/SKILL.md` — persona-aware journeys
+- `.claude/skills/retro/SKILL.md` — retrospective composition
+- `.claude/skills/promote/SKILL.md` — audit backstop
+- `.claude/skills/longrun/SKILL.md` — closeout composes /session-end
+<!-- /FKGL-EXEMPT -->
+
+## Why this skill exists
+
+Sessions that end without clean artifacts leak state. The next session starts cold. Session logs go missing. Whereami goes stale. Journal drafts pile up unpushed. The MUST tier of `/session-end` writes local artifacts even when the network is down or context is exhausted. The SHOULD tier pushes when network is available. Without `/session-end`, the operator faces an archaeology task at every next session start.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/session-log/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: session-log
+description: "Write the session's log entry \u2014 what shipped, what was decided, what's still open. Reads the day's commits and conversation. Outputs a markdown entry with gates fired, sources read, and discoveries surfaced. Renamed from /chronicle."
+problem: "Session logs get lost between mid-session interrupts and Stop hook races. Next session has no memory."
+value: "One log entry that names what shipped and what was decided and what's still open."
+inputs: [Optional Gate Evidence auto-populate flag]
+outputs: [Session log entry at chronicle/*, Gate Evidence table populated]
+tier: lite
+user_invocable: true
+disable_model_invocation: false
+modes: [default]
+composes_with: [kiss, promote, retro]
+---
+
+# /session-log
+
+## What you get
+
+A timestamped markdown record of what happened this session. `/session-log` reads the day's commits, walks the conversation, and outputs a session log entry with frontmatter (timing, closes) plus body sections (Entry State, Work Done, Decisions, Open Threads, Key Files Changed). The Gate Evidence table lands with authoritative counts from marker files. The next session reads Open Threads first. `/session-log` was called `/chronicle` before 2026-07-17; both names work through 2026-10-31.
+
+## When to use it
+
+Run `/session-log` at session end before close. `/session-end` calls it as part of the MUST tier. If you want to write the log alone (rare — usually it composes with a longer close), invoke `/session-log` directly.
+
+## When NOT to use
+
+Do not run `/session-log` mid-session. Wait for session end. Do not run it for a session with zero substantive work. Skip the entry that day. Do not run it to write a retrospective. That is `/retro`. Do not run it to update `docs/whereami.md`. That is `/session-end`.
+
+## Tier gate (bassclef#740 Task 1.5)
+
+`/session-log` runs at `tier: lite`. It writes files locally. It calls no standard-tier skills. Lite adopters run it as documented. The body names `/retro` in "When NOT to use" — `/retro` ships at `tier: standard`. Lite adopters skip `/retro`. `/retro` requires bassclef standard. Write a two-line note in Open Threads instead. Resolve tier via `lib/tier-check.sh`. Per canvas Q6 Option E.
+
+## FAQ
+
+### What was this skill called before?
+
+`/chronicle`. Renamed to `/session-log` per ADR-040 Decision 1 (vocabulary rename). Both names work through 2026-10-31 per `.claude/rules/we-dont-break-adopters.md`. After the grace window ends, only `/session-log` resolves.
+
+The artifact directory names stay as `chronicle/` (bassclef) and `docs/chronicle/` (app repos) during the same window. Renaming the directories is a separate migration; the SKILL name change happens first.
+
+### What sections does the log entry have?
+
+Frontmatter:
+
+- `started_at`, `ended_at`, `duration_minutes` — deterministic timing from the session-end hook
+- `turns` — approximate conversation turns
+- `closes` — issues resolved this session (e.g., `["#123", "#456"]`)
+
+Body sections:
+
+- **Entry State** — where the project was at session start
+- **Work Done** — what shipped in one to three paragraphs
+- **Decisions** — non-obvious choices, why, alternatives considered
+- **Open Threads** — what remains, in priority order; the next session reads this first
+- **Key Files Changed** — path list with a one-line description each
+- **Gate Evidence** — table showing which gates fired this session per branch
+- **Promotable Patterns** — novel patterns that would help in a different repo
+
+The template at `templates/chronicle-template.md` carries the exact shape. Copy it and fill in the fields; do not invent ad-hoc structures. Ad-hoc structures silently drop the Gate Evidence table per bassclef#298.
+
+### Why is the Gate Evidence table required?
+
+The pre-commit hook BLOCKS commits missing `## Gate Evidence` per bassclef#298. The section is the authoritative record for the 5-session rolling gate-compliance counter that fires at session start. Skipping it produces "verify-compliance 0% / temperance-compliance 0%" BLOCKED items at the next session's start.
+
+Auto-populate via the bash snippet in `templates/chronicle-template.md`. Use `state_marker_count <category> <since-days>` from `lib/state.sh` for spine v0 repos; falls back to `[ -f state/markers/<gate>/<branch-slug>.marker ]` on pre-spine repos.
+
+### Where does the log entry write?
+
+- Bassclef repos: `chronicle/{YYYY-MM-DD}-{slug}.md`
+- App repos: `docs/chronicle/{YYYY-MM-DD}-{slug}.md`
+
+Per `standards/project-directory-layout.md`. If an entry already exists for today, append a letter suffix: `{date}b-{slug}.md`.
+
+The directory name stays as `chronicle/` during the grace window. A separate migration renames the directory to `session-log/` after the SKILL rename settles.
+
+### What plain-English discipline applies?
+
+Before writing, pass narrative content through `/kiss words`. The session log is operator-narrative — voice trumps strict rule, but bassclef-internal jargon (per `standards/bassclef-internal-jargon.md`) still gets substituted. The substrate-clarity-gate hook emits ADVISORY notices for jargon, long sentences, and passive voice. Treat the advisory as a checklist before commit.
+
+Standard tech vocab stays (API, hook, schema, ORM). Only bassclef-internal terms get replaced.
+
+### What are Promotable Patterns and when do I add them?
+
+Before finalizing the entry, ask: "Did this session produce a novel diagnostic approach, workaround, or workflow improvement that would help in a *different* repo?" If yes, add a `## Promotable Patterns` section:
+
+```markdown
+## Promotable Patterns
+
+- **Pattern name** — one-sentence description → /promote candidate
+```
+
+Then run `/promote` before session-end closes. This catches pattern-level discoveries that the pre-commit hook (file-level only) misses.
+
+## Details below the fold
+
+### Procedure
+
+**Step 1** — List recent session logs via accessor to understand sequence and format:
+
+```bash
+bash scripts/state.sh get reference chronicle <id>
+# or via lib:
+source lib/state.sh && state_chronicle_list --recent 3
+```
+
+Body content of past entries is operator-readable per `.claude/rules/accessor-library-discipline.md`. Read with `cat chronicle/<id>.md` after listing.
+
+**Step 2** — Run `git log --oneline` to see what committed this session.
+
+**Step 3** — Determine today's date and pick a descriptive slug for the session's work.
+
+**Step 4** — Capture timing data via deterministic measurement:
+
+- Run `bash scripts/longrun-telemetry.sh <session-id>` for the harness session ID. Populates `peak_input_tokens`, `compaction_count`, `total_turns` from the authoritative JSONL log.
+- When the harness session ID is not accessible (rare edge case), fall back to reading `state/markers/session-timing/` for the hook-recorded timestamp; use that as `started_at`, compute `ended_at` from `git log --format=%aI` on last session commit. Flag `appetite_actuals.estimate_method: fallback` in frontmatter so the next reader sees the data is estimated.
+- `turns` — approximate conversation turns.
+- `closes` — list any issues resolved this session.
+
+**Step 5** — Summarize accomplishments, decisions, and open threads.
+
+**Step 6** — Fill in the Gate Evidence table. Use `state_marker_count` for verified firings; falls back to direct marker file checks for pre-spine repos:
+
+```bash
+source lib/state.sh 2>/dev/null
+BRANCH_SLUG=$(git branch --show-current | tr '/' '-')
+
+if command -v state_marker_count >/dev/null; then
+  [ "$(state_marker_count temperance 7)" -gt 0 ] && echo "temperance: yes"
+  [ "$(state_marker_count diagnose 7)" -gt 0 ] && echo "diagnose: yes"
+  [ "$(state_marker_count verify 7)" -gt 0 ] && echo "verify: yes"
+else
+  [ -f "state/markers/temperance/${BRANCH_SLUG}.marker" ] && echo "temperance: yes"
+  [ -f "state/markers/diagnose/${BRANCH_SLUG}.marker" ] && echo "diagnose: yes"
+  [ -f "state/markers/verify/${BRANCH_SLUG}.marker" ] && echo "verify: yes"
+fi
+```
+
+Marker absent (count 0) means the gate did NOT fire this session for that branch.
+
+**Step 7** — Validate before commit:
+
+```bash
+CHRONICLE=chronicle/{YYYY-MM-DD}-{slug}.md   # or docs/chronicle/...
+grep -qiE "^## Gate (E|e)vidence" "$CHRONICLE" || echo "MISSING — fix before commit"
+```
+
+The pre-commit hook performs the same check mechanically; this is the agent-side equivalent so failures surface at write time.
+
+### Self-check step — before writing the log entry
+
+Before writing the log body, I:
+
+1. Read the draft against `standards/bassclef-internal-jargon.md` BLOCK terms.
+2. Rewrite any BLOCK matches in plain English per `/kiss words`.
+3. Verify the Gate Evidence table is populated.
+4. Write the file and commit.
+
+The pre-commit hook catches missing Gate Evidence. The substrate-clarity-gate hook emits ADVISORY on jargon leaks.
+
+### Rules
+
+- Open Threads is the most important section. The next session reads it first.
+- Be factual, not promotional. Record what happened; do not editorialize.
+- Tags should be specific enough to filter by later.
+- Every entry MUST include a Gate Evidence table. Silence is not deferral per `.claude/rules/session-artifacts.md`.
+- Use `templates/chronicle-template.md` as-is. Do not invent ad-hoc section structures.
+
+### Common failure modes
+
+- **Gate Evidence missing.** Pre-commit hook BLOCKS. Auto-populate via template snippet.
+- **Timing missing.** Fall back to `state/markers/session-timing/` timestamp plus git log tail. Flag `estimate_method: fallback` in frontmatter.
+- **Two entries same day.** Append letter suffix: `{date}b-{slug}.md`.
+- **Ad-hoc structure.** Rejected. Copy the template.
+- **Bassclef jargon in narrative.** Substrate-clarity-gate emits ADVISORY. Rewrite before commit.
+
+### What /session-log does NOT do — INSTEAD guidance
+
+- Does not open issues or PRs.
+  INSTEAD: use `/promote` for that; run it before `/session-end` closes.
+- Does not modify the roadmap.
+  INSTEAD: `/roadmap-reconcile` runs at the MUST tier of `/session-end` and handles roadmap edits.
+- Does not run long network work.
+  INSTEAD: write local files and validate them here; SHOULD-tier network work belongs in `/session-end`.
+- Does not invent timing when hook output is missing.
+  INSTEAD: use the explicit fallback sources (`state/markers/session-timing/`, `git log --format=%aI`) and mark the frontmatter `estimate_method: fallback`.
+- Does not edit prior entries.
+  INSTEAD: write a new entry; corrections go in the next session's Decisions section.
+
+### When to write more than one entry per day
+
+If a single date carries two distinct work sessions (morning + evening, or goal A + goal B on the same day), write two files: `{date}-{first-slug}.md` and `{date}b-{second-slug}.md`. The letter suffix disambiguates. The `/session-end` skill picks the next available letter automatically.
+
+### Grace window on old vocabulary and skill name
+
+Old vocabulary (bet → goal, step → step, chronicle → session log) still works through 2026-10-31 per ADR-031 and `.claude/rules/we-dont-break-adopters.md`. The old skill name `/chronicle` still resolves alongside `/session-log` during the same window. The rename registers in `standards/file-renames.json` per the bassclef file-rename discipline (standard tier).
+
+Artifact directory names (`chronicle/`, `docs/chronicle/`) stay during this grace window. A separate migration handles the directory rename after the SKILL rename settles.
+
+## Examples
+
+<!-- FKGL-EXEMPT: sample entry -->
+
+**Frontmatter of a shipped entry:**
+
+```yaml
+---
+started_at: 2026-07-19T18:00:00+0100
+ended_at: 2026-07-19T22:15:00+0100
+duration_minutes: 255
+turns: 340
+closes: ["#800", "#799"]
+---
+```
+
+**Body section shape:**
+
+```markdown
+## Entry State
+Construction phase. Goal 19j closed. Wave 1 refactor not started.
+
+## Work Done
+Shipped 4 PRs across foundation cures + first Wave 1 skill refactor...
+
+## Gate Evidence
+| Gate | Fired | Marker path |
+|---|---|---|
+| Temperance | 3 | state/markers/temperance/... |
+```
+
+<!-- /FKGL-EXEMPT -->
+
+## Anti-patterns and INSTEAD
+
+| Anti-pattern | INSTEAD |
+|---|---|
+| Skip the Gate Evidence table | Copy the template and fill counts from marker files |
+| Invent ad-hoc section names | Use the 7 body sections named in FAQ Q2 |
+| Write the entry mid-session | Wait for session end; the timing block needs start + end |
+| Rebuild timing from memory | Read `scripts/longrun-telemetry.sh` output at session end |
+| Fold the retrospective into the log | Retrospectives live in `/retro`; the log is a record |
+
+## Composes with
+
+- `/session-end` — calls `/session-log` as part of the MUST tier.
+- `/kiss` — applied to prose before write.
+- `/promote` — reads Promotable Patterns for candidate tickets.
+- `/retro` — sits alongside the log at session end.
+
+## Distinct from
+
+- `/session-end` — runs the whole close. `/session-log` writes one file.
+- `/retro` — reflects on what worked. `/session-log` records what shipped.
+- `/journal` — writes for an outside reader. `/session-log` writes for the operator.
+- `/chronicle` — old alias during the grace window through 2026-10-31.
+
+## Rules
+
+- Do not skip the Gate Evidence table. INSTEAD, copy the template + fill counts from markers.
+- Do not invent section names. INSTEAD, use the 7 body sections in FAQ Q2.
+- Do not write mid-session. INSTEAD, wait for session end.
+- Always cite marker paths in Gate Evidence rows.
+- Always run the plain-English self-check before write.
+
+## Test cases
+
+<!-- FKGL-EXEMPT: structured test spec -->
+| ID | Prompt | Expected behavior |
+|---|---|---|
+| T1 | `/session-log` at session end after 3 PRs shipped | Entry lands with all 7 body sections + Gate Evidence + closes list |
+| T2 | `/session-log` when zero commits this session | Skip entry OR write minimal "no substantive work" note |
+| T3 | `/session-log` when a second entry lands same date | File uses letter suffix (2026-07-19b-...) |
+| T4 | `/session-log` when a Promotable Pattern surfaces | Pattern lands in section with slug + one line |
+| T5 | Old skill name `/chronicle` invoked | Resolves to `/session-log` during grace window |
+<!-- /FKGL-EXEMPT -->
+
+## Sources read
+
+<!-- FKGL-EXEMPT: reference list -->
+- ADR-040 planning-skill vocabulary and lite profile
+- `.claude/rules/plain-english-discipline.md`
+- `.claude/rules/we-dont-break-adopters.md`
+- file-rename-discipline (standard tier)
+- `.claude/rules/session-artifacts.md`
+- `.claude/rules/accessor-library-discipline.md`
+- `standards/sdlc-compliance.md` — Gate Evidence discipline
+- `standards/project-directory-layout.md` — session log path per repo type
+- `standards/bassclef-internal-jargon.md` — self-check wordlist
+- `standards/file-renames.json` — rename registered here
+- `templates/chronicle-template.md` — authoritative shape (path stays during grace window)
+- `scripts/longrun-telemetry.sh` — deterministic timing measurement
+- `lib/state.sh` — accessor library for `state_marker_count` and related accessors
+- bassclef-upstream#298 — Gate Evidence table required
+- bassclef-upstream#559 — plain-English discipline
+- bassclef-upstream#907 — /kiss wordlist single source of truth
+<!-- /FKGL-EXEMPT -->
+
+## Why this skill exists
+
+Session end without a written log means the next session starts cold. Operators returning after a break rebuild state from git log + open issues. That rebuild costs 20-40 turns. It often drifts into the wrong active goal. `/session-log` writes one file per session. The next session reads Open Threads first. Then Work Done. Then decides. Without `/session-log`, session-end obligations collapse. The whereami rule loses its input source.