[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CR9C40NXJS28AVMER8CNCW":3,"skill-same:01M7CR9C40NXJS28AVMER8CNCW":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7CR9C40NXJS28AVMER8CNCW","archkeel",null,"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.","rapiddweller\u002Farchkeel","rapiddweller","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F47653827?v=4","01M7CR8QYZZSVFRW1KCSAB6RVG","01M7CR8QZHVZ9CSHWQWDJPBRJX",18,"MIT","https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fskills\u002Farchkeel\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: archkeel\ndescription: 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.\n---\n\n# Archkeel\n\nArchkeel is a deterministic architecture checker. Main observes Rust and TypeScript through native collectors, evaluates a\ndeclared contract of components and rules against that observation, and distinguishes\nPASS, FAIL and UNKNOWN. Rules live in `architecture-contract.json` and its explicit nested\ncontracts; nothing is enforced by convention alone.\n\nPython and Dart projects get verdicts only for import rules in this version; use archkeel 4.0.1 for the other rules.\nThe Rust core decides `validate` and `report`, and no other command runs in this version.\n`check`, `explore`, `init`, `guide`, `story`, `view` and `studio` give a typed refusal with exit 2.\nRelease 4.0.1 has `check` and `init`; no release has the other five commands.\nA refusal is not a result: do not report PASS after one.\nUnsupported profiles give exit 2 before collection, including saved facts and baseline commands.\nDo not report PASS for a supported subset of an unsupported project.\nIn a source checkout, run `make core` to build the core binary. There is no Python fallback.\n\nOn main, `report --output PATH` writes one static HTML page. Add `--format json` for the core frame.\nThere is no default file or sidecar. The parent must exist; final links and directories refuse with exit 2.\nAncestor links are resolved once. Empty, `.` and `-` output targets refuse before the scan.\nSafe file output requires POSIX directory handles. It keeps stdout and the frame exit unchanged.\nIf file delivery fails, stdout keeps the frame verdict but exit 2 replaces the verdict exit, including FAIL exit 1.\nUNKNOWN and collection-refused reports show their causes. A refusal without an accepted frame writes no file.\nThis is not `architecture.json`, a saved snapshot or a graph. The legacy report instructions below do not apply to main.\n`validate --output`, `--html`, saved-input and report-filter options remain refused.\n\n## First run on a codebase\n\nFor native Python parity work, use `--dump-proofs` for the import-local proof boundary (AD-404).\nIts empty provider proof sets do not prove member convergence or enable the production reply.\n\nIf `explore` reports `runtime_mismatch`, do not use its result as a complete scan. Read the\nreported current Python version and full `requires-python` range. Select a Python version that\nsatisfies that range, then retry with `uvx --python \u003Ccompatible-version> archkeel explore --json`.\nArchkeel does not install or switch Python versions.\n\nUse this procedure when a repository has no `archkeel.toml`. The first run gives the owner content\nfrom the measured code: how the system starts, an overview, and one sentence for each component.\nAfter the draft, continue with \"Onboarding\" below. When the owner wants to see the map in the\nbrowser, use the `explore` skill with the same scope options as `explore`. Studio is local and\nwrites nothing into the repository (AD-290).\n\n1. Run `archkeel explore --language \u003Clanguage> --source \u003Cdir> --namespace \u003Cname> --json`.\n   Add `--tsconfig \u003Cfile>` for TypeScript. It writes nothing into the repository. Check `scan_roots` as\n   \"Show a flow\" step 2 tells. Keep the `findings` of the result.\n2. Run `archkeel report --input \u003Csnapshot> --only architecture --json`.\n   `\u003Csnapshot>` is `artifact` in the explore result.\n3. Ask the owner once: \"Create a draft contract?\" A request to onboard or to set up Archkeel is\n   the yes: go to step 5.\n4. Without a clear yes, skip steps 5 to 8 and use the explore snapshot. Never write a contract or\n   another file into the repository. The views of steps 11 and 12 write only to the user cache.\n5. With a yes, run `archkeel init --source \u003Cdir> --namespace \u003Cpackage> --language \u003Clanguage> --json`.\n   Use the scope options of step 1 with the same values, also `--tsconfig` for TypeScript. Omit\n   them when `explore` needed none. Each rule it drafts has `decided_by: \"agent\"` and waits for\n   the architect.\n6. For each top-level component (about 10 at most), write one sentence as one list item in\n   `responsibilities`. Base it on the package docstring, the entry points and the imports of its\n   modules. Cite `file:line` in the sentence, not in `provenance` (it takes paths only). Set\n   `decided_by: \"agent\"` on the component. Without evidence, keep `responsibilities: []` and say\n   \"unknown\" in chat only. Never invent a responsibility.\n7. Optionally, replace a drafted `label` with a short speaking name, only in the new draft.\n   `label` is the name that `requires`, `--component` and nested scopes use. Then run\n   `archkeel validate --write-graph` to update the graph in the architecture page. For a draft,\n   exit 2 with `decision.open` and `rationale.placeholder` is expected. Do not fix them: the\n   architect closes them in \"Interview mode\".\n8. Run `archkeel report --output \u003Ctmp>\u002Farchitecture.json --json`, with `\u003Ctmp>` outside the\n   repository. The draft changed the contract digest: this file is now `\u003Csnapshot>`. Keep the\n   `findings` and the `declared_rules` of the result.\n9. Write a \"get started\" view spec with steps and stops, as \"Show a flow\" steps 3, 4 and 6\n   tell. Start at each entry point: a `[project.scripts]` target (`pkg.mod:main` is the module\n   node `pkg.mod`), a `__main__` module or a `main()`. If you find no entry point, say so and\n   ask the owner for the start module.\n10. Add the first modules that the entry point imports or calls, one direct edge for each step.\n11. Run `archkeel view check \u003Cspec> --snapshot \u003Csnapshot> --json`.\n12. Run `archkeel view show \u003Cspec> --snapshot \u003Csnapshot>`. The page opens at the tour.\n13. Give the owner an overview in chat:\n    - each top-level component with its name and its sentence, or \"unknown\";\n    - the start flow, each step with its status mark;\n    - up to 3 weak spots from the latest `findings` (step 8 after a yes, else step 1), with their\n      `locations`. With none, say that there are none. The kind does not give the scope of a\n      cycle: a `module_cycle` can cross components. Read its `subjects` (the members),\n      `component_ids` and the evidence lines in `path.steps`, and say which components it touches.\n      A `fan_in_hub` or `fan_out_hub` is a hub;\n    - after a yes, the `declared_rules` of the draft.\n14. Offer the next step: define a target together, then compare it in the Target and Diff views.\n\n## Show a flow\n\nWhen the user asks \"show me the flow of X\", answer with a checked view, not with text only.\nA view spec is author text; the check in step 5 decides what the code proves (AD-284).\n\n1. Confirm the start point and the goal. Ask one short question only when the request is ambiguous.\n2. Get a snapshot. With `archkeel.toml`, run `archkeel report --output \u003Cdir>\u002Farchitecture.json --json`.\n   Without it, run `archkeel explore --json`: no contract, no setup, output only in the user cache.\n   On `scope_empty`, read the diagnostic and run\n   `archkeel explore --source \u003Cdir> --namespace \u003Cpackage> --language \u003Clanguage> --json`.\n   Use the same options when `scan_roots` is not the code in question. Keep `--language` when\n   the language is not Python. If `src\u002F` has no Python package, detection searches the root.\n   `\u003Clanguage>` is `rust` or `typescript`. For TypeScript, also pass `--tsconfig \u003Cfile>`.\n   The snapshot path is `artifact` in the result.\n3. Query before you write. `archkeel report --input \u003Csnapshot> --only architecture --json` lists\n   the component ids. `archkeel report --input \u003Csnapshot> --only architecture --component \u003Cid> --full --json`\n   lists its `modules`. A key `''` or a key that starts with `.` gets a prefix: the\n   `selector_prefix` of that component when present, else its own `namespace`. A component with an `inside` contract lists most modules under the child ids\n   of the first command. Use module names as nodes: a child component is `unknown` as a node.\n   Use module nodes for import checks; function nodes support calls only. Source text names\n   candidates, not proof. Read the evidence lines from the check.\n4. Write the working spec in a new temporary folder outside the repository and outside an output\n   folder (`explore` and `view show` clear theirs). Follow the [schema reference](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fschema\u002Fview-spec.schema.json)\n   and the [example](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Ffixtures\u002FF-architecture-view\u002Fplace-order.json).\n   Copy `source.source_digest` and `contract.digest` of the snapshot into `snapshot`. Give each\n   later step and each edge a `kind` (`imports` or `calls`); the first step takes none.\n   Keep no node or edge that the check makes `missing`, except when you deliberately assert it.\n   Set `\"claim\": true` and explain why in `note`. Keep an `unknown` step without `claim` so its\n   cause stays visible.\n   Never write `status` or `evidence`: the check decides, and such a spec is rejected (exit 2).\n5. Run `archkeel view check \u003Cspec> --snapshot \u003Csnapshot> --json` and read each status:\n   - `proven`: observed, with `evidence` (`file`, `line`). Read those lines: a module edge can\n     come from another function. Only one direct edge of its kind proves a step.\n   - `missing`: not in the code. Fix the node or `kind`, remove it, or keep it as a claim. A step\n     with no direct edge is `missing` too: add the modules between as steps.\n   - `unknown`: the snapshot cannot decide. Keep it with your note, without `claim`, so its\n     reason stays visible. A partial call is `claim`, not `unknown`. Check module pairs as `imports` too:\n     `missing` there means no static link (a parameter, a port or a child process). Say so.\n   - `declared`: a contract component or `requires` entry. After `explore`, a layout group\n     declares nothing and is `unknown`: use module nodes.\n6. For a first contact (\"how does it start?\"), also add `stops`: 4 to 8 nodes in reading order,\n   each with a `title` and a `note`, and set `\"schema_version\": \"1.1.0\"`. A stop takes no `kind`:\n   it is a reading order, not a claim. The check adds measured facts to each stop (AD-289).\n   Run `archkeel view show \u003Cspec> --snapshot \u003Csnapshot>`. Stderr names the page. Without stops\n   it opens at the flow; with stops it opens at the tour.\n   Tell the user to open it: `open \u003Cpage>` on macOS, `xdg-open \u003Cpage>` on Linux.\n7. Tell the user the count for each status, each claim, each `unknown` with its reason, each\n   `missing` and each change after the first check. Say: \"proven means structure of the code (an\n   observed import or call), not runtime order.\"\n\nA graph path is not an execution trace. An import proves only that one module imports the other.\nWithout a contract the result has `target: unavailable` and `declared_rules: UNKNOWN`, never PASS.\nYour explanation is your own text, without authority. Never change source or contract for a view.\nThe `explain-flow` skill stores the final checked story under `.archkeel\u002Fstories\u002F` as reviewed\ndocumentation (AD-291). This specific exception does not allow other drafts or evidence in Git.\n\n## Onboarding (first time in this repository): a target, not a description\n\n`architecture-contract.json` is the target architecture — where the system should be, not\nwhere the code already is. `archkeel report` measures declared constraints, not the quality\nof the whole architecture. The architect owns the target and review scope; within that scope,\ninspect the physical structure at every depth, not just the top level. Support them with evidence\nfrom the repository and the architect's quality goals for this codebase (which components\nmust scale, stay easy to change, or are performance-critical). Read those goals from ADRs\nand architecture documents first; ask the architect only when a goal is unknown and would\nchange your recommendation. Every\nrecommendation and every rationale cites the goal it rests on. There is no contract field\nfor a quality goal: record it next to the rule it justifies, following the chosen decision\nmode below.\n\nOn a repository without `archkeel.toml`, start with \"First run on a codebase\": a request to\nonboard is its yes, so `explore` comes first and `init` follows at its step 5.\nFor requested first-time onboarding, inspect existing files, then run\n`archkeel init [--root DIR] [--source DIR] [--namespace NAME] [--force] [--json]` once.\nA read-only assessment uses existing contracts, reports and source; it does not authorize\ninitialization, contract edits, file moves or commits.\nPreserve existing contracts and their `inside` references. If onboarding files already exist,\ncontinue from them; do not use `--force` without explicit approval to replace those files.\n`init` checks `src\u002F` for Python packages first. If it finds none, it checks the repository root.\nIn the selected directory, it uses the only top-level package or the package named by\n`pyproject.toml`'s `[project] name` when test packages sit beside it. Otherwise it exits 2 and\nasks for `--source` and `--namespace`. It also requires an existing Git repository with at least\none commit, and writes three files: `archkeel.toml`, `architecture-contract.json` (one component\nper top-level subpackage\u002Fmodule, plus `complete_assignment` and — only when no component\ncycle exists — `no_component_cycles`, and `interface_boundary` when it drafts public\ninterfaces; no dependency rule), and\n`docs\u002Farchitecture\u002Farchitecture.md` (component table, each component's modules and inner\nedges, and a Mermaid graph of observed edges).\nEvery rule `init` drafts carries `decided_by: \"agent\"` as a placeholder you must resolve, not\nan answer, and so does every component whose `public` list it drafted. It refuses to overwrite existing files without `--force`.\n\n`init` does not infer a foundation or decide where classes belong. Ask who owns a shared type\nfirst; foundation is not the default owner for domain enums or models. Record the architect's\nchoice with the existing `symbol_placement` rule: set `source` to the package, `class_kinds` to\nthe types it owns, and `exact_sources` to the chosen module (or `allowed_sources` to a package\nsubtree). Follow the ownership example in the [target-first guide of release 4.0.1](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002F4.0.1\u002Fdocs\u002Ftarget-first.md). Run `archkeel validate` after\nadding it; a misplaced matching class is a `rule.violated`.\n\nFor TypeScript, use `archkeel init --language typescript --source src --namespace app\n--tsconfig tsconfig.json`; for Dart, use `archkeel init --language dart --source lib\n--namespace app`. Repeat `--source` for multiple roots. A non-empty namespace initializer\nrequires explicit ownership via `exact_modules`; inspect it before recording the owner.\n`init` shows DRAFT while its completed scan remains PASS. Review measured\n`measurements.scalars.cycle_edges`: a cyclic component graph receives no drafted\n`no_component_cycles` rule. Cycles are an advisory, not an error diagnostic.\nIgnore `\u002Ftest-artifacts\u002F` in `.gitignore` for default report output, or choose `--output`.\nRestore missing configuration in existing setups or select `--config PATH`; use `init`\nonly for a new setup. Without Git history, run `git init` and create a commit first.\n\nFor example, after defining storage's responsibility and approving `storage -> domain`,\nadd this fragment to the existing `storage` component. Replace the example reason with\nthe decision owner's actual reason; keep its existing ownership and public interface fields.\n\n```json\n{\n  \"responsibilities\": [\"Persist and retrieve domain records.\"],\n  \"decided_by\": \"architect\",\n  \"requires\": [\n    {\n      \"component\": \"domain\",\n      \"rationale\": \"Storage persists domain records.\",\n      \"decided_by\": \"architect\"\n    }\n  ]\n}\n```\n\nAppend this rule to the existing `rules` list. An empty or absent `requires` list then\nforbids all outbound component pairs; it does not grant observed imports.\n\n```json\n{\n  \"id\": \"REQUIRES-COMPLETE\",\n  \"kind\": \"complete_requires\",\n  \"rationale\": \"Each source states its approved outbound dependencies.\",\n  \"provenance\": [\"docs\u002Farchitecture\u002Farchitecture.md\"],\n  \"decided_by\": \"architect\"\n}\n```\n\nReview drafted `public` entries and replace each structural rule's TODO with its own real\nreason and decision author. A non-empty namespace initializer needs explicit ownership via\n`exact_modules`; inspect it before adding that ownership. Rule kinds and selectors are in\nthe [rule catalog](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Frules.md).\n\nWhen an API role must declare a canonical port, use contract 3.9.0's\n`protocol_declarations`. Select a source scope plus exact `parameter` or annotated class\n`member` names and visibility; this includes future declarations. The canonical dotted\n`protocol` must resolve to a scanned Protocol. An optional selector permits only that Protocol\nwith `None`; broader unions, missing annotations, `object`, and `Any` fail. Statically\nproven single-name `TypeAlias` chains resolve to their target; unsupported alias shapes,\nincluding union-valued aliases, remain UNKNOWN. Shadowed and unresolved names also remain\nUNKNOWN. MyPy checks assignability, and the rule does not replace structural conformance review.\n\nThen pick one of two modes. The architect chooses; do not choose for them.\n\n### Physical structure review (both modes)\n\nAfter `init`, and during architecture assessments, inspect every maintained source package\nin scope recursively down to leaf packages, whether or not it has an `inside` contract.\nThe generated inventory and a green contract are not evidence that this structure is good.\n\n- Count direct source modules and immediate subpackages at each level; exclude `__init__.py`\n  from this count, not from ownership, behavior or dependency review. Record excluded generated\n  or vendored trees.\n  More than seven direct children triggers a review, not an automatic split or a failing\n  rule. Five to seven understandable groups is a review heuristic, not a cognitive law.\n- Challenge mixed responsibilities, unclear names, oversized leaf modules, excessive\n  nesting, cycles and cross-package coupling even below that threshold. Trace entry points\n  and data flow before choosing boundaries; check who owns shared types and public interfaces.\n  Follow one real operation through business logic, state\u002Fexternal effects and its observable\n  result. For each layer, name its invariant, failure mode and what breaks if removed.\n- Review changed APIs against a concrete caller purpose: named operation\u002Ftype, typed inputs\n  and result, errors, and state\u002Fresource\u002Ftransaction lifetime. Assess test-only helpers and\n  dynamic discovery separately; discovery needs a real caller\u002Fprotocol, not an invented import.\n  Recommend delete\u002Fsimplify\u002Fkeep for redundant wrappers, duplicate knowledge owners, brittle\n  string dispatch and reflection\u002Fcoercions hiding incorrect models. Candidates are review\n  work, never automatic deletion or a semantic PASS.\n- Propose physical packages around cohesive responsibilities, not arbitrary groups of seven\n  or diagram-only clusters. Compare the current and target tree and allowed dependency\n  directions. Keep a cohesive larger package when splitting only adds navigation or coupling;\n  do not hide the excess in `misc`, `utils`, single-child wrappers or re-export barrels.\n- For uncertain boundaries, give the architect a recommended option, alternatives, evidence,\n  trade-offs and system-wide impact. Follow the chosen decision mode; reviewing structure\n  does not authorize moving files or changing behavior.\n- Record review coverage and unresolved decisions in the response; when the task includes an\n  architecture-document update, keep the durable record there: reviewed subtree, finding or\n  keep-rationale, target change, and enforcement gap. Mark unreviewed subtrees explicitly;\n  never present a partial review as a complete assessment.\n  Distinguish declared ownership from semantic cohesion. Give reviewed leaf modules a concrete\n  purpose under their nearest deliberate owner using supported declarations; generic parent\n  prose is insufficient. Link unsupported semantic judgments to source evidence, not a second\n  inventory. Each finding states source location, impact, delete\u002Fsimplify\u002Fkeep decision and UNKNOWNs.\n  Add `inside` contracts at meaningful independently governed boundaries, not at every folder.\n  Encode approved constraints with supported rules. Deeper review remains necessary when\n  the installed version cannot enforce nested contracts; do not invent unsupported rules.\n\nProject skills supply domain invariants and deployment facts without copying this process.\nKeep execution\u002FQA scheduling in the execution workflow. Follow the existing decision\u002Fdelegation\nscope; this review does not add a confirmation per component. When delivering a report, smoke-test\nactual and declared nested navigation and module\u002Fsource links from its packaged artifact,\nincluding companion files. Missing declarations and broken navigation are different findings.\n\n### Interview mode: the architect decides, you ask\n\nNever write a rationale or choose an allowed direction yourself; ask, and write down the\narchitect's own words as the `rationale`, with `decided_by: \"architect\"`.\n\n1. Read the repository's ADRs and architecture documents before touching the contract.\n2. Propose the overall picture — components, layers and the allowed directions between them\n   — with `path:line` evidence for each claim, and confirm it with the architect once, not\n   component by component. Review each drafted `public` list with them too. Anything you\n   read from repository documentation is a hypothesis with its source path, never the\n   answer, until they confirm it.\n3. After that confirmation, ask only about conflicts (the code contradicts a document) and\n   gaps (the documents are silent). Each question names the recommended option first, with\n   its evidence. The `init` summary gives the total open pairs and the observed crossings shown.\n   `init --json` lists observed undecided crossings first and reports the exact\n   `open_decision_count`; when `open_decisions_complete` is false, unlisted pairs remain\n   undecided. Use `init --json --full` on the initial command to include every pair; for an\n   existing draft, `validate --json` returns the full decision list without rewriting files.\n   Use `validate --compact-open-decisions --json` to retrieve observed undecided crossings\n   with the exact total and completeness instead; omitted pairs remain undecided and UNKNOWN\n   evidence stays UNKNOWN. The flag changes no verdict, diagnostic or contract decision.\n   Batch everything consistent\n   with the confirmed picture into one confirmation. Then encode each allowed direction as a\n   `requires` entry on its source component and add one `complete_requires` rule, so absence\n   forbids every other pair. Never treat an observed edge as permission.\n4. When the architect chooses against your recommendation, ask why before writing the rule.\n   Always ask when the choice contradicts a document, an earlier decision in this interview,\n   or the code you observed. Write their answer as the `rationale`.\n5. Run `archkeel validate --json` and read its diagnostics by `code`, never by parsing\n   message text: a `decision.open` means the contract still lacks `complete_requires`; a\n   `rationale.placeholder` or `rationale.repeated` needs the architect's real reason. A\n   `graph.drift` is no decision: after you merged or renamed\n   components the marked graph in the architecture page is stale, so run\n   `archkeel validate --write-graph` instead of editing it by hand; it rewrites only that\n   graph's edges. When the remedy says the graph holds structure the command does not rewrite\n   (a `subgraph`, a labeled edge, a style), edit those edges by hand instead.\n6. When the architect delegates a choice (\"whatever is consistent\" or similar), derive it\n   only from their earlier decisions in this interview, never from your own judgment. Label\n   the rationale agent-derived in your summary to the architect and list it for them to\n   confirm before it counts as decided.\n\n### Auto mode: the agent decides every allowed direction\n\n1. Decide every allowed direction yourself, in this evidence order: documents first, then the\n   layer principles the architect already confirmed or the documents state, then your own\n   judgment, labeled as judgment in the rationale.\n2. Never treat an observed edge as permission: code importing across a boundary today is not\n   evidence the boundary should allow it.\n3. Write every rule you decide with `decided_by: \"agent\"`, and mark a component whose\n   `public` list or `requires` edges you decided the same way: `decided_by` on the component\n   covers its `public` list and every `requires` entry that carries none of its own, and one\n   entry may override it.\n4. End with a summary of your decisions grouped by evidence basis (document, layer\n   principle, judgment) and name the lowest-confidence decisions first, for the architect to\n   review.\n\nA later interview on an auto-mode contract asks the architect only about rules, entries and\ncomponents with `decided_by: \"agent\"`; an `architect`-decided one is already closed and is not\nreopened.\n\n### Ending onboarding, either mode\n\nBefore ending, record the physical structure review and any deferred subtrees or decisions;\na closed dependency contract alone does not complete the architecture assessment.\nThe dependency interview (or auto-mode pass) ends when `complete_requires` closes the\ndependency set and `validate --json` reports none of `decision.open`, `rationale.placeholder` or\n`rationale.repeated` — not when the command exits 0. A `rule.violated` diagnostic is the\narchitecture's own finding, not an onboarding step: the code still uses an edge the target\nomits. Show it to the architect with `archkeel report`. They resolve it by changing the code or\nchanging the target; the agent never does that itself and never loops `validate --json` waiting\nfor exit 0.\n\nOnce it ends, run `archkeel report`. Include the generated files (`archkeel.toml`,\n`architecture-contract.json`, `docs\u002Farchitecture\u002Farchitecture.md`) when they are part of the\nrequested change. A remaining `rule.violated` is follow-up code work, tracked separately from\nonboarding.\n\nWhere that follow-up is long — a contract that states the target architecture the code has\nyet to reach — freeze the known violations instead of weakening the contract:\n\n```bash\narchkeel validate --baseline known-violations.json --write-baseline   # once, then review it\narchkeel validate --baseline known-violations.json                    # the CI gate\n```\n\n`--baseline` and `--amendment` are relative to `--root`, like the contract: with `--root mobile`,\npass `--baseline known-violations.json` for `mobile\u002Fknown-violations.json`, never the\n`mobile\u002F`-prefixed path. An absolute path inside the root works; one outside it is\n`baseline.invalid`, exit 2.\nThe gate fails (exit 1) on a violation the file does not state, and on one it states that\nnobody violates any more — so the budget only shrinks, and the file is rewritten in the same\nchange that shrinks it. `declarations.measurement_budgets` may put deterministic scalar values\nthrough the same loop. `declarations.facade_budgets` and\n`declarations.coupling_budgets` set name targets in the contract, and the baseline holds their\naccepted names.\nNever raise any of them to make a run pass without the architect's decision.\nWhen `calls_unresolved` rises, rerun with `--against \u003Cbase ref>`, as the\nfinding says: `unresolved_call_changes` names each added and removed unresolved call with its\ncaller, path, lines, expression, reason and component. `report --only calls --json` lists every\nunresolved and partially resolved call as `filtered_calls`; add `--component \u003Clabel>` for one\ncomponent's calls.\n\nA reviewer or a CI gate may hold your branch to this the same way, with `archkeel validate\n--against \u003Cbase ref>`: it classifies every difference from the contract at that revision — a\nnew `requires` edge, a `public` entry, an `allowed_sources` module, a relaxed or deleted rule,\na padded baseline entry, and anything else this repository's `ir.widening` does not otherwise\nname — as a widening, which fails (exit 1) unless `--amendment \u003Cpath>` names a file the\narchitect wrote, recording who decided it and why, bound to this exact change.\nIn `validate --json`, `widenings` is `null` when `--against` was not checked, otherwise it lists\nunamended widenings with `code: \"ir.widening\"`, `subject` and `field`; `failures` keeps the\nhuman-readable messages. `amendment_status` is `valid` or `stale` when a supplied amendment was\nchecked, and `null` otherwise. A valid amendment may leave `widenings` empty even when it accepts\na real change.\nNever widen the contract in the same change that removes the violation it names: fix the code,\nor ask the architect for an amendment. The full loop — gating, widening, picking a slice of the\nbacklog and landing a planned interface — is worked end to end on the shop sample in\nhttps:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002F4.0.1\u002Fdocs\u002Ftarget-first.md.\n\n## Retiring local dependency gates\n\nUse native dependency policy for proven Python literal loaders as well as static\nimports. Binding mutation, unknown targets and nonempty builtin fromlists retain\nscoped UNKNOWN evidence. A dependency edge does not prove a public value API.\nBefore deleting a local scanner, compare its forbidden, allowed and missing-scope\ninputs against the installed release, including aliases and dynamic forms. A source\ncheckout or Draft PR is not proof that the installed release supports them.\n\nUse `call_owner` only where its installed observer proves the complete selected\ncall scope. Observation 2.4 adds bounded proofs for stored typed receivers,\nstable default constructions, and selected native targets (`random`,\n`secrets.token_hex`, and CPython `datetime.datetime.now`). Inheritance is followed\nonly through a unique recorded base path. Dynamic dispatch, custom allocation,\nunsupported mutation, and native APIs without an admitted provider witness remain\nUNKNOWN. The datetime witness inspects the isolated collector runtime’s stdlib\ndescriptor and source digest; it does not import project modules. Arguments and\nguards are not proved by this change. Check the rule receipt and supported forms\nbefore retiring any method-name scanner. Older readers must reject observation\n2.4 rather than omit the added proof vocabulary; current readers continue to\naccept historical observations.\n\nContract 3.8 `bounded_numeric_operand` checks selected Python `%` and `%=` sites\nby written terminal identifier suffix. Only bounded integer\u002FBoolean literals,\nunary signs, powers and unique preceding aliases prove values. Review its source\nevidence: each operation and alias must fit a replayable single-line excerpt\nof at most 16,384 characters; single-line `if`, `elif`, `while`, `for`, `with`,\nfunction and class headers and inline suites are supported with Python indentation. Multiline\nor otherwise incomplete evidence remains UNKNOWN. Review the source\nreceipt and UNKNOWNs; it does not establish runtime types, reachability, entropy\nor collision freedom. Empty\u002Fmissing selected scope is UNKNOWN. See\n[AD-246](..\u002F..\u002Fdocs\u002Farchitecture\u002Fdecisions\u002Fad-246-bounded-numeric-operand.md)\nand [rule limits](..\u002F..\u002Fdocs\u002Fknown-limits.md).\n\nUse `forbidden_call_argument` to select one written-literal policy\nfor a canonical target's formal parameter. It binds explicit source actuals to\nthe observed signature; spreads, invalid bindings, missing signatures and\nunproven targets leave UNKNOWN. Calls without canonical binding carry null\nargument facts; a proven call with no actuals carries an empty list. It does not check runtime type compatibility\nor apply omitted defaults. Check the rule receipt and supported forms before\nretiring any method-name scanner. Argument facts require observation 2.5 and\ncontract 3.10; older readers must reject that evidence. The current reader\ncontinues to accept historical observation formats.\n\nUse `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.\n\nUse `source_ownership` for Python-local policy over source roles. In `retired` mode,\nselect `symbols` and roles `definition`, `read`, `write` and\u002For `delete`. In `confined`\nmode, select `symbols` plus `owner`, or formal `parameters` plus `value_owner`; choose\nroles `value_transfer`, `parameter_default` and `fallback` only when the observer can\nlink each value to admitted source evidence. Unsupported or ambiguous expressions remain\nUNKNOWN. This rule is available with contract 3.12 and observation 2.7; older readers\nmust reject those formats rather than silently ignore the rule or role facts. See\n[AD-249](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Farchitecture\u002Fdecisions\u002Fad-249-source-ownership-defaults.md)\nand the [rule catalog](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Frules.md).\nUse `forbidden_construct.selector` when a policy must select one nominal\nreceiver\u002Fmember and access or comparison role. Contract 3.11 and observation\n2.6 enable the Python slice: annotated direct member reads, positional literal\nreflection names, selected local constructors and type probes, literal equality\nin either direction, membership, `match`, and `startswith`\u002F`endswith`.\nDynamic names, unannotated or ambiguous receivers and missing selected subjects\nremain UNKNOWN. Other language profiles do not claim selector support. See\n[AD-248](..\u002F..\u002Fdocs\u002Farchitecture\u002Fdecisions\u002Fad-248-construct-selectors.md) and\nthe [rule grammar](..\u002F..\u002Fdocs\u002Frules.md#interfaces-and-types).\n`forbidden_effect_under_condition` is a static ownership rule. It can prove a declared\nBoolean parameter\u002Fmember through truth, negation, `if`\u002F`else`, ternary and early\n`return`\u002F`raise`, plus one unique private helper with signature-bound actuals. A known\nunconditional effect is reachable while the condition is true. Reassignment, named\nexpressions, short-circuiting, loops, `try`\u002F`finally`, reflection and helper chains or\nrecursion remain UNKNOWN. Inspect the rule receipt and path evidence before relying on\nPASS; see [AD-250](..\u002F..\u002Fdocs\u002Farchitecture\u002Fdecisions\u002Fad-250-bounded-guarded-effect-ownership.md).\n\n## Daily loop\n\nValidation reports `responsibility.missing` only for components explicitly marked\n`decided_by: \"architect\"` with no non-whitespace responsibility text. It checks declaration\npresence, not prose quality or complete coverage of cross-cutting concerns; an agent draft stays\nusable and incomplete until the architect decides it.\nContract text with `decided_by: \"architect\"` wins over agent text. Text with `decided_by: \"agent\"`\nis a draft: revise it only on request, and show the difference in chat.\n\n- Start with `archkeel report --only architecture --json`. It projects authenticated intent,\n  ownership, dependency permissions, observed use and required Target relationships. Use\n  `--component \u003Cid-or-scope>` for a slice; global verdicts, coverage and uncertainty remain.\n  Missing evidence is UNKNOWN. Permissions never prove use or required execution.\n  After one scan, query that packet with `archkeel report --input architecture.json --only architecture\n  --component \u003Cid-or-scope> --json`. Omit `--component` to discover its exact ids and scopes.\n  This reads recorded source identity and evidence; it does not verify the current working\n  tree or write files. Read `architecture_projection.required_relationships` for Target intent.\n  For findings, query the same packet with\n  `--only violations --component \u003Cid-or-scope> --json`; add `--rule \u003Cid>` to intersect.\n  The compact query omits module lists, policy detail and `filtered_violations`; it reports\n  the selected-scope `filtered_violation_count` (`null` when unavailable) and sets\n  `violation_details_included` to `false`. Add `--full` to retrieve the complete\n  `permission_rules`, `policy_context` and violation records: `archkeel report --input\n  architecture.json --only architecture --full --json`. Full output includes an empty\n  `filtered_violations` array when the measured selected scope has no findings.\n- Revisit the physical structure review for changed packages and their parent boundaries;\n  recheck related findings rather than repeating a whole-repository review for every edit.\n- Run `archkeel report --json` before submitting any change. A rule violation does not\n  change the exit code; read the `declared_rules` verdict. Exit 2 means the evidence is\n  incomplete; fix the diagnostic before trusting any verdict. An unfiltered report also\n  carries `findings`, the ranked list its terminal summary and HTML page open with:\n  violations, then dependency cycles, then hubs, each with a `size`, source `locations` and one\n  `sentence`. Read it first; a missing `findings` (filtered report) never means none.\n- On a large repository, `report --only violations --rule \u003Cid> --component \u003Cid-or-scope> --json`\n  narrows the review surface to a slice you can actually read: `--only violations` drops\n  component flow, communication, claims and structure from the HTML page; `--rule` and\n  `--component` narrow the violations table further and combine as an intersection.\n  This includes local Target findings and descendants, plus crossings touching either side.\n  Top-level labels take precedence over identical nested labels. This changes only what is\n  shown - `declared_rules`, the violation counts and the exit code stay computed from every\n  violation - and a filtered `--json` result says so in its own `report_filter` field, so never\n  read a filtered `filtered_violations` count as the repository's total; read the unfiltered\n  `violations` measurement for that. A `--rule` or `--component` you misspelled is a named exit\n  2, not a silently empty page.\n- If a rule fails, fix the code so the rule passes.\n- Never weaken or delete a rule just to make a violation disappear, unless the component\n  owner explicitly approves the change to the contract. A silently loosened rule hides the\n  next real violation.\n- `validate --json` and `report --json` report `agent_decisions` as `[agent, total]`, counting\n  one rule declaration, one `requires` entry and one declared `public` list alike; a nonzero\n  first value means an auto-mode contract still awaits an architect interview on those\n  decisions.\n- The same two commands report `claims`, the Class D review claims. They never change a\n  verdict or an exit code; bring a nonzero count to the architect as reading work, and never\n  delete code because a claim named it. `--json` carries only counts; the HTML page of\n  `report --only architecture` names each claimed symbol, binding, repetition and type.\n  `oversized_components` is a compatibility count, not a claim (AD-235); read component\n  sizes in the Structure overview instead.\n\n## Nested contracts: the inside of a component\n\nA component may name a contract of its own, which becomes a second level of the same\narchitecture. Adding one is the architect's decision; inspecting the physical\nsubtree is already part of the recursive review above and does not depend on that decision. A\ncomponent that holds more modules than the whole top level, as the Structure overview shows, is\na reason to ask, not permission to split (AD-235).\n\nOnce the architect decides:\n\n1. Inventory the source tree and the existing `archkeel report --json` structure measurements.\n   Review every relevant child before grouping; a report does not cover detail it does not\n   expose. Do not rerun `init --source` at the repository root for this scope: `init` writes the\n   standard root onboarding files and requires `--force` if they already exist. On Archkeel's\n   own `check`, a per-module draft produced 12 sub-components and 132 open decisions where the\n   three layers the architect settled on need 6. Consolidate into a few layers with the architect\n   before deciding a single pair.\n2. Point the outer component at the resulting contract with\n   `\"inside\": \"\u003Crepository-relative path>\"`.\n3. Decide the inside the way you decide the top level: a `requires` list per sub-component and\n   one `complete_requires` rule, so absence forbids there too.\n\n`validate` holds the declared levels to each other; read its diagnostics by `code`:\n\n- Each level's `public` list serves that boundary. Child APIs stay local unless the parent\n  explicitly publishes them or a proven facade reexport. Do not copy every child API upward.\n- `reference.public_owner`, `reference.public_underscore` and `reference.namespace` also apply\n  inside. Correct the declaration at its mounted pointer; do not broaden ownership to silence it.\n- With an inner `interface_boundary`, `interface.missing` names an unscanned public module.\n  `interface.unused` means no scoped sibling import or proven facade publication reaches it.\n  A built, unused planned entry stays target work; reaching it requires promotion through\n  `interface.planned_built`, not automatic permission. Publisher evidence belongs to the exact\n  parent scope, including proven re-export chains. Unknown import names are not proof of non-use.\n- `inside.forbidden_import` — the inside grants an edge the level above forbids the component,\n  by a rule or by absence under `requires`. Remove the grant, or change the decision above.\n- `contract.invalid` at `\u002Fcomponents\u002F\u003Cn>\u002Finside` — the file is missing, outside the repository,\n  or does not parse on its own.\n\n`report` evaluates `complete_requires` a second time against the inside, over the imports the\nouter scan already collected, so a crossing between two sub-components that no `requires` entry\ncovers is a violation like any other, and the flow view opens that component into its\nsub-components before its modules. Such a finding names the rule as `\u003Ccomponent>:\u003Crule id>`,\nfor example `store:STORE-REQUIRES-COMPLETE`: the id you will find in the inside contract is the\npart after the colon, and the part before it is the component that names that contract. Resolve\nit according to the target decision: update the inside `requires` only for an architect-approved\ncrossing; otherwise change the code. Do not add a rule above to hide an inside crossing.\n\nExplicit `inside` references are followed recursively and use the shared rule evaluators.\nMounting a contract does not create a standalone `archkeel.toml` for it. Nonempty inside\n`declarations` fields remain unsupported and are refused. An inner `external_dependency_scope`\ndeclaration is not compared with ancestor declarations; ancestor rules still evaluate their\nown source scope. A physical folder alone is not a declared contract.\n\n## Maintaining a nested contract\n\nUse the saved architecture projection with `--component \u003Cid-or-scope> --full`. Read the owner's\npurpose\u002Fexclusions, deliberate API, dependency reasons and ancestor\u002Fchild `policy_context`.\nFill missing context from the canonical mounted contracts and source; mark absent evidence.\nBind the review to the source revision, contract\u002Fanalyzer identities and installed CLI version.\nValidation catches supported reference, ownership and stale-declaration errors; it does not\njudge whether responsibility prose is good.\n\nFor each edit, record affected scopes\u002Fdeclarations, focused\u002Ffull input bytes, logical edit\nfiles\u002Fsites, and before\u002Fafter ownership, API and permissions. Edit size is maintenance evidence,\nnot an architecture verdict or a pass threshold. Run `validate --against \u003Caccepted-ref>` and\nuse the existing bound amendment for approved widening; never regenerate intent from imports.\nIts `contract_changes` list each change as widened or narrowed; only widenings need the\namendment, and a tightened `requires` entry narrows. Narrowings cover `requires`, `public` and\nrule presence only; anything else is not enumerated.\n\nThe [checkout fixture](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Ftree\u002Fmain\u002Ffixtures\u002FH-uml-dart)\nhas `ordering -> domain -> orders\u002Fpricing` boundaries. Try these changes independently:\n\n| Change | Deliberate edit sites | Control |\n| --- | --- | --- |\n| Move `discount_policy` from pricing to orders | Source path; domain owner\u002Fpublic\u002Fmodule 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. |\n| Rename persistence API `findById` to `find` | Implementation\u002Fcaller and the two existing nested signature targets. | Return-type drift fails; changed Target requires its bound amendment. |\n| Remove unused pricing-to-orders permission | The existing nested `requires` entry. | The same import passes before tightening and fails after it. |\n\nReview the resulting owner from the same saved packet:\n\n```bash\narchkeel report --input architecture.json --only architecture --component ordering:domain:orders --full --json\n```\n\nFor this example, a project adapter supplies only domain invariants such as \"orders own\nlifecycle; adapters own persistence\". Trace checkout through the persistence port to the\nobservable receipt; keep cohesive larger packages when a split adds only indirection.\nAn unused public helper needs a caller justification; a dynamically selected collector entry\nneeds its actual process\u002Fprotocol evidence. Neither import counts nor generic leaf prose settle\nthose review judgments. Retire supplemental guards only after equivalent positive, violating\nand missing-scope controls pass on the installed version, including relevant alias, relative,\ntype-only, discovery and reexport paths. Unreplaced policy remains a disclosed gap.\n\n## Rule catalog\n\nUse the [canonical field reference and examples](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Frules.md)\nfor rule kinds and selectors. Class A evaluates declared constraints; unavailable evidence\nremains UNKNOWN. Class B compares accepted and candidate observations, requiring comparable\nprofiles and complete coverage. Class C records declarations. Class D claims are review tasks;\nthey never change verdicts or exit codes, and `null` means unavailable evidence.\n\n## Exit codes\n\nSee the canonical [per-command exit table](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Freference.md#exit-codes).\n\n`check`'s expectation's `selected_changes` may be `[]`\n  when a candidate is not meant to change anything architectural, such as a pure refactor. That\n  declares absence, not \"nothing to report\": `check` then fails on any semantic change the\n  candidate actually produced, in any dimension, not only the six guardrail ones. Declare `[]`\n  only when you mean it; naming the real changes remains the default. A non-empty\n  declaration still lets an undeclared change through in most dimensions, except\n  `dependency_edges`: name every new edge you add, or `check` fails on the one you left out.\n\n## JSON output\n\nEvery command accepts `--json`. Prefer it when scripting or reading output\nprogrammatically: `archkeel validate --json`, `archkeel init --json`, `archkeel report\n--json`. Interactive terminals otherwise get a Rich-formatted summary instead of raw JSON.\nRead `declared_rules`, not just exit 0: FAIL names violated constraints; UNKNOWN retains\nunproved results. The [command-result schema](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fschema\u002Fcommand-result.schema.json)\ncovers `init`, `check`, `validate` and `report`, excluding `skill` and the observation artifact.\nFor completed `init` and observed `validate` results, `open_decision_count` is the exact total\nand `open_decisions_complete` marks whether `open_decisions` lists every pair. `init` defaults\nto observed crossings; `validate` defaults to the full list and offers\n`--compact-open-decisions` for observed undecided crossings. Omitted pairs remain undecided;\nan empty compact list with a positive total still needs decisions. `draft_sizes` records\neach component's measured size only for `init`. Unavailable summaries remain `null`.\nUse the CLI’s bundled schemas for offline validation; pin schema and CLI together.\nIn a checkout, schemas are under `schema\u002F`. The installed distribution includes them under\n`archkeel\u002Fschema\u002F`. `archkeel view check --help` names the spec schema. Use a schema from the same\nCLI version. Do not fetch a schema from the network for local validation.\n","# Archkeel\n\nArchkeel is a deterministic architecture checker. Main observes Rust and TypeScript through native collectors, evaluates a\ndeclared contract of components and rules against that observation, and distinguishes\nPASS, FAIL and UNKNOWN. Rules live in `architecture-contract.json` and its explicit nested\ncontracts; nothing is enforced by convention alone.\n\nPython and Dart projects get verdicts only for import rules in this version; use archkeel 4.0.1 for the other rules.\nThe Rust core decides `validate` and `report`, and no other command runs in this version.\n`check`, `explore`, `init`, `guide`, `story`, `view` and `studio` give a typed refusal with exit 2.\nRelease 4.0.1 has `check` and `init`; no release has the other five commands.\nA refusal is not a result: do not report PASS after one.\nUnsupported profiles give exit 2 before collection, including saved facts and baseline commands.\nDo not report PASS for a supported subset of an unsupported project.\nIn a source checkout, run `make core` to build the core binary. There is no Python fallback.\n\nOn main, `report --output PATH` writes one static HTML page. Add `--format json` for the core frame.\nThere is no default file or sidecar. The parent must exist; final links and directories refuse with exit 2.\nAncestor links are resolved once. Empty, `.` and `-` output targets refuse before the scan.\nSafe file output requires POSIX directory handles. It keeps stdout and the frame exit unchanged.\nIf file delivery fails, stdout keeps the frame verdict but exit 2 replaces the verdict exit, including FAIL exit 1.\nUNKNOWN and collection-refused reports show their causes. A refusal without an accepted frame writes no file.\nThis is not `architecture.json`, a saved snapshot or a graph. The legacy report instructions below do not apply to main.\n`validate --output`, `--html`, saved-input and report-filter options remain refused.\n\n## First run on a codebase\n\nFor native Python parity work, use `--dump-proofs` for the import-local proof boundary (AD-404).\nIts empty provider proof sets do not prove member convergence or enable the production reply.\n\nIf `explore` reports `runtime_mismatch`, do not use its result as a complete scan. Read the\nreported current Python version and full `requires-python` range. Select a Python version that\nsatisfies that range, then retry with `uvx --python \u003Ccompatible-version> archkeel explore --json`.\nArchkeel does not install or switch Python versions.\n\nUse this procedure when a repository has no `archkeel.toml`. The first run gives the owner content\nfrom the measured code: how the system starts, an overview, and one sentence for each component.\nAfter the draft, continue with \"Onboarding\" below. When the owner wants to see the map in the\nbrowser, use the `explore` skill with the same scope options as `explore`. Studio is local and\nwrites nothing into the repository (AD-290).\n\n1. Run `archkeel explore --language \u003Clanguage> --source \u003Cdir> --namespace \u003Cname> --json`.\n   Add `--tsconfig \u003Cfile>` for TypeScript. It writes nothing into the repository. Check `scan_roots` as\n   \"Show a flow\" step 2 tells. Keep the `findings` of the result.\n2. Run `archkeel report --input \u003Csnapshot> --only architecture --json`.\n   `\u003Csnapshot>` is `artifact` in the explore result.\n3. Ask the owner once: \"Create a draft contract?\" A request to onboard or to set up Archkeel is\n   the yes: go to step 5.\n4. Without a clear yes, skip steps 5 to 8 and use the explore snapshot. Never write a contract or\n   another file into the repository. The views of steps 11 and 12 write only to the user cache.\n5. With a yes, run `archkeel init --source \u003Cdir> --namespace \u003Cpackage> --language \u003Clanguage> --json`.\n   Use the scope options of step 1 with the same values, also `--tsconfig` for TypeScript. Omit\n   them when `explore` needed none. Each rule it drafts has `decided_by: \"agent\"` and waits for\n   the architect.\n6. For each top-level component (about 10 at most), write one sentence as one list item in\n   `responsibilities`. Base it on the package docstring, the entry points and the imports of its\n   modules. Cite `file:line` in the sentence, not in `provenance` (it takes paths only). Set\n   `decided_by: \"agent\"` on the component. Without evidence, keep `responsibilities: []` and say\n   \"unknown\" in chat only. Never invent a responsibility.\n7. Optionally, replace a drafted `label` with a short speaking name, only in the new draft.\n   `label` is the name that `requires`, `--component` and nested scopes use. Then run\n   `archkeel validate --write-graph` to update the graph in the architecture page. For a draft,\n   exit 2 with `decision.open` and `rationale.placeholder` is expected. Do not fix them: the\n   architect closes them in \"Interview mode\".\n8. Run `archkeel report --output \u003Ctmp>\u002Farchitecture.json --json`, with `\u003Ctmp>` outside the\n   repository. The draft changed the contract digest: this file is now `\u003Csnapshot>`. Keep the\n   `findings` and the `declared_rules` of the result.\n9. Write a \"get started\" view spec with steps and stops, as \"Show a flow\" steps 3, 4 and 6\n   tell. Start at each entry point: a `[project.scripts]` target (`pkg.mod:main` is the module\n   node `pkg.mod`), a `__main__` module or a `main()`. If you find no entry point, say so and\n   ask the owner for the start module.\n10. Add the first modules that the entry point imports or calls, one direct edge for each step.\n11. Run `archkeel view check \u003Cspec> --snapshot \u003Csnapshot> --json`.\n12. Run `archkeel view show \u003Cspec> --snapshot \u003Csnapshot>`. The page opens at the tour.\n13. Give the owner an overview in chat:\n    - each top-level component with its name and its sentence, or \"unknown\";\n    - the start flow, each step with its status mark;\n    - up to 3 weak spots from the latest `findings` (step 8 after a yes, else step 1), with their\n      `locations`. With none, say that there are none. The kind does not give the scope of a\n      cycle: a `module_cycle` can cross components. Read its `subjects` (the members),\n      `component_ids` and the evidence lines in `path.steps`, and say which components it touches.\n      A `fan_in_hub` or `fan_out_hub` is a hub;\n    - after a yes, the `declared_rules` of the draft.\n14. Offer the next step: define a target together, then compare it in the Target and Diff views.\n\n## Show a flow\n\nWhen the user asks \"show me the flow of X\", answer with a checked view, not with text only.\nA view spec is author text; the check in step 5 decides what the code proves (AD-284).\n\n1. Confirm the start point and the goal. Ask one short question only when the request is ambiguous.\n2. Get a snapshot. With `archkeel.toml`, run `archkeel report --output \u003Cdir>\u002Farchitecture.json --json`.\n   Without it, run `archkeel explore --json`: no contract, no setup, output only in the user cache.\n   On `scope_empty`, read the diagnostic and run\n   `archkeel explore --source \u003Cdir> --namespace \u003Cpackage> --language \u003Clanguage> --json`.\n   Use the same options when `scan_roots` is not the code in question. Keep `--language` when\n   the language is not Python. If `src\u002F` has no Python package, detection searches the root.\n   `\u003Clanguage>` is `rust` or `typescript`. For TypeScript, also pass `--tsconfig \u003Cfile>`.\n   The snapshot path is `artifact` in the result.\n3. Query before you write. `archkeel report --input \u003Csnapshot> --only architecture --json` lists\n   the component ids. `archkeel report --input \u003Csnapshot> --only architecture --component \u003Cid> --full --json`\n   lists its `modules`. A key `''` or a key that starts with `.` gets a prefix: the\n   `selector_prefix` of that component when present, else its own `namespace`. A component with an `inside` contract lists most modules under the child ids\n   of the first command. Use module names as nodes: a child component is `unknown` as a node.\n   Use module nodes for import checks; function nodes support calls only. Source text names\n   candidates, not proof. Read the evidence lines from the check.\n4. Write the working spec in a new temporary folder outside the repository and outside an output\n   folder (`explore` and `view show` clear theirs). Follow the [schema reference](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fschema\u002Fview-spec.schema.json)\n   and the [example](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Ffixtures\u002FF-architecture-view\u002Fplace-order.json).\n   Copy `source.source_digest` and `contract.digest` of the snapshot into `snapshot`. Give each\n   later step and each edge a `kind` (`imports` or `calls`); the first step takes none.\n   Keep no node or edge that the check makes `missing`, except when you deliberately assert it.\n   Set `\"claim\": true` and explain why in `note`. Keep an `unknown` step without `claim` so its\n   cause stays visible.\n   Never write `status` or `evidence`: the check decides, and such a spec is rejected (exit 2).\n5. Run `archkeel view check \u003Cspec> --snapshot \u003Csnapshot> --json` and read each status:\n   - `proven`: observed, with `evidence` (`file`, `line`). Read those lines: a module edge can\n     come from another function. Only one direct edge of its kind proves a step.\n   - `missing`: not in the code. Fix the node or `kind`, remove it, or keep it as a claim. A step\n     with no direct edge is `missing` too: add the modules between as steps.\n   - `unknown`: the snapshot cannot decide. Keep it with your note, without `claim`, so its\n     reason stays visible. A partial call is `claim`, not `unknown`. Check module pairs as `imports` too:\n     `missing` there means no static link (a parameter, a port or a child process). Say so.\n   - `declared`: a contract component or `requires` entry. After `explore`, a layout group\n     declares nothing and is `unknown`: use module nodes.\n6. For a first contact (\"how does it start?\"), also add `stops`: 4 to 8 nodes in reading order,\n   each with a `title` and a `note`, and set `\"schema_version\": \"1.1.0\"`. A stop takes no `kind`:\n   it is a reading order, not a claim. The check adds measured facts to each stop (AD-289).\n   Run `archkeel view show \u003Cspec> --snapshot \u003Csnapshot>`. Stderr names the page. Without stops\n   it opens at the flow; with stops it opens at the tour.\n   Tell the user to open it: `open \u003Cpage>` on macOS, `xdg-open \u003Cpage>` on Linux.\n7. Tell the user the count for each status, each claim, each `unknown` with its reason, each\n   `missing` and each change after the first check. Say: \"proven means structure of the code (an\n   observed import or call), not runtime order.\"\n\nA graph path is not an execution trace. An import proves only that one module imports the other.\nWithout a contract the result has `target: unavailable` and `declared_rules: UNKNOWN`, never PASS.\nYour explanation is your own text, without authority. Never change source or contract for a view.\nThe `explain-flow` skill stores the final checked story under `.archkeel\u002Fstories\u002F` as reviewed\ndocumentation (AD-291). This specific exception does not allow other drafts or evidence in Git.\n\n## Onboarding (first time in this repository): a target, not a description\n\n`architecture-contract.json` is the target architecture — where the system should be, not\nwhere the code already is. `archkeel report` measures declared constraints, not the quality\nof the whole architecture. The architect owns the target and review scope; within that scope,\ninspect the physical structure at every depth, not just the top level. Support them with evidence\nfrom the repository and the architect's quality goals for this codebase (which components\nmust scale, stay easy to change, or are performance-critical). Read those goals from ADRs\nand architecture documents first; ask the architect only when a goal is unknown and would\nchange your recommendation. Every\nrecommendation and every rationale cites the goal it rests on. There is no contract field\nfor a quality goal: record it next to the rule it justifies, following the chosen decision\nmode below.\n\nOn a repository without `archkeel.toml`, start with \"First run on a codebase\": a request to\nonboard is its yes, so `explore` comes first and `init` follows at its step 5.\nFor requested first-time onboarding, inspect existing files, then run\n`archkeel init [--root DIR] [--source DIR] [--namespace NAME] [--force] [--json]` once.\nA read-only assessment uses existing contracts, reports and source; it does not authorize\ninitialization, contract edits, file moves or commits.\nPreserve existing contracts and their `inside` references. If onboarding files already exist,\ncontinue from them; do not use `--force` without explicit approval to replace those files.\n`init` checks `src\u002F` for Python packages first. If it finds none, it checks the repository root.\nIn the selected directory, it uses the only top-level package or the package named by\n`pyproject.toml`'s `[project] name` when test packages sit beside it. Otherwise it exits 2 and\nasks for `--source` and `--namespace`. It also requires an existing Git repository with at least\none commit, and writes three files: `archkeel.toml`, `architecture-contract.json` (one component\nper top-level subpackage\u002Fmodule, plus `complete_assignment` and — only when no component\ncycle exists — `no_component_cycles`, and `interface_boundary` when it drafts public\ninterfaces; no dependency rule), and\n`docs\u002Farchitecture\u002Farchitecture.md` (component table, each component's modules and inner\nedges, and a Mermaid graph of observed edges).\nEvery rule `init` drafts carries `decided_by: \"agent\"` as a placeholder you must resolve, not\nan answer, and so does every component whose `public` list it drafted. It refuses to overwrite existing files without `--force`.\n\n`init` does not infer a foundation or decide where classes belong. Ask who owns a shared type\nfirst; foundation is not the default owner for domain enums or models. Record the architect's\nchoice with the existing `symbol_placement` rule: set `source` to the package, `class_kinds` to\nthe types it owns, and `exact_sources` to the chosen module (or `allowed_sources` to a package\nsubtree). Follow the ownership example in the [target-first guide of release 4.0.1](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002F4.0.1\u002Fdocs\u002Ftarget-first.md). Run `archkeel validate` after\nadding it; a misplaced matching class is a `rule.violated`.\n\nFor TypeScript, use `archkeel init --language typescript --source src --namespace app\n--tsconfig tsconfig.json`; for Dart, use `archkeel init --language dart --source lib\n--namespace app`. Repeat `--source` for multiple roots. A non-empty namespace initializer\nrequires explicit ownership via `exact_modules`; inspect it before recording the owner.\n`init` shows DRAFT while its completed scan remains PASS. Review measured\n`measurements.scalars.cycle_edges`: a cyclic component graph receives no drafted\n`no_component_cycles` rule. Cycles are an advisory, not an error diagnostic.\nIgnore `\u002Ftest-artifacts\u002F` in `.gitignore` for default report output, or choose `--output`.\nRestore missing configuration in existing setups or select `--config PATH`; use `init`\nonly for a new setup. Without Git history, run `git init` and create a commit first.\n\nFor example, after defining storage's responsibility and approving `storage -> domain`,\nadd this fragment to the existing `storage` component. Replace the example reason with\nthe decision owner's actual reason; keep its existing ownership and public interface fields.\n\n```json\n{\n  \"responsibilities\": [\"Persist and retrieve domain records.\"],\n  \"decided_by\": \"architect\",\n  \"requires\": [\n    {\n      \"component\": \"domain\",\n      \"rationale\": \"Storage persists domain records.\",\n      \"decided_by\": \"architect\"\n    }\n  ]\n}\n```\n\nAppend this rule to the existing `rules` list. An empty or absent `requires` list then\nforbids all outbound component pairs; it does not grant observed imports.\n\n```json\n{\n  \"id\": \"REQUIRES-COMPLETE\",\n  \"kind\": \"complete_requires\",\n  \"rationale\": \"Each source states its approved outbound dependencies.\",\n  \"provenance\": [\"docs\u002Farchitecture\u002Farchitecture.md\"],\n  \"decided_by\": \"architect\"\n}\n```\n\nReview drafted `public` entries and replace each structural rule's TODO with its own real\nreason and decision author. A non-empty namespace initializer needs explicit ownership via\n`exact_modules`; inspect it before adding that ownership. Rule kinds and selectors are in\nthe [rule catalog](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Frules.md).\n\nWhen an API role must declare a canonical port, use contract 3.9.0's\n`protocol_declarations`. Select a source scope plus exact `parameter` or annotated class\n`member` names and visibility; this includes future declarations. The canonical dotted\n`protocol` must resolve to a scanned Protocol. An optional selector permits only that Protocol\nwith `None`; broader unions, missing annotations, `object`, and `Any` fail. Statically\nproven single-name `TypeAlias` chains resolve to their target; unsupported alias shapes,\nincluding union-valued aliases, remain UNKNOWN. Shadowed and unresolved names also remain\nUNKNOWN. MyPy checks assignability, and the rule does not replace structural conformance review.\n\nThen pick one of two modes. The architect chooses; do not choose for them.\n\n### Physical structure review (both modes)\n\nAfter `init`, and during architecture assessments, inspect every maintained source package\nin scope recursively down to leaf packages, whether or not it has an `inside` contract.\nThe generated inventory and a green contract are not evidence that this structure is good.\n\n- Count direct source modules and immediate subpackages at each level; exclude `__init__.py`\n  from this count, not from ownership, behavior or dependency review. Record excluded generated\n  or vendored trees.\n  More than seven direct children triggers a review, not an automatic split or a failing\n  rule. Five to seven understandable groups is a review heuristic, not a cognitive law.\n- Challenge mixed responsibilities, unclear names, oversized leaf modules, excessive\n  nesting, cycles and cross-package coupling even below that threshold. Trace entry points\n  and data flow before choosing boundaries; check who owns shared types and public interfaces.\n  Follow one real operation through business logic, state\u002Fexternal effects and its observable\n  result. For each layer, name its invariant, failure mode and what breaks if removed.\n- Review changed APIs against a concrete caller purpose: named operation\u002Ftype, typed inputs\n  and result, errors, and state\u002Fresource\u002Ftransaction lifetime. Assess test-only helpers and\n  dynamic discovery separately; discovery needs a real caller\u002Fprotocol, not an invented import.\n  Recommend delete\u002Fsimplify\u002Fkeep for redundant wrappers, duplicate knowledge owners, brittle\n  string dispatch and reflection\u002Fcoercions hiding incorrect models. Candidates are review\n  work, never automatic deletion or a semantic PASS.\n- Propose physical packages around cohesive responsibilities, not arbitrary groups of seven\n  or diagram-only clusters. Compare the current and target tree and allowed dependency\n  directions. Keep a cohesive larger package when splitting only adds navigation or coupling;\n  do not hide the excess in `misc`, `utils`, single-child wrappers or re-export barrels.\n- For uncertain boundaries, give the architect a recommended option, alternatives, evidence,\n  trade-offs and system-wide impact. Follow the chosen decision mode; reviewing structure\n  does not authorize moving files or changing behavior.\n- Record review coverage and unresolved decisions in the response; when the task includes an\n  architecture-document update, keep the durable record there: reviewed subtree, finding or\n  keep-rationale, target change, and enforcement gap. Mark unreviewed subtrees explicitly;\n  never present a partial review as a complete assessment.\n  Distinguish declared ownership from semantic cohesion. Give reviewed leaf modules a concrete\n  purpose under their nearest deliberate owner using supported declarations; generic parent\n  prose is insufficient. Link unsupported semantic judgments to source evidence, not a second\n  inventory. Each finding states source location, impact, delete\u002Fsimplify\u002Fkeep decision and UNKNOWNs.\n  Add `inside` contracts at meaningful independently governed boundaries, not at every folder.\n  Encode approved constraints with supported rules. Deeper review remains necessary when\n  the installed version cannot enforce nested contracts; do not invent unsupported rules.\n\nProject skills supply domain invariants and deployment facts without copying this process.\nKeep execution\u002FQA scheduling in the execution workflow. Follow the existing decision\u002Fdelegation\nscope; this review does not add a confirmation per component. When delivering a report, smoke-test\nactual and declared nested navigation and module\u002Fsource links from its packaged artifact,\nincluding companion files. Missing declarations and broken navigation are different findings.\n\n### Interview mode: the architect decides, you ask\n\nNever write a rationale or choose an allowed direction yourself; ask, and write down the\narchitect's own words as the `rationale`, with `decided_by: \"architect\"`.\n\n1. Read the repository's ADRs and architecture documents before touching the contract.\n2. Propose the overall picture — components, layers and the allowed directions between them\n   — with `path:line` evidence for each claim, and confirm it with the architect once, not\n   component by component. Review each drafted `public` list with them too. Anything you\n   read from repository documentation is a hypothesis with its source path, never the\n   answer, until they confirm it.\n3. After that confirmation, ask only about conflicts (the code contradicts a document) and\n   gaps (the documents are silent). Each question names the recommended option first, with\n   its evidence. The `init` summary gives the total open pairs and the observed crossings shown.\n   `init --json` lists observed undecided crossings first and reports the exact\n   `open_decision_count`; when `open_decisions_complete` is false, unlisted pairs remain\n   undecided. Use `init --json --full` on the initial command to include every pair; for an\n   existing draft, `validate --json` returns the full decision list without rewriting files.\n   Use `validate --compact-open-decisions --json` to retrieve observed undecided crossings\n   with the exact total and completeness instead; omitted pairs remain undecided and UNKNOWN\n   evidence stays UNKNOWN. The flag changes no verdict, diagnostic or contract decision.\n   Batch everything consistent\n   with the confirmed picture into one confirmation. Then encode each allowed direction as a\n   `requires` entry on its source component and add one `complete_requires` rule, so absence\n   forbids every other pair. Never treat an observed edge as permission.\n4. When the architect chooses against your recommendation, ask why before writing the rule.\n   Always ask when the choice contradicts a document, an earlier decision in this interview,\n   or the code you observed. Write their answer as the `rationale`.\n5. Run `archkeel validate --json` and read its diagnostics by `code`, never by parsing\n   message text: a `decision.open` means the contract still lacks `complete_requires`; a\n   `rationale.placeholder` or `rationale.repeated` needs the architect's real reason. A\n   `graph.drift` is no decision: after you merged or renamed\n   components the marked graph in the architecture page is stale, so run\n   `archkeel validate --write-graph` instead of editing it by hand; it rewrites only that\n   graph's edges. When the remedy says the graph holds structure the command does not rewrite\n   (a `subgraph`, a labeled edge, a style), edit those edges by hand instead.\n6. When the architect delegates a choice (\"whatever is consistent\" or similar), derive it\n   only from their earlier decisions in this interview, never from your own judgment. Label\n   the rationale agent-derived in your summary to the architect and list it for them to\n   confirm before it counts as decided.\n\n### Auto mode: the agent decides every allowed direction\n\n1. Decide every allowed direction yourself, in this evidence order: documents first, then the\n   layer principles the architect already confirmed or the documents state, then your own\n   judgment, labeled as judgment in the rationale.\n2. Never treat an observed edge as permission: code importing across a boundary today is not\n   evidence the boundary should allow it.\n3. Write every rule you decide with `decided_by: \"agent\"`, and mark a component whose\n   `public` list or `requires` edges you decided the same way: `decided_by` on the component\n   covers its `public` list and every `requires` entry that carries none of its own, and one\n   entry may override it.\n4. End with a summary of your decisions grouped by evidence basis (document, layer\n   principle, judgment) and name the lowest-confidence decisions first, for the architect to\n   review.\n\nA later interview on an auto-mode contract asks the architect only about rules, entries and\ncomponents with `decided_by: \"agent\"`; an `architect`-decided one is already closed and is not\nreopened.\n\n### Ending onboarding, either mode\n\nBefore ending, record the physical structure review and any deferred subtrees or decisions;\na closed dependency contract alone does not complete the architecture assessment.\nThe dependency interview (or auto-mode pass) ends when `complete_requires` closes the\ndependency set and `validate --json` reports none of `decision.open`, `rationale.placeholder` or\n`rationale.repeated` — not when the command exits 0. A `rule.violated` diagnostic is the\narchitecture's own finding, not an onboarding step: the code still uses an edge the target\nomits. Show it to the architect with `archkeel report`. They resolve it by changing the code or\nchanging the target; the agent never does that itself and never loops `validate --json` waiting\nfor exit 0.\n\nOnce it ends, run `archkeel report`. Include the generated files (`archkeel.toml`,\n`architecture-contract.json`, `docs\u002Farchitecture\u002Farchitecture.md`) when they are part of the\nrequested change. A remaining `rule.violated` is follow-up code work, tracked separately from\nonboarding.\n\nWhere that follow-up is long — a contract that states the target architecture the code has\nyet to reach — freeze the known violations instead of weakening the contract:\n\n```bash\narchkeel validate --baseline known-violations.json --write-baseline   # once, then review it\narchkeel validate --baseline known-violations.json                    # the CI gate\n```\n\n`--baseline` and `--amendment` are relative to `--root`, like the contract: with `--root mobile`,\npass `--baseline known-violations.json` for `mobile\u002Fknown-violations.json`, never the\n`mobile\u002F`-prefixed path. An absolute path inside the root works; one outside it is\n`baseline.invalid`, exit 2.\nThe gate fails (exit 1) on a violation the file does not state, and on one it states that\nnobody violates any more — so the budget only shrinks, and the file is rewritten in the same\nchange that shrinks it. `declarations.measurement_budgets` may put deterministic scalar values\nthrough the same loop. `declarations.facade_budgets` and\n`declarations.coupling_budgets` set name targets in the contract, and the baseline holds their\naccepted names.\nNever raise any of them to make a run pass without the architect's decision.\nWhen `calls_unresolved` rises, rerun with `--against \u003Cbase ref>`, as the\nfinding says: `unresolved_call_changes` names each added and removed unresolved call with its\ncaller, path, lines, expression, reason and component. `report --only calls --json` lists every\nunresolved and partially resolved call as `filtered_calls`; add `--component \u003Clabel>` for one\ncomponent's calls.\n\nA reviewer or a CI gate may hold your branch to this the same way, with `archkeel validate\n--against \u003Cbase ref>`: it classifies every difference from the contract at that revision — a\nnew `requires` edge, a `public` entry, an `allowed_sources` module, a relaxed or deleted rule,\na padded baseline entry, and anything else this repository's `ir.widening` does not otherwise\nname — as a widening, which fails (exit 1) unless `--amendment \u003Cpath>` names a file the\narchitect wrote, recording who decided it and why, bound to this exact change.\nIn `validate --json`, `widenings` is `null` when `--against` was not checked, otherwise it lists\nunamended widenings with `code: \"ir.widening\"`, `subject` and `field`; `failures` keeps the\nhuman-readable messages. `amendment_status` is `valid` or `stale` when a supplied amendment was\nchecked, and `null` otherwise. A valid amendment may leave `widenings` empty even when it accepts\na real change.\nNever widen the contract in the same change that removes the violation it names: fix the code,\nor ask the architect for an amendment. The full loop — gating, widening, picking a slice of the\nbacklog and landing a planned interface — is worked end to end on the shop sample in\nhttps:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002F4.0.1\u002Fdocs\u002Ftarget-first.md.\n\n## Retiring local dependency gates\n\nUse native dependency policy for proven Python literal loaders as well as static\nimports. Binding mutation, unknown targets and nonempty builtin fromlists retain\nscoped UNKNOWN evidence. A dependency edge does not prove a public value API.\nBefore deleting a local scanner, compare its forbidden, allowed and missing-scope\ninputs against the installed release, including aliases and dynamic forms. A source\ncheckout or Draft PR is not proof that the installed release supports them.\n\nUse `call_owner` only where its installed observer proves the complete selected\ncall scope. Observation 2.4 adds bounded proofs for stored typed receivers,\nstable default constructions, and selected native targets (`random`,\n`secrets.token_hex`, and CPython `datetime.datetime.now`). Inheritance is followed\nonly through a unique recorded base path. Dynamic dispatch, custom allocation,\nunsupported mutation, and native APIs without an admitted provider witness remain\nUNKNOWN. The datetime witness inspects the isolated collector runtime’s stdlib\ndescriptor and source digest; it does not import project modules. Arguments and\nguards are not proved by this change. Check the rule receipt and supported forms\nbefore retiring any method-name scanner. Older readers must reject observation\n2.4 rather than omit the added proof vocabulary; current readers continue to\naccept historical observations.\n\nContract 3.8 `bounded_numeric_operand` checks selected Python `%` and `%=` sites\nby written terminal identifier suffix. Only bounded integer\u002FBoolean literals,\nunary signs, powers and unique preceding aliases prove values. Review its source\nevidence: each operation and alias must fit a replayable single-line excerpt\nof at most 16,384 characters; single-line `if`, `elif`, `while`, `for`, `with`,\nfunction and class headers and inline suites are supported with Python indentation. Multiline\nor otherwise incomplete evidence remains UNKNOWN. Review the source\nreceipt and UNKNOWNs; it does not establish runtime types, reachability, entropy\nor collision freedom. Empty\u002Fmissing selected scope is UNKNOWN. See\n[AD-246](..\u002F..\u002Fdocs\u002Farchitecture\u002Fdecisions\u002Fad-246-bounded-numeric-operand.md)\nand [rule limits](..\u002F..\u002Fdocs\u002Fknown-limits.md).\n\nUse `forbidden_call_argument` to select one written-literal policy\nfor a canonical target's formal parameter. It binds explicit source actuals to\nthe observed signature; spreads, invalid bindings, missing signatures and\nunproven targets leave UNKNOWN. Calls without canonical binding carry null\nargument facts; a proven call with no actuals carries an empty list. It does not check runtime type compatibility\nor apply omitted defaults. Check the rule receipt and supported forms before\nretiring any method-name scanner. Argument facts require observation 2.5 and\ncontract 3.10; older readers must reject that evidence. The current reader\ncontinues to accept historical observation formats.\n\nUse `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.\n\nUse `source_ownership` for Python-local policy over source roles. In `retired` mode,\nselect `symbols` and roles `definition`, `read`, `write` and\u002For `delete`. In `confined`\nmode, select `symbols` plus `owner`, or formal `parameters` plus `value_owner`; choose\nroles `value_transfer`, `parameter_default` and `fallback` only when the observer can\nlink each value to admitted source evidence. Unsupported or ambiguous expressions remain\nUNKNOWN. This rule is available with contract 3.12 and observation 2.7; older readers\nmust reject those formats rather than silently ignore the rule or role facts. See\n[AD-249](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Farchitecture\u002Fdecisions\u002Fad-249-source-ownership-defaults.md)\nand the [rule catalog](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Frules.md).\nUse `forbidden_construct.selector` when a policy must select one nominal\nreceiver\u002Fmember and access or comparison role. Contract 3.11 and observation\n2.6 enable the Python slice: annotated direct member reads, positional literal\nreflection names, selected local constructors and type probes, literal equality\nin either direction, membership, `match`, and `startswith`\u002F`endswith`.\nDynamic names, unannotated or ambiguous receivers and missing selected subjects\nremain UNKNOWN. Other language profiles do not claim selector support. See\n[AD-248](..\u002F..\u002Fdocs\u002Farchitecture\u002Fdecisions\u002Fad-248-construct-selectors.md) and\nthe [rule grammar](..\u002F..\u002Fdocs\u002Frules.md#interfaces-and-types).\n`forbidden_effect_under_condition` is a static ownership rule. It can prove a declared\nBoolean parameter\u002Fmember through truth, negation, `if`\u002F`else`, ternary and early\n`return`\u002F`raise`, plus one unique private helper with signature-bound actuals. A known\nunconditional effect is reachable while the condition is true. Reassignment, named\nexpressions, short-circuiting, loops, `try`\u002F`finally`, reflection and helper chains or\nrecursion remain UNKNOWN. Inspect the rule receipt and path evidence before relying on\nPASS; see [AD-250](..\u002F..\u002Fdocs\u002Farchitecture\u002Fdecisions\u002Fad-250-bounded-guarded-effect-ownership.md).\n\n## Daily loop\n\nValidation reports `responsibility.missing` only for components explicitly marked\n`decided_by: \"architect\"` with no non-whitespace responsibility text. It checks declaration\npresence, not prose quality or complete coverage of cross-cutting concerns; an agent draft stays\nusable and incomplete until the architect decides it.\nContract text with `decided_by: \"architect\"` wins over agent text. Text with `decided_by: \"agent\"`\nis a draft: revise it only on request, and show the difference in chat.\n\n- Start with `archkeel report --only architecture --json`. It projects authenticated intent,\n  ownership, dependency permissions, observed use and required Target relationships. Use\n  `--component \u003Cid-or-scope>` for a slice; global verdicts, coverage and uncertainty remain.\n  Missing evidence is UNKNOWN. Permissions never prove use or required execution.\n  After one scan, query that packet with `archkeel report --input architecture.json --only architecture\n  --component \u003Cid-or-scope> --json`. Omit `--component` to discover its exact ids and scopes.\n  This reads recorded source identity and evidence; it does not verify the current working\n  tree or write files. Read `architecture_projection.required_relationships` for Target intent.\n  For findings, query the same packet with\n  `--only violations --component \u003Cid-or-scope> --json`; add `--rule \u003Cid>` to intersect.\n  The compact query omits module lists, policy detail and `filtered_violations`; it reports\n  the selected-scope `filtered_violation_count` (`null` when unavailable) and sets\n  `violation_details_included` to `false`. Add `--full` to retrieve the complete\n  `permission_rules`, `policy_context` and violation records: `archkeel report --input\n  architecture.json --only architecture --full --json`. Full output includes an empty\n  `filtered_violations` array when the measured selected scope has no findings.\n- Revisit the physical structure review for changed packages and their parent boundaries;\n  recheck related findings rather than repeating a whole-repository review for every edit.\n- Run `archkeel report --json` before submitting any change. A rule violation does not\n  change the exit code; read the `declared_rules` verdict. Exit 2 means the evidence is\n  incomplete; fix the diagnostic before trusting any verdict. An unfiltered report also\n  carries `findings`, the ranked list its terminal summary and HTML page open with:\n  violations, then dependency cycles, then hubs, each with a `size`, source `locations` and one\n  `sentence`. Read it first; a missing `findings` (filtered report) never means none.\n- On a large repository, `report --only violations --rule \u003Cid> --component \u003Cid-or-scope> --json`\n  narrows the review surface to a slice you can actually read: `--only violations` drops\n  component flow, communication, claims and structure from the HTML page; `--rule` and\n  `--component` narrow the violations table further and combine as an intersection.\n  This includes local Target findings and descendants, plus crossings touching either side.\n  Top-level labels take precedence over identical nested labels. This changes only what is\n  shown - `declared_rules`, the violation counts and the exit code stay computed from every\n  violation - and a filtered `--json` result says so in its own `report_filter` field, so never\n  read a filtered `filtered_violations` count as the repository's total; read the unfiltered\n  `violations` measurement for that. A `--rule` or `--component` you misspelled is a named exit\n  2, not a silently empty page.\n- If a rule fails, fix the code so the rule passes.\n- Never weaken or delete a rule just to make a violation disappear, unless the component\n  owner explicitly approves the change to the contract. A silently loosened rule hides the\n  next real violation.\n- `validate --json` and `report --json` report `agent_decisions` as `[agent, total]`, counting\n  one rule declaration, one `requires` entry and one declared `public` list alike; a nonzero\n  first value means an auto-mode contract still awaits an architect interview on those\n  decisions.\n- The same two commands report `claims`, the Class D review claims. They never change a\n  verdict or an exit code; bring a nonzero count to the architect as reading work, and never\n  delete code because a claim named it. `--json` carries only counts; the HTML page of\n  `report --only architecture` names each claimed symbol, binding, repetition and type.\n  `oversized_components` is a compatibility count, not a claim (AD-235); read component\n  sizes in the Structure overview instead.\n\n## Nested contracts: the inside of a component\n\nA component may name a contract of its own, which becomes a second level of the same\narchitecture. Adding one is the architect's decision; inspecting the physical\nsubtree is already part of the recursive review above and does not depend on that decision. A\ncomponent that holds more modules than the whole top level, as the Structure overview shows, is\na reason to ask, not permission to split (AD-235).\n\nOnce the architect decides:\n\n1. Inventory the source tree and the existing `archkeel report --json` structure measurements.\n   Review every relevant child before grouping; a report does not cover detail it does not\n   expose. Do not rerun `init --source` at the repository root for this scope: `init` writes the\n   standard root onboarding files and requires `--force` if they already exist. On Archkeel's\n   own `check`, a per-module draft produced 12 sub-components and 132 open decisions where the\n   three layers the architect settled on need 6. Consolidate into a few layers with the architect\n   before deciding a single pair.\n2. Point the outer component at the resulting contract with\n   `\"inside\": \"\u003Crepository-relative path>\"`.\n3. Decide the inside the way you decide the top level: a `requires` list per sub-component and\n   one `complete_requires` rule, so absence forbids there too.\n\n`validate` holds the declared levels to each other; read its diagnostics by `code`:\n\n- Each level's `public` list serves that boundary. Child APIs stay local unless the parent\n  explicitly publishes them or a proven facade reexport. Do not copy every child API upward.\n- `reference.public_owner`, `reference.public_underscore` and `reference.namespace` also apply\n  inside. Correct the declaration at its mounted pointer; do not broaden ownership to silence it.\n- With an inner `interface_boundary`, `interface.missing` names an unscanned public module.\n  `interface.unused` means no scoped sibling import or proven facade publication reaches it.\n  A built, unused planned entry stays target work; reaching it requires promotion through\n  `interface.planned_built`, not automatic permission. Publisher evidence belongs to the exact\n  parent scope, including proven re-export chains. Unknown import names are not proof of non-use.\n- `inside.forbidden_import` — the inside grants an edge the level above forbids the component,\n  by a rule or by absence under `requires`. Remove the grant, or change the decision above.\n- `contract.invalid` at `\u002Fcomponents\u002F\u003Cn>\u002Finside` — the file is missing, outside the repository,\n  or does not parse on its own.\n\n`report` evaluates `complete_requires` a second time against the inside, over the imports the\nouter scan already collected, so a crossing between two sub-components that no `requires` entry\ncovers is a violation like any other, and the flow view opens that component into its\nsub-components before its modules. Such a finding names the rule as `\u003Ccomponent>:\u003Crule id>`,\nfor example `store:STORE-REQUIRES-COMPLETE`: the id you will find in the inside contract is the\npart after the colon, and the part before it is the component that names that contract. Resolve\nit according to the target decision: update the inside `requires` only for an architect-approved\ncrossing; otherwise change the code. Do not add a rule above to hide an inside crossing.\n\nExplicit `inside` references are followed recursively and use the shared rule evaluators.\nMounting a contract does not create a standalone `archkeel.toml` for it. Nonempty inside\n`declarations` fields remain unsupported and are refused. An inner `external_dependency_scope`\ndeclaration is not compared with ancestor declarations; ancestor rules still evaluate their\nown source scope. A physical folder alone is not a declared contract.\n\n## Maintaining a nested contract\n\nUse the saved architecture projection with `--component \u003Cid-or-scope> --full`. Read the owner's\npurpose\u002Fexclusions, deliberate API, dependency reasons and ancestor\u002Fchild `policy_context`.\nFill missing context from the canonical mounted contracts and source; mark absent evidence.\nBind the review to the source revision, contract\u002Fanalyzer identities and installed CLI version.\nValidation catches supported reference, ownership and stale-declaration errors; it does not\njudge whether responsibility prose is good.\n\nFor each edit, record affected scopes\u002Fdeclarations, focused\u002Ffull input bytes, logical edit\nfiles\u002Fsites, and before\u002Fafter ownership, API and permissions. Edit size is maintenance evidence,\nnot an architecture verdict or a pass threshold. Run `validate --against \u003Caccepted-ref>` and\nuse the existing bound amendment for approved widening; never regenerate intent from imports.\nIts `contract_changes` list each change as widened or narrowed; only widenings need the\namendment, and a tightened `requires` entry narrows. Narrowings cover `requires`, `public` and\nrule presence only; anything else is not enumerated.\n\nThe [checkout fixture](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Ftree\u002Fmain\u002Ffixtures\u002FH-uml-dart)\nhas `ordering -> domain -> orders\u002Fpricing` boundaries. Try these changes independently:\n\n| Change | Deliberate edit sites | Control |\n| --- | --- | --- |\n| Move `discount_policy` from pricing to orders | Source path; domain owner\u002Fpublic\u002Fmodule 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. |\n| Rename persistence API `findById` to `find` | Implementation\u002Fcaller and the two existing nested signature targets. | Return-type drift fails; changed Target requires its bound amendment. |\n| Remove unused pricing-to-orders permission | The existing nested `requires` entry. | The same import passes before tightening and fails after it. |\n\nReview the resulting owner from the same saved packet:\n\n```bash\narchkeel report --input architecture.json --only architecture --component ordering:domain:orders --full --json\n```\n\nFor this example, a project adapter supplies only domain invariants such as \"orders own\nlifecycle; adapters own persistence\". Trace checkout through the persistence port to the\nobservable receipt; keep cohesive larger packages when a split adds only indirection.\nAn unused public helper needs a caller justification; a dynamically selected collector entry\nneeds its actual process\u002Fprotocol evidence. Neither import counts nor generic leaf prose settle\nthose review judgments. Retire supplemental guards only after equivalent positive, violating\nand missing-scope controls pass on the installed version, including relevant alias, relative,\ntype-only, discovery and reexport paths. Unreplaced policy remains a disclosed gap.\n\n## Rule catalog\n\nUse the [canonical field reference and examples](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Frules.md)\nfor rule kinds and selectors. Class A evaluates declared constraints; unavailable evidence\nremains UNKNOWN. Class B compares accepted and candidate observations, requiring comparable\nprofiles and complete coverage. Class C records declarations. Class D claims are review tasks;\nthey never change verdicts or exit codes, and `null` means unavailable evidence.\n\n## Exit codes\n\nSee the canonical [per-command exit table](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fdocs\u002Freference.md#exit-codes).\n\n`check`'s expectation's `selected_changes` may be `[]`\n  when a candidate is not meant to change anything architectural, such as a pure refactor. That\n  declares absence, not \"nothing to report\": `check` then fails on any semantic change the\n  candidate actually produced, in any dimension, not only the six guardrail ones. Declare `[]`\n  only when you mean it; naming the real changes remains the default. A non-empty\n  declaration still lets an undeclared change through in most dimensions, except\n  `dependency_edges`: name every new edge you add, or `check` fails on the one you left out.\n\n## JSON output\n\nEvery command accepts `--json`. Prefer it when scripting or reading output\nprogrammatically: `archkeel validate --json`, `archkeel init --json`, `archkeel report\n--json`. Interactive terminals otherwise get a Rich-formatted summary instead of raw JSON.\nRead `declared_rules`, not just exit 0: FAIL names violated constraints; UNKNOWN retains\nunproved results. The [command-result schema](https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fschema\u002Fcommand-result.schema.json)\ncovers `init`, `check`, `validate` and `report`, excluding `skill` and the observation artifact.\nFor completed `init` and observed `validate` results, `open_decision_count` is the exact total\nand `open_decisions_complete` marks whether `open_decisions` lists every pair. `init` defaults\nto observed crossings; `validate` defaults to the full list and offers\n`--compact-open-decisions` for observed undecided crossings. Omitted pairs remain undecided;\nan empty compact list with a positive total still needs decisions. `draft_sizes` records\neach component's measured size only for `init`. Unavailable summaries remain `null`.\nUse the CLI’s bundled schemas for offline validation; pin schema and CLI together.\nIn a checkout, schemas are under `schema\u002F`. The installed distribution includes them under\n`archkeel\u002Fschema\u002F`. `archkeel view check --help` names the spec schema. Use a schema from the same\nCLI version. Do not fetch a schema from the network for local validation.\n",{"name":5,"description":7},"main","127aa1fa2a936eaf11024bac3052a25c2e4efc11","skills\u002Farchkeel",3,"https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel","https:\u002F\u002Farchkeel.com","https:\u002F\u002Fgithub.com\u002Frapiddweller","https:\u002F\u002Fwww.rapiddweller.com","We are driving the digital transformation by automating monotonous dweller tasks to leave meaningful work for humans. DATAMIMIC, SEO, PageSpeed, Testdata, QA","2026-11-15 06:11:03",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add rapiddweller\u002Farchkeel --skill archkeel",{"tool":39,"command":40},"bunx","bunx skills add rapiddweller\u002Farchkeel --skill archkeel",{"tool":42,"command":43},"pnpm","pnpm dlx skills add rapiddweller\u002Farchkeel --skill archkeel","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fskills\u002Farchkeel\u002FSKILL.md",true,[],[48,54,61,68],{"skillNo":49,"name":50,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":51,"categories":52,"keywords":53,"publishedAt":18},"01M7CR9TB4S1E04RK787H4NAGV","assets","https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fsrc\u002Farchkeel\u002Fcli\u002Fassets\u002FSKILL.md",[],[],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":18},"01M7CR9PDQP3NXE7JEMX8V1P6H","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.","https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fskills\u002Fexplore\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":18},"01M7CR9J7XT66GMNHDFGVC7KME","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.","https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Fskills\u002Fexplain-flow\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":18},"01M7CR98YWY5ZH26KK6ANAX51D","orders-domain","Use with the archkeel skill when reviewing or changing the orders service; supplies its domain invariants only.","https:\u002F\u002Fgithub.com\u002Frapiddweller\u002Farchkeel\u002Fblob\u002Fmain\u002Ffixtures\u002FM-review-workflow\u002Fskills\u002Forders-domain\u002FSKILL.md",[],[]]