@opengsd/gsd-core 1.10.0 → 1.12.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-document.cjs

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Plan Document Module — the single parser for a `*-PLAN.md` document BODY.
+ *
+ * Owns: objective extraction, the task-block grammar (`<task>` elements, with
+ * the legacy `## Task N` heading fallback — including the optional `tracker-id`
+ * attribute, ADR-3646 Phase 1, read verbatim and never split here), planned-file
+ * extraction, and the frontmatter-derived scheduling metadata (`wave`,
+ * `depends_on`, `autonomous`, `agent_hint`, `files_modified`).
+ *
+ * WHY THIS IS A LEAF MODULE. This logic was written inline inside
+ * `cmdPhasePlanIndex` (`src/phase.cts`). Two commands in two different families
+ * now need it — `phase.plan-index` and `planning.inspect` (#2790) — so leaving
+ * it in `phase.cts` would force `planning` to depend on `phase`, and copying it
+ * would be the *Generative Fix Divergence* class `CLAUDE.md` names. A leaf owned
+ * by neither family is the seam that matches the actual usage (Conway's Law).
+ *
+ * NOT an ADR-3180 §7 derivation. §6 puts the document-parsing layer explicitly
+ * out of that epic's scope (#2143); this module answers "what does this plan
+ * document say", never "how many plans are outstanding" (that is
+ * `scanPhasePlans`, §7.5) or "is this phase complete" (`isPhaseComplete`, §7.4).
+ *
+ * BEHAVIOUR IS PRESERVED BYTE-FOR-BEHAVIOUR from the prior inline code. In
+ * particular `tasks.length` is exactly the legacy `taskCount`
+ * (`xmlTasks.length || mdTasks.length`), including its known fence-blindness —
+ * a `## Task 1` inside a fenced code block still counts, exactly as it does
+ * today. That is a characterised limit, not an endorsement: changing it would
+ * silently change `phase.plan-index`'s output for existing projects, which is a
+ * Hyrum's-Law break that belongs in its own issue rather than riding along on a
+ * read-only query addition.
+ *
+ * ADR-457 build-at-publish: source in src/plan-document.cts, compiled to
+ * gsd-core/bin/lib/plan-document.cjs (gitignored).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatterMod;
+// ─── Frozen vocabularies ──────────────────────────────────────────────────────
+/**
+ * How a task row was expressed in the document. `auto` is the ordinary
+ * executable task; `checkpoint` is a `<task type="checkpoint:*">` block, which
+ * carries an entirely different element set (`<decision>`/`<what-built>`, no
+ * `<name>`/`<files>`/`<acceptance_criteria>`). Distinguishing them is what
+ * stops a checkpoint from being reported as a malformed auto task.
+ */
+const TASK_KIND = Object.freeze({
+    AUTO: 'auto',
+    CHECKPOINT: 'checkpoint',
+});
+// ─── Task grammar ─────────────────────────────────────────────────────────────
+// The legacy counting rule, preserved verbatim from cmdPhasePlanIndex. `g` is
+// required (we count every occurrence) and these are rebuilt per call rather
+// than hoisted to module scope: a global regex carries mutable `lastIndex`
+// state, and a shared instance is a cross-call contamination bug.
+function xmlTaskOpenings(content) {
+    return [...content.matchAll(/<task(?=[\s>])[^>]*>/gi)];
+}
+function markdownTaskHeadings(content) {
+    return [...content.matchAll(/##\s*Task\s*\d+[^\n]*/gi)];
+}
+/** Extract the value of one attribute from a `<task ...>` opening tag. */
+function tagAttribute(openTag, attr) {
+    const re = new RegExp(`\\b${attr}\\s*=\\s*"([^"]*)"|\\b${attr}\\s*=\\s*'([^']*)'`, 'i');
+    const m = re.exec(openTag);
+    if (!m)
+        return null;
+    const value = (m[1] ?? m[2] ?? '').trim();
+    return value.length > 0 ? value : null;
+}
+/**
+ * Body of the first `<tag>…</tag>` inside `block`, or null. Non-greedy and
+ * case-insensitive; a tag that is opened but never closed yields null rather
+ * than swallowing the rest of the document.
+ */
+function elementBody(block, tag) {
+    const re = new RegExp(`<${tag}\\s*>([\\s\\S]*?)</${tag}\\s*>`, 'i');
+    const m = re.exec(block);
+    return m ? m[1] : null;
+}
+/**
+ * Split a `<files>` body into paths. Comma-separated per the shipped
+ * `templates/phase-prompt.md` grammar; newline-separated forms are tolerated
+ * too (Postel — liberal in what we accept), and the caller records nothing
+ * special for them because a path list is a path list either way.
+ */
+function splitFileList(body) {
+    if (body === null)
+        return [];
+    return body
+        .split(/[,\n]/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+/** `<acceptance_criteria>` carries `- ` bullets, one criterion per line. */
+function splitCriteria(body) {
+    if (body === null)
+        return [];
+    return body
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => line.replace(/^[-*]\s*/, ''))
+        .filter((line) => line.length > 0);
+}
+function collapseWhitespace(value) {
+    if (value === null)
+        return null;
+    const trimmed = value.replace(/\s+/g, ' ').trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Parse the `<task>` blocks. Each opening tag found by `xmlTaskOpenings` yields
+ * exactly one row — the block runs from that tag to its `</task>`, or to the
+ * next opening tag, or to end-of-document. Bounding on the NEXT OPENING rather
+ * than only on `</task>` is what keeps an unclosed block from consuming its
+ * siblings, so the row count still equals the opening count.
+ */
+function parseXmlTasks(content) {
+    const openings = xmlTaskOpenings(content);
+    return openings.map((match, i) => {
+        const start = match.index ?? 0;
+        const openTag = match[0];
+        const nextStart = i + 1 < openings.length ? (openings[i + 1].index ?? content.length) : content.length;
+        const window = content.slice(start, nextStart);
+        const closeIdx = window.search(/<\/task\s*>/i);
+        const block = closeIdx === -1 ? window : window.slice(0, closeIdx);
+        const type = tagAttribute(openTag, 'type');
+        const kind = type !== null && type.toLowerCase().startsWith('checkpoint')
+            ? TASK_KIND.CHECKPOINT
+            : TASK_KIND.AUTO;
+        // A checkpoint block has no <name>/<files>/<acceptance_criteria>/<done> in
+        // the shipped grammar. Reading them anyway would be harmless but dishonest:
+        // the caller must be able to tell "this element is absent because this kind
+        // of task has no such element" from "this element is missing and should not
+        // be".
+        if (kind === TASK_KIND.CHECKPOINT) {
+            return {
+                index: i + 1,
+                kind,
+                type,
+                name: null,
+                plannedFiles: [],
+                acceptanceCriteria: [],
+                done: null,
+                trackerId: null,
+            };
+        }
+        return {
+            index: i + 1,
+            kind,
+            type,
+            name: collapseWhitespace(elementBody(block, 'name')),
+            plannedFiles: splitFileList(elementBody(block, 'files')),
+            acceptanceCriteria: splitCriteria(elementBody(block, 'acceptance_criteria')),
+            done: collapseWhitespace(elementBody(block, 'done')),
+            trackerId: tagAttribute(openTag, 'tracker-id'),
+        };
+    });
+}
+/**
+ * Legacy fallback: `## Task N` headings, used ONLY when the document carries no
+ * `<task>` blocks at all. Deliberately fence-blind, matching the counting rule
+ * `cmdPhasePlanIndex` has always used — see this module's header comment.
+ */
+function parseMarkdownTasks(content) {
+    return markdownTaskHeadings(content).map((match, i) => ({
+        index: i + 1,
+        kind: TASK_KIND.AUTO,
+        type: null,
+        name: collapseWhitespace(match[0].replace(/^##\s*/, '')),
+        plannedFiles: [],
+        acceptanceCriteria: [],
+        done: null,
+        trackerId: null,
+    }));
+}
+// ─── Objective ────────────────────────────────────────────────────────────────
+/**
+ * Preserved verbatim from `cmdPhasePlanIndex`: the first line following an
+ * `<objective>` tag. Deliberately NOT widened to the full element body — that
+ * would change `phase.plan-index`'s existing output for any multi-line
+ * objective.
+ */
+function extractObjective(content) {
+    const m = content.match(/<objective>\s*\n?\s*(.+)/);
+    return m ? m[1].trim() : null;
+}
+// ─── Entry point ──────────────────────────────────────────────────────────────
+/**
+ * The plan id for a plan FILE ENTRY, exactly as `scanPhasePlans` stores it
+ * (root entries bare, nested entries `plans/`-prefixed).
+ *
+ * This is the established derivation from `cmdPhasePlanIndex`, moved here
+ * VERBATIM (#2790) so `phase.plan-index` and `planning.inspect` cannot report
+ * different ids for the same plan — a consumer correlating the two surfaces
+ * needs them to join. Deliberately NOT "improved": it is a display/lookup key
+ * with existing callers, and changing what it returns would be a Hyrum's-Law
+ * break on `phase-plan-index`.
+ */
+function planIdFromFile(planFile) {
+    return planFile.replace('-PLAN.md', '').replace('PLAN.md', '');
+}
+/**
+ * Parse one plan document.
+ *
+ * @param content  Raw `*-PLAN.md` text.
+ * @param planPath Optional path, used only to name the file in `extractFrontmatter`'s
+ *                 truncated-frontmatter diagnostic (#1882). Callers that do not have
+ *                 one omit it — this default IS the shape production uses from the
+ *                 read-only query path.
+ */
+function parsePlanDocument(content, planPath = '') {
+    const fm = extractFrontmatter(content, planPath);
+    const xmlTasks = parseXmlTasks(content);
+    const tasks = xmlTasks.length > 0 ? xmlTasks : parseMarkdownTasks(content);
+    const parsedWave = parseInt(fm['wave'], 10);
+    const declaredWave = Number.isNaN(parsedWave) ? null : parsedWave;
+    let dependsOn = [];
+    const fmDeps = fm['depends_on'];
+    if (Array.isArray(fmDeps)) {
+        dependsOn = fmDeps.map(String);
+    }
+    else if (typeof fmDeps === 'string' && fmDeps.trim() !== '') {
+        dependsOn = [fmDeps];
+    }
+    let autonomous = true;
+    if (fm['autonomous'] !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue comparison
+        autonomous = fm['autonomous'] === 'true' || String(fm['autonomous']) === 'true';
+    }
+    let filesModified = [];
+    const fmFiles = fm['files_modified'] || fm['files-modified'];
+    if (fmFiles) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
+        filesModified = Array.isArray(fmFiles) ? fmFiles.map(String) : [String(fmFiles)];
+    }
+    let filesDeleted = [];
+    const fmDeleted = fm['files_deleted'] || fm['files-deleted'];
+    if (fmDeleted) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
+        filesDeleted = Array.isArray(fmDeleted) ? fmDeleted.map(String) : [String(fmDeleted)];
+    }
+    let agentHint = null;
+    const fmAgentHint = fm['agent_hint'];
+    if (fmAgentHint !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
+        const hintStr = String(fmAgentHint).trim();
+        agentHint = hintStr !== '' ? hintStr : null;
+    }
+    return {
+        objective: extractObjective(content) || fm['objective'] || null,
+        declaredWave,
+        dependsOn,
+        autonomous,
+        agentHint,
+        filesModified,
+        filesDeleted,
+        tasks,
+        taskCount: tasks.length,
+    };
+}
+const planDocument = { TASK_KIND, parsePlanDocument, planIdFromFile };
+module.exports = planDocument;

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;
@@ -82,7 +88,18 @@ function isRootPlanFile(fileName) {
     // substring "PLAN") are not double-counted as plans. (#500 RC2)
     if (isRootSummaryFile(fileName))
         return false;
-    return /\.md$/i.test(fileName) && /PLAN/i.test(fileName);
+    // #3741: the PLAN token must be DELIMITED — anchored at the start or after
+    // a hyphen, and followed only by an optional `-<digits>…` suffix before
+    // `.md` (the `…` keeps the legacy slug form `3-PLAN-01-setup.md` that
+    // gsd-plan-phase writes, per #3128). A bare substring test counted
+    // REPLAN-INPUTS / PLANNING-INPUTS / PLANNING-NOTES as plans, inflating
+    // planCount and STATE.md's derived total_plans. Delimited keeps the
+    // fallback's deliberate permissiveness for legacy single-token names
+    // (`plan.md`, `Plan.md`, `01-PLAN-02.md`, `3-PLAN-01-setup.md`) while
+    // excluding any name where PLAN is merely embedded in a larger word
+    // (REPLAN, PLANNING) — the same anchoring discipline isNestedPlanFile
+    // already applies.
+    return /(^|-)PLAN(-\d+.*)?\.md$/i.test(fileName);
 }
 function isNestedPlanFile(fileName) {
     if (PLAN_OUTLINE_RE.test(fileName))
@@ -97,6 +114,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 delimited-PLAN 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 +163,9 @@ function scanPhasePlans(phaseDir) {
             completed: false,
             hasNestedPlans: false,
             planFiles: [],
+            allPlanFiles: [],
             summaryFiles: [],
+            scope: SCOPE.UNREADABLE,
         };
     }
     const rootPlanFiles = rootFiles.filter(isRootPlanFile);
@@ -117,6 +173,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 +182,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 +206,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 +228,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 +261,5 @@ module.exports = Object.assign(scanPhasePlans, {
     isNestedPlanFile,
     isRootSummaryFile,
     isNestedSummaryFile,
+    isCanonicalPlanFile,
 });