@ulysses-ai/create-workspace 0.16.0-beta.1 → 0.18.0-beta.0

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

@@ -11,7 +11,7 @@ Save structured workstream state to workspace-context. Usable anytime, any numbe
 - `/handoff {name}` — create or update a named handoff
 - `/handoff` (no param) — analyze session and suggest name(s)
 
-## Session-Aware Behavior
+## Lifecycle-Aware Behavior
 
 When called within an active work session (the active-session pointer at `.claude/.active-session.json` exists inside the current worktree):
 
@@ -26,9 +26,16 @@ When called within an active work session (the active-session pointer at `.claud
   git commit -m "handoff: update {session-name} tracker"
   ```
 
-When called from the workspace root (no active session):
-- Only `local-only-*` files are writable from the root
-- Suggest starting a work session first, or use the helper with `--local-only`
+Under the task model — `workspace.sessionModel` is `"task"` in `workspace.json` 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/`
+
+When called from the workspace root with no active session — every other case, including a `sessionModel: "session"` workspace (the `Chat record:` line is injected in every chat, so it alone does not select the drawer):
+
+- Use `--local-only` so the captured file is gitignored (the root only allows local-only writes), landing in `team-member/{user}/`
+- If the task model applies but the `Chat record:` line is absent, say the drawer destination is unavailable for that reason
+- Suggest starting work (`/start-work`) first if the handoff is about actionable work
 
 The flows below apply when NOT in an active work session, or when the user explicitly asks for a standalone handoff file.
 

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

@@ -44,6 +44,10 @@ For each workspace-context `.md` file and each `work-sessions/*/workspace/sessio
 - Worktrees whose branch has already been merged? (cleanup candidates)
 - 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.
+- 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).
+  - **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
 
@@ -108,22 +112,39 @@ Report one of:
 
 Active recommendations. Flags problems and suggests fixes, but asks before acting.
 
-### 7. Stale context
+### 7. Component age check
+
+Scan the following file sets for a YAML frontmatter `updated:` field:
+- `.claude/rules/*.md` (active rules only — `.md.skip` files are included too, since the rule content can still drift)
+- `.claude/skills/*/SKILL.md`
+- `.claude/agents/*.md`
+- `.claude/hooks/*.mjs`
+
+For each file that has an `updated:` field, compute the age in days from today. If the age exceeds 180 days, flag the file as a stale component candidate. Print the file name, the `updated:` date, and the age in days so the contributor knows how far the file has drifted.
+
+Files without an `updated:` field are skipped — the check is opt-in and activates the discipline incrementally as contributors add frontmatter to the files they own. To start tracking a file, add `updated: <today>` to its frontmatter; the check will surface it if it goes stale.
+
+When stale candidates are found, surface them as warnings in the output format and link to `config-review.md.skip` (in `.claude/rules/`) as the opt-in rule that documents the review cadence and rationale.
+
+### 8. 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
+- Unrecorded task-prefixed worktrees (no chat-record entry claims them; may be no-tracker tasks) — ask, then suggest `task-worktree.mjs --remove`
+- 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")
 - Handoffs referencing deleted branches — suggest resolve or remove
 
-### 8. Context reconciliation
+### 9. Context reconciliation
 - Read recent workspace-context writes (last session or last N files by updated date)
 - For each, scan other workspace-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
 
-### 9. Canonical budget triage
+### 10. Canonical budget triage
 
-This step runs only when the post-regen `--check` from step 8 still reports `selectionStatus: 'over-budget'`. If the regular regen pass cleared the budget — or if `--check` was already `ok`, `trimmed`, or `stubbed` after step 8 — skip this step entirely.
+This step runs only when the post-regen `--check` from step 9 still reports `selectionStatus: 'over-budget'`. If the regular regen pass cleared the budget — or if `--check` was already `ok`, `trimmed`, or `stubbed` after step 9 — skip this step entirely.
 
 The rest of cleanup is suggestion-list-with-confirmation: surface a candidate, ask before applying, move on. Triage is the one meaningfully more interactive surface in `/maintenance`. It runs as a small REPL: present the budget state and a triage menu, take one action, re-run `--check`, present the menu again with the new state. No suggestion is auto-applied; every action is the user's choice.
 
@@ -168,7 +189,19 @@ For each chosen action:
 
 Trim markers and demotions only matter for `priority: reference` files — `<!-- canonical:trim -->` spans on a `priority: critical` file are inert until the file is demoted. The triage flow never auto-decides which file to demote or which section to wrap; it surfaces the data, presents options, and waits.
 
-### 10. Health metrics
+### 11. Forge configuration
+
+Read `workspace.json`. If `workspace.tracker?.type === 'github-issues'` and `workspace.forge` is unset, emit a notice (not an error):
+
+```
+ℹ workspace.json has tracker.type='github-issues' but no workspace.forge field.
+  Skills default to GitHub forge operations; add `"forge": {"type": "github"}`
+  to workspace.json to make the choice explicit. See .claude/rules/forge-operations.md.
+```
+
+This is migration guidance for workspaces created before the `forge` field landed — the field is back-compat with a sensible default, so the unset case is not a bug, just an opportunity to make the implicit explicit. If `workspace.forge.type` is set to a value with no adapter at `.claude/scripts/forges/{type}.mjs`, that IS an error and goes in the Issues section.
+
+### 12. Health metrics
 - Canonical budget — read from the same `--check` invocation as step 5. Reported as `current / budget` bytes with the selection status (e.g., `full`, `2 reference files trimmed`). Over-budget cases are deferred to the cleanup triage flow rather than re-reported here.
 - Number of ephemeral files — flag if accumulating without resolution
 - Session log stats (if `workspace-scratchpad/session-log.jsonl` exists):
@@ -215,7 +248,7 @@ OK (5):
 5. Check git state (worktrees, branches, remotes)
 6. Run `node .claude/scripts/build-workspace-context.mjs --check --root .` — capture status. Exit `0` = clean and within budget, `1` = artifact missing or stale, `2` = artifacts current but canonical body over budget. The `canonical` block in the JSON output drives both the audit budget line and the cleanup triage decision.
 7. Read session-log.jsonl if it exists
-8. If cleanup mode: regenerate the workspace-context auto-files if stale (index.md, canonical.md, per-user team-member indexes); compare files pairwise for overlap; scan for stale cross-references. If post-regen `--check` reports `over-budget`, enter the canonical-budget triage flow described in cleanup step 9.
+8. If cleanup mode: regenerate the workspace-context auto-files if stale (index.md, canonical.md, per-user team-member indexes); compare files pairwise for overlap; scan for stale cross-references. If post-regen `--check` reports `over-budget`, enter the canonical-budget triage flow described in cleanup step 10.
 9. Compile and present findings grouped by severity
 
 ## Notes

package/template/.claude/skills/migrate-sessions/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: migrate-sessions
+description: Migrate this workspace from the session lifecycle to the task lifecycle — inventory old work sessions, decide each one with the operator, finish or archive them, and switch workspace.json to the task model. Runs only inside the current workspace; never deletes anything.
+---
+
+# Migrate Sessions
+
+Drain a workspace's accumulated session entries and switch new work to the task lifecycle. The script is `.claude/scripts/migrate-sessions.mjs`; this skill is the operator procedure around it.
+
+**Scope rule, before anything else: this skill acts only on the workspace it is run in.** Never read, inventory, or act on any other workspace or directory — even if asked to "do them all." Each workspace runs its own migration from its own root, by its own operator, on its own schedule.
+
+**Run from the launcher root only** — the workspace root itself, never a session folder or any other worktree. The script refuses a linked-worktree `--root` on its own (one exception, the Switch step below), and it refuses to back up or archive the session that hosts the current chat, so there is no way to drain the session you are sitting in from inside it.
+
+## 1. Inventory
+
+```bash
+node .claude/scripts/migrate-sessions.mjs --inventory
+```
+
+Read-only. Present the stderr table plus each session's proposal with its reasons and warnings. Say plainly that the proposals are proposals — evidence and a starting point, not decisions. Pay particular attention to the per-remote state shown per worktree (`same`, `ahead +N`, `behind -N`, `diverged +N/-M`, `not-fetched`, `unknown`) and to `unbacked` warnings: they change what Finish and Archive mean for that session. Entries shown as `foreign` (symlinked) are never acted on — surface them for manual reconciliation.
+
+## 2. Decide per session, with the operator — one at a time
+
+For each session, lay out its evidence and ask the operator which way to go. Never infer the decision from the proposal. The options:
+
+- **Finish** (typical for MERGEABLE) — resume the session with `/start-work`, then run `/complete-work`; its own merge confirmation applies there. But if the inventory shows a **diverged** remote for that session, say so *before* the operator chooses Finish: `/complete-work`'s plain push will be rejected, and pushing the rewritten history needs `--force-with-lease` — which you run only on the operator's explicit yes naming the branch. Never force silently.
+- **Archive** (typical for ABANDONED, a broken shell, or a MERGEABLE the operator gives up on) — take it out of the active lifecycle without destroying anything. Two steps, each its own decision:
+  1. **Offer a backup.** Archiving keeps everything on this machine; a backup adds an off-machine copy of the session's commits, and it is what makes a later deletion safe. It creates `drain/{session}/…` tags and pushes them to the resolved remote(s) — tags may land in a public repository, so show the plan first: `node .claude/scripts/migrate-sessions.mjs --backup --session {name} --dry-run` (add `--remote <name>` to aim somewhere other than the resolved default). It lists, per tip, the tag, the remote, and which tips a remote branch or tag already holds exactly, with no side effects. On the operator's yes, run it without `--dry-run` and show the tags it created. Declining is fine — the archive still keeps everything locally. A repo with no remote at all is refused by backup; say so.
+  2. **Archive after an explicit yes naming the session:** `node .claude/scripts/migrate-sessions.mjs --archive --session {name}`. The whole session folder moves to `{sessions}/.archived/{name}--{timestamp}/` and git's worktree links are repaired to follow it — every commit, uncommitted edit, untracked or ignored file, and embedded repository comes along. If the move or the repair fails, the session is put back and the result says whether every link was verified. The session's branches stay checked out in the archived worktrees, so a new task cannot reuse those branch names until the archive is deleted. The archive refuses, touching nothing, when a directory in the folder cannot be read, when the folder holds a worktree of a repository outside this workspace, or when it holds a submodule checkout (its link cannot be repaired) — surface the reason; for a submodule the options are Finish or Keep. Relay any `warnings` (relative symlinks that pointed outside the session no longer resolve after the move).
+- **Keep** (typical for ACTIVE, and the only sane answer for UNKNOWN) — leave it; it completes later under the session lifecycle.
+
+Unbacked commits (present on no remote) are safe in an archive — they are only ever at risk when someone deletes one. Say so when you archive such a session, and offer the backup.
+
+## 3. Switch — never write the launcher's tracked `workspace.json` directly
+
+The switch procedure:
+
+1. Create a workspace task worktree for the change:
+   ```bash
+   node .claude/scripts/task-worktree.mjs --root . --create --repo . --branch chore/enable-task-model
+   ```
+2. Run the switch against that worktree (the one mode that accepts a linked-worktree root — it only edits `workspace.json`):
+   ```bash
+   node .claude/scripts/migrate-sessions.mjs --enable-task-model --root .claude/worktrees/chore-enable-task-model
+   ```
+3. Commit there, open a PR through the workspace's normal flow, and pull the launcher after merge. The launcher root never commits to its default branch.
+
+The switch output reports `remainingSessions: null` when run from the worktree — the real remaining-sessions list comes from a separate `--inventory` at the launcher root. Remaining sessions are fine either way: they keep resuming and completing under the session lifecycle after the switch.
+
+## 4. Verify
+
+Re-run `--inventory` at the launcher root and report what remains and why — kept sessions, anything the operator deferred, foreign entries, or an empty list.
+
+## 5. Afterwards
+
+The first new piece of work starts with `/start-work` under the task lifecycle.
+
+## Deleting an archive — the operator's call, never this skill's
+
+Archives are meant to be kept until the operator has looked at them. When the operator asks to delete one, first show them — for the whole archive, not just its top level — everything that deletion would destroy, per worktree (list them with `git -C {repo} worktree list --porcelain` in the workspace repo and each `repos/{name}`, filtered to paths under the archive):
+
+- commits no remote holds: `git -C {worktree} log --oneline --branches --not --remotes` and whether a `drain/*` tag covers the tip;
+- uncommitted, untracked and ignored files: `git -C {worktree} status --porcelain --ignored`;
+- edits hidden from status: `git -C {worktree} ls-files -v` — any lowercase tag (assume-unchanged) or `S` (skip-worktree) whose file differs from the index;
+- per-worktree refs that die with the worktree: `git -C {worktree} for-each-ref refs/worktree refs/bisect`;
+- an operation in progress: `MERGE_HEAD`, `rebase-merge`, `rebase-apply` under `git -C {worktree} rev-parse --git-dir`;
+- embedded repositories (any `.git` directory under the archive) and their unpushed branches;
+- files in the archive outside the worktrees (e.g. beside `workspace/`).
+
+Only on their explicit yes naming the archive: remove the worktrees deepest-first (`git -C {repo} worktree remove --force {path}`), delete each branch they confirm (`git -C {repo} branch -D {branch}`), then delete the archive folder. Nothing in this workspace does this automatically.

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

@@ -28,7 +28,15 @@ This is a coherent rewrite of the Progress section, not an append (coherent-revi
 
 ### Step 3: Update frontmatter status and post pause comment on tracker
 
-Use the session-frontmatter helper to set `status: paused` in the tracker's frontmatter.
+Set `status: paused` in the tracker's frontmatter. `.claude/lib/session-frontmatter.mjs` is
+a library, not a CLI — running it with flags does nothing and exits 2:
+
+```bash
+node --input-type=module -e '
+import { updateSessionFile } from "./.claude/lib/session-frontmatter.mjs";
+updateSessionFile("session.md", { status: "paused" });
+'
+```
 
 If the session tracker has a `workItem:` field AND `workspace.tracker` is configured, post a pause comment on the linked issue via the adapter:
 
@@ -95,16 +103,33 @@ git push -u origin {branch}
 
 ### Step 7: Create draft PRs
 
-```bash
-# For each repo in the tracker's repos:
-cd work-sessions/{session-name}/workspace/repos/{repo}
-gh pr create --draft --title "WIP: {description}" --body "Work in progress. Session paused."
+PR creation goes through the forge adapter (`.claude/scripts/forges/interface.mjs`), not directly through `gh` — see `.claude/rules/forge-operations.md` for the contract and why. The adapter resolves the target repo from `workspace.forge.repo` or the local git remote.
 
-# Workspace repo — from the workspace worktree
-gh pr create --draft --title "context: {session-name} (paused)" --body "Workspace context for paused session."
+```javascript
+import { createForge } from './.claude/scripts/forges/interface.mjs';
+import { readFileSync } from 'node:fs';
+
+const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+const forge = createForge(ws.workspace?.forge);
+
+// For each repo in the tracker's repos, from work-sessions/{session-name}/workspace/repos/{repo}:
+const projectPr = await forge.prCreate({
+  title: `WIP: ${description}`,
+  body: 'Work in progress. Session paused.',
+  draft: true,
+});
+console.log(projectPr.url);
+
+// Workspace repo — from the workspace worktree:
+const workspacePr = await forge.prCreate({
+  title: `context: ${sessionName} (paused)`,
+  body: 'Workspace context for paused session.',
+  draft: true,
+});
+console.log(workspacePr.url);
 ```
 
-If PRs already exist, update them to draft status if needed.
+If PRs already exist, update them to draft status if needed (use `gh pr ready --undo` directly until a `forge.prSetDraft` method lands — that's tracked as a future forge adapter extension, not blocking here).
 
 ### Step 8: Confirm
 

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

@@ -1,151 +1,87 @@
 ---
 name: release
-description: Prepend a new CHANGELOG.md entry per project repo by synthesizing unreleased branch notes. Deletes consumed branch notes and synthesizes workspace-context into canonical (locked) entries. Use at release time.
+description: Cut a versioned release of one project repo — bump the version, merge it through a PR, tag it, and publish a forge release whose notes are generated from merged PRs. No release-notes files.
 ---
 
 # Release
 
-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-context into canonical (locked) team knowledge.
+Cut a versioned release of one project repo. The version bump travels through a PR like any other change; the tag marks the merge commit; the forge generates the release notes from merged PR titles. The workspace keeps no release-notes files of its own.
 
 ## 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.
+Release notes come from the forge. GitHub's generated notes (merged PR titles) are what users of a published release actually read; the detail behind each PR already lives in the issue and the PR body, so duplicating it into workspace files buys nothing. Projects that use changesets, semantic-release, or their own release tooling simply don't use this skill. A repo's `CHANGELOG.md`, if it has one, is historical — this skill never writes it.
 
 ## Parameters
-- `/release {version}` — create a release entry for a specific version
+
+- `/release {version}` — release a specific version
 - `/release` — ask for the version
 
 ## Flow
 
 **Step 1: Determine version and repo**
-If no version parameter: ask "What version is this release? (e.g., 1.2.0)"
-
-Check `workspace.json` for `releaseMode`:
-- **per-repo** (default): ask which repo to release
-- **workspace**: process all repos together
-- **ask**: "Process all repos together or individually?"
 
-**Release-notes base directory.** Read `workspace.releaseNotesDir` from `workspace.json` (default `workspace-context/release-notes` if the field is absent). Throughout this skill `{releaseNotesDir}` refers to that resolved value; every branch-note path is `{releaseNotesDir}/unreleased/{repo}/…`. Never use a bare `release-notes/`.
+Ask which repo to release — read `repos` from `workspace.json` and default to the entry with `"primary": true`. If no version was given, ask the bump kind (patch/minor/major) after showing the merged PRs since the last tag, so the operator can judge the impact:
 
-**Step 2: Read unreleased notes**
-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 {releaseNotesDir}/unreleased/{repo}/
+git -C repos/{repo} describe --tags --abbrev=0
 ```
-Read all `branch-release-notes-*.md` and `branch-release-questions-*.md` files.
 
-If no unreleased files exist for a target repo: "No unreleased notes found for {repo}. Nothing to release."
+Then call the forge adapter's `prList` with a merged-after search bounded by that tag's date (e.g. `merged:>{date}`). Pre-v1.0 breaking changes are a minor bump.
 
-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 2: Preflight the tag**
 
-**Step 3: Group and organize**
-Group notes by `type:` frontmatter (feature, fix, chore). Within each group, order chronologically by date. This ordering drives bullet sequence in the synthesized entry.
+If `v{version}` already exists on origin, stop and ask — reuse it, investigate with `forge.releaseView`, or pick another version. Never force-push a tag.
 
-**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 as a "Known issues" sub-bullet in the CHANGELOG entry
-- **Discard** — no longer relevant
+```bash
+git -C repos/{repo} ls-remote --exit-code origin refs/tags/v{version}
+```
 
-**Step 5: Synthesize the CHANGELOG entry**
+**Step 3: Bump on a branch**
 
-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.
+Create a task worktree for the release branch:
 
-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:
+```bash
+node .claude/scripts/task-worktree.mjs --root . --create --repo "{repo}" --branch "release/v{version}"
+```
 
-```markdown
-## v{version} — {YYYY-MM-DD}
+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.
 
-- {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.}
+**Step 4: Merge**
 
-### Known issues
-- {Deferred questions from Step 4, if any. Omit this subsection when empty.}
-```
+Push the branch and open a PR through the forge adapter — per-repo `createForge({ ...ws.workspace?.forge, repo: '{owner}/{name}' })` with head `release/v{version}`. Ask `Merge? [Y/n]`, then merge (squash, delete branch).
 
-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 5: Tag and publish**
 
-**Step 6: Delete consumed branch notes from the workspace**
-```bash
-rm {releaseNotesDir}/unreleased/{repo}/branch-release-*
-# If the directory is now empty, remove it too:
-rmdir {releaseNotesDir}/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.
+Pull the merge, tag it, push the tag, and publish the forge release:
 
-**Step 7: Commit the CHANGELOG entry to the project repo**
 ```bash
-cd repos/{repo}
-git add CHANGELOG.md
-git commit -m "docs: v{version} changelog entry"
+git -C repos/{repo} pull --ff-only
+git -C repos/{repo} tag v{version}
+git -C repos/{repo} push origin v{version}
 ```
-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 (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
-git add package.json
-git commit -m "chore: bump version to v{version}"
+```js
+await forge.releaseCreate({ tag: 'v{version}', repo, generateNotes: true });
 ```
-Skip this step if the repo has no package.json or no version field.
 
-**Step 7c: Commit the consumed-notes deletion in the workspace**
+If the repo has `.github/workflows/publish.yml`, find and watch its run with `workflowRunFind` / `workflowRunWatch` — retry the find up to 5 times with 3 s backoff (the run may not be registered the moment the tag lands). A failed run is reported to the operator, not thrown.
+
+**Step 6: Tear down and report**
+
+Remove the release worktree:
+
 ```bash
-# From the workspace root
-git add {releaseNotesDir}/unreleased/
-git commit -m "release: consume {repo} branch notes for v{version}"
+node .claude/scripts/task-worktree.mjs --root . --remove --repo "{repo}" --branch "release/v{version}" --delete-branch
 ```
-Workspace and project repos have separate commits — they are separate git histories.
-
-**Step 8: Consume project-scoped specs**
-Project-scoped specs and plans in `workspace-context/team-member/{user}/` (ongoing) that are fully covered by this release:
-- 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
-
-**Step 9: Synthesize workspace-context for canonical promotion**
-Process ephemeral workspace-context entries:
-
-1. List all ephemeral entries with `lifecycle: resolved` (across `shared/` and any `team-member/{user}/`).
-2. For each, determine:
-   - Does an existing locked entry cover this topic? → Merge into it (enrich)
-   - Are there related resolved entries? → Combine into a new locked entry
-   - Is it stale/fully consumed by release notes? → Archive or delete
-   - Is it unresolvable but still valuable? → Move to `team-member/{user}/` ongoing or keep at `shared/` root ephemeral
-3. For merged/new locked entries:
-   - Set `state: locked`, `type: synthesized` (or `type: reference` for clean truths)
-   - Write to `workspace-context/shared/locked/{bare-name}.md` — locked files use bare names (location signals the type), so strip any `braindump_/handoff_/research_` prefix when promoting
-   - Write concise, focused content — team truths, not session history
-4. Regenerate auto-files so `canonical.md` and `index.md` reflect the new locked content:
-   ```bash
-   node .claude/scripts/build-workspace-context.mjs --write --root .
-   ```
-5. Commit:
-   ```bash
-   git add workspace-context/
-   git commit -m "release: synthesize workspace-context for v{version}"
-   ```
-
-**Step 10: Report**
-"Release v{version} complete for {repo}. {N} branch notes consumed into CHANGELOG.md. {M} context entries synthesized into {K} locked entries."
+
+Report the PR, the tag, the release URL, and the publish status.
+
+**Step 7: 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.
 
 ## 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 `{releaseNotesDir}/unreleased/{repo}/` (resolved from `workspace.json` → `workspace.releaseNotesDir`, default `workspace-context/release-notes`). `/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 (workspace-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.
-- Tagging happens in `/complete-work`, not here. When the session branch starts with `release/`, `/complete-work` tags the merge commit on the project repo's default branch and pushes the tag, which triggers `.github/workflows/publish.yml` to publish to npm. `/release` produces the synthesis (CHANGELOG entry + version bump + consumed-notes deletion); `/complete-work` does the push, PR, merge, and tag.
-- Do not run `npm publish` locally. The publish workflow is the only path that exercises OIDC trusted publishing — local publish requires 2FA OTP and bypasses that. If the workflow fails, investigate via `gh run view`; do not fall back to local publish.
-- Recovery from a failed publish. Transient failure: rerun via `gh run rerun {run_id}`. Content failure: delete the tag (`git push origin --delete v{version} && git tag -d v{version}`), then redo the release in a new release session — `/start-work`, then `/release v{version}`, then `/complete-work`. Once a version is published to npm, that version is committed on the registry; bump and start a new release.
+- Never run `npm publish` locally. The publish workflow is the only path that exercises OIDC trusted publishing; a local publish requires a 2FA OTP and bypasses it. If the workflow fails, investigate via `gh run view` — do not fall back to a local publish.
+- Recovery from a failed publish: transient failures rerun via `gh run rerun {run_id}`; content failures mean deleting the tag and redoing the release. Once a version is published to a registry, that version number is committed — bump and release a new version instead.
+- Pre-v1.0 breaking changes are a minor bump, not major.

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

@@ -5,6 +5,8 @@ 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.
+
 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.
 
 ## Parameters
@@ -13,6 +15,55 @@ Begin or resume a persistent work session. Each session lives in its own `work-s
 - `/start-work handoff` — list shared context to resume from
 - `/start-work all` — list active sessions across all users (for shared debugging or multi-user workspaces)
 
+## Flow: Task (session model v2)
+
+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. Tell the user plainly what that costs: without a tracker there is no `workItem`, the task is not recorded on the chat record, and `/complete-work` cannot find it from the launcher. It is completed either by running `/complete-work` from inside the worktree (cwd detection) or by opening the PR by hand.
+
+1. **Identify or create the tracker issue and claim it** — the same adapter calls as Flow: Blank steps 3–6:
+
+   ```javascript
+   import { createTracker } from './.claude/scripts/trackers/interface.mjs';
+   import { readFileSync } from 'node:fs';
+   const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+   const tracker = createTracker(ws.workspace.tracker);
+   const assigned = await tracker.listAssignedToMe();
+   const candidates = assigned.length > 0 ? assigned : await tracker.listUnassigned();
+   ```
+
+   Present the list as Flow: Blank step 4 does. When the pick came from the unassigned fallback, claim it atomically and re-fetch on `ALREADY_ASSIGNED` exactly as Blank step 5 shows; for "something new", create and self-assign per Blank step 6:
+
+   ```javascript
+   const newIssue = await tracker.createIssue({
+     title: description,
+     body: `Created at /start-work by ${user}.`,
+     labels: [type, priority],
+     milestone: milestone || null,
+   });
+   await tracker.claim(newIssue.id);
+   ```
+
+   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 "."`).
+
+3. **Propose the branch** — `{prefix}/{slug}` with the prefix from type (`feature/`, `bugfix/`, `chore/`), per the branch-naming step in Flow: Blank.
+
+4. **Create one worktree per repo the work touches:**
+   ```bash
+   node .claude/scripts/task-worktree.mjs --root . --create --repo "{repo}" --branch "{branch}"
+   ```
+   The script fetches origin best-effort (offline is fine) before choosing the base. A project repo's worktree lands at `repos/{repo}/.claude/worktrees/{slug}/` — Claude Code's native worktree location — based on `origin/{defaultBranch}` when that ref exists, and never tracking it. For `.` the worktree lands at `.claude/worktrees/{slug}/` — the same native location, one level up — based on the workspace origin's HEAD (falling back to `main`); the workspace's own `.gitignore` already covers the path.
+
+5. **Record the task on this chat's record** (only when a `workItem` exists — see the no-tracker note above):
+   ```bash
+   node .claude/scripts/chat-record.mjs --root . --add-task --chat "{chat}" --work-item "{workItem}" --branch "{branch}" --repo "{repo}"
+   ```
+   `{chat}` is the name from the `Chat record:` line the SessionStart hook injected into this conversation. If there is no such line, say so and skip recording rather than guessing a name.
+
+6. **Tell the user where the work happens:** the worktree path(s) above — edits belong there, not in the source clones at `repos/{repo}/`. Work continues from this chat by path. A chat started inside a **project** worktree would not load the workspace's conventions or hooks (a worktree is a context boundary), so staying here is the default. A `.` worktree does load a copy of the workspace's `CLAUDE.md`/`.claude/` — but with the worktree as root, so its chat records land in the worktree's own scratchpad rather than the launcher's; the task still belongs to this chat.
+
 ## Flow: No Parameter
 
 1. Read the current user from `.claude/settings.local.json` → `workspace.user`. If unset, behave as `/start-work all` (no user filter). If the user invoked `/start-work all`, also skip filtering.
@@ -40,7 +91,7 @@ Begin or resume a persistent work session. Each session lives in its own `work-s
    - Workspace: `work-sessions/{name}/workspace/`
    - For each repo in `repos:` frontmatter: `work-sessions/{name}/workspace/repos/{repo}/`
    - If any are missing, recreate from the branch
-3. The session-start hook automatically registers each chat in the session tracker's `chatSessions` frontmatter when Claude opens in a worktree. Verify the current chat is registered — if not (e.g., the hook didn't fire), add an entry manually via the session-frontmatter helper.
+3. The session-start hook automatically registers each chat in the session tracker's `chatSessions` frontmatter when Claude opens in a worktree. Verify the current chat is registered — if not (e.g., the hook didn't fire), append an entry using the invocation shown under "Create work session" below (the helper is an importable library, not a CLI).
 
    Each `chatSessions` entry has this shape:
    ```yaml
@@ -55,7 +106,7 @@ Begin or resume a persistent work session. Each session lives in its own `work-s
 4. Update the tracker `status:` to `active` if it was `paused`
 5. Restore the task list from `## Tasks` per the `task-list-mirroring` rule:
    ```bash
-   cd work-sessions/{name}/workspace
+   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.
@@ -165,9 +216,40 @@ The script creates:
 - Active-session pointer at `work-sessions/{session-name}/workspace/.claude/.active-session.json`
 - Copies `settings.local.json` into the worktree if it exists at the workspace root
 
-If a `workItem:` was set in step 5 or 6, write it into the tracker's frontmatter via the session-frontmatter helper after creation. This is what `/pause-work` and `/complete-work` use to locate the linked issue.
+If a `workItem:` was set in step 5 or 6, write it into the tracker's frontmatter after
+creation. `/pause-work` and `/complete-work` both use this to locate the linked issue, and
+a session created without it looks fine until one of them silently cannot find the ticket.
+
+`.claude/lib/session-frontmatter.mjs` is a **library, not a CLI** — running it with flags
+does nothing and exits 2. Import it:
+
+```bash
+cd "work-sessions/{session-name}/workspace"
+node --input-type=module -e '
+import { updateSessionFile, readSessionFields } from "./.claude/lib/session-frontmatter.mjs";
+updateSessionFile("session.md", { workItem: "{workItem}" });
+console.log("workItem =", readSessionFields("session.md").workItem);
+'
+```
+
+Read the value back, as above, and confirm it before moving on — this write has failed
+silently before (gh:143).
+
+Register this chat in the tracker's `chatSessions` frontmatter. For new sessions, the session-start hook has already fired (before /start-work was invoked) but the session folder didn't exist yet. Find the current chat's UUID from the most recently modified `.jsonl` file in
+`~/.claude/projects/{project-path}/` and append the entry with the same library:
+
+```bash
+node --input-type=module -e '
+import { updateSessionFile, readSessionFields } from "./.claude/lib/session-frontmatter.mjs";
+const existing = readSessionFields("session.md").chatSessions || [];
+updateSessionFile("session.md", {
+  chatSessions: [...existing, { id: "{uuid}", names: [], started: new Date().toISOString(), ended: null }],
+});
+'
+```
 
-Register this chat in the tracker's `chatSessions` frontmatter. For new sessions, the session-start hook has already fired (before /start-work was invoked) but the session folder didn't exist yet. Find the current chat's UUID from the most recently modified `.jsonl` file in `~/.claude/projects/{project-path}/` and add the entry manually via the session-frontmatter helper. Subsequent chats on this session will be registered automatically by the hook.
+Append — never replace: the list is the session'"'"'s whole chat history. Subsequent chats are
+registered automatically by the hook.
 
 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`.
 
@@ -177,7 +259,7 @@ After session creation, seed the `## Tasks` section in the new tracker so `TodoW
 
 ```bash
 # Build the seed from inside the worktree so the helper resolves workspace.json correctly.
-cd work-sessions/{session-name}/workspace
+cd "work-sessions/{session-name}/workspace"
 echo '{"todos": []}' | node .claude/scripts/sync-tasks.mjs --write session.md
 ```
 
@@ -199,7 +281,7 @@ The auto-commit at the end of "Capture prior conversation context" picks up the
 
 ### 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.
+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 write a thin PR body.
 
 Check: has the current conversation included substantive discussion (design decisions, requirements exploration, approach selection) before this point?
 
@@ -208,7 +290,7 @@ If yes:
 2. Write the summary into `work-sessions/{session-name}/workspace/session.md`'s body, in a `## Pre-session context` or `## Progress` section
 3. Auto-commit from inside the worktree so the capture lands on the session branch:
    ```bash
-   cd work-sessions/{session-name}/workspace
+   cd "work-sessions/{session-name}/workspace"
    git add session.md
    git commit -m "chore: capture pre-session discussion for {session-name}"
    ```