@opengsd/gsd-core 1.11.0 → 1.12.0

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

@@ -11,6 +11,17 @@
  * Dependencies:
  *   - ./pattern.cjs (escapeRegex — #3212 Phase 1 seam; this module is no
  *     longer the owner of pattern-escaping, only a consumer)
+ *   - ./core-utils.cjs (generateSlugInternal — #3883/ADR-3473 §8.3: the
+ *     canonical slug formula). core-utils.cjs also requires THIS module
+ *     (comparePhaseNum, scopeToPhase), so a top-level require here would be
+ *     circular and — per this codebase's compiled-.cjs convention of a
+ *     single `module.exports = {...}` reassignment at the bottom of each
+ *     file — a top-level circular require captures a stale, still-empty
+ *     exports object forever (verified live: it throws
+ *     "generateSlugInternal is not a function" when core-utils.cjs happens
+ *     to load first). The require is deferred (lazy, inside each function
+ *     body) instead, mirroring the same cycle-break already used by
+ *     core-utils.cts's own getPhaseFileStats/plan-scan.cjs seam.
  */
 const pattern_cjs_1 = require("./pattern.cjs");
 // ─── Phase-id helpers ─────────────────────────────────────────────────────────
@@ -214,9 +225,15 @@ function getPhaseDirFromPhaseId(phaseId, phaseName, projectCode) {
     const milestone = String(parseInt(m[1], 10)).padStart(2, '0');
     const subParts = m[2].split('-').map(p => String(parseInt(p, 10)).padStart(2, '0'));
     const sub = subParts.join('-');
-    const slug = phaseName
-        ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
-        : '';
+    // #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 silently shadow one on-disk phase dir's
+    // reported phase_slug behind another distinct >60-char phase name's.
+    // Lazy require to break the core-utils.cjs <-> phase-id.cjs cycle (see the
+    // module dependency doc comment above).
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+    const slug = phaseName ? (require('./core-utils.cjs').generateSlugInternal(phaseName, null) ?? '') : '';
     const parts = [milestone, sub, slug].filter(Boolean);
     const base = parts.join('-');
     return projectCode ? `${projectCode}-${base}` : base;
@@ -324,7 +341,22 @@ function toDir(id, slug) {
     const sub = id.subphase ? `.${id.subphase}` : '';
     // Slug guard: the slug becomes an on-disk path segment, so collapse it to a
     // safe lowercase token — never a path separator or `..` traversal.
-    const safeSlug = slug.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    // #3883 (ADR-3473 §8.3): delegate the sanitize formula itself to the
+    // canonical (generateSlugInternal, core-utils.cts) — this fixes the
+    // Cyrillic-collapses-to-empty defect (#2848-class) that toDir carried
+    // before (it never transliterated). The empty-sanitize and all-digit
+    // throw guards below stay: they are a DECLARED DIFFERENCE from every
+    // other slug call site, not a bug — a slug here becomes a real directory
+    // name, and toDir protects the parsePhaseId dir↔identity bijection
+    // (see the toDir docstring above) by refusing to emit an unusable name,
+    // where every other site silently accepts "" or a re-truncated value.
+    // `maxLen: null` preserves toDir's pre-migration untruncated contract — the
+    // 60-char default let two distinct >60-char phase names collapse onto the
+    // identical directory name, one silently shadowing the other on disk.
+    // Lazy require to break the core-utils.cjs <-> phase-id.cjs cycle (see the
+    // module dependency doc comment above).
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+    const safeSlug = require('./core-utils.cjs').generateSlugInternal(slug, null) ?? '';
     // A slug that sanitizes to nothing (e.g. '!!!') would otherwise emit a
     // dangling trailing hyphen.
     if (!safeSlug) {
@@ -360,6 +392,39 @@ function isSentinelPhaseId(phaseId, convention) {
         return false;
     return SENTINEL_RANGES.includes(parseInt(legacy[1], 10));
 }
+/**
+ * Disk-side sentinel recognizer (#3639): is this on-disk PHASE DIRECTORY a
+ * sentinel (never-on-roadmap by convention)?
+ *
+ * The disk-side guards (C001 gap numbering, W007 orphan dirs) see raw
+ * directory names and do not know the repo's naming convention — and neither
+ * convention-blind route could recognize a bracket sentinel: `isSentinelPhaseId`
+ * without the convention argument reads only the legacy leading int, while
+ * `extractPhaseToken(dirName)` (convention-aware or not) strips the MILESTONE
+ * and returns the bare phase token — bracket sentinel-ness lives in the
+ * milestone portion (`GSD.999-07-icebox` is icebox because of the 999, not
+ * the 07). This helper reads the milestone directly off the dir name.
+ *
+ * The bracket branch requires the FULL bracket dir shape — code prefix, dot,
+ * milestone digits, hyphen, PHASE DIGITS — so a #1324 letter-prefixed real
+ * dir with a LETTER slug (`P0.0-foundation`) never matches it (ADR-2121
+ * indistinguishability, same gate as extractPhaseToken below). DISCLOSED
+ * RESIDUAL (#3639 review): the #1324 family also has digit continuations
+ * (`P0.0-1-foundation`, `P0.3-2` are real shapes per derivePhaseTokenSegments),
+ * and `{code}.{0|999}-{digit}...` is string-indistinguishable from a bracket
+ * sentinel dir — no convention-free discriminator exists (ADR-2121). Such a
+ * dir reads as sentinel here, which at the disk-guard call sites suppresses
+ * a warning (conservative for a linter) rather than deleting data. The
+ * digit-continuation family with NON-sentinel first decimals (`P0.3-2`)
+ * reads milestone 3 — ordinary — exactly as the convention-gated id
+ * predicate does. Everything else falls to the legacy leading-int rule.
+ */
+function isSentinelPhaseDir(dirName) {
+    const bracketDir = dirName.match(/^[A-Z][A-Z0-9_]*\.(\d+)-\d/); // milestone digits + hyphen + phase DIGITS
+    if (bracketDir)
+        return SENTINEL_RANGES.includes(parseInt(bracketDir[1], 10));
+    return isSentinelPhaseId(dirName);
+}
 /**
  * Render a regex source fragment matching a phase number against ROADMAP/STATE
  * prose regardless of zero-padding on either side.
@@ -1120,6 +1185,7 @@ module.exports = {
     toDir,
     SENTINEL_RANGES,
     isSentinelPhaseId,
+    isSentinelPhaseDir,
     phaseMarkdownRegexSource,
     phaseMarkdownRegexSourceExact,
     comparePhaseNum,

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

@@ -21,6 +21,7 @@
  *   - Issue #4 (open-gsd/gsd-core)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.locateProgressTable = locateProgressTable;
 exports.deriveProgressFromRoadmap = deriveProgressFromRoadmap;
 exports.clampPercentFromFraction = clampPercentFromFraction;
 exports.clampPercent = clampPercent;
@@ -29,8 +30,10 @@ const markdown_table_cjs_1 = require("./markdown-table.cjs");
 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
@@ -49,6 +52,24 @@ const { isSentinelPhaseId } = phaseIdMod;
  * 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"
@@ -67,20 +88,7 @@ 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;

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

@@ -29,7 +29,7 @@ const coreUtilsModule = require("./core-utils.cjs");
 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;
@@ -95,24 +95,56 @@ function compareArchiveVersionDesc(aName, bName) {
     }
     return 0;
 }
-function listArchiveVersionDirs(cwd) {
-    const milestonesDir = node_path_1.default.join(planningDir(cwd), 'milestones');
-    if (!node_fs_1.default.existsSync(milestonesDir))
-        return [];
+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(compareArchiveVersionDesc)
-            .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 {
@@ -211,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,
@@ -339,13 +376,56 @@ function listMilestonePhaseDirs(phasesDir, opts = {}) {
         .sort((a, b) => comparePhaseNum(a, b));
     return { value, scope };
 }
-function getArchivedPhaseDirs(cwd) {
+/**
+ * #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({
@@ -358,9 +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,
 };