fallow: codebase intelligence for TypeScript and JavaScript

Surface only the consequential structural decisions a change embeds: a new cross-zone dependency edge, a new exported public-API surface, a new third-party dependency. Each one is framed as a judgment question, anchored to a deterministic graph-derived signal_id, paired with the routed expert to ask, and carries the named trade-off it makes. decision-surface is the apex of the review brief, emitted on its own: separable, cheap, and advisory.

fallow decision-surface --base main
fallow decision-surface --base main --format json --quiet
fallow decision-surface --base main --max-decisions 5

fallow decision-surface always exits 0. It is advisory, never a gate: the verdict is carried informationally, unlike fallow audit, which exits non-zero on a fail verdict. It answers “which one or two things here deserve a human judgment call?”, not “will CI block this?”.

When to reach for it

Three commands look at changed code; they answer different questions. Pick by the question you have.

You want to know	Command	Gates?
Will CI block this PR?	`fallow audit`	Yes (exits non-zero on a fail verdict)
Where do I look, across the whole change?	`fallow review` (the full brief: subtract, focus, structure, direct)	No (always exits 0)
Which few decisions deserve a human judgment call?	`fallow decision-surface` (just the structure job)	No (always exits 0)

fallow review produces the complete brief: it subtracts mechanical findings out of the judgment loop, ranks every changed unit into a focus map, surfaces the decision surface, and emits the agent walkthrough contract. fallow decision-surface runs the same changed-code analysis but emits only the decisions, then discards the rest of the brief (the subtract list and the weighted focus map). Reach for it when you do not need the focus map or the walkthrough scaffolding, just the handful of structural choices the diff bakes in. It is the cheapest way to get the apex of the brief.

In a PR loop, run fallow audit for the pass/warn/fail gate and fallow decision-surface for the “ask a human about these” list. They are complementary: the gate catches mechanical regressions, the decision surface catches the consequential choices the gate is silent on.

What a decision is

A change can touch hundreds of lines and still embed only one or two choices that are expensive to walk back. The decision surface isolates those. Every entry is a framed judgment question with the context an agent or reviewer needs to answer it, not a recommendation. fallow never tells you which way to choose. The surface has exactly three shippable categories:

Category	Meaning
`coupling-boundary`	A new cross-zone dependency edge.
`public-api-contract`	A new exported public-API surface, or a changed contract consumed by modules outside this diff.
`dependency`	A new third-party dependency.

The set is ranked by consequence (blast radius x reversibility) and capped to a small, working-memory-sized list: 3 to 5 decisions, default 4, via --max-decisions. The cap is the point: a reviewer can hold a handful of structural questions in their head, not a flat wall of findings.

What each decision carries

Field	What it is
The question	The judgment framed as a question, the thing a human should weigh in on.
`routed_expert`	Who to ask. The decision points at the person or role whose judgment the category calls for, so the question reaches the right reviewer.
`signal_id`	The deterministic, graph-derived anchor for this decision. Stable across runs against the same tree, and the join key for re-attaching review comments.
`tradeoff`	The named structural sacrifice, stated as a fact (never a recommendation). For example: `"Couples app to infra; 4 in-repo modules already depend on this anchor"`.
`internal_consumer_count`	The honest count of in-repo modules outside the diff that already depend on the anchor. This is your reversibility signal: the higher the count, the more expensive it is to walk this back. It is the display number, distinct from the ranking-only blast figure.
`previous_signal_id`	Optional. The `signal_id` the anchor had before a rename of its anchor file, so a review surface can re-attach a prior comment across a `git mv`.

internal_consumer_count is the number you read reversibility from, and it is distinct from the internal blast figure used only to rank the list. The human view shows the question and the trade-off; you infer the reversibility yourself from the count. fallow never labels a decision as reversible or irreversible for you.

Every decision is suppressible with an inline // fallow-ignore comment, the same way findings are suppressed elsewhere in fallow. Place the comment at the decision’s anchor to drop it from the surface. Suppression removes a decision from the output; it does not change the verdict, because decision-surface never gates.

How an agent consumes it

The decision surface is built for agents. The recommended shape is: get the JSON, walk decisions[], and for each one decide whether it needs a human, using internal_consumer_count as the reversibility signal and the tradeoff clause as the stated cost.

fallow decision-surface --base main --format json --quiet

A typical agent flow:

Read decisions[]. It is already ranked and capped, so the first entry is the most consequential.
For each decision, surface the question and the routed_expert to the human, not the raw diff.
Use internal_consumer_count to decide how loudly to flag it: 0 is a cheap, reversible choice; a high count is a load-bearing anchor that is expensive to undo.
Quote the tradeoff clause verbatim. It is a fact, so an agent can relay it without editorializing.
Anchor any comment to signal_id. If the run reports a previous_signal_id, re-attach a prior comment across the rename instead of posting a duplicate.

The digest the decision surface is built from comes from the graph only; PR prose is never folded into it. An agent can trust that the surfaced decisions reflect the actual structural change, not a description of it.

Picking the comparison point

decision-surface scopes to changed code exactly like fallow audit. Use --base (or its --changed-since alias) to pick what “changed” means. When omitted, the base is the git merge-base against the branch’s upstream or the remote default (origin/main); set FALLOW_AUDIT_BASE to pin it without a flag.

# Against the merge-base with the default branch (auto-detected)
fallow decision-surface

# Explicit base ref
fallow decision-surface --base main

# Decisions embedded in the last 5 commits
fallow decision-surface --base HEAD~5

Options

Flag	Description
`--base <REF>`	Git ref to compare against (e.g. `main`, `HEAD~5`, a commit SHA). Alias for `--changed-since`. When omitted, the base is the `git merge-base` against the branch’s upstream or the remote default (`origin/main`); set `FALLOW_AUDIT_BASE` to pin it without a flag.
`--changed-since <REF>`	Alias for `--base`. Scope the comparison to changes since this git ref.
`--max-decisions <N>`	Cap on the number of consequential structural decisions surfaced (the working-memory limit). Default 4; clamped to a 3 to 5 band. Values outside the band are clamped, not rejected.
`-f, --format <FORMAT>`	Output format: `human` (default) or `json`.
`-r, --root <PATH>`	Project root directory.
`-c, --config <PATH>`	Path to a fallow config file.
`-w, --workspace <NAME>`	Scope to a single workspace package.
`-q, --quiet`	Suppress progress and status output on stderr.

See global flags for the full list.

Examples

# Auto-detect base; render the decisions for a human
fallow decision-surface

# Explicit base ref
fallow decision-surface --base main

# Widen to the full 3 to 5 band
fallow decision-surface --base main --max-decisions 5

# JSON for an agent to walk decisions[]
fallow decision-surface --base main --format json --quiet

# Environment variables work too
FALLOW_FORMAT=json FALLOW_QUIET=1 fallow decision-surface --base main

# Scope to one workspace package
fallow decision-surface --base main --workspace @app/api --format json

Example output

$ fallow decision-surface --base main

Decision surface: 3 decisions vs main (d4a2f91..HEAD)

● coupling-boundary  (ask: architecture owner)
  src/app/checkout.ts → src/infra/queue.ts
  Should the app zone depend directly on infra here?
  trade-off: Couples app to infra; 4 in-repo modules already depend on this anchor.
  internal consumers: 4

● public-api-contract  (ask: API owner)
  src/lib/client.ts:createClient
  This export is now public surface consumed outside the diff. Is the contract right?
  trade-off: Locks the createClient signature for external callers.
  internal consumers: 2

● dependency  (ask: platform owner)
  package.json → fast-xml-parser
  A new third-party dependency enters the graph. Is it warranted?
  trade-off: Adds a third-party maintenance and supply-chain surface.
  internal consumers: 0

The human view shows the question and the trade-off; you read reversibility from internal_consumer_count directly.

JSON output

fallow decision-surface --format json carries a ranked, capped decisions[] array. Each entry is the framed judgment question with its anchor, routed expert, trade-off, and consumer count. This is the same decision surface fallow review --format json carries under its decisions key.

$ fallow decision-surface --base main --format json

{
  "command": "decision-surface",
  "base_ref": "main",
  "head_sha": "d4a2f91",
  "decisions": [
    {
      "signal_id": "coupling:app/checkout->infra/queue",
      "category": "coupling-boundary",
      "question": "Should the app zone depend directly on infra here?",
      "routed_expert": "architecture owner",
      "tradeoff": "Couples app to infra; 4 in-repo modules already depend on this anchor",
      "internal_consumer_count": 4
    },
    {
      "signal_id": "public-api:lib/client:createClient",
      "category": "public-api-contract",
      "question": "This export is now public surface consumed outside the diff. Is the contract right?",
      "routed_expert": "API owner",
      "tradeoff": "Locks the createClient signature for external callers",
      "internal_consumer_count": 2,
      "previous_signal_id": "public-api:lib/old-client:createClient"
    }
  ]
}

Key fields

Field	Type	Description
`decisions[].signal_id`	string	Deterministic, graph-derived anchor for the decision. Stable across runs against the same tree; the join key for re-attaching comments.
`decisions[].category`	`"coupling-boundary"` \| `"public-api-contract"` \| `"dependency"`	The kind of structural choice.
`decisions[].question`	string	The judgment framed as a question.
`decisions[].routed_expert`	string	Who to ask: the reviewer whose judgment the category calls for.
`decisions[].tradeoff`	string	The named structural sacrifice, stated as a fact.
`decisions[].internal_consumer_count`	integer	In-repo modules outside the diff that already depend on the anchor. The reversibility signal.
`decisions[].previous_signal_id`	string \| null	Present when the anchor was renamed: the prior `signal_id`, for re-attaching a comment across a `git mv`.

Decisions are ordered by consequence, so the first entry is the most worth a human’s time. The list is capped to --max-decisions; there is no pagination, by design. The point is the short list.

MCP tool

The decision surface is also exposed as the decision_surface MCP tool, so an agent gets the same ranked, capped, signal_id-anchored decisions through structured tool calling:

Example request

{
  "tool": "decision_surface",
  "arguments": {
    "base": "main",
    "max_decisions": 4
  }
}

Set base to specify the comparison ref and max_decisions to cap the surfaced decisions (default 4, clamped to a 3 to 5 band). Like the CLI, the brief always exits 0 and the verdict is carried informationally; it never gates. See MCP integration for the full tool list and setup.

Audit and review brief

The gating audit, plus the full review brief that the decision surface is the apex of.

Trace a call chain

Walk the callers and callees of one exported symbol before you change it.

MCP integration

Use the decision_surface tool from AI coding agents.

Commands

fallow decision-surface

When to reach for it

What a decision is

What each decision carries

How an agent consumes it

Picking the comparison point

Options

Examples

Example output

JSON output

Key fields

MCP tool

See also

Audit and review brief

Trace a call chain

MCP integration

​When to reach for it

​What a decision is

​What each decision carries

​How an agent consumes it

​Picking the comparison point

​Options

​Examples

​Example output

​JSON output

​Key fields

​MCP tool

​See also

Audit and review brief

Trace a call chain

MCP integration

When to reach for it

What a decision is

What each decision carries

How an agent consumes it

Picking the comparison point

Options

Examples

Example output

JSON output

Key fields

MCP tool

See also