NODEDC_1C/docs/ARCH/11 - architecture_turnaround/README.md

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

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: 5371 nodes, 11523 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;
  • product shaping is now secondary debt, not the primary blocker.
• 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

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

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

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

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.