# AceLM Architecture & Lifecycle Documentation

Welcome to the technical documentation for **AceLM (Agentic Coding Environment with Lifecycle Management)**.

AceLM brings professional engineering discipline to coding agents: defined requirements and architecture, evidence of work and quality, documented decisions, continuity for collaboration, and visibility into progress and resources. Experienced developers remain at the helm. AceLM is in development; capabilities still in design are identified explicitly.

## Decision Precedence & Maturity

The documentation in this portal reflects the latest confirmed design decisions for AceLM. Detailed reconciliation notes, confirmed invariants, and open proposals are tracked in the [**Design Decisions & Alignment Record**](acelm-docs-alignment.md).

The documentation follows this precedence:
1. **Authoritative sources:** [Artifact Transition Catalog](acelm-artifact-transition-catalog.md) and [Status Vocabulary & Terminal UX](acelm-status-and-terminal-ux.md), including their explicit maturity boundaries.
2. **Downstream rules:** lifecycle, metadata, isolation, assessment, and website references defer to those sources.
3. **Evidence register:** [alignment record](acelm-docs-alignment.md) reports corrections and checks; it does not create authority or finalize proposals.

Finalized Run/readiness semantics apply now; favored common lifecycle names await explicit adoption under the [status migration contract](acelm-status-migration.md).

## Core Documentation Index

### 1. Overview & Architecture
- [**Design Decisions & Alignment Record**](acelm-docs-alignment.md): Evidence register, decision precedence, and scoped verification status across the design documentation suite.
- [**Product Positioning**](acelm-positioning.md): The five pillars of professional engineering discipline for coding agents.
- [**Engineering Rigor & Delivery Controls**](acelm-engineering-rigor.md): Evidence across the SDLC, durable decisions, collaboration, and planned resource reporting and configurable policy.
- [**Status Vocabulary & Terminal UX**](acelm-status-and-terminal-ux.md): Unified status vocabulary, 8-character compact terminal displays, phase retention rules, and Run/Readiness dimensions.
- [**Common Artifact Metadata**](acelm-artifact-metadata.md): P0-P7 priorities, state-qualified dependencies, action readiness, and stable open question IDs.

### 2. Lifecycles & State Machines
- [**Lifecycle Rules & State Machines**](acelm-lifecycle-rules.md): Specification, Backlog, Plan, and Release Candidate lifecycles, adversarial review gates, and explicit failure dispositions.
- [**Artifact Transitions & Gate Remediation Catalog**](acelm-artifact-transition-catalog.md): Comprehensive transition contract (R01-R15, S01-S06, P01-P13, B01-B16, X01-X15, F01-F08) and 40 gate failure remediation cases (G01-G40).
- [**Plan Items & E/V Contracts**](acelm-plan-items.md): Execution items (`E-*`) vs. Verification items (`V-*`), mapping rules, and evidence verification gates.
- [**Workspace Isolation & Worktree Policy**](acelm-isolation-policy.md): Git branch isolation, isolated worktree allocation, single-writer leases, and daemon process durability.

### 3. Release Governance & Assessments
- [**Gated Release Lifecycle**](acelm-release-lifecycle.md): Release candidate definitions, candidate pinning, release gates, separate assessment verdict and action readiness, and post-release verification.
- [**Sequential Release Assessment Cycle**](acelm-sequential-release-cycle.md): Multi-pass evaluation algorithm (Pass 1 deep, Pass 2 light, Pass 3 convergence) and per-lens remediation inner loops.
- [**31-Lens Assessment Catalog**](acelm-assessment-catalog.md): Complete catalog of 31 engineering lenses across Security, Reliability, Architecture, Performance, UX, and Compliance.

### 4. Research

Research about other products, the market, and how agent tools communicate with models lives in the
private [`acelm-research`](https://github.com/acelm-ai/acelm-research) repository. Documents here cite
it by path. Material that moved there on 2026-10-11:
- the OpenCode and Hermes Agent execution-flow analysis (`docs/opencode-hermes-…-execution-flow.md`) → `agent-tools/findings/`
- `docs/cursor-info/` → `competitors/cursor/`
- `docs/architecture-evaluations/acelm-client-interface-strategy.researched.md` and its research prompt → `market/`

## Visual Diagrams & Architectural Panels

### Historical Baseline Lifecycle Panels

These preserved assets are historical shorthand, not the full current contract. Direct accepted-to-done arrows still require actual execution, evidence, and independent verification. Plan states do not define set states. The authoritative catalog and detailed diagrams govern all gates.
- [Specification Lifecycle (SVG)](panels/acelm-specification.svg)
- [Plan Lifecycle (SVG)](panels/acelm-plan.svg)
- [Backlog Item Lifecycle (SVG)](panels/acelm-backlog-item.svg)
- [Artifact Origins & Graduation (SVG)](panels/acelm-origins-and-graduation.svg)
- [Shared Transitions (SVG)](panels/acelm-shared-transitions.svg)

### Detailed State Machine Diagrams
| State Machine / Rule | SVG Diagram | Mermaid Source |
| --- | --- | --- |
| **Review Retries & Acceptance** | [SVG Preview](rules/acelm-review-retries.svg) | [Mermaid](rules/acelm-review-retries.mmd) |
| **Verification Retries & Completion** | [SVG Preview](rules/acelm-verification-retries.svg) | [Mermaid](rules/acelm-verification-retries.mmd) |
| **Completion Gates (E/V)** | [SVG Preview](rules/acelm-completion-gates.svg) | [Mermaid](rules/acelm-completion-gates.mmd) |
| **Runtime Ownership & Failures** | [SVG Preview](rules/acelm-runtime-and-failures.svg) | [Mermaid](rules/acelm-runtime-and-failures.mmd) |
| **Dependencies & Readiness** | [SVG Preview](rules/acelm-dependency-readiness.svg) | [Mermaid](rules/acelm-dependency-readiness.mmd) |
| **Plan Item Evidence** | [SVG Preview](rules/acelm-plan-item-evidence.svg) | [Mermaid](rules/acelm-plan-item-evidence.mmd) |
| **Workspace Isolation** | [SVG Preview](rules/acelm-workspace-isolation.svg) | [Mermaid](rules/acelm-workspace-isolation.mmd) |
| **Release Lifecycle** | [SVG Preview](rules/acelm-release-lifecycle.svg) | [Mermaid](rules/acelm-release-lifecycle.mmd) |
| **Release Assessment Gates** | [SVG Preview](rules/acelm-release-assessment-gates.svg) | [Mermaid](rules/acelm-release-assessment-gates.mmd) |
| **Sequential Release Passes** | [SVG Preview](rules/acelm-sequential-release-passes.svg) | [Mermaid](rules/acelm-sequential-release-passes.mmd) |

## Core Architectural Invariants

1. **Persistent Git Records**: All specifications, plans, decisions, and verification records travel with the Git repository.
2. **Execution Never Implies Verification**: Fulfilling an `E-*` task does not satisfy a `V-*` requirement. Verification requires independent observation and reproducible test output.
3. **Adversarial Independence**: Reviewing and verification tasks are performed in isolated agent contexts separate from authoring and execution sessions.
4. **Human Acceptance Authority**: Agents propose; authorized humans accept. Release authorization is strictly bounded to concrete candidate revisions and target environments.