pair-next esteso & orchestrators (root, filters, multi-step, declarative stop, macro-phases, profiles)

[rucka]

Epic Information

Epic ID: EP-204
Initiative: Process Engine & Orchestration #200
Theme: Parametrized orchestration
Epic Owner: Foomakers Product Team
Status: Planning
Priority: P0
Epic Points: 21 (estimated)
Target Release: Slice ③ — ENABLING for automation

Epic Statement

As a developer or supervising agent
I need pair-next parametrized (root, filters, multi-step, declarative stop) with facade macro-phases and process profiles
So that process branches run on criteria with zero merit logic in the loop

Epic Context

pair-next as the automation atom (R2.2). Filters treat tags GENERICALLY (no classification semantics) and are RE-EVALUATED at every run/step — tags may change between runs (e.g., review raises the tier); never cache the selection (D18).

Business Value & Objectives

Primary Business Goals

1. Goal 1: Execute process branches on criteria (root + filter) — prerequisite for external-agent automation.
2. Goal 2: Multi-step runs with declarative, always-terminating stop criteria (no infinite refines).
3. Goal 3: Simpler UX: 2–3 macro-phases hide real steps (R2.11); process subsets via profiles (R2.7).

Success Metrics (KPIs)

• Merit logic in loop/automation code - Target: 0 (grep-verifiable)
  • Measurement method: code review + grep
  • Current baseline: n/a (feature absent)
• Multi-step run completion - Target: loop terminates by predicate in 100% of runs
  • Measurement method: smoke tests on until-predicates
  • Current baseline: single-step only

Problem Statement & Market Opportunity

Current State

pair-next is read-only, single-step, no filters/root; "macro-phases" don't exist; process subsets not configurable; control state relies on literal board states.

Target State

pair-next --root <id> --filter <tag> --steps <n>|--until "<selector> ⇒ <condition>"; macro-phase modes; process profile read from WoW.

Solution Overview

Core Solution Approach

All criteria live outside the loop (adoption/classification); the loop evaluates only declarative predicates on PM-tool state.

Key Capabilities

1. Arguments — --root (epic → epic-level; story → develop/refine), --filter, --steps/--until (R2.3, R2.8).
2. Declarative stop criterion — <selector> ⇒ <condition>: selector = root/tag/type; condition = macrostate and/or tag presence (e.g. tag:x ⇒ Done; root:#66 tipo:story ⇒ Ready; root:#66 ⇒ has-tag:risk:*). Never body-content conditions.
3. Macro-phases as pair-next MODES (D24) — analysis / implementation / review; granular skills stay invocable; NOT new skills.
4. Process profile in WoW (D19) — default, poc (skips heavy structuring, guidelines still apply), custom; multi-profile arg = future extension.
5. Extended control state (R2.5) — macrostates + DoR criteria, never title heuristics.

Epic Breakdown

User Stories (High-Level)

Must-Have Stories (P0)

• US: As a developer I want --root + --filter (generic tags, re-evaluated per step) so that pair-next works on a scoped branch
• US: As a developer I want --steps/--until with declarative predicate so that multi-step runs terminate deterministically
• US: As a team I want the process-profile section in WoW + poc profile so that process subsets are configurable

Should-Have Stories (P1)

• US: As a user I want macro-phase modes (analysis/implementation/review) so that real steps are hidden
• US: As a maintainer I want control state on macrostates + DoR fallback (R2.5) so that phases don't block on template mismatches

Epic Acceptance Criteria

• AC1: pair-next --root EP-x --filter tag:ui --steps 3 runs 3 coherent steps only on matching issues
• AC2: --until "tag:x ⇒ Done" terminates when the predicate is true on the board
• AC3: Filter re-evaluated at each step (tag changed mid-loop alters selection)
• AC4: poc profile: no DDD steps proposed

Timeline & Roadmap

Critical Path Dependencies

• Requires: Canonical states (Canonical states, n-m mapping, DoR/DoD, refine=Draft→Ready #202)
• Enables: Supervised Automation (under Advanced Features Enablement #5)

Success Validation

Launch Criteria

• Functionality: All must-have stories completed and tested
• Documentation: Docs site updated for every feature/artifact of this epic
• CLI: apps/pair-cli updated where install/update/distribution is touched

---

Appendix

Related Documentation

• Requirements R2.2–R2.4, R2.7, R2.8, R2.11 · Spec G2 in pair-requirements-triage.md · Decisions D18, D19, D24

Addendum — spec integrations (2026-07-06)

• Process profile granularity: the profile section in way-of-working supports a per-step whitelist of enabled how-to/skills (e.g. only story-level steps enabled, strategic/DDD steps disabled). pair-next never proposes a disabled step; disabled steps are skipped, not errored. Validated requirement from a production adoption running 5/9 how-to enabled.