@sabaiway/agent-workflow-kit 1.10.0 → 1.12.0

package/tools/fs-safe.test.mjs

@@ -9,6 +9,8 @@ import {
   assertContainedRealPath,
   copyTreeRefresh,
   linkManaged,
+  removeTreeManaged,
+  unlinkManaged,
   MANAGED_LINK_CONFLICT,
 } from './fs-safe.mjs';
 
@@ -30,6 +32,12 @@ describe('assertContainedRealPath', () => {
     assert.throws(() => assertContainedRealPath('/root', '/etc/passwd'), /outside/);
   });
 
+  it('Issue-004: accepts a contained child literally named "..foo", still rejects a true ".." segment', () => {
+    // rel "..foo" is a real child, NOT a "../" escape — the old `rel.startsWith('..')` wrongly rejected it.
+    assert.doesNotThrow(() => assertContainedRealPath(dir, join(dir, '..foo')));
+    assert.throws(() => assertContainedRealPath(dir, join(dir, '..', 'escape')), /outside/);
+  });
+
   it('rejects writing INTO a symlinked root', () => {
     const real = join(dir, 'real');
     const root = join(dir, 'root');
@@ -198,3 +206,141 @@ describe('linkManaged', () => {
     assert.throws(() => linkManaged(srcDir, join(root, 'cmd'), root), /regular file/i);
   });
 });
+
+// ── removeTreeManaged ───────────────────────────────────────────────────────────
+
+describe('removeTreeManaged', () => {
+  it('recursively removes a managed dir tree', () => {
+    const root = join(dir, 'skills');
+    const skill = join(root, 'agent-workflow-kit');
+    mkdirSync(join(skill, 'tools'), { recursive: true });
+    writeFileSync(join(skill, 'SKILL.md'), 'x');
+    writeFileSync(join(skill, 'tools', 'a.mjs'), 'y');
+    const result = removeTreeManaged(skill, root);
+    assert.equal(result, 'removed');
+    assert.equal(existsSync(skill), false);
+    assert.equal(existsSync(root), true); // only the target went, not the parent
+  });
+
+  it('is a no-op when the target is already absent', () => {
+    const root = join(dir, 'skills');
+    mkdirSync(root);
+    assert.equal(removeTreeManaged(join(root, 'gone'), root), 'noop');
+  });
+
+  it('STOPs on a symlinked target (never follows + deletes through it)', () => {
+    const root = join(dir, 'skills');
+    const real = join(dir, 'real-skill');
+    mkdirSync(root);
+    mkdirSync(real);
+    writeFileSync(join(real, 'keep.txt'), 'keep');
+    symlinkSync(real, join(root, 'agent-workflow-kit')); // the skill dir is a symlink
+    assert.throws(() => removeTreeManaged(join(root, 'agent-workflow-kit'), root), /symlink/i);
+    assert.equal(existsSync(join(real, 'keep.txt')), true); // the target it pointed at is untouched
+  });
+
+  it('removes a symlink ENTRY inside the tree without touching what it points at', () => {
+    const root = join(dir, 'skills');
+    const skill = join(root, 'agent-workflow-kit');
+    const outside = join(dir, 'outside');
+    mkdirSync(skill, { recursive: true });
+    mkdirSync(outside);
+    writeFileSync(join(outside, 'precious.txt'), 'precious');
+    symlinkSync(outside, join(skill, 'link-to-outside')); // an internal symlink
+    removeTreeManaged(skill, root);
+    assert.equal(existsSync(skill), false);
+    assert.equal(existsSync(join(outside, 'precious.txt')), true); // never recursed through the link
+  });
+
+  it('refuses a target outside the root', () => {
+    const root = join(dir, 'skills');
+    mkdirSync(root);
+    assert.throws(() => removeTreeManaged(join(dir, 'elsewhere'), root), /outside/);
+  });
+
+  it('rm is injectable (no real deletion when injected)', () => {
+    const root = join(dir, 'skills');
+    const skill = join(root, 'agent-workflow-kit');
+    mkdirSync(skill, { recursive: true });
+    let removed = null;
+    const result = removeTreeManaged(skill, root, { rm: (p) => { removed = p; } });
+    assert.equal(result, 'removed');
+    assert.equal(removed, skill);
+    assert.equal(existsSync(skill), true); // the injected rm did nothing
+  });
+});
+
+// ── unlinkManaged ───────────────────────────────────────────────────────────────
+
+describe('unlinkManaged', () => {
+  const makeSrc = () => {
+    const src = join(dir, 'src.sh');
+    writeFileSync(src, '#!/bin/sh\n');
+    return src;
+  };
+
+  it('unlinks a symlink that points at our source', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    symlinkSync(src, dest);
+    const result = unlinkManaged(dest, src, root);
+    assert.equal(result, 'unlinked');
+    assert.equal(existsSync(dest), false);
+    assert.equal(existsSync(src), true); // the source it pointed at is untouched
+  });
+
+  it('is a no-op when the dest is absent', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    assert.equal(unlinkManaged(join(root, 'cmd'), src, root), 'noop');
+  });
+
+  it('STOPs on a non-symlink dest (typed ManagedLinkConflict)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    writeFileSync(dest, 'someone-elses-file');
+    assert.throws(() => unlinkManaged(dest, src, root), (err) => err.code === MANAGED_LINK_CONFLICT);
+    assert.equal(readFileSync(dest, 'utf8'), 'someone-elses-file'); // untouched
+  });
+
+  it('STOPs on a foreign symlink (points elsewhere)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    const foreign = join(dir, 'foreign.sh');
+    writeFileSync(foreign, '#!/bin/sh\n');
+    symlinkSync(foreign, dest);
+    assert.throws(() => unlinkManaged(dest, src, root), (err) => err.code === MANAGED_LINK_CONFLICT);
+    assert.equal(readlinkSync(dest), foreign); // untouched
+  });
+
+  it('removes a dangling symlink that still textually points at our source', () => {
+    const src = join(dir, 'src.sh'); // never created → the link is dangling
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    symlinkSync(src, dest);
+    assert.equal(unlinkManaged(dest, src, root), 'unlinked');
+    assert.equal(lstatSync(root).isDirectory(), true);
+    assert.equal(existsSync(dest), false);
+  });
+
+  it('unlink is injectable', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    symlinkSync(src, dest);
+    let unlinked = null;
+    const result = unlinkManaged(dest, src, root, { unlink: (p) => { unlinked = p; } });
+    assert.equal(result, 'unlinked');
+    assert.equal(unlinked, dest);
+    assert.equal(existsSync(dest), true); // the injected unlink did nothing
+  });
+});

package/tools/inject-methodology.mjs

@@ -3,9 +3,12 @@
 // deployed AGENTS.md.
 //
 // Both templates (memory's + the kit fallback) ship an EMPTY delimited slot; the kit (which knows
-// the whole family) fills it. The bounded fragment (tools/methodology-slot.md) is a BOUNDED summary
-// + pointer, NOT the full references/planning.md, so AGENTS.md stays under its line cap; it is a
-// byte-identical MIRROR of the canonical text in agent-workflow-engine (drift-guarded).
+// the whole family) fills it. The bounded fragment is a BOUNDED summary + pointer (NOT the full
+// references/planning.md), so AGENTS.md stays under its line cap. It is read LIVE from the installed
+// agent-workflow-engine (references/methodology-slot.md) via engine-source.mjs — the family's one
+// source of truth; there is no bundled mirror (retired in Plan 3D, AD-016). The live read is lazy +
+// fail-loud: resolve+read the engine ONLY when a fill is actually needed, and STOP loudly (never a
+// silent fallback) when the engine is needed but absent/invalid.
 //
 // Two layers over one marker parser:
 //   - injectMethodology — fill an EXISTING slot. Marker contract, strictly enforced:
@@ -152,11 +155,24 @@ export const reconcileSlot = (text, fragment, { maxLines } = {}) => {
   return { status, text: injected.text };
 };
 
+// Pure predicate (no fs): does this AGENTS.md actually need the methodology fragment? True only when
+// the slot can be ensured (present or insertable) AND is empty — i.e. when reconcileSlot would
+// inject. False when the slot is already filled (preserve-verbatim, no fragment read) OR when the
+// slot/anchor is malformed (so reconcileSlot's own precise error path still fires). It reuses the
+// SAME primitives as reconcileSlot (ensureSlot + extractSlot), so the lazy "read the engine only
+// when needed" guard in main() cannot diverge from the actual fill decision.
+export const slotNeedsFill = (text) => {
+  const ensured = ensureSlot(text);
+  if (ensured.status === 'error') return false;
+  const current = extractSlot(ensured.text);
+  return current == null || current.trim() === '';
+};
+
 const main = async (argv) => {
   const { readFile, writeFile, rename, rm } = await import('node:fs/promises');
   const { dirname, basename, join, resolve } = await import('node:path');
-  const { fileURLToPath } = await import('node:url');
-  const here = dirname(fileURLToPath(import.meta.url));
+  const { homedir } = await import('node:os');
+  const { resolveEngineDir, readEngineFragment } = await import('./engine-source.mjs');
 
   // `reconcile <AGENTS.md> [fragment.md]` = ensure-slot + inject-if-empty + cap (bootstrap/upgrade);
   // `<AGENTS.md> [fragment.md]` = the legacy inject-into-existing-slot mode.
@@ -167,9 +183,29 @@ const main = async (argv) => {
     console.error('usage: inject-methodology.mjs [reconcile] <path/to/AGENTS.md> [fragment.md]');
     process.exit(2);
   }
-  const fragmentPath = rest[1] ? resolve(rest[1]) : resolve(here, 'methodology-slot.md');
+  const explicitFragmentArg = rest[1];
   const text = await readFile(resolve(agentsPath), 'utf8');
-  const fragment = await readFile(fragmentPath, 'utf8');
+
+  // Source the bounded fragment LAZILY. An explicit [fragment.md] arg (tests + manual) wins and skips
+  // engine resolution entirely. Otherwise read it LIVE from the installed engine — there is no
+  // bundled mirror. readEngineFragment THROWS (never falls back) when the engine is needed but
+  // absent/invalid; sourceFragmentOrStop turns that into a hard, loud STOP carrying the install
+  // command. The caller only invokes this when a fill is actually needed (the laziness).
+  const sourceFragment = async () => {
+    if (explicitFragmentArg) return readFile(resolve(explicitFragmentArg), 'utf8');
+    const { dir, source } = resolveEngineDir({ env: process.env, home: homedir() });
+    return readEngineFragment(dir, { source }); // sync; throws loudly when the engine is absent/invalid
+  };
+  const sourceFragmentOrStop = async (label) => {
+    try {
+      return await sourceFragment();
+    } catch (err) {
+      // Engine needed-but-absent → a hard STOP, distinct from the soft cap-skip. The
+      // "methodology engine not found/invalid" prefix lets the agent classify this exit (SKILL.md).
+      console.error(`[inject-methodology] ${label} — ${err.message}`);
+      process.exit(1);
+    }
+  };
 
   const writeAtomic = async (out) => {
     const tmp = join(dirname(resolve(agentsPath)), `.${basename(agentsPath)}.tmp-${process.pid}-${Date.now()}`);
@@ -183,6 +219,10 @@ const main = async (argv) => {
   };
 
   if (mode === 'reconcile') {
+    // Read the engine only when the slot actually needs filling (lazy). slotNeedsFill reuses the same
+    // primitives reconcileSlot does, so it cannot disagree with the fill decision below — a filled
+    // slot reconciles to a zero-diff no-op WITHOUT consulting the engine.
+    const fragment = slotNeedsFill(text) ? await sourceFragmentOrStop('reconcile STOP') : '';
     const result = reconcileSlot(text, fragment, { maxLines: AGENTS_MD_CAP });
     if (result.status === 'error') {
       console.error(`[inject-methodology] reconcile refused — ${result.error}`);
@@ -201,6 +241,10 @@ const main = async (argv) => {
     return;
   }
 
+  // Legacy inject-into-existing-slot mode. injectMethodology no-ops on absent markers and errors on a
+  // malformed slot WITHOUT reading the fragment, so resolve+read the engine only when there is a
+  // present (ok) slot to fill — a markerless legacy AGENTS.md stays a no-op without the engine.
+  const fragment = findSlot(text).state === 'ok' ? await sourceFragmentOrStop('STOP') : '';
   const result = injectMethodology(text, fragment, { maxLines: AGENTS_MD_CAP });
   if (result.status === 'error') {
     console.error(`[inject-methodology] malformed slot — refusing to edit: ${result.error}`);

package/tools/inject-methodology.test.mjs

@@ -1,6 +1,6 @@
-import { describe, it } from 'node:test';
+import { describe, it, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +11,7 @@ import {
   extractSlot,
   ensureSlot,
   reconcileSlot,
+  slotNeedsFill,
   METHODOLOGY_ANCHOR,
   EMPTY_SLOT,
   AGENTS_MD_CAP,
@@ -20,7 +21,47 @@ import {
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const SCRIPT = join(HERE, 'inject-methodology.mjs');
-const FRAGMENT = readFileSync(join(HERE, 'methodology-slot.md'), 'utf8');
+
+// The bounded methodology fragment is read LIVE from the installed engine now (the kit mirror is
+// retired in Plan 3D), so this suite no longer reads a bundled methodology-slot.md. Tests use an
+// inline fragment and, for the live-read CLI cases, an on-the-fly engine fixture that ships exactly
+// this fragment — keeping the kit suite decoupled from the sibling engine's on-disk presence.
+// Single-line (like the canonical fragment) so byte-equality holds in both LF and CRLF documents.
+const FRAGMENT =
+  '> **Workflow methodology (test fixture)** — plan → execute → review. Plans are ephemeral, gitignored, never committed; every Plan ends with a mandatory **Phase: Cleanup**.\n';
+
+// Temp dirs created by the fixtures below — cleaned up once after the whole file.
+const tmpDirs = [];
+after(() => tmpDirs.forEach((d) => rmSync(d, { recursive: true, force: true })));
+
+// A minimal but VALID installed-engine fixture: a methodology-engine capability.json + a SKILL.md
+// whose metadata.version matches it (the validator's authoritative version source when there is no
+// package.json) + the live fragment at references/methodology-slot.md. detectEngine accepts it.
+const makeEngineFixture = (fragment = FRAGMENT, version = '1.0.0') => {
+  const dir = mkdtempSync(join(tmpdir(), 'engine-fixture-'));
+  tmpDirs.push(dir);
+  const manifest = {
+    family: 'agent-workflow',
+    schema: 1,
+    name: 'agent-workflow-engine',
+    kind: 'methodology-engine',
+    version,
+    available: true,
+    provides: ['plan'],
+    roles: {},
+  };
+  writeFileSync(join(dir, 'capability.json'), JSON.stringify(manifest, null, 2));
+  writeFileSync(join(dir, 'SKILL.md'), `---\nname: agent-workflow-engine\nmetadata:\n  version: '${version}'\n---\n# engine\n`);
+  mkdirSync(join(dir, 'references'), { recursive: true });
+  writeFileSync(join(dir, 'references', 'methodology-slot.md'), fragment);
+  return dir;
+};
+
+const ENGINE = makeEngineFixture();
+// A path that is guaranteed NOT to be a valid engine — proves the no-op / explicit-override paths
+// never consult the engine, and drives the fail-loud STOP.
+const NO_ENGINE = join(tmpdir(), `definitely-no-engine-${process.pid}`);
+const withEngine = (engineDir) => ({ ...process.env, AGENT_WORKFLOW_ENGINE_DIR: engineDir });
 
 const wrap = (inner) =>
   `# AGENTS.md\n\nprefix bytes\n\n## Session Protocols\n\nintro line.\n\n${START_MARKER}${inner}${END_MARKER}\n\n## Hard Constraints\n\nsuffix bytes\n`;
@@ -309,7 +350,46 @@ describe('reconcileSlot — ensure + inject-if-empty + cap, as one atomic policy
   });
 });
 
-describe('reconcile CLI — atomic ensure+inject-if-empty+cap on the real filesystem', () => {
+describe('slotNeedsFill — lazy-read predicate (matches reconcileSlot fill decision)', () => {
+  it('present empty slot → true', () => {
+    assert.equal(slotNeedsFill(wrap('\n')), true);
+  });
+  it('markerless legacy with one anchor (insertable empty slot) → true', () => {
+    assert.equal(slotNeedsFill(legacyWithAnchor()), true);
+  });
+  it('present filled/customized slot → false (fragment not needed)', () => {
+    assert.equal(slotNeedsFill(wrap('\nuser notes\n')), false);
+  });
+  it('malformed slot → false (reconcileSlot error path fires, not a fill)', () => {
+    assert.equal(slotNeedsFill(`${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`), false);
+  });
+  it('markerless with no anchor → false (cannot insert; reconcile errors without the engine)', () => {
+    assert.equal(slotNeedsFill('# AGENTS.md\n\nno anchor here\n'), false);
+  });
+
+  // slotNeedsFill and reconcileSlot share the SAME emptiness primitives (ensureSlot + extractSlot), so
+  // the lazy "read the engine only when needed" guard cannot disagree with reconcileSlot's actual fill
+  // decision. Pin that equivalence across representative inputs: needsFill === true  IFF reconcile fills
+  // (reconciled-filled / reconciled-inserted); needsFill === false IFF reconcile does NOT fill
+  // (present-filled / error). This forecloses any future divergence that could silently drop a slot.
+  it('agrees with reconcileSlot across every slot state (no divergence → no silent drop)', () => {
+    const cases = [
+      wrap('\n'), // present empty slot → fill
+      legacyWithAnchor(), // markerless + anchor → insert + fill
+      wrap('\nuser notes\n'), // filled slot → no fill
+      `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`, // malformed → no fill (error)
+      '# AGENTS.md\n\nno anchor here\n', // no anchor → no fill (error)
+    ];
+    for (const text of cases) {
+      const needs = slotNeedsFill(text);
+      const result = reconcileSlot(text, FRAGMENT, { maxLines: AGENTS_MD_CAP });
+      const filled = result.status === 'reconciled-filled' || result.status === 'reconciled-inserted';
+      assert.equal(needs, filled, `slotNeedsFill (${needs}) must match whether reconcile fills (${result.status})`);
+    }
+  });
+});
+
+describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragment LIVE from the engine', () => {
   const withTempAgents = (contents, run) => {
     const dir = mkdtempSync(join(tmpdir(), 'reconcile-cli-'));
     const agents = join(dir, 'AGENTS.md');
@@ -321,35 +401,100 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap on the real filesy
     }
   };
 
-  it('markerless legacy (with anchor) → slot inserted and filled (exit 0)', () => {
+  it('markerless legacy (with anchor) → slot inserted + filled from the live engine fragment (exit 0)', () => {
     withTempAgents(legacyWithAnchor(), (agents) => {
-      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) });
       const out = readFileSync(agents, 'utf8');
       assert.equal(findSlot(out).state, 'ok');
       assert.equal(extractSlot(out).trim(), FRAGMENT.trim());
     });
   });
 
-  it('present empty slot → slot filled (exit 0)', () => {
+  it('present empty slot → filled from the live engine fragment (exit 0)', () => {
     withTempAgents(wrap('\n'), (agents) => {
-      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) });
       assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), FRAGMENT.trim());
     });
   });
 
-  it('filled/customized slot → file left byte-for-byte untouched', () => {
+  it('filled/customized slot → zero-diff no-op WITHOUT consulting the engine (engine absent, exit 0)', () => {
     const custom = wrap('\nuser notes\n');
     withTempAgents(custom, (agents) => {
-      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      // Engine pointed at a path that does not exist — a filled slot must NOT require it.
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
       assert.equal(readFileSync(agents, 'utf8'), custom);
     });
   });
 
-  it('malformed slot → STOP with non-zero exit, file byte-unchanged', () => {
+  it('present empty slot + engine ABSENT → hard STOP (nonzero) printing the install command, file unchanged', () => {
+    withTempAgents(wrap('\n'), (agents) => {
+      const err = (() => {
+        try {
+          execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
+          return null;
+        } catch (e) {
+          return e;
+        }
+      })();
+      assert.ok(err, 'expected a non-zero exit when a fill is needed but the engine is absent');
+      const stderr = String(err.stderr);
+      assert.match(stderr, /methodology engine not found\/invalid/);
+      assert.match(stderr, /npx @sabaiway\/agent-workflow-engine@latest init/);
+      assert.equal(readFileSync(agents, 'utf8'), wrap('\n'), 'no partial write on STOP');
+    });
+  });
+
+  it('explicit [fragment.md] override fills from that file and skips engine resolution (engine absent)', () => {
+    const override = '> custom override fragment line\n';
+    const fdir = mkdtempSync(join(tmpdir(), 'frag-'));
+    tmpDirs.push(fdir);
+    const fpath = join(fdir, 'frag.md');
+    writeFileSync(fpath, override);
+    withTempAgents(wrap('\n'), (agents) => {
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents, fpath], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
+      assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), override.trim());
+    });
+  });
+
+  it('malformed slot → STOP with non-zero exit, file byte-unchanged (engine never consulted)', () => {
     const malformed = `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`;
     withTempAgents(malformed, (agents) => {
-      assert.throws(() => execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' }));
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) }),
+      );
       assert.equal(readFileSync(agents, 'utf8'), malformed);
     });
   });
+
+  it('legacy inject mode: markerless AGENTS.md → no-op WITHOUT the engine (exit 0)', () => {
+    const markerless = '# AGENTS.md\n\nlegacy, no slot\n';
+    withTempAgents(markerless, (agents) => {
+      execFileSync(process.execPath, [SCRIPT, agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
+      assert.equal(readFileSync(agents, 'utf8'), markerless);
+    });
+  });
+
+  // Legacy `inject` mode FORCE-OVERWRITES any present (ok) slot — filled or empty — unlike `reconcile`,
+  // which preserves a filled slot. So for an ok slot it genuinely NEEDS the fragment and reads the
+  // engine; the read-on-`state==='ok'` guard is correct (reading only an EMPTY ok slot would inject ''
+  // and WIPE a filled slot). These two tests pin that contract.
+  it('legacy inject mode: a FILLED slot is OVERWRITTEN from the live engine (engine present, exit 0)', () => {
+    const filled = wrap('\nstale user content\n');
+    withTempAgents(filled, (agents) => {
+      execFileSync(process.execPath, [SCRIPT, agents], { stdio: 'pipe', env: withEngine(ENGINE) });
+      const out = readFileSync(agents, 'utf8');
+      assert.equal(extractSlot(out).trim(), FRAGMENT.trim(), 'slot overwritten with the live fragment');
+      assert.ok(!out.includes('stale user content'), 'prior slot content replaced');
+    });
+  });
+
+  it('legacy inject mode: a present (ok) slot + engine ABSENT → hard STOP, file unchanged', () => {
+    const filled = wrap('\nstale user content\n');
+    withTempAgents(filled, (agents) => {
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) }),
+      );
+      assert.equal(readFileSync(agents, 'utf8'), filled, 'no partial write on STOP');
+    });
+  });
 });

package/tools/manifest/validate.mjs

@@ -77,7 +77,9 @@ const readSkillVersion = (text) => {
 
 // Authoritative version source: package.json where one exists, else SKILL.md
 // frontmatter metadata.version. So a bridge (no package.json) can't drift from its SKILL.md.
-const readAuthoritativeVersion = (skillDir) => {
+// Exported so the family registry (tools/family-registry.mjs) reports an INSTALLED member's
+// version from the SAME authoritative source the validator checks — no second, drifting reader.
+export const readAuthoritativeVersion = (skillDir) => {
   const pkgPath = join(skillDir, 'package.json');
   if (existsSync(pkgPath)) {
     try {

package/tools/uninstall.integration.test.mjs

@@ -0,0 +1,144 @@
+// Integration acceptance for the guarded uninstaller against the REAL filesystem — what the mocked
+// unit test cannot prove: real validateManifest over real skill dirs, real removeTreeManaged deleting
+// a real tree, real unlinkManaged removing OUR symlink while leaving a FOREIGN one, a real marker
+// pre-commit hook removed, and user-authored docs/ai LEFT INTACT after a full --yes teardown. The
+// git-backed fence unhide is delegated to hideFootprint (already covered by its own integration test),
+// so it is injected here as a recording stub — this test owns the uninstaller's own fs mutations.
+
+import { describe, it, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync, existsSync, lstatSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { buildPlan, executePlan, SAFE_REMOVE, MANAGED_MARKER, REPORT_ONLY, STOP } from './uninstall.mjs';
+import { surveyFamily, surveyProject } from './family-registry.mjs';
+import { START_MARKER } from './hide-footprint.mjs';
+
+const made = [];
+const mkdtemp = (tag) => { const d = mkdtempSync(join(tmpdir(), tag)); made.push(d); return d; };
+afterEach(() => { while (made.length) { try { rmSync(made.pop(), { recursive: true, force: true }); } catch { /* best effort */ } } });
+
+const writeFile = (p, s) => { mkdirSync(join(p, '..'), { recursive: true }); writeFileSync(p, s); };
+
+// A minimal but VALID family skill dir (passes the real validateManifest: family/schema/kind/version
+// match + SKILL.md metadata.version == capability.json version + role sources exist).
+const makeMemorySkill = (skillsRoot) => {
+  const dir = join(skillsRoot, 'agent-workflow-memory');
+  writeFile(join(dir, 'SKILL.md'), "---\nname: agent-workflow-memory\nmetadata:\n  version: '1.1.1'\n---\n# memory\n");
+  writeFile(join(dir, 'capability.json'), JSON.stringify({
+    family: 'agent-workflow', schema: 1, name: 'agent-workflow-memory', kind: 'memory-substrate',
+    version: '1.1.1', provides: ['context'], roles: {},
+    detect: { installed: { env: 'AGENT_WORKFLOW_MEMORY_DIR', default: '~/.claude/skills/agent-workflow-memory', file: 'SKILL.md' } },
+  }));
+  return dir;
+};
+
+const makeCodexBridge = (skillsRoot) => {
+  const dir = join(skillsRoot, 'codex-cli-bridge');
+  writeFile(join(dir, 'SKILL.md'), "---\nname: codex-cli-bridge\nmetadata:\n  version: '1.0.0'\n---\n# codex\n");
+  writeFile(join(dir, 'bin', 'codex-exec.sh'), '#!/bin/sh\n');
+  writeFile(join(dir, 'bin', 'codex-review.sh'), '#!/bin/sh\n');
+  writeFile(join(dir, 'capability.json'), JSON.stringify({
+    family: 'agent-workflow', schema: 1, name: 'codex-cli-bridge', kind: 'execution-backend',
+    version: '1.0.0', provides: ['execute', 'review'],
+    roles: {
+      execute: { cmd: 'codex-exec', source: 'bin/codex-exec.sh' },
+      review: { cmd: 'codex-review', source: 'bin/codex-review.sh' },
+    },
+    detect: { installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' } },
+  }));
+  return dir;
+};
+
+describe('uninstall integration (real fs)', () => {
+  it('plans + applies a full guarded teardown: removes ours, keeps foreign + user-authored', () => {
+    const home = mkdtemp('aw-unh-home-');
+    const skills = mkdtemp('aw-unh-skills-');
+    const bindir = mkdtemp('aw-unh-bin-');
+    const proj = mkdtemp('aw-unh-proj-');
+    const foreignTarget = mkdtemp('aw-unh-foreign-');
+
+    const memorySkill = makeMemorySkill(skills);
+    const codexSkill = makeCodexBridge(skills);
+
+    // ~/.local/bin wrappers: codex-exec is OURS; codex-review is a FOREIGN symlink (must be kept).
+    symlinkSync(join(codexSkill, 'bin/codex-exec.sh'), join(bindir, 'codex-exec'));
+    writeFileSync(join(foreignTarget, 'codex-review'), '#!/bin/sh\n');
+    symlinkSync(join(foreignTarget, 'codex-review'), join(bindir, 'codex-review'));
+
+    // Project surfaces: a hidden fence, OUR marker pre-commit hook, and user-authored docs/ai.
+    writeFile(join(proj, '.git/info/exclude'), `# user rule\n${START_MARKER}\n/AGENTS.md\n# <<< agent-workflow-kit hidden mode <<<\n`);
+    writeFile(join(proj, '.git/hooks/pre-commit'), '#!/usr/bin/env bash\n# myproj:install-git-hooks.mjs\nset -e\nnode scripts/check-docs-size.mjs\n');
+    writeFile(join(proj, 'docs/ai/handover.md'), '# handover (USER-AUTHORED)\n');
+    writeFile(join(proj, 'docs/ai/.workflow-version'), '1.3.0\n');
+
+    // Resolve only memory + codex as installed (env-pointed); other members fall to <home>/.claude → absent.
+    const deps = {
+      getenv: { AGENT_WORKFLOW_MEMORY_DIR: memorySkill, CODEX_CLI_BRIDGE_DIR: codexSkill },
+      home,
+    };
+    const family = surveyFamily(deps);
+    const project = surveyProject(proj, deps);
+    assert.equal(project.hiddenFence, true);
+    assert.equal(family.find((m) => m.name === 'agent-workflow-memory').manifestState, 'ok');
+    assert.equal(family.find((m) => m.name === 'codex-cli-bridge').manifestState, 'ok');
+
+    const plan = buildPlan({ family, project, projectDir: proj, bindir }, deps);
+    const cls = (surface, pred) => plan.items.find((i) => i.surface === surface && pred(i));
+    assert.equal(cls('skill', (i) => i.member === 'agent-workflow-memory').class, SAFE_REMOVE);
+    assert.equal(cls('wrapper', (i) => i.path.endsWith('codex-exec')).class, MANAGED_MARKER);
+    assert.equal(cls('wrapper', (i) => i.path.endsWith('codex-review')).class, STOP); // foreign
+    assert.equal(cls('fence', () => true).class, MANAGED_MARKER);
+    assert.equal(cls('hook', () => true).class, MANAGED_MARKER);
+    assert.equal(cls('docs', (i) => i.path.endsWith('docs/ai')).class, REPORT_ONLY);
+
+    // Apply. Inject a recording fence-unhide (its real git path is covered by hide-footprint's own test).
+    const unhideCalls = [];
+    const r = executePlan(plan, { yes: true }, { ...deps, hideFootprint: (opts) => { unhideCalls.push(opts); return { action: 'unhidden' }; } });
+
+    // Ours is gone:
+    assert.equal(existsSync(memorySkill), false, 'memory skill dir removed');
+    assert.equal(existsSync(codexSkill), false, 'codex skill dir removed');
+    assert.equal(existsSync(join(bindir, 'codex-exec')), false, 'our wrapper symlink removed');
+    assert.equal(existsSync(join(proj, '.git/hooks/pre-commit')), false, 'marker hook removed');
+    assert.equal(r.unhidden, true);
+    // The fence is validated by a dry-run unhide in preflight, then unhidden for real in the mutate phase.
+    assert.deepEqual(unhideCalls, [{ dir: proj, unhide: true, dryRun: true }, { dir: proj, unhide: true }]);
+
+    // Foreign + user-authored is KEPT:
+    assert.equal(lstatSync(join(bindir, 'codex-review')).isSymbolicLink(), true, 'foreign wrapper kept');
+    assert.equal(existsSync(join(foreignTarget, 'codex-review')), true, 'foreign target untouched');
+    assert.equal(existsSync(join(proj, 'docs/ai/handover.md')), true, 'user-authored docs/ai NEVER deleted');
+  });
+
+  it('preflight refuses (zero mutation) when a skill dir turns foreign between plan and apply', () => {
+    const home = mkdtemp('aw-unh2-home-');
+    const skills = mkdtemp('aw-unh2-skills-');
+    const memorySkill = makeMemorySkill(skills);
+    const deps = { getenv: { AGENT_WORKFLOW_MEMORY_DIR: memorySkill }, home };
+
+    const family = surveyFamily(deps);
+    const plan = buildPlan({ family }, deps);
+    assert.equal(plan.items.find((i) => i.surface === 'skill').class, SAFE_REMOVE);
+
+    // Corrupt the manifest after planning → the preflight re-check must STOP, leaving the dir intact.
+    writeFileSync(join(memorySkill, 'capability.json'), '{ not json');
+    assert.throws(() => executePlan(plan, { yes: true }, deps), (err) => err.code === 'UNINSTALL_STOP');
+    assert.equal(existsSync(memorySkill), true, 'skill dir untouched after a refused preflight');
+  });
+
+  it('keeps a pre-commit hook whose marker was removed between plan and apply', () => {
+    const home = mkdtemp('aw-unh3-home-');
+    const proj = mkdtemp('aw-unh3-proj-');
+    writeFile(join(proj, '.git/hooks/pre-commit'), '#!/usr/bin/env bash\n# myproj:install-git-hooks.mjs\nset -e\n');
+    const deps = { getenv: {}, home };
+
+    const plan = buildPlan({ family: [], project: surveyProject(proj, deps), projectDir: proj }, deps);
+    assert.equal(plan.items.find((i) => i.surface === 'hook').class, MANAGED_MARKER);
+
+    // The user rewrites the hook (dropping our marker) before they apply the teardown.
+    writeFileSync(join(proj, '.git/hooks/pre-commit'), '#!/bin/sh\n# my own hook now\n');
+    assert.throws(() => executePlan(plan, { yes: true }, deps), (err) => err.code === 'UNINSTALL_STOP');
+    assert.equal(existsSync(join(proj, '.git/hooks/pre-commit')), true, 'a now-unmarked (user) hook is NEVER deleted');
+  });
+});