@opengsd/gsd-core 1.9.1 → 1.11.0

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

@@ -18,7 +18,14 @@
  *   5. "main"  (last-resort default)
  *
  * Every git subprocess is bounded with a timeout (≤ 30 s); on timeout/error
- * the resolver degrades gracefully to the next tier — it never throws.
+ * the resolver degrades gracefully to the next tier — it never throws. Tier 5
+ * is reachable two ways that `resolveBaseBranch()` alone cannot tell apart: a
+ * repository that genuinely has no candidate branch (every git query on tiers
+ * 2-4 completed and cleanly answered "nothing"), or a total resolution
+ * failure (some query timed out / could not run). `resolveBaseBranchDiagnostics()`
+ * distinguishes the two via `verified`; `cmdGitBaseBranch` surfaces the
+ * unverified case as a stderr diagnostic without changing its stdout contract
+ * (#3057 B4).
  *
  * Pure/testable: all I/O is injectable via the `deps` argument so unit
  * tests can run without touching the real filesystem or spawning real git.
@@ -31,8 +38,11 @@ exports.readConfigBaseBranch = readConfigBaseBranch;
 exports.trySymbolicRef = trySymbolicRef;
 exports.tryRemoteShow = tryRemoteShow;
 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"));
@@ -115,7 +125,8 @@ function tryRemoteShow(cwd, execGit) {
         const branch = m[1];
         // git emits "(unknown)" when the remote is offline but the local cache
         // resolved it; treat that as non-authoritative and fall through.
-        if (!branch || branch === '(unknown)')
+        // No `!branch ||` guard: m[1] comes from the `(\S+)` capture group above, so it is never empty.
+        if (branch === '(unknown)')
             return null;
         return branch;
     }
@@ -153,41 +164,70 @@ function tryLocalBranch(cwd, execGit) {
     }
 }
 /**
- * Resolve the default/base branch for the repository at `cwd`.
+ * Resolve the default/base branch for the repository at `cwd`, along with
+ * whether the tier-5 last-resort default (if reached) was verified.
  *
  * Consults the full precedence ladder and always returns a non-empty string.
  * Never throws.
  */
-function resolveBaseBranch(cwd, deps) {
-    const execGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
+function resolveBaseBranchDiagnostics(cwd, 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
+    // from git completing and cleanly reporting a negative answer (non-zero
+    // exit with no useful output, or exit 0 with empty stdout). Only the former
+    // means a tier's answer was never actually obtained. Wrapping execGit here
+    // observes every tier's calls uniformly without changing trySymbolicRef /
+    // tryRemoteShow / tryLocalBranch's own return contracts.
+    let anyGitFailure = false;
+    const execGit = (args, opts) => {
+        const r = rawExecGit(args, opts);
+        if (r.timedOut || r.error)
+            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 configured;
+        return { branch: configured, verified: true };
     // 2. symbolic-ref (fast, no network)
     const symref = trySymbolicRef(cwd, execGit);
     if (symref)
-        return symref;
+        return { branch: symref, verified: true };
     // 3. git remote show origin (authoritative when origin/HEAD unset)
     const remoteShow = tryRemoteShow(cwd, execGit);
     if (remoteShow)
-        return remoteShow;
+        return { branch: remoteShow, verified: true };
     // 4. Local branch existence
     const local = tryLocalBranch(cwd, execGit);
     if (local)
-        return local;
-    // 5. Last-resort default
-    return 'main';
+        return { branch: local, verified: true };
+    // 5. Last-resort default. `verified:false` when at least one tier-2/3/4
+    // execGit call timed out or failed to run — the default was never actually
+    // checked against this repository, it is just what's left after git could
+    // not answer (#3057 B4).
+    return { branch: 'main', verified: !anyGitFailure };
+}
+/**
+ * Resolve the default/base branch for the repository at `cwd`.
+ *
+ * Consults the full precedence ladder and always returns a non-empty string.
+ * Never throws. See {@link resolveBaseBranchDiagnostics} for a caller that
+ * needs to distinguish a verified answer from an unverified fallback.
+ */
+function resolveBaseBranch(cwd, deps) {
+    return resolveBaseBranchDiagnostics(cwd, deps).branch;
 }
 /**
  * Detect whether `cwd` sits inside a git worktree, and if so, return the
  * absolute path of the worktree root.
  */
-function gitWorktreeInfoInternal(cwd) {
+function gitWorktreeInfoInternal(cwd, deps) {
+    const execGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
     try {
-        const insideResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--is-inside-work-tree'], { cwd, timeout: 5000 });
+        const insideResult = execGit(['rev-parse', '--is-inside-work-tree'], { cwd, timeout: 5000 });
         if (insideResult.exitCode !== 0) {
             return { inside: false, worktreeRoot: null };
         }
@@ -195,7 +235,7 @@ function gitWorktreeInfoInternal(cwd) {
         if (insideStdout !== 'true') {
             return { inside: false, worktreeRoot: null };
         }
-        const rootResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--show-toplevel'], { cwd, timeout: 5000 });
+        const rootResult = execGit(['rev-parse', '--show-toplevel'], { cwd, timeout: 5000 });
         if (rootResult.exitCode !== 0) {
             return { inside: true, worktreeRoot: null };
         }
@@ -206,6 +246,106 @@ function gitWorktreeInfoInternal(cwd) {
         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`
@@ -213,7 +353,12 @@ function gitWorktreeInfoInternal(cwd) {
  * Called by workflows via `gsd_run query git.base-branch`.
  */
 function cmdGitBaseBranch(cwd, _args, deps) {
-    const branch = resolveBaseBranch(cwd, deps);
+    const { branch, verified } = resolveBaseBranchDiagnostics(cwd, deps);
+    if (!verified) {
+        const writeDiagnostic = deps?.writeDiagnostic ?? ((s) => process.stderr.write(s));
+        writeDiagnostic(`⚠ git-base-branch: defaulted to 'main' WITHOUT verifying against this repository — ` +
+            `a git query timed out or could not run. See #3057.\n`);
+    }
     const write = deps?.write ?? ((s) => process.stdout.write(s));
     write(branch + '\n');
     return branch;

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

@@ -16,6 +16,15 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateMod = require("./capability-state.cjs");
 const { isCapabilityActive } = capabilityStateMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- io.cjs is an export= CommonJS module
+const ioMod = require("./io.cjs");
+const { serializeForOutput } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- prompt-budget.cjs is an export= CommonJS module
+const promptBudget = require("./prompt-budget.cjs");
+// The repo's single token scale (phase-estimation.cts documents the rule: a
+// ratio between two measurement methods measures the methods, not the miss).
+// This module previously carried a private copy of the same chars/4 formula.
+const { estimateTokens } = promptBudget;
 /**
  * Return the standard disabled response object.
  */
@@ -52,8 +61,12 @@ function execGraphify(cwd, args, options = {}) {
             reason: GRAPHIFY_REASON.ENOENT,
         };
     }
-    // Timeout — seam exposes signal; spawnSync sets SIGTERM when killed by timeout.
-    if (result.signal === 'SIGTERM') {
+    // Timeout — result.timedOut is derived by the shared isSpawnTimeout predicate
+    // (shell-command-projection.cts), keyed on error.code === 'ETIMEDOUT' rather
+    // than signal === 'SIGTERM': Windows does not reliably report SIGTERM on a
+    // timeout kill, and an externally-delivered SIGTERM (error is null) is not
+    // a timeout at all.
+    if (result.timedOut) {
         return {
             exitCode: 124,
             stdout: result.stdout,
@@ -104,15 +117,28 @@ function checkGraphifyVersion() {
         }
     }
     // Strategy 2: fall back to python3 importlib.metadata
+    let pyPackageConfirmed = false;
     if (!versionStr) {
         const pyResult = (0, shell_command_projection_cjs_1.execTool)('python3', [
             '-c',
             'from importlib.metadata import version; print(version("graphifyy"))',
         ], { timeout: 5000 });
         if (!pyResult.error && pyResult.exitCode === 0 && pyResult.stdout) {
-            versionStr = pyResult.stdout;
+            versionStr = pyResult.stdout.trim();
+            pyPackageConfirmed = true; // importlib.metadata confirmed the package
         }
     }
+    else {
+        // #3020: verify the `graphify` binary on PATH is actually the graphifyy
+        // package — a foreign binary that happens to print a version-like string
+        // must not silently report compatible. If importlib.metadata cannot confirm
+        // the package, emit an identity warning even if the version looks right.
+        const pyVerify = (0, shell_command_projection_cjs_1.execTool)('python3', [
+            '-c',
+            'from importlib.metadata import version; print(version("graphifyy"))',
+        ], { timeout: 5000 });
+        pyPackageConfirmed = !pyVerify.error && pyVerify.exitCode === 0 && !!pyVerify.stdout;
+    }
     if (!versionStr) {
         return { version: null, compatible: null, warning: 'Could not determine graphify version' };
     }
@@ -120,9 +146,19 @@ function checkGraphifyVersion() {
     if (parts.length < 2 || parts.some(isNaN)) {
         return { version: versionStr, compatible: null, warning: 'Could not parse version: ' + versionStr };
     }
-    const compatible = parts[0] === 0 && parts[1] >= 4;
-    const warning = compatible ? null : 'graphify version ' + versionStr + ' is outside tested range >=0.4.0,<1.0';
-    return { version: versionStr, compatible, warning };
+    const versionInRange = parts[0] === 0 && parts[1] >= 4;
+    // #3020: if the `graphify` binary answered --version but the Python package
+    // graphifyy could not be confirmed, the tool identity is unverified — emit
+    // a warning naming the mismatch regardless of version-range compatibility.
+    if (!pyPackageConfirmed) {
+        return {
+            version: versionStr,
+            compatible: false,
+            warning: 'graphify version ' + versionStr + ' detected but the graphifyy Python package could not be confirmed — the `graphify` binary on PATH may be a different tool. Verify with: pip show graphifyy',
+        };
+    }
+    const warning = versionInRange ? null : 'graphify version ' + versionStr + ' is outside tested range >=0.4.0,<1.0';
+    return { version: versionStr, compatible: versionInRange, warning };
 }
 /**
  * Safely read and parse a JSON file. Returns null on missing file or parse error.
@@ -195,41 +231,118 @@ function seedAndExpand(graph, term, maxHops = 2) {
     const resultNodes = [...visitedNodes].map(id => nodeMap[id]).filter((n) => Boolean(n));
     return { nodes: resultNodes, edges: collectedEdges, seeds: new Set(seeds.map(n => n.id)) };
 }
+/**
+ * The single definition of `graphifyQuery`'s wire shape.
+ *
+ * Both the emitter (`graphifyQuery`'s return) and the budget estimator go
+ * through here, so `budget_estimate` measures the object the caller actually
+ * receives rather than a private approximation of it (#2738).
+ */
+function buildQueryResponse(term, core) {
+    return {
+        term,
+        nodes: core.nodes,
+        edges: core.edges,
+        total_nodes: core.nodes.length,
+        total_edges: core.edges.length,
+        trimmed: core.trimmed,
+        // Budget outcome (#2738) — only present when a budget was requested
+        ...(core.budget ? { budget_met: core.budget.met, budget_estimate: core.budget.estimate } : {}),
+    };
+}
 /**
  * Apply token budget by dropping edges by confidence tier (D-04, D-05, D-06).
- * Token estimation: Math.ceil(JSON.stringify(obj).length / 4).
  * Drop order: AMBIGUOUS -> INFERRED -> EXTRACTED.
+ *
+ * The estimate measures the response **as emitted** — `serializeForOutput()`
+ * over the same object `graphifyQuery` returns, pretty-printed and including
+ * the wrapper keys. Measuring a compact `{nodes, edges}` instead understates
+ * the payload the caller receives, which makes `budget_met` a confident claim
+ * about a payload nobody is handed (#2738).
+ *
+ * `term` participates in the emitted bytes, so it is threaded through; the
+ * default keeps direct unit calls on the same wire shape, minus those bytes.
  */
-function applyBudget(result, budgetTokens) {
-    if (!budgetTokens)
+function applyBudget(result, budgetTokens, term = '') {
+    // == null (not truthiness): --budget 0 is a valid parsed budget the router
+    // forwards, and treating it as "no budget" silently returns the unbounded
+    // result — the same silent-non-application defect class as #974/#2738.
+    //
+    // Number.isFinite additionally keeps NaN out of the comparisons below, where
+    // every `estimate <= NaN` is false: the loop would strip all three tiers and
+    // return a seeds-only payload indistinguishable from a legitimate aggressive
+    // trim. The CLI cannot reach that state — graphify-command-router rejects a
+    // non-numeric --budget before this is called — but graphifyQuery and
+    // applyBudget are module-level entry points a future caller could reach
+    // without that validation. Infinity routes here too, and deliberately: an
+    // unbounded budget is not a budget.
+    if (budgetTokens == null || !Number.isFinite(budgetTokens))
         return result;
     const CONFIDENCE_ORDER = ['AMBIGUOUS', 'INFERRED', 'EXTRACTED'];
     let edges = [...result.edges];
     let omitted = 0;
-    const estimateTokens = (obj) => Math.ceil(JSON.stringify(obj).length / 4);
+    // Nodes that survive a given edge set: edge-reachable, plus seeds (always kept)
+    const survivingNodes = (edgeSet) => {
+        const reachableNodes = new Set();
+        for (const edge of edgeSet) {
+            reachableNodes.add(edge.source);
+            reachableNodes.add(edge.target);
+        }
+        return result.nodes.filter(n => reachableNodes.has(n.id) || (result.seeds && result.seeds.has(n.id)));
+    };
+    const trimmedLabel = (dropped, unreachable) => dropped > 0 ? `[${dropped} edges omitted, ${unreachable} nodes unreachable]` : null;
+    /**
+     * Tokens of the response as `output()` will emit it.
+     *
+     * Self-referential by construction: `budget_estimate` is itself one of the
+     * emitted fields, so its own digit width counts toward the total. Resolved by
+     * iterating to a fixed point — the sequence is non-decreasing (a wider number,
+     * and `false` over `true`, can only add characters), so it settles in a couple
+     * of passes. The cap is a guard rather than an expectation, and it exits on the
+     * larger value: over-reporting is the safe direction for a budget signal;
+     * under-reporting is the defect this fixes.
+     */
+    const wireEstimate = (candidateNodes, candidateEdges, trimmed) => {
+        let est = 0;
+        for (let i = 0; i < 8; i++) {
+            const next = estimateTokens(serializeForOutput(buildQueryResponse(term, {
+                nodes: candidateNodes,
+                edges: candidateEdges,
+                trimmed,
+                budget: { met: est <= budgetTokens, estimate: est },
+            })));
+            if (next === est)
+                break;
+            est = next;
+        }
+        return est;
+    };
+    // Estimate against the post-pruning node set after each tier removal, so a
+    // removal that already fits (once orphaned nodes are excluded) stops the loop
+    // instead of dropping the next, higher-confidence tier too (#2738).
+    let nodes = survivingNodes(edges);
+    let estimate = wireEstimate(nodes, edges, trimmedLabel(omitted, result.nodes.length - nodes.length));
     for (const tier of CONFIDENCE_ORDER) {
-        if (estimateTokens({ nodes: result.nodes, edges }) <= budgetTokens)
+        if (estimate <= budgetTokens)
             break;
         const before = edges.length;
         // Check both confidence and confidence_score field names (Open Question 1)
         edges = edges.filter(e => (e.confidence || e.confidence_score) !== tier);
         omitted += before - edges.length;
+        nodes = survivingNodes(edges);
+        estimate = wireEstimate(nodes, edges, trimmedLabel(omitted, result.nodes.length - nodes.length));
     }
-    // Find unreachable nodes after edge removal
-    const reachableNodes = new Set();
-    for (const edge of edges) {
-        reachableNodes.add(edge.source);
-        reachableNodes.add(edge.target);
-    }
-    // Always keep seed nodes
-    const nodes = result.nodes.filter(n => reachableNodes.has(n.id) || (result.seeds && result.seeds.has(n.id)));
     const unreachable = result.nodes.length - nodes.length;
     return {
         nodes,
         edges,
-        trimmed: omitted > 0 ? `[${omitted} edges omitted, ${unreachable} nodes unreachable]` : null,
+        trimmed: trimmedLabel(omitted, unreachable),
         total_nodes: nodes.length,
         total_edges: edges.length,
+        // Seeds are retained unconditionally, so the seed set is a floor the
+        // reduction cannot go below — report the outcome instead of hiding a miss (#2738)
+        budget_met: estimate <= budgetTokens,
+        budget_estimate: estimate,
     };
 }
 // ─── Public API ──────────────────────────────────────────────────────────────
@@ -303,17 +416,19 @@ function graphifyQuery(cwd, term, options = {}) {
         return { error: 'Failed to parse graph.json' };
     }
     let result = seedAndExpand(graph, term);
-    if (options.budget) {
-        result = applyBudget(result, options.budget);
+    if (options.budget != null) {
+        result = applyBudget(result, options.budget, term);
     }
-    return {
-        term,
+    // Same builder the estimator measured, so budget_estimate describes exactly
+    // these bytes (#2738).
+    return buildQueryResponse(term, {
         nodes: result.nodes,
         edges: result.edges,
-        total_nodes: result.nodes.length,
-        total_edges: result.edges.length,
         trimmed: 'trimmed' in result ? (result.trimmed || null) : null,
-    };
+        budget: 'budget_met' in result
+            ? { met: result.budget_met, estimate: result.budget_estimate }
+            : undefined,
+    });
 }
 /**
  * Return status information about the knowledge graph (STAT-01, STAT-02).

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

@@ -27,9 +27,16 @@ 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
 const ioMod = require("./io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
+const frontmatterMod = require("./frontmatter.cjs");
 const { output } = ioMod;
+const { transliterateForSlug } = coreUtilsMod;
+const { stripFrontmatter } = frontmatterMod;
 // ─── Utilities ──────────────────────────────────────────────────────────────
 function readOptional(filePath) {
     try {
@@ -43,7 +50,11 @@ function zeroPad(n, width = 2) {
     return String(n).padStart(width, '0');
 }
 function slugify(title) {
-    return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    // #2848: transliterate Cyrillic to ASCII before the filter so a non-Latin
+    // title does not collapse to an empty slug. The shared primitive keeps this
+    // in sync with generateSlugInternal. slugify's DISTINCT contract is preserved:
+    // single leading/trailing hyphen strip (/^-|-$/), and NO 60-char truncation.
+    return transliterateForSlug(title).replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
 }
 // ─── GSD-2 Parser ───────────────────────────────────────────────────────────
 /**
@@ -116,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 [];
@@ -218,9 +235,22 @@ function buildPlanMd(task, phasePrefix, planPrefix, phaseSlug, milestoneTitle) {
  */
 function buildSummaryMd(task, phasePrefix, planPrefix) {
     const raw = task.summary || '';
-    // Strip GSD-2 frontmatter block (--- ... ---) if present
-    const bodyMatch = raw.match(/^---[\s\S]*?---\n+([\s\S]*)$/);
-    const body = bodyMatch ? bodyMatch[1].trim() : raw.trim();
+    // Strip the GSD-2 frontmatter block via the canonical primitive (#2703). The
+    // previous local regex required a bare `\n` after the closing `---`, so a
+    // CRLF-authored summary never matched, fell through to the untouched-raw
+    // branch, and had its frontmatter emitted a second time inside the body of
+    // the document this function then wrapped in a fresh v1 block.
+    //
+    // `extractFrontmatter` — which the issue names — returns only the parsed
+    // object and never the body, so it cannot serve this call site;
+    // `stripFrontmatter` is the same module's canonical body primitive.
+    //
+    // `once` is load-bearing. A GSD-2 summary is an arbitrary user-authored
+    // document, not a GSD artefact with a known frontmatter-doubling failure
+    // mode, so a body opening with a thematic-break-delimited section
+    // (`---` / heading / `---`) is far likelier than a corrupt second header —
+    // and the default greedy loop would delete it without a trace.
+    const body = stripFrontmatter(raw, { once: true }).trim();
     return [
         '---',
         `phase: "${phasePrefix}"`,
@@ -271,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';