@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/workstream-inventory-builder.cjs

@@ -12,13 +12,62 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickRollupWinners = pickRollupWinners;
 exports.isCompletedInventory = isCompletedInventory;
 exports.buildWorkstreamInventory = buildWorkstreamInventory;
 const node_path_1 = __importDefault(require("node:path"));
+const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
 // Internal helpers
 function toPosixPath(p) {
     return p.split('\\').join('/');
 }
+// #2562/#2645's FAILING_VERIFICATION_STATUSES set (the verdicts that used to
+// disqualify a phase from `complete` when combined with a local
+// summary-count-meets-plan-count check) was removed by ADR-3180 §7.4
+// (#3186): `complete` is now the single canonical owner's verdict
+// (`PhaseFilesCount.complete`, computed via `isPhaseComplete` by the
+// I/O-capable caller — see the loop below), which already requires
+// `verification.status === 'passed'` unconditionally. Disk-strict (#2957)
+// deliberately DROPS the prior "verifier-disabled projects fall back to
+// summaries-met" tolerance that set existed to preserve — a phase with no
+// `*-VERIFICATION.md` (`missing`) is no longer treated as complete just
+// because its summaries meet its plan count. Disclosed in this phase's
+// changeset.
+/**
+ * #2562 / Bug #2445 / #2645 review: pick ONE winning item per key from a
+ * PRE-SORTED list — newest `mtimeMs` wins; on an exact tie the incumbent
+ * (first-in-sort-order) wins, since only a STRICTLY greater mtime replaces
+ * it. `includeItem` lets a caller exclude items before comparison (e.g.
+ * out-of-milestone directories) — critically, the filter runs BEFORE the
+ * mtime comparison, so an excluded item can never win a tie or a comparison
+ * against an included one.
+ *
+ * Extracted as the SINGLE shared implementation after a #2645 review found
+ * two independently-written copies of this exact rule had silently
+ * diverged: `workstream-inventory.cts`'s ledger-winner selection compared
+ * raw mtimes with no scoping filter, while this module's own `rollupDirByKey`
+ * (below) filtered out-of-milestone directories first. A stale out-of-
+ * milestone directory with a newer mtime than the live in-milestone one
+ * (plausible after a checkout/rebase resets mtimes) could then win the
+ * LEDGER's selection while losing the BUILDER's — reopening #2645's own
+ * hole for the phase that actually counts toward `completed_phases`,
+ * reachable with a plain `rm` and no ledger tampering. A comment asserting
+ * two hand-written copies "use the same rule" is not a guarantee they do;
+ * one shared function is.
+ */
+function pickRollupWinners(sortedItems, keyOf, mtimeOf, includeItem = () => true) {
+    const winners = new Map();
+    for (const item of sortedItems) {
+        if (!includeItem(item))
+            continue;
+        const key = keyOf(item);
+        const incumbent = winners.get(key);
+        if (incumbent === undefined || mtimeOf(item) > mtimeOf(incumbent)) {
+            winners.set(key, item);
+        }
+    }
+    return winners;
+}
 function isCompletedInventory(status) {
     const s = (typeof status === 'string'
         ? status
@@ -28,42 +77,153 @@ function isCompletedInventory(status) {
     return /\bmilestone\s+complete\b/.test(s) || /\barchived\b/.test(s);
 }
 function buildWorkstreamInventory(inputs) {
-    const { name, projectDir, workstreamDir, phaseDirNames, activeWorkstreamName, phaseFilesCounts, roadmapPhaseCount, stateProjection, filesExist, milestoneShipped, } = inputs;
+    const { name, projectDir, workstreamDir, phaseDirNames, activeWorkstreamName, phaseFilesCounts, roadmapPhaseCount, stateProjection, filesExist, milestoneShipped, milestoneShippedSignal, currentMilestonePhaseCount = 0, milestoneScoped, } = inputs;
+    // A caller that passes only the legacy boolean states THAT a signal fired but
+    // not which one. Treat it as `legacy` — the ungated strength — so pre-review
+    // callers keep their exact behavior rather than silently acquiring a new gate.
+    const shippedSignal = milestoneShippedSignal !== undefined ? milestoneShippedSignal : (milestoneShipped ? 'legacy' : null);
+    const milestoneShippedResolved = shippedSignal !== null;
+    // #2562: when scoping is active, prior-milestone phase directories are
+    // excluded from the completion rollup and the denominator. The caller states
+    // this; the count-derived default is the pre-#2562 fallback for callers that
+    // do not, and cannot represent a scoped-but-empty current milestone.
+    const scoped = milestoneScoped ?? currentMilestonePhaseCount > 0;
     // Index counts by directory for O(1) lookup during sort/iteration
     const countsMap = new Map();
     for (const entry of phaseFilesCounts) {
-        countsMap.set(entry.directory, { planCount: entry.planCount, summaryCount: entry.summaryCount });
+        countsMap.set(entry.directory, entry);
     }
+    // #2562 / Bug #2445: pick ONE directory per phase key for the rollup. Stale
+    // same-numbered directories left over from a prior milestone would otherwise
+    // each add to the numerator while the denominator counts distinct phases —
+    // pushing completed_phases past it, where the old `Math.min` cap silently
+    // rounded the result up to 100% and hid an unstarted phase. Newest-on-disk
+    // wins, mirroring state.cts's #2445 de-duplication. `pickRollupWinners` is
+    // the SHARED implementation `workstream-inventory.cts`'s ledger-winner
+    // selection also calls, so the two can never independently diverge again
+    // (#2645 review).
+    const rollupDirByKey = pickRollupWinners([...phaseDirNames].sort(), (dir) => countsMap.get(dir)?.phaseKey ?? dir, (dir) => countsMap.get(dir)?.mtimeMs ?? 0, (dir) => !(scoped && countsMap.get(dir)?.inMilestone === false));
+    const rollupDirs = new Set(rollupDirByKey.values());
     const phases = [];
     let completedPhases = 0;
     let totalPlans = 0;
     let completedPlans = 0;
+    // #2562 review: in-milestone phase directories still present under `phases/`,
+    // whatever their status. A CLEAN archive has none — `milestone complete` moves
+    // them all out — so this counts exactly the phases that outlived the archive,
+    // which is what distinguishes "archived" from "archived, then reopened".
+    // Deliberately NOT "…and unfinished": a complete live dir beside a declared
+    // but never-scaffolded phase is a dirty archive too, and the dirless phase has
+    // no directory to inspect.
+    let liveInMilestonePhases = 0;
     for (const dir of [...phaseDirNames].sort()) {
-        const counts = countsMap.get(dir) ?? { planCount: 0, summaryCount: 0 };
-        const status = counts.summaryCount >= counts.planCount && counts.planCount > 0
+        const counts = countsMap.get(dir);
+        const planCount = counts?.planCount ?? 0;
+        const summaryCount = counts?.summaryCount ?? 0;
+        // ADR-3180 §7.4 (issue #3186): routed through the single canonical owner
+        // (`isPhaseComplete`, src/verification.cts) — via `PhaseFilesCount.complete`,
+        // which the I/O-capable CALLER computes (this module is a PURE, I/O-free
+        // projection — see the module header: "No I/O. No async." — and cannot
+        // call the owner itself). The prior local derivation
+        // (`summaryCount >= planCount && planCount > 0` combined with a
+        // caller-supplied verification status) was this module's OWN completion
+        // verdict computed from raw counts — the exact "post-process a canonical
+        // result locally" bypass §7.4 rules out, and it reproduced the disk-strict
+        // headline case (#3168): a zero-plan phase with a passing verification
+        // read `pending` instead of `complete`. `complete` defaults to `false`
+        // when absent so a caller that has not been updated to pass it never
+        // silently reads as complete.
+        const status = (counts?.complete ?? false)
             ? 'complete'
-            : counts.planCount > 0
+            : planCount > 0
                 ? 'in_progress'
                 : 'pending';
-        totalPlans += counts.planCount;
-        completedPlans += Math.min(counts.summaryCount, counts.planCount);
-        if (status === 'complete')
-            completedPhases++;
+        // #2562: only current-milestone phases feed the rollup when scoping is on,
+        // and only one directory per phase key (see rollupDirs above).
+        const countsTowardMilestone = (!scoped || counts?.inMilestone !== false) && rollupDirs.has(dir);
+        if (countsTowardMilestone) {
+            totalPlans += planCount;
+            completedPlans += Math.min(summaryCount, planCount);
+            if (status === 'complete')
+                completedPhases++;
+            liveInMilestonePhases++;
+        }
         phases.push({
             directory: dir,
             status,
-            plan_count: counts.planCount,
-            summary_count: counts.summaryCount,
+            plan_count: planCount,
+            summary_count: summaryCount,
         });
     }
+    // #2562: the denominator is the current milestone's declared phase count when
+    // scoping is active (catches phases declared but never scaffolded), else the
+    // legacy whole-roadmap heading count.
+    const effectivePhaseCount = scoped ? currentMilestonePhaseCount : roadmapPhaseCount;
+    // #2562 invariant: the numerator counts de-duplicated in-milestone phase keys
+    // and the denominator counts the union of those keys with the roadmap's own
+    // declarations, so the numerator can never exceed it. Raising the numerator
+    // above the denominator means the two sides were derived in different key
+    // spaces — the defect class this issue is about. The old `Math.min(100, …)`
+    // capped that away and reported 100%; this makes it fail loudly instead.
+    if (scoped && completedPhases > effectivePhaseCount) {
+        throw new Error(`workstream inventory invariant violated for "${name}": completed_phases (${completedPhases}) ` +
+            `exceeds the current-milestone denominator (${effectivePhaseCount}). The completion numerator and ` +
+            `denominator were derived in different phase-key spaces.`);
+    }
     // #1913: derive status from authoritative shipped signals rather than trusting
     // the mutable STATE.md `Status` field. When a shipped signal is present, the
     // workstream is "milestone complete" regardless of a stale field value.
+    //
+    // #2562 review: a shipped signal is a CLAIM, and a claim its own milestone's
+    // artifacts contradict must not be echoed as fact — the defect class this issue
+    // is about reaches `status`, not just `progress_percent`. The two signals need
+    // DIFFERENT cross-checks; one check for both regresses the commonest shape:
+    //
+    //  - `heading` — operator-typed marker in the LIVE roadmap. Nothing has been
+    //    archived, so every phase the milestone declares should be on disk and
+    //    complete. Gate on the full ratio, which also catches the
+    //    declared-but-never-scaffolded phases that have no directory to inspect.
+    //  - `snapshot` — `milestones/<version>-ROADMAP.md`. The `milestone complete`
+    //    run that writes it also MOVES the milestone's phase directories into
+    //    `milestones/<version>-phases/` (milestone.cts:783-790) while COPYING —
+    //    never truncating — the live ROADMAP (:700-702), so its Progress rows
+    //    survive. A CLEAN archive therefore reads 0/N by construction, and gating
+    //    it on the ratio alone would strip `milestone complete` from every
+    //    archived milestone. But a live in-milestone directory means the archive
+    //    is NOT clean — a phase was added or reopened after it, reachable because
+    //    `milestone complete` does not advance STATE's `milestone:` field
+    //    (state-transition.cts:83, :1335); only `/gsd-new-milestone` does (:1224).
+    //    Once any in-milestone directory is live the ratio IS meaningful again, so
+    //    the check is the conjunction. Requiring the live directory to itself be
+    //    unfinished was too narrow: it let a complete live dir alongside a
+    //    declared-but-unscaffolded phase reproduce the reported symptom, since a
+    //    dirless phase has nothing to inspect.
+    //
+    // The whole cross-check is scoped-only, and NOT because of the signal: when
+    // scoping is off, `effectivePhaseCount` is the whole-roadmap count and
+    // membership is everything, so there is no current-milestone artifact set to
+    // check a current-milestone claim against. `legacy` is additionally ungated by
+    // signal — it is the fallback for an unknown milestone version, which is
+    // exactly when scoping cannot engage either.
     const fieldStatus = stateProjection.status;
-    const useDerived = milestoneShipped;
-    const status = useDerived ? 'milestone complete' : fieldStatus;
-    const status_source = useDerived ? 'derived' : 'field';
-    const status_conflict = useDerived && !isCompletedInventory(fieldStatus);
+    const shippedContradicted = scoped && (shippedSignal === 'heading'
+        ? completedPhases < effectivePhaseCount
+        : shippedSignal === 'snapshot'
+            ? liveInMilestonePhases > 0 && completedPhases < effectivePhaseCount
+            : false);
+    const useDerived = milestoneShippedResolved && !shippedContradicted;
+    // Refusing the claim does not make the STATE field a safe fallback: it is
+    // operator-written and in this window it commonly ALSO reads "milestone
+    // complete", which would re-report the refused claim through the other door.
+    // Against contradicting artifacts, NEITHER source may assert completion.
+    const artifactOverride = shippedContradicted && isCompletedInventory(fieldStatus);
+    const status = useDerived
+        ? 'milestone complete'
+        : artifactOverride
+            ? 'in_progress'
+            : fieldStatus;
+    const status_source = useDerived || artifactOverride ? 'derived' : 'field';
+    const status_conflict = (useDerived && !isCompletedInventory(fieldStatus)) || artifactOverride;
     return {
         name,
         path: toPosixPath(node_path_1.default.relative(projectDir, workstreamDir)),
@@ -76,16 +236,40 @@ function buildWorkstreamInventory(inputs) {
         status,
         status_source,
         status_conflict,
+        milestone_shipped_unverified: shippedContradicted,
         current_phase: stateProjection.current_phase,
         last_activity: stateProjection.last_activity,
         phases,
         phase_count: phases.length,
         completed_phases: completedPhases,
-        roadmap_phase_count: roadmapPhaseCount,
+        roadmap_phase_count: effectivePhaseCount,
         total_plans: totalPlans,
         completed_plans: completedPlans,
-        progress_percent: roadmapPhaseCount > 0
-            ? Math.min(100, Math.round((completedPhases / roadmapPhaseCount) * 100))
-            : 0,
+        // `clampPercent`'s 100 ceiling is unreachable under milestone scoping (the
+        // invariant above throws first) and matters only for the legacy unscoped
+        // path, where the denominator is a roadmap heading count that a caller
+        // cannot guarantee bounds the numerator.
+        //
+        // #3217 (ADR-3180 §7.6 rule 4) — WRITTEN REASON this site is NOT migrated
+        // onto the `SCOPE` enum this phase: `buildWorkstreamInventory` is a pure
+        // projection (no I/O — see the module header) fed `BuildWorkstreamInventoryInputs`
+        // by `workstream-inventory.cts`. Its own `milestoneScoped` is a pre-ADR-3180
+        // bespoke boolean, not a `SCOPE` value, and its caller does not currently
+        // thread a real `listMilestonePhaseDirs` scope into these inputs. Doing
+        // this honestly requires ONE of: (a) widening `BuildWorkstreamInventoryInputs`
+        // with a `Scope` field and `WorkstreamInventory.progress_percent`'s type
+        // from `number` to `number | null` — the exact "re-architecting
+        // StateProjection/WorkstreamInventory return types" the design phase
+        // (`.gsd/phase/refactor-3217-completion-ratio-scoping/40-design.md`,
+        // "Known limits") states is OUT of this phase's scope; or (b) silently
+        // reusing `milestoneScoped` as a `Scope` stand-in, which would be exactly
+        // the kind of proxy-for-a-data-flow-property this same phase's guard
+        // section explicitly rejects (a `boolean` cannot distinguish TRUNCATED
+        // from UNSCOPED from UNREADABLE, so a caller could not tell which
+        // non-answer it got). Left un-migrated rather than done dishonestly;
+        // `workstream inventory`'s `progress_percent` can still render a number
+        // derived from an under-scoped set (A8 in the phase's test matrix is
+        // NOT covered here for that reason — see this phase's PR description).
+        progress_percent: (0, phase_lifecycle_cjs_1.clampPercent)(completedPhases, effectivePhaseCount),
     };
 }