@sdd-method/maintain-cli 0.1.0 → 0.3.0

package/dist/lib/sync/briefing-merge.js

@@ -5,7 +5,7 @@
  *
  *   - `agent-instructions.md` — fully method-managed; unconditional
  *     overwrite on every sync. No marker-aware merge.
- *   - Harness wrapper (`CLAUDE.md` / `AGENTS.md` / …) — partially
+ *   - The wrappers, `CLAUDE.md` and the `AGENTS.md` pointer (M-ADR 0220 §4.6) — partially
  *     method-managed. The `<!-- method-managed: begin/end -->` block
  *     is overwritten; adopter content around it survives via the
  *     existing `writeMarkedBlockFile` machinery (same pattern as
@@ -20,9 +20,9 @@
  * pre-dating ADR 0148 won't carry the templates; this module skips
  * gracefully with a log line in that case.
  */
-import { access, mkdir, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { AGENT_INSTRUCTIONS_REL_PATH, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, harnessWrapperOutputPath, renderAgentInstructions, renderHarnessWrapper, resolveBriefingVariables, splitWrapperTemplate, } from "../briefing/index.js";
+import { AGENT_INSTRUCTIONS_REL_PATH, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, briefingWrappers, renderAgentInstructions, renderWrapper, resolveBriefingVariables, splitWrapperTemplate, } from "../briefing/index.js";
 import { writeMarkedBlockFile } from "./yaml-block-merge.js";
 export async function syncBriefingFiles(opts) {
     const log = [];
@@ -31,14 +31,36 @@ export async function syncBriefingFiles(opts) {
         repoKindOverride: opts.repoKind,
         baselineVersionOverride: opts.baselineVersion,
     });
-    // 1. agent-instructions.md — unconditional overwrite.
+    // 1. agent-instructions.md — unconditional overwrite, once no wrapper will refuse.
     const aiRender = await renderAgentInstructions(opts.targetRepo, vars);
     if (aiRender === null) {
         log.push(`Skipped ${AGENT_INSTRUCTIONS_REL_PATH}: bundle does not ship a briefing template (pre-ADR-0148 baseline).`);
-        // If the agent-instructions template is missing the wrapper one almost
-        // certainly is too — skip the rest as well.
+        // If the agent-instructions template is missing the wrapper ones almost
+        // certainly are too — skip the rest as well.
         return { log, refused: null };
     }
+    // 2. The wrappers, rendered first so a refusal leaves nothing written. A baseline that does not
+    // ship a wrapper's template (the AGENTS.md pointer arrived with M-ADR 0220) skips that wrapper.
+    const wrappers = [];
+    for (const w of briefingWrappers(opts.agentHarness)) {
+        const render = await renderWrapper(opts.targetRepo, w.templateRel, vars);
+        if (render === null) {
+            log.push(`Skipped ${w.outputRel}: the baseline does not ship ${w.templateRel}.`);
+            continue;
+        }
+        if (render.unresolved.length > 0) {
+            log.push(`Warning: ${w.outputRel} has unresolved placeholders: ${render.unresolved.join(", ")}`);
+        }
+        wrappers.push({ rel: w.outputRel, content: render.content });
+    }
+    if (!opts.allowOverwrite) {
+        for (const w of wrappers) {
+            const existing = await readIfExists(join(opts.targetRepo, w.rel));
+            if (existing !== null && existing !== "" && !(existing.includes(WRAPPER_BLOCK_BEGIN) && existing.includes(WRAPPER_BLOCK_END))) {
+                return { log, refused: w.rel };
+            }
+        }
+    }
     if (aiRender.unresolved.length > 0) {
         log.push(`Warning: agent-instructions.md has unresolved placeholders: ${aiRender.unresolved.join(", ")}`);
     }
@@ -46,37 +68,31 @@ export async function syncBriefingFiles(opts) {
     await mkdir(dirname(aiPath), { recursive: true });
     await writeFile(aiPath, aiRender.content, "utf8");
     log.push(`Refreshed ${AGENT_INSTRUCTIONS_REL_PATH}.`);
-    // 2. Harness wrapper — marker-aware merge.
-    const wrapperRender = await renderHarnessWrapper(opts.targetRepo, opts.agentHarness, vars);
-    if (wrapperRender === null) {
-        log.push(`Skipped ${harnessWrapperOutputPath(opts.agentHarness)}: bundle does not ship a wrapper template for ${opts.agentHarness}.`);
-        return { log, refused: null };
+    // 3. Each wrapper — marker-aware merge. Mirror the ci-workflow sync pattern: when the target
+    // file does not yet exist, write the full rendered template (block + adopter section template).
+    // When it exists, write the method-managed block and scaffold-fill blank regions around it from
+    // the template — writeMarkedBlockFile preserves non-blank adopter content verbatim.
+    for (const w of wrappers) {
+        const wrapperPath = join(opts.targetRepo, w.rel);
+        const wrapperExists = await fileExists(wrapperPath);
+        const templateParts = splitWrapperTemplate(w.content);
+        const mergeResult = await writeMarkedBlockFile(wrapperPath, wrapperExists ? templateParts.block : w.content, { begin: WRAPPER_BLOCK_BEGIN, end: WRAPPER_BLOCK_END }, opts.allowOverwrite, wrapperExists ? { pre: templateParts.pre, post: templateParts.post } : undefined);
+        if (mergeResult.refused) {
+            return { log, refused: w.rel };
+        }
+        if (mergeResult.changed) {
+            log.push(`Refreshed ${w.rel}.`);
+        }
     }
-    if (wrapperRender.unresolved.length > 0) {
-        log.push(`Warning: ${harnessWrapperOutputPath(opts.agentHarness)} has unresolved placeholders: ${wrapperRender.unresolved.join(", ")}`);
-    }
-    const wrapperRel = harnessWrapperOutputPath(opts.agentHarness);
-    const wrapperPath = join(opts.targetRepo, wrapperRel);
-    // Mirror the ci-workflow sync pattern: when the target file does not
-    // yet exist, write the full rendered template (block + adopter
-    // section template). When it exists, write the method-managed block
-    // and scaffold-fill blank regions around it from the template —
-    // writeMarkedBlockFile preserves non-blank adopter content verbatim.
-    const wrapperExists = await fileExists(wrapperPath);
-    const templateParts = splitWrapperTemplate(wrapperRender.content);
-    const incoming = wrapperExists
-        ? templateParts.block
-        : wrapperRender.content;
-    const mergeResult = await writeMarkedBlockFile(wrapperPath, incoming, { begin: WRAPPER_BLOCK_BEGIN, end: WRAPPER_BLOCK_END }, opts.allowOverwrite, wrapperExists
-        ? { pre: templateParts.pre, post: templateParts.post }
-        : undefined);
-    if (mergeResult.refused) {
-        return { log, refused: wrapperRel };
+    return { log, refused: null };
+}
+async function readIfExists(path) {
+    try {
+        return await readFile(path, "utf8");
     }
-    if (mergeResult.changed) {
-        log.push(`Refreshed ${wrapperRel}.`);
+    catch {
+        return null;
     }
-    return { log, refused: null };
 }
 async function fileExists(path) {
     try {

package/dist/lib/sync/diff.js

@@ -139,7 +139,7 @@ export const GENERATED_NEVER_REMOVE = [
     "AGENTS.md",
     "agent-instructions.md",
 ];
-/** `.github/hooks/<event>.json` — rendered per-event by hooks-seed/copilot.ts. */
+/** `.github/hooks/` — written by the retired Copilot harness (M-ADR 0220 §4.6); an adopter keeps those files, unmanaged, so sync never removes them. */
 const GENERATED_PREFIXES = [".github/hooks/"];
 /** True when this path's existence is owned by a generator, not by a payload. */
 export function isGeneratedPath(p) {

package/dist/lib/sync/index.js

@@ -11,12 +11,12 @@ import { cacheBundle, ensureCacheGitignored, splitConsumptionModes, } from "./bu
 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 { CLI_SOURCES, NPM_PACKAGE_NAME } from "../hooks-seed/index.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, parseCiRunner, syncCiBinding, } from "../ci-binding/index.js";
-import { BRIEFING_TEMPLATE_ROOT, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, harnessWrapperOutputPath, } from "../briefing/index.js";
+import { BRIEFING_TEMPLATE_ROOT, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, briefingWrappers, } from "../briefing/index.js";
 const SECTION_RULE = "═".repeat(59);
 /**
  * Report the pristine/edited/unclassifiable split for a conflict set.
@@ -103,6 +103,24 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
             return { exitCode: 1 };
         }
         const ciRunner = opts.ciRunner ?? lockRunner;
+        const lockSource = prevLock?.cliSource;
+        if (lockSource !== undefined && !CLI_SOURCES.includes(lockSource)) {
+            stdout(fail(`method-baseline.lock names cli_source '${lockSource}', which is not one of ${CLI_SOURCES.join(", ")}. Re-run with --cli-source <source> to choose one.`));
+            return { exitCode: 1 };
+        }
+        const lockPackage = prevLock?.cliPackage;
+        if (lockPackage !== undefined && !NPM_PACKAGE_NAME.test(lockPackage)) {
+            stdout(fail(`method-baseline.lock names cli_package '${lockPackage}', which is not an npm package name. Re-run with --cli-package <name> or --cli-package default.`));
+            return { exitCode: 1 };
+        }
+        const source = opts.cliSource ?? lockSource ?? "registry";
+        if (source === "installed" && typeof opts.cliPackage === "string") {
+            stdout(fail("--cli-package names an npm package for the registry source; the installed source runs sdd-verify from PATH. Drop --cli-package or choose --cli-source registry."));
+            return { exitCode: 1 };
+        }
+        // The installed source has no package; switching to it drops a recorded name.
+        const cliPackage = source === "installed" ? undefined : opts.cliPackage === undefined ? lockPackage : (opts.cliPackage ?? undefined);
+        const cliSource = source === "installed" ? { source } : { source, ...(cliPackage ? { package: cliPackage } : {}) };
         const classification = await classifyConflicts(conflicts, opts.targetRepo, prevEntry?.pathDigests);
         if (conflicts.length > 0) {
             reportClassification(stdout, conflicts.length, classification, prevEntry?.bundleVersion);
@@ -332,32 +350,16 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
             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,
+                            cliSource,
                             ...(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.`);
+                            failures.push(`.claude/settings.json has adopter-modified method entries (hooks: ${probe.hooksDrifted.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
@@ -377,13 +379,18 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
                     // 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.`);
+                        // Every wrapper the bundle ships a template for: CLAUDE.md and, from M-ADR 0220, the
+                        // AGENTS.md pointer. An unmarked file is the adopter's and refuses.
+                        for (const w of briefingWrappers(opts.agentHarness ?? DEFAULT_AGENT_HARNESS)) {
+                            if (!bundle.managedPaths.includes(`${BRIEFING_TEMPLATE_ROOT}/${w.templateRel}`))
+                                continue;
+                            const preflightWrapper = await tryReadFile(join(opts.targetRepo, w.outputRel));
+                            if (preflightWrapper !== null &&
+                                preflightWrapper !== "" &&
+                                !(preflightWrapper.includes(WRAPPER_BLOCK_BEGIN) &&
+                                    preflightWrapper.includes(WRAPPER_BLOCK_END))) {
+                                failures.push(`${w.outputRel} has adopter edits outside the method-managed markers. Re-run with --allow-overwrite to replace the file.`);
+                            }
                         }
                     }
                 }
@@ -508,58 +515,22 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
         }
         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 {
+        // The harness wiring: .claude/settings.json, the one supported harness's hooks (M-ADR 0220 §4.6).
+        {
             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,
+                cliSource,
                 ...(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.`));
+                stdout(fail(`.claude/settings.json has adopter-modified method entries (hooks: ${settingsResult.hooksDrifted.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.retiredServers.length > 0)
+                    labels.push(`removed the method's retired MCP server entry: ${settingsResult.retiredServers.join(", ")} (M-ADR 0220)`);
                 if (settingsResult.hooksChangedEvents.length > 0)
                     labels.push(`hooks: ${settingsResult.hooksChangedEvents.join(", ")}`);
                 stdout(info(`Refreshed ${settingsResult.path} (${labels.join("; ") || "no changes"}).`));
@@ -602,15 +573,18 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
         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.
+        // can tell them untouched from edited (M-ADR 0218 §4.7), and the binding and the CLI source
+        // when they are not the defaults.
         const nextLock = upsertBundle(migrateFrom ? removeBundle(prevLock, migrateFrom.name) : prevLock, newEntry);
-        const { ciBinding: _previousBinding, ciRunner: _previousRunner, ciWorkflowBlockSha256: _previousSha, ...lockBase } = nextLock;
+        const { ciBinding: _previousBinding, ciRunner: _previousRunner, ciWorkflowBlockSha256: _previousSha, cliSource: _previousSource, cliPackage: _previousPackage, ...lockBase } = nextLock;
         await writeLockFile(opts.targetRepo, {
             ...lockBase,
             ...(ciBinding !== DEFAULT_CI_BINDING ? { ciBinding } : {}),
             ...(ciRunner !== undefined && ciRunner.length > 0 ? { ciRunner: ciRunner.join(",") } : {}),
             ...(ci.wrapperSha !== null ? { ciWorkflowBlockSha256: ci.wrapperSha } : {}),
             ciModuleSha256: ci.moduleSha,
+            ...(cliSource.source !== "registry" ? { cliSource: cliSource.source } : {}),
+            ...(cliPackage !== undefined ? { cliPackage } : {}),
         });
         stdout(pass(`Method baseline synced to: ${opts.targetRepo}`));
         stdout(info(`Updated lock file: method-baseline.lock (lock_version: ${LOCK_VERSION})`));

package/dist/lib/sync/settings-merge.js

@@ -1,145 +1,99 @@
 /**
- * `.claude/settings.json` merge pass during `sdd-cli sync`. Method-
- * managed `mcpServers` entries (see src/lib/mcp-seed/) get upserted;
- * any adopter-added entries or other top-level keys are preserved.
+ * `.claude/settings.json` merge pass during `sdd-cli sync`. The method's hooks (see
+ * src/lib/hooks-seed/) are upserted when the repo runs the claude-code harness; every adopter
+ * entry and every other top-level key is preserved.
  *
- * The file cannot ship in the method baseline bundle because it
- * carries per-adopter absolute paths. That's why this is a separate
- * sync step, outside the bundle-driven `copyManagedFiles` path.
+ * The method seeds no MCP server (M-ADR 0220 §4.5). Sync removes the `sdd-mcp` entry it seeded
+ * before, without --allow-overwrite, because an entry whose command is the method's own
+ * `sdd-cli mcp serve` is the method's output: the same rule by which sync retired its own
+ * SDD_REPO_PATH value. An adopter's other servers, and an `sdd-mcp` entry that runs anything
+ * else, are left alone.
  *
- * Conflict handling mirrors ADR 0114: if the adopter has manually
- * modified a method-owned entry, sync refuses unless
- * `--allow-overwrite` is passed.
+ * Conflict handling mirrors ADR 0114: if the adopter has modified a method-owned hook, sync
+ * refuses unless `--allow-overwrite` is passed.
  */
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { buildMethodManagedServers, detectManagedDrift, upsertMethodManagedServers, } from "../mcp-seed/index.js";
-import { buildMethodManagedHooks, detectHooksDrift, upsertMethodManagedHooks, } from "../hooks-seed/index.js";
+import { buildMethodManagedHooks, detectHooksDrift, normaliseOwnHookRenders, upsertMethodManagedHooks, } from "../hooks-seed/index.js";
 export const SETTINGS_REL_PATH = ".claude/settings.json";
+/** The server id the method used to seed. */
+export const RETIRED_SERVER_ID = "sdd-mcp";
+/**
+ * Whether an `mcpServers` entry is one the method seeded: `sdd-cli mcp serve` and no other field,
+ * with no env or only an SDD_REPO_PATH that resolves to the repo itself (the value older syncs
+ * wrote for a platform repo). An SDD_REPO_PATH pointing anywhere else was the adopter's own
+ * configuration, as is any other change, and the entry stays.
+ */
+export function isOwnSddMcpEntry(entry, targetRepo) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return false;
+    const e = entry;
+    if (Object.keys(e).some((k) => k !== "command" && k !== "args" && k !== "env"))
+        return false;
+    if (e["command"] !== "sdd-cli")
+        return false;
+    const args = e["args"];
+    if (!Array.isArray(args) || args.length !== 2 || args[0] !== "mcp" || args[1] !== "serve")
+        return false;
+    const env = e["env"];
+    if (env === undefined)
+        return true;
+    if (!env || typeof env !== "object" || Array.isArray(env))
+        return false;
+    const keys = Object.keys(env);
+    if (keys.length !== 1 || keys[0] !== "SDD_REPO_PATH")
+        return false;
+    const path = env["SDD_REPO_PATH"];
+    return typeof path === "string" && resolve(targetRepo, path) === resolve(targetRepo);
+}
+/** The settings with the method's own `sdd-mcp` entry removed, and which ids went. */
+export function retireOwnMcpServers(settings, targetRepo) {
+    const servers = settings["mcpServers"];
+    if (!servers || typeof servers !== "object" || Array.isArray(servers))
+        return { settings, retired: [] };
+    const current = servers;
+    if (!(RETIRED_SERVER_ID in current) || !isOwnSddMcpEntry(current[RETIRED_SERVER_ID], targetRepo)) {
+        return { settings, retired: [] };
+    }
+    const { [RETIRED_SERVER_ID]: _retired, ...rest } = current;
+    const { mcpServers: _servers, ...others } = settings;
+    return {
+        settings: Object.keys(rest).length > 0 ? { ...others, mcpServers: rest } : others,
+        retired: [RETIRED_SERVER_ID],
+    };
+}
 export async function syncMethodManagedSettings(opts) {
     const absPath = join(opts.targetRepo, SETTINGS_REL_PATH);
+    const fileExisted = await fileExists(absPath);
     const existing = await readSettings(absPath);
-    // No profile gets an SDD_REPO_PATH any more (ruled 2026-10-01). It was written for platform
-    // repos only because the resolver treated a marker-bearing repo as one candidate among its
-    // marker-bearing siblings (MULTIPLE_SDDS_FOUND in the reverse estate's layout). The resolver now
-    // lets a platform-product repo serve itself, so the env var, an absolute, machine-specific
-    // path in a COMMITTED file, is no longer needed. A value left by an older sync that points at
-    // the repo itself is this tool's own output and is removed (normaliseSddRepoPathForDrift); a
-    // value pointing anywhere else is the adopter's and is still drift. App/integration repos
-    // configure their sibling platform SDD as before.
-    const owned = buildMethodManagedServers({});
-    // Drift is detected against a PATH-NORMALISED view of the existing file,
-    // not the raw bytes. Reason, measured on a live estate: the F27 defect
-    // wrote the literal CLI argument (".") as SDD_REPO_PATH. Once the
-    // generator was fixed to emit the absolute form, a strict comparison
-    // classified the defect's own historical output as an ADOPTER
-    // modification and refused to correct it — while the only offered remedy,
-    // --allow-overwrite, is the flag that rewrites genuinely adopter-owned
-    // keys. A repair that requires the dangerous flag is not a repair. So: an
-    // existing SDD_REPO_PATH that RESOLVES (from the target repo) to the same
-    // absolute path as the generated value is the tool's own output in an
-    // older costume, and is treated as regenerable, never as drift. The raw
-    // `existing` still flows into the upsert below, so the merge rewrites the
-    // stale form to the canonical one — the sync self-heals instead of
-    // wedging. A path that resolves DIFFERENTLY is still drift.
-    const drifted = detectManagedDrift(normaliseSddRepoPathForDrift(existing, owned, opts.targetRepo), owned);
-    // Computed from the state as READ, before any upsert: which method-managed ids
-    // were absent from the file this run opened. Combined with `hadPreviousSync`
-    // that is a re-seed; without it, a first seeding. Deliberately not derived
-    // from the upsert's `added`, which cannot tell the two apart — that conflation
-    // IS the defect.
-    const absentOnRead = absentManagedIds(existing, owned);
-    const reseeded = opts.hadPreviousSync === true ? absentOnRead : [];
     const hooksActive = opts.agentHarness === "claude-code";
-    const ownedHooks = hooksActive ? buildMethodManagedHooks() : undefined;
+    const ownedHooks = hooksActive ? buildMethodManagedHooks(opts.cliSource) : undefined;
     const hooksDrifted = hooksActive && ownedHooks
-        ? detectHooksDrift(existing, ownedHooks)
+        ? detectHooksDrift(normaliseOwnHookRenders(existing, ownedHooks), ownedHooks)
         : [];
-    if ((drifted.length > 0 || hooksDrifted.length > 0) && !opts.allowOverwrite) {
-        return {
-            path: SETTINGS_REL_PATH,
-            drifted,
-            added: [],
-            // Reported even on the refusal path: the re-seed was OBSERVED when the
-            // file was read, and it stays true whether or not this run went on to
-            // write. Zeroing it here would make a refusal hide a second finding.
-            reseeded,
-            updated: [],
-            unchanged: [],
-            hooksChangedEvents: [],
-            hooksDrifted,
-            wroteFile: false,
-            refused: true,
-        };
+    const base = { path: SETTINGS_REL_PATH, hooksDrifted };
+    if (hooksDrifted.length > 0 && !opts.allowOverwrite) {
+        return { ...base, retiredServers: [], hooksChangedEvents: [], wroteFile: false, refused: true };
     }
+    const retirement = retireOwnMcpServers(existing, opts.targetRepo);
     if (opts.checkOnly) {
-        return {
-            path: SETTINGS_REL_PATH,
-            drifted,
-            added: [],
-            reseeded,
-            updated: [],
-            unchanged: [],
-            hooksChangedEvents: [],
-            hooksDrifted,
-            wroteFile: false,
-            refused: false,
-        };
+        return { ...base, retiredServers: retirement.retired, hooksChangedEvents: [], wroteFile: false, refused: false };
     }
-    const mcpResult = upsertMethodManagedServers(existing, owned);
-    let nextSettings = mcpResult.settings;
+    let nextSettings = retirement.settings;
     let hooksChangedEvents = [];
     if (hooksActive && ownedHooks) {
         const hooksResult = upsertMethodManagedHooks(nextSettings, ownedHooks);
         nextSettings = hooksResult.settings;
         hooksChangedEvents = [...hooksResult.changedEvents];
     }
-    const changed = mcpResult.changed || hooksChangedEvents.length > 0;
-    if (!changed) {
-        return {
-            path: SETTINGS_REL_PATH,
-            drifted,
-            added: mcpResult.added,
-            reseeded,
-            updated: mcpResult.updated,
-            unchanged: mcpResult.unchanged,
-            hooksChangedEvents: [],
-            hooksDrifted,
-            wroteFile: false,
-            refused: false,
-        };
+    const changed = retirement.retired.length > 0 || hooksChangedEvents.length > 0;
+    // Nothing to write: leave the file as it is, and never create one just to hold nothing.
+    if (!changed || (!fileExisted && Object.keys(nextSettings).length === 0)) {
+        return { ...base, retiredServers: [], hooksChangedEvents: [], wroteFile: false, refused: false };
     }
     await mkdir(dirname(absPath), { recursive: true });
     await writeFile(absPath, JSON.stringify(nextSettings, null, 2) + "\n", "utf8");
-    return {
-        path: SETTINGS_REL_PATH,
-        drifted,
-        added: mcpResult.added,
-        reseeded,
-        updated: mcpResult.updated,
-        unchanged: mcpResult.unchanged,
-        hooksChangedEvents,
-        hooksDrifted,
-        wroteFile: true,
-        refused: false,
-    };
-}
-/**
- * Method-managed ids absent from the settings file as read.
- *
- * A missing or malformed `mcpServers` map counts every managed id as absent —
- * `readSettings` already collapses an unparseable file to `{}`, and a file whose
- * managed block was destroyed rather than edited is exactly the re-seed case
- * this exists to name.
- */
-function absentManagedIds(existing, owned) {
-    const servers = existing["mcpServers"];
-    const present = servers && typeof servers === "object" && !Array.isArray(servers)
-        ? servers
-        : {};
-    return Object.keys(owned)
-        .filter((id) => !(id in present))
-        .sort();
+    return { ...base, retiredServers: retirement.retired, hooksChangedEvents, wroteFile: true, refused: false };
 }
 async function readSettings(absPath) {
     if (!(await fileExists(absPath)))
@@ -167,50 +121,4 @@ async function fileExists(path) {
         return false;
     }
 }
-/**
- * A view of `existing` for drift detection ONLY: where a method-managed
- * entry's `env.SDD_REPO_PATH` resolves (from the target repo) to the same
- * absolute path as the generated value, substitute the generated form.
- *
- * This makes "the tool's own older output" (the F27 relative-path defect,
- * or a lexically different spelling of the same location) compare as
- * pristine, so the merge proceeds and REWRITES it — while a path that
- * resolves somewhere else entirely remains drift and still refuses.
- * Never used for the write: the raw `existing` flows into the upsert, so
- * the correction actually lands on disk.
- */
-function normaliseSddRepoPathForDrift(existing, owned, targetRepo) {
-    const servers = existing["mcpServers"];
-    if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
-        return existing;
-    }
-    const current = servers;
-    const out = {};
-    let touched = false;
-    for (const [id, entry] of Object.entries(current)) {
-        const existingPath = entry?.env?.["SDD_REPO_PATH"];
-        const ownedPath = owned[id]?.env?.["SDD_REPO_PATH"];
-        if (typeof existingPath === "string" &&
-            ownedPath === undefined &&
-            resolve(targetRepo, existingPath) === resolve(targetRepo)) {
-            // The retired platform SDD_REPO_PATH, pointing at the repo itself: regenerable, so the
-            // drift view drops it and the write (which replaces the entry whole) removes it.
-            const { SDD_REPO_PATH: _dropped, ...rest } = entry.env ?? {};
-            const { env: _env, ...bare } = entry;
-            out[id] = Object.keys(rest).length > 0 ? { ...bare, env: rest } : bare;
-            touched = true;
-        }
-        else if (typeof existingPath === "string" &&
-            typeof ownedPath === "string" &&
-            existingPath !== ownedPath &&
-            resolve(targetRepo, existingPath) === resolve(ownedPath)) {
-            out[id] = { ...entry, env: { ...entry.env, SDD_REPO_PATH: ownedPath } };
-            touched = true;
-        }
-        else {
-            out[id] = entry;
-        }
-    }
-    return touched ? { ...existing, mcpServers: out } : existing;
-}
 //# sourceMappingURL=settings-merge.js.map

package/dist/lib/validate/plan.js

@@ -25,7 +25,7 @@ const TITLES = {
     // CI has no platform checkout, so this step runs the app-only checks; the met gate needs the platform beside it.
     "app-dependencies": "Validate app dependencies (app-only checks; no platform checkout in CI)",
 };
-export function methodValidationPlan(profile) {
+export function methodValidationPlan(profile, opts = {}) {
     const steps = validatorsForProfile(profile)
         .filter((v) => v.optional !== true)
         .map((v) => ({
@@ -38,12 +38,15 @@ export function methodValidationPlan(profile) {
     if (profile === "platform") {
         steps.push({ id: "cascade-completeness", title: "Validate cascade completeness", tool: "bash", args: ["orchestration/scripts/validate-cascade-completeness.sh", "all"], advisory: false }, { id: "architecture-alignment", title: "Validate architecture alignment", tool: "bash", args: ["orchestration/scripts/validate-architecture-alignment.sh"], advisory: false });
     }
+    const gating = opts.catalogueRebuild === true;
     steps.push({
         id: "catalogue-freshness",
-        title: "Check catalogues reproduce from the specs (advisory)",
+        title: gating
+            ? "Check catalogues reproduce from the specs (gating: the pipeline rebuilt them)"
+            : "Check catalogues reproduce from the specs (advisory)",
         tool: "sdd-maintain",
         args: ["catalogue", "build", "--check", "--sdd-path", "."],
-        advisory: true,
+        advisory: !gating,
     });
     return steps;
 }