@sdd-method/maintain-cli 0.1.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/README.md

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

package/dist/lib/agent-harness.js

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

package/dist/lib/briefing/index.js

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

package/dist/lib/briefing/render.js

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

package/dist/lib/catalogue/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/aggregation-manifest-loader.js

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

package/dist/lib/catalogue/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/freshness.js

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

package/dist/lib/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"')],