@ulysses-ai/create-workspace 0.14.0-beta.3 → 0.15.0-beta.1

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

@@ -17,13 +17,13 @@ Keep the workspace healthy. Combines integrity auditing with active cleanup reco
 Read-only integrity checks. Reports problems but never modifies files.
 
 ### 1. Cross-reference consistency
-Scan all shared-context files against each other:
+Scan all workspace-context files against each other:
 - **Stale references** — file A mentions "2 mandatory rules" but there are now 4
 - **Path references** — file A mentions a file that was moved or deleted
 - **Contradictions** — file A says "user-scoped is default" but file B says "root is default"
 
 ### 2. Frontmatter integrity
-For each shared-context `.md` file and each `work-sessions/*/workspace/session.md`:
+For each workspace-context `.md` file and each `work-sessions/*/workspace/session.md`:
 - Valid frontmatter? (state, lifecycle, type, topic, author, updated; plus name/status/branch/repos for session trackers)
 - `branch` field references a branch that still exists?
 - `repo`/`repos` field references repos that exist in workspace.json?
@@ -45,23 +45,43 @@ For each shared-context `.md` file and each `work-sessions/*/workspace/session.m
 - Workspace repo on expected branch?
 - Orphan worktree records in project repos — run `git -C repos/{repo} worktree list` for each repo and flag any `prunable` markers. These usually come from a workspace-first teardown (the unsafe order) leaving stale admin records behind. Suggest `git worktree prune` on the affected repo.
 
-### 5. Shared-context index integrity
+### 5. Workspace-context auto-file integrity
 
-`shared-context/index.md` is auto-generated from frontmatter. Run the check:
+`workspace-context/index.md`, `workspace-context/canonical.md`, and each `workspace-context/team-member/{user}/index.md` are auto-generated from frontmatter and locked content. Run the check:
 
 ```bash
-node .claude/scripts/build-shared-context-index.mjs --check --root .
+node .claude/scripts/build-workspace-context.mjs --check --root .
 ```
 
-Three failure modes (script exits 1 with a JSON status):
+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`.
+- `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.
+
+The JSON payload always includes a `canonical` block summarizing the budget outcome:
+
+```json
+{
+  "status": "current",
+  "missing": [],
+  "stale": [],
+  "canonical": {
+    "budget": 40960,
+    "current": 47802,
+    "overBy": 6842,
+    "selectionStatus": "stubbed",
+    "trimmedFiles": ["post-release-discipline"],
+    "stubbedFiles": ["project-status", "release-flow-recipes"]
+  }
+}
+```
 
-- `missing` — `shared-context/` exists but `index.md` does not. Run `--write` to create.
-- `stale` — `index.md` exists but its entries no longer match the filesystem. Causes: a file was added or deleted, a `description:` was changed, a `.indexignore` rule was added. Run `--write` to regenerate.
-- (no failure) — `current` with the entry count.
+`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. Cleanup mode runs `--write` if stale or missing, then re-checks.
+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`.
 
-While the index is being read, also flag entries with weak fallbacks: filename-slug-only descriptions (e.g., "project status" with no period) usually indicate the underlying file is missing a `description:` or has no usable opening sentence. Suggest adding `description:` to those source files — the index will pick it up on the next regeneration.
+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
 
@@ -96,13 +116,60 @@ Active recommendations. Flags problems and suggests fixes, but asks before actin
 - Handoffs referencing deleted branches — suggest resolve or remove
 
 ### 8. Context reconciliation
-- Read recent shared-context writes (last session or last N files by updated date)
-- For each, scan other shared-context files for references that are now stale
+- 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. Health metrics
-- Size of `shared-context/locked/` relative to the active model's context window — flag if over 5% (yellow) or 15% (red). Absolute byte count is a weak proxy; contradictions, stale references, and duplicated coverage across files matter more than total size.
+### 9. 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.
+
+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.
+
+Inputs to gather before the first menu render:
+
+- The `canonical` block from the `--check` JSON: `budget`, `current`, `overBy`, `selectionStatus`, `trimmedFiles`, `stubbedFiles`.
+- Each `workspace-context/shared/locked/*.md` file with its on-disk byte size and frontmatter `priority`.
+- Per file, a list of `## Section heading` spans with byte sizes — use a simple `^## ` boundary scan, not a full markdown AST. Locked files are short and shallow enough that the naive split is sufficient; if a file ever has nested headings that confuse it, fall back to opening the file in an editor (option `[c]` below).
+
+Render the state and present this menu:
+
+```
+Canonical budget: 40960 bytes. Current: 47802 bytes. Over by 6842 bytes.
+
+Locked files by size:
+  1. project-status.md           (priority: reference, 18432 bytes)  ← stubbed in canonical
+  2. post-release-discipline.md  (priority: critical, 12104 bytes)
+  3. naming-conventions.md       (priority: critical,  4218 bytes)
+  4. cross-platform.md           (priority: critical,   702 bytes)
+  5. product-bias-risk.md        (priority: critical,  1346 bytes)
+
+Largest sections in priority:critical files (eligible for promotion to reference or trim markers):
+  - project-status.md > "What's Built" (5120 bytes)
+  - post-release-discipline.md > "Backstop: branch protection" (3892 bytes)
+  - post-release-discipline.md > "Why" (2104 bytes)
+
+Triage (one at a time):
+  [a] Demote a file from critical to reference
+  [b] Add canonical:trim markers around a specific section
+  [c] Open a locked file in the editor for manual edits
+  [d] Skip — accept the over-budget warning
+  [q] Done
+```
+
+For each chosen action:
+
+- **`[a]` Demote.** Ask which file. Rewrite its frontmatter `priority: critical` → `priority: reference`. No body changes. Re-run `--check`, re-render the menu with the new state.
+- **`[b]` Add trim markers.** Ask which `file > section`. Wrap the section by inserting `<!-- canonical:trim -->` on its own line just before the section heading and `<!-- canonical:end-trim -->` on its own line just after the section's last line (the line before the next `^## ` heading or EOF). Re-run `--check`, re-render.
+- **`[c]` Open in editor.** Print the file path and pause. The user edits manually, returns, and confirms — then re-run `--check` and re-render.
+- **`[d]` Skip.** Accept the over-budget state for this run; record the acknowledgement in the run summary. Audit will continue to surface the warning on subsequent runs.
+- **`[q]` Done.** Exit triage. Report the final `--check` status as the run result.
+
+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
+- 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):
   - Sessions without capture
@@ -115,13 +182,14 @@ Active recommendations. Flags problems and suggests fixes, but asks before actin
 /maintenance results:
 
 Issues (3):
-  ✗ shared-context/alice/old-handoff.md references branch feature/old
+  ✗ workspace-context/team-member/alice/old-handoff.md references branch feature/old
     but that branch was deleted
   ✗ 2 inflight files exist but no active work session (orphaned?)
-  ✗ Locked context is 18% of model context window (red threshold: 15%)
+  ✗ Canonical exceeds budget: 47 KB / 40 KB. 2 reference files were stubbed;
+    canonical is still 6.8 KB over. Run /maintenance cleanup to triage.
 
 Warnings (2):
-  ⚠ shared-context/alice/workspace-analytics.md not updated in 8 days
+  ⚠ workspace-context/team-member/alice/workspace-analytics.md not updated in 8 days
   ⚠ Worktree work-sessions/old-feature/workspace has no commits in 5 days
 
 Cleanup suggestions (2):
@@ -134,20 +202,20 @@ OK (5):
   ✓ All CLAUDE.md skill references valid
   ✓ Workspace structure matches rule
   ✓ workspace.json repos all present
-  ✓ No frontmatter errors
+  ✓ Canonical: 17 KB / 40 KB (full)
   ✓ Template is up to date (v0.14.0)
 ```
 
 ## Flow
 
-1. Scan shared-context/ recursively — read all `.md` files and their frontmatter
+1. Scan workspace-context/ recursively — read all `.md` files and their frontmatter
 2. Read CLAUDE.md — extract skill and rule references
 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-shared-context-index.mjs --check --root .` — capture status
+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 shared-context index if stale; compare files pairwise for overlap; scan for stale cross-references
+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.
 9. Compile and present findings grouped by severity
 
 ## Notes

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

@@ -113,7 +113,7 @@ If PRs already exist, update them to draft status if needed.
 No worktree cleanup — the session is meant to be resumed. The `work-sessions/{session-name}/` folder stays intact.
 
 ## Notes
-- Pause writes ONLY to `work-sessions/{session-name}/workspace/session.md` — never to ongoing or root shared-context
+- Pause writes ONLY to `work-sessions/{session-name}/workspace/session.md` — never to ongoing or root workspace-context
 - The session tracker's frontmatter stays in the session folder — it's the resume mechanism
 - Draft PRs signal work-in-progress without implying merge readiness
 - Auto-committing the pause capture is a workflow artifact — this intentionally bypasses normal commit conventions

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

@@ -1,17 +1,17 @@
 ---
 name: promote
-description: Move personal auto-memory or local-only files into shared context. Use when you've discovered something valuable that the team should know.
+description: Move personal auto-memory or local-only files into workspace-context. Use when you've discovered something valuable that the team should know.
 ---
 
 # Promote
 
-Promote personal knowledge into shared context. Assess all candidates, recommend actions, let the user decide with coded references.
+Promote personal knowledge into workspace-context. Assess all candidates, recommend actions, let the user decide with coded references.
 
 ## Sources
 
 This skill can promote from three sources:
 1. **Auto-memory (AM)** — files in `~/.claude/projects/*/memory/`
-2. **Local-only context (LOC)** — `shared-context/local-only-*.md`
+2. **Local-only context (LOC)** — `workspace-context/team-member/{user}/local-only-*.md` (and any other `local-only-*.md` under `workspace-context/`)
 3. **Local-only rules (LOR)** — `.claude/rules/local-only-*.md`
 
 ## Flow
@@ -47,9 +47,19 @@ The user responds using codes:
 **Step 3: Execute decisions**
 
 For each **promote** action:
-- Ask: "Team-visible, user-scoped (default), or locked?"
-- Copy to destination, set `type: promoted` in frontmatter
-- Remove the local-only original
+- Ask: "Team-visible (`workspace-context/shared/`), user-scoped (default, `workspace-context/team-member/{user}/`), or locked (`workspace-context/shared/locked/`)?"
+- Use `capture-context.mjs --update` to write to the destination with the right frontmatter:
+  ```bash
+  cat {source-file} | node .claude/scripts/capture-context.mjs \
+    --type {braindump|handoff|research} \
+    --topic {kebab-name} \
+    --scope {team-member|shared} \
+    [--user {workspace.user}] \
+    --update
+  ```
+  When promoting *to locked*, write directly to `workspace-context/shared/locked/{bare-name}.md` instead — locked files use bare names (location signals the type) and don't take a prefix. Strip the `braindump_/handoff_/research_` prefix when locking.
+- Set `type: promoted` in the destination frontmatter (the helper writes the standard fields; edit `type` afterward, or have the body's frontmatter override).
+- Remove the `local-only-` original.
 - Commit individually: `git commit -m "promote: {name}"`
 
 For each **drop** action:
@@ -65,13 +75,13 @@ For each **keep** action:
 
 ## Rewrite on Promote
 
-Auto-memory files are terse notes written for Claude's internal use. When promoting to shared context, rewrite into proper format with:
+Auto-memory files are terse notes written for Claude's internal use. When promoting to workspace-context, rewrite into proper format with:
 - Frontmatter (state, lifecycle, type: promoted, topic, author, updated)
 - Sections with enough context to be useful to someone who wasn't in the original session
 - Local-only files may already be well-formatted — copy as-is if so, just update frontmatter
 
 ## Notes
-- Promotion is one-way: shared context should not be demoted back to local-only
+- Promotion is one-way: workspace-context should not be demoted back to local-only
 - Use this when you discover a pattern, convention, or decision that would benefit the team
 - The coded table makes bulk decisions fast — no need to type full filenames
 - Assess everything upfront so the user sees the full picture before deciding

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

@@ -1,11 +1,11 @@
 ---
 name: release
-description: Prepend a new CHANGELOG.md entry per project repo by synthesizing unreleased branch notes. Deletes consumed branch notes and synthesizes workspace shared-context into locked entries. Use at release time.
+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.
 ---
 
 # 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 shared-context into locked team knowledge.
+Synthesize unreleased branch notes (in the **workspace** repo) into a concise, user-facing entry at the top of each project repo's `CHANGELOG.md`. Delete the consumed branch notes from the workspace. Bump the project repo's `package.json` version. In parallel, promote resolved workspace-context into canonical (locked) team knowledge.
 
 ## Why this shape
 
@@ -104,28 +104,32 @@ git commit -m "release: consume {repo} branch notes for v{version}"
 Workspace and project repos have separate commits — they are separate git histories.
 
 **Step 8: Consume project-scoped specs**
-Project-scoped specs and plans in `shared-context/{user}/` (ongoing) that are fully covered by this release:
+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 shared context**
-Process ephemeral shared-context entries:
+**Step 9: Synthesize workspace-context for canonical promotion**
+Process ephemeral workspace-context entries:
 
-1. List all ephemeral entries with `lifecycle: resolved`
+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 `{user}/` ongoing or keep as root ephemeral
+   - 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`
-   - Move to `shared-context/locked/`
+   - 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. Commit:
+4. Regenerate auto-files so `canonical.md` and `index.md` reflect the new locked content:
    ```bash
-   git add shared-context/
-   git commit -m "release: synthesize shared context for v{version}"
+   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**
@@ -137,6 +141,9 @@ Process ephemeral shared-context entries:
 - Branch notes live in the WORKSPACE at `release-notes/unreleased/{repo}/`. `/complete-work` writes them; `/release` consumes and deletes them. They never reach project repos.
 - Versions are bumped here, not in `/complete-work`. This keeps the version semantics aligned with what actually shipped (accumulated changes since last release).
 - The public repo stays lean. Detailed per-branch retrospection exists in workspace git history (the consumed-notes commit) but is not surfaced as standalone files in either repo.
-- Context synthesis happens in the WORKSPACE repo — Step 7c (consumed-notes) and Step 9 (shared-context synthesis) are separate workspace commits.
+- 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.

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

@@ -249,7 +249,7 @@ If not: ask "Ready to start implementing, or want to brainstorm first?"
 
 When /start-work is called after work has already begun:
 
-1. Detect uncommitted changes in `repos/` or `shared-context/`
+1. Detect uncommitted changes in `repos/` or `workspace-context/`
 2. "It looks like you've already been working. Let me formalize this."
 3. If changes are on a default branch: stash → create session → pop stash
 4. If changes are already on a feature branch: create workspace worktree and nest the existing project worktree(s) under it, or create a fresh session if the work is small enough to re-apply

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

@@ -68,7 +68,7 @@ Ask the user:
 
 This determines whether documentation extraction is part of the plan.
 
-**Important:** If the user indicates a source, ask: "Has any content already been extracted from this source? (e.g., rules or context files already pulled down from Notion)" Check `shared-context/` and `.claude/rules/` for files that appear to contain extracted content. If content already exists from a source, mark it as "already extracted" and skip re-fetching unless the user explicitly wants a refresh.
+**Important:** If the user indicates a source, ask: "Has any content already been extracted from this source? (e.g., rules or context files already pulled down from Notion)" Check `workspace-context/` and `.claude/rules/` for files that appear to contain extracted content. If content already exists from a source, mark it as "already extracted" and skip re-fetching unless the user explicitly wants a refresh.
 
 ### Step 4: Present the plan
 
@@ -134,7 +134,7 @@ List all `.md.skip` files in `.claude/rules/`:
 For each documentation source identified in Step 3:
 
 **Before fetching from any source, check if content was already extracted:**
-- Scan `shared-context/` and `.claude/rules/` for files that reference the source (e.g., files mentioning Notion page IDs, Confluence URLs, etc.)
+- Scan `workspace-context/` and `.claude/rules/` for files that reference the source (e.g., files mentioning Notion page IDs, Confluence URLs, etc.)
 - If found: "Content from {source} appears to already be in {files}. Skip re-fetching? [Y/n]"
 - If the user confirms skip: move on to the next source
 - If the user wants a refresh: proceed with extraction but note which files will be updated
@@ -145,7 +145,7 @@ For sources that need extraction:
 - **Track access failures** — if a source is unreachable, note it but don't stop
 - For rules/conventions found: write to `.claude/rules/{rule-name}.md`
 - For project context/decisions: stage for Step 10 (locked knowledge)
-- For handoffs/active work: write to `shared-context/{user}/` as ephemeral
+- For handoffs/active work: write to `workspace-context/team-member/{user}/` as ephemeral
 
 **Commit:** `git commit -m "feat: extract rules and context from documentation sources"`
 
@@ -181,7 +181,7 @@ Write `workspace-scratchpad/chat-history-manifest.json`:
 3. Update the manifest entry status to "processed"
 4. Synthesize findings into shared context:
    - Decisions and architecture → stage for locked context (Step 10)
-   - Work-in-progress context → `shared-context/{user}/` as ephemeral handoffs
+   - Work-in-progress context → `workspace-context/team-member/{user}/` as ephemeral handoffs
    - Patterns and conventions → candidate rules for `.claude/rules/`
 
 Present a summary: "Found {N} prior sessions. Extracted {M} decisions, {K} handoffs, {P} convention candidates."
@@ -199,7 +199,7 @@ rm -f workspace-scratchpad/chat-history-manifest.json
 
 Read CLAUDE.md.bak for non-documentation content worth keeping:
 - Local coding conventions → `.claude/rules/` (new rule files)
-- Project-specific notes → `shared-context/locked/` or `shared-context/{user}/`
+- Project-specific notes → `workspace-context/shared/locked/` or `workspace-context/team-member/{user}/`
 - Repo paths → verify they match workspace.json
 
 **Commit:** `git commit -m "feat: preserve local preferences as rules and context"`
@@ -207,7 +207,7 @@ Read CLAUDE.md.bak for non-documentation content worth keeping:
 ### Step 10: Create locked team knowledge
 
 Combine content from Steps 7, 8, 9, and existing auto-memory into locked context:
-- For each piece of stable knowledge: write to `shared-context/locked/{topic}.md`
+- For each piece of stable knowledge: write to `workspace-context/shared/locked/{topic}.md`
 - Keep locked context lean — target <10KB total
 - One topic per file, proper frontmatter
 - Only lock what the team needs every session. Everything else is ephemeral.
@@ -269,7 +269,7 @@ Save to `.claude/settings.local.json`:
 
 ### Step 14: Clean root directory
 
-The workspace root should contain ONLY template structure: CLAUDE.md, workspace.json, .gitignore, and the standard directories (`.claude/`, `shared-context/`). The `repos/`, `work-sessions/`, and `workspace-scratchpad/` directories are lazy-created the first time something writes to them — they won't exist yet unless a repo has already been cloned.
+The workspace root should contain ONLY template structure: CLAUDE.md, workspace.json, .gitignore, and the standard directories (`.claude/`, `workspace-context/`). The `repos/`, `work-sessions/`, and `workspace-scratchpad/` directories are lazy-created the first time something writes to them — they won't exist yet unless a repo has already been cloned.
 
 Move everything else to `workspace-scratchpad/unmigrated/`:
 
@@ -299,8 +299,8 @@ Report: "Moved {N} items to workspace-scratchpad/unmigrated/: {list}."
 
 Read EVERY created and activated file:
 - Every `.claude/rules/*.md` (not .skip)
-- Every `shared-context/locked/*.md`
-- Every `shared-context/{user}/*.md`
+- Every `workspace-context/shared/locked/*.md`
+- Every `workspace-context/team-member/{user}/*.md`
 
 Check for:
 - References to removed services or files
@@ -333,8 +333,8 @@ git remote -v
   ```bash
   git rebase origin/main
   ```
-  If conflicts arise (e.g., shared-context differs between your init and what's already committed), STOP and present them. These are legitimate merge decisions — your extracted content vs what your teammate committed. Help the user resolve each conflict:
-  - For shared-context files: the remote version likely has the teammate's extractions. Merge both perspectives or keep the more complete version.
+  If conflicts arise (e.g., workspace-context differs between your init and what's already committed), STOP and present them. These are legitimate merge decisions — your extracted content vs what your teammate committed. Help the user resolve each conflict:
+  - For workspace-context files: the remote version likely has the teammate's extractions. Merge both perspectives or keep the more complete version.
   - For rules: if both sides activated different optional rules, keep both.
   - For CLAUDE.md: use the remote version (it's the established one), add any local customizations the user wants.
 
@@ -408,7 +408,7 @@ This session is done. Start a fresh Claude Code session and run /start-work to b
 - **Don't suggest starting work at the end.** Tell the user to restart Claude Code and run /start-work in a fresh session.
 - The verification step (Step 16) is mandatory — read every file, check thoroughly.
 - **Build manifests before long operations.** Chat history scanning (Step 8) and worktree formalization (Step 11) can be interrupted by auto-compaction. Write a manifest to `workspace-scratchpad/` before starting so progress survives.
-- **Never re-fetch content that already exists.** Always check shared-context and rules for existing extractions before accessing external sources.
+- **Never re-fetch content that already exists.** Always check workspace-context and rules for existing extractions before accessing external sources.
 - This skill is idempotent — safe to run if interrupted and restarted.
 
 ## Notes

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

@@ -77,7 +77,7 @@ Read `toVersion` from `.workspace-update/.manifest.json` and update `templateVer
 
 ### Step 4a: Run idempotent migrators
 
-The payload may include migrator scripts at `.workspace-update/.claude/scripts/migrate-*.mjs` that bring older workspaces forward in shape. They are idempotent — safe to re-run on already-migrated workspaces. Run each one and surface its action in the upgrade summary.
+The payload may include migrator scripts at `.workspace-update/.claude/scripts/migrate-*.mjs` that bring older workspaces forward in shape. They are idempotent — safe to re-run on already-migrated workspaces. Run each one in document order and surface its action in the upgrade summary.
 
 ```bash
 node .workspace-update/.claude/scripts/migrate-claude-md-freshness-include.mjs
@@ -89,6 +89,12 @@ Output is JSON: `{"action":"appended"|"unchanged"|"skipped"}`.
 - `unchanged` — the line was already present.
 - `skipped` — no `CLAUDE.md` exists at the workspace root (rare; surface to the user).
 
+```bash
+node .workspace-update/.claude/scripts/migrate-canonical-priority.mjs --root .
+```
+
+Output is JSON: `{"status":"applied"|"noop","files":[...]}`. Back-fills `priority: critical` on every `workspace-context/shared/locked/*.md` that lacks the field, preserving today's full-load behavior until the user explicitly demotes a file. Idempotent — safe to re-run on already-migrated workspaces.
+
 Add other migrators here as the template ships them.
 
 ### Step 5: Post-update verification

package/template/CLAUDE.md.tmpl

@@ -7,14 +7,15 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - `/start-work` to create or resume a work session
 - Each session is a self-contained folder at `work-sessions/{name}/` containing the worktree, nested project worktrees, and the session tracker
 - From root: only `local-only-*` and `workspace-scratchpad/` are writable
-- Shared memory lives in `shared-context/`
+- Team knowledge lives in `workspace-context/`
 
 ## Workspace Config
 @workspace.json
 @local-only-template-freshness.md
 
-## Team Knowledge (always loaded)
-@shared-context/locked/
+## Team Knowledge
+@workspace-context/canonical.md
+@workspace-context/index.md
 
 ## Skills
 - `/workspace-init` — first-time workspace setup (clone repos, install template, activate rules)

package/template/_gitignore

@@ -15,6 +15,7 @@ workspace-scratchpad/
 # Personal overrides
 .claude/settings.local.json
 .claude/.active-session.json
+CLAUDE.local.md
 
 # Local-only convention — machine-local state, any depth
 local-only-*

package/template/workspace.json.tmpl

@@ -5,8 +5,9 @@
     "versionCheck": { "ambient": true },
     "scratchpadDir": "workspace-scratchpad",
     "workSessionsDir": "work-sessions",
-    "sharedContextDir": "shared-context",
-    "releaseNotesDir": "release-notes",
+    "workspaceContextDir": "workspace-context",
+    "releaseNotesDir": "workspace-context/release-notes",
+    "canonicalBudgetBytes": 40960,
     "subagentContextMaxBytes": 10240,
     "greeting": "Welcome back to {{project-name}}.",
     "releaseMode": "per-repo",

package/template/.claude/hooks/_bash-output-advisory.test.mjs

@@ -1,88 +0,0 @@
-#!/usr/bin/env node
-// Unit tests for bash-output-advisory.mjs pattern detection.
-// Run: node .claude/hooks/_bash-output-advisory.test.mjs
-import { detectNoisyPattern } from './bash-output-advisory.mjs';
-
-let failed = 0;
-let passed = 0;
-
-function shouldWarn(command, label) {
-  const result = detectNoisyPattern(command);
-  if (result) {
-    passed++;
-  } else {
-    failed++;
-    console.error(`  FAIL: ${label}\n    command: ${command}\n    expected an advisory, got null`);
-  }
-}
-
-function shouldNotWarn(command, label) {
-  const result = detectNoisyPattern(command);
-  if (!result) {
-    passed++;
-  } else {
-    failed++;
-    console.error(`  FAIL: ${label}\n    command: ${command}\n    expected null, got: ${result}`);
-  }
-}
-
-// === Test runners ===
-shouldWarn('npm test', 'bare npm test');
-shouldWarn('npm run test', 'bare npm run test');
-shouldWarn('yarn test', 'bare yarn test');
-shouldWarn('pnpm test', 'bare pnpm test');
-shouldWarn('bun test', 'bare bun test');
-shouldWarn('cargo test', 'bare cargo test');
-shouldWarn('npm test --coverage', 'npm test with non-scoping flag');
-
-shouldNotWarn('npm test path/to/file.test.mjs', 'npm test with file path');
-shouldNotWarn('npm test src/', 'npm test with directory');
-shouldNotWarn('npm test -- --grep auth', 'npm test with -- args');
-shouldNotWarn('npm test myFile.test.js', 'npm test with bare filename');
-shouldNotWarn('npm test | grep FAIL', 'npm test piped to grep');
-shouldNotWarn('npm test | head -50', 'npm test piped to head');
-shouldNotWarn('cargo test auth_module', 'cargo test with module filter');
-
-// === grep -r ===
-shouldWarn('grep -r "pattern" .', 'bare grep -r');
-shouldWarn('grep --recursive "pattern" src/', 'grep --recursive long form');
-shouldWarn('grep -rn "TODO" .', 'grep -rn (recursive + line numbers)');
-
-shouldNotWarn('grep -r --include="*.js" pattern .', 'grep -r with --include');
-shouldNotWarn('grep -r pattern . --exclude="*.log"', 'grep -r with --exclude');
-shouldNotWarn('grep "pattern" file.txt', 'non-recursive grep');
-
-// === find on broad anchors ===
-shouldWarn('find /', 'find on root');
-shouldWarn('find ~', 'find on home tilde');
-shouldWarn('find $HOME', 'find on $HOME');
-
-shouldNotWarn('find / -name "*.log"', 'find / with -name');
-shouldNotWarn('find ~ -path "*node_modules*" -prune', 'find ~ with -path');
-shouldNotWarn('find . -type f', 'find on cwd');
-shouldNotWarn('find ./src -name "*.ts"', 'find on relative subdir');
-
-// === cat on log-shaped files ===
-shouldWarn('cat server.log', 'cat .log file');
-shouldWarn('cat events.jsonl', 'cat .jsonl file');
-shouldWarn('cat trace.ndjson', 'cat .ndjson file');
-shouldWarn('cat path/to/big.log', 'cat .log in subdir');
-
-shouldNotWarn('cat package.json', 'cat package.json');
-shouldNotWarn('cat README.md', 'cat README');
-shouldNotWarn('cat src/index.ts', 'cat source file');
-shouldNotWarn('cat server.log | tail -50', 'cat .log piped to tail');
-
-// === redirected output (always allowed) ===
-shouldNotWarn('npm test > /tmp/test-output.txt', 'npm test redirected to file');
-shouldNotWarn('grep -r foo . > out.txt', 'grep -r redirected to file');
-shouldNotWarn('find / 2>&1 | tee /tmp/find.txt', 'find piped to tee');
-
-// === unrelated commands ===
-shouldNotWarn('git status', 'git status');
-shouldNotWarn('ls -la', 'ls');
-shouldNotWarn('echo hello', 'echo');
-shouldNotWarn('node --version', 'node version');
-
-console.log(`Passed: ${passed}, Failed: ${failed}`);
-if (failed > 0) process.exit(1);