@litfamily/lithermes 1.0.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, and review blockers) as the authoritative durable goal
+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,207 @@
+"""`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 model, runtime, store
+from .tools import NATIVE_GOAL_CAPABILITY
+
+
+def _ws(args) -> Path:
+    val = getattr(args, "workspace", None)
+    return Path(val).expanduser().resolve() if val else Path.cwd()
+
+
+def _session(args) -> str:
+    return str(getattr(args, "session_id", "") or "")
+
+
+def _force(args) -> bool:
+    return bool(getattr(args, "force", False))
+
+
+def setup(parser) -> None:
+    parser.add_argument("--workspace", help="workspace root (default: cwd)")
+    parser.add_argument(
+        "--session-id",
+        dest="session_id",
+        default="",
+        help="scope state to .hermes/lithermes/litgoal/sessions/<id>/ so new work "
+             "opens new state instead of writing into a finished aggregate",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="allow mutating a COMPLETED goal, overwriting finished evidence. "
+             "Prefer --session-id <new-id> for new work.",
+    )
+    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=list(model.CRITERION_STATUSES))
+
+    p_steer = sub.add_parser("steer", help="record a steering directive")
+    p_steer.add_argument("directive")
+    p_steer.add_argument("--kind", default="redirect", choices=list(model.STEERING_KINDS),
+                         help="add_criterion is structural; every other kind is annotation-only")
+    p_steer.add_argument("--evidence", required=True,
+                         help="REQUIRED: what you observed that forced the change")
+    p_steer.add_argument("--rationale", required=True,
+                         help="REQUIRED: why that observation changes the plan")
+
+    p_gs = sub.add_parser("goal-status", help="set the active goal status (not completion)")
+    p_gs.add_argument("status", choices=[s for s in model.GOAL_STATUSES if s != "complete"])
+
+    sub.add_parser("sessions", help="list session-scoped litgoal states")
+
+    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)
+    sid = _session(args)
+    force = _force(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, session_id=sid)
+        return _print_status(ws, sid)
+    if cmd == "sessions":
+        sessions = store.list_sessions(ws)
+        print("\n".join(sessions) if sessions else "no session-scoped litgoal state")
+        return 0
+    if cmd in (None, "status"):
+        return _print_status(ws, sid)
+    if cmd == "show":
+        path = store.goals_path(ws, sid)
+        print(path.read_text(encoding="utf-8") if path.exists() else "{}")
+        return 0
+    if cmd == "criterion":
+        crit = runtime.add_criterion(
+            ws, args.scenario, qa_channel=args.qa_channel, test_ref=args.test_ref,
+            session_id=sid, force=force,
+        )
+        print(f"added {crit.id}")
+        return _print_status(ws, sid)
+    if cmd == "evidence":
+        runtime.add_evidence(
+            ws, args.criterion_id, args.kind, args.ref, args.detail, session_id=sid, force=force
+        )
+        return _print_status(ws, sid)
+    if cmd == "criterion-status":
+        attempt = runtime.set_criterion_status(
+            ws, args.criterion_id, args.status, session_id=sid, force=force
+        )
+        print(f"{args.criterion_id} attempt {attempt}")
+        return _print_status(ws, sid)
+    if cmd == "steer":
+        try:
+            runtime.record_steering(
+                ws, args.directive, kind=args.kind, evidence=args.evidence,
+                rationale=args.rationale, session_id=sid, force=force,
+            )
+        except ValueError as exc:
+            runtime.record_steering_rejection(
+                ws, args.directive, str(exc), kind=args.kind, session_id=sid
+            )
+            print(f"steering rejected: {exc}")
+            return 1
+        return _print_status(ws, sid)
+    if cmd == "goal-status":
+        runtime.set_goal_status(ws, args.status, session_id=sid, force=force)
+        return _print_status(ws, sid)
+    if cmd == "checkpoint":
+        runtime.record_checkpoint(
+            ws, args.summary, active_criterion=args.active_criterion, session_id=sid, force=force
+        )
+        return _print_status(ws, sid)
+    if cmd == "blocker":
+        b = runtime.add_review_blocker(ws, args.detail, session_id=sid, force=force)
+        print(f"blocker {b.id}")
+        return _print_status(ws, sid)
+    if cmd == "resolve-blocker":
+        runtime.resolve_review_blocker(ws, args.blocker_id, session_id=sid, force=force)
+        return _print_status(ws, sid)
+    if cmd == "complete":
+        result = runtime.complete_goal(ws, session_id=sid, force=force)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0 if result.get("completed") else 1
+    return _print_status(ws, sid)
+
+
+def _print_status(ws: Path, session_id: str = "") -> int:
+    capability = NATIVE_GOAL_CAPABILITY
+    print(
+        "native goal capability: "
+        f"mode={capability['mode']} state={capability['state']}"
+    )
+    print(f"native goal reason: {capability['reason']}")
+    if session_id:
+        print(f"session: {session_id}")
+    goal = runtime.get_active(ws, session_id)
+    if goal is None:
+        print("no active litgoal")
+        return 0
+    gate = runtime.quality_gate(ws, session_id=session_id)
+    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 '-'} "
+            f"attempt={c.attempt} 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,81 @@
+"""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
+
+try:
+    from ..session_context import is_delegate_child_platform
+except ImportError:  # standalone litgoal tests import this package at top level
+    from session_context import is_delegate_child_platform
+from . import model, runtime
+
+
+def snapshot_context(**kwargs: Any) -> str | None:
+    if is_delegate_child_platform(str(kwargs.get("platform") or "")):
+        return None
+    workspace = Path.cwd()
+    session_id = str(kwargs.get("session_id") or kwargs.get("task_id") or "")
+    try:
+        goal = runtime.get_active(workspace, session_id)
+    except Exception:
+        return None
+    if goal is None or goal.status == "complete":
+        return None
+
+    gate = runtime.quality_gate(workspace, session_id=session_id)
+    open_crit = [
+        c
+        for c in goal.criteria
+        if c.status != "pass"
+        or not {"green", "scenario"}.issubset(runtime.current_attempt_evidence_kinds(c))
+    ]
+    stalled = goal.status in model.GOAL_STALLED_STATUSES
+    lines = [
+        "<lithermes-litgoal-snapshot>",
+        "schema_version: lithermes_llm_contract/v1",
+        "#contract.activation: active litgoal snapshot is in force for this turn.",
+        "#contract.inputs: criteria, blockers, and evidence below are durable state, not optional prose.",
+        "#contract.outputs: do not claim completion until the quality gate allows goal_complete.",
+        "#contract.evidence: every passed criterion needs green + scenario evidence.",
+        "#contract.hard_stops: unresolved blockers or missing evidence keep the gate closed.",
+        f"Active goal {goal.id} [{goal.status}]: {goal.objective}",
+    ]
+    if stalled:
+        lines.append(
+            "STALLED: this goal is '{0}'. Do not keep implementing — resolve the "
+            "blocker or get the user's decision first.".format(goal.status)
+        )
+    if goal.steering:
+        latest = goal.steering[-1]
+        lines.append(
+            "Latest steering [{0}]: {1} | evidence: {2} | rationale: {3}".format(
+                latest.kind, latest.directive, latest.evidence or "-", latest.rationale or "-"
+            )
+        )
+    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(runtime.current_attempt_evidence_kinds(crit))
+        missing = [k for k in ("green", "scenario") if k not in kinds]
+        miss = f" missing: {', '.join(missing)}" if missing else ""
+        attempt = f" attempt {crit.attempt}" if int(crit.attempt or 1) > 1 else ""
+        lines.append(
+            f"- {crit.id} [{crit.status}]{attempt} {crit.scenario} "
+            f"(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,203 @@
+"""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", "needs_user_decision", "pass", "fail",
+)
+# `review_blocked` is set automatically while an unresolved review blocker exists
+# and cleared when the last one resolves; `needs_user_decision` is set by hand when
+# work cannot proceed without an answer only the user can give. Both were
+# previously unrepresentable, so a stalled goal was indistinguishable from a
+# running one by status alone.
+GOAL_STATUSES = (
+    "active", "review_blocked", "needs_user_decision", "blocked", "complete",
+)
+# A goal in one of these states is stalled: it is not complete, and no further
+# progress is expected until something outside the loop changes.
+GOAL_STALLED_STATUSES = ("review_blocked", "needs_user_decision", "blocked")
+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 = ""
+    # Which attempt of the criterion produced this. Evidence is append-only, so a
+    # retry never overwrites a prior record; the attempt number is what lets a
+    # reader tell attempt-1 evidence from attempt-2 evidence for the same criterion.
+    attempt: int = 1
+
+    @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", "")),
+            attempt=int(d.get("attempt", 1) or 1),
+        )
+
+
+@dataclass
+class Criterion:
+    id: str
+    scenario: str
+    qa_channel: str = ""
+    test_ref: str = ""
+    status: str = "pending"
+    # Bumped when a criterion leaves a terminal-negative state (fail/blocked) and
+    # is picked back up. Evidence artifacts are written under a per-attempt
+    # directory so a retry cannot overwrite what the previous attempt proved.
+    attempt: int = 1
+    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")),
+            attempt=int(d.get("attempt", 1) or 1),
+            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"
+    # Both required at the CLI and tool surfaces. A steering directive that
+    # carries no evidence and no rationale is an unattributable change of course.
+    evidence: str = ""
+    rationale: str = ""
+    # Set when the directive structurally changed the goal (currently only
+    # kind="add_criterion"); empty for annotation-only kinds.
+    applied: str = ""
+
+    @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")),
+            evidence=str(d.get("evidence", "")),
+            rationale=str(d.get("rationale", "")),
+            applied=str(d.get("applied", "")),
+        )
+
+
+@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