create-agentic-workspace 0.3.1 → 0.4.0

package/package.json

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

package/src/floorReconcile.mjs

@@ -0,0 +1,233 @@
+// floorReconcile.mjs — feat-foundry-adoption-permission-floor-reconcile.
+//
+// The wizard already computes the whole answer for an existing workspace and refuses to act on it:
+// it ships the floor as a bundled constant, reads the target's effective rules, and names every
+// missing rule — then reports and writes nothing, because settings.json goes through the whole-file
+// never-clobber plan (exists and differs -> `drifted` -> untouched). Five of seven adopter
+// handbooks are missing the entire floor as a result.
+//
+// This module converges the target's `permissions` block by ADDING the rules the classifier named.
+// Nothing is removed, nothing is reordered. The desired state is the shipped constant, the current
+// state is what the classifier reads, and the write is the delta — recomputed every run, which is
+// why no ledger is needed and why a second run is silent.
+//
+// THE WRITE IS THIS CLI'S FIRST TO A PATH THAT ALREADY EXISTS, and every anti-clobber control in
+// the codebase is structurally unavailable to it. `applyPlan` opens O_EXCL, create-only, refusing
+// by definition the case this module is entirely about. So:
+//   - confinedJoin refuses a resolution that ESCAPES the root but PASSES an in-root symlink, and
+//     `.claude/settings.json` symlinked to `.claude/foundry-operators.json` resolves inside it —
+//     onto the file whose key membership alone mints an authorizer. statSync().isFile() returns
+//     true through a symlink; only lstat sees it.
+//   - truncate-then-write loses the operator's whole permissions block AND their install pin on a
+//     ^C or ENOSPC. That is silent loss from a benign cause, which is never-clobber's substance
+//     rather than its letter.
+// One mechanism answers all three: confinement join + LINK-LEVEL stat + temp-in-.claude + rename.
+import fs from 'node:fs';
+import path from 'node:path';
+import { confinedJoin, RefusalError } from './util.mjs';
+import { buildSettings } from './permissionFloor.mjs';
+
+/** The drift classes whose findings name a rule this module may ADD. Everything else the
+ * classifier can emit is report-only: blanket-allow, ask-shadowed, ask-shadowed-ceremony and
+ * tier-conflict each need a REMOVAL or a narrowing to close, which is a different and strictly
+ * more dangerous capability than adding a rule from a shipped constant. An allowlist, not a
+ * denylist — a class added to the vocabulary later defaults to not being written. */
+export const ADDITIVE_CLASSES = Object.freeze(['allow-absent', 'ask-absent', 'deny-missing']);
+
+const TIER_OF_CLASS = Object.freeze({
+  'allow-absent': 'allow',
+  'ask-absent': 'ask',
+  'deny-missing': 'deny',
+});
+
+/** Read the target's TRACKED settings.json only. Deliberately not the union with
+ * settings.local.json: a floor rule carried only in the untracked file reads as covered, so the
+ * tracked file would stay incomplete while the report says converged — sharpest for `deny`, where
+ * the repo then ships to every other clone and to CI without it. The union is still what the
+ * REPORT is computed over; only the write set is narrowed. */
+export function readTrackedRules(settingsObj) {
+  const perms = (settingsObj && settingsObj.permissions) || {};
+  const out = { allow: [], ask: [], deny: [] };
+  for (const tier of ['allow', 'ask', 'deny']) {
+    for (const rule of perms[tier] || []) out[tier].push({ rule, origin: 'settings.json', tierKey: tier });
+  }
+  return out;
+}
+
+/** Does this target carry a foundry marketplace entry, and is it pinned?
+ *
+ * Load-bearing, and easy to miss. Every bundled `allow` rule is wildcarded across the plugin cache,
+ * so the grant is bounded only by the pinned marketplace ref + autoUpdate:false that the create
+ * path writes IN THE SAME FILE, IN THE SAME WRITE. Adding the allow rules alone would convert one
+ * trust acceptance into a standing grant over whatever a future resolution drops into that cache
+ * path. Six of the seven adopter handbooks carry no marketplace entry at all. */
+export function classifyPin(settingsObj, pins) {
+  const entry = ((settingsObj && settingsObj.extraKnownMarketplaces) || {})[pins.marketplace_name];
+  if (entry === undefined) return { state: 'absent', ref: null, skew: false };
+  const ref = entry && entry.source && entry.source.ref;
+  const pinned = typeof ref === 'string' && ref !== '' && !ref.includes('*') && entry.autoUpdate === false;
+  // A pin can be perfectly well-formed and still name a DIFFERENT plugin than the map these rules
+  // came from. The 42 allow rules are wildcarded across the cache and their per-script rationales
+  // were reviewed against THIS version's scripts; writing them over a workspace pinned at an older
+  // one grants the same paths against different code. Surfaced rather than refused — the operator's
+  // review of the plan is the control, and it can only work if the skew is on screen.
+  const skew = pinned && ref !== `v${pins.plugin_version}`;
+  return { state: pinned ? 'pinned' : 'unpinned', ref: typeof ref === 'string' ? ref : null, skew };
+}
+
+/** Compute the delta WITHOUT touching the filesystem. Returns
+ * { additions: {allow,ask,deny}, total, pin, withheldAllow, blanket }.
+ *
+ * `findings` is classifyDrift's output over the TRACKED rules; `map` supplies the tier each rule
+ * belongs in — never the finding, and never anything read from the target. */
+export function planAdditions({ findings, map, settingsObj, pins }) {
+  const tierOfRule = new Map(map.entries.map((e) => [e.rule, e.tier]));
+  const additions = { allow: [], ask: [], deny: [] };
+
+  const pin = classifyPin(settingsObj, pins);
+  // An UNPINNED existing entry withholds the allow tier only. ask and deny are strengthening —
+  // more prompting, more blocking — so holding them hostage to the pin would leave the floor worse
+  // for no gain. An ABSENT entry is not a refusal: the pin is added alongside the grants, exactly
+  // as the create path emits them together.
+  const withheldAllow = pin.state === 'unpinned';
+
+  for (const f of findings) {
+    if (!ADDITIVE_CLASSES.includes(f.class)) continue;
+    const tier = tierOfRule.get(f.rule);
+    // the tier comes from the map; a finding naming a rule the map does not declare is not ours
+    if (tier === undefined || tier !== TIER_OF_CLASS[f.class]) continue;
+    if (tier === 'allow' && withheldAllow) continue;
+    if (!additions[tier].includes(f.rule)) additions[tier].push(f.rule);
+  }
+
+  // preserve bundled-map order so two runs over the same input produce the same diff
+  for (const tier of ['allow', 'ask', 'deny']) {
+    const order = map.entries.filter((e) => e.tier === tier).map((e) => e.rule);
+    additions[tier].sort((a, b) => order.indexOf(a) - order.indexOf(b));
+  }
+
+  const total = additions.allow.length + additions.ask.length + additions.deny.length;
+  const blanket = findings.filter((f) => f.class === 'blanket-allow').map((f) => f.rule);
+  return { additions, total, pin, withheldAllow, blanket, pinsVersion: pins.plugin_version };
+}
+
+/** Apply a plan to a parsed settings object, returning a NEW object. Pure — no I/O.
+ *
+ * Additive by construction: every pre-existing rule keeps its text, its tier and its position
+ * relative to the other pre-existing rules of that tier, because new rules are appended and the
+ * prior array is copied in order. No input can express a removal — the rules come from the bundled
+ * map and the only operation is append. */
+export function applyAdditions(settingsObj, plan, { map, pins }) {
+  const next = { ...settingsObj };
+  const perms = { ...(settingsObj.permissions || {}) };
+  for (const tier of ['allow', 'ask', 'deny']) {
+    const existing = Array.isArray(perms[tier]) ? perms[tier] : [];
+    perms[tier] = plan.additions[tier].length > 0 ? [...existing, ...plan.additions[tier]] : existing;
+  }
+  next.permissions = perms;
+
+  if (plan.pin.state === 'absent') {
+    // Taken from buildSettings — the SAME function the create path uses, over the same map and the
+    // same pins — rather than re-spelling the entry here. A second copy of that literal is how the
+    // pin drifts from what a fresh scaffold writes. Only its marketplace block is used; the
+    // permissions it also builds are irrelevant here and discarded.
+    const created = buildSettings(map, pins);
+    next.extraKnownMarketplaces = {
+      ...(settingsObj.extraKnownMarketplaces || {}),
+      ...created.extraKnownMarketplaces,
+    };
+  }
+  return next;
+}
+
+/** Resolve the target settings path, refusing anything that is not a regular file inside the root.
+ * lstat, NOT stat: statSync().isFile() follows a symlink, so an in-root link would pass. */
+export function resolveTarget(physicalRoot) {
+  const joined = confinedJoin(physicalRoot, path.join('.claude', 'settings.json'));
+  if (joined === null) {
+    throw new RefusalError('refusing .claude/settings.json: path escapes the target root', '.claude/settings.json');
+  }
+  const st = fs.lstatSync(joined, { throwIfNoEntry: false });
+  if (!st) return { path: joined, present: false };
+  if (!st.isFile()) {
+    throw new RefusalError(
+      `refusing ${joined}: not a regular file (symlink or special file)`,
+      '.claude/settings.json',
+    );
+  }
+  return { path: joined, present: true };
+}
+
+/** Parse the tracked settings file, refusing rather than treating unparseable as empty. Classifying
+ * against an empty rule set and then writing into a file whose keys could not be read would make
+ * the preserve-every-other-key guarantee unimplementable. */
+export function readTarget(targetPath) {
+  const raw = fs.readFileSync(targetPath, 'utf-8');
+  try {
+    const doc = JSON.parse(raw);
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) throw new Error('not an object');
+    return doc;
+  } catch (e) {
+    throw new RefusalError(
+      `refusing ${targetPath}: does not parse as a JSON object (${e.message})`,
+      '.claude/settings.json',
+    );
+  }
+}
+
+/** Install new content by rename. Temp file in the TARGET'S OWN directory so the rename is
+ * same-filesystem and therefore atomic; rename neither follows a symlink at the destination nor
+ * can leave a truncated file, which closes the interrupted-write loss and the classify-to-write
+ * race together — the same argument applyPlan's O_EXCL comment already makes for the create path. */
+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');
+  const fd = fs.openSync(tmp, 'wx');
+  try {
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    fs.renameSync(tmp, targetPath);
+  } catch (e) {
+    fs.rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+/** Render the plan for the operator: every rule that would be added, with its tier, plus the
+ * per-tier counts and any qualifier. Used for both the dry-run report and the post-write one, so
+ * the two cannot describe the same plan differently. */
+export function renderPlan(plan, { applied }) {
+  const lines = [];
+  const verb = applied ? 'added' : 'would add';
+  for (const tier of ['allow', 'ask', 'deny']) {
+    for (const rule of plan.additions[tier]) lines.push(`  [${tier}] ${rule}`);
+  }
+  lines.push(
+    `permission-floor reconcile: ${verb} ` +
+      ['allow', 'ask', 'deny'].map((t) => `${t}=${plan.additions[t].length}`).join(', '),
+  );
+  if (plan.pin.state === 'absent') {
+    lines.push(`  + marketplace pin added — the bundled allow rules are wildcarded across the plugin cache and are bounded only by it`);
+  } else if (plan.pin.state === 'pinned') {
+    // printed on EVERY pinned run, not only the skewed one: an operator cannot notice a mismatch
+    // that is never shown, and this is the branch where 42 grants are written without comment
+    lines.push(
+      `  · marketplace pinned at ${plan.pin.ref}; these rules come from the floor generated for v${plan.pinsVersion}` +
+        (plan.pin.skew ? ' — VERSION SKEW: the same wildcarded paths will resolve to that pin\'s scripts, not this one\'s' : ''),
+    );
+  } else if (plan.withheldAllow) {
+    lines.push(
+      `  ! marketplace entry present but unpinned (ref=${plan.pin.ref === null ? 'none' : plan.pin.ref})` +
+        ' — allow-tier rules WITHHELD; ask and deny still applied. Pin the marketplace, then re-run.',
+    );
+  }
+  for (const rule of plan.blanket) {
+    lines.push(`  ! qualified by blanket allow ${rule} — this rule defeats the floor until it is narrowed`);
+  }
+  return lines;
+}

package/src/permissionFloor.mjs

@@ -4,10 +4,56 @@
 // (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 os from 'node:os';
 
+/** The one map schema_version this build understands. A map declaring anything else is refused
+ * rather than read optimistically — the tier field is load-bearing (it decides which effective tier
+ * an entry is compared against, and which tier a consumer writes it into), so a shape this code
+ * does not know is not a shape it may guess at. */
+export const MAP_SCHEMA_VERSION = 1;
+
+export const TIERS = Object.freeze(['allow', 'ask', 'deny']);
+
+/** Thrown by loadMap for a structurally invalid bundled map. Mirrors the Python floor checker's
+ * FloorMalformed, which is the one condition that reds the doctor rather than reporting advisory. */
+export class MapMalformed extends Error {}
+
+/** Load + VALIDATE the bundled map. Validation is new (AC-FDC-4): this used to parse and return,
+ * with no schema_version check and no tier check — the Python twin already refused an out-of-enum
+ * tier, so the two disagreed on what counted as a loadable map. On the create path a bad tier at
+ * least crashed in buildSettings (`byTier[e.tier].push` on undefined); anything consuming findings
+ * programmatically would instead act on it. */
 export function loadMap(mapPath) {
   const text = fs.readFileSync(mapPath, 'utf-8');
-  return JSON.parse(text);
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch (e) {
+    throw new MapMalformed(`permission-floor map unparseable: ${e.message}`);
+  }
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw new MapMalformed('permission-floor map is not a JSON object');
+  }
+  if (doc.schema_version !== MAP_SCHEMA_VERSION) {
+    throw new MapMalformed(
+      `permission-floor map schema_version ${JSON.stringify(doc.schema_version)} is not the ` +
+        `${MAP_SCHEMA_VERSION} this build understands`,
+    );
+  }
+  if (!Array.isArray(doc.entries) || doc.entries.length === 0) {
+    throw new MapMalformed('permission-floor map missing entries');
+  }
+  for (const e of doc.entries) {
+    if (e === null || typeof e !== 'object' || typeof e.rule !== 'string' || e.rule === '') {
+      throw new MapMalformed('permission-floor map entry has a non-string/empty rule');
+    }
+    if (!TIERS.includes(e.tier)) {
+      throw new MapMalformed(
+        `permission-floor map entry has invalid tier ${JSON.stringify(e.tier)}`,
+      );
+    }
+  }
+  return doc;
 }
 
 const RULE_RE = /^([A-Za-z0-9_-]+)\((.*)\)$/s;
@@ -23,28 +69,110 @@ export function ruleTool(rule) {
   return m ? m[1] : null;
 }
 
-/** covers(A, B): true if the broad rule A's reach (a `:*`-terminated prefix) subsumes rule B's
- * body. Mirrors tests/test_permission_floor_map.py::_subsumes exactly (same prefix rule). */
-export function covers(ruleA, ruleB) {
-  const bodyA = ruleBody(ruleA);
-  if (bodyA === null || !bodyA.endsWith(':*')) return false;
-  const sA = bodyA.slice(0, -2);
-  const bodyB = ruleBody(ruleB);
-  if (bodyB === null) return false;
-  const sB = bodyB.endsWith(':*') ? bodyB.slice(0, -2) : bodyB;
-  return sB.startsWith(sA);
+// --------------------------------------------------------------------------------------------- //
+// canonicalization + the covers relation — AC-DPF-3's fold, ported from the Python floor checker
+// so the two implementations decide coverage the same way (AC-FDC-6).
+//
+// WHY THIS REPLACED A RAW PREFIX MATCH. The previous `covers` compared rule bodies as literal
+// strings. The Python twin canonicalizes first: it drops a leading interpreter word, expands `~/`
+// and `$HOME/` against the real home, and folds away the marketplace/version segments beneath
+// the plugin root. For the input that actually occurs in the wild — the harness's ask-to-allow persist,
+// which writes an ABSOLUTE, version-resolved path into settings.local.json — the two disagreed:
+//
+//   effective  an ABSOLUTE, version-resolved path under the operator's real plugin root
+//   map        the same script named through the map's `~` + wildcard form
+//   python covers -> true          node covers -> false
+//
+// So the CLI reported `allow-absent` for rules the doctor could see were covered. Left alone, the
+// consuming reconcile atom would write ~42 duplicates of rules already effectively present.
+// --------------------------------------------------------------------------------------------- //
+
+const INTERPRETER_WORDS = new Set(['python3', 'python', 'bash', 'sh']);
+
+/** Build the cache-fold pattern from the map's OWN `plugin_root_glob` rather than from a second
+ * hardcoded copy of that path. One source of truth: a map that moves its plugin root cannot leave
+ * a stale fold behind here. Each `*` becomes one non-empty, slash-free segment.
+ *
+ * Absent a glob there is no fold — a caller that does not know where the plugin root lives has no
+ * business guessing at it. classifyDrift always has the map, so the real path always folds. */
+export function foldRegexFromGlob(glob) {
+  if (typeof glob !== 'string' || glob === '') return null;
+  const tail = glob.replace(/^~\//, '').replace(/^\.claude\//, '');
+  const escaped = tail
+    .split('*')
+    .map((seg) => seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('[^/\\s]+');
+  return new RegExp(escaped + '/');
 }
 
-const BLANKET_BODIES = new Set(['*', 'python3 *', 'python3:*']);
+function foldBody(body, home, foldRe) {
+  body = body.trim();
+  const m = /^(\S+)\s+([\s\S]+)$/.exec(body);
+  if (m && INTERPRETER_WORDS.has(m[1])) body = m[2];
+  if (body.startsWith('~/')) body = home.replace(/\/+$/, '') + body.slice(1);
+  else if (body.startsWith('$HOME/')) body = home.replace(/\/+$/, '') + body.slice('$HOME'.length);
+  if (foldRe) {
+    const f = foldRe.exec(body);
+    if (f) body = body.slice(f.index + f[0].length);
+  }
+  return body;
+}
+
+/** Returns { reach, isPrefix }. */
+function splitMarker(body) {
+  if (body === '*') return { reach: '', isPrefix: true };
+  if (body.endsWith(':*')) return { reach: body.slice(0, -2), isPrefix: true };
+  if (body.length >= 2 && body.endsWith('*') && (body[body.length - 2] === ' ' || body[body.length - 2] === '/')) {
+    return { reach: body.slice(0, -2), isPrefix: true };
+  }
+  return { reach: body, isPrefix: false };
+}
 
-/** A blanket effective allow rule: one whose reach swallows the whole map (AC-DPF-3(a)'s named
- * spellings this atom's own controls (g)(h)(i) exercise: `Bash(*)`, `Bash(python3 *)`,
- * `Bash(python3:*)`). */
-export function isBlanketAllow(rule) {
+/** AC-DPF-3's ask/allow-direction fold. Returns null for a rule that does not participate. */
+export function canonicalize(rule, home = os.homedir(), foldRe = null) {
   const body = ruleBody(rule);
-  if (body === null) return false;
-  const stripped = body.endsWith(':*') ? body.slice(0, -2) : body;
-  return BLANKET_BODIES.has(body) || stripped === '' || stripped === '*';
+  if (body === null) return null;
+  const folded = foldBody(body, home, foldRe);
+  const { reach, isPrefix } = splitMarker(folded);
+  const isBlanket = isPrefix && (reach === '' || INTERPRETER_WORDS.has(reach));
+  return { raw: rule, folded, reach, isPrefix, isBlanket, coverageReach: isBlanket ? '' : reach };
+}
+
+function coversCanon(effectiveC, mapC) {
+  if (effectiveC === null || mapC === null) return false;
+  if (effectiveC.isPrefix) return mapC.reach.startsWith(effectiveC.coverageReach);
+  return effectiveC.reach === mapC.reach;
+}
+
+/** Does `effectiveRule` (the broad rule) cover `mapRule` under the ask/allow fold? */
+export function covers(effectiveRule, mapRule, home = os.homedir(), foldRe = null) {
+  return coversCanon(canonicalize(effectiveRule, home, foldRe), canonicalize(mapRule, home, foldRe));
+}
+
+/** AC-DPF-3(b), the DENY direction: no interpreter drop, no plugin-cache fold, and coverage
+ * requires EXACT reach equality rather than a prefix. A deny is a promise about a specific thing;
+ * folding one rule into another would let a broader-looking deny silently stand in for a narrower
+ * one the map actually requires. The Node side previously reused the allow-direction `covers` here,
+ * which is strictly more permissive than the twin. */
+export function canonicalizeIdentity(rule) {
+  const body = ruleBody(rule);
+  if (body === null) return null;
+  return splitMarker(body.trim());
+}
+
+export function denyCovers(effectiveRule, mapRule) {
+  const a = canonicalizeIdentity(effectiveRule);
+  const b = canonicalizeIdentity(mapRule);
+  if (a === null || b === null) return false;
+  return a.reach === b.reach;
+}
+
+/** A blanket effective allow rule: one whose reach swallows the whole map. Derived from the fold
+ * rather than from an enumerated set of spellings — the old hardcoded trio (`Bash(*)`,
+ * `Bash(python3 *)`, `Bash(python3:*)`) missed every other interpreter word the twin folds. */
+export function isBlanketAllow(rule, home = os.homedir(), foldRe = null) {
+  const c = canonicalize(rule, home, foldRe);
+  return c !== null && c.isBlanket;
 }
 
 const SCRIPTS_BASENAME_RE = /scripts\/([A-Za-z0-9_.-]+)/;
@@ -60,6 +188,19 @@ export const DRIFT_CLASSES = Object.freeze([
   'ask-shadowed-ceremony',
   'ask-shadowed',
   'deny-missing',
+  // AC-FDC-1. The `ask` tier was the one absence this vocabulary could not name: ask entries were
+  // checked ONLY for being shadowed, never for being missing. Measured against a real target
+  // a real adopter workspace, the tools reported 46 findings and were silent about 16 more — every
+  // ceremony rule gone, with the floor reading clean on that dimension.
+  'ask-absent',
+  // AC-FDC-2. Every absence test is tier-scoped: it consults only the effective tier matching the
+  // map's declared tier. A map rule the operator deliberately placed in ANOTHER tier was therefore
+  // reported absent while plainly present — and a consumer acting on that would add a second copy,
+  // leaving one capability declared twice under two tiers. Which of the two governs is a
+  // precedence question this tooling deliberately does not model (the shipped
+  // doctor-permission-floor-check residual R3), so the double declaration is REPORTED, never
+  // resolved.
+  'tier-conflict',
   'settings-unreadable',
   'stale-plugin-path',
   'allow-absent',
@@ -115,8 +256,9 @@ export function renderCapabilityLines(map) {
  * directories `plugin_root_glob` expanded to on disk (empty => stale-plugin-path). Returns an
  * array of finding objects `{class, ...}` using exactly the AC-DPF-8 vocabulary — no other class
  * name is ever emitted. */
-export function classifyDrift(map, effective, { pluginRootExpansion = [], unreadableOrigins = [] } = {}) {
+export function classifyDrift(map, effective, { pluginRootExpansion = [], unreadableOrigins = [], home = os.homedir() } = {}) {
   const findings = [];
+  const foldRe = foldRegexFromGlob(map.plugin_root_glob);
 
   for (const origin of unreadableOrigins) {
     findings.push({ class: 'settings-unreadable', origin });
@@ -124,11 +266,14 @@ export function classifyDrift(map, effective, { pluginRootExpansion = [], unread
 
   const shadowedByBlanket = new Set();
   for (const a of effective.allow) {
-    if (isBlanketAllow(a.rule)) {
+    if (isBlanketAllow(a.rule, home, foldRe)) {
       const swallowed = map.entries.filter((e) => e.tier !== 'allow');
       findings.push({
         class: 'blanket-allow',
         rule: a.rule,
+        // the folded reach the blanket decision was actually made on — the same short form the
+        // Python twin renders, so the two name this class identically (AC-FDC-6)
+        folded: canonicalize(a.rule, home, foldRe).folded,
         origin: a.origin,
         swallows: swallowed.map((e) => e.rule),
       });
@@ -136,9 +281,34 @@ export function classifyDrift(map, effective, { pluginRootExpansion = [], unread
     }
   }
 
+  // AC-FDC-2, computed FIRST because it suppresses the absence findings below. A map entry whose
+  // exact rule text sits in a tier other than the one the map declares is PRESENT — deliberately
+  // placed — so reporting it absent would be false, and would invite a consumer to add a duplicate.
+  // Exact text only: `covers()` needs a `:*`-terminated body to match at all, so a cross-tier
+  // duplicate of a non-wildcard rule is invisible to the shadowing tests too, which is precisely
+  // the gap this class closes.
+  const conflicted = new Set();
+  for (const entry of map.entries) {
+    for (const tierKey of TIERS) {
+      if (tierKey === entry.tier) continue;
+      const found = effective[tierKey].filter((e) => e.rule === entry.rule);
+      if (found.length === 0) continue;
+      conflicted.add(entry.rule);
+      findings.push({
+        class: 'tier-conflict',
+        rule: entry.rule,
+        declaredTier: entry.tier,
+        foundTier: tierKey,
+        // AC-FDC-3 — the origin is what lets a consumer separate the tracked settings.json from the
+        // untracked settings.local.json, which the effective set unions together.
+        origins: found.map((e) => e.origin),
+      });
+    }
+  }
+
   for (const entry of map.entries.filter((e) => e.tier === 'ask')) {
     if (shadowedByBlanket.has(entry.rule)) continue;
-    const coveringAllow = effective.allow.filter((a) => covers(a.rule, entry.rule));
+    const coveringAllow = effective.allow.filter((a) => covers(a.rule, entry.rule, home, foldRe));
     if (coveringAllow.length > 0) {
       findings.push({
         class: isCeremonyEntry(entry) ? 'ask-shadowed-ceremony' : 'ask-shadowed',
@@ -149,18 +319,36 @@ export function classifyDrift(map, effective, { pluginRootExpansion = [], unread
   }
 
   for (const entry of map.entries.filter((e) => e.tier === 'deny')) {
-    const coveringDeny = effective.deny.filter((d) => covers(d.rule, entry.rule) || d.rule === entry.rule);
+    if (conflicted.has(entry.rule)) continue;
+    // denyCovers, not covers: the deny direction refuses the fold and requires exact reach
+    // equality (AC-DPF-3(b)). Reusing the allow-direction relation here was strictly more
+    // permissive than the Python twin — a broad deny would have stood in for a narrower one.
+    const coveringDeny = effective.deny.filter((d) => denyCovers(d.rule, entry.rule));
     if (coveringDeny.length === 0) {
       findings.push({ class: 'deny-missing', rule: entry.rule });
     }
   }
 
+  // AC-FDC-1 — the exact mirror of deny-missing above, against the `ask` tier. Note what it does
+  // NOT consult: effective.allow. An ask entry covered by a broad allow is already named by
+  // ask-shadowed, and whether that allow actually defeats the ask at match time is the precedence
+  // question this tooling abstains from — so absence and shadowing are reported as the two
+  // independent facts they are, rather than one being folded into the other.
+  for (const entry of map.entries.filter((e) => e.tier === 'ask')) {
+    if (conflicted.has(entry.rule)) continue;
+    const coveringAsk = effective.ask.filter((a) => covers(a.rule, entry.rule, home, foldRe));
+    if (coveringAsk.length === 0) {
+      findings.push({ class: 'ask-absent', rule: entry.rule });
+    }
+  }
+
   if (pluginRootExpansion.length === 0) {
     findings.push({ class: 'stale-plugin-path', glob: map.plugin_root_glob });
   }
 
   for (const entry of map.entries.filter((e) => e.tier === 'allow')) {
-    const coveringAllow = effective.allow.filter((a) => covers(a.rule, entry.rule) || a.rule === entry.rule);
+    if (conflicted.has(entry.rule)) continue;
+    const coveringAllow = effective.allow.filter((a) => covers(a.rule, entry.rule, home, foldRe));
     if (coveringAllow.length === 0) {
       findings.push({ class: 'allow-absent', rule: entry.rule });
     }
@@ -175,5 +363,18 @@ export function classifyDrift(map, effective, { pluginRootExpansion = [], unread
     }
   }
 
+  // AC-FDC-7 — QUALIFIED, not suppressed. `covers()` returns false for a body that does not end
+  // `:*`, so under `Bash(*)` every map entry still classifies absent and a consumer could converge
+  // all 62 rules and report success over a floor that rule defeats entirely. Suppressing the other
+  // findings would hide the gap; marking them names both facts at once — here is the gap, and here
+  // is why closing it changes nothing until this rule is narrowed.
+  const blanketRules = findings.filter((f) => f.class === 'blanket-allow').map((f) => f.rule);
+  if (blanketRules.length > 0) {
+    for (const f of findings) {
+      if (f.class === 'blanket-allow') continue;
+      f.qualifiedBy = [...blanketRules];
+    }
+  }
+
   return findings;
 }

package/src/questions.mjs

@@ -122,6 +122,21 @@ export const QUESTION_TABLE = [
     default: false,
     interactive: false,
   },
+  {
+    id: 'reconcileFloor',
+    flag: 'reconcile-floor',
+    type: 'boolean',
+    prompt: 'Add any missing permission-floor rules to this workspace?',
+    description:
+      'For an EXISTING workspace whose .claude/settings.json is missing floor\n' +
+      'rules. Adds only the rules the floor declares and this workspace lacks —\n' +
+      'nothing is removed, reordered, or overwritten, and no other setting is\n' +
+      'touched. Running it twice changes nothing the second time.\n' +
+      'Use --dry-run first to see the exact rules it would add.\n' +
+      'Enter alone means no. y, yes, true or 1 mean yes.',
+    default: false,
+    interactive: false,
+  },
   {
     id: 'help',
     flag: 'help',

package/src/run.mjs

@@ -14,6 +14,10 @@ import { buildManagedFiles, DECLARED_PATH_SET } from './scaffold.mjs';
 import { planManagedFiles, applyPlan, exitCodeForPlan } from './reconcile.mjs';
 import { renderPreview, TRUST_HANDOFF_TEXT } from './preview.mjs';
 import { validateSlug, resolveIdentity, wireIdentity, plannedMachineScopeWrites } from './identity.mjs';
+import {
+  resolveTarget, readTarget, readTrackedRules, planAdditions, applyAdditions,
+  writeTargetAtomically, renderPlan,
+} from './floorReconcile.mjs';
 
 export { DECLARED_PATH_SET };
 
@@ -151,6 +155,54 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
 
     print(renderPreview({ plan, machineScopeWrites, map }));
 
+    // Drift is classified HERE — before the write phase and before the dry-run return — not after
+    // applyPlan where the advisory report used to compute it. Two things depend on the move: the
+    // reconcile must know what it would add in order to decide whether to write at all, and
+    // --dry-run must be able to report those rules, which it never could before because it returned
+    // above the only classifyDrift call in the file.
+    const { effective, unreadable } = readEffectiveRules(physicalRoot);
+    const pluginRootExpansion = expandPluginRootGlob(map.plugin_root_glob, homeDir);
+    const findings = classifyDrift(map, effective, {
+      pluginRootExpansion, unreadableOrigins: unreadable, home: homeDir,
+    });
+
+    // The reconcile classifies against the TRACKED settings.json alone. A floor rule carried only
+    // in the untracked settings.local.json reads as covered in the union above, so the tracked file
+    // would stay incomplete while the report said converged — and the repo would then ship to every
+    // other clone and to CI without it.
+    let floorPlan = null;
+    let floorTarget = null;
+    if (answers.reconcileFloor) {
+      floorTarget = resolveTarget(physicalRoot);
+      if (floorTarget.present) {
+        const settingsObj = readTarget(floorTarget.path);
+        const trackedFindings = classifyDrift(map, readTrackedRules(settingsObj), {
+          pluginRootExpansion, unreadableOrigins: [], home: homeDir,
+        });
+        floorPlan = planAdditions({ findings: trackedFindings, map, settingsObj, pins });
+        floorPlan.settingsObj = settingsObj;
+        print('');
+        for (const line of renderPlan(floorPlan, { applied: false })) print(line);
+      } else {
+        // absent settings.json is the CREATE path's business, not this one's — the managed-file
+        // plan above already writes the full floor for it, and racing that would duplicate it
+        print('');
+        print('permission-floor reconcile: .claude/settings.json absent — left to the create path.');
+      }
+    }
+
+    // Refuse BEFORE anything is written. isYesMode is true whenever stdin is not a TTY, which also
+    // waives the --existing basename ceremony, so a piped invocation would otherwise mutate the
+    // 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.
+    if (floorPlan && floorPlan.total > 0 && !isTTY && answers.yes !== true) {
+      throw new RefusalError(
+        'refusing --reconcile-floor without a terminal: pass --yes explicitly to confirm the write',
+        'reconcile-floor',
+      );
+    }
+
     if (answers.dryRun) {
       print('(dry-run: no write, no side effect, zero child processes spawned)');
       return { exitCode: 0, output: lines.join('\n') };
@@ -167,6 +219,12 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
 
     applyPlan(plan);
 
+    if (floorPlan && floorPlan.total > 0) {
+      writeTargetAtomically(floorTarget.path, applyAdditions(floorPlan.settingsObj, floorPlan, { map, pins }));
+      print('');
+      for (const line of renderPlan(floorPlan, { applied: true })) print(line);
+    }
+
     if (slug) {
       ensureGitRepo(physicalRoot);
       const identity = await resolveIdentity(slug, {
@@ -185,9 +243,6 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
       wireIdentity({ slug, name: identity.name, email: identity.email, targetRoot: physicalRoot, homeDir });
     }
 
-    const { effective, unreadable } = readEffectiveRules(physicalRoot);
-    const pluginRootExpansion = expandPluginRootGlob(map.plugin_root_glob, homeDir);
-    const findings = classifyDrift(map, effective, { pluginRootExpansion, unreadableOrigins: unreadable });
     if (findings.length > 0) {
       print('');
       print(`Permission-floor report (advisory, ${findings.length} finding(s)):`);