@sdd-method/maintain-cli 0.1.0 → 0.3.0

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,63 @@ export function buildMethodGuardPreToolUse() {
         ],
     };
 }
-export function buildSessionStartValidate() {
+const SESSION_START_VALIDATE_ARGS = ' validate --target-repo "${CLAUDE_PROJECT_DIR:-$(pwd)}" --validator adr-structure 2>&1 | head -20';
+/** The verify persona's npm package, unless the lock names a rescoped one (sync --cli-package). */
+export const DEFAULT_VERIFY_CLI_PACKAGE = "@sdd-method/verify-cli";
+/** One npm package name, scoped or not, the shape `npm pack` and `npx` accept. */
+export const NPM_PACKAGE_NAME = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+export const CLI_SOURCES = ["registry", "installed"];
+export const DEFAULT_CLI_SOURCE = { source: "registry" };
+function registryLauncher(version, pkg) {
+    return `npx --yes ${pkg}@${version}${SESSION_START_VALIDATE_ARGS}`;
+}
+function installedLauncher(version) {
+    return (`v=$(sdd-verify --version 2>/dev/null); [ "$v" = "${version}" ] || ` +
+        `echo "[method] sdd-verify \${v:-is not installed}; this SDD pins verify-cli ${version}: ` +
+        `pull your CLI release repository and run ./install.sh ${version}"; ` +
+        `if [ -n "$v" ]; then sdd-verify${SESSION_START_VALIDATE_ARGS}; fi`);
+}
+/**
+ * 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 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.
+ */
+export function sessionStartValidateCommand(verifyVersion = getVerifyCliVersion(), cli = DEFAULT_CLI_SOURCE) {
+    const body = cli.source === "installed"
+        ? installedLauncher(verifyVersion)
+        : registryLauncher(verifyVersion, cli.package ?? DEFAULT_VERIFY_CLI_PACKAGE);
+    return withSentinel(body);
+}
+const REGISTRY_FORM = /^npx --yes ((?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*)@(\S+) validate /;
+const INSTALLED_FORM = /^v=\$\(sdd-verify --version 2>\/dev\/null\); \[ "\$v" = "([^"]+)" \]/;
+/**
+ * Whether a session-start command is one this tool rendered, at any exact version and from either
+ * source: the sdd-cli form it wrote until the hook moved to verify-cli, the npx form under any
+ * package name, or the installed form. Sync replaces its own earlier render without counting it as
+ * drift, so a release that moves the pin, or a switch of source, needs no --allow-overwrite (the
+ * flag that also rewrites keys the adopter owns). The candidate is re-rendered from the version it
+ * names and must match exactly, so anything edited under the sentinel is still drift.
+ */
+export function isOwnSessionStartRender(command) {
+    const body = command.replace(METHOD_MANAGED_SENTINEL, "").trimEnd();
+    if (body === `sdd-cli${SESSION_START_VALIDATE_ARGS}`)
+        return true;
+    const npx = REGISTRY_FORM.exec(body);
+    if (npx && EXACT_VERSION.test(npx[2]))
+        return body === registryLauncher(npx[2], npx[1]);
+    const installed = INSTALLED_FORM.exec(body);
+    if (installed && EXACT_VERSION.test(installed[1]))
+        return body === installedLauncher(installed[1]);
+    return false;
+}
+export function buildSessionStartValidate(cli = DEFAULT_CLI_SOURCE) {
     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(getVerifyCliVersion(), cli),
             },
         ],
     };
@@ -37,10 +88,10 @@ export function buildSessionStartValidate() {
  * Full method-managed hooks block. When extending, add a new event
  * name to the returned object and a corresponding builder above.
  */
-export function buildMethodManagedHooks() {
+export function buildMethodManagedHooks(cli = DEFAULT_CLI_SOURCE) {
     const hooks = {
         PreToolUse: [buildMethodGuardPreToolUse()],
-        SessionStart: [buildSessionStartValidate()],
+        SessionStart: [buildSessionStartValidate(cli)],
     };
     return hooks;
 }

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, CLI_SOURCES, DEFAULT_CLI_SOURCE, DEFAULT_VERIFY_CLI_PACKAGE, isOwnSessionStartRender, NPM_PACKAGE_NAME, 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

@@ -8,7 +8,7 @@
  * block-marker pair so the sync path can preserve adopter-authored
  * content outside the block.
  */
-import { DAGGER_VERSION, MODULE_CALL, MODULE_DIR } from "../ci-binding/module.js";
+import { DAGGER_VERSION, MODULE_CALL, MODULE_DIR, REBUILD_FLAG, REBUILD_SCRIPT } from "../ci-binding/module.js";
 export const WORKFLOW_REL_PATH = ".github/workflows/method-validation.yml";
 export const BLOCK_BEGIN = "# method-managed: begin";
 export const BLOCK_END = "# method-managed: end";
@@ -56,6 +56,13 @@ function buildMethodManagedBlock(profile, runner) {
         "# released with the sdd-cli that last synced this repository. The catalogue",
         "# freshness step (@sdd-method/maintain-cli, pinned the same way) is advisory.",
         "#",
+        "# Catalogue rebuild (M-ADR 0220 §4.4), off until you configure it: set the",
+        "# repository variable SDD_CATALOGUE_APP_ID and the secret",
+        "# SDD_CATALOGUE_APP_PRIVATE_KEY for a GitHub App that can write contents, and",
+        "# the job rebuilds the catalogues and pushes them to the branch it is building",
+        "# (a pull request's own branch, never a fork's); the freshness step then gates.",
+        "# An App token, because pushes made with the default token start no workflow.",
+        "#",
         "# Run it locally (needs a container engine):",
         `#   ${MODULE_CALL}`,
         "",
@@ -74,11 +81,28 @@ function buildMethodManagedBlock(profile, runner) {
         "    name: Method Validation",
         `    runs-on: ${runsOn(runner)}`,
         "    steps:",
+        "      - name: Catalogue rebuild token",
+        "        id: catalogue-token",
+        "        if: vars.SDD_CATALOGUE_APP_ID != '' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)",
+        "        uses: actions/create-github-app-token@v1",
+        "        with:",
+        "          app-id: ${{ vars.SDD_CATALOGUE_APP_ID }}",
+        "          private-key: ${{ secrets.SDD_CATALOGUE_APP_PRIVATE_KEY }}",
         "      - uses: actions/checkout@v4",
+        "        with:",
+        // The branch itself when rebuilding, so the rebuild lands on it; otherwise the event's own ref.
+        "          ref: ${{ steps.catalogue-token.outputs.token != '' && (github.head_ref || github.ref_name) || '' }}",
+        "          persist-credentials: false",
         "      - name: Install Dagger",
         `        run: curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR="$RUNNER_TEMP/dagger" DAGGER_VERSION=${DAGGER_VERSION} sh && echo "$RUNNER_TEMP/dagger" >> "$GITHUB_PATH"`,
+        "      - name: Rebuild catalogues",
+        "        if: steps.catalogue-token.outputs.token != ''",
+        "        env:",
+        "          SDD_REBUILD_TOKEN: ${{ steps.catalogue-token.outputs.token }}",
+        "          SDD_REBUILD_BRANCH: ${{ github.head_ref || github.ref_name }}",
+        `        run: SDD_REBUILD_PUSH_URL="https://x-access-token:$SDD_REBUILD_TOKEN@\${GITHUB_SERVER_URL#https://}/$GITHUB_REPOSITORY.git" sh ${REBUILD_SCRIPT}`,
         "      - name: Method Validation",
-        `        run: ${MODULE_CALL}`,
+        `        run: ${MODULE_CALL} ${REBUILD_FLAG}`,
         BLOCK_END,
     ].join("\n");
 }

package/dist/lib/lock-file.js

@@ -66,6 +66,8 @@ export function serialiseLockFile(lock) {
         ...(lock.ciRunner !== undefined ? [`ci_runner: "${lock.ciRunner}"`] : []),
         ...(lock.ciWorkflowBlockSha256 !== undefined ? [`ci_workflow_block_sha256: "${lock.ciWorkflowBlockSha256}"`] : []),
         ...(lock.ciModuleSha256 !== undefined ? [`ci_module_sha256: "${lock.ciModuleSha256}"`] : []),
+        ...(lock.cliSource !== undefined ? [`cli_source: ${lock.cliSource}`] : []),
+        ...(lock.cliPackage !== undefined ? [`cli_package: "${lock.cliPackage}"`] : []),
         "bundles:",
     ];
     for (const b of lock.bundles) {
@@ -117,6 +119,8 @@ function parseVersioned(raw) {
     let ciBinding;
     let ciRunner;
     let ciModuleSha256;
+    let cliSource;
+    let cliPackage;
     const bundles = [];
     let inBundles = false;
     let inPaths = false;
@@ -186,6 +190,10 @@ function parseVersioned(raw) {
                     ciRunner = stripQuotes(value);
                 else if (key === "ci_module_sha256")
                     ciModuleSha256 = stripQuotes(value);
+                else if (key === "cli_source")
+                    cliSource = stripQuotes(value);
+                else if (key === "cli_package")
+                    cliPackage = stripQuotes(value);
             }
             continue;
         }
@@ -313,6 +321,8 @@ function parseVersioned(raw) {
         ...(ciRunner !== undefined ? { ciRunner } : {}),
         ...(ciWorkflowBlockSha256 !== undefined ? { ciWorkflowBlockSha256 } : {}),
         ...(ciModuleSha256 !== undefined ? { ciModuleSha256 } : {}),
+        ...(cliSource !== undefined ? { cliSource } : {}),
+        ...(cliPackage !== undefined ? { cliPackage } : {}),
     };
 }
 function migrateV1(raw, legacyBundleName) {

package/dist/lib/pack/builder.js

@@ -69,7 +69,9 @@ export async function buildPack(opts) {
         // 4. Checksums (over the published payload)
         const checksums = await computeChecksums(payload, publishedPaths);
         // 5. Manifest + managed_paths + checksums files
-        const gitInfo = await readGitInfo(opts.producerRepo);
+        const gitInfo = opts.provenance
+            ? { commit: opts.provenance.commit, branch: opts.provenance.branch }
+            : await readGitInfo(opts.producerRepo);
         await writeFile(join(root, "MANAGED_PATHS.txt"), publishedPaths.join("\n") + "\n");
         await writeFile(join(root, "CHECKSUMS.sha256"), checksums);
         await writeFile(join(root, "BUNDLE_MANIFEST.yaml"), renderManifest({
@@ -79,12 +81,13 @@ export async function buildPack(opts) {
             managedPathCount: publishedPaths.length,
             sourceCommit: gitInfo.commit,
             sourceBranch: gitInfo.branch,
+            ...(opts.provenance && { sourceRepo: opts.provenance.repo, generatedAt: opts.provenance.generatedAt }),
         }));
         // 6. tar -czf
         await mkdir(outDir, { recursive: true });
         const tarballName = `${rootName}.tar.gz`;
         const tarballPath = join(outDir, tarballName);
-        await execFile("tar", ["-czf", tarballPath, "-C", stage, rootName]);
+        await writeArchive(tarballPath, stage, rootName, await archiveEpoch(opts));
         // Also emit a sidecar checksum file for the tarball itself
         const tarballHash = await sha256File(tarballPath);
         const sidecar = `${tarballHash}  ${tarballName}\n`;
@@ -210,8 +213,8 @@ function renderManifest(ctx) {
     // sdd-method/orchestration/templates/bundle/BUNDLE_MANIFEST.yaml.hbs.
     // We don't go through a Handlebars engine because that would be the
     // only template-rendered file in sdd-cli; everything else is direct.
-    const generatedAt = new Date().toISOString();
-    const sourceRepo = deriveSourceRepoName(ctx.producerRepo);
+    const generatedAt = ctx.generatedAt ?? new Date().toISOString();
+    const sourceRepo = ctx.sourceRepo ?? deriveSourceRepoName(ctx.producerRepo);
     const lines = [];
     lines.push(`bundle_name: "${ctx.packName}"`);
     lines.push(`bundle_version: "v${ctx.seed.version}"`);
@@ -256,6 +259,55 @@ function renderManifest(ctx) {
     }
     return lines.join("\n") + "\n";
 }
+/**
+ * Member file times: the release record's time, else SOURCE_DATE_EPOCH, else the producer's HEAD
+ * commit time, else now (not a git tree, no record). Two cuts of one commit then agree.
+ */
+async function archiveEpoch(opts) {
+    if (opts.provenance)
+        return Math.floor(Date.parse(opts.provenance.generatedAt) / 1000);
+    const env = process.env.SOURCE_DATE_EPOCH;
+    if (env && /^\d+$/.test(env))
+        return Number(env);
+    try {
+        const { stdout } = await execFile("git", ["-C", opts.producerRepo, "log", "-1", "--format=%ct", "HEAD"]);
+        if (/^\d+$/.test(stdout.trim()))
+            return Number(stdout.trim());
+    }
+    catch {
+        // Not a git working tree.
+    }
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Write the tarball deterministically with GNU tar: sorted members, owner and group zeroed, modes
+ * normalised, fixed file times; gzip -n, so the header carries no name or time. Plain `tar -czf` stamped all of these from the machine, so a rebuild never matched.
+ * Without GNU tar (e.g. macOS's bsdtar) the archive is written the old way and is not reproducible.
+ */
+async function writeArchive(tarballPath, stage, rootName, epoch) {
+    let gnu = false;
+    try {
+        gnu = (await execFile("tar", ["--version"])).stdout.includes("GNU tar");
+    }
+    catch {
+        gnu = false;
+    }
+    if (!gnu) {
+        await execFile("tar", ["-czf", tarballPath, "-C", stage, rootName]);
+        return;
+    }
+    const tarPath = `${tarballPath}.tar`;
+    try {
+        await execFile("tar", ["--sort=name", "--format=gnu", `--mtime=@${epoch}`, "--owner=0", "--group=0", "--numeric-owner",
+            "--mode=u+rwX,go+rX,go-w", "-cf", tarPath, "-C", stage, rootName], { env: { ...process.env, LC_ALL: "C" } });
+        // GNU gzip, not Node's zlib: Node bundles a zlib fork whose output can depend on the CPU, and
+        // the method's own bundle builder compresses with gzip too.
+        await execFile("sh", ["-c", 'gzip -n -9 -c "$1" > "$2"', "sh", tarPath, tarballPath]);
+    }
+    finally {
+        await rm(tarPath, { force: true });
+    }
+}
 /**
  * Read git provenance from the producer working tree. Mirrors the
  * behaviour of sdd-method/orchestration/scripts/build-method-baseline-

package/dist/lib/pack/index.js

@@ -53,6 +53,7 @@ export async function runPackBuild(opts, stdout = (s) => process.stdout.write(s)
             }),
             ...(publishTransform && { publishTransform: true }),
             ...(opts.originPrefix === true && { mAdrPrefix: true }),
+            ...(opts.provenance && { provenance: opts.provenance }),
         });
     }
     catch (err) {

package/dist/lib/pack/publish-transform.js

@@ -48,7 +48,7 @@ const DENY_TEMPORAL = [
 ];
 const DENY_PRODUCER = [
     /sdd-method#/i,
-    /sdd-method-gov/i,
+    /sdd-method-g[o]v/i, // the class keeps the literal name out of this file, which ships
     /sdd-method repo/i,
     /the method repo/i,
     /governance repo/i,