@opengsd/gsd-core 1.8.0 → 1.9.0

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

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * Estimate CLI — the I/O seam over the pure phase-estimation module.
+ *
+ * Epic #1952 Phase 1 (#2630). Design lock: docs/adr/2629-phase-effort-estimation-calibration.md.
+ *
+ * `phase-estimation.cts` is pure policy; everything that touches disk or config
+ * lives here. Two leaf verbs (a pair, so leaves rather than a family per
+ * ADR-2346's ">=3 subcommands" rule):
+ *
+ *   gsd-tools query estimate-check --tokens <n>
+ *   gsd-tools query estimate-calibration
+ *
+ * Both degrade rather than fail. A missing or corrupt
+ * `.planning/estimation-calibration.json` yields an inert calibration
+ * (factor 1, applied false) instead of breaking planning — the file is a disk
+ * trust boundary that steers planning output, so it is parsed defensively and
+ * never trusted structurally.
+ */
+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.readSmartZoneBudget = readSmartZoneBudget;
+exports.readCalibrationSamples = readCalibrationSamples;
+exports.parseTokensFlag = parseTokensFlag;
+exports.cmdEstimateCheck = cmdEstimateCheck;
+exports.collectCalibrationSamples = collectCalibrationSamples;
+exports.cmdEstimateCalibrate = cmdEstimateCalibrate;
+exports.cmdEstimateCalibration = cmdEstimateCalibration;
+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 -- io.cjs is an export= CommonJS module
+const io = require("./io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-estimation.cjs is an export= CommonJS module
+const estimation = require("./phase-estimation.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
+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");
+const { output, error, ERROR_REASON } = io;
+const { planningDir } = planningWorkspace;
+const { CONFIG_DEFAULTS } = configLoader;
+// 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.
+const RENAME_RETRY_ERRNOS = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const RENAME_MAX_ATTEMPTS = 3;
+const RENAME_RETRY_BACKOFF_MS = 50;
+let _renameSleepBuf = null;
+function renameBackoff() {
+    if (_renameSleepBuf === null)
+        _renameSleepBuf = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(_renameSleepBuf, 0, 0, RENAME_RETRY_BACKOFF_MS);
+}
+/** Rename with a bounded retry on the transient Windows errnos. Rethrows anything else. */
+function renameWithRetry(from, to) {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            node_fs_1.default.renameSync(from, to);
+            return;
+        }
+        catch (err) {
+            const code = err.code ?? '';
+            if (attempt < RENAME_MAX_ATTEMPTS && RENAME_RETRY_ERRNOS.has(code)) {
+                renameBackoff();
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+/** Filename of the persisted calibration document, written by extract-learnings (Phase 3). */
+exports.CALIBRATION_FILENAME = 'estimation-calibration.json';
+function defaultBudget() {
+    const fromManifest = Number(CONFIG_DEFAULTS.smart_zone_tokens);
+    return Number.isSafeInteger(fromManifest) && fromManifest > 0 ? fromManifest : 100000;
+}
+/**
+ * Read the configured smart-zone budget, degrading to the manifest default.
+ *
+ * Reads config.json directly rather than through the flat loadConfig
+ * projection: a hand-edited config can hold any value, and this seam must
+ * validate rather than assume. An out-of-shape value falls back to the default
+ * instead of propagating NaN into the comparison.
+ */
+function readSmartZoneBudget(cwd) {
+    try {
+        const configPath = node_path_1.default.join(planningDir(cwd), 'config.json');
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+        if (parsed !== null && typeof parsed === 'object') {
+            const workflow = parsed['workflow'];
+            if (workflow !== null && typeof workflow === 'object') {
+                const value = workflow['smart_zone_tokens'];
+                if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0)
+                    return value;
+            }
+        }
+    }
+    catch {
+        // Absent, unreadable, or malformed config — the default is the answer.
+    }
+    return defaultBudget();
+}
+/** Read and defensively parse the calibration history. Never throws. */
+function readCalibrationSamples(cwd) {
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), exports.CALIBRATION_FILENAME), 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    return estimation.parseCalibrationDocument(raw);
+}
+/**
+ * Parse `--tokens <n>`.
+ *
+ * Rejects a missing value, an empty/whitespace value, a value that is really
+ * the next flag, and anything that is not a positive integer. Uses an exact
+ * digit match rather than Number()/parseInt so that "1; touch x", "1e5",
+ * "0x10", and " 1 " are all refused — the value reaches us as argv, is never
+ * shell-interpolated, and must not be coerced into looking valid.
+ *
+ * Returns a PLAIN number, deliberately (#2671). This function validates the
+ * magnitude of `--tokens`; it cannot know the figure's basis, because that is
+ * decided by a DIFFERENT flag (`--calibrated`). Branding here would force it to
+ * pick RawTokens or CalibratedTokens for every caller, and it would be wrong
+ * half the time — a type that lies is worse than no type. The basis assertion
+ * therefore belongs to the caller that reads both flags; today that is
+ * `cmdEstimateCheck`, which is this function's only caller. A future second
+ * caller must make the same assertion explicitly rather than inherit a guess.
+ */
+function parseTokensFlag(args) {
+    const idx = args.indexOf('--tokens');
+    if (idx === -1) {
+        error('Usage: estimate-check --tokens <positive integer> [--calibrated]', ERROR_REASON.USAGE);
+    }
+    const value = args[idx + 1];
+    if (value === undefined || value.startsWith('--') || !/^[0-9]+$/.test(value)) {
+        error(`Invalid --tokens ${JSON.stringify(value ?? '')}. Must be a positive integer (token count).`, ERROR_REASON.USAGE);
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        error(`Invalid --tokens ${JSON.stringify(value)}. Must be a positive integer (token count).`, ERROR_REASON.USAGE);
+    }
+    return parsed;
+}
+/**
+ * `estimate-check --tokens <n>` — classify an estimate against the configured
+ * smart-zone budget, with the current calibration applied.
+ *
+ * The advisory contract (ADR-2629 Decision 5): this reports, it never blocks.
+ * Exit status is 0 whether or not the estimate is over budget; `over_budget`
+ * in the payload is the signal.
+ */
+function cmdEstimateCheck(cwd, args, raw) {
+    const inputTokens = parseTokensFlag(args);
+    const preCalibrated = args.includes('--calibrated');
+    const budget = readSmartZoneBudget(cwd);
+    const calibration = estimation.computeCalibration(readCalibrationSamples(cwd));
+    // `--calibrated` says the caller already applied the factor. Without it we
+    // would apply the correction a SECOND time and compare factor^2 against the
+    // budget — with the [0.5, 3.0] clamp that is anywhere from 4x under to 9x
+    // over, and it is invisible until a project reaches 3 samples (below that
+    // factor === 1, and 1^2 === 1). A plan's recorded `estimate.tokens` is
+    // calibrated at emission time per ADR-2629 Decision 1, so the plan-checker
+    // MUST pass this flag.
+    //
+    // `--calibrated` is the whole basis question, and argv cannot answer it for
+    // the type system — so this is where the caller's claim is turned into a type
+    // (#2671). Past this expression the basis is carried by RawTokens /
+    // CalibratedTokens and the wrong composition stops compiling; the ambiguity
+    // is confined to these two lines instead of running the length of the seam.
+    const calibratedTokens = preCalibrated
+        ? estimation.asCalibratedTokens(inputTokens)
+        : estimation.applyCalibration(estimation.asRawTokens(inputTokens), calibration.factor);
+    const classification = estimation.classifyAgainstBudget(calibratedTokens, budget);
+    output({
+        raw_tokens: inputTokens,
+        calibrated_tokens: calibratedTokens,
+        pre_calibrated: preCalibrated,
+        budget,
+        over_budget: classification.overBudget,
+        budget_valid: classification.budgetValid,
+        ratio: Number(classification.ratio.toFixed(4)),
+        recommendation: classification.recommendation,
+        confidence: calibration.confidence,
+        calibration_applied: calibration.applied,
+        calibration_factor: calibration.factor,
+        sample_count: calibration.sampleCount,
+    }, raw);
+}
+/**
+ * Pair each completed phase's PLAN estimate with its SUMMARY actuals.
+ *
+ * A phase contributes a sample only when BOTH sides are present and well-formed.
+ * 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.
+ */
+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 readBlock = (file, key) => {
+        let text;
+        try {
+            text = node_fs_1.default.readFileSync(file, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+        return estimation.extractFrontmatterBlock(text, key);
+    };
+    const samples = [];
+    for (const phase of phases) {
+        const dir = node_path_1.default.join(phasesRoot, phase);
+        let files;
+        try {
+            files = node_fs_1.default.readdirSync(dir).sort();
+        }
+        catch {
+            continue;
+        }
+        // Pair PER PLAN, keyed on the `<NN>-<PP>` stem, NOT per phase directory.
+        // A phase routinely holds several plans (docs/reference/planning-artifacts.md:
+        // "one file per plan"). Taking the first plan with an estimate and the first
+        // summary with actuals independently cross-pairs one plan's projection with
+        // another's cost — a fabricated sample — and discards every later plan.
+        const stems = new Map();
+        for (const f of files) {
+            const m = /^(.*?)-(PLAN|SUMMARY)\.md$/.exec(f);
+            if (m === null)
+                continue;
+            const stem = m[1];
+            const entry = stems.get(stem) ?? {};
+            if (m[2] === 'PLAN')
+                entry.plan = node_path_1.default.join(dir, f);
+            else
+                entry.summary = node_path_1.default.join(dir, f);
+            stems.set(stem, entry);
+        }
+        for (const stem of [...stems.keys()].sort()) {
+            const { plan, summary } = stems.get(stem);
+            if (plan === undefined || summary === undefined)
+                continue;
+            const estimate = estimation.parseEstimate(readBlock(plan, 'estimate'));
+            const actuals = estimation.parseActuals(readBlock(summary, 'actuals'));
+            if (estimate === null || actuals === null)
+                continue;
+            // Measure against the RAW projection — see PhaseEstimate.rawTokens for why
+            // measuring against the calibrated figure makes the loop self-defeating.
+            samples.push({
+                estimateTokens: estimation.calibrationBasis(estimate),
+                actualTokens: actuals.tokens,
+            });
+        }
+    }
+    return samples;
+}
+/**
+ * `estimate-calibrate` — rebuild the calibration document from completed phases.
+ *
+ * Rebuilds from scratch every run rather than appending, so it is idempotent and
+ * a corrupt prior document is replaced rather than merged. This is the verb that
+ * closes the loop (#1952 AC4): extract-learnings invokes it, and the planner's
+ * next estimate reads the result.
+ */
+function cmdEstimateCalibrate(cwd, _args, raw) {
+    const samples = collectCalibrationSamples(cwd);
+    const calibration = estimation.computeCalibration(samples);
+    const target = node_path_1.default.join(planningDir(cwd), exports.CALIBRATION_FILENAME);
+    let written = true;
+    let writeError = null;
+    try {
+        // Write-then-rename: a direct writeFileSync can leave a truncated file if
+        // interrupted, and parseCalibrationDocument treats malformed JSON exactly
+        // like "no history yet" — so a torn write would silently erase the
+        // calibration instead of surfacing.
+        const tmp = `${target}.tmp-${String(process.pid)}`;
+        try {
+            node_fs_1.default.writeFileSync(tmp, estimation.renderCalibrationDocument(samples), 'utf-8');
+            renameWithRetry(tmp, target);
+        }
+        catch (err) {
+            // Never leave the temp behind for a later run to trip over.
+            try {
+                node_fs_1.default.rmSync(tmp, { force: true });
+            }
+            catch { /* best effort */ }
+            throw err;
+        }
+    }
+    catch (err) {
+        // Persisting is best-effort: a read-only .planning must not fail the phase.
+        // But report WHY — a genuine bug and a benign permission issue are otherwise
+        // indistinguishable to both the caller and the workflow.
+        written = false;
+        writeError = err instanceof Error ? (err.message || String(err)) : String(err);
+    }
+    output({
+        factor: calibration.factor,
+        applied: calibration.applied,
+        sample_count: calibration.sampleCount,
+        confidence: calibration.confidence,
+        clamped: calibration.clamped,
+        min_samples: estimation.MIN_CALIBRATION_SAMPLES,
+        written,
+        write_error: writeError,
+    }, raw);
+}
+/**
+ * `estimate-calibration` — report the current correction factor and the
+ * history behind it.
+ */
+function cmdEstimateCalibration(cwd, _args, raw) {
+    const calibration = estimation.computeCalibration(readCalibrationSamples(cwd));
+    output({
+        factor: calibration.factor,
+        applied: calibration.applied,
+        sample_count: calibration.sampleCount,
+        confidence: calibration.confidence,
+        clamped: calibration.clamped,
+        min_samples: estimation.MIN_CALIBRATION_SAMPLES,
+    }, raw);
+}

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

@@ -15,6 +15,10 @@ const node_path_1 = __importDefault(require("node:path"));
 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");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const unusableInputMod = require("./unusable-input.cjs");
+const { UNUSABLE_REASON, warnUnusableInput } = unusableInputMod;
 // ─── Parsing engine ───────────────────────────────────────────────────────────
 /**
  * Split a YAML inline array body on commas, respecting quoted strings.
@@ -52,18 +56,50 @@ function splitInlineArray(body) {
         items.push(trimmed);
     return items;
 }
-function extractFrontmatter(content) {
+/**
+ * How many parsed keys an unterminated region must yield before it is reported as a
+ * truncated frontmatter rather than left alone as ordinary Markdown. See the rationale on
+ * `extractFrontmatter`; exported for tests so the boundary is asserted against the constant
+ * rather than a magic number duplicated in the suite.
+ */
+const UNTERMINATED_KEY_THRESHOLD = 2;
+/**
+ * Does every non-empty line of an unterminated region look like frontmatter?
+ *
+ * The key count alone cannot separate a truncated write from ordinary Markdown, because a
+ * thematic break above a short labelled preamble parses as keys too:
+ *
+ *     ---
+ *     Author: Jane Doe
+ *     Reviewed-by: John Smith
+ *
+ *     Ordinary prose, and no second `---` anywhere.
+ *
+ * Raising the threshold only moves that boundary — two labelled lines are as common in prose as
+ * one. What actually distinguishes the two is what follows: a write interrupted part-way through
+ * a frontmatter block ends mid-block, so *every* line in the region is still frontmatter-shaped,
+ * whereas a document merely opening with a rule goes on to prose. So the region must be
+ * uniformly frontmatter-shaped AND carry enough keys to be worth reporting; either test alone
+ * has a false-positive class the other closes.
+ */
+function isFrontmatterShaped(region) {
+    const lines = region.split(/\r?\n/).filter((line) => line.trim() !== '');
+    if (lines.length === 0)
+        return false;
+    return lines.every((line) => (/^\s*[a-zA-Z0-9_-]+:/.test(line) // key: value
+        || /^\s*-\s+/.test(line) // - list item
+        || /^\s+\S/.test(line) // indented continuation of a nested value
+    ));
+}
+/**
+ * Parse one already-delimited YAML region into a Frontmatter object.
+ *
+ * Extracted from `extractFrontmatter` (#1882) so the truncation probe below and the real
+ * parse run the *same* parser. A second, simpler "does this look like YAML?" matcher would
+ * be a parallel surface that drifts — exactly the generative-fix-divergence class.
+ */
+function parseYamlRegion(yaml) {
     const frontmatter = {};
-    // Match frontmatter only at byte 0 — a `---` block later in the document
-    // body (YAML examples, horizontal rules) must never be treated as frontmatter.
-    const headerEnd = content.startsWith('---\r\n') ? 5 : content.startsWith('---\n') ? 4 : -1;
-    if (headerEnd === -1)
-        return frontmatter;
-    const closingLineStart = content.indexOf('\n---', headerEnd);
-    if (closingLineStart === -1)
-        return frontmatter;
-    const yamlEnd = content[closingLineStart - 1] === '\r' ? closingLineStart - 1 : closingLineStart;
-    const yaml = content.slice(headerEnd, yamlEnd);
     const lines = yaml.split(/\r?\n/);
     const stack = [{ obj: frontmatter, key: null, indent: -1 }];
     for (const line of lines) {
@@ -126,6 +162,60 @@ function extractFrontmatter(content) {
     }
     return frontmatter;
 }
+/**
+ * Extract frontmatter from a document.
+ *
+ * Returns `{}` when the document has no frontmatter — and, unchanged since #1882, also
+ * returns `{}` when the frontmatter fence was opened and never closed. That return value is
+ * deliberately preserved: ADR-1411's amendment requires the fallback to stay, because
+ * changing it would break callers that treat "absent" and "unusable" identically. What #1882
+ * adds is that the second case is no longer *silent*.
+ *
+ * The discriminator is the reason this is not simply "opened but never closed". A Markdown
+ * document whose first line is a thematic break (`---`) takes that exact branch, so flagging
+ * on the missing fence alone reports corruption on perfectly good Markdown. Instead the
+ * unterminated region is run through this module's own parser and reported only when it
+ * yields **two or more** keys.
+ *
+ * Two, not one, and the extra key is doing real work. A single `key: value` line is genuinely
+ * ambiguous: `---` followed by `Note: this is a paragraph.` — or `Author:`, `TODO:`, `See:` —
+ * is ordinary technical writing, a thematic break above a labelled line, and it parses as
+ * exactly one key. There is no textual signal that separates it from a write interrupted
+ * after its first key, so the threshold is set where the ambiguity ends. The cost is a false
+ * negative on a file truncated after exactly one key; the benefit is silence on a very common
+ * Markdown shape. That direction is deliberate and matches the choice already made at zero
+ * keys: a false positive on valid Markdown is worse than a missed edge, because the
+ * diagnostic is unconditional and cannot be turned off. Every GSD artefact this guards
+ * (STATE.md, PLAN.md, ROADMAP.md, SUMMARY.md, agent/command docs) carries two or more
+ * frontmatter keys, so the realistic interruption window stays covered.
+ *
+ * @param content Raw document text.
+ * @param sourcePath Optional resolved path, used to name the file in the diagnostic and to
+ *   key its deduplication. Optional because this function has 50-odd call sites and several
+ *   hold only an in-memory string; those dedup on a content digest instead.
+ */
+function extractFrontmatter(content, sourcePath) {
+    // Match frontmatter only at byte 0 — a `---` block later in the document
+    // body (YAML examples, horizontal rules) must never be treated as frontmatter.
+    const headerEnd = content.startsWith('---\r\n') ? 5 : content.startsWith('---\n') ? 4 : -1;
+    if (headerEnd === -1)
+        return {};
+    const closingLineStart = content.indexOf('\n---', headerEnd);
+    if (closingLineStart === -1) {
+        const region = content.slice(headerEnd);
+        const probe = parseYamlRegion(region);
+        if (Object.keys(probe).length >= UNTERMINATED_KEY_THRESHOLD && isFrontmatterShaped(region)) {
+            warnUnusableInput({
+                reason: UNUSABLE_REASON.FRONTMATTER_UNTERMINATED,
+                source: sourcePath,
+                content,
+            });
+        }
+        return {};
+    }
+    const yamlEnd = content[closingLineStart - 1] === '\r' ? closingLineStart - 1 : closingLineStart;
+    return parseYamlRegion(content.slice(headerEnd, yamlEnd));
+}
 /**
  * Escape a string for emission inside a YAML double-quoted scalar (#1779).
  * Backslash must be escaped first so the backslashes added for embedded quotes
@@ -557,7 +647,9 @@ function cmdFrontmatterGet(cwd, filePath, field, raw) {
         output({ error: 'File not found', path: filePath }, raw, undefined);
         return;
     }
-    const fm = extractFrontmatter(content);
+    // Pass the resolved path so a truncated file is named in the diagnostic and deduplicated
+    // per file rather than per content digest (#1882, ADR-1411 wiring clause).
+    const fm = extractFrontmatter(content, fullPath);
     if (field) {
         const value = fm[field];
         if (value === undefined) {
@@ -584,7 +676,9 @@ function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
         return;
     }
     const content = node_fs_1.default.readFileSync(fullPath, 'utf-8');
-    const fm = extractFrontmatter(content);
+    // Pass the resolved path so a truncated file is named in the diagnostic and deduplicated
+    // per file rather than per content digest (#1882, ADR-1411 wiring clause).
+    const fm = extractFrontmatter(content, fullPath);
     let parsedValue;
     try {
         parsedValue = JSON.parse(value);
@@ -633,7 +727,9 @@ function cmdFrontmatterMerge(cwd, filePath, data, raw) {
         return;
     }
     const content = node_fs_1.default.readFileSync(fullPath, 'utf-8');
-    const fm = extractFrontmatter(content);
+    // Pass the resolved path so a truncated file is named in the diagnostic and deduplicated
+    // per file rather than per content digest (#1882, ADR-1411 wiring clause).
+    const fm = extractFrontmatter(content, fullPath);
     let mergeData;
     try {
         mergeData = JSON.parse(data);
@@ -651,6 +747,9 @@ function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
     if (!filePath || !schemaName) {
         error('file and schema required');
     }
+    if (filePath.includes('\0')) {
+        error('file path contains null bytes');
+    }
     const schema = FRONTMATTER_SCHEMAS[schemaName];
     if (!schema) {
         error(`Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(', ')}`);
@@ -661,13 +760,24 @@ function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
         output({ error: 'File not found', path: filePath }, raw, undefined);
         return;
     }
-    const fm = extractFrontmatter(content);
+    // #2701: fail loud on NUL/binary corruption before schema checks. A structurally
+    // intact-but-NUL-corrupted file otherwise passes as valid:true and is then silently
+    // skipped by recursive/binary-skipping searchers, reading downstream as "absent."
+    const encErr = (0, validate_cjs_1.textEncodingError)(content, filePath);
+    if (encErr) {
+        output({ valid: false, errors: [encErr], schema: schemaName }, raw, 'invalid');
+        return;
+    }
+    // Pass the resolved path so a truncated file is named in the diagnostic and deduplicated
+    // per file rather than per content digest (#1882, ADR-1411 wiring clause).
+    const fm = extractFrontmatter(content, fullPath);
     const missing = schema.required.filter(f => fm[f] === undefined);
     const present = schema.required.filter(f => fm[f] !== undefined);
     output({ valid: missing.length === 0, missing, present, schema: schemaName }, raw, missing.length === 0 ? 'valid' : 'invalid');
 }
 module.exports = {
     extractFrontmatter,
+    UNTERMINATED_KEY_THRESHOLD,
     // Additive alias (#644 prohibition-probe schema contract): the probe round-trip seam reads a
     // frontmatter object via `parseFrontmatter` (the name the contract test pins). It is the SAME
     // function as `extractFrontmatter` — a bare-object parse with no behavior change — exposed under