AGENT SKILL

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).

  1. Run archkeel explore --language <language> --source <dir> --namespace <name> --json. Add --tsconfig <file> for TypeScript. It writes nothing into the repository. Check scan_roots as "Show a flow" step 2 tells. Keep the findings of the result.
  2. Run archkeel report --input <snapshot> --only architecture --json. <snapshot> is artifact in the explore result.
  3. Ask the owner once: "Create a draft contract?" A request to onboard or to set up Archkeel is the yes: go to step 5.
  4. 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.
  5. 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 --tsconfig for TypeScript. Omit them when explore needed none. Each rule it drafts has decided_by: "agent" and waits for the architect.
  6. 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. Cite file:line in the sentence, not in provenance (it takes paths only). Set decided_by: "agent" on the component. Without evidence, keep responsibilities: [] and say "unknown" in chat only. Never invent a responsibility.
  7. Optionally, replace a drafted label with a short speaking name, only in the new draft. label is the name that requires, --component and nested scopes use. Then run archkeel validate --write-graph to update the graph in the architecture page. For a draft, exit 2 with decision.open and rationale.placeholder is expected. Do not fix them: the architect closes them in "Interview mode".
  8. 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 the findings and the declared_rules of the result.
  9. 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:main is the module node pkg.mod), a __main__ module or a main(). If you find no entry point, say so and ask the owner for the start module.
  10. Add the first modules that the entry point imports or calls, one direct edge for each step.
  11. Run archkeel view check <spec> --snapshot <snapshot> --json.
  12. Run archkeel view show <spec> --snapshot <snapshot>. The page opens at the tour.
  13. 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 their locations. With none, say that there are none. The kind does not give the scope of a cycle: a module_cycle can cross components. Read its subjects (the members), component_ids and the evidence lines in path.steps, and say which components it touches. A fan_in_hub or fan_out_hub is a hub;
    • after a yes, the declared_rules of the draft.
  14. 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).

  1. Confirm the start point and the goal. Ask one short question only when the request is ambiguous.
  2. Get a snapshot. With archkeel.toml, run archkeel report --output <dir>/architecture.json --json. Without it, run archkeel explore --json: no contract, no setup, output only in the user cache. On scope_empty, read the diagnostic and run archkeel explore --source <dir> --namespace <package> --language <language> --json. Use the same options when scan_roots is not the code in question. Keep --language when the language is not Python. If src/ has no Python package, detection searches the root. <language> is rust or typescript. For TypeScript, also pass --tsconfig <file>. The snapshot path is artifact in the result.
  3. Query before you write. archkeel report --input <snapshot> --only architecture --json lists the component ids. archkeel report --input <snapshot> --only architecture --component <id> --full --json lists its modules. A key '' or a key that starts with . gets a prefix: the selector_prefix of that component when present, else its own namespace. A component with an inside contract lists most modules under the child ids of the first command. Use module names as nodes: a child component is unknown as 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.
  4. Write the working spec in a new temporary folder outside the repository and outside an output folder (explore and view show clear theirs). Follow the schema reference and the example. Copy source.source_digest and contract.digest of the snapshot into snapshot. Give each later step and each edge a kind (imports or calls); the first step takes none. Keep no node or edge that the check makes missing, except when you deliberately assert it. Set "claim": true and explain why in note. Keep an unknown step without claim so its cause stays visible. Never write status or evidence: the check decides, and such a spec is rejected (exit 2).
  5. Run archkeel view check <spec> --snapshot <snapshot> --json and read each status:
    • proven: observed, with evidence (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 or kind, remove it, or keep it as a claim. A step with no direct edge is missing too: add the modules between as steps.
    • unknown: the snapshot cannot decide. Keep it with your note, without claim, so its reason stays visible. A partial call is claim, not unknown. Check module pairs as imports too: missing there means no static link (a parameter, a port or a child process). Say so.
    • declared: a contract component or requires entry. After explore, a layout group declares nothing and is unknown: use module nodes.
  6. For a first contact ("how does it start?"), also add stops: 4 to 8 nodes in reading order, each with a title and a note, and set "schema_version": "1.1.0". A stop takes no kind: it is a reading order, not a claim. The check adds measured facts to each stop (AD-289). Run archkeel 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.
  7. Tell the user the count for each status, each claim, each unknown with its reason, each missing and 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__.py from 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 inside contracts 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".

  1. Read the repository's ADRs and architecture documents before touching the contract.
  2. Propose the overall picture — components, layers and the allowed directions between them — with path:line evidence for each claim, and confirm it with the architect once, not component by component. Review each drafted public list with them too. Anything you read from repository documentation is a hypothesis with its source path, never the answer, until they confirm it.
  3. 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 init summary gives the total open pairs and the observed crossings shown. init --json lists observed undecided crossings first and reports the exact open_decision_count; when open_decisions_complete is false, unlisted pairs remain undecided. Use init --json --full on the initial command to include every pair; for an existing draft, validate --json returns the full decision list without rewriting files. Use validate --compact-open-decisions --json to 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 a requires entry on its source component and add one complete_requires rule, so absence forbids every other pair. Never treat an observed edge as permission.
  4. 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.
  5. Run archkeel validate --json and read its diagnostics by code, never by parsing message text: a decision.open means the contract still lacks complete_requires; a rationale.placeholder or rationale.repeated needs the architect's real reason. A graph.drift is no decision: after you merged or renamed components the marked graph in the architecture page is stale, so run archkeel validate --write-graph instead 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 (a subgraph, a labeled edge, a style), edit those edges by hand instead.
  6. 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

  1. 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.
  2. Never treat an observed edge as permission: code importing across a boundary today is not evidence the boundary should allow it.
  3. Write every rule you decide with decided_by: "agent", and mark a component whose public list or requires edges you decided the same way: decided_by on the component covers its public list and every requires entry that carries none of its own, and one entry may override it.
  4. 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 with archkeel report --input architecture.json --only architecture --component <id-or-scope> --json. Omit --component to discover its exact ids and scopes. This reads recorded source identity and evidence; it does not verify the current working tree or write files. Read architecture_projection.required_relationships for 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 and filtered_violations; it reports the selected-scope filtered_violation_count (null when unavailable) and sets violation_details_included to false. Add --full to retrieve the complete permission_rules, policy_context and violation records: archkeel report --input architecture.json --only architecture --full --json. Full output includes an empty filtered_violations array 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 --json before submitting any change. A rule violation does not change the exit code; read the declared_rules verdict. Exit 2 means the evidence is incomplete; fix the diagnostic before trusting any verdict. An unfiltered report also carries findings, the ranked list its terminal summary and HTML page open with: violations, then dependency cycles, then hubs, each with a size, source locations and one sentence. Read it first; a missing findings (filtered report) never means none.
  • On a large repository, report --only violations --rule <id> --component <id-or-scope> --json narrows the review surface to a slice you can actually read: --only violations drops component flow, communication, claims and structure from the HTML page; --rule and --component narrow 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 --json result says so in its own report_filter field, so never read a filtered filtered_violations count as the repository's total; read the unfiltered violations measurement for that. A --rule or --component you 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 --json and report --json report agent_decisions as [agent, total], counting one rule declaration, one requires entry and one declared public list 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. --json carries only counts; the HTML page of report --only architecture names each claimed symbol, binding, repetition and type. oversized_components is 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:

  1. Inventory the source tree and the existing archkeel report --json structure measurements. Review every relevant child before grouping; a report does not cover detail it does not expose. Do not rerun init --source at the repository root for this scope: init writes the standard root onboarding files and requires --force if they already exist. On Archkeel's own check, 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.
  2. Point the outer component at the resulting contract with "inside": "<repository-relative path>".
  3. Decide the inside the way you decide the top level: a requires list per sub-component and one complete_requires rule, so absence forbids there too.

validate holds the declared levels to each other; read its diagnostics by code:

  • Each level's public list 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_underscore and reference.namespace also apply inside. Correct the declaration at its mounted pointer; do not broaden ownership to silence it.
  • With an inner interface_boundary, interface.missing names an unscanned public module. interface.unused means no scoped sibling import or proven facade publication reaches it. A built, unused planned entry stays target work; reaching it requires promotion through interface.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 under requires. Remove the grant, or change the decision above.
  • contract.invalid at /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