144 lines
7.3 KiB
Markdown
144 lines
7.3 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: `~92%`
|
|
- exit-from-danger-zone readiness: `~84%`
|
|
- pre-multidomain readiness: `~64%`
|
|
- graph snapshot after latest rebuild: `5352 nodes`, `11506 edges`, `134 communities`
|
|
- current breakpoint:
|
|
- the validated hot paths are no longer structurally broken;
|
|
- flagship continuity collapse is no longer the primary risk;
|
|
- the main remaining risk is incomplete convergence toward one true runtime authority plus replay breadth still below the intended multi-domain blast radius;
|
|
- product shaping is now secondary debt, not the primary blocker.
|
|
- 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()`
|
|
- replay breadth still narrower than the intended multi-domain rollout surface
|
|
- remaining answer-semantics pressure inside `composeStage.ts` / `answerComposer.ts`
|
|
|
|
Latest live proof now includes:
|
|
|
|
- `address_truth_harness_phase12_wider_saved_session_pool_live_20260418_rerun10` accepted `20/20`
|
|
- `address_truth_harness_phase14_counterparty_tail_resume_live_20260418_rerun2` accepted `10/10`
|
|
- `address_truth_harness_phase15_answer_inspection_followup_live_20260418_rerun7` accepted `9/9`
|
|
|
|
Current architectural reading:
|
|
|
|
- the system is already materially past the dangerous regression breakpoint;
|
|
- it is now safe for continued architecture hardening and controlled domain-by-domain enablement under replay gates;
|
|
- it is still not safe to declare broad low-risk multi-domain expansion.
|
|
|
|
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 is no longer in the same acute collapse state. The remaining blocker is no longer the original continuity failure itself, but the unfinished convergence toward one runtime authority plus still-insufficient replay breadth for 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 is much better than before, but still not yet proven widely enough outside the repaired replay family;
|
|
- residual `assistantService` overload;
|
|
- central intent pressure in `resolveAddressIntent()`;
|
|
- remaining answer-semantics pressure in `composeStage.ts` and `answerComposer.ts`.
|