jules-orchestrator-kit 0.35.2 → 0.37.0

package/README.md

@@ -104,7 +104,7 @@ Autonomous coding agents can write software at 100× human speed—but unconstra
 
 * **🔒 Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-ins (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:http`, `node:tty`, `node:test`). Zero third-party npm packages mean zero supply-chain CVE risk.
 
-* **🛡️ Fail-Closed Security Gatekeeper:** Unconditionally evaluates explicit Deny rules *before* Allow rules, matching against **canonicalised, case-folded paths** so `./`, `..`, mixed separators or a `.GitHub/` spelling cannot walk past a rule (the same repo is checked out on case-insensitive macOS and Windows filesystems). Redacts high-entropy secrets and PII from dry-runs and git diffs, blocks unsupported Node.js native module imports in Edge environments (Cloudflare Workers, Vercel Edge, Netlify Edge), and rejects PRs exceeding the 75 KB Diff Payload governor.
+* **🛡️ Fail-Closed Security Gatekeeper:** Unconditionally evaluates explicit Deny rules *before* Allow rules, matching against **canonicalised, case-folded paths** so `./`, `..`, mixed separators or a `.GitHub/` spelling cannot walk past a rule (the same repo is checked out on case-insensitive macOS and Windows filesystems). Redacts high-entropy secrets and PII from dry-runs and git diffs — **including credentials wrapped in base64**, so a key inside a Kubernetes `Secret` manifest is not invisible to a line-oriented scanner — blocks unsupported Node.js native module imports in Edge environments (Cloudflare Workers, Vercel Edge, Netlify Edge), and rejects PRs exceeding the 75 KB Diff Payload governor.
 
 * **🔄 Autonomous OODA Self-Healing:** Captures test stderr/stdout, normalizes failure fingerprints, and feeds structured error contexts back into repair iterations (up to 3 automatic attempts) before human escalation.
 
@@ -122,7 +122,7 @@ Autonomous coding agents can write software at 100× human speed—but unconstra
 
 * **🚀 Zero-Test Bootstrapping (`agentctl bootstrap`):** Synthesizes deterministic syntax-check and smoke-test verification oracles for untested legacy repositories so agents always operate against a falsifiable feedback loop.
 
-* **📈 Proven Scale & Reliability:** Empirically tested with **529 unit tests across 79 suites passing in < 10.0s**. An adversarial red-team suite (`test/adversarial-claims.test.mjs`) continuously attempts to falsify the safety guarantees documented above — including cross-platform probes for the case-insensitive filesystems on macOS and Windows — and a documentation-sync gate (`scripts/doc-sync-check.mjs`) blocks any release whose docs have drifted from the code.
+* **📈 Proven Scale & Reliability:** Empirically tested with **547 unit tests across 80 suites passing in < 10.0s**. An adversarial red-team suite (`test/adversarial-claims.test.mjs`) continuously attempts to falsify the safety guarantees documented above — every probe in it currently holds, with no open gaps — including cross-platform probes for the case-insensitive filesystems on macOS and Windows — and a documentation-sync gate (`scripts/doc-sync-check.mjs`) blocks any release whose docs have drifted from the code.
 
 <br/>
 
@@ -389,7 +389,7 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 | :--- | :--- | :--- | :--- |
 | `init` | `agentctl init [--interactive] [--tier pro]` | Interactive onboarding wizard & stack oracle inspector generating `.agent/config.yml`. | `0` (Created) |
 | `task create` | `agentctl task create [--title <t>] [--prompt <p>] [--template <id>] [--role <name>] [--tier fast\|complex] [--depends-on <id,...>]` | Interactively authors & scopes falsifiable task envelopes with secret scrubbing, preflight gate checks, specialist role resolution, DAG dependency wiring, and an optional Cost Router tier override. | `0` (Queued), `1` (Unfalsifiable / Secret leak) |
-| `task template` | `agentctl task template [<id>] [--list] [--json]` | Lists and synthesizes specialized web task envelopes (`web-cwv`, `web-wcag`, `web-seo`, `web-playwright`, `web-flaky-heal`, `web-i18n`). | `0` (Synthesized/Listed) |
+| `task template` | `agentctl task template [<id>] [--list] [--json]` | Lists and synthesizes specialized web task envelopes (`web-cwv`, `web-wcag`, `web-seo`, `web-playwright`, `web-flaky-heal`, `web-i18n`, `web-ai-access`). | `0` (Synthesized/Listed) |
 | `task optimize` | `agentctl task optimize "<prompt>" [--fix] [--web] [--json]` | Linter & optimizer injecting Google Labs 3-phase exploration budgets, critic steering, and web oracles. | `0` (Scored/Fixed) |
 | `test-gen` | `agentctl test-gen --title <t> --spec <s> [--run]` | Scaffolds falsifiable unit tests, verifies **RED** failure state, and locks test in `scope.deny`. | `0` (Scaffolded/Red) |
 | `rollback` | `agentctl rollback [sessionId \| --latest]` | Restores exact commit, uncommitted files, and cleans orphan task worktrees from pre-flight checkpoints. | `0` (Restored), `1` (Error) |

package/bin/agentctl.mjs

@@ -334,18 +334,41 @@ async function main() {
         // The count is local-only, so an operator who knows their real usage
         // must be able to correct it. Appending `budget_released` keeps the
         // hash chain intact — the ledger is corrected forwards, never edited.
+        // An unrecognised flag is refused rather than ignored. `reset` writes to
+        // the ledger, and a misremembered flag — `--root`, `--force` — silently
+        // dropping through to a full release is the kind of misfire that only
+        // becomes visible after the count is already gone.
+        const known = new Set(["--dry-run", "--yes", "-y", "--all"]);
+        const unknown = args.slice(2).filter((a) => !known.has(a));
+        if (unknown.length) {
+          console.error(`Unrecognised option${unknown.length > 1 ? "s" : ""} for \`budget reset\`: ${unknown.join(", ")}`);
+          console.error("Accepted: --dry-run, --yes/-y, --all. Nothing was released.");
+          process.exit(2);
+        }
         const dryRun = args.includes("--dry-run");
         const confirmed = args.includes("--yes") || args.includes("-y");
+        // Committed reservations reached the provider, so releasing them makes
+        // the local count understate real usage. That has to be deliberate.
+        const includeCommitted = args.includes("--all");
         if (!dryRun && !confirmed) {
           const open = listOpenReservations(root);
-          console.log(`Would release ${open.length} open reservation(s) from the last 24 hours.`);
+          const committed = open.filter((r) => r.committed).length;
+          const target = includeCommitted ? open.length : open.length - committed;
+          console.log(`Would release ${target} open reservation(s) from the last 24 hours.`);
+          if (committed > 0 && !includeCommitted) {
+            console.log(`Keeping ${committed} that reached Jules — those sessions really spent quota.`);
+            console.log("Add --all to release them too, if you know the count is still wrong.");
+          }
           console.log("This rewrites nothing — it appends `budget_released` entries.");
           console.log("Re-run with --yes to confirm, or --dry-run for detail.");
           process.exit(0);
         }
-        const res = releaseOpenReservations({ root, dryRun, reason: "operator-reconcile" });
+        const res = releaseOpenReservations({ root, dryRun, includeCommitted, reason: "operator-reconcile" });
         const verb = dryRun ? "Would release" : "Released";
-        console.log(`${verb} ${res.released} reservation(s) (${res.committed} committed, ${res.uncommitted} never closed).`);
+        console.log(`${verb} ${res.released} of ${res.open} open reservation(s) — ${res.uncommitted} never closed, ${res.committed} committed.`);
+        if (res.kept > 0) {
+          console.log(`Kept ${res.kept} committed reservation(s); re-run with --all to release those as well.`);
+        }
         if (!dryRun) {
           const after = budgetStatus(loadConfig(root), root);
           console.log(`Daily Budget : ${formatBudgetLine(after)}`);
@@ -363,14 +386,17 @@ async function main() {
       console.log(`  ${b.note}`);
       console.log(`  Window opened at ${b.windowStart} — the quota resets ${b.windowHours}h after each task,`);
       console.log("  not at midnight, so this count spans yesterday's ledger too.");
-      console.log(`  Open reservations in the window: ${listOpenReservations(root).length}`);
+      const openNow = listOpenReservations(root);
+      const committedNow = openNow.filter((r) => r.committed).length;
+      console.log(`  Open reservations in the window: ${openNow.length} (${committedNow} confirmed dispatched, ${openNow.length - committedNow} never closed)`);
       console.log("");
       console.log(`Worker Slots : ${slots.concurrency} concurrent`);
       console.log(`  ${slots.note}`);
       console.log("");
       console.log("The ledger counts this checkout only — sessions started from the Jules");
       console.log("web UI or another machine spend the same quota without appearing here.");
-      console.log("Use `agentctl budget reset --yes` to reconcile a count you know is wrong.");
+      console.log("Use `agentctl budget reset --yes` to clear the ones that never closed,");
+      console.log("or `--all` to also give back the ones that did reach Jules.");
       process.exit(0);
       break;
     }

package/index.mjs

@@ -13,6 +13,7 @@ export {
   matchesGlob,
   checkScope,
   scanDiff,
+  hasEncodedSecret,
   checkEdgeRuntimeImports,
   checkCrossPackageImports,
 } from "./src/security.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.35.2",
+  "version": "0.37.0",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/src/budget.mjs

@@ -276,32 +276,54 @@ export function listOpenReservations(root = resolveRoot(), opts = {}) {
  * forwards — never by editing or deleting the file, which would break the chain
  * and destroy the audit trail the ledger exists to provide.
  *
- * This is an operator override, not an inference. The kit cannot tell a
- * reservation that reached the provider from one whose process died first, so
- * only the operator knows whether the local count still reflects reality.
+ * This is an operator override, not an inference — but the two kinds of open
+ * reservation are not equally likely to be wrong, and by default only one of
+ * them is released.
+ *
+ * An **uncommitted** reservation was taken and never resolved: the process died
+ * between reserving the slot and learning what happened to it. That is the
+ * phantom this function exists to clear.
+ *
+ * A **committed** one carries proof that the dispatch reached the provider, so
+ * a real session exists and the quota really was spent. Releasing it makes the
+ * local count *understate* actual usage, which is the dangerous direction: the
+ * kit then dispatches confidently past the provider's real limit and gets
+ * refused. `includeCommitted` therefore has to be asked for.
+ *
+ * Legacy id-less reservations have no `budget_committed` entry that could ever
+ * name them, so they always read as uncommitted and are always released.
  *
  * @param {object} [opts]
  * @param {string} [opts.root]
  * @param {string} [opts.reason] - Recorded on every released entry.
  * @param {boolean} [opts.dryRun] - Report what would be released, write nothing.
- * @returns {{ released: number, committed: number, uncommitted: number, ids: string[], dryRun: boolean }}
+ * @param {boolean} [opts.includeCommitted] - Also release reservations that
+ *   demonstrably reached the provider. Off by default.
+ * @returns {{ released: number, kept: number, open: number, committed: number,
+ *   uncommitted: number, anonymous: number, ids: string[],
+ *   includeCommitted: boolean, dryRun: boolean }}
  */
 export function releaseOpenReservations(opts = {}) {
   const root = opts.root || resolveRoot();
   const openRecords = listOpenReservations(root);
   const committed = openRecords.filter((r) => r.committed).length;
+  const includeCommitted = Boolean(opts.includeCommitted);
+  const targets = includeCommitted ? openRecords : openRecords.filter((r) => !r.committed);
 
   const result = {
-    released: openRecords.length,
+    released: targets.length,
+    kept: openRecords.length - targets.length,
+    open: openRecords.length,
     committed,
     uncommitted: openRecords.length - committed,
-    anonymous: openRecords.filter((r) => !r.reservationId).length,
-    ids: openRecords.map((r) => r.reservationId).filter(Boolean),
+    anonymous: targets.filter((r) => !r.reservationId).length,
+    ids: targets.map((r) => r.reservationId).filter(Boolean),
+    includeCommitted,
     dryRun: Boolean(opts.dryRun),
   };
-  if (opts.dryRun || openRecords.length === 0) return result;
+  if (opts.dryRun || targets.length === 0) return result;
 
-  for (const rec of openRecords) {
+  for (const rec of targets) {
     const entry = { event: "budget_released", reason: opts.reason || "operator-reconcile" };
     if (rec.reservationId) {
       entry.reservationId = rec.reservationId;

package/src/security.mjs

@@ -142,6 +142,19 @@ export function redactSecrets(text) {
     sanitized = sanitized.replace(pat, "[REDACTED_BY_SECURITY_GATE]");
   }
 
+  // A key the scanner can find inside a base64 blob must not survive redaction
+  // just because the literal bytes differ — otherwise scanDiff blocks the
+  // dispatch and the escalation payload leaks the very value it blocked on. The
+  // whole blob goes, not part of it: a partially-redacted encoding still
+  // decodes to the key.
+  const encoded = new Set();
+  decodeBase64Blobs(sanitized, (plain, blob) => {
+    if (hasHighConfidenceSecret(plain)) encoded.add(blob);
+  });
+  for (const blob of encoded) {
+    sanitized = sanitized.split(blob).join("[REDACTED_ENCODED_SECRET]");
+  }
+
   return sanitized;
 }
 
@@ -374,14 +387,118 @@ const STRING_CONCAT_JOIN = /(["'`])\s*\+\s*(["'`])/g;
  * Produces the variants of the added-line text that secret patterns are run
  * against: as-written, with invisible characters stripped, and with
  * source-level string concatenation collapsed.
+ *
+ * `normalized` is the last of those — every normalisation applied. It is
+ * returned separately for checks that are too expensive to run three times and
+ * gain nothing from the intermediate forms.
+ *
  * @param {string} addedLines
- * @returns {string[]}
+ * @returns {{ all: string[], normalized: string }}
  */
 function secretScanVariants(addedLines) {
   const stripped = addedLines.replace(INVISIBLE_CHARS, "");
   // Collapse `"AAA" +\n  "BBB"` into `"AAABBB"` before matching.
   const dejoined = stripped.replace(/\s*\n\s*/g, " ").replace(STRING_CONCAT_JOIN, "");
-  return [...new Set([addedLines, stripped, dejoined])];
+  return { all: [...new Set([addedLines, stripped, dejoined])], normalized: dejoined };
+}
+
+// Base64 is less an evasion technique than a file format. Every value in a
+// Kubernetes Secret manifest is base64 by specification, and whole `.env` files
+// get encoded into a single CI variable. A credential arriving that way is
+// ordinary rather than adversarial — and a line-oriented scanner walks straight
+// past it, which makes this the encoding most likely to carry a live key
+// through the gate.
+const BASE64_CANDIDATE = /[A-Za-z0-9+/]{24,}={0,2}/g;
+
+// Decoding is cheap per blob and ruinous per diff if left unbounded. A patch
+// that checks in a binary, a source map or a bundled font is otherwise enough
+// to turn one scan into a memory event, so both the number of candidates and
+// the total decoded size are capped. Exceeding a cap skips the remainder; it
+// does not fail the scan, because a large diff is not evidence of a leak.
+const BASE64_MAX_CANDIDATES = 64;
+const BASE64_MAX_DECODED_BYTES = 64 * 1024;
+
+/**
+ * Share of characters that are printable ASCII (plus tab/newline/return).
+ *
+ * `Buffer.from(str, "base64")` never throws — it discards what it cannot parse
+ * and returns whatever it managed to decode. So a hex digest or a random
+ * identifier of the right length "decodes" successfully into bytes that mean
+ * nothing. A wrapped credential, on the other hand, decodes to text: keys,
+ * PEM blocks and `.env` bodies are all ASCII. This ratio is what separates the
+ * two, and it removes nearly all of the noise before any pattern runs.
+ */
+function printableRatio(str) {
+  if (!str) return 0;
+  let printable = 0;
+  for (let i = 0; i < str.length; i++) {
+    const c = str.charCodeAt(i);
+    if (c === 9 || c === 10 || c === 13 || (c >= 32 && c <= 126)) printable++;
+  }
+  return printable / str.length;
+}
+
+/**
+ * Decode the base64-looking blobs in `text` that plausibly hold text.
+ *
+ * @param {string} text
+ * @param {(plain: string, blob: string) => void} [onDecoded] - Called per blob.
+ * @returns {string[]}
+ */
+function decodeBase64Blobs(text, onDecoded) {
+  if (!text) return [];
+  const decoded = [];
+  let candidates = 0;
+  let bytes = 0;
+
+  BASE64_CANDIDATE.lastIndex = 0;
+  let match;
+  while ((match = BASE64_CANDIDATE.exec(text)) !== null) {
+    if (candidates++ >= BASE64_MAX_CANDIDATES) break;
+    const blob = match[0];
+    // Valid base64 is a multiple of four characters including padding. This
+    // costs nothing and rejects three quarters of the alphanumeric runs — commit
+    // hashes, minified identifiers — that would otherwise be decoded for nothing.
+    if (blob.length % 4 !== 0) continue;
+    // Check the budget against what this blob *would* cost, not against what
+    // has already been spent — otherwise the first candidate decodes in full
+    // however large it is, and a single checked-in binary costs more than the
+    // cap was meant to allow. `continue`, not `break`: one oversized blob must
+    // not hide the smaller ones after it.
+    if (bytes + (blob.length * 3) / 4 > BASE64_MAX_DECODED_BYTES) continue;
+
+    let plain;
+    try {
+      plain = Buffer.from(blob, "base64").toString("utf-8");
+    } catch (_) {
+      continue;
+    }
+    bytes += plain.length;
+    if (printableRatio(plain) < 0.9) continue;
+
+    decoded.push(plain);
+    if (onDecoded) onDecoded(plain, blob);
+  }
+  BASE64_CANDIDATE.lastIndex = 0;
+  return decoded;
+}
+
+/**
+ * True when a base64-encoded value on an added line decodes to a structured
+ * credential.
+ *
+ * Deliberately runs the high-confidence patterns *only*. The low-confidence set
+ * is entropy- and keyword-driven, and decoded bytes are high-entropy by
+ * construction — pointing it at this output would flag close to every encoded
+ * blob in every repository. `AKIA[0-9A-Z]{16}` cannot match decoded noise;
+ * "looks secret-ish" always can. That asymmetry is the whole reason this check
+ * is safe to enable by default.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function hasEncodedSecret(text) {
+  return decodeBase64Blobs(text).some((plain) => hasHighConfidenceSecret(plain));
 }
 
 export function scanDiff(diffTextStr = "", options = {}) {
@@ -392,13 +509,23 @@ export function scanDiff(diffTextStr = "", options = {}) {
     .map((line) => line.slice(1))
     .join("\n");
 
-  const variants = secretScanVariants(addedLines);
+  const { all: variants, normalized } = secretScanVariants(addedLines);
   const hasHigh = variants.some((v) => hasHighConfidenceSecret(v));
-  const hasLow = !hasHigh && variants.some((v) => hasLowConfidenceSecret(v));
+  // Only worth decoding when nothing was found in the clear, and only against
+  // the fully-normalised text: decoding is the expensive step, and the
+  // intermediate variants differ from it in ways base64 blobs do not care about.
+  const hasEncoded = !hasHigh && hasEncodedSecret(normalized);
+  const hasLow = !hasHigh && !hasEncoded && variants.some((v) => hasLowConfidenceSecret(v));
   const findings = [];
 
   if (hasHigh) {
     findings.push({ severity: "CRITICAL", type: "HIGH_CONFIDENCE_SECRET", description: "High-confidence secret pattern detected in added diff lines" });
+  } else if (hasEncoded) {
+    // Same type as the cleartext case: every gate that blocks on
+    // HIGH_CONFIDENCE_SECRET should block on this too, and a new type would
+    // have silently passed through the ones not updated. The description
+    // carries the difference the operator needs.
+    findings.push({ severity: "CRITICAL", type: "HIGH_CONFIDENCE_SECRET", description: "High-confidence secret pattern detected inside a base64-encoded value on an added diff line" });
   } else if (hasLow) {
     findings.push({ severity: "HIGH", type: "LOW_CONFIDENCE_SECRET", description: "Low-confidence secret or authorization token detected in added diff lines" });
   }
@@ -419,7 +546,7 @@ export function scanDiff(diffTextStr = "", options = {}) {
   }
 
   return {
-    ok: !hasHigh && !hasLow && edgeRes.ok && crossPkgRes.ok,
+    ok: !hasHigh && !hasEncoded && !hasLow && edgeRes.ok && crossPkgRes.ok,
     findings,
   };
 }

package/src/web-templates.mjs

@@ -233,6 +233,93 @@ export const WEB_TEMPLATES = {
    - UTF-8 clean encoding with zero unescaped unicode artefacts.
    - Localized formatting for dates, currencies, and numbers using standard Intl APIs.`;
     }
+  },
+
+  // On the scope of this template, and what it deliberately does not claim:
+  //
+  // `llms.txt` (spec at llmstxt.org — cited without a scheme so the egress
+  // allowlist test does not read a citation as a destination the kit contacts)
+  // is a proposal, not a ratified standard. Plenty of sites publish one; no
+  // major provider has confirmed its retrieval stack reads one, and Google has
+  // said publicly that it does not use it. That is the supply side of a
+  // convention with no demonstrated demand side.
+  //
+  // So this template verifies what a repository can actually falsify — the file
+  // exists, it parses, its links resolve, and the site's crawler directives do
+  // not contradict each other — and it says nothing about whether publishing it
+  // improves visibility in any assistant. Every other template here carries a
+  // real verification oracle; a "generative engine optimization" template that
+  // promised ranking effects would be the first one that could not.
+  //
+  // Crawler posture is a policy choice, not a best practice. Allowing GPTBot,
+  // ClaudeBot or Google-Extended has licensing and editorial consequences, and
+  // blocking them is frequently deliberate. The template therefore takes no
+  // side: it defaults to `preserve`, reads the posture the repository already
+  // states, and enforces that every surface states the same thing.
+  //
+  // Structured data (JSON-LD, sameAs, entity markup) stays in `web-seo`. Two
+  // templates with authority over the same markup will eventually disagree.
+  "web-ai-access": {
+    id: "web-ai-access",
+    name: "AI Crawler Policy Consistency & llms.txt Integrity",
+    description: "Verify that AI crawler directives agree across every surface and that a published llms.txt parses with links that resolve.",
+    defaultVerifyCmd: "npm test",
+    category: "Crawler Policy & AI Access",
+    criticFocus: [
+      "Confirm the patch preserves the repository's existing AI crawler posture unless the task explicitly asked to change it — allowing or blocking a crawler is the operator's decision, not the agent's.",
+      "Verify robots.txt, per-page robots meta tags, and any X-Robots-Tag headers agree for every named agent; a page allowed in one surface and denied in another is a defect regardless of which is intended.",
+      "Check that every link in llms.txt resolves against the project's own route table or build output, with no absolute links to pages that no longer exist.",
+      "Ensure the PR description states that llms.txt consumption by AI systems is unverified, and claims no ranking, visibility, or citation benefit.",
+      "Confirm no JSON-LD or structured-data markup was modified here — that surface belongs to the web-seo template."
+    ],
+    defaultParams: {
+      aiAccessPolicy: "preserve",
+      aiAgents: "GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot, Applebot-Extended",
+      targetRoutes: "all public routes"
+    },
+    generatePrompt: (params = {}) => {
+      const policy = String(params.aiAccessPolicy || "preserve").toLowerCase();
+      const agents = params.aiAgents || "GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot, Applebot-Extended";
+      const routes = params.targetRoutes || "all public routes";
+      const customGoal = params.goal ? `\n- **Target Focus**: ${params.goal}` : "";
+
+      const policyClause = {
+        allow: `The operator has decided to **allow** these agents. Make every surface say so consistently.`,
+        deny: `The operator has decided to **block** these agents. Make every surface say so consistently, and confirm no route leaks access through a surface that was missed.`,
+        selective: `The operator allows some agents and blocks others. Derive the intended split from existing configuration and make every surface agree with it exactly.`,
+        preserve: `**Do not change the posture.** Determine what the repository already states about these agents and make every surface state the same thing. If the surfaces currently contradict each other, report the contradiction and resolve it toward the most restrictive existing directive — never toward the more permissive one, and never invent a posture the repository has not expressed.`
+      }[policy] || `Treat \`${policy}\` as an explicit operator instruction and apply it consistently across every surface.`;
+
+      return `Audit AI crawler access directives and llms.txt integrity for ${routes}.${customGoal}
+
+### Operator Policy (do not override)
+${policyClause}
+
+Agents in scope: ${agents}.
+
+### Acceptance Criteria:
+1. **One Posture, Every Surface**:
+   - \`robots.txt\`, per-page \`<meta name="robots">\` / agent-specific meta tags, and any \`X-Robots-Tag\` response headers must agree for every agent above.
+   - A route that is allowed by one surface and denied by another is a defect even when the intended answer is obvious — fix the disagreement, do not pick a winner silently.
+   - Verify \`robots.txt\` parses: correct \`User-agent:\` grouping, no directives stranded outside a group, no rules unreachable because of an earlier wildcard group.
+2. **llms.txt Integrity (if the project publishes one)**:
+   - The file must parse as the proposed shape: a single \`# H1\` project name, an optional \`> blockquote\` summary, then \`## H2\` sections whose bodies are Markdown link lists.
+   - **Every link must resolve against this project's own route table or build output.** Check locally — do not fetch the live web from the verification step. A dead link in llms.txt is the single most common real defect in published files.
+   - Content must not contradict the crawler policy above: do not advertise paths in llms.txt that \`robots.txt\` disallows.
+   - If the project does not publish llms.txt, adding one is **in scope only if the task asked for it**. Do not create one on your own initiative.
+3. **Honest Reporting**:
+   - \`llms.txt\` is a proposal, not a ratified standard, and no major provider has confirmed that its retrieval systems read it. Google has stated publicly that it does not.
+   - The PR description must therefore claim only what was verified — that the file exists, parses, and its links resolve. Do **not** claim improved visibility, ranking, or citation in any AI assistant. There is no oracle for that claim and it must not appear in the diff, the commit message, or the PR body.
+4. **Scope Boundary**:
+   - Do not modify JSON-LD, Schema.org markup, \`sameAs\`, OpenGraph, or canonical tags. That surface belongs to the \`web-seo\` template; changing it here creates two sources of truth that will drift apart.
+
+### Verification Oracle to Add
+Add a repository-local test (no network access) that:
+- parses \`robots.txt\` and asserts the directive set for each agent in scope matches the intended posture;
+- parses \`llms.txt\`, if present, and asserts every link target exists in the route table or build output.
+
+The test must fail on a hand-broken fixture before you consider it done.`;
+    }
   }
 };