Skip to content

Declared rules and budgets ​

Two tools turn architectural intent into something a build can fail on: check_architecture evaluates boundary dependency rules against the current graph, and quality_gate compares the current graph with a reviewed baseline snapshot. Both are also composed into review_diff, which scopes their findings to one change set.

Both read their declarations from files you check in, so the rules live beside the code they govern. knossos.json holds them directly, as policies and quality_budgets; see project configuration. Boundaries are explained in the graph and its evidence.

Boundary policies ​

The Boundaries tab: 33 declared boundaries and 1 inferred, the first five listed with their components and dependencies in and out, what the marked tests boundary depends on and what uses it, and the tests to Query flow drawn with the component pairs behind it

In the pane, the Boundaries tab lists every boundary, what it depends on and what depends on it, and draws the dependencies behind a flow between two.

check_architecture evaluates explicit boundary dependency rules against the active static graph. A policy names its source boundary, and each target, by stable ID, by exact name, or by any name the boundary has had, and declares allowed and/or forbidden target boundaries. Internal dependencies within the source boundary are implicitly allowed unless that boundary is explicitly denied. Two reserved targets match code outside every boundary: @unassigned is the project's own code that no boundary holds, and @external is vendor code and language builtins, which never join a boundary, including the npm packages the TypeScript worker records. Before 0.32 vendor code counted as @unassigned, so a policy written then may need @external beside it: an allow list that should let a boundary call its libraries names @external, and a deny list that should keep a boundary off vendor code names @external too, since @unassigned alone no longer matches it.

A policy takes these fields and no others: id (required, unique, at most 100 bytes), from_boundary (required), allow_targets, deny_targets (at least one of the two) and edge_kinds. When you leave out edge_kinds, every dependency relationship counts but launches: starting a worker in another process is how code is meant to cross an out-of-process boundary, so a policy that forbids it names launches in edge_kinds. The boundary matrix counts the same relationships. At most 50 policies can be evaluated at once.

json
[
    {
        "id": "domain-isolation",
        "from_boundary": "Domain",
        "allow_targets": ["Domain", "Shared"],
        "deny_targets": ["Infrastructure", "@unassigned"],
        "edge_kinds": ["calls", "imports", "depends_on", "constructs"]
    }
]

Without a file, the CLI checks the policies the project declares in knossos.json, and refuses to run when it declares none or the file cannot be read. --policies reads them from a bounded JSON file instead. The project is a path inside it or its ID:

sh
knossos check-architecture . --json
knossos check-architecture . --policies=policies.json --json
knossos policies .

knossos policies shows the boundaries and policies the project declares. The equivalent MCP tool accepts the JSON array as policies, and without it checks the declared ones too. Optional min_confidence, limit, max_edges, and timeout_ms inputs control the evaluation.

An inferred boundary is renamed when a manifest joins it: adding a composer.json beside a package.json named web turns node:web into composer:acme/lib (+node:web), and a second package.json named loc turns node:loc into node:loc (a) and node:loc (b). The names a boundary had are listed under aliases in list_boundaries, and a policy that uses one, or the stable ID that name had, still resolves. A name or alias that two boundaries share, such as node:loc above or a name both an explicit and an inferred boundary carry, is rejected with the candidates' stable IDs; use one of those. file_context, the session brief, the dashboard and export_diagram read a policy's boundaries the same way. A policy whose source boundary reference is ambiguous or names no boundary is therefore not listed by file_context for any file, check_architecture and quality_gate refuse it, and the session brief shows the reference as written.

Findings include the policy ID, the violating relationship (with its kind, confidence and origin), both components, the boundary memberships on each side, the reasons, and source evidence in the envelope. bounds.violation_count is the exact total even when limit cuts the list. Findings describe the indexed static graph, not runtime enforcement, and may miss dependencies created through reflection, configuration, framework conventions, or dynamic dispatch.

Quality budgets ​

quality_gate compares the active graph with a complete retained baseline (see scan history) and evaluates only the limits supplied by the caller. Each limit is an integer from 0 to 100000, and the baseline must differ from the active snapshot. A rescan with nothing changed keeps the same snapshot, so comparing right after one is refused until something changes. Supported budgets are:

BudgetWhat it limits
new_cyclesCycles in the active graph whose members were not all one cycle in the baseline. A cycle that only moved to another namespace or file is not new: a member the baseline lacks counts as the one removed baseline component with the same language, kind, owning type and name. Type-only imports are not dependencies, as in dependency_cycles.
boundary_violationsPolicy violations in the active graph. Needs policies.
error_diagnostics, warning_diagnosticsDiagnostics of that severity in the active scan.
hub_degree_growthHow far the highest component degree grew past the baseline's.
unreferenced_candidatesDead-code candidates in the active graph.
public_surface_changesRoutes, commands, endpoints, exports and public or entry-point roles added or removed.

Example budget file:

json
{
    "new_cycles": 0,
    "boundary_violations": 0,
    "error_diagnostics": 0,
    "hub_degree_growth": 4,
    "public_surface_changes": 0
}

Run it with a reviewed retained baseline:

sh
knossos quality-gate project_... scan_... \
  --budgets=knossos-budgets.json --policies=architecture-policies.json --json

The command exits nonzero when any budget fails. A boundary_violations check whose policy scan hit its edge or time bound is marked indeterminate and fails, because a count taken from a partial scan is only a lower bound. --sarif embeds SARIF 2.1.0 for findings with sound file mappings, currently boundary-policy evidence and scanner diagnostics. Other metrics remain structured JSON because assigning a single source location would be misleading.

--propose-baseline returns the current metrics as proposed_baseline, a reviewable proposal. It never writes, updates, or suppresses a checked-in baseline automatically; adopting a proposal remains an explicit repository change.

Cycle and degree metrics use the same bounded static dependency kinds as other Knossos analyses. Unreferenced and public-surface results are conservative static signals and may not capture dynamic framework behavior.

Wiring both into CI, with exit codes and SARIF upload, is covered in CI and editor integration.