# 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](</x:/1C/NDC_1C/docs/ARCH/11 - unified_project_architecture_and_reference_update_plan_2026-04-15.md:1>)

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](./01%20-%20project_architecture_baseline_map.md)
2. [02 - state_and_transition_contracts.md](./02%20-%20state_and_transition_contracts.md)
3. [03 - capability_contract_spec.md](./03%20-%20capability_contract_spec.md)
4. [04 - coverage_evidence_truth_gate.md](./04%20-%20coverage_evidence_truth_gate.md)
5. [05 - assistantService_extraction_map.md](./05%20-%20assistantService_extraction_map.md)
6. [06 - phase_acceptance_matrix.md](./06%20-%20phase_acceptance_matrix.md)
7. [07 - external_reference_appendix.md](./07%20-%20external_reference_appendix.md)
8. [08 - current_status_audit_2026-04-17.md](./08%20-%20current_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](./08%20-%20current_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()`.