@opengsd/gsd-core 1.9.1 → 1.10.0

package/gsd-core/bin/lib/mcp-server.cjs

@@ -27,6 +27,9 @@
  * the additive, importable server surface a host (or the bin shim) drives.
  */
 'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SERVER_NAME = exports.PROTOCOL_VERSION = void 0;
 exports.handleMessage = handleMessage;
@@ -36,9 +39,62 @@ const stateIo = require("./state-io.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCommandProjection = require("./shell-command-projection.cjs");
 const { dispatchGsdCommand } = shellCommandProjection;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const mcp_catalog_cjs_1 = require("./mcp-catalog.cjs");
 exports.PROTOCOL_VERSION = '2024-11-05';
 exports.SERVER_NAME = 'gsd-core';
-const SERVER_VERSION = '1.7.0';
+// #3072: resolve SERVER_VERSION from package.json (source tree) or the
+// installed gsd-core/VERSION marker, WITHOUT a top-level `require(...)` —
+// mirrors the established, already-precedented resolver in
+// `runtime-artifact-conversion.cts`'s `gsdVersion()` (#1383): a top-level
+// require would throw on any runtime whose root has no package.json/VERSION,
+// and `scripts/sync-manifest-versions.cjs` is not a fit here — its
+// `VERSIONED_MANIFESTS` list stamps a `version` FIELD into hand-authored JSON
+// manifests (plugin.json, marketplace.json, vscode/package.json); a `.cts`
+// source constant is not a JSON document that script can round-trip through
+// `readJson`/`setByPath`, and teaching it to text-edit TypeScript source
+// would be a much larger footprint than this lazy, cached, defensive read.
+// Resolved once per process (never per-request) and cached; a failed lookup
+// degrades to '0.0.0' (never `undefined`, never a crash) rather than making
+// `initialize`'s `serverInfo.version` field absent or malformed.
+const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
+let cachedServerVersion;
+function resolveServerVersion() {
+    if (cachedServerVersion !== undefined)
+        return cachedServerVersion;
+    let version = '0.0.0';
+    try {
+        const v = node_fs_1.default.readFileSync(node_path_1.default.join(__dirname, '..', '..', 'VERSION'), 'utf8').trim();
+        if (SEMVER_PREFIX.test(v))
+            version = v;
+    }
+    catch {
+        /* not an installed tree (no gsd-core/VERSION) */
+    }
+    if (version === '0.0.0') {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy, defensive: a top-level require would throw on a runtime root with no package.json.
+            const pkg = require(node_path_1.default.join(__dirname, '..', '..', '..', 'package.json'));
+            if (pkg && typeof pkg.version === 'string' && SEMVER_PREFIX.test(pkg.version))
+                version = pkg.version;
+        }
+        catch {
+            /* runtime root has no package.json */
+        }
+    }
+    cachedServerVersion = version;
+    return version;
+}
+// Catalog is built once per process, lazily, and cached (design "Shape" /
+// Gall's Law — no watching, no invalidation; Known limits: the package is
+// immutable in every install mode we ship).
+let cachedCatalog;
+function getCatalog() {
+    if (cachedCatalog === undefined)
+        cachedCatalog = (0, mcp_catalog_cjs_1.buildCatalog)();
+    return cachedCatalog;
+}
 // JSON-RPC 2.0 error codes.
 const PARSE_ERROR = -32700;
 const INVALID_REQUEST = -32600;
@@ -93,6 +149,32 @@ function okResponse(id, result) {
 function asString(v) {
     return typeof v === 'string' ? v : null;
 }
+/** Extract the {@link REASON} carried by a `CatalogError`, if any (see `mcp-catalog.cts`). */
+function catalogErrorReason(err) {
+    const reason = err && typeof err === 'object' ? err.reason : undefined;
+    return typeof reason === 'string' ? reason : undefined;
+}
+function catalogErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Map a `mcp-catalog.cts` `CatalogError.reason` to a JSON-RPC error code.
+ * `READ_FAILED` is a server-side IO/compose failure (`INTERNAL_ERROR`);
+ * every other reason (unknown uri/prompt/cursor/root, malformed/traversal
+ * uri, wrong-typed param) is a client-supplied-value problem (`INVALID_PARAMS`)
+ * — deliberately never `METHOD_NOT_FOUND`, so a refusal is never
+ * indistinguishable from the method simply not existing (test-matrix rows
+ * 33/35).
+ */
+function catalogErrorCode(err) {
+    return catalogErrorReason(err) === mcp_catalog_cjs_1.REASON.READ_FAILED ? INTERNAL_ERROR : INVALID_PARAMS;
+}
+function wireResource(entry) {
+    return { uri: entry.uri, name: entry.name, title: entry.title, description: entry.description, mimeType: entry.mimeType };
+}
+function wirePrompt(entry) {
+    return { name: entry.name, title: entry.title, description: entry.description };
+}
 function callTool(name, args, ctx) {
     const a = (args && typeof args === 'object' ? args : {});
     const cwd = asString(ctx.cwd) || process.cwd();
@@ -148,8 +230,12 @@ function handleMessage(request, ctx = {}) {
         case 'initialize':
             result = {
                 protocolVersion: exports.PROTOCOL_VERSION,
-                capabilities: { tools: {} },
-                serverInfo: { name: exports.SERVER_NAME, version: SERVER_VERSION },
+                // #3072: resources/prompts declared alongside tools. Deliberately NO
+                // subscribe/listChanged — nothing ever sends those notifications
+                // (design row 2 / Hyrum's Law: advertising an unimplemented
+                // notification is a lie a host would act on).
+                capabilities: { tools: {}, resources: {}, prompts: {} },
+                serverInfo: { name: exports.SERVER_NAME, version: resolveServerVersion() },
             };
             break;
         case 'tools/list':
@@ -163,6 +249,52 @@ function handleMessage(request, ctx = {}) {
             result = callTool(toolName, params.arguments, ctx);
             break;
         }
+        case 'resources/list': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            try {
+                const cursor = typeof params.cursor === 'string' ? params.cursor : undefined;
+                const pageSize = typeof params.pageSize === 'number' ? params.pageSize : undefined;
+                const page = (0, mcp_catalog_cjs_1.listResources)(getCatalog(), { cursor, pageSize });
+                result = page.nextCursor === undefined
+                    ? { resources: page.resources.map(wireResource) }
+                    : { resources: page.resources.map(wireResource), nextCursor: page.nextCursor };
+            }
+            catch (e) {
+                return errorResponse(id, catalogErrorCode(e), catalogErrorMessage(e));
+            }
+            break;
+        }
+        case 'resources/read': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            try {
+                const read = (0, mcp_catalog_cjs_1.readResource)(getCatalog(), params.uri);
+                result = { contents: [{ uri: read.uri, mimeType: read.mimeType, text: read.text }] };
+            }
+            catch (e) {
+                return errorResponse(id, catalogErrorCode(e), catalogErrorMessage(e));
+            }
+            break;
+        }
+        case 'prompts/list':
+            result = {
+                prompts: [...getCatalog().prompts.values()]
+                    .map(wirePrompt)
+                    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+            };
+            break;
+        case 'prompts/get': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            const name = asString(params.name);
+            if (!name)
+                return errorResponse(id, INVALID_PARAMS, 'prompts/get requires string "name".');
+            try {
+                result = (0, mcp_catalog_cjs_1.getPrompt)(getCatalog(), name, params.arguments);
+            }
+            catch (e) {
+                return errorResponse(id, catalogErrorCode(e), catalogErrorMessage(e));
+            }
+            break;
+        }
         default:
             if (isNotification)
                 return null;

package/gsd-core/bin/lib/milestone.cjs

@@ -464,13 +464,25 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // Guard: prevent marking complete when ROADMAP still lists phases that have
     // no directory on disk (disk_status: no_directory). This catches the case
     // where the active milestone was erroneously marked complete before phases
-    // were even started. Only fires when STATE.md confirms the current milestone
-    // version matches what is being completed — no false positives on fresh
-    // projects where phases haven't been scaffolded yet.
+    // were even started. The scan scopes the ROADMAP via the `version` argument
+    // (getMilestonePhaseFilter / extractCurrentMilestone above) and runs whenever
+    // --force is absent — a fresh project with no `### Phase N:` headings in the
+    // scoped slice yields an empty `noDirectoryPhases` and the guard is a no-op,
+    // so no STATE match is required to avoid false positives.
     // Pass --force to override this guard.
+    //
+    // #2946: the scan used to be nested inside `if (stateVersion && stateVersion
+    // === version)`, which silently disarmed the guard whenever STATE.md's
+    // `milestone:` field was desynced or absent — functionally an implicit
+    // --force on a one-way-door operation (ROADMAP/REQUIREMENTS archived, phase
+    // directories MOVED). The STATE field is not the source of truth for which
+    // phases belong to this milestone; the ROADMAP scoping is. The scan now runs
+    // unconditionally, and a present-but-mismatched STATE field emits a WARNING
+    // so the suspicious condition is visible rather than silent.
     if (!options.force) {
         try {
-            // Only guard when STATE.md's milestone field matches the version being completed.
+            // Read STATE.md's milestone field only to detect a suspicious mismatch;
+            // it no longer gates the scan. (#2946)
             let stateVersion = null;
             try {
                 const stateRaw = node_fs_1.default.existsSync(statePath) ? node_fs_1.default.readFileSync(statePath, 'utf-8') : null;
@@ -481,58 +493,74 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                 }
             }
             catch {
-                /* skip */
+                /* skip — stateVersion stays null, scan still runs */
             }
-            if (stateVersion && stateVersion === version) {
-                const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-                const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
-                // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-                const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
-                const noDirectoryPhases = [];
-                let pm;
-                const phaseDirEntries = (() => {
-                    try {
-                        return node_fs_1.default
-                            .readdirSync(phasesDir, { withFileTypes: true })
-                            .filter((e) => e.isDirectory())
-                            .map((e) => e.name);
-                    }
-                    catch {
-                        return [];
-                    }
-                })();
-                while ((pm = phasePattern.exec(scopedContent)) !== null) {
-                    const phaseNum = pm[1];
-                    // Phase 0 (pre-milestone) and Phase 999 (backlog) are sentinels, not
-                    // real phases — they legitimately have no directory and must not block
-                    // milestone completion. Mirrors the engine-wide sentinel convention
-                    // (phase-id getMilestoneFromPhaseId, roadmap-command-router SENTINELS,
-                    // the #1445 /^999/ progress filters). (#1580)
-                    const major = parseInt(phaseNum, 10);
-                    if (major === 0 || major === 999)
-                        continue;
-                    const normalized = normalizePhaseName(phaseNum);
-                    // A phase has disk_status: 'no_directory' when no phase directory
-                    // with a matching token exists on disk. Use the same phaseTokenMatches
-                    // helper that roadmap.analyze uses to avoid false positives on decimal
-                    // (2.1) and letter-suffix (12A) phase IDs.
-                    const hasDirectory = phaseDirEntries.some((d) => phaseTokenMatches(d, normalized));
-                    if (!hasDirectory) {
-                        noDirectoryPhases.push(phaseNum);
-                    }
+            if (stateVersion !== null && stateVersion !== version) {
+                // #2946: emit a WARNING so the suspicious STATE mismatch is visible
+                // rather than silently disarming the guard. Plain-text diagnostic on
+                // stderr, matching the existing [gsd-tools] WARNING convention
+                // (state.cts). A missing STATE.md `milestone:` field is not warned
+                // here — the scan still runs, and "no milestone declared" is a normal
+                // state for a fresh project, not a suspicious drift.
+                //
+                // `stateVersion` comes from a user-controlled file (STATE.md) and is
+                // not validated like the CLI `version` arg (ARCHIVE_VERSION_LABEL_RE).
+                // Sanitize before interpolating into stderr so ANSI escapes / control
+                // chars / secret-looking strings cannot be echoed verbatim into a CI
+                // log or terminal (CONTRIBUTING.md security: secret-looking values in
+                // stderr). `version` is already constrained to [A-Za-z0-9._-].
+                const safeStateVersion = stateVersion.replace(/[\x00-\x1f\x7f]/g, '?').slice(0, 80);
+                process.stderr.write(`[gsd-tools] WARNING: STATE.md milestone: "${safeStateVersion}" ≠ requested "${version}" — ` +
+                    `running the unstarted-phase guard against the ROADMAP scoped for "${version}" anyway.\n`);
+            }
+            const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+            const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
+            // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+            const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
+            const noDirectoryPhases = [];
+            let pm;
+            const phaseDirEntries = (() => {
+                try {
+                    return node_fs_1.default
+                        .readdirSync(phasesDir, { withFileTypes: true })
+                        .filter((e) => e.isDirectory())
+                        .map((e) => e.name);
                 }
-                if (noDirectoryPhases.length > 0) {
-                    error(`Cannot mark milestone complete: ROADMAP lists ${noDirectoryPhases.length} unstarted phase(s) ` +
-                        `(e.g. Phase ${noDirectoryPhases[0]}). Re-run with --force to override.`);
+                catch {
+                    return [];
+                }
+            })();
+            while ((pm = phasePattern.exec(scopedContent)) !== null) {
+                const phaseNum = pm[1];
+                // Phase 0 (pre-milestone) and Phase 999 (backlog) are sentinels, not
+                // real phases — they legitimately have no directory and must not block
+                // milestone completion. Mirrors the engine-wide sentinel convention
+                // (phase-id getMilestoneFromPhaseId, roadmap-command-router SENTINELS,
+                // the #1445 /^999/ progress filters). (#1580)
+                const major = parseInt(phaseNum, 10);
+                if (major === 0 || major === 999)
+                    continue;
+                const normalized = normalizePhaseName(phaseNum);
+                // A phase has disk_status: 'no_directory' when no phase directory
+                // with a matching token exists on disk. Use the same phaseTokenMatches
+                // helper that roadmap.analyze uses to avoid false positives on decimal
+                // (2.1) and letter-suffix (12A) phase IDs.
+                const hasDirectory = phaseDirEntries.some((d) => phaseTokenMatches(d, normalized));
+                if (!hasDirectory) {
+                    noDirectoryPhases.push(phaseNum);
                 }
             }
+            if (noDirectoryPhases.length > 0) {
+                error(`Cannot mark milestone complete: ROADMAP lists ${noDirectoryPhases.length} unstarted phase(s) ` +
+                    `(e.g. Phase ${noDirectoryPhases[0]}). Re-run with --force to override.`);
+            }
         }
         catch (e) {
             // If the error came from our guard, re-throw it; otherwise skip silently.
             const message = e instanceof Error ? e.message : String(e);
             if (message && message.startsWith('Cannot mark milestone complete:'))
                 throw e;
-            // Phase scan failed or STATE version mismatch — allow completion to proceed.
+            // Phase scan failed (e.g. ROADMAP unreadable) — allow completion to proceed.
         }
     }
     // Gather stats from phases (scoped to current milestone only)
@@ -695,7 +723,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             kind: 'milestoneComplete',
             version,
             nextMilestoneCommand: (0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd)),
-        }, { clock: clock_cjs_1.realClock, progressProvider: () => null, sourcePath: statePath });
+        }, { clock: clock_cjs_1.realClock, sourcePath: statePath });
         writeStateMd(statePath, result.content, cwd);
     }
     // Archive phase directories if requested

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

@@ -520,6 +520,65 @@ function phaseTokenMatches(dirName, normalized) {
     }
     return false;
 }
+// ─── Canonical phase KEY surface (#2562) ─────────────────────────────────────
+//
+// A phase "key" is the padding-, case- and project-code-insensitive identity of
+// a phase, for use as a Map/Set key when two independently-derived phase
+// references (a ROADMAP table cell and a phase directory name, say) must be
+// compared. Promoted here from a local pair in state.cts (#2445) so every
+// consumer derives BOTH sides of a comparison from the SAME function — deriving
+// one side with a bespoke regex is the #2562 defect class (a `01` table cell
+// never matching a `1-slug` directory, silently zeroing a rollup).
+/**
+ * Canonical key for an already-extracted phase TOKEN (`"5"`, `"05"`, `"005"`,
+ * `"12A"`, `"30.1"`, `"PROJ-05"`). Padding- and case-insensitive: every
+ * spelling of a number collapses to one key.
+ *
+ * Leading zeros are stripped per hyphen-separated segment BEFORE
+ * `normalizePhaseName` pads to the 2-digit convention. Padding alone is not a
+ * normalisation — `padStart(2)` is a no-op once the input is already ≥2
+ * characters, so `5` yielded `05` while `005` stayed `005` and the two never
+ * compared equal. The strip is deliberately confined to this key surface:
+ * `normalizePhaseName` itself is a RENDERING function whose verbatim treatment
+ * of wide IDs (`001.10`) is relied on by plan-ID capture and wave assignment.
+ * Arithmetic is avoided (`parseInt` would lose precision on a long digit run).
+ */
+function phaseKeyFromToken(token) {
+    const stripped = String(token)
+        .split('-')
+        .map(segment => segment.replace(/^0+(?=\d)/, ''))
+        .join('-');
+    return normalizePhaseName(stripped).toUpperCase();
+}
+/**
+ * Canonical key for a phase DIRECTORY name (`"05-schedule-8"` → `"05"`,
+ * `"PROJ-5-x"` → `"05"`, `"30.1-follow-up"` → `"30.1"`).
+ */
+function phaseKeyFromDir(dirName) {
+    return phaseKeyFromToken(extractPhaseToken(dirName));
+}
+/**
+ * Canonical key for a phase referenced in PROSE — a ROADMAP `## Progress` table
+ * cell (`"30. Schedule 8 rollout"`, `"**05.1 Follow-up**"`) or a STATE.md
+ * `Phase:` value. Markdown emphasis is stripped first so a bolded cell is not
+ * mistaken for a non-phase. Returns null when the value does not BEGIN with a
+ * phase token (`parsePhaseFromProse` anchoring, #2111).
+ */
+function phaseKeyFromProse(value) {
+    if (value == null)
+        return null;
+    const { phase } = parsePhaseFromProse(String(value).replace(/[*_`~]/g, ''));
+    return phase === null ? null : phaseKeyFromToken(phase);
+}
+/**
+ * The PARENT phase key of a sub-phase key (`"30.1"` → `"30"`), or null for a
+ * top-level phase. A sub-phase directory inserted mid-milestone frequently has
+ * no ROADMAP row of its own and inherits its parent's milestone (#2562).
+ */
+function parentPhaseKey(key) {
+    const dot = key.indexOf('.');
+    return dot === -1 ? null : key.slice(0, dot);
+}
 // ─── #2121 canonical surface (ADR-2121) ──────────────────────────────────────
 /**
  * Parse a phase identifier from a STATE.md `Phase:` prose field VALUE — the text
@@ -662,6 +721,10 @@ module.exports = {
     comparePhaseNum,
     extractPhaseToken,
     phaseTokenMatches,
+    phaseKeyFromToken,
+    phaseKeyFromDir,
+    phaseKeyFromProse,
+    parentPhaseKey,
     parsePhaseFromProse,
     stripConfiguredProjectCodePrefix,
     isForeignPrefixedPhaseQuery,

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

@@ -30,7 +30,67 @@ const { readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPa
 // 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;
+/**
+ * #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 (reverse-sorted directory names).
+ * 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 [];
+    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),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
 function searchPhaseInDir(baseDir, relBase, normalized) {
     try {
         const dirs = readSubdirectories(baseDir, true);
@@ -55,6 +115,9 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
                 has_verification: false,
                 has_reviews: false,
                 ambiguous_matches: matches,
+                halted_plans: [],
+                blocked_by: {},
+                runnable_plans: [],
             };
         }
         const match = matches[0];
@@ -76,6 +139,50 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
             const canonical = extractCanonicalPlanId(p);
             return !completedPlanIds.has(planId) && !completedPlanIds.has(canonical);
         });
+        // #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);
+            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 +196,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,59 +214,42 @@ 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;
 }
 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 = {