@skyramp/mcp 0.4.1 → 0.4.2-rc.1

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

@@ -79,7 +79,7 @@ export type RepoCheckoutRef = RepoCheckout;
 export declare function findAssertionRecordByFileName(outcomes: Record<string, AssertionRecord>, row: {
     fileName: string;
     testType?: string;
-    repository?: string;
+    repository: string;
 }, checkouts: RepoCheckoutRef[]): AssertionRecord | undefined;
 /**
  * Report-facing proof-of-work summary re-derived from the spec as delivered

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

@@ -54,7 +54,7 @@ preloaded) {
         const next = patch(data.assertionOutcomes?.[key]);
         if (next === undefined)
             return false;
-        await manager.writeData({
+        await manager.appendData({
             ...data,
             assertionOutcomes: {
                 ...data.assertionOutcomes,

package/build/tools/code-refactor/assertionOperations.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The deterministic half of assertion enhancement, shared by
+ * `skyramp_enhance_assertions` and by the two single-purpose tools the
+ * `enhance-assertions` skill drives (SKYR-4310). One implementation, so the
+ * skill workflow and the original tool can never diverge on the gates, the
+ * baseline, or the verdict.
+ */
+export interface AssertionCallParams {
+    testFile: string;
+    testType: string;
+    enhanceType: string;
+    stateFile?: string;
+}
+/**
+ * Reject a relative test-file path: everything downstream keys state by this
+ * path, and a relative spelling would fork records and fail gates open
+ * (review finding on SKYR-4262). Shared with `skyramp_align_assertions`,
+ * whose post-execution check keys the same `testExecutions` state by this
+ * path but needs neither the reuse-debt gate nor the retrofit staging below,
+ * both generation-time concerns.
+ */
+export declare function requireAbsoluteTestFile(testFile: string): string | undefined;
+/**
+ * Everything both entry points must do before either branch: reject a relative
+ * path, stage the shared utils file, and run the reuse-debt gate.
+ *
+ * Returns the gate's refusal message, or undefined when the call may proceed.
+ */
+export declare function prepareAssertionCall(params: AssertionCallParams): Promise<string | undefined>;
+/**
+ * Snapshot the file as generated so a later verify pass has a baseline to
+ * measure against. Best-effort — no run state means a stateless verify later.
+ */
+export declare function snapshotAssertionBaseline(params: AssertionCallParams): Promise<void>;
+export interface AssertionVerifyOutcome {
+    ok: boolean;
+    report: string;
+}
+/**
+ * Deterministically check the hand-out instructions were applied — hash delta,
+ * no removed coverage, rubric lints, strength increase — and format the
+ * per-violation feedback that drives the fix-and-retry loop.
+ */
+export declare function verifyAssertionCall(params: AssertionCallParams): Promise<AssertionVerifyOutcome>;

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

@@ -0,0 +1,82 @@
+import * as path from "path";
+import { pendingReuseDebt } from "./reuse-state.js";
+import { baselineFrom, readAssertionRecord, recordAssertionBaseline, recordAssertionVerdict, trustedRecord, } from "./assertion-state.js";
+import { formatAssertionVerifyReport, verifyAssertionEnhancement, } from "../../utils/assertion-verify/index.js";
+import { stageAndRecordRetrofits } from "./retrofit-state.js";
+import { stageGeneratedPaths } from "../../utils/gitStaging.js";
+/**
+ * Reject a relative test-file path: everything downstream keys state by this
+ * path, and a relative spelling would fork records and fail gates open
+ * (review finding on SKYR-4262). Shared with `skyramp_align_assertions`,
+ * whose post-execution check keys the same `testExecutions` state by this
+ * path but needs neither the reuse-debt gate nor the retrofit staging below,
+ * both generation-time concerns.
+ */
+export function requireAbsoluteTestFile(testFile) {
+    if (!path.isAbsolute(testFile)) {
+        return `testFile must be an absolute path, got: ${testFile}`;
+    }
+    return undefined;
+}
+/**
+ * Everything both entry points must do before either branch: reject a relative
+ * path, stage the shared utils file, and run the reuse-debt gate.
+ *
+ * Returns the gate's refusal message, or undefined when the call may proceed.
+ */
+export async function prepareAssertionCall(params) {
+    const { testFile, testType, stateFile } = params;
+    const pathError = requireAbsoluteTestFile(testFile);
+    if (pathError)
+        return pathError;
+    // SKYR-4115: the reuse tool hands out POM mapping instructions and then relies on
+    // the agent to come back with `verify: true` — the call that runs the zero-reuse
+    // gate. This is the first tool called after it on the same spec, so it is where a
+    // skipped verify is caught cheapest. Enforcing the call (not the outcome) keeps
+    // the policy in the reuse phase where it belongs.
+    // SKYR-4220: stage the shared utils file this spec wrote or imports BEFORE the
+    // debt check, unconditionally — so the file reaches the output commit even on a
+    // path where the agent never calls verify. Located by header, not by name.
+    await stageAndRecordRetrofits(testFile);
+    const owed = await pendingReuseDebt(testFile, stateFile, testType, {
+        chain: false,
+    });
+    if (owed)
+        return owed;
+    // Stage so testbot includes the generated files in its output commit.
+    await stageGeneratedPaths(testFile);
+    return undefined;
+}
+/**
+ * Snapshot the file as generated so a later verify pass has a baseline to
+ * measure against. Best-effort — no run state means a stateless verify later.
+ */
+export async function snapshotAssertionBaseline(params) {
+    await recordAssertionBaseline(params.testFile, params.testType, params.enhanceType, params.stateFile);
+}
+/**
+ * Deterministically check the hand-out instructions were applied — hash delta,
+ * no removed coverage, rubric lints, strength increase — and format the
+ * per-violation feedback that drives the fix-and-retry loop.
+ */
+export async function verifyAssertionCall(params) {
+    const { testFile, testType, enhanceType, stateFile } = params;
+    const record = await readAssertionRecord(testFile, stateFile);
+    // Discriminators come from the persisted record when it matches this
+    // canonical path — params are agent-supplied, and flipping enhanceType
+    // to "maintenance" would disarm the strength gate and structural lints
+    // for a permanent PASS. Canonical comparison closes the alias bypass
+    // (dir//x.spec.ts). Falls back to params only when stateless.
+    const trusted = trustedRecord(record, testFile);
+    const result = await verifyAssertionEnhancement({
+        testFile,
+        testType: trusted?.testType ?? testType,
+        enhanceType: (trusted?.enhanceType ?? enhanceType),
+        baseline: baselineFrom(record, testFile),
+    });
+    await recordAssertionVerdict(testFile, result, stateFile);
+    return {
+        ok: result.ok,
+        report: formatAssertionVerifyReport(result, testFile),
+    };
+}

package/build/tools/code-refactor/assertionSkillTools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAssertionSnapshotTool(server: McpServer): void;
+export declare function registerAssertionVerifyTool(server: McpServer): void;

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

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { ASSERTION_ENHANCEABLE_TEST_TYPES } from "../../types/TestTypes.js";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { toolError } from "../../utils/utils.js";
+import { prepareAssertionCall, snapshotAssertionBaseline, verifyAssertionCall, } from "./assertionOperations.js";
+/**
+ * The two halves of `skyramp_enhance_assertions`' deterministic work, exposed
+ * as single-purpose tools so the `enhance-assertions` skill can drive the
+ * workflow itself: snapshot, apply the rules, verify (SKYR-4310).
+ *
+ * They share one implementation with the original tool, and are registered
+ * only when the skills plugin is loaded — with it off, nothing invokes them
+ * and no agent pays for their schemas.
+ */
+const SNAPSHOT_TOOL_NAME = "skyramp_enhance_assertions_snapshot";
+const VERIFY_TOOL_NAME = "skyramp_verify_enhance_assertions";
+const sharedSchema = {
+    testFile: z
+        .string()
+        .describe("Absolute path to the generated or updated test file whose assertions are being enhanced."),
+    testType: z
+        .enum(ASSERTION_ENHANCEABLE_TEST_TYPES)
+        .describe("The type of test whose assertions are being enhanced. Contract applies to provider contract tests only, not consumer contract tests."),
+    enhanceType: z
+        .enum(["generation", "maintenance"])
+        .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)."),
+    stateFile: z
+        .string()
+        .optional()
+        .describe("Path to the run state file, when the run has one."),
+};
+export function registerAssertionSnapshotTool(server) {
+    server.registerTool(SNAPSHOT_TOOL_NAME, {
+        description: `Record the assertion baseline for a test file BEFORE its assertions are enhanced. Returns no instructions — the \`enhance-assertions\` skill carries those. Call this first, apply the rules, then call ${VERIFY_TOOL_NAME}.`,
+        inputSchema: sharedSchema,
+    }, async (params) => {
+        const refusal = await prepareAssertionCall(params);
+        if (refusal)
+            return toolError(refusal);
+        await snapshotAssertionBaseline(params);
+        AnalyticsService.pushMCPToolEvent(SNAPSHOT_TOOL_NAME, undefined, {
+            testFile: params.testFile,
+            testType: params.testType,
+            enhanceType: params.enhanceType,
+        }).catch(() => { });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Assertion baseline recorded for \`${params.testFile}\`. Apply the assertion rules, then call ${VERIFY_TOOL_NAME} with the same arguments.`,
+                },
+            ],
+            isError: false,
+        };
+    });
+}
+export function registerAssertionVerifyTool(server) {
+    server.registerTool(VERIFY_TOOL_NAME, {
+        description: `Deterministically verify the assertion enhancement of a test file against the baseline ${SNAPSHOT_TOOL_NAME} recorded. Returns PASS, or FAIL with per-violation remediations. Fix every violation and call again until it passes.`,
+        inputSchema: sharedSchema,
+    }, async (params) => {
+        const refusal = await prepareAssertionCall(params);
+        if (refusal)
+            return toolError(refusal);
+        try {
+            const { ok, report } = await verifyAssertionCall(params);
+            AnalyticsService.pushMCPToolEvent(VERIFY_TOOL_NAME, undefined, {
+                testFile: params.testFile,
+                testType: params.testType,
+                enhanceType: params.enhanceType,
+                verifyPassed: ok,
+            }).catch(() => { });
+            return {
+                content: [{ type: "text", text: report }],
+                // isError on FAILED forces the fix-and-retry loop.
+                isError: !ok,
+            };
+        }
+        catch (err) {
+            // Not necessarily the test file — state reads can throw here too.
+            return toolError(`${VERIFY_TOOL_NAME} failed for ${params.testFile}: ${err.message}`);
+        }
+    });
+}

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

@@ -31,11 +31,33 @@ const codeReuseSchema = z.object({
     verify: z
         .boolean()
         .default(false)
-        .describe("Verify a previously refactored test instead of returning the reuse prompt. POM path (browser tests): checks the test's POM calls against source; requires the discovery pass — this tool called for the same testFile without `verify` — to have run first. SkyrampUtils path (every other test type): stages the shared utils file for the output commit, checks its invariants, and — when skyramp_modularization recorded a baseline for this spec — compares the delivered assertion count and page.on('pageerror') guard against that hand-out, rejecting a net loss (API helpers: one helper per method+path, status-code-only assertions, method+resource names; browser helpers: actions and structural waits only, intent names, one helper per action sequence; every family: one name is defined once per module, with one parameter count across modules). Call it after the reuse edits are written; skyramp_enhance_assertions and skyramp_execute_test refuse until it has passed."),
+        .describe("Verify a previously refactored test instead of returning the reuse prompt. POM path (browser tests): checks the test's POM calls against source; requires the discovery pass — this tool called for the same testFile without `verify` — to have run first. SkyrampUtils path (every other test type): stages the shared utils file for the output commit, checks its invariants, and — when skyramp_modularization recorded a baseline for this spec — compares the delivered assertion count and page.on('pageerror') guard against that hand-out, rejecting a net loss (API helpers: one helper per method+path, status-code-only assertions, method+resource names; browser helpers: actions and structural waits only, intent names, one helper per action sequence; every family: one name is defined once per module, with one parameter count across modules). For a UI test it also checks the repository's own helper modules the test imports: each imported name resolves with an argument count the signature accepts, and every change this run made to such a module adds a helper or a defaulted parameter. Call it after the reuse edits are written; skyramp_enhance_assertions and skyramp_execute_test refuse until it has passed."),
     testType: z
         .nativeEnum(TestType)
         .optional()
         .describe("The type of the test being refactored (shared TestType vocabulary). The tool routes on it server-side: browser types (ui, e2e) may take the POM path; every other type takes the SkyrampUtils path. Omit when unknown."),
+    inHouse: z
+        .object({
+        filesRead: z
+            .array(z.string())
+            .describe("Every file the search for the repository's own browser helper modules READ, repository-relative. All of them, not only the ones that qualified."),
+        declined: z
+            .array(z.object({
+            file: z
+                .string()
+                .describe("Repository-relative path of the module."),
+            helper: z
+                .string()
+                .describe("The helper's name as the module defines it."),
+            reason: z
+                .string()
+                .describe("Why it was not called: the locator is not a plain string (variable, template literal, regex) so its action key is undefined; the module is not written for Playwright; no step matched it; …"),
+        }))
+            .default([])
+            .describe("Helpers the search read and did not call, one entry each, with the reason."),
+    })
+        .optional()
+        .describe("Verify mode, UI tests only (the SkyrampUtils path with page-object reuse off): what the search for the repository's own browser helper modules read and declined. These are DECLARATIONS — the report records them as what the run states it read, labelled as such, not as a measurement. Pass them on the `verify: true` call once the reuse edits are written."),
 });
 const TOOL_NAME = "skyramp_reuse_code";
 /**
@@ -144,14 +166,16 @@ async function runUtilsVerify(params) {
         // whatever the file's invariants say.
         if (staging.failed.length > 0)
             r.ok = false;
-        const recorded = await recordUtilsVerifyOutcome(params.testFile, r, params.language, params.framework, params.testType);
+        const recorded = await recordUtilsVerifyOutcome(params.testFile, r, params.language, params.framework, params.testType, undefined, params.inHouse);
         return {
             content: [
                 {
                     type: "text",
                     text: formatUtilsVerifyText(r, {
                         staged: staging.staged,
-                        unstaged: staging.failed,
+                        // A refused in-house module is the customer's file, not ours to move.
+                        unstaged: staging.failed.filter((f) => !staging.inHouse.includes(f)),
+                        unstagedInHouse: staging.failed.filter((f) => staging.inHouse.includes(f)),
                         recorded,
                     }),
                 },

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

@@ -1,42 +1,12 @@
 import { z } from "zod";
-import { pendingReuseDebt } from "./reuse-state.js";
-import { baselineFrom, readAssertionRecord, recordAssertionBaseline, recordAssertionVerdict, trustedRecord, } from "./assertion-state.js";
-import { formatAssertionVerifyReport, verifyAssertionEnhancement, } from "../../utils/assertion-verify/index.js";
-import { stageAndRecordRetrofits } from "./retrofit-state.js";
-import * as path from "path";
 import { toolError } from "../../utils/utils.js";
-import { ASSERTION_ENHANCEABLE_TEST_TYPES, TestType, } from "../../types/TestTypes.js";
+import { ASSERTION_ENHANCEABLE_TEST_TYPES } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
-import { getContractProviderAssertionsPrompt } from "../../prompts/enhance-assertions/contractProviderAssertionsPrompt.js";
-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";
+import { buildEnhanceAssertionsInstructions, sharedAssertionRules, } from "../../skills/enhanceAssertionsSkill.js";
+import { prepareAssertionCall, snapshotAssertionBaseline, verifyAssertionCall, } from "./assertionOperations.js";
 const TOOL_NAME = "skyramp_enhance_assertions";
-const TESTBOT_UI_CHECKS = `
-### Additional Testbot-Specific 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. Do not re-record an assertion that is expected to fail today; add it here with the blueprint's selector.
-- **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);
+    const typeSpecificInstructions = buildEnhanceAssertionsInstructions(testFile, testType, enhanceType);
     return [
         `Enhance response body assertions in: \`${testFile}\``,
         `Test type: ${testType} | Context: ${enhanceType}`,
@@ -44,7 +14,7 @@ function buildAutoApplyInstructions(testFile, testType, 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, or add comments. You may add an import when a new assertion needs a helper — from \`@skyramp/skyramp\` or from the test's own helper module. Only add assertion lines.`,
+        `Do NOT restructure, reformat, add comments, or change imports. Only add assertion lines.`,
         ``,
         `Type-specific assertion guidance:`,
         typeSpecificInstructions,
@@ -91,63 +61,29 @@ export function registerEnhanceAssertionsTool(server) {
 - Optionally with \`verify: true\` for early feedback — the same deterministic checks run automatically inside skyramp_execute_test, which returns per-violation feedback instead of executing until they pass.`,
         inputSchema: enhanceAssertionsSchema,
     }, async (params) => {
-        const { testFile, testType, enhanceType, autoApply, verify, stateFile } = params;
-        // Everything downstream keys state by this path; a relative spelling
-        // would fork records and fail gates open (review finding on SKYR-4262).
-        if (!path.isAbsolute(testFile)) {
-            return toolError(`testFile must be an absolute path, got: ${testFile}`);
-        }
-        // SKYR-4115: the reuse tool hands out POM mapping instructions and then relies on
-        // the agent to come back with `verify: true` — the call that runs the zero-reuse
-        // gate. This is the first tool called after it on the same spec, so it is where a
-        // skipped verify is caught cheapest. Enforcing the call (not the outcome) keeps
-        // the policy in the reuse phase where it belongs.
-        // SKYR-4220: stage the shared utils file this spec wrote or imports BEFORE the
-        // debt check, unconditionally — so the file reaches the output commit even on a
-        // path where the agent never calls verify. Located by header, not by name.
-        await stageAndRecordRetrofits(testFile);
-        const owed = await pendingReuseDebt(testFile, stateFile, testType, {
-            chain: false,
-        });
-        if (owed)
-            return toolError(owed);
-        // Stage so testbot includes the generated files in its output commit.
-        await stageGeneratedPaths(testFile);
+        // stateFile is threaded through `params` into the shared helpers.
+        const { testFile, testType, enhanceType, autoApply, verify } = params;
+        // Path check, retrofit staging and the reuse-debt gate are shared with
+        // the single-purpose tools the skill drives (SKYR-4310).
+        const refusal = await prepareAssertionCall(params);
+        if (refusal)
+            return toolError(refusal);
         // Verify pass: deterministically check the hand-out instructions were applied
         // (hash delta, no removed coverage, rubric lints, strength increase) and give
         // per-violation feedback. isError on FAILED forces the fix-and-retry loop.
         if (verify) {
             try {
-                const record = await readAssertionRecord(testFile, stateFile);
-                // Discriminators come from the persisted record when it matches this
-                // canonical path — params are agent-supplied, and flipping enhanceType
-                // to "maintenance" would disarm the strength gate and structural lints
-                // for a permanent PASS. Canonical comparison closes the alias bypass
-                // (dir//x.spec.ts). Falls back to params only when stateless.
-                const trusted = trustedRecord(record, testFile);
-                const result = await verifyAssertionEnhancement({
-                    testFile,
-                    testType: trusted?.testType ?? testType,
-                    enhanceType: (trusted?.enhanceType ??
-                        enhanceType),
-                    baseline: baselineFrom(record, testFile),
-                });
-                await recordAssertionVerdict(testFile, result, stateFile);
+                const { ok, report } = await verifyAssertionCall(params);
                 AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, {
                     testFile,
                     testType,
                     enhanceType,
                     verify: true,
-                    verifyPassed: result.ok,
+                    verifyPassed: ok,
                 }).catch(() => { });
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: formatAssertionVerifyReport(result, testFile),
-                        },
-                    ],
-                    isError: !result.ok,
+                    content: [{ type: "text", text: report }],
+                    isError: !ok,
                 };
             }
             catch (err) {
@@ -157,7 +93,7 @@ export function registerEnhanceAssertionsTool(server) {
         }
         // Hand-out: snapshot the file as generated so the verify pass has a baseline
         // to measure against. Best-effort — no run state means stateless verify later.
-        await recordAssertionBaseline(testFile, testType, enhanceType, stateFile);
+        await snapshotAssertionBaseline(params);
         if (autoApply) {
             const compactInstructions = [
                 `Enhance response body assertions in: \`${testFile}\``,
@@ -167,7 +103,7 @@ export function registerEnhanceAssertionsTool(server) {
                 `Use SDK helper: Python \`skyramp.get_response_value(response, "json.path")\`, JS \`getValue(response, "json.path")\`.`,
                 ``,
                 `Shared assertion rules (apply all that fit):`,
-                renderSharedAssertionRules(),
+                sharedAssertionRules(),
                 ``,
                 `Do NOT restructure, reformat, or add comments. You may add an import when a new assertion needs a helper — from \`@skyramp/skyramp\` or from the test's own helper module. Only add assertion lines.`,
             ].join("\n");
@@ -186,7 +122,7 @@ export function registerEnhanceAssertionsTool(server) {
         const enhanceCtx = enhanceType;
         const instructions = autoApply
             ? buildAutoApplyInstructions(testFile, testType, enhanceCtx)
-            : buildAssertionInstructions(testFile, testType, enhanceCtx);
+            : buildEnhanceAssertionsInstructions(testFile, testType, enhanceCtx);
         const result = {
             content: [
                 {

package/build/tools/code-refactor/gate-markers.d.ts

@@ -0,0 +1,51 @@
+import { type UtilsLanguageSpec } from "../../utils/utils-verify/index.js";
+/**
+ * Remove every comment addressed to a Skyramp gate from a delivered file.
+ *
+ * Two gates ask the agent to write a decline into the file it delivers — the utils
+ * verifier's `reuse-verify: allow <kind> <helper> — <reason>` and the POM gate's
+ * `// kept inline: <basename> — <reason>`. Both are how the agent tells a gate it has
+ * read a finding and chosen not to act, and neither says anything to the customer who
+ * ends up owning the file. A marker also records the state of the file at one moment,
+ * and nothing re-reads it when the file changes afterwards, so a delivered file can
+ * carry a claim its own code contradicts.
+ *
+ * A marker OWNS ITS LINE. Both gates instruct exactly that, and both parsers now
+ * accept only that, so removal is the deletion of a line. That one constraint is what
+ * keeps this safe: a line whose first characters are the comment prefix cannot be a
+ * regex literal, cannot carry code, cannot share a comment with the customer's prose,
+ * and cannot hold the `*\/` that terminates a block. Every one of those was a way an
+ * earlier version of this function delivered a file that did not compile.
+ *
+ * Strings are blanked first, so a marker quoted in code — or inside a Python docstring
+ * — is not a marker. Removal follows the WELL-FORMED grammars, not the loose patterns
+ * the gates use to spot a malformed marker: `// kept inline: this loop is kept inline
+ * for performance` is English. Neither grammar is re-spelled here; each pattern comes
+ * from the module that declares it.
+ */
+export interface GateMarkerStrip {
+    content: string;
+    /** The markers removed, each the line it was. */
+    removed: string[];
+    /** Text that announces a marker but does not own its line. Left in place — the
+     *  verify pass reports it as malformed, so it should not reach delivery. */
+    unremovable: string[];
+}
+export declare function stripGateMarkers(content: string, spec: UtilsLanguageSpec): GateMarkerStrip;
+/**
+ * Whether the only change between two versions of a file is the deletion of whole
+ * comment lines.
+ *
+ * Computed WITHOUT reference to how the strip works, and that is the point. Every
+ * defect this function has had was a case nobody had thought of — a regex literal, a
+ * line carrying a block terminator, a comment shared with the customer's prose, a
+ * directive before a trailing marker. Each was found by a reader. This check does not
+ * need the case to be foreseen: it states the only edit the strip is permitted to
+ * make, and the caller restores the original bytes when something else happened.
+ *
+ * Two conditions, together: every line of `after` appears in `before` in the same
+ * order, and every line of `before` that `after` drops opens with the comment prefix.
+ * A line that was EDITED therefore fails the first, and a line of code that was
+ * deleted fails the second.
+ */
+export declare function onlyCommentLinesRemoved(before: string, after: string, prefix: "//" | "#"): boolean;

package/build/tools/code-refactor/gate-markers.js

@@ -0,0 +1,95 @@
+import { blankStrings } from "../../utils/utils-verify/parse.js";
+import { ALLOW_LOOSE_RE, ALLOW_START_RE, MARKER_SHAPE_RE, lineCommentOpeners, markerOnOwnLine, } from "../../utils/utils-verify/index.js";
+import { KEPT_INLINE_LOOSE_RE } from "./reuse-outcome.js";
+export function stripGateMarkers(content, spec) {
+    const removed = [];
+    const unremovable = [];
+    const rawLines = content.split("\n");
+    const codeLines = blankStrings(content, spec).split("\n");
+    const kept = [];
+    // Where a comment actually OPENS. A `//` on its own line inside `/* … *\/` opens
+    // nothing: the block does, and deleting that line can take the block's terminator
+    // with it. One statement of this, shared with the marker parser — when each had its
+    // own, the parser read a decline the strip then refused to remove.
+    const opensHere = lineCommentOpeners(content, spec.commentPrefix);
+    for (let n = 0; n < rawLines.length; n++) {
+        const raw = rawLines[n];
+        const code = codeLines[n] ?? "";
+        if (!ALLOW_LOOSE_RE.test(code) && !KEPT_INLINE_LOOSE_RE.test(code)) {
+            kept.push(raw);
+            continue;
+        }
+        const marker = opensHere && !opensHere.has(n)
+            ? undefined
+            : markerOnOwnLine(raw, code, spec.commentPrefix);
+        const body = marker === undefined
+            ? undefined
+            : marker.replace(spec.commentPrefix, "").trimStart();
+        // The SHAPE guard is for the ambiguous grammar only. `// kept inline: this loop is
+        // kept inline for performance` is English a customer may write, so removing it
+        // needs the separator and reason that make it a marker. `reuse-verify: allow` is
+        // nobody's prose: an own-line comment opening with it is gate-addressed whatever
+        // follows, and requiring the full shape left a MALFORMED one in the file — which
+        // ships once the verifier's bounded refusals run out.
+        const removable = body !== undefined &&
+            (ALLOW_START_RE.test(body) || MARKER_SHAPE_RE.test(body));
+        if (!removable) {
+            unremovable.push(raw.trim());
+            kept.push(raw);
+            continue;
+        }
+        // Removal follows the marker's SHAPE, not the grammar the gates can read. An
+        // own-line comment is safe to delete, and the verify pass lets some of these
+        // through: a marker naming an advisory kind is inert by design, so verification
+        // passes and the comment reached the customer. Only what the caller CARRIES has
+        // to parse — it re-reads `removed` with the well-formed grammars for that.
+        removed.push(marker);
+    }
+    return { content: kept.join("\n"), removed, unremovable };
+}
+/**
+ * Whether the only change between two versions of a file is the deletion of whole
+ * comment lines.
+ *
+ * Computed WITHOUT reference to how the strip works, and that is the point. Every
+ * defect this function has had was a case nobody had thought of — a regex literal, a
+ * line carrying a block terminator, a comment shared with the customer's prose, a
+ * directive before a trailing marker. Each was found by a reader. This check does not
+ * need the case to be foreseen: it states the only edit the strip is permitted to
+ * make, and the caller restores the original bytes when something else happened.
+ *
+ * Two conditions, together: every line of `after` appears in `before` in the same
+ * order, and every line of `before` that `after` drops opens with the comment prefix.
+ * A line that was EDITED therefore fails the first, and a line of code that was
+ * deleted fails the second.
+ */
+export function onlyCommentLinesRemoved(before, after, prefix) {
+    const from = before.split("\n");
+    const to = after.split("\n");
+    // A line that CLOSES a block comment cannot be deleted without changing what that
+    // comment covers, whatever else the line looks like. Checked textually, so this
+    // holds even when the lexer and the strip agree with each other and are both wrong
+    // — which is what a `//` inside a block made them do.
+    //
+    // Only `*\/` is tested. A `/*` inside the reason of a genuine line comment is inert
+    // text, and deleting a line cannot open a block that was not already open; treating
+    // it as active made the strip abandon the write, so a marker whose reason discussed
+    // a selector shipped to the customer — the one outcome this pass exists to prevent.
+    const isComment = (line) => line.trimStart().startsWith(prefix) &&
+        !(prefix === "//" && line.includes("*/"));
+    let i = 0;
+    for (const line of to) {
+        while (i < from.length && from[i] !== line) {
+            if (!isComment(from[i]))
+                return false;
+            i++;
+        }
+        if (i >= from.length)
+            return false;
+        i++;
+    }
+    for (; i < from.length; i++)
+        if (!isComment(from[i]))
+            return false;
+    return true;
+}

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

@@ -27,7 +27,9 @@ export interface RetrofitView {
     /** Absolute path. */
     file: string;
     utilsFile: string;
-    /** The spec whose reuse pass caused the edit (absolute). */
+    /** The spec whose reuse pass caused the edit (absolute) — the row the retrofit is
+     *  reported on. Equals `file` when the causing spec cannot be established: see
+     *  `uncrossAttributions`. */
     testFile: string;
     /** Status of an execution that ran the CURRENT bytes (executedAt ≥ the file's
      *  mtime), if any. */