devflow-kit 2.4.0 → 3.0.0

package/dist/targets/claude-code/installer.js

@@ -1,10 +1,13 @@
 import { promises as fs } from 'fs';
 import { existsSync } from 'fs';
 import * as path from 'path';
-import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
-import { skillsDir, agentsDir, rulesDir, commandsDir, scriptsDir } from '../../core/assets.js';
-import { getPackageRoot } from '../../core/paths.js';
+import { SKILL_NAMESPACE, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS, resolveSkillInstallPlan } from '../../core/plugins.js';
+import { skillsDir, agentSourceDirs, rulesDir, commandsDir, scriptsDir, compiledSkillRefsDir } from '../../core/assets.js';
+import { getPackageRoot, isContainedIn } from '../../core/paths.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
+import { generatedReferenceManifest, installedReferenceManifest, PR_HOST_DESTINATION_ROOT, SKILL_REFS_SKILL_NAME, TRACKER_DESTINATION_ROOT } from '../../core/mds-variants.js';
+import { sweepOrphanedReferences, MAX_REFERENCE_SWEEP_DEPTH } from '../../core/reference-sweep.js';
+import { TRACKER_AGENT_NAME } from './tracker-install.js';
 // ---------------------------------------------------------------------------
 // Shadow validation helpers (exported — reused by Step 4 list commands)
 // ---------------------------------------------------------------------------
@@ -157,14 +160,42 @@ export async function copyDirectory(src, dest) {
     }
 }
 /**
- * Recursively chmod all files in a directory tree.
+ * Recursively chmod all files in a directory tree, bounded by the shared descent bound.
+ *
+ * `_depth` counts the walked root as 0 and a breach is `_depth > MAX_REFERENCE_SWEEP_DEPTH`
+ * — the same comparison every other walk over this same tree already makes
+ * (`sweepOrphanedReferences`, the build's `pruneOrphans`, the harness's `walkFiles`). The
+ * constant is imported, never re-spelled: one tree, one bound — two walkers each
+ * carrying their own literal is how a pair of them comes to disagree.
+ *
+ * The bound is CONSISTENCY, not an exploit closure. `Dirent.isDirectory()` is lstat-based,
+ * so a symlink-to-directory is a leaf to this walk and a symlink loop — the hazard the
+ * shared constant's own rationale cites — cannot be entered here in the first place. What
+ * the bound buys is that the one walk over `references/` holding no explicit upper bound
+ * stops holding the opposite position on a hazard its siblings document, in a codebase
+ * whose standing rule is that every loop has one.
+ *
+ * A breach THROWS rather than returning quietly. A walk that stopped early would leave an
+ * unnamed part of the tree on its source modes while the caller believed the whole tree
+ * was normalised — the same "converged over ground it never covered" claim the sweep's
+ * `failed` channel exists to prevent. The reference overlay — the walk this bound is for,
+ * and the only one that crosses a tree the installer does not own — turns the throw into a
+ * `warn(...)` line carrying the directory and the bound, through the channel it already
+ * has for mode normalisation (see {@link overlayGeneratedReferences}). The other caller,
+ * {@link composeScripts}, swallows it with the rest of its copy-and-chmod step; that tree
+ * is three levels of shipped assets, so a breach there means the package itself grew a
+ * shape no walk in this repo expects, and neither call site aborts an install over it.
  */
-export async function chmodRecursive(dir, mode) {
+export async function chmodRecursive(dir, mode, _depth = 0) {
+    if (_depth > MAX_REFERENCE_SWEEP_DEPTH) {
+        throw new Error(`chmodRecursive: descent into ${dir} exceeds the bound of ` +
+            `${MAX_REFERENCE_SWEEP_DEPTH} levels — that subtree keeps the modes it arrived with.`);
+    }
     const entries = await fs.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            await chmodRecursive(fullPath, mode);
+            await chmodRecursive(fullPath, mode, _depth + 1);
         }
         else if (entry.isFile()) {
             await fs.chmod(fullPath, mode);
@@ -172,6 +203,967 @@ export async function chmodRecursive(dir, mode) {
     }
 }
 // ---------------------------------------------------------------------------
+// Generated skill-reference overlay
+// ---------------------------------------------------------------------------
+/**
+ * Every sub-path under the references root the prune converges to the manifest.
+ *
+ * D-CONVERGED-SUBTREES: a directory converges exactly when EVERY file in it is
+ * generated — that is the whole rule, and these two directories are the whole set that
+ * satisfies it today.
+ *
+ * `tracker/` ({@link TRACKER_DESTINATION_ROOT}) holds the per-provider mechanics and `pr/`
+ * ({@link PR_HOST_DESTINATION_ROOT}) the PR/review host bodies; the build emits both
+ * wholesale, so anything inside them the manifest does not name is by construction a
+ * leftover — a retired op, a provider the registry dropped, a shadow-supplied file, a
+ * staging tree a crashed run stranded — and removing it is the only way the installed
+ * tree can equal the manifest. Every install carries both whole
+ * (D-INSTALL-ALL-PROVIDERS), so what the prune converges is each directory's CONTENTS. Both entries are the
+ * registry's own constants, so a renamed destination root moves the build and the prune
+ * together.
+ *
+ * The references ROOT is the exemption, and the reason is the inverse of the rule: it
+ * holds hand-authored documents (`github-api.md`, `violations.md`, …) beside the flat
+ * generated ones with no manifest of which names are hand-authored, so a prune there
+ * cannot tell a retired generated document from a reference the skill has always shipped
+ * (D-OVERLAY-FLAT-UNIT). The root is overlaid and never pruned; the full-install
+ * pre-clean is what reaches a stale file there ({@link overlayOwnedSkillPaths}).
+ *
+ * An explicit list rather than "every top-level directory the manifest names", which
+ * would be self-maintaining and is still the wrong rule: a subtree the manifest stops
+ * naming ENTIRELY would drop out of a derived set and keep its whole installed tree,
+ * which is the retirement case this prune exists for. Listed here, the same subtree
+ * converges to empty. The list is also the one thing that lets the pre-clean keep a
+ * nested directory whole ({@link overlayOwnedSkillPaths}), so a directory missing from
+ * it fails safe — kept file by file, like the root — rather than keeping its stale files
+ * forever (avoids PF-074). The cost is one entry per new wholly-generated directory, and
+ * that entry is the whole edit: everything downstream reads the list (avoids PF-015).
+ */
+const CONVERGED_SUBTREES = [TRACKER_DESTINATION_ROOT, PR_HOST_DESTINATION_ROOT];
+/** Is this top-level directory under the references root one the prune converges? */
+function isConvergedSubtree(top) {
+    return CONVERGED_SUBTREES.includes(top);
+}
+/**
+ * One spelling of a unit's name, for every message about it.
+ *
+ * Pure function — the installer owns the unit types, so it owns how they are named,
+ * rather than leaving each render site to invent its own wording (avoids PF-013).
+ */
+export function overlayUnitLabel(unit) {
+    switch (unit.kind) {
+        case 'provider':
+            return `provider directory "${unit.subdir}"`;
+        case 'pr-host':
+            return `the PR-host mechanics in "${unit.dir}"`;
+        case 'cross-cutting':
+            return unit.dir === ''
+                ? 'the cross-cutting document set'
+                : `the cross-cutting document set in "${unit.dir}"`;
+        default: {
+            const _exhaustive = unit;
+            return _exhaustive;
+        }
+    }
+}
+/** The identity half of a unit, as the failure report carries it. */
+function unitRef(unit) {
+    return unit.kind === 'provider'
+        ? { kind: unit.kind, subdir: unit.subdir }
+        : { kind: unit.kind, dir: unit.dir };
+}
+/** POSIX sub-path a unit's files land in under a root — `''` for the references root. */
+function unitSubdir(unit) {
+    return unit.kind === 'provider' ? unit.subdir : unit.dir;
+}
+/**
+ * Is this directory part a PROVIDER directory — a provider's mechanics, swapped whole?
+ *
+ * `D-OVERLAY-PROVIDER-SHAPE`. Exactly `tracker/{provider}`: the only directory the
+ * reference-module registry emits INSIDE `tracker/`, and so the only one there whose
+ * whole directory may be renamed into place. (`pr/` is the registry's other emitted
+ * directory, and is classified by name in {@link planOverlayUnits}.)
+ *
+ * The distinction is load-bearing rather than cosmetic, and it is what the previous
+ * "any non-empty directory part is a provider" rule got wrong the first time the
+ * manifest carried a file directly under `tracker/`. That entry bucketed to the
+ * directory part `tracker`, which was then treated as a provider directory — so the
+ * unit's atomic swap was a rename of `tracker/` ITSELF, over a directory whose other
+ * entries are every provider's mechanics. Its staging sibling (`tracker.{token}.tmp`)
+ * also sat OUTSIDE the subtree the prune converges, which is what
+ * {@link stagingDirFor}'s second property exists to guarantee.
+ */
+function isProviderSubdir(subdir) {
+    const segments = subdir.split('/');
+    return segments.length === 2 && segments[0] === TRACKER_DESTINATION_ROOT && segments[1] !== '';
+}
+/**
+ * Group a manifest into overlay units by the directory each entry lands in.
+ *
+ * Deterministic order — sorted by directory part — so a failure report and a loud throw
+ * are reproducible run to run.
+ *
+ * Three kinds, decided by the directory part: a `tracker/{provider}` directory
+ * ({@link isProviderSubdir}) is a provider unit and `pr/` ({@link PR_HOST_DESTINATION_ROOT})
+ * is the PR-host unit — each a directory holding only its own unit's documents, swapped
+ * whole. Every other directory holds a FLAT SET — documents that land beside entries this
+ * overlay must never replace or delete, promoted one rename at a time. The references
+ * root is one such directory (beside the hand-authored references) and `tracker/` is
+ * another (beside the provider directories); both take the flat arm, which is why that
+ * arm carries the directory it lands in rather than assuming the root.
+ *
+ * Exported for the one property no arm reading the INSTALLED tree can discriminate:
+ * which KIND a directory becomes. The directory parts sort `'' < pr < tracker <
+ * tracker/{provider}`, so a `tracker/` entry mis-bucketed as a provider renames the
+ * whole subtree into place BEFORE the provider units promote back into it, and the
+ * installed tree ends up complete under either rule. The classification itself is the
+ * observation that separates them (avoids PF-018).
+ */
+export function planOverlayUnits(manifest) {
+    const bySubdir = new Map();
+    for (const relPath of manifest) {
+        const segments = relPath.split('/');
+        const subdir = segments.slice(0, -1).join('/');
+        const bucket = bySubdir.get(subdir);
+        if (bucket === undefined)
+            bySubdir.set(subdir, [relPath]);
+        else
+            bucket.push(relPath);
+    }
+    return [...bySubdir.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([subdir, files]) => {
+        if (isProviderSubdir(subdir))
+            return { kind: 'provider', subdir, files };
+        if (subdir === PR_HOST_DESTINATION_ROOT)
+            return { kind: 'pr-host', dir: subdir, files };
+        return { kind: 'cross-cutting', dir: subdir, files };
+    });
+}
+/** Resolve a POSIX manifest sub-path against a root, spelled for this filesystem. */
+function underRoot(root, posixSubPath) {
+    return posixSubPath === '' ? root : path.join(root, ...posixSubPath.split('/'));
+}
+/**
+ * Process-unique token every staging directory this run creates carries.
+ *
+ * `scripts/build-mds.ts` scopes its own staging path to the writing process for the same
+ * reason and in the same idiom (`tempPathFor`: `${dest}.${process.pid}.tmp`). A FIXED
+ * staging name was the one thing standing between two concurrent `devflow init` runs and a
+ * PARTIAL unit promoted into an installed skill: the first thing
+ * {@link buildUnitStagingTree} does to its staging path is
+ * `fs.rm(stagingDir, { recursive: true, force: true })`, so under one shared name each run
+ * deletes the other's half-built tree, and whichever reaches promotion second renames
+ * whatever happened to survive into place — defeating the per-unit atomic swap outright.
+ *
+ * The pid is what makes two live runs disjoint. The timestamp is what makes a REUSED pid
+ * disjoint from the run that crashed before it, so a tree stranded by that earlier run is
+ * never mistaken for this one's own and adopted mid-build.
+ *
+ * Fixed for the life of the process so {@link stagingDirFor} stays a pure function of the
+ * unit it is asked about: one path per unit, computed once and threaded from the build to
+ * whichever promotion half consumes it.
+ */
+const STAGING_TOKEN = `${process.pid}-${Date.now().toString(36)}`;
+/**
+ * Staging directory for a unit — process-unique, under the subtree the prune converges.
+ *
+ * Both properties are about a run that is not this one:
+ *
+ * 1. The basename carries {@link STAGING_TOKEN}, so a concurrent run's staging tree is
+ *    never the tree this one pre-cleans, builds into, or promotes.
+ * 2. Both names resolve under `tracker/`, one of the {@link CONVERGED_SUBTREES}, so a
+ *    staging tree stranded by a crash
+ *    between `mkdir` and promotion is removed by the next run's prune. It HAS to be the
+ *    prune that removes it, because (1) means no later run's pre-clean will ever look at
+ *    that name again. A staging directory at the references root instead (say
+ *    `references/.cross-cutting.tmp`) would sit outside that subtree and outside every
+ *    other convergence this module performs, so a stranded partial copy of the
+ *    cross-cutting documents would sit inside the installed skill indefinitely — and be
+ *    mode-normalised by {@link chmodRecursive} on every later install, that being the one
+ *    part of the overlay which does reach the whole references root.
+ *
+ * The provider arm inherits the property from its unit: the path is the unit's own
+ * installed location plus a suffix, so it is converged exactly when the unit is, and every
+ * provider subdir the reference-module registry declares is `tracker/{provider}`. Every
+ * other arm is placed under the converged subtree explicitly ({@link sidecarBaseFor}): a
+ * flat set has no installed location to hang a suffix on — its documents ARE the
+ * directory — and `pr/`'s own sibling (`pr.{token}.tmp`) would sit at the references
+ * root, outside every convergence. The name carries the kind and the directory slug, so
+ * no two units share one staging path. The cost is that a manifest carrying no provider
+ * would create an empty `tracker/` on its way through; the registry never produces one,
+ * and an empty directory is not a partial install.
+ *
+ * No staging name can collide with a manifest entry, and the prune reaches them all for
+ * the same reason it reaches the `.old` backups: it converges the `tracker/` subtree
+ * against the manifest BY PATH, so anything under it the manifest does not name is
+ * removed and no staging name has to be recognised as one. Not by spelling — a provider
+ * arm's basename is `{provider}.{token}.tmp`, which is not dot-prefixed, so a rule keyed
+ * on the name would reach the other arms only.
+ */
+function stagingDirFor(referencesTarget, unit) {
+    return `${sidecarBaseFor(referencesTarget, unit)}.${STAGING_TOKEN}.tmp`;
+}
+/**
+ * Backup a directory unit is displaced to while its replacement is renamed into place.
+ *
+ * Beside the staging tree, and under `tracker/` for the same reason (property 2 of
+ * {@link stagingDirFor}): a backup a crash strands is removed by a later run's prune.
+ */
+function backupDirFor(referencesTarget, unit) {
+    return `${sidecarBaseFor(referencesTarget, unit)}.old`;
+}
+/**
+ * The path a unit's staging tree and backup are named from, before their suffixes.
+ *
+ * A provider's own installed location, which already lies under `tracker/`. Every other
+ * unit gets a dot-prefixed name directly under `tracker/`, keyed on kind AND directory:
+ * with two flat sets (the references root, and the tool-call contract in `tracker/`) a
+ * name keyed on the kind alone would give both units the SAME staging path, each deleting
+ * the other's half-built tree — the collision STAGING_TOKEN prevents between runs,
+ * reproduced within one.
+ */
+function sidecarBaseFor(referencesTarget, unit) {
+    if (unit.kind === 'provider')
+        return underRoot(referencesTarget, unit.subdir);
+    const slug = unit.dir === '' ? 'root' : unit.dir.split('/').join('-');
+    return path.join(referencesTarget, TRACKER_DESTINATION_ROOT, `.${unit.kind}.${slug}`);
+}
+/**
+ * Why a converged subtree's root must not be used — or `null` when it may.
+ *
+ * D-CONVERGED-ROOT-REAL: every write and every removal the overlay makes under a
+ * converged subtree goes through that subtree's ROOT — staging trees are built under
+ * `tracker/`, `pr/` is renamed into place, and each prune starts with a `readdir` of its
+ * root. The per-entry symlink guards (the prune's lstat-based `isDirectory()`, the
+ * build's symlink skip) protect everything BELOW a root and nothing AT it: `readdir` and
+ * `mkdir` follow a link at the root itself. So a root planted as a symlink would send the
+ * installer's writes and deletions into whatever it points at.
+ *
+ * Absent is fine — the overlay creates what it converges. Anything else that is not a
+ * real directory, including a root that cannot be lstat'd, is refused (fail closed), and
+ * the refusal is reported by the caller rather than repaired: the installer does not
+ * delete a link it did not create.
+ */
+async function convergedRootFault(referencesTarget, subtree) {
+    const root = underRoot(referencesTarget, subtree);
+    let stat;
+    try {
+        stat = await fs.lstat(root);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        return `references/${subtree} could not be inspected (${String(err)}) — ` +
+            `nothing is staged, promoted or pruned through it.`;
+    }
+    if (stat.isDirectory())
+        return null;
+    const what = stat.isSymbolicLink() ? 'a symbolic link' : 'not a directory';
+    return `references/${subtree} is ${what} — nothing is staged, promoted or pruned ` +
+        `through it. Replace it with a real directory and re-run.`;
+}
+/**
+ * The {@link CONVERGED_SUBTREES} a unit's build or promotion writes under.
+ *
+ * Read off the paths the unit actually uses — where its documents land, where it stages,
+ * and where a directory unit's backup goes — rather than restated per kind, so a unit
+ * that moves its staging moves this answer with it.
+ */
+function subtreesTouchedBy(referencesTarget, unit) {
+    const paths = [underRoot(referencesTarget, unitSubdir(unit)), stagingDirFor(referencesTarget, unit)];
+    if (unit.kind !== 'cross-cutting')
+        paths.push(backupDirFor(referencesTarget, unit));
+    const tops = new Set(paths.map(p => path.relative(referencesTarget, p).split(path.sep)[0]));
+    return CONVERGED_SUBTREES.filter(subtree => tops.has(subtree));
+}
+/**
+ * Build one unit's complete replacement tree under a `.tmp` sibling.
+ *
+ * Returns the staging directory on success, or the rendered cause when the unit must be
+ * abandoned. Throws — and only throws — when a manifest entry is ABSENT from the
+ * generated tree: that is a build artifact that was never produced, not an I/O
+ * degradation, and shipping an installer that silently omits the mechanics the agent is
+ * told to load would move the failure to every user's first spawn.
+ *
+ * Applies PF-011 (build under a `.tmp` sibling, pre-cleaning an orphan from a prior
+ * crashed run). Applies PF-009 for everything else: a copy that fails aborts this unit
+ * and no other.
+ */
+async function buildUnitStagingTree(unit, sourceRoot, referencesTarget, warn) {
+    const stagingDir = stagingDirFor(referencesTarget, unit);
+    const subdir = unitSubdir(unit);
+    const sourceDir = underRoot(sourceRoot, subdir);
+    const wanted = new Map(unit.files.map(relPath => [relPath.split('/').slice(-1)[0], relPath]));
+    const landed = new Set();
+    const discard = async () => {
+        await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+    };
+    try {
+        await fs.rm(stagingDir, { recursive: true, force: true });
+        await fs.mkdir(stagingDir, { recursive: true });
+    }
+    catch (err) {
+        return { ok: false, error: String(err) };
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    }
+    catch (err) {
+        await discard();
+        return { ok: false, error: String(err) };
+    }
+    for (const entry of entries) {
+        const relPath = subdir === '' ? entry.name : `${subdir}/${entry.name}`;
+        // Symlinks are skipped, never followed. copyDirectory follows them and preserves
+        // source modes, which is why the overlay does its own copying: a link planted in the
+        // generated tree would otherwise pull arbitrary bytes into an installed skill.
+        if (entry.isSymbolicLink()) {
+            warn(`reference overlay: skipping symlink entry "${relPath}" — symlinks are never followed`);
+            continue;
+        }
+        // A nested directory is another unit's business, and a source file the manifest does
+        // not name is not installed at all: the overlay converges to the manifest, it does
+        // not merge whatever happens to be lying in the generated tree.
+        if (!entry.isFile())
+            continue;
+        if (!wanted.has(entry.name))
+            continue;
+        try {
+            await fs.copyFile(path.join(sourceDir, entry.name), path.join(stagingDir, entry.name));
+            landed.add(entry.name);
+        }
+        catch (err) {
+            await discard();
+            return { ok: false, error: String(err) };
+        }
+    }
+    for (const [basename, relPath] of wanted) {
+        if (landed.has(basename))
+            continue;
+        await discard();
+        throw new Error(`Generated skill reference not found for declared reference "${relPath}": ` +
+            `${underRoot(sourceRoot, relPath)}. ` +
+            `Run \`npm run build:mds\` to regenerate dist/skills/git/references/ before install.`);
+    }
+    return { ok: true, stagingDir };
+}
+/**
+ * Is this unit's freshly built staging tree already what is installed?
+ *
+ * Asked once per unit, between the build and the promotion, so a unit that would be
+ * promoted onto an identical copy of itself is skipped and reported as unchanged
+ * instead. Without it every run writes every unit, `overlaidRefs` is never empty, and
+ * every render site downstream — `devflow tracker --set`'s `(unchanged)` line, init's
+ * `Tracker assets: +N` summary — can only ever report movement (AC-23).
+ *
+ * Comparison is against what the PROMOTION would do, not merely against the bytes the
+ * manifest names, and the two differ by unit kind:
+ *
+ *   - a DIRECTORY unit (a provider, or `pr/`) is swapped whole
+ *     ({@link promoteDirectoryUnit}), so an installed entry the manifest no longer names
+ *     is something this run would REMOVE. Comparing only the manifest's own files would
+ *     call such a unit unchanged and leave the stray installed — converge-not-merge
+ *     silently downgraded to a merge.
+ *   - a CROSS-CUTTING unit is promoted one document at a time into a directory holding
+ *     entries the overlay must never replace or delete (D-OVERLAY-FLAT-UNIT), so its
+ *     files are exactly the comparison and the neighbours are none of its business.
+ *
+ * What it deliberately does NOT compare is file MODE. D-OVERLAY-MODE-SCOPE normalises the
+ * whole references directory on every run regardless of which units promoted, so a unit
+ * skipped here still has its modes converged — a skipped promotion can hide byte drift
+ * from nothing, and mode drift from nothing either.
+ *
+ * Any error — an absent installed copy, an unreadable one, a directory that is not there
+ * — answers "no". The fallback is always the promotion that was going to happen anyway,
+ * so a failure to compare can only cost a write, never correctness.
+ */
+async function stagedUnitIsAlreadyInstalled(unit, referencesTarget, stagingDir) {
+    const basenameOf = (relPath) => relPath.split('/').slice(-1)[0];
+    if (unit.kind !== 'cross-cutting') {
+        const owned = new Set(unit.files.map(basenameOf));
+        let installed;
+        try {
+            installed = await fs.readdir(underRoot(referencesTarget, unitSubdir(unit)));
+        }
+        catch {
+            return false;
+        }
+        if (installed.length !== owned.size)
+            return false;
+        if (installed.some(name => !owned.has(name)))
+            return false;
+    }
+    for (const relPath of unit.files) {
+        try {
+            const staged = await fs.readFile(path.join(stagingDir, basenameOf(relPath)));
+            const live = await fs.readFile(underRoot(referencesTarget, relPath));
+            if (!staged.equals(live))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Put a displaced unit back, and say whether it actually went back.
+ *
+ * A swallowed rename error would make a failed recovery indistinguishable from a
+ * successful one: the install would report the previously installed files as unchanged
+ * over a directory that no longer exists, and the prune would then delete the
+ * backup holding the only copy. What this returns is what the failure state is built
+ * from.
+ */
+async function restoreDisplacedUnit(backup, target) {
+    try {
+        await fs.rename(backup, target);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: String(err) };
+    }
+}
+/**
+ * Promote the flat cross-cutting set — one `rename` per document.
+ *
+ * There is no directory to swap. These documents land in `references/{unit.dir}` — the
+ * references root itself when `dir` is empty — beside hand-authored files the overlay must
+ * never replace or delete, so the unit is promoted one `rename` per document and a
+ * mid-flight failure leaves it part new and part old
+ * (D-OVERLAY-FLAT-UNIT, recorded on {@link OverlayUnit}). That is a weaker guarantee than
+ * {@link promoteDirectoryUnit}'s whole-directory swap, which is why the recorded state
+ * names which documents carry this run's bytes rather than claiming the set is untouched.
+ *
+ * Throws on the first failing rename; the caller reports the state recorded by then.
+ */
+async function promoteCrossCuttingUnit(unit, referencesTarget, stagingDir, record) {
+    const destDir = underRoot(referencesTarget, unit.dir);
+    // The directory this set lands in, created rather than assumed — {@link promoteDirectoryUnit}
+    // does the same for its target's parent. The two flat directories the registry emits today
+    // exist by the time promotion runs for reasons that have nothing to do with the unit landing
+    // in them: the references root is created by {@link overlayGeneratedReferences}, and
+    // `tracker/` as a side effect of this arm's own staging path. A flat set landing anywhere
+    // else takes ENOENT on its first rename — a unit reported as failed for where it was asked
+    // to land rather than for anything wrong with the documents it carries.
+    await fs.mkdir(destDir, { recursive: true });
+    for (const [index, relPath] of unit.files.entries()) {
+        const basename = relPath.split('/').slice(-1)[0];
+        await fs.rename(path.join(stagingDir, basename), path.join(destDir, basename));
+        // Past the first rename the set is mixed, and there is no directory to swap back
+        // (D-OVERLAY-FLAT-UNIT). The documents renamed so far carry this run's bytes; the
+        // rest still carry the previous install's. Recorded after each rename so a failure
+        // on the next one names both halves instead of claiming the set is untouched.
+        record({
+            kind: 'partially-refreshed',
+            refreshed: unit.files.slice(0, index + 1),
+            stale: unit.files.slice(index + 1),
+        });
+    }
+    await fs.rm(stagingDir, { recursive: true, force: true });
+}
+/**
+ * Promote a directory unit (a provider, or `pr/`) — swapped whole, or not at all.
+ *
+ * Displace the installed unit to its `.old` backup ({@link backupDirFor}), rename the
+ * staging tree into its place, then drop the backup — so the installed directory is
+ * either entirely the previous install or entirely the new one (DR-05, risk P2-g), and a
+ * rename that fails half-way restores the previous one rather than leaving it empty.
+ *
+ * Throws once the state it left has been recorded; the caller reports it.
+ */
+async function promoteDirectoryUnit(unit, referencesTarget, stagingDir, record) {
+    const target = underRoot(referencesTarget, unitSubdir(unit));
+    const backup = backupDirFor(referencesTarget, unit);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.mkdir(path.dirname(backup), { recursive: true });
+    // Move the installed unit ASIDE, never delete it, before the staging tree takes
+    // its place. `rm(target)` then `rename(staging, target)` destroys the only copy
+    // first: a rename that then fails leaves the unit with NO mechanics at all,
+    // while the report — and the summary line init.ts renders from it — still claims
+    // the previously installed files were left unchanged. The backup is what makes
+    // that claim true, so a failed promotion is recoverable rather than a silent
+    // deletion (avoids PF-009: a reported failure must describe the state it left).
+    //
+    // The `.old` backup is pre-cleaned like the `.tmp` tree. A crash that strands
+    // either is converged away by a later run's tracker-subtree prune (both names end
+    // in neither `/` nor `.md`, so no manifest entry can collide with them) — but the
+    // backup this run is still relying on is exempt from this run's prune, which is
+    // what `restore-failed` carries the recovery path for.
+    await fs.rm(backup, { recursive: true, force: true });
+    let displaced = false;
+    try {
+        await fs.rename(target, backup);
+        displaced = true;
+    }
+    catch (err) {
+        // Nothing installed yet — a first install has no unit to displace, so a failure
+        // from here on leaves the unit ABSENT rather than stale.
+        if (err.code !== 'ENOENT')
+            throw err;
+        record({ kind: 'not-installed', absent: unit.files });
+    }
+    try {
+        await fs.rename(stagingDir, target);
+    }
+    catch (err) {
+        if (displaced) {
+            const restored = await restoreDisplacedUnit(backup, target);
+            if (!restored.ok) {
+                record({ kind: 'restore-failed', recoveryPath: backup, restoreError: restored.error });
+            }
+        }
+        throw err;
+    }
+    await fs.rm(backup, { recursive: true, force: true }).catch(() => undefined);
+}
+/**
+ * Promote a fully built staging tree into place, dispatched on what kind of unit it is.
+ *
+ * The unit kinds are promoted by two different strategies with two different guarantees,
+ * and each half states its own: {@link promoteDirectoryUnit} swaps a directory whole,
+ * {@link promoteCrossCuttingUnit} renames the flat set document by document.
+ *
+ * What they share is the failure shape. A failure reports the state it left rather than a
+ * state a failure is assumed to imply: `state` is advanced as the running half passes each
+ * point of no return, so the catch describes the filesystem as it now is. That is the whole
+ * difference between a report a user can act on and one that names a recovery copy the same
+ * run went on to delete. Discarding the staging tree is shared for the same reason — an
+ * abandoned unit leaves no `.tmp` residue, whichever half abandoned it.
+ *
+ * Exported for the sake of ONE property that cannot be driven through
+ * {@link overlayGeneratedReferences}: a promotion that fails AFTER the installed unit has
+ * been displaced. The overlay builds and promotes in the same breath, so there is no seam
+ * at which a real filesystem failure can be injected between the two — and the behaviour
+ * that failure selects (previous unit restored, not deleted) is exactly the one worth
+ * pinning.
+ */
+export async function promoteUnitStagingTree(unit, referencesTarget, stagingDir) {
+    let state = { kind: 'installed-unchanged' };
+    const record = next => { state = next; };
+    try {
+        switch (unit.kind) {
+            case 'cross-cutting':
+                await promoteCrossCuttingUnit(unit, referencesTarget, stagingDir, record);
+                break;
+            case 'provider':
+            case 'pr-host':
+                await promoteDirectoryUnit(unit, referencesTarget, stagingDir, record);
+                break;
+            default: {
+                const _exhaustive = unit;
+                void _exhaustive;
+                throw new Error('Unknown overlay unit kind');
+            }
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+        return { ok: false, error: String(err), state };
+    }
+}
+/**
+ * Which "nothing was modified" sentence is true for a unit whose build failed.
+ *
+ * A build failure touches nothing under the references root, so the unit is left in
+ * whatever state it was already in — and those are two different states with two
+ * different consequences. Falling back on a working previous install is a deferred
+ * refresh; having no copy at all ships an agent whose mechanics pointers resolve to
+ * nothing, which is the worse outcome and the one a shared sentence would describe
+ * most quietly.
+ *
+ * One `access` per file, on the failure path only; the loop is bounded by the unit's
+ * own manifest slice.
+ */
+async function classifyUntouchedUnit(unit, referencesTarget) {
+    const absent = [];
+    for (const relPath of unit.files) {
+        try {
+            await fs.access(underRoot(referencesTarget, relPath));
+        }
+        catch {
+            absent.push(relPath);
+        }
+    }
+    return absent.length === unit.files.length
+        ? { kind: 'not-installed', absent }
+        : { kind: 'installed-unchanged' };
+}
+/**
+ * Refuse the whole overlay when the generated tree was never produced.
+ *
+ * The per-entry throw in {@link buildUnitStagingTree} cannot reach this case. It is
+ * raised after a successful `readdir` of a unit's source directory, so when the ROOT is
+ * absent — `npm run build:cli` alone, or a build interrupted before it emitted anything —
+ * no unit ever gets that far: each one degrades to a reported failure and the install
+ * returns success carrying an agent whose mechanics pointers resolve to nothing. That is
+ * the outcome the per-entry throw exists to prevent, arriving by the one route it does
+ * not cover — and the same root cause the agent resolver in `installViaFileCopy` already
+ * throws for, so the two build artifacts are guarded at the same strength.
+ *
+ * Deliberately ONE `stat` before the unit loop rather than a check inside it (PF-009):
+ * the fan-out has no per-item failure isolation, so a per-unit refusal would let one
+ * unbuilt provider abort every other unit's install. A unit directory that is absent
+ * under a root that exists stays a per-unit report, exactly as today.
+ *
+ * Only ENOENT refuses. A root that cannot be stat'd for any other reason (EACCES on a
+ * parent, a filesystem in a bad way) is an I/O degradation, not a missing build
+ * artifact, and belongs to the per-unit reporting path like every other one.
+ */
+async function requireGeneratedTree(sourceRoot, manifest) {
+    try {
+        await fs.stat(sourceRoot);
+        return;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            return;
+    }
+    throw new Error(`Generated skill references not found: ${sourceRoot}. ` +
+        `The whole generated tree is absent, so none of the ${manifest.length} references the ` +
+        `devflow:git agent is instructed to load would be installed. ` +
+        `Run \`npm run build:mds\` to regenerate dist/skills/git/references/ before install ` +
+        `(\`npm run build:cli\` alone does not produce it).`);
+}
+/**
+ * Converge ONE subtree to the manifest — unless that would delete a recovery copy this
+ * same run just created.
+ *
+ * A promotion whose restore failed leaves the unit's ONLY surviving copy in its `.old`
+ * sibling, which sits inside the subtree this prune converges and which the manifest
+ * (rightly) does not name. Pruning it destroys the backup in the same run that reported
+ * it as the way back, so the path the warning names is gone before the user reads it.
+ *
+ * Of the three ways to stop that, this is the one that leaves the SUCCESSFUL path
+ * byte-identical — the same call, the same arguments, the same position in the run.
+ * Moving the prune ahead of the unit loop would also spare the backup, but it converges
+ * a tree the loop has not rebuilt yet: it reports removals the promotion would have made
+ * anyway, and it mutates the install before the one throw path that aborts it. Excluding
+ * `.old`/`.tmp` names from the walk would mean a new exclusion option on
+ * sweepOrphanedReferences, i.e. changing the shape of a module this concern does not own.
+ *
+ * The skip is scoped to the subtree the recovery copy is IN, which is what makes it a
+ * skip rather than a blanket refusal: a backup stranded under `tracker/` says nothing
+ * about whether `pr/` can be converged, and a run that stopped converging both would
+ * leave orphans behind for a reason that never applied to one of them.
+ *
+ * The skip is not silent. The unswept subtree is reported through `failed` — the same
+ * channel that module uses for its own depth-bound breach — so nothing claims
+ * convergence over ground it did not cover (avoids PF-009, PF-015). Orphans under that
+ * subtree survive this install and the next one converges them.
+ *
+ * A subtree whose root is not a real directory ({@link convergedRootFault}) is skipped
+ * the same way and through the same channel: a sweep's `readdir` of its root follows a
+ * link planted there, so pruning it would delete inside whatever the link points at.
+ *
+ * Every name this returns is relative to the references ROOT, not to the subtree it
+ * swept. The results of the {@link CONVERGED_SUBTREES} sweeps are merged into one
+ * {@link SweepResult}, and `stale.md` removed from `pr/` and `stale.md` removed from
+ * `tracker/` would otherwise reach the install report as one indistinguishable name —
+ * a report naming a file the user cannot find. It also puts the removals in the same
+ * coordinate system as the manifest that decided them and as the stranded-skip failure
+ * below, which has always named its subtree from the root.
+ */
+async function prunePreservingRecoveryCopies(referencesTarget, subtree, manifest, overlayFailures) {
+    const subtreeRoot = underRoot(referencesTarget, subtree);
+    const prefix = `${subtree}/`;
+    // Checked here rather than trusted from the unit loop: this is the call that follows
+    // the root, and the root is re-read at the moment it would be followed.
+    const fault = await convergedRootFault(referencesTarget, subtree);
+    if (fault !== null) {
+        return { scanned: 0, removed: [], failed: [{ name: subtree, error: new Error(fault) }] };
+    }
+    const stranded = [];
+    for (const failure of overlayFailures) {
+        if (failure.state.kind !== 'restore-failed')
+            continue;
+        if (!isContainedIn(subtreeRoot, failure.state.recoveryPath))
+            continue;
+        stranded.push(failure.state.recoveryPath);
+    }
+    if (stranded.length > 0) {
+        return {
+            scanned: 0,
+            removed: [],
+            failed: [{
+                    name: subtree,
+                    error: new Error(`${subtree}: the stale-reference prune was skipped — a promotion that ` +
+                        `could not be rolled back left the only surviving copy of its references in ` +
+                        `${stranded.join(', ')}, which this prune would delete in the same run that ` +
+                        `named it as the way back. Orphaned references under ${prefix} ` +
+                        `survive this install; the next one converges them.`),
+                }],
+        };
+    }
+    // Keyed by relative path, because `tracker/{provider}/{op}.md` is what distinguishes
+    // two providers' identically named files — the reason mdEntryName cannot serve here.
+    const swept = await sweepOrphanedReferences(subtreeRoot, new Set(manifest.filter(p => p.startsWith(prefix)).map(p => p.slice(prefix.length))));
+    return {
+        scanned: swept.scanned,
+        removed: swept.removed.map(rel => `${prefix}${rel}`),
+        failed: swept.failed.map(f => ({ name: `${prefix}${f.name}`, error: f.error })),
+    };
+}
+/**
+ * Converge every wholly-generated subtree, as one result.
+ *
+ * One {@link SweepResult} rather than one per subtree because a sweep result is a
+ * REPORT, and its three fields already answer the two questions any reader has —
+ * "what went" (`removed`, each name rooted at `references/`) and "what was left
+ * unconverged, and why" (`failed`). Splitting it per subtree would push that join onto
+ * {@link recordSweep} and `devflow tracker --set`'s summary line, neither of which has
+ * anything to say about which directory a reference used to live in.
+ *
+ * `scanned` sums, which keeps it the non-vacuity counter it is everywhere else: a run
+ * that scanned nothing scanned nothing in any subtree.
+ */
+async function pruneConvergedSubtrees(referencesTarget, manifest, overlayFailures) {
+    let scanned = 0;
+    const removed = [];
+    const failed = [];
+    for (const subtree of CONVERGED_SUBTREES) {
+        const swept = await prunePreservingRecoveryCopies(referencesTarget, subtree, manifest, overlayFailures);
+        scanned += swept.scanned;
+        removed.push(...swept.removed);
+        failed.push(...swept.failed);
+    }
+    return { scanned, removed, failed };
+}
+/**
+ * Converge an installed `devflow:git` references directory onto the generated tree.
+ *
+ * Converge, not merge — for every wholly-generated subtree ({@link CONVERGED_SUBTREES}).
+ * Every unit is rebuilt from the generated sources and swapped in atomically, and anything
+ * under one of those subtrees that the manifest does not name is then removed: a shadow
+ * that supplies its own file under `tracker/` does not keep it (AC-2.4c), a provider
+ * directory the manifest stops listing is gone rather than left to rot (GAP-24), and a
+ * retired `pr/{op}.md` goes the same way for the same reason.
+ *
+ * The references ROOT is overlaid but never pruned, and that is where the guarantee stops.
+ * The flat cross-cutting documents land beside hand-authored references with no manifest of
+ * which names are hand-authored to prune against (D-OVERLAY-FLAT-UNIT), so a document
+ * retired from `GIT_CROSS_CUTTING_DOCS` keeps its installed copy until the skill directory
+ * is replaced — the one convergence this module does not deliver, and the scope
+ * CHANGELOG.md states for the shipped claim. A prunable flat root needs an allowlist of the
+ * hand-authored names, which is a Phase-3 candidate rather than a Phase-2 omission.
+ *
+ * Runs for a shadowed and a canonical install alike: a user who overrides the git skill
+ * must still receive the canonical GitHub mechanics the agent is told to load
+ * (AC-2.4a / UAC-28).
+ *
+ * The prune runs last and yields to two things only — a recovery copy this run itself
+ * created and is still relying on, and a converged root that is not a real directory
+ * (see {@link prunePreservingRecoveryCopies}); a unit that would stage or land through
+ * such a root is refused before it is built (D-CONVERGED-ROOT-REAL). Every unit this run
+ * did not refresh reaches `overlayFailures` carrying the state it was actually left in,
+ * never a blanket claim that nothing changed.
+ *
+ * A unit already installed byte-for-byte is neither written nor a failure: it is skipped
+ * and named in `unchangedRefs` (see {@link stagedUnitIsAlreadyInstalled}), so
+ * `overlaidRefs` is what this run WROTE rather than what it considered. Every run still
+ * BUILDS every unit's staging tree, because that comparison is what the convergence is —
+ * the saving is the promotion, not the work of deciding.
+ *
+ * @param opts.referencesTarget - `{claudeDir}/skills/devflow:git/references`.
+ * @param opts.sourceRoot - Generated tree; defaults to `compiledSkillRefsDir()`.
+ * @param opts.manifest - Manifest to converge to; defaults to the build registries.
+ *   Injectable so a provider set the GitHub-only build does not produce can be exercised.
+ * @param opts.warn - Receives non-fatal notices (skipped symlinks, mode normalisation).
+ *
+ * @throws on three conditions, each of them a build artifact that was never produced
+ *   rather than an I/O degradation. Every other failure is reported, never thrown
+ *   (PF-009), and the three are ordered here as the function reaches them:
+ *   1. `opts.manifest` omitted AND the reference-module registry does not expand —
+ *      raised by {@link generatedReferenceManifest} while resolving the default. A
+ *      caller that passes its own manifest cannot reach this one.
+ *   2. `opts.sourceRoot` (default {@link compiledSkillRefsDir}) does not exist at all —
+ *      see {@link requireGeneratedTree}. Nothing is installed and nothing is reported;
+ *      the refusal is the whole outcome.
+ *   3. A manifest entry is absent from a source directory that does exist — see
+ *      {@link buildUnitStagingTree}. Raised mid-loop, so units planned before the
+ *      failing one may already have been promoted.
+ */
+export async function overlayGeneratedReferences(opts) {
+    const sourceRoot = opts.sourceRoot ?? compiledSkillRefsDir();
+    const manifest = opts.manifest ?? generatedReferenceManifest();
+    const warn = opts.warn ?? (() => { });
+    const overlaidRefs = [];
+    const unchangedRefs = [];
+    const overlayFailures = [];
+    // Before the target is touched, so a refused overlay leaves the install exactly as it
+    // found it rather than a references directory it went on to abandon.
+    await requireGeneratedTree(sourceRoot, manifest);
+    await fs.mkdir(opts.referencesTarget, { recursive: true });
+    // D-CONVERGED-ROOT-REAL, unit half: a unit whose build or promotion would pass through
+    // a converged root that is not a real directory is refused before it touches anything.
+    // Every unit stages under `tracker/`, so a faulted `tracker/` refuses them all.
+    const rootFaults = new Map();
+    for (const subtree of CONVERGED_SUBTREES) {
+        const fault = await convergedRootFault(opts.referencesTarget, subtree);
+        if (fault !== null)
+            rootFaults.set(subtree, fault);
+    }
+    for (const unit of planOverlayUnits(manifest)) {
+        const fault = subtreesTouchedBy(opts.referencesTarget, unit)
+            .map(subtree => rootFaults.get(subtree))
+            .find((reason) => reason !== undefined);
+        if (fault !== undefined) {
+            overlayFailures.push({
+                unit: unitRef(unit),
+                state: await classifyUntouchedUnit(unit, opts.referencesTarget),
+                error: fault,
+            });
+            continue;
+        }
+        const built = await buildUnitStagingTree(unit, sourceRoot, opts.referencesTarget, warn);
+        if (!built.ok) {
+            overlayFailures.push({
+                unit: unitRef(unit),
+                state: await classifyUntouchedUnit(unit, opts.referencesTarget),
+                error: built.error,
+            });
+            continue;
+        }
+        // Converged already — discard the staging tree rather than promote a copy of what is
+        // installed, so `overlaidRefs` names what this run WROTE (AC-23). The discard is the
+        // same one both promotion halves perform on their way out; skipping it would leave
+        // the `.tmp` residue every other path is asserted not to leave.
+        if (await stagedUnitIsAlreadyInstalled(unit, opts.referencesTarget, built.stagingDir)) {
+            await fs.rm(built.stagingDir, { recursive: true, force: true }).catch(() => undefined);
+            unchangedRefs.push(...unit.files);
+            continue;
+        }
+        const promoted = await promoteUnitStagingTree(unit, opts.referencesTarget, built.stagingDir);
+        if (!promoted.ok) {
+            overlayFailures.push({ unit: unitRef(unit), state: promoted.state, error: promoted.error });
+            continue;
+        }
+        overlaidRefs.push(...unit.files);
+    }
+    const pruned = await pruneConvergedSubtrees(opts.referencesTarget, manifest, overlayFailures);
+    // D-OVERLAY-MODE-SCOPE: normalise the WHOLE references directory, not only the files
+    // this run installed. copyDirectory preserves source modes, so a hand-authored
+    // reference checked in with an odd mode installs with it; a reference is read-only
+    // instruction text and 0644 is what every one of them should be. Best-effort: a
+    // filesystem that does not honour mode bits must not fail an install (PF-009).
+    //
+    // This is the one step that reaches a file the overlay does not own, and it is why the
+    // boundary is stated as "never replace or delete" rather than "never touch": the MODE of
+    // a hand-authored reference — and of whatever a shadowed skill supplied outside
+    // `tracker/` — is normalised here. ADR-024 corollary (b) permits exactly that: the
+    // ownership guard protects deletion, not overwrite.
+    //
+    // It is also the one walk that can breach chmodRecursive's descent bound. The catch is
+    // that breach's reporting channel, not just an I/O guard (see {@link chmodRecursive}).
+    try {
+        await chmodRecursive(opts.referencesTarget, 0o644);
+    }
+    catch (err) {
+        warn(`reference overlay: could not normalise reference file modes — ${String(err)}`);
+    }
+    return { overlaidRefs, unchangedRefs, overlayFailures, pruned };
+}
+/** The directory inside an installed skill that the reference overlay converges. */
+const SKILL_REFERENCES_DIRNAME = 'references';
+/**
+ * What inside an installed skill directory the reference overlay owns, and the
+ * pre-clean must therefore leave standing (D-OVERLAY-OWNERSHIP).
+ *
+ * Derived from the manifest the overlay is about to converge to, never a hand-typed
+ * list: the two would be one edit apart from disagreeing, and the failure is silent —
+ * a name the pre-clean forgot is simply force-promoted again on every run, which is the
+ * defect this split exists to close.
+ *
+ * Paths are skill-relative, and what an entry contributes depends on whether a prune
+ * converges the directory it lands in — the one thing that makes preserving a whole
+ * directory safe:
+ *   - an entry under a {@link CONVERGED_SUBTREES} directory (`tracker/jira/setup-task.md`)
+ *     contributes that SUBTREE, `references/tracker`. The overlay prunes everything under
+ *     it the manifest does not name, so preserving it whole cannot strand an orphan — a
+ *     file the manifest lost leaves through {@link prunePreservingRecoveryCopies} on this
+ *     same run.
+ *   - any other entry contributes only THAT FILE: a flat one (`decision-markers.md`), and
+ *     a nested one whose directory no prune converges. The references root holds
+ *     hand-authored documents beside the generated ones with no manifest of which is
+ *     which (D-OVERLAY-FLAT-UNIT), so the overlay never prunes there and the pre-clean
+ *     must keep reaching it; a nested directory missing from the converged list is in
+ *     the same position. Preserving either wholesale would make a retired generated
+ *     document, and any stale file beside it, permanent.
+ *
+ * Deciding the subtree arm by {@link CONVERGED_SUBTREES} rather than by nesting is what
+ * makes the two lists agree by construction: a directory is kept whole exactly when a
+ * prune owns it, so a fan-out directory registered without a converged entry fails safe
+ * instead of surviving every install (avoids PF-074).
+ *
+ * Pure function (applies ADR-013). Exported for the one property no installed-tree arm
+ * can reach: the build emits no nested directory outside the converged list, so the
+ * fail-safe arm is only observable on a manifest the registry does not produce.
+ */
+export function overlayOwnedSkillPaths(manifest) {
+    const owned = new Set();
+    for (const relPath of manifest) {
+        const segments = relPath.split('/');
+        if (segments[0] === '')
+            continue;
+        const keptWhole = segments.length > 1 && isConvergedSubtree(segments[0]);
+        owned.add(`${SKILL_REFERENCES_DIRNAME}/${keptWhole ? segments[0] : relPath}`);
+    }
+    return owned;
+}
+/**
+ * Empty a directory of everything but the paths another converger owns.
+ *
+ * `fs.rm(dir)` with a hole in it. `keep` holds directory-relative paths, each preserved
+ * whole — a file as itself, a directory with its entire subtree. Everything else is
+ * removed exactly as the unconditional pre-clean would have removed it.
+ *
+ * A kept path is preserved only as a real file or directory. A symlink planted at one is
+ * removed like anything else (the link, never its target): the converger that owns the
+ * path writes and prunes through it, so a link left standing here would hand that
+ * converger someone else's directory (D-CONVERGED-ROOT-REAL). `Dirent` types are
+ * lstat-based, which is what makes the check see the link rather than its target.
+ *
+ * Descent is bounded, and the bound is the `keep` set's own deepest path rather than a
+ * constant: the walk only ever descends INTO a directory that still has a kept
+ * descendant below it, so there is nothing to look for past that depth. A `keep` set of
+ * depth 2 — which is what {@link overlayOwnedSkillPaths} produces for every manifest the
+ * build emits — walks two levels and `fs.rm`s the rest recursively in one call.
+ *
+ * An unreadable directory is left alone rather than reported: the caller already
+ * swallows the errors of the `fs.rm` this stands in for, and a pre-clean that cannot
+ * read its target has nothing to remove from it.
+ */
+async function emptyDirectoryExcept(dir, keep) {
+    const kept = [...keep];
+    const maxDepth = Math.max(0, ...kept.map(relPath => relPath.split('/').length));
+    const walk = async (current, rel, depth) => {
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const entryRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
+            if (keep.has(entryRel) && !entry.isSymbolicLink())
+                continue;
+            const holdsSomethingKept = entry.isDirectory()
+                && depth < maxDepth
+                && kept.some(relPath => relPath.startsWith(`${entryRel}/`));
+            if (holdsSomethingKept) {
+                await walk(path.join(current, entry.name), entryRel, depth + 1);
+                continue;
+            }
+            await fs.rm(path.join(current, entry.name), { recursive: true, force: true });
+        }
+    };
+    await walk(dir, '', 1);
+}
+// ---------------------------------------------------------------------------
 // Script composer
 // ---------------------------------------------------------------------------
 /** Matches relative ES import/export specifiers and dynamic import() calls. */
@@ -200,11 +1192,24 @@ function collectRelativeImports(source) {
 export async function composeScripts(scriptsTarget) {
     await fs.mkdir(scriptsTarget, { recursive: true });
     // (a) src/assets/scripts/ verbatim
+    //
+    // D-SCRIPTS-EXEC-SCOPE: only what this step copied is made executable — each of the
+    // source tree's top-level entries, at its destination. A chmod over the whole target
+    // would also reach what (b) and (c) wrote there on an earlier run (package.json, the
+    // mirrored dist/hud/ closure), so a re-run gave package.json an exec bit the first
+    // run never did and re-init stopped being a no-op on disk (#388 AC-3). Scoping the
+    // chmod to the copied entries makes the first and every later run agree.
     const srcScripts = scriptsDir();
     try {
         await copyDirectory(srcScripts, scriptsTarget);
         if (process.platform !== 'win32') {
-            await chmodRecursive(scriptsTarget, 0o755);
+            for (const entry of await fs.readdir(srcScripts, { withFileTypes: true })) {
+                const copied = path.join(scriptsTarget, entry.name);
+                if (entry.isDirectory())
+                    await chmodRecursive(copied, 0o755);
+                else if (entry.isFile())
+                    await fs.chmod(copied, 0o755);
+            }
         }
     }
     catch { /* scripts dir may not exist yet during development */ }
@@ -258,10 +1263,48 @@ export async function composeScripts(scriptsTarget) {
     }
     catch { /* already exists from prior install — leave as-is */ }
 }
+/**
+ * First path in `candidates` that exists on disk, or undefined when none do.
+ * Bounded by candidates.length. The fs.access rejection is the existence probe,
+ * not a failure: callers decide what an exhausted candidate list means.
+ */
+async function firstExisting(candidates) {
+    for (const candidate of candidates) {
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch { /* not here — try the next directory in preference order */ }
+    }
+    return undefined;
+}
+/**
+ * Registry skills that have a shadow directory under `~/.devflow/skills/`.
+ *
+ * One readdir of the SHADOW tree, intersected with the registry. Deliberately
+ * not a readdir of the installed skills directory: that tree is the thing being
+ * converged, and reading it to decide what to remove is how a directory a user
+ * put there by hand becomes a deselection (applies ADR-024).
+ *
+ * Whether a shadow is VALID is a separate question, answered per skill by
+ * validateSkillShadow at install time. This only answers "did the user write
+ * one?", which is what dormancy reporting turns on.
+ */
+async function listShadowedSkills(devflowDir) {
+    const registry = new Set(getAllSkillNames());
+    let entries;
+    try {
+        entries = await fs.readdir(path.join(devflowDir, 'skills'));
+    }
+    catch {
+        return [];
+    }
+    return entries.filter(name => registry.has(name));
+}
 /**
  * Records the result of a single orphan-sweep run into the install report.
- * Extracted from the thrice-repeated inline block to keep each call-site a
- * one-liner and ensure the kind tag is always populated. (F14)
+ * Shared by every sweep-recording call site so each stays a one-liner and
+ * the kind tag is always populated. (F14)
  */
 function recordSweep(report, kind, sweep) {
     report.sweptOrphans.push(...sweep.removed.map(name => ({ kind, name })));
@@ -275,14 +1318,36 @@ function recordSweep(report, kind, sweep) {
  * Returns an InstallReport describing which shadows were applied and which were skipped.
  */
 export async function installViaFileCopy(options) {
-    const { plugins, claudeDir, devflowDir, skillsMap, agentsMap, rulesMap = new Map(), isPartialInstall, spinner, } = options;
+    const { plugins, claudeDir, devflowDir, skillsMap, agentsMap, rulesMap = new Map(), isPartialInstall, spinner, warn = () => { }, } = options;
     const report = {
         shadowedSkills: [],
         shadowedRules: [],
         skippedShadows: [],
         sweptOrphans: [],
         sweepFailures: [],
+        overlaidRefs: [],
+        unchangedRefs: [],
+        overlayFailures: [],
+        removedSkills: [],
+        dormantShadows: [],
     };
+    // The skill decision, made in full before anything is touched — which skills
+    // this selection installs, which it removes, and which shadows it leaves inert.
+    // Pure and registry-driven: the removal set is `skillsOf(all) \ skillsOf(selected)
+    // \ FEATURE_OWNED`, never a readdir of the installed skills directory, so an
+    // unrelated `devflow:` directory a user put there by hand is not swept as a
+    // deselection (applies ADR-024).
+    //
+    // Computed BEFORE shadows are resolved: a shadow is applied only to a skill the
+    // selection installs, so the install set is the question that has to be settled
+    // first. Resolving shadows first would mean probing shadow directories for
+    // skills this run is about to remove.
+    const skillPlan = resolveSkillInstallPlan({
+        effectivePlugins: options.effectivePlugins ?? plugins,
+        isPartialInstall,
+        shadowedSkills: await listShadowedSkills(devflowDir),
+    });
+    report.dormantShadows = [...skillPlan.dormantShadows];
     // Clean old Devflow files before installing
     spinner.message('Cleaning old files...');
     if (!isPartialInstall) {
@@ -291,7 +1356,6 @@ export async function installViaFileCopy(options) {
         // without discarding assets from plugins not included in this run.
         const oldDirs = [
             path.join(claudeDir, 'commands', 'devflow'),
-            path.join(claudeDir, 'agents', 'devflow'),
             path.join(claudeDir, 'rules', 'devflow'),
         ];
         for (const dir of oldDirs) {
@@ -300,6 +1364,19 @@ export async function installViaFileCopy(options) {
             }
             catch { /* ignore */ }
         }
+        // D-TRACKER-AGENT-OWNER, pre-clean half — the same split the reference tree
+        // needed (D-OVERLAY-OWNERSHIP), for the same reason. The agent directory is
+        // emptied AROUND the one file `convergeTrackerArtifacts` owns: taking it
+        // would leave converge with nothing to byte-compare against, so a
+        // steady-state re-init would re-copy the agent and announce
+        // `tracker agent installed` on every run. Everything else is removed
+        // exactly as the unconditional wipe removed it, and the file is still
+        // converged on this run — drift in it is restored, so preserving it strands
+        // nothing.
+        try {
+            await emptyDirectoryExcept(path.join(claudeDir, 'agents', 'devflow'), new Set([mdFileName(TRACKER_AGENT_NAME)]));
+        }
+        catch { /* ignore */ }
     }
     // Sweep stale devflow:* skill dirs — ungated: runs on every install shape,
     // including partial installs, so renamed/deleted skills are pruned promptly.
@@ -317,21 +1394,67 @@ export async function installViaFileCopy(options) {
     // Pre-clean the prefixed install targets before re-copying so stale content
     // never bleeds into a fresh install. Bare pre-namespace dirs at
     // ~/.claude/skills/{name} are owned solely by the frozen LEGACY_SKILL_NAMES
-    // pass in init.ts (runs immediately after this call, init.ts:1149). A bare
-    // dir whose name matches a current registry skill is by construction foreign
-    // to Devflow and must not be touched here (avoids PF-012).
-    const allSkills = new Set();
-    for (const plugin of DEVFLOW_PLUGINS) {
-        for (const skill of plugin.skills) {
-            allSkills.add(skill);
+    // pass in init.ts (runs immediately after this call). A bare dir whose name
+    // matches a current registry skill is by construction foreign to Devflow and
+    // must not be touched here (avoids PF-012).
+    //
+    // The pre-clean is SCOPED to what this run reinstalls and the orphan sweep
+    // above is UNSCOPED (the full registry). The opposite scoping is deliberate,
+    // not an inconsistency waiting to be simplified away:
+    //   - the sweep removes names the registry no longer has at all, which is true
+    //     regardless of selection, so a partial install must still prune them;
+    //   - the pre-clean empties a directory this run is about to rewrite, so
+    //     widening it past the install set would delete a selected plugin's skill
+    //     and never put it back.
+    // Gated on a full install for the same reason: `--plugin=X` rewrites X's
+    // skills only, and a pre-clean over the whole registry would wipe every other
+    // plugin's skills on an add-one run.
+    //
+    // ONE skill is pre-cleaned around a hole rather than emptied: the skill hosting the
+    // generated references, whose overlay-owned subtree belongs to
+    // {@link overlayGeneratedReferences} and to nothing else (D-OVERLAY-OWNERSHIP). The
+    // two mechanisms are not alternatives — the overlay is a CONVERGER and the pre-clean
+    // is not, so handing it the subtree loses what the converger is for:
+    //   - the overlay compares each unit against what is installed and skips the ones
+    //     already correct ({@link stagedUnitIsAlreadyInstalled}). A pre-clean that deletes
+    //     the installed copy first leaves it nothing to compare against, so every unit is
+    //     force-promoted and a re-init that changed nothing still reports the whole
+    //     manifest as written (QA S2);
+    //   - the overlay PRUNES every wholly-generated subtree (`tracker/`, `pr/`) down to the
+    //     manifest and swaps each unit atomically, so drift and orphans under those subtrees
+    //     are converged away without the pre-clean reaching them at all.
+    // Everything else in the directory is still emptied, so a stale hand-authored skill
+    // file — including a reference at the references ROOT, which the overlay may replace
+    // but never delete (D-OVERLAY-FLAT-UNIT) — does not survive a full install.
+    if (!isPartialInstall) {
+        const overlayOwned = overlayOwnedSkillPaths(installedReferenceManifest());
+        for (const skill of skillsMap.keys()) {
+            // Empty the prefixed directory (its contents are re-created during the install
+            // phase), minus whatever another converger owns inside it.
+            const target = path.join(claudeDir, 'skills', prefixSkillName(skill));
+            try {
+                if (skill === SKILL_REFS_SKILL_NAME) {
+                    await emptyDirectoryExcept(target, overlayOwned);
+                }
+                else {
+                    await fs.rm(target, { recursive: true, force: true });
+                }
+            }
+            catch { /* ignore */ }
         }
     }
-    for (const skill of allSkills) {
-        // Remove prefixed directory (will be re-created during install phase)
+    // Remove the skills no selected plugin owns or requires — the deselection half
+    // of the scoped install. Empty on a partial install by construction
+    // (resolveSkillInstallPlan gates it), so `--plugin=X` adds and never subtracts
+    // (AC-22). Failures are per-item and non-fatal (applies PF-009).
+    for (const skill of skillPlan.remove) {
         try {
             await fs.rm(path.join(claudeDir, 'skills', prefixSkillName(skill)), { recursive: true, force: true });
+            report.removedSkills.push(skill);
+        }
+        catch (err) {
+            warn(`Could not remove deselected skill "${prefixSkillName(skill)}" — ${String(err)}`);
         }
-        catch { /* ignore */ }
     }
     // Install commands from selected plugins using registry-driven lookup.
     // Source: dist/commands/{name}.md (single lookup directory for all commands).
@@ -364,14 +1487,30 @@ export async function installViaFileCopy(options) {
     // knownNames spans ALL plugins (getAllCommandNames) so commands from uninstalled
     // plugins survive a partial run. Only names absent from the full registry are removed.
     recordSweep(report, 'command', await sweepOrphanedAssets(commandsTarget, new Set(getAllCommandNames()), mdEntryName));
-    // Install agents (deduplicated) from flat src/assets/agents/{name}.md.
-    // A declared agent whose source file is absent is a build/packaging failure
-    // and throws rather than silently skipping (matches command pattern).
+    // Install agents (deduplicated), resolved dist-first with a src fallback:
+    // dist/agents/{name}.md (compiled from an .mds generator host) wins over
+    // src/assets/agents/{name}.md. A declared agent absent from BOTH is a
+    // build/packaging failure and throws rather than silently skipping (matches
+    // command pattern); the message names the build step as well as the tree.
+    //
+    // D-TRACKER-AGENT-OWNER: every declared agent but ONE. The Tracker agent is
+    // converged by `convergeTrackerArtifacts` alone (plan A3), which runs after this
+    // function in init and reports whether this run wrote it. Copying it here too
+    // would make every install do the work twice, and a fresh install would never
+    // report `installed` because converge would find this loop's byte-identical copy
+    // already in place.
+    //
+    // The name is skipped from the COPY set only. It stays declared in
+    // `devflow-core-skills.agents`, so the sweep below — which keys on the full
+    // registry via getAllAgentNames() — still treats a converged tracker.md as known
+    // and leaves it alone.
     const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
-    const aDir = agentsDir();
+    const agentDirs = options.agentSourceDirs ?? agentSourceDirs();
     const allAgentNames = new Set();
     for (const plugin of plugins) {
         for (const agent of plugin.agents) {
+            if (agent === TRACKER_AGENT_NAME)
+                continue;
             if (!allAgentNames.has(agent) && agentsMap.get(agent) === plugin.name) {
                 allAgentNames.add(agent);
             }
@@ -380,13 +1519,12 @@ export async function installViaFileCopy(options) {
     if (allAgentNames.size > 0) {
         await fs.mkdir(agentsTarget, { recursive: true });
         for (const agentName of allAgentNames) {
-            const srcFile = path.join(aDir, mdFileName(agentName));
-            try {
-                await fs.access(srcFile);
-            }
-            catch {
-                throw new Error(`Agent source not found for declared agent "${agentName}": ${srcFile}. ` +
-                    `Ensure the agent file exists in src/assets/agents/.`);
+            const candidates = agentDirs.map(dir => path.join(dir, mdFileName(agentName)));
+            const srcFile = await firstExisting(candidates);
+            if (srcFile === undefined) {
+                throw new Error(`Agent source not found for declared agent "${agentName}": ${candidates[0]}. ` +
+                    `Run \`npm run build:mds\` if it is compiled from an .mds generator host, otherwise ` +
+                    `ensure the agent file exists in src/assets/agents/ (searched: ${candidates.join(', ')}).`);
             }
             await fs.copyFile(srcFile, path.join(agentsTarget, mdFileName(agentName)));
         }
@@ -427,6 +1565,23 @@ export async function installViaFileCopy(options) {
         else {
             await copyDirectory(skillSource, skillTarget);
         }
+        // Converge the generated references onto the skill that was just installed. One call
+        // site downstream of all three branches above, so a shadowed devflow:git receives the
+        // canonical GitHub mechanics exactly as a canonical install does — AC-2.4a / UAC-28,
+        // which is a release blocker, not merely an acceptance criterion.
+        if (skillName === SKILL_REFS_SKILL_NAME) {
+            const overlay = await overlayGeneratedReferences({
+                referencesTarget: path.join(skillTarget, 'references'),
+                // Every provider's mechanics (D-INSTALL-ALL-PROVIDERS). The overlay
+                // converges rather than merges, so a retired generated document is pruned.
+                manifest: installedReferenceManifest(),
+                warn,
+            });
+            report.overlaidRefs.push(...overlay.overlaidRefs);
+            report.unchangedRefs.push(...overlay.unchangedRefs);
+            report.overlayFailures.push(...overlay.overlayFailures);
+            recordSweep(report, 'reference', overlay.pruned);
+        }
     }
     // Install rules from selected plugins (rulesMap covers selected plugins only).
     // Rules are flat .md files resolved from src/assets/rules/{name}.md (no per-plugin subdir).