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

package/template/{.claude → _claude}/skills/context-placement/SKILL.md

@@ -70,7 +70,7 @@ does not need to be in context while you are editing documentation.
 ---
 paths:
   - ".claude/scripts/**/*.mjs"
-  - "repos/*/template/.claude/scripts/**/*.mjs"
+  - "repos/*/template/_claude/scripts/**/*.mjs"
 ---
 ```
 
@@ -189,11 +189,14 @@ Gitignored files (anything matching `local-only-*`) are excluded automatically,
 `workspace-context/.indexignore` adds path-prefix excludes for tracked files that should
 not appear in the shared index.
 
-When `canonical.md` exceeds `workspace.canonicalBudgetBytes` (default 40960), the builder
-honours per-file `priority` and section-level `<!-- canonical:trim --> ... <!-- canonical:end-trim -->`
+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 and offers triage when
-over.
+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 → _claude}/skills/goal-driven-work/SKILL.md

@@ -17,7 +17,7 @@ the work at hand. This skill covers everything after that decision.
 - 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.
-- 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.
+- 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
 

package/template/{.claude → _claude}/skills/handoff/SKILL.md

@@ -30,6 +30,7 @@ Under the task model — `workspace.sessionModel` is `"task"` in `workspace.json
 
 - 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):
 

package/template/{.claude → _claude}/skills/maintenance/SKILL.md

@@ -59,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:
 
@@ -83,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.
 
@@ -112,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)
@@ -126,7 +155,7 @@ 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
@@ -136,15 +165,15 @@ When stale candidates are found, surface them as warnings in the output format a
 - 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.
 
@@ -189,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):
 
@@ -201,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
@@ -231,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)
 ```
 
@@ -246,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 → _claude}/skills/release/SKILL.md

@@ -52,7 +52,7 @@ Push the branch and open a PR through the forge adapter — per-repo `createForg
 
 **Step 5: Tag and publish**
 
-Pull the merge, tag it, push the tag, and publish the forge release:
+Pull the merge, tag it, and push the tag:
 
 ```bash
 git -C repos/{repo} pull --ff-only
@@ -60,11 +60,15 @@ git -C repos/{repo} tag v{version}
 git -C repos/{repo} push origin v{version}
 ```
 
+Who creates the release depends on the repo. If `.github/workflows/publish.yml` exists and itself creates the release (it contains `gh release create`, `softprops/action-gh-release`, or `actions/create-release`), the workflow owns the release — do not call `releaseCreate`; racing it duplicates the release or fails. Instead 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 — then confirm the release exists with `forge.releaseView({ tag: 'v{version}', repo })`.
+
+Otherwise the skill creates the release itself:
+
 ```js
 await forge.releaseCreate({ tag: 'v{version}', repo, generateNotes: true });
 ```
 
-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.
+If a `publish.yml` without release creation exists, still find and watch its run the same way.
 
 **Step 6: Tear down and report**
 

package/template/{.claude → _claude}/skills/start-work/SKILL.md

@@ -21,7 +21,7 @@ New work as a task: one tracker issue, one branch, one worktree per repo the wor
 
 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:
+1. **Identify or create the tracker issue and claim it.** If the invocation's arguments already name an issue — `gh:N`, `#N`, or an issue URL — normalize it to the adapter's id (`#42` and a `.../issues/42` URL both mean `gh:42`), fetch it with `tracker.getIssue(id)`, claim it when it is not yet assigned to you (with the same `ALREADY_ASSIGNED` handling as the fallback pick below), and skip the candidate list entirely. Otherwise, list the candidates — the same adapter calls as Flow: Blank steps 3–6:
 
    ```javascript
    import { createTracker } from './.claude/scripts/trackers/interface.mjs';
@@ -60,7 +60,7 @@ If `workspace.tracker` is absent, say tracking is off and skip step 1 — but st
    ```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.
+   `{chat}` is the name from the `Chat record:` line the SessionStart hook injected into this conversation. If there is no such line, run `node .claude/scripts/chat-record.mjs --whoami --root .` first — compaction can drop the hook line, and this recovers the name by matching the chat's session id. When that too prints nothing, 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.
 

package/template/workspace.json.tmpl

@@ -6,7 +6,7 @@
     "scratchpadDir": "workspace-scratchpad",
     "workSessionsDir": "work-sessions",
     "workspaceContextDir": "workspace-context",
-    "canonicalBudgetBytes": 40960,
+    "alwaysLoadedBudgetBytes": 65536,
     "subagentContextMaxBytes": 32768,
     "subagentInlineMaxBytes": 8192,
     "greeting": "Welcome back to {{project-name}}.",