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 new package.json dependency entry (the arm is present; its candidate source is a dependency delta not yet threaded on the brief path, so it produces decisions only once that delta lands, never a fabricated signal).

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).

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.

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.