Design and implement first-class delivery phases for promoted candidates, acceptance, and rollback semantics

[fujiwaranosai850]

From research #215

Overview

DevClaw currently models implementation, review, and optional technical testing, but it under-models the generic delivery lifecycle between technical completion and actual production acceptance. We need a product-level workflow extension that gives #207 and related UAT work the correct architectural home.

This task should define and implement a generic delivery-phase model that separates:

• technical testing
• candidate promotion / release-candidate identity
• acceptance (UAT)
• post-release validation
• rollback / demotion of failed promoted candidates

The goal is not to hardcode every environment or deployment style into core. The goal is to add the smallest correct first-class workflow semantics so projects can model delivery safely, while keeping environment-specific mechanics in project overlays/runbooks.

Implementation Checklist

Phase 1: Product model and workflow semantics (~2-3 days)

• Define the target lifecycle contract in a design note under docs/ that formalizes the recommended sequence from research #215: technical review → test → promote candidate → acceptance/UAT → post-release validation → terminal outcome.
• Decide and document which delivery concepts are first-class in core versus project-specific overlay policy, including explicit treatment of environment naming, deployment mechanisms, rollout styles, and observability checks.
• Extend workflow typing in lib/workflow/types.ts and resolved config loading in lib/config/loader.ts, lib/config/merge.ts, and lib/config/types.ts so the workflow can express delivery-step policy beyond just reviewPolicy and testPolicy.
• Update schema validation in lib/config/schema.ts so any new delivery-step config is validated with clear errors and preserves backward compatibility when the new phases are disabled.

Phase 2: Core workflow and routing implementation (~3-4 days)

• Add first-class workflow defaults in lib/workflow/defaults.ts for a generic promotion/candidate step and an acceptance/UAT step, keeping them disabled or skippable by default so existing projects preserve current behavior.
• Add any required step-routing labels and helpers in lib/workflow/labels.ts so delivery phases can be routed per issue similarly to review:* and test:*.
• Update dispatch/pickup behavior in lib/dispatch/index.ts and lib/services/tick.ts so issues acquire the correct delivery routing labels and only dispatch to workers when the configured policy requires it.
• Implement the missing heartbeat/pass logic, parallel to the current review/test handling in lib/services/heartbeat/review.ts, lib/services/heartbeat/review-skip.ts, and lib/services/heartbeat/test-skip.ts, for skipped or human-gated delivery phases.
• Define the minimal candidate identity/provenance contract for v1, including where the exact promoted candidate should be recorded (for example issue comments/body/labels/PR metadata), and wire that contract into the relevant workflow transition points.
• Ensure failure transitions cleanly support candidate invalidation and rollback/demotion semantics, sending work back to To Improve or Refining as appropriate without leaving the failed candidate represented as current.

Phase 3: UAT alignment, reporting, and documentation (~2-3 days)

• Reconcile the narrower UAT design from #207 / #212 against the new delivery model so UAT is explicitly modeled as acceptance of a promoted candidate rather than as another generic testing bucket.
• Update workflow reporting and admin surfaces in files such as docs/WORKFLOW.md, docs/ROADMAP.md, docs/CONFIGURATION.md, lib/tools/admin/workflow-guide.ts, lib/tools/admin/project-status.ts, and lib/tools/admin/project-register.ts so the new phases appear correctly in docs and summaries.
• Add or update tests covering config loading, label sync expectations, dispatch behavior, skip/human/agent routing, and failure-path transitions. Relevant suites likely include lib/services/pipeline.e2e.test.ts, lib/tools/tasks/research-task.test.ts, heartbeat tests, and workflow/config tests.
• Document migration and enablement guidance for existing projects, including the default no-op/backward-compatible behavior and how projects can opt into promotion/UAT/post-release phases incrementally.

Dependencies & Blockers

• Depends on the architectural conclusions from research #215 remaining the accepted direction.
• Should explicitly coordinate with #207 so first-class UAT implementation is not built on the old “test then UAT directly” assumption.
• Candidate identity/provenance should stay minimal in v1 to avoid over-scoping into a full release registry.
• Keep environment-specific deploy/runbook logic out of core unless a truly generic abstraction emerges during implementation.

Estimated Total: 7-10 days

[fujiwaranosai850]

🎛️ ORCHESTRATOR: Spawning architect research as a child lane so #216 stays the canonical root tracker.

Research issue:

• #217 Research: Design and implement first-class delivery phases for promoted candidates, acceptance, and rollback semantics #216 first-class delivery phases for promoted candidates, acceptance, and rollback semantics
• Research: #216 first-class delivery phases for promoted candidates, acceptance, and rollback semantics #217

Intent:

• use the architect to produce a development-ready lifecycle/state recommendation
• keep #216 as the root delivery-phase tracker
• let the architect create concrete follow-up implementation tasks if needed