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

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

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