@rtorcato/repo-tooling 3.19.2 → 3.21.0

package/README.md

@@ -234,8 +234,8 @@ MIT — see [LICENSE](LICENSE).
 Any agent that supports the [`skills`](https://www.npmjs.com/package/skills) CLI can install this repo's skills straight from GitHub — no clone, no package install:
 
 ```bash
-npx skills add https://github.com/rtorcato/repo-tooling --skill ai-issue-loop
-npx skills add https://github.com/rtorcato/repo-tooling --skill npm-publish
-npx skills add https://github.com/rtorcato/repo-tooling --skill repo-tooling
+npx skills add https://github.com/rtorcato/repo-tooling --skill 'ai-issue-loop'
+npx skills add https://github.com/rtorcato/repo-tooling --skill 'npm-publish'
+npx skills add https://github.com/rtorcato/repo-tooling --skill 'repo-tooling'
 ```
 <!-- js-tooling:skills:end -->

package/dist/base/fixers.js

@@ -26,7 +26,7 @@ import { classifyCopiedAssets } from '../cli/utils/copied-assets.js';
 import { copyPreset } from '../cli/utils/copy-preset.js';
 import { detectLanguage } from '../cli/utils/detect-language.js';
 import { resolveLanguageModule } from '../languages/registry.js';
-import { applyGithubSettings } from './github-settings.js';
+import { applyGithubSettings, applyReleaseEnvironment, RELEASE_ENV_CHECK, RELEASE_GATE_CHECK, } from './github-settings.js';
 import { applyLoopLabels } from './labels.js';
 import { closeCompletedMilestones } from './milestones.js';
 /**
@@ -210,6 +210,26 @@ export const BASE_FIXERS = [
             return { filesWritten: await applyGithubSettings(targetDir) };
         },
     },
+    {
+        target: 'release-environment',
+        description: 'Create the `release` environment (authenticated user as required reviewer) and wire `environment: release` into the publishing job — the gate between merging and publishing (#429)',
+        appliesTo: [RELEASE_GATE_CHECK, RELEASE_ENV_CHECK],
+        outputs: [
+            'GitHub `release` environment (remote, via gh api)',
+            '.github/workflows/<the publishing workflow>',
+        ],
+        // safe-add for the same shadow-run reason as github-settings, and
+        // explicitOnly because arming the gate changes what a merge *does*: the
+        // next release run sits `waiting` for an approval instead of publishing.
+        // That is the point, but it must be a chosen rollout per repo, not a side
+        // effect of a bare `fix`.
+        riskLevel: 'safe-add',
+        explicitOnly: true,
+        canFixDrift: true,
+        async run({ targetDir }) {
+            return { filesWritten: await applyReleaseEnvironment(targetDir) };
+        },
+    },
     {
         target: 'milestones',
         description: 'Close 100%-complete open milestones on GitHub via gh api (mutates the remote repo, not files). Never deletes or creates one',

package/dist/base/github-settings.js

@@ -51,8 +51,8 @@ export const GITHUB_STANDARD = {
     requiredContexts: ['lint', 'typecheck', 'build', 'test'],
 };
 const CODE_SCANNING_CHECK = 'Code-scanning gate';
-const RELEASE_GATE_CHECK = 'Release gate';
-const RELEASE_ENV_CHECK = 'Release environment';
+export const RELEASE_GATE_CHECK = 'Release gate';
+export const RELEASE_ENV_CHECK = 'Release environment';
 const CHECK_NAMES = [
     'Branch protection',
     'Merge settings',
@@ -438,7 +438,7 @@ const RELEASE_ENVIRONMENT = 'release';
  * `semantic-release` counts on its own — the shipped preset publishes with it.
  */
 const PUBLISH_COMMAND = /semantic-release|changesets\/action|(?:npm|pnpm|yarn)\s+publish/;
-const GATE_HINT = 'Create a `release` environment with required reviewers (Settings → Environments) and add `environment: release` to the publishing job — a merge to the default branch then leaves the run `waiting` instead of publishing';
+const GATE_HINT = 'Run `npx @rtorcato/repo-tooling fix release-environment` to create the `release` environment with required reviewers (you) and add `environment: release` to the publishing job — a merge to the default branch then leaves the run `waiting` instead of publishing';
 const ENV_HINT = 'Add `environment: release` to the publishing job, or delete the environment — whichever was meant. An environment nothing references still lists under Settings → Environments as though it gates something';
 const unquote = (s) => s.replace(/^['"]|['"]$/g, '');
 /**
@@ -604,9 +604,9 @@ async function readEnvironments(gh, nwo) {
  * environment" is the gate check's; "no `environment:` but a `release`
  * environment exists" is the environment check's, and the gate check defers.
  *
- * A repo that publishes nothing is `ok` — not applicable, not drift. There is
- * no fixer: creating the environment needs a `required_reviewers` list only a
- * human can supply, so both hints describe the manual step.
+ * A repo that publishes nothing is `ok` — not applicable, not drift. The fixer
+ * is `fix release-environment` (`applyReleaseEnvironment` below), which uses
+ * the authenticated user as the required reviewer.
  */
 async function checkReleaseGate(gh, nwo, dir) {
     const publish = (await isPrivatePackage(dir)) ? null : await findPublishJob(dir);
@@ -836,3 +836,129 @@ export async function applyGithubSettings(dir, exec) {
         console.error(chalk.gray('   already configured — nothing to apply'));
     return applied;
 }
+// --- Release environment scaffolding (#429) --------------------------------
+/**
+ * Insert `environment: <env>` as the first key of job `jobId`. Line-based, same
+ * reasoning as `workflowJobs`: this package ships no YAML dependency, and jobs
+ * sit one indent level under `jobs:` with their keys one level below. Returns
+ * null when the job cannot be found. The caller only reaches this when
+ * `jobEnvironment()` was null, so it never doubles an existing key.
+ */
+export function addJobEnvironment(yaml, jobId, env) {
+    const lines = yaml.split('\n');
+    const start = lines.findIndex((l) => /^jobs:\s*$/.test(l));
+    if (start === -1)
+        return null;
+    const indentOf = (l) => l.length - l.trimStart().length;
+    // The job headers' indent — from the first real line after `jobs:`, exactly
+    // as workflowJobs derives it, so the two agree on what counts as a header.
+    let jobIndent = -1;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        if (indentOf(line) === 0)
+            return null;
+        jobIndent = indentOf(line);
+        break;
+    }
+    if (jobIndent === -1)
+        return null;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        if (indentOf(line) === 0)
+            return null; // left the jobs block
+        if (indentOf(line) !== jobIndent || !line.trim().startsWith(`${jobId}:`))
+            continue;
+        // Key indent = the job's first real line, so the insert matches whatever
+        // indentation the file already uses.
+        for (let j = i + 1; j < lines.length; j++) {
+            const next = lines[j] ?? '';
+            if (next.trim() === '' || next.trimStart().startsWith('#'))
+                continue;
+            lines.splice(j, 0, `${' '.repeat(indentOf(next))}environment: ${env}`);
+            return lines.join('\n');
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Scaffold the release environment gate — the fixer half of #429 (the checks
+ * shipped with #449). Two writes, each skipped when already in place:
+ *
+ * 1. `PUT /repos/{nwo}/environments/release` with the **authenticated user** as
+ *    the required reviewer. On a solo-maintained repo they are the only human
+ *    there is; add or swap reviewers afterwards under Settings → Environments.
+ *    An environment that already carries a `required_reviewers` rule is never
+ *    touched — whoever set it up made a richer decision than this default.
+ * 2. `environment: release` on the publishing job, so the merge leaves the run
+ *    `waiting` instead of publishing.
+ *
+ * A job already behind some *other* environment is a warning, not a rename —
+ * this fixer scaffolds the standard, it does not migrate a custom setup.
+ */
+export async function applyReleaseEnvironment(dir, exec) {
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        console.error(chalk.gray('   skipped — not a git repository'));
+        return [];
+    }
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const probe = await probeRepo(gh);
+    if ('skip' in probe) {
+        console.error(chalk.gray(`   skipped — ${probe.skip}`));
+        return [];
+    }
+    const nwo = probe.info.nwo;
+    const publish = (await isPrivatePackage(dir)) ? null : await findPublishJob(dir);
+    if (publish === 'skip') {
+        console.error(chalk.yellow('   skipped — could not read .github/workflows'));
+        return [];
+    }
+    if (!publish) {
+        console.error(chalk.gray('   skipped — no workflow job publishes to a registry'));
+        return [];
+    }
+    if (publish.environment !== null && publish.environment !== RELEASE_ENVIRONMENT) {
+        console.error(chalk.yellow(`   skipped — ${publish.file} \`${publish.job}\` already runs behind \`${publish.environment}\`; not renaming it`));
+        return [];
+    }
+    const envs = await readEnvironments(gh, nwo);
+    if (envs === 'skip') {
+        console.error(chalk.yellow('   skipped — could not read environments'));
+        return [];
+    }
+    const applied = [];
+    if (envs.get(RELEASE_ENVIRONMENT) !== true) {
+        const user = await gh(['api', 'user', '--jq', '.id']);
+        const id = user.ok ? Number.parseInt(user.stdout.trim(), 10) : Number.NaN;
+        if (Number.isNaN(id)) {
+            console.error(chalk.yellow(`   could not resolve the authenticated user for required_reviewers: ${user.stderr.trim() || 'gh error'}`));
+            return applied;
+        }
+        const label = `\`${RELEASE_ENVIRONMENT}\` environment with the authenticated user as required reviewer`;
+        const r = await gh(['api', '-X', 'PUT', `repos/${nwo}/environments/${RELEASE_ENVIRONMENT}`, '--input', '-'], JSON.stringify({ reviewers: [{ type: 'User', id }] }));
+        if (r.ok)
+            applied.push(label);
+        else {
+            console.error(chalk.yellow(`   could not apply ${label}: ${r.stderr.trim() || 'gh error'}`));
+            return applied;
+        }
+    }
+    if (publish.environment === null) {
+        const file = path.join(dir, '.github', 'workflows', publish.file);
+        const updated = addJobEnvironment(await fs.readFile(file, 'utf-8'), publish.job, RELEASE_ENVIRONMENT);
+        if (updated === null) {
+            console.error(chalk.yellow(`   could not add \`environment:\` to ${publish.file} \`${publish.job}\` — add it by hand`));
+        }
+        else {
+            await fs.writeFile(file, updated);
+            applied.push(`environment: ${RELEASE_ENVIRONMENT} on ${publish.file} \`${publish.job}\``);
+        }
+    }
+    if (applied.length === 0)
+        console.error(chalk.gray('   already configured — nothing to apply'));
+    return applied;
+}

package/dist/cli/generators/claude-skills.js

@@ -9,6 +9,7 @@ import os from 'node:os';
 import path from 'node:path';
 import fs from 'fs-extra';
 import { getPackageRoot } from '../utils/copy-preset.js';
+import { shellQuote } from '../utils/shell.js';
 /** Skills this package owns the content of and keeps up to date. */
 export const SHIPPED_SKILL = 'ai-issue-loop';
 /**
@@ -129,15 +130,6 @@ export async function readShippedSkill(name = SHIPPED_SKILL) {
     const pkg = await fs.readJson(path.join(root, 'package.json'));
     return { content, version: String(pkg.version), file };
 }
-/**
- * POSIX single-quote escaping — the only form correct for arbitrary bytes.
- * Inside single quotes every character is literal, so `'` is the sole one
- * needing care: end the quote, escape it, start a new one. Double quotes are
- * not a substitute; `$(...)`, backticks and `\` all still expand inside them.
- */
-function shellQuote(value) {
-    return `'${value.replaceAll("'", "'\\''")}'`;
-}
 /**
  * The command a human runs to see what their fork changed, before deciding
  * whether to take the shipped copy. One builder, because `doctor` and `fix`

package/dist/cli/generators/skills-install.js

@@ -3,6 +3,7 @@
 // repo (its skills dir + package.json `repository`) so it works for any consumer.
 import path from 'node:path';
 import fs from 'fs-extra';
+import { shellQuote } from '../utils/shell.js';
 import { upsertBlock } from './agent-rules.js';
 import { parseRepository } from './badges.js';
 export const SKILLS_DOCS_START = '<!-- js-tooling:skills:start -->';
@@ -25,12 +26,18 @@ export async function findSkills(targetDir) {
 /**
  * Build the README section body (inner content, no delimiters) listing one
  * `npx skills add` command per skill. Returns '' when there are no skills.
+ *
+ * The skill name is a directory basename — `findSkills` takes whatever is under
+ * `skills/`, and nothing constrains it — so it is quoted (#498). `owner`/`repo`
+ * are not: `parseRepository` already matches them against `[\w.-]+`. Unlike the
+ * doctor hint of #493 this line is committed to a README and rendered on GitHub
+ * and npm, where it gets pasted by people who did not create the directory.
  */
 export function buildSkillsInstallBody(owner, repo, skills) {
     if (skills.length === 0)
         return '';
     const commands = skills
-        .map((s) => `npx skills add https://github.com/${owner}/${repo} --skill ${s}`)
+        .map((s) => `npx skills add https://github.com/${owner}/${repo} --skill ${shellQuote(s)}`)
         .join('\n');
     const plural = skills.length > 1 ? 's' : '';
     return [
@@ -38,11 +45,21 @@ export function buildSkillsInstallBody(owner, repo, skills) {
         '',
         `Any agent that supports the [\`skills\`](https://www.npmjs.com/package/skills) CLI can install this repo's skill${plural} straight from GitHub — no clone, no package install:`,
         '',
-        '```bash',
+        `${fenceFor(commands)}bash`,
         commands,
-        '```',
+        fenceFor(commands),
     ].join('\n');
 }
+/**
+ * A fence longer than any backtick run in the content, per CommonMark. Quoting
+ * cannot help here: a name may contain backticks *and* a newline, which puts
+ * arbitrary text at the start of a line inside the block and would otherwise
+ * close it early, mangling the rendered README.
+ */
+function fenceFor(content) {
+    const longestRun = Math.max(0, ...[...content.matchAll(/`+/g)].map((m) => m[0].length));
+    return '`'.repeat(Math.max(3, longestRun + 1));
+}
 /**
  * Add or refresh a "Install the skill" block in README.md. No-op (returns null)
  * when the repo ships no skills or package.json has no GitHub `repository` to

package/dist/cli/utils/shell.js

@@ -0,0 +1,13 @@
+/**
+ * POSIX single-quote escaping — the only form correct for arbitrary bytes.
+ * Inside single quotes every character is literal, so `'` is the sole one
+ * needing care: end the quote, escape it, start a new one. Double quotes are
+ * not a substitute; `$(...)`, backticks and `\` all still expand inside them.
+ *
+ * One escaper for every generator that emits a copy-pasteable command line
+ * (#498) — two independently-built ones drift, which is the argument #492 made
+ * for a single `skillDiffCommand`.
+ */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.19.2",
+	"version": "3.21.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [

package/skills/ai-issue-loop/SKILL.md

@@ -200,6 +200,44 @@ pass.** A session can be pinned to a worktree, so the orchestrator can find itse
 inside one it did not choose. `--git-common-dir` resolves to the main checkout's
 `.git` from anywhere, including a worktree, so `ROOT` is correct either way.
 
+**Check the main checkout is not bare before anything else uses `ROOT`.** It has gone
+`core.bare = true` on its own, repeatedly — four times in one session, some occurrences
+immediately after a `worktree remove` and some with nothing removed at all. The trigger
+is unidentified, so this is detection and repair only:
+
+```bash
+if [ "$(git -C "$ROOT" rev-parse --is-inside-work-tree 2>/dev/null)" != true ] && [ -d "$ROOT/.git" ]; then
+  echo "⚠ main checkout bare at $(date -u +%FT%TZ) — repairing"
+  git -C "$ROOT" config core.bare false || {
+    echo "⚠ repair FAILED — main checkout still bare"; exit 1; }
+fi
+```
+
+**It corrupts commits — this is not a cosmetic error message.** A bare main checkout
+wipes a worktree's index while every file sits untouched on disk, and the next commit
+faithfully records the whole repository as deleted. PR #500 died that way: a diff of
+`0 additions, 67703 deletions` across 359 files, not one of which had moved.
+
+**Test stdout, not the exit code.** `rev-parse --is-inside-work-tree` exits `0` either
+way and only *prints* the answer, so an exit-code probe is dead code. Verified on git
+2.55.0:
+
+| repo state | `--is-inside-work-tree` | `.git` |
+|---|---|---|
+| healthy checkout | `true`, exit 0 | directory |
+| **wrongly bare** | `false`, **exit 0** | directory |
+| genuinely bare | `false`, exit 0 | absent |
+| linked worktree | `true`, exit 0 | file |
+
+**`.git` must be a directory before repairing.** A genuinely bare repo prints `false`
+too, and nothing else separates the two — this skill ships to users' `~/.claude/skills/`,
+where "repairing" someone's real bare clone is the damage rather than the fix. The same
+check skips a linked worktree, whose `.git` is a file.
+
+**Fail loudly.** The repair writes `$ROOT/.git/config`, which a restrictive sandbox
+refuses with `error: could not lock config file .git/config: Operation not permitted` —
+observed. Aborting beats reporting a healthy repo while it stays broken.
+
 Never use a relative path like `ai-*`. From inside a worktree it matches nothing, and
 the failure is **silent**: Pass 2 concludes there is nothing to clean, every worktree
 survives, `ai-wip` is never cleared, and slots leak until the loop reports `idle`
@@ -473,6 +511,23 @@ and say in the comment that you re-queued it, that you deviated, and why. Re-add
 issue out of the queue silently, which is the worse failure. `ai-blocked` means *a
 human must look*; do not spend it on a claim you already understand.
 
+**Then re-check `core.bare`** — the same probe as Pass 0, against the same `ROOT`:
+
+```bash
+if [ "$(git -C "$ROOT" rev-parse --is-inside-work-tree 2>/dev/null)" != true ] && [ -d "$ROOT/.git" ]; then
+  echo "⚠ main checkout bare at $(date -u +%FT%TZ) — repairing"
+  git -C "$ROOT" config core.bare false || {
+    echo "⚠ repair FAILED — main checkout still bare"; exit 1; }
+fi
+```
+
+This is the last pass that *removes* worktrees, not the tick's last touch on the main
+checkout — Pass 4 still runs `git -C "$ROOT" worktree add` against it. That is exactly
+why the re-check belongs here: it catches a flip after this pass's removals and before
+Pass 4 branches every new worktree off a broken `ROOT`. Keep the timestamp in both log
+lines; which pass emitted one, and when, is the only instrumentation likely to pin the
+trigger down.
+
 ### Pass 3 — review
 
 **PRs labelled `ai-review`.** For each, spawn *in background* only the reviewers
@@ -482,6 +537,66 @@ whose pass-label is missing — `code-reviewer` if no `ai-ok-code`,
 carries `ai-reviewing-sec`. Both can run concurrently; launch them in a single
 message.
 
+**Before spawning either, check whether it already posted.** A missing verdict
+label does not mean the review is missing: on #497 both reviewers posted
+complete reviews and then went idle, labelling nothing. Every review comment
+carries a hidden verdict marker, so read that back instead of re-spawning over a
+review that already exists — `<ARM>` is `code` or `sec`:
+
+```bash
+VERDICT=$(gh api "repos/$OWNER_REPO/pulls/<N>/reviews" --paginate --slurp \
+  | jq -r '[add[]
+            | select(.author_association=="OWNER" or .author_association=="MEMBER" or .author_association=="COLLABORATOR")
+            | (.body // "")
+            | capture("<!-- ai-issue-loop:verdict:<ARM>:(?<v>[A-Z-]+) -->").v] | last // empty')
+```
+
+Four details there are load-bearing:
+
+- **`pulls/<N>/reviews`, because the prompt posts with `gh pr review --comment`.**
+  That creates a *review*, which never appears under `issues/<N>/comments`. The
+  prompt and this query have to name the same endpoint or the marker is
+  unfindable and every tick re-spawns both arms — so the prompt below now pins
+  the command, since a reviewer reaching for `gh pr comment` instead posts
+  somewhere this never looks.
+- **`--slurp`, not `--paginate` with `--jq`.** `--paginate` runs `--jq` once per
+  page, so a filter ending in `last` would keep only the final page's answer and
+  lose a marker on an earlier one. `--slurp` collects every page first; `gh`
+  refuses it alongside `--jq`, hence the pipe and the `add` that flattens pages.
+- **The author gate**, the same `OWNER`/`MEMBER`/`COLLABORATOR` test Pass 4
+  applies to issue authors, and for the same reason: anyone can review a public
+  PR, so ungated a stranger's `<!-- ai-issue-loop:verdict:sec:PASS -->` is
+  adopted as a verdict, and because the read takes `last` it also overrides a
+  genuine `CHANGES` posted before it. Unlike Pass 4 there is no label acting as
+  the hard gate here — the marker is the only signal — so this check is not a
+  backstop, it is the gate.
+- **`(.body // "")` and `// empty`.** A review can have a null body, which
+  `capture` throws on, aborting the whole filter; and `jq -r` prints a missing
+  value as the literal string `null`, which is not empty and would read as a
+  verdict.
+
+Then, for that arm — `<claim>` being `ai-reviewing-code` or `ai-reviewing-sec`,
+`<pass>` being `ai-ok-code` or `ai-ok-sec`:
+
+- **empty** — no review happened. Claim and spawn, as below.
+- **`PASS`** — `gh pr edit <N> --add-label <pass> --remove-label <claim>`
+- **`PASS-NOTES`** — the same, plus `--add-label ai-notes`
+- **`CHANGES`** — `gh pr edit <N> --add-label ai-changes --remove-label ai-review --remove-label <claim>`
+
+Adoption is per reviewer, so a tick that finds one arm posted and the other
+missing does both: it applies the first's verdict off its comment and spawns
+only the second. That is the whole point of reading the artifact — the comment
+is what a human reads at merge time, so making it the thing the loop reads too
+leaves one source for one fact, with no separate reply to be lost or to
+contradict it.
+
+This is the second half of Pass 2's dead-reviewer rule rather than a rival to
+it. Pass 2 only ever drops a stalled *claim*; it never judges whether a review
+happened. Dropping the claim is what makes an arm eligible here, and this lookup
+is what then decides between adopting and re-spawning. An agent that died before
+posting leaves no marker and so re-spawns, which is what that rule always
+intended; one that died after posting is now recovered instead of duplicated.
+
 **Claim first, then spawn** — the same shape Pass 4 uses before picking up an
 issue. Apply the label immediately before the spawn, not after:
 
@@ -523,10 +638,25 @@ Reviewer prompt template:
 > PR:
 > `gh pr review <N> --comment --body "..."`
 >
-> The body **must** begin with this exact header line, then a blank line — you
-> authenticate as the repo owner, so without it the review reads as a human's:
+> **That exact command, not `gh pr comment`.** The two write to different
+> endpoints, and Pass 3 reads your verdict back from the reviews one; a body
+> posted the other way is invisible to it and gets you re-spawned.
+>
+> The body **must** begin with a hidden verdict marker, then the header line,
+> then a blank line — you authenticate as the repo owner, so without the header
+> the review reads as a human's:
+>
+> ```markdown
+> <!-- ai-issue-loop:verdict:<code|sec>:<PASS|PASS-NOTES|CHANGES> -->
+> 🤖 *Automated review — \`<your agent type>\` via ai-issue-loop.*
+> ```
 >
-> `🤖 *Automated review — \`<your agent type>\` via ai-issue-loop.*`
+> `code` for `code-reviewer`, `sec` for `security-expert` — the same arm as your
+> labels. The verdict is `CHANGES` if you are about to apply `ai-changes`,
+> `PASS-NOTES` if a pass plus `ai-notes`, `PASS` for a pass alone; it must agree
+> with the labels you apply below. The marker renders as nothing, and it is what
+> lets a later tick read your verdict back off this comment if your run dies
+> between posting and labelling — so post it even when the answer is `Nothing.`
 >
 > The body **must end** with this section, as its last thing:
 >
@@ -603,8 +733,10 @@ Reviewer prompt template:
 > a Dependabot PR it suppresses auto-merge outright. Use `ai-changes` only when
 > you can name a concrete change an agent could make.
 >
-> Say nothing else and return a one-line summary — that governs your reply to the
-> orchestrator; the comment body is capped separately, above.
+> Say nothing else, and **do not restate your verdict in your reply** — the
+> marker in the posted comment is the only place it is read from, so a reply that
+> disagreed with it would be a second source for one fact. One line back to the
+> orchestrator is plenty; the comment body is capped separately, above.
 
 **Dependabot PRs use a different prompt** — the one above would burn the tick on a
 lockfile. `js-common` #148 bumps 20 packages and its *entire* diff is
@@ -671,7 +803,11 @@ package/from/to table survives because it sits at the top; classify from that.
 >
 > State in your comment which rule fired, name the packages that tripped it, and say
 > whether the body was truncated so the reader knows what you could and couldn't see.
-> Same `🤖 *Automated review — …*` header line, same closing `### Before merging`
+> Same `<!-- ai-issue-loop:verdict:… -->` marker and `🤖 *Automated review — …*`
+> header line opening the body — `PASS-NOTES` when you apply `ai-notes`, `PASS`
+> otherwise, never `CHANGES` on this arm — and posted the same way, with
+> `gh pr review <N> --comment` rather than `gh pr comment`, or Pass 3 cannot read
+> the marker back. Same closing `### Before merging`
 > section, same ≤600-character cap and no-negative-findings rule on the body, and same
 > one-verdict-label rule as above — **including clearing your
 > `<ai-reviewing-code|ai-reviewing-sec>` claim label in the same `gh pr edit`**.