create-agentic-workspace 0.17.3 → 0.17.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-workspace",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "description": "The pre-session bootstrap wizard for an Agentic Foundry workspace: declares (never grants) the permission floor, absorbs foundry-bootstrap.sh's out-of-session identity wiring, and scaffolds a seven-file schema-valid workspace. Zero dependencies, no lifecycle scripts, no telemetry.",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,7 @@
     "src",
     "templates",
     "permission-floor.json",
+    "retired-artifacts.json",
     "package.json",
     "README.md"
   ],
@@ -34,7 +35,7 @@
     "marketplace_name": "agentic-foundry",
     "marketplace_repo": "lukasrepublic/agentic-foundry",
     "plugin_name": "foundry",
-    "plugin_version": "1.17.3",
+    "plugin_version": "1.17.5",
     "pins_researched": "2026-08-02"
   }
 }

package/permission-floor.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "plugin_root_glob": "~/.claude/plugins/cache/*/foundry/*",
-  "generated_for_plugin_version": "1.17.3",
+  "generated_for_plugin_version": "1.17.5",
   "entries": [
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-acceptance-contract-validate.py:*)",

package/retired-artifacts.json

@@ -0,0 +1,32 @@
+{
+  "schema_version": 1,
+  "_comment": "Workspace-side artifacts an earlier release wrote and no current release reads (hotfix-v1.17.4, ER #236). The updater reports every present entry as [stale] on every run and removes it only under --cleanup. `path` is relative to the workspace root; a single `*` is allowed in the LAST segment only (a basename glob). `kind` is `file` or `dir`; a path of the other kind, or a symlink, is reported and never removed. Nothing outside this list is ever touched; `.claude/skills`, `.claude/agents` and operator files are never candidates.",
+  "reference_scan": {
+    "_comment": "ER #241: a catalogued path is `stale` only when NONE of these workspace files names its full relative path (and, for a hook, when no other hook script names its basename) — an adopter may re-adopt a retired path for their own CI or tooling, in their own namespace. The updater and the doctor both read this list. A heuristic, deliberately fail-closed: a symlink, an unreadable entry, or a budget exceeded refuses every row. `.foundry/` itself is not scanned (the upgrade report lists retired paths by design).",
+    "files": [".claude/settings.json", ".claude/settings.local.json", ".mcp.json", ".gitlab-ci.yml", "Jenkinsfile", "Dockerfile", "Makefile", "justfile", "Taskfile.yml", "package.json", "pyproject.toml", "tox.ini", "noxfile.py", ".envrc", ".pre-commit-config.yaml", ".vscode/tasks.json"],
+    "dirs": [".github", ".gitlab", ".circleci", ".buildkite", ".gitea", ".forgejo", ".claude/hooks", ".claude/commands", ".claude/skills", ".claude/agents", ".githooks", ".husky", "scripts", "bin", "tools"],
+    "root_suffixes": [".md", ".sh", ".yml", ".yaml"],
+    "max_files": 5000,
+    "max_dirs": 20000,
+    "max_bytes": 4194304,
+    "max_total_bytes": 67108864
+  },
+  "entries": [
+    { "path": ".foundry/wiring-hash.pin", "kind": "file", "retired_in": "0.24.0", "reason": "the wiring-hash auto-heal and its pin were removed with the live-seam merge gate" },
+    { "path": ".foundry/active-workflow.json", "kind": "file", "retired_in": "0.5.0", "reason": "the macro-workflow engine's active-workflow pointer; the engine was retired" },
+    { "path": ".foundry/context-snapshots", "kind": "dir", "retired_in": "0.25.0", "reason": "the bespoke context-lifecycle snapshots; /foundry:context wraps native /compact and --resume now" },
+    { "path": ".foundry/branch-protection-unenforced.json", "kind": "file", "retired_in": "0.24.0", "reason": "branch-protection-as-code's marker; Tier A is applied by hand and observed, never written from here" },
+    { "path": ".foundry/hasher-ref", "kind": "file", "retired_in": "0.24.0", "reason": "the retired hasher reference; no current foundry script reads it" },
+    { "path": ".claude/settings.json.bak", "kind": "file", "retired_in": "1.7.0", "reason": "a backup an early settings migration left behind; the updater writes atomically and keeps no .bak" },
+    { "path": ".claude/dispatch-queue", "kind": "dir", "retired_in": "1.10.0", "reason": "the retired dispatch-queue's old location; the multi-repo worktree manifest lives under .foundry/dispatch-queue" },
+    { "path": ".claude/dispatcher-mode.json", "kind": "file", "retired_in": "1.10.0", "reason": "the retired dispatcher's mode file" },
+    { "path": ".claude/dispatcher-mode.json.example", "kind": "file", "retired_in": "1.10.0", "reason": "the retired dispatcher's example" },
+    { "path": ".claude/dispatcher-mode.json.lock", "kind": "file", "retired_in": "1.10.0", "reason": "the retired dispatcher's lock" },
+    { "path": ".claude/dispatch-log.jsonl.example", "kind": "file", "retired_in": "1.10.0", "reason": "the retired dispatcher's example log" },
+    { "path": ".claude/context-state", "kind": "dir", "retired_in": "0.25.0", "reason": "the bespoke context-state store; native session state replaced it" },
+    { "path": ".claude/resume", "kind": "dir", "retired_in": "0.25.0", "reason": "the bespoke resume store; native --resume replaced it" },
+    { "path": ".claude/logs", "kind": "dir", "retired_in": "1.10.0", "reason": "the retired dispatcher's logs" },
+    { "path": ".claude/session-learnings", "kind": "dir", "retired_in": "1.0.0", "reason": "the old learnings location; the partition is .foundry/session-learnings" },
+    { "path": ".claude/hooks/*-exec-guard.sh", "kind": "file", "exclude_prefix": "foundry-", "retired_in": "1.8.0", "reason": "the retired session-context framework's cloud-cli exec guard; a hook still named by a command in .claude/settings*.json is refused, never removed" }
+  ]
+}

package/src/floorReconcile.mjs

@@ -272,13 +272,25 @@ function shippedRootNames(map) {
   return set;
 }
 
+/** The `(name, sub)` keys of every wildcard-shaped `ask` row a settings object carries — what
+ * `planRetirements({ askCoveredBy })` takes for the local file (hotfix-v1.17.4). */
+export function askRootKeys(settingsObj, map) {
+  const keys = new Set();
+  const perms = (settingsObj && settingsObj.permissions) || {};
+  for (const rule of perms.ask || []) {
+    const parsed = typeof rule === 'string' ? parseFloorRootShape(rule, map.plugin_root_glob) : null;
+    if (parsed) keys.add(rootNameKey(parsed));
+  }
+  return keys;
+}
+
 /** Compute the rows the reconcile SHALL remove (AC-FRR-1), WITHOUT touching the filesystem. Every
  * `allow`/`ask` row shaped exactly like the floor's own root-glob rows, whose `(name, sub)` pair the
  * shipped map no longer declares, is queued for removal. `deny` is never a candidate (AC-FRR-2) —
  * retirement only narrows a grant or a prompt, and a deny row read back as "extra" is, if anything,
  * a reason to leave it exactly where the operator (or an earlier release) put it. Returns
  * `{ retirements: { allow: [...], ask: [...] }, total }`. */
-export function planRetirements({ settingsObj, map }) {
+export function planRetirements({ settingsObj, map, askCoveredBy = null }) {
   const shipped = shippedRootNames(map);
   const shippedAsk = new Set();
   for (const e of map.entries) {
@@ -286,6 +298,13 @@ export function planRetirements({ settingsObj, map }) {
     const parsed = parseFloorRootShape(e.rule, map.plugin_root_glob);
     if (parsed) shippedAsk.add(rootNameKey(parsed));
   }
+  // hotfix-v1.17.4 (PR #237 security review Risk 3): for a file this pass does NOT also reconcile
+  // (`.claude/settings.local.json`), "the wildcard ask row replaces it" is only true when the
+  // TRACKED file actually carries that wildcard row — so the caller passes the tracked file's ask
+  // keys (`askRootKeys`) and a pinned `ask` row is retired only when both sets hold the pair.
+  // `null` (the tracked-file call sites, where the same pass adds the wildcard row) keeps the
+  // v1.17.3 rule unchanged.
+  const askReplaced = (key) => shippedAsk.has(key) && (askCoveredBy === null || askCoveredBy.has(key));
   const retirements = { allow: [], ask: [] };
   const perms = (settingsObj && settingsObj.permissions) || {};
   for (const tier of ['allow', 'ask']) {
@@ -305,7 +324,7 @@ export function planRetirements({ settingsObj, map }) {
       const pinned = parseFloorPinnedShape(rule, map.plugin_root_glob);
       if (pinned) {
         if (tier === 'allow') retirements[tier].push(rule);
-        else if (shippedAsk.has(rootNameKey(pinned))) retirements[tier].push(rule);
+        else if (askReplaced(rootNameKey(pinned))) retirements[tier].push(rule);
       }
       // any other shape -> never touched (AC-FRR-2)
     }
@@ -438,8 +457,19 @@ export function writeTargetAtomically(targetPath, obj) {
   const dir = path.dirname(targetPath);
   const tmp = path.join(dir, `.settings.json.${process.pid}.tmp`);
   const bytes = Buffer.from(`${JSON.stringify(obj, null, 2)}\n`, 'utf-8');
+  // hotfix-v1.17.4 (PR #237 security review Risk 5): a rename-install would otherwise reset the
+  // target's mode to the umask default — an operator's 0600 `settings.local.json` (it often holds
+  // `env`) must come back 0600. The original's permission bits are copied onto the temp file
+  // before the rename; a target that does not exist yet keeps the default.
+  let mode = null;
+  try {
+    mode = fs.statSync(targetPath).mode & 0o777;
+  } catch {
+    mode = null;
+  }
   const fd = fs.openSync(tmp, 'wx');
   try {
+    if (mode !== null) fs.fchmodSync(fd, mode);
     fs.writeFileSync(fd, bytes);
     fs.fsyncSync(fd);
   } finally {

package/src/retiredArtifacts.mjs

@@ -0,0 +1,298 @@
+// retiredArtifacts.mjs — the sweep for workspace-side files an earlier release wrote and no current
+// release reads (hotfix-v1.17.4, ER #236). Driven by the shipped catalogue `cli/retired-artifacts.json`:
+// every present entry is reported `[stale]` on every run; removal happens only under `--cleanup`,
+// only for catalogued paths, only when the path is exactly the catalogued kind (a regular file, or a
+// real directory) — a symlink or the other kind is reported `[refused]` and left alone, and so is a
+// hook under `.claude/hooks/` that a hook command in `.claude/settings*.json` still names, and so is
+// any path a workspace wiring file (CI, scripts, settings, root docs — the catalogue's reference_scan)
+// still names by its full relative path (ER #241). Nothing
+// outside the catalogue is ever a candidate: `.claude/skills`, `.claude/agents` and every operator
+// file are invisible to this module by construction.
+import fs from 'node:fs';
+import path from 'node:path';
+import { confinedJoin } from './util.mjs';
+
+export const CATALOGUE_REL = 'retired-artifacts.json';
+
+/** Load and validate the catalogue shipped beside `src/` (the package root). Refuses a malformed
+ * entry loudly rather than sweeping with a half-read list. */
+export function loadRetiredCatalogue(pkgDir) {
+  const doc = JSON.parse(fs.readFileSync(path.join(pkgDir, CATALOGUE_REL), 'utf-8'));
+  if (!doc || doc.schema_version !== 1 || !Array.isArray(doc.entries)) {
+    throw new Error('retired-artifacts.json: unrecognised schema');
+  }
+  const rs = doc.reference_scan;
+  const relOk = (x) => typeof x === 'string' && x.length > 0 && !path.isAbsolute(x) && !x.split(/[\\/]+/).includes('..');
+  if (!rs || !Array.isArray(rs.files) || !Array.isArray(rs.dirs) || !Array.isArray(rs.root_suffixes)
+    || !rs.files.every(relOk) || !rs.dirs.every(relOk) || !rs.root_suffixes.every((x) => typeof x === 'string' && x.startsWith('.'))
+    || !['max_files', 'max_dirs', 'max_bytes', 'max_total_bytes'].every((k) => Number.isInteger(rs[k]) && rs[k] >= 1)) {
+    throw new Error('retired-artifacts.json: reference_scan missing or malformed');
+  }
+  for (const e of doc.entries) {
+    if (typeof e.path !== 'string' || path.isAbsolute(e.path) || e.path.split(/[\\/]+/).includes('..')) {
+      throw new Error(`retired-artifacts.json: bad path ${JSON.stringify(e.path)}`);
+    }
+    if (e.kind !== 'file' && e.kind !== 'dir') throw new Error(`retired-artifacts.json: bad kind for ${e.path}`);
+    const star = e.path.indexOf('*');
+    if (star !== -1 && (e.path.lastIndexOf('*') !== star || e.path.slice(star).includes('/'))) {
+      throw new Error(`retired-artifacts.json: only one '*' in the last segment is allowed (${e.path})`);
+    }
+  }
+  return doc;
+}
+
+/** Expand an entry to concrete relative paths present on disk: the path itself, or, for a
+ * basename glob, every directory entry that matches (names starting with `exclude_prefix` skipped). */
+function candidates(physicalRoot, entry) {
+  if (!entry.path.includes('*')) return [entry.path];
+  const dirRel = path.posix.dirname(entry.path);
+  const pattern = path.posix.basename(entry.path);
+  const [pre, post] = pattern.split('*');
+  const dirAbs = confinedJoin(physicalRoot, dirRel);
+  if (!dirAbs) return [];
+  let names;
+  try {
+    names = fs.readdirSync(dirAbs);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => n.startsWith(pre) && n.endsWith(post) && n.length >= pre.length + post.length)
+    .filter((n) => !(entry.exclude_prefix && n.startsWith(entry.exclude_prefix)))
+    .map((n) => path.posix.join(dirRel, n));
+}
+
+const HOOKS_DIR_REL = '.claude/hooks/';
+const SETTINGS_FILES = ['.claude/settings.json', '.claude/settings.local.json'];
+
+/** Every `command` string under `hooks` in the two workspace settings files, joined — the text a
+ * hook candidate's basename is checked against (PR #237 security review Risk 1: a basename glob
+ * must never take a hook the operator still wires). `unreadable` is true when a settings file
+ * exists but does not parse: then nothing under `.claude/hooks/` is planned removable (fail-closed). */
+function hookCommandText(physicalRoot) {
+  const parts = [];
+  let unreadable = false;
+  for (const rel of SETTINGS_FILES) {
+    const abs = confinedJoin(physicalRoot, rel);
+    if (!abs) continue;
+    let raw;
+    try {
+      if (!fs.lstatSync(abs).isFile()) continue;
+      raw = fs.readFileSync(abs, 'utf-8');
+    } catch {
+      continue; // absent: nothing wired there
+    }
+    let obj;
+    try {
+      obj = JSON.parse(raw);
+    } catch {
+      unreadable = true;
+      continue;
+    }
+    const walk = (v) => {
+      if (Array.isArray(v)) { for (const x of v) walk(x); return; }
+      if (v && typeof v === 'object') {
+        if (typeof v.command === 'string') parts.push(v.command);
+        for (const x of Object.values(v)) walk(x);
+      }
+    };
+    if (obj && typeof obj === 'object' && obj.hooks) walk(obj.hooks);
+  }
+  return { text: parts.join('\n'), unreadable };
+}
+
+// Skipped at ANY depth: version-control internals and installed dependencies only (PR #242 review
+// Risk 1 — `build`/`dist`/`venv` inside a wiring dir may hold wiring, so they are read).
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+const ABSENT = new Set(['ENOENT', 'ENOTDIR']);
+
+/** ER #241: read every file the catalogue's `reference_scan` names (explicit files, the tree under each
+ * listed dir, and workspace-root files with a listed suffix). Returns `{ texts: [[relPath, text]],
+ * incomplete: null | '<why>' }`. Links are never followed and never skipped silently: a symlink, a
+ * path escaping the root, a non-ENOENT stat error, an unreadable entry, or any budget exceeded
+ * (`max_files`, `max_dirs`, `max_bytes` per file, `max_total_bytes`) makes the scan `incomplete`, and
+ * the caller then refuses every row (PR #242 review Risks 2 and 5). Iterative, so depth cannot throw. */
+export function scanReferenceTexts(physicalRoot, rs) {
+  const texts = [];
+  let files = 0;
+  let dirs = 0;
+  let bytes = 0;
+  let incomplete = null;
+  const fail = (why) => { if (!incomplete) incomplete = why; };
+  const statOf = (rel) => {
+    const abs = confinedJoin(physicalRoot, rel);
+    if (!abs) { fail(`${rel} resolves outside the workspace`); return null; }
+    try {
+      return { abs, st: fs.lstatSync(abs) };
+    } catch (e) {
+      if (!ABSENT.has(e.code)) fail(`${rel} unreadable (${e.code || 'error'})`);
+      return null; // absent: nothing wired there
+    }
+  };
+  const readFile = (rel, abs, st) => {
+    files += 1;
+    if (files > rs.max_files) return fail(`more than ${rs.max_files} files to scan`);
+    if (st.size > rs.max_bytes) return fail(`${rel} is larger than ${rs.max_bytes} bytes`);
+    bytes += st.size;
+    if (bytes > rs.max_total_bytes) return fail(`more than ${rs.max_total_bytes} bytes to scan`);
+    try { texts.push([rel, fs.readFileSync(abs, 'utf-8')]); } catch (e) { fail(`${rel} unreadable (${e.code || 'error'})`); }
+  };
+  const visit = (rel, { treeRoot }) => {
+    const hit = statOf(rel);
+    if (!hit) return [];
+    const { abs, st } = hit;
+    if (st.isSymbolicLink()) { fail(`${rel} is a symlink (not followed)`); return []; }
+    if (st.isFile()) { readFile(rel, abs, st); return []; }
+    if (!st.isDirectory() || !treeRoot) return [];
+    dirs += 1;
+    if (dirs > rs.max_dirs) { fail(`more than ${rs.max_dirs} directories to scan`); return []; }
+    let names;
+    try { names = fs.readdirSync(abs).sort(); } catch (e) { fail(`${rel} unreadable (${e.code || 'error'})`); return []; }
+    return names.filter((n) => !SKIP_DIRS.has(n)).map((n) => path.posix.join(rel, n));
+  };
+  for (const f of rs.files) { visit(f, { treeRoot: false }); if (incomplete) return { texts, incomplete }; }
+  for (const d of rs.dirs) {
+    const stack = [d];
+    while (stack.length > 0 && !incomplete) stack.push(...visit(stack.pop(), { treeRoot: true }).reverse());
+    if (incomplete) return { texts, incomplete };
+  }
+  let rootNames = [];
+  try { rootNames = fs.readdirSync(physicalRoot).sort(); } catch (e) { fail(`workspace root unreadable (${e.code || 'error'})`); }
+  const explicit = new Set(rs.files);
+  for (const n of rootNames) {
+    if (incomplete) break;
+    if (explicit.has(n) || !rs.root_suffixes.some((suf) => n.endsWith(suf))) continue;
+    visit(n, { treeRoot: false });
+  }
+  return { texts, incomplete };
+}
+
+/** Plan: `{ rows: [{ relPath, kind, retired_in, reason, state, why?, entries? }], present, refused }`
+ * where `state` is `stale` (present, of the catalogued kind, and not wired) or `refused` (present
+ * but a symlink, the other kind, escaping the root, or — for a hook — still named by a hook command
+ * in `.claude/settings*.json`, or those files unreadable); absent paths are omitted. A `dir` row
+ * carries `entries` (its direct entry count) so the operator sees what a removal takes. Pure over
+ * the filesystem — nothing is written. */
+export function planRetiredArtifacts({ physicalRoot, catalogue }) {
+  const rows = [];
+  let hooks = null; // read lazily, once, only when a hook candidate is present
+  let refs = null;  // ER #241: the reference scan, read lazily, once, only when a stale candidate exists
+  for (const entry of catalogue.entries) {
+    for (const relPath of candidates(physicalRoot, entry)) {
+      const abs = confinedJoin(physicalRoot, relPath);
+      let st = null;
+      if (abs) {
+        try {
+          st = fs.lstatSync(abs);
+        } catch {
+          continue; // absent: nothing to say
+        }
+      } else {
+        // the path resolves OUTSIDE the workspace (a symlink escaping the root): present, reported,
+        // never touched
+        try {
+          st = fs.lstatSync(path.join(physicalRoot, relPath));
+        } catch {
+          continue;
+        }
+      }
+      const kindOk = abs && !st.isSymbolicLink() && (entry.kind === 'dir' ? st.isDirectory() : st.isFile());
+      const row = { relPath, kind: entry.kind, retired_in: entry.retired_in, reason: entry.reason, state: kindOk ? 'stale' : 'refused', why: kindOk ? null : 'kind' };
+      if (row.state === 'stale' && relPath.startsWith(HOOKS_DIR_REL)) {
+        if (hooks === null) hooks = hookCommandText(physicalRoot);
+        if (hooks.unreadable) { row.state = 'refused'; row.why = 'settings-unreadable'; }
+        else if (hooks.text.includes(path.posix.basename(relPath))) { row.state = 'refused'; row.why = 'referenced'; }
+      }
+      if (row.state === 'stale') {
+        // ER #241: an adopter may re-adopt a retired path for their own CI or tooling. A path named
+        // (full relative path) by any file the catalogue's reference_scan lists is refused, never
+        // removed; a scan that could not finish refuses every row (fail-closed).
+        if (refs === null) refs = scanReferenceTexts(physicalRoot, catalogue.reference_scan);
+        if (refs.incomplete) { row.state = 'refused'; row.why = 'scan-incomplete'; row.detail = refs.incomplete; }
+        else {
+          // full relative path anywhere in the scan set; for a hook, also its basename in any OTHER
+          // hook script (a live hook that sources `$(dirname "$0")/<name>` — PR #242 review Risk 3)
+          const base = relPath.startsWith(HOOKS_DIR_REL) ? path.posix.basename(relPath) : null;
+          const by = refs.texts.filter(([rel, text]) => rel !== relPath
+            && (text.includes(relPath) || (base && rel.startsWith(HOOKS_DIR_REL) && text.includes(base)))).map(([rel]) => rel);
+          if (by.length > 0) { row.state = 'refused'; row.why = 'referenced'; row.refs = by.slice(0, 3); }
+        }
+      }
+      if (row.state === 'stale' && entry.kind === 'dir') {
+        try { row.entries = fs.readdirSync(abs).length; } catch { row.entries = null; }
+      }
+      rows.push(row);
+    }
+  }
+  return {
+    rows,
+    present: rows.filter((r) => r.state === 'stale').length,
+    refused: rows.filter((r) => r.state === 'refused').length,
+  };
+}
+
+/** Remove every `stale` row (re-checked with lstat immediately before each removal). Returns the
+ * count removed. A row whose state changed between plan and apply is skipped, never forced. */
+export function applyRetiredArtifacts(plan, physicalRoot) {
+  let removed = 0;
+  for (const row of plan.rows) {
+    if (row.state !== 'stale') continue;
+    const abs = confinedJoin(physicalRoot, row.relPath);
+    if (!abs) continue;
+    let st;
+    try {
+      st = fs.lstatSync(abs);
+    } catch {
+      continue;
+    }
+    if (st.isSymbolicLink()) continue;
+    if (row.kind === 'dir' ? !st.isDirectory() : !st.isFile()) continue;
+    try {
+      if (row.kind === 'dir') fs.rmSync(abs, { recursive: true, force: false });
+      else fs.unlinkSync(abs);
+      removed += 1;
+      row.state = 'removed';
+    } catch (e) {
+      row.state = 'refused';
+      row.why = 'remove-failed';
+      row.error = e && e.code ? e.code : 'error';
+    }
+  }
+  plan.removed = removed;
+  return removed;
+}
+
+/** The rows every writer prints. `phase` is `'preview'` (before the first write) or `'result'`
+ * (after apply; the default). `cleanup` false → `[stale] …; remove with --cleanup` in both phases.
+ * `cleanup` true → the preview says `; will be removed`; after apply, `[removed]` for what went,
+ * `[refused]` for what was never removable, and `— NOT removed (changed since the plan)` only for a
+ * row apply skipped because it changed between plan and apply (hotfix-v1.17.5: the preview used to
+ * print that last wording, contradicting the `[removed]` row the same run printed next). Empty when
+ * nothing catalogued is present. */
+export function renderRetiredArtifactRows(plan, { cleanup, phase = 'result' }) {
+  const out = [];
+  for (const r of plan.rows) {
+    const size = r.kind === 'dir' && typeof r.entries === 'number' ? ` [${r.entries} entr${r.entries === 1 ? 'y' : 'ies'}]` : '';
+    if (r.state === 'stale') {
+      const tail = !cleanup ? '; remove with --cleanup'
+        : phase === 'preview' ? '; will be removed'
+          : ' — NOT removed (changed since the plan)';
+      out.push(`  [stale] ${r.relPath}${size} — retired in v${r.retired_in} (${r.reason})${tail}`);
+    } else if (r.state === 'removed') {
+      out.push(`  [removed] ${r.relPath}${size} — retired in v${r.retired_in}`);
+    } else if (r.why === 'referenced' && r.refs) {
+      out.push(`  [refused] ${r.relPath} — still referenced by ${r.refs.join(', ')} — left alone`);
+    } else if (r.why === 'referenced') {
+      out.push(`  [refused] ${r.relPath} — still named by a hook command in .claude/settings*.json — left alone`);
+    } else if (r.why === 'scan-incomplete') {
+      out.push(`  [refused] ${r.relPath} — the reference scan could not finish (${r.detail}) — left alone`);
+    } else if (r.why === 'remove-failed') {
+      out.push(`  [refused] ${r.relPath} — removal failed (${r.error}) — left in place`);
+    } else if (r.why === 'settings-unreadable') {
+      out.push(`  [refused] ${r.relPath} — .claude/settings*.json does not parse, so its hook wiring is unknown — left alone`);
+    } else {
+      out.push(`  [refused] ${r.relPath} — present but not a regular ${r.kind} (a link, or the other kind) — left alone`);
+    }
+  }
+  return out;
+}

package/src/update.mjs

@@ -7,7 +7,7 @@
 // machinery run.mjs's create path already uses (cli/src/reconcile.mjs, cli/src/floorReconcile.mjs).
 import fs from 'node:fs';
 import path from 'node:path';
-import { RefusalError, physicalResolve } from './util.mjs';
+import { RefusalError, physicalResolve, confinedJoin } from './util.mjs';
 import { loadMap, buildSettings } from './permissionFloor.mjs';
 import { buildManagedFiles } from './scaffold.mjs';
 import { planManagedFiles, applyPlan } from './reconcile.mjs';
@@ -19,6 +19,8 @@ import { planAmendmentsBackfill, applyAmendmentsBackfill, renderAmendmentsRow }
 import { buildUpgradeReport, writeUpgradeReport, installedVersionBefore, versionOrNull, NEXT_LINE } from './upgradeReport.mjs';
 import { planStatuslineWiring, applyStatuslineWiring, renderStatuslineRows, statuslineChanged } from './statuslineWiring.mjs';
 import { policyPresent, missingSelfGuardDeny, applySelfGuardDeny, renderSelfGuardRow, selfGuardShapeOk } from './selfGuardDeny.mjs';
+import { loadRetiredCatalogue, planRetiredArtifacts, applyRetiredArtifacts, renderRetiredArtifactRows } from './retiredArtifacts.mjs';
+import { planRetirements, applyRetirements, askRootKeys } from './floorReconcile.mjs';
 import {
   ALLOWED_CLAUDE_SUBCOMMANDS, resolveClaudeOnPath, runClaude,
   defaultScopes, snapshotScopes, classifyMigration, migrationActions, migrateScope,
@@ -48,6 +50,29 @@ export function parseUpdateArgv(argv) {
  * itself defines (marketplace-refresh, plugin-update, reinitialization); the full orchestrator
  * below may print a fourth `cleanup` row once the sibling atom's phase is wired in, which is a
  * property of the RUNTIME composition, not of this formatter's own contract. */
+/** hotfix-v1.17.4 (ER #236): the retirement-only plan over `.claude/settings.local.json`, which the
+ * tracked-file reconcile never reads. Read-only; `{ rel, abs, plan, error }` — `plan` null when the
+ * file is absent, not a regular file, or resolves outside the root; `error` set when it exists but
+ * does not parse (reported, never guessed). A pinned `ask` row is retired only when the TRACKED file
+ * carries the replacing wildcard row (`askCoveredBy`; PR #237 security review Risk 3). */
+function planLocalRetirement({ physicalRoot, map, trackedSettingsObj }) {
+  const rel = '.claude/settings.local.json';
+  const abs = confinedJoin(physicalRoot, rel);
+  if (!abs) return { rel, abs: null, plan: null, error: 'resolves outside the workspace' };
+  try {
+    if (!fs.lstatSync(abs).isFile()) return { rel, abs, plan: null, error: 'not a regular file' };
+  } catch (e) {
+    return { rel, abs, plan: null, error: e && e.code === 'ENOENT' ? null : e.message };
+  }
+  try {
+    const settingsObj = readTarget(abs);
+    const askCoveredBy = trackedSettingsObj ? askRootKeys(trackedSettingsObj, map) : new Set();
+    return { rel, abs, settingsObj, plan: planRetirements({ settingsObj, map, askCoveredBy }), error: null };
+  } catch (e) {
+    return { rel, abs, plan: null, error: e.message };
+  }
+}
+
 export function renderSummary(phases) {
   const lines = ['Summary:'];
   for (const p of phases) {
@@ -230,6 +255,18 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     if (previewAmendmentsRow) previewLines.push(previewAmendmentsRow);
     // statusline-wiring (AC-SLW-1/-2): PREVIEW-ONLY rows; Phase 4 re-plans fresh from disk.
     previewLines.push(...renderStatuslineRows(planStatuslineWiring({ physicalRoot, templatesDir })));
+    // retired-artifacts (hotfix-v1.17.4, ER #236): PREVIEW-ONLY rows; Phase 4 re-plans fresh from disk.
+    const retiredCatalogue = loadRetiredCatalogue(pkgDir);
+    previewLines.push(...renderRetiredArtifactRows(planRetiredArtifacts({ physicalRoot, catalogue: retiredCatalogue }), { cleanup: flags.cleanup, phase: 'preview' }));
+    // settings.local.json retirement (hotfix-v1.17.4): PREVIEW-ONLY row (PR #237 review Risk 2 —
+    // every Phase 4 write is announced before the first write happens); Phase 4 re-plans fresh.
+    {
+      const lp = planLocalRetirement({
+        physicalRoot, map, trackedSettingsObj: floorTarget.present ? readTarget(floorTarget.path) : null,
+      });
+      if (lp.plan && lp.plan.total > 0) previewLines.push(`  [permission-floor] ${lp.rel}: would retire allow=${lp.plan.retirements.allow.length}, ask=${lp.plan.retirements.ask.length} (never adds)`);
+      else if (lp.error) previewLines.push(`  [permission-floor] ${lp.rel}: would not be reconciled (${lp.error})`);
+    }
     print(previewLines.join('\n'));
 
     const env = { ...spawnEnv, CLAUDE_CONFIG_DIR: configDir };
@@ -348,10 +385,40 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     const statuslinePlan = planStatuslineWiring({ physicalRoot, templatesDir });
     applyStatuslineWiring(statuslinePlan);
     for (const row of renderStatuslineRows(statuslinePlan)) print(row);
+    // retired-artifacts (hotfix-v1.17.4, ER #236): re-planned FRESH from disk; reported every run,
+    // removed only under --cleanup, only catalogued paths of the catalogued kind, never a hook a
+    // settings hook command still names.
+    const retiredPlan = planRetiredArtifacts({ physicalRoot, catalogue: retiredCatalogue });
+    let retiredRemoved = 0;
+    if (flags.cleanup && retiredPlan.present > 0) retiredRemoved = applyRetiredArtifacts(retiredPlan, physicalRoot);
+    for (const row of renderRetiredArtifactRows(retiredPlan, { cleanup: flags.cleanup })) print(row);
+
+    // settings.local.json (hotfix-v1.17.4): the tracked-file reconcile never reads it, so a
+    // version-pinned floor row an old init left there survived every upgrade. Only RETIREMENT is
+    // applied here (never additions — the local file is the operator's), with the same planner and
+    // the same never-clobber, mode-preserving write as the tracked file. The tracked file is re-read
+    // AFTER its own write above, so an `ask` row is retired only when the wildcard row that replaces
+    // it is really there (Risk 3); confined like every other path (Risk 4).
+    let localRetired = 0;
+    {
+      const lp = planLocalRetirement({
+        physicalRoot, map,
+        trackedSettingsObj: freshFloorTarget.present ? readTarget(freshFloorTarget.path) : null,
+      });
+      if (lp.plan && lp.plan.total > 0) {
+        writeTargetAtomically(lp.abs, applyRetirements(lp.settingsObj, lp.plan));
+        localRetired = lp.plan.total;
+        for (const tier of ['allow', 'ask']) for (const r of lp.plan.retirements[tier]) print(`  [retired] ${lp.rel}: ${r}`);
+        print(`  [permission-floor] ${lp.rel}: retired ${localRetired} version-pinned/gone row(s)`);
+      } else if (lp.error) {
+        print(`  [permission-floor] ${lp.rel}: not reconciled (${lp.error})`);
+      }
+    }
+
     phases.push({
       name: 'reinitialization',
       verdict: anyCreated || anyFloorAdded || anyGitignoreChanged || anyAmendmentsBackfilled
-        || statuslineChanged(statuslinePlan) ? 'changed' : 'already current',
+        || statuslineChanged(statuslinePlan) || retiredRemoved > 0 || localRetired > 0 ? 'changed' : 'already current',
     });
 
     print('');
@@ -363,6 +430,8 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     const report = buildUpgradeReport({
       installedBefore, afterEntry, toPluginVersion: pins.plugin_version, phases, filePlan, amendmentsPlan,
       updaterVersion, coreVersion: corePkg.version, updaterPluginVersion: pins.plugin_version,
+      retiredArtifacts: { present: retiredPlan.rows.filter((r) => r.state === 'stale').map((r) => r.relPath), removed: retiredRemoved, refused: retiredPlan.refused },
+      localRetired,
     });
     const reportPath = writeUpgradeReport(physicalRoot, report);
     print('');

package/src/upgradeReport.mjs

@@ -32,6 +32,7 @@ export function versionOrNull(v) {
 export function buildUpgradeReport({
   installedBefore = null, afterEntry, toPluginVersion, phases, filePlan, amendmentsPlan, now = new Date(),
   updaterVersion = null, coreVersion = null, updaterPluginVersion = null,
+  retiredArtifacts = null, localRetired = 0,
 }) {
   const seedRow = (filePlan || []).find((f) => f.seed);
   return {
@@ -57,6 +58,11 @@ export function buildUpgradeReport({
       : { backfilled: 0, present: 0, skipped: 0, total: 0 },
     permissions_policy: seedRow ? (seedRow.action === 'create' ? 'created' : 'kept') : 'absent',
     drifted: (filePlan || []).filter((f) => f.action === 'drifted').map((f) => f.relPath),
+    // hotfix-v1.17.4: what the sweep found (paths are workspace-relative catalogue entries, never free text)
+    retired_artifacts: retiredArtifacts
+      ? { present: retiredArtifacts.present, removed: retiredArtifacts.removed, refused: retiredArtifacts.refused }
+      : { present: [], removed: 0, refused: 0 },
+    settings_local_retired: localRetired,
   };
 }