[rucka]

PR Information

PR Title: [US-611] feat: prioritize root delivery state
Story/Epic: #611 / #605
Type: Feature
Priority: High
Assignee: @rucka
Labels: none until review classification

Summary

What Changed

Root runs use mapped delivery state in stable Review → In Progress → Ready order. A validated --state-order argument overrides ## Delivery State Order adoption. Draft follows those states; unreadable and unmapped states get explicit exclusions. Mutex conflicts wait in the finite pool and run after release.

Why This Change

The #605 parallel run selected Ready #598 before Review #589. Both need pair-capability-publish-pr; the conflict dropped #589 from a non-watch run. Priority now gives #589 the mutex first and retains #598 for the same batch.

Story Context

User Story: #611
Acceptance Criteria: AC1–6: state order and override, #589/#598 mutex, finite queue drain, mapped/unknown states, audit and console, selection → plan → pool tests.

Changes Made

Implementation Details

• Selector transports canonical state from PM State Mapping; CLI validates the public override.
• Planner keeps stable state order and dependency exclusions; pool serializes shared resources and drains queued cards.
• Shipped workflow, skill, policy and CLI docs describe the same order and override.

Files Changed

• Modified: apps/pair-cli/src/commands/run/, canonical .workflows/pair-loop.js, .skills/loop/SKILL.md, generated mirrors, policy and CLI docs.
• Added: .changeset/611.md.

Services to Release

• @pair/pair-cli: patch release for root scheduling and --state-order.

Testing

Test Coverage

• Unit and integration: selector → planner → pool; override precedence; dependencies; parallel 1/2; mutex release; unknown states; root skip; run --root: mutex exclusion applied at effective parallelism 1, excluded cards never driven in the same run #590/run: honor argument precedence and full-preset card eligibility #593 regression fixtures.

Test Results

pnpm quality-gate passed, including 3,624 CLI tests, workflow tests, lint, type checking, formatting and repository checks. The pre-push gate passed on the pushed head.

Documentation

Documentation Updates

• User Documentation: CLI command reference and loop skill document --state-order.
• Technical Documentation: automation policy defines the adopted order and unmapped-state handling.

Reviewer Guide

Review Focus Areas

Check mapped-state transport, stable priority before mutex acquisition, and pool queue release in root-select.ts, root-plan.ts, parallel-entry.ts and parallel.ts. Compare the shipped workflow and generated mirror.

Testing the Changes

pnpm quality-gate

[rucka]

Code Review — PR #612

Verdict

risk:red · cost:green — CHANGES-REQUESTED — explicit workflow order can be rejected by malformed adoption.

Open findings: 2.

PR: #612 · Author: rucka · Reviewer: independent Pair verifier · Date: 2026-11-07 · Story: US-611 · Type: feature

Classification matrix

Service criticality green (adopted Low); change risk yellow (shared CLI/workflow contracts); business impact red (core workflow); security relevance red (untrusted argument parsing, no introduced vulnerability); coupling balanced. Story floor red. Cost green: no new cost signal.

Assessments

Security — Input validation

Verdict: green — --state-order rejects incomplete, duplicate and unknown values.

Security — Output handling

Verdict: green — state values are quoted in errors; audit values come from fixed state tokens.

Security — Authentication

Verdict: green — no changed authentication path.

Security — Authorization

Verdict: green — no changed access-control path.

Security — Introduced vulnerabilities

Verdict: green — none found.

Cost

Verdict: cost:green — no paid service, provisioning or metered workload change.

Architecture (Coupling)

Verdict: green — the CLI and workflow share a policy contract; both are tested, but the override boundary diverges (r0-1).

Bug fix — Red test before fix

Verdict: not applicable — feature PR.

Details

Findings by severity

Major (must fix before merge)

• r0-1 · packages/knowledge-hub/dataset/.workflows/pair-loop.js:753 — A valid stateOrder argument still HALTs when the adopted ## Delivery State Order is malformed. The workflow parses adoption at line 770 before applying the argument at line 771. A stubbed workflow probe with adopted Ready,Ready,Review and explicit Review,In Progress,Ready returned HALT: ## Delivery State Order must be a permutation, touching no card. Resolve the explicit argument before validating the overridden adoption value, and test the boundary.

Minor (must fix before merge)

• r0-2 · apps/pair-cli/src/commands/run/root-select.test.ts:33 — AC5's custom board-label mapping has no proof at the selector boundary. The new test starts with canonical Review; if a selector returns the project's literal Refined despite Refined → Ready, the planner excludes it as unmapped and existing new tests do not catch the missing map. Add a test starting with a custom board label and assert canonical transport into the planner; keep a truly unknown label excluded.

Functionality & requirements (AC coverage)

AC1: root-plan.test.ts stable state order and parallel-entry.test.ts plan. AC2: parser.test.ts and parallel-entry.test.ts prove valid overrides; malformed-adoption precedence fails (r0-1). AC3: #589/#598 integration test. AC4: parallel.test.ts release and serial tests. AC5: root-select.test.ts proves canonical transport, not custom mapping (r0-2). AC6: integration, dependency, unknown-state, root-skip and parallel 1/2 suites retained.

Testing & quality gates

pnpm install --frozen-lockfile && pnpm build, pnpm quality-gate, pnpm smoke-tests, pnpm --filter @pair/website e2e: all exit 0 on c13762c. Custody: verified; this run sealed no contract.

Adoption, debt, docs, deployment

GitHub Projects mapping and detached setup followed. No new dependency or cost surface. CLI docs, policy and generated mirrors changed with the implementation. No separate debt item; revert is the rollback path.

[rucka]

Open findings

Re-review r2: 1 new (r2-3 new in r2), 2 still open.

id	severity	found	status	location	summary	resolution
r0-2	Minor	r0	open	apps/pair-cli/src/commands/run/parallel-entry.test.ts:112	With board label Refined mapped to Ready, the new selector-to-planner tests still inject Ready directly; dele…	—
r2-3	Minor	r2	open	packages/knowledge-hub/dataset/.skills/workflow/cycle/scripts/loop-workflow-dispatch.mjs:25	(new) When the dispatcher receives an explicitly supplied --state-order with JSON null, it silently omits sta…	—