ddduck 0.1.0 → 0.1.2

package/scripts/check-model.mjs

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+/**
+ * The model checker behind `ddduck check`: validates a product root's canonical
+ * YAML against the framework schemas, referential integrity (single Model,
+ * ownership, decisions), evidence anchors, guarantee lifecycle rules, and the
+ * executable policy checks (ownership, documentation model-reference
+ * resolution). With --base it also enforces guarantee history retention against
+ * a previous product root. Exports validateProduct for the operation runner,
+ * query loader, and root resolver; runs standalone as a CLI (exit 1 on errors).
+ */
+
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -7,7 +17,7 @@ import Ajv2020 from "ajv/dist/2020.js";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import { parseDocument } from "yaml";
-import { detectProductLayout, loadProductNodes } from "./lib/product-layout.mjs";
+import { detectProductLayout, loadProductNodes, nodeDirectoryKinds } from "./lib/product-layout.mjs";
 import { shouldIgnoreScanEntry } from "./lib/scan-ignore.mjs";
 import { findRepositoryRoot, resolveConfiguredIgnores } from "./lib/ddduck-config.mjs";
 
@@ -18,7 +28,7 @@ const executableRuleChecks = new Set([
 ]);
 
 const markdownReferencePattern =
-  /\b(?:(?:model|domain|concept|rel|rule|use-case|interface):[a-z0-9][a-z0-9-]*|[A-Z][A-Z0-9-]+-(?:INV|AC)-[0-9]+|ADR-[0-9]{3})\b/g;
+  /\b(?:(?:model|domain|concept|rel|use-case|interface):[a-z0-9][a-z0-9-]*|[A-Z][A-Z0-9-]+-(?:INV|AC)-[0-9]+|ADR-[0-9]{3})\b/g;
 
 const defaultFrameworkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -58,6 +68,11 @@ function parseArgs(args) {
   return parsed;
 }
 
+/**
+ * One validation run over a product root: loads nodes and decisions, then
+ * accumulates every diagnostic in `errors` (file-relative, one per line) while
+ * counting nodes, references, and executed policies for the verbose summary.
+ */
 class ProductCheck {
   constructor(rootPath, frameworkPath, basePath, documentationRoots, { sourceOnly = false } = {}) {
     this.root = rootPath;
@@ -78,6 +93,7 @@ class ProductCheck {
     this.loadDecisions();
     this.loadNodes();
     this.validateSchemas();
+    this.validateNodeDirectories();
     this.validateEvidenceAnchors();
     this.validateReferences();
     this.validateGuaranteeLifecycle();
@@ -147,6 +163,22 @@ class ProductCheck {
     }
   }
 
+  validateNodeDirectories() {
+    for (const [id, filePath] of this.nodeFiles) {
+      const segments = path.relative(this.root, filePath).split(path.sep);
+      if (segments[0] !== "model") continue;
+      const expectedKind = nodeDirectoryKinds.get(segments[1]);
+      if (!expectedKind) continue;
+      const node = this.nodes.get(id);
+      if (node.kind !== expectedKind) {
+        this.addError(
+          id,
+          `node kind ${node.kind} does not match directory model/${segments[1]} (expected ${expectedKind})`,
+        );
+      }
+    }
+  }
+
   validateReferences() {
     const models = [...this.nodes.values()].filter((node) => node.kind === "Model");
     if (models.length !== 1) {
@@ -195,6 +227,15 @@ class ProductCheck {
             node.id,
             `evidence anchor path must resolve to an existing regular file below product root: ${evidence.path}`,
           );
+          continue;
+        }
+        // Markdown targets must contain the anchor text; non-Markdown anchors
+        // stay free-form labels.
+        if (evidence.path.endsWith(".md") && typeof evidence.anchor === "string") {
+          const content = readFileSync(path.resolve(this.root, evidence.path), "utf8");
+          if (!content.includes(evidence.anchor)) {
+            this.addError(node.id, `evidence anchor not found in ${evidence.path}: ${evidence.anchor}`);
+          }
         }
       }
     }
@@ -207,8 +248,17 @@ class ProductCheck {
         if (successors.length === 0) this.addError(node.id, "split guarantee requires active successors");
         for (const id of successors) {
           const successor = this.nodes.get(id);
-          if (!successor || successor.kind !== "Guarantee" || successor.status !== "active")
-            this.addError(node.id, `split successor must be an active guarantee ${id}`);
+          if (!successor || successor.kind !== "Guarantee") {
+            this.addError(node.id, `split successor must be a guarantee ${id}`);
+            continue;
+          }
+          // A successor may leave `active` through its own authorized lifecycle
+          // transition; its record must then carry a registered lifecycleDecision.
+          if (successor.status !== "active" && !this.decisions.has(successor.lifecycleDecision))
+            this.addError(
+              node.id,
+              `split successor must be an active guarantee or carry a registered lifecycleDecision ${id}`,
+            );
         }
       }
       if (node.kind === "DomainInterface" || node.kind === "UseCase") {
@@ -269,9 +319,35 @@ class ProductCheck {
       this.errors.push(`base: ${error.message}`);
       return;
     }
+    const legalStatusTransitions = new Map([
+      ["active", ["active", "split", "retired"]],
+      ["split", ["split"]],
+      ["retired", ["retired"]],
+    ]);
     for (const baseNode of baseNodes.values()) {
-      if (baseNode.kind === "Guarantee" && !this.nodes.has(baseNode.id)) {
+      if (baseNode.kind !== "Guarantee") continue;
+      const current = this.nodes.get(baseNode.id);
+      if (!current) {
         this.errors.push(`guarantee disappeared from the product: ${baseNode.id}`);
+        continue;
+      }
+      if (!(legalStatusTransitions.get(baseNode.status) ?? []).includes(current.status)) {
+        this.addError(baseNode.id, `illegal guarantee status transition ${baseNode.status} -> ${current.status}`);
+        continue;
+      }
+      if (baseNode.status === "split" || baseNode.status === "retired") {
+        if (current.lifecycleDecision !== baseNode.lifecycleDecision)
+          this.addError(
+            baseNode.id,
+            `closed guarantee must keep lifecycleDecision ${baseNode.lifecycleDecision} from base`,
+          );
+        const baseSuccessors = asArray(baseNode.successors);
+        const currentSuccessors = asArray(current.successors);
+        if (
+          baseSuccessors.length !== currentSuccessors.length ||
+          baseSuccessors.some((id, index) => currentSuccessors[index] !== id)
+        )
+          this.addError(baseNode.id, `closed guarantee must keep successors ${baseSuccessors.join(", ")} from base`);
       }
     }
   }
@@ -373,6 +449,14 @@ function listFiles(directory, pattern) {
   }
 }
 
+/**
+ * Recursively list Markdown files under a documentation root, skipping ignored
+ * scan entries, nested git checkouts, nested product roots, and the audit and
+ * superpowers doc areas.
+ * @param {string} rootPath - Documentation root to walk.
+ * @param {string[]} [ignoredEntryNames] - Extra directory names to skip (from .ddduck config).
+ * @returns {string[]} Sorted absolute Markdown file paths.
+ */
 function listMarkdownFiles(rootPath, ignoredEntryNames = []) {
   const files = [];
 
@@ -454,6 +538,12 @@ function executePolicyChecks(check, checksToRun, { includeDocumentation = true }
   }
 }
 
+/**
+ * Validate a product root and return the completed check (inspect `.errors`).
+ * @param {string} rootPath - Product root to validate.
+ * @param {{baseRoot?: string, includeDocumentation?: boolean, documentationRoots?: string[], sourceOnly?: boolean}} [options] - Base product for history retention, documentation scope, and whether generated docs are scanned.
+ * @returns {ProductCheck} The finished check with errors and counters.
+ */
 export function validateProduct(
   rootPath,
   { baseRoot, includeDocumentation = true, documentationRoots, sourceOnly = false } = {},

package/scripts/ddduck.mjs

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
 
+/**
+ * Entry point for the `ddduck` CLI (the package bin). Dispatches the commands
+ * init, check, generate, query, install, and the guarantee lifecycle commands
+ * create/move/split/retire. Mutations run through the locked, staged operation
+ * runner in lib/product-operation.mjs; init publishes a fresh product root via
+ * PID-stamped staging; check delegates to check-model.mjs plus the generated
+ * freshness gates. Errors leave through writeCliError with a Next: action line.
+ */
+
 import {
   existsSync,
   mkdirSync,
@@ -10,6 +19,7 @@ import {
   renameSync,
   rmSync,
   rmdirSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import path from "node:path";
@@ -20,10 +30,17 @@ import { writeModelOverview } from "./generate-docs.mjs";
 import { writeModelGraph } from "./generate-graph.mjs";
 import { checkGeneratedDocs } from "./check-generated-docs.mjs";
 import { checkGeneratedGraph } from "./check-generated-graph.mjs";
-import { assertProductNotBusy, findLeftoverOperationState, runProductOperation } from "./lib/product-operation.mjs";
+import {
+  assertProductNotBusy,
+  findLeftoverOperationState,
+  generatedPaths,
+  isProcessAlive,
+  runProductOperation,
+  validationFailureError,
+} from "./lib/product-operation.mjs";
 import { resolveContainedOutput } from "./lib/product-paths.mjs";
 import { initStagingPrefix, resolveInitDestination, resolveProductRoot } from "./lib/product-root-resolver.mjs";
-import { defaultConfigIgnore, findRepositoryRoot } from "./lib/ddduck-config.mjs";
+import { defaultConfigIgnore, findRepositoryRoot, loadDdduckConfig } from "./lib/ddduck-config.mjs";
 import { installSkill } from "./lib/skill-installer.mjs";
 import { runQuery } from "./query-model.mjs";
 import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
@@ -38,6 +55,11 @@ try {
   writeCliError(error, { nextAction: nextActionFor(cliArgs) });
 }
 
+/**
+ * Dispatch one parsed CLI invocation to its command handler.
+ * @param {string[]} args - Raw CLI arguments (process.argv minus node and script).
+ * @returns {void}
+ */
 function run(args) {
   if (args.length === 1 && args[0] === "--help") {
     process.stdout.write(renderHelp());
@@ -81,6 +103,12 @@ function run(args) {
   }
 }
 
+/**
+ * Implement `ddduck install skill update-ddduck-specs`: install the bundled
+ * host skill adapter and .ddduck/agent-skills.lock.json into --repo.
+ * @param {string[]} args - Arguments after the `install` command word.
+ * @returns {void}
+ */
 function install(args) {
   const { positionals, options } = parseCommandArgs(args, {
     positionals: { min: 2, max: 2 },
@@ -92,6 +120,13 @@ function install(args) {
   }
   const packageVersion = JSON.parse(readFileSync(path.join(frameworkRoot, "package.json"), "utf8")).version;
   const repository = path.resolve(options.repo ?? process.cwd());
+  // A typo'd --repo must fail instead of silently manufacturing a directory
+  // tree (and a lock) at the wrong path while the real repository gets nothing.
+  if (!existsSync(repository) || !statSync(repository).isDirectory()) {
+    throw new CliUsageError(`install requires an existing repository directory: ${repository}`, {
+      nextAction: "Pass --repo <existing-repository-root> and retry.",
+    });
+  }
   const result = installSkill({
     repository,
     skillName,
@@ -104,6 +139,14 @@ function install(args) {
   );
 }
 
+/**
+ * Implement `ddduck init`: build a new product root (canonical directories,
+ * product.yaml, all generated views) in a PID-stamped staging directory beside
+ * the destination, then publish it atomically via rename and write
+ * .ddduck/config.json if absent.
+ * @param {string[]} args - Arguments after the `init` command word.
+ * @returns {{result: object, json: boolean}} The operation result and whether --json was requested.
+ */
 function initialize(args) {
   const { positionals, options } = parseCommandArgs(args, {
     positionals: { min: 0, max: 1 },
@@ -112,7 +155,9 @@ function initialize(args) {
   const destination = resolveInitDestination({ explicitDestination: positionals[0] });
   const productId = requiredOption(options, "id", "init requires --id model:<product-id>");
   if (!/^model:[a-z0-9][a-z0-9-]*$/.test(productId)) {
-    throw new Error(`Invalid product ID ${JSON.stringify(productId)}`);
+    throw new Error(
+      `Invalid product ID ${JSON.stringify(productId)}; expected model:<lowercase-slug> (for example model:library)`,
+    );
   }
 
   mkdirSync(path.dirname(destination), { recursive: true });
@@ -121,14 +166,19 @@ function initialize(args) {
   }
 
   // Stage names embed the destination so concurrent inits to sibling
-  // destinations never sweep each other's live staging directories.
+  // destinations never sweep each other's live staging directories, and the
+  // creating PID so concurrent inits to the SAME destination only sweep stages
+  // whose creator is dead (mirroring the mutation lock's reclaim rule). Stages
+  // without a parseable live PID are interrupted-init debris and get swept.
   const destinationStagePrefix = `${initStagingPrefix}${path.basename(destination)}-`;
   for (const entry of readdirSync(path.dirname(destination))) {
-    if (entry.startsWith(destinationStagePrefix)) {
-      rmSync(path.join(path.dirname(destination), entry), { recursive: true, force: true });
-    }
+    if (!entry.startsWith(destinationStagePrefix)) continue;
+    const stagePid = Number.parseInt(entry.slice(destinationStagePrefix.length).match(/^(\d+)-/)?.[1] ?? "", 10);
+    if (Number.isInteger(stagePid) && stagePid > 0 && isProcessAlive(stagePid)) continue;
+    rmSync(path.join(path.dirname(destination), entry), { recursive: true, force: true });
   }
-  const stagingRoot = mkdtempSync(path.join(path.dirname(destination), destinationStagePrefix));
+  const stagingRoot = mkdtempSync(path.join(path.dirname(destination), `${destinationStagePrefix}${process.pid}-`));
+  let config;
   try {
     for (const directory of ["domains", "concepts", "relationships", "use-cases", "interfaces", "guarantees"]) {
       mkdirSync(resolveContainedOutput(stagingRoot, path.join("model", directory)), { recursive: true });
@@ -145,10 +195,22 @@ function initialize(args) {
       decisions: [],
     });
     refreshDerivedOutput(stagingRoot);
-    if (existsSync(destination)) rmdirSync(destination);
-    renameSync(stagingRoot, destination);
     try {
-      writeConfigIfAbsent(destination);
+      if (existsSync(destination)) rmdirSync(destination);
+      renameSync(stagingRoot, destination);
+    } catch (error) {
+      // A concurrent init to the same destination can publish between the
+      // emptiness check above and this rename; name the collision instead of
+      // surfacing the raw filesystem error.
+      if (error.code === "ENOTEMPTY" || error.code === "EEXIST") {
+        throw new Error(
+          `Refusing to initialize non-empty directory ${destination}; another init published it concurrently`,
+        );
+      }
+      throw error;
+    }
+    try {
+      config = writeConfigIfAbsent(destination);
     } catch (error) {
       // Writing the config is the final publish step. If it fails (for example a
       // regular file already occupies the .ddduck config path), roll back the
@@ -160,6 +222,7 @@ function initialize(args) {
   } finally {
     rmSync(stagingRoot, { recursive: true, force: true });
   }
+  if (!config.created) warnPinnedRepositoryDefault(config, destination);
   return {
     json: options.json,
     result: {
@@ -167,15 +230,46 @@ function initialize(args) {
       root: realpathSync(destination),
       affectedIds: [productId],
       canonicalPaths: ["product.yaml"],
-      generatedPaths: [
-        "generated/docs/model-overview.md",
-        "generated/graph/model-graph.json",
-        "generated/graph/model-graph.ndjson",
-      ],
+      generatedPaths: [...generatedPaths],
+      ...(config.created ? { configPath: config.configPath } : {}),
     },
   };
 }
 
+// A pre-existing repository config keeps selecting its own product root; a
+// second init must say so or every rootless command silently addresses the
+// other product.
+function warnPinnedRepositoryDefault(config, destination) {
+  let configuredRoot;
+  try {
+    const loaded = loadDdduckConfig(config.repositoryRoot);
+    if (!loaded) return;
+    configuredRoot = path.resolve(config.repositoryRoot, loaded.productRoot);
+  } catch {
+    return; // An unreadable config surfaces on the next root resolution.
+  }
+  if (canonicalPath(configuredRoot) === canonicalPath(destination)) return;
+  process.stderr.write(
+    `init: ${config.configPath} still selects ${configuredRoot} as the repository default root; pass --root or update the config to select ${path.resolve(destination)}.\n`,
+  );
+}
+
+function canonicalPath(candidate) {
+  try {
+    return realpathSync(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+
+/**
+ * Implement `ddduck check`: run check-model.mjs in a child process against the
+ * resolved root, then gate generated-view freshness (docs, graph JSON/NDJSON,
+ * and the SVG via a subprocess because rendering is async WASM) and refuse
+ * leftover interrupted-operation state. Busy roots exit 2 via ProductBusyError.
+ * @param {string[]} args - Arguments after the `check` command word.
+ * @returns {void}
+ */
 function executeChecker(args) {
   const { options } = parseCommandArgs(args, {
     options: {
@@ -186,6 +280,11 @@ function executeChecker(args) {
     },
   });
   const root = resolveProductRoot({ explicitRoot: options.root });
+  // Name the validated root when it was resolved implicitly, so a config-pinned
+  // root can never be validated invisibly. stderr keeps stdout script-safe.
+  if (!options.root) {
+    process.stderr.write(`check: validating ${root} (root resolved automatically; pass --root to override)\n`);
+  }
   assertProductNotBusy(root);
   const checkerArgs = [path.join(frameworkRoot, "scripts", "check-model.mjs"), "--root", root];
   if (options.base) checkerArgs.push("--base", path.resolve(options.base));
@@ -200,7 +299,8 @@ function executeChecker(args) {
   if (result.stdout) process.stdout.write(result.stdout);
   if (result.status !== 0) {
     const diagnostic = result.stderr.trim();
-    throw new CliUsageError(`Validation failed for ${root}${diagnostic ? `:\n${diagnostic}` : ""}`);
+    if (!diagnostic) throw new CliUsageError(`Validation failed for ${root}`);
+    throw validationFailureError(root, diagnostic.split("\n"));
   }
   if (options["source-only"]) return;
   try {
@@ -222,7 +322,11 @@ function executeChecker(args) {
     throw new Error(`Failed to run the model graph SVG check for ${root}: ${svgCheck.error.message}`);
   }
   if (svgCheck.status !== 0) {
-    const diagnostic = (svgCheck.stderr || "").trim() || "generated/graph/model-graph.svg is missing or stale";
+    // The standalone gate prints its own regenerate remedy; strip it here so
+    // the remedy appears exactly once, in the Next: line below.
+    const diagnostic =
+      (svgCheck.stderr || "").trim().replace(/; run ddduck generate --root [^\n]*/g, "") ||
+      "generated/graph/model-graph.svg is missing or stale";
     throw new CliUsageError(`Validation failed for ${root}: ${diagnostic}`, {
       nextAction: `Run ddduck generate --root ${root}, then re-run ddduck check.`,
     });
@@ -238,6 +342,12 @@ function executeChecker(args) {
   }
 }
 
+/**
+ * Implement `ddduck generate`: refresh every generated view through the locked
+ * staged operation runner with an empty (no canonical replacement) plan.
+ * @param {string[]} args - Arguments after the `generate` command word.
+ * @returns {void}
+ */
 function generate(args) {
   const { options } = parseCommandArgs(args, { options: { root: { value: true }, json: { value: false } } });
   const root = resolveProductRoot({ explicitRoot: options.root });
@@ -248,6 +358,14 @@ function generate(args) {
   writeProductOperationResult(result, options.json);
 }
 
+/**
+ * Implement the guarantee lifecycle commands create, move, split, and retire:
+ * parse per-command options, require a registered decision for split/retire,
+ * and run the resulting plan through the staged operation runner.
+ * @param {"create"|"move"|"split"|"retire"} command - Lifecycle command name.
+ * @param {string[]} args - Arguments after the command word.
+ * @returns {void}
+ */
 function transitionGuarantee(command, args) {
   const optionDefinitions = {
     create: {
@@ -307,6 +425,12 @@ function requireRegisteredDecision(root, decision, command) {
   );
 }
 
+/**
+ * Print an operation result as one text line or one JSON object (--json).
+ * @param {{operation: string, root: string, affectedIds: string[], canonicalPaths: string[], generatedPaths: string[], configPath?: string}} result - Result from the operation runner or init.
+ * @param {boolean} json - Emit JSON instead of the text form.
+ * @returns {void}
+ */
 function writeProductOperationResult(result, json) {
   if (json) {
     process.stdout.write(`${JSON.stringify(result)}\n`);
@@ -314,11 +438,21 @@ function writeProductOperationResult(result, json) {
   }
   const affected = result.affectedIds.length > 0 ? ` ${result.affectedIds.join(", ")}` : "";
   const canonical = result.canonicalPaths.length > 0 ? result.canonicalPaths.join(", ") : "none";
+  const config = result.configPath ? `; config: ${result.configPath} (created)` : "";
   process.stdout.write(
-    `${result.operation}${affected} in ${result.root}; canonical: ${canonical}; generated: ${result.generatedPaths.join(", ")}\n`,
+    `${result.operation}${affected} in ${result.root}; canonical: ${canonical}; generated: ${result.generatedPaths.join(", ")}${config}\n`,
   );
 }
 
+/**
+ * Build the operation plan for one guarantee lifecycle command from a frozen
+ * product snapshot; move/split/retire require the source guarantee to be active.
+ * @param {"create"|"move"|"split"|"retire"} command - Lifecycle command name.
+ * @param {{nodes: object[], canonicalPaths: Record<string, string>}} snapshot - Frozen staged product snapshot.
+ * @param {string|undefined} id - Target guarantee ID (absent for create).
+ * @param {Record<string, string|boolean>} options - Parsed command options.
+ * @returns {{operation: string, affectedIds: string[], replacements: {path: string, value: object}[]}} Plan for the operation runner.
+ */
 function buildGuaranteePlan(command, snapshot, id, options) {
   if (command === "create") return createGuarantee(snapshot, options);
   const guarantee = requireGuarantee(snapshot, id);
@@ -395,10 +529,14 @@ function moveGuarantee(snapshot, guarantee, destinationDomain) {
   if (guarantee.ownerDomain === destinationDomain)
     throw new Error(`${guarantee.id} is already owned by ${destinationDomain}`);
   const previousOwner = guarantee.ownerDomain;
+  // ownershipHistory lists former owning Domains only (model-reference.md), so
+  // an owner that regains the guarantee leaves the history again.
   const updated = {
     ...guarantee,
     ownerDomain: destinationDomain,
-    ownershipHistory: [...new Set([...(guarantee.ownershipHistory ?? []), previousOwner])],
+    ownershipHistory: [...new Set([...(guarantee.ownershipHistory ?? []), previousOwner])].filter(
+      (domainId) => domainId !== destinationDomain,
+    ),
   };
   return {
     operation: "move guarantee",
@@ -517,10 +655,16 @@ function writeYaml(filePath, value) {
   writeFileSync(filePath, stringify(value));
 }
 
+/**
+ * Write .ddduck/config.json at the repository root selecting the new product
+ * root, unless a config already exists (then it is left untouched).
+ * @param {string} destination - Absolute path of the freshly published product root.
+ * @returns {{configPath: string, repositoryRoot: string, created: boolean}} Where the config lives and whether it was created.
+ */
 function writeConfigIfAbsent(destination) {
   const repositoryRoot = findRepositoryRoot(destination);
   const configPath = path.join(repositoryRoot, ".ddduck", "config.json");
-  if (existsSync(configPath)) return;
+  if (existsSync(configPath)) return { configPath, repositoryRoot, created: false };
   const relativeProductRoot = path.relative(repositoryRoot, destination).split(path.sep).join("/");
   // findRepositoryRoot falls back to the destination itself when no enclosing
   // .git exists, which makes the relative path empty; "." keeps productRoot
@@ -531,6 +675,7 @@ function writeConfigIfAbsent(destination) {
     configPath,
     `${JSON.stringify({ schemaVersion: "1", productRoot, ignore: [...defaultConfigIgnore] }, null, 2)}\n`,
   );
+  return { configPath, repositoryRoot, created: true };
 }
 
 function nextActionFor(args) {

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

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 
+/**
+ * CLI wrapper for the agent-readiness report (`--root <product-root>`):
+ * delegates to lib/agent-readiness-report.mjs and prints the JSON report of
+ * missing evidence roles, unresolved references, stale generated views,
+ * orphaned nodes, and ambiguous ownership. Exits 1 when validation failed
+ * (report reduced to unresolvedReferences) or on any error.
+ */
+
 import path from "node:path";
 import { generateAgentReadinessReport } from "./lib/agent-readiness-report.mjs";
 

package/scripts/generate-docs.mjs

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
 
+/**
+ * Renders the generated Markdown view generated/docs/model-overview.md from a
+ * product root's canonical YAML: domains with their concepts, interfaces, and
+ * active guarantees, then use cases, interfaces, relationships, and decisions.
+ * Inactive (split/retired) guarantees are excluded. buildModelOverview feeds
+ * the freshness gate (check-generated-docs.mjs); writeModelOverview is called
+ * by init and the staged operation runner. Also runnable standalone via --root.
+ */
+
 import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -9,12 +18,22 @@ import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
 
 const outputPath = path.join("generated", "docs", "model-overview.md");
 
+/**
+ * Build the model overview Markdown for a product root without writing it.
+ * @param {string} rootPath - Product root path.
+ * @returns {string} The full generated Markdown document.
+ */
 export function buildModelOverview(rootPath) {
   const layout = detectProductLayout(rootPath);
   const graph = loadGraph(layout);
   return renderModelOverview(assembleModelView(graph, findModelId(graph)));
 }
 
+/**
+ * Write generated/docs/model-overview.md below the product root.
+ * @param {string} rootPath - Product root path.
+ * @returns {string} The root-relative path that was written.
+ */
 export function writeModelOverview(rootPath) {
   const output = buildModelOverview(rootPath);
   const absoluteOutputPath = resolveContainedOutput(rootPath, outputPath);
@@ -30,6 +49,14 @@ function loadGraph(layout) {
   };
 }
 
+/**
+ * Assemble the sorted, resolved view of the model that the renderer consumes:
+ * domains with their owned nodes resolved, relationships, decisions, use
+ * cases, and every DomainInterface in the product.
+ * @param {{nodes: Map<string, object>}} graph - Loaded product nodes (active guarantees only).
+ * @param {string} modelId - ID of the single Model node.
+ * @returns {{model: object, domains: object[], relationships: object[], decisions: string[], useCases: object[], interfaces: object[]}} The renderable view.
+ */
 function assembleModelView(graph, modelId) {
   const model = resolveNode(graph, modelId);
   const domains = asArray(model.domains)
@@ -62,8 +89,7 @@ function renderModelOverview(view) {
     "",
     `# ${view.model.name} (\`${view.model.id}\`)`,
     "",
-    `Name status: \`${view.model.nameStatus ?? "stable"}\``,
-    "",
+    ...(view.model.nameStatus === undefined ? [] : [`Name status: \`${view.model.nameStatus}\``, ""]),
     view.model.purpose,
     "",
     "## Domains",