lithermes-ai 0.5.0

package/assets/lithermes-plugin/litgoal/__init__.py

@@ -0,0 +1,10 @@
+"""LitHermes litgoal durable runtime.
+
+Layers durable artifacts (criteria, evidence ledger, checkpoints, steering
+history, quality gate, review blockers) on top of Hermes' native goal/subgoal
+system. State persists under <workspace>/.hermes/lithermes/litgoal/.
+"""
+
+from __future__ import annotations
+
+from . import model, store, runtime, tools, cli, hook  # noqa: F401

package/assets/lithermes-plugin/litgoal/cli.py

@@ -0,0 +1,133 @@
+"""`hermes lithermes goal ...` CLI surface for the litgoal durable runtime.
+
+Registered via ctx.register_cli_command("goal", help, setup_fn, handler_fn).
+setup_fn receives an argparse subparser; handler_fn(args) dispatches.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from . import runtime, store
+
+
+def _ws(args) -> Path:
+    val = getattr(args, "workspace", None)
+    return Path(val).expanduser().resolve() if val else Path.cwd()
+
+
+def setup(parser) -> None:
+    parser.add_argument("--workspace", help="workspace root (default: cwd)")
+    sub = parser.add_subparsers(dest="goal_cmd")
+
+    p_set = sub.add_parser("set", help="create the active goal")
+    p_set.add_argument("--objective", required=True)
+    p_set.add_argument("--title", default="")
+    p_set.add_argument("--criterion", action="append", default=[],
+                       help="scenario|qa_channel|test_ref (repeatable)")
+
+    sub.add_parser("status", help="show the active goal + quality gate")
+    sub.add_parser("show", help="dump raw goals.json")
+
+    p_crit = sub.add_parser("criterion", help="add a success criterion")
+    p_crit.add_argument("--scenario", required=True)
+    p_crit.add_argument("--qa-channel", default="")
+    p_crit.add_argument("--test-ref", default="")
+
+    p_ev = sub.add_parser("evidence", help="attach evidence to a criterion")
+    p_ev.add_argument("criterion_id")
+    p_ev.add_argument("--kind", required=True, choices=["red", "green", "scenario", "cleanup", "note"])
+    p_ev.add_argument("--ref", required=True)
+    p_ev.add_argument("--detail", default="")
+
+    p_st = sub.add_parser("criterion-status", help="set a criterion status")
+    p_st.add_argument("criterion_id")
+    p_st.add_argument("status", choices=["pending", "in_progress", "blocked", "pass", "fail"])
+
+    p_steer = sub.add_parser("steer", help="record a steering directive")
+    p_steer.add_argument("directive")
+
+    p_cp = sub.add_parser("checkpoint", help="record a checkpoint")
+    p_cp.add_argument("summary")
+    p_cp.add_argument("--active-criterion", default="")
+
+    p_bl = sub.add_parser("blocker", help="add a review blocker")
+    p_bl.add_argument("detail")
+    p_rb = sub.add_parser("resolve-blocker", help="resolve a review blocker")
+    p_rb.add_argument("blocker_id")
+
+    sub.add_parser("complete", help="attempt to complete the goal (gated)")
+
+
+def handle(args) -> int:
+    ws = _ws(args)
+    cmd = getattr(args, "goal_cmd", None)
+    if cmd == "set":
+        criteria = []
+        for raw in args.criterion:
+            parts = (raw.split("|") + ["", "", ""])[:3]
+            criteria.append({"scenario": parts[0], "qa_channel": parts[1], "test_ref": parts[2]})
+        runtime.create_goal(ws, args.objective, title=args.title, criteria=criteria)
+        return _print_status(ws)
+    if cmd in (None, "status"):
+        return _print_status(ws)
+    if cmd == "show":
+        print(store.goals_path(ws).read_text(encoding="utf-8") if store.goals_path(ws).exists() else "{}")
+        return 0
+    if cmd == "criterion":
+        crit = runtime.add_criterion(ws, args.scenario, qa_channel=args.qa_channel, test_ref=args.test_ref)
+        print(f"added {crit.id}")
+        return _print_status(ws)
+    if cmd == "evidence":
+        runtime.add_evidence(ws, args.criterion_id, args.kind, args.ref, args.detail)
+        return _print_status(ws)
+    if cmd == "criterion-status":
+        runtime.set_criterion_status(ws, args.criterion_id, args.status)
+        return _print_status(ws)
+    if cmd == "steer":
+        runtime.record_steering(ws, args.directive)
+        return _print_status(ws)
+    if cmd == "checkpoint":
+        runtime.record_checkpoint(ws, args.summary, active_criterion=args.active_criterion)
+        return _print_status(ws)
+    if cmd == "blocker":
+        b = runtime.add_review_blocker(ws, args.detail)
+        print(f"blocker {b.id}")
+        return _print_status(ws)
+    if cmd == "resolve-blocker":
+        runtime.resolve_review_blocker(ws, args.blocker_id)
+        return _print_status(ws)
+    if cmd == "complete":
+        result = runtime.complete_goal(ws)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0 if result.get("completed") else 1
+    return _print_status(ws)
+
+
+def _print_status(ws: Path) -> int:
+    goal = runtime.get_active(ws)
+    if goal is None:
+        print("no active litgoal")
+        return 0
+    gate = runtime.quality_gate(ws)
+    print(f"goal {goal.id} [{goal.status}]: {goal.objective}")
+    for c in goal.criteria:
+        kinds = ",".join(sorted({e.kind for e in c.evidence})) or "-"
+        print(f"  {c.id} [{c.status}] {c.scenario}  channel={c.qa_channel or '-'} evidence={kinds}")
+    for b in goal.review_blockers:
+        flag = "resolved" if b.resolved else "OPEN"
+        print(f"  blocker {b.id} [{flag}] {b.detail}")
+    print(f"quality gate: {'PASS' if gate['passed'] else 'CLOSED'}")
+    for r in gate["reasons"]:
+        print(f"  - {r}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="hermes lithermes goal")
+    setup(parser)
+    args = parser.parse_args(argv)
+    return handle(args)

package/assets/lithermes-plugin/litgoal/hook.py

@@ -0,0 +1,48 @@
+"""pre_llm_call snapshot injection for the active litgoal.
+
+Returns a compact context block reminding the model of the live objective, the
+next unmet criteria, unresolved review blockers, and that completion is gated on
+proven evidence. Returns None when no active goal exists.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import runtime
+
+
+def snapshot_context(**kwargs: Any) -> str | None:
+    workspace = Path.cwd()
+    try:
+        goal = runtime.get_active(workspace)
+    except Exception:
+        return None
+    if goal is None or goal.status == "complete":
+        return None
+
+    gate = runtime.quality_gate(workspace)
+    open_crit = [c for c in goal.criteria if c.status != "pass"]
+    lines = [
+        "<lithermes-litgoal-snapshot>",
+        f"Active goal {goal.id}: {goal.objective}",
+    ]
+    if goal.steering:
+        lines.append(f"Latest steering: {goal.steering[-1].directive}")
+    if not goal.criteria:
+        lines.append("No success criteria yet — define them (goal_add_criterion) before claiming progress.")
+    for crit in open_crit:
+        kinds = sorted({e.kind for e in crit.evidence})
+        missing = [k for k in ("green", "scenario") if k not in kinds]
+        miss = f" missing: {', '.join(missing)}" if missing else ""
+        lines.append(f"- {crit.id} [{crit.status}] {crit.scenario} (channel {crit.qa_channel or '?'}).{miss}")
+    unresolved = [b for b in goal.review_blockers if not b.resolved]
+    for blocker in unresolved:
+        lines.append(f"- BLOCKER {blocker.id}: {blocker.detail}")
+    if gate["passed"]:
+        lines.append("Quality gate: PASS — you may call goal_complete.")
+    else:
+        lines.append("Quality gate: CLOSED — goal_complete is refused until every criterion has green + scenario evidence and blockers are resolved.")
+    lines.append("</lithermes-litgoal-snapshot>")
+    return "\n".join(lines)

package/assets/lithermes-plugin/litgoal/model.py

@@ -0,0 +1,171 @@
+"""Durable litgoal data model.
+
+Plain dataclasses with explicit (de)serialization so state survives across turns
+and sessions as human-auditable JSON.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+STATE_VERSION = 1
+
+CRITERION_STATUSES = ("pending", "in_progress", "blocked", "pass", "fail")
+GOAL_STATUSES = ("active", "blocked", "complete")
+EVIDENCE_KINDS = ("red", "green", "scenario", "cleanup", "note")
+# Structured steering kinds. Steering can redirect or extend the goal; it can
+# NEVER weaken the completion gate (see runtime._weakening_reason).
+STEERING_KINDS = ("redirect", "add_criterion", "narrow_scope", "reprioritize", "annotate")
+
+
+@dataclass
+class Evidence:
+    kind: str
+    ref: str
+    detail: str = ""
+    at: str = ""
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "Evidence":
+        return Evidence(
+            kind=str(d.get("kind", "note")),
+            ref=str(d.get("ref", "")),
+            detail=str(d.get("detail", "")),
+            at=str(d.get("at", "")),
+        )
+
+
+@dataclass
+class Criterion:
+    id: str
+    scenario: str
+    qa_channel: str = ""
+    test_ref: str = ""
+    status: str = "pending"
+    evidence: list[Evidence] = field(default_factory=list)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "Criterion":
+        return Criterion(
+            id=str(d.get("id", "")),
+            scenario=str(d.get("scenario", "")),
+            qa_channel=str(d.get("qa_channel", "")),
+            test_ref=str(d.get("test_ref", "")),
+            status=str(d.get("status", "pending")),
+            evidence=[Evidence.from_dict(e) for e in d.get("evidence", []) or []],
+        )
+
+
+@dataclass
+class Checkpoint:
+    id: str
+    at: str
+    summary: str
+    active_criterion: str = ""
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "Checkpoint":
+        return Checkpoint(
+            id=str(d.get("id", "")),
+            at=str(d.get("at", "")),
+            summary=str(d.get("summary", "")),
+            active_criterion=str(d.get("active_criterion", "")),
+        )
+
+
+@dataclass
+class Steering:
+    id: str
+    at: str
+    directive: str
+    kind: str = "redirect"
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "Steering":
+        return Steering(
+            id=str(d.get("id", "")),
+            at=str(d.get("at", "")),
+            directive=str(d.get("directive", "")),
+            kind=str(d.get("kind", "redirect")),
+        )
+
+
+@dataclass
+class ReviewBlocker:
+    id: str
+    detail: str
+    resolved: bool = False
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "ReviewBlocker":
+        return ReviewBlocker(
+            id=str(d.get("id", "")),
+            detail=str(d.get("detail", "")),
+            resolved=bool(d.get("resolved", False)),
+        )
+
+
+@dataclass
+class Goal:
+    id: str
+    objective: str
+    title: str = ""
+    status: str = "active"
+    criteria: list[Criterion] = field(default_factory=list)
+    checkpoints: list[Checkpoint] = field(default_factory=list)
+    steering: list[Steering] = field(default_factory=list)
+    review_blockers: list[ReviewBlocker] = field(default_factory=list)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "Goal":
+        return Goal(
+            id=str(d.get("id", "")),
+            objective=str(d.get("objective", "")),
+            title=str(d.get("title", "")),
+            status=str(d.get("status", "active")),
+            criteria=[Criterion.from_dict(c) for c in d.get("criteria", []) or []],
+            checkpoints=[Checkpoint.from_dict(c) for c in d.get("checkpoints", []) or []],
+            steering=[Steering.from_dict(s) for s in d.get("steering", []) or []],
+            review_blockers=[ReviewBlocker.from_dict(b) for b in d.get("review_blockers", []) or []],
+        )
+
+
+@dataclass
+class LitgoalState:
+    version: int = STATE_VERSION
+    created_at: str = ""
+    updated_at: str = ""
+    active_goal_id: str = ""
+    goals: list[Goal] = field(default_factory=list)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "LitgoalState":
+        return LitgoalState(
+            version=int(d.get("version", STATE_VERSION)),
+            created_at=str(d.get("created_at", "")),
+            updated_at=str(d.get("updated_at", "")),
+            active_goal_id=str(d.get("active_goal_id", "")),
+            goals=[Goal.from_dict(g) for g in d.get("goals", []) or []],
+        )
+
+    def active_goal(self) -> Goal | None:
+        for g in self.goals:
+            if g.id == self.active_goal_id:
+                return g
+        return None
+
+    def goal_by_id(self, goal_id: str) -> Goal | None:
+        for g in self.goals:
+            if g.id == goal_id:
+                return g
+        return None
+
+
+def to_dict(obj: Any) -> Any:
+    """Recursive dataclass→dict that preserves field order and nested lists."""
+    from dataclasses import asdict, is_dataclass
+
+    if is_dataclass(obj):
+        return asdict(obj)
+    return obj

package/assets/lithermes-plugin/litgoal/runtime.py

@@ -0,0 +1,273 @@
+"""Litgoal lifecycle operations on top of the durable store.
+
+Every mutation: load -> mutate -> save -> append a typed ledger event. The
+quality gate is the completion contract — a goal cannot complete until every
+criterion is proven (status=pass + RED/GREEN + manual-QA scenario evidence) and
+no review blocker is unresolved.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from . import model, store
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _next_id(prefix: str, existing: list[str]) -> str:
+    n = 1
+    used = set(existing)
+    while f"{prefix}{n:03d}" in used:
+        n += 1
+    return f"{prefix}{n:03d}"
+
+
+# -- goal lifecycle ---------------------------------------------------------
+
+def create_goal(
+    workspace: Path,
+    objective: str,
+    *,
+    title: str = "",
+    criteria: list[dict[str, Any]] | None = None,
+) -> model.Goal:
+    objective = (objective or "").strip()
+    if not objective:
+        raise ValueError("objective must be non-empty")
+    state = store.load_or_create(workspace)
+    goal_id = _next_id("G", [g.id for g in state.goals])
+    goal = model.Goal(id=goal_id, objective=objective, title=title.strip())
+    for spec in criteria or []:
+        goal.criteria.append(
+            model.Criterion(
+                id=_next_id("C", [c.id for c in goal.criteria]),
+                scenario=str(spec.get("scenario", "")).strip(),
+                qa_channel=str(spec.get("qa_channel", "")).strip(),
+                test_ref=str(spec.get("test_ref", "")).strip(),
+            )
+        )
+    state.goals.append(goal)
+    state.active_goal_id = goal_id
+    store.save(workspace, state)
+    store.append_ledger(workspace, {"kind": "goal_created", "goal_id": goal_id, "objective": objective})
+    return goal
+
+
+def get_active(workspace: Path) -> model.Goal | None:
+    return store.load_or_create(workspace).active_goal()
+
+
+def _require_active(state: model.LitgoalState) -> model.Goal:
+    goal = state.active_goal()
+    if goal is None:
+        raise ValueError("no active litgoal — create one first")
+    return goal
+
+
+# -- criteria + evidence ----------------------------------------------------
+
+def add_criterion(
+    workspace: Path,
+    scenario: str,
+    *,
+    qa_channel: str = "",
+    test_ref: str = "",
+) -> model.Criterion:
+    state = store.load_or_create(workspace)
+    goal = _require_active(state)
+    crit = model.Criterion(
+        id=_next_id("C", [c.id for c in goal.criteria]),
+        scenario=scenario.strip(),
+        qa_channel=qa_channel.strip(),
+        test_ref=test_ref.strip(),
+    )
+    goal.criteria.append(crit)
+    store.save(workspace, state)
+    store.append_ledger(workspace, {"kind": "criterion_added", "goal_id": goal.id, "criterion_id": crit.id})
+    return crit
+
+
+def set_criterion_status(workspace: Path, criterion_id: str, status: str) -> None:
+    if status not in model.CRITERION_STATUSES:
+        raise ValueError(f"invalid criterion status '{status}' (valid: {model.CRITERION_STATUSES})")
+    state = store.load_or_create(workspace)
+    goal = _require_active(state)
+    for crit in goal.criteria:
+        if crit.id == criterion_id:
+            crit.status = status
+            store.save(workspace, state)
+            store.append_ledger(
+                workspace,
+                {"kind": "criterion_status", "criterion_id": criterion_id, "status": status},
+            )
+            return
+    raise ValueError(f"criterion '{criterion_id}' not found")
+
+
+def add_evidence(
+    workspace: Path,
+    criterion_id: str,
+    kind: str,
+    ref: str,
+    detail: str = "",
+) -> model.Evidence:
+    if kind not in model.EVIDENCE_KINDS:
+        raise ValueError(f"invalid evidence kind '{kind}' (valid: {model.EVIDENCE_KINDS})")
+    state = store.load_or_create(workspace)
+    goal = _require_active(state)
+    for crit in goal.criteria:
+        if crit.id == criterion_id:
+            ev = model.Evidence(kind=kind, ref=ref, detail=detail, at=_utc_now())
+            crit.evidence.append(ev)
+            store.save(workspace, state)
+            store.append_ledger(
+                workspace,
+                {"kind": "evidence_added", "criterion_id": criterion_id, "evidence_kind": kind, "ref": ref},
+            )
+            return ev
+    raise ValueError(f"criterion '{criterion_id}' not found")
+
+
+# -- checkpoints + steering -------------------------------------------------
+
+def record_checkpoint(workspace: Path, summary: str, *, active_criterion: str = "") -> model.Checkpoint:
+    state = store.load_or_create(workspace)
+    goal = _require_active(state)
+    cp = model.Checkpoint(
+        id=_next_id("K", [c.id for c in goal.checkpoints]),
+        at=_utc_now(),
+        summary=summary.strip(),
+        active_criterion=active_criterion.strip(),
+    )
+    goal.checkpoints.append(cp)
+    store.save(workspace, state)
+    store.append_ledger(workspace, {"kind": "checkpoint", "goal_id": goal.id, "checkpoint_id": cp.id})
+    return cp
+
+
+# Directives that try to weaken the completion contract are refused: steering can
+# redirect or extend the work, never lower the evidence bar or force completion.
+_STEERING_WEAKENS = [
+    re.compile(pattern, re.IGNORECASE)
+    for pattern in (
+        r"\bskip(p?ing)?\s+(the\s+|all\s+)?(unit\s+|integration\s+)?tests?\b",
+        r"\bbypass(ing)?\s+(the\s+)?(quality\s+)?(gate|tests?|qa|review|criteri)",
+        r"\bdisabl(e|ing)\s+(the\s+)?(tests?|gate|check|qa)",
+        r"\bwithout\s+(running\s+|a\s+|any\s+)?(tests?|qa|review|evidence)",
+        r"\bauto[-\s]?complet",
+        r"\b(force|mark)\s+\w*\s*complet",
+        r"\bignore\s+(the\s+)?(criteri|tests?|gate|evidence|qa)",
+        r"\b(lower|relax|loosen)\s+(the\s+)?(bar|gate|criteri|standard)",
+        r"\bskip\s+(the\s+)?(qa|review|gate|verification|evidence)",
+    )
+]
+
+
+def _weakening_reason(directive: str) -> str | None:
+    for pattern in _STEERING_WEAKENS:
+        if pattern.search(directive):
+            return f"directive matches a completion-weakening pattern ({pattern.pattern})"
+    return None
+
+
+def record_steering(workspace: Path, directive: str, *, kind: str = "redirect") -> model.Steering:
+    if kind not in model.STEERING_KINDS:
+        raise ValueError(f"invalid steering kind '{kind}' (valid: {model.STEERING_KINDS})")
+    reason = _weakening_reason(directive)
+    if reason is not None:
+        raise ValueError(
+            f"steering refused: {reason}. Steering can redirect or extend the goal, "
+            "but never weaken the completion gate (skip tests/QA/review or auto-complete)."
+        )
+    state = store.load_or_create(workspace)
+    goal = _require_active(state)
+    st = model.Steering(
+        id=_next_id("S", [s.id for s in goal.steering]),
+        at=_utc_now(),
+        directive=directive.strip(),
+        kind=kind,
+    )
+    goal.steering.append(st)
+    store.save(workspace, state)
+    store.append_ledger(
+        workspace,
+        {"kind": "steer", "goal_id": goal.id, "steering_id": st.id, "steer_kind": kind},
+    )
+    return st
+
+
+# -- review blockers --------------------------------------------------------
+
+def add_review_blocker(workspace: Path, detail: str) -> model.ReviewBlocker:
+    state = store.load_or_create(workspace)
+    goal = _require_active(state)
+    blocker = model.ReviewBlocker(
+        id=_next_id("B", [b.id for b in goal.review_blockers]),
+        detail=detail.strip(),
+    )
+    goal.review_blockers.append(blocker)
+    store.save(workspace, state)
+    store.append_ledger(workspace, {"kind": "review_blocker", "goal_id": goal.id, "blocker_id": blocker.id})
+    return blocker
+
+
+def resolve_review_blocker(workspace: Path, blocker_id: str) -> None:
+    state = store.load_or_create(workspace)
+    goal = _require_active(state)
+    for blocker in goal.review_blockers:
+        if blocker.id == blocker_id:
+            blocker.resolved = True
+            store.save(workspace, state)
+            store.append_ledger(
+                workspace, {"kind": "review_blocker_resolved", "blocker_id": blocker_id}
+            )
+            return
+    raise ValueError(f"review blocker '{blocker_id}' not found")
+
+
+# -- quality gate + completion ---------------------------------------------
+
+def _evaluate_gate(goal: model.Goal) -> dict[str, Any]:
+    reasons: list[str] = []
+    if not goal.criteria:
+        reasons.append("no success criteria defined")
+    for crit in goal.criteria:
+        kinds = {e.kind for e in crit.evidence}
+        if crit.status != "pass":
+            reasons.append(f"{crit.id} status is '{crit.status}' (need 'pass')")
+        if "green" not in kinds:
+            reasons.append(f"{crit.id} missing RED->GREEN proof (green evidence)")
+        if "scenario" not in kinds:
+            reasons.append(f"{crit.id} missing manual-QA scenario evidence")
+    for blocker in goal.review_blockers:
+        if not blocker.resolved:
+            reasons.append(f"unresolved review blocker {blocker.id}: {blocker.detail}")
+    return {"passed": len(reasons) == 0, "reasons": reasons, "goal_id": goal.id}
+
+
+def quality_gate(workspace: Path, goal_id: str | None = None) -> dict[str, Any]:
+    state = store.load_or_create(workspace)
+    goal = state.goal_by_id(goal_id) if goal_id else state.active_goal()
+    if goal is None:
+        return {"passed": False, "reasons": ["no active goal"]}
+    return _evaluate_gate(goal)
+
+
+def complete_goal(workspace: Path) -> dict[str, Any]:
+    # Single load: evaluate the gate and mutate the same state to avoid any
+    # read-decide-read race between the gate check and the completion write.
+    state = store.load_or_create(workspace)
+    goal = _require_active(state)
+    gate = _evaluate_gate(goal)
+    if not gate["passed"]:
+        return {"completed": False, "reasons": gate["reasons"]}
+    goal.status = "complete"
+    store.save(workspace, state)
+    store.append_ledger(workspace, {"kind": "goal_completed", "goal_id": goal.id})
+    return {"completed": True, "goal_id": goal.id}