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

package/dist/lib/context-pull/index.js

@@ -0,0 +1,191 @@
+/**
+ * `sdd-cli context pull` — write the code-repo briefing into a code repository from its upstream
+ * SDD (M-ADR 0220 §4.5, re-homing M-ADR 0150 §4.4 Phase D).
+ *
+ * The successor to the code-repo half of `generate-claude-md.sh`. No dynamic content is baked
+ * in: the briefing points at the SDD's files. A sibling verb to `generate-briefing`, not an extension of it:
+ * `generate-briefing` needs the target to be an SDD (marker, lock, synced
+ * templates), and a code repository is none of those. They share the
+ * placeholder substitution and the wrapper's marker-block merge.
+ *
+ * What it writes, and nothing else (M-ADR 0218 §4.3 item 9, a MAINTAIN verb):
+ *   agent-instructions.md   whole file, method-managed
+ *   CLAUDE.md, AGENTS.md    the method-managed block only; adopter content survives (AGENTS.md is
+ *                           the pointer, M-ADR 0220 §4.6, when the SDD's baseline carries it)
+ * Templates are read from the SDD, which carries them via its baseline bundle. MCP_SETUP.md is no
+ * longer written (M-ADR 0220 §4.5); a copy this verb wrote earlier is removed when it still
+ * matches the method's last render, and left with a notice when it does not.
+ */
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { AGENT_INSTRUCTIONS_REL_PATH, AGENTS_POINTER, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, findUnresolvedPlaceholders, harnessWrapperOutputPath, resolveBriefingVariables, splitWrapperTemplate, } from "../briefing/index.js";
+import { readLockFile } from "../lock-file.js";
+import { readRepoKind } from "../repo-kind.js";
+import { writeMarkedBlockFile } from "../sync/yaml-block-merge.js";
+import { defaultSearchRoots, resolveCodeRepoName, resolveSdd } from "./resolve.js";
+import { RETIRED_MCP_SETUP_TEMPLATE } from "./retired-mcp-setup.js";
+export const CODE_REPO_BRIEFING_ROOT = "orchestration/templates/briefing/code-repo";
+export const MCP_SETUP_REL_PATH = "MCP_SETUP.md";
+const WRAPPER_TEMPLATE = {
+    "claude-code": "claude-code/CLAUDE.md.hbs",
+};
+export async function runContextPull(opts, out = (line) => process.stdout.write(line)) {
+    const codeRepo = resolve(opts.codeRepo);
+    if ((await readRepoKind(codeRepo)) !== null) {
+        out(fail(`${codeRepo} is an SDD repository (it has .sdd-repo-kind). context pull writes into a code repository; for an SDD use sdd-cli generate-briefing.`));
+        return { exitCode: 1 };
+    }
+    const repoName = resolveCodeRepoName(codeRepo, opts.repoName);
+    const outcome = await resolveSdd({
+        repoName,
+        sddPath: opts.sddPath,
+        searchRoots: opts.searchRoots ?? defaultSearchRoots(codeRepo),
+        codeRepo,
+    });
+    if (outcome.kind === "not-an-sdd") {
+        out(fail(`--sdd ${outcome.path} is not an SDD repository (no .sdd-repo-kind).`));
+        return { exitCode: 1 };
+    }
+    if (outcome.kind === "not-found") {
+        out(fail(`No SDD lists repository "${repoName}" in its catalogues/repositories.csv (searched ${outcome.searched.length} SDD(s) under ${(opts.searchRoots ?? defaultSearchRoots(codeRepo)).join(", ")}). Pass --sdd <path>, or --repo <id> if this repository is catalogued under another id.`));
+        return { exitCode: 1 };
+    }
+    if (outcome.kind === "ambiguous") {
+        out(fail(`Repository "${repoName}" is listed by ${outcome.candidates.length} SDDs: ${outcome.candidates.join(", ")}. Pass --sdd <path> to choose.`));
+        return { exitCode: 1 };
+    }
+    const sddRoot = outcome.sddRoot;
+    if (!outcome.catalogued) {
+        out(warn(`${basename(sddRoot)}'s catalogues/repositories.csv does not list "${repoName}"; continuing because --sdd was given.`));
+    }
+    // The SDD's own identity, profile and baseline, exactly as its own briefing renders them.
+    const lock = await readLockFile(sddRoot);
+    const forwardBase = lock?.bundles.find((b) => b.isForwardBase);
+    if (!forwardBase) {
+        out(fail(`${sddRoot} has no forward-base bundle in method-baseline.lock; sync it first.`));
+        return { exitCode: 1 };
+    }
+    const sdd = await resolveBriefingVariables({ targetRepo: sddRoot, baselineVersionOverride: forwardBase.bundleVersion });
+    const vars = {
+        repo_name: repoName,
+        sdd_name: sdd.sdd_name,
+        sdd_root: sddRoot,
+        repo_kind: sdd.repo_kind,
+        baseline_version: sdd.baseline_version,
+        pull_date: opts.pullDate ?? new Date().toISOString().slice(0, 10),
+    };
+    const aiTemplate = join(sddRoot, CODE_REPO_BRIEFING_ROOT, "agent-instructions.md.hbs");
+    const wrapperTemplate = join(sddRoot, CODE_REPO_BRIEFING_ROOT, WRAPPER_TEMPLATE[opts.agentHarness]);
+    for (const t of [aiTemplate, wrapperTemplate]) {
+        if (!(await exists(t))) {
+            out(fail(`${sddRoot} does not carry ${t.slice(sddRoot.length + 1)}: its method baseline predates context pull. Sync the SDD to a baseline that ships the code-repo templates.`));
+            return { exitCode: 1 };
+        }
+    }
+    // The AGENTS.md pointer (M-ADR 0220 §4.6) arrived later than the other code-repo templates: an SDD
+    // whose baseline does not carry it yet gets no pointer, and everything else proceeds.
+    const pointerTemplate = join(sddRoot, CODE_REPO_BRIEFING_ROOT, AGENTS_POINTER.templateRel);
+    const wrapperSources = [[harnessWrapperOutputPath(opts.agentHarness), wrapperTemplate]];
+    if (await exists(pointerTemplate))
+        wrapperSources.push([AGENTS_POINTER.outputRel, pointerTemplate]);
+    const rendered = {};
+    for (const [rel, path] of [[AGENT_INSTRUCTIONS_REL_PATH, aiTemplate], ...wrapperSources]) {
+        const content = substituteAll(await readFile(path, "utf8"), vars);
+        const unresolved = findUnresolvedPlaceholders(content);
+        if (unresolved.length > 0) {
+            out(fail(`${rel}: the SDD's template has placeholders this CLI does not know: ${unresolved.join(", ")}. Upgrade sdd-cli.`));
+            return { exitCode: 1 };
+        }
+        rendered[rel] = content;
+    }
+    // The wrappers first: they are the only writes that can be refused, and a refusal must leave
+    // nothing written, so every wrapper is checked before any is written.
+    const existingOf = {};
+    for (const [rel] of wrapperSources) {
+        const path = join(codeRepo, rel);
+        const existing = (await exists(path)) ? await readFile(path, "utf8") : null;
+        existingOf[rel] = existing;
+        const hasMarkers = existing !== null && existing.includes(WRAPPER_BLOCK_BEGIN) && existing.includes(WRAPPER_BLOCK_END);
+        if (existing !== null && !hasMarkers && !opts.allowOverwrite) {
+            // No markers: a pre-briefing-layer file (the bash generator wrote these whole) or adopter-authored.
+            out(fail(`${rel} exists without method-managed markers, so it is treated as adopter-authored. Nothing was written. Re-run with --allow-overwrite to replace it with the rendered wrapper (move anything worth keeping below its markers afterwards).`));
+            return { exitCode: 1 };
+        }
+    }
+    const changed = [];
+    for (const [rel] of wrapperSources) {
+        const path = join(codeRepo, rel);
+        const existing = existingOf[rel] ?? null;
+        const hasMarkers = existing !== null && existing.includes(WRAPPER_BLOCK_BEGIN) && existing.includes(WRAPPER_BLOCK_END);
+        if (existing !== null && !hasMarkers) {
+            await writeFile(path, rendered[rel], "utf8");
+            if (existing !== rendered[rel])
+                changed.push(rel);
+            continue;
+        }
+        const parts = splitWrapperTemplate(rendered[rel]);
+        const merge = await writeMarkedBlockFile(path, existing === null ? rendered[rel] : parts.block, { begin: WRAPPER_BLOCK_BEGIN, end: WRAPPER_BLOCK_END }, opts.allowOverwrite, existing === null ? undefined : { pre: parts.pre, post: parts.post });
+        if (merge.changed)
+            changed.push(rel);
+    }
+    for (const rel of [AGENT_INSTRUCTIONS_REL_PATH]) {
+        const path = join(codeRepo, rel);
+        const before = (await exists(path)) ? await readFile(path, "utf8") : null;
+        if (before !== rendered[rel]) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, rendered[rel], "utf8");
+            changed.push(rel);
+        }
+    }
+    const mcpSetup = await retireMcpSetup(codeRepo);
+    out(info(`Code repo "${repoName}" is specified by ${sdd.sdd_name} (${sdd.repo_kind}, ${sdd.baseline_version}) at ${sddRoot}.`));
+    out(info(changed.length > 0 ? `Wrote ${changed.join(", ")}.` : `Already current: ${[AGENT_INSTRUCTIONS_REL_PATH, ...wrapperSources.map(([rel]) => rel)].join(", ")}.`));
+    if (mcpSetup === "removed")
+        out(info(`Removed ${MCP_SETUP_REL_PATH}: the method no longer ships it (M-ADR 0220), and this copy was unedited.`));
+    if (mcpSetup === "kept")
+        out(info(`${MCP_SETUP_REL_PATH} is no longer written (M-ADR 0220). This copy differs from the method's last render, so it was left; delete it if nothing in it is yours.`));
+    return { exitCode: 0 };
+}
+/**
+ * Remove an MCP_SETUP.md this verb wrote before M-ADR 0220, when it is byte-identical to the
+ * method's last template rendered with the values its own header records. Anything else is the
+ * adopter's now, and stays.
+ */
+export async function retireMcpSetup(codeRepo) {
+    const path = join(codeRepo, MCP_SETUP_REL_PATH);
+    if (!(await exists(path)))
+        return "absent";
+    const text = await readFile(path, "utf8");
+    const repo = /^\* \*\*Emitted by:\*\* `sdd-cli context pull`, for code repo `([^`]*)`$/m.exec(text);
+    const upstream = /^\* \*\*Upstream SDD:\*\* `([^`]*)` at `([^`]*)`$/m.exec(text);
+    const baseline = /^\* \*\*Baseline version:\*\* `([^`]*)`$/m.exec(text);
+    if (!repo || !upstream || !baseline)
+        return "kept";
+    const render = substituteAll(RETIRED_MCP_SETUP_TEMPLATE, {
+        repo_name: repo[1],
+        upstream_sdd_name: upstream[1],
+        sdd_root: upstream[2],
+        sdd_method_baseline_version: baseline[1],
+    });
+    if (render !== text)
+        return "kept";
+    await rm(path);
+    return "removed";
+}
+/** `{{name}}` substitution over an open variable set (the briefing renderer's is closed to four). */
+export function substituteAll(template, vars) {
+    return template.replace(/\{\{\s*([a-z_][a-z0-9_]*)\s*\}\}/g, (full, key) => (key in vars ? vars[key] : full));
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const info = (m) => `[INFO] ${m}\n`;
+const warn = (m) => `[WARN] ${m}\n`;
+const fail = (m) => `[FAIL] ${m}\n`;
+//# sourceMappingURL=index.js.map

package/dist/lib/context-pull/resolve.js

@@ -0,0 +1,70 @@
+/**
+ * Code-repo SDD-source resolution for `sdd-cli context pull` (M-ADR 0128 §1,
+ * M-ADR 0150 §4.4 Phase D).
+ *
+ * A code repository has no `.sdd-repo-kind`, no lock and no bundle, so nothing
+ * in it names the SDD that specifies it. The SDD names the code repository
+ * instead: every repository it owns is a row in its own
+ * `catalogues/repositories.csv`, keyed by id. Resolution is therefore a lookup
+ * in that direction: find the SDD whose catalogue lists this repository.
+ *
+ * Only the SDD's OWN catalogue counts, never `catalogues-aggregated/`: a
+ * platform root's aggregate lists every member's repositories too, so reading
+ * it would make every code repo resolve to two SDDs.
+ */
+import { access } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { basename, dirname, join, resolve } from "node:path";
+import { readCatalogueCsv } from "../catalogue/csv-reader.js";
+import { discoverSddRepos } from "../list/discover.js";
+import { readRepoKind } from "../repo-kind.js";
+export const REPOSITORIES_CATALOGUE = "catalogues/repositories.csv";
+/** The code repository's id: `--repo` when given, else its git top-level's directory name. */
+export function resolveCodeRepoName(codeRepo, override) {
+    if (override !== undefined && override.trim() !== "")
+        return override.trim();
+    const top = spawnSync("git", ["-C", codeRepo, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    if (top.status === 0 && top.stdout.trim() !== "")
+        return basename(top.stdout.trim());
+    return basename(resolve(codeRepo));
+}
+/** Does this SDD's own repositories catalogue list `repoName`? */
+export async function catalogueListsRepo(sddRoot, repoName) {
+    const path = join(sddRoot, REPOSITORIES_CATALOGUE);
+    try {
+        await access(path);
+    }
+    catch {
+        return false;
+    }
+    const { rows } = await readCatalogueCsv(path);
+    return rows.some((r) => r["id"] === repoName);
+}
+export async function resolveSdd(opts) {
+    if (opts.sddPath !== undefined) {
+        const root = resolve(opts.sddPath);
+        if ((await readRepoKind(root)) === null)
+            return { kind: "not-an-sdd", path: root };
+        // An explicit --sdd is the caller's assertion, so an uncatalogued repository is reported
+        // (the caller may be wiring a repository the SDD has not catalogued yet), not refused.
+        return { kind: "resolved", sddRoot: root, catalogued: await catalogueListsRepo(root, opts.repoName) };
+    }
+    const self = resolve(opts.codeRepo);
+    const found = await discoverSddRepos(opts.searchRoots);
+    const searched = found.map((r) => r.path).filter((p) => resolve(p) !== self);
+    const matches = [];
+    for (const p of searched) {
+        if (await catalogueListsRepo(p, opts.repoName))
+            matches.push(p);
+    }
+    if (matches.length === 1)
+        return { kind: "resolved", sddRoot: matches[0], catalogued: true };
+    if (matches.length === 0)
+        return { kind: "not-found", searched };
+    return { kind: "ambiguous", candidates: matches };
+}
+/** Default discovery root: the directory holding the code repository. */
+export function defaultSearchRoots(codeRepo) {
+    return [dirname(resolve(codeRepo))];
+}
+//# sourceMappingURL=resolve.js.map

package/dist/lib/context-pull/retired-mcp-setup.js

@@ -0,0 +1,7 @@
+/**
+ * The last MCP_SETUP.md template the method shipped (sdd-method 52bbc36), kept so `context pull`
+ * can tell a copy it wrote from one an adopter edited after M-ADR 0220 §4.5 retired the file.
+ * The SDD's own baseline stops carrying the template, so the comparison cannot read it from there.
+ */
+export const RETIRED_MCP_SETUP_TEMPLATE = "# MCP_SETUP.md\n\n* **Source:** sdd-method-baseline\n* **Emitted by:** `sdd-cli context pull`, for code repo `{{repo_name}}`\n* **Upstream SDD:** `{{upstream_sdd_name}}` at `{{sdd_root}}`\n* **Baseline version:** `{{sdd_method_baseline_version}}`\n\nThis file is **method-shipped guidance for agents working in this code repo**. It tells the agent how to reach the upstream SDD's live context via MCP. Read it alongside `agent-instructions.md` at session start.\n\nPer M-ADR 0150 (MCP as the primary dynamic-context layer), the **primary dynamic-context surface** for this code repo is the upstream SDD's MCP server, not baked-in snapshot content. Prefer MCP queries over reading static files for anything that might have changed since the last `sdd-cli context pull`.\n\n## \u00a71 What MCP gives you here\n\nThis code repo (`{{repo_name}}`) consumes specifications from the upstream SDD `{{upstream_sdd_name}}`. The upstream SDD exposes a read-only MCP server (`sdd-mcp`) you can query for:\n\n* **Catalogue rows** \u2014 current capability inventory, service registry, contract list, feature tree, cross-SDD edges.\n* **Gate state** \u2014 lock-in recommendations, intent-quality scores, domain-architecture scores, contract-quality scores per capability.\n* **Plan progress** \u2014 active plans, phases shipped, deferred follow-ups.\n* **Spec lookups** \u2014 ADRs, capability specs, feature specs, traceability manifests.\n\nThe static briefing in this repo (`agent-instructions.md` and the harness wrapper) covers conventions and orientation that are stable across syncs. Anything that changes faster than syncs run \u2014 gate state, catalogue rows, lock-in status \u2014 belongs behind MCP.\n\n## \u00a72 Server identity\n\n* **Server name:** `sdd-mcp`\n* **Upstream SDD path:** `{{sdd_root}}`\n* **Transport:** stdio (per M-ADR 0128's three-MCP-server commitment)\n\n`{{sdd_root}}` is where the SDD was checked out when this file was written; adjust it if your checkout differs. The MCP server resolves the SDD root with this precedence (per sdd-cli):\n\n1. `SDD_REPO_PATH` environment variable.\n2. `--sdd-repo <path>` flag on `sdd-cli mcp serve`.\n3. A platform SDD serves itself: when the git root's own `.sdd-repo-kind` reads `platform-product`, that repository is the SDD, whatever its siblings carry (so a platform repo needs no `SDD_REPO_PATH`).\n4. Sibling-directory auto-discovery from the code repo.\n\n## \u00a73 Harness wiring\n\n### Claude Code (reference)\n\nAdd this fragment to `.claude/settings.json` in this code repo. If the SDD is checked out in a sibling directory, discovery finds it and the `--sdd-repo` argument can be dropped:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"sdd-mcp\": {\n      \"command\": \"sdd-cli\",\n      \"args\": [\"mcp\", \"serve\", \"--sdd-repo\", \"{{sdd_root}}\"]\n    }\n  }\n}\n```\n\nVerify the wiring: open this code repo in Claude Code; in a session, ask the agent \"list available MCP resources\". You should see `sdd://` URIs from `sdd-mcp`.\n\n### GitHub Copilot CLI\n\nCopilot CLI's MCP wiring uses `.github/copilot/mcp.json` (verify against the current Copilot CLI docs at the time of setup; this surface is evolving). Equivalent shape:\n\n```jsonc\n{\n  \"servers\": {\n    \"sdd-mcp\": {\n      \"command\": \"sdd-cli\",\n      \"args\": [\"mcp\", \"serve\", \"--sdd-repo\", \"{{sdd_root}}\"]\n    }\n  }\n}\n```\n\n### Other harnesses\n\nFor any other harness (OpenAI Codex CLI, OpenCode, a generic-stdio harness, or custom in-house): follow the adopter-responsibility flow per M-ADR 0141 \u00a74.5. Read the portable contract of each MCP resource (in the upstream SDD's `docs/method/methods/`) and instantiate against your harness's native MCP-client interface. Document the wiring in an adopter-side ADR or guide.\n\n## \u00a74 Resource surface \u2014 quick reference\n\nThe upstream `sdd-mcp` server exposes resources keyed by `sdd://` URIs. The most relevant for code-repo agents:\n\n| URI pattern | Returns | Typical use |\n|---|---|---|\n| `sdd://catalogue/{name}` | All rows from one catalogue (e.g. `services`, `capabilities`, `features`, `contracts`) | Discover what exists in the SDD |\n| `sdd://catalogue/metamodel` | The catalogue metamodel doc | Understand the entity / edge model |\n| `sdd://catalogue/schema` | Parsed schema (entities + columns + FK constraints) | Reason about data shape |\n| `sdd://gates/{gate}` | Current gate state per capability | Check whether your dependency has locked in |\n| `sdd://specs/{path}` | Spec content lookup | Read a specific feature / capability spec by ID |\n| `sdd://adrs/{id}` | ADR content + metadata | Cross-reference architectural decisions |\n\nNewly-added resource families ship via baseline sync; consult the upstream SDD's MCP setup docs for the current list.\n\nTools (callable via MCP `tools/call`): `find_producers`, `find_consumers`, `find_consumers_of_contract`, `find_dependencies`, `find_dependents`, `cascade_impact`, `query_edges_for_entity`, `find_orphan_rows`, `query_catalogue_coverage`, `find_products_by_category`, `find_related_specs`, `search_specs`, `list_adrs`, `query_gate_status`. Ask the server for `tools/list` for each tool's arguments.\n\n## \u00a75 Troubleshooting\n\n**`sdd-mcp` unreachable / \"Connection refused\"**\nThe MCP server is launched on-demand by the harness; if it isn't starting, check:\n1. `sdd-cli` is installed and on `$PATH` (`which sdd-cli` should resolve).\n2. The harness's MCP config exists and points at `sdd-cli mcp serve`.\n3. The `--sdd-repo` path (or the sibling the server discovers) is a real SDD root.\n\n**\"SDD root not found\" or \"manifest missing\"**\nThe SDD path doesn't resolve to a valid SDD. The path should contain `.sdd/sdd-manifest.yaml` (or the legacy `docs/method/foundations/` layout).\n\n**Version mismatch on resources**\nSome resource families require a minimum `sdd-cli` version. Check `npm list -g @sdd-method/sdd-cli`; upgrade via `npm install -g @sdd-method/sdd-cli@latest` if a resource returns \"unsupported by this server version\".\n\n**Permission denied**\nFor adopter-scoped resources (per M-ADR 0130), `platform-mcp` / `partner-mcp` enforce scope. If you're hitting permission errors, confirm you're querying the right MCP server for the resource (operator scope vs partner scope).\n\n## \u00a76 Fallback semantics \u2014 no silent stale-data\n\nIf `sdd-mcp` is unreachable for any reason, **the agent must report the error and continue with whatever static context exists in this code repo** \u2014 `CLAUDE.md` snapshot + the orientation in this file. **There is no silent fallback to stale baked-in dynamic state.** Per M-ADR 0128 \u00a71, falling back to stale data re-introduces exactly the problem MCP exists to fix.\n\nIf MCP-served dynamic context is unavailable, surface this back to the user explicitly. The user can choose to:\n\n* Proceed without dynamic context (accept the limitation).\n* Restart the MCP server / fix the connection.\n* Re-run `sdd-cli context pull` for a fresh static briefing, acknowledging it is still a point-in-time read.\n\n## Cross-references\n\n* Upstream SDD: `{{sdd_root}}`\n* M-ADR 0128 (MCP live-query infrastructure)\n* M-ADR 0150 (MCP as primary dynamic-context layer)\n* M-ADR 0130 (adopter MCP composition pattern \u2014 `platform-mcp` / `partner-mcp`)\n* M-ADR 0148 (the static-briefing layer this file complements)\n\n---\n\n<!-- This file is rewritten whole by sdd-cli context pull. Put repo-specific MCP guidance in the harness wrapper, below its method-managed markers. -->\n";
+//# sourceMappingURL=retired-mcp-setup.js.map

package/dist/lib/contracts-availability/index.js

@@ -0,0 +1,267 @@
+/**
+ * Contract availability manifest (M-ADR 0202).
+ *
+ * `.sdd/contract-availability.yaml` — the committed attestation that lets an
+ * instrument distinguish "absent because wrong" from "absent because not
+ * checked out" when an SDD references contract artefacts living in sibling
+ * repositories (the M-ADR 0110 contracts-* pattern).
+ *
+ * Two modes, per the format spec (docs/method/foundations/
+ * contract-availability-manifest.md in the method baseline):
+ *   --refresh  runs where siblings ARE checked out: resolves every collected
+ *              reference, writes/updates entries with content digest and
+ *              repo@commit coordinate. Preserves entries it cannot currently
+ *              see (still referenced, artefact absent here); drops entries no
+ *              longer referenced anywhere, and says so.
+ *   --verify   runs anywhere: present artefacts are digest-compared (drift);
+ *              absent-but-attested is satisfied; referenced-but-unattested-
+ *              and-absent is the failure class.
+ *
+ * References are collected from BOTH observed forms (M-ADR 0200 §4.5 — read
+ * what the estate writes):
+ *   1. traceability.contracts declarations (string and object entries), when
+ *      the declared path does not resolve inside the repo;
+ *   2. markdown links under docs/ whose target escapes the repo root.
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { parse as parseYaml } from "yaml";
+import { loadTraceabilityManifests } from "../catalogue/traceability-loader.js";
+import { FindingsLog } from "../catalogue/findings.js";
+const execFile = promisify(execFileCb);
+export const AVAILABILITY_MANIFEST_REL_PATH = ".sdd/contract-availability.yaml";
+export async function runAttest(opts) {
+    const log = [];
+    const repo = resolve(opts.targetRepo);
+    const codeRoot = resolve(opts.codeRoot ?? join(repo, ".."));
+    const manifestAbs = join(repo, AVAILABILITY_MANIFEST_REL_PATH);
+    const refs = await collectReferences(repo);
+    const existing = await readManifest(manifestAbs);
+    const existingByPath = new Map(existing.map((e) => [e.path, e]));
+    const refSet = new Set(refs.map((r) => r.ref));
+    if (opts.mode === "refresh") {
+        const entries = [];
+        const unresolvable = [];
+        const preserved = [];
+        for (const r of refs) {
+            const abs = resolveRef(r, repo, codeRoot);
+            if (abs !== null) {
+                entries.push(await attestOne(r.ref, abs));
+            }
+            else if (existingByPath.has(r.ref)) {
+                // Still referenced; artefact not visible from this machine. Keep the
+                // prior attestation rather than silently discarding evidence this
+                // run cannot re-establish.
+                entries.push(existingByPath.get(r.ref));
+                preserved.push(r.ref);
+            }
+            else {
+                unresolvable.push(r.ref);
+            }
+        }
+        const dropped = existing.filter((e) => !refSet.has(e.path)).map((e) => e.path);
+        await writeManifest(manifestAbs, entries);
+        log.push(`references collected: ${refs.length}`);
+        log.push(`attested: ${entries.length - preserved.length}`);
+        report(log, "preserved (referenced; artefact not visible here)", preserved);
+        report(log, "unresolvable on this machine (NOT attested)", unresolvable);
+        report(log, "dropped (no longer referenced anywhere)", dropped);
+        return { exitCode: 0, log };
+    }
+    // verify
+    const drift = [];
+    const attestedAbsent = [];
+    const presentClean = [];
+    const stale = [];
+    for (const e of existing) {
+        if (!refSet.has(e.path)) {
+            stale.push(e.path);
+            continue;
+        }
+        const abs = resolveRefPath(e.path, repo, codeRoot);
+        if (abs === null) {
+            attestedAbsent.push(e.path);
+            continue;
+        }
+        const digest = await sha256File(abs);
+        if (digest === e.sha256)
+            presentClean.push(e.path);
+        else
+            drift.push(`${e.path} (manifest ${e.sha256.slice(0, 12)}… vs present ${digest.slice(0, 12)}…)`);
+    }
+    const unattested = refs
+        .filter((r) => !existingByPath.has(r.ref) && resolveRef(r, repo, codeRoot) === null)
+        .map((r) => r.ref);
+    log.push(`entries: ${existing.length}, references: ${refs.length}`);
+    report(log, "present and clean", presentClean);
+    report(log, "attested (absent here, satisfied by manifest)", attestedAbsent);
+    report(log, "DRIFT (present artefact disagrees with attestation)", drift);
+    report(log, "UNATTESTED (referenced, absent, no entry)", unattested);
+    report(log, "stale entries (no longer referenced — remove)", stale);
+    const exitCode = drift.length > 0 || unattested.length > 0 ? 1 : 0;
+    return { exitCode, log };
+}
+async function collectReferences(repo) {
+    const out = new Map();
+    // 1. traceability.contracts declarations that do not resolve in-repo.
+    const manifests = await loadTraceabilityManifests({
+        sddPath: repo,
+        findings: new FindingsLog(),
+    });
+    for (const m of manifests) {
+        const block = m.traceability.contracts;
+        if (!block)
+            continue;
+        for (const list of [block.openapi, block.proto, block.avro, block.spicedb]) {
+            if (!Array.isArray(list))
+                continue;
+            for (const entry of list) {
+                const p = typeof entry === "string" ? entry : entry.path;
+                if (typeof p !== "string" || p === "")
+                    continue;
+                if (existsSync(join(repo, p)))
+                    continue;
+                out.set(p, { ref: p });
+            }
+        }
+    }
+    // 2. markdown links under docs/ escaping the repo root.
+    const files = await walkMd(join(repo, "docs"));
+    const LINK = /(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+    for (const f of files) {
+        const txt = await readFile(f, "utf8").catch(() => "");
+        for (const match of txt.matchAll(LINK)) {
+            const raw = decodeURIComponent((match[1] ?? "").split("#")[0] ?? "").trim();
+            if (raw === "" || /^(https?|mailto|tel):/i.test(raw) || raw.startsWith("#"))
+                continue;
+            if (isAbsolute(raw) || raw.includes("{") || raw.includes("<"))
+                continue;
+            const abs = normalize(join(dirname(f), raw));
+            if (!relative(repo, abs).startsWith(".."))
+                continue;
+            out.set(raw, { ref: raw, relTo: dirname(f) });
+        }
+    }
+    return [...out.values()];
+}
+function resolveRef(r, repo, codeRoot) {
+    if (r.relTo !== undefined) {
+        const abs = normalize(join(r.relTo, r.ref));
+        return existsSync(abs) ? abs : null;
+    }
+    return resolveRefPath(r.ref, repo, codeRoot);
+}
+/** Repo-root-relative declaration: in-repo first, then under codeRoot. Doc-relative refs (../…) resolve against repo root's parent chain via normalize. */
+function resolveRefPath(ref, repo, codeRoot) {
+    for (const base of [repo, codeRoot]) {
+        const abs = normalize(join(base, ref));
+        if (existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+async function attestOne(ref, abs) {
+    const sha256 = await sha256File(abs);
+    const source = await sourceCoordinate(abs);
+    const kind = inferKind(ref);
+    return { path: ref, sha256, source, ...(kind ? { kind } : {}) };
+}
+async function sha256File(abs) {
+    const buf = await readFile(abs);
+    return createHash("sha256").update(buf).digest("hex");
+}
+async function sourceCoordinate(abs) {
+    try {
+        const dir = dirname(abs);
+        const { stdout: top } = await execFile("git", ["-C", dir, "rev-parse", "--show-toplevel"]);
+        const { stdout: head } = await execFile("git", ["-C", dir, "rev-parse", "--short", "HEAD"]);
+        const name = top.trim().split(sep).pop() ?? "unknown";
+        return `${name}@${head.trim()}`;
+    }
+    catch {
+        return "unversioned";
+    }
+}
+function inferKind(ref) {
+    if (ref.endsWith(".avsc"))
+        return "event";
+    if (ref.endsWith(".proto"))
+        return "rpc";
+    if (ref.endsWith(".zed"))
+        return "authz";
+    if (/openapi/.test(ref) && /\.(ya?ml|json)$/.test(ref))
+        return "rest";
+    return undefined;
+}
+async function readManifest(abs) {
+    if (!existsSync(abs))
+        return [];
+    const raw = await readFile(abs, "utf8");
+    const doc = parseYaml(raw);
+    if (!doc || !Array.isArray(doc.artefacts))
+        return [];
+    const out = [];
+    for (const a of doc.artefacts) {
+        if (a === null || typeof a !== "object")
+            continue;
+        const o = a;
+        if (typeof o["path"] !== "string" || typeof o["sha256"] !== "string")
+            continue;
+        out.push({
+            path: o["path"],
+            sha256: o["sha256"],
+            source: typeof o["source"] === "string" ? o["source"] : "unversioned",
+            ...(typeof o["kind"] === "string" ? { kind: o["kind"] } : {}),
+        });
+    }
+    return out;
+}
+async function writeManifest(abs, entries) {
+    const sorted = [...entries].sort((a, b) => a.path.localeCompare(b.path));
+    const lines = ['schema_version: "1.0"', "artefacts:"];
+    for (const e of sorted) {
+        lines.push(`  - path: ${JSON.stringify(e.path)}`);
+        lines.push(`    sha256: "${e.sha256}"`);
+        lines.push(`    source: ${JSON.stringify(e.source)}`);
+        if (e.kind)
+            lines.push(`    kind: "${e.kind}"`);
+    }
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, lines.join("\n") + "\n", "utf8");
+}
+async function walkMd(root) {
+    const { readdir } = await import("node:fs/promises");
+    const out = [];
+    async function rec(dir) {
+        let names;
+        try {
+            names = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const d of names) {
+            const p = join(dir, d.name);
+            if (d.isDirectory()) {
+                if (d.name === "node_modules" || d.name === ".git")
+                    continue;
+                await rec(p);
+            }
+            else if (d.name.endsWith(".md"))
+                out.push(p);
+        }
+    }
+    await rec(root);
+    return out;
+}
+function report(log, label, items) {
+    // Count AND list, always (M-ADR 0200 §4.3).
+    log.push(`${label}: ${items.length}`);
+    for (const i of items)
+        log.push(`  - ${i}`);
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/generate-briefing/index.js

@@ -0,0 +1,77 @@
+/**
+ * `sdd-cli generate-briefing` — regenerate `agent-instructions.md` +
+ * the harness wrapper for an existing SDD repo without pulling a
+ * bundle. Reuses the briefing-merge sync helpers so behaviour matches
+ * what `sdd-cli sync` writes (the templates already on disk are the
+ * source of truth).
+ *
+ * Replaces the v0.3.0 `generate-claude-md` verb whose rich-content
+ * output diverges from the ADR 0148 thin-pointer shape.
+ */
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { AGENT_INSTRUCTIONS_REL_PATH, BRIEFING_TEMPLATE_ROOT, harnessWrapperOutputPath, } from "../briefing/index.js";
+import { syncBriefingFiles } from "../sync/briefing-merge.js";
+import { DEFAULT_AGENT_HARNESS, resolveAgentHarness, } from "../agent-harness.js";
+import { readRepoKind } from "../repo-kind.js";
+import { readLockFile } from "../lock-file.js";
+export async function runGenerateBriefing(opts, stdout = (line) => process.stdout.write(line)) {
+    const repoKind = await readRepoKind(opts.targetDir);
+    if (repoKind === null) {
+        stdout(fail(`Not an SDD repo: no .sdd-repo-kind marker in ${opts.targetDir}`));
+        return { exitCode: 1 };
+    }
+    const lock = await readLockFile(opts.targetDir);
+    if (!lock) {
+        stdout(fail(`Cannot regenerate briefing: method-baseline.lock missing at ${opts.targetDir}. Run sdd-cli sync first.`));
+        return { exitCode: 1 };
+    }
+    const forwardBase = lock.bundles.find((b) => b.isForwardBase);
+    if (!forwardBase) {
+        stdout(fail(`Cannot regenerate briefing: no forward-base bundle in method-baseline.lock at ${opts.targetDir}.`));
+        return { exitCode: 1 };
+    }
+    // Templates ship in the bundle and land here on sync. Refusing
+    // up-front when they're absent gives a clearer error than the
+    // graceful skip downstream.
+    const templatesPresent = await fileExists(join(opts.targetDir, BRIEFING_TEMPLATE_ROOT, "agent-instructions.md.hbs"));
+    if (!templatesPresent) {
+        stdout(fail(`Briefing templates not found under ${BRIEFING_TEMPLATE_ROOT}/ — sync against a baseline that ships ADR 0148 templates first.`));
+        return { exitCode: 1 };
+    }
+    const result = await syncBriefingFiles({
+        targetRepo: opts.targetDir,
+        repoKind,
+        baselineVersion: forwardBase.bundleVersion,
+        agentHarness: opts.agentHarness ?? DEFAULT_AGENT_HARNESS,
+        allowOverwrite: opts.allowOverwrite,
+    });
+    if (result.refused) {
+        stdout(fail(`${result.refused} has adopter edits outside the method-managed markers. Re-run with --allow-overwrite to replace the file.`));
+        return { exitCode: 1 };
+    }
+    for (const line of result.log)
+        stdout(info(line));
+    if (result.log.length === 0) {
+        stdout(info(`Briefing files already match templates — no changes (${AGENT_INSTRUCTIONS_REL_PATH}, ${harnessWrapperOutputPath(opts.agentHarness ?? DEFAULT_AGENT_HARNESS)}).`));
+    }
+    return { exitCode: 0 };
+}
+// Re-export so the verb layer can use the validator without an extra import line.
+export { resolveAgentHarness };
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function info(msg) {
+    return `[INFO] ${msg}\n`;
+}
+function fail(msg) {
+    return `[FAIL] ${msg}\n`;
+}
+//# sourceMappingURL=index.js.map