@quikit/quikpilot-runner 7.0.5 → 8.1.0

package/dist/index.js

@@ -23,18 +23,67 @@ 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 } = params;
+  const { callbackUrl, runToken, status, branch, warnings } = params;
   const body = { status };
   if (branch) body.branch = branch;
+  if (warnings && warnings.length > 0) body.warnings = warnings;
   const res = await fetch(callbackUrl, {
     method: "POST",
     headers: { Authorization: `Bearer ${runToken}`, "Content-Type": "application/json" },
     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)}`);
   }
 }
 
@@ -130,14 +179,21 @@ function push(branch, installationToken) {
 }
 
 // src/commit.ts
-function commitAndPush(branch, runId, installationToken) {
+function buildCommitMessage(runId, targeted, issueKey, issueTitle) {
+  if (!targeted) return `QuikPilot Phase 0 skeleton (run ${runId})`;
+  if (issueKey && issueTitle) return `${issueKey}: ${issueTitle}
+
+QuikPilot run ${runId}`;
+  return `QuikPilot generated changes (run ${runId})`;
+}
+function commitAndPush(branch, runId, installationToken, targeted, issueKey, issueTitle) {
   if (!hasStagedChanges()) return { changed: false };
   if (!branch) {
     throw new Error("packet carried no branch name");
   }
   configureCommitIdentity();
   checkoutNewBranch(branch);
-  commit(`QuikPilot Phase 0 skeleton (run ${runId})`);
+  commit(buildCommitMessage(runId, targeted, issueKey, issueTitle));
   push(branch, installationToken);
   return { changed: true, branch };
 }
@@ -147,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(
@@ -159,35 +223,131 @@ 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";
-function findNearestSibling(targetPath, workspaceListing) {
-  let dir = (0, import_node_path.dirname)(targetPath);
-  for (; ; ) {
-    const candidate = workspaceListing.find((f) => f !== targetPath && (0, import_node_path.dirname)(f) === dir);
-    if (candidate) return candidate;
-    const parent = (0, import_node_path.dirname)(dir);
-    if (parent === dir) return null;
-    dir = parent;
+var CONTEXT_TOO_LARGE_CODE = "CODEGEN_CONTEXT_TOO_LARGE";
+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;
 }
-async function runCodegen(gateway, targets, workspaceListing) {
+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) {
     const isNewFile = target.kind === "NEW_FILE";
     const currentContent = isNewFile ? "" : (0, import_node_fs.readFileSync)(target.path, "utf8");
+    const contextPaths = target.contextPaths ?? [];
+    for (const contextPath of contextPaths) {
+      if (!listing.has(contextPath)) {
+        throw new Error(
+          `pilot.codegen contextPaths named a file not found in the checkout: ${contextPath} (target ${target.path})`
+        );
+      }
+    }
+    const contextContents = contextPaths.map((path) => ({ path, content: (0, import_node_fs.readFileSync)(path, "utf8") }));
     const contextData = {
       targetPath: target.path,
       currentContent,
       planSteps: target.planStepsImplemented,
-      kind: target.kind
+      kind: target.kind,
+      contextContents,
+      // QUIKTR-1083 (§15.6) — required on every call on the versioned path.
+      contractVersion: CONTRACT_VERSION
     };
     if (isNewFile) {
       contextData.workspaceListing = workspaceListing;
-      const sibling = findNearestSibling(target.path, workspaceListing);
-      if (sibling) contextData.siblingContent = (0, import_node_fs.readFileSync)(sibling, "utf8");
     }
-    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({
@@ -202,8 +362,10 @@ async function runCodegen(gateway, targets, workspaceListing) {
       throw new Error(`Codegen call failed for ${target.path}: ${res.status} ${res.statusText}`);
     }
     const envelope = await res.json();
-    if (envelope?.errorCode === FILE_TOO_LARGE_CODE) {
-      throw new Error(`Codegen refused ${target.path}: ${FILE_TOO_LARGE_CODE} (not retried)`);
+    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}`);
     }
     const body = unwrapExecute(envelope, "pilot.codegen");
     if (body.outcome !== "GENERATED" || typeof body.newContent !== "string") {
@@ -211,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;
@@ -265,30 +445,32 @@ var NODE_BUILTINS = /* @__PURE__ */ new Set([
   "inspector",
   "async_hooks"
 ]);
-function packageNameFromSpecifier(specifier) {
+var DEFAULT_ALIAS_PREFIXES = ["@/", "~/"];
+function packageNameFromSpecifier(specifier, aliasPrefixes = DEFAULT_ALIAS_PREFIXES) {
   if (specifier.startsWith(".") || specifier.startsWith("/")) return null;
   if (specifier.startsWith("node:")) return null;
+  if (aliasPrefixes.some((prefix) => specifier.startsWith(prefix))) return null;
   const segments = specifier.split("/");
   const name = specifier.startsWith("@") ? segments.slice(0, 2).join("/") : segments[0];
   if (NODE_BUILTINS.has(name)) return null;
   return name;
 }
-function scanImports(source) {
+function scanImports(source, aliasPrefixes = DEFAULT_ALIAS_PREFIXES) {
   const found = /* @__PURE__ */ new Set();
   let match;
   IMPORT_RE.lastIndex = 0;
   while (match = IMPORT_RE.exec(source)) {
-    const name = packageNameFromSpecifier(match[2]);
+    const name = packageNameFromSpecifier(match[2], aliasPrefixes);
     if (name) found.add(name);
   }
   return [...found];
 }
-function checkImportDependencies(results, declaredDependencies) {
+function checkImportDependencies(results, declaredDependencies, aliasPrefixes = DEFAULT_ALIAS_PREFIXES) {
   if (!declaredDependencies) return { blocked: false, violations: [] };
   const violations = [];
   for (const { targetPath, newContent } of results) {
     if (!SCANNABLE_EXTENSIONS.some((ext) => targetPath.endsWith(ext))) continue;
-    const invented = scanImports(newContent).filter((pkg) => !declaredDependencies.has(pkg));
+    const invented = scanImports(newContent, aliasPrefixes).filter((pkg) => !declaredDependencies.has(pkg));
     if (invented.length > 0) violations.push({ file: targetPath, packages: invented });
   }
   return { blocked: violations.length > 0, violations };
@@ -320,28 +502,86 @@ function readDeclaredDependencies(results, workspaceRoot) {
     return null;
   }
 }
-function describeDependencyViolations(check) {
-  return check.violations.map((v) => `${v.file} imports ${v.packages.join(", ")}, not a dependency of this repository`).join("; ");
+function stripJsonComments(text) {
+  let out = "";
+  let inString = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    const next = text[i + 1];
+    if (inLineComment) {
+      if (c === "\n") {
+        inLineComment = false;
+        out += c;
+      }
+      continue;
+    }
+    if (inBlockComment) {
+      if (c === "*" && next === "/") {
+        inBlockComment = false;
+        i++;
+      }
+      continue;
+    }
+    if (inString) {
+      out += c;
+      if (c === "\\") {
+        out += next;
+        i++;
+        continue;
+      }
+      if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      out += c;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      inLineComment = true;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      inBlockComment = true;
+      i++;
+      continue;
+    }
+    out += c;
+  }
+  return out.replace(/,(\s*[}\]])/g, "$1");
 }
-
-// src/env.ts
-function required(name, value) {
-  if (!value) {
-    throw new Error(`Missing required environment variable: ${name}`);
+function resolveAliasPrefixes(results, workspaceRoot) {
+  const root = (0, import_node_path2.resolve)(workspaceRoot ?? ".");
+  for (const filename of ["tsconfig.json", "jsconfig.json"]) {
+    const configPath = (0, import_node_path2.join)(root, filename);
+    const generated = results.find((r) => (0, import_node_path2.resolve)(r.targetPath) === configPath);
+    let raw;
+    if (generated) {
+      raw = generated.newContent;
+    } else {
+      try {
+        raw = (0, import_node_fs2.readFileSync)(configPath, "utf8");
+      } catch {
+        raw = null;
+      }
+    }
+    if (raw === null) continue;
+    try {
+      const parsed = JSON.parse(stripJsonComments(raw));
+      const paths = parsed.compilerOptions?.paths;
+      const fromConfig = paths && typeof paths === "object" ? Object.keys(paths).map((k) => k.endsWith("*") ? k.slice(0, -1) : k) : [];
+      return [.../* @__PURE__ */ new Set([...DEFAULT_ALIAS_PREFIXES, ...fromConfig])];
+    } catch {
+      continue;
+    }
   }
-  return value;
+  return DEFAULT_ALIAS_PREFIXES;
 }
-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)
-  };
+function describeDependencyViolations(check) {
+  return check.violations.map((v) => `${v.file} imports ${v.packages.join(", ")}, not a dependency of this repository`).join("; ");
 }
 
 // src/guardrail.ts
@@ -361,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) {
@@ -372,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)}`;
@@ -396,6 +636,108 @@ async function fetchGithubOidcToken(env = process.env) {
   return body.value;
 }
 
+// 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",
+  "the",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "of",
+  "to",
+  "in",
+  "on",
+  "for",
+  "with",
+  "at",
+  "by",
+  "from",
+  "as",
+  "and",
+  "or",
+  "not",
+  "no",
+  "nor",
+  "this",
+  "that",
+  "these",
+  "those",
+  "it",
+  "its",
+  "cannot",
+  "can't",
+  "should",
+  "must",
+  "may",
+  "will",
+  "shall",
+  "when",
+  "if",
+  "than",
+  "then",
+  "so",
+  "do",
+  "does",
+  "did"
+]);
+var MIN_WORD_LENGTH = 3;
+function significantWords(step) {
+  return new Set(
+    step.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((w) => w.length >= MIN_WORD_LENGTH && !STOPWORDS.has(w))
+  );
+}
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const w of a) if (b.has(w)) intersection++;
+  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(
+    (target) => target.planStepsImplemented.map((step) => ({
+      target: target.path,
+      step,
+      words: significantWords(step)
+    }))
+  );
+  const warnings = [];
+  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,
+          severity: normalizedStep(items[i].step) === normalizedStep(items[j].step) ? "identical" : "similar"
+        });
+      }
+    }
+  }
+  return warnings;
+}
+function describeOverlapWarnings(warnings) {
+  return warnings.map(
+    (w) => `${w.targetA} and ${w.targetB} both implement what looks like the same rule \u2014 "${w.stepA}" / "${w.stepB}". Check these aren't two independent implementations of the same behavior.`
+  );
+}
+
 // src/packet.ts
 async function fetchPacket(packetUrl, runToken, githubRunId) {
   const url = `${packetUrl}?githubRunId=${encodeURIComponent(githubRunId)}`;
@@ -403,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) {
@@ -479,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" },
@@ -502,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)) {
@@ -512,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);
@@ -527,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`);
@@ -563,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}`);
   }
@@ -588,8 +1058,22 @@ function validateTarget(target, workspaceRoot, workspaceListing) {
     );
   }
 }
-async function runTargeting(gateway, design, workspaceRoot, workspaceListing) {
-  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({
@@ -597,15 +1081,14 @@ async function runTargeting(gateway, design, workspaceRoot, workspaceListing) {
       useCase: "pilot.targeting",
       expectedOutputType: "json",
       userPrompt: "",
-      // NESTED, NOT FLATTENED — a second vocabulary for the design shape is exactly what
-      // QUIKTR-1034 cost.
-      contextData: { workspaceListing, design }
+      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 };
@@ -615,9 +1098,13 @@ async function runTargeting(gateway, design, workspaceRoot, workspaceListing) {
   }
   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
@@ -627,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) {
@@ -637,42 +1124,81 @@ async function exchangeForRunToken(tokenUrl, oidcToken) {
 }
 
 // src/run.ts
-async function run(env = readRunnerEnv()) {
+async function run(env2) {
   let hardFailure = false;
   let packet;
   let branch;
   let runToken;
+  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(
       packet.gateway,
       packet.design,
       packet.workspaceRoot,
-      workspaceListing
+      workspaceListing,
+      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);
+      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,
-        readDeclaredDependencies(results, packet.workspaceRoot)
+        readDeclaredDependencies(results, packet.workspaceRoot),
+        resolveAliasPrefixes(results, packet.workspaceRoot)
       );
       if (depCheck.blocked) {
         throw new Error(
           `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");
@@ -699,18 +1225,25 @@ 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, installationToken);
+      const result = commitAndPush(
+        packet.branch,
+        env2.runId,
+        installationToken,
+        targeted,
+        packet.issueKey,
+        packet.issueTitle
+      );
       branch = result.branch;
     } catch (err) {
       hardFailure = true;
@@ -718,16 +1251,53 @@ async function run(env = readRunnerEnv()) {
     }
   }
   await reportBack({
-    callbackUrl: env.callbackUrl,
+    callbackUrl: env2.callbackUrl,
     runToken,
     status: hardFailure ? "failed" : "completed",
-    branch
+    branch,
+    warnings
   });
   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));