Durable product and tooling repositories explain **why they exist** with
`INTENT.md`. Project repositories are temporary and outcome-bounded; they use
**`GOAL.md`** instead.
`GOAL.md` MUST include:
1.**Outcome** — what success looks like in one short section.
2.**Invariants** — rules that must hold during the project.
3.**Success gates** — checkable conditions for “goal achieved”.
4.**Project retirement** — conditions under which *this repository* may be
archived (usually: gates met + residuals handed off + durable decisions
promoted).
Recommended frontmatter:
```yaml
---
repo: prj-<slug>
repo_flavor: project
project_status: draft | active | completed | archived
started: "YYYY-MM-DD"
reviewed: "YYYY-MM-DD"
---
```
**Anti-pattern:** shipping both `INTENT.md` and `GOAL.md` in a `prj-` repo.
If a durable intent emerges, promote it into a permanent repository's
`INTENT.md` (or canon) and keep the project goal as the temporary outcome
document.
### Relation to durable `INTENT.md`
| Repository kind | Purpose document |
| --- | --- |
| product / tooling / research / business / experimental | `INTENT.md` |
| **project (`prj-`)** | **`GOAL.md` only** |
Tooling that scaffolds repositories (e.g. `statehub register`) MUST treat
`GOAL.md` + `repo_flavor: project` as sufficient purpose documentation for
`prj-` repos and MUST NOT require inventing an `INTENT.md` that pretends the
project is a permanent product.
## Lifecycle
```
draft → active → completed → archived
```
| Status | Meaning | Repo / hub signals |
| --- | --- | --- |
| `draft` | Convention and foundation still forming; may not yet be registered | `project_status: draft`; workplans often `proposed` / `ready` |
| `active` | Coordination and child implementation in progress | `project_status: active`; at least one workplan `active` or `ready` |
| `completed` | All success gates have accepted evidence; residuals have live owners outside this repo | `project_status: completed`; project workplans `finished` or cancelled with rationale |
| `archived` | Repository is read-only provenance | forge archive flag; hub repo/workplan `archived`; no normal writes |
Promotion rules:
-`draft → active` when `GOAL.md` / `SCOPE.md` are reviewable and the foundation
workplan is `ready` or `active`.
-`active → completed` only when **every**`GOAL.md` success gate has accepted
evidence **and** residuals are live work records elsewhere (see below).
-`completed → archived` after the completion record is written, durable
decisions are promoted, and a final consistency/link check passes.
## Residuals before completion
Actionable leftovers MUST NOT live only in finished workplan prose or
`SCOPE.md`. Before any project workplan is set to `finished`, and again before
`project_status: completed`, each residual becomes a **live work record**
outside the closing narrative:
- intake with `origin: residual` + `origin_ref: <WP-id>`, or
- a next workplan / decision / engagement / register-entry in a permanent repo.
Canon: `work-record-types_v0.1.md` § Residuals. Fleet residual listing is a
State Hub concern, not a project-local queue file.
## Completion record
Before archival, the project repository MUST contain a completion record
(recommended path: `history/YYYY-MM-DD-completion.md`) that lists:
1. deployed or merged revisions that realize the outcome;
2. every participating repository touched, with links to merged PRs/commits or
