lithermes-ai 0.8.3 → 0.8.5

package/README.md

@@ -59,7 +59,7 @@ Restart any running Hermes CLI or Hermes gateway process. Then open Hermes and t
 - LitHermes workflow skill set: `ai-slop-remover`, `comment-checker`,
   `debugging`, `deep-interview`, `frontend-ui-ux`, `git-master`, `init-deep`,
   `lsp`, `programming`, `refactor`,
-  `remove-ai-slops`, `review-work`, `rules`, `start-work`, `lit-plan`,
+  `remove-ai-slops`, `review-work`, `rules`, `visual-qa`, `lsp-setup`, `litresearch`, `start-work`, `lit-plan`,
   `litgoal`, and `litwork` are installed as `lithermes:*` skills.
 - The full plugin payload — the `pre_llm_call` / `subagent_stop` hooks, every
   skill, and the durable goal tooling — ships in the bundle exactly as installed,

package/README_Ko-KR.md

@@ -59,7 +59,7 @@ npx lithermes-ai install --yes
 - LitHermes workflow skill set: `ai-slop-remover`, `comment-checker`,
   `debugging`, `deep-interview`, `frontend-ui-ux`, `git-master`, `init-deep`,
   `lsp`, `programming`, `refactor`,
-  `remove-ai-slops`, `review-work`, `rules`, `start-work`, `lit-plan`,
+  `remove-ai-slops`, `review-work`, `rules`, `visual-qa`, `lsp-setup`, `litresearch`, `start-work`, `lit-plan`,
   `litgoal`, `litwork`가 `lithermes:*` skill로 함께 설치됩니다.
 - 전체 plugin payload — `pre_llm_call` / `subagent_stop`
   hook, 모든 skill, durable goal tooling — 이 설치 상태 그대로 번들에 들어가므로,

package/assets/lithermes-plugin/README.md

@@ -16,11 +16,11 @@ first-class Hermes skills:
   `lithermes:ai-slop-remover`, `lithermes:comment-checker`,
   `lithermes:debugging`, `lithermes:deep-interview`,
   `lithermes:frontend-ui-ux`, `lithermes:git-master`,
-  `lithermes:init-deep`, `lithermes:lsp`,
-  `lithermes:programming`, `lithermes:refactor`,
+  `lithermes:init-deep`, `lithermes:lsp`, `lithermes:lsp-setup`,
+  `lithermes:litresearch`, `lithermes:programming`, `lithermes:refactor`,
   `lithermes:remove-ai-slops`, `lithermes:review-work`,
-  `lithermes:rules`, `lithermes:start-work`, `lithermes:lit-plan`,
-  `lithermes:litgoal`, and `lithermes:litwork`.
+  `lithermes:rules`, `lithermes:start-work`, `lithermes:visual-qa`,
+  `lithermes:lit-plan`, `lithermes:litgoal`, and `lithermes:litwork`.
 - Delegation fans lanes out through the native `delegate_task` tool (children
   run in parallel, the parent blocks for all); there is no named-agent registry
   and no per-child model selection.

package/assets/lithermes-plugin/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import argparse
 import functools
 from pathlib import Path
 from typing import Any
@@ -79,6 +80,18 @@ PORTED_SKILLS = [
         "litwork",
         "Hermes-native Litwork execution discipline.",
     ),
+    (
+        "visual-qa",
+        "Rigorously verify any web/TUI UI you built or changed with screenshot/terminal diffs and oracle passes.",
+    ),
+    (
+        "lsp-setup",
+        "Configure a language server for LitHermes LSP diagnostics across 20+ languages.",
+    ),
+    (
+        "litresearch",
+        "Run the LitHermes maximum-saturation research orchestrator: decompose, parallel delegate_task swarms, verify, synthesize cited.",
+    ),
 ]
 
 
@@ -104,16 +117,40 @@ def _pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
 
 
 def _setup_lithermes_cli(parser) -> None:
+    try:
+        parser.formatter_class = argparse.RawDescriptionHelpFormatter
+    except Exception:
+        pass
+    parser.description = "LitHermes — Hermes-native Litwork toolkit (litgoal runtime, skills, hooks)."
+    parser.epilog = (
+        "slash commands: /lit /lit-loop /lit-plan /litgoal /review-work /start-work /deep-interview\n"
+        "skills: 20 lithermes:* skills — `hermes lithermes status` lists them\n"
+        "hooks: pre_llm_call, subagent_stop, transform_llm_output\n"
+        "run `hermes lithermes status` for versions + full surface, or `doctor` for health checks"
+    )
+    parser.add_argument("--version", action="store_true", help="print the LitHermes plugin version")
     sub = parser.add_subparsers(dest="lh_cmd")
+    sub.add_parser("version", help="print the LitHermes plugin version")
+    sub.add_parser("status", help="show LitHermes + Hermes versions, hooks, commands, skills")
+    sub.add_parser("doctor", help="run LitHermes health checks")
     goal_parser = sub.add_parser("goal", help="LitHermes litgoal durable runtime")
     litgoal_cli.setup(goal_parser)
 
 
 def _handle_lithermes_cli(args) -> int:
-    if getattr(args, "lh_cmd", None) == "goal":
+    cmd = getattr(args, "lh_cmd", None)
+    if getattr(args, "version", False) or cmd == "version":
+        print(core.version_line())
+        return 0
+    if cmd == "doctor":
+        lines, code = core.doctor_report()
+        print("\n".join(lines))
+        return code
+    if cmd == "goal":
         return litgoal_cli.handle(args)
-    print("usage: hermes lithermes goal <set|status|criterion|evidence|steer|checkpoint|complete>")
-    return 1
+    # status, or bare `hermes lithermes` → the most useful "who am I" answer
+    print(core.status_report())
+    return 0
 
 
 def _ignited(handler):

package/assets/lithermes-plugin/core.py

@@ -981,3 +981,107 @@ def command_start_work(raw_args: str) -> str | dict[str, str]:
         "display": display,
         "agent_message": build_run_agent_message(load_run_state(run_dir)),
     }
+
+
+# ---------------------------------------------------------------------------
+# Management / diagnostics surface (hermes lithermes version|status|doctor).
+# Hermes plugins otherwise can't answer "who am I and what version" — these
+# helpers back the CLI subcommands wired in __init__.py.
+# ---------------------------------------------------------------------------
+
+PLUGIN_ROOT = Path(__file__).resolve().parent
+# These mirror what register()/register_hook()/litgoal tools wire up in __init__.py.
+# They are hardcoded (not introspected) so `status` works without a live ctx —
+# keep them in sync when adding a hook / slash command / goal tool.
+HOOKS = ("pre_llm_call", "subagent_stop", "transform_llm_output")
+SLASH_COMMANDS = (
+    "lit", "lit-loop", "lit-plan", "litgoal", "review-work",
+    "start-work", "deep-interview", "litwork-loop", "litwork-plan",
+)
+GOAL_TOOLS = (
+    "goal_set", "goal_status", "goal_add_criterion", "goal_evidence",
+    "goal_criterion_status", "goal_steer", "goal_checkpoint", "goal_complete",
+)
+_VERSION_RE = re.compile(r"^version:\s*(.+)$", re.MULTILINE)
+
+
+def plugin_version() -> str:
+    """Read the LitHermes plugin version from the bundled plugin.yaml."""
+    try:
+        m = _VERSION_RE.search((PLUGIN_ROOT / "plugin.yaml").read_text(encoding="utf-8"))
+        return m.group(1).strip().strip("\"'") if m else "unknown"
+    except (OSError, ValueError):
+        return "unknown"
+
+
+def hermes_host_version() -> str:
+    """Best-effort Hermes host runtime version (unknown outside Hermes)."""
+    try:
+        import hermes_cli
+        return str(getattr(hermes_cli, "__version__", "") or "unknown")
+    except Exception:
+        return "unknown"
+
+
+def version_line() -> str:
+    return f"lithermes {plugin_version()}"
+
+
+def _evidence_kinds() -> tuple[str, ...]:
+    try:
+        from .litgoal import model
+        return tuple(model.EVIDENCE_KINDS)
+    except Exception:
+        return ("red", "green", "scenario", "cleanup", "note")
+
+
+def _skill_names() -> list[str]:
+    skills_dir = PLUGIN_ROOT / "skills"
+    if not skills_dir.is_dir():
+        return []
+    return sorted(d.name for d in skills_dir.iterdir() if (d / "SKILL.md").is_file())
+
+
+def status_report() -> str:
+    """One-glance health/identity line for `hermes lithermes status`."""
+    skills = _skill_names()
+    return "\n".join([
+        f"LitHermes plugin {plugin_version()}   (Hermes host {hermes_host_version()})",
+        f"plugin dir: {PLUGIN_ROOT}",
+        f"hooks ({len(HOOKS)}): {', '.join(HOOKS)}",
+        f"slash commands ({len(SLASH_COMMANDS)}): {', '.join('/' + c for c in SLASH_COMMANDS)}",
+        f"skills ({len(skills)}): {', '.join(skills)}",
+        f"goal tools ({len(GOAL_TOOLS)}): {', '.join(GOAL_TOOLS)}",
+        "litgoal state: .hermes/lithermes/litgoal/   (drive via: hermes lithermes goal status)",
+        f"litgoal evidence kinds: {', '.join(_evidence_kinds())}",
+    ])
+
+
+def doctor_report() -> tuple[list[str], int]:
+    """Health checks for `hermes lithermes doctor`. Returns (lines, exit_code)."""
+    lines: list[str] = []
+    ok = True
+    ver = plugin_version()
+    if ver != "unknown":
+        lines.append(f"[OK] plugin.yaml readable (version {ver})")
+    else:
+        lines.append("[WARN] plugin.yaml unreadable or missing a version field")
+        ok = False
+    skills = _skill_names()
+    if skills:
+        lines.append(f"[OK] skills bundled: {len(skills)}")
+    else:
+        lines.append("[WARN] no skills found under skills/")
+        ok = False
+    try:
+        from .litgoal import runtime as _rt  # noqa: F401
+        lines.append("[OK] litgoal durable runtime importable")
+    except Exception as exc:
+        lines.append(f"[WARN] litgoal runtime import failed: {exc}")
+        ok = False
+    hv = hermes_host_version()
+    if hv != "unknown":
+        lines.append(f"[OK] Hermes host detected (v{hv})")
+    else:
+        lines.append("[NOTE] Hermes host version unknown (running outside Hermes?)")
+    return lines, (0 if ok else 1)

package/assets/lithermes-plugin/payload-version.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-06-14T07:44:14.269Z",
+  "syncedAt": "2026-06-15T16:35:55.443Z",
   "source": "source-reference",
-  "sourceHash": "1072e4218aeda8d0a4c03e11189b07505021bc4acc3b1280bfeabdd420d1ff9a",
+  "sourceHash": "c93c37881e1f6f5730a1adc6c0e62e4dfab1ca44146eed900b8468448438fe8a",
   "files": [
     {
       "path": "NOTICE.md",
@@ -9,15 +9,15 @@
     },
     {
       "path": "README.md",
-      "sha256": "e0bc7d60f61a8d35df9f6287876e236e59e80e871261558701375a12cc4e4feb"
+      "sha256": "29f9157e4aa5a667c0d4c2df30d803c4eaa8cc4b30937c84ac1a08b8257e1eca"
     },
     {
       "path": "__init__.py",
-      "sha256": "9a0b19060eb12799bf76b15b729fcbab4388d74aac9e888b40369b809fd54669"
+      "sha256": "96b816aee730ea9a5e1fedbc283829240baffddecc37872e4f60bb05f420366c"
     },
     {
       "path": "core.py",
-      "sha256": "6b9d8b488d5905232d170f78943d2b5f9b9a4bde564e01a816c4fcc45098a7df"
+      "sha256": "70ddccfb4cc2fe1a923a5a61244e5cb36ef8ac0f94d34a76703fa6d82dbabf3f"
     },
     {
       "path": "litgoal/__init__.py",
@@ -49,7 +49,7 @@
     },
     {
       "path": "plugin.yaml",
-      "sha256": "7ef63d09b537d994dc5ed25149b0841e84745ae352c851d9a54788ddd793b0e9"
+      "sha256": "7761c417acfcd614e8d434b3ca11c498f48422a72f5b70f817a59326aca51b60"
     },
     {
       "path": "skills/ai-slop-remover/SKILL.md",
@@ -61,7 +61,7 @@
     },
     {
       "path": "skills/debugging/SKILL.md",
-      "sha256": "aff2ca5765f490ed1e45d2eaa77c48db3ef98cec12fa10ebff3f91b82eab1254"
+      "sha256": "48bdb0df0f41633aca17d6193aa98aabac4c49cc25c36e50f26b020f89f77d43"
     },
     {
       "path": "skills/debugging/references/methodology/00-setup.md",
@@ -163,10 +163,114 @@
       "path": "skills/litgoal/SKILL.md",
       "sha256": "7a1fc23afe57f957a063a70b1bf810dc9c66fd44bcfd93b1ec739d59167e5ad9"
     },
+    {
+      "path": "skills/litresearch/SKILL.md",
+      "sha256": "3ff390e7a5847aebfa8943fe593fa386f9aeab2716fb30f7b20feaa3990f311f"
+    },
     {
       "path": "skills/litwork/SKILL.md",
       "sha256": "625e8ed44365d5ebcab9b8a3a2e1db4ccd5d4b6a7cbff6710fabfa51fd8727ad"
     },
+    {
+      "path": "skills/lsp-setup/SKILL.md",
+      "sha256": "52e473a5727ab80e90d1bfd6c3a91d8a2ba9579c30bf65af1dd895eb3918900a"
+    },
+    {
+      "path": "skills/lsp-setup/references/bash/README.md",
+      "sha256": "7d32640c2f50ad18e4ccf1ab2f7b4b1ea989ce2228054c8bc2f05b97d484f8ad"
+    },
+    {
+      "path": "skills/lsp-setup/references/c-cpp/README.md",
+      "sha256": "0334f275754d4231a30700b9f1518c06ae9fd04f8809e3c89b197763cbdfdbb3"
+    },
+    {
+      "path": "skills/lsp-setup/references/csharp/README.md",
+      "sha256": "1717ca8bf762832f7209ef1d10f8896958e1a5a9c0445b8b9ce7bbce18423fb8"
+    },
+    {
+      "path": "skills/lsp-setup/references/dart/README.md",
+      "sha256": "eaa9b13bdbcd162b43220fdefb6292a86d53b053c32d60b3d067f9785a26c9df"
+    },
+    {
+      "path": "skills/lsp-setup/references/elixir/README.md",
+      "sha256": "385b3d4c3d0d531afb07e33570c502e754174b52125ae6572a35edd24d0da1e5"
+    },
+    {
+      "path": "skills/lsp-setup/references/go/README.md",
+      "sha256": "e0f2ced60994adfe22a76e37d69deb3308fe7f4885a9579e28b864a1948e7c22"
+    },
+    {
+      "path": "skills/lsp-setup/references/haskell/README.md",
+      "sha256": "df6dc810662b52de10d358edae6742cfab9cd66fc1636c68096ffe7f241fe102"
+    },
+    {
+      "path": "skills/lsp-setup/references/java/README.md",
+      "sha256": "a33e64405e090ffc4ec028d2aead42ec3c52b8c38f72ec0f92e4f0324bbbf4f3"
+    },
+    {
+      "path": "skills/lsp-setup/references/julia/README.md",
+      "sha256": "779799ec0ce809b10136167f768c65a756438e5a478ef338249619cc76511e78"
+    },
+    {
+      "path": "skills/lsp-setup/references/kotlin/README.md",
+      "sha256": "f4472bb7c34328aaeb1461d0c729efbf738a2e89fc94a1eb729f2a868ca88a76"
+    },
+    {
+      "path": "skills/lsp-setup/references/lua/README.md",
+      "sha256": "892613acb00e9cdb50ba5e69f147e33788a9b3db6500371f2ae6e20a07db3220"
+    },
+    {
+      "path": "skills/lsp-setup/references/php/README.md",
+      "sha256": "3719c12c64bd823ff9cf7af4073e14eaa4799726dee5b20a593b8a528527472f"
+    },
+    {
+      "path": "skills/lsp-setup/references/python/README.md",
+      "sha256": "b64b0add1c8eb5472cf03bfe4aad7ee4eab20c8f12874be20739071cdd58be7d"
+    },
+    {
+      "path": "skills/lsp-setup/references/ruby/README.md",
+      "sha256": "6c7a146dc58ef38c3670ba4c16690e419c96099ac6e62f0f059d4f16a5792e48"
+    },
+    {
+      "path": "skills/lsp-setup/references/rust/README.md",
+      "sha256": "2797c7c27d1041924600192cb649d81bbb94a53ddbb894f82748e977eac64d3a"
+    },
+    {
+      "path": "skills/lsp-setup/references/swift/README.md",
+      "sha256": "d7589fe85fae9937bfcfb951e41171577e743f6e4b7cea9dbef575b811d041ed"
+    },
+    {
+      "path": "skills/lsp-setup/references/terraform/README.md",
+      "sha256": "fe86c8bcb4966efd400e083bd3e22863ee4fae56c3fba1eb3abdaa666fe9c24e"
+    },
+    {
+      "path": "skills/lsp-setup/references/typescript/README.md",
+      "sha256": "fbdc8348d5d0b3978e73d7bd3701d34d8df692d031437e87c19b8708a5946108"
+    },
+    {
+      "path": "skills/lsp-setup/references/yaml/README.md",
+      "sha256": "c9456d750ba91716e30538d262e83f70ae51b44697e3bdee87d68dbf861f4b63"
+    },
+    {
+      "path": "skills/lsp-setup/references/zig/README.md",
+      "sha256": "87b955a8bd792561e291fe2922b467714aefdf59bede752938b20ce3da2a402c"
+    },
+    {
+      "path": "skills/lsp-setup/scripts/detect-lsp.ts",
+      "sha256": "32d9dba93c1e604e49e6049603c0ee8da67927540a7c53c87fc46c9a059b5178"
+    },
+    {
+      "path": "skills/lsp-setup/scripts/lsp-server-table.ts",
+      "sha256": "fc281d78ff2f50657d4c9bcc253f2ff8c0f9e6be1dcea0b9963f52d874ef801e"
+    },
+    {
+      "path": "skills/lsp-setup/scripts/tsconfig.json",
+      "sha256": "8eecbbef0296b909dbe17af651126cf2c00a825ae65fa5be2836b212267c6f83"
+    },
+    {
+      "path": "skills/lsp-setup/scripts/verify-lsp.ts",
+      "sha256": "33c6c22236234ed5f4db7b0deae560b9b5e0c8c018be4ded1a6c1179792655fe"
+    },
     {
       "path": "skills/lsp/SKILL.md",
       "sha256": "3e793aaa158156dd60ec11add7375050bbeeb7b3eb77497f1c432d0842abff5c"
@@ -478,6 +582,46 @@
     {
       "path": "skills/start-work/SKILL.md",
       "sha256": "194a1d719c00564959da99715c86424a5ecd76196a4db9ca60e64be062dc70b5"
+    },
+    {
+      "path": "skills/visual-qa/SKILL.md",
+      "sha256": "fd1ed0841afc08ca838069969284afa04b16c81016a63a16d2f9187a3bde3327"
+    },
+    {
+      "path": "skills/visual-qa/scripts/ansi.ts",
+      "sha256": "8d6e2f3881093538a96040ec8fea28285754e28ceac1b1f1da1e6d5024eeacfd"
+    },
+    {
+      "path": "skills/visual-qa/scripts/cli.ts",
+      "sha256": "0dc05cf89afbd8df5371722229ada00751ba58eda633405457964ccd8bc6ac23"
+    },
+    {
+      "path": "skills/visual-qa/scripts/east-asian-width.ts",
+      "sha256": "8cd4ac48a57bad794639be581f7dd2b52105ad258d090b403a74a46b10a83952"
+    },
+    {
+      "path": "skills/visual-qa/scripts/image-diff.ts",
+      "sha256": "3b4e68afa5ad3e2bbd2866ba9b5a39b7e371b773c6d6b1d3a080a2f381cc00e4"
+    },
+    {
+      "path": "skills/visual-qa/scripts/png-crc.ts",
+      "sha256": "881027d0bb58b1633fd46b58e3034fefb61cba2e173af666c24a5ea4f95429d0"
+    },
+    {
+      "path": "skills/visual-qa/scripts/png-decode.ts",
+      "sha256": "9c190b960e276a81b3f962e509a45b72fe8bcc6a93d704fbee3a383fcde4bb64"
+    },
+    {
+      "path": "skills/visual-qa/scripts/png-synth.ts",
+      "sha256": "acc348340f1efd1cc6d312753912ef294640d5585a05a6839c72784fb64fcb84"
+    },
+    {
+      "path": "skills/visual-qa/scripts/tui-grid.ts",
+      "sha256": "63a0db7624eda98cfd37434552f9e56a48195bbeab8a9bbdd017c97b369bf58c"
+    },
+    {
+      "path": "skills/visual-qa/scripts/types.ts",
+      "sha256": "ef5ee3c9adfeb2d92138b2ce543232a8323247d5b9dbdde13b26f3197ee13c62"
     }
   ]
 }

package/assets/lithermes-plugin/plugin.yaml

@@ -1,5 +1,5 @@
 name: lithermes
-version: 0.8.3
+version: 0.8.5
 description: "Hermes-native workflow toolkit: litgoal durable runtime, 5-lane review orchestrator, Litwork commands, skills, and prompt steering."
 author: "Hermes Agent"
 kind: standalone

package/assets/lithermes-plugin/skills/debugging/SKILL.md

@@ -89,6 +89,48 @@ These are not phases — read them when the situation calls for them:
 
 ---
 
+## Reproduction standards
+
+A good reproduction is:
+
+- runnable from the project root
+- deterministic, or carries a bounded flake note
+- small enough for the next agent to rerun
+- tied to one expected observable
+
+For LitHermes examples:
+
+- `cd ~/.hermes/hermes-agent && venv/bin/python -c "import sys; sys.path.insert(0,'$HOME/.hermes/plugins'); import lithermes.core as c; print(bool(c.pre_llm_call(user_message='lit go', session_id='x')))"`
+- `hermes -z "Reply READY then stop. lit"` → expect `READY`, exit 0
+- `npm test` from `packages/lithermes-installer/`
+- `node test/scripts/scan-forbidden-tokens.js --tracked`
+
+## Root cause discipline
+
+Explain the mechanism, not just the symptom. "The command didn't bind the goal"
+is not a root cause. "The slash-command handler is dispatched as `handler(user_args)`
+with no `session_id`, so it cannot call `GoalManager.set()` — binding has to happen
+in `pre_llm_call`, which does receive the session id" is a root cause.
+
+## Common LitHermes failure classes
+
+- Plugin manifest (`plugin.yaml`) version drifts from `package.json` — a guard test asserts they match.
+- `npx <pkg>` fails with `command not found` when the bin name ≠ the package name (needs a matching bin alias).
+- `npm publish` requires the user's OTP and fails with `EOTP` — it cannot be run unattended.
+- Hook JSON parsing must fail with a controlled error, never a raw stack trace.
+- Package `files` / `payload-version.json` omit a newly added skill or command.
+- A per-turn flag left in module state leaks into the next turn when a hook does not fire (e.g. an interrupted turn).
+
+## Patch rules
+
+- Patch the failing boundary, not an unrelated symptom.
+- Keep compatibility aliases unless a breaking change is intentional.
+- Add the failing test before changing production behavior.
+- Do not broaden `except`/`catch` blocks without asserting the new error path.
+- Never call the network, publish, or mutate shared user state inside tests.
+
+---
+
 ## Non-Negotiable Safety Invariants
 
 <safety>