ddduck 0.1.0 → 0.1.2

package/scripts/generate-graph-svg.mjs

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
 
-// Experimental: render generated/graph/model-graph.json to an SVG using the
-// Graphviz WASM engine (@hpcc-js/wasm). Pure JS + WASM, no system binary, so it
-// stays offline and deterministic. A hosted render API (e.g. Kroki) is a
-// possible future fallback but is intentionally not the default.
+/**
+ * Renders generated/graph/model-graph.json to the canonical SVG view
+ * generated/graph/model-graph.svg using the Graphviz WASM engine
+ * (@hpcc-js/wasm): pure JS + WASM, no system binary, so it stays offline and
+ * deterministic. Because rendering is async, init, the operation runner, check,
+ * and query all invoke this script as a child process. Experimental layout
+ * variants (--layout/--all-layouts) land under .ddduck/graph-layouts/, outside
+ * the generated-view contract. A hosted render API (e.g. Kroki) is a possible
+ * future fallback but is intentionally not the default.
+ */
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -15,7 +21,8 @@ export const jsonInputPath = path.join("generated", "graph", "model-graph.json")
 
 // Graphviz layout engines worth comparing for a model graph. `dot` is the
 // hierarchical default; the force-directed and radial engines often read better
-// once the ownership tree gets wide. Output goes to `model-graph.<engine>.svg`.
+// once the ownership tree gets wide. Variant output goes to
+// `.ddduck/graph-layouts/model-graph.<engine>.svg`.
 export const LAYOUT_ENGINES = ["dot", "twopi", "circo", "fdp", "sfdp", "neato"];
 
 // Only `dot` and `fdp` do cluster-aware layout. The other engines still *draw*
@@ -32,8 +39,13 @@ export function engineSupportsClusters(engine) {
 export const svgOutputPath = path.join("generated", "graph", "model-graph.svg");
 export const canonicalEngine = "dot";
 
+// Experimental layout variants (`--layout` / `--all-layouts`) are not part of
+// the generated-view contract: `generated/` holds only the canonical views that
+// `ddduck generate` refreshes and `ddduck check` gates. Variants land in the
+// `.ddduck/` tool-metadata area instead, so they can never rot unswept inside
+// `generated/`.
 export function svgOutputPathFor(engine) {
-  return path.join("generated", "graph", `model-graph.${engine}.svg`);
+  return path.join(".ddduck", "graph-layouts", `model-graph.${engine}.svg`);
 }
 
 // Visual vocabulary keyed by the graph's node/edge `kind`. Shapes and fills are
@@ -214,9 +226,14 @@ function edgeStatements(graphEdge, nodeIds) {
   return [edge(graphEdge.from, graphEdge.to, { ...base, label: graphEdge.label ?? graphEdge.kind })];
 }
 
-// Pure translation from the model graph JSON to a deterministic DOT string.
-// `clusters` groups each domain and its owned nodes into a titled box; disable it
-// for engines that draw but do not lay out clusters (they would overlap).
+/**
+ * Pure translation from the model graph JSON to a deterministic DOT string.
+ * `clusters` groups each domain and its owned nodes into a titled box; disable
+ * it for engines that draw but do not lay out clusters (they would overlap).
+ * @param {{modelId?: string, modelName?: string, nodes?: object[], edges?: object[]}} modelGraph - Parsed model-graph.json.
+ * @param {{clusters?: boolean, legend?: boolean}} [options] - Cluster domains into boxes; emit the legend cluster.
+ * @returns {string} The DOT source.
+ */
 export function graphToDot(modelGraph, { clusters = true, legend = clusters } = {}) {
   const nodes = modelGraph.nodes ?? [];
   const edges = modelGraph.edges ?? [];
@@ -254,9 +271,14 @@ function loadGraphviz() {
   return graphvizInstance;
 }
 
-// Render a DOT string to SVG via the Graphviz WASM engine. `engine` selects the
-// layout algorithm. Isolated so the backend can be swapped without touching the
-// translation above.
+/**
+ * Render a DOT string to SVG via the Graphviz WASM engine. `engine` selects
+ * the layout algorithm. Isolated so the backend can be swapped without
+ * touching the translation above.
+ * @param {string} dot - DOT source from graphToDot.
+ * @param {string} [engine] - One of LAYOUT_ENGINES (default "dot").
+ * @returns {Promise<string>} The rendered SVG.
+ */
 export async function renderDotToSvg(dot, engine = "dot") {
   if (!LAYOUT_ENGINES.includes(engine)) {
     throw new Error(`unknown layout engine ${engine}; expected one of ${LAYOUT_ENGINES.join(", ")}`);
@@ -281,13 +303,22 @@ function writeSvg(rootPath, relativePath, svg) {
   return relativePath;
 }
 
-// Build the canonical diagram bytes (dot, clustered, legend). Shared by the
-// writer and the freshness check so both agree byte-for-byte.
+/**
+ * Build the canonical diagram bytes (dot, clustered, legend). Shared by the
+ * writer and the freshness check so both agree byte-for-byte.
+ * @param {object} modelGraph - Parsed model-graph.json.
+ * @returns {Promise<string>} The canonical SVG bytes.
+ */
 export async function buildModelGraphSvg(modelGraph) {
   const dot = graphToDot(modelGraph, { clusters: true, legend: true });
   return renderDotToSvg(dot, canonicalEngine);
 }
 
+/**
+ * Write the canonical generated/graph/model-graph.svg below the product root.
+ * @param {string} rootPath - Product root path.
+ * @returns {Promise<string>} The root-relative path that was written.
+ */
 export async function writeModelGraphSvgCanonical(rootPath) {
   const svg = await buildModelGraphSvg(readModelGraph(rootPath));
   return writeSvg(rootPath, svgOutputPath, svg);
@@ -298,8 +329,14 @@ export async function writeModelGraphSvg(rootPath, engine = "dot") {
   return writeSvg(rootPath, svgOutputPathFor(engine), await renderDotToSvg(dot, engine));
 }
 
-// Render one SVG per layout engine so the variants can be compared side by side.
-// Clusters are emitted only for the engines that lay them out (dot, fdp).
+/**
+ * Render one SVG per layout engine so the variants can be compared side by
+ * side. Clusters are emitted only for the engines that lay them out (dot,
+ * fdp). Variants go to .ddduck/graph-layouts/, not generated/.
+ * @param {string} rootPath - Product root path.
+ * @param {string[]} [engines] - Layout engines to render (default all LAYOUT_ENGINES).
+ * @returns {Promise<string[]>} The root-relative variant paths written.
+ */
 export async function writeModelGraphSvgVariants(rootPath, engines = LAYOUT_ENGINES) {
   const modelGraph = readModelGraph(rootPath);
   const writtenPaths = [];

package/scripts/generate-graph.mjs

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
 
+/**
+ * Builds the generated graph views generated/graph/model-graph.json and
+ * .ndjson from a product root: one record per model node plus ownership,
+ * relationship, and guarantee-reference (requires/preserves/establishes/uses/
+ * guarantees) edges. buildModelGraph also feeds the SVG renderer and the query
+ * engine (with --history including inactive guarantees); the byte-exact
+ * outputs are pinned by check-generated-graph.mjs. Runnable standalone.
+ */
+
 import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,6 +19,11 @@ import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
 export const jsonOutputPath = path.join("generated", "graph", "model-graph.json");
 export const ndjsonOutputPath = path.join("generated", "graph", "model-graph.ndjson");
 
+/**
+ * Build the serialized JSON and NDJSON graph views without writing them.
+ * @param {string} rootPath - Product root path.
+ * @returns {{json: string, ndjson: string}} The exact bytes of both generated views.
+ */
 export function buildModelGraphOutputs(rootPath) {
   const modelGraph = buildModelGraph(rootPath);
   return {
@@ -18,12 +32,23 @@ export function buildModelGraphOutputs(rootPath) {
   };
 }
 
+/**
+ * Build the model graph object (nodes plus edges) for a product root.
+ * @param {string} rootPath - Product root path.
+ * @param {{history?: boolean}} [options] - With history, inactive guarantees are included.
+ * @returns {{schemaVersion: string, formatVersion: string, modelId: string, modelName: string, generatedBy: string, nodes: object[], edges: object[]}} The assembled graph.
+ */
 export function buildModelGraph(rootPath, { history = false } = {}) {
   const layout = detectProductLayout(rootPath);
   const graph = loadGraph(layout, { history });
   return assembleModelGraph(graph, findModelId(graph));
 }
 
+/**
+ * Write generated/graph/model-graph.json and .ndjson below the product root.
+ * @param {string} rootPath - Product root path.
+ * @returns {string[]} The root-relative paths that were written.
+ */
 export function writeModelGraph(rootPath) {
   const outputs = buildModelGraphOutputs(rootPath);
   const writtenPaths = [];
@@ -63,7 +88,7 @@ function assembleModelGraph(graph, modelId) {
     formatVersion: "final",
     modelId: model.id,
     modelName: requireField(model, "name"),
-    nameStatus: model.nameStatus ?? "stable",
+    ...(model.nameStatus === undefined ? {} : { nameStatus: model.nameStatus }),
     generatedBy: "scripts/generate-graph.mjs",
     nodes,
     edges,

package/scripts/lib/agent-readiness-evals.mjs

@@ -1,3 +1,14 @@
+/**
+ * Agent-readiness eval harness: validates JSONL eval records (strict shape,
+ * unique IDs, repo-contained roots, shell-safe query args), replays each
+ * record's query in-process through runQuery, and checks the record's
+ * candidateEvidence against the resulting document — citations must occur in
+ * it and facts must strictly equal the value at their JSON Pointer, with
+ * <product-root> as the portable placeholder for the resolved root. Consumed
+ * by run-agent-readiness-evals.mjs; results are deterministic (sorted cases
+ * and diagnostics).
+ */
+
 import { readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { runQuery } from "../query-model.mjs";
@@ -11,6 +22,11 @@ const candidateEvidenceKeys = new Set(["origin", "citations", "facts"]);
 const citationKeys = new Set(["id", "sourcePath"]);
 const factKeys = new Set(["pointer", "equals"]);
 
+/**
+ * Run every eval record in a JSONL input file and aggregate the case results.
+ * @param {{inputPath: string, repoRoot: string}} options - JSONL input path and the repository root that bounds product roots.
+ * @returns {{schemaVersion: string, passed: boolean, cases: object[]}} Deterministically sorted eval outcome.
+ */
 export function runAgentReadinessEvals({ inputPath, repoRoot }) {
   const resolvedRepoRoot = path.resolve(repoRoot);
   const records = readRecords(inputPath);
@@ -27,6 +43,16 @@ export function runAgentReadinessEvals({ inputPath, repoRoot }) {
   };
 }
 
+/**
+ * Verify candidate evidence against a query document: origin must be "query",
+ * every citation must occur in the document, and every fact's JSON Pointer
+ * must resolve to a value strictly equal to `equals` (after <product-root>
+ * substitution).
+ * @param {object} document - The JSON document produced by the replayed query.
+ * @param {{origin?: string, citations?: object[], facts?: object[]}} candidateEvidence - Evidence claimed by the eval record.
+ * @param {{productRoot?: string}} [context] - Resolved product root for the <product-root> placeholder.
+ * @returns {string[]} Sorted diagnostics; empty when the evidence holds.
+ */
 export function validateCandidateEvidence(document, candidateEvidence, { productRoot } = {}) {
   const diagnostics = [];
   if (!isObject(candidateEvidence)) {
@@ -306,6 +332,12 @@ function collectCitations(value, citations = []) {
   return citations.sort(compareCitations);
 }
 
+/**
+ * Resolve an RFC 6901 JSON Pointer against a document.
+ * @param {unknown} document - The query document to walk.
+ * @param {string} pointer - JSON Pointer ("" selects the whole document).
+ * @returns {{ok: true, value: unknown}|{ok: false, error: string}} The resolved value or the failure reason.
+ */
 function resolveJsonPointer(document, pointer) {
   if (pointer === "") return { ok: true, value: document };
   if (!pointer.startsWith("/")) return { ok: false, error: "must start with /" };

package/scripts/lib/agent-readiness-report.mjs

@@ -1,8 +1,22 @@
+/**
+ * Builds the agent-readiness report for a product root, answering "how ready
+ * is this model for agent consumption": nodes missing evidence roles (via
+ * query anchors), stale generated views (via query spec freshness), owned
+ * nodes with no owning Domain, and nodes listed by multiple Domains. When
+ * validation fails the report collapses to unresolvedReferences only.
+ * Consumed by generate-agent-readiness-report.mjs.
+ */
+
 import { validateProduct } from "../check-model.mjs";
 import { loadQueryProduct, queryAnchors, querySpec } from "./product-query.mjs";
 
 const ownershipKinds = new Set(["Concept", "DomainInterface", "Guarantee"]);
 
+/**
+ * Build the readiness report for one product root.
+ * @param {string} rootPath - Product root path.
+ * @returns {{missingEvidence: object[], unresolvedReferences: string[], staleGeneratedViews: object[], orphanedNodes: object[], ambiguousOwnership: object[]}|{unresolvedReferences: string[]}} Full report, or only unresolvedReferences when validation fails.
+ */
 export function generateAgentReadinessReport(rootPath) {
   const check = validateProduct(rootPath, { includeDocumentation: false });
   if (check.errors.length > 0) {

package/scripts/lib/cli-contract.mjs

@@ -1,3 +1,13 @@
+/**
+ * The shared CLI contract for every ddduck command surface: the usage-error
+ * type, the option/positional parser, the per-command --help text (including
+ * the documented exit codes: 0 success, 1 failure, 2 retryable busy), and the
+ * single-format error writer that always emits `Error: ...` plus a `Next:`
+ * action line. Consumed by ddduck.mjs, query-model.mjs, and
+ * audit-fr-to-code.mjs so agents can rely on one stable error shape.
+ */
+
+/** Invalid CLI input; may carry a nextAction line for the error writer. */
 export class CliUsageError extends Error {
   constructor(message, { nextAction } = {}) {
     super(message);
@@ -6,6 +16,14 @@ export class CliUsageError extends Error {
   }
 }
 
+/**
+ * Parse command arguments against a declared option/positional shape,
+ * supporting --name value and --name=value, boolean flags, repeatable
+ * options, and duplicate rejection.
+ * @param {string[]} args - Arguments after the command word.
+ * @param {{positionals?: {min?: number, max?: number, syntax?: string}, options?: Record<string, {value?: boolean, repeatable?: boolean}>}} [spec] - Accepted positional bounds and option definitions.
+ * @returns {{positionals: string[], options: Record<string, string|string[]|boolean>}} Parsed values (booleans default false, repeatables default []).
+ */
 export function parseCommandArgs(args, { positionals = {}, options = {} } = {}) {
   const minimum = positionals.min ?? 0;
   const maximum = positionals.max ?? minimum;
@@ -55,6 +73,11 @@ export function parseCommandArgs(args, { positionals = {}, options = {} } = {})
   return { positionals: values, options: parsed };
 }
 
+/**
+ * Render the --help text for one command, or the top-level command list.
+ * @param {string} [command] - Command name; unknown or absent yields the overview.
+ * @returns {string} The help text, newline-terminated.
+ */
 export function renderHelp(command) {
   const usage = {
     undefined: [
@@ -74,8 +97,8 @@ export function renderHelp(command) {
       "Syntax: ddduck check [--root <product-root>] [--base <previous-product-root>] [--docs-root <docs-root> ...] [--source-only]",
       "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); --base is unset; documentation references are checked inside the product root unless --docs-root replaces that scope; generated freshness is checked.",
       "Writes: nothing.",
-      "Success output: none.",
-      "Exit status: 0 on a valid fresh product or help; nonzero on invalid source, stale views, leftover interrupted-operation state, or invalid input.",
+      "Success output: none on standard output; when --root is omitted, one standard-error note names the validated root.",
+      "Exit status: 0 on a valid fresh product or help; 2 when the product root is busy (operation lock held by a running process, retryable); 1 on invalid source, stale views, leftover interrupted-operation state, or invalid input.",
       "JSON: unavailable; --json is not accepted.",
     ],
     generate: [
@@ -83,15 +106,15 @@ export function renderHelp(command) {
       "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); text output is used.",
       "Writes: all required generated docs and graph views after staged validation.",
       "Success output: one text result with the root and refreshed generated paths.",
-      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "Exit status: 0 on publication or help; 2 when the product root is busy (operation lock held by a running process, retryable); 1 with no intended product changes on any other failure.",
       "JSON: --json emits the same result as one JSON object.",
     ],
     query: [
       "Syntax: ddduck query <node|neighbors|impact|anchors|spec|context> [options] [--json]",
-      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery) except context requires it; --history is false.",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); --history is false.",
       "Writes: nothing.",
       "Success output: exactly one JSON query document.",
-      "Exit status: 0 on a resolved query or help; nonzero on invalid input, product, or selection.",
+      "Exit status: 0 on a resolved query or help; 2 when the product root is busy (operation lock held by a running process, retryable); 1 on invalid input, product, or selection.",
       "JSON: output is always JSON; --json is accepted and has no effect.",
       "Options: --id <model-node-id> (repeatable for context), --root <product-root>, --history.",
     ],
@@ -108,7 +131,7 @@ export function renderHelp(command) {
       "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); the next origin/classification serial is allocated.",
       "Writes: the new Guarantee, its owning Domain, and all generated views through staged publication.",
       "Success output: one text result with the allocated ID, root, canonical paths, and generated paths.",
-      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "Exit status: 0 on publication or help; 2 when the product root is busy (operation lock held by a running process, retryable); 1 with no intended product changes on any other failure.",
       "JSON: --json emits the same result as one JSON object.",
     ],
     move: [
@@ -116,7 +139,7 @@ export function renderHelp(command) {
       "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery).",
       "Writes: the Guarantee, affected Domains, and all generated views through staged publication.",
       "Success output: one text result with affected IDs, root, canonical paths, and generated paths.",
-      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "Exit status: 0 on publication or help; 2 when the product root is busy (operation lock held by a running process, retryable); 1 with no intended product changes on any other failure.",
       "JSON: --json emits the same result as one JSON object.",
     ],
     split: [
@@ -124,7 +147,7 @@ export function renderHelp(command) {
       "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery).",
       "Writes: the source Guarantee lifecycle state and all generated views through staged publication.",
       "Success output: one text result with affected IDs, root, canonical paths, and generated paths.",
-      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "Exit status: 0 on publication or help; 2 when the product root is busy (operation lock held by a running process, retryable); 1 with no intended product changes on any other failure.",
       "JSON: --json emits the same result as one JSON object.",
     ],
     retire: [
@@ -132,7 +155,7 @@ export function renderHelp(command) {
       "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery).",
       "Writes: the Guarantee lifecycle state and all generated views through staged publication.",
       "Success output: one text result with affected IDs, root, canonical paths, and generated paths.",
-      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "Exit status: 0 on publication or help; 2 when the product root is busy (operation lock held by a running process, retryable); 1 with no intended product changes on any other failure.",
       "JSON: --json emits the same result as one JSON object.",
     ],
     "audit-fr-to-code": [
@@ -142,6 +165,14 @@ export function renderHelp(command) {
   return `${(usage[command] ?? usage.undefined).join("\n")}\n`;
 }
 
+/**
+ * Format any error into the CLI contract shape: `Error: <message>` (multi-line
+ * diagnostics preserved) followed by a `Next: <action>` line, preferring the
+ * error's own nextAction over the caller's fallback.
+ * @param {unknown} error - The thrown error or value.
+ * @param {{nextAction?: string}} [options] - Fallback next action.
+ * @returns {string} The formatted error text (no trailing newline).
+ */
 export function formatCliError(error, { nextAction } = {}) {
   const message = error instanceof Error ? error.message : String(error);
   const action = error?.nextAction ?? nextAction ?? "Review the diagnostic, correct the input, and retry.";
@@ -156,7 +187,15 @@ export function formatCliError(error, { nextAction } = {}) {
   return [`Error: ${lines[0]}`, ...lines.slice(1), `Next: ${action}`].join("\n");
 }
 
+/**
+ * Write a formatted error to stderr and set the process exit code.
+ * @param {unknown} error - The thrown error or value.
+ * @param {{stderr?: {write: (chunk: string) => unknown}, nextAction?: string}} [options] - Stream override and fallback next action.
+ * @returns {void}
+ */
 export function writeCliError(error, { stderr = process.stderr, nextAction } = {}) {
   stderr.write(`${formatCliError(error, { nextAction })}\n`);
-  process.exitCode = 1;
+  // Exit 1 is the default failure code; an error may carry a distinct code
+  // (exit 2 marks the retryable busy case, see ProductBusyError).
+  process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
 }

package/scripts/lib/context-pack.mjs

@@ -1,7 +1,49 @@
+/**
+ * Implements `ddduck query context`: the context pack that returns the
+ * selected active nodes in full, every edge touching them, and summaries of
+ * the unselected endpoints, all under a sha256 source digest of the canonical
+ * YAML so consumers can detect drift. Also home to the shared sourceDigest
+ * helpers, shellQuote for copy-pasteable emitted commands, and the
+ * unknown-model-node error used across the query surface.
+ */
+
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 
+/**
+ * Quote a value for safe copy-paste into a shell. Emitted commands are copied
+ * into shells by humans and agents; roots with spaces or metacharacters must
+ * survive that round trip.
+ * @param {string} value - The path or argument to quote.
+ * @returns {string} The value, single-quoted unless already shell-safe.
+ */
+export function shellQuote(value) {
+  if (/^[A-Za-z0-9_\-./]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * Build the error for an ID that names no model node. An unknown ID is a model
+ * failure, not a CLI-input failure: point the caller at the generated graph
+ * view, the surface that enumerates every node ID, instead of the usage hint.
+ * @param {{root: string}} product - The loaded query product.
+ * @param {string} id - The unresolved model node ID.
+ * @returns {Error} Error with a node-listing nextAction.
+ */
+export function unknownModelNodeError(product, id) {
+  const error = new Error(`Unknown model node ${id}`);
+  error.nextAction = `List the model's node IDs in ${path.join(product.root, "generated", "graph", "model-graph.ndjson")} (one node per line), then retry.`;
+  return error;
+}
+
+/**
+ * Resolve a context pack for a set of selected node IDs: full selected nodes,
+ * direct edges, and neighbor summaries. Inactive guarantees cannot be selected.
+ * @param {{rootModelId: string, nodes: Map<string, object>, edges: object[], sourcePaths: Map<string, string>, sourceDigest: string, lifecycleRedirects: Map<string, object>}} product - The loaded query product.
+ * @param {string[]} selectedIds - Distinct model node IDs to select.
+ * @returns {object} The context pack document (schemaVersion, query, snapshot, result).
+ */
 export function resolveContextPack(product, selectedIds) {
   const ids = validateSelectedIds(product, selectedIds);
   const selectedSet = new Set(ids);
@@ -29,6 +71,12 @@ export function sourceDigest(root, sourcePaths) {
   return sourceDigestFromSources(sources);
 }
 
+/**
+ * Compute the canonical sha256 digest over already-read source files: paths
+ * sorted, each path and content NUL-separated.
+ * @param {Map<string, Buffer|string>} sources - Root-relative path to file bytes.
+ * @returns {string} Hex digest identifying this exact canonical snapshot.
+ */
 export function sourceDigestFromSources(sources) {
   const hash = createHash("sha256");
   for (const relativePath of [...sources.keys()].sort(byString)) {
@@ -64,7 +112,7 @@ function validateSelectedIds(product, selectedIds) {
     if (lifecycleRedirect) {
       throw new Error(`Cannot select inactive model node ${id} (${lifecycleRedirect.status})`);
     }
-    throw new Error(`Unknown model node ${id}`);
+    throw unknownModelNodeError(product, id);
   }
   return ids;
 }

package/scripts/lib/ddduck-config.mjs

@@ -1,3 +1,12 @@
+/**
+ * Repository-level configuration for ddduck: locates the repository root (the
+ * nearest .git ancestor, else the starting directory) and reads/validates
+ * .ddduck/config.json, whose productRoot pins the repository's default product
+ * root and whose optional ignore list extends the repo scanners' skipped
+ * directory names. Consumed by the product root resolver, init, and the
+ * documentation reference check.
+ */
+
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
 
@@ -5,17 +14,32 @@ const configRelativePath = path.join(".ddduck", "config.json");
 
 export const defaultConfigIgnore = Object.freeze(["vendor", "target", "build", "dist", "__pycache__"]);
 
+/**
+ * Find the nearest ancestor directory containing .git; without one, fall back
+ * to the starting directory itself (never a file path).
+ * @param {string} [startPath] - Directory or file to start from (default cwd).
+ * @returns {string} Absolute repository root, always a directory.
+ */
 export function findRepositoryRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
   if (existsSync(current) && !lstatSync(current).isDirectory()) current = path.dirname(current);
+  // The adjusted starting directory is the fallback when no .git ancestor exists,
+  // so a file startPath never leaks back out as if it were a directory.
+  const fallback = current;
   while (true) {
     if (existsSync(path.join(current, ".git"))) return current;
     const parent = path.dirname(current);
-    if (parent === current) return path.resolve(startPath);
+    if (parent === current) return fallback;
     current = parent;
   }
 }
 
+/**
+ * Load and validate .ddduck/config.json from a repository root; a malformed
+ * config throws, an absent one returns null.
+ * @param {string} repositoryRoot - Repository root to read the config from.
+ * @returns {{schemaVersion: "1", productRoot: string, ignore?: string[]}|null} The validated config or null.
+ */
 export function loadDdduckConfig(repositoryRoot) {
   const configPath = path.join(repositoryRoot, configRelativePath);
   if (!existsSync(configPath)) return null;
@@ -50,6 +74,12 @@ export function loadDdduckConfig(repositoryRoot) {
   return config;
 }
 
+/**
+ * Resolve the ignored directory names for repo scans: the config's ignore list
+ * when present, else the defaults (vendor, target, build, dist, __pycache__).
+ * @param {string} repositoryRoot - Repository root whose config applies.
+ * @returns {string[]} Directory names to skip.
+ */
 export function resolveConfiguredIgnores(repositoryRoot) {
   const config = loadDdduckConfig(repositoryRoot);
   if (!config || config.ignore === undefined) return [...defaultConfigIgnore];

package/scripts/lib/fr-to-code-audit.mjs

@@ -1,3 +1,13 @@
+/**
+ * Verification core for FR-to-code audit records, shared by the
+ * audit-fr-to-code CLI and its tests. Validates a record against
+ * schemas/fr-to-code-audit.schema.json, checks the requirement ID (and traced
+ * guarantee) appear in the pinned requirement source, confirms every
+ * production/test anchor's line range exists and digests its excerpt
+ * (sha256), and enforces verdict consistency (realized-and-tested,
+ * realized-untested, unrealized) before rendering the deterministic report.
+ */
+
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
@@ -12,6 +22,12 @@ const auditSchema = JSON.parse(
 );
 const validateAudit = new Ajv2020({ allErrors: true, strict: true }).compile(auditSchema);
 
+/**
+ * Verify one audit record against its sources and render the report.
+ * @param {object} record - The parsed FrToCodeAudit YAML mapping.
+ * @param {{readFile: (source: object, relativePath: string) => string}} sourceReader - Reader that serves file text at each source's pinned revision.
+ * @returns {object} The FrToCodeAuditReport document with digested anchors.
+ */
 export function verifyFrToCodeAudit(record, sourceReader) {
   const normalized = validateRecord(record);
   requireReader(sourceReader);
@@ -69,6 +85,14 @@ function requireText(text, value, label) {
   if (!text.includes(value)) throw new Error(`FrToCodeAudit ${label} ${value} is missing from its source file`);
 }
 
+/**
+ * Resolve each anchor's source file, verify its line range fits the file, and
+ * replace the excerpt with a sha256 digest in the rendered report.
+ * @param {{sourceId: string, path: string, startLine: number, endLine: number}[]} anchors - Production or test anchors.
+ * @param {Map<string, object>} sourcesById - Declared sources keyed by ID.
+ * @param {{readFile: (source: object, relativePath: string) => string}} sourceReader - Pinned-revision file reader.
+ * @returns {object[]} Sorted anchors with excerptDigest entries.
+ */
 function renderAnchors(anchors, sourcesById, sourceReader) {
   return anchors
     .map((anchor) => {

package/scripts/lib/product-layout.mjs

@@ -1,9 +1,33 @@
+/**
+ * Defines the on-disk layout of a product root and loads its canonical YAML:
+ * product.yaml plus the model/{domains,concepts,relationships,use-cases,
+ * interfaces,guarantees} directories (nodeDirectoryKinds maps directory to
+ * node kind). loadProductNodes yields mutable nodes with file paths and raw
+ * sources (for the query digest); loadProductSnapshot yields the deep-frozen
+ * snapshot with root-relative canonical paths that mutation transforms plan
+ * against. Strict YAML parsing: duplicate keys and non-mapping files fail.
+ */
+
 import { readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "yaml";
 
-const nodeDirectories = ["domains", "concepts", "relationships", "use-cases", "interfaces", "guarantees"];
+export const nodeDirectoryKinds = new Map([
+  ["domains", "Domain"],
+  ["concepts", "Concept"],
+  ["relationships", "Relationship"],
+  ["use-cases", "UseCase"],
+  ["interfaces", "DomainInterface"],
+  ["guarantees", "Guarantee"],
+]);
+
+const nodeDirectories = [...nodeDirectoryKinds.keys()];
 
+/**
+ * Describe the canonical layout below a product root.
+ * @param {string} rootPath - Product root path.
+ * @returns {{root: string, productPath: string, nodeDirectories: string[], decisionsDirectory: string, generatedDirectory: string}} Resolved layout paths.
+ */
 export function detectProductLayout(rootPath) {
   const root = path.resolve(rootPath);
   return {
@@ -15,6 +39,11 @@ export function detectProductLayout(rootPath) {
   };
 }
 
+/**
+ * Load every canonical YAML node under a layout, rejecting duplicate node IDs.
+ * @param {{root: string, productPath: string, nodeDirectories: string[]}} layout - Layout from detectProductLayout.
+ * @returns {{nodes: Map<string, object>, nodeFiles: Map<string, string>, nodeSources: Map<string, Buffer>}} Nodes, their file paths, and raw source bytes keyed by ID.
+ */
 export function loadProductNodes(layout) {
   const nodes = new Map();
   const nodeFiles = new Map();
@@ -35,6 +64,12 @@ export function loadProductNodes(layout) {
   return { nodes, nodeFiles, nodeSources };
 }
 
+/**
+ * Load the deep-frozen snapshot that mutation transforms receive: immutable
+ * nodes plus each node's root-relative canonical path.
+ * @param {{root: string, productPath: string, nodeDirectories: string[]}} layout - Layout from detectProductLayout.
+ * @returns {{nodes: readonly object[], canonicalPaths: Record<string, string>}} Frozen snapshot.
+ */
 export function loadProductSnapshot(layout) {
   const loaded = loadProductNodes(layout);
   const nodes = Object.freeze([...loaded.nodes.values()].map((node) => deepFreeze(node)));
@@ -49,6 +84,12 @@ export function loadProductSnapshot(layout) {
   return Object.freeze({ nodes, canonicalPaths });
 }
 
+/**
+ * Parse one canonical YAML file strictly (unique keys) into a plain mapping.
+ * @param {string} filePath - File path, used in diagnostics.
+ * @param {string} [source] - YAML source; read from filePath when omitted.
+ * @returns {object} The parsed YAML mapping.
+ */
 export function parseYamlMapping(filePath, source = readFileSync(filePath, "utf8")) {
   const document = parseDocument(source, { keepSourceTokens: true, strict: true, uniqueKeys: true });
   if (document.errors.length > 0) {