131 lines
6.4 KiB
Markdown
131 lines
6.4 KiB
Markdown
# 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)
|
|
9. [09 - pre_expansion_cut_2026-04-17.md](./09%20-%20pre_expansion_cut_2026-04-17.md)
|
|
10. [10 - regression_breakpoint_analysis_2026-04-17.md](./10%20-%20regression_breakpoint_analysis_2026-04-17.md)
|
|
11. [11 - continuity_stabilization_plan_2026-04-17.md](./11%20-%20continuity_stabilization_plan_2026-04-17.md)
|
|
12. [12 - manual_run_system_analysis_3NilqwT1G2_2026-04-18.md](./12%20-%20manual_run_system_analysis_3NilqwT1G2_2026-04-18.md)
|
|
13. [13 - pre_multidomain_readiness_audit_2026-04-18.md](./13%20-%20pre_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](./08%20-%20current_status_audit_2026-04-17.md)
|
|
- [09 - pre_expansion_cut_2026-04-17.md](./09%20-%20pre_expansion_cut_2026-04-17.md)
|
|
- [10 - regression_breakpoint_analysis_2026-04-17.md](./10%20-%20regression_breakpoint_analysis_2026-04-17.md)
|
|
- [11 - continuity_stabilization_plan_2026-04-17.md](./11%20-%20continuity_stabilization_plan_2026-04-17.md)
|
|
- [12 - manual_run_system_analysis_3NilqwT1G2_2026-04-18.md](./12%20-%20manual_run_system_analysis_3NilqwT1G2_2026-04-18.md)
|
|
- [13 - pre_multidomain_readiness_audit_2026-04-18.md](./13%20-%20pre_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`.
|