testguard-cli 0.18.3__tar.gz → 0.19.0__tar.gz

testguard_cli-0.19.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 📖 Documentation
+    url: https://github.com/raccioly/testguard/blob/main/docs/README.md
+    about: Quickstart, adoption guides, the CLI reference and troubleshooting.
+  - name: 💬 Questions and adoption help
+    url: https://github.com/raccioly/testguard/discussions
+    about: How to state a claim, read a verdict or fit TestGuard to your stack.
+  - name: 🔒 Security vulnerability
+    url: https://github.com/raccioly/testguard/security/advisories/new
+    about: Report privately. Do not open a public issue; see SECURITY.md.

testguard_cli-0.19.0/.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,17 @@
+---
+name: 📖 Documentation
+about: A page that is wrong, missing, unclear or out of date
+title: '[DOCS] '
+labels: documentation
+assignees: ''
+---
+
+## Which page
+
+<!-- A link to the page and heading, e.g. docs/guides/existing-projects.md#4-gate-new-changes-from-today -->
+
+## What is wrong or missing
+
+<!-- If the page contradicts what the CLI does, paste the command and its output. -->
+
+## What you were trying to do

{testguard_cli-0.18.3 → testguard_cli-0.19.0}/.github/scripts/install-smoke.mjs

@@ -49,7 +49,7 @@ try {
   const emptyStatus = JSON.parse(run(bin, ['probe', emptyProject, '--allow-empty', '--json'], consumer));
   if (emptyStatus.state !== 'no-claims' || emptyStatus.run || existsSync(join(emptyProject, '.testguard', 'evidence.json'))) throw new Error('installed empty-adoption probe invented verification evidence');
   const replayHelp = run(bin, ['replay', '--help'], consumer);
-  if (!replayHelp.includes('--since') || replayHelp.includes('--node-modules')) throw new Error('installed command help is not command-specific');
+  if (!replayHelp.includes('--since') || replayHelp.includes('--allow-empty')) throw new Error('installed command help is not command-specific');
   writeFileSync(join(emptyProject, 'vite.config.mjs'), "export default { base: '/', plugins: [{ configureServer(s) { s.middlewares.use('/__rooms', () => {}); const parts = '/__room'.split('/'); } }] };\n");
   const installedDiscovery = join(consumer, 'node_modules', 'testguard-cli', 'src', 'probe', 'runners', 'discovery.mjs');
   run(process.execPath, ['--input-type=module', '-e',

testguard_cli-0.19.0/.github/scripts/jules-policy.mjs

@@ -0,0 +1,269 @@
+/**
+ * Policy for Google Jules pull requests: which routines exist and what each
+ * may work on, what is noise, what is a duplicate, when the queue is full,
+ * and what may merge without a human.
+ *
+ * Pure: no network, no filesystem, no clock. Three consumers pass it data:
+ *   .jules/preflight.mjs            — before Jules works (cooperative)
+ *   .github/workflows/jules-triage.yml — when a Jules PR opens (authoritative)
+ *   .github/workflows/auto-merge.yml   — after CI is green on a Jules PR
+ *
+ * The default is HOLD. Every merge rule is an allowlist; anything it does not
+ * recognise goes to a human. A wrongly held PR costs a click; a wrongly merged
+ * one ships through the weekly release to npm and PyPI.
+ */
+
+export const JULES_LOGIN = 'google-labs-jules[bot]';
+
+/** Open Jules PRs that may wait for review before new ones are closed unread. */
+export const QUEUE_CAP = 5;
+
+/** A Jules PR closed unmerged this recently blocks the same work being re-proposed. */
+export const DECLINE_WINDOW_DAYS = 60;
+
+export const LABELS = Object.freeze({
+  noise: 'jules-noise',
+  duplicate: 'jules-duplicate',
+  declined: 'jules-previously-declined',
+  queueFull: 'jules-queue-full',
+  review: 'jules-review',
+  eligible: 'jules-automerge-eligible',
+});
+
+/**
+ * Runner and project shapes a field user is likely to have. `runner-scout`
+ * builds one per run, outside the repository, and probes it.
+ */
+export const RUNNER_SCENARIOS = Object.freeze([
+  ['vitest-workspace-projects', 'vitest with a workspace of two projects, defenders in only one of them'],
+  ['vitest-ts-path-aliases', 'vitest + TypeScript, imports through tsconfig "paths" aliases that extend a base config'],
+  ['vitest-setup-files', 'vitest with setupFiles that mock a module the claim targets'],
+  ['jest-projects', 'jest with a "projects" array, defenders split across both projects'],
+  ['jest-esm', 'jest running native ESM via --experimental-vm-modules'],
+  ['jest-ts-jest', 'jest + ts-jest transforming TypeScript sources'],
+  ['playwright-custom-testdir', 'Playwright with a non-default testDir beside vitest unit tests'],
+  ['pytest-conftest-fixtures', 'pytest with conftest.py fixtures that import the target module'],
+  ['pytest-src-layout', 'pytest on a src/ layout package installed in editable mode'],
+  ['unittest-nested-discovery', 'stdlib unittest discovery across nested packages'],
+  ['node-test-native', 'node:test with no test dependency installed'],
+  ['npm-workspaces-monorepo', 'npm workspaces monorepo, probing one package from the repository root'],
+]);
+export const SCENARIO_IDS = Object.freeze(RUNNER_SCENARIOS.map(([id]) => id));
+
+export const ROUTINES = Object.freeze(['scaffold-hunt', 'runner-scout', 'docs-drift']);
+
+export const isJules = (login) => String(login ?? '').toLowerCase().replace(/^app\//, '') === JULES_LOGIN
+  || String(login ?? '').toLowerCase() === 'google-labs-jules';
+
+/** `[jules:scaffold-hunt] src/git.mjs — two survivors defended` → { routine, target } */
+export function parseTag(title) {
+  const m = /^\[jules:([a-z0-9-]+)\]\s+(\S+)/.exec(String(title ?? '').trim());
+  return m && ROUTINES.includes(m[1]) ? { routine: m[1], target: m[2] } : null;
+}
+
+export const tagTitle = (routine, target) => `[jules:${routine}] ${target}`;
+
+const names = (files) => files.map((f) => f.filename ?? f);
+
+/** Bookkeeping files that do not make two changes different. */
+const BOOKKEEPING = new Set(['CHANGELOG.md']);
+
+/** The file set that identifies a change. Bots word one change many ways; the files do not move. */
+export const dupKey = (filenames) => [...new Set(filenames)].filter((f) => !BOOKKEEPING.has(f)).sort().join('\n');
+
+const PERSONA = /(?:^|\s|\])(?:🛡️|⚡|🎨)|\b(?:sentinel|bolt|palette)\s*:/i;
+const NO_OP = /\b(?:no (?:changes?|action|issues?|updates?) (?:needed|required|found)|(?:already|is|are) up[- ]to[- ]date|nothing to (?:do|change|fix|update)|verif(?:y|ied|ying) (?:test )?stability)\b/i;
+const COUNT_SYNC = /\b(?:sync|update|bump|refresh|fix)\b.{0,40}\b(?:test )?(?:counts?|metrics?|numbers?|totals?)\b/i;
+
+/**
+ * Classes that are reliably regenerated noise. Returns a reason, or null.
+ * Each one cost a sibling project dozens of PRs before it had a name.
+ */
+export function noiseReason({ title, files }) {
+  const changed = names(files);
+  if (changed.length === 0) return 'it changes no files: a status report is a task summary, not a pull request';
+  if (PERSONA.test(title ?? '')) return 'it comes from a built-in Jules persona (Sentinel, Bolt, Palette), which is not enabled for this repository';
+  if (NO_OP.test(title ?? '')) return 'its title reports that nothing needed changing';
+  if (changed.every((n) => n.startsWith('.jules/'))) return 'it changes only `.jules/`, the routines that steer Jules; those change through a maintainer';
+  if (COUNT_SYNC.test(title ?? '') && changed.every(isDocPath)) return 'it syncs a count or metric in prose; the docs checks in CI own that, and a count changes with every merge';
+  return null;
+}
+
+const daysBetween = (a, b) => Math.abs(Date.parse(a) - Date.parse(b)) / 86_400_000;
+
+/** The same work: the same routine target, or the same changed-file set. */
+function sameWork(a, b) {
+  const ta = parseTag(a.title), tb = parseTag(b.title);
+  if (ta && tb && ta.routine === tb.routine && ta.target === tb.target) return true;
+  const ka = dupKey(names(a.files)), kb = dupKey(names(b.files));
+  return ka !== '' && ka === kb;
+}
+
+const labelled = (pr, name) => (pr.labels ?? []).some((l) => (l.name ?? l) === name);
+
+/**
+ * Decide what happens to a Jules PR the moment it opens.
+ *
+ * `pr`     { number, title, files: [{ filename, status }] }
+ * `open`   other OPEN Jules PRs, each { number, title, files: [names], labels }
+ * `closed` recently closed Jules PRs, each { number, title, files, labels, mergedAt, closedAt }
+ * `now`    ISO timestamp (passed in: the policy reads no clock)
+ *
+ * → { action: 'close' | 'keep', label, reason, ref? }
+ */
+export function triage({ pr, open, closed, now }) {
+  const noise = noiseReason({ title: pr.title, files: pr.files });
+  if (noise) return { action: 'close', label: LABELS.noise, reason: noise };
+
+  const others = open.filter((o) => o.number !== pr.number);
+  const older = others.filter((o) => o.number < pr.number && sameWork(o, pr)).sort((a, b) => a.number - b.number)[0];
+  if (older) return { action: 'close', label: LABELS.duplicate, ref: older.number, reason: `it is the same work as #${older.number}, which is still open` };
+
+  const declined = closed
+    .filter((c) => !c.mergedAt && c.closedAt && daysBetween(c.closedAt, now) <= DECLINE_WINDOW_DAYS)
+    .filter((c) => !labelled(c, LABELS.queueFull))
+    .filter((c) => sameWork(c, pr))
+    .sort((a, b) => b.number - a.number)[0];
+  if (declined) return { action: 'close', label: LABELS.declined, ref: declined.number, reason: `the same work was closed without merging in #${declined.number} within the last ${DECLINE_WINDOW_DAYS} days` };
+
+  const waiting = others.filter((o) => !labelled(o, LABELS.queueFull)).length;
+  if (waiting >= QUEUE_CAP) return { action: 'close', label: LABELS.queueFull, reason: `${waiting} Jules PRs are already waiting for review (cap ${QUEUE_CAP}); the work is not lost, the routine proposes it again once the queue drains` };
+
+  // A preview: the claims contents are compared only once CI is green, by auto-merge.
+  const { verdict, reason } = mergeVerdict({ files: pr.files, claims: null, preview: true });
+  return verdict === 'merge'
+    ? { action: 'keep', label: LABELS.eligible, reason }
+    : { action: 'keep', label: LABELS.review, reason };
+}
+
+/** Prose a bot may change without a human: the user docs, not the rules. */
+export function isDocPath(f) {
+  return f === 'README.md' || (f.startsWith('docs/') && f.endsWith('.md'));
+}
+
+/** A new test module, outside the shared helpers every other test imports. */
+const isNewTestPath = (f) => /^test\/(?!helpers\/)[^]*\.test\.mjs$/.test(f);
+
+const MAX_FILES = 25;
+
+const canonical = (v) => Array.isArray(v) ? v.map(canonical)
+  : v && typeof v === 'object' ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canonical(v[k])]))
+  : v;
+const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+const without = (o, key) => { const { [key]: _drop, ...rest } = o; return rest; };
+
+/**
+ * True when `head` differs from `base` only by defenders appended to
+ * `defendedBy` lists (claim- or fault-level), each one a test this PR adds.
+ * Anything else in the claims file is the contract and needs a human.
+ */
+export function claimsOnlyGainDefenders(base, head, addedTests) {
+  if (!base || !head || !same(without(base, 'claims'), without(head, 'claims'))) return false;
+  if (base.claims.length !== head.claims.length) return false;
+  const added = new Set(addedTests);
+  const grew = (b = [], h = []) => b.every((x, i) => h[i] === x) && h.slice(b.length).every((x) => added.has(x));
+  return base.claims.every((bc, i) => {
+    const hc = head.claims[i];
+    if (bc.id !== hc.id || bc.faults.length !== hc.faults.length) return false;
+    if (!same(without(without(bc, 'defendedBy'), 'faults'), without(without(hc, 'defendedBy'), 'faults'))) return false;
+    if (!grew(bc.defendedBy, hc.defendedBy)) return false;
+    return bc.faults.every((bf, j) => {
+      const hf = hc.faults[j];
+      return same(without(bf, 'defendedBy'), without(hf, 'defendedBy')) && grew(bf.defendedBy, hf.defendedBy);
+    });
+  });
+}
+
+/**
+ * May a green Jules PR merge without a human?
+ *
+ * `files`  the immutable base...head comparison: { filename, status, previous_filename? }
+ * `claims` { base, head } parsed testguard.claims.json when the PR changes it, else null
+ *
+ * Merges: user docs; new test modules; and defenders for those new tests
+ * appended to existing claims (a new test file must defend a claim or the
+ * gate fails it). Never: src/, spec/, fixtures/, .github/, .jules/, packaging,
+ * instruction files, a removed or renamed file, an edited test, a claim or
+ * fault that changed.
+ */
+export function mergeVerdict({ files, claims, preview = false }) {
+  if (!files.length) return { verdict: 'hold', reason: 'no files changed' };
+  if (files.length > MAX_FILES) return { verdict: 'hold', reason: `${files.length} files changed (limit ${MAX_FILES}): a refactor in disguise` };
+
+  const addedTests = [];
+  let claimsFile = false;
+  let substance = 0;
+  for (const f of files) {
+    const name = f.filename;
+    if (f.previous_filename || !['added', 'modified'].includes(f.status)) return { verdict: 'hold', reason: `${name} was ${f.status}: removing or renaming a file needs a human` };
+    if (name === 'testguard.claims.json') { claimsFile = true; continue; }
+    if (BOOKKEEPING.has(name)) continue;
+    if (isDocPath(name)) { substance++; continue; }
+    if (isNewTestPath(name) && f.status === 'added') { addedTests.push(name); substance++; continue; }
+    if (isNewTestPath(name)) return { verdict: 'hold', reason: `${name} edits an existing test: an assertion that changed is a change to what the suite defends` };
+    return { verdict: 'hold', reason: `${name} is outside what a bot may merge alone (user docs, new tests, defenders for them)` };
+  }
+  if (!substance) return { verdict: 'hold', reason: 'only bookkeeping changed' };
+  if (claimsFile && !preview) {
+    if (!claims) return { verdict: 'hold', reason: 'testguard.claims.json changed and its contents were not compared' };
+    if (!claimsOnlyGainDefenders(claims.base, claims.head, addedTests)) {
+      return { verdict: 'hold', reason: 'testguard.claims.json changes more than defenders for the tests this PR adds: a claim or fault changed, which is the contract' };
+    }
+  }
+  const parts = [addedTests.length && `${addedTests.length} new test file(s)`, claimsFile && 'their defenders', files.some((f) => isDocPath(f.filename)) && 'user docs'].filter(Boolean);
+  return { verdict: 'merge', reason: parts.join(', ') };
+}
+
+/** ISO-8601 week number, so a weekly routine walks its targets in a fixed order. */
+export function isoWeek(iso) {
+  const d = new Date(Date.parse(iso));
+  const t = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+  const day = (new Date(t).getUTCDay() + 6) % 7;
+  const thursday = t - day * 86_400_000 + 3 * 86_400_000;
+  const yearStart = Date.UTC(new Date(thursday).getUTCFullYear(), 0, 1);
+  return 1 + Math.floor((thursday - yearStart) / (7 * 86_400_000));
+}
+
+/**
+ * The work a routine has been given, or why it has none. Deterministic for a
+ * week: the rotation starts at the week number and skips every target that
+ * is open, recently declined, or (for the queue) over the cap.
+ *
+ * → { go: true, target } | { go: false, reason }
+ */
+export function pickTarget({ routine, candidates, open, closed, now }) {
+  if (!ROUTINES.includes(routine)) return { go: false, reason: `unknown routine "${routine}"; known: ${ROUTINES.join(', ')}` };
+  const waiting = open.filter((o) => !labelled(o, LABELS.queueFull)).length;
+  if (waiting >= QUEUE_CAP) return { go: false, reason: `the review queue is full: ${waiting} Jules PRs are waiting (cap ${QUEUE_CAP})` };
+  if (!candidates.length) return { go: false, reason: 'the routine has no candidate targets' };
+  const taken = new Set([
+    ...open,
+    ...closed.filter((c) => !c.mergedAt && c.closedAt && daysBetween(c.closedAt, now) <= DECLINE_WINDOW_DAYS && !labelled(c, LABELS.queueFull)),
+  ].map((p) => parseTag(p.title)).filter((t) => t?.routine === routine).map((t) => t.target));
+  const start = isoWeek(now) % candidates.length;
+  for (let i = 0; i < candidates.length; i++) {
+    const target = candidates[(start + i) % candidates.length];
+    if (!taken.has(target)) return { go: true, target };
+  }
+  return { go: false, reason: `every ${routine} target is already open or was declined in the last ${DECLINE_WINDOW_DAYS} days` };
+}
+
+/**
+ * scaffold-hunt targets: claimed source modules, thinnest first (fewest
+ * faults), so the files the claims say least about are hunted first.
+ */
+export function scaffoldTargets(claimsDoc) {
+  const faults = new Map();
+  for (const claim of claimsDoc.claims) {
+    for (const fault of claim.faults) {
+      if (!/^src\/.*\.mjs$/.test(fault.file)) continue;
+      faults.set(fault.file, (faults.get(fault.file) ?? 0) + 1);
+    }
+  }
+  return [...faults].sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0])).map(([file]) => file);
+}
+
+/** docs-drift targets: the subcommands `testguard --help` lists, in order. */
+export function helpSubcommands(helpText) {
+  return [...new Set([...String(helpText).matchAll(/^\s+testguard\s+([a-z][a-z-]*)\b/gm)].map((m) => m[1]))];
+}

testguard_cli-0.19.0/.github/scripts/jules-triage.mjs

@@ -0,0 +1,68 @@
+/**
+ * API glue for .github/workflows/jules-triage.yml. Every decision is made by
+ * jules-policy.mjs; this only gathers its inputs and carries out its answer.
+ *
+ * Runs under pull_request_target (write scope) from the default branch. It
+ * reads PR metadata through the API and never checks out or executes PR code.
+ *
+ * Comments never mention the agent by handle: with Jules' Reactive Mode on,
+ * a mention is an instruction, and a closed PR is not one to act on.
+ */
+import { DECLINE_WINDOW_DAYS, LABELS, isJules, triage } from './jules-policy.mjs';
+
+const MARKER = '<!-- testguard-jules:triage -->';
+const COLORS = {
+  [LABELS.noise]: 'CCCCCC', [LABELS.duplicate]: 'CCCCCC', [LABELS.declined]: 'CCCCCC',
+  [LABELS.queueFull]: 'FBCA04', [LABELS.review]: 'B60205', [LABELS.eligible]: '0E8A16',
+};
+
+export async function run({ github, context, core }) {
+  const { owner, repo } = context.repo;
+  const number = context.payload.pull_request.number;
+  const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: number });
+  if (!isJules(pr.user.login) || pr.state !== 'open') { core.info(`#${number}: not an open Jules PR`); return; }
+
+  const filesOf = async (n) => (await github.paginate(github.rest.pulls.listFiles, { owner, repo, pull_number: n, per_page: 100 }))
+    .map((f) => ({ filename: f.filename, status: f.status }));
+  const shape = async (p) => ({
+    number: p.number, title: p.title, labels: p.labels, mergedAt: p.merged_at, closedAt: p.closed_at,
+    files: (await filesOf(p.number)).map((f) => f.filename),
+  });
+
+  const now = new Date().toISOString();
+  const openJules = (await github.paginate(github.rest.pulls.list, { owner, repo, state: 'open', per_page: 100 }))
+    .filter((p) => isJules(p.user.login) && p.number !== number);
+  const cutoff = Date.now() - DECLINE_WINDOW_DAYS * 86_400_000;
+  const { data: recent } = await github.rest.pulls.list({ owner, repo, state: 'closed', sort: 'updated', direction: 'desc', per_page: 100 });
+  const closedJules = recent.filter((p) => isJules(p.user.login) && p.closed_at && Date.parse(p.closed_at) >= cutoff);
+
+  const decision = triage({
+    pr: { number, title: pr.title, files: await filesOf(number) },
+    open: await Promise.all(openJules.map(shape)),
+    closed: await Promise.all(closedJules.map(shape)),
+    now,
+  });
+  core.info(`#${number}: ${decision.action} (${decision.label}) — ${decision.reason}`);
+
+  await github.rest.issues.createLabel({ owner, repo, name: decision.label, color: COLORS[decision.label] ?? 'CCCCCC' }).catch(() => {});
+  await github.rest.issues.addLabels({ owner, repo, issue_number: number, labels: [decision.label] });
+
+  if (decision.action === 'close') {
+    await github.rest.issues.createComment({
+      owner, repo, issue_number: number,
+      body: `${MARKER}\n**Closed automatically:** ${decision.reason}.\n\n`
+        + 'Jules PRs on this repository follow the policy in `.github/scripts/jules-policy.mjs` and the '
+        + '**Automated agents** section of `AGENTS.md`: one PR per routine target, a target is not re-proposed '
+        + 'while it is open or for 60 days after it was declined, and at most five wait for review at once. '
+        + 'A maintainer can reopen this if the policy got it wrong.',
+    });
+    await github.rest.pulls.update({ owner, repo, pull_number: number, state: 'closed' });
+    return;
+  }
+  await github.rest.issues.createComment({
+    owner, repo, issue_number: number,
+    body: decision.label === LABELS.eligible
+      ? `${MARKER}\n**Eligible to merge on green CI** — ${decision.reason}. The auto-merge workflow re-checks the exact head and the claims file before it merges.`
+      : `${MARKER}\n**Needs a maintainer** — ${decision.reason}. CI still runs; nothing merges without a human.`,
+  });
+}

{testguard_cli-0.18.3 → testguard_cli-0.19.0}/.github/scripts/sync-release-version.mjs

@@ -8,6 +8,8 @@
  *                            from the PUBLISHED tarball (release.yml, after npm)
  *   - packaging/gitlab/*.yml  the include URL tag and the `version` input default
  *   - README.md               the GitHub Action reference AND the GitLab include URL
+ *   - .pre-commit-hooks.yaml  the `rev:` in the consumer example
+ *   - docs/** (DOC_SURFACES)  every docs page that shows a pinned install
  *
  * A file may carry more than one form, and each needs its own entry: README
  * holds both the `raccioly/testguard@vX.Y.Z` action reference and the
@@ -102,8 +104,40 @@ const surfaces = [
   // Sync the two separately and they disagree — the failure that is worse than
   // being stale, because the document then contradicts itself.
   ['docs/testguard-explained.html', /(Technical Brief · v)\d+\.\d+\.\d+( · MIT)/, `$1${version}$2`],
+  // The consumer-facing example at the top of the hooks manifest. It read
+  // v0.1.0 for eighteen releases because nothing looked at it.
+  ['.pre-commit-hooks.yaml', /(raccioly\/testguard\n#\s+rev: )v\d+\.\d+\.\d+/, `$1v${version}`],
 ];
 
+/**
+ * The docs pages that show a pinned install. Each may carry any of the pin
+ * forms below but must carry at least one: a page registered here that pins
+ * nothing is a page someone moved the pin out of, and the list is stale.
+ * A pin in a page NOT listed here fails test/release-version.test.mjs, which
+ * finds pins by content — the README lesson above, applied to docs/.
+ */
+const DOC_SURFACES = [
+  'docs/installation.md',
+  'docs/guides/ci/github-actions.md',
+  'docs/guides/ci/gitlab.md',
+  'docs/guides/ci/pre-commit.md',
+  'docs/guides/monorepo.md',
+  // Translations of the README carry its install table, pins included.
+  'docs/i18n/pt-BR/README.md',
+  'docs/i18n/es/README.md',
+  'docs/i18n/zh-CN/README.md',
+];
+const DOC_PIN_FORMS = [
+  [/raccioly\/testguard@v\d+\.\d+\.\d+/g, `raccioly/testguard@v${version}`],
+  [/testguard\/v\d+\.\d+\.\d+\/packaging/g, `testguard/v${version}/packaging`],
+  [/(raccioly\/testguard\n\s*rev: )v\d+\.\d+\.\d+/g, `$1v${version}`],
+];
+for (const rel of DOC_SURFACES) {
+  const forms = DOC_PIN_FORMS.filter(([pattern]) => new RegExp(pattern.source).test(readFileSync(resolve(root, rel), 'utf8')));
+  if (!forms.length) throw new Error(`${rel}: registered as a docs version surface but pins no version`);
+  for (const [pattern, replacement] of forms) surfaces.push([rel, pattern, replacement]);
+}
+
 if (listSurfaces) {
   // Derived from the same table the writes use, so the two cannot disagree.
   for (const rel of [...new Set(surfaces.map(([rel]) => rel))]) console.log(rel);

{testguard_cli-0.18.3 → testguard_cli-0.19.0}/.github/workflows/auto-merge.yml

@@ -1,9 +1,15 @@
 name: Auto-merge (green bot PRs)
 
 # After a successful CI run on a PR, merge it if — and only if — it is a
-# non-major dependabot bump or an automated release PR touching release
-# surfaces only. Everything else is left for a human. The CI run that
-# triggered this is re-verified job by job; a green badge is not trusted.
+# non-major dependabot bump, an automated release PR touching release
+# surfaces only, or a Jules PR that .github/scripts/jules-policy.mjs allows
+# (user docs, new tests, defenders for them). Everything else is left for a
+# human. The CI run that triggered this is re-verified job by job; a green
+# badge is not trusted.
+#
+# SECURITY: workflow_run has write scope. The only checkout is the default
+# branch (for the Jules policy), without persisted credentials; PR code is
+# never checked out or run, and PR contents are read through the API.
 
 on:
   workflow_run:
@@ -20,6 +26,12 @@ jobs:
     if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request'
     runs-on: ubuntu-latest
     steps:
+      - name: Check out the merge policy from the default branch (never the PR head)
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
       - name: Evaluate and merge if safe
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
@@ -30,9 +42,12 @@ jobs:
             const pr = prs.find((p) => p.state === 'open');
             if (!pr) { core.info('No open PR for this SHA.'); return; }
             const num = pr.number, author = pr.user.login;
-            const hold = async (why) => {
-              try { await github.rest.issues.addLabels({ owner, repo, issue_number: num, labels: ['needs-review'] }); } catch {}
-              await github.rest.issues.createComment({ owner, repo, issue_number: num, body: `⏸️ **Held for human review** — ${why}\n\nCI is green, but this falls outside the policy in \`.github/workflows/auto-merge.yml\`.` });
+            const hold = async (why, label = 'needs-review') => {
+              try { await github.rest.issues.addLabels({ owner, repo, issue_number: num, labels: [label] }); } catch {}
+              // One comment per distinct reason: a bot that pushes again must not stack identical holds.
+              const body = `<!-- testguard-automerge:hold -->\n⏸️ **Held for human review** — ${why}\n\nCI is green, but this falls outside the policy in \`.github/workflows/auto-merge.yml\`.`;
+              const seen = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number: num, per_page: 100 });
+              if (!seen.some((c) => c.body === body)) await github.rest.issues.createComment({ owner, repo, issue_number: num, body });
               core.notice(`#${num} held: ${why}`);
             };
             if (run.head_sha !== pr.head.sha || run.head_branch !== pr.head.ref) { core.info('Run does not match current PR head.'); return; }
@@ -53,7 +68,7 @@ jobs:
             // three files the bump writes — test/release-sync.test.mjs fails if
             // a surface is missing, which is how the GitLab template's absence
             // (it would have held every release PR for review) was found.
-            const RELEASE_SURFACES = new Set(['package.json', 'package-lock.json', 'pyproject.toml', 'CHANGELOG.md', 'action.yml', 'packaging/homebrew/testguard.rb', 'README.md', 'packaging/gitlab/testguard.gitlab-ci.yml', 'docs/testguard-explained.html', 'docs/testguard-explained.pdf']);
+            const RELEASE_SURFACES = new Set(['package.json', 'package-lock.json', 'pyproject.toml', 'CHANGELOG.md', 'action.yml', 'packaging/homebrew/testguard.rb', 'README.md', 'packaging/gitlab/testguard.gitlab-ci.yml', 'docs/testguard-explained.html', 'docs/testguard-explained.pdf', '.pre-commit-hooks.yaml', 'docs/installation.md', 'docs/guides/ci/github-actions.md', 'docs/guides/ci/gitlab.md', 'docs/guides/ci/pre-commit.md', 'docs/guides/monorepo.md', 'docs/i18n/pt-BR/README.md', 'docs/i18n/es/README.md', 'docs/i18n/zh-CN/README.md']);
 
             if (author === 'dependabot[bot]') {
               const m = /from (\d+)\.(\d+)\.\S+ to (\d+)\.(\d+)\./.exec(pr.title || '');
@@ -62,12 +77,31 @@ jobs:
             } else if (author === 'github-actions[bot]' && /^release: v\d+\.\d+\.\d+/.test(pr.title || '')) {
               const stray = paths.filter((p) => !RELEASE_SURFACES.has(p));
               if (stray.length) { await hold(`release PR touches non-release files:\n${stray.map((p) => `- \`${p}\``).join('\n')}`); return; }
+            } else if (author === 'google-labs-jules[bot]') {
+              const policy = await import(`${process.env.GITHUB_WORKSPACE}/.github/scripts/jules-policy.mjs`);
+              if (pr.labels.some((l) => l.name === policy.LABELS.queueFull)) { core.info(`#${num} was closed by triage as queue-full.`); return; }
+              // listFiles follows a branch that can move while it is read; the
+              // comparison of this exact head against its base cannot.
+              const { data: cmp } = await github.rest.repos.compareCommitsWithBasehead({ owner, repo, basehead: `${pr.base.sha}...${run.head_sha}` });
+              let claims = null;
+              if (cmp.files.some((f) => f.filename === 'testguard.claims.json')) {
+                // Raw, not base64: the inline content field stops at 1 MB and this file only grows.
+                const read = async (ref) => {
+                  const { data } = await github.rest.repos.getContent({ owner, repo, path: 'testguard.claims.json', ref, mediaType: { format: 'raw' } });
+                  return JSON.parse(typeof data === 'string' ? data : Buffer.from(data).toString('utf8'));
+                };
+                claims = { base: await read(cmp.merge_base_commit.sha), head: await read(run.head_sha) };
+              }
+              const v = policy.mergeVerdict({ files: cmp.files, claims });
+              if (v.verdict !== 'merge') { await hold(v.reason, policy.LABELS.review); return; }
+              core.info(`#${num} Jules: ${v.reason} — eligible.`);
             } else {
               core.info(`#${num} by ${author} — not a handled bot; leaving alone.`); return;
             }
 
             try {
-              const { data: merge } = await github.rest.pulls.merge({ owner, repo, pull_number: num, merge_method: 'squash' });
+              // Pinned to the verified head: a push after CI ran makes GitHub refuse the merge.
+              const { data: merge } = await github.rest.pulls.merge({ owner, repo, pull_number: num, merge_method: 'squash', sha: run.head_sha });
               if (!merge.merged) throw new Error(merge.message || 'GitHub declined the merge');
               await github.rest.issues.createComment({ owner, repo, issue_number: num, body: `🤖 **Auto-merged** — the exact CI run passed all three Node legs (20/22/24) within the runtime budget and satisfied \`.github/workflows/auto-merge.yml\`.` });
             } catch (e) {

{testguard_cli-0.18.3 → testguard_cli-0.19.0}/.github/workflows/ci.yml

@@ -405,6 +405,50 @@ jobs:
             console.log('playwright fixture verdicts match expected.json:', ev.records.length);
           "
 
+  # ── Hermeticity: the suite must not depend on the machine's git config.
+  #    Runners carry none, so a fixture that commits through a global
+  #    core.hooksPath or commit.gpgsign is green here and red on every
+  #    machine that has one — 142 tests were. On a sibling project that gap
+  #    made a coding agent re-propose the same "fix" 27 times, because CI
+  #    could never reproduce what its sandbox saw. Fixtures pin their own
+  #    git options (test/helpers/git.mjs); the product code under test
+  #    still meets this config, which is the point of running it. ──
+  hermeticity:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+      - name: Install
+        run: npm ci
+      - name: Manufacture a hostile global git config
+        shell: bash
+        run: |
+          H="$RUNNER_TEMP/hostile"
+          mkdir -p "$H/hooks"
+          for hook in pre-commit prepare-commit-msg commit-msg post-commit pre-push post-checkout; do
+            printf '#!/bin/sh\necho "hostile %s hook fired" >&2\nexit 1\n' "$hook" > "$H/hooks/$hook"
+            chmod +x "$H/hooks/$hook"
+          done
+          printf '[core]\n\thooksPath = %s\n[commit]\n\tgpgsign = true\n[tag]\n\tgpgsign = true\n[gpg]\n\tprogram = /usr/bin/false\n[init]\n\tdefaultBranch = trunk\n' "$H/hooks" > "$H/gitconfig"
+          echo "GIT_CONFIG_GLOBAL=$H/gitconfig" >> "$GITHUB_ENV"
+      # A hostile config that git ignores proves nothing; fail before the suite
+      # if an unpinned commit would still succeed under it.
+      - name: Prove the config is hostile
+        shell: bash
+        run: |
+          R="$(mktemp -d)"
+          git -C "$R" init -q
+          if git -C "$R" -c user.name=probe -c user.email=probe@example.invalid commit -q --allow-empty -m probe 2>/dev/null; then
+            echo "::error::an unpinned commit succeeded; the hostile config is not in effect"
+            exit 1
+          fi
+      - name: Run tests under the hostile config
+        run: npm test
+
   # ── npm publish dry-run on tags ──
   publish-check:
     runs-on: ubuntu-latest

testguard_cli-0.19.0/.github/workflows/jules-triage.yml

@@ -0,0 +1,41 @@
+name: Jules PR triage
+
+# Closes Google Jules PRs that are noise, duplicates, previously declined
+# work, or over the review queue cap; labels the rest. Policy:
+# .github/scripts/jules-policy.mjs (pure, unit-tested in
+# test/jules-policy.test.mjs, claimed in testguard.claims.json).
+#
+# SECURITY: pull_request_target carries write scope, so nothing here checks
+# out or runs PR code. The checkout is the default branch, credentials are not
+# persisted, and the PR is read through the API only.
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+concurrency:
+  group: jules-triage
+  cancel-in-progress: false
+
+jobs:
+  triage:
+    if: github.event.pull_request.user.login == 'google-labs-jules[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the policy from the default branch (never the PR head)
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - name: Triage
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { run } = await import(`${process.env.GITHUB_WORKSPACE}/.github/scripts/jules-triage.mjs`);
+            await run({ github, context, core });

{testguard_cli-0.18.3 → testguard_cli-0.19.0}/.gitignore

@@ -11,6 +11,11 @@ coverage/
 .testguard/gate.json
 .testguard/ci-self-evidence.json
 .testguard/scaffold-*.json
+.testguard/replay.json
+.testguard/calibration.json
+.testguard/ci/
+.testguard/sweep.json
+.testguard/sweep-evidence.json
 # Local agent tooling — not part of the public project
 .wolf/
 .claude/