@jenga-ai/agent 2.0.0 → 3.1.0

package/scripts/postinstall.js

@@ -24,7 +24,86 @@
  *
  * The actual filesystem mirror is delegated to `lib/mirror.js`, which is the
  * single source of truth shared with the in-repo `/self-sync` skill. Consumer
- * install always uses `reconcileDeletes: false` (additive-only).
+ * install always uses `reconcileDeletes: false` (additive-only) — that flag diffs
+ * the destination's current contents against the source tree with no notion of who
+ * wrote a given file, so enabling it here would delete a consumer's own custom
+ * skills. It is deliberately left off; see the manifest mechanism below.
+ *
+ * Upgrade cleanup — manifest-based delete reconciliation (E26_S08_T01)
+ * ────────────────────────────────────────────────────────────────────
+ * Additive-only mirroring means a release that renames, removes, or excludes a
+ * skill leaves the previously installed copies in the consumer's mirror roots
+ * forever, so old and new forms both keep loading. To clean those up *without*
+ * risking consumer-authored files, each run records what it wrote and the next run
+ * removes only what it itself wrote last time and did not write again.
+ *
+ *   Location : one manifest per destination root, inside that root —
+ *                <consumer>/.agents/.jenga-postinstall-manifest.json
+ *                <consumer>/.claude/.jenga-postinstall-manifest.json
+ *              Keeping it inside the root it describes means it travels with that
+ *              mirror; moving or renaming the consumer project cannot desync it.
+ *
+ *   Format   : {
+ *                "manifest_version": 1,
+ *                "package":          "@jenga-ai/agent",
+ *                "package_version":  "3.0.1",
+ *                "generated_at":     "<ISO 8601>",
+ *                "dest_root":        ".agents",
+ *                "paths":            ["agents/developer.md", "skills/do/SKILL.md"]
+ *              }
+ *              `paths` are relative to the destination root, POSIX-separated,
+ *              deduped and sorted, and record REGULAR FILES ONLY — never
+ *              directories. Directory removal is derived by pruning parents that
+ *              become empty, which is precisely why a directory still holding a
+ *              consumer file is never removed.
+ *
+ *   Rule     : a path is deleted only if a manifest previously written by THIS
+ *              package's postinstall lists it AND the current run did not write it.
+ *              If no prior manifest exists, see the legacy-path seeding note below —
+ *              "we don't know what we wrote before" is never treated as "delete
+ *              everything we didn't just write". Every parse/IO failure likewise
+ *              degrades to additive-only.
+ *
+ *   Skipped   : if any `copySet` entry is missing from the package (a packaging
+ *              regression), BOTH the delete pass and the manifest write are skipped
+ *              for that run — otherwise the run would under-report what it wrote and
+ *              read an entire mirrored subtree as stale. The previous manifest is
+ *              left in place because it still describes what is on disk.
+ *
+ * Legacy-path seeding — first-manifest orphan cleanup (E26_S08_T03)
+ * ────────────────────────────────────────────────────────────────────
+ * T01's rule above is purely forward-looking: a consumer already installed BEFORE any
+ * manifest existed takes the `no-prior-manifest` branch on their first run of a fixed
+ * version, and the manifest that run writes records only what that one run mirrored —
+ * pre-existing orphans (e.g. a retired `j:`-form skill, an excluded `j-<name>` twin)
+ * were never in it, so they could never become deletion candidates on any FUTURE
+ * upgrade either. Confirmed empirically against a throwaway fixture, not merely
+ * reasoned about: such a file survived two upgrades, the second with an active delete
+ * pass, appearing 0 times in either manifest.
+ *
+ * On the `no-prior-manifest` branch, this run now additionally seeds a SYNTHETIC prior
+ * path list from `lib/legacy-shipped-paths.json` — a static, package-shipped list of
+ * paths known to have shipped in some real prior published version (see
+ * `scripts/generate-legacy-shipped-paths.js`) — intersected with what is ACTUALLY a
+ * regular file on disk in that mirror root right now
+ * (`seedFromLegacyPaths` in `lib/postinstall-manifest.js`). If anything seeds, it is
+ * reconciled against THIS run's copy set immediately (adopt-then-reconcile), so the
+ * cleanup lands on the very upgrade that introduces this feature rather than one cycle
+ * later. Provenance stays the entire compensating control: a path absent from every
+ * published version's file list is never in `lib/legacy-shipped-paths.json`, so it can
+ * never be seeded, regardless of where it sits in the mirror root — a consumer's own
+ * hand-authored file was never in any published version and stays untouchable exactly
+ * as before. A genuine first-ever install has nothing on disk to intersect with, so the
+ * seed set is naturally empty and this falls straight through to the additive-only
+ * behaviour — no separate "is this a first install" branch is needed for that to hold.
+ * The seeded reconciliation reuses the EXACT SAME boundary/type-checked delete engine
+ * as the manifest-backed path (`reconcileWithPriorPaths` shares its core with
+ * `reconcileFromManifest`), so invariants 3, 4, and 5 apply unchanged over seeded
+ * candidates too.
+ *
+ * Implementation lives in `lib/postinstall-manifest.js` (full rationale + safety
+ * invariants documented there) and `scripts/generate-legacy-shipped-paths.js` (legacy
+ * path list generation); consumer-facing docs in `docs/distribution.md`.
  */
 
 import fs   from 'node:fs';
@@ -32,7 +111,16 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { mirror } from '../lib/mirror.js';
+import {
+  toRelativePaths,
+  reconcileFromManifest,
+  reconcileWithPriorPaths,
+  seedFromLegacyPaths,
+  writeManifest,
+} from '../lib/postinstall-manifest.js';
+import { readLegacyShippedPaths } from './generate-legacy-shipped-paths.js';
 import { generateCopilotInstructions } from '../lib/generate-copilot-instructions.js';
+import { generateCopilotHooks } from '../lib/generate-copilot-hooks.js';
 import { generateSkillAllowList } from '../lib/generate-skill-allow-list.js';
 
 // ESM equivalent of __dirname
@@ -73,10 +161,12 @@ function main() {
 
   // Read this package's version
   let packageVersion = '0.0.0';
+  let packageName    = '';
   try {
     const pkgPath = path.join(packageRoot, 'package.json');
     const pkg     = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
     packageVersion = pkg.version || '0.0.0';
+    packageName    = pkg.name || '';
   } catch (_) {
     // non-fatal — proceed with default
   }
@@ -120,14 +210,36 @@ function main() {
   // Warn about any copySet entries that are missing from the package — the
   // helper silently skips missing sources, so we surface it here for parity
   // with the previous UX.
+  const missingEntries = [];
   for (const entry of copySet) {
     if (!fs.existsSync(path.join(packageRoot, entry))) {
       console.log(`  ⚠  ${entry}/ not found in package — skipped`);
+      missingEntries.push(entry);
     }
   }
 
+  // A copySet entry missing from the package is a PACKAGING regression, not a signal
+  // that the consumer should lose those files. mirror() silently skips a missing
+  // source, so `currentPaths` would under-report everything under that entry and the
+  // delete pass would read the whole mirrored subtree as stale and wipe it — turning
+  // a bad publish into mass deletion on every consumer that installs it.
+  //
+  // So when anything is missing we skip BOTH the delete pass and the manifest write.
+  // Leaving the previous manifest untouched is deliberate: it still accurately
+  // describes what is on disk (those files are still there, just not refreshed), so a
+  // later healthy release reconciles correctly against it. Writing an under-reporting
+  // manifest here would merely defer the same mass delete to the next run.
+  const reconcileSafe = missingEntries.length === 0;
+  if (!reconcileSafe) {
+    console.log(
+      `  ⚠  Upgrade cleanup skipped — ${missingEntries.join(', ')} missing from the package. ` +
+      'Existing mirrored files are left untouched.'
+    );
+  }
+
   let totalCopied  = 0;
   let totalSkipped = 0;
+  let totalDeleted = 0;
 
   for (const targetRoot of targetRoots) {
     const destRoot = path.join(consumerRoot, targetRoot);
@@ -151,6 +263,82 @@ function main() {
       console.log(`  ✓ ${targetRoot}/${entry}/ — ${wrote} file(s) copied`);
     }
 
+    // ── Manifest-based delete reconciliation (E26_S08_T01) ───────────────────
+    // The copy set for manifest purposes is added + overwritten + SKIPPED. Including
+    // `skipped` is essential, not incidental: a file that was byte-identical and
+    // therefore skipped by mirror() is still a package-owned path, and leaving it out
+    // would make the very next run classify it as stale and delete it.
+    const currentPaths = toRelativePaths(destRoot, [
+      ...result.added,
+      ...result.overwritten,
+      ...result.skipped,
+    ]);
+
+    // Deletes only ever touch paths a manifest we ourselves wrote lists and this run
+    // did not rewrite. No prior manifest => see the E26_S08_T03 seeding branch below.
+    try {
+      let recon = reconcileSafe
+        ? reconcileFromManifest({ destRoot, currentPaths })
+        : { deleted: [], prunedDirs: [], refused: [], reason: 'skipped-incomplete-package' };
+
+      // ── Legacy-path seeding (E26_S08_T03) ───────────────────────────────────
+      // reconcileFromManifest returned 'no-prior-manifest' — this is either a genuine
+      // first-ever install, OR a consumer already installed before this manifest
+      // mechanism (E26_S08_T01) existed. The two are indistinguishable from a manifest
+      // alone, which is exactly the gap T03 closes: seed a SYNTHETIC prior-path list from
+      // this package's known-shipped legacy paths, intersected with what is ACTUALLY a
+      // regular file on disk right now (seedFromLegacyPaths never seeds a path that isn't
+      // really there), then reconcile against that seed in THIS SAME run
+      // (adopt-then-reconcile) rather than waiting one more upgrade cycle. A genuine
+      // first-ever install has nothing on disk to intersect with, so the seed set is
+      // naturally empty and this falls straight through to the additive-only branch below
+      // — no separate first-install check is needed for that to hold.
+      if (reconcileSafe && recon.reason === 'no-prior-manifest') {
+        const legacyPathsFile = path.join(packageRoot, 'lib', 'legacy-shipped-paths.json');
+        const legacyPaths = readLegacyShippedPaths(legacyPathsFile);
+        const seeded = seedFromLegacyPaths({ destRoot, legacyPaths });
+        if (seeded.length > 0) {
+          const seedRecon = reconcileWithPriorPaths({ destRoot, priorPaths: seeded, currentPaths });
+          // Only surface this as a distinct outcome if the seed actually produced
+          // something to report. A seeded path that is STILL part of this run's own
+          // currentPaths (e.g. a legacy path this release still ships) is neither
+          // stale nor refused — nothing happened, so the plain "no previous install
+          // manifest" additive-only message stays accurate and must not be hidden by
+          // an outcome-less 'seeded-reconciled' relabel.
+          if (seedRecon.deleted.length > 0 || seedRecon.prunedDirs.length > 0 || seedRecon.refused.length > 0) {
+            recon = { ...seedRecon, reason: 'seeded-reconciled' };
+          }
+        }
+      }
+
+      if (recon.reason === 'skipped-incomplete-package') {
+        // already reported once above, per-run rather than per-root
+      } else if (recon.reason === 'no-prior-manifest') {
+        console.log(`  ℹ  ${targetRoot}/ — no previous install manifest; additive copy only (no deletes)`);
+      } else if (recon.deleted.length > 0 || recon.prunedDirs.length > 0) {
+        const suffix = recon.reason === 'seeded-reconciled' ? ' (seeded from known-shipped legacy paths)' : '';
+        console.log(
+          `  ✓ ${targetRoot}/ — ${recon.deleted.length} stale file(s) removed${suffix}` +
+          (recon.prunedDirs.length ? `, ${recon.prunedDirs.length} empty dir(s) pruned` : '')
+        );
+        totalDeleted += recon.deleted.length;
+      }
+      for (const r of recon.refused) {
+        console.log(`  ⚠  ${targetRoot}/${r.path} — left in place (${r.reason})`);
+      }
+    } catch (e) {
+      // Cleanup is best-effort: a reconciliation failure must never fail the install.
+      console.log(`  ⚠  ${targetRoot}/ — upgrade cleanup skipped (${e.message})`);
+    }
+
+    try {
+      if (reconcileSafe) {
+        writeManifest({ destRoot, currentPaths, packageName, packageVersion });
+      }
+    } catch (e) {
+      console.log(`  ⚠  ${targetRoot}/ — could not write install manifest (${e.message})`);
+    }
+
     totalCopied  += result.added.length + result.overwritten.length;
     totalSkipped += result.skipped.length;
   }
@@ -199,11 +387,26 @@ function main() {
     console.log(`  ⚠  Could not bootstrap .github/copilot-instructions.md — ${e.message}`);
   }
 
+  // Bootstrap .github/hooks/jenga.json unconditionally, same pattern as the
+  // copilot-instructions.md bootstrap immediately above (E16_S03_T04). Wires Copilot CLI's
+  // native sessionEnd/userPromptSubmitted hooks to this package's hooks/copilot_session_end.sh
+  // and hooks/prompt_router.sh, using absolute node_modules/@jenga-ai/agent paths (packageRoot
+  // !== consumerRoot here, so lib/generate-copilot-hooks.js bakes in the stable installed-package
+  // path rather than a runtime git-root lookup — see that file's own header comment for why).
+  // Entirely Jenga-owned output (unlike copilot-instructions.md), so this is a plain
+  // idempotent overwrite — no marker-merge needed.
+  try {
+    const result = generateCopilotHooks(consumerRoot, packageRoot);
+    console.log(`  ✓ .github/hooks/jenga.json bootstrapped (${result.path})`);
+  } catch (e) {
+    console.log(`  ⚠  Could not bootstrap .github/hooks/jenga.json — ${e.message}`);
+  }
+
   // Write .jenga-version to record the installed version at consumer root
   fs.writeFileSync(versionFile, packageVersion + '\n', 'utf8');
 
   console.log('\n──────────────────────────────────────────────────────');
-  console.log(`  Summary: ${totalCopied} file(s) copied, ${totalSkipped} skipped`);
+  console.log(`  Summary: ${totalCopied} file(s) copied, ${totalSkipped} skipped, ${totalDeleted} stale file(s) removed`);
   console.log(`  .jenga-version written: ${packageVersion}`);
   console.log('──────────────────────────────────────────────────────\n');
 }

package/scripts/verify-legacy-seed-reconcile.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+#
+# verify-legacy-seed-reconcile.sh — fixture rehearsal for E26_S08_T03
+#
+# Rehearses the legacy-path-seeding mechanism (lib/postinstall-manifest.js's
+# seedFromLegacyPaths/reconcileWithPriorPaths, wired into scripts/postinstall.js's
+# no-prior-manifest branch) against THROWAWAY fixture consumer projects, as required by
+# this task's `crucial_level: gated` note ("must be rehearsed against a throwaway
+# fixture consumer directory before being considered done, not just unit-reasoned
+# about"). Kept as a SEPARATE script from scripts/verify-postinstall-reconcile.sh
+# (E26_S08_T01's already-Passed rehearsal harness) so that harness is not touched by
+# this task.
+#
+# SAFETY: this script creates its own fixture root via `mktemp -d` and writes and
+# deletes ONLY inside it. It takes no path argument and will never operate on an
+# existing directory, so it cannot touch this repo or a real consumer project.
+# Set KEEP_FIXTURE=1 to leave the fixture on disk for inspection.
+#
+# Scenarios covered
+#   A. Pre-manifest orphan cleanup — THE fix this task delivers. A consumer already
+#      carrying an orphan predating any manifest (e.g. a retired j-<name> twin) gets it
+#      cleaned up on the VERY FIRST run of a fixed version (adopt-then-reconcile in one
+#      pass), while a consumer-authored sibling file in the same directory survives
+#      along with the directory itself.
+#   B. Genuine first-ever install (nothing on disk to intersect with) stays purely
+#      additive — no deletes, regardless of what the legacy path list contains.
+#   C. A legacy-listed path that is STILL currently shipped survives (it's part of this
+#      run's own copy set, so it is never "stale").
+#   D. A legacy-listed path that isn't actually present on disk is never seeded (no
+#      phantom delete attempt, no error).
+#   E. Boundary/type safety over SEEDED paths: a traversal entry and a symlink entry in
+#      the legacy list are refused exactly like a manifest-based candidate would be —
+#      seeding narrows which paths are eligible, it does not relax how a candidate is
+#      validated.
+#   F. Regression: a consumer with a VALID prior manifest reconciles exactly as T01
+#      already verifies — seeding must never fire once a real manifest exists.
+#
+# Usage:  bash scripts/verify-legacy-seed-reconcile.sh
+# Exit:   0 = all assertions passed, 1 = at least one failed.
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FIXTURE="$(mktemp -d "${TMPDIR:-/tmp}/jenga-legacy-seed-fixture.XXXXXX")"
+
+PASS=0
+FAIL=0
+
+# When RESULTS_FILE is set, every verdict is also appended in a machine-readable
+# `PASS<TAB><name>` / `FAIL<TAB><name>` form, so tests/postinstall-legacy-seed.bats can
+# assert on individual named checks instead of on one opaque exit status. Mirrors the
+# exact convention scripts/verify-postinstall-reconcile.sh already established.
+record() { if [ -n "${RESULTS_FILE:-}" ]; then printf '%s\t%s\n' "$1" "$2" >> "$RESULTS_FILE"; fi; }
+
+pass() { PASS=$((PASS + 1)); record PASS "$1"; printf '  \033[32mPASS\033[0m  %s\n' "$1"; }
+fail() { FAIL=$((FAIL + 1)); record FAIL "$1"; printf '  \033[31mFAIL\033[0m  %s\n' "$1"; }
+
+assert_file()      { if [ -f "$1" ]; then pass "$2"; else fail "$2 (missing: $1)"; fi; }
+assert_absent()    { if [ ! -e "$1" ]; then pass "$2"; else fail "$2 (still present: $1)"; fi; }
+assert_dir()       { if [ -d "$1" ]; then pass "$2"; else fail "$2 (missing dir: $1)"; fi; }
+assert_grep()      { if grep -q "$1" "$2" 2>/dev/null; then pass "$3"; else fail "$3"; fi; }
+assert_nogrep_re() { if grep -qE "$1" "$2" 2>/dev/null; then fail "$3"; else pass "$3"; fi; }
+
+cleanup() {
+  if [ "${KEEP_FIXTURE:-0}" = "1" ]; then
+    printf '\n  Fixture retained at: %s\n' "$FIXTURE"
+  else
+    rm -rf "$FIXTURE"
+  fi
+}
+trap cleanup EXIT
+
+# ── build a synthetic "current package" ──────────────────────────────────────
+# Real lib/ + scripts/ (the code under test), a small synthetic skills/+agents/ tree,
+# and a hand-authored lib/legacy-shipped-paths.json standing in for the real generated
+# artifact — this fixture's package version doesn't need to match any real published
+# version; only the LOGIC under test needs to be real.
+make_pkg() {
+  local dir="$1"
+  mkdir -p "$dir"
+  cp -R "$REPO_ROOT/lib"     "$dir/lib"
+  cp -R "$REPO_ROOT/scripts" "$dir/scripts"
+  cat > "$dir/package.json" <<'JSON'
+{ "name": "@jenga-ai/agent", "version": "3.0.0", "type": "module" }
+JSON
+  mkdir -p "$dir/skills/do" "$dir/agents"
+  printf '# do skill (still shipped)\n' > "$dir/skills/do/SKILL.md"
+  printf '# developer agent (still shipped)\n' > "$dir/agents/developer.md"
+}
+
+write_legacy_paths() {
+  local dir="$1"; shift
+  local paths_json
+  paths_json=$(printf '"%s",' "$@")
+  paths_json="[${paths_json%,}]"
+  cat > "$dir/lib/legacy-shipped-paths.json" <<JSON
+{
+  "generated_at": "2026-01-01T00:00:00.000Z",
+  "package": "@jenga-ai/agent",
+  "source": "test-fixture",
+  "paths": $paths_json
+}
+JSON
+}
+
+run_install() {
+  local pkg="$1" consumer="$2" log="$3"
+  ( cd "$pkg" && INIT_CWD="$consumer" node scripts/postinstall.js ) > "$log" 2>&1
+}
+
+echo
+echo "══ Jenga legacy-path seeding rehearsal (E26_S08_T03) ══"
+echo "  fixture: $FIXTURE"
+
+PKG="$FIXTURE/pkg"
+make_pkg "$PKG"
+write_legacy_paths "$PKG" \
+  "agents/developer.md" \
+  "skills/do/SKILL.md" \
+  "skills/j-legacy-twin/SKILL.md" \
+  "../OUTSIDE-THE-FIXTURE.txt" \
+  "skills/trap/LINK.md"
+
+# ═══ Scenario A — pre-manifest orphan cleanup (THE fix) ══════════════════════
+echo
+echo "── Scenario A: pre-manifest orphan cleaned on the very first run ──"
+
+CONSUMER_A="$FIXTURE/consumer-a"
+mkdir -p "$CONSUMER_A/.agents/skills/j-legacy-twin" "$CONSUMER_A/.claude/skills/j-legacy-twin"
+printf '# retired twin, predates any manifest\n' > "$CONSUMER_A/.agents/skills/j-legacy-twin/SKILL.md"
+printf 'my own notes\n'                          > "$CONSUMER_A/.agents/skills/j-legacy-twin/my-notes.md"
+printf '# retired twin, predates any manifest\n' > "$CONSUMER_A/.claude/skills/j-legacy-twin/SKILL.md"
+printf 'my own notes\n'                          > "$CONSUMER_A/.claude/skills/j-legacy-twin/my-notes.md"
+
+run_install "$PKG" "$CONSUMER_A" "$FIXTURE/a-install.log"
+
+assert_absent "$CONSUMER_A/.agents/skills/j-legacy-twin/SKILL.md" \
+  "pre-manifest orphan removed on first run (.agents)"
+assert_absent "$CONSUMER_A/.claude/skills/j-legacy-twin/SKILL.md" \
+  "pre-manifest orphan removed on first run (.claude)"
+assert_file "$CONSUMER_A/.agents/skills/j-legacy-twin/my-notes.md" \
+  "consumer-authored sibling survives (.agents)"
+assert_file "$CONSUMER_A/.claude/skills/j-legacy-twin/my-notes.md" \
+  "consumer-authored sibling survives (.claude)"
+assert_dir "$CONSUMER_A/.agents/skills/j-legacy-twin" \
+  "directory survives because it still holds a consumer file (.agents)"
+assert_grep "seeded from known-shipped legacy paths" "$FIXTURE/a-install.log" \
+  "install log attributes the cleanup to legacy-path seeding"
+assert_file "$CONSUMER_A/.agents/skills/do/SKILL.md" \
+  "currently-shipped skill untouched"
+assert_file "$CONSUMER_A/.agents/agents/developer.md" \
+  "currently-shipped agent file untouched"
+
+# Manifest written this run must describe reality: current package paths only, never
+# the just-deleted orphan and never the consumer's own file.
+python3 - "$CONSUMER_A/.agents/.jenga-postinstall-manifest.json" <<'PYEOF'
+import json, sys
+paths = json.load(open(sys.argv[1]))["paths"]
+assert "skills/j-legacy-twin/SKILL.md" not in paths, "deleted orphan must not be in the fresh manifest"
+assert "skills/j-legacy-twin/my-notes.md" not in paths, "consumer file must never be in the manifest"
+assert "skills/do/SKILL.md" in paths and "agents/developer.md" in paths, "current package paths must be present"
+PYEOF
+if [ $? -eq 0 ]; then pass "fresh manifest describes only what is actually on disk post-cleanup"; else fail "fresh manifest is inaccurate"; fi
+
+# ═══ Scenario B — genuine first-ever install stays additive-only ═════════════
+echo
+echo "── Scenario B: genuine first-ever install (nothing to intersect with) ──"
+
+CONSUMER_B="$FIXTURE/consumer-b"
+mkdir -p "$CONSUMER_B"
+run_install "$PKG" "$CONSUMER_B" "$FIXTURE/b-install.log"
+
+assert_nogrep_re "[1-9][0-9]* stale file" "$FIXTURE/b-install.log" \
+  "first-ever install deletes nothing despite a non-empty legacy path list"
+assert_grep "no previous install manifest" "$FIXTURE/b-install.log" \
+  "first-ever install reports plain additive-only, not a seeded outcome"
+assert_file "$CONSUMER_B/.agents/skills/do/SKILL.md" \
+  "first-ever install still copies current package files"
+
+# ═══ Scenario C — a legacy path still currently shipped is never touched ═════
+# (Implicitly exercised by Scenario A's "do"/"developer.md" already surviving, but
+# asserted here as its own named check for clarity.)
+assert_file "$CONSUMER_A/.claude/skills/do/SKILL.md" \
+  "a legacy-listed path that is STILL shipped survives untouched (not stale)"
+
+# ═══ Scenario D — a legacy path absent from disk is never phantom-seeded ═════
+# The legacy list includes "skills/j-legacy-twin/SKILL.md" for consumer-b too, but
+# consumer-b never had that file on disk at all. No error, no crash, nothing reported.
+assert_absent "$CONSUMER_B/.agents/skills/j-legacy-twin" \
+  "a legacy path never present on disk produces no phantom entries"
+
+# ═══ Scenario E — boundary/type safety over SEEDED paths ═════════════════════
+echo
+echo "── Scenario E: adversarial legacy-listed paths are refused, not exploited ──"
+
+CONSUMER_E="$FIXTURE/consumer-e"
+mkdir -p "$CONSUMER_E/.agents/skills/trap"
+printf 'precious\n' > "$FIXTURE/OUTSIDE-THE-FIXTURE.txt"
+ln -sf "$FIXTURE/OUTSIDE-THE-FIXTURE.txt" "$CONSUMER_E/.agents/skills/trap/LINK.md"
+
+run_install "$PKG" "$CONSUMER_E" "$FIXTURE/e-install.log"
+
+assert_file "$FIXTURE/OUTSIDE-THE-FIXTURE.txt" \
+  "traversal entry in the legacy list cannot delete outside the mirror root"
+if [ -L "$CONSUMER_E/.agents/skills/trap/LINK.md" ]; then
+  pass "symlink entry in the legacy list is refused, not followed or unlinked"
+else
+  fail "symlink entry in the legacy list was removed"
+fi
+
+# ═══ Scenario F — regression: a VALID prior manifest reconciles normally, unseeded ═══
+# Uses a genuine two-version upgrade (like T01's own harness) so a REAL manifest-backed
+# stale entry exists to clean up — proving the seeding branch never fires once a real
+# manifest is present, not merely that nothing happened to need it.
+echo
+echo "── Scenario F: a consumer with a real prior manifest reconciles normally, unseeded ──"
+
+PKG_F1="$FIXTURE/pkg-f1"
+make_pkg "$PKG_F1"
+mkdir -p "$PKG_F1/skills/renamed-old"
+printf '# renamed-old — removed in the next version\n' > "$PKG_F1/skills/renamed-old/SKILL.md"
+write_legacy_paths "$PKG_F1" "agents/developer.md" "skills/do/SKILL.md"
+
+PKG_F2="$FIXTURE/pkg-f2"
+make_pkg "$PKG_F2"
+python3 -c "
+import json
+p = '$PKG_F2/package.json'
+d = json.load(open(p)); d['version'] = '3.0.1'; json.dump(d, open(p, 'w'))
+"
+write_legacy_paths "$PKG_F2" "agents/developer.md" "skills/do/SKILL.md" "skills/renamed-old/SKILL.md"
+
+CONSUMER_F="$FIXTURE/consumer-f"
+mkdir -p "$CONSUMER_F"
+run_install "$PKG_F1" "$CONSUMER_F" "$FIXTURE/f-install-1.log"
+assert_grep "no previous install manifest" "$FIXTURE/f-install-1.log" \
+  "first run for consumer-f is a normal, unseeded additive install"
+assert_file "$CONSUMER_F/.agents/skills/renamed-old/SKILL.md" \
+  "v1 skill mirrored before the upgrade that removes it"
+
+run_install "$PKG_F2" "$CONSUMER_F" "$FIXTURE/f-install-2.log"
+assert_absent "$CONSUMER_F/.agents/skills/renamed-old/SKILL.md" \
+  "genuinely stale entry cleaned up via the REAL manifest-backed path"
+assert_grep "stale file(s) removed" "$FIXTURE/f-install-2.log" \
+  "the real manifest-backed delete pass ran and reported a removal"
+assert_nogrep_re "seeded from known-shipped legacy paths" "$FIXTURE/f-install-2.log" \
+  "seeding branch never fires when a real prior manifest is present"
+
+echo
+echo "──────────────────────────────────────────────────────"
+printf '  %d passed, %d failed\n' "$PASS" "$FAIL"
+echo "──────────────────────────────────────────────────────"
+
+[ "$FAIL" -eq 0 ]