A session log that parallel agents never conflict on

Parallel session log

Goal: every session leaves a record, and two sessions running at once never touch the same file.

Why a single log breaks

Every session adds its entry at the same place in one file. Two pull requests open at the same time both edit those lines, so the second one conflicts, and a careless resolution drops an entry. More parallel sessions means more conflicts.

The shape

• docs/progress/YYYY-MM-DD-slug.md: one file per session, named by its date and a short slug (lowercase words joined by hyphens). Names sort by date.
• docs/progress/_TEMPLATE.md: the entry template. The underscore keeps it out of the index.
• docs/PROGRESS.md: the old log, kept as history, plus an index of the session files between two markers. Sessions never edit it.
• .github/scripts/session-log-index.mjs: rebuilds the index from the folder. Run it now and then (a housekeeping pull request, or before a release), never in every session's pull request, or the index becomes the new conflict.
• .github/scripts/check-session-log.mjs: a CI check. Every file added or changed in docs/progress/ must have a valid name and the required line. Entries still added to the old log are checked too, so pull requests opened before the switch keep passing.

Steps

1. Ask what each entry must contain that CI should enforce (for example a **Harvest:**, **Risk:**, or **Tests:** line), and where the log lives today. Use their answer as the required line.
2. Read the current log. Note its template and the order entries were added in (newest first, appended at the end, or mixed). Do not reorder history.
3. Create docs/progress/_TEMPLATE.md from the existing template, with a short comment on top saying how to name the file and that the old log is not edited.
4. Rewrite only the top of the old log: say where entries go now, add a "Sessions" heading with the two index markers, and a "History" heading above the old entries. Leave every old entry as it is. Keeping the change at the top avoids conflicts with sessions that are still appending.
5. Add the two scripts from scripts/ to .github/scripts/ (Node standard library only, no dependencies). The index is rebuilt with node .github/scripts/session-log-index.mjs; offer to add a package script for it, and let the person add it.
6. Wire the check into the CI that runs on documentation changes, on pull requests, with full history (fetch-depth: 0), passing the base branch: node .github/scripts/check-session-log.mjs "origin/$BASE_REF".
7. Update every instruction that says where to log: the project's CLAUDE.md, the pull request template, contributor and deploy docs. Search for the old file name. Leave published or released material as it is.
8. Test the check before opening the pull request: a new file without the line fails, a badly named file fails, a good one passes, and the new headings in the old log do not count as entries.
9. Merge it last if other sessions are writing to the old log right now: rebase on the main branch first so their entries survive, and tell them about the new convention.

Rules

• One file per session. A long session adds sections to its own file, never a second file for the same work.
• Sessions never edit the index or the history. The folder is the record; the index may lag behind it.
• The required-line check is a nudge, not a gate on content: "none, because ..." passes.

Safety

This kit writes only the files listed in its permissions, and only after you see the change. It runs nothing on its own and never commits, pushes, or opens pull requests. The scripts read files in the repository and call git diff and git ls-files; they make no network calls.