@makerx/yoke 0.11.0 → 0.13.0

package/README.md

@@ -23,7 +23,7 @@ yoke sync --user   # ~/.claude/skills
 
 - `/pr` raises a PR with a short What/Why/(How) description.
 - `/review [number]` reviews a PR with Claude and Codex, combines their findings and offers to post them. [Configure](src/features/review/README.md#settings).
-- `/review-ci` adds a workflow that reviews each PR in CI and helps set its variable and secret. [Details](src/features/review/README.md#ci).
+- `/review-ci` makes CI review each PR, adding a workflow or switching the repo's existing LLM review workflow over, and helps set its variable and secret. [Details](src/features/review/README.md#ci).
 
 ## CLI
 
@@ -31,6 +31,7 @@ yoke sync --user   # ~/.claude/skills
 yoke sync [--user] [--force]  # write yoke's skills
 yoke review [number]          # review a PR (used by /review)
 yoke review-ci                # add the CI review workflow (used by /review-ci)
+yoke review-gate <result>     # block merging until the PR's latest review succeeds (used by review.yml)
 yoke models                   # list each provider's models
 ```
 

package/dist/cli.js

@@ -7,7 +7,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@makerx/yoke",
-  version: "0.11.0",
+  version: "0.13.0",
   description: "Lean, user-invoked Claude Code skills for MakerX AI-assisted delivery, plus the CLI they call.",
   license: "MIT",
   author: "MakerX",
@@ -415,6 +415,45 @@ import { execFileSync as execFileSync2 } from "child_process";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
 import { dirname as dirname2, join as join3 } from "path";
 
+// src/features/review/shellQuote.ts
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+// src/features/review/ciEntra.ts
+var githubOidcIssuer = "https://token.actions.githubusercontent.com";
+var entraTokenExchangeAudience = "api://AzureADTokenExchange";
+function federatedCredential(repo, environment) {
+  return {
+    issuer: githubOidcIssuer,
+    audience: entraTokenExchangeAudience,
+    subject: environment ? `repo:${repo}:environment:${environment}` : `repo:${repo}:pull_request`
+  };
+}
+function federatedCredentialCommand(clientId, credential) {
+  const parameters = JSON.stringify({
+    name: "yoke-review-ci",
+    issuer: credential.issuer,
+    subject: credential.subject,
+    audiences: [credential.audience]
+  });
+  return `az ad app federated-credential create --id ${shellQuote(clientId)} --parameters ${shellQuote(parameters)}`;
+}
+function entraSetup({ clientId, environment }, repo) {
+  const credential = federatedCredential(repo, environment);
+  return [
+    "",
+    `Instead of an API key, the review signs in to Foundry as Entra app ${clientId}. So that the app trusts this repo's review runs, add a federated credential to it with:`,
+    `  issuer:   ${credential.issuer}`,
+    `  audience: ${credential.audience}`,
+    `  subject:  ${credential.subject}`,
+    "for example with:",
+    `  ${federatedCredentialCommand(clientId, credential)}`,
+    "and give the app the Cognitive Services User role on the Foundry resource.",
+    ...environment ? [`The job runs in the ${environment} environment; create it on the repo if it does not exist.`] : []
+  ];
+}
+
 // src/features/review/pr.ts
 import { execFile } from "child_process";
 import { join as join2 } from "path";
@@ -506,6 +545,9 @@ async function submitPendingReview(pr2, review, body, exec2 = run) {
 async function discardPendingReview(pr2, review, exec2 = run) {
   await exec2("gh", ["api", "--method", "DELETE", `${reviewsPath(pr2)}/${review.id}`]);
 }
+async function githubGet(path, exec2 = run) {
+  return JSON.parse(await exec2("gh", ["api", path]));
+}
 var github = {
   open: (pr2) => openPendingReview(pr2),
   add: (review, comment) => addReviewComment(review, comment),
@@ -629,6 +671,8 @@ var reviewWorkflowRef = "MakerXStudio/yoke/.github/workflows/review.yml@main";
 var callerWorkflowPath = join3(".github", "workflows", "review-pr.yml");
 var baseUrlVariable = "REVIEW_CI_BASE_URL";
 var apiKeySecret = "REVIEW_CI_API_KEY";
+var callerTriggerTypes = ["opened", "synchronize", "reopened", "ready_for_review"];
+var gateCheck = "review / gate";
 function workflowSecrets({ entra }) {
   return entra ? [] : [apiKeySecret];
 }
@@ -692,9 +736,10 @@ function renderCallerWorkflow(workflow) {
     "",
     "on:",
     "  pull_request:",
-    "    types: [opened, reopened, ready_for_review]",
+    `    types: [${callerTriggerTypes.join(", ")}]`,
     "",
     "permissions:",
+    "  actions: read",
     "  contents: read",
     "  pull-requests: write",
     ...workflow.entra ? ["  id-token: write"] : [],
@@ -709,9 +754,6 @@ function renderCallerWorkflow(workflow) {
     ""
   ].join("\n");
 }
-function shellQuote(value) {
-  return `'${value.replaceAll("'", `'\\''`)}'`;
-}
 function setupCommands(settings, workflow) {
   const baseUrl = settings[`${workflow.provider}.baseUrl`];
   return [
@@ -719,23 +761,20 @@ function setupCommands(settings, workflow) {
     ...workflowSecrets(workflow).map((secret2) => `gh secret set ${secret2}`)
   ];
 }
-var githubOidcIssuer = "https://token.actions.githubusercontent.com";
-var entraTokenExchangeAudience = "api://AzureADTokenExchange";
-function federatedCredential(repo, environment) {
-  return {
-    issuer: githubOidcIssuer,
-    audience: entraTokenExchangeAudience,
-    subject: environment ? `repo:${repo}:environment:${environment}` : `repo:${repo}:pull_request`
-  };
-}
-function federatedCredentialCommand(clientId, credential) {
-  const parameters = JSON.stringify({
-    name: "yoke-review-ci",
-    issuer: credential.issuer,
-    subject: credential.subject,
-    audiences: [credential.audience]
-  });
-  return `az ad app federated-credential create --id ${shellQuote(clientId)} --parameters ${shellQuote(parameters)}`;
+var gateRuleset = {
+  name: "yoke review",
+  target: "branch",
+  enforcement: "active",
+  conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+  rules: [
+    {
+      type: "required_status_checks",
+      parameters: { strict_required_status_checks_policy: false, required_status_checks: [{ context: gateCheck }] }
+    }
+  ]
+};
+function rulesetCommand() {
+  return `echo ${shellQuote(JSON.stringify(gateRuleset))} | gh api --method POST 'repos/{owner}/{repo}/rulesets' --input -`;
 }
 var unknownRepo = "<owner>/<repo>";
 function githubRepo(cwd = process.cwd()) {
@@ -756,44 +795,125 @@ function repoRoot(cwd = process.cwd()) {
     throw new ReviewError("Not in a git repository; run `yoke review-ci` from the repo to review.");
   }
 }
-function writeCallerWorkflow(root, content, force) {
+var editInPlaceMessage = [
+  `${callerWorkflowPath} already exists and differs from yoke's version, so it was left as it is.`,
+  "Edit it in place to run yoke's review, keeping its provider, models and names. `yoke review-ci --print` shows yoke's version without saving it."
+].join("\n");
+function writeCallerWorkflow(root, content) {
   const path = join3(root, callerWorkflowPath);
   if (existsSync2(path)) {
     if (readFileSync2(path, "utf8") === content) return "unchanged";
-    if (!force) throw new ReviewError(`${callerWorkflowPath} already exists and differs; pass --force to overwrite it.`);
+    throw new ReviewError(editInPlaceMessage);
   }
   mkdirSync2(dirname2(path), { recursive: true });
   writeFileSync2(path, content);
   return "wrote";
 }
-function entraSetup({ clientId, environment }, repo) {
-  const credential = federatedCredential(repo, environment);
+function reportHeading(outcome, workflow) {
+  if (outcome === "printed")
+    return [`yoke's version of ${callerWorkflowPath}, not saved to the repo:`, "", renderCallerWorkflow(workflow).trimEnd()];
+  if (outcome === "unchanged") return [`${callerWorkflowPath} already matches yoke's version; nothing changed.`];
+  return [`Added ${callerWorkflowPath}, which reviews each PR opened from this repo.`];
+}
+function variableAndSecretSetup(settings, workflow) {
+  const hasSecret = workflowSecrets(workflow).length > 0;
   return [
-    "",
-    `Instead of REVIEW_CI_API_KEY, the job signs in to Foundry as Entra app ${clientId} with its GitHub OIDC token. On that app, create a federated credential with:`,
-    `  issuer:   ${credential.issuer}`,
-    `  audience: ${credential.audience}`,
-    `  subject:  ${credential.subject}`,
-    "for example with:",
-    `  ${federatedCredentialCommand(clientId, credential)}`,
-    "and give the app the Cognitive Services User role on the Foundry resource.",
-    ...environment ? [`The job runs in the ${environment} environment; create it on the repo if it does not exist.`] : []
+    hasSecret ? `The review reads the model server's address from the repo variable ${baseUrlVariable} and its API key from the secret ${apiKeySecret}. Set them with:` : `The review reads the model server's address from the repo variable ${baseUrlVariable}. Set it with:`,
+    ...setupCommands(settings, workflow).map((command) => `  ${command}`),
+    ...hasSecret ? [`Skip the secret if ${apiKeySecret} is already set for your organisation.`] : []
   ];
 }
 function reviewCiReport(outcome, settings, workflow, repo) {
-  const action = outcome === "wrote" ? "wrote" : "kept";
-  const reads = [`variable ${baseUrlVariable}`, ...workflowSecrets(workflow).map((secret2) => `secret ${secret2}`)];
   return [
-    `${action} ${callerWorkflowPath}`,
+    ...reportHeading(outcome, workflow),
     "",
-    `The workflow reads ${reads.join(" and ")}. Set ${reads.length > 1 ? "them" : "it"} on the repo (or the org) with:`,
-    ...setupCommands(settings, workflow).map((command) => `  ${command}`),
+    ...variableAndSecretSetup(settings, workflow),
     ...workflow.entra ? entraSetup(workflow.entra, repo()) : [],
     "",
-    "Commit and push the workflow; each PR opened from this repo then gets a review."
+    outcome === "printed" ? "Once the repo's review workflow runs this review, commit and push it; each PR opened from this repo then gets a review." : `Commit and push ${callerWorkflowPath}; each PR opened from this repo then gets a review.`,
+    "",
+    `To block merging while the review fails, require the ${gateCheck} check on the default branch with:`,
+    `  ${rulesetCommand()}`,
+    "Run it only after this workflow is merged to the default branch, or pushes to open PRs get stuck waiting for a status."
   ].join("\n");
 }
 
+// src/features/review/gate.ts
+import { appendFileSync, readFileSync as readFileSync3 } from "fs";
+import { setTimeout } from "timers/promises";
+import { z as z2 } from "zod";
+var eventSchema = z2.object({
+  action: z2.string(),
+  pull_request: z2.object({
+    number: z2.number(),
+    head: z2.object({ ref: z2.string(), repo: z2.object({ full_name: z2.string() }).nullable() }),
+    user: z2.object({ type: z2.string() })
+  })
+});
+var runsSchema = z2.object({
+  workflow_runs: z2.array(z2.object({ id: z2.number(), run_number: z2.number(), pull_requests: z2.array(z2.object({ number: z2.number() })) }))
+});
+var jobsSchema = z2.object({ jobs: z2.array(z2.object({ name: z2.string(), status: z2.string(), conclusion: z2.string().nullable() })) });
+var pollInterval = 3e4;
+var rerunHint = "Mark the PR as draft, then ready for review, to run the review again.";
+var firstRunHint = "Mark the PR as ready for review (from draft if it is not one) to run it.";
+function verdict(conclusion, message) {
+  const pass = conclusion === "success";
+  return { pass, message: pass ? message : `${message} ${rerunHint}` };
+}
+function gateContext(env = process.env) {
+  const { GITHUB_REPOSITORY, GITHUB_RUN_ID, GITHUB_RUN_NUMBER, GITHUB_SERVER_URL, GITHUB_EVENT_PATH } = env;
+  if (!GITHUB_REPOSITORY || !GITHUB_RUN_ID || !GITHUB_RUN_NUMBER || !GITHUB_SERVER_URL || !GITHUB_EVENT_PATH) {
+    throw new ReviewError("yoke review-gate runs only in a GitHub Actions pull_request workflow");
+  }
+  const event = eventSchema.safeParse(JSON.parse(readFileSync3(GITHUB_EVENT_PATH, "utf8")));
+  if (!event.success) throw new ReviewError("yoke review-gate runs only on pull_request events");
+  return {
+    repo: GITHUB_REPOSITORY,
+    runId: GITHUB_RUN_ID,
+    runNumber: Number(GITHUB_RUN_NUMBER),
+    serverUrl: GITHUB_SERVER_URL,
+    event: event.data
+  };
+}
+async function earlierRuns({ repo, runId, runNumber, event }, deps) {
+  const { workflow_id } = z2.object({ workflow_id: z2.number() }).parse(await deps.get(`repos/${repo}/actions/runs/${runId}`));
+  const query = new URLSearchParams({ event: "pull_request", branch: event.pull_request.head.ref, per_page: "100" });
+  const { workflow_runs } = runsSchema.parse(await deps.get(`repos/${repo}/actions/workflows/${workflow_id}/runs?${query.toString()}`));
+  return workflow_runs.filter((run2) => run2.run_number < runNumber && run2.pull_requests.some((pr2) => pr2.number === event.pull_request.number)).toSorted((a, b) => b.run_number - a.run_number).map((run2) => run2.id);
+}
+async function settledReview(repo, run2, deps) {
+  for (; ; ) {
+    const { jobs } = jobsSchema.parse(await deps.get(`repos/${repo}/actions/runs/${run2}/jobs`));
+    const review = jobs.find((job) => job.name.endsWith(" / review"));
+    if (!review || review.conclusion === "skipped") return void 0;
+    if (review.status === "completed") return review.conclusion ?? "unknown";
+    deps.log(`Waiting for the review in run ${run2} to finish (${review.status})`);
+    await deps.sleep(pollInterval);
+  }
+}
+async function reviewGate(reviewResult, context, deps) {
+  if (reviewResult !== "skipped") return verdict(reviewResult, `The review on this event finished with ${reviewResult}.`);
+  const { pull_request } = context.event;
+  if (pull_request.head.repo?.full_name !== context.repo || pull_request.user.type === "Bot") {
+    return verdict("success", "No review runs for PRs from forks or bots.");
+  }
+  for (const run2 of await earlierRuns(context, deps)) {
+    const conclusion = await settledReview(context.repo, run2, deps);
+    const url = `${context.serverUrl}/${context.repo}/actions/runs/${run2}`;
+    if (conclusion) return verdict(conclusion, `The latest review for this PR, in run ${url}, finished with ${conclusion}.`);
+  }
+  return { pass: false, message: `No review has completed for this PR yet. ${firstRunHint}` };
+}
+async function runReviewGate(reviewResult, out, env = process.env) {
+  const deps = { get: (path) => githubGet(path), sleep: (ms) => setTimeout(ms), log: out };
+  const { pass, message } = await reviewGate(reviewResult, gateContext(env), deps);
+  out(pass ? message : `::error::${message}`);
+  if (env.GITHUB_STEP_SUMMARY) appendFileSync(env.GITHUB_STEP_SUMMARY, `${message}
+`);
+  return pass;
+}
+
 // src/features/review/comments.ts
 var markerPrefix = "<!-- yoke-review:";
 function slug(text2) {
@@ -935,7 +1055,8 @@ function selfReviewNote(diff) {
 This change adds or edits a workflow that calls \`MakerXStudio/yoke/.github/workflows/review.yml\`, the CI setup for this review. Review it like any other file, but these are yoke's deliberate design: do not raise them as findings, keep them in a consolidated review, or mention them in a summary.
 
 - Calling the workflow at \`@main\` rather than a tag or SHA.
-- The trigger types, including leaving out \`synchronize\`: a review is re-run by marking the PR as draft and then ready for review.
+- The trigger types, including \`synchronize\`: pushes run only the \`review / gate\` job, and a review is re-run by marking the PR as draft and then ready for review.
+- The \`actions: read\` permission: the gate reads earlier runs of the workflow to find the PR's latest review.
 - Draft PRs being reviewed twice: the reusable workflow already skips drafts.
 
 Real defects in it are still findings, such as:
@@ -1294,7 +1415,7 @@ async function listModels(settings, fetchModels = fetch) {
 }
 
 // src/features/review/review.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync4, mkdtempSync, readFileSync as readFileSync7, rmSync as rmSync2, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, mkdtempSync, readFileSync as readFileSync8, rmSync as rmSync2, writeFileSync as writeFileSync7 } from "fs";
 import { homedir as homedir2, tmpdir } from "os";
 import { join as join8 } from "path";
 
@@ -1364,10 +1485,10 @@ async function withEntraToken(settings, { env, fetch: fetchFn = fetch, mask }) {
 
 // src/features/review/harness.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
 
 // src/features/review/usage.ts
-import { appendFileSync } from "fs";
+import { appendFileSync as appendFileSync2 } from "fs";
 var fields2 = ["input", "output", "cacheRead", "cacheWrite"];
 var rows = [
   ["reviewer1", "Reviewer 1"],
@@ -1430,7 +1551,7 @@ function writeJobSummary(summary, usage, log, env = process.env) {
   const path = env.GITHUB_STEP_SUMMARY;
   if (!path) return;
   try {
-    appendFileSync(path, `${jobSummary(summary, usage)}
+    appendFileSync2(path, `${jobSummary(summary, usage)}
 `);
     log("wrote the review summary and token usage to the job summary");
   } catch (error) {
@@ -1556,7 +1677,7 @@ function exitError(harness, code, output) {
   return [`${harness} exited with code ${code ?? "unknown"}`, ...detail ? [detail] : []].join("\n");
 }
 function hasReview(path) {
-  return existsSync3(path) && readFileSync3(path, "utf8").trim().length > 0;
+  return existsSync3(path) && readFileSync4(path, "utf8").trim().length > 0;
 }
 var runHarness = (run2) => new Promise((resolve) => {
   const shell = process.platform === "win32";
@@ -1610,11 +1731,11 @@ var runHarness = (run2) => new Promise((resolve) => {
 import { execFile as execFile2 } from "child_process";
 
 // src/features/review/run.ts
-import { existsSync as existsSync6, readFileSync as readFileSync6, rmSync, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync7, rmSync, writeFileSync as writeFileSync6 } from "fs";
 import { join as join6 } from "path";
 
 // src/features/review/cachedSlots.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
 import { join as join4 } from "path";
 function slotsPath(reviewDir) {
   return join4(reviewDir, "slots.json");
@@ -1625,7 +1746,7 @@ function isCachedSlots(value) {
 function readCachedSlots(reviewDir) {
   const path = slotsPath(reviewDir);
   if (!existsSync4(path)) return {};
-  const parsed = JSON.parse(readFileSync4(path, "utf8"));
+  const parsed = JSON.parse(readFileSync5(path, "utf8"));
   return isCachedSlots(parsed) ? parsed : {};
 }
 function cachedSlot(reviewDir, step) {
@@ -1779,7 +1900,7 @@ ${files.join("\n")}
 }
 
 // src/features/review/usedModels.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "fs";
 import { join as join5 } from "path";
 var repoUrl = "https://github.com/MakerXStudio/yoke";
 function modelsPath(reviewDir) {
@@ -1791,7 +1912,7 @@ function isUsedModels(value) {
 function readUsedModels(reviewDir) {
   const path = modelsPath(reviewDir);
   if (!existsSync5(path)) return {};
-  const parsed = JSON.parse(readFileSync5(path, "utf8"));
+  const parsed = JSON.parse(readFileSync6(path, "utf8"));
   return isUsedModels(parsed) ? parsed : {};
 }
 function recordUsedModel(reviewDir, step, harness, model) {
@@ -1862,7 +1983,7 @@ async function runStep({ name, label, slot, ...step }, context) {
 }
 function hasOutput({ name, slot, outputPath }, context) {
   if (cachedSlot(context.reviewDir, name) !== describeSlot(slot)) return false;
-  return existsSync6(outputPath) && readFileSync6(outputPath, "utf8").trim().length > 0;
+  return existsSync6(outputPath) && readFileSync7(outputPath, "utf8").trim().length > 0;
 }
 async function runOrReuse(step, context) {
   if (!hasOutput(step, context)) return { ok: await runStep(step, context), ran: true };
@@ -1889,7 +2010,7 @@ function synthesisResult(markdown) {
 function rawReviews(succeeded, context) {
   const report = succeeded.map((reviewer) => `# ${reviewerLabel(reviewer, context)} review
 
-${readFileSync6(reviewPath(context, reviewer), "utf8").trim()}`).join("\n\n");
+${readFileSync7(reviewPath(context, reviewer), "utf8").trim()}`).join("\n\n");
   return { report, synthesis: null, markdown: null };
 }
 function synthesisSlot(succeeded, context) {
@@ -1906,7 +2027,7 @@ async function synthesise(requestPath, succeeded, reviewersRan, context) {
   }));
   const prompt = buildSynthesisPrompt(requestPath, files);
   if ((await runOrReuse({ name: "synthesis", label: `synthesis (${describeSlot(slot)})`, slot, prompt, outputPath }, context)).ok)
-    return synthesisResult(readFileSync6(outputPath, "utf8"));
+    return synthesisResult(readFileSync7(outputPath, "utf8"));
   if (context.strict) throw new ReviewFailure("synthesis failed", "The synthesis failed; nothing to post.");
   context.log("showing the raw reviews instead");
   return rawReviews(succeeded, context);
@@ -2014,21 +2135,21 @@ async function assertViable(slots2, check = checks) {
 }
 
 // src/features/review/reviewLog.ts
-import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync3 } from "fs";
+import { appendFileSync as appendFileSync3, mkdirSync as mkdirSync3 } from "fs";
 import { join as join7 } from "path";
 function reviewLog(command = process.argv.slice(2), now = () => /* @__PURE__ */ new Date()) {
   let path;
   let buffered = [];
   return {
     append: (line) => {
-      if (path) appendFileSync2(path, `${line}
+      if (path) appendFileSync3(path, `${line}
 `);
       else buffered.push(line);
     },
     attach: (reviewDir) => {
       mkdirSync3(reviewDir, { recursive: true });
       path = join7(reviewDir, "review.log");
-      appendFileSync2(path, `${["", `=== ${now().toISOString()} ===`, `$ yoke ${command.join(" ")}`, ...buffered].join("\n")}
+      appendFileSync3(path, `${["", `=== ${now().toISOString()} ===`, `$ yoke ${command.join(" ")}`, ...buffered].join("\n")}
 `);
       buffered = [];
     }
@@ -2087,7 +2208,7 @@ async function reviewAtHead(pr2, reviewDir, request, slots2, ui, strict) {
 }
 function savedReview(path, post) {
   if (!post || !existsSync7(path)) return null;
-  return parseSynthesis(readFileSync7(path, "utf8"));
+  return parseSynthesis(readFileSync8(path, "utf8"));
 }
 function saveReview(path, markdown) {
   if (markdown) writeFileSync7(path, markdown);
@@ -2149,7 +2270,7 @@ async function reviewPr(number, settings, { post, force }, io) {
 }
 
 // src/features/sync/sync.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync8, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir3 } from "os";
 import { join as join9 } from "path";
 
@@ -2185,23 +2306,40 @@ If \`yoke\` is not found, run \`npm i -g @makerx/yoke\` and retry.
 // src/features/review/ciSkill.ts
 var reviewCiSkill = {
   name: "review-ci",
-  description: "Add yoke's adversarial PR review workflow to this repo and set the variable and secret it needs.",
+  description: "Add yoke's adversarial PR review workflow to this repo, or switch its existing LLM review workflow to it, and set the variable and secret it needs.",
   disableModelInvocation: true,
   userLevel: true,
   body: `
-Run \`yoke review-ci $ARGUMENTS\`. If it reports that a model is required, run \`yoke models\` to list what the provider serves, ask the user which model each reviewer should run, and rerun with \`--reviewer-1-model\` and \`--reviewer-2-model\`. If it reports the workflow already exists and differs, show the user the difference and ask before rerunning with \`--force\`.
+Read \`.github/workflows/\`, recent review runs (\`gh run list\`, \`gh run view --log\`) and \`yoke config list\` before asking anything. Only ask what they don't answer, in plain words about the repo, not flags.
 
-With \`--provider foundry\`, if the Foundry resource has local (API key) auth disabled or the user prefers Entra, rerun with \`--azure-client-id\` and \`--azure-tenant-id\` of the Entra app the job signs in as, plus \`--environment\` if the job should run in a GitHub environment. Ask the user for these values; don't guess them.
+## Workflow
 
-Then set the variable and secret it printed. Run \`gh variable list\` and \`gh secret list\` first; if one is missing, ask whether it is already set at the org level before setting it on the repo.
-- \`REVIEW_CI_BASE_URL\` is a variable, not a secret: confirm the URL with the user and run the printed \`gh variable set\` command.
-- \`REVIEW_CI_API_KEY\` must never enter this conversation: ask the user to run \`gh secret set REVIEW_CI_API_KEY\` in their own terminal, outside this session, and paste the key at its prompt. With Entra auth there is no API key to set.
+A workflow is an LLM review if it has a model review PRs, whatever tool it uses.
 
-With Entra auth, show the user the federated credential it printed (issuer, audience, subject) and the \`az ad app federated-credential create\` command, and ask whether to run it or whether they will add the credential in the Azure portal. The app also needs the Cognitive Services User role on the Foundry resource, and the environment, if given, must exist on the repo.
+- **None:** run \`yoke review-ci $ARGUMENTS\`.
+- **One, not yoke's:** run \`yoke review-ci $ARGUMENTS --print\` with its provider and models, then edit that file in place to run yoke's review. Keep its name, triggers, provider, models, base URL, variable and secret names.
+- **Already yoke's** (calls MakerXStudio/yoke's \`review.yml\`, or \`./.github/workflows/review.yml\` in yoke itself): compare with \`--print\` and add only what is missing.
 
-Finish by running \`gh variable list\` and \`gh secret list\` and telling the user to commit and push the workflow file.
+Never ask whether to overwrite a workflow. If \`review-pr.yml\` exists and differs, edit it in place.
 
-If \`yoke\` is not found, run \`npm i -g @makerx/yoke\` and retry.
+The \`review / gate\` merge gate needs the \`synchronize\` trigger and \`actions: read\` permission from \`--print\`; add them to an edited workflow if missing.
+
+If no workflow or setting names the models, ask which model each reviewer runs. For LiteLLM, offer \`yoke models\`. For Foundry, ask for deployment names.
+
+For Foundry with Entra, reuse the client and tenant IDs from the existing workflow; ask only if none is there.
+
+## Variable and secret
+
+Never ask whether they are set for the organisation, and don't query org settings.
+
+- \`REVIEW_CI_BASE_URL\` not in \`gh variable list\`: set it on the repo with the base URL from the workflow or the printed command.
+- \`REVIEW_CI_API_KEY\` not in \`gh secret list\`: tell the user to run \`gh secret set REVIEW_CI_API_KEY\` in their own terminal, and to skip it if the secret is already set for the organisation. Never take the key in this conversation.
+
+With Entra, check \`az ad app federated-credential list --id <client-id>\` and show the printed create command if the credential is missing.
+
+Finish with what changed and what's left: commit and push the workflow, then, only once it is merged to the default branch, run the printed \`gh api\` ruleset command requiring \`review / gate\`. Don't run it before then.
+
+If \`yoke\` is not found, run \`npm i -g @makerx/yoke\`.
 `
 };
 
@@ -2225,7 +2363,7 @@ function skillsRoot(user, cwd = process.cwd(), home = homedir3()) {
   return join9(user ? home : cwd, ".claude", "skills");
 }
 function isOwnedByUser(skillFile) {
-  return existsSync8(skillFile) && !readFileSync8(skillFile, "utf8").includes(ownerMarker);
+  return existsSync8(skillFile) && !readFileSync9(skillFile, "utf8").includes(ownerMarker);
 }
 function syncSkills(destination, userDestination, force = false, skills = bundledSkills) {
   const result = { written: [], skipped: [] };
@@ -2310,14 +2448,14 @@ addSettingOptions(
   ).option("--provider <provider>", "litellm or foundry; every slot uses it in CI. Default: review.reviewer1.provider, else litellm").option(
     "--azure-client-id <id>",
     "Entra app (client) ID to sign in to Foundry with GitHub OIDC instead of an API key; needs --provider foundry"
-  ).option("--azure-tenant-id <id>", "Entra tenant ID of that app").option("--environment <name>", "GitHub environment the review job runs in, matching the app's federated credential subject").option("--force", `overwrite an existing ${callerWorkflowPath} that differs`),
+  ).option("--azure-tenant-id <id>", "Entra tenant ID of that app").option("--environment <name>", "GitHub environment the review job runs in, matching the app's federated credential subject").option("--print", `print the workflow and setup commands without writing ${callerWorkflowPath}`),
   ciKeys
 ).addHelpText("after", settingsHelp).action((options) => {
   try {
     const settings = resolveSettings(flagSettings(options, ciKeys), process.env, readUserConfig(userConfigPath()));
     const workflow = callerWorkflow(settings, options.provider, options);
     const root = repoRoot();
-    const outcome = writeCallerWorkflow(root, renderCallerWorkflow(workflow), options.force ?? false);
+    const outcome = options.print ? "printed" : writeCallerWorkflow(root, renderCallerWorkflow(workflow));
     console.log(reviewCiReport(outcome, settings, workflow, () => githubRepo(root)));
   } catch (error) {
     if (!(error instanceof ReviewError || error instanceof ConfigError)) throw error;
@@ -2325,6 +2463,15 @@ addSettingOptions(
     process.exitCode = 1;
   }
 });
+program.command("review-gate").description("Block merging until the latest review that ran for the PR succeeds; fork and bot PRs pass. Used by review.yml's gate job").argument("<result>", "result of the review job on this event: success, failure, cancelled or skipped").action(async (result) => {
+  try {
+    if (!await runReviewGate(result, console.log)) process.exitCode = 1;
+  } catch (error) {
+    if (!(error instanceof ReviewError)) throw error;
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+});
 addSettingOptions(
   program.command("models").description("List the models each configured provider serves, for review.*.provider and review.*.model"),
   providerKeys

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makerx/yoke",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Lean, user-invoked Claude Code skills for MakerX AI-assisted delivery, plus the CLI they call.",
   "license": "MIT",
   "author": "MakerX",