@opengsd/gsd-core 1.17.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;
@@ -4230,7 +4335,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     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/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

package/gsd-core/bin/lib/runtime-artifact-conversion.cjs

@@ -2923,8 +2923,13 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
     // See DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT in CONTEXT.md.
     const posixTarget = (0, shell_command_projection_cjs_1.posixNormalize)(String(resolvedTarget));
     const posixHome = homeDir ? (0, shell_command_projection_cjs_1.posixNormalize)(String(homeDir)) : homeDir;
-    if (isGlobal && posixTarget.startsWith(posixHome) && !isOpencode) {
-        return '$HOME' + posixTarget.slice(posixHome.length) + '/';
+    // #5123: `startsWith` alone treats a SIBLING directory whose name begins with
+    // the home path (`/home/u2/cfg` under `/home/u`) as under home and yields the
+    // broken `$HOMEu2/cfg/`. Require a path boundary.
+    const underHome = typeof posixHome === 'string' && posixHome.length > 0
+        && (posixTarget === posixHome || posixTarget.startsWith(posixHome.endsWith('/') ? posixHome : `${posixHome}/`));
+    if (isGlobal && underHome && !isOpencode) {
+        return '$HOME' + posixTarget.slice(posixHome.length).replace(/^(?!\/)(?=.)/, '/') + '/';
     }
     if (!isGlobal && projectRelative) {
         // An explicit local config dir need not be the descriptor's conventional
@@ -2938,6 +2943,44 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
     }
     return `${posixTarget}/`;
 }
+/**
+ * #5123: retarget an installed artifact's `@` includes to the REAL install root.
+ * Driven by the runtime descriptor's hostBehaviors, never by a runtime name:
+ *
+ * - `defaultHomeIncludeRoot` (Copilot, Antigravity): their converters hard-code
+ *   the DEFAULT home into includes, so with `--config-dir` the payload lives
+ *   elsewhere and `@~/<root>/gsd-core/…` points at nothing. `@~/<root>/` and
+ *   `@$HOME/<root>/` become `@<pathPrefix>`. A default install (pathPrefix is
+ *   already `$HOME/<root>/`) is returned unchanged, so it stays byte-identical.
+ * - `retargetsGsdCoreProsePath` (Kimi): Kimi has no `@` include, so its prompt
+ *   converter turns `~/.claude/gsd-core` into the prose "GSD core", leaving
+ *   `@GSD core/x.md` pointing nowhere. A `GSD core/<path>` reference followed
+ *   by a path segment becomes the real `<pathPrefix>gsd-core/<path>`, with the
+ *   unsupported `@` dropped. Bare prose "GSD core" is not followed by `/`.
+ *
+ * `pathPrefix` is the install root as computePathPrefix derives it
+ * (`$HOME/…/` under HOME, otherwise absolute), with a trailing slash. Pure and
+ * idempotent: a second pass finds none of the literals it rewrites.
+ */
+function retargetInstalledIncludes(content, behaviors, pathPrefix) {
+    if (typeof content !== 'string' || content.length === 0)
+        return content;
+    if (typeof pathPrefix !== 'string' || !pathPrefix.endsWith('/'))
+        return content;
+    if (!behaviors)
+        return content;
+    let result = content;
+    if (behaviors.retargetsGsdCoreProsePath === true) {
+        result = result.replace(/@?GSD core\/(?=[a-z])/g, `${pathPrefix}gsd-core/`);
+    }
+    const home = behaviors.defaultHomeIncludeRoot;
+    if (typeof home === 'string' && home.length > 0 && pathPrefix !== `$HOME/${home}/`) {
+        result = result
+            .split(`@~/${home}/`).join(`@${pathPrefix}`)
+            .split(`@$HOME/${home}/`).join(`@${pathPrefix}`);
+    }
+    return result;
+}
 /** Return a safe project-relative prefix for a resolved install target. */
 function projectRelativePrefixFromProjectRoot(projectRoot, resolvedTarget) {
     if (typeof projectRoot !== 'string' || typeof resolvedTarget !== 'string')
@@ -3974,4 +4017,6 @@ module.exports = {
     _negotiatedDispatchIsolation,
     // #1521: canonical non-Claude runtime list for test files and tooling
     NON_CLAUDE_RUNTIMES,
+    // #5123: post-install include retarget (config-dir aware; Kimi prose path)
+    retargetInstalledIncludes,
 };

package/gsd-core/bin/lib/runtime-homes.cjs

@@ -40,6 +40,7 @@ exports.resolveConfigHomeFromDescriptor = resolveConfigHomeFromDescriptor;
 exports.resolveAntigravityGlobalDir = resolveAntigravityGlobalDir;
 exports.detectAntigravityDirAmbiguity = detectAntigravityDirAmbiguity;
 exports.resolveKimiGlobalDir = resolveKimiGlobalDir;
+exports.resolveGsdHome = resolveGsdHome;
 exports.resolveKimiHooksTomlDir = resolveKimiHooksTomlDir;
 exports.getGlobalConfigDir = getGlobalConfigDir;
 exports.resolveSkillsBaseFromDescriptor = resolveSkillsBaseFromDescriptor;
@@ -403,6 +404,23 @@ exports.NON_REGISTRY_CONFIG_HOME_DESCRIPTORS = [
  * through resolveConfigHomeFromDescriptor and have no `kind`/`name` shape.
  */
 exports.GSD_LOCATION_ENV_KEYS = ['GSD_HOME', 'GSD_AGENTS_DIR'];
+/**
+ * #5017: the ONE rule for the root of the GSD-owned store (`$GSD_HOME/.gsd/`:
+ * defaults.json, consent.json, capability overlays) — `GSD_HOME` when set and
+ * non-blank, otherwise the home directory. The config loader, the install-time
+ * resolvers, the installer's defaults writer and capability staging all call
+ * this, so one configuration gives one answer at install time, at dispatch time
+ * and in the staged capabilities. The hooks (cold-tree, no lib import) and the
+ * settings / new-project workflows (shell) carry the same rule inline; a test
+ * pins each of them to it.
+ *
+ * `fallbackHome` lets a caller that already holds an injected home directory
+ * (the install-time resolvers' test seam) keep using it when GSD_HOME is unset.
+ * A blank `GSD_HOME` is "unset": `''` must never become a relative store path.
+ */
+function resolveGsdHome(fallbackHome = node_os_1.default.homedir()) {
+    return process.env['GSD_HOME'] || fallbackHome;
+}
 /**
  * Resolve the directory holding the Kimi product's OWN native config.toml —
  * the file that product itself reads for providers/models/hooks/etc, and the

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -1131,6 +1131,8 @@ function _normalizeMd(content) {
 }
 function normalizeContent(filePath, content, opts = {}) {
     const encoding = opts.encoding ?? 'utf-8';
+    if (opts.verbatim === true)
+        return { content: content ?? '', encoding };
     const isMd = node_path_1.default.extname(filePath).toLowerCase() === '.md';
     let normalized;
     if (isMd) {

package/gsd-core/bin/lib/smart-entry.cjs

@@ -675,6 +675,28 @@ function actionsFor(situation, s, runtime = 'claude') {
     }
 }
 // ─── Summary line ─────────────────────────────────────────────────────────────
+function phaseSummary(s) {
+    const phase = s.current_phase;
+    // Preserve the milestone ordinal introduced by #5228 when it is known.
+    const at = phase === null ? -1 : s.milestone_phases.findIndex((id) => comparePhaseNum(id, phase) === 0);
+    if (at >= 0)
+        return `Phase ${at + 1} of ${s.milestone_phases.length}`;
+    const total = s.total_phases;
+    const legacy = `Phase ${phase ?? '?'} of ${total ?? '?'}`;
+    const roadmapTotal = s.roadmap_total_phases;
+    // Keep the recorded pair when roadmap counts are unavailable, or when the
+    // pair can describe a single milestone without changing its existing text.
+    if (phase === null || total === null || roadmapTotal === null || roadmapTotal <= 0
+        || (total === roadmapTotal && comparePhaseNum(phase, total) <= 0)) {
+        return legacy;
+    }
+    // When the recorded pair cannot safely describe this roadmap, label its
+    // counts separately rather than printing a mixed-scope ratio.
+    const roadmapDone = s.roadmap_completed_phases;
+    return roadmapDone === null
+        ? `Phase ${phase} (${roadmapTotal} roadmap phases)`
+        : `Phase ${phase} (${roadmapDone} of ${roadmapTotal} roadmap phases complete)`;
+}
 function buildSummary(situation, s) {
     switch (situation) {
         case 'no-project':
@@ -688,7 +710,7 @@ function buildSummary(situation, s) {
         case 'needs-first-phase':
             return 'Project initialized — plan your first phase';
         case 'planning':
-            return `${phasePosition(s)} — needs a plan`;
+            return `${phaseSummary(s)} — needs a plan`;
         case 'executing':
             return progressLine('executing', s);
         case 'verify-pending':
@@ -702,24 +724,10 @@ function buildSummary(situation, s) {
             return 'Unsure of state — showing progress';
     }
 }
-/**
- * "Phase N of M" for the current phase. N is the phase's 1-based position in
- * the current milestone's ordered phase list (#5228), so a milestone that
- * continues the numbering of an earlier one (phases 9-17) reads "Phase 1 of 9",
- * not "Phase 9 of 9". When the phase is not in that list (or the roadmap lists
- * none) the STATE.md figures are printed as recorded.
- */
-function phasePosition(s) {
-    const current = s.current_phase;
-    const at = current === null ? -1 : s.milestone_phases.findIndex((id) => comparePhaseNum(id, current) === 0);
-    if (at >= 0)
-        return `Phase ${at + 1} of ${s.milestone_phases.length}`;
-    return `Phase ${s.current_phase ?? '?'} of ${s.total_phases ?? '?'}`;
-}
 function progressLine(tail, s) {
     const parts = [];
     if (s.current_phase !== null && s.total_phases !== null) {
-        parts.push(phasePosition(s));
+        parts.push(phaseSummary(s));
     }
     else if (s.current_phase !== null) {
         parts.push(`Phase ${s.current_phase}`);