@ulysses-ai/create-workspace 0.13.0-beta.2 → 0.14.0-beta.3

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

@@ -38,7 +38,18 @@ If conflicts arise in any repo, STOP and present them to the user. Do not auto-r
 Run `/braindump` to capture any final discussion/reasoning to the session tracker body.
 If the user declines or there's nothing to capture, skip.
 
-### Step 4: Gather source material
+### Step 4: Flush task list to session.md
+
+Before reading sources for synthesis, flush current `TodoWrite` state to `## Tasks` per the `task-list-mirroring` rule. This ensures the synthesis in Step 6 sees the final state:
+
+```bash
+cd work-sessions/{session-name}/workspace
+echo '<JSON-of-current-todos>' | node .claude/scripts/sync-tasks.mjs --write session.md
+```
+
+Mark `Complete work` as `in_progress` in the JSON before flushing — the rest of this skill IS the act of completing.
+
+### Step 5: Gather source material
 
 Formally read ALL sources before synthesizing — do not write release notes from memory alone:
 
@@ -62,20 +73,24 @@ Formally read ALL sources before synthesizing — do not write release notes fro
    git log origin/{repo-branch}..HEAD --oneline
    ```
 
-### Step 5: Synthesize release notes
+### Step 6: Synthesize release notes
+
+Branch notes are written to the **workspace** repo, not the project repo. They are an internal retrospection artifact consumed by `/release` at release time; the project repo only ever receives a `CHANGELOG.md` entry. This separation keeps dogfood content out of public project repos between feature merge and the next release cut.
 
 For each repo in the tracker's `repos:` list that has commits beyond the base branch:
 
 ```bash
 cd work-sessions/{session-name}/workspace/repos/{repo}
 COMMIT_ID=$(git rev-parse --short HEAD)
-mkdir -p release-notes/unreleased
+cd ../..  # back to the workspace worktree
+mkdir -p release-notes/unreleased/{repo-name}
 ```
 
-**File 1: `release-notes/unreleased/branch-release-notes-{COMMIT_ID}.md`**
+**File 1: `release-notes/unreleased/{repo-name}/branch-release-notes-{COMMIT_ID}.md`** (relative to the workspace worktree)
 ```markdown
 ---
 branch: {branch}
+repo: {repo-name}
 type: {feature|fix|chore}
 author: {user}
 date: {YYYY-MM-DD}
@@ -87,10 +102,11 @@ date: {YYYY-MM-DD}
 Written from scratch per coherent-revisions rule.}
 ```
 
-**File 2: `release-notes/unreleased/branch-release-questions-{COMMIT_ID}.md`**
+**File 2: `release-notes/unreleased/{repo-name}/branch-release-questions-{COMMIT_ID}.md`**
 ```markdown
 ---
 branch: {branch}
+repo: {repo-name}
 author: {user}
 date: {YYYY-MM-DD}
 ---
@@ -100,23 +116,22 @@ date: {YYYY-MM-DD}
 {Only genuinely open questions — not things resolved during implementation.}
 ```
 
-Commit per repo:
+The `repo:` frontmatter field is what `/release` uses to know which project repo's `CHANGELOG.md` should consume each note. The directory name is the same as the field for redundancy.
+
+After all repos are processed, commit once on the workspace branch:
 ```bash
+cd work-sessions/{session-name}/workspace
 git add release-notes/unreleased/
 git commit -m "docs: add release notes for {branch}"
 ```
 
 If a repo has no commits beyond the base, skip release notes for it.
 
-### Step 6: Consume session-scoped sources
-
-The entire `work-sessions/{session-name}/` folder is removed by the cleanup script in Step 11. Before that happens, make sure everything worth preserving has landed in release notes.
-
-No separate "consume spec and plan" commit is needed for the project repos — specs and plans now live in the session folder, not in the project worktrees. The project worktrees only carry source code changes.
+### Step 7: Remove session artifacts from the workspace branch
 
-### Step 6c: Remove session artifacts from the workspace branch
+The entire `work-sessions/{session-name}/` folder is removed by the cleanup script in Step 12. Before that happens, make sure everything worth preserving has landed in release notes (Step 6) — once Step 6 has run, the tracker, specs, and plans have served their purpose.
 
-Session content (tracker, specs, plans) lives at the top of the workspace worktree on the session branch. Its purpose was synthesis into release notes in Step 5 — that work is now done. Remove the files from the branch before the final push so main's top level stays free of session artifacts:
+Session content lives at the top of the workspace worktree on the session branch. Remove these files from the branch before the final push so main's top level stays free of session artifacts:
 
 ```bash
 cd work-sessions/{session-name}/workspace
@@ -130,35 +145,11 @@ The `|| true` guards keep this idempotent — if a file is already gone (e.g., a
 
 This commit persists in the branch's history. On squash merge or rebase merge, branch history collapses to one clean commit on main with no session artifacts. On merge commits, branch history is reachable but the final tree on main shows no session content.
 
-### Step 6b: Version bump (if applicable)
-
-For each repo in the tracker's `repos:`, check if the repo has versioning:
-```bash
-cd work-sessions/{session-name}/workspace/repos/{repo}
-cat package.json 2>/dev/null | grep '"version"'
-```
-
-If no `package.json` or no `version` field: skip this repo — no versioning to manage.
-
-If the repo has a version, determine the appropriate bump from the release notes just written:
-
-1. Read the `type:` field from the branch release notes created in Step 5
-2. Determine the bump:
-   - `type: fix` or `type: chore` → **patch** (auto-bump, no confirmation needed)
-   - `type: feature` → **minor** (present to user: "This session adds new functionality. Suggested bump: {current} → {next-minor}. Confirm or adjust?")
-   - Breaking changes detected (schema changes, removed APIs, convention changes) → **major** (present to user: "This session includes breaking changes. Suggested bump: {current} → {next-major}. Confirm or adjust?")
-
-3. Apply the bump:
-   ```bash
-   git add package.json
-   git commit -m "chore: bump version to {new-version}"
-   ```
-
-The user can override any suggestion. Accept their decision.
+> **No version bump here.** Versions are bumped at release time by `/release`, which consumes accumulated unreleased branch notes into a single `CHANGELOG.md` entry per project repo. `/complete-work` only writes branch notes; it does not modify any project repo's `package.json`. This avoids version drift when multiple feature branches land between releases.
 
-### Step 7: Detect remote type per repo
+### Step 8: Detect remote type per repo
 
-For each repo in the tracker's `repos:` plus the workspace repo, determine the remote type. This drives how Step 8 and Step 9 push and merge.
+For each repo in the tracker's `repos:` plus the workspace repo, determine the remote type. This drives how Step 9 and Step 10 push and merge.
 
 ```bash
 cd work-sessions/{session-name}/workspace/repos/{repo}
@@ -167,14 +158,14 @@ git remote get-url origin 2>&1
 
 Classify the result:
 
-- **GitHub remote** — URL contains `github.com` or `gh repo view` succeeds against origin → use the PR flow (Step 8a, Step 9a).
-- **Local / bare remote** — URL is a filesystem path (starts with `/`, `./`, `file://`, or points at a `.git` bare mirror) → use the local merge flow (Step 8b, Step 9b).
-- **Other remote** (e.g., GitLab, Bitbucket, self-hosted) — no `gh` support → fall back to the local merge flow (Step 8b, Step 9b), and mention it in the final summary.
+- **GitHub remote** — URL contains `github.com` or `gh repo view` succeeds against origin → use the PR flow (Step 9a, Step 10a).
+- **Local / bare remote** — URL is a filesystem path (starts with `/`, `./`, `file://`, or points at a `.git` bare mirror) → use the local merge flow (Step 9b, Step 10b).
+- **Other remote** (e.g., GitLab, Bitbucket, self-hosted) — no `gh` support → fall back to the local merge flow (Step 9b, Step 10b), and mention it in the final summary.
 - **No remote at all** — "No remote configured for {repo}. Want me to create one on GitHub, add an existing URL, or keep the session local (push/merge inside the local clone only)?" Act on the user's choice. Never silently skip push.
 
-### Step 8: Push all repos
+### Step 9: Push all repos
 
-#### Step 8a: GitHub remotes
+#### Step 9a: GitHub remotes
 
 ```bash
 # Each project repo with a GitHub remote
@@ -188,7 +179,7 @@ git commit -m "chore: finalize context for {session-name}"
 git push -u origin {branch}
 ```
 
-#### Step 8b: Local/bare remotes
+#### Step 9b: Local/bare remotes
 
 ```bash
 # Push the feature branch to the bare remote so it exists there
@@ -202,11 +193,11 @@ git commit -m "chore: finalize context for {session-name}"
 git push -u origin {branch}
 ```
 
-The push shape is the same as 8a — what differs is the merge mechanics in Step 9b.
+The push shape is the same as 9a — what differs is the merge mechanics in Step 10b.
 
-### Step 9: Merge and present unified summary
+### Step 10: Merge and present unified summary
 
-#### Step 9a: GitHub remotes — create PRs, unified summary, merge
+#### Step 10a: GitHub remotes — create PRs, unified summary, merge
 
 Create one PR per project repo plus one workspace PR:
 
@@ -258,7 +249,7 @@ cd repos/{repo} && git pull origin {repo-branch}
 cd {main-workspace-root} && git pull origin main
 ```
 
-#### Step 9b: Local / bare / other remotes — local merge flow
+#### Step 10b: Local / bare / other remotes — local merge flow
 
 No PRs are created — these remotes don't have a PR concept (or we don't have a client wired up for them). Present an adjusted summary:
 
@@ -304,7 +295,7 @@ For repos with no remote at all (user chose "keep local"): skip push entirely. T
 cd repos/{repo} && git merge --ff-only {branch}
 ```
 
-### Step 10: Close the linked issue on the tracker
+### Step 11: Close the linked issue on the tracker
 
 If the session tracker has a `workItem:` field AND `workspace.tracker` is configured, close the linked issue via the adapter after all PRs have merged:
 
@@ -328,9 +319,9 @@ if (ws.workspace?.tracker) {
 
 If `workItem:` is unset, skip the close — this was a blank session.
 
-If the close call fails (tracker unreachable, auth expired), report the error in the unified summary but do not block Step 11 cleanup. The issue can be closed manually via the GitHub UI; no data is at risk.
+If the close call fails (tracker unreachable, auth expired), report the error in the unified summary but do not block Step 12 cleanup. The issue can be closed manually via the GitHub UI; no data is at risk.
 
-### Step 11: Cleanup
+### Step 12: Cleanup
 
 Run the cleanup helper script from the main workspace root:
 ```bash
@@ -342,7 +333,7 @@ The script tears down in the **mandatory** order:
 2. Remove the workspace worktree from the workspace repo
 3. `git worktree prune` on each project repo (belt-and-suspenders for orphan records)
 4. Delete local branches in all repos
-5. `rm -rf work-sessions/{session-name}/` — the tracker, specs, plans, and any local-only artifacts vanish. Their content was already archived into release notes in Step 5.
+5. `rm -rf work-sessions/{session-name}/` — the tracker, specs, plans, and any local-only artifacts vanish. Their content was already archived into release notes in Step 6.
 
 Workspace-first removal silently deletes the nested project worktrees' `.git` files and leaves orphan worktree records in the project repos. The script enforces the safe order.
 
@@ -362,8 +353,9 @@ Ask: "These changes weren't part of a formal work session. What do you want to d
 - **Revert** — undo the changes (with confirmation)
 
 ## Notes
-- Release notes live in the PROJECT repo worktrees — never the workspace
+- Branch release notes live in the WORKSPACE repo at `release-notes/unreleased/{repo-name}/` — never in project repos. Project repos only ever see code commits and (at release time) `CHANGELOG.md` entries written by `/release`.
 - The session tracker's body is the primary source for release note synthesis — it captures the full session history alongside specs and plans
 - All repos get PRed and merged together — one approval for all
+- Version bumps 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 consumption, cleanup, and auto-committing release notes are intentional workflow behavior — these bypass normal commit conventions by design

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

@@ -84,6 +84,21 @@ updated: {YYYY-MM-DD}
    - If no: ask for a single name that covers both
 4. Proceed with the named flow for each handoff
 
+## Include task snapshot
+
+If an active session exists (detected via `.claude/.active-session.json`), include a `## Tasks at capture time` section in the handoff artifact with a snapshot of the current `TodoWrite` state:
+
+```markdown
+## Tasks at capture time
+
+- [x] Start work
+- [x] Reproduce on iOS Safari
+- [ ] Identify race condition
+- [ ] Complete work
+```
+
+Use the same GFM checkbox format as `session.md`'s `## Tasks` section (just `content` and `status` per task — no `activeForm` field, no blockquote line) and render it inline in the handoff. Do NOT call `sync-tasks.mjs --write` — handoffs are snapshots, not the canonical store.
+
 ## Updating Existing Handoffs
 
 When updating an existing handoff, rewrite it as a fresh snapshot of current understanding (coherent-revisions rule). Don't append below the old content. The updated handoff should read as if written in one pass reflecting the current state.

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

@@ -30,6 +30,7 @@ For each shared-context `.md` file and each `work-sessions/*/workspace/session.m
 - `lifecycle: active` on a file not updated in 7+ days? (stale candidate)
 - `lifecycle: resolved` files that should have been processed by /complete-work?
 - Session tracker `status: active` but the workspace worktree at `work-sessions/{name}/workspace/` is missing? (orphaned)
+- `confidence` field present? Must be one of `high`, `medium`, `low` if set.
 
 ### 3. Workspace structure
 - Actual directory layout matches what workspace-structure rule describes?
@@ -44,24 +45,63 @@ For each shared-context `.md` file and each `work-sessions/*/workspace/session.m
 - Workspace repo on expected branch?
 - 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.
 
+### 5. Shared-context index integrity
+
+`shared-context/index.md` is auto-generated from frontmatter. Run the check:
+
+```bash
+node .claude/scripts/build-shared-context-index.mjs --check --root .
+```
+
+Three failure modes (script exits 1 with a JSON status):
+
+- `missing` — `shared-context/` exists but `index.md` does not. Run `--write` to create.
+- `stale` — `index.md` exists but its entries no longer match the filesystem. Causes: a file was added or deleted, a `description:` was changed, a `.indexignore` rule was added. Run `--write` to regenerate.
+- (no failure) — `current` with the entry count.
+
+Audit mode reports the status. Cleanup mode runs `--write` if stale or missing, then re-checks.
+
+While the index is being read, also flag entries with weak fallbacks: filename-slug-only descriptions (e.g., "project status" with no period) usually indicate the underlying file is missing a `description:` or has no usable opening sentence. Suggest adding `description:` to those source files — the index will pick it up on the next regeneration.
+
+### 6. Template freshness
+
+Compare the workspace's pinned template version against the latest published on npm.
+
+Always invoke `refreshIfStale` from the audit (regardless of `workspace.versionCheck.ambient` — the user explicitly ran `/maintenance`):
+
+```javascript
+import { refreshIfStale } from './.claude/lib/freshness.mjs';
+const result = await refreshIfStale({
+  workspaceRoot: process.cwd(),
+  ttlMs: 24 * 60 * 60 * 1000,
+});
+```
+
+Report one of:
+- `outdated` → `✗ Template v{current} → v{latest} available. Run npx @ulysses-ai/create-workspace --upgrade.`
+- `current` → `✓ Template is up to date (v{latest}).`
+- `unknown` (with cache) → `⚠ Could not reach npm registry; last cached latest was v{latest} as of {checkedAt}.`
+- `unknown` (no cache) → `⚠ Could not reach npm registry; no cached version on file. Try again when online.`
+- `skipped: 'uninitialized'` → `⚠ Workspace not initialized; freshness check unavailable.`
+
 ## Cleanup
 
 Active recommendations. Flags problems and suggests fixes, but asks before acting.
 
-### 5. Stale context
+### 7. Stale context
 - Ephemeral files not updated in 7+ days — suggest resolve, update, or archive
 - `work-sessions/{name}/` folders whose worktrees are gone — suggest cleanup
 - Session trackers whose branches have been merged — suggest `/complete-work` post-flight cleanup
 - Braindumps that overlap significantly — suggest merging (e.g., "workspace-branching.md and persistent-work-sessions.md cover the same topic")
 - Handoffs referencing deleted branches — suggest resolve or remove
 
-### 6. Context reconciliation
+### 8. Context reconciliation
 - Read recent shared-context writes (last session or last N files by updated date)
 - For each, scan other shared-context files for references that are now stale
 - Surface: "{file} says X but {newer-file} now says Y. Update {file}?"
 - This is the capture-time cross-check, run retroactively instead of inline
 
-### 7. Health metrics
+### 9. Health metrics
 - Size of `shared-context/locked/` relative to the active model's context window — flag if over 5% (yellow) or 15% (red). Absolute byte count is a weak proxy; contradictions, stale references, and duplicated coverage across files matter more than total size.
 - Number of ephemeral files — flag if accumulating without resolution
 - Session log stats (if `workspace-scratchpad/session-log.jsonl` exists):
@@ -90,11 +130,12 @@ Cleanup suggestions (2):
   ⊕ migration-recipes.md still says "/sync handles dogfood" but
     /sync was replaced by /sync-work — update?
 
-OK (4):
+OK (5):
   ✓ All CLAUDE.md skill references valid
   ✓ Workspace structure matches rule
   ✓ workspace.json repos all present
   ✓ No frontmatter errors
+  ✓ Template is up to date (v0.14.0)
 ```
 
 ## Flow
@@ -104,9 +145,10 @@ OK (4):
 3. Read workspace.json — extract repo manifest
 4. Check `.claude/rules/`, `.claude/skills/`, `.claude/agents/` against references
 5. Check git state (worktrees, branches, remotes)
-6. Read session-log.jsonl if it exists
-7. If cleanup mode: compare files pairwise for overlap, scan for stale cross-references
-8. Compile and present findings grouped by severity
+6. Run `node .claude/scripts/build-shared-context-index.mjs --check --root .` — capture status
+7. Read session-log.jsonl if it exists
+8. If cleanup mode: regenerate the shared-context index if stale; compare files pairwise for overlap; scan for stale cross-references
+9. Compile and present findings grouped by severity
 
 ## Notes
 - Audit mode is always read-only — never modifies files

package/template/.claude/skills/pause-work/SKILL.md

@@ -54,7 +54,28 @@ If `workItem:` is unset, skip the comment — this is a blank session with no tr
 
 If the comment fails (tracker unreachable, auth expired), report the error but do not block the pause. The pause state lives locally in the session tracker regardless.
 
-### Step 4: Commit and push workspace
+### Step 4: Flush task list to session.md
+
+Before the commit picks it up, flush current `TodoWrite` state to `## Tasks` per the `task-list-mirroring` rule:
+
+```bash
+cd work-sessions/{session-name}/workspace
+echo '<JSON-of-current-todos>' | node .claude/scripts/sync-tasks.mjs --write session.md
+```
+
+The `<JSON-of-current-todos>` is the same shape Claude has been maintaining via `TodoWrite`:
+
+```json
+{
+  "todos": [
+    { "content": "...", "activeForm": "...", "status": "pending|in_progress|completed" }
+  ]
+}
+```
+
+The helper enforces the bookend invariant — pass whatever current state you have, including any missing or misplaced bookends, and the helper will normalize.
+
+### Step 5: Commit and push workspace
 
 ```bash
 # From the workspace worktree
@@ -64,7 +85,7 @@ git commit -m "handoff: pause {session-name}"
 git push -u origin {branch}
 ```
 
-### Step 5: Push project repos
+### Step 6: Push project repos
 
 ```bash
 # For each repo in the tracker's repos:
@@ -72,7 +93,7 @@ cd work-sessions/{session-name}/workspace/repos/{repo}
 git push -u origin {branch}
 ```
 
-### Step 6: Create draft PRs
+### Step 7: Create draft PRs
 
 ```bash
 # For each repo in the tracker's repos:
@@ -85,7 +106,7 @@ gh pr create --draft --title "context: {session-name} (paused)" --body "Workspac
 
 If PRs already exist, update them to draft status if needed.
 
-### Step 7: Confirm
+### Step 8: Confirm
 
 "Session '{session-name}' paused. Resume anytime with /start-work."
 

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

@@ -1,14 +1,20 @@
 ---
 name: release
-description: Combine unreleased branch notes into a versioned release document. Targets project repos, not the workspace. Synthesizes ephemeral shared context into locked entries. Use at release time.
+description: Prepend a new CHANGELOG.md entry per project repo by synthesizing unreleased branch notes. Deletes consumed branch notes and synthesizes workspace shared-context into locked entries. Use at release time.
 ---
 
 # Release
 
-Combine unreleased branch-release-notes into a versioned document per project repo. Synthesize ephemeral workspace context into locked team knowledge.
+Synthesize unreleased branch notes (in the **workspace** repo) into a concise, user-facing entry at the top of each project repo's `CHANGELOG.md`. Delete the consumed branch notes from the workspace. Bump the project repo's `package.json` version. In parallel, promote resolved workspace shared-context into locked team knowledge.
+
+## Why this shape
+
+Branch notes are detailed dogfood-retrospective artifacts that should not bloat public project repos. By keeping them in the workspace repo until release time, the project repo stays lean — it only ever sees code commits and `CHANGELOG.md` entries. A single `CHANGELOG.md` with one concise entry per version is what users of a published package actually want. Branch notes remain the input format for `/complete-work` (they capture per-session detail at the right moment), but they live in the workspace and are consumed-then-deleted by `/release`.
+
+Versions are bumped here, not in `/complete-work`, because version semantics describe what shipped — accumulated changes since the last release — not the timing of any individual feature merge.
 
 ## Parameters
-- `/release {version}` — create release notes for a specific version
+- `/release {version}` — create a release entry for a specific version
 - `/release` — ask for the version
 
 ## Flow
@@ -22,66 +28,65 @@ Check `workspace.json` for `releaseMode`:
 - **ask**: "Process all repos together or individually?"
 
 **Step 2: Read unreleased notes**
-For each target repo:
+Branch notes live in the **workspace** repo, written there by `/complete-work`. For each target repo, list the workspace's unreleased subdirectory for that project:
 ```bash
-ls repos/{repo}/release-notes/unreleased/
+ls release-notes/unreleased/{repo}/
 ```
 Read all `branch-release-notes-*.md` and `branch-release-questions-*.md` files.
 
-If no unreleased files exist: "No unreleased notes found for {repo}. Nothing to release."
+If no unreleased files exist for a target repo: "No unreleased notes found for {repo}. Nothing to release."
+
+The frontmatter `repo:` field on each branch-notes file confirms which project repo the notes belong to — match that to the directory name as a sanity check. Notes mismatched on `repo:` are a sign of manual file moves; surface to the user.
 
 **Step 3: Group and organize**
-Group notes by type using `type:` frontmatter (feature, fix, chore):
-- Features first, then fixes, then chores
-- Within each group, order chronologically by date
+Group notes by `type:` frontmatter (feature, fix, chore). Within each group, order chronologically by date. This ordering drives bullet sequence in the synthesized entry.
 
 **Step 4: Handle questions**
 Present all open questions from `branch-release-questions-*.md` files:
 "These questions are still open from development. For each one:"
 - **Answer** — provide the answer, remove from questions
-- **Defer** — keep in a "Known Issues" section of the release notes
+- **Defer** — keep as a "Known issues" sub-bullet in the CHANGELOG entry
 - **Discard** — no longer relevant
 
-**Step 5: Synthesize release document**
-Write `repos/{repo}/release-notes/v{version}.md`:
-```markdown
-# v{version} Release Notes
-
-**Date:** {YYYY-MM-DD}
+**Step 5: Synthesize the CHANGELOG entry**
 
-## Features
-{Coherent narrative combining all feature branch-release-notes.
-Deduplicate related items. Credit authors.
-Write from scratch — don't concatenate. Coherent-revisions rule applies.}
+Read the current `repos/{repo}/CHANGELOG.md` (if it exists) so the new entry matches the existing voice and structure. If no CHANGELOG exists, create one with a short header explaining that entries are written for package users, not contributors.
 
-## Fixes
-{Same treatment for bugfix branches.}
+Prepend a new section at the top of the changelog body (after the header, before any existing version entries). Write it user-facing — what shipped, not how it shipped:
 
-## Maintenance
-{Same for chore branches.}
+```markdown
+## v{version} — {YYYY-MM-DD}
 
-## Known Issues
-{Deferred questions from Step 4, if any.}
+- {Concise bullet per meaningful change. Features, fixes, and chores interleaved
+  by significance, not by category. Each bullet is one sentence or short paragraph
+  in plain user-facing language: "the CLI now supports X", "corrected Y behavior
+  on Z", not "we decided" or "the team merged." Deduplicate related items.
+  Write from scratch per the coherent-revisions rule.}
 
-## Contributors
-{List of unique authors from all branch notes.}
+### Known issues
+- {Deferred questions from Step 4, if any. Omit this subsection when empty.}
 ```
 
-**Step 6: Archive unreleased files**
+The entry stays short. If a change needs more detail, reference the repo's docs or a dedicated design doc — do not inline session-level retrospection into the public changelog.
+
+**Step 6: Delete consumed branch notes from the workspace**
 ```bash
-mkdir -p repos/{repo}/release-notes/archive/v{version}
-mv repos/{repo}/release-notes/unreleased/branch-release-* repos/{repo}/release-notes/archive/v{version}/
+rm release-notes/unreleased/{repo}/branch-release-*
+# If the directory is now empty, remove it too:
+rmdir release-notes/unreleased/{repo} 2>/dev/null || true
 ```
+The branch notes were an intermediate capture; their content is now in the CHANGELOG entry and their raw form in git history. They do not survive into the project repo.
 
-**Step 7: Commit release notes to project repo**
+**Step 7: Commit the CHANGELOG entry to the project repo**
 ```bash
 cd repos/{repo}
-git add release-notes/
-git commit -m "docs: v{version} release notes"
+git add CHANGELOG.md
+git commit -m "docs: v{version} changelog entry"
 ```
+This commit lands on the project repo's source clone (which stays on its default branch). The user pushes it when ready — `/release` does not push automatically.
 
-**Step 7b: Bump package.json version**
-If the project repo has a `package.json` with a `version` field (as in the scaffolder repo), update it to match the release version:
+**Step 7b: Bump package.json version (project repo)**
+If the project repo has a `package.json` with a `version` field, update it to match the release version:
 ```bash
 cd repos/{repo}
 # Update "version": "..." in package.json to the release version
@@ -90,9 +95,17 @@ git commit -m "chore: bump version to v{version}"
 ```
 Skip this step if the repo has no package.json or no version field.
 
+**Step 7c: Commit the consumed-notes deletion in the workspace**
+```bash
+# From the workspace root
+git add release-notes/unreleased/
+git commit -m "release: consume {repo} branch notes for v{version}"
+```
+Workspace and project repos have separate commits — they are separate git histories.
+
 **Step 8: Consume project-scoped specs**
 Project-scoped specs and plans in `shared-context/{user}/` (ongoing) that are fully covered by this release:
-- Consume into the release notes (their content is now captured in the versioned doc)
+- Consume into the CHANGELOG entry (their content is now captured there)
 - Remove the source files
 - If partially covered: rewrite the spec to reflect only what remains unimplemented
 
@@ -116,11 +129,14 @@ Process ephemeral shared-context entries:
    ```
 
 **Step 10: Report**
-"Release v{version} complete for {repo}. {N} branch notes combined. {M} context entries synthesized into {K} locked entries."
+"Release v{version} complete for {repo}. {N} branch notes consumed into CHANGELOG.md. {M} context entries synthesized into {K} locked entries."
 
 ## Notes
-- Release notes live in the PROJECT repo — the workspace never gets versioned
-- Context synthesis happens in the WORKSPACE repo — both get separate commits
-- The archive directory preserves raw branch notes for audit
-- Per-repo is the default — each repo has its own release cadence
-- The coherent-revisions rule applies: write the release narrative from scratch, don't concatenate branch notes
+
+- Release entries live in `CHANGELOG.md` at the project repo root — one file, one concise entry per version. No `release-notes/v*.md`, no `release-notes/archive/`.
+- Branch notes live in the WORKSPACE at `release-notes/unreleased/{repo}/`. `/complete-work` writes them; `/release` consumes and deletes them. They never reach project repos.
+- Versions are bumped here, not in `/complete-work`. This keeps the version semantics aligned with what actually shipped (accumulated changes since last release).
+- The public repo stays lean. Detailed per-branch retrospection exists in workspace git history (the consumed-notes commit) but is not surfaced as standalone files in either repo.
+- Context synthesis happens in the WORKSPACE repo — Step 7c (consumed-notes) and Step 9 (shared-context synthesis) are separate workspace commits.
+- Per-repo is the default — each project repo has its own release cadence.
+- The coherent-revisions rule applies: write the CHANGELOG entry from scratch, don't concatenate branch notes.

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

@@ -53,8 +53,14 @@ Begin or resume a persistent work session. Each session lives in its own `work-s
    - `names` is a list of all names the chat has had (users can rename). Append, never replace.
    - `ended` is set by the session-end hook when the chat closes.
 4. Update the tracker `status:` to `active` if it was `paused`
-5. Run history reconstruction (see below)
-6. Tell user: "Resuming {name}. Work from `work-sessions/{name}/workspace/`."
+5. Restore the task list from `## Tasks` per the `task-list-mirroring` rule:
+   ```bash
+   cd work-sessions/{name}/workspace
+   node .claude/scripts/sync-tasks.mjs --read session.md
+   ```
+   Pass the parsed `todos` array to `TodoWrite` so the live UI matches the durable state. If the section is missing (legacy session predating this feature), seed it first via `--write` with an empty `todos` array — the helper will insert the bookends.
+6. Run history reconstruction (see below)
+7. Tell user: "Resuming {name}. Work from `work-sessions/{name}/workspace/`."
 
 ### History Reconstruction
 
@@ -165,6 +171,32 @@ Register this chat in the tracker's `chatSessions` frontmatter. For new sessions
 
 The tracker already reflects the correct state — assignment happened in step 5 or 6 via `adapter.claim()`. Do not write to any local file mirror. There is no `open-work.md`.
 
+### Seed the task list
+
+After session creation, seed the `## Tasks` section in the new tracker so `TodoWrite` has something to mirror. See the `task-list-mirroring` rule for the schema.
+
+```bash
+# Build the seed from inside the worktree so the helper resolves workspace.json correctly.
+cd work-sessions/{session-name}/workspace
+echo '{"todos": []}' | node .claude/scripts/sync-tasks.mjs --write session.md
+```
+
+The helper auto-inserts the `Start work` (completed) and `Complete work` (pending) bookends, and resolves the tracker title from `workItem:` if set.
+
+Then call `TodoWrite` with the same seed so the live UI matches:
+
+```javascript
+// Pseudocode — call the actual TodoWrite tool.
+TodoWrite({
+  todos: [
+    { content: 'Start work',    activeForm: 'Starting work',    status: 'completed' },
+    { content: 'Complete work', activeForm: 'Completing work',  status: 'pending'   },
+  ]
+});
+```
+
+The auto-commit at the end of "Capture prior conversation context" picks up the new section — no separate commit needed.
+
 ### Capture prior conversation context
 
 If brainstorming, spec writing, or design discussion happened in this conversation before `/start-work` was called, that reasoning needs to be captured into the session tracker body. Otherwise it will be lost when the conversation ends and `/complete-work` will produce thin release notes.

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

@@ -75,6 +75,22 @@ Also handle these non-component files from the payload:
 
 Read `toVersion` from `.workspace-update/.manifest.json` and update `templateVersion` in `workspace.json` to match.
 
+### Step 4a: Run idempotent migrators
+
+The payload may include migrator scripts at `.workspace-update/.claude/scripts/migrate-*.mjs` that bring older workspaces forward in shape. They are idempotent — safe to re-run on already-migrated workspaces. Run each one and surface its action in the upgrade summary.
+
+```bash
+node .workspace-update/.claude/scripts/migrate-claude-md-freshness-include.mjs
+```
+
+Output is JSON: `{"action":"appended"|"unchanged"|"skipped"}`.
+
+- `appended` — the workspace's `CLAUDE.md` got the `@local-only-template-freshness.md` include line added at the end.
+- `unchanged` — the line was already present.
+- `skipped` — no `CLAUDE.md` exists at the workspace root (rare; surface to the user).
+
+Add other migrators here as the template ships them.
+
 ### Step 5: Post-update verification
 
 Run `/maintenance audit` again to verify the update didn't introduce: