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

package/dist/lib/snapshot/manifest.js

@@ -0,0 +1,206 @@
+// Implementation-set snapshot manifests (`<area>/<baseline-id>/snapshot.yaml`)
+// and the file-level primitives the `snapshot` verbs share.
+//
+// The shape is the method's, not this module's: reverse/artifact-conventions.md
+// "Implementation-Set Snapshots". Where the conventions REQUIRE a companion
+// field (`carried_reason` beside `carried_from`, `reverification` beside
+// `reverified_at`), readManifest refuses a manifest without it — a carried member
+// with no reason cannot be told apart from an unrecorded removal.
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { parse } from "yaml";
+/** The line every later verb prints while a baseline carries unresolved credential findings. */
+export function credentialNotice(m) {
+    const s = m.credential_scan;
+    if (!s || s.result === "clean")
+        return null;
+    return `CREDENTIAL FINDINGS on record for ${m.snapshot_id}: ${s.result} — ${s.disposition ?? "NO DISPOSITION"}`;
+}
+export class SnapshotError extends Error {
+}
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+export function isIsoDate(s) {
+    if (typeof s !== "string" || !DATE.test(s))
+        return false;
+    const d = new Date(`${s}T00:00:00Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === s;
+}
+/** `name-branch@rev` → { stem: "name-branch", revision: "rev" }. */
+export function splitFolder(folder) {
+    const at = folder.lastIndexOf("@");
+    if (at <= 0 || at === folder.length - 1)
+        return null;
+    return { stem: folder.slice(0, at), revision: folder.slice(at + 1) };
+}
+/** Member folders (`*@*` directories) directly under a baseline directory. */
+export async function memberFolders(baselineDir) {
+    const out = [];
+    for (const e of await readdir(baselineDir, { withFileTypes: true })) {
+        if (e.isDirectory() && splitFolder(e.name) !== null)
+            out.push(e.name);
+    }
+    return out.sort();
+}
+/** Dated baseline ids under an area, ascending. */
+export async function baselineIds(areaRoot) {
+    const out = [];
+    for (const e of await readdir(areaRoot, { withFileTypes: true })) {
+        if (e.isDirectory() && isIsoDate(e.name))
+            out.push(e.name);
+    }
+    return out.sort();
+}
+export async function exists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function manifestPath(areaRoot, id) {
+    return join(areaRoot, id, "snapshot.yaml");
+}
+export async function readManifest(areaRoot, id) {
+    const p = manifestPath(areaRoot, id);
+    if (!(await exists(p)))
+        throw new SnapshotError(`no manifest at ${p}`);
+    const raw = parse(await readFile(p, "utf8"));
+    if (raw === null || typeof raw !== "object")
+        throw new SnapshotError(`${p}: not a mapping`);
+    const problems = [];
+    if (raw.snapshot_id !== id)
+        problems.push(`snapshot_id '${String(raw.snapshot_id)}' does not match its folder '${id}'`);
+    if (!isIsoDate(raw.observed_at))
+        problems.push("observed_at must be YYYY-MM-DD");
+    if (typeof raw.implementation !== "string" || raw.implementation === "")
+        problems.push("implementation missing");
+    if (raw.prior_snapshot !== null && raw.prior_snapshot !== undefined && !isIsoDate(raw.prior_snapshot)) {
+        problems.push("prior_snapshot must be a baseline id or null");
+    }
+    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 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 ?? []) {
+        if (m && typeof m === "object") {
+            for (const f of ["canonical_repo_key", "exported_folder_name", "source_revision"]) {
+                if (typeof m[f] === "number")
+                    m[f] = String(m[f]);
+            }
+        }
+    }
+    for (const r of raw.members_removed ?? []) {
+        if (r && typeof r.last_revision === "number")
+            r.last_revision = String(r.last_revision);
+    }
+    for (const [i, m] of (raw.members ?? []).entries()) {
+        const at = `members[${i}] (${m?.canonical_repo_key ?? "?"})`;
+        if (!m?.canonical_repo_key || !m.exported_folder_name || !m.source_revision) {
+            problems.push(`${at}: canonical_repo_key, exported_folder_name and source_revision are required`);
+        }
+        if (m?.carried_from !== undefined && !m.carried_reason)
+            problems.push(`${at}: carried_from requires carried_reason`);
+        if (m?.reverified_at !== undefined && !m.reverification)
+            problems.push(`${at}: reverified_at requires reverification`);
+    }
+    for (const [i, r] of (raw.members_removed ?? []).entries()) {
+        if (!r?.canonical_repo_key || !r.last_revision || !r.reason) {
+            problems.push(`members_removed[${i}]: canonical_repo_key, last_revision and reason are required`);
+        }
+    }
+    if (problems.length > 0)
+        throw new SnapshotError(`${p}:\n  - ${problems.join("\n  - ")}`);
+    return raw;
+}
+/** Where a member's bytes live: its own baseline, or the one it was carried from. */
+export function memberBytesDir(areaRoot, manifest, m) {
+    return join(areaRoot, m.carried_from ?? manifest.snapshot_id, m.exported_folder_name);
+}
+/** relative path → sha256 for every file under a directory. */
+export async function hashTree(root) {
+    const out = new Map();
+    async function walk(dir) {
+        for (const e of await readdir(dir, { withFileTypes: true })) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name === ".git")
+                    continue;
+                await walk(full);
+            }
+            else if (e.isFile()) {
+                const h = createHash("sha256").update(await readFile(full)).digest("hex");
+                out.set(relative(root, full).split(sep).join("/"), h);
+            }
+        }
+    }
+    await walk(root);
+    return out;
+}
+export function diffTrees(before, after) {
+    const added = [];
+    const removed = [];
+    const modified = [];
+    for (const [p, h] of after) {
+        const b = before.get(p);
+        if (b === undefined)
+            added.push(p);
+        else if (b !== h)
+            modified.push(p);
+    }
+    for (const p of before.keys())
+        if (!after.has(p))
+            removed.push(p);
+    return { added: added.sort(), removed: removed.sort(), modified: modified.sort() };
+}
+const BRANCH_SUFFIX = /-(master|main|develop|trunk)$/;
+/**
+ * The repository ids an SDD declares: every `orchestration/repo-config/**\/<id>.yaml` file
+ * name and every id in its built `catalogues/repositories.csv`. Empty when neither exists.
+ */
+export async function knownRepositoryIds(sddPath) {
+    const out = new Set();
+    const walk = async (dir) => {
+        if (!(await exists(dir)))
+            return;
+        for (const e of await readdir(dir, { withFileTypes: true })) {
+            if (e.isDirectory())
+                await walk(join(dir, e.name));
+            else if (/\.ya?ml$/.test(e.name))
+                out.add(e.name.replace(/\.ya?ml$/, ""));
+        }
+    };
+    await walk(join(sddPath, "orchestration", "repo-config"));
+    const csv = join(sddPath, "catalogues", "repositories.csv");
+    if (await exists(csv)) {
+        for (const line of (await readFile(csv, "utf8")).split("\n").slice(1)) {
+            const id = line.split(",")[0]?.trim();
+            if (id)
+                out.add(id);
+        }
+    }
+    return out;
+}
+/**
+ * A canonical_repo_key derived from a folder's stem, checked. Stripping a branch
+ * suffix only works for the four names it knows: a `-_dev` or `-release-1.X` branch
+ * leaves a key that is no repository id, and nothing downstream says so until a
+ * catalogue build cannot resolve it. With the SDD's ids known, such a key is a
+ * PROBLEM naming the nearest id; without them it is marked unverified.
+ */
+export function deriveKey(folder, stem, known) {
+    const key = stem.replace(BRANCH_SUFFIX, "");
+    if (known.size === 0)
+        return { key, unverified: true };
+    if (known.has(key))
+        return { key };
+    const nearest = [...known].filter((id) => stem.startsWith(`${id}-`)).sort((a, b) => b.length - a.length)[0];
+    return {
+        key,
+        problem: `${folder}: derived canonical_repo_key '${key}' is not a repository id of this SDD — ${nearest ? `nearest is '${nearest}' (a branch suffix?): pass --key ${folder}=${nearest}` : `pass --key ${folder}=<repository id>`}`,
+    };
+}
+//# sourceMappingURL=manifest.js.map

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

@@ -0,0 +1,250 @@
+// ADR transitions (R6 item 12) — the bundle-declared rename / withdrawal /
+// reassignment log, applied at sync.
+//
+// Every method-baseline bundle embeds `ADR_TRANSITIONS.yaml`. Its stated purpose:
+// "Adopters apply transitions during sync to keep their inherited ADR set aligned
+// with upstream without manual `git rm` / `git mv` cleanup." 95 transitions ship in
+// each baseline today, so this is live, not theoretical.
+//
+// The bash reference implemented it; sdd-cli did not, and the gap was invisible
+// because the parity oracle it was compared against also predated the feature.
+//
+// WHY REMOVAL-BY-OMISSION IS NOT AN ADEQUATE SUBSTITUTE. Sync already deletes any
+// previously-managed path missing from the incoming bundle, which incidentally makes
+// a rename look right (old path deleted, new path copied). But the three kinds have
+// semantics that differ from delete-and-add in ways that matter:
+//
+//   - rename:       the file should MOVE, so an adopter's local edits travel with it
+//                   and git sees a rename. Delete-plus-copy discards local edits and
+//                   loses the history link. Under `--no-delete` it leaves BOTH paths.
+//   - withdrawal:   the schema is explicit — "do NOT auto-delete the file (the
+//                   adopter may still depend on the decision). Show the
+//                   `adopter_action` text. Sync continues." Removal-by-omission does
+//                   the opposite: it deletes silently. So withdrawn paths must be
+//                   PROTECTED from removal, which is the one place this module has to
+//                   reach into the rest of sync.
+//   - reassignment: an ADR number now means a different decision. There is no file
+//                   operation at all — the only correct behaviour is to say so.
+//
+// Version-gated on the bundle_version previously applied FOR THIS BUNDLE, so a
+// re-sync does not re-announce transitions the adopter has already taken.
+import { access, mkdir, rename } from "node:fs/promises";
+import { dirname, join, posix } from "node:path";
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+const EMPTY = { renames: [], warnings: [], protectedFromRemoval: [], movedPaths: [] };
+/**
+ * Compare a semver-ish pair, tolerating a leading `v`.
+ *
+ * The lock records `bundle_version` as `v1.2.0` while `introduced_in_version` is
+ * written bare (`1.3.0`). The bash implementation carries the same normalisation
+ * with a comment noting that without it "every rename transition is silently
+ * skipped" — worth keeping, because the failure is silent in both languages.
+ */
+export function versionLessThan(a, b) {
+    const parts = (v) => v.replace(/^v/, "").split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const [x, y] = [parts(a), parts(b)];
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d !== 0)
+            return d < 0;
+    }
+    return false;
+}
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the transition plan for this sync.
+ *
+ * @param bundleRootDir  extracted bundle root (holds ADR_TRANSITIONS.yaml)
+ * @param targetRepo     adopter repo root
+ * @param previousVersion bundle_version last applied for THIS bundle, or undefined
+ *                        on a first sync — in which case every transition is in
+ *                        scope, because the adopter has taken none of them.
+ */
+export async function planAdrTransitions(bundleRootDir, targetRepo, previousVersion) {
+    const file = join(bundleRootDir, "ADR_TRANSITIONS.yaml");
+    if (!(await exists(file)))
+        return EMPTY;
+    let raw;
+    try {
+        raw = parseYaml(await readFile(file, "utf8"));
+    }
+    catch {
+        // A malformed transitions file must not block a sync: the payload is still
+        // valid and the adopter's tree is still correct without the cleanup.
+        return { renames: [], warnings: ["ADR_TRANSITIONS.yaml could not be parsed — transitions skipped"], protectedFromRemoval: [], movedPaths: [] };
+    }
+    const list = raw?.transitions;
+    if (!Array.isArray(list))
+        return EMPTY;
+    const renames = [];
+    const rawWarnings = [];
+    const protectedFromRemoval = [];
+    const movedPaths = [];
+    /**
+     * FIRST ADOPTION replays the bundle's whole transition history (ledger §3ae).
+     * 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
+     * version", and there is no last applied version, so nothing is filtered.
+     * One estate met an ancient reassignment as a fresh warning carrying a
+     * colon-form path that read like rename residue to post-wave eyes.
+     *
+     * Labelled rather than suppressed, deliberately: the notices are TRUE, and a
+     * first adopter inheriting a decision that moved slots may still want to know.
+     * What was wrong was their apparent currency, not their content — so the fix
+     * is to say when they happened, not to hide them.
+     */
+    const firstAdoption = previousVersion === undefined || previousVersion === "";
+    for (const entry of list) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const kind = String(entry.kind ?? "");
+        const adrId = String(entry.adr_id ?? "");
+        const introduced = String(entry.introduced_in_version ?? "");
+        // Only what is newer than the last applied version. On a first sync
+        // (previousVersion undefined) nothing is filtered out.
+        if (previousVersion && introduced && !versionLessThan(previousVersion, introduced)) {
+            continue;
+        }
+        switch (kind) {
+            case "move":
+            case "rename": {
+                const fromPath = String(entry.from_path ?? "");
+                const toPath = String(entry.to_path ?? "");
+                if (!fromPath || !toPath)
+                    continue;
+                const label = kind === "move" ? "move" : `ADR ${adrId} rename`;
+                // A rename to itself is a no-op and MUST be silent. Not hypothetical: 92 of
+                // the 93 rename entries shipping today have from_path === to_path, because
+                // the generator derives from_path from the canon name while the bundle's
+                // publish transform has already renamed the file — so by the time the log is
+                // embedded, the two have collapsed. Without this guard every one of those
+                // would find "both paths exist" (they are the same file) and emit a
+                // manual-review warning, burying the real notices in ~92 lines of noise.
+                if (fromPath === toPath)
+                    continue;
+                movedPaths.push({ fromPath, toPath, label });
+                const fromExists = await exists(join(targetRepo, fromPath));
+                const toExists = await exists(join(targetRepo, toPath));
+                if (fromExists && toExists) {
+                    // Both present: the adopter may have copied rather than moved, or has
+                    // content at both names. Renaming over the top could destroy work.
+                    rawWarnings.push(`[${label}] both paths exist in adopter repo; manual review needed: ${fromPath} → ${toPath}`);
+                }
+                else if (fromExists) {
+                    renames.push({ adrId, fromPath, toPath });
+                }
+                // Only `toPath` present → already migrated, nothing to do.
+                break;
+            }
+            case "withdrawal": {
+                const withdrawnPath = String(entry.withdrawn_path ?? "");
+                if (!withdrawnPath)
+                    continue;
+                // Protected regardless of presence: it must not be removed by omission on
+                // this sync even if a concurrent step would otherwise have swept it.
+                protectedFromRemoval.push(withdrawnPath);
+                if (await exists(join(targetRepo, withdrawnPath))) {
+                    const action = String(entry.adopter_action ?? "").trim();
+                    rawWarnings.push(`[ADR ${adrId} withdrawal] ${withdrawnPath} is still present.` +
+                        (action ? ` ${action}` : ""));
+                }
+                break;
+            }
+            case "reassignment": {
+                const newDecision = String(entry.new_decision_path ?? "");
+                rawWarnings.push(`[ADR ${adrId} reassignment] slot now points to a different decision: ${newDecision}`);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    const warnings = firstAdoption
+        ? rawWarnings.map((w) => `${w} — HISTORICAL REPLAY: this transition predates this repo's adoption of the bundle, ` +
+            `so it is a record of what happened, not a change arriving now`)
+        : rawWarnings;
+    return { renames, warnings, protectedFromRemoval, movedPaths };
+}
+const CITATION_LINK = /\]\(([^)\s#]+)(?:#[^)\s]*)?\)/g;
+/**
+ * Citations an adopter's OWN documents still make to a path that moved.
+ *
+ * A move strands its citations, not just the file: one estate held 33 citations
+ * resolving to stale copies and 25 dangling (four gate thresholds resolving to
+ * nothing) after a rubric reorg. Ruled 2026-09-29: report each, never rewrite —
+ * the quiet case (a citation that still resolves, to the wrong copy) is exactly
+ * the one an automatic rewrite could get wrong.
+ *
+ * A citation is the moved path written literally (repo-relative), or a Markdown
+ * link whose target resolves to it from the citing file. Method-managed files are
+ * excluded: the bundle already ships them corrected.
+ */
+export async function findStrandedCitations(targetRepo, moved, managed, trackedTextFiles) {
+    if (moved.length === 0)
+        return [];
+    const out = [];
+    for (const file of trackedTextFiles) {
+        if (managed.has(file))
+            continue;
+        let text;
+        try {
+            text = await readFile(join(targetRepo, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const lines = text.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            for (const m of moved) {
+                let hit = line.includes(m.fromPath);
+                if (!hit && line.includes("](")) {
+                    for (const link of line.matchAll(CITATION_LINK)) {
+                        const target = decodeURIComponent(link[1]);
+                        if (/^[a-z]+:/i.test(target))
+                            continue;
+                        if (posix.normalize(posix.join(posix.dirname(file), target)) === m.fromPath)
+                            hit = true;
+                    }
+                }
+                if (hit) {
+                    out.push(`${file}:${i + 1}: cites ${m.fromPath}, which moved to ${m.toPath} (${m.label}) — update the citation`);
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Apply the planned renames. Uses a real move so an adopter's local edits travel
+ * with the file and git can see a rename, which is the whole point of doing this
+ * rather than letting delete-plus-copy approximate it.
+ */
+export async function applyAdrRenames(plan, targetRepo) {
+    let applied = 0;
+    for (const r of plan.renames) {
+        const from = join(targetRepo, r.fromPath);
+        const to = join(targetRepo, r.toPath);
+        try {
+            await mkdir(dirname(to), { recursive: true });
+            await rename(from, to);
+            applied++;
+        }
+        catch {
+            // A rename that cannot be applied is not fatal: the file-copy phase will
+            // still place the new path, leaving the old one for the adopter to resolve.
+        }
+    }
+    return applied;
+}
+//# sourceMappingURL=adr-transitions.js.map

package/dist/lib/sync/apply.js

@@ -0,0 +1,91 @@
+import { copyFile, mkdir, readdir, rm, rmdir } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+export async function copyManagedFiles(incomingPaths, payloadDir, targetRepo) {
+    for (const p of incomingPaths) {
+        const src = join(payloadDir, p);
+        const dst = join(targetRepo, p);
+        await mkdir(dirname(dst), { recursive: true });
+        await copyFile(src, dst);
+    }
+}
+/**
+ * Withdraw method-managed files, then remove the directories the withdrawal
+ * itself emptied.
+ *
+ * Without the second half, `sync` left the skeleton of everything it had ever
+ * shipped behind: measured 156 empty directories across 13 reverse-estate repos
+ * (12 `docs/method/methods/skills/reverse-*` dirs each, from the v2.3.0 wave
+ * moving reverse skills out of the forward bases). Git does not track empty
+ * directories, so no commit ever carries them and no diff ever shows them —
+ * they are invisible to review and live only in working copies, which is exactly
+ * why they accumulated unnoticed.
+ *
+ * TWO CONDITIONS, and the second is the one that matters. A directory is pruned
+ * only if it is (1) empty, and (2) DERIVED FROM THE WITHDRAWAL SET — that is, it
+ * is an ancestor directory of a path this call actually removed. Emptiness alone
+ * is not sufficient: an adopter's own empty directory that happens to sit beside
+ * the withdrawal tree is not ours to delete, and deleting it would be an
+ * unrecoverable side effect of a sync that was asked only to withdraw files.
+ * The walk stops at the first directory failing either condition, so a parent
+ * that still holds adopter content survives with its remaining entries intact —
+ * the real-world shape being 12 emptied `reverse-*` dirs beside 3 populated
+ * non-reverse skills under one `skills/` parent, where the walk must stop at
+ * `skills/`.
+ *
+ * Returns the pruned directories, repo-relative and deepest-first, so the caller
+ * reports each one. A pruned directory is an action taken on an adopter's tree,
+ * and this codebase does not take silent actions.
+ */
+export async function removeManagedFiles(paths, targetRepo) {
+    for (const p of paths) {
+        await rm(join(targetRepo, p), { force: true });
+    }
+    // Every directory the withdrawal set could legitimately have emptied: each
+    // removed path's ancestor chain, up to but excluding the repo root. Built
+    // from `paths` rather than from the filesystem, so nothing outside what this
+    // call withdrew is ever a candidate.
+    const candidates = new Set();
+    for (const p of paths) {
+        const parts = p.split(/[/\\]/).filter((s) => s !== "" && s !== ".");
+        for (let i = parts.length - 1; i > 0; i--) {
+            candidates.add(parts.slice(0, i).join(sep));
+        }
+    }
+    // Deepest first, so a child is always considered before its parent and a
+    // chain of emptied directories collapses in one pass.
+    //
+    // The name tiebreak is BYTE ORDER, not `localeCompare`, and that is a contract
+    // rather than a preference: `sync-method-baseline.sh` prunes and reports the
+    // same directories, and tests/parity asserts the two produce byte-identical
+    // stdout. `localeCompare` resolves through ICU while the script's `sort`
+    // resolves through glibc — two different collation engines, both sensitive to
+    // the ambient locale, so a byte-identical contract resting on them would pass
+    // or fail by environment. The script pins `LC_ALL=C`; this pins the same order
+    // here, so the tiebreak is defined by the method and not by the machine.
+    const ordered = [...candidates].sort((a, b) => b.split(sep).length - a.split(sep).length ||
+        (a < b ? -1 : a > b ? 1 : 0));
+    const pruned = [];
+    for (const rel of ordered) {
+        const abs = join(targetRepo, rel);
+        let entries;
+        try {
+            entries = await readdir(abs);
+        }
+        catch {
+            continue; // already gone, or never existed
+        }
+        if (entries.length > 0)
+            continue; // adopter content remains — stop here
+        try {
+            await rmdir(abs);
+            pruned.push(rel);
+        }
+        catch {
+            // Racing writer, permissions, or a mount point. A directory we could not
+            // remove is left alone rather than escalated: the files are withdrawn,
+            // which is what the caller asked for.
+        }
+    }
+    return pruned;
+}
+//# sourceMappingURL=apply.js.map

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

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ *   - Harness wrapper (`CLAUDE.md` / `AGENTS.md` / …) — 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, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { AGENT_INSTRUCTIONS_REL_PATH, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, harnessWrapperOutputPath, renderAgentInstructions, renderHarnessWrapper, 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.
+    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 one almost
+        // certainly is too — skip the rest as well.
+        return { log, refused: null };
+    }
+    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}.`);
+    // 2. Harness wrapper — marker-aware merge.
+    const wrapperRender = await renderHarnessWrapper(opts.targetRepo, opts.agentHarness, vars);
+    if (wrapperRender === null) {
+        log.push(`Skipped ${harnessWrapperOutputPath(opts.agentHarness)}: bundle does not ship a wrapper template for ${opts.agentHarness}.`);
+        return { log, refused: null };
+    }
+    if (wrapperRender.unresolved.length > 0) {
+        log.push(`Warning: ${harnessWrapperOutputPath(opts.agentHarness)} has unresolved placeholders: ${wrapperRender.unresolved.join(", ")}`);
+    }
+    const wrapperRel = harnessWrapperOutputPath(opts.agentHarness);
+    const wrapperPath = join(opts.targetRepo, wrapperRel);
+    // 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.
+    const wrapperExists = await fileExists(wrapperPath);
+    const templateParts = splitWrapperTemplate(wrapperRender.content);
+    const incoming = wrapperExists
+        ? templateParts.block
+        : wrapperRender.content;
+    const mergeResult = await writeMarkedBlockFile(wrapperPath, incoming, { begin: WRAPPER_BLOCK_BEGIN, end: WRAPPER_BLOCK_END }, opts.allowOverwrite, wrapperExists
+        ? { pre: templateParts.pre, post: templateParts.post }
+        : undefined);
+    if (mergeResult.refused) {
+        return { log, refused: wrapperRel };
+    }
+    if (mergeResult.changed) {
+        log.push(`Refreshed ${wrapperRel}.`);
+    }
+    return { log, refused: null };
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=briefing-merge.js.map