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

Current Status Snapshot (2026-04-18)

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: ~90%
• exit-from-danger-zone readiness: ~78%
• pre-multidomain readiness: ~58%
• graph snapshot after latest rebuild: 5339 nodes, 11476 edges, 134 communities
• current breakpoint:
  • the validated hot paths are no longer structurally broken;
  • but mixed continuity is still not governed by one fully central runtime authority;
  • wider saved-session proof is still too narrow for low-risk multi-domain rollout;
  • answer shaping is still heavier and more template-driven than the target product feel.
• main remaining architectural pressure:
  • no single fully authoritative continuity contract consumed by all hot runtime owners
  • residual coordinator/legacy pressure inside assistantService.ts
  • central domain-intent pressure inside resolveAddressIntent()
  • remaining answer-semantics pressure inside composeStage.ts / answerComposer.ts

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-18, the project is already materially closer to the target description and no longer in the same acute collapse state, but mixed-session continuity is still not governed by one runtime authority strongly enough to justify 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;
• clarification precedence still too strong in mixed sessions;
• residual assistantService overload;
• central intent pressure in resolveAddressIntent();
• remaining answer-semantics pressure in composeStage.ts and answerComposer.ts.