ddduck 0.1.0 → 0.2.0

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

@@ -0,0 +1,60 @@
+# Authoring and verification
+
+Read this reference before proposing or applying canonical ddduck changes.
+
+## Resolve and classify once
+
+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:
+
+- `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.
+
+Stop before mutation when the executable is missing or incompatible, 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/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.
+
+## 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.