@ulysses-ai/create-workspace 0.17.0-beta.0 → 0.19.0-beta.0

package/template/_claude/skills/context-placement/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: context-placement
+description: Use when deciding where a durable fact, instruction, or procedure belongs — a rule, canonical context, shared or personal context, auto-memory, or a skill — and when writing it once the destination is settled. Routes the decision, states the always-loaded cost before anything is written, and carries the frontmatter schema, generator invocations, and the canonical admission test.
+---
+
+# Context Placement
+
+Something is worth keeping. This skill decides where it goes, and makes the cost of that
+choice visible before you write it.
+
+The hard part is routing, not prose. Most placement mistakes are not badly written files —
+they are correctly written files in a destination that charges every future session for
+them. Two of this workspace's own bugs (gh:136, gh:138) were exactly that: rules that had
+quietly absorbed reference material and worked examples until the always-loaded directory
+cost more than the conversation.
+
+## The destinations
+
+Exactly one of these. The right-hand column is what every session pays, forever, for the
+choice.
+
+| destination | route here when | always-loaded cost |
+|---|---|---|
+| **nowhere** | it is already covered somewhere, or it is true only today | zero |
+| `.claude/rules/{name}.md` with `paths:` | an instruction that applies only when specific files are touched | zero until a matching file is read |
+| `.claude/skills/{name}/SKILL.md` | a procedure with steps, invoked on demand | the `description` line, ~200 B |
+| auto-memory | a machine-local preference or correction; not shared, not reviewable | one `MEMORY.md` line, ~100 B |
+| `workspace-context/team-member/{user}/` | one person's working context | one index line, ~120 B, that user only |
+| `workspace-context/shared/` | team-visible reference to look up when relevant | one index line, ~120 B |
+| `workspace-context/shared/locked/` | a team-wide fact or constraint that passes the canonical test | **the whole file, every session** |
+| `.claude/rules/{name}.md` (no `paths:`) | an instruction that must shape every session, everywhere in the repo | **the whole file, every session** |
+
+The table is ordered by cost, cheapest first. Work down it and stop at the first
+destination that genuinely fits. The two bold rows are the only ones that tax every
+session; reach them only after the cheaper ones have actually been ruled out, not skipped.
+
+**`nowhere` is the most common correct answer.** Before anything else, check whether the
+thing is already stated. A second copy in a second location is worse than no copy: they
+drift, and the reader cannot tell which one is current.
+
+## Step 1 — classify what you have
+
+Three kinds. The kind determines which destinations are even eligible.
+
+- **Instruction** — changes what Claude *does*. "Never force push." "Rebase before opening
+  a PR." Imperative, applies without being asked for. Eligible: rules (scoped or not).
+- **Reference** — something Claude needs to *know* when a particular topic comes up. API
+  shapes, schemas, architecture facts, why an approach was rejected. Eligible: canonical,
+  shared, team-member, auto-memory.
+- **Procedure** — a sequence of steps with a beginning and an end, run on request.
+  Eligible: a skill.
+
+Most drift comes from putting reference or procedure content in a rule. A rule that
+contains an API table or a worked example is carrying reference material at instruction
+prices. Split it: the instruction stays in the rule, the detail moves to a skill or a
+context file, and the rule points at it in one line.
+
+## Step 2 — scope it
+
+For an instruction, the only question that matters is *when must this be true?*
+
+- Every session, every file → unconditional rule.
+- Only when certain files are involved → rule with `paths:`.
+
+`paths:` is a real Claude Code feature and is almost always the better answer for anything
+domain-specific. A rule about migration scripts, or about a single repo's test conventions,
+does not need to be in context while you are editing documentation.
+
+```yaml
+---
+paths:
+  - ".claude/scripts/**/*.mjs"
+  - "repos/*/template/_claude/scripts/**/*.mjs"
+---
+```
+
+Rules with `paths:` load only when Claude reads a matching file. Rules without it load at
+launch, at the same priority as `CLAUDE.md`, in every session — and, for anything shipped
+in the template, in every downstream workspace too.
+
+For reference content, scope is about reach. Pick the narrowest that works: auto-memory
+(this machine only) → `team-member/{user}/` (one person) → `shared/` (the team) →
+`shared/locked/` (the team, always loaded).
+
+## Step 3 — state the cost, then write
+
+Before writing, run the footprint tool and report the projection to the user in one line.
+This step is not optional. Making the cost visible at the decision point is the whole
+reason this skill exists.
+
+```bash
+node .claude/scripts/context-footprint.mjs --root .
+node .claude/scripts/context-footprint.mjs --root . --add <bytes> --as <destination>
+```
+
+Valid `--as` values: `rule`, `rule-scoped`, `locked`, `shared`, `team-member`, `memory`,
+`skill`, `nowhere`.
+
+Say it plainly — "this adds 1.4 KB to every session, taking always-loaded context from
+7.8% to 8.0% of the window" — and then write the file. If the projection looks
+disproportionate to the value, go back to the table and take a cheaper row.
+
+## The canonical test
+
+Canonical content is loaded verbatim into every session prompt, so it frames how Claude
+reads the rest of the conversation. The principle: canonical describes what *is* and what
+*to do*, never what *to think*.
+
+> If Claude read this for the first time during a session about an unrelated topic, would
+> it (a) help frame the problem correctly, or (b) push Claude toward a particular answer to
+> a question that hasn't been asked yet?
+
+(a) is canonical. (b) is `shared/` at most, more often `team-member/{user}/`.
+
+**Belongs in `shared/locked/`:**
+
+- **Facts about the system** — architecture, supported targets, naming conventions, where
+  things live, what is published.
+- **Hard constraints** — "must work on Windows and macOS," "PRs only, no direct push to
+  main." Constraints scope the solution space without prejudging the solution.
+- **Process rules** — workflow discipline that applies regardless of task.
+- **Settled-rejection guardrails** — "we evaluated X, rejected it because Y, do not propose
+  it again." Must include the *why*, so a genuine edge case can still be recognised.
+- **Meta-principles for debiasing** — explicit reminders to widen evaluation.
+
+**Does not:**
+
+- **Opinions on open technical questions.** "Library X beats Y here" makes Claude start
+  from the conclusion instead of reasoning toward it. Write it as a constraint with its
+  reason, or leave it in `shared/`.
+- **Conclusions Claude might be asked to question.** Locking a conclusion on a topic still
+  under design biases the discussion before it starts.
+- **Personal preferences.** Those are `team-member/{user}/`.
+- **Status snapshots that age fast.** `project-status.md` is the bounded exception; finer
+  detail lives in the tracker.
+
+Pre-loaded conclusions do not read as opinions to Claude — they read as ground truth. A
+reference doc Claude *finds* while researching is weighed against the question; a canonical
+doc loaded before the question is asked frames what Claude considers at all.
+
+## Writing a workspace-context file
+
+Frontmatter fields — conventions, not all required on every file:
+
+- `state` — `locked` (team truth, lives under `shared/locked/`) or `ephemeral`.
+- `lifecycle` — for ephemeral files: `active` or `resolved`.
+- `type` — `reference`, `braindump`, `handoff`, `research`, `design`, `index`, `canonical`,
+  `promoted`.
+- `priority` — locked files only: `critical` (always in canonical) or `reference` (eligible
+  for trim or stub under budget pressure). Absent defaults to `critical`.
+- `topic` — kebab-case slug matching the filename after any type prefix.
+- `author` — required for `team-member/{user}/` files.
+- `updated` — ISO date of last meaningful edit. `/maintenance` flags stale `active` files.
+- `description` — one line, used verbatim by the generated indexes. Without it the index
+  falls back to the first sentence, then the filename slug. Adding one to a file with a
+  weak fallback is the cheapest possible index improvement.
+- `confidence` — `high` | `medium` | `low`. Use on research, design, and exploration where
+  conclusions may still shift. Skip on locked files and on handoffs and braindumps.
+
+```yaml
+---
+state: ephemeral
+lifecycle: active
+type: research
+topic: vector-search-evaluation
+description: Evaluation of FAISS for workspace-context — concluded the NL index is sufficient at our scale.
+author: alex
+confidence: medium
+updated: 2026-04-25
+---
+```
+
+## Regenerating the indexes
+
+One generator produces all three artifacts in a single pass:
+
+- `workspace-context/index.md` — catalog of `shared/` (locked first), imported by `CLAUDE.md`.
+- `workspace-context/canonical.md` — verbatim concatenation of `shared/locked/*.md`, also
+  imported by `CLAUDE.md`.
+- `workspace-context/team-member/{user}/index.md` — per-user catalog, imported by each
+  user's gitignored `CLAUDE.local.md`.
+
+```bash
+node .claude/scripts/build-workspace-context.mjs --check --root .   # exits 1 if stale
+node .claude/scripts/build-workspace-context.mjs --write --root .   # regenerate
+```
+
+Gitignored files (anything matching `local-only-*`) are excluded automatically, and
+`workspace-context/.indexignore` adds path-prefix excludes for tracked files that should
+not appear in the shared index.
+
+The canonical byte budget is opt-in: `workspace.canonicalBudgetBytes` is off by default
+(absent or `null`), and the whole always-loaded set is measured by
+`workspace.alwaysLoadedBudgetBytes` instead. When a byte count is set and `canonical.md`
+exceeds it, the builder honours per-file `priority` and section-level
+`<!-- canonical:trim --> ... <!-- canonical:end-trim -->`
+markers to fit: `priority: reference` files are trimmed, then stubbed; `priority: critical`
+files are always included in full. `/maintenance` audits the budget when on and offers
+triage when over.
+
+Hand edits to `index.md`, `canonical.md`, or any per-user index are overwritten. Change the
+source file or its `description:` instead.

package/template/{.claude/rules/goal-driven-work.md → _claude/skills/goal-driven-work/SKILL.md}

@@ -1,23 +1,23 @@
-# Goal-Driven Work
-
-How to use Claude Code's built-in `/goal` command in a Ulysses workspace for multi-phase, agent-team-driven work. `/goal` is the autonomy loop; this rule is the convention layer that gives the main agent durable phase state and a consistent dispatch pattern across turns and resumes.
-
-## When to reach for `/goal`
+---
+name: goal-driven-work
+description: Use when setting up or running multi-phase autonomous work under Claude Code's built-in /goal command in a Ulysses workspace — drafting a goal-{topic}.md artifact, defining phases, dispatching phase agent teams, or completing a goal-driven session. Covers the frontmatter schema, the three phase types, gate conventions, the integration-branch model with per-phase sub-PRs, and model tiering.
+---
 
-Use `/goal` when the work meets all three:
+# Goal-Driven Work
 
-1. **Multi-phase.** It naturally decomposes into discrete phases (research, design, implementation, validation, etc.) and the phases produce intermediate artifacts before the work is done.
-2. **Verifiable end state.** "Done" can be demonstrated from the conversation transcript — a PR opened, a set of artifacts written, a test suite passing — rather than judged subjectively.
-3. **Spans more than one or two turns of natural conversation.** Single-skill invocations (one brainstorm, one plan, one fix) don't need `/goal`; the existing skills carry them.
+The convention layer over Claude Code's built-in `/goal` command. `/goal` is the autonomy
+loop; this skill gives the main agent durable phase state and a consistent dispatch pattern
+across turns and resumes.
 
-If any of the three fails, prefer plain session work or a single skill invocation. `/goal` is overhead. Pay it only when the work is long enough to earn it.
+Read `.claude/rules/goal-driven-work.md` first for whether `/goal` is the right shape for
+the work at hand. This skill covers everything after that decision.
 
 ## File layout
 
-- One `goal-{topic}.md` artifact at the top of the active worktree, alongside `session.md`. One goal per worktree.
+- One `goal-{topic}.md` artifact per effort. Session model: at the top of the session worktree, alongside `session.md`. Task model: in the chat drawer at `workspace-scratchpad/chats/{chat}/`, alongside its phase outputs. One goal per worktree or task either way.
 - The artifact's frontmatter holds machine state; its body holds the human-readable goal statement, per-phase intent, and a mandatory `## Start command` section (see "Kicking off the goal") with the literal `/goal "..."` invocation the user runs to start the loop.
 - Phase output artifacts live as siblings. `research-*.md` and `crossref-*.md` are goal-native (produced by `parallel-research` and `crossref` phase types). `design-*.md` and `plan-*.md` are pre-existing session-artifact patterns that `type: skill` phases reuse when the wrapped skill is `superpowers:brainstorming` or `superpowers:writing-plans`; they are not goal-specific.
-- The artifact is tracked on the session branch and lives there until `/complete-work` runs. It is removed from the branch before the final PR alongside other session artifacts.
+- Session model: the artifact is tracked on the session branch and lives there until `/complete-work` runs, which strips it before the final PR. Task model: the drawer is machine-local and untracked; `/complete-work` routes the artifact (promote into `workspace-context/` or discard) at completion, so while a task is active give the artifact's frontmatter a `workItem: {id}` line — the offer is scoped to the task that owns the artifact.
 
 ## Frontmatter schema
 
@@ -122,7 +122,7 @@ This guidance is workspace-side mitigation only. The underlying friction — the
 
 ## Integration branch and per-phase sub-PRs
 
-While a `/goal`-driven session is running, the session branch (`feature/{session-name}`) acts as the goal's integration branch. Main is untouched until `/complete-work` opens the final session→main PR for human review. This is the key autonomy boundary: phase agents can merge their own work, repeatedly, throughout the goal — but only into the integration branch, never into main.
+While a `/goal`-driven effort is running, its work branch (`feature/{session-name}` for a session, the task's branch for a task) acts as the goal's integration branch. Main is untouched until `/complete-work` opens the final PR for human review. This is the key autonomy boundary: phase agents can merge their own work, repeatedly, throughout the goal — but only into the integration branch, never into main. The integration-branch and sub-branch guidance in this section applies to task branches unchanged.
 
 Two merge strategies, picked per phase:
 
@@ -197,11 +197,38 @@ The `/goal` evaluator runs after every turn against the conversation transcript.
 - **Demonstrable from transcript.** The main agent's own output must be able to evidence completion. "The PR URL was reported in the transcript and `git status` showed clean" rather than "the work feels done."
 - **Bounded.** Includes a turn budget as a backstop (e.g., "or stop after 60 turns") so the loop can't run away if something goes wrong.
 - **Within the 4000-char limit.** Up to four kilobytes of condition text are accepted.
+- **Reachable by the agent.** This is the one that gets written wrong. If any phase carries
+  `gate: review`, or the goal depends on a merge, a deploy, or anything else only the
+  operator can authorise, then a condition demanding those be *done* can never be satisfied
+  by the agent — and the evaluator will re-ping indefinitely against work that is correctly
+  waiting. Either the condition names the blocked state as terminal, or the goal cannot end
+  without the backstop.
+
+**The failure this prevents, observed.** A goal was started with
+
+> All 6 phases show status: complete. […] The seven PRs are merged or closed.
+
+while three of its phases were `gate: review` and the PRs depended on two prerequisite PRs
+merging to `main`. Everything the agent could do was done inside about forty turns; the
+remaining eighty were spent re-reporting the same three blockers, because the condition had
+no terminal state for "built, verified, awaiting authorisation."
+
+Write the disjunction in from the start:
+
+```
+Every phase shows status: complete, or status: awaiting-review with its artifact
+written. […] Either <external step> is done, or it is still pending and that is
+stated in the transcript. Or stop after <N> turns.
+```
+
+Editing the artifact afterwards does not rescue a running goal: the evaluator's text is
+fixed from the original `/goal` invocation. The corrected condition only takes effect after
+`/goal clear` and a re-run of the `## Start command`.
 
 A reasonable template:
 
 ```
-All phases in goal-<topic>.md show status: complete. Phase artifacts exist at: <list paths>. The /complete-work skill has produced release notes and opened the final PR; the PR URL appeared in the transcript. Or stop after <N> turns.
+Every phase in goal-<topic>.md shows status: complete, or status: awaiting-review with its artifact written. Phase artifacts exist at: <list paths>. Either the /complete-work skill has opened the final PR with the URL in the transcript, or the goal is blocked on a named operator step and that is stated. Or stop after <N> turns.
 ```
 
 Fill in `<topic>`, paths, and `<N>` per goal. Anchor on artifacts and committed state, not on feelings.
@@ -216,7 +243,7 @@ Every `goal-{topic}.md` body MUST include a `## Start command` section containin
 ## Start command
 
 ```
-/goal "All phases in goal-<topic>.md show status: complete. Phase artifacts exist at: <paths>. The /complete-work skill has produced release notes and opened the final PR; the PR URL appeared in the transcript. Or stop after <N> turns."
+/goal "All phases in goal-<topic>.md show status: complete. Phase artifacts exist at: <paths>. The /complete-work skill has opened the final PR; the PR URL appeared in the transcript. Or stop after <N> turns."
 ```
 ````
 
@@ -230,9 +257,9 @@ When the artifact is drafted and the user has reviewed it, the agent's hand-off
 
 ## Lifecycle integration
 
-- `/goal` runs inside an active work session. It does NOT replace `/start-work`. The session is created the normal way, the goal artifact is drafted at the worktree top (including its `## Start command` block), and the user runs that block's `/goal "..."` command to kick off the loop.
-- The goal artifact lives on the session branch and travels with `git push`. It survives across machines and `--resume`.
-- `session.md`'s `## Tasks` should mirror the phase list at coarse grain (one task per phase) so `TodoWrite` shows high-level progress. The main agent updates `## Tasks` at phase transitions via the helper specified by the `task-list-mirroring` rule, in addition to updating `goal-{topic}.md`.
+- `/goal` runs inside started work. It does NOT replace `/start-work`. Session model: the session is created the normal way and the goal artifact is drafted at the worktree top (including its `## Start command` block). Task model: the task is started the normal way and the artifact is drafted into the chat drawer. Either way the user runs the `## Start command` block's `/goal "..."` to kick off the loop.
+- Session model: the goal artifact lives on the session branch and travels with `git push`, surviving across machines and `--resume`. Task model: the drawer is machine-local — push the task branch for the code, and `/promote` the artifact if it must travel.
+- Session model: `session.md`'s `## Tasks` should mirror the phase list at coarse grain (one task per phase) so `TodoWrite` shows high-level progress; the main agent updates `## Tasks` at phase transitions via the helper specified by the `task-list-mirroring` rule, in addition to updating `goal-{topic}.md`. Task model: TodoWrite is the live mirror and there is no durable `## Tasks` — the goal artifact's own `phases:` list is the durable state.
 - `/pause-work` works without special handling. The goal-evaluator state resets on resume per the Claude Code docs; phase state is durable in the artifact.
 - `/complete-work` reads `goal-*.md`, `research-*.md`, and `crossref-*.md` for release-note synthesis and strips them from the branch before the final PR, alongside the existing `design-*.md` and `plan-*.md` handling. When a goal artifact is present, it also runs a pre-flight check that every declared sub-branch (from phases with `integration.strategy: sub-branch`) has been merged into the session branch. Unmerged sub-branches abort completion with a clear list to resolve.
 
@@ -396,7 +423,7 @@ on the session branch.
 ## Start command
 
 ```
-/goal "All 5 phases in goal-evaluate-rate-limiting.md show status: complete. Phase artifacts exist at: research-rate-limiting-strategies.md, crossref-existing-infrastructure.md, design-rate-limiting.md, plan-rate-limiting.md, and the implementation commits land on the session branch (visible in git log). The /complete-work skill has produced release notes and opened the final PR; the PR URL appeared in the transcript. Or stop after 60 turns."
+/goal "All 5 phases in goal-evaluate-rate-limiting.md show status: complete. Phase artifacts exist at: research-rate-limiting-strategies.md, crossref-existing-infrastructure.md, design-rate-limiting.md, plan-rate-limiting.md, and the implementation commits land on the session branch (visible in git log). The /complete-work skill has opened the final PR; the PR URL appeared in the transcript. Or stop after 60 turns."
 ```
 
 This is the frontmatter `completion_condition` flattened to one line. Run it after reviewing the artifact; it flips the goal to `status: active`.

package/template/{.claude → _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,17 @@ 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/`
+- While a task is active, add `workItem: {id}` to the file's frontmatter: `/complete-work` offers a drawer item only to the task that owns it, so the tag keeps this capture out of another task's promotion list
+
+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 → _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
 
@@ -55,9 +59,9 @@ node .claude/scripts/build-workspace-context.mjs --check --root .
 
 The script reports per-artifact status as JSON and uses three exit codes to distinguish what's wrong:
 
-- `0` — all artifacts current and the rendered canonical fits inside `workspace.canonicalBudgetBytes`.
+- `0` — all artifacts current and, when a canonical budget is set, the rendered canonical fits inside `workspace.canonicalBudgetBytes`.
 - `1` — at least one artifact is `missing` or `stale`. Run `--write` to regenerate. `missing` means the artifact does not exist yet; `stale` means it exists but no longer matches its sources (a file was added or deleted, a `description:` changed, a `shared/locked/` file was edited, an `.indexignore` rule was added).
-- `2` — artifacts are current but canonical body bytes exceed the budget after the trim and stub stages have already run. Regeneration cannot fix this; the locked content itself needs triage. Stale wins over over-budget when both apply, so a `1` can hide an over-budget condition until you regen.
+- `2` — artifacts are current but canonical body bytes exceed the budget after the trim and stub stages have already run. Only reachable when a budget is set. Regeneration cannot fix this; the locked content itself needs triage. Stale wins over over-budget when both apply, so a `1` can hide an over-budget condition until you regen.
 
 The JSON payload always includes a `canonical` block summarizing the budget outcome:
 
@@ -79,11 +83,40 @@ The JSON payload always includes a `canonical` block summarizing the budget outc
 
 `selectionStatus` walks `ok` → `trimmed` → `stubbed` → `over-budget` as the script gives up progressively more reference content trying to fit the budget. `trimmedFiles` lists reference files whose `<!-- canonical:trim --> ... <!-- canonical:end-trim -->` spans were dropped; `stubbedFiles` lists reference files whose entire body was replaced with a one-line breadcrumb. `overBy` is present only when `selectionStatus === 'over-budget'` and reports the bytes still over after stubbing.
 
-Audit mode reports the status verbatim. When `selectionStatus` is `over-budget`, audit emits the budget violation and recommends `/maintenance cleanup` to triage — regeneration will not resolve it. Cleanup mode runs `--write` when `missing` or `stale`, re-checks, and then enters the budget triage flow described in cleanup step 9 if the post-regen check still reports `over-budget`.
+The canonical budget is opt-in. `workspace.canonicalBudgetBytes` is off unless workspace.json sets it — absent or `null` means no budget. When off, `canonical.md` ships every locked file in full, the `canonical` block reports `"budget": null` with `selectionStatus: "ok"`, exit `2` cannot occur, and the audit reports one informational line in place of the budget OK/warning line:
+
+```
+• Canonical budget: off (alwaysLoadedBudgetBytes covers the total)
+```
+
+No warning accompanies it. To turn the budget back on, set a byte count in workspace.json (e.g. `"canonicalBudgetBytes": 40960`) and regenerate.
+
+Audit mode reports the status verbatim. When a budget is set and `selectionStatus` is `over-budget`, audit emits the budget violation and recommends `/maintenance cleanup` to triage — regeneration will not resolve it. Cleanup mode runs `--write` when `missing` or `stale`, re-checks, and then enters the budget triage flow described in cleanup step 11 if the post-regen check still reports `over-budget`.
 
 While the indexes are 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
+### 6. Always-loaded context budget
+
+Everything Claude reads at launch — CLAUDE.md, its @-imports, and the active rules — is measured against `workspace.alwaysLoadedBudgetBytes`:
+
+```bash
+node .claude/scripts/context-footprint.mjs --root .
+```
+
+Rules carrying `paths:` frontmatter are conditional (they load only when a matching file is touched); the script lists them in a separate conditional section and excludes them from the total. With no `alwaysLoadedBudgetBytes` in workspace.json there is no budget and this check passes trivially.
+
+Within budget → an OK line: `✓ Always-loaded context: 43 KB / 64 KB`. Over budget → a Warning (the workspace still functions; this is drift, not breakage) naming the top contributors and the fixes:
+
+```
+⚠ Always-loaded context exceeds budget: 78 KB / 64 KB. Top contributors:
+  .claude/rules/git-conventions.md (12 KB), CLAUDE.md (9 KB),
+  .claude/rules/workspace-structure.md (8 KB). Scope situational rules with
+  paths: frontmatter, or move reference content to shared/.
+```
+
+The script itself exits `1` when over budget; `/maintenance` reports that as the warning above, not as a failed run.
+
+### 7. Template freshness
 
 Compare the workspace's pinned template version against the latest published on npm.
 
@@ -108,7 +141,7 @@ Report one of:
 
 Active recommendations. Flags problems and suggests fixes, but asks before acting.
 
-### 7. Component age check
+### 8. 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)
@@ -122,22 +155,25 @@ Files without an `updated:` field are skipped — the check is opt-in and activa
 
 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
+### 9. 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
 
-### 9. Context reconciliation
+### 10. 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
 
-### 10. Canonical budget triage
+### 11. Canonical budget triage
 
-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.
+This step runs only when a canonical budget is set (`workspace.canonicalBudgetBytes` holds a number) and the post-regen `--check` from the cleanup regen pass (Flow step 9) still reports `selectionStatus: 'over-budget'`. With the budget off — absent or `null` in workspace.json — `--check` can never report over-budget, so this step is unreachable. Skip it too if the regular regen pass cleared the budget, or if `--check` was already `ok`, `trimmed`, or `stubbed` after that pass.
 
 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.
 
@@ -182,7 +218,7 @@ 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.
 
-### 11. Forge configuration
+### 12. Forge configuration
 
 Read `workspace.json`. If `workspace.tracker?.type === 'github-issues'` and `workspace.forge` is unset, emit a notice (not an error):
 
@@ -194,8 +230,9 @@ Read `workspace.json`. If `workspace.tracker?.type === 'github-issues'` and `wor
 
 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.
+### 13. Health metrics
+- Canonical budget — read from the same `--check` invocation as step 5. When a budget is set, 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. When off, report the step 5 one-liner: `• Canonical budget: off (alwaysLoadedBudgetBytes covers the total)`.
+- Always-loaded context — read from the same `context-footprint.mjs` invocation as audit step 6, reported the same way (`current / budget` bytes); over-budget is already surfaced as a warning there.
 - Number of ephemeral files — flag if accumulating without resolution
 - Session log stats (if `workspace-scratchpad/session-log.jsonl` exists):
   - Sessions without capture
@@ -224,11 +261,12 @@ Cleanup suggestions (2):
   ⊕ migration-recipes.md still says "/sync handles dogfood" but
     /sync was replaced by /sync-work — update?
 
-OK (5):
+OK (6):
   ✓ All CLAUDE.md skill references valid
   ✓ Workspace structure matches rule
   ✓ workspace.json repos all present
   ✓ Canonical: 17 KB / 40 KB (full)
+  ✓ Always-loaded context: 43 KB / 64 KB
   ✓ Template is up to date (v0.14.0)
 ```
 
@@ -239,10 +277,11 @@ OK (5):
 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. 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 10.
-9. Compile and present findings grouped by severity
+6. Run `node .claude/scripts/build-workspace-context.mjs --check --root .` — capture status. Exit `0` = clean (and within budget when one is set), `1` = artifact missing or stale, `2` = artifacts current but canonical body over budget — only possible with a budget set. The `canonical` block in the JSON output drives both the audit budget line and the cleanup triage decision; `"budget": null` means the canonical budget is off.
+7. Run `node .claude/scripts/context-footprint.mjs --root .` — capture the total and the `BUDGET` line. Exit `0` = within budget or no budget set; exit `1` = over budget, reported as a warning with the top contributors (audit step 6).
+8. Read session-log.jsonl if it exists
+9. 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 11.
+10. Compile and present findings grouped by severity
 
 ## Notes
 - Audit mode is always read-only — never modifies files

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 → _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: