io.github.pedroknigge/arkgate

Scan the project for architecture findings (layer-import violations, forbidden globals, cycles, config warnings). Returns pass/fail/incomplete plus evidence — not a yes/no architecture score. Same engine as arkgate-check. Applies the baseline when one exists. isError when the scan fails. Prefer after ark_identity.

Report what each layer actually governs: per-layer file counts, the FULL list of unclassified (ungoverned) files, layers whose patterns match nothing, and layers with no rule edge. Use this to audit config coverage instead of hand-rolling find/readdir. Report only — never an error.

First call. Prove this MCP process is the right project: pass project.expectedRoot (exact absolute root) and reuse the returned projectId. Do this before any other Ark tool. A missing/unmatched root or processPackage.processStale means restart/retarget the host and use the project-local CLI until identity and package versions align.

Return the machine-readable architecture contract with an authoritative project binding when project.expectedRoot matches this MCP project. Prefer this tool over the ark://manifest compatibility resource, whose standard MCP read shape cannot carry a portable project expectation.

Place a file in the architecture: filePath is required (fail-closed without it — never invents components/*.tsx or defaults to Presentation). Returns layer, mayImport / mustNotImport, forbiddenGlobals, and goldenPattern (load-bearing for NEW code when .ark/golden-pattern.json exists — adopt generates it). When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. When the matched layer has layers[].trustBoundary (public|auth|admin|internal), the JSON includes trustBoundary; omitted when absent. When the matched layer has layers[].owners, the JSON includes owners; omitted when absent. Call BEFORE writing a new file to learn the layer. Prefer ark_prepare_write only as fallback when the host has no hard pre-hook (or that hook is missing / fail-open) and you already have the source snippet.

Classify a complete ark.config.json transition as strengthening, neutral, judgment-required, or weakening. Pass the previous baseConfig and optional candidateConfig (defaults to this project contract). Weakening and judgment-required results set isError unless acknowledgement exactly matches both policy hashes and all blocking finding ids, and adrPath names a short note under docs/adr/ or docs/decisions/. Read-only; never edits the contract.

Validate one complete governed-source create/update/delete batch as an atomic in-memory candidate. Catches cross-file forbidden edges and cycles before any host write, and returns per-file content hashes plus base/candidate tree and policy hashes. Never writes files.

Prepare a write against the architecture contract: place (filePath required; fail-closed without it — never invents a path) + constrain (layer, mayImport, mustNotImport, forbiddenGlobals) + validate source + optional mechanical-safe autoPatch + judgmentBrief when judgment is needed + contentHash for host commit. Also returns the versioned new/worsened designDelta for the proposed full file. Composes ark_place + write-gate. Fallback when the host has no trusted hard pre-hook (or that hook is fail-open). When a hard hook is installed, the host already gates the write; this tool stays available but is not the primary gate. When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. When the matched layer has layers[].trustBoundary (public|auth|admin|internal), the JSON includes trustBoundary; omitted when absent. When the matched layer has layers[].owners, the JSON includes owners; omitted when absent. Single-file evidence is partial, so valid stays false (isError:true) until complete-candidate preflight; read lexicalValid for the snippet verdict and use ark_prepare_change for a green result. Returns { filePath, layer, description?, trustBoundary?, owners?, valid, lexicalValid, violations?, autoPatch?, judgmentBrief?, contentHash, ... }.

Score this repository against templates/architecture-playbook.json and return the tool-agnostic application shape to adopt (archetype, preset, phased layer plan, analogy, anti-patterns). Same structured output as ark-check --recommend --json. Call BEFORE generating project structure on greenfield or early-adoption repos.

Deterministic brownfield rules inventory (AR13): validation-in-controller, magic constants, anemic entities, mutation-without-guard. Returns honest counts (inventoried/under-contract/frozen) — never a numeric score. Same plane as ark-check --rules-inventory.

Unified session/project status manifest (ACS03): project identity binding, honest write-path activation, last-check summary, ArkRules residual counts, and primary next action. Same envelope as `ark status --json`. Never prompts; never a numeric score. Prefer after ark_identity so project.expectedRoot is bound.

Propose ark.config.json include roots from workspaces and nested TypeScript packages (polyglot-safe). Same idea as ark-check --suggest-include. Use when coverage is empty or the contract misses package roots.

Single-file lexical check of a source snippet against Ark's architecture (forbidden infra imports, unknown intents, layer-reference violations, and the enforced ArkRun / ArkRules structure / ArkOrder sensors CI runs on that file). One file can never prove the whole candidate, so the result is always partial: valid:false and isError:true until complete-candidate preflight. Read lexicalValid and violations for the snippet verdict; use ark_prepare_change (or arkgate-check) for a green result. For hard write-path blocking use the `arkgate-mcp --hook` PreToolUse hook, not this tool. Returns { valid, lexicalValid, completeness, violations, autoPatch? }. autoPatch (when present) is a mechanical-safe rewrite of the source (import type conversion); hosts may apply it instead of re-drafting.