# AceLM common artifact metadata

These fields apply to every artifact type, including specifications, plans, backlog items, plan sets, and releases. The user-defined fields and allowed values are requirements. Encoding details, validation behavior, and edge-case policies below are explicitly proposed design rules.

## Optional fields

| Field | Allowed values | Meaning |
| --- | --- | --- |
| `priority` | Missing/null or integer 0 through 7 | Relative scheduling priority. Zero is a real priority, not absence. |
| `dependency` | Missing/null, one id6, or a list of id6s | Required artifacts, all of which must meet their predicates. State-qualified entries are described below. |
| `status` | Missing/null or a valid lifecycle status for the artifact type | Lifecycle position, separate from readiness and priority. |
| `readiness` | Missing/null, `go`, `no-go`, `need-ok` (legacy: `go-pending-approval`) | Whether the next action is permitted, blocked, or awaiting approval. |
| `activity` | Missing/null, `queued`, `running`, `waiting`, `paused` | Underlying activity of the selected assignment; never the derived Run label. |
| `assignment_outcome` | Missing/null, `done`, `fail`, `died` | Recorded final assignment outcome, separate from the artifact or content verdict. |
| `worker_liveness` | `alive`, `dead`, `unknown` | Observed process/service fact, with observation time and identity in details. |
| `intervention` | Missing/null or structured intervention record (`needs-human`) | Orthogonal human attention tracking; does not replace lifecycle status. |
| `open_questions` | Missing/null or a list of questions | Artifact-local questions with stable `OQ-01`, `OQ-02`, etc. identifiers. |

**Proposed:** optional storage does not mean optional enforcement. A newly created lifecycle-managed artifact normally records `draft`. If an imported record has no status, the status remains unknown unless an authoritative transition/history record resolves it; do not infer acceptance from readiness, priority, directory naming alone, or completed checkboxes. Unknown status cannot pass a status-dependent gate. Missing readiness means unspecified, not automatic `go`. The transition service recomputes actual gates before every action even if the displayed readiness is `go`.

## Separate operational dimensions

To maintain precise lifecycle tracking, AceLM distinguishes five orthogonal operational dimensions:

1. **Lifecycle Status:** Phase reached or recorded outcome/disposition (`draft`, `reviewing`, `reviewed`, `accepted`, `executing`, `verifying`, `complete`, failure states, and universal exits). Retained during ordinary pauses or waiting.
2. **Assignment Activity (Run):** Activity of the selected assignment (`queue`, `run`, `wait`, `pause`, `done`, `issue`, `fail`, `died`, `-`). Max five characters in compact terminal tables.
3. **Readiness:** Evaluated for a named intended next action (`go`, `no-go`, `need-ok`, `-`).
4. **Human Intervention:** Structured record (`needs-human`) capturing the exact blocking question, blocked actions, requested actor, and checkpoint.
5. **Worker Liveness:** Observed process/service fact (`alive`, `dead`, `unknown`), exposed in row details and not conflated with assignment outcome.

### Proposed storage and finalized display contract

The field names and serialization below are proposed schema design, not a claim about implemented storage. Keep underlying activity, final assignment outcome, human intervention, and worker liveness separately. Select the current assignment, otherwise the latest relevant outcome; show other concurrent assignments in details. Clearing the association displays `-` and preserves history.

Derive Run in this order:

1. A final unsuccessful assignment displays `fail` or confirmed `died`; a human recovery request does not replace it with `issue`.
2. A final successful assignment displays `done`. A VA that successfully delivered a negative content verdict is still `done`; the artifact can be `fail-verify`.
3. An unfinished assignment with a genuine human intervention displays `issue`, retaining its underlying activity.
4. Otherwise translate `queued/running/waiting/paused` to `queue/run/wait/pause`. Missing association displays `-`; unknown activity requires a visible diagnostic, never an invented success.

```yaml
status: executing
activity: waiting
assignment_outcome: null
intervention:
  kind: needs-human
  question: OQ-01
  blocks_actions: [resume-execute]
worker_liveness: alive
# Derived Run: issue; reached phase remains executing.
```

See [the status migration contract](acelm-status-migration.md) for retained lifecycle values and import aliases.

Compact 8-character display is a presentation formatting convenience only; canonical stored metadata, CLI structured output, and schema validators always retain the full unabbreviated strings.

## Priority

| Label | Stored value |
| --- | --- |
| none | Missing or null |
| very low | 0 |
| low | 1 |
| med-low | 2 |
| medium | 3 |
| med-high | 4 |
| high | 5 |
| very high | 6 |
| critical | 7 |

**Required:** preserve the exact scale above. **Proposed:** canonical portable storage is the integer or null; UI may show labels. Reject booleans, fractional values, and values outside 0 to 7. Do not treat `0` as false/empty. Missing/null stays unranked; it does not silently become medium or very low. Priority ranks eligible work; critical priority never bypasses dependencies, review, acceptance, or verification. Scheduling of unranked items and tie-breaking are explicit project policy.

## Dependency requirements

**Required:** dependencies can point to any artifact type. With a list, every referenced artifact must satisfy its requirement (logical AND). A bare id6 requires a terminal status. A state-qualified dependency requires its specified status instead, such as a specification being accepted rather than implemented.

**Proposed canonical encoding:** retain the required shorthand and allow state-qualified objects, including a mixed list:

```yaml
# No dependencies:
dependency: null

# One artifact, default terminal predicate:
dependency: a1b2c3

# Every artifact must satisfy the default terminal predicate:
dependency: [a1b2c3, d4e5f6]

# Explicitly require one state:
dependency:
  id6: a1b2c3
  state: accepted

# Mixed predicates; every entry must be met:
dependency:
  - id6: a1b2c3
    state: accepted
  - id6: d4e5f6
    state: implemented
  - g7h8j9
```

`a1b2c3` and other six-character values here are illustrative IDs, not references to actual artifacts. ID syntax must use the project's canonical id6 validator. These examples propose a serialization; they do not assert that current `aw` already reads these keys.

### Terminal does not necessarily mean successful

**Literal user rule:** bare-ID dependencies use terminal status, rather than assuming every dependency asks for successful implementation. In the currently defined lifecycles, terminal classifications include the type's normal completion state (including proposed release state `released`) and the explicit dispositions `superseded`, `retired`, and `abandoned`. Therefore an abandoned prerequisite satisfies the literal default-terminal predicate, but it does not satisfy an explicit `implemented`, `executed`, or `done` predicate. It also does not fulfill a parent's mandatory implementation/child-completion rule.

**Recommendation, still open:** consider making successful completion the default instead. This is safer for work that consumes a dependency's deliverable, but it would change the literal terminal rule and must be an explicit decision. For this package, the diagrams and examples retain the literal terminal rule. Use explicit successful-state selectors for dependencies that need actual fulfillment.

**Proposed:** failure states remain recoverable blocked states, not automatically terminal. If project policy declares a failure terminal, that classification must be explicit and visible. Plan-set terminal status remains unresolved; a dependency on a set cannot claim satisfaction until its lifecycle/closure predicate is defined. Unknown artifact types/states fail closed rather than inventing completion semantics.

### State-qualified dependencies

`approved` in the user's example maps to canonical lifecycle state `accepted`. **Proposed:** import may normalize that known alias with a visible diagnostic; new records write `accepted`.

**Proposed default:** a specified state is an exact-state predicate. `state: accepted` is satisfied while the dependency is accepted, but not automatically when it later becomes implementing or implemented. If the intent is "has valid acceptance and has reached at least this milestone," encode that separately, for example `mode: milestone`, with an explicit per-type progression model and revision-bound acceptance evidence. There is no implicit numeric ordering across failure states, dispositions, or branches in the lifecycle. The milestone extension is a proposal, not a required existing field.

Before launching or resuming work, reevaluate predicates against current revisions. **Proposed:** after a milestone dependency legitimately advances, already-running work should use the recorded qualifying revision rather than being interrupted merely by normal forward progress. Revocation, semantic revision, supersession, or invalidated fulfillment requires revalidation. The exact live-run response is project policy, recorded as an open question.

### Validation and resolution

**Proposed:** normalize one ID to a one-entry list internally and missing/null to an empty list, preserving the portable value. Empty lists also mean no prerequisites. Do not reuse JSON null for an unresolved referenced ID.

- Resolve IDs through the project-wide artifact registry, across all artifact types.
- Missing or ambiguous IDs block work with a clear diagnostic; they are not satisfied dependencies.
- Reject self-dependencies and circular blocking dependencies. Historical derivation may be cyclic over time, but a live blocking graph must not deadlock itself.
- Duplicate identical predicates may be deduplicated. Different predicates on the same artifact remain conjunctive and must be checked for contradiction.
- The specified state must be valid for the referenced artifact type.
- Do not silently redirect a superseded ID to its replacement. Update the dependency explicitly, with provenance and required review.
- Store the evaluated target revision, predicate, result, time, and reason. Cached results in SQLite are indexes; stale cache entries are not transition authority.

## Status and readiness are separate

A reviewed artifact can be `need-ok` (legacy: `go-pending-approval`); an accepted artifact can be `no-go` because a dependency is unmet. A successful completion state does not mean there is another action ready to run. Readiness is always understood relative to a named next action.

**Proposed evaluation:**

1. If any nonapproval gate for the intended action is unmet or unknown, readiness is `no-go`.
2. If those gates are met but required human/delegated acceptance is pending, readiness is `need-ok` (legacy: `go-pending-approval`).
3. If all gates, including required approval, are met, readiness is `go`.
4. If no intended action or gate evaluation exists, readiness stays missing/null.

Pending human approval alone is not `fail-gate`. An unresolved question alone does not exhaust a gate-remediation budget. Lifecycle rules define when a blocker becomes an unrecoverable gate failure.

## Open questions

**Required:** each question has an artifact-local ID such as `OQ-01`, `OQ-02`, and so forth.

**Proposed question record:**

```yaml
open_questions:
  - id: OQ-01
    question: Should the rename cover public API names?
    blocking: true
    blocks_actions: [accept, execute]
    status: open
    owner: human-maintainer
    resolution: null
    evidence: []
```

**Proposed:** IDs are unique within the artifact and stable across revisions. Use at least two digits and expand naturally beyond 99 (`OQ-100`); never renumber questions after deletion/resolution and never recycle IDs. Portable qualified references use `<artifact-id6>:OQ-01`. Question status is independent of the artifact status; proposed values are `open`, `resolved`, and `deferred`.

Every resolved question records the answer, actor, timestamp, and rationale/evidence. Deferral requires a reason and an authorized decision; it does not silently clear a blocking question. Record which action a question blocks. RA checks completeness and relevance; acceptance cannot proceed with unresolved acceptance-blocking questions, and execution cannot proceed with unresolved execution-blocking questions. Nonblocking questions may remain open without forcing no-go, but remain visible.

## Minimum artifact example

```yaml
id6: m2n3p4
type: plan
priority: 5
dependency:
  - id6: a1b2c3
    state: implemented
status: reviewed
readiness: need-ok
open_questions: []
```

This is metadata only. A valid plan must also contain at least one E-* and one V-* item, as specified in `acelm-plan-items.md`.

## Open decisions added by this metadata model

- `OQ-01`: default dependency terminal classification versus successful-completion default.
- `OQ-02`: exact-state versus explicitly supported milestone predicates, including live-run invalidation behavior.
- `OQ-03`: plan-set terminal/closure status and predicates for other future artifact types.
- `OQ-04`: scheduling and tie-break policy for missing/null priorities.
- `OQ-05`: cross-repository ID namespaces, if dependencies may extend beyond a single project registry.

These are questions for this design document, not new questions inserted into any user's repository artifact.