@documentation-robotics/cli 0.2.0 → 0.3.0

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

@@ -11,13 +11,13 @@ triggers:
     "test strategy",
     "coverage model"
   ]
-version: 0.8.1
+version: 0.8.3
 ---
 
 # Testing Layer Skill
 
 **Layer Number:** 12
-**Specification:** Metadata Model Spec v0.8.1
+**Specification:** Metadata Model Spec v0.8.3
 **Purpose:** Defines test coverage using ISP (Input Space Partitioning) Coverage Model, specifying coverage requirements, test cases, and input partitions.
 
 ---
@@ -30,7 +30,7 @@ The Testing Layer captures **test coverage strategy**:
 - **COVERAGE TARGETS** - What needs testing (APIs, features, data)
 - **INPUT PARTITIONS** - Partition input space for systematic coverage
 - **TEST CASES** - Concrete test case sketches
-- **CONTEXT VARIATIONS** - Environmental and contextual variations
+- **CONTEXT VARIATIONS** - Test strategy variation types (functional, load, security, regression, smoke, exploratory)
 - **COVERAGE GAPS** - Identified gaps in coverage
 
 This layer uses **ISP Coverage Model** (systematic input space partitioning).
@@ -44,26 +44,86 @@ This layer uses **ISP Coverage Model** (systematic input space partitioning).
 > **CLI Introspection:** Run `dr schema types testing` for the authoritative, always-current list of node types.
 > Run `dr schema node <type-id>` for full attribute details on any type.
 
-### Core Testing Entities (17 entities)
-
-| Entity Type                 | Description                              |
-| --------------------------- | ---------------------------------------- |
-| **TestCoverageModel**       | Root coverage model for system/component |
-| **TestCoverageTarget**      | What needs testing (API, feature, data)  |
-| **InputSpacePartition**     | Partition of input space                 |
-| **PartitionValue**          | Value/range within partition             |
-| **InputPartitionSelection** | Selected partition values for coverage   |
-| **CoverageRequirement**     | Specific coverage requirement            |
-| **TestCaseSketch**          | High-level test case description         |
-| **OutcomeCategory**         | Expected outcome categories              |
-| **ContextVariation**        | Environmental/contextual variation       |
-| **EnvironmentFactor**       | Environment-specific factor              |
-| **PartitionDependency**     | Dependencies between partitions          |
-| **CoverageGap**             | Identified gap in coverage               |
-| **CoverageExclusion**       | Explicitly excluded coverage             |
-| **CoverageSummary**         | Summary of coverage status               |
-| **TargetCoverageSummary**   | Coverage summary for target              |
-| **TargetInputField**        | Input field for target                   |
+### Core Testing Entities (17 types)
+
+| Entity Type                 | Description                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------ |
+| **TestCoverageModel**       | Root coverage model for system/component                                       |
+| **TestCoverageTarget**      | What needs testing (API, feature, data)                                        |
+| **InputSpacePartition**     | Partition of input space                                                       |
+| **PartitionValue**          | Value/range within partition                                                   |
+| **InputPartitionSelection** | Selected partition values for coverage                                         |
+| **InputSelection**          | Concrete resolved input value chosen from a partition for a specific test case |
+| **CoverageRequirement**     | Specific coverage requirement                                                  |
+| **TestCaseSketch**          | High-level test case description                                               |
+| **OutcomeCategory**         | Expected outcome categories                                                    |
+| **ContextVariation**        | Environmental/contextual variation                                             |
+| **EnvironmentFactor**       | Environment-specific factor                                                    |
+| **PartitionDependency**     | Dependencies between partitions                                                |
+| **CoverageGap**             | Identified gap in coverage                                                     |
+| **CoverageExclusion**       | Explicitly excluded coverage                                                   |
+| **CoverageSummary**         | Summary of coverage status                                                     |
+| **TargetCoverageSummary**   | Coverage summary for target                                                    |
+| **TargetInputField**        | Input field for target                                                         |
+
+---
+
+## Type Decision Tree
+
+Use this decision tree **before assigning a type** to any testing concept.
+
+```
+IS this the root coverage plan for a system, service, or feature?
+  → testing.testcoveragemodel
+
+IS this a specific thing being tested (an API operation, feature, workflow, data field)?
+  → testing.testcoveragetarget
+
+IS this a division of an input field's possible values (valid/invalid/boundary ranges)?
+  → testing.inputspacepartition
+
+IS this one specific value or boundary within a partition?
+  → testing.partitionvalue
+
+IS this a constraint that links partition values to other partitions (e.g., field B depends on field A)?
+  → testing.partitiondependency
+
+IS this a declarative selection of which partition values to exercise in a test run?
+  → testing.inputpartitionselection
+
+IS this a single concrete resolved value chosen from a partition for a specific test case?
+  → testing.inputselection
+
+IS this an overall coverage requirement (criteria like "each-choice", "pairwise")?
+  → testing.coveragerequirement
+
+IS this a concrete high-level description of a single test case?
+  → testing.testcasesketch
+
+IS this a category of expected outcomes (success, error, edge-case)?
+  → testing.outcomecategory
+
+IS this a test strategy variation type — functional, load, security, regression, smoke, or exploratory testing?
+  → testing.contextvariation
+
+IS this a concrete environmental setting with a specific value (e.g., os=Linux, locale=en-US, network=low-bandwidth)?
+  → testing.environmentfactor
+
+IS this an input field on a target that is mapped to partitions?
+  → testing.targetinputfield
+
+IS this an identified gap — something that should be tested but is not?
+  → testing.coveragegap
+
+IS this a deliberate decision to NOT test something, with documented rationale?
+  → testing.coverageexclusion
+
+IS this a rollup of coverage metrics across all targets?
+  → testing.coveragesummary
+
+IS this a per-target rollup of sketch/implementation/automation counts?
+  → testing.targetcoveragesummary
+```
 
 ---
 
@@ -79,22 +139,85 @@ Activate when the user:
 
 ---
 
-## Cross-Layer Relationships
-
-**Outgoing (Testing → Other Layers):**
+## 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"               |
 
-- `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`).
 
 ---
 
@@ -114,22 +237,22 @@ Activate when the user:
 
 ```bash
 # Add coverage model
-dr add testing test-coverage-model --name "API Coverage Model"
+dr add testing testcoveragemodel "API Coverage Model"
 
 # Add coverage target
-dr add testing test-coverage-target --name "Login API Coverage"
+dr add testing testcoveragetarget "Login API Coverage"
 
 # Add test case sketch
-dr add testing test-case-sketch --name "Valid Login Test"
+dr add testing testcasesketch "Valid Login Test"
 
 # List coverage models
-dr list testing test-coverage-model
+dr list testing --type testcoveragemodel
 
 # Validate testing layer
-dr validate --layer testing
+dr validate --layers testing
 
 # Export coverage report
-dr export --layer testing --format markdown
+dr export markdown --layers testing
 ```
 
 ---
@@ -137,22 +260,16 @@ dr export --layer testing --format markdown
 ## Example: Login API Coverage Model
 
 ```yaml
-id: testing.coverage-model.login-api
+id: testing.testcoveragemodel.login-api
 name: "Login API Coverage Model"
-type: test-coverage-model
+type: testcoveragemodel
 properties:
-  targets:
-    - testing.target.login-endpoint
-  coverageCriteria: each-choice
-  contextVariations:
-    - browser: [Chrome, Firefox, Safari]
-    - network: [high-speed, low-speed, offline]
-    - device: [desktop, mobile, tablet]
-  motivation:
-    supports-goals:
-      - motivation.goal.quality-assurance
-    fulfills-requirements:
-      - motivation.requirement.comprehensive-testing
+  version: "1.0"
+  description: "ISP coverage model for the Login API"
+```
+
+```bash
+dr relationship add testing.testcoveragemodel.login-api application.applicationcomponent.auth-service --predicate covers
 ```
 
 ---
@@ -160,33 +277,18 @@ properties:
 ## Example: Login Test Coverage Target
 
 ```yaml
-id: testing.target.login-endpoint
+id: testing.testcoveragetarget.login-endpoint
 name: "Login Endpoint Coverage"
-type: test-coverage-target
+type: testcoveragetarget
 properties:
-  targetRef: api.operation.login
-  inputFields:
-    - name: email
-      partitions:
-        - valid-email: [user@example.com]
-        - invalid-format: [notanemail, @example.com]
-        - missing: [null, empty]
-    - name: password
-      partitions:
-        - valid-password: [StrongPass123!]
-        - weak-password: [123, abc]
-        - missing: [null, empty]
-        - too-long: [1000-char-string]
-  outcomeCategories:
-    - success: 200 OK with auth token
-    - invalid-credentials: 401 Unauthorized
-    - validation-error: 400 Bad Request
-    - rate-limited: 429 Too Many Requests
-  testCases:
-    - testing.test-case.valid-login
-    - testing.test-case.invalid-email
-    - testing.test-case.invalid-password
-    - testing.test-case.missing-credentials
+  targetType: api-endpoint
+  description: "POST /auth/login — validates credentials and returns a JWT"
+  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
 ```
 
 ---
@@ -194,30 +296,48 @@ properties:
 ## Example: Test Case Sketch
 
 ```yaml
-id: testing.test-case.valid-login
+id: testing.testcasesketch.valid-login
 name: "Valid Login Test Case"
-type: test-case-sketch
+type: testcasesketch
 properties:
-  target: testing.target.login-endpoint
-  description: "Test successful login with valid credentials"
-  inputSelection:
-    email: valid-email
-    password: valid-password
-  contextSelection:
-    browser: Chrome
-    network: high-speed
-    device: desktop
-  expectedOutcome: success
-  expectedResponse:
-    status: 200
-    body:
-      token: JWT token present
-      user: User object with id and email
-  motivation:
-    supports-goals:
-      - motivation.goal.secure-authentication
+  status: draft
+  description: "Successful login with valid email and password returns 200 with JWT"
+  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
+
+Before declaring testing layer extraction complete, verify each type was considered:
+
+- [ ] **testcoveragemodel** — Root coverage model exists for each major system or component under test
+- [ ] **testcoveragetarget** — All APIs, features, workflows, and data paths being tested are captured
+- [ ] **inputspacepartition** — Input fields on each target have their value space partitioned
+- [ ] **partitionvalue** — Each partition has concrete representative values and boundary cases
+- [ ] **partitiondependency** — Cross-field constraints between partitions are documented
+- [ ] **inputpartitionselection** — Coverage selections specify which partition values are exercised
+- [ ] **inputselection** — Concrete resolved inputs are selected for each test case sketch
+- [ ] **coveragerequirement** — Coverage criteria (each-choice, pairwise, etc.) are specified
+- [ ] **testcasesketch** — High-level test case sketches cover the required combinations
+- [ ] **outcomecategory** — Expected outcome categories (success, error, edge) are defined per target
+- [ ] **contextvariation** — Test strategy variation types (functional, load, security, regression, smoke, exploratory) are captured
+- [ ] **environmentfactor** — Specific factor values for each context variation are recorded
+- [ ] **targetinputfield** — Input fields on coverage targets are explicitly mapped to partitions
+- [ ] **coveragegap** — Known gaps in coverage are documented with severity and affected requirements
+- [ ] **coverageexclusion** — Deliberate out-of-scope decisions are recorded with rationale and approver
+- [ ] **coveragesummary** — An overall coverage summary exists if aggregated metrics are needed
+- [ ] **targetcoveragesummary** — Per-target coverage rollups exist for targets with tracked implementation
+
+If any type has ZERO elements, explicitly decide:
+"This type doesn't apply to this codebase" with reasoning.
+
 ---
 
 ## Pitfalls to Avoid

package/dist/integrations/github_copilot/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 (`dr mcp`, registered in Copilot's MCP configuration with the
+  `DR_MCP_API_KEY` it prints on start; see `integrations/claude_code/docs/MCP_SERVER.md`). The
+  tool names below are the server's own; Copilot may show them with a server prefix. If the tools
+  are missing, tell the user to register the server and stop. Don't fall back to prose.
+- Staging writes files under `documentation-robotics/changesets/`.
+- 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/github_copilot/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/hash-utils.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/integrations/hash-utils.ts"],
-  "sourcesContent": ["/**\n * File Hashing Utilities\n *\n * Provides SHA256-based file hashing for change detection in integration files.\n * Uses streaming for memory efficiency when handling large files.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { createReadStream } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { existsSync } from \"node:fs\";\n\n/**\n * Compute SHA256 hash of a file, truncated to 8 characters\n *\n * Uses streaming to efficiently handle files of any size without loading\n * them entirely into memory. Matches Python implementation using the same\n * truncation length (8 characters) for consistency.\n *\n * @param filePath - Absolute path to file to hash\n * @returns Promise resolving to 8-character hex hash\n * @throws Error if file cannot be read\n *\n * @example\n * const hash = await computeFileHash('/path/to/file.ts');\n * // Returns: 'a1b2c3d4'\n */\nexport async function computeFileHash(filePath: string): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const hash = createHash(\"sha256\");\n    const stream = createReadStream(filePath);\n\n    stream.on(\"data\", (data: Buffer) => {\n      hash.update(data);\n    });\n\n    stream.on(\"end\", () => {\n      const fullHash = hash.digest(\"hex\");\n      resolve(fullHash.substring(0, 8));\n    });\n\n    stream.on(\"error\", (error: Error) => {\n      reject(error);\n    });\n  });\n}\n\n/**\n * Compute hashes for all files in a directory recursively\n *\n * Scans the directory tree and computes hashes for all files, optionally\n * filtering by a filename prefix. Returns a map of relative paths to hashes,\n * enabling efficient comparison of installed vs. source files.\n *\n * @param baseDir - Base directory to scan\n * @param prefix - Optional prefix filter (only include files matching prefix)\n * @returns Promise resolving to Map of relative paths to 8-character hashes\n * @throws Error if directory cannot be read\n *\n * @example\n * const hashes = await computeDirectoryHashes('/path/to/dir', 'dr-');\n * // Returns: Map { 'dr-file1.md' => 'a1b2c3d4', 'subdir/dr-file2.md' => 'e5f6g7h8' }\n */\nexport async function computeDirectoryHashes(\n  baseDir: string,\n  prefix?: string\n): Promise<Map<string, string>> {\n  const hashes = new Map<string, string>();\n\n  // Return empty map if directory doesn't exist\n  if (!existsSync(baseDir)) {\n    return hashes;\n  }\n\n  async function scanDir(dir: string, relativePrefix: string = \"\"): Promise<void> {\n    try {\n      const entries = await readdir(dir, { withFileTypes: true });\n\n      for (const entry of entries) {\n        const fullPath = join(dir, entry.name);\n        const relativePath = relativePrefix ? join(relativePrefix, entry.name) : entry.name;\n\n        if (entry.isDirectory()) {\n          // Recursively scan subdirectories\n          await scanDir(fullPath, relativePath);\n        } else if (entry.isFile()) {\n          // Check prefix filter\n          if (prefix && !entry.name.startsWith(prefix)) {\n            continue;\n          }\n\n          // Compute hash for file\n          try {\n            const hash = await computeFileHash(fullPath);\n            hashes.set(relativePath, hash);\n          } catch (error) {\n            // Log error but continue processing other files\n            console.error(`Failed to hash file ${fullPath}:`, error);\n          }\n        }\n      }\n    } catch (error) {\n      // Re-throw directory read errors\n      throw error;\n    }\n  }\n\n  await scanDir(baseDir);\n  return hashes;\n}\n"],
-  "mappings": "AAOA,SAAS,kBAAkB;AAC3B,SAAS,wBAAwB;AACjC,SAAS,eAAe;AACxB,SAAS,YAAY;AACrB,SAAS,kBAAkB;AAiB3B,eAAsB,gBAAgB,UAAgB;AACpD,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAU;AACrC,UAAM,OAAO,WAAW,QAAQ,GAC1B,SAAS,iBAAiB,QAAQ;AAExC,WAAO,GAAG,QAAQ,CAAC,SAAgB;AACjC,WAAK,OAAO,IAAI;IAClB,CAAC,GAED,OAAO,GAAG,OAAO,MAAK;AACpB,YAAM,WAAW,KAAK,OAAO,KAAK;AAClC,cAAQ,SAAS,UAAU,GAAG,CAAC,CAAC;IAClC,CAAC,GAED,OAAO,GAAG,SAAS,CAAC,UAAgB;AAClC,aAAO,KAAK;IACd,CAAC;EACH,CAAC;AACH;AAkBA,eAAsB,uBACpB,SACA,QAAe;AAEf,QAAM,SAAS,oBAAI,IAAG;AAGtB,MAAI,CAAC,WAAW,OAAO;AACrB,WAAO;AAGT,iBAAe,QAAQ,KAAa,iBAAyB,IAAE;AAC7D,QAAI;AACF,YAAM,UAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,GAAI,CAAE;AAE1D,iBAAW,SAAS,SAAS;AAC3B,cAAM,WAAW,KAAK,KAAK,MAAM,IAAI,GAC/B,eAAe,iBAAiB,KAAK,gBAAgB,MAAM,IAAI,IAAI,MAAM;AAE/E,YAAI,MAAM,YAAW;AAEnB,gBAAM,QAAQ,UAAU,YAAY;iBAC3B,MAAM,OAAM,GAAI;AAEzB,cAAI,UAAU,CAAC,MAAM,KAAK,WAAW,MAAM;AACzC;AAIF,cAAI;AACF,kBAAM,OAAO,MAAM,gBAAgB,QAAQ;AAC3C,mBAAO,IAAI,cAAc,IAAI;UAC/B,SAAS,OAAO;AAEd,oBAAQ,MAAM,uBAAuB,QAAQ,KAAK,KAAK;UACzD;QACF;MACF;IACF,SAAS,OAAO;AAEd,YAAM;IACR;EACF;AAEA,eAAM,QAAQ,OAAO,GACd;AACT;",
+  "sourcesContent": ["/**\n * File Hashing Utilities\n *\n * Provides SHA256-based file hashing for change detection in integration files.\n * Uses streaming for memory efficiency when handling large files.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { createReadStream } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { existsSync } from \"node:fs\";\n\n/**\n * Compute SHA256 hash of a file, truncated to 8 characters\n *\n * Uses streaming to efficiently handle files of any size without loading\n * them entirely into memory. Matches Python implementation using the same\n * truncation length (8 characters) for consistency.\n *\n * @param filePath - Absolute path to file to hash\n * @returns Promise resolving to 8-character hex hash\n * @throws Error if file cannot be read\n *\n * @example\n * const hash = await computeFileHash('/path/to/file.ts');\n * // Returns: 'a1b2c3d4'\n */\nexport async function computeFileHash(filePath: string): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const hash = createHash(\"sha256\");\n    const stream = createReadStream(filePath);\n\n    stream.on(\"data\", (data: string | Buffer) => {\n      hash.update(data);\n    });\n\n    stream.on(\"end\", () => {\n      const fullHash = hash.digest(\"hex\");\n      resolve(fullHash.substring(0, 8));\n    });\n\n    stream.on(\"error\", (error: Error) => {\n      reject(error);\n    });\n  });\n}\n\n/**\n * Compute hashes for all files in a directory recursively\n *\n * Scans the directory tree and computes hashes for all files, optionally\n * filtering by a filename prefix. Returns a map of relative paths to hashes,\n * enabling efficient comparison of installed vs. source files.\n *\n * @param baseDir - Base directory to scan\n * @param prefix - Optional prefix filter (only include files matching prefix)\n * @returns Promise resolving to Map of relative paths to 8-character hashes\n * @throws Error if directory cannot be read\n *\n * @example\n * const hashes = await computeDirectoryHashes('/path/to/dir', 'dr-');\n * // Returns: Map { 'dr-file1.md' => 'a1b2c3d4', 'subdir/dr-file2.md' => 'e5f6g7h8' }\n */\nexport async function computeDirectoryHashes(\n  baseDir: string,\n  prefix?: string\n): Promise<Map<string, string>> {\n  const hashes = new Map<string, string>();\n\n  // Return empty map if directory doesn't exist\n  if (!existsSync(baseDir)) {\n    return hashes;\n  }\n\n  async function scanDir(dir: string, relativePrefix: string = \"\"): Promise<void> {\n    try {\n      const entries = await readdir(dir, { withFileTypes: true });\n\n      for (const entry of entries) {\n        const fullPath = join(dir, entry.name);\n        const relativePath = relativePrefix ? join(relativePrefix, entry.name) : entry.name;\n\n        if (entry.isDirectory()) {\n          // Recursively scan subdirectories\n          await scanDir(fullPath, relativePath);\n        } else if (entry.isFile()) {\n          // Check prefix filter\n          if (prefix && !entry.name.startsWith(prefix)) {\n            continue;\n          }\n\n          // Compute hash for file\n          try {\n            const hash = await computeFileHash(fullPath);\n            hashes.set(relativePath, hash);\n          } catch (error) {\n            // Log error but continue processing other files\n            console.error(`Failed to hash file ${fullPath}:`, error);\n          }\n        }\n      }\n    } catch (error) {\n      // Re-throw directory read errors\n      throw error;\n    }\n  }\n\n  await scanDir(baseDir);\n  return hashes;\n}\n"],
+  "mappings": "AAOA,SAAS,kBAAkB;AAC3B,SAAS,wBAAwB;AACjC,SAAS,eAAe;AACxB,SAAS,YAAY;AACrB,SAAS,kBAAkB;AAiB3B,eAAsB,gBAAgB,UAAgB;AACpD,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAU;AACrC,UAAM,OAAO,WAAW,QAAQ,GAC1B,SAAS,iBAAiB,QAAQ;AAExC,WAAO,GAAG,QAAQ,CAAC,SAAyB;AAC1C,WAAK,OAAO,IAAI;IAClB,CAAC,GAED,OAAO,GAAG,OAAO,MAAK;AACpB,YAAM,WAAW,KAAK,OAAO,KAAK;AAClC,cAAQ,SAAS,UAAU,GAAG,CAAC,CAAC;IAClC,CAAC,GAED,OAAO,GAAG,SAAS,CAAC,UAAgB;AAClC,aAAO,KAAK;IACd,CAAC;EACH,CAAC;AACH;AAkBA,eAAsB,uBACpB,SACA,QAAe;AAEf,QAAM,SAAS,oBAAI,IAAG;AAGtB,MAAI,CAAC,WAAW,OAAO;AACrB,WAAO;AAGT,iBAAe,QAAQ,KAAa,iBAAyB,IAAE;AAC7D,QAAI;AACF,YAAM,UAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,GAAI,CAAE;AAE1D,iBAAW,SAAS,SAAS;AAC3B,cAAM,WAAW,KAAK,KAAK,MAAM,IAAI,GAC/B,eAAe,iBAAiB,KAAK,gBAAgB,MAAM,IAAI,IAAI,MAAM;AAE/E,YAAI,MAAM,YAAW;AAEnB,gBAAM,QAAQ,UAAU,YAAY;iBAC3B,MAAM,OAAM,GAAI;AAEzB,cAAI,UAAU,CAAC,MAAM,KAAK,WAAW,MAAM;AACzC;AAIF,cAAI;AACF,kBAAM,OAAO,MAAM,gBAAgB,QAAQ;AAC3C,mBAAO,IAAI,cAAc,IAAI;UAC/B,SAAS,OAAO;AAEd,oBAAQ,MAAM,uBAAuB,QAAQ,KAAK,KAAK;UACzD;QACF;MACF;IACF,SAAS,OAAO;AAEd,YAAM;IACR;EACF;AAEA,eAAM,QAAQ,OAAO,GACd;AACT;",
   "names": []
 }

package/dist/mcp/api-key-manager.js

@@ -29,6 +29,16 @@ class ApiKeyManager {
       throw new Error(`API key file at ${path} is empty or corrupt. Delete it and re-run to generate a new key, or restore a valid key file.`);
     return key;
   }
+  /** The key stored at `path`, or null when there is no usable key file there. */
+  async loadIfPresent(path) {
+    if (!existsSync(path))
+      return null;
+    try {
+      return await this.load(path);
+    } catch {
+      return null;
+    }
+  }
   /** Write a key to disk with owner-only permissions. */
   async store(path, key) {
     await mkdir(dirname(path), { recursive: !0 }), await writeFile(path, `${key}
@@ -68,7 +78,10 @@ class ApiKeyManager {
     const config = await this.loadConfigOrThrow(), existingPath = config.mcp?.api_key_path;
     if (existingPath && existsSync(existingPath))
       return { key: await this.load(existingPath), path: existingPath, isNew: !1 };
-    const chosenPath = promptForPath ? await promptForPath(this.defaultKeyPath) : this.defaultKeyPath, key = this.generate();
+    const chosenPath = promptForPath ? await promptForPath(this.defaultKeyPath) : this.defaultKeyPath, adopted = await this.loadIfPresent(chosenPath);
+    if (adopted)
+      return await saveDRConfig({ ...config, mcp: { ...config.mcp, api_key_path: chosenPath } }), { key: adopted, path: chosenPath, isNew: !1 };
+    const key = this.generate();
     return await this.store(chosenPath, key), await saveDRConfig({
       ...config,
       mcp: { ...config.mcp, api_key_path: chosenPath }