acdl/.ciagent/PLAN.md

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.