# AceLM Release Workflow and Lifecycle

# 1. Release Artifact Definition

A release is a versioned artifact that establishes what will ship, where it will ship, and the empirical evidence and authorization supporting that action.

Key release fields include:

• version: Target semantic version or release tag.
• candidate_revision: Pinned candidate git commit hash.
• target_environment: Target deployment or distribution registry (e.g., staging, production, package index).
• included_artifacts: Associated specs, plans, and backlog item IDs included in the candidate.
• assessment_profile: Configured sequence of assessment lenses and evaluation passes.
• evidence_manifest: Pinned test logs, security scan results, and verification digests.
• blocking_findings: Active findings preventing advancement.
• approvals: Cryptographically attributed human release authorization.
• rollback_plan: Verified rollback procedure and recovery criteria.

# 2. Release Lifecycle States

The release lifecycle follows eight formal states:

draft → to-review → reviewing → reviewed → accepted → releasing → verifying → released

Crucial Distinction: Plan execution creates a release candidate, but does not authorize deployment. Development plan acceptance is distinct from candidate-specific release authorization.

# 3. Phase Retention, Human Intervention, and Retries

• Phase Retention Invariant: When release qualification pauses or awaits human intervention, the release retains its reached lifecycle phase. For example, a candidate awaiting human release authorization remains in reviewed with readiness need-ok and Run issue. An assessment-blocking question discovered during lens evaluation leaves the candidate in reviewing with readiness no-go and Run issue. Work never reverts to draft or accepted solely because an agent is waiting.
• Retry Inheritance: Release candidate loops follow the standard four-family inheritance: MAX_RELEASE_<FAMILY>_RETRY → MAX_<FAMILY>_RETRY → MAX_RETRY → 2, bounded by the artifact-wide cumulative ceiling MAX_CUMULATIVE_RETRIES (default: 20 x resolved global MAX_RETRY).
• Planned Passes vs. Retries: The standard 62 scheduled lens evaluations across 2 passes (up to 93 for 3 passes) are planned sequential evaluation steps, not retries. Corrective repairs of discovered defects and rerun checks consume artifact retry budgets; planned sweeps do not.

# 4. Assessment Modes vs. Release Workflow

• Single-Concern Assessment: Evaluates a single lens (e.g., alm assess security) and produces diagnostic findings and remediation proposals without modifying the repository.
• Cross-Concern Assessment (assess-all): Runs a full or category sweep to cross-prioritize findings and synthesize a consolidated remediation plan.
• Automated Release Qualification: Executes lenses sequentially with immediate remediation inner loops across multi-pass cycles (see acelm-sequential-release-cycle.md).
• Release Execution: Executes only upon explicit human acceptance, applying changes to target environments with verified rollback plans.

# 5. Release Review Disciplines

# Security & Data Protection

• Authentication enforcement, token lifecycles, and tenant isolation.
• 2FA/MFA enrollment, enforcement, bypass prevention, and recovery flows.
• Data exfiltration prevention, secret scanning across Git history, and privacy-safe logging.
• Ransomware resilience, data backup integrity, and recovery blast radius limits.

# Accessibility (WCAG 2.1 AA & Terminal Rubrics)

• WCAG 2.1 AA conformance for web interfaces (contrast, keyboard navigation, screen reader semantics).
• Dedicated terminal accessibility rubrics for CLI tools (clear focus, color-independent indicators, plain-text modes, motion suppression).

# Architecture & Usability

• Public API contract ergonomics, schema evolution, and backward compatibility.
• Avoidable object fragmentation vs. intentional availability redundancy.
• User task completion efficiency, error recovery paths, and documentation accuracy.

# Performance & Reliability

• Latency and throughput benchmarks under real workloads.
• Algorithmic complexity analysis and hot-path profiling.
• Memory leak detection, connection pool sizing, and long-running process stability.

# 6. Assessment verdict and action readiness

Record the assessment verdict and its candidate-bound evidence separately from readiness. A positive assessment is not acceptance or permission to publish. This contract does not define a separate CONDITIONAL GO ship verdict or authorize waiving blockers. Readiness below is for the named action release; other actions have their own gate evaluations.

# 7. Mermaid Visualizations

# Release Lifecycle State Machine

flowchart TB
    D["draft: scope, version, targets, candidate"] --> T["to-review"]
    T --> R["reviewing: sequential lenses with remediation; deep + light passes"]
    R --> PASS{"Required review gates pass?"}
    PASS -->|"no; retries remain"| FIX["reviewing + waiting: accepted remediation E/V plans execute and verify"]
    FIX -->|"ordinary remediation complete; continue assessment"| R
    FIX -->|"review snapshot invalidated; new review request"| T
    PASS -->|"review budget exhausted"| FR["fail-review"]
    PASS -->|"yes"| RD["reviewed: candidate-bound assessment verdict"]
    RD --> AUTH{"Candidate-specific release authority and prerequisites?"}
    AUTH -->|"pending"| WAIT["Retain reviewed + wait/issue; readiness for named action; no publication"]
    WAIT --> AUTH
    AUTH -->|"yes"| A["accepted"]
    A --> REL["releasing: authorized publication begun; waits retain phase"]
    REL --> V["verifying: publication/deployment and smoke-test evidence"]
    V --> VG{"Required post-release checks pass?"}
    VG -->|"yes"| DONE["released"]
    VG -->|"no"| REC["Controlled remediation / rollback; bounded verify retries"]
    REC -->|"same candidate; authorized retry"| V
    REC -->|"candidate changed; renew review and authority"| T
    REC -->|"budget exhausted"| FV["fail-verify"]
    classDef good fill:#eaf8f5,stroke:#27806d,color:#173d35;
    classDef fail fill:#fff2ee,stroke:#a35743,color:#572d23;
    class A,DONE good;
    class FR,FV fail;

# Release Assessment Gates

flowchart TB
    START["Current integrated candidate + next configured lens + pass mode"] --> A["Assess lens: deep / light / convergence instructions"]
    A --> ISSUE{"Warranted remediation?"}
    ISSUE -->|"no"| CLEAN["Evidence-backed clean or justified not-applicable result"]
    ISSUE -->|"yes"| PLAN["Produce plan or plan set with E-* and V-* items"]
    PLAN --> R["Independent RA review"]
    R --> ACCEPT["Human or scoped delegated plan acceptance"]
    ACCEPT --> EA["EA executes approved work in isolated worktrees"]
    EA --> V["Independent VA + programmatic verification"]
    V --> INTEG["Integrate verified changes; recheck affected evidence"]
    INTEG --> G{"All required remediation and gates complete?"}
    G -->|"no"| STOP["Pause / bounded remediation or failure; do not advance lens"]
    G -->|"yes"| RECORD["Record lens result, commits, dispositions, evidence, checkpoint"]
    CLEAN --> RECORD
    RECORD --> NEXT["Only now advance to next lens"]
    classDef good fill:#eaf8f5,stroke:#27806d,color:#173d35;
    class NEXT good;