session-report

name	session-report
description	Close a work step with a resumable session report. Use at the end of every step/PR so a fresh session can pick up exactly where this one left off. Updates the canonical docs/STATUS.md and appends a dated report under docs/sessions/.

Session report (close a work step)

Produce the artifacts that let a new session resume with zero context loss. Run this at the end of each step/PR, before stopping.

1. Gather the real state (don't guess)

date +%F                       # the report's date / filename prefix
git branch --show-current
git status --short

Then run the quality gate and record the result:

• pnpm gate (typecheck + biome + arch + tests with coverage + knip + jscpd).
• Mutation testing locally (Stryker). If the step touched @app/core (the mutated scope), run pnpm test:mutation and report the score in the gate section. The CI post-merge run is a backstop, not the gate — surviving mutants must be caught before the PR, while the code is fresh. Skip only when the step touched no mutated package (say so).
• Don't fabricate a green check — report failures honestly.

2. Append a dated session report

• Copy docs/sessions/_TEMPLATE.md to docs/sessions/<YYYY-MM-DD>-<slug>.md (slug = the step). Never overwrite an existing report — history is append-only.
• Fill every section honestly: Done, Not done / remaining, Decisions, Gate status (with the results from step 1), State to resume from.
• "State to resume from" must name the SINGLE next action and any gotchas / half-done edits.

3. Update the canonical STATUS

Edit docs/STATUS.md:

• Update the roadmap / progress: what's done, in-progress, next.
• Update "Where we are" (branch, current step, next step).
• Record any open decision that got resolved this session.

4. Keep memory in sync (optional, if the plan shifted)

If a durable cross-session decision changed (an invariant, a resolved open question, a scope change), capture it. Don't duplicate the whole report — just the durable decision.

5. Commit the report on the feature branch — BEFORE the PR

The report + STATUS update describe the work the PR contains, so they ship inside the PR — never as a separate post-merge commit on main.

• Commit them on the feature branch, before gh pr create. Order per feature: feature commits → this report commit → pnpm gate → push → open PR → merge.
• Phrase the report for the pre-merge state ("PR #N opened", branch still current) — not as if it were already merged.
• The doc-only-direct-to-main exception (see the block-commit-on-main hook) is only for a standalone report not tied to a code PR; a report that accompanies code goes in that code's PR.

Output

End with a 3-line summary to the user: what's done, the next action, and the report path.