@skyramp/mcp 0.3.2-rc.pom-4 → 0.3.2

package/build/tool-phases.js

@@ -11,7 +11,11 @@ export const TOOL_PHASE_MAP = {
     skyramp_ui_test_generation: "generating",
     skyramp_batch_scenario_test_generation: "generating",
     skyramp_mock_generation: "generating",
+    skyramp_batch_mock_generation: "generating",
+    skyramp_generate_enriched_integration_test: "generating",
+    skyramp_enrich_test_with_mocks: "generating",
     skyramp_execute_test: { before: "maintaining", after: "executing" },
+    skyramp_run_existing_tests: { before: "maintaining", after: "executing" },
     skyramp_analyze_test_health: "maintaining",
     skyramp_submit_report: "reporting",
 };
@@ -30,6 +34,7 @@ export const TOOLS_WITHOUT_PHASE = new Set([
     "skyramp_init_scan",
     "skyramp_init_workspace",
     "skyramp_one_click_tool",
+    "skyramp_setup_local_dev_worker",
     "skyramp_actions",
     "skyramp_start_trace_collection",
     "skyramp_stop_trace_collection",
@@ -37,4 +42,6 @@ export const TOOLS_WITHOUT_PHASE = new Set([
     "skyramp_modularization",
     "skyramp_reuse_code",
     "skyramp_enhance_assertions",
+    "skyramp_preflight_mock_check",
+    "skyramp_query_proxy_mocks",
 ]);

package/build/tools/code-refactor/codeReuseTool.js

@@ -4,9 +4,11 @@ import { getCodeReusePrompt, isPomAwareTarget } from "../../prompts/code-reuse.j
 import { selectScopedPoms } from "../../utils/pom-scope/index.js";
 import { verifyReuse } from "../../utils/pom-verify/index.js";
 import { infraGateFailure, zeroReuseGateFailure, composeVerifyText } from "./verify-gates.js";
+import { recordCandidates, recordNoPomLayer, recordVerifyOutcome } from "./reuse-state.js";
 import { codeRefactoringSchema, languageSchema, } from "../../types/TestTypes.js";
 import { SKYRAMP_UTILS_HEADER } from "../../utils/utils.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { isPomReuseEnabled } from "../../utils/featureFlags.js";
 import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 const codeReuseSchema = z.object({
     testFile: z
@@ -25,6 +27,12 @@ const codeReuseSchema = z.object({
         .describe("Verify a previously written refactored test's POM calls against source instead of returning the reuse prompt"),
 });
 const TOOL_NAME = "skyramp_reuse_code";
+// Only advertised when SKYRAMP_FEATURE_POM_REUSE=1 — with the flag off this tool
+// never takes the POM path, so describing it would promise behavior it won't do.
+const POM_AWARE_MODE_DESCRIPTION = `
+
+      **POM-AWARE MODE (TypeScript/JavaScript + Playwright):**
+      For projects with \`language: "typescript" or "javascript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` / \`*.page.js\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization — on this path that supersedes WORKFLOW SUMMARY step 6.`;
 export function registerCodeReuseTool(server) {
     server.registerTool(TOOL_NAME, {
         description: `Analyzes code for reuse opportunities and enforces code reuse principles.
@@ -57,10 +65,7 @@ export function registerCodeReuseTool(server) {
 
       **MANDATORY**: ONLY ALLOW CODE REUSE IF THE IS TRACE BASED FLAG IS SET TO TRUE ELSE DO NOT ALLOW CODE REUSE AND LEAVE THE TEST FILE AS IS.
       **CRITICAL**: NON TRACE BASED TESTS ARE ALREADY MODULARIZED AND DO NOT NEED CODE REUSE.
-      The tool will provide step-by-step instructions that MUST be followed exactly.
-
-      **POM-AWARE MODE (TypeScript/JavaScript + Playwright):**
-      For projects with \`language: "typescript" or "javascript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` / \`*.page.js\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization.`,
+      The tool will provide step-by-step instructions that MUST be followed exactly.${isPomReuseEnabled() ? POM_AWARE_MODE_DESCRIPTION : ""}`,
         inputSchema: codeReuseSchema.shape,
         _meta: {
             keywords: [
@@ -75,9 +80,26 @@ export function registerCodeReuseTool(server) {
         let errorResult;
         try {
             if (params.verify) {
+                // The verify pass is POM-only, and it is the sole writer of the report's
+                // reuse summary — so with the flag off a stale instruction to verify must
+                // not run it, or a POM-less run would still emit POM reuse numbers.
+                if (!isPomReuseEnabled()) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "VERIFICATION SKIPPED — POM-aware code reuse is disabled. Nothing to verify; continue.",
+                            },
+                        ],
+                    };
+                }
                 try {
                     const r = await verifyReuse(params.testFile, params.language);
                     const gate = (await infraGateFailure(params, r)) ?? (await zeroReuseGateFailure(params, r));
+                    // Record what this pass established before returning the text report:
+                    // every number in it is already in hand here, so the agent is never
+                    // asked to read one back out and retype it later.
+                    await recordVerifyOutcome(params.testFile, r, gate !== undefined, params.language);
                     return { content: [{ type: "text", text: composeVerifyText(gate, r) }] };
                 }
                 catch (err) {
@@ -110,11 +132,28 @@ export function registerCodeReuseTool(server) {
                     });
                     if (tier1.length + tier2.length > 0) {
                         scopedPoms = { tier1, tier2 };
+                        // Only report candidates found through the conventional POM globs.
+                        //
+                        // The selector-grep fallback also matches ordinary in-repo frontend
+                        // source — app components legitimately contain the spec's test-ids by
+                        // construction — so in a repo with no page-object layer at all it still
+                        // yields "candidates". Reporting those would render, on a POM-less repo,
+                        // "4 candidate POM files detected" next to zero reuse: each number true
+                        // in isolation, but together they assert reusable page objects existed
+                        // and were ignored. `zeroReuseGateFailure` already draws this exact line
+                        // for the same reason; the report has to draw it too.
+                        //
+                        // The agent is still handed the grep-discovered files to consider —
+                        // only the customer-facing count is withheld.
+                        if (diagnostics.discovery === "globs") {
+                            await recordCandidates(params.testFile, tier1.length);
+                        }
                     }
                     else if (diagnostics.selectors > 0 && diagnostics.discovery !== "skipped-too-large") {
                         // A clean scan ran (glob or selector-grep) and found zero overlap — distinct from
                         // "scoping wasn't attempted" (no selectors) or "scan was skipped" (repo too large).
                         scopedPoms = { tier1: [], tier2: [], scannedNoOverlap: true };
+                        await recordNoPomLayer(params.testFile);
                     }
                     logger.info("POM pre-scoping", {
                         ...diagnostics,

package/build/tools/code-refactor/enhanceAssertionsTool.js

@@ -5,6 +5,7 @@ import { getContractProviderAssertionsPrompt } from "../../prompts/enhance-asser
 import { getIntegrationAssertionsPrompt } from "../../prompts/enhance-assertions/integrationAssertionsPrompt.js";
 import { getUIAssertionsPrompt } from "../../prompts/enhance-assertions/uiAssertionsPrompt.js";
 import { isTestbotEnabled } from "../../utils/featureFlags.js";
+import { renderSharedAssertionRules } from "../../prompts/enhance-assertions/sharedAssertionRules.js";
 import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 const TOOL_NAME = "skyramp_enhance_assertions";
 const TESTBOT_UI_CHECKS = `
@@ -12,6 +13,37 @@ const TESTBOT_UI_CHECKS = `
 - If no suitable selector exists in the generated file for an assertion you need to add, go back and call \`browser_assert\` on the live page to record it with a valid selector, then re-export and regenerate.
 - **After executing a UI test that documents a bug from \`issuesFound\`**: if it passed when you expected it to fail, the assertions are too weak — add a stronger \`expect()\` that directly targets the buggy behavior. This counts as the single allowed retry under the 2-attempt cap — do NOT re-run more than once.
 `;
+function buildAssertionInstructions(testFile, testType, enhanceType) {
+    if (testType === TestType.UI) {
+        let instructions = getUIAssertionsPrompt(testFile, enhanceType);
+        if (isTestbotEnabled()) {
+            instructions += TESTBOT_UI_CHECKS;
+        }
+        return instructions;
+    }
+    if (testType === TestType.CONTRACT) {
+        return getContractProviderAssertionsPrompt(testFile, enhanceType);
+    }
+    if (testType === TestType.INTEGRATION) {
+        return getIntegrationAssertionsPrompt(testFile, enhanceType);
+    }
+    throw new Error(`Unsupported testType for ${TOOL_NAME}: ${testType}`);
+}
+function buildAutoApplyInstructions(testFile, testType, enhanceType) {
+    const typeSpecificInstructions = buildAssertionInstructions(testFile, testType, enhanceType);
+    return [
+        `Enhance response body assertions in: \`${testFile}\``,
+        `Test type: ${testType} | Context: ${enhanceType}`,
+        ``,
+        `Read the file, apply the type-specific assertion guidance below, and write the file back directly.`,
+        `Add assertions after each send_request/sendRequest status-code assertion.`,
+        `Use SDK helper: Python \`skyramp.get_response_value(response, "json.path")\`, JS \`getValue(response, "json.path")\`.`,
+        `Do NOT restructure, reformat, add comments, or change imports. Only add assertion lines.`,
+        ``,
+        `Type-specific assertion guidance:`,
+        typeSpecificInstructions,
+    ].join("\n");
+}
 const enhanceAssertionsSchema = {
     testFile: z
         .string()
@@ -24,6 +56,12 @@ const enhanceAssertionsSchema = {
         .describe("The context of the enhancement. " +
         "Use 'generation' after generating a new test file (applies to every test function). " +
         "Use 'maintenance' during drift UPDATE (applies only to new or diff-affected functions)."),
+    autoApply: z
+        .boolean()
+        .default(false)
+        .describe("When true, returns a compact instruction set (10 lines) that tells the agent to " +
+        "read the test file, enhance assertions per standard rules, and write it back directly. " +
+        "When false (default), returns the full verbose instruction set."),
 };
 export function registerEnhanceAssertionsTool(server) {
     server.registerTool(TOOL_NAME, {
@@ -34,26 +72,33 @@ export function registerEnhanceAssertionsTool(server) {
 - After updating an existing supported test file during maintenance`,
         inputSchema: enhanceAssertionsSchema,
     }, async (params) => {
-        const { testFile, testType, enhanceType } = params;
+        const { testFile, testType, enhanceType, autoApply } = params;
         // Stage so testbot includes the generated files in its output commit.
         await stageGeneratedPaths(testFile);
-        const enhanceCtx = enhanceType;
-        let instructions;
-        if (testType === TestType.UI) {
-            instructions = getUIAssertionsPrompt(testFile, enhanceCtx);
-            if (isTestbotEnabled()) {
-                instructions += TESTBOT_UI_CHECKS;
-            }
-        }
-        else if (testType === TestType.CONTRACT) {
-            instructions = getContractProviderAssertionsPrompt(testFile, enhanceCtx);
-        }
-        else if (testType === TestType.INTEGRATION) {
-            instructions = getIntegrationAssertionsPrompt(testFile, enhanceCtx);
-        }
-        else {
-            throw new Error(`Unsupported testType for ${TOOL_NAME}: ${testType}`);
+        if (autoApply) {
+            const compactInstructions = [
+                `Enhance response body assertions in: \`${testFile}\``,
+                `Test type: ${testType} | Context: ${enhanceType}`,
+                ``,
+                `Read the file, add assertions after each send_request/sendRequest status-code assertion, write it back.`,
+                `Use SDK helper: Python \`skyramp.get_response_value(response, "json.path")\`, JS \`getValue(response, "json.path")\`.`,
+                ``,
+                `Shared assertion rules (apply all that fit):`,
+                renderSharedAssertionRules(),
+                ``,
+                `Do NOT restructure, reformat, add comments, or change imports. Only add assertion lines.`,
+            ].join("\n");
+            const result = {
+                content: [{ type: "text", text: compactInstructions }],
+                isError: false,
+            };
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, { testFile: params.testFile, testType: params.testType, enhanceType: params.enhanceType, autoApply: Boolean(params.autoApply) }).catch(() => { });
+            return result;
         }
+        const enhanceCtx = enhanceType;
+        const instructions = autoApply
+            ? buildAutoApplyInstructions(testFile, testType, enhanceCtx)
+            : buildAssertionInstructions(testFile, testType, enhanceCtx);
         const result = {
             content: [
                 {
@@ -63,7 +108,12 @@ export function registerEnhanceAssertionsTool(server) {
             ],
             isError: false,
         };
-        AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, params).catch(() => { });
+        AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, {
+            testFile: params.testFile,
+            testType: params.testType,
+            enhanceType: params.enhanceType,
+            autoApply: Boolean(params.autoApply),
+        }).catch(() => { });
         return result;
     });
 }

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

@@ -0,0 +1,109 @@
+import type { VerifyResult } from "../../utils/pom-verify/index.js";
+import { ReuseVerificationOutcome, type ReuseSkippedEntry } from "../../types/ReuseOutcome.js";
+export { ReuseDeclinedBy, ReuseVerificationOutcome, type ReuseOutcome, type ReuseSkippedEntry, } from "../../types/ReuseOutcome.js";
+/** A member the verifier flagged at some point in this run. NOT the same as "a
+ *  member that was demoted": the workflow allows one remap attempt, so a flagged
+ *  member may have been fixed rather than restored to raw inline. Only a
+ *  `// kept inline:` marker proves a decline; this list can at most say which
+ *  member a decline was about. */
+export interface FlaggedMember {
+    pageObject: string;
+    member: string;
+}
+/**
+ * What run state holds between the verify pass and the report step.
+ *
+ * Deliberately NOT an extension of {@link ReuseOutcome}: it is a disjoint type
+ * holding only what cannot be recomputed from the delivered spec. Two reasons.
+ *
+ * Anything recomputable must not be stored, because storing it makes it stale the
+ * moment the spec changes — and it does change: the execution fix-up may restore
+ * `<testFile>.raw.bak` over the spec by plain `cp`, invisible to this tool. The
+ * counts and the decline list are therefore derived at report time (see
+ * `rederiveReuseOutcome`), never read back from here.
+ *
+ * And keeping the two types disjoint makes the report boundary opt-IN. When the
+ * record extended the wire type, every field added here shipped to the
+ * customer-facing report unless someone remembered to widen a destructure — a
+ * default that quietly asserts something, which is the same shape as the
+ * file-level attribution bug this module already had once. Now adding a field is
+ * a type error at the construction site instead.
+ */
+export interface ReuseRecord {
+    /** Tier-1 POM candidate FILES detection found. Not recoverable from the spec:
+     *  it describes what was available to reuse, not what was reused. */
+    candidatesDetected?: number;
+    /** Needs `gateFired`, which only the verify call knows. */
+    verification?: ReuseVerificationOutcome;
+    /** Members the verifier flagged, accumulated across this run's verify passes —
+     *  by the time verification PASSES the violations are gone, so a member that was
+     *  substituted and then restored survives only as a `// kept inline:` comment,
+     *  indistinguishable from one the mapper never promoted.
+     *
+     *  Named for what it holds, not for what it is used to infer: FLAGGED is weaker
+     *  than "demoted" (see {@link FlaggedMember}). Calling it `demoted` is what
+     *  licensed attributing a whole file's declines to one member — do not rename it
+     *  back. */
+    flagged?: FlaggedMember[];
+    /** Identity of the spec to re-derive from, and the language to parse it as. */
+    testFilePath?: string;
+    language?: string;
+}
+/**
+ * Every well-formed `// kept inline: <basename> — <reason>` marker in a spec.
+ *
+ * Deliberately separate from `isKeptInlineDocumented` (verify-gates.ts) rather
+ * than replacing it: that one asks "is THIS known basename documented", so it can
+ * anchor on the basename and never has to guess where the name ends. Loosening the
+ * gate's predicate to share this regex would change when the zero-reuse escape
+ * hatch fires, which is not a side effect worth taking for deduplication — but see
+ * `findUnparsableKeptInline` for how the gap between them is kept visible.
+ */
+export declare function parseKeptInline(specContent: string): {
+    pageObject: string;
+    reason: string;
+}[];
+/**
+ * Lines that announce a kept-inline decline but that `parseKeptInline` cannot
+ * read — a missing reason clause, or a bare unspaced hyphen the zero-reuse gate's
+ * looser predicate would still accept.
+ *
+ * Such a marker satisfies the escape hatch (no gate failure, the agent proceeds)
+ * while the decline never reaches the report: silent signal loss, which is exactly
+ * the failure class this feature exists to close. Callers log these rather than
+ * dropping them quietly.
+ */
+export declare function findUnparsableKeptInline(specContent: string): string[];
+/** Members the verifier flagged in one pass, keyed to the file a decline comment
+ *  would name. */
+export declare function flaggedFrom(r: VerifyResult): FlaggedMember[];
+/** Union two flagged-member lists, deduplicated. */
+export declare function mergeFlagged(prior: FlaggedMember[] | undefined, next: FlaggedMember[]): FlaggedMember[];
+/**
+ * Build the `skipped` list for a spec: one entry per documented kept-inline
+ * marker — markers are the only ground truth for "this was actually left inline".
+ *
+ * Attribution is deliberately conservative, and only labels a decline when the
+ * correspondence is exact — one marker for that file and one flagged member for
+ * it:
+ *
+ *  - No member of the file was ever flagged → the mapper never promoted it,
+ *    `not-mapped`. Unambiguous: a flagged member implies it had been substituted.
+ *  - Exactly one marker and one flagged member → that marker is that member,
+ *    `demoted-by-verify`.
+ *  - Anything else → the entry keeps its reason but carries no `member` and no
+ *    `declinedBy`. Several markers on one file (S-01b's shape: a demote and an
+ *    abstention on the same class) give no way to say which marker is which
+ *    member, and a flagged member may have been remapped successfully rather than
+ *    demoted, so a count mismatch is not even reliably a mixed-cause file.
+ *
+ * Guessing here is worse than omitting: a wrong member under a confident
+ * "demoted by verification" label sends a reviewer chasing a decline that never
+ * happened, which is the multi-hour log dig this field exists to end.
+ */
+export declare function buildSkipped(specContent: string, flagged: FlaggedMember[] | undefined): ReuseSkippedEntry[];
+/** The verdict for a verify pass. A fired compliance gate is a failure regardless
+ *  of the raw result; otherwise `r.ok` decides. `skipped-no-pom` is not reachable
+ *  here — it is recorded on the prompt-generation call, where "no reusable POM
+ *  layer detected" is determined. */
+export declare function verificationFrom(gateFired: boolean, r: VerifyResult): ReuseVerificationOutcome;

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

@@ -0,0 +1,158 @@
+import * as path from "path";
+import { stripStrings } from "../../utils/pom-scope/strip.js";
+import { ReuseDeclinedBy, ReuseVerificationOutcome, } from "../../types/ReuseOutcome.js";
+/**
+ * Server-side derivation of a UI test's POM code-reuse outcome.
+ *
+ * The counts and verdicts here are all computed in-process by `skyramp_reuse_code`
+ * already — tier-1 detection by `selectScopedPoms`, the call counts and violations
+ * by `verifyReuse`, the demote/abstain record by the `// kept inline:` comments in
+ * the spec the tool just read. Routing them through the agent (read four integers
+ * out of tool text, hold them across the rest of the run, retype them into a later
+ * call) is still prose-mediated and still droppable, which is the failure this
+ * whole feature exists to fix. So they are persisted to run state and merged into
+ * the report server-side, exactly as `beforeStatus`/`afterStatus` are.
+ *
+ * The agent supplies nothing here.
+ */
+/** Separator between composite-key parts. `\0` cannot occur in a file name or a
+ *  reason clause, so it cannot collide — written as an escape, never as a literal
+ *  control byte, or git classifies this source file as binary. */
+const KEY_SEP = "\0";
+// The wire shape lives in types/ (and is re-exported from types/index.ts for
+// consumers). Re-exported here so this module stays the one place to look when
+// working on the derivation.
+export { ReuseDeclinedBy, ReuseVerificationOutcome, } from "../../types/ReuseOutcome.js";
+/** Matches a well-formed `// kept inline: <basename> <sep> <reason>` marker.
+ *
+ *  The separator must be an em/en dash or a *spaced* hyphen. Discovery has no
+ *  anchor to tell where the file name ends, and a bare hyphen is ambiguous with
+ *  hyphens inside file names (`alert-destinations.page.ts-reason`), so requiring
+ *  whitespace is what makes the split decidable. `findUnparsableKeptInline` below
+ *  reports anything that looks like a marker but does not match, so a malformed
+ *  one is never silently lost. */
+const KEPT_INLINE_RE = /\/\/\s*kept inline:\s*(\S.*?)\s*(?:[—–]+|\s+-+\s+)\s*(\S.*?)\s*$/;
+/** Lines that look like a kept-inline marker. Deliberately looser than
+ *  KEPT_INLINE_RE so the difference between the two is detectable. */
+const KEPT_INLINE_LOOSE_RE = /\/\/\s*kept inline:/;
+/** Comment lines only — a marker quoted inside a string literal is not a real
+ *  marker, the same reasoning as the zero-reuse gate's predicate. */
+function commentLines(specContent) {
+    return stripStrings(specContent).split("\n");
+}
+/**
+ * Every well-formed `// kept inline: <basename> — <reason>` marker in a spec.
+ *
+ * Deliberately separate from `isKeptInlineDocumented` (verify-gates.ts) rather
+ * than replacing it: that one asks "is THIS known basename documented", so it can
+ * anchor on the basename and never has to guess where the name ends. Loosening the
+ * gate's predicate to share this regex would change when the zero-reuse escape
+ * hatch fires, which is not a side effect worth taking for deduplication — but see
+ * `findUnparsableKeptInline` for how the gap between them is kept visible.
+ */
+export function parseKeptInline(specContent) {
+    const out = [];
+    const seen = new Set();
+    for (const line of commentLines(specContent)) {
+        const m = KEPT_INLINE_RE.exec(line);
+        if (!m)
+            continue;
+        const pageObject = path.basename(m[1].trim());
+        const reason = m[2].trim();
+        const key = `${pageObject}${KEY_SEP}${reason}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ pageObject, reason });
+    }
+    return out;
+}
+/**
+ * Lines that announce a kept-inline decline but that `parseKeptInline` cannot
+ * read — a missing reason clause, or a bare unspaced hyphen the zero-reuse gate's
+ * looser predicate would still accept.
+ *
+ * Such a marker satisfies the escape hatch (no gate failure, the agent proceeds)
+ * while the decline never reaches the report: silent signal loss, which is exactly
+ * the failure class this feature exists to close. Callers log these rather than
+ * dropping them quietly.
+ */
+export function findUnparsableKeptInline(specContent) {
+    return commentLines(specContent)
+        .filter((line) => KEPT_INLINE_LOOSE_RE.test(line) && !KEPT_INLINE_RE.test(line))
+        .map((line) => line.trim());
+}
+/** Members the verifier flagged in one pass, keyed to the file a decline comment
+ *  would name. */
+export function flaggedFrom(r) {
+    const out = [];
+    for (const v of r.violations) {
+        const file = v.searched[0];
+        if (file)
+            out.push({ pageObject: path.basename(file), member: `${v.binding}.${v.member}` });
+    }
+    return out;
+}
+/** Union two flagged-member lists, deduplicated. */
+export function mergeFlagged(prior, next) {
+    const byKey = new Map();
+    for (const d of [...(prior ?? []), ...next]) {
+        byKey.set(`${d.pageObject}${KEY_SEP}${d.member}`, d);
+    }
+    return [...byKey.values()];
+}
+function countByFile(items) {
+    const counts = new Map();
+    for (const i of items)
+        counts.set(i.pageObject, (counts.get(i.pageObject) ?? 0) + 1);
+    return counts;
+}
+/**
+ * Build the `skipped` list for a spec: one entry per documented kept-inline
+ * marker — markers are the only ground truth for "this was actually left inline".
+ *
+ * Attribution is deliberately conservative, and only labels a decline when the
+ * correspondence is exact — one marker for that file and one flagged member for
+ * it:
+ *
+ *  - No member of the file was ever flagged → the mapper never promoted it,
+ *    `not-mapped`. Unambiguous: a flagged member implies it had been substituted.
+ *  - Exactly one marker and one flagged member → that marker is that member,
+ *    `demoted-by-verify`.
+ *  - Anything else → the entry keeps its reason but carries no `member` and no
+ *    `declinedBy`. Several markers on one file (S-01b's shape: a demote and an
+ *    abstention on the same class) give no way to say which marker is which
+ *    member, and a flagged member may have been remapped successfully rather than
+ *    demoted, so a count mismatch is not even reliably a mixed-cause file.
+ *
+ * Guessing here is worse than omitting: a wrong member under a confident
+ * "demoted by verification" label sends a reviewer chasing a decline that never
+ * happened, which is the multi-hour log dig this field exists to end.
+ */
+export function buildSkipped(specContent, flagged) {
+    const markers = parseKeptInline(specContent);
+    const markerCounts = countByFile(markers);
+    const flaggedByFile = new Map();
+    for (const f of flagged ?? []) {
+        const members = flaggedByFile.get(f.pageObject) ?? [];
+        members.push(f.member);
+        flaggedByFile.set(f.pageObject, members);
+    }
+    return markers.map(({ pageObject, reason }) => {
+        const members = flaggedByFile.get(pageObject) ?? [];
+        if (members.length === 0) {
+            return { pageObject, declinedBy: ReuseDeclinedBy.NotMapped, reason };
+        }
+        if (members.length === 1 && markerCounts.get(pageObject) === 1) {
+            return { pageObject, member: members[0], declinedBy: ReuseDeclinedBy.DemotedByVerify, reason };
+        }
+        return { pageObject, reason };
+    });
+}
+/** The verdict for a verify pass. A fired compliance gate is a failure regardless
+ *  of the raw result; otherwise `r.ok` decides. `skipped-no-pom` is not reachable
+ *  here — it is recorded on the prompt-generation call, where "no reusable POM
+ *  layer detected" is determined. */
+export function verificationFrom(gateFired, r) {
+    return !gateFired && r.ok ? ReuseVerificationOutcome.Passed : ReuseVerificationOutcome.Failed;
+}

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

@@ -0,0 +1,45 @@
+import { type VerifyResult } from "../../utils/pom-verify/index.js";
+import { type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
+/** Record the tier-1 candidate count STEP 1 detected. */
+export declare function recordCandidates(testFile: string, candidatesDetected: number, explicitStateFile?: string): Promise<void>;
+/** 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",
+ *  and rendering both produces a redundant zero in the summary. */
+export declare function recordNoPomLayer(testFile: string, explicitStateFile?: string): Promise<void>;
+/**
+ * Record what one verify pass established: the call counts, the verdict, and the
+ * declines read out of the spec the verifier just parsed.
+ *
+ * `flagged` accumulates across passes because a PASSED verdict has no violations
+ * left to inspect — a member that was substituted and then restored survives only
+ * as a `// kept inline:` comment, indistinguishable from one the mapper never
+ * promoted. Accumulating is what keeps that distinction recoverable at all; it does
+ * not by itself establish it, since a flagged member may have been remapped rather
+ * than restored (see buildSkipped for how narrowly it is trusted).
+ */
+export declare function recordVerifyOutcome(testFile: string, r: VerifyResult, gateFired: boolean, language: string, explicitStateFile?: string): Promise<void>;
+/**
+ * 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.
+ *
+ * `candidatesDetected` is kept as recorded — it counts POM FILES that detection
+ * found, which a restore does not change. Everything else comes from the file.
+ *
+ * `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.
+ *
+ * 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.
+ */
+export declare function rederiveReuseOutcome(record: ReuseRecord): Promise<ReuseOutcome | undefined>;