Wrap

Goal: after this, a fresh session (/clear) resumes from /yah:where alone. State lives in STATE.md, or in beads if the repo already uses it. Docs, memory and chat never hold progress.

1. Read the state

Run with Bash, exactly:

PY "${CLAUDE_SKILL_DIR}/../../scripts/where.py" --json --no-gh

PY is python on Windows and python3 elsewhere; use py -3 only if both fail.

Note state.plan (its spec is the plan file), state.phase (label, branch, id), store, git.branch, git.dirty, protected and next_stale.

next_stale set means commits landed after NEXT was written, so it may already be done. Run git log --oneline <next_stale.sha>..<next_stale.branch> and write the new NEXT from where those commits leave off.

store says where the plan is written; never work that out yourself. If store.note is set, tell the user first.

• store.kind is beads and state.plan is set: use 2b.
• Otherwise use 2a, STATE.md.

Run every bd command in this skill as store.bd, quoted. Never set, export or follow BEADS_DIR, and never run bd against a database outside this repo.

2a. STATE.md: write today's entry

Edit the file at store.path, or create it if it does not exist. In a linked worktree that is the main checkout's, which outlives the worktree.

• Add a ## YYYY-MM-DD entry for today (or rewrite today's), with - Next: <NEXT line> first and at most 3 short lines after it: what is done, what is half-done and where, any trap.
• The NEXT line is what /yah:where prints as NEXT: one concrete action someone could start cold, at most 140 characters. Example: "Run make eval, then paste the table into PR #9".
• After a tiny task done while a plan phase is open, NEXT goes back to that phase's step, so the plan picks up again.
• In the ## Plan: section, keep the phase lines (the outermost checkboxes) true: [x] done, exactly one [~] current, [ ] open, with | branch X | base Y | PR #N fields. Indented checkbox lines under a phase are its sub-tasks.
• While a phase is open, add 1 to 3 handoff lines indented under its phase line, plain, not checkboxes: - Done: <what>, - Tried: <what> failed because <why>, - Decided: <what> because <why>. They are the phase's log, which the next session reads before it starts. New lines go below the older ones. Keep only the newest 6; delete older ones.
• A new follow-up becomes a - [ ] <title> line under ## Follow-ups (add the section if missing), never prose. Mark one being worked on [~]. Delete finished ones; the commit or PR is their record.
• Delete a ## Plan: section whose phases are all [x] once none of their PRs is open (gh pr view <N> --json state). The plan file and the PRs keep its history, and the file the model reads each session stays short.
• A step only the user can do (a review, a merge, a console step) ends with (you), and names the command that does it when there is one, ready to paste in a terminal: Merge PR #13: gh pr merge 13 --merge (you). /yah:where lists the open ones as waiting on the user.
• Keep only the 5 newest dated entries; delete older ones. Leave anything else in the file alone, above all the AIM: line under the # title: never move, reword or delete it.

2b. Beads: rewrite the phase bead's notes

Replace the notes with --notes, never --append-notes: each wrap rewrites NEXT, so the whole notes field is written again.

bd update <phase-id> --notes "<NEXT line> <the phase's log: the newest 6 Done/Tried/Decided lines, with this session's added>"

• The NEXT rules in 2a apply to the first line; the log lines follow the rules in 2a.
• A new follow-up becomes a bead (bd create "<title>" --silent), never prose. A step only the user can do gets -l human. Close finished ones: bd close <id>.

3. Brain note (only if the brain folder exists)

The folder is docs/brain at the repo root, unless yah's config sets brain_dir. No folder: skip this step.

Ask: did this session establish a durable project fact or decision a future session would otherwise rediscover (a constraint, convention, gotcha, or decision with its reason)? Progress belongs in NEXT; personal preferences belong in memory. If no, skip. If yes, write at most one note.

Run PY "${CLAUDE_SKILL_DIR}/../../scripts/brain.py" find <key words>, then:

• A listed note already holds the fact: edit it in place only if a detail changed, then run brain.py index.
• The fact replaces a listed note: brain.py new ... --supersedes <old-slug>. Never delete a note.
• Otherwise: brain.py new --title "<fact>" --tldr "<one line, 200 chars or fewer>" --tags a,b --paths "<globs>" --source "<evidence>".

The source must be evidence: a PR, commit sha, issue, URL, path/to/file:line, or user, YYYY-MM-DD when the user stated it. A fact you inferred gets no --source; it goes to _pending.md for the user to review.

Stage what brain.py wrote (the note and INDEX.md, or _pending.md) with the WIP commit.

4. Commit work in progress, then stamp NEXT

Commit only if git.dirty > 0, step 3 wrote a note, or step 2a changed a STATE.md the repo tracks.

• Never commit on a branch in protected (trunks, the PROD branch, and where open PRs land). If you are on one, stop and tell the user.
• Run git status, then stage files by name. Never stage .env*, credentials, or large generated files the repo does not already track. Stage STATE.md only if the repo already tracks it.
• git commit -m "wip(<phase label>): <what>". Do not push unless step 6 applies.

Always stamp NEXT with the commit it was written at, so /yah:where flags it once later commits make it stale:

• STATE.md or NOW.md the repo does not track: put - At: <git rev-parse --short HEAD> right under - Next:. A tracked one needs no stamp; its own commit is the stamp.
• Beads: bd update <phase-id> --set-metadata next_sha=$(git rev-parse HEAD).

5. Memory

Save only durable, non-obvious lessons: a trap, a user preference, a fact that cost time to learn. Progress and status never go into memory. Update an existing memory rather than add a duplicate.

If this project's auto-memory index (MEMORY.md in its memory folder under $CLAUDE_CONFIG_DIR or ~/.claude) is over 100 lines, say so and offer to prune it.

6. Only if the phase is complete

The phase's done-when in the plan file (state.plan.spec: the path in ## Plan: <name> (<path>), or the epic's spec_id) is met and the tests pass.

1. Review the branch diff: run /code-review --fix, then /simplify, if available. Re-run the tests.
2. Push the feature branch in a Bash call of its own, with nothing chained to it; open the PR in the next call. Never push a branch in protected.
3. Open the PR into the phase's base (base, else the plan's target branch), following the project's title convention. If the base is another phase's branch, say so in the body. Move the phase's log lines into the body. Write the body to a temp file outside the repo, add the phase's map with PY "${CLAUDE_SKILL_DIR}/../../scripts/phasemap.py" P<n> --into <file> --no-gh (STATE.md or beads holds the PR numbers), and pass it with --body-file <file>, never --body: the run's deny rules can match words in an inline body. Updating an open PR, refresh its map the same way: gh pr view <N> --json body -q .body into the file, --into, then gh pr edit <N> --body-file <file>.
4. Record it. STATE.md: mark the phase [x], add | PR #<N> and delete its log lines. Beads: bd update <phase-id> --external-ref gh-<N>, then bd close <phase-id> --reason "PR #<N> open". Then refresh the PR's map as in step 3, so it shows the phase done with its PR.
5. Claim the next phase and give it a NEXT line, stamped as in step 4. STATE.md: mark it [~]. Beads: bd update <next-id> --claim.
6. No phase left in this plan, and another ## Plan: section has a phase with a - Parked: NEXT was <NEXT> line under it (STATE.md only): claim that phase. Mark it [~], take NEXT from its Parked line, stamped as in step 4, and delete the Parked line. The merge of this PR becomes a (you) follow-up with its command.

Merging is always the user's.

6.5 Hand the open phase to a run

Skip this step under /yah:resume: a run's own session never starts or stops a run. Skip it too when the user ended a run in this session, or chose to go on by hand after one ended: never restart a run unasked. Otherwise run step 1's command again and go on only when all of these hold:

• A plan phase is open (the one wrapped, or the one step 6 claimed), and its line does not end with (you).
• NEXT does not start with NEEDS-HUMAN:.
• No run is live: run is null or run.alive is not true.
• The tree is clean: git.dirty is 0, not counting a STATE.md the repo does not track.

Then run PY "${CLAUDE_SKILL_DIR}/../../scripts/run.py" --plan --detach in a Bash call of its own, --detach last. Exit 0: use the finish line for a started run. Any other exit: show its output and use the finish line for an open phase.

7. Finish with exactly this

Saved   <phase label> NEXT = <the NEXT line>
Commit  <short sha or none>   PR <#N or none>
Merge   <the merge command>
<finish line>

The merge command is the one the user pastes in a terminal: gh pr merge <N> --merge. For a PR stacked on another PR, it is gh pr edit <N> --base <that PR's base> once that PR merges, then gh pr merge <N> --merge. Leave the Merge line out when no PR is open, or when /yah:where shows auto-merge: on for it.

The finish line, when step 6.5 started the run:

The run has <phase label>; this session can close. `/yah:where` or `yah <project>` shows its RUN line.

Otherwise, when a plan phase is still open (the one wrapped, or the one step 6 claimed):

Safe to /clear. Then /yah:auto, or `yah <project>` from a terminal, hands <phase label> to autopilot (a detached `yah run --plan`); `/yah:auto here` works it by hand.

With no plan phase open:

Safe to /clear. Then /yah:auto, or `yah <project>` from a terminal, picks up from NEXT.