dsh-model-everything 0.2.0 → 0.4.0

package/lib/structure.js

@@ -444,8 +444,9 @@ function requireDiagramText(value) {
 export function reviewStructure(options) {
     // Not `if (options.diagram !== undefined)`: a missing `diagram` reached the parser as `undefined`
     // and threw a read of `split` on it - the same defect, one guard narrower.
-    requireDiagramText(options.diagram);
-    const graph = parseStructure(options.diagram, options.notation ?? 'auto');
+    // A graph built from source arrives already parsed; a caller that passes one has no diagram text to
+    // require, so the text guard belongs to the other branch.
+    const graph = options.graph ?? parseStructure(requireDiagramText(options.diagram), options.notation ?? 'auto');
     const warnings = [...graph.warnings];
     const findings = [];
     const nodes = graph.nodes;
@@ -657,6 +658,25 @@ export function reviewStructure(options) {
             evidence: { missing },
         });
     }
+    // Degree is what a reader asks first and counts worst: which module everything depends on, and which
+    // depends on nothing. Counting it here means the answer is one line in the report rather than a scan of
+    // the graph by hand, which is where a correct graph still produced a wrong answer.
+    const inDegree = new Map();
+    const outDegree = new Map();
+    for (const edge of graph.edges) {
+        inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+        outDegree.set(edge.from, (outDegree.get(edge.from) ?? 0) + 1);
+    }
+    const hubs = [...inDegree.entries()]
+        .filter(([, count]) => count > 0)
+        .sort((a, b) => (b[1] === a[1] ? a[0].localeCompare(b[0]) : b[1] - a[1]))
+        .slice(0, 5)
+        .map(([id, dependents]) => ({ id, dependents }));
+    const leaves = nodes
+        .filter((node) => !node.container && (outDegree.get(node.id) ?? 0) === 0)
+        .map((node) => node.id)
+        .sort()
+        .slice(0, 10);
     const errors = findings.filter((finding) => finding.severity === 'error').length;
     const warningCount = findings.filter((finding) => finding.severity === 'warning').length;
     const summary = {
@@ -672,6 +692,8 @@ export function reviewStructure(options) {
         errors,
         warnings: warningCount,
         rules: rules.length,
+        hubs,
+        leaves,
     };
     const nextSteps = [];
     if (errors > 0)
@@ -689,10 +711,13 @@ export function reviewStructure(options) {
         notation: graph.notation,
         graph,
         ...(options.matrix === undefined ? {} : { edgeVerdicts }),
+        ...(options.scan === undefined ? {} : { scan: options.scan }),
         findings,
         summary,
         hashes: {
-            diagram: createHash('sha256').update(options.diagram).digest('hex'),
+            // A graph built from source has no diagram text to hash; hashing the text would hash the empty
+            // string, and every scan would then carry the same input hash.
+            diagram: createHash('sha256').update(options.graph === undefined ? options.diagram : canonicalJson({ nodes: options.graph.nodes.map((node) => node.id), edges: options.graph.edges.map((edge) => ({ from: edge.from, to: edge.to })) })).digest('hex'),
             ...(options.matrix === undefined ? {} : { matrix: createHash('sha256').update(canonicalJson(options.matrix)).digest('hex') }),
         },
         warnings,

package/lib/tool.js

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { runVerification } from './engine.js';
 import { renderReportText } from './report-view.js';
+import { reportCallView, reportCard, reportResultView } from './presentation.js';
 import { OptionShapeError, optionRefusal, requireObjectOption } from './option-shape.js';
 import { oneOf } from './model-file.js';
 export const MODEL_VERIFY_TOOL_NAME = 'model_verify';
@@ -59,7 +60,13 @@ export const modelVerifyTool = defineTool({
         render(args, value) {
             return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full', check: args.check }) }];
         },
+        // The card a UI shows, separated from the text the model reads.
+        presentationMeta(args, value) {
+            return reportCard(value, MODEL_VERIFY_TOOL_NAME);
+        },
     },
+    presentCall: reportCallView(MODEL_VERIFY_TOOL_NAME),
+    presentResult: reportResultView(MODEL_VERIFY_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {

package/lib/types/automaton-tool.d.ts

@@ -0,0 +1,2 @@
+export declare const MODEL_AUTOMATON_TOOL_NAME = "model_automaton_verify";
+export declare const modelAutomatonTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/automaton.d.ts

@@ -0,0 +1,57 @@
+export interface AutomatonTransition {
+    from: string;
+    symbol: string;
+    to: string;
+}
+export interface Automaton {
+    states: string[];
+    alphabet: string[];
+    transitions: AutomatonTransition[];
+    init: string;
+    accepting: string[];
+}
+export interface AutomatonFinding {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    detail?: string;
+}
+/** Validate the shape, so a refusal says which field is wrong rather than throwing later. */
+export declare function validateAutomaton(input: unknown): {
+    ok: true;
+    automaton: Automaton;
+} | {
+    ok: false;
+    errors: string[];
+};
+export type AutomatonRelation = 'equivalent' | 'subset' | 'superset';
+export interface AutomatonReport {
+    ok: boolean;
+    ran: boolean;
+    verdict: 'pass' | 'pass_with_findings' | 'fail';
+    verdictReason: string;
+    schema: string;
+    automaton: {
+        states: number;
+        transitions: number;
+        alphabet: number;
+        deterministic: boolean;
+    };
+    findings: AutomatonFinding[];
+    /** Set when the relation fails: the shortest word that breaks it. */
+    witness?: {
+        word: string[];
+        reason: string;
+    };
+    /** True when the product search stopped before deciding, so `pass` is not a proof of equality. */
+    truncated?: boolean;
+    hashes: {
+        automaton: string;
+        other?: string;
+    };
+    nextSteps: string[];
+}
+export declare function verifyAutomaton(input: unknown, options?: {
+    other?: unknown;
+    relation?: AutomatonRelation;
+}): AutomatonReport;

package/lib/types/edit-tool.d.ts

@@ -0,0 +1,2 @@
+export declare const MODEL_EDIT_TOOL_NAME = "model_edit";
+export declare const modelEditTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/editor.d.ts

@@ -0,0 +1,46 @@
+type Json = Record<string, unknown>;
+export interface EditOperation {
+    op: string;
+    [key: string]: unknown;
+}
+export interface ModelChange {
+    kind: 'added' | 'removed' | 'updated';
+    what: string;
+    detail: string;
+}
+/** Read the model at `path`; a missing file is a refusal, not an empty model. */
+export declare function readModelFile(path: unknown): {
+    model: Json;
+    full: string;
+};
+/**
+ * Accept the compact spelling of an operation as well as the long one.
+ *
+ * An operation is a small thing - add a state, wire a transition - and the long form spends more
+ * tokens on key names than on the change. Five operations cost 76 tokens spelled out and 39 in the
+ * compact form, and a batch of twenty is where that difference starts to matter.
+ *
+ *   {addState: "c"}                    {addState: {id: "c", terminal: true}}
+ *   {removeState: "c"}
+ *   {addTransition: ["a", "reset", "c"]}     {addTransition: {from, event, to, guard?, ...}}
+ *   {removeTransition: ["a", "go"]}          {updateTransition: ["a", "go", {guard: ...}]}
+ *   {set: ["/init", "a"]}                    {remove: "/init"}
+ *
+ * The long form is unchanged and is what the errors talk about.
+ */
+export declare function normalizeOperation(raw: unknown): EditOperation;
+/** Apply one operation to a model copy, returning the changes it made. */
+export declare function applyOperation(model: Json, operation: EditOperation): ModelChange[];
+/** Validate the edited model and write it atomically. A refused edit leaves the file untouched. */
+export interface EditOutcome {
+    model: Json;
+    changes: ModelChange[];
+    full: string;
+    /** Whether the model as written validates. False only when the caller allowed it. */
+    valid: boolean;
+    errors: string[];
+}
+export declare function applyEdits(path: unknown, operations: unknown, options?: {
+    allowInvalid?: boolean;
+}): EditOutcome;
+export {};

package/lib/types/engine.d.ts

@@ -314,6 +314,7 @@ export declare const REPORT_SCHEMAS: {
     readonly granularity: 'model-everything/granularity/v1';
     readonly design: 'model-everything/design/v1';
     readonly baseline: 'model-everything/baseline/v1';
+    readonly edit: 'model-everything/edit/v1';
 };
 export type ReportSchema = typeof REPORT_SCHEMAS[keyof typeof REPORT_SCHEMAS];
 /**

package/lib/types/presentation.d.ts

@@ -0,0 +1,164 @@
+/**
+ * What a UI shows for a report, separated from what the model reads.
+ *
+ * A report is written for a model: it names every check, every finding and the next step, because the
+ * model has to act on all of it. A reader wants four things instead - did it run, what does it decide,
+ * what is the first thing wrong, what to do next - and wants the rest folded away.
+ *
+ * Two host hooks carry that split:
+ *
+ * - `output.presentationMeta` projects a small JSON payload the host persists on the result; a client
+ *   card narrows it without parsing prose.
+ * - `presentResult` returns the card body from that payload, so a UI that supports it shows the summary
+ *   and a UI that does not falls back to the raw text. The model-facing content never changes.
+ *
+ * Both are pure and replayable: they read the persisted value, never the filesystem.
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools';
+/** One finding, as a card needs it: a code to name it and a sentence to read. */
+export interface CardFinding {
+    code: string;
+    severity: string;
+    message: string;
+}
+/** The payload a client card narrows. Small on purpose: a card is a summary, not a second report. */
+export interface ReportCard {
+    verdict?: string;
+    verdictReason?: string;
+    errors: number;
+    warnings: number;
+    checksRun?: number;
+    first: CardFinding | null;
+    /** The one step a reader should take, already a sentence. */
+    next: string | null;
+    /** Which family produced this, so a card can pick an icon and a colour without parsing codes. */
+    family: string;
+    /** What this family owns, and where the case just outside it goes. One table, not a second prose copy. */
+    route?: {
+        owns: string;
+        instead: string;
+    };
+    /** `model_edit`: the changes this call applied, as the report lists them. */
+    changes?: Array<{
+        kind: string;
+        what: string;
+        detail?: string;
+    }>;
+    /** `model_edit` and `report_diff`: how the findings moved, when either report could compare. */
+    delta?: {
+        added: number;
+        removed: number;
+        changed: number;
+        addedErrors: number;
+    };
+    /** `report_diff`: the first finding the change adds, so a card can lead with it. */
+    firstAdded?: CardFinding;
+    /** `report_diff`: the current report's own verdict, which differs from the delta's when a clean change lands on a failing report. */
+    currentVerdict?: string;
+    /** The artifact a translation or a rendering produced, as the first lines of it. */
+    source?: {
+        label: string;
+        lines: string[];
+        total: number;
+    };
+    /** `uml_structure_verify`: the graph's own counts, which are measurements rather than findings. */
+    graph?: {
+        nodes: number;
+        edges: number;
+        cycles: number;
+        isolated: number;
+        dangling: number;
+    };
+    /** `model_design_review`: three levels, because a signal is not a violation and a fact is neither. */
+    levels?: {
+        violations: number;
+        signals: number;
+        facts: number;
+        skipped: number;
+    };
+    /** `model_interleaving_scan`: how many claims were found, and in which families. */
+    claims?: {
+        absolute: number;
+        keywords: number;
+        families: Array<{
+            family: string;
+            count: number;
+        }>;
+    };
+}
+/**
+ * Project a report into the card payload.
+ *
+ * Read defensively: this runs on replay too, and a payload that once had a shape may come back with a
+ * field missing. A card that throws would take the whole session view with it.
+ */
+export declare function reportCard(value: unknown, family: string): ReportCard;
+/** The card body: four lines, in the order a reader asks the questions. */
+export declare function cardBlocks(card: ReportCard): ContentBlock[];
+/**
+ * The pending card for a report tool: a title naming the artifact, and the file to follow.
+ *
+ * From the arguments only, because a UI calls this during streaming and again on replay; the file has not
+ * been opened at that point and must not be.
+ */
+/**
+ * The card payload with the artifact previewed.
+ *
+ * A translation and a rendering both produce text a reader wants to see the shape of, and neither should
+ * paste the whole file into a card: the preview is bounded, and it says how much it left out. The report
+ * keeps the artifact in full for whoever needs it.
+ */
+export declare function cardWithSource(value: unknown, family: string, text: string | undefined, label: string, limit?: number): ReportCard;
+export declare function reportCallView(family: string): (args: unknown) => ToolCallView | undefined;
+/**
+ * The card for `model_edit`: what changed, and what the change did to the findings.
+ *
+ * Both lists are already in the report, so this is a rendering of the same value rather than a second
+ * computation - the rule every card here follows.
+ */
+export declare function editCardBlocks(card: ReportCard): ContentBlock[];
+/**
+ * The card for `report_diff`: does this change add anything, read as counts and the first added error.
+ *
+ * A diff's `verdict` is about the delta, so the card leads with the delta and never with the current
+ * report's own verdict - the two differ exactly when a clean change lands on an already-failing report.
+ */
+export declare function diffCardBlocks(card: ReportCard): ContentBlock[];
+/** `presentResult` for `model_edit`, falling back to the generic card when the payload has no changes. */
+export declare function editResultView(family: string): (_args: unknown, result: {
+    content: ContentBlock[];
+    meta?: unknown;
+}) => ToolResultView | undefined;
+export declare function reportResultView(family: string): (_args: unknown, result: {
+    content: ContentBlock[];
+    meta?: unknown;
+}) => ToolResultView | undefined;
+/** The card for `uml_structure_verify`: the graph's shape first, then the first finding. */
+export declare function structureCardBlocks(card: ReportCard): ContentBlock[];
+/** The card for `model_design_review`: violations, then signals, then facts - never one number. */
+export declare function designCardBlocks(card: ReportCard): ContentBlock[];
+/** The card for `model_interleaving_scan`: claims by family, and the reminder that nothing was proven. */
+export declare function scanCardBlocks(card: ReportCard): ContentBlock[];
+/** One `presentResult` per card body, since the shapes differ but the fallback does not. */
+export declare function familyResultView(family: string, body: (card: ReportCard) => ContentBlock[]): (_args: unknown, result: {
+    content: ContentBlock[];
+    meta?: unknown;
+}) => ToolResultView | undefined;
+export declare const structureResultView: (_args: unknown, result: {
+    content: ContentBlock[];
+    meta?: unknown;
+}) => ToolResultView | undefined;
+export declare const designResultView: (_args: unknown, result: {
+    content: ContentBlock[];
+    meta?: unknown;
+}) => ToolResultView | undefined;
+export declare const scanResultView: (_args: unknown, result: {
+    content: ContentBlock[];
+    meta?: unknown;
+}) => ToolResultView | undefined;
+/** `presentResult` for `report_diff`: the delta leads, never the current report's own verdict. */
+export declare function diffResultView(family: string): (_args: unknown, result: {
+    content: ContentBlock[];
+    meta?: unknown;
+}) => ToolResultView | undefined;

package/lib/types/routing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which tool owns which question, in one table.
+ *
+ * Two consumers read this, and they used to read two different things: the result a model gets
+ * (`nextSteps` naming a sibling) and the toolset map a human reads (hand-written prose). That is how the
+ * map came to say "about ten thousand characters" while the descriptions measured twenty-nine: a fact
+ * stated twice drifts, and nothing fails when it does.
+ *
+ * So the table states the routing once. `routeFor` hands it to the card a UI draws; the toolset map
+ * generator reads the same table and refuses to write a map for a tool that is missing from it.
+ *
+ * What it is not: a decision. The tool a request should use is chosen by the model from the descriptions.
+ * This table says what each tool owns and which neighbour takes the case just outside that line, so a
+ * report can redirect without a reader having to remember the roster.
+ */
+export interface Route {
+    /** What this tool decides, in the words its report already uses. */
+    owns: string;
+    /** The case just outside the line, and the tool that owns it. */
+    notFor: {
+        when: string;
+        tool: string;
+    };
+}
+export declare const ROUTES: Record<string, Route>;
+/** The route for a tool, or undefined when the tool has none. */
+export declare function routeFor(tool: string): Route | undefined;
+/** Every tool a route names, for a caller that has to check the table against the registry. */
+export declare function routedTools(): string[];
+/** The tools named as the owner of an adjacent case. */
+export declare function siblingTools(): string[];

package/lib/types/scan.d.ts

@@ -0,0 +1,37 @@
+export interface ScannedEdge {
+    from: string;
+    to: string;
+}
+export interface ScannedGraph {
+    /** Module ids, posix-style and relative to the scanned root. File ids for file languages, directory ids for package languages. */
+    nodes: string[];
+    edges: ScannedEdge[];
+    /** Files read, and files skipped because they are not source. */
+    filesRead: number;
+    /** Relative specifiers that pointed outside the root or at a file that does not exist. */
+    unresolved: string[];
+    /** Bare specifiers seen (a package name), counted once each. */
+    packages: string[];
+    /** Which languages were scanned, and at what granularity. */
+    languages: {
+        language: string;
+        files: number;
+        granularity: 'file' | 'package';
+    }[];
+}
+export type LangGranularity = 'file' | 'package';
+export interface Language {
+    name: string;
+    extensions: string[];
+    granularity: LangGranularity;
+    /** Specifiers this file names, already separated from external ones. */
+    extract(text: string): {
+        local: string[];
+        external: string[];
+    };
+}
+/** Every language this scan understands, by extension. */
+export declare const LANGUAGES: Language[];
+/** Which language a file belongs to, if any. */
+export declare function languageOf(path: string): Language | undefined;
+export declare function scanDependencyGraph(root: unknown): ScannedGraph;

package/lib/types/structure.d.ts

@@ -95,6 +95,13 @@ export interface StructureSummary {
     errors: number;
     warnings: number;
     rules: number;
+    /** The most depended-on nodes, by incoming edges. What a reader asks first and counts worst. */
+    hubs: {
+        id: string;
+        dependents: number;
+    }[];
+    /** Modules nothing depends on (no outgoing edges), capped for the report. */
+    leaves: string[];
 }
 export interface StructureReport {
     /** The tool ran and produced this report; read `verdict` for the outcome. */
@@ -142,6 +149,15 @@ export declare function shortestCycle(nodes: string[], edges: StructureEdge[]):
 export interface StructureReviewOptions {
     /** Diagram text to review. */
     diagram: string;
+    /** A graph built from source, instead of parsed from a diagram. `diagram` is then ignored. */
+    graph?: StructureGraph;
+    /** How the graph was produced, when it came from a scan rather than a drawing. */
+    scan?: {
+        files: number;
+        unresolved: number;
+        packages: number;
+        languages: string[];
+    };
     notation?: 'auto' | StructureNotation;
     /** Dependency matrix: allowed/denied edges, layers, required edges. */
     matrix?: unknown;

package/lib/uml-tool.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, valueHash, refusalVerdict, verdictOf, verdictOfFindings } from './engine.js';
 import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, checkUmlIntent, UmlError, UML_DIAGRAMS, } from './uml.js';
 import { renderReportText } from './report-view.js';
+import { cardWithSource, reportCallView, reportCard, reportResultView } from './presentation.js';
 /**
  * The UML front end as four tools, one per job.
  *
@@ -41,13 +42,19 @@ const intentParameter = {
     enum: ['present', 'verify', 'fidelity'],
     description: 'What the artifact is for, declared up front: present = a human will read it; verify = it must be readable as a model by the verification engine; fidelity = the render-and-reparse proof is the point. A view that cannot serve the declared intent is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes.',
 };
-const reportOutput = {
+const reportOutput = (family) => ({
     schema: { type: 'json', description: 'The result: diagram source, a family model, or a modelling review report with findings, round-trip fidelity and next steps.' },
     render(args, value) {
         // A rendered diagram is source text: the body prints it verbatim, once.
         return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
     },
-};
+    // The card a UI shows, separated from the text the model reads. The family is the tool's own name, so
+    // one shared output does not have to guess which tool is calling it.
+    presentationMeta(_args, value) {
+        const report = value;
+        return cardWithSource(value, family, typeof report.diagram === 'string' ? report.diagram : undefined, 'diagram source');
+    },
+});
 /** Draw a model as diagram source. */
 export const umlRenderTool = defineTool({
     name: UML_RENDER_TOOL_NAME,
@@ -60,7 +67,9 @@ export const umlRenderTool = defineTool({
         intent: intentParameter,
         reportView: reportViewParameter,
     },
-    output: reportOutput,
+    output: reportOutput(UML_RENDER_TOOL_NAME),
+    presentCall: reportCallView(UML_RENDER_TOOL_NAME),
+    presentResult: reportResultView(UML_RENDER_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {
@@ -97,7 +106,9 @@ export const umlParseTool = defineTool({
         intent: intentParameter,
         reportView: reportViewParameter,
     },
-    output: reportOutput,
+    output: reportOutput(UML_PARSE_TOOL_NAME),
+    presentCall: reportCallView(UML_PARSE_TOOL_NAME),
+    presentResult: reportResultView(UML_PARSE_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {
@@ -148,7 +159,9 @@ export const umlReviewTool = defineTool({
         intent: intentParameter,
         reportView: reportViewParameter,
     },
-    output: reportOutput,
+    output: reportOutput(UML_REVIEW_TOOL_NAME),
+    presentCall: reportCallView(UML_REVIEW_TOOL_NAME),
+    presentResult: reportResultView(UML_REVIEW_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {
@@ -179,7 +192,9 @@ export const umlExplainLabelsTool = defineTool({
         notation: notationParameter,
         reportView: reportViewParameter,
     },
-    output: reportOutput,
+    output: reportOutput(UML_LABELS_TOOL_NAME),
+    presentCall: reportCallView(UML_LABELS_TOOL_NAME),
+    presentResult: reportResultView(UML_LABELS_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-model-everything",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Modeling abstraction and automated review for designs and code, including a refactoring harness: UML diagrams, executable verification of machines and protocols with before/after regression, data-model and migration checks, concurrency claim routing, export to external checkers, dependency-graph review, and report diffing. Native plugin for DeepSeek Harness (dsh).",
   "type": "module",
   "main": "lib/index.js",
@@ -64,8 +64,11 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint:md": "markdownlint --dot --ignore \"**/node_modules/**\" .",
     "bump": "node scripts/bump-version.mjs",
-    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/design-engine/run.mjs && node tests/catalog/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/uml/run.mjs && node tests/apply-smoke.mjs && node tests/memory/run.mjs && node tests/skills/run.mjs && node tests/gate/run.mjs && node tests/skill-routing/run.mjs && node tests/toolset/run.mjs && node tests/principles/run.mjs && node tests/feature-checklist/run.mjs && node tests/usage/run.mjs && node tests/translation/run.mjs && node tests/documentation/run.mjs && node tests/contributing/run.mjs && node tests/routing-map/run.mjs && node tests/report-reading/run.mjs && node tests/structure/run.mjs && node tests/baseline/run.mjs && node tests/granularity/run.mjs && node tests/exporters/run.mjs && node tests/report-view/run.mjs && node tests/contracts/run.mjs && node tests/tool-boundary/run.mjs && node tests/negatives/run.mjs && node tests/external/run.mjs",
-    "test:full": "npm run build && node tests/full-suite.mjs"
+    "test:cards": "node tests/presentation/run.mjs && node tests/automaton/run.mjs && node tests/routing/run.mjs",
+    "coverage": "c8 --reporter=text --exclude-after-remap=false npm run test:engine",
+    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/design-engine/run.mjs && node tests/catalog/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/uml/run.mjs && node tests/apply-smoke.mjs && node tests/memory/run.mjs && node tests/skills/run.mjs && node tests/gate/run.mjs && node tests/skill-routing/run.mjs && node tests/toolset/run.mjs && node tests/principles/run.mjs && node tests/feature-checklist/run.mjs && node tests/usage/run.mjs && node tests/translation/run.mjs && node tests/documentation/run.mjs && node tests/contributing/run.mjs && node tests/routing-map/run.mjs && node tests/report-reading/run.mjs && node tests/structure/run.mjs && node tests/automaton/run.mjs && node tests/presentation/run.mjs && node tests/routing/run.mjs && node tests/tool-routing/run.mjs && node tests/tools/run.mjs && node tests/baseline/run.mjs && node tests/granularity/run.mjs && node tests/exporters/run.mjs && node tests/report-view/run.mjs && node tests/contracts/run.mjs && node tests/tool-boundary/run.mjs && node tests/negatives/run.mjs && node tests/external/run.mjs",
+    "test:full": "npm run build && node tests/full-suite.mjs",
+    "check": "npm run lint:md && npm run test:engine"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",

package/skills/model-everything/SKILL.md

@@ -9,7 +9,11 @@ For an unverified design, failure is only a matter of time. Complex code becomes
 
 ## When This Skill Applies
 
-**This is the entry point.** Load this skill whenever you need to check whether something about the code is true, however small the claim looks. It owns the doctrine: enumerate the claims, verify each against the code, cite `file:line`, read `verdict`. It also owns the executable verification for behaviour. A neighbouring domain goes to its own skill through the routing table below.
+**This is the entry point.** Load this skill when a claim about the code has to be settled and a reading will not settle it. It owns the doctrine: enumerate the claims, verify each against the code, cite `file:line`, read `verdict`. It also owns the executable verification for behaviour. A neighbouring domain goes to its own skill through the routing table below.
+
+**It decides small models, not programs.** The engine enumerates states, so a model that explodes is reported `truncated` with the undecided check named. That is not a bug to retry with a larger `maxStates`: reduce the model first (drop variables the property does not read, collapse symmetric states), and if it still explodes the property needs a tool that does not enumerate - SPIN for partial-order reduction, NuSMV for symbolic search, CBMC for bounded SAT. This plugin builds no abstraction and reads no program source.
+
+**This costs more than reading, and less the larger the task.** On a fixture of a few hundred lines it costs several times a plain reading, because the fixed cost has nothing to amortise against. On a tree of tens of thousands of lines the ratio falls to roughly parity. Spend it where the object is large enough for one decision to replace many reads. Reach for it when the claim is about all paths rather than one, when nothing in the repository will go red if it is false, or when the verdict has to be reproducible later. A claim one reading settles belongs in a sentence, not in a model.
 
 | The task involves… | What it does |
 |---|---|
@@ -180,7 +184,7 @@ not a bound on the search.
 
 ### Native dsh Tools
 
-Twelve tools: `model_verify`, `model_compose_verify`, `model_datamodel_verify`, `model_design_review`, `model_interleaving_scan`, `model_export`, `report_diff`, `uml_render`, `uml_parse`, `uml_review`, `uml_explain_labels`, `uml_structure_verify`. Each tool's description states what it decides and what it does not. Read the description before calling it, and read the report's `verdict` afterwards.
+The tools are `model_verify`, `model_edit`, `model_compose_verify`, `model_datamodel_verify`, `model_design_review`, `model_interleaving_scan`, `model_export`, `report_diff`, `uml_render`, `uml_parse`, `uml_review`, `uml_explain_labels`, `uml_structure_verify` and `model_automaton_verify`. `model_automaton_verify` decides a finite-word language and its relation to another automaton, returning the shortest word that separates them; `references/automata.md` states what each of its checks decides, on what authority, and where it stops. `model_edit` changes a model file by naming the change and returns the structural diff plus the difference in findings, so a fix round costs one call instead of three. `uml_structure_verify` builds its graph from a source tree when given `repoPath`, reading each language's own import construct, so a dependency question about code does not start with drawing. Each tool's description states what it decides and what it does not. Read the description before calling it, and read the report's `verdict` afterwards.
 
 A model is the largest argument these tools take. When it is long, or you have edited it more than once, write it to a file and pass `modelPath` instead of inlining it: a streamed argument that long is where invalid JSON comes from, and the file accepts any formatting.