## Purpose

Define the durable project repository flavor used for complex cross-repository efforts: naming, required files, authority boundary, lifecycle, residual handoff, and archive procedure.

This standard implements and completes ADR-005 (Cross-Repo Workplans Live in Dedicated Project Repos). It does not replace the Repo Classification Standard: project repositories still use `category: project` in `.repo-classification.yaml`.

## When to use a project repository

Create a project repository when all of the following hold:

1. The work coordinates change across two or more functional repositories.
2. Binding the coordination workplan to any single product/tooling repo would misrepresent ownership or pollute that repo's history.
3. The effort has a bounded outcome with explicit success and retirement conditions (not an open-ended product roadmap).

Do not create a project repository for:

- single-repo workplans;
- small cross-cutting fixes that fit one lead repo's workplan plus dependency links;
- durable products, libraries, or services (those use `INTENT.md` and ordinary product/tooling/research categories);
- long-lived domain charters (those remain under `the-custodian/canon/projects/`).

## Naming

Element | Convention
--- | ---
Git / local directory | `prj-<kebab-slug>`
Hub `repo` slug | same as directory name
Workplan prefix | short uppercase prefix derived from the project, ending in `-WP-` (example: `SHR-WP-` for State Hub Retirement)
Classification | `category: project`

Canonical prefix is `prj-`. ADR-005's illustrative `proj-` form is superseded for new repositories. Do not invent parallel prefixes (`project-`, `xrepo-`, …).

Slug rules:

- lowercase kebab-case;
- outcome-oriented (`prj-state-hub-retirement`), not a random ticket id;
- stable for the life of the project (rename only with an explicit migration note in `history/`).

## Authority boundary

Concern | Owner
--- | ---
Project goal, success gates, retirement conditions | project repo (`GOAL.md`)
Architecture decisions, sequencing, dependency map, migration ledger, risks, consolidated evidence | project repo
Cross-repo workplans that coordinate the effort | project repo (`workplans/`)
Production implementation, tests, deployables | participating functional repositories
Per-repo implementation workplans and local evidence | each functional repository
Durable post-project standards and ADRs | permanent homes (`the-custodian` canon, or the owning product/tooling repo)

Hard rules:

1. Project repositories MUST NOT host production implementation code for the systems being changed.
2. Project workplans link child workplans by stable ID; they MUST NOT copy or replace child task lists.
3. The hub remains a read/index layer; work records originate as files (ADR-001).
4. Results of the project live primarily in the modified functional repositories and promoted canon. The project repo is coordination + provenance.

## Required files

At registration / first meaningful commit:

Path | Required | Role
--- | --- | ---
`GOAL.md` | yes | Outcome, invariants, success gates, project retirement conditions. Replaces `INTENT.md` for this flavor.
`SCOPE.md` | yes | Project authority, participating repos, in/out of scope, work-record rule.
`README.md` | yes | Short entry point linking `GOAL.md`, `SCOPE.md`, genesis/history, active workplans.
`AGENTS.md` | yes | Agent session protocol for this project (orient → work → close; hub integration).
`.repo-classification.yaml` | yes | `category: project` plus domain / capability tags for the effort.
`workplans/` | yes | At least one foundation workplan; prefix unique to the project.
`history/` | recommended | Genesis and significant milestones (why the project exists).
`WORK-RECORDS.md` | generated | Hub index; do not hand-edit.
`.custodian-brief.md` | generated | Offline orientation brief.

### `GOAL.md` (not `INTENT.md`)

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:

    ---
    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 child workplan IDs;
3. promoted durable artefacts (canon paths, ADRs, standards);
4. migration and retirement evidence pointers (counts, cutover windows, backups);
5. residual work-record IDs and their owning repos;
6. rollback expiry or remaining operational obligations, if any.

Without this record, do not archive.

## Archive procedure

1. Verify all success gates and retirement conditions in `GOAL.md`.
2. Confirm residuals are live and owned outside this repository.
3. Promote remaining durable decisions/standards to permanent homes; leave pointers from the project repo.
4. Finish or cancel project workplans; move finished files to `workplans/archived/YYMMDD-<id>-<slug>.md` per workplan convention.
5. Write the completion record.
6. Set `project_status: archived` in `GOAL.md` frontmatter.
7. Run `statehub fix-consistency` (or equivalent) so the hub reflects finished workplans and the archived status.
8. Archive the repository in the forge (read-only); do not delete it.
9. Optionally mark the hub registration archived / read-only.

Archive means read-only provenance, never deletion. Historical evidence and coordination narrative remain queryable.

## Workplan and agent conventions

- Workplan files: `workplans/<PREFIX>-WP-NNNN-<slug>.md` with fleet status vocabulary (`proposed` … `archived`).
- Session start order for agents: `GOAL.md` → `SCOPE.md` → genesis/history → active workplans (see project `AGENTS.md`).
- Progress and task status follow ordinary State Hub / fix-consistency rules.
- Ad-hoc low-risk fixes may use `workplans/ADHOC-YYYY-MM-DD.md` with canonical id `{PREFIX}-WP-ADHOC-YYYY-MM-DD`; anything multi-step belongs in a normal workplan.

## Minimal layout example

    prj-example-cutover/
      GOAL.md
      SCOPE.md
      README.md
      AGENTS.md
      .repo-classification.yaml
      history/
        2026-08-09-genesis.md
      workplans/
        EX-WP-0001-foundation.md

## Reference instance

The first repository under this standard is `prj-state-hub-retirement` (State Hub retirement / hub-core consolidation). Use it as the structural reference when scaffolding later `prj-` repos; do not copy its domain-specific content.

## Conformance checklist

A repository conforms to the `prj-` flavor when:

- [ ] Named `prj-<slug>` and classified `category: project`.
- [ ] Has `GOAL.md` with outcome, invariants, success gates, and retirement.
- [ ] Has no durable-product `INTENT.md` (or documents an explicit temporary exception during migration of a mis-scaffolded repo).
- [ ] Has `SCOPE.md`, `README.md`, `AGENTS.md`, and `.repo-classification.yaml`.
- [ ] Hosts coordination workplans only; implementation lives in child repos.
- [ ] Links child workplans by ID rather than duplicating their tasks.
- [ ] Defines archive/completion discipline consistent with this standard.
- [ ] On completion, writes a completion record and archives read-only.

## Related

- ADR-001 — Workplans and Work Items Are Repository Artefacts
- ADR-005 — Cross-Repo Workplans Live in Dedicated Project Repos
- `repo-classification-standard_v1.0.md` — `category: project`
- `work-record-types_v0.1.md` — residuals and work-record kinds
- `workplan-terminology-fleet_v0.1.md` — workplan vocabulary