archkeel
Use when meeting a new or unknown codebase ("explain this codebase", "how does it start", "show me the flow of X"), defining or reviewing architecture, maintaining nested contracts, or checking an Archkeel repository before submitting code.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 18
- Forks
- 3
01 前言 Front Matter
- name
- archkeel
- description
- Use when meeting a new or unknown codebase ("explain this codebase", "how does it start", "show me the flow of X"), defining or reviewing architecture, maintaining nested contracts, or checking an Archkeel repository before submitting code.
03 SKILL.md 正文
Archkeel
Archkeel is a deterministic architecture checker. Main observes Rust and TypeScript through native collectors, evaluates a
declared contract of components and rules against that observation, and distinguishes
PASS, FAIL and UNKNOWN. Rules live in architecture-contract.json and its explicit nested
contracts; nothing is enforced by convention alone.
Python and Dart projects get verdicts only for import rules in this version; use archkeel 4.0.1 for the other rules.
The Rust core decides validate and report, and no other command runs in this version.
check, explore, init, guide, story, view and studio give a typed refusal with exit 2.
Release 4.0.1 has check and init; no release has the other five commands.
A refusal is not a result: do not report PASS after one.
Unsupported profiles give exit 2 before collection, including saved facts and baseline commands.
Do not report PASS for a supported subset of an unsupported project.
In a source checkout, run make core to build the core binary. There is no Python fallback.
On main, report --output PATH writes one static HTML page. Add --format json for the core frame.
There is no default file or sidecar. The parent must exist; final links and directories refuse with exit 2.
Ancestor links are resolved once. Empty, . and - output targets refuse before the scan.
Safe file output requires POSIX directory handles. It keeps stdout and the frame exit unchanged.
If file delivery fails, stdout keeps the frame verdict but exit 2 replaces the verdict exit, including FAIL exit 1.
UNKNOWN and collection-refused reports show their causes. A refusal without an accepted frame writes no file.
This is not architecture.json, a saved snapshot or a graph. The legacy report instructions below do not apply to main.
validate --output, --html, saved-input and report-filter options remain refused.
First run on a codebase
For native Python parity work, use --dump-proofs for the import-local proof boundary (AD-404).
Its empty provider proof sets do not prove member convergence or enable the production reply.
If explore reports runtime_mismatch, do not use its result as a complete scan. Read the
reported current Python version and full requires-python range. Select a Python version that
satisfies that range, then retry with uvx --python <compatible-version> archkeel explore --json.
Archkeel does not install or switch Python versions.
Use this procedure when a repository has no archkeel.toml. The first run gives the owner content
from the measured code: how the system starts, an overview, and one sentence for each component.
After the draft, continue with "Onboarding" below. When the owner wants to see the map in the
browser, use the explore skill with the same scope options as explore. Studio is local and
writes nothing into the repository (AD-290).
- Run
archkeel explore --language <language> --source <dir> --namespace <name> --json. Add--tsconfig <file>for TypeScript. It writes nothing into the repository. Checkscan_rootsas "Show a flow" step 2 tells. Keep thefindingsof the result. - Run
archkeel report --input <snapshot> --only architecture --json.<snapshot>isartifactin the explore result. - Ask the owner once: "Create a draft contract?" A request to onboard or to set up Archkeel is the yes: go to step 5.
- Without a clear yes, skip steps 5 to 8 and use the explore snapshot. Never write a contract or another file into the repository. The views of steps 11 and 12 write only to the user cache.
- With a yes, run
archkeel init --source <dir> --namespace <package> --language <language> --json. Use the scope options of step 1 with the same values, also--tsconfigfor TypeScript. Omit them whenexploreneeded none. Each rule it drafts hasdecided_by: "agent"and waits for the architect. - For each top-level component (about 10 at most), write one sentence as one list item in
responsibilities. Base it on the package docstring, the entry points and the imports of its modules. Citefile:linein the sentence, not inprovenance(it takes paths only). Setdecided_by: "agent"on the component. Without evidence, keepresponsibilities: []and say "unknown" in chat only. Never invent a responsibility. - Optionally, replace a drafted
labelwith a short speaking name, only in the new draft.labelis the name thatrequires,--componentand nested scopes use. Then runarchkeel validate --write-graphto update the graph in the architecture page. For a draft, exit 2 withdecision.openandrationale.placeholderis expected. Do not fix them: the architect closes them in "Interview mode". - Run
archkeel report --output <tmp>/architecture.json --json, with<tmp>outside the repository. The draft changed the contract digest: this file is now<snapshot>. Keep thefindingsand thedeclared_rulesof the result. - Write a "get started" view spec with steps and stops, as "Show a flow" steps 3, 4 and 6
tell. Start at each entry point: a
[project.scripts]target (pkg.mod:mainis the module nodepkg.mod), a__main__module or amain(). If you find no entry point, say so and ask the owner for the start module. - Add the first modules that the entry point imports or calls, one direct edge for each step.
- Run
archkeel view check <spec> --snapshot <snapshot> --json. - Run
archkeel view show <spec> --snapshot <snapshot>. The page opens at the tour. - Give the owner an overview in chat:
- each top-level component with its name and its sentence, or "unknown";
- the start flow, each step with its status mark;
- up to 3 weak spots from the latest
findings(step 8 after a yes, else step 1), with theirlocations. With none, say that there are none. The kind does not give the scope of a cycle: amodule_cyclecan cross components. Read itssubjects(the members),component_idsand the evidence lines inpath.steps, and say which components it touches. Afan_in_huborfan_out_hubis a hub; - after a yes, the
declared_rulesof the draft.
- Offer the next step: define a target together, then compare it in the Target and Diff views.
Show a flow
When the user asks "show me the flow of X", answer with a checked view, not with text only. A view spec is author text; the check in step 5 decides what the code proves (AD-284).
- Confirm the start point and the goal. Ask one short question only when the request is ambiguous.
- Get a snapshot. With
archkeel.toml, runarchkeel report --output <dir>/architecture.json --json. Without it, runarchkeel explore --json: no contract, no setup, output only in the user cache. Onscope_empty, read the diagnostic and runarchkeel explore --source <dir> --namespace <package> --language <language> --json. Use the same options whenscan_rootsis not the code in question. Keep--languagewhen the language is not Python. Ifsrc/has no Python package, detection searches the root.<language>isrustortypescript. For TypeScript, also pass--tsconfig <file>. The snapshot path isartifactin the result. - Query before you write.
archkeel report --input <snapshot> --only architecture --jsonlists the component ids.archkeel report --input <snapshot> --only architecture --component <id> --full --jsonlists itsmodules. A key''or a key that starts with.gets a prefix: theselector_prefixof that component when present, else its ownnamespace. A component with aninsidecontract lists most modules under the child ids of the first command. Use module names as nodes: a child component isunknownas a node. Use module nodes for import checks; function nodes support calls only. Source text names candidates, not proof. Read the evidence lines from the check. - Write the working spec in a new temporary folder outside the repository and outside an output
folder (
exploreandview showclear theirs). Follow the schema reference and the example. Copysource.source_digestandcontract.digestof the snapshot intosnapshot. Give each later step and each edge akind(importsorcalls); the first step takes none. Keep no node or edge that the check makesmissing, except when you deliberately assert it. Set"claim": trueand explain why innote. Keep anunknownstep withoutclaimso its cause stays visible. Never writestatusorevidence: the check decides, and such a spec is rejected (exit 2). - Run
archkeel view check <spec> --snapshot <snapshot> --jsonand read each status:proven: observed, withevidence(file,line). Read those lines: a module edge can come from another function. Only one direct edge of its kind proves a step.missing: not in the code. Fix the node orkind, remove it, or keep it as a claim. A step with no direct edge ismissingtoo: add the modules between as steps.unknown: the snapshot cannot decide. Keep it with your note, withoutclaim, so its reason stays visible. A partial call isclaim, notunknown. Check module pairs asimportstoo:missingthere means no static link (a parameter, a port or a child process). Say so.declared: a contract component orrequiresentry. Afterexplore, a layout group declares nothing and isunknown: use module nodes.
- For a first contact ("how does it start?"), also add
stops: 4 to 8 nodes in reading order, each with atitleand anote, and set"schema_version": "1.1.0". A stop takes nokind: it is a reading order, not a claim. The check adds measured facts to each stop (AD-289). Runarchkeel view show <spec> --snapshot <snapshot>. Stderr names the page. Without stops it opens at the flow; with stops it opens at the tour. Tell the user to open it:open <page>on macOS,xdg-open <page>on Linux. - Tell the user the count for each status, each claim, each
unknownwith its reason, eachmissingand each change after the first check. Say: "proven means structure of the code (an observed import or call), not runtime order."
A graph path is not an execution trace. An import proves only that one module imports the other.
Without a contract the result has target: unavailable and declared_rules: UNKNOWN, never PASS.
Your explanation is your own text, without authority. Never change source or contract for a view.
The explain-flow skill stores the final checked story under .archkeel/stories/ as reviewed
documentation (AD-291). This specific exception does not allow other drafts or evidence in Git.
Onboarding (first time in this repository): a target, not a description
architecture-contract.json is the target architecture — where the system should be, not
where the code already is. archkeel report measures declared constraints, not the quality
of the whole architecture. The architect owns the target and review scope; within that scope,
inspect the physical structure at every depth, not just the top level. Support them with evidence
from the repository and the architect's quality goals for this codebase (which components
must scale, stay easy to change, or are performance-critical). Read those goals from ADRs
and architecture documents first; ask the architect only when a goal is unknown and would
change your recommendation. Every
recommendation and every rationale cites the goal it rests on. There is no contract field
for a quality goal: record it next to the rule it justifies, following the chosen decision
mode below.
On a repository without archkeel.toml, start with "First run on a codebase": a request to
onboard is its yes, so explore comes first and init follows at its step 5.
For requested first-time onboarding, inspect existing files, then run
archkeel init [--root DIR] [--source DIR] [--namespace NAME] [--force] [--json] once.
A read-only assessment uses existing contracts, reports and source; it does not authorize
initialization, contract edits, file moves or commits.
Preserve existing contracts and their inside references. If onboarding files already exist,
continue from them; do not use --force without explicit approval to replace those files.
init checks src/ for Python packages first. If it finds none, it checks the repository root.
In the selected directory, it uses the only top-level package or the package named by
pyproject.toml's [project] name when test packages sit beside it. Otherwise it exits 2 and
asks for --source and --namespace. It also requires an existing Git repository with at least
one commit, and writes three files: archkeel.toml, architecture-contract.json (one component
per top-level subpackage/module, plus complete_assignment and — only when no component
cycle exists — no_component_cycles, and interface_boundary when it drafts public
interfaces; no dependency rule), and
docs/architecture/architecture.md (component table, each component's modules and inner
edges, and a Mermaid graph of observed edges).
Every rule init drafts carries decided_by: "agent" as a placeholder you must resolve, not
an answer, and so does every component whose public list it drafted. It refuses to overwrite existing files without --force.
init does not infer a foundation or decide where classes belong. Ask who owns a shared type
first; foundation is not the default owner for domain enums or models. Record the architect's
choice with the existing symbol_placement rule: set source to the package, class_kinds to
the types it owns, and exact_sources to the chosen module (or allowed_sources to a package
subtree). Follow the ownership example in the target-first guide of release 4.0.1. Run archkeel validate after
adding it; a misplaced matching class is a rule.violated.
For TypeScript, use archkeel init --language typescript --source src --namespace app --tsconfig tsconfig.json; for Dart, use archkeel init --language dart --source lib --namespace app. Repeat --source for multiple roots. A non-empty namespace initializer
requires explicit ownership via exact_modules; inspect it before recording the owner.
init shows DRAFT while its completed scan remains PASS. Review measured
measurements.scalars.cycle_edges: a cyclic component graph receives no drafted
no_component_cycles rule. Cycles are an advisory, not an error diagnostic.
Ignore /test-artifacts/ in .gitignore for default report output, or choose --output.
Restore missing configuration in existing setups or select --config PATH; use init
only for a new setup. Without Git history, run git init and create a commit first.
For example, after defining storage's responsibility and approving storage -> domain,
add this fragment to the existing storage component. Replace the example reason with
the decision owner's actual reason; keep its existing ownership and public interface fields.
{
"responsibilities": ["Persist and retrieve domain records."],
"decided_by": "architect",
"requires": [
{
"component": "domain",
"rationale": "Storage persists domain records.",
"decided_by": "architect"
}
]
}
Append this rule to the existing rules list. An empty or absent requires list then
forbids all outbound component pairs; it does not grant observed imports.
{
"id": "REQUIRES-COMPLETE",
"kind": "complete_requires",
"rationale": "Each source states its approved outbound dependencies.",
"provenance": ["docs/architecture/architecture.md"],
"decided_by": "architect"
}
Review drafted public entries and replace each structural rule's TODO with its own real
reason and decision author. A non-empty namespace initializer needs explicit ownership via
exact_modules; inspect it before adding that ownership. Rule kinds and selectors are in
the rule catalog.
When an API role must declare a canonical port, use contract 3.9.0's
protocol_declarations. Select a source scope plus exact parameter or annotated class
member names and visibility; this includes future declarations. The canonical dotted
protocol must resolve to a scanned Protocol. An optional selector permits only that Protocol
with None; broader unions, missing annotations, object, and Any fail. Statically
proven single-name TypeAlias chains resolve to their target; unsupported alias shapes,
including union-valued aliases, remain UNKNOWN. Shadowed and unresolved names also remain
UNKNOWN. MyPy checks assignability, and the rule does not replace structural conformance review.
Then pick one of two modes. The architect chooses; do not choose for them.
Physical structure review (both modes)
After init, and during architecture assessments, inspect every maintained source package
in scope recursively down to leaf packages, whether or not it has an inside contract.
The generated inventory and a green contract are not evidence that this structure is good.
- Count direct source modules and immediate subpackages at each level; exclude
__init__.pyfrom this count, not from ownership, behavior or dependency review. Record excluded generated or vendored trees. More than seven direct children triggers a review, not an automatic split or a failing rule. Five to seven understandable groups is a review heuristic, not a cognitive law. - Challenge mixed responsibilities, unclear names, oversized leaf modules, excessive nesting, cycles and cross-package coupling even below that threshold. Trace entry points and data flow before choosing boundaries; check who owns shared types and public interfaces. Follow one real operation through business logic, state/external effects and its observable result. For each layer, name its invariant, failure mode and what breaks if removed.
- Review changed APIs against a concrete caller purpose: named operation/type, typed inputs and result, errors, and state/resource/transaction lifetime. Assess test-only helpers and dynamic discovery separately; discovery needs a real caller/protocol, not an invented import. Recommend delete/simplify/keep for redundant wrappers, duplicate knowledge owners, brittle string dispatch and reflection/coercions hiding incorrect models. Candidates are review work, never automatic deletion or a semantic PASS.
- Propose physical packages around cohesive responsibilities, not arbitrary groups of seven
or diagram-only clusters. Compare the current and target tree and allowed dependency
directions. Keep a cohesive larger package when splitting only adds navigation or coupling;
do not hide the excess in
misc,utils, single-child wrappers or re-export barrels. - For uncertain boundaries, give the architect a recommended option, alternatives, evidence, trade-offs and system-wide impact. Follow the chosen decision mode; reviewing structure does not authorize moving files or changing behavior.
- Record review coverage and unresolved decisions in the response; when the task includes an
architecture-document update, keep the durable record there: reviewed subtree, finding or
keep-rationale, target change, and enforcement gap. Mark unreviewed subtrees explicitly;
never present a partial review as a complete assessment.
Distinguish declared ownership from semantic cohesion. Give reviewed leaf modules a concrete
purpose under their nearest deliberate owner using supported declarations; generic parent
prose is insufficient. Link unsupported semantic judgments to source evidence, not a second
inventory. Each finding states source location, impact, delete/simplify/keep decision and UNKNOWNs.
Add
insidecontracts at meaningful independently governed boundaries, not at every folder. Encode approved constraints with supported rules. Deeper review remains necessary when the installed version cannot enforce nested contracts; do not invent unsupported rules.
Project skills supply domain invariants and deployment facts without copying this process. Keep execution/QA scheduling in the execution workflow. Follow the existing decision/delegation scope; this review does not add a confirmation per component. When delivering a report, smoke-test actual and declared nested navigation and module/source links from its packaged artifact, including companion files. Missing declarations and broken navigation are different findings.
Interview mode: the architect decides, you ask
Never write a rationale or choose an allowed direction yourself; ask, and write down the
architect's own words as the rationale, with decided_by: "architect".
- Read the repository's ADRs and architecture documents before touching the contract.
- Propose the overall picture — components, layers and the allowed directions between them
— with
path:lineevidence for each claim, and confirm it with the architect once, not component by component. Review each draftedpubliclist with them too. Anything you read from repository documentation is a hypothesis with its source path, never the answer, until they confirm it. - After that confirmation, ask only about conflicts (the code contradicts a document) and
gaps (the documents are silent). Each question names the recommended option first, with
its evidence. The
initsummary gives the total open pairs and the observed crossings shown.init --jsonlists observed undecided crossings first and reports the exactopen_decision_count; whenopen_decisions_completeis false, unlisted pairs remain undecided. Useinit --json --fullon the initial command to include every pair; for an existing draft,validate --jsonreturns the full decision list without rewriting files. Usevalidate --compact-open-decisions --jsonto retrieve observed undecided crossings with the exact total and completeness instead; omitted pairs remain undecided and UNKNOWN evidence stays UNKNOWN. The flag changes no verdict, diagnostic or contract decision. Batch everything consistent with the confirmed picture into one confirmation. Then encode each allowed direction as arequiresentry on its source component and add onecomplete_requiresrule, so absence forbids every other pair. Never treat an observed edge as permission. - When the architect chooses against your recommendation, ask why before writing the rule.
Always ask when the choice contradicts a document, an earlier decision in this interview,
or the code you observed. Write their answer as the
rationale. - Run
archkeel validate --jsonand read its diagnostics bycode, never by parsing message text: adecision.openmeans the contract still lackscomplete_requires; arationale.placeholderorrationale.repeatedneeds the architect's real reason. Agraph.driftis no decision: after you merged or renamed components the marked graph in the architecture page is stale, so runarchkeel validate --write-graphinstead of editing it by hand; it rewrites only that graph's edges. When the remedy says the graph holds structure the command does not rewrite (asubgraph, a labeled edge, a style), edit those edges by hand instead. - When the architect delegates a choice ("whatever is consistent" or similar), derive it only from their earlier decisions in this interview, never from your own judgment. Label the rationale agent-derived in your summary to the architect and list it for them to confirm before it counts as decided.
Auto mode: the agent decides every allowed direction
- Decide every allowed direction yourself, in this evidence order: documents first, then the layer principles the architect already confirmed or the documents state, then your own judgment, labeled as judgment in the rationale.
- Never treat an observed edge as permission: code importing across a boundary today is not evidence the boundary should allow it.
- Write every rule you decide with
decided_by: "agent", and mark a component whosepubliclist orrequiresedges you decided the same way:decided_byon the component covers itspubliclist and everyrequiresentry that carries none of its own, and one entry may override it. - End with a summary of your decisions grouped by evidence basis (document, layer principle, judgment) and name the lowest-confidence decisions first, for the architect to review.
A later interview on an auto-mode contract asks the architect only about rules, entries and
components with decided_by: "agent"; an architect-decided one is already closed and is not
reopened.
Ending onboarding, either mode
Before ending, record the physical structure review and any deferred subtrees or decisions;
a closed dependency contract alone does not complete the architecture assessment.
The dependency interview (or auto-mode pass) ends when complete_requires closes the
dependency set and validate --json reports none of decision.open, rationale.placeholder or
rationale.repeated — not when the command exits 0. A rule.violated diagnostic is the
architecture's own finding, not an onboarding step: the code still uses an edge the target
omits. Show it to the architect with archkeel report. They resolve it by changing the code or
changing the target; the agent never does that itself and never loops validate --json waiting
for exit 0.
Once it ends, run archkeel report. Include the generated files (archkeel.toml,
architecture-contract.json, docs/architecture/architecture.md) when they are part of the
requested change. A remaining rule.violated is follow-up code work, tracked separately from
onboarding.
Where that follow-up is long — a contract that states the target architecture the code has yet to reach — freeze the known violations instead of weakening the contract:
archkeel validate --baseline known-violations.json --write-baseline # once, then review it
archkeel validate --baseline known-violations.json # the CI gate
--baseline and --amendment are relative to --root, like the contract: with --root mobile,
pass --baseline known-violations.json for mobile/known-violations.json, never the
mobile/-prefixed path. An absolute path inside the root works; one outside it is
baseline.invalid, exit 2.
The gate fails (exit 1) on a violation the file does not state, and on one it states that
nobody violates any more — so the budget only shrinks, and the file is rewritten in the same
change that shrinks it. declarations.measurement_budgets may put deterministic scalar values
through the same loop. declarations.facade_budgets and
declarations.coupling_budgets set name targets in the contract, and the baseline holds their
accepted names.
Never raise any of them to make a run pass without the architect's decision.
When calls_unresolved rises, rerun with --against <base ref>, as the
finding says: unresolved_call_changes names each added and removed unresolved call with its
caller, path, lines, expression, reason and component. report --only calls --json lists every
unresolved and partially resolved call as filtered_calls; add --component <label> for one
component's calls.
A reviewer or a CI gate may hold your branch to this the same way, with archkeel validate --against <base ref>: it classifies every difference from the contract at that revision — a
new requires edge, a public entry, an allowed_sources module, a relaxed or deleted rule,
a padded baseline entry, and anything else this repository's ir.widening does not otherwise
name — as a widening, which fails (exit 1) unless --amendment <path> names a file the
architect wrote, recording who decided it and why, bound to this exact change.
In validate --json, widenings is null when --against was not checked, otherwise it lists
unamended widenings with code: "ir.widening", subject and field; failures keeps the
human-readable messages. amendment_status is valid or stale when a supplied amendment was
checked, and null otherwise. A valid amendment may leave widenings empty even when it accepts
a real change.
Never widen the contract in the same change that removes the violation it names: fix the code,
or ask the architect for an amendment. The full loop — gating, widening, picking a slice of the
backlog and landing a planned interface — is worked end to end on the shop sample in
https://github.com/rapiddweller/archkeel/blob/4.0.1/docs/target-first.md.
Retiring local dependency gates
Use native dependency policy for proven Python literal loaders as well as static imports. Binding mutation, unknown targets and nonempty builtin fromlists retain scoped UNKNOWN evidence. A dependency edge does not prove a public value API. Before deleting a local scanner, compare its forbidden, allowed and missing-scope inputs against the installed release, including aliases and dynamic forms. A source checkout or Draft PR is not proof that the installed release supports them.
Use call_owner only where its installed observer proves the complete selected
call scope. Observation 2.4 adds bounded proofs for stored typed receivers,
stable default constructions, and selected native targets (random,
secrets.token_hex, and CPython datetime.datetime.now). Inheritance is followed
only through a unique recorded base path. Dynamic dispatch, custom allocation,
unsupported mutation, and native APIs without an admitted provider witness remain
UNKNOWN. The datetime witness inspects the isolated collector runtime’s stdlib
descriptor and source digest; it does not import project modules. Arguments and
guards are not proved by this change. Check the rule receipt and supported forms
before retiring any method-name scanner. Older readers must reject observation
2.4 rather than omit the added proof vocabulary; current readers continue to
accept historical observations.
Contract 3.8 bounded_numeric_operand checks selected Python % and %= sites
by written terminal identifier suffix. Only bounded integer/Boolean literals,
unary signs, powers and unique preceding aliases prove values. Review its source
evidence: each operation and alias must fit a replayable single-line excerpt
of at most 16,384 characters; single-line if, elif, while, for, with,
function and class headers and inline suites are supported with Python indentation. Multiline
or otherwise incomplete evidence remains UNKNOWN. Review the source
receipt and UNKNOWNs; it does not establish runtime types, reachability, entropy
or collision freedom. Empty/missing selected scope is UNKNOWN. See
AD-246
and rule limits.
Use forbidden_call_argument to select one written-literal policy
for a canonical target's formal parameter. It binds explicit source actuals to
the observed signature; spreads, invalid bindings, missing signatures and
unproven targets leave UNKNOWN. Calls without canonical binding carry null
argument facts; a proven call with no actuals carries an empty list. It does not check runtime type compatibility
or apply omitted defaults. Check the rule receipt and supported forms before
retiring any method-name scanner. Argument facts require observation 2.5 and
contract 3.10; older readers must reject that evidence. The current reader
continues to accept historical observation formats.
Use catalog_argument to compare a bound operation argument against canonical Python enum string values, and catalog_use to require a real selected member read. The contract names declaration owners, never copied values or used flags. Comments, docs, definitions and annotation-only links are not reads; TYPE_CHECKING reads count syntactically. Missing or partial scope remains UNKNOWN. These rules require contract 3.14 and observation 2.9; older saved artifacts remain readable but cannot certify them. See AD-251 for limits.
Use source_ownership for Python-local policy over source roles. In retired mode,
select symbols and roles definition, read, write and/or delete. In confined
mode, select symbols plus owner, or formal parameters plus value_owner; choose
roles value_transfer, parameter_default and fallback only when the observer can
link each value to admitted source evidence. Unsupported or ambiguous expressions remain
UNKNOWN. This rule is available with contract 3.12 and observation 2.7; older readers
must reject those formats rather than silently ignore the rule or role facts. See
AD-249
and the rule catalog.
Use forbidden_construct.selector when a policy must select one nominal
receiver/member and access or comparison role. Contract 3.11 and observation
2.6 enable the Python slice: annotated direct member reads, positional literal
reflection names, selected local constructors and type probes, literal equality
in either direction, membership, match, and startswith/endswith.
Dynamic names, unannotated or ambiguous receivers and missing selected subjects
remain UNKNOWN. Other language profiles do not claim selector support. See
AD-248 and
the rule grammar.
forbidden_effect_under_condition is a static ownership rule. It can prove a declared
Boolean parameter/member through truth, negation, if/else, ternary and early
return/raise, plus one unique private helper with signature-bound actuals. A known
unconditional effect is reachable while the condition is true. Reassignment, named
expressions, short-circuiting, loops, try/finally, reflection and helper chains or
recursion remain UNKNOWN. Inspect the rule receipt and path evidence before relying on
PASS; see AD-250.
Daily loop
Validation reports responsibility.missing only for components explicitly marked
decided_by: "architect" with no non-whitespace responsibility text. It checks declaration
presence, not prose quality or complete coverage of cross-cutting concerns; an agent draft stays
usable and incomplete until the architect decides it.
Contract text with decided_by: "architect" wins over agent text. Text with decided_by: "agent"
is a draft: revise it only on request, and show the difference in chat.
- Start with
archkeel report --only architecture --json. It projects authenticated intent, ownership, dependency permissions, observed use and required Target relationships. Use--component <id-or-scope>for a slice; global verdicts, coverage and uncertainty remain. Missing evidence is UNKNOWN. Permissions never prove use or required execution. After one scan, query that packet witharchkeel report --input architecture.json --only architecture --component <id-or-scope> --json. Omit--componentto discover its exact ids and scopes. This reads recorded source identity and evidence; it does not verify the current working tree or write files. Readarchitecture_projection.required_relationshipsfor Target intent. For findings, query the same packet with--only violations --component <id-or-scope> --json; add--rule <id>to intersect. The compact query omits module lists, policy detail andfiltered_violations; it reports the selected-scopefiltered_violation_count(nullwhen unavailable) and setsviolation_details_includedtofalse. Add--fullto retrieve the completepermission_rules,policy_contextand violation records:archkeel report --input architecture.json --only architecture --full --json. Full output includes an emptyfiltered_violationsarray when the measured selected scope has no findings. - Revisit the physical structure review for changed packages and their parent boundaries; recheck related findings rather than repeating a whole-repository review for every edit.
- Run
archkeel report --jsonbefore submitting any change. A rule violation does not change the exit code; read thedeclared_rulesverdict. Exit 2 means the evidence is incomplete; fix the diagnostic before trusting any verdict. An unfiltered report also carriesfindings, the ranked list its terminal summary and HTML page open with: violations, then dependency cycles, then hubs, each with asize, sourcelocationsand onesentence. Read it first; a missingfindings(filtered report) never means none. - On a large repository,
report --only violations --rule <id> --component <id-or-scope> --jsonnarrows the review surface to a slice you can actually read:--only violationsdrops component flow, communication, claims and structure from the HTML page;--ruleand--componentnarrow the violations table further and combine as an intersection. This includes local Target findings and descendants, plus crossings touching either side. Top-level labels take precedence over identical nested labels. This changes only what is shown -declared_rules, the violation counts and the exit code stay computed from every violation - and a filtered--jsonresult says so in its ownreport_filterfield, so never read a filteredfiltered_violationscount as the repository's total; read the unfilteredviolationsmeasurement for that. A--ruleor--componentyou misspelled is a named exit 2, not a silently empty page. - If a rule fails, fix the code so the rule passes.
- Never weaken or delete a rule just to make a violation disappear, unless the component owner explicitly approves the change to the contract. A silently loosened rule hides the next real violation.
validate --jsonandreport --jsonreportagent_decisionsas[agent, total], counting one rule declaration, onerequiresentry and one declaredpubliclist alike; a nonzero first value means an auto-mode contract still awaits an architect interview on those decisions.- The same two commands report
claims, the Class D review claims. They never change a verdict or an exit code; bring a nonzero count to the architect as reading work, and never delete code because a claim named it.--jsoncarries only counts; the HTML page ofreport --only architecturenames each claimed symbol, binding, repetition and type.oversized_componentsis a compatibility count, not a claim (AD-235); read component sizes in the Structure overview instead.
Nested contracts: the inside of a component
A component may name a contract of its own, which becomes a second level of the same architecture. Adding one is the architect's decision; inspecting the physical subtree is already part of the recursive review above and does not depend on that decision. A component that holds more modules than the whole top level, as the Structure overview shows, is a reason to ask, not permission to split (AD-235).
Once the architect decides:
- Inventory the source tree and the existing
archkeel report --jsonstructure measurements. Review every relevant child before grouping; a report does not cover detail it does not expose. Do not reruninit --sourceat the repository root for this scope:initwrites the standard root onboarding files and requires--forceif they already exist. On Archkeel's owncheck, a per-module draft produced 12 sub-components and 132 open decisions where the three layers the architect settled on need 6. Consolidate into a few layers with the architect before deciding a single pair. - Point the outer component at the resulting contract with
"inside": "<repository-relative path>". - Decide the inside the way you decide the top level: a
requireslist per sub-component and onecomplete_requiresrule, so absence forbids there too.
validate holds the declared levels to each other; read its diagnostics by code:
- Each level's
publiclist serves that boundary. Child APIs stay local unless the parent explicitly publishes them or a proven facade reexport. Do not copy every child API upward. reference.public_owner,reference.public_underscoreandreference.namespacealso apply inside. Correct the declaration at its mounted pointer; do not broaden ownership to silence it.- With an inner
interface_boundary,interface.missingnames an unscanned public module.interface.unusedmeans no scoped sibling import or proven facade publication reaches it. A built, unused planned entry stays target work; reaching it requires promotion throughinterface.planned_built, not automatic permission. Publisher evidence belongs to the exact parent scope, including proven re-export chains. Unknown import names are not proof of non-use. inside.forbidden_import— the inside grants an edge the level above forbids the component, by a rule or by absence underrequires. Remove the grant, or change the decision above.contract.invalidat/components/<n>/inside— the file is missing, outside the repository, or does not parse on its own.
report evaluates complete_requires a second time against the inside, over the imports the
outer scan already collected, so a crossing between two sub-components that no requires entry
covers is a violation like any other, and the flow view opens that component into its
sub-components before its modules. Such a finding names the rule as <component>:<rule id>,
for example store:STORE-REQUIRES-COMPLETE: the id you will find in the inside contract is the
part after the colon, and the part before it is the component that names that contract. Resolve
it according to the target decision: update the inside requires only for an architect-approved
crossing; otherwise change the code. Do not add a rule above to hide an inside crossing.
Explicit inside references are followed recursively and use the shared rule evaluators.
Mounting a contract does not create a standalone archkeel.toml for it. Nonempty inside
declarations fields remain unsupported and are refused. An inner external_dependency_scope
declaration is not compared with ancestor declarations; ancestor rules still evaluate their
own source scope. A physical folder alone is not a declared contract.
Maintaining a nested contract
Use the saved architecture projection with --component <id-or-scope> --full. Read the owner's
purpose/exclusions, deliberate API, dependency reasons and ancestor/child policy_context.
Fill missing context from the canonical mounted contracts and source; mark absent evidence.
Bind the review to the source revision, contract/analyzer identities and installed CLI version.
Validation catches supported reference, ownership and stale-declaration errors; it does not
judge whether responsibility prose is good.
For each edit, record affected scopes/declarations, focused/full input bytes, logical edit
files/sites, and before/after ownership, API and permissions. Edit size is maintenance evidence,
not an architecture verdict or a pass threshold. Run validate --against <accepted-ref> and
use the existing bound amendment for approved widening; never regenerate intent from imports.
Its contract_changes list each change as widened or narrowed; only widenings need the
amendment, and a tightened requires entry narrows. Narrowings cover requires, public and
rule presence only; anything else is not enumerated.
The checkout fixture
has ordering -> domain -> orders/pricing boundaries. Try these changes independently:
| Change | Deliberate edit sites | Control |
|---|---|---|
Move discount_policy from pricing to orders |
Source path; domain owner/public/module intent; ordering's existing domain port references. Keep the root API unchanged. | New owner and Target match; domain-to-adapter import still fails; unapproved widening fails. |
Rename persistence API findById to find |
Implementation/caller and the two existing nested signature targets. | Return-type drift fails; changed Target requires its bound amendment. |
| Remove unused pricing-to-orders permission | The existing nested requires entry. |
The same import passes before tightening and fails after it. |
Review the resulting owner from the same saved packet:
archkeel report --input architecture.json --only architecture --component ordering:domain:orders --full --json
For this example, a project adapter supplies only domain invariants such as "orders own lifecycle; adapters own persistence". Trace checkout through the persistence port to the observable receipt; keep cohesive larger packages when a split adds only indirection. An unused public helper needs a caller justification; a dynamically selected collector entry needs its actual process/protocol evidence. Neither import counts nor generic leaf prose settle those review judgments. Retire supplemental guards only after equivalent positive, violating and missing-scope controls pass on the installed version, including relevant alias, relative, type-only, discovery and reexport paths. Unreplaced policy remains a disclosed gap.
Rule catalog
Use the canonical field reference and examples
for rule kinds and selectors. Class A evaluates declared constraints; unavailable evidence
remains UNKNOWN. Class B compares accepted and candidate observations, requiring comparable
profiles and complete coverage. Class C records declarations. Class D claims are review tasks;
they never change verdicts or exit codes, and null means unavailable evidence.
Exit codes
See the canonical per-command exit table.
check's expectation's selected_changes may be []
when a candidate is not meant to change anything architectural, such as a pure refactor. That
declares absence, not "nothing to report": check then fails on any semantic change the
candidate actually produced, in any dimension, not only the six guardrail ones. Declare []
only when you mean it; naming the real changes remains the default. A non-empty
declaration still lets an undeclared change through in most dimensions, except
dependency_edges: name every new edge you add, or check fails on the one you left out.
JSON output
Every command accepts --json. Prefer it when scripting or reading output
programmatically: archkeel validate --json, archkeel init --json, archkeel report --json. Interactive terminals otherwise get a Rich-formatted summary instead of raw JSON.
Read declared_rules, not just exit 0: FAIL names violated constraints; UNKNOWN retains
unproved results. The command-result schema
covers init, check, validate and report, excluding skill and the observation artifact.
For completed init and observed validate results, open_decision_count is the exact total
and open_decisions_complete marks whether open_decisions lists every pair. init defaults
to observed crossings; validate defaults to the full list and offers
--compact-open-decisions for observed undecided crossings. Omitted pairs remain undecided;
an empty compact list with a positive total still needs decisions. draft_sizes records
each component's measured size only for init. Unavailable summaries remain null.
Use the CLI’s bundled schemas for offline validation; pin schema and CLI together.
In a checkout, schemas are under schema/. The installed distribution includes them under
archkeel/schema/. archkeel view check --help names the spec schema. Use a schema from the same
CLI version. Do not fetch a schema from the network for local validation.
04 同仓库更多 Skills
assets
暂无简介
explore
Use when the owner wants to see the codebase map in the browser ("show me the architecture", "open the explorer", "start Studio"), or to stop or reuse a running ArchKeel Studio.
explain-flow
Use when the owner wants a flow of this codebase explained as a story ("how does X run", "walk me through the flow of Y"), with every step checked against the code.
orders-domain
Use with the archkeel skill when reviewing or changing the orders service; supplies its domain invariants only.