feature_list.json

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

{
  "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.

Archiving milestones

milestone archive (see the Planning commands reference) moves a fully-passing milestone, and its features, out of feature_list.json into .harness/archive/<milestone-id>.json:

{
  "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.

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.

Getting started

Guides

Reference

Help

Top-level fields

Feature definition

verification

CLI-managed fields

evidence

Archiving milestones

​Top-level fields

​Feature definition

​verification

​CLI-managed fields

​evidence

​Archiving milestones

Top-level fields

Feature definition

verification

CLI-managed fields

evidence

Archiving milestones