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

package/README.md

@@ -4,4 +4,4 @@
 
 Verbs: everything in `@sdd-method/verify-cli`, plus `sync`, `generate-briefing`, `context pull`, `catalogue build`, `catalogue aggregate`, `catalogue graph`, `catalogue diff`, `pack build`, `render screen`.
 
-Each writes only derived or method-managed content, and two runs on the same commit write the same bytes. Authoring verbs — `init`, `scaffold`, `plan`, `mcp`, `conformance` and the rest — are not present in it, and are in `@sdd-method/sdd-cli`. Invoking one fails with exit 1.
+Each writes only derived or method-managed content, and two runs on the same commit write the same bytes. Authoring verbs — `init`, `scaffold`, `plan`, `conformance` and the rest — are not present in it, and are in `@sdd-method/sdd-cli`. Invoking one fails with exit 1.

package/dist/lib/agent-harness.js

@@ -1,25 +1,34 @@
 /**
  * Agent-harness identifiers — the value space of `--agent-harness` on
- * `sdd-cli init` and `sdd-cli sync` per ADR 0141 §4.6.
+ * `sdd-cli init`, `sdd-cli sync` and `context pull` per ADR 0141 §4.6.
  *
- * Claude Code is the reference implementation per ADR 0141 §4.4 and
- * the default. GitHub Copilot CLI is the second reference per
- * `docs/method/methods/hook-contracts.md`. Adopters using a different
- * harness implement the portable contracts themselves per ADR 0141 §4.5.
+ * Claude Code is the one supported harness (M-ADR 0220 §4.6) and the default. The GitHub Copilot
+ * CLI value is retired: passing it fails, naming that record. Every SDD and code repository also
+ * gets an AGENTS.md pointer to agent-instructions.md, with no flag; it is a pointer, not support
+ * for another harness. Adopters binding any other harness implement the portable contracts
+ * themselves (ADR 0141 §4.5).
  */
-export const AGENT_HARNESSES = ["claude-code", "github-copilot-cli"];
+export const AGENT_HARNESSES = ["claude-code"];
 export const DEFAULT_AGENT_HARNESS = "claude-code";
+/** Retired values, each with the record that retired it. */
+export const RETIRED_AGENT_HARNESSES = {
+    "github-copilot-cli": "M-ADR 0220 §4.6",
+};
 export function isAgentHarness(value) {
     return AGENT_HARNESSES.includes(value);
 }
 /**
  * Resolve an optional CLI input to a concrete harness, falling back to
- * the reference default when unset. Throws on an unsupported value so
- * the CLI can surface a clear error to the caller.
+ * the reference default when unset. Throws on an unsupported or retired
+ * value so the CLI can surface a clear error to the caller.
  */
 export function resolveAgentHarness(input) {
     if (input === undefined)
         return DEFAULT_AGENT_HARNESS;
+    const retired = RETIRED_AGENT_HARNESSES[input];
+    if (retired !== undefined) {
+        throw new Error(`--agent-harness "${input}" is retired (${retired}): Claude Code is the one supported harness, and every repository gets an AGENTS.md pointer to agent-instructions.md without a flag. Supported: ${AGENT_HARNESSES.join(", ")}.`);
+    }
     if (!isAgentHarness(input)) {
         throw new Error(`Unsupported --agent-harness "${input}". Supported: ${AGENT_HARNESSES.join(", ")}.`);
     }

package/dist/lib/briefing/index.js

@@ -8,6 +8,6 @@
  * content below survives sync via the existing `writeMarkedBlockFile`
  * machinery.
  */
-export { AGENT_INSTRUCTIONS_REL_PATH, BRIEFING_TEMPLATE_ROOT, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, extractWrapperBlock, findUnresolvedPlaceholders, harnessWrapperOutputPath, renderAgentInstructions, renderHarnessWrapper, splitWrapperTemplate, substitute, } from "./render.js";
+export { AGENT_INSTRUCTIONS_REL_PATH, BRIEFING_TEMPLATE_ROOT, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, extractWrapperBlock, findUnresolvedPlaceholders, AGENTS_POINTER, briefingWrappers, harnessWrapperOutputPath, renderAgentInstructions, renderHarnessWrapper, renderWrapper, splitWrapperTemplate, substitute, } from "./render.js";
 export { resolveBriefingVariables } from "./variables.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/briefing/render.js

@@ -21,15 +21,22 @@ const HARNESS_WRAPPER_TEMPLATE = {
         templateRel: "claude-code/CLAUDE.md.hbs",
         outputRel: "CLAUDE.md",
     },
-    "github-copilot-cli": {
-        templateRel: "github-copilot-cli/AGENTS.md.hbs",
-        outputRel: "AGENTS.md",
-    },
 };
-/** Output filename per harness — e.g. `CLAUDE.md` or `AGENTS.md`. */
+/** Output filename per harness — `CLAUDE.md`. */
 export function harnessWrapperOutputPath(harness) {
     return HARNESS_WRAPPER_TEMPLATE[harness].outputRel;
 }
+/**
+ * The AGENTS.md pointer (M-ADR 0220 §4.6): a few lines directing any agent tool that reads a root
+ * AGENTS.md to agent-instructions.md. Written for every SDD and code repository with no flag, and
+ * rendered and refreshed exactly as the CLAUDE.md wrapper is. A pointer, not support for another
+ * harness. Relative to the briefing template root; code repositories read it under code-repo/.
+ */
+export const AGENTS_POINTER = { templateRel: "AGENTS.md.hbs", outputRel: "AGENTS.md" };
+/** Every marker-merged wrapper a repository gets: the harness's own, then the AGENTS.md pointer. */
+export function briefingWrappers(harness) {
+    return [HARNESS_WRAPPER_TEMPLATE[harness], AGENTS_POINTER];
+}
 /**
  * Marker pair the wrapper templates use to delimit the method-managed
  * region. The wrapper sync path slices this region out of the freshly
@@ -71,9 +78,11 @@ export async function renderAgentInstructions(targetRepo, vars) {
     return renderFromPath(templatePath, vars);
 }
 export async function renderHarnessWrapper(targetRepo, harness, vars) {
-    const { templateRel } = HARNESS_WRAPPER_TEMPLATE[harness];
-    const templatePath = join(targetRepo, BRIEFING_TEMPLATE_ROOT, templateRel);
-    return renderFromPath(templatePath, vars);
+    return renderWrapper(targetRepo, HARNESS_WRAPPER_TEMPLATE[harness].templateRel, vars);
+}
+/** Render one wrapper template from the briefing root; null when the baseline does not ship it. */
+export async function renderWrapper(targetRepo, templateRel, vars) {
+    return renderFromPath(join(targetRepo, BRIEFING_TEMPLATE_ROOT, templateRel), vars);
 }
 /**
  * Split a fully-rendered wrapper template at the method-managed

package/dist/lib/catalogue/aggregation-manifest-loader.js

@@ -1,8 +1,8 @@
 // Aggregation-manifest loader per
 // docs/method/methods/aggregation-manifest-schema.yaml.
 //
-// v1 supports `pull.kind: filesystem` only; other kinds (git-ref,
-// release-asset, mcp-resource) are schema-reserved and reject with a
+// v1 supports `pull.kind: filesystem` only; the other kinds (git-ref,
+// release-asset) are schema-reserved and reject with a
 // clear "deferred" error so adopters get unambiguous feedback.
 import { readFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
@@ -115,8 +115,8 @@ export async function loadAggregationManifest(manifestPath, options) {
         const kind = s.pull.kind;
         if (kind !== "filesystem") {
             throw new Error(`aggregation manifest: sibling "${s.sdd_id}" uses pull.kind="${kind}"\n` +
-                `  v1 supports filesystem only. Other kinds (git-ref, release-asset,\n` +
-                `  mcp-resource) are schema-reserved and not yet implemented.\n` +
+                `  v1 supports filesystem only. The other kinds (git-ref, release-asset)\n` +
+                `  are schema-reserved and not yet implemented.\n` +
                 `  See: docs/method/methods/aggregation-manifest-schema.yaml#pull_kinds`);
         }
         const path = s.pull.path;

package/dist/lib/catalogue/freshness.js

@@ -39,6 +39,7 @@ export async function compareCatalogueDirs(producedDir, committedDir) {
     return stale;
 }
 export async function checkCataloguesFresh(sddPath, opts, out) {
+    const label = opts.label ?? "catalogue build --check";
     const tmp = await mkdtemp(join(tmpdir(), "sdd-catalogue-check-"));
     try {
         const built = await runCatalogueBuild({
@@ -48,16 +49,16 @@ export async function checkCataloguesFresh(sddPath, opts, out) {
             ...(opts.snapshotStore !== undefined ? { snapshotStore: opts.snapshotStore } : {}),
         }, () => { });
         if (built.exitCode !== 0) {
-            out(`[FAIL] catalogue build --check: the build itself failed (exit ${built.exitCode}); run catalogue build to see why.\n`);
+            out(`[FAIL] ${label}: the build itself failed (exit ${built.exitCode}); run catalogue build to see why.\n`);
             return { exitCode: built.exitCode, stale: [] };
         }
         const produced = (await readdir(tmp)).sort();
         const stale = await compareCatalogueDirs(tmp, join(sddPath, "catalogues"));
         if (stale.length === 0) {
-            out(`[PASS] catalogue build --check: ${produced.length} catalogue file(s) reproduce byte-identically from the committed specs.\n`);
+            out(`[PASS] ${label}: ${produced.length} catalogue file(s) reproduce byte-identically from the committed specs.\n`);
             return { exitCode: 0, stale };
         }
-        out(`[FAIL] catalogue build --check: ${stale.length} catalogue file(s) are stale against the committed specs — run sdd-cli catalogue build and commit the result:\n`);
+        out(`[FAIL] ${label}: ${stale.length} catalogue file(s) are stale against the committed specs — catalogue build (sdd-maintain or sdd-cli) rebuilds them:\n`);
         for (const s of stale)
             out(`  ${s}\n`);
         return { exitCode: 1, stale };

package/dist/lib/ci-binding/index.js

@@ -18,6 +18,16 @@ import { DAGGER_VERSION, MODULE_CALL, MODULE_DIR, moduleSha256, renderModuleFile
 export const CI_BINDINGS = ["github", "gitlab", "jenkins"];
 /** M-ADR 0219 §8.2 (ruled 2026-10-16): what every SDD has before it chooses. */
 export const DEFAULT_CI_BINDING = "github";
+/**
+ * Runner labels (sync --ci-runner): where the host runs the job. One label is a word of letters,
+ * digits, '.', '_' or '-', so a label can never inject YAML or Groovy into a wrapper.
+ */
+export const CI_RUNNER_DEFAULT = "default";
+const RUNNER_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function parseCiRunner(s) {
+    const labels = s.split(",").map((l) => l.trim());
+    return labels.length > 0 && labels.every((l) => RUNNER_LABEL.test(l)) ? labels : null;
+}
 export function isCiBinding(s) {
     return CI_BINDINGS.includes(s);
 }
@@ -42,13 +52,14 @@ function header(comment, profile) {
 // GitLab: a Docker-in-Docker service, the shape GitLab documents for Dagger. The runner must allow
 // privileged containers; that is the adopter's infrastructure (M-ADR 0219 §4.5). No `stage:`, so
 // the job lands in the default `test` stage whatever stages the adopter declares around it.
-function gitlabBlock(profile) {
+function gitlabBlock(profile, runner) {
     return [
         HASH.begin,
         ...header("#", profile),
         "",
         "method-validation:",
         "  image: docker:27.3.1",
+        ...(runner !== undefined && runner.length > 0 ? [`  tags: [${runner.join(", ")}]`] : []),
         "  services:",
         "    - docker:27.3.1-dind",
         "  variables:",
@@ -70,13 +81,13 @@ function gitlabBlock(profile) {
 // Jenkins: a declarative pipeline at its own path, so it never collides with an adopter's
 // Jenkinsfile; the job's Script Path points at it. The agent must reach a Docker daemon. Dagger is
 // installed outside the workspace, so the binary is not uploaded with --source.
-function jenkinsBlock(profile) {
+function jenkinsBlock(profile, runner) {
     return [
         SLASH.begin,
         ...header("//", profile),
         "",
         "pipeline {",
-        "  agent any",
+        runner !== undefined && runner.length > 0 ? `  agent { label '${runner.join(" && ")}' }` : "  agent any",
         "  stages {",
         "    stage('Method Validation') {",
         "      steps {",
@@ -100,13 +111,13 @@ export const HOST_WRAPPERS = {
         relPath: ".gitlab-ci.yml",
         markers: HASH,
         block: gitlabBlock,
-        file: (p) => gitlabBlock(p) + "\n\n# Adopter-specific jobs go below, outside the method-managed markers.\n",
+        file: (p, r) => gitlabBlock(p, r) + "\n\n# Adopter-specific jobs go below, outside the method-managed markers.\n",
     },
     jenkins: {
         relPath: ".jenkins/method-validation.Jenkinsfile",
         markers: SLASH,
         block: jenkinsBlock,
-        file: (p) => jenkinsBlock(p) + "\n",
+        file: (p, r) => jenkinsBlock(p, r) + "\n",
     },
 };
 /** sha256 of a host file's method-managed block (begin marker through end marker), or null without one. */
@@ -128,7 +139,7 @@ export async function syncCiBinding(o) {
     // 1. The host wrapper.
     const wrapperAbs = join(o.targetRepo, host.relPath);
     const existing = await tryRead(wrapperAbs);
-    const block = host.block(o.profile);
+    const block = host.block(o.profile, o.runner);
     const drifted = existing !== null && detectBlockDrift(existing, block, host.markers);
     const recorded = sameBinding ? o.prevLock?.ciWorkflowBlockSha256 : undefined;
     const pristine = existing !== null && recorded !== undefined && blockSha256(existing, host.markers) === recorded;
@@ -159,7 +170,7 @@ export async function syncCiBinding(o) {
     if (o.checkOnly || failures.length > 0) {
         return { failures, log, wrapperSha: null, moduleSha: moduleSha256(onDisk) };
     }
-    const written = await writeMarkedBlockFile(wrapperAbs, existing === null ? host.file(o.profile) : block, host.markers, o.allowOverwrite);
+    const written = await writeMarkedBlockFile(wrapperAbs, existing === null ? host.file(o.profile, o.runner) : block, host.markers, o.allowOverwrite);
     if (written.changed)
         log.push(`${existing === null ? "Wrote" : "Refreshed"} ${host.relPath}.`);
     if (!matches) {

package/dist/lib/context-pull/index.js

@@ -1,33 +1,33 @@
 /**
- * `sdd-cli context pull` — write the code-repo briefing and MCP_SETUP.md into a
- * code repository from its upstream SDD (M-ADR 0128 §1; M-ADR 0150 §4.3–4.4).
+ * `sdd-cli context pull` — write the code-repo briefing into a code repository from its upstream
+ * SDD (M-ADR 0220 §4.5, re-homing M-ADR 0150 §4.4 Phase D).
  *
- * The successor to the code-repo half of `generate-claude-md.sh`, scoped by
- * M-ADR 0150 Phase D: no dynamic content is baked in; that is the SDD's MCP
- * server's job. A sibling verb to `generate-briefing`, not an extension of it:
+ * The successor to the code-repo half of `generate-claude-md.sh`. No dynamic content is baked
+ * in: the briefing points at the SDD's files. A sibling verb to `generate-briefing`, not an extension of it:
  * `generate-briefing` needs the target to be an SDD (marker, lock, synced
  * templates), and a code repository is none of those. They share the
  * placeholder substitution and the wrapper's marker-block merge.
  *
  * What it writes, and nothing else (M-ADR 0218 §4.3 item 9, a MAINTAIN verb):
  *   agent-instructions.md   whole file, method-managed
- *   CLAUDE.md / AGENTS.md   the method-managed block only; adopter content survives
- *   MCP_SETUP.md            whole file, method-managed
- * Templates are read from the SDD, which carries them via its baseline bundle.
+ *   CLAUDE.md, AGENTS.md    the method-managed block only; adopter content survives (AGENTS.md is
+ *                           the pointer, M-ADR 0220 §4.6, when the SDD's baseline carries it)
+ * Templates are read from the SDD, which carries them via its baseline bundle. MCP_SETUP.md is no
+ * longer written (M-ADR 0220 §4.5); a copy this verb wrote earlier is removed when it still
+ * matches the method's last render, and left with a notice when it does not.
  */
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { AGENT_INSTRUCTIONS_REL_PATH, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, findUnresolvedPlaceholders, harnessWrapperOutputPath, resolveBriefingVariables, splitWrapperTemplate, } from "../briefing/index.js";
+import { AGENT_INSTRUCTIONS_REL_PATH, AGENTS_POINTER, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, findUnresolvedPlaceholders, harnessWrapperOutputPath, resolveBriefingVariables, splitWrapperTemplate, } from "../briefing/index.js";
 import { readLockFile } from "../lock-file.js";
 import { readRepoKind } from "../repo-kind.js";
 import { writeMarkedBlockFile } from "../sync/yaml-block-merge.js";
 import { defaultSearchRoots, resolveCodeRepoName, resolveSdd } from "./resolve.js";
+import { RETIRED_MCP_SETUP_TEMPLATE } from "./retired-mcp-setup.js";
 export const CODE_REPO_BRIEFING_ROOT = "orchestration/templates/briefing/code-repo";
-export const MCP_SETUP_TEMPLATE = "orchestration/templates/mcp/code-repo/MCP_SETUP.md.hbs";
 export const MCP_SETUP_REL_PATH = "MCP_SETUP.md";
 const WRAPPER_TEMPLATE = {
     "claude-code": "claude-code/CLAUDE.md.hbs",
-    "github-copilot-cli": "github-copilot-cli/AGENTS.md.hbs",
 };
 export async function runContextPull(opts, out = (line) => process.stdout.write(line)) {
     const codeRepo = resolve(opts.codeRepo);
@@ -73,21 +73,23 @@ export async function runContextPull(opts, out = (line) => process.stdout.write(
         repo_kind: sdd.repo_kind,
         baseline_version: sdd.baseline_version,
         pull_date: opts.pullDate ?? new Date().toISOString().slice(0, 10),
-        // MCP_SETUP.md's own names, kept so the template the bash generator rendered still renders.
-        upstream_sdd_name: basename(sddRoot),
-        sdd_method_baseline_version: sdd.baseline_version,
     };
     const aiTemplate = join(sddRoot, CODE_REPO_BRIEFING_ROOT, "agent-instructions.md.hbs");
     const wrapperTemplate = join(sddRoot, CODE_REPO_BRIEFING_ROOT, WRAPPER_TEMPLATE[opts.agentHarness]);
-    const mcpTemplate = join(sddRoot, MCP_SETUP_TEMPLATE);
-    for (const t of [aiTemplate, wrapperTemplate, mcpTemplate]) {
+    for (const t of [aiTemplate, wrapperTemplate]) {
         if (!(await exists(t))) {
             out(fail(`${sddRoot} does not carry ${t.slice(sddRoot.length + 1)}: its method baseline predates context pull. Sync the SDD to a baseline that ships the code-repo templates.`));
             return { exitCode: 1 };
         }
     }
+    // The AGENTS.md pointer (M-ADR 0220 §4.6) arrived later than the other code-repo templates: an SDD
+    // whose baseline does not carry it yet gets no pointer, and everything else proceeds.
+    const pointerTemplate = join(sddRoot, CODE_REPO_BRIEFING_ROOT, AGENTS_POINTER.templateRel);
+    const wrapperSources = [[harnessWrapperOutputPath(opts.agentHarness), wrapperTemplate]];
+    if (await exists(pointerTemplate))
+        wrapperSources.push([AGENTS_POINTER.outputRel, pointerTemplate]);
     const rendered = {};
-    for (const [rel, path] of [[AGENT_INSTRUCTIONS_REL_PATH, aiTemplate], [harnessWrapperOutputPath(opts.agentHarness), wrapperTemplate], [MCP_SETUP_REL_PATH, mcpTemplate]]) {
+    for (const [rel, path] of [[AGENT_INSTRUCTIONS_REL_PATH, aiTemplate], ...wrapperSources]) {
         const content = substituteAll(await readFile(path, "utf8"), vars);
         const unresolved = findUnresolvedPlaceholders(content);
         if (unresolved.length > 0) {
@@ -96,30 +98,37 @@ export async function runContextPull(opts, out = (line) => process.stdout.write(
         }
         rendered[rel] = content;
     }
-    // The wrapper first: it is the only write that can be refused, and a refusal must leave nothing written.
-    const wrapperRel = harnessWrapperOutputPath(opts.agentHarness);
-    const wrapperPath = join(codeRepo, wrapperRel);
-    const existing = (await exists(wrapperPath)) ? await readFile(wrapperPath, "utf8") : null;
-    const parts = splitWrapperTemplate(rendered[wrapperRel]);
-    const hasMarkers = existing !== null && existing.includes(WRAPPER_BLOCK_BEGIN) && existing.includes(WRAPPER_BLOCK_END);
-    let wrapperChanged;
-    if (existing !== null && !hasMarkers) {
-        // No markers: a pre-briefing-layer file (the bash generator wrote these whole) or adopter-authored.
-        if (!opts.allowOverwrite) {
-            out(fail(`${wrapperRel} exists without method-managed markers, so it is treated as adopter-authored. Nothing was written. Re-run with --allow-overwrite to replace it with the rendered wrapper (move anything worth keeping below its markers afterwards).`));
+    // The wrappers first: they are the only writes that can be refused, and a refusal must leave
+    // nothing written, so every wrapper is checked before any is written.
+    const existingOf = {};
+    for (const [rel] of wrapperSources) {
+        const path = join(codeRepo, rel);
+        const existing = (await exists(path)) ? await readFile(path, "utf8") : null;
+        existingOf[rel] = existing;
+        const hasMarkers = existing !== null && existing.includes(WRAPPER_BLOCK_BEGIN) && existing.includes(WRAPPER_BLOCK_END);
+        if (existing !== null && !hasMarkers && !opts.allowOverwrite) {
+            // No markers: a pre-briefing-layer file (the bash generator wrote these whole) or adopter-authored.
+            out(fail(`${rel} exists without method-managed markers, so it is treated as adopter-authored. Nothing was written. Re-run with --allow-overwrite to replace it with the rendered wrapper (move anything worth keeping below its markers afterwards).`));
             return { exitCode: 1 };
         }
-        await writeFile(wrapperPath, rendered[wrapperRel], "utf8");
-        wrapperChanged = existing !== rendered[wrapperRel];
-    }
-    else {
-        const merge = await writeMarkedBlockFile(wrapperPath, existing === null ? rendered[wrapperRel] : parts.block, { begin: WRAPPER_BLOCK_BEGIN, end: WRAPPER_BLOCK_END }, opts.allowOverwrite, existing === null ? undefined : { pre: parts.pre, post: parts.post });
-        wrapperChanged = merge.changed;
     }
     const changed = [];
-    if (wrapperChanged)
-        changed.push(wrapperRel);
-    for (const rel of [AGENT_INSTRUCTIONS_REL_PATH, MCP_SETUP_REL_PATH]) {
+    for (const [rel] of wrapperSources) {
+        const path = join(codeRepo, rel);
+        const existing = existingOf[rel] ?? null;
+        const hasMarkers = existing !== null && existing.includes(WRAPPER_BLOCK_BEGIN) && existing.includes(WRAPPER_BLOCK_END);
+        if (existing !== null && !hasMarkers) {
+            await writeFile(path, rendered[rel], "utf8");
+            if (existing !== rendered[rel])
+                changed.push(rel);
+            continue;
+        }
+        const parts = splitWrapperTemplate(rendered[rel]);
+        const merge = await writeMarkedBlockFile(path, existing === null ? rendered[rel] : parts.block, { begin: WRAPPER_BLOCK_BEGIN, end: WRAPPER_BLOCK_END }, opts.allowOverwrite, existing === null ? undefined : { pre: parts.pre, post: parts.post });
+        if (merge.changed)
+            changed.push(rel);
+    }
+    for (const rel of [AGENT_INSTRUCTIONS_REL_PATH]) {
         const path = join(codeRepo, rel);
         const before = (await exists(path)) ? await readFile(path, "utf8") : null;
         if (before !== rendered[rel]) {
@@ -128,10 +137,41 @@ export async function runContextPull(opts, out = (line) => process.stdout.write(
             changed.push(rel);
         }
     }
+    const mcpSetup = await retireMcpSetup(codeRepo);
     out(info(`Code repo "${repoName}" is specified by ${sdd.sdd_name} (${sdd.repo_kind}, ${sdd.baseline_version}) at ${sddRoot}.`));
-    out(info(changed.length > 0 ? `Wrote ${changed.join(", ")}.` : `Already current: ${AGENT_INSTRUCTIONS_REL_PATH}, ${wrapperRel}, ${MCP_SETUP_REL_PATH}.`));
+    out(info(changed.length > 0 ? `Wrote ${changed.join(", ")}.` : `Already current: ${[AGENT_INSTRUCTIONS_REL_PATH, ...wrapperSources.map(([rel]) => rel)].join(", ")}.`));
+    if (mcpSetup === "removed")
+        out(info(`Removed ${MCP_SETUP_REL_PATH}: the method no longer ships it (M-ADR 0220), and this copy was unedited.`));
+    if (mcpSetup === "kept")
+        out(info(`${MCP_SETUP_REL_PATH} is no longer written (M-ADR 0220). This copy differs from the method's last render, so it was left; delete it if nothing in it is yours.`));
     return { exitCode: 0 };
 }
+/**
+ * Remove an MCP_SETUP.md this verb wrote before M-ADR 0220, when it is byte-identical to the
+ * method's last template rendered with the values its own header records. Anything else is the
+ * adopter's now, and stays.
+ */
+export async function retireMcpSetup(codeRepo) {
+    const path = join(codeRepo, MCP_SETUP_REL_PATH);
+    if (!(await exists(path)))
+        return "absent";
+    const text = await readFile(path, "utf8");
+    const repo = /^\* \*\*Emitted by:\*\* `sdd-cli context pull`, for code repo `([^`]*)`$/m.exec(text);
+    const upstream = /^\* \*\*Upstream SDD:\*\* `([^`]*)` at `([^`]*)`$/m.exec(text);
+    const baseline = /^\* \*\*Baseline version:\*\* `([^`]*)`$/m.exec(text);
+    if (!repo || !upstream || !baseline)
+        return "kept";
+    const render = substituteAll(RETIRED_MCP_SETUP_TEMPLATE, {
+        repo_name: repo[1],
+        upstream_sdd_name: upstream[1],
+        sdd_root: upstream[2],
+        sdd_method_baseline_version: baseline[1],
+    });
+    if (render !== text)
+        return "kept";
+    await rm(path);
+    return "removed";
+}
 /** `{{name}}` substitution over an open variable set (the briefing renderer's is closed to four). */
 export function substituteAll(template, vars) {
     return template.replace(/\{\{\s*([a-z_][a-z0-9_]*)\s*\}\}/g, (full, key) => (key in vars ? vars[key] : full));

package/dist/lib/context-pull/retired-mcp-setup.js

@@ -0,0 +1,7 @@
+/**
+ * The last MCP_SETUP.md template the method shipped (sdd-method 52bbc36), kept so `context pull`
+ * can tell a copy it wrote from one an adopter edited after M-ADR 0220 §4.5 retired the file.
+ * The SDD's own baseline stops carrying the template, so the comparison cannot read it from there.
+ */
+export const RETIRED_MCP_SETUP_TEMPLATE = "# MCP_SETUP.md\n\n* **Source:** sdd-method-baseline\n* **Emitted by:** `sdd-cli context pull`, for code repo `{{repo_name}}`\n* **Upstream SDD:** `{{upstream_sdd_name}}` at `{{sdd_root}}`\n* **Baseline version:** `{{sdd_method_baseline_version}}`\n\nThis file is **method-shipped guidance for agents working in this code repo**. It tells the agent how to reach the upstream SDD's live context via MCP. Read it alongside `agent-instructions.md` at session start.\n\nPer M-ADR 0150 (MCP as the primary dynamic-context layer), the **primary dynamic-context surface** for this code repo is the upstream SDD's MCP server, not baked-in snapshot content. Prefer MCP queries over reading static files for anything that might have changed since the last `sdd-cli context pull`.\n\n## \u00a71 What MCP gives you here\n\nThis code repo (`{{repo_name}}`) consumes specifications from the upstream SDD `{{upstream_sdd_name}}`. The upstream SDD exposes a read-only MCP server (`sdd-mcp`) you can query for:\n\n* **Catalogue rows** \u2014 current capability inventory, service registry, contract list, feature tree, cross-SDD edges.\n* **Gate state** \u2014 lock-in recommendations, intent-quality scores, domain-architecture scores, contract-quality scores per capability.\n* **Plan progress** \u2014 active plans, phases shipped, deferred follow-ups.\n* **Spec lookups** \u2014 ADRs, capability specs, feature specs, traceability manifests.\n\nThe static briefing in this repo (`agent-instructions.md` and the harness wrapper) covers conventions and orientation that are stable across syncs. Anything that changes faster than syncs run \u2014 gate state, catalogue rows, lock-in status \u2014 belongs behind MCP.\n\n## \u00a72 Server identity\n\n* **Server name:** `sdd-mcp`\n* **Upstream SDD path:** `{{sdd_root}}`\n* **Transport:** stdio (per M-ADR 0128's three-MCP-server commitment)\n\n`{{sdd_root}}` is where the SDD was checked out when this file was written; adjust it if your checkout differs. The MCP server resolves the SDD root with this precedence (per sdd-cli):\n\n1. `SDD_REPO_PATH` environment variable.\n2. `--sdd-repo <path>` flag on `sdd-cli mcp serve`.\n3. A platform SDD serves itself: when the git root's own `.sdd-repo-kind` reads `platform-product`, that repository is the SDD, whatever its siblings carry (so a platform repo needs no `SDD_REPO_PATH`).\n4. Sibling-directory auto-discovery from the code repo.\n\n## \u00a73 Harness wiring\n\n### Claude Code (reference)\n\nAdd this fragment to `.claude/settings.json` in this code repo. If the SDD is checked out in a sibling directory, discovery finds it and the `--sdd-repo` argument can be dropped:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"sdd-mcp\": {\n      \"command\": \"sdd-cli\",\n      \"args\": [\"mcp\", \"serve\", \"--sdd-repo\", \"{{sdd_root}}\"]\n    }\n  }\n}\n```\n\nVerify the wiring: open this code repo in Claude Code; in a session, ask the agent \"list available MCP resources\". You should see `sdd://` URIs from `sdd-mcp`.\n\n### GitHub Copilot CLI\n\nCopilot CLI's MCP wiring uses `.github/copilot/mcp.json` (verify against the current Copilot CLI docs at the time of setup; this surface is evolving). Equivalent shape:\n\n```jsonc\n{\n  \"servers\": {\n    \"sdd-mcp\": {\n      \"command\": \"sdd-cli\",\n      \"args\": [\"mcp\", \"serve\", \"--sdd-repo\", \"{{sdd_root}}\"]\n    }\n  }\n}\n```\n\n### Other harnesses\n\nFor any other harness (OpenAI Codex CLI, OpenCode, a generic-stdio harness, or custom in-house): follow the adopter-responsibility flow per M-ADR 0141 \u00a74.5. Read the portable contract of each MCP resource (in the upstream SDD's `docs/method/methods/`) and instantiate against your harness's native MCP-client interface. Document the wiring in an adopter-side ADR or guide.\n\n## \u00a74 Resource surface \u2014 quick reference\n\nThe upstream `sdd-mcp` server exposes resources keyed by `sdd://` URIs. The most relevant for code-repo agents:\n\n| URI pattern | Returns | Typical use |\n|---|---|---|\n| `sdd://catalogue/{name}` | All rows from one catalogue (e.g. `services`, `capabilities`, `features`, `contracts`) | Discover what exists in the SDD |\n| `sdd://catalogue/metamodel` | The catalogue metamodel doc | Understand the entity / edge model |\n| `sdd://catalogue/schema` | Parsed schema (entities + columns + FK constraints) | Reason about data shape |\n| `sdd://gates/{gate}` | Current gate state per capability | Check whether your dependency has locked in |\n| `sdd://specs/{path}` | Spec content lookup | Read a specific feature / capability spec by ID |\n| `sdd://adrs/{id}` | ADR content + metadata | Cross-reference architectural decisions |\n\nNewly-added resource families ship via baseline sync; consult the upstream SDD's MCP setup docs for the current list.\n\nTools (callable via MCP `tools/call`): `find_producers`, `find_consumers`, `find_consumers_of_contract`, `find_dependencies`, `find_dependents`, `cascade_impact`, `query_edges_for_entity`, `find_orphan_rows`, `query_catalogue_coverage`, `find_products_by_category`, `find_related_specs`, `search_specs`, `list_adrs`, `query_gate_status`. Ask the server for `tools/list` for each tool's arguments.\n\n## \u00a75 Troubleshooting\n\n**`sdd-mcp` unreachable / \"Connection refused\"**\nThe MCP server is launched on-demand by the harness; if it isn't starting, check:\n1. `sdd-cli` is installed and on `$PATH` (`which sdd-cli` should resolve).\n2. The harness's MCP config exists and points at `sdd-cli mcp serve`.\n3. The `--sdd-repo` path (or the sibling the server discovers) is a real SDD root.\n\n**\"SDD root not found\" or \"manifest missing\"**\nThe SDD path doesn't resolve to a valid SDD. The path should contain `.sdd/sdd-manifest.yaml` (or the legacy `docs/method/foundations/` layout).\n\n**Version mismatch on resources**\nSome resource families require a minimum `sdd-cli` version. Check `npm list -g @sdd-method/sdd-cli`; upgrade via `npm install -g @sdd-method/sdd-cli@latest` if a resource returns \"unsupported by this server version\".\n\n**Permission denied**\nFor adopter-scoped resources (per M-ADR 0130), `platform-mcp` / `partner-mcp` enforce scope. If you're hitting permission errors, confirm you're querying the right MCP server for the resource (operator scope vs partner scope).\n\n## \u00a76 Fallback semantics \u2014 no silent stale-data\n\nIf `sdd-mcp` is unreachable for any reason, **the agent must report the error and continue with whatever static context exists in this code repo** \u2014 `CLAUDE.md` snapshot + the orientation in this file. **There is no silent fallback to stale baked-in dynamic state.** Per M-ADR 0128 \u00a71, falling back to stale data re-introduces exactly the problem MCP exists to fix.\n\nIf MCP-served dynamic context is unavailable, surface this back to the user explicitly. The user can choose to:\n\n* Proceed without dynamic context (accept the limitation).\n* Restart the MCP server / fix the connection.\n* Re-run `sdd-cli context pull` for a fresh static briefing, acknowledging it is still a point-in-time read.\n\n## Cross-references\n\n* Upstream SDD: `{{sdd_root}}`\n* M-ADR 0128 (MCP live-query infrastructure)\n* M-ADR 0150 (MCP as primary dynamic-context layer)\n* M-ADR 0130 (adopter MCP composition pattern \u2014 `platform-mcp` / `partner-mcp`)\n* M-ADR 0148 (the static-briefing layer this file complements)\n\n---\n\n<!-- This file is rewritten whole by sdd-cli context pull. Put repo-specific MCP guidance in the harness wrapper, below its method-managed markers. -->\n";
+//# sourceMappingURL=retired-mcp-setup.js.map

package/dist/lib/hooks-seed/entries.js

@@ -5,6 +5,7 @@
  * merge path can identify it on refresh. Adopter-added hooks under
  * the same event survive because they lack the sentinel.
  */
+import { EXACT_VERSION, getVerifyCliVersion } from "../package-version.js";
 import { METHOD_MANAGED_SENTINEL } from "./types.js";
 function withSentinel(command) {
     if (command.includes(METHOD_MANAGED_SENTINEL))
@@ -22,13 +23,41 @@ export function buildMethodGuardPreToolUse() {
         ],
     };
 }
+const SESSION_START_VALIDATE_ARGS = ' validate --target-repo "${CLAUDE_PROJECT_DIR:-$(pwd)}" --validator adr-structure 2>&1 | head -20';
+const VERIFY_CLI_NPX = /^npx --yes @sdd-method\/verify-cli@(\S+)$/;
+/**
+ * The session-start check runs the VERIFY persona's CLI (M-ADR 0218, 0220), not sdd-cli, which is
+ * the administrator's: validating is routine author work. It runs through npx at the exact
+ * verify-cli version this sdd-cli releases with, the version the managed CI workflow installs, so a
+ * local pass comes from the same verifier CI uses and nothing needs installing globally.
+ */
+export function sessionStartValidateCommand(verifyVersion = getVerifyCliVersion()) {
+    return withSentinel(`npx --yes @sdd-method/verify-cli@${verifyVersion}${SESSION_START_VALIDATE_ARGS}`);
+}
+/**
+ * Whether a session-start command is one this tool rendered, at any version: the sdd-cli form it
+ * wrote until the hook moved to verify-cli, or the npx form at any exact version. Sync replaces its
+ * own earlier render without counting it as drift; otherwise every release that moves the pinned
+ * version would refuse the settings sync until --allow-overwrite, the flag that also rewrites keys
+ * the adopter owns. Anything else under the sentinel (an edited command) is still drift.
+ */
+export function isOwnSessionStartRender(command) {
+    const body = command.replace(METHOD_MANAGED_SENTINEL, "").trimEnd();
+    if (!body.endsWith(SESSION_START_VALIDATE_ARGS))
+        return false;
+    const launcher = body.slice(0, body.length - SESSION_START_VALIDATE_ARGS.length);
+    if (launcher === "sdd-cli")
+        return true;
+    const npx = VERIFY_CLI_NPX.exec(launcher);
+    return npx !== null && EXACT_VERSION.test(npx[1]);
+}
 export function buildSessionStartValidate() {
     return {
         matcher: "startup",
         hooks: [
             {
                 type: "command",
-                command: withSentinel('sdd-cli validate --target-repo "${CLAUDE_PROJECT_DIR:-$(pwd)}" --validator adr-structure 2>&1 | head -20'),
+                command: sessionStartValidateCommand(),
             },
         ],
     };

package/dist/lib/hooks-seed/index.js

@@ -5,13 +5,10 @@
  * `.claude/settings.json`'s `hooks` key. Ownership is identified by
  * the `# sdd-method-managed:true` sentinel in each hook command.
  *
- * Integration: `src/lib/sync/settings-merge.ts` conditionally calls
- * `upsertMethodManagedHooks` after `upsertMethodManagedServers` when
- * the adopter opted into `--agent-harness claude-code` at init time.
+ * Integration: `src/lib/sync/settings-merge.ts` calls `upsertMethodManagedHooks`
+ * when the repo runs the claude-code harness (the default).
  */
 export { METHOD_MANAGED_SENTINEL, isMethodManagedMatcher } from "./types.js";
-export { buildMethodManagedHooks } from "./entries.js";
-export { detectHooksDrift, upsertMethodManagedHooks, } from "./merge.js";
-export { buildMethodManagedCopilotHooks, copilotHookFilePath, detectCopilotHookDrift, isMethodManagedEvent, upsertCopilotHookFile, } from "./copilot.js";
-export { nativeEventName, } from "./lifecycle-mapping.js";
+export { buildMethodManagedHooks, isOwnSessionStartRender, sessionStartValidateCommand, } from "./entries.js";
+export { detectHooksDrift, normaliseOwnHookRenders, upsertMethodManagedHooks, } from "./merge.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/hooks-seed/merge.js

@@ -6,6 +6,7 @@
  * sync untouched.
  */
 import { METHOD_MANAGED_SENTINEL, isMethodManagedMatcher } from "./types.js";
+import { isOwnSessionStartRender } from "./entries.js";
 /**
  * Strip the method-managed sentinel and trailing whitespace from a hook
  * command so two commands can be compared modulo ownership marker.
@@ -105,6 +106,36 @@ export function upsertMethodManagedHooks(existing, owned) {
  * from what we would write now. Returns the list of events where drift
  * is present.
  */
+/**
+ * The existing settings with every method-managed session-start command this tool rendered at an
+ * earlier version swapped for the current render, for drift detection only. The tool's own older
+ * output is regenerable, never drift (the same rule settings-merge applies to an SDD_REPO_PATH it
+ * wrote). The raw settings still go to the upsert, which rewrites the older render.
+ */
+export function normaliseOwnHookRenders(existing, owned) {
+    const current = existing["hooks"];
+    const ownedCommand = owned.SessionStart?.[0]?.hooks[0]?.command;
+    if (!isHooksObject(current) || ownedCommand === undefined)
+        return existing;
+    const block = current;
+    const sessionStart = block.SessionStart;
+    if (!sessionStart)
+        return existing;
+    return {
+        ...existing,
+        hooks: {
+            ...block,
+            SessionStart: sessionStart.map((m) => isMethodManagedMatcher(m)
+                ? {
+                    ...m,
+                    hooks: m.hooks.map((h) => typeof h.command === "string" && isOwnSessionStartRender(h.command)
+                        ? { ...h, command: ownedCommand }
+                        : h),
+                }
+                : m),
+        },
+    };
+}
 export function detectHooksDrift(existing, owned) {
     const current = isHooksObject(existing["hooks"])
         ? existing["hooks"]

package/dist/lib/init/ci-workflow.js

@@ -16,8 +16,8 @@ export const BLOCK_END = "# method-managed: end";
  * Full file content (block + adopter-extension footer). Used by
  * `sdd-cli init` to write a fresh workflow.
  */
-export function renderMethodValidationWorkflow(profile) {
-    const methodBlock = buildMethodManagedBlock(profile);
+export function renderMethodValidationWorkflow(profile, runner) {
+    const methodBlock = buildMethodManagedBlock(profile, runner);
     return methodBlock + "\n\n# Adopter-specific jobs go in a separate workflow file\n# (e.g. .github/workflows/adopter-validation.yml) — see\n# docs/method/methods/ci-baseline-guide.md.\n";
 }
 /**
@@ -26,10 +26,19 @@ export function renderMethodValidationWorkflow(profile) {
  * `writeMarkedBlockFile` so adopter content outside the markers is
  * preserved verbatim.
  */
-export function renderMethodManagedWorkflowBlock(profile) {
-    return buildMethodManagedBlock(profile);
+export function renderMethodManagedWorkflowBlock(profile, runner) {
+    return buildMethodManagedBlock(profile, runner);
 }
-function buildMethodManagedBlock(profile) {
+/**
+ * `runs-on`: GitHub's hosted runner unless the SDD chose labels (sync --ci-runner), e.g. a
+ * self-hosted runner, where the Dagger engine and its cache persist between runs.
+ */
+function runsOn(runner) {
+    if (runner === undefined || runner.length === 0)
+        return "ubuntu-latest";
+    return runner.length === 1 ? runner[0] : `[${runner.join(", ")}]`;
+}
+function buildMethodManagedBlock(profile, runner) {
     return [
         BLOCK_BEGIN,
         "# Method Validation per M-ADR 0129, run by the method's Dagger module (M-ADR 0219).",
@@ -63,7 +72,7 @@ function buildMethodManagedBlock(profile) {
         // ONE job: GitHub bills each job rounded UP to a whole minute (adopter measurement, 2026-10-12).
         "  method-validation:",
         "    name: Method Validation",
-        "    runs-on: ubuntu-latest",
+        `    runs-on: ${runsOn(runner)}`,
         "    steps:",
         "      - uses: actions/checkout@v4",
         "      - name: Install Dagger",

package/dist/lib/lock-file.js

@@ -63,6 +63,7 @@ export function serialiseLockFile(lock) {
         `method_repo: ${lock.methodRepo}`,
         `lock_version: ${lock.lockVersion}`,
         ...(lock.ciBinding !== undefined ? [`ci_binding: ${lock.ciBinding}`] : []),
+        ...(lock.ciRunner !== undefined ? [`ci_runner: "${lock.ciRunner}"`] : []),
         ...(lock.ciWorkflowBlockSha256 !== undefined ? [`ci_workflow_block_sha256: "${lock.ciWorkflowBlockSha256}"`] : []),
         ...(lock.ciModuleSha256 !== undefined ? [`ci_module_sha256: "${lock.ciModuleSha256}"`] : []),
         "bundles:",
@@ -114,6 +115,7 @@ function parseVersioned(raw) {
     let lockVersion;
     let ciWorkflowBlockSha256;
     let ciBinding;
+    let ciRunner;
     let ciModuleSha256;
     const bundles = [];
     let inBundles = false;
@@ -180,6 +182,8 @@ function parseVersioned(raw) {
                     ciWorkflowBlockSha256 = stripQuotes(value);
                 else if (key === "ci_binding")
                     ciBinding = stripQuotes(value);
+                else if (key === "ci_runner")
+                    ciRunner = stripQuotes(value);
                 else if (key === "ci_module_sha256")
                     ciModuleSha256 = stripQuotes(value);
             }
@@ -306,6 +310,7 @@ function parseVersioned(raw) {
         lockVersion: LOCK_VERSION,
         bundles,
         ...(ciBinding !== undefined ? { ciBinding } : {}),
+        ...(ciRunner !== undefined ? { ciRunner } : {}),
         ...(ciWorkflowBlockSha256 !== undefined ? { ciWorkflowBlockSha256 } : {}),
         ...(ciModuleSha256 !== undefined ? { ciModuleSha256 } : {}),
     };