ddduck 0.1.2 → 0.2.0

package/README.md

@@ -4,6 +4,8 @@ ddduck defines a small, machine-readable product-spec format. The framework keep
 schemas, validators, policies, and generators separate from each consumer product.
 
 Start with [the getting-started guide](docs/getting-started.md) for a working first product.
+For an unsettled product question or a proposed change, use the optional
+[definition-to-planning workflow](docs/definition-workflow.md) and reuse your existing brief.
 Then use [the model guide](docs/model.md), [the model reference](docs/model-reference.md),
 [the CLI reference](docs/cli.md), and [the architecture guide](docs/architecture.md) as needed.
 
@@ -76,8 +78,8 @@ 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 (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
+example-candidate fallback), and fails with a diagnostic when the choice is ambiguous. The mutation surface is deliberately narrow —
+`generate`, domain/concept/use-case creation, 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/cli.md

@@ -59,7 +59,7 @@ 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
+mutations regenerate all required views. `check`, `diff`, and every `query` are read-only. A successful
 `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
@@ -129,6 +129,65 @@ ddduck generate [--root <product-root>] [--json]
 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.
 
+## `diff`
+
+```text
+ddduck diff --base <previous-product-root> [--root <product-root>] [--json]
+```
+
+Compare two independently valid versions of the same Model by stable node ID. `--base` is
+required and `--root` uses normal root resolution. Generated output may be absent or stale.
+The command does not apply historical retention validation first: removing a Guarantee must
+remain visible in the comparison even when a subsequent `check --base` rejects that removal.
+
+The text report shows IDs, field changes, and path relocations. `--json` emits one
+`ModelDiff` version `"1"` document conforming to `schemas/model-diff.schema.json`:
+
+- `before` and `after` contain `modelId` and canonical `sourceDigest`.
+- `added` and `removed` contain full records with their product-relative source paths.
+- `changed` contains field changes keyed by escaped JSON Pointer paths. `beforePresent` and
+  `afterPresent` distinguish absent fields from explicit null values.
+- `relocated` records path changes without treating the same ID as a new record.
+- `scope` is `canonical-yaml-only`; `excludedScopes` names decision content, evidence content,
+  delivery artifacts, and runtime.
+
+Object-key order, comments, and YAML formatting are not record differences. Array order is
+preserved, so a reordered list is reported. Raw canonical-file changes still affect digests.
+Neither the digests nor an empty comparison establish ADR/evidence freshness or semantic
+equivalence. Source reads are not atomic snapshots; run comparisons while neither root is
+being edited. Busy and interrupted roots are refused.
+
+Exit 0 means comparison completed, including when changes exist; it is not an approval.
+Exit 2 means busy, and exit 1 covers invalid or incompatible inputs. Use existing `impact`
+and `neighbors` queries on both roots to inspect changed/removed context, then review meaning
+and run historical retention checking separately.
+
+## Creating domains, concepts, and use cases
+
+```text
+ddduck create domain --id domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]
+ddduck create concept --id concept:<slug> --owner domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]
+ddduck create use-case --file <yaml-file> [--root <product-root>] [--json]
+```
+
+Domain creation writes the node and adds its ID to the Model's `domains` list. Concept creation
+writes the node and adds its ID to the owning Domain's `concepts` list. These forms require
+every displayed field; they take model identity from the selected product.
+
+Use-case creation reads a complete canonical `UseCase` YAML mapping. Its `model` must match
+the selected product and all Guarantee/interface references must already resolve. It writes
+the new node and adds its ID to the Model's `useCases` list without changing the input file.
+An empty prerequisite or outcome list is allowed; the tool does not invent obligations.
+
+All three forms derive the destination filename from the validated ID. Duplicate IDs,
+occupied canonical paths, unknown fields, invalid references, or validation/generation
+failures reject the operation without intended publication. Successful operations update
+the owning collection and generate all views through the existing staged mutation runner.
+There is no overwrite mode. Existing YAML comments and unrelated parent fields are retained.
+The result has `operation`, `root`, `affectedIds` (new node and parent), `canonicalPaths`, and
+`generatedPaths`; append `--json` for one JSON document. Publication has the filesystem
+interruption limitations described in the [architecture guide](architecture.md#staged-lifecycle-mutation).
+
 ## Guarantee mutations
 
 All mutation results identify the selected root, affected Guarantee IDs, canonical paths, and
@@ -242,10 +301,12 @@ no .agents/ or .claude/   -> .agents/skills/update-ddduck-specs/SKILL.md
 ```
 
 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
+adapters, package version, installed file manifest, `SKILL.md` SHA-256, and whole-bundle SHA-256.
+It installs `SKILL.md` and its bundled `references/` directory, refuses locally modified managed
+files, and upgrades legacy single-file locks without overwriting extra local files. 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:
@@ -256,5 +317,5 @@ 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)).
+Its workflow behavior is defined by the installed skill bundle (see its packaged
+[canonical entrypoint](../skills/update-ddduck-specs/SKILL.md)).

package/docs/definition-workflow.md

@@ -0,0 +1,130 @@
+# From a product question to a planning brief
+
+Start with the question, not a YAML record. Reuse an existing proposal or design brief;
+the [optional change brief](templates/change-brief.md) is a checklist for missing context,
+not a required document. A short note can be enough.
+
+## Explore, decide, then model
+
+1. Identify the actor and problem with concrete success and refusal examples.
+2. Separate observed evidence from accepted intent and open questions. Record alternatives
+   and contradictory evidence with provenance.
+3. Make the semantic decision explicit. Record the decision and rationale in the brief;
+   create an ADR only for a consequential, durable choice that needs its own history.
+4. Update canonical YAML only where accepted meaning changed. Preserve stable IDs and use
+   lifecycle commands for Guarantee transitions. A partial update can encode independent
+   accepted obligations while an unresolved question stays in prose. Zero model change is
+   correct when the existing model suffices, the change is implementation-only, or no
+   decision has been reached.
+5. Validate structure and refresh derived views, then hand selected context to the planner
+   with delivery intent, scope, exclusions, dependencies, and acceptance examples.
+
+**Observed** means evidence was inspected, not endorsed. **Open** means undecided.
+**Accepted** means intended behavior, possibly not implemented. **Rejected** records an
+alternative and rationale. These are prose labels, not new schema fields or Guarantee
+statuses. A passing checker settles none of these semantic decisions.
+
+For example, an admin capability need not be a member role. Existing code that grants one
+from the other establishes observed behavior; whether that coupling is intended remains a
+decision. Likewise, delivering a relay directive does not establish that the recipient
+enacted it. Leave an unanswered question about who may authorize it open rather than
+inventing an authority boundary.
+
+## Model only what helps a decision
+
+| Kind         | Useful meaning                                                             | Counterexample to avoid                            |
+| ------------ | -------------------------------------------------------------------------- | -------------------------------------------------- |
+| Domain       | A distinct product responsibility                                          | A domain for each package or screen                |
+| Concept      | Vocabulary needed to reason about behavior                                 | A concept for every class, queue, or button        |
+| Guarantee    | An observable obligation or invariant                                      | “Best effort delivery” with no concrete commitment |
+| Use case     | An actor's goal and the obligations it requires, preserves, or establishes | An implementation task list                        |
+| Relationship | A connection worth reviewing, with its meaning stated                      | Treating every connection as a causal dependency   |
+
+Interfaces are optional. A useful behavioral model can have none. Empty prerequisite lists
+are not inherently wrong; add a reference when it expresses a real prerequisite, not to
+make the diagram look complete.
+
+For a small relay, introducing separate UI, transport, and receipt domains and
+concepts would obscure the one responsibility under discussion. Three cohesive obligations
+can distinguish authorization/refusal, the limit of delivery, and honest reporting. Do not
+split every clause: split when meaning, change, or verification is independent. Remove an
+extra Guarantee, domain, brief section, or review step when it answers no additional question.
+Consumer practice is inspiration, not proof that its artifact count or boundaries are right.
+
+The [relay walkthrough](https://github.com/diegomarino/ddduck/tree/main/examples/control-relay)
+is a fictional educational scenario. The
+[reminders scenario](https://github.com/diegomarino/ddduck/tree/main/examples/reminders)
+illustrates refusal. Neither specifies a real product or runs an application.
+
+## Author and review with existing tools
+
+After hand edits, `generate` validates the staged source and generated outputs before
+publishing derived views. It is the normal refresh action. Run operations serially against a root.
+
+```bash
+ddduck generate --root <root>
+ddduck check --root <root>
+```
+
+An optional `ddduck check --root <root> --source-only` diagnoses canonical edits before
+generation; `query spec` can inspect individual view freshness when needed.
+`check` is read-only and suitable for CI/final readback. Fresh generated views establish
+consistency with source, not product acceptance or runtime correctness.
+
+For each selected ID, compose the existing reads:
+
+```bash
+ddduck query impact --id <id> --root <root> --json
+ddduck query neighbors --id <id> --root <root> --json
+ddduck query node --id <relationship-id> --root <root> --json
+ddduck query context --id <id> --root <root> --json
+```
+
+Impact follows reverse owns/requires/preserves/establishes/uses/guarantees edges.
+Neighbors exposes direct incoming/outgoing edges, including explicit relationships. Read
+the relationship record for its type, description, and constraints when needed. These are
+review candidates requiring judgment; an empty result does not establish absence of risk.
+To select explicit relationships, filter both edge lists by `edge.kind === 'relationship'`
+and deduplicate by `edge.id`; a self-relationship appears in both lists. If the changed ID
+is itself a Relationship, query its record and inspect its `from` and `to` endpoints:
+neighbors matches endpoint IDs, not the relationship record's ID.
+There is no separate review query. Do not infer transitive effects from relationship names.
+Separate query calls are not an atomic snapshot: keep the source stable during review and
+re-read if it changes. A source digest identifies the read source only when it did not race
+a mutation; it does not make multiple reads transactionally consistent.
+
+Inspect before and after roots when something moves or disappears. In the fictional
+ownership fixture, the same Guarantee moves from Members to Reminders within the small
+reference corpus:
+review its owner, both domains' lists, wording, and use-case references without inventing a
+new ID. Read-only current-root queries alone cannot recover removed context. External feature
+references remain the consumer bridge's responsibility.
+
+The comparison command is:
+
+```text
+ddduck diff --base <root> [--root <root>] [--json]
+```
+
+Its scope is canonical YAML records by stable identity, not decision/evidence
+content, delivery artifacts, or runtime. Keep semantic review separate from structural
+comparison and historical retention checking.
+
+Use the implemented [domain, concept, and use-case creation commands](cli.md#creating-domains-concepts-and-use-cases)
+to create records and update their parent lists coherently. Use-case creation consumes a
+complete canonical YAML mapping; it does not invent obligations or decisions. See that
+reference for syntax and refusal behavior. Schema-guided hand edits remain useful for
+changes outside these helpers; update ownership/reference lists together before generation.
+
+## Hand off intent, not just a graph
+
+Select canonical context explicitly and link it from the receiving plan. Add why the work
+is needed, scope and non-goals, success/refusal examples, dependencies, exclusions, open
+decisions, and the next verification required. Reuse the exploration brief if it already
+answers those questions; do not maintain duplicate requirement prose or a second backlog.
+
+State evidence levels precisely: inspected implementation, declared evidence anchors,
+structural checks, tests actually executed, and observed runtime are different claims.
+An audit verdict is a declared assessment whose anchor integrity is checked; readiness
+roles and valid links do not prove behavioral coverage. Keep anchors inside the supported
+product root, and never create fake executable evidence or bridge documents to fill gaps.

package/docs/getting-started.md

@@ -1,6 +1,8 @@
 # Getting started
 
 This executable journey creates a product with one Domain, one Concept, and one Guarantee.
+For help deciding what belongs in that model, start with the
+[definition workflow](definition-workflow.md).
 
 ## Install ddduck
 
@@ -37,9 +39,9 @@ repository root, and without one writes it inside the new product root instead (
 
 ```mermaid
 flowchart LR
-  Source[Manual canonical YAML edit] --> SourceCheck[ddduck check --source-only]
-  SourceCheck -->|valid| Generate[ddduck generate]
-  SourceCheck -->|invalid| Diagnostic[Actionable diagnostic]
+  Create[ddduck create] --> FreshCheck[ddduck check]
+  Source[Manual canonical YAML edit] --> Generate[ddduck generate]
+  Generate -->|invalid source| Diagnostic[Actionable diagnostic]
   Generate --> FreshCheck[ddduck check]
   FreshCheck --> Docs[Generated Markdown is fresh]
   FreshCheck --> Graph[Generated graph is fresh]
@@ -48,54 +50,22 @@ flowchart LR
 ```bash
 ddduck init ddd --id model:library
 
-cat > ddd/model/domains/catalog.yaml <<'YAML'
-schemaVersion: "1"
-kind: Domain
-id: domain:catalog
-model: model:library
-name: Catalog
-purpose: Organize the library catalog.
-concepts:
-  - concept:book
-interfaces: []
-guarantees: []
-YAML
-
-cat > ddd/model/concepts/book.yaml <<'YAML'
-schemaVersion: "1"
-kind: Concept
-id: concept:book
-model: model:library
-ownerDomain: domain:catalog
-name: Book
-purpose: Identify a catalogued book.
-YAML
-
-cat > ddd/product.yaml <<'YAML'
-schemaVersion: "1"
-kind: Model
-id: model:library
-name: library
-purpose: Define the library product.
-domains:
-  - domain:catalog
-useCases: []
-decisions: []
-YAML
-
-ddduck check --root ddd --source-only
-ddduck generate --root ddd
-ddduck check --root ddd
+ddduck create domain --id domain:catalog --name Catalog \
+  --purpose "Organize the library catalog." --root ddd
+ddduck create concept --id concept:book --owner domain:catalog --name Book \
+  --purpose "Identify a catalogued book." --root ddd
 ddduck create guarantee --origin catalog --classification invariant \
   --owner domain:catalog --statement "A Book has a stable catalog identity." --root ddd
+ddduck check --root ddd
 ddduck query spec --root ddd --json
 ```
 
 Default `check` requires both valid canonical source and fresh generated views. After a manual
-source edit, use `check --source-only`, run `generate`, then use default `check`. Do not edit
-`generated/` by hand.
+source edit, `ddduck generate --root ddd` validates the source and refreshes the views;
+use `ddduck check --root ddd` for final readback or CI. To diagnose source without writing
+anything, run `ddduck check --root ddd --source-only`. Do not edit `generated/` by hand.
 
-The successful `create` allocates the first catalog invariant serial, adds it to the Domain, and
-refreshes all generated views. The final query emits one JSON document suitable for a tool or
+Each successful `create` updates the owning collection and refreshes all generated views.
+Guarantee creation allocates the first catalog invariant serial. The final query emits one JSON document suitable for a tool or
 agent. See the [model reference](model-reference.md) before adding other node kinds, and use the
 [CLI reference](cli.md) for the complete command contracts.

package/docs/templates/change-brief.md

@@ -0,0 +1,48 @@
+# Optional change brief
+
+Reuse an existing proposal, issue, or design brief first. Keep only sections that help a
+decision; a few paragraphs may suffice. This file is not a canonical schema or a second backlog.
+Use Observed, Open, Accepted, and Rejected as prose labels, never YAML lifecycle states.
+
+## Problem and actor
+
+Who needs what outcome, and why now?
+
+## Examples and refusal cases
+
+Describe concrete success, refusal, and uncertainty cases. Label expected behavior separately
+from results actually observed.
+
+## Observed evidence
+
+Cite paths and headings, symbols, or tests; state provenance, inspected scope, and gaps.
+Observed implementation may be a bug rather than intended behavior.
+
+## Accepted constraints
+
+Record accepted intent and its authority. Accepted does not mean implemented.
+
+## Alternatives
+
+Include doing nothing or reusing existing obligations, with tradeoffs and rejected choices.
+
+## Open questions and conflicts
+
+What still needs a decision? Which work depends on it? Keep unresolved assertions out of YAML.
+
+## Affected canonical IDs
+
+Select existing records explicitly; label proposed additions as proposals. Use fenced code
+for IDs from another product when the repository scans documentation references.
+Record partial or zero-model-change outcomes with a reason.
+
+## Decision and rationale
+
+Record who accepted what and why, plus what remains open. Link an ADR only if the durable
+decision warrants a separate artifact.
+
+## Planning handoff
+
+Link the receiving plan and provide intent, scope, non-goals, acceptance/refusal examples,
+dependencies, exclusions, unresolved decisions, and selected canonical context. State what
+was verified, by which commands, and what has not been executed. A graph is not a delivery plan.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ddduck",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "An opinionated DDD framework for authoring, validating, and visualizing machine-readable product-spec models.",
   "keywords": [
     "ddd",
@@ -32,6 +32,8 @@
     "policies/",
     "skills/",
     "docs/architecture.md",
+    "docs/definition-workflow.md",
+    "docs/templates/change-brief.md",
     "docs/getting-started.md",
     "docs/model.md",
     "docs/model-reference.md",
@@ -72,6 +74,6 @@
     "prettier": "^3.9.6"
   },
   "overrides": {
-    "fast-uri": "^3.1.5"
+    "fast-uri": "^3.1.7"
   }
 }

package/schemas/model-diff.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ddduck.local/schemas/model-diff.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "before",
+    "after",
+    "scope",
+    "excludedScopes",
+    "added",
+    "removed",
+    "changed",
+    "relocated"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1" },
+    "kind": { "const": "ModelDiff" },
+    "before": { "$ref": "#/$defs/identity" },
+    "after": { "$ref": "#/$defs/identity" },
+    "scope": { "const": "canonical-yaml-only" },
+    "excludedScopes": { "const": ["decision-content", "evidence-content", "delivery-artifacts", "runtime"] },
+    "added": { "type": "array", "items": { "$ref": "#/$defs/record" } },
+    "removed": { "type": "array", "items": { "$ref": "#/$defs/record" } },
+    "changed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "changes"],
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "type": "string" },
+          "changes": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/change" } }
+        }
+      }
+    },
+    "relocated": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "beforePath", "afterPath"],
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "type": "string" },
+          "beforePath": { "type": "string" },
+          "afterPath": { "type": "string" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["modelId", "sourceDigest"],
+      "properties": {
+        "modelId": { "type": "string", "pattern": "^model:" },
+        "sourceDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "record": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "sourcePath", "node"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "type": "string" },
+        "sourcePath": { "type": "string" },
+        "node": { "type": "object" }
+      }
+    },
+    "change": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "beforePresent", "afterPresent"],
+      "properties": {
+        "path": { "type": "string", "pattern": "^(?:/(?:[^~/]|~[01])*)+$" },
+        "beforePresent": { "type": "boolean" },
+        "afterPresent": { "type": "boolean" },
+        "before": {},
+        "after": {}
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "beforePresent": { "const": true } } },
+          "then": { "required": ["before"] },
+          "else": { "not": { "required": ["before"] } }
+        },
+        {
+          "if": { "properties": { "afterPresent": { "const": true } } },
+          "then": { "required": ["after"] },
+          "else": { "not": { "required": ["after"] } }
+        },
+        {
+          "anyOf": [
+            { "properties": { "beforePresent": { "const": true } } },
+            { "properties": { "afterPresent": { "const": true } } }
+          ]
+        }
+      ]
+    }
+  }
+}

package/scripts/ddduck.mjs

@@ -44,6 +44,9 @@ import { defaultConfigIgnore, findRepositoryRoot, loadDdduckConfig } from "./lib
 import { installSkill } from "./lib/skill-installer.mjs";
 import { runQuery } from "./query-model.mjs";
 import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
+import { buildAuthoringPlan } from "./lib/product-authoring.mjs";
+import { parseYamlMapping } from "./lib/product-layout.mjs";
+import { compareProductRoots, renderProductDiff } from "./lib/product-diff.mjs";
 
 const frameworkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -68,7 +71,7 @@ function run(args) {
   const [command, ...commandArgs] = args;
   if (
     !command ||
-    !["init", "check", "generate", "query", "install", "create", "move", "split", "retire"].includes(command)
+    !["init", "check", "generate", "query", "diff", "install", "create", "move", "split", "retire"].includes(command)
   ) {
     throw new CliUsageError(`Unknown command ${command ?? "(missing)"}`);
   }
@@ -93,10 +96,24 @@ function run(args) {
     runQuery(commandArgs);
     return;
   }
+  if (command === "diff") {
+    const { options } = parseCommandArgs(commandArgs, {
+      options: { base: { value: true }, root: { value: true }, json: { value: false } },
+    });
+    const base = requiredOption(options, "base", "diff requires --base <previous-product-root>");
+    const root = resolveProductRoot({ explicitRoot: options.root });
+    const report = compareProductRoots(path.resolve(base), root);
+    process.stdout.write(`${options.json ? JSON.stringify(report) : renderProductDiff(report)}\n`);
+    return;
+  }
   if (command === "install") {
     install(commandArgs);
     return;
   }
+  if (command === "create" && ["domain", "concept", "use-case"].includes(commandArgs[0])) {
+    createNode(commandArgs);
+    return;
+  }
   if (["create", "move", "split", "retire"].includes(command)) {
     transitionGuarantee(command, commandArgs);
     return;
@@ -105,7 +122,7 @@ function run(args) {
 
 /**
  * Implement `ddduck install skill update-ddduck-specs`: install the bundled
- * host skill adapter and .ddduck/agent-skills.lock.json into --repo.
+ * host skill bundle and .ddduck/agent-skills.lock.json into --repo.
  * @param {string[]} args - Arguments after the `install` command word.
  * @returns {void}
  */
@@ -358,6 +375,38 @@ function generate(args) {
   writeProductOperationResult(result, options.json);
 }
 
+function createNode(args) {
+  const kind = args[0];
+  const shared = { root: { value: true }, json: { value: false } };
+  const fields =
+    kind === "use-case"
+      ? { file: { value: true } }
+      : {
+          id: { value: true },
+          name: { value: true },
+          purpose: { value: true },
+          ...(kind === "concept" ? { owner: { value: true } } : {}),
+        };
+  const { options } = parseCommandArgs(args, {
+    positionals: { min: 1, max: 1 },
+    options: { ...shared, ...fields },
+  });
+  const required = (field) => requiredOption(options, field, `create ${kind} requires --${field} <value>`);
+  const request =
+    kind === "use-case"
+      ? { kind: "UseCase", node: parseYamlMapping(path.resolve(required("file"))) }
+      : {
+          kind: kind === "domain" ? "Domain" : "Concept",
+          id: required("id"),
+          name: required("name"),
+          purpose: required("purpose"),
+          ...(kind === "concept" ? { ownerDomain: required("owner") } : {}),
+        };
+  const root = resolveProductRoot({ explicitRoot: options.root });
+  const result = runProductOperation({ root, transform: (snapshot) => buildAuthoringPlan(snapshot, request) });
+  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,

package/scripts/generate-docs.mjs

@@ -137,7 +137,7 @@ function renderModelOverview(view) {
   lines.push("## Decisions", "");
   for (const decision of view.decisions) lines.push(`- \`${decision}\``);
   lines.push("");
-  return lines.join("\n");
+  return `${lines.join("\n").trimEnd()}\n`;
 }
 
 function renderNodeList(lines, title, nodes) {