# 06 - Phase Acceptance Matrix

## Purpose

This document turns the high-level turnaround direction into a phase-by-phase execution matrix.

Each phase must specify:

- `goal`
- `output artifacts`
- `done criteria`
- `non-goals`
- `acceptance signals`

## Current Status Pointer (2026-05-01)

This file is now a historical phase matrix, not the current progress dashboard.

Current status is tracked in:

- [README.md](./README.md)
- [21 - current_status_canon_2026-05-01.md](./21%20-%20current_status_canon_2026-05-01.md)
- [23 - current_execution_spine_and_semantic_control_gate_2026-05-05.md](./23%20-%20current_execution_spine_and_semantic_control_gate_2026-05-05.md)

Current reporting baseline:

- Post-F Semantic Integrity Hardening: `99%`, operationally closed/regression gate.
- Planner Autonomy Consolidation: `100%` for the declared phase83 slice.
- Open-World Business Overview implementation breadth: `~99%` through Slice 25.
- Active next pressure: `Open-World Semantic Control Gate`, accepted module progress `~98%` after the EHMO-derived critical subset accepted live; fat GUI pack review remains before full closure.

## Archived Execution Snapshot (2026-04-17)

Archived honest estimate of overall turnaround completion for this snapshot: `~85%`

Archived phase status:

- `Phase 0` - `100%`
- `Phase 1` - `100%`
- `Phase 2` - `92%`
- `Phase 3` - `86%`
- `Phase 4` - `84%`
- `Phase 5` - `76%`
- `Phase 6` - `80%`
- `Phase 7` - `90%`

This estimate is supported by:

- graph snapshot: `5228 nodes`, `11338 edges`, `133 communities`
- explicit truth/coverage contracts in code
- extracted policy owners in code
- machine-readable scenario acceptance artifacts
- mixed AGENT semantic source catalogs and accepted packs

Main remaining blockers:

- `assistantService.ts` is still too large
- `resolveAddressIntent()` remains a high-pressure god node
- `composeFactualReply()` remains a high-pressure god node

For the full audit, see:

- [08 - current_status_audit_2026-04-17.md](./08%20-%20current_status_audit_2026-04-17.md)

## Phase 0. Shared Baseline

Goal:

- align the team on one architecture vocabulary and one baseline map.

Output artifacts:

- baseline note in `docs/ARCH/11 - unified_project_architecture_and_reference_update_plan_2026-04-15.md`
- this package under `docs/ARCH/11 - architecture_turnaround/`

Done when:

- project discussions use the same names for layers, state, transitions, truth gate, and capabilities;
- no major planning discussion treats the system as "just a chat with LLM".

Non-goals:

- code changes;
- capability rewrites.

Acceptance signals:

- planning references point to the package rather than ad hoc prose;
- new refactor proposals can be mapped to a package artifact.

## Phase 1. Formal Layer Separation

Goal:

- explicitly separate project subsystems and their sources of truth.

Output artifacts:

- updated architecture notes if needed;
- clear internal naming for:
  - data foundation
  - assistant runtime
  - domain loop
  - experimental router contour

Done when:

- production assistant routing is no longer confused with Python router experiments;
- `canonical_layer` and `llm_normalizer/backend` are treated as different subsystems in planning.

Non-goals:

- merging runtimes;
- changing domain behavior.

Acceptance signals:

- no architecture review uses the wrong contour as the current runtime source of truth.

## Phase 2. State And Transition Contracts

Goal:

- make state and transition classes explicit.

Output artifacts:

- state schema note
- transition class registry note
- transition-oriented tests or planning matrix

Done when:

- every critical follow-up path is described as a named transition class;
- root frame, selected object frame, meta frame, clarification state, and coverage gate state are explicit objects.

Non-goals:

- answer wording cleanup;
- adding new business capabilities.

Acceptance signals:

- critical scenario failures can be described as transition failures, not only as "assistant got confused";
- at least one major follow-up-heavy domain can be read through transition contracts alone.

## Phase 3. Capability Contracts

Goal:

- make capabilities explicit contract objects instead of half-implicit route behavior.

Output artifacts:

- capability contract schema
- pilot contract set for critical inventory capabilities

Done when:

- critical capabilities declare entry modes, anchors, scope policy, truth behavior, and scenario families;
- new capability review can happen via contract inspection.

Non-goals:

- low-code workflow migration;
- removing recipe catalog.

Acceptance signals:

- at least one selected-object capability and one root capability are represented as full contract specs.

## Phase 4. Coverage / Evidence / Truth Gate Isolation

Goal:

- separate truth determination from answer policy.

Output artifacts:

- gate contract
- reason-code taxonomy
- carryover-eligibility contract

Done when:

- answer layer no longer decides whether a result is full, partial, or blocked;
- truth mode and carryover eligibility are explicit gate outputs.

Non-goals:

- UI redesign;
- full answer package rewrite.

Acceptance signals:

- scenario regressions can fail specifically on gate semantics;
- limited mode honesty is measurable independently from wording quality.

## Phase 5. AssistantService Extraction

Goal:

- reduce `assistantService` from god-service to coordinator.

Output artifacts:

- extraction map
- named policy owners
- reduced coordinator responsibility map

Done when:

- route policy, transition policy, boundary policy, and meta policy have explicit owners outside the coordinator;
- `assistantService` retains orchestration ownership but not most raw policy logic.

Non-goals:

- file splitting for its own sake;
- replacing the coordinator with a monolithic new router.

Acceptance signals:

- scenario regressions can point to extracted policy owners;
- code review no longer requires reading most of `assistantService.ts` to understand one policy area.

## Phase 6. Provider / Runtime Axis Hardening

Goal:

- make provider/runtime behavior an explicit architectural concern.

Output artifacts:

- provider execution contract
- structured-output compatibility matrix
- local/openai execution semantics note

Done when:

- provider quirks no longer bleed into business routing policy;
- structured output, tool calling expectations, and fallback behavior are documented per provider mode.

Non-goals:

- adding many providers immediately;
- model benchmarking as primary objective.

Acceptance signals:

- changing provider mode does not silently change core business semantics without explicit compatibility review.

## Phase 7. Scenario Acceptance As Primary Gate

Goal:

- enforce scenario-tree acceptance as the refactoring completion standard.

Output artifacts:

- phase-specific acceptance matrix
- updated scenario packs and required wording families

Done when:

- no phase is considered complete based only on unit tests or prettier answers;
- critical paths, critical edges, and selected-object continuity remain mandatory acceptance criteria.

Non-goals:

- shrinking evaluation to smoke tests;
- accepting root-only success as domain completion.

Acceptance signals:

- `pack_state.final_status`
- scenario acceptance matrix
- no unresolved `P0`
- direct answer, temporal honesty, selected-object continuity, and truth gate invariants all pass.

## Cross-Phase Rule

A phase is not done when the code "looks cleaner".

A phase is done only when:

- the declared artifact exists;
- the responsible layer is explicit;
- acceptance signals are green.