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

Current Status Snapshot (2026-04-17)

This package is no longer planning-only.

It now documents a turnaround that is already partially operational in code:

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

• estimated overall completion: ~85%
• graph snapshot after latest rebuild: 5228 nodes, 11338 edges, 133 communities
• main remaining architectural pressure:
  • resolveAddressIntent()
  • composeFactualReply()
  • residual coordinator/legacy pressure inside assistantService.ts

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

• 08 - current_status_audit_2026-04-17.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

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-17, the project is already materially closer to the target description, but not fully there yet.

The biggest remaining blockers are:

• residual assistantService overload;
• central answer-shaping pressure in composeFactualReply();
• central intent pressure in resolveAddressIntent().