@ulysses-ai/create-workspace 0.23.3-beta.0 → 0.24.0-beta.0

package/template/_claude/skills/braindump/SKILL.md

@@ -26,7 +26,7 @@ When called within an active work session (the active-session pointer at `.claud
   git commit -m "braindump: update {session-name} tracker"
   ```
 
-Under the task model — `workspace.sessionModel` is `"task"` in `workspace.json` AND the SessionStart hook injected a `Chat record:` line (`{chat}` is its name):
+Under the task model — `workspace.sessionModel` is `"task"` (the SessionStart hook's `Workspace config (workspace.json):` line carries it; read `workspace.json` when that line is not in context) AND the SessionStart hook injected a `Chat record:` line (`{chat}` is its name):
 
 - Default behavior: write `braindump_{topic}.md` directly into that chat's drawer at `workspace-scratchpad/chats/{chat}/` — the drawer sits outside `workspace-context/`, so `capture-context.mjs` is not involved
 - No commit for drawer writes: the drawer is gitignored and machine-local; `/complete-work` lists it and asks what to promote into `workspace-context/`

package/template/_claude/skills/complete-work/SKILL.md

@@ -23,7 +23,7 @@ node "{launcher-root}/.claude/scripts/task-worktree.mjs" --root "{launcher-root}
 - `{chat}` is the name from the `Chat record:` line the SessionStart hook injects. If that line is absent, run `node .claude/scripts/chat-record.mjs --whoami --root "{launcher-root}"` first — compaction can drop the hook line, and this recovers the name by matching the chat's session id against the records. When that too prints nothing (exit 1), omit `--chat` — detection then relies on cwd and the session id alone. Detection also matches this chat's session id against each `work-sessions/*/workspace/session.md` `chatSessions` list, so a lane chat that drove an old-model session by path is findable from the launcher. Pass `--session-id` when the id is known from somewhere else; otherwise it resolves from the chat record's `sessionId`, then `$CLAUDE_CODE_SESSION_ID`, in that order.
 - `model: session` → continue with this flow (read the session tracker as below), taking `{session-name}` from the detect result's `sessionName`. When detection ran at the launcher the result instead carries `source: "chat-sessions"` and a `sessions` list — present the entries (each `{ name, branch, workItem, status }`) and ask which to finish; `{session-name}` is the chosen entry's `name`.
 - `model: mixed` → this chat has open tasks AND sessions its id is registered in. List both — each session as `{name} ({status}, {branch})`, each task group as `{branch}` (grouping by branch as below) — and ask which to finish. A session continues this session flow with that `{session-name}`; a task goes to **Task completion (session model v2)**.
-- `model: task` → go to **Task completion (session model v2)**. The result's `tasks` come from the chat record; if several are open, ask the user which one to complete — group by branch, a multi-repo task is several entries sharing a branch.
+- `model: task` → go to **Task completion (session model v2)**. The result's `tasks` come from the chat record; if several are open, ask the user which one to complete — group by branch: a multi-repo task is several entries sharing a branch, and one issue may be open on several branches (gh:206), each its own group.
 - `model: none` → "No active work session. Nothing to complete."
 
 Read the full session tracker at `work-sessions/{session-name}/workspace/session.md` (use the frontmatter helper in `.claude/lib/session-frontmatter.mjs` — scripts and hooks use `_utils.mjs` which wraps it).
@@ -375,7 +375,7 @@ Reached from Step 1 when detection says `model: task`. The state is the branch,
 - `{defaultBranch}` — `workspace.json` → `repos.{repo}.branch`, default `main`; for `.` it is the workspace origin's HEAD with `main` as the fallback — or, when the launcher has no origin, the branch it sits on when that is `main`/`master` — exactly what `task-worktree.mjs`'s `defaultBranchFor` resolves
 - `{mode}` per repo — `forge` or `local`, resolved exactly as `task-pr.mjs` resolves it: `local` when the repo has no origin remote or its override says so (`repos.{repo}.merge`, or `workspace.merge` for `.`) — the override for a clone whose origin is a third-party upstream nobody here may push to; `forge` when its origin is a forge remote. A local repo is never pushed: it merges into its source clone in step 4.
 
-If several tasks are open, ask the user which one to complete — group by branch; a multi-repo task is several entries sharing a branch — and complete one branch at a time.
+If several tasks are open, ask the user which one to complete — group by branch: a multi-repo task is several entries sharing a branch, and one issue may be open on several branches (gh:206), each its own group — and complete one branch at a time.
 
 Notes meant for another chat are not drawer notes. The drawer is per-chat and machine-local — no other chat can read it, and this machine is its only copy — so nothing in it survives a handoff. Anything the next chat (or the operator, from another machine) needs to continue this task — decisions, gotchas, where work stopped — goes on the linked issue as a comment through the tracker adapter (`await tracker.comment("{workItem}", body)`), where every chat can read it.
 
@@ -409,15 +409,23 @@ Notes meant for another chat are not drawer notes. The drawer is per-chat and ma
      --out "{launcher-root}/workspace-scratchpad/chats/{chat}/prs-{slug}.json"
    ```
 
-   Omit `--work-item` when the task has none, and repeat `--body-file` once per forge repo. `--chat` resolves the task's repos from this chat's record entries for the branch; when detection came from cwd alone, pass `--repo "{repo}"` once per repo instead. The script resolves each repo's merge mode before doing anything else: a forge repo is pushed `-u origin {branch}` and gets one PR through a per-repo forge aimed at that worktree's own origin, never the launcher's; a local repo (no origin, or `merge: "local"`) is neither pushed nor PR'd — it is recorded as a local entry for step 4. The workspace repo (`.`) is handled exactly like a project repo. It skips repos whose branch has no commits over the base (reporting them as `empty` — no push, no PR, no body file needed, torn down in step 5 like any other; a workspace branch that collected no promotions gets no PR), and stops **before pushing anything** when a repo's origin exists but is not forge-hosted and has no `"local"` override — the error names the `workspace.json` setting (`repos.{repo}.merge`, or `workspace.merge` for `.`) that opts the repo into local mode. The PR title is the linked issue's title, or the branch's first commit subject without a `{workItem}`; the body is the drawer file with `Closes <ref>` appended, where `<ref>` is `#N` when the PR's repo is the tracker's repo and `{tracker-repo}#N` otherwise — only the first form closes an issue in the PR's own repo. If the push is rejected as non-fast-forward — the branch already existed on origin and step 1's rebase rewrote it — the script stops and says so; ask the user, and only on explicit confirmation re-run the same command with `--force-with-lease` (the script never forces on its own). If `workspace.forge` is `false` in `workspace.json` and any repo resolved to forge, the script refuses before pushing anything: forge operations are disabled in this workspace and the PR is opened by hand. `--out` writes the run's JSON to `prs-{slug}.json` for step 4 — `{ prs: [{ repo, mode, … }], empty: [repo…], pushed: [repo…] }`, printed to stdout as well — instead of shell redirection, so the command is identical on every shell. Every entry carries `commits`; a forge entry also carries `owner`, `name`, `number`, `id`, `url`, `isWorkspace`, and a local entry `branch`, `base`, `worktree`. The run is idempotent: a repo whose branch already has an open PR against `{defaultBranch}` gets that PR reused, never duplicated, and if the run fails partway the file still records what was pushed and opened so far — fix the cause and re-run the same command; it completes the set.
+   Omit `--work-item` when the task has none, and repeat `--body-file` once per forge repo. `--chat` resolves the task's repos from this chat's record entries for the branch; when detection came from cwd alone, pass `--repo "{repo}"` once per repo instead. The script resolves each repo's merge mode before doing anything else: a forge repo is pushed `-u origin {branch}` and gets one PR through a per-repo forge aimed at that worktree's own origin, never the launcher's; a local repo (no origin, or `merge: "local"`) is neither pushed nor PR'd — it is recorded as a local entry for step 4. The workspace repo (`.`) is handled exactly like a project repo. It skips repos whose branch has no commits over the base (reporting them as `empty` — no push, no PR, no body file needed, torn down in step 5 like any other; a workspace branch that collected no promotions gets no PR), and stops **before pushing anything** when a repo's origin exists but is not forge-hosted and has no `"local"` override — the error names the `workspace.json` setting (`repos.{repo}.merge`, or `workspace.merge` for `.`) that opts the repo into local mode. The PR title is the linked issue's title, or the branch's first commit subject without a `{workItem}`; the body is the drawer file with `Closes <ref>` appended, where `<ref>` is `#N` when the PR's repo is the tracker's repo and `{tracker-repo}#N` otherwise — only the first form closes an issue in the PR's own repo. If the push is rejected as non-fast-forward — the branch already existed on origin and step 1's rebase rewrote it — the script stops and says so; ask the user, and only on explicit confirmation re-run the same command with `--force-with-lease` (the script never forces on its own). If `workspace.forge` is `false` in `workspace.json` and any repo resolved to forge, the script refuses before pushing anything: forge operations are disabled in this workspace and the PR is opened by hand. `--out` writes the run's JSON to `prs-{slug}.json` for step 4 — `{ prs: [{ repo, mode, … }], empty: [repo…], pushed: [repo…] }`, printed to stdout as well — instead of shell redirection, so the command is identical on every shell. Every entry carries `commits` and `mergeApproval` — the repo's resolved merge-approval policy (gh:202: `repos.{repo}.mergeApproval`, or `workspace.mergeApproval` for the workspace repo `.`; `ask` when unset), which step 4 acts on; a forge entry also carries `owner`, `name`, `number`, `id`, `url`, `isWorkspace`, and a local entry `branch`, `base`, `worktree`. The run is idempotent: a repo whose branch already has an open PR against `{defaultBranch}` gets that PR reused, never duplicated, and if the run fails partway the file still records what was pushed and opened so far — fix the cause and re-run the same command; it completes the set.
 
-4. **Ask before merging, then run `task-pr.mjs --merge`, which also closes the linked issue.** When step 3 reported `prs: []` — every repo was empty — there is nothing to merge: skip this step, say so, and leave the linked issue open for the user to decide (close it by hand, or keep the task going); `--merge` itself refuses an empty PRs file for exactly that reason. Otherwise present a summary per repo that got an entry — forge and local alike, the workspace repo included — built from `--create`'s output, and ask once. A local repo shows `(local merge)` in place of a PR line; a mixed task asks `Merge all?`, an all-local task `Merge all locally?`:
+4. **Read the checks, then merge under the task's approval policy — `task-pr.mjs --merge` also closes the linked issue.** When step 3 reported `prs: []` — every repo was empty — there is nothing to merge: skip this step, say so, and leave the linked issue open for the user to decide (close it by hand, or keep the task going); `--merge` itself refuses an empty PRs file for exactly that reason. Otherwise read every entry's CI state — the same read `--merge` gates on:
+
+   ```bash
+   node "{launcher-root}/.claude/scripts/task-pr.mjs" --checks --root "{launcher-root}" \
+     --prs "{launcher-root}/workspace-scratchpad/chats/{chat}/prs-{slug}.json"
+   ```
+
+   One `{ repo, mode, state, url, failing }` per entry (a local repo reports `none` — no forge, no checks; a GitLab pipeline waiting on a manual job reports `pending` with a `note`). Present a summary per repo that got an entry — forge and local alike, the workspace repo included — built from `--create`'s output plus the check state. A local repo shows `(local merge)` in place of a PR line:
 
    ```
    Task complete:
 
    PROJECT: {owner}/{name}
      PR: {pr.url}
+     Checks: {success|pending|failure|none}   # failure names its failing jobs
      Branch: {branch} → {defaultBranch}
      Commits: {n}   # from the entry's `commits` count
 
@@ -426,34 +434,36 @@ Notes meant for another chat are not drawer notes. The drawer is per-chat and ma
 
    WORKSPACE: {ws-owner}/{ws-name}   # from the workspace worktree's origin, or "(local merge)"
      PR: {ws-pr.url}
+     Checks: {state}
      Branch: {branch} → {defaultBranch}
-
-   Merge all? [Y/n]
    ```
 
-   On "n", stop: the PRs stay open and the worktrees, branches, and record entries stay in place — say so.
+   The approval policy is each entry's `mergeApproval` field (gh:202), and one `operator` entry anywhere governs the whole task — the workspace PR may never merge ahead of the project PRs it describes, so the task cannot merge part-way; a context-only PR held by its task's code PRs is the accepted limitation:
+
+   - **ask** (the default) — ask once, after the summary: `Merge all? [Y/n]`, or `Merge all locally? [Y/n]` for an all-local task. On "n", stop: the PRs stay open and the worktrees, branches, and record entries stay in place — say so. On "y", run the merge command below.
+   - **operator** — do not ask and do not merge. Report the PR links with their check states and stop there; the PRs wait. The task continues when the operator explicitly says merge in a later turn — then run the merge command below with `--approved`, which the script demands for any operator entry and which this skill passes only on that say-so — or after they merge in the forge UI, where the re-run detects the already-merged PRs, skips them (no `--approved`, no checks), and carries on to the close and the teardown. A local operator entry is done the same way: once its branch is merged into the repo's default branch — by hand or an earlier run — the re-run detects the containment and asks no approval. Keep the drawer's `prs-{slug}.json` until that run happens (it is the command's input); delete the drawer's `pr-{slug}-*.md` bodies and the spent JSON only after a successful merge.
 
-   On "y":
+   The merge command — on "y" under ask, or the operator's go (add `--approved`):
 
    ```bash
    node "{launcher-root}/.claude/scripts/task-pr.mjs" --merge --root "{launcher-root}" \
      --prs "{launcher-root}/workspace-scratchpad/chats/{chat}/prs-{slug}.json" --work-item "{workItem}"
    ```
 
-   The script checks each entry's state first, then finishes the project entries — forge PRs (squash, delete branch) and local branches as `git merge --ff-only {branch}` in the repo's source clone (`repos/{repo}`, or the launcher for `.`), which must sit clean on its default branch — then the workspace entry only when every project merge succeeded: the workspace branch's promoted context describes the project merges and must never merge ahead of them. A PR the forge already reports as merged and a local branch already contained in the default branch both count as done, which is what makes a re-run safe: the run that finally gets every entry merged also does the pull and the close. A local branch that will not fast-forward stops the run and says to rebase the task branch onto the local `{defaultBranch}` and re-run. The launcher is pulled `--ff-only` only when it sits on the workspace default branch, `.` was not itself merged locally (that merge ran in the launcher — `pullSkipped: "workspace merged locally"`), the workspace repo is not local (no forge merge of `.` happened that a pull could fetch — `pullSkipped: "workspace repo is local"`), and the launcher branch has an upstream to pull from (`pullSkipped: "launcher has no upstream"`); a launcher on some other branch reports `pullSkipped: "launcher on <branch>"`, and a failed pull is reported as `pullFailed: true` rather than an error, because the merges stand and the issue still closes — a failed pull is the one case that needs the launcher pulled by hand before step 5. The close comes last, with a one-line comment naming each merged PR URL or local `{repo} {branch}->{base}`: merge precedes close because an issue closed before its PR merges points at work that never landed. It happens only when `{workItem}` is given AND a tracker is configured — without a work item or without a tracker, `closed` is `null` and the JSON says why (`closeSkipped`) — say so to the user. On any merge failure the script stops, names what is still open, and exits non-zero — nothing is torn down, and re-running `--merge` once the failure is fixed is safe. After a successful merge, delete the drawer's `pr-{slug}-*.md` body files and the spent `prs-{slug}.json`.
+   Before the first merge the script reads the checks of every forge PR that is not already merged — all of them up front, so the run is all-or-nothing (gh:201): any failure, or any entry still pending, stops it with every entry's state listed and nothing merged, not even the green PRs ahead of the red one — re-run once checks finish, or pass `--wait`, which polls every still-pending entry each 20-second round up to `--wait-timeout {min}` minutes (default 30, counted after the settle) and, once the last pending entry goes terminal, re-reads every entry once more so a PR that went green early and red during the wait is still caught. Checks can lag PR creation: a PR opened within the last 90 seconds that reports no checks is re-read before `none` is accepted — every such PR per round, one shared 30-second pause, twice at most — a fresh `none` may be a race rather than a verdict. `none` (no CI) and `success` proceed to the merges, in order, un-re-gated. `--skip-checks` bypasses the gate and is recorded as `checksSkipped` in the output — reach for it only on the user's say-so. Local entries skip checks: there is no forge to ask. Beyond the gate, the script finishes the project entries — forge PRs (squash, delete branch) and local branches as `git merge --ff-only {branch}` in the repo's source clone (`repos/{repo}`, or the launcher for `.`), which must sit clean on its default branch — then the workspace entry only when every project merge succeeded: the workspace branch's promoted context describes the project merges and must never merge ahead of them. A PR the forge already reports as merged and a local branch already contained in the default branch both count as done — and read no checks — which is what makes a re-run safe: the run that finally gets every entry merged also does the pull and the close. A local branch that will not fast-forward stops the run and says to rebase the task branch onto the local `{defaultBranch}` and re-run. The launcher is pulled `--ff-only` only when it sits on the workspace default branch, `.` was not itself merged locally (that merge ran in the launcher — `pullSkipped: "workspace merged locally"`), the workspace repo is not local (no forge merge of `.` happened that a pull could fetch — `pullSkipped: "workspace repo is local"`), and the launcher branch has an upstream to pull from (`pullSkipped: "launcher has no upstream"`); a launcher on some other branch reports `pullSkipped: "launcher on <branch>"`, and a failed pull is reported as `pullFailed: true` rather than an error, because the merges stand and the issue still closes — a failed pull is the one case that needs the launcher pulled by hand before step 5. The close comes last, with a one-line comment naming each merged PR URL or local `{repo} {branch}->{base}`: merge precedes close because an issue closed before its PR merges points at work that never landed. It happens only when `{workItem}` is given AND a tracker is configured — without a work item or without a tracker, `closed` is `null` and the JSON says why (`closeSkipped`) — say so to the user. On any merge failure the script stops, names what is still open, and exits non-zero — nothing is torn down, and re-running `--merge` once the failure is fixed is safe. After a successful merge, delete the drawer's `pr-{slug}-*.md` body files and the spent `prs-{slug}.json`.
 
 5. **Tear down only what finished — worktree first, then the record entry**, and only for a repo whose PR merged or whose local merge succeeded in step 4, or whose branch was empty and never pushed in step 3; the workspace repo included (`--repo "."`). If a repo's push, PR, or merge failed, or the user declined the merge, leave that repo's worktree, branch, and record entry exactly in place and say so: `--delete-branch` would otherwise `branch -D` commits that exist nowhere but the local worktree. For `.` the script never deletes the branch checked out at the launcher root.
 
    ```bash
    node "{launcher-root}/.claude/scripts/task-worktree.mjs" --root "{launcher-root}" --remove --repo "{repo}" --branch "{branch}" --delete-branch
-   node "{launcher-root}/.claude/scripts/chat-record.mjs" --root "{launcher-root}" --remove-task --chat "{chat}" --work-item "{workItem}" --repo "{repo}"
+   node "{launcher-root}/.claude/scripts/chat-record.mjs" --root "{launcher-root}" --remove-task --chat "{chat}" --work-item "{workItem}" --branch "{branch}" --repo "{repo}"
    ```
 
-   When the task has no `{workItem}`, drop `--work-item` and pass `--branch "{branch}"` instead — the record entry is keyed by repo + branch. Worktree first because a refusal (dirty worktree, slug collision) then leaves both the worktree and its record entry in place — nothing orphaned, safe to retry. `--delete-branch` also removes the local branch: the forge's `deleteBranch` removed only the remote one, so post-merge teardown passes it to clean the local clone; this is the only step that ever passes it. Never pass `--force` without asking the user.
+   `--branch` is always passed: one issue may be open on several branches (gh:206), and without it the removal would take every branch of the item/repo — a sibling still in flight included. When the task has no `{workItem}`, drop `--work-item` — the entry is then keyed by repo + branch, which `--branch` selects on its own. Worktree first because a refusal (dirty worktree, slug collision) then leaves both the worktree and its record entry in place — nothing orphaned, safe to retry. `--delete-branch` also removes the local branch: the forge's `deleteBranch` removed only the remote one, so post-merge teardown passes it to clean the local clone; this is the only step that ever passes it. Never pass `--force` without asking the user.
 
 ## Notes
 - The session tracker's body is the primary source for PR-body synthesis — it captures the full session history alongside specs and plans
-- All repos get PRed and merged together — one approval for all
+- All repos get PRed and merged together — one approval for all, unless a repo's `mergeApproval` says `operator` (gh:202), in which case the PRs wait for the operator's merge
 - Version bumps, tags, and publish happen in `/release`, not `/complete-work` — this avoids version drift when multiple feature branches land between releases
 - The teardown order is mandatory: project worktrees first, then workspace worktree, then prune, then delete the session folder
 - Context promotion and cleanup are intentional workflow behavior — they bypass normal commit conventions by design

package/template/_claude/skills/handoff/SKILL.md

@@ -26,7 +26,7 @@ When called within an active work session (the active-session pointer at `.claud
   git commit -m "handoff: update {session-name} tracker"
   ```
 
-Under the task model — `workspace.sessionModel` is `"task"` in `workspace.json` AND the SessionStart hook injected a `Chat record:` line (`{chat}` is its name):
+Under the task model — `workspace.sessionModel` is `"task"` (the SessionStart hook's `Workspace config (workspace.json):` line carries it; read `workspace.json` when that line is not in context) AND the SessionStart hook injected a `Chat record:` line (`{chat}` is its name):
 
 - Default behavior: write `handoff_{topic}.md` directly into that chat's drawer at `workspace-scratchpad/chats/{chat}/` — the drawer sits outside `workspace-context/`, so `capture-context.mjs` is not involved
 - No commit for drawer writes: the drawer is gitignored and machine-local; `/complete-work` lists it and asks what to promote into `workspace-context/`

package/template/_claude/skills/maintenance/SKILL.md

@@ -44,17 +44,21 @@ For each non-gitignored workspace-context `.md` and each `work-sessions/*/worksp
 ### 3. Workspace structure
 The script checks that workspace.json and CLAUDE.md are present and parseable, that `workspace-context/` and `.claude/rules`, `skills`, `scripts` directories exist, and that every manifest repo is cloned under `repos/`.
 
+It also checks the template-modification registry (`.claude/template-modifications.json`, the workspace's record of files it owns outright or deliberately edits): legacy keys still in workspace.json (`workspace.localFiles`, `workspace.templateModifications`), keys that escape `.claude/` (the registry covers `.claude/` paths only — root files are handled by their own merge paths), and registrations whose file has gone back to the template's baseline content are info — `/workspace-update` offers the cleanups. A registry that doesn't parse is a warning: its localFiles exclusions and reasons are being ignored, and the update flow stops on it.
+
 ### 4. Git state
 The script covers the launcher itself: on its default branch, tracked tree clean. Untracked paths are info — gitignored content is not counted.
 
-The worktree-level checks are not carried by the script; perform them alongside it:
+It also lists leftover Claude Code agent worktrees (gh:205). A subagent with worktree isolation gets `.claude/worktrees/agent-{id}/` on a `worktree-agent-{id}` branch — in the workspace repo and in each `repos/*/`. Claude Code removes a clean one when the subagent finishes and sweeps the rest past `cleanupPeriodDays`, but the sweep keeps any worktree holding work, and a subagent that commits without pushing is exactly that, indefinitely. Per its docs, Claude Code locks a worktree while its agent runs. Each leftover is one info finding plus a `summary.agentWorktrees` entry (`--json`) carrying the facts and a scripted verdict that fails closed: `removable` is true only when the directory still matches git's record of the worktree (not prunable, toplevel intact), the worktree is clean (untracked files count as dirty), it holds no work of its own (`commitsBeyond: 0`, or only non-merge commits whose patch-ids all landed on `base` per `git cherry` — which sees rebase and cherry-pick landings `--merged` misses; a squash merge leaves patch-ids unmatched, so a squash-merged branch is deliberately not removable), it is not locked, it has been idle for over an hour (newest of the HEAD reflog entry and the directory mtime), and no chat-record task claims the branch — records that cannot be read count as unknown, not none. `reasons` lists every failed gate. Cleanup step 9 offers removal only for `removable: true` entries — the safety call is scripted, not re-derived from prose.
+
+The remaining worktree-level checks are not carried by the script; perform them alongside it:
 - Worktrees with no recent commits? (orphaned)
 - Local branches with no remote tracking? (unpushed work)
 - Worktrees whose branch has already been merged? (cleanup candidates)
 - Orphan worktree records in project repos — run `git -C repos/{repo} worktree list` for each repo and flag any `prunable` markers. These usually come from a workspace-first teardown (the unsafe order) leaving stale admin records behind. Suggest `git worktree prune` on the affected repo.
 - Task-model state (gh:146), three checks:
   - **Unrecorded task worktrees** — list `repos/*/.claude/worktrees/*` and `.claude/worktrees/*`, read each candidate's branch (`git -C "{path}" rev-parse --abbrev-ref HEAD`), and keep only those on a task-prefixed branch (`feature/`, `bugfix/`, `chore/`) — Claude Code's own worktrees carry other branch names, so the prefix filter skips them without guessing a name convention. Cross-reference the chat records (`node .claude/scripts/chat-record.mjs --root . --list`): a task-prefixed worktree no record entry claims is *unrecorded* — it may be a legitimate no-tracker task (those are never recorded), so present it and ask before suggesting `node .claude/scripts/task-worktree.mjs --root . --remove --repo "{repo}" --branch "{branch}"`.
-  - **Stale record entries** — a record task entry whose worktree is gone (neither `repos/{repo}/.claude/worktrees/{slug}/` nor, for `repo: "."`, `.claude/worktrees/{slug}/` exists). Suggest `node .claude/scripts/chat-record.mjs --root . --remove-task --chat "{chat}" --work-item "{workItem}" --repo "{repo}"` (omit `--repo` when the entry has none).
+  - **Stale record entries** — a record task entry whose worktree is gone (neither `repos/{repo}/.claude/worktrees/{slug}/` nor, for `repo: "."`, `.claude/worktrees/{slug}/` exists). Suggest `node .claude/scripts/chat-record.mjs --root . --remove-task --chat "{chat}" --work-item "{workItem}" --branch "{branch}" --repo "{repo}"` (omit `--repo` when the entry has none). Always pass `--branch`: without it the removal takes every branch of the item/repo (gh:206), a sibling branch with a live worktree included.
   - **Merged but never completed** — a recorded task branch that already merged. Judge merged-ness by the forge's merged PRs for that repo, matching on head branch — never `git branch --merged`, which a squash merge (never an ancestor) silently misses. `/complete-work` never ran. Suggest running `/complete-work` for that branch (detection from the chat record finds it).
 
 ### 5. Workspace-context auto-file integrity
@@ -105,6 +109,7 @@ When stale candidates are found, surface them as warnings in the output format a
 - `work-sessions/{name}/` folders whose worktrees are gone — suggest cleanup
 - Session trackers whose branches have been merged — suggest `/complete-work` post-flight cleanup
 - Unrecorded task-prefixed worktrees (no chat-record entry claims them; may be no-tracker tasks) — ask, then suggest `task-worktree.mjs --remove`
+- Leftover Claude Code agent worktrees (gh:205) — the audit script's info findings (or `summary.agentWorktrees` via `--json`) carry each one's facts with a scripted `removable` verdict and the `reasons` behind it. Offer removal one worktree at a time, always asking first, and only for entries marked `removable: true` — the script has already verified the directory matches git's record of the worktree, it is clean (untracked files count as dirty), it holds no work of its own (`commitsBeyond: 0`, or only non-merge commits whose patch-ids all landed on the base per `git cherry`; a squash merge leaves patch-ids unmatched and is deliberately not removable), it is unlocked, idle for over an hour, and claimed by no chat-record task. Never widen these criteria by hand. For `removable: false` entries, report the `reasons` and leave the worktree alone — locked means locked: Claude Code considers an agent running, and nothing in this flow overrides it. Removal, run from the launcher root, is `git -C <repo-dir> worktree remove <absolute-path>` (never `-f` — a refusal means the worktree no longer matches the recorded facts) then `git -C <repo-dir> branch -D <branch>`, with `<repo-dir>` the owning repo — the workspace root itself for `repo: "."`, `repos/{repo}/` otherwise — and `<absolute-path>` the entry's `absolutePath` fact. Never touch task worktrees: task-prefixed branches never reach the agent list, and claimed agent branches are already excluded by the script.
 - Chat-record task entries whose worktree is gone — suggest `chat-record.mjs --remove-task`
 - Recorded task branches already merged (per the forge's merged PRs, not `git branch --merged`) — suggest `/complete-work`
 - Braindumps that overlap significantly — suggest merging (e.g., "workspace-branching.md and persistent-work-sessions.md cover the same topic")
@@ -217,7 +222,7 @@ OK (6):
 
 ## Flow
 
-1. Run `node .claude/scripts/maintenance-audit.mjs --root .` and present its report — it carries audit sections 1–7. Add `--offline` when there is no network (section 7 is the only network user), or `--json` when step 13's health metrics want the machine-readable `summary.canonical` / `summary.alwaysLoaded` numbers.
+1. Run `node .claude/scripts/maintenance-audit.mjs --root .` and present its report — it carries audit sections 1–7. Add `--offline` when there is no network (section 7 is the only network user), or `--json` when step 13's health metrics or cleanup step 9's agent-worktree pass want the machine-readable `summary.canonical` / `summary.alwaysLoaded` / `summary.agentWorktrees` numbers.
 2. Perform the residual checks the script does not carry — the worktree-level git checks from audit section 4 (orphaned worktrees, unpushed branches, merged worktrees, prunable worktree records, the task-model checks against `chat-record.mjs --list`).
 3. Read session-log.jsonl if it exists (feeds step 13's session log stats)
 4. If cleanup mode: run `node .claude/scripts/build-workspace-context.mjs --check --root .` — exit `0` = clean (and within budget when one is set), `1` = artifact missing or stale → regenerate with `--write`, `2` = artifacts current but canonical body over budget (only possible with a budget set). The `canonical` block in the JSON drives the triage decision; `"budget": null` means the canonical budget is off. Then compare context files pairwise for overlap and scan for stale cross-references; if the post-regen `--check` reports `over-budget`, enter the canonical-budget triage flow described in cleanup step 11.

package/template/_claude/skills/release/SKILL.md

@@ -37,7 +37,7 @@ Two checks before anything is pushed. First the tag: if `v{version}` already exi
 git -C repos/{repo} ls-remote --exit-code origin refs/tags/v{version}
 ```
 
-Second the release path. Build the repo's forge with `forgeConfigForRepo(root, '{repo}', ws)` from `.claude/scripts/merge-mode.mjs` — it picks the adapter from the repo's own origin, so a GitLab repo gets the gitlab adapter whatever `workspace.forge` says — and decide now who creates the release (Step 5): the repo's CI, or this skill. If the flow needs something the forge cannot do, stop here — past this point the tag is pushed, and a publish that cannot run is much harder to unwind.
+Second the release path. Build the repo's forge with `forgeConfigForRepo(root, '{repo}', ws)` from `.claude/scripts/merge-mode.mjs` — it picks the adapter from the repo's own origin, so a GitLab repo gets the gitlab adapter whatever `workspace.forge` says — and decide now who creates the release (Step 6): the repo's CI, or this skill. If the flow needs something the forge cannot do, stop here — past this point the tag is pushed, and a publish that cannot run is much harder to unwind.
 
 **Step 3: Bump on a branch**
 
@@ -47,18 +47,32 @@ Create a task worktree for the release branch:
 node .claude/scripts/task-worktree.mjs --root . --create --repo "{repo}" --branch "release/v{version}"
 ```
 
-If the repo has a `package.json` with a `version`, set it to `{version}` (edit the JSON; keep formatting) and update `package-lock.json`'s top-level version fields if that file is present. Commit `chore: release v{version}`. If the repo has no version file, skip the commit — step 5 tags the current default-branch head instead.
+If the repo has a `package.json` with a `version`, set it to `{version}` (edit the JSON; keep formatting) and update `package-lock.json`'s top-level version fields if that file is present. Commit `chore: release v{version}`. If the repo has no version file, skip the commit — step 6 tags the current default-branch head instead.
 
 **Step 4: Merge**
 
 Push the branch and open a PR through the same per-repo forge (`forgeConfigForRepo` from Step 2) with head `release/v{version}`. Ask `Merge? [Y/n]`, then merge (squash, delete branch).
 
-**Step 5: Tag and publish**
+**Step 5: Leak audit (optional)**
 
-Pull the merge, tag it, and push the tag:
+Pull the merge, then audit what is about to be tagged:
 
 ```bash
 git -C repos/{repo} pull --ff-only
+node .claude/scripts/release-leak-audit.mjs --root . --repo "{repo}"
+```
+
+Patterns live in `workspace.json` — `repos.{repo}.release.leakPatterns` for one repo, `workspace.release.leakPatterns` for every repo — as arrays of strings: `/…/flags` is that regex, anything else a case-insensitive literal. Mind the seam between the forms: a path-like literal whose tail parses as a flags run (`/keys/i`) reads as a regex — write such literals without the leading slash or escape them as a regex.
+
+The script scans what this release publishes: for a publishable package the `npm pack --dry-run --ignore-scripts` file list (the root package only — a monorepo's workspace packages are not enumerated, and build artifacts a publish workflow generates only in CI are not in npm's local list) together with the files changed since the last tag, else the changed files alone (`--tag-range <from>..<to>` overrides, reading contents from the range's end commit when it is not HEAD) — plus every commit message in the range, squash-merged PR bodies included. The worktree must be clean, since contents are read from disk (`--allow-dirty` overrides). Matched spans are masked in the excerpt, so showing a match never echoes the secret.
+
+Exit 1 lists matches as `{ file, line, pattern, excerpt }` plus a `skipped` list of files it could not read: stop and show them; never edit files to silence the audit. Exit 0 with `no leak patterns configured` is the no-patterns case — the step still runs and exits 0, so a workspace that never opts in needs no special-casing. Exit 2 means the audit itself could not run (including a dirty worktree); report that too. Whether a match is a true leak, an over-broad pattern, or a release to redo is the operator's call — cheap before the tag is pushed, impossible after.
+
+**Step 6: Tag and publish**
+
+Tag the merge and push the tag:
+
+```bash
 git -C repos/{repo} tag v{version}
 git -C repos/{repo} push origin v{version}
 ```
@@ -86,7 +100,7 @@ await forge.releaseCreate({ tag: 'v{version}', repo, generateNotes: false,
 
 If a `publish.yml` (or a publish job) without release creation exists, still find and watch its run the same way.
 
-**Step 6: Tear down and report**
+**Step 7: Tear down and report**
 
 Remove the release worktree:
 
@@ -96,7 +110,7 @@ node .claude/scripts/task-worktree.mjs --root . --remove --repo "{repo}" --branc
 
 Report the PR, the tag, the release URL, and the publish status.
 
-**Step 7: Update workspace release state**
+**Step 8: Update workspace release state**
 
 If the workspace keeps release state in `workspace-context/` (for example a current-release line in a status file under `shared/locked/`), offer to update it — through a workspace task worktree and PR, never on the launcher.
 

package/template/_claude/skills/setup-tracker/SKILL.md

@@ -130,13 +130,36 @@ For (5): exit — no changes.
    glab issue list --repo {group/sub/project} --per-page 5
    ```
 
-### Step 5: Report
+### Step 5: Configure epics (optional)
+
+Epics group related issues across a release or theme. Two modes, both through the adapter:
+
+- **Label mode** — the default, works on any plan, both backends. An epic is the label `epic:{name}` carried by every issue in it. Nothing to configure unless the team already uses that prefix for something else: `epicLabelPrefix` renames it (e.g. `"E:"` — any delimiter-terminated prefix works; a trailing alphanumeric is rejected), and existing labels under the chosen prefix become epics as they are. On GitLab, `epicLabelPrefix: "epic::"` makes epics **scoped labels** — GitLab itself then enforces one epic per issue.
+- **Native mode** — GitLab only, `"epics": "native"`: real group epics with ids and URLs, living at the project's parent group. Needs Premium/Ultimate on that instance. Without it every epic call fails with a clear error pointing back at label mode — the adapter never silently falls back, so a native-configured team finds out at the first call instead of discovering epics split across two representations. GitHub has no native epic object: `"native"` on `github-issues` throws from every epic method (sub-issues may back one later).
+
+Ask: "Group work into epics? [label/skip]" — plus `native` as a third choice when the backend is gitlab-issues. Default skip. For label or native, write the key into the `workspace.tracker` block (`{"epics": "label"}` or `{"epics": "native"}`; plain label mode needs no key at all). If the user wants starter epics, create them through the adapter — idempotent, so re-running setup duplicates nothing:
+
+```bash
+node --input-type=module -e "
+  import { createTracker } from './.claude/scripts/trackers/interface.mjs';
+  import { readFileSync } from 'node:fs';
+  const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+  const t = createTracker(ws.workspace.tracker);
+  await t.createEpic({ name: 'auth', description: 'Authentication work' });
+  console.log((await t.listEpics()).map((e) => e.name).join(', '));
+"
+```
+
+`/start-work` reads the epic list before creating a new issue and offers an epic picker once at least one epic exists; a workspace with none sees no change.
+
+### Step 6: Report
 
 ```
 Tracker configured:
   Type: {github-issues | gitlab-issues}
   Repo: {slug}
   Labels: bug, feat, chore, P1, P2, P3
+  Epics: {label mode (epic:{name} labels) | native (GitLab group epics) | off}
   Milestones: {list or "(none — add via the forge UI)"}
 
 Next: run /start-work to pick or create an issue and begin.

package/template/_claude/skills/start-work/SKILL.md

@@ -5,7 +5,7 @@ description: Begin or resume a work session. Creates a self-contained work-sessi
 
 # Start Work
 
-Two lifecycles share this skill. `workspace.sessionModel` in `workspace.json` selects for new work: `"task"` routes new work to **Flow: Task** (session model v2 — no session folder, no `session.md`); absent or `"session"` keeps the existing flows below, unchanged. Resuming an existing `work-sessions/` session always uses the existing Resume flow regardless of the setting.
+Two lifecycles share this skill. `workspace.sessionModel` in `workspace.json` selects for new work: `"task"` routes new work to **Flow: Task** (session model v2 — no session folder, no `session.md`); absent or `"session"` keeps the existing flows below, unchanged. Resuming an existing `work-sessions/` session always uses the existing Resume flow regardless of the setting. CLAUDE.md no longer imports `workspace.json`: take `sessionModel`, `tracker`, and the repo names from the SessionStart hook's `Workspace config (workspace.json):` line when it is in context, else read `workspace.json`.
 
 Begin or resume a persistent work session. Each session lives in its own `work-sessions/{name}/` folder containing one workspace worktree, nested project worktrees, and a unified `session.md` tracker. Sessions can run in parallel from separate terminals.
 
@@ -19,7 +19,7 @@ Begin or resume a persistent work session. Each session lives in its own `work-s
 
 New work as a task: one tracker issue, one branch, one worktree per repo the work touches. This flow creates no `work-sessions/` folder, no `session.md`, and seeds no task list — the issue, the branch, and the chat record are the entire state. The chat stays at the workspace root — `{launcher-root}`, the absolute path on the `Workspace root:` line the SessionStart hook injects (at /start-work time you are normally already there); the worktrees are reached by path.
 
-If `workspace.tracker` is absent, say tracking is off and skip step 1 — but still ask for the type (`bug` / `feat` / `chore`) and a one-line description, because the type picks the branch prefix — then continue with steps 2–6. What that costs: without a tracker there is no `workItem` and no issue to close at completion — the task is still recorded on the chat record (with no work item, keyed by repo + branch), so `/complete-work` finds it from the launcher like any other task.
+If `workspace.tracker` is absent (the hook's `Workspace config` line reads `tracker: off`), say tracking is off and skip step 1 — but still ask for the type (`bug` / `feat` / `chore`) and a one-line description, because the type picks the branch prefix — then continue with steps 2–6. What that costs: without a tracker there is no `workItem` and no issue to close at completion — the task is still recorded on the chat record (with no work item, keyed by repo + branch), so `/complete-work` finds it from the launcher like any other task.
 
 1. **Identify or create the tracker issue and claim it.** If the invocation's arguments already name an issue — `gh:N`, `#N`, or an issue URL — normalize it to the adapter's id (`#42` and a `.../issues/42` URL both mean `gh:42`) and fetch it with `tracker.getIssue(id)`. Then check whether the issue already has a task before claiming anything — another chat may have started it (gh:188):
 
@@ -27,8 +27,8 @@ If `workspace.tracker` is absent, say tracking is off and skip step 1 — but st
    node .claude/scripts/chat-record.mjs --root . --owner "{workItem}"
    ```
 
-   Exit 1 means no chat owns a task for the issue: claim it when it is not yet assigned to you (with the same `ALREADY_ASSIGNED` handling as the fallback pick below) and skip the candidate list entirely. Exit 0 prints `{ chat, branch, repos }` — a task exists. First make sure its worktrees are there: run step 4's `--create` for each of `repos`; over an existing branch or worktree `--create` REUSES what it finds (`created: false`) — it never fails or duplicates. Then ask the operator which way to take it:
-   - **Adopt into this chat** — record the task with step 5's `--add-task`, and remove it from the old chat's record (`--remove-task --chat "{owner.chat}"` with the same selectors) only when the operator says that chat is done with it. While both chats still work the task, both records legitimately list it — the branch and worktrees are shared, not duplicated.
+   Exit 1 means no chat owns a task for the issue: claim it when it is not yet assigned to you (with the same `ALREADY_ASSIGNED` handling as the fallback pick below) and skip the candidate list entirely. Exit 0 prints `{ chat, branches }` — a task exists, one `{ branch, repos }` per branch the issue is open on (gh:206: one issue may carry several branches, each its own worktree and PR). First make sure the worktrees are there: run step 4's `--create` once per branch, for each repo in that branch's `repos`; over an existing branch or worktree `--create` REUSES what it finds (`created: false`) — it never fails or duplicates. Then ask the operator which way to take it:
+   - **Adopt into this chat** — record each adopted branch with step 5's `--add-task`, and remove it from the old chat's record (`--remove-task --chat "{owner.chat}" --work-item "{workItem}" --branch "{branch}" --repo "{repo}"`) only when the operator says that chat is done with it. While both chats still work a branch, both records legitimately list it — the branch and worktrees are shared, not duplicated — and a sibling branch the owner keeps is not this adoption's to take.
    - **Leave it with the owner** — message the owning chat via SendMessage using the name `--owner` printed (the record name doubles as the session-registry name SendMessage reaches a chat by) and stop here.
    - When `--owner` names this chat, it is a resume of your own task: reuse the worktrees as above and continue.
 
@@ -57,6 +57,8 @@ If `workspace.tracker` is absent, say tracking is off and skip step 1 — but st
    await tracker.claim(newIssue.id);
    ```
 
+   The epic flow from Blank step 6 applies here too — `tracker.listEpics()` read before the create (a failure there is reported and skipped, never fatal), the picker offered only when it is non-empty.
+
    Remember `workItem: {issue.id}`.
 
 2. **Pick repo(s)** — the same numbered multi-select as Blank step 7 (e.g. `1,3` or `all`), defaulting to the repo marked `"primary": true` under `repos` in `workspace.json`, falling back to the first entry when none is marked. The list also offers the **workspace repo itself**, shown as `workspace (this repo)` and addressed as `.`. Include it when the task changes anything tracked in the workspace repo — `workspace-context/`, the workspace's own `.claude/` (rules, hooks, scripts, skills), or, in a dogfood workspace, mirrors of template changes. Steps 4 and 5 take `.` like any other repo name (`--repo "."`).
@@ -192,8 +194,15 @@ If no gap is found, skip silently.
 
 6. **User picked "Something new" (or fell through from step 2 with no tracker).**
    - Ask for a description, type (`bug` / `feat` / `chore`), priority (`P1` / `P2` / `P3`), optional milestone.
-   - If a tracker is configured, create the issue and self-assign:
+   - If a tracker is configured, read the epic list first — a tracker/epic failure must surface before anything is created, and it never blocks issue creation — then create the issue and self-assign:
      ```javascript
+     let epics = [];
+     try {
+       epics = await tracker.listEpics();
+     } catch (e) {
+       console.log(`Skipping the epic picker — could not list epics: ${e.message}`);
+     }
+
      const newIssue = await tracker.createIssue({
        title: description,
        body: `Created at /start-work by ${user}.`,
@@ -201,7 +210,16 @@ If no gap is found, skip silently.
        milestone: milestone || null,
      });
      await tracker.claim(newIssue.id);
+
+     // Offered only when epics already exist; teams without them see
+     // nothing new. Present a numbered menu: the existing epics, "[0] No
+     // epic", and "[N] New epic…". Create only on the explicit new-epic
+     // choice (tracker.createEpic({ name })), then assign the pick:
+     if (epics.length > 0) {
+       await tracker.setIssueEpic(newIssue.id, chosenName /* or null for no epic */);
+     }
      ```
+     `setIssueEpic` replaces any epic the issue already carries, and an unknown name throws — never invent epic names to satisfy it. If it itself fails after the issue exists, report that and continue: the issue is already created and claimed, and nothing after that point is worth aborting over.
      Remember `workItem: {newIssue.id}` for the session tracker.
    - If no tracker: proceed without a `workItem:` linkage — the session is a pure blank.
 

package/template/_claude/skills/workspace-update/SKILL.md

@@ -9,7 +9,7 @@ Apply a staged template update to an initialized workspace. The CLI (`npx @ulyss
 
 ## Prerequisites
 
-- `workspace.json` must have `initialized: true`
+- Read `workspace.json` (the file at the workspace root — the SessionStart hook's `Workspace config (workspace.json):` line is only a summary) and check `workspace.initialized` is `true`
 - If not initialized, check whether initialization was committed but never merged — the workspace-init flow ends with its commits merged to the default branch, so an unmerged init branch explains a missing flag:
   ```bash
   git log --all --format=%H -S'"initialized": true' -- workspace.json
@@ -54,14 +54,19 @@ It runs from the payload precisely so workspaces that don't have it installed ye
 - `new` — no installed counterpart and no baseline entry; safe to batch-apply (Step 3) behind one confirmation
 - `identical` — installed file already equals the payload; skip silently
 - `updated` — installed file still holds the baseline content while the payload ships something new: a pure template change the user never touched. Batched with `new` behind one confirmation
-- `differs` — installed file matches neither the payload nor the baseline, and the template changed it since the baseline too: a local edit that meets a template change. Needs a per-file decision — Step 3 merges these three-way when a merge base is staged
+- `differs` — installed file matches neither the payload nor the baseline, and the template changed it since the baseline too: a local edit that meets a template change. Needs a per-file decision — Step 3 merges these three-way when a merge base is staged. A path registered in `.claude/template-modifications.json` (see the registry note below) enters as `{ file, reason }`, its reason saying why the file diverges — show it at every decision about the file
 - `config` — `.mcp.json` and `.claude/settings.json`: JSON the workspace owns jointly with the template — never compared by content, never batch-copied. Each entry carries a key-level diff (`added` keys the template ships, `workspaceOnly` keys only the workspace has, `changed` keys with different values; nested paths like `mcpServers/{server}`), element diffs for array-valued keys (`arrays`: `{ path, added, workspaceOnly }` element lists for `hooks/{event}`, `permissions/allow`/`deny`), or a `notInstalled` / `unparseable` flag. Merged key by key in Step 3.
-- `localOnly` — installed file differs from the payload, but the payload equals the baseline: these are local edits to files the template didn't touch. Informational only — never asked about, never applied
-- `deletedLocally` — the baseline records the file and the payload still ships it, but it is missing from the workspace (deleted locally, or declined at install time). Step 3 asks once whether to restore the list
+- `localOnly` — installed file differs from the payload, but the payload equals the baseline: these are local edits to files the template didn't touch. Informational only — never asked about, never applied; registered entries carry their reason, shown in the summary
+- `deletedLocally` — the baseline records the file and the payload still ships it, but it is missing from the workspace (deleted locally, or declined at install time). Step 3 asks once whether to restore the list; registered entries carry their reason, shown with that ask
 - `activated` — the payload ships `rules/{name}.md.skip` while the workspace keeps `{name}.md` active: the rule was deliberately activated. Nothing to install — the active rule stays.
-- `removed` — installed file with no counterpart in the payload. The config files above never appear here (the template dropping one hands it to the workspace). Gitignored paths, `.claude/worktrees/`, and files listed in `workspace.json` → `workspace.localFiles` (an array of `.claude/`-relative paths or globs the workspace owns) are excluded automatically. An entry is a plain path, `{ file, referencedBy }` — a hook a workspace-only `settings.json` entry still registers (the paths say where) — or `{ file, userOwned: true }` — no baseline record, so the template never shipped it and it is the workspace's own.
+- `removed` — installed file with no counterpart in the payload. The config files above never appear here (the template dropping one hands it to the workspace). Gitignored paths, `.claude/worktrees/`, and files claimed in `.claude/template-modifications.json` → `localFiles` (an array of `.claude/`-relative paths or globs the workspace owns; the legacy `workspace.json` → `workspace.localFiles` array still counts) are excluded automatically. An entry is a plain path, `{ file, referencedBy }` — a hook a workspace-only `settings.json` entry still registers (the paths say where) — or `{ file, userOwned: true }` — no baseline record, so the template never shipped it and it is the workspace's own; any of these may carry `reason` when the file is registered in the registry's `modifications` map.
 - `staleTests` — `*.test.mjs` files under `.claude/` the payload doesn't carry. The package never ships tests, so these came from a dev checkout and no update refreshes them (Step 3 offers removal).
 - `implicitDefaults` — `workspace.json` keys whose absence carried a default in the version being upgraded from. Today: `canonicalBudgetBytes`, an implicit 40960-byte budget between v0.15.0-beta.1 and v0.19.0-beta.0 (before v0.15 there was no budget at all; since v0.19 absent means off). An upgrade from inside that window into a workspace.json that never set the key reports `{ key, value, reason }` — Step 3's workspace.json step writes the value explicitly so trimming doesn't silently stop.
+- `staleModifications` — `{ file, reason }` entries from the registry whose installed file already equals the payload: the template's version was taken at some point, so the recorded reason describes nothing. `file` is the `.claude/`-prefixed path; the registry key is that path with the prefix stripped. Step 3 offers to drop them.
+- `legacyKeys` — template-modification data still sitting in `workspace.json` (`workspace.localFiles`, `workspace.templateModifications`) instead of the registry file. Step 3 offers the migration.
+- `ignoredKeys` — registry keys that escape `.claude/` (`../CLAUDE.md`, absolute paths): the registry covers `.claude/` paths only — root files (`CLAUDE.md`, `.mcp.json`, `.claudeignore`) are handled by their own merge paths — so these are reported for the operator to fix rather than sitting silently inert.
+
+The classification also consults `.claude/template-modifications.json`, the workspace's registry of deliberate divergences from the template — `{ "localFiles": [...], "modifications": { "<path>": "<reason>" } }` with paths relative to `.claude/` (backslashes and leading `./` or `.claude/` are normalized on read). The template never ships or overwrites this file. `localFiles` are paths or globs the workspace owns outright (never offered by an update); `modifications` records why edited template files are kept as they are — those files still update (three-way merge when both sides changed), the reason just travels with every decision about them. If the output carries `modificationsError`, the registry doesn't parse — STOP: report the error and ask the operator to fix the JSON before any per-file decision. Classification has already failed closed (every `removed` entry is marked `unverifiable: true`, because the file's ownership claims cannot be read), so nothing is offered as a plain removal while it is broken; never invent reasons or exclusions, and after the fix re-run the classifier.
 
 Content is compared with line endings normalized (CRLF ≡ LF; binary files byte-exact), so a Windows autocrlf checkout does not read as locally modified.
 
@@ -102,27 +107,29 @@ Batch the safe cases, ask on the rest:
   ```bash
   node {payload}/.claude/scripts/template-merge.mjs --root . --payload {payload} --baseline {baseline}
   ```
-  (`{baseline}` resolves as in Step 2; `--files a,b` re-runs a subset, `--out <dir>` redirects the output.) It merges each `differs` file with `git merge-file` — the workspace copy as "local", the staged base as the common ancestor, the payload's copy as "template" — and prints `{ merged: [{path, conflicts: 0, out}], conflicted: [{path, conflicts: N, out}], noBase: [path], errors: [...] }`, writing the merged text under `{payload}/.merged/` mirroring each path. It never writes a workspace file; applying is this skill's job, on approval:
-  - **Clean merges (`merged`):** show the diff workspace→merged for each file (`git diff --no-index` the workspace file against its `out`), then ONE batched confirmation — "Apply these {N} clean merges? [Y/n]" — listing the files. On yes, copy each `out` file to the same path in the workspace (the update worktree in the remote flow).
-  - **Conflicts (`conflicted`):** one file at a time. Show the conflict hunks (`<<<<<<< local` … `>>>>>>> template`), propose a resolution, and write the resolved file only after the operator's yes for THAT file. Never resolve a conflict silently, and never delegate resolution to a subagent or any unattended step without the operator approving each file.
-  - **`noBase`** (no staged base for the path, or its hash does not match the baseline — the base is not this workspace's ancestor): fall back to the two-way ask — "Your version of {file} differs from the template's. Show diff? [y/N]" — then apply, keep, or merge by hand per the user's decision. Expect a previously declined update here: its baseline entry keeps the older version's hash (Step 4's rule), so the newly staged base no longer validates and the file takes this per-file decision.
+  (`{baseline}` resolves as in Step 2; `--files a,b` re-runs a subset, `--out <dir>` redirects the output.) It merges each `differs` file with `git merge-file` — the workspace copy as "local", the staged base as the common ancestor, the payload's copy as "template" — and prints `{ merged: [{path, conflicts: 0, out}], conflicted: [{path, conflicts: N, out}], noBase: [path], errors: [...] }`, writing the merged text under `{payload}/.merged/` mirroring each path. Entries in `merged`/`conflicted` carry `reason` when the file is registered in `.claude/template-modifications.json`, and a registered `noBase` path prints as `{ path, reason }` — show that reason at the decision it belongs to. It never writes a workspace file; applying is this skill's job, on approval:
+  - **Clean merges (`merged`):** show the diff workspace→merged for each file (`git diff --no-index` the workspace file against its `out`), with its registered reason when it has one, then ONE batched confirmation — "Apply these {N} clean merges? [Y/n]" — listing the files. On yes, copy each `out` file to the same path in the workspace (the update worktree in the remote flow).
+  - **Conflicts (`conflicted`):** one file at a time. Show the conflict hunks (`<<<<<<< local` … `>>>>>>> template`) with the file's registered reason when it has one, propose a resolution, and write the resolved file only after the operator's yes for THAT file. Never resolve a conflict silently, and never delegate resolution to a subagent or any unattended step without the operator approving each file.
+  - **`noBase`** (no staged base for the path, or its hash does not match the baseline — the base is not this workspace's ancestor): fall back to the two-way ask — "Your version of {file} differs from the template's{ — registered reason}. Show diff? [y/N]" — then apply, keep, or merge by hand per the user's decision. Expect a previously declined update here: its baseline entry keeps the older version's hash (Step 4's rule), so the newly staged base no longer validates and the file takes this per-file decision.
+  Whenever the operator's decision KEEPS their local version — a `noBase` "keep", a conflict resolution that keeps the local wording — and the path is not yet registered, offer: "Record why you keep {file} in .claude/template-modifications.json? [y/N]" — on yes, add `"<path>": "<their reason>"` to its `modifications` map (path relative to `.claude/`, creating the file if absent), so the next update shows the reason instead of re-asking blind.
   When the payload carries no `.template-base/` at all (the CLI could not fetch the installed version — offline or unpublished; the helper reports `templateBase: null`), every `differs` file takes the `noBase` path — say so once in the report.
 - **Config files (`config`):** `.mcp.json` and `.claude/settings.json` are never copied wholesale — a batch copy wipes the workspace's own MCP servers and settings. Merge each entry key by key (values from `{payload}/{path}` and the workspace's copy): add every `added` key, keep every `workspaceOnly` key untouched, and for each `changed` key ask — "Template changed `{key}` in `{path}`. Take the template's, keep yours, or inspect?" Array-valued keys merge as a union, no ask: keep the workspace's elements in place and append each `arrays` entry's `added` elements (`workspaceOnly` elements are already in place, listed for visibility). `notInstalled` — ask once: "Install {path} from the template? [Y/n]" (never install a config silently); `unparseable` means broken JSON on one side — show the file and ask, never merge blind.
 - **Local-only edits (`localOnly`):** nothing to decide — these are your local edits to files the template hasn't changed since the last update. List them in the summary (so the edits are visible) and move on; do not ask about them.
-- **Deleted locally (`deletedLocally`):** "These {N} files exist in the template and its baseline but not in your workspace — deleted locally (or never installed). Restore from the template? [Y/n]" — one confirmation for the whole list. Restoring installs the payload's version of each.
-- **Removed in template (`removed`):** a plain path — "Template removed {file}. Delete locally? [y/N]" (conservative default). An entry `{ file, referencedBy }` is a hook still registered in `.claude/settings.json`: ask once — "Template removed {file}, which your settings.json still references via {refs}. Remove the file and those settings entries together? [Y/n]" — never delete the file and leave a settings entry pointing at nothing. An entry `{ file, userOwned: true }` was never shipped by the template (no baseline record): do not offer deletion — suggest claiming it in `workspace.json` → `workspace.localFiles` instead, showing the exact entry (`"localFiles": ["skills/my-skill/**"]`, or `["rules/my-rule.md"]` for a single file) so future updates skip it.
+- **Deleted locally (`deletedLocally`):** "These {N} files exist in the template and its baseline but not in your workspace — deleted locally (or never installed). Restore from the template? [Y/n]" — one confirmation for the whole list, showing each registered reason (a registered deletion is usually deliberate). Restoring installs the payload's version of each.
+- **Removed in template (`removed`):** a plain path — "Template removed {file}. Delete locally? [y/N]" (conservative default). An entry `{ file, referencedBy }` is a hook still registered in `.claude/settings.json`: ask once — "Template removed {file}, which your settings.json still references via {refs}. Remove the file and those settings entries together? [Y/n]" — never delete the file and leave a settings entry pointing at nothing. An entry `{ file, userOwned: true }` was never shipped by the template (no baseline record): do not offer deletion — suggest claiming it in `.claude/template-modifications.json` → `localFiles` instead, showing the exact entry (`"localFiles": ["skills/my-skill/**"]`, or `["rules/my-rule.md"]` for a single file) so future updates skip it. An entry carrying `reason` shows it with its ask — the registry already says why this file is what it is. An entry carrying `unverifiable: true` means the registry didn't parse and its ownership claims were unreadable — that is Step 2's stop; never offer deletion for one until the JSON is fixed and the classification re-run.
 - **Activated rules (`activated`):** keep the active file, install nothing — report: "Rule {name} is active here and optional in the template; your activation is preserved."
 - **Stale tests (`staleTests`):** "These {N} test files under .claude/ came from a dev checkout — the package never ships them, so updates can't refresh them (tests live in the template repo). Remove them? [Y/n]" — one confirmation for the whole list.
+- **Template-modification registry (`legacyKeys` + `staleModifications`):** when `legacyKeys` is non-empty, offer once — "Move your localFiles/templateModifications out of workspace.json into `.claude/template-modifications.json`? [Y/n]". On yes, write the registry in the workspace being updated (the update worktree in the remote flow): merge the legacy values into its `localFiles` array and `modifications` map (paths `.claude/`-relative; create the file if absent) and remove the legacy keys from `workspace.json` there — both edits ride the update's commit, so the rest of the team gets the migration with the update. When `staleModifications` is non-empty, offer once — "These {N} modification entries match the template again ({files}, each with its reason shown) — drop them? [Y/n]"; on yes remove those paths from the registry's `modifications` map. `ignoredKeys` entries cover nothing — mention them in the report so the operator can drop or fix them. Never edit the registry without the operator's yes.
 - **Hook migration (.sh to .mjs):** Detect old `.sh` hooks in `.claude/hooks/` that have `.mjs` replacements in the payload. Offer: "Hook {name}.sh has a .mjs replacement in the update. Replace and update settings.json commands? [Y/n]" — this is a one-time migration for workspaces upgrading from pre-0.2.0
 
 Also handle these non-component files from the payload:
 
-- **workspace.json keys:** First apply any `implicitDefaults` from Step 2 — write the reported key and value into the workspace.json being updated and tell the operator: "kept your previous canonical trimming (40 KB) explicitly; remove the key to turn it off." Then compare the `workspace` object of the payload's `workspace.json.tmpl` with the installed `workspace.json`, key by key. For each key the template ships that the workspace lacks, show its template default and ask before adding. Never remove an existing key just because the template no longer ships it. `canonicalBudgetBytes` is opt-in since v0.19 — leave an existing value alone and mention it can be removed to turn the budget off.
+- **workspace.json keys:** First apply any `implicitDefaults` from Step 2 — write the reported key and value into the workspace.json being updated and tell the operator: "kept your previous canonical trimming (40 KB) explicitly; remove the key to turn it off." Then compare the `workspace` object of the payload's `workspace.json.tmpl` with the installed `workspace.json`, key by key. For each key the template ships that the workspace lacks, show its template default and ask before adding. Never remove an existing key just because the template no longer ships it — the one exception is the legacy `localFiles`/`templateModifications` keys, which the registry migration above removes with the operator's yes. `canonicalBudgetBytes` is opt-in since v0.19 — leave an existing value alone and mention it can be removed to turn the budget off.
 - **CLAUDE.md:** If `{payload}/CLAUDE.md.tmpl` exists, merge — never regenerate from scratch:
   ```bash
   node {payload}/.claude/scripts/classify-update.mjs --root . --payload {payload} --merge-claude-md
   ```
-  The command prints JSON `{ claudeMd, missingIncludes }`. `claudeMd` is the merged CLAUDE.md: template-owned lines take the template's new versions (skill-list entries match by their `/name`), while lines the template doesn't have — the workspace's own skill entries, custom bullets, whole sections — are kept in place. `missingIncludes` lists the `@{file}` include lines the merged file carries whose targets don't exist here (machine-local `local-only-*` targets are exempt — expected absent, never reported). Two consequences to watch in the diff: an edit made directly to a template-owned skill line is replaced by the template's new wording, and a template prose line that was reworded locally survives alongside the new template line (it may appear twice). The merge keeps the current file's line endings. Show the user the diff against the current CLAUDE.md before writing the merged result, and act on each `missingIncludes` entry — ask "The merged CLAUDE.md includes `{file}`, which doesn't exist here. Create the stub, or leave the include out?" — never write a dangling include silently. (The two JSON configs are the `config` list's, not this block's.)
+  The command prints JSON `{ claudeMd, droppedIncludes, missingIncludes }`. `claudeMd` is the merged CLAUDE.md: template-owned lines take the template's new versions (skill-list entries match by their `/name`), while lines the template doesn't have — the workspace's own skill entries, custom bullets, whole sections — are kept in place. `droppedIncludes` names retired `@{file}` includes the workspace still carries but this payload no longer ships — today `@workspace.json`, whose config summary the SessionStart hook now injects instead (gh:196); the line is dropped from the merged result, so name the drop when you show the diff and let the operator's yes (or refusal) on the merged file decide it. `missingIncludes` lists the `@{file}` include lines the merged file carries whose targets don't exist here (machine-local `local-only-*` targets are exempt — expected absent, never reported). Two consequences to watch in the diff: an edit made directly to a template-owned skill line is replaced by the template's new wording, and a template prose line that was reworded locally survives alongside the new template line (it may appear twice). The merge keeps the current file's line endings. Show the user the diff against the current CLAUDE.md before writing the merged result, and act on each `missingIncludes` entry — ask "The merged CLAUDE.md includes `{file}`, which doesn't exist here. Create the stub, or leave the include out?" — never write a dangling include silently. (The two JSON configs are the `config` list's, not this block's.)
 - **.gitignore:** Merge new entries from the payload's `_gitignore` into the existing `.gitignore` — do not remove user-added lines. An ignore pattern does not untrack already-committed files: if the workspace still tracks the per-machine catalogs the template now ignores (`git ls-files -- 'workspace-context/team-member/*/index.md'`), untrack them (`git rm -r --cached 'workspace-context/team-member/*/index.md'`), or every machine's regenerations keep dirtying pulls.
 
 ### Step 4: Update version and write the baseline
@@ -229,13 +236,14 @@ Report: "Workspace updated to v{templateVersion}. Restart Claude Code if rules o
 
 ### Step 8: Session-model migration nudge
 
-After the update is applied, if the sessions directory (`workspace.workSessionsDir`, default `work-sessions/`) has entries and `workspace.sessionModel` is not `"task"`, append one line to the report: "This workspace still has {N} session(s) under the session model — `/migrate-sessions` can inventory and drain them and switch to the task model whenever you're ready." Suggest only; the operator decides whether and when.
+After the update is applied, read `workspace.json` (Step 4 just rewrote its `templateVersion`, so the file is in hand): if the sessions directory (`workspace.workSessionsDir`, default `work-sessions/`) has entries and `workspace.sessionModel` is not `"task"`, append one line to the report: "This workspace still has {N} session(s) under the session model — `/migrate-sessions` can inventory and drain them and switch to the task model whenever you're ready." Suggest only; the operator decides whether and when.
 
 ## Notes
 
 - The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload, installs the current copy of this skill into `.claude/skills/workspace-update/` (so an outdated installed flow never processes a new payload; a locally customised SKILL.md is backed up as `SKILL.md.local-backup` first), stages a reconstructed baseline inside the payload as `.template-baseline.reconstructed.json` when the workspace has none, and stages the installed version's template files as `.template-base/` (the merge base `differs` files are merged against) whenever that tarball could be fetched — the launcher itself gets no new untracked files, and Step 7 restores the launcher's skill copy before the post-merge pull, rebuilds the per-user catalogs the pull may delete, and removes the update worktree with its branch
 - Never overwrites without asking — `new` and `updated` files are batched behind one confirmation; `differs` files are three-way merged against the staged base when there is one (clean merges batch behind one confirmation, conflicts are resolved one file at a time with the operator's yes, files without a base fall back to the per-file ask); `config` files (`.mcp.json`, `.claude/settings.json`) are merged key by key (array-valued keys union-merged) and never copied wholesale; `localOnly` files are never asked about (local edits to files the template didn't touch)
-- Preserves local modifications, custom content, the workspace's own MCP servers and settings, existing `workspace.json` keys, and deliberately activated rules
+- Preserves local modifications, custom content, the workspace's own MCP servers and settings, existing `workspace.json` keys (the legacy `localFiles`/`templateModifications` keys excepted — they migrate to the registry with the operator's yes), and deliberately activated rules
+- `.claude/template-modifications.json` is the workspace's own registry of deliberate divergences — `localFiles` it owns outright (never offered), `modifications` it keeps with a reason (still updated, reason shown at each decision). The template never ships or overwrites the file; this skill reads it, offers to record a reason when the operator keeps an edit, migrates the legacy `workspace.json` keys into it, offers to drop entries that no longer describe the file, and stops on a registry that doesn't parse until the operator fixes the JSON
 - The template baseline (`.claude/.template-baseline.json`) is what separates `updated`, `differs`, and `localOnly`: entries hold the payload hash of the last-shipped content (unapplied updates keep the older entry), so a deliberately kept local edit stays visible across updates while an untouched file never prompts
 - The launcher's default branch takes a template-update commit only when the workspace repo has no remote; with ANY remote, the update lands through a task worktree, a branch, and a PR/MR — the default branch is never pushed directly
 - Can be run multiple times safely (idempotent) — if `.workspace-update/` doesn't exist, it reports no payload and exits

package/template/workspace.json.tmpl

@@ -12,7 +12,8 @@
     "greeting": "Welcome back to {{project-name}}.",
     "sessionModel": "session",
     "tracker": null,
-    "forge": { "type": "github" }
+    "forge": { "type": "github" },
+    "mergeApproval": "ask"
   },
   "repos": {}
 }

package/lib/init.test.mjs

@@ -1,75 +0,0 @@
-#!/usr/bin/env node
-// Test for init.mjs (--init scaffolding)
-// Run: node lib/init.test.mjs
-//
-// --init stages the template payload, installs the bootstrap skills plus
-// hooks/scripts/lib, and must leave a template baseline behind: the sha256 of
-// every verbatim payload file, so the first /workspace-update classifies
-// three ways instead of treating every template change as a local edit
-// (gh:183).
-import { initWorkspace } from './init.mjs';
-import { createHash } from 'node:crypto';
-import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
-
-let failed = 0;
-let passed = 0;
-function check(label, ok) {
-  if (ok) { passed++; } else {
-    failed++;
-    console.error(`  FAIL: ${label}`);
-  }
-}
-
-const here = dirname(fileURLToPath(import.meta.url));
-const pkgVersion = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version;
-const sha = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
-
-const root = mkdtempSync(join(tmpdir(), 'init-test-'));
-
-try {
-  await initWorkspace(root);
-
-  const baselinePath = join(root, '.claude', '.template-baseline.json');
-  check('baseline written at .claude/.template-baseline.json', existsSync(baselinePath));
-  const baseline = JSON.parse(readFileSync(baselinePath, 'utf8'));
-
-  check(`baseline records the payload version (${pkgVersion})`, baseline.templateVersion === pkgVersion);
-  check(
-    'baseline covers the bootstrap skills --init installs',
-    typeof baseline.files['.claude/skills/workspace-update/SKILL.md'] === 'string'
-      && typeof baseline.files['.claude/skills/workspace-init/SKILL.md'] === 'string',
-  );
-  check(
-    'baseline covers hooks and scripts',
-    typeof baseline.files['.claude/hooks/session-start.mjs'] === 'string'
-      && typeof baseline.files['.claude/scripts/classify-update.mjs'] === 'string',
-  );
-  check(
-    'baseline covers the standalone verbatim files',
-    typeof baseline.files['.mcp.json'] === 'string' && typeof baseline.files['.claudeignore'] === 'string',
-  );
-  check(
-    'entry hash matches the installed file byte-for-byte',
-    baseline.files['.claude/scripts/classify-update.mjs'] === sha(join(root, '.claude', 'scripts', 'classify-update.mjs')),
-  );
-  check(
-    'baseline never covers tests (the tarball ships none)',
-    Object.keys(baseline.files).every((k) => !k.endsWith('.test.mjs')),
-  );
-  check(
-    'baseline never covers machine-local files',
-    !('.claude/settings.local.json' in baseline.files) && !('.claude/.active-session.json' in baseline.files),
-  );
-} finally {
-  rmSync(root, { recursive: true, force: true });
-}
-
-if (failed > 0) {
-  console.error(`${failed} check(s) failed, ${passed} passed`);
-  process.exit(1);
-}
-console.log(`${passed} checks passed`);