hubkit-cli 0.1.0__py3-none-any.whl

hubcore/data/hub/docs/commands.md

@@ -0,0 +1,66 @@
+# Command reference
+
+`hubkit` below means `python3 ~/.claude/skills/hub/scripts/hubkit`. Exit codes: 0 success, 2 a refused or invalid request (message on stderr), 1 `doctor` found a problem. `hook` always exits 0.
+
+## hubkit
+
+| Verb | What it does |
+|---|---|
+| `skills --install DIR` | Copies the hub, hub-mep and hubkit-setup skills into DIR (re-run refreshes; the running copy is left alone). |
+| `hooks [--skills-dir DIR] [--merge-guard]` | Prints the `hooks` JSON for settings.json. `--merge-guard` adds the warn-only PreToolUse merge guard. Never edits settings.json. |
+| `hubkit bind [--pid N]` | Bind this session (found by walking up the process tree, or the process `N`) as the hub. Interactive sessions only; refuses while another hub is live. |
+| `hubkit unbind` | Remove the bind. |
+| `hubkit status [--json]` | Rebuild `status.json` and print the status block (or the JSON). |
+| `hubkit order ls` | One line per live order. |
+| `hubkit order status [ID]` | The status line of one order, or all live orders. |
+| `hubkit order open --kind K --quote "..." [--unconfirmed]` | Open an order by hand. |
+| `hubkit order confirm ID` | Turn an unconfirmed order into an open one. |
+| `hubkit order move ID --note "..." [--estimate N]` | Record real movement. The first move also records the order's estimate (N minutes, else the usual time for its kind; printed when defaulted). |
+| `hubkit asks ls [--since 12h]` | His recent prompts (from `recent-prompts.jsonl`), one line each, newest last. Marks the asks as re-read for the Stop gate. |
+| `hubkit order block ID --on "..." [--fix "..."] [--holder who]` | Record what blocks an order and the fix running now (a second call with the same `--on` adds the fix). No fix, or a fix older than `blocker_fix_min` with no result, alerts and holds the Stop gate. |
+| `hubkit order result ID --note "..."` | Record the result of an action: movement, clears the blocker and any STOP-LOSS. Notes from `order move` do neither. |
+| `hubkit order hold ID --quote "..."` / `resume ID` | Hold (with the user's words) and resume. |
+| `hubkit order cancel ID --quote "..."` | Cancel and archive. |
+| `hubkit order close ID --evidence name=value ...` | Close; every name in the kind's `done_when` is required. `file:<path>` values must exist and be newer than the order. Every PR number the order names must appear in the evidence. |
+| `hubkit order metrics [--day YYYY-MM-DD]` | Orders and chases for a day, as JSON. |
+| `hubkit work add --kind active\|tracked\|priority --title "..." [--owner X] [--note ".."]` | Add a live work item; prints its id. |
+| `hubkit work add --kind routed --owner X --title "..." [--pr URL ...] [--head SHA]` | Record routed work by hand. |
+| `hubkit work add --kind ask --title ".." --note ".."` | Register a question that really blocks work on the user; his card answer closes it. |
+| `hubkit work add ... [--estimate N]` | `--estimate` is the minutes the job should take (routed items default to the usual time for their step). |
+| `hubkit work estimate ID --minutes N --why "..."` | Hub-internal. Record a new estimate for a routed item or live order beside the old one (never over it). `N` must exceed the minutes already spent and `--why` is required. This is one way to address an overrun. |
+| `hubkit work block ID --on OTHER` | Hub-internal. Say that routed item ID waits on job OTHER: while OTHER is live, ID raises no STALLED/OVERDUE or SLOW. `hubkit work block ID` (no `--on`) clears it. |
+| `hubkit work done ID --note ".."` | Archive an item. |
+| `hubkit work ls` | List live items. |
+| `hubkit tick [--if-bound] [--no-notify]` | One watchdog pass; prints `ALERT ...` lines. `--if-bound` is a no-op unless a hub is bound or an order is open (for cron). |
+| `hubkit watch [--interval S] [--max-cycles N]` | Loop `tick` (defaults 300 s, 12 cycles). Exits 0 printing `ALERT ...`, 3 after the cycles, 4 if another watch runs. |
+| `hubkit eod [--day D] [--note ".."]` | Write and print the end-of-day review. |
+| `hubkit doctor [--check-clean]` | Print config, state, bind, hook heartbeats, ledger health and a count of secret-shaped strings in state. `--check-clean` also lists checkout files containing a `private.terms` word. Exit 1 on a problem. |
+| `hubkit hook EVENT` | Run one hook (`session`, `prompt`, `answer`, `routed`, `stop`, `record`); reads the payload from stdin. For Claude Code, not for people. |
+
+## learn.py
+
+`python3 ~/.claude/skills/hub/scripts/learn.py [--file PATH] VERB`
+
+| Verb | What it does |
+|---|---|
+| `add --class C --quote "..." [--gate G1..G8] [--date D] [--situation ..] [--wrong ..] [--right ..] [--evidence ..]` | Record a class of mistake, or a dated repeat of one. |
+| `list [--last N]` | The N most recently seen entries (default 30). |
+| `promote-candidates [--min N]` | Classes seen at least N times (default 2). |
+| `promote CLASS --gate G --rule "..."` | Write a rule line tagged `[CLASS]` into the overlay under its gate. |
+| `address --class C --how "..."` | Mark a class fixed. Refused unless the overlay or SKILL.md changed since it was last seen and holds a `[C]` rule line. |
+| `review [--day D]` | New, repeated, regressed, holding and unaddressed classes for a day. |
+
+## Example
+
+```console
+$ hubkit work add --kind active --title "triage the flaky test"
+W1
+$ hubkit tick --no-notify
+$ hubkit status
+hubkit: you are the hub session for the user. Re-read the hub SKILL.md and the overlay before acting.
+status built 0 min ago
+active: W1 triage the flaky test
+mep: UNVERIFIED (mep CLI not found; it is optional, set [mep] enabled = false in config.toml)
+hook errors in scan window: 0
+open orders: 0
+```

hubcore/data/hub/docs/configuration.md

@@ -0,0 +1,151 @@
+# Configuration reference
+
+All user-specific values live in `~/.config/hubkit/` (or `$XDG_CONFIG_HOME/hubkit/`). Nothing personal belongs in the checkout. Every key is optional; a missing key uses the default in `scripts/hubcore/config.py` (`DEFAULTS`). Templates: [`config.example.toml`](../config.example.toml) and [`intents.example.toml`](../intents.example.toml).
+
+## Files and environment
+
+| What | Where | Override |
+|---|---|---|
+| Settings | `<config dir>/config.toml` | `$HUBKIT_CONFIG` (full path) |
+| Intents | `<config dir>/intents.toml`, else the `intents.example.toml` shipped in the checkout | `paths.intents` |
+| Overlay (your rules) | `<config dir>/overlay.md` | `paths.overlay` |
+| Extensions | `<config dir>/ext/*.py` | `paths.extensions_dir` |
+| State | `$XDG_STATE_HOME/hubkit` (default `~/.local/state/hubkit`) | `$HUBKIT_STATE`, `paths.state_dir` |
+| Learnings | `<state dir>/learnings.md` | `paths.learnings` |
+
+Other environment variables: `HUBKIT_SESSIONS` (directory of Claude Code session files, overrides `paths.sessions_dir`), `HUBKIT_DISABLE` (any value: every hook is a no-op), `HUBKIT_DIE_AFTER` (test hook for crash recovery; do not set).
+
+## config.toml
+
+### `[user]`
+| Key | Default | Meaning |
+|---|---|---|
+| `name` | `"the user"` | How the status block names you. |
+| `timezone` | `""` (system zone) | IANA name, for example `Europe/Berlin`. Times are stored as epoch and shown in this zone; days roll over in it. |
+| `github_login` | `""` | Your GitHub login. On a PR you wrote, the reviewer peer posts from your account and GitHub allows only a COMMENT there, so a COMMENT review with a body (not an empty-body inline-thread reply) at the PR head counts as the review (verdict check, item close, queue advance). Empty keeps the non-author rule everywhere. |
+
+### `[hub]`
+| Key | Default | Meaning |
+|---|---|---|
+| `name` | `"hub"` | Names the hub in the status block and is the session name matched when the SessionStart hook re-binds a resumed hub. |
+
+### `[paths]`
+| Key | Default | Meaning |
+|---|---|---|
+| `state_dir` | `""` | State directory. Must not be inside a git repository or the skill directory. |
+| `intents` | `""` | Path of `intents.toml`. |
+| `overlay` | `""` | Path of `overlay.md`. |
+| `learnings` | `""` | Path of the learnings file. |
+| `sessions_dir` | `~/.claude/sessions` | Where Claude Code writes one `<pid>.json` per running session; used to find and verify the hub. |
+| `transcripts_glob` | `~/.claude/projects/*/*.jsonl` | Transcripts scanned for failures of hubkit's own hooks and for heard-from signals. |
+| `extensions_dir` | `""` | Directory of extension modules. |
+
+### `[tools]`
+| Key | Default | Meaning |
+|---|---|---|
+| `mep` | `"mep"` | Name or path of the optional `mep` CLI. |
+| `gh` | `"gh"` | Name or path of the GitHub CLI. |
+| `notify_cmd` | `""` | Command run with the alert message as its last argument (for example `notify-send -u critical -a hubkit`). Empty means no desktop notification. |
+
+### `[mep]`
+| Key | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | Ask `mep status --json` for the items on the user. Set `false` if you do not use mep. When enabled and `mep` is missing, the status block shows `mep: UNVERIFIED (...)`. |
+| `timeout_s` | `30` | Seconds before a slow `mep` call is abandoned (the last good answer is kept, labelled stale). |
+| `data_dir` | unset | Exported as `MISEENPLACE_DIR` for the call. |
+
+### `[watchdog]`
+| Key | Default | Meaning |
+|---|---|---|
+| `transcript_scan_hours` | `24` | How far back to scan transcripts for hubkit hook failures. |
+| `cron_stale_min` | `15` | `doctor` flags `seen/cron` as stale when the crontab runs hubkit and the file is older than this. |
+
+### `[slow]`
+
+Estimates and the slowness check (hub-internal, see architecture).
+
+| Key | Default | Meaning |
+|---|---|---|
+| `min_samples` | `3` | Archived samples needed before the usual time replaces the stall limit. |
+| `order_default_min` | `30` | Default order estimate while there is no history. |
+| `floor_min` | `2` | A job is never SLOW under this many minutes. |
+| `tool_min` | `2` | A tool running this long is named in the why. |
+| `scan_kb` | `2048` | Tail of a transcript read for the why (tool names and queue operations only). |
+
+### `[watcher]`
+
+| Key | Default | Meaning |
+|---|---|---|
+| `stuck_min` | `30` | Hub session `busy` this long with live jobs raises `hub:stuck`. |
+| `unhandled_min` | `10` | An alert this old with no hub heartbeat since raises `hub:unhandled`. |
+| `waiting_min` | `3` | A peer waiting on a prompt this long raises `peer:<name>:waiting`. |
+| `active_s` | `120` | A busy holder whose transcript grew this recently is working, not stalled. |
+| `watch_grace_min` | `5` | Live work with no running `hubkit watch` this long raises `watch:dead`. |
+| `notify_user` | `true` | Use the platform default desktop notification for hub and peer alerts when `tools.notify_cmd` is empty. |
+
+### `[stop_guard]`
+| Key | Default | Meaning |
+|---|---|---|
+| `phrases` | `["waits for your go", "say go", "want me to", "shall i"]` | A final message ending in `?` or containing one of these, while no `ask` item exists, is blocked by the stop gate. |
+
+### `[private]`
+| Key | Default | Meaning |
+|---|---|---|
+| `terms` | `[]` | Words that must never appear in the checkout's own files. `hubkit doctor --check-clean` lists the files that contain one (never the match). Keep this file on your machine. |
+
+### `[routed]` (also readable from `intents.toml`; intents win)
+| Key | Default | Meaning |
+|---|---|---|
+| `stall_min` | `15` | Silence from the owner this long is STALLED; the ladder steps at multiples of it. |
+| `review_words` | `["review"]` | A message naming a PR and one of these is a review item. |
+| `review_stall_min` | `5` | Reviews: chase after this. |
+| `review_overdue_min` | `10` | Reviews: hard OVERDUE this long after routing, whatever the owner said. |
+| `skip_owners` | `["inbox"]` | Owners that are never tracked. |
+| `min_chars` | `200` | A message without a PR is work only from this length. |
+| `gh_timeout_s` | `10` | Timeout for one `gh` read. |
+| `queued_wait_min` | `60` | Work queued "after X" gets no review clock until this long after the ask (or until a review shows). |
+| `reply_window_min` | `60` | A hub reply to a peer who wrote this recently is not an ask. |
+| `repo` | `""` | `owner/name`; a bare `#N` resolves against it so `gh` can read the PR. |
+| `repo_aliases` | `{}` | Table of alias to `owner/name`. `<alias> 123`, `<alias>#123` and `owner/name#123` name the PR in that repo instead of the default `repo`. |
+| `owner_logins` | `{}` | Map of owner name to GitHub login, for peers who author PRs. |
+| `reviewer_logins` | `[]` | Logins whose review counts. Empty means any non-author review. |
+| `skip_briefs` | `["mep watch", "inbox watch"]` | Briefs containing one of these are standing watchers, never routed work. |
+| `activity_globs` | two Claude Code paths | Files whose growth shows a background agent is alive. `{id}` is the agent id. |
+
+## intents.toml
+
+The first kind whose words match wins, so put the narrower kind first (`hotfix` before `release`).
+
+### `[intake]`
+| Key | Meaning |
+|---|---|
+| `imperative` | An order opens as `open` only if one of these words is present; otherwise it is `unconfirmed`. |
+| `hold_words` | Explicit holds only. Bare "don't", "wait", "stop" are not holds. |
+| `urgent_words` | A hold is ignored, and a held order restarts, when one is in the prompt. |
+| `stop_loss` | This many chases on one order print a stop-loss line. |
+| `not_order_phrases` | Phrases that contain an order word but are not orders ("release notes"). |
+| `question_start` | Regex; an order word in a question is never an order, urgent words or not (the hook then says so and shows `hubkit order open` for opening one by hand). |
+| `unconfirmed_ttl_min` | `tick` expires unconfirmed orders after this long. |
+| `held_review_min` | A hold this long raises an alert. |
+| `cancel_words`, `resume_words` | Words for the cancel and resume verbs. |
+| `verb_max_chars` | Prompts longer than this never hold, cancel, resume or count as chases. |
+| `chase` | Regex; a short prompt matching it while an order is open is a chase. |
+
+### `[corrections]` (the learn loop)
+| Key | Meaning |
+|---|---|
+| `patterns` | Regexes; a typed prompt matching one injects a `CORRECTION` line asking the hub to record it. |
+| `repeat_similarity` | Word-set similarity (0 to 1) above which a prompt counts as repeating a recent one. Default `0.6`. |
+| `repeat_window_min` | How far back a repeat is looked for. Default `30`. |
+
+### `[kinds.<name>]`
+| Key | Meaning |
+|---|---|
+| `words` | Words that open an order of this kind. |
+| `first_action_min` | No `order move` within this many minutes raises an alert. |
+| `stall_min` | No movement for this long raises an alert. |
+| `dispatch` | Text printed when the order opens. |
+| `done_when` | Evidence names `order close` requires (`--evidence name=value`). |
+| `movement_files` | Globs; a file touched after the order opened counts as movement. |
+
+Add your own kinds the same way; the words are matched as whole words, case-insensitively.

hubcore/data/hub/docs/troubleshooting.md

@@ -0,0 +1,21 @@
+# Troubleshooting
+
+Start with `hubkit doctor`: it prints the config path, state path, bind, hook heartbeats (`seen/<hook>`), ledger health, hook errors and a count of secret-shaped strings in state.
+
+| Symptom | Cause and fix |
+|---|---|
+| Hooks print nothing | Expected outside the bound hub. Run `hubkit bind` in the session meant to be the hub; `doctor` must show `bind: live <name>`. Headless runs and non-interactive sessions are never the hub. `HUBKIT_DISABLE` also silences hooks. |
+| `seen/session: never` (or any hook) | The hook is not registered in `~/.claude/settings.json`, or Claude Code was not restarted after editing it. Check the command line against the README. |
+| `seen/cron: never` or old | The cron line is missing or fails. `tick` touches `seen/cron` on every run, even the early no-op, so this tells a dead cron from an idle one. `doctor` prints `cron: STALE` when a crontab line runs hubkit but `seen/cron` is older than `watchdog.cron_stale_min`. The usual cause is cron running an older `python3` than 3.14 (hubkit fails with a `SyntaxError` that goes to `/dev/null`): run `env -i PATH="$(grep ^PATH= /etc/environment | cut -d'"' -f2)" sh -c 'python3 --version'` and put the full interpreter path in the crontab line. Add `DISPLAY` and `DBUS_SESSION_BUS_ADDRESS` to the crontab for desktop notifications. |
+| `error: state dir ... is inside a git repository` | State must not be committed. Move it with `$HUBKIT_STATE` or `paths.state_dir`, or run from a home directory that is not a git repository. |
+| `error: no Claude session found for this process (pass --pid)` | `bind` walks up the process tree to a Claude Code process listed in `paths.sessions_dir`. Run it from the hub session, or pass `--pid`. |
+| `error: live hub already bound` | Another hub is bound. `hubkit unbind` from that session, or wait for it to exit (a dead process frees the bind). |
+| `mep: UNVERIFIED (mep CLI not found ...)` | The optional `mep` CLI is missing. Set `[mep] enabled = false` in `config.toml`. |
+| `PR unknown` on routed items | `gh` is missing, not authenticated, or the PR is in a repository the token cannot read. Check `gh auth status`; set `routed.repo` so bare `#N` resolves. |
+| A prompt did not open an order | The sentence was a question, held a `not_order_phrases` phrase, had no `imperative` word (so it is `unconfirmed`: `hubkit order confirm ID`), or came from peer or harness text, which never opens orders. |
+| `close refused: missing evidence` | Give every name in the kind's `done_when`: `--evidence name=value`. `file:<path>` must exist and be newer than the order. |
+| The turn will not end (Stop gate) | Read the `NEXT:` in the block reason. Usually: start the watch (`hubkit watch --interval 120 --max-cycles 30` in the background), act on a stalled item, drop an unbacked verdict, or register the question with `hubkit work add --kind ask`. |
+| `import-errors.log` in the state dir | hubkit failed to import (wrong Python version, damaged checkout). Hooks exit 0 so Claude Code is unaffected. Run `python3 --version` (3.14 or newer needed) and `hubkit doctor`. |
+| `SyntaxError` on `except A, B:` | Python older than 3.14. |
+| `doctor --check-clean` lists files | The files contain a word from `private.terms`. Edit them; the match is not printed. |
+| `learn.py address` refused | No rule line tagged `[class]` exists in the overlay or SKILL.md, or neither changed since the class was last seen. Run `learn.py promote` first. |

hubcore/data/hub/intents.example.toml

@@ -0,0 +1,74 @@
+# Intents: words in the user's own prompts that start an order, and what "done" means.
+# Copy to ~/.config/hubkit/intents.toml (or set paths.intents in config.toml) and edit.
+# The first kind whose words match wins, so put the narrower kind first (hotfix before release).
+
+[intake]
+# An order opens as "open" only if one of these words is present; otherwise "unconfirmed"
+# (no clock alerts until `hubkit order confirm <id>`).
+imperative = ["now", "asap", "need", "must", "do", "make", "start", "run", "merge", "fix", "finish", "go", "urgent"]
+# Explicit holds only. Bare "don't", "wait" or "stop" are NOT holds ("don't wait, merge it now").
+hold_words = ["hold off", "on hold", "put it on hold", "hold the", "hold it", "pause", "not yet", "don't deploy", "dont deploy", "do not deploy", "stand by"]
+# A hold is ignored, and a held order restarts, when one of these is in the prompt.
+urgent_words = ["now", "asap", "urgent", "immediately", "right away", "hurry", "don't wait", "dont wait", "do not wait"]
+# This many chases on one order: the hook prints a stop-loss line (stop other work, report the blocker).
+stop_loss = 3
+# A blocker on an order must have a fix running; a fix with no recorded result after this long alerts and holds the Stop gate.
+blocker_fix_min = 3
+# Phrases that contain an order word but are not orders ("the release notes look fine").
+not_order_phrases = ["release notes", "release note", "release branch", "release candidate", "release date", "release process", "release checklist"]
+# An order word in a question is never an order, urgent words or not; the prompt hook says no order was opened and how to open one by hand.
+question_start = '(?i)^\W*(why|what|how|did|does|do you|is|are|was|were|can|could|would|should|when|where|who|which|has|have)\b'
+# Orders left unconfirmed this long are expired by `tick`; a hold this long raises an alert.
+unconfirmed_ttl_min = 30
+held_review_min = 120
+cancel_words = ["cancel", "abort", "drop it", "never mind"]
+
+resume_words = ["resume", "go ahead", "continue"]
+# Prompts longer than this never hold, cancel or count as chases (they are discussion).
+verb_max_chars = 120
+# A short prompt matching this while an order is open counts as a chase on that order.
+chase = '(?i)\b(status|eta|done\?|still (not|waiting|running|open)|hold ?up|hurry|where are we|any progress|update\?|why is (it|this|that)|how long)'
+
+[stop_gate]
+# A final message holding one of these words, while an order is open and none has a fix on record, cannot end the turn:
+# a blocker is solved, not reported. Whole words or phrases, case-insensitive.
+blocked_words = ["blocked", "is down", "are down", "failed", "failing", "no host", "cannot reach", "can't reach", "unreachable", "not available", "waiting on", "waiting for", "stuck", "needs a person", "needs his call", "needs her call"]
+
+[corrections]
+# A human prompt matching one of these regexes (or repeating the previous prompt) makes the prompt
+# hook inject a reminder to record it: learn.py add with the quote.
+patterns = ["(?i)\\b(useless|stupid|dumb|idiot|wtf|r u (dumb|kidding|sleeping))\\b", "(?i)^\\W*(wrong|no+|nope)[!. ]*$", "(?i)\\bwhy (did|didn't|do|are) (you|u)\\b", "(?i)\\bi (told|asked|said)\\b", "(?i)\\balready (told|said|asked|replied)\\b", "(?i)\\bnot what i (asked|said|meant)\\b"]
+repeat_similarity = 0.6
+repeat_window_min = 30
+
+[kinds.hotfix]
+words = ["hotfix", "hotpatch"]
+first_action_min = 5        # no `order move` within this many minutes -> alert
+stall_min = 10              # no movement for this long -> alert
+dispatch = "Dispatch the hotfix path; merge the named PR first."
+done_when = ["pr_merged", "prod_live"]            # evidence names `order close` requires
+movement_files = []         # globs; a file touched after the order opened counts as movement
+
+[kinds.release]
+words = ["release", "app update"]
+first_action_min = 5
+stall_min = 15
+dispatch = "Dispatch the release path."
+done_when = ["prs_merged", "smoke_passed"]
+movement_files = []
+
+[kinds.merge]
+words = ["merge"]
+first_action_min = 5
+stall_min = 30
+dispatch = "Merge exactly the named set."
+done_when = ["merged"]
+movement_files = []
+
+[kinds.code_red]
+words = ["code red", "p0"]
+first_action_min = 10
+stall_min = 30
+dispatch = "Name an owner and check for a commit or review signal."
+done_when = ["resolved"]
+movement_files = []

hubcore/data/hub/references/design-sources.md

@@ -0,0 +1,14 @@
+# Where the design parts come from
+
+| Part | Source |
+|---|---|
+| Hub keeps control, workers are tools; never accept "done" from the author | research.md [A2] evaluator-optimizer, [S1] supervisor, "Verification by a separate judge" |
+| Briefs carry objective, output, boundaries; agents see only the brief | [A1], [A3] |
+| Effort scaling, agent cap, parallel launch | [A1]; the cap itself is a user rule, kept in the overlay |
+| Hard stop and human checkpoints; resume from failure | [A2], [A1]; implemented as the stop-loss line on repeated chases and the order `hold` verb |
+| Evaluate early on about 20 real cases; trace decision patterns | [A1]; the tests replay realistic prompts and transcript entries |
+| Persist plan and state outside the context; fresh-context hand-off | [A1]; status file, orders and archive in the state dir, reloaded by the SessionStart block |
+| Block size cap (5 learnings), 30-day expiry and 14-day probation of learnings | keeps post-compaction context small; probation so a fix is proven before it drops |
+| Orders with clock and evidence, watchdog outside the hooks, hooks fail open and stay silent outside the hub | hook failures are invisible to the model, so the watchdog scans transcripts for them |
+| Learnings promoted into rules, addressed only after a rule change | "Learning loops and memory" in research.md: a correction repeated without a rule change is not fixed |
+| Human-only intake, fail-open hooks, stale-labelled external reads | prompt origin must be human, whole-text peer-marker scan, import failure exits 0, `mep` kept as last good answer when slow |

hubcore/data/hub/references/research.md

@@ -0,0 +1,49 @@
+# Research: hub orchestration (2026-11-04)
+
+Fetched and read in full: [A1], [A2], [A3]. Search snippets only (not opened): [S1], [S2], [S3].
+Figures below come from the fetched pages. Treat snippet-only claims as unverified.
+
+## Sources
+- [A1] https://www.anthropic.com/engineering/multi-agent-research-system (read)
+- [A2] https://www.anthropic.com/engineering/building-effective-agents (read)
+- [A3] https://code.claude.com/docs/en/sub-agents (first 100k chars read)
+- [S1] https://github.com/langchain-ai/langgraph-supervisor-py (snippet)
+- [S2] https://fast.io/resources/openai-agents-sdk-vs-langgraph/ (snippet, vendor blog)
+- [S3] https://www.developersdigest.tech/blog/multi-agent-orchestration-patterns (snippet)
+- Not fetched: the Claude Code skills doc (https://code.claude.com/docs/en/skills).
+
+## What applies to the hub
+
+Delegation criteria
+- [A3] Delegate side tasks that would flood the main context with logs, search results or file bodies. Keep in the main thread only what needs back-and-forth.
+- [A1] Scale effort to the task: simple fact-finding = 1 agent, 3-10 tool calls. Early agents spawned 50 subagents for simple queries. Put an effort rule in the brief.
+- [A1] Multi-agent costs about 15x the tokens of chat. Skip it for shared-context work, many dependencies, few parallel steps (most coding).
+- [A2] Orchestrator-workers fits tasks whose subtasks cannot be predicted. Start simple, add structure only when it measurably helps.
+- [S2] Handoffs (control moves) fit linear triage. Agents-as-tools (manager keeps control) fits the hub: it never hands the user over to a peer.
+
+Brief quality
+- [A1] Every brief carries: objective, output format, tools and sources to use, clear task boundaries. Vague briefs caused duplicated work and gaps.
+- [A3] A subagent does not see the conversation. The brief is its only context.
+- [S1] A supervisor that calls workers as tools keeps control of context. This matches the hub model.
+
+Parallelism
+- [A1] Launch independent workers in parallel, not in series. This cut research time by up to 90%.
+- A cap on parallel agents and a model-tier ceiling are the user's rules; keep them in the overlay.
+
+Verification by a separate judge
+- [A2] Evaluator-optimizer: one model produces, another evaluates against clear criteria. Ground truth comes from the environment (tool results), not from the agent's own claim.
+- [A1] Judge the end state, not the path. Use an LLM judge plus human checks for edge cases.
+- The hub never accepts "done" from the agent that did the work.
+
+Context hygiene
+- [A1] Save the plan to external memory before context fills. Spawn fresh agents with clean context and hand off carefully. Workers return lightweight references, not bulk output.
+- [A3] Subagents return a summary only. Resume with SendMessage to keep their context. Explore and Plan agents cannot be resumed.
+
+Stop conditions and human checkpoints
+- [A2] Pause for human input at checkpoints or blockers. Add a hard stop (max iterations).
+- [A1] Resume from the point of failure, not from scratch. Tell an agent when a tool is failing so it adapts.
+
+Learning loops and memory
+- [A1] Start evaluating at once with ~20 real cases. Prompt changes were the main lever. Trace decision patterns, not every transcript.
+- [A1] Persist the plan. [A2] Test tools with real inputs and fix the mistakes the model makes (poka-yoke).
+- Applied here: every user correction becomes a learnings entry tied to a gate check. A class seen twice is promoted into the gate. See SKILL.md section 9.

hubcore/data/hub/scripts/hubcore/__init__.py

@@ -0,0 +1 @@
+"""hubkit core: orders, status, watchdog, hooks. Stdlib only, Python 3.11+."""