Control state on macrostates + DoR fallback (no title heuristics)

[rucka]

Story Statement

As a maintainer of pair's orchestration
I want pair-next decisions based on macrostates (via the state mapping) plus DoR-criteria fallback — never title heuristics or hardcoded board names
So that phases don't block on template/board mismatches and control state is deterministic (R2.5)

Where: pair-next decision logic, observable in its suggestions on any board

Epic Context

Parent Epic: pair-next esteso & orchestrators #204
Status: Refined
Priority: P1 (Should-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a board whose states are mapped in WoW (n-m)
   When pair-next evaluates an issue
   Then it resolves the macrostate via the map and decides on that — board state names never appear in decision logic

2. Given a board with NO state expressing readiness (e.g. Todo/In Progress/Done)
   When pair-next evaluates a Todo issue
   Then readiness is detected via DoR criteria on the body (AC present + estimate + inline task breakdown), per D4 fallback

3. Given an issue whose title suggests one thing and whose state/body another
   When pair-next decides
   Then state+criteria win — titles are NEVER used as control signals (grep-verifiable: no title heuristics in the skill)

4. Given an unmapped board state on an issue
   When pair-next encounters it
   Then the issue is reported as out-of-process (not an error), consistent with "unmapped states allowed" (Canonical states, n-m mapping, DoR/DoD, refine=Draft→Ready #202)

Business Rules

• Control state = macrostate (primary) + DoR criteria (fallback when mapping absent/insufficient) — R2.5, D4
• The DoR criteria set is the canonical one from Canonical states, n-m mapping, DoR/DoD, refine=Draft→Ready #202 (single source, no local variant)
• Same resolution used by orchestrators and the automation loop (Supervised automation — zero logic, consumes tags #212) — one implementation

Edge Cases and Error Handling

• Missing WoW entirely: canonical state names assumed (D21) + DoR fallback active
• Conflicting signals (state says Ready, DoR fails): flagged to the user with the failing criteria listed

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Code review completed and approved
• Documentation updated — docs site (apps/website): control-state resolution documented
• CLI (apps/pair-cli) updated where install/update/distribution is touched

Quality Assurance

• Fixture boards: mapped, minimal (no Refined), unmapped states, missing WoW
• Grep audit: no board-state names, no title heuristics in decision text

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 (M)
Confidence Level: Medium
Sizing Justification: consolidates resolution logic already specified by #202 into pair-next's decision path; confirmed M(3)

Sprint Capacity Validation

Sprint Fit Assessment: yes
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #202 canonical states + DoR/DoD stories (definitions); root/filter story (shared selection engine)
Dependent Stories: supervised automation (#212) relies on this determinism

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: decision transcripts on fixture boards; conflict scenario (state vs DoR) verified
Test Data Requirements: boards with mapped/minimal/unmapped configurations; stories with complete/incomplete DoR bodies

Notes and Additional Context

Refinement Session Insights: validated in production by a board where "Refined" is not a state — readiness read from the body (addendum on #202)
Documentation Links: R2.5, D4 · Spec G1/G2

Technical Analysis

Implementation Approach

Technical Strategy: single "resolve control state" procedure in pair-next SKILL.md: map lookup → macrostate; if readiness undecidable → DoR criteria check on body sections; conflict and unmapped-state reporting; procedure referenced (not duplicated) by orchestration modes
Key Components: resolution procedure; DoR checklist reference; reporting formats
Integration Points: #202 mapping schema and DoR definitions; run loop; macro-phase modes

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
DoR body checks too strict (false not-ready)	Medium	Medium	criteria = section presence + explicit list of failures shown to user

Task Breakdown

Checklist

• T1 — Control-state resolution procedure (map → macrostate → DoR fallback)
• T2 — Conflict + unmapped-state reporting
• T3 — Adoption of the procedure across pair-next decision points (single reference)
• T4 — Fixture-board sessions + grep audit + docs site

Dependency Graph

T1 → T2 → T3 → T4

AC Coverage

Task	AC1	AC2	AC3	AC4
T1	✓	✓
T2			✓	✓
T3	✓		✓
T4	✓	✓	✓	✓