@opengsd/gsd-core 1.10.0 → 1.11.0

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

@@ -114,6 +114,68 @@ function buildSummaryFileIndex(summaryFiles, extractCanonicalPlanId) {
     }
     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.
  *
@@ -229,4 +291,13 @@ function computeHaltPropagation(nodes, precomputedOrder) {
     }
     return { order, visited, blockedBy };
 }
-module.exports = { computeHaltPropagation, isHaltedStatus, buildSummaryFileIndex, isSummaryFileHalted };
+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;