@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/tools/code-refactor/reuse-state.d.ts

@@ -1,6 +1,7 @@
+import { type ReuseHandOff, type ReuseHandOffSource } from "../../utils/AnalysisStateManager.js";
 import { type VerifyResult } from "../../utils/pom-verify/index.js";
-import { type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
-import { type UtilsVerifyResult } from "../../utils/utils-verify/index.js";
+import { type InHouseDeclaration, type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
+import { type UtilsVerifyResult, type UtilsViolationKind } from "../../utils/utils-verify/index.js";
 import type { ReuseVerificationFailure } from "../../types/ReuseOutcome.js";
 /**
  * Record the tier-1 candidate count STEP 1 detected, plus the identity needed to
@@ -98,7 +99,9 @@ export declare function canonPath(p: string): string;
 export declare function utilsFileLabel(files: string[]): string;
 /** 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 declare function recordUtilsVerifyOutcome(testFile: string, r: UtilsVerifyResult, language: string, framework: string, testType: string | undefined, explicitStateFile?: string): Promise<boolean>;
+export declare function recordUtilsVerifyOutcome(testFile: string, r: UtilsVerifyResult, language: string, framework: string, testType: string | undefined, explicitStateFile?: string, 
+/** The agent's declarations from this verify call, when it made any. */
+inHouseDeclared?: InHouseDeclaration): Promise<boolean>;
 /** `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 declare function recordModularized(testFile: string, explicitStateFile?: string): Promise<void>;
@@ -135,14 +138,22 @@ export declare function pendingUtilsVerification(testFile: string, explicitState
  * 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 declare function recordReuseHandOff(files: string[], testType: string, language: string, framework: string, explicitStateFile?: string): Promise<void>;
+export declare function recordReuseHandOff(files: string[], testType: string, language: string, framework: string, explicitStateFile?: string, source?: ReuseHandOffSource): Promise<void>;
 /**
- * Does this spec owe the modularize→reuse pair its generation handed off? The
+ * Does this spec owe the modularize→reuse pair it was 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.
+ * integration test's imports by hand and skipped the pair. A hand-off names this
+ * exact file with the spec's test type (integration, or ui since SKYR-4224) and no
+ * reuse pass was ever recorded for it → refuse, naming the two calls. Fails open on
+ * everything else.
+ *
+ * Whether the file is at HEAD matters only for a GENERATION hand-off: the
+ * `isNewInRepo` guard exists for a pre-existing test that a stale hand-off names
+ * although this run never wrote it (measured 2026-08-26: two maintained tests
+ * blocked on a debt they never owed). A MAINTENANCE hand-off is recorded by
+ * skyramp_actions for the file it told the agent to update or regenerate — at HEAD
+ * by definition — so that file owes the pair whether or not it is present at HEAD,
+ * and the guard is not consulted.
  */
 export declare function pendingReuseChain(testFile: string, explicitStateFile?: string, testType?: string): Promise<string | undefined>;
 /** Every reuse-phase debt a downstream tool must refuse on, first one wins. One call
@@ -153,14 +164,15 @@ export declare function pendingReuseDebt(testFile: string, explicitStateFile?: s
 /**
  * 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
+ * only when such a file exists, this run wrote it (generation hand-off, new in the
+ * repo) or rewrote it (maintenance hand-off), and no reuse record was ever written
+ * for that basename — never `false`, so a consumer omits rather than renders a
  * negative.
  */
-export declare function reuseChainSkipped(fileName: string, testType: string, record: ReuseRecord | undefined, handOffs: Record<string, {
-    testType: string;
-    language: string;
-}> | undefined): Promise<true | undefined>;
+export declare function reuseChainSkipped(fileName: string, testType: string, record: ReuseRecord | undefined, 
+/** Optional because `reuseHandOffs` is optional on the run state: a run that
+ *  armed nothing never writes the field. */
+handOffs: Record<string, ReuseHandOff> | undefined): Promise<true | undefined>;
 /**
  * A blocking reuse verdict measured on the DELIVERED files at report time — the
  * same predicate the live `verify: true` pass refuses on, re-run on what ships.
@@ -208,6 +220,16 @@ export declare const REUSE_SUBMIT_MAX_REFUSALS = 2;
 /** What one report row's re-derivation established: the outcome to publish, and a
  *  blocking verdict when the delivered files fail the live check. */
 export interface ReuseRederivation {
+    /** Carried declines a finding consumed on this pass. The caller keeps these and
+     *  retires the rest: a decline that covers nothing is permission looking for a
+     *  fault, and the next fault it meets is one nobody declined. */
+    carriedConsumed?: CarriedDecline[];
+    /** Whether this pass actually MEASURED the spec, so `carriedConsumed` is an answer
+     *  rather than a silence. A pass that threw, or one whose record carries no spec
+     *  identity, consumes nothing for the same reason it reports nothing: it read
+     *  nothing. Retiring on that deletes permission while the fault it covers is still
+     *  in the file, and the next submission refuses a decline already made. */
+    carriedEvaluated?: boolean;
     outcome: ReuseOutcome | undefined;
     blocking?: ReuseBlockingVerdict;
 }
@@ -251,4 +273,56 @@ export declare function verificationFailures(r: UtilsVerifyResult): ReuseVerific
  * and no verdict. A verifier that cannot run is not evidence against the file, and
  * refusing a report on a malfunction would deliver nothing to the customer.
  */
-export declare function rederiveReuse(record: ReuseRecord): Promise<ReuseRederivation>;
+/** A decline the run documented in a delivered file and then removed from it before
+ *  delivery. Read exactly like a marker still in the file — the record of the decline
+ *  belongs to the run, not to the customer's copy. */
+/** A decline the run removed from a delivered file. `file` is a runtime tag the
+ *  submit path puts on when it reads the record, so a consumption can be attributed
+ *  back to the file it came from; it is not part of what is persisted. */
+export type CarriedDecline = 
+/** A `reuse-verify: allow` decline: the finding it documented, by kind and helper. */
+{
+    kind: UtilsViolationKind;
+    helper: string;
+    keptInline?: undefined;
+    file?: string;
+}
+/** A `// kept inline:` decline: the page-object file basename it named, and the
+ *  reason it gave. The reason is the part the customer's report shows, so dropping
+ *  it silently emptied the report's `skipped` list on a later submission. */
+ | {
+    keptInline: string;
+    reason: string;
+    kind?: undefined;
+    helper?: undefined;
+    file?: string;
+};
+/**
+ * The shared-helper record for a delivered test that has NO reuse record — derived
+ * from the file's own imports.
+ *
+ * The record the report normally carries is written by the verify pass, so a row
+ * only got one when the agent chose to call `skyramp_reuse_code` with
+ * `verify: true` on that file. That keys the report on the tool's activity rather
+ * than on the product: a contract test whose delivered file imports and calls three
+ * helpers reported `reuse: null`, which a reader cannot tell from "did not reuse".
+ *
+ * So where no record exists, the row is answered from the delivered file instead.
+ * What this can state is exactly what the file proves — which module, which helpers
+ * taken from it. It states NO `verification`: nothing verified this spec, and an
+ * optional member that is absent means "not measured", never "false". It raises no
+ * blocking verdict for the same reason — a file the gates never walked must not
+ * start failing a report at submission time.
+ *
+ * Returns `notDerived` with a stated reason where the file cannot answer, because a
+ * bare `null` is indistinguishable from "did not reuse" and is read as a fault.
+ *
+ * The reason names what was LOOKED AT, not what exists. `locateUtilsFiles` returns
+ * the modules this run wrote or changed beside the spec, plus the ones the spec
+ * imports — it does not enumerate the directory, so a clean tracked module beside a
+ * spec that imports nothing is not among them. Saying "no module was found here"
+ * would assert a sweep that did not happen, which is the same overclaim as the row
+ * this function exists to replace.
+ */
+export declare function deriveReuseFromDelivered(testFile: string, language?: string): Promise<ReuseOutcome>;
+export declare function rederiveReuse(record: ReuseRecord, carriedAllows?: CarriedDecline[]): Promise<ReuseRederivation>;

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

@@ -9,6 +9,8 @@ import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateMan
 import { verifyReuse, } from "../../utils/pom-verify/index.js";
 import { buildSkipped, findUnparsableKeptInline, flaggedFrom, mergeFlagged, verificationFrom, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./reuse-outcome.js";
 import { verifyUtils, realpath, utilsSpecFor, countAssertions, hasPageErrorGuard, utilsSpecForFile, } from "../../utils/utils-verify/index.js";
+import { readDeliveredImports } from "../../utils/utils-verify/delivered-imports.js";
+import { hasUtilsHeader } from "../../utils/utils-verify/locate.js";
 import { detectGitRoot } from "../../utils/gitStaging.js";
 import { formatUtilsVerifyText } from "./utils-verify-gates.js";
 import { composeVerifyText, infraGateFailure, zeroReuseGateFailure, } from "./verify-gates.js";
@@ -45,7 +47,7 @@ async function updateReuseOutcome(testFile, patch, explicitStateFile) {
             return false;
         const key = path.basename(testFile);
         const existing = data.reuseOutcomes?.[key] ?? {};
-        await manager.writeData({
+        await manager.appendData({
             ...data,
             reuseOutcomes: {
                 ...data.reuseOutcomes,
@@ -289,14 +291,18 @@ function canon(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) {
+export async function recordUtilsVerifyOutcome(testFile, r, language, framework, testType, explicitStateFile, 
+/** The agent's declarations from this verify call, when it made any. */
+inHouseDeclared) {
     // `ok` first: a baseline violation is a failed verify with or without a module
     // beside the spec (the live text says FAILED), and recording NoUtilsFile there
     // cleared the debt, let execution proceed, and left the fault to be refused first
-    // at submit — the recorded verdict was a stale positive.
+    // at submit — the recorded verdict was a stale positive. A spec that calls the
+    // repository's own helpers and no Skyramp module was verified — the in-house
+    // checks ran — so it is a PASS, not "no utils file".
     const verification = !r.ok
         ? HelperVerificationOutcome.Failed
-        : r.utilsFiles.length === 0
+        : r.utilsFiles.length === 0 && !r.inHouse
             ? HelperVerificationOutcome.NoUtilsFile
             : HelperVerificationOutcome.Passed;
     return updateReuseOutcome(testFile, (existing) => {
@@ -318,6 +324,11 @@ export async function recordUtilsVerifyOutcome(testFile, r, language, framework,
                 testType: testType ?? prior?.testType,
                 verification,
                 verifyError: false,
+                // The latest declaration stands; a verify call that declares nothing
+                // keeps the one before it — the agent is told to declare once.
+                ...((inHouseDeclared ?? prior?.inHouseDeclared)
+                    ? { inHouseDeclared: inHouseDeclared ?? prior?.inHouseDeclared }
+                    : {}),
             },
         };
     }, explicitStateFile);
@@ -402,7 +413,9 @@ export async function pendingModularization(testFile, explicitStateFile) {
             return undefined;
         if (!(await runStateWritable(explicitStateFile)))
             return undefined;
-        return (`${path.basename(testFile)} was generated with code reuse enabled, and its flow modularizes BEFORE reuse: ` +
+        return ((handOff.source === "maintenance"
+            ? `${path.basename(testFile)} was updated by this run's maintenance step, and its flow modularizes BEFORE reuse: `
+            : `${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.`);
@@ -486,7 +499,7 @@ export async function pendingUtilsVerification(testFile, explicitStateFile) {
  * 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) {
+export async function recordReuseHandOff(files, testType, language, framework, explicitStateFile, source = "generation") {
     if (files.length === 0)
         return;
     // A language the utils verifier does not cover (Java) has no payable reuse half —
@@ -501,10 +514,18 @@ export async function recordReuseHandOff(files, testType, language, framework, e
         const data = await manager.readData();
         if (!data)
             return;
+        // A REGENERATE marks its file as maintenance before the generation call it
+        // prescribes records the same file as generation. The rewrite is still the
+        // maintenance of a file at HEAD, so the origin is never demoted.
         const entries = {};
-        for (const f of files)
-            entries[await realpath(f)] = { testType, language, framework };
-        await manager.writeData({
+        for (const f of files) {
+            const key = await realpath(f);
+            const origin = data.reuseHandOffs?.[key]?.source === "maintenance"
+                ? "maintenance"
+                : source;
+            entries[key] = { testType, language, framework, source: origin };
+        }
+        await manager.appendData({
             ...data,
             reuseHandOffs: { ...data.reuseHandOffs, ...entries },
         });
@@ -516,10 +537,12 @@ export async function recordReuseHandOff(files, testType, language, framework, e
         });
     }
 }
-/** 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. */
+/** True when `file` is not in HEAD — i.e. this run created it. Consulted only for a
+ *  GENERATION hand-off: that debt applies to the tests generation wrote, and a
+ *  pre-existing test in the same directory, executed by the same tool, must never be
+ *  held to it. A maintenance hand-off names a file this run rewrote in place, which
+ *  is at HEAD by definition, so its callers do not ask. Fails open (false) when git
+ *  cannot answer. */
 async function isNewInRepo(file) {
     const root = detectGitRoot(file);
     if (!root)
@@ -556,12 +579,20 @@ async function isNewInRepo(file) {
     }
 }
 /**
- * Does this spec owe the modularize→reuse pair its generation handed off? The
+ * Does this spec owe the modularize→reuse pair it was 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.
+ * integration test's imports by hand and skipped the pair. A hand-off names this
+ * exact file with the spec's test type (integration, or ui since SKYR-4224) and no
+ * reuse pass was ever recorded for it → refuse, naming the two calls. Fails open on
+ * everything else.
+ *
+ * Whether the file is at HEAD matters only for a GENERATION hand-off: the
+ * `isNewInRepo` guard exists for a pre-existing test that a stale hand-off names
+ * although this run never wrote it (measured 2026-08-26: two maintained tests
+ * blocked on a debt they never owed). A MAINTENANCE hand-off is recorded by
+ * skyramp_actions for the file it told the agent to update or regenerate — at HEAD
+ * by definition — so that file owes the pair whether or not it is present at HEAD,
+ * and the guard is not consulted.
  */
 export async function pendingReuseChain(testFile, explicitStateFile, testType) {
     try {
@@ -590,9 +621,12 @@ export async function pendingReuseChain(testFile, explicitStateFile, testType) {
             return undefined;
         if (record && reuseRan(record))
             return undefined;
-        if (!(await isNewInRepo(testFile)))
+        const maintained = handOff.source === "maintenance";
+        if (!maintained && !(await isNewInRepo(testFile)))
             return undefined;
-        return (`${path.basename(testFile)} was generated with code reuse enabled, but its modularize→reuse steps were never run. ` +
+        return ((maintained
+            ? `${path.basename(testFile)} was updated by this run's maintenance step, and the modularize→reuse steps it owes were never run. `
+            : `${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.`);
@@ -620,11 +654,15 @@ export async function pendingReuseDebt(testFile, explicitStateFile, testType, op
 /**
  * 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
+ * only when such a file exists, this run wrote it (generation hand-off, new in the
+ * repo) or rewrote it (maintenance hand-off), 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) {
+export async function reuseChainSkipped(fileName, testType, record, 
+/** Optional because `reuseHandOffs` is optional on the run state: a run that
+ *  armed nothing never writes the field. */
+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)
@@ -646,9 +684,9 @@ export async function reuseChainSkipped(fileName, testType, record, handOffs) {
         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))
+        // A maintenance hand-off names a file at HEAD; the newness guard is for a
+        // generation hand-off only (see isNewInRepo).
+        if (h.source === "maintenance" || (await isNewInRepo(file)))
             return true;
     }
     return undefined;
@@ -687,7 +725,7 @@ export const REUSE_SUBMIT_MAX_REFUSALS = 2;
  * raised whether or not a utils file was located: a spec that drops below its
  * modularization baseline is below it with or without a module beside it.
  */
-async function rederiveHelperOutcome(record) {
+async function rederiveHelperOutcome(record, carriedAllows) {
     const { testFilePath, language } = record;
     if (!testFilePath || !language)
         return { outcome: undefined };
@@ -696,6 +734,8 @@ async function rederiveHelperOutcome(record) {
         language,
         testType: record.utils?.testType,
         baseline: record.baseline,
+        // Only the utils grammar's declines mean anything to this verifier.
+        carriedAllows: (carriedAllows ?? []).filter((c) => c.kind !== undefined),
     });
     const failures = r.ok ? [] : verificationFailures(r);
     const blocking = r.ok
@@ -716,8 +756,47 @@ async function rederiveHelperOutcome(record) {
             unextractedDuplicateSites: r.unextractedDuplicates.reduce((n, d) => n + d.sites.length, 0),
         }
         : {};
+    // The repository's own modules the spec imports, measured now like everything
+    // else, with the agent's declarations attached and labelled as such by the type.
+    const inHouse = r.inHouse
+        ? {
+            modules: r.inHouse.modules.map((m) => utilsFileLabel([m])),
+            helpersUsed: r.inHouse.resolved,
+            helpersAdded: r.inHouse.added.map((a) => ({
+                module: utilsFileLabel([a.file]),
+                helper: a.helper,
+            })),
+            helpersWidened: r.inHouse.widened.map((a) => ({
+                module: utilsFileLabel([a.file]),
+                helper: a.helper,
+            })),
+            additiveGateRan: r.inHouse.additiveGateRan,
+            ...(record.utils?.inHouseDeclared
+                ? {
+                    filesRead: record.utils.inHouseDeclared.filesRead,
+                    ...(record.utils.inHouseDeclared.declined.length > 0
+                        ? { declined: record.utils.inHouseDeclared.declined }
+                        : {}),
+                }
+                : {}),
+            // With no Skyramp module there is no helpers row to carry the verdict.
+            ...(r.utilsFiles.length === 0
+                ? {
+                    verification: r.ok
+                        ? HelperVerificationOutcome.Passed
+                        : HelperVerificationOutcome.Failed,
+                    ...(r.ok ? {} : { verificationFailures: failures }),
+                }
+                : {}),
+        }
+        : undefined;
     if (r.utilsFiles.length === 0)
-        return { outcome: unextracted, blocking };
+        return {
+            outcome: { ...unextracted, ...(inHouse ? { inHouse } : {}) },
+            blocking,
+            carriedConsumed: r.carriedConsumed,
+            carriedEvaluated: true,
+        };
     // Two faults, two fields: a deleted guard is not a lost assertion, and a reader
     // acting on the row must not be sent after the wrong one. The count is MEASURED:
     // a `reuse-verify: allow` marker documents a loss and clears the verdict, it does
@@ -726,6 +805,8 @@ async function rederiveHelperOutcome(record) {
     const assertionLoss = [...r.violations, ...r.allowed].some((v) => v.kind === "assertion-loss");
     const guardRemoved = r.violations.some((v) => v.kind === "guard-removed");
     return {
+        carriedConsumed: r.carriedConsumed,
+        carriedEvaluated: true,
         outcome: {
             ...unextracted,
             helpers: {
@@ -750,6 +831,7 @@ async function rederiveHelperOutcome(record) {
                     : HelperVerificationOutcome.Failed,
                 ...(r.ok ? {} : { verificationFailures: failures }),
             },
+            ...(inHouse ? { inHouse } : {}),
         },
         blocking,
     };
@@ -817,44 +899,61 @@ async function coverageFrom(testFilePath, specContent) {
     }
 }
 /**
- * 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.
- *
- * The two can differ: the execution fix-up may restore `<testFile>.raw.bak` over
- * the spec after verification, reverting every substitution with a plain `cp` that
- * this tool never sees. Trusting the recorded counts there would publish
- * `callsReused: 5, verification: "passed"` for a spec containing no POM calls —
- * a confident false claim, strictly worse than the silence this feature replaced.
- * Re-deriving here rather than requiring a final `verify: true` pass is deliberate:
- * the report step always runs, so the agent cannot skip it.
+ * The shared-helper record for a delivered test that has NO reuse record — derived
+ * from the file's own imports.
  *
- * `candidatesDetected` is kept as recorded — it counts POM FILES that detection
- * found, which a restore does not change. Everything else comes from the file.
+ * The record the report normally carries is written by the verify pass, so a row
+ * only got one when the agent chose to call `skyramp_reuse_code` with
+ * `verify: true` on that file. That keys the report on the tool's activity rather
+ * than on the product: a contract test whose delivered file imports and calls three
+ * helpers reported `reuse: null`, which a reader cannot tell from "did not reuse".
  *
- * `verification` is dropped when the delivered spec reuses nothing: a PASSED
- * verdict describes a spec that no longer exists, and pairing it with a zero count
- * reads as though the empty result had been blessed.
+ * So where no record exists, the row is answered from the delivered file instead.
+ * What this can state is exactly what the file proves — which module, which helpers
+ * taken from it. It states NO `verification`: nothing verified this spec, and an
+ * optional member that is absent means "not measured", never "false". It raises no
+ * blocking verdict for the same reason — a file the gates never walked must not
+ * start failing a report at submission time.
  *
- * Returns the recorded outcome minus internals when re-derivation is impossible
- * (no path recorded — now only the no-POM-layer path, which has no spec to measure
- * and no candidates to contrast against), and no outcome when it fails outright.
- * Failing closed matters: falling back to the recorded counts is exactly the false
- * claim this exists to prevent.
+ * Returns `notDerived` with a stated reason where the file cannot answer, because a
+ * bare `null` is indistinguishable from "did not reuse" and is read as a fault.
  *
- * Beside the outcome comes the blocking verdict the delivered files earn under the
- * live check — see {@link ReuseBlockingVerdict}. One measurement feeds both: the row
- * the report publishes and the refusal `skyramp_submit_report` returns. That half
- * fails OPEN like every reuse check: a re-derivation that throws yields no outcome
- * and no verdict. A verifier that cannot run is not evidence against the file, and
- * refusing a report on a malfunction would deliver nothing to the customer.
+ * The reason names what was LOOKED AT, not what exists. `locateUtilsFiles` returns
+ * the modules this run wrote or changed beside the spec, plus the ones the spec
+ * imports — it does not enumerate the directory, so a clean tracked module beside a
+ * spec that imports nothing is not among them. Saying "no module was found here"
+ * would assert a sweep that did not happen, which is the same overclaim as the row
+ * this function exists to replace.
  */
-export async function rederiveReuse(record) {
+export async function deriveReuseFromDelivered(testFile, language) {
+    // The shared module gets a report row of its own (the `skyrampUtils.ts` UPDATE or
+    // VERIFY row). It is not a test and has no reuse to state, so it gets nothing —
+    // the row stays as it is. A reason here would read as a fault on a file that has
+    // none, which is the mistake this whole function exists to stop making.
+    if (await hasUtilsHeader(testFile))
+        return {};
+    const read = await readDeliveredImports({ testFile, language });
+    if ("reason" in read)
+        return { notDerived: read.reason };
+    if (read.utilsFiles.length === 0)
+        return {
+            notDerived: "no shared helper module was located for this test: this run wrote or changed none beside it, and it imports none",
+        };
+    return {
+        helpers: {
+            utilsFile: utilsFileLabel(read.utilsFiles),
+            helpersImported: read.importedNames.length,
+            helperNames: read.importedNames,
+        },
+    };
+}
+export async function rederiveReuse(record, carriedAllows) {
     const { candidatesDetected, verification, flagged, testFilePath, language } = record;
     // 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);
+            return await rederiveHelperOutcome(record, carriedAllows);
         }
         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) });
@@ -870,7 +969,9 @@ export async function rederiveReuse(record) {
     try {
         const r = await verifyReuse(testFilePath, language);
         const specContent = await readFile(testFilePath, "utf8");
-        const blocking = await pomBlockingVerdict(testFilePath, language, r);
+        const carriedKeptInline = (carriedAllows ?? []).filter((c) => c.keptInline !== undefined);
+        const classification = { covered: new Set(), ran: false };
+        const blocking = await pomBlockingVerdict(testFilePath, language, r, carriedKeptInline.map((c) => c.keptInline), classification);
         // Diagnose the file the report is actually built from. A marker the zero-reuse
         // gate accepts but this cannot parse satisfies the escape hatch while its
         // decline never reaches the report — silent signal loss is the failure class
@@ -880,7 +981,19 @@ export async function rederiveReuse(record) {
             logger.warning("Malformed `// kept inline:` marker(s) in the delivered spec — these declines will be missing from the PR report. " +
                 "Use `// kept inline: <file basename> — <reason>` (em dash, or a hyphen with spaces around it).", { testFile: testFilePath, markers: unparsable });
         }
-        const skipped = buildSkipped(specContent, flagged);
+        // Declines this run removed from the spec before delivery are put back for the
+        // REPORT, not for the file. `buildSkipped` reads the markers out of the delivered
+        // spec and this run took them out, so without this the report loses a decline it
+        // disclosed on the submission that stripped it.
+        //
+        // Fed through `buildSkipped` rather than appended: that function also decides
+        // `declinedBy`, and sometimes `member`. A raw append emitted neither, so two
+        // identical submissions produced different reports.
+        const carriedMarkers = (carriedAllows ?? [])
+            .filter((c) => c.keptInline !== undefined)
+            .map((c) => `// kept inline: ${c.keptInline} — ${c.reason}`)
+            .join("\n");
+        const skipped = buildSkipped(carriedMarkers ? `${specContent}\n${carriedMarkers}\n` : specContent, flagged);
         const coverage = await coverageFrom(testFilePath, specContent);
         const reuseHappened = r.reusedCalls > 0;
         const outcome = {
@@ -918,7 +1031,18 @@ export async function rederiveReuse(record) {
             ...(blocking ? { verificationFailures: blocking.failures } : {}),
             skipped: skipped.length > 0 ? skipped : undefined,
         };
-        return { outcome, blocking };
+        return {
+            outcome,
+            blocking,
+            // A kept-inline decline is consumed when the candidate it names is still one the
+            // gate would otherwise report. One that covers nothing is retired with the rest.
+            carriedConsumed: carriedKeptInline.filter((c) => classification.covered.has(c.keptInline)),
+            // Only where the gate WALKED the candidates. The infra gate takes precedence
+            // over it, an unknown language skips it and a scoping failure falls back — each
+            // leaves nothing covered while classifying nothing, and retiring on that deletes
+            // permission for a candidate still undocumented in the spec.
+            carriedEvaluated: classification.ran,
+        };
     }
     catch (err) {
         logger.warning("Could not re-derive the POM-reuse outcome from the delivered spec — omitting the reuse summary rather than reporting counts that may no longer hold", { testFile: testFilePath, error: String(err) });
@@ -943,7 +1067,11 @@ export async function rederiveReuse(record) {
  * record that never held it. Fails open when a gate throws — a gate that cannot run
  * is no evidence.
  */
-async function pomBlockingVerdict(testFile, language, r) {
+async function pomBlockingVerdict(testFile, language, r, carriedKeptInline, 
+/** Filled with what the zero-reuse gate did — see `zeroReuseGateFailure`. `ran`
+ *  stays false on every path that returns before the candidate walk, including the
+ *  unknown language and the infra-gate precedence below. */
+classification) {
     // The record's language was written from the reuse tool's validated `language`
     // param, but the record type keeps it a string: a value outside the enum means a
     // check that cannot run, and a check that cannot run does not block.
@@ -962,7 +1090,9 @@ async function pomBlockingVerdict(testFile, language, r) {
     try {
         infra = await infraGateFailure(target, r);
         zero =
-            infra === undefined ? await zeroReuseGateFailure(target, r) : undefined;
+            infra === undefined
+                ? await zeroReuseGateFailure(target, r, carriedKeptInline, classification)
+                : undefined;
     }
     catch (err) {
         logger.warning("Report-time POM gate threw — not refusing the report on a check that could not run", { testFile, error: String(err) });

package/build/tools/code-refactor/utils-verify-gates.d.ts

@@ -19,6 +19,10 @@ export interface UtilsVerifyContext {
     staged?: string[];
     /** Utils files `git add` refused in a testbot run — a failed verification on its own. */
     unstaged?: string[];
+    /** The repository's own modules this run changed that `git add` refused. Rendered
+     *  apart from `unstaged`: the remedy for a Skyramp module (move it, un-ignore it)
+     *  is an edit to the customer's repository when the file is theirs. */
+    unstagedInHouse?: string[];
     /** Whether the verdict reached run state. When it did not, the checkpoints fail
      *  open on the unwritable state file — the agent is told rather than left to loop. */
     recorded?: boolean;