@documentation-robotics/cli 0.2.0 → 0.4.0

package/dist/integrations/claude_code/skills/dr_12_apm_layer/SKILL.md

@@ -143,20 +143,65 @@ Activate when the user:
 
 ---
 
-## Cross-Layer Relationships
+## Intra-Layer Relationships
+
+A resource aggregates the instrumentation scopes running in it, and a scope aggregates the spans,
+metric instruments and log records emitted under it. Providers (trace, metric, log configurations)
+depend on their resource and aggregate processors and exporters. Each signal flows through its own
+processors to exporters; signals are correlated by `references`. Only signals and instrumentation
+configurations `monitors` elements in other layers; alerts and dashboards monitor signals.
+
+| Source Type           | Predicate  | Target Type          | Example                                                          |
+| --------------------- | ---------- | -------------------- | ---------------------------------------------------------------- |
+| Span                  | composes   | SpanEvent            | "Process Order" composes "Payment Authorized"                    |
+| Span                  | aggregates | SpanLink             | "Process Order Batch" aggregates "Link To Enqueue Trace"         |
+| SpanLink              | references | Span                 | "Link To Enqueue Trace" references "Enqueue Order"               |
+| Span                  | references | Span                 | "Charge Card" references "Process Order" (parent span)           |
+| Resource              | aggregates | InstrumentationScope | "order-service Resource" aggregates "orders-tracer"              |
+| Span                  | flows-to   | ExporterConfig       | "Process Order" flows-to "OTLP Trace Exporter"                   |
+| InstrumentationScope  | aggregates | LogRecord            | "orders-logger" aggregates "Payment Error Log"                   |
+| MetricInstrument      | flows-to   | ExporterConfig       | "order_rate" flows-to "Prometheus Exporter"                      |
+| LogRecord             | references | Span                 | "Payment Error Log" references "Charge Card"                     |
+| LogRecord             | flows-to   | LogProcessor         | "Payment Error Log" flows-to "PII Redaction Processor"           |
+| LogProcessor          | flows-to   | ExporterConfig       | "PII Redaction Processor" flows-to "OTLP Log Exporter"           |
+| InstrumentationScope  | aggregates | Span                 | "orders-tracer" aggregates "Process Order"                       |
+| InstrumentationScope  | aggregates | MetricInstrument     | "orders-meter" aggregates "order_rate"                           |
+| InstrumentationConfig | references | InstrumentationScope | "Node Auto-Instrumentation" references "express instrumentation" |
+| TraceConfiguration    | depends-on | Resource             | "Order Service Tracing" depends-on "order-service Resource"      |
+| MetricConfiguration   | aggregates | MetricInstrument     | "Order Service Metrics" aggregates "order_rate"                  |
+| LogConfiguration      | aggregates | LogProcessor         | "Order Service Logging" aggregates "PII Redaction Processor"     |
+| Alert                 | monitors   | MetricInstrument     | "High Order Error Rate" monitors "order_errors_total"            |
+| Dashboard             | monitors   | MetricInstrument     | "Order Operations Dashboard" monitors "order_rate"               |
+| Dashboard             | references | Alert                | "Order Operations Dashboard" references "High Order Error Rate"  |
 
-**Outgoing (APM → Other Layers):**
-
-- `instrumented-service` → Application Layer (which service is being monitored?)
-- `business-metrics` → Business Layer (business KPIs)
-
-**Incoming (Other Layers → APM):**
+---
 
-- Application Layer → APM (services reference metrics)
-- API Layer → APM (operations set SLA targets)
-- Business Layer → APM (processes reference business metrics)
-- Data Model Layer → APM (metric instruments tracking data quality KPIs)
-- Data Store Layer → APM (query performance metrics)
+## Cross-Layer References
+
+### Outgoing References (APM → Other Layers)
+
+| Source Type           | Predicate        | Target Type                        | Example                                                        |
+| --------------------- | ---------------- | ---------------------------------- | -------------------------------------------------------------- |
+| Span                  | monitors         | `application.applicationservice`   | "Process Order" monitors "Order Service"                       |
+| Span                  | monitors         | `api.operation`                    | "POST /orders" span monitors "Create Order"                    |
+| Span                  | monitors         | `navigation.route`                 | "Route Change" monitors "Checkout Route"                       |
+| Span                  | monitors         | `data-store.collection`            | "Insert Order" monitors "orders table"                         |
+| MetricInstrument      | monitors         | `api.operation`                    | "http_server_duration" monitors "Create Order"                 |
+| MetricInstrument      | monitors         | `business.businessprocess`         | "order_rate" monitors "Order Fulfillment"                      |
+| MetricInstrument      | monitors         | `data-store.database`              | "db_pool_connections" monitors "Orders Database"               |
+| MetricInstrument      | measures-outcome | `motivation.outcome`               | "order_rate" measures "Higher Order Throughput"                |
+| MetricInstrument      | satisfies        | `motivation.requirement`           | "http_server_duration" satisfies "p95 Latency Under 300ms"     |
+| Resource              | maps-to          | `application.applicationcomponent` | "order-service Resource" maps-to "Order Service Component"     |
+| Resource              | references       | `technology.node`                  | "order-service Resource" references "EKS Production Cluster"   |
+| InstrumentationConfig | monitors         | `application.applicationcomponent` | "Node Auto-Instrumentation" monitors "Order Service Component" |
+| LogConfiguration      | satisfies        | `security.auditconfig`             | "Order Service Logging" satisfies "Order Audit Logging"        |
+
+### Incoming References (Other Layers → APM)
+
+| Source Type                      | Predicate  | Target Type        | Example                                            |
+| -------------------------------- | ---------- | ------------------ | -------------------------------------------------- |
+| `application.applicationservice` | references | TraceConfiguration | "Order Service" references "Order Service Tracing" |
+| `testing.testcasesketch`         | tests      | MetricInstrument   | "Order Counter Increments" tests "order_rate"      |
 
 ---
 

package/dist/integrations/claude_code/skills/dr_13_testing_layer/SKILL.md

@@ -139,22 +139,88 @@ Activate when the user:
 
 ---
 
-## Cross-Layer Relationships
+## Intra-Layer Relationships
+
+Each testing type has one composing parent. The model composes targets, partitions, context
+variations, environment factors, exclusions and the summary; a target composes its input fields,
+outcome categories, coverage requirements and test case sketches. A sketch `validates` the one
+requirement it exercises and `references` its context variation and outcome category. Only target
+input fields reference the field under test, so partitions stay reusable. Summaries report with
+`references` and `aggregates`; they never `validates`.
+
+| Source Type             | Predicate  | Target Type             | Example                                                                   |
+| ----------------------- | ---------- | ----------------------- | ------------------------------------------------------------------------- |
+| TestCoverageModel       | composes   | TestCoverageTarget      | "Login API Coverage Model" composes "Login Endpoint Coverage"             |
+| TestCoverageModel       | composes   | ContextVariation        | "Login API Coverage Model" composes "Security Testing"                    |
+| TestCoverageModel       | composes   | EnvironmentFactor       | "Login API Coverage Model" composes "Rate Limiter Enabled"                |
+| TestCoverageModel       | composes   | InputSpacePartition     | "Login API Coverage Model" composes "Email Format Partition"              |
+| TestCoverageModel       | composes   | CoverageExclusion       | "Login API Coverage Model" composes "SSO Login Out Of Scope"              |
+| TestCoverageModel       | composes   | CoverageSummary         | "Login API Coverage Model" composes "Login Coverage Summary"              |
+| TestCoverageTarget      | composes   | TargetInputField        | "Login Endpoint Coverage" composes "email field"                          |
+| TestCoverageTarget      | composes   | OutcomeCategory         | "Login Endpoint Coverage" composes "Invalid Credentials (401)"            |
+| TestCoverageTarget      | composes   | CoverageRequirement     | "Login Endpoint Coverage" composes "Pairwise Credentials"                 |
+| TestCoverageTarget      | composes   | TestCaseSketch          | "Login Endpoint Coverage" composes "Valid Login Test Case"                |
+| TargetInputField        | references | InputSpacePartition     | "email field" references "Email Format Partition"                         |
+| InputSpacePartition     | composes   | PartitionValue          | "Email Format Partition" composes "Malformed Email"                       |
+| PartitionDependency     | references | PartitionValue          | "Locked Account Requires Valid Email" references "Locked Account"         |
+| PartitionDependency     | references | InputSpacePartition     | "Locked Account Requires Valid Email" references "Email Format Partition" |
+| CoverageRequirement     | composes   | InputPartitionSelection | "Pairwise Credentials" composes "Email x Password Selection"              |
+| CoverageRequirement     | references | OutcomeCategory         | "Pairwise Credentials" references "Invalid Credentials (401)"             |
+| CoverageRequirement     | references | ContextVariation        | "Pairwise Credentials" references "Security Testing"                      |
+| InputPartitionSelection | references | PartitionValue          | "Email x Password Selection" references "Malformed Email"                 |
+| TestCaseSketch          | validates  | CoverageRequirement     | "Valid Login Test Case" validates "Pairwise Credentials"                  |
+| TestCaseSketch          | composes   | InputSelection          | "Valid Login Test Case" composes "Valid Email + Valid Password"           |
+| InputSelection          | references | PartitionValue          | "Valid Email + Valid Password" references "Well-Formed Email"             |
+| TestCaseSketch          | references | OutcomeCategory         | "Valid Login Test Case" references "Success (200 + JWT)"                  |
+| TestCaseSketch          | references | ContextVariation        | "Brute Force Lockout Test" references "Security Testing"                  |
+| ContextVariation        | references | EnvironmentFactor       | "Security Testing" references "Rate Limiter Enabled"                      |
+| CoverageGap             | references | CoverageRequirement     | "No MFA Cases" references "Pairwise Credentials"                          |
+| CoverageExclusion       | references | TestCoverageTarget      | "SSO Login Out Of Scope" references "Login Endpoint Coverage"             |
+| CoverageExclusion       | references | CoverageGap             | "SSO Login Out Of Scope" references "No SSO Cases"                        |
+| TargetCoverageSummary   | references | TestCoverageTarget      | "Login Endpoint Rollup" references "Login Endpoint Coverage"              |
+| TargetCoverageSummary   | references | CoverageGap             | "Login Endpoint Rollup" references "No MFA Cases"                         |
+| CoverageSummary         | aggregates | TargetCoverageSummary   | "Login Coverage Summary" aggregates "Login Endpoint Rollup"               |
 
-**Outgoing (Testing → Other Layers):**
-
-- `motivation.supports-goals` → Motivation Layer (quality goals)
-- `motivation.fulfills-requirements` → Motivation Layer (test requirements)
-- `business.covers-process` → Business Layer (process coverage)
-- `api.tests-operation` → API Layer (API endpoint testing)
-- `data.validates-schema` → Data Model Layer (data validation)
-- `ux.tests-view` → UX Layer (UI testing)
-
-**Incoming (Other Layers → Testing):**
+---
 
-- Motivation Layer → Testing (requirements drive coverage)
-- API Layer → Testing (operations need test coverage)
-- Business Layer → Testing (processes need testing)
+## Cross-Layer References
+
+### Outgoing References (Testing → Other Layers)
+
+A target `covers` the production artifact it names; a sketch `tests` what it exercises. The model
+covers only the application component, UX application or API document it is for. Requirements and
+summaries reach no other layer. Only the model and test case sketches link to motivation.
+
+| Source Type        | Predicate        | Target Type                        | Example                                                               |
+| ------------------ | ---------------- | ---------------------------------- | --------------------------------------------------------------------- |
+| TestCoverageModel  | covers           | `application.applicationcomponent` | "Login API Coverage Model" covers "Auth Service"                      |
+| TestCoverageModel  | covers           | `api.openapidocument`              | "Login API Coverage Model" covers "Auth API"                          |
+| TestCoverageModel  | supports         | `motivation.goal`                  | "Login API Coverage Model" supports "Secure Customer Access"          |
+| TestCoverageModel  | satisfies        | `motivation.requirement`           | "Login API Coverage Model" satisfies "Auth Must Be Regression Tested" |
+| TestCoverageModel  | measures-outcome | `motivation.outcome`               | "Login API Coverage Model" measures-outcome "Fewer Auth Incidents"    |
+| TestCoverageTarget | covers           | `api.operation`                    | "Login Endpoint Coverage" covers "POST /auth/login"                   |
+| TestCoverageTarget | covers           | `product.feature`                  | "Password Reset Coverage" covers "Self-Service Password Reset"        |
+| TestCoverageTarget | covers           | `ux.view`                          | "Login Screen Coverage" covers "Login View"                           |
+| TestCoverageTarget | covers           | `data-store.storedlogic`           | "Order Total Trigger Coverage" covers "recalc_order_total"            |
+| TestCaseSketch     | tests            | `api.operation`                    | "Valid Login Test Case" tests "POST /auth/login"                      |
+| TestCaseSketch     | tests            | `api.response`                     | "Invalid Password Test" tests "401 Unauthorized"                      |
+| TestCaseSketch     | tests            | `business.businessprocess`         | "Complete Checkout E2E" tests "Order Checkout"                        |
+| TestCaseSketch     | tests            | `ux.view`                          | "Login Form Renders Errors" tests "Login View"                        |
+| TestCaseSketch     | tests            | `navigation.route`                 | "Deep Link To Profile" tests "User Profile Route"                     |
+| TestCaseSketch     | tests            | `security.threat`                  | "Brute Force Lockout Test" tests "Credential Stuffing"                |
+| TestCaseSketch     | tests            | `data-model.schemadefinition`      | "Reject Unknown Order Fields" tests "Order Schema"                    |
+| TestCaseSketch     | tests            | `data-model.objectschema`          | "Order Total Is Never Negative" tests "Order"                         |
+| TestCaseSketch     | tests            | `data-store.accesspattern`         | "Find Owners By Last Name" tests "findByLastName"                     |
+| TestCaseSketch     | tests            | `application.applicationcomponent` | "Pet Type Formatter Parses Names" tests "PetTypeFormatter"            |
+| TestCaseSketch     | satisfies        | `motivation.requirement`           | "Brute Force Lockout Test" satisfies "Lock After 5 Failures"          |
+| TestCaseSketch     | accesses         | `data-store.collection`            | "Order History Test" accesses `orders`                                |
+| TargetInputField   | references       | `api.parameter`                    | "email field" references "email parameter"                            |
+| TargetInputField   | references       | `data-model.schemaproperty`        | "email field" references "User.email"                                 |
+| EnvironmentFactor  | references       | `technology.systemsoftware`        | "PostgreSQL 16" references "PostgreSQL"                               |
+
+### Incoming References (Other Layers → Testing)
+
+None. Testing is a leaf layer: other layers do not hold relationships pointing into it. Record traceability from the testing side (e.g. `TestCaseSketch tests api.operation`).
 
 ---
 
@@ -202,10 +268,13 @@ name: "Login API Coverage Model"
 type: testcoveragemodel
 properties:
   version: "1.0"
-  application: application.service.auth-service
   description: "ISP coverage model for the Login API"
 ```
 
+```bash
+dr relationship add testing.testcoveragemodel.login-api application.applicationcomponent.auth-service --predicate covers
+```
+
 ---
 
 ## Example: Login Test Coverage Target
@@ -220,6 +289,11 @@ properties:
   priority: critical
 ```
 
+```bash
+dr relationship add testing.testcoveragemodel.login-api testing.testcoveragetarget.login-endpoint --predicate composes
+dr relationship add testing.testcoveragetarget.login-endpoint api.operation.login --predicate covers
+```
+
 ---
 
 ## Example: Test Case Sketch
@@ -234,6 +308,12 @@ properties:
   implementationFormat: automated
 ```
 
+```bash
+dr relationship add testing.testcoveragetarget.login-endpoint testing.testcasesketch.valid-login --predicate composes
+dr relationship add testing.testcasesketch.valid-login testing.coveragerequirement.pairwise-credentials --predicate validates
+dr relationship add testing.testcasesketch.valid-login api.operation.login --predicate tests
+```
+
 ---
 
 ## Coverage Completeness Checklist

package/dist/integrations/claude_code/skills/dr_change_planning/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: dr_change_planning
+description: Plan a code change as a staged DR changeset through the dr MCP server, pressure-test it against the model, build from its brief, and verify the build against it. Use when asked to plan, design or scope a change in a project with a DR model.
+triggers:
+  [
+    "plan this change",
+    "plan the change",
+    "plan a change",
+    "plan this feature",
+    "how should we build",
+    "scope this change",
+    "design this change",
+    "draft a changeset",
+    "changeset brief"
+  ]
+---
+
+# Plan a change as a DR changeset
+
+In a project with a DR model (`documentation-robotics/model/`), a plan is a staged changeset, not a
+prose document. The changeset says what the change will build. The model says what is built. The
+graph checks the plan for you. The full design is `docs/CHANGE_MODELING.md` in the DR repository.
+
+## Before you start
+
+- You need the `dr` MCP server. Its tools show up as `mcp__plugin_dr_dr__<tool>` from the `dr`
+  plugin, or `mcp__dr__<tool>` when the server is registered by hand as `dr`. If they are missing,
+  tell the user to install the `dr` plugin (see `integrations/claude_code/docs/MCP_SERVER.md`)
+  and stop. Don't fall back to prose.
+- Staging writes files under `documentation-robotics/changesets/`. If the session is in plan mode,
+  say that the plan will be a changeset and leave plan mode before staging.
+- If the project has no model yet, propose a name and confirm it with the human before
+  `project_init`. Then ask whether to bootstrap the model from the code now or let it grow with
+  each change, and wait for their answer.
+- When `codebase_extract` returns cards (in a bootstrap, or when you verify), ask the developer about
+  the ones you can't place with confidence: whether a card is a model element at all, which type it
+  is, or whether to reject it. Don't guess. Collect them and ask once, in one short list (the card,
+  your best guess, the question), then stage or reject from the answers.
+- You never land or discard the plan on your own. Commit it (`changeset_commit`) only when the
+  human asks you to land it; they confirm it in a dialog. Apply is not an MCP tool. Discard only when
+  they agree.
+
+## The loop
+
+1. **Frame.** `changeset_list` first: if a changeset for this change exists, `changeset_activate` it
+   and continue. Otherwise propose a short kebab-case `name` and a `description` that states the
+   intent (what the change is for and what done looks like), and confirm both with the human before
+   you call `changeset_create` with them. Wait for their answer. Find the goal,
+   requirement or feature it serves (`model_search` in motivation, business, product). If there is
+   none, stage one, or ask the human what the change is for.
+2. **Orient.** `model_search` / `model_show` / `model_trace` for the elements the change touches.
+   Inside a changeset these read the plan as it stands (each result carries a change status).
+   `spec_type` for a type you will add: its required attributes, enums, and the relationships the
+   catalog allows to and from it. Within reason, every connection the spec models for a type is
+   expected, though not every one will exist: treat the catalog's list as the checklist for each
+   element the change adds or alters.
+3. **Draft.** Stage the change in every layer it reaches: `model_add`, `model_update`,
+   `model_delete`, `relationship_add`, `relationship_delete`. Relationships may join elements that
+   exist only in the changeset. When you wire several, use the lists: `model_add` with
+   `elements: [...]` (plus `relationships` that may name elements added in the same call), and
+   `relationship_add` with `relationships: [{source, predicate, target, properties?}]`. Each list is
+   staged in one write; an invalid item is skipped and reported, so read the per-item results. For
+   a planned element with no code yet, send no source fields. Pass `sourceFile` and `sourceSymbol`
+   (with `sourceProvenance: "manual"`) only when you know where the code goes.
+   Change one attribute with `model_update` `attributePatch`, not by repeating every attribute. Fix a
+   mistake with `changeset_unstage` (one element, one relationship, or `source` or `target` alone for
+   every staged connection at that end), not by staging the reverse. To drop several, send them as
+   `changes: [...]`: one call, one write, a result per item.
+4. **Pressure-test.** `changeset_brief`, then `changeset_impact` for anything the brief questions.
+   The brief is compact by default; pass `detail: "full"` only when you need every section in full.
+   Steps 3 and 4 are a loop: a plan comes into focus over many passes. Each pass, stage a little,
+   then:
+   - Pass the last brief's `revisionToken` as `since`; read the `delta` first. It covers unstages
+     too (`unstaged`). If it warns (a hand-edited `changes.yaml`, or a reach back past the last 200
+     unstages), read the brief itself.
+   - Work through `unwired` for each element you added or changed. The default brief only counts
+     it per layer, and `sections` returns only the sections it names, so list the entries with
+     `sections: ["unwired"], unwiredLayers: [<the layers the change reaches>]`, narrowed further with
+     `layers` or `ids` if you like. Always pass a filter: unfiltered it runs to hundreds of KB on a
+     large model. Where `existingCount` is above 0, link an existing element; otherwise decide
+     whether the change needs a new one.
+   - Walk `changeset_impact` with `from` set to what you just added, not the whole changeset.
+   - Read the plan with `changeset_show` `detail: "summary"`, not the full snapshots.
+
+   Read the brief's gaps:
+   - `peer-pattern`: most elements like this one have a connection it lacks.
+   - `unconnected`: an added element with no relationships.
+   - Intent: a change that reaches no motivation, business or product element.
+   - Layers not reached: a new API operation with nothing in data model, testing or APM is a small
+     change or an unfinished plan. Decide which.
+   - Connections the brief can't flag: for each changed element, compare what `spec_type` says its
+     type can connect to with what the plan has. Stage the ones the change needs; leave the ones it
+     doesn't, but don't skip the comparison.
+
+   For each gap, either stage what is missing or accept it. Record an accepted gap where the human
+   will see it: an `annotation_create` on the element, or a line in the description
+   (`changeset_update`). `model_validate` should pass on the projected model.
+
+5. **Review.** Stop and show the human the brief: changes by layer, gaps fixed and gaps accepted,
+   impact, code touched. Call `review_open` and give them its `url`: it opens the plan on the graph
+   in the viewer, reusing the viewer already running for the project or starting one. The human
+   comments on elements there, including ones the plan adds. Read their comments with
+   `annotation_list`, answer with `annotation_reply`, revise, and run the brief again. Don't start building until they agree.
+6. **Build.** Build from the brief. At the start of the build, read it with
+   `sections: ["changes"]`: each changed element's attributes and changed fields, and its
+   connections as `predicate → id` lines. For a large plan, read one layer at a time with
+   `sections: ["changes"], layers: ["<layer>"]`, taking the layers from the default brief's
+   `byLayer`. The default brief's "code touched" list is what you will edit or must not
+   break. Keep the changeset staged and commit only the plan's own directory
+   (`documentation-robotics/changesets/<id>/`, with the id `changeset_show` reports) on the branch
+   with the code. Don't add the whole `changesets/` directory: the `.active` marker and any
+   `<name>-as-built` changeset stay out of the commit. If the build has to differ from the plan,
+   change the plan to match and say why. Don't verify during the build: no `codebase_extract`, no
+   as-built changeset and no `changeset_verify` until the build is committed. Verify is the next
+   step, on its own.
+7. **Verify.** Verify as its own step, after the build (the code and the plan's directory) is
+   committed, not in the turn that builds it. Extract what was built, separately from the plan. The
+   as-built changeset comes from `codebase_extract` and the code. Never hand-write it, and never copy
+   plan elements into it: name each element after its card (the code's symbol), not after the plan's
+   element, and don't add planned elements extraction can't see (tests, intent) to make the verdict
+   match. Re-index the code once the build is committed: `codebase_index` with `wait: 30` (it re-indexes when source files changed since the last
+   index, committed or not), then `status: true` and `wait: 30` until the job is done; don't call it
+   in a quick loop. If the result reports `ignoreFile` (the `.cbmignore` it wrote so DR's own folders
+   aren't indexed), tell the developer to commit that file. Then `codebase_extract`
+   with `since` set to the branch the work started from (e.g. `main`) and
+   `changeset: "<name>-as-built"`. It stages what the rules decide in the changed files and leaves
+   `<name>-as-built` active. If it staged nothing, it makes no changeset: `changeset_create` with the
+   name it gives before you `model_add` its cards. For each card it returns that is a model element, stage it with
+   `model_add` (`sourceFile` and `sourceSymbol` from the card, `sourceProvenance: "extracted"`),
+   reading the code, not the plan, and ask the developer about the cards you can't place, in one short
+   list;
+   then call `codebase_extract` again to stage their relationships, and `model_delete` the
+   `candidateDeletes` that are really gone. Then `changeset_verify` with `planned: <name>` and
+   `against: {"changesetId": "<name>-as-built"}`. Fix each missing, unplanned or divergent item in
+   the code or in the plan. `unverifiable` items are planned parts extraction can't see (motivation,
+   re-exports, TypeScript tests), and `notes` are description-only differences: neither needs a
+   plan edit. Never edit the plan to match extracted placeholder text. A verdict of `unverifiable`
+   means the plan has nothing extraction can check; say so rather than call it a failure. Look for missing connections in the as-built too: for each element,
+   compare what the spec models for its type with what was staged, and look for evidence of each
+   absent one in the code (and the analyzer's graph, `dr analyzer callers` / `callees`). Confirm or
+   reject every `probable` match. `changeset_activate` the plan again afterwards (the extract
+   result's `previousActive`). After verify, the plan is what lands (step 8), not the as-built
+   changeset. Ask the human whether to discard the as-built changeset (`changeset_discard`,
+   `confirm: true`) or keep it as a record, and discard it only when they agree. Don't land it:
+   landing it first changes the plan's base, so the plan then needs `force`, and the plan's
+   descriptions don't apply to elements already in the base. It stays out of git: when you commit
+   fixes, add only the plan's directory again. If the as-built changes were landed anyway,
+   `against: {"base": true, "extracted": true}` compares the plan with the model, with extraction's blind spots applied.
+8. **Land.** The PR carries the code and the staged plan, and the human commits the plan in it, not
+   the as-built changeset. When they ask you to land it, call `changeset_commit` with its name. The server asks them
+   to confirm in a dialog that shows the name, intent, counts by operation, layers and drift, and
+   commits only if they confirm; if they decline, leave it staged. If it is refused for drift, show
+   them what drifted (`changeset_brief`) and pass `force: true` only if they still want it. Then add
+   the model's changed files and the changeset's directory to the branch. If it is refused, they land
+   it in the viewer (`review_open`, then Apply on the changeset), or you call it again from an
+   interactive session. Never point them to the `dr` CLI.
+
+## Tolerance
+
+Tools report odd input and carry on instead of failing. Read the report each time:
+
+- `relationship_add` reports a duplicate, or restores a relationship the plan had deleted.
+- `changeset_unstage` reports `not-staged` when there was nothing to drop.
+- In a changeset-only session (DrBot with `--with-changesets`), a write with no active changeset is
+  refused. Call `changeset_create` or `changeset_activate` and retry.
+- `changeset_commit` is refused when the human declines or cancels the dialog, when the client
+  can't show one (no MCP elicitation), and in DrBot, which doesn't have it. Nothing is written; the
+  human lands it in the viewer (`review_open`, then Apply), or from an interactive session.
+- DrBot cannot write annotations (`annotation_create` and `annotation_reply` are not among its
+  tools). There, record accepted gaps in the description with `changeset_update` and answer the
+  human's comments in the chat.
+- DrBot has no `review_open`: it runs in the viewer, so the human already has the plan in front
+  of them. Point them to the changeset in the viewer's Changesets view instead.
+
+## Keep it short
+
+Model at the grain of the change. One function, one operation and one test sketch beat a
+speculative tree. Add detail as the build firms up.

package/dist/integrations/claude_code/skills/dr_changeset_reviewer/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: dr_changeset_reviewer
+description: Review a DR changeset's staged changes for naming consistency, reference validity and layer-appropriate properties, and suggest improvements before it is committed. Use when the user works with changesets or asks for a review of one.
+---
+
 # Changeset Reviewer Skill
 
 When the user works with changesets or asks for review:
@@ -134,6 +139,9 @@ For each addition, check:
 - [ ] Layer-appropriate properties used
 - [ ] References point to existing elements
 - [ ] Status is valid for the element type
+- [ ] Connections the spec models for its type (`dr schema relationship <layer>.<type>`) are present
+      where the change needs them; within reason every modeled connection is expected, though not
+      every one will exist
 
 For each modification, check:
 

package/dist/integrations/claude_code/skills/dr_engineering_guide/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: dr_engineering_guide
+description: Engineering guidance grounded in the DR model, in three modes - review requirements before code is written, guide how an implementation is structured, and critique code that exists (PR or code review). Advisory only; it recommends the next DR step rather than changing the model.
+---
+
 # dr_engineering_guide — Engineering Guidance Skill
 
 ## Purpose
@@ -57,7 +62,7 @@ Map the proposed change to the 13-layer model:
 
 **2. Layer Hierarchy Check**
 
-- Does the proposal respect the "higher layers reference lower layers" rule?
+- Do the proposed relationships use predicates whose direction matches their meaning (an application function `realizes` an API operation; a service `serves` a process), and do implementation elements trace to a motivation element through `realizes`, `satisfies` or `supports`?
 - Example red flag: "A data-store change that has no corresponding data-model change"
 - Example red flag: "An API endpoint that doesn't map to any application service"
 

package/dist/integrations/github_copilot/agents/dr-architect.md

@@ -44,6 +44,8 @@ Unlike specialized agents that do one thing, you understand the **full picture**
 
 **Note**: The DR CLI is implemented in TypeScript and should be invoked using bash commands.
 
+**One `dr` command per Bash call.** Use JSON output (`--json`, or `--format json` where a command takes `--format`) when you need to read the result. Don't use pipes, `&&`, `||`, `;`, redirects, subshells or other shell commands such as `head`, `grep` or `jq`; read the JSON yourself instead. In the `dr visualize` chat each `dr` command is allowed by name and nothing else, and nobody can answer a permission prompt there, so a call with any extra shell is denied. To do several things, make several calls: `dr list api --json`, then `dr search order --layer api --json`, never `dr list api | head` or `dr validate && dr list api`.
+
 ## Knowledge Base: DR Specification v0.8.1
 
 ### The 13-Layer Architecture
@@ -105,7 +107,7 @@ x-supports-goals: [motivation.goal.revenue]
 
 ```yaml
 motivation:
-  supports-goals: [motivation.goal.revenue]
+  supports: [motivation.goal.revenue]
 business:
   realizes-services: [business.service.orders]
 ```