Supervised automation — zero logic, consumes tags

[rucka]

Epic Information

Epic ID: EP-212
Initiative: Advanced Features Enablement #5
Theme: Workflow automation (Initiative Epic 5 scope)
Epic Owner: Foomakers Product Team
Status: Planning
Priority: P1
Epic Points: 26 (estimated)
Target Release: LAST in sequencing — requires pair-next esteso (#204), classification (#208), publish-pr (#206)

Epic Statement

As a team supervising AI-assisted delivery
I need automation that starts and advances autonomously only on tag-eligible cards, with explicit human intervention points
So that autonomous phases advance alone and humans intervene only where required (orchestrator → supervisor)

Epic Context

Principle (D18): automation has ZERO merit logic. All criteria live in the classification model (adoption); classify emits tags; automation reads only tags and states. Schema: classify → tags → pair-next --root --filter tag:x --until "tag:x ⇒ Done" → skills. Goal (§4): run multiple steps from the dev machine today, then external agents doing the same with the same pair primitives. Enabling steps (from requirements): risk matrix (R5.2) + pair-next branch execution on criteria (R2.3, R2.8).

Business Value & Objectives

Primary Business Goals

1. Goal 1: Autonomous advancement only on eligible cards (tag-driven, R4.4); nothing happens on untagged issues.
2. Goal 2: Two automation levels distinct (R5.5): what the AI does vs what gets approved; auto-approval only for light-tagged PRs.
3. Goal 3: Full audit trail: every run leaves comments/state transitions; same primitives for human and agent.

Success Metrics (KPIs)

• Autonomous actions on untagged issues - Target: 0
  • Measurement method: audit trail review
  • Current baseline: n/a (feature absent)
• Merit criteria in supervisor code - Target: 0 (grep-verifiable: reads only tags/states)
  • Measurement method: grep + code review
  • Current baseline: n/a

Problem Statement & Market Opportunity

Current State

Every step is human-initiated (orchestrator mode); no eligibility concept; no approval entity; no tag-driven workflows.

Target State

Supervisor loop on pair-next with declarative stop; auto-development only for cards tagged eligible in refinement (non-business-critical, e.g. cosmetic/UI — criteria in adoption); approval/block entity gates merges.

Solution Overview

Key Capabilities

1. Eligibility via classification (R4.3): classify in refinement emits the eligibility tag per adoption criteria.
2. Tag-driven workflows (R4.4): different tags → different workflows; only tagged issues; CLI command candidate (pair-cli run — decided at story design).
3. Supervisor loop (R4.5): start+advance = pure pair-next loop (--root --filter --until); human points explicit (🔴 review approval, state promotions).
4. Approval/block entity (R5.6): dedicated identity with state-change permission; yellow → dev retries, red → human stop; no merge without approval. + Light-PR auto-approval (R5.5).
5. Breakdown-to-task feedback (R4.6): project created down to tasks; AI closes tasks and comments as it advances.

Epic Breakdown

User Stories (High-Level)

Detailed to stories NOW per decision D9 — see linked sub-issues.

Must-Have Stories (P0)

• US: Design spike (ADR): triggers, execution isolation, run triage
• US: Eligibility tag in refinement (auto-development criteria in adoption)
• US: Tag-driven workflows (only tagged issues; CLI command evaluation)
• US: Approval/block entity + light-PR auto-approval

Should-Have Stories (P1)

• US: Supervisor loop on pair-next with declarative stop + audit trail
• US: Breakdown-to-task feedback loop (close tasks + comment)

Epic Acceptance Criteria

• AC1: No autonomous action on issues without the eligibility tag
• AC2: Supervisor contains no classification criteria (grep-verifiable)
• AC3: PR without light tag never auto-approved; business-critical never auto-developed
• AC4: Loop stop = declarative predicate on the board; every run leaves an audit trail

Timeline & Roadmap

Critical Path Dependencies

• Requires: pair-next esteso (pair-next esteso & orchestrators (root, filters, multi-step, declarative stop, macro-phases, profiles) #204), Classification (Unified classification & assessments → tags (risk, cost, security, impact) #208), publish-pr (Split implement: checkpoint + publish-pr via subagent #206)

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 (tag-driven run command if adopted)

---

Appendix

Related Documentation

• Requirements R4.3–R4.6, R5.5, R5.6 · Spec G10 in pair-requirements-triage.md · Decisions D9, D18