@skyramp/mcp 0.3.4 → 0.3.6-rc.1

package/build/tools/code-refactor/reuse-state.js

@@ -1,9 +1,17 @@
 import * as path from "path";
-import { readFile } from "fs/promises";
+import { readFile, stat, access, constants as fsConstants } from "fs/promises";
+import { realpathSync } from "fs";
+import { execFile } from "child_process";
+import { promisify } from "util";
 import { logger } from "../../utils/logger.js";
 import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateManager.js";
-import { verifyReuse } from "../../utils/pom-verify/index.js";
-import { buildSkipped, findUnparsableKeptInline, flaggedFrom, mergeFlagged, verificationFrom, ReuseVerificationOutcome, } from "./reuse-outcome.js";
+import { verifyReuse, } from "../../utils/pom-verify/index.js";
+import { buildSkipped, findUnparsableKeptInline, flaggedFrom, mergeFlagged, verificationFrom, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./reuse-outcome.js";
+import { verifyUtils, realpath, utilsSpecFor, } from "../../utils/utils-verify/index.js";
+import { detectGitRoot } from "../../utils/gitStaging.js";
+const execFileAsync = promisify(execFile);
+import { resolvePomCatalogPath } from "../../utils/pom-catalog.js";
+import { parsePomCatalog, findMissedReuse, } from "../../utils/pom-catalog-parse.js";
 /**
  * Persistence for the server-derived POM-reuse outcome, keyed by test-file
  * basename (what `newTestsCreated[].fileName` carries, so
@@ -25,29 +33,55 @@ import { buildSkipped, findUnparsableKeptInline, flaggedFrom, mergeFlagged, veri
 async function updateReuseOutcome(testFile, patch, explicitStateFile) {
     const stateFile = resolveRunStatePath(explicitStateFile);
     if (!stateFile)
-        return;
+        return false;
     try {
         const manager = StateManager.fromStatePath(stateFile);
         const data = await manager.readData();
         if (!data)
-            return;
+            return false;
         const key = path.basename(testFile);
         const existing = data.reuseOutcomes?.[key] ?? {};
         await manager.writeData({
             ...data,
-            reuseOutcomes: { ...data.reuseOutcomes, [key]: { ...existing, ...patch(existing) } },
+            reuseOutcomes: {
+                ...data.reuseOutcomes,
+                [key]: { ...existing, ...patch(existing) },
+            },
         });
+        return true;
     }
     catch (err) {
         logger.warning("Could not record POM-reuse outcome — report will omit the reuse summary", {
             testFile,
             error: String(err),
         });
+        return false;
     }
 }
-/** Record the tier-1 candidate count STEP 1 detected. */
-export async function recordCandidates(testFile, candidatesDetected, explicitStateFile) {
-    await updateReuseOutcome(testFile, () => ({ candidatesDetected }), explicitStateFile);
+/** Read one spec's record, or `undefined` when there is no run state, no record, or the
+ * state file cannot be read. Shares `updateReuseOutcome`'s resolve-read-basename plumbing
+ * so the two cannot disagree about which key a spec maps to. */
+async function readReuseRecord(testFile, explicitStateFile) {
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return undefined;
+    const data = await StateManager.fromStatePath(stateFile).readData();
+    return data?.reuseOutcomes?.[path.basename(testFile)];
+}
+/**
+ * Record the tier-1 candidate count STEP 1 detected, plus the identity needed to
+ * re-derive the counts from the delivered spec later.
+ *
+ * The identity is written here and not only by {@link recordVerifyOutcome} because
+ * the verify pass is a call the agent decides whether to make. When it skips it,
+ * a record holding the candidate count alone makes `rederiveReuseOutcome` bail out,
+ * and the report states "N candidate POM files detected" with no reuse numbers —
+ * indistinguishable from a run where reuse was measured and simply not summarized.
+ * Recording it unconditionally is what makes the zero-reuse case reportable without
+ * the agent's cooperation.
+ */
+export async function recordCandidates(testFile, candidatesDetected, language, explicitStateFile) {
+    await updateReuseOutcome(testFile, () => ({ candidatesDetected, testFilePath: testFile, language }), explicitStateFile);
 }
 /** The prompt-generation call found no reusable POM layer at all. No candidate
  *  count is recorded: "0 candidates" adds nothing to "no POM layer was found",
@@ -79,6 +113,549 @@ export async function recordVerifyOutcome(testFile, r, gateFired, language, expl
         };
     }, explicitStateFile);
 }
+/**
+ * Has this spec been handed POM mapping instructions it never came back to verify?
+ *
+ * The enforcement half of SKYR-4115, and deliberately NOT a second copy of the
+ * zero-reuse policy. `zeroReuseGateFailure` is already the right check in the right
+ * place — inside `skyramp_reuse_code`'s verify branch. Its only defect was being
+ * reachable solely through a call the agent chooses to make. So this enforces the
+ * CALL, not the outcome: the gate then runs where it was designed to, with its own
+ * mapping instructions and its own documented-decline escape hatch.
+ *
+ * The debt needs no field of its own — it is exactly "detection recorded candidates
+ * and no verify pass has recorded a verdict". `recordCandidates` writes the former,
+ * `recordVerifyOutcome` always writes the latter, so ONE `verify: true` call clears
+ * this unconditionally. That is what makes a hard block safe without a retry budget:
+ * the agent cannot be stuck, because the action that clears it always succeeds.
+ *
+ * A FAILED verdict does NOT clear it. `formatVerifyReport` already tells the agent
+ * "do not finish until it reports PASSED" — enforcing that in prose is the exact
+ * failure this ticket exists to replace, and this is the one place positioned to
+ * enforce it in code.
+ *
+ * Blocking on a failure needs no retry budget either, because these checkpoints are
+ * NOT terminal. A PASS is always reachable in one edit plus one call (substitute the
+ * members, or document each candidate with a `// kept inline:` marker, which the gate
+ * accepts), and an agent that resolves neither can still walk past these tools to
+ * `skyramp_submit_report`, which does not block and reports the honest zero. So the
+ * worst case degrades to the reporting half rather than to a run that produces
+ * nothing — which is what a bound would have been protecting against.
+ */
+export async function pendingReuseVerification(testFile, explicitStateFile) {
+    try {
+        const record = await readReuseRecord(testFile, explicitStateFile);
+        // candidatesDetected is written only for a POM-aware target whose candidates came
+        // from the conventional globs, so its presence is what limits this to specs that
+        // actually had a page-object layer to reuse.
+        if (!record?.candidatesDetected)
+            return undefined;
+        // `reuseOutcomes` is keyed by BASENAME across the whole run, so in a multi-repo run
+        // two specs can share one record. Blocking a tool on another spec's debt is worse
+        // than missing this one, so a mismatch fails open. `recordCandidates` always writes
+        // the path, which is what makes the owner checkable at all.
+        if (record.testFilePath && !samePath(record.testFilePath, testFile))
+            return undefined;
+        const cleared = record.verification === ReuseVerificationOutcome.Passed ||
+            record.verification === ReuseVerificationOutcome.SkippedNoPom;
+        if (cleared)
+            return undefined;
+        const spec = path.basename(testFile);
+        const state = record.verification === ReuseVerificationOutcome.Failed
+            ? `the last verification of ${spec} did not pass`
+            : `the refactor of ${spec} was never verified`;
+        return (`${record.candidatesDetected} reusable page-object candidate${record.candidatesDetected === 1 ? "" : "s"} ` +
+            `were detected and ${state}. Call skyramp_reuse_code with verify: true on this file and resolve what it ` +
+            `reports — it names the POM members the spec should use, and accepts a documented decline ` +
+            `(\`// kept inline: <POM file basename> — <reason>\`) when a candidate genuinely cannot cover the test.`);
+    }
+    catch (err) {
+        // Fail open: an unreadable state file is not evidence the agent skipped anything.
+        logger.warning("Could not check for a pending POM-reuse verification — proceeding", {
+            testFile,
+            error: String(err),
+        });
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// SkyrampUtils (shared-helper) path — SKYR-4220
+// ---------------------------------------------------------------------------
+/**
+ * The utils path handed out its reuse instructions for this spec. This is the debt:
+ * from here until a `verify: true` pass records PASSED or NoUtilsFile, the tools that
+ * follow reuse on the same spec refuse.
+ *
+ * Same shape as {@link recordCandidates} for the POM path, and for the same reason:
+ * the verify call is the agent's to make, and the utils file it stages and checks is
+ * the artifact a skipped call would ship broken (SKYR-4196 Part B run 2). Recorded
+ * unconditionally on the utils path — even a spec that ends up moving nothing clears
+ * cheaply (NoUtilsFile), and the cost of a skipped debt is a test importing a module
+ * the PR does not contain.
+ */
+export async function recordUtilsReuseIssued(testFile, language, framework, testType, explicitStateFile) {
+    await updateReuseOutcome(testFile, (existing) => ({
+        testFilePath: testFile,
+        language,
+        // A re-issued prompt (the agent calling discovery twice) must not erase a
+        // verdict already earned; only the identity is refreshed. But a record OWNED
+        // BY ANOTHER SPEC (same basename, another directory) is not this spec's history:
+        // inheriting its verdict would let this spec skip verify entirely — a debt born
+        // cleared — so ownership is checked on the write, not only on the read.
+        // Ownership change resets the WHOLE record: a foreign spec's POM facts must not
+        // make this spec owe the foreign POM debt.
+        ...(owns(existing, testFile) ? {} : freshRecord()),
+        utils: {
+            ...(owns(existing, testFile) ? existing.utils : {}),
+            issued: true,
+            framework,
+            testType,
+        },
+    }), explicitStateFile);
+}
+/** Every field cleared — the patch spread onto a record owned by another spec. */
+function freshRecord() {
+    return {
+        candidatesDetected: undefined,
+        verification: undefined,
+        flagged: undefined,
+        language: undefined,
+        utils: undefined,
+        modularized: undefined,
+    };
+}
+/** A verify pass that threw. Recorded so the debt FAILS OPEN — a verifier that cannot
+ *  run must not leave a debt nothing can pay — and cleared by the next successful pass. */
+export async function recordUtilsVerifyError(testFile, explicitStateFile) {
+    await updateReuseOutcome(testFile, (existing) => owns(existing, testFile) && existing.utils
+        ? { utils: { ...existing.utils, verifyError: true } }
+        : {}, explicitStateFile);
+}
+/** Whether `record` describes `testFile` (or nobody yet). Basename-keyed run state
+ *  means two specs can share one record; only the owner's history carries over. */
+function owns(record, testFile) {
+    return !record.testFilePath || samePath(record.testFilePath, testFile);
+}
+/** Canonical comparison: a record written through a symlinked path (macOS /var →
+ *  /private/var) must still be recognised as this spec's when checked by realpath. */
+function samePath(a, b) {
+    return canon(a) === canon(b);
+}
+function canon(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** Verdict of one utils verify pass. The verdict alone is stored — counts and the
+ *  file list are re-derived from the delivered files at report time. */
+export async function recordUtilsVerifyOutcome(testFile, r, language, framework, testType, explicitStateFile) {
+    const verification = r.utilsFiles.length === 0
+        ? HelperVerificationOutcome.NoUtilsFile
+        : r.ok
+            ? HelperVerificationOutcome.Passed
+            : HelperVerificationOutcome.Failed;
+    return updateReuseOutcome(testFile, (existing) => {
+        const mine = owns(existing, testFile);
+        const prior = mine ? existing.utils : undefined;
+        return {
+            ...(mine ? {} : freshRecord()),
+            testFilePath: testFile,
+            language,
+            // A verify without a prior discovery records the verdict but NOT a debt:
+            // `issued` stays false, so a spec that was never handed reuse instructions is
+            // never blocked by this record. The test type is persisted from the verify
+            // call itself, so the report re-derives with the same helper family the gate
+            // used (a browser helper's toBeVisible must not become a body assertion at
+            // report time).
+            utils: {
+                issued: prior?.issued ?? false,
+                framework: prior?.framework || framework,
+                testType: testType ?? prior?.testType,
+                verification,
+                verifyError: false,
+            },
+        };
+    }, explicitStateFile);
+}
+/** Whether the run state file can be written — the precondition for any debt this
+ *  module holds, since only a write clears it. */
+async function runStateWritable(explicitStateFile) {
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return false;
+    try {
+        await access(stateFile, fsConstants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `skyramp_modularization` was called for this spec. Ownership on the write, like
+ *  the utils debt: a same-basename spec elsewhere does not inherit the mark. */
+export async function recordModularized(testFile, explicitStateFile) {
+    await updateReuseOutcome(testFile, (existing) => owns(existing, testFile)
+        ? { testFilePath: existing.testFilePath ?? testFile, modularized: true }
+        : {
+            testFilePath: testFile,
+            modularized: true,
+            utils: undefined,
+            verification: undefined,
+            candidatesDetected: undefined,
+            flagged: undefined,
+        }, explicitStateFile);
+}
+/**
+ * Does this spec owe `skyramp_modularization` before reuse may be issued? Only a spec
+ * generation handed off (modularize-first flows: the hand-off names both calls, in
+ * order) and only until the mark exists. Measured: eval run u4219f — the agent skipped
+ * modularization for both new tests and went straight to reuse; the reuse half was
+ * enforced, the modularization half was prose. Fails open without a hand-off, on a
+ * record owned by another spec, on an unwritable or unreadable state file.
+ */
+export async function pendingModularization(testFile, explicitStateFile) {
+    try {
+        const stateFile = resolveRunStatePath(explicitStateFile);
+        if (!stateFile)
+            return undefined;
+        const data = await StateManager.fromStatePath(stateFile).readData();
+        const handOff = data?.reuseHandOffs?.[await realpath(testFile)];
+        if (!handOff)
+            return undefined;
+        const record = data?.reuseOutcomes?.[path.basename(testFile)];
+        if (record && !owns(record, testFile))
+            return undefined;
+        if (record?.modularized)
+            return undefined;
+        if (!(await runStateWritable(explicitStateFile)))
+            return undefined;
+        return (`${path.basename(testFile)} was generated with code reuse enabled, and its flow modularizes BEFORE reuse: ` +
+            `modularization is what creates the named helpers reuse consolidates. Call skyramp_modularization with ` +
+            `{ testFile: "${testFile}", testType: "${handOff.testType}", isTraceBased: true }, apply the returned instructions to the file, ` +
+            `then call skyramp_reuse_code again with the same arguments.`);
+    }
+    catch (err) {
+        logger.warning("Could not check for a pending modularization — proceeding", {
+            testFile,
+            error: String(err),
+        });
+        return undefined;
+    }
+}
+/** The exact `skyramp_reuse_code` verify call for a spec — handed to the agent verbatim
+ *  so the gate never depends on the agent interpolating a placeholder correctly. */
+function utilsVerifyCall(record, testFile) {
+    const args = [
+        `testFile: "${testFile}"`,
+        `language: "${record.language ?? ""}"`,
+        `framework: "${record.utils?.framework ?? ""}"`,
+        record.utils?.testType ? `testType: "${record.utils.testType}"` : undefined,
+        "verify: true",
+    ].filter(Boolean);
+    return `skyramp_reuse_code with { ${args.join(", ")} }`;
+}
+/**
+ * Has this spec been handed SkyrampUtils reuse instructions it never came back to
+ * verify? The utils-path twin of {@link pendingReuseVerification}, needed because that
+ * predicate keys on `candidatesDetected`, which only a POM-aware target writes — a
+ * utils debt riding it would fail open on every repo without a page-object layer,
+ * precisely the population this exists for.
+ *
+ * Failure mode, stated: an unresolved utils debt BLOCKS execution. On the POM path
+ * a missed verify degrades a report; here it ships a test importing a file the PR
+ * does not contain, which cannot run at all — so losing the execution attempt is
+ * the cheaper failure. Same no-retry-budget reasoning as the POM twin: PASSED is one
+ * edit plus one call away (fix the invariant, or document it with the
+ * `reuse-verify: allow` line the verify text hands over), NoUtilsFile clears it for
+ * free, and `skyramp_submit_report` never reads it, so nothing hangs.
+ */
+export async function pendingUtilsVerification(testFile, explicitStateFile) {
+    try {
+        const record = await readReuseRecord(testFile, explicitStateFile);
+        if (record?.utils?.issued !== true)
+            return undefined;
+        // The last verify pass threw: the agent was told not to loop on it, so the debt
+        // must not hold either.
+        if (record.utils.verifyError)
+            return undefined;
+        // Basename-keyed across the run — fail open on another spec's record (see the POM twin).
+        if (record.testFilePath && !samePath(record.testFilePath, testFile))
+            return undefined;
+        // A debt only a state write can clear must not outlive the ability to write. If the
+        // state file is not writable, the verify pass has already said PASSED and could not
+        // record it — refusing here would leave no action that clears the block.
+        if (!(await runStateWritable(explicitStateFile)))
+            return undefined;
+        const v = record.utils.verification;
+        if (v === HelperVerificationOutcome.Passed ||
+            v === HelperVerificationOutcome.NoUtilsFile)
+            return undefined;
+        const spec = path.basename(testFile);
+        const state = v === HelperVerificationOutcome.Failed
+            ? `its last shared-helper verification did not pass`
+            : `its shared-helper reuse was never verified`;
+        return (`${spec} was handed code-reuse instructions and ${state}. Call ${utilsVerifyCall(record, testFile)} ` +
+            `and resolve what it reports — it stages the shared utils file for the output commit and checks its invariants ` +
+            `(API helpers: one helper per method+path, status-code-only assertions, method+resource names; browser helpers: actions and structural waits only). It passes trivially when no ` +
+            `utils file was written, and accepts a documented decline per violation (the exact \`reuse-verify: allow\` line is in its output).`);
+    }
+    catch (err) {
+        logger.warning("Could not check for a pending shared-helper verification — proceeding", {
+            testFile,
+            error: String(err),
+        });
+        return undefined;
+    }
+}
+/**
+ * Generation emitted a modularize→reuse hand-off for the tests it wrote into
+ * `outputDir`. Recorded at the SAME site and under the SAME condition as the
+ * hand-off text, so the debt can never be owed for a test that was never told to
+ * pay it (a gate that cannot be satisfied is the SKYR-4115 failure inverted).
+ */
+export async function recordReuseHandOff(files, testType, language, framework, explicitStateFile) {
+    if (files.length === 0)
+        return;
+    // A language the utils verifier does not cover (Java) has no payable reuse half —
+    // nothing on the reuse side records for it — so no hand-off is owed either.
+    if (!utilsSpecFor(language))
+        return;
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return;
+    try {
+        const manager = StateManager.fromStatePath(stateFile);
+        const data = await manager.readData();
+        if (!data)
+            return;
+        const entries = {};
+        for (const f of files)
+            entries[await realpath(f)] = { testType, language, framework };
+        await manager.writeData({
+            ...data,
+            reuseHandOffs: { ...data.reuseHandOffs, ...entries },
+        });
+    }
+    catch (err) {
+        logger.warning("Could not record the reuse hand-off — chain compliance will not be checked", {
+            files,
+            error: String(err),
+        });
+    }
+}
+/** True when `file` is not in HEAD — i.e. this run created it. The chain debt applies
+ *  only to tests generation wrote; pre-existing tests in the same directory are
+ *  executed by the same tool and must never be held to it. Fails open (false) when
+ *  git cannot answer. */
+async function isNewInRepo(file) {
+    const root = detectGitRoot(file);
+    if (!root)
+        return false;
+    // Both sides canonical: git reports the REAL root, and a tool-supplied path through
+    // a symlink (macOS /tmp → /private/tmp) would otherwise produce a `../../` relative
+    // path that `cat-file` cannot resolve — reading every pre-existing test as new
+    // (measured: eval run 2026-08-26 blocked two maintained tests on the chain debt).
+    const rel = path
+        .relative(await realpath(root), await realpath(file))
+        .split(path.sep)
+        .join("/");
+    if (rel.startsWith(".."))
+        return false;
+    try {
+        await execFileAsync("git", ["cat-file", "-e", `HEAD:${rel}`], {
+            cwd: root,
+        });
+        return false; // present at HEAD → pre-existing
+    }
+    catch (err) {
+        // Only "absent from HEAD" (or no HEAD yet) means new. Anything else — git missing,
+        // a corrupt object store, a permission error — is git not answering, and the
+        // documented answer to that is false: never block, never accuse, on a malfunction.
+        const e = err;
+        const text = `${e.stderr ?? ""} ${String(err)}`;
+        if (/does not exist|Not a valid object name|bad revision|exists on disk, but not in/i.test(text))
+            return true;
+        logger.warning("Could not determine whether a file is new in the repository — treating it as pre-existing", {
+            file,
+            error: String(err),
+        });
+        return false;
+    }
+}
+/**
+ * Does this spec owe the modularize→reuse pair its generation handed off? The
+ * chain-compliance half of SKYR-4220: 2 of 8 SKYR-4196 Part B runs wrote a second
+ * integration test's imports by hand and skipped the pair. A hand-off of the spec's
+ * test type exists for its directory (integration, or ui since SKYR-4224), the spec
+ * is new in this run, and no reuse pass was ever recorded for it → refuse, naming
+ * the two calls. Fails open on everything else.
+ */
+export async function pendingReuseChain(testFile, explicitStateFile, testType) {
+    try {
+        const stateFile = resolveRunStatePath(explicitStateFile);
+        if (!stateFile)
+            return undefined;
+        const data = await StateManager.fromStatePath(stateFile).readData();
+        // Keyed by the GENERATED FILE: generation snapshots its outputDir before and after
+        // the codegen call and records exactly the files it wrote, so a test generated
+        // without codeReuse into the same directory owes nothing, and neither does a
+        // pre-existing test beside it.
+        const handOff = data?.reuseHandOffs?.[await realpath(testFile)];
+        if (!handOff)
+            return undefined;
+        // A caller that knows the file's type and disagrees with the hand-off is exempt;
+        // an unknown type still owes (the hand-off is authoritative for this file).
+        if (testType && testType !== handOff.testType)
+            return undefined;
+        const record = data?.reuseOutcomes?.[path.basename(testFile)];
+        // A FOREIGN record fails open (refusing this spec over another spec's history is
+        // the worse error). The OWNER's record clears only if reuse actually ran for it —
+        // a modularization mark or a bare verify verdict (`issued: false`) is not reuse,
+        // and treating it as such would let an agent modularize, skip skyramp_reuse_code,
+        // and execute.
+        if (record && !owns(record, testFile))
+            return undefined;
+        if (record && reuseRan(record))
+            return undefined;
+        if (!(await isNewInRepo(testFile)))
+            return undefined;
+        return (`${path.basename(testFile)} was generated with code reuse enabled, but its modularize→reuse steps were never run. ` +
+            `First call skyramp_modularization with { testFile: "${testFile}", testType: "${handOff.testType}", isTraceBased: true } and apply the result; ` +
+            `then, as the very next skyramp call, skyramp_reuse_code with { testFile: "${testFile}", language: "${handOff.language}", framework: "${handOff.framework}", testType: "${handOff.testType}" } ` +
+            `and follow its steps (including its final verify: true call). A "nothing to reuse" result is normal — do not retry.`);
+    }
+    catch (err) {
+        logger.warning("Could not check for a pending modularize→reuse chain — proceeding", {
+            testFile,
+            error: String(err),
+        });
+        return undefined;
+    }
+}
+/** Every reuse-phase debt a downstream tool must refuse on, first one wins. One call
+ *  site for both checkpoints so they cannot drift apart. */
+export async function pendingReuseDebt(testFile, explicitStateFile, testType, opts = {}) {
+    return ((await pendingReuseVerification(testFile, explicitStateFile)) ??
+        (await pendingUtilsVerification(testFile, explicitStateFile)) ??
+        // The chain debt belongs to the LAST checkpoint only: the UI utils flow runs
+        // skyramp_enhance_assertions BEFORE modularize→reuse by design, so checking the
+        // chain there would refuse the very first call the generator prescribes.
+        (opts.chain === false
+            ? undefined
+            : await pendingReuseChain(testFile, explicitStateFile, testType)));
+}
+/**
+ * Report-time chain verdict for one report row. `fileName` is a basename, so it is
+ * matched against the basenames of the handed-off files of the same test type. True
+ * only when such a file exists, is new in this run, and no reuse record was ever
+ * written for that basename — never `false`, so a consumer omits rather than renders a
+ * negative.
+ */
+export async function reuseChainSkipped(fileName, testType, record, handOffs) {
+    // Same rule as the gate: a foreign record fails open; the owner's record suppresses
+    // the signal only when reuse was actually issued for it.
+    if (!handOffs)
+        return undefined;
+    const base = path.basename(fileName);
+    for (const [file, h] of Object.entries(handOffs)) {
+        if (h.testType !== testType || path.basename(file) !== base)
+            continue;
+        if (record) {
+            if (!owns(record, file))
+                continue; // foreign basename — fail open for this file
+            if (reuseRan(record))
+                return undefined;
+        }
+        try {
+            if (!(await stat(file)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        // The hand-off names files generation wrote, so newness is implied — but the
+        // guard is kept for state written by an older recorder that keyed directories.
+        if (await isNewInRepo(file))
+            return true;
+    }
+    return undefined;
+}
+/** Whether a record shows the reuse tool ran for its spec: the utils path issued its
+ *  instructions, or the POM path recorded detection/verification. A modularization mark
+ *  alone, or a verify verdict recorded without a prior discovery, is NOT reuse. */
+function reuseRan(record) {
+    return (record.utils?.issued === true ||
+        record.candidatesDetected !== undefined ||
+        record.verification !== undefined);
+}
+/**
+ * Re-derive the shared-helper outcome from the delivered files. Everything is
+ * measured now: the utils file is located by header, its invariants re-checked, the
+ * imports re-counted — the recorded verdict is not consulted, so a utils file
+ * rewritten after the verify pass is described as it stands. Returns `undefined`
+ * (omit `helpers`) when no utils file exists for the spec.
+ */
+async function rederiveHelperOutcome(record) {
+    const { testFilePath, language } = record;
+    if (!testFilePath || !language)
+        return undefined;
+    const r = await verifyUtils({
+        testFile: testFilePath,
+        language,
+        testType: record.utils?.testType,
+    });
+    if (r.utilsFiles.length === 0)
+        return {};
+    return {
+        helpers: {
+            utilsFile: r.utilsFiles.map((f) => path.basename(f)).join(", "),
+            helpersImported: r.imported,
+            ...(r.inlineCallSites.length > 0
+                ? { siblingInlineCallSites: r.inlineCallSites.length }
+                : {}),
+            verification: r.ok
+                ? HelperVerificationOutcome.Passed
+                : HelperVerificationOutcome.Failed,
+        },
+    };
+}
+/**
+ * Raw-locator coverage for the delivered spec, or `undefined` when it cannot be
+ * established.
+ *
+ * Fails open at every step. No catalog is the common case — a POM-less repo, or a
+ * run where the agent never reached STEP 2 — and that case stays silent: it is
+ * expected, not a defect. An unreadable or unparseable catalog is different — the
+ * file exists but the agent wrote something this cannot use — and that case is
+ * logged, per the design's failure-mode contract, so the gap is diagnosable
+ * without a customer-facing symptom. Either way, no number reaches the report that
+ * is not backed by the spec on disk.
+ */
+async function coverageFrom(testFilePath, specContent) {
+    const catalogPath = resolvePomCatalogPath(testFilePath);
+    try {
+        const markdown = await readFile(catalogPath, "utf8");
+        const members = parsePomCatalog(markdown);
+        if (members.length === 0)
+            return undefined;
+        return findMissedReuse(specContent, members);
+    }
+    catch (err) {
+        // ENOENT (no catalog at all) is the common, expected case — silent. Anything
+        // else (permission error, unreadable file) means a catalog exists but could
+        // not be used, which the design's failure-modes table promises a warning for.
+        if (err?.code !== "ENOENT") {
+            logger.warning("Could not read the POM catalog — omitting reuse coverage from the report", {
+                catalogPath,
+                error: String(err),
+            });
+        }
+        return undefined;
+    }
+}
 /**
  * Re-derive a recorded outcome from the spec as it stands NOW, so the report
  * describes the delivered artifact rather than the state at verify time.
@@ -99,14 +676,28 @@ export async function recordVerifyOutcome(testFile, r, gateFired, language, expl
  * reads as though the empty result had been blessed.
  *
  * Returns the recorded outcome minus internals when re-derivation is impossible
- * (no path recorded — e.g. only the candidate count was ever written), and
- * `undefined` when it fails outright. Failing closed matters: falling back to the
- * recorded counts is exactly the false claim this exists to prevent.
+ * (no path recorded — now only the no-POM-layer path, which has no spec to measure
+ * and no candidates to contrast against), and `undefined` when it fails outright.
+ * Failing closed matters: falling back to the recorded counts is exactly the false
+ * claim this exists to prevent.
  */
 export async function rederiveReuseOutcome(record) {
     const { candidatesDetected, verification, flagged, testFilePath, language } = record;
-    // No verify pass ran for this spec, so there are no counts to derive — only the
-    // detection-time facts, which no spec change can invalidate.
+    // A SkyrampUtils-path record has nothing for the POM verifier to measure; its
+    // outcome is re-derived from the utils file instead.
+    if (record.utils) {
+        try {
+            return await rederiveHelperOutcome(record);
+        }
+        catch (err) {
+            logger.warning("Could not re-derive the shared-helper outcome from the delivered files — omitting it rather than reporting a stale verdict", { testFile: testFilePath, error: String(err) });
+            return undefined;
+        }
+    }
+    // No spec identity was ever recorded, so there is nothing to measure — only the
+    // detection-time facts, which no spec change can invalidate. Reached by the
+    // no-POM-layer path; a run that detected candidates always records the identity
+    // (see recordCandidates), precisely so the zero-reuse case does not land here.
     if (!testFilePath || !language)
         return { candidatesDetected, verification };
     try {
@@ -122,14 +713,35 @@ export async function rederiveReuseOutcome(record) {
                 "Use `// kept inline: <file basename> — <reason>` (em dash, or a hyphen with spaces around it).", { testFile: testFilePath, markers: unparsable });
         }
         const skipped = buildSkipped(specContent, flagged);
+        const coverage = await coverageFrom(testFilePath, specContent);
+        const reuseHappened = r.reusedCalls > 0;
         return {
             candidatesDetected,
             callsReused: r.reusedCalls,
-            callsVerified: r.checkedCalls,
+            // Only a POM call can be checked, so `checkedCalls` is a subset of
+            // `reusedCalls` and at zero reuse both it and the unverifiable remainder
+            // are structurally implied. Emitting them anyway is worse than redundant:
+            // two equal counts render as "0 POM calls reused and verified", asserting
+            // that a verification blessed the empty result. The pair is dropped
+            // together so `callsVerified + callsUnverifiable === callsReused` stays
+            // statable. Same reasoning as dropping `verification` just below.
+            ...(reuseHappened
+                ? {
+                    callsVerified: r.checkedCalls,
+                    // From the counts, not from the list: these are the numbers a renderer
+                    // subtracts with, and they must close.
+                    callsUnverifiable: r.reusedCalls - r.checkedCalls,
+                }
+                : {}),
+            unverifiableCalls: r.unverifiableCalls.length > 0 ? r.unverifiableCalls : undefined,
+            // Raw-locator coverage describes the delivered spec, not the reuse count, so
+            // it is reported at zero reuse too — that is where it says the most.
+            rawLocatorsInline: coverage?.rawLocatorsInline,
+            missedReuse: coverage && coverage.missed.length > 0 ? coverage.missed : undefined,
             // A PASSED verdict describes a spec that no longer exists once reuse is gone,
             // and pairing it with a zero count reads as though the empty result had been
             // blessed.
-            verification: r.reusedCalls > 0 ? verification : undefined,
+            verification: reuseHappened ? verification : undefined,
             skipped: skipped.length > 0 ? skipped : undefined,
         };
     }