@opengsd/gsd-core 1.7.0-rc.6 → 1.8.0

package/gsd-core/bin/lib/milestone.cjs

@@ -21,6 +21,8 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const clock_cjs_1 = require("./clock.cjs");
 const state_transition_cjs_1 = require("./state-transition.cjs");
+const write_set_cjs_1 = require("./write-set.cjs");
+const markdown_table_cjs_1 = require("./markdown-table.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
@@ -36,6 +38,51 @@ const { extractOneLinerFromBody } = coreUtilsMod;
 const { planningPaths } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 const { writeStateMd } = stateMod;
+// #2288 security: a milestone version label becomes a filesystem directory
+// component (`milestones/<label>-phases/`) into which phase directories are
+// MOVED. Any label used as a path segment must be a safe version token —
+// letters/digits/'.'/'-'/'_', leading alphanumeric, no path separators and no
+// `..` (the leading-alphanumeric anchor rejects a bare `..`). This gates both
+// the caller-supplied `--archive-version` override and the STATE.md-derived
+// live-read value, so a crafted value cannot escape `.planning/milestones/`.
+const ARCHIVE_VERSION_LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * Scope an `updateTableCell` call to the `## Traceability` (or
+ * `## Traceability Status`) heading's own section — up to the next H1/H2
+ * heading — instead of handing it the WHOLE REQUIREMENTS.md content.
+ *
+ * F1 (#2245 review, BLOCKER): `updateTableCell` binds to the FIRST GFM table
+ * found in whatever text it is given. The shipped requirements template
+ * (gsd-core/templates/requirements.md) puts an `## Out of Scope` table
+ * (`| Feature | Reason |`, no `Status` column) BEFORE `## Traceability` — so
+ * an unscoped whole-file call targets the Out-of-Scope table instead, fails
+ * with `{ok:false, reason:'unknown column: Status'}`, and the real
+ * Traceability row is never flipped, while the checkbox surface still flips
+ * and the command reports success (the #2140 silent-divergence class one
+ * level deeper). Mirrors phase.cts's `editProgressHeadingSlice` scoping of
+ * `## Progress` writes to that heading's own slice.
+ *
+ * Falls back to running `updateTableCell` against the whole `text` when no
+ * `## Traceability` heading exists — matching the previous (unscoped)
+ * behaviour for a REQUIREMENTS.md whose traceability table sits under some
+ * other heading, or with no heading at all (never worse than before this fix).
+ */
+function updateTraceabilityCell(text, match, column, newValue) {
+    const headingMatch = text.match(/^##[ \t]+Traceability(?:[ \t]+Status)?\b/im);
+    if (!headingMatch || headingMatch.index === undefined) {
+        return (0, markdown_table_cjs_1.updateTableCell)(text, match, column, newValue);
+    }
+    const headingOffset = headingMatch.index;
+    const before = text.slice(0, headingOffset);
+    const fromHeading = text.slice(headingOffset);
+    const nextHeadingOffset = fromHeading.search(/\n#{1,2}[ \t]/);
+    const scoped = nextHeadingOffset >= 0 ? fromHeading.slice(0, nextHeadingOffset) : fromHeading;
+    const after = nextHeadingOffset >= 0 ? fromHeading.slice(nextHeadingOffset) : '';
+    const result = (0, markdown_table_cjs_1.updateTableCell)(scoped, match, column, newValue);
+    if (!result.ok)
+        return result;
+    return { ok: true, value: before + result.value + after };
+}
 function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     if (!reqIdsRaw || reqIdsRaw.length === 0) {
         error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
@@ -59,56 +106,310 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     const updated = [];
     const alreadyComplete = [];
     const notFound = [];
+    // #2140: IDs reconciled on the checkbox surface only — a traceability table
+    // exists but has no row for the ID. Without this bucket the payload for a
+    // partial reconcile is byte-identical to a full one, and audit-milestone (which
+    // reads the table) still sees Pending while the CLI reported success.
+    const tableUnmatched = [];
+    // A traceability table is present if the file has a requirement-ID column
+    // header: "Requirement", "Requirement ID", or "REQ-ID" (#2769/#2203) — kept
+    // in sync with the positional first-cell rowMatch/hasRow below so a
+    // REQ-ID-headed table (the real-world format) participates in the
+    // write-set and the #2140 drift check below, not just the "Requirement"
+    // case. A REQUIREMENTS.md with no such table is legitimate (mid-roadmap),
+    // so a missing row only counts as drift when a table actually exists.
+    const hasTable = /^\|\s*(?:Requirement(?:\s*ID)?|REQ[-\s]?ID)\s*\|/im.test(reqContent);
+    // ADR-2143 §6 per-surface write-set, tracked PER requirement ID: a
+    // multi-ID batch must not OR one ID's surface outcome into another's —
+    // that is the exact #2140 class one level up (an ID whose traceability
+    // row is absent/unmatched must not have its partial write masked by a
+    // different ID in the same invocation that fully reconciled). Reported
+    // additively as `write_set` below — it does not change the existing
+    // marked_complete/already_complete/not_found/table_unmatched/updated
+    // computation, which stays byte-for-behaviour identical (#2140's tactical
+    // fix already surfaces the checkbox-only-partial-write case via
+    // table_unmatched; this only adds the structured ADR-2143 shape on top).
+    const writeSet = [];
     for (const reqId of reqIds) {
-        let found = false;
         const reqEscaped = escapeRegex(reqId);
-        // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
-        // Use replace() directly and compare — avoids test()+replace() global regex
+        // Surface 1 — the checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+        // Use replace() + compare to avoid the test()+replace() global regex
         // lastIndex bug where test() advances state and replace() misses matches.
         const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
         const afterCheckbox = reqContent.replace(checkboxPattern, '$1x$2');
-        if (afterCheckbox !== reqContent) {
+        const checkboxHit = afterCheckbox !== reqContent;
+        if (checkboxHit)
             reqContent = afterCheckbox;
-            found = true;
+        // Surface 2 — the traceability row: | <REQ-ID> | Phase N | Pending | → ... Complete |
+        // via the markdown-table seam (ADR-2143 §7) — supersedes the prior ordinal
+        // regex. Match the row by its FIRST cell's value (the requirement-ID column)
+        // regardless of that column's HEADER name — real tables head it `REQ-ID`,
+        // others `Requirement` (#2769/#2203); this mirrors the prior regex's first-cell
+        // `\|\s*<id>\s*\|` anchor. Object.values(row) is in header order so [0] is the
+        // first column. Case-insensitive (mirrors the prior regex's 'i' flag).
+        const rowMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === reqId.toLowerCase();
+        // Ragged-tolerant (#2245 Blocker 2): drive the write purely off
+        // updateTableCell's own tolerant row scan — a DIFFERENT requirement's row
+        // elsewhere in the same table having a mismatched cell count must never
+        // silently no-op THIS requirement's write. The "only flip Pending ->
+        // Complete" gate is folded into the newValue callback so one
+        // updateTableCell call both probes the current value and writes.
+        let tableHit = false;
+        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+            if (/^pending$/i.test(current.trim())) {
+                tableHit = true;
+                return ' Complete ';
+            }
+            return current;
+        });
+        if (tableUpdate.ok) {
+            reqContent = tableUpdate.value;
         }
-        // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete |
-        const tablePattern = new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
-        const afterTable = reqContent.replace(tablePattern, '$1 Complete $2');
-        if (afterTable !== reqContent) {
-            reqContent = afterTable;
-            found = true;
+        // ADR-2143 §6 per-ID write-set entries: this ID's checkbox surface is
+        // always tracked; the traceability surface is tracked only when the file
+        // has a traceability table at all (same `hasTable` gate the existing
+        // required-surface logic below uses) — omitted entirely, not a false
+        // `applied:false`, when no table is required of this file.
+        writeSet.push({ requirement: reqId, surface: 'checkbox', applied: checkboxHit });
+        if (hasTable) {
+            writeSet.push({ requirement: reqId, surface: 'traceability', applied: tableHit });
         }
-        if (found) {
+        // Coverage of the traceability surface for this ID (computed after any flip).
+        // hasRow keys on the ID's FIRST cell (the requirement-ID column, by position —
+        // see rowMatch above) so a bare mention of the ID in a non-traceability table
+        // does not masquerade as a real row.
+        // Ragged-tolerant (#2245 Blocker 2): same reasoning as the write above — a
+        // sibling row's raggedness must not blind this classification to a row
+        // that genuinely exists. Probe via a no-op updateTableCell write (its own
+        // tolerant scan) instead of findTableWithColumns (whole-table parse gate).
+        let currentStatusCell = '';
+        const statusProbe = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+            currentStatusCell = current;
+            return current;
+        });
+        const hasRow = statusProbe.ok;
+        const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i').test(reqContent);
+        const doneTable = Boolean(hasRow && /^complete$/i.test(currentStatusCell.trim()));
+        if (checkboxHit || tableHit) {
             updated.push(reqId);
         }
-        else {
-            // Check if already complete before declaring not_found.
-            // Non-global flag is fine here — we only need to know if a match exists.
-            const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i');
-            const doneTable = new RegExp(`\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|\\s*Complete\\s*\\|`, 'i');
-            if (doneCheckbox.test(reqContent) || doneTable.test(reqContent)) {
-                alreadyComplete.push(reqId);
-            }
-            else {
-                notFound.push(reqId);
-            }
+        else if (doneTable || (doneCheckbox && !hasTable)) {
+            // Fully reconciled: the table row is Complete, OR the checkbox is done and
+            // there is no table to reconcile against. (A [x] checkbox with a Pending or
+            // absent row is NOT fully reconciled when a table exists — #2140.)
+            alreadyComplete.push(reqId);
+        }
+        else if (!doneCheckbox && !doneTable) {
+            notFound.push(reqId);
+        }
+        // else: doneCheckbox && hasTable && !doneTable — partially reconciled. It is
+        // neither updated, already_complete, nor not_found; the table_unmatched bucket
+        // below carries the truthful partial-reconcile signal.
+        // Surface traceability drift: checkbox reconciled (this run or before) but the
+        // table has no row for this ID. This is what makes a partial reconcile
+        // distinguishable from a full one (#2140).
+        if (hasTable && doneCheckbox && !hasRow) {
+            tableUnmatched.push(reqId);
         }
     }
     if (updated.length > 0) {
         (0, shell_command_projection_cjs_1.platformWriteSync)(reqPath, reqContent);
     }
+    // ADR-2143 §6: `writeSet` above already carries one WriteOutcome per
+    // (requirement, surface) this invocation could have written to — per ID,
+    // not ORed across the batch. `write_set` and `write_set_complete` are
+    // additive: they do not replace or gate `updated` / `marked_complete` /
+    // `already_complete` / `not_found` / `table_unmatched`, which remain
+    // computed exactly as before (see #2140 note above — that fix already
+    // surfaces a checkbox-only partial write via `table_unmatched`;
+    // `write_set_complete` is a structured, ADR-2143-shaped read of the SAME
+    // per-surface, per-ID facts, `false` if ANY id's ANY required surface did
+    // not apply, since `writeSetComplete` requires EVERY entry to have
+    // applied, never an OR across surfaces OR across IDs).
     output({
         updated: updated.length > 0,
         marked_complete: updated,
         already_complete: alreadyComplete,
         not_found: notFound,
+        table_unmatched: tableUnmatched,
         total: reqIds.length,
+        write_set: writeSet,
+        write_set_complete: (0, write_set_cjs_1.writeSetComplete)(writeSet),
     }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
 }
+/**
+ * #2388: a requirement ID shared by more than one plan in a phase must not be
+ * handed to `cmdRequirementsMarkComplete` until every plan declaring it has
+ * finished (i.e. has a `*-SUMMARY.md`) — otherwise the ID reads `Complete` in
+ * REQUIREMENTS.md ~20 minutes before its sibling plans even run, and long
+ * before `verify_phase_goal` has a chance to catch a gap.
+ *
+ * Pure read-only gate: scans sibling `*-PLAN.md` files in the SAME phase
+ * directory as `planPath` (excluding `planPath` itself) and, for each
+ * candidate ID, blocks it only when a sibling plan ALSO declares that ID in
+ * its own `requirements:` frontmatter AND that sibling has no matching
+ * `*-SUMMARY.md` yet. An ID no sibling declares is never blocked — a
+ * single-plan (non-shared) ID is always `ready`, preserving immediate
+ * marking with no added latency (acceptance criterion 4). Does not read or
+ * write REQUIREMENTS.md itself; callers pass the `ready` subset on to
+ * `cmdRequirementsMarkComplete` (whose own flip semantics are untouched).
+ */
+function cmdRequirementsReadyIds(cwd, args, raw) {
+    const planPathArg = args[0];
+    if (!planPathArg) {
+        error('plan path required. Usage: requirements ready-ids <plan-path> REQ-01,REQ-02');
+    }
+    const reqIds = args
+        .slice(1)
+        .join(' ')
+        .replace(/[\[\]]/g, '')
+        .split(/[,\s]+/)
+        .map((r) => r.trim())
+        .filter(Boolean);
+    if (reqIds.length === 0) {
+        output({ ready: [], blocked: [], total: 0 }, raw, 'no requirement IDs provided');
+        return;
+    }
+    const planAbsPath = node_path_1.default.resolve(cwd, planPathArg);
+    const phaseDir = node_path_1.default.dirname(planAbsPath);
+    const currentBasename = node_path_1.default.basename(planAbsPath);
+    let siblingPlanFiles = [];
+    try {
+        siblingPlanFiles = node_fs_1.default
+            .readdirSync(phaseDir)
+            .filter((f) => f.endsWith('-PLAN.md') && f !== currentBasename);
+    }
+    catch {
+        siblingPlanFiles = [];
+    }
+    const parseFrontmatterReqIds = (content) => {
+        const fm = extractFrontmatter(content);
+        const fmReq = fm.requirements;
+        if (Array.isArray(fmReq))
+            return fmReq.map((r) => String(r).trim()).filter(Boolean);
+        if (typeof fmReq === 'string') {
+            return fmReq
+                .replace(/[\[\]]/g, '')
+                .split(/[,\s]+/)
+                .map((r) => r.trim())
+                .filter(Boolean);
+        }
+        return [];
+    };
+    const ready = [];
+    const blocked = [];
+    for (const reqId of reqIds) {
+        let blockedBySibling = false;
+        for (const siblingFile of siblingPlanFiles) {
+            const siblingPath = node_path_1.default.join(phaseDir, siblingFile);
+            let siblingContent;
+            try {
+                siblingContent = node_fs_1.default.readFileSync(siblingPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const siblingReqIds = parseFrontmatterReqIds(siblingContent);
+            const siblingDeclaresId = siblingReqIds.some((id) => id.toLowerCase() === reqId.toLowerCase());
+            if (!siblingDeclaresId)
+                continue;
+            // Sibling declares the SAME ID — it must have finished (produced a
+            // SUMMARY) before this ID is ready to mark Complete.
+            const siblingSummaryPath = siblingPath.replace(/-PLAN\.md$/, '-SUMMARY.md');
+            if (!node_fs_1.default.existsSync(siblingSummaryPath)) {
+                blockedBySibling = true;
+                break;
+            }
+        }
+        if (blockedBySibling)
+            blocked.push(reqId);
+        else
+            ready.push(reqId);
+    }
+    output({ ready, blocked, total: reqIds.length }, raw, `${ready.length}/${reqIds.length} requirement(s) ready to mark complete`);
+}
+/**
+ * #2388: revert this phase's own requirement IDs out of `Complete` when
+ * `verify_phase_goal` returns `gaps_found` — a gap verdict must not leave a
+ * premature `Complete` (from a shared ID's first-declaring plan, or from any
+ * other early write) sitting in REQUIREMENTS.md indefinitely.
+ *
+ * Mirrors `cmdRequirementsMarkComplete`'s two write surfaces in reverse:
+ * checkbox `[x]` -> `[ ]`, and traceability Status `Complete` -> `Gaps
+ * Found`. Phase-scoping is the CALLER's responsibility — this function only
+ * ever touches the exact IDs it is given, so a caller passing just this
+ * phase's own `phase_req_ids` never touches another phase's `Complete` row.
+ * Never call this on the pass path; it is `gaps_found`-only.
+ */
+function cmdRequirementsRevertPhase(cwd, reqIdsRaw, raw) {
+    const reqIds = (reqIdsRaw || [])
+        .join(' ')
+        .replace(/[\[\]]/g, '')
+        .split(/[,\s]+/)
+        .map((r) => r.trim())
+        .filter(Boolean);
+    if (reqIds.length === 0) {
+        output({ reverted: [], unchanged: [], total: 0 }, raw, 'no requirement IDs provided');
+        return;
+    }
+    const reqPath = planningPaths(cwd).requirements;
+    if (!node_fs_1.default.existsSync(reqPath)) {
+        output({ reverted: [], unchanged: reqIds, total: reqIds.length, reason: 'REQUIREMENTS.md not found' }, raw, 'no requirements file');
+        return;
+    }
+    let reqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
+    const reverted = [];
+    const unchanged = [];
+    for (const reqId of reqIds) {
+        const reqEscaped = escapeRegex(reqId);
+        let idReverted = false;
+        // Surface 1 — checkbox: - [x] **REQ-ID** -> - [ ] **REQ-ID**
+        const checkboxPattern = new RegExp(`(-\\s*\\[)x(\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+        const afterCheckbox = reqContent.replace(checkboxPattern, '$1 $2');
+        if (afterCheckbox !== reqContent) {
+            reqContent = afterCheckbox;
+            idReverted = true;
+        }
+        // Surface 2 — traceability row: Status Complete -> Gaps Found. Only
+        // flips a row currently reading Complete (mirrors mark-complete's own
+        // "only flip Pending -> Complete" gate, in reverse).
+        const rowMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === reqId.toLowerCase();
+        let tableHit = false;
+        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+            if (/^complete$/i.test(current.trim())) {
+                tableHit = true;
+                return ' Gaps Found ';
+            }
+            return current;
+        });
+        if (tableUpdate.ok) {
+            reqContent = tableUpdate.value;
+            if (tableHit)
+                idReverted = true;
+        }
+        if (idReverted)
+            reverted.push(reqId);
+        else
+            unchanged.push(reqId);
+    }
+    if (reverted.length > 0) {
+        (0, shell_command_projection_cjs_1.platformWriteSync)(reqPath, reqContent);
+    }
+    output({ reverted, unchanged, total: reqIds.length }, raw, `${reverted.length}/${reqIds.length} requirement(s) reverted from Complete`);
+}
 function cmdMilestoneComplete(cwd, version, options, raw) {
     if (!version) {
         error('version required for milestone complete (e.g., v1.0)');
     }
+    // #2288 security: `version` is a CLI positional that is interpolated into
+    // multiple filesystem sinks below — `path.join(archiveDir, `${version}-ROADMAP.md`)`,
+    // `${version}-REQUIREMENTS.md`, `${version}-MILESTONE-AUDIT.md`, and the
+    // `${version}-phases` archive directory that phase dirs are MOVED into. Reject
+    // path separators / `..` here (same guard as `--archive-version`) so a crafted
+    // version cannot write or relocate content outside `.planning/milestones/`.
+    if (!ARCHIVE_VERSION_LABEL_RE.test(version)) {
+        error(`milestone complete: version "${version}" is invalid — a milestone version label may contain only letters, digits, '.', '-' and '_', and must not contain path separators or "..".`);
+    }
     const roadmapPath = planningPaths(cwd).roadmap;
     const reqPath = planningPaths(cwd).requirements;
     const statePath = planningPaths(cwd).state;
@@ -120,10 +421,12 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     const milestonesPath = node_path_1.default.join(planningBase, 'MILESTONES.md');
     const archiveDir = node_path_1.default.join(planningBase, 'milestones');
     const phasesDir = planningPaths(cwd).phases;
-    const today = new Date().toISOString().split('T')[0];
+    const today = clock_cjs_1.realClock.localToday();
     const milestoneName = options.name || version;
-    // Ensure archive directory exists
-    (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveDir);
+    // Ensure archive directory exists (skipped in dry-run — no mutations)
+    if (!options.dryRun) {
+        (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveDir);
+    }
     // Scope stats and accomplishments to only the phases belonging to the
     // current milestone's ROADMAP.  Uses the shared filter from roadmap-parser.cjs
     // (same logic used by cmdPhasesList and other callers).
@@ -247,13 +550,62 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                     }
                 }
                 catch {
-                    /* intentionally empty */
+                    /* best-effort (#2245 audit): one unreadable/malformed SUMMARY.md
+                     * must not abort the accomplishments/task-count roll-up for every
+                     * OTHER summary across every OTHER phase — it's simply excluded
+                     * from the milestone's shipped-summary text. */
                 }
             }
         }
     }
     catch {
-        /* intentionally empty */
+        /* best-effort (#2245 audit): mirrors the phaseDirEntries IIFE a few
+         * lines below this function (same phasesDir, same "try readdirSync,
+         * tolerate ENOENT" pattern) — phasesDir may legitimately not exist yet
+         * (e.g. milestone being force-completed before any phase directories
+         * were created). Degrades stats to phaseCount/totalPlans/totalTasks=0,
+         * accomplishments=[] rather than crash `milestone complete`. */
+    }
+    // #2118: --dry-run preview — compute what WOULD happen without mutating.
+    // The stats above are read-only; all mutations start at the archive section below.
+    if (options.dryRun) {
+        const phaseDirsToArchive = [];
+        if (options.archivePhases !== false) {
+            try {
+                const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
+                for (const e of entries) {
+                    if (e.isDirectory() && isDirInMilestone(e.name)) {
+                        phaseDirsToArchive.push(e.name);
+                    }
+                }
+            }
+            catch { /* phasesDir missing — nothing to archive */ }
+        }
+        const dryRunResult = {
+            dry_run: true,
+            version,
+            name: milestoneName,
+            stats: { phases: phaseCount, plans: totalPlans, tasks: totalTasks },
+            accomplishments,
+            would_archive: {
+                roadmap: node_fs_1.default.existsSync(roadmapPath)
+                    ? { source: node_path_1.default.relative(cwd, roadmapPath).split(node_path_1.default.sep).join('/'), target: node_path_1.default.relative(cwd, node_path_1.default.join(archiveDir, `${version}-ROADMAP.md`)).split(node_path_1.default.sep).join('/') }
+                    : null,
+                requirements: node_fs_1.default.existsSync(reqPath)
+                    ? { source: node_path_1.default.relative(cwd, reqPath).split(node_path_1.default.sep).join('/'), target: node_path_1.default.relative(cwd, node_path_1.default.join(archiveDir, `${version}-REQUIREMENTS.md`)).split(node_path_1.default.sep).join('/') }
+                    : null,
+                audit: node_fs_1.default.existsSync(node_path_1.default.join(planningBase, `${version}-MILESTONE-AUDIT.md`))
+                    ? { source: node_path_1.default.relative(cwd, node_path_1.default.join(planningBase, `${version}-MILESTONE-AUDIT.md`)).split(node_path_1.default.sep).join('/'), target: node_path_1.default.relative(cwd, node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)).split(node_path_1.default.sep).join('/') }
+                    : null,
+                phases: phaseDirsToArchive,
+            },
+            would_update: {
+                milestones_md: node_path_1.default.relative(cwd, milestonesPath).split(node_path_1.default.sep).join('/'),
+                state_md: node_fs_1.default.existsSync(statePath) ? node_path_1.default.relative(cwd, statePath).split(node_path_1.default.sep).join('/') : null,
+            },
+        };
+        output(dryRunResult, raw);
+        return;
     }
     // Archive ROADMAP.md
     if (node_fs_1.default.existsSync(roadmapPath)) {
@@ -323,22 +675,33 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     let phasesArchived = false;
     // #1871: archive phase dirs by default on milestone complete (opt out via --no-archive-phases).
     if (options.archivePhases !== false) {
+        // #2245 audit (was ERROR-HIDING): retryRenameSync moves one phase dir at a
+        // time — a mid-loop failure (e.g. the Nth rename) used to leave
+        // `phasesArchived` at its `false` default even though the first N-1 dirs
+        // had ALREADY been moved to phaseArchiveDir on disk, silently
+        // under-reporting a real partial archive in the JSON result. archivedCount
+        // is now computed in a `finally` so it reflects whatever succeeded before
+        // any failure, instead of being lost with the swallowed exception.
+        let archivedCount = 0;
         try {
             const phaseArchiveDir = node_path_1.default.join(archiveDir, `${version}-phases`);
             (0, shell_command_projection_cjs_1.platformEnsureDir)(phaseArchiveDir);
             const phaseEntries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
             const phaseDirNames = phaseEntries.filter((e) => e.isDirectory()).map((e) => e.name);
-            let archivedCount = 0;
             for (const dir of phaseDirNames) {
                 if (!isDirInMilestone(dir))
                     continue;
                 (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, dir), node_path_1.default.join(phaseArchiveDir, dir));
                 archivedCount++;
             }
-            phasesArchived = archivedCount > 0;
         }
         catch {
-            /* intentionally empty */
+            /* best-effort: phasesDir may not exist yet, or the archive rename loop
+             * failed partway — phasesArchived below still reflects whatever
+             * archivedCount succeeded before the failure. */
+        }
+        finally {
+            phasesArchived = archivedCount > 0;
         }
     }
     const result = {
@@ -366,6 +729,32 @@ function cmdPhasesClear(cwd, raw, args) {
     // --force bypasses the uncommitted-changes guard. Only use when the caller
     // has already archived or explicitly accepts loss of uncommitted work. (#1447)
     const force = Array.isArray(args) && args.includes('--force');
+    // #2288: explicit outgoing-version override for the archive destination.
+    // new-milestone.md runs `state.milestone-switch` BEFORE `phases.clear --confirm`,
+    // so a live read of STATE.md would already report the NEW milestone version by
+    // the time we get here. Callers that know the outgoing version pass it explicitly;
+    // absent an override, archivePhaseDirectories falls back to the live read.
+    const avIndex = Array.isArray(args) ? args.indexOf('--archive-version') : -1;
+    let archiveVersionOverride = null;
+    if (avIndex !== -1) {
+        const rawArchiveVersion = args[avIndex + 1];
+        // Missing / flag-shaped value: fail loud instead of silently dropping the
+        // override. A truncated invocation (e.g. a broken template substitution
+        // leaving `--archive-version` with no value) must NOT fall through to the
+        // live read — that silently re-files the archive under the new milestone,
+        // the exact #2288 bug this flag exists to prevent.
+        if (typeof rawArchiveVersion !== 'string' || rawArchiveVersion.startsWith('--') || rawArchiveVersion.trim() === '') {
+            error('--archive-version requires a value (a milestone version token, e.g. v1.0)');
+        }
+        const trimmed = rawArchiveVersion.trim();
+        // #2288 security: reject path separators / `..` so a crafted value cannot
+        // relocate phase history outside `.planning/milestones/` (phase dirs are
+        // MOVED into the archive dir — a traversal is data loss, not just an odd name).
+        if (!ARCHIVE_VERSION_LABEL_RE.test(trimmed)) {
+            error(`--archive-version "${trimmed}" is invalid — a milestone version label may contain only letters, digits, '.', '-' and '_', and must not contain path separators or "..".`);
+        }
+        archiveVersionOverride = trimmed;
+    }
     let cleared = 0;
     if (node_fs_1.default.existsSync(phasesDir)) {
         const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
@@ -412,7 +801,8 @@ function cmdPhasesClear(cwd, raw, args) {
         }
         try {
             // #1871: archive phase directories instead of destroying them (shared helper).
-            cleared = archivePhaseDirectories(cwd, phasesDir, dirs).archived;
+            // #2288: thread the explicit --archive-version override (if any) through.
+            cleared = archivePhaseDirectories(cwd, phasesDir, dirs, archiveVersionOverride).archived;
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
@@ -423,18 +813,46 @@ function cmdPhasesClear(cwd, raw, args) {
 }
 /**
  * #1871: move each non-999 phase directory under `phasesDir` into
- * `milestones/<version>-phases/` (collision-safe; version from getMilestoneInfo,
- * timestamp fallback). Shared by `phases clear` (archive-then-remove) and the
- * internal milestone.complete phase archival so phase history survives a
- * milestone switch instead of being hard-deleted.
+ * `milestones/<version>-phases/` (collision-safe). Shared by `phases clear`
+ * (archive-then-remove) and the internal milestone.complete phase archival so
+ * phase history survives a milestone switch instead of being hard-deleted.
+ *
+ * Archive-version precedence (#2288): an explicit `archiveVersionOverride` wins
+ * first, then a live `getMilestoneInfo(cwd)` read (which itself defaults to a
+ * version like `v1.0` when ROADMAP/STATE is absent), and only a dated fallback
+ * label if no safe version label is resolvable at all. The override is validated
+ * by the caller (`cmdPhasesClear`); the live-read value is re-validated here
+ * (defense in depth) because `getMilestoneInfo` derives it from STATE.md's
+ * unvalidated `milestone:` field. The override exists because `new-milestone.md`
+ * runs `state.milestone-switch` BEFORE `phases.clear --confirm` — by the time
+ * this runs, a live read of STATE.md would already report the NEW milestone
+ * version, so phase history from the OLD milestone would be misfiled under the
+ * new version's archive directory. Callers that know the outgoing version must
+ * pass it explicitly.
  */
-function archivePhaseDirectories(cwd, phasesDir, dirs) {
-    let archiveVersion = null;
-    try {
-        archiveVersion = getMilestoneInfo(cwd).version ?? null;
-    }
-    catch {
-        /* ROADMAP/STATE unreadable — fall back to a dated label */
+function archivePhaseDirectories(cwd, phasesDir, dirs, archiveVersionOverride = null) {
+    // Self-protecting (#2288 security defense in depth): the sole current caller
+    // (`cmdPhasesClear`) already validates the override, but re-test it here so a
+    // future caller cannot reopen the path-traversal sink at line ~742. An override
+    // that fails the safe-label check is discarded (falls through to the live read
+    // / dated label) rather than reaching `path.join` unvalidated.
+    const safeOverride = archiveVersionOverride && ARCHIVE_VERSION_LABEL_RE.test(archiveVersionOverride.trim())
+        ? archiveVersionOverride.trim()
+        : null;
+    let archiveVersion = safeOverride;
+    if (!archiveVersion) {
+        try {
+            const liveVersion = getMilestoneInfo(cwd).version ?? null;
+            // Defense in depth (#2288 security): getMilestoneInfo reads STATE.md's
+            // `milestone:` field, which is unvalidated file content. Only accept it
+            // as a path component if it is a safe version label; a crafted value
+            // (path separators / `..`) falls through to the dated label below rather
+            // than escaping `.planning/milestones/`.
+            archiveVersion = liveVersion && ARCHIVE_VERSION_LABEL_RE.test(liveVersion) ? liveVersion : null;
+        }
+        catch {
+            /* ROADMAP/STATE unreadable — fall back to a dated label */
+        }
     }
     if (!archiveVersion) {
         archiveVersion = `archived-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 8)}`;
@@ -457,6 +875,8 @@ function archivePhaseDirectories(cwd, phasesDir, dirs) {
 }
 module.exports = {
     cmdRequirementsMarkComplete,
+    cmdRequirementsReadyIds,
+    cmdRequirementsRevertPhase,
     cmdMilestoneComplete,
     cmdPhasesClear,
 };