@sdd-method/maintain-cli 0.0.0-stage → 0.1.0-rc.0

package/dist/lib/sync/index.js

@@ -0,0 +1,809 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { loadBundle } from "../bundle.js";
+import { getSddCliVersion } from "../package-version.js";
+import { LOCK_VERSION, findBundle, findForwardBase, hasForwardBase, pathToBundleMap, readLockFile, removeBundle, upsertBundle, writeLockFile, } from "../lock-file.js";
+import { REPO_KIND_FILE, profileFromBundleName, repoKindFromProfile, writeRepoKind, } from "../repo-kind.js";
+import { join } from "node:path";
+import { copyManagedFiles, removeManagedFiles } from "./apply.js";
+import { cacheBundle, ensureCacheGitignored, splitConsumptionModes, } from "./bundle-cache.js";
+import { PROTECTED_PREFIXES, allPristine, classifyConflicts, computeRemovals, detectShadowCollisions, digestManagedPaths, findConflicts, findMissingPayloadFiles, findProtectedPaths, } from "./diff.js";
+import { applyAdrRenames, findStrandedCitations, planAdrTransitions, } from "./adr-transitions.js";
+import { syncMethodManagedSettings } from "./settings-merge.js";
+import { syncMethodManagedCopilotHooks } from "./copilot-hooks-merge.js";
+import { syncBriefingFiles } from "./briefing-merge.js";
+import { DEFAULT_AGENT_HARNESS } from "../agent-harness.js";
+import { BLOCK_BEGIN, BLOCK_END } from "../init/ci-workflow.js";
+import { blockSha256, CI_BINDINGS, DEFAULT_CI_BINDING, isCiBinding, syncCiBinding, } from "../ci-binding/index.js";
+import { BRIEFING_TEMPLATE_ROOT, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, harnessWrapperOutputPath, } from "../briefing/index.js";
+const SECTION_RULE = "═".repeat(59);
+/**
+ * Report the pristine/edited/unclassifiable split for a conflict set.
+ *
+ * The message this replaces said only "Found N conflicting managed file(s)",
+ * which reads as "you have local edits at risk" — and twice the truth was the
+ * opposite. Each branch below states what is actually known, and the
+ * undecidable case says so plainly rather than defaulting to alarm.
+ */
+function reportClassification(stdout, total, c, priorVersion) {
+    const from = priorVersion ? ` (match last-applied ${priorVersion})` : "";
+    if (c.edited.length === 0 && c.unclassifiable.length === 0) {
+        stdout(pass(`${total} differ, ${c.pristine.length} pristine${from} — safe to apply, ` +
+            `--allow-overwrite not required`));
+        return;
+    }
+    if (c.unclassifiable.length === total) {
+        // The accepted non-retroactive case. Silence here would recreate exactly the
+        // "you have local edits at risk" misread this work exists to remove.
+        stdout(info(`${total} differ, cannot classify: no per-path digests recorded` +
+            (priorVersion ? ` for ${priorVersion}` : "") +
+            ` — re-run after one sync to enable pristine detection`));
+        return;
+    }
+    stdout(info(`${total} differ: ${c.pristine.length} pristine${from}, ` +
+        `${c.edited.length} locally edited, ${c.unclassifiable.length} not classifiable`));
+}
+export async function runSync(opts, stdout = (line) => process.stdout.write(line)) {
+    if (!(await exists(opts.bundle))) {
+        stdout(fail(`Bundle not found: ${opts.bundle}`));
+        return { exitCode: 1 };
+    }
+    if (!(await exists(opts.targetRepo))) {
+        stdout(fail(`Target repo not found: ${opts.targetRepo}`));
+        return { exitCode: 1 };
+    }
+    stdout(section("Sync Method Baseline"));
+    const bundle = await loadBundle(opts.bundle);
+    try {
+        // Enforce minimum sdd-cli version declared by the bundle manifest.
+        // Bundles built before v0.13.2 omit the field; for those, no check
+        // applies. Forward-baseline bundles starting at v0.6.0 (sdd-method
+        // v0.9.0, schema relocation) declare a minimum so adopters whose
+        // installed sdd-cli predates the relocation cannot apply a bundle
+        // that depends on schema-from-sdd-cli rather than schema-from-bundle.
+        const minVersionError = checkMinimumSddCliVersion(bundle.manifest);
+        if (minVersionError !== null) {
+            stdout(fail(minVersionError));
+            return { exitCode: 1 };
+        }
+        if (bundle.manifest.minimumSddCliVersion) {
+            stdout(info(`sdd-cli ${getSddCliVersion()} satisfies bundle minimum ${bundle.manifest.minimumSddCliVersion}`));
+        }
+        const missing = await findMissingPayloadFiles(bundle.managedPaths, bundle.payloadDir);
+        if (missing.length > 0) {
+            stdout(fail(`Missing payload file listed in MANAGED_PATHS.txt: ${missing[0]}`));
+            return { exitCode: 1 };
+        }
+        // ADR 0176 §4.3: split consumption modes. Scaffold-source paths and
+        // the registry file extract to the bundle cache only; everything
+        // else materialises into the repo tree as before.
+        const { materialise: materialisePaths, cacheOnly: cacheOnlyPaths } = splitConsumptionModes(bundle.managedPaths, bundle.manifest.scaffoldSourcePaths);
+        const protectedIncoming = findProtectedPaths(bundle.managedPaths);
+        if (protectedIncoming.length > 0) {
+            stdout(fail(`Incoming bundle attempts to manage protected product-owned path: ${protectedIncoming[0]}`));
+            stdout(fail(`Method baseline bundles must not manage files under: ${PROTECTED_PREFIXES.join(" ")}`));
+            return { exitCode: 1 };
+        }
+        const conflicts = await findConflicts(materialisePaths, bundle.payloadDir, opts.targetRepo);
+        // Read the lock BEFORE gating on conflicts: lock_version 3's per-path
+        // digests are what turn "N files differ" into "N files differ and every one
+        // is untouched", which decides whether --allow-overwrite is warranted at all.
+        const prevLock = await readLockFile(opts.targetRepo);
+        const prevEntry = findBundle(prevLock, bundle.manifest.bundleName);
+        const lockBinding = prevLock?.ciBinding;
+        if (lockBinding !== undefined && !isCiBinding(lockBinding)) {
+            stdout(fail(`method-baseline.lock names ci_binding '${lockBinding}', which is not one of ${CI_BINDINGS.join(", ")}. Re-run with --ci-binding <binding> to choose one.`));
+            return { exitCode: 1 };
+        }
+        const ciBinding = opts.ciBinding ?? lockBinding ?? DEFAULT_CI_BINDING;
+        const classification = await classifyConflicts(conflicts, opts.targetRepo, prevEntry?.pathDigests);
+        if (conflicts.length > 0) {
+            reportClassification(stdout, conflicts.length, classification, prevEntry?.bundleVersion);
+        }
+        // A conflict set that is provably pristine is not a risk, so the flag is not
+        // required for it. Genuine edits, and anything undecidable, still are.
+        const safeWithoutFlag = allPristine(classification);
+        if (conflicts.length > 0 && !opts.allowOverwrite && !safeWithoutFlag) {
+            const blocking = [...classification.edited, ...classification.unclassifiable];
+            stdout(fail(`Re-run with --allow-overwrite to apply. ${blocking.length} of ${conflicts.length} ` +
+                `conflicting file(s) are not provably untouched:`));
+            for (const p of blocking) {
+                const why = classification.edited.includes(p) ? "locally edited" : "not classifiable";
+                stdout(`  - ${p} (${why})\n`);
+            }
+            return { exitCode: 1 };
+        }
+        // Validate protected prefixes across ALL previously-locked paths.
+        if (prevLock) {
+            for (const b of prevLock.bundles) {
+                const protectedPrev = findProtectedPaths(b.managedPaths);
+                if (protectedPrev.length > 0) {
+                    stdout(fail(`Existing lock file contains protected product-owned path: ${protectedPrev[0]} (bundle: ${b.name})`));
+                    stdout(fail("Resolve this manually before refreshing the method baseline."));
+                    return { exitCode: 1 };
+                }
+            }
+        }
+        // Additive bundles require a forward base already in the lock.
+        // For adopter packs (ADR 0151) the requires_forward_base field
+        // declares which sdd-method bundle (and minimum version) is needed.
+        const incomingBundleName = bundle.manifest.bundleName;
+        const incomingIsForward = bundle.manifest.isForwardBase;
+        if (!incomingIsForward && !hasForwardBase(prevLock, incomingBundleName)) {
+            stdout(fail(`${incomingBundleName} is an additive extension. Sync a forward base first.`));
+            stdout(fail(`Forward bases: platform-baseline, app-baseline, integration-baseline, reverse-baseline.`));
+            return { exitCode: 1 };
+        }
+        // Bundle migration (--replace-bundle): validate the request before any
+        // gate that would misread the overlap as a defect.
+        const migrateFrom = opts.replaceBundle
+            ? findBundle(prevLock, opts.replaceBundle)
+            : null;
+        if (opts.replaceBundle) {
+            if (opts.replaceBundle === incomingBundleName) {
+                stdout(fail(`--replace-bundle ${opts.replaceBundle}: replacing a bundle with itself is a plain sync — drop the flag.`));
+                return { exitCode: 1 };
+            }
+            if (!migrateFrom) {
+                stdout(fail(`--replace-bundle ${opts.replaceBundle}: the lock has no bundle of that name. Nothing to migrate.`));
+                return { exitCode: 1 };
+            }
+            if (migrateFrom.isForwardBase !== incomingIsForward) {
+                stdout(fail(`--replace-bundle: '${opts.replaceBundle}' (forward base: ${migrateFrom.isForwardBase}) and '${incomingBundleName}' (forward base: ${incomingIsForward}) are different layer kinds — a migration swaps like for like.`));
+                return { exitCode: 1 };
+            }
+        }
+        // Adopter pack requires_forward_base check: the named forward base
+        // must be in the lock at a compatible version. Per ADR 0151 §4.2.
+        if (!incomingIsForward && bundle.manifest.requiresForwardBase) {
+            const err = checkRequiresForwardBase(prevLock, bundle.manifest.requiresForwardBase, incomingBundleName);
+            if (err !== null) {
+                stdout(fail(err));
+                return { exitCode: 1 };
+            }
+        }
+        // Adopter pack requires_pack check: vertical extensions name a base
+        // pack they depend on. Per ADR 0151 §4.3.
+        if (!incomingIsForward && bundle.manifest.requiresPack) {
+            const err = checkRequiresPack(prevLock, bundle.manifest.requiresPack, incomingBundleName);
+            if (err !== null) {
+                stdout(fail(err));
+                return { exitCode: 1 };
+            }
+        }
+        // Cross-bundle ownership: a path managed by another bundle in the
+        // lock cannot also be claimed by this bundle. Under --replace-bundle the
+        // outgoing bundle's claims are released — migration is the overlap
+        // guard's sanctioned inverse, not its removal: a path owned by any THIRD
+        // bundle still refuses below.
+        const otherBundlePaths = pathToBundleMap(prevLock, incomingBundleName);
+        if (migrateFrom) {
+            for (const p of migrateFrom.managedPaths) {
+                if (otherBundlePaths.get(p) === migrateFrom.name)
+                    otherBundlePaths.delete(p);
+            }
+        }
+        for (const p of bundle.managedPaths) {
+            const owner = otherBundlePaths.get(p);
+            if (owner !== undefined) {
+                stdout(fail(`Path '${p}' is already managed by bundle '${owner}'; cannot also be claimed by '${incomingBundleName}'.`));
+                stdout(fail("Method baselines must not overlap. Fix upstream and rebuild."));
+                return { exitCode: 1 };
+            }
+        }
+        // ADR transitions (bundle-declared rename / withdrawal / reassignment).
+        // Planned BEFORE removals because a withdrawal's whole contract is that the
+        // file is preserved and reported rather than deleted — and removal-by-omission
+        // would otherwise sweep it, since a withdrawn ADR is no longer in the bundle.
+        const adrTransitions = await planAdrTransitions(bundle.rootDir, opts.targetRepo, prevEntry?.bundleVersion);
+        // Removals are scoped to THIS bundle's previously-managed paths — plus,
+        // under --replace-bundle, the outgoing bundle's paths, so its orphans
+        // (old-only, unclaimed by the incoming bundle) are removed in the same
+        // pass rather than left as untracked strays.
+        const prevBundleEntry = findBundle(prevLock, incomingBundleName);
+        const prevPaths = [
+            ...(prevBundleEntry?.managedPaths ?? []),
+            ...(migrateFrom?.managedPaths ?? []),
+        ];
+        const withdrawnKeep = new Set(adrTransitions.protectedFromRemoval);
+        const removals = computeRemovals(prevPaths, materialisePaths, {
+            noDelete: !opts.delete,
+        }).filter((p) => !withdrawnKeep.has(p));
+        stdout(info(`Bundle: ${incomingBundleName} (version: ${bundle.manifest.bundleVersion})`));
+        stdout(info(`Incoming managed files: ${bundle.managedPaths.length}`));
+        if (cacheOnlyPaths.length > 0) {
+            stdout(info(`Cache-only (scaffold-source/registry) files: ${cacheOnlyPaths.length} — extracted to .sdd/bundle-cache, not materialised`));
+        }
+        // SHADOW-COLLISION FLAG (ledger §3ap, the durable move-rule's machinery).
+        // When the distributed surface MOVES a file, previously-delivered copies at
+        // the old location are stranded as unmanaged files: they keep resolving, so
+        // nothing breaks loudly, and they silently go stale as their managed twins
+        // evolve. One estate carried six such shadows, all stale — one of them a
+        // rubric its own scoring tooling was still reading, so a repaired anchor
+        // shipped and was simultaneously unreachable.
+        //
+        // The quiet failure is the one that needs machinery; a rename that breaks
+        // its citations announces itself. This flags the collision at the moment it
+        // is created — an incoming managed path whose BASENAME already exists at a
+        // shallower, non-managed path — rather than leaving it to a per-estate
+        // census to find later.
+        const shadows = detectShadowCollisions(materialisePaths, (rel) => existsSync(join(opts.targetRepo, rel)), (rel) => {
+            try {
+                return readFileSync(join(opts.targetRepo, rel), "utf-8");
+            }
+            catch {
+                return null;
+            }
+        });
+        if (shadows.length > 0) {
+            stdout(info(`Shadow collisions: ${shadows.length} — an incoming managed file shares its name with an ` +
+                `existing UNMANAGED file at a shallower path. These are not conflicts and nothing is ` +
+                `overwritten, but a stale twin that still resolves is read by tooling and by people ` +
+                `without either noticing (M-ADR 0200 move-rule):`));
+            for (const sh of shadows) {
+                stdout(info(`  ${sh.shadow}  (shadowed by managed ${sh.managed})`));
+            }
+        }
+        stdout(info(`Conflicts: ${conflicts.length}`));
+        // RELABEL (ledger §3y.2): the raw count mixes two different things and an
+        // adopter's dry-run reported 31 where the artefacts on disk numbered 5.
+        // Nothing was wrong with the mechanism — the LABEL claimed deletions for
+        // lock entries whose paths were never materialised (cache-only payload
+        // members). An alarming label on a harmless mechanism is a stop-generator,
+        // and this one generated a stop.
+        const removalsOnDisk = [];
+        for (const rel of removals) {
+            if (existsSync(join(opts.targetRepo, rel)))
+                removalsOnDisk.push(rel);
+        }
+        const lockOnly = removals.length - removalsOnDisk.length;
+        stdout(info(`Removals from previous sync of this bundle: ${removals.length}` +
+            (lockOnly > 0
+                ? ` — ${removalsOnDisk.length} file(s) on disk to delete, ${lockOnly} lock entr(ies) only ` +
+                    `(paths never materialised here, e.g. cache-only payload members; nothing is deleted for these)`
+                : ` (all present on disk)`)));
+        stdout(info(`ADR renames to apply: ${adrTransitions.renames.length}`));
+        stdout(info(`ADR transition warnings: ${adrTransitions.warnings.length}`));
+        if (adrTransitions.warnings.length > 0) {
+            stdout(info("ADR transition notices:"));
+            for (const w of adrTransitions.warnings)
+                stdout(`  ! ${w}\n`);
+        }
+        // A move strands its citations as well as its file (ruled 2026-09-29): report
+        // each citation in the adopter's own documents to a moved path. Never
+        // rewritten; printed in dry-run too, so the figure a reviewer approves is the
+        // figure the run states.
+        const stranded = await findStrandedCitations(opts.targetRepo, adrTransitions.movedPaths, new Set(materialisePaths), await trackedTextFiles(opts.targetRepo));
+        if (stranded.length > 0) {
+            stdout(warn(`Citations to moved paths: ${stranded.length} — the adopter's own documents still name ` +
+                `a path the method moved. Update each (not rewritten automatically):`));
+            for (const s of stranded)
+                stdout(`  ! ${s}\n`);
+        }
+        stdout(info(`Protected ownership prefixes: ${PROTECTED_PREFIXES.join(" ")}`));
+        // Migration three-way split — always printed, dry-run or not, so the
+        // figures a reviewer approves are the figures the real run states.
+        if (migrateFrom) {
+            const incomingSet = new Set(bundle.managedPaths);
+            const shared = migrateFrom.managedPaths.filter((p) => incomingSet.has(p));
+            const arriving = bundle.managedPaths.filter((p) => !migrateFrom.managedPaths.includes(p));
+            const orphaned = migrateFrom.managedPaths.filter((p) => !incomingSet.has(p));
+            stdout(info(`Migration ${migrateFrom.name} → ${incomingBundleName}:`));
+            stdout(info(`  shared (ownership transfers): ${shared.length}`));
+            stdout(info(`  arriving (new to this repo):  ${arriving.length}`));
+            stdout(info(`  orphaned (removed unless --no-delete): ${orphaned.length}`));
+            for (const p of orphaned)
+                stdout(`    - ${p}\n`);
+            if (!opts.dryRun && opts.yes !== true) {
+                stdout(fail(`--replace-bundle is destructive (drops the '${migrateFrom.name}' lock block). ` +
+                    `Review the split above (use --dry-run first), then re-run with --yes.`));
+                return { exitCode: 1 };
+            }
+        }
+        // PRE-FLIGHT: evaluate every merge-managed refusal BEFORE the first
+        // write. The same gates exist downstream, but they used to fire after
+        // the payload had been applied — a refused sync left the repo holding
+        // the new bundle's content under the OLD lock, and the next run's
+        // digest comparison then classified every method-written file as an
+        // adopter edit. A gate that fires after 46 writes is not a gate.
+        // Measured on a live estate: 46 files written, then exit 1, no warning
+        // that anything had been written. The checks here are read-only and
+        // mirror the real gates exactly; those stay in place as defence in
+        // depth. All of them no-op under --allow-overwrite, hence the guard.
+        // Under --replace-bundle the method-managed settings/workflow blocks were
+        // rendered for the OUTGOING bundle's profile; the incoming profile renders
+        // different blocks, so drift against them is EXPECTED, not adopter edits.
+        // The merges below re-render method-managed content only — adopter entries
+        // outside the markers are preserved either way — so migration overrides
+        // this gate without touching --allow-overwrite's file-conflict semantics.
+        // The dry run evaluates this too: it used to return before the pre-flight
+        // ran, so on a live estate the dry run PASSED on 70 repos whose apply the
+        // pre-flight then refused on all 70 — a plan reported as clean that could
+        // not be performed. One function, both paths.
+        const preflightFailures = async () => {
+            const failures = [];
+            if (incomingIsForward && !opts.allowOverwrite && !migrateFrom) {
+                const preflightProfile = profileFromBundleName(incomingBundleName);
+                if (preflightProfile) {
+                    if (opts.agentHarness === "github-copilot-cli") {
+                        const probe = await syncMethodManagedCopilotHooks({
+                            targetRepo: opts.targetRepo,
+                            allowOverwrite: false,
+                            checkOnly: true,
+                        });
+                        if (probe.refused) {
+                            failures.push(`.github/hooks/*.json has adopter-modified method entries (${probe.driftedRefused.join(", ")}). Re-run with --allow-overwrite to rewrite them.`);
+                        }
+                    }
+                    else {
+                        const probe = await syncMethodManagedSettings({
+                            targetRepo: opts.targetRepo,
+                            profile: preflightProfile,
+                            allowOverwrite: false,
+                            checkOnly: true,
+                            hadPreviousSync: prevLock !== null,
+                            ...(opts.agentHarness ? { agentHarness: opts.agentHarness } : {}),
+                        });
+                        if (probe.refused) {
+                            const conflicts = [];
+                            if (probe.drifted.length > 0)
+                                conflicts.push(`mcpServers: ${probe.drifted.join(", ")}`);
+                            if (probe.hooksDrifted.length > 0)
+                                conflicts.push(`hooks: ${probe.hooksDrifted.join(", ")}`);
+                            failures.push(`.claude/settings.json has adopter-modified method entries (${conflicts.join("; ")}). Re-run with --allow-overwrite to rewrite them.`);
+                        }
+                    }
+                    // The CI host wrapper and the Method Validation module (M-ADR 0219): the same check the
+                    // write path runs, read-only.
+                    const ciProbe = await syncCiBinding({
+                        targetRepo: opts.targetRepo,
+                        profile: preflightProfile,
+                        binding: ciBinding,
+                        prevLock,
+                        allowDrift: false,
+                        allowOverwrite: false,
+                        checkOnly: true,
+                    });
+                    failures.push(...ciProbe.failures);
+                    // Briefing wrapper — only refusable when this bundle ships briefing
+                    // templates; pre-ADR-0148 baselines skip the briefing pass entirely.
+                    const shipsBriefing = bundle.managedPaths.some((p) => p.startsWith(`${BRIEFING_TEMPLATE_ROOT}/`));
+                    if (shipsBriefing) {
+                        const wrapperRel = harnessWrapperOutputPath(opts.agentHarness ?? DEFAULT_AGENT_HARNESS);
+                        const preflightWrapper = await tryReadFile(join(opts.targetRepo, wrapperRel));
+                        if (preflightWrapper !== null &&
+                            preflightWrapper !== "" &&
+                            !(preflightWrapper.includes(WRAPPER_BLOCK_BEGIN) &&
+                                preflightWrapper.includes(WRAPPER_BLOCK_END))) {
+                            failures.push(`${wrapperRel} has adopter edits outside the method-managed markers. Re-run with --allow-overwrite to replace the file.`);
+                        }
+                    }
+                }
+            }
+            return failures;
+        };
+        if (opts.dryRun) {
+            const wouldRefuse = await preflightFailures();
+            if (wouldRefuse.length > 0) {
+                for (const f of wouldRefuse)
+                    stdout(fail(`the apply would REFUSE: ${f}`));
+                stdout(info("Dry run: the plan below cannot be performed as it stands — the apply's pre-flight refuses it (see above). Exit 1."));
+            }
+            stdout(info("Dry run enabled. No files modified."));
+            if (conflicts.length > 0) {
+                stdout(info("Conflicting files:"));
+                for (const p of conflicts)
+                    stdout(`  - ${p}\n`);
+            }
+            if (removals.length > 0) {
+                stdout(info("Files that would be removed:"));
+                for (const p of removals)
+                    stdout(`  - ${p}\n`);
+            }
+            return { exitCode: wouldRefuse.length > 0 ? 1 : 0 };
+        }
+        const failures = await preflightFailures();
+        if (failures.length > 0) {
+            for (const f of failures)
+                stdout(fail(f));
+            stdout(info(
+            // The figures above describe the PLAN, and they print before this
+            // line because they are computed before the gate runs. An estate
+            // sweep keyed on them read 39 correct plans as 39 successes while
+            // every repo was untouched, so the outcome restates them in their
+            // own vocabulary rather than leaving the reader to infer that a
+            // plan reported is a plan performed.
+            `Pre-flight refusal: NOTHING was written — no files copied, no removals, lock unchanged. The ${bundle.managedPaths.length} incoming managed file(s), ${conflicts.length} conflict(s) and ${removals.length} removal(s) reported above are the plan that was ABANDONED, not work performed. Resolve the above (or re-run with --allow-overwrite) and sync again.`));
+            return { exitCode: 1 };
+        }
+        // Before the copy: move renamed ADRs so the adopter's own edits travel with the
+        // file and git records a rename, instead of the copy phase creating the new path
+        // and removal deleting the old one.
+        await applyAdrRenames(adrTransitions, opts.targetRepo);
+        await copyManagedFiles(materialisePaths, bundle.payloadDir, opts.targetRepo);
+        // Each pruned directory is named, not counted: it is an action taken on the
+        // adopter's tree, and git cannot show it afterwards because empty
+        // directories are untracked. The sync output is the only place it can ever
+        // be seen.
+        const prunedDirs = await removeManagedFiles(removals, opts.targetRepo);
+        if (prunedDirs.length > 0) {
+            stdout(info(`Emptied directories removed: ${prunedDirs.length} (withdrawal left them empty)`));
+            for (const d of prunedDirs)
+                stdout(`  - ${d}/\n`);
+        }
+        // ADR 0176 §4.2: cache non-forward-base bundles (the resolution
+        // substrate for scaffold --archetype). Forward bases are not cached
+        // — they carry no archetype registries and are large.
+        if (!bundle.manifest.isForwardBase) {
+            await cacheBundle({
+                targetRepo: opts.targetRepo,
+                bundleName: bundle.manifest.bundleName,
+                bundleVersion: bundle.manifest.bundleVersion,
+                managedPaths: bundle.managedPaths,
+                payloadDir: bundle.payloadDir,
+            });
+            const ignored = await ensureCacheGitignored(opts.targetRepo);
+            stdout(info(`Bundle cached: .sdd/bundle-cache/${bundle.manifest.bundleName}@${bundle.manifest.bundleVersion}${ignored ? " (.gitignore updated)" : ""}`));
+        }
+        const bundleSha = await sha256File(opts.bundle);
+        // Per-path digests (lock_version 3), taken from the PAYLOAD rather than the
+        // repo after copying: the payload is definitionally what this sync applied,
+        // and hashing the repo afterwards would silently absorb any concurrent local
+        // write into the "as applied" record — making a later edit look pristine.
+        // Cache-only paths are excluded because they never land in the tree, so a
+        // digest for them could never be compared against anything.
+        const pathDigests = await digestManagedPaths(materialisePaths, bundle.payloadDir);
+        const newEntry = {
+            name: incomingBundleName,
+            bundleVersion: bundle.manifest.bundleVersion,
+            sourceCommit: bundle.manifest.sourceCommit,
+            bundleSha256: bundleSha,
+            // Re-applying the SAME bundle (same sha256) keeps the time it was first applied, so a repeat
+            // sync writes the same lock bytes: sync is a function of its inputs, not of the clock
+            // (M-ADR 0218 §4.2, determinism). Found by maintain-cli's acceptance run, where the second
+            // sync on one commit changed nothing but this timestamp. A different bundle gets a new time.
+            syncedAtUtc: prevBundleEntry !== null && prevBundleEntry !== undefined && prevBundleEntry.bundleSha256 === bundleSha
+                ? prevBundleEntry.syncedAtUtc
+                : nowUtcIso(),
+            isForwardBase: incomingIsForward,
+            managedPaths: [...bundle.managedPaths],
+            pathDigests,
+            // Adopter-pack provenance per ADR 0151 — fields only present for
+            // non-forward-base bundles produced by adopter pack builders.
+            ...(bundle.manifest.producedByAdopter && {
+                producedByAdopter: bundle.manifest.producedByAdopter,
+            }),
+            ...(bundle.manifest.scope && { scope: bundle.manifest.scope }),
+            ...(bundle.manifest.requiresForwardBase && {
+                requiresForwardBase: bundle.manifest.requiresForwardBase,
+            }),
+            ...(bundle.manifest.requiresPack && {
+                requiresPack: bundle.manifest.requiresPack,
+            }),
+        };
+        // Additive layers (e.g. reverse-extension-baseline) own only the
+        // reverse-method content. They do NOT set .sdd-repo-kind, refresh
+        // .claude/settings.json, or rewrite the CI workflow — the forward
+        // base owns those.
+        if (!incomingIsForward) {
+            await writeLockFile(opts.targetRepo, upsertBundle(migrateFrom ? removeBundle(prevLock, migrateFrom.name) : prevLock, newEntry));
+            stdout(pass(`Method baseline synced to: ${opts.targetRepo}`));
+            stdout(info(`Updated lock file: method-baseline.lock (lock_version: ${LOCK_VERSION})`));
+            stdout(info("Additive layer applied; .sdd-repo-kind unchanged."));
+            return { exitCode: 0 };
+        }
+        // Forward base path: settings, workflow, repo-kind all belong here.
+        const profile = profileFromBundleName(incomingBundleName);
+        if (!profile) {
+            // Should be unreachable: forward bases all map to a profile.
+            throw new Error(`Forward-base bundle "${incomingBundleName}" has no profile mapping`);
+        }
+        const repoKind = repoKindFromProfile(profile);
+        await writeRepoKind(opts.targetRepo, repoKind);
+        // Harness-aware merge of agent-harness wiring per ADR 0141 §4.6.
+        // claude-code keeps the .claude/settings.json path (MCP + Claude
+        // hooks). github-copilot-cli writes .github/hooks/*.json instead;
+        // its MCP wiring lands separately under ADR 0150 Phase 3.
+        if (opts.agentHarness === "github-copilot-cli") {
+            const copilotResult = await syncMethodManagedCopilotHooks({
+                targetRepo: opts.targetRepo,
+                allowOverwrite: opts.allowOverwrite || migrateFrom !== null,
+            });
+            if (copilotResult.refused) {
+                stdout(fail(`.github/hooks/*.json has adopter-modified method entries (${copilotResult.driftedRefused.join(", ")}). Re-run with --allow-overwrite to rewrite them.`));
+                return { exitCode: 1 };
+            }
+            const written = copilotResult.files.filter((f) => f.wrote);
+            if (written.length > 0) {
+                stdout(info(`Refreshed ${written.map((f) => f.relPath).join(", ")}.`));
+            }
+        }
+        else {
+            const settingsResult = await syncMethodManagedSettings({
+                targetRepo: opts.targetRepo,
+                profile,
+                allowOverwrite: opts.allowOverwrite || migrateFrom !== null,
+                // A lock is the only sound evidence the managed entries were seeded
+                // before, which is what makes a re-seed distinguishable from a first
+                // sync into an adopter's own settings file.
+                hadPreviousSync: prevLock !== null,
+                ...(opts.agentHarness ? { agentHarness: opts.agentHarness } : {}),
+            });
+            if (settingsResult.refused) {
+                const conflicts = [];
+                if (settingsResult.drifted.length > 0)
+                    conflicts.push(`mcpServers: ${settingsResult.drifted.join(", ")}`);
+                if (settingsResult.hooksDrifted.length > 0)
+                    conflicts.push(`hooks: ${settingsResult.hooksDrifted.join(", ")}`);
+                stdout(fail(`.claude/settings.json has adopter-modified method entries (${conflicts.join("; ")}). Re-run with --allow-overwrite to rewrite them.`));
+                return { exitCode: 1 };
+            }
+            // Drift-class line of its own, ahead of the refresh summary: these
+            // entries were seeded by an earlier sync and had been removed since.
+            // Restoring them is not the news — that they went missing is, and the
+            // same ids reappearing here every sync means something is removing them
+            // repeatedly.
+            if (settingsResult.reseeded.length > 0) {
+                stdout(info(`${settingsResult.path}: RE-SEEDED ${settingsResult.reseeded.length} method-managed entr${settingsResult.reseeded.length === 1 ? "y" : "ies"} (${settingsResult.reseeded.join(", ")}) — present after a previous sync, absent now. Restored; if this recurs, something in this repo is removing them.`));
+            }
+            if (settingsResult.wroteFile) {
+                const labels = [];
+                if (settingsResult.added.length > 0)
+                    labels.push(`mcp added: ${settingsResult.added.join(", ")}`);
+                if (settingsResult.updated.length > 0)
+                    labels.push(`mcp updated: ${settingsResult.updated.join(", ")}`);
+                if (settingsResult.hooksChangedEvents.length > 0)
+                    labels.push(`hooks: ${settingsResult.hooksChangedEvents.join(", ")}`);
+                stdout(info(`Refreshed ${settingsResult.path} (${labels.join("; ") || "no changes"}).`));
+            }
+        }
+        // The CI host wrapper and the Method Validation module it calls (M-ADR 0219). Under
+        // --replace-bundle the blocks were rendered for the outgoing profile, so drift is expected.
+        const ci = await syncCiBinding({
+            targetRepo: opts.targetRepo,
+            profile,
+            binding: ciBinding,
+            prevLock,
+            allowDrift: opts.allowOverwrite || migrateFrom !== null,
+            allowOverwrite: opts.allowOverwrite,
+            checkOnly: false,
+        });
+        if (ci.failures.length > 0) {
+            for (const f of ci.failures)
+                stdout(fail(f));
+            return { exitCode: 1 };
+        }
+        for (const line of ci.log)
+            stdout(info(line));
+        // Briefing layer per ADR 0148: agent-instructions.md (unconditional
+        // overwrite) + harness wrapper (marker-aware merge). Templates ship
+        // in the bundle's orchestration/templates/briefing/; gracefully skip
+        // when an older bundle without them is being synced.
+        const briefingResult = await syncBriefingFiles({
+            targetRepo: opts.targetRepo,
+            repoKind: repoKindFromProfile(profile),
+            baselineVersion: bundle.manifest.bundleVersion,
+            agentHarness: opts.agentHarness ?? DEFAULT_AGENT_HARNESS,
+            allowOverwrite: opts.allowOverwrite || migrateFrom !== null,
+        });
+        if (briefingResult.refused) {
+            stdout(fail(`${briefingResult.refused} has adopter edits outside the method-managed markers. Re-run with --allow-overwrite to replace the file.`));
+            return { exitCode: 1 };
+        }
+        for (const line of briefingResult.log)
+            stdout(info(line));
+        // Record the wrapper block and the module exactly as they now stand on disk, so the next sync
+        // can tell them untouched from edited (M-ADR 0218 §4.7), and the binding when it is not the default.
+        const nextLock = upsertBundle(migrateFrom ? removeBundle(prevLock, migrateFrom.name) : prevLock, newEntry);
+        const { ciBinding: _previousBinding, ciWorkflowBlockSha256: _previousSha, ...lockBase } = nextLock;
+        await writeLockFile(opts.targetRepo, {
+            ...lockBase,
+            ...(ciBinding !== DEFAULT_CI_BINDING ? { ciBinding } : {}),
+            ...(ci.wrapperSha !== null ? { ciWorkflowBlockSha256: ci.wrapperSha } : {}),
+            ciModuleSha256: ci.moduleSha,
+        });
+        stdout(pass(`Method baseline synced to: ${opts.targetRepo}`));
+        stdout(info(`Updated lock file: method-baseline.lock (lock_version: ${LOCK_VERSION})`));
+        stdout(info(`Set repo kind marker: ${REPO_KIND_FILE} = ${repoKind}`));
+        return { exitCode: 0 };
+    }
+    finally {
+        await bundle.cleanup();
+    }
+}
+/** sha256 of the GitHub workflow's method-managed block (begin marker through end marker), or null without one. */
+export function workflowBlockSha256(text) {
+    return blockSha256(text, { begin: BLOCK_BEGIN, end: BLOCK_END });
+}
+function section(title) {
+    return `\n${SECTION_RULE}\n  ${title}\n${SECTION_RULE}\n\n`;
+}
+function info(msg) {
+    return `[INFO] ${msg}\n`;
+}
+function warn(msg) {
+    return `[WARN] ${msg}\n`;
+}
+function pass(msg) {
+    return `[PASS] ${msg}\n`;
+}
+function fail(msg) {
+    return `[FAIL] ${msg}\n`;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * If the bundle manifest declares a minimum sdd-cli version, verify the
+ * installed version satisfies it. Returns null on success or no
+ * declared minimum; returns a formatted error message on failure.
+ *
+ * Comparison is structural semver (major.minor.patch) — installed >=
+ * minimum at each segment. Pre-release identifiers (e.g. "0.14.0-rc.1")
+ * are stripped before comparison; the minimum field always declares a
+ * stable release version.
+ */
+export function checkMinimumSddCliVersion(manifest, installedOverride) {
+    const required = manifest.minimumSddCliVersion;
+    if (!required || required.length === 0)
+        return null;
+    const installed = installedOverride ?? getSddCliVersion();
+    if (versionAtLeast(installed, required))
+        return null;
+    return [
+        `Bundle ${manifest.bundleName} ${manifest.bundleVersion} requires sdd-cli >= ${required}`,
+        `but installed sdd-cli is ${installed}.`,
+        `Remediation: npm install -g @sdd-method/sdd-cli@^${required}`,
+    ].join(" ");
+}
+/**
+ * Verify `requires_forward_base` declared by an adopter pack against
+ * the consumer's lock. Returns null on success or a formatted error.
+ */
+export function checkRequiresForwardBase(prevLock, required, incomingBundleName) {
+    const fwd = findForwardBase(prevLock, incomingBundleName);
+    if (fwd === null) {
+        return (`${incomingBundleName} requires forward base ${required.bundle} ` +
+            `>= ${required.minimumVersion}, but the consumer lock has no forward base.`);
+    }
+    if (fwd.name !== required.bundle) {
+        return (`${incomingBundleName} requires forward base ${required.bundle}, ` +
+            `but the consumer lock has ${fwd.name} as its forward base.`);
+    }
+    if (!versionAtLeast(fwd.bundleVersion, required.minimumVersion)) {
+        return (`${incomingBundleName} requires ${required.bundle} >= ${required.minimumVersion}, ` +
+            `but the consumer lock has ${fwd.name} ${fwd.bundleVersion}.`);
+    }
+    return null;
+}
+/**
+ * Verify `requires_pack` declared by a vertical extension against the
+ * consumer's lock. Returns null on success or a formatted error.
+ *
+ * @public exported for unit testing.
+ *
+ * Version semantics: caret-range default (`^vX.Y.Z` matches `X.x.y` ≥
+ * `X.Y.Z` for X >= 1; for `^v0.Y.Z` only the same minor — `0.Y.x`).
+ * Exact pin (`vX.Y.Z`) matches only that version. Tilde (`~vX.Y.Z`)
+ * matches `X.Y.x`. `>=vX.Y.Z` matches anything ≥ that version.
+ */
+export function checkRequiresPack(prevLock, required, incomingBundleName) {
+    const target = findBundle(prevLock, required.name);
+    if (target === null) {
+        return (`${incomingBundleName} requires pack ${required.name} ${required.version}, ` +
+            `but no such pack is in the consumer lock.`);
+    }
+    if (!rangeSatisfies(target.bundleVersion, required.version)) {
+        return (`${incomingBundleName} requires ${required.name} ${required.version}, ` +
+            `but the consumer lock has ${target.name} ${target.bundleVersion} (range not satisfied).`);
+    }
+    return null;
+}
+/**
+ * Semver range satisfaction. Supports caret (^), tilde (~), >= and
+ * exact-pin (no prefix). Versions may carry a leading 'v'.
+ *
+ * Pre-1.0 caret narrows to the same minor: ^v0.1.x matches only 0.1.y
+ * (per npm convention). ^v1.2.x matches 1.x.y >= 1.2.x.
+ */
+export function rangeSatisfies(version, range) {
+    const stripV = (s) => s.replace(/^v/, "");
+    const parse = (s) => parseSimpleSemver(stripV(s));
+    let prefix = "=";
+    let body = range;
+    if (range.startsWith("^")) {
+        prefix = "^";
+        body = range.slice(1);
+    }
+    else if (range.startsWith("~")) {
+        prefix = "~";
+        body = range.slice(1);
+    }
+    else if (range.startsWith(">=")) {
+        prefix = ">=";
+        body = range.slice(2);
+    }
+    const v = parse(version);
+    const r = parse(body);
+    if (v === null || r === null)
+        return false;
+    switch (prefix) {
+        case "=":
+            return v.major === r.major && v.minor === r.minor && v.patch === r.patch;
+        case ">=":
+            return versionAtLeast(stripV(version), stripV(body));
+        case "~":
+            // Same major.minor, patch >= r.patch
+            return v.major === r.major && v.minor === r.minor && v.patch >= r.patch;
+        case "^":
+            // Pre-1.0: same major.minor (narrow caret)
+            if (r.major === 0) {
+                return v.major === 0 && v.minor === r.minor && v.patch >= r.patch;
+            }
+            // Stable: same major, version >= range
+            return v.major === r.major && versionAtLeast(stripV(version), stripV(body));
+    }
+}
+function versionAtLeast(installed, minimum) {
+    const i = parseSimpleSemver(installed);
+    const m = parseSimpleSemver(minimum);
+    if (i === null || m === null)
+        return false;
+    if (i.major !== m.major)
+        return i.major > m.major;
+    if (i.minor !== m.minor)
+        return i.minor > m.minor;
+    return i.patch >= m.patch;
+}
+function parseSimpleSemver(s) {
+    // Strip optional `v` prefix and any pre-release / build suffix.
+    const cleaned = s.replace(/^v/, "").replace(/[-+].*$/, "");
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(cleaned);
+    if (!m)
+        return null;
+    return {
+        major: parseInt(m[1], 10),
+        minor: parseInt(m[2], 10),
+        patch: parseInt(m[3], 10),
+    };
+}
+async function tryReadFile(path) {
+    try {
+        await access(path);
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function sha256File(path) {
+    const buf = await readFile(path);
+    return createHash("sha256").update(buf).digest("hex");
+}
+function nowUtcIso() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * The adopter's git-tracked Markdown and YAML — the documents that can cite a
+ * moved path. Outside a git work tree there is no honest scope: nothing is
+ * scanned, rather than guessing at the whole directory.
+ */
+async function trackedTextFiles(targetRepo) {
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    try {
+        const { stdout } = await promisify(execFile)("git", ["-C", targetRepo, "ls-files", "-z", "--", "*.md", "*.yaml", "*.yml"], { maxBuffer: 64 * 1024 * 1024 });
+        return stdout.split("\0").filter((p) => p !== "");
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=index.js.map