CodeScanner

Reads

The repository, locally. Before any call is made, Spec4 walks the tree, measures it, and chooses the evidence the model receives from that measurement rather than from walk order, within a budget of 24,000 tokens (scan_context_tokens in the model settings overrides it). The evidence is assembled in four tiers, each with its own share of the budget:

Within each tier, files reached from an entry point go first. A block that doesn't fit is skipped, so a smaller one later in the order can still use the room; an __init__.py under 20 lines never takes a slot. Test files are outside the graph and outside the samples. On Spec4's own tree this is 4 bodies, 17 signature files, and every src/ module named, at about 17,400 tokens of evidence.

Skipped: .git, node_modules, .venv, __pycache__, dist, build, target, .next, .spec4, and the other cache and vendor directories.

Before the call, the chat shows how many files were indexed and roughly how many tokens are about to be sent, and to which model. Nothing else leaves the machine. What was shown is recorded in scan.coverage, by the code that pastes it, so the review says what the model saw.

Writes

code_review.json, as an envelope with schema_version: 2 and two objects. The model emits a bare review block, validated on its own; the envelope is assembled and validated again at commit, and a review that fails validation is written to .spec4/failures/ and re-asked once.

The scan layer

Computed from the same walk the model is shown, and held until the model's block is committed. Each block is optional and closed, so a review from an earlier 2.x is still read:

The review layer

• project_type, languages, frameworks, build_system, commands, entrypoints, ui_summary, and notes are required when the directory holds a software project.
• Every fact carries a source — the file it was read from — or inferred_from — the file it was deduced from. A fact with neither is not written.
• commands has a closed set of keys: build, test, lint, typecheck, run, dev, deploy. entrypoints likewise: main, wsgi_app, cli_script, dev_server, ui_root. Anything else the project has goes in notes.other_notes as a line of text, so a downstream agent reading commands.test always finds the same thing.
• load_bearing: one entry per candidate the scan named, with its role and contract — inputs, outputs, invariants, side effects. Its consumers are filled from the graph at commit, replacing whatever the model emitted, so the stored list is always the measured one.
• implemented: what is built, each with a status of complete, partial, stub, or scaffolded_only, its paths, and the ids of the prior round's features it realizes.
• integrations: each external service by name and kind — an LLM provider, a database, a cache, a queue, a web search, an MCP server, and the rest of StackAdvisor's vocabulary — with its client module, the names of its environment variables (never values), and its purpose.
• prior_round_reconciliation: one entry per phase of the previous round, with a verdict — evidence_found, evidence_partial, no_evidence_found, or unassessed for a phase that declared no features — computed at commit from implemented against the features the phase declared. The model contributes only the gap for a phase it judges short.
• unplanned_changes: three to ten entries, grouped by area, for what entered the codebase outside any plan; classified out_of_round at commit when a path it names is among the most-touched or added files.
• divergences: where the built stack departs from the planned one — planned, found, and a kind of renamed, replaced, dropped, added, or reshaped. Never a dependency name; plan_drift has those.
• A key the model can't verify is omitted, never filled with "none" or "n/a".
• notes.change_risks records where a change is likely to break something; StackAdvisor is told to read it before proposing a swap. notes.security_observations and existing_self_description (quoted from the README or a package description, never from a config file) are also there.
• An empty directory, or one without code, gets is_software_project: false and a one-line summary.

Later agents don't receive the file as pasted JSON. Brainstormer, StackAdvisor, and Phaser each get a rendered view of exactly the blocks they read, each block under one line of guidance, with values verbatim and their source or inferred_from in brackets; a field the renderer has no special knowledge of still reaches them. The views carry measured facts beside the model's judgments: Phaser reads load_bearing, implemented, the reconciliation, the unplanned changes, and a coverage line; StackAdvisor reads integrations, divergences, the drift's planned_unmatched and declared_not_planned, and the dependency delta; Brainstormer reads implemented and the unplanned changes. Deployer reads integrations and is told to plan against the committed tree when the scan found it dirty; Agentifier's Scout reads through a view of its own. No raw review JSON reaches a downstream model, and none of them receives scan whole.

A probe, evals/code_scanner/review_reach.py, showed why the views exist: with the raw paste, fields a prompt named reached the plan and fields it didn't mostly didn't, and StackAdvisor recorded its prompt example's ESLint and Prettier in eight rounds out of eight for a codebase whose review said oxlint.

Excerpts of both layers are on the Artifacts page.

Asks

Nothing, by default. The scan and the draft are one call. After the review is drafted you can reply in the chat to correct or extend it — CodeScanner re-emits the review block — or press Modify later to reopen it. Re-scan Project, in the action row under a finished review, walks the tree again.

Web search, if you've given it a key, is available to CodeScanner for the standards and protocols it names.

A review block that fails schema validation is written to .spec4/failures/code_scanner_review_<n>.txt — the validator's errors first, then the raw reply — before the re-ask, and again if the re-ask fails too. Nothing in the chat is lost; the file is there so a failure can be read rather than remembered.

Buttons

CodeScanner has no upstream artifact, so it is never Needs Update or Not Ready. A directory you answered New project to skips it and starts with Brainstormer.

Across rounds

Every round after the first begins with a re-scan, and the re-scan reads the code as it stands: what the coding agent built, what you changed by hand, and what the previous round's plan never mentioned. That is what makes the next round a plan against the code rather than against the last plan. Rounds

The review is not rewritten from scratch. The scan finds the previous round's review, measures the delta from it, and hands the model that review with the exact list of paths that changed since it. An entry whose source path isn't on the list is carried verbatim; the model re-derives only where the list names the path, adds for paths it adds, and drops for paths it removes, and it reuses the id of a capability the prior review already names. What it drops anyway from an untouched file — an environment variable, a dependency, an endpoint — is put back at commit, keyed by name and in the prior's order, and scan.delta.carried records how many were put back and against which baseline. On BWS4's first scan after its v9 round, under 2.9.2, the model dropped 10 of 22 environment variables and 21 of 46 dependencies whose source files hadn't changed; the carry restores both lists. The committed v10 review, scanned under 2.11.1 with the carry rule in the seed, records carried: {env_vars: 0, dependencies: 0, api_surface: 0} — the model kept every untouched entry itself. With no prior review, no delta, or a truncated file list, the carry is suspended and the seed says so.

The drift is measured, not recalled. The scan compares what the last round planned with what the manifests now declare and what files in the tree witness, and lists what changed as files, signatures, manifests, and load-bearing modules, so the agents read what changed as a list rather than as the model's recollection of it.

A review written under an older schema isn't read as current. The gate above fires, and the re-scan starts fresh — the fresh seed with the old review appended as context — rather than asking for a merge into a shape the current version doesn't read.