diff --git a/canon/architecture/adr-005-cross-repo-workplans-project-repos.md b/canon/architecture/adr-005-cross-repo-workplans-project-repos.md index e5a3829..b50e2f1 100644 --- a/canon/architecture/adr-005-cross-repo-workplans-project-repos.md +++ b/canon/architecture/adr-005-cross-repo-workplans-project-repos.md @@ -74,10 +74,17 @@ draft → active → completed → archived ## Naming -Project repos SHOULD be identifiable as such (e.g. a `proj-` prefix or a -dedicated grouping). Exact convention is deferred to `CUST-WP-0050` rollout -(tracked as an open question there), but the lifecycle and ownership rules above -are fixed by this ADR. +Project repos MUST use the `prj-` prefix. + +Exact naming, required files (`GOAL.md` instead of durable-product +`INTENT.md`), authority boundary, residual handoff, and archive procedure are +defined in: + +`canon/standards/project-repository-flavor_v0.1.md` + +That standard closes the naming open question previously deferred to +`CUST-WP-0050` (D1a). The illustrative `proj-` form mentioned in earlier drafts +is not used for new repositories. ## Consequences diff --git a/canon/standards/project-repository-flavor_v0.1.md b/canon/standards/project-repository-flavor_v0.1.md new file mode 100644 index 0000000..ec4d41c --- /dev/null +++ b/canon/standards/project-repository-flavor_v0.1.md @@ -0,0 +1,277 @@ +--- +id: canon-project-repository-flavor +type: standard +title: "Project Repository Flavor (prj-) v0.1" +domain: custodian +status: active +version: "0.1" +created: "2026-08-09" +updated: "2026-08-09" +scope: fleet +related_workplans: + - SHR-WP-0001 + - CUST-WP-0050 +related_adrs: + - ADR-001 + - ADR-005 +supersedes: none +closes: + - "ADR-005 deferred naming convention" + - "CUST-WP-0050 open question D1a (naming + archival trigger details)" +--- + +# Project Repository Flavor (`prj-`) v0.1 + +## 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-` | +| 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: + +```yaml +--- +repo: prj- +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: `, 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--.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/-WP-NNNN-.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`; anything + multi-step belongs in a normal workplan. + +## Minimal layout example + +```text +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-` 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 diff --git a/canon/standards/repo-classification-standard_v1.0.md b/canon/standards/repo-classification-standard_v1.0.md index c0b820f..8204f94 100755 --- a/canon/standards/repo-classification-standard_v1.0.md +++ b/canon/standards/repo-classification-standard_v1.0.md @@ -228,6 +228,14 @@ Typical signs: - may become a product later, - may depend on active development milestones. +**Cross-repository project repositories** (temporary coordination repos for +multi-repo efforts under ADR-005) also use `category: project`. Their naming +(`prj-`), required files (`GOAL.md` rather than durable-product +`INTENT.md`), lifecycle, and archive procedure are defined in +`project-repository-flavor_v0.1.md`. Not every `category: project` repo must +be a `prj-` repo — only those that exist solely to coordinate a bounded +cross-repo outcome. + Examples: ```yaml diff --git a/workplans/CUST-WP-0050-repo-classification-registration-redesign.md b/workplans/CUST-WP-0050-repo-classification-registration-redesign.md index e4750b4..de645d3 100644 --- a/workplans/CUST-WP-0050-repo-classification-registration-redesign.md +++ b/workplans/CUST-WP-0050-repo-classification-registration-redesign.md @@ -344,11 +344,12 @@ recorded exclusion list). classification; `topic`/`domain` stop being the spine (`topic` retires or becomes an optional cross-repo tag). This supersedes the earlier "keep topic as an independent coordination unit" proposal. Implemented by T04/T10. -- **D1a (open, follows from D1): anchor for cross-repo workplans.** Per **ADR-005**, - a complex cross-repo effort gets its own **project repo** (`category: project`) - as the anchor, retired to archive on completion with results living in the - modified product repos. Open sub-point: the project-repo **naming convention** - (e.g. `proj-` vs a dedicated grouping) and the archival trigger details. +- **D1a (RESOLVED 2026-08-09, follows from D1): anchor for cross-repo workplans.** + Per **ADR-005**, a complex cross-repo effort gets its own **project repo** + (`category: project`) as the anchor, retired to archive on completion with + results living in the modified product repos. Naming, files, lifecycle, and + archive procedure: `canon/standards/project-repository-flavor_v0.1.md` + (`prj-`, `GOAL.md` not durable-product `INTENT.md`). - **D2: classification ownership/approval.** Who approves each repo's `.repo-classification.yaml` — per-repo owner, or central custodian review? - **D3 (RESOLVED 2026-06-22): exclusion list.** Recorded at