buddie 1.0.0__py3-none-any.whl

buddie/__init__.py

@@ -0,0 +1,3 @@
+"""buddie: an evidence layer for orchestrator/executor chats (audit/08). Engine: verbatim + anchors."""
+
+__version__ = "1.0.0"

buddie/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from buddie.cli import main
+
+sys.exit(main())

buddie/anchors.py

@@ -0,0 +1,216 @@
+"""State claims in a report: `⚓ path#sha256`, `⚓ path@commit`, `⚓ fact=value` (lab README, rule 7).
+
+This is the repo-agnostic half of lab's tools/anchors.py: the report is a message from another session, so the
+repository it talks about is not known in advance. Each anchor is resolved against the given repos in order:
+
+  path#sha     HOLDS when some repo has the file and its sha256 starts with the prefix; BROKEN when a repo has
+               the file with other bytes; UNCHECKABLE when no repo has that path
+  path@commit  HOLDS when some repo has the commit and the file in it; BROKEN when the commit is there without
+               the file; UNCHECKABLE when no repo has the commit (shallow clone, another repository)
+  fact=value   computed by FACTS of the first repo with tools/anchors.py (lab); UNCHECKABLE when none has it
+
+pr:, ci: and run: anchors (a PR's state, checks on a commit, a command and its output) are judged by effects.py
+against GitHub and the session transcript given in ctx; choice:<id>=<step> (what the person picked on a summary card)
+by summary.py against the hook's journal.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import re
+import subprocess
+from pathlib import Path
+
+# the sign inside the backticks (`⚓ x`) or right before them (⚓ `x`, as people and the buddie skill write it)
+BACKTICKED = re.compile(r"(?:`⚓\s*|(?:(?<!`)⚓\s*|⚓\s+)`\s*)([^`\s][^`]*?)\s*`")
+FILE_SHA = re.compile(r"^(?P<path>[^#@=\s]+)#(?P<sha>[0-9a-f]{12,64})$")
+FILE_AT = re.compile(r"^(?P<path>[^#@=\s]+)@(?P<commit>[0-9a-f]{7,40})$")
+FACT = re.compile(r"^(?P<name>[a-z0-9_.]+)=(?P<value>\S+)$")
+CODE_SPAN = re.compile(r"`[^`]*`")
+BARE_SIGN = re.compile(r"⚓[ \t]*(?=[^\s`⚓])")
+# a placeholder from the anchor table, not a claim: «(⚓ path@commit, … or ⚓ run:CMD => OUTPUT)» quoted from a return
+TEMPLATE = re.compile(r"<[^>]*>|…|\b(?:OWNER/REPO|SHA)\b|^(?:path#sha256|path@commit|fact=value)$")
+RUN_TEMPLATE = re.compile(r"^run:\s*(?:CMD|<[^>]*>)(?:\s|$)|=>\s*(?:OUT|OUTPUT|<[^>]*>)$")
+TRAIL = ".,;:!?»\"'"
+
+
+def _bare_end(line: str, start: int) -> int:
+    """Where a bare anchor's run: claim ends: the next sign, a table cell's border (a line that starts with |),
+    or the end of the line."""
+    end = len(line)
+    if (nxt := line.find("⚓", start)) != -1:
+        end = nxt
+    if line.lstrip().startswith("|") and (bar := line.find("|", start)) != -1:
+        end = min(end, bar)
+    return end
+
+
+def _bare(line: str, start: int) -> tuple[str, int] | None:
+    """The bare anchor (no backticks, E017 / NEXT №97) that starts at `start` and where it ends; None when the text
+    after the sign is not an anchor (prose, a placeholder): a bare sign is a claim only in an anchor's own form."""
+    from buddie import effects
+    rest = line[start:_bare_end(line, start)]
+    if rest.startswith("run:"):  # CMD => OUT holds spaces: to the end of the line or the delimiter
+        cand = rest.rstrip()
+        cand = cand.rstrip(TRAIL + " ")
+        if cand.endswith(")") and cand.count(")") > cand.count("("):
+            cand = cand[:-1].rstrip()
+        end = start + len(cand)
+    else:
+        token = rest.split()[0] if rest.split() else ""
+        cand = token.rstrip(TRAIL)
+        if cand.endswith(")") and "(" not in cand:
+            cand = cand.rstrip(")" + TRAIL)
+        end = start + len(cand)
+    if not cand or (RUN_TEMPLATE.search(cand) if cand.startswith("run:") else TEMPLATE.search(cand)):
+        return None
+    ok = (FILE_SHA.match(cand) or FILE_AT.match(cand) or FACT.match(cand) or cand.startswith("choice:")
+          or effects.PR.match(cand) or effects.CI.match(cand) or effects.RUN.match(cand))
+    return (cand, end) if ok else None
+
+
+def spans(line: str) -> list[tuple[int, int, str]]:
+    """(start, end, anchor) of each anchor on a line: in backticks, or bare after the sign up to a space (a file,
+    a commit, a fact, a PR) or, for run:, to the end of the line or the delimiter (NEXT №97)."""
+    found = [(m.start(), m.end(), m.group(1)) for m in BACKTICKED.finditer(line)]
+    masked = list(line)
+    for a, b, _ in found:
+        masked[a:b] = " " * (b - a)
+    masked = CODE_SPAN.sub(lambda m: " " * len(m.group()), "".join(masked))
+    for m in BARE_SIGN.finditer(masked):
+        if got := _bare(masked, m.end()):
+            found.append((m.start(), got[1], got[0]))
+    return sorted(found)
+
+
+class _Anchors:
+    """The anchors of a text, as the regex it replaces was used: findall, search, sub, line by line."""
+
+    def findall(self, text: str) -> list[str]:
+        return [a for line in text.split("\n") for _, _, a in spans(line)]
+
+    def search(self, text: str) -> bool:
+        return any(spans(line) for line in text.split("\n"))
+
+    def sub(self, repl: str, text: str) -> str:
+        out = []
+        for line in text.split("\n"):
+            for a, b, _ in reversed(spans(line)):
+                line = line[:a] + repl + line[b:]
+            out.append(line)
+        return "\n".join(out)
+
+
+ANCHOR = _Anchors()
+
+HOLDS, BROKEN, UNCHECKABLE = "HOLDS", "BROKEN", "UNCHECKABLE"
+
+
+def _git(repo: Path, *args: str) -> int:
+    return subprocess.run(["git", "-C", str(repo), *args], capture_output=True).returncode
+
+
+def _facts(repo: Path):
+    """tools/anchors.py of a repo that has one (lab), loaded once; None otherwise."""
+    path = repo / "tools" / "anchors.py"
+    if not path.is_file():
+        return None
+    spec = importlib.util.spec_from_file_location(f"buddie_facts_{abs(hash(str(repo)))}", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def check_one(anchor: str, repos: list[Path], cache: dict, ctx: dict | None = None) -> dict:
+    from buddie import effects
+    if effects.is_effect(anchor):
+        return effects.check(anchor, ctx)
+    if anchor.startswith("choice:"):
+        from buddie.summary import check_choice
+        return check_choice(anchor, ctx)
+    out = {"anchor": anchor}
+    if m := FILE_SHA.match(anchor):
+        for repo in repos:
+            target = repo / m["path"]
+            if target.is_file():
+                actual = hashlib.sha256(target.read_bytes()).hexdigest()
+                if actual.startswith(m["sha"]):
+                    return dict(out, status=HOLDS, repo=str(repo))
+                out.update(status=BROKEN, repo=str(repo), why=f"sha256 is now {actual[:12]}")
+        return out if "status" in out else dict(out, status=UNCHECKABLE, why=f"no repo has {m['path']}")
+    if m := FILE_AT.match(anchor):
+        for repo in repos:
+            if _git(repo, "cat-file", "-e", f"{m['commit']}^{{commit}}") != 0:
+                continue
+            if _git(repo, "cat-file", "-e", f"{m['commit']}:{m['path']}") == 0:
+                return dict(out, status=HOLDS, repo=str(repo))
+            return dict(out, status=BROKEN, repo=str(repo), why=f"{m['commit']} has no {m['path']}")
+        return dict(out, status=UNCHECKABLE, why=f"no repo has commit {m['commit']} (fetch it, or full history)")
+    if m := FACT.match(anchor):
+        for repo in repos:
+            key = ("facts", str(repo))
+            if key not in cache:
+                cache[key] = _facts(repo)
+            module = cache[key]
+            if module is None:
+                continue
+            if m["name"] not in module.FACTS:
+                return dict(out, status=BROKEN, repo=str(repo), why=f"unknown fact {m['name']}")
+            vkey = ("value", str(repo), m["name"])
+            if vkey not in cache:
+                cache[vkey] = str(module.fact(m["name"]))
+            if cache[vkey] == m["value"]:
+                return dict(out, status=HOLDS, repo=str(repo))
+            return dict(out, status=BROKEN, repo=str(repo), why=f"is now {cache[vkey]}")
+        return dict(out, status=UNCHECKABLE, why="no repo defines facts (tools/anchors.py)")
+    return dict(out, status=BROKEN, why="not an anchor: expected path#sha256, path@commit, fact=value, pr:, ci:, run: or choice:")
+
+
+def check_text(text: str, repos: list[Path], ctx: dict | None = None) -> list[dict]:
+    """ctx for effect anchors: {"github": a GET function or None (offline), "transcript": the session jsonl}."""
+    results, cache, ctx = [], {}, ctx if ctx is not None else {}
+    for number, line in enumerate(text.splitlines(), 1):
+        for anchor in ANCHOR.findall(line):
+            results.append(dict(check_one(anchor, repos, cache, ctx), line=number))
+    return results
+
+
+# a number stated as a fact ("73 из 84", "11 %", "505 цитат", "0,61"); ids, dates, times, links and code are not
+COUNT = re.compile(r"(?<![\w#№.,:/-])\d+(?:[.,]\d+)?(?![\w.:/-]|,\d)")
+# a lone year names a time, as a date does (NEXT №108: «по переписи 2020 года», «за 2024 год», «April 2026»,
+# «(2021)»): 1800-2099, or a range of two, followed by a year word, or after a month (with its day: «14 марта 2024»),
+# after in/since/until, or in brackets
+_Y = r"(?<![\w#№.,:/-])(?:1[89]|20)\d{2}(?![\w,:/-]|\.\d)"
+_MONTH = (r"(?i:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|june?|july?|aug(?:ust)?|sep(?:t(?:ember)?)?"
+          r"|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?|январ[а-я]*|феврал[а-я]*|март[а-я]*|апрел[а-я]*|ма[йяе]|июн[а-я]*"
+          r"|июл[а-я]*|август[а-я]*|сентябр[а-я]*|октябр[а-я]*|ноябр[а-я]*|декабр[а-я]*)")
+YEAR = re.compile(rf"(?:{_Y}\s*[–—]\s*)?{_Y}(?=\s*(?:-(?:го|м|й|х)\b|гг?\.|(?i:год[а-я]*|year)\b))"
+                  rf"|(?:\b\d{{1,2}}\s+)?\b{_MONTH}\s+{_Y}|\b(?i:in|since|until)\s+{_Y}|\(\s*{_Y}\s*\)")
+NOT_COUNT = re.compile(r"`[^`]*`|\[[^\]]*\]\([^)]*\)|https?://\S+|\b\d{4}-\d{2}-\d{2}\b|\b\d{1,2}:\d{2}\b|" + YEAR.pattern)
+
+
+def counts(line: str) -> list[str]:
+    """The counts and shares a line states, leaving out ids, dates, lone years, times, links and code."""
+    return COUNT.findall(NOT_COUNT.sub(" ", line))
+
+
+def unanchored_lines(text: str, backed=()) -> list[int]:
+    """Numbers of the lines that state a count with no anchor on the line; `backed` lines (a quote found on the page
+    the line links, verify.quote_backed) carry their source and are left out."""
+    return [n for n, line in enumerate(text.splitlines(), 1)
+            if n not in backed and not ANCHOR.search(line) and counts(line)]
+
+
+def unanchored(text: str, limit: int = 5, backed=()) -> tuple[int, list[str]]:
+    """Lines that state a count or a share with no anchor on the line (E003: bare numbers drift when relayed).
+    A signal for the reader, never a failure: chat replies are not bound by the anchor rule."""
+    found, lines = unanchored_lines(text, backed), text.splitlines()
+    return len(found), [f"line {n}: {lines[n - 1].strip()[:120]}" for n in found[:limit]]
+
+
+def find_repos(cwd: Path) -> list[Path]:
+    """The git repo around cwd, else the git repos directly under it (a cloud session clones each repo there)."""
+    top = subprocess.run(["git", "-C", str(cwd), "rev-parse", "--show-toplevel"], capture_output=True, text=True)
+    if top.returncode == 0:
+        return [Path(top.stdout.strip())]
+    return sorted(p for p in cwd.iterdir() if (p / ".git").exists()) if cwd.is_dir() else []

buddie/cli.py

@@ -0,0 +1,215 @@
+"""buddie command line.
+
+  buddie verify REPORT [--repo DIR ...] [--no-fetch] [--access default] [--numbers gap|fail|off] [--json receipt.json]
+                [--transcript SESSION.jsonl] [--no-github]
+                                    receipt for a report; exit 1 on FAIL
+  buddie mandate queue|accepted|verdict [N ...] [--repo DIR] [--rev COMMIT]
+                                    the work queue itself: done rows anchored, accepted plans quoting the user,
+                                    auto/ask per row; exit 1 when a claim is BROKEN
+  buddie journal lessons|measure [PATH ...] [--since TIME] [--sessions 10] [--skip SESSION]
+                                    the gate's journal (files or dirs of *.jsonl; default: the hook's own): what
+                                    past sessions were sent back for (SessionStart prints it), and NEXT №55's measure
+  buddie summary [--session ID] [--repo DIR] [--no-queue] [--stale 30] [--text]
+                                    when no subagent is left: what they did, what was lost, the next steps with
+                                    auto/ask and a ready AskUserQuestion card (JSON; --text only the text)
+  buddie init [--repo DIR]          write buddie.toml with the default levels and the intro mode on
+  buddie intro [--false] [--repo DIR]
+                                    where the intro mode stands; --false: the last return was false, restart the count
+  buddie enforce [--repo DIR]       end the intro mode: returns block from now on
+  buddie serve                      MCP server on stdio (verify_report, snap, source_text, summary)
+  buddie serve --http [--host 127.0.0.1] [--port 8000]
+                                    remote MCP server over Streamable HTTP at /mcp (remote.py: no files, no
+                                    local repos, public addresses only)
+  buddie hook                       Claude Code hook: reads the event on stdin, exit 2 blocks a FAIL answer
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def cmd_verify(args) -> int:
+    from buddie.anchors import find_repos
+    from buddie.effects import github_get
+    from buddie.verify import verify
+    text = sys.stdin.read() if args.report == "-" else Path(args.report).read_text(encoding="utf-8")
+    repos = [Path(r) for r in args.repo] if args.repo else find_repos(Path.cwd())
+    receipt = verify(text, name=args.report, repos=repos, store=args.store, fetch=not args.no_fetch,
+                     access=args.access, quotes=not args.anchors_only, rev=args.rev,
+                     github=None if args.no_github else github_get, transcript=args.transcript,
+                     numbers=args.numbers)
+    pred = receipt["predicate"]
+    if args.json:
+        Path(args.json).write_text(json.dumps(receipt, ensure_ascii=False, indent=1) + "\n", encoding="utf-8")
+    for item in pred["blocking"]:
+        print(f"BLOCK {item}")
+    for item in pred["gaps"]:
+        print(f"gap   {item}")
+    for item in pred.get("notes", []):
+        print(f"note  {item}")
+    print(pred["line"])
+    return 1 if pred["outcome"] == "FAIL" else 0
+
+
+def cmd_mandate(args) -> int:
+    from buddie import mandate as man
+    from buddie.anchors import find_repos
+    repos = [Path(r) for r in args.repo] if args.repo else find_repos(Path.cwd())
+    cfg = man.find_config(repos)
+    if cfg is None:
+        print(f"no {man.CONFIG} with a [mandate] section in {', '.join(map(str, repos)) or 'cwd'}", file=sys.stderr)
+        return 2
+    if args.what == "queue":
+        out = man.check_queue(cfg, args.rev)
+        claims = out["done"]
+    elif args.what == "accepted":
+        out = claims = man.check_accepted(cfg, args.rev)
+    else:
+        m = man.Mandate(cfg, args.rev)
+        out = [m.verdict(n) for n in (args.rows or [n for n in sorted(m.table)
+                                                    if m.table[n]["status"].startswith(cfg["proposed"])])]
+        claims = []
+    print(json.dumps(out, ensure_ascii=False, indent=1))
+    return 1 if man.outcome(claims) == "FAIL" else 0
+
+
+def cmd_journal(args) -> int:
+    from buddie import journal
+    from buddie.hook import journal_paths
+    rows = journal.entries([Path(p) for p in args.paths] if args.paths else journal_paths())
+    if args.what == "lessons":
+        print(journal.lessons(rows, skip_session=args.skip))
+    else:
+        print(json.dumps(journal.measure(rows, args.since, args.sessions), ensure_ascii=False, indent=1))
+    return 0
+
+
+def cmd_summary(args) -> int:
+    from buddie.anchors import find_repos
+    from buddie.summary import summarize
+    repos = [Path(r) for r in args.repo] if args.repo else find_repos(Path.cwd())
+    out = summarize(args.session, repos, queue=not args.no_queue, stale=args.stale)
+    print(out["text"] if args.text else json.dumps(out, ensure_ascii=False, indent=1))
+    if args.text and out["card"]:
+        print(json.dumps(out["card"], ensure_ascii=False))
+    return 0
+
+
+def _config_path(args) -> Path | None:
+    from buddie import config
+    from buddie.anchors import find_repos
+    return config.find([Path(r) for r in args.repo] if args.repo else find_repos(Path.cwd()) or [Path.cwd()])
+
+
+def cmd_init(args) -> int:
+    from buddie import config
+    from buddie.anchors import find_repos
+    repo = Path(args.repo[0]) if args.repo else (find_repos(Path.cwd()) or [Path.cwd()])[0]
+    try:
+        path = config.init(repo)
+    except FileExistsError as e:
+        print(f"{e} exists; not overwritten", file=sys.stderr)
+        return 1
+    print(f"wrote {path}: intro mode for the next {config.INIT_FINALS} final answers (returns only warn)")
+    return 0
+
+
+def cmd_intro(args, enforce: bool = False) -> int:
+    from buddie import config
+    path = _config_path(args)
+    if path is None:
+        print(f"no {config.CONFIG} here: run `buddie init`", file=sys.stderr)
+        return 2
+    if enforce:
+        config.enforce(path)
+    elif args.false:
+        config.false_return(path)
+    tour = config.intro(path, config.load(path))
+    print(f"{path}: " + (f"intro, {tour['seen']} of {tour['finals']} final answers passed without a false return"
+                         if tour else "enforced: returns block"))
+    return 0
+
+
+def cmd_serve(args) -> int:
+    if args.http:
+        from buddie.remote import serve as serve_http
+        return serve_http(args.host, args.port)
+    from buddie.mcp import serve
+    return serve()
+
+
+def cmd_hook(args) -> int:
+    from buddie.hook import main
+    return main()
+
+
+def main(argv: list[str] | None = None) -> int:
+    from buddie import __version__
+    for stream in (sys.stdout, sys.stderr):  # quotes, anchors and reasons are UTF-8 on every OS (Windows: cp1252)
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    p = argparse.ArgumentParser(prog="buddie", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", action="version", version=f"buddie {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("verify", help="receipt for a report")
+    s.add_argument("report", help="Markdown file, or - for stdin")
+    s.add_argument("--repo", action="append", help="repo checkout for anchors (repeatable; default: around cwd)")
+    s.add_argument("--store", help="snapshot store (default $VERBATIM_STORE or ./.verbatim)")
+    s.add_argument("--no-fetch", action="store_true", help="only use snapshots already in the store")
+    s.add_argument("--access", help="verbatim access cascade for unreadable pages, e.g. default")
+    s.add_argument("--anchors-only", action="store_true", help="skip quotes")
+    s.add_argument("--json", help="write the receipt here")
+    s.add_argument("--rev", help="judge work claims against the queue as of this commit")
+    s.add_argument("--transcript", help="Claude Code session jsonl for run: anchors")
+    s.add_argument("--no-github", action="store_true", help="leave pr:/ci: anchors UNCHECKABLE (offline)")
+    s.add_argument("--numbers", choices=("gap", "fail", "off"), default="gap",
+                   help="a number of a cited sentence not in its source: a gap (default), a failure, or not checked")
+    s.set_defaults(func=cmd_verify)
+    m = sub.add_parser("mandate", help="check the work queue and the accepted plans (buddie.toml [mandate])")
+    m.add_argument("what", choices=("queue", "accepted", "verdict"))
+    m.add_argument("rows", nargs="*", type=int)
+    m.add_argument("--repo", action="append", help="repo checkout with buddie.toml (default: around cwd)")
+    m.add_argument("--rev", help="the queue as of this commit")
+    m.set_defaults(func=cmd_mandate)
+    j = sub.add_parser("journal", help="the gate's journal: lessons for a new session, the closed-loop measure")
+    j.add_argument("what", choices=("lessons", "measure"))
+    j.add_argument("paths", nargs="*", help="journal files or directories of *.jsonl (default: the hook's own)")
+    j.add_argument("--since", default="", help="measure: sessions that started at or after this time")
+    j.add_argument("--sessions", type=int, default=10, help="measure: the first N such sessions (0: all)")
+    j.add_argument("--skip", help="lessons: leave out this session")
+    j.set_defaults(func=cmd_journal)
+    u = sub.add_parser("summary", help="summary of the subagents' results and a choice card for the next steps")
+    u.add_argument("--session", help="the session (default: the one whose hook state changed last)")
+    u.add_argument("--repo", action="append", help="repo checkout with buddie.toml for the queue (default: around cwd)")
+    u.add_argument("--no-queue", action="store_true", help="only the steps the subagents named, not the queue's rows")
+    u.add_argument("--stale", type=int, default=30, help="minutes of silence before a started subagent counts as lost")
+    u.add_argument("--text", action="store_true", help="print the text, then the card as one JSON line")
+    u.set_defaults(func=cmd_summary)
+    i = sub.add_parser("init", help="write buddie.toml with the default levels and the intro mode on")
+    i.add_argument("--repo", action="append", help="where to write it (default: the repo around cwd)")
+    i.set_defaults(func=cmd_init)
+    t = sub.add_parser("intro", help="where the intro mode stands; --false reports a false return")
+    t.add_argument("--false", action="store_true", help="the last return was false: restart the count")
+    t.add_argument("--repo", action="append", help="repo with buddie.toml (default: around cwd)")
+    t.set_defaults(func=cmd_intro)
+    e = sub.add_parser("enforce", help="end the intro mode")
+    e.add_argument("--repo", action="append", help="repo with buddie.toml (default: around cwd)")
+    e.set_defaults(func=lambda args: cmd_intro(args, enforce=True))
+    s = sub.add_parser("serve", help="MCP server on stdio, or over HTTP with --http")
+    s.add_argument("--http", action="store_true", help="Streamable HTTP at /mcp instead of stdio (remote.py)")
+    s.add_argument("--host", default=os.environ.get("BUDDIE_HTTP_HOST", "127.0.0.1"),
+                   help="address to listen on (default 127.0.0.1; 0.0.0.0 in a container)")
+    s.add_argument("--port", type=int, default=int(os.environ.get("PORT") or 8000), help="default $PORT or 8000")
+    s.set_defaults(func=cmd_serve)
+    sub.add_parser("hook", help="Claude Code hook on stdin").set_defaults(func=cmd_hook)
+    args = p.parse_args(argv)
+    try:
+        return args.func(args)
+    except FileNotFoundError as e:
+        if args.cmd not in ("verify", "mandate"):
+            raise
+        print(f"buddie {args.cmd}: {e}", file=sys.stderr)  # a missing report or --rev: usage, not FAIL (NEXT №105)
+        return 2

buddie/config.py

@@ -0,0 +1,193 @@
+"""buddie.toml for the hook (0.8, NEXT №93, audit/20 §3.2–3.3): a level per class of claims, and the intro mode.
+
+[gates] sets each class to "block" (the text goes back to the model), "warn" (it leaves, and the person sees what
+the gate would have said, as a systemMessage) or "off" (not checked):
+
+  anchors   a broken anchor (path@commit, path#sha, pr:, ci:, run:)          default block
+  quotes    a quote not on its source                                        default block
+  final     a final answer with no anchor, or a count line without one       default block
+  prose     work claimed in prose with no anchor on the line                 default warn
+  numbers   a number of a cited sentence not in its source                   default warn
+  work      a claim about the work queue that does not hold ([mandate])      default block
+  summary   a Stop returned once for the summary of the subagents' results   default off
+  promises  a Stop returned for a promise whose condition holds              default off
+
+BUDDIE_GATES="prose=block,summary=block" overrides the file (per class). A project without buddie.toml gets the
+defaults.
+
+[intro] finals = N (what `buddie init` writes): until N final answers have passed since the last false return was
+reported (`buddie intro --false`), nothing is returned: each would-be return is a warning that says what it would
+have returned. `buddie enforce` ends the intro at once. The count is kept per buddie.toml in $BUDDIE_INTRO, default
+~/.cache/buddie/intro.json.
+
+[journal] text = false (the default, NEXT №104): the hook's journal keeps receipts only (time, tool, counts,
+verdicts, exit code, the sha256 of the text), never words of the conversation. A promise line keeps its kind, row,
+condition and the sha256 of its sentence, not the sentence; a choice line keeps the hashes of the steps the person
+picked and the queue rows of a typed answer, not the questions, options or answer. text = true keeps those words
+(lab's dogfood); BUDDIE_JOURNAL_TEXT=1 or 0 overrides the file.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tomllib
+from pathlib import Path
+
+CONFIG = "buddie.toml"
+LEVELS = ("block", "warn", "off")
+DEFAULTS = {"anchors": "block", "quotes": "block", "final": "block", "prose": "warn", "numbers": "warn",
+            "work": "block", "summary": "off", "promises": "off"}
+INIT_FINALS = 20
+
+TEMPLATE = f"""# buddie config (buddie init). Each class of claims is "block", "warn" or "off".
+[gates]
+anchors = "block"   # a broken anchor: path@commit, path#sha256, pr:, ci:, run:
+quotes = "block"    # a quote not on its source
+final = "block"     # a final answer with no anchor, or a count line without one
+prose = "warn"      # "merged", "tests passed" in prose with no anchor on the line
+numbers = "warn"    # a number of a cited sentence not in its source
+summary = "off"     # return a Stop once for the summary of the subagents' results
+promises = "off"    # return a Stop for a promise whose condition holds
+
+# The journal keeps receipts only (counts, verdicts, hashes), no words of the conversation; true keeps promise
+# sentences and choice cards in it.
+[journal]
+text = false
+
+# Intro mode: nothing is returned until this many final answers have passed without a false return; each
+# would-be return is a warning. Report a false return with `buddie intro --false`; end the intro with `buddie enforce`.
+[intro]
+finals = {INIT_FINALS}
+"""
+
+
+def find(repos: list[Path]) -> Path | None:
+    for repo in repos:
+        if (repo / CONFIG).is_file():
+            return repo / CONFIG
+    return None
+
+
+def load(path: Path | None) -> dict:
+    if path is None:
+        return {}
+    try:
+        return tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+
+
+def of_event(event: dict) -> tuple[Path | None, dict]:
+    from buddie.promises import repos_of
+    path = find(repos_of(event))
+    return path, load(path)
+
+
+def levels(cfg: dict) -> dict[str, str]:
+    out = dict(DEFAULTS)
+    for k, v in (cfg.get("gates") or {}).items():
+        if k in out and v in LEVELS:
+            out[k] = v
+    for pair in os.environ.get("BUDDIE_GATES", "").split(","):
+        k, _, v = pair.strip().partition("=")
+        if k in out and v.strip() in LEVELS:
+            out[k] = v.strip()
+    return out
+
+
+def numbers_mode(level: str) -> str:
+    """The verify mode a numbers level needs: a warning is a blocking item demoted by the gate."""
+    return {"block": "fail", "warn": "fail", "off": "off"}[level]
+
+
+def classify(item: str) -> str | None:
+    """The class of one blocking item of the gate (verify's blocking strings, hook.unbacked, hook.prose_claims)."""
+    if item.startswith("quote "):
+        return "quotes"
+    if item.startswith("anchor line "):
+        return "anchors"
+    if item.startswith(("final answer has no anchor", "number without anchor")):
+        return "final"
+    if item.startswith("number "):
+        return "numbers"
+    if item.startswith("work claimed in prose"):
+        return "prose"
+    if " line " in item.split(":", 1)[0]:
+        return "work"
+    return None  # the context gate and anything new: always block
+
+
+def journal_text(cfg: dict) -> bool:
+    """Whether the journal may keep words of the conversation (promise sentences, choice cards); default no."""
+    env = os.environ.get("BUDDIE_JOURNAL_TEXT")
+    if env in ("0", "1"):
+        return env == "1"
+    return (cfg.get("journal") or {}).get("text") is True
+
+
+def _intro_file() -> Path | None:
+    target = os.environ.get("BUDDIE_INTRO", str(Path.home() / ".cache" / "buddie" / "intro.json"))
+    return None if target in ("", "0") else Path(target)
+
+
+def _intro_state() -> dict:
+    f = _intro_file()
+    try:
+        return json.loads(f.read_text(encoding="utf-8")) if f and f.is_file() else {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _save(state: dict) -> None:
+    f = _intro_file()
+    if f is None:
+        return
+    try:
+        f.parent.mkdir(parents=True, exist_ok=True)
+        f.write_text(json.dumps(state, ensure_ascii=False, indent=1) + "\n", encoding="utf-8")
+    except OSError:
+        pass
+
+
+def _key(path: Path) -> str:
+    return str(path.resolve())
+
+
+def intro(path: Path | None, cfg: dict) -> dict | None:
+    """The intro of this buddie.toml while it lasts: {finals, seen}; None once enforced or with no [intro]."""
+    n = (cfg.get("intro") or {}).get("finals")
+    if path is None or not isinstance(n, int) or n <= 0:
+        return None
+    mine = _intro_state().get(_key(path), {})
+    if mine.get("enforced") or mine.get("seen", 0) >= n:
+        return None
+    return {"finals": n, "seen": mine.get("seen", 0)}
+
+
+def count_final(path: Path) -> int:
+    state = _intro_state()
+    mine = state.setdefault(_key(path), {})
+    mine["seen"] = mine.get("seen", 0) + 1
+    _save(state)
+    return mine["seen"]
+
+
+def false_return(path: Path) -> None:
+    state = _intro_state()
+    mine = state.setdefault(_key(path), {})
+    mine["seen"], mine["false"] = 0, mine.get("false", 0) + 1
+    _save(state)
+
+
+def enforce(path: Path) -> None:
+    state = _intro_state()
+    state.setdefault(_key(path), {})["enforced"] = True
+    _save(state)
+
+
+def init(repo: Path) -> Path:
+    path = repo / CONFIG
+    if path.exists():
+        raise FileExistsError(path)
+    path.write_text(TEMPLATE, encoding="utf-8")
+    return path