create-agentic-workspace 0.17.4 → 0.17.5

package/package.json

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

package/retired-artifacts.json

@@ -1,12 +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.",
+  "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 script reads it" },
+    { "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" },

package/src/retiredArtifacts.mjs

@@ -3,7 +3,9 @@
 // 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
+// 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';
@@ -19,6 +21,13 @@ export function loadRetiredCatalogue(pkgDir) {
   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)}`);
@@ -92,6 +101,72 @@ function hookCommandText(physicalRoot) {
   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
@@ -101,6 +176,7 @@ function hookCommandText(physicalRoot) {
 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);
@@ -127,6 +203,21 @@ export function planRetiredArtifacts({ physicalRoot, catalogue }) {
         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; }
       }
@@ -161,28 +252,42 @@ export function applyRetiredArtifacts(plan, physicalRoot) {
       else fs.unlinkSync(abs);
       removed += 1;
       row.state = 'removed';
-    } catch {
+    } 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. `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 }) {
+/** 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') {
-      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`);
+      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 {

package/src/update.mjs

@@ -257,7 +257,7 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     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 }));
+    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.
     {