@sdd-method/maintain-cli 0.2.0 → 0.4.0

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

@@ -8,14 +8,21 @@
  * wrote is pristine and re-renders with no override, and only an edited copy needs --allow-overwrite.
  * The binding is remembered in the lock too (`ci_binding:`, absent meaning github), so an estate
  * chooses it once.
+ *
+ * `local` is the binding with no host: the module is written and nothing calls it but people, for an
+ * estate that validates on its own machines only (the module is run with `dagger call` there). Sync
+ * removes the wrapper this tool wrote for the previous binding when its block still hashes to the
+ * lock's digest; an edited one is drift, and a file without markers is the adopter's and stays.
  */
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { dirname, join } from "node:path";
 import { BLOCK_BEGIN, BLOCK_END, WORKFLOW_REL_PATH, renderMethodManagedWorkflowBlock, renderMethodValidationWorkflow, } from "../init/ci-workflow.js";
 import { detectBlockDrift, writeMarkedBlockFile } from "../sync/yaml-block-merge.js";
-import { DAGGER_VERSION, MODULE_CALL, MODULE_DIR, moduleSha256, renderModuleFiles } from "./module.js";
-export const CI_BINDINGS = ["github", "gitlab", "jenkins"];
+import { DAGGER_VERSION, MODULE_CALL, MODULE_DIR, REBUILD_FLAG, REBUILD_SCRIPT, moduleSha256, renderModuleFiles } from "./module.js";
+/** The bindings that render a wrapper for a CI host. */
+export const HOST_BINDINGS = ["github", "gitlab", "jenkins"];
+export const CI_BINDINGS = [...HOST_BINDINGS, "local"];
 /** M-ADR 0219 §8.2 (ruled 2026-10-16): what every SDD has before it chooses. */
 export const DEFAULT_CI_BINDING = "github";
 /**
@@ -31,9 +38,24 @@ export function parseCiRunner(s) {
 export function isCiBinding(s) {
     return CI_BINDINGS.includes(s);
 }
+export function isHostBinding(s) {
+    return HOST_BINDINGS.includes(s);
+}
 const HASH = { begin: BLOCK_BEGIN, end: BLOCK_END };
 // Groovy has no '#' comments.
 const SLASH = { begin: "// method-managed: begin", end: "// method-managed: end" };
+// How each host's adopter switches the catalogue rebuild on (M-ADR 0220 §4.4): the variable the method names.
+const REBUILD_SETUP = {
+    "#": [
+        "set the masked (not protected) CI variable",
+        "SDD_CATALOGUE_PUSH_TOKEN to a project or group access token with write_repository.",
+    ],
+    "//": [
+        "set the job's environment variable",
+        "SDD_CATALOGUE_PUSH_CREDENTIAL to the ID of a username-and-password credential (a token",
+        "with write) for the repository's https remote.",
+    ],
+};
 function header(comment, profile) {
     return [
         `${comment} Method Validation per M-ADR 0129, run by the method's Dagger module (M-ADR 0219).`,
@@ -47,6 +69,11 @@ function header(comment, profile) {
         comment,
         `${comment} Run it locally:`,
         `${comment}   ${MODULE_CALL}`,
+        comment,
+        `${comment} Catalogue rebuild (M-ADR 0220 §4.4), off until you configure it:`,
+        ...REBUILD_SETUP[comment].map((l) => `${comment} ${l}`),
+        `${comment} The job then rebuilds the catalogues and pushes them to the branch it is`,
+        `${comment} building (never a fork's), and the freshness step gates.`,
     ];
 }
 // GitLab: a Docker-in-Docker service, the shape GitLab documents for Dagger. The runner must allow
@@ -71,10 +98,16 @@ function gitlabBlock(profile, runner) {
         '    - if: $CI_PIPELINE_SOURCE == "merge_request_event"',
         "    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH",
         "  before_script:",
-        "    - apk add --no-cache curl",
+        "    - apk add --no-cache curl git",
         `    - curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR=/usr/local/bin DAGGER_VERSION=${DAGGER_VERSION} sh`,
         "  script:",
-        `    - ${MODULE_CALL}`,
+        "    - |",
+        '      if [ -n "${SDD_CATALOGUE_PUSH_TOKEN:-}" ] && [ "${CI_MERGE_REQUEST_SOURCE_PROJECT_ID:-$CI_PROJECT_ID}" = "$CI_PROJECT_ID" ]; then',
+        '        SDD_REBUILD_BRANCH="${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME:-$CI_COMMIT_BRANCH}" \\',
+        '        SDD_REBUILD_PUSH_URL="${CI_SERVER_PROTOCOL}://oauth2:${SDD_CATALOGUE_PUSH_TOKEN}@${CI_SERVER_URL#*://}/${CI_PROJECT_PATH}.git" \\',
+        `        sh ${REBUILD_SCRIPT}`,
+        "      fi",
+        `    - ${MODULE_CALL} ${REBUILD_FLAG}`,
         HASH.end,
     ].join("\n");
 }
@@ -92,7 +125,18 @@ function jenkinsBlock(profile, runner) {
         "    stage('Method Validation') {",
         "      steps {",
         `        sh 'curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR="$WORKSPACE@tmp/dagger" DAGGER_VERSION=${DAGGER_VERSION} sh'`,
-        `        sh 'PATH="$WORKSPACE@tmp/dagger:$PATH" ${MODULE_CALL}'`,
+        "        script {",
+        "          if (env.SDD_CATALOGUE_PUSH_CREDENTIAL && !env.CHANGE_FORK) {",
+        "            withCredentials([usernamePassword(credentialsId: env.SDD_CATALOGUE_PUSH_CREDENTIAL, usernameVariable: 'SDD_PUSH_USER', passwordVariable: 'SDD_PUSH_TOKEN')]) {",
+        "              sh '''",
+        '                export SDD_REBUILD_BRANCH="${CHANGE_BRANCH:-${BRANCH_NAME:-${GIT_BRANCH#origin/}}}"',
+        '                export SDD_REBUILD_PUSH_URL="$(git config --get remote.origin.url | sed "s#^https://#https://${SDD_PUSH_USER}:${SDD_PUSH_TOKEN}@#")"',
+        `                PATH="$WORKSPACE@tmp/dagger:$PATH" sh ${REBUILD_SCRIPT}`,
+        "              '''",
+        "            }",
+        "          }",
+        "        }",
+        `        sh 'PATH="$WORKSPACE@tmp/dagger:$PATH" ${MODULE_CALL} ${REBUILD_FLAG}'`,
         "      }",
         "    }",
         "  }",
@@ -134,8 +178,41 @@ export function blockSha256(text, markers) {
 export async function syncCiBinding(o) {
     const failures = [];
     const log = [];
+    const was = o.prevLock?.ciBinding;
+    const sameBinding = (was ?? DEFAULT_CI_BINDING) === o.binding;
+    if (o.binding === "local") {
+        // No host. A switch removes the wrapper this tool wrote for the previous binding, but only when its
+        // block still hashes to the lock's digest: an edited block is drift, a file without markers is the
+        // adopter's and stays.
+        if (o.runner !== undefined && o.runner.length > 0) {
+            failures.push("--ci-runner names where a CI host runs the job; the local binding has no host. Drop --ci-runner (or choose a host binding).");
+        }
+        let removal = null;
+        const previous = sameBinding ? null : was === undefined ? DEFAULT_CI_BINDING : isHostBinding(was) ? was : null;
+        if (previous !== null) {
+            const prevHost = HOST_WRAPPERS[previous];
+            const abs = join(o.targetRepo, prevHost.relPath);
+            const text = await tryRead(abs);
+            const sha = blockSha256(text, prevHost.markers);
+            if (text !== null && sha === null) {
+                log.push(`${prevHost.relPath} has no method-managed markers, so it is the adopter's: left in place.`);
+            }
+            else if (text !== null && (sha === o.prevLock?.ciWorkflowBlockSha256 || o.allowDrift)) {
+                removal = { abs, rel: prevHost.relPath, text, host: prevHost };
+            }
+            else if (text !== null) {
+                failures.push(`${prevHost.relPath}: the method-managed block was edited since the last sync (it no longer matches the lock's digest), so switching to the local binding will not remove it. Re-run with --allow-overwrite to remove the block; adopter content outside the markers is kept.`);
+            }
+        }
+        const mod = await checkModule(o, failures, log);
+        if (o.checkOnly || failures.length > 0)
+            return { failures, log, wrapperSha: null, moduleSha: mod.shaOnDisk };
+        await writeModule(o, mod, log, "; the local binding calls it from no CI host");
+        if (removal !== null)
+            await removeWrapper(removal, o.profile, log);
+        return { failures, log, wrapperSha: null, moduleSha: mod.shaRendered };
+    }
     const host = HOST_WRAPPERS[o.binding];
-    const sameBinding = (o.prevLock?.ciBinding ?? DEFAULT_CI_BINDING) === o.binding;
     // 1. The host wrapper.
     const wrapperAbs = join(o.targetRepo, host.relPath);
     const existing = await tryRead(wrapperAbs);
@@ -153,49 +230,84 @@ export async function syncCiBinding(o) {
     else if (markerless && !o.allowOverwrite) {
         failures.push(`${host.relPath} exists without method-managed markers — refusing to overwrite adopter content. Re-run with --allow-overwrite to replace the file.`);
     }
-    // 2. The module: every file it renders, compared as one set.
+    // 2. The module.
+    const mod = await checkModule(o, failures, log);
+    if (o.checkOnly || failures.length > 0) {
+        return { failures, log, wrapperSha: null, moduleSha: mod.shaOnDisk };
+    }
+    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}.`);
+    await writeModule(o, mod, log, "");
+    // A binding switch between hosts leaves the previous host's file alone: it is the adopter's to delete
+    // once the new host runs, and deleting it here would remove a job some branch protection may still
+    // require. (From local there is no previous host file.)
+    if (!sameBinding && (was === undefined || isHostBinding(was))) {
+        const prevHost = HOST_WRAPPERS[was ?? DEFAULT_CI_BINDING];
+        if ((await tryRead(join(o.targetRepo, prevHost.relPath))) !== null) {
+            log.push(`CI binding is now ${o.binding}; ${prevHost.relPath} (the previous binding) is left in place. Delete it once ${host.relPath} runs.`);
+        }
+    }
+    return {
+        failures,
+        log,
+        wrapperSha: blockSha256(await tryRead(wrapperAbs), host.markers),
+        moduleSha: mod.shaRendered,
+    };
+}
+/**
+ * The module: every file it renders, compared as one set. Pristine when the files on disk hash to the
+ * lock's digest. The render may list a file the last sync never wrote (the generator gained one): it is
+ * absent, not edited, so the digest over the files present decides. A file the adopter deleted still
+ * changes that digest, so it is still drift.
+ */
+async function checkModule(o, failures, log) {
     const rendered = renderModuleFiles();
     const onDisk = [];
     for (const [rel] of rendered)
         onDisk.push([rel, await tryRead(join(o.targetRepo, MODULE_DIR, rel))]);
     const present = onDisk.some(([, c]) => c !== null);
     const matches = rendered.every(([rel, c], i) => onDisk[i][0] === rel && onDisk[i][1] === c);
-    const modulePristine = o.prevLock?.ciModuleSha256 !== undefined && moduleSha256(onDisk) === o.prevLock.ciModuleSha256;
+    const lockSha = o.prevLock?.ciModuleSha256;
+    const modulePristine = lockSha !== undefined &&
+        (moduleSha256(onDisk) === lockSha || moduleSha256(onDisk.filter(([, c]) => c !== null)) === lockSha);
     if (present && !matches && modulePristine) {
         log.push(`${MODULE_DIR}/: unmodified since the last sync (digest matches the lock); re-rendering it for this sdd-cli.`);
     }
     if (present && !matches && !modulePristine && !o.allowDrift) {
         failures.push(`${MODULE_DIR}/: the method-managed module differs from what this sdd-cli renders. Either the generator changed since the last sync (expected after a CLI upgrade) or a file was hand-edited. Re-run with --allow-overwrite to re-render it.`);
     }
-    if (o.checkOnly || failures.length > 0) {
-        return { failures, log, wrapperSha: null, moduleSha: moduleSha256(onDisk) };
+    return { rendered, present, matches, shaOnDisk: moduleSha256(onDisk), shaRendered: moduleSha256(rendered) };
+}
+async function writeModule(o, mod, log, note) {
+    if (mod.matches)
+        return;
+    for (const [rel, content] of mod.rendered) {
+        const abs = join(o.targetRepo, MODULE_DIR, rel);
+        await mkdir(dirname(abs), { recursive: true });
+        await writeFile(abs, content, "utf8");
     }
-    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) {
-        for (const [rel, content] of rendered) {
-            const abs = join(o.targetRepo, MODULE_DIR, rel);
-            await mkdir(dirname(abs), { recursive: true });
-            await writeFile(abs, content, "utf8");
-        }
-        log.push(`${present ? "Refreshed" : "Wrote"} ${MODULE_DIR}/ (the Method Validation module, M-ADR 0219).`);
+    log.push(`${mod.present ? "Refreshed" : "Wrote"} ${MODULE_DIR}/ (the Method Validation module, M-ADR 0219)${note}.`);
+}
+/**
+ * Remove a wrapper's method-managed block. The file goes with it when what remains is this tool's own
+ * template text (or nothing), since then no line of it is the adopter's; otherwise the rest is kept.
+ */
+async function removeWrapper(r, profile, log) {
+    const cut = (text) => {
+        const b = text.indexOf(r.host.markers.begin);
+        const e = text.indexOf(r.host.markers.end, b) + r.host.markers.end.length;
+        return (text.slice(0, b) + text.slice(e)).replace(/^\n+/, "");
+    };
+    const rest = cut(r.text);
+    if (rest.trim() === "" || rest.trim() === cut(r.host.file(profile)).trim()) {
+        await rm(r.abs);
+        log.push(`Removed ${r.rel}: the local binding has no CI host, and the file held only this tool's wrapper.`);
     }
-    // A binding switch leaves the previous host's file alone: it is the adopter's to delete once the
-    // new host runs, and deleting it here would remove a job some branch protection may still require.
-    if (!sameBinding) {
-        const was = o.prevLock?.ciBinding;
-        const previous = HOST_WRAPPERS[was !== undefined && isCiBinding(was) ? was : DEFAULT_CI_BINDING];
-        if ((await tryRead(join(o.targetRepo, previous.relPath))) !== null) {
-            log.push(`CI binding is now ${o.binding}; ${previous.relPath} (the previous binding) is left in place. Delete it once ${host.relPath} runs.`);
-        }
+    else {
+        await writeFile(r.abs, rest, "utf8");
+        log.push(`Removed the method-managed block from ${r.rel}; the adopter content outside it is kept.`);
     }
-    return {
-        failures,
-        log,
-        wrapperSha: blockSha256(await tryRead(wrapperAbs), host.markers),
-        moduleSha: moduleSha256(rendered),
-    };
 }
 async function tryRead(path) {
     try {

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

@@ -22,6 +22,16 @@ export const MODULE_DIR = ".dagger/method-validation";
 export const DAGGER_VERSION = "0.21.10";
 /** The command every host wrapper runs. */
 export const MODULE_CALL = `dagger call -m ${MODULE_DIR} method-validation --source .`;
+/** The pipeline catalogue rebuild (M-ADR 0220 §4.4): a method-managed script in the module, run by every host wrapper. */
+export const REBUILD_SCRIPT = `${MODULE_DIR}/catalogue-rebuild.sh`;
+/**
+ * Left in the git directory by REBUILD_SCRIPT when the rebuild ran, whether or not it pushed. Every
+ * wrapper turns it into the module's --catalogue-rebuild, so the freshness step gates exactly where
+ * the rebuild ran and the wrapper holds no condition of its own.
+ */
+export const REBUILD_RAN_MARKER = "sdd-catalogue-rebuild-ran";
+/** What every wrapper appends to MODULE_CALL: --catalogue-rebuild when, and only when, the rebuild ran. */
+export const REBUILD_FLAG = `$(test -f "$(git rev-parse --git-dir)/${REBUILD_RAN_MARKER}" && echo --catalogue-rebuild)`;
 const VERIFY_PIN = "@@VERIFY_CLI_VERSION@@";
 // The module's SDK import, substituted at render: written literally, the persona builds' import-closure
 // scan would read this text as an import of the CLI's own and refuse a dependency it does not declare.
@@ -39,7 +49,8 @@ const INDEX_TS = String.raw `/**
  *
  * The steps are the method's job plan, read at run time from "sdd-verify validate --list". Every
  * step runs even after an earlier one fails, so one red step never hides the verdicts after it. The
- * job fails only when a non-advisory step fails; the catalogue freshness step is advisory.
+ * job fails only when a non-advisory step fails; the catalogue freshness step is advisory unless the
+ * pipeline rebuilt the catalogues on this run (catalogue-rebuild.sh, M-ADR 0220 §4.4).
  */
 import { dag, Container, Directory, File, object, func, ReturnType } from ${DAGGER_SDK}
 
@@ -102,12 +113,14 @@ export class MethodValidation {
     maintainVersion: string = "${MAINTAIN_PIN}",
     verifyTarball?: File,
     maintainTarball?: File,
+    catalogueRebuild: boolean = false,
   ): Promise<string> {
     const base = this.toolchain(verifyVersion, maintainVersion, verifyTarball, maintainTarball)
       .withMountedDirectory("/src", source)
       .withWorkdir("/src")
     const versions = (await base.withExec(["sh", "-c", "sdd-verify --version; sdd-maintain --version"]).stdout()).split("\n")
-    const plan = JSON.parse(await base.withExec(["sdd-verify", "validate", "--list"]).stdout()) as {
+    const listArgs = ["sdd-verify", "validate", "--list"]
+    const plan = JSON.parse(await base.withExec(catalogueRebuild ? [...listArgs, "--catalogue-rebuild"] : listArgs).stdout()) as {
       profile: string
       steps: PlanStep[]
     }
@@ -130,8 +143,66 @@ export class MethodValidation {
     if (failed > 0) throw new Error(report)
     return report
   }
+
+  /**
+   * Rebuild the committed catalogues from the specifications (M-ADR 0220 §4.4) and return the whole
+   * new catalogues directory: every file sdd-maintain catalogue build produces, plus every file
+   * already there except a .csv the build no longer produces, the freshness check's own rule. The
+   * host wrapper's catalogue-rebuild.sh exports it over catalogues/ and pushes only if it changed.
+   */
+  @func()
+  catalogueRebuild(source: Directory, maintainVersion: string = "${MAINTAIN_PIN}", maintainTarball?: File): Directory {
+    return this.toolchain(undefined, maintainVersion, undefined, maintainTarball)
+      .withMountedDirectory("/src", source)
+      .withWorkdir("/src")
+      .withExec(["sdd-maintain", "catalogue", "build", "--sdd-path", ".", "--out", "/rebuilt"])
+      .withExec([
+        "sh",
+        "-c",
+        "mkdir -p /next && if [ -d catalogues ]; then cp -a catalogues/. /next/; fi && " +
+          "for f in /next/*.csv; do [ -e \"$f\" ] || continue; [ -e \"/rebuilt/$(basename \"$f\")\" ] || rm \"$f\"; done && " +
+          "cp -a /rebuilt/. /next/",
+      ])
+      .directory("/next")
+  }
 }
 `;
+// Run by every host wrapper, and only where the adopter has provided the push credential. Plain
+// strings, not a template: the shell's own \${...} must reach the file as written.
+const REBUILD_SH = [
+    "#!/bin/sh",
+    "# Pipeline catalogue rebuild (M-ADR 0220 §4.4). Written by sdd-cli sync and method-managed, like the",
+    "# rest of this module. The host wrapper runs it only where the adopter has provided the push",
+    "# credential, and sets:",
+    "#   SDD_REBUILD_BRANCH    the branch this pipeline builds, which the rebuild is pushed to",
+    "#   SDD_REBUILD_PUSH_URL  the repository's URL, carrying the credential",
+    "#",
+    "# A rebuild that changes nothing pushes nothing, so the push cannot loop: the pipeline it starts",
+    "# rebuilds the same catalogues, finds no change, and runs Method Validation.",
+    "set -eu",
+    ': "${SDD_REBUILD_BRANCH:?the host wrapper sets it}" "${SDD_REBUILD_PUSH_URL:?the host wrapper sets it}"',
+    "",
+    "# A merge the pipeline made (a merged-results or merge-with-target build) is not the branch's head,",
+    "# and pushing it would put that merge on the branch. The branch's own pipeline rebuilds instead.",
+    'if [ "$(git rev-list --parents -n 1 HEAD | wc -w)" -gt 2 ]; then',
+    '  echo "Catalogue rebuild: skipped, HEAD is a merge commit this pipeline made; the branch pipeline rebuilds."',
+    "  exit 0",
+    "fi",
+    "",
+    "dagger call -m " + MODULE_DIR + " catalogue-rebuild --source . export --path catalogues --wipe >/dev/null",
+    'touch "$(git rev-parse --git-dir)/' + REBUILD_RAN_MARKER + '"',
+    "git add -A catalogues",
+    "if git diff --cached --quiet; then",
+    '  echo "Catalogue rebuild: the committed catalogues already match the specifications; nothing to push."',
+    "  exit 0",
+    "fi",
+    "git diff --cached --stat",
+    'git -c user.name="sdd-method catalogue rebuild" -c user.email="catalogue-rebuild@sdd-method.invalid" \\',
+    '  commit -q -m "Rebuild catalogues from the specifications (Method Validation, M-ADR 0220 §4.4)"',
+    'git push -q "$SDD_REBUILD_PUSH_URL" "HEAD:refs/heads/$SDD_REBUILD_BRANCH"',
+    'echo "Catalogue rebuild: pushed $(git rev-parse --short HEAD) to $SDD_REBUILD_BRANCH; Method Validation runs on it there too."',
+    "",
+].join("\n");
 const DAGGER_JSON = `{
   "name": "method-validation",
   "engineVersion": "v${DAGGER_VERSION}",
@@ -183,6 +254,7 @@ const GITIGNORE = `/sdk
 export function renderModuleFiles(pins = { verify: getVerifyCliVersion(), maintain: getMaintainCliVersion() }) {
     return [
         [".gitignore", GITIGNORE],
+        ["catalogue-rebuild.sh", REBUILD_SH],
         ["dagger.json", DAGGER_JSON],
         ["package.json", PACKAGE_JSON],
         ["src/index.ts", INDEX_TS.split(VERIFY_PIN).join(pins.verify).split(MAINTAIN_PIN).join(pins.maintain).split(DAGGER_SDK).join('"@dagger.io' + '/dagger"')],

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

@@ -24,40 +24,62 @@ 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 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 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.
+ * 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()) {
-    return withSentinel(`npx --yes @sdd-method/verify-cli@${verifyVersion}${SESSION_START_VALIDATE_ARGS}`);
+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 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.
+ * 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.endsWith(SESSION_START_VALIDATE_ARGS))
-        return false;
-    const launcher = body.slice(0, body.length - SESSION_START_VALIDATE_ARGS.length);
-    if (launcher === "sdd-cli")
+    if (body === `sdd-cli${SESSION_START_VALIDATE_ARGS}`)
         return true;
-    const npx = VERIFY_CLI_NPX.exec(launcher);
-    return npx !== null && EXACT_VERSION.test(npx[1]);
+    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() {
+export function buildSessionStartValidate(cli = DEFAULT_CLI_SOURCE) {
     return {
         matcher: "startup",
         hooks: [
             {
                 type: "command",
-                command: sessionStartValidateCommand(),
+                command: sessionStartValidateCommand(getVerifyCliVersion(), cli),
             },
         ],
     };
@@ -66,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

@@ -9,6 +9,6 @@
  * when the repo runs the claude-code harness (the default).
  */
 export { METHOD_MANAGED_SENTINEL, isMethodManagedMatcher } from "./types.js";
-export { buildMethodManagedHooks, isOwnSessionStartRender, sessionStartValidateCommand, } from "./entries.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/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;
         }
@@ -207,7 +215,7 @@ function parseVersioned(raw) {
             // a YAML reader parses 113 of 325 entries in one real lock as MAPPINGS
             // rather than strings — silently, with no error. Quoting on write is the
             // fix; reading both forms ships first so no lock can be written that an
-            // older reader cannot parse. See method-open-items §3l.
+            // older reader cannot parse.
             const entry = stripQuotes(line.slice("      - ".length));
             const withDigest = DIGEST_ENTRY_RE.exec(entry);
             if (withDigest) {
@@ -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) {