10 KiB

Raw Blame History

11 - Architecture Turnaround Package

Purpose

This folder is the execution-oriented continuation of the baseline note:

11 - unified_project_architecture_and_reference_update_plan_2026-04-15.md

That baseline note answers:

what the project is today;
where the main architectural fragility sits;
what direction is safe.

This package answers the next question:

how the team should design the architectural turnaround without breaking the current exact-data baseline.

Package Contents

Current Status Snapshot (2026-04-22)

This package is no longer planning-only.

It now documents a turnaround that is already operational in code, already materially past the acute regression breakpoint, and already moved into bounded MCP autonomy work beyond the first stabilization wave:

route, transition, boundary, meta, memory, and provider policy owners exist as separate modules;
exact-lane truth and coverage/evidence contracts exist as explicit runtime artifacts;
scenario acceptance writes machine-readable scenario_acceptance_matrix.json and pack_state.json;
AGENT semantic packs and source catalogs already exist for mixed domain/meta validation.
the reset toward MCP-first bounded autonomy is now formalized;
Big Block A/B/C of that reset are now closed in runtime code and replay-backed;
the next architecture mainline is no longer continuity polishing, but D/E/F:
- Question -> Data Need Graph
- dynamic schema traversal and primitive search
- multi-hop evidence loop with bounded clarification recovery

Current honest status:

turnaround implementation progress: ~96%
exit-from-danger-zone readiness: ~91%
pre-multidomain readiness: ~78%
bounded-autonomy foundation readiness: ~60%
graph snapshot after latest rebuild: 5741 nodes, 12385 edges, 137 communities
current breakpoint:
- the validated hot paths are no longer structurally broken;
- flagship continuity collapse is no longer the primary risk;
- the main remaining risk is no longer clarification-resume collapse, but the unfinished shift from bounded reviewed chains toward open-world data-need-driven MCP planning;
- pure wording polish is now secondary debt, but semantic robustness plus open-world evidence navigation is now a first-class blocker;
- the practical product risk is no longer only "the route collapsed", but "the assistant still cannot yet understand and explore many non-preworked 1C questions on its own".
main remaining architectural pressure:
- no general Question -> Data Need Graph authority yet
- planner chain selection is still reviewed-family bounded rather than open-world over the primitive catalog
- schema traversal is still narrower than the intended arbitrary 1C blast radius
- multi-hop evidence recovery is still too shallow for unfamiliar asks
- central domain-intent pressure inside resolveAddressIntent()
- replay breadth is still below the future open-world autonomy surface

Latest live proof now includes:

address_truth_harness_phase12_wider_saved_session_pool_live_20260419_rerun16 accepted 20/20
address_truth_harness_phase14_counterparty_tail_resume_live_20260418_rerun2 accepted 10/10
address_truth_harness_phase15_answer_inspection_followup_live_20260419_rerun11 accepted 9/9
address_truth_harness_phase16_multicompany_late_pivot_live_20260419_rerun10 accepted
address_truth_harness_phase17_clarification_resume_and_counterparty_tail_live_20260419_rerun5 accepted 10/10
address_truth_harness_phase24_metadata_lane_choice_loop_live_rerun5 accepted
address_truth_harness_phase25_entity_resolution_chain_live_rerun_full_chain accepted
address_truth_harness_phase32_planner_selected_chain_end_to_end_live_rerun2 accepted 6/6

Current architectural reading:

the system is already materially past the dangerous regression breakpoint;
it is now safe for continued architecture hardening and controlled domain-by-domain enablement under replay gates;
it is now materially closer to pre-multidomain stability, but still not safe to declare broad low-risk multi-domain expansion.
the practical next target is no longer only 90%+ pre-multidomain readiness, but the first believable open-world bounded autonomy over 1C evidence.
from this point onward, readiness must be judged not only by route truth and replay pass rate, but also by whether a new human user can ask a structurally new 1C data question and still get a bounded, evidence-honest answer path.

For the detailed audit, current percentages, and remaining debt, read:

Architectural Objects Of Planning

This package makes five objects explicit:

state model
transition model
capability contract model
coverage / evidence / truth gate
assistantService extraction plan

These are the objects that should now drive refactoring discussions.

How To Use The Package

Read in this order:

baseline note in docs/ARCH/11 - unified_project_architecture_and_reference_update_plan_2026-04-15.md
01 - project_architecture_baseline_map.md
02 - state_and_transition_contracts.md
03 - capability_contract_spec.md
04 - coverage_evidence_truth_gate.md
05 - assistantService_extraction_map.md
06 - phase_acceptance_matrix.md
07 - external_reference_appendix.md
08 - current_status_audit_2026-04-17.md
09 - pre_expansion_cut_2026-04-17.md
10 - regression_breakpoint_analysis_2026-04-17.md
11 - continuity_stabilization_plan_2026-04-17.md
12 - manual_run_system_analysis_3NilqwT1G2_2026-04-18.md
13 - pre_multidomain_readiness_audit_2026-04-18.md
14 - semantic_dialog_authority_recovery_plan_2026-04-19.md
15 - mcp_bounded_autonomy_reset_plan_2026-04-21.md
16 - data_need_graph_and_open_world_mcp_plan_2026-04-22.md

Planning Rules

Do not treat this package as a rewrite plan.
Do not dissolve AddressQueryService into generic chat logic.
Do not move state back into transcript-only memory.
Do not let answer wording substitute for policy/runtime fixes.
Use scenario-based acceptance as the primary gate for all phases.

Expected Outcome

When this package is fully operational, the project should stop being described as:

"a big custom assistant service with many heuristics"

and start being described as:

"a stateful exact-data assistant with explicit transition contracts and isolated truth gating."

As of 2026-04-22, the project is already materially closer to the target description and is no longer in the same acute collapse state. The remaining blocker is no longer the original continuity failure itself, but the unfinished convergence from reviewed bounded MCP chains toward open-world data-need-driven autonomy with replay breadth still below the future blast radius.

The biggest remaining blockers are:

no general Question -> Data Need Graph runtime authority yet;
planner-selected primitive chains are real, but still narrower than open-world primitive search;
dynamic schema traversal is not yet broad enough for unfamiliar 1C asks outside the repaired families;
multi-hop evidence recovery still depends on bounded reviewed seams and not yet on a general exploration loop;
residual assistantService overload;
central intent pressure in resolveAddressIntent();
semantic robustness gaps where already-supported questions can still look broken to a human user because of typo sensitivity, short follow-up retarget loss, or human-answer mismatch.

10 KiB Raw Blame History