# PLAN — v1.27 PO State Catalog & Ciagent Compression

> **Milestone:** v1.27 (NFR — docs/chore only). Tags on the **v1.26.x**
> line: `v1.26.0` (P0) → `v1.26.1..v1.26.3` (P1..P3). The final phase's
> patch (`v1.26.3`) IS the milestone release.
> **Branch:** `milestone/v1.27-po-state-catalog`. Phase branches:
> `phase/00-pre-execution`, `phase/01-author-archive`,
> `phase/02-fix-stale-wire`, `phase/03-final-review-ship`.

## Milestone goal

Author `.ciagent/STATE.md` (PO-facing capability catalog, backfilled
through v1.26) + compress `.ciagent/` by archiving 11 outdated files +
fix 3 stale-but-kept files + wire STATE.md into the P-final ship
discipline. NFR milestone — no code, no schema, no platform behavior
change.

## Requirements

No new REQ-NNN. v1.27 is a docs/chore milestone; the work items are
the user-approved plan from the prior conversation. The traceability
is by-file (the "requirements" are the 15 file operations + 6 doc
edits in the plan summary).

## Phase breakdown

### Phase P1 — author-archive (additive + lossless)

**Goal:** Author STATE.md (already done in P0 SPECIFY, refined here)
+ archive 11 outdated files. Pure-additive + lossless moves only —
no edits to kept files.

#### Wave 1 — verify STATE.md backfill
- **Task 1.1** (lead-developer): verify STATE.md 36 capability rows
  against the authoritative sources (regression_verify.py CAP-NNN list,
  modules/registry.json, REQUIREMENTS.md traceability, CHECKPOINT
  tags). Fix any inaccurate citation (shipped tag, file path).

#### Wave 2 — archive platform-root files (10)
- **Task 2.1** (lead-developer): `git mv` 10 files to
  `.ciagent/archive/` with milestone-suffix names:
  - `CAPABILITY_INVENTORY.md` → `CAPABILITY_INVENTORY-v1.10.md`
  - `CLARIFY.md` → `CLARIFY-v1.26.md`
  - `GRILL.md` → `GRILL-v1.26.md`
  - `IDEATE.md` → `IDEATE-v1.26.md`
  - `RESEARCH.md` → `RESEARCH-v1.26.md`
  - `REVIEW-AUDIT-P05.md` → `REVIEW-AUDIT-P05.md`
  - `VERIFY-P03.md` → `VERIFY-P03.md`
  - `VERIFY-P04.md` → `VERIFY-P04.md`
  - `P4-PILOT-RUN-EVIDENCE.md` → `P4-PILOT-RUN-EVIDENCE-v1.26.md`
  - `AUTONOMY_THESIS.md` → `AUTONOMY_THESIS-v1.21.md`
  - `COST.md` → `COST-v1.14.md`
  Use `git mv` to preserve history. NOTE: CLARIFY/GRILL/IDEATE/RESEARCH
  were rewritten in P0 with v1.27 content — archive the v1.27 versions
  (they document the v1.27 pre-execution; the next P0 writes fresh).
  Wait — per D-219, the v1.26 pre-execution artifacts are archived. The
  v1.27 versions replace them in active context; they are NOT archived
  at P1 (they are the current P0 artifacts, active until v1.27 ships,
  then archived at v1.28 P1 if v1.28 happens). **Correction:** archive
  only the v1.26-era pre-execution artifacts. But P0 already
  overwrote CLARIFY/GRILL/IDEATE/RESEARCH with v1.27 content. The v1.26
  content lives in git history (the pre-P0 commits). So:
  - The 4 pre-execution files (CLARIFY/GRILL/IDEATE/RESEARCH) at HEAD
    are the v1.27 P0 artifacts — **keep active** through v1.27, archive
    at v1.28.
  - The v1.26-era content is in git history — reachable.
  **Revised archive list (7 files, not 10):** CAPABILITY_INVENTORY,
  REVIEW-AUDIT-P05, VERIFY-P03, VERIFY-P04, P4-PILOT-RUN-EVIDENCE,
  AUTONOMY_THESIS, COST.

  Hold — let me re-check D-219. The user said "Archive all 4
  pre-execution artifacts." That was decided *before* P0 overwrote
  them. The intent was to archive the v1.26 pre-execution record. The
  v1.27 P0 overwrites are the new pre-execution record. Archiving the
  v1.27 versions at v1.27 P1 would lose the v1.27 pre-execution
  narrative. **Resolution:** archive the v1.26-era content (preserved
  in git history at the pre-P0 commits) by noting it in the archive
  README; keep the v1.27 P0 versions active through v1.27. The 4 files
  stay active until v1.28 P1.

  **Final archive list (7 files):** CAPABILITY_INVENTORY.md,
  REVIEW-AUDIT-P05.md, VERIFY-P03.md, VERIFY-P04.md,
  P4-PILOT-RUN-EVIDENCE.md, AUTONOMY_THESIS.md, COST.md.

- **Task 2.2** (lead-developer): grep for dangling references to the
  archived filenames across `.ciagent/` + `docs/`; fix any in P2 (the
  fix-stale phase).

#### Wave 3 — archive consumer file (1)
- **Task 3.1** (lead-developer): `mkdir
  .ciagent/nova-blockchain-exchange/archive/` + `git mv
  nova-blockchain-exchange/ROADMAP.md` →
  `nova-blockchain-exchange/archive/ROADMAP-v1.26.md` (D-221).

#### Wave 4 — commit P1
- **Task 4.1** (lead-developer): single commit `chore(P01): archive 7
  platform + 1 consumer outdated .ciagent files` with `---ci---`
  block.

**Must-haves (verify before ship):**
- STATE.md 36 rows accurate (Wave 1 verification).
- 7 platform files present in `.ciagent/archive/` with milestone
  suffixes; originals gone from `.ciagent/` root.
- 1 consumer file present in
  `.ciagent/nova-blockchain-exchange/archive/`; original gone.
- 0 dangling references in active files (checked in P2, but flagged
  here).

### Phase P2 — fix-stale-wire (corrections + wiring)

**Goal:** Fix 3 stale-but-kept files + wire STATE.md into the P-final
ship discipline + add a pointer in the consumer PROJECT.md.

#### Wave 1 — fix PROJECT.md phase-status
- **Task 1.1** (lead-developer): `.ciagent/PROJECT.md` lines 424–431 —
  the v1.26 phase-status block. Mark P3/P4/P5 complete with shipped
  tags (`v1.25.3`, `v1.25.4`, `v1.25.5`); mark v1.26 milestone shipped.
- **Task 1.2** (lead-developer): add a one-line pointer to STATE.md in
  the "Capability Status" section header (line 130): "The PO-facing
  capability catalog is `.ciagent/STATE.md` (additive; updated at
  milestone ship). CAP-NNN IDs cross-reference the regression gate at
  `core/regression_verify.py`."

#### Wave 2 — fix ROADMAP.md phase-status
- **Task 2.1** (lead-developer): `.ciagent/ROADMAP.md` v1.26 section —
  mark P3/P4/P5 complete with shipped tags; mark the v1.26 Overview
  line (line 181) "(active, ...)" → "(complete, tag `v1.25.5`)".
- **Task 2.2** (lead-developer): add STATE.md to the v1.25 + v1.26 P5
  phase-detail "Updated at ship" list (the convention visibility
  point).

#### Wave 3 — wire STATE.md into ship discipline
- **Task 3.1** (lead-developer): `.ciagent/PLAN.md` P5 Wave 3 Task 3.5
  — add STATE.md to the file-update list: "append new capability
  entries to `.ciagent/STATE.md`; mark any deprecated capability."
- **Task 3.2** (lead-developer): `.ciagent/NORTH_STAR.md` — add a
  one-line note in "Relationship to engineering files" (or the v1.25
  update section): "STATE.md is the *what exists* catalog (PO-owned,
  additive, updated at milestone ship); this file is the *why*."

#### Wave 4 — fix archive README + consumer PROJECT pointer
- **Task 4.1** (lead-developer): `.ciagent/archive/README.md` — add
  the 8 new archived files (7 platform + 1 consumer) to the contents
  tables (Snapshots + Completed-phase artifacts sections).
- **Task 4.2** (lead-developer):
  `.ciagent/nova-blockchain-exchange/PROJECT.md` — add a one-line
  pointer to the platform ROADMAP for milestone-phase history (since
  the consumer ROADMAP is archived): "Phase-by-phase history:
  `.ciagent/ROADMAP.md` §v1.26 (the consumer ROADMAP is archived at
  `.ciagent/nova-blockchain-exchange/archive/ROADMAP-v1.26.md`)."

#### Wave 5 — fix any dangling references from P1 Wave 2
- **Task 5.1** (lead-developer): apply fixes for any dangling
  references found in P1 Wave 2.

#### Wave 6 — commit P2
- **Task 6.1** (lead-developer): single commit `docs(P02): fix stale
  phase-status + wire STATE.md into ship discipline` with `---ci---`
  block.

**Must-haves (verify before ship):**
- PROJECT.md v1.26 phase-status matches CHECKPOINT.json (P3/P4/P5
  complete, v1.26 shipped).
- ROADMAP.md v1.26 sections show P3/P4/P5 complete + Overview complete.
- PLAN.md P5 Wave 3 names STATE.md.
- NORTH_STAR.md notes STATE.md.
- archive/README.md lists the 8 new archived files.
- nova-blockchain-exchange/PROJECT.md points to platform ROADMAP.

### Phase P3 — final-review-ship (review + audit + milestone ship)

**Goal:** Final review + audit + milestone ship.

#### Wave 1 — review
- **Task 1.1** (lead-developer): review all P1/P2 changes for
  correctness (no broken markdown, no inaccurate citations, no
  dangling references).
- **Task 1.2** (lead-developer): fix any P0 issues in this phase.

#### Wave 2 — audit
- **Task 2.1** (lead-developer): reconstruction test — git log
  `---ci---` blocks ↔ `.ciagent/` files consistent; phase
  progression P0→P1→P2→P3.
- **Task 2.2** (lead-developer): `.ciagent/` file discipline —
  CHECKPOINT consistent with HEAD; PROJECT/ROADMAP phase-status
  consistent with CHECKPOINT; STATE.md present + 36 rows; archive
  contents match the moves.
- **Task 2.3** (lead-developer): branch hygiene — only main +
  milestone + P3; P1/P2 deleted.
- **Task 2.4** (lead-developer): commit discipline — all v1.27 commits
  carry `---ci---` blocks.

#### Wave 3 — milestone ship
- **Task 3.1** (lead-developer): merge `phase/03` →
  `milestone/v1.27-po-state-catalog` → `main`.
- **Task 3.2** (lead-developer): tag `v1.26.3` (= the v1.27 release per
  prev-minor tagging rule; v1.27 is an NFR milestone, tags on v1.26.x).
- **Task 3.3** (lead-developer): create Gitea release with full
  milestone summary.
- **Task 3.4** (lead-developer): delete all milestone branches (local
  + remote). Tags preserve all history.
- **Task 3.5** (lead-developer): update `.ciagent/REQUIREMENTS.md`
  (no REQs to mark — NFR milestone), `.ciagent/ROADMAP.md` (mark
  v1.27 complete), `.ciagent/NORTH_STAR.md` (no strategic change),
  `.ciagent/STATE.md` (bump "Last milestone ship" to v1.27).
- **Task 3.6** (lead-developer): write checkpoint `stage: complete,
  phase: 3, phase_role: final` + clear checkpoint (milestone
  complete).

**Must-haves (verify before ship):**
- Review: 0 P0 issues unfixed; P1+ flagged for post-hoc.
- Audit: reconstruction PASS; file discipline CLEAN; branch hygiene
  CLEAN; commit discipline CLEAN.
- Ship: `v1.26.3` tag exists; Gitea release created; milestone
  branches deleted; main has the milestone merge.

---

## Requirement → Phase Mapping

No REQ-NNN (NFR milestone). The work items are file operations,
traced by the Wave tasks above.

---

## Wave Ordering Rationale

- **P1 W1 → W2:** verify STATE.md before archiving (the archive removes
  the source-of-truth CAPABILITY_INVENTORY; STATE.md must be accurate
  first).
- **P1 W2 → W3:** platform archive before consumer archive (the
  platform archive pattern is established; the consumer archive
  creates a new subdir).
- **P2 W1 → W2 → W3:** PROJECT.md fix before ROADMAP.md fix before
  ship-discipline wiring (PROJECT is the source-of-truth narrative;
  ROADMAP mirrors it; PLAN/NORTH_STAR wire the convention).
- **P2 W4:** archive README + consumer pointer (cross-cutting; lands
  after the active-file fixes).
- **P2 W5:** dangling-reference fixes (lands after all moves + edits
  are known).

---

## Vertical-slice integrity

Each phase ships a self-contained, verifiable slice:
- P1 ships STATE.md (verified accurate) + 8 archived files (verified
  moved). The active `.ciagent/` root drops from 25 to 17 files.
- P2 ships 3 fixed files + 3 wired files + archive README + consumer
  pointer. The kept files match CHECKPOINT.json state.
- P3 ships the milestone release + cleared checkpoint.

---

## Durable convention (v1.27 establishes)

The P-final (milestone-ship) Wave 3 file-update list for every future
milestone includes `.ciagent/STATE.md`:

1. Append new capability entries for each shipped REQ (one row per
   capability; group by domain).
2. Mark any deprecated capability with a `Deprecated` row citing the
   milestone + replacement.
3. Bump the "Last milestone ship" header in STATE.md.

This is wired into the v1.25 + v1.26 P5 "Updated at ship" lists in
`ROADMAP.md` (see those sections). The next milestone's P0 PLAN.md
inherits this convention by reading ROADMAP.md.