ddduck 0.1.0 → 0.2.0

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,11 +73,16 @@ 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: [
       "Usage: ddduck <command> [options]",
-      "Commands: init, check, generate, query, install, create, move, split, retire.",
+      "Commands: init, check, generate, query, diff, install, create, move, split, retire.",
       "Run `ddduck <command> --help` for command usage.",
     ],
     init: [
@@ -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,32 +106,43 @@ 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.",
     ],
+    diff: [
+      "Syntax: ddduck diff --base <previous-product-root> [--root <product-root>] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); --base is required; output is text.",
+      "Writes: nothing; source roots are validated independently and generated freshness is not required.",
+      "Success output: a stable-ID comparison of added, removed, changed, and relocated canonical records, with source digests and explicit exclusions.",
+      "Exit status: 0 on a completed comparison (including differences) or help; 2 for a busy root; 1 for invalid input, source, interrupted state, or different Model IDs.",
+      "JSON: --json emits one ModelDiff document; comparison is canonical YAML only and requires human interpretation.",
+    ],
     install: [
       "Syntax: ddduck install skill update-ddduck-specs [--repo <repository-root>]",
       "Defaults: --repo is the current directory.",
-      "Writes: the selected host skill adapter and .ddduck/agent-skills.lock.json in --repo.",
+      "Writes: the selected host skill bundle and .ddduck/agent-skills.lock.json in --repo.",
       "Success output: one text result with the action (created, upgraded, or no-op), repository, canonical path, and lock path.",
       "Exit status: 0 on installation, no-op, or help; nonzero on invalid input or conflicting host state.",
       "JSON: unavailable; --json is not accepted.",
     ],
     create: [
       "Syntax: ddduck create guarantee --origin <origin> --classification <invariant|acceptance-criterion> --owner <domain-id> --statement <text> [--root <product-root>] [--json]",
-      "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.",
+      "Syntax: ddduck create domain --id domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]",
+      "Syntax: ddduck create concept --id concept:<slug> --owner domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]",
+      "Syntax: ddduck create use-case --file <yaml-file> [--root <product-root>] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); guarantees allocate the next origin/classification serial; other kinds require an explicit ID or complete UseCase input.",
+      "Writes: the new node, its owning collection, and all generated views through staged publication; input files are read-only.",
+      "Success output: one text result with affected IDs, root, canonical paths, and generated paths.",
+      "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 +150,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 +158,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 +166,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 +176,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 +198,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) => {
@@ -117,6 +141,12 @@ function renderReport(record, productionAnchors, testAnchors) {
     requirement: record.requirement,
     coverage: record.coverage,
     verdict: record.verdict,
+    verificationScope: {
+      verdictSource: "input-record",
+      anchorIntegrityChecked: true,
+      testsExecuted: false,
+      behaviorVerified: false,
+    },
     productionAnchors,
     testAnchors,
     reviewerDisposition: record.reviewerDisposition,

package/scripts/lib/product-authoring.mjs

@@ -0,0 +1,52 @@
+const kinds = {
+  Domain: { prefix: "domain", directory: "domains", collection: "domains" },
+  Concept: { prefix: "concept", directory: "concepts", collection: "concepts" },
+  UseCase: { prefix: "use-case", directory: "use-cases", collection: "useCases" },
+};
+
+export function buildAuthoringPlan(snapshot, request) {
+  const definition = kinds[request.kind];
+  if (!definition) throw new Error(`Unsupported creation kind ${request.kind}`);
+  const models = snapshot.nodes.filter(({ kind }) => kind === "Model");
+  if (models.length !== 1) throw new Error("Creation requires exactly one Model");
+  const [model] = models;
+  const node =
+    request.kind === "UseCase"
+      ? globalThis.structuredClone(request.node)
+      : {
+          schemaVersion: "1",
+          kind: request.kind,
+          id: request.id,
+          model: model.id,
+          ...(request.kind === "Concept" ? { ownerDomain: request.ownerDomain } : {}),
+          name: request.name,
+          purpose: request.purpose,
+          ...(request.kind === "Domain" ? { concepts: [], interfaces: [], guarantees: [] } : {}),
+        };
+  if (node?.kind !== request.kind) throw new Error(`create ${definition.prefix} requires kind ${request.kind}`);
+  if (node.model !== model.id) throw new Error(`New node model must be ${model.id}`);
+  if (typeof node.id !== "string" || !new RegExp(`^${definition.prefix}:[a-z0-9][a-z0-9-]*$`).test(node.id)) {
+    throw new Error(`Invalid ${request.kind} ID ${JSON.stringify(node.id)}`);
+  }
+  if (snapshot.nodes.some(({ id }) => id === node.id)) throw new Error(`Model node ${node.id} already exists`);
+  const destination = `model/${definition.directory}/${node.id.slice(definition.prefix.length + 1)}.yaml`;
+  if (Object.values(snapshot.canonicalPaths).includes(destination)) {
+    throw new Error(`Canonical destination already occupied: ${destination}`);
+  }
+  const parent =
+    request.kind === "Concept"
+      ? snapshot.nodes.find(({ id, kind }) => kind === "Domain" && id === node.ownerDomain)
+      : model;
+  if (!parent) throw new Error(`Unknown domain ${node.ownerDomain}`);
+  return {
+    operation: `create ${definition.prefix}`,
+    affectedIds: [node.id, parent.id],
+    replacements: [
+      { path: destination, value: node },
+      {
+        path: snapshot.canonicalPaths[parent.id],
+        value: { ...parent, [definition.collection]: [...(parent[definition.collection] ?? []), node.id] },
+      },
+    ],
+  };
+}