@litfamily/lithermes 1.0.30 → 1.0.32

package/README.md

@@ -1,14 +1,14 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored robots power on one by one, the LitHermes robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored robots power on one by one, the LitHermes robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
 <p align="center">
-<a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/badge-version.svg" alt="1.0.30" /></a>
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/badge-license.svg" alt="MIT license" /></a>
+<a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/badge-version.svg" alt="1.0.32" /></a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/badge-license.svg" alt="MIT license" /></a>
 </p>
 
 <p align="center">
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/lucide-book-open.svg" width="16" alt="" /> Guide</a> &nbsp;
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition film</a> &nbsp;
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/lucide-book-open.svg" width="16" alt="" /> Guide</a> &nbsp;
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition film</a> &nbsp;
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
 </p>
 
 # LitHermes
@@ -17,7 +17,7 @@
 
 A plugin for **Hermes Agent**. Put `lit` in front of a request, and Hermes plans the task, does it, checks the result and writes down where things stand, so the next session can pick up where this one stopped.
 
-**[README and docs on GitHub](https://github.com/wjgoarxiv/lithermes#readme)** · [한국어](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/README_Ko-KR.md)
+**[README and docs on GitHub](https://github.com/wjgoarxiv/lithermes#readme)** · [한국어](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/README_Ko-KR.md)
 
 ## Install
 

package/README_Ko-KR.md

@@ -1,14 +1,14 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 로봇 패널이 차례로 켜지고, LitHermes 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 로봇 패널이 차례로 켜지고, LitHermes 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
 
 <p align="center">
-<a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/badge-version.svg" alt="1.0.30" /></a>
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/badge-license.svg" alt="MIT license" /></a>
+<a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/badge-version.svg" alt="1.0.32" /></a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/badge-license.svg" alt="MIT license" /></a>
 </p>
 
 <p align="center">
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.ko.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/lucide-book-open.svg" width="16" alt="" /> 안내</a> &nbsp;
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition 영상</a> &nbsp;
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.ko.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/lucide-book-open.svg" width="16" alt="" /> 안내</a> &nbsp;
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition 영상</a> &nbsp;
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
 </p>
 
 # LitHermes
@@ -17,7 +17,7 @@
 
 **Hermes Agent**용 플러그인입니다. 요청 앞에 `lit`을 붙이면 Hermes가 작업을 계획하고, 해내고, 결과를 확인한 뒤 어디까지 왔는지 적어 둡니다. 그래서 다음 세션이 그 기록을 읽고 멈춘 자리에서 이어 갈 수 있습니다.
 
-**[GitHub의 README와 문서](https://github.com/wjgoarxiv/lithermes/blob/main/README_Ko-KR.md)** · [English](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.30/README.md)
+**[GitHub의 README와 문서](https://github.com/wjgoarxiv/lithermes/blob/main/README_Ko-KR.md)** · [English](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.32/README.md)
 
 ## 설치
 

package/assets/lithermes-plugin/adhd_stack.py

@@ -11,7 +11,8 @@ the loop exactly where it was.
 A bare ``go`` (also ``lit go``, ``ㄱㄱ``, ``고``, ``진행``, as the whole prompt) continues the
 step the last brief offered: the hook reads the next-step record the collector wrote for this
 session (``.hermes/lithermes/adhd/next-<session>.json``) and returns a short context note for
-the model. A record older than 30 minutes, or no record at all, reads as no next step on
+the model. A plan saved under ``plans/`` during a lit-plan turn writes the same record
+(``start-plan``), so ``go`` right after planning shows that plan's ``/start-work`` command. A record older than 30 minutes, or no record at all, reads as no next step on
 record. Hermes has no typed ``go`` command; ``go`` is a word the hook consumes.
 """
 from __future__ import annotations
@@ -158,6 +159,49 @@ def finish(workspace: Path | str, session_id: Any, skill: str = "") -> bool:
         return False
 
 
+def active_skill(workspace: Path | str, session_id: Any) -> str:
+    """The skill of this session's latest active frame, or "" when none is active."""
+    for frame in reversed(_frames(read_stack(workspace), str(session_id or ""))):
+        if frame.get("status") == "active":
+            return str(frame.get("skill") or "")
+    return ""
+
+
+def write_next_step(
+    workspace: Path | str, session_id: Any, kind: str, target: dict[str, Any], *, now: float | None = None
+) -> bool:
+    """Write this session's `{kind, target, at}` record, the shape the collector writes.
+
+    Refuses a symlinked adhd or ``.hermes`` directory and stages through an exclusive,
+    no-follow, pid-unique file, so a planted link is never written through. Never raises.
+    """
+    import time as _time
+    from datetime import datetime, timezone
+
+    try:
+        directory = adhd_dir(workspace)
+        for probe in (directory, Path(workspace) / ".hermes"):
+            if probe.is_symlink():
+                return False
+        directory.mkdir(parents=True, exist_ok=True)
+        at = datetime.fromtimestamp(now if now is not None else _time.time(), tz=timezone.utc)
+        payload = {"kind": kind, "target": target, "at": at.isoformat(timespec="milliseconds").replace("+00:00", "Z")}
+        path = next_step_path(workspace, session_id)
+        staging = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+        flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0)
+        fd = os.open(staging, flags, 0o600)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                handle.write(json.dumps(payload) + "\n")
+            os.replace(staging, path)
+        except BaseException:
+            staging.unlink(missing_ok=True)
+            raise
+        return True
+    except (OSError, ValueError, TypeError):
+        return False
+
+
 def read_next_step(workspace: Path | str, session_id: Any) -> dict[str, Any] | None:
     """This session's next-step record, or None when it is missing or malformed. Never raises."""
     try:

package/assets/lithermes-plugin/bounded_work.py

@@ -801,6 +801,45 @@ def _terminal_requirement(args: dict[str, Any]) -> tuple[str, list[Path]] | None
     return action, [_canonical_tool_path(args.get("workdir") or Path.cwd())]
 
 
+_OBSERVER_HERDR_READS = {
+    "pane": {"list", "read", "get", "layout"},
+    "agent": {"list", "get", "read"},
+    "tab": {"list"},
+    "workspace": {"list"},
+}
+_OBSERVER_FILTERS = {"grep", "rg", "head", "tail", "wc"}
+
+
+def classify_observation(command: Any) -> bool:
+    """True when a terminal command only reads: a herdr read or a grep/rg pipeline.
+
+    Pipes are the only shell control admitted; redirects, chaining, command
+    substitution and newlines still refuse, as in ``_terminal_requirement``.
+    """
+    text = str(command or "").strip()
+    if not text or _SHELL_CONTROL_RE.search(text.replace("|", "")):
+        return False
+    segments = text.split("|")
+    for index, segment in enumerate(segments):
+        try:
+            words = shlex.split(segment)
+        except ValueError:
+            return False
+        if not words:
+            return False
+        executable = Path(words[0]).name
+        if executable == "rg" and any(word.startswith("--pre") for word in words):
+            return False
+        if index == 0 and executable == "herdr":
+            if len(words) < 3 or words[2] not in _OBSERVER_HERDR_READS.get(words[1], set()):
+                return False
+        elif index == 0 and executable not in {"grep", "rg"}:
+            return False
+        elif index > 0 and executable not in _OBSERVER_FILTERS:
+            return False
+    return True
+
+
 def _tool_requirement(tool_name: str, args: dict[str, Any]) -> tuple[str, list[Path]] | None:
     if tool_name in _READ_ONLY_TOOLS:
         return None
@@ -866,6 +905,8 @@ def enforce_tool_authority(tool_name: Any, args: Any, session_id: Any) -> dict[s
     exact_session = str(session_id or "")
     bound = [state for state in states if state.get("active_session_id") == exact_session]
     if not exact_session or not bound:
+        if name == "terminal" and classify_observation(payload.get("command")):
+            return None
         return _block_tool("Bounded work mutation blocked: the exact Hermes session is not bound.")
     if any(state.get("status") == "paused" for state in bound):
         return _block_tool("Bounded work mutation blocked: this Hermes session has paused work.")

package/assets/lithermes-plugin/core.py

@@ -149,6 +149,7 @@ def post_tool_call(**kwargs: Any) -> None:
     )
     if not paths:
         return None
+    _arm_plan_go(str(kwargs.get("session_id") or ""), paths)
     key = str(kwargs.get("session_id") or "") or str(kwargs.get("task_id") or "")
     if not key:
         return None
@@ -168,6 +169,24 @@ def post_tool_call(**kwargs: Any) -> None:
     return None
 
 
+def _arm_plan_go(session_id: str, paths: list[str]) -> None:
+    """After a lit-plan turn writes ``plans/<name>.md``, record it as this session's `go` step."""
+    if not session_id:
+        return
+    try:
+        workspace = Path.cwd().resolve()
+        if _adhd_stack.active_skill(workspace, session_id) != "lit-plan":
+            return
+        for raw in reversed(paths):
+            target = Path(raw).expanduser()
+            target = (target if target.is_absolute() else workspace / target).resolve()
+            if target.parent == workspace / "plans" and target.suffix == ".md":
+                _adhd_stack.write_next_step(workspace, session_id, "start-plan", {"plan": f"plans/{target.name}"})
+                return
+    except (OSError, RuntimeError, ValueError):
+        return
+
+
 def post_api_request(**kwargs: Any) -> None:
     """Record Hermes' numeric provider usage receipt in the local ledger.
 
@@ -1694,6 +1713,10 @@ def pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
     # route envelope only; native /goal is user-managed and never mutated here.
     bind_obj = _extract_bind_goal(user_message)
     if bind_obj:
+        # The /lit-plan envelope marks this session's lit-plan frame, so the plan
+        # it saves arms `go` the same way a natural `lit plan` turn does.
+        if session_id and "<lithermes-plan-context>" in user_message:
+            _adhd_stack.push(Path.cwd().resolve(), session_id, "lit-plan")
         return None
     # A bare `go` continues the step the last brief offered. The hook consumes
     # the word and injects the next-step record; it never runs a command.

package/assets/lithermes-plugin/core_contexts.py

@@ -152,7 +152,7 @@ _SKILL_ROUTE_CONTRACTS = {
     ),
     "lit-adhd": (
         "Brief task",
-        "Mode Contract: read-only. Run the installed collector once and write the five-part brief from its JSON only: headline, one card per session, roadmap timeline, paused work, one next step. Gauges are copied verbatim and never drawn by hand.",
+        "Mode Contract: read-only. Run the installed collector once and write the five-part brief from its JSON only, after the Done so far/Doing now/Next opener: headline, one card per session, roadmap timeline, paused work, one next step. Gauges are copied verbatim and never drawn by hand.",
         "Read the installed lit-adhd skill first. Run node scripts/adhd.mjs --json from the installed skill root (--here/--since/--max only when asked). Copy every gauge verbatim; an unknown total is the pulse line, never ?, never a guess. End with the one next step from next: the /start-work command when next.command names one, otherwise continue in chat. Hermes has no typed go; offer `lit adhd` for the next brief.",
         "Single-session recaps stay with lit-recap; execution stays with start-work.",
     ),

package/assets/lithermes-plugin/core_plans.py

@@ -408,6 +408,86 @@ def plan_structure_issues(markdown: str) -> list[str]:
     return issues
 
 
+# `Scope roots: <path> (<actions>)` names a folder outside the project that the work
+# reaches. Hermes bounded work grants only inside its worktree, so the line is advisory:
+# it tells the reviewer and the user, before execution, what the todos will touch.
+SCOPE_ROOT_LINE = re.compile(r"^Scope roots?:[ \t]*(\S+)[ \t]*\(([a-z, -]+)\)[ \t]*$")
+_ABSOLUTE_PATH = re.compile(r"(?<![\w.~/-])/[\w.@+%,=~-]+(?:/[\w.@+%,=~-]+)+/?")
+_CODE_SPAN = re.compile(r"`([^`]*)`")
+
+
+def _path_mentions(line: str) -> list[str]:
+    # A code span holding whitespace is a quoted command, not a folder; a span that
+    # is one bare path still counts.
+    def unquote(match: re.Match[str]) -> str:
+        span = match.group(1).strip()
+        return " " if re.search(r"\s", span) else f" {span} "
+
+    return _ABSOLUTE_PATH.findall(_CODE_SPAN.sub(unquote, line))
+
+
+def _nearest_directory(path: Path) -> Path:
+    for candidate in (path, *path.parents):
+        if candidate.is_dir():
+            return candidate.resolve()
+    return Path(path.anchor or "/")
+
+
+def _too_broad(directory: Path) -> bool:
+    return len(directory.parents) <= 1 or directory == Path.home().resolve()
+
+
+def _covers(root: Path, path: Path) -> bool:
+    return path == root or root in path.parents
+
+
+def scope_root_issues(markdown: str, workspace: Path | str) -> list[str]:
+    """Advisory: absolute paths under '## Todos' outside the project and every Scope roots line.
+
+    Fenced lines, command spans and other sections do not count. A root that is the
+    filesystem root, a top-level folder or the bare home folder never covers anything.
+    One message per folder, naming the line to add or asking for a narrower folder.
+    """
+    project = Path(workspace).resolve()
+    lines = list(_outside_fence_lines(markdown))
+    roots = []
+    for _, raw in lines:
+        match = SCOPE_ROOT_LINE.match(raw)
+        if match:
+            root = Path(match.group(1)).expanduser()
+            root = (root if root.is_absolute() else project / root).resolve()
+            if not _too_broad(root):
+                roots.append(root)
+    issues: list[str] = []
+    seen: set[Path] = set()
+    section = ""
+    for _, raw in lines:
+        if raw.startswith("## "):
+            section = raw.strip()
+            continue
+        if section != _TODOS_HEADING:
+            continue
+        for mention in _path_mentions(raw):
+            path = mention.rstrip(".,:;)")
+            directory = _nearest_directory(Path(path))
+            resolved = Path(path).resolve()
+            if any(_covers(root, candidate) for root in (project, *roots) for candidate in (resolved, directory)):
+                continue
+            if directory in seen:
+                continue
+            seen.add(directory)
+            if _too_broad(directory):
+                issues.append(
+                    f"{path} is outside the project; name a narrower existing folder on a Scope roots line"
+                )
+            else:
+                issues.append(
+                    f"{path} is outside the project and no Scope roots line covers it; "
+                    f"add: Scope roots: {directory} (read)"
+                )
+    return issues
+
+
 def assert_plan_structure(markdown: str) -> None:
     """Raise unless the plan satisfies the row grammar. Use before handoff."""
     issues = plan_structure_issues(markdown)

package/assets/lithermes-plugin/core_workflow_commands.py

@@ -6,7 +6,7 @@ try:
         LITGOAL_MEANING, _skill_body_block, conditional_uiux_skill_blocks, contract_route_block,
         reader_facing_contract_block,
     )
-    from .core_plans import plan_structure_issues, unchecked_items
+    from .core_plans import plan_structure_issues, scope_root_issues, unchecked_items
     from .core_reader_args import parse_reader_facing_command_args
     from .core_routing import bind_goal_marker
     from .core_runs import build_run_agent_message, find_plan, latest_start_work_run, load_run_state, write_run_state
@@ -17,7 +17,7 @@ except (ImportError, ModuleNotFoundError):
         LITGOAL_MEANING, _skill_body_block, conditional_uiux_skill_blocks, contract_route_block,
         reader_facing_contract_block,
     )
-    from core_plans import plan_structure_issues, unchecked_items
+    from core_plans import plan_structure_issues, scope_root_issues, unchecked_items
     from core_reader_args import parse_reader_facing_command_args
     from core_routing import bind_goal_marker
     from core_runs import build_run_agent_message, find_plan, latest_start_work_run, load_run_state, write_run_state
@@ -144,14 +144,20 @@ def command_start_work(raw_args: str) -> str | dict[str, str]:
         raise ValueError(msg)
     conditional_uiux = conditional_uiux_skill_blocks(text)
     open_items = unchecked_items(text)
+    outside = scope_root_issues(text, workspace)
+    scope_note = (
+        "\nScope roots advisory (Hermes grants nothing outside the worktree; settle these "
+        "with the user before the todos reach them):\n" + "\n".join(f"- {issue}" for issue in outside[:8])
+        if outside else ""
+    )
     if dry_run:
         preview = "\n".join(f"- {item}" for item in open_items[:8]) or "- no unchecked items found"
         if resume:
             run_dir = latest_start_work_run(workspace, plan)
             if not run_dir:
                 return f"BLOCKED: /start-work --resume found no prior run for {plan}."
-            return f"LitHermes resume dry-run for {plan}: would resume {run_dir}\n{preview}"
-        return f"LitHermes dry-run for {plan}:\n{preview}"
+            return f"LitHermes resume dry-run for {plan}: would resume {run_dir}\n{preview}{scope_note}"
+        return f"LitHermes dry-run for {plan}:\n{preview}{scope_note}"
 
     if resume:
         run_dir = latest_start_work_run(workspace, plan)
@@ -189,7 +195,7 @@ def command_start_work(raw_args: str) -> str | dict[str, str]:
     display = (
         f"Started LitHermes work run from approved plan: {run_dir}\n"
         f"Plan: {plan}\n"
-        f"Open items:\n{first_items}"
+        f"Open items:\n{first_items}{scope_note}"
     )
     return {
         "display": display,

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

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-10-26T21:40:45.035Z",
+  "syncedAt": "2026-10-28T14:17:34.226Z",
   "source": "bundled-payload",
-  "sourceHash": "bca2bacc6e77a46a4cea81a3e04b4bffa340b6a2e7e431e867e58e03ca2a818d",
+  "sourceHash": "4b34138dc5258862c601aff0cb5ef841a2ca102319a24a6316c6c5977b099639",
   "files": [
     {
       "path": "NOTICE.md",
@@ -17,7 +17,7 @@
     },
     {
       "path": "adhd_stack.py",
-      "sha256": "14597ea1f5aaed802613b947e384239a5f1e3129c2616c7600c45b15188def35"
+      "sha256": "0a1e3e45f6697918758b1454a53f034a61658f3980430c5c1a15c149a9ba7012"
     },
     {
       "path": "auto_handoff.py",
@@ -29,7 +29,7 @@
     },
     {
       "path": "bounded_work.py",
-      "sha256": "57ce1eab813a0363a819a64da58a87de5889c29234b656306faee1f0cba9e660"
+      "sha256": "12159eed9ea3ca71d1de7b10c12b4dea5cb273d9abe7b1b52dddad1738cbeb04"
     },
     {
       "path": "bounded_work_tools.py",
@@ -37,7 +37,7 @@
     },
     {
       "path": "core.py",
-      "sha256": "c23c4ea051087b9f8a0a5b601ab75e72a2abc9629a52436ab1e3481dc60d7eed"
+      "sha256": "68641a92c3cc389c46bc1c1dc8bfab7e72fed16c10769a0f5ad7a6327258178e"
     },
     {
       "path": "core_commands.py",
@@ -45,7 +45,7 @@
     },
     {
       "path": "core_contexts.py",
-      "sha256": "5f03a2cce9f8a50fbc06f40aef4d4c9098b9b2a89d251207b28b81a66fb169bb"
+      "sha256": "4b8ab6c18ac58c1b9472547c6f4c50aa64b40878f86f848e6e1ca5a5dc800640"
     },
     {
       "path": "core_contract.py",
@@ -53,7 +53,7 @@
     },
     {
       "path": "core_plans.py",
-      "sha256": "2f53c04e6c2d7ef3bc7a2cabfea8fb0a2d3967a06a65aa9195a85338ee3898a4"
+      "sha256": "e1f138375a88a5098ac091444fbf528eeb8e83d750c68a4ced5072c779b1c2e4"
     },
     {
       "path": "core_reader_args.py",
@@ -85,7 +85,7 @@
     },
     {
       "path": "core_workflow_commands.py",
-      "sha256": "e8ca7656e1a66149b11c6e9ce982becf8fca700a9cd9d614c89fb349c4811e0f"
+      "sha256": "734133dbfac98d98fff445c5787fab49899c94a9f72f5aace27665798765ee37"
     },
     {
       "path": "deliverable_hedge_guard.py",
@@ -185,7 +185,7 @@
     },
     {
       "path": "plugin.yaml",
-      "sha256": "7a165108f0ccba9dcf63b0b7082fa9ad4fb72954a2f44ca177fd32af23e17bff"
+      "sha256": "568a992a47e5bece2aaa24ae0930e3a205fac0cfb58ed20d84c00364bd8d4478"
     },
     {
       "path": "provider_metrics.py",
@@ -1333,7 +1333,7 @@
     },
     {
       "path": "skills/frontend-ui-ux/references/complete-contract.md",
-      "sha256": "a9a9c8476a1df3b019976b84b82817c643e89be01d8b5b36daffea2298927d24"
+      "sha256": "ac5181cf8922fdf980d136b23c2da9cd8d4ec34b03dce165e25bc591e90abd0d"
     },
     {
       "path": "skills/frontend-ui-ux/references/composition.md",
@@ -1489,19 +1489,19 @@
     },
     {
       "path": "skills/lit-adhd/SKILL.md",
-      "sha256": "30805f92fbdbcb63a9c9b38e070729ac271390d765274cd2bfb07a7752963788"
+      "sha256": "5c7b769bbca2e534874425e755d0b8d01a57f3b042a7368ba7575cceea0a7c76"
     },
     {
       "path": "skills/lit-adhd/references/brief-contract.md",
-      "sha256": "3d10bb1f01629dcc63d8eba79006b0810a8dd75c2373c883ef5aa71fbc709cd3"
+      "sha256": "e7ee488082297403e1ff5796f7a117fe69e7e62fbae749c547ec41dd1b70bfc4"
     },
     {
       "path": "skills/lit-adhd/references/card-examples.md",
-      "sha256": "08675a2a8225b5a1a57f6a1a162b7e4860b7f630456bbbc394b60ed87debf550"
+      "sha256": "b077110d4eb04ce96640646280544dd4eb5ca287d0492356dd62b376aa162129"
     },
     {
       "path": "skills/lit-adhd/references/status-taxonomy.md",
-      "sha256": "843512db99743ac2121936f77c24acb517b2bf6a3416634cc266b7cddd56c061"
+      "sha256": "3f18ce0e1509d0c3e8d48730fb29625883d52eb05cc7bdf4dbac35c5df77291d"
     },
     {
       "path": "skills/lit-adhd/scripts/adhd.mjs",
@@ -1509,7 +1509,7 @@
     },
     {
       "path": "skills/lit-adhd/scripts/lib/collect.mjs",
-      "sha256": "91ab388060b2324fc617e9de7929a94ed27ae27cc43c0c508f8beca8c51867f0"
+      "sha256": "ca056223c8dba8008543ba900a45f4bbea5859119215ad6a2a35cf0fb34ed68f"
     },
     {
       "path": "skills/lit-adhd/scripts/lib/gauge.mjs",
@@ -3677,7 +3677,7 @@
     },
     {
       "path": "skills/lit-plan/SKILL.md",
-      "sha256": "8309c86e23dec6e8f5000f887eb7484875544772bc7c6575691d874a80aa07ce"
+      "sha256": "8325532a4394f033feeb5a55d64938967458a87324dd688b4783050858195014"
     },
     {
       "path": "skills/lit-pptx/FORBIDDEN_TERMS.json",
@@ -4945,7 +4945,7 @@
     },
     {
       "path": "skills/visual-qa/references/complete-contract.md",
-      "sha256": "38ecb56893febb43bdbb06c47df683a5bcb8fb136c0fc1480ca9eab801886b38"
+      "sha256": "a0ca33f1bc157de7e2c0cbbe38688fee6c7818674c691bbb3dbd6d18083cf932"
     },
     {
       "path": "skills/visual-qa/schemas/evidence-manifest-v1alpha1.schema.json",

package/assets/lithermes-plugin/plugin.yaml

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

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/complete-contract.md

@@ -445,7 +445,7 @@ isolated Hermes home. Use `--hermes-home`; never `--home`.
 
 ```text
 $ node packages/lithermes-installer/bin/lithermes.js install --yes --offline --no-hud --hermes-home "$ISOLATED"
-Installed LitHermes 1.0.30
+Installed LitHermes 1.0.32
 plugin: $ISOLATED/plugins/lithermes
 model config: updated
 
@@ -462,7 +462,7 @@ installed payload: PASS
 enabled config: PASS
 
 $ hermes lithermes doctor
-[OK] plugin.yaml readable (version 1.0.30)
+[OK] plugin.yaml readable (version 1.0.32)
 [OK] skills bundled: 40
 [OK] litgoal durable runtime importable
 ```

package/assets/lithermes-plugin/skills/lit-adhd/SKILL.md

@@ -51,17 +51,23 @@ verdicts: [PASS, FAIL, BLOCKED]
 
 ## #contract.outputs
 
-The brief has five parts, in this order:
+The brief opens with three lines, each from records only (`references/brief-contract.md`, "The opener"):
+
+- `Done so far:` / `지금까지:` — this worktree's newest commits in the window (two at most), then its finished start-work runs (`finished.runs`, written `plans/<f>.md (start-work complete)`) and fully ticked plans (`finished.plans`), three items in all; with none, "nothing finished in this window".
+- `Doing now:` / `지금:` — this session's active frame from `workflows`, else its own active `startWork` run with the gauge, else the newest active session's goal, else another session's active run marked `(another session)`; with none, "nothing running".
+- `Next:` / `다음:` — the same one step the box at the end names.
+
+Then the brief has five parts, in this order:
 
 1. **Headline.** Sessions found, how many wait on the user, the one next step: `3 sessions · 1 waiting on you · next: start plan (run /start-work plans/<plan>.md)` / `세션 3개 · 나를 기다리는 것 1 · 다음: start plan (/start-work plans/<plan>.md 실행)`. The headline doubles as the counts-only status line: session counts first, then plan and goal gauges, each a real `k/n` from the first source that knows it, never `?`, never `k/?`.
 2. **A full card per live session, a table for ended ones.** Waiting, active and unknown sessions get a full card: a status badge (`● waiting on you`, `▶ active`, `○ unknown`, in the user's language), the goal in plain words (the first ask, clipped), a real gauge or the known-facts line, `now:` naming the last tool call on active sessions, what was done (tools used and commits), what is next. Group cards under their worktree when sessions span more than one. Ended sessions collapse to one table row each (id, folder, goal, age, done; at most eight, newest first).
-3. **Roadmap timeline.** Done `✓` (finished plans and landed commits with dates), now `▶` (the current item of each open plan), later `○` (remaining names), then litgoal objectives with their gauges. Plans from other worktrees carry their worktree name. When `plansOmitted` is above zero, say how many more open plans exist.
+3. **Roadmap timeline.** Done `✓` (landed commits with dates), now `▶` (the current item of each open plan), later `○` (remaining names), then litgoal objectives with their gauges. Plans from other worktrees carry their worktree name. When `plansOmitted` is above zero, say how many more open plans exist. Only plans changed inside the window are listed, this worktree's too; a fully ticked plan is finished work for the opener, never a roadmap row.
 4. **Paused work.** Each paused bounded-work run from `startWork` with its gauge and an approval offer: `answer in chat to approve or deny the boundary`. Approval stays with the user in words; the grant settles it. Never start or approve it yourself.
-5. **One next step in a box.** Exactly one, from `next`: what it does, then the slash command when `next.command` names one, otherwise "continue in chat". When `next` is `none`, show the suggestion the collector printed instead; it is shown, never a second candidate.
+5. **One next step in a box.** Exactly one, from `next`: what it does, then the slash command when `next.command` names one, otherwise "continue in chat". When `next` is `none`, the first `## Next` item of this worktree's own HANDOFF.md (`handoffs[].next` with `local: true`) is the step (`HANDOFF.md Next: <item>`); without one, show the suggestion the collector printed. Either is shown, never recorded, and never a second candidate.
 
 **Progress gauges (D9), required.** One real gauge per session and per plan, each copied verbatim from the collector, in the form `[▉▉▉░░] 3/5` (filled `▉` done, light `░` remaining, then done/total). The remaining items are listed by name under each gauge, from its `remaining` array, clipped by the collector to fit. A gauge renders only when both numbers are real: an unknown total is the known-facts line (`… 3 steps`, or `… running` when nothing is counted), never `?`, never a guess, never an estimate, never a gauge of your own.
 
-Reader mode is the default conversational projection: the five parts above are the result, so give them and nothing more. Open the brief with the label `REWIND <<` on its own line (the rewind look; Hermes shows no colour or animation, so the label and badges are the whole look). Keep collector metadata such as byte budgets, source maps and file paths internal unless the user asks; technical or audit detail appears only when the current request asks for it. A material failure, risk or uncertainty stays visible: a source that read `unknown` is named in one line at the end (`모름: herdr, git` / `unknown: herdr, git`), and a truncated read (`budget.exhausted`) is stated as "older sessions were not read".
+Reader mode is the default conversational projection: the opener and the five parts above are the result, so give them and nothing more. Open the brief with the label `REWIND <<` on its own line (the rewind look; Hermes shows no colour or animation, so the label and badges are the whole look), then the three opener lines. Keep collector metadata such as byte budgets, source maps and file paths internal unless the user asks; technical or audit detail appears only when the current request asks for it. A material failure, risk or uncertainty stays visible: a source that read `unknown` is named in one line at the end (`모름: herdr, git` / `unknown: herdr, git`), and a truncated read (`budget.exhausted`) is stated as "older sessions were not read". Plans are read before session records; when the plans alone fill the budget, `roadmap.plansSkipped` says how many were not read, and the brief says so ("2 plans were not read (read budget used up)").
 
 The Hermes chat surface is not animated and carries no colour, so the psychedelic look does not port: the brief is plain text with no colour codes, and no colour escape ever enters the collector JSON. This skill asks no theme or preset, so the ask-first rule does not apply to it.
 
@@ -74,7 +80,7 @@ limitations_channel: inline
 
 ## #contract.evidence
 
-- The collector JSON is the evidence. Every claim in the brief maps to a field in it: `sessions[].asked`, `done.tools`, `done.commits`, `status`, `roadmap`, `workflows`, `startWork`, `next`.
+- The collector JSON is the evidence. Every claim in the brief maps to a field in it: `sessions[].asked`, `done.tools`, `done.commits`, `status`, `roadmap`, `finished`, `handoffs[].next`, `workflows`, `startWork`, `next`.
 - A session's "what that means" is a one-clause reading of its `asked`, `done.tools` and `done.commits` only. When all are empty, say what is known (elapsed time, last action) and mark nothing as done.
 - Real-surface proof for this skill lives in the repo's tests (`test/lit-adhd.test.js`, `test/python/test_lit_adhd.py`) and in recorded real-session briefs; detailed evidence stays internal to the run.
 
@@ -123,15 +129,15 @@ The collector (`skills/lit-adhd/scripts/lib/collect.mjs`, served as `scripts/adh
 | Source | What it gives | Missing reads |
 | --- | --- | --- |
 | Hermes sessions, `~/.hermes/state.db` read-only (`HERMES_SESSION_STORE` overrides it) | per session: title, first and last ask, tools used, status | `sessions: unknown` |
-| `plans/*.md` checkbox rows | open plans, current item, done/total, remaining names | `plans: unknown` |
+| `plans/*.md` checkbox rows | open plans changed in the window (current item, done/total, remaining names) and fully ticked ones as finished work | `plans: unknown` |
 | `.hermes/lithermes/litgoal/*/goals.json` | objective and passed/total criteria per goal | `litgoal: unknown` |
-| `HANDOFF*.md` and the `.handoff/` directory | headings from the first 40 lines only | `handoffs: unknown` |
+| `HANDOFF*.md` and the `.handoff/` directory | headings from the first 40 lines; for this worktree's own, the first `## Next` item | `handoffs: unknown` |
 | `git log --since` | commits in the window, matched to sessions by time and branch | `git: unknown` |
 | `.hermes/lithermes/adhd/stack.json` | active disciplines per session from the prompt hook | `workflowStack: unknown` |
-| start-work runs and bounded-work states | live runs and their plans, paused boundaries with progress | `startWork: unknown` |
+| start-work runs and bounded-work states | live and finished runs (`done`, `completed`) and their plans, paused boundaries with progress | `startWork: unknown` |
 | `herdr agent list` (only when `HERDR_ENV=1`) | agent panes | `herdr: unknown` |
 
-Sessions are read newest first under one 8 MiB budget for the whole run; a session belongs to a worktree when the repo root or cwd its record carries sits inside it. Archived and hidden sessions are skipped. Every string is redacted before it leaves the collector: credential shapes, `NAME=value` with a secret-like name, URI userinfo, any current environment value of eight or more characters, and the home directory (shown as `~`). Assistant text and changed files are not session records on this host, so the brief shows commits and tool names instead.
+Plans, goals, handoffs, the stack and start-work states are read first; sessions are read after them, newest first, under one 8 MiB budget for the whole run; a session belongs to a worktree when the repo root or cwd its record carries sits inside it. Archived and hidden sessions are skipped. Every string is redacted before it leaves the collector: credential shapes, `NAME=value` with a secret-like name, URI userinfo, any current environment value of eight or more characters, and the home directory (shown as `~`). Assistant text and changed files are not session records on this host, so the brief shows commits and tool names instead.
 
 ## Status taxonomy
 
@@ -142,6 +148,8 @@ Sessions are read newest first under one 8 MiB budget for the whole run; a sessi
 
 Sessions waiting on the user come first, then active ones, newest first.
 
+A start-work run whose plan has every row ticked reads `done`, and completed bounded work reads `completed`; both are finished work on the opener's `Done so far:` line. A session never reads `done` on Hermes: run records carry no session id and completed bounded work clears its owner, so nothing ties a finished run to the session that ran it (`references/status-taxonomy.md`).
+
 ## The next step
 
 `next` is chosen by code, in this priority order, and the brief offers exactly that one:
@@ -153,7 +161,7 @@ Sessions waiting on the user come first, then active ones, newest first.
 
 ## Continuing after the brief
 
-After a brief, the user's bare `go` (also `lit go`, `ㄱㄱ`, `고`, `진행`, as the whole prompt) continues the step the brief offered, in the same session, within 30 minutes. The prompt hook reads the next-step record the collector wrote for this session and tells the model what to do next: a paused boundary is shown for a chat answer, an active run continues in chat, a single open plan starts through `/start-work`. Anything else typed after the brief is an ordinary prompt. There is no typed `go` command on Hermes; `go` is a word the hook consumes, and an expired or missing record reads as no next step on record.
+After a brief, the user's bare `go` (also `lit go`, `ㄱㄱ`, `고`, `진행`, as the whole prompt) continues the step the brief offered, in the same session, within 30 minutes. The prompt hook reads the next-step record the collector wrote for this session and tells the model what to do next: a paused boundary is shown for a chat answer, an active run continues in chat, a single open plan starts through `/start-work`. Anything else typed after the brief is an ordinary prompt. A plan saved under `plans/` in a lit-plan turn writes the same record (`start-plan`), so `go` right after planning shows that plan's `/start-work` command too. There is no typed `go` command on Hermes; `go` is a word the hook consumes, and an expired or missing record reads as no next step on record.
 
 ## Relation to lit-recap
 
@@ -178,7 +186,7 @@ The prompt hook records each lit route activation as a frame in the adhd stack f
 ## Stop and report
 
 - Stop with `BLOCKED: lit-adhd collector unavailable (<reason>)` when the collector exits non-zero or is not found; never rebuild the brief from memory.
-- The reply is the five-part brief (summary, session cards, roadmap, paused work, one next step) and nothing more. Name every `unknown` source once on the last line.
+- The reply is the three opener lines and the five-part brief (summary, session cards, roadmap, paused work, one next step) and nothing more. Name every `unknown` source once on the last line.
 - Start nothing: the user's next reply starts the next step, not this turn.
 
 ## Pitfalls

package/assets/lithermes-plugin/skills/lit-adhd/references/brief-contract.md

@@ -1,7 +1,23 @@
 # lit-adhd brief contract
 
-The brief the model writes from one collector run. Five parts, in order: headline, one card per
-session, roadmap timeline, paused work, one next step. Dense, pretty, plain words.
+The brief the model writes from one collector run. Three opener lines, then five parts, in order:
+headline, one card per session, roadmap timeline, paused work, one next step. Dense, pretty,
+plain words.
+
+## The opener
+
+Three lines before the headline, each from records only:
+
+- `Done so far:` (`지금까지:`) — this worktree's newest commits in the window (two at most), then
+  its finished start-work runs (`plans/<f>.md (start-work complete)`) and its plans with every
+  row ticked, three items in all. With none: "nothing finished in this window".
+- `Doing now:` (`지금:`) — this session's active discipline frame, else its own running
+  start-work with the gauge, else the newest active session's goal, else another session's
+  running start-work marked `(another session)`. With none: "nothing running".
+- `Next:` (`다음:`) — the same one step the box at the end names, with its slash command.
+
+The plain-text render prints the three lines as they are; Hermes shows them as plain text, so no
+fence or tag wraps them.
 
 ## Forbidden glyphs (A)
 
@@ -27,17 +43,21 @@ surfaces; a session id with no recorded value reads `unknown`.
    age in the largest unit under an `ago` header, done as commit count or tools used; more
    ended sessions than fit read `…(+N more ended)`. Hermes records no changed-file list,
    so the table never shows one.
-3. **Roadmap timeline.** `✓` finished plans and landed commits with dates, `▶` the current item
-   of each open plan with its gauge, `○` remaining names, then litgoal objectives with gauges.
-   Other worktrees' plans carry their worktree name. `plansOmitted` above zero is stated.
+3. **Roadmap timeline.** `✓` landed commits with dates, `▶` the current item of each open plan
+   with its gauge, `○` remaining names, then litgoal objectives with gauges. Other worktrees'
+   plans carry their worktree name. `plansOmitted` above zero is stated. Only plans changed
+   inside the window are listed, this worktree's included: a stale plan is left out. A plan
+   with every row ticked is finished work (`finished.plans`, named in the opener), never roadmap.
 4. **Paused work.** Each paused bounded-work run with its gauge and an approval offer in words.
    Approval stays with the user: a chat answer approves or denies, and only the bounded-work
    grant settles it. The brief never starts, approves, or denies anything itself.
 5. **One next step in a box.** Exactly the `next` record: what it does, then the slash command
    (`/start-work plans/<f>.md`) when `next.command` names one, otherwise "continue in chat".
-   When `next` is `none`, the box shows the suggestion instead — a waiting session to
-   answer, an open plan item, another active session to check, another ended one to pick
-   up — and the headline names it; the suggestion is shown, never recorded. Never a second
+   When `next` is `none`, the first item under `## Next` in this worktree's own HANDOFF.md
+   (`handoffs[].next`, `local: true`) comes first (`HANDOFF.md Next: <item>`); without one the
+   box shows the suggestion — a waiting session to answer, an open plan item, another active
+   session to check, another ended one to pick up — and the headline names it; it is shown,
+   never recorded. Another worktree's handoff never supplies the step. Never a second
    candidate, never a `go` to type: Hermes has no typed `go` command.
 
 ## Surface notes (C, D)
@@ -51,5 +71,8 @@ surfaces; a session id with no recorded value reads `unknown`.
 
 - Name every `unknown` source once on the last line (`unknown: herdr, git`).
 - Say "older sessions were not read" when `budget.exhausted` is true.
+- Say "N plans were not read (read budget used up)" when `roadmap.plansSkipped` is above zero.
+  Plans are read before session transcripts, so this happens only when the plans themselves
+  fill the 8 MiB budget.
 - Name the collector failure and stop with `BLOCKED:` when the collector fails; never rebuild
   the brief from memory, from the session store, or from a guess.

package/assets/lithermes-plugin/skills/lit-adhd/references/card-examples.md

@@ -12,6 +12,8 @@ verbatim; only the connecting words change with the language. The JSON excerpt c
     { "id8": "2fad84a7", "title": "schematic lane", "asked": ["render the figure"], "done": { "tools": { "bash": 4 }, "commits": [] }, "status": "ended", "progress": { "gauge": "[▉▉▉] 3/3", "remaining": [] } }
   ],
   "roadmap": { "progress": { "gauge": "[▉▉▉▉░░░░░░] 10/20" }, "plans": [{ "plan": "plans/lit-adhd.md", "local": true, "current": "11. Skill lit-adhd", "progress": { "gauge": "[▉▉▉▉░░░░░░] 10/19" } }], "plansOmitted": 0 },
+  "finished": { "runs": [], "plans": [] },
+  "commits": [{ "hash": "bdea372", "at": "2026-10-25T09:12:00Z", "subject": "feat(adhd): collect cross-session records" }],
   "startWork": [{ "id8": "f06fb727", "workId": "work-abc", "status": "paused", "pendingBoundary": { "boundary": "b-1" } }],
   "next": { "kind": "approve-boundary", "target": { "workId": "work-abc" }, "say": null },
   "sources": { "herdr": "unknown" }
@@ -20,6 +22,10 @@ verbatim; only the connecting words change with the language. The JSON excerpt c
 
 ## English
 
+> Done so far: feat(adhd): collect cross-session records
+> Doing now: pptx lane
+> Next: approve boundary: work-abc. Answer in chat.
+>
 > lit-adhd: 3 session(s) · 1 waiting on you · next: approve boundary
 >
 > == ● waiting on you · 655f39d3 · ADHD lane
@@ -50,6 +56,10 @@ verbatim; only the connecting words change with the language. The JSON excerpt c
 
 ## 한국어
 
+> 지금까지: feat(adhd): collect cross-session records
+> 지금: pptx lane
+> 다음: approve boundary: work-abc. 채팅으로 답하세요.
+>
 > lit-adhd: 세션 3개 · 나를 기다리는 것 1 · 다음: approve boundary
 >
 > == ● 나를 기다림 · 655f39d3 · ADHD lane
@@ -82,5 +92,6 @@ verbatim; only the connecting words change with the language. The JSON excerpt c
 
 - They do not estimate the pptx lane's progress: with no count it reads `[…] running`, copied as is.
 - They do not describe work the records do not show: the pptx lane's "did" line names tools and commits only.
-- They offer one next step only, and do not start it.
+- They offer one next step only, and do not start it; the opener's `Next:` line and the box name the same step.
+- Their `Done so far:` line holds only records: commits, finished start-work runs and fully ticked plans. With none, it reads "nothing finished in this window".
 - They never show `?`, `?/?`, `[???]` or `k/?`: an unknown total is the pulse line, and the examples carry none of the four.

package/assets/lithermes-plugin/skills/lit-adhd/references/status-taxonomy.md

@@ -14,6 +14,22 @@ with the words below and never invents a fifth.
 
 Order in the brief: waiting sessions first, then active, ended and unknown; newest first inside each group.
 
+## Start-work statuses
+
+`startWork[].status` describes a run, not a session:
+
+| Status | Set when |
+| --- | --- |
+| `active` | A start-work run whose plan still has an unticked row, or bounded work in progress |
+| `paused` | Bounded work stopped at a boundary that waits on a chat answer |
+| `done` | A start-work run whose plan has every row ticked |
+| `completed` | Bounded work the owner completed |
+
+A `done` or `completed` run inside the window is listed in `finished.runs` and named on the
+opener's `Done so far:` line. A session itself never reads `done` on Hermes: a start-work run
+record carries no session id, and completed bounded work clears its owner, so no record ties a
+finished run to the session that ran it. Sessions keep the four statuses above.
+
 ## Sources
 
 Each entry of `sources` is `ok` or `unknown`. An `unknown` source is named once on the brief's last
@@ -24,7 +40,7 @@ line and never filled in from memory.
 | `sessions` | Hermes `state.db` sessions |
 | `plans` | `plans/*.md` checkbox rows |
 | `litgoal` | `.hermes/lithermes/litgoal/*/goals.json` |
-| `handoffs` | `HANDOFF*.md` and `.handoff/HANDOFF.md` headings |
+| `handoffs` | `HANDOFF*.md` and `.handoff/HANDOFF.md` headings, plus the first `## Next` item of this worktree's own |
 | `git` | `git log --since` |
 | `workflowStack` | `.hermes/lithermes/adhd/stack.json` |
 | `startWork` | start-work runs and bounded-work states |

package/assets/lithermes-plugin/skills/lit-adhd/scripts/lib/collect.mjs

@@ -68,14 +68,15 @@ const entries = (directory) => {
 
 const defaultExec = (file, args, options) => execFileSync(file, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], ...options });
 
-const outermostRoot = (startDir) => {
+// The nearest `.git` (a directory, or the file a linked worktree carries) bounds the state root,
+// so a worktree nested inside another checkout never reads that checkout's stale plans.
+const nearestRoot = (startDir) => {
   const start = resolve(startDir);
-  let root = null;
   let current = start;
   for (;;) {
-    if (existsSync(join(current, '.git'))) root = current;
+    if (existsSync(join(current, '.git'))) return current;
     const parent = dirname(current);
-    if (parent === current) return root ?? start;
+    if (parent === current) return start;
     current = parent;
   }
 };
@@ -90,25 +91,41 @@ const worktreesOf = (cwd, exec) => {
   }
 };
 
-const plansIn = (root, budget, redact, local) => {
+const mtimeOf = (path) => {
+  try {
+    return lstatSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+};
+
+// A plan met once the read budget is spent is counted in `skipped.count`, so the brief can say so.
+const plansIn = (root, budget, redact, local, skipped) => {
   const list = entries(join(root, 'plans'));
   if (!list) return null;
   return list.filter((entry) => entry.isFile() && entry.name.endsWith('.md')).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
-    const text = readSmallFile(join(root, 'plans', entry.name), budget);
+    if (budget.used >= budget.limit) {
+      skipped.count += 1;
+      return [];
+    }
+    const path = join(root, 'plans', entry.name);
+    const text = readSmallFile(path, budget);
     if (text === null) return [];
     // Column-zero `- [ ] N. title` and `- [ ] FN. title` rows; a non-numbered checkbox row
     // still counts, the same way the source collector counts every checkbox row.
     const rows = parsePlanTaskRows(text);
     if (!rows.length) return [];
     const open = rows.filter((row) => !row.checked);
-    if (!open.length) return [];
     const done = rows.length - open.length;
+    // Every row ticked: kept and marked complete, as finished work for the opener, never roadmap.
     return [{
       worktree: redact(root),
       plan: `plans/${entry.name}`,
       local,
+      complete: open.length === 0,
+      changedMs: mtimeOf(path),
       rows: rows.map((row) => ({ checked: row.checked, title: clipToWidth(redact(row.text), NAME_MAX) })),
-      current: clipToWidth(redact(open[0].text), NAME_MAX),
+      current: open.length ? clipToWidth(redact(open[0].text), NAME_MAX) : null,
       progress: progressOf(done, rows.length, open.map((row) => clipToWidth(redact(row.text), NAME_MAX))),
     }];
   });
@@ -147,7 +164,23 @@ const goalsOf = (root, budget, redact) => {
   });
 };
 
-const handoffsOf = (root, budget, redact) => {
+// The first item under a `## Next` (or `## Next steps`) heading, its list marker removed.
+const nextItemOf = (text) => {
+  let inside = false;
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (/^#{1,6}\s/u.test(line)) {
+      if (inside) return null;
+      inside = /^#{1,6}\s+next(?:\s+steps?)?$/iu.test(line);
+    } else if (inside && line) {
+      return line.replace(/^(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?/u, '');
+    }
+  }
+  return null;
+};
+
+// Only this worktree's own handoff offers a `next`; another worktree's never does.
+const handoffsOf = (root, budget, redact, local) => {
   const files = (entries(root) ?? [])
     .filter((entry) => entry.isFile() && /^HANDOFF.*\.md$/u.test(entry.name))
     .map((entry) => join(root, entry.name));
@@ -156,7 +189,8 @@ const handoffsOf = (root, budget, redact) => {
   return files.map((path) => {
     const text = readSmallFile(path, budget) ?? '';
     const headings = text.split('\n').slice(0, 40).filter((line) => /^#{1,3} /u.test(line)).map((line) => clipToWidth(redact(line), 100));
-    return { worktree: redact(root), file: basename(path), headings };
+    const next = local ? nextItemOf(text) : null;
+    return { worktree: redact(root), file: basename(path), headings, local, next: next ? clipToWidth(redact(next), 120) : null };
   });
 };
 
@@ -197,7 +231,7 @@ const stacksOf = (root, budget, redact) => {
 };
 
 // Hermes start-work state: newest `runs/*/state.json` with `command: start-work` (a run has no
-// status field, so an unfinished plan reads active and a finished plan reads ended), plus
+// status field, so an unfinished plan reads active and a finished plan reads done), plus
 // bounded-work `work/*/state.json` records, which carry a real status and a pending boundary.
 const startWorkOf = (root, budget, redact, sessionId) => {
   const items = [];
@@ -218,7 +252,8 @@ const startWorkOf = (root, budget, redact, sessionId) => {
       worktree: redact(root),
       workId: `run-${String(newestRun.run_id ?? 'unknown').slice(0, 16)}`,
       plan: plan ? redact(plan) : 'unknown',
-      status: rows.length && !open.length ? 'ended' : 'active',
+      status: rows.length && !open.length ? 'done' : 'active',
+      atMs: Date.parse(String(newestRun.created_at ?? '')),
       sessionId: sessionId ?? null,
       id8: sessionId ? String(sessionId).slice(0, 8) : 'unknown',
       progress: rows.length
@@ -246,6 +281,7 @@ const startWorkOf = (root, budget, redact, sessionId) => {
       workId: typeof state.work_id === 'string' ? state.work_id : entry.name,
       plan: plan ? redact(plan) : 'unknown',
       status,
+      atMs: Date.parse(String(state.updated_at ?? state.created_at ?? '')),
       sessionId: owner,
       id8: owner ? owner.slice(0, 8) : 'unknown',
       ...(boundary ? { pendingBoundary: { boundary: clipToWidth(redact(String(boundary.id ?? 'unknown')), NAME_MAX) } } : {}),
@@ -270,6 +306,8 @@ const herdrOf = (env, exec, redact) => {
 };
 
 const known = (list) => (list === null ? 'unknown' : 'ok');
+// A run records its plan as an absolute path; inside its own worktree it reads `plans/<f>.md`.
+const planInWorktree = (worktree, plan) => (plan.startsWith(`${worktree}/`) ? plan.slice(worktree.length + 1) : plan);
 const statusRank = { 'waiting-on-user': 0, active: 1, ended: 2, unknown: 3 };
 
 /**
@@ -293,10 +331,27 @@ export const collectAdhd = ({
   const sinceMs = parseSince(since) ?? parseSince(DEFAULT_SINCE);
   const limit = Number.isInteger(max) && max > 0 ? Math.min(max, 50) : DEFAULT_MAX;
   const start = normalizeRoot(resolve(cwd));
-  const stateRoot = outermostRoot(start);
+  const stateRoot = nearestRoot(start);
   const listed = here ? null : worktreesOf(start, exec);
   const roots = [...new Set([start, ...(here ? [] : listed ?? [stateRoot])])];
 
+  // The small on-disk records first, so the session transcripts read after them cannot spend
+  // the budget a plan or handoff needs.
+  const collectEach = (read) => {
+    const results = roots.map(read);
+    return results.every((value) => value === null) ? null : results.flatMap((value) => value ?? []);
+  };
+  const isLocal = (root) => resolve(root) === stateRoot || resolve(root) === start;
+  const plansSkipped = { count: 0 };
+  const plans = collectEach((root) => plansIn(root, budget, redact, isLocal(root), plansSkipped));
+  const litgoal = collectEach((root) => {
+    const goals = goalsOf(root, budget, redact);
+    return goals ? goals.map((goal) => ({ ...goal, local: isLocal(root) })) : null;
+  });
+  const handoffs = roots.flatMap((root) => handoffsOf(root, budget, redact, resolve(root) === start));
+  const workflows = collectEach((root) => stacksOf(root, budget, redact));
+  const startWork = collectEach((root) => startWorkOf(root, budget, redact, sessionId));
+
   const found = findHermesSessions(hermesStorePath(env), roots, { exec });
   const sessions = [];
   for (const entry of found.sessions) {
@@ -308,19 +363,7 @@ export const collectAdhd = ({
     sessions.push(session);
   }
 
-  const collectEach = (read) => {
-    const results = roots.map(read);
-    return results.every((value) => value === null) ? null : results.flatMap((value) => value ?? []);
-  };
-  const plans = collectEach((root) => plansIn(root, budget, redact, resolve(root) === stateRoot || resolve(root) === start));
-  const litgoal = collectEach((root) => {
-    const goals = goalsOf(root, budget, redact);
-    return goals ? goals.map((goal) => ({ ...goal, local: resolve(root) === stateRoot || resolve(root) === start })) : null;
-  });
-  const handoffs = roots.flatMap((root) => handoffsOf(root, budget, redact));
   const commits = collectEach((root) => commitsOf(root, sinceMs, now, exec, redact));
-  const workflows = collectEach((root) => stacksOf(root, budget, redact));
-  const startWork = collectEach((root) => startWorkOf(root, budget, redact, sessionId));
   const herdr = herdrOf(env, exec, redact);
 
   // A session waits on the user when it asked something, or holds a paused boundary.
@@ -340,9 +383,13 @@ export const collectAdhd = ({
   }
   sessions.sort((a, b) => statusRank[a.status] - statusRank[b.status] || (b.lastMs ?? 0) - (a.lastMs ?? 0));
 
-  // Every worktree's open plans are listed, this one's first, up to a short cap; the roadmap gauge
+  // Open plans changed inside the window are listed, this worktree's first, then the most recently
+  // changed, up to a short cap; a stale plan is left out here and elsewhere. The roadmap gauge
   // counts this worktree only, since a sum over unrelated branches measures nothing.
-  const orderedPlans = [...(plans ?? [])].sort((a, b) => Number(b.local) - Number(a.local));
+  const recent = (plan) => plan.changedMs !== null && now - plan.changedMs <= sinceMs;
+  const orderedPlans = (plans ?? [])
+    .filter((plan) => !plan.complete && recent(plan))
+    .sort((a, b) => Number(b.local) - Number(a.local) || (b.changedMs ?? 0) - (a.changedMs ?? 0));
   const shownPlans = orderedPlans.slice(0, PLAN_LIMIT);
   const localGoals = (litgoal ?? []).filter((goal) => goal.local);
   const roadmapItems = [...orderedPlans.filter((plan) => plan.local).map((plan) => plan.progress), ...localGoals.map((goal) => goal.progress)];
@@ -370,9 +417,18 @@ export const collectAdhd = ({
     roadmap: {
       plans: shownPlans,
       plansOmitted: orderedPlans.length - shownPlans.length,
+      plansSkipped: plansSkipped.count,
       litgoal: litgoal ?? [],
       progress: roadmapItems.length ? aggregateProgress(roadmapItems) : progressOf(null, null),
     },
+    // Finished inside the window: start-work runs whose plan is fully ticked, completed bounded
+    // work, and plans with every row ticked.
+    finished: {
+      runs: (startWork ?? [])
+        .filter((work) => ['done', 'completed'].includes(work.status) && Number.isFinite(work.atMs) && now - work.atMs <= sinceMs)
+        .map(({ worktree, plan, workId }) => ({ worktree, plan: planInWorktree(worktree, plan), workId })),
+      plans: (plans ?? []).filter((plan) => plan.complete && recent(plan)).map(({ worktree, plan, local, progress }) => ({ worktree, plan, local, gauge: progress.gauge })),
+    },
     workflows: (workflows ?? []).map((frame) => ({ ...frame, self: Boolean(sessionId) && frame.sessionId === sessionId })),
     startWork: startWork ?? [],
     handoffs,
@@ -385,7 +441,7 @@ export const collectAdhd = ({
   if (record && sessionId) {
     try {
       // The record lives beside the working directory the hook reads (`go`
-      // uses `Path.cwd()`), not at the outermost git root: a brief run from a
+      // uses `Path.cwd()`), not at the git root: a brief run from a
       // subdirectory must be continued from that same directory.
       writeNextStep(start, sessionId, next, new Date(now));
       data.nextRecorded = true;
@@ -394,7 +450,11 @@ export const collectAdhd = ({
     }
   }
   for (const frame of data.workflows) delete frame.sessionId;
-  for (const work of data.startWork) delete work.sessionId;
+  for (const work of data.startWork) {
+    work.self = Boolean(sessionId) && work.sessionId === sessionId;
+    delete work.sessionId;
+    delete work.atMs;
+  }
   return data;
 };
 
@@ -474,15 +534,56 @@ const endedTable = (sessions, nowMs) => {
   return ['| id | where | goal | ago | done |', '|---|---|---|---|---|', ...rows, ...more];
 };
 
-/** Plain-text brief: headline, cards for live sessions, ended table, roadmap, one next step in a box. */
+/**
+ * The three opening lines, from records only. Done: this worktree's newest commits in the window
+ * (two at most), then its finished start-work runs and fully ticked plans (three items in all).
+ * Doing: this session's active frame, else its own running start-work, else the newest active
+ * session's goal, else another session's running start-work. Next: the same step the box names.
+ */
+const openerLines = (data, nextText) => {
+  const local = data.scope.worktrees[0];
+  const runs = (data.finished?.runs ?? []).filter((run) => run.worktree === local);
+  const runPlans = new Set(runs.map((run) => run.plan));
+  const finished = [
+    ...(data.commits ?? []).filter((commit) => commit.worktree === local).slice(0, 2).map((commit) => commit.subject),
+    ...runs.map((run) => `${run.plan} (start-work complete)`),
+    ...(data.finished?.plans ?? []).filter((plan) => plan.worktree === local && !runPlans.has(plan.plan)).map((plan) => `${plan.plan} ${plan.gauge}`),
+  ];
+  const done = [...new Set(finished)].slice(0, 3).join('; ') || 'nothing finished in this window';
+  const frame = (data.workflows ?? []).filter((item) => item.self && item.status === 'active').at(-1);
+  const running = (data.startWork ?? []).filter((item) => item.status === 'active');
+  const work = running.find((item) => item.self);
+  const active = (data.sessions ?? []).find((session) => session.status === 'active');
+  const doing = frame
+    ? [frame.skill, frame.stage].filter((part) => part && part !== 'unknown').join(' · ')
+    : work
+      ? `start-work ${planInWorktree(work.worktree, work.plan)} ${work.progress.gauge}`
+      : active
+        ? clipToWidth(goalOf(active), 80)
+        : running[0]
+          ? `start-work ${planInWorktree(running[0].worktree, running[0].plan)} ${running[0].progress.gauge} (another session)`
+          : 'nothing running';
+  return [`Done so far: ${done}`, `Doing now: ${doing}`, `Next: ${nextText}`];
+};
+
+/** Plain-text brief: opener, headline, cards for live sessions, ended table, roadmap, one next step in a box. */
 export const renderAdhd = (data, width = 100, sessionId = null) => {
   const out = [];
   const push = (text) => out.push(line(text, width));
   const recorded = data.next.kind !== 'none';
-  const step = recorded ? data.next : suggestNext(data, sessionId);
+  // With no step on record, this worktree's HANDOFF.md `## Next` item comes before any suggestion.
+  const handoffNext = (data.handoffs ?? []).find((handoff) => handoff.local && handoff.next)?.next;
+  const step = recorded
+    ? data.next
+    : handoffNext
+      ? { kind: 'suggest', label: 'handoff next', say: `HANDOFF.md Next: ${handoffNext}`, command: null }
+      : suggestNext(data, sessionId);
   const stepName = recorded ? data.next.kind.replace(/-/gu, ' ') : step.label;
   const stepSay = recorded && data.next.say ? ` (say "${data.next.say}")` : '';
   const stepRun = step.command ? ` (run ${step.command})` : recorded ? '' : ' (continue in chat)';
+  const target = recorded ? data.next.target?.plan ?? data.next.target?.workId ?? '' : '';
+  const nextText = recorded ? `${stepName}${target ? `: ${target}` : ''}${stepSay}${stepRun}` : `${step.say}${stepRun}`;
+  for (const opener of openerLines(data, nextText)) push(opener);
   push(`lit-adhd: ${data.summary.sessions} session(s) · ${data.summary.waitingOnUser} waiting on you · next: ${stepName}${stepSay}${stepRun}`);
   const live = data.sessions.filter((session) => session.status !== 'ended');
   const ended = data.sessions.filter((session) => session.status === 'ended');
@@ -512,16 +613,11 @@ export const renderAdhd = (data, width = 100, sessionId = null) => {
     for (const goal of data.roadmap.litgoal) push(`○ litgoal ${goal.progress.gauge} ${goal.objective}`);
     for (const commit of data.commits.slice(0, 5)) push(`✓ ${commit.hash} ${commit.at.slice(0, 10)} ${commit.subject}`);
   }
-  {
-    if (recorded) {
-      const target = data.next.target?.plan ?? data.next.target?.workId ?? '';
-      push(`-- next --\n> ${data.next.kind.replace(/-/gu, ' ')}${target ? `: ${target}` : ''}${stepSay}${stepRun}.`);
-    } else {
-      push(`-- next --\n> ${step.say}${stepRun}.`);
-    }
-  }
+  push(`-- next --\n> ${nextText}.`);
   const unknownSources = Object.entries(data.sources).filter(([, status]) => status !== 'ok').map(([name]) => name);
   if (unknownSources.length) push(`unknown: ${unknownSources.join(', ')}`);
+  const skipped = data.roadmap.plansSkipped ?? 0;
+  if (skipped) push(`${skipped} ${skipped === 1 ? 'plan was' : 'plans were'} not read (read budget used up)`);
   return `${out.join('\n')}\n`;
 };
 

package/assets/lithermes-plugin/skills/lit-plan/SKILL.md

@@ -446,6 +446,30 @@ must carry an **action / output / verification** contract:
 7. **Commit, when approved and in scope**: a Conventional Commit message in
    the form `<type>(<scope>): <imperative>`.
 
+### Scope Roots For Outside Folders
+
+When a todo names an absolute path outside the project (a sibling checkout, a
+shared data folder, a scratch directory), add one column-zero line per folder
+near the top of the plan, before you save it:
+
+```
+Scope roots: <path> (<actions>)
+Scope roots: /srv/shared/fixtures (read)
+```
+
+`<actions>` is a comma list such as `read`, `write`, `execute`. Name the
+narrowest existing folder: the filesystem root, a top-level folder and the bare
+home folder never count as cover. Paths inside fenced blocks, inline code spans
+that hold a whole command, and sections other than `## Todos` are not checked.
+
+On Hermes this is **advisory**. Bounded work (`/lit-loop init --grant
+ACTION@ROOT`) only grants roots inside its own worktree, so a Scope roots line
+cannot become a grant. It tells the reviewer and the user, before execution,
+which outside folders the todos will touch. `/start-work` (and its `--dry-run`)
+runs the same check and lists every todo path no line covers, with the line to
+add, under "Scope roots advisory"; it does not block the run. Settle those
+folders with the user before the todo that reaches them.
+
 ### Failure And Decision Branches
 
 Add **failure and decision branches** only where outcomes genuinely change the
@@ -534,10 +558,18 @@ Once both passes clear, output:
 4. The handoff line — this bridges to the execution loop:
 
 ```
-Plan is ready. Use /lit-loop "<brief>" or /start-work <slug> to begin execution.
+Plan is ready: plans/<slug>.md. To start it, type `go` within 30 minutes
+(I will show the /start-work command), or run /start-work plans/<slug>.md yourself.
 The plan path will appear in each execution commit footer: Plan: plans/<slug>.md
 ```
 
+Saving `plans/<slug>.md` in this lit-plan turn is what arms `go`: the
+`post_tool_call` hook records a `start-plan` next step for this session only
+(`.hermes/lithermes/adhd/next-<session>.json`). A `go` from another session, or
+more than 30 minutes later, finds nothing to continue. `go` only presents the
+`/start-work` command for the user to run; it never starts execution, so the
+approval gate above still holds. Save the plan only after the gate clears.
+
 Do **not** reproduce the full plan in the chat output — it is already written to
 disk. If the user wants to read it, they can open `plans/<slug>.md`.
 

package/assets/lithermes-plugin/skills/visual-qa/references/complete-contract.md

@@ -485,7 +485,7 @@ isolated Hermes home. Use `--hermes-home`; never `--home`.
 
 ```text
 $ node packages/lithermes-installer/bin/lithermes.js install --yes --offline --no-hud --hermes-home "$ISOLATED"
-Installed LitHermes 1.0.30
+Installed LitHermes 1.0.32
 plugin: $ISOLATED/plugins/lithermes
 model config: updated
 
@@ -502,7 +502,7 @@ installed payload: PASS
 enabled config: PASS
 
 $ hermes lithermes doctor
-[OK] plugin.yaml readable (version 1.0.30)
+[OK] plugin.yaml readable (version 1.0.32)
 [OK] skills bundled: 40
 [OK] litgoal durable runtime importable
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/lithermes",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "description": "Hermes Agent plugin that plans, builds, checks and hands off your work when you add one word, lit, to a request.",
   "keywords": [
     "hermes-agent",

package/readme-assets/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.30"><title>release: 1.0.30</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.30</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.32"><title>release: 1.0.32</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.32</text></g></svg>