@theagilemonkeys/facility 0.3.1

package/templates/delivery/verify.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// Generated by facility — deterministic /builder delivery acceptance.
+import { execFileSync } from "node:child_process";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const mode = process.argv[2];
+const repo = required("GITHUB_REPOSITORY");
+const defaultBranch = required("DEFAULT_BRANCH");
+const receiptDir = join(required("RUNNER_TEMP"), "facility-delivery");
+const receiptPath = join(receiptDir, "receipt.json");
+const conventionalSubject =
+  /^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\((?=\S)[^()\r\n]*[^\s()\r\n]\))?!?: \S.*$/;
+
+if (mode === "discover") discover();
+else if (mode === "finalize") finalize();
+else throw new Error("Usage: verify.mjs discover|finalize");
+
+function discover() {
+  const event = JSON.parse(readFileSync(required("GITHUB_EVENT_PATH"), "utf8"));
+  const startedAt = required("FACILITY_STARTED_AT");
+  const startSha = required("FACILITY_START_SHA");
+  const existingPr =
+    event.pull_request?.number ?? (event.issue?.pull_request ? event.issue.number : undefined);
+  const pr = existingPr ? pull(existingPr) : newlyOpenedPull(startedAt);
+
+  assert(pr.state === "open", `PR #${pr.number} is not open`);
+  assert(!pr.draft, `PR #${pr.number} is still a draft; automated review would not run`);
+  assert(
+    pr.base?.ref === defaultBranch,
+    `PR #${pr.number} targets ${pr.base?.ref}, not ${defaultBranch}`,
+  );
+  assert(pr.head?.repo?.full_name === repo, `PR #${pr.number} is not a same-repository PR`);
+  assert(
+    pr.user?.type === "Bot",
+    `PR #${pr.number} is not bot-authored; address-review would be disabled`,
+  );
+  assert(
+    /^(feature|fix|chore|ci|docs|refactor|perf|test|build|revert)\/[a-z0-9][a-z0-9._/-]*$/.test(
+      pr.head.ref,
+    ),
+    `branch ${pr.head?.ref} is not semantic or still carries an agent/tool prefix`,
+  );
+  assert(pr.head?.sha !== startSha, "builder reported success without delivering a new commit");
+
+  const commits = ghJson(["api", `repos/${repo}/pulls/${pr.number}/commits?per_page=100`]);
+  const startIndex = commits.findIndex((commit) => commit.sha === startSha);
+  if (existingPr) {
+    assert(
+      startIndex >= 0,
+      `PR #${pr.number} no longer contains its pre-builder head; history was rewritten`,
+    );
+  }
+  const delivered = startIndex >= 0 ? commits.slice(startIndex + 1) : commits;
+  assert(delivered.length > 0, `PR #${pr.number} contains no builder-delivered commits`);
+
+  for (const commit of delivered) {
+    const message = commit.commit?.message ?? "";
+    const subject = message.split(/\r?\n/, 1)[0];
+    assert(
+      !hasForbiddenSubjectCharacters(subject) && conventionalSubject.test(subject),
+      `commit ${commit.sha} is not Conventional Commits: ${subject}`,
+    );
+    assert(
+      !/^Co-authored-by:/im.test(message),
+      `commit ${commit.sha} contains a Co-authored-by trailer`,
+    );
+    assert(
+      commit.commit?.verification?.verified === true,
+      `commit ${commit.sha} is not verified by GitHub`,
+    );
+  }
+
+  mkdirSync(receiptDir, { recursive: true });
+  const receipt = {
+    schema: "facility.delivery.v1",
+    repository: repo,
+    pullRequest: { number: pr.number, url: pr.html_url, base: pr.base.ref },
+    branch: pr.head.ref,
+    headSha: pr.head.sha,
+    author: pr.user.login,
+    deliveredCommits: delivered.map((commit) => commit.sha),
+    startedAt,
+    verification: "pending",
+  };
+  writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+  output("pr_number", String(pr.number));
+  output("head_ref", pr.head.ref);
+  output("head_sha", pr.head.sha);
+  console.log(`Validated delivery metadata for ${pr.html_url} at ${pr.head.sha}.`);
+}
+
+function finalize() {
+  const prNumber = required("FACILITY_PR_NUMBER");
+  const headRef = required("FACILITY_HEAD_REF");
+  const headSha = required("FACILITY_HEAD_SHA");
+  const pr = pull(prNumber);
+  assert(pr.head?.ref === headRef, `PR #${prNumber} head branch changed during verification`);
+  assert(pr.head?.sha === headSha, `PR #${prNumber} head commit changed during verification`);
+
+  const receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+  receipt.verification = "passed";
+  receipt.verifiedAt = new Date().toISOString();
+  writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+  console.log(JSON.stringify(receipt));
+}
+
+function newlyOpenedPull(startedAt) {
+  const pulls = ghJson([
+    "api",
+    `repos/${repo}/pulls?state=open&base=${encodeURIComponent(defaultBranch)}&sort=created&direction=desc&per_page=50`,
+  ]).filter(
+    (pr) =>
+      pr.head?.repo?.full_name === repo &&
+      pr.created_at >= startedAt &&
+      pr.head?.sha !== process.env.FACILITY_START_SHA,
+  );
+  assert(
+    pulls.length === 1,
+    `expected exactly one new PR from this builder run; found ${pulls.length}`,
+  );
+  return pulls[0];
+}
+
+function pull(number) {
+  return ghJson(["api", `repos/${repo}/pulls/${number}`]);
+}
+
+function ghJson(args) {
+  return JSON.parse(execFileSync("gh", args, { encoding: "utf8" }));
+}
+
+function output(name, value) {
+  appendFileSync(required("GITHUB_OUTPUT"), `${name}=${value}\n`);
+}
+
+function hasForbiddenSubjectCharacters(subject) {
+  return [...subject].some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return (
+      codePoint <= 0x1f ||
+      (codePoint >= 0x7f && codePoint <= 0x9f) ||
+      codePoint === 0x2028 ||
+      codePoint === 0x2029
+    );
+  });
+}
+
+function required(name) {
+  const value = process.env[name];
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}

package/templates/doctor/resolve.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+// Generated by facility — https://github.com/theam/facility
+//
+// Deterministic doctor resolver. Runs on every completed watched workflow and
+// decides — with rules, not judgment — what the doctor may do:
+//
+//   none    not a failure / not a PR / already handled (fingerprint dedup)
+//   triage  post one concise comment pointing a human at the failure
+//   repair  start the bounded repair agent (crew-authored PRs only, and only
+//           when neither the failure nor the PR touches a sensitive surface)
+//
+// The repair policy is deliberately conservative: human branches get triage,
+// never uninvited commits. Sensitive surfaces are always triage-only.
+// Env: GH_TOKEN, GITHUB_REPOSITORY, GITHUB_EVENT_PATH, GITHUB_OUTPUT.
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+
+const SENSITIVE_PATHS = [
+  ".github/workflows/",
+  ".github/facility/",
+  "guards/",
+  ".claude/",
+  ".env",
+  "migrations/",
+  "supabase/migrations/",
+  "db/migrations/",
+  "prisma/migrations/",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+];
+
+const repo = process.env.GITHUB_REPOSITORY;
+const event = JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, "utf8"));
+const run = event.workflow_run;
+const gh = (args) => execFileSync("gh", args, { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
+const out = (key, value) => appendFileSync(process.env.GITHUB_OUTPUT, `${key}=${value}\n`);
+
+function decide() {
+  if (run?.conclusion !== "failure") return { action: "none", reason: "watched run did not fail" };
+  const prNumber = run.pull_requests?.[0]?.number;
+  if (!prNumber) return { action: "none", reason: "no same-repo PR attached to the failed run" };
+
+  const pr = JSON.parse(gh(["api", `repos/${repo}/pulls/${prNumber}`]));
+  if (pr.state !== "open" || pr.draft) return { action: "none", reason: "PR closed or draft" };
+
+  const fingerprint = createHash("sha256")
+    .update(`${run.name}|${run.head_branch}`)
+    .digest("hex")
+    .slice(0, 16);
+  const marker = `<!-- facility-doctor:${fingerprint} -->`;
+  const comments = JSON.parse(
+    gh(["api", `repos/${repo}/issues/${prNumber}/comments?per_page=100`]),
+  );
+  if (comments.some((c) => c.body?.includes(marker))) {
+    return { action: "none", reason: "this failure fingerprint was already handled on the PR" };
+  }
+
+  const failedJobs = JSON.parse(
+    gh(["api", `repos/${repo}/actions/runs/${run.id}/jobs?per_page=50`]),
+  )
+    .jobs.filter((j) => j.conclusion === "failure")
+    .map((j) => ({
+      name: j.name,
+      steps: (j.steps ?? []).filter((s) => s.conclusion === "failure").map((s) => s.name),
+    }));
+
+  const files = gh([
+    "api",
+    `repos/${repo}/pulls/${prNumber}/files?per_page=100`,
+    "--jq",
+    ".[].filename",
+  ])
+    .split("\n")
+    .filter(Boolean);
+  const sensitive = files.filter((f) =>
+    SENSITIVE_PATHS.some((p) => f === p || f.startsWith(p) || f.includes(`/${p}`)),
+  );
+  const authorIsBot = (pr.user?.login ?? "").endsWith("[bot]");
+
+  const base = { prNumber, pr, fingerprint, marker, failedJobs, sensitive };
+  if (sensitive.length)
+    return {
+      ...base,
+      action: "triage",
+      reason: `PR touches sensitive surfaces (${sensitive.slice(0, 5).join(", ")})`,
+    };
+  if (!authorIsBot)
+    return {
+      ...base,
+      action: "triage",
+      reason: "human-authored PR — the doctor never commits to your branch uninvited",
+    };
+  return { ...base, action: "repair", reason: "crew-authored PR, non-sensitive failure" };
+}
+
+const decision = decide();
+console.log(`doctor: ${decision.action} — ${decision.reason}`);
+out("action", decision.action);
+if (decision.action === "none") process.exit(0);
+
+const jobsText = decision.failedJobs
+  .map((j) => `- **${j.name}**${j.steps.length ? ` → ${j.steps.join(", ")}` : ""}`)
+  .join("\n");
+
+if (decision.action === "triage") {
+  const body = [
+    `**Doctor triage** — \`${run.name}\` failed on this PR ([run](${run.html_url})).`,
+    "",
+    jobsText,
+    "",
+    `Not auto-repaired: ${decision.reason}.`,
+    decision.marker,
+  ].join("\n");
+  gh(["api", `repos/${repo}/issues/${decision.prNumber}/comments`, "-f", `body=${body}`]);
+  process.exit(0);
+}
+
+// repair: hand the agent a sanitized task packet (names and refs only — no
+// raw logs, which can carry secrets; the agent reproduces on the provisioned
+// runner instead).
+mkdirSync(".facility-doctor", { recursive: true });
+writeFileSync(
+  ".facility-doctor/context.json",
+  JSON.stringify(
+    {
+      schema: "facility.doctor.context.v1",
+      failure: { workflow: run.name, runUrl: run.html_url, failedJobs: decision.failedJobs },
+      pr: {
+        number: decision.prNumber,
+        headRef: decision.pr.head.ref,
+        baseRef: decision.pr.base.ref,
+      },
+      fingerprint: decision.fingerprint,
+      marker: decision.marker,
+    },
+    null,
+    2,
+  ),
+);
+out("pr_number", String(decision.prNumber));
+out("head_ref", decision.pr.head.ref);
+out("fingerprint", decision.fingerprint);

package/templates/guards/README.md

@@ -0,0 +1,30 @@
+# Guards
+
+Deterministic, fast invariant checks for this repository, run as **one**
+umbrella status. Generated by [facility](https://github.com/theam/facility);
+every file here is yours.
+
+```
+node guards/run.mjs                 # run all guards
+node guards/run.mjs --only=<name>   # run one guard (repeatable)
+node guards/run.mjs --json          # machine-readable (CI / agents)
+node guards/run.mjs --list          # list registered guards
+```
+
+The rule behind this directory, from `STANDARD.md`: **if a rule is repeatedly
+missed, add a deterministic check instead of more prose.** Prose decays;
+checks hold.
+
+## Add a guard
+
+1. Create `guards/<name>.mjs` exporting a default `{ name, description,
+   requires?, run() }`. Return a list of `{ file?, line?, message }`
+   violations (empty = pass). Keep it deterministic and read-only.
+2. Give it an in-code `ALLOWLIST` (keyed, with a written reason per entry) for
+   justified exceptions — `applyAllowlist` from `_kit.mjs` flags stale entries
+   so the list cannot rot.
+3. To wrap an existing CLI/DB check instead of porting its logic, use
+   `commandGuard(...)` from `_kit.mjs`.
+4. Guards needing external state declare `requires: ["SOME_ENV_VAR"]` and are
+   **skipped** (not failed) when it is absent, so local runs stay fast while
+   CI runs everything.

package/templates/guards/_kit.mjs

@@ -0,0 +1,81 @@
+// Generated by facility — https://github.com/theam/facility
+//
+// Small helpers for writing guards. Zero dependencies; everything is yours
+// to read and change.
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Recursively list files under `dir` matching any of `extensions`. */
+export function listFiles(dir, extensions, ignore = ["node_modules", ".git"]) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (ignore.includes(entry)) continue;
+    const path = join(dir, entry);
+    const stats = statSync(path);
+    if (stats.isDirectory()) out.push(...listFiles(path, extensions, ignore));
+    else if (extensions.some((ext) => entry.endsWith(ext))) out.push(path);
+  }
+  return out;
+}
+
+/** Read a file as UTF-8, returning "" when it does not exist. */
+export function readText(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Wrap an existing CLI/DB check as a guard instead of re-implementing its
+ * logic. The command's non-zero exit becomes a single violation carrying its
+ * output tail.
+ */
+export function commandGuard({ name, description, command, args = [], requires = [] }) {
+  return {
+    name,
+    description,
+    requires,
+    run() {
+      try {
+        execFileSync(command, args, { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+        return [];
+      } catch (error) {
+        const tail = `${error.stdout ?? ""}${error.stderr ?? ""}`
+          .trim()
+          .split("\n")
+          .slice(-12)
+          .join("\n");
+        return [{ message: `\`${[command, ...args].join(" ")}\` failed:\n${tail}` }];
+      }
+    },
+  };
+}
+
+/**
+ * Filter violations through a keyed allowlist. Every allowlist entry must
+ * carry a written reason; entries that no longer match anything are reported
+ * as stale so the list cannot rot.
+ */
+export function applyAllowlist(violations, allowlist) {
+  const used = new Set();
+  const kept = violations.filter((violation) => {
+    const hit = Object.keys(allowlist).find((key) => violation.key === key);
+    if (hit) used.add(hit);
+    return !hit;
+  });
+  for (const key of Object.keys(allowlist)) {
+    if (!used.has(key)) {
+      kept.push({ message: `stale allowlist entry "${key}" (${allowlist[key]}) — remove it` });
+    }
+  }
+  return kept;
+}

package/templates/guards/actions-pinned.mjs

@@ -0,0 +1,38 @@
+// Generated by facility — https://github.com/theam/facility
+//
+// Every third-party GitHub Action must be pinned to a full commit SHA.
+// Tags and branches are mutable: a compromised action repo can re-point
+// `v4` at malicious code and your CI — which holds secrets and write
+// tokens — runs it on the next push. A 40-hex SHA cannot be re-pointed.
+import { applyAllowlist, listFiles, readText } from "./_kit.mjs";
+
+// key: "<file>:<uses-ref>", value: written reason. Keep this empty unless a
+// pin is truly impossible; document why.
+const ALLOWLIST = {};
+
+export default {
+  name: "actions-pinned",
+  description: "third-party GitHub Actions are pinned to full commit SHAs",
+  run() {
+    const violations = [];
+    for (const file of listFiles(".github/workflows", [".yml", ".yaml"])) {
+      const lines = readText(file).split("\n");
+      lines.forEach((line, index) => {
+        const match = line.match(/^\s*(?:-\s+)?uses:\s*([^\s#]+)/);
+        if (!match) return;
+        const ref = match[1].replace(/^["']|["']$/g, "");
+        if (ref.startsWith("./") || ref.startsWith("docker://")) return;
+        const pinned = /@[0-9a-f]{40}$/.test(ref);
+        if (!pinned) {
+          violations.push({
+            file,
+            line: index + 1,
+            key: `${file}:${ref}`,
+            message: `"${ref}" is not pinned to a full commit SHA (use @<40-hex-sha> with a version comment)`,
+          });
+        }
+      });
+    }
+    return applyAllowlist(violations, ALLOWLIST);
+  },
+};

package/templates/guards/run.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Generated by facility — https://github.com/theam/facility
+//
+// Deterministic, fast invariant checks that run as ONE umbrella status
+// instead of a sprawl of bespoke CI steps. Standard toolchain checks
+// (typecheck, lint, tests, build) stay as their own statuses — guards are
+// only for repo-specific invariants.
+//
+//   node guards/run.mjs                 run all guards
+//   node guards/run.mjs --only=<name>   run one guard (repeatable)
+//   node guards/run.mjs --json          machine-readable (CI / agents)
+//   node guards/run.mjs --list          list registered guards
+//
+// A guard is a file in this directory exporting:
+//
+//   export default {
+//     name: "my-invariant",
+//     description: "what it enforces, in one line",
+//     requires: ["SOME_ENV_VAR"],          // optional: skip (not fail) when absent
+//     async run() { return [/* violations */]; },
+//   }
+//
+// A violation: { file?, line?, message }. Empty array = pass.
+// Keep guards deterministic and read-only. Justified exceptions belong in an
+// in-code ALLOWLIST inside the guard, keyed, with a written reason per entry.
+//
+// Design goal: adding a new safety invariant is a single small file — easy
+// for engineers and for agents to extend. If a rule in STANDARD.md is
+// repeatedly missed, it belongs here.
+import { readdirSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const asJson = args.includes("--json");
+const list = args.includes("--list");
+const only = args.filter((a) => a.startsWith("--only=")).map((a) => a.slice(7));
+
+const guardFiles = readdirSync(here)
+  .filter(
+    (f) =>
+      f.endsWith(".mjs") && !f.startsWith("_") && f !== basename(fileURLToPath(import.meta.url)),
+  )
+  .sort();
+
+const guards = [];
+for (const file of guardFiles) {
+  const mod = await import(pathToFileURL(join(here, file)).href);
+  const guard = mod.default;
+  if (!guard?.name || typeof guard.run !== "function") {
+    console.error(`guards/${file} does not export a valid guard ({ name, description, run }).`);
+    process.exit(1);
+  }
+  guards.push({ ...guard, file });
+}
+
+if (list) {
+  for (const g of guards) console.log(`${g.name.padEnd(32)} ${g.description ?? ""}`);
+  process.exit(0);
+}
+
+const selected = only.length ? guards.filter((g) => only.includes(g.name)) : guards;
+if (only.length && selected.length !== only.length) {
+  const known = new Set(guards.map((g) => g.name));
+  for (const name of only.filter((n) => !known.has(n))) console.error(`Unknown guard: ${name}`);
+  process.exit(1);
+}
+
+const results = [];
+for (const guard of selected) {
+  const missing = (guard.requires ?? []).filter((envVar) => !process.env[envVar]);
+  if (missing.length) {
+    results.push({
+      name: guard.name,
+      status: "skipped",
+      reason: `missing env: ${missing.join(", ")}`,
+      violations: [],
+    });
+    continue;
+  }
+  try {
+    const violations = (await guard.run()) ?? [];
+    results.push({ name: guard.name, status: violations.length ? "fail" : "pass", violations });
+  } catch (error) {
+    results.push({
+      name: guard.name,
+      status: "fail",
+      violations: [{ message: `guard crashed: ${error?.message ?? error}` }],
+    });
+  }
+}
+
+const failed = results.filter((r) => r.status === "fail");
+
+if (asJson) {
+  console.log(JSON.stringify({ ok: failed.length === 0, results }, null, 2));
+} else {
+  for (const r of results) {
+    const mark = r.status === "pass" ? "✓" : r.status === "skipped" ? "—" : "✗";
+    console.log(`${mark} ${r.name}${r.status === "skipped" ? `  (skipped: ${r.reason})` : ""}`);
+    for (const v of r.violations) {
+      const where = v.file ? `  ${v.file}${v.line ? `:${v.line}` : ""}  ` : "  ";
+      console.log(`  ${where}${v.message}`);
+    }
+  }
+  const ran = results.filter((r) => r.status !== "skipped").length;
+  console.log(`\n${ran} guard${ran === 1 ? "" : "s"} ran, ${failed.length} failed.`);
+}
+
+process.exit(failed.length ? 1 : 0);

package/templates/guards/watchtower-locked.mjs

@@ -0,0 +1,66 @@
+// Generated by facility — https://github.com/theam/facility
+//
+// Structural drift in the watchtower must be visible. This guard requires the
+// three workflow files and their cron entries, and verifies that the canary
+// hash pinned in facility-crew.yml matches the canonical probe body in
+// .github/facility/watchtower/canary.mjs. It does not evaluate job conditions
+// or GitHub repository settings, so it cannot tell whether Actions or a
+// schedule is enabled or runnable.
+import { createHash } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import { readText } from "./_kit.mjs";
+
+export default {
+  name: "watchtower-locked",
+  description: "watchtower/canary cron entries exist and the canary hash stays in sync",
+  async run() {
+    const violations = [];
+
+    const scheduled = [
+      [".github/workflows/facility-watchtower.yml", 2],
+      [".github/workflows/facility-canary.yml", 1],
+      [".github/workflows/facility-security-sweep.yml", 1],
+    ];
+    for (const [file, minCrons] of scheduled) {
+      const text = readText(file);
+      if (!text) {
+        violations.push({ file, message: "missing required watchtower workflow" });
+        continue;
+      }
+      const crons = (text.match(/- cron:/g) ?? []).length;
+      if (crons < minCrons) {
+        violations.push({
+          file,
+          message: `expected at least ${minCrons} cron schedule(s), found ${crons}`,
+        });
+      }
+    }
+
+    const crew = readText(".github/workflows/facility-crew.yml");
+    if (!crew) {
+      violations.push({ file: ".github/workflows/facility-crew.yml", message: "missing" });
+      return violations;
+    }
+    try {
+      const { CANARY_PROBE_BODY } = await import(
+        pathToFileURL(".github/facility/watchtower/canary.mjs").href
+      );
+      const expected = createHash("sha256")
+        .update(CANARY_PROBE_BODY.replace(/\r/g, ""), "utf8")
+        .digest("hex");
+      if (!crew.includes(expected)) {
+        violations.push({
+          file: ".github/workflows/facility-crew.yml",
+          message: `canary hash out of sync — expected sha256 ${expected} (from canary.mjs CANARY_PROBE_BODY)`,
+        });
+      }
+    } catch {
+      violations.push({
+        file: ".github/facility/watchtower/canary.mjs",
+        message: "missing or unreadable — cannot verify the pinned canary hash",
+      });
+    }
+
+    return violations;
+  },
+};

package/templates/prompts/address-review.md

@@ -0,0 +1,14 @@
+# Review feedback agent operating contract
+
+Address the actionable review findings on the linked agent pull request. Read
+the accepted plan, complete review thread, current diff, repository standard,
+and failing checks before editing. Preserve contributor intent and do not make
+unrelated changes.
+
+For each thread, either implement the correction and prove it with the relevant
+checks, or reply with concrete evidence that the request is already satisfied
+or unsafe. When Facility owns execution, provide the existing PR branch and a
+Conventional Commit message in the runner-requested delivery manifest; Facility
+adds the signed commit to that exact branch. Never create another branch or pull
+request, approve or merge, force-push, weaken a guard, or modify the protected
+branch.