lithermes-ai 0.5.0

package/assets/lithermes-plugin/core.py

@@ -0,0 +1,853 @@
+from __future__ import annotations
+
+import json
+import importlib
+import re
+import shlex
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+try:
+    get_hermes_home = importlib.import_module("hermes_constants").get_hermes_home
+except Exception:
+    import os
+
+    def get_hermes_home() -> Path:
+        val = (os.environ.get("HERMES_HOME") or "").strip()
+        return Path(val).expanduser() if val else Path.home() / ".hermes"
+
+
+# Durable litgoal runtime state lives under <workspace>/.hermes/lithermes/<dir>.
+# This constant anchors every litgoal state path (goals/ledger/evidence).
+LITGOAL_STATE_DIRNAME = "litgoal"
+
+# Fire on a standalone `lit`/`litwork` token delimited by whitespace, string
+# edge, or punctuation — but NOT inside a larger word ("split", "literally") and
+# NOT as a hyphen/underscore compound ("lit-review", "lit_loop"). This keeps
+# "…진행해줘 lit" (trailing token) firing while excluding command-like compounds.
+LIT_PATTERN = re.compile(r"(?<![\w-])(?:litwork|lit)(?![\w-])", re.IGNORECASE)
+DIRECT_LIT_PATTERN = re.compile(r"^\s*(?:lit|litwork)\b\s+(?P<task>.+?)\s*$", re.IGNORECASE | re.DOTALL)
+MAX_TASK_LEN = 4000
+_SLUG_PATTERN = re.compile(r"[^a-z0-9]+")
+
+LIT_CONTEXT = "\n".join(
+    [
+        "<lithermes-litwork>",
+        "The user invoked Litwork/LitHermes. Operate in a durable, evidence-first loop:",
+        "- restate the concrete completion promise before changing files;",
+        "- keep the implementation scoped to the current repository and existing Hermes patterns;",
+        "- use focused tests and manual verification evidence before claiming done;",
+        "- preserve unrelated user changes and avoid destructive git commands;",
+        "- keep local state, plans, and evidence under plans/ or .hermes/lithermes when useful.",
+        "",
+        "<lithermes-loop-discipline>",
+        "Per success criterion, loop: PIN -> RED -> GREEN -> VERIFY -> SURFACE -> CLEAN -> RECORD.",
+        "- RED: write the failing test FIRST; capture the assertion message proving it fails for the right reason.",
+        "- GREEN: smallest change to flip RED->GREEN; capture the passing output.",
+        "- SURFACE (manual QA): actually run ONE channel scenario end-to-end and capture the artifact path:",
+        "  HTTP (`curl -i` / APIRequestContext), tmux (`tmux new-session`/`send-keys`/`capture-pane`),",
+        "  browser use, or computer use. TESTS ALONE NEVER PROVE DONE; `--dry-run`/'looks correct' never count.",
+        "- CLEAN (paired, never skip): tear down every artifact the QA spawned (kill PIDs, `tmux kill-session`,",
+        "  free ports, `rm -rf` temp dirs) and append a one-line cleanup receipt next to the artifact, e.g.",
+        "  `cleanup: killed 12345; tmux kill-session lit-qa-foo; rm -rf /tmp/lit.aB12`. No receipt => criterion stays open.",
+        "- Reviewer gate (triggered): on 3+ files OR 20+ turns OR refactor/migration/security or an explicit",
+        "  'strictly/rigorously/엄밀' request, delegate_task a strict reviewer; treat the verdict as binding;",
+        "  loop until UNCONDITIONAL approval ('looks good but...' = rejection).",
+        "</lithermes-loop-discipline>",
+        "",
+        "<lithermes-goal-bootstrap>",
+        "Goal binding in Hermes:",
+        "- Hermes has no model-facing goal tools; do not invoke get_goal/create_goal/update_goal.",
+        "- LitHermes binds the native standing /goal for you (session goal manager) so it persists.",
+        "- Track success criteria + evidence with the durable lithermes goal tools (goal_set,",
+        "  goal_add_criterion, goal_evidence, goal_criterion_status, goal_complete) and inspect",
+        "  with `hermes lithermes goal status`. The native evidence-judge decides completion.",
+        "</lithermes-goal-bootstrap>",
+        "</lithermes-litwork>",
+    ]
+)
+
+
+@dataclass(frozen=True)
+class CommandArgs:
+    positional: list[str]
+    options: dict[str, str | bool]
+
+
+def slugify(text: str, fallback: str = "lithermes-plan") -> str:
+    lowered = text.strip().lower()
+    slug = _SLUG_PATTERN.sub("-", lowered).strip("-")
+    return (slug[:60].strip("-") or fallback)
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def run_id(prefix: str = "run") -> str:
+    return f"{prefix}-{utc_now().strftime('%Y%m%dT%H%M%SZ')}-{uuid.uuid4().hex[:8]}"
+
+
+def parse_args(raw_args: str) -> CommandArgs:
+    try:
+        tokens = shlex.split(raw_args or "")
+    except ValueError as exc:
+        raise ValueError(f"could not parse arguments: {exc}") from exc
+
+    positional: list[str] = []
+    options: dict[str, str | bool] = {}
+    i = 0
+    while i < len(tokens):
+        token = tokens[i]
+        if not token.startswith("--"):
+            positional.append(token)
+            i += 1
+            continue
+
+        key_value = token[2:]
+        if not key_value:
+            i += 1
+            continue
+        if "=" in key_value:
+            key, value = key_value.split("=", 1)
+            options[key] = value
+            i += 1
+            continue
+        key = key_value
+        if i + 1 < len(tokens) and not tokens[i + 1].startswith("--"):
+            options[key] = tokens[i + 1]
+            i += 2
+        else:
+            options[key] = True
+            i += 1
+
+    return CommandArgs(positional=positional, options=options)
+
+
+def workspace_from_option(value: str | bool | None) -> Path:
+    if isinstance(value, str) and value.strip():
+        return Path(value).expanduser().resolve()
+    return Path.cwd().resolve()
+
+
+def plan_dir(workspace: Path) -> Path:
+    return workspace / "plans"
+
+
+def lithermes_dir(workspace: Path) -> Path:
+    return workspace / ".hermes" / "lithermes"
+
+
+def event_log_path() -> Path:
+    return get_hermes_home() / "lithermes" / "events.jsonl"
+
+
+def append_jsonl(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(payload, sort_keys=True) + "\n")
+
+
+def record_event(event: str, **fields: Any) -> None:
+    payload = {
+        "event": event,
+        "timestamp": utc_now().isoformat(),
+        **fields,
+    }
+    try:
+        append_jsonl(event_log_path(), payload)
+    except OSError:
+        pass
+
+
+_RUN_CONTEXT_TASK_PATTERN = re.compile(r"^task:\s*(?P<task>.+?)\s*$", re.MULTILINE)
+
+
+def bind_native_goal(session_id: str, goal_text: str) -> bool:
+    """Bind the NATIVE Hermes goal via the session GoalManager.
+
+    Hermes has no model-facing goal tools — goals are set through the `/goal`
+    command + hermes_cli.goals.GoalManager. We set it programmatically so a
+    LitHermes Litwork run makes the standing `/goal` actually stick (and the
+    native evidence-judge Stop-hook engages). Never clobbers an active goal.
+    Import is guarded so the plugin still loads / tests run outside Hermes.
+    """
+    goal_text = (goal_text or "").strip()
+    if not session_id or not goal_text:
+        return False
+    try:
+        from hermes_cli.goals import GoalManager
+    except (ImportError, ModuleNotFoundError):
+        return False
+    try:
+        mgr = GoalManager(session_id)
+        if mgr.is_active():
+            return False
+        mgr.set(goal_text)
+    except Exception:
+        return False
+    record_event("native_goal_bound", session_id=session_id)
+    return True
+
+
+def _clamp_task(task: str) -> str:
+    """Bound a triggered task before it is bound into native goal / run-state.
+
+    A pasted multi-thousand-char prompt would otherwise inflate the injected
+    LIT_CONTEXT and the persisted run-state. Clamp to MAX_TASK_LEN chars.
+    """
+    task = task.strip()
+    if len(task) > MAX_TASK_LEN:
+        return task[:MAX_TASK_LEN].rstrip() + " […]"
+    return task
+
+
+def _extract_run_context_task(message: str) -> str:
+    m = _RUN_CONTEXT_TASK_PATTERN.search(message)
+    return _clamp_task(m.group("task")) if m else ""
+
+
+def pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
+    user_message = str(kwargs.get("user_message") or "")
+    session_id = str(kwargs.get("session_id") or "")
+    # The /lit command injects a run-context message. Bind the native goal from
+    # it (we have session_id here), then skip re-injecting context.
+    if "<lithermes-run-context>" in user_message:
+        task = _extract_run_context_task(user_message)
+        if task:
+            bind_native_goal(session_id, task)
+        return None
+    if not LIT_PATTERN.search(user_message):
+        return None
+    direct = DIRECT_LIT_PATTERN.match(user_message)
+    run_context = ""
+    if direct:
+        task = _clamp_task(direct.group("task"))
+        if task:
+            bind_native_goal(session_id, task)
+            workspace = Path.cwd().resolve()
+            run_dir = write_run_state(
+                workspace,
+                task=task,
+                command="lit",
+            )
+            run_context = "\n\n" + build_run_agent_message(load_run_state(run_dir))
+    record_event(
+        "litwork_trigger",
+        session_id=session_id,
+        platform=str(kwargs.get("platform") or ""),
+    )
+    return {"context": LIT_CONTEXT + run_context}
+
+
+def subagent_stop(**kwargs: Any) -> None:
+    """Record each delegate_task child (e.g. a review lane) to the LitHermes ledger.
+
+    Hermes fires this once per child after delegate_task finishes. Observer-only:
+    the return value is ignored.
+    """
+    record_event(
+        "subagent_stop",
+        parent_session_id=str(kwargs.get("parent_session_id") or ""),
+        child_role=str(kwargs.get("child_role") or ""),
+        child_status=str(kwargs.get("child_status") or ""),
+        duration_ms=kwargs.get("duration_ms"),
+    )
+    return None
+
+
+def build_goal_instruction(
+    objective: str,
+    *,
+    plan: Path | None = None,
+    workspace: Path | None = None,
+) -> str:
+    objective = objective.strip() or "Complete the requested LitHermes task with evidence."
+    plan_line = f"Plan: {plan}" if plan else "Plan: none"
+    workspace_line = f"Workspace: {workspace}" if workspace else "Workspace: current"
+    return "\n".join(
+        [
+            "<lithermes-goal-instruction>",
+            "Hermes goal handoff.",
+            workspace_line,
+            plan_line,
+            "",
+            "Standing goal (native):",
+            "- Hermes has NO model-facing goal tools. Do not invoke get_goal, create_goal, or",
+            "  update_goal — they do not exist in Hermes and the request will fail.",
+            "- LitHermes binds the native standing goal for you via the session goal manager",
+            f"  (the /goal equivalent), so it persists across turns: \"{objective}\".",
+            f"- If it is not bound, the user can set it with: /goal {objective}",
+            "- The native evidence-judge decides completion across turns; keep producing real evidence.",
+            "",
+            "Durable litgoal layer (criteria + evidence + gate) — drive via the lithermes goal tools:",
+            "- goal_set to declare the objective and 3+ upfront success criteria (happy/edge/regression);",
+            "- goal_add_criterion / goal_evidence(kind=red|green|scenario|cleanup) / goal_criterion_status as you work;",
+            "- goal_steer to redirect, goal_checkpoint to snapshot; inspect via `hermes lithermes goal status`;",
+            "- goal_complete is REFUSED until every criterion has green + scenario evidence and no blocker is open.",
+            "",
+            "Isolation: for risky/parallel edits use a worktree (EnterWorktree, or `claude --worktree <name> --tmux`).",
+            "",
+            "Delegation model (you conduct, workers play):",
+            "- Use delegate_task(tasks:[{goal, context}]) to fan out INDEPENDENT work in parallel;",
+            "  children run concurrently and the parent blocks for all. Serialize only on a NAMED",
+            "  dependency (a child consumes another's output or edits the same file).",
+            "- Do NOT trust a child's self-report: re-read its diff, re-run its tests, and run LSP",
+            "  diagnostics yourself before accepting 'done'. Forward learnings to the next worker.",
+            "- Each child message is self-contained: goal + exact files in scope + constraints + the",
+            "  verify commands + the ONE manual-QA channel + the exact evidence artifact path.",
+            "- Read-only codebase-search child: 'where is X / which files do Y' — fan out parallel",
+            "  rg/LSP/AST/glob and return absolute paths plus the answer to the actual need.",
+            "- Read-only external-research child: an unfamiliar dependency/API — consult docs/gh/web",
+            "  and cite SHA-pinned permalinks to primary sources; never mutate the worktree.",
+            "</lithermes-goal-instruction>",
+        ]
+    )
+
+
+def create_plan(brief: str, workspace: Path | None = None) -> Path:
+    brief = brief.strip()
+    if not brief:
+        raise ValueError('usage: /lit-plan "what to build"')
+
+    root = (workspace or Path.cwd()).resolve()
+    out_dir = plan_dir(root)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    path = out_dir / f"{slugify(brief)}.md"
+    if path.exists():
+        path = out_dir / f"{slugify(brief)}-{utc_now().strftime('%H%M%S')}.md"
+
+    now = utc_now().isoformat()
+    content = "\n".join(
+        [
+            f"# {brief}",
+            "",
+            f"Created: {now}",
+            "Source: lithermes",
+            "",
+            "## TL;DR",
+            "> Summary:      <1-2 sentences>",
+            "> Deliverables: <bullet list>",
+            "> Effort:       <Quick | Short | Medium | Large | XL>",
+            "> Risk:         <Low | Medium | High> - <one-line driver>",
+            "",
+            "## Success Criteria",
+            "Declare 3+ upfront (happy / edge / regression). Each pairs an automated test",
+            "(written BEFORE code) with a manual-QA channel scenario. Format is parsed by the",
+            "runtime — keep the `C0NN | channel: | test: | scenario:` shape.",
+            "",
+            "- [ ] C001 | channel: tmux | test: <path::test_id> | scenario: Happy path — <user-visible outcome>",
+            "- [ ] C002 | channel: http | test: <path::test_id> | scenario: Edge/boundary — <malformed/empty/concurrent>",
+            "- [ ] C003 | channel: cli | test: <path::test_id> | scenario: Adjacent-surface regression — <named file+function>",
+            "",
+            "## Scope",
+            "### Must have",
+            "- [ ] <deliverable>",
+            "### Must NOT have (guardrails / anti-slop)",
+            "- [ ] <explicit exclusion>",
+            "",
+            "## Verification strategy",
+            "- Test decision: <TDD | tests-after> + framework",
+            "- QA policy: every criterion has an agent-executed channel scenario (tmux/http/browser/computer)",
+            "- Evidence: `.hermes/lithermes/runs/<run>/evidence/`",
+            "",
+            "## Execution strategy",
+            "### Parallel execution waves (target 5-8 tasks/wave)",
+            "- Wave 1 (no deps): ...",
+            "- Wave 2 (after Wave 1): ...",
+            "",
+            "### Dependency matrix",
+            "| Task | Depends on | Blocks | Parallel with |",
+            "|------|------------|--------|---------------|",
+            "| 1    | none       | 2      | -             |",
+            "",
+            "## Todos",
+            "> Implementation + Test = ONE task. Each carries References + Acceptance + QA + Commit.",
+            "",
+            "- [ ] 1. <task title>",
+            "  - What to do: <steps>",
+            "  - Must NOT do: <exclusions>",
+            "  - References: `<file:line>` - <pattern/contract to follow>",
+            "  - Acceptance: [ ] <verifiable command or assertion>",
+            "  - QA scenario: tool=<tmux|curl|...> steps=<...> expected=<binary pass/fail> evidence=<path>",
+            "  - Commit: `<type>(<scope>): <imperative>`",
+            "",
+            "## Final verification wave (after all tasks — ALL must pass)",
+            "- [ ] F1. Plan compliance audit — every task + acceptance criterion met",
+            "- [ ] F2. Code quality / diagnostics clean, idioms match, no dead code",
+            "- [ ] F3. Real manual QA — every criterion's channel scenario run with evidence + cleanup receipt",
+            "- [ ] F4. Scope fidelity — nothing extra, nothing Must-NOT-have introduced",
+            "",
+            "## Commit strategy",
+            "- Atomic Conventional Commits; each builds + tests green on its own.",
+            f"- Final footer: `Plan: plans/{path.name}`",
+            "",
+            "## Verification Evidence",
+            "- [ ] Record commands, outputs, transcripts, screenshots, and cleanup receipts that justify trust.",
+            "",
+        ]
+    )
+    path.write_text(content, encoding="utf-8")
+    record_event("plan_created", workspace=str(root), plan=str(path), brief=brief)
+    return path
+
+
+def unchecked_items(markdown: str) -> list[str]:
+    items: list[str] = []
+    for line in markdown.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("- [ ] "):
+            items.append(stripped[6:].strip())
+    return items
+
+
+_CRITERION_PATTERN = re.compile(r"^- \[[ xX]\]\s*(C\d+)\s*\|(.*)$")
+
+
+def extract_success_criteria(markdown: str) -> list[dict[str, str]]:
+    """Parse the plan's Success Criteria block.
+
+    Lines look like:
+      - [ ] C001 | channel: tmux | test: path::id | scenario: Happy path — ...
+    """
+    out: list[dict[str, str]] = []
+    for line in markdown.splitlines():
+        m = _CRITERION_PATTERN.match(line.strip())
+        if not m:
+            continue
+        crit: dict[str, str] = {"id": m.group(1), "qa_channel": "", "test_ref": "", "scenario": ""}
+        for field in m.group(2).split("|"):
+            if ":" not in field:
+                continue
+            key, _, value = field.partition(":")
+            key = key.strip().lower()
+            value = value.strip()
+            if key == "channel":
+                crit["qa_channel"] = value
+            elif key == "test":
+                crit["test_ref"] = value
+            elif key == "scenario":
+                crit["scenario"] = value
+        out.append(crit)
+    return out
+
+
+def build_notepad(task: str, criteria: list[dict[str, str]]) -> str:
+    crit_lines = [
+        f"- {c['id']} [{c.get('qa_channel') or '?'}] {c.get('scenario') or ''} (test: {c.get('test_ref') or '?'})"
+        for c in criteria
+    ] or ["- (define success criteria before claiming progress)"]
+    return "\n".join(
+        [
+            f"# Litwork Notepad — {task}",
+            f"Started: {utc_now().isoformat()}",
+            "",
+            "## Plan (exhaustively detailed)",
+            "<every atomic step, in order>",
+            "",
+            "## Success criteria + QA scenarios",
+            *crit_lines,
+            "",
+            "## Now",
+            "<the single step in progress>",
+            "",
+            "## Todo",
+            "<every remaining step, ordered>",
+            "",
+            "## Findings",
+            "<non-obvious facts with file:line refs>",
+            "",
+            "## Learnings",
+            "<patterns / pitfalls to remember next turn>",
+            "",
+        ]
+    )
+
+
+def record_criterion_event(run_dir: Path, criterion_id: str, kind: str, **fields: Any) -> None:
+    """Append a TDD/QA criterion event to the run ledger.
+
+    kinds: criterion_started, test_red_captured, test_green_captured,
+    scenario_executed, cleanup_receipt, criterion_complete, reviewer_verdict.
+    """
+    append_jsonl(
+        run_dir / "ledger.jsonl",
+        {"event": kind, "at": utc_now().isoformat(), "criterion_id": criterion_id, **fields},
+    )
+
+
+def find_plan(name: str, workspace: Path) -> Path | None:
+    plans = plan_dir(workspace)
+    if not plans.exists():
+        return None
+
+    raw = name.strip()
+    if not raw:
+        candidates = sorted(plans.glob("*.md"), key=lambda p: p.stat().st_mtime, reverse=True)
+        return candidates[0] if candidates else None
+
+    direct = Path(raw).expanduser()
+    if direct.exists():
+        return direct.resolve()
+
+    slug = slugify(raw, fallback=raw)
+    candidates = [
+        plans / raw,
+        plans / f"{raw}.md",
+        plans / slug,
+        plans / f"{slug}.md",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate.resolve()
+    return None
+
+
+def write_run_state(
+    workspace: Path,
+    *,
+    task: str,
+    command: str,
+    plan: Path | None = None,
+    completion_promise: str = "",
+    strategy: str = "continue",
+) -> Path:
+    rid = run_id("lithermes")
+    run_dir = lithermes_dir(workspace) / "runs" / rid
+    evidence_dir = run_dir / "evidence"
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+
+    criteria: list[dict[str, str]] = []
+    if plan and plan.exists():
+        try:
+            criteria = extract_success_criteria(plan.read_text(encoding="utf-8"))
+        except OSError:
+            criteria = []
+
+    notepad = run_dir / "notepad.md"
+    notepad.write_text(build_notepad(task, criteria), encoding="utf-8")
+
+    state = {
+        "run_id": rid,
+        "created_at": utc_now().isoformat(),
+        "workspace": str(workspace),
+        "command": command,
+        "task": task,
+        "completion_promise": completion_promise,
+        "strategy": strategy,
+        "plan": str(plan) if plan else "",
+        "evidence_dir": str(evidence_dir),
+        "notepad_path": str(notepad),
+        "criteria": criteria,
+        "active_criterion": criteria[0]["id"] if criteria else "",
+    }
+    (run_dir / "state.json").write_text(
+        json.dumps(state, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    append_jsonl(run_dir / "ledger.jsonl", {"event": "run_started", **state})
+    record_event("run_started", workspace=str(workspace), command=command, run_id=rid)
+    return run_dir
+
+
+def load_run_state(run_dir: Path) -> dict[str, Any]:
+    return json.loads((run_dir / "state.json").read_text(encoding="utf-8"))
+
+
+def build_run_agent_message(state: dict[str, Any]) -> str:
+    plan_line = f"\nPlan: {state['plan']}" if state.get("plan") else ""
+    promise = state.get("completion_promise") or "Complete the requested task with evidence."
+    plan_path = Path(state["plan"]) if state.get("plan") else None
+    workspace = Path(state["workspace"]) if state.get("workspace") else None
+    return "\n".join(
+        [
+            state["task"],
+            "",
+            build_goal_instruction(state["task"], plan=plan_path, workspace=workspace),
+            "",
+            "<lithermes-run-context>",
+            f"run_id: {state['run_id']}",
+            f"workspace: {state['workspace']}",
+            f"evidence_dir: {state['evidence_dir']}",
+            f"ledger: {Path(state['evidence_dir']).parent / 'ledger.jsonl'}",
+            f"strategy: {state['strategy']}",
+            f"completion_promise: {promise}",
+            f"task: {state['task']}{plan_line}",
+            "",
+            "Execute this LitHermes request now. Inspect the workspace as needed,",
+            "keep useful evidence under evidence_dir, append meaningful progress to the ledger,",
+            "and answer the user with the result instead of stopping after run creation.",
+            "Loop each criterion RED->GREEN->manual-QA->cleanup-receipt; when the work is risky, spans 3+",
+            "files, or the user demanded rigour, run the reviewer gate (delegate_task a strict reviewer)",
+            "and loop until UNCONDITIONAL approval before declaring done.",
+            "</lithermes-run-context>",
+        ]
+    )
+
+
+def build_dispatch_result(run_dir: Path, *, display: str) -> dict[str, str]:
+    state = load_run_state(run_dir)
+    return {
+        "display": display,
+        "agent_message": build_run_agent_message(state),
+        "run_dir": str(run_dir),
+    }
+
+
+def _join_positional(positional: Iterable[str]) -> str:
+    return " ".join(part for part in positional if part).strip()
+
+
+def build_plan_agent_message(brief: str, plan: Path, workspace: Path) -> str:
+    return "\n".join(
+        [
+            brief,
+            "",
+            build_goal_instruction(brief, plan=plan, workspace=workspace),
+            "",
+            "<lithermes-plan-context>",
+            f"workspace: {workspace}",
+            f"plan: {plan}",
+            "",
+            "Run the LitHermes planning process — load the lithermes:lit-plan skill and follow it.",
+            "The plan file above is a scaffold to FILL, not a finished plan:",
+            "1) classify the request size (trivial / standard / architecture);",
+            "2) explore-first — fan out read-only delegate_task children to gather repo + external",
+            "   facts BEFORE asking (discoverable facts -> explore; genuine preferences -> ask);",
+            "3) interview only the real unknowns;",
+            "4) APPROVAL GATE — present the facts found + remaining ambiguities (each with a",
+            "   recommended default) + the intended approach, then WAIT for the user's explicit okay;",
+            "5) fill the scaffold, keeping the parseable Success Criteria (C0NN | channel: | test: |",
+            "   scenario:) shape;",
+            "6) before finalizing, run a read-only pre-plan gap-analysis pass (contradictions,",
+            "   ambiguity, missing constraints, execution risks) and a plan-review pass (references",
+            "   resolve, tasks startable, QA scenarios concrete) and fold in the findings.",
+            "The native /goal is bound for you; track success criteria + evidence with the durable",
+            "goal tools (goal_set / goal_add_criterion / goal_evidence / goal_complete) and inspect",
+            "with `hermes lithermes goal status`.",
+            "</lithermes-plan-context>",
+        ]
+    )
+
+
+def command_lit_plan(raw_args: str) -> dict[str, str]:
+    args = parse_args(raw_args)
+    workspace = workspace_from_option(args.options.get("worktree"))
+    brief = _join_positional(args.positional)
+    path = create_plan(brief, workspace)
+    return {
+        "display": f"Created LitHermes plan: {path}\nForwarding goal bootstrap to Hermes agent now.",
+        "agent_message": build_plan_agent_message(brief, path, workspace),
+        "plan": str(path),
+    }
+
+
+def _command_lit_dispatch(raw_args: str, *, command: str) -> dict[str, str]:
+    args = parse_args(raw_args)
+    workspace = workspace_from_option(args.options.get("worktree"))
+    task = _join_positional(args.positional)
+    if not task:
+        raise ValueError('usage: /lit-loop "task" [--completion-promise TEXT] [--strategy reset|continue]')
+    completion = str(args.options.get("completion-promise") or "")
+    strategy = str(args.options.get("strategy") or "continue")
+    if strategy not in {"continue", "reset"}:
+        raise ValueError("--strategy must be either 'continue' or 'reset'")
+    run_dir = write_run_state(
+        workspace,
+        task=task,
+        command=command,
+        completion_promise=completion,
+        strategy=strategy,
+    )
+    promise = f"\nCompletion promise: {completion}" if completion else ""
+    display = (
+        f"Started LitHermes Litwork run: {run_dir}"
+        f"{promise}\nForwarding task to Hermes agent now."
+    )
+    return build_dispatch_result(run_dir, display=display)
+
+
+def command_lit_loop(raw_args: str) -> dict[str, str]:
+    return _command_lit_dispatch(raw_args, command="lit-loop")
+
+
+def command_lit(raw_args: str) -> dict[str, str]:
+    return _command_lit_dispatch(raw_args, command="lit")
+
+
+def _run_git(workspace: Path, args: list[str]) -> str:
+    import subprocess
+
+    try:
+        out = subprocess.run(
+            ["git", *args],
+            cwd=str(workspace),
+            capture_output=True,
+            text=True,
+            timeout=20,
+        )
+        return out.stdout if out.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def detect_run_command(workspace: Path) -> str:
+    pkg = workspace / "package.json"
+    if pkg.exists():
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+            scripts = data.get("scripts", {}) if isinstance(data, dict) else {}
+            for key in ("dev", "start", "serve"):
+                if key in scripts:
+                    return f"npm run {key}"
+        except Exception:
+            pass
+    if (workspace / "Makefile").exists():
+        return "make (see Makefile targets)"
+    if (workspace / "docker-compose.yml").exists() or (workspace / "compose.yaml").exists():
+        return "docker compose up"
+    return "(detect manually — no dev/start script found)"
+
+
+REVIEW_LANES = [
+    ("goal", "Goal & constraint verification — does the diff achieve the stated goal within every constraint; flag missed requirements, over-engineering, edge cases. Verdict PASS/FAIL + confidence."),
+    ("qa", "QA by execution — brainstorm 15+ scenarios (happy/boundary/error/regression), then actually run the app/surface and capture evidence. Verdict PASS/FAIL with per-scenario results."),
+    ("code-quality", "Code quality — staff-engineer review across correctness, patterns, naming, error handling, types, perf, tests, API design. Severity CRITICAL/MAJOR/MINOR/NITPICK. Verdict PASS/FAIL."),
+    ("security", "Security (supplementary) — input validation, authz, secrets, data exposure, deps/CVEs, path/file ops. Severity CRITICAL/HIGH/MEDIUM/LOW. Verdict PASS/FAIL."),
+    ("context", "Context mining — git history, issues/PRs, related systems, developer TODO/warnings the diff may have missed. Verdict PASS/FAIL + discovered context."),
+]
+
+
+def command_review_work(raw_args: str) -> dict[str, str]:
+    args = parse_args(raw_args)
+    workspace = workspace_from_option(args.options.get("worktree"))
+    base = str(args.options.get("base") or "HEAD~1")
+    changed = _run_git(workspace, ["diff", "--name-only", base]).strip()
+    diff = _run_git(workspace, ["diff", base])
+    if len(diff) > 60000:
+        diff = diff[:60000] + "\n... [diff truncated at 60k chars — lanes should read full files as needed]"
+    run_cmd = detect_run_command(workspace)
+    files_block = changed or "(no changed files detected vs " + base + ")"
+
+    lane_lines = []
+    for key, brief in REVIEW_LANES:
+        lane_lines.append(f"- lane[{key}]: {brief}")
+
+    agent_lines = [
+        "Run the LitHermes 5-lane review orchestrator on the current changes.",
+        "",
+        "<lithermes-review-work>",
+        f"workspace: {workspace}",
+        f"base: {base}",
+        f"run command (for QA lane): {run_cmd}",
+        "",
+        "Changed files:",
+        files_block,
+        "",
+        "Dispatch ALL FIVE lanes IN ONE delegate_task call — pass a `tasks` array of 5 entries,",
+        "each {goal: <lane brief>, context: <diff + changed files>}; children run in parallel and the",
+        "parent blocks until all five return:",
+        *lane_lines,
+        "",
+        "Each lane returns: verdict (PASS|FAIL), confidence, and findings with file:line.",
+        "Aggregate + dedupe findings across lanes. Gate is ALL-OR-NOTHING:",
+        "ANY lane FAIL => REVIEW FAILED (list blocking issues, prioritised by severity);",
+        "all five PASS => REVIEW PASSED (non-blocking suggestions only).",
+        "Load the lithermes:review-work skill for the full lane prompts and output contract.",
+        "",
+        "Diff under review:",
+        "```diff",
+        diff.strip() or "(empty diff)",
+        "```",
+        "</lithermes-review-work>",
+    ]
+    return {
+        "display": (
+            f"LitHermes review-work: 5 lanes over {base} "
+            f"({len([f for f in changed.splitlines() if f.strip()])} changed files). "
+            "Dispatching parallel review now."
+        ),
+        "agent_message": "\n".join(agent_lines),
+    }
+
+
+def command_litgoal(raw_args: str) -> dict[str, str]:
+    args = parse_args(raw_args)
+    workspace = workspace_from_option(args.options.get("worktree"))
+    objective = _join_positional(args.positional)
+    intro = (
+        "Opened the LitHermes litgoal durable runtime."
+        if objective
+        else "LitHermes litgoal runtime."
+    )
+    agent_lines = [
+        objective or "Inspect and drive the active LitHermes litgoal.",
+        "",
+        "<lithermes-litgoal-command>",
+        f"workspace: {workspace}",
+        "Durable goal state lives under .hermes/lithermes/litgoal/ (goals.json + ledger.jsonl + evidence/).",
+        "Drive it through the model-facing goal tools, not prose:",
+        "- goal_status to read the active objective, criteria, evidence, and quality gate;",
+        "- goal_set to declare the objective and upfront success criteria (happy/edge/regression);",
+        "- goal_add_criterion / goal_evidence (red|green|scenario|cleanup) / goal_criterion_status as you work;",
+        "- goal_steer to redirect, goal_checkpoint to snapshot for resume;",
+        "- goal_complete only succeeds once the quality gate passes (every criterion has green + scenario",
+        "  evidence and no unresolved review blocker). Inspect anytime with: hermes lithermes goal status.",
+        "Load the lithermes:litgoal skill for the full discipline.",
+        "</lithermes-litgoal-command>",
+    ]
+    return {
+        "display": f"{intro}\nState dir: {lithermes_dir(workspace) / 'litgoal'}",
+        "agent_message": "\n".join(agent_lines),
+    }
+
+
+def command_start_work(raw_args: str) -> str | dict[str, str]:
+    args = parse_args(raw_args)
+    workspace = workspace_from_option(args.options.get("worktree"))
+    plan_name = _join_positional(args.positional)
+    dry_run = bool(args.options.get("dry-run"))
+    plan = find_plan(plan_name, workspace)
+
+    # No-plan bootstrap: /start-work with a brief but no matching plan creates the
+    # plan first (treating start-work as approval to bootstrap), then proceeds.
+    bootstrapped = False
+    if plan is None:
+        if not plan_name:
+            raise ValueError(
+                f"no plan found in {plan_dir(workspace)} and no brief given to bootstrap one"
+            )
+        if dry_run:
+            return (
+                f"LitHermes dry-run: no plan named '{plan_name}' found; "
+                f"would bootstrap a new plan from it in {plan_dir(workspace)}."
+            )
+        plan = create_plan(plan_name, workspace)
+        bootstrapped = True
+
+    text = plan.read_text(encoding="utf-8")
+    open_items = unchecked_items(text)
+    if dry_run:
+        preview = "\n".join(f"- {item}" for item in open_items[:8]) or "- no unchecked items found"
+        return f"LitHermes dry-run for {plan}:\n{preview}"
+
+    run_dir = write_run_state(
+        workspace,
+        task=f"Start work from {plan.name}",
+        command="start-work",
+        plan=plan,
+    )
+    first_items = "\n".join(f"- {item}" for item in open_items[:5]) or "- no unchecked items found"
+    display = (
+        f"{'Bootstrapped a new plan and started' if bootstrapped else 'Started'} "
+        f"LitHermes work run: {run_dir}\n"
+        f"Plan: {plan}\n"
+        f"Open items:\n{first_items}"
+    )
+    return {
+        "display": display,
+        "agent_message": build_run_agent_message(load_run_state(run_dir)),
+    }