# AceLM status vocabulary and terminal UX

Design record, 2026-10-04 America/New_York. Companion to [the artifact transition catalog](acelm-artifact-transition-catalog.md). Captures the latest discussion for the AceLM documentation and website project. This is product design documentation, not a claim that these behaviors already ship or a request to publish website copy.

## Decision maturity

- Agreed direction: concise canonical labels, consistent terminology across artifact types, successful completion separate from run completion, explicit human intervention, and lifecycle phase retained while work waits.
- Favored vocabulary: common lifecycle/failure labels below remain subject to the explicit migration decisions in [the status migration contract](acelm-status-migration.md).
- Finalized readiness: `go`, `no-go`, `need-ok`, and missing/null displayed as `-`.
- User preference: permit an eight-character status display when terminal space is limited.
- Finalized Run: the label meanings, outcome precedence, selection rule, and separation from worker liveness below. Proposed serialization and unresolved lifecycle choices remain marked explicitly.

## Separate dimensions

| Dimension | Purpose |
| --- | --- |
| Lifecycle status | Phase reached or recorded outcome/disposition of the artifact |
| Run display | State/result of the selected work assignment for this artifact; not worker-process liveness |
| Readiness | Whether the intended next action passes its gates |
| Human intervention | Pending human decision/request and the affected actions |
| Worker liveness | Whether the worker process/service is alive; shown in details, not inferred from Run |

Acceptance-blocking open questions prevent acceptance. A question first discovered during execution can block affected work without erasing the acceptance or execution phase. Changing accepted scope/requirements requires revision, independent review, and acceptance again.

**Agreed phase retention:** executing + wait/issue retains executing while blocked. Verification likewise retains verifying. Lifecycle labels denote a phase that has begun, not a promise that a process is continuously working. This supersedes the earlier proposal to return paused work to accepted and the earlier active-agent-only meaning of implementing/executing. Beginning those phases still requires an authorized actual start; an untouched queued artifact remains accepted.

## Favored canonical lifecycle vocabulary

The intended common progression is draft → to-review → reviewing → reviewed → accepted → executing → verifying → complete. Type-specific completion gates remain different. Review passed does not mean human acceptance; complete requires verified fulfillment, not merely that a worker stopped.

| Meaning | Canonical label | Width | Eight-character display |
| --- | --- | ---: | --- |
| Authoring | draft | 5 | draft |
| Submitted for review | to-review | 9 | to-revie |
| Review phase | reviewing | 9 | reviewin |
| Successful review | reviewed | 8 | reviewed |
| Human/scoped delegated acceptance | accepted | 8 | accepted |
| Fulfillment phase | executing | 9 | executin |
| Verification phase | verifying | 9 | verifyin |
| Successful artifact completion | complete | 8 | complete |
| Review budget exhausted | fail-review | 11 | fail-rev |
| Verification budget exhausted | fail-verify | 11 | fail-ver |
| Execution failure | fail-exec | 9 | fail-exe |
| Unremediable/exhausted gate | fail-gate | 9 | fail-gat |
| Interrupted process | fail-int | 8 | fail-int |
| Confirmed unexpected process death | fail-died | 9 | fail-die |
| Replaced artifact | superseded | 10 | supersed |
| No longer needed | retired | 7 | retired |
| Intentionally discontinued | abandoned | 9 | abandone |

These displays are literal first-eight-character truncations. They are unique for this proposed vocabulary; validate uniqueness whenever adding a status. Provide full canonical values in details/help and structured output. Do not store truncated labels or silently accept ambiguous prefix filters. Full labels are preferred when space allows; an explicit compact mode can use width 8 without an ellipsis taking another cell. An ASCII status token does not depend on color or symbol interpretation.

Implementing specification, executing plan, graduating backlog, and verifying closure can remain descriptive action labels. Shared executing status supports investigation, documentation, orchestration, and direct code work. The favored terminal success is complete for specs, plans, and backlog items.

Graduation-as-activity remains a recommendation under discussion, not a settled deletion of states. If retained as statuses, graduating → graduati (10 → 8 characters) and graduated → graduate (9 → 8 characters) are distinct. Preserve successor links and graduation events in either model.

## Favored readiness vocabulary

| Canonical label | Meaning |
| --- | --- |
| go | All required gates for the intended action pass |
| no-go | At least one nonapproval gate blocks that action |
| need-ok | Other gates pass; required approval is pending |
| Missing/null; displayed as - | Unspecified/not evaluated |

The finalized need-ok replaces the legacy go-pending-approval. Eight-character truncation of that older label is ambiguous and should not become the new canonical spelling. The display should not use go-pend? to imply a known pending approval; the question mark looks like uncertainty.

## Finalized Run labels

The finalized Run label set is queue, run, wait, pause, done, issue, fail, died, and -. Every label is at most five characters. The Run column displays the selected assignment's activity or outcome, not a raw worker-process liveness indicator. A persistent worker can complete one assignment while continuing to run other assignments.

| Label | Meaning | Worker alive? |
| --- | --- | --- |
| queue | Assignment scheduled but not started | Independent/unknown |
| run | Assignment actively making progress | Expected; liveness must be observed |
| wait | Expected wait with no human action currently required | May be alive |
| pause | Assignment deliberately suspended by user or policy | May be alive |
| done | Assignment performed its assigned task successfully; the worker may remain running | May remain alive and perform other work |
| issue | Human intervention is required, without a decisive assignment failure; includes an unanswerable OQ, acceptance decision, or authority beyond delegation | May be alive; affected work is usually waiting |
| fail | A decisive unsuccessful assignment outcome was recorded | May remain alive; inspect run outcome and artifact status |
| died | Runner terminated unexpectedly without recording a final assignment outcome; confirmed during reconciliation | Terminated; recovery assignment will be scheduled |
| - | No associated assignment to display | No implication about service liveness |

The name **died is finalized** (not dead, lost, orphan, or stop):
- `lost` was rejected because it implies unrecoverable work; AceLM preserves checkpoints, worktrees, commits, and uncommitted progress for recovery.
- `dead` describes process liveness and can apply after normal completion.
- `orphan` remains a descriptive detail indicating an ownerless lane or assignment.
- `stop` was removed because it was too ambiguous: normal completion, deliberate pause, interruption, death, and failure have fundamentally different operational consequences.

**done is assignment completion, not artifact completion.** A review assignment can be done while its artifact is reviewed; an execution assignment can be done while the artifact enters verifying. A successfully completed review process with a negative content verdict is not an infrastructure failure: its assignment can be done while the artifact needs author revision or reaches fail-review. Distinguish process/task completion from content verdicts in details.

**fail is decisive assignment failure, distinct from artifact retry exhaustion.** One failed individual assignment may still have an authorized retry available before the artifact transitions to a fail-* status. Details expose the failed assignment and cause. A VA assignment that successfully delivers a negative verification verdict has performed its checking task; it is marked done with a negative verdict, rather than a failed assignment runner.

**issue is not triggered by the mere existence of an open question.** An agent investigating an answerable OQ can remain run. An unanswered nonblocking OQ need not block the assignment; if it genuinely requires a human response, it is recorded as human intervention and exposed in attention views. An unanswerable, action-blocking OQ shows issue with needs-human intervention; operationally that assignment is waiting. Store underlying activity and blocker separately and derive the compact Run label.

User-defined distinction: issue means human intervention is required without a decisive failure. wait means an expected wait with no human action currently required. Pending human acceptance therefore shows issue with readiness need-ok; a pending dependency normally shows wait with readiness no-go. An agent-remediable problem alone does not imply issue. Human-needed metadata can coexist with other authorized ongoing work; the detailed activity remains visible if the compact label shows issue. A terminal failed assignment keeps fail (or died) even if a human is now needed to recover it; details expose that intervention.

## Unexpected termination, reconciliation, and recoverable progress

Durable recovery governs crashes, power loss, reboot, and unclean runner termination:

1. **Identity and Termination Confirmation:** Startup and periodic reconciliation confirm worker identity and termination using durable run records, host/boot identity, process-start identity, and ownership leases. A reused PID or missing heartbeat alone is insufficient.
2. **Uncertainty vs. Confirmed Death:** An unreachable host, uncertain ownership, or terminal disconnection alone does not justify died or fail-died. Reconcile uncertainty and suspend new mutation authority before declaring death.
3. **Preservation Invariant:** `died` never means discard or blindly reexecute. The system preserves lane/branch/worktree, commits, uncommitted work, E/V progress, execution logs, checkpoints, and records uncertain side effects.
4. **Fencing and Recovery:** Stale mutation ownership is fenced before assigning a replacement worker. Recovery inspects actual results and resumes only unestablished work. Evidence is recovered where possible; commits alone do not prove completion gates passed.
5. **Detection and Retry Accounting:** Detection and human waiting consume no retries. Automatic corrective recovery uses FAIL retry limits and respects the artifact cumulative ceiling. Detection timestamp is recorded separately from last observed activity; termination history is preserved after an authorized recovery assignment transitions to queue/run.

## Display selection and concurrent assignments

1. Show the current assignment for each artifact; if none is current, show the latest relevant assignment outcome. Otherwise done/fail/died would vanish as soon as the assignment ends. Clearing an association produces -; it does not rewrite history.
2. Selecting/queuing a new assignment replaces the previous displayed done/fail/died with its queue/run state. Preserve the older outcome in history.
3. A terminal unsuccessful assignment shows fail or died; a terminal successful assignment shows done. An unfinished assignment requiring human intervention shows issue; otherwise display its queue/run/wait/pause activity.
4. Do not let an agent-remediable or informational warning mask run. If a genuine human request coexists with ongoing unrelated work, the primary label can show issue while details preserve the running activity. If parallel assignments exist, use a deterministic primary assignment selection and expose the others in details or an expanded runs view.
5. Display needs-human in details and focused blocked/attention views rather than adding another permanent column to an already-wide default table. Keep OQ open/total counts but do not infer human need solely from the count.
6. Status failure prefixes are useful for grouping/filtering. Eight-character display is presentation only; CLI commands and exported records keep full canonical values.

## Examples under the display contract and favored lifecycle names

| Status | Run | Readiness | Explanation |
| --- | --- | --- | --- |
| reviewed | issue | no-go | Acceptance-blocking OQ needs a human answer |
| reviewed | issue | need-ok | Review passed; human acceptance required |
| accepted | queue | go | Authorized execution assignment queued |
| executing | run | go | Agent executing accepted work |
| executing | issue | no-go | New execution-blocking OQ needs human judgment; resume execute after gates pass |
| executing | wait | no-go | Waiting for required dependency |
| executing | done | - | Execution assignment finished; verification handoff still being scheduled; readiness has not been evaluated |
| verifying | run | go | Verification assignment active |
| complete | done | - | Artifact completion published; latest assignment succeeded |
| fail-verify | done | no-go | VA successfully delivered a final negative verdict; content verification exhausted |
| executing | fail | no-go | Latest execution assignment failed; artifact recovery decision is pending |
| fail-died | died | no-go | Confirmed unexpected worker death recorded; runner fenced and uncommitted progress preserved |

Readiness is always relative to the named intended action. These are illustrative outcomes, not values inferred from lifecycle status alone.

## Decisions still open

- Finalize canonical vocabulary and graduation handling, then migrate all transition tables, diagrams, examples, schema validators, and website claims together.

Run task success, final failure precedence, and human-intervention precedence are resolved by the finalized sections above. This record is authoritative design documentation; expressly open naming/state choices are not silently finalized.

The original catalog keeps older tokens for traceability until naming is finalized; its pause/human-intervention semantics have been corrected to retain phase. Retry inheritance and the cumulative default of 20 x resolved MAX_RETRY remain unchanged.