@yottameta/yotta-dev-mcp 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v0.2.0 (2026-09-25)
+
+- 新增 `system_model`：模块、依赖、入口、测试映射、配置与数据归属的确定性系统模型，
+  附带 `.yotta/architecture.json` 契约分层。
+- 新增 `architecture_review`：按契约评审依赖规则、边界可见性与数据归属，
+  每条产出 file / line / severity 证据；critical / high 判 FAIL，medium / low 只告警，
+  无法判定的部分进 UNKNOWN，声明的不变量一律进 `unverified_claims`。
+- 新增 `impact_analysis`：从 changed_files / unified diff / 目标符号生成变更影响锥，
+  含直接消费者、受影响层与边界、数据存储、不变量、映射测试、可解释风险分级与回滚探针。
+- 新增 `verify_change`：L0-L5 验证阶梯与确定性证据账本；L0 / L1 默认运行，
+  L2-L4 必须同时有 `.yotta/verification.json` 白名单声明与 `allow_execute=true`，
+  L5 人工复核始终留在 `unverified_claims`；账本以 output hash 与 ledger digest 复算。
+- 新增 `self_test`：检查必需文件、版本五件、协议工具 schema / engine dispatch 漂移、
+  写入与执行闸门是否 fail-closed，并用 seeded defect 与 mutation control 反证验证器会红。
+- 新增 `run_adapter`：探测或显式运行项目已安装的 import-linter /
+  dependency-cruiser / Repomix；固定 argv、项目内 cwd、有界输出与 hash，
+  缺工具 / 缺配置 / 超时 / 非法输出一律返回 UNKNOWN，且不自动安装、不下载、不访问远端。
+- 新增架构契约（版本 1）：分层、依赖规则、边界、数据归属、不变量、风险权重；
+  校验输出 code / severity / JSON pointer / evidence。
+- 新增可选验证策略（版本 1）：只允许白名单 runner、仓库内相对 cwd 与显式执行；
+  拒绝任意命令、绝对路径与越界 cwd。
+- 结论只给 `PASS` / `FAIL` / `UNKNOWN`；缺证据项写入 `unknowns`，未执行的验证级别
+  写入 `unverified_claims`；模型带稳定 `model_digest`。
+- 引擎按共享层拆分：`dev_common` / `dev_model` / `dev_architecture` /
+  `dev_impact` / `dev_verify` / `dev_selftest` / `dev_adapters`；`dev_engine`
+  保留原公开函数与 dispatch 作为稳定门面。
+- 原 12 个工具行为不变；新增的六个工具离线、零依赖（适配器只在用户已安装时调用），默认只读。
+
 ## v0.1.1 (2026-09-25)
 
 - 品牌改名：对外显示名统一为「元开（yotta-dev-mcp）」，不再把功能描述「开发能力 MCP」当产品名。

package/README.md

@@ -9,6 +9,12 @@ Deterministic local development tools exposed over a stdio MCP server.
 | Tool | Purpose |
 |---|---|
 | `repo_map` | Map modules, imports and entrypoints in a repository. |
+| `system_model` | Build a system model with layer data from the architecture contract. |
+| `architecture_review` | Review dependency rules, boundaries and data ownership with evidence. |
+| `impact_analysis` | Build the change impact cone with tests, blast radius and rollback probes. |
+| `verify_change` | Run the L0-L5 verification ladder and return an evidence ledger. |
+| `self_test` | Check files, versions, tool contracts, write gates and seeded-defect counterexamples. |
+| `run_adapter` | Probe or explicitly run optional import-linter / dependency-cruiser / Repomix adapters. |
 | `find_code` | Locate symbols and text with bounded results. |
 | `compress_output` | Compress long logs while keeping errors and head/tail context. |
 | `review_code` | Apply deterministic review rules with file, line and evidence. |
@@ -21,9 +27,48 @@ Deterministic local development tools exposed over a stdio MCP server.
 | `scaffold_skill` | Plan or create a minimal skill scaffold; dry-run by default. |
 | `workflow_state` | Read `.workflow` and optionally append an explicit log entry. |
 
-The first nine tools are read-only; `run_checks` requires `allow_execute=true`, and
-`scaffold_skill` / `workflow_state` require `apply=true` before writing. Python 3.8+
-standard library is sufficient; no network access is required.
+Tools are read-only by default; `run_checks`, the L2-L4 policy checks in
+`verify_change`, the test subset in `self_test`, and `run_adapter` with
+`action=run` require `allow_execute=true`. `scaffold_skill` / `workflow_state`
+require `apply=true` before writing. Python 3.8+ standard library is sufficient;
+no network access is required.
+
+### Architecture contract
+
+`system_model` reads an optional `.yotta/architecture.json` (version 1) that declares
+layers, dependency rules, boundaries, data ownership, invariants and risk weights. The
+result reports `PASS`, `FAIL` or `UNKNOWN`, lists every unknown that still needs
+evidence, and keeps verification levels that were not executed in `unverified_claims`.
+`architecture_review` then checks that contract: dependency rules, boundary visibility
+and data ownership each produce findings with file, line and severity. `critical` and
+`high` findings fail the review, `medium` and `low` stay advisory, and anything that
+cannot be decided from the model becomes `UNKNOWN` instead of a silent pass.
+
+`impact_analysis` starts from `changed_files`, a unified diff or target symbols and
+walks reverse dependencies into a bounded cone: direct consumers, affected layers,
+boundaries, data stores, invariants, mapped tests, an explainable blast radius and
+rollback probes. It executes nothing.
+
+`verify_change` runs the post-change ladder: L0 syntax and contract schema, L1
+architecture checks inside the impact cone, L2-L4 whitelisted checks declared in
+`.yotta/verification.json` with explicit `allow_execute=true`, and L5 independent
+review kept as unverified work. Ledger entries carry a claim, status, evidence,
+check name and output hash so the result can be recomputed; skipped levels are never
+written as passing.
+
+`self_test` checks the integrity of yotta-dev-mcp itself: required files, version
+alignment across package / SKILL / CHANGELOG / server / engine, protocol tool schema
+drift, fail-closed write gates, and seeded-defect plus mutation controls that prove
+the verifier turns red or unknown. The test suite is not executed by default.
+
+`run_adapter` is an optional enhancement layer. `action=list` only probes the
+project-local `node_modules/.bin`, project virtualenvs and `PATH`; `action=run`
+requires `allow_execute=true` and runs one fixed adapter command. Missing tools,
+missing config, invalid output and timeouts return `UNKNOWN` with a next step.
+No package is installed or downloaded, and adapter results do not silently change
+the status of the core architecture tools. Details: `references/adapters.md`.
+
+Schema, glob rules, finding codes and cone fields: `references/architecture-contract.md`.
 
 ## Install
 
@@ -60,6 +105,14 @@ The engine can also be used without MCP:
 
 ```bash
 python scripts/dev_engine.py repo-map .
+python scripts/dev_engine.py system-model .
+python scripts/dev_engine.py architecture-review .
+python scripts/dev_engine.py impact-analysis . --changed src/core/store.py
+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 dependency-cruiser --allow-execute
 python scripts/dev_engine.py find-code . "helper"
 python scripts/dev_engine.py review-code .
 python scripts/dev_engine.py mcp-doctor
@@ -73,4 +126,7 @@ python scripts/dev_engine.py mcp-doctor
 
 ## Current version
 
-`0.1.0` ships the protocol core and twelve deterministic tools.
+`0.2.0` (2026-09-25) adds `system_model`, `architecture_review`,
+`impact_analysis`, `verify_change`, `self_test`, `run_adapter`, and the
+`.yotta/architecture.json` plus optional `.yotta/verification.json` contracts on
+top of the twelve deterministic tools.

package/README.zh-CN.md

@@ -9,6 +9,12 @@
 | 工具 | 用途 |
 |---|---|
 | `repo_map` | 代码库模块、导入关系与入口点地图。 |
+| `system_model` | 系统模型：模块、依赖、入口、测试映射、配置与数据归属，附带契约分层。 |
+| `architecture_review` | 按契约评审依赖规则、边界可见性与数据归属，逐条给出证据。 |
+| `impact_analysis` | 变更影响锥：消费者、受影响层与存储、映射测试、风险分级与回滚探针。 |
+| `verify_change` | L0-L5 验证阶梯与证据账本；未执行级别保留在 `unverified_claims`。 |
+| `self_test` | 文件、版本、工具契约、写闸门与 seeded defect / mutation 反证自测。 |
+| `run_adapter` | 探测或显式运行 import-linter / dependency-cruiser / Repomix 可选适配器。 |
 | `find_code` | 符号与文本定位，结果有数量上限。 |
 | `compress_output` | 压缩长日志，保留错误、错误栈和首尾上下文。 |
 | `review_code` | 规则化代码评审，输出文件、行号、证据与建议。 |
@@ -21,8 +27,40 @@
 | `scaffold_skill` | 规划或生成最小技能脚手架，默认 dry-run。 |
 | `workflow_state` | 读取 `.workflow`，可选显式追加快照日志。 |
 
-前九个工具只读；`run_checks` 必须显式 `allow_execute=true`，`scaffold_skill` /
-`workflow_state` 必须显式 `apply=true` 才写入。核心只用 Python 3.8+ 标准库，默认不联网。
+默认只读；`run_checks`、`verify_change` 的 L2-L4 策略检查、`self_test` 的测试子集，
+以及 `run_adapter` 的 `action=run` 必须显式 `allow_execute=true`，
+`scaffold_skill` / `workflow_state` 必须显式 `apply=true` 才写入。
+核心只用 Python 3.8+ 标准库，默认不联网。
+
+### 架构契约
+
+`system_model` 读取可选的 `.yotta/architecture.json`（版本 1），其中声明分层、依赖规则、
+边界、数据归属、不变量与风险权重。结果只给 `PASS` / `FAIL` / `UNKNOWN`，把还缺证据的
+未知项列进 `unknowns`，未执行的验证级别保留在 `unverified_claims`。schema、glob 规则与
+错误码见 `references/architecture-contract.md`。
+
+`architecture_review` 在这份契约上做评审：依赖规则、边界可见性与数据归属逐条产出
+文件、行号与严重级；`critical` / `high` 判 FAIL，`medium` / `low` 只告警，
+模型无法判定的部分进 `UNKNOWN`，不会被静默放行。
+
+`impact_analysis` 从 `changed_files`、unified diff 或目标符号出发，沿反向依赖走出一棵
+有上限的影响锥：直接消费者、受影响层与边界、数据存储、不变量、映射测试、
+可解释的风险分级与回滚探针；全程不执行任何命令。
+
+`verify_change` 在改动后跑同一份模型：L0 检查语法与契约 schema，L1 检查影响锥内架构规则，
+L2-L4 只执行 `.yotta/verification.json` 中声明的白名单检查且必须显式 `allow_execute=true`，
+L5 独立复核始终保留在未验证项。账本中的每个结论都带 claim、status、evidence、check 与
+output hash，便于复算；未跑级别不会被写成“已通过”。
+
+`self_test` 对元开自身做完整性检查：必需文件、版本五件、协议工具 schema 与引擎
+dispatch 是否漂移、写 / 执行闸门是否仍 fail-closed，并用临时仓库里的 seeded defect
+与 mutation control 证明验证器会变红或变 UNKNOWN。测试子集默认不跑。
+
+`run_adapter` 是可选增强层：`action=list` 只探测项目 `node_modules/.bin`、
+项目虚拟环境和 `PATH`；`action=run` 必须显式 `allow_execute=true`，且只运行固定
+适配器命令。缺工具、缺配置、非法输出或超时都返回 `UNKNOWN` 并给出下一步；
+不安装、不下载，适配器结果也不会悄悄改写核心架构工具的状态。详见
+`references/adapters.md`。
 
 ## 安装
 
@@ -55,6 +93,14 @@ bash <技能目录>/yotta-dev-mcp/install.sh --agent codex
 
 ```bash
 python scripts/dev_engine.py repo-map .
+python scripts/dev_engine.py system-model .
+python scripts/dev_engine.py architecture-review .
+python scripts/dev_engine.py impact-analysis . --changed src/core/store.py
+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 dependency-cruiser --allow-execute
 python scripts/dev_engine.py find-code . "helper"
 python scripts/dev_engine.py review-code .
 python scripts/dev_engine.py mcp-doctor
@@ -68,4 +114,7 @@ python scripts/dev_engine.py mcp-doctor
 
 ## 当前版本
 
-`0.1.0` 提供协议内核与十二个确定性工具。
+`0.2.0`（2026-09-25）在原有十二个确定性工具之上新增 `system_model`、
+`architecture_review`、`impact_analysis`、`verify_change`、`self_test`、
+`run_adapter`，以及 `.yotta/architecture.json` 与可选
+`.yotta/verification.json` 契约（版本 1）。

package/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/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@yottameta/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.",
   "license": "MIT",
   "keywords": [
     "agent-skills",
     "yottaskills",
     "mcp",
     "developer-tools",
-    "code-review"
+    "code-review",
+    "verification"
   ],
   "files": [
     "SKILL.md",
@@ -40,7 +41,7 @@
     "yotta-dev-mcp-install": "bin/install.js"
   },
   "scripts": {
-    "test": "python scripts/test_dev_engine.py && python scripts/test_yotta_dev_mcp.py"
+    "test": "python scripts/test_dev_contract.py && python scripts/test_dev_adapters.py && python scripts/test_dev_engine.py && python scripts/test_yotta_dev_mcp.py"
   },
   "engines": {
     "node": ">=18"

package/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/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
+```