# 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, value-flow, and metadata-lane scoring consolidation steps:

- `npm.cmd test -- assistantMcpCatalogIndex.test.ts assistantMcpDiscoveryPlanner.test.ts`: passed, `47 passed`
- MCP-discovery suite: passed, `227 passed`, `9 skipped`
- `npm.cmd run build`: passed
- graphify rebuild: `5911 nodes`, `12830 edges`, `138 communities`
- live value-flow canary: `address_truth_harness_phase66_human_org_open_scope_dialog_planner_template_rerun2`, accepted `7/7`
- live metadata movement canary: `address_truth_harness_phase52_metadata_movement_full_recovery_planner_metadata_scoring_rerun2`, accepted `4/4`
- live metadata document canary: `address_truth_harness_phase54_metadata_document_full_recovery_planner_metadata_scoring_rerun2`, accepted `4/4`

Additional code-level consolidation:

- ambiguous metadata surfaces no longer carry both document and movement primitives when the current data-need graph explicitly selects `document_evidence` or `movement_evidence`;
- thin neutral metadata follow-ups still do not force a lane and keep the clarification boundary intact;
- planner reason codes now expose when an explicit lane family is scored against carried metadata ambiguity:
  `planner_metadata_surface_scored_with_explicit_lane_family`.

## Next Step

The next safe step is to continue from catalog-instantiated known chain templates and first scoring rules into stronger bounded inference templates.

Recommended order:

1. lifecycle evidence template with stronger bounded inference semantics;
2. inventory-stock evidence templates only after the generic fabric remains stable under one more replay slice;
3. broaden catalog scoring beyond explicit document/movement lane choice into unfamiliar 1C asks;
4. keep value-flow and metadata ambiguity canaries as Post-F regression gates.

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.