hubkit-cli 0.1.0__py3-none-any.whl

hubcore/data/hub/scripts/hubcore/learnings.py

@@ -0,0 +1,232 @@
+"""Learnings log: one block per class of mistake. Locked, atomic, redacted."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import re
+from datetime import datetime
+from pathlib import Path
+
+from . import config, store
+from .redact import redact
+
+HEADER_RE = re.compile(r"^## (?P<cls>[a-z0-9][a-z0-9-]*) \| gate: (?P<gate>.+)$")
+SEEN_RE = re.compile(r"^  - (\d{4}-\d{2}-\d{2}) (.*)$")
+BASIS_RE = re.compile(r"^- basis: (\w+)$")
+ADDR_RE = re.compile(r"^- addressed: (\d{4}-\d{2}-\d{2}) (.*)$")
+PREAMBLE = (
+    "# Hub learnings\n\n"
+    "One block per class of mistake. A repeat appends to `seen`.\n"
+    "A class seen 2+ times is promoted into the overlay (`learn.py promote-candidates`, then `learn.py promote`).\n"
+)
+
+
+def default_file(cfg: dict) -> Path:
+    """The learnings file: paths.learnings, else <state dir>/learnings.md."""
+    return config.path_of(cfg, "learnings", store.state(cfg) / "learnings.md")
+
+
+def read_blocks(path: Path) -> tuple[str, list[list[str]]]:
+    """Split the learnings file into its preamble and one block of lines per class."""
+    if not path.exists():
+        return PREAMBLE, []
+    pre: list[str] = []
+    blocks: list[list[str]] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.startswith("## "):
+            blocks.append([line])
+        elif blocks:
+            blocks[-1].append(line)
+        else:
+            pre.append(line)
+    return ("\n".join(pre) + "\n" if pre else PREAMBLE), blocks
+
+
+def write_blocks(path: Path, pre: str, blocks: list[list[str]]) -> None:
+    """Write the preamble and blocks back atomically."""
+    body = "\n\n".join("\n".join(b).rstrip() for b in blocks)
+    store.write_atomic(path, pre.rstrip() + "\n\n" + body + "\n")
+
+
+def block_class(block: list[str]) -> str:
+    """The class name of a block (from its header line)."""
+    m = HEADER_RE.match(block[0])
+    return m["cls"] if m else ""
+
+
+def seen_lines(block: list[str]) -> list[str]:
+    """The dated `seen` lines of a block."""
+    return [ln for ln in block if SEEN_RE.match(ln)]
+
+
+def seen_dates(block: list[str]) -> list[str]:
+    """The dates a block's class was seen."""
+    return [m[1] for ln in seen_lines(block) if (m := SEEN_RE.match(ln))]
+
+
+def addressed(block: list[str]) -> tuple[str, str] | None:
+    """(date, how) when the block is marked addressed, else None."""
+    for ln in block:
+        if m := ADDR_RE.match(ln):
+            return m[1], m[2]
+    return None
+
+
+def field(block: list[str], name: str) -> str:
+    """The text of a `- name: ...` line in a block, or an empty string."""
+    for ln in block:
+        if ln.startswith(f"- {name}: "):
+            return ln[len(name) + 4 :]
+    return ""
+
+
+def clean(text: str) -> str:
+    """Collapse whitespace and redact secrets from user-supplied text."""
+    return redact(" ".join(text.split()))[0]
+
+
+def locked_edit(path: Path) -> contextlib.AbstractContextManager[bool]:
+    """Exclusive lock around an edit of `path`."""
+    return store.locked(path.with_name(f".{path.name}.lock"))
+
+
+def overlay_path(cfg: dict) -> Path:
+    """The overlay file (personal rules): paths.overlay, else <config dir>/overlay.md."""
+    return config.path_of(cfg, "overlay", Path(cfg["_config_dir"]) / "overlay.md")
+
+
+def rules_hash(cfg: dict) -> str:
+    """Hash of the rule texts a learning can be promoted into (overlay + SKILL.md)."""
+    h = hashlib.sha1()
+    for f in (overlay_path(cfg), config.SKILL_DIR / "SKILL.md"):
+        h.update(f.read_bytes() if f.exists() else b"")
+    return h.hexdigest()[:12]
+
+
+def _set_basis(block: list[str], basis: str) -> None:
+    if not basis:
+        return
+    block[:] = [ln for ln in block if not BASIS_RE.match(ln)]
+    block.insert(next(i for i, ln in enumerate(block) if ln == "- seen:"), f"- basis: {basis}")
+
+
+def add(path: Path, cls: str, quote: str, day: str, gate: str = "?", basis: str = "", **fields: str) -> str:
+    """Record a correction: new block for a new class, a dated `seen` line for a repeat."""
+    if not re.fullmatch(r"[a-z0-9][a-z0-9-]*", cls):
+        raise ValueError("--class must be kebab-case (a-z, 0-9, -)")
+    q = clean(quote).replace('"', "'")
+    seen = f'  - {day} "{q}"'
+    with locked_edit(path):
+        pre, blocks = read_blocks(path)
+        for block in blocks:
+            if block_class(block) != cls:
+                continue
+            if seen in block:
+                return f"skip: duplicate of {cls}"
+            idx = max(i for i, ln in enumerate(block) if SEEN_RE.match(ln))
+            block.insert(idx + 1, seen)
+            _set_basis(block, basis)
+            write_blocks(path, pre, blocks)
+            return f"repeat: {cls} now seen {len(seen_lines(block))}x"
+        for name in ("situation", "wrong", "right", "evidence"):
+            if not fields.get(name):
+                raise ValueError(f"new class needs --{name}")
+        blocks.append(
+            [f"## {cls} | gate: {clean(gate)}"]
+            + [f"- {n}: {clean(fields[n])}" for n in ("situation", "wrong", "right", "evidence")]
+            + ["- seen:", seen]
+        )
+        _set_basis(blocks[-1], basis)
+        write_blocks(path, pre, blocks)
+    return f"added: {cls}"
+
+
+def mark_addressed(path: Path, cls: str, day: str, how: str, current: str, rules_mtime: float, rule_text: str = "") -> str:
+    """Mark a class fixed. Refused unless the overlay or SKILL.md changed since the entry was seen."""
+    with locked_edit(path):
+        pre, blocks = read_blocks(path)
+        for block in blocks:
+            if block_class(block) != cls:
+                continue
+            basis = next((m[1] for ln in block if (m := BASIS_RE.match(ln))), "")
+            if basis:
+                changed = current != basis
+            else:  # old entry without a basis: file must be newer than the last sighting's day
+                last = last_seen(block)
+                changed = bool(last) and rules_mtime >= datetime.strptime(last, "%Y-%m-%d").timestamp()
+            if f"[{cls}]" not in rule_text:
+                raise ValueError(f"refused: no rule line tagged [{cls}] in the overlay or SKILL.md; run learn.py promote first")
+            if not changed:
+                raise ValueError(f"refused: overlay and SKILL.md unchanged since {cls} was seen; promote the rule first")
+            block[:] = [ln for ln in block if not ADDR_RE.match(ln)]
+            block.insert(next(i for i, ln in enumerate(block) if ln == "- seen:"), f"- addressed: {day} {clean(how)}")
+            write_blocks(path, pre, blocks)
+            return f"addressed: {cls}"
+    raise KeyError(f"no class {cls}")
+
+
+PROMOTED = "## Promoted rules (learn.py promote)"
+
+
+def promote(path: Path, overlay: Path, cls: str, gate: str, rule: str) -> str:
+    """Write one short rule line into the overlay under its gate heading. User data stays out of SKILL.md."""
+    _, blocks = read_blocks(path)
+    if not any(block_class(b) == cls for b in blocks):
+        raise KeyError(f"no class {cls}")
+    if not re.fullmatch(r"G[1-9]", gate):
+        raise ValueError("--gate must look like G1..G9")
+    line = f"- {clean(rule)} [{cls}]"
+    with locked_edit(overlay):
+        lines = overlay.read_text(encoding="utf-8").splitlines() if overlay.exists() else []
+        if line in lines:
+            return f"skip: {cls} already promoted"
+        if PROMOTED not in lines:
+            lines += ["", PROMOTED, ""]
+        head = f"### {gate}"
+        start = lines.index(PROMOTED)
+        end = next((i for i in range(start + 1, len(lines)) if lines[i].startswith("## ")), len(lines))
+        if head not in lines[start:end]:
+            lines[end:end] = [head, ""]
+            end += 2
+        at = lines.index(head, start)
+        stop = next((i for i in range(at + 1, len(lines)) if lines[i].startswith("#")), len(lines))
+        while stop > at + 1 and not lines[stop - 1].strip():
+            stop -= 1
+        lines.insert(stop, line)
+        store.write_atomic(overlay, "\n".join(lines) + "\n")
+    return f"promoted: {cls} -> {gate}"
+
+
+def last_seen(block: list[str]) -> str:
+    """Latest date a block was seen, or an empty string."""
+    return max(seen_dates(block), default="")
+
+
+def recent(path: Path, n: int) -> list[list[str]]:
+    """The `n` most recently seen blocks."""
+    _, blocks = read_blocks(path)
+    return sorted(blocks, key=last_seen)[-n:]
+
+
+def review(path: Path, day: str) -> dict[str, list[str]]:
+    """Compare learnings with the day: new today, repeated today, and addressed status."""
+    _, blocks = read_blocks(path)
+    out: dict[str, list[str]] = {
+        "new": [], "repeated": [], "regressed": [], "holding": [], "unaddressed": []
+    }
+    for b in blocks:
+        cls, dates = block_class(b), seen_dates(b)
+        if dates and min(dates) == day:
+            out["new"].append(cls)
+        elif day in dates:
+            out["repeated"].append(cls)
+        addr = addressed(b)
+        if addr:
+            after = [d for d in dates if d > addr[0]]
+            (out["regressed"] if after else out["holding"]).append(
+                f"{cls} (addressed {addr[0]}" + (f", seen again {max(after)})" if after else ")")
+            )
+        elif len(dates) >= 2:
+            out["unaddressed"].append(f"{cls} ({len(dates)}x)")
+    return out

hubcore/data/hub/scripts/hubcore/lessons.py

@@ -0,0 +1,168 @@
+"""Checks that come from repeated corrections: re-reading the user's asks, unchecked claims, briefs that forbid the
+fix, and an unasked merge. Every check is a warning or a Stop reason; none denies a tool call."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from pathlib import Path
+
+from . import store
+from .orders import Orders
+
+# ---- asks: the user's recent words, one line each ----
+
+DONE_WORDS = re.compile(r"(?i)\b(done|finished|complete[d]?|all set|shipped)\b")
+SPAN = re.compile(r"^(\d+)\s*([mhd])$")
+
+
+def parse_span(text: str) -> float:
+    """`30m`, `12h` or `2d` as seconds; raises ValueError otherwise."""
+    m = SPAN.match(text.strip().lower())
+    if not m:
+        raise ValueError(f"--since takes a number and m, h or d (for example 12h), not {text!r}")
+    return int(m[1]) * {"m": 60, "h": 3600, "d": 86400}[m[2]]
+
+
+def recent_prompts(cfg: dict, since_s: float, now: float | None = None) -> list[dict]:
+    """The human prompts held in recent-prompts.jsonl within the span, oldest first."""
+    now = now or time.time()
+    rows = store.read_rows(store.state(cfg) / "recent-prompts.jsonl")[0]
+    return [r for r in rows if now - r["ts"] <= since_s]
+
+
+def asks_lines(cfg: dict, span: str) -> list[str]:
+    """`HH:MM  words` per prompt, newest last. Reading them marks the asks as swept for the Stop gate."""
+    rows = recent_prompts(cfg, parse_span(span))
+    store.write_atomic(store.state(cfg) / "asks-swept", str(time.time()))
+    return [f"{store.clock(cfg, r['ts'])}  {r['text']}" for r in rows] or ["(no prompts in that span)"]
+
+
+def _last_work_done(cfg: dict, now: float) -> float:
+    last = 0.0
+    for back in (0, 1):
+        day = store.day_of(cfg, now - back * 86400)
+        for r in store.read_rows(store.state(cfg) / "archive" / f"archive_{day}.jsonl")[0]:
+            if r.get("type") == "work" and r.get("outcome") == "done":
+                last = max(last, float(r["ts"]))
+    return last
+
+
+def unswept_asks(cfg: dict, last: str, now: float | None = None) -> str | None:
+    """A reason when the message says done while the user's newest prompt is newer than the last `work done` and
+    the last `hubkit asks ls`: the requirements were not re-read."""
+    now = now or time.time()
+    if not DONE_WORDS.search(last):
+        return None
+    prompts = recent_prompts(cfg, 86400, now)
+    if not prompts:
+        return None
+    try:
+        swept = float((store.state(cfg) / "asks-swept").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        swept = 0.0
+    if prompts[-1]["ts"] <= max(swept, _last_work_done(cfg, now)):
+        return None
+    return ("hubkit: you say it is done but have not re-read his words since his last prompt. NEXT: hubkit asks ls --since 12h; "
+            "list every requirement in them and tick each with evidence before saying done")
+
+
+# ---- claims that need a lookup in the same turn ----
+
+UNCHECKED_WORDS = ["gone", "lost", "absent", "vanished", "disappeared", "does not exist", "doesn't exist", "never written", "was never there",
+                   "a person's call", "needs your call", "needs his call", "needs her call", "needs a human decision"]
+LOOKUP_TOOLS = ("Read", "Grep", "Glob", "Bash")
+
+
+def lookups_this_turn(transcript: str | Path | None) -> int | None:
+    """Count of Read/Grep/Glob/Bash calls after the last typed prompt in the transcript, or None when unreadable."""
+    if not transcript:
+        return None
+    try:
+        lines = Path(transcript).read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return None
+    n = 0
+    for line in reversed(lines):
+        try:
+            o = json.loads(line)
+        except ValueError:
+            continue
+        c = (o.get("message") or {}).get("content")
+        blocks = [b for b in c if isinstance(b, dict)] if isinstance(c, list) else []
+        if o.get("type") == "user" and (isinstance(c, str) or any(b.get("type") == "text" for b in blocks)) \
+                and (o.get("origin") or {}).get("kind", "human") == "human":
+            break
+        if o.get("type") == "assistant":
+            n += sum(1 for b in blocks if b.get("type") == "tool_use" and b.get("name") in LOOKUP_TOOLS)
+    return n
+
+
+def unchecked_claim(cfg: dict, last: str, transcript: str | Path | None) -> str | None:
+    """A reason when the message calls something gone/lost/absent, or a person's call, and this turn made no lookup."""
+    from .gate import _asserted
+
+    words = Orders(cfg).intents.get("stop_gate", {}).get("unchecked_words", UNCHECKED_WORDS)
+    hit = next((s.strip()[:100] for s in re.split(r"(?<=[.!?])\s+|\n", last) if any(_asserted(s.lower(), w.lower()) for w in words)), None)
+    if not hit or lookups_this_turn(transcript) != 0:
+        return None
+    return (f"hubkit: your message claims {hit!r} but this turn read nothing. A report that something is gone, or is a person's call, "
+            "is checked, not relayed. NEXT: read the code or record that writes it (or what he already decided), then say it")
+
+
+# ---- a brief must not forbid the step that clears a blocker ----
+
+FORBID = re.compile(r"(?i)\b(do not|don't|dont|never|must not|mustn't|not allowed|forbidden|banned)\b")
+STOP_WORDS = {"with", "that", "this", "from", "have", "been", "when", "then", "than", "into", "does", "host", "need", "needs", "start",
+              "running", "after", "before", "about", "their", "there", "which", "would", "could", "should"}
+
+
+def _keys(text: str) -> set[str]:
+    return {w for w in re.findall(r"[a-z][a-z0-9_-]{3,}", text.lower()) if w not in STOP_WORDS}
+
+
+def brief_forbids_fix(cfg: dict, brief: str) -> str | None:
+    """The line of a brief that forbids a step an open order is blocked on (shares a key word with its blocker or fix)."""
+    blockers = [(o["id"], b) for o in Orders(cfg).live() if o["state"] == "open" and (b := o.get("blocker"))]
+    for line in brief.splitlines():
+        if not FORBID.search(line):
+            continue
+        for oid, b in blockers:
+            shared = _keys(line) & _keys(b["on"] + " " + b["fix"])
+            if shared:
+                return (f"hubkit WARNING: this brief says {line.strip()[:100]!r}, which touches what {oid} is blocked on ({b['on'][:60]}; "
+                        f"shared: {', '.join(sorted(shared)[:3])}). A brief must not forbid the one action that clears the blocker. "
+                        "NEXT: reword it, or allow that step explicitly")
+    return None
+
+
+# ---- merge guard (warn only) ----
+
+MERGE_CMD = re.compile(r"\bgh\s+pr\s+merge\b([^\n;&|]*)")
+
+
+def merge_target(command: str) -> str | None:
+    """The PR number a `gh pr merge` command names ("" when it names none), or None when it is not a merge."""
+    m = MERGE_CMD.search(command)
+    if not m:
+        return None
+    n = re.search(r"(?:/pull/|\s)(\d{1,7})\b", " " + m[1])
+    return n[1] if n else ""
+
+
+def merge_warning(cfg: dict, command: str, now: float | None = None) -> str | None:
+    """A warning when a merge has neither a live order nor a typed word of his naming that PR. Never denies."""
+    num = merge_target(command)
+    if num is None:
+        return None
+    now = now or time.time()
+    for o in Orders(cfg).live():
+        if o["state"] == "open" and (re.search(rf"(?<!\d){num}(?!\d)", " ".join([o["quote"], *o["refs"]])) if num else o["kind"] == "merge"):
+            return None
+    for r in recent_prompts(cfg, 7200, now):
+        if re.search(r"(?i)\bmerge", r["text"]) and (not num or re.search(rf"(?<!\d){num}(?!\d)", r["text"])):
+            return None
+    what = f"#{num}" if num else "a PR"
+    return (f"hubkit WARNING: merging {what} with no live order and none of his typed words naming it. A merge is done on his order only. "
+            "NEXT: stop unless he ordered it; if he did, open the order: hubkit order open --kind merge --quote \"<his words>\"")