@sdd-method/maintain-cli 0.2.0 → 0.3.0

package/NOTICE

@@ -2,7 +2,7 @@ sdd-cli
 Copyright 2026 Tom Foster
 
 This product includes software developed as part of the SDD method
-distribution (https://github.com/tomfosteruk/sdd-method).
+distribution.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/dist/lib/catalogue/aggregate.js

@@ -184,8 +184,8 @@ export async function runCatalogueAggregate(inputs, write) {
     // The same roots, additionally reachable by DIRECTORY BASENAME. An author who
     // writes a `platform/<name>/...` contract path is reading that name off the
     // filesystem, so it is the directory — which is routinely not the sdd_id (one
-    // estate declares `experience-platform` in a directory named
-    // `sdd-experience-platform`). Kept separate from sddRootsById on purpose: the
+    // estate declares `customer-platform` in a directory named
+    // `sdd-customer-platform`). Kept separate from sddRootsById on purpose: the
     // try-every-root pass must iterate each root ONCE, or a root reachable under two
     // names would count as two hits and report a false ambiguity.
     const sddRootAliases = new Map(sddRootsById);
@@ -1385,8 +1385,8 @@ export function adjudicateExternalSystems(rowsByCatalogue, findings) {
     const containers = rowsByCatalogue.get("c4_containers") ?? [];
     const deps = rowsByCatalogue.get("system_external_dependency") ?? [];
     // Camel humps split BEFORE lowercasing (F11a): most SDD ids are
-    // hyphenated, and `bvfmGatewayFramework` must be able to declare
-    // `bvfm-gateway-framework`.
+    // hyphenated, and `posGatewayFramework` must be able to declare
+    // `pos-gateway-framework`.
     const norm = (s) => s
         .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
         .toLowerCase()
@@ -1556,10 +1556,10 @@ export function adjudicateExternalSystems(rowsByCatalogue, findings) {
     // the display name agrees with the target — diagram entry ids are
     // conventionally local, and an old mnemonic that happens to equal an
     // estate id must not convert silently. Comparison is TOKEN-level, not
-    // substring (F12): "Tachograph Service" must not corroborate `tacho`
+    // substring (F12): "Stockroom Service" must not corroborate `stock`
     // (shared prefix, different entity), while "Engine (telematics
     // processor)" must corroborate a container named "Engine" (a richer
-    // label must not defeat the match) and three-letter names like "CWS"
+    // label must not defeat the match) and three-letter names like "OMS"
     // must work (no length floor). Corroborated = compact equality with the
     // target's name or id, or every token of either appearing among the
     // label's tokens. A declared id that corroborates is an assertion the

package/dist/lib/catalogue/build.js

@@ -1158,7 +1158,7 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
     out.set("repo_dependency", await buildRepoDependencies({ sddPath, configs: reposResult.configs, knownRepoIds: knownRepoIdsFinal, findings }));
     // 15. C4 systems + containers + components (L1 + L2 + L3). The L3 walker
     // shipped per `coordination/c4-l3-walker-and-path-convention-coordination.md`
-    // (sdd-method-gov, 2026-05-29) — forward-method authoring path reading
+    // (method governance, 2026-05-29) — forward-method authoring path reading
     // `c4-l3-*.mermaid.md` files alongside the L2 layout. The earlier Path-B
     // deferral assumed reverse-method code-walking; this walker is the
     // forward-method analogue, granularity-agnostic (per-container or

package/dist/lib/catalogue/builders/c4-components.js

@@ -6,7 +6,7 @@
 //
 // Mirrors c4-containers.ts at one level down. Source convention per
 // `coordination/c4-l3-walker-and-path-convention-coordination.md`
-// (sdd-method-gov, 2026-05-29). The walker is granularity-agnostic — both
+// (method governance, 2026-05-29). The walker is granularity-agnostic — both
 // per-container files (one `Container_Boundary` block per file) and
 // per-domain rollup files (multiple `Container_Boundary` blocks per file)
 // produce identical row output. Adopters pick the file shape that suits

package/dist/lib/catalogue/builders/c4-containers.js

@@ -219,7 +219,7 @@ function slugify(s) {
 }
 /**
  * F21: two technology strings flatly contradict when both are present and
- * share no token — ".NET 6 (in Linton)" vs "Java" needs no NLP. Absent or
+ * share no token — ".NET 6 (in Kestrel)" vs "Java" needs no NLP. Absent or
  * overlapping strings are NOT a contradiction (silence, not a guess).
  */
 export function techContradicts(a, b) {

package/dist/lib/catalogue/builders/c4-l1-candidates.js

@@ -20,7 +20,7 @@
 // personas instead of the sibling's. c4-external-systems UNIONS every
 // existing L1 file rather than picking one, so candidate order is irrelevant
 // there; it shares these paths only to avoid a divergent copy.
-// See sdd-method-gov/coordination/persona-c4system-l1-priority-bug-coordination.md.
+// See the method's coordination record persona-c4system-l1-priority-bug.
 import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 /** Own-L1 candidates usable by ANY SDD, in priority order. */

package/dist/lib/catalogue/builders/container-dependency.js

@@ -121,7 +121,7 @@ export async function buildContainerDependency(inputs) {
  * SAME referent and fired. The predicate was inverted on the two
  * name-shapes the estate actually uses.
  *
- * The independent channel is the technology string: ".NET 6 (in Linton)"
+ * The independent channel is the technology string: ".NET 6 (in Kestrel)"
  * against "Java" is a flat contradiction and needs no NLP. A dual-use
  * entry-id (Container + System_Ext in one SDD) whose technologies
  * contradict draws the finding REGARDLESS of what the names say — name

package/dist/lib/catalogue/builders/data-store-mapping.js

@@ -71,7 +71,7 @@ export function collectTableLines(lines, startIdx) {
     return null;
 }
 // ADR 0164: map a Data Store Mapping `Store` cell (a physical engine such as
-// "MySQL (fleet-db)", "MongoDB", "DynamoDB", "Kinesis") to the canonical
+// "MySQL (orders-db)", "MongoDB", "DynamoDB", "Kinesis") to the canonical
 // `entities.persistence_kind` classification. This mirrors the services
 // builder's deriveLanguage (a normalised token derived from a raw cell) —
 // faithful classification, not a verbatim engine. The raw engine string is

package/dist/lib/catalogue/builders/screen-tree.js

@@ -35,7 +35,7 @@ const STRING_RE = /"[^"]*"|'[^']*'/g;
  * line-structure-preserving) so call-head lexing can never fire on quoted
  * content — `Table("Odometer (km)")` must not mint a phantom `Odometer`
  * component, and `"total (sum)"` must not false-fire the lowercase-call-head
- * finding (tomfosteruk/sdd-cli#1). Quote characters are kept; newlines inside
+ * finding (sdd-cli issue 1). Quote characters are kept; newlines inside
  * a span survive. The grammar defines no escape sequences (a quote always
  * closes the literal), matching STRING_RE and stripLineComment.
  *

package/dist/lib/catalogue/contract-path-resolution.js

@@ -54,8 +54,8 @@ export function isPathShaped(value) {
  * sdd_id OR by its directory basename, and the distinction is not cosmetic: an
  * author writing this prefix is reading it off the filesystem, so it is the
  * DIRECTORY they write. In one measured estate every such prefix is
- * `platform/sdd-experience-platform/` while that SDD's declared sdd_id is
- * `experience-platform` — matching on sdd_id alone therefore split nothing and
+ * `platform/sdd-customer-platform/` while that SDD's declared sdd_id is
+ * `customer-platform` — matching on sdd_id alone therefore split nothing and
  * reported 13 existing contracts as missing. Both keys are accepted.
  *
  * That prefix

package/dist/lib/catalogue/scores-coverage.js

@@ -171,7 +171,7 @@ export const RUBRIC_ELIGIBILITY = [
         joinColumn: "id",
         refTransform: null,
         eligibilityFilter: null,
-        eligibilityNote: "NO local population, measured rather than assumed. Refs are '<domain>-feature-grounding-<slug>' and the tails are SIBLING SDD SLUGS (app-shell, cold-chain, connect-rapide), not rows in this SDD: 0/15 against products, applications, features and repositories, and 1/15 against capabilities — a coincidence, not a join. A cross-SDD reference the member tier cannot resolve, so its coverage is declared unmeasurable rather than given a transform that would produce plausible wrong numbers.",
+        eligibilityNote: "NO local population, measured rather than assumed. Refs are '<domain>-feature-grounding-<slug>' and the tails are SIBLING SDD SLUGS (app-shell, gift-cards, storefront-express), not rows in this SDD: 0/15 against products, applications, features and repositories, and 1/15 against capabilities — a coincidence, not a join. A cross-SDD reference the member tier cannot resolve, so its coverage is declared unmeasurable rather than given a transform that would produce plausible wrong numbers.",
     },
     {
         rubricId: "reverse-contract-quality",

package/dist/lib/catalogue/service-contract-aliases-loader.js

@@ -27,7 +27,7 @@
  *       # services). Use when the federated SDD lacks a services.csv to
  *       # gate emission and consumes rows would otherwise dangle at the
  *       # aggregator with unresolved service_id.
- *       - postman-tacho
+ *       - postman-stock
  *       - smoke-tests
  *
  *     same_product_inference:

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

@@ -14,7 +14,7 @@ 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";
+import { DAGGER_VERSION, MODULE_CALL, MODULE_DIR, REBUILD_FLAG, REBUILD_SCRIPT, moduleSha256, renderModuleFiles } from "./module.js";
 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";
@@ -34,6 +34,18 @@ export function isCiBinding(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 +59,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 +88,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 +115,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}'`,
         "      }",
         "    }",
         "  }",
@@ -160,7 +194,12 @@ export async function syncCiBinding(o) {
         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;
+    // 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.
+    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.`);
     }

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 (sdm-jts.9's ruling) 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;
         }
@@ -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,

package/dist/lib/sync/index.js

@@ -11,6 +11,7 @@ import { cacheBundle, ensureCacheGitignored, splitConsumptionModes, } from "./bu
 import { PROTECTED_PREFIXES, allPristine, classifyConflicts, computeRemovals, detectShadowCollisions, digestManagedPaths, findConflicts, findMissingPayloadFiles, findProtectedPaths, } from "./diff.js";
 import { applyAdrRenames, findStrandedCitations, planAdrTransitions, } from "./adr-transitions.js";
 import { syncMethodManagedSettings } from "./settings-merge.js";
+import { CLI_SOURCES, NPM_PACKAGE_NAME } from "../hooks-seed/index.js";
 import { syncBriefingFiles } from "./briefing-merge.js";
 import { DEFAULT_AGENT_HARNESS } from "../agent-harness.js";
 import { BLOCK_BEGIN, BLOCK_END } from "../init/ci-workflow.js";
@@ -102,6 +103,24 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
             return { exitCode: 1 };
         }
         const ciRunner = opts.ciRunner ?? lockRunner;
+        const lockSource = prevLock?.cliSource;
+        if (lockSource !== undefined && !CLI_SOURCES.includes(lockSource)) {
+            stdout(fail(`method-baseline.lock names cli_source '${lockSource}', which is not one of ${CLI_SOURCES.join(", ")}. Re-run with --cli-source <source> to choose one.`));
+            return { exitCode: 1 };
+        }
+        const lockPackage = prevLock?.cliPackage;
+        if (lockPackage !== undefined && !NPM_PACKAGE_NAME.test(lockPackage)) {
+            stdout(fail(`method-baseline.lock names cli_package '${lockPackage}', which is not an npm package name. Re-run with --cli-package <name> or --cli-package default.`));
+            return { exitCode: 1 };
+        }
+        const source = opts.cliSource ?? lockSource ?? "registry";
+        if (source === "installed" && typeof opts.cliPackage === "string") {
+            stdout(fail("--cli-package names an npm package for the registry source; the installed source runs sdd-verify from PATH. Drop --cli-package or choose --cli-source registry."));
+            return { exitCode: 1 };
+        }
+        // The installed source has no package; switching to it drops a recorded name.
+        const cliPackage = source === "installed" ? undefined : opts.cliPackage === undefined ? lockPackage : (opts.cliPackage ?? undefined);
+        const cliSource = source === "installed" ? { source } : { source, ...(cliPackage ? { package: cliPackage } : {}) };
         const classification = await classifyConflicts(conflicts, opts.targetRepo, prevEntry?.pathDigests);
         if (conflicts.length > 0) {
             reportClassification(stdout, conflicts.length, classification, prevEntry?.bundleVersion);
@@ -336,6 +355,7 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
                             targetRepo: opts.targetRepo,
                             allowOverwrite: false,
                             checkOnly: true,
+                            cliSource,
                             ...(opts.agentHarness ? { agentHarness: opts.agentHarness } : {}),
                         });
                         if (probe.refused) {
@@ -500,6 +520,7 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
             const settingsResult = await syncMethodManagedSettings({
                 targetRepo: opts.targetRepo,
                 allowOverwrite: opts.allowOverwrite || migrateFrom !== null,
+                cliSource,
                 ...(opts.agentHarness ? { agentHarness: opts.agentHarness } : {}),
             });
             if (settingsResult.refused) {
@@ -552,15 +573,18 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
         for (const line of briefingResult.log)
             stdout(info(line));
         // Record the wrapper block and the module exactly as they now stand on disk, so the next sync
-        // can tell them untouched from edited (M-ADR 0218 §4.7), and the binding when it is not the default.
+        // can tell them untouched from edited (M-ADR 0218 §4.7), and the binding and the CLI source
+        // when they are not the defaults.
         const nextLock = upsertBundle(migrateFrom ? removeBundle(prevLock, migrateFrom.name) : prevLock, newEntry);
-        const { ciBinding: _previousBinding, ciRunner: _previousRunner, ciWorkflowBlockSha256: _previousSha, ...lockBase } = nextLock;
+        const { ciBinding: _previousBinding, ciRunner: _previousRunner, ciWorkflowBlockSha256: _previousSha, cliSource: _previousSource, cliPackage: _previousPackage, ...lockBase } = nextLock;
         await writeLockFile(opts.targetRepo, {
             ...lockBase,
             ...(ciBinding !== DEFAULT_CI_BINDING ? { ciBinding } : {}),
             ...(ciRunner !== undefined && ciRunner.length > 0 ? { ciRunner: ciRunner.join(",") } : {}),
             ...(ci.wrapperSha !== null ? { ciWorkflowBlockSha256: ci.wrapperSha } : {}),
             ciModuleSha256: ci.moduleSha,
+            ...(cliSource.source !== "registry" ? { cliSource: cliSource.source } : {}),
+            ...(cliPackage !== undefined ? { cliPackage } : {}),
         });
         stdout(pass(`Method baseline synced to: ${opts.targetRepo}`));
         stdout(info(`Updated lock file: method-baseline.lock (lock_version: ${LOCK_VERSION})`));

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

@@ -67,7 +67,7 @@ export async function syncMethodManagedSettings(opts) {
     const fileExisted = await fileExists(absPath);
     const existing = await readSettings(absPath);
     const hooksActive = opts.agentHarness === "claude-code";
-    const ownedHooks = hooksActive ? buildMethodManagedHooks() : undefined;
+    const ownedHooks = hooksActive ? buildMethodManagedHooks(opts.cliSource) : undefined;
     const hooksDrifted = hooksActive && ownedHooks
         ? detectHooksDrift(normaliseOwnHookRenders(existing, ownedHooks), ownedHooks)
         : [];

package/dist/lib/validate/plan.js

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

package/dist/maintain-program.js

@@ -24,7 +24,7 @@ import { registerGenerateBriefing } from "./verbs/generate-briefing.js";
 import { registerPackBuild } from "./verbs/pack-build.js";
 import { registerRender } from "./verbs/render.js";
 import { registerSync } from "./verbs/sync.js";
-const SPEC_URL = "https://github.com/tomfosteruk/sdd-method/blob/main/docs/method/cli/sdd-cli-specification.md";
+const SPEC_URL = "docs/method/cli/sdd-cli-specification.md (in the method distribution)";
 /** The verbs maintain adds to verify, as `<verb>` or `<verb> <subcommand>`. Asserted by test. */
 export const MAINTAIN_ONLY_SURFACE = [
     "sync",

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.2.0",
-  "built_against_sdd_cli": "1.43.0"
+  "version": "0.3.0",
+  "built_against_sdd_cli": "1.44.0"
 }

package/dist/verbs/pack-build.js

@@ -13,7 +13,21 @@ export function registerPackBuild(pack) {
         .option("--forward-base-managed-paths <path>", "path to forward-base MANAGED_PATHS.txt for the leakage check (defaults to extracting from method-baseline.lock)")
         .option("--publish-transform", "apply the point-in-time / producer-agnostic publish transform (ADR 0183/0184): drop non-Accepted ADRs, strip lineage + stripped-class fields, flatten cross-repo refs, fail closed on leaks. For producer-published bundles.")
         .option("--origin-prefix", "with the publish transform, apply the range-aware origin prefix (ADR 0140 §4.1): 0NNN→M-ADR, 9NNN→RA-ADR, adopter 1NNN stays ADR; ADR files renamed to match. Implies --publish-transform. The RA-ADR bundle cutover switch.")
+        .option("--source-commit <sha>", "provenance from a release record: the commit the manifest records (with --source-branch, --source-repo and --generated-at)")
+        .option("--source-branch <name>", "provenance from a release record: the branch the manifest records")
+        .option("--source-repo <name>", "provenance from a release record: the repository name the manifest records, whatever the checkout is called")
+        .option("--generated-at <utc>", "provenance from a release record: the manifest's generated_at_utc (YYYY-MM-DDTHH:MM:SSZ), also every archive member's file time")
         .action(async (opts) => {
+        const rec = [opts.sourceCommit, opts.sourceBranch, opts.sourceRepo, opts.generatedAt];
+        const given = rec.filter((v) => v !== undefined).length;
+        if (given !== 0 && given !== 4) {
+            process.stderr.write(`--source-commit, --source-branch, --source-repo and --generated-at go together (got ${given} of 4)\n`);
+            process.exit(2);
+        }
+        if (opts.generatedAt !== undefined && !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(opts.generatedAt)) {
+            process.stderr.write(`--generated-at must be UTC, YYYY-MM-DDTHH:MM:SSZ (got '${opts.generatedAt}')\n`);
+            process.exit(2);
+        }
         const { exitCode } = await runPackBuild({
             seedPath: opts.seed,
             producerRepo: opts.producerRepo ?? process.cwd(),
@@ -23,6 +37,14 @@ export function registerPackBuild(pack) {
             }),
             ...(opts.publishTransform && { publishTransform: true }),
             ...(opts.originPrefix && { originPrefix: true }),
+            ...(given === 4 && {
+                provenance: {
+                    commit: opts.sourceCommit,
+                    branch: opts.sourceBranch,
+                    repo: opts.sourceRepo,
+                    generatedAt: opts.generatedAt,
+                },
+            }),
         });
         if (exitCode !== 0)
             process.exit(exitCode);

package/dist/verbs/sync.js

@@ -3,6 +3,7 @@ import { loadSyncConfig } from "../lib/sync/config.js";
 import { materialiseBundle } from "../lib/sync/bundle-source.js";
 import { runSync } from "../lib/sync/index.js";
 import { CI_BINDINGS, CI_RUNNER_DEFAULT, isCiBinding, parseCiRunner } from "../lib/ci-binding/index.js";
+import { CLI_SOURCES, DEFAULT_VERIFY_CLI_PACKAGE, NPM_PACKAGE_NAME } from "../lib/hooks-seed/index.js";
 import { resolvePathOption } from "./path-option.js";
 export function registerSync(program) {
     program
@@ -19,6 +20,8 @@ export function registerSync(program) {
         .option("--agent-harness <name>", `target agent harness for hooks + briefing. Default: claude-code. Supported: ${AGENT_HARNESSES.join(", ")}`)
         .option("--ci-binding <host>", `CI host whose wrapper calls the Method Validation module (M-ADR 0219): ${CI_BINDINGS.join(", ")}. Default: the binding the lock records, else github; a new choice is recorded in the lock`)
         .option("--ci-runner <labels>", `runner label(s) the CI wrapper targets, comma-separated (GitHub runs-on, GitLab tags, Jenkins agent label), e.g. a self-hosted runner. '${CI_RUNNER_DEFAULT}' returns to the host's default runner. Default: what the lock records; a new choice is recorded`)
+        .option("--cli-source <source>", `where the session-start hook finds the verify CLI: ${CLI_SOURCES.join(" (npx at the pinned version) or ")} (sdd-verify from PATH, for an org that installs the release's CLI tarballs; the hook names the version to install when it differs). Default: what the lock records, else registry; a new choice is recorded`)
+        .option("--cli-package <name>", `the verify CLI's npm package under the registry source, for a registry that rescopes it. 'default' returns to ${DEFAULT_VERIFY_CLI_PACKAGE}. Default: what the lock records; a new choice is recorded`)
         .action(async (opts) => {
         if (opts.ciBinding !== undefined && !isCiBinding(opts.ciBinding)) {
             process.stderr.write(`[FAIL] --ci-binding must be one of ${CI_BINDINGS.join(", ")}; got '${opts.ciBinding}'\n`);
@@ -34,6 +37,16 @@ export function registerSync(program) {
             }
             ciRunner = parsed;
         }
+        if (opts.cliSource !== undefined && !CLI_SOURCES.includes(opts.cliSource)) {
+            process.stderr.write(`[FAIL] --cli-source must be one of ${CLI_SOURCES.join(", ")}; got '${opts.cliSource}'\n`);
+            process.exit(1);
+        }
+        const cliSource = opts.cliSource;
+        if (opts.cliPackage !== undefined && opts.cliPackage !== "default" && !NPM_PACKAGE_NAME.test(opts.cliPackage)) {
+            process.stderr.write(`[FAIL] --cli-package takes an npm package name, or 'default'; got '${opts.cliPackage}'\n`);
+            process.exit(1);
+        }
+        const cliPackage = opts.cliPackage === undefined ? undefined : opts.cliPackage === "default" ? null : opts.cliPackage;
         let agentHarness;
         try {
             agentHarness = resolveAgentHarness(opts.agentHarness);
@@ -61,6 +74,8 @@ export function registerSync(program) {
                 agentHarness,
                 ...(ciBinding ? { ciBinding } : {}),
                 ...(ciRunner ? { ciRunner } : {}),
+                ...(cliSource ? { cliSource } : {}),
+                ...(cliPackage !== undefined ? { cliPackage } : {}),
                 ...(opts.replaceBundle ? { replaceBundle: opts.replaceBundle } : {}),
                 ...(opts.yes === true ? { yes: true } : {}),
             });
@@ -90,6 +105,8 @@ export function registerSync(program) {
                         agentHarness,
                         ...(ciBinding ? { ciBinding } : {}),
                         ...(ciRunner ? { ciRunner } : {}),
+                        ...(cliSource ? { cliSource } : {}),
+                        ...(cliPackage !== undefined ? { cliPackage } : {}),
                     });
                     if (exitCode !== 0) {
                         await resolved.cleanup();

package/dist/verbs/validate.js

@@ -14,7 +14,12 @@ export function registerValidate(program) {
         .option("--strict", "treat warnings as failures")
         .option("--list", "print the method-managed validation job for this repo's profile as JSON (the plan every CI executor runs, the Dagger module included) and run nothing")
         .option("--profile <profile>", "with --list: the profile to list, instead of reading .sdd-repo-kind (platform | application | integration)")
+        .option("--catalogue-rebuild", "with --list: the pipeline rebuilt the catalogues on this run (M-ADR 0220 §4.4), so the catalogue freshness step gates instead of advising")
         .action(async (opts) => {
+        if (opts.catalogueRebuild === true && opts.list !== true) {
+            process.stderr.write("--catalogue-rebuild only applies with --list\n");
+            process.exit(2);
+        }
         if (opts.list === true) {
             let profile;
             if (opts.profile !== undefined) {
@@ -32,7 +37,7 @@ export function registerValidate(program) {
                 }
                 profile = profileFromRepoKind(kind);
             }
-            process.stdout.write(JSON.stringify({ profile, steps: methodValidationPlan(profile) }, null, 2) + "\n");
+            process.stdout.write(JSON.stringify({ profile, steps: methodValidationPlan(profile, { catalogueRebuild: opts.catalogueRebuild === true }) }, null, 2) + "\n");
             return;
         }
         const { exitCode } = await runValidate({

package/dist/verify-program.js

@@ -29,7 +29,7 @@ import { registerCatalogueBaselineCheck, registerCatalogueImpact, registerCatalo
 import { registerList } from "./verbs/list.js";
 import { registerPackValidate } from "./verbs/pack-validate.js";
 import { registerValidate } from "./verbs/validate.js";
-const SPEC_URL = "https://github.com/tomfosteruk/sdd-method/blob/main/docs/method/cli/sdd-cli-specification.md";
+const SPEC_URL = "docs/method/cli/sdd-cli-specification.md (in the method distribution)";
 /** The full surface, as `<verb>` or `<verb> <subcommand>`. Asserted by test. */
 export const VERIFY_SURFACE = [
     "validate",

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "1.2.0",
-  "built_against_sdd_cli": "1.43.0"
+  "version": "1.3.0",
+  "built_against_sdd_cli": "1.44.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/maintain-cli",
-  "version": "0.2.0",
-  "sddCliVersion": "1.43.0",
+  "version": "0.3.0",
+  "sddCliVersion": "1.44.0",
   "description": "Bring an SDD repository current and rebuild its derived model — sync, briefing, catalogue build and aggregate, pack build, context pull — plus every read-only verify verb. Ships only the code those verbs reach; it cannot author specification content. Authoring is in @sdd-method/sdd-cli.",
   "license": "Apache-2.0",
   "type": "module",
@@ -17,10 +17,6 @@
     "zod": "^4.3.6",
     "@duckdb/node-api": "^1.5.5-r.3"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tomfosteruk/sdd-cli.git"
-  },
   "publishConfig": {
     "access": "public"
   },