@quikit/quikpilot-runner 7.0.6 → 8.1.0

package/dist/index.js

@@ -23,6 +23,54 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// src/env.ts
+function required(name, value) {
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+function readRunnerEnv(env2 = process.env) {
+  const githubRunId = required("GITHUB_RUN_ID", env2.GITHUB_RUN_ID);
+  const githubServerUrl = env2.GITHUB_SERVER_URL ?? "https://github.com";
+  const githubRepository = required("GITHUB_REPOSITORY", env2.GITHUB_REPOSITORY);
+  if (env2.MODE === "readiness_check") {
+    return {
+      mode: "readiness_check",
+      readinessToken: required("READINESS_TOKEN", env2.READINESS_TOKEN),
+      readinessCallbackUrl: required("READINESS_CALLBACK_URL", env2.READINESS_CALLBACK_URL),
+      setupCmd: env2.SETUP_CMD ?? "",
+      testCmd: required("TEST_CMD", env2.TEST_CMD),
+      githubRunId,
+      githubServerUrl,
+      githubRepository
+    };
+  }
+  return {
+    mode: "run",
+    runId: required("RUN_ID", env2.RUN_ID),
+    callbackUrl: required("CALLBACK_URL", env2.CALLBACK_URL),
+    packetUrl: required("PACKET_URL", env2.PACKET_URL),
+    tokenUrl: required("TOKEN_URL", env2.TOKEN_URL),
+    installationTokenUrl: required("INSTALLATION_TOKEN_URL", env2.INSTALLATION_TOKEN_URL),
+    githubRunId,
+    githubServerUrl,
+    githubRepository
+  };
+}
+
+// src/quiktrackError.ts
+async function describeQuikTrackFailure(res) {
+  try {
+    const body = await res.json();
+    if (body && typeof body === "object" && typeof body.reason_code === "string") {
+      return `${res.status} ${res.statusText} (${body.reason_code})`;
+    }
+  } catch {
+  }
+  return `${res.status} ${res.statusText}`;
+}
+
 // src/callback.ts
 async function reportBack(params) {
   const { callbackUrl, runToken, status, branch, warnings } = params;
@@ -35,7 +83,7 @@ async function reportBack(params) {
     body: JSON.stringify(body)
   });
   if (!res.ok) {
-    throw new Error(`Report back to QuikTrack failed: ${res.status} ${res.statusText}`);
+    throw new Error(`Report back to QuikTrack failed: ${await describeQuikTrackFailure(res)}`);
   }
 }
 
@@ -155,6 +203,14 @@ var import_node_fs = require("node:fs");
 var import_node_path = require("node:path");
 
 // src/envelope.ts
+var HARD_FAILURE_CODES = /* @__PURE__ */ new Set(["SEMANTIC_MISMATCH", "CONTRACT_REJECTED"]);
+function checkHardFailure(envelope, useCase) {
+  const code = envelope?.errorCode;
+  if (typeof code === "string" && HARD_FAILURE_CODES.has(code)) {
+    const detail = envelope.error ?? envelope.normalizedText ?? "no detail";
+    throw new Error(`${useCase} failed (${code}, not retried): ${detail}`);
+  }
+}
 function unwrapExecute(envelope, useCase) {
   if (envelope?.success === false) {
     throw new Error(
@@ -167,11 +223,97 @@ function unwrapExecute(envelope, useCase) {
   return envelope.structuredJson;
 }
 
+// src/retryFetch.ts
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([502, 503, 504]);
+var RETRYABLE_NETWORK_ERROR_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "ETIMEDOUT"]);
+function isRetryableNetworkError(err) {
+  const code = err?.cause?.code ?? err?.code;
+  return typeof code === "string" && RETRYABLE_NETWORK_ERROR_CODES.has(code);
+}
+async function fetchWithRetry(url, init, { retries = 2, backoffMs = 250 } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const res = await fetch(url, init);
+      if (RETRYABLE_STATUS_CODES.has(res.status) && attempt < retries) {
+        await new Promise((r) => setTimeout(r, backoffMs));
+        continue;
+      }
+      return res;
+    } catch (err) {
+      if (isRetryableNetworkError(err) && attempt < retries) {
+        await new Promise((r) => setTimeout(r, backoffMs));
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
 // src/codegen.ts
 var FILE_TOO_LARGE_CODE = "CODEGEN_FILE_TOO_LARGE";
 var CONTEXT_TOO_LARGE_CODE = "CODEGEN_CONTEXT_TOO_LARGE";
-var NOT_RETRIED_CODES = /* @__PURE__ */ new Set([FILE_TOO_LARGE_CODE, CONTEXT_TOO_LARGE_CODE]);
-async function runCodegen(gateway, targets, workspaceListing) {
+var OUTPUT_TOO_LARGE_CODE = "CODEGEN_OUTPUT_TOO_LARGE";
+var NOT_RETRIED_CODES = /* @__PURE__ */ new Set([FILE_TOO_LARGE_CODE, CONTEXT_TOO_LARGE_CODE, OUTPUT_TOO_LARGE_CODE]);
+var SUSPECT_PLACEHOLDER_RE = /rest(?: of the)? (?:file|code) unchanged|remainder unchanged|\/\/\s*\.\.\.\s*(?:rest|remaining)/i;
+var SUSPECT_LENGTH_DROP_RATIO = 0.6;
+var SUSPECT_REMOVED_LINE_RATIO = 0.3;
+var MIN_LINES_FOR_REMOVED_LINE_CHECK = 10;
+var JS_TS_EXTENSION_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs)$/;
+var EXPORTED_SYMBOL_RE = /^export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum)\s+([A-Za-z_$][\w$]*)/gm;
+function countRemovedLines(currentContent, newContent) {
+  const remaining = /* @__PURE__ */ new Map();
+  for (const line of newContent.split("\n")) {
+    remaining.set(line, (remaining.get(line) ?? 0) + 1);
+  }
+  let removed = 0;
+  for (const line of currentContent.split("\n")) {
+    const count = remaining.get(line) ?? 0;
+    if (count > 0) {
+      remaining.set(line, count - 1);
+    } else {
+      removed++;
+    }
+  }
+  return removed;
+}
+function extractExportedSymbols(content) {
+  const symbols = /* @__PURE__ */ new Set();
+  for (const match of content.matchAll(EXPORTED_SYMBOL_RE)) {
+    symbols.add(match[1]);
+  }
+  return symbols;
+}
+function removedUnexplainedSymbols(targetPath, planText, currentContent, newContent) {
+  if (!JS_TS_EXTENSION_RE.test(targetPath)) return [];
+  const before = extractExportedSymbols(currentContent);
+  const after = extractExportedSymbols(newContent);
+  const lowerPlan = planText.toLowerCase();
+  return [...before].filter((symbol) => !after.has(symbol) && !lowerPlan.includes(symbol.toLowerCase()));
+}
+function looksLikeTruncatedRewrite(target, currentContent, newContent) {
+  if (SUSPECT_PLACEHOLDER_RE.test(newContent)) {
+    return "contains placeholder text suggesting an abbreviated rewrite";
+  }
+  if (currentContent.length > 0 && newContent.length < currentContent.length * SUSPECT_LENGTH_DROP_RATIO) {
+    return `sharp length drop (${currentContent.length} -> ${newContent.length} chars)`;
+  }
+  const currentLineCount = currentContent.length > 0 ? currentContent.split("\n").length : 0;
+  if (currentLineCount >= MIN_LINES_FOR_REMOVED_LINE_CHECK) {
+    const removedLines = countRemovedLines(currentContent, newContent);
+    if (removedLines > currentLineCount * SUSPECT_REMOVED_LINE_RATIO) {
+      const pct = (removedLines / currentLineCount * 100).toFixed(0);
+      return `removed ${removedLines} of ${currentLineCount} lines (${pct}%) without a matching drop in character count`;
+    }
+  }
+  const planText = target.planStepsImplemented.join(" ");
+  const unexplainedSymbols = removedUnexplainedSymbols(target.path, planText, currentContent, newContent);
+  if (unexplainedSymbols.length > 0) {
+    return `removed exported symbol(s) the plan steps don't mention: ${unexplainedSymbols.join(", ")}`;
+  }
+  return null;
+}
+var CONTRACT_VERSION = "test-targets-1";
+async function runCodegen(gateway, targets, workspaceListing, requiredTests, deniedPaths) {
   const results = [];
   const listing = new Set(workspaceListing);
   for (const target of targets) {
@@ -191,12 +333,21 @@ async function runCodegen(gateway, targets, workspaceListing) {
       currentContent,
       planSteps: target.planStepsImplemented,
       kind: target.kind,
-      contextContents
+      contextContents,
+      // QUIKTR-1083 (§15.6) — required on every call on the versioned path.
+      contractVersion: CONTRACT_VERSION
     };
     if (isNewFile) {
       contextData.workspaceListing = workspaceListing;
     }
-    const res = await fetch(`${gateway.baseUrl}/ai/execute`, {
+    if (deniedPaths.length > 0) {
+      contextData.deniedPaths = deniedPaths;
+    }
+    if (target.automationIds && target.automationIds.length > 0) {
+      const wanted = new Set(target.automationIds);
+      contextData.requiredTests = requiredTests.filter((tc) => wanted.has(tc.automationId));
+    }
+    const res = await fetchWithRetry(`${gateway.baseUrl}/ai/execute`, {
       method: "POST",
       headers: { "content-type": "application/json", "x-run-token": gateway.token },
       body: JSON.stringify({
@@ -211,6 +362,7 @@ async function runCodegen(gateway, targets, workspaceListing) {
       throw new Error(`Codegen call failed for ${target.path}: ${res.status} ${res.statusText}`);
     }
     const envelope = await res.json();
+    checkHardFailure(envelope, "pilot.codegen");
     if (typeof envelope?.errorCode === "string" && NOT_RETRIED_CODES.has(envelope.errorCode)) {
       const detail = envelope.error ? `: ${envelope.error}` : "";
       throw new Error(`Codegen refused ${target.path}: ${envelope.errorCode} (not retried)${detail}`);
@@ -221,6 +373,24 @@ async function runCodegen(gateway, targets, workspaceListing) {
         `Codegen refused ${target.path}${body.refusalReason ? `: ${body.refusalReason}` : ""}`
       );
     }
+    if (!isNewFile) {
+      const suspectReason = looksLikeTruncatedRewrite(target, currentContent, body.newContent);
+      if (suspectReason) {
+        throw new Error(
+          `Codegen output for ${target.path} looks like a truncated/abbreviated rewrite (${suspectReason}) \u2014 refusing to apply it. Interim guard per \xA716.7; the AI Runtime's own output-cap check is not live yet.`
+        );
+      }
+    }
+    console.log(
+      JSON.stringify({
+        event: "codegen.metrics",
+        targetPath: target.path,
+        kind: target.kind,
+        inputLength: currentContent.length,
+        outputLength: body.newContent.length,
+        removedLines: isNewFile ? null : countRemovedLines(currentContent, body.newContent)
+      })
+    );
     results.push({ targetPath: target.path, newContent: body.newContent });
   }
   return results;
@@ -414,26 +584,6 @@ function describeDependencyViolations(check) {
   return check.violations.map((v) => `${v.file} imports ${v.packages.join(", ")}, not a dependency of this repository`).join("; ");
 }
 
-// src/env.ts
-function required(name, value) {
-  if (!value) {
-    throw new Error(`Missing required environment variable: ${name}`);
-  }
-  return value;
-}
-function readRunnerEnv(env = process.env) {
-  return {
-    runId: required("RUN_ID", env.RUN_ID),
-    callbackUrl: required("CALLBACK_URL", env.CALLBACK_URL),
-    packetUrl: required("PACKET_URL", env.PACKET_URL),
-    tokenUrl: required("TOKEN_URL", env.TOKEN_URL),
-    installationTokenUrl: required("INSTALLATION_TOKEN_URL", env.INSTALLATION_TOKEN_URL),
-    githubRunId: required("GITHUB_RUN_ID", env.GITHUB_RUN_ID),
-    githubServerUrl: env.GITHUB_SERVER_URL ?? "https://github.com",
-    githubRepository: required("GITHUB_REPOSITORY", env.GITHUB_REPOSITORY)
-  };
-}
-
 // src/guardrail.ts
 function checkGuardrail(deniedPaths) {
   addAll();
@@ -451,7 +601,7 @@ async function exchangeForInstallationToken(installationTokenUrl, runToken) {
     headers: { Authorization: `Bearer ${runToken}` }
   });
   if (!res.ok) {
-    throw new Error(`Exchange installation token failed: ${res.status} ${res.statusText}`);
+    throw new Error(`Exchange installation token failed: ${await describeQuikTrackFailure(res)}`);
   }
   const body = await res.json();
   if (body.success !== true) {
@@ -462,14 +612,14 @@ async function exchangeForInstallationToken(installationTokenUrl, runToken) {
 
 // src/oidc.ts
 var QUIKPILOT_OIDC_AUDIENCE = "quiktrack-quikpilot";
-async function fetchGithubOidcToken(env = process.env) {
+async function fetchGithubOidcToken(env2 = process.env) {
   const requestUrl = required(
     "ACTIONS_ID_TOKEN_REQUEST_URL",
-    env.ACTIONS_ID_TOKEN_REQUEST_URL
+    env2.ACTIONS_ID_TOKEN_REQUEST_URL
   );
   const requestToken = required(
     "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
-    env.ACTIONS_ID_TOKEN_REQUEST_TOKEN
+    env2.ACTIONS_ID_TOKEN_REQUEST_TOKEN
   );
   const separator = requestUrl.includes("?") ? "&" : "?";
   const url = `${requestUrl}${separator}audience=${encodeURIComponent(QUIKPILOT_OIDC_AUDIENCE)}`;
@@ -487,6 +637,10 @@ async function fetchGithubOidcToken(env = process.env) {
 }
 
 // src/overlapCheck.ts
+var TEST_PATH_RE = /(\.(test|spec)\.[jt]sx?$)|(^|\/)(__tests__|tests?)\//i;
+function isTestTarget(path) {
+  return TEST_PATH_RE.test(path);
+}
 var STOPWORDS = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -548,6 +702,9 @@ function jaccard(a, b) {
   const union = a.size + b.size - intersection;
   return intersection / union;
 }
+function normalizedStep(step) {
+  return step.trim().toLowerCase().replace(/\s+/g, " ");
+}
 var OVERLAP_THRESHOLD = 0.5;
 function findOverlappingSteps(targets) {
   const items = targets.flatMap(
@@ -561,12 +718,14 @@ function findOverlappingSteps(targets) {
   for (let i = 0; i < items.length; i++) {
     for (let j = i + 1; j < items.length; j++) {
       if (items[i].target === items[j].target) continue;
+      if (isTestTarget(items[i].target) || isTestTarget(items[j].target)) continue;
       if (jaccard(items[i].words, items[j].words) >= OVERLAP_THRESHOLD) {
         warnings.push({
           targetA: items[i].target,
           stepA: items[i].step,
           targetB: items[j].target,
-          stepB: items[j].step
+          stepB: items[j].step,
+          severity: normalizedStep(items[i].step) === normalizedStep(items[j].step) ? "identical" : "similar"
         });
       }
     }
@@ -586,7 +745,7 @@ async function fetchPacket(packetUrl, runToken, githubRunId) {
     headers: { Authorization: `Bearer ${runToken}` }
   });
   if (!res.ok) {
-    throw new Error(`Fetch work packet failed: ${res.status} ${res.statusText}`);
+    throw new Error(`Fetch work packet failed: ${await describeQuikTrackFailure(res)}`);
   }
   const body = await res.json();
   if (body.success !== true) {
@@ -662,9 +821,9 @@ async function reportToQuikTest(params) {
   try {
     console.log(`reporting ${report}`);
     const ciUrl = buildCiUrl(githubServerUrl, githubRepository, githubRunId);
-    const { readFileSync: readFileSync4 } = await import("node:fs");
-    const body = readFileSync4(report);
-    const url = `${resultsUrl}?ciUrl=${encodeURIComponent(ciUrl)}`;
+    const { readFileSync: readFileSync5 } = await import("node:fs");
+    const body = readFileSync5(report);
+    const url = `${resultsUrl}?ciUrl=${encodeURIComponent(ciUrl)}&automationIdFormat=bracket`;
     const res = await fetch(url, {
       method: "POST",
       headers: { Authorization: `Bearer ${runToken}`, "Content-Type": "text/xml" },
@@ -685,8 +844,24 @@ var TESTCASE_RE = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
 var NAME_ATTR_RE = /\bname="([^"]*)"/;
 var CLASSNAME_ATTR_RE = /\bclassname="([^"]*)"/;
 var FAILURE_CHILD_RE = /<failure\b|<error\b/;
+var FAILURE_TAG_RE = /<(?:failure|error)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/(?:failure|error)>)/;
+var FAILURE_MESSAGE_ATTR_RE = /\bmessage="([^"]*)"/;
+var MAX_FAILURE_TEXT = 500;
+function unescapeXmlEntities(s) {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+function extractFailureText(testcaseBody) {
+  const tag = FAILURE_TAG_RE.exec(testcaseBody);
+  if (!tag) return null;
+  const [, attrs = "", inner = ""] = tag;
+  const raw = (FAILURE_MESSAGE_ATTR_RE.exec(attrs)?.[1] ?? inner).trim();
+  if (!raw) return null;
+  const text = unescapeXmlEntities(raw);
+  return text.length > MAX_FAILURE_TEXT ? `${text.slice(0, MAX_FAILURE_TEXT)}\u2026` : text;
+}
 function parseJUnitOutcomes(xml) {
-  const results = /* @__PURE__ */ new Map();
+  const outcomes = /* @__PURE__ */ new Map();
+  const failureText = /* @__PURE__ */ new Map();
   let match;
   TESTCASE_RE.lastIndex = 0;
   while (match = TESTCASE_RE.exec(xml)) {
@@ -695,9 +870,14 @@ function parseJUnitOutcomes(xml) {
     if (!name) continue;
     const classname = CLASSNAME_ATTR_RE.exec(attrs)?.[1];
     const id = classname ? `${classname}::${name}` : name;
-    results.set(id, !FAILURE_CHILD_RE.test(body));
+    const failed = FAILURE_CHILD_RE.test(body);
+    outcomes.set(id, !failed);
+    if (failed) {
+      const text = extractFailureText(body);
+      if (text) failureText.set(id, text);
+    }
   }
-  return results;
+  return { outcomes, failureText };
 }
 function readJUnitOutcomes(cwd) {
   const report = findJUnitReport(cwd);
@@ -710,35 +890,55 @@ function readJUnitOutcomes(cwd) {
 }
 function captureTestSnapshot(command, cwd = process.cwd()) {
   const outcome = runTestCommand(command);
-  return { outcome, results: readJUnitOutcomes(cwd) };
+  const parsed = readJUnitOutcomes(cwd);
+  return { outcome, results: parsed?.outcomes ?? null, failureText: parsed?.failureText };
 }
 async function captureBaselineSnapshot(command, cwd = process.cwd()) {
   const outcome = await runTestCommandAsync(command);
-  return { outcome, results: readJUnitOutcomes(cwd) };
+  const parsed = readJUnitOutcomes(cwd);
+  return { outcome, results: parsed?.outcomes ?? null, failureText: parsed?.failureText };
 }
 function checkForRegressions(baseline, after) {
   if (!baseline.results || !after.results) {
-    return { blocked: false, regressions: [], newFailures: [], preExisting: [] };
+    return { blocked: false, regressions: [], newFailures: [], preExisting: [], failureText: /* @__PURE__ */ new Map() };
   }
   const regressions = [];
   const newFailures = [];
   const preExisting = [];
+  const failureText = /* @__PURE__ */ new Map();
+  const afterFailureText = after.failureText;
   for (const [testId, passed] of after.results) {
     if (passed) continue;
     const before = baseline.results.get(testId);
-    if (before === true) regressions.push(testId);
-    else if (before === false) preExisting.push(testId);
-    else newFailures.push(testId);
+    if (before === true) {
+      regressions.push(testId);
+      const text = afterFailureText?.get(testId);
+      if (text) failureText.set(testId, text);
+    } else if (before === false) {
+      preExisting.push(testId);
+    } else {
+      newFailures.push(testId);
+      const text = afterFailureText?.get(testId);
+      if (text) failureText.set(testId, text);
+    }
   }
-  return { blocked: regressions.length > 0 || newFailures.length > 0, regressions, newFailures, preExisting };
+  return { blocked: regressions.length > 0 || newFailures.length > 0, regressions, newFailures, preExisting, failureText };
 }
 function describeRegressions(check) {
+  const withText = (id) => {
+    const text = check.failureText.get(id);
+    return text ? `${id} (${text})` : id;
+  };
   const parts = [];
   if (check.regressions.length > 0) {
-    parts.push(`${check.regressions.length} regression(s) (passed before, now fail): ${check.regressions.join(", ")}`);
+    parts.push(
+      `${check.regressions.length} regression(s) (passed before, now fail): ${check.regressions.map(withText).join(", ")}`
+    );
   }
   if (check.newFailures.length > 0) {
-    parts.push(`${check.newFailures.length} new failure(s) (did not exist before): ${check.newFailures.join(", ")}`);
+    parts.push(
+      `${check.newFailures.length} new failure(s) (did not exist before): ${check.newFailures.map(withText).join(", ")}`
+    );
   }
   if (check.preExisting.length > 0) {
     parts.push(`${check.preExisting.length} pre-existing failure(s), unrelated to this change, not blocking`);
@@ -746,12 +946,99 @@ function describeRegressions(check) {
   return parts.join("; ");
 }
 
+// src/scopeCheck.ts
+var import_node_fs6 = require("node:fs");
+var ROUTE_METHOD_RE = /\b(GET|POST|PUT|PATCH|DELETE)\b/i;
+var ROUTE_PATH_RE = /\/[A-Za-z0-9_\-{}[\]]+(?:\/[A-Za-z0-9_\-:{}[\]]+)+/;
+var ROUTE_EXPORT_RE = /\bexport\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)\s*\(/;
+var NO_PATH = "(this file's route)";
+function detectMentions(text) {
+  const found = [];
+  for (const line of text.split("\n")) {
+    const methodMatch = ROUTE_METHOD_RE.exec(line);
+    const pathMatch = ROUTE_PATH_RE.exec(line);
+    if (methodMatch && pathMatch) {
+      found.push({ method: methodMatch[1].toUpperCase(), path: pathMatch[0] });
+    }
+    const exportMatch = ROUTE_EXPORT_RE.exec(line);
+    if (exportMatch) {
+      found.push({ method: exportMatch[1].toUpperCase(), path: NO_PATH });
+    }
+  }
+  return found;
+}
+function normalizePath(path) {
+  return path.replace(/:[A-Za-z0-9_]+|\{[^}]+\}|\[[^\]]+\]/g, "*");
+}
+function surfaceCovers(surface, mention) {
+  if (!new RegExp(`\\b${mention.method}\\b`, "i").test(surface)) return false;
+  if (mention.path === NO_PATH) return true;
+  const declaredPath = normalizePath(surface);
+  const mentionPath = normalizePath(mention.path);
+  return declaredPath.includes(mentionPath) || mentionPath.includes(declaredPath);
+}
+function addedLines(before, after) {
+  const beforeLines = new Set(before.split("\n"));
+  return after.split("\n").filter((line) => !beforeLines.has(line)).join("\n");
+}
+function checkApiScope(results, targets, apiChanges) {
+  const targetsByPath = new Map(targets.map((t) => [t.path, t]));
+  const violations = [];
+  for (const { targetPath, newContent } of results) {
+    const target = targetsByPath.get(targetPath);
+    const isNewFile = target?.kind === "NEW_FILE";
+    let scanned;
+    if (isNewFile) {
+      scanned = newContent;
+    } else {
+      let currentContent;
+      try {
+        currentContent = (0, import_node_fs6.readFileSync)(targetPath, "utf8");
+      } catch {
+        currentContent = "";
+      }
+      scanned = addedLines(currentContent, newContent);
+    }
+    for (const mention of detectMentions(scanned)) {
+      if (!apiChanges.some((c) => surfaceCovers(c.surface, mention))) {
+        violations.push({ file: targetPath, method: mention.method, path: mention.path });
+      }
+    }
+  }
+  return { blocked: violations.length > 0, violations };
+}
+function describeScopeViolations(check) {
+  return check.violations.map((v) => `${v.file} adds ${v.method} ${v.path}, not declared in the design's API changes`).join("; ");
+}
+
 // src/targeting.ts
 var import_node_path4 = require("node:path");
+
+// src/deniedPaths.ts
+function globToRegExp(pattern) {
+  const escaped = pattern.split("").map((c) => /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c).join("");
+  const withGlobs = escaped.replace(/\*\*\//g, " SLASH ").replace(/\*\*/g, " STAR ").replace(/\*/g, "[^/]*").replace(/ SLASH /g, "(?:.*/)?").replace(/ STAR /g, ".*");
+  return new RegExp(`^${withGlobs}$`);
+}
+function matchesDeniedPath(path, patterns) {
+  for (const pattern of patterns) {
+    if (globToRegExp(pattern).test(path)) return pattern;
+  }
+  return null;
+}
+
+// src/targeting.ts
+var CONTRACT_VERSION2 = "test-targets-1";
 function listWorkspaceFiles(workspaceRoot) {
   return listFiles(workspaceRoot ?? ".");
 }
-function validateTarget(target, workspaceRoot, workspaceListing) {
+function validateTarget(target, workspaceRoot, workspaceListing, deniedPaths) {
+  const denied = matchesDeniedPath(target.path, deniedPaths);
+  if (denied) {
+    throw new Error(
+      `pilot.targeting proposed a target matching a denied path (${denied}): ${target.path}`
+    );
+  }
   if (target.kind !== "EXISTING" && target.kind !== "NEW_FILE") {
     throw new Error(`pilot.targeting returned an unknown kind "${target.kind}" for ${target.path}`);
   }
@@ -771,8 +1058,22 @@ function validateTarget(target, workspaceRoot, workspaceListing) {
     );
   }
 }
-async function runTargeting(gateway, design, workspaceRoot, workspaceListing, requiredTests) {
-  const res = await fetch(`${gateway.baseUrl}/ai/execute`, {
+async function runTargeting(gateway, design, workspaceRoot, workspaceListing, requiredTests, deniedPaths) {
+  const contextData = {
+    // NESTED, NOT FLATTENED — a second vocabulary for the design shape is exactly what
+    // QUIKTR-1034 cost.
+    workspaceListing,
+    design,
+    // QUIKTR-1065/1083 — requiredTests carried through so targeting can propose a test-file
+    // target naming which cases it covers (§15.1's Case shape, unchanged).
+    requiredTests,
+    // QUIKTR-1083 (§15.6) — required on the versioned path.
+    contractVersion: CONTRACT_VERSION2
+  };
+  if (deniedPaths.length > 0) {
+    contextData.deniedPaths = deniedPaths;
+  }
+  const res = await fetchWithRetry(`${gateway.baseUrl}/ai/execute`, {
     method: "POST",
     headers: { "content-type": "application/json", "x-run-token": gateway.token },
     body: JSON.stringify({
@@ -780,18 +1081,14 @@ async function runTargeting(gateway, design, workspaceRoot, workspaceListing, re
       useCase: "pilot.targeting",
       expectedOutputType: "json",
       userPrompt: "",
-      // NESTED, NOT FLATTENED — a second vocabulary for the design shape is exactly what
-      // QUIKTR-1034 cost.
-      // QUIKTR-1065 — requiredTests carried through so targeting CAN propose a test-file
-      // target naming which cases it covers. The AI Runtime prompt doesn't read this yet
-      // (that half is theirs, not this package's) — sending it now is what makes it possible.
-      contextData: { workspaceListing, design, requiredTests }
+      contextData
     })
   });
   if (!res.ok) {
     throw new Error(`Targeting call failed: ${res.status} ${res.statusText}`);
   }
   const envelope = await res.json();
+  checkHardFailure(envelope, "pilot.targeting");
   const body = unwrapExecute(envelope, "pilot.targeting");
   if (body.outcome === "NO_TARGET") {
     return { outcome: "NO_TARGET", reason: body.noTargetReason ?? null };
@@ -801,9 +1098,13 @@ async function runTargeting(gateway, design, workspaceRoot, workspaceListing, re
   }
   const listing = new Set(workspaceListing);
   for (const target of body.targets) {
-    validateTarget(target, workspaceRoot, listing);
+    validateTarget(target, workspaceRoot, listing, deniedPaths);
   }
-  return { outcome: "TARGETED", targets: body.targets };
+  return {
+    outcome: "TARGETED",
+    targets: body.targets,
+    skippedCases: body.skippedCases ?? []
+  };
 }
 
 // src/tokenExchange.ts
@@ -813,7 +1114,7 @@ async function exchangeForRunToken(tokenUrl, oidcToken) {
     headers: { Authorization: `Bearer ${oidcToken}` }
   });
   if (!res.ok) {
-    throw new Error(`Exchange run token failed: ${res.status} ${res.statusText}`);
+    throw new Error(`Exchange run token failed: ${await describeQuikTrackFailure(res)}`);
   }
   const body = await res.json();
   if (body.success !== true) {
@@ -823,7 +1124,7 @@ async function exchangeForRunToken(tokenUrl, oidcToken) {
 }
 
 // src/run.ts
-async function run(env = readRunnerEnv()) {
+async function run(env2) {
   let hardFailure = false;
   let packet;
   let branch;
@@ -831,8 +1132,8 @@ async function run(env = readRunnerEnv()) {
   let warnings = [];
   let targeted = false;
   try {
-    runToken = await exchangeForRunToken(env.tokenUrl, await fetchGithubOidcToken());
-    packet = await fetchPacket(env.packetUrl, runToken, env.githubRunId);
+    runToken = await exchangeForRunToken(env2.tokenUrl, await fetchGithubOidcToken());
+    packet = await fetchPacket(env2.packetUrl, runToken, env2.githubRunId);
     checkoutTargetBranch(packet.targetBranch);
     const workspaceListing = listWorkspaceFiles(packet.workspaceRoot);
     const targeting = await runTargeting(
@@ -840,26 +1141,47 @@ async function run(env = readRunnerEnv()) {
       packet.design,
       packet.workspaceRoot,
       workspaceListing,
-      packet.requiredTests
+      packet.requiredTests,
+      packet.guardrails.deniedPaths
     );
     if (targeting.outcome === "NO_TARGET") {
-      writePhase0Marker(env.runId);
+      writePhase0Marker(env2.runId);
       runCommand(packet.commands.setup, "Setup");
       runCommand(packet.commands.lint, "Lint");
       runTestCommand(packet.commands.test);
     } else {
       targeted = true;
+      if (targeting.skippedCases?.length) {
+        for (const skipped of targeting.skippedCases) {
+          const w = `Test case ${skipped.automationId} has no given/when/then \u2014 skipped, no test was written for it.`;
+          warnings.push(w);
+          console.warn(`QuikPilot targeting warning (not blocking): ${w}`);
+        }
+      }
       const overlaps = findOverlappingSteps(targeting.targets);
-      if (overlaps.length > 0) {
-        warnings = describeOverlapWarnings(overlaps);
+      const blockingOverlaps = overlaps.filter((o) => o.severity === "identical");
+      const softOverlaps = overlaps.filter((o) => o.severity === "similar");
+      if (softOverlaps.length > 0) {
+        warnings = describeOverlapWarnings(softOverlaps);
         for (const w of warnings) {
           console.warn(`QuikPilot targeting warning (not blocking): ${w}`);
         }
       }
+      if (blockingOverlaps.length > 0) {
+        throw new Error(
+          `QuikPilot's generated plan gives two files identical instructions \u2014 ${describeOverlapWarnings(blockingOverlaps).join("; ")}`
+        );
+      }
       runCommand(packet.commands.setup, "Setup");
       const [baseline, results] = await Promise.all([
         captureBaselineSnapshot(packet.commands.test),
-        runCodegen(packet.gateway, targeting.targets, workspaceListing)
+        runCodegen(
+          packet.gateway,
+          targeting.targets,
+          workspaceListing,
+          packet.requiredTests,
+          packet.guardrails.deniedPaths
+        )
       ]);
       const depCheck = checkImportDependencies(
         results,
@@ -871,6 +1193,12 @@ async function run(env = readRunnerEnv()) {
           `QuikPilot's generated code imports packages this repository doesn't have \u2014 ${describeDependencyViolations(depCheck)}`
         );
       }
+      const scopeCheck = checkApiScope(results, targeting.targets, packet.design?.apiChanges ?? []);
+      if (scopeCheck.blocked) {
+        throw new Error(
+          `QuikPilot's generated code exceeds the approved design \u2014 ${describeScopeViolations(scopeCheck)}`
+        );
+      }
       flushCodegenResults(results);
       try {
         runCommand(packet.commands.format, "Format");
@@ -897,20 +1225,20 @@ async function run(env = readRunnerEnv()) {
   await reportToQuikTest({
     resultsUrl: packet?.quikTest?.resultsUrl,
     runToken,
-    githubServerUrl: env.githubServerUrl,
-    githubRepository: env.githubRepository,
-    githubRunId: env.githubRunId
+    githubServerUrl: env2.githubServerUrl,
+    githubRepository: env2.githubRepository,
+    githubRunId: env2.githubRunId
   });
   if (!hardFailure && packet) {
     try {
       checkGuardrail(packet.guardrails.deniedPaths);
       const installationToken = await exchangeForInstallationToken(
-        env.installationTokenUrl,
+        env2.installationTokenUrl,
         runToken
       );
       const result = commitAndPush(
         packet.branch,
-        env.runId,
+        env2.runId,
         installationToken,
         targeted,
         packet.issueKey,
@@ -923,7 +1251,7 @@ async function run(env = readRunnerEnv()) {
     }
   }
   await reportBack({
-    callbackUrl: env.callbackUrl,
+    callbackUrl: env2.callbackUrl,
     runToken,
     status: hardFailure ? "failed" : "completed",
     branch,
@@ -932,8 +1260,44 @@ async function run(env = readRunnerEnv()) {
   return { hardFailure };
 }
 
+// src/readinessCheck.ts
+async function runReadinessCheck(env2) {
+  let setupOk = true;
+  try {
+    runCommand(env2.setupCmd || null, "Setup");
+  } catch (err) {
+    setupOk = false;
+    console.error(err instanceof Error ? err.message : String(err));
+  }
+  const testOutcome = runTestCommand(env2.testCmd);
+  const testOk = testOutcome === "success";
+  const junitPath = findJUnitReport();
+  const result = {
+    setupOk,
+    testOk,
+    junitFound: junitPath !== null,
+    junitPath
+  };
+  try {
+    const res = await fetch(env2.readinessCallbackUrl, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${env2.readinessToken}`, "Content-Type": "application/json" },
+      body: JSON.stringify(result)
+    });
+    if (!res.ok) {
+      throw new Error(`Readiness callback POST failed: ${await describeQuikTrackFailure(res)}`);
+    }
+  } catch (err) {
+    console.warn(
+      `::warning::QuikPilot readiness check failed to report its result: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
 // src/index.ts
-run().then(({ hardFailure }) => {
+var env = readRunnerEnv();
+var task = env.mode === "readiness_check" ? runReadinessCheck(env).then(() => ({ hardFailure: false })) : run(env);
+task.then(({ hardFailure }) => {
   process.exitCode = hardFailure ? 1 : 0;
 }).catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));