@yottameta/yotta-dev-mcp 0.1.1 → 0.2.0

package/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: