@opengsd/gsd-core 1.9.1 → 1.11.0

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

@@ -22,8 +22,12 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 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.
@@ -81,10 +85,11 @@ function deriveProgressFromRoadmap(roadmapContent) {
         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 +103,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,18 +23,104 @@ 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;
+// 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
+ * this primitive's existing fail-safe posture (a plan directory this
+ * primitive can otherwise read must never throw here).
+ */
+function parsePlanDependsOn(phaseDir, planFile) {
+    try {
+        const planPath = node_path_1.default.join(phaseDir, planFile);
+        const content = node_fs_1.default.readFileSync(planPath, 'utf-8');
+        const fm = extractFrontmatter(content, planPath);
+        const fmDeps = fm['depends_on'];
+        if (Array.isArray(fmDeps))
+            return fmDeps.map(String);
+        if (typeof fmDeps === 'string' && fmDeps.trim() !== '')
+            return [fmDeps];
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
 // ─── Phase search helpers ─────────────────────────────────────────────────────
+/**
+ * #2855: single source of truth for resolving and enumerating a project's
+ * (or, when a workstream is active, that workstream's OWN) archived-milestone
+ * directories — `<planningDir(cwd)>/milestones/vX.Y-phases/`. Both
+ * `findPhaseInternal`'s archive fallback and `getArchivedPhaseDirs` used to
+ * carry independent copies of this resolve-then-enumerate logic, which is
+ * 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, 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 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) {
+    const milestonesDir = node_path_1.default.join(planningDir(cwd), 'milestones');
+    if (!node_fs_1.default.existsSync(milestonesDir))
+        return [];
+    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(compareArchiveVersionDesc)
+            .map(archiveName => ({
+            version: archiveName.match(/^(v[\d.]+)-phases$/)[1],
+            archivePath: node_path_1.default.join(milestonesDir, archiveName),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
 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
@@ -55,10 +141,13 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
                 has_verification: false,
                 has_reviews: false,
                 ambiguous_matches: matches,
+                halted_plans: [],
+                blocked_by: {},
+                runnable_plans: [],
             };
         }
         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;
@@ -66,16 +155,57 @@ 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', '');
+        // #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
+        // belongs to which plan.
+        const summaryFileByPlanId = buildSummaryFileIndex(summaries, extractCanonicalPlanId);
+        // #2830: this primitive previously never parsed depends_on at all — see
+        // src/plan-dependency-graph.cts's file header. Build the same
+        // PlanHaltNode[] shape phase.cts's cmdPhasePlanIndex builds (id resolution
+        // mirrors its planMap/canonicalToId pattern) and hand it to the ONE
+        // shared halt-propagation traversal so this reader and the wave-grouping
+        // reader can never diverge on the halt rule again.
+        const planIds = plans.map(p => p.replace('-PLAN.md', '').replace('PLAN.md', ''));
+        const planIdByLower = new Map(planIds.map(id => [id.toLowerCase(), id]));
+        const canonicalToPlanId = new Map(plans.map((p, i) => [extractCanonicalPlanId(p).toLowerCase(), planIds[i]]));
+        const haltNodes = plans.map((p, i) => {
+            const planId = planIds[i];
             const canonical = extractCanonicalPlanId(p);
-            return !completedPlanIds.has(planId) && !completedPlanIds.has(canonical);
+            const summaryFile = summaryFileByPlanId.get(planId) ?? summaryFileByPlanId.get(canonical);
+            const halted = summaryFile !== undefined && isSummaryFileHalted(node_path_1.default.join(phaseDir, summaryFile));
+            const resolvedDependsOn = parsePlanDependsOn(phaseDir, p)
+                .map((dep) => {
+                const lower = dep.toLowerCase();
+                return planIdByLower.get(lower) ?? canonicalToPlanId.get(lower) ?? null;
+            })
+                .filter((id) => id !== null);
+            return { id: planId, resolvedDependsOn, halted };
         });
+        const { blockedBy } = computeHaltPropagation(haltNodes);
+        const haltedPlans = plans.filter((_, i) => haltNodes[i].halted);
+        const incompletePlanSet = new Set(incompletePlans);
+        const blockedByFiles = {};
+        const runnablePlans = [];
+        for (let i = 0; i < plans.length; i++) {
+            const p = plans[i];
+            if (!incompletePlanSet.has(p))
+                continue;
+            const causes = blockedBy.get(planIds[i]) ?? [];
+            if (causes.length > 0) {
+                blockedByFiles[p] = causes;
+            }
+            else {
+                runnablePlans.push(p);
+            }
+        }
         return {
             found: true,
             directory: toPosixPath(node_path_1.default.join(relBase, match)),
@@ -89,6 +219,9 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
             has_context: hasContext,
             has_verification: hasVerification,
             has_reviews: hasReviews,
+            halted_plans: haltedPlans,
+            blocked_by: blockedByFiles,
+            runnable_plans: runnablePlans,
         };
     }
     catch {
@@ -104,63 +237,130 @@ function findPhaseInternal(cwd, phase) {
     const current = searchPhaseInDir(phasesDir, relPhasesDir, normalized);
     if (current)
         return current;
-    const milestonesDir = node_path_1.default.join(cwd, '.planning', 'milestones');
-    if (!node_fs_1.default.existsSync(milestonesDir))
-        return null;
-    try {
-        const milestoneEntries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
-        const archiveDirs = milestoneEntries
-            .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
-            .map(e => e.name)
-            .sort()
-            .reverse();
-        for (const archiveName of archiveDirs) {
-            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 result = searchPhaseInDir(archivePath, relBase, normalized);
-            if (result) {
-                result.archived = version;
-                return result;
-            }
+    // #2855: scope the archived-milestone fallback to the SAME workstream as the
+    // active-phase search above (planningDir(cwd) resolves GSD_WORKSTREAM/GSD_PROJECT
+    // the identical way both places), not the hardcoded project-root tree. Archived
+    // phases genuinely live under a workstream's own `.planning/workstreams/<ws>/
+    // milestones/` — that is where archivePhaseDirectories (milestone.cts) writes
+    // them via the same planningDir(cwd) resolution. Hardcoding root here let a
+    // pending workstream phase resolve to an unrelated workstream's (or a flat-mode
+    // project's) archived phase that merely shares a phase number. Shared with
+    // getArchivedPhaseDirs via listArchiveVersionDirs (see its doc comment).
+    for (const { version, archivePath } of listArchiveVersionDirs(cwd)) {
+        const relBase = toPosixPath(node_path_1.default.relative(cwd, archivePath));
+        const result = searchPhaseInDir(archivePath, relBase, normalized);
+        if (result) {
+            result.archived = version;
+            return result;
         }
     }
-    catch { /* intentionally empty */ }
     return null;
 }
+/**
+ * #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 };
+}
 function getArchivedPhaseDirs(cwd) {
-    const milestonesDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    // #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 = [];
-    if (!node_fs_1.default.existsSync(milestonesDir))
-        return results;
-    try {
-        const milestoneEntries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
-        const phaseDirs = milestoneEntries
-            .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
-            .map(e => e.name)
-            .sort()
-            .reverse();
-        for (const archiveName of phaseDirs) {
-            const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
-            const version = versionMatch[1];
-            const archivePath = node_path_1.default.join(milestonesDir, archiveName);
-            const dirs = readSubdirectories(archivePath, true);
-            for (const dir of dirs) {
-                results.push({
-                    name: dir,
-                    milestone: version,
-                    basePath: node_path_1.default.join('.planning', 'milestones', archiveName),
-                    fullPath: node_path_1.default.join(archivePath, dir),
-                });
-            }
+    for (const { version, archivePath } of listArchiveVersionDirs(cwd)) {
+        const dirs = readSubdirectories(archivePath, true);
+        for (const dir of dirs) {
+            results.push({
+                name: dir,
+                milestone: version,
+                basePath: toPosixPath(node_path_1.default.relative(cwd, archivePath)),
+                fullPath: node_path_1.default.join(archivePath, dir),
+            });
         }
     }
-    catch { /* intentionally empty */ }
     return results;
 }
 module.exports = {
     searchPhaseInDir,
     findPhaseInternal,
     getArchivedPhaseDirs,
+    listMilestonePhaseDirs,
 };