@yottameta/yotta-dev-mcp-plugin 0.1.1 → 0.2.0

package/.agents/plugins/marketplace.json

@@ -12,11 +12,11 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.1.1",
-      "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
+      "version": "0.2.0",
+      "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architecture_review, impact_analysis, verify_change, self_test, run_adapter, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
       "interface": {
         "displayName": "元开 yotta-dev-mcp",
-        "shortDescription": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, find_code, compress_ou",
+        "shortDescription": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architec",
         "developerName": "YottaMeta",
         "category": "Developer Tools"
       }

package/.claude-plugin/marketplace.json

@@ -12,11 +12,11 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.1.1",
-      "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
+      "version": "0.2.0",
+      "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architecture_review, impact_analysis, verify_change, self_test, run_adapter, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
       "interface": {
         "displayName": "元开 yotta-dev-mcp",
-        "shortDescription": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, find_code, compress_ou",
+        "shortDescription": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architec",
         "developerName": "YottaMeta",
         "category": "Developer Tools"
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-dev-mcp-plugin",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "YuanKai (yotta-dev-mcp) Agent Plugin: deterministic local development tools over stdio MCP.",
   "license": "MIT",
   "repository": {

package/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "yotta-dev-mcp",
-  "version": "0.1.1",
-  "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
+  "version": "0.2.0",
+  "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architecture_review, impact_analysis, verify_change, self_test, run_adapter, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
   "author": {
     "name": "YottaMeta",
     "url": "https://github.com/YottaMeta"

package/skills/yotta-dev-mcp/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-dev-mcp
-description: 元开（yotta-dev-mcp）—— 本地、确定性的开发工具 MCP，把只读默认的开发能力暴露为 stdio MCP server：repo_map / find_code / compress_output / review_code / review_diff / mcp_doctor / scan_secrets / scan_dependencies / check_publish_readiness / run_checks / scaffold_skill / workflow_state。触发：让 AI 在陌生项目里先做结构盘点、定位代码、评审改动、扫描密钥/依赖、检查发布就绪、运行白名单检查、生成脚手架或读取 .workflow 状态时；或用户说 元开 / 开发能力 MCP / yotta-dev-mcp / 代码库地图 / 代码评审 MCP 等。边界：Python 3.8+ 标准库、离线默认；除 run_checks（显式 allow_execute）与 scaffold_skill / workflow_state 的显式 apply 外均为只读；不上传源码、不自动修改、不提交、不联网查询包是否存在。
-version: 0.1.1
+description: 元开（yotta-dev-mcp）—— 本地、确定性的开发工具 MCP，把只读默认的开发能力暴露为 stdio MCP server：repo_map / system_model / architecture_review / impact_analysis / verify_change / self_test / run_adapter / find_code / compress_output / review_code / review_diff / mcp_doctor / scan_secrets / scan_dependencies / check_publish_readiness / run_checks / scaffold_skill / workflow_state。触发：让 AI 在陌生项目里先做结构盘点、构建系统模型或架构契约（.yotta/architecture.json）、按契约评审架构、分析改动影响锥与回归面、按验证阶梯产出证据账本、对元开自身做完整性 / 反证自测、探测或显式运行 import-linter / dependency-cruiser / Repomix 可选适配器、定位代码、评审改动、扫描密钥/依赖、检查发布就绪、运行白名单检查、生成脚手架或读取 .workflow 状态时；或用户说 元开 / 开发能力 MCP / yotta-dev-mcp / 代码库地图 / 系统模型 / 架构契约 / 架构评审 / 影响分析 / 验证账本 / 反证自测 / 代码评审 MCP / 适配器 等。边界：Python 3.8+ 标准库、离线默认；除 run_checks（显式 allow_execute）、verify_change 的 L2-L4 策略检查（显式 allow_execute）与 self_test 的测试子集（显式 allow_execute）、run_adapter 的 action=run（显式 allow_execute）、scaffold_skill / workflow_state 的显式 apply 外均为只读；不上传源码、不自动修改、不提交、不联网查询包是否存在、不自动安装或下载适配器。
+version: 0.2.0
 license: MIT
 ---
 
@@ -13,6 +13,12 @@ license: MIT
 ## 何时使用
 
 - 接手陌生项目：先 `repo_map` 看模块、依赖和入口，再 `find_code` 定位。
+- 架构与影响分析：先写 `.yotta/architecture.json`，再用 `system_model` 拿分层、依赖、测试映射与 `UNKNOWN` 清单。
+- 契约评审：用 `architecture_review` 查依赖规则、边界可见性与数据归属，每条给证据与严重级。
+- 改动前评估：用 `impact_analysis` 从改动文件 / diff / 目标符号走出影响锥、映射测试与回滚探针。
+- 改动后验证：用 `verify_change` 跑 L0 / L1 默认检查，按需结合 `.yotta/verification.json` 与 `allow_execute=true` 执行 L2-L4 白名单检查，产出可复算账本。
+- 自身完整性：用 `self_test` 检查文件、版本、工具契约、写闸门与 seeded defect / mutation 反证。
+- 可选增强：用 `run_adapter` 先 `action=list` 探测 import-linter / dependency-cruiser / Repomix，再按需 `action=run` + `allow_execute=true`；缺工具或配置返回 UNKNOWN，不自动安装、不自动下载。
 - 评审改动：`review_diff` 只看新增行；`review_code` 对文件或仓库做规则检查。
 - 长日志 / 长命令输出：`compress_output` 保错误、错误栈和首尾上下文。
 - 本机排查：`mcp_doctor` 只读检查技能目录和 MCP JSON 配置。
@@ -40,6 +46,12 @@ python scripts/yotta_dev_mcp.py
 | 工具 | 用途 | 写入 |
 |---|---|---|
 | `repo_map` | 模块、导入、入口点地图 | 否 |
+| `system_model` | 系统模型：模块、依赖、入口、测试映射、配置与数据归属；附带契约分层，输出 PASS / FAIL / UNKNOWN | 否 |
+| `architecture_review` | 按契约评审依赖规则、边界可见性与数据归属；critical / high 判 FAIL，medium / low 只告警 | 否 |
+| `impact_analysis` | 变更影响锥：直接消费者、受影响层 / 边界 / 存储 / 不变量、映射测试、风险分级与回滚探针 | 否 |
+| `verify_change` | L0-L5 验证阶梯与证据账本：L0 / L1 默认，L2-L4 需策略声明 + 显式执行，L5 始终留在未验证项 | 仅显式 allow_execute 的 L2-L4 |
+| `self_test` | 文件 / 版本 / 工具契约 / 写闸门 / seeded defect 与 mutation 反证自测 | 仅显式 allow_execute 的测试子集 |
+| `run_adapter` | 探测或显式运行 import-linter / dependency-cruiser / Repomix；固定 argv、项目内 cwd、有界输出与哈希 | 仅 action=run + 显式 allow_execute |
 | `find_code` | 符号 / 文本定位，结果有上限 | 否 |
 | `compress_output` | 保留错误与首尾的长输出压缩 | 否 |
 | `review_code` | 规则化代码评审，带行号与建议 | 否 |
@@ -52,16 +64,18 @@ python scripts/yotta_dev_mcp.py
 | `scaffold_skill` | 生成最小技能脚手架，默认 dry-run | 仅显式 apply |
 | `workflow_state` | 读取 `.workflow`，可选显式追加日志 | 仅显式 apply |
 
-详细契约见 `references/tools.md`。
+详细契约见 `references/tools.md`；架构契约、评审语义与影响锥字段见 `references/architecture-contract.md`。
 
 ## 边界
 
-- `run_checks` 是唯一会执行项目代码的工具，默认关闭，必须显式 `allow_execute=true`；只运行白名单检查。
-- `scaffold_skill` / `workflow_state` 默认只预览，显式 `apply=true` 才写入；写入前做原子替换并保留 `.bak`。
+- 会执行项目代码的工具默认关闭：`run_checks`、`verify_change` 的 L2-L4 策略检查、`self_test` 的测试子集都必须显式 `allow_execute=true`，且只运行白名单检查或已声明的策略检查。
+- 外部适配器只在用户已安装时接入：`run_adapter` 不安装、不下载、不访问远端、不接收任意命令参数；工具缺失或配置缺失一律返回 `UNKNOWN` 并给出 next_step。
+- `scaffold_skill` / `workflow_state` 默认只预览，显式 `apply=true` 才写入；脚手架拒绝覆盖已有非空目录，状态写入使用原子替换并为被覆盖文件保留 `.bak`。
 - 不联网，不查询包是否存在于公共仓库。
 - 不读取或修改 YottaCode 仓库。
 - 结论是确定性静态判断，不替代人工评审与最终决策。
 
 ## 当前版本
 
+- v0.2.0（2026-09-25）：新增 `system_model`、`architecture_review`、`impact_analysis`、`verify_change`、`self_test`、`run_adapter`，以及 `.yotta/architecture.json` 与可选 `.yotta/verification.json` 契约（版本 1）；工具总数 18，原 12 个工具行为不变。
 - v0.1.1：品牌显示名统一为「元开」；功能与 12 个工具不变。

package/skills/yotta-dev-mcp/references/adapters.md

@@ -0,0 +1,69 @@
+# Optional external adapters
+
+`run_adapter` probes and explicitly runs mature third-party tools that the user
+already installed. The core engine stays Python-standard-library-only; adapters
+are optional evidence sources, never a required dependency.
+
+## Adapter matrix
+
+| Adapter | License | What it adds | Required config |
+|---|---|---|---|
+| `import-linter` | BSD-2-Clause | Python import boundaries and layered contracts | `.importlinter`, `setup.cfg`, `tox.ini` or `pyproject.toml` |
+| `dependency-cruiser` | MIT | JavaScript / TypeScript dependency rules | `.dependency-cruiser.js` / `.cjs` / `.mjs` / `.json` |
+| `repomix` | MIT | Repository packing and context budget enforcement | optional `repomix.config.json` |
+
+## Commands
+
+`action=list` only inspects the project-local `node_modules/.bin`, project
+virtualenv directories and `PATH`. It does not execute anything. Each adapter
+entry reports `available`, `ready`, `executable`, `executable_source`, `config`
+and a reason when it is not ready.
+
+`action=run` requires `allow_execute=true` and exactly one adapter. The command
+arguments are fixed by the adapter implementation:
+
+```text
+lint-imports --config <detected-config>
+depcruise --config <detected-config> --output-type json --progress none --exclude node_modules <target>
+repomix --stdout --style xml --quiet --no-git-sort-by-changes [--token-budget N] <target>
+```
+
+No adapter accepts arbitrary arguments, shell strings, remote repositories or
+package installation. Repomix never receives `--remote` or
+`--no-security-check`.
+
+## Output
+
+The run result contains:
+
+- `status`: `PASS`, `FAIL` or `UNKNOWN`;
+- `adapter`: detected executable, source, config and version;
+- `command`: fixed argv, relative cwd, exit code, timeout flag and output hash;
+- `findings`: normalized adapter violations with rule, severity, path and target;
+- `content`: Repomix-only packed text metadata and bounded text;
+- `next_step`: what to install, configure or rerun when the result is not PASS.
+
+Missing tools, missing required config, invalid JSON output, timeouts and
+non-whitelisted execution all degrade to `UNKNOWN`. Adapter findings are
+reported separately; they do not silently change the status of
+`system_model`, `architecture_review`, `impact_analysis` or `verify_change`.
+
+## Safety boundary
+
+Adapters are local-only and deterministic under the same repository state:
+
+- executable discovery is limited to the project `node_modules/.bin`, project
+  virtualenvs and `PATH`;
+- execution uses a fixed argv with `shell=False`;
+- the working directory and target must stay inside the repository;
+- output is bounded, hashed and never contains wall-clock timestamps;
+- no package is installed, downloaded or updated by this tool.
+
+## Command line
+
+```bash
+python scripts/dev_engine.py adapter . --action list
+python scripts/dev_engine.py adapter . --action run --adapter import-linter --allow-execute
+python scripts/dev_engine.py adapter . --action run --adapter dependency-cruiser --allow-execute
+python scripts/dev_engine.py adapter . --action run --adapter repomix --allow-execute --token-budget 50000
+```

package/skills/yotta-dev-mcp/references/architecture-contract.md

@@ -0,0 +1,256 @@
+# Architecture contract and system model
+
+`system_model` builds a deterministic model of a local repository and attaches
+layer data from an optional architecture contract. Everything runs offline with
+the Python standard library; no file is written.
+
+## Contract file
+
+Path: `.yotta/architecture.json`. Plain JSON, version `1`.
+
+```json
+{
+  "version": 1,
+  "project": "demo",
+  "layers": [
+    {"id": "core", "title": "Core", "paths": ["src/core/**"], "risk": "high"},
+    {"id": "api", "paths": ["src/api/**"]},
+    {"id": "ui", "paths": ["src/ui/**"]}
+  ],
+  "rules": [
+    {
+      "id": "core-no-ui",
+      "type": "forbid-dependency",
+      "from": "core",
+      "to": "ui",
+      "severity": "high",
+      "claim": "core must not import ui"
+    }
+  ],
+  "boundaries": [
+    {"id": "public-api", "layer": "api", "paths": ["src/api/public/**"], "visibility": "public"}
+  ],
+  "data_ownership": [
+    {"store": "memory-db", "owner": "core", "paths": ["var/memory/**"], "kind": "sqlite"}
+  ],
+  "invariants": [
+    {"id": "no-plaintext-secrets", "claim": "secrets are never stored in plaintext",
+     "severity": "high", "check": "static"}
+  ],
+  "risk_weights": {"core": 3, "api": 2, "ui": 1}
+}
+```
+
+### Fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `version` | yes | Must be `1`. |
+| `project` | no | Free-form name. |
+| `layers` | yes | Layer id, optional title/description, `paths` globs, optional `risk`. |
+| `rules` | no | `forbid-dependency` (`to` is one layer) or `allow-dependency` (`to` is a layer list). `from`, `to`, `severity` and `claim` describe the invariant. |
+| `boundaries` | no | Layer id plus globs; `visibility` is `public`, `internal` or `private`. |
+| `data_ownership` | no | Store id, owning layer, globs and optional `kind`. |
+| `invariants` | no | id plus a non-empty `claim`; `check` is `static`, `command` or `manual`. |
+| `risk_weights` | no | Layer id to a number between 0 and 5. |
+
+Ids match `[a-z0-9][a-z0-9._-]{0,63}`. Paths are repository-relative POSIX
+globs and must not be absolute or contain `..`.
+
+### Glob rules
+
+`*` stays inside one path segment, `**` crosses segments, `?` matches one
+character, and a trailing `/` means the whole directory (`pkg/` equals
+`pkg/**`). Matching is case-sensitive. Layers are evaluated in declaration
+order and the first match wins; a module that matches several layers is
+reported as `layer-overlap`.
+
+### Validation findings
+
+Every finding carries `code`, `severity`, `message`, a JSON `pointer`, the
+contract `path` and short `evidence`. Severity `critical` or `high` makes the
+contract `FAIL`; `medium` and `low` are advisory.
+
+| Code | Meaning |
+|---|---|
+| `contract-invalid-json` | The file is not valid JSON. |
+| `contract-not-object` | The root value is not a JSON object. |
+| `contract-unsupported-version` | `version` is missing or not `1`. |
+| `contract-invalid-layer` / `contract-duplicate-layer` | Layer shape or ids are wrong. |
+| `contract-layer-without-paths` | A layer declares no globs. |
+| `contract-invalid-path` | A glob is absolute, escapes the root, or is empty. |
+| `contract-invalid-rule` / `contract-duplicate-rule` | Rule shape, type or ids are wrong. |
+| `contract-invalid-severity` / `contract-invalid-risk` | Enum values are outside the allowed set. |
+| `contract-unknown-layer-ref` | A rule, boundary, store or risk weight points at a missing layer. |
+| `contract-invalid-boundary` / `contract-invalid-store` / `contract-invalid-invariant` | Section entries are malformed. |
+| `contract-unknown-key` | Unknown top-level key; reported as a warning and ignored. |
+
+## system_model output
+
+| Key | Content |
+|---|---|
+| `status` | `PASS`, `FAIL` (contract has blocking findings) or `UNKNOWN` (something still needs evidence). |
+| `contract` | Path, presence, validity, version, layer and rule ids, findings. |
+| `model.modules` | Repository-relative module id, language, line count and resolved layer. |
+| `model.layers` | Declared layers with the modules that match them. |
+| `model.imports` | `source`, `target`, `kind`, `line` and the raw specifier. |
+| `model.entrypoints` | Files that look like executable entrypoints. |
+| `model.tests` | Test files and the internal modules they import. |
+| `model.configs` | Configuration files with a coarse kind. |
+| `model.data_stores` | Declared stores (with owner and owner modules) and detected local database files. |
+| `unknowns` | `contract-missing`, `contract-invalid`, `unassigned-module`, `layer-overlap`, `unresolved-import`. |
+| `unverified_claims` | Verification levels that were not executed, with the reason. |
+| `evidence` | Bounded, sorted evidence lines for the findings above. |
+| `truncated` | True when the file limit cut the scan short. |
+| `model_digest` | `sha256:` digest of the model, stable across runs on the same tree. |
+
+Import kinds: `internal` (another source module), `internal-file` (a
+repository file that is not source, such as `package.json`), `external`
+(outside the repository) and `unresolved` (a relative path that does not
+exist; also listed under `unknowns`).
+
+`system_model` never asserts that a change is safe. Levels `L1` and above stay
+listed in `unverified_claims` until a dedicated check runs them.
+
+## architecture_review
+
+`architecture_review` evaluates the same contract against the same system model and
+returns every finding with file, line and severity. Per-item status is `PASS`,
+`WARN` (advisory findings only), `FAIL` or `UNKNOWN`.
+
+| Code | Meaning | Severity |
+|---|---|---|
+| `rule-forbid-dependency` | a module in the rule's `from` layer imports the forbidden `to` layer | the rule's severity |
+| `rule-allow-dependency` | a module in the rule's `from` layer imports a layer outside `to` | the rule's severity |
+| `boundary-visibility` | a module imports a protected boundary it may not reach | `high` for `private`, `medium` for `internal` |
+| `data-ownership-mismatch` | a module inside the store paths is not in the owner layer | `medium` |
+| `data-store-access-outside-owner` | a module outside the owner layer references the store path | `medium` |
+
+Boundary visibility decides who may import the protected modules:
+
+- `public` - any layer may import them; the declaration is recorded and never a finding.
+- `internal` - only modules of the same layer may import them.
+- `private` - only modules inside the boundary globs may import them.
+
+Data ownership is checked in two ways: modules that live inside a store's paths but
+belong to another layer, and modules outside the owner layer that reference the
+store path literal (the part before the first wildcard).
+
+Invariants are never reported as passing. `static`, `command` and `manual` checks
+all land in `unverified_claims` with the reason, so a review can be `PASS` while
+still stating what it did not verify.
+
+The overall status is `FAIL` when the contract has blocking findings or any
+violation reaches `critical` / `high`; `UNKNOWN` when the contract is missing or
+anything stays undecided; otherwise `PASS` (advisory findings may still be listed).
+
+### Unknown kinds
+
+| Kind | Meaning |
+|---|---|
+| `contract-missing` / `contract-invalid` | no usable contract was found. |
+| `model-truncated` | the file limit cut the scan short. |
+| `unassigned-module` / `layer-overlap` | a module has no layer or matches several. |
+| `unresolved-import` | a relative import does not resolve. |
+| `rule-target-unassigned` | the rule's source layer matches, but the target module has no layer. |
+| `boundary-no-modules` | the boundary globs match no module. |
+| `boundary-importer-unassigned` | the importer has no layer, so visibility is undecided. |
+
+## impact_analysis
+
+`impact_analysis` starts from changed files, a unified diff or target symbols and
+walks reverse dependencies (internal imports and repository-file imports) into a
+bounded cone. Each node carries `depth`, `via`, `line`, `layer` and `is_test`.
+
+Alongside the cone it reports direct consumers, affected layers, boundaries, data
+stores, invariants scoped to the changed paths, tests mapped to the cone, the
+architecture violations that fall inside the cone, rollback probes and an
+explainable blast radius.
+
+| Blast radius factor | Weight | When |
+|---|---|---|
+| `layer-risk` | 0-5 | highest declared risk weight or risk level of affected layers |
+| `layer-count` | +1 / +2 | 3-4 layers / 5 or more layers are affected |
+| `cone-depth` | +1 | the consumer chain reaches depth 2 or more |
+| `public-boundary` | +1 | a public boundary is inside the cone |
+| `data-store` | +1 per store, capped at 2 | declared or detected stores are touched |
+| `architecture-violation` | +2 / +3 | a `high` / `critical` violation is inside the cone |
+
+`level` maps the capped score (10 max): 9-10 `critical`, 6-8 `high`, 3-5 `medium`,
+otherwise `low`. `score` is the raw sum of the weights and `reasons` lists every
+factor with its detail, so the number can be recomputed by hand.
+
+Rollback probes are derived, not invented: `data-store` (affected stores),
+`entrypoint` (non-test entrypoints in the cone, capped at 5), `tests` (mapped test
+files), `invariant` (declared `command` checks) and `model` (fallback when the cone
+has no anchor). Test files that only guard on `__main__` are covered by the test
+probe and are not reported as startup entrypoints.
+
+## verification policy
+
+`.yotta/verification.json` is optional. It declares the L2-L4 checks that
+`verify_change` may execute, plus manual work that must stay unverified. It never
+holds shell strings: `kind` must be one of the whitelisted runners already supported
+by `run_checks`.
+
+```json
+{
+  "version": 1,
+  "checks": [
+    {
+      "id": "unit-tests",
+      "level": "L2",
+      "kind": "python-unittest",
+      "cwd": ".",
+      "timeout": 120,
+      "required": true,
+      "claim": "the unit suite passes"
+    }
+  ],
+  "manual": [
+    {"id": "independent-review", "claim": "a second person reviews the change"}
+  ]
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `version` | yes | Must be `1`. |
+| `checks` | no | Array of L2-L4 checks. |
+| `checks[].id` | yes | Unique slug matching the same id rule as the architecture contract. |
+| `checks[].level` | yes | `L2`, `L3` or `L4`. |
+| `checks[].kind` | yes | `python-unittest`, `pytest`, `python-compile`, `npm-test` or `npm-lint`. |
+| `checks[].cwd` | no | Repository-relative directory, default `.`; absolute paths and `..` are rejected. |
+| `checks[].timeout` | no | 1-600 seconds, default 120. |
+| `checks[].required` | no | Default `true`; a required check that did not run keeps the overall result `UNKNOWN`. |
+| `checks[].claim` | no | Human-readable claim recorded in the ledger. |
+| `manual[].id` / `manual[].claim` | yes | Manual claims that are always reported as unverified. |
+
+Verification findings use the same evidence shape as the architecture contract:
+`code`, `severity`, `message`, JSON `pointer`, `path` and short `evidence`.
+Blocking codes include `verification-invalid-json`,
+`verification-unsupported-version`, `verification-invalid-id`,
+`verification-duplicate-check`, `verification-invalid-level`,
+`verification-invalid-kind`, `verification-invalid-cwd`,
+`verification-invalid-timeout` and `verification-invalid-manual`.
+
+`verify_change` runs L0/L1 in-process. L2-L4 execute only when the caller passes
+`allow_execute=true`; L5 is always manual. A `PASS` means every required claim has
+evidence. Unrun or manual claims remain in `unverified_claims` and are never written
+as passing.
+
+## Command line
+
+```bash
+python scripts/dev_engine.py system-model .
+python scripts/dev_engine.py system-model . --contract config/architecture.json
+python scripts/dev_engine.py architecture-review .
+python scripts/dev_engine.py impact-analysis . --changed src/core/store.py
+python scripts/dev_engine.py impact-analysis . --diff-file change.patch --depth 2
+python scripts/dev_engine.py impact-analysis . --symbol save
+python scripts/dev_engine.py verify-change . --changed src/core/store.py
+python scripts/dev_engine.py verify-change . --changed src/core/store.py --level L2 --allow-execute
+python scripts/dev_engine.py self-test .
+python scripts/dev_engine.py adapter . --action list
+python scripts/dev_engine.py adapter . --action run --adapter import-linter --allow-execute
+```

package/skills/yotta-dev-mcp/references/tools.md

@@ -1,6 +1,9 @@
 # Tool contracts
 
-All tools are local, deterministic and read-only in v0.1.0.
+All tools are local and deterministic. Unless a section says otherwise they are
+read-only; `run_checks`, `verify_change` and `run_adapter` require
+`allow_execute=true` for their explicit execution paths, and `scaffold_skill` /
+`workflow_state` require `apply=true` before writing.
 
 ## repo_map
 
@@ -11,6 +14,149 @@ Input:
 
 Output: `root`, `modules`, `imports`, `entrypoints`, `truncated`.
 
+## system_model
+
+Input:
+
+- `path` (required): repository or source directory.
+- `max_files` (optional, default 2000): source file limit.
+- `contract_file` (optional): contract path relative to the repository root
+  (default `.yotta/architecture.json`).
+
+Output: `status` (`PASS` / `FAIL` / `UNKNOWN`), `contract`, `model` (`modules`,
+`layers`, `imports`, `entrypoints`, `tests`, `configs`, `data_stores`),
+`unknowns`, `unknowns_truncated`, `unverified_claims`, `evidence`, `truncated`
+and `model_digest`.
+
+Contract schema, glob rules, finding codes and import kinds are documented in
+`references/architecture-contract.md`.
+
+## architecture_review
+
+Input:
+
+- `path` (required): repository or source directory.
+- `max_files` (optional, default 2000): source file limit.
+- `contract_file` (optional): contract path relative to the repository root
+  (default `.yotta/architecture.json`).
+
+Output: `status` (`PASS` / `FAIL` / `UNKNOWN`), `contract`, `checked`
+(`rules` / `boundaries` / `data_stores` / `invariants`, each with a per-item
+`status` of `PASS` / `WARN` / `FAIL` / `UNKNOWN`), `violations`, `blocking_findings`,
+`advisory_findings`, `unknowns`, `unverified_claims`, `evidence`, `truncated` and
+`model_digest`.
+
+`critical` / `high` findings fail the review; `medium` / `low` stay advisory.
+Anything the model cannot decide becomes `UNKNOWN`; declared invariants that this
+tool cannot evaluate are listed in `unverified_claims` instead of being reported
+as passing. Read-only.
+
+## impact_analysis
+
+Input:
+
+- `path` (required): repository or source directory.
+- `changed_files` (optional): repository-relative changed files.
+- `diff` (optional): unified diff text; changed files and line numbers are parsed
+  from it, deleted files keep their declared layer.
+- `symbols` (optional): target symbols; their definition sites become the change.
+- `depth` (optional, default 3, 1-10): reverse-dependency depth.
+- `max_files` (optional, default 2000): source file limit.
+- `contract_file` (optional): contract path relative to the repository root.
+
+At least one of `changed_files`, `diff` or `symbols` is required.
+
+Output: `status`, `inputs`, `changed`, `direct_consumers`, `cone` (`nodes` with
+`depth` / `via` / `layer` / `is_test`, `max_depth`, `limit`, `truncated`),
+`affected_layers`, `affected_boundaries`, `affected_data_stores`,
+`affected_invariants`, `relevant_tests`, `architecture` (`status`,
+`violations_total`, `violations_in_scope`, `unknowns`), `blast_radius`
+(`level`, `score`, `capped`, `reasons`), `rollback_probes`, `unknowns`,
+`unverified_claims`, `evidence`, `truncated` and `model_digest`.
+
+`status` is `FAIL` when a blocking architecture violation sits inside the cone,
+`UNKNOWN` while anything is undecided, otherwise `PASS`. Read-only; no command is
+executed.
+
+## verify_change
+
+Input:
+
+- `path` (required): repository or source directory.
+- `changed_files` / `diff` / `symbols` (at least one): the same change inputs as
+  `impact_analysis`.
+- `depth` (optional, default 3, 1-10): reverse-dependency depth.
+- `levels` (optional): additional execution levels `L2`, `L3`, `L4` or manual `L5`.
+  L0 and L1 always run.
+- `allow_execute` (optional, default false): required before any L2-L4 check runs.
+- `timeout` (optional, default 120, 1-600): upper bound for each policy check.
+- `max_files` / `contract_file` (optional): model limit and contract override.
+- `policy_file` (optional, default `.yotta/verification.json`): policy override.
+
+Output: `status`, `inputs`, `required_levels`, `ledger`, `unverified_claims`,
+`policy`, `evidence`, `ledger_digest`, `model_digest` and `impact_status`.
+
+Every ledger entry has `id`, `level`, `claim`, `status` (`PASS` / `FAIL` / `UNKNOWN` /
+`UNVERIFIED`), `severity`, `check`, `confidence`, `evidence`, `next_step` and
+`command`. Static checks keep `command` as `null`; executed checks record the
+whitelisted kind, relative cwd, exit code, timeout flag and `output_hash`.
+
+The default ladder runs L0 (changed-file syntax, contract schema) and L1 (architecture
+rules and boundaries inside the change cone). L2-L4 are skipped unless both a policy
+check is declared and `allow_execute=true`; they never accept arbitrary commands.
+L5 is always manual and stays in `unverified_claims`. The ledger intentionally has no
+wall-clock timestamp: its digest and the command output hashes are the reproducible
+evidence anchors.
+
+## self_test
+
+Input:
+
+- `path` (required): source checkout or installed skill directory.
+- `mode` (optional, default `auto`): `auto`, `source` or `installed`.
+- `allow_execute` (optional, default false): run the target test suite.
+- `timeout` (optional, default 120, 1-600).
+
+Source mode checks required files, version alignment across `package.json` /
+`SKILL.md` / `CHANGELOG.md` / `server.json` / engine `VERSION`, protocol tool names
+and `inputSchema.additionalProperties=false`, fail-closed defaults for every write or
+execute gate, and counterexamples. Installed mode checks `SKILL.md` and the installed
+asset payload, and records source-only checks as out of scope.
+
+The counterexample suite is in-process and deterministic: a seeded forbidden
+dependency must be `FAIL`, removing the rule must stop the failure, an invalid
+contract must be `FAIL` or `UNKNOWN`, a missing contract must be `UNKNOWN`, a seeded
+credential must be found, and a seeded version mismatch must fail readiness. These
+probes prove the verifier is not a rubber stamp.
+
+## run_adapter
+
+Input:
+
+- `action` (required): `list` probes optional adapters without executing them;
+  `run` executes exactly one adapter.
+- `path` (required): repository root.
+- `adapter` (required when `action=run`): `import-linter`,
+  `dependency-cruiser` or `repomix`.
+- `allow_execute` (optional, default false): required for `action=run`.
+- `timeout` (optional, default 120, 1-600).
+- `max_chars` (optional, default 120000, 1000-1000000): Repomix output cap.
+- `token_budget` (optional): Repomix token budget; over-budget output fails.
+- `target` (optional, default `.`): repository-relative adapter target.
+
+`action=list` returns `status`, `adapters` with `available` / `ready` /
+`executable` / `executable_source` / `config` / `reason`, plus `unknowns`.
+
+`action=run` returns `status` (`PASS` / `FAIL` / `UNKNOWN`), the selected
+`adapter` metadata, a fixed `command` record with `output_hash`, normalized
+`findings`, Repomix `content` metadata when applicable, `next_step` and
+`unknowns`. Missing tools, missing configs, invalid output and timeouts are
+`UNKNOWN`, never silent passes.
+
+Adapters are optional enhancements: no package is installed or downloaded, no
+arbitrary argv is accepted, and adapter findings do not silently change the
+status of the core architecture tools. See `references/adapters.md`.
+
 ## find_code
 
 Input: