> ## Documentation Index
> Fetch the complete documentation index at: https://gump.top/sdlc-harness-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# feature_list.json

> Understand milestone, feature, dependency, verification, evidence, and runtime status fields.

`feature_list.json` is the single source of truth for the feature plan and execution status. Developers, Agents, the CLI, Git hooks, and CI all read it.

## Top-level fields

| Field | Meaning |
| - | - |
| `project` | Project name |
| `schema_version` | State file format version string |
| `last_updated` | Most recent update time |
| `milestones` | Ordered milestone list |
| `features` | Feature list |
| `rules` | Project governance contract |
| `rule_exceptions` | Explicit rule exception information |
| `status_legend` | Status meaning descriptions |
| `evidence` | Project-level evidence such as artifact approvals |

A milestone contains at least `id`, `title`, and `objective`. List order is used to check milestone ordering for dependencies.

## Feature definition

| Field | Required | Purpose |
| - | - | - |
| `id` | Yes | Unique ID in the repository |
| `milestone` | Yes | Existing milestone ID |
| `behavior` | Yes | Observable completion behavior |
| `status` | Yes | `not_started`, `in_progress`, `blocked`, `passing` |
| `dependencies` | Yes | Feature IDs that must pass first |
| `verification` | Yes | At least one automated or manual verification item |
| `title`, `area` | No | Human-readable name and domain |
| `priority` | No | Lower numbers have higher priority |
| `risk` | No | `low`, `medium`, `high`; used only for workflow decisions |
| `source_refs` | Required for real features | Requirement, story, acceptance criterion, or ADR references |
| `implementation` | No | Related files and commit |
| `notes` | No | Additional information |

## verification

```json theme={null}
{
  "type": "automated",
  "command": "npm test -- auth",
  "expected": "A valid login creates a session",
  "source_refs": ["docs/product/user-stories.md#US-1.AC-1"]
}
```

`type` can only be `automated` or `manual`. `verify` executes automated items; `evidence manual` records manual items. `source_refs` should point precisely to the acceptance criteria covered by the check.

## CLI-managed fields

Do not maintain these fields manually:

* `claim`: owner, actor, claim time, lease, heartbeat, and takeover information.
* `workspace`: branch, path, baseline commit, and creation time.
* Test, manual, review, and project approval records in `evidence`.
* `blocker` and lifecycle status transitions.

The related commands use compare-and-swap atomic writes. When they detect concurrent modification, they safely retry or refuse to overwrite it.

## evidence

Common `kind` values for feature evidence include test, manual, and review. Records contain results and timestamps plus the relevant command, verification index, reviewer, actor, notes, or CI metadata. Top-level project evidence is used for artifact approval and additionally stores the artifact and content hash.

<h2 id="archiving-milestones">
  Archiving milestones
</h2>

`milestone archive` (see the [Planning commands reference](/sdlc-harness-docs/reference/command-planning#milestone-archive)) moves a fully-`passing` milestone, and its features, out of `feature_list.json` into `.harness/archive/<milestone-id>.json`:

```json theme={null}
{
  "milestone": { "id": "M1", "title": "…", "objective": "…" },
  "features": [ /* the milestone's feature objects, unchanged */ ],
  "archived_at": "2026-08-20T03:07:12.440Z",
  "archived_by": "alice"
}
```

Archived feature IDs are not gone from the project's record: `claim`, `feature start`, and dependency-cycle checks still treat them as satisfied ("passing") dependencies, and `traceability` still counts them toward the requirements, stories, and acceptance criteria they covered. Archiving is a storage move for completed work, not a way to drop it — it keeps `feature_list.json` focused on the current and upcoming milestones without losing history or breaking anything that depended on the archived work.

<Warning>
  Passing JSON Schema validation only means the structure is valid. `validate` semantic auditors still check dependency order, WIP, evidence freshness, independent review, source references, and traceability completeness.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.