NODEDC_1C/docs/ARCH/11 - architecture_turnaround/20 - planner_autonomy_consolidation_2026-05-01.md

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.