# 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`

| State | Definition and Gate Requirements |
| --- | --- |
| `draft` | Define version, scope, included artifacts, target environments, required checks, and rollback plans. |
| `to-review` | Release candidate commit is pinned and ready for sequential lens evaluation. |
| `reviewing` | Assessment phase has begun across configured lenses; ordinary remediation, dependency, or human waits retain `reviewing`. |
| `reviewed` | All required lens assessments are complete with recorded evidence; zero unresolved release blockers. |
| `accepted` | An authorized human explicitly approves release for the specific candidate commit and target. |
| `releasing` | Authorized publication/deployment has actually begun; ordinary pauses retain `releasing` while activity records the wait. |
| `verifying` | Post-release health checks, smoke tests, and deployed artifact digests are independently confirmed. |
| `released` | All publication steps and post-release verifications have succeeded; release record is archived. |

**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.

| Readiness for `release` | Definition | Consequence |
| --- | --- | --- |
| `go` | All required lens evidence passes; candidate-specific human approval granted. | Ready for active `releasing` execution. |
| `need-ok` | All required assessments complete cleanly; human release approval is pending. | Candidate remains `reviewed`; Run displays `issue`. |
| `no-go` | Unresolved release blockers, failed test gates, or missing empirical evidence. | Release advancement blocked; remediation cycle required. |
| Missing/null, displayed as `-` | Release readiness has not been evaluated. | Evaluate the named action before proceeding; absence is not permission. |

## 7. Mermaid Visualizations

### Release Lifecycle State Machine

```mermaid
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

```mermaid
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;
```