@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/plan-dependency-graph.cjs

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * Plan Dependency Graph — shared halt-propagation over a plan's depends_on DAG (#2830).
+ *
+ * Two independent "which plans are incomplete" readers exist in this codebase:
+ * phase.cts's wave-grouping (`cmdPhasePlanIndex`) and phase-locator.cts's
+ * phase-location primitive (`searchPhaseInDir`, consumed by ~50 symbols across
+ * five command routers). Before #2830, only the former parsed `depends_on` —
+ * and even it used the DAG only for topological wave assignment, never to
+ * propagate a halted plan's block onto its dependents. The latter never parsed
+ * `depends_on` at all; it derived completion from summary-file presence only.
+ * A plan that reaches a designed stop still writes a SUMMARY (recording the
+ * halt in prose only — no prior structured status existed for it), so both
+ * readers saw it as ordinary "complete" and reported its dependents as
+ * ordinary incomplete work, available to spawn against.
+ *
+ * This module is the SINGLE topological-order + halt-propagation engine both
+ * readers call, so the two can never re-diverge on this rule again. Each
+ * caller resolves its own raw `depends_on` tokens to canonical plan ids
+ * (case-fold + `extractCanonicalPlanId` fallback — the same resolution
+ * already performed by phase.cts's `computeDependencyLevels`) before
+ * building `PlanHaltNode[]`; this module owns the graph traversal (exactly
+ * one pass — Kahn's algorithm, or none at all when the caller already has a
+ * valid topological order, see `computeHaltPropagation`'s `precomputedOrder`
+ * parameter) plus the two small pure helpers below (`isHaltedStatus`,
+ * `buildSummaryFileIndex`) that both callers would otherwise duplicate
+ * identically — the exact "two implementations, one drifts" failure mode
+ * this fix exists to close. Each caller still owns its own file I/O (the
+ * actual `fs.readFileSync` + `extractFrontmatter` calls); only the
+ * interpretive logic is centralized here — except the SUMMARY-file
+ * read+extract wrapper itself (`isSummaryFileHalted`), which both callers
+ * previously duplicated near-identically and which is now centralized here
+ * too, for the same reason.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
+const frontmatterMod = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatterMod;
+/**
+ * The one place "does this SUMMARY status value mean halted" is decided.
+ * Case-insensitive, trims whitespace. Both `phase.cts`'s `cmdPhasePlanIndex`
+ * and `phase-locator.cts`'s `searchPhaseInDir` call this after reading a
+ * completed plan's SUMMARY frontmatter `status` field, so the definition of
+ * "halted" cannot drift between the two readers.
+ */
+function isHaltedStatus(status) {
+    if (typeof status !== 'string')
+        return false;
+    // #2830 review (defect 2): strip an unquoted trailing YAML comment (a run
+    // of whitespace followed by `#` and the rest of the line) before
+    // trimming/lowercasing. YAML scalars don't need quoting to carry an inline
+    // comment (`status: halted # designed stop`), but `extractFrontmatter`
+    // does not strip one — and all four summary templates literally show that
+    // spelling as guidance on the value line. Without this, an executor that
+    // mimics the template's own presentation would write a halt that silently
+    // reads back as not-halted. A `#` with no preceding whitespace is NOT a
+    // YAML comment start, so `halted#nospace` intentionally still fails to match.
+    const withoutTrailingComment = status.replace(/\s+#.*$/, '');
+    return withoutTrailingComment.trim().toLowerCase() === 'halted';
+}
+/**
+ * Read a plan's SUMMARY file and report whether it declares `status: halted`
+ * (a designed stop, not an ordinary completion). Returns false — never
+ * throws — on a missing/unreadable/malformed SUMMARY, so an unreadable file
+ * degrades to the pre-#2830 behavior ("has a SUMMARY = complete") rather
+ * than breaking either caller.
+ *
+ * Two callers share this wrapper: `phase.cts`'s `cmdPhasePlanIndex` and
+ * `phase-locator.cts`'s `searchPhaseInDir` (the phase-location primitive
+ * consumed by ~50 symbols across five command routers). Both previously
+ * carried a near-identical local copy (read file -> `extractFrontmatter` ->
+ * `isHaltedStatus` -> swallow errors) that this module's own header comment
+ * calls out as the exact "two implementations, one drifts" failure mode it
+ * exists to prevent — centralizing the read+extract wrapper here, not just
+ * the `isHaltedStatus` predicate, closes that gap.
+ *
+ * Takes a single resolved `summaryPath` (not a `dir` + `filename` pair) —
+ * `phase-locator.cts`'s prior local copy took the two parts separately and
+ * `path.join`'d them internally; that caller now does the join itself
+ * before calling in, so both callers share one signature.
+ *
+ * @param summaryPath - absolute or relative path to a `*-SUMMARY.md` file.
+ */
+function isSummaryFileHalted(summaryPath) {
+    try {
+        const content = node_fs_1.default.readFileSync(summaryPath, 'utf-8');
+        const fm = extractFrontmatter(content, summaryPath);
+        return isHaltedStatus(fm['status']);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build a planId -> summary-filename lookup from a phase's summary file
+ * list, keyed by both the exact SUMMARY-file-derived id and its canonical
+ * form (mirrors the `completedPlanIds` construction each caller already
+ * performs for its own SUMMARY-presence check — same `summaryFiles` list,
+ * same exact/canonical key pair — so the two can never disagree about which
+ * summary file belongs to which plan id). `extractCanonicalPlanId` is
+ * supplied by the caller (each module owns its own resolution helper).
+ */
+function buildSummaryFileIndex(summaryFiles, extractCanonicalPlanId) {
+    const index = new Map();
+    for (const s of summaryFiles) {
+        const exact = s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+        const canonical = extractCanonicalPlanId(s);
+        index.set(exact, s);
+        if (canonical !== exact)
+            index.set(canonical, s);
+    }
+    return index;
+}
+/**
+ * #3345: the one place "does this SUMMARY status value mean blocked" is
+ * decided, sibling to `isHaltedStatus` above. A SUMMARY declaring
+ * `status: blocked` records a plan that could NOT finish — it is a failure
+ * record, not a completion record — so it must not count toward
+ * `completed_plans` (scanPhasePlans's summaryCount) nor read as
+ * `has_summary: true` in phase-plan-index's `incomplete` construction.
+ *
+ * `halted` is deliberately NOT matched here: a designed stop still writes a
+ * completion record (#2830's model — its dependents get `blocked_by` halt
+ * propagation), so a `status: halted` SUMMARY keeps counting as summarized.
+ * Case-insensitive, trims whitespace, and strips an unquoted trailing YAML
+ * comment exactly like `isHaltedStatus` (same #2830 review defect-2 rule).
+ */
+function isBlockedStatus(status) {
+    if (typeof status !== 'string')
+        return false;
+    const withoutTrailingComment = status.replace(/\s+#.*$/, '');
+    return withoutTrailingComment.trim().toLowerCase() === 'blocked';
+}
+// #3345: SUMMARY frontmatter sits at byte 0 and closes well before the body,
+// so only a bounded prefix is ever needed to read the `status` marker — the
+// same cap discipline as plan-scan.cts's PLAN_FRONTMATTER_READ_CAP (#2349),
+// kept here because this predicate's primary caller (scanPhasePlans) loops
+// over every phase directory on hot paths (state sync, roadmap progress).
+const SUMMARY_FRONTMATTER_READ_CAP = 64 * 1024;
+/**
+ * #3345: read a SUMMARY file's frontmatter `status` (bounded-prefix read) and
+ * report whether it declares `status: blocked`. Returns false — never throws —
+ * on a missing/unreadable/malformed/non-regular SUMMARY, so an unreadable file
+ * degrades to the pre-#3345 filename-existence behaviour rather than breaking
+ * either caller. Fail-open by design, mirroring `isPlanSuperseded`'s posture.
+ *
+ * Callers: plan-scan.cts's `scanPhasePlans` (the count side) and phase.cts's
+ * `cmdPhasePlanIndex` (the read side) BOTH filter their summary lists through
+ * this one predicate, so the count and the `incomplete` list can never
+ * re-diverge on the blocked rule.
+ */
+function isSummaryFileBlocked(summaryPath) {
+    let content;
+    try {
+        const st = node_fs_1.default.statSync(summaryPath); // follows symlinks → resolves to the target's real type
+        if (!st.isFile())
+            return false;
+        const length = Math.min(st.size, SUMMARY_FRONTMATTER_READ_CAP);
+        if (length === 0)
+            return false;
+        const fd = node_fs_1.default.openSync(summaryPath, 'r');
+        try {
+            const buf = Buffer.allocUnsafe(length);
+            const bytesRead = node_fs_1.default.readSync(fd, buf, 0, length, 0);
+            content = buf.toString('utf8', 0, bytesRead);
+        }
+        finally {
+            node_fs_1.default.closeSync(fd);
+        }
+    }
+    catch {
+        return false;
+    }
+    return isBlockedStatus(extractFrontmatter(content, summaryPath)['status']);
+}
+/**
+ * Computes halt-propagation over a plan dependency DAG.
+ *
+ * `precomputedOrder`: when the caller ALREADY has a valid topological order
+ * for these exact node ids (e.g. phase.cts's `cmdPhasePlanIndex`, which runs
+ * `computeDependencyLevels`'s Kahn's-algorithm pass for wave assignment
+ * before ever calling this function), pass it here and this function skips
+ * running Kahn's algorithm a second time — the halt-propagation forward pass
+ * below only needs A valid topological order, not to derive one itself.
+ * Omit it (as phase-locator.cts's `searchPhaseInDir` does — it has no prior
+ * traversal of this DAG) and this function derives the order itself; either
+ * way, exactly one Kahn's-algorithm pass runs per caller, never two.
+ *
+ * Diamond-safe (a plan blocked via two different halted ancestors gets both
+ * in its `blockedBy` list, deduplicated) and transitive-safe (a dependent of
+ * a dependent of a halted plan is blocked, at any depth).
+ */
+function computeHaltPropagation(nodes, precomputedOrder) {
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    let order;
+    let visited;
+    if (precomputedOrder) {
+        // Caller already ran Kahn's algorithm over this exact node set (same ids)
+        // — trust its order and skip re-deriving one. `visited` mirrors the same
+        // "count of nodes reachable in valid topological order" contract a fresh
+        // derivation would produce.
+        order = precomputedOrder;
+        visited = precomputedOrder.length;
+    }
+    else {
+        const inDeg = new Map();
+        const adj = new Map(); // dependency id -> dependent ids
+        for (const n of nodes) {
+            if (!inDeg.has(n.id))
+                inDeg.set(n.id, 0);
+            if (!adj.has(n.id))
+                adj.set(n.id, []);
+            for (const depId of n.resolvedDependsOn) {
+                if (!byId.has(depId))
+                    continue; // fail-safe: caller should have filtered these already
+                if (!adj.has(depId))
+                    adj.set(depId, []);
+                adj.get(depId).push(n.id);
+                inDeg.set(n.id, (inDeg.get(n.id) ?? 0) + 1);
+            }
+        }
+        const queue = [];
+        for (const n of nodes) {
+            if ((inDeg.get(n.id) ?? 0) === 0)
+                queue.push(n.id);
+        }
+        // Dequeue by head index, not Array.shift() — O(1) amortized, same
+        // rationale as computeDependencyLevels (#307).
+        let head = 0;
+        let v = 0;
+        while (head < queue.length) {
+            const cur = queue[head++];
+            v++;
+            for (const dep of adj.get(cur) ?? []) {
+                inDeg.set(dep, inDeg.get(dep) - 1);
+                if (inDeg.get(dep) === 0)
+                    queue.push(dep);
+            }
+        }
+        order = queue;
+        visited = v;
+    }
+    // `order` is a valid topological order for every visited node: for edge
+    // dep -> dependent, dep appears before dependent. A single forward pass
+    // over it — using each node's own already-resolved dependsOn ids —
+    // computes blockedBy without any further graph traversal.
+    const blockedBy = new Map();
+    for (const id of order) {
+        const node = byId.get(id);
+        if (!node)
+            continue;
+        const causes = new Set();
+        for (const depId of node.resolvedDependsOn) {
+            const depNode = byId.get(depId);
+            if (!depNode)
+                continue;
+            if (depNode.halted)
+                causes.add(depId);
+            const depCauses = blockedBy.get(depId);
+            if (depCauses) {
+                for (const c of depCauses)
+                    causes.add(c);
+            }
+        }
+        if (causes.size > 0)
+            blockedBy.set(id, Array.from(causes));
+    }
+    // #2830 review (defect 1): a node involved in a depends_on cycle (or
+    // downstream of one) never reaches indegree 0, so it never appears in
+    // `order` and the forward pass above never visits it — it would otherwise
+    // end up absent from BOTH `blockedBy` and any cycle diagnostic, i.e.
+    // reported as ordinary runnable. A node whose position in the topological
+    // order is undecidable cannot be shown to be safe to run: silently
+    // dropping it is the exact silent-disappearance failure #2830 exists to
+    // prevent. Fail closed — give every such non-halted node an explicit,
+    // non-empty `blockedBy` entry so no consumer (present or future) can
+    // re-admit it as runnable merely by checking "absent from blockedBy".
+    // (A node that is itself halted is not "blocked" — it IS the blocker —
+    // so it is left out here exactly as the normal forward pass leaves it out.)
+    if (order.length < nodes.length) {
+        const orderSet = new Set(order);
+        for (const n of nodes) {
+            if (orderSet.has(n.id) || n.halted)
+                continue;
+            const causes = Array.from(new Set(n.resolvedDependsOn.filter((depId) => byId.has(depId)))).sort();
+            blockedBy.set(n.id, causes.length > 0 ? causes : [n.id]);
+        }
+    }
+    return { order, visited, blockedBy };
+}
+module.exports = {
+    computeHaltPropagation,
+    isHaltedStatus,
+    buildSummaryFileIndex,
+    isSummaryFileHalted,
+    // #3345: blocked-SUMMARY detection, shared by the count side (scanPhasePlans)
+    // and the read side (phase-plan-index) so the two cannot diverge.
+    isBlockedStatus,
+    isSummaryFileBlocked,
+};

package/gsd-core/bin/lib/plan-drift-guard.cjs

@@ -20,6 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AUTHORITY_RUNGS = void 0;
 exports.getEffectiveAuthority = getEffectiveAuthority;
 exports.classifyDriftSeverity = classifyDriftSeverity;
+exports.comparePhaseStatus = comparePhaseStatus;
 /**
  * Frozen map from authority name to its rung number.
  *
@@ -115,3 +116,122 @@ function classifyDriftSeverity({ status, authority, }) {
             return { severity: 'INFO', hardBlock: false };
     }
 }
+/**
+ * Frozen map from lowercased phase-status text to a shared ordinal rank,
+ * covering the union of the STATE.md "Current Position" vocabulary
+ * (gsd-core/templates/state.md) and the FULL ROADMAP.md "## Progress" table
+ * Status column vocabulary declared by gsd-core/templates/roadmap.md:133 —
+ * `Not started | In progress | Complete | Deferred`.
+ *
+ * The two vocabularies overlap on 'in progress', which is rank 1 in both —
+ * no conflict. 'deferred' is rank 0 (no work done) — see comparePhaseStatus's
+ * doc comment for how a deferred/non-rank-0 mismatch is classified; it is NOT
+ * simply numeric distance from rank 0 like an ordinary lag.
+ */
+const PHASE_STATUS_RANKS = Object.freeze({
+    // STATE.md "Current Position" vocabulary
+    'ready to plan': 0,
+    'planning': 0,
+    'ready to execute': 1,
+    'in progress': 1,
+    'phase complete': 2,
+    // ROADMAP.md "## Progress" table Status column vocabulary
+    'not started': 0,
+    'complete': 2,
+    'deferred': 0,
+});
+/** Rank at which a status asserts work is DONE (terminal, not comparative). */
+const TERMINAL_RANK = 2;
+/**
+ * Normalize a raw phase-status string for lookup/comparison: trims
+ * surrounding whitespace and lowercases. Returns null for missing/empty
+ * values. Single owner of this normalization so `resolvePhaseStatusRank` and
+ * the 'deferred' declared-intent check in `comparePhaseStatus` cannot drift
+ * apart on what counts as "empty".
+ */
+function normalizePhaseStatusText(value) {
+    if (value === null || value === undefined)
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return normalized === '' ? null : normalized;
+}
+/**
+ * Resolve a raw phase-status string to its shared ordinal rank, or null when
+ * the value is missing/empty/unrecognized. Case-insensitive, trims
+ * surrounding whitespace.
+ *
+ * @param value - raw status text from STATE.md or ROADMAP.md
+ * @returns the resolved rank, or null if unresolvable
+ */
+function resolvePhaseStatusRank(value) {
+    const normalized = normalizePhaseStatusText(value);
+    if (normalized === null)
+        return null;
+    if (!Object.prototype.hasOwnProperty.call(PHASE_STATUS_RANKS, normalized))
+        return null;
+    return PHASE_STATUS_RANKS[normalized];
+}
+/**
+ * Compare a phase's status as reported by STATE.md against the same phase's
+ * status as reported by ROADMAP.md's "## Progress" table, and classify the
+ * result.
+ *
+ * Unlike classifyDriftSeverity, this never throws for an unrecognized
+ * status: the inputs are user document text (prose a human or agent typed
+ * into STATE.md/ROADMAP.md), not config, so an unrecognized value is data —
+ * surfaced as 'uncheckable' — not a programming error.
+ *
+ * Rank 2 ('phase complete' / 'Complete') is TERMINAL: it asserts the work is
+ * DONE. If exactly one side reports rank 2 and the other does not, that is
+ * always 'drifted', regardless of numeric distance — a document claiming
+ * "done" while another claims "still going" is a direct contradiction, not
+ * mere lag. This is the issue's canonical example: complete in STATE.md but
+ * in progress in ROADMAP.md.
+ *
+ * 'Deferred' is a second declared-intent rank-0 status (gsd-core/templates/
+ * roadmap.md:133's full vocabulary: `Not started | In progress | Complete |
+ * Deferred`) that is NOT ordinary lag from rank 0: it is an explicit
+ * decision to STOP work, not merely "hasn't started yet". If exactly one
+ * side declares 'deferred' and the other side's rank is >= 1 (work is
+ * reported as in progress or complete), that is always 'drifted' — a phase
+ * declared deferred while the other document says work is happening is a
+ * direct contradiction, checked here (like the terminal-completeness rule
+ * above) BEFORE the numeric distance comparison. 'Deferred' against a
+ * rank-0 status on the other side (e.g. 'Not started') stays 'consistent' —
+ * both agree no work has happened.
+ *
+ * Otherwise, ranks are compared numerically: equal → 'consistent';
+ * off-by-one → 'lag'; off-by-two-or-more → 'drifted'.
+ *
+ * @param opts.stateStatus   - raw Status value from STATE.md's Current Position
+ * @param opts.roadmapStatus - raw Status cell from ROADMAP.md's Progress table
+ * @returns { verdict, stateRank, roadmapRank }
+ */
+function comparePhaseStatus({ stateStatus, roadmapStatus, }) {
+    const stateRank = resolvePhaseStatusRank(stateStatus);
+    const roadmapRank = resolvePhaseStatusRank(roadmapStatus);
+    if (stateRank === null || roadmapRank === null) {
+        return { verdict: 'uncheckable', stateRank, roadmapRank };
+    }
+    const stateIsTerminal = stateRank === TERMINAL_RANK;
+    const roadmapIsTerminal = roadmapRank === TERMINAL_RANK;
+    if (stateIsTerminal !== roadmapIsTerminal) {
+        return { verdict: 'drifted', stateRank, roadmapRank };
+    }
+    const stateIsDeferred = normalizePhaseStatusText(stateStatus) === 'deferred';
+    const roadmapIsDeferred = normalizePhaseStatusText(roadmapStatus) === 'deferred';
+    if (stateIsDeferred !== roadmapIsDeferred) {
+        const otherRank = stateIsDeferred ? roadmapRank : stateRank;
+        if (otherRank >= 1) {
+            return { verdict: 'drifted', stateRank, roadmapRank };
+        }
+    }
+    const diff = Math.abs(stateRank - roadmapRank);
+    if (diff === 0) {
+        return { verdict: 'consistent', stateRank, roadmapRank };
+    }
+    if (diff === 1) {
+        return { verdict: 'lag', stateRank, roadmapRank };
+    }
+    return { verdict: 'drifted', stateRank, roadmapRank };
+}

package/gsd-core/bin/lib/plan-scan.cjs

@@ -15,6 +15,12 @@ const { countMatchedSummaries } = coreUtils;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatterMod = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatterMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planDependencyGraphMod = require("./plan-dependency-graph.cjs");
+const { isSummaryFileBlocked } = planDependencyGraphMod;
 // Excluded derivative files
 const PLAN_OUTLINE_RE = /-OUTLINE\.md$/i;
 const PLAN_PRE_BOUNCE_RE = /\.pre-bounce\.md$/i;
@@ -97,6 +103,43 @@ function isRootSummaryFile(fileName) {
 function isNestedSummaryFile(fileName) {
     return /^SUMMARY-\d+.*\.md$/i.test(fileName) || /-SUMMARY-\d+.*\.md$/i.test(fileName);
 }
+/**
+ * Strict canonical-naming predicate over a `scanPhasePlans` `planFiles`/
+ * `allPlanFiles` ENTRY (root form bare, nested form `plans/`-prefixed, exactly
+ * as those arrays store them) — root `<phase>-<NN>-PLAN.md`/bare `PLAN.md`,
+ * or nested `plans/PLAN-<NN>....md`/`plans/<x>-PLAN-<NN>....md` — WITHOUT
+ * `isRootPlanFile`'s loose `/\.md$/i && /PLAN/i` fallback.
+ *
+ * The `plans/` prefix check is load-bearing, not cosmetic: `isNestedPlanFile`
+ * matches ANY basename containing `-PLAN-<digits>...md` with no anchor
+ * requiring an actual `plans/` directory — that shape is exactly the #2893
+ * reporter's non-canonical example, `01-PLAN-01-foundation.md`. Applying
+ * `isNestedPlanFile` directly to a bare root-level name would therefore
+ * misclassify that exact offender as canonical. Only entries scanPhasePlans
+ * itself produced with the `plans/` prefix (i.e. read from the real nested
+ * subdirectory) are eligible for the nested check.
+ *
+ * #2893/#3183: `isRootPlanFile`'s loose fallback is deliberately permissive
+ * for live-plan COUNTING (a lowercase `plan.md` still counts toward
+ * completion — see plan-count-single-owner.test.cjs's pinned case-sensitivity
+ * asymmetry). But the #2893 "non-canonical filename" diagnostic (phase.cts's
+ * `describeNonCanonicalPlans`, used by find-phase/phase-plan-index/phases
+ * list --type plans) exists specifically to CATCH a plan-shaped file that
+ * does NOT match the canonical contract and warn instead of silently
+ * scheduling it. Feeding that diagnostic (and the `plans`/`files` lists those
+ * commands return) the loose `allPlanFiles`/`planFiles` set defeats the
+ * diagnostic entirely, since the loose fallback already recognizes the
+ * non-canonical file as "matched". This predicate is the STRICT filter those
+ * three call sites intersect against so the diagnostic (and what counts as a
+ * schedulable plan for those commands specifically) stays canonical-only,
+ * while scanPhasePlans's own planCount/summaryCount/completed stay on the
+ * loose, permissive rule.
+ */
+function isCanonicalPlanFile(fileEntry) {
+    if (fileEntry.startsWith('plans/'))
+        return isNestedPlanFile(fileEntry.slice('plans/'.length));
+    return fileEntry.endsWith('-PLAN.md') || fileEntry === 'PLAN.md';
+}
 function scanPhasePlans(phaseDir) {
     let rootFiles;
     try {
@@ -109,7 +152,9 @@ function scanPhasePlans(phaseDir) {
             completed: false,
             hasNestedPlans: false,
             planFiles: [],
+            allPlanFiles: [],
             summaryFiles: [],
+            scope: SCOPE.UNREADABLE,
         };
     }
     const rootPlanFiles = rootFiles.filter(isRootPlanFile);
@@ -117,6 +162,7 @@ function scanPhasePlans(phaseDir) {
     let nestedPlanFiles = [];
     let nestedSummaryFiles = [];
     let hasNestedPlans = false;
+    let scope = SCOPE.COMPLETE;
     const nestedDir = (0, node_path_1.join)(phaseDir, 'plans');
     if ((0, node_fs_1.existsSync)(nestedDir)) {
         try {
@@ -125,7 +171,12 @@ function scanPhasePlans(phaseDir) {
             nestedSummaryFiles = nestedFiles.filter(isNestedSummaryFile).map((file) => `plans/${file}`);
             hasNestedPlans = nestedPlanFiles.length > 0;
         }
-        catch { /* ignore unreadable nested layout */ }
+        catch {
+            // #3183 (ADR-3180 Decision 2): the nested plans/ dir exists but could not
+            // be read — this scan cannot see plans it knows are there, so zero is
+            // NOT a reliable answer; mark TRUNCATED rather than COMPLETE.
+            scope = SCOPE.TRUNCATED;
+        }
     }
     const allPlanFiles = rootPlanFiles.concat(nestedPlanFiles);
     // #2349: drop plans explicitly marked `status: superseded` from the plan set
@@ -144,7 +195,18 @@ function scanPhasePlans(phaseDir) {
     // 30-GAPCLOSURE-SUMMARY.md) must not inflate summary_count or flip a phase to
     // Complete when plans are still missing summaries. summaryFiles (the array)
     // still holds every summary on disk for callers that read/list them.
-    const summaryCount = countMatchedSummaries(planFiles, summaryFiles);
+    //
+    // #3345: a SUMMARY whose frontmatter declares `status: blocked` is a failure
+    // record, not a completion record — it is dropped from the COUNTABLE pairing
+    // set before matching. The bounded-prefix status read is the SHARED predicate
+    // (plan-dependency-graph.cjs's isSummaryFileBlocked) that phase.cts's read
+    // path also filters through, so the count and the `incomplete` list cannot
+    // diverge. Fail-open: a SUMMARY with no `status` key, or one that cannot be read,
+    // keeps its pre-#3345 filename-existence meaning — untouched projects are
+    // byte-for-behaviour identical. `status: halted` stays counted (#2830: a
+    // designed stop still writes a completion record).
+    const countableSummaryFiles = summaryFiles.filter((f) => !isSummaryFileBlocked((0, node_path_1.join)(phaseDir, f)));
+    const summaryCount = countMatchedSummaries(planFiles, countableSummaryFiles);
     return {
         planCount,
         summaryCount,
@@ -155,10 +217,31 @@ function scanPhasePlans(phaseDir) {
         // (0 >= 0) rather than being pinned below 100% forever, which is the very
         // failure this fix removes. A genuinely empty phase (no plans authored)
         // still has allPlanFiles.length 0 and stays not-completed, exactly as before.
+        //
+        // ADR-3180 §7.4 (issue #3186) — DELIBERATELY NOT routed through
+        // `isPhaseComplete` (src/verification.cts). This field answers "are all
+        // plans summarized?", NOT "is the phase complete?" — completion
+        // additionally requires a passing `*-VERIFICATION.md`, which is the
+        // whole point of that owner's unconditional readVerificationStatus call.
+        // Folding this field onto `isPhaseComplete` would either over-report
+        // completion (a phase whose plans are done but never verified) or drag a
+        // verification read into this module, inverting the dependency
+        // direction between this Phase-1 owner (plan counting) and the Phase-4
+        // owner (completion) — the owner must consume plan counts, never the
+        // reverse. Kept as its own, differently-scoped answer per the design's
+        // "0.x split" and exempted (function-scoped, not file-scoped) in
+        // scripts/lint-completion-predicate-drift.cjs's FUNCTION_SCOPED_EXEMPTIONS.
+        // The field name is left unchanged (not renamed to e.g.
+        // `summariesMeetPlanCount`) — scanPhasePlans has 11 direct callers, and a
+        // rename's blast radius is out of this phase's declared scope; noted
+        // here as a deliberate, considered-and-declined option rather than an
+        // oversight.
         completed: allPlanFiles.length > 0 && summaryCount >= planCount,
         hasNestedPlans,
         planFiles,
+        allPlanFiles,
         summaryFiles,
+        scope,
     };
 }
 module.exports = Object.assign(scanPhasePlans, {
@@ -167,4 +250,5 @@ module.exports = Object.assign(scanPhasePlans, {
     isNestedPlanFile,
     isRootSummaryFile,
     isNestedSummaryFile,
+    isCanonicalPlanFile,
 });

package/gsd-core/bin/lib/planning-scope.cjs

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Planning Scope — shared result discriminator for live-plan scanning.
+ *
+ * ADR-3180 Decision 2 (docs/adr/3180-planning-semantic-model-single-owner.md):
+ * `scanPhasePlans` is the single owner of live-plan counting, and every
+ * consumer of that count needs to distinguish a REAL answer from a
+ * NON-answer. `SCOPE.COMPLETE` with zero items is a real answer — a phase
+ * genuinely has no plans yet. `SCOPE.TRUNCATED`, `SCOPE.UNSCOPED`, and
+ * `SCOPE.UNREADABLE` with zero items are NOT — they mean the scan could not
+ * see (part of) the phase directory, so a caller must not treat that zero as
+ * "this phase has no plans."
+ *
+ * This is a frozen enum, not a message string: CONTRIBUTING.md bans raw-text
+ * matching on outputs and requires a typed IR, so callers branch on the
+ * `SCOPE` value rather than pattern-matching prose.
+ *
+ * PROVISIONAL: this contract is pending this phase's validation and may be
+ * revised before the epic (#3180) ships.
+ *
+ * Dependencies: none — this is a leaf module (mirrors src/phase-id.cts). It
+ * imports nothing, so any consumer can depend on it without risking a cycle.
+ */
+const SCOPE = Object.freeze({
+    COMPLETE: 'complete',
+    TRUNCATED: 'truncated',
+    UNSCOPED: 'unscoped',
+    UNREADABLE: 'unreadable',
+});
+const planningScope = { SCOPE };
+module.exports = planningScope;