@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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. */

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

@@ -49,7 +49,7 @@ export async function recordReuseRetrofits(retrofits, utilsFiles, testFile, expl
             if (!entries[key])
                 entries[key] = { utilsFile, testFile: await realpath(testFile) };
         }
-        await manager.writeData({ ...data, reuseRetrofits: entries });
+        await manager.appendData({ ...data, reuseRetrofits: entries });
     }
     catch (err) {
         logger.warning("Could not record the reuse retrofits — the report will not be checked for them", { retrofits, error: String(err) });
@@ -83,7 +83,49 @@ export async function standingRetrofits(state, changedFilesAbs) {
         }
         out.push({ file, utilsFile: r.utilsFile, testFile: r.testFile, execution });
     }
-    return out;
+    return uncrossAttributions(out);
+}
+/**
+ * Drop the CAUSING spec from any pair of retrofits that name each other, keeping the
+ * retrofit itself and re-attributing it to its own file.
+ *
+ * A retrofit is found by `modifiedSiblingsImporting`, whose evidence is "modified
+ * since HEAD and imports the module". That establishes the edit; it establishes
+ * nothing about WHO made it. When two specs on one module are each edited by their
+ * own chain, each one's staging call sees the other as a modified sibling and claims
+ * it, and `recordReuseRetrofits` is first-wins, so both claims persist. The report
+ * then shows each row naming the other row's file — a statement of cause that cannot
+ * be true in both directions, observed in three fixtures of the 2026-09-18 cohort.
+ *
+ * A cycle proves at least one claim is false and run state holds nothing that says
+ * which, so neither is reported. What survives is what the files do prove: this
+ * pre-existing test was rewired onto the shared module by this run, and here is the
+ * execution that ran it. That keeps the disclosure — and the report gate over it — on
+ * the row a reader looks at for that file, instead of on a sibling that may not have
+ * touched it.
+ *
+ * Only reciprocal claims ON THE SAME MODULE are touched. Two conditions, both read
+ * off the evidence:
+ *
+ *  - A one-way attribution is the ordinary STEP 5c case, where a spec's reuse pass
+ *    reached a sibling that is not being edited in its own right, and nothing
+ *    contradicts it.
+ *  - A reciprocal pair naming DIFFERENT modules is a shape no cohort has produced —
+ *    the observed defect is two specs on one module — so nothing says the same cause
+ *    is behind it, and the row it would move to carries another module's record.
+ */
+function uncrossAttributions(views) {
+    const claimed = new Map();
+    for (const v of views)
+        claimed.set(canonPath(v.file), v);
+    return views.map((v) => {
+        const reciprocal = claimed.get(canonPath(v.testFile));
+        return reciprocal &&
+            canonPath(reciprocal.testFile) === canonPath(v.file) &&
+            reciprocal.utilsFile === v.utilsFile
+            ? { ...v, testFile: v.file }
+            : v;
+    });
 }
 /**
  * The report gate over the standing retrofits: every one needs an execution of its

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

@@ -1,5 +1,5 @@
 import type { VerifyResult } from "../../utils/pom-verify/index.js";
-import { ReuseVerificationOutcome, type ReuseSkippedEntry } from "../../types/ReuseOutcome.js";
+import { ReuseVerificationOutcome, type InHouseDeclinedEntry, type ReuseSkippedEntry } from "../../types/ReuseOutcome.js";
 import { HelperVerificationOutcome } from "../../types/ReuseOutcome.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, type ReuseOutcome, type ReuseSkippedEntry, } from "../../types/ReuseOutcome.js";
 /** A member the verifier flagged at some point in this run. NOT the same as "a
@@ -77,7 +77,29 @@ export interface UtilsReuseRecord {
     verification?: HelperVerificationOutcome;
     /** The last verify pass threw; the debt fails open until a pass succeeds. */
     verifyError?: boolean;
+    /** What the agent DECLARED on its last verify call about the search for the
+     *  repository's own browser helper modules: the files it read, the helpers it
+     *  declined. Testimony, kept for the report and labelled there as such. */
+    inHouseDeclared?: InHouseDeclaration;
 }
+export interface InHouseDeclaration {
+    filesRead: string[];
+    declined: InHouseDeclinedEntry[];
+}
+/** 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. */
+export declare const KEPT_INLINE_RE: RegExp;
+/** Lines that look like a kept-inline marker. Deliberately looser than
+ *  KEPT_INLINE_RE so the difference between the two is detectable. Exported so the
+ *  delivery-time strip recognises the grammar from its one declaration here rather
+ *  than re-spelling it. */
+export declare const KEPT_INLINE_LOOSE_RE: RegExp;
 /**
  * Every well-formed `// kept inline: <basename> — <reason>` marker in a spec.
  *

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

@@ -1,5 +1,6 @@
 import * as path from "path";
 import { stripStrings } from "../../utils/pom-scope/strip.js";
+import { lineCommentOpeners, markerOnOwnLine, } from "../../utils/utils-verify/allow.js";
 import { ReuseDeclinedBy, ReuseVerificationOutcome, } from "../../types/ReuseOutcome.js";
 /**
  * Server-side derivation of a UI test's POM code-reuse outcome.
@@ -31,15 +32,12 @@ export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, }
  *  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*$/;
+export 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");
-}
+ *  KEPT_INLINE_RE so the difference between the two is detectable. Exported so the
+ *  delivery-time strip recognises the grammar from its one declaration here rather
+ *  than re-spelling it. */
+export const KEPT_INLINE_LOOSE_RE = /\/\/\s*kept inline:/;
 /**
  * Every well-formed `// kept inline: <basename> — <reason>` marker in a spec.
  *
@@ -53,8 +51,8 @@ function commentLines(specContent) {
 export function parseKeptInline(specContent) {
     const out = [];
     const seen = new Set();
-    for (const line of commentLines(specContent)) {
-        const m = KEPT_INLINE_RE.exec(line);
+    for (const { marker } of keptInlineLines(specContent)) {
+        const m = marker && KEPT_INLINE_RE.exec(marker);
         if (!m)
             continue;
         const pageObject = path.basename(m[1].trim());
@@ -67,6 +65,31 @@ export function parseKeptInline(specContent) {
     }
     return out;
 }
+/** Every line that announces a kept-inline decline, with the marker text when the
+ *  comment owns the line. A marker after code or inside a block reports as
+ *  unparsable — one placement, so a decline can be removed by deleting a line. */
+function keptInlineLines(specContent) {
+    const rawLines = specContent.split("\n");
+    const codeLines = stripStrings(specContent).split("\n");
+    // Where a comment actually OPENS. Through the same helper the utils grammar and the
+    // delivery strip use: a `//` inside `/* … *\/` opens nothing, and reading one as a
+    // decline authorised the candidate it named while the strip — correctly — refused
+    // to delete a line carrying the block's terminator, so the note shipped as well.
+    const opens = lineCommentOpeners(specContent, "//");
+    const out = [];
+    for (let n = 0; n < rawLines.length; n++) {
+        const code = codeLines[n] ?? "";
+        if (!KEPT_INLINE_LOOSE_RE.test(code))
+            continue;
+        out.push({
+            raw: rawLines[n],
+            marker: opens && !opens.has(n)
+                ? undefined
+                : markerOnOwnLine(rawLines[n], code, "//"),
+        });
+    }
+    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
@@ -78,9 +101,9 @@ export function parseKeptInline(specContent) {
  * 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());
+    return keptInlineLines(specContent)
+        .filter(({ marker }) => !marker || !KEPT_INLINE_RE.test(marker))
+        .map(({ raw }) => raw.trim());
 }
 /** Members the verifier flagged in one pass, keyed to the file a decline comment
  *  would name. */