hubkit-cli 0.1.0__py3-none-any.whl

hubcore/store.py

@@ -0,0 +1,172 @@
+"""Append-only JSONL, flock, atomic replace, human-prompt test, time helpers."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import time
+import unicodedata
+from collections.abc import Iterator
+from datetime import datetime
+from datetime import tzinfo as TzInfo
+from pathlib import Path
+
+from . import compat, config
+from .redact import redact_obj
+
+# Harness and peer wrappers. The test is a denylist on the whole normalised text, plus: any text
+# that starts with a tag is not a typed prompt, and a payload origin other than "human" is rejected.
+HARNESS_PREFIXES = ("caveat", "this session is being continued", "/compact", "[artifact", "[system", "[cross-session")
+HARNESS_MARKERS = (
+    "cross-session-message",
+    "another-claude-session-sent-a-message",
+    "system-notification",
+    "task-notification",
+    "system-reminder",
+    "teammate-message",
+    "local-command-stdout",
+    "command-name",
+    "bash-input",
+    "bash-stdout",
+    "artifact-content-authored-by",
+)
+
+
+class StateError(RuntimeError):
+    pass
+
+
+def _normalise(text: str) -> str:
+    """NFKC, all dash look-alikes to '-', zero-width and format characters removed, lower case."""
+    out = []
+    for ch in unicodedata.normalize("NFKC", text):
+        cat = unicodedata.category(ch)
+        if cat == "Cf":
+            continue
+        out.append("-" if cat == "Pd" else ch)
+    return "".join(out).lower()
+
+
+def is_human(text: str, origin: str | None = None) -> bool:
+    """True only for a typed prompt. origin, when the payload has it, must be 'human'."""
+    if origin is not None and origin != "human":
+        return False
+    t = re.sub(r"</?pasted_content[^>]*>", " ", _normalise(text)).lstrip()  # a typed paste is human
+    if not t or t.startswith(HARNESS_PREFIXES) or re.match(r"<[a-z/!?]", t):
+        return False
+    squashed = re.sub(r"[\s_]+", "-", t)
+    return not any(m in squashed for m in HARNESS_MARKERS)
+
+
+def _inside_git(path: Path) -> bool:
+    p = path.resolve()
+    return any((q / ".git").exists() for q in [p, *p.parents])
+
+
+def state(cfg: dict, create: bool = True) -> Path:
+    """The state directory (created on demand); refuses one inside a git repository or the skill dir."""
+    d = config.state_dir(cfg)
+    if d.resolve().is_relative_to(config.SKILL_DIR):
+        raise StateError(f"state dir {d} is inside the skill dir")
+    if _inside_git(d):
+        raise StateError(f"state dir {d} is inside a git repository")
+    if create:
+        for sub in ("", "seen", "archive", "eod", "payload-samples"):
+            (d / sub).mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def tzinfo(cfg: dict) -> TzInfo | None:
+    """The configured timezone, else the system one."""
+    name = cfg["user"].get("timezone", "")
+    if name:
+        from zoneinfo import ZoneInfo
+
+        return ZoneInfo(name)
+    return datetime.now().astimezone().tzinfo
+
+
+def day_of(cfg: dict, epoch: float) -> str:
+    """YYYY-MM-DD of an epoch in the configured timezone."""
+    return datetime.fromtimestamp(epoch, tzinfo(cfg)).strftime("%Y-%m-%d")
+
+
+def clock(cfg: dict, epoch: float) -> str:
+    """HH:MM of an epoch in the configured timezone."""
+    return datetime.fromtimestamp(epoch, tzinfo(cfg)).strftime("%H:%M")
+
+
+def append_row(path: Path, row: dict) -> None:
+    """Redact, then one os.write on an O_APPEND fd. No lock needed for a pure append."""
+    row = redact_obj(row)
+    row.setdefault("ts", time.time())
+    data = (json.dumps(row, ensure_ascii=False, separators=(",", ":")) + "\n").encode()
+    fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+    try:
+        os.write(fd, data)
+    finally:
+        os.close(fd)
+
+
+def read_rows(path: Path) -> tuple[list[dict], int]:
+    """Return (rows, bad_lines). A torn or corrupt line is skipped and counted."""
+    rows: list[dict] = []
+    bad = 0
+    if not path.exists():
+        return rows, bad
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        if not line.strip():
+            continue
+        try:
+            obj = json.loads(line)
+        except ValueError:
+            bad += 1
+            continue
+        if isinstance(obj, dict):
+            rows.append(obj)
+        else:
+            bad += 1
+    return rows, bad
+
+
+@contextlib.contextmanager
+def locked(path: Path, blocking: bool = True, retries: int = 3) -> Iterator[bool]:
+    """flock on a lock file. Yields True when held. Non-blocking mode retries then yields False."""
+    fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o600)
+    got = False
+    try:
+        for _ in range(retries if not blocking else 1):
+            got = compat.lock_exclusive(fd, wait=blocking)
+            if got:
+                break
+            time.sleep(0.05)
+        yield got
+    finally:
+        os.close(fd)
+
+
+def write_atomic(path: Path, text: str) -> None:
+    """Write text via a temp file and rename."""
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def write_json_atomic(path: Path, obj: object, indent: int | None = 1) -> None:
+    """Redact every string, then write atomically (status.json, work.json)."""
+    write_atomic(path, json.dumps(redact_obj(obj, 2000), indent=indent, ensure_ascii=False) + "\n")
+
+
+def safe(text: str, n: int = 300) -> str:
+    """Redact first, then truncate, so a cut secret cannot leak a prefix."""
+    from .redact import redact
+
+    return redact(text)[0][:n]
+
+
+def touch_seen(sd: Path, name: str) -> None:
+    """Touch a heartbeat file under seen/."""
+    (sd / "seen").mkdir(exist_ok=True)
+    (sd / "seen" / name).touch()

hubcore/watcher.py

@@ -0,0 +1,167 @@
+"""Checks that run in every tick (cron or watch), outside the hub session: the hub itself, peers stuck on a prompt,
+the watch and cron checking each other, and the user notification."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+
+from . import hooks, routed, slow, store
+from .orders import Orders
+
+USER_KEYS = ("hub:", "peer:")  # alerts that go to the user's desktop when no notify_cmd is configured
+WAITING_STATES = ("waiting", "blocked", "needs_input", "permission")
+HUB_SEEN = ("prompt", "stop", "routed", "answer", "session")
+
+
+def live_jobs(cfg: dict, orders: Orders) -> int:
+    """Routed items plus open orders: the work that needs a hub."""
+    return len(routed.items(cfg)) + sum(o["state"] == "open" for o in orders.live())
+
+
+def _last_hub_activity(sd: store.Path) -> float:
+    """Latest heartbeat the hub's own hooks touched."""
+    return max([(sd / "seen" / n).stat().st_mtime for n in HUB_SEEN if (sd / "seen" / n).exists()] or [0.0])
+
+
+def hub_checks(cfg: dict, orders: Orders, now: float) -> list[dict]:
+    """The hub is gone, stuck on one status, or has not acted on an alert, while jobs are live."""
+    n = live_jobs(cfg, orders)
+    if not n:
+        return []
+    w = cfg["watcher"]
+    b = hooks.read_bind(cfg)
+    if not hooks.bind_alive(b):
+        return [{"key": "hub:dead", "msg": f"hub session is not running and {n} job{'s' if n > 1 else ''} are live. "
+                 "NEXT: start the hub session and run hubkit bind"}]
+    out: list[dict] = []
+    sess = hooks.session_file(cfg, int(b["pid"])) or {}
+    since = float(sess.get("statusUpdatedAt", 0)) / 1000
+    if sess.get("status") == "busy" and since and now - since > float(w["stuck_min"]) * 60:
+        out.append({"key": "hub:stuck", "msg": f"hub session has been busy for {int((now - since) / 60)} min with {n} live jobs; "
+                    "check it is not stuck on a prompt"})
+    act = _last_hub_activity(store.state(cfg))
+    old = [r for r in store.read_rows(store.state(cfg) / "alerts.jsonl")[0]
+           if r["ts"] > act and now - r["ts"] > float(w["unhandled_min"]) * 60 and not str(r.get("key", "")).startswith("hub:")]
+    if old:
+        first = min(old, key=lambda r: r["ts"])
+        out.append({"key": "hub:unhandled", "msg": f"alert unhandled for {int((now - first['ts']) / 60)} min and the hub has not acted since "
+                    f"({str(first.get('msg', ''))[:70]})"})
+    return out
+
+
+def peer_checks(cfg: dict, now: float) -> list[dict]:
+    """A peer holding a live item sits on a permission prompt or waits for input (session status / waitingFor)."""
+    out = []
+    for owner in dict.fromkeys(i["owner"] for i in routed.items(cfg)):
+        sess = slow.holder_session(cfg, owner)
+        if not sess or not (sess.get("waitingFor") or str(sess.get("status")) in WAITING_STATES):
+            continue
+        mins = int((now - float(sess.get("statusUpdatedAt", 0)) / 1000) / 60)
+        if mins >= int(cfg["watcher"]["waiting_min"]):
+            ids = ",".join(i["id"] for i in routed.items(cfg) if i["owner"] == owner)
+            what = store.safe(str(sess.get("waitingFor") or sess.get("status")), 40)
+            out.append({"key": f"peer:{owner}:waiting", "msg": f"{owner} has waited {mins} min on {what} (holds {ids}). "
+                        f"NEXT: ask the user to answer it in that session, or re-brief"})
+    return out
+
+
+def liveness_checks(cfg: dict, orders: Orders) -> list[dict]:
+    """Watch and cron check each other: work is live and no watch runs, or cron is configured but has gone stale."""
+    from . import cli, gate
+
+    out = []
+    started = [routed.started_at(cfg, i) for i in routed.items(cfg)] + [o["opened"] for o in orders.live() if o["state"] == "open"]
+    grace = float(cfg["watcher"]["watch_grace_min"]) * 60  # the stop gate makes the hub arm a watch; give it a moment
+    if started and time.time() - min(started) > grace and not gate.watch_live(cfg):
+        out.append({"key": "watch:dead", "msg": f"hubkit watch is not running and work is live. NEXT: start in the background: {gate.WATCH_CMD}"})
+    f = store.state(cfg) / "seen" / "cron"
+    limit = float(cfg["watchdog"]["cron_stale_min"])
+    quiet_min = (time.time() - f.stat().st_mtime) / 60 if f.exists() else (time.time() - min(started)) / 60 if started else 0.0
+    if quiet_min > limit and cli.cron_configured():  # never written counts from the oldest live job
+        out.append({"key": "cron:dead", "msg": f"cron has not run hubkit for over {int(limit)} min. NEXT: check the crontab line and cron's mail"})
+    return out
+
+
+def checks(cfg: dict, orders: Orders, now: float) -> list[dict]:
+    """Every watcher alert that holds now."""
+    return [*hub_checks(cfg, orders, now), *peer_checks(cfg, now), *liveness_checks(cfg, orders), *stale_agent_checks(cfg, now)]
+
+
+def stale_agent_checks(cfg: dict, now: float) -> list[dict]:
+    """A background agent reported finished long ago and its item is still listed (a review item waits on its PR)."""
+    limit = float(cfg["watcher"]["stale_agent_min"])
+    return [
+        {"key": f"agent:{i['owner']}:stale", "msg": f"agent {i['owner']} finished {int((now - i['reported']) / 60)} min ago and {i['id']} is still listed. "
+         "NEXT: close the item (hubkit work done) or act on the PR it waits for"}
+        for i in routed.items(cfg)
+        if i.get("tool_use_id") and i.get("reported") and (now - float(i["reported"])) / 60 > limit
+    ]
+
+
+def desktop_argv(msg: str, platform: str = sys.platform) -> list[str] | None:
+    """The default desktop notification command for this platform, or None when no tool is installed."""
+    if platform.startswith("linux") and shutil.which("notify-send"):
+        return ["notify-send", "-u", "critical", "-a", "hubkit", "hubkit", msg]
+    if platform == "darwin" and shutil.which("osascript"):
+        safe = msg.replace("\\", " ").replace('"', "'")
+        return ["osascript", "-e", f'display notification "{safe}" with title "hubkit"']
+    return None
+
+
+def notify(cfg: dict, new: list[dict]) -> None:
+    """Tell the user's desktop about new alerts. `tools.notify_cmd` (every alert) wins; with none set, the platform's
+    default is used for the alerts that are about the hub or a stuck peer. Never posts to chat."""
+    cmd = cfg["tools"]["notify_cmd"]
+    if cmd:
+        argv: list[str] | None = [*shlex.split(cmd), "hubkit: " + "; ".join(a["msg"] for a in new)]
+    else:
+        mine = [a["msg"] for a in new if str(a["key"]).startswith(USER_KEYS)]
+        argv = desktop_argv("; ".join(mine)) if mine else None
+    if not argv or (not cmd and not cfg["watcher"]["notify_user"]):
+        return
+    try:
+        subprocess.run(argv, timeout=5, check=False)
+    except OSError, subprocess.SubprocessError:
+        pass
+
+
+def excused(cfg: dict, item: dict, now: float) -> str | None:
+    """Why a silent item is not a stall: it is blocked on another live job, or its holder is visibly working
+    (session busy and its transcript growing). An active holder is excused for 3x the limit only."""
+    live = {i["id"] for i in routed.items(cfg)}
+    if item.get("blocked_on") in live:
+        return f"blocked on {item['blocked_on']}"
+    if (now - routed.base(cfg, item)) / 60 > 3 * routed.limit(cfg, item):
+        return None
+    owner = item["owner"]
+    sess = slow.holder_session(cfg, owner)
+    path = slow.holder_transcript(cfg, owner, sess)
+    if sess and str(sess.get("status")) == "busy" and path:
+        try:
+            if now - os.path.getmtime(path) < float(cfg["watcher"]["active_s"]):
+                return "holder is working"
+        except OSError:
+            return None
+    return None
+
+
+def set_blocked(cfg: dict, wid: str, on: str) -> str:
+    """Link a routed item to the job it waits on (empty `on` clears it)."""
+    sd = store.state(cfg)
+    with store.locked(sd / "work.lock"):
+        items = routed.work_load(sd)
+        hit = next((i for i in items if i["id"] == wid and i.get("kind") == "routed"), None)
+        if hit is None:
+            raise KeyError(f"no live routed item {wid}")
+        if on and on == wid:
+            raise ValueError("an item cannot block on itself")
+        if on and not any(i["id"] == on for i in items):
+            raise KeyError(f"no live item {on}")
+        hit["blocked_on"] = on
+        routed.work_save(sd, items)
+    return f"{wid} blocked on {on}" if on else f"{wid} no longer blocked"

hubkit_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: hubkit-cli
+Version: 0.1.0
+Summary: Session supervisor for Claude Code: hooks-based multi-agent orchestration with order clocks, routed-work tracking, a watchdog and a stop gate, standard library only.
+Project-URL: Repository, https://github.com/ankitkpandey1/hubkit
+Project-URL: Documentation, https://github.com/ankitkpandey1/hubkit/tree/main/docs
+Project-URL: Issues, https://github.com/ankitkpandey1/hubkit/issues
+Author: Ankit Kumar Pandey
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: adaptive,agent-coordination,agents,claude-code,hooks,multi-agent,orchestration,supervisor,watchdog
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# hubkit
+
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue.svg)
+![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen.svg)
+
+**hubkit is a session supervisor for Claude Code: a hooks-based kit for multi-agent orchestration that keeps the one session coordinating your other sessions and agents honest. It gives each order a clock, tracks work routed to peers, blocks a premature "done", and learns from your corrections.**
+
+hubkit adapts to you. When you correct the hub ("I told you to wait for the review"), a hook notices, the hub records the correction as a class of mistake, and a class that repeats is promoted to a written rule in your own overlay file. A rule only counts as fixed after a check that the rule really exists, and it stays on probation until it has held. The words that open an urgent order, the clocks, what "done" means and every other setting live in your config files, not in the code, so the kit bends to how you work. This is a log-and-verify loop around the hub model, not machine learning: hubkit detects, stores and checks; the hub session writes the entries and rules.
+
+## Why use a Claude Code session supervisor
+
+A coordinating Claude Code session routes work to peers and background agents, then forgets. After a context compaction it no longer knows which order was urgent, who was asked to review what, or whether "done" was ever proven. hubkit keeps that record outside the model's memory, gives every order a clock and an evidence check, watches routed work for silence, and blocks the hub from ending a turn while it owes something. Example session:
+
+```console
+$ hubkit order open --kind hotfix --quote "hotfix the billing bug now"
+O-261105-bd22 hotfix [open] open 0m, idle 0m, chases 0; done needs: pr_merged,prod_live
+$ hubkit order move O-261105-bd22 --note "PR merged"
+$ hubkit order close O-261105-bd22 --evidence pr_merged=https://github.com/acme/repo/pull/12
+error: close refused: missing evidence 'prod_live'
+$ hubkit order close O-261105-bd22 --evidence pr_merged=https://github.com/acme/repo/pull/12 \
+      --evidence prod_live=https://example.com/deploy-log
+O-261105-bd22 closed
+```
+
+In a live hub, the prompt hook opens that order itself from your sentence, and the hub only reports "done" after the close succeeds.
+
+## What hubkit does for multi-agent coordination
+
+- **Learns from corrections.** A prompt hook flags correction phrases and repeated instructions. `scripts/learn.py` records, promotes and verifies them. See [docs/architecture.md](docs/architecture.md#the-learn-loop).
+- **Order clock.** Orders open from your own prompts (never from peer or harness text), each with a first-action limit, a stall limit and a definition of done checked by evidence on close.
+- **Routed-work tracking.** A hook on `SendMessage` and `Agent` records what the hub asked of whom, one item per (owner, PR). It follows last heard-from, moved heads and GitHub reviews at the PR head.
+- **Watchdog and wake-up.** `hubkit tick` (cron) and `hubkit watch` (a background process) raise alerts with back-off; a watch exit wakes an idle hub.
+- **Stop gate.** The Stop hook refuses to let the turn end while the hub owes something (no watch running, a stalled item, an unbacked verdict, a question to you that blocks nothing).
+- **Status, end-of-day review.** A status block at session start and on each prompt, a daily archive, and `hubkit eod`.
+
+`SKILL.md` is the behaviour contract the hub session reads. This file is the operator view.
+
+## Requirements
+
+- Linux. hubkit has only been run on Linux; macOS and Windows code exists but has never been run (see [Platform support](#platform-support)).
+- Python 3.14 or newer (the code uses `except A, B:` without parentheses, PEP 758). Standard library only.
+- [Claude Code](https://code.claude.com), which provides the hooks and the skills directory.
+- Optional: `gh` (GitHub CLI) on `PATH` for PR checks; without it items show "PR unknown". Optional: [`mep`](https://pypi.org/project/miseenplace-cli/) for a personal task list in the status block; without it the block shows `mep: UNVERIFIED (mep CLI not found ...)`, and `[mep] enabled = false` silences that.
+
+## Paste this into your agent
+
+```text
+Install hubkit with `uv tool install hubkit-cli`, run `hubkit skills --install DIR` with the skills directory
+for your tool, then run the hubkit-setup skill and follow it. Ask me only for things you cannot find out yourself.
+```
+
+hubkit runs on Claude Code hooks, so the skills directory is Claude Code's: `~/.claude/skills` (user level) or `.claude/skills` (project level). The PyPI name `hubkit-cli` is free as of 2026-11-06 and is not published yet; until it is, install straight from GitHub with `uv tool install git+https://github.com/ankitkpandey1/hubkit` (or from a clone with `uv tool install ./hubkit`).
+
+`hubkit skills --install DIR` copies three skills into `DIR`: `hub` (the rules and the scripts the hooks run), `hub-mep` (optional) and `hubkit-setup` (finds your facts, writes the config, registers the hooks, binds, proves it with `hubkit doctor`). Run it again after an upgrade to refresh the copies. `hubkit hooks --skills-dir DIR` prints the hooks block for `~/.claude/settings.json`.
+
+### Install by hand
+
+```bash
+git clone https://github.com/ankitkpandey1/hubkit ~/.claude/skills/hub
+python3 --version                             # 3.14 or newer
+python3 ~/.claude/skills/hub/scripts/hubkit doctor
+```
+
+The directory name must be `hub`: Claude Code finds the skill there, and the hooks and the stop gate use that path. `doctor` prints the config and state paths, the bind and the hook heartbeats; on a fresh install it shows `config: ... (defaults)` and `bind: none or dead`, which is correct.
+
+## Claude Code hook setup
+
+Add the hooks to `~/.claude/settings.json` (merge with any existing `hooks` block). Each command is a shim that prints a visible line if the script is missing, then runs one hook event:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{"hooks": [{"type": "command", "command": "[ -f $HOME/.claude/skills/hub/scripts/hubkit ] || echo 'hubkit: script missing'; python3 $HOME/.claude/skills/hub/scripts/hubkit hook session"}]}],
+    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "python3 $HOME/.claude/skills/hub/scripts/hubkit hook prompt"}]}],
+    "PostToolUse": [
+      {"matcher": "AskUserQuestion", "hooks": [{"type": "command", "command": "python3 $HOME/.claude/skills/hub/scripts/hubkit hook answer"}]},
+      {"matcher": "SendMessage|Agent", "hooks": [{"type": "command", "timeout": 6, "command": "python3 $HOME/.claude/skills/hub/scripts/hubkit hook routed"}]}
+    ],
+    "Stop": [{"hooks": [{"type": "command", "command": "python3 $HOME/.claude/skills/hub/scripts/hubkit hook stop"}]}]
+  }
+}
+```
+
+Hooks do nothing, print nothing and exit 0 in every session that is not the bound hub. Then, in the session that is to be the hub (interactive sessions only):
+
+```bash
+python3 ~/.claude/skills/hub/scripts/hubkit bind      # --pid N to name the process
+python3 ~/.claude/skills/hub/scripts/hubkit doctor    # now shows "bind: live <name>"
+```
+
+`hubkit unbind` frees it. For the `hubkit` command used below, add an alias such as `alias hubkit='python3 ~/.claude/skills/hub/scripts/hubkit'`.
+
+## Quick start
+
+```bash
+hubkit order open --kind hotfix --quote "hotfix the billing bug now"   # or let the prompt hook do it
+hubkit order ls
+hubkit work add --kind active --title "triage the flaky test"
+hubkit status                                                          # the status block
+python3 ~/.claude/skills/hub/scripts/learn.py add --class ask-before-merge --gate G5 \
+    --quote "I told you to wait for the review" --situation "..." --wrong "..." --right "..." --evidence "..."
+```
+
+Optional cron line for the watchdog (a no-op unless a hub is bound or an order is open). hubkit needs Python 3.14; cron's `PATH` can put an older `python3` first (for example `/usr/local/bin`), which fails on the first import and, with output sent to `/dev/null`, leaves no trace except a stale `seen/cron`. Name the interpreter:
+
+```
+*/5 * * * * /usr/bin/python3 $HOME/.claude/skills/hub/scripts/hubkit tick --if-bound
+```
+
+## Configuration files
+
+Everything personal lives outside the checkout, in `~/.config/hubkit/`:
+
+| File | Purpose |
+|---|---|
+| `config.toml` | Settings. Template: [`config.example.toml`](config.example.toml). Override the path with `$HUBKIT_CONFIG`. No file means generic defaults. |
+| `intents.toml` | Words that open an order, clocks, what "done" needs. Template: [`intents.example.toml`](intents.example.toml). |
+| `overlay.md` | Your own rules (people, accounts, routing). The hub reads it with `SKILL.md`; promoted learnings are written here. |
+| `ext/*.py` | Optional extensions: extra status lines and watchdog checks. |
+| `~/.local/state/hubkit/` | State: orders, work items, alerts, archive, status. Override with `$HUBKIT_STATE`. Refused if inside a git repository. |
+
+Every key is documented in [docs/configuration.md](docs/configuration.md).
+
+## What hubkit enforces and what it only warns about
+
+| Behaviour | Strength |
+|---|---|
+| The Stop hook holds the turn while the hub owes something: no watch running, a stalled item, an unbacked verdict, an unsolved blocker, an item over its estimate, a "done" while your newest prompt is unread | Enforced (blocks the turn end) |
+| An order closes only with the evidence its kind requires | Enforced (the close is refused) |
+| A learned class counts as fixed only if a rule for it exists | Enforced (the address is refused) |
+| A second job sent to a busy owner while an order is open; a brief that bans the action a blocker needs | Warning only |
+| `gh pr merge` with no live order naming that PR (the merge guard, `hubkit hook pretool`) | Warning only, never denies |
+| `hubkit doctor` warning when your `intents.toml` lacks keys the example has | Warning only |
+
+Details and exact rules: [SKILL.md](SKILL.md) and [docs/architecture.md](docs/architecture.md#stop-gate-gatepy).
+
+## Documentation
+
+- [docs/architecture.md](docs/architecture.md): hooks, orders, routed work, the stop gate and the learn loop, with a diagram.
+- [docs/configuration.md](docs/configuration.md): every `config.toml` and `intents.toml` key.
+- [docs/commands.md](docs/commands.md): every `hubkit` and `learn.py` verb.
+- [docs/troubleshooting.md](docs/troubleshooting.md): common problems and what to check.
+- [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [CHANGELOG.md](CHANGELOG.md).
+
+## Tests
+
+```bash
+python3 -m pytest tests -q          # real subprocesses, scratch state dirs only
+python3 tests/run_reverts.py        # each guard reverted in a copy must fail its test (minutes)
+```
+
+`run_reverts.py` exits 0 only when every reverted copy fails its test and every listed pattern and test exists. Install `pytest` first (`pip install pytest`).
+
+## Platform support
+
+All OS-specific code is in one module, `scripts/hubcore/compat.py` (standard library only): process start time and parent (`/proc` on Linux, `ps` on macOS, kernel32 through `ctypes` on Windows), file locks (`flock`, or `msvcrt` on Windows), the scheduler check (`crontab -l`, or `schtasks /query` on Windows) and UTF-8 stdio.
+
+| OS | Status |
+|---|---|
+| Linux | Full test suite run and passing here (ruff, mypy, pytest). |
+| macOS | The `ps` code path is exercised on Linux against the real `ps` (`tests/test_compat.py`), and mypy checks it with `--platform darwin`. Never run on a Mac. Not claimed to work until someone runs it there. |
+| Windows | The `ctypes` and `msvcrt` code is type-checked with `--platform win32` only. Never run on Windows. Tests that need a POSIX `sh` shim for `gh`, `crontab` or a notifier are skipped there. Not claimed to work until someone runs it there. There is no default desktop notification on Windows: set `tools.notify_cmd`. |
+
+There is no CI. Update this table only from a real run on that OS. On Windows the schedule is a Task Scheduler task whose name or command holds `hubkit` (for example `schtasks /create /sc minute /mo 5 /tn hubkit-tick /tr "python %USERPROFILE%\.claude\skills\hub\scripts\hubkit tick --if-bound"`), and hooks in `settings.json` call `python ...\hubkit hook <event>`.
+
+## Limits and known gaps
+
+- Python 3.14 only. macOS and Windows are written but unproven; see Platform support.
+- It targets one hub per machine. A second live hub is refused at bind.
+- Order creation takes a blocking `flock` (`scripts/hubcore/orders.py`); a process that holds the lock forever stalls order opens.
+- A hook payload with no `origin` field is treated as human input.
+- Redaction matches secret shapes and `key=value` forms. Natural-language secrets ("the password is hunter2") are not caught. See [SECURITY.md](SECURITY.md).
+- Whether a message to a peer is an ask, a reply or a follow-up is decided by rules in `scripts/hubcore/routed.py`; an unusual message can be misjudged.
+- The learn loop needs the hub model to act on the `CORRECTION` line; hubkit cannot make it record or write a rule, only refuse to mark a class fixed without one.
+- `skills/hub-mep` describes an optional integration with the `mep` task-list CLI and is of no use without it.
+- Hooks are written against the Claude Code hook payloads of late 2026; `payload-samples/` in the state dir records the real payload keys so a schema change is visible.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE). Copyright 2026 the hubkit contributors.

hubkit_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,51 @@
+hubcore/__init__.py,sha256=IyQZIMUEIvq505jdiUulXi0cbQHQ93shqO0_2L0yPMo,79
+hubcore/cli.py,sha256=ms5bvHnI95ml2XO9PdWAHfKQVK25pFsUhVS8FG99cwE,12336
+hubcore/compat.py,sha256=yCCV2IA-T2vxTYe1Fp47qkCXREJb4OmSzv6OyiNuBjU,6700
+hubcore/config.py,sha256=qN_ewJJrt99FCcWzCx1Tf_nDacSJfiT4nFknRx0641U,4611
+hubcore/gate.py,sha256=mENEHwD8dMWSjef28rz4Ug0T2QepsSWfHoalDp__JVA,8124
+hubcore/hooks.py,sha256=okuNkqj0uvKaAfPeagL91-p1j6qngK1zPQB6Bgu9Eww,14757
+hubcore/install.py,sha256=VBgLXi28spfEn5By2GzSUmeYbikDmexlhlBsqzm0hK0,3073
+hubcore/learnings.py,sha256=1Sm5XaokUcKBCrb7vw9FLsf9GZFRr7j68cYgbt4MMeo,9257
+hubcore/lessons.py,sha256=Nvetkk10bcDGygSyPYFE1GddGQ2pMRzdNA2ViQT-OqA,7867
+hubcore/orders.py,sha256=oHU45Gem5bQlXHGWJKMkh4Wf3juSxJLJ1jVQTLn9xMk,24779
+hubcore/redact.py,sha256=sT4tSvUbDd7FqYHJ0-deLEub52opMpgYc8KTxFKTimU,3322
+hubcore/routed.py,sha256=eA3Wv8hOcmcIlbzLZntHwUxCu97apXcMs12W95qT-h8,50013
+hubcore/slow.py,sha256=lKHqyUOXKKLilQwtnbR1IUZ6OgPO4L9zIfZBomglcOw,20597
+hubcore/status.py,sha256=jzG-EtE3uCu2Ezwvj9DZiZwCl91sok1kYc1koXES0R4,23452
+hubcore/store.py,sha256=EzDzNZcCw-xUorNxXKZNyfBoLlYG5M5hrffbMfOg4zI,5647
+hubcore/watcher.py,sha256=pjalPYGF_6W1QzLjMw_iC1SIaP1oW8r9aGkrxQeQudE,8454
+hubcore/data/hub-mep/SKILL.md,sha256=Z1BV-MezlAoW02KDPsb4Va3eAL9nruFi70GdCh5KhsE,3302
+hubcore/data/hubkit-setup/SKILL.md,sha256=0O_ji8sJzgZGOE1LX3m_BQRKCU-UxFdbS3WEOqhia3w,3961
+hubcore/data/hub/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+hubcore/data/hub/SKILL.md,sha256=pG9wkwZBAAsBiwx55A4Jx2ktzZiQpiK0tS5nCoRM9PQ,17053
+hubcore/data/hub/config.example.toml,sha256=Sot5NKXtN-Uxco_WAWxHTpqpQbbxP-Lv0NbIjjZ3Sqs,4884
+hubcore/data/hub/docs/architecture.md,sha256=KZZHvzAxHd9jhV3RnzK7vWKi3hlvC2isiL7g2XXtefU,16764
+hubcore/data/hub/docs/commands.md,sha256=Yelxi785rv9f3DoKljIItqY8n9iCGFzfo4Ky_WbKJhQ,5632
+hubcore/data/hub/docs/configuration.md,sha256=blhBZpzmsi0MnZWK2aZVb4t7Vf-iWgAfmGOTZpiZ0-s,9150
+hubcore/data/hub/docs/troubleshooting.md,sha256=SPonaqwdj3Uu9UXfYxQO33HL1c-SxGc67MqHjx0FGpw,3469
+hubcore/data/hub/intents.example.toml,sha256=zkCGO-zp8YL4E1fhdulBK313xeMyNz-2gbdy6Xd9XCI,4323
+hubcore/data/hub/references/design-sources.md,sha256=i53AaQsJFnZLFXAJoWZxaCEy918BFf0neqvJDyNWJ_k,1607
+hubcore/data/hub/references/research.md,sha256=SDKPp3XDnbI20M1fNEZBpPw26zaV8D6Yewf-Aj7VAM0,3523
+hubcore/data/hub/scripts/hubcore/__init__.py,sha256=IyQZIMUEIvq505jdiUulXi0cbQHQ93shqO0_2L0yPMo,79
+hubcore/data/hub/scripts/hubcore/cli.py,sha256=ms5bvHnI95ml2XO9PdWAHfKQVK25pFsUhVS8FG99cwE,12336
+hubcore/data/hub/scripts/hubcore/compat.py,sha256=yCCV2IA-T2vxTYe1Fp47qkCXREJb4OmSzv6OyiNuBjU,6700
+hubcore/data/hub/scripts/hubcore/config.py,sha256=qN_ewJJrt99FCcWzCx1Tf_nDacSJfiT4nFknRx0641U,4611
+hubcore/data/hub/scripts/hubcore/gate.py,sha256=mENEHwD8dMWSjef28rz4Ug0T2QepsSWfHoalDp__JVA,8124
+hubcore/data/hub/scripts/hubcore/hooks.py,sha256=okuNkqj0uvKaAfPeagL91-p1j6qngK1zPQB6Bgu9Eww,14757
+hubcore/data/hub/scripts/hubcore/install.py,sha256=VBgLXi28spfEn5By2GzSUmeYbikDmexlhlBsqzm0hK0,3073
+hubcore/data/hub/scripts/hubcore/learnings.py,sha256=1Sm5XaokUcKBCrb7vw9FLsf9GZFRr7j68cYgbt4MMeo,9257
+hubcore/data/hub/scripts/hubcore/lessons.py,sha256=Nvetkk10bcDGygSyPYFE1GddGQ2pMRzdNA2ViQT-OqA,7867
+hubcore/data/hub/scripts/hubcore/orders.py,sha256=oHU45Gem5bQlXHGWJKMkh4Wf3juSxJLJ1jVQTLn9xMk,24779
+hubcore/data/hub/scripts/hubcore/redact.py,sha256=sT4tSvUbDd7FqYHJ0-deLEub52opMpgYc8KTxFKTimU,3322
+hubcore/data/hub/scripts/hubcore/routed.py,sha256=eA3Wv8hOcmcIlbzLZntHwUxCu97apXcMs12W95qT-h8,50013
+hubcore/data/hub/scripts/hubcore/slow.py,sha256=lKHqyUOXKKLilQwtnbR1IUZ6OgPO4L9zIfZBomglcOw,20597
+hubcore/data/hub/scripts/hubcore/status.py,sha256=jzG-EtE3uCu2Ezwvj9DZiZwCl91sok1kYc1koXES0R4,23452
+hubcore/data/hub/scripts/hubcore/store.py,sha256=EzDzNZcCw-xUorNxXKZNyfBoLlYG5M5hrffbMfOg4zI,5647
+hubcore/data/hub/scripts/hubcore/watcher.py,sha256=pjalPYGF_6W1QzLjMw_iC1SIaP1oW8r9aGkrxQeQudE,8454
+hubcore/data/hub/scripts/hubkit,sha256=ipNoQHb3kntnBFQ_qct9ytR5AM7c1qR45Vp6DBrr6_4,1405
+hubcore/data/hub/scripts/learn.py,sha256=x_XMSy59ar-bbhP0viD0-TKBLFY_KxQLnfhiWmzDLh8,4036
+hubkit_cli-0.1.0.dist-info/METADATA,sha256=8JhDlWxxDvcHvj7Rf2hrIY10NXQTLS0iJ46CQYGswh4,14277
+hubkit_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+hubkit_cli-0.1.0.dist-info/entry_points.txt,sha256=gxPYc8e-YUz4olwwJQwyblb4oXmGki5dYpNKtAGPW3w,43
+hubkit_cli-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+hubkit_cli-0.1.0.dist-info/RECORD,,

hubkit_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hubkit_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hubkit = hubcore.cli:run