lithermes-ai 0.5.0

package/assets/lithermes-plugin/skills/start-work/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: start-work
+description: Hermes-native plan executor for /start-work — resume from durable run state, then drive every plan checkbox through test + manual-QA + cleanup gates with independent verification.
+---
+
+# LitHermes Start-Work
+
+> **Hermes-native overrides (authoritative — read first).** Hermes has **no
+> model-facing goal tools**: do **not** call `create_goal`, `get_goal`, or
+> `update_goal` (they do not exist). LitHermes binds the native standing `/goal`
+> via the session goal manager; track success criteria and evidence with the
+> durable LitHermes goal tools (`goal_set`, `goal_add_criterion`, `goal_evidence`,
+> `goal_criterion_status`, `goal_steer`, `goal_checkpoint`, `goal_complete`) and
+> inspect with `hermes lithermes goal status`. Wherever legacy docs say "Call
+> `create_goal`" or "open a `# Goal` block", treat the goal as already bound and
+> use `goal_set` for the durable criteria layer. To run a reviewer or worker lane,
+> use the native **`delegate_task`** tool — `tasks:[{goal, context, toolsets?, role?}]`
+> for a parallel batch, parent blocks until all children stop. No spawn_agent,
+> no named-agent registry, no per-child model selection.
+
+This skill governs all `/start-work` invocations in Hermes. It resolves a plan
+file (`plans/<slug>.md`), opens or resumes a durable run, and drives every
+top-level checkbox to completion through strict gates. The skill never re-plans
+from scratch mid-run; all recovery is from durable artifacts.
+
+---
+
+## When this skill fires
+
+The trigger is any of:
+
+- `/start-work <slug>` — resolve `plans/<slug>.md`, open a new run.
+- `/start-work <slug> --resume` — locate the most recent run for `<slug>` under
+  `.hermes/lithermes/runs/` and resume from where `state.json` says.
+- `/start-work` with no slug but a one-liner brief supplied — bootstrap a plan
+  first (see §0 below), then open the run.
+
+---
+
+## §0 — No-plan bootstrap (only when no plan file exists)
+
+If `/start-work` was given a brief but `plans/<slug>.md` does not yet exist:
+
+1. Derive a slug from the brief (kebab-case, ≤ 40 chars).
+2. Write `plans/<slug>.md` with:
+   - A one-line **Goal** heading.
+   - A **Tasks** section: one `- [ ] T-NNN | <imperative verb phrase>` line per
+     deliverable, ordered by dependency.
+   - A **Success Criteria** section: one machine-parseable row per criterion:
+     `- [ ] C-NNN | channel: <http|tmux|browser|computer> | test: <file::id> | scenario: <one-line>`
+3. Then proceed to §1 as if the plan existed from the start.
+
+The brief is the contract. Do not expand scope beyond it.
+
+---
+
+## §1 — Resume first (MANDATORY — never skip)
+
+Before touching any file or running any command, re-read the durable run artifacts
+in this order:
+
+1. `state.json` — identifies the active run ID, the last completed checkbox index,
+   and any in-progress task that was interrupted.
+2. `notepad.md` — your working memory from prior turns; surface the `## Now` and
+   `## Todo` sections.
+3. `ledger.jsonl` — append-only event log; scan for `task_completed` entries to
+   confirm which checkboxes are truly done.
+4. The plan file (`plans/<slug>.md`) — count remaining unchecked `- [ ]` lines to
+   set the loop boundary.
+
+All four reads happen before any other action. If an interrupted task is recorded
+in `state.json`, resume it from the last safe checkpoint — do not repeat gates
+that `ledger.jsonl` already records as passed. Do not re-read the brief and
+re-plan. Do not ask the user what to do next unless the run directory is missing
+entirely (no prior run exists).
+
+Run state and evidence live under:
+
+```
+.hermes/lithermes/runs/<run-id>/
+  state.json      ← active checkbox index, interrupt record
+  notepad.md      ← working memory (append-only)
+  ledger.jsonl    ← event log (append-only)
+  evidence/       ← artifact files captured during QA gates
+```
+
+---
+
+## §2 — Per-checkbox execution loop
+
+For each top-level `- [ ] T-NNN | …` in the plan, run all five gates **in order**
+before flipping the checkbox. Gates are not optional and not reorderable.
+
+### Gate A — Plan reread
+
+Re-read the task row and any referenced sections in the plan. State in the notepad:
+
+- The task's exact intent (one sentence).
+- Which Success Criteria rows (`C-NNN`) it advances.
+- Any files, APIs, or boundaries named in the plan.
+
+### Gate B — Failing test first (RED)
+
+Write the automated test **before** any production code. The test file and test ID
+must match the `test:` field of the relevant `C-NNN` row(s). Run the test. Capture
+the exact assertion message that proves it fails for the right reason — not a syntax
+error, not a missing import, not a crash before the assertion. Paste the RED output
+into `notepad.md`.
+
+No production code may be written until RED is confirmed and recorded.
+
+### Gate C — Smallest green change (GREEN)
+
+Write the minimum production change that flips RED → GREEN. Re-run the test.
+Capture the GREEN output. If making GREEN required more than roughly 20 lines of
+production change, the test was too coarse — split the test and re-run from Gate B.
+
+Run LSP diagnostics on every modified file. Zero errors allowed before proceeding.
+
+### Gate D — Manual-QA channel scenario (YOU EXECUTE — NO STUBS)
+
+Identify the `channel:` value for the relevant `C-NNN` row and run the corresponding
+scenario yourself. The full test suite being green is **never** a substitute for
+this gate. "Should work" and "looks correct" are not evidence.
+
+**Channel table:**
+
+| Channel | What to do | Artifact |
+|---------|-----------|---------|
+| `http` | Hit the live endpoint with `curl -i`; capture status line + headers + body. | curl transcript |
+| `tmux` | `tmux new-session -d -s sw-qa-<criterion>`, drive with `send-keys`, dump via `tmux capture-pane -pS -E -`. | session transcript |
+| `browser` | Drive the real page via Playwright / puppeteer / Chromium; capture action log + screenshot path. | log + screenshot |
+| `computer` | OS-level GUI automation (AppleScript, xdotool, computer-use agent) against the running app; capture action log + screenshot. | log + screenshot |
+
+Paste the artifact path into `notepad.md` immediately after capture.
+
+**Adversarial classes to exercise where applicable:**
+
+- Malformed input (truncated payload, wrong type, empty body, oversized field).
+- Prompt injection or boundary-crossing inputs.
+- Cancel / resume: interrupt the task mid-way, restart, verify state is consistent.
+- Stale state: run the scenario against an artifact left from a prior incomplete run.
+- Dirty worktree: ensure the feature behaves correctly with uncommitted sibling changes present.
+- Hung commands: send a well-formed request to a temporarily unavailable dependency; verify timeout and error surface.
+- Flaky test detection: run the test suite three times in a row; flag any non-deterministic result.
+- Misleading success output: verify the happy-path output does not mask a silent failure (exit code 0 with error text in stdout).
+- Repeated interruptions: interrupt the QA scenario twice at different points; confirm recovery each time.
+
+Not every class applies to every task. Record which were exercised and which were
+skipped with a one-line justification in `notepad.md`.
+
+### Gate E — Paired cleanup (never skip — no receipt = checkbox stays open)
+
+Every runtime artifact spawned in Gate D **must** be torn down before this gate
+is considered complete:
+
+- Server PIDs: `kill <pid>`; verify with `kill -0 <pid>` (must fail).
+- tmux sessions: `tmux kill-session -t sw-qa-<criterion>`; verify with `tmux ls`.
+- Browser / Playwright contexts: `.close()`.
+- Containers: `docker rm -f <name>`.
+- Bound ports: `lsof -i :<port>` must return empty.
+- Temp sockets, files, dirs: `rm -rf <mktemp path>`.
+- QA-only environment variables: `unset <VAR>`.
+
+Append a one-line cleanup receipt to `notepad.md` immediately after teardown:
+
+```
+cleanup [C-NNN]: killed PID 12345; tmux kill-session sw-qa-c-003; rm -rf /tmp/sw.aB12cD
+```
+
+No receipt → the checkbox stays open. This is not negotiable.
+
+---
+
+## §3 — Independent verification gate
+
+Trigger this gate when **any** of the following are true:
+
+- The task touches 3 or more files.
+- The task is marked security-sensitive, has network-facing behavior, or modifies
+  shared state.
+- The plan row contains `verify: strict` or the user said "rigorously" / "엄밀"
+  / "deeply" / "깊게".
+- 20 or more turns have elapsed since the run opened.
+
+**Procedure:**
+
+1. Dispatch a `delegate_task` child as an independent verifier. Its goal must
+   contain: the task row, the Success Criteria rows it maps to, the full diff
+   since the last commit, the `notepad.md` path, and the artifact paths from
+   Gates B–D. The child's role is explicitly to **refute** the done-claim — not
+   to rubber-stamp it.
+2. The verifier re-reads the diff, re-runs the test suite, re-runs the Gate D
+   channel scenario independently, and returns a verdict.
+3. Treat the verdict as binding. There is no "false positive". "Looks good but…"
+   is a rejection. Do not argue, minimise, or explain away concerns.
+4. Fix every issue raised. Re-run Gates C, D, and E. Capture fresh evidence.
+5. Re-dispatch the same verifier. Loop until the verdict is **unconditional
+   approval** with no qualifications.
+6. Record the verifier's final approval message in `ledger.jsonl` as a
+   `verification_approved` event before proceeding.
+
+---
+
+## §4 — Mark-progress loop (CONTINUE WITHOUT ASKING)
+
+After all five gates (and §3 if triggered) pass for a task:
+
+1. Flip the checkbox in the plan file: `- [ ] T-NNN` → `- [x] T-NNN`.
+2. Re-read the plan file. Count the remaining unchecked `- [ ]` lines. Assert
+   the count decreased by exactly one from the previous count. If it did not,
+   stop and surface the discrepancy before continuing.
+3. Append a `task_completed` entry to `ledger.jsonl`:
+   ```json
+   {"event":"task_completed","task":"T-NNN","ts":"<ISO>","evidence":["<path>","<path>"],"cleanup_receipt":"<one-line>"}
+   ```
+4. Update `state.json` to reflect the new last-completed index.
+5. Move to the next unchecked task **without asking the user**. The loop
+   continues autonomously until every top-level checkbox is done.
+
+Do not pause between tasks. Do not summarise progress mid-loop. Do not ask for
+confirmation. The only permitted pause is after 2 consecutive identical failures
+on the same gate — surface what was tried and ask before a third attempt.
+
+---
+
+## §5 — Final verification wave (F1–F4)
+
+After every top-level checkbox is flipped to `[x]`, run the four-phase final wave
+before declaring the run complete.
+
+### F1 — Full scenario replay
+
+Re-run every `C-NNN` channel scenario from §2 Gate D, in order, against the final
+state. Capture fresh artifacts. Record each as a `final_qa` event in `ledger.jsonl`.
+
+### F2 — Full test suite
+
+Run the complete test suite (all files, no skip flags, no `.only`, no `xfail`
+added this run). Every test must be green. Record the suite output path.
+
+### F3 — LSP diagnostics sweep
+
+Run LSP diagnostics across every file modified during the run. Zero errors
+permitted. Warnings that existed before the run are acceptable; new warnings
+introduced during the run must be resolved.
+
+### F4 — Ledger integrity check
+
+Read `ledger.jsonl` end-to-end. Verify:
+
+- Every `T-NNN` task has a corresponding `task_completed` entry.
+- Every `task_completed` entry has a non-empty `cleanup_receipt`.
+- Every `C-NNN` criterion has at least one `evidence` path that exists on disk.
+- A `final_qa` entry exists for every `C-NNN` criterion.
+
+If any check fails, fix the gap before proceeding.
+
+---
+
+## §6 — Commits
+
+Atomic commits per logical change, following Conventional Commits:
+`<type>(<scope>): <imperative>` — types: `feat`, `fix`, `refactor`, `test`,
+`docs`, `chore`, `build`, `ci`, `perf`. Each commit must build and pass the full
+test suite on its own. No WIP commits on the final branch.
+
+Final commit footer must include:
+
+```
+Plan: plans/<slug>.md
+Run: .hermes/lithermes/runs/<run-id>/
+```
+
+Do **not** auto-commit unless the user requested or pre-authorised this session.
+Default: stage + draft message + present for approval.
+
+---
+
+## §7 — Stop conditions
+
+The run is done **only** when all of the following are true:
+
+- Every top-level `- [ ]` checkbox in the plan file is `[x]`.
+- F1–F4 final wave all passed with captured artifacts.
+- Every cleanup receipt is recorded in `ledger.jsonl`.
+- The notepad `## Todo` section is empty.
+- If §3 was triggered: `ledger.jsonl` contains an unconditional
+  `verification_approved` event for every task that triggered the gate.
+
+Leftover state disqualifies completion: a QA-spawned process still alive, a tmux
+session still listed by `tmux ls`, a browser context still open, a bound port, a
+temp file still on disk. Tear it down, record the receipt, then re-check.
+
+After 2 consecutive identical failures on the same gate, surface what was tried
+and ask the user before a third attempt. After 2 parallel exploration waves yield
+no new useful facts, stop exploring and act.
+
+---
+
+## §8 — Output discipline
+
+- First line this turn: `START-WORK ACTIVE — run <run-id>`
+- After artifact reads (§1): one paragraph summarising what the ledger says is
+  done, what is in-progress, and how many checkboxes remain.
+- During the loop: surface only state changes — RED captured, GREEN captured,
+  QA scenario PASS/FAIL with artifact path, verifier verdict, checkbox flipped.
+- No commentary between gates. No "now I will…" narration. State changes only.
+- Final message: run ID + plan path + per-task summary table (task | status |
+  evidence paths | cleanup receipt) + F1–F4 results + commit list
+  (`<sha> <subject>`) if commits were made.
+
+---
+
+## §9 — Constraints (non-negotiable)
+
+- TDD is mandatory on every production change — features, fixes, refactors,
+  glue, config-with-logic. No "too small", "too obvious", or "just a one-liner"
+  exemptions. If production code was written without a preceding failing test in
+  the same notepad, stop, revert, write the test, watch it fail, then redo.
+- The only changes exempt from a new test: pure formatting, comment-only edits,
+  dependency version bumps with no behavior delta, rename-only moves. Each
+  exemption must be justified in `## Findings`; unjustified exemption is a gate
+  failure.
+- Never suppress lints, errors, or test failures. Never delete, skip, `.only`,
+  `.skip`, or comment out tests to green the suite.
+- Never claim a checkbox done from inference alone — only from RED → GREEN +
+  channel artifact + cleanup receipt.
+- Parallel tool calls for any independent work within a step; never parallelise
+  RED and GREEN of the same criterion.
+- Plan files are read-only except for flipping `[ ]` → `[x]`. Do not add,
+  remove, or reorder tasks.

package/bin/lithermes.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+const { main } = require("../src/cli");
+
+main(process.argv.slice(2)).catch((error) => {
+  const code = Number.isInteger(error.exitCode) ? error.exitCode : 1;
+  console.error(error.message || String(error));
+  process.exit(code);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "lithermes-ai",
+  "version": "0.5.0",
+  "description": "npx/bunx installer for the LitHermes Hermes plugin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wjgoarxiv/lithermes.git",
+    "directory": "packages/lithermes-installer"
+  },
+  "homepage": "https://www.npmjs.com/package/lithermes-ai",
+  "bugs": {
+    "url": "https://github.com/wjgoarxiv/lithermes/issues"
+  },
+  "bin": {
+    "lithermes": "bin/lithermes.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "!assets/**/__pycache__/**",
+    "!assets/**/*.pyc",
+    "!assets/**/upstream/**",
+    "README.md",
+    "README_Ko-KR.md",
+    "cover.png"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "sync-plugin": "node scripts/sync-plugin.js",
+    "pack:dry": "npm pack --dry-run --json",
+    "clean:payload": "find assets -name __pycache__ -type d -prune -exec rm -rf {} + && find assets -name '*.py[co]' -delete",
+    "prepack": "npm run clean:payload"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,129 @@
+const path = require("node:path");
+const { installLitHermes, uninstallLitHermes } = require("./lib/install");
+const { checkLitHermes, doctorLitHermes } = require("./lib/check");
+const { createSpinner, shouldUseSpinner } = require("./lib/spinner");
+const { listHud, applyHud, clearHud, resolveHome, promptAccent } = require("./lib/hud");
+const { supportsColor, findAccent } = require("./lib/skins");
+
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = argv[i];
+    if (!item.startsWith("--")) {
+      positionals.push(item);
+      continue;
+    }
+    const key = item.slice(2);
+    if (["yes", "offline", "dry-run", "spinner", "no-spinner", "gateway-offline", "force", "patch-installed-hermes", "no-patch-installed-hermes", "rollback-patches", "list", "no-hud"].includes(key)) {
+      flags[key] = true;
+      continue;
+    }
+    const value = argv[i + 1];
+    if (!value || value.startsWith("--")) {
+      flags[key] = "";
+      continue;
+    }
+    flags[key] = value;
+    i += 1;
+  }
+  return { command: positionals[0] || "help", flags, positionals };
+}
+
+function packageVersion() {
+  const pkg = require(path.join(__dirname, "..", "package.json"));
+  // Print the command/brand name (the bin), not the npm package name — the
+  // command is `lithermes` even though the npm package is published as `lithermes-ai`.
+  const brand = Object.keys(pkg.bin || {})[0] || pkg.name;
+  return `${brand} ${pkg.version}`;
+}
+
+// Pick a HUD accent after install: explicit --hud <accent>, an interactive TTY
+// prompt, or skip (--no-hud / non-TTY / --dry-run).
+async function maybePickHudAccent(flags) {
+  if (flags["dry-run"]) return;
+  let entry = null;
+  if (typeof flags.hud === "string" && flags.hud.trim()) {
+    entry = findAccent(flags.hud);
+    if (!entry) {
+      console.error(`HUD: unknown accent '${flags.hud}'; skipping (run \`lithermes hud --list\`).`);
+      return;
+    }
+  } else if (flags["no-hud"]) {
+    return;
+  } else if (process.stdin.isTTY && process.stdout.isTTY && !process.env.CI) {
+    entry = await promptAccent({ color: supportsColor() });
+  } else {
+    return;
+  }
+  if (entry) console.log(applyHud(entry.accent, flags));
+}
+
+async function main(argv) {
+  const { command, flags, positionals } = parseArgs(argv);
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(packageVersion());
+    return;
+  }
+  if (command === "hud") {
+    const accent = positionals[1];
+    if (flags.list || !accent) {
+      console.log(listHud({ color: supportsColor(), hermesHome: resolveHome(flags) }));
+      return;
+    }
+    if (accent === "off" || accent === "clear" || accent === "none") {
+      console.log(clearHud(flags));
+      return;
+    }
+    try {
+      console.log(applyHud(accent, flags));
+    } catch (error) {
+      console.error(error.message);
+      process.exitCode = error.exitCode || 1;
+    }
+    return;
+  }
+  if (command === "install") {
+    const spinner = shouldUseSpinner({ flags }) ? createSpinner() : null;
+    try {
+      if (spinner) spinner.start();
+      const result = installLitHermes({
+        ...flags,
+        onProgress: spinner ? (message) => spinner.update(message) : undefined,
+      });
+      if (spinner) spinner.succeed("Installing LitHermes complete");
+      console.log(result.message);
+    } catch (error) {
+      if (spinner) spinner.fail();
+      throw error;
+    }
+    await maybePickHudAccent(flags);
+    return;
+  }
+  if (command === "uninstall") {
+    const result = uninstallLitHermes(flags);
+    console.log(result.message);
+    return;
+  }
+  if (command === "check") {
+    const result = checkLitHermes(flags);
+    console.log(result.message);
+    return;
+  }
+  if (command === "doctor") {
+    const result = doctorLitHermes(flags);
+    console.log(result.message);
+    return;
+  }
+  console.log([
+    "lithermes commands:",
+    "  install [--yes] [--dry-run] [--spinner] [--no-spinner] [--hud <accent>] [--no-hud] [--hermes-home PATH]",
+    "  check [--offline] [--gateway-offline] [--hermes-home PATH]",
+    "  doctor [--offline] [--hermes-home PATH] [--hermes-repo PATH]",
+    "  uninstall [--yes] [--hermes-home PATH]",
+    "  hud [<accent>|off|--list] [--hermes-home PATH]   (Hermes HUD skin accents)",
+    "  version",
+  ].join("\n"));
+}
+
+module.exports = { main, parseArgs };

package/src/lib/check.js

@@ -0,0 +1,94 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { configHasLitHermes, readConfig } = require("./config");
+const { ensureHermesHome, LitHermesError } = require("./hermesDiscovery");
+const { assetRoot, pluginDest } = require("./install");
+
+const requiredCommands = ["lit", "lit-loop", "lit-plan"];
+
+function scanPluginCommands(pluginPath) {
+  const init = path.join(pluginPath, "__init__.py");
+  if (!fs.existsSync(init)) return [];
+  const source = fs.readFileSync(init, "utf8");
+  return requiredCommands.filter((cmd) => source.includes(`"${cmd}"`) || source.includes(`'${cmd}'`));
+}
+
+function checkGatewaySource(repo) {
+  if (!repo) return { ok: true, skipped: true };
+  const file = path.join(repo, "gateway", "run.py");
+  if (!fs.existsSync(file)) return { ok: false, reason: "gateway/run.py missing" };
+  const source = fs.readFileSync(file, "utf8");
+  return {
+    ok: source.includes('command.replace("_", "-")') && source.includes("_plugin_agent_dispatch_payload"),
+    reason: "gateway underscore dispatch or structured payload helper missing",
+  };
+}
+
+function checkCliSource(repo) {
+  if (!repo) return { ok: true, skipped: true };
+  const file = path.join(repo, "cli.py");
+  if (!fs.existsSync(file)) return { ok: false, reason: "cli.py missing" };
+  const source = fs.readFileSync(file, "utf8");
+  return {
+    ok: source.includes("agent_message") && source.includes("_pending_input.put") && source.includes("ast.literal_eval"),
+    reason: "CLI plugin structured payload dispatch missing",
+  };
+}
+
+function checkTuiSource(repo) {
+  if (!repo) return { ok: true, skipped: true };
+  const file = path.join(repo, "tui_gateway", "server.py");
+  if (!fs.existsSync(file)) return { ok: false, reason: "tui_gateway/server.py missing" };
+  const source = fs.readFileSync(file, "utf8");
+  return {
+    ok: source.includes("_plugin_agent_dispatch_payload") && source.includes("command.dispatch") && source.includes('"type": "send"'),
+    reason: "TUI plugin structured payload dispatch missing",
+  };
+}
+
+function checkLitHermes(flags = {}) {
+  const { hermesHome, hermesRepo } = ensureHermesHome(flags);
+  const pluginPath = pluginDest(hermesHome);
+  const commands = scanPluginCommands(pluginPath);
+  const configOk = configHasLitHermes(readConfig(hermesHome));
+  const missing = requiredCommands.filter((cmd) => !commands.includes(cmd));
+  if (missing.length || !configOk) {
+    throw new LitHermesError(`LitHermes check FAIL\nmissing: ${missing.join(", ") || "none"}\nconfig enabled: ${configOk}`, 6);
+  }
+  const lines = [`LitHermes check PASS`, `commands: ${commands.join(", ")}`];
+  if (flags["gateway-offline"]) {
+    const gateway = checkGatewaySource(hermesRepo);
+    if (!gateway.ok && !gateway.skipped) throw new LitHermesError(`gateway check FAIL: ${gateway.reason}`, 7);
+    lines.push("gateway /lit_loop PASS");
+    lines.push("gateway /lit_plan PASS");
+  }
+  return { message: lines.join("\n") };
+}
+
+function doctorLitHermes(flags = {}) {
+  const { hermesHome, hermesRepo } = ensureHermesHome(flags);
+  const pluginPath = pluginDest(hermesHome);
+  const commands = scanPluginCommands(pluginPath);
+  const configOk = configHasLitHermes(readConfig(hermesHome));
+  const cli = checkCliSource(hermesRepo);
+  const tui = checkTuiSource(hermesRepo);
+  const gateway = checkGatewaySource(hermesRepo);
+  const installedPass = requiredCommands.every((cmd) => commands.includes(cmd)) && configOk;
+  const lines = [
+    `plugin discovery: ${installedPass ? "PASS" : "PATCH_AVAILABLE"}`,
+    `cli payload dispatch: ${cli.ok ? (cli.skipped ? "SKIPPED" : "PASS") : "PATCH_AVAILABLE"}`,
+    `tui payload dispatch: ${tui.ok ? (tui.skipped ? "SKIPPED" : "PASS") : "PATCH_AVAILABLE"}`,
+    `gateway underscore dispatch: ${gateway.ok ? "PASS" : "PATCH_AVAILABLE"}`,
+  ];
+  return { message: lines.join("\n") };
+}
+
+module.exports = {
+  checkCliSource,
+  checkGatewaySource,
+  checkLitHermes,
+  checkTuiSource,
+  doctorLitHermes,
+  requiredCommands,
+  scanPluginCommands,
+};