@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/dist/lib/snapshot/targets.js

@@ -0,0 +1,169 @@
+// `sdd-cli snapshot targets` — route each delta.yaml finding to the SDD
+// artefacts it grounds, recording the GRAIN each route was found at:
+//
+//   file — the artefact cites a changed file's path (feature-grounding style
+//          evidence citing `src/…`): the route is as precise as the citation;
+//   repo — the artefact only names the member's canonical_repo_key: the route
+//          reaches everything that repo grounds, and must not read as precise.
+//
+// Findings whose targets are already set are left alone (routing refined by
+// hand is judgement). Findings nothing cites are listed as unroutable, never
+// dropped. Writes back into delta.yaml preserving everything else in it.
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { parseDocument } from "yaml";
+import { deltaPath } from "./diff.js";
+import { SnapshotError, exists } from "./manifest.js";
+/** Minimal glob → RegExp: `**` any path, `*` within a segment, `?` one character. */
+export function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*" && glob[i + 1] === "*") {
+            re += glob[i + 2] === "/" ? "(?:.*/)?" : ".*";
+            i += glob[i + 2] === "/" ? 2 : 1;
+        }
+        else if (c === "*")
+            re += "[^/]*";
+        else if (c === "?")
+            re += "[^/]";
+        else
+            re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${re}$`);
+}
+const TEXT = /\.(md|ya?ml|json|txt|adoc|mermaid|puml|csv)$/i;
+const SKIP_DIRS = new Set([".git", "node_modules", ".sdd", "catalogues"]);
+const MAX_BYTES = 4 * 1024 * 1024;
+/** Every text artefact of the SDD, excluding the method's own copies and generated catalogues. */
+export async function sddArtefacts(sddPath) {
+    const out = new Map();
+    async function walk(dir) {
+        for (const e of await readdir(dir, { withFileTypes: true })) {
+            const full = join(dir, e.name);
+            const rel = relative(sddPath, full).split(sep).join("/");
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name) || rel === "docs/method")
+                    continue;
+                await walk(full);
+            }
+            else if (e.isFile() && TEXT.test(e.name) && (await stat(full)).size <= MAX_BYTES) {
+                out.set(rel, await readFile(full, "utf8"));
+            }
+        }
+    }
+    await walk(sddPath);
+    return out;
+}
+// A path needs two segments to be a citation rather than a coincidence:
+// `pom.xml` alone appears in every Java SDD.
+const citable = (p) => p.includes("/");
+/**
+ * `shared` holds paths that more than one member changed (`helm/values.yaml`,
+ * `src/main/resources/application.properties`): a citation of one of those names
+ * nobody in particular, so it is file grain only on a line that also names this
+ * member. Without that, a citation of another member's copy reads as precise.
+ */
+export function routeFinding(f, artefacts, shared = new Set()) {
+    const targets = new Map();
+    const paths = [...f.files.added, ...f.files.removed, ...f.files.modified].filter(citable);
+    // The key alone, or in export-folder form (`<key>-master@<rev>`): a hyphen may
+    // follow it only as a branch suffix, so `tcu` never matches inside `tcu-collector`.
+    const keyRe = new RegExp(`(^|[^A-Za-z0-9_-])${f.member.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(-(master|main|develop|trunk)@|[^A-Za-z0-9_-]|$)`);
+    const cites = (text, p) => shared.has(p) ? text.split("\n").some((line) => line.includes(p) && keyRe.test(line)) : text.includes(p);
+    // Folder-qualified — `<key>-<branch>@<rev>/<path>` — names the member AND the file,
+    // so it routes at file grain even for a one-segment path (`…@f504/build.gradle`).
+    const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const all = [...f.files.added, ...f.files.removed, ...f.files.modified];
+    const qualified = (text, p) => new RegExp(`${esc(f.member)}(-(master|main|develop|trunk))?@[0-9a-f]+/${esc(p)}(?![\\w/.-])`).test(text);
+    for (const [rel, text] of artefacts) {
+        const hit = paths.find((p) => cites(text, p)) ?? all.find((p) => qualified(text, p));
+        if (hit)
+            targets.set(rel, { artefact: rel, grain: "file", cited: hit });
+    }
+    for (const [rel, text] of artefacts) {
+        if (!targets.has(rel) && keyRe.test(text))
+            targets.set(rel, { artefact: rel, grain: "repo", cited: f.member });
+    }
+    return [...targets.values()].sort((a, b) => (a.grain === b.grain ? a.artefact.localeCompare(b.artefact) : a.grain === "file" ? -1 : 1));
+}
+/**
+ * Artefacts that mention a changed file by BASENAME only (`CollectorActor.java:49`) —
+ * too ambiguous to route, too likely to matter to drop silently. Reported, not routed.
+ */
+export function basenameOnly(f, artefacts, routed) {
+    const names = [...new Set([...f.files.added, ...f.files.removed, ...f.files.modified].map((p) => p.split("/").pop()))]
+        .filter((b) => /\.[A-Za-z0-9]+$/.test(b) && b.length >= 8);
+    const out = [];
+    for (const [rel, text] of artefacts) {
+        if (!routed.has(rel) && names.some((b) => new RegExp(`(^|[^\\w/.-])${b.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w.-])`).test(text)))
+            out.push(rel);
+    }
+    return out.sort();
+}
+export async function runSnapshotTargets(inputs, write) {
+    const dp = deltaPath(inputs.areaRoot, inputs.id);
+    if (!(await exists(dp))) {
+        write(`REFUSED: no ${dp} — run snapshot diff first\n`);
+        return { exitCode: 1 };
+    }
+    try {
+        const doc = parseDocument(await readFile(dp, "utf8"));
+        const findings = doc.toJS().findings ?? [];
+        const derivedRes = (inputs.derived ?? []).map(globToRegExp);
+        const kindOf = (artefact) => (derivedRes.some((r) => r.test(artefact)) ? "derived" : "spec");
+        const artefacts = await sddArtefacts(inputs.sddPath);
+        const owners = new Map();
+        for (const f of findings) {
+            for (const p of [...(f.files?.added ?? []), ...(f.files?.removed ?? []), ...(f.files?.modified ?? [])]) {
+                if (!owners.has(p))
+                    owners.set(p, new Set());
+                owners.get(p).add(f.member);
+            }
+        }
+        const shared = new Set([...owners].filter(([, m]) => m.size > 1).map(([p]) => p));
+        let routed = 0;
+        let kept = 0;
+        const unroutable = [];
+        const grains = { file: 0, repo: 0, confirmed: 0 };
+        const kinds = { spec: 0, derived: 0 };
+        for (const [i, f] of findings.entries()) {
+            if (Array.isArray(f.targets) && f.targets.length > 0) {
+                kept++;
+                continue;
+            }
+            const t = routeFinding(f, artefacts, shared);
+            const loose = basenameOnly(f, artefacts, new Set(t.filter((x) => x.grain === "file").map((x) => x.artefact)));
+            if (loose.length > 0)
+                write(`${f.id}: ${loose.length} artefact(s) mention a changed file by basename only, not routed at file grain: ${loose.slice(0, 4).join(", ")}${loose.length > 4 ? ", …" : ""}\n`);
+            if (t.length === 0) {
+                unroutable.push(f.id);
+                continue;
+            }
+            for (const x of t) {
+                x.kind = kindOf(x.artefact);
+                grains[x.grain]++;
+                kinds[x.kind]++;
+            }
+            doc.setIn(["findings", i, "targets"], doc.createNode(t));
+            routed++;
+        }
+        await writeFile(dp, doc.toString({ lineWidth: 0 }));
+        write(`${routed} finding(s) routed (${grains.file} file-grain, ${grains.repo} repo-grain target(s)); ${kept} already targeted, left alone; ` +
+            `${unroutable.length} unroutable${unroutable.length ? `: ${unroutable.join(", ")}` : ""}\n` +
+            `targets by kind: ${kinds.spec} spec (re-derive by reading), ${kinds.derived} derived (regenerate)` +
+            `${(inputs.derived ?? []).length === 0 ? " — no --derived globs given, so every target is counted as a spec" : ""}\n`);
+        if (grains.repo > 0) {
+            write("note: a repo-grain target reaches everything that repo grounds — narrow it by hand before re-reversing\n");
+        }
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        if (e instanceof SnapshotError) {
+            write(`REFUSED: ${e.message}\n`);
+            return { exitCode: 1 };
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=targets.js.map

package/dist/lib/snapshot/verify.js

@@ -0,0 +1,91 @@
+// `sdd-cli snapshot verify` — T0 provenance before the diff is trusted
+// (delta-reverse.md §3).
+//
+// Two legs. LOCAL, checked here: each member folder exists, its `@revision`
+// suffix matches source_revision, and where the export kept its `.git`, HEAD is
+// that revision. CANONICAL — that the revision is a real commit on the canonical
+// repo — cannot be proven from an export, so it is supplied: `--confirmed
+// key=<how it was checked>` per member, or one recorded `--waiver` (who, why,
+// date). A member with neither is "cannot assert", which FAILS: could-not-check
+// is never silently checked. The result is written beside the baseline as
+// provenance.yaml, so the waiver travels with the baseline it excuses.
+import { execFile as execFileCb } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { stringify } from "yaml";
+import { SnapshotError, credentialNotice, exists, isIsoDate, memberBytesDir, readManifest, splitFolder } from "./manifest.js";
+const execFile = promisify(execFileCb);
+export async function runSnapshotVerify(inputs, write) {
+    try {
+        const m = await readManifest(inputs.areaRoot, inputs.id);
+        const notice = credentialNotice(m);
+        if (notice)
+            write(`${notice}\n`);
+        const w = inputs.waiver;
+        if (w && (!w.who || !w.why || !isIsoDate(w.date))) {
+            throw new SnapshotError("--waiver needs who=…,why=…,date=YYYY-MM-DD — an unattributed waiver is a skip with a name on it");
+        }
+        // A snapshot with no members has no provenance to assert. Refused before
+        // anything is written: `pass: 0 member(s)` used to be persisted to
+        // provenance.yaml as `result: pass` (empty-set sweep, R2, ruled 2026-09-29).
+        if (m.members.length === 0) {
+            throw new SnapshotError(`${inputs.id} has 0 members — nothing to verify, and an empty verification is not a pass`);
+        }
+        const rows = [];
+        const failures = [];
+        for (const mem of m.members) {
+            const dir = memberBytesDir(inputs.areaRoot, m, mem);
+            let local = "ok";
+            if (!(await exists(dir)))
+                local = `FAIL: ${dir} does not exist`;
+            else if (splitFolder(mem.exported_folder_name)?.revision !== mem.source_revision) {
+                local = `FAIL: folder revision does not match source_revision ${mem.source_revision}`;
+            }
+            else if (await exists(join(dir, ".git"))) {
+                const head = (await execFile("git", ["-C", dir, "rev-parse", "HEAD"])).stdout.trim();
+                if (!head.startsWith(mem.source_revision))
+                    local = `FAIL: .git HEAD ${head} is not ${mem.source_revision}`;
+                else
+                    local = "ok (git HEAD matches)";
+            }
+            const how = inputs.confirmed?.get(mem.canonical_repo_key);
+            const canonical = how ? `confirmed: ${how}` : w ? "waived" : "CANNOT ASSERT";
+            if (local.startsWith("FAIL"))
+                failures.push(`${mem.canonical_repo_key}: ${local}`);
+            if (canonical === "CANNOT ASSERT")
+                failures.push(`${mem.canonical_repo_key}: canonical provenance not confirmed and no waiver`);
+            rows.push({ canonical_repo_key: mem.canonical_repo_key, local, canonical });
+        }
+        for (const k of inputs.confirmed?.keys() ?? []) {
+            if (!m.members.some((x) => x.canonical_repo_key === k))
+                throw new SnapshotError(`--confirmed ${k}: not a member of ${inputs.id}`);
+        }
+        const report = {
+            baseline: inputs.id,
+            verified_at: inputs.today ?? new Date().toISOString().slice(0, 10),
+            result: failures.length === 0 ? (w ? "pass-with-waiver" : "pass") : "fail",
+            ...(w ? { waiver: w } : {}),
+            members: rows,
+        };
+        await writeFile(join(inputs.areaRoot, inputs.id, "provenance.yaml"), stringify(report, { lineWidth: 0 }));
+        for (const r of rows)
+            write(`${r.canonical_repo_key}: local ${r.local}; canonical ${r.canonical}\n`);
+        if (w)
+            write(`WAIVER in force — ${w.who}, ${w.date}: ${w.why}\n`);
+        if (failures.length > 0) {
+            write(`FAIL: ${failures.length} problem(s); written to provenance.yaml\n`);
+            return { exitCode: 1 };
+        }
+        write(`${report.result}: ${rows.length} member(s)\n`);
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        if (e instanceof SnapshotError) {
+            write(`REFUSED: ${e.message}\n`);
+            return { exitCode: 1 };
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=verify.js.map

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

@@ -0,0 +1,106 @@
+/**
+ * Briefing-layer sync per ADR 0148.
+ *
+ * Two files participate, with different semantics:
+ *
+ *   - `agent-instructions.md` — fully method-managed; unconditional
+ *     overwrite on every sync. No marker-aware merge.
+ *   - The wrappers, `CLAUDE.md` and the `AGENTS.md` pointer (M-ADR 0220 §4.6) — partially
+ *     method-managed. The `<!-- method-managed: begin/end -->` block
+ *     is overwritten; adopter content around it survives via the
+ *     existing `writeMarkedBlockFile` machinery (same pattern as
+ *     `.github/workflows/method-validation.yml`). Blank regions
+ *     around the block are scaffold-filled from the template so
+ *     template-shape changes (heading, adopter-guidance scaffold)
+ *     propagate instead of drifting — non-blank adopter regions are
+ *     never touched.
+ *
+ * Both files are rendered from templates that ship in the bundle at
+ * `<target>/orchestration/templates/briefing/...`. Older bundles
+ * pre-dating ADR 0148 won't carry the templates; this module skips
+ * gracefully with a log line in that case.
+ */
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { AGENT_INSTRUCTIONS_REL_PATH, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, briefingWrappers, renderAgentInstructions, renderWrapper, resolveBriefingVariables, splitWrapperTemplate, } from "../briefing/index.js";
+import { writeMarkedBlockFile } from "./yaml-block-merge.js";
+export async function syncBriefingFiles(opts) {
+    const log = [];
+    const vars = await resolveBriefingVariables({
+        targetRepo: opts.targetRepo,
+        repoKindOverride: opts.repoKind,
+        baselineVersionOverride: opts.baselineVersion,
+    });
+    // 1. agent-instructions.md — unconditional overwrite, once no wrapper will refuse.
+    const aiRender = await renderAgentInstructions(opts.targetRepo, vars);
+    if (aiRender === null) {
+        log.push(`Skipped ${AGENT_INSTRUCTIONS_REL_PATH}: bundle does not ship a briefing template (pre-ADR-0148 baseline).`);
+        // If the agent-instructions template is missing the wrapper ones almost
+        // certainly are too — skip the rest as well.
+        return { log, refused: null };
+    }
+    // 2. The wrappers, rendered first so a refusal leaves nothing written. A baseline that does not
+    // ship a wrapper's template (the AGENTS.md pointer arrived with M-ADR 0220) skips that wrapper.
+    const wrappers = [];
+    for (const w of briefingWrappers(opts.agentHarness)) {
+        const render = await renderWrapper(opts.targetRepo, w.templateRel, vars);
+        if (render === null) {
+            log.push(`Skipped ${w.outputRel}: the baseline does not ship ${w.templateRel}.`);
+            continue;
+        }
+        if (render.unresolved.length > 0) {
+            log.push(`Warning: ${w.outputRel} has unresolved placeholders: ${render.unresolved.join(", ")}`);
+        }
+        wrappers.push({ rel: w.outputRel, content: render.content });
+    }
+    if (!opts.allowOverwrite) {
+        for (const w of wrappers) {
+            const existing = await readIfExists(join(opts.targetRepo, w.rel));
+            if (existing !== null && existing !== "" && !(existing.includes(WRAPPER_BLOCK_BEGIN) && existing.includes(WRAPPER_BLOCK_END))) {
+                return { log, refused: w.rel };
+            }
+        }
+    }
+    if (aiRender.unresolved.length > 0) {
+        log.push(`Warning: agent-instructions.md has unresolved placeholders: ${aiRender.unresolved.join(", ")}`);
+    }
+    const aiPath = join(opts.targetRepo, AGENT_INSTRUCTIONS_REL_PATH);
+    await mkdir(dirname(aiPath), { recursive: true });
+    await writeFile(aiPath, aiRender.content, "utf8");
+    log.push(`Refreshed ${AGENT_INSTRUCTIONS_REL_PATH}.`);
+    // 3. Each wrapper — marker-aware merge. Mirror the ci-workflow sync pattern: when the target
+    // file does not yet exist, write the full rendered template (block + adopter section template).
+    // When it exists, write the method-managed block and scaffold-fill blank regions around it from
+    // the template — writeMarkedBlockFile preserves non-blank adopter content verbatim.
+    for (const w of wrappers) {
+        const wrapperPath = join(opts.targetRepo, w.rel);
+        const wrapperExists = await fileExists(wrapperPath);
+        const templateParts = splitWrapperTemplate(w.content);
+        const mergeResult = await writeMarkedBlockFile(wrapperPath, wrapperExists ? templateParts.block : w.content, { begin: WRAPPER_BLOCK_BEGIN, end: WRAPPER_BLOCK_END }, opts.allowOverwrite, wrapperExists ? { pre: templateParts.pre, post: templateParts.post } : undefined);
+        if (mergeResult.refused) {
+            return { log, refused: w.rel };
+        }
+        if (mergeResult.changed) {
+            log.push(`Refreshed ${w.rel}.`);
+        }
+    }
+    return { log, refused: null };
+}
+async function readIfExists(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=briefing-merge.js.map

package/dist/lib/sync/bundle-cache.js

@@ -0,0 +1,109 @@
+import { appendFile, copyFile, mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * Consumer-side bundle cache (ADR 0176 §4.2).
+ *
+ * Every consumed non-forward-base bundle is extracted to
+ * `<targetRepo>/.sdd/bundle-cache/<bundleName>@<version>/` — the
+ * resolution substrate for `sdd-cli scaffold domain --archetype` and
+ * the staging source for materialise-mode paths. The cache directory
+ * is gitignored (ensured at sync time).
+ *
+ * Cache layout per bundle: the bundle's payload tree, verbatim (so
+ * registry.yaml and scaffold-source files sit at their shipped paths).
+ * Stale versions of the same bundle name are pruned on refresh.
+ */
+export const BUNDLE_CACHE_REL = ".sdd/bundle-cache";
+/**
+ * The registry file name (ADR 0176 §4.1) — always cache-only. A bundle may
+ * ship its registry at the payload root or nested (a multi-bundle producer
+ * repo keeps one registry per bundle subtree, e.g. a vertical overlay's
+ * `verticals/fleet/registry.yaml`, because the producer-layout rule forbids
+ * path mapping and the root name can only be claimed once).
+ */
+export const REGISTRY_FILE = "registry.yaml";
+/**
+ * The application-archetype vocabulary file name (M-ADR 0191 §4.2) — always
+ * cache-only, like the registry. Carries the seedless classification
+ * vocabulary a bundle contributes (resolution data, not adopter-editable
+ * content). May sit at the payload root (core layer) or nested (a vertical
+ * overlay's `verticals/<v>/application-archetypes.yaml`), same as the
+ * registry.
+ */
+export const VOCAB_FILE = "application-archetypes.yaml";
+/**
+ * Split a bundle's managed paths into the set to materialise into the
+ * repo tree vs the set that stays cache-only (ADR 0176 §4.3):
+ * scaffold-source-prefixed paths, registry files, and the archetype
+ * vocabulary file are cache-only.
+ */
+export function splitConsumptionModes(managedPaths, scaffoldSourcePaths) {
+    const prefixes = scaffoldSourcePaths ?? [];
+    const materialise = [];
+    const cacheOnly = [];
+    for (const p of managedPaths) {
+        const isScaffoldSource = prefixes.some((prefix) => p.startsWith(prefix));
+        const isRegistry = p === REGISTRY_FILE || p.endsWith(`/${REGISTRY_FILE}`);
+        const isVocab = p === VOCAB_FILE || p.endsWith(`/${VOCAB_FILE}`);
+        if (isScaffoldSource || isRegistry || isVocab) {
+            cacheOnly.push(p);
+        }
+        else {
+            materialise.push(p);
+        }
+    }
+    return { materialise, cacheOnly };
+}
+/**
+ * Extract a bundle's payload into the cache, replacing any previously
+ * cached version of the same bundle name (one cached version per
+ * bundle — the lock pins exactly one).
+ */
+export async function cacheBundle(input) {
+    const cacheRoot = join(input.targetRepo, BUNDLE_CACHE_REL);
+    await prunePreviousVersions(cacheRoot, input.bundleName);
+    const dest = join(cacheRoot, `${input.bundleName}@${input.bundleVersion}`);
+    for (const p of input.managedPaths) {
+        const src = join(input.payloadDir, p);
+        const dst = join(dest, p);
+        await mkdir(dirname(dst), { recursive: true });
+        await copyFile(src, dst);
+    }
+    return dest;
+}
+async function prunePreviousVersions(cacheRoot, bundleName) {
+    let entries;
+    try {
+        entries = await readdir(cacheRoot, { withFileTypes: true });
+    }
+    catch {
+        return; // no cache yet
+    }
+    for (const e of entries) {
+        if (e.isDirectory() && e.name.startsWith(`${bundleName}@`)) {
+            await rm(join(cacheRoot, e.name), { recursive: true, force: true });
+        }
+    }
+}
+/**
+ * Ensure the consumer's .gitignore excludes the bundle cache. Appends
+ * a marked line when absent; leaves adopter content untouched otherwise.
+ */
+export async function ensureCacheGitignored(targetRepo) {
+    const giPath = join(targetRepo, ".gitignore");
+    const line = `${BUNDLE_CACHE_REL}/`;
+    let existing = "";
+    try {
+        existing = await readFile(giPath, "utf8");
+    }
+    catch {
+        // no .gitignore yet — create one below
+    }
+    if (existing.split("\n").some((l) => l.trim() === line || l.trim() === BUNDLE_CACHE_REL)) {
+        return false;
+    }
+    const prefixNewline = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await appendFile(giPath, `${prefixNewline}# sdd-cli bundle cache (ADR 0176) — extracted bundle payloads, not source\n${line}\n`);
+    return true;
+}
+//# sourceMappingURL=bundle-cache.js.map

package/dist/lib/sync/yaml-block-merge.js

@@ -0,0 +1,120 @@
+/**
+ * Merge-aware write for files with `# method-managed: begin/end`
+ * markers. The method block is replaced; content outside the block
+ * (including content above a lone trailing block, or below it, or
+ * both) is preserved verbatim.
+ *
+ * Conflict model (per ADR 0114, narrowed to block scope):
+ *  - If the existing file has no markers, treat it as adopter-authored.
+ *    Refuse to replace unless `allowOverwrite` is true.
+ *  - If the existing file has markers, upsert the block. Lines outside
+ *    the markers survive unchanged.
+ *  - Drift inside the block does not block here — callers compare the
+ *    in-block slice to the incoming slice separately if they need
+ *    refuse-on-drift semantics (see `detectBlockDrift`).
+ */
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export function mergeMarkedBlock(opts) {
+    const existing = opts.existing ?? "";
+    const { begin, end } = opts.markers;
+    const beginIdx = existing.indexOf(begin);
+    const endIdx = existing.indexOf(end, beginIdx === -1 ? 0 : beginIdx);
+    if (existing === "") {
+        return {
+            output: opts.incomingBlock.endsWith("\n")
+                ? opts.incomingBlock
+                : opts.incomingBlock + "\n",
+            refused: false,
+            changed: true,
+            preAdopter: "",
+            postAdopter: "",
+        };
+    }
+    if (beginIdx === -1 || endIdx === -1) {
+        // Existing file has no markers — treat as adopter-authored.
+        if (!opts.allowOverwrite) {
+            return {
+                output: existing,
+                refused: true,
+                changed: false,
+                preAdopter: existing,
+                postAdopter: "",
+            };
+        }
+        // Overwrite: replace the whole file with the method block.
+        return {
+            output: opts.incomingBlock.endsWith("\n")
+                ? opts.incomingBlock
+                : opts.incomingBlock + "\n",
+            refused: false,
+            changed: existing !== opts.incomingBlock,
+            preAdopter: existing,
+            postAdopter: "",
+        };
+    }
+    let preAdopter = existing.slice(0, beginIdx);
+    let postAdopter = existing.slice(endIdx + end.length);
+    if (opts.scaffold?.pre !== undefined && preAdopter.trim() === "") {
+        preAdopter = opts.scaffold.pre;
+    }
+    if (opts.scaffold?.post !== undefined && postAdopter.trim() === "") {
+        postAdopter = opts.scaffold.post;
+    }
+    const output = preAdopter +
+        opts.incomingBlock +
+        (postAdopter.startsWith("\n") ? postAdopter : "\n" + postAdopter);
+    const finalOutput = output.endsWith("\n") ? output : output + "\n";
+    return {
+        output: finalOutput,
+        refused: false,
+        changed: finalOutput !== existing,
+        preAdopter,
+        postAdopter,
+    };
+}
+/**
+ * Detect whether the method block in `existing` differs from the
+ * incoming block. Returns true if the adopter has edited inside the
+ * markers (drift); false if no markers, exact match, or no file.
+ * Callers use this to implement refuse-on-drift policy where desired.
+ */
+export function detectBlockDrift(existing, incomingBlock, markers) {
+    if (!existing)
+        return false;
+    const beginIdx = existing.indexOf(markers.begin);
+    const endIdx = existing.indexOf(markers.end, beginIdx === -1 ? 0 : beginIdx);
+    if (beginIdx === -1 || endIdx === -1)
+        return false;
+    const currentBlock = existing.slice(beginIdx, endIdx + markers.end.length);
+    return currentBlock !== incomingBlock.trimEnd();
+}
+/**
+ * Apply the merge and write the result to disk. Creates the target
+ * directory if absent.
+ */
+export async function writeMarkedBlockFile(absPath, incomingBlock, markers, allowOverwrite, scaffold) {
+    const existing = await tryReadFile(absPath);
+    const result = mergeMarkedBlock({
+        existing,
+        incomingBlock,
+        markers,
+        allowOverwrite,
+        scaffold,
+    });
+    if (!result.refused && result.changed) {
+        await mkdir(dirname(absPath), { recursive: true });
+        await writeFile(absPath, result.output, "utf8");
+    }
+    return result;
+}
+async function tryReadFile(path) {
+    try {
+        await access(path);
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=yaml-block-merge.js.map

package/dist/lib/validate/aggregate.js

@@ -0,0 +1,51 @@
+const WARN_MARKER = "[WARN]";
+// A validator that ran over an EMPTY population says so with an `[N/A]` line
+// and prints no `[PASS]`. Counting it as passed is the vacuous pass the
+// empty-set sweep measured (an empty platform SDD validated `passed=8`); it is
+// counted apart instead (R1, ruled 2026-09-29). Exit codes are unchanged: a
+// run that measured nothing neither passes nor fails the gate — it is named.
+// A script that measured PART of its population prints real `[PASS]` lines,
+// so a stray `[N/A]` on one sub-check never demotes a real pass.
+const NA_LINE = /^\[N\/A\]/m;
+const PASS_LINE = /^\[PASS\]/m;
+export function classifyResult(r, opts) {
+    if (r.status === "skip")
+        return "skipped";
+    if (r.exitCode !== 0)
+        return "failed";
+    const hasWarn = r.stdout.includes(WARN_MARKER);
+    if (opts.strict && hasWarn)
+        return "failed";
+    if (NA_LINE.test(r.stdout) && !PASS_LINE.test(r.stdout))
+        return "not-measured";
+    return hasWarn ? "warned" : "passed";
+}
+export function aggregateResults(results, opts) {
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    let warned = 0;
+    let notMeasured = 0;
+    for (const r of results) {
+        const outcome = classifyResult(r, opts);
+        if (r.status === "run" && r.exitCode === 0 && r.stdout.includes(WARN_MARKER))
+            warned++;
+        if (outcome === "skipped")
+            skipped++;
+        else if (outcome === "failed")
+            failed++;
+        else if (outcome === "not-measured")
+            notMeasured++;
+        else
+            passed++;
+    }
+    return {
+        exitCode: failed > 0 ? 1 : 0,
+        passed,
+        failed,
+        skipped,
+        warned,
+        notMeasured,
+    };
+}
+//# sourceMappingURL=aggregate.js.map