@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/phase-lifecycle.cjs

@@ -21,12 +21,19 @@
  *   - Issue #4 (open-gsd/gsd-core)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.locateProgressTable = locateProgressTable;
 exports.deriveProgressFromRoadmap = deriveProgressFromRoadmap;
+exports.clampPercentFromFraction = clampPercentFromFraction;
 exports.clampPercent = clampPercent;
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
+const phaseIdMod = require("./phase-id.cjs");
+const { isSentinelPhaseId } = phaseIdMod;
 /**
- * Derive completed_phases, total_phases, and total_plans from ROADMAP content.
- * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ * #3227: the single owner of "where is this ROADMAP's Progress table".
+ * Lifted verbatim out of deriveProgressFromRoadmap so `state-contract.cts`
+ * enumerates phases from THE SAME table this module derives its counts from.
+ * A second copy of this locator is the DEFECT.GENERATIVE-FIX shape.
  *
  * ADR-2143 §3 ("addressed by NAME, never ordinal"): the Progress table is
  * located via the markdown-table seam's `findTableWithColumns`, which is
@@ -45,6 +52,24 @@ const markdown_table_cjs_1 = require("./markdown-table.cjs");
  * to scanning the whole input, preserving the "Progress table not under a
  * `## Progress` heading, or not the first table in the document, still
  * resolves" behaviour.
+ */
+function locateProgressTable(roadmapContent) {
+    const progressMatch = roadmapContent.match(/^##[ \t]+Progress\b/im);
+    let scoped = roadmapContent;
+    if (progressMatch && progressMatch.index !== undefined) {
+        const afterHeading = roadmapContent.slice(progressMatch.index);
+        const nextHeading = afterHeading.search(/\n#{1,2}[ \t]/);
+        scoped = nextHeading >= 0 ? afterHeading.slice(0, nextHeading) : afterHeading;
+    }
+    return (0, markdown_table_cjs_1.findTableWithColumns)(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
+}
+/**
+ * Derive completed_phases, total_phases, and total_plans from ROADMAP content.
+ * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ *
+ * The Progress table itself is located by `locateProgressTable` (ADR-2143 §3,
+ * lifted out as #3227's single-owner extraction) — this function consumes
+ * that table.
  *
  * Cells are read by column NAME (`r['Status']`, `r['Plans Complete']`,
  * `r['Phase']`), fixing #2137 (the old position-based regex assumed "Status"
@@ -63,28 +88,16 @@ function deriveProgressFromRoadmap(roadmapContent) {
     // `{ ok: false, reason }`, not an exception — so the catch was masking
     // nothing but dead code paths. Removed per ADR-2143 §5; the public
     // `RoadmapProgress` contract (nulls = absent) is unchanged.
-    //
-    // ADR-2143 §3: read the Progress table by column NAME (order/injection-invariant),
-    // via the markdown-table seam. Scope to the `## Progress` section when present
-    // (#2012 decoy avoidance); a headingless milestone slice (#1445) falls back to the
-    // whole input. Requires the canonical Phase/Plans Complete/Status/Completed columns
-    // in any order (extra columns ignored) — supersedes findTableBySchema's exact-schema lookup.
-    const progressMatch = roadmapContent.match(/^##[ \t]+Progress\b/im);
-    let scoped = roadmapContent;
-    if (progressMatch && progressMatch.index !== undefined) {
-        const afterHeading = roadmapContent.slice(progressMatch.index);
-        const nextHeading = afterHeading.search(/\n#{1,2}[ \t]/);
-        scoped = nextHeading >= 0 ? afterHeading.slice(0, nextHeading) : afterHeading;
-    }
-    const table = (0, markdown_table_cjs_1.findTableWithColumns)(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
+    const table = locateProgressTable(roadmapContent);
     if (table) {
         const allRows = table.rows;
         const completed = allRows.filter((r) => /^complete$/i.test((r['Status'] ?? '').trim())).length;
         completedPhases = completed > 0 ? completed : null;
-        // Data rows only (exclude 999.x backlog phases). Mirrors init.cts /^999(?:\.|$)/ filter.
+        // Data rows only (exclude sentinel phases 0 and 999.x).
+        // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
         const dataRows = allRows.filter((r) => {
             const phase = (r['Phase'] ?? '').trim();
-            return /^\d/.test(phase) && !/^999\b/.test(phase);
+            return /^\d/.test(phase) && !isSentinelPhaseId(phase);
         });
         totalPhases = dataRows.length > 0 ? dataRows.length : null;
         let totalPlansSum = 0;
@@ -98,12 +111,32 @@ function deriveProgressFromRoadmap(roadmapContent) {
     }
     return { completedPhases, totalPhases, totalPlans };
 }
+/**
+ * Compute progress percent clamped to 100 from an already-computed FRACTION.
+ *
+ * ADR-3180 Decision 7 (#3180): the completion-RATIO derivation has exactly one
+ * owner, and this is its kernel — the single place the `fraction -> integer
+ * percent` rounding and the 100 ceiling are expressed. `clampPercent` below is
+ * the count-shaped entry point and delegates here; a caller that already holds a
+ * fraction (rather than a completed/total pair) calls this directly instead of
+ * re-deriving `Math.min(100, Math.round(f * 100))` locally.
+ *
+ * Enforced by `scripts/lint-completion-ratio-drift.cjs`.
+ */
+function clampPercentFromFraction(fraction) {
+    return Math.min(100, Math.round(fraction * 100));
+}
 /**
  * Compute progress percent clamped to 100.
  * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ *
+ * A non-positive (or absent) denominator yields `0` — "nothing to complete" is
+ * reported as 0%, never as 100%. Every `.planning/` completion percentage in this
+ * codebase routes through here (ADR-3180 Decision 7); the `total > 0 ? ... : 0`
+ * ternary that used to precede each inline copy IS this function's first line.
  */
 function clampPercent(completed, total) {
     if (!total || total <= 0)
         return 0;
-    return Math.min(100, Math.round((completed / total) * 100));
+    return clampPercentFromFraction(completed / total);
 }

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

@@ -12,7 +12,7 @@
  *
  * Dependencies (leaf modules only — no loadConfig):
  *   - node:fs / node:path (stdlib)
- *   - ./phase-id.cjs       (normalizePhaseName, phaseTokenMatches, extractPhaseToken)
+ *   - ./phase-id.cjs       (normalizePhaseName, matchPhaseDirs, phaseNumberForMatch)
  *   - ./core-utils.cjs     (readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath)
  *   - ./planning-workspace.cjs (planningDir)
  */
@@ -23,19 +23,25 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdModule = require("./phase-id.cjs");
-const { normalizePhaseName, phaseTokenMatches, extractPhaseToken } = phaseIdModule;
+const { normalizePhaseName, matchPhaseDirs, phaseNumberForMatch, isSentinelPhaseId, comparePhaseNum } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtilsModule = require("./core-utils.cjs");
-const { readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath } = coreUtilsModule;
+const { readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath, findUnsummarizedPlans } = coreUtilsModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningDir } = planningWorkspace;
+const { planningDir, planningRoot } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatterModule = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatterModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planDependencyGraphModule = require("./plan-dependency-graph.cjs");
 const { computeHaltPropagation, buildSummaryFileIndex, isSummaryFileHalted } = planDependencyGraphModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParserModule = require("./roadmap-parser.cjs");
+const { getMilestonePhaseFilter } = roadmapParserModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 /**
  * #2830: parse a plan file's `depends_on` frontmatter. Returns [] — never
  * throws — on a missing/unreadable/malformed plan or absent field, matching
@@ -68,33 +74,85 @@ function parsePlanDependsOn(phaseDir, planFile) {
  * exactly the shape that let the original #2855 bug (hardcoded root path)
  * exist in one copy and not the other. Sharing this seam means a future
  * change to how the archive tree is located only needs to happen once.
- * Most-recent-milestone-first order (reverse-sorted directory names).
+ * Most-recent-milestone-first order, compared numerically segment-by-segment
+ * on the version (e.g. `v1.10` before `v1.9`) — NOT lexicographically. A
+ * lexicographic `.sort().reverse()` (the prior implementation) ranks `v1.9`
+ * ahead of `v1.10` because the string `"1.9"` sorts after `"1.10"`; that is
+ * deterministic but wrong for every double-digit-or-higher minor/patch
+ * version, and #3458 is what first surfaces archived phases in audit output
+ * where the misordering becomes user-visible.
  * Never throws: an absent/unreadable milestones/ dir yields [].
  */
-function listArchiveVersionDirs(cwd) {
-    const milestonesDir = node_path_1.default.join(planningDir(cwd), 'milestones');
-    if (!node_fs_1.default.existsSync(milestonesDir))
-        return [];
+function compareArchiveVersionDesc(aName, bName) {
+    const aParts = (aName.match(/^v([\d.]+)-phases$/)?.[1] ?? '').split('.').map(Number);
+    const bParts = (bName.match(/^v([\d.]+)-phases$/)?.[1] ?? '').split('.').map(Number);
+    const len = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < len; i++) {
+        const a = aParts[i] ?? 0;
+        const b = bParts[i] ?? 0;
+        if (a !== b)
+            return b - a; // descending: newest (numerically largest) first
+    }
+    return 0;
+}
+function listArchiveVersionDirs(cwd, wsOverride) {
+    // #3804: enumerate BOTH archive shapes under the CURRENT SCOPE's milestones
+    // tree (planningDir — GSD_WORKSTREAM/GSD_PROJECT-aware, exactly the
+    // #2855 scoping findPhaseInternal and getArchivedPhaseDirs rely on):
+    //   flat:               <scope>/milestones/vX.Y-phases/<phase-dir>/
+    //   workstream archive: <scope>/milestones/ws-<slug>-<date>/phases/<phase-dir>/
+    // Pre-#3804 only the flat shape matched, so workstream-archived milestones
+    // were invisible (the reporter's repo: 20 hidden phase artifacts). The
+    // ws-* shape's phase dirs sit one level deeper (under phases/) and its dir
+    // name fails ^v[\d.]+-phases$ — both the name AND the level are modeled.
+    // Version labels: flat keeps the bare vX.Y; ws-* shapes carry the dir name
+    // (no numeric version). Flat-newest-first (compareArchiveVersionDesc), then
+    // ws dirs by name descending — deterministic. The AUDIT's cross-workstream
+    // enumeration (audit.cts listAuditPhaseTargets) calls this helper once per
+    // tree (root + each workstream) rather than widening this scope — the
+    // #2855 no-leak contract for findPhaseInternal/getArchivedPhaseDirs is
+    // preserved untouched.
+    const milestonesDir = node_path_1.default.join(planningDir(cwd, wsOverride ?? undefined), 'milestones');
+    const out = [];
+    const seen = new Set();
+    const pushVersion = (version, archivePath) => {
+        const rel = toPosixPath(node_path_1.default.relative(cwd, archivePath));
+        if (seen.has(rel))
+            return;
+        seen.add(rel);
+        out.push({ version, archivePath });
+    };
+    let entries;
     try {
-        const milestoneEntries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
-        return milestoneEntries
-            .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
-            .map(e => e.name)
-            .sort()
-            .reverse()
-            .map(archiveName => ({
-            version: archiveName.match(/^(v[\d.]+)-phases$/)[1],
-            archivePath: node_path_1.default.join(milestonesDir, archiveName),
-        }));
+        entries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
     }
     catch {
         return [];
     }
+    const flat = entries
+        .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
+        .map(e => e.name)
+        .sort(compareArchiveVersionDesc);
+    for (const archiveName of flat) {
+        pushVersion(archiveName.match(/^(v[\d.]+)-phases$/)[1], node_path_1.default.join(milestonesDir, archiveName));
+    }
+    const wsDirs = entries
+        .filter(e => e.isDirectory() && /^ws-/.test(e.name))
+        .map(e => e.name)
+        .sort()
+        .reverse();
+    for (const wsName of wsDirs) {
+        pushVersion(wsName, node_path_1.default.join(milestonesDir, wsName, 'phases'));
+    }
+    return out;
 }
 function searchPhaseInDir(baseDir, relBase, normalized) {
     try {
         const dirs = readSubdirectories(baseDir, true);
-        const matches = dirs.filter(d => phaseTokenMatches(d, normalized));
+        // #2528: canonical two-pass selection (exact token match, then the
+        // bare-integer leading-digit-run fallback) shared with the find-phase and
+        // phase-plan-index scans — see phase-id.cts::matchPhaseDirs.
+        const { matches, usedBareFallback } = matchPhaseDirs(dirs, normalized);
         if (matches.length === 0)
             return null;
         // #2237: fail loud when multiple directories match the same bare phase
@@ -121,7 +179,7 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
             };
         }
         const match = matches[0];
-        const phaseToken = extractPhaseToken(match);
+        const phaseToken = phaseNumberForMatch(match, usedBareFallback);
         const phaseNumber = phaseToken || normalized;
         const afterToken = match.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
         const phaseName = afterToken || null;
@@ -129,16 +187,13 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
         const { plans: unsortedPlans, summaries: unsortedSummaries, hasResearch, hasContext, hasVerification, hasReviews } = getPhaseFileStats(phaseDir);
         const plans = unsortedPlans.sort();
         const summaries = unsortedSummaries.sort();
-        const completedPlanIds = new Set(summaries.flatMap(s => {
-            const exact = s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
-            const canonical = extractCanonicalPlanId(s);
-            return canonical === exact ? [exact] : [exact, canonical];
-        }));
-        const incompletePlans = plans.filter(p => {
-            const planId = p.replace('-PLAN.md', '').replace('PLAN.md', '');
-            const canonical = extractCanonicalPlanId(p);
-            return !completedPlanIds.has(planId) && !completedPlanIds.has(canonical);
-        });
+        // #3183 (ADR-3180 Decision 2): the summary→plan pairing used to be a
+        // bespoke rule local to this function (a third pairing rule alongside
+        // scanPhasePlans's completion check and countMatchedSummaries). Routed
+        // through the canonical core-utils.findUnsummarizedPlans instead, which
+        // shares its `summaryCandidates` matching rule with countMatchedSummaries
+        // so the count and this named list can never disagree.
+        const incompletePlans = findUnsummarizedPlans(plans, summaries);
         // #2830: reverse lookup from a completed plan's id (exact or canonical) to
         // its actual summary filename. Shared builder (also used by phase.cts's
         // cmdPhasePlanIndex) so the two can never disagree about which summary
@@ -188,7 +243,12 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
             directory: toPosixPath(node_path_1.default.join(relBase, match)),
             phase_number: phaseNumber,
             phase_name: phaseName,
-            phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null,
+            // #3883 (ADR-3473 §8.3): delegate to the canonical slug formula
+            // (generateSlugInternal, core-utils.cts) rather than re-implementing
+            // it. `maxLen: null` preserves this site's pre-migration untruncated
+            // contract — the 60-char default would drop an on-disk phase slug's
+            // reported value out of sync with the real directory name.
+            phase_slug: phaseName ? coreUtilsModule.generateSlugInternal(phaseName, null) : null,
             plans,
             summaries,
             incomplete_plans: incompletePlans,
@@ -233,13 +293,139 @@ function findPhaseInternal(cwd, phase) {
     }
     return null;
 }
-function getArchivedPhaseDirs(cwd) {
+/**
+ * #3185 (epic #3180 Phase 3, ADR-3180 Decision 1 row "Phase enumeration"):
+ * the SINGLE canonical owner of "which phase directories belong to the current
+ * milestone". Applies the milestone window AND the sentinel filter, in that
+ * order, and returns the surviving directory names.
+ *
+ * Before this existed the derivation had four independent implementations and
+ * only `cmdRoadmapAnalyze` carried both halves; `cmdProgressRender`,
+ * `cmdStats` and `cmdPhasesList` each carried neither or one.
+ *
+ * TWO THINGS THIS GETS RIGHT THAT A HEADING-SIDE FILTER CANNOT:
+ *
+ * 1. The sentinel test runs against DIRECTORY NAMES and is UNCONDITIONAL.
+ *    `getMilestonePhaseFilter` excludes sentinels from its ROADMAP HEADING
+ *    set, but when that set is empty it degrades to a literal `() => true`
+ *    pass-all predicate and never consults the heading set at all — so its
+ *    own sentinel exclusion becomes unreachable exactly when it is needed,
+ *    and every directory on disk (backlog included) is reported as a
+ *    current-milestone phase. That degrade is the #3167 symptom path.
+ *
+ * 2. The sentinel predicate is the canonical `isSentinelPhaseId`
+ *    (`src/phase-id.cts`, SENTINEL_RANGES [0, 999]), not a local literal.
+ *    The rule had five copies and three different regexes before this phase,
+ *    and they disagreed about Phase 0.
+ *
+ * The pass-all degrade is narrowed MINIMALLY: it stays over-inclusive for
+ * non-sentinel directories, so a project whose window declares no phases
+ * still sees its real phase directories. Only sentinels are refused.
+ *
+ * `scope` distinguishes a REAL empty from a NON-answer (ADR-3180 Decision 2):
+ * an absent `phasesDir` is a real empty (a new project genuinely has no
+ * phases) and inherits the window's scope, whereas a `phasesDir` that exists
+ * but cannot be read is UNREADABLE.
+ *
+ * `opts.ws` is tri-state, matching `planningDir`'s own contract: `undefined`
+ * (the default — do not pass `ws` at all) resolves the AMBIENT workstream
+ * from `GSD_WORKSTREAM`; `null` FORCES the project root regardless of any
+ * ambient workstream; a string forces that specific workstream.
+ */
+function listMilestonePhaseDirs(phasesDir, opts = {}) {
+    // #3597: `ws` must default to `undefined`, NOT `null`. `undefined` means
+    // "resolve the ambient workstream" (mirrors planningDir's own contract,
+    // src/planning-workspace.cts:124); `null` means "force the project root".
+    // Every cwd-bearing caller derives `phasesDir` ambiently (planningPaths(cwd)
+    // / planningDir(cwd) with no explicit ws), so defaulting `ws` to `null` here
+    // forced the milestone WINDOW to the root ROADMAP while the caller's
+    // `phasesDir` stayed workstream-scoped — numerator and denominator drawn
+    // from different scoped sets (ADR-3180 §7.6 rule 3 violation). That is what
+    // made `--ws <name> progress` read `phase_scope: "unreadable"` and withhold
+    // `percent` once `workstream create` migrated the root ROADMAP away.
+    const { cwd, ws, versionOverride = null, phaseIdConvention = null } = opts;
+    // Without a cwd there is nothing to scope AGAINST — the caller asked for an
+    // unscoped read, which is a real answer (mirrors extractCurrentMilestoneScoped's
+    // row 1). Sentinels are still refused: they are never milestone phases.
+    let inWindow = () => true;
+    let scope = SCOPE.COMPLETE;
+    if (cwd) {
+        const filter = getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws);
+        inWindow = filter;
+        scope = filter.scope;
+    }
+    // An ABSENT phases dir is a real empty, not a failure: a freshly-created
+    // project genuinely has no phase directories yet. Distinguishing this from
+    // the unreadable case below is the whole point of the scope discriminator.
+    if (!node_fs_1.default.existsSync(phasesDir))
+        return { value: [], scope };
+    let names;
+    try {
+        names = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        // The directory EXISTS but could not be read (EACCES/EIO). An empty list
+        // here is a NON-answer and must not be reported as "this milestone has no
+        // phases" — that collapse is the defect class this epic removes.
+        return { value: [], scope: SCOPE.UNREADABLE };
+    }
+    const value = names
+        .filter((name) => inWindow(name) && !isSentinelPhaseId(name, phaseIdConvention ?? undefined))
+        .sort((a, b) => comparePhaseNum(a, b));
+    return { value, scope };
+}
+/**
+ * #3882 (ADR-3473 §8.2, issue #3882): the single owner of "the PHYSICAL set
+ * of phase directories on disk, entirely un-windowed" — the OTHER axis
+ * `listMilestonePhaseDirs` above deliberately does not offer. That owner
+ * refuses sentinels UNCONDITIONALLY (see its own doc comment); it has no way
+ * to say "physical set, sentinels included". That is exactly what an
+ * archival, lookup-index, or health-sweep caller needs — e.g. a heading ->
+ * directory lookup index that must resolve a directory regardless of
+ * milestone window (`cmdRoadmapAnalyze`'s `_phaseDirNames`,
+ * `cmdInitMilestoneOp`'s `diskPhaseDirs`) — which is why those callers used
+ * to hand-roll a `readdirSync` instead of calling either owner.
+ *
+ * `includeSentinels` is REQUIRED, with no default value. #3882/ADR-3473 §8.2:
+ * "a caller that wants sentinels asks for them explicitly" — obtaining
+ * sentinel-inclusion by silent omission is exactly the defect class this
+ * axis exists to close, so the call site is refused at COMPILE TIME without
+ * it, not merely documented against it here.
+ *
+ * Mirrors `listMilestonePhaseDirs`'s own absent/unreadable handling
+ * (ADR-3180 Decision 2): an ABSENT `phasesDir` is a real empty (a project
+ * with no phase directories yet), `scope: SCOPE.COMPLETE`; a `phasesDir`
+ * that EXISTS but cannot be read is a NON-answer, `scope: SCOPE.UNREADABLE`
+ * — a caller must not treat that empty list as "this project has no
+ * phases."
+ */
+function listAllPhaseDirs(phasesDir, opts) {
+    const { includeSentinels, phaseIdConvention = null } = opts;
+    if (!node_fs_1.default.existsSync(phasesDir))
+        return { value: [], scope: SCOPE.COMPLETE };
+    let names;
+    try {
+        names = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return { value: [], scope: SCOPE.UNREADABLE };
+    }
+    const value = names
+        .filter((name) => includeSentinels || !isSentinelPhaseId(name, phaseIdConvention ?? undefined))
+        .sort((a, b) => comparePhaseNum(a, b));
+    return { value, scope: SCOPE.COMPLETE };
+}
+function getArchivedPhaseDirs(cwd, wsOverride) {
     // #2855: same workstream-scoped resolution as findPhaseInternal above, via
     // the shared listArchiveVersionDirs helper. `phase.list --include-archived`
     // (the primary non-init consumer) must not leak a different workstream's
     // archive either.
     const results = [];
-    for (const { version, archivePath } of listArchiveVersionDirs(cwd)) {
+    for (const { version, archivePath } of listArchiveVersionDirs(cwd, wsOverride)) {
         const dirs = readSubdirectories(archivePath, true);
         for (const dir of dirs) {
             results.push({
@@ -252,8 +438,50 @@ function getArchivedPhaseDirs(cwd) {
     }
     return results;
 }
+/**
+ * #3804 — the CROSS-WORKSTREAM archive enumeration the audit surfaces need.
+ * getArchivedPhaseDirs above is deliberately #2855-SCOPED (an ambient
+ * workstream must not leak other trees' phases to findPhaseInternal), but
+ * audit-uat's charter (#2766: outstanding items do not stop mattering) is
+ * cross-workstream: enumerate the project root plus every workstream's own
+ * milestones tree, labeling workstream entries '<ws>/<version>' so
+ * acknowledge-by-label stays unambiguous. Deduped by full path (the same
+ * tree cannot be reached twice, but the guard keeps the invariant explicit).
+ */
+function getAllArchivedPhaseDirs(cwd) {
+    const out = [];
+    const seen = new Set();
+    const collect = (labelPrefix, wsOverride) => {
+        for (const archived of getArchivedPhaseDirs(cwd, wsOverride)) {
+            const rel = toPosixPath(node_path_1.default.relative(cwd, archived.fullPath));
+            if (seen.has(rel))
+                continue;
+            seen.add(rel);
+            out.push({ ...archived, milestone: `${labelPrefix}${archived.milestone}` });
+        }
+    };
+    collect('', null);
+    const workstreamsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams');
+    try {
+        const wsEntries = node_fs_1.default.readdirSync(workstreamsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort()
+            .reverse();
+        for (const ws of wsEntries) {
+            collect(`${ws}/`, ws);
+        }
+    }
+    catch {
+        /* no workstreams dir — the root pass above already ran */
+    }
+    return out;
+}
 module.exports = {
     searchPhaseInDir,
     findPhaseInternal,
     getArchivedPhaseDirs,
+    getAllArchivedPhaseDirs,
+    listMilestonePhaseDirs,
+    listAllPhaseDirs,
 };