# 20 - Planner Autonomy Consolidation (2026-05-01)

## Purpose

This note starts the consolidation layer after the first accepted inventory-stock breadth proof.

The goal is to move from:

- domain pack proves one more slice;
- planner still carries too many local recipe branches;

to:

- reusable MCP primitive and chain descriptors;
- planner-selected route fabric;
- domain packs as semantic gates, not as the main design mechanism.

This is the continuation of the original "MCP as bounded brain" goal.

## Architectural Reading

The target is not an unrestricted model agent.

The target remains:

`user question -> data_need_graph -> catalog chain template -> reviewed primitives -> bounded evidence loop -> truth gate -> answer`

The LLM may help choose the path, but only inside reviewed MCP boundaries.

## Code Steps

The first consolidation step adds reusable chain templates to `assistantMcpCatalogIndex`.

The catalog now describes not only primitive contracts, but also planner route-fabric templates:

- `metadata_inspection`
- `catalog_drilldown`
- `entity_resolution`
- `document_evidence`
- `movement_evidence`
- `value_flow`
- `value_flow_comparison`
- `value_flow_ranking`
- `lifecycle`

Each template declares:

- semantic data need;
- human-readable chain summary;
- fallback primitive sequence;
- base required axes;
- supported fact/action families;
- planning tags;
- evidence-gate requirement.

The planner now instantiates selected evidence chains from this catalog for the first base lanes instead of keeping all route meaning only in local planner branches.

The follow-up consolidation step moved the value-flow planner seams onto the same catalog fabric:

- bidirectional incoming-vs-outgoing comparison now instantiates `value_flow_comparison`;
- ranked revenue/payment questions now instantiate `value_flow_ranking`;
- organization-scoped open totals now instantiate `value_flow` with subjectless primitives but catalog-owned axes and evidence-gate semantics;
- heuristic fallback routes for value-flow, lifecycle, metadata, movement, document, entity, and unclassified metadata inspection now also use catalog chain templates.

This keeps behavior stable while making the planner's route meaning inspectable through catalog descriptors instead of only through local `recipeFor()` branches.

## Why This Matters

This reduces the pressure to add one hard route per user wording.

Future domain enablement should prefer:

- add or strengthen primitive descriptors;
- add or strengthen chain templates;
- let data-need graph and catalog search assemble the path;
- use domain packs to verify the scenario tree and catch semantic drift.

Domain-specific exact recipes can still exist as fast paths, but they should not be the only way the assistant understands a new business question.

## Validation

Local validation after the catalog-template and value-flow consolidation steps:

- `npm.cmd test -- assistantMcpCatalogIndex.test.ts assistantMcpDiscoveryPlanner.test.ts`: passed, `46 passed`
- MCP-discovery suite: passed, `226 passed`, `9 skipped`
- `npm.cmd run build`: passed
- graphify rebuild: `5908 nodes`, `12815 edges`, `138 communities`

## Next Step

The next safe step is to move beyond catalog-instantiated known chain templates into broader catalog scoring and live proof.

Recommended order:

1. metadata-scoped document/movement continuation scoring, not only template instantiation;
2. lifecycle evidence template with stronger bounded inference semantics;
3. inventory-stock evidence templates only after the generic fabric is stable;
4. a small live semantic canary that proves catalog-instantiated value-flow still preserves Post-F stale-scope and clarification invariants.

The key rule remains:

- do not hide a domain workaround inside the planner;
- promote repeated successful domain behavior into a reviewed primitive or chain template.