@sdd-method/maintain-cli 0.2.0 → 0.4.0

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/pack/reference-closure.js

@@ -14,10 +14,10 @@
  * ENFORCEMENT (validate-link-closure.sh). A subset cannot satisfy closure
  * without ceasing to be a subset.
  *
- * Parser hardening comes from the estate that measured this problem — the
- * four traps their link audit hit are this module's controls: markdown
+ * Parser hardening covers the four traps a real link audit hit, which are
+ * this module's controls: markdown
  * targets containing SPACES (unencoded paths must not truncate at the first
- * space), targets containing PARENTHESES (balance them; "…(ReBAC).md" broke
+ * space), targets containing PARENTHESES (balance them; "…(v2).md" broke
  * every naive regex), URL-ENCODED targets (%20, %3A… decode before
  * resolving), and never scanning outside the payload set (no cache dirs —
  * guaranteed here by construction, since only staged payload paths are read).

package/dist/lib/package-version.js

@@ -83,7 +83,7 @@ export function getVerifyCliVersion() {
 }
 /**
  * The @sdd-method/maintain-cli version released WITH this sdd-cli. The managed CI workflow's
- * catalogue freshness step installs exactly this version (M-ADR 0218 §5; ruled 2026-10-15, sdm-jts.6).
+ * catalogue freshness step installs exactly this version (M-ADR 0218 §5).
  * Read the same way as the verify version, for the same reason (dist/ copy, never scripts/ live).
  */
 export function getMaintainCliVersion() {

package/dist/lib/snapshot/manifest.js

@@ -82,7 +82,7 @@ export async function readManifest(areaRoot, id) {
     }
     if (!Array.isArray(raw.members))
         problems.push("members must be a list");
-    // A hand-written revision of digits only (`50834756022`) parses as a NUMBER, and
+    // A hand-written revision of digits only (`12345678901`) parses as a NUMBER, and
     // a strict comparison with the folder's string suffix then calls an unchanged
     // member changed. Identity fields are strings, whatever YAML made of them.
     for (const m of raw.members ?? []) {

package/dist/lib/sync/adr-transitions.js

@@ -90,7 +90,7 @@ export async function planAdrTransitions(bundleRootDir, targetRepo, previousVers
     const protectedFromRemoval = [];
     const movedPaths = [];
     /**
-     * FIRST ADOPTION replays the bundle's whole transition history (ledger §3ae).
+     * FIRST ADOPTION replays the bundle's whole transition history.
      * A repo adopting a bundle for the first time receives its CURRENT state, so
      * every transition in the log happened before this repo existed as an
      * adopter — yet the log is filtered only by "newer than the last applied

package/dist/lib/sync/diff.js

@@ -154,7 +154,7 @@ export function computeRemovals(prevPaths, incomingPaths, options) {
 }
 /**
  * SHADOW COLLISIONS — an incoming managed file whose basename already exists at
- * a SHALLOWER, unmanaged path in the adopter's repo (ledger §3ap).
+ * a SHALLOWER, unmanaged path in the adopter's repo.
  *
  * When the distributed surface MOVES a file, copies previously delivered at the
  * old location are stranded as unmanaged files. They keep resolving, so nothing

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";
@@ -101,7 +102,30 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
             stdout(fail(`method-baseline.lock names ci_runner '${prevLock.ciRunner}', which is not a list of runner labels. Re-run with --ci-runner <label[,label]> or --ci-runner default.`));
             return { exitCode: 1 };
         }
-        const ciRunner = opts.ciRunner ?? lockRunner;
+        // The local binding has no host to run on: a runner the lock recorded for an earlier host binding is
+        // dropped (and the lock line with it); only an explicit --ci-runner with local is refused.
+        const droppedRunner = ciBinding === "local" && opts.ciRunner === undefined && lockRunner !== undefined && lockRunner.length > 0;
+        const ciRunner = ciBinding === "local" && opts.ciRunner === undefined ? undefined : opts.ciRunner ?? lockRunner;
+        if (droppedRunner)
+            stdout(info(`ci_runner '${prevLock.ciRunner}' dropped: the local binding has no CI host to run on.`));
+        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);
@@ -220,7 +244,7 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
         if (cacheOnlyPaths.length > 0) {
             stdout(info(`Cache-only (scaffold-source/registry) files: ${cacheOnlyPaths.length} — extracted to .sdd/bundle-cache, not materialised`));
         }
-        // SHADOW-COLLISION FLAG (ledger §3ap, the durable move-rule's machinery).
+        // SHADOW-COLLISION FLAG (the durable move-rule's machinery).
         // When the distributed surface MOVES a file, previously-delivered copies at
         // the old location are stranded as unmanaged files: they keep resolving, so
         // nothing breaks loudly, and they silently go stale as their managed twins
@@ -251,7 +275,7 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
             }
         }
         stdout(info(`Conflicts: ${conflicts.length}`));
-        // RELABEL (ledger §3y.2): the raw count mixes two different things and an
+        // RELABEL: the raw count mixes two different things and an
         // adopter's dry-run reported 31 where the artefacts on disk numbered 5.
         // Nothing was wrong with the mechanism — the LABEL claimed deletions for
         // lock entries whose paths were never materialised (cache-only payload
@@ -336,6 +360,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 +525,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 +578,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/index.js

@@ -54,7 +54,7 @@ export async function runValidate(opts, stdout = (line) => process.stdout.write(
 // passed" with none were previously the same line (M-ADR 0200 §4.3). The
 // exit code is deliberately unchanged — the defect is the claim, not the
 // gating; whether an unexecutable validator should FAIL is the open design
-// question (post-3.0.0-followons.md A2), not this one.
+// question, not this one.
 function verdict(summary, selected) {
     if (summary.exitCode !== 0)
         return fail("One or more validators failed");

package/dist/lib/validate/plan.js

@@ -1,5 +1,5 @@
 /**
- * The method-managed validation job, as DATA (bead sdm-dd6.2; Dagger ruling sdm-s48, 2026-10-15).
+ * The method-managed validation job, as DATA (M-ADR 0219).
  *
  * One ordered plan per profile: every default validator, the platform's script-only checks, then the
  * advisory catalogue freshness check. Every executor renders or runs THIS: the GitHub workflow
@@ -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/lib/validate/yaml-parse.js

@@ -10,7 +10,7 @@
 // with it certifies exactly the corruption a line-surgery transformer
 // produces. `yaml` v2 refuses duplicate keys (DUPLICATE_KEY) and the other
 // malformations a lenient parse glosses — e.g. a `: ` inside an unquoted
-// scalar (`path: (none — tel: URL)`), which no pattern rule catches.
+// scalar (`path: (none — see: docs)`), which no pattern rule catches.
 //
 // Scope: the YAML files git TRACKS (`*.yaml`, `*.yml`) — the repo's sources,
 // not build output or dependencies. Outside a git work tree there is no

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.4.0",
+  "built_against_sdd_cli": "1.45.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
@@ -17,8 +18,10 @@ export function registerSync(program) {
         .option("--allow-overwrite", "accept overwrites of locally-modified method content")
         .option("--no-delete", "preserve files removed upstream")
         .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-binding <host>", `CI host whose wrapper calls the Method Validation module (M-ADR 0219): ${CI_BINDINGS.join(", ")}. local writes the module and no wrapper, for an estate that runs it with dagger call on its own machines, and removes the wrapper this tool wrote for the previous binding while it is unedited. 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.4.0",
+  "built_against_sdd_cli": "1.45.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/maintain-cli",
-  "version": "0.2.0",
-  "sddCliVersion": "1.43.0",
+  "version": "0.4.0",
+  "sddCliVersion": "1.45.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"
   },