@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -23,15 +23,19 @@ const node_fs_1 = __importDefault(require("node:fs"));
 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 { output, error, formatDiagnosticToken } = io;
+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.
  *
@@ -50,6 +54,17 @@ function parseRequirements(reqMd) {
     // The **ID** is extracted from the bullet text caller-side — the seam provides
     // the raw text; we parse the bold-ID prefix from it here.
     const boldIdRe = new RegExp(`^\\*\\*(${ID_PATTERN})\\*\\*\\s*(.*)$`);
+    // The shipped template (gsd-core/templates/requirements.md) writes
+    // `- [ ] **AUTH-01**: User can sign up` — a single separator delimiter
+    // between the bold ID and the description. Strip AT MOST ONE leading
+    // delimiter (plus its surrounding whitespace) before the final `.trim()`,
+    // mirroring roadmap-parser.cts's `stripLeadingDelimiter` delimiter set
+    // (em dash, en dash, colon, hyphen) — that helper is not exported, and its
+    // own `+`-quantified strip removes an entire delimiter RUN, which would
+    // also eat a second, meaningful marker (`**X-01**: -- weird` must keep the
+    // `--`), so the set is mirrored here with a single-occurrence match instead
+    // of reused verbatim.
+    const ONE_LEADING_DELIMITER_RE = /^\s*[—–:-]\s*/;
     for (const bullet of (0, markdown_sectionizer_cjs_1.iterateBullets)(reqMd)) {
         if (bullet.marker !== 'checkbox-unchecked' && bullet.marker !== 'checkbox-checked')
             continue;
@@ -61,7 +76,8 @@ function parseRequirements(reqMd) {
             continue;
         if (!seen.has(id)) {
             seen.add(id);
-            out.push({ id, text: (m[2] || '').trim() });
+            const rawText = m[2] || '';
+            out.push({ id, text: rawText.replace(ONE_LEADING_DELIMITER_RE, '').trim() });
         }
     }
     // Pipe-table-row path and separator-row skip stay caller-side
@@ -91,7 +107,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 +168,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 +260,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 +286,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);
@@ -240,6 +302,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             table: '',
             summary: 'workflow.post_planning_gaps disabled — skipping post-planning gap analysis',
             counts: { total: 0, covered: 0, uncovered: 0 },
+            phase_dir_read_error: null,
         };
     }
     const absPhaseDir = node_path_1.default.isAbsolute(phaseDir) ? phaseDir : node_path_1.default.join(cwd, phaseDir);
@@ -263,12 +326,25 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
     // Read the phase directory once; reuse the listing for both context detection
     // and plan-file enumeration (avoids redundant readdirSync calls).
     let phaseDirFiles = [];
+    // #3885 (ADR-3473 §8.5): the existsSync guard above already means a catch
+    // here is NEVER "genuinely absent" (ENOENT) — this directory exists, so any
+    // failure to list it is a real read error (EACCES/EIO/...) and must be
+    // named, not folded into the same `[]` an absent directory produces.
+    let phaseDirReadError = null;
     try {
         if (node_fs_1.default.existsSync(absPhaseDir))
             phaseDirFiles = node_fs_1.default.readdirSync(absPhaseDir);
     }
-    catch { /* unreadable */ }
-    const ctxFile = findContextMdIn(phaseDirFiles);
+    catch (err) {
+        phaseDirReadError = `Could not read phase directory ${formatDiagnosticToken(absPhaseDir)}: ${formatDiagnosticToken(err?.message ?? String(err))}`;
+    }
+    // #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 +354,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');
@@ -323,6 +404,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
                 table: formatGapTable(rows) + '\n' + coverageSummary + '\n\n' + mismatchMsg,
                 summary: coverageSummary + '; extracted 0 of N — possible format mismatch',
                 counts: { total: rows.length, covered, uncovered },
+                phase_dir_read_error: phaseDirReadError,
             };
         }
         return {
@@ -331,6 +413,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             table: mismatchMsg,
             summary: 'extracted 0 of N — possible format mismatch',
             counts: { total: 0, covered: 0, uncovered: 0 },
+            phase_dir_read_error: phaseDirReadError,
         };
     }
     // #1365: if no items at all, surface a clean no-check message.
@@ -347,6 +430,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             table: '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n',
             summary: 'no requirements or decisions to check',
             counts: { total: 0, covered: 0, uncovered: 0 },
+            phase_dir_read_error: phaseDirReadError,
         };
     }
     const rows = sortRows([
@@ -364,6 +448,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
         table: formatGapTable(rows) + '\n' + summary + '\n',
         summary,
         counts: { total: rows.length, covered, uncovered },
+        phase_dir_read_error: phaseDirReadError,
     };
 }
 function cmdGapAnalysis(cwd, args, raw) {

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

@@ -34,55 +34,134 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readConfigBaseBranch = readConfigBaseBranch;
+exports._readGitNested = _readGitNested;
+exports._readGitKey = _readGitKey;
 exports.trySymbolicRef = trySymbolicRef;
 exports.tryRemoteShow = tryRemoteShow;
 exports.tryLocalBranch = tryLocalBranch;
 exports.resolveBaseBranchDiagnostics = resolveBaseBranchDiagnostics;
 exports.resolveBaseBranch = resolveBaseBranch;
+exports.resolveProtectedBranchStatus = resolveProtectedBranchStatus;
 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"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoader = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const configuration_cjs_1 = require("./configuration.cjs");
+const security_cjs_1 = require("./security.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
-// ─── Helpers ──────────────────────────────────────────────────────────────────
+const { error, ERROR_REASON } = io;
+const { loadConfig: loadConfigSeam } = configLoader;
+/** Render a rejected config value for a diagnostic without throwing on exotic input. */
+function renderRejected(value) {
+    try {
+        return (0, security_cjs_1.sanitizeLabel)(JSON.stringify(value) ?? String(value));
+    }
+    catch {
+        return (0, security_cjs_1.sanitizeLabel)(String(value));
+    }
+}
+/** Nested-only read of `git.<field>`, mirroring `loadConfigResolved`'s `getNested`. */
+function _readGitNested(config, field) {
+    const git = config['git'];
+    if (git !== null && typeof git === 'object' && !Array.isArray(git)) {
+        return git[field];
+    }
+    return undefined;
+}
+/**
+ * Flat-then-nested read, mirroring `loadConfigResolved`'s own `get()`.
+ *
+ * Used for `base_branch` ONLY, and only because it HAS a legacy flat spelling:
+ * `normalizeLegacyKeys` normally hoists it away, so a flat key that SURVIVED
+ * normalization is one the migration refused (a non-object `git` section,
+ * #3760) and is the user's last remaining expression of intent.
+ *
+ * `protected_branches` deliberately does NOT use this. It is new in #3552 with
+ * no legacy form, so honouring a top-level spelling would invent an
+ * undocumented alias that silently outranks the canonical nested key
+ * (round-4 external review).
+ */
+function _readGitKey(config, field) {
+    if (config[field] !== undefined)
+        return config[field];
+    return _readGitNested(config, field);
+}
 /**
- * Safely look up `git.base_branch` from the project's config.json.
- * Returns the configured value (a non-empty, non-null string) or null.
+ * Read the effective root/workstream configuration once for branch policy.
+ *
+ * Production takes the `loadConfig` branch, with `persist: false` — this is a
+ * PREDICATE, invoked on every `execute-phase` and every `ship` run, and a
+ * question must not rewrite the file it is asking about. Without it, any project
+ * carrying a legacy flat key (`base_branch`, `branching_strategy`, `depth`, …)
+ * has `.planning/config.json` silently normalized and rewritten by a call whose
+ * entire contract is to answer a boolean (#3648 review Blocker 1).
+ *
+ * The `readFile` branch is a unit-test seam, NOT a second production path, and
+ * it is deliberately narrower than `loadConfig`. It covers exactly two of
+ * production's steps — `normalizeLegacyKeys`, then the flat-then-nested lookup
+ * — over a single `<cwd>/.planning/config.json`. It does NOT apply
+ * root/workstream `_deepMergeConfig`, builtin or `~/.gsd/defaults.json`
+ * defaults, or `mergeFederatedConfig`. Tests that assert on any of those must
+ * drive `loadConfig` instead; the seam's own tests are scoped to normalization
+ * and shape validation, which is all it reproduces (#3648 review Major 3).
  */
-function readConfigBaseBranch(planningDir, deps) {
-    const readFile = deps?.readFile ??
-        ((p) => { try {
-            return node_fs_1.default.readFileSync(p, 'utf8');
+function readEffectiveGitConfig(cwd, deps) {
+    let config = {};
+    if (deps?.readFile && !deps.loadConfig) {
+        const raw = deps.readFile(node_path_1.default.join(cwd, '.planning', 'config.json'));
+        if (raw) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    const { parsed: normalized } = (0, configuration_cjs_1.normalizeLegacyKeys)(parsed);
+                    config = {
+                        base_branch: _readGitKey(normalized, 'base_branch'),
+                        protected_branches: _readGitNested(normalized, 'protected_branches'),
+                    };
+                }
+            }
+            catch { /* malformed direct edit contributes no policy values */ }
         }
-        catch {
-            return null;
-        } });
-    const configPath = node_path_1.default.join(planningDir, 'config.json');
-    const raw = readFile(configPath);
-    if (!raw)
-        return null;
-    let cfg;
-    try {
-        cfg = JSON.parse(raw);
     }
-    catch {
-        return null;
+    else {
+        try {
+            config = (deps?.loadConfig ?? loadConfigSeam)(cwd, { persist: false });
+        }
+        catch { /* configuration loading is fail-soft for branch resolution */ }
     }
-    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg))
-        return null;
-    const top = cfg;
-    // Support both "git.base_branch" (nested) and "base_branch" (flat legacy)
-    const gitSection = top.git;
-    if (gitSection && typeof gitSection === 'object' && !Array.isArray(gitSection)) {
-        const nested = gitSection.base_branch;
-        if (typeof nested === 'string' && nested.trim())
-            return nested.trim();
+    const rawBaseBranch = config.base_branch;
+    const baseBranch = typeof rawBaseBranch === 'string' && rawBaseBranch.trim()
+        ? rawBaseBranch.trim()
+        : null;
+    // A protection predicate must not fail OPEN. `config-set` validation is
+    // bypassable by a direct edit of .planning/config.json, so one bad element
+    // discarding the whole list would silently answer "not protected" for names
+    // the user believes are protected — the exact failure #3552 exists to close,
+    // reintroduced through a different door (#3648 review Blocker 3). Drop only
+    // the bad elements, and report every rejection so it cannot pass unnoticed.
+    const rawProtectedBranches = config.protected_branches;
+    const protectedBranches = [];
+    const rejectedProtectedBranches = [];
+    if (Array.isArray(rawProtectedBranches)) {
+        for (const branch of rawProtectedBranches) {
+            if (typeof branch === 'string' && branch.trim() !== '') {
+                protectedBranches.push(branch.trim());
+            }
+            else {
+                rejectedProtectedBranches.push(renderRejected(branch));
+            }
+        }
     }
-    const flat = top.base_branch;
-    if (typeof flat === 'string' && flat.trim())
-        return flat.trim();
-    return null;
+    else if (rawProtectedBranches !== undefined && rawProtectedBranches !== null) {
+        // Not a list at all — contributes no names, but is still a misconfiguration.
+        rejectedProtectedBranches.push(renderRejected(rawProtectedBranches));
+    }
+    return { baseBranch, protectedBranches, rejectedProtectedBranches };
 }
 /**
  * Try `git symbolic-ref --short refs/remotes/origin/HEAD` (no network).
@@ -168,7 +247,7 @@ function tryLocalBranch(cwd, execGit) {
  * Consults the full precedence ladder and always returns a non-empty string.
  * Never throws.
  */
-function resolveBaseBranchDiagnostics(cwd, deps) {
+function resolveBaseBranchDiagnosticsWithConfig(cwd, configured, deps) {
     const rawExecGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
     // A genuine execGit failure (timeout, or the call could not even spawn —
     // e.g. git missing, surfaced as exitCode 127 with `error` set) is distinct
@@ -184,10 +263,7 @@ function resolveBaseBranchDiagnostics(cwd, deps) {
             anyGitFailure = true;
         return r;
     };
-    // Derive .planning dir relative to cwd (mirrors planningDir() in planning-workspace.cjs)
-    const planningDir = node_path_1.default.join(cwd, '.planning');
     // 1. Config override
-    const configured = readConfigBaseBranch(planningDir, deps);
     if (configured)
         return { branch: configured, verified: true };
     // 2. symbolic-ref (fast, no network)
@@ -208,6 +284,10 @@ function resolveBaseBranchDiagnostics(cwd, deps) {
     // not answer (#3057 B4).
     return { branch: 'main', verified: !anyGitFailure };
 }
+function resolveBaseBranchDiagnostics(cwd, deps) {
+    const { baseBranch } = readEffectiveGitConfig(cwd, deps);
+    return resolveBaseBranchDiagnosticsWithConfig(cwd, baseBranch, deps);
+}
 /**
  * Resolve the default/base branch for the repository at `cwd`.
  *
@@ -218,6 +298,19 @@ function resolveBaseBranchDiagnostics(cwd, deps) {
 function resolveBaseBranch(cwd, deps) {
     return resolveBaseBranchDiagnostics(cwd, deps).branch;
 }
+/** Resolve the base branch plus configured protected-branch extensions. */
+function resolveProtectedBranchStatus(cwd, currentBranch, deps) {
+    const effectiveConfig = readEffectiveGitConfig(cwd, deps);
+    const { branch: baseBranch, verified } = resolveBaseBranchDiagnosticsWithConfig(cwd, effectiveConfig.baseBranch, deps);
+    const protectedBranches = [...new Set([baseBranch, ...effectiveConfig.protectedBranches])];
+    return {
+        baseBranch,
+        protectedBranches,
+        rejectedProtectedBranches: effectiveConfig.rejectedProtectedBranches,
+        isProtected: protectedBranches.includes(currentBranch),
+        verified,
+    };
+}
 /**
  * Detect whether `cwd` sits inside a git worktree, and if so, return the
  * absolute path of the worktree root.
@@ -244,13 +337,157 @@ 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`
  * Resolves the default branch and writes it to stdout (raw string, newline-terminated).
  * Called by workflows via `gsd_run query git.base-branch`.
  */
-function cmdGitBaseBranch(cwd, _args, deps) {
+function cmdGitBaseBranch(cwd, args, deps) {
+    if (args[0] === '--is-protected') {
+        if (args.length > 2) {
+            error('Usage: git base-branch --is-protected [<branch>]', ERROR_REASON.USAGE);
+        }
+        const writeDiagnostic = deps?.writeDiagnostic ?? ((s) => process.stderr.write(s));
+        // `git branch --show-current` prints nothing on a detached HEAD, so the
+        // call sites legitimately pass an explicit empty string: no protected
+        // branch is named '', the answer is false, and that is not a fault worth
+        // reporting. The flag with NO argument is a different thing — a caller bug
+        // that `args[1] ?? ''` used to collapse into the detached-HEAD case. Same
+        // handling, but said out loud so the two can be told apart.
+        //
+        // This diagnostic deliberately does NOT state the answer. The empty branch
+        // matches no protected name, but the fail-closed guard below still renders
+        // `true` when the base branch could not be verified — so promising "false"
+        // here would contradict what this same call prints on stdout (#3648 review).
+        if (args.length < 2) {
+            writeDiagnostic(`⚠ git-base-branch: --is-protected was called without a branch argument; ` +
+                `treating it as an empty branch name. Pass the branch to test, ` +
+                `e.g. --is-protected "$CURRENT_BRANCH".\n`);
+        }
+        const status = resolveProtectedBranchStatus(cwd, args[1] ?? '', deps);
+        if (status.rejectedProtectedBranches.length > 0) {
+            writeDiagnostic(`⚠ git-base-branch: ignoring ${status.rejectedProtectedBranches.length} unusable ` +
+                `git.protected_branches entr${status.rejectedProtectedBranches.length === 1 ? 'y' : 'ies'} ` +
+                `(${status.rejectedProtectedBranches.join(', ')}) — each must be a non-empty branch name. ` +
+                `The remaining names are still enforced. See #3552.\n`);
+        }
+        // A protection guard must fail closed: if the base branch could not be
+        // verified against this repository (a git query timed out or failed to
+        // run — #3057 B4), report "protected" rather than silently trusting an
+        // unverified guess that might happen to not match the current branch.
+        const rendered = String(status.verified ? status.isProtected : true);
+        if (!status.verified) {
+            writeDiagnostic(`⚠ git-base-branch: --is-protected could not verify repository branch metadata; ` +
+                `defaulting to protected (fail-closed). See #3057.\n`);
+        }
+        const write = deps?.write ?? ((s) => process.stdout.write(s));
+        write(rendered + '\n');
+        return rendered;
+    }
+    if (args.length > 0) {
+        error(`Unknown flag for git.base-branch: ${args[0]}`, ERROR_REASON.USAGE);
+    }
     const { branch, verified } = resolveBaseBranchDiagnostics(cwd, deps);
     if (!verified) {
         const writeDiagnostic = deps?.writeDiagnostic ?? ((s) => process.stderr.write(s));

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';