Archkeel – coding agents declare architecture changes before they submit

Archkeel, a tool from rapiddweller, checks architecture boundaries and declared changes in AI-assisted code by comparing an accepted commit with a candidate and verifying the candidate matches an expectation published before its first submission. The tool catches two failure modes that finding-only diffs miss: architecture changed without being declared, and a scanner seeing less of the program so results look clean only because the graph became blinder. In Fixture A, a refactor introduced no new forbidden import, cycle, or private crossing, but resolved calls fell from 2 of 2 to 0 of 1 and unresolved calls rose from 0 to 1, producing an Archkeel verdict of FAIL with no new finding fingerprints.

The agent declares before it submits. The check is deterministic. Archkeel checks architecture boundaries and declared changes in AI-assisted code. It compares an accepted commit with a candidate, checks their scans against the configured contract, and verifies that the candidate matches an expectation published before its first submission. It catches two failure modes that finding-only diffs miss: - the architecture changed without being declared; - the scanner saw less of the program, so the result looks clean only because the graph became blinder. Try the demo try-the-demo · Onboard your project onboard-your-project · How it works how-it-works · Reference https://github.com/rapiddweller/archkeel/blob/main/docs/reference.md · Roadmap https://github.com/rapiddweller/archkeel/blob/main/docs/roadmap.md Implemented and planned work is tracked in the roadmap https://github.com/rapiddweller/archkeel/blob/main/docs/roadmap.md . An agent can keep tests green and introduce no new architecture finding while making the code harder to analyze. If the gate compares finding identities only, that change passes. Fixture A is the smallest example: php def run key: str - int: - return first + second + handlers = {"first": first, "second": second} + return handlers key The refactor introduces no new forbidden import, cycle, or private crossing. But static call resolution gets worse: | Observation | Accepted | Candidate | |---|---|---| | Resolved calls | 2 of 2 | 0 of 1 | | Unresolved calls | 0 | 1 | | New finding fingerprints | 0 | 0 | | Archkeel verdict | baseline | FAIL | php expectation fulfilled: FAIL regression check failed in calls unresolved: 0- 1 regression check failed in unresolved ratio: 0/2- 1/1 Archkeel compares raw measurements as well as finding counts and fingerprints. The ratio check uses integer cross-multiplication, never rounded percentages: U candidate × T accepted <= U accepted × T candidate when both T 0 - Precommitment with evidence. The agent publishes the intended change before it submits the candidate. Git ancestry and host records prove the order; author timestamps do not. - Coverage-aware regression checks. A disappearing edge is not mistaken for an improvement just because a finding disappeared with it. - Explicit uncertainty. An incomplete scan, broken lock, empty scope, or runtime mismatch returns exit 2 with a diagnostic. Unknown never becomes green. Archkeel complements tests, linters, and human review. It does not replace any of them. Its job is narrower: keep architecture changes declared, observable, and mechanically checkable. The HTML report is designed for a reviewer making a merge decision: - Decision first. PASS , REJECT , or UNVERIFIABLE and one sentence explaining it are visible before details, in the HTML report and in the terminal. - No blended score. Scan completeness, contract compliance, expectation matching, Git order and publication order remain separate verdicts. - Unknown stays visible. Missing or invalid evidence includes the affected subject, unknown claim, and remedy. - Evidence stays inspectable. Exact counts, fingerprints, source locations, digests, and runtime provenance remain available beside the verdict. The demo builds three small Git repositories and runs the real checks. Fixture A is rejected because the call graph got blinder, Fixture B because its expectation was published too late, and Fixture C passes. git clone https://github.com/rapiddweller/archkeel.git cd archkeel make demo make demo-screenshots OUTPUT=<directory also captures each HTML report as PNG and each terminal view as SVG. Requirements: Python 3.11+ and a Git repository with at least one commit. uvx archkeel skill install claude or codex uvx archkeel init uvx archkeel validate init observes the only top-level package and writes archkeel.toml , architecture-contract.json and docs/architecture/architecture.md . It proposes one component per subpackage and forbids every component pair that is not imported today. Each rule starts with a TODO: rationale, so validate lists every decision that remains, each with a JSON Pointer. Give the prompt in docs/onboarding.md https://github.com/rapiddweller/archkeel/blob/main/docs/onboarding.md to your coding agent, or work through the list yourself. The rule catalog is in docs/rules.md https://github.com/rapiddweller/archkeel/blob/main/docs/rules.md . To install it permanently instead, run pip install archkeel . Every command explains itself with archkeel <command --help . Observe the current repository: archkeel report The command writes the canonical architecture.json and a self-contained architecture.report.html beside it. A terminal shows the decision and verdicts; pipes and --json receive the JSON result. Check a candidate against its published expectation: archkeel check \ --root /repo \ --baseline "$B" \ --expectation-commit "$E" \ --head "$H" \ --expected expectation.json \ --expected-digest "$DIGEST" \ --accepted-branch main \ --branch candidate Run the Python version required by the repository being scanned. A mismatch is reported as runtime mismatch with exit 2 , not as broken source code. php flowchart TB B "Locked accepted state" -- O "Observe accepted + candidate" E "Expectation published first" -- H "Candidate submitted" H -- O O -- C{"Deterministic check"} C -- P "0 · pass" C -- R "1 · reject" C -- U "2 · unverifiable" classDef locked fill: 141414,stroke: C5F82A,color: E8E8E2 classDef declared fill: 141414,stroke: 5EEAD4,color: E8E8E2 classDef candidate fill: 141414,stroke: 8A8A84,color: E8E8E2 classDef gate fill: C5F82A,stroke: C5F82A,color: 0D1F05 classDef result fill: 141414,stroke: 2A2A28,color: E8E8E2 class B locked class E declared class H,O candidate class C gate class P,R,U result A check answers three independent questions. It never compresses them into a single score. | Verdict | Question | Typical failure | |---|---|---| | observation complete | Did the scan see everything it claims to see? | Incomplete scan, empty scope, rule without subjects | | declared rules | Does the code obey the architecture contract? | Forbidden import between components | | expectation fulfilled | Did the candidate match the declaration without regressions? | Coverage regression, undeclared change, late expectation | | Exit | Meaning | |---|---| | 0 | Complete report or successful check | | 1 | Rejected because at least one verdict is FAIL | | 2 | Unverifiable input, always with at least one diagnostic | Every exit 2 diagnostic contains: kind · subject · unknown claim · remedy A broken lock is therefore not interpreted as an empty accepted state. gitGraph commit id: "M · accepted" commit id: "B · lock only" branch candidate commit id: "E · expectation only" commit id: "H · implementation" | Commit | Contract | |---|---| | M | Accepted state. Archkeel re-observes it. | | B | Lock-only child of M and tip of the accepted branch. It binds the config, checker, and observation digests. | | E | Child of B that changes only the expectation file. It must be published before the first submission of H. | | H | Descendant of E. It must not modify the lock, config, architecture contract, or expectation. | 1. Start from the lock commit B . 2. Write the intended architecture change and commit it alone as E . 3. Publish E before submitting implementation work. 4. Implement the change in one or more commits ending at H . 5. Run archkeel check . Fix the code or revise the proposal in a new protocol cycle; do not rewrite protected inputs inside H. Fixture B writes its expectation after implementation by deriving it from the observed delta. Its architecture findings are otherwise clean. Archkeel still rejects it: host order: FAIL expectation fulfilled: FAIL expectation was not published before the first candidate submission Precommitment proves "published before submission." It does not prove that no private edit existed before publication. In GitLab CI, Archkeel reads merge-request diff versions through glab to establish publication order. For local testing, replay captured host records: uv run archkeel check ... --host-records records.json A local replay validates the record shape and behavior. It does not prove host authenticity. Run the complete project gate: make check This runs Ruff, strict mypy, pytest, and Archkeel's self-check. Run the full release check, build both distributions, and install each one in isolation: make release-check Reproduce the protocol fixtures: make fixtures architecture-contract.json https://github.com/rapiddweller/archkeel/blob/main/architecture-contract.json holds Archkeel to the rules it sells, and every rule was proven by a deliberate violation: - Closed world. Seven components; every ordered pair is either one of the ten observed imports or forbidden with a rationale. The architecture guide https://github.com/rapiddweller/archkeel/blob/main/docs/architecture/archkeel.md explains each allowed edge in the single marked component graph. - Deterministic core. ir and check never import adapters or presentation; the CLI is the composition root. The analyzer may import only archkeel.ir.model and archkeel.ir.codec . - No dynamic shortcuts. getattr , hasattr , cast , eval , exec , dynamic imports and type: ignore are forbidden everywhere. - Confined dependencies. packaging only in the analyzer runtime gate, rich only in the terminal view, rich argparse only in the CLI. - Complete and acyclic. Every module belongs to exactly one component, and components form no cycle. make check reobserves the repository and compares it with fixtures/D-self https://github.com/rapiddweller/archkeel/blob/main/fixtures/D-self/result.json ; CI also runs archkeel validate and uploads the self-observation. Archkeel is deliberately strict about what it can prove: - Competing implementations: review is still required when no declared rule or observed regression exposes them. - Private crossings: only import records are checked. import pkg; pkg. member is not detected. - Precommitment: publication order is proven; private editing order is not. - Analyzer runtime: Archkeel's Python must be at least the target repository's Python. - Acceptance: accept is a placeholder and returns exit 2 . - Onboarding: init detects one top-level package; other layouts need --source and --namespace . It cannot know why a boundary exists, so every rationale stays a decision. Completed work and the ordered UI, CI and release plan live in docs/roadmap.md https://github.com/rapiddweller/archkeel/blob/main/docs/roadmap.md . Items remain planned until their listed evidence exists. MIT © 2026 Rapiddweller Asia Co., Ltd. Maintained by Alexander Kell https://github.com/ake2l .