create-agentic-workspace 0.17.2 → 0.17.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-workspace",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "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.2",
+    "plugin_version": "1.17.4",
     "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.2",
+  "generated_for_plugin_version": "1.17.4",
   "entries": [
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-acceptance-contract-validate.py:*)",

package/retired-artifacts.json

@@ -0,0 +1,22 @@
+{
+  "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.",
+  "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 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

@@ -213,6 +213,45 @@ export function parseFloorRootShape(rule, pluginRootGlob) {
   return { name: m[1], sub: m[2] ?? null };
 }
 
+/** The floor's root-glob shape with every `*` segment of the glob allowed to be a CONCRETE
+ * segment instead (`cache/agentic-foundry/foundry/1.9.1/scripts/<name>[ <sub>]:*`) — the shape an
+ * init before installer-unpinning (v1.7.0) wrote, with the marketplace directory and the plugin
+ * version spelled out. hotfix-v1.17.3: such rows are stale by construction (the floor has written
+ * only version-wildcarded rows since; the wildcard row the reconcile adds in the same pass covers
+ * the script), and because they never matched the exact-shape regex above, nothing ever retired
+ * them — an adopter carried `1.9.1` allow rows across eight releases. `*` in the glob becomes
+ * `([^/]+)`; a row whose captured segments are ALL literal `*` is the exact shape (handled above),
+ * so this parser reports `pinned: true` only when at least one segment is concrete. */
+function floorPinnedShapeRe(pluginRootGlob) {
+  // PR #233 security review Risk 2: every `*` but the last (the marketplace directory) may be a
+  // plain name (no dots — so `..` and an operator's partial glob like `1.*` never qualify) or the
+  // literal `*`; the LAST `*` (the plugin version) may be a semver-shaped segment or `*`. A rule
+  // from a foreign marketplace still matches by shape (the name is not the floor's to know here),
+  // but only for the tiers and conditions planRetirements allows.
+  const stars = (pluginRootGlob.match(/\*/g) || []).length;
+  let seen = 0;
+  const src = escapeLiteral(pluginRootGlob).replace(/\\\*/g, () => {
+    seen += 1;
+    return seen === stars ? '(\\*|\\d+\\.\\d+\\.\\d+[A-Za-z0-9.+-]*)' : '(\\*|[A-Za-z0-9_-]+)';
+  });
+  return new RegExp(`^Bash\\(${src}/scripts/(${ROOT_SHAPE_NAME_RE})(?: (.+))?:\\*\\)$`);
+}
+
+/** Parse `rule` as a version-/marketplace-PINNED variant of the floor's own row shape. Returns
+ * `{ name, sub, pinned: true }` when at least one glob segment is concrete in the row, `null` for
+ * the exact wildcard shape (parseFloorRootShape's business) and for every other shape. Exported for
+ * the fixture tests. */
+export function parseFloorPinnedShape(rule, pluginRootGlob) {
+  if (typeof pluginRootGlob !== 'string' || pluginRootGlob === '') return null;
+  const stars = (pluginRootGlob.match(/\*/g) || []).length;
+  if (stars === 0) return null;
+  const m = floorPinnedShapeRe(pluginRootGlob).exec(rule);
+  if (!m) return null;
+  const segs = m.slice(1, 1 + stars);
+  if (segs.every((x) => x === '*')) return null;
+  return { name: m[1 + stars], sub: m[2 + stars] ?? null, pinned: true };
+}
+
 /** A collision-free key for the `(name, sub)` pair — `JSON.stringify` of a 2-tuple rather than a
  * string concatenation with a hand-picked separator, which a `sub` containing that exact separator
  * (an unlikely but not-impossible flag value) could otherwise fold into a DIFFERENT pair's key. */
@@ -233,21 +272,61 @@ 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) {
+    if (e.tier !== 'ask') continue;
+    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']) {
     for (const rule of perms[tier] || []) {
       const parsed = parseFloorRootShape(rule, map.plugin_root_glob);
-      if (!parsed) continue; // not the floor's own shape at all -> never touched (AC-FRR-2)
-      if (!shipped.has(rootNameKey(parsed))) retirements[tier].push(rule);
+      if (parsed) {
+        if (!shipped.has(rootNameKey(parsed))) retirements[tier].push(rule);
+        continue;
+      }
+      // hotfix-v1.17.3: a version-/marketplace-pinned variant of the floor's own shape. An `allow`
+      // row is retired whether or not the script still ships — the wildcard row covers a shipped
+      // script (added in this same pass when absent), and a pinned row for a gone script is exactly
+      // the ER #199 class. An `ask` row is retired ONLY when the shipped map declares the same
+      // (name, sub) at `ask`, so the wildcard `ask` row replaces it (PR #233 security review Risk 1:
+      // `ask` beats `allow`, so dropping an ask row under a broader allow would turn a prompt into a
+      // silent grant — a widening this pass must never perform).
+      const pinned = parseFloorPinnedShape(rule, map.plugin_root_glob);
+      if (pinned) {
+        if (tier === 'allow') retirements[tier].push(rule);
+        else if (askReplaced(rootNameKey(pinned))) retirements[tier].push(rule);
+      }
+      // any other shape -> never touched (AC-FRR-2)
     }
   }
   const total = retirements.allow.length + retirements.ask.length;
@@ -378,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/permissionFloor.mjs

@@ -4,6 +4,7 @@
 // (AC-BCL-8). `covers()` agrees with tests/test_permission_floor_map.py::_subsumes on the shared
 // 8-row table by construction (same prefix-subsumption rule).
 import fs from 'node:fs';
+import { SELF_GUARD_DENY } from './selfGuardDeny.mjs';
 import os from 'node:os';
 
 /** The one map schema_version this build understands. A map declaring anything else is refused
@@ -214,6 +215,10 @@ export function buildSettings(map, pins) {
   for (const e of map.entries) {
     byTier[e.tier].push(e.rule);
   }
+  // hotfix-v1.17.3: the policy file's own self-guard pair rides with the floor on the create path
+  // (the scaffold seeds .foundry/permissions.yaml in the same run), so a fresh workspace is in-sync
+  // instead of `policy drift (2)` until someone runs the compiler.
+  for (const r of SELF_GUARD_DENY) if (!byTier.deny.includes(r)) byTier.deny.push(r);
   // THE PINNED LITERAL — SUPERSEDED (feat-foundry-installer-unpinning, AC-IUP-3). This block used
   // to read (AC-BCL-4(b), contract v1.2 — PR #61 security review Block 1), verbatim:
   //

package/src/retiredArtifacts.mjs

@@ -0,0 +1,193 @@
+// 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. 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');
+  }
+  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 };
+}
+
+/** 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
+  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' && 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 {
+      row.state = 'refused';
+    }
+  }
+  plan.removed = removed;
+  return removed;
+}
+
+/** The rows every writer prints. `cleanup` false → `[stale]` (nothing removed); true → `[removed]`
+ * for what went, `[refused]` for what did not. Empty when nothing catalogued is present. */
+export function renderRetiredArtifactRows(plan, { cleanup }) {
+  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') {
+      out.push(cleanup
+        ? `  [stale] ${r.relPath}${size} — retired in v${r.retired_in} (${r.reason}) — NOT removed`
+        : `  [stale] ${r.relPath}${size} — retired in v${r.retired_in} (${r.reason}); remove with --cleanup`);
+    } else if (r.state === 'removed') {
+      out.push(`  [removed] ${r.relPath}${size} — retired in v${r.retired_in}`);
+    } 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 === '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/run.mjs

@@ -20,6 +20,7 @@ import {
 import { reconcileGitignorePlan, applyGitignorePlan, renderGitignoreRow } from './gitignoreReconcile.mjs';
 import { planAmendmentsBackfill, applyAmendmentsBackfill, renderAmendmentsRow } from './amendmentsBackfill.mjs';
 import { planStatuslineWiring, applyStatuslineWiring, renderStatuslineRows } from './statuslineWiring.mjs';
+import { policyPresent, missingSelfGuardDeny, applySelfGuardDeny, renderSelfGuardRow, selfGuardShapeOk } from './selfGuardDeny.mjs';
 
 export { DECLARED_PATH_SET };
 
@@ -253,8 +254,18 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
     // permission floor unattended; --yes must be given EXPLICITLY. This sits above applyPlan
     // deliberately — a "refused" verdict printed after the scaffold write had already landed reads
     // as "nothing happened", which is the one thing it must not mean.
+    // hotfix-v1.17.3 (PR #233 review Risk 4): the self-guard pair is previewed here and counts as
+    // floor work, so a piped run cannot write it without an explicit --yes and --dry-run names it.
+    let selfGuardPreview = { missing: [], shapeOk: true };
+    if (answers.reconcileFloor && floorTarget && floorTarget.present && policyPresent(physicalRoot)) {
+      const cur0 = readTarget(floorTarget.path);
+      selfGuardPreview = { missing: missingSelfGuardDeny(cur0), shapeOk: selfGuardShapeOk(cur0) };
+      const prow = renderSelfGuardRow(physicalRoot, selfGuardPreview.missing.length, { shapeOk: selfGuardPreview.shapeOk, applied: false });
+      if (prow) print(prow);
+    }
     const floorHasWork = Boolean(floorPlan)
-      && (floorPlan.total > 0 || (floorRetirementPlan && floorRetirementPlan.total > 0));
+      && (floorPlan.total > 0 || (floorRetirementPlan && floorRetirementPlan.total > 0)
+          || selfGuardPreview.missing.length > 0);
     if (floorHasWork && !isTTY && answers.yes !== true) {
       throw new RefusalError(
         'refusing --reconcile-floor without a terminal: pass --yes explicitly to confirm the write',
@@ -297,6 +308,17 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
         applied: true, retirementPlan: floorRetirementPlan, mapEntryCount: map.entries.length,
       })) print(line);
     }
+    // hotfix-v1.17.3 (ER #232): under --reconcile-floor (the one opt-in that permits a narrow
+    // settings write on --existing), converge the policy file's self-guard deny pair, fresh from
+    // disk after the floor write, whenever a policy file exists.
+    if (answers.reconcileFloor && floorTarget && floorTarget.present && policyPresent(physicalRoot)) {
+      const cur = readTarget(floorTarget.path);
+      const shapeOk = selfGuardShapeOk(cur);
+      const missing = missingSelfGuardDeny(cur);
+      if (shapeOk && missing.length > 0) writeTargetAtomically(floorTarget.path, applySelfGuardDeny(cur));
+      const row = renderSelfGuardRow(physicalRoot, missing.length, { shapeOk });
+      if (row) print(row);
+    }
     // AFTER the floor write above: that write serialises a settings object read before this
     // point, so wiring the statusLine keys first would have been overwritten by it. The wiring
     // re-reads settings.json itself and adds only the absent keys (AC-SLW-2).

package/src/selfGuardDeny.mjs

@@ -0,0 +1,75 @@
+// selfGuardDeny.mjs — the two framework-owned deny rules that protect the operator's policy file
+// (hotfix-v1.17.3, ER #232): `Edit(.foundry/permissions.yaml)` and `Write(.foundry/permissions.yaml)`.
+//
+// They are what `scripts/foundry-permissions-compile.py --write` derives for a policy with ZERO grants
+// (its SELF_GUARD pair) — no operator judgement is in them, so every writer that seeds or keeps the
+// policy file converges them too, and a fresh seed is in-sync instead of `policy drift (2)` until
+// someone remembers the compiler. Grants stay the compiler's (operator-run) business.
+//
+// Discipline: add-if-absent onto `permissions.deny`, never reorder or remove anything, never touch
+// another key; a settings object without a `permissions` block gains one with only `deny`.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const POLICY_REL = '.foundry/permissions.yaml';
+export const SELF_GUARD_DENY = Object.freeze([
+  `Edit(${POLICY_REL})`,
+  `Write(${POLICY_REL})`,
+]);
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** `true` when `settingsObj.permissions` is absent or a plain object whose `deny`, if present, is an
+ * array — the only shapes this module will write into. Anything else is refused rather than
+ * guessed (PR #233 security review Risk 3: a string `deny` would otherwise be spread into
+ * characters and written back). */
+export function selfGuardShapeOk(settingsObj) {
+  if (!isPlainObject(settingsObj)) return false;
+  const perms = settingsObj.permissions;
+  if (perms === undefined) return true;
+  if (!isPlainObject(perms)) return false;
+  return perms.deny === undefined || Array.isArray(perms.deny);
+}
+
+/** Which of the two rules `settingsObj` still lacks. Pure. Returns [] for a shape this module will
+ * not write into (see selfGuardShapeOk) — the caller reports that separately. */
+export function missingSelfGuardDeny(settingsObj) {
+  if (!selfGuardShapeOk(settingsObj)) return [];
+  const deny = (settingsObj.permissions && settingsObj.permissions.deny) || [];
+  return SELF_GUARD_DENY.filter((r) => !deny.includes(r));
+}
+
+/** A NEW settings object with the missing rules appended to `permissions.deny`. Pure; returns the
+ * input unchanged for a shape it will not write into. */
+export function applySelfGuardDeny(settingsObj) {
+  if (!selfGuardShapeOk(settingsObj)) return settingsObj;
+  const missing = missingSelfGuardDeny(settingsObj);
+  if (missing.length === 0) return settingsObj;
+  const next = { ...settingsObj };
+  next.permissions = { ...(next.permissions || {}) };
+  next.permissions.deny = [...(next.permissions.deny || []), ...missing];
+  return next;
+}
+
+/** `true` when the policy file exists as a regular file under `physicalRoot` (seeded or kept) — the
+ * rules guard a file, so they are written only when there is one. Never follows a symlink. */
+export function policyPresent(physicalRoot) {
+  try {
+    return fs.lstatSync(path.join(physicalRoot, POLICY_REL)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** The one row every writer prints: `[permissions] self-guard deny rules added (N)` or
+ * `already present`. `null` when there is no policy file to guard (nothing to say). */
+export function renderSelfGuardRow(physicalRoot, addedCount, { shapeOk = true, applied = true } = {}) {
+  if (!policyPresent(physicalRoot)) return null;
+  if (!shapeOk) return '  [permissions] settings.permissions is not the shape expected (object with an array deny) — self-guard deny rules NOT written';
+  if (addedCount > 0) {
+    return applied
+      ? `  [permissions] self-guard deny rules added (${addedCount}): Edit/Write on ${POLICY_REL}`
+      : `  [permissions] would add self-guard deny rules (${addedCount}): Edit/Write on ${POLICY_REL}`;
+  }
+  return '  [permissions] self-guard deny rules already present';
+}

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';
@@ -18,6 +18,9 @@ import { reconcileGitignorePlan, applyGitignorePlan, renderGitignoreRow } from '
 import { planAmendmentsBackfill, applyAmendmentsBackfill, renderAmendmentsRow } from './amendmentsBackfill.mjs';
 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,
@@ -47,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) {
@@ -211,6 +237,13 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
       if (previewRetirementPlan && previewRetirementPlan.total > 0) {
         previewLines.push(`  [permission-floor] would retire allow=${previewRetirementPlan.retirements.allow.length}, ask=${previewRetirementPlan.retirements.ask.length}`);
       }
+      // hotfix-v1.17.3 (PR #233 review Risk 4): the self-guard pair is previewed like the floor.
+      if (policyPresent(physicalRoot) || filePlan.some((f) => f.seed && f.action === 'create')) {
+        const cur0 = readTarget(floorTarget.path);
+        const prow = renderSelfGuardRow(physicalRoot, missingSelfGuardDeny(cur0).length, { shapeOk: selfGuardShapeOk(cur0), applied: false });
+        if (prow) previewLines.push(prow);
+        else previewLines.push('  [permissions] would add self-guard deny rules (2): Edit/Write on .foundry/permissions.yaml (with the seed)');
+      }
     } else {
       previewLines.push('  [permission-floor] .claude/settings.json absent — left to the create path');
     }
@@ -222,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 }));
+    // 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 };
@@ -293,6 +338,17 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
           applied: true, retirementPlan: floorRetirementPlan, mapEntryCount: map.entries.length,
         })) print(line);
       }
+      // hotfix-v1.17.3 (ER #232): the policy file's self-guard deny pair is framework-owned — converge
+      // it here, fresh from disk after the floor write, whenever a policy file exists (seeded above or
+      // kept). Grants stay the compiler's (operator-run) business.
+      if (policyPresent(physicalRoot)) {
+        const cur = readTarget(freshFloorTarget.path);
+        const shapeOk = selfGuardShapeOk(cur);
+        const missing = missingSelfGuardDeny(cur);
+        if (shapeOk && missing.length > 0) writeTargetAtomically(freshFloorTarget.path, applySelfGuardDeny(cur));
+        const row = renderSelfGuardRow(physicalRoot, missing.length, { shapeOk });
+        if (row) print(row);
+      }
     }
     // Recomputed FRESH from disk, same reasoning as floorPlan just above: never apply a plan
     // captured before Phases 1-3 ran, even though `.gitignore` is not itself a migration target.
@@ -329,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('');
@@ -344,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,
   };
 }