ddduck 0.1.2 → 0.3.0

package/skills/update-ddduck-specs/SKILL.md

@@ -1,98 +1,41 @@
 ---
 name: update-ddduck-specs
-description: Use when a repository's ddduck product model needs to be created, audited against current code, tests, and documentation, or reconciled after product changes.
+description: Use when a repository's ddduck product model needs to be created, audited against current code, tests, and documentation, compared across revisions, or reconciled after product changes.
 ---
 
 # Update ddduck Specs
 
-Maintain or bootstrap a repository's ddduck product model from evidence visible in the current working tree.
+Maintain or bootstrap a ddduck product model from evidence in the current working tree. Preserve the difference between observed implementation, accepted intent, canonical product meaning, generated views, and runtime proof.
 
-## Inputs and boundaries
+## Operating contract
 
-- Resolve the repository root, read all applicable repository instructions, and inspect Git status before analysis.
-- Use an explicitly requested product root; otherwise let ddduck resolve it in its own order: the enclosing product root of the current directory, else the `productRoot` in `.ddduck/config.json`, else the unique discovered product root in the repository (the ddduck CLI reference documents the full order, including the example-candidate fallback). `ddduck query spec` reports the resolved root. Ambiguous resolution is a stop condition: report the candidates and ask; never bootstrap a second product root beside an existing one.
-- Default to plan-only. Mutate files only when the current user request explicitly authorizes application, including prose that clearly authorizes the evidence-backed changes. `--root <path>` and `--apply` may be convenient shorthand, but ordinary prose must work.
-- Preserve unrelated and uncommitted work. Stop when intended target files overlap user changes inseparably.
-- Write only `<root>/product.yaml`, `<root>/model/**`, `<root>/decisions/**`, and regenerated `<root>/generated/**`.
-- Never edit generated views directly. Regenerate them with ddduck.
-- Use only evidence visible in the current working tree. Do not rely on prior chat, cursor, cache, or an assumed previous revision.
-- Preserve stable IDs and Guarantee lifecycle. Never silently delete or reuse a Guarantee ID. Use ddduck lifecycle commands where they cover the mutation.
-- Never create an ADR merely to satisfy validation or justify an inferred change.
-- Keep unresolved questions out of canonical model facts.
-- Prefer the smallest coherent product-model change. Avoid ornamental DDD vocabulary and speculative structure.
-- Do not commit or push consumer changes unless the user separately requests it.
+- Resolve the repository root, read every applicable instruction file, and inspect Git status before analysis.
+- Resolve a repository-compatible ddduck executable with the probe order in [executable resolution](references/executable-resolution.md). Do not install dependencies or substitute an unrelated global version.
+- Default to plan-only. Mutate model files only when the current request explicitly authorizes applying the evidence-backed proposal.
+- Preserve unrelated work. Stop when intended model edits overlap user changes inseparably or the analyzed tree changes before application.
+- Write only `<root>/product.yaml`, `<root>/model/**`, `<root>/decisions/**`, and regenerated `<root>/generated/**`. Regenerate derived views; never edit them directly.
+- Preserve stable IDs and Guarantee history. Use lifecycle commands for Guarantee transitions and the supported creation commands for Domain, Concept, and UseCase.
+- Keep unresolved questions in prose. Canonicalize only meaning that is unambiguous and supported by inspected evidence or accepted authority.
+- Commit, push, consumer migration, and external effects require separate authorization.
 
-Use a repository-compatible ddduck executable. Do not install dependencies or silently fall back to an unrelated global version.
+## Load the relevant reference
 
-## Establish the baseline
+Read each selected reference completely before acting. All references are one level below this file.
 
-Classify the selected root exactly once:
+- Before the first ddduck command, read [executable resolution](references/executable-resolution.md).
+- For every bootstrap, audit, or reconciliation, read [modeling and evidence](references/modeling-and-evidence.md).
+- When comparing revisions, reviewing moves/removals, or selecting affected context, read [reviewing changes](references/reviewing-changes.md). Start with `ddduck diff --base <before-root> --root <after-root> --json` when two valid roots exist.
+- Before proposing or applying canonical changes, read [authoring and verification](references/authoring-and-verification.md). Use `ddduck create domain`, `ddduck create concept`, and `ddduck create use-case` for the kinds they support.
 
-- `existing`: `product.yaml` exists. Run `ddduck query spec --root <root> --json` and `ddduck check --root <root>`, recording both outcomes independently. A failing existing model is invalid, not absent, and must not be reinitialized.
-- `absent`: the root is missing or empty. Inspect the repository before proposing initialization.
-- `path-collision`: the root is non-empty but not a recognizable ddduck product. Report the collision and never initialize over it.
+## Workflow
 
-Stop before mutation when the ddduck executable is missing or incompatible, multiple product roots are plausible and none was selected, the selected root is a non-empty path collision, bootstrap identity, purpose, or initial domain seams are not grounded, evidence conflicts materially change the proposed model, target model files overlap inseparable user changes, or the analyzed working-tree state changed before application.
+1. Resolve the executable, then resolve and classify the product root. Record `query spec` and `check` independently; an invalid existing model is not an absent model, and a root that was never inspected is `undetermined`, never absent.
+2. Gather current code, tests, interfaces, documentation, configuration, schemas, and accepted decisions. Record contradictions, exclusions, and coverage gaps.
+3. Separate observed behavior, accepted intent, open questions, and rejected alternatives. Classify every material model difference using the modeling reference.
+4. Produce the plan-only report defined in the authoring reference. A partial or zero-model-change result is valid when it is the evidence-backed outcome.
+5. If application is explicitly authorized, recheck Git status, decisive evidence, and target files; then apply only the approved unambiguous changes.
+6. Run the complete verification sequence from the authoring reference. Any failed command makes the result `incomplete`.
 
-## Gather evidence
+## Completion criteria
 
-Inspect relevant current code, tests, public interfaces, documentation, configuration, schemas, workspace structure, and accepted decisions. Record material exclusions and coverage gaps.
-
-For every candidate fact, record:
-
-- proposed model assertion;
-- repository-relative path plus line, symbol, heading, or test name;
-- evidence role: implementation, verification, documentation, decision, or configuration;
-- contradictory evidence;
-- inspected scope and remaining unknowns.
-
-Executable behavior and passing tests establish observed behavior. Accepted requirements and decisions establish intended behavior. Treat conflicts between them as inconsistencies; do not silently encode either a possible bug or an unimplemented requirement as product truth.
-
-The current schema restricts persisted interface evidence anchors to paths inside the product root. Cite repository-wide evidence in the plan and final report, but persist only schema-supported product-root anchors. Do not copy source evidence into the product root, invent unsupported metadata, or create bridge documents merely to manufacture provenance.
-
-For a greenfield repository, use runtime-supported subagents only when no model exists and the relevant corpus spans several substantial, independent packages, applications, or domain areas that cannot be covered reliably in the coordinating context. Repository file count alone is not sufficient. Subagents are read-only evidence adapters: assign non-overlapping scopes, provide applicable repository instructions, forbid writes and canonical model synthesis, require candidate facts with exact evidence locations, conflicts, unknowns, and coverage, then re-read decisive evidence before adopting it. The coordinator is the sole writer. If subagents are unavailable, inspect the same scopes sequentially and disclose the coverage limitations.
-
-## Compare and classify
-
-Classify every material difference as exactly one of:
-
-- verified omission;
-- stale modeled fact;
-- structural inconsistency with an unambiguous repair;
-- contradiction or uncertainty requiring a human decision;
-- irrelevant implementation detail;
-- insufficiently covered.
-
-For existing models, preserve identity and history.
-
-## Plan-only workflow
-
-Before any mutation, report in this order:
-
-1. Mode, resolved root, and model state.
-2. Baseline query and validation status.
-3. Inspected coverage, exclusions, and gaps.
-4. Proposed changes with classification, concrete evidence, and exact target files.
-5. Contradictions, uncertainties, and required decisions.
-6. Exact generation and verification commands.
-
-Without explicit application authorization, stop before all writes. Plan mode performs no writes, including initialization and generation.
-
-## Apply workflow
-
-When application is explicitly authorized:
-
-1. Recheck Git status, intended target files, and decisive evidence.
-2. Initialize only an absent or empty root whose model identity, purpose, and initial domain seams are explicit or unambiguously grounded. Otherwise request the missing decision.
-3. Apply only planned, evidence-backed changes whose meaning is unambiguous.
-4. Leave unresolved findings unchanged.
-5. Use ddduck lifecycle commands for Guarantee transitions. Author other canonical YAML against installed schemas and existing model conventions.
-6. Run `ddduck check --root <root> --source-only` before generation; hand-authored canonical edits legitimately leave generated views stale until step 7.
-7. Run `ddduck generate --root <root>`.
-8. Run `ddduck check --root <root>` again.
-9. Run `ddduck query spec --root <root> --json` and require every generated view to be fresh.
-10. Inspect the final diff for scope.
-
-Any command failure makes the result incomplete. Inspect and report the resulting working tree; never destructively roll back unrelated user work.
-
-Report changed canonical, decision, and generated files; evidence supporting each material change; skipped and unresolved findings; exact command outcomes and diagnostics; final generated-view freshness; and remaining coverage gaps. Explicitly report `incomplete` when any verification or scope check fails. A verified no-op is a valid result; do not create model content merely to demonstrate activity.
+Report the resolved root and mode, baseline outcomes, inspected coverage, changed or proposed IDs and files, supporting evidence, contradictions and open decisions, exact command results, generated-view freshness, and remaining gaps. For comparisons, distinguish structural differences from semantic approval. For applications, inspect the final scoped diff and report every skipped or unresolved finding.

package/skills/update-ddduck-specs/references/authoring-and-verification.md

@@ -0,0 +1,62 @@
+# Authoring and verification
+
+Read this reference before proposing or applying canonical ddduck changes.
+
+## Resolve and classify once
+
+Root resolution is delegated to the executable, so resolve one first with the probe order in [executable resolution](executable-resolution.md). Every `ddduck …` command in this file names that resolved command; substitute it before running. Then use an explicitly requested root. Otherwise let ddduck resolve the enclosing product root, then `.ddduck/config.json`, then the unique repository candidate. `ddduck query spec --root <root> --json` reports the resolved root. Ambiguity is a stop condition: report candidates and ask rather than initializing a second model.
+
+Classify the selected path. These three states are observations; each requires an inspection that actually ran.
+
+- `existing`: `product.yaml` exists. Run `query spec` and `check` independently. A failing model remains existing and invalid.
+- `absent`: the root is missing or empty. Inspect the repository before proposing initialization.
+- `path-collision`: the path is non-empty but is not a recognizable product. Report it and do not initialize over it.
+
+When no executable resolves, or the inspection that distinguishes those states did not complete, the state is `undetermined`: the absence of an observation rather than a fourth thing observed. Report `undetermined` and stop; never downgrade it to `absent`, because `absent` is the only state that authorizes initialization.
+
+Stop before mutation when the executable is unresolved, missing, or incompatible, the model state is `undetermined`, the root is ambiguous, the path collides, bootstrap identity or seams are ungrounded, evidence conflicts change the proposal materially, target files overlap inseparable user work, or the analyzed working tree changed.
+
+## Plan-only report
+
+Before any write, report in this order:
+
+1. Mode, resolved root, and model state.
+2. Independent query and validation outcomes.
+3. Inspected coverage, exclusions, and gaps.
+4. Proposed changes with classification, evidence, affected IDs, and exact files.
+5. Contradictions, uncertainties, and required decisions.
+6. Exact authoring, generation, and verification commands.
+
+Without explicit application authorization, stop here. Plan-only performs no initialization or generation.
+
+## Apply canonical changes
+
+Recheck Git status, intended files, and decisive evidence immediately before writing.
+
+Use the supported operation instead of coordinating parent collections by hand:
+
+```bash
+ddduck create domain --id domain:<slug> --name <text> --purpose <text> --root <root>
+ddduck create concept --id concept:<slug> --owner domain:<slug> --name <text> --purpose <text> --root <root>
+ddduck create use-case --file <yaml-file> --root <root>
+```
+
+Use ddduck lifecycle commands for Guarantee creation, movement, splitting, and retirement. Author canonical YAML directly only for kinds or field changes without a supported mutation command, following installed schemas and existing conventions. Never edit generated views.
+
+Apply only approved, unambiguous changes. Leave unresolved findings unchanged. A helper coordinates structure and publication; it does not supply product meaning.
+
+## Verify and read back
+
+For hand-authored canonical edits, run the source-only check before generation. Mutation commands already stage validation and generation, but still perform the common final readback:
+
+```bash
+ddduck check --root <root> --source-only
+ddduck generate --root <root>
+ddduck check --root <root>
+ddduck query spec --root <root> --json
+git diff -- <root>/product.yaml <root>/model <root>/decisions <root>/generated
+```
+
+When only mutation commands were used, the first two commands may be redundant; run them when hand edits occurred or when generated freshness is uncertain. Always require the final `check`, fresh generated views in `query spec`, and a scoped diff.
+
+Any failure makes the result `incomplete`. Inspect the resulting tree without destructive rollback. Report changed canonical, decision, and generated files; evidence for every material change; skipped and unresolved findings; exact diagnostics; freshness; and remaining coverage gaps.

package/skills/update-ddduck-specs/references/executable-resolution.md

@@ -0,0 +1,39 @@
+# Executable resolution
+
+Read this reference before running any ddduck command. Root classification, baselines, and verification results are only as trustworthy as the executable that produced them, so resolving one is a precondition for the workflow rather than a step inside it.
+
+## Probe in order
+
+Take the first candidate that runs. Confirm a candidate by appending `--version` to that candidate's own command, never by running a different one: `node_modules/.bin/ddduck --version` for probe 2, `node scripts/ddduck.mjs --version` for probe 3, and the bare `ddduck --version` only when `ddduck` on `PATH` is itself the candidate being probed. A working repository-local candidate must not be rejected because `ddduck` is absent from `PATH`. The command prints `ddduck <version>`; read the resolved version from that output.
+
+1. A command or path supplied in the current request.
+2. `node_modules/.bin/ddduck` at the repository root, then at any enclosing workspace root.
+3. `node scripts/ddduck.mjs`, the repository's own `package.json` `bin` target, when the repository under analysis is ddduck itself.
+4. `ddduck` on `PATH`.
+5. A ddduck source checkout that the user named or that the repository records, only when its reported version matches the version the repository pins: a `ddduck` dependency in `package.json`, or `ddduckVersion` in `.ddduck/agent-skills.lock.json`.
+
+Do not install dependencies and do not substitute an unrelated global version. A candidate that fails to run, or that reports a version incompatible with the pinned one, is not a resolution; continue with the next probe.
+
+Record which probe resolved, the exact command, and its reported version. Reuse that one command for every subsequent ddduck invocation.
+
+Every `ddduck <subcommand>` form written in this skill and its references names the resolved command, not the literal `ddduck` on `PATH`. Substitute the resolved command before running any of them: with probe 3 resolved, `ddduck check --root <root>` is run as `node scripts/ddduck.mjs check --root <root>`.
+
+## Named paths only, never scan
+
+Probe only the paths listed above plus the paths the request or the repository explicitly names. Never search parent directories or the wider filesystem for a checkout. An unbounded search exhausts the available budget, times out, and still resolves nothing.
+
+## An unresolved executable is `undetermined`
+
+`existing`, `absent`, and `path-collision` are observations, and each one requires an inspection that actually ran. When no probe resolves, that inspection never ran and the model state is `undetermined`.
+
+Report `undetermined`, stop before any mutation, and never downgrade it to `absent`. Only `absent` authorizes initialization, and initializing on an unverified `absent` bootstraps a second product root beside a healthy one. A named `productRoot` in `.ddduck/config.json`, or an existing `product.yaml`, is evidence against `absent` even while the executable remains unresolved.
+
+## Remediation
+
+When no probe resolves, report every probe attempted and its outcome, then present these options and let the user choose:
+
+- `npm i -g ddduck`
+- `npm i --save-dev ddduck`
+- `npx ddduck@<version>`, using the pinned version when the repository records one
+
+Present the options only. Do not install anything, and do not invoke an installer or `npx` on the user's behalf.

package/skills/update-ddduck-specs/references/modeling-and-evidence.md

@@ -0,0 +1,56 @@
+# Modeling and evidence
+
+Read this reference for every ddduck bootstrap, audit, or reconciliation.
+
+## Evidence ledger
+
+For every candidate model fact, record:
+
+- the proposed assertion;
+- repository-relative path plus line, symbol, heading, or test name;
+- role: implementation, verification, documentation, decision, or configuration;
+- contradictory evidence;
+- inspected scope and remaining unknowns.
+
+Executable behavior and passing tests establish observed behavior. Accepted requirements and decisions establish intended behavior. A conflict between them is an inconsistency requiring a decision; neither side silently becomes product truth.
+
+Repository-wide evidence belongs in the plan and final report. Persist only evidence fields supported by the installed schema. Interface anchors must remain inside the product root. Do not copy source into the model, invent metadata, or create bridge documents merely to manufacture provenance.
+
+Valid anchors prove that declared text exists. Declared audit verdicts remain assessments. Readiness records and valid links do not execute tests or prove runtime behavior.
+
+## Define before asserting
+
+Reuse an existing proposal or brief. Capture the actor and problem, success and refusal examples, evidence provenance, accepted constraints, alternatives, open conflicts, affected IDs, decision and rationale, and receiving plan. Omit sections that add no decision value.
+
+- `Observed`: inspected behavior, not endorsement.
+- `Accepted`: intended behavior with identified authority; it may be unimplemented.
+- `Open`: unresolved meaning that stays out of canonical YAML.
+- `Rejected`: considered alternative retained with its rationale.
+
+These labels are prose, not schema fields or Guarantee lifecycle states. Independent accepted obligations may be modeled while another question remains open. Zero canonical change is correct when existing obligations suffice, the proposal remains unresolved, or the change is implementation-only. Create an ADR only for a durable consequential decision worth maintaining.
+
+## Model by meaning
+
+- Domain: a distinct product responsibility, not a package or screen.
+- Concept: vocabulary needed to reason about a decision, not every noun or class.
+- Guarantee: an observable obligation or invariant, not an aspiration.
+- UseCase: an actor goal and the obligations it requires, preserves, or establishes, not an implementation task list.
+- Relationship: an explicit connection worth reviewing, not proof of causation.
+- Interface: optional; add one only when an external behavioral boundary matters.
+
+Prefer the smallest coherent model change. Preserve identity and history. Never silently delete or reuse a Guarantee ID.
+
+Classify every material difference as exactly one of:
+
+- verified omission;
+- stale modeled fact;
+- structural inconsistency with an unambiguous repair;
+- contradiction or uncertainty requiring a human decision;
+- irrelevant implementation detail;
+- insufficiently covered.
+
+## Greenfield coverage
+
+Initialize only when identity, purpose, and initial domain seams are explicit or unambiguously grounded.
+
+Use runtime-supported subagents only when no model exists and the evidence corpus spans several substantial independent packages, applications, or domains that cannot fit reliably in the coordinating context. File count alone is insufficient. Give each subagent a non-overlapping read-only scope and require candidate facts with exact evidence locations, conflicts, unknowns, and coverage. The coordinator re-reads decisive evidence and is the sole model writer.

package/skills/update-ddduck-specs/references/reviewing-changes.md

@@ -0,0 +1,45 @@
+# Reviewing changes
+
+Read this reference when two product roots or revisions must be compared, or when a move, removal, or affected-context review is requested. Every `ddduck …` command below names the command resolved by [executable resolution](executable-resolution.md); substitute it before running.
+
+## Structural comparison
+
+Keep both roots stable and run:
+
+```bash
+ddduck diff --base <before-root> --root <after-root> --json
+```
+
+The command validates both roots independently and compares canonical YAML records by stable ID. It reports additions, removals, field changes, and relocations. Object-key order, comments, and YAML formatting are not semantic record changes; array order is significant. Raw canonical bytes still contribute to each source digest.
+
+Exit `0` means the comparison completed, including when differences exist. It is not approval. Exit `2` means a root is busy; other failures exit `1`. The report excludes decision content, evidence content, delivery artifacts, and runtime. Empty output does not prove semantic equivalence or freshness outside that scope.
+
+Source reads are not an atomic snapshot. Keep both roots unchanged during review and repeat the comparison if either tree changes.
+
+## Inspect affected context
+
+For each changed or removed ID, inspect both roots where the record exists:
+
+```bash
+ddduck query node --id <id> --root <root> --json
+ddduck query impact --id <id> --root <root> --json
+ddduck query neighbors --id <id> --root <root> --json
+ddduck query context --id <id> --root <root> --json
+```
+
+`impact` follows reverse ownership and behavioral-reference edges. `neighbors` returns direct edges; relationships are review candidates, not causal proof. Filter incoming and outgoing edges with `edge.kind === "relationship"` and deduplicate by `edge.id`, because a self-relationship appears in both lists.
+
+When the changed ID is a Relationship, query the relationship record and inspect its `from`, `to`, description, and constraints. `neighbors` matches endpoint IDs, not the Relationship record's own ID.
+
+Inspect the before root for removed context; current-root queries cannot reconstruct deleted records. Use the consumer's own bridge for feature traces or delivery references outside the ddduck product root.
+
+## Review outcome
+
+For every reported ID, state the structural difference, before/after ownership and paths, affected obligations and use cases, supporting evidence, contradictions, and one of the exact classifications from the modeling reference. Preserve a Guarantee ID across ownership moves. Treat deletion and recreation under another ID as an identity break, not a move.
+
+Conclude separately:
+
+- structural comparison completed or incomplete;
+- semantic change acceptable, not acceptable, or decision required;
+- historical retention check required or satisfied;
+- runtime and external effects verified or unverified.