@pareto4/pp-core 1.11.1 → 1.12.0

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

@@ -27,13 +27,145 @@ const phaseIdMod = require("./phase-id.cjs");
 const { escapeRegex, normalizePhaseName, phaseTokenMatches } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { getMilestonePhaseFilter, extractCurrentMilestone } = roadmapParserMod;
+const { getMilestonePhaseFilter, extractCurrentMilestone, getClosedMilestonePhaseDirOwners } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtilsMod = require("./core-utils.cjs");
-const { extractOneLinerFromBody } = coreUtilsMod;
+const { extractOneLinerFromBody, toPosixPath } = coreUtilsMod;
 const { planningPaths } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
-const { writeStateMd, stateReplaceFieldWithFallback } = stateMod;
+const { writeStateMd, stateReplaceField, stateReplaceFieldWithFallback, matchSessionSection } = stateMod;
+/**
+ * Write `value` into the Session-scoped `Stopped at:` field — the exact scope the
+ * frontmatter `stopped_at` is derived from (matchSessionSection, as
+ * sessionStoppedAtField reads it) — so writeStateMd sees the caller changed the
+ * field and the frontmatter follows (261007-rly D-5, D-7). A Session section
+ * without the line gains it; a body without a Session section gains a
+ * `## Session` block holding the canonical `**Stopped at:**` label that
+ * `state record-session` writes.
+ */
+function setSessionStoppedAt(content, value) {
+    const m = matchSessionSection(content);
+    if (m && m.index !== undefined) {
+        const start = m.index + m[0].length - m[1].length;
+        const slice = m[1];
+        const replaced = stateReplaceField(slice, 'Stopped At', value) || stateReplaceField(slice, 'Stopped at', value);
+        const next = replaced ?? `${slice.replace(/\s+$/, '')}\n**Stopped at:** ${value}\n`;
+        return content.slice(0, start) + next + content.slice(start + slice.length);
+    }
+    return `${content.trimEnd()}\n\n## Session\n\n**Stopped at:** ${value}\n`;
+}
+// ─── The milestone record (261007-rly D-1, D-2, D-6) ─────────────────────────
+/** The marker for an index cell the engine cannot state truthfully — never a guess. */
+const NOT_RECORDED = '(not recorded)';
+/**
+ * The milestone label: the version once, then the name only when it says
+ * something the version does not (261007-rly D-2). One helper for the two
+ * surfaces that used to read `v1.1 v1.1` when no --name was given: the
+ * MILESTONES.md heading and the archived REQUIREMENTS header.
+ */
+function milestoneLabel(version, name) {
+    const n = (name || '').trim();
+    return !n || n === version ? version : `${version} ${n}`;
+}
+function splitTableRow(line) {
+    const t = line.trim();
+    if (!t.startsWith('|'))
+        return null;
+    return t.replace(/^\|/, '').replace(/(?<!\\)\|$/, '').split(/(?<!\\)\|/).map((c) => c.trim());
+}
+/** One cell for one header, read from the header text at write time (D-1's column map). */
+function indexCell(header, cells) {
+    let value;
+    switch (header.trim().toLowerCase()) {
+        case 'version':
+            value = cells.version;
+            break;
+        case 'shipped':
+        case 'date':
+            value = cells.shipped;
+            break;
+        case 'phases':
+            value = cells.phases === undefined ? undefined : String(cells.phases);
+            break;
+        case 'plans':
+            value = cells.plans === undefined ? undefined : String(cells.plans);
+            break;
+        case 'tasks':
+            value = cells.tasks === undefined ? undefined : String(cells.tasks);
+            break;
+        case 'name':
+            value = cells.name;
+            break;
+        case 'archive':
+            value = cells.archive;
+            break;
+        default: value = undefined; // Requirements, PRs, anything unforeseen
+    }
+    const text = (value ?? '').replace(/\s*\r?\n\s*/g, ' ').trim();
+    return text ? text.replace(/(?<!\\)\|/g, '\\|') : NOT_RECORDED;
+}
+/**
+ * The ONE writer of a milestone record into MILESTONES.md, shared by
+ * `milestone complete` and `validate health`'s backfill (261007-rly D-1, D-6).
+ *
+ * (a) The index row. Before the first `## ` line, a pipe table whose header row
+ * has a `Version` cell is the file's index: a row for this version is added
+ * directly below the separator (newest first, the order the live table and the
+ * sections both use), unless a body row already carries the version. No such
+ * table → no row; a table is never invented.
+ * (b) The section. Inserted immediately before the first `## ` line — after the
+ * H1, any preamble and the index table — never between the H1 and the table,
+ * which is where the old header-regex prepend put it on the live shape. With no
+ * `## ` line it is appended; an empty or missing file gets `# Milestones` + entry.
+ */
+function insertMilestoneRecord(existing, record) {
+    if (existing === null || existing === undefined || !existing.trim()) {
+        return { content: `# Milestones\n\n${record.entry}`, index_row: 'no_index_table' };
+    }
+    const crlf = existing.includes('\r\n');
+    const bare = (l) => l.replace(/\r$/, '');
+    const lines = existing.split('\n');
+    const firstSection = () => lines.findIndex((l) => /^## /.test(bare(l)));
+    let indexRow = 'no_index_table';
+    const limit = firstSection() === -1 ? lines.length : firstSection();
+    for (let i = 0; i + 1 < limit; i++) {
+        const header = splitTableRow(bare(lines[i]));
+        const versionCol = header ? header.findIndex((c) => c.toLowerCase() === 'version') : -1;
+        if (!header || versionCol === -1)
+            continue;
+        const separator = splitTableRow(bare(lines[i + 1]));
+        if (!separator || !separator.every((c) => /^:?-+:?$/.test(c)))
+            continue;
+        let present = false;
+        for (let j = i + 2; j < lines.length; j++) {
+            const row = splitTableRow(bare(lines[j]));
+            if (!row)
+                break;
+            if ((row[versionCol] || '') === record.version)
+                present = true;
+        }
+        if (present) {
+            indexRow = 'already_present';
+        }
+        else {
+            const row = `| ${header.map((h) => indexCell(h, record.cells)).join(' | ')} |`;
+            lines.splice(i + 2, 0, crlf ? `${row}\r` : row);
+            indexRow = 'added';
+        }
+        break;
+    }
+    const entry = crlf ? record.entry.replace(/\n/g, '\r\n') : record.entry;
+    const at = firstSection();
+    let content;
+    if (at === -1) {
+        content = `${lines.join('\n').replace(/\s+$/, '')}${crlf ? '\r\n\r\n' : '\n\n'}${entry}`;
+    }
+    else {
+        const head = at === 0 ? '' : `${lines.slice(0, at).join('\n')}\n`;
+        content = head + entry + lines.slice(at).join('\n');
+    }
+    return { content, index_row: indexRow };
+}
 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');
@@ -103,6 +235,21 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         total: reqIds.length,
     }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
 }
+/**
+ * The ONE refusal for "the planning base in scope has no ROADMAP.md" — the root of a
+ * project partitioned into workstreams when no --ws, env or pointer selects one, or a
+ * workstream right after `workstream create`. The predicate is the milestone filter's
+ * own `roadmapMissing` signal (CARRY-04); `milestone complete` and `phases
+ * archive-closed` both call this, so the two verbs answer the same input the same way
+ * (261007-mmz follow-up: archive-closed used to return an empty success there, which
+ * let new-milestone §7.5's stop check stay silent on an unsubstituted ${GSD_WS}).
+ */
+function refuseWithoutRoadmap(roadmapMissing, roadmapPath, what) {
+    if (roadmapMissing) {
+        error(`ROADMAP.md not found at ${roadmapPath} — nothing to ${what}. ` +
+            `Write it, or pass --ws <name> if this project is partitioned into workstreams.`);
+    }
+}
 function cmdMilestoneComplete(cwd, version, options, raw) {
     if (!version) {
         error('version required for milestone complete (e.g., v1.0)');
@@ -110,20 +257,55 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     const roadmapPath = planningPaths(cwd).roadmap;
     const reqPath = planningPaths(cwd).requirements;
     const statePath = planningPaths(cwd).state;
-    const milestonesPath = node_path_1.default.join(cwd, '.planning', 'MILESTONES.md');
-    const archiveDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    // A milestone record belongs beside the ROADMAP it closes, so a project
+    // partitioned into workstreams archives into its OWN .planning/workstreams/
+    // <name>/milestones/ rather than the repo root — which is where all three of
+    // these used to land while roadmap/requirements/state/phases above already
+    // resolved per workstream. `--ws` needs no parsing here: pp-tools.cjs strips
+    // it centrally and applies it as GSD_WORKSTREAM, which planningDir() reads,
+    // and routing through planningPaths inherits that function's rejection of
+    // path separators and `..` in the name (phase 12, CARRY-04).
+    //
+    // CARRY-05: the location is no longer joined here — planningPaths owns it, so
+    // this writer and every reader resolve the same two paths from one place.
+    const milestonesPath = planningPaths(cwd).milestones;
+    const archiveDir = planningPaths(cwd).milestonesArchive;
     const phasesDir = planningPaths(cwd).phases;
     const today = new Date().toISOString().split('T')[0];
     const milestoneName = options.name || version;
-    // Ensure archive directory exists
-    (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).
+    //
+    // All three refusals run BEFORE the archive directory is created below: a
+    // close that is going to be refused must leave nothing behind, not even an
+    // empty milestones/ directory. This is also the ONLY consumer of the filter's
+    // signal properties — the other nine call sites read none (phase 12).
     const isDirInMilestone = getMilestonePhaseFilter(cwd, version);
+    refuseWithoutRoadmap(isDirInMilestone.roadmapMissing, roadmapPath, 'close');
     if (isDirInMilestone.missingExplicitVersion) {
         error(`no phases found for milestone ${version} in ROADMAP.md`);
     }
+    // The third "could not scope this" arm (261007-mmz D-1, D-3). A ROADMAP that
+    // reads fine and declares the version but names no phase for it — or whose
+    // parse threw, which the filter swallows — yields the same pass-all callable
+    // with phaseCount 0. At this consumer that is indistinguishable from "this
+    // milestone legitimately contains every directory", so it used to count every
+    // directory under phases/ into MILESTONES.md, overwrite the archived
+    // <version>-ROADMAP.md snapshot, and under --archive-phases rename them all
+    // under this version's label, exit 0. The filter stays pass-all for its nine
+    // non-destructive callers (changing it changes ten call sites at once, the
+    // CARRY-04 argument); the refusal lives here, unconditionally, because the
+    // close without --archive-phases writes those false records too.
+    // See todos/done/milestone-complete-archives-every-directory-when-the-roadmap-lists-no-phases.md.
+    if (isDirInMilestone.phaseCount === 0) {
+        error(`milestone ${version}: ROADMAP.md at ${roadmapPath} names no phase for this milestone — ` +
+            `refusing to close; nothing was archived, moved or written. ` +
+            `List the milestone's phases as "### Phase N: Name" headings under its milestone, ` +
+            `or pass the version the ROADMAP declares.`);
+    }
+    // Ensure archive directory exists
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveDir);
     // Guard: prevent marking complete when ROADMAP still lists phases that have
     // no directory on disk (disk_status: no_directory). This catches the case
     // where the active milestone was erroneously marked complete before phases
@@ -245,43 +427,54 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
         (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(archiveDir, `${version}-ROADMAP.md`), roadmapContent);
     }
     // Archive REQUIREMENTS.md
+    // 261007-rly D-1: the Archive cell links only what THIS run wrote.
+    const archivedHere = [];
+    if (node_fs_1.default.existsSync(roadmapPath))
+        archivedHere.push(`${version}-ROADMAP.md`);
     if (node_fs_1.default.existsSync(reqPath)) {
+        archivedHere.push(`${version}-REQUIREMENTS.md`);
         const reqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
-        const archiveHeader = `# Requirements Archive: ${version} ${milestoneName}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`.planning/REQUIREMENTS.md\`.\n\n---\n\n`;
+        // 261007-rly D-2: the version once when no --name was given.
+        const archiveHeader = `# Requirements Archive: ${milestoneLabel(version, options.name)}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`.planning/REQUIREMENTS.md\`.\n\n---\n\n`;
         (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent);
     }
     // Archive audit file if exists
-    const auditFile = node_path_1.default.join(cwd, '.planning', `${version}-MILESTONE-AUDIT.md`);
+    const auditFile = node_path_1.default.join(planningPaths(cwd).planning, `${version}-MILESTONE-AUDIT.md`);
     if (node_fs_1.default.existsSync(auditFile)) {
         node_fs_1.default.renameSync(auditFile, node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
+        archivedHere.push(`${version}-MILESTONE-AUDIT.md`);
     }
-    // Create/append MILESTONES.md entry
+    // Under --archive-phases the directory is created unconditionally below and a
+    // failed move ends the verb naming the partial state, so the target exists
+    // whenever the verb returns (261007-rly D-1).
+    if (options.archivePhases)
+        archivedHere.push(`${version}-phases/`);
+    // Create/append MILESTONES.md entry — one row in the index table (when the
+    // file has one) and the section after it, through the shared record writer
+    // (261007-rly D-1, D-2, D-6).
     const accomplishmentsList = accomplishments.map((a) => `- ${a}`).join('\n');
-    const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
-    if (node_fs_1.default.existsSync(milestonesPath)) {
-        const existing = node_fs_1.default.readFileSync(milestonesPath, 'utf-8');
-        if (!existing.trim()) {
-            // Empty file — treat like new
-            (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
-        }
-        else {
-            // Insert after the header line(s) for reverse chronological order (newest first)
-            const headerMatch = existing.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
-            if (headerMatch) {
-                const header = headerMatch[1];
-                const rest = existing.slice(header.length);
-                (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, header + milestoneEntry + rest);
-            }
-            else {
-                // No recognizable header — prepend the entry
-                (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, milestoneEntry + existing);
-            }
-        }
-    }
-    else {
-        (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
-    }
+    const milestoneEntry = `## ${milestoneLabel(version, options.name)} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+    const linkPrefix = toPosixPath(node_path_1.default.relative(node_path_1.default.dirname(milestonesPath), archiveDir));
+    const archiveCell = archivedHere
+        .map((f) => `[${f}](${linkPrefix ? `${linkPrefix}/` : ''}${f})`)
+        .join(' · ');
+    const milestonesRecord = insertMilestoneRecord(node_fs_1.default.existsSync(milestonesPath) ? node_fs_1.default.readFileSync(milestonesPath, 'utf-8') : null, {
+        version,
+        entry: milestoneEntry,
+        cells: {
+            version,
+            shipped: today,
+            phases: phaseCount,
+            plans: totalPlans,
+            tasks: totalTasks,
+            name: options.name || null,
+            archive: archiveCell,
+        },
+    });
+    (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, milestonesRecord.content);
     // Update STATE.md — keep frontmatter/body semantically aligned after closure
+    // 261007-ixt D-3: every frontmatter key the shared writer changed is named.
+    let stateFrontmatterUpdated = [];
     if (node_fs_1.default.existsSync(statePath)) {
         let stateContent = node_fs_1.default.readFileSync(statePath, 'utf-8');
         stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null, `${version} milestone complete`);
@@ -308,28 +501,57 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
         else {
             stateContent = `${stateContent.trimEnd()}\n\n## Operator Next Steps\n\n- Start the next milestone with ${(0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))}\n`;
         }
-        writeStateMd(statePath, stateContent, cwd);
+        // 261007-rly D-5: the Session `Stopped at:` line — and through writeStateMd's
+        // delta the frontmatter stopped_at — moves only when the caller passes a new
+        // value. Without --stopped-at neither moves and the key is not reported.
+        // T-rly-03: operator text, written as ONE line — a newline in the value could
+        // otherwise open a new section of STATE.md below the Session block.
+        const stoppedAt = typeof options.stoppedAt === 'string' ? options.stoppedAt.replace(/\s+/g, ' ').trim() : '';
+        if (stoppedAt) {
+            stateContent = setSessionStoppedAt(stateContent, stoppedAt);
+        }
+        stateFrontmatterUpdated = writeStateMd(statePath, stateContent, cwd, undefined, { stoppedAtSetByCaller: !!stoppedAt }).frontmatter_updated;
     }
     // Archive phase directories if requested
     let phasesArchived = false;
     if (options.archivePhases) {
+        const phaseArchiveDir = node_path_1.default.join(archiveDir, `${version}-phases`);
+        // A missing phases/ directory is "nothing to archive" — archived.phases
+        // stays false, which is true. Anything else that goes wrong is reported:
+        // a blanket catch here used to swallow a failed rename, so the verb exited
+        // 0 reporting archived.phases: false while every directory sorted before
+        // the failure HAD moved and the rest stayed behind (measured, 261007-mmz).
+        let phaseDirNames = [];
         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;
-                node_fs_1.default.renameSync(node_path_1.default.join(phasesDir, dir), node_path_1.default.join(phaseArchiveDir, dir));
-                archivedCount++;
+            phaseDirNames = node_fs_1.default
+                .readdirSync(phasesDir, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name)
+                .filter((name) => isDirInMilestone(name))
+                .sort();
+        }
+        catch (e) {
+            if (e?.code !== 'ENOENT') {
+                const message = e instanceof Error ? e.message : String(e);
+                error(`--archive-phases: could not read ${phasesDir}; the milestone record was already written. ${message}`);
             }
-            phasesArchived = archivedCount > 0;
+            phaseDirNames = [];
         }
-        catch {
-            /* intentionally empty */
+        (0, shell_command_projection_cjs_1.platformEnsureDir)(phaseArchiveDir);
+        const moved = [];
+        for (const dir of phaseDirNames) {
+            try {
+                node_fs_1.default.renameSync(node_path_1.default.join(phasesDir, dir), node_path_1.default.join(phaseArchiveDir, dir));
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                error(`--archive-phases: could not move ${dir} into ${phaseArchiveDir} after moving ` +
+                    `${moved.length} of ${phaseDirNames.length} (${moved.length > 0 ? moved.join(', ') : 'none'}); ` +
+                    `the milestone record was already written. ${message}`);
+            }
+            moved.push(dir);
         }
+        phasesArchived = moved.length > 0;
     }
     const result = {
         version,
@@ -346,7 +568,9 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             phases: phasesArchived,
         },
         milestones_updated: true,
+        milestones_index_row: milestonesRecord.index_row,
         state_updated: node_fs_1.default.existsSync(statePath),
+        state_frontmatter_updated: stateFrontmatterUpdated,
     };
     output(result, raw);
 }
@@ -374,8 +598,81 @@ function cmdPhasesClear(cwd, raw, args) {
     }
     output({ cleared }, raw, `${cleared} phase director${cleared === 1 ? 'y' : 'ies'} cleared`);
 }
+/**
+ * `phases archive-closed [--dry-run]` (261007-mmz): move each directory under
+ * `phases/` that exactly one CLOSED milestone names into that milestone's
+ * `milestones/<version>-phases/`, and leave every other directory in place,
+ * reporting why. Membership comes from getClosedMilestonePhaseDirOwners — the
+ * archived `<version>-ROADMAP.md` snapshot lists the directory's number AND name,
+ * and the current milestone does not — the predicate the progress writer already
+ * reads (261007-ixt D-9). It replaces new-milestone.md's `--reset-phase-numbers`
+ * shell move, which renamed EVERY directory into the latest milestone's archive
+ * and so recorded a phase no milestone named as that milestone's (sweep R17a).
+ * Paths resolve through planningPaths, so `--ws` scopes it to one workstream.
+ */
+function cmdPhasesArchiveClosed(cwd, raw, args) {
+    const dryRun = Array.isArray(args) && args.includes('--dry-run');
+    const phasesDir = planningPaths(cwd).phases;
+    const archiveDir = planningPaths(cwd).milestonesArchive;
+    refuseWithoutRoadmap(getMilestonePhaseFilter(cwd).roadmapMissing, planningPaths(cwd).roadmap, 'archive');
+    const ownersOf = getClosedMilestonePhaseDirOwners(cwd);
+    let dirNames = [];
+    try {
+        dirNames = node_fs_1.default
+            .readdirSync(phasesDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT') {
+            const message = e instanceof Error ? e.message : String(e);
+            error(`phases archive-closed: could not read ${phasesDir}. ${message}`);
+        }
+    }
+    const rel = (p) => node_path_1.default.relative(cwd, p).split(node_path_1.default.sep).join('/');
+    const planned = [];
+    const left = [];
+    for (const dir of dirNames) {
+        const owners = ownersOf(dir);
+        if (owners.length === 1) {
+            planned.push({ dir, milestone: owners[0], to: node_path_1.default.join(archiveDir, `${owners[0]}-phases`, dir) });
+        }
+        else if (owners.length > 1) {
+            left.push({ dir, reason: 'named_by_several_closed_milestones', milestones: owners });
+        }
+        else if (/^999(?:\.|-|$)/.test(dir)) {
+            left.push({ dir, reason: 'backlog' });
+        }
+        else {
+            left.push({ dir, reason: 'not_named_by_a_closed_milestone' });
+        }
+    }
+    const moved = [];
+    if (!dryRun) {
+        for (const item of planned) {
+            try {
+                if (node_fs_1.default.existsSync(item.to))
+                    throw new Error(`${rel(item.to)} already exists`);
+                (0, shell_command_projection_cjs_1.platformEnsureDir)(node_path_1.default.dirname(item.to));
+                node_fs_1.default.renameSync(node_path_1.default.join(phasesDir, item.dir), item.to);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                error(`phases archive-closed: could not move ${item.dir} into ${rel(node_path_1.default.dirname(item.to))} after moving ` +
+                    `${moved.length} of ${planned.length} (${moved.length > 0 ? moved.map((m) => m.dir).join(', ') : 'none'}). ${message}`);
+            }
+            moved.push(item);
+        }
+    }
+    const shown = (dryRun ? planned : moved).map((m) => ({ dir: m.dir, milestone: m.milestone, to: rel(m.to) }));
+    output({ dry_run: dryRun, moved: shown, left }, raw, `${shown.length} phase director${shown.length === 1 ? 'y' : 'ies'} ${dryRun ? 'would be ' : ''}archived; ${left.length} left in place`);
+}
 module.exports = {
     cmdRequirementsMarkComplete,
     cmdMilestoneComplete,
+    insertMilestoneRecord,
+    milestoneLabel,
     cmdPhasesClear,
+    cmdPhasesArchiveClosed,
 };

package/pp-core/bin/lib/phase-command-router.cjs

@@ -6,7 +6,7 @@
  * Unsupported in this router:
  * - scaffold: routed through top-level scaffold command.
  *
- * CJS-only subcommands: mvp-mode (dispatched directly, before hub).
+ * CJS-only subcommands: mvp-mode, dispatch-plan, install-run, tier, tier-propose (dispatched directly, before hub).
  *
  * #3788: dispatch is mediated by CommandRoutingHub. The public entry point
  * and observable CLI behaviour are unchanged.
@@ -51,6 +51,28 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
         phase.cmdPhaseMvpMode(cwd, args.slice(2), raw);
         return;
     }
+    // `dispatch-plan` (pack 9): read-only; the executor spawns, suite runs and
+    // tracking commits execute-phase obeys (src/dispatch-plan.cts).
+    if (subcommand === 'dispatch-plan') {
+        phase.cmdPhaseDispatchPlan(cwd, args.slice(2), raw);
+        return;
+    }
+    // `install-run` (pack 9): heavy-tier verification of the installed product —
+    // pack, install, init, run the phase's install checks (src/install-run.cts).
+    if (subcommand === 'install-run') {
+        phase.cmdPhaseInstallRun(cwd, args.slice(2), raw);
+        return;
+    }
+    // `tier` / `tier-propose` (pack 9): the phase's ceremony tier and its
+    // proposal (src/phase-tier.cts); `tier-propose --record` writes ROADMAP.
+    if (subcommand === 'tier') {
+        phase.cmdPhaseTier(cwd, args.slice(2), raw);
+        return;
+    }
+    if (subcommand === 'tier-propose') {
+        phase.cmdPhaseTierPropose(cwd, args.slice(2), raw);
+        return;
+    }
     // ── Build the CJS registry ──────────────────────────────────────────────────
     // Each handler receives a ctx object from the hub and must return a HubResult.
     const cjsRegistry = {

package/pp-core/bin/lib/phase-locator.cjs

@@ -14,7 +14,7 @@
  *   - node:fs / node:path (stdlib)
  *   - ./phase-id.cjs       (normalizePhaseName, phaseTokenMatches, extractPhaseToken)
  *   - ./core-utils.cjs     (readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath)
- *   - ./planning-workspace.cjs (planningDir)
+ *   - ./planning-workspace.cjs (planningDir, planningPaths)
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -29,7 +29,7 @@ const coreUtilsModule = require("./core-utils.cjs");
 const { readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath } = coreUtilsModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningDir } = planningWorkspace;
+const { planningDir, planningPaths } = planningWorkspace;
 // ─── Phase search helpers ─────────────────────────────────────────────────────
 function searchPhaseInDir(baseDir, relBase, normalized) {
     try {
@@ -83,9 +83,15 @@ function findPhaseInternal(cwd, phase) {
     const current = searchPhaseInDir(phasesDir, relPhasesDir, normalized);
     if (current)
         return current;
-    const milestonesDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    // CARRY-05: the archive directory is planningPaths' to name, not ours. The
+    // hardcoded path.join(cwd, '.planning', 'milestones') that stood here
+    // bypassed the workspace helper entirely, so a phase archived inside a
+    // workstream was unreachable from every verb that resolves through
+    // findPhaseInternal.
+    const milestonesDir = planningPaths(cwd).milestonesArchive;
     if (!node_fs_1.default.existsSync(milestonesDir))
         return null;
+    const relMilestonesDir = node_path_1.default.relative(cwd, milestonesDir);
     try {
         const milestoneEntries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
         const archiveDirs = milestoneEntries
@@ -97,7 +103,7 @@ function findPhaseInternal(cwd, phase) {
             const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
             const version = versionMatch[1];
             const archivePath = node_path_1.default.join(milestonesDir, archiveName);
-            const relBase = '.planning/milestones/' + archiveName;
+            const relBase = toPosixPath(node_path_1.default.join(relMilestonesDir, archiveName));
             const result = searchPhaseInDir(archivePath, relBase, normalized);
             if (result) {
                 result.archived = version;
@@ -109,7 +115,10 @@ function findPhaseInternal(cwd, phase) {
     return null;
 }
 function getArchivedPhaseDirs(cwd) {
-    const milestonesDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    // CARRY-05: same owner as findPhaseInternal above and as the `milestone
+    // complete` writer — not a second hardcoded copy.
+    const milestonesDir = planningPaths(cwd).milestonesArchive;
+    const relMilestonesDir = node_path_1.default.relative(cwd, milestonesDir);
     const results = [];
     if (!node_fs_1.default.existsSync(milestonesDir))
         return results;
@@ -129,7 +138,7 @@ function getArchivedPhaseDirs(cwd) {
                 results.push({
                     name: dir,
                     milestone: version,
-                    basePath: node_path_1.default.join('.planning', 'milestones', archiveName),
+                    basePath: node_path_1.default.join(relMilestonesDir, archiveName),
                     fullPath: node_path_1.default.join(archivePath, dir),
                 });
             }