@ulysses-ai/create-workspace 0.23.3-beta.0 → 0.24.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.23.3-beta.0",
+  "version": "0.24.0-beta.0",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",
@@ -31,6 +31,7 @@
   "files": [
     "bin/",
     "lib/",
+    "!lib/**/*.test.mjs",
     "template/"
   ],
   "scripts": {

package/template/CLAUDE.md.tmpl

@@ -11,7 +11,7 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - Run `/rename` to label this chat before `/clear` — keeps the chat findable in your CLI history after the context is wiped
 
 ## Workspace Config
-@workspace.json
+Config lives in `workspace.json` — read it when a skill needs a value.
 @local-only-template-freshness.md
 
 ## Team Knowledge
@@ -52,4 +52,4 @@ Drop from the summary:
 - Exploratory reads that did not lead to a change
 - Conversational asides
 
-Files in `workspace-context/`, the session tracker (`session.md`) or chat drawer (`workspace-scratchpad/chats/{chat}/`), and any `design-*.md`/`plan-*.md` survive compaction — they're on disk. Re-read them on demand instead of trying to keep their contents in summary.
+Files in `workspace-context/`, the session tracker (`session.md`) or chat drawer (`workspace-scratchpad/chats/{chat}/`), and any `design-*.md`/`plan-*.md` survive compaction — they're on disk; re-read them on demand.

package/template/_claude/hooks/_utils.mjs

@@ -50,6 +50,49 @@ export function getWorkspacePaths(root) {
   };
 }
 
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/**
+ * The `Workspace config (workspace.json):` summary line session-start injects
+ * (gh:196): sessionModel, tracker, forge, and the repo names (primary
+ * marked). The labels mirror what the scripts reading workspace.json actually
+ * do — no invented defaults: an absent tracker is `off`, a tracker object
+ * without a type (or a non-object in its place) is `invalid`, an absent
+ * forge type leaves each repo's origin to pick its adapter, and `repos` that
+ * isn't a plain object is `invalid` rather than a silent empty manifest.
+ * sessionModel defaults to "session", matching how /start-work routes absent
+ * config.
+ */
+export function configSummary(config) {
+  const w = config?.workspace || {};
+  const model = typeof w.sessionModel === 'string' && w.sessionModel ? w.sessionModel : 'session';
+  const parts = [`sessionModel: ${model}`];
+
+  let tracker;
+  if (!w.tracker) tracker = 'off';
+  else if (!isPlainObject(w.tracker)) tracker = 'invalid';
+  else if (typeof w.tracker.type !== 'string' || !w.tracker.type) tracker = 'invalid (no type)';
+  else tracker = w.tracker.repo ? `${w.tracker.type} on ${w.tracker.repo}` : w.tracker.type;
+  parts.push(`tracker: ${tracker}`);
+
+  let forge;
+  if (w.forge === false) forge = 'off';
+  else if (!isPlainObject(w.forge)) forge = w.forge ? 'invalid' : 'auto (from origin)';
+  else if (typeof w.forge.type !== 'string' || !w.forge.type) forge = 'auto (from origin)';
+  else forge = w.forge.type;
+  parts.push(`forge: ${forge}`);
+
+  let repos;
+  if (!isPlainObject(config?.repos)) repos = config?.repos ? 'invalid' : 'none';
+  else {
+    const names = Object.keys(config.repos);
+    repos = names.length === 0 ? 'none'
+      : names.map((n) => (config.repos[n]?.primary ? `${n} (primary)` : n)).join(', ');
+  }
+  parts.push(`repos: ${repos}`);
+  return parts.join(' | ');
+}
+
 /**
  * Defensive normalization for a session tracker's `repos` field. A fresh
  * tracker written by create-work-session always holds an array, but an

package/template/_claude/hooks/session-start.mjs

@@ -15,6 +15,7 @@ import {
   updateSessionTracker,
   sessionFolderPath,
   timeAgo,
+  configSummary,
 } from './_utils.mjs';
 import { reconcile, readSessionRegistry, resolveChatName } from '../scripts/chat-record.mjs';
 
@@ -35,6 +36,15 @@ if (!config) {
 
 lines.push(`Workspace: ${config.workspace?.name || 'unnamed'}`);
 
+// One compact config summary (gh:196). CLAUDE.md no longer imports
+// workspace.json, so this line is what a session sees of the config without
+// reading the file — it names the file so sessions know where the values
+// live, and skills that need more than these fields read it on demand. Keep
+// it small: every session pays for it, which is exactly why the import was
+// dropped. configSummary (_utils.mjs) prints invalid/absent states rather
+// than inventing defaults the scripts don't apply.
+lines.push(`Workspace config (workspace.json): ${configSummary(config)}`);
+
 // Keep this chat's record in step with its identity (gh:132). The record is
 // keyed on sessionId and filed under the chat name, so a rename moves the file
 // and its drawer rather than orphaning them.

package/template/_claude/rules/work-item-tracking.md

@@ -15,9 +15,12 @@ humans and Claude read the same list in the same place.
 ## Configuration
 
 `workspace.json` → `workspace.tracker`: `{ "type": "github-issues", "repo": "owner/name" }`.
-`type` names the adapter at `.claude/scripts/trackers/{type}.mjs`; only `github-issues` ships.
-`repo` is adapter-specific — for GitHub, the slug where issues live, or `"auto"` to resolve
-from the git remote. No `workspace.tracker` means tracking is disabled, and skills fall back
+`type` names the adapter at `.claude/scripts/trackers/{type}.mjs`; the template ships
+`github-issues` and `gitlab-issues`. `repo` is adapter-specific — for GitHub, the slug where
+issues live, or `"auto"` to resolve from the git remote. Epics are configured with `epics`
+(label mode by default, `"native"` for GitLab Premium group epics) and `epicLabelPrefix`
+(default `epic:`) — an issue carries exactly one epic, and assigning an unknown epic name
+throws. No `workspace.tracker` means tracking is disabled, and skills fall back
 to a blank describe-the-work flow rather than fabricating a local mirror.
 
 ## Session linkage

package/template/_claude/rules/workspace-structure.md

@@ -28,7 +28,7 @@ Canonical loads verbatim into every session (`CLAUDE.md` → `@workspace-context
 
 ## Dynamic context loading (hooks)
 
-- **`session-start.mjs`** (`SessionStart`): injects the workspace name, a `Chat record:` line naming this chat's record, and a `Workspace root:` line with the launcher's absolute path (git-derived roots land on the source clone from inside a task worktree); with an active session pointer, also the session's name, branch, work item, and shared-context catalog.
+- **`session-start.mjs`** (`SessionStart`): injects the workspace name, a `Workspace config (workspace.json):` line, a `Chat record:` line for this chat, and a `Workspace root:` line with the launcher's path (git-derived roots land on the source clone in a task worktree); with an active session, also its name, branch, work item, and shared-context catalog.
 - **`subagent-start.mjs`** (`SubagentStart`): gives subagents the canonical truths they miss (subagents do not load `CLAUDE.md`) — locked files under `workspace.subagentInlineMaxBytes` (8192) are inlined with frontmatter stripped, larger ones become pointers, and past `workspace.subagentContextMaxBytes` (32768) the largest demote first. Gitignored and `local-only-*` files are excluded.
 
 Both are Node.js scripts — cross-platform, no shell dependency.

package/template/_claude/scripts/chat-record.mjs

@@ -23,19 +23,19 @@
 //   node chat-record.mjs --root <dir> --whoami
 //   node chat-record.mjs --root <dir> --owner <work-item>
 //   node chat-record.mjs --root <dir> --add-task    --chat <n> --branch <b> [--repo <r>] [--work-item <id>]
-//   node chat-record.mjs --root <dir> --remove-task --chat <n> (--work-item <id> | --branch <b>) [--repo <r>]
+//   node chat-record.mjs --root <dir> --remove-task --chat <n> (--work-item <id> [--branch <b>] | --branch <b>) [--repo <r>]
 //
-// --add-task / --remove-task report `action`: "added" | "updated" for
-// --add-task, "removed" | "unchanged" for --remove-task. They also keep the
-// older `updated` boolean / `removed` count fields — `updated` means "an
-// existing entry was replaced", not "anything changed" — but new callers
-// should read `action`. --whoami prints this chat's record name by matching
+// --add-task / --remove-task report `action`: "added" | "unchanged" for
+// --add-task, "removed" | "unchanged" for --remove-task, which also reports
+// a `removed` count — removing by work item without a branch takes every
+// branch of the item. --whoami prints this chat's record name by matching
 // $CLAUDE_CODE_SESSION_ID against the records' sessionId, nothing and exit
 // 1 when there is no match: the `Chat record:` hook line can be missing
 // after context compaction, and this is the recovery path. --owner prints
-// the chat a work item's open task belongs to as `{ chat, branch, repos }`,
-// and nothing with exit 1 when no record lists it — /start-work uses it to
-// offer adopting a task another chat started (gh:188).
+// the chat a work item's open task belongs to as `{ chat, branches }` — one
+// `{ branch, repos }` per branch the item is open on — and nothing with
+// exit 1 when no record lists it: /start-work uses it to offer adopting a
+// task another chat started (gh:188).
 
 import {
   readFileSync, writeFileSync, existsSync, mkdirSync,
@@ -200,35 +200,43 @@ function resolveChatName(root, { sessionId, registryName = null } = {}) {
 // merges — nothing about it is durable except the issue and the commits, so
 // the record holds only the pointer, never a copy of the issue.
 //
-// Identity is workItem + repo: the same issue can legitimately be open against
-// two repos in a multi-repo task, and re-recording the same one must update
-// rather than duplicate. /start-work is not always run exactly once. A task
-// recorded without a tracker (gh:173) carries `workItem: null` and is keyed
-// by branch + repo instead — the branch is the only identity it has — so
-// both add and remove take the branch for those entries.
+// Identity is workItem + repo + branch (gh:206). The same issue can
+// legitimately be open against two repos in a multi-repo task, and equally
+// on two branches of the same repo — a second attempt, a scoped alternative
+// — each with its own worktree and its own PR, so a different branch is
+// added alongside rather than replacing what was there, and re-recording
+// the same triple is a no-op. /start-work is not always run exactly once. A
+// task recorded without a tracker (gh:173) carries `workItem: null` and is
+// keyed by branch + repo instead — the branch is the only identity it has —
+// so add always takes the branch, and remove by branch alone touches only
+// those tracker-less entries.
 function addTask(root, chatName, { workItem = null, branch, repo = null } = {}) {
   if (!branch) throw new Error('addTask: branch is required');
   const rec = readRecord(root, chatName);
   if (!rec) throw new Error(`addTask: no chat record for "${chatName}"`);
   const i = rec.tasks.findIndex(
-    (t) => (t.workItem ?? null) === workItem && (t.repo ?? null) === repo
-      && (workItem !== null || t.branch === branch),
+    (t) => (t.workItem ?? null) === workItem && (t.repo ?? null) === repo && t.branch === branch,
   );
-  const task = { workItem, branch, repo };
-  if (i >= 0) rec.tasks[i] = task;
-  else rec.tasks.push(task);
+  if (i < 0) rec.tasks.push({ workItem, branch, repo });
   writeRecord(root, rec);
-  return { record: rec, action: i >= 0 ? 'updated' : 'added', updated: i >= 0 };
+  return { record: rec, action: i >= 0 ? 'unchanged' : 'added' };
 }
 
+// Removal selects by the same identity, one dimension at a time: a given
+// work item matches only its own entries (absent, only tracker-less ones),
+// while a given branch or repo narrows within whatever the work item
+// selected — an omitted branch or repo matches any. `--work-item` with
+// neither takes every branch of the item across repos; `--branch` narrows
+// the removal to that one branch.
 function removeTask(root, chatName, { workItem = null, branch = null, repo = null } = {}) {
   if (workItem === null && !branch) throw new Error('removeTask: workItem or branch is required');
   const rec = readRecord(root, chatName);
   if (!rec) throw new Error(`removeTask: no chat record for "${chatName}"`);
   const before = rec.tasks.length;
   rec.tasks = rec.tasks.filter(
-    (t) => !((t.workItem ?? null) === workItem && (t.repo ?? null) === repo
-      && (workItem !== null || t.branch === branch)),
+    (t) => !((t.workItem ?? null) === workItem
+      && (branch === null || t.branch === branch)
+      && (repo === null || (t.repo ?? null) === repo)),
   );
   writeRecord(root, rec);
   return { record: rec, action: before - rec.tasks.length > 0 ? 'removed' : 'unchanged', removed: before - rec.tasks.length };
@@ -252,6 +260,11 @@ function whoami(root, { env = process.env } = {}) {
 // by, so it doubles as the address for "ask the owner". Records are scanned
 // most-recently-modified first, so a stray duplicate answers with the chat
 // that touched its record last. Null when no record lists the work item.
+//
+// One issue may be open on several branches (gh:206), so the answer carries
+// one `{ branch, repos }` per branch — a multi-repo task is several entries
+// sharing a branch — rather than one flattened branch that would hide the
+// rest behind whichever entry happened to come first.
 function findOwner(root, workItem) {
   if (!workItem) return null;
   const dir = chatsDir(root);
@@ -268,9 +281,13 @@ function findOwner(root, workItem) {
       ? rec.tasks.filter((t) => (t.workItem ?? null) === workItem)
       : [];
     if (hits.length === 0) continue;
-    // One issue is one task: a shared branch across repos. All matching
-    // entries are that task's repos.
-    return { chat: rec.chat, branch: hits[0].branch, repos: hits.map((t) => t.repo) };
+    const branches = [];
+    for (const t of hits) {
+      const b = branches.find((x) => x.branch === t.branch);
+      if (b) { if (!b.repos.includes(t.repo)) b.repos.push(t.repo); }
+      else branches.push({ branch: t.branch, repos: [t.repo] });
+    }
+    return { chat: rec.chat, branches };
   }
   return null;
 }

package/template/_claude/scripts/classify-update.mjs

@@ -18,7 +18,10 @@
 //            Pass it explicitly in the worktree flow, where <root> is the
 //            worktree and the launcher's baseline may not be reachable.
 //
-// The default mode prints JSON with these lists:
+// The default mode prints JSON with these lists; unless a bullet says
+// otherwise an entry is a plain path string — entries in differs, localOnly,
+// deletedLocally, and removed may instead be { file, reason } objects when
+// the registry claims the path (gh:194, marker paragraph below).
 //   new        — no installed counterpart and no baseline entry; safe to
 //                batch-apply after one confirm
 //   identical  — installed file already equals the payload
@@ -64,16 +67,23 @@
 //                the config files above (the template dropping one hands it
 //                to the workspace, it never deletes user content),
 //                *.test.mjs (see staleTests), anything gitignored
-//                (machine-local), paths under .claude/worktrees/, and entries
-//                of workspace.json → workspace.localFiles (array of
-//                .claude/-relative paths or globs for files this workspace
-//                owns) (gh:180). Two markers refine the per-file offer
-//                (gh:190): `{ file, referencedBy }` — a removed hook that a
-//                workspace-only settings.json entry still registers (the
-//                config-diff paths); the skill removes file and settings
-//                entry together. `{ file, userOwned: true }` — no baseline
-//                entry, so the template never shipped it: the workspace's
-//                own, offered a workspace.localFiles entry, not deletion.
+//                (machine-local), paths under .claude/worktrees/,
+//                .claude/template-modifications.json (the workspace's own
+//                registry, never shipped), and the registry's `localFiles`
+//                entries (.claude/-relative paths or globs for files this
+//                workspace owns; the legacy workspace.json →
+//                workspace.localFiles array still counts, gh:180/gh:194).
+//                Markers refine the per-file offer: `{ file, referencedBy }`
+//                (gh:190) — a removed hook that a workspace-only
+//                settings.json entry still registers (the config-diff
+//                paths); the skill removes file and settings entry together.
+//                `{ file, userOwned: true }` — no baseline entry, so the
+//                template never shipped it: the workspace's own, offered a
+//                localFiles entry in the registry, not deletion.
+//                `{ file, unverifiable: true }` — the registry file doesn't
+//                parse, so its ownership claims cannot be read and no
+//                removal can be proven unowned; the skill stops and asks
+//                for the JSON to be fixed first (gh:194).
 //   staleTests — *.test.mjs files under .claude/ with no payload counterpart.
 //                The npm tarball ships no tests, so these came from a dev
 //                checkout and are never updated by /workspace-update; the
@@ -86,6 +96,39 @@
 //                An upgrade from inside that window into a workspace.json
 //                without the key reports { key, value, reason } so the skill
 //                writes the value explicitly (gh:190).
+//   staleModifications — registry entries whose installed file now equals
+//                the payload: the workspace already took the template's
+//                version, so the recorded reason describes nothing. Each
+//                reports { file, reason } so the skill can offer dropping
+//                the entry; file is the .claude/-prefixed path — the
+//                registry key is that path with the prefix stripped — and a
+//                key naming a directory (or normalizing away) never reports,
+//                only regular files compare (gh:194).
+//   legacyKeys — template-modification data still sitting in workspace.json
+//                (`workspace.localFiles`, `workspace.templateModifications`)
+//                instead of .claude/template-modifications.json; the skill
+//                offers the migration (gh:194).
+//   ignoredKeys — registry keys that escape .claude/ ('../CLAUDE.md',
+//                absolute paths, drive letters): the registry covers .claude/
+//                paths only — root files (CLAUDE.md, .mcp.json,
+//                .claudeignore) are handled by their own merge paths — so
+//                these report for the operator to fix instead of sitting
+//                silently inert (gh:194).
+//
+// Entries in differs, localOnly, deletedLocally, and removed carry the
+// workspace's registered modification reason (gh:194): a path listed in
+// .claude/template-modifications.json's `modifications` map (read through
+// template-modifications.mjs, which also honors the legacy workspace.json
+// keys for one release) becomes { file, reason } in those lists — reason
+// undefined entries stay plain paths, and a removed entry's existing
+// referencedBy/userOwned markers keep their fields alongside `reason`.
+// `modificationsError`, present only when the registry file doesn't parse,
+// names the parse error: reasons and localFiles exclusions from the file are
+// then unavailable (legacy keys still apply) and classification FAILS
+// CLOSED — every removed entry is marked `unverifiable: true`, because the
+// file's ownership claims cannot be read, and the skill stops and asks the
+// operator to fix the JSON before any per-file decision. Nothing is applied
+// or deleted silently.
 //
 // Plus `hasBaseline`: whether a usable baseline was found, `baselineSource`
 // (which file it came from) and `baselineReconstructed`. The default
@@ -117,15 +160,18 @@
 //                     present as `updated` again next time; see
 //                     template-baseline.mjs. Throws rather than writing an
 //                     empty baseline.
-//   --merge-claude-md print JSON { claudeMd, missingIncludes }: CLAUDE.md
-//                     with the payload's CLAUDE.md.tmpl merged in — template
-//                     lines updated, the workspace's own lines (custom skill
-//                     entries, sections) kept — plus the `@{path}` include
-//                     lines the merged file carries whose targets don't
-//                     exist at the root (machine-local local-only-* targets
-//                     exempt). The skill shows the diff against the current
-//                     file before writing, and asks on each missing include
-//                     instead of leaving it dangling (gh:190).
+//   --merge-claude-md print JSON { claudeMd, droppedIncludes, missingIncludes }:
+//                     CLAUDE.md with the payload's CLAUDE.md.tmpl merged in —
+//                     template lines updated, the workspace's own lines (custom
+//                     skill entries, sections) kept — minus the retired
+//                     @-includes the workspace still carries but this payload
+//                     no longer ships (droppedIncludes names them, gh:196) —
+//                     plus the `@{path}` include lines the merged file carries
+//                     whose targets don't exist at the root (machine-local
+//                     local-only-* targets exempt). The skill shows the diff
+//                     against the current file before writing, and asks on
+//                     each missing include instead of leaving it dangling
+//                     (gh:190).
 
 import {
   existsSync,
@@ -145,6 +191,15 @@ import {
   readBaselineFile,
   writeBaseline,
 } from './template-baseline.mjs';
+// The workspace's template-modification registry (gh:194): localFiles
+// exclusions, registered modification reasons, keys that escape .claude/,
+// the legacy workspace.json keys still present, and a parse error when the
+// file is broken. The module documents the shape, the path normalization,
+// and the one-release legacy fallback.
+import {
+  readTemplateModifications,
+  TEMPLATE_MODIFICATIONS_PATH,
+} from './template-modifications.mjs';
 
 function isMainModule(metaUrl) {
   if (!process.argv[1]) return false;
@@ -308,18 +363,37 @@ function* walkInstalledFiles(absRoot) {
   }
 }
 
-/** workspace.json → workspace.localFiles, normalized to .claude/-relative globs. */
-function readLocalFiles(absRoot) {
-  const configPath = join(absRoot, 'workspace.json');
+/**
+ * A classification path's registered modification reason, or undefined.
+ * Registry keys are .claude/-relative, so only paths under .claude/ can be
+ * registered — .mcp.json and .claudeignore live outside it and route to
+ * their own lists anyway.
+ */
+function registeredReason(modifications, rel) {
+  if (!rel.startsWith('.claude/')) return undefined;
+  const reason = modifications[rel.slice('.claude/'.length)];
+  return typeof reason === 'string' ? reason : undefined;
+}
+
+/** Attach registered reasons to a list of plain-path entries (gh:194). */
+function withReasons(list, modifications) {
+  return list.map((rel) => {
+    const reason = registeredReason(modifications, rel);
+    return reason === undefined ? rel : { file: rel, reason };
+  });
+}
+
+/**
+ * A registry key may name a directory or a path that is gone; only a regular
+ * file that exists can be content-compared, so the stale check skips
+ * everything else rather than reading (and crashing on) a directory
+ * (gh:194 review).
+ */
+function isRegularFile(path) {
   try {
-    const config = JSON.parse(readFileSync(configPath, 'utf8'));
-    const entries = config?.workspace?.localFiles;
-    if (!Array.isArray(entries)) return [];
-    return entries
-      .filter((e) => typeof e === 'string' && e.length > 0)
-      .map((e) => e.replace(/^(\.claude\/)+/, ''));
+    return statSync(path).isFile();
   } catch {
-    return [];
+    return false;
   }
 }
 
@@ -345,6 +419,10 @@ function isOwnedByWorkspace(rel, localFiles) {
   if (rel === '.claude/settings.local.json' || rel === '.claude/.active-session.json' || rel === BASELINE_PATH) {
     return true;
   }
+  // The template-modification registry is workspace-owned state the template
+  // never ships — like the baseline, its absence from the payload is not a
+  // removal (gh:194).
+  if (rel === TEMPLATE_MODIFICATIONS_PATH) return true;
   if (!rel.startsWith('.claude/')) return false;
   const claudeRel = rel.slice('.claude/'.length);
   return localFiles.some((pattern) => globMatches(pattern, claudeRel));
@@ -425,6 +503,7 @@ export function classifyUpdate({ root, payload, baseline: baselineArg = null })
   const payloadFiles = [...walkFiles(absPayload)].filter(isClassified);
   const payloadSet = new Set(payloadFiles);
   const { baseline, source } = resolveBaseline({ root: absRoot, payload: absPayload, baseline: baselineArg });
+  const mods = readTemplateModifications(absRoot);
 
   const result = {
     new: [],
@@ -438,10 +517,14 @@ export function classifyUpdate({ root, payload, baseline: baselineArg = null })
     removed: [],
     staleTests: [],
     implicitDefaults: [],
+    staleModifications: [],
+    legacyKeys: mods.legacyKeys,
+    ignoredKeys: mods.ignoredKeys,
     hasBaseline: baseline !== null,
     baselineSource: source,
     baselineReconstructed: baseline !== null && baseline.reconstructed === true,
   };
+  if (mods.parseError !== null) result.modificationsError = mods.parseError;
   for (const rel of payloadFiles) {
     // Jointly-owned JSON configs never compare by content — the config
     // list carries a key-level diff for the skill to merge instead.
@@ -494,7 +577,7 @@ export function classifyUpdate({ root, payload, baseline: baselineArg = null })
 
   // Removed: installed verbatim-managed files with no payload counterpart.
   const skipSet = new Set(payloadFiles);
-  const localFiles = readLocalFiles(absRoot);
+  const localFiles = mods.localFiles;
   const installedFiles = [...walkInstalledFiles(absRoot)];
   const gitignored = gitIgnoredPaths(absRoot, installedFiles);
   for (const rel of installedFiles) {
@@ -529,6 +612,46 @@ export function classifyUpdate({ root, payload, baseline: baselineArg = null })
     }
   }
   linkRemovedHooks(result, absRoot);
+
+  // Registered reasons ride along wherever a local divergence is visible
+  // (gh:194): differs/localOnly/deletedLocally entries become { file, reason }
+  // for registered paths, and a removed entry — plain, referencedBy, or
+  // userOwned — gains the same reason field.
+  result.differs = withReasons(result.differs, mods.modifications);
+  result.localOnly = withReasons(result.localOnly, mods.modifications);
+  result.deletedLocally = withReasons(result.deletedLocally, mods.modifications);
+  result.removed = result.removed.map((entry) => {
+    const file = typeof entry === 'string' ? entry : entry.file;
+    const reason = registeredReason(mods.modifications, file);
+    if (reason === undefined) return entry;
+    return typeof entry === 'string' ? { file, reason } : { ...entry, reason };
+  });
+
+  // A registry that doesn't parse leaves its ownership claims unreadable, so
+  // no removal can be proven unowned: fail closed — mark every removed entry
+  // unverifiable and let the skill stop and ask for the JSON to be fixed
+  // before any per-file decision (gh:194 review).
+  if (mods.parseError !== null) {
+    result.removed = result.removed.map((entry) => (typeof entry === 'string'
+      ? { file: entry, unverifiable: true }
+      : { ...entry, unverifiable: true }));
+  }
+
+  // Stale registrations: the installed file now equals the payload's copy, so
+  // the workspace already holds the template's version and the recorded
+  // reason describes nothing. The skill offers to drop them. A path missing
+  // on either side never reports — a registered deletion is a live decision
+  // (it explains a deletedLocally entry), not a stale one — and neither does
+  // a key naming a directory: only regular files on both sides compare.
+  result.staleModifications = Object.entries(mods.modifications)
+    .filter(([key]) => {
+      const installed = join(absRoot, `.claude/${key}`);
+      const inPayload = join(absPayload, `.claude/${key}`);
+      if (!isRegularFile(installed) || !isRegularFile(inPayload)) return false;
+      return hashBytes(readFileSync(installed)) === hashBytes(readFileSync(inPayload));
+    })
+    .map(([key, reason]) => ({ file: `.claude/${key}`, reason }));
+
   result.implicitDefaults = implicitDefaults(absRoot, absPayload);
   return result;
 }
@@ -580,6 +703,41 @@ function linkRemovedHooks(result, absRoot) {
 
 // ---------- CLAUDE.md merge ----------
 
+// @-includes the template has retired. The merge keeps "lines the template
+// doesn't have" — a workspace's `@workspace.json` line would otherwise survive
+// every update forever. A retired include is dropped only when THIS payload no
+// longer ships it; an older payload whose template still carries the line
+// merges it like any other template line. The SessionStart hook now supplies
+// the config summary the import existed for (gh:196).
+const RETIRED_INCLUDES = ['workspace.json'];
+
+function hasIncludeLine(text, name) {
+  return text.split(/\r?\n/).some((l) => l.trim() === `@${name}`);
+}
+
+/** Every `@{name}` include line removed from `text`, preserving its EOLs. */
+function dropIncludeLines(text, name) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  return text.split(/\r?\n/).filter((l) => l.trim() !== `@${name}`).join(eol);
+}
+
+/**
+ * Retired includes still present in the workspace's CLAUDE.md: each is named
+ * in the output so the skill can call the drop out, and stripped from the
+ * current text before the merge so the merged result loses the line.
+ */
+function stripRetiredIncludes(currentText, nextText) {
+  const dropped = [];
+  let stripped = currentText;
+  for (const name of RETIRED_INCLUDES) {
+    if (!hasIncludeLine(currentText, name)) continue;
+    if (hasIncludeLine(nextText, name)) continue; // this payload still ships it
+    dropped.push(name);
+    stripped = dropIncludeLines(stripped, name);
+  }
+  return { stripped, dropped };
+}
+
 /**
  * Split markdown into blocks: the preamble (heading null) plus one block per
  * `## ` heading. Deeper headings belong to their enclosing section, and `## `
@@ -764,12 +922,16 @@ function mergeClaudeMdMode(args) {
   const next = readFileSync(tmplPath, 'utf8').replace(/\{\{project-name\}\}/g, name);
   const claudeMdPath = join(absRoot, 'CLAUDE.md');
   const current = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, 'utf8') : '';
-  const claudeMd = mergeClaudeMd(current, next);
+  const { stripped, dropped } = stripRetiredIncludes(current, next);
+  const claudeMd = mergeClaudeMd(stripped, next);
   // The gained-@include check is deterministic, not something to eyeball in
   // the diff: every include line whose target is absent here is reported so
   // the skill asks (stub or omit) instead of writing it silently (gh:190).
+  // A retired include the workspace still carried is the mirror decision —
+  // reported as dropped so the diff the operator approves says so (gh:196).
   process.stdout.write(JSON.stringify({
     claudeMd,
+    droppedIncludes: dropped,
     missingIncludes: missingIncludes(absRoot, claudeMd),
   }, null, 2) + '\n');
 }