@appchy/jarvis 0.1.36 → 0.1.39

package/harness/harness/wrap.py

@@ -0,0 +1,217 @@
+"""Finishing a session cleanly — what only a machine knows, and what to do about it.
+
+**It COMPUTES and never WRITES.** A handoff is prose about judgement: what is actually
+left, what is risky, what the next session must not assume. A tool that writes one
+produces something plausible and wrong, which is worse than blank because it reads as
+considered. So this reports, the agent writes, and the person approves. It must not
+edit governance for the same reason — a tool that quietly rewrites a rule to make its
+own check pass is the worst available version of this.
+
+Everything here is a thing a session cannot reliably remember and a machine can simply
+answer. The sharpest is the first: work that is not in git. Three tasks have been
+completed on this board with their implementation in no commit anywhere, one of them
+the task about that exact failure.
+"""
+from pathlib import Path
+
+from . import git, kickoff, report
+from .model import scan
+from .tree import cli, find_work_root
+
+
+def cmd_wrap(cfg: dict, args=None, repo=None) -> int:
+    """Print the wrap brief: what a machine knows, then what the session must do."""
+    args = args or {}
+    root = find_work_root()
+    repo = Path(repo) if repo is not None else root.parent
+    out = ["wrap — finish this session cleanly. What only a machine knows, first:"]
+    out += _uncommitted(repo)
+    out += _in_flight(root)
+    out += _governance_touched(repo)
+    out += _misaligned(root)
+    out.append("")
+    out += _steps(cfg, root, args.get("task"))
+    print("\n".join(out))
+    return 0
+
+
+def _uncommitted(repo) -> list:
+    """Work that exists only on this disk — the one finding worth interrupting for.
+
+    Said as a refusal to round down. "3 files uncommitted" reads as routine; a session
+    that has just been told its work would be lost does not skim.
+    """
+    code, out, _ = git._git(repo, "status", "--porcelain", "--untracked-files=all")
+    if code != 0:
+        return ["  code in git: cannot tell — this is not a git repo, or git did not "
+                "answer. Check it yourself before you walk away."]
+    paths = [line[3:] for line in out.splitlines() if len(line) > 3]
+    # The board writes itself, so its own churn is not somebody's unsaved work.
+    theirs = [p for p in paths if not p.startswith("work/")]
+    if not theirs:
+        ahead = _unpushed(repo)
+        if ahead:
+            return [f"  code in git: committed, and {ahead} commit(s) are NOT PUSHED — "
+                    f"they exist on this machine only."]
+        return ["  code in git: yes — nothing uncommitted outside the board."]
+    listed = "\n      ".join(sorted(theirs)[:20])
+    more = f"\n      … and {len(theirs) - 20} more" if len(theirs) > 20 else ""
+    return [f"  YOUR WORK IS NOT IN GIT — {len(theirs)} file(s) changed and "
+            f"uncommitted. Committing them is step 0, before any of the below:"
+            f"\n      {listed}{more}"]
+
+
+def _unpushed(repo) -> int:
+    """Commits this clone holds that its upstream does not, or 0 when there is no
+    upstream to compare against — which is not the same as nothing to push, and is
+    reported as nothing rather than guessed at."""
+    code, out, _ = git._git(repo, "rev-list", "--count", "@{upstream}..HEAD")
+    try:
+        return int(out.strip()) if code == 0 else 0
+    except ValueError:
+        return 0
+
+
+def _in_flight(root) -> list:
+    """Items the board still says somebody is on.
+
+    A session that walks away from one leaves the board claiming a person who is not
+    there — which is the state every other session then plans around.
+    """
+    live = [t for v in scan(root)["versions"] for t in v.all_tasks()
+            if t.status == "in-progress"]
+    if not live:
+        return ["  in progress: nothing — the board claims nobody is on anything."]
+    named = "\n      ".join(f"{t.name} — {t.title}" for t in live)
+    return [f"  in progress: {len(live)} item(s). Move what finished, park what did "
+            f"not — the bucket IS the status:\n      {named}"]
+
+
+def _governance_touched(repo) -> list:
+    """Which descriptions of the world this run changed.
+
+    Governance and specs are what go stale first: a rule, a feature spec or an
+    architecture doc that moved makes everything citing it possibly wrong, and nothing
+    else in a session notices.
+
+    "This run" is everything the world has not seen yet — the working tree plus any
+    commit ahead of the upstream. Deliberately not the session's own commits: a run
+    that picked up yesterday's unfinished edit is still the run responsible for it.
+    """
+    seen = set()
+    code, out, _ = git._git(repo, "status", "--porcelain", "--untracked-files=all")
+    if code == 0:
+        seen.update(line[3:] for line in out.splitlines() if len(line) > 3)
+    code, out, _ = git._git(repo, "diff", "--name-only", "@{upstream}..HEAD")
+    if code == 0:
+        seen.update(p for p in out.splitlines() if p.strip())
+
+    docs = sorted(p for p in seen if p.startswith("work/")
+                  and p.endswith(".md")
+                  and "/versions/" not in p and "/backlog/" not in p)
+    if not docs:
+        return ["  descriptions of the world: none changed by this run."]
+    listed = "\n      ".join(docs[:15])
+    more = f"\n      … and {len(docs) - 15} more" if len(docs) > 15 else ""
+    return [f"  descriptions of the world CHANGED by this run — whatever cites these "
+            f"may now be stale, and a rule added without `enforced_by:` is a wish:"
+            f"\n      {listed}{more}"]
+
+
+def _misaligned(root) -> list:
+    """The tree's own misalignments, from the sweep that already knows them.
+
+    `align` is report-only and exits 0, which is why nothing makes anybody look at it.
+    Wrap is the moment somebody looks.
+    """
+    try:
+        findings = report.misalignments(root)
+    except (OSError, ValueError):
+        return []
+    loud = [f for f in findings if f[0] in ("error", "warn")]
+    if not loud:
+        return ["  alignment: clean."]
+    shown = "\n      ".join(f"{cls}: {msg}" for _, cls, msg in loud[:8])
+    more = f"\n      … `{cli()} align` has the rest" if len(loud) > 8 else ""
+    return [f"  alignment: {len(loud)} thing(s) the tree disagrees with itself about. "
+            f"Fix what this session caused; the rest is somebody's to pick up:"
+            f"\n      {shown}{more}"]
+
+
+def _steps(cfg: dict, root, task) -> list:
+    """What the session does with all of that. The order matters: the handoff is
+    written while the reasoning is still in the room, and the successor is started
+    last, from a file that is already current."""
+    out = [
+        "Then, in order — report what you did, and say plainly where there was "
+        "nothing to do:",
+        "",
+        f"  1. THE HANDOFF — `{cli()} handoff <task>`. Fill it so a session that has "
+        "never seen this work continues without re-deriving anything. `**Status:**` "
+        "and `**NEXT:**` stay the top two lines: they are what gets read, and step 5 "
+        "lifts them straight into the next session's prompt. Write down the dead ends, "
+        "the thing that was not where it looked, the constraint found halfway — the "
+        "code is in git and the reasoning is not.",
+        "",
+        "  2. BRING THE DOCS TO CURRENT. A brief describing a design you abandoned is "
+        "worse than no brief, because the next session builds against it. The task's "
+        "criteria, the epic's plan where it settled something a sibling now inherits, "
+        "the owning feature spec and its `state:` if the evidence moved, and any "
+        "durable rule this work established — in the domain or system that owns it.",
+        "",
+        f"  3. MOVE WHAT FINISHED — `{cli()} move <task> complete`, with what shipped "
+        "and what it deliberately leaves out. If the gate refuses, the refusal is the "
+        "truth: run the verify commands, or record what you saw with "
+        f"`{cli()} observed`. Never move a task the gate declined.",
+        "",
+        f"  4. PARK WHAT IS STILL OPEN — `{cli()} ask <task> --question \"…\"`. A "
+        "question carried in your head all session is one the next session has to "
+        "rediscover. Park it or answer it here; do not hand it across as a note.",
+    ]
+    out += _successor(cfg, root, task)
+    return out
+
+
+def _successor(cfg: dict, root, task) -> list:
+    """The last step, which is a different step depending on what this repo has.
+
+    Telling a repo with no session starter to start one would be inventing a
+    capability; telling one that has a starter to leave a prompt for a person would be
+    withholding what is already wired up.
+    """
+    head = (f"  5. THE NEXT SESSION — `{cli()} kickoff <task>` prints the prompt. "
+            "Never write one by hand: a hand-written prompt has never opened a session "
+            "with the method actually loaded, which is why this is a command and not a "
+            "template.")
+    tail = ("Start it only if the task is still in progress and the person asked for "
+            "it in this session — wrapping finished work and spawning a session on the "
+            "next thing is their call, not a default of wrapping. Then "
+            f"`{cli()} session <task> --id <sessionId>` so the successor lands on the "
+            "board rather than in a line of prose.")
+    if not cfg["session"]["mcp"]:
+        return ["", head + " This repo names no session starter, so print the prompt "
+                "and stop — that is a mode, not a failure."]
+
+    ready = _prompt(root, task)
+    if ready:
+        return ["", head, "",
+                "  The prompt, already derived — pass it VERBATIM, including the order "
+                "of its first two lines, and the repo root as `cwd`:", "",
+                "  ---8<---", ready, "  ---8<---", "", "  " + tail]
+    return ["", head + " " + tail]
+
+
+def _prompt(root, task) -> str:
+    """The kickoff prompt for `task`, or empty when there is no one obvious task.
+
+    Named rather than guessed: with several items in progress, picking one would be
+    the tool deciding what the session was about.
+    """
+    live = [t for v in scan(root)["versions"] for t in v.all_tasks()
+            if t.status == "in-progress" and (not task or t.name == task)]
+    if len(live) != 1:
+        return ""
+    try:
+        return kickoff.build_prompt(live[0], root)
+    except (OSError, ValueError, KeyError):
+        return ""

package/harness/hooks/guard.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""PreToolUse(Bash) — the floor under an unattended shift.
+
+The harness's other hook is a sensor: it prints and decides nothing, which is the
+right shape when a person is at the keyboard, because that person IS the floor
+under a destructive command. On a schedule there is no such person, and the cost
+of the failure is asymmetric in a way ordinary bugs are not — everything else the
+harness guards against is recoverable by re-running, and `rm -rf` is not.
+
+Three design rules, and they matter more than the pattern list:
+
+**Fail open.** An unparseable command, an unknown binary, or a crash in here
+allows. A guard that breaks sessions gets disabled, and a disabled guard protects
+nothing.
+
+**Block only the unrecoverable.** Every false positive spends the guard's
+authority, and an authority-less guard is switched off by the next person it
+annoys. `rg "DROP TABLE"` searches for a string; `psql -c "DROP TABLE"` drops a
+table. This reads the command, it does not grep the line.
+
+**Warn-but-allow is a real third state.** `--no-verify`, `npm publish`,
+`terraform apply`, `kubectl delete` are all recoverable and all worth naming.
+
+Ships INERT — `hooks.json` does not register it. A hook that narrows what runs on
+someone's machine is their call to install, not the plugin's to assume.
+"""
+import json
+import re
+import shlex
+import sys
+
+# --- unrecoverable: deny -----------------------------------------------------
+# Each entry is (name, predicate over the argv list, what to do instead).
+# Predicates take the parsed argv so a quoted string argument can never be
+# mistaken for the operation it names, plus `stdin` — what an upstream command in
+# the same pipeline feeds them, because for some binaries that IS the instruction.
+
+#: Paths whose recursive removal is never a legitimate build step.
+_FATAL_RM = re.compile(r"^(/|~|\$HOME|/\*|~/\*|\.\.?/?)$")
+#: An unexpanded variable in an `rm -rf` target. `rm -rf "$DIR/build"` with DIR
+#: unset is `rm -rf /build` — the single most common way this goes wrong.
+_BARE_VAR = re.compile(r"^\$\{?\w+\}?/?\*?$")
+_SQL_FATAL = re.compile(r"\b(drop\s+(table|database|schema)|truncate\s+table)\b", re.I)
+_SQL_UNSCOPED = re.compile(r"\b(delete\s+from|update)\b(?!.*\bwhere\b)", re.I | re.S)
+_PROTECTED = ("main", "master", "release", "production", "prod")
+
+
+def _rm(argv, stdin=""):
+    if argv[0] != "rm":
+        return None
+    flags = "".join(a for a in argv[1:] if a.startswith("-"))
+    if not ("r" in flags and "f" in flags):
+        return None
+    for target in [a for a in argv[1:] if not a.startswith("-")]:
+        if _FATAL_RM.match(target):
+            return (f"`rm -rf {target}` removes the filesystem or the home "
+                    f"directory.", "Name the directory explicitly.")
+        if _BARE_VAR.match(target):
+            return (f"`rm -rf {target}` — an unset variable makes this a path you "
+                    f"did not mean.", "Expand it first and check it is non-empty.")
+    return None
+
+
+def _git(argv, stdin=""):
+    if argv[0] != "git":
+        return None
+    sub = argv[1] if len(argv) > 1 else ""
+    rest = argv[2:]
+    joined = " ".join(rest)
+    if sub == "push" and any(f in rest for f in ("--force", "-f")):
+        if "--force-with-lease" in rest:
+            return None
+        return ("`git push --force` overwrites history someone else may have "
+                "pulled.", "Use `--force-with-lease`, which refuses if the remote "
+                "moved.")
+    if sub == "push" and any(b in rest for b in _PROTECTED) and "--delete" in rest:
+        return ("deleting a protected branch on the remote.", "Do it in the host's "
+                "UI, where it is undoable.")
+    if sub == "reset" and "--hard" in rest:
+        return ("`git reset --hard` discards every uncommitted change with no "
+                "reflog entry for the working tree.", "`git stash` keeps them.")
+    if sub == "clean" and re.search(r"-\w*f", joined) and re.search(r"-\w*d", joined):
+        return ("`git clean -fd` deletes untracked files permanently — including "
+                "the ones never added yet.", "`git clean -nd` lists them first.")
+    if sub == "checkout" and rest and rest[0] in (".", "--"):
+        return ("`git checkout .` discards every uncommitted change.",
+                "`git stash` keeps them.")
+    return None
+
+
+def _sql(argv, stdin=""):
+    """A SQL client handed a statement. The binary is what distinguishes running it
+    from searching for it.
+
+    `stdin` is read as part of the statement because for a SQL client it IS one:
+    `echo "DROP TABLE users" | psql prod` drops the table exactly as the `-c` form
+    does, and looking only at the command line missed it. What flows in from a FILE
+    is still invisible here, and deliberately — `cat migration.sql | psql prod` is the
+    normal way to run a migration, and denying it would spend the guard's authority
+    on the case it is meant to serve."""
+    if argv[0] not in ("psql", "mysql", "sqlite3", "mongosh", "clickhouse-client"):
+        return None
+    body = " ".join(argv[1:] + ([stdin] if stdin else []))
+    if _SQL_FATAL.search(body):
+        return ("a DROP/TRUNCATE against a live database.",
+                "Run it in a migration that has a tested down-step.")
+    if _SQL_UNSCOPED.search(body):
+        return ("a DELETE or UPDATE with no WHERE clause — it rewrites every row.",
+                "Add a WHERE, or SELECT it first to see the blast radius.")
+    return None
+
+
+def _fs(argv, stdin=""):
+    head = argv[0]
+    joined = " ".join(argv)
+    if head == "mkfs" or head.startswith("mkfs."):
+        return ("`mkfs` formats a device.", "There is no undo. Do this by hand.")
+    if head == "dd" and any(a.startswith("of=/dev/") for a in argv):
+        return ("`dd` writing straight to a device.", "There is no undo.")
+    if head == "chmod" and "777" in joined:
+        return ("`chmod 777` makes it world-writable.",
+                "755 for a directory, 644 for a file.")
+    if head in ("curl", "wget") and "|" in joined:
+        return ("piping a download into a shell runs code nobody has read.",
+                "Download it, read it, then run it.")
+    return None
+
+
+DENY = (_rm, _git, _sql, _fs)
+
+#: Recoverable, but worth saying out loud. Substring match on the command line is
+#: fine here: the cost of a false positive is one extra line of output.
+WARN = {
+    "--no-verify": "skips the pre-commit hooks this repo installed on purpose",
+    "npm publish": "publishes to the registry — a version number cannot be reused",
+    "pnpm publish": "publishes to the registry — a version number cannot be reused",
+    "terraform apply": "changes real infrastructure",
+    "terraform destroy": "tears down real infrastructure",
+    "kubectl delete": "removes a live resource",
+    "docker system prune": "removes every unused image, container and volume",
+}
+
+
+#: Operator characters that end one command and begin the next. `(`, `)`, `<` and
+#: `>` are here so a redirect or a subshell cannot glue two commands into one argv.
+_OPERATORS = set("|&;\n()<>")
+
+#: Words that stand in FRONT of the real command. `xargs` earns its place the same
+#: way `sudo` does: `… | xargs rm -rf ~` runs `rm -rf ~`, and reading `xargs` as the
+#: command is how that got through.
+_PREFIXES = ("sudo", "env", "time", "nohup", "xargs")
+
+
+def _segments(command: str):
+    """The command as `(argv, pipes_into_something)` pairs — or None if unparseable.
+
+    **One tokenizer, and it is the shell's own.** This used to `re.split` on the
+    operators and then `shlex.split` each piece, which reads a quote as ordinary text
+    until it is too late: `psql -c "DROP TABLE users;"` was cut at the semicolon
+    INSIDE the string, both halves then failed to parse as unbalanced quotes, and the
+    command sailed past every rule. Measured — that exact line was allowed while the
+    same statement without its trailing semicolon was denied, and a trailing semicolon
+    is how SQL is normally written.
+
+    Tokenizing first, with the operators declared as operators, is what makes a quoted
+    `;` stay inside its argument and a real `;` end the command. `|` becomes a genuine
+    separator too, so what a pipe feeds is a command in its own right rather than a
+    tail nobody looked at.
+    """
+    lex = shlex.shlex(command, posix=True, punctuation_chars="();<>|&\n")
+    lex.whitespace_split = True
+    # Newline is an operator here, not blank space between words: `echo hi\nrm -rf ~`
+    # is two commands, and reading it as one leaves `rm` sitting in `echo`'s arguments
+    # where no rule looks for it.
+    lex.whitespace = " \t\r"
+    try:
+        tokens = list(lex)
+    except ValueError:
+        return None  # unbalanced quotes — not ours to judge
+    out, current = [], []
+    for token in tokens:
+        if token and set(token) <= _OPERATORS:
+            if current:
+                out.append((current, token.startswith("|")))
+            current = []
+        else:
+            current.append(token)
+    if current:
+        out.append((current, False))
+    return out
+
+
+def check(command: str):
+    """(decision, message) — `decision` is 'deny', 'warn' or None."""
+    # A compound command is checked segment by segment, so `cd x && rm -rf /` is
+    # not read as one harmless `cd`.
+    fed_by = ""
+    for argv, pipes_on in _segments(command) or []:
+        # What the previous stage of a pipeline produced, for the next one to read.
+        # Carried across the loop rather than looked up, so a rule sees its own input
+        # without knowing anything about the shape of the whole command line.
+        upstream, fed_by = fed_by, " ".join(argv[1:]) if pipes_on else ""
+        # `env A=b cmd`, `sudo cmd`, `time cmd`, `xargs cmd` — look past the prefix.
+        while argv and (argv[0] in _PREFIXES
+                        or "=" in argv[0] and not argv[0].startswith("-")):
+            argv = argv[1:]
+        if not argv:
+            continue
+        # Whether this feeds another command is a property of the segment, and a rule
+        # reads it off the argv it is handed — which is what `curl … | sh` turns on.
+        probe = argv + ["|"] if pipes_on else argv
+        for rule in DENY:
+            try:
+                hit = rule(probe, upstream)
+            except Exception:
+                hit = None  # fail open, always
+            if hit:
+                what, instead = hit
+                return "deny", f"blocked: {what}\nInstead: {instead}"
+    low = command.lower()
+    for needle, why in WARN.items():
+        if needle in low:
+            return "warn", f"note: `{needle}` {why}."
+    return None, ""
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0  # fail open
+    if payload.get("tool_name") != "Bash":
+        return 0
+    command = str((payload.get("tool_input") or {}).get("command", ""))
+    if not command.strip():
+        return 0
+
+    try:
+        decision, message = check(command)
+    except Exception:
+        return 0  # fail open on our own bug, always
+
+    if decision == "deny":
+        print(json.dumps({"hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": message,
+        }}))
+        return 0
+    if decision == "warn":
+        print(message, file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception:
+        sys.exit(0)