dsh-model-everything 0.0.0-stage → 0.2.0

package/skills/model-everything-report-reading/references/reading-a-report.md

@@ -0,0 +1,166 @@
+# How to read a report
+
+Every tool returns a report. They share one skeleton, and they differ in where they keep their
+findings. This guide is the reading order: what to look at first, what each field answers, and what
+a report does not tell you.
+
+The structure of this guide is the mind map beside it, which is generated from live reports rather
+than drawn. A hand-drawn map drifts; this one cannot claim a shape the engines do not produce.
+
+## The three questions, in order
+
+### 1. Did it run?
+
+`ran` separates a tool that refused from one that ran, but it answers that question for one kind of
+refusal only. A call refused at the boundary — an argument in the wrong shape, a format that does not
+exist, a notation that is not one — comes back with `ran: false`, an `errorCode`, and a
+`verdictReason` beginning "the tool did not run". There is no verdict to route on, so fix the call.
+
+An input the engine's own schema rejects is a different shape, and it matters more because it looks
+like a review: `ran: true` (the engine did run), `ok: false`, `verdict: fail`, no `errorCode`, and one
+finding under a check whose id is `MODEL`, `DATA_MODEL` or `DESIGN`. Its `summary.checksRun` is `0`.
+Read it as "the input is the problem, not the design" — a model that was actually reviewed examined
+something, so a non-zero `checksRun` is what separates a defective model from a malformed one.
+
+So a refusal and a failing review need different responses, and `ran` alone does not tell them apart:
+the test is `ran: false`, or `checksRun: 0` beside a check named after the validation.
+
+### 2. What did it decide?
+
+`verdict` is the answer, and it has three values:
+
+| `verdict` | Means |
+|---|---|
+| `pass` | The checks ran and found nothing to report |
+| `pass_with_findings` | Warnings only; nothing decided against the model |
+| `fail` | At least one error finding |
+
+Read `verdict`, never `ok`. `ok` carries a different historical meaning in each family — in most it
+is `true` for a failing review, and a composition sets it to `false` when any error-severity finding
+exists — so it cannot be read as a verdict, and reading it as one is how a reader concludes the
+opposite of what the report says. A report with `verdict: "fail"` is a successful run that found
+something; that is the normal way this plugin tells you about a defect.
+
+`verdictReason` is the one-line why, and it names the first error code. When the verdict is not what
+you expected, that string is where to start.
+
+### 3. What should I do?
+
+`nextSteps` is never empty, and it is derived from the findings rather than written beside them. It
+names the route to whatever covers the ground the report does not: another check, a source-side
+scan, or an external checker.
+
+## The skeleton every report shares
+
+`ok`, `ran`, `verdict`, `verdictReason`, `schema`, `summary`, `nextSteps` — every family carries all
+of them. `schema` is the versioned contract, so a reader can tell which shape it is holding.
+
+`hashes` and `modelHash` are there so two reports can be compared. The same input and the same hash
+spec give the same hash; a changed hash means the model changed, which is what makes a diff
+meaningful.
+
+`summary.boundNotes` records a budget that was replaced or clamped, and `metadataKeys` lists the
+`_`-prefixed keys the schema ignored. Both are printed by the rendered body (`BOUND`, `METADATA`),
+so a reader who only has the text still learns that the numbers came from a different bound than
+the one they asked for, and that a field they wrote was treated as annotation.
+
+A report can also carry notes beside its findings — `warnings` holds what a notation or a parser
+could not carry. They count towards the verdict, so the body prints them under `WARNING`, and the
+`FINDINGS` line says how many there are when the roster itself is empty. A body that shouted
+"nothing was reported" over a note the verdict had already counted was the defect this line fixes.
+
+## Where the findings are
+
+This is the part that varies, and it is worth knowing before you go looking:
+
+| Where | Families |
+|---|---|
+| Inside each check, as `checks[].findings` | `model_verify`, `model_compose_verify`, `model_datamodel_verify`, `model_design_review` |
+| At the top level, as `findings` | `uml_structure_verify`, the `uml` review path, `model_interleaving_scan` |
+| Nowhere — compare `added` / `changed` / `removed` | `report_diff` |
+
+A check-carried finding is attributed to a check, and the check also carries a status of its own:
+`pass`, `fail`, or `skip`. A top-level finding has no check to attribute it to, which is why those
+families report a `summary` instead.
+
+The status is coarse on purpose: `fail` means the check has a finding, not that the finding is severe.
+A check holding only warnings is `fail` just as a check holding errors is, so `status` alone cannot tell
+you whether the verdict moved - the finding's own severity does that. The rendered body separates them,
+because a human reads it: `fail` there means at least one error, and `warn` means warnings only. When
+the body lists a check under `warn` and the JSON gives that same check `"status": "fail"`, both are
+correct and they answer different questions.
+
+`summary.checksRun` counts the checks that examined the model, so it is smaller than the number of check
+objects whenever something was skipped. `summary.checksSkipped` names those, and it is absent when
+nothing was skipped.
+
+`report_diff` is the exception in a second way: it has no findings because its subject is the
+difference between two other reports. `verdict` describes the delta, and `currentVerdict` describes
+the current run on its own terms. The two differ exactly when the run is not clean but the delta is
+empty — comparing a failing report against itself gives `verdict: "pass", currentVerdict: "fail"`,
+and both are true: nothing changed, and the run fails.
+
+A delta looks at three things, and only one of them is "new": `added`, `removed`, and `changed` — a
+finding that kept its identity and moved. A warning that became an error is in `changed`, not in
+`added`, and it still fails the delta: the slice added nothing and made the report worse. A change
+the other way, error to warning, is named too, and does not fail it.
+
+## Read the severity before the code
+
+Within a finding, the severity decides whether it changed the verdict:
+
+- **error** — this is what makes the verdict `fail`;
+- **warning** — reported, does not fail the delta;
+- **info** — context, for example that one element makes an inseparable group of findings;
+- **undecided** — the search stopped before deciding. Not a pass. `summary.truncated` says the same
+  thing for the report as a whole, and the rendered body leads with a `LIMIT` line, so a reader who
+  only has the text is told before reaching any finding.
+
+The finding codes are prefixed by the check that owns them (`S1`, `A4`, `DS5`, `DA2`, `DES12`,
+`UML023`), so a code tells you where to look even before you read its message.
+
+### A code is for you, not for the person you are answering
+
+The codes exist so you can route a finding to the reference that explains it, and so a run is comparable
+with the last one. A user who never read the report has no idea what `A4_NO_RELEASE_EVENT` means, and a
+reply that recites codes makes the work look opaque while telling them nothing they can act on.
+
+**Say what the finding says, in words.** Each finding's own `message` is already a sentence written for a
+reader who does not know the codes. Use it. Name the code afterwards only when it helps the user find the
+same line in the report, and give it a meaning at the same time: not "S7 failed", but "the invariant is
+violated - the model reaches C after two events (`S7_INVARIANT_VIOLATION`)".
+
+The same rule covers a check id: `Event Completeness` is the name, `S5` is the label. Lead with the name.
+
+One code is worth relaying with its reason rather than its name. A model whose reachable state space is
+infinite is reported as `S6_UNBOUNDED_VARIABLE`, an error, and the point to pass on is that **no** search
+bound would have decided it: the question is undecidable for that model, not merely unanswered.
+
+## What each family adds
+
+Beyond the skeleton, each family carries what its own domain needs: a graph, a round-trip record,
+a notation, a rendered source, the three delta lists, or a design review's split of `violations`,
+`signals` and `facts`. Read `schema` to know which one you have, then read the section that belongs
+to it.
+
+The design review's three lists are worth knowing, because only the first decides anything:
+
+- `violations` — the check levels that decide the verdict. Ten codes carry it, from a dependency
+  cycle to a type relation that resolves to nothing;
+- `signals` — four codes that are worth a look and fail nothing;
+- `facts` — no findings at all: one measurement object with the graph's numbers (`density`, `ranks`,
+  `articulationPoints`, `feedbackArcs`, `largestCycle`). It also carries `checksSkipped`, which is
+  where a reader learns that nine of the checks never ran for want of a declaration.
+
+No code appears in both `violations` and `signals`: the split is exclusive, so a reader who reads
+only `violations` sees every finding that decided the verdict and none that did not.
+
+## What a report does not tell you
+
+- **It is about the model, not the code.** A clean verdict is evidence about the drawing you
+  supplied. Reconciling it with the source is a separate step, and the difference between the two is
+  where the finding usually is.
+- **A truncated search decided nothing.** When `truncated` is true, the checks that stopped early
+  report themselves as undecided rather than as passes.
+- **A skipped check examined nothing.** `skip` and `pass` are different answers: a check that had no
+  vocabulary to work with did not look, and saying so is the point.

package/skills/model-everything-report-reading/references/reading-a-report.mmd

@@ -0,0 +1,59 @@
+mindmap
+root((how to read a report))
+  the three questions in order
+    did it run
+      ran tells a refusal apart from a review
+      a refusal carries no verdict to route on
+    what did it decide
+      verdict is the answer
+      ok is not a verdict, see the misreadings
+      verdictReason is the one-line why
+    what should I do
+      nextSteps is never empty
+      it is derived from the findings
+  the skeleton every report shares
+    ok
+    ran
+    verdict
+    verdictReason
+    schema
+    summary
+    nextSteps
+    hashes and modelHash
+      same input and same spec give the same hash
+      a changed hash means the model changed
+  where the findings are
+    inside each check: verify compose datamodel design
+    at the top level: structure uml concurrency
+    nowhere, compare the three lists: baseline
+  read severity before the code
+    error decides the verdict
+    warning is reported and does not
+    info is context
+    undecided is not a pass
+      truncated says the search stopped early
+      an infinite state space is a finding of its own
+  what each family adds
+    verify adds checks metadataKeys
+    compose adds checks
+    datamodel adds checks
+    design adds the graph numbers and three lists
+    structure adds findings graph notation warnings
+    uml adds findings metadataKeys primary roundTrip source warnings
+    concurrency adds findings
+    baseline adds added changed currentVerdict removed
+    only violations decide, signals do not, facts are numbers
+      no code is in both lists
+  what a report does not tell you
+    it is about the model not the code
+      a clean verdict is evidence about the drawing
+    a truncated search decided nothing
+    a skipped check examined nothing
+      skip and pass are different answers
+  the two easy misreadings
+    ok is not the verdict
+      it means no error finding in most families
+      a composition sets it false where verify sets it true
+    a delta and a run answer different questions
+      verdict is the delta, currentVerdict is the run
+      an unchanged failing report is pass over fail

package/skills/model-everything-structure/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: model-everything-structure
+description: "Use when auditing architecture or module structure from a drawing. It reads component, package, class, object or deployment diagrams as a dependency graph and checks isolated nodes, dangling endpoints, cycles, allowed-dependency violations, layer violations and missing required edges, across one level or several. Audits the drawing, not the code — reconcile it with a source-side scan. SRP/LSP/ISP questions are model-everything-design. Doctrine: the model-everything skill."
+---
+
+# Model Everything — Structure and Dependency Review
+
+A component diagram is a model of an architecture, and a model can be wrong. This skill audits the graph the diagram actually draws — nodes and dependency arrows — against a declared dependency matrix, and says plainly what that does and does not prove.
+
+The claim-verification doctrine it inherits — cite evidence, read `verdict` and never `ok` — lives in the `model-everything` skill. Load that one for behavioural claims (state machines, protocols, timing); load this one when the question is *where the dependencies point*.
+
+## When This Skill Applies
+
+| The task involves… | What it does |
+|---|---|
+| "Review this architecture", "are the module dependencies sound", "is the layering right" | Parse the structure diagram into a graph, then run the structural checks below |
+| A component / package / class / deployment diagram (PlantUML) or a Mermaid class diagram | `uml_structure_verify` reads nodes, containers, labels and arrows; nothing is discarded |
+| A rule table of allowed dependencies (allow/deny, layers, required edges) | Every edge is judged against it and reported with the rule ids it matched |
+| One architecture drawn at several levels (repository / module / subdirectory) | `diagrams: [{name, diagram, parent}]`: each level is checked on its own, then against its declared parent, with the per-pair node/edge/expansion counts (`UML028`-`UML031`) |
+| A diagram that must be reconciled with an include/graph check over the source | The per-edge rule ids are the meeting point: a difference between the two is the finding worth chasing |
+
+A host without the tools runs the repository engine on the same diagram text, and on a `granularity` manifest for a multi-level set.
+
+## What It Checks
+
+| Code | Severity | What it means |
+|---|---|---|
+| `UML020_ISOLATED_NODE` | warning | A declared, non-container node with no edge at all. A dead entry, or a dependency the diagram forgot to draw. |
+| `UML021_DANGLING_REFERENCE` | error | An arrow endpoint that no declaration ever introduced. In a component diagram this is how a dependency on a component that does not exist stays invisible. |
+| `UML022_CYCLE` | error | A directed cycle, reported as the **shortest** cycle path. A cycle means no build order and no layering can hold. |
+| `UML023_DISALLOWED_EDGE` | error | An edge the matrix forbids — or, with `default: "deny"`, an edge no rule permits. The denying rule id is named. |
+| `UML024_LAYER_VIOLATION` | error | An edge from a lower declared layer into a higher one (a child depending on its parent). Downward edges are allowed. |
+| `UML025_MISSING_EXPECTED_EDGE` | warning | A rule with `require: true` whose edge the diagram does not draw — including the case where no node matches the source pattern at all. The matrix and the diagram disagree. |
+| `UML026_NO_NODES` | error | The text declares no node, so there is no structure to review. |
+| `UML028_UNKNOWN_PARENT` | error | A level names a parent that is not in the set. |
+| `UML029_REFINEMENT_VIOLATION` | error | Multi-level only: a child invents a dependency at the parent level, or drops a parent edge instead of expanding it into a path. |
+| `UML030_PARENT_CYCLE` | error | The declared parent relation is not a forest. |
+| `UML031_NO_DIAGRAMS` | error | Nothing was supplied to compare. |
+
+## The Dependency Matrix
+
+The matrix is the single source of truth the diagram is checked against. Keep it next to the rules it encodes, in JSON:
+
+```json
+{
+  "rules": [
+    { "id": "R1-app-may-use-hal", "source": "app.*", "allow": ["hal.*"], "deny": ["hal.internal"] },
+    { "id": "R2-adapter-owns-hal", "source": "PAY", "allow": ["DRV"], "deny": ["SVC"] },
+    { "id": "R3-no-back-edges", "source": "*", "deny": ["SVC"] },
+    { "id": "R4-persistence-required", "source": "PAY", "allow": ["DB"], "require": true }
+  ],
+  "layers": [
+    { "name": "app", "members": ["SVC", "PAY"] },
+    { "name": "hal", "members": ["DRV", "DB"] }
+  ],
+  "default": "deny"
+}
+```
+
+- `source`, `allow`, `deny` and `layers[].members` accept **node ids or globs** (`*` any run, `?` one character).
+- **`deny` wins globally.** A later rule's allow never resurrects an edge an earlier rule forbade; the result cannot depend on rule order.
+- `default: "allow"` (the default) means only the rules judge: an edge no rule mentions is `default`. `default: "deny"` closes the matrix — anything unlisted is `UML023`.
+- `require: true` turns a rule into an expectation about the diagram (`UML025`); it needs `allow` to say which edges must exist.
+- Layers are ordered **top first**: an edge from an earlier layer to a later one is allowed, the reverse is `UML024`.
+- Every edge is echoed in `edgeVerdicts` as `{from, to, line, matchedRules, allowed, basis}`, where `basis` is `allow` / `deny` / `default` / `unlisted`. That is the audit trail for the reconciliation below.
+
+## Reconciling With a Source-Side Check
+
+This tool audits the **diagram**; an include or dependency scan audits the **code**. They answer the same question from two sides, and each side can be the one that is wrong:
+
+1. Run both. Keep the rule ids identical on both sides — that is what makes a difference explainable.
+2. For every rule id, compare: does the diagram draw the edge, and does the source contain the dependency?
+3. Classify each difference instead of averaging it away:
+   - **Diagram missing an edge the code has** — the diagram is stale (`UML025` fires when the rule is `require: true`).
+   - **Diagram drawing an edge the code does not have** — either the diagram is aspirational, or the source scan's scope is narrower (different file set, generated code, conditional compilation).
+   - **Code violating an allowed dependency the diagram never showed** — the architecture defect the diagram was hiding. This is the one worth acting on.
+4. Report the difference with both citations. Never present the diagram as evidence about the code without saying which side produced which half.
+
+## Limits — Say These Out Loud
+
+- **The diagram may be wrong.** A clean `pass` means the drawn graph is internally consistent and satisfies the matrix — not that the code matches it. Only the reconciliation above touches the code.
+- **No transitive closure by default.** `A → B → C` does not report `A` reaching `C`; write the rule you mean, or add the edge the code actually has.
+- **No runtime behaviour.** Calls through function pointers, DI containers, registries, plugin loading and dynamic dispatch do not appear as edges. A missing edge is not proof of a missing dependency.
+- **Containers are not dependencies.** Package/rectangle nodes carry members, not arrows; they are exempt from `UML020`.
+- **The matrix is a claim too.** A matrix nobody maintains produces confident, wrong verdicts. Treat a rule change as a code change: review, version, cite.
+- **State machines are a different question.** For guards, deadlocks, budget, probability or deadlines, that is `model_verify` and `model-everything-uml` (the diagram round trip).
+
+## Rules for This Mode
+
+1. **Never read a structure diagram as a state machine.** The state-machine front end refuses such a file (`UML_NOT_A_STATE_DIAGRAM`); this skill reads it as the dependency graph it is. The two must not be mixed in one report.
+2. **Quote the rule id for every judged edge.** "Not allowed" without the rule is an opinion; `matchedRules` makes it a finding.
+3. **Run the numbers, never the impression.** An isolated node and a back edge are exactly what a reader misses by eye; that is why the check exists.
+4. **Report the diagram-code difference, not just the diagram.** A structure review that never touches the source is a review of a drawing.
+5. **Report the rule id with its meaning, never the id alone.** Rule 2 keeps the id on every judged edge, so the finding is defensible; the sentence the reader gets says what the edge violated (「HAL 反向依赖了上层」), in their language. The full rule is under "Writing the Answer" in the `model_verify` skill.
+
+The full matrix schema, a worked example and the reconciliation worksheet are in [`references/structure-review-guide.md`](references/structure-review-guide.md).

package/skills/model-everything-structure/references/structure-review-guide.md

@@ -0,0 +1,201 @@
+# Structure Review Guide
+
+How to audit a component, package, class or deployment diagram as a dependency graph: the matrix schema, every finding code, a worked example, and the method for reconciling the diagram with a source-side check.
+
+The tool is `uml_structure_verify`: it audits a component, package, class or deployment diagram as a dependency graph.
+
+## Inputs
+
+```text
+uml_structure_verify  { diagram: "<PlantUML or Mermaid class text>", notation?: auto|plantuml|mermaid, matrix?: {...} }
+```
+
+**Accepted diagram families**: PlantUML `component`, `package`, `class`, `interface`, `enum`, `object`, `actor`, `usecase`, `database`, `node`, `artifact`, `deployment`, `rectangle`, `folder`, `frame`, `cloud`, `queue`, `stack`, `storage`, `collections`, `agent`, `boundary`, `control`, `entity`, `namespace`, `module`; Mermaid `classDiagram` (`class X`, `X --> Y : label`, `X ..|> Y`).
+
+**Edge forms** (PlantUML): `-->`, `->`, `..>`, `--`, `==>`, `<--`, `<..`. Mermaid class: `-->`, `..>`, `--|>`, `..|>`, `--`, `..`.
+
+**What is read**: declarations (with `as` aliases and quoted labels), container nesting (`package "app" { … }`), arrows with labels, and note blocks (skipped — a note is not a dependency). Anything else is reported as `STRUCTURE_IGNORED_LINE` in `warnings`, never silently dropped.
+
+**Node identity**: the alias/id when one exists (`component [Order Service] as SVC` → `SVC`), otherwise the declared name. An endpoint that only ever appears in an arrow still becomes a node, marked `declared: false` — that is what `UML021` reports.
+
+## Matrix schema
+
+```jsonc
+{
+  "rules": [
+    {
+      "id": "R1",              // required, unique; this is what the report cites
+      "source": "app.*",       // node id or glob; absent = the rule judges no source
+      "allow": ["hal.*"],      // permitted targets (glob or id)
+      "deny": ["hal.secret"],  // forbidden targets; deny wins over allow, globally
+      "require": false         // true = an edge matching source→allow must exist (UML025)
+    }
+  ],
+  "layers": [
+    { "name": "app", "members": ["SVC", "PAY"] },   // top first
+    { "name": "hal", "members": ["DRV", "DB"] }
+  ],
+  "default": "allow"           // or "deny": anything unlisted is a violation
+}
+```
+
+Rules:
+
+- Glob: `*` matches any run of characters (including `.` and `:`), `?` exactly one. `app.*` matches `app.motion`, not `hal.app`.
+- **Deny is global.** Evaluation collects every rule whose `source` matches the edge, then: any deny match ⇒ violation; else any allow match ⇒ permitted; else the matrix `default` decides (`default` basis vs `unlisted` basis). The verdict cannot depend on rule order.
+- `default: "allow"` is the permissive default: rules are exceptions. `default: "deny"` is the closed-world form and is what most architecture tables actually mean.
+- Layers are independent of rules and are evaluated on every edge whose endpoints both belong to a layer: index order is top→bottom, so `app → hal` is allowed and `hal → app` is `UML024`.
+- An invalid matrix is a hard error (`MATRIX_INVALID`) and no rules apply — a typo must never silently weaken the check. Unknown keys, duplicate rule ids, non-string patterns and `require` without `allow` are all rejected.
+
+## Finding codes
+
+| Code | Severity | Evidence | How to read it |
+|---|---|---|---|
+| `UML020_ISOLATED_NODE` | warning | `nodes[{id,line}]` | Declared, non-container, degree 0. Either a dead entry or a forgotten dependency. |
+| `UML021_DANGLING_REFERENCE` | error | `nodes[{id,line}]` | An arrow endpoint no declaration introduced. The dependency targets something the diagram never defines. |
+| `UML022_CYCLE` | error | `cycle[]`, `path[]` | Shortest directed cycle, start repeated (`A → B → C → A`). A self-loop is a cycle of two elements (`A → A`). |
+| `UML023_DISALLOWED_EDGE` | error | `edge{from,to,line}`, `rule?`, `matchedRules[]`, `basis` | `basis: deny` means a rule forbade it; `basis: unlisted` means no rule allowed it under `default: deny`. |
+| `UML024_LAYER_VIOLATION` | error | `violations[{from,to,fromLayer,toLayer,line}]` | An upward edge between declared layers. |
+| `UML025_MISSING_EXPECTED_EDGE` | warning | `missing[{rule,source,expected,unsatisfiedFrom,noSourceMatch}]` | A `require: true` rule the diagram does not satisfy. `noSourceMatch` distinguishes "wrong target" from "no such source node". |
+| `UML026_NO_NODES` | error | `notation` | Nothing to review; the text is not a structure diagram. |
+| `MATRIX_INVALID` | error | — | The matrix was rejected; its messages name the exact field. |
+
+Every report also carries `summary` (nodes, edges, containers, isolated, dangling, cycles, disallowedEdges, layerViolations, missingExpectedEdges, errors, warnings, rules), `edgeVerdicts` when a matrix was supplied, and `verdict` / `verdictReason`. A structure diagram with an error finding is `verdict: "fail"` even though `ok: true` — `ok` only means the tool ran.
+
+## Worked example
+
+The diagram (a real shape: two packages, an orphan, a back edge, an undeclared endpoint):
+
+```plantuml
+@startuml
+package "app" {
+  component [Order Service] as SVC
+  component [Payment Adapter] as PAY
+}
+package "hal" {
+  component [Storage Driver] as DRV
+}
+component [Orphan Cache] as CACHE
+SVC --> PAY : plan
+PAY --> DRV : read
+DRV --> SVC : fault
+SVC --> GHOST : unknown
+@enduml
+```
+
+Without a matrix the structural checks already speak:
+
+```text
+UML021_DANGLING_REFERENCE (error)   GHOST is never declared
+UML020_ISOLATED_NODE      (warning) CACHE has no edge
+UML022_CYCLE              (error)   SVC → PAY → DRV → SVC
+verdict: fail
+```
+
+With the matrix from the skill body (`default: "deny"`, layers `app` over `hal`):
+
+```text
+UML023_DISALLOWED_EDGE (error)  DRV → SVC  basis=deny      (R3-no-back-edges)
+UML023_DISALLOWED_EDGE (error)  SVC → GHOST basis=unlisted (no rule allows it)
+UML024_LAYER_VIOLATION (error)  DRV (hal) → SVC (app)
+verdict: fail, disallowedEdges: 2, layerViolations: 1
+```
+
+Both `UML022` and `UML023` fire on the same back edge: the cycle is a graph property, the violation is a matrix property. Report both — they are different findings with different fixes (a cycle needs restructuring; a disallowed edge needs either the edge removed or the matrix amended deliberately).
+
+## Reconciliation with a source-side check
+
+The diagram and an include/dependency scan over the source are two representations of one fact, and they drift. Keep the rule ids identical on both sides, then classify each difference:
+
+| Difference | Reading | Action |
+|---|---|---|
+| Code has the include, diagram has no edge | The diagram is stale | Redraw; `require: true` makes this a `UML025` warning every run |
+| Diagram has the edge, code has no include | Either the diagram is aspirational, or the scan scope is narrower (generated files, `#ifdef`, build-time includes) | State which, with both citations |
+| Code violates a rule the diagram never showed | The architecture defect the diagram hid | Fix the code, or amend the rule deliberately and record why |
+| Both agree an edge is forbidden | A real violation, agreed by two methods | Act on it |
+
+Never present the diagram's clean verdict as evidence about the code: it is evidence about the drawing. The reconciliation is the part that touches the source.
+
+## Multi-granularity: one architecture at several levels
+
+A module-level diagram and the repository-level diagram it belongs to are two views of one
+fact, and nothing keeps them in step. Declare the relation and both are checked:
+
+```text
+uml_structure_verify  { diagrams: [ { name, diagram, parent? }, … ] }
+uml_structure_verify { diagrams: [ { name: "L1", diagram: "…", parent: "L0" }, … ] }
+```
+
+Per-diagram structural checks run first (UML020-UML026), and every finding is tagged with
+the `file` it came from, so a report over several levels never carries an anonymous
+finding. Then each declared pair is checked:
+
+| Code | Severity | What it means |
+|---|---|---|
+| `UML028_UNKNOWN_PARENT` | error | The `parent` names a diagram that is not in the set. |
+| `UML029_REFINEMENT_VIOLATION` | error | **invented-edge**: the child draws a dependency between two nodes the parent also has, but the parent does not. **unexpanded-edge**: the parent draws an edge between two nodes the child also has, the child does not draw it, and no child path connects the same ends. |
+| `UML030_PARENT_CYCLE` | error | The parent relation contains a cycle, so "which level owns this dependency" has no answer. |
+| `UML031_NO_DIAGRAMS` | error | Nothing was supplied to compare. |
+
+The rule is *refinement*, not equality: a child may add nodes and edges **below** the
+parent level (an edge with an endpoint the parent does not have is the child's own
+detail), and it may cover a **subtree** of the parent — a parent edge whose ends are not
+both present in the child is out of scope for that level, not dropped. What it may never
+do is invent a dependency at the parent level, or silently drop one it should have
+expanded.
+
+Each pair is summarised so the counts can be read without diffing two diagrams by eye:
+
+```json
+{ "parent": "L0", "child": "L1",
+  "parentNodes": 3, "childNodes": 4, "parentEdges": 2, "childEdges": 4,
+  "inheritedEdges": 1, "newEdges": 2,
+  "expandedEdges": [{ "from": "SVC", "to": "PAY", "line": 5 }],
+  "missingEdges": [], "inventedEdges": [] }
+```
+
+A parent edge the child replaces with a path is a **legitimate expansion**, and it is
+listed in `expandedEdges` rather than silently accepted: a reviewer confirms each one,
+because that is where a refactoring quietly changes who calls whom. `hashes.diagrams`
+records a sha256 per level, so a baseline diff can tell which level moved.
+
+The same discipline as the single-diagram review applies: this checks the *diagrams*
+against each other, not against the code. A level that is consistent with its parent but
+not with the code is a drawing bug; a level that disagrees with its parent is a hierarchy
+bug. Both need the source-side scan to settle.
+
+## Extracting the matrix from an existing rule table
+
+A machine-checked rule table (an include/dependency checker, a lint config, a review checklist) can seed the matrix: one rule entry per row, `id` = the row's own number so citations line up, `source`/`allow`/`deny` = the row's patterns, `layers` = the layering the table describes. Review the result before trusting it — a translation that silently widens `deny` into `allow` is worse than no check. Keep both files under version control together, and treat a matrix change as a code change.
+
+## Where each class of check comes from
+
+The distinction matters for how much weight a finding carries. A **published method** has a
+definition and a body of work behind it. A **house convention** is this plugin's own rule: the
+concern is standard, the decision procedure is ours.
+
+| Codes | Method | Provenance |
+|---|---|---|
+| `UML020_ISOLATED_NODE` | Connectivity, and the degree-0 vertices of a graph | Published, as graph theory. The reading - "a declared node with no edge is a dead entry or a forgotten dependency" - is this guide's |
+| `UML021_DANGLING_REFERENCE` | Referential closure: an edge endpoint must name a declared vertex | Published, as graph theory. In UML terms it is the notation's own well-formedness expectation that a relationship has two ends; see the UML review checklist, which separates normative constraints from tool rules |
+| `UML022_CYCLE` | Cycle detection with the shortest cycle named | Published. The algorithm is standard; the **shortest** cycle as the reported witness follows the counterexample-minimality idea the verification engine uses for A7 |
+| `UML023_DISALLOWED_EDGE` | Edge legality against a declared rule set: `deny` beats `allow`, and a `default` decides the rest | **Convention.** Conjunctive rule tables over a graph are common practice; this evaluation order is defined in `src/structure.ts` |
+| `UML024_LAYER_VIOLATION` | Layer order over a declared partition: a later band may not depend on an earlier one | **Convention**, and it checks the *declaration* rather than deriving it. `layerOf` reads `matrix.layers` and nothing else, so a design with no declared layers has no layer order to violate - which is a `skip`, not a pass |
+| `UML025_MISSING_EXPECTED_EDGE` | A declared rule with `require` whose edge the diagram does not draw | **Convention.** The idea of asserting a required dependency is standard; the `require` semantics and the `noSourceMatch` distinction are this plugin's |
+| `UML026_NO_NODES` | Input completeness: no vertex means no graph to audit | **Convention**, and deliberately an error rather than an empty pass: auditing nothing must not read as "nothing wrong" |
+| `UML028`-`UML031` | Refinement between levels: a child must not invent a parent-level dependency, and the parent relation must be a forest | **Convention.** Refinement checking has a literature (alloy/VDM refinement); the specific rules here are defined in `src/granularity.ts` |
+
+Graph theory has more to say about a dependency graph than this audit asks it. Five questions
+are computable today and deliberately not asked here: the minimum feedback arc set (NP-hard,
+Garey & Johnson 1979 - `model_design_review` decides it for small cyclic parts), community
+detection and spectral clustering (Newman & Girvan 2004; Fiedler 1973 - and unreliable at the
+size of a typical design, see `model-everything-design`), betweenness centrality (Freeman 1977),
+and deriving the layers from the graph instead of checking declared ones.
+
+## Limits
+
+- The graph is what the diagram draws. Function pointers, DI, registries, plugins and dynamic dispatch are invisible.
+- No transitive closure unless you write the rule for it.
+- Containers (`package`, `rectangle`, `frame`) are exempt from the isolated-node check by design.
+- `STRUCTURE_IGNORED_LINE` warnings mean the parser met a statement it does not model; treat a non-empty list as a signal that the diagram family may not be the one you think it is.
+- Behaviour is out of scope: state machines, protocols, timing, budget, probability and deadlines belong to `model_verify` (verification) and `model-everything-uml` (the diagram round trip).

package/skills/model-everything-uml/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: model-everything-uml
+description: "Use when drawing a UML diagram or auditing a hand-drawn one: parse it as a state, activity, timing, profile or composite structure model, render a model in a notation that can draw it, and check round-trip fidelity. A component, class, object, package or deployment diagram is read as a dependency graph by the model-everything-structure skill; an entity-relationship diagram is not a UML family and is refused, with the reason. Doctrine: the model-everything skill."
+---
+
+# Model Everything — UML Modelling
+
+A diagram is a model, and a model can be wrong. A tidy flow chart is not evidence about the code, and a diagram that disagrees with its own model is worse than no diagram, because a reader will believe it.
+
+This skill covers the diagram half of this toolbox. The claim-verification doctrine it inherits — enumerate verifiable claims, cite `file:line`, read `verdict` and never `ok` — lives in the `model-everything` skill; load that one when the task is to verify behaviour rather than to draw or audit a diagram.
+
+## When This Skill Applies
+
+| The task involves… | What it does |
+|---|---|
+| Modelling a code flow as a state, activity or sequence diagram | `uml_render`: model to diagram source, with a citation per state, event, guard and action |
+| Reading a hand-drawn diagram back into a model | `uml_parse`: Mermaid or PlantUML state/activity text into a LogicModelV1 that `model_verify` can check |
+| Auditing a diagram somebody drew | `uml_review`: structural defects, documentation gaps, and render-versus-model round-trip fidelity |
+| Printing what the parser accepts for labels and comments | `action=explain-labels`: the accepted label spellings, the form the renderer writes, and which lines are ignored |
+| A diagram whose claims must be tied to the code | Every element needs a source citation; the review says what the diagram says, not whether the code is correct |
+
+Pipeline (DSH):
+
+```text
+code flow → model (citation per element) → uml_render → diagram source
+          → uml_review → modelling findings + round-trip fidelity
+          → model_verify           → behaviour (S1-S8 structural, A1-A14 adversarial)
+```
+
+- **render** — model to diagram. Mermaid covers the state, activity, sequence and `interaction-overview` families. PlantUML covers the state, sequence, timing, profile, composite structure, communication, class, object, package, component and deployment families. Any construct the notation cannot carry becomes a warning, never a silent drop. PlantUML activity is refused instead of approximated, and a family the notation only approximates is drawn with an `UML_RENDER_APPROXIMATE_VIEW` warning that names what the picture cannot say.
+- **parse** — diagram to model. It reads Mermaid and PlantUML state or activity text, so a hand-drawn diagram can be verified like any other model. A PlantUML timing diagram is read as its own model (lifelines, states over time, messages, duration constraints), and a composite structure or communication diagram reads back exactly (nesting and port direction; lifelines, links and the numbered messages). Inputs are refused with the reason when they cannot reconstruct a model: a sequence diagram (a trace cannot reconstruct a machine), a profile (an extension and a generalization are the same arrow), an interaction overview (a flowchart node names an interaction rather than being one), an entity-relationship diagram (not a UML 2.5 family), a different Mermaid family (`classDiagram`, `erDiagram`, `gantt`, `mindmap`, …). Each comes back with its `errorCode` and, where the diagram carried constructs that were dropped, the construct named. The body carries the model it read (`MODEL`) and how it read the text (`PARSE`), and each note the parser made is a finding — a note that changed the verdict but appeared in no roster read as "nothing was reported".
+- **review** — it answers one of three questions. Give it a model: is the machine well-modelled? Give it a diagram: what does the diagram say? Give it both: does the diagram match the model?
+- **explain-labels** — the parser's own account of labels and comments: the accepted spellings, the form the renderer writes, and which lines it ignores. No diagram needed. It answers "why does my hand-drawn diagram report drift or ignored lines?" without reading the source.
+
+The view follows the question, not the machine, and no tool picks it for you. Declare the question with `intent` (`present` / `verify` / `fidelity`) and a view that cannot serve it is refused before any work, with a code that names why. The ordered procedure, the intent-by-action table and those codes are under [Choosing the view](references/uml-modeling-guide.md#choosing-the-view).
+
+A host without the tools runs the same four actions through the repository engine. The engine is deliberately single-source — do not copy it into this skill.
+
+## A Structure Diagram Is the Dangerous Case, Because It Parses
+
+PlantUML component, package, class and deployment diagrams declare no diagram kind, so the parser meets their keywords line by line. It still returns *something* — the arrows look like transitions — so `parse` reports the by-product model **plus** an error finding `UML_NOT_A_STATE_DIAGRAM`, the declarations it could not represent in `discardedConstructs` (with line and text), the arrows that were misread in `discardedEdges`, and `verdict: "fail"`.
+
+Read that as: **there is no model of this file; the diagram was not checked.** Do not feed that model to `model_verify` and call the result a review of the architecture, and do not present a component diagram as evidence about dependencies. A structure diagram has its own reviewer: the `model-everything-structure` skill and the `uml_structure_verify` tool parse the same text into a real dependency graph and check isolated nodes, dangling endpoints, cycles, allowed-dependency and layer violations (`UML020`-`UML026`). Use that one when the question is *where the dependencies point*.
+
+Mermaid families with an explicit header (`classDiagram`, `erDiagram`, `gantt`, …) are refused outright, because an empty model would be worse than no model.
+
+## What the Review Reports
+
+Structural defects: unreachable states, dead ends, ambiguous or non-exhaustive branches, self-loops with no exit, duplicate transitions. Documentation gaps: a missing narrative, unbounded variables, states the reader cannot map back to code, and label drift between diagram and narrative. It also runs the fidelity check — any structural difference between the diagram and its model is `UML017_ROUND_TRIP_MISMATCH`.
+
+## Rules for This Mode
+
+1. **A diagram is not evidence.** Every state, event, guard and action needs a citation. Use `file:line` for code and a section reference for a document. Present the citations with the diagram.
+2. **Review before you present.** Run `uml_review` and fix the error findings first. An ambiguous or dead-ended diagram misleads every later reader.
+3. **Check the verdict before the picture.** `ok: true` with `verdict: "fail"` means the review failed; a diagram whose review failed is not something to show as if it were checked.
+4. **The review never replaces verification.** It covers the modelling. S1-S8 and A1-A14 cover the behaviour, and each finding names the check that settles it — hand those over to the `model_verify` skill.
+5. **Keep the narrative with the model.** Write `narrative.states`, `narrative.events` and `narrative.scenarios`. Then the diagram stays readable against the code, and label drift shows up as a finding instead of as a stale picture.
+6. **Name a finding for the reader, not by its code.** `UML017_ROUND_TRIP_MISMATCH` is a report field; the sentence the reader gets says what disagreed (「图里少了 ERROR→COOLDOWN 这条迁移」), in their language. Keep the code for a report field quoted verbatim, a diff or a test name. The full rule is under "Writing the Answer" in the `model_verify` skill.
+
+The full checklist (codes `UML001` to `UML019` plus `UML_NOT_A_STATE_DIAGRAM`), the directive format generated diagrams carry, a worked example, and the limits of each view are in [`references/uml-modeling-guide.md`](references/uml-modeling-guide.md).