ddduck 0.1.0 → 0.1.2

package/README.md

@@ -14,7 +14,7 @@ Every product renders to a verified graph of its model — the ownership spine
 line styles. `ddduck generate` produces it as a deterministic SVG. This
 framework's own model:
 
-![ddduck model graph: the framework's Model, its Domains and owned Concepts, Interfaces, Guarantees, and Use Cases, with a legend](https://raw.githubusercontent.com/diegomarino/ddduck/main/docs/ddd/generated/graph/model-graph.svg)
+![ddduck model graph: the framework's Model, its Domains and owned Concepts, and typed relationships, with a legend](https://raw.githubusercontent.com/diegomarino/ddduck/main/docs/ddd/generated/graph/model-graph.svg)
 
 ## Product layout
 
@@ -40,7 +40,9 @@ docs/ddd/
 `product.yaml` and files under `model/` are canonical source. `generated/` is derived
 output: never edit it by hand.
 
-Repository-local ddduck tool metadata lives outside the product root in `.ddduck/`. For example,
+Repository-local ddduck tool metadata lives outside the product root in `.ddduck/` at the
+enclosing repository root; without one, `ddduck init` writes it inside the new product root
+instead (see [the CLI reference](docs/cli.md#product-root-resolution)). For example,
 this framework repository stores its own model in `docs/ddd/` and records that selection in:
 
 ```json
@@ -57,7 +59,7 @@ and fully editable (see [the CLI reference](docs/cli.md)).
 
 ## Authoring
 
-Install the CLI from npm:
+Install the CLI from npm (requires Node.js 22 or newer):
 
 ```bash
 npm install -g ddduck
@@ -72,8 +74,9 @@ ddduck init ddd --id model:<product-id>
 ```
 
 `--root <path>` is always the explicit override; without it, ddduck resolves the enclosing
-product root, then `.ddduck/config.json`, then a unique repository candidate, and fails with a
-diagnostic when the choice is ambiguous. The mutation surface is deliberately narrow — `check`,
+product root, then `.ddduck/config.json`, then a unique repository candidate (see
+[the CLI reference](docs/cli.md#product-root-resolution) for the full order, including the
+example-candidate fallback), and fails with a diagnostic when the choice is ambiguous. The mutation surface is deliberately narrow — `check`,
 `generate`, and the `create`/`move`/`split`/`retire` Guarantee lifecycle commands — and every
 successful source mutation regenerates the derived views. The canonical resolution rules and
 command contracts live in [the CLI reference](docs/cli.md#product-root-resolution).

package/docs/architecture.md

@@ -61,8 +61,11 @@ flowchart LR
 
 ## Query boundary
 
-Queries are read-only and require `--json`. A context query returns selected canonical records,
-direct touching edges, one-hop summaries for unselected neighbors, and a source digest. It does
+Queries are read-only and always emit exactly one JSON document (`--json` is accepted as a
+no-op). A context query returns selected canonical records,
+direct touching edges, one-hop summaries for unselected neighbors, and a source digest. The
+source digest covers the canonical node YAML sources only — `product.yaml` and the files under
+`model/` — so decision records under `decisions/` are outside its scope. It does
 not recursively expand context or write canonical or generated files.
 
 ```mermaid

package/docs/cli.md

@@ -7,7 +7,12 @@ with `--` must use the `--option=value` form. Every command rejects unknown opti
 options, missing option values, and unexpected positional arguments. Expected failures write a
 concise diagnostic (multi-error validation reports keep one line per error) plus a safe next
 action to standard error and exit nonzero; errors without a specific next action fall back to a
-command-specific hint. Help exits zero.
+command-specific hint. Help exits zero. Exit codes are part of the contract: the one retryable
+failure — a busy product root, whose operation lock is held by a running process — exits 2, so
+retry logic never has to string-match standard error; every other failure exits 1.
+
+This package is published to npm as `ddduck`; install the CLI globally with `npm install -g ddduck`
+(see [the getting-started guide](getting-started.md#install-ddduck)).
 
 ## Product root resolution
 
@@ -44,51 +49,20 @@ Use `.ddduck/config.json` for a repository default:
 every ddduck scanner skips, in addition to the always-skipped dot-directories
 and `node_modules`. Omit the key to accept the defaults shown above; set it to
 `[]` to skip nothing beyond the built-in defaults. `ddduck init` writes this
-file pre-filled when it does not already exist.
-
-## Install an agent skill
-
-```text
-ddduck install skill update-ddduck-specs [--repo <repository-root>]
-```
-
-`--repo` defaults to the current directory. The installer chooses the least intrusive host
-topology from the repository's existing directories:
-
-```text
-no .agents/ or .claude/   -> .agents/skills/update-ddduck-specs/SKILL.md
-.agents/ only             -> .agents/skills/update-ddduck-specs/SKILL.md
-.claude/ only             -> .claude/skills/update-ddduck-specs/SKILL.md
-.agents/ and .claude/     -> .agents/skills/update-ddduck-specs/SKILL.md
-                             .claude/skills/update-ddduck-specs -> ../../.agents/skills/update-ddduck-specs
-```
-
-The installer writes `.ddduck/agent-skills.lock.json` with the selected canonical path, host
-adapters, package version, and installed `SKILL.md` SHA-256. It does not create a host directory
-for a host that is absent from the repository, except for the `.agents/` fallback when no host
-directory exists. On success it prints one result line naming the action (`created`, `upgraded`,
-or `no-op`), the repository, the canonical skill path, and the lock path. It does not accept
-`--json`.
-
-Invoke the skill from the relevant host:
-
-```text
-Codex:  $update-ddduck-specs
-Claude: /update-ddduck-specs
-```
-
-The skill defaults to plan-only; changing a product model requires explicit apply authorization.
-Its workflow behavior is defined by the installed `SKILL.md` (and its packaged
-[canonical source](../skills/update-ddduck-specs/SKILL.md)).
-
-This package is published to npm as `ddduck`; install the CLI globally with `npm install -g ddduck`
-(see [the getting-started guide](getting-started.md#install-ddduck)).
+file pre-filled when it does not already exist and reports the write in its result
+(`config: <path> (created)` in text, `configPath` in `--json`; omitted when the file
+pre-existed). The config is written at the enclosing repository root (the nearest ancestor
+containing `.git`); without one, at the destination directory itself, so the file then lives
+inside the new product root with `"productRoot": "."`. When the file already exists and selects a different product root, `init` prints a
+standard-error note that the repository default still selects that other root.
 
 ## Common behavior
 
 Product writes are `init`, `generate`, `create`, `move`, `split`, and `retire`; successful
 mutations regenerate all required views. `check` and every `query` are read-only. A successful
-`check` is silent. Successful product mutations print one concise result line, or one JSON result
+`check` writes nothing to standard output; when `--root` was omitted, it prints one standard-error
+note naming the validated root so an implicitly resolved (for example config-pinned) root is never
+validated invisibly. Successful product mutations print one concise result line, or one JSON result
 object when `--json` is available.
 
 ## `init`
@@ -103,8 +77,10 @@ ddduck init [destination] --id model:<product-id> [--json]
 | `--id`             | yes      | none                          | Root Model ID, matching `model:<lowercase-slug>`. |
 | `--json`           | no       | false                         | Emit one JSON result object instead of text.      |
 
-`init` writes the canonical directory layout, `product.yaml`, and fresh generated docs and graph
-views. It refuses a non-empty destination. On success it reports the Model ID, normalized root,
+`init` writes the canonical directory layout, `product.yaml`, and the four fresh generated views
+(`generated/docs/model-overview.md`, `generated/graph/model-graph.json`,
+`generated/graph/model-graph.ndjson`, and `generated/graph/model-graph.svg`). It refuses a
+non-empty destination. On success it reports the Model ID, normalized root,
 `product.yaml`, and all generated paths as one text line or, with `--json`, one object containing
 `operation`, `root`, `affectedIds`, `canonicalPaths`, and `generatedPaths`. On failure it exits
 nonzero without reporting success.
@@ -126,9 +102,12 @@ ddduck check [--root <product-root>] [--base <previous-product-root>] \
 By default, `check` validates canonical source, then requires fresh generated Markdown and graph
 views. Documentation references are validated only inside the product root; pass one or more
 `--docs-root` directories to widen (and replace) that scope, mirroring the framework's own
-repository-wide gate. It writes nothing and is quiet on success. It exits nonzero for invalid source, stale
-views, invalid roots, invalid options, a busy root (`.ddduck-operation.lock` held by a live
-ddduck operation), or leftover state from an interrupted operation
+repository-wide gate. Documentation-reference scanning always skips the `docs/audits` and
+`docs/superpowers` directories (paths relative to each scanned root). It writes nothing and keeps standard output empty on success; when `--root`
+was omitted, one standard-error note names the validated root. It exits 2 for a busy root
+(`.ddduck-operation.lock` held by a live ddduck operation — the retryable case), and 1 for
+invalid source, stale views, invalid roots, invalid options, or leftover state from an
+interrupted operation
 (`.ddduck-operation.lock`, `.ddduck-operation.reclaim`, or `.ddduck-operation-stage-*` with no
 live owning process); running any mutation, such as `ddduck generate`, reclaims that leftover
 state.
@@ -145,7 +124,8 @@ ddduck generate [--root <product-root>] [--json]
 | `--json` | false         | Emit one JSON mutation-result object instead of the text result line. |
 
 `generate` validates canonical source before writing `generated/docs/model-overview.md`,
-`generated/graph/model-graph.json`, and `generated/graph/model-graph.ndjson`. A successful text
+`generated/graph/model-graph.json`, `generated/graph/model-graph.ndjson`, and
+`generated/graph/model-graph.svg`. A successful text
 result identifies the root, canonical paths (none for generate), and generated paths. It exits
 nonzero without an intended product mutation if validation or contained-output checks fail.
 
@@ -205,13 +185,19 @@ staged validation exits nonzero without an intended mutation.
 
 Every query emits exactly one JSON document and writes no source or generated output. While a
 live ddduck mutation holds `.ddduck-operation.lock`, queries and `check` fail with a busy
-diagnostic instead of reading a partially published snapshot. A read racing the very start of a
+diagnostic (exit code 2, the retryable case) instead of reading a partially published snapshot.
+Queries also refuse leftover state from an interrupted operation — the same
+`.ddduck-operation.lock`, `.ddduck-operation.reclaim`, or `.ddduck-operation-stage-*` entries
+`check` reports — with exit code 1 and the reclaim next action (run any mutation, such as
+`ddduck generate`, to reclaim), because the snapshot may be partially published. A read racing the very start of a
 mutation, before the lock exists, may still observe a partial snapshot, so `sourceDigest` is
-authoritative only for reads that did not race a mutation. JSON is
+authoritative only for reads that did not race a mutation. `sourceDigest` covers the canonical
+node YAML sources only — `product.yaml` and the files under `model/` — not decision records:
+editing a file under `decisions/` does not change the digest. JSON is
 the only output format, so `--json` is optional and accepted as a no-op for compatibility. The
 document contains `schemaVersion`, `query`, `rootModelId`, `result`, and
-`diagnostics`. Non-context query roots are resolved through the common product-root rules.
-`context` requires an explicit `--root`. Non-context queries accept optional `--history`; without it, a split or retired
+`diagnostics`. Every query root is resolved through the common product-root rules.
+Non-context queries accept optional `--history`; without it, a split or retired
 Guarantee resolves to its lifecycle redirect rather than its historical contract.
 
 ```mermaid
@@ -232,8 +218,43 @@ sequenceDiagram
 | `ddduck query impact --id <id> [--root <root>] [--history] [--json]`       | `--id`           | Reverse impact closure over ownership and behavioral references.        |
 | `ddduck query anchors --id <id> [--root <root>] [--history] [--json]`      | `--id`           | Evidence, reachable decisions, policies, and view freshness.            |
 | `ddduck query spec [--id <model-id>] [--root <root>] [--history] [--json]` | none             | Root, domains, view freshness, and verification commands.               |
-| `ddduck query context --id <id> [--id <id> ...] --root <root> [--json]`    | `--id`, `--root` | Selected records, touching edges, one-hop summaries, and source digest. |
+| `ddduck query context --id <id> [--id <id> ...] [--root <root>] [--json]`  | `--id`           | Selected records, touching edges, one-hop summaries, and source digest. |
 
 `context` accepts one or more distinct, repeatable `--id` options; it rejects `--history`.
 Its selected records are complete, while unselected endpoints appear only as one-hop summaries.
 The command does not recursively expand the perimeter.
+
+## Install an agent skill
+
+```text
+ddduck install skill update-ddduck-specs [--repo <repository-root>]
+```
+
+`--repo` defaults to the current directory. The installer chooses the least intrusive host
+topology from the repository's existing directories:
+
+```text
+no .agents/ or .claude/   -> .agents/skills/update-ddduck-specs/SKILL.md
+.agents/ only             -> .agents/skills/update-ddduck-specs/SKILL.md
+.claude/ only             -> .claude/skills/update-ddduck-specs/SKILL.md
+.agents/ and .claude/     -> .agents/skills/update-ddduck-specs/SKILL.md
+                             .claude/skills/update-ddduck-specs -> ../../.agents/skills/update-ddduck-specs
+```
+
+The installer writes `.ddduck/agent-skills.lock.json` with the selected canonical path, host
+adapters, package version, and installed `SKILL.md` SHA-256. It does not create a host directory
+for a host that is absent from the repository, except for the `.agents/` fallback when no host
+directory exists. On success it prints one result line naming the action (`created`, `upgraded`,
+or `no-op`), the repository, the canonical skill path, and the lock path. It does not accept
+`--json`.
+
+Invoke the skill from the relevant host:
+
+```text
+Codex:  $update-ddduck-specs
+Claude: /update-ddduck-specs
+```
+
+The skill defaults to plan-only; changing a product model requires explicit apply authorization.
+Its workflow behavior is defined by the installed `SKILL.md` (and its packaged
+[canonical source](../skills/update-ddduck-specs/SKILL.md)).

package/docs/getting-started.md

@@ -4,7 +4,7 @@ This executable journey creates a product with one Domain, one Concept, and one
 
 ## Install ddduck
 
-Install the published CLI globally from npm:
+Requires Node.js 22 or newer. Install the published CLI globally from npm:
 
 ```sh
 npm install -g ddduck
@@ -15,7 +15,7 @@ To contribute or run an unreleased revision, work from a local checkout instead.
 `ddduck` bin on `PATH` with `npm link`:
 
 ```sh
-git clone <ddduck-repository-url> ddduck
+git clone https://github.com/diegomarino/ddduck.git ddduck
 cd ddduck
 npm install
 npm link
@@ -30,7 +30,10 @@ node <checkout>/scripts/ddduck.mjs --help
 
 ## Create the first product
 
-Run the complete Bash block from an empty working directory with `ddduck` on `PATH`.
+Run the complete Bash block from an empty working directory with `ddduck` on `PATH`, normally
+inside a Git repository: `init` records the repository default in `.ddduck/config.json` at the
+repository root, and without one writes it inside the new product root instead (see
+[the CLI reference](cli.md#product-root-resolution)).
 
 ```mermaid
 flowchart LR

package/docs/model-reference.md

@@ -11,6 +11,8 @@ The checker requires exactly one Model root.
 `product.yaml` is the only `Model` node. Unlike every child node, it has no `model` field.
 Required fields are `schemaVersion`, `kind`, `id`, `name`, `purpose`, and `domains`. Optional
 top-level fields include `nameStatus`, `useCases`, `relationships`, `decisions`, and `notes`.
+`nameStatus` is a free-form string describing how settled the model name is (for example
+`stable` or `provisional`); generated views show it only when it is declared.
 
 ```yaml
 schemaVersion: "1"
@@ -87,6 +89,8 @@ records former owning Domains. Evidence anchors are also supported.
 
 Evidence anchors contain a product-relative `path`, `anchor`, and `role` (`source`, `decision`,
 or `verification`). The path must resolve to a regular file inside the selected product root.
+For Markdown (`.md`) paths the checker also verifies that the `anchor` string occurs in the
+file content; for non-Markdown paths the anchor is a free-form label and is not content-checked.
 
 For full schema constraints, inspect the shipped files under `schemas/product/`; use
 [the getting-started guide](getting-started.md) for the minimal working path.

package/docs/model.md

@@ -20,6 +20,7 @@ docs/ddd/
     docs/model-overview.md
     graph/model-graph.json
     graph/model-graph.ndjson
+    graph/model-graph.svg
 ```
 
 `product.yaml` and `model/**/*.yaml` are canonical. `generated/` is derived output and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ddduck",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "An opinionated DDD framework for authoring, validating, and visualizing machine-readable product-spec models.",
   "keywords": [
     "ddd",
@@ -23,7 +23,7 @@
     "url": "https://github.com/diegomarino/ddduck/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "type": "module",
   "files": [
@@ -41,7 +41,8 @@
     "ddduck": "scripts/ddduck.mjs"
   },
   "scripts": {
-    "check": "npm run check:model && npm run check:docs && npm run check:graph && npm run check:graph:svg && npm run lint && npm run lint:md && npm run format:check && npm test",
+    "check": "npm run check:static && npm test",
+    "check:static": "npm run check:model && npm run check:docs && npm run check:graph && npm run check:graph:svg && npm run lint && npm run lint:md && npm run format:check",
     "check:docs": "node scripts/check-generated-docs.mjs",
     "check:graph": "node scripts/check-generated-graph.mjs",
     "check:graph:svg": "node scripts/check-generated-graph-svg.mjs",
@@ -51,7 +52,7 @@
     "generate:graph": "node scripts/generate-graph.mjs",
     "generate:graph:svg": "node scripts/generate-graph-svg.mjs",
     "lint": "eslint .",
-    "lint:md": "markdownlint-cli2 \"*.md\" \"docs/**/*.md\" \"examples/**/*.md\"",
+    "lint:md": "markdownlint-cli2 \"*.md\" \"docs/**/*.md\" \"examples/**/*.md\" \"#CHANGELOG.md\" \"#docs/audits\" \"#docs/superpowers\"",
     "test": "node --test test/*.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage test/*.test.mjs",
     "pack:dry-run": "npm pack --dry-run --cache .npm-cache",

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

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+/**
+ * CLI for verifying FR-to-code audit records (`audit-fr-to-code --input
+ * <audit.yaml> --source-root <source-id>=<checkout> --json`). Reads the YAML
+ * audit record, binds each declared source to a local git checkout whose
+ * origin URL and pinned 40-hex revision must match, reads anchored files via
+ * `git show` at that exact revision (regular-file tree entries only), and
+ * delegates verdict verification to lib/fr-to-code-audit.mjs, emitting one
+ * JSON report on stdout.
+ */
+
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -7,6 +17,13 @@ import { parseDocument } from "yaml";
 import { verifyFrToCodeAudit } from "./lib/fr-to-code-audit.mjs";
 import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
 
+/**
+ * Parse arguments, verify the audit record against its pinned sources, and
+ * write the JSON report.
+ * @param {string[]} args - CLI arguments (--input, repeatable --source-root, --json).
+ * @param {{stdout?: {write: (chunk: string) => unknown}}} [io] - Output stream override for tests.
+ * @returns {void}
+ */
 export function runFrToCodeAudit(args, { stdout = process.stdout } = {}) {
   if (args.length === 1 && args[0] === "--help") {
     stdout.write(renderHelp("audit-fr-to-code"));
@@ -61,6 +78,14 @@ function validateDeclaredSources(record, filePath) {
   }
 }
 
+/**
+ * Build the source reader that serves file contents from pinned git revisions.
+ * Requires exactly one --source-root mapping per declared source and verifies
+ * each checkout's origin URL and revision presence up front.
+ * @param {{sources: {id: string, repository: string, revision: string}[]}} record - The validated audit record.
+ * @param {{id: string, root: string}[]} sourceRoots - Parsed --source-root mappings.
+ * @returns {{readFile: (source: object, relativePath: string) => string}} Reader handed to verifyFrToCodeAudit.
+ */
 function createGitSourceReader(record, sourceRoots) {
   if (!Array.isArray(record.sources)) throw new Error("audit input must declare sources");
   const declaredIds = new Set(record.sources.map((source) => source?.id));

package/scripts/check-generated-docs.mjs

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 
+/**
+ * Freshness gate for the generated docs view: rebuilds
+ * generated/docs/model-overview.md from the canonical YAML and compares it
+ * byte-for-byte against the committed file. Consumed by `ddduck check` and the
+ * staged operation runner (both import checkGeneratedDocs); also runnable
+ * standalone, where a stale view exits 1 with a regenerate remedy.
+ */
+
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,10 +16,21 @@ import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
 
 const outputPath = path.join("generated", "docs", "model-overview.md");
 
-function staleMessage(root) {
-  return `${outputPath} is missing or stale; run ddduck generate --root ${root}`;
+// The message states the fact only, so callers that add their own next-action
+// line never state the remedy twice; `remedy` carries the regenerate hint for
+// callers with no next-action surface (the standalone gate below).
+function staleError(root) {
+  const error = new Error(`${outputPath} is missing or stale`);
+  error.remedy = `run ddduck generate --root ${root}`;
+  return error;
 }
 
+/**
+ * Throw if generated/docs/model-overview.md is missing or differs from the
+ * output rebuilt from the current canonical YAML.
+ * @param {string} rootPath - Product root path.
+ * @returns {void}
+ */
 export function checkGeneratedDocs(rootPath) {
   const root = path.resolve(rootPath);
   const expected = buildModelOverview(root);
@@ -19,10 +38,10 @@ export function checkGeneratedDocs(rootPath) {
   try {
     actual = readFileSync(path.join(root, outputPath), "utf8");
   } catch (error) {
-    if (error.code === "ENOENT") throw new Error(staleMessage(root));
+    if (error.code === "ENOENT") throw staleError(root);
     throw error;
   }
-  if (actual !== expected) throw new Error(staleMessage(root));
+  if (actual !== expected) throw staleError(root);
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
@@ -31,7 +50,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
     checkGeneratedDocs(resolveProductRoot({ explicitRoot: options.root }));
     if (options.verbose) console.log("generated docs ok");
   } catch (error) {
-    console.error(error.message);
+    console.error(error.remedy ? `${error.message}; ${error.remedy}` : error.message);
     process.exit(1);
   }
 }

package/scripts/check-generated-graph-svg.mjs

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
 
+/**
+ * Freshness gate for the canonical SVG view generated/graph/model-graph.svg.
+ * Rendering uses the async Graphviz WASM engine, so unlike the docs and
+ * JSON/NDJSON gates this one is always executed as a child process by
+ * `ddduck check`, the staged operation runner, and query freshness — never
+ * imported into their synchronous flows. Standalone runs exit 1 on a missing
+ * or stale SVG with a regenerate remedy.
+ */
+
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -7,13 +16,22 @@ import { buildModelGraph } from "./generate-graph.mjs";
 import { buildModelGraphSvg, svgOutputPath } from "./generate-graph-svg.mjs";
 import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
 
-function staleMessage(root) {
-  return `${svgOutputPath} is missing or stale; run ddduck generate --root ${root}`;
+// The message states the fact only, so callers that add their own next-action
+// line never state the remedy twice; `remedy` carries the regenerate hint for
+// callers with no next-action surface (the standalone gate below).
+function staleError(root) {
+  const error = new Error(`${svgOutputPath} is missing or stale`);
+  error.remedy = `run ddduck generate --root ${root}`;
+  return error;
 }
 
-// Pin the canonical SVG byte-for-byte: rebuild it from the source model and
-// compare against the committed file. Deterministic because @hpcc-js/wasm is
-// version-pinned in the lockfile (the SVG embeds its Graphviz version).
+/**
+ * Pin the canonical SVG byte-for-byte: rebuild it from the source model and
+ * compare against the committed file. Deterministic because @hpcc-js/wasm is
+ * version-pinned in the lockfile (the SVG embeds its Graphviz version).
+ * @param {string} rootPath - Product root path.
+ * @returns {Promise<void>} Rejects when the SVG is missing or stale.
+ */
 export async function checkGeneratedGraphSvg(rootPath) {
   const root = path.resolve(rootPath);
   const expected = await buildModelGraphSvg(buildModelGraph(root));
@@ -21,10 +39,10 @@ export async function checkGeneratedGraphSvg(rootPath) {
   try {
     actual = readFileSync(path.join(root, svgOutputPath), "utf8");
   } catch (error) {
-    if (error.code === "ENOENT") throw new Error(staleMessage(root));
+    if (error.code === "ENOENT") throw staleError(root);
     throw error;
   }
-  if (actual !== expected) throw new Error(staleMessage(root));
+  if (actual !== expected) throw staleError(root);
 }
 
 function parseArgs(args) {
@@ -54,7 +72,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
     await checkGeneratedGraphSvg(resolveProductRoot({ explicitRoot: options.root }));
     if (options.verbose) console.log("generated graph svg ok");
   } catch (error) {
-    console.error(error.message);
+    console.error(error.remedy ? `${error.message}; ${error.remedy}` : error.message);
     process.exit(1);
   }
 }

package/scripts/check-generated-graph.mjs

@@ -1,15 +1,35 @@
 #!/usr/bin/env node
 
+/**
+ * Freshness gate for the generated graph views: rebuilds
+ * generated/graph/model-graph.json and .ndjson from the canonical YAML and
+ * compares each byte-for-byte against the committed files. Consumed by
+ * `ddduck check` and the staged operation runner (both import
+ * checkGeneratedGraph); also runnable standalone, where a stale view exits 1
+ * with a regenerate remedy.
+ */
+
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildModelGraphOutputs, jsonOutputPath, ndjsonOutputPath } from "./generate-graph.mjs";
 import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
 
-function staleMessage(relativePath, root) {
-  return `${relativePath} is missing or stale; run ddduck generate --root ${root}`;
+// The message states the fact only, so callers that add their own next-action
+// line never state the remedy twice; `remedy` carries the regenerate hint for
+// callers with no next-action surface (the standalone gate below).
+function staleError(relativePath, root) {
+  const error = new Error(`${relativePath} is missing or stale`);
+  error.remedy = `run ddduck generate --root ${root}`;
+  return error;
 }
 
+/**
+ * Throw if model-graph.json or model-graph.ndjson is missing or differs from
+ * the outputs rebuilt from the current canonical YAML.
+ * @param {string} rootPath - Product root path.
+ * @returns {void}
+ */
 export function checkGeneratedGraph(rootPath) {
   const root = path.resolve(rootPath);
   const expected = buildModelGraphOutputs(root);
@@ -23,13 +43,13 @@ function checkOutput(root, relativePath, expected) {
     actual = readFileSync(path.join(root, relativePath), "utf8");
   } catch (error) {
     if (error.code === "ENOENT") {
-      throw new Error(staleMessage(relativePath, root));
+      throw staleError(relativePath, root);
     }
     throw error;
   }
 
   if (actual !== expected) {
-    throw new Error(staleMessage(relativePath, root));
+    throw staleError(relativePath, root);
   }
 }
 
@@ -60,7 +80,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
     checkGeneratedGraph(resolveProductRoot({ explicitRoot: options.root }));
     if (options.verbose) console.log("generated graph ok");
   } catch (error) {
-    console.error(error.message);
+    console.error(error.remedy ? `${error.message}; ${error.remedy}` : error.message);
     process.exit(1);
   }
 }