mixdog 1.0.12 → 1.1.0

package/scripts/lib/run-node-tests.mjs

@@ -2,10 +2,12 @@ import { spawn } from 'node:child_process';
 import { appendFile, mkdtemp, readdir, readFile, rm, stat } from 'node:fs/promises';
 import { availableParallelism, tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { FAILURE_RECORDS_ENV } from './test-failure-records.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { FAILURE_RECORDS_ENV, spawnLedgerPath } from './test-failure-records.mjs';
 import { classifyRerunOutcomes, formatFailureSummary } from './test-failure-summary.mjs';
 
 const SUMMARY_REPORTER = new URL('./test-summary-reporter.mjs', import.meta.url).href;
+const SPAWN_LEDGER = new URL('./test-spawn-ledger.mjs', import.meta.url).href;
 
 // A whole-suite run passes ~700 paths to one node process. Windows caps a
 // command line at 32767 characters (CreateProcess) and POSIX caps argv+env at
@@ -81,17 +83,212 @@ export function testConcurrencyArg(nodeArgs, env = process.env, parallelism = av
   return `--test-concurrency=${Math.max(2, Math.floor(parallelism / cap))}`;
 }
 
-function spawnBatch(args, env) {
+// A batch that has not exited by then is killed with its process tree and
+// fails the run; MIXDOG_TEST_BATCH_TIMEOUT_MS overrides the default.
+const DEFAULT_BATCH_TIMEOUT_MS = 60 * 60 * 1000;
+const minutes = (ms) => Number((ms / 60_000).toFixed(2));
+
+// Runs a helper command to completion and returns its stdout.
+function capture(command, args) {
   return new Promise((resolve) => {
-    const child = spawn(process.execPath, args, { stdio: 'inherit', env });
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+    let out = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      out += chunk;
+    });
+    child.on('error', (error) => {
+      console.error(`${command} failed: ${error.message}`);
+      resolve('');
+    });
+    child.on('close', () => resolve(out));
+  });
+}
+
+// Kills a process and every descendant still linked to it. On POSIX a batch
+// leads its own process group (spawned detached), so the group goes with it.
+async function killTree(pid) {
+  if (process.platform === 'win32') {
+    await capture('taskkill', ['/T', '/F', '/PID', String(pid)]);
+    return;
+  }
+  for (const target of [-pid, pid]) {
+    try {
+      process.kill(target, 'SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+// Every live process: { pid, ppid, created (epoch ms), exe ('' when unknown) }.
+// POSIX ps only reports elapsed seconds, so its creation times are ±1 s.
+async function processSnapshot() {
+  if (process.platform === 'win32') {
+    const out = await capture('powershell', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      "Get-CimInstance Win32_Process | Where-Object CreationDate | ForEach-Object { '{0} {1} {2} {3}' -f $_.ProcessId, $_.ParentProcessId, ([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds(), $_.ExecutablePath }",
+    ]);
+    return out
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((line) => {
+        const [pid, ppid, created, ...exe] = line.split(' ');
+        return { pid: Number(pid), ppid: Number(ppid), created: Number(created), exe: exe.join(' ') };
+      });
+  }
+  const now = Date.now();
+  const out = await capture('ps', ['-A', '-o', 'pid=,ppid=,etime=']);
+  return out
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/))
+    .filter((fields) => fields.length === 3)
+    .map(([pid, ppid, etime]) => {
+      // [[dd-]hh:]mm:ss
+      const [days, clock] = etime.includes('-') ? etime.split('-') : ['0', etime];
+      const seconds = clock.split(':').reduce((total, part) => total * 60 + Number(part), Number(days) * 86_400);
+      return { pid: Number(pid), ppid: Number(ppid), created: now - seconds * 1000, exe: '' };
+    });
+}
+
+const CLOCK_SLACK_MS = 2000;
+
+// The processes this run owns, out of a snapshot: an anchor (the batch, or a
+// child a test process recorded in its spawn ledger) still alive under its
+// pid, the orphans an exited anchor left (they still name it as their parent;
+// a later process that reuses its pid only has younger children), every
+// descendant of those, and anything executing from the run's scratch root
+// (e.g. the postgres the memory runtime downloads into MIXDOG_DATA_DIR).
+// Command-line text never makes a process the run's: an editor or terminal
+// opened on the scratch root is not.
+export function ownedProcesses(snapshot, anchors, { batchStart, scratchDir, platform = process.platform }) {
+  const byPid = new Map(snapshot.map((entry) => [entry.pid, entry]));
+  const childrenOf = new Map();
+  for (const entry of snapshot) childrenOf.set(entry.ppid, [...(childrenOf.get(entry.ppid) ?? []), entry]);
+  const owned = new Map();
+  const queue = [];
+  const claim = (entry) => {
+    if (entry.pid === process.pid || owned.has(entry.pid)) return;
+    owned.set(entry.pid, entry);
+    queue.push(entry);
+  };
+  for (const { pid, since } of anchors) {
+    const holder = byPid.get(pid);
+    if (holder && holder.created >= batchStart - CLOCK_SLACK_MS && holder.created <= since + CLOCK_SLACK_MS) {
+      claim(holder);
+      continue;
+    }
+    for (const orphan of childrenOf.get(pid) ?? []) {
+      if (orphan.created >= since - CLOCK_SLACK_MS && (!holder || orphan.created < holder.created)) claim(orphan);
+    }
+  }
+  const fold = (path) => (platform === 'win32' ? path.toLowerCase() : path);
+  const scratchPrefix = fold(join(scratchDir, '/'));
+  for (const entry of snapshot) if (entry.exe && fold(entry.exe).startsWith(scratchPrefix)) claim(entry);
+  while (queue.length > 0) {
+    const parent = queue.pop();
+    for (const entry of childrenOf.get(parent.pid) ?? []) {
+      if (entry.created >= parent.created - CLOCK_SLACK_MS) claim(entry);
+    }
+  }
+  return [...owned.values()];
+}
+
+async function readSpawnLedger(path) {
+  const text = await readFile(path, 'utf8').catch(() => '');
+  return text
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [pid, since] = line.split(' ').map(Number);
+      return { pid, since };
+    });
+}
+
+// A process a test leaves running must not outlive its batch: it can hold a
+// port, a database, or files in the scratch root the run removes at the end.
+async function reapLeftovers(child, { batchStart, ledger, scratchDir }) {
+  // The batch itself has exited: only its process group can remain.
+  if (process.platform !== 'win32' && child.pid) {
+    try {
+      process.kill(-child.pid, 'SIGKILL');
+    } catch {
+      /* the group is empty */
+    }
+  }
+  const anchors = [...(child.pid ? [{ pid: child.pid, since: batchStart }] : []), ...(await readSpawnLedger(ledger))];
+  const leftovers = ownedProcesses(await processSnapshot(), anchors, { batchStart, scratchDir });
+  if (leftovers.length === 0) return;
+  const pids = leftovers.map((entry) => entry.pid);
+  console.error(`Killing ${pids.length} process(es) a test left running: ${pids.join(' ')}`);
+  if (process.platform === 'win32') {
+    await capture('taskkill', ['/T', '/F', ...pids.flatMap((pid) => ['/PID', String(pid)])]);
+    return;
+  }
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+// Resolves { code, hung } once the batch exited and its leftovers are gone.
+function spawnBatch(args, env, { files, ledger, scratchDir, timeoutMs }) {
+  return new Promise((resolve) => {
+    const batchStart = Date.now();
+    const child = spawn(process.execPath, args, { stdio: 'inherit', env, detached: process.platform !== 'win32' });
+    let hung = '';
+    const watchdog = setTimeout(() => {
+      hung = `hung after ${minutes(timeoutMs)} min: ${files.join(' ') || '(discovered files)'}`;
+      console.error(`Test batch ${hung}; killing its process tree`);
+      void killTree(child.pid);
+    }, timeoutMs);
+    // A detached POSIX batch no longer gets the terminal's signals itself.
+    const forward = (signal) => {
+      try {
+        process.kill(-child.pid, signal);
+      } catch {
+        /* already gone */
+      }
+    };
+    const signals = process.platform === 'win32' ? [] : ['SIGINT', 'SIGTERM'];
+    for (const signal of signals) process.on(signal, forward);
+    const settle = async (code) => {
+      clearTimeout(watchdog);
+      for (const signal of signals) process.off(signal, forward);
+      await reapLeftovers(child, { batchStart, ledger, scratchDir });
+      resolve({ code: hung ? 1 : code, hung });
+    };
     child.on('error', (error) => {
       console.error(error);
-      resolve(1);
+      void settle(1);
     });
-    child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    child.on('exit', (code, signal) => void settle(code ?? (signal ? 1 : 0)));
   });
 }
 
+// rm's own maxRetries re-walks the tree on every nested retry, so one held
+// file a few directories down multiplied its delay into hours. Each pass here
+// is a single bounded walk.
+async function removeScratch(dir) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      await rm(dir, { recursive: true, force: true });
+      return;
+    } catch (error) {
+      if (attempt === 5) {
+        console.error(`Test scratch left behind (${error.code}): ${dir}`);
+        return;
+      }
+      await delay(200 * attempt);
+    }
+  }
+}
+
 // The failure reporter writes one JSON line per failed test; a spawn that
 // died before Node opened its destination leaves no file at all.
 async function readFailureRecords(path) {
@@ -136,6 +333,8 @@ export async function runNodeTests(
   const runArgs = [
     ...nodeArgs,
     ...(concurrencyArg ? [concurrencyArg] : []),
+    // Node's test runner passes --import on to every test file process.
+    `--import=${SPAWN_LEDGER}`,
     `--test-reporter=${SUMMARY_REPORTER}`,
     '--test-reporter-destination=stdout',
     '--test-reporter=spec',
@@ -171,15 +370,25 @@ export async function runNodeTests(
     ...(coverageDir ? { NODE_V8_COVERAGE: coverageDir } : {}),
     ...(nodeOptions ? { NODE_OPTIONS: nodeOptions } : {}),
   });
+  const batchOptions = (files, recordsPath) => ({
+    files,
+    ledger: spawnLedgerPath(recordsPath),
+    scratchDir,
+    timeoutMs: positiveInt(process.env.MIXDOG_TEST_BATCH_TIMEOUT_MS) ?? DEFAULT_BATCH_TIMEOUT_MS,
+  });
   let status = 0;
   const failures = [];
+  const hung = [];
   for (const [index, batch] of batches.entries()) {
     const batchLog = batches.length === 1 ? logPath : `${logPath}.${index + 1}`;
     const batchFailures = join(failureDir, `batch-${index + 1}.jsonl`);
-    const code = await spawnBatch(
+    const outcome = await spawnBatch(
       [...runArgs, `--test-reporter-destination=${batchLog}`, ...batch],
-      childEnv(batchFailures)
+      childEnv(batchFailures),
+      batchOptions(batch, batchFailures)
     );
+    const { code } = outcome;
+    if (outcome.hung) hung.push(outcome.hung);
     if (batchLog !== logPath) {
       await appendFile(logPath, await readFile(batchLog));
       await rm(batchLog, { force: true });
@@ -196,10 +405,13 @@ export async function runNodeTests(
     console.error(`Re-running ${files.length} failed file(s): attempt ${attempt}/${rerunFailed}`);
     const attemptLog = `${logPath}.rerun-${attempt}`;
     const attemptFailures = join(failureDir, `rerun-${attempt}.jsonl`);
-    lastAttemptStatus = await spawnBatch(
+    const outcome = await spawnBatch(
       [...runArgs, `--test-reporter-destination=${attemptLog}`, ...files],
-      childEnv(attemptFailures)
+      childEnv(attemptFailures),
+      batchOptions(files, attemptFailures)
     );
+    lastAttemptStatus = outcome.code;
+    if (outcome.hung) hung.push(outcome.hung);
     await appendFile(logPath, await readFile(attemptLog));
     await rm(attemptLog, { force: true });
     attempts.push({ files, failures: await readFailureRecords(attemptFailures) });
@@ -209,17 +421,27 @@ export async function runNodeTests(
   // Flaky tolerance applies only to an ordinary test-failure exit that the
   // re-runs fully explained: nothing failed twice and the last re-run itself
   // came back clean.
-  if (rerunFailed > 0 && status === 1 && failed.length === 0 && flaky.length > 0 && lastAttemptStatus === 0) status = 0;
+  // A hung batch is never explained by re-runs.
+  if (
+    rerunFailed > 0 &&
+    status === 1 &&
+    hung.length === 0 &&
+    failed.length === 0 &&
+    flaky.length > 0 &&
+    lastAttemptStatus === 0
+  )
+    status = 0;
   process.exitCode = status;
 
   await rm(failureDir, { recursive: true, force: true });
-  // A process a test left running may still hold a file; what it holds stays.
-  await rm(scratchDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }).catch(() => {});
+  // Leftover processes are already killed; what a process outside the run
+  // still holds stays behind.
+  await removeScratch(scratchDir);
   if (coverageDir) {
     const { reportCoverage } = await import('./coverage.mjs');
     await reportCoverage(coverageDir);
     await rm(coverageDir, { recursive: true, force: true });
   }
   // Last line of the run, after every reporter and the coverage report.
-  process.stdout.write(`\n${formatFailureSummary({ failed, flaky, rerunFailed })}`);
+  process.stdout.write(`\n${formatFailureSummary({ failed, flaky, rerunFailed, hung })}`);
 }

package/scripts/lib/test-failure-records.mjs

@@ -13,6 +13,11 @@ import { relative } from 'node:path';
 
 export const FAILURE_RECORDS_ENV = 'MIXDOG_TEST_FAILURE_RECORDS';
 
+// Every child process a test process starts is logged beside its spawn's
+// failure records (scripts/lib/test-spawn-ledger.mjs), so the runner can tell
+// a process the run started from one that merely names its directories.
+export const spawnLedgerPath = (recordsPath) => (recordsPath ? `${recordsPath}.spawns` : '');
+
 // Ancestor names are tracked per file: node:test runs files concurrently, so
 // one flat stack would mix their nestings.
 export function failureRecord(event, stacks) {

package/scripts/lib/test-failure-summary.mjs

@@ -43,8 +43,14 @@ export function policyLine(rerunFailed) {
     : 'policy: --rerun-failed is off, so every failure fails the run (pass --rerun-failed <n> to classify flaky)';
 }
 
-export function formatFailureSummary({ failed = [], flaky = [], rerunFailed = 0 }) {
-  const lines = [`${SUMMARY_TAG} ${failed.length} failed, ${flaky.length} flaky (every failed test is named below)`];
+// `hung` holds one "hung after N min: <files>" message per batch the runner's
+// watchdog killed; such a batch fails the run whatever its tests reported.
+export function formatFailureSummary({ failed = [], flaky = [], rerunFailed = 0, hung = [] }) {
+  const hungCount = hung.length > 0 ? `, ${hung.length} hung batch(es)` : '';
+  const lines = [
+    `${SUMMARY_TAG} ${failed.length} failed, ${flaky.length} flaky${hungCount} (every failed test is named below)`,
+  ];
+  for (const message of hung) lines.push(`${SUMMARY_TAG} HUNG ${message}`);
   for (const record of failed) {
     const origin = record.firstSeenOnRerun ? ` (first seen on re-run ${record.firstSeenOnRerun})` : '';
     lines.push(`${SUMMARY_TAG} FAILED ${record.file} > ${record.name}${origin}`);
@@ -54,6 +60,6 @@ export function formatFailureSummary({ failed = [], flaky = [], rerunFailed = 0
       `${SUMMARY_TAG} FLAKY ${record.file} > ${record.name} (failed, then passed on re-run ${record.passedOnAttempt}/${rerunFailed})`
     );
   }
-  if (failed.length > 0 || flaky.length > 0) lines.push(`${SUMMARY_TAG} ${policyLine(rerunFailed)}`);
+  if (failed.length > 0 || flaky.length > 0 || hung.length > 0) lines.push(`${SUMMARY_TAG} ${policyLine(rerunFailed)}`);
   return `${lines.join('\n')}\n`;
 }

package/scripts/lib/test-spawn-ledger.mjs

@@ -0,0 +1,19 @@
+// Preloaded (--import) into every test process the runner starts: records
+// "<pid> <spawn time ms>" for each child process, so a process a test leaves
+// running can be traced back to the run after its parent exited
+// (scripts/lib/run-node-tests.mjs). Without the runner's environment it does
+// nothing.
+import { ChildProcess } from 'node:child_process';
+import { appendFileSync } from 'node:fs';
+import { FAILURE_RECORDS_ENV, spawnLedgerPath } from './test-failure-records.mjs';
+
+const ledger = spawnLedgerPath(process.env[FAILURE_RECORDS_ENV]);
+if (ledger) {
+  // spawn, exec, execFile and fork all start their process here.
+  const spawn = ChildProcess.prototype.spawn;
+  ChildProcess.prototype.spawn = function recordedSpawn(...args) {
+    const result = spawn.apply(this, args);
+    if (this.pid) appendFileSync(ledger, `${this.pid} ${Date.now()}\n`);
+    return result;
+  };
+}

package/scripts/prune-embedding-runtime.mjs

@@ -3,6 +3,7 @@
 import { access, readdir, rm } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { onnxRuntimeSupported } from '../src/runtime/shared/onnx-runtime-support.mjs';
 
 const SUPPORTED_TARGETS = new Map([
   ['win32', new Set(['x64', 'arm64'])],
@@ -83,8 +84,9 @@ export async function pruneEmbeddingRuntime(packageRoot, options = {}) {
   ).find(Boolean);
   if (!ortRoot) throw new Error('Embedding runtime is incomplete: onnxruntime-node is unavailable');
 
-  const targetBinaryDir = join(ortRoot, 'bin', 'napi-v6', target.platform, target.arch);
-  if (!(await exists(join(targetBinaryDir, 'onnxruntime_binding.node')))) {
+  const onnx = onnxRuntimeSupported(target.platform, target.arch);
+  const targetBinaryDir = onnx ? join(ortRoot, 'bin', 'napi-v6', target.platform, target.arch) : null;
+  if (onnx && !(await exists(join(targetBinaryDir, 'onnxruntime_binding.node')))) {
     throw new Error(`Embedding runtime is incomplete: missing ${target.key} ONNX binding`);
   }
 
@@ -100,10 +102,11 @@ export async function pruneEmbeddingRuntime(packageRoot, options = {}) {
   // bin/napi-v6/${process.platform}/${process.arch}/onnxruntime_binding.node.
   // Keep one native payload and remove every foreign OS/architecture.
   const napiRoot = join(ortRoot, 'bin', 'napi-v6');
-  await removeChildrenExcept(napiRoot, new Set([target.platform]));
-  await removeChildrenExcept(join(napiRoot, target.platform), new Set([target.arch]));
+  // Targets without an ONNX binding keep no native payload at all.
+  await removeChildrenExcept(napiRoot, new Set(onnx ? [target.platform] : []));
+  if (onnx) await removeChildrenExcept(join(napiRoot, target.platform), new Set([target.arch]));
   const removedTargetFiles = [];
-  if (target.platform === 'win32') {
+  if (onnx && target.platform === 'win32') {
     // The fixed production embedding profile uses CPU inference. Keep
     // DirectML.dll for explicit device overrides, but remove the optional DXC
     // shader compiler payload verified unnecessary by packaged-runtime warmup.
@@ -132,6 +135,7 @@ export async function pruneEmbeddingRuntime(packageRoot, options = {}) {
     ...target,
     transformerRoot,
     ortRoot,
+    onnx,
     targetBinaryDir,
     removedTargetFiles,
   };

package/scripts/test-direct.mjs

@@ -2,5 +2,20 @@
 // Explicit Node test options and file paths, without discovery or lane filters.
 import { runNodeTests } from './lib/run-node-tests.mjs';
 
+const argv = process.argv.slice(2);
+// The same defaults as scripts/test.mjs: `mock.module` is still flag-gated on
+// 22/24, and a suite that leaves a handle open must not hang the whole run.
+// A flag the caller already passed (to node or to this script) is not repeated.
+const given = new Set([...process.execArgv, ...argv]);
+const unlessGiven = (flag) => (given.has(flag) ? [] : [flag]);
+
 // Preserve parent Node flags such as heap limits and preload modules.
-await runNodeTests([...process.execArgv, '--test'], process.argv.slice(2));
+await runNodeTests(
+  [
+    ...process.execArgv,
+    ...unlessGiven('--experimental-test-module-mocks'),
+    '--test',
+    ...unlessGiven('--test-force-exit'),
+  ],
+  argv
+);

package/src/agents/advisor/AGENT.md

@@ -0,0 +1,38 @@
+---
+name: Advisor
+description: Use on non-trivial work after orientation and before committing to an approach, when stuck or results do not converge, before changing approach, and for requested second opinions. Skip for low-difficulty work. Advisory analysis only; the final check belongs to Reviewer.
+---
+
+Independent technical advisor.
+
+You are consulted at decision points: once orientation is done and before an
+approach is committed, when errors recur or results stop converging, before a
+change of approach, and when the user asks for a second opinion or
+cross-validation. You do not see the Lead's conversation; work from the brief
+and verify its evidence against the source yourself.
+
+For design advice, compare the smallest viable alternatives against the
+requested outcome, established project patterns, correctness, compatibility,
+security, performance, and maintenance cost. Recommend one course of action and
+explain the material trade-off. Do not broaden the task into a general audit or
+redesign.
+
+For a stuck or non-converging task, identify the most likely cause from the
+actual execution paths and observed behavior, and name the decisive check that
+separates competing explanations. Reproduce counterexamples with bounded tests
+when needed. A passing test is evidence only for the path it exercises.
+
+When the brief reports evidence that conflicts with earlier advice, resolve the
+conflict explicitly: state which constraint decides it and why.
+
+Work from source and observed behavior, not from the Lead's conclusion. State
+what is confirmed, inferred, or unverified; name missing evidence and concrete
+blockers rather than inventing certainty.
+
+Do not implement fixes, modify project files or settings, stage or commit
+changes, deploy, or delegate work. Keep checks non-destructive and isolate any
+test fixtures from existing user data. The final check belongs to Reviewer.
+
+Lead with the recommendation, then actionable findings ordered by severity, with
+evidence located by project-relative path and function or symbol. If no issue
+is found, say so and list only material residual risks and verification limits.

package/src/agents/advisor/agent.json

@@ -0,0 +1,6 @@
+{
+  "id": "advisor",
+  "name": "Advisor",
+  "description": "Use on non-trivial work after orientation and before committing to an approach, when stuck or results do not converge, before changing approach, and for requested second opinions. Skip for low-difficulty work. Advisory analysis only; the final check belongs to Reviewer.",
+  "entry": "AGENT.md"
+}

package/src/agents/reviewer/AGENT.md

@@ -1,9 +1,12 @@
 ---
 name: Reviewer
-description: Use after implementation to independently verify correctness, regressions, risks, and stated acceptance criteria before final reporting.
+description: Use once at the final check of non-trivial work: after the implementation is written and verified, before reporting completion, to independently verify correctness, regressions, risks, and acceptance criteria. Skip for low-difficulty work.
 ---
 
-Independent regression/risk review agent.
+Independent final-check review agent.
+
+You are called once, after the deliverable is written and the Lead's own
+verification has run, before completion is reported.
 
 Inspect the diff, affected boundaries, existing tests, and stated acceptance
 criteria with independent judgment. Run the necessary builds, tests, lint, or

package/src/agents/reviewer/agent.json

@@ -1,6 +1,6 @@
 {
   "id": "reviewer",
   "name": "Reviewer",
-  "description": "Use after implementation to independently verify correctness, regressions, risks, and stated acceptance criteria before final reporting.",
+  "description": "Use once at the final check of non-trivial work: after the implementation is written and verified, before reporting completion, to independently verify correctness, regressions, risks, and acceptance criteria. Skip for low-difficulty work.",
   "entry": "AGENT.md"
 }