Skip to content

Reviewing a change ​

Four tools answer "what does this change put at risk?" at different widths. Start with review_diff. Reach for changed_files_impact when you want its impact part on its own, and for test_impact and change_impact when you want the tests or the Git history. They rest on the graph described in the graph and its evidence.

ToolCLIAnswers
review_diffreview-diffImpact, rules, budgets and cycles for a change, in one call.
changed_files_impactchanged-files-impactWhat a set of changed files, or your working tree, touches.
test_impacttest-impactWhich test files statically exercise the change.
change_impactchange-impactStatic blast radius weighted by recent Git churn.

Every Git-reading tool here runs git read-only in the scanned root: optional locks disabled, argument-array process execution, hooks never invoked, a hard timeout, and stdout/stderr byte caps. None modifies the worktree, index, refs, or repository configuration. See the HTTP threat model for the exact hardening.

The Branch tab: a detached checkout four commits ahead of main, 14 things to look at, most of them new dependencies across boundaries, and what it changed by boundary with its lines and its reach

In Claude Code, the pane's Branch tab gives this review for the branch you are on, against main, at a glance.

Review diff ​

review_diff is a one-call architectural review of a change set: it composes changed_files_impact, check_architecture, quality_gate, and dependency_cycles into a single result, scoping the policy violations and cycles it returns to the components the change actually touches. Use it when you want a single answer instead of chaining four separate calls.

Unlike changed_files_impact, review_diff has no working_tree flag: an empty files list is the working-tree default, so there is no flag/argument combination that can silently do the wrong thing. Passing files together with base_ref is rejected.

sh
knossos review-diff project_... --json                       # the working tree
knossos review-diff project_... src/Checkout.php --json      # an explicit set
knossos review-diff project_... --base-ref=origin/main --json

The MCP forms take the same three shapes: {} for the working tree, files for an explicit set, base_ref for a Git range.

Policies and budgets default to knossos.json ​

If policies or budgets are omitted, review_diff reads the policies and quality_budgets keys of the project's knossos.json (or .jsonc) at query time: no separate check_architecture/quality_gate call is needed to exercise the project's own declared rules. Pass either explicitly (as with check_architecture and quality_gate) to override the file, including passing []/{} to opt out. The CLI accepts --policies=FILE and --budgets=FILE, read the same way as check-architecture and quality-gate.

Result shape ​

Each of the four sections carries its own status, 'evaluated' or 'not_evaluated' (with a reason in the latter case): a review with partial signal beats an error, so a missing config file, an unreadable project root, or the absence of a retained baseline snapshot degrades the affected section instead of failing the whole call:

  • change: the changed_files_impact result: changed_files, unresolved_files, direct_components, impacted_components, git.
  • policy_check: policies_evaluated; total_violations, the whole project's violation count; touching_violation_count, the exact number of violations whose source or target is a direct or impacted component of the change, or a file component (a shell script or another file no worker reads) whose path is one of the changed files; and violations_touching_change, the first 100 of those. The touching ones come from a check scoped to the change's components, not from the first page of the whole project's. not_evaluated when no policies are declared or supplied.
  • quality_gate: passed, checks, baseline_snapshot and baseline, computed against the most recently retained non-active snapshot unless baseline_snapshot is given explicitly. baseline names that snapshot, its source (previous_scan or argument), captured_at and age_seconds. The previous scan is often minutes old, so a pass means no regression since that scan, not since base_ref: base_ref only chooses the changed files. When base_ref is given and the gate used the previous scan, a warning says so; pass baseline_snapshot with a scan of that ref to gate against it. not_evaluated when no budgets are declared or supplied, or when no retained baseline snapshot exists yet.
  • cycles_touching_change: the subset of dependency_cycles's cycles with at least one member among the change's direct or impacted components or its changed file components, matched on every member (member_ids), not only the first 100 listed. not_evaluated (with a reason) if the cycle scan itself fails.

bounds mirrors changed_files_impact's bounds with cycle_scan_limit added. The envelope's evidence, warnings, and truncation flag are the union of the underlying calls': evidence from change, the policy check (when evaluated, the scoped check's evidence for the violations touching the change), the quality gate (when evaluated), and the cycle scan (when evaluated), capped at the first 100 rows; a section that degrades to not_evaluated contributes no evidence.

Results are static and conservative, subject to the same caveats as the underlying tools: impact is a blast-radius estimate that guarantees nothing; change frequency signals are absent here (see change_impact for those); and a truncated cycle or edge scan may under-report.

Changed-file impact ​

changed_files_impact maps a bounded set of changed project-relative files to their indexed components and then performs conservative reverse static impact analysis. It separates direct components, impacted dependants, known entry points, and unresolved paths.

In Claude Code you can see this without a call: the pane's Changes tab lists every file changed since the session began, with the files that depend on it and the tests that reach it.

The Changes tab after a turn edited hooks/lib/paths.ts: the file with its 16 dependents, the tests that reach it nearest first with the command to run them, and its detail with the diff since the session began

Pass explicit paths when a client already has a change set:

json
{
    "project_id": "project_...",
    "files": ["src/Checkout.php", "frontend/src/cart.ts"],
    "max_depth": 4,
    "limit": 100
}

Or explicitly opt into a read-only Git working-tree query:

json
{
    "project_id": "project_...",
    "working_tree": true,
    "base_ref": "main"
}

CLI equivalents are:

sh
knossos changed-files-impact project_... src/Checkout.php --json
knossos changed-files-impact project_... --working-tree --base-ref=main --json

The Git adapter resolves a supplied base ref to a commit, detects renames, and includes untracked files for the default working-tree comparison. Deleted and old rename paths can still resolve when they exist in the active indexed snapshot.

Results are static and conservative. Dynamic dispatch may be absent, unresolved paths are returned explicitly, and truncation means the reported set may be incomplete.

Test impact ​

test_impact finds the test files that statically reach the changed code, ranked by distance. It maps the changed files to their components the way changed_files_impact does, then runs a search of its own: a reverse breadth-first walk over every dependant, production and test alike, that keeps only the components classified quality.test_module. Production dependants cost a visit but never a place in the answer, so a test behind a hub with hundreds of callers is still found. Use it to run the relevant tests first in an edit-test loop; it is a lower bound, so keep running the full suite: data-driven tests, fixtures, and glob-only discovery are invisible to the graph.

The walk follows a launches edge, so a test that starts a script or a worker process is found through the code that names it. A launch hop does not count toward max_depth, which goes up to 12.

sh
knossos test-impact project_... src/Checkout.php --json
knossos test-impact project_... --working-tree --base-ref=main --json

The MCP form takes the same files / working_tree + base_ref inputs as changed_files_impact.

test_files is a list of {path, distance, via}, sorted by distance then path:

  • distance is the shortest static hop count from a changed component to a component classified quality.test_module in that file; 0 means the test file itself was in the changed set.
  • via names up to three of the test components (classes/functions) in that file responsible for the reachability, sorted and de-duplicated.

test_files_via_wiring has the same shape and holds the test files that reach the change only through a composition root: a method, function or class that constructs or injects at least six classes and makes fewer calls into the project than half that, such as a container's wiring method. Such a test builds the application rather than using the change, so it is listed after the direct ones. A file with any test that reaches the change some other way is only in test_files, and a change to the composition root itself reaches its tests directly.

changed_files and unresolved_files mirror changed_files_impact's fields. bounds reports the limits and what the search did:

  • max_files, max_direct_components, limit and max_depth: the change set and answer limits, as in changed_files_impact.
  • max_visited (50,000 components) and max_edges (500,000 relationships): the search's own bounds. timeout_ms bounds the whole request, and on a graph of a few hundred thousand relationships it is the bound met first.
  • visited_nodes and edges_examined: how far the search went.
  • test_files_found and test_files_via_wiring_found: how many test files of each kind the search reached before limit cut the lists. One limit covers both, the direct files first.
  • truncation_reasons: every bound that cut the answer, in the order met: changed_file_limit, direct_component_limit, visit_limit, edge_limit, time_limit, result_limit or depth_horizon.

When the search was cut, the summary says so and names the reasons, because test files beyond that bound are not listed. When only limit cut the list, the summary says how many of how many test files you are seeing. Reaching max_depth is the horizon you asked for, not a cut, but when the walk stops there with dependants still unread, depth_horizon joins truncation_reasons and the summary suggests a larger max_depth. A warning is always attached reminding you this is a lower bound.

Git change signals and time-aware impact ​

The Churn tab: a scatter of commits in the last 30 days against dependents, and the churn hotspots ranked by commits times dependents

In the pane, the Churn tab plots the files that change often against how much depends on them.

change_impact starts with the same bounded reverse static dependency analysis as impact_analysis, then reads recent Git history for the impacted components' indexed files.

Inputs include since_days, max_commits, static max_depth/relationship filters, a result limit, and timeout_ms. Per-file signals are recent commit count, distinct author email identifiers, and latest author timestamp. The risk ranking exposes its simple factors: three points per commit, one per distinct author, and a bounded static-proximity weight.

These are prioritization heuristics. They prove nothing about risk, ownership, code quality, or future failure. Renames are not followed, and history outside the selected window is absent. If Git is unavailable or the scanned root is not a repository, the tool returns the static impact with zero change scores and a reason instead of failing the whole query.

When history was read, git.available is true and git.reason is null. Otherwise git.reason says what stopped it, and the value distinguishes two different failures. unmatched_target and ambiguous_target mean the request never resolved to one component, so there is no blast radius to score and risk_ranking is empty: the first when symbol matched nothing, the second when it matched several. Every other value still carries the full static impact with zero change scores, either provider_unavailable when no Git provider is configured, or the Git error message itself, truncated to 500 characters. That last case is free-form, so read reason as a diagnostic string rather than a closed set of codes.