nobrainer-tech-flow 2.5.0 → 2.7.0

package/skills/nobrainer-tech-flow/scripts/flow_guard.py

@@ -5,6 +5,9 @@
 shell command; it never denies. ``stop`` reads a Stop or SubagentStop payload and
 blocks the stop once when a turn that edited files or ran commands ends without a
 proof line. Both fail open: input they cannot read is allowed, with a note on stderr.
+``session`` reads a SessionStart payload and, when the project has active Flow goal
+files, tells the agent to re-read them. It prints only their paths and a known STATUS
+word, never other goal-file text, and prints nothing at all on any error.
 
 This is a seatbelt, not a security boundary. It reads the command text, so a
 command hidden behind ``sh -c``, a variable or an alias can pass unnoticed, and a
@@ -16,10 +19,13 @@ https://code.claude.com/docs/en/hooks.
 
 from __future__ import annotations
 
+import fnmatch
+import itertools
 import json
 import os
 import re
 import shlex
+import stat
 import sys
 import tempfile
 from pathlib import Path
@@ -67,6 +73,31 @@ STOP_REASON = (
     "proof. Add a line starting with 'Proof:' or 'Checked:' that names the command, test "
     "or readback showing the result, or say UNVERIFIED and what is missing."
 )
+# A goal file as nobrainer-context's context_inventory.goal_state finds it: Markdown with a
+# GOAL_ID line whose first STATUS is not COMPLETE, in the project root or one or two levels
+# into tasks/, docs/ or .nobrainer/. tests/test_flow_guard.py checks that both agree.
+# Unlike goal_state, the guard follows no symlink, so it never reads outside the project,
+# and stops after MAX_ENTRIES folder entries or MAX_READS files, so it stays fast.
+GOAL_ID = re.compile(r"^GOAL_ID:\s*\S", re.MULTILINE)
+GOAL_STATUS = re.compile(r"^STATUS:\s*([A-Z_]+)", re.MULTILINE)
+GOAL_DIRS = ("", "tasks", "docs", ".nobrainer")
+GOAL_MAX_BYTES = 256 * 1024
+MAX_ENTRIES = 5000
+MAX_READS = 200
+FOLDER_FLAGS = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+# Non-blocking, so a FIFO swapped in for a goal file cannot hang the hook.
+FILE_FLAGS = os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_NOFOLLOW", 0)
+# The goal file is repository content, so none of its text reaches the context: only a
+# STATUS from references/long-run-state.md, and only a path made of these characters.
+KNOWN_STATUSES = ("ACTIVE", "BLOCKED", "OWNER_DECISION_REQUIRED")
+PATH_PART = re.compile(r"[A-Za-z0-9._-]+")
+MAX_PATH_CHARS = 200
+MAX_GOALS_SHOWN = 3
+SESSION_INTRO = (
+    "Flow guard: the context was compacted, resumed or cleared. Before continuing, re-read "
+    "these active Flow goal files from disk and check GOAL_ID, STATUS, CHECKPOINT and "
+    "NEXT_SAFE_ACTION against the repository. Only paths and known STATUS words are shown here."
+)
 
 
 def note(message: str) -> None:
@@ -229,11 +260,157 @@ def stop(payload: dict) -> dict | None:
     return {"decision": "block", "reason": STOP_REASON}
 
 
+def project_root(cwd: Path) -> Path:
+    """The nearest folder holding .git, where context_inventory looks too; else CWD.
+
+    Only a missing .git moves the search up; any other error propagates.
+    """
+
+    for folder in (cwd, *cwd.parents):
+        try:
+            os.stat(folder / ".git")
+        except FileNotFoundError:
+            continue
+        return folder
+    return cwd
+
+
+def goal_status(folder: int, name: str) -> str | None:
+    """The STATUS of goal file NAME in the open FOLDER, UNKNOWN when it names none.
+
+    None when NAME is not a regular file of at most GOAL_MAX_BYTES with a GOAL_ID line.
+    """
+
+    with os.fdopen(os.open(name, FILE_FLAGS, dir_fd=folder), "rb") as handle:
+        if not stat.S_ISREG(os.fstat(handle.fileno()).st_mode):
+            return None
+        data = handle.read(GOAL_MAX_BYTES + 1)
+    text = data.decode("utf-8", errors="replace")
+    if len(data) > GOAL_MAX_BYTES or not GOAL_ID.search(text):
+        return None
+    status = GOAL_STATUS.search(text)
+    return status.group(1) if status else "UNKNOWN"
+
+
+def active_goals(root: Path) -> list[tuple[Path, str]]:
+    """(path, STATUS) of each active goal file, in goal_state order, within the bounds.
+
+    Every folder and file is opened relative to its open parent and never through a
+    symlink, so nothing outside ROOT is listed or read even if the tree changes meanwhile.
+    Errors propagate, so the caller says nothing.
+    """
+
+    budget = {"entries": MAX_ENTRIES, "reads": MAX_READS}
+    goals: list[tuple[Path, str]] = []
+
+    def listing(folder: int) -> list[os.DirEntry]:
+        found = []
+        if budget["entries"] > 0:
+            with os.scandir(folder) as entries:
+                for entry in entries:
+                    budget["entries"] -= 1
+                    if not entry.is_symlink():
+                        found.append(entry)
+                    if budget["entries"] <= 0:
+                        break
+        return sorted(found, key=lambda entry: entry.name)
+
+    def walk(folder: int, path: Path, nested: bool) -> None:
+        # Files first, then each subfolder in name order: the order goal_state sorts into.
+        entries = listing(folder)
+        for entry in entries:
+            if not fnmatch.fnmatchcase(entry.name, "*.md") or not entry.is_file(follow_symlinks=False):
+                continue
+            if budget["reads"] <= 0:
+                return
+            budget["reads"] -= 1
+            status = goal_status(folder, entry.name)
+            if status is not None and status != "COMPLETE":
+                goals.append((path / entry.name, status))
+        for entry in entries if nested else ():
+            if entry.is_dir(follow_symlinks=False) and budget["entries"] > 0:
+                inner = os.open(entry.name, FOLDER_FLAGS, dir_fd=folder)
+                try:
+                    walk(inner, path / entry.name, False)
+                finally:
+                    os.close(inner)
+
+    top = os.open(root, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+    try:
+        for sub in GOAL_DIRS:
+            if not sub:
+                walk(top, root, False)
+                continue
+            try:
+                mode = os.stat(sub, dir_fd=top, follow_symlinks=False).st_mode
+            except FileNotFoundError:
+                continue
+            # A tasks/, docs/ or .nobrainer/ that is a symlink or a file is not looked into.
+            if stat.S_ISDIR(mode) and budget["entries"] > 0:
+                folder = os.open(sub, FOLDER_FLAGS, dir_fd=top)
+                try:
+                    walk(folder, root / sub, True)
+                finally:
+                    os.close(folder)
+    finally:
+        os.close(top)
+    return goals
+
+
+def shown_path(path: Path, cwd: Path) -> str | None:
+    """PATH relative to CWD when every part is plain and the whole is short, else None."""
+
+    relative = os.path.relpath(path, cwd)
+    parts = relative.split(os.sep)
+    named = list(itertools.dropwhile(lambda part: part == "..", parts))
+    if len(relative) > MAX_PATH_CHARS or not named:
+        return None
+    if not all(PATH_PART.fullmatch(part) and part not in (".", "..") for part in named):
+        return None
+    return "/".join(parts)
+
+
+def session(payload: dict) -> dict | None:
+    cwd = payload.get("cwd")
+    folder = Path(cwd) if isinstance(cwd, str) and os.path.isabs(cwd) else Path.cwd()
+    # A session folder that is missing or cannot be listed is an error, so nothing is said.
+    with os.scandir(folder):
+        pass
+    goals = active_goals(project_root(folder))
+    if not goals:
+        return None
+    lines = []
+    for path, status in goals:
+        name = shown_path(path, folder)
+        if name is None or len(lines) == MAX_GOALS_SHOWN:
+            continue
+        lines.append(f"- {name} (STATUS: {status})" if status in KNOWN_STATUSES else f"- {name} (STATUS not shown)")
+    if len(goals) > len(lines):
+        lines.append(f"- {len(goals) - len(lines)} more active goal file(s) not listed")
+    context = "\n".join((SESSION_INTRO, *lines))
+    return {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": context}}
+
+
 def main(argv: list[str] | None = None) -> int:
     argv = sys.argv[1:] if argv is None else argv
-    if len(argv) != 1 or argv[0] not in ("pre-tool", "stop"):
-        print("usage: flow_guard.py pre-tool|stop  (reads the hook payload on stdin)", file=sys.stderr)
+    if len(argv) != 1 or argv[0] not in ("pre-tool", "stop", "session"):
+        print("usage: flow_guard.py pre-tool|stop|session  (reads the hook payload on stdin)", file=sys.stderr)
         return 1
+    if argv[0] == "session":
+        # Whatever goes wrong, a session must start with no guard text and no error notice.
+        try:
+            payload = json.loads(sys.stdin.read())
+            result = session(payload) if isinstance(payload, dict) else None
+            if result is not None:
+                sys.stdout.write(json.dumps(result) + "\n")
+                sys.stdout.flush()
+        except Exception:
+            # Output that could not be written must not fail again when Python exits.
+            try:
+                os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+            except (OSError, ValueError):
+                pass
+        return 0
     try:
         payload = json.loads(sys.stdin.read())
     except ValueError as exc: