@opengsd/gsd-core 1.10.0 → 1.11.0

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

@@ -16,6 +16,7 @@ const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const validate_cjs_1 = require("./validate.cjs");
+const text_lines_cjs_1 = require("./text-lines.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const unusableInputMod = require("./unusable-input.cjs");
 const { UNUSABLE_REASON, warnUnusableInput } = unusableInputMod;
@@ -83,7 +84,7 @@ const UNTERMINATED_KEY_THRESHOLD = 2;
  * has a false-positive class the other closes.
  */
 function isFrontmatterShaped(region) {
-    const lines = region.split(/\r?\n/).filter((line) => line.trim() !== '');
+    const lines = (0, text_lines_cjs_1.splitLines)(region).filter((line) => line.trim() !== '');
     if (lines.length === 0)
         return false;
     return lines.every((line) => (/^\s*[a-zA-Z0-9_-]+:/.test(line) // key: value
@@ -91,6 +92,80 @@ function isFrontmatterShaped(region) {
         || /^\s+\S/.test(line) // indented continuation of a nested value
     ));
 }
+/**
+ * #3257: a Symbol-keyed channel that carries full-line (column-0 `#`) YAML
+ * comments through a parse → reconstruct round-trip. Comments are otherwise
+ * unrepresentable on the Frontmatter object (Record<string, ...>) and were
+ * silently dropped by reconstructFrontmatter. The Symbol is invisible to
+ * Object.entries / Object.keys / JSON.stringify / for-in, so every existing
+ * reader is unchanged; only reconstructFrontmatter reads it. Leading comments
+ * are attached to the top-level key that follows them; comments after the last
+ * key go to `trailing`. Only set when a comment is actually seen, so comment-less
+ * frontmatter parses byte-identically to before.
+ */
+const FULL_LINE_COMMENTS = Symbol('fullLineComments');
+/**
+ * Unescape the interior of a YAML double-quoted scalar — the exact inverse of
+ * `escapeDoubleQuoted` (#3497). The writer has escaped `\`/`"`/`\n`/`\t`/`\r`/
+ * `\xHH` since #1779, but the reader only stripped the delimiters, so
+ * parse(serialize(x)) ≠ x for any quoted scalar carrying a `"` or `\`: each
+ * read-modify-write round-trip doubled the backslashes (b → 2b+1), growing a
+ * repeatedly-synced field — and its document — without bound until tooling
+ * OOMed. Recognized escapes decode per YAML double-quoted semantics; an
+ * unrecognized `\c` is kept literally (backslash + char), matching the
+ * strip-only behavior hand-authored files had before this fix.
+ */
+function unescapeDoubleQuoted(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch !== '\\' || i === s.length - 1) {
+            out += ch;
+            continue;
+        }
+        const next = s[++i];
+        if (next === '\\' || next === '"') {
+            out += next;
+        }
+        else if (next === 'n') {
+            out += '\n';
+        }
+        else if (next === 't') {
+            out += '\t';
+        }
+        else if (next === 'r') {
+            out += '\r';
+        }
+        else if (next === 'x') {
+            const hex = s.slice(i + 1, i + 3);
+            if (/^[0-9a-fA-F]{2}$/.test(hex)) {
+                out += String.fromCharCode(parseInt(hex, 16));
+                i += 2;
+            }
+            else {
+                out += '\\x'; // not \xHH — keep literally
+            }
+        }
+        else {
+            out += '\\' + next; // unrecognized escape — keep literally
+        }
+    }
+    return out;
+}
+/**
+ * Strip the quote delimiters off a parsed YAML scalar, un-escaping the interior
+ * when the scalar is double-quoted (#3497 — the parse-side complement of
+ * `escapeDoubleQuoted`). Single-quoted scalars keep the historical strip-only
+ * behavior (the writer never emits them; `''` → `'` folding is out of scope).
+ * A scalar wrapped in double quotes un-escapes; anything else keeps the exact
+ * prior delimiter-strip behavior, including a stray unpaired boundary quote.
+ */
+function parseQuotedScalar(value) {
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        return unescapeDoubleQuoted(value.slice(1, -1));
+    }
+    return value.replace(/^["']|["']$/g, '');
+}
 /**
  * Parse one already-delimited YAML region into a Frontmatter object.
  *
@@ -100,12 +175,20 @@ function isFrontmatterShaped(region) {
  */
 function parseYamlRegion(yaml) {
     const frontmatter = {};
-    const lines = yaml.split(/\r?\n/);
+    const lines = (0, text_lines_cjs_1.splitLines)(yaml);
+    // #3257: pending column-0 full-line comments, attached to the next top-level key.
+    let pendingComments = [];
+    let commentChannel;
     const stack = [{ obj: frontmatter, key: null, indent: -1 }];
     for (const line of lines) {
         // Skip empty lines
         if (line.trim() === '')
             continue;
+        // #3257: capture column-0 full-line comments; attach them to the next top-level key.
+        if (/^#/.test(line)) {
+            pendingComments.push(line);
+            continue;
+        }
         // Calculate indentation (number of leading spaces)
         const indentMatch = line.match(/^(\s*)/);
         const indent = indentMatch ? indentMatch[1].length : 0;
@@ -118,6 +201,13 @@ function parseYamlRegion(yaml) {
         const keyMatch = line.match(/^(\s*)([a-zA-Z0-9_-]+):\s*(.*)/);
         if (keyMatch) {
             const key = keyMatch[2];
+            // #3257: attach any pending comments to this (top-level) key.
+            if (pendingComments.length) {
+                if (!commentChannel)
+                    commentChannel = { leading: {}, trailing: [] };
+                commentChannel.leading[key] = pendingComments;
+                pendingComments = [];
+            }
             const value = keyMatch[3].trim();
             if (value === '' || value === '[') {
                 // Key with no value or opening bracket — could be nested object or array
@@ -134,13 +224,13 @@ function parseYamlRegion(yaml) {
             }
             else {
                 // Simple key: value
-                current.obj[key] = value.replace(/^["']|["']$/g, '');
+                current.obj[key] = parseQuotedScalar(value);
                 current.key = null;
             }
         }
         else if (line.trim().startsWith('- ')) {
             // Array item
-            const itemValue = line.trim().slice(2).replace(/^["']|["']$/g, '');
+            const itemValue = parseQuotedScalar(line.trim().slice(2));
             // If current context is an empty object, convert to array
             if (typeof current.obj === 'object' && !Array.isArray(current.obj) && Object.keys(current.obj).length === 0) {
                 // Find the key in parent that points to this object and convert it
@@ -160,6 +250,15 @@ function parseYamlRegion(yaml) {
             }
         }
     }
+    // #3257: trailing comments (after the last key) + attach the channel if any comment was seen.
+    if (pendingComments.length) {
+        if (!commentChannel)
+            commentChannel = { leading: {}, trailing: [] };
+        commentChannel.trailing = pendingComments;
+    }
+    if (commentChannel) {
+        frontmatter[FULL_LINE_COMMENTS] = commentChannel;
+    }
     return frontmatter;
 }
 /**
@@ -273,9 +372,17 @@ function scalarNeedsDoubleQuoting(s) {
 }
 function reconstructFrontmatter(obj) {
     const lines = [];
+    // #3257: read the full-line-comment channel (set by parseYamlRegion when comments
+    // were present). Object.entries skips the Symbol key, so the data loop is unchanged.
+    const commentChannel = obj[FULL_LINE_COMMENTS];
     for (const [key, value] of Object.entries(obj)) {
         if (value === null || value === undefined)
             continue;
+        // #3257: re-emit this key's leading full-line comments before the key itself.
+        const leading = commentChannel?.leading[key];
+        if (leading)
+            for (const c of leading)
+                lines.push(c);
         if (Array.isArray(value)) {
             if (value.length === 0) {
                 lines.push(`${key}: []`);
@@ -348,8 +455,35 @@ function reconstructFrontmatter(obj) {
             }
         }
     }
+    // #3257: re-emit any trailing full-line comments (those after the last key).
+    if (commentChannel?.trailing?.length) {
+        for (const c of commentChannel.trailing)
+            lines.push(c);
+    }
     return lines.join('\n');
 }
+/**
+ * #3257: copy the full-line-comment channel from `source` onto `target`, filtering
+ * `leading` to keys still present in `target` (a deleted key's annotation goes with
+ * it — AC5). No-op when `source` carries no channel. Consumers that rebuild their
+ * target object fresh (syncStateFrontmatter builds derivedFm via buildStateFrontmatter
+ * and copies keys with Object.keys, which skips the Symbol) MUST call this before
+ * reconstructFrontmatter, or the channel parseYamlRegion attached to the extracted
+ * source is lost.
+ */
+function propagateCommentChannel(source, target) {
+    const channel = source[FULL_LINE_COMMENTS];
+    if (!channel)
+        return;
+    const filtered = { leading: {}, trailing: channel.trailing };
+    for (const [key, comments] of Object.entries(channel.leading)) {
+        if (key in target)
+            filtered.leading[key] = comments;
+    }
+    if (filtered.trailing.length || Object.keys(filtered.leading).length) {
+        target[FULL_LINE_COMMENTS] = filtered;
+    }
+}
 /**
  * Slice a frontmatter YAML body into per-top-level-key raw text segments. Each segment
  * runs from a column-0 `key:` line through the line before the next column-0 key (or the
@@ -359,7 +493,7 @@ function reconstructFrontmatter(obj) {
  * not modify (e.g. must_haves.artifacts / .prohibitions).
  */
 function sliceTopLevelFrontmatterSegments(yaml) {
-    const lines = yaml.split(/\r?\n/);
+    const lines = (0, text_lines_cjs_1.splitLines)(yaml);
     const segments = [];
     let current = null;
     for (const line of lines) {
@@ -423,7 +557,7 @@ function spliceFrontmatter(content, newObj) {
         // unrelated `must_haves` block. Keys absent from the original (genuinely new) are
         // regenerated and appended; keys absent from `newObj` are preserved (never silently
         // deleted by a set/merge).
-        const fmLines = fmBlock.split(/\r?\n/);
+        const fmLines = (0, text_lines_cjs_1.splitLines)(fmBlock);
         const inner = fmLines.slice(1, -1).join('\n'); // drop the opening `---` and closing `---`
         let originalParsed;
         try {
@@ -504,27 +638,27 @@ function parseMustHavesBlock(content, blockName) {
     if (!fmMatch)
         return [];
     const yaml = fmMatch[1];
-    // Find must_haves: first to detect its indentation level
-    const mustHavesMatch = yaml.match(/^(\s*)must_haves:\s*$/m);
-    if (!mustHavesMatch)
+    const yamlLines = (0, text_lines_cjs_1.splitLines)(yaml);
+    // Find must_haves: first to detect its indentation level. Split-then-scan
+    // (rather than a whole-string /m match) so a CRLF or blank-line boundary
+    // can never be absorbed into the indent capture (#3360) — see
+    // .gsd/phase/chore-3413-text-lines-seam/40-design.md.
+    const mustHavesLinePattern = /^(\s*)must_haves:\s*$/;
+    const mustHavesLineIndex = yamlLines.findIndex((line) => mustHavesLinePattern.test(line));
+    if (mustHavesLineIndex === -1)
         return [];
-    const mustHavesIndent = mustHavesMatch[1].length;
+    const mustHavesIndent = yamlLines[mustHavesLineIndex].match(/^(\s*)/)[1].length;
     // Find the block (e.g., "truths:", "artifacts:", "key_links:") under must_haves
     // It must be indented more than must_haves but we detect the actual indent dynamically
-    const blockPattern = new RegExp(`^(\\s+)${blockName}:\\s*$`, 'm');
-    const blockMatch = yaml.match(blockPattern);
-    if (!blockMatch)
+    const blockLinePattern = new RegExp(`^(\\s+)${blockName}:\\s*$`);
+    const blockLineIndex = yamlLines.findIndex((line) => blockLinePattern.test(line));
+    if (blockLineIndex === -1)
         return [];
-    const blockIndent = blockMatch[1].length;
+    const blockIndent = yamlLines[blockLineIndex].match(/^(\s*)/)[1].length;
     // The block must be nested under must_haves (more indented)
     if (blockIndent <= mustHavesIndent)
         return [];
-    // Find where the block starts in the yaml string
-    const blockStart = yaml.indexOf(blockMatch[0]);
-    if (blockStart === -1)
-        return [];
-    const afterBlock = yaml.slice(blockStart);
-    const blockLines = afterBlock.split(/\r?\n/).slice(1); // skip the header line
+    const blockLines = yamlLines.slice(blockLineIndex + 1); // skip the header line
     // List items are indented one level deeper than blockIndent
     // Continuation KVs are indented one level deeper than list items
     const items = [];
@@ -865,4 +999,5 @@ module.exports = {
     cmdFrontmatterSet,
     cmdFrontmatterMerge,
     cmdFrontmatterValidate,
+    propagateCommentChannel,
 };

package/gsd-core/bin/lib/gap-checker.cjs

@@ -24,14 +24,18 @@ const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const io = require("./io.cjs");
 const { output, error } = io;
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const phaseId = require("./phase-id.cjs");
-const { escapeRegex } = phaseId;
+const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningPaths, planningDir, findContextMdIn } = planningWorkspace;
 const decisions_cjs_1 = require("./decisions.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planScanMod = require("./plan-scan.cjs");
+const { scanPhasePlans } = planScanMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { scopeToPhase } = phaseIdMod;
 /**
  * Parse REQ-IDs from REQUIREMENTS.md content.
  *
@@ -91,7 +95,7 @@ function parseRequirements(reqMd) {
 }
 function detectCoverage(items, planText) {
     return items.map(it => {
-        const re = new RegExp('\\b' + escapeRegex(it.id) + '\\b');
+        const re = new RegExp('\\b' + (0, pattern_cjs_1.escapeRegex)(it.id) + '\\b');
         return {
             source: it.source,
             item: it.id,
@@ -152,6 +156,38 @@ const PHASE_REQ_RANGE_RE = /^(.+-)(\d+)\.\.(.+-)(\d+)$/;
  * against pathological input like `X-1..X-100000` ballooning the comparison set.
  */
 const MAX_PHASE_REQ_RANGE = 1000;
+/**
+ * Shape filter applied to `--phase-req-ids` tokens AFTER range expansion
+ * (#3189). ROADMAP `**Requirements:**` lines routinely carry prose trailing
+ * the real ID list — locked-decision annotations, ambiguity scores,
+ * prohibitions, dates — and the function's own contract says callers may pass
+ * that roadmap value through verbatim. Without a shape filter every prose word
+ * survives the whitespace split and is reported as an individually-missing
+ * requirement, drowning the real coverage signal.
+ *
+ * The filter is intentionally wider than `ID_PATTERN` (which mandates a hyphen
+ * and so would reject the hyphen-less `R1`..`R8` family real roadmaps use).
+ * Three load-bearing details (#3189):
+ *
+ *   1. The digit lookahead `(?=.*\d)` matters. Without it ALL-CAPS prose tokens
+ *      that appear in annotations (`LOCKED`, `TBD`-as-prose, `NONE`-as-prose)
+ *      would pass and still reach the report as fake IDs. Every real
+ *      requirement ID carries a digit (`R1`, `SEL-01`, `P1-P3`).
+ *   2. It MUST run after `expandPhaseReqIdToken`. Filtering before would
+ *      discard the range tokens themselves (`SEL-01..SEL-03` matches no
+ *      single-ID shape), silently undoing the #1269 / #1419 range expansion.
+ *   3. It is NOT reusable as `ID_PATTERN`. `ID_PATTERN` mandates a hyphen,
+ *      so it rejects `R1`..`R8` and would leave only range-shaped tokens
+ *      standing — a silently-empty report, which is worse.
+ *
+ * Accepts both hyphen-less digit-bearing IDs (`R1`, `R8`) and prefix-hyphen
+ * IDs (`REQ-01`, `SEL-01`, `BACK-07`), including multi-segment prefixes
+ * (`REQ2-01`). Rejects prose (`LOCKED`), punctuation (`—`, `##`, `+`),
+ * dates, version-likes (`0.12;`), backtick fragments, and any token still
+ * containing `.` (so invalid range tokens returned literal by
+ * `expandPhaseReqIdToken` are dropped rather than surfaced as fake IDs).
+ */
+const PHASE_REQ_ID_SHAPE_RE = /^(?=.*\d)[A-Z][A-Z0-9]*(?:[-_][A-Za-z0-9]+)*$/;
 /**
  * Expand a single `--phase-req-ids` token in place. If it is a valid ascending
  * same-prefix numeric range (`<PREFIX>-NN..<PREFIX>-MM`, identical prefix both
@@ -212,6 +248,15 @@ function expandPhaseReqIdToken(token) {
  * spanning more than MAX_PHASE_REQ_RANGE IDs) stays literal — no partial
  * expansion, no guessing.
  *
+ * ID-shape filter (#3189): STRICTLY AFTER range expansion, every token is
+ * filtered through `PHASE_REQ_ID_SHAPE_RE`. ROADMAP `**Requirements:**` lines
+ * routinely carry prose trailing the real ID list (locked-decision annotations,
+ * ambiguity scores, prohibitions, dates); without the filter every prose word
+ * would be reported as an individually-missing requirement. Tokens that cannot
+ * be requirement IDs (prose, punctuation, dates, invalid range tokens left
+ * literal by `expandPhaseReqIdToken`) are dropped; an input whose every token
+ * is dropped collapses to `null` (skip semantics).
+ *
  * Tolerates JSON-array-ish input (`["REQ-01","REQ-02"]`) since callers may pass
  * the roadmap value through verbatim.
  */
@@ -229,7 +274,12 @@ function normalizePhaseReqIds(rawVal) {
     const ids = v.split(/[\s,]+/).map(s => s.trim()).filter(Boolean);
     // Expand range tokens (#1269) per-token AFTER the split, preserving input order.
     const expanded = ids.flatMap(expandPhaseReqIdToken);
-    return expanded.length === 0 ? null : expanded;
+    // #3189: drop tokens that cannot be requirement IDs (prose, punctuation,
+    // dates, invalid range tokens left literal by expandPhaseReqIdToken). MUST
+    // run after expand so valid ranges still expand (filtering before would
+    // discard `SEL-01..SEL-03` itself, undoing #1269 / #1419).
+    const filtered = expanded.filter(t => PHASE_REQ_ID_SHAPE_RE.test(t));
+    return filtered.length === 0 ? null : filtered;
 }
 function runGapAnalysis(cwd, phaseDir, options = {}) {
     const phaseReqIds = normalizePhaseReqIds(options.phaseReqIds);
@@ -268,7 +318,13 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             phaseDirFiles = node_fs_1.default.readdirSync(absPhaseDir);
     }
     catch { /* unreadable */ }
-    const ctxFile = findContextMdIn(phaseDirFiles);
+    // #3511-class: scope the raw listing to this phase dir before the
+    // phase-numbered -CONTEXT.md predicate. `phaseDirFiles` itself stays raw —
+    // it is also reused below only as a `.length > 0` guard ahead of
+    // scanPhasePlans's own plan-sequence-numbered enumeration, a different
+    // grammar that must not be scoped by phase number.
+    const scopedPhaseDirFiles = scopeToPhase(phaseDirFiles, node_path_1.default.basename(absPhaseDir));
+    const ctxFile = findContextMdIn(scopedPhaseDirFiles);
     const ctxPath = ctxFile ? node_path_1.default.join(absPhaseDir, ctxFile) : null;
     const ctxMd = ctxPath ? node_fs_1.default.readFileSync(ctxPath, 'utf-8') : '';
     // Use extractDecisions so gap-checker can distinguish could-not-parse from none-present.
@@ -278,7 +334,12 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
     let planText = '';
     try {
         if (phaseDirFiles.length > 0) {
-            const files = phaseDirFiles.filter(f => /-PLAN\.md$/.test(f));
+            // #3183 (lint-plan-count-drift): source the live plan-file list from
+            // the single owner (scanPhasePlans) instead of a local `-PLAN\.md$`
+            // filter on the already-read listing — picks up bare PLAN.md, nested
+            // plans/, and excludes superseded plans, none of which the prior
+            // root-only exact-suffix filter did.
+            const files = scanPhasePlans(absPhaseDir).planFiles;
             planText = files.map(f => {
                 try {
                     return node_fs_1.default.readFileSync(node_path_1.default.join(absPhaseDir, f), 'utf-8');

package/gsd-core/bin/lib/git-base-branch.cjs

@@ -41,6 +41,8 @@ exports.tryLocalBranch = tryLocalBranch;
 exports.resolveBaseBranchDiagnostics = resolveBaseBranchDiagnostics;
 exports.resolveBaseBranch = resolveBaseBranch;
 exports.gitWorktreeInfoInternal = gitWorktreeInfoInternal;
+exports.phaseStartCommit = phaseStartCommit;
+exports.changedFilesSince = changedFilesSince;
 exports.cmdGitBaseBranch = cmdGitBaseBranch;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -244,6 +246,106 @@ function gitWorktreeInfoInternal(cwd, deps) {
         return { inside: false, worktreeRoot: null };
     }
 }
+// ─── Adapter 3: phase-start anchor + touched-file listing (issue #1953) ───────
+/**
+ * Resolve the commit that ADDED `<phaseDir>/*-PLAN.md` — the anchor commit
+ * marking when the phase began (see `.gsd/phase/feat-1953-complexity-triggered-
+ * refactor/42-router-contract.md`, "Touched-file anchor"). `phaseDir` is a
+ * project-relative path (backslashes are normalized unconditionally before
+ * building the pathspec, never via `path.sep` — matches the repo's
+ * cross-platform path-normalization convention).
+ *
+ * Bounded (`timeout: 15_000`), degrades to `null` on any failure or when no
+ * such commit exists (a phase never planned through git, a shallow clone).
+ * Never throws.
+ */
+function phaseStartCommit(cwd, phaseDir, execGit) {
+    const git = execGit ?? shell_command_projection_cjs_1.execGit;
+    try {
+        const normalizedPhaseDir = phaseDir.replace(/\\/g, '/');
+        const pathspec = `${normalizedPhaseDir}/*-PLAN.md`;
+        const r = git(['log', '--format=%H', '--diff-filter=A', '-1', '--', pathspec], { cwd, timeout: 15_000 });
+        if (r.exitCode !== 0 || !r.stdout)
+            return null;
+        const sha = r.stdout.trim();
+        return sha || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reject characters/sequences that have no legitimate use in a git revision
+ * expression reaching this module (a ref name, SHA, or `<ref>~N` / `<ref>^N`
+ * / `<ref>@{...}` navigation) but that a hostile `--since` value could use to
+ * confuse either the shell-out or a downstream reader: whitespace, ASCII
+ * control characters, and the option-shaped `?`, `*`, `[`, `\` characters
+ * that `git check-ref-format` also disallows in ref *names*. A leading `-`
+ * is rejected outright — that is the actual option-injection vector `--end-
+ * of-options` (below) already neutralizes, so this is belt-and-suspenders
+ * for older git. `..` is rejected because `sinceRef` is a single revision
+ * that this function itself turns into a range (`sinceRef..HEAD`); a
+ * `sinceRef` that already contains `..` can only produce a malformed or
+ * misleading range. A trailing `.lock` is rejected per `check-ref-format`.
+ *
+ * Deliberately NOT rejected: `~`, `^`, `:`, `@`, `{`, `}` — `check-ref-
+ * format` disallows these in a bare ref *name*, but this value is a git
+ * *revision expression*, and rejecting them would break entirely ordinary
+ * user input such as `HEAD~1`, `HEAD^`, or `main@{yesterday}`. None of
+ * these characters can reintroduce option parsing once `--end-of-options`
+ * is in effect, so allowing them costs nothing security-wise.
+ */
+function isSafeRevisionRef(ref) {
+    if (ref === '')
+        return false;
+    if (ref.startsWith('-'))
+        return false;
+    if (/[\x00-\x1f\x7f ?*[\\]/.test(ref))
+        return false;
+    if (ref.includes('..'))
+        return false;
+    if (ref.endsWith('.lock'))
+        return false;
+    return true;
+}
+/**
+ * List files changed between `sinceRef` and `HEAD`, NUL-delimited and
+ * quotepath-safe. Load-bearing details (see the router contract):
+ *   - `-z` and `-c core.quotepath=false` avoid git's lossy quote-and-escape
+ *     round-trip for non-ASCII paths;
+ *   - splitting on `NUL` (never `\n`) tolerates a filename containing a real
+ *     newline (git permits it);
+ *   - `sinceRef` is validated by `isSafeRevisionRef` AND the revision-range
+ *     argument is preceded by `--end-of-options`. A trailing `--` alone does
+ *     NOT stop git from option-parsing an argument that appears BEFORE it —
+ *     it only stops PATHSPEC interpretation of arguments AFTER it — so
+ *     `--since '--output=/tmp/pwn'` would otherwise become the argument
+ *     `--output=/tmp/pwn..HEAD`, which git accepts as an option and uses to
+ *     redirect diff output to an attacker-chosen path. `--end-of-options`
+ *     (git >= 2.24) is the correct fix: everything after it is parsed as a
+ *     revision or path, never as an option, regardless of leading `-`.
+ *
+ * Bounded (`timeout: 15_000`), degrades to `null` when `sinceRef` fails
+ * validation or the underlying git call fails (non-zero exit, timeout, or
+ * spawn error) — never throws. An empty result set (no files changed
+ * between the two revisions) is a valid, non-null answer: `[]`.
+ */
+function changedFilesSince(cwd, sinceRef, execGit) {
+    if (!isSafeRevisionRef(sinceRef))
+        return null;
+    const git = execGit ?? shell_command_projection_cjs_1.execGit;
+    try {
+        const r = git(['-c', 'core.quotepath=false', 'diff', '--name-only', '-z', '--end-of-options', `${sinceRef}..HEAD`, '--'], { cwd, timeout: 15_000 });
+        if (r.exitCode !== 0)
+            return null;
+        if (!r.stdout)
+            return [];
+        return r.stdout.split('\0').filter((f) => f.length > 0);
+    }
+    catch {
+        return null;
+    }
+}
 // ─── CLI entry point ──────────────────────────────────────────────────────────
 /**
  * CLI command: `gsd-tools git base-branch`

package/gsd-core/bin/lib/gsd2-import.cjs

@@ -27,6 +27,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const clock_cjs_1 = require("./clock.cjs");
+const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- core-utils.cjs is an export= CommonJS module
 const coreUtilsMod = require("./core-utils.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -126,6 +127,12 @@ function parseTaskMustHaves(content) {
 /**
  * Read all task plan files from a GSD-2 tasks/ directory.
  */
+// #3183 (ADR-3180 Decision 4(a) — bucket B, out of scope for the
+// scanPhasePlans migration): this reads a FOREIGN GSD-2 legacy project's own
+// `tasks/` directory convention (`T##-PLAN.md`) during a one-time import —
+// it is not this project's `.planning/phases/<phase>/` layout at all, has no
+// nested-plans/superseded-status concept, and scanPhasePlans's grammar
+// (which is scoped to GSD's OWN phase directories) does not apply here.
 function readTasksDir(tasksDir) {
     if (!node_fs_1.default.existsSync(tasksDir))
         return [];
@@ -294,7 +301,9 @@ function buildStateMd(phaseMap) {
     const currentEntry = phaseMap.find(p => !p.slice.done);
     const totalPhases = phaseMap.length;
     const donePhases = phaseMap.filter(p => p.slice.done).length;
-    const pct = totalPhases > 0 ? Math.round((donePhases / totalPhases) * 100) : 0;
+    // ADR-3180 D7: one owner for completion percent. clampPercent's 100 ceiling is
+    // unreachable here (donePhases is a subset of totalPhases) — the value is unchanged.
+    const pct = (0, phase_lifecycle_cjs_1.clampPercent)(donePhases, totalPhases);
     const currentPhaseNum = currentEntry ? zeroPad(currentEntry.phaseNum) : zeroPad(totalPhases);
     const currentSlug = currentEntry ? slugify(currentEntry.slice.title) : 'complete';
     const status = currentEntry ? 'Ready to plan' : 'All phases complete';

package/gsd-core/bin/lib/health-diagnostic-rules/agent-install.cjs

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Agent Install rule (Phase 11, #3309, ADR-3180 §8.2/§8.3/§8.5).
+ *
+ * One code, W010, ported behavior-preserving from `cmdValidateHealth`'s
+ * agent-install block (`src/verify.cts:1992-2027`). That block wraps a
+ * single `checkAgentsInstalled(_slashRuntime, cwd)` call in a try/catch that
+ * swallows any thrown exception silently ("agent check is non-blocking",
+ * `verify.cts:2025-2027`) and then branches on the SAME subject —
+ * "agent installation is incomplete" — across four mutually exclusive
+ * combinations of `missing_agents`/`incomplete_agents`, firing at most one
+ * `addIssue('warning', 'W010', ...)` per call. Per this phase's design doc
+ * ("Rejected alternatives" §3), these four sites are confirmed to be one
+ * subject varying only in trigger detail, not four subjects — W010 stays a
+ * single code.
+ *
+ * `snapshot.agentInstall` (`src/planning-snapshot.cts`'s `buildAgentInstallField`)
+ * already performs the try/catch this rule used to need: `scope` is
+ * `UNREADABLE` only when the scan itself threw, mirroring
+ * `cmdValidateHealth`'s silent catch — this rule reproduces that silence by
+ * returning no diagnostic for `UNREADABLE`, rather than inventing a new,
+ * more severe 5th case the original never had.
+ *
+ * Design: .gsd/phase/refactor-3309-health-diagnostic-rule-table/40-design.md
+ *         ("Rule table organization" — Agent installation group)
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- health-diagnostic-types.cjs is an export= CommonJS module
+const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
+const { SEVERITY, adviseRemedy } = healthDiagnosticMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("../planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+const package_identity_cjs_1 = require("../package-identity.cjs");
+/**
+ * `check(snapshot)` for W010 — see module header for the exact 4-way
+ * branching this ports from `verify.cts:1992-2027`, and its message/fix
+ * templates copied verbatim (only the interpolated `agentStatus.*` values
+ * differ per call).
+ */
+function checkAgentInstall(snapshot) {
+    const { value: status, scope } = snapshot.agentInstall;
+    // Mirrors verify.cts:2025-2027's try/catch around the checkAgentsInstalled
+    // call itself — a thrown scan is swallowed, not reported. `scope` here is
+    // UNREADABLE only in that same case (buildAgentInstallField's own catch).
+    if (scope === SCOPE.UNREADABLE)
+        return [];
+    if (status.agents_installed)
+        return [];
+    // verify.cts:1995 — zero agents installed at all.
+    if (status.installed_agents.length === 0) {
+        return [
+            {
+                code: 'W010',
+                severity: SEVERITY.WARNING,
+                message: `No GSD agents found in ${status.agents_dir} — Task(subagent_type="gsd-*") will fall back to general-purpose`,
+                remedy: adviseRemedy(`Run the GSD installer: npx ${package_identity_cjs_1.PACKAGE_NAME}@latest`),
+            },
+        ];
+    }
+    // verify.cts:2002 — some agents incomplete (missing a generated file), zero fully missing.
+    if (status.incomplete_agents.length > 0 && status.missing_agents.length === 0) {
+        return [
+            {
+                code: 'W010',
+                severity: SEVERITY.WARNING,
+                message: `Incomplete agent installs (missing generated file): ${status.incomplete_agents.join(', ')} — affected workflows may fall back to general-purpose`,
+                remedy: adviseRemedy(`Re-run the GSD installer to complete the install: npx ${package_identity_cjs_1.PACKAGE_NAME}@latest`),
+            },
+        ];
+    }
+    // verify.cts:2009 — both missing AND incomplete agents present.
+    if (status.incomplete_agents.length > 0) {
+        return [
+            {
+                code: 'W010',
+                severity: SEVERITY.WARNING,
+                message: `Missing ${status.missing_agents.length} GSD agents: ${status.missing_agents.join(', ')}; incomplete agent installs (missing generated file): ${status.incomplete_agents.join(', ')} — affected workflows will fall back to general-purpose`,
+                remedy: adviseRemedy(`Run the GSD installer: npx ${package_identity_cjs_1.PACKAGE_NAME}@latest`),
+            },
+        ];
+    }
+    // verify.cts:2017 — agents missing only (no incomplete).
+    return [
+        {
+            code: 'W010',
+            severity: SEVERITY.WARNING,
+            message: `Missing ${status.missing_agents.length} GSD agents: ${status.missing_agents.join(', ')} — affected workflows will fall back to general-purpose`,
+            remedy: adviseRemedy(`Run the GSD installer: npx ${package_identity_cjs_1.PACKAGE_NAME}@latest`),
+        },
+    ];
+}
+const RULES = [
+    {
+        code: 'W010',
+        severity: SEVERITY.WARNING,
+        description: 'GSD agent installation missing or incomplete',
+        repairable: false,
+        check: checkAgentInstall,
+    },
+];
+module.exports = { RULES };