mandrel 2.60.0 → 2.61.0

package/lib/cli/sync-agents.js

@@ -1,47 +1,9 @@
 // lib/cli/sync-agents.js
 /**
- * `mandrel sync-agents` subcommand (Story #4528 / #4530).
- *
- * Thin wrapper that delegates to the canonical sync script
- * (.agents/scripts/sync-claude-agents.js), projecting `.agents/agents/` into
- * a flat `.claude/agents/` tree. Exact sibling of `sync-commands.js` —
- * same delegation shape, same marker-gated refusal check, same seams —
- * targeting the role-agent tree instead of the command tree. The sync
- * script owns all sync logic; this module exists only to expose it through
- * the mandrel CLI surface without reimplementing it.
- *
- * `sync-claude-agents.js` uses top-level await and has no exported `main()`
- * function (marked `cli-opt-out`), so delegation runs via a child process
- * rather than a direct import. Exit code and all output are forwarded
- * verbatim to the caller so `mandrel sync-agents` is transparent to scripts
- * that check $?.
- *
- * ## Prior to this Story
- *
- * `sync-claude-agents.js` was invoked on the **bootstrap** path
- * (`project-bootstrap.js`'s `sync:agents` script, `prepare`, and
- * `runSyncCommands`) but had no `lib/cli/` subcommand counterpart and was
- * never run by `mandrel sync` / `mandrel update` on the CLI path — the gap
- * #4528 reported. See `update.js`'s `driftHealSteps()` /
- * `fullUpgradeSteps()`, which now spawn a `sync-agents` phase alongside
- * `sync-commands` so `.claude/agents/` materializes on that path too.
- *
- * ## Marker-gated refusal (Story #4526 / #4530) — same shape as sync-commands
- *
- * Before delegating, this wrapper checks whether the `.agents/` tree it is
- * about to project agents FROM actually matches the running CLI's own
- * payload version, exactly as `sync-commands.js` does for the command tree.
- * See that module's doc comment for the full rationale and the anchor-trap
- * warning — it applies identically here (`PROJECT_ROOT` is deliberately the
- * package root, used only to read the running CLI's OWN version; the marker
- * read is anchored at `cwd()`, never at `PROJECT_ROOT`).
- *
- * Gate order:
- *   1. Marker present (`.agents/.mandrel-version`) → compare it to the
- *      running CLI's own package version. Mismatch → refuse.
- *   2. Marker absent (a pre-marker install) → fall back to the existing
- *      `agents-drift` content-hash check. Drift detected → refuse.
- *   3. Clean either way → project as before.
+ * `mandrel sync-agents`: project `.agents/agents/` into `.claude/agents/` via
+ * `.agents/scripts/sync-claude-agents.js`. Exact sibling of
+ * `sync-commands.js` — same child-process delegation, same marker-gated
+ * refusal and anchor rule (see that module's doc).
  */
 
 import { spawnSync } from 'node:child_process';
@@ -63,11 +25,6 @@ const SYNC_SCRIPT = path.join(
 );
 
 /**
- * Resolve the running CLI's own package version from `PROJECT_ROOT`'s
- * `package.json`. See `sync-commands.js`'s "anchor trap" module doc: this is
- * the ONE place `PROJECT_ROOT` (the package's own two-dirs-up root) is the
- * correct anchor.
- *
  * @param {typeof nodeFs} fsImpl
  * @returns {string}
  */
@@ -79,23 +36,6 @@ function resolveOwnPackageVersion(fsImpl) {
 }
 
 /**
- * Run the sync-claude-agents script and forward its output + exit code —
- * unless the marker-gated refusal check (see module doc) finds the
- * `.agents/` tree mismatched against the running CLI, in which case it
- * refuses and exits non-zero before spawning anything.
- *
- * Injectable seams — identical shape to `sync-commands.js`:
- * - `runner` — replaces `spawnSync` for the real delegation.
- * - `cwd()` — replaces `process.cwd`; anchors the marker read at the
- *   consumer project root.
- * - `fs` — replaces the `node:fs` surface for both the marker read and the
- *   own-version read.
- * - `ownVersion` — overrides the running CLI's own resolved version
- *   directly, bypassing `resolveOwnPackageVersion`.
- * - `checkAgentsDrift` — overrides the fallback drift probe used when the
- *   marker is absent; defaults to `runAgentsDrift({ cwd })`.
- * - `writeErr` / `exit` — replace the corresponding process surfaces.
- *
  * @param {string[]} _argv - Unused; reserved for future flags.
  * @param {{
  *   runner?: typeof spawnSync,

package/lib/cli/sync-commands.js

@@ -1,49 +1,18 @@
 // lib/cli/sync-commands.js
 /**
- * `mandrel sync-commands` subcommand.
+ * `mandrel sync-commands`: delegate to `.agents/scripts/sync-claude-commands.js`
+ * in a child process (it has top-level await and no exported main), forwarding
+ * output and exit code.
  *
- * Thin wrapper that delegates to the canonical sync script
- * (.agents/scripts/sync-claude-commands.js). The sync script owns all sync
- * logic; this module exists only to expose that logic through the mandrel CLI
- * surface without reimplementing it.
+ * Refuses first when `.agents/` does not match the running CLI — otherwise
+ * commands are projected from a stale tree, and since `.claude/*` is
+ * gitignored nothing surfaces until an agent hits a missing module. With the
+ * `.agents/.mandrel-version` marker, compare it to the CLI's own version;
+ * without it, fall back to the `agents-drift` content check.
  *
- * The sync script uses top-level await and has no exported `main()` function
- * (marked `cli-opt-out`), so delegation runs via a child process rather than
- * a direct import. Exit code and all output are forwarded verbatim to the
- * caller so `mandrel sync-commands` is transparent to scripts that check $?.
- *
- * ## Marker-gated refusal (Story #4526 / #4530)
- *
- * Before delegating, this wrapper checks whether the `.agents/` tree it is
- * about to project commands FROM actually matches the running CLI's own
- * payload version. Without this gate, a consumer whose `.agents/` tree lags
- * the installed package (see #4525's pin-skew scenario) gets commands
- * faithfully projected from a **stale** tree — describing a workflow whose
- * backing scripts are not installed. Because `.claude/*` is conventionally
- * gitignored, that wrong projection leaves no diff and no signal until an
- * agent hits a missing-module error mid-task, far from the actual cause.
- *
- * Gate order:
- *   1. Marker present (`.agents/.mandrel-version`, Story #4530) → compare it
- *      to the running CLI's own package version. Mismatch → refuse.
- *   2. Marker absent (a pre-marker install with no baseline to compare) →
- *      fall back to the existing `agents-drift` content-hash check
- *      (`registry.js`). Drift detected → refuse.
- *   3. Clean either way → project as before.
- *
- * ## Anchor trap (do not repeat)
- *
- * `PROJECT_ROOT` below is deliberately the **package** root — resolved from
- * this module's own two-dirs-up location — because it is used ONLY to read
- * the running CLI's OWN version, which is exactly what that self-referential
- * pattern correctly answers (contrast with the #4525 bug in `update.js`,
- * where the same pattern was wrongly used to answer a *consumer*-pin
- * question). The marker read is a SEPARATE resolution, anchored at `cwd()`
- * (the consumer project root) via `readVersionMarker` — never at
- * `PROJECT_ROOT`. Comparing the marker to `PROJECT_ROOT`'s own version would
- * make the check compare the package against itself and could never fire —
- * the exact trap `registry.js`'s `agents-in-sync` check documents for the
- * same reason.
+ * `PROJECT_ROOT` (the package root) answers only "what version is this CLI";
+ * the marker is read from `cwd()`. Reading both from `PROJECT_ROOT` would
+ * compare the package with itself and never fire.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -65,10 +34,6 @@ const SYNC_SCRIPT = path.join(
 );
 
 /**
- * Resolve the running CLI's own package version from `PROJECT_ROOT`'s
- * `package.json`. See the "anchor trap" module doc: this is the ONE place
- * `PROJECT_ROOT` (the package's own two-dirs-up root) is the correct anchor.
- *
  * @param {typeof nodeFs} fsImpl
  * @returns {string}
  */
@@ -80,24 +45,6 @@ function resolveOwnPackageVersion(fsImpl) {
 }
 
 /**
- * Run the sync-claude-commands script and forward its output + exit code —
- * unless the marker-gated refusal check (see module doc) finds the
- * `.agents/` tree mismatched against the running CLI, in which case it
- * refuses and exits non-zero before spawning anything.
- *
- * Injectable seams (used by tests so no real filesystem, child process, or
- * package resolution occurs on the gate path):
- * - `runner` — replaces `spawnSync` for the real delegation.
- * - `cwd()` — replaces `process.cwd`; anchors the marker read at the
- *   consumer project root.
- * - `fs` — replaces the `node:fs` surface for both the marker read and the
- *   own-version read.
- * - `ownVersion` — overrides the running CLI's own resolved version
- *   directly, bypassing `resolveOwnPackageVersion`.
- * - `checkAgentsDrift` — overrides the fallback drift probe used when the
- *   marker is absent; defaults to `runAgentsDrift({ cwd })`.
- * - `writeErr` / `exit` — replace the corresponding process surfaces.
- *
  * @param {string[]} _argv - Unused; reserved for future flags.
  * @param {{
  *   runner?: typeof spawnSync,

package/lib/cli/sync.js

@@ -1,64 +1,16 @@
 // lib/cli/sync.js
 /**
- * `mandrel sync` subcommand — the .agents/ materializer.
+ * `mandrel sync`: materialize `node_modules/mandrel/.agents/` into
+ * `./.agents/` by plain file copy (never symlinks, so Windows and POSIX
+ * match), then prune managed-zone files with no payload counterpart and write
+ * the version marker. Idempotent; `--dry-run` writes nothing. `.agents/local/`
+ * and `*.local.*` files are never copied into or pruned.
  *
- * Copies the published package payload
- * (`node_modules/mandrel/.agents/`) into the consumer project's
- * `./.agents/` directory by **plain file copy** — never a symlink — so
- * Windows and POSIX behave identically (Tech Spec #3459, Feature #3461).
- *
- * Design contract (per Story #3467 AC, Tech Spec #3459 "API Changes", and
- * Story #4046 sync-prune):
- *   - Copy, not symlink. The materialized tree is plain regular files.
- *   - Idempotent. A second run overwrites in place and leaves ./.agents/
- *     byte-identical to the package payload.
- *   - Self-locating. The package root is resolved from the installed
- *     `mandrel` package metadata, not from the current working
- *     directory, so it works regardless of where `mandrel` is invoked.
- *   - Exits non-zero with an actionable message when `mandrel` is
- *     not resolvable in node_modules.
- *   - `--dry-run` reports the planned copies and writes nothing.
- *   - Local-additions zone. The `.agents/local/` subtree is never copied
- *     into nor pruned from the destination (Story #3498). It is the
- *     consumer-owned space for hand-authored additions that must survive
- *     every re-materialization.
- *   - Sync prune (Story #4046). After the copy pass, any file inside the
- *     managed `.agents/` zone (everything except `.agents/local/`) that has
- *     no counterpart in the package payload is deleted. Consumer additions
- *     under `.agents/local/` are never touched.
- *   - Generated, never-pruned registry (Story #4534). Framework-generated
- *     `.agents/` files have no payload counterpart by design, so the prune
- *     pass would delete each one unless it is declared in
- *     {@link GENERATED_FILES}. That registry — not a per-file special case in
- *     {@link listDestFiles} — is the single place a generated artifact is
- *     exempted. Registered today: the version marker (Story #4530) and the
- *     install ledger the bootstrap writes and `mandrel uninstall` reads.
- *   - Version marker (Story #4530). After the prune pass, `.agents/.mandrel-
- *     version` is (re)written with the executing package's own version. See
- *     {@link readVersionMarker} for how callers consume it.
- *
- * Security (Tech Spec #3459 "Postinstall safety"):
- *   - No network, and no shell: every child process is spawned with argv
- *     tokens and `shell: false`.
- *   - Logs only paths and counts, never file contents or environment values.
- *   - One write outside `./.agents/` (Story #5277): the per-clone
- *     `merge.mandrel-baseline.driver` git config, and only when the project's
- *     own tracked `.gitattributes` already declares the attribute that needs
- *     it. That half of the registration cannot ship with the repository — git
- *     will not execute a command chosen by whoever wrote it — so every fresh
- *     clone silently text-merges generated baselines until something installs
- *     it locally, and `sync` is the one command every consumer runs. It never
- *     creates or edits `.gitattributes`; a project that has not opted into the
- *     quality surface is left untouched.
- *
- * Injectable seams (used by lib/cli/__tests__/sync.test.js):
- *   - `resolvePackageRoot` — replaces real `mandrel` resolution
- *   - `fs`                 — replaces the node:fs surface used here
- *   - `cwd`                — replaces process.cwd()
- *   - `ensureMergeDriver`  — replaces the git-config merge-driver install
- *   - `write`              — replaces process.stdout.write
- *   - `writeErr`           — replaces process.stderr.write
- *   - `exit`               — replaces process.exit
+ * No network, no shell. The one write outside `./.agents/` is the per-clone
+ * `merge.mandrel-baseline.driver` git config, made only when the project's
+ * tracked `.gitattributes` already declares the attribute — git will not run
+ * a command shipped by the repo, so every fresh clone needs it installed
+ * locally, and `sync` is the command every consumer runs.
  */
 
 import nodeFs from 'node:fs';
@@ -70,56 +22,22 @@ import { LEDGER_RELATIVE_PATH } from '../../.agents/scripts/lib/bootstrap/instal
 
 export const PACKAGE_NAME = 'mandrel';
 
-/**
- * Name of the managed destination directory, relative to the project root.
- * Generating modules export their artifact paths relative to the *project
- * root* (e.g. `install-ledger.js`'s `LEDGER_RELATIVE_PATH`), whereas the
- * prune pass compares paths relative to this directory — {@link
- * toManagedZoneRelative} is the one conversion between the two.
- */
 const AGENTS_DIR = '.agents';
 
-/**
- * Top-level directory name (relative to `.agents/`) reserved as the
- * sync-exempt local-additions zone (Story #3498, f-drift-local-zone).
- *
- * `.agents/local/` is a sanctioned space for consumer hand-authored
- * additions: `mandrel sync` never copies a payload file into it (the
- * published payload ships none) and never prunes what a consumer has
- * placed there, so local additions survive every re-materialization. The
- * exemption is enforced by skipping this subtree during source enumeration,
- * which keeps both the dry-run plan and the real copy free of any
- * `.agents/local/**` path even if a future payload were to ship one.
- */
+/** Top-level `.agents/` subdirectory reserved for consumer additions. */
 export const LOCAL_ZONE_DIR = 'local';
 
-/**
- * Basename pattern for consumer local-override files (`*.local.<ext>`,
- * e.g. `instructions.local.md`, `foo.local.json`). Matches the gitignore
- * convention (`.agents/*.local.md`, `.agentrc.local.json`) and the override
- * mechanism documented in `.agents/instructions.md` § 1.E. These files never
- * ship in the payload and are exempt from the sync prune pass.
- */
+/** Consumer local-override basenames (`instructions.local.md`, …). */
 export const LOCAL_OVERRIDE_RE = /\.local\.[^.]+$/;
 
-/**
- * Relative path (from `.agents/`) of the version marker `runSync` writes
- * after every sync, carrying the executing package's own version.
- */
+/** `.agents/`-relative path of the version marker written after each sync. */
 export const VERSION_MARKER_RELATIVE_PATH = '.mandrel-version';
 
 /**
- * Convert a project-root-relative POSIX path — the shape a generating module
- * exports as its own source of truth (e.g. `install-ledger.js`'s
- * `LEDGER_RELATIVE_PATH`, `'.agents/.install-manifest.json'`) — into the
- * `.agents/`-relative, OS-separator form {@link listDestFiles} enumerates and
- * {@link GENERATED_FILES} is compared against.
- *
- * Throws on a path outside `.agents/`: a generated file the sync prune pass
- * never walks has no business in the registry, and registering one would be a
- * silent no-op that reads as protection. Failing at module load surfaces the
- * mistake at the first import rather than as a mystery deletion in a
- * consumer's tree.
+ * Convert a project-root-relative POSIX path into the `.agents/`-relative,
+ * OS-separator form {@link listDestFiles} enumerates. Throws on a path
+ * outside `.agents/` at module load, since registering one would be a silent
+ * no-op that reads as protection.
  *
  * @param {string} projectRelativePosixPath - e.g. `.agents/.install-manifest.json`.
  * @returns {string} e.g. `.install-manifest.json` (OS separators).
@@ -136,50 +54,20 @@ function toManagedZoneRelative(projectRelativePosixPath) {
 }
 
 /**
- * The **generated, never-pruned registry**: every framework-generated
- * `.agents/` file that has no payload counterpart and must therefore be
- * exempted from the prune pass. Paths are `.agents/`-relative with OS
- * separators, matching what {@link listDestFiles} enumerates.
- *
- * The prune pass (Story #4046 A3) deletes any managed-zone file absent from
- * the payload. That is the correct rule for consumer drift, but it is also
- * exactly the shape of every file the framework itself generates into
- * `.agents/` outside the payload — so each such artifact is deleted by the very
- * sync that wrote it unless registered here. Two have hit this already: the
- * install ledger (`.agents/.install-manifest.json`), whose loss made
- * `mandrel uninstall` silently reverse nothing and exit 0 (Story #4534), and
- * the version marker (Story #4530).
- *
- * This is deliberately a **registry, not a list of special cases**. Register a
- * new generated file by adding one entry here — keyed off the generating
- * module's own exported constant wherever one exists, never a duplicated
- * string literal — rather than by adding another branch to
- * {@link listDestFiles}. That keeps the never-prune contract declared in one
- * place and keeps the registry honest: if the generator renames its artifact,
- * the exemption moves with it.
- *
- * This registry does **not** subsume the `.agents/local/` zone or the
- * `*.local.*` overrides ({@link LOCAL_ZONE_DIR}, {@link LOCAL_OVERRIDE_RE}).
- * Those are a different concept — consumer-authored overrides, not
- * framework-generated artifacts — and stay separate on purpose.
+ * Framework-generated `.agents/` files with no payload counterpart, which the
+ * prune pass would otherwise delete (losing the install ledger makes
+ * `mandrel uninstall` silently reverse nothing). Register a new one here,
+ * keyed off the generator's exported constant — not as a branch in
+ * {@link listDestFiles}. Consumer overrides are a separate concept.
  */
 export const GENERATED_FILES = Object.freeze([
-  // Version marker (Story #4530) — written by runSync itself, below.
   VERSION_MARKER_RELATIVE_PATH,
-  // Install ledger (Story #4534) — written by the bootstrap
-  // (`install-ledger.js`), read by `mandrel uninstall` as its single source of
-  // truth. Keyed off the generator's exported constant.
   toManagedZoneRelative(LEDGER_RELATIVE_PATH),
 ]);
 
 /**
- * Resolve the version of the package whose `.agents/` payload was just
- * copied — i.e. the version the marker must carry. Reads `package.json` at
- * the already-resolved `packageRoot`, never the two-directories-up
- * self-referential pattern `lib/cli/update.js`'s pre-Story-#4530
- * `defaultCurrentVersion` used (that pattern conflates "the CLI that is
- * running" with "the payload that was materialized" — the exact confusion
- * #4525 fixes on the consumer-pin side of this Story).
+ * Version of the payload just copied, read at `packageRoot` — not the
+ * running CLI's own version, which may differ.
  *
  * @param {string} packageRoot - Absolute path to the resolved package root.
  * @param {typeof nodeFs} fsImpl
@@ -192,10 +80,8 @@ function resolvePackageVersion(packageRoot, fsImpl) {
 }
 
 /**
- * Read the consumer's `.agents/.mandrel-version` marker. Returns `null` when
- * absent — a pre-marker install, or a tree that has never been synced —
- * so callers (the sync-commands mismatch refusal, the doctor pin check) can
- * degrade to their existing content-hash drift check rather than failing.
+ * `null` when absent (pre-marker install or never synced), so callers can
+ * fall back to content-hash drift checks.
  *
  * @param {string} consumerRoot - Consumer project root (not `.agents/`).
  * @param {typeof nodeFs} [fsImpl]
@@ -216,33 +102,21 @@ export function readVersionMarker(consumerRoot, fsImpl = nodeFs) {
 }
 
 /**
- * Default resolver: locate the installed `mandrel` package root by
- * resolving its `package.json` and returning the directory that contains it.
- *
- * Throws an Error with `code: 'MODULE_NOT_FOUND'` when the package is not
- * installed — the caller maps that to an actionable non-zero exit.
+ * Resolved from the consumer project so it finds their install, not a copy
+ * hoisted next to this module. Throws `MODULE_NOT_FOUND` when not installed.
  *
  * @param {string} fromDir - Directory to resolve from (the consumer project).
  * @returns {string} Absolute path to the package root.
  */
 export function defaultResolvePackageRoot(fromDir) {
-  // Resolve relative to the consumer project so we find *their* install,
-  // not a copy hoisted next to this CLI module.
   const requireFrom = createRequire(path.join(fromDir, 'noop.js'));
   const pkgJsonPath = requireFrom.resolve(`${PACKAGE_NAME}/package.json`);
   return path.dirname(pkgJsonPath);
 }
 
 /**
- * Recursively enumerate every regular file under `dir`, returning paths
- * relative to `dir` using POSIX-agnostic OS separators.
- *
- * Symlinks encountered in the source are dereferenced to their target file
- * content on copy (we never create symlinks in the destination).
- *
- * The top-level `local/` subtree (`.agents/local/`) is skipped entirely:
- * it is the consumer-owned local-additions zone and is never materialized
- * from the package payload (Story #3498). See {@link LOCAL_ZONE_DIR}.
+ * Every file under `dir` (relative, OS separators), skipping the top-level
+ * local zone only.
  *
  * @param {string} dir - Absolute directory to walk.
  * @param {typeof nodeFs} fsImpl
@@ -252,9 +126,6 @@ export function defaultResolvePackageRoot(fromDir) {
 export function listFiles(dir, fsImpl, prefix = '') {
   const out = [];
   for (const ent of fsImpl.readdirSync(dir, { withFileTypes: true })) {
-    // Never enumerate the sync-exempt local-additions zone. Matching on the
-    // empty prefix scopes the skip to the top-level `.agents/local/` only,
-    // leaving any deeper directory that happens to be named `local` intact.
     if (prefix === '' && ent.name === LOCAL_ZONE_DIR && ent.isDirectory()) {
       continue;
     }
@@ -270,26 +141,8 @@ export function listFiles(dir, fsImpl, prefix = '') {
 }
 
 /**
- * Recursively enumerate every regular file under `dir`, returning paths
- * relative to `dir` using OS separators. Three disjoint classes are skipped,
- * so a caller diffing this against the payload never treats them as stale:
- *
- *   1. The top-level `local/` subtree — consumer additions inside
- *      `.agents/local/` are never pruned (Story #3498).
- *   2. Files matching the `*.local.*` convention (e.g.
- *      `.agents/instructions.local.md`) — the documented consumer override
- *      mechanism (instructions.md § 1.E); they never ship in the payload and
- *      must survive every sync.
- *   3. Everything declared in the {@link GENERATED_FILES} registry —
- *      framework-generated artifacts with no payload counterpart by design
- *      (Story #4534). New generated files are registered there, not added as
- *      a fourth branch here.
- *
- * (1) and (2) are consumer-authored; (3) is framework-generated. They are
- * kept separate deliberately — conflating them would muddy both contracts.
- *
- * Mirrors `listFiles` but operates on the destination tree so we can
- * identify stale files that have no payload counterpart (Story #4046 A3).
+ * Destination-tree enumeration for pruning. Skips the top-level local zone,
+ * `*.local.*` overrides, and {@link GENERATED_FILES}.
  *
  * @param {string} dir - Absolute directory to walk.
  * @param {typeof nodeFs} fsImpl
@@ -302,23 +155,16 @@ function listDestFiles(dir, fsImpl, prefix = '') {
   try {
     entries = fsImpl.readdirSync(dir, { withFileTypes: true });
   } catch {
-    // Directory absent — nothing to prune.
     return out;
   }
   for (const ent of entries) {
-    // The local-additions zone is never pruned; skip it at the top level.
     if (prefix === '' && ent.name === LOCAL_ZONE_DIR && ent.isDirectory()) {
       continue;
     }
-    // Consumer local-override files (`*.local.*`, e.g. instructions.local.md,
-    // foo.local.json) are gitignored, never shipped in the payload, and a
-    // documented override mechanism (instructions.md § 1.E) — never prune.
     if (!ent.isDirectory() && LOCAL_OVERRIDE_RE.test(ent.name)) {
       continue;
     }
     const rel = prefix ? path.join(prefix, ent.name) : ent.name;
-    // Framework-generated artifacts — declared once in the never-pruned
-    // registry (Story #4534); see GENERATED_FILES.
     if (!ent.isDirectory() && GENERATED_FILES.includes(rel)) {
       continue;
     }
@@ -333,13 +179,6 @@ function listDestFiles(dir, fsImpl, prefix = '') {
 }
 
 /**
- * Materialize the package's `.agents/` tree into `./.agents/`.
- *
- * After the copy pass, any file inside the managed zone of the destination
- * `.agents/` tree (everything outside `.agents/local/`) that has no
- * counterpart in the package payload is deleted (sync-prune, Story #4046 A3).
- * Consumer additions placed under `.agents/local/` are never touched.
- *
  * @param {{
  *   argv?: string[],
  *   resolvePackageRoot?: (fromDir: string) => string,
@@ -395,8 +234,6 @@ export function runSync({
     for (const rel of payloadFiles) {
       write(`would copy  ${path.join('.agents', rel)}\n`);
     }
-    // Compute stale files (managed-zone destination files with no payload
-    // counterpart) for the dry-run plan so operators can preview pruning.
     const payloadSet = new Set(payloadFiles);
     const destFiles = listDestFiles(destRoot, fs);
     const stale = destFiles.filter((f) => !payloadSet.has(f));
@@ -418,15 +255,9 @@ export function runSync({
     const src = path.join(sourceRoot, rel);
     const dest = path.join(destRoot, rel);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
-    // copyFileSync overwrites the destination in place (idempotent) and
-    // produces a plain regular file — never a symlink.
     fs.copyFileSync(src, dest);
   }
 
-  // Prune pass (Story #4046 A3): remove managed-zone destination files that
-  // have no counterpart in the payload. The local-additions zone
-  // (.agents/local/) is never enumerated by listDestFiles and is therefore
-  // never pruned — consumer additions there are sanctioned, not stale.
   const payloadSet = new Set(payloadFiles);
   const destFiles = listDestFiles(destRoot, fs);
   const staleFiles = destFiles.filter((f) => !payloadSet.has(f));
@@ -435,22 +266,14 @@ export function runSync({
     fs.unlinkSync(dest);
   }
 
-  // Version marker (Story #4530): written AFTER the prune pass, never
-  // before — the GENERATED_FILES registry already keeps listDestFiles from
-  // ever enumerating it as stale, but ordering the write after prune is a
-  // second, independent safeguard against the same class of bug (see the
-  // GENERATED_FILES doc comment) surviving a future prune-pass reorder. The
-  // install ledger gets no such belt-and-braces: it is written by the
-  // bootstrap, not here, so the registry is its only protection.
+  // Written after the prune as a second safeguard beside GENERATED_FILES.
   const packageVersion = resolvePackageVersion(packageRoot, fs);
   fs.writeFileSync(
     path.join(destRoot, VERSION_MARKER_RELATIVE_PATH),
     `${packageVersion}\n`,
   );
 
-  // Baseline merge driver (Story #5277) — config half only; see the module
-  // preamble's security note. Never allowed to fail the sync: a consumer
-  // without git, or with a read-only config, still gets their `.agents/` tree.
+  // Config half only; never allowed to fail the sync (no git, read-only config).
   const driver = ensureMergeDriver({
     projectRoot,
     configOnly: true,
@@ -476,8 +299,6 @@ export function runSync({
 }
 
 /**
- * Default export consumed by `bin/mandrel.js`.
- *
  * @param {string[]} argv - Subcommand arguments (after `mandrel sync`).
  * @returns {Promise<void>}
  */