Session end

Run this when the user ends a session. It keeps the docs true, short and ready for the next session. The next session starts a hook (scripts/session-start-check.sh). It reads the marker docs/SESSION-END. If code changed after the marker, the new session runs this procedure first.

Procedure

1. Find what changed. Read docs/SESSION-END (line 1: a commit hash and a date). Run git log --oneline <hash>..HEAD and git diff --stat <hash>..HEAD. With no marker, use the commits of this session.
2. docs/HANDOFF.md: say what is true now and what the next session must do.
   • Put a short "Done" list of this session first (one line for each item), then the open work in the order to do it.
   • Delete every item that is done. Do not keep history: git log has it. For a change of design write one line: "Was: X. Is: Y."
   • Keep the rules and the facts that stay true. Cut the rest.
3. docs/STATUS.md (if the repo has it): move each changed feature to the right list (works and seen, needs work, not seen yet, not built).
4. Fix stale facts. For each file that changed, search the docs for its name and path (grep -rn). Check each fact against the code, never against memory. Fix what is wrong. A path in backticks must exist.
5. docs/ARCHITECTURE.md (if the repo has it): update it when a part, a flow or a reason changed.
6. If the project keeps notes for the agent (a memory folder), delete the ones that are now wrong and update the ones that changed. Do not save what the code or git log already says.
7. Run sh <this skill folder>/scripts/docs-lint.sh from the repo root. Fix every finding. To fix a size finding, cut text. Do not move text into a new file.
8. Commit the docs: "Session end YYYY-MM-DD". Write the marker: line 1 is git rev-parse HEAD and the date. Commit the marker alone. Push only when the project rules or the user say so.
9. Tell the user in 3 lines: what changed in the docs, what is open, what the next session does first.

How long a doc is

• A doc is long enough to say what is true now, and not longer. Cut history, repeated facts, finished plans and lists of done work.
• Do not add a section for one fact. Do not copy what the code says (names, line numbers, option lists) unless the reader needs it to act.
• One topic lives in one file. Link to it. Do not write it twice.
• Default limits (the lint checks them): docs/HANDOFF.md 12 KB, docs/STATUS.md 6 KB, README.md 12 KB, any other doc 16 KB. A repo can set its own in docs/.docs-limits (one line each: path bytes).
• A reference doc (a protocol, an API) can be longer on purpose. Give it its own limit in docs/.docs-limits.

The lint

scripts/docs-lint.sh checks, in the current git repo:

• the size of each .md file against its limit;
• each path in backticks (a file name or a path with a slash) names a tracked file;
• the handoff has no "Older" or "History" section. It prints one line for each problem and exits 1 when it finds one. It changes no file.