@sabaiway/agent-workflow-kit 1.11.0 → 1.13.0

package/tools/recipes.test.mjs

@@ -0,0 +1,363 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import {
+  RECIPES,
+  BACKEND_ROLES,
+  BACKEND_META,
+  DISPLAY_ALIASES,
+  planRecipe,
+  recommendRecipe,
+  formatRecipes,
+} from './recipes.mjs';
+import { READY, NEEDS_SKILL, NEEDS_CLI, NEEDS_CREDENTIALS, DEGRADED } from './detect-backends.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(HERE, 'recipes.mjs');
+const REPO_ROOT = join(HERE, '..', '..');
+
+const CODEX = 'codex-cli-bridge';
+const AGY = 'antigravity-cli-bridge';
+const RECIPE_IDS = ['solo', 'reviewed', 'council', 'delegated'];
+
+// A synthetic detector fixture — the planner only consumes { name, readiness } off each entry, built
+// from the REAL readiness vocabulary (no `missing` — that is a probe-axis state, not a readiness).
+const detect = (codexReadiness, agyReadiness) => [
+  { name: CODEX, readiness: codexReadiness },
+  { name: AGY, readiness: agyReadiness },
+];
+
+const readManifest = (name) => JSON.parse(readFileSync(join(REPO_ROOT, name, 'capability.json'), 'utf8'));
+
+// ── RECIPES shape ────────────────────────────────────────────────────────────────
+
+describe('RECIPES — the four named patterns', () => {
+  it('is exactly the four recipes, in lattice order', () => {
+    assert.deepEqual(RECIPES.map((r) => r.id), RECIPE_IDS);
+  });
+
+  it('each recipe declares a role (or null for Solo), a minBackends count, and a degradation target', () => {
+    for (const r of RECIPES) {
+      assert.ok(typeof r.id === 'string' && r.id.length > 0);
+      assert.ok('role' in r, `${r.id} declares a role key`);
+      assert.ok(Number.isInteger(r.minBackends), `${r.id} declares minBackends`);
+      assert.ok('degradesTo' in r, `${r.id} declares a degradation target`);
+    }
+  });
+
+  it('Solo is the floor (no role, no backend, no degradation target)', () => {
+    const solo = RECIPES.find((r) => r.id === 'solo');
+    assert.equal(solo.role, null);
+    assert.equal(solo.minBackends, 0);
+    assert.equal(solo.degradesTo, null);
+  });
+
+  it('Reviewed/Council need review; Delegated needs execute; degradation chains terminate at Solo', () => {
+    const by = Object.fromEntries(RECIPES.map((r) => [r.id, r]));
+    assert.equal(by.reviewed.role, 'review');
+    assert.equal(by.reviewed.minBackends, 1);
+    assert.equal(by.reviewed.degradesTo, 'solo');
+    assert.equal(by.council.role, 'review');
+    assert.equal(by.council.minBackends, 2);
+    assert.equal(by.council.degradesTo, 'reviewed');
+    assert.equal(by.delegated.role, 'execute');
+    assert.equal(by.delegated.minBackends, 1);
+    assert.equal(by.delegated.degradesTo, 'solo');
+  });
+});
+
+// ── drift guards ───────────────────────────────────────────────────────────────
+
+describe('role-coverage drift-guard — every recipe role ∈ union of the bridges provides[]', () => {
+  it('no recipe demands a role no backend provides', () => {
+    const union = new Set([...readManifest(CODEX).provides, ...readManifest(AGY).provides]);
+    for (const r of RECIPES) {
+      if (r.role !== null) assert.ok(union.has(r.role), `recipe ${r.id} role "${r.role}" is provided by some backend`);
+    }
+  });
+});
+
+describe('BACKEND_ROLES drift-guard — keyed by status.name, equals each bridge provides[]', () => {
+  it('is keyed by the manifest names the detector emits (not the display aliases)', () => {
+    assert.deepEqual(Object.keys(BACKEND_ROLES).sort(), [AGY, CODEX].sort());
+  });
+  it('matches each bridge capability.json provides[]', () => {
+    assert.deepEqual(BACKEND_ROLES[CODEX], readManifest(CODEX).provides);
+    assert.deepEqual(BACKEND_ROLES[AGY], readManifest(AGY).provides);
+  });
+});
+
+describe('BACKEND_META drift-guard — cost/quota mirror the manifests; agy carries a health advisory', () => {
+  it('cost + quota equal each bridge capability.json', () => {
+    for (const name of [CODEX, AGY]) {
+      const m = readManifest(name);
+      assert.equal(BACKEND_META[name].cost, m.cost);
+      assert.deepEqual(BACKEND_META[name].quota, m.quota);
+    }
+  });
+  it('the agy health advisory (Issue-001) is present as static project knowledge', () => {
+    assert.equal(typeof BACKEND_META[AGY].health, 'string');
+    assert.ok(BACKEND_META[AGY].health.length > 0);
+    // codex carries no standing health caveat
+    assert.ok(!BACKEND_META[CODEX].health);
+  });
+});
+
+describe('DISPLAY_ALIASES — the manifest-name → human-alias map', () => {
+  it('maps both bridges to their short aliases', () => {
+    assert.equal(DISPLAY_ALIASES[CODEX], 'codex');
+    assert.equal(DISPLAY_ALIASES[AGY], 'agy');
+  });
+});
+
+// ── engine ⟷ kit recipe-name parity (cross-package read in the monorepo) ───────────
+
+describe('engine↔kit recipe-name parity — the four ids appear in the engine canon', () => {
+  const engineRefs = ['orchestration.md', 'orchestration-slot.md'].map((f) =>
+    readFileSync(join(REPO_ROOT, 'agent-workflow-engine', 'references', f), 'utf8').toLowerCase(),
+  );
+  for (const id of RECIPE_IDS) {
+    it(`"${id}" appears in both engine orchestration files`, () => {
+      for (const text of engineRefs) assert.ok(text.includes(id), `engine canon names "${id}"`);
+    });
+  }
+});
+
+// The engine narrative (orchestration.md) hardcodes the bridges' role vocabulary as prose; keep it in
+// lockstep with the manifests so a future `provides[]` change forces the narrative to be updated too.
+describe('engine narrative ⟷ manifest role-vocabulary parity', () => {
+  const orchestration = readFileSync(join(REPO_ROOT, 'agent-workflow-engine', 'references', 'orchestration.md'), 'utf8');
+  const norm = (s) => s.replace(/\s+/g, ''); // whitespace-insensitive: prose has `["a", "b"]`, JSON has `["a","b"]`
+
+  for (const name of [CODEX, AGY]) {
+    it(`orchestration.md renders ${name}'s provides[] from the manifest`, () => {
+      const provides = readManifest(name).provides;
+      assert.ok(
+        norm(orchestration).includes(norm(`provides: ${JSON.stringify(provides)}`)),
+        `orchestration.md §1 must render ${name} provides ${JSON.stringify(provides)} (drifted from the manifest)`,
+      );
+    });
+  }
+
+  it('the agy health advisory (Issue-001) is consistent between BACKEND_META and the engine narrative', () => {
+    // Flatten whitespace so a prose line-wrap (e.g. "substantive\nprompts") doesn't hide the substring.
+    const flat = orchestration.replace(/\s+/g, ' ').toLowerCase();
+    assert.match(flat, /stall on substantive prompts/, 'the engine narrates the stall advisory');
+    assert.match(flat, /issue-001/, 'the engine narrative ties it to Issue-001');
+    assert.match(flat, /prefer .?codex/, 'the engine narrates the prefer-codex remedy');
+    // BACKEND_META carries the same advisory facts (kit-side), tying the two representations together.
+    const health = BACKEND_META[AGY].health.toLowerCase();
+    assert.ok(health.includes('stall on substantive prompts') && health.includes('issue-001') && health.includes('codex'));
+  });
+});
+
+// ── planRecipe ─────────────────────────────────────────────────────────────────
+
+const dispatchBackends = (plan) => plan.dispatch.map((d) => d.backend);
+const notesText = (plan) => plan.notes.join(' :: ');
+
+describe('planRecipe — all backends ready', () => {
+  const det = detect(READY, READY);
+
+  it('Solo: no degradation, no dispatch', () => {
+    const p = planRecipe('solo', det);
+    assert.equal(p.effective, 'solo');
+    assert.equal(p.degraded, false);
+    assert.deepEqual(p.dispatch, []);
+  });
+
+  it('Reviewed: picks codex over agy (deterministic tie-break), not degraded', () => {
+    const p = planRecipe('reviewed', det);
+    assert.equal(p.effective, 'reviewed');
+    assert.equal(p.degraded, false);
+    assert.deepEqual(dispatchBackends(p), [CODEX]);
+    // codex chosen → the agy health caveat is NOT attached
+    assert.ok(!notesText(p).includes(BACKEND_META[AGY].health));
+  });
+
+  it('Council: both backends review; the agy health caveat + the two-quota note are attached', () => {
+    const p = planRecipe('council', det);
+    assert.equal(p.effective, 'council');
+    assert.equal(p.degraded, false);
+    assert.deepEqual(dispatchBackends(p), [CODEX, AGY]);
+    assert.ok(notesText(p).includes(BACKEND_META[AGY].health), 'agy health note present when agy is used');
+    assert.match(notesText(p), /two backends|both backends|two .*quota/i);
+  });
+
+  it('Delegated: codex executes the bounded sub-task', () => {
+    const p = planRecipe('delegated', det);
+    assert.equal(p.effective, 'delegated');
+    assert.equal(p.degraded, false);
+    assert.deepEqual(p.dispatch, [{ role: 'execute', backend: CODEX, display: 'codex' }]);
+  });
+});
+
+describe('planRecipe — codex only (agy needs-skill)', () => {
+  const det = detect(READY, NEEDS_SKILL);
+
+  it('Council → Reviewed(codex) with a stated reason', () => {
+    const p = planRecipe('council', det);
+    assert.equal(p.effective, 'reviewed');
+    assert.equal(p.degraded, true);
+    assert.equal(p.degradation[0].from, 'council');
+    assert.equal(p.degradation[0].to, 'reviewed');
+    assert.match(p.degradation[0].reason, /not installed/i);
+    assert.deepEqual(dispatchBackends(p), [CODEX]);
+  });
+
+  it('Delegated stays Delegated (codex provides execute and is ready)', () => {
+    const p = planRecipe('delegated', det);
+    assert.equal(p.effective, 'delegated');
+    assert.equal(p.degraded, false);
+  });
+
+  it('Reviewed → codex', () => {
+    assert.deepEqual(dispatchBackends(planRecipe('reviewed', det)), [CODEX]);
+  });
+});
+
+describe('planRecipe — agy only (codex needs-skill)', () => {
+  const det = detect(NEEDS_SKILL, READY);
+
+  it('Council → Reviewed(agy)', () => {
+    const p = planRecipe('council', det);
+    assert.equal(p.effective, 'reviewed');
+    assert.equal(p.degraded, true);
+    assert.deepEqual(dispatchBackends(p), [AGY]);
+    assert.ok(notesText(p).includes(BACKEND_META[AGY].health), 'agy health note present when agy is the reviewer');
+  });
+
+  it('Delegated → Solo (no backend provides execute) with the reason stated', () => {
+    const p = planRecipe('delegated', det);
+    assert.equal(p.effective, 'solo');
+    assert.equal(p.degraded, true);
+    assert.match(p.degradation[0].reason, /execute/i);
+    assert.deepEqual(p.dispatch, []);
+  });
+
+  it('Reviewed → agy', () => {
+    assert.deepEqual(dispatchBackends(planRecipe('reviewed', det)), [AGY]);
+  });
+});
+
+describe('planRecipe — none installed (both needs-skill)', () => {
+  const det = detect(NEEDS_SKILL, NEEDS_SKILL);
+  for (const id of ['reviewed', 'council', 'delegated']) {
+    it(`${id} → Solo, reason names the not-installed bridge skill`, () => {
+      const p = planRecipe(id, det);
+      assert.equal(p.effective, 'solo');
+      assert.equal(p.degraded, true);
+      assert.match(p.degradation.map((d) => d.reason).join(' '), /not installed/i);
+    });
+  }
+});
+
+describe('planRecipe — agy degraded (wrapper not on PATH)', () => {
+  const det = detect(READY, DEGRADED);
+
+  it('Reviewed → codex (agy not dispatchable); no agy health note (agy unused)', () => {
+    const p = planRecipe('reviewed', det);
+    assert.equal(p.effective, 'reviewed');
+    assert.equal(p.degraded, false);
+    assert.deepEqual(dispatchBackends(p), [CODEX]);
+    assert.ok(!notesText(p).includes(BACKEND_META[AGY].health));
+  });
+
+  it('Council → Reviewed(codex); the degradation reason is the wrapper one (distinct from the health note)', () => {
+    const p = planRecipe('council', det);
+    assert.equal(p.effective, 'reviewed');
+    assert.equal(p.degraded, true);
+    assert.match(p.degradation[0].reason, /PATH|wrapper/i);
+    assert.deepEqual(dispatchBackends(p), [CODEX]);
+  });
+});
+
+describe('planRecipe — purity + determinism', () => {
+  it('is deterministic: same detection → deeply-equal plan', () => {
+    const det = detect(READY, NEEDS_CREDENTIALS);
+    assert.deepEqual(planRecipe('council', det), planRecipe('council', det));
+  });
+  it('does not mutate the detection input', () => {
+    const det = detect(READY, READY);
+    const snapshot = JSON.parse(JSON.stringify(det));
+    planRecipe('council', det);
+    assert.deepEqual(det, snapshot);
+  });
+});
+
+// ── recommendRecipe ──────────────────────────────────────────────────────────────
+
+describe('recommendRecipe — never blank; the everyday default', () => {
+  it('both ready → Council available, Reviewed the everyday default', () => {
+    const r = recommendRecipe(detect(READY, READY));
+    assert.equal(r.recipe, 'council');
+    assert.match(r.clause, /council/i);
+    assert.match(r.clause, /reviewed/i);
+  });
+
+  it('one ready → Reviewed', () => {
+    const r = recommendRecipe(detect(READY, NEEDS_SKILL));
+    assert.equal(r.recipe, 'reviewed');
+    assert.match(r.clause, /reviewed/i);
+  });
+
+  it('none installed → Solo + a setup pointer', () => {
+    const r = recommendRecipe(detect(NEEDS_SKILL, NEEDS_SKILL));
+    assert.equal(r.recipe, 'solo');
+    assert.match(r.clause, /solo/i);
+    assert.match(r.clause, /\/agent-workflow-kit setup/);
+  });
+
+  it('present-but-not-ready → Solo with the specific remedy', () => {
+    const r = recommendRecipe(detect(NEEDS_CLI, NEEDS_SKILL));
+    assert.equal(r.recipe, 'solo');
+    assert.match(r.clause, /CLI|cli/);
+  });
+
+  it('the clause is never empty', () => {
+    for (const det of [
+      detect(READY, READY),
+      detect(READY, NEEDS_SKILL),
+      detect(NEEDS_SKILL, NEEDS_SKILL),
+      detect(NEEDS_CREDENTIALS, DEGRADED),
+    ]) {
+      assert.ok(recommendRecipe(det).clause.trim().length > 0);
+    }
+  });
+
+  it('present-but-not-ready tie-break is deterministic (codex before agy) regardless of detection order', () => {
+    // Both present-but-not-ready at the SAME readiness rank → the remedy must name codex, not whichever
+    // the detector happened to emit first (mirrors the dispatch-path priority).
+    const forward = recommendRecipe([{ name: CODEX, readiness: DEGRADED }, { name: AGY, readiness: DEGRADED }]);
+    const reversed = recommendRecipe([{ name: AGY, readiness: DEGRADED }, { name: CODEX, readiness: DEGRADED }]);
+    assert.equal(forward.clause, reversed.clause, 'order-independent');
+    assert.match(forward.clause, /codex/, 'ties break to codex');
+  });
+});
+
+// ── CLI / formatRecipes ──────────────────────────────────────────────────────────
+
+describe('formatRecipes — deterministic advisor text', () => {
+  it('renders the four recipes + a recommendation deterministically', () => {
+    const det = detect(READY, NEEDS_SKILL);
+    const once = formatRecipes(det);
+    assert.equal(once, formatRecipes(det), 'same detection → identical text');
+    for (const title of ['Solo', 'Reviewed', 'Council', 'Delegated']) assert.match(once, new RegExp(title));
+  });
+});
+
+describe('recipes.mjs CLI — read-only, exit 0', () => {
+  it('prints the recipes and exits 0', () => {
+    const out = execFileSync(process.execPath, [SCRIPT], { encoding: 'utf8', env: { ...process.env, PATH: '' } });
+    for (const title of ['Solo', 'Reviewed', 'Council', 'Delegated']) assert.match(out, new RegExp(title));
+  });
+  it('--json emits parseable JSON with the recommendation', () => {
+    const out = execFileSync(process.execPath, [SCRIPT, '--json'], { encoding: 'utf8', env: { ...process.env, PATH: '' } });
+    const parsed = JSON.parse(out);
+    assert.ok(Array.isArray(parsed.recipes));
+    assert.ok(parsed.recommendation && typeof parsed.recommendation.recipe === 'string');
+  });
+});

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');
+  });
+});