@opengsd/gsd-core 1.16.0 → 1.18.0

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

@@ -1067,6 +1067,62 @@ function describeGoalShapedTitle(description) {
     return (`description looks goal-shaped, not title-shaped (${reasons}). It was written verbatim ` +
         `as the phase title; consider a short title with the detail moved to **Goal:**.`);
 }
+/**
+ * Phase numbers the roadmap itself declares — a section header or a roadmap bullet — sentinels
+ * excluded. This is deliberately NOT the allocation set: allocation also counts on-disk directories
+ * and sibling-worktree phases so a new number cannot collide, but a `Depends on:` line has to point
+ * at something a reader of THIS roadmap can find (#5113).
+ */
+function roadmapDeclaredPhaseNums(rawContent) {
+    const { regex: headerPattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.LABEL_ONLY);
+    const bulletPattern = /^[ \t]*-[ \t]*\[[^\]]{0,200}\][ \t]*\*{0,2}Phase[ \t]+(\d+)(?=[:.\s*]|$)/gim;
+    const nums = new Set();
+    let m;
+    while ((m = headerPattern.exec(rawContent)) !== null) {
+        const num = parseInt(m[phaseNumGroup], 10);
+        if (!isSentinelPhaseId(num))
+            nums.add(num);
+    }
+    while ((m = bulletPattern.exec(rawContent)) !== null) {
+        const num = parseInt(m[1], 10);
+        if (!isSentinelPhaseId(num))
+            nums.add(num);
+    }
+    return [...nums];
+}
+/**
+ * The `**Depends on:**` line for a freshly added numeric phase: the nearest lower phase the roadmap
+ * declares, or `Nothing` when it declares none. It was `newId - 1` regardless, which named a phase
+ * that exists only on a sibling branch, as an orphan directory, or not at all when numbering has a
+ * gap (#5113). Custom-named phases carry no dependency line.
+ */
+function dependsOnLine(newPhaseId, declared) {
+    if (typeof newPhaseId !== 'number')
+        return '';
+    let nearest = null;
+    for (const n of declared)
+        if (n < newPhaseId && (nearest === null || n > nearest))
+            nearest = n;
+    return `\n**Depends on:** ${nearest === null ? 'Nothing' : `Phase ${nearest}`}`;
+}
+/**
+ * Splice a phase entry into `rawContent` at `at`, changing nothing else: the blank lines around the
+ * block and its line endings are the block's own, so the surrounding document is published byte for
+ * byte (#5113). `block` is LF text that starts and ends with a newline.
+ */
+function spliceRoadmapBlock(rawContent, atOffset, block) {
+    const eol = rawContent.includes('\r\n') ? '\r\n' : '\n';
+    // The insertion offset is found by searching for '\n---', which lands between the CR and the LF of
+    // a CRLF pair; splice before the pair instead of through it.
+    const at = rawContent[atOffset - 1] === '\r' && rawContent[atOffset] === '\n' ? atOffset - 1 : atOffset;
+    const before = rawContent.slice(0, at);
+    const after = rawContent.slice(at);
+    const body = block.replace(/^\n+/, '').replace(/\n+$/, '\n').replace(/\n/g, eol);
+    const blankBefore = before === '' || /(?:\r?\n){2}$/.test(before);
+    const lead = blankBefore ? '' : /\n$/.test(before) ? eol : eol + eol;
+    const tail = after === '' || /^\r?\n/.test(after) ? '' : eol;
+    return before + lead + body + tail + after;
+}
 /**
  * #3163: compute the byte offset in `rawContent` where a new `### Phase N:`
  * entry should be inserted — at the end of the active phase list, scoped to the
@@ -1310,13 +1366,11 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
         const dirPath = node_path_1.default.join(planningDir(cwd), 'phases', _dirName);
         (0, shell_command_projection_cjs_1.platformEnsureDir)(dirPath);
         (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(dirPath, '.gitkeep'), '');
-        const dependsOn = config.phase_naming === 'custom'
-            ? ''
-            : `\n**Depends on:** Phase ${typeof _newPhaseId === 'number' ? _newPhaseId - 1 : 'TBD'}`;
+        const dependsOn = config.phase_naming === 'custom' ? '' : dependsOnLine(_newPhaseId, roadmapDeclaredPhaseNums(rawContent));
         const phaseEntry = `\n### Phase ${_newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run ${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} ${_newPhaseId} to break down)\n`;
         const insertAt = phaseEntryInsertOffset(rawContent, cwd);
-        const updatedContent = rawContent.slice(0, insertAt) + phaseEntry + rawContent.slice(insertAt);
-        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, updatedContent);
+        const updatedContent = spliceRoadmapBlock(rawContent, insertAt, phaseEntry);
+        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, updatedContent, { verbatim: true });
         return { newPhaseId: _newPhaseId, dirName: _dirName };
     });
     const titleWarning = describeGoalShapedTitle(description);
@@ -1432,12 +1486,10 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
             const dirPath = node_path_1.default.join(planningDir(cwd), 'phases', dirName);
             (0, shell_command_projection_cjs_1.platformEnsureDir)(dirPath);
             (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(dirPath, '.gitkeep'), '');
-            const dependsOn = config.phase_naming === 'custom'
-                ? ''
-                : `\n**Depends on:** Phase ${typeof newPhaseId === 'number' ? newPhaseId - 1 : 'TBD'}`;
+            const dependsOn = config.phase_naming === 'custom' ? '' : dependsOnLine(newPhaseId, roadmapDeclaredPhaseNums(rawContent));
             const phaseEntry = `\n### Phase ${newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run ${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} ${newPhaseId} to break down)\n`;
             const insertAt = phaseEntryInsertOffset(rawContent, cwd);
-            rawContent = rawContent.slice(0, insertAt) + phaseEntry + rawContent.slice(insertAt);
+            rawContent = spliceRoadmapBlock(rawContent, insertAt, phaseEntry);
             added.push({
                 phase_number: typeof newPhaseId === 'number' ? newPhaseId : String(newPhaseId),
                 padded: typeof newPhaseId === 'number' ? String(newPhaseId).padStart(2, '0') : String(newPhaseId),
@@ -1447,7 +1499,7 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
                 naming_mode: config.phase_naming,
             });
         }
-        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, rawContent);
+        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, rawContent, { verbatim: true });
         return added;
     });
     output({ phases: results, count: results.length }, raw);
@@ -3061,6 +3113,42 @@ function formatRequirementsLineWarning(phaseNum, rawLine, analysis) {
             oversized,
     };
 }
+/**
+ * #4972: advisory gaps for the phase artifacts that active `verify:post` steps
+ * declared `onError: "halt"` and `produces` (SECURITY.md, VALIDATION.md).
+ * Missing file, an unresolved `status: draft`, or (SECURITY.md) `threats_open`
+ * above zero. Any other `status` spelling counts as closed — the audit skills
+ * do not pin one value, so this does not invent a vocabulary.
+ */
+function auditArtifactWarnings(cwd, phaseFullDir) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy: loop-resolver pulls in the capability registry
+    const loopResolver = require('./loop-resolver.cjs');
+    const out = [];
+    const files = node_fs_1.default.readdirSync(phaseFullDir);
+    for (const hook of loopResolver.resolveActiveHooksForPoint(cwd, 'verify:post').activeHooks) {
+        if (hook.kind !== 'step' || hook.onError !== 'halt')
+            continue;
+        for (const artifact of hook.produces ?? []) {
+            if (!/^[A-Z][A-Z0-9-]*\.md$/.test(artifact))
+                continue;
+            const skill = hook.ref?.skill ?? hook.capId;
+            const found = files.filter((f) => f === artifact || f.endsWith(`-${artifact}`)).sort()[0];
+            if (!found) {
+                out.push(`${artifact}: missing — the ${hook.capId} audit (/gsd:${skill}) never ran for this phase, and a verify:post step cannot block the close (#4972)`);
+                continue;
+            }
+            const fm = frontmatterMod.extractFrontmatter(node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, found), 'utf-8'));
+            if (typeof fm['status'] === 'string' && fm['status'].trim().toLowerCase() === 'draft') {
+                out.push(`${found}: status is still draft — the ${hook.capId} audit (/gsd:${skill}) was not completed (#4972)`);
+            }
+            const open = Number(fm['threats_open']);
+            if (artifact === 'SECURITY.md' && Number.isFinite(open) && open > 0) {
+                out.push(`${found}: ${open} threat(s) still open (#4972)`);
+            }
+        }
+    }
+    return out;
+}
 function cmdPhaseComplete(cwd, phaseNum, raw) {
     if (!phaseNum) {
         error('phase number required for phase complete');
@@ -3274,6 +3362,23 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         /* best-effort, same posture as the #2245 pre-scan above: an unreadable
          * SUMMARY means one fewer advisory this run, never a blocked completion. */
     }
+    // #4972: a `verify:post` STEP declared `onError: "halt"` that produces a
+    // phase artifact (security -> SECURITY.md, nyquist -> VALIDATION.md) reads as
+    // a blocking precondition, but a step is advisory by construction (ADR-894
+    // "steps are additive, gates block") and the workflow only prints a line the
+    // operator can ignore — so a phase could close with the audit never run. This
+    // verb is the one place every close passes through, so it names the gap on
+    // the same ADVISORY `warnings[]` channel as the #2572 check above. Advisory,
+    // not a refusal: both capabilities are on by default, so a hard block here
+    // would stop every existing project's next phase close; the security
+    // threats-open gate at `ship:pre` is the enforced one and is untouched.
+    try {
+        warnings.push(...auditArtifactWarnings(cwd, phaseFullDir));
+    }
+    catch {
+        /* best-effort, same posture as the advisories above: an unresolvable hook
+         * set or unreadable artifact means one fewer advisory, never a blocked close. */
+    }
     let nextPhaseNum = null;
     let nextPhaseName = null;
     let isLastPhase = true;
@@ -4199,6 +4304,26 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 // #3374 / #3469).
                 const nextPhaseDisplayName = phaseDisplayNameFromRoadmap(roadmapContent, nextPhaseNum) ??
                     phaseDisplayNameFromSlug(nextPhaseName);
+                // #4824: classify the SELECTED next phase from disk (the same ladder
+                // roadmap analyze uses) so the Status / Current Plan / Stopped-at
+                // handoff does not say "ready to plan" for a phase already planned or
+                // executed. A missing directory or unreadable phase keeps the
+                // historical wording.
+                let nextPhaseDisk = null;
+                if (nextPhaseNum && !isLastPhase) {
+                    try {
+                        const nextInfo = findPhaseInternal(cwd, nextPhaseNum);
+                        if (nextInfo && nextInfo.found && nextInfo.directory) {
+                            const { value } = (0, phase_status_cjs_1.phaseStatus)(node_path_1.default.join(cwd, nextInfo.directory), {
+                                convention: resolvePhaseIdConvention(cwd),
+                            });
+                            nextPhaseDisk = { status: value.status, planCount: value.planCount, summaryCount: value.summaryCount };
+                        }
+                    }
+                    catch {
+                        /* best-effort: an unreadable next phase keeps `Ready to plan` */
+                    }
+                }
                 const completeResult = (0, state_transition_cjs_1.transitionCore)(stateContent, {
                     kind: 'completePhase',
                     phaseNum,
@@ -4207,9 +4332,14 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     isLastPhase,
                     planCount,
                     summaryCount,
+                    nextPhaseDisk,
                 }, {
                     clock: clock_cjs_1.realClock,
-                    roadmapProvider: () => roadmapContent,
+                    // #4901: the body counter derives from the same current-milestone scope
+                    // as its frontmatter twin below (postCompletionRoadmapScope), not the
+                    // whole file, so the two writers cannot disagree on which
+                    // `## Progress` table they count.
+                    roadmapProvider: () => (roadmapContent !== null ? extractCurrentMilestone(roadmapContent, cwd) : null),
                     sourcePath: statePath,
                 });
                 stateContent = completeResult.content;

package/gsd-core/bin/lib/quick-batch-dispatch.cjs

@@ -26,6 +26,7 @@
  *
  * ADR-457 build-at-publish: compiled by tsc to gsd-core/bin/lib/quick-batch-dispatch.cjs.
  */
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planDocumentMod = require("./plan-document.cjs");
 const { parsePlanDocument } = planDocumentMod;
@@ -42,7 +43,7 @@ function parseQuickBatchArgs(args) {
         return { ok: false, reason: 'quick-batch args must be an array' };
     }
     if (args.includes('--discuss')) {
-        return { ok: false, reason: 'quick-batch does not support --discuss in v1 — use /gsd:quick --discuss per item instead' };
+        return { ok: false, reason: `quick-batch does not support --discuss in v1 — use ${(0, runtime_slash_cjs_1.runtimeCommand)(null, 'quick --discuss')} per item instead` };
     }
     if (args.includes('--full')) {
         return { ok: false, reason: 'quick-batch does not support --full in v1' };

package/gsd-core/bin/lib/report-parser.cjs

@@ -6,7 +6,7 @@ exports.parseTestReport = parseTestReport;
 const tap_parser_cjs_1 = require("./vendor/tap-parser.cjs");
 const saxes_cjs_1 = require("./vendor/saxes.cjs");
 exports.ReportFormat = {
-    Tap: 'tap', Junit: 'junit', SwiftTesting: 'swift-testing', Unittest: 'unittest', Unknown: 'unknown',
+    Tap: 'tap', Junit: 'junit', SwiftTesting: 'swift-testing', Unittest: 'unittest', GoTest: 'go-test', Unknown: 'unknown',
 };
 exports.TestStatus = { Passed: 'passed', Failed: 'failed', Skipped: 'skipped', Todo: 'todo' };
 function parseTap(output) {
@@ -247,7 +247,63 @@ function parseUnittest(output) {
     report.valid = report.issues.length === 0;
     return report;
 }
+/**
+ * `go test` text output (#5106). Plain console text, so the shape is matched by line:
+ *   --- FAIL: TestName (0.00s)          one per failed test (every test with -v; subtests indented)
+ *   FAIL\texample.com/pkg\t0.004s        one package summary per package, after that package's tests
+ *   FAIL\texample.com/pkg [build failed]   the package did not compile — nothing asserted anything
+ * A test's name carries no package, so each test is also known as `<package>.<name>`, attributed to
+ * the next package summary line. The same name failing in two packages is ambiguous until qualified.
+ * `go test -json` is not text and stays unsupported.
+ */
+const GO_TEST_RESULT = /^[ \t]*-{3} (PASS|FAIL|SKIP): (\S+) \(\d+(?:\.\d+)?s\)$/; // -{3}: not a literal fence, see frontmatter-fence-drift
+const GO_PACKAGE_LINE = /^(ok|FAIL|\?)[ \t]+(\S+)[ \t]+(?:\d+(?:\.\d+)?s\b|\(cached\)|\[([a-z ]+)\])/;
+function isGoTestOutput(output) {
+    if (/^TAP version \d+/.test(output.trimStart()))
+        return false;
+    return output.split(/\r?\n/).some((line) => GO_TEST_RESULT.test(line) || GO_PACKAGE_LINE.test(line));
+}
+function parseGoTest(output) {
+    const report = { format: exports.ReportFormat.GoTest, valid: true, tests: [], issues: [] };
+    let segment = [];
+    let packages = 0;
+    for (const line of output.split(/\r?\n/)) {
+        const result = GO_TEST_RESULT.exec(line);
+        if (result) {
+            const name = result[2];
+            const status = result[1] === 'FAIL' ? exports.TestStatus.Failed : result[1] === 'SKIP' ? exports.TestStatus.Skipped : exports.TestStatus.Passed;
+            if (!segment.some((test) => test.name === name && test.status === status)) {
+                segment.push({ name, identities: [name], group: null, groupIdentities: [], status });
+            }
+            continue;
+        }
+        const pkg = GO_PACKAGE_LINE.exec(line);
+        if (!pkg)
+            continue;
+        packages++;
+        const [, outcome, importPath, bracket] = pkg;
+        if (outcome === 'FAIL' && (bracket === 'build failed' || bracket === 'setup failed')) {
+            report.buildFailed = true;
+            report.issues.push(`go test package ${importPath} ${bracket}`);
+        }
+        else if (outcome === 'ok' && segment.some((test) => test.status === exports.TestStatus.Failed)) {
+            report.issues.push(`go test package ${importPath} is ok but its output reports a failed test`);
+        }
+        for (const test of segment)
+            test.identities.push(`${importPath}.${test.name}`);
+        report.tests.push(...segment);
+        segment = [];
+    }
+    if (packages === 0)
+        report.issues.push('Missing go test package summary');
+    if (segment.length > 0)
+        report.issues.push('go test results without a following package summary');
+    report.valid = report.issues.length === 0;
+    return report;
+}
 const adapters = [
+    // Before TAP: a run whose first package is fine begins `ok  <TAB>pkg`, which the TAP matcher reads as a point.
+    { matches: isGoTestOutput, parse: parseGoTest },
     { matches: (output) => /^(?:TAP version \d+|(?:not )?ok\b|1\.\.\d+|#)/.test(output.trimStart()), parse: parseTap },
     { matches: (output) => output.trimStart().startsWith('<'), parse: parseJunit },
     { matches: (output) => new RegExp(SWIFT_AGGREGATE.source, 'm').test(output), parse: parseSwiftTesting },

package/gsd-core/bin/lib/review-lane-invocation.cjs

@@ -31,6 +31,7 @@ exports.resolveTimeoutMs = resolveTimeoutMs;
 exports.nativeTimeoutToken = nativeTimeoutToken;
 exports.isEmptyReview = isEmptyReview;
 exports.fileRefPrompt = fileRefPrompt;
+exports.applyPromptOverride = applyPromptOverride;
 exports.artifactPaths = artifactPaths;
 exports.resolveLaneBudget = resolveLaneBudget;
 exports.resolveLanePlan = resolveLanePlan;
@@ -229,6 +230,45 @@ function fileRefPrompt(promptPath, repoRoot) {
         `review request against that absolute root. Output only the resulting markdown review. ` +
         `Do not edit any files.`);
 }
+/**
+ * Re-point a resolved plan at a different prompt file (`review-lane invoke --prompt-file`, #5049).
+ *
+ * The override carries a budget-trimmed prompt, so it has to land wherever THIS lane actually
+ * reads its prompt, and that differs by channel:
+ *   - `stdin`: the runner streams the file `plan.stdin` names.
+ *   - `argv-file-ref`: the prompt PATH is embedded in a sentence in argv (`fileRefPrompt`), already
+ *     expanded by the time an override can run. Swapping `plan.promptPath` alone changes nothing
+ *     the CLI reads, which is how the override was dropped silently for cursor, antigravity and
+ *     kimi-code.
+ *   - `argv`: the bare path is an argv element.
+ *   - `openai-http`: the runner reads `plan.promptPath`.
+ * Argv elements are matched whole (the file-ref sentence, or the bare path), never by substring,
+ * so an unrelated argument that merely contains the path is left alone. `promptPath` moves with
+ * argv: the antigravity handler re-derives the sentence it swaps from `plan.promptPath` and would
+ * otherwise stop recognising it. A plan that takes no prompt (`none`) is returned unchanged.
+ * Pure: returns a new plan and never mutates the one it is given.
+ */
+function applyPromptOverride(plan, promptPath, repoRoot) {
+    if (plan.transport !== 'spawn')
+        return { ...plan, promptPath };
+    if (plan.stdin)
+        return { ...plan, stdin: promptPath, promptPath };
+    const oldRef = fileRefPrompt(plan.promptPath, repoRoot);
+    const newRef = fileRefPrompt(promptPath, repoRoot);
+    let replaced = false;
+    const argv = plan.argv.map((a) => {
+        if (a === oldRef) {
+            replaced = true;
+            return newRef;
+        }
+        if (a === plan.promptPath) {
+            replaced = true;
+            return promptPath;
+        }
+        return a;
+    });
+    return replaced ? { ...plan, argv, promptPath } : plan;
+}
 /** Run-dir artifact paths. POSIX-joined: these are workflow-visible strings, not OS paths. */
 function artifactPaths(runDir, slug) {
     const base = String(runDir ?? '').replace(/\/+$/, '');

package/gsd-core/bin/lib/review-reviewer-selection.cjs

@@ -113,6 +113,22 @@ exports.KNOWN_REVIEWER_SLUGS = (() => {
         return [];
     }
 })();
+/**
+ * #5359: map a lane flag alias (`agy` for `--agy`) to its canonical slug via the
+ * descriptor roster's declared `flags` (same source as `review-lane explicit-from-argv`).
+ * Guarded like KNOWN_REVIEWER_SLUGS: a load failure degrades to the plain error.
+ */
+function laneSlugForAlias(name, lanes) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const roster = lanes ?? require('./review-lane-descriptor.cjs').REVIEWER_LANES;
+        // `l.slug !== name`: an undetected canonical slug (`--codex` flag) is not an alias.
+        return roster.find((l) => l.slug !== name && l.flags.includes(`--${name}`))?.slug;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Instance names are lowercase slugs that must not shadow a built-in slug. */
 exports.INSTANCE_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 function normalizeConfiguredDefaultReviewers(rawValue) {
@@ -239,7 +255,10 @@ function resolveReviewerSelection(input) {
         // Sorted so the error order does not depend on flag order on the command line.
         const missing = [...explicitFlags].filter((slug) => !detected.has(slug)).sort();
         for (const slug of missing) {
-            errors.push(`explicit reviewer '${slug}' is not available on this host`);
+            const canonical = laneSlugForAlias(slug, input.lanes);
+            errors.push(canonical
+                ? `explicit reviewer '${slug}' is a flag alias; pass its canonical slug '${canonical}'`
+                : `explicit reviewer '${slug}' is not available on this host`);
         }
         // Guarded on the error count as it stood BEFORE this branch, so the
         // aggregate message fires under exactly the conditions it did previously.

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

@@ -1075,6 +1075,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     // refusal below declines with the analyzer's own `missing_phase_details`
     // vocabulary and leaves ROADMAP.md byte-identical.
     let missingPhaseDetails = false;
+    const warnings = [];
     withPlanningLock(cwd, () => {
         // #3957 (B9.4): captured BEFORE any transform runs, so the write/report
         // decision below reflects whether the transforms actually changed
@@ -1190,6 +1191,16 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             }
             return text;
         });
+        // #4947: a word-prefixed Phase cell (`Phase 68`) is deliberately not a
+        // writable table target (#4247 — the read side ignores it too), but when the
+        // phase's heading section is still written the command reports
+        // `updated: true` and the unwritten Status cell looked like a silent bug.
+        // The row stays byte-identical; the output now says so.
+        const wordPrefixedCellRe = new RegExp(`^Phase\\s+${phasePattern}\\.?(?:\\s|$)`, 'i');
+        const progressTable = tableRowFound ? null : (0, markdown_table_cjs_1.findTableWithColumns)(gateActiveRegion, ['Phase', 'Status']);
+        if (progressTable && progressTable.rows.some((row) => wordPrefixedCellRe.test((row['Phase'] ?? '').trim()))) {
+            warnings.push(`Progress table row for phase ${formatDiagnosticToken(String(phaseNum))} was not updated: its Phase cell is word-prefixed ("Phase N"), and only a bare phase number (N or N.) is recognized. Edit that row by hand or rewrite the cell as the bare number.`);
+        }
         // Update plan count in phase detail section.
         // Three recognised forms (all tolerated; canonical template uses the first):
         //   `**Plans**: N plans`  — bold word + outer colon (gsd-core/templates/roadmap.md)
@@ -1247,6 +1258,13 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // wording, so it correctly falls through to arm 3 untouched. Kept as a
         // caller-side classifier (NOT seam grammar) reused below against the
         // `boldField` node's own parsed `value`.
+        // #4947: a value that is exactly `TBD` is the planner's own "no plans yet"
+        // marker, not an operator annotation — once plans exist it contradicts the
+        // checklist this verb inserts right under it. `TBD — note` keeps its note
+        // (row 5): on the bold path the note is the node's trailing span, which the
+        // caller checks is empty; on the plain path the note is part of the value,
+        // so the whole-value comparison already excludes it.
+        const isBareTbd = (value) => value.trim() === 'TBD';
         const isTemplatePlaceholder = (value) => {
             const trimmed = value.trim();
             return /^\[\s*Number of plans\b[\s\S]*\]$/i.test(trimmed);
@@ -1272,6 +1290,35 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             const m = value.match(/^\d+\s+plans?/i);
             return m ? m[0].length : -1;
         };
+        // #4947: the pending-plan clause a human or planner glues after the count
+        // (`; 2 gap-closure plans pending (48-18, 48-19)`) is DERIVED from the same
+        // plan/summary facts this verb already computes, so a completed plan left
+        // listed as pending contradicts the count the verb just wrote. The verb
+        // owns that one clause: ids that now have a SUMMARY.md are removed, the
+        // number is recounted, and an emptied clause is dropped. Everything else in
+        // the tail (`in 11 waves`, free prose) stays the operator's — a wave total
+        // does not change when a plan completes. A clause whose ids are not all
+        // plan ids (`(see backlog)`) is not provably derived, so it is left alone.
+        const summarizedPlanIds = new Set(phaseInfo.summaries
+            .map((summaryFile) => summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', ''))
+            .filter((id) => id !== ''));
+        const pendingClauseRe = /;[ \t]*(\d+)[ \t]+((?:[\w-]+[ \t]+)*?)plans?[ \t]+pending[ \t]*\(([^()\r\n]*)\)/i;
+        const planIdShape = /^\d+(?:\.\d+)?-\d+(?:\.\d+)?$/;
+        const reconcilePendingClause = (tail) => {
+            const m = pendingClauseRe.exec(tail);
+            if (!m)
+                return tail;
+            const ids = m[3].split(',').map((id) => id.trim());
+            if (ids.length === 0 || !ids.every((id) => planIdShape.test(id)))
+                return tail;
+            const stillPending = ids.filter((id) => !summarizedPlanIds.has(id));
+            if (stillPending.length === ids.length)
+                return tail;
+            const replacement = stillPending.length === 0
+                ? ''
+                : `; ${stillPending.length} ${m[2]}plan${stillPending.length === 1 ? '' : 's'} pending (${stillPending.join(', ')})`;
+            return tail.slice(0, m.index) + replacement + tail.slice(m.index + m[0].length);
+        };
         roadmapContent = replaceInCurrentMilestone(roadmapContent, planSectionPattern, (sectionText) => {
             const parsed = (0, planning_document_cjs_1.parsePlanningDoc)(sectionText, 'ROADMAP.md');
             if (!parsed.ok) {
@@ -1302,12 +1349,12 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
                 const plainFractionLen = fractionCountPrefixLength(plainValue);
                 const plainBareLen = bareCountPrefixLength(plainValue);
                 const plainCountPrefixLen = plainFractionLen >= 0 ? plainFractionLen : plainBareLen;
-                if (plainCountPrefixLen < 0 && !isTemplatePlaceholder(plainValue)) {
+                if (plainCountPrefixLen < 0 && !isTemplatePlaceholder(plainValue) && !isBareTbd(plainValue)) {
                     // Arm 3: freeform prose, TBD, a bracketed human annotation, or an
                     // empty value — leave the section exactly as it was.
                     return sectionText;
                 }
-                const plainSuffix = plainCountPrefixLen >= 0 ? plainValue.slice(plainCountPrefixLen) : '';
+                const plainSuffix = plainCountPrefixLen >= 0 ? reconcilePendingClause(plainValue.slice(plainCountPrefixLen)) : '';
                 const newPlainLine = `${indent}Plans:${spacing}${planCountText}${plainSuffix}`;
                 const start = plainMatch.index ?? sectionText.indexOf(whole);
                 return sectionText.slice(0, start) + newPlainLine + sectionText.slice(start + whole.length);
@@ -1320,7 +1367,11 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             const fractionPrefixLen = fractionCountPrefixLength(currentValue);
             const barePrefixLen = bareCountPrefixLength(currentValue);
             const countPrefixLen = fractionPrefixLen >= 0 ? fractionPrefixLen : barePrefixLen;
-            if (countPrefixLen < 0 && !isTemplatePlaceholder(currentValue)) {
+            const fieldNode = parsed.value.nodes.find((n) => n.id === fieldId);
+            const trailingText = fieldNode && fieldNode.kind === 'boldField'
+                ? parsed.value.source.slice(fieldNode.trailingSpan.start, fieldNode.trailingSpan.end)
+                : '';
+            if (countPrefixLen < 0 && !isTemplatePlaceholder(currentValue) && !(isBareTbd(currentValue) && trailingText.trim() === '')) {
                 // Arm 3: freeform prose, TBD, a bracketed human annotation, or an
                 // empty value — leave the section exactly as it was.
                 return sectionText;
@@ -1331,7 +1382,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             // `setFieldValue`'s valueSpan/trailingSpan split additionally preserves
             // any EM-DASH-separated trailing annotation (#2853) automatically — no
             // separate "preserve trailing" branch needed for that shape.
-            const suffix = countPrefixLen >= 0 ? currentValue.slice(countPrefixLen) : '';
+            const suffix = countPrefixLen >= 0 ? reconcilePendingClause(currentValue.slice(countPrefixLen)) : '';
             const newValueToWrite = planCountText + suffix;
             const staged = (0, planning_document_cjs_1.setFieldValue)(parsed.value, fieldId, newValueToWrite);
             if (!staged.ok) {
@@ -1490,7 +1541,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         verification_stale_check_indeterminate: verificationStaleCheckIndeterminate,
     };
     if (updated) {
-        output({ updated: true, ...computed }, raw, `${summaryCount}/${planCount} ${status}`);
+        output(warnings.length > 0 ? { updated: true, ...computed, warnings } : { updated: true, ...computed }, raw, `${summaryCount}/${planCount} ${status}`);
     }
     else if (missingPhaseDetails) {
         // #4247: honest refusal — the reason names the real condition (the