@pareto4/pp-core 1.11.0 → 1.12.0

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

@@ -35,10 +35,13 @@ const phaseIdMod = require("./phase-id.cjs");
 const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, phaseTokenMatches } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal, getArchivedPhaseDirs } = phaseLocatorMod;
+const { getArchivedPhaseDirs } = phaseLocatorMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-scope.cjs is an export= CommonJS module
+const phaseScopeMod = require("./phase-scope.cjs");
+const { resolvePhaseForRead } = phaseScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- roadmap-parser.cjs is an export= CommonJS module
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { stripShippedMilestones, extractCurrentMilestone, getMilestonePhaseFilter } = roadmapParserMod;
+const { stripShippedMilestones, extractCurrentMilestone, getMilestonePhaseFilter, buildPlansSummaryLinePattern } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
@@ -48,11 +51,16 @@ const stateMod = require("./state.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+const state_document_cjs_1 = require("./state-document.cjs");
 const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- uat-predicate.cjs is an export= CommonJS module
 const uatPredicate = require("./uat-predicate.cjs");
 const { evaluateUatPassed } = uatPredicate;
-const { planningDir, withPlanningLock } = planningWorkspace;
+const plan_graph_cjs_1 = require("./plan-graph.cjs");
+const dispatch_plan_cjs_1 = require("./dispatch-plan.cjs");
+const phase_tier_cjs_1 = require("./phase-tier.cjs");
+const install_run_cjs_1 = require("./install-run.cjs");
+const { planningDir, withPlanningLock, milestonePathsFor } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 const { readModifyWriteStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, syncStateFrontmatter, withStateLock, updatePerformanceMetricsSection, } = stateMod;
 // #2893 — strict canonical filter: `{padded_phase}-{NN}-PLAN.md` or `PLAN.md`.
@@ -287,7 +295,8 @@ function cmdFindPhase(cwd, phase, raw) {
     if (node_fs_1.default.existsSync(flatPhasesDir))
         searchDirs.push(flatPhasesDir);
     try {
-        const milestonesDir = node_path_1.default.join(planBase, 'milestones');
+        // CARRY-05: archive location from the owner, not a local join.
+        const milestonesDir = milestonePathsFor(planBase).milestonesArchive;
         const entries = node_fs_1.default
             .readdirSync(milestonesDir, { withFileTypes: true })
             .filter((e) => e.isDirectory() && /^v\d+.*-phases$/.test(e.name))
@@ -399,6 +408,140 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     if (!phase) {
         error('phase required for phase-plan-index');
     }
+    const built = buildPhasePlanIndex(cwd, phase);
+    if (built.fatal !== undefined) {
+        error(built.fatal);
+        return;
+    }
+    output(built.result, raw);
+}
+/**
+ * `phase.dispatch-plan <phase> [--wave N] [--gaps-only] [--use-worktrees true|false]`:
+ * the executor spawns, builds, suite runs and tracking commits for the phase's
+ * incomplete plans (computed by src/dispatch-plan.cts from the plan inventory).
+ */
+function cmdPhaseDispatchPlan(cwd, args, raw) {
+    const parsed = (0, dispatch_plan_cjs_1.parseDispatchPlanArgs)(args);
+    if ('error' in parsed) {
+        error(parsed.error);
+        return;
+    }
+    const built = buildPhasePlanIndex(cwd, parsed.phase);
+    if (built.fatal !== undefined) {
+        error(built.fatal);
+        return;
+    }
+    if (built.phaseDir === null) {
+        output({ phase: built.result['phase'], error: 'Phase not found' }, raw);
+        return;
+    }
+    const policy = (0, dispatch_plan_cjs_1.resolveDispatchPolicy)(cwd, parsed);
+    const plans = built.result['plans'].map((p) => {
+        const extra = built.extras.get(p['id']);
+        return {
+            id: p['id'],
+            title: p['title'] ?? null,
+            wave: p['wave'],
+            serial_group: p['serial_group'] ?? null,
+            files_modified: p['files_modified'],
+            autonomous: p['autonomous'],
+            has_summary: p['has_summary'],
+            requirements: extra?.requirements ?? [],
+            gap_closure: extra?.gapClosure ?? false,
+        };
+    });
+    const phaseDirRel = node_path_1.default.relative(cwd, built.phaseDir).split(node_path_1.default.sep).join('/');
+    const tier = (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, parsed.phase, parsed.tier);
+    output((0, dispatch_plan_cjs_1.computeDispatchPlan)(built.result['phase'], phaseDirRel, plans, policy, tier, { planBounceScript: tier.plan_bounce_script }), raw);
+}
+/**
+ * `phase.install-run <phase> [--tarball <tgz>] [--package-dir <dir>] [--no-build]`:
+ * pack, install into a temp project, init and run the phase's install checks
+ * against the installed copy; writes `<NN>-INSTALL-RUN.json` (src/install-run.cts).
+ */
+function cmdPhaseInstallRun(cwd, args, raw) {
+    const parsed = (0, install_run_cjs_1.parseInstallRunArgs)(args);
+    if ('error' in parsed) {
+        error(parsed.error, ERROR_REASON.USAGE);
+        return;
+    }
+    let out;
+    try {
+        out = (0, install_run_cjs_1.runInstallRun)({ cwd, phase: parsed.phase, tarball: parsed.tarball, packageDir: parsed.packageDir, build: parsed.build });
+    }
+    catch (e) {
+        error(e.message);
+        return;
+    }
+    output(out, raw);
+}
+/**
+ * `phase.tier <phase> [--tier light|standard|heavy]`: the phase's resolved
+ * ceremony tier — tier, source, gate set, suppressed gates (src/phase-tier.cts).
+ */
+function cmdPhaseTier(cwd, args, raw) {
+    const usage = 'Usage: phase tier <phase> [--tier light|standard|heavy]';
+    const parsed = (0, phase_tier_cjs_1.parseTierFlag)(args.filter((a) => a !== '--raw'));
+    if ('error' in parsed) {
+        error(`${parsed.error}. ${usage}`, ERROR_REASON.USAGE);
+        return;
+    }
+    if (parsed.rest.length !== 1 || parsed.rest[0].startsWith('--')) {
+        error(parsed.rest.length === 0 ? `phase required for phase tier. ${usage}` : `phase tier takes one phase and --tier. ${usage}`, ERROR_REASON.USAGE);
+        return;
+    }
+    const phaseArg = parsed.rest[0];
+    output({ phase: phaseArg, ...(0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, phaseArg, parsed.tier) }, raw);
+}
+/**
+ * `phase.tier-propose <phase> [--record] [--tier X]`: propose a tier from the
+ * phase's plans (`files_modified`) or, before planning, its requirement tags
+ * and ROADMAP text. `--record` writes it to the phase's ROADMAP `**Tier:**`
+ * field, marked `(proposed: …)`, unless the operator already chose one;
+ * `--record --tier X` records X as the operator's choice.
+ */
+function cmdPhaseTierPropose(cwd, args, raw) {
+    const usage = 'Usage: phase tier-propose <phase> [--record] [--tier light|standard|heavy]';
+    const parsed = (0, phase_tier_cjs_1.parseTierFlag)(args.filter((a) => a !== '--raw'));
+    if ('error' in parsed) {
+        error(`${parsed.error}. ${usage}`, ERROR_REASON.USAGE);
+        return;
+    }
+    const doRecord = parsed.rest.includes('--record');
+    const positional = parsed.rest.filter((a) => a !== '--record');
+    if (positional.length !== 1 || positional[0].startsWith('--')) {
+        error(positional.length === 0 ? `phase required for phase tier-propose. ${usage}` : `phase tier-propose does not support ${positional.find((a) => a.startsWith('--')) ?? positional.join(' ')}. ${usage}`, ERROR_REASON.USAGE);
+        return;
+    }
+    const phaseArg = positional[0];
+    const record = (0, phase_tier_cjs_1.readPhaseRecord)(cwd, phaseArg);
+    if (record.section === null) {
+        output({ phase: phaseArg, error: 'Phase not found in ROADMAP.md' }, raw);
+        return;
+    }
+    const built = buildPhasePlanIndex(cwd, phaseArg);
+    const planRows = built.fatal === undefined && built.phaseDir !== null
+        ? built.result['plans'].map((p) => ({ id: p['id'], files_modified: p['files_modified'] ?? [] }))
+        : [];
+    const reqMatch = record.section.match(/^\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]*)$/m);
+    const requirements = reqMatch ? reqMatch[1].replace(/[[\]]/g, '').split(',').map((s) => s.trim()).filter((s) => s !== '' && s !== 'TBD') : [];
+    const proposal = (0, phase_tier_cjs_1.proposePhaseTier)({ plans: planRows, requirements, roadmapText: record.section });
+    let recorded = null;
+    if (doRecord) {
+        recorded = parsed.tier !== null
+            ? (0, phase_tier_cjs_1.recordPhaseTier)(cwd, phaseArg, parsed.tier, { proposed: false })
+            : (0, phase_tier_cjs_1.recordPhaseTier)(cwd, phaseArg, proposal.tier, { proposed: true, reason: proposal.reason });
+    }
+    const after = (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, phaseArg, parsed.tier);
+    output({
+        phase: phaseArg,
+        proposal,
+        phase_record: record.tier !== null ? { tier: record.tier, proposed: record.proposed } : null,
+        recorded,
+        effective: { tier: after.tier, source: after.source, suppressed: after.suppressed },
+    }, raw);
+}
+function buildPhasePlanIndex(cwd, phase) {
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
     const normalized = normalizePhaseName(phase);
     let phaseDir = null;
@@ -419,8 +562,11 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         // phases dir doesn't exist
     }
     if (!phaseDir) {
-        output({ phase: normalized, error: 'Phase not found', plans: [], waves: {}, incomplete: [], has_checkpoints: false }, raw);
-        return;
+        return {
+            result: { phase: normalized, error: 'Phase not found', plans: [], waves: {}, incomplete: [], has_checkpoints: false },
+            phaseDir: null,
+            extras: new Map(),
+        };
     }
     void phaseDirName; // used only to set phaseDir above
     const phaseFiles = node_fs_1.default.readdirSync(phaseDir);
@@ -442,6 +588,13 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         const xmlTasks = content.match(/<task[\s>]/gi) || [];
         const mdTasks = content.match(/##\s*Task\s*\d+/gi) || [];
         const taskCount = xmlTasks.length || mdTasks.length;
+        const taskTypes = xmlTasks.length > 0
+            ? [...content.matchAll(/<task(\s[^>]*)?>/gi)].map((m) => /type=["']?([\w:-]+)/i.exec(m[1] ?? '')?.[1] ?? 'auto')
+            : mdTasks.map(() => 'auto');
+        const fmString = (key) => {
+            const value = fm[key];
+            return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+        };
         const parsedWave = parseInt(fm['wave'], 10);
         const declaredWave = Number.isNaN(parsedWave) ? null : parsedWave;
         let dependsOn = [];
@@ -464,6 +617,10 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
             filesModified = Array.isArray(fmFiles) ? fmFiles.map(String) : [String(fmFiles)];
         }
         const hasSummary = completedPlanIds.has(planId) || completedPlanIds.has(extractCanonicalPlanId(planFile));
+        const fmReqs = fm['requirements'];
+        const requirements = (Array.isArray(fmReqs) ? fmReqs.map(String) : typeof fmReqs === 'string' && fmReqs.trim() !== '' ? fmReqs.split(/[\s,]+/) : [])
+            .map((r) => r.trim())
+            .filter((r) => r !== '' && r !== '[]');
         rawPlans.push({
             id: planId,
             declaredWave,
@@ -473,6 +630,13 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
             filesModified,
             taskCount,
             hasSummary,
+            title: (0, plan_graph_cjs_1.readPlanTitle)(fm['title']),
+            serialGroup: fmString('serial_group'),
+            chainReason: fmString('chain_reason'),
+            taskTypes,
+            requirements,
+            // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
+            gapClosure: String(fm['gap_closure'] ?? '').trim() === 'true',
         });
     }
     // ── Pass 2: topological level assignment via depends_on DAG ──────────────
@@ -481,18 +645,31 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         const lower = p.id.toLowerCase();
         const existing = seenLower.get(lower);
         if (existing !== undefined) {
-            error(`depends_on index collision in phase ${normalized}: plan IDs '${existing}' and '${p.id}' are identical when case-folded. Rename one file to avoid ambiguous dependency resolution.`);
-            return;
+            return {
+                fatal: `depends_on index collision in phase ${normalized}: plan IDs '${existing}' and '${p.id}' are identical when case-folded. Rename one file to avoid ambiguous dependency resolution.`,
+            };
         }
         seenLower.set(lower, p.id);
     }
     const planMap = new Map(rawPlans.map((p) => [p.id.toLowerCase(), p]));
     const canonicalToId = new Map(rawPlans.map((p) => [extractCanonicalPlanId(p.id).toLowerCase(), p.id]));
-    const { level, visited } = computeDependencyLevels(rawPlans, planMap, canonicalToId);
-    if (visited < rawPlans.length) {
-        const cycleNodes = rawPlans.filter((p) => !level.has(p.id)).map((p) => p.id);
-        error(`depends_on cycle detected in phase ${normalized} — cycle involves: ${cycleNodes.join(', ')}`);
-        return;
+    // Wave + serial-group assignment and chain metrics: single owner is plan-graph.cts.
+    const resolveDep = (dep) => {
+        const lower = String(dep).toLowerCase();
+        return planMap.has(lower) ? planMap.get(lower).id : canonicalToId.get(lower);
+    };
+    const graph = (0, plan_graph_cjs_1.computePlanGraph)(rawPlans.map((p) => ({
+        id: p.id,
+        title: p.title,
+        dependsOn: p.dependsOn.map(resolveDep).filter((d) => d !== undefined),
+        filesModified: p.filesModified,
+        serialGroup: p.serialGroup,
+        chainReason: p.chainReason,
+        taskTypes: p.taskTypes,
+    })));
+    if (graph.cycle) {
+        const cycleNodes = graph.cycle;
+        return { fatal: `depends_on cycle detected in phase ${normalized} — cycle involves: ${cycleNodes.join(', ')}` };
     }
     // ── Pass 3: determine lowest bucket key and build output ─────────────────
     const anyWaveZero = rawPlans.some((p) => p.declaredWave === 0);
@@ -509,14 +686,16 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         if (!rawPlan.hasSummary) {
             incomplete.push(rawPlan.id);
         }
-        const computedWave = (level.get(rawPlan.id) ?? 0) + levelOffset;
+        const computedWave = (graph.level[rawPlan.id] ?? 0) + levelOffset;
         const effectiveWave = computedWave;
         if (rawPlan.declaredWave !== null && rawPlan.declaredWave !== computedWave) {
             warnings.push(`Plan ${rawPlan.id}: declared wave: ${rawPlan.declaredWave} but depends_on DAG places it in wave ${computedWave}`);
         }
         const plan = {
             id: rawPlan.id,
+            title: rawPlan.title,
             wave: effectiveWave,
+            serial_group: graph.serialGroupOf[rawPlan.id] ?? null,
             depends_on: rawPlan.dependsOn.map((dep) => {
                 const lower = String(dep).toLowerCase();
                 return planMap.has(lower) ? planMap.get(lower).id : dep;
@@ -538,14 +717,28 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         phase: normalized,
         plans,
         waves,
+        serial_groups: Object.fromEntries(graph.serialGroups.map((g) => [g.name, { wave: g.level + levelOffset, plans: g.plans, shared_files: g.shared_files }])),
+        graph: {
+            plan_count: graph.plan_count,
+            wave_count: graph.wave_count,
+            longest_chain: graph.longest_chain,
+            chain_check: graph.chain_check,
+            implicit_edges: graph.implicitEdges,
+            merge_candidates: graph.merge_candidates,
+        },
         incomplete,
         has_checkpoints: hasCheckpoints,
     };
+    warnings.push(...graph.warnings);
     if (planNamingWarning)
         result['warning'] = planNamingWarning;
     if (warnings.length > 0)
         result['warnings'] = warnings;
-    output(result, raw);
+    return {
+        result,
+        phaseDir,
+        extras: new Map(rawPlans.map((p) => [p.id, { requirements: p.requirements, gapClosure: p.gapClosure }])),
+    };
 }
 function cmdPhaseAdd(cwd, description, raw, customId) {
     if (!description) {
@@ -986,8 +1179,10 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     }
     updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, parseInt(normalized, 10), cwd);
     const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
+    // 261007-ixt D-3: name every frontmatter key the shared writer changed.
+    let stateFrontmatterUpdated = [];
     if (node_fs_1.default.existsSync(statePath)) {
-        readModifyWriteStateMd(statePath, (stateContent) => {
+        stateFrontmatterUpdated = readModifyWriteStateMd(statePath, (stateContent) => {
             const totalRaw = stateExtractField(stateContent, 'Total Phases');
             if (totalRaw) {
                 stateContent =
@@ -999,7 +1194,7 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
                 stateContent = stateContent.replace(/(\bof\s+)(\d+)(\s*(?:\(|phases?))/i, `$1${parseInt(ofMatch[2], 10) - 1}$3`);
             }
             return stateContent;
-        }, cwd);
+        }, cwd).frontmatter_updated;
     }
     output({
         removed: targetPhase,
@@ -1008,6 +1203,7 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
         renamed_files: renamedFiles,
         roadmap_updated: true,
         state_updated: node_fs_1.default.existsSync(statePath),
+        state_frontmatter_updated: stateFrontmatterUpdated,
     }, raw);
 }
 function writePlanningFileSet(writes) {
@@ -1064,7 +1260,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
     const today = clock_cjs_1.realClock.today();
-    const phaseInfoRaw = findPhaseInternal(cwd, phaseNum);
+    const phaseInfoRaw = resolvePhaseForRead(cwd, phaseNum);
     if (!phaseInfoRaw) {
         error(`Phase ${phaseNum} not found`);
     }
@@ -1113,6 +1309,8 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     let nextPhaseNum = null;
     let nextPhaseName = null;
     let isLastPhase = true;
+    // 261007-ixt D-3: every STATE.md frontmatter key this transaction changes.
+    let stateFrontmatterUpdated = [];
     withPlanningLock(cwd, () => {
         const runPhaseCompleteTransaction = () => {
             const writes = [];
@@ -1143,7 +1341,16 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     }
                     return '|' + cells.join('|') + '|';
                 });
-                const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`, 'i');
+                // D-08-33: the Plans summary line is resolved through the ONE builder in
+                // src/roadmap-parser.cjs. The inline pattern that stood here knew a
+                // single spelling (`**Plans:**`), had no phase-number boundary and
+                // scanned without a bound — so on a CANONICAL roadmap (`**Plans**:`,
+                // colon outside the bold) it walked out of this phase's section and
+                // wrote `N/N plans complete` into a LATER phase, asserting a build that
+                // had not happened (UAT F2, measured on the live fixture). Only the
+                // pattern moved: the replacement string, the unscoped `.replace` and
+                // this transaction's write set are unchanged (D-08-13/14).
+                const planCountPattern = buildPlansSummaryLinePattern(phaseNum);
                 roadmapContent = roadmapContent.replace(planCountPattern, `$1${summaryCount}/${planCount} plans complete`);
                 const phaseInfoSummaries = phaseInfo['summaries'];
                 for (const summaryFile of phaseInfoSummaries) {
@@ -1370,7 +1577,21 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     }
                 }
                 stateContent = updatePerformanceMetricsSection(stateContent, cwd, phaseNum, planCount, summaryCount);
-                stateContent = syncStateFrontmatter(stateContent, cwd);
+                // 261007-ixt D-1: completed_phases is capped by the ROADMAP progress table,
+                // and this transaction is flipping this phase's row to Complete in the same
+                // file set — so the writer counts from the roadmap being written, not the
+                // one still on disk.
+                // D-10: this transaction sets Last activity itself; that explicit date flows.
+                const activityFieldSet = (0, state_document_cjs_1.extractPositionalField)(stateContent, 'Last Activity', 'Last activity') !==
+                    (0, state_document_cjs_1.extractPositionalField)(originalStateContent, 'Last Activity', 'Last activity');
+                // 261007-rly D-11: phase complete opts OUT of the stopped_at hold and keeps
+                // re-deriving the key from the Session line, as it did before the hold moved
+                // into syncStateFrontmatter: bug #3517's pin (tests/phase.test.cjs) needs a
+                // newer Session line to replace a stale stored value here, the opposite of
+                // the operator-note shape the hold protects. Filed, not decided here:
+                // todos/pending/phase-complete-rederives-stopped-at-from-the-session-line.md.
+                stateContent = syncStateFrontmatter(stateContent, cwd, roadmapContent, activityFieldSet, true);
+                stateFrontmatterUpdated = (0, state_document_cjs_1.diffFrontmatterFields)(extractFrontmatter(originalStateContent), extractFrontmatter(stateContent));
                 writes.push({ filePath: statePath, before: originalStateContent, after: stateContent });
             }
             writePlanningFileSet(writes);
@@ -1410,6 +1631,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         date: today,
         roadmap_updated: node_fs_1.default.existsSync(roadmapPath),
         state_updated: node_fs_1.default.existsSync(statePath),
+        state_frontmatter_updated: stateFrontmatterUpdated,
         requirements_updated: requirementsUpdated,
         auto_pruned: autoPruned,
         warnings,
@@ -1421,7 +1643,7 @@ function cmdPhaseUatPassed(cwd, phaseNum, raw, opts = {}) {
     if (!phaseNum) {
         error('phase number required for phase uat-passed');
     }
-    const phaseInfoRaw = findPhaseInternal(cwd, phaseNum);
+    const phaseInfoRaw = resolvePhaseForRead(cwd, phaseNum);
     if (!phaseInfoRaw) {
         error(`Phase ${phaseNum} not found`);
     }
@@ -1435,6 +1657,10 @@ module.exports = {
     cmdPhaseNextDecimal,
     cmdFindPhase,
     cmdPhasePlanIndex,
+    cmdPhaseDispatchPlan,
+    cmdPhaseInstallRun,
+    cmdPhaseTier,
+    cmdPhaseTierPropose,
     cmdPhaseAdd,
     cmdPhaseAddBatch,
     cmdPhaseMvpMode,

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

@@ -35,6 +35,8 @@ function routePhasesCommand({ phase, milestone, args, cwd, raw, error }) {
                 phase.cmdPhasesList(cwd, options, raw);
             },
             clear: () => milestone.cmdPhasesClear(cwd, raw, args.slice(2)),
+            // 261007-mmz: the closed-milestone mover new-milestone.md --reset-phase-numbers calls.
+            'archive-closed': () => milestone.cmdPhasesArchiveClosed(cwd, raw, args.slice(2)),
         },
     });
 }