NODEDC_1C/docs/ARCH/11 - architecture_turnaround

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

1. 01 - project_architecture_baseline_map.md
2. 02 - state_and_transition_contracts.md
3. 03 - capability_contract_spec.md
4. 04 - coverage_evidence_truth_gate.md
5. 05 - assistantService_extraction_map.md
6. 06 - phase_acceptance_matrix.md
7. 07 - external_reference_appendix.md
8. 08 - current_status_audit_2026-04-17.md
9. 09 - pre_expansion_cut_2026-04-17.md
10. 10 - regression_breakpoint_analysis_2026-04-17.md
11. 11 - continuity_stabilization_plan_2026-04-17.md
12. 12 - manual_run_system_analysis_3NilqwT1G2_2026-04-18.md
13. 13 - pre_multidomain_readiness_audit_2026-04-18.md
14. 14 - semantic_dialog_authority_recovery_plan_2026-04-19.md

Current Status Snapshot (2026-04-19)

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, but still not ready for wide multi-domain expansion:

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

Current honest status:

• turnaround implementation progress: ~96%
• exit-from-danger-zone readiness: ~91%
• pre-multidomain readiness: ~78%
• graph snapshot after latest rebuild: 5372 nodes, 11525 edges, 135 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 final convergence toward one true runtime authority plus replay breadth still below the intended multi-domain blast radius;
  • pure wording polish is now secondary debt, but semantic robustness of user-facing answers is now a first-class blocker;
  • the practical product risk is no longer "the route collapsed", but "a new user can still feel that the assistant is glitchy, misses intent, or answers the wrong thing on short live wording".
• main remaining architectural pressure:
  • no single fully authoritative continuity contract consumed by every hot runtime owner
  • residual coordinator/legacy pressure inside assistantService.ts
  • central domain-intent pressure inside resolveAddressIntent()
  • replay breadth still narrower than the intended multi-domain rollout surface beyond the flagship and late-switch families
  • remaining answer-semantics pressure inside composeStage.ts / answerComposer.ts
  • insufficient semantic robustness on live user wording, especially short follow-up retarget, typo tolerance, and intent-faithful human answers
  • no guarded MCP semantic discovery lane yet for understood long-tail 1C questions that should not require one-off route hardcoding

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

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 now 90%+ pre-multidomain readiness, and the remaining gap should be treated as five large architecture iterations rather than as cosmetic cleanup.
• 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 would feel that the assistant understands the intent and responds meaningfully in live wording.

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

• 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

Architectural Objects Of Planning

This package makes five objects explicit:

1. state model
2. transition model
3. capability contract model
4. coverage / evidence / truth gate
5. assistantService extraction plan

These are the objects that should now drive refactoring discussions.

How To Use The Package

Read in this order:

1. baseline note in docs/ARCH/11 - unified_project_architecture_and_reference_update_plan_2026-04-15.md
2. 01 - project_architecture_baseline_map.md
3. 02 - state_and_transition_contracts.md
4. 03 - capability_contract_spec.md
5. 04 - coverage_evidence_truth_gate.md
6. 05 - assistantService_extraction_map.md
7. 06 - phase_acceptance_matrix.md
8. 07 - external_reference_appendix.md
9. 08 - current_status_audit_2026-04-17.md
10. 09 - pre_expansion_cut_2026-04-17.md
11. 10 - regression_breakpoint_analysis_2026-04-17.md
12. 11 - continuity_stabilization_plan_2026-04-17.md
13. 12 - manual_run_system_analysis_3NilqwT1G2_2026-04-18.md
14. 13 - pre_multidomain_readiness_audit_2026-04-18.md
15. 14 - semantic_dialog_authority_recovery_plan_2026-04-19.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-19, 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 toward one runtime authority plus still-insufficient replay breadth for low-risk multi-domain expansion.

The biggest remaining blockers are:

• split continuity ownership across route / transition / recap / coordinator glue;
• saved-session acceptance still too narrow compared with the intended domain-expansion blast radius outside the repaired flagship + late-pivot families;
• clarification precedence is much better than before, but still not yet proven widely enough outside the repaired replay family;
• residual assistantService overload;
• central intent pressure in resolveAddressIntent();
• remaining answer-semantics pressure in composeStage.ts and answerComposer.ts.
• 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.
• missing MCP semantic data-discovery layer where Qwen3 can help plan controlled 1C evidence search without bypassing runtime truth gates.