@documentation-robotics/cli 0.1.13 → 0.3.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,85 @@ 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     | 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 +265,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 +286,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 +305,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,119 @@
+---
+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__dr__<tool>` (the prefix is whatever name
+  the server has in `.mcp.json`). If they are missing, tell the user to register `dr mcp` (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.
+- You never commit, apply or discard the plan. Those are the human's steps, and commit and apply are
+  not MCP tools.
+
+## The loop
+
+1. **Frame.** `changeset_list` first: if a changeset for this change exists, `changeset_activate` it
+   and continue. Otherwise `changeset_create` with a short kebab-case `name` and a `description`
+   that states the intent: what the change is for and what done looks like. 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. Pass `sourceFile`, `sourceProvenance` (`manual` for a planned location) and `sourceSymbol` 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.
+4. **Pressure-test.** `changeset_brief`, then `changeset_impact` for anything the brief questions.
+   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. Where `existingCount` is above
+     0, link an existing element; otherwise decide whether the change needs a new one. Use
+     `unwiredLayers` to see one layer in full, and `unwired: "none"` when you only need the gaps.
+   - 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. Ask them to look at it in `dr visualize` and comment on elements there.
+   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. Its "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.
+7. **Verify.** Write down what was built, separately from the plan: `changeset_create`
+   `<name>-as-built`, stage what the diff actually contains (read the code, not the plan), 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. 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`, when it is indexed). Confirm or reject
+   every `probable` match. `changeset_activate` the plan again afterwards. Tell the human the
+   as-built changeset can be discarded; discard it (`changeset_discard`, `confirm: true`) only when
+   they agree. Until then it stays out of git: when you commit fixes, add only the plan's
+   directory again. If the as-built changes are committed to the model instead of kept as a changeset,
+   `against: {"base": true}` compares the plan with the model.
+8. **Land.** Hand over: the PR carries the code and the staged changeset. The human commits it,
+   in the viewer or with `dr changeset commit`.
+
+## 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.
+- 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.
+
+## 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

@@ -134,6 +134,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

@@ -57,7 +57,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

@@ -105,7 +105,7 @@ x-supports-goals: [motivation.goal.revenue]
 
 ```yaml
 motivation:
-  supports-goals: [motivation.goal.revenue]
+  supports: [motivation.goal.revenue]
 business:
   realizes-services: [business.service.orders]
 ```