Module decision_surface 

Decision-surface extractor (stage 6 / 6.G): THE product.

The apex of the review brief. A change embeds many decisions; almost all are mechanical and a few are consequential enough to need human taste. This extractor lifts the consequential STRUCTURAL decisions out of the scattered diff, frames each as a judgment question, ranks by consequence (blast x reversibility), caps the surface to a working-memory-sized handful (4 plus or minus 1), collapses the mechanical remainder, and pairs each decision with the routed expert (“who to ask”).

The SOLID-3 (the ONLY categories that ship)

Per the verdict (.plans/agentic-review-e0-verdict.md) the decision categories are NOT uniformly reliable on a syntactic engine (ADR-001). Exactly three are validated and shippable, each backed by a deterministic signal fallow already emits:

1. coupling/boundary (boundary_introduced): a new cross-zone edge.
2. public-API/contract (public_api_added + coordination gaps): a new exports-aware public surface, or a changed contract consumed by modules outside the diff.
3. dependency: a changed package.json that adds third-party entries or moves one across a major version (dependency_added / dependency_major_bumped), batch-consolidated per manifest per kind and weighted by the graph’s in-repo importers of the affected packages.

The four CUT categories (abstraction-with-1-implementor, deletion-still- reachable, convention-divergence, irreversibility/migration) are CONFIRMED NOISE and MUST NOT ship. DecisionCategory has exactly three discriminants, so a cut category is not even representable: the type system is the guarantee.

The trust mechanism (anti-hallucination)

Post-validation closes on EXTRACTION, not on framing. Every decision carries a signal_id deterministically derived from the fallow-emitted candidate key it frames (a delta key or a coordination-gap key). The deterministic layer keeps the SET of signal_ids it emitted; DecisionSurface::accept_signal_id returns true iff an id is in that set. An agent-proposed decision whose signal_id was never emitted is REJECTED. The agent proposes; the graph disposes.

Structs

BoundaryAnchor

A representative boundary violation used to anchor a coupling/boundary decision to a file + line. Decoupled from the fallow_types finding type so the extractor unit-tests without constructing full findings.

CoordinationAnchor

A coordination gap projected onto the public-API/contract decision shape: a changed contract consumed by a module outside the diff.

Decision

One consequential structural decision, framed as a judgment question for a human with taste, anchored to a fallow-emitted signal.

DecisionInputs

All inputs the extractor needs, gathered from the assembled brief data.

DecisionSurface

The ranked, capped decision surface plus the set of signal_ids the deterministic layer emitted (the anti-hallucination allowlist).

DependencyAnchor

A changed manifest’s dependency candidates of one kind, batch-consolidated per manifest (rule R1): a reviewer reads “3 new dependencies”, never one decision per package. The importer counts come from the graph’s package usage, so the decision carries the modules the change actually reaches.

DependencyEntry

One declared dependency entry inside a dependency decision.

TruncationNote

A note for decisions collapsed below the cap.

Enums

DecisionCategory

The exactly-three shippable decision categories (the SOLID-3). No cut category (abstraction / deletion / convention / irreversibility) is representable: this enum is the structural guarantee that confirmed-noise categories never ship.

DependencyChangeKind

Which manifest change a dependency decision frames.

Constants

DEFAULT_DECISION_CAP

Default decision-surface cap (the working-memory limit). The surface holds at most this many ranked decisions; the rest collapse into a truncation note.

MAX_DECISION_CAP

Upper bound on the configurable cap (4 plus 1).

MIN_DECISION_CAP

Lower bound on the configurable cap (4 minus 1).

Functions

build_decision_surface_output

Project a DecisionSurface into the separable, action-bearing envelope.

derive_signal_id

Derive a deterministic, content-addressed signal_id from a category tag plus the fallow-emitted candidate key. The tag namespaces the key so a boundary key and a public-API key sharing text never collide. Pure: same inputs always yield the same id (byte-identical across runs).

extract_decision_surface

Extract the full decision surface from the assembled brief inputs: classify the SOLID-3 candidates, anchor each signal_id, rank by consequence, cap to the working-memory limit, collapse the rest, and drop suppressed decisions.