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