@skyramp/mcp 0.4.1 → 0.4.2-rc.1

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

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

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