@opengsd/gsd-core 1.11.0 → 1.13.0

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

@@ -75,6 +75,215 @@ const bulletTitledColonRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([
  * shape without hardcoding the `D`.
  */
 const boldLeadInBulletRe = /^\s*-\s+\*\*[A-Z]+[0-9]*-[A-Za-z0-9]/m;
+/**
+ * #3939: a decision bullet's DECLARATION line — the `- **D-NN … **` bold lead-in
+ * the three grammars above anchor on — may wrap across a line break. Physical
+ * line breaks inside a bullet are markdown-insignificant, and GSD's own
+ * discuss-phase writer emits the wrapped shape whenever a decision title runs
+ * past the wrap column. All three grammars require the closing `**` in the same
+ * string as the `- **D-` anchor, so a wrapped declaration matched none of them
+ * and fell to the #1365 parse-miss guard, forcing `could-not-parse` (which
+ * hard-blocks `check.decision-coverage-plan`) on a well-formed CONTEXT.md.
+ *
+ * The repair is confined to how the LOGICAL bullet is assembled — the grammars
+ * themselves are untouched, so every single-line form parses exactly as before.
+ */
+const decisionBulletStartRe = /^\s*-\s+\*\*D-/;
+/**
+ * A line that opens a new BLOCK-LEVEL construct, and therefore terminates the
+ * bullet above it: a list marker of any family (`-`, `*`, `+`, `1.`, `1)`), an
+ * ATX heading, a blockquote, or a table row. Joining never reaches across one of
+ * these (nor across a blank/whitespace-only line, checked separately), so a
+ * declaration whose bold run genuinely never closes cannot absorb the block
+ * below it and get "closed" by an unrelated inline `**` — it stays a parse-miss
+ * and still fails loud, which #1365's contract requires.
+ *
+ * The four MARKER families demand trailing whitespace so that a continuation
+ * line opening with emphasis (`*in* the header.** …`) is text, not a bullet.
+ * The table-row alternative deliberately does not: CommonMark tables may open
+ * flush (`|Col1|Col2|`), and a leading `|` is never ordinary decision prose.
+ * A `- ` line at ANY indent stops the join: a deeper one is #3169 nested
+ * elaboration, which the main loop folds into the open decision itself.
+ *
+ * DELIBERATE DIVERGENCE from the sectionizer seam (ADR-1372): `iterateBullets`
+ * recognises only the `N. ` ordered-list form (`numberedRe`,
+ * src/markdown-sectionizer.cts), while this set also stops at the `N) ` form.
+ * That is intentional and one-directional — this regex answers "may the join
+ * cross this line?", where recognising MORE block openers is the conservative
+ * answer (a missed terminator can manufacture a decision; a spare one can only
+ * make a malformed bullet fail loud, which #1365 already wants). `N)` is a
+ * CommonMark ordered-list marker, so a join must not reach across it whether or
+ * not the seam's own bullet iterator yields it. Both forms are pinned by tests,
+ * and a drift test asserts the seam still does NOT treat `N)` as a bullet, so
+ * this divergence stays visible if either side moves.
+ *
+ * Accepted over-termination: continuation prose that happens to open with
+ * digits-then-`.`/`)` ("10. really keeps going") or a literal `|` stops the join
+ * early, so such a bullet fails loud rather than parsing. That is the same
+ * markdown ambiguity every line-oriented reader carries, and this direction of
+ * the trade is the one #1365 asks for — fail loud, never guess.
+ */
+const blockConstructRe = /^(?:[-*+]\s|\d+[.)]\s|#{1,6}\s|>\s|\|)/;
+/**
+ * The id-adjacent `[tags]` REGION of a logical bullet, as far as it has been
+ * assembled. Matching means the region is still unsettled, in one of two ways:
+ * capture group 1 is present when the bracket is open (group 1 is the content
+ * seen so far), and absent when the id has been read but no `[` has followed
+ * yet — so a bracket may still open on the next absorbed line.
+ *
+ * A NON-match means the region is settled for good: the bracket closed, or
+ * something other than `[` followed the id. Either way the join no longer has
+ * to watch for a splice.
+ *
+ * The id character class is deliberately looser than the grammars' (it admits
+ * an empty id, so a bare `- **D-` still counts as unsettled). This regex only
+ * answers "may an id-adjacent bracket still open here?", where recognising MORE
+ * shapes is the conservative direction: an over-broad match can only make a
+ * malformed bullet fail loud, while a missed one silently re-classifies.
+ *
+ * Only the ID-ADJACENT bracket matters: that is the one the three grammars turn
+ * into `tags` (and therefore into `trackable`). A `[` further along the title is
+ * ordinary text and does not restrict the join.
+ */
+const tagRegionRe = /^\s*-\s+\*\*D-[A-Za-z0-9_-]*\s*(?:\[([^\]]*))?$/;
+/**
+ * #3939 (review): would folding `next` onto a lead-in whose `[tags]` bracket is
+ * still open splice the inserted space INTO a tag token?
+ *
+ * Tags are comma-split and trimmed, so a space landing next to a delimiter
+ * (`[`, `,`, `]`) changes nothing — `[informational,` + `deferred]` is still
+ * exactly `[informational, deferred]`. A space landing anywhere else splits one
+ * token into two (`[defer` + `red]` → `defer red`), which would not fail; it
+ * would parse to a DIFFERENT tag, silently flipping `trackable` on a gate that
+ * decides whether a decision must be covered. Refusing to join there leaves the
+ * bullet unchanged, so it reaches the #1365 parse-miss guard and fails loud —
+ * a wrong answer about coverage is worse than a blocked gate.
+ *
+ * `tail` is the bracket content accumulated so far, `next` the trimmed
+ * continuation line.
+ */
+function wouldSpliceTagToken(tail, next) {
+    const before = tail.trimEnd();
+    if (before === '' || before.endsWith(',') || before.endsWith('['))
+        return false;
+    return !(next.startsWith(',') || next.startsWith(']'));
+}
+/**
+ * True when the bullet's own bold lead-in — the FIRST bold run on the line —
+ * is still open at end-of-line. Deliberately asks only about that first run
+ * (not `**`-parity over the whole string), because that is the run the three
+ * grammars anchor on: a balanced inline `**bold**` later in the body must not
+ * make a terminated lead-in look open.
+ */
+function boldLeadInIsUnterminated(text) {
+    const open = text.indexOf('**');
+    if (open === -1)
+        return false;
+    return text.indexOf('**', open + 2) === -1;
+}
+/**
+ * Fold a decision bullet whose bold lead-in wraps into ONE logical line, so the
+ * declaration grammars see the whole lead-in (#3939).
+ *
+ * Bounded and fail-loud-preserving: a wrapped declaration absorbs following
+ * lines only until its lead-in closes, and a blank/whitespace-only line, a new
+ * block-level construct (`blockConstructRe`), or the end of the block stops it.
+ * If the lead-in never closes, the original line is emitted UNCHANGED — a
+ * genuinely malformed bullet (e.g. an unterminated bold run) still reaches the
+ * parse-miss guard and still fails loud, exactly as #1365 requires. Non-decision
+ * lines pass through untouched, so continuation lines (#1372 FIX) and nested
+ * cross-reference bullets (#3169) are handled by the main loop as before.
+ *
+ * The joined line keeps the FIRST physical line's leading whitespace, so the
+ * `indentWidth` signal #3169 depends on is unchanged. Absorbed lines are
+ * trimmed and re-joined with a single space, which is what a soft line break
+ * means in markdown — so the join reproduces the rendered one-line text rather
+ * than concatenating the raw bytes.
+ *
+ * One place that equivalence does not hold is inside the id-adjacent `[tags]`
+ * bracket, where an inserted space can split a tag token and silently flip
+ * `trackable`. The join stops there instead (`wouldSpliceTagToken`), leaving the
+ * bullet to fail loud.
+ *
+ * Absorption stops at the first `**` on a continuation line, so an inline
+ * `**bold**` INSIDE a wrapped title closes the run early. That is deliberate:
+ * the result is byte-identical to what the same bullet written on one physical
+ * line parses to (the text past the early close re-attaches through the main
+ * loop's continuation folding), which is the whole contract here — wrapping is
+ * markdown-insignificant, never a second grammar.
+ */
+function joinWrappedBoldLeadIns(lines) {
+    const joined = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (!decisionBulletStartRe.test(line) || !boldLeadInIsUnterminated(line)) {
+            joined.push(line);
+            continue;
+        }
+        // Absorbed lines accumulate as SEGMENTS joined by a single space, and each
+        // new segment is searched on its own: the lead-in is known to be open at the
+        // end of the declaration line, and the inserted space means a closing `**`
+        // can never straddle a segment boundary, so the first `**` in any later
+        // segment is the close. Scanning per segment (rather than re-searching the
+        // accumulated string, which forces a rope flatten every iteration) keeps a
+        // long unterminated run linear on the plan gate's hot path.
+        const segments = [line];
+        // Bracket content accumulated while the id-adjacent `[tags]` bracket is
+        // still open; null when it is not open. O(1) per segment.
+        let tagTail = null;
+        // The logical text assembled so far, kept ONLY while the id-adjacent
+        // bracket has yet to open, so a bracket that opens on ANY absorbed line
+        // arms the splice guard — not just one that opens on the declaration line.
+        // Null once the region settles (the bracket opened and `tagTail` took over,
+        // or the id was followed by something else), so this never re-walks a long
+        // absorption: a non-empty segment that is not a bracket-open settles the
+        // region immediately, which bounds the string to a single extra join.
+        let tagRegion = null;
+        const declRegion = tagRegionRe.exec(line);
+        if (declRegion !== null) {
+            if (declRegion[1] === undefined)
+                tagRegion = line;
+            else
+                tagTail = declRegion[1];
+        }
+        let scan = i + 1;
+        let closed = false;
+        while (scan < lines.length) {
+            const trimmed = lines[scan].trim();
+            if (trimmed === '' || blockConstructRe.test(trimmed))
+                break;
+            if (tagTail !== null && wouldSpliceTagToken(tagTail, trimmed))
+                break;
+            segments.push(trimmed);
+            scan += 1;
+            if (tagTail !== null) {
+                tagTail = trimmed.indexOf(']') === -1 ? trimmed : null;
+            }
+            else if (tagRegion !== null) {
+                tagRegion = `${tagRegion} ${trimmed}`;
+                const opened = tagRegionRe.exec(tagRegion);
+                if (opened === null)
+                    tagRegion = null;
+                else if (opened[1] !== undefined) {
+                    tagTail = opened[1];
+                    tagRegion = null;
+                }
+            }
+            if (trimmed.indexOf('**') !== -1) {
+                closed = true;
+                break;
+            }
+        }
+        if (closed) {
+            joined.push(segments.join(' '));
+            i = scan - 1;
+        }
+        else {
+            joined.push(line);
+        }
+    }
+    return joined;
+}
 /**
  * Parse decision lines from a block of text (the inner text of a <decisions>
  * or markdown-header section body). Returns the extracted decisions and a count
@@ -83,9 +292,12 @@ const boldLeadInBulletRe = /^\s*-\s+\*\*[A-Z]+[0-9]*-[A-Za-z0-9]/m;
  * FIX B (#1365): parseMisses > 0 means the caller must treat the result as
  * could-not-parse even when some decisions were extracted — a silent drop is
  * worse than a fail-loud signal.
+ *
+ * #3939: physical lines are folded into logical bullets first, so a declaration
+ * whose bold lead-in wraps is matched as the one bullet it is.
  */
 function parseDecisionLines(block) {
-    const lines = block.split(/\r?\n/);
+    const lines = joinWrappedBoldLeadIns(block.split(/\r?\n/));
     const out = [];
     let category = '';
     let inDiscretion = false;

package/gsd-core/bin/lib/edge-probe.cjs

@@ -27,6 +27,9 @@ exports.validateResolution = validateResolution;
 exports.proposeEdges = proposeEdges;
 exports.analyzeCoverage = analyzeCoverage;
 const probe_core_cjs_1 = require("./probe-core.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { runMain } = cliExitModule;
 /**
  * Word-boundary cues mapping requirement prose -> data/behavior shape.
  * Heuristic and intentionally lossy; an authored `shapes` array overrides it.
@@ -107,6 +110,15 @@ function validateRequirement(requirement) {
     if (r.shapes == null && !(typeof r.text === 'string' && r.text.trim())) {
         throw new Error(`requirement ${requirement.id} text must be a non-empty string when no shapes override is provided`);
     }
+    // text_en (#3717) is optional, but when present it must be a non-empty string. An empty
+    // string is NOT caught by `??` (only null/undefined are), so an unvalidated `text_en: ''`
+    // would silently win `text_en ?? text` and classify against '' — the same fail-open shape
+    // #1110/#2773 already exist to eliminate, just moved one field over. Validated
+    // unconditionally (not gated on whether `shapes` will make it unused) so bad data fails
+    // closed even when it happens to be dead for this particular call.
+    if (r.text_en != null && !(typeof r.text_en === 'string' && r.text_en.trim())) {
+        throw new Error(`requirement ${requirement.id} text_en must be a non-empty string when present`);
+    }
 }
 /** Validate an edge resolution against the edge verification vocabulary. */
 function validateResolution(resolution) {
@@ -132,7 +144,11 @@ function proposeEdges(requirement) {
         shapes = requirement.shapes;
     }
     else {
-        shapes = classifyShape(requirement.text);
+        // #3717: prefer the English translation when present — SHAPE_CUES are English-only
+        // word-boundary patterns, so a non-English `text` (e.g. response_language projects)
+        // would otherwise classify to zero shapes. validateRequirement (called above) has
+        // already guaranteed text_en, if present, is a non-empty string.
+        shapes = classifyShape(requirement.text_en ?? requirement.text);
         if (shapes.length === 0) {
             // Prose present but no shape cue matched. Do NOT silently drop it (#1110): an
             // edge-relevant requirement whose phrasing missed every cue would otherwise vanish from
@@ -192,5 +208,10 @@ function analyzeCoverage(requirements, resolutions = []) {
  * `require.main === module` so it runs only when the compiled `.cjs` is executed directly.
  */
 if (require.main === module) {
-    (0, probe_core_cjs_1.runProbeCli)((requirements, resolutions) => analyzeCoverage(requirements, resolutions), { usage: 'edge-probe.cjs <requirements.json> [resolutions.json]' });
+    // runProbeCli's default `exit` now throws ExitError (src/probe-core.cts) rather
+    // than calling process.exit directly, so this entry point must run under
+    // runMain to translate that throw into process.exitCode.
+    runMain(() => {
+        (0, probe_core_cjs_1.runProbeCli)((requirements, resolutions) => analyzeCoverage(requirements, resolutions), { usage: 'edge-probe.cjs <requirements.json> [resolutions.json]' });
+    });
 }

package/gsd-core/bin/lib/estimate-cli.cjs

@@ -21,7 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CALIBRATION_FILENAME = void 0;
+exports.PhasesUnreadableError = exports.CALIBRATION_FILENAME = void 0;
 exports.readSmartZoneBudget = readSmartZoneBudget;
 exports.readCalibrationSamples = readCalibrationSamples;
 exports.parseTokensFlag = parseTokensFlag;
@@ -39,9 +39,15 @@ const estimation = require("./phase-estimation.cjs");
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
 const configLoader = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
+const phaseLocator = require("./phase-locator.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
+const planningScopeMod = require("./planning-scope.cjs");
 const { output, error, ERROR_REASON } = io;
 const { planningDir } = planningWorkspace;
 const { CONFIG_DEFAULTS } = configLoader;
+const { listMilestonePhaseDirs } = phaseLocator;
+const { SCOPE } = planningScopeMod;
 // WIN-1 parity (DEFECT.WINDOWS-FS-OPS): on Windows a concurrent reader, indexer,
 // or AV scanner can transiently hold the rename target open. Retry the transient
 // errnos with backoff, matching the writeLedger / writeConsentStore idiom.
@@ -192,6 +198,24 @@ function cmdEstimateCheck(cwd, args, raw) {
         sample_count: calibration.sampleCount,
     }, raw);
 }
+/**
+ * Thrown by `collectCalibrationSamples` when the phases directory EXISTS but
+ * could not be read (EACCES/EIO, `scope: SCOPE.UNREADABLE`). #3882/ADR-3473
+ * §8.5: that is a NON-answer, not "zero completed phases" — silently
+ * returning `[]` here would make an unreadable directory output-identical to
+ * a genuinely empty one, which is exactly the defect class §8.5 exists to
+ * end. `cmdEstimateCalibrate` catches this and refuses the rebuild instead
+ * of persisting a phantom empty calibration.
+ */
+class PhasesUnreadableError extends Error {
+    phasesRoot;
+    constructor(phasesRoot) {
+        super(`phases directory exists but could not be read: ${phasesRoot}`);
+        this.phasesRoot = phasesRoot;
+        this.name = 'PhasesUnreadableError';
+    }
+}
+exports.PhasesUnreadableError = PhasesUnreadableError;
 /**
  * Pair each completed phase's PLAN estimate with its SUMMARY actuals.
  *
@@ -199,18 +223,25 @@ function cmdEstimateCheck(cwd, args, raw) {
  * A plan with no `estimate` block, a summary with no `actuals`, or a malformed
  * value is skipped rather than guessed — a fabricated sample would silently
  * steer every future estimate.
+ *
+ * #3882 (ADR-3473 §8.2): this used to hand-roll a raw `readdirSync` over the
+ * phases directory, treating every directory (including sentinel phases —
+ * milestone 0 / 999, SENTINEL_RANGES) as a completed phase. A sentinel's
+ * PLAN/SUMMARY pair then silently contributed a phantom sample to the
+ * CALIBRATION FACTOR applied to every future estimate. Routed through the
+ * canonical owner (`listMilestonePhaseDirs`, `src/phase-locator.cts`) called
+ * with NO `cwd` — that combination is already "all milestone windows,
+ * sentinels excluded", exactly what this caller needs; no new API was
+ * required for this half (see the design doc's §3, corrected after
+ * measurement). It also inherits the `scope` discriminator for free, so an
+ * unreadable phases directory is no longer indistinguishable from a real
+ * empty one.
  */
 function collectCalibrationSamples(cwd) {
     const phasesRoot = node_path_1.default.join(planningDir(cwd), 'phases');
-    let phases;
-    try {
-        phases = node_fs_1.default.readdirSync(phasesRoot, { withFileTypes: true })
-            .filter((d) => d.isDirectory())
-            .map((d) => d.name)
-            .sort();
-    }
-    catch {
-        return [];
+    const { value: phases, scope } = listMilestonePhaseDirs(phasesRoot);
+    if (scope === SCOPE.UNREADABLE) {
+        throw new PhasesUnreadableError(phasesRoot);
     }
     const readBlock = (file, key) => {
         let text;
@@ -277,7 +308,20 @@ function collectCalibrationSamples(cwd) {
  * next estimate reads the result.
  */
 function cmdEstimateCalibrate(cwd, _args, raw) {
-    const samples = collectCalibrationSamples(cwd);
+    let samples;
+    try {
+        samples = collectCalibrationSamples(cwd);
+    }
+    catch (err) {
+        if (err instanceof PhasesUnreadableError) {
+            // #3882/ADR-3473 §8.5: refuse rather than silently rebuild the
+            // calibration document from a phantom empty sample set — an
+            // unreadable phases directory must never look output-identical to a
+            // project with genuinely zero completed phases.
+            error(err.message, ERROR_REASON.ESTIMATE_PHASES_UNREADABLE);
+        }
+        throw err;
+    }
     const calibration = estimation.computeCalibration(samples);
     const target = node_path_1.default.join(planningDir(cwd), exports.CALIBRATION_FILENAME);
     let written = true;

package/gsd-core/bin/lib/exit-code-registry.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+// GENERATED FILE — DO NOT EDIT BY HAND.
+// Source of truth: gsd-core/bin/shared/exit-codes.json. Regenerate with:
+//   node scripts/gen-exit-code-registry.cjs --write
+// This exact content is emitted to THREE locations — gsd-core/bin/lib/exit-code-registry.cjs,
+// scripts/lib/exit-code-registry.cjs, and hooks/lib/exit-code-registry.js (the latter two
+// committed so scripts/ and hooks/ consumers work on an unbuilt clone) — all byte-compared by
+// `npm run lint:generated-sync` (#3905 ADR-3889 Phase 1; #3906 Phase 2 added the second copy;
+// #3911 ADR-3889 Phase 7 added the hooks/lib/ copy).
+//
+// exitCodeFor(name) / nameForExitCode(code) are pure and total over this
+// closed table — each throws for anything not registered here.
+
+const EXIT_CODES = Object.freeze([
+  Object.freeze({
+    code: 2,
+    name: "HOOK_DENY",
+    meaning: "Hook protocol deny — the harness blocks the tool call",
+    owner: "hook-adapter",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 64,
+    name: "USAGE",
+    meaning: "Caller error — bad argv, unknown subcommand, missing argument",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 66,
+    name: "NO_INPUT",
+    meaning: "Ran; zero units were in scope, and that emptiness is known to be genuine",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 69,
+    name: "UNAVAILABLE",
+    meaning: "Could not run — prerequisite absent, input unreadable, scope unestablished",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 70,
+    name: "INTERNAL",
+    meaning: "Self-failure — crash, timeout, killed subprocess",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 80,
+    name: "DEGRADED",
+    meaning: "Ran to completion and is reporting a condition through its result payload rather than as a process failure",
+    owner: "gsd-tools",
+    authorizedBy: "ADR-3889 + ADR-2980",
+  })
+]);
+
+const NAME_TO_CODE = new Map(EXIT_CODES.map((entry) => [entry.name, entry.code]));
+const CODE_TO_NAME = new Map(EXIT_CODES.map((entry) => [entry.code, entry.name]));
+
+/**
+ * Resolve the registered exit code for a symbolic name. Pure, total: throws
+ * for anything not an exact, registered, exact-case key — including
+ * non-strings, the empty string, untrimmed strings, wrong case, and
+ * prototype-chain names like `__proto__`/`constructor`/`toString` (a Map
+ * lookup never touches the prototype chain, so these are indistinguishable
+ * from any other unregistered name).
+ *
+ * @param {string} name
+ * @returns {number}
+ */
+function exitCodeFor(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error(`exitCodeFor: name must be a non-empty string, received ${JSON.stringify(name)}`);
+  }
+  if (!NAME_TO_CODE.has(name)) {
+    throw new Error(`exitCodeFor: unregistered exit code name: ${JSON.stringify(name)}`);
+  }
+  return NAME_TO_CODE.get(name);
+}
+
+/**
+ * Reverse of exitCodeFor: resolve the symbolic name for a registered exit
+ * code. Pure, total: throws for anything not an exact, registered code.
+ *
+ * @param {number} code
+ * @returns {string}
+ */
+function nameForExitCode(code) {
+  if (!CODE_TO_NAME.has(code)) {
+    throw new Error(`nameForExitCode: unregistered exit code: ${JSON.stringify(code)}`);
+  }
+  return CODE_TO_NAME.get(code);
+}
+
+module.exports = { EXIT_CODES, exitCodeFor, nameForExitCode };

package/gsd-core/bin/lib/file-overlap-partitioner.cjs

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * File-overlap partitioner — shared greedy first-fit stage assignment (#3674).
+ *
+ * Extracted from `claude-orchestration.cts`'s `partitionStages` (#1143), which
+ * emits sequential Workflow `parallel()` stage barriers so that no two plans
+ * sharing a `files_modified` entry ever cohabit a stage. This module is the
+ * SAME algorithm, generalized: it depends on no `Plan`/`Wave` interface from
+ * `claude-orchestration.cts` (or any other caller-specific shape), so a future
+ * consumer (quick-batch, #3675 / ADR-1239 "Quick-batch binding") can partition
+ * its own planned-path items without pulling in orchestration internals.
+ *
+ * This is a pure, behavior-preserving extraction (#3674's acceptance bar is
+ * byte-identical output for `claude-orchestration.cts`'s existing callers —
+ * not an improvement). Explicitly OUT of scope, per the #3674 design lock:
+ *   - dependency-DAG ordering — this module only ever sees a flat item list
+ *     and file-overlap; a caller resolves dependency order before calling in
+ *     (same contract `partitionStages` already had);
+ *   - path normalization — file entries are compared by exact string equality
+ *     only. `Foo.ts` vs `foo.ts`, or `src/a.ts` vs `src\a.ts`, are treated as
+ *     DISTINCT files. This is deliberate, not a gap to "fix" during extraction;
+ *   - filesystem access — this module never reads a path off disk.
+ *
+ * Zero external dependencies. Pure function. Never throws on well-typed input.
+ */
+/**
+ * Partition `items` into a near-minimal number of sequential stages (via
+ * greedy first-fit — not guaranteed optimal for arbitrary overlap graphs, but
+ * correct: no two items sharing a file ever cohabit a stage) such that no two
+ * items in the same stage share a file. Each item goes into the earliest
+ * stage where it does not overlap any item already there, in input order.
+ *
+ * An item with an EMPTY `files` array declares no files; it overlaps nothing
+ * and coalesces into stage 0 (mirrors `partitionStages`' original behavior —
+ * this module cannot guard against undeclared concurrent writes; a caller
+ * must declare `files` accurately).
+ *
+ * File comparison is EXACT STRING EQUALITY — no path normalization, no
+ * case-folding, no separator canonicalization. Duplicate `id`s in the input
+ * are NOT deduplicated; each item is placed independently, in input order.
+ *
+ * Deterministic: identical input (including input order) always yields an
+ * identical partition.
+ */
+function partitionByFileOverlap(items) {
+    const stages = [];
+    for (const item of items) {
+        const fileSet = new Set(item.files);
+        let placed = false;
+        for (const stage of stages) {
+            let overlap = false;
+            for (const f of fileSet) {
+                if (stage.files.has(f)) {
+                    overlap = true;
+                    break;
+                }
+            }
+            if (!overlap) {
+                stage.items.push(item);
+                for (const f of fileSet)
+                    stage.files.add(f);
+                placed = true;
+                break;
+            }
+        }
+        if (!placed) {
+            stages.push({ items: [item], files: new Set(fileSet) });
+        }
+    }
+    return stages.map((s) => s.items.map((i) => i.id));
+}
+module.exports = {
+    partitionByFileOverlap,
+};