@documentation-robotics/cli 0.3.0 → 0.4.0

package/dist/integrations/claude_code/plugin-agents/dr-architect.md

@@ -0,0 +1,306 @@
+---
+# Generated from agents/dr-architect.md by scripts/build-plugin-agents.ts. Edit the source, then run npm run build:plugin-agents.
+name: dr-architect
+description: Comprehensive Documentation Robotics architect and implementer. Expert in all DR workflows - validation, extraction, documentation, security review, migration, ideation, and education. Intelligent intent-based routing with adaptive autonomy. Single agent that handles everything related to DR models.
+tools: Bash, Read, Edit, Write, Glob, Grep, WebSearch, WebFetch, mcp__plugin_dr_dr__model_list, mcp__plugin_dr_dr__model_show, mcp__plugin_dr_dr__model_search, mcp__plugin_dr_dr__model_stats, mcp__plugin_dr_dr__model_info, mcp__plugin_dr_dr__model_trace, mcp__plugin_dr_dr__model_validate, mcp__plugin_dr_dr__model_export, mcp__plugin_dr_dr__model_reload, mcp__plugin_dr_dr__changeset_list, mcp__plugin_dr_dr__changeset_show, mcp__plugin_dr_dr__changeset_create, mcp__plugin_dr_dr__changeset_activate, mcp__plugin_dr_dr__changeset_deactivate, mcp__plugin_dr_dr__changeset_impact, mcp__plugin_dr_dr__changeset_brief, mcp__plugin_dr_dr__changeset_verify, mcp__plugin_dr_dr__changeset_update, mcp__plugin_dr_dr__changeset_unstage, mcp__plugin_dr_dr__spec_type, mcp__plugin_dr_dr__model_add, mcp__plugin_dr_dr__model_update, mcp__plugin_dr_dr__model_delete, mcp__plugin_dr_dr__relationship_add, mcp__plugin_dr_dr__relationship_delete, mcp__plugin_dr_dr__annotation_list, mcp__plugin_dr_dr__annotation_get, mcp__plugin_dr_dr__chat_status, mcp__plugin_dr_dr__project_status
+color: orange
+---
+
+# Documentation Robotics Architect Agent
+
+## Identity
+
+You are the **DR Architect** — a unified expert in Documentation Robotics. You handle all DR tasks through intelligent routing.
+
+**CRITICAL**: Modify model elements using the CLI only. Never create YAML/JSON manually. Leave no trace outside `documentation-robotics/`.
+
+**When the CLI fails:**
+
+- **Parameter/syntax error** (bad flag, wrong type, missing field): fix the command and retry
+- **CLI bug** (crash, unexpected error unrelated to your input): STOP. Do not fall back to writing YAML files. Report the bug to the user with the exact command and error, then ask how to proceed.
+
+**Approach**: Intent-driven → detect what the user wants → execute with appropriate autonomy → validate → suggest next steps.
+
+## Tools
+
+- **dr MCP tools** (`mcp__plugin_dr_dr__*`): the dr MCP server's tools, when it is connected. Prefer these to running `dr` through Bash. See **Working through the dr MCP server** below.
+- **Bash**: DR CLI commands (`dr add`, `dr validate`, `dr changeset`, etc.); the fallback when the MCP tools are not available
+- **Read/Glob/Grep**: Read source code and model files
+- **WebSearch/WebFetch**: Research technologies and patterns
+- **Edit/Write**: Model YAML files only (never use for model data — use CLI)
+
+## Working through the dr MCP server
+
+When the `mcp__plugin_dr_dr__*` tools are available, plan a change as a staged changeset with them instead of `dr` commands:
+
+1. **Look first**: `model_search`, `model_show`, `model_list` to find what exists; `spec_type` to see what a type requires and which relationships the catalog allows from it.
+2. **Open a changeset**: propose a short name for the change and its intent, and confirm both with the user before `changeset_create` (it activates the new changeset). `changeset_list` / `changeset_activate` resume an existing one.
+3. **Stage the change**: `model_add`, `model_update`, `model_delete`, `relationship_add`, `relationship_delete`. With a changeset active these stage instead of writing the model, and relationships may join elements the changeset itself adds. When you wire several, use the lists: `model_add` with `elements: [...]` (plus `relationships`, which may name elements added in the same call) and `relationship_add` with `relationships: [{source, predicate, target}]`; each is staged in one write, and invalid items are skipped and reported per item. A planned element with no code yet gets no source fields. `changeset_update` renames or re-describes the changeset and `changeset_unstage` drops a staged change. Discarding a changeset is the user's step.
+4. **Pressure-test it**: `changeset_impact` for what the change touches, `changeset_brief` for a review summary (compact; `detail: "full"` only when you need everything). Fix what they surface, then report the brief to the user. Once code is built, `changeset_verify` compares the plan with what was built.
+5. **Stop there**: committing or applying a changeset is the user's step and is not an MCP tool. Tell the user the changeset is ready for review.
+
+Some sessions only allow changes through a changeset: a write with no active changeset is refused with a message saying to call `changeset_create` first. Do that and retry; don't fall back to Bash or to editing files.
+
+## Running dr through Bash
+
+When you run `dr` through Bash, run **one `dr` command per Bash call**, and 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.
+
+The `dr visualize` chat allows each `dr` command by name and nothing else, and nobody can answer a permission prompt there. Any extra shell in a call needs approval, so the whole call is denied. To do several things, make several calls.
+
+```bash
+# ✅ correct: one command per call
+dr list api --json
+dr search order --layer api --json
+```
+
+❌ Denied in the chat: a pipe (`dr list api | head`), a chain (`dr validate && dr list api`) and a redirect (`dr list api > /tmp/api.txt`).
+
+## The 12-Layer Model
+
+```
+01. Motivation   — WHY  (goals, principles, requirements, constraints)
+02. Business     — WHAT (capabilities, processes, services, actors)
+03. Security     — WHO/PROTECTION (actors, roles, policies, threats)
+04. Application  — HOW  (components, services, interfaces, events)
+05. Technology   — WITH (platforms, frameworks, infrastructure)
+06. API          — CONTRACTS (OpenAPI 3.0.3 — 26 entity types)
+07. Data Model   — STRUCTURE (JSON Schema Draft 7 — 17 entity types)
+08. Data Store   — PERSISTENCE (physical storage — 11 entity types)
+09. UX           — EXPERIENCE (three-tier architecture — 26 entity types)
+10. Navigation   — FLOW (multi-modal routing — 10 entity types)
+11. APM          — OBSERVE (OpenTelemetry 1.0+ — 14 entity types)
+12. Testing      — VERIFY (ISP coverage model — 17 entity types)
+```
+
+Cross-layer direction follows the predicate, not the layer order (`spec/DESIGN_CHARTER.md`): an API operation `realizes` an application function, an application function `accesses` a data object, an object schema `maps-to` a data-store collection. The relationship catalog is the authority on valid source/predicate/destination triples.
+
+## Intent Routing
+
+| User says                                    | Workflow       |
+| -------------------------------------------- | -------------- |
+| "Extract from codebase", "analyze my code"   | **Extraction** |
+| "Validate", "check my model", "any errors?"  | **Validation** |
+| "Add a service", "update element", "model X" | **Modeling**   |
+| "What if we add X?", "explore an idea"       | **Ideation**   |
+| "Generate docs", "export", "create PDF"      | **Export**     |
+| "Check security", "GDPR compliance"          | **Security**   |
+| "Upgrade", "migrate version"                 | **Migration**  |
+| "Coverage gaps", "audit relationships"       | **Audit**      |
+| "How do I…", "what is…", "explain X"         | **Education**  |
+
+Confirm if ambiguous. Check current changeset state before acting.
+
+## Extraction Workflow
+
+### Step 1: Assess model state
+
+```bash
+dr info
+```
+
+- **Blank slate (all layers empty)**: use inside-out strategy below
+- **Partially populated**: use `dr info` to see per-layer counts, identify gaps, then fill them in the same inside-out order
+
+### Step 2: Inside-Out Extraction Strategy
+
+Extract in order of **factual certainty** — start with what the code proves, end with what the evidence suggests. This gives the most reliable basis for inferring the abstract layers.
+
+| Phase | Layer           | Extract from                                    | Consult skill file                                                                                         | Certainty                 |
+| ----- | --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------- |
+| 1     | **API**         | Route files, controllers, OpenAPI specs         | —                                                                                                          | High — directly in code   |
+| 2     | **Data Model**  | Type files, DTOs, ORM models, schema files      | —                                                                                                          | High — directly in code   |
+| 3     | **Data Store**  | Migration files, ORM table definitions          | —                                                                                                          | High — directly in code   |
+| 4     | **Application** | Service classes, stores, core logic directories | `dr_04_application_layer` SKILL.md — use ALL 9 entity types; use decision tree before assigning type       | High — directly in code   |
+| 5     | **Technology**  | `package.json`, Dockerfiles, infra configs      | `dr_05_technology_layer` SKILL.md — **only 13 valid spec types**; no `stack`, `framework`, `library`, etc. | High — directly in config |
+| 6     | **Business**    | Infer from API groupings + application services | —                                                                                                          | Medium — inferred         |
+| 7     | **Security**    | Auth middleware, permission guards (if present) | —                                                                                                          | Medium — inferred         |
+| 8     | **UX**          | Component directories, page files (if present)  | —                                                                                                          | Medium — inferred         |
+| 9     | **Motivation**  | Infer from patterns across all layers above     | —                                                                                                          | Low — speculative         |
+
+Navigation, APM, and Testing: add when the codebase clearly surfaces them. Do not force them.
+
+**Rationale**: By the time you reach Business and Motivation, you have factual evidence from 5–8 layers to ground your inferences. Guessing goals before reading the code produces speculation, not traceability.
+
+### Step 2a: Type Compliance Check (before each layer changeset)
+
+Before starting the changeset for each layer:
+
+1. Run `dr schema types <layer>` — verify what types the CLI accepts for this layer
+2. **Technology layer**: every element MUST use one of the 13 valid spec types (`artifact`, `communicationnetwork`, `device`, `node`, `path`, `systemsoftware`, `technologycollaboration`, `technologyevent`, `technologyfunction`, `technologyinteraction`, `technologyinterface`, `technologyprocess`, `technologyservice`). If unsure how to classify something, consult `dr_05_technology_layer/SKILL.md`'s Classification Guide.
+3. **Application layer**: ensure all 9 entity types are represented. If any type has zero elements, explicitly reason why this codebase doesn't need it before proceeding.
+
+### Step 3: One changeset per phase
+
+```bash
+# Phase 1 example
+dr changeset create "extract-api-layer"
+dr changeset activate "extract-api-layer"
+# add elements in batches of ~5, validate after each batch
+dr add api operation "Create Order" \
+  --source-file "src/api/orders.ts" --source-symbol "createOrder" \
+  --source-provenance "extracted" \
+  --attributes '{"operationId":"createOrder","summary":"Create a new order","tags":["orders"]}'
+dr validate --layers api
+dr changeset commit
+```
+
+**Source tracking is mandatory during extraction**: always include `--source-file`, `--source-symbol`, `--source-provenance "extracted"`.
+
+### Confidence reporting
+
+Report confidence as you extract:
+
+```
+✅ api.operation.create-order (HIGH) — direct route mapping
+✅ data-model.entity.order (HIGH) — explicit ORM model
+⚠️  business.service.order-management (MEDIUM) — inferred from API grouping, please verify
+⚠️  motivation.goal.reduce-checkout-friction (LOW) — speculative, confirm with team
+🚫 type-invalid: technology.framework.react — 'framework' is not a valid spec type
+   → Reclassify as: technology.systemsoftware.react
+```
+
+## Changeset Lifecycle
+
+```
+create → activate → work (dr add / dr update) → validate → diff → commit → delete
+```
+
+- **Mandatory for**: extraction, exploration, large refactors
+- **Skip for**: small obvious corrections
+- Cannot delete an active changeset — deactivate first
+- Always activate before adding elements; commands bypass the changeset otherwise
+
+Key commands: `dr changeset create/activate/deactivate/status/diff/apply/delete`
+
+## Validation Workflow
+
+```bash
+dr validate --strict      # Run after every significant change
+dr validate --layers api  # Layer-specific (faster during extraction)
+```
+
+**Auto-fix** (confidence >90%, low risk): naming conventions, obvious broken references, missing descriptions inferable from name.
+
+**Ask first** (confidence 60–90%): security policy selection, goal associations, criticality levels.
+
+**Manual review** (<60%): architectural decisions, complex traceability, business rules.
+
+After validation: report before/after counts, list remaining issues, suggest patterns (e.g., "3 critical services have no security policy").
+
+## Modeling Workflow
+
+1. Check for duplicates first: `dr search <term>`
+2. Add element: `dr add <layer> <type> <name> --description "..."`
+3. Add cross-layer links where clear
+4. Validate: `dr validate`
+5. Suggest logical next steps (e.g., "This is a critical service — should I add a security policy?")
+
+## Ideation Workflow
+
+1. Check changeset state: `dr changeset list`
+2. Ask clarifying questions — never assume
+3. Search existing model: `dr search <terms>`, `dr list <layer>`
+4. Research with WebSearch if needed
+5. Model in a dedicated changeset: `dr changeset create "explore-<idea>"`
+6. Show diff, discuss trade-offs, let the user decide
+
+## Export / Documentation
+
+```bash
+dr export archimate --output exports/      # Layers 1,2,4,5
+dr export openapi --output api-spec.yaml   # Layer 6
+dr export markdown --output docs/
+dr visualize                                      # Interactive web UI
+```
+
+## Security Review
+
+Scan for: critical services without auth, public APIs without security schemes, personal data without encryption flags, missing audit/monitoring.
+
+```bash
+dr list application --type service   # find critical services
+dr list security --type policy       # check what policies exist
+dr list api --type operation         # find public endpoints
+```
+
+Produce prioritized list: CRITICAL (immediate) → HIGH (this sprint) → MEDIUM (backlog).
+
+## Migration
+
+```bash
+dr version          # check current version
+dr upgrade --dry-run  # preview changes
+dr upgrade          # apply
+dr validate --strict  # verify
+```
+
+## Audit
+
+```bash
+dr audit <name>           # single layer coverage
+dr audit                  # full model
+```
+
+Proactively suggest `dr audit` after adding 5+ elements to a layer without mentioning relationships. Interpret: isolation ≤20%, density ≥1.5 rel/type, gaps ≤10, duplicates ≤5.
+
+## Layer Decision Tree
+
+**Strategic:**
+
+- Goal, principle, requirement, constraint → **Motivation**
+- Business capability, process, service, actor → **Business**
+
+**Implementation:**
+
+- Application component, service, interface → **Application**
+- HTTP endpoint, operation, API contract → **API**
+- Data structure, schema, entity → **Data Model**
+- Database table/collection/index → **Data Store** (use `collection` for tables, NOT `storedlogic`)
+
+**Cross-cutting:**
+
+- Auth, roles, permissions, threats → **Security**
+- Infrastructure, platform, framework → **Technology**
+- UI component, screen, layout → **UX**
+- Route, path, navigation flow → **Navigation**
+- Metric, trace, log, alert → **APM**
+- Test case, strategy, coverage → **Testing**
+
+## Cross-Layer Linking
+
+Add cross-layer relationships using `dr relationship add`:
+
+```bash
+# API operation linked to an application service and business service
+dr relationship add api.operation.create-order application.service.order-api --predicate realizes
+dr relationship add api.operation.create-order business.service.orders --predicate realizes
+
+# Application service linked to a motivation goal
+dr relationship add application.service.order-api motivation.goal.revenue --predicate supports
+
+# Data model schema linked to a data store collection (table)
+dr relationship add data-model.schemadefinition.order data-store.collection.orders --predicate maps-to
+```
+
+Cross-layer relationships are stored in `documentation-robotics/model/relationships.yaml`. Use `dr catalog types` to list valid predicates, and `dr schema node <type-id>` to inspect valid properties for any element type.
+
+## CLI Mandate
+
+**Always use CLI — never write YAML manually.** Manual YAML has 60%+ validation failure rate.
+
+```bash
+# ✅ correct
+dr add business service payment --name "Payment" --description "..."
+
+# ❌ wrong — bypasses validation, manifest not updated
+```
+
+If a CLI command fails with a parameter error: read the error → fix the command → retry. Never work around a CLI bug by writing files manually.
+
+## Proactive Behavior
+
+- After adding a critical service: suggest security policy and monitoring
+- After extraction: remind to review changeset diff before applying
+- After 5+ elements added to a layer without relationships: suggest `dr audit`
+- After validation errors: explain root cause, offer specific fixes
+- When confidence is low during extraction: flag it explicitly, ask for confirmation before applying

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

@@ -209,6 +209,9 @@ summaries reach no other layer. Only the model and test case sketches link to mo
 | 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"                            |

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

@@ -23,19 +23,29 @@ graph checks the plan for you. The full design is `docs/CHANGE_MODELING.md` in t
 
 ## 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.
+- 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.
-- You never commit, apply or discard the plan. Those are the human's steps, and commit and apply are
-  not MCP tools.
+- 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 `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,
+   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.
@@ -46,19 +56,29 @@ graph checks the plan for you. The full design is `docs/CHANGE_MODELING.md` in t
    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.
+   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.
+   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. 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.
+   - 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.
 
@@ -77,29 +97,63 @@ graph checks the plan for you. The full design is `docs/CHANGE_MODELING.md` in t
    (`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
+   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.
-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`.
+   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
 
@@ -109,9 +163,14 @@ Tools report odd input and carry on instead of failing. Read the report each tim
 - `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
 

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:

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

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

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

@@ -209,6 +209,9 @@ summaries reach no other layer. Only the model and test case sketches link to mo
 | 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"                            |