canary-test-cli 7.1.0 → 7.2.0

package/agents/skills/claude-code/canary-setup-harness/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: canary-setup-harness
+description: >
+  Configure the Harness Engineering guardrails in a new Canary project (or a
+  fork) — installs the harness CLI, initialises `harness.config.json`, wires
+  up the five required CI workflows, generates the initial security ledger,
+  and verifies all gates pass on a clean repository. Use for "set up harness
+  for this project", "onboard this repo with harness", "install the harness
+  CLI", "configure the CI gates", or when a fork has drifted from the
+  harness config and needs re-alignment. Not for day-to-day harness updates,
+  adding a single new gate to an existing config, or troubleshooting a
+  failing CI check.
+---
+
+# Canary: Setup Harness
+
+> Configure the Harness Engineering guardrails in a new Canary
+> project (or a fork). Installs the harness CLI, initialises the
+> config, wires up CI workflows, and verifies all gates pass on
+> a clean repository.
+
+## When to Use
+
+- When setting up Canary (or a fork) in a new repository for
+  the first time
+- When onboarding a new project that wants Canary's CI gate
+  structure
+- When a fork has drifted from the harness config and needs
+  to be re-aligned
+- NOT for day-to-day harness updates — use the harness CLI's
+  own update flow for that
+- NOT for adding a single new gate to an existing config —
+  edit `harness.config.json` directly
+- NOT for troubleshooting a failing CI check — see the
+  [Understanding the Harness][harness-wiki] wiki page
+
+[harness-wiki]: ../../../../docs/wiki/Understanding-the-Harness.md
+
+## Process
+
+### Phase 1: PREREQUISITES — Confirm the Environment
+
+1. **Verify Node.js is available** (harness CLI requires it):
+
+   ```bash
+   node --version
+   ```
+
+   Version 18 or later is required.
+
+2. **Verify Python is available** (security ledger script):
+
+   ```bash
+   python3 --version
+   ```
+
+   Version 3.11 or later is required.
+
+3. **Confirm the repo has a `harness.config.json`** at the
+   root. If it doesn't, the harness is not yet configured —
+   continue to Phase 2. If it does, validate it first:
+
+   ```bash
+   npx --yes -p @harness-engineering/cli harness validate
+   ```
+
+   If validation passes, the harness is already set up. Stop
+   here unless re-alignment is the goal.
+
+### Phase 2: INSTALL — Run the Harness Init
+
+1. **Initialise the harness** from the repo root:
+
+   ```bash
+   npx --yes -p @harness-engineering/cli harness init
+   ```
+
+   This creates `harness.config.json` with default gates and
+   generates the `.harness/` hooks directory.
+
+2. **Review the generated `harness.config.json`.** The defaults
+   are sensible, but confirm:
+
+   - `layers` matches the project's actual package structure
+     (for Canary: `llm`, `core`, `cli`)
+   - `entrypoints` lists the correct top-level packages
+   - `telemetry` and `adoption` settings match team policy
+
+3. **Inspect `.harness/hooks/`.** The hooks directory contains
+   scripts that run locally on git events. Review each file
+   briefly — they should not require network access outside
+   the harness telemetry endpoint.
+
+### Phase 3: CONFIGURE — Wire Up CI Workflows
+
+1. **Check which workflows already exist:**
+
+   ```bash
+   ls .github/workflows/
+   ```
+
+2. **Required workflows for a full harness setup.** Each
+   should exist as a `.yml` file in `.github/workflows/`:
+
+   - `harness.yml` — core phase-gate checks
+   - `harness-architecture.yml` — layer dependency validation
+   - `harness-quality.yml` — quality and integrity checks
+   - `harness-security.yml` — security scan + ledger refresh
+   - `docs-lint.yml` — markdown formatting enforcement
+
+   If any are missing, copy them from an upstream Canary
+   reference install or generate them:
+
+   ```bash
+   npx --yes -p @harness-engineering/cli harness \
+     generate-workflows
+   ```
+
+3. **Confirm `harness-security.yml` refreshes the ledger.**
+   The final steps of the security job must run the ledger
+   script and commit if changed. Without this, the security
+   ledger goes stale and the Quality gate fails.
+
+4. **Confirm `docs-lint.yml` covers all doc paths.** The
+   workflow's `paths` filter should include:
+
+   - `docs/**`
+   - `agents/**`
+   - `AGENTS.md`
+
+5. **Set required permissions.** Workflows that commit
+   back to the repository need `contents: write`:
+
+   ```yaml
+   permissions:
+     contents: write
+   ```
+
+   This applies to `harness-security.yml` at minimum.
+
+### Phase 4: BASELINE — Generate Initial Artifacts
+
+1. **Run the security scan to create the initial ledger:**
+
+   ```bash
+   npx --yes -p @harness-engineering/cli harness check-security
+   python3 scripts/security_ledger.py
+   ```
+
+2. **Commit the generated baseline files:**
+
+   ```bash
+   git add harness.config.json .harness/ \
+     .harness/security/timeline.json \
+     docs/SECURITY_LEDGER.md
+   git commit -m "chore: initialise harness configuration"
+   ```
+
+3. **Push and confirm all CI gates pass** on the resulting
+   commit before calling setup complete.
+
+### Phase 5: VERIFY — Confirm All Gates Pass
+
+1. **Open a pull request** (or push to the configured branch)
+   to trigger CI.
+2. **Check each workflow:**
+
+   - Architecture Enforcer: green
+   - Quality & Integrity: green
+   - Docs Lint: green
+   - Security Reviewer: green (ledger will be auto-refreshed
+     by the workflow on first scan)
+
+3. **If any gate fails:** Read the error, fix the root cause,
+   push again. Do not suppress gates or skip hooks to make CI
+   green — fix the actual issue.
+
+4. **Log to `docs/CANARY_STATE.md`** that harness setup was
+   completed, including the date and commit SHA.
+
+## Canary Integration
+
+- **`harness.config.json`** — Layer rules, entrypoints,
+  telemetry/adoption settings. Source of truth for all
+  harness gates.
+- **`.harness/hooks/`** — Local git hooks generated during
+  `harness init`. Committed so all contributors share them.
+- **`.github/workflows/`** — CI workflows that run the harness
+  gates on every PR.
+- **`scripts/security_ledger.py`** — Regenerates
+  `docs/SECURITY_LEDGER.md` from `.harness/security/timeline.json`.
+  Must be run after every security scan.
+- **`docs/CANARY_STATE.md`** — Project ledger. Log setup
+  completion here.
+
+## Success Criteria
+
+- `harness validate` exits cleanly with no violations
+- All five CI workflows exist and pass on a clean push
+- The security ledger (`docs/SECURITY_LEDGER.md`) exists and
+  is not stale
+- `.harness/hooks/` is committed and present in the repo
+- A setup entry exists in `docs/CANARY_STATE.md`
+
+## Rationalizations to Reject
+
+| Rationalization | Why It Is Wrong |
+| --- | --- |
+| "CI is red but the code is fine, I'll add `--no-verify`" | Skipping hooks defeats the entire purpose of the harness. Fix the root cause. |
+| "I'll set up the workflows later — the config is good enough" | A config with no CI enforcement is ornamental. The gates only protect the team when they run on every PR. |
+| "The security ledger step seems redundant — the scan already ran" | The scan writes to a JSON timeline; the ledger script produces the human-readable summary. Both are needed. |
+| "I'll commit the hooks directory but not review the files" | Hook files run on every developer's machine. Review them before committing — they're executable scripts. |
+
+## Examples
+
+### Example: Fresh install on a new fork
+
+**Scenario:** `cap-canary` is a new fork of `canary-test-ai-agent`.
+It has no harness config yet.
+
+**Steps:**
+
+1. Clone the fork and run `harness init`.
+2. Review `harness.config.json` — layers match `llm`, `core`,
+   `cli`. Entrypoints set to `agent`.
+3. Copy the five CI workflow files from upstream.
+4. Run the security scan, generate the baseline ledger, commit.
+5. Push. All five gates pass. Log to `CANARY_STATE.md`.
+
+### Example: Re-aligning a drift after harness update
+
+**Scenario:** A harness CLI update added a new hook file to
+`.harness/hooks/`. The local copy doesn't have it.
+
+**Steps:**
+
+1. Run `npx --yes -p @harness-engineering/cli harness update`.
+2. Review the diff in `.harness/hooks/` — confirm the new
+   file is expected.
+3. Stage and commit the new hook file.
+4. Push. CI passes.
+
+## Escalation
+
+- **When `harness init` fails or produces unexpected output:**
+  Check the harness CLI version. A major version mismatch
+  between the CLI and the `harness.config.json` schema is the
+  most common cause.
+- **When a CI gate fails after a clean setup:** Don't assume
+  the setup is wrong. Read the failure output — it often points
+  to a pre-existing issue in the repo that the harness is now
+  surfacing for the first time.
+- **When a fork needs company-specific config injected:**
+  Set up the base harness using this skill, then apply the
+  company-specific overrides as a follow-up commit. Don't
+  mix upstream setup with fork-specific changes.
+- **When the wiki-sync workflow fails on first run:** The
+  GitHub wiki is a separate git repository that GitHub creates
+  lazily — it doesn't exist until someone saves the first page
+  via the UI. Go to the repo → Wiki → create any placeholder
+  page. After that, the wiki-sync workflow handles the wiki
+  repo correctly on all subsequent runs. Each new fork needs
+  this one-time step.

package/agents/skills/claude-code/canary-shadow/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: canary-shadow
+description: >
+  Differential ("shadow") parity testing — run the SAME invocation through a
+  baseline and a candidate, normalize away irrelevant noise (ANSI, timestamps,
+  temp paths, version banners, SHAs), diff, and flag divergences. Use to prove a
+  behavior-preserving change actually preserves behavior: a language/framework
+  port (Python→TS, typer→commander), a skill rewrite (old vs new), a refactor
+  claimed equivalent, or "does this still match the old CLI?". Runs both sides
+  live, so it needs no golden capture — just the two versions. NOT a correctness
+  oracle: it proves the two AGREE, not that either is right, so pair it with a
+  few asserted cases.
+cli: scripts/cli.mjs
+requires: [node>=20]
+---
+
+# Canary: Shadow (differential parity testing)
+
+> Run one invocation through two implementations, normalize the noise, diff the
+> rest. Every un-accepted divergence is a behavior change to explain or fix.
+
+## When to Use
+
+- **Ports / rewrites** where output should be identical: Python→TS, a BoP skill
+  re-port, typer→commander, one engine replacing another. (This is exactly how
+  the v6 cutover was validated: run `canary <cmd>` through the TS engine AND the
+  Python reference, diff. It surfaced a divergence the unit tests + golden suite
+  missed — Python's `rich` console renders the ticket-marker hint
+  `# canary:ticket:` as `# canary🎫` via emoji-shortcode substitution, mangling
+  a hint the parser can't match; the TS port printed the literal, correct
+  marker. A console-rendering artifact only a live side-by-side run exposes.)
+- **Skill changes** — old skill vs new skill on the same inputs: "prove the
+  rewrite is equivalent."
+- **Refactors** asserted to be behavior-preserving.
+- **Framework / dependency swaps** where the observable surface should not move.
+- NOT for greenfield behavior (nothing to compare against) — use asserted tests.
+- NOT as a sole correctness check — see the caveat at the bottom.
+
+## The idea (differential / shadow testing)
+
+For each case, run the SAME arguments through a `baseline` command and a
+`candidate` command, capture `{exitCode, stdout, stderr}`, **normalize** both,
+and diff. Identical (post-normalization) ⇒ `ok`. Different ⇒ `DIVERGE` — a real
+behavior change, unless it's a _documented, intentional_ difference recorded in
+the accepted-divergence allowlist.
+
+The value is not the runner (two `spawn`s and a diff) — it's the two disciplines
+below.
+
+### 1. The normalization ruleset (get this right, or drown)
+
+Output has meaningful content and irrelevant noise. Normalize the noise; keep
+everything else. Default masks (see `scripts/cli.mjs`): ANSI SGR codes, ISO
+timestamps, temp paths (`/tmp`, `/var/folders`, `/private`), version banners
+(`vX.Y.Z[-rc.N]`), commit SHAs, run-ids.
+
+- **Under-normalize** and every run is a wall of false DIVERGE (a timestamp, a
+  temp dir) — you stop reading them.
+- **Over-normalize** and you mask a real bug (don't blanket-strip numbers if the
+  command emits counts/scores that matter).
+- Make masking **visible**: the runner reports what each mask touched, so a
+  reviewer can see a real difference wasn't hidden. Tune masks per project in
+  the cases file's `normalize` list, don't hardcode.
+
+### 2. The accepted-divergence allowlist
+
+Some differences are intentional and permanent (e.g. Python `rich` soft-wraps
+prose at 80 cols; a TS port emits it unwrapped — same content, different line
+breaks). Record each in the cases file with a **reason**, keyed by case label.
+This is the differential-test analog of `// harness-ignore`: an allowlisted
+DIVERGE is reported as `accept` (with its reason), never as a failure, and a NEW
+divergence still fails loudly. Review the allowlist like code — an entry with no
+reason, or one that quietly grows, is a smell.
+
+## Process
+
+### Phase 1: SCOPE — define baseline, candidate, and cases
+
+1. Identify the two implementations and how to invoke each (argv-preserving):
+   `baseline` = the trusted side (old skill, Python reference, prior version),
+   `candidate` = the new side.
+2. Enumerate cases that cover the observable surface: the happy paths, the JSON
+   contracts, the error/exit-code paths (a good differential run checks exit
+   codes AND stdout), and any command that needs a fixture (a sample file, a
+   temp project). Prefer read-only/deterministic cases first; give
+   state-changing ones (`init`, `migrate`) an isolated `cwd`.
+
+### Phase 2: RUN — cycle until clean
+
+1. Write a cases file (see `scripts/cases.example.json`) and run:
+   `node scripts/cli.mjs --cases <file>` (or via the skill `cli`). It prints
+   `ok` / `DIVERGE` / `accept` per case and a summary; exit is non-zero if any
+   un-accepted divergence remains.
+2. For each DIVERGE: read the diff. Decide — **bug** (fix the candidate),
+   **noise** (add/adjust a normalize rule), or **intentional** (add an allowlist
+   entry WITH a reason). Re-run. Iterate in cycles until the only remaining
+   divergences are `accept`ed.
+3. Do multiple cycles broadening coverage (add sub-commands, more fixtures,
+   adversarial inputs) — the first cycle finds the obvious breaks; the tail
+   finds the subtle ones.
+
+### Phase 3: LOCK — keep it honest
+
+1. Commit the cases file + allowlist alongside the change so the parity contract
+   is reviewable and re-runnable in CI.
+2. Add a handful of **asserted** cases (expected exact output/exit for a few
+   invocations) so the suite also catches "both sides are wrong the same way."
+
+## Invocation
+
+```bash
+# Usage, flags, and the cases-file contract (exits 0):
+canary skills run canary-shadow -- --help
+```
+
+A run needs a cases file, so the shape below is illustrative — copy
+`scripts/cases.example.json`, point it at your two implementations, and
+substitute the path:
+
+<!-- canary:illustrative -->
+
+```bash
+canary skills run canary-shadow -- --cases <cases.json>
+```
+
+## Caveat — agreement is not correctness
+
+Differential testing proves the two implementations AGREE. If the baseline has a
+bug the candidate faithfully reproduces, both pass. So it is a powerful
+regression net, not a correctness oracle — always pair it with a few asserted
+cases and human review of the allowlist.

package/agents/skills/claude-code/canary-shadow/scripts/cases.example.json

@@ -0,0 +1,32 @@
+{
+  "//": "Example shadow-parity config: the released CLI (baseline) vs the local build (candidate) — does this branch still agree with what users have? Copy, point baseline/candidate at your two implementations, and edit `cases`. Run: node cli.mjs --cases cases.example.json",
+  "baseline": ["npx", "--yes", "canary-test-cli@6.6.0"],
+  "candidate": ["node", "ts/bin/canary.js"],
+  "env": { "NO_COLOR": "1" },
+  "normalize": ["ansi", "version", "timestamp", "tmppath", "sha"],
+  "accept": {
+    "skills list": "The released build soft-wraps long skill descriptions at 80 cols; the local build emits them unwrapped. Same content + names, different line breaks — a documented, intentional presentation deviation, not a contract."
+  },
+  "cases": [
+    { "label": "frameworks --json", "argv": ["frameworks", "--json"] },
+    { "label": "frameworks", "argv": ["frameworks"] },
+    {
+      "label": "recommend e2e --json",
+      "argv": ["recommend", "test a login form", "--json"]
+    },
+    { "label": "recommend prose", "argv": ["recommend", "test a login form"] },
+    { "label": "skills list", "argv": ["skills", "list"] },
+    {
+      "label": "bad: unknown option (exit 2)",
+      "argv": ["frameworks", "--nope"]
+    },
+    { "label": "bad: missing arg (exit 2)", "argv": ["recommend"] },
+    { "label": "bad: unknown command (exit 2)", "argv": ["frobnicate"] },
+    { "label": "analyze flaky --json", "argv": ["analyze", "flaky", "--json"] },
+    {
+      "label": "init playwright (isolated cwd)",
+      "argv": ["init", "playwright"],
+      "isolate": true
+    }
+  ]
+}

package/agents/skills/claude-code/canary-shadow/scripts/cli.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// canary-shadow — differential ("shadow") parity runner.
+//
+// Runs each case's argv through a `baseline` and a `candidate` command,
+// normalizes away irrelevant noise, and diffs exit code + stdout. Prints
+// ok / accept / DIVERGE per case; exits non-zero if any un-accepted divergence
+// remains. See ../SKILL.md for the methodology and cases.example.json for the
+// config shape.
+//
+// Usage: node cli.mjs --cases <cases.json> [--verbose]
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  createParser,
+  formatUsageError,
+  EXIT_USAGE,
+} from '../../../lib/parse-args.mjs';
+
+const USAGE =
+  'usage: canary-shadow [-h] --cases PATH [--verbose]\n' +
+  '\n' +
+  'Run each case through a baseline and a candidate command, normalize away\n' +
+  'irrelevant noise, and diff exit code + stdout.\n' +
+  '\n' +
+  'options:\n' +
+  '  -h, --help    show this help message and exit\n' +
+  '  --cases PATH  cases file describing baseline, candidate, and cases\n' +
+  '  --verbose     print a line per matching case, not just divergences';
+
+/**
+ * canary-shadow shipped BEFORE the family had a shared contract, and it showed:
+ * no `--help`, no unknown-flag rejection, and a usage line naming `cli.mjs`
+ * rather than the skill. Nobody noticed, because there was nothing to violate
+ * (#479).
+ */
+export const CLI_SPEC = {
+  prog: 'canary-shadow',
+  booleans: { '--verbose': 'verbose' },
+  values: { '--cases': { key: 'cases' } },
+  required: ['--cases'],
+};
+
+const parseArgs = createParser(CLI_SPEC);
+
+// --- built-in normalization masks (name -> {re, replace}). Each records
+// whether it fired so the reviewer can see what was hidden. Extend/override per
+// project via the cases file's `normalize` list. ---
+const MASKS = {
+  ansi: { re: /\x1b\[[0-9;]*m/g, replace: '' },
+  version: { re: /v\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?/g, replace: 'vX' },
+  timestamp: {
+    re: /\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?/g,
+    replace: 'TS',
+  },
+  tmppath: { re: /(?:\/private)?\/(?:var|tmp)\/[^\s"']+/g, replace: 'TMP' },
+  sha: { re: /\b[0-9a-f]{7,40}\b/g, replace: 'SHA' },
+  runid: { re: /\b(?:run|job)[-_]?\d{3,}\b/gi, replace: 'RUNID' },
+};
+const DEFAULT_MASKS = ['ansi', 'version', 'timestamp', 'tmppath', 'sha'];
+
+function buildMasks(spec) {
+  // spec: array of built-in names and/or {name, pattern, flags?, replace}
+  const list = [];
+  for (const m of spec ?? DEFAULT_MASKS) {
+    if (typeof m === 'string') {
+      if (!MASKS[m]) throw new Error(`unknown built-in mask: ${m}`);
+      list.push({ name: m, ...MASKS[m] });
+    } else {
+      list.push({
+        name: m.name ?? m.pattern,
+        re: new RegExp(m.pattern, m.flags ?? 'g'),
+        replace: m.replace ?? '',
+      });
+    }
+  }
+  return list;
+}
+
+function normalize(text, masks, fired) {
+  let out = text;
+  for (const m of masks) {
+    if (m.re.test(out)) fired.add(m.name);
+    m.re.lastIndex = 0;
+    out = out.replace(m.re, m.replace);
+  }
+  return out.replace(/[ \t]+$/gm, '').trim();
+}
+
+function run(cmd, argv, cwd, env) {
+  const r = spawnSync(cmd[0], [...cmd.slice(1), ...argv], {
+    cwd,
+    env: { ...process.env, NO_COLOR: '1', ...env },
+    encoding: 'utf-8',
+    maxBuffer: Infinity,
+    timeout: 120_000,
+  });
+  return {
+    code: r.status ?? 1,
+    stdout: r.stdout ?? '',
+    stderr: r.stderr ?? '',
+  };
+}
+
+function unifiedDiff(a, b, max = 30) {
+  const A = a.split('\n');
+  const B = b.split('\n');
+  // minimal LCS-free line diff: good enough for review, keeps the runner small.
+  const out = [];
+  const bSet = new Set(B);
+  const aSet = new Set(A);
+  for (const line of A) if (!bSet.has(line)) out.push('- ' + line);
+  for (const line of B) if (!aSet.has(line)) out.push('+ ' + line);
+  return out.slice(0, max);
+}
+
+export function main(argv = []) {
+  const { opts, help, error } = parseArgs(argv);
+
+  if (help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (error) {
+    console.error(formatUsageError(CLI_SPEC.prog, error));
+    return EXIT_USAGE;
+  }
+
+  const { cases: casesPath, verbose } = opts;
+  const cfg = JSON.parse(readFileSync(casesPath, 'utf-8'));
+  const masks = buildMasks(cfg.normalize);
+  // Null-prototype: `accept` comes straight from JSON, so on a plain object a
+  // case labelled `toString` resolved to Object.prototype.toString and was
+  // reported `accept` instead of DIVERGE -- a parity tool silently suppressing
+  // a parity failure, which is the worst place in the family for this bug to
+  // have landed (#479).
+  const accept = Object.assign(Object.create(null), cfg.accept ?? {});
+  const fired = new Set();
+
+  let ok = 0;
+  let accepted = 0;
+  let diverged = 0;
+  for (const c of cfg.cases) {
+    let cwd = cfg.cwd;
+    let tmp;
+    if (c.isolate) {
+      tmp = mkdtempSync(join(tmpdir(), 'shadow-'));
+      cwd = tmp;
+    }
+    try {
+      const base = run(cfg.baseline, c.argv, cwd, cfg.env);
+      const cand = run(cfg.candidate, c.argv, cwd, cfg.env);
+      const bOut = normalize(base.stdout, masks, fired);
+      const cOut = normalize(cand.stdout, masks, fired);
+      const match = base.code === cand.code && bOut === cOut;
+      if (match) {
+        ok++;
+        if (verbose)
+          process.stdout.write(`ok     ${c.label}  (exit ${base.code})\n`);
+      } else if (accept[c.label]) {
+        accepted++;
+        process.stdout.write(`accept ${c.label}  — ${accept[c.label]}\n`);
+      } else {
+        diverged++;
+        process.stdout.write(
+          `DIVERGE ${c.label}  (exit base=${base.code} cand=${cand.code})\n`,
+        );
+        if (base.code !== cand.code)
+          process.stdout.write(
+            `        exit differs: base=${base.code} cand=${cand.code}\n`,
+          );
+        for (const line of unifiedDiff(bOut, cOut))
+          process.stdout.write('        ' + line + '\n');
+      }
+    } finally {
+      if (tmp) rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+  process.stdout.write(
+    `\n=== ${ok} ok, ${accepted} accepted, ${diverged} DIVERGE ` +
+      `(${cfg.cases.length} cases) — masks fired: ${[...fired].join(', ') || 'none'} ===\n`,
+  );
+  return diverged > 0 ? 1 : 0;
+}
+
+// Direct execution (the skill runner execs this file via its shebang).
+//
+// `process.exitCode`, not `process.exit()`: a large `--json` payload exceeds
+// the pipe buffer, and `process.exit` tears the process down mid-write, leaving
+// truncated JSON that still exits 0 (#791).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exitCode = main(process.argv.slice(2));
+}