NODEDC_1C/docs/ARCH/11 - architecture_turnaround/06 - phase_acceptance_matrix.md

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
• 21 - current_status_canon_2026-05-01.md
• 23 - current_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.
• Open-World Semantic Control Gate: accepted critical subset after EHMO/W5/W7 hardening; fat GUI pack review remains a broad human-pressure gate.
• Route-Candidate-Driven Enablement Loop: 100%, now regression-gated by phase91-phase98 canaries.
• Open-World Schema/Primitive Discovery: 95%, phases97-105 accepted live and saved as user-runnable AGENT autoruns; latest closure replay phase105_mixed_schema_primitive_closure_live3 accepted 13/13. Remaining gate is manual GUI/fat-pack review before final closure or a narrow phase106 repair if that review reveals a new semantic defect.

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

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.