@onlooker-community/ecosystem 0.9.0 → 0.14.0

package/plugins/tribunal/scripts/lib/tribunal-verdict.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# Verdict persistence for Tribunal.
+#
+# Writes per-iteration artifacts under:
+#   $ONLOOKER_DIR/tribunal/<project-key>/<task_id>/iteration-<iteration_id>/
+#     actor.md
+#     jury.json
+#     verdicts/<judge_id>.json
+#     consensus.json
+#     dissent.json   (optional)
+#     meta.json
+#     gate.json
+#
+# Plus task-level files at <task_id>/{manifest,session-start,session-complete}.json.
+#
+# Requires tribunal-project-key.sh to be sourced.
+
+tribunal_storage_root() {
+	local base="${ONLOOKER_DIR:-$HOME/.onlooker}"
+	printf '%s/tribunal' "$base"
+}
+
+tribunal_project_dir() {
+	local key="$1"
+	printf '%s/%s' "$(tribunal_storage_root)" "$key"
+}
+
+tribunal_task_dir() {
+	local key="$1"
+	local task_id="$2"
+	printf '%s/%s' "$(tribunal_project_dir "$key")" "$task_id"
+}
+
+tribunal_iteration_dir() {
+	local key="$1"
+	local task_id="$2"
+	local iteration_id="$3"
+	printf '%s/iteration-%s' "$(tribunal_task_dir "$key" "$task_id")" "$iteration_id"
+}
+
+tribunal_init_task() {
+	local key="$1"
+	local task_id="$2"
+	[[ -z "$key" || -z "$task_id" ]] && return 1
+	mkdir -p "$(tribunal_task_dir "$key" "$task_id")" 2>/dev/null
+}
+
+tribunal_init_iteration() {
+	local key="$1"
+	local task_id="$2"
+	local iteration_id="$3"
+	[[ -z "$key" || -z "$task_id" || -z "$iteration_id" ]] && return 1
+	mkdir -p "$(tribunal_iteration_dir "$key" "$task_id" "$iteration_id")/verdicts" 2>/dev/null
+}
+
+# Write the project-level manifest (one per project key, refreshed each task).
+tribunal_write_project_manifest() {
+	local key="$1"
+	local remote_url="$2"
+	local repo_root="$3"
+	[[ -z "$key" ]] && return 1
+	mkdir -p "$(tribunal_project_dir "$key")" 2>/dev/null
+
+	local now
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	jq -n \
+		--arg key "$key" \
+		--arg remote "$remote_url" \
+		--arg root "$repo_root" \
+		--arg now "$now" \
+		'{
+			project_key: $key,
+			remote_url: (if $remote == "" then null else $remote end),
+			repo_root: (if $root == "" then null else $root end),
+			last_task_at: $now,
+			source: "local"
+		}' > "$(tribunal_project_dir "$key")/manifest.json"
+}
+
+# Write the per-task manifest with the active rubric snapshot.
+tribunal_write_task_manifest() {
+	local key="$1"
+	local task_id="$2"
+	local task_summary="$3"
+	local rubric_id="$4"
+	local rubric_json="$5"
+	[[ -z "$key" || -z "$task_id" ]] && return 1
+	tribunal_init_task "$key" "$task_id" || return 1
+
+	local now
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	jq -n \
+		--arg task_id "$task_id" \
+		--arg summary "$task_summary" \
+		--arg rubric_id "$rubric_id" \
+		--argjson rubric "$rubric_json" \
+		--arg now "$now" \
+		'{
+			task_id: $task_id,
+			task_summary: $summary,
+			rubric_id: $rubric_id,
+			rubric: $rubric,
+			started_at: $now
+		}' > "$(tribunal_task_dir "$key" "$task_id")/manifest.json"
+}
+
+# Append-time helpers for each per-iteration artifact. Each takes the full JSON
+# blob the caller wants persisted (typically the same payload it just emitted as
+# a canonical event).
+tribunal_write_actor_output() {
+	local key="$1" task_id="$2" iteration_id="$3" body="$4"
+	tribunal_init_iteration "$key" "$task_id" "$iteration_id" || return 1
+	printf '%s\n' "$body" > "$(tribunal_iteration_dir "$key" "$task_id" "$iteration_id")/actor.md"
+}
+
+tribunal_write_iteration_artifact() {
+	local key="$1" task_id="$2" iteration_id="$3" name="$4" json="$5"
+	tribunal_init_iteration "$key" "$task_id" "$iteration_id" || return 1
+	printf '%s\n' "$json" > "$(tribunal_iteration_dir "$key" "$task_id" "$iteration_id")/${name}.json"
+}
+
+tribunal_write_judge_verdict() {
+	local key="$1" task_id="$2" iteration_id="$3" judge_id="$4" verdict_json="$5"
+	tribunal_init_iteration "$key" "$task_id" "$iteration_id" || return 1
+	printf '%s\n' "$verdict_json" \
+		> "$(tribunal_iteration_dir "$key" "$task_id" "$iteration_id")/verdicts/${judge_id}.json"
+}

package/plugins/tribunal/skills/tribunal/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: tribunal
+description: Run a task under multi-agent quality gates. Spawns the tribunal-actor subagent, a jury of typed Judges, and a Meta-Judge; aggregates verdicts under a configurable gate policy; retries the Actor with critique on rejection until acceptance or max_iterations. Use when the user explicitly wraps a task with /tribunal, or wants stronger correctness/safety review than a single pass. Emits the full tribunal.* canonical event stream.
+---
+
+# Tribunal: Multi-Agent Execution with Quality Gates
+
+You are orchestrating a **Tribunal** evaluation loop. A user task gets wrapped in: **Actor → Jury → Meta-Judge → Gate**, retrying the Actor with feedback until the gate passes or `max_iterations` is reached.
+
+## Setup
+
+Before the loop, source the plugin's bash helpers and load config. Run this once at the start:
+
+```bash
+set -uo pipefail
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-config.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-rubric.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-jury.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-aggregate.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-gate.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-events.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-verdict.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-project-key.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-ulid.sh"
+
+tribunal_config_load "$(pwd)"
+tribunal_rubric_load "$(pwd)"
+```
+
+Parse the task description from the user's prompt arguments. If the user passed `--rubric=<id>`, use that; otherwise use `tribunal_rubric_default_id`.
+
+Resolve the active rubric with `tribunal_rubric_get "$rubric_id"`. Validate it with `tribunal_rubric_validate "$rubric"`. If validation fails, abort with `tribunal.session.complete` outcome `aborted` and tell the user why.
+
+## Per-task initialization
+
+Generate identifiers and persist task-level state:
+
+```bash
+task_id=$(tribunal_ulid)
+project_key=$(tribunal_project_key "$(pwd)")
+remote=$(tribunal_project_remote_url "$(pwd)")
+repo_root=$(tribunal_project_repo_root "$(pwd)")
+tribunal_write_project_manifest "$project_key" "$remote" "$repo_root"
+tribunal_write_task_manifest "$project_key" "$task_id" "$task_summary" "$rubric_id" "$rubric"
+```
+
+Emit `tribunal.session.start` with the resolved config (`judge_types`, `gate_policy`, `score_threshold`, `max_iterations`, model IDs).
+
+## The loop
+
+For `iteration_number` from `0` while `iteration_number < max_iterations`:
+
+1. **Iteration start.** Generate `iteration_id=$(tribunal_ulid)`. `trigger` is `"initial"` for n=0, `"gate_blocked"` for retries. Emit `tribunal.iteration.start`.
+
+2. **Actor.** Emit `tribunal.actor.start`. Use the Task tool to spawn `tribunal-actor` with:
+   - The task description.
+   - The rubric criteria (just `name` + `weight` + `min_pass`).
+   - On retries: a digest of the prior iteration's consensus, dissent (if any), and Meta-Judge override.
+
+   Capture the Actor's final output. Persist it: `tribunal_write_actor_output "$project_key" "$task_id" "$iteration_id" "$actor_output"`. Emit `tribunal.actor.complete` with `success: true` and the inferred `artifact_kind` (`file` / `patch` / `message` / `command`).
+
+3. **Empanel the jury.** Resolve the panel from configured types:
+   ```bash
+   types=$(tribunal_config_get_json '.tribunal.session.judge_types')
+   # Rubric may override:
+   rubric_types=$(printf '%s' "$rubric" | jq -c '.judge_types // empty')
+   [[ -n "$rubric_types" && "$rubric_types" != "null" ]] && types="$rubric_types"
+   jury=$(tribunal_jury_empanel "$types")
+   ```
+   Persist the jury (`tribunal_write_iteration_artifact ... jury ...`) and emit `tribunal.jury.empaneled` with the schema-shaped `judges[]` (`tribunal_jury_to_schema_judges "$jury"`).
+
+4. **Run each Judge.** For each entry in the jury panel:
+   - Emit `tribunal.judge.start` with `judge_id`, `judge_type`, `judge_model_id`.
+   - Spawn the judge subagent (`.subagent` field) with the Actor output + rubric.
+   - Parse the JSON object the judge returns. Augment it with `task_id`, `iteration_id`, `judge_id`, `judge_model_id` from the panel entry, and `judge_type` from the panel entry (canonical, overriding what the agent self-reported).
+   - Emit `tribunal.verdict` with that payload.
+   - Persist with `tribunal_write_judge_verdict`.
+
+   Collect the verdicts into a JSON array `verdicts`.
+
+5. **Aggregate + dissent.**
+   ```bash
+   method=$(printf '%s' "$rubric" | jq -r '.aggregation_method // "weighted_mean"')
+   threshold=$(printf '%s' "$rubric" | jq -r '.score_threshold // 0.75')
+   dissent_threshold=$(tribunal_config_get '.tribunal.session.dissent_threshold')
+   [[ -z "$dissent_threshold" ]] && dissent_threshold="0.25"
+
+   aggregated=$(tribunal_aggregate "$method" "$verdicts" "$rubric")
+   dissent=$(tribunal_disagreement "$verdicts")
+   ```
+   Build and emit `tribunal.consensus.reached`. If `dissent > dissent_threshold`, emit `tribunal.dissent.recorded` (set `resolution` to `null` for now — the Meta-Judge may set it on the next step via `override_recommendation`).
+
+6. **Meta-Judge.** Emit `tribunal.meta.start`. Spawn `tribunal-meta-judge` with the verdicts and the Actor output. Parse its JSON; augment with `task_id`, `iteration_id`, `meta_model_id`. Emit `tribunal.meta.complete`. Persist.
+
+7. **Gate.**
+   ```bash
+   policy=$(printf '%s' "$rubric" | jq -r '.gate_policy // "majority"')
+   gate=$(tribunal_gate_decide "$policy" "$verdicts" "$aggregated" "$threshold" "$meta" "$dissent" "$dissent_threshold")
+   ```
+   If `gate.passed == true`, emit `tribunal.gate.passed` with `final_score: aggregated` and break the loop with outcome `accepted`. Otherwise emit `tribunal.gate.blocked` with the `reason`, `will_retry: (iteration_number + 1 < max_iterations)`, and `retry_iteration_number` if retrying. Persist `gate.json` either way.
+
+   If blocking and retrying, build the retry digest (lowest-scoring criteria + meta override + dissent summary) and feed it into the next iteration's Actor prompt.
+
+## Termination
+
+When the loop exits:
+
+- `accepted` — gate passed.
+- `exhausted_iterations` — loop ran `max_iterations` without acceptance.
+- `aborted` — orchestrator caught an unrecoverable error (rubric validation failed, Actor subagent crashed twice, etc.). Set this explicitly when you catch errors; do not silently swallow.
+
+Emit `tribunal.session.complete` with `outcome`, `final_score`, `iterations_used`, `total_duration_ms`. Skip `total_cost_usd` in v0.1 — the runtime does not surface subagent costs to the orchestrator yet.
+
+## Summary to the user
+
+After emitting `session.complete`, render a compact markdown summary to the user:
+
+- Verdict (✓ accepted / ✗ rejected / ⏱ exhausted / ⚠ aborted) with final score.
+- Per-iteration table: iteration | per-judge scores | dissent | gate result.
+- Meta-Judge bias notes if any.
+- Path to the persisted artifacts (`~/.onlooker/tribunal/<key>/<task_id>/`).
+
+Keep the summary terse. The artifacts on disk are the long form.
+
+## Error handling
+
+- If a judge subagent fails to return parseable JSON, treat that judge as `score: 0, passed: false, confidence: 0` and surface the parse error in `feedback_summary`. Do not abort the iteration — let the gate decide.
+- If the Meta-Judge fails, default to `verdict_quality: "questionable", bias_detected: false` so the gate falls back to score-based logic.
+- If event emission fails (schema validation), keep going and write a warning to stderr. The persisted artifacts on disk are still trustworthy.

package/release-please-config.json

@@ -10,18 +10,56 @@
       "extra-files": [
         {
           "type": "json",
-          "path": "package.json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
+    "plugins/archivist": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "archivist",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
           "jsonpath": "$.version"
-        },
+        }
+      ]
+    },
+    "plugins/tribunal": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "tribunal",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
         {
           "type": "json",
           "path": ".claude-plugin/plugin.json",
           "jsonpath": "$.version"
-        },
+        }
+      ]
+    },
+    "plugins/echo": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "echo",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
         {
           "type": "json",
-          "path": ".claude-plugin/marketplace.json",
-          "jsonpath": "$.plugins[0].version"
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
         }
       ]
     }

package/scripts/coverage/bash-coverage.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// Bash "tested-functions ratio" heuristic.
+//
+// True bash line coverage (bashcov / kcov) is heavy and flaky in CI, so
+// instead we ask the cheaper question: "for every public function defined
+// in scripts/lib/, does at least one bats test reference it by name?". The
+// result is a per-file ratio plus a flat list of untested public functions.
+//
+// What counts as a "public" function:
+//   * defined with either `name() { ... }` or `function name { ... }`
+//   * name does NOT start with an underscore (those are private helpers and
+//     should be tested indirectly through their callers).
+//
+// What counts as a "reference" in tests:
+//   * the function name appears as a standalone word in any *.bats file
+//     (typical patterns: `run my_func ...`, `my_func "$arg"`, or sourced
+//     and called directly). False positives are possible — that's the cost
+//     of a heuristic — but the score is still useful as a regression gate
+//     and is calibrated against the noise floor.
+//
+// Flags:
+//   --json     emit structured JSON on stdout (default: human-readable)
+//   --root <p> override repo root
+//
+// Exit codes: always 0; this is an informational tool. Use --json to feed
+// into format-comment.mjs.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function findRepoRoot(start) {
+  let cur = resolve(start);
+  while (cur !== '/') {
+    try {
+      statSync(join(cur, '.claude-plugin', 'marketplace.json'));
+      return cur;
+    } catch {}
+    cur = dirname(cur);
+  }
+  throw new Error(`no repo root above ${start}`);
+}
+
+function parseArgs(argv) {
+  const out = { json: false, root: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--json') out.json = true;
+    else if (argv[i] === '--root') out.root = argv[++i];
+  }
+  return out;
+}
+
+function walk(dir, predicate) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    let items;
+    try {
+      items = readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const item of items) {
+      const p = join(cur, item.name);
+      if (item.isDirectory()) {
+        if (item.name === 'node_modules' || item.name === '.git') continue;
+        stack.push(p);
+      } else if (item.isFile() && predicate(p)) {
+        out.push(p);
+      }
+    }
+  }
+  return out.sort();
+}
+
+// Extract `name` from lines like `name() {`, `name () {`, or `function name`.
+// Skips lines indented (those are nested fns / non-top-level callbacks we
+// don't want to attribute to the file's public surface).
+function extractFunctions(content) {
+  const out = [];
+  const lines = content.split(/\r?\n/);
+  const def = /^(?:function\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*\(\s*\)\s*\{?/;
+  for (const line of lines) {
+    // Strict: must start at column 0 (no leading whitespace).
+    if (line.length === 0 || line[0] === ' ' || line[0] === '\t') continue;
+    const m = line.match(def);
+    if (!m) continue;
+    const name = m[1];
+    // Skip private helpers and bash keywords that look like fn names.
+    if (name.startsWith('_')) continue;
+    if (['if', 'while', 'for', 'case', 'then', 'do', 'else', 'fi', 'done'].includes(name)) continue;
+    out.push(name);
+  }
+  return [...new Set(out)];
+}
+
+function isReferenced(name, testsContent) {
+  // Look for the name as a standalone word (preceded/followed by non-word
+  // characters). This catches `run name`, `name "$x"`, `$( name )`, etc.
+  const rx = new RegExp(`(^|[^A-Za-z0-9_])${name}([^A-Za-z0-9_]|$)`);
+  return rx.test(testsContent);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const here = dirname(fileURLToPath(import.meta.url));
+  const root = args.root ? resolve(args.root) : findRepoRoot(here);
+
+  const libDirs = [join(root, 'scripts', 'lib'), join(root, 'plugins', 'archivist', 'scripts', 'lib')];
+  const libFiles = [];
+  for (const d of libDirs) {
+    try {
+      libFiles.push(...walk(d, (p) => p.endsWith('.sh')));
+    } catch {}
+  }
+
+  const testsDir = join(root, 'test', 'bats');
+  const testFiles = walk(testsDir, (p) => p.endsWith('.bats'));
+  const testsContent = testFiles.map((f) => readFileSync(f, 'utf8')).join('\n');
+
+  const perFile = [];
+  let totalFns = 0;
+  let totalTested = 0;
+  const untested = [];
+
+  for (const file of libFiles) {
+    const fns = extractFunctions(readFileSync(file, 'utf8'));
+    const tested = fns.filter((name) => isReferenced(name, testsContent));
+    const fileTotal = fns.length;
+    const fileTested = tested.length;
+    totalFns += fileTotal;
+    totalTested += fileTested;
+    const relpath = relative(root, file);
+    perFile.push({
+      file: relpath,
+      total: fileTotal,
+      tested: fileTested,
+      ratio: fileTotal === 0 ? 1 : fileTested / fileTotal,
+      untested: fns.filter((n) => !tested.includes(n)),
+    });
+    for (const u of fns.filter((n) => !tested.includes(n))) {
+      untested.push({ file: relpath, name: u });
+    }
+  }
+
+  const overallRatio = totalFns === 0 ? 1 : totalTested / totalFns;
+  const report = {
+    overall: { total: totalFns, tested: totalTested, ratio: overallRatio },
+    files: perFile,
+    untested,
+  };
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`bash function coverage: ${totalTested}/${totalFns} (${(overallRatio * 100).toFixed(1)}%)\n\n`);
+  for (const f of perFile) {
+    const pct = (f.ratio * 100).toFixed(0).padStart(3);
+    process.stdout.write(`  ${pct}%  ${f.tested}/${f.total}  ${f.file}\n`);
+    for (const u of f.untested) {
+      process.stdout.write(`         - ${u}\n`);
+    }
+  }
+}
+
+main();

package/scripts/coverage/format-comment.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Combine node coverage + bash function coverage into a single markdown
+// comment suitable for posting on a pull request via `gh pr comment`.
+//
+// Reads each report from a file path (so the caller can capture stdout
+// once and pass the file through). Emits markdown on stdout.
+//
+// Usage:
+//   format-comment.mjs --node coverage-node.json --bash coverage-bash.json
+//
+// Each file should be JSON produced by the matching script's --json mode.
+
+import { readFileSync } from 'node:fs';
+
+function parseArgs(argv) {
+  const out = { node: null, bash: null, sha: process.env.GITHUB_SHA ?? null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--node') out.node = argv[++i];
+    else if (argv[i] === '--bash') out.bash = argv[++i];
+    else if (argv[i] === '--sha') out.sha = argv[++i];
+  }
+  return out;
+}
+
+function pct(n) {
+  if (typeof n !== 'number' || Number.isNaN(n)) return '—';
+  return `${n.toFixed(1)}%`;
+}
+
+function badge(value, kind) {
+  if (typeof value !== 'number') return '⚪';
+  if (kind === 'bash') {
+    if (value >= 70) return '🟢';
+    if (value >= 50) return '🟡';
+    return '🔴';
+  }
+  if (value >= 80) return '🟢';
+  if (value >= 60) return '🟡';
+  return '🔴';
+}
+
+function nodeSection(report) {
+  if (!report?.overall) {
+    return '_No node coverage report._';
+  }
+  const o = report.overall;
+  const lines = [
+    `**Overall:** ${badge(o.line, 'node')} ${pct(o.line)} lines · ${pct(o.branch)} branches · ${pct(o.funcs)} functions`,
+    '',
+    '| file | line | branch | funcs |',
+    '| --- | ---: | ---: | ---: |',
+  ];
+  for (const f of report.files) {
+    lines.push(`| \`${f.file}\` | ${pct(f.line)} | ${pct(f.branch)} | ${pct(f.funcs)} |`);
+  }
+  return lines.join('\n');
+}
+
+function bashSection(report) {
+  if (!report?.overall) {
+    return '_No bash function coverage report._';
+  }
+  const o = report.overall;
+  const overallPct = o.ratio * 100;
+  const lines = [
+    `**Overall:** ${badge(overallPct, 'bash')} ${o.tested}/${o.total} public functions exercised by bats (${pct(overallPct)})`,
+    '',
+    '| file | tested / total | ratio |',
+    '| --- | ---: | ---: |',
+  ];
+  for (const f of report.files) {
+    if (f.total === 0) continue;
+    lines.push(`| \`${f.file}\` | ${f.tested} / ${f.total} | ${pct(f.ratio * 100)} |`);
+  }
+  if (report.untested.length > 0) {
+    lines.push('');
+    lines.push('<details><summary>Untested public functions</summary>');
+    lines.push('');
+    for (const u of report.untested) {
+      lines.push(`- \`${u.file}\` — \`${u.name}\``);
+    }
+    lines.push('');
+    lines.push('</details>');
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  let nodeReport = null;
+  let bashReport = null;
+  if (args.node) nodeReport = JSON.parse(readFileSync(args.node, 'utf8'));
+  if (args.bash) bashReport = JSON.parse(readFileSync(args.bash, 'utf8'));
+
+  const out = [];
+  out.push('<!-- onlooker-coverage-comment -->');
+  out.push('## Coverage');
+  out.push('');
+  if (args.sha) {
+    out.push(`Commit: \`${args.sha.slice(0, 12)}\``);
+    out.push('');
+  }
+  out.push('### Node (.mjs)');
+  out.push('');
+  out.push(nodeSection(nodeReport));
+  out.push('');
+  out.push('### Bash (function-reference heuristic)');
+  out.push('');
+  out.push(bashSection(bashReport));
+  out.push('');
+  out.push('---');
+  out.push('');
+  out.push(
+    'Bash numbers are a heuristic — they count public functions referenced by bats tests, not real line coverage. A red score points to public helpers nobody directly exercises.',
+  );
+
+  process.stdout.write(`${out.join('\n')}\n`);
+}
+
+main();