@dalzoubi/dev-agents-sync 2.0.17 → 2.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "2.0.17",
+  "version": "2.0.19",
   "type": "module",
   "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
   "license": "UNLICENSED",

package/src/commands/update.mjs

@@ -5,7 +5,7 @@
  * and rewrites managed files for the recorded targets.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 
@@ -33,6 +33,71 @@ function filterFileMapByTargets(fileMap, targets) {
   return out;
 }
 
+// Maps a lockfile target key to the consumer subdirectory it owns. Only these
+// directories are ever scanned for orphans — pruning never crosses into another
+// target's tree or the repo root. Mirrors writer.mjs TARGET_PREFIX, restricted
+// to the targets that have a dedicated managed directory ('root'/'codex' are
+// out of scope by design — root-level files are never pruned).
+const PRUNE_TARGET_DIR = {
+  claude: '.claude',
+  cursor: '.cursor',
+  copilot: '.github',
+};
+
+/**
+ * Computes the set of marker-bearing managed files that are present on disk
+ * under the active target directories but absent from the freshly-fetched
+ * `scoped` file-map. Those are orphans to delete.
+ *
+ * Returns consumer-relative POSIX paths (e.g. ".claude/agents/old.md"),
+ * deterministically sorted. Unmarked files are never included (consumer-owned).
+ */
+function computeOrphans(consumerCwd, scopedKeys, targets) {
+  const orphans = [];
+  for (const target of targets) {
+    const subdir = PRUNE_TARGET_DIR[target];
+    if (!subdir) continue; // target has no managed dir (root/codex) — never scan.
+    const targetRoot = path.join(consumerCwd, subdir);
+    if (!existsSync(targetRoot)) continue;
+
+    walkFiles(targetRoot, (absPath) => {
+      let content;
+      try {
+        content = readFileSync(absPath, 'utf8');
+      } catch {
+        // Unreadable entry (e.g. removed mid-walk) — skip; never treat as orphan.
+        return;
+      }
+      // Never touch files without the managed-by marker — consumer owns them.
+      if (!hasMarker(content)) return;
+
+      // Reconstruct the target-prefixed relKey the fetch would have used,
+      // e.g. ".claude/agents/old.md" -> "claude/agents/old.md".
+      const rel = path.relative(targetRoot, absPath).split(path.sep).join('/');
+      const relKey = `${target}/${rel}`;
+      if (scopedKeys.has(relKey)) return; // still shipped — keep it.
+
+      // Consumer-relative path for reporting/deletion bookkeeping.
+      orphans.push(`${subdir}/${rel}`);
+    });
+  }
+  orphans.sort();
+  return orphans;
+}
+
+/** Depth-first walk invoking `onFile(absPath)` for every regular file under `dir`. */
+function walkFiles(dir, onFile) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(full, onFile);
+    } else if (entry.isFile()) {
+      onFile(full);
+    }
+  }
+}
+
 export async function runUpdate(consumerCwd, opts = {}) {
   const {
     force = false,
@@ -113,6 +178,12 @@ export async function runUpdate(consumerCwd, opts = {}) {
     : null;
   const claudeMdPath = path.join(consumerCwd, 'CLAUDE.md');
 
+  // Orphan set: marker-bearing managed files under active target dirs that the
+  // fetch no longer ships. Computed from the scoped keys so it honors the same
+  // target scoping as the writes.
+  const scopedKeys = new Set(Object.keys(scoped));
+  const orphans = computeOrphans(consumerCwd, scopedKeys, lock.targets);
+
   if (dryRun) {
     // Compute the planned CLAUDE.md change so callers can inspect it without
     // the result shape silently diverging from the init --dry-run contract.
@@ -125,6 +196,7 @@ export async function runUpdate(consumerCwd, opts = {}) {
       previousVersion: lock.resolvedVersion,
       files: plannedWrites.map(({ relKey }) => relKey),
       claudeMd: claudeMdResult,
+      plannedPrune: orphans,
       steering,
     };
   }
@@ -174,6 +246,31 @@ export async function runUpdate(consumerCwd, opts = {}) {
     }
   }
 
+  // Prune orphans: marker-bearing managed files no longer shipped. Delete in
+  // sorted order (computeOrphans returns sorted) before the lockfile is rewritten
+  // so a delete failure aborts that file and leaves the lockfile untouched (never
+  // corrupted). A failure surfaces a generic, actionable error naming the path.
+  const pruned = [];
+  for (const relPath of orphans) {
+    const absPath = path.join(consumerCwd, relPath);
+    try {
+      rmSync(absPath, { force: false });
+    } catch (cause) {
+      const err = new Error(
+        `failed to prune orphaned managed file ${relPath} (${absPath}). ` +
+          `Check filesystem permissions and remove it manually, then re-run update.`,
+      );
+      err.exitCode = 1;
+      err.cause = cause;
+      throw err;
+    }
+    pruned.push(relPath);
+  }
+  const pruneSummary = `pruned ${pruned.length} orphaned managed file(s)`;
+  if (pruned.length > 0) {
+    process.stderr.write(`info: dev-agents-sync: ${pruneSummary}\n`);
+  }
+
   writeLockfile(consumerCwd, {
     source: lock.source,
     range: lock.range,
@@ -194,6 +291,9 @@ export async function runUpdate(consumerCwd, opts = {}) {
     previousVersion: lock.resolvedVersion,
     files: plannedWrites.map(({ relKey }) => relKey),
     hooks: hookPaths,
+    pruned,
+    prunedCount: pruned.length,
+    summary: pruneSummary,
     steering,
   };
 }

package/tests/steering-agent-behavior.test.mjs

@@ -78,18 +78,22 @@ let mirrorDefineContent;
 let mirrorImplementContent;
 
 before(() => {
+  // Post-S6 hard cutover: the old roster was relocated to the define/deliver
+  // topology. The steering-behavior contract moved with it —
+  // implement→deliver-solution, analyze→define-analyze, test→deliver-test,
+  // validate→deliver-validate, supervise→deliver. define stays.
   defineContent = readFileSync(path.join(AGENTS_DIR, 'define.md'), 'utf8');
-  implementContent = readFileSync(path.join(AGENTS_DIR, 'implement.md'), 'utf8');
-  analyzeContent = readFileSync(path.join(AGENTS_DIR, 'analyze.md'), 'utf8');
-  testContent = readFileSync(path.join(AGENTS_DIR, 'test.md'), 'utf8');
-  validateContent = readFileSync(path.join(AGENTS_DIR, 'validate.md'), 'utf8');
-  superviseContent = readFileSync(path.join(AGENTS_DIR, 'supervise.md'), 'utf8');
+  implementContent = readFileSync(path.join(AGENTS_DIR, 'deliver-solution.md'), 'utf8');
+  analyzeContent = readFileSync(path.join(AGENTS_DIR, 'define-analyze.md'), 'utf8');
+  testContent = readFileSync(path.join(AGENTS_DIR, 'deliver-test.md'), 'utf8');
+  validateContent = readFileSync(path.join(AGENTS_DIR, 'deliver-validate.md'), 'utf8');
+  superviseContent = readFileSync(path.join(AGENTS_DIR, 'deliver.md'), 'utf8');
 
   mirrorDefineContent = existsSync(path.join(MIRROR_DIR, 'define.md'))
     ? readFileSync(path.join(MIRROR_DIR, 'define.md'), 'utf8')
     : '';
-  mirrorImplementContent = existsSync(path.join(MIRROR_DIR, 'implement.md'))
-    ? readFileSync(path.join(MIRROR_DIR, 'implement.md'), 'utf8')
+  mirrorImplementContent = existsSync(path.join(MIRROR_DIR, 'deliver-solution.md'))
+    ? readFileSync(path.join(MIRROR_DIR, 'deliver-solution.md'), 'utf8')
     : '';
 });
 

package/tests/supervise-estimate-provenance.test.mjs

@@ -26,7 +26,8 @@ import path from 'node:path';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '../../..');
-const SUPERVISE_MD = path.join(REPO_ROOT, '.agents', 'agents', 'supervise.md');
+// Post-S6 hard cutover: supervise relocated to the deliver orchestrator.
+const SUPERVISE_MD = path.join(REPO_ROOT, '.agents', 'agents', 'deliver.md');
 
 let content;
 

package/tests/update-prune.test.mjs

@@ -0,0 +1,686 @@
+/**
+ * tests/update-prune.test.mjs
+ *
+ * Behavior-anchored tests for the orphan-pruning feature of `runUpdate`.
+ *
+ * SLICE: cli-orphan-pruning
+ *
+ * These tests are written RED-first. They will FAIL until `update.mjs` gains
+ * the pruning logic described below. They are intentionally NOT "does code run"
+ * tests — each assertion guards a specific observable behavior that would break
+ * if the feature regressed.
+ *
+ * ASSUMED API CONTRACT (for the implement agent to match):
+ *
+ *   result = await runUpdate(consumerDir, { fetcher, availableTags, ... })
+ *
+ *   result.pruned       — string[] of consumer-relative paths that were deleted
+ *                         (e.g. [".claude/agents/old-agent.md"])
+ *   result.prunedCount  — number: result.pruned.length (convenience field)
+ *   result.summary      — string containing a one-line prune summary, e.g.
+ *                         "pruned 1 orphaned managed file(s)"
+ *                         (must include the count and the word "pruned")
+ *
+ *   Under --dry-run:
+ *   result.plannedPrune — string[] of paths that WOULD be deleted (not deleted)
+ *                         OR result.pruned contains those paths (same entries as
+ *                         a live run, but nothing was removed from disk).
+ *                         (implement agent may choose either field name — but at
+ *                         least one of result.pruned or result.plannedPrune must
+ *                         carry the orphan list and the file must NOT be deleted.)
+ *
+ * SCOPING RULE (what counts as a managed target dir):
+ *   - "claude"  →  <consumerDir>/.claude/
+ *   - "cursor"  →  <consumerDir>/.cursor/
+ *   - "copilot" →  <consumerDir>/.github/
+ *
+ *   Only directories whose target key is in `lock.targets` are scanned for orphans.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+  readdirSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runUpdate } from '../src/commands/update.mjs';
+import { writeLockfile } from '../src/lockfile.mjs';
+import { hasMarker } from '../src/marker.mjs';
+
+// ---------------------------------------------------------------------------
+// Fixture helpers (mirrors update.test.mjs conventions exactly)
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+
+function readFixtureContent(relativePath) {
+  return readFileSync(path.join(FIXTURE_DIR, relativePath), 'utf8');
+}
+
+/**
+ * Builds a FileMap from the fixture directory for the given targets.
+ * Keys are prefixed with target name: "claude/agents/define.md", etc.
+ */
+function buildFixtureFileMap(targets = ['claude', 'cursor', 'copilot']) {
+  const map = {};
+  for (const target of targets) {
+    const targetDir = path.join(FIXTURE_DIR, target);
+    if (!existsSync(targetDir)) continue;
+    collectFiles(targetDir, targetDir, map, target);
+  }
+  return map;
+}
+
+function collectFiles(baseDir, currentDir, map, prefix) {
+  const entries = readdirSync(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(baseDir, full, map, prefix);
+    } else {
+      const rel = path.relative(baseDir, full).replace(/\\/g, '/');
+      map[`${prefix}/${rel}`] = readFileSync(full, 'utf8');
+    }
+  }
+}
+
+/**
+ * Fetcher that returns the v1.0.0 fixture content but with only `define.md`
+ * in the claude/agents/ directory (omitting `test.md`).
+ *
+ * This simulates a release that DROPPED test.md — so any pre-existing
+ * test.md in the consumer is an orphan.
+ */
+function makeReducedFetcher() {
+  return async (_repo, _tag, _token) => {
+    const fileMap = {};
+    // Include define.md but NOT test.md — test.md is the "orphaned" file.
+    fileMap['claude/agents/define.md'] = readFixtureContent('claude/agents/define.md').replace(
+      /<!-- managed-by: dev-agents-sync v[\d.]+ -->/,
+      '<!-- managed-by: dev-agents-sync v1.2.0 -->',
+    );
+    // Also include commands to give the update something to write
+    fileMap['claude/commands/preflight.md'] = readFixtureContent(
+      'claude/commands/preflight.md',
+    ).replace(
+      /<!-- managed-by: dev-agents-sync v[\d.]+ -->/,
+      '<!-- managed-by: dev-agents-sync v1.2.0 -->',
+    );
+    return fileMap;
+  };
+}
+
+/**
+ * Fetcher that returns the full v1.2.0 fixture set (no files dropped).
+ * Used for the "no orphans" baseline and for confirming unmanaged files survive.
+ */
+function makeFullFetcher() {
+  return async (_repo, _tag, _token) => {
+    const base = buildFixtureFileMap(['claude']);
+    const updated = {};
+    for (const [key, content] of Object.entries(base)) {
+      updated[key] = content.replace(
+        /<!-- managed-by: dev-agents-sync v[\d.]+ -->/,
+        '<!-- managed-by: dev-agents-sync v1.2.0 -->',
+      );
+    }
+    return updated;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-prune-test-'));
+}
+
+/**
+ * Sets up a consumer repo with:
+ *   - lockfile pinned to resolvedVersion (triggers a version bump to 1.2.0)
+ *   - .claude/agents/define.md   (managed — will be kept)
+ *   - .claude/agents/test.md     (managed — will be orphaned when fetcher omits it)
+ *   - .claude/commands/preflight.md (managed — will be kept)
+ */
+async function setupRepoWithOrphan(consumerDir, opts = {}) {
+  const { targets = ['claude'], resolvedVersion = '1.0.0' } = opts;
+
+  writeLockfile(consumerDir, {
+    source: 'github:dalzoubi/dev-agents',
+    range: '^1',
+    resolvedVersion,
+    targets,
+    lastUpdated: '2026-04-01T00:00:00Z',
+  });
+
+  if (targets.includes('claude')) {
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    const commandsDir = path.join(consumerDir, '.claude', 'commands');
+    mkdirSync(agentsDir, { recursive: true });
+    mkdirSync(commandsDir, { recursive: true });
+
+    // define.md: managed (present in the next fetch → KEPT)
+    writeFileSync(
+      path.join(agentsDir, 'define.md'),
+      readFixtureContent('claude/agents/define.md'),
+      'utf8',
+    );
+    // test.md: managed (ABSENT from the next fetch → ORPHAN to be deleted)
+    writeFileSync(
+      path.join(agentsDir, 'test.md'),
+      readFixtureContent('claude/agents/test.md'),
+      'utf8',
+    );
+    // preflight.md: managed (present in the next fetch → KEPT)
+    writeFileSync(
+      path.join(commandsDir, 'preflight.md'),
+      readFixtureContent('claude/commands/preflight.md'),
+      'utf8',
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Verify the fixture files have the managed-by marker — if this fails, the
+// fixture is broken, not our test. Keeps error messages clear.
+// ---------------------------------------------------------------------------
+
+{
+  const defineContent = readFixtureContent('claude/agents/define.md');
+  const testContent = readFixtureContent('claude/agents/test.md');
+  if (!hasMarker(defineContent)) throw new Error('fixture: define.md is missing managed-by marker');
+  if (!hasMarker(testContent)) throw new Error('fixture: test.md is missing managed-by marker');
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: Orphan in a managed dir is DELETED after update
+// ---------------------------------------------------------------------------
+
+describe('update — orphan pruning: deletes marker-bearing orphan files', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('deletes a managed orphan file that is absent from the fetched set', async () => {
+    // Behavior: after update, .claude/agents/test.md is absent from the fetcher
+    // response. Because it bears the managed-by marker, update must DELETE it.
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+
+    const orphanPath = path.join(consumerDir, '.claude', 'agents', 'test.md');
+
+    // Pre-condition: file exists before update
+    assert.ok(existsSync(orphanPath), 'test setup: test.md must exist before update');
+
+    await runUpdate(consumerDir, {
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    // POST-CONDITION (the behavior this test guards):
+    // The orphan must be deleted because it bore the marker and was absent from the fetch.
+    assert.ok(
+      !existsSync(orphanPath),
+      '.claude/agents/test.md must be deleted after update when absent from fetched set',
+    );
+  });
+
+  it('result.pruned includes the deleted orphan path', async () => {
+    // Behavior: the return value of runUpdate must carry an array of deleted paths
+    // so the caller / CLI can log what was removed.
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+
+    const result = await runUpdate(consumerDir, {
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok(
+      Array.isArray(result.pruned),
+      `result.pruned must be an array, got: ${JSON.stringify(result?.pruned)}`,
+    );
+    assert.ok(
+      result.pruned.length > 0,
+      `result.pruned must contain at least one entry, got empty array`,
+    );
+    // The path must be identifiable as pointing at test.md
+    const hasPrunedEntry = result.pruned.some(
+      (p) => p.includes('test.md') || p.includes('agents'),
+    );
+    assert.ok(
+      hasPrunedEntry,
+      `result.pruned must mention test.md or agents dir, got: ${JSON.stringify(result.pruned)}`,
+    );
+  });
+
+  it('result.prunedCount equals the number of deleted files', async () => {
+    // Behavior: result.prunedCount (convenience count) must match result.pruned.length.
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+
+    const result = await runUpdate(consumerDir, {
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok(
+      typeof result.prunedCount === 'number',
+      `result.prunedCount must be a number, got: ${typeof result.prunedCount}`,
+    );
+    assert.equal(
+      result.prunedCount,
+      result.pruned?.length ?? -1,
+      'result.prunedCount must equal result.pruned.length',
+    );
+    assert.ok(result.prunedCount > 0, 'prunedCount must be > 0 when an orphan exists');
+  });
+
+  it('result includes a summary mentioning "pruned" and the count', async () => {
+    // Behavior: result.summary is a human-readable one-line string that tells the
+    // operator how many files were pruned so CLI/stdout can surface it.
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+
+    const result = await runUpdate(consumerDir, {
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok(
+      typeof result.summary === 'string' && result.summary.length > 0,
+      `result.summary must be a non-empty string, got: ${JSON.stringify(result.summary)}`,
+    );
+    assert.ok(
+      /pruned/i.test(result.summary),
+      `result.summary must contain "pruned", got: "${result.summary}"`,
+    );
+    assert.ok(
+      /1/.test(result.summary),
+      `result.summary must mention the count (1), got: "${result.summary}"`,
+    );
+  });
+
+  it('non-orphan managed files are not deleted', async () => {
+    // Behavior: define.md IS in the fetched set — it must remain on disk untouched.
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+
+    const definePath = path.join(consumerDir, '.claude', 'agents', 'define.md');
+    const preflightPath = path.join(consumerDir, '.claude', 'commands', 'preflight.md');
+
+    await runUpdate(consumerDir, {
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok(existsSync(definePath), 'define.md must NOT be deleted — it is in the fetched set');
+    assert.ok(
+      existsSync(preflightPath),
+      'preflight.md must NOT be deleted — it is in the fetched set',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test 2: UNMARKED files in the same dir are PRESERVED (never deleted)
+// ---------------------------------------------------------------------------
+
+describe('update — orphan pruning: never deletes unmanaged (unmarked) files', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('a file without the managed-by marker is never deleted, even if absent from fetch', async () => {
+    // Behavior: consumer-owned files (no marker) must survive update no matter what.
+    // This is the "never touch unmarked files" contract from CLAUDE.md.
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+
+    // Add an unmarked file at the same level as the orphan-eligible files.
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    const unmanagedFile = path.join(agentsDir, 'my-custom-agent.md');
+    writeFileSync(unmanagedFile, '# My custom agent\nNo marker here — I own this.', 'utf8');
+
+    // Confirm no marker
+    const content = readFileSync(unmanagedFile, 'utf8');
+    assert.ok(!hasMarker(content), 'test setup: custom file must NOT have the managed-by marker');
+
+    await runUpdate(consumerDir, {
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    // POST-CONDITION: unmanaged file must still exist with original content
+    assert.ok(
+      existsSync(unmanagedFile),
+      'unmanaged file (no marker) must NOT be deleted during orphan pruning',
+    );
+    const afterContent = readFileSync(unmanagedFile, 'utf8');
+    assert.equal(
+      afterContent,
+      '# My custom agent\nNo marker here — I own this.',
+      'unmanaged file content must be byte-identical after update',
+    );
+  });
+
+  it('unmanaged file is not included in result.pruned', async () => {
+    // Behavior: only marker-bearing orphans appear in result.pruned.
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    const unmanagedFile = path.join(agentsDir, 'my-custom-agent.md');
+    writeFileSync(unmanagedFile, '# Custom — no marker', 'utf8');
+
+    const result = await runUpdate(consumerDir, {
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const pruned = result.pruned ?? [];
+    const unmanagedInPruned = pruned.some((p) => p.includes('my-custom-agent.md'));
+    assert.ok(
+      !unmanagedInPruned,
+      `unmanaged file must not appear in result.pruned, got: ${JSON.stringify(pruned)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test 3: --dry-run deletes NOTHING but reports the orphan
+// ---------------------------------------------------------------------------
+
+describe('update — orphan pruning: --dry-run preview without deletion', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('--dry-run does not delete the orphan file from disk', async () => {
+    // Behavior: dry-run must never modify the filesystem. The orphan must survive.
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+
+    const orphanPath = path.join(consumerDir, '.claude', 'agents', 'test.md');
+
+    await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok(
+      existsSync(orphanPath),
+      'orphan file must NOT be deleted in --dry-run mode',
+    );
+  });
+
+  it('--dry-run result reports the would-be-pruned orphan (plannedPrune or pruned)', async () => {
+    // Behavior: the caller must be able to see WHAT would be pruned without it
+    // actually being deleted. result.plannedPrune OR result.pruned must include
+    // the orphan path, and the file must still be on disk.
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+
+    const result = await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    // Either field name is accepted; the implement agent picks one.
+    const reportedOrphans = result.plannedPrune ?? result.pruned ?? [];
+
+    assert.ok(
+      Array.isArray(reportedOrphans),
+      `dry-run result must carry orphan list in plannedPrune or pruned, got: ${JSON.stringify(result)}`,
+    );
+    assert.ok(
+      reportedOrphans.length > 0,
+      'dry-run result must report at least one would-be-pruned path',
+    );
+    const hasTestMd = reportedOrphans.some((p) => p.includes('test.md'));
+    assert.ok(
+      hasTestMd,
+      `dry-run orphan list must include test.md, got: ${JSON.stringify(reportedOrphans)}`,
+    );
+  });
+
+  it('--dry-run with no orphans reports empty plannedPrune or pruned', async () => {
+    // Behavior: when nothing would be pruned, the list is empty (not undefined).
+    await setupRepoWithOrphan(consumerDir, { targets: ['claude'] });
+    // Remove the orphan pre-emptively so there is nothing to prune
+    rmSync(path.join(consumerDir, '.claude', 'agents', 'test.md'));
+
+    const result = await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeReducedFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const reportedOrphans = result.plannedPrune ?? result.pruned ?? [];
+    assert.ok(
+      Array.isArray(reportedOrphans),
+      'dry-run result must still have an array field for planned prunes even when empty',
+    );
+    assert.equal(
+      reportedOrphans.length,
+      0,
+      'no orphans should be reported when none exist on disk',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test 4: Pruning is scoped to active `targets` only
+// ---------------------------------------------------------------------------
+
+describe('update — orphan pruning: scoped to active targets only', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('a marker-bearing file under an inactive target directory is NOT deleted', async () => {
+    // Behavior: if lockfile.targets is ["claude"], orphan pruning must only scan
+    // .claude/. Files in .cursor/ or .github/ must be left alone even if they
+    // bear the managed-by marker and are absent from the fetch.
+    //
+    // Setup: targets=["claude"]; we manually plant a marker-bearing file in
+    // .cursor/rules/ (as if a previous cursor-target run wrote it). The current
+    // update has targets=["claude"] only, so .cursor/ is an inactive target and
+    // must never be touched.
+
+    // Write lockfile with claude-only targets
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+
+    // Plant managed files in .claude/ (active target)
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+    writeFileSync(
+      path.join(agentsDir, 'define.md'),
+      readFixtureContent('claude/agents/define.md'),
+      'utf8',
+    );
+
+    // Plant a marker-bearing file in .cursor/ (INACTIVE target)
+    const cursorRulesDir = path.join(consumerDir, '.cursor', 'rules');
+    mkdirSync(cursorRulesDir, { recursive: true });
+    // Build a synthetic cursor file with a managed-by marker on the first
+    // non-frontmatter body line (mimicking what a cursor-target init would write).
+    const cursorOrphanContent = `<!-- managed-by: dev-agents-sync v1.0.0 -->\n# define cursor rule\n`;
+    writeFileSync(path.join(cursorRulesDir, 'old-rule.mdc'), cursorOrphanContent, 'utf8');
+
+    // Confirm our cursor file is recognized as managed
+    assert.ok(
+      hasMarker(cursorOrphanContent),
+      'test setup: cursor orphan file must have the managed-by marker',
+    );
+
+    // Run update with a fetcher that omits all cursor content
+    // (only claude files are returned, matching the active target)
+    const claudeOnlyFetcher = async () => ({
+      'claude/agents/define.md': readFixtureContent('claude/agents/define.md').replace(
+        /<!-- managed-by: dev-agents-sync v[\d.]+ -->/,
+        '<!-- managed-by: dev-agents-sync v1.2.0 -->',
+      ),
+    });
+
+    await runUpdate(consumerDir, {
+      fetcher: claudeOnlyFetcher,
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    // POST-CONDITION: .cursor/rules/old-rule.mdc must be untouched.
+    // Pruning must NOT cross into an inactive target.
+    const cursorOrphanPath = path.join(cursorRulesDir, 'old-rule.mdc');
+    assert.ok(
+      existsSync(cursorOrphanPath),
+      '.cursor/rules/old-rule.mdc must NOT be deleted — cursor is not in active targets',
+    );
+    const afterContent = readFileSync(cursorOrphanPath, 'utf8');
+    assert.equal(
+      afterContent,
+      cursorOrphanContent,
+      '.cursor orphan file content must be byte-identical — inactive target must not be touched',
+    );
+  });
+
+  it('result.pruned does not include paths from inactive targets', async () => {
+    // Behavior: even if the implement agent walks the filesystem broadly,
+    // result.pruned must not list paths outside the active target dirs.
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+    writeFileSync(
+      path.join(agentsDir, 'define.md'),
+      readFixtureContent('claude/agents/define.md'),
+      'utf8',
+    );
+
+    const cursorRulesDir = path.join(consumerDir, '.cursor', 'rules');
+    mkdirSync(cursorRulesDir, { recursive: true });
+    writeFileSync(
+      path.join(cursorRulesDir, 'old-rule.mdc'),
+      `<!-- managed-by: dev-agents-sync v1.0.0 -->\n# old rule\n`,
+      'utf8',
+    );
+
+    const claudeOnlyFetcher = async () => ({
+      'claude/agents/define.md': readFixtureContent('claude/agents/define.md').replace(
+        /<!-- managed-by: dev-agents-sync v[\d.]+ -->/,
+        '<!-- managed-by: dev-agents-sync v1.2.0 -->',
+      ),
+    });
+
+    const result = await runUpdate(consumerDir, {
+      fetcher: claudeOnlyFetcher,
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const pruned = result.pruned ?? [];
+    const hasCursorEntry = pruned.some((p) => p.includes('.cursor') || p.includes('cursor'));
+    assert.ok(
+      !hasCursorEntry,
+      `result.pruned must not include .cursor/ paths (inactive target), got: ${JSON.stringify(pruned)}`,
+    );
+  });
+
+  it('prunes from multiple active targets simultaneously', async () => {
+    // Behavior: when targets=["claude","cursor"] both dirs are scanned.
+    // Orphans in BOTH active target dirs must be pruned in one update call.
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude', 'cursor'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+
+    // Active: .claude/
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+    writeFileSync(
+      path.join(agentsDir, 'define.md'),
+      readFixtureContent('claude/agents/define.md'),
+      'utf8',
+    );
+    // Orphan in .claude/ — managed but absent from fetch
+    writeFileSync(
+      path.join(agentsDir, 'old-claude-agent.md'),
+      `<!-- managed-by: dev-agents-sync v1.0.0 -->\n# old claude agent\n`,
+      'utf8',
+    );
+
+    // Active: .cursor/
+    const rulesDir = path.join(consumerDir, '.cursor', 'rules');
+    mkdirSync(rulesDir, { recursive: true });
+    // Orphan in .cursor/ — managed but absent from fetch
+    writeFileSync(
+      path.join(rulesDir, 'old-cursor-rule.mdc'),
+      `<!-- managed-by: dev-agents-sync v1.0.0 -->\n# old cursor rule\n`,
+      'utf8',
+    );
+
+    // Fetcher returns define.md for claude and nothing for cursor
+    const multiTargetFetcher = async () => ({
+      'claude/agents/define.md': readFixtureContent('claude/agents/define.md').replace(
+        /<!-- managed-by: dev-agents-sync v[\d.]+ -->/,
+        '<!-- managed-by: dev-agents-sync v1.2.0 -->',
+      ),
+    });
+
+    await runUpdate(consumerDir, {
+      fetcher: multiTargetFetcher,
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    // Both orphans must be deleted
+    assert.ok(
+      !existsSync(path.join(agentsDir, 'old-claude-agent.md')),
+      '.claude orphan must be deleted when claude is an active target',
+    );
+    assert.ok(
+      !existsSync(path.join(rulesDir, 'old-cursor-rule.mdc')),
+      '.cursor orphan must be deleted when cursor is an active target',
+    );
+  });
+});