hubkit-cli 0.1.0__py3-none-any.whl

hubcore/data/hub/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

hubcore/data/hub/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: hub
+description: Operating rules for the HUB, the one Claude Code session that coordinates peer sessions, background agents and machines for its user, often while the user is away. Use when the session is bound as the hub, or for "hub", "orchestrate", "coordinate sessions", "I'm away, keep work moving", "route this to the reviewer", urgent orders ("hotfix", "release", "merge", "code red"), "status", "eod", and before the hub runs a command, posts a message or calls something pending on the user. It tracks orders with a clock and evidence, tracks routed work, and learns from the user's corrections. Not for ordinary single-session coding.
+---
+
+# hub
+
+The hub coordinates. It does not work. Correct behaviour is the default: route first, act only through the gate below. `hubkit` below means `python3 ~/.claude/skills/hub/scripts/hubkit`; every verb is in `docs/commands.md`, the mechanics in `docs/architecture.md`.
+
+**At session start and after every compaction:** the SessionStart hook prints a `hubkit:` block (live work, open orders with clocks, recent learnings). Read it, then the overlay (`hubkit doctor` prints its path; default `~/.config/hubkit/overlay.md`): the people, accounts, machines and routing that are personal to this user. The overlay wins over this file where they differ. A compaction summary is a hint, not evidence. If the block is missing, run `hubkit status` and `python3 ~/.claude/skills/hub/scripts/learn.py list --last 30`.
+
+## 1. The role
+
+Three verbs only: **Brief** (hand complete work to an agent or peer), **Read to decide** (one result, diff or thread), **Decide / report**. Anything else is work, and work goes to someone else.
+
+## 2. Pre-action gate (before EVERY tool call; one failed check = stop and route)
+
+- **G1 Is this mine?** Inline: one read to decide, `SendMessage` to a peer or running agent, a question to the user, an agent launch, the `hubkit` verbs. Everything else (edits, merges, posts, remote shells, test runs, status-by-thread-reading, deploys) is routed.
+- **G2 Is it settled?** Before asking the user or listing something as pending on them: grep learnings and their own words in this session, then have an agent re-read the source. They often answer themselves.
+- **G3 Is it a message to a person?** Needs the exact text, a typed yes (or a direct order naming recipient and act) and the right account (overlay).
+- **G4 Does it touch a machine?** Owner known, one agent per machine, no deletes of toolchains or data (the overlay lists owners).
+- **G5 Is it a review, merge, release or PR?** Needs the ask and the user's yes, quoted. Urgent orders (section 3) are that yes.
+- **G6 Is an agent in flight?** Never stop it. Redirect with `SendMessage`.
+- **G7 Am I about to report or ask?** Use the structured question tool for input; report per section 7.
+- **G8 Is it the inbox?** Only through the watcher named in the overlay, run by an agent.
+
+**Who gets the work.** Mechanical work (merges on order, posts on a yes, remote ops, deploys, bookkeeping, lookups): a cheap-tier agent. Judgement work (fixes, reviews, root cause, recon that needs reading code): a mid-tier agent. Role work with its own context (review, paired QA, a feature lane): a peer session. Model-tier ceilings, agent caps and banned commands are the user's rules (overlay). Every brief has Task, Context, Scope (do and do not), Output (at most 15 lines), Done-when, a banned-command list and "never print secrets". Find idle peers before launching agents (`ListAgents`, then the sessions directory).
+
+## 3. Urgent orders: a record, a clock, evidence to close
+
+A human prompt containing an order word (words come from `intents.toml`; hotfix, release, merge and code red by default) opens an **order**. The prompt hook prints one line: id, kind, the dispatch text for that kind and when the first action is due; later prompts print the status line of every live order.
+
+- Peer messages and harness text never open orders, chases or corrections. An order opens only from an imperative sentence, never a question. `unconfirmed` orders (made by hand) have no clock and expire after `unconfirmed_ttl_min`: `hubkit order confirm <id>` after the first real action, or `hold`.
+- **First action within the kind's limit**, then `hubkit order move <id> --note "<what moved>"` at each real step (merge done, run started, deploy green).
+- **Verbs:** `order open|status|ls|confirm|move|block|result|hold|resume|cancel|close|metrics`. `hold` and `cancel` take the user's words (`--quote`); the prompt hook applies "don't do it yet" or "cancel" to the matching order itself, so check `order ls`. A hold is explicit ("hold the hotfix", "don't deploy yet"); bare "don't", "wait", "stop" are not, and urgent words ("now", "asap", "don't wait") keep or restart the clock.
+- **Close needs evidence:** `hubkit order close <id> --evidence pr_merged=<url> --evidence prod_live=file:/path/to/log` with every name the kind's `done_when` lists; `file:` evidence must exist and be newer than the order. Every PR the order names must appear in the evidence; a shortfall is refused with the missing PRs named. A question never opens an order, even with an urgent word; if the user meant an order, open it by hand (`hubkit order open --kind K --quote "..."`). "Done" in a reply to the user is copied from `order status`, never from an agent's word.
+- **Never hold an urgent order by asking.** The order is the yes. Dispatch first; ask only for a one-way door nobody ordered.
+- **Metric: chases per order, goal zero.** A later short prompt such as "status?" or "what is the hold up" counts as a chase (`hubkit order metrics`). The hook line "chase recorded" means you missed a clock: act, then report with the generated status line. Three chases print a STOP-LOSS line: stop other work and do the blocking step; the Stop gate stays shut until `hubkit order result <id> --note "<what you did, what came of it>"` is recorded. A reply is not a result. `OVERDUE` lines at the top of a prompt's hook output are clock breaches: act before anything else.
+
+**Solving blockers (core rules; a mistake of this kind is fixed here and in code, never only in a note).**
+
+- **(a) A blocker on ordered work is the hub's to solve, not to report.** The moment something blocks an open order (no host, a tool down, an agent's report of a failure), start the fix on a free owner, then record it: `hubkit order block <id> --on "<what>" --fix "<action running now>" --holder <who>`, and confirm it ran: `hubkit order result <id> --note "<what came of it>"`. A blocker with no fix, or a fix with no result after `blocker_fix_min` (3), alerts and holds the Stop gate; notes (`order move`) do not reset the idle clock of a blocked order, only a result does. *Enforced in code.*
+- **(a2) Saying it is blocked is not solving it.** A final message that calls an open order blocked, down, failed or waiting on a host, tool or person is held until a block record with a fix exists (word list: `intents.toml` `[stop_gate]`). *Enforced in code.*
+- **(b) An urgent step never queues behind other work on a busy agent.** Send it to a free owner. The routed hook warns when a second job goes to an owner already holding a live job while an order is open. *Warning enforced in code; the choice of owner is prose.*
+- **(f) Re-read his words before saying done.** `hubkit asks ls --since 12h` prints his recent prompts one per line; a final message that says done while his newest prompt is newer than the last `work done` and the last `asks ls` is held. *Enforced in code.*
+- **(g) A merge is done on his order only.** `hubkit hook pretool` (register it as a PreToolUse hook on Bash) warns, never denies, on `gh pr merge` with no live order and none of his typed words naming that PR. *Warning only.*
+- **(c) An agent's "that is a person's call" is checked, not relayed.** Read what the person already decided (the record, the order's words) before asking or telling anyone it needs them. *Checked in code:* a final message that relays "a person's call" with no Read/Grep/Glob/Bash call in that turn is held at the Stop gate (words: `intents.toml` `[stop_gate] unchecked_words`).
+- **(d) Before saying something is gone or absent, read the code that writes it.** A missing file, row or log line is proof of nothing until you know what produces it and when. *Checked in code:* a final message that says something is gone, lost or absent, with no lookup in that turn, is held the same way.
+- **(e) A brief must not forbid the one action that clears the blocker.** Before sending a brief, check its banned-command list against the step the order needs. *Checked in code:* the routed hook warns when a brief's "do not / never" line shares a key word with an open order's blocker or fix.
+
+## 4. Live status and routed work
+
+`hubkit work add --kind active|tracked|priority --title "..." [--owner X]`, `hubkit work done <id> --note "..."`, `hubkit work ls`. The work file holds only live items; finished ones move to `archive/archive_<day>.jsonl`. `hubkit status` rebuilds the block. Before saying anything is pending on the user, section 5 applies.
+
+**Routed work is tracked automatically**, one outcome per (owner, PR number), by a hook on `SendMessage` and `Agent`. What counts, what does not and how a chase differs from a new ask are in `docs/architecture.md`. What you must know:
+
+- A message naming a PR, or a long one, or a background agent brief that asks for a result, opens an item. A later message to that owner is a chase: it counts (`chased Nx`) and never resets the ask's clock. **Only a new brief (`Done-when`, `Output`) is a new ask.**
+- A review item closes itself, PR by PR, when a non-author review lands at the PR's current head (on a PR written by `user.github_login`, a COMMENT review with a body counts); a review on an older head never closes it.
+- By hand: `hubkit work add --kind routed --owner X --title ".." --pr URL --head SHA`; close with `hubkit work done <id> --note ".."`. A question that really blocks ordered work: `hubkit work add --kind ask --title ".." --note ".."` (his card answer closes it).
+
+## 5. Before saying anything is pending on the user
+
+- Have an agent re-read the thread or PR now; the compaction summary and the watcher are not evidence.
+- Check the user's latest messages first. If they replied or acted, drop the item silently.
+- PR status comes from `gh` (head sha, last commit age, last review age), not from agent words. No movement for the kind's `stall_min` on an urgent order: chase the agent.
+- State the read time.
+
+## 6. Watchdog and stop gate
+
+Silence on routed work past `stall_min` (reviews: `review_stall_min`, hard `OVERDUE` at `review_overdue_min` from routing) climbs a ladder: step 1 a one-line state ask, step 2 a re-brief to another owner (never while the owner reported within the limit), step 3 tell the user. Every item shows one `NEXT:`; a chased item waits for the next step.
+
+**Wake-up.** The hub runs `hubkit watch --interval 120 --max-cycles 30` in the background (one at a time). It exits 0 printing `ALERT ..` on a new alert or a backed-off repeat, which wakes you; it exits 3 after its cycles, so re-arm it. Cron runs `hubkit tick --if-bound` as a backstop; overdue orders also reach the hub at its next prompt.
+
+**The Stop hook blocks the turn end** (JSON `decision: block`, shown to you) while: routed work is open and no watch runs; an item needs action; the message ends on a question to the user and no `hubkit work add --kind ask` item exists; or a sentence gives a verdict on a PR of a review item while GitHub shows no counting review at its head (non-author, or a COMMENT with a body on a PR written by `user.github_login`). Follow the `NEXT:` in the reason.
+
+`hubkit doctor` prints the bind, heartbeat ages (`seen/cron` is touched by every `tick`, so it tells a dead cron from an idle one), hook errors and a count of secret-shaped strings in state (never the strings).
+
+## 7. Reporting
+
+- At most 15 lines. Lead with what changed or what the user must decide. Tag claims verified / read / inferred. Full URLs. Times in the user's zone.
+- One line names what was left out and where it is. Input needed: the question tool after the report, recommended option first.
+- Hand over all PRs of a wave in one list, only when reviewed and ready.
+- Code or commands for the user go to a file, not a raw block (the overlay may name the clipboard step).
+
+## 8. End of day
+
+`hubkit eod [--note "<one self-improvement sentence>"]` writes `eod/eod_<day>.md` from the record, no model: the day at a glance (orders opened, closed, cancelled, held, open; chases per order; finished work; alerts; hook errors), a self-reflection (orders that needed a chase or are still open) and the learnings (new, repeated, addressed and holding, addressed but repeated, seen 2+ times and not addressed). Act on the last two the same day: promote the rule, add a check, then `learn.py address`. A repeat after `address` shows as regressed tomorrow. Combine with the user's own end-of-day skill if the overlay names one.
+
+## 9. Adaptive learning loop
+
+On every correction ("why did you...", "I told you...", a repeated instruction), the prompt hook injects a `CORRECTION` line with the quote. That turn:
+
+1. **Quote** the exact words.
+2. **Record** (a cheap agent runs it): `learn.py add --class <kebab> --gate <G1..G8> --quote "<words>" --situation "..." --wrong "..." --right "..." --evidence "<where>"`. Reuse an existing class for the same kind of mistake; a repeat appends a dated line.
+3. **Promote.** `learn.py promote-candidates` lists classes seen 2+ times. For each: `learn.py promote <class> --gate <G> --rule "<one short line>"` writes the rule into the overlay under its gate (personal rules stay out of this file), then `learn.py address --class <c> --how "..."`. `address` refuses unless the overlay or this file changed since the entry was last seen and holds a rule line tagged `[<class>]`.
+4. **Read** recent entries at session start and after compaction. The block shows at most five, only those seen in the last 30 days; an addressed class stays 14 days on probation, then drops.
+
+If a rule here contradicts what the user says now, their latest words win; fix the rule.
+
+## 10. Composition
+
+| Need | Hand off to |
+|---|---|
+| Notes, tickets, inbox, asks, the user's own list | `hub-mep` (optional, thin; routes to the mep skills) |
+| State across sessions, handover | the durable-notes skill named in the overlay |
+| Any question, approval or report to the user | the human-loop skill named in the overlay |
+| Release, hotfix, deploy | the release skills named in the overlay (the order's `dispatch` text names the entry point) |
+| Build, review, QA, long unattended run | peer sessions or skills named in the overlay |
+
+## 11. Configuration, redaction and install
+
+Everything personal is in `~/.config/hubkit/`: `config.toml` (names, zone, tools, paths, private terms), `intents.toml` (order words, clocks, evidence names), `overlay.md` (rules), `ext/*.py` (optional extensions). Keys: `docs/configuration.md`. This file and the scripts carry no personal names; `hubkit doctor --check-clean` checks that against `private.terms`.
+
+All state writes are redacted (8 token shapes, `key=value` secrets, long base64/hex runs). Natural-language secrets ("the password is hunter2") are not caught. State is in `$XDG_STATE_HOME/hubkit` (override `$HUBKIT_STATE`), refused if inside a git repo or this directory.
+
+**Install** (details in `README.md`): hooks in `~/.claude/settings.json` run `hubkit hook <session|prompt|answer|routed|stop|record>`; bind once per hub session with `hubkit bind` (interactive sessions only; liveness is pid plus process start time, so a crashed hub frees the bind, and a resumed hub session re-binds itself without ever taking over a live hub). Hooks no-op in every session that is not the live bound hub and in headless runs, always exit 0, and show or log errors only for the hub. If hubkit fails to import, the hook exits 0 and appends to `import-errors.log` in the state dir. Deny hooks are not part of this version.
+
+## Example
+
+User, to the hub: "hotfix the billing bug now, the fix is PR 41."
+
+1. The prompt hook prints `O-... hotfix [open] ... done needs: pr_merged,prod_live` and the dispatch text. The hub briefs a cheap agent: Task merge PR 41; Output at most 15 lines; Done-when merged; banned commands; never print secrets. No question back to the user (section 3).
+2. Merge done: `hubkit order move O-... --note "PR 41 merged"`. Deploy green: move again.
+3. `hubkit order close O-... --evidence pr_merged=https://github.com/acme/repo/pull/41 --evidence prod_live=file:/path/to/deploy.log`. If it is refused, the missing evidence is named; fetch it, do not claim done.
+4. The user says "I told you to tell me when it is live." The hook injects `CORRECTION`; the hub has a cheap agent run `learn.py add --class report-when-live --gate G7 --quote "I told you to tell me when it is live" ...`. Seen twice, it becomes a rule via `learn.py promote` and `learn.py address`.

hubcore/data/hub/config.example.toml

@@ -0,0 +1,84 @@
+# hubkit config. Copy to ~/.config/hubkit/config.toml (or set $HUBKIT_CONFIG).
+# Everything user-specific lives here, in intents.toml and in overlay.md. Nothing else.
+# Every key is optional; missing keys use the defaults in scripts/hubcore/config.py.
+
+[user]
+name = "Alex"                 # how the hub block names you
+timezone = "Europe/Berlin"    # IANA name; times are stored as epoch and shown in this zone
+github_login = ""             # your GitHub login: on PRs you wrote, a COMMENT review at the head counts (the reviewer peer posts as you)
+
+[hub]
+name = "hub"                  # names the hub in the status block; also the session name used to re-bind a resumed hub
+
+[paths]
+# state_dir      = ""         # default $XDG_STATE_HOME/hubkit. Must NOT be inside a git repo.
+# intents        = ""         # default <config dir>/intents.toml, else the skill's intents.example.toml
+# overlay        = ""         # default <config dir>/overlay.md (your personal rules; see SKILL.md)
+# learnings      = ""         # default <state dir>/learnings.md
+# sessions_dir   = "~/.claude/sessions"
+# transcripts_glob = "~/.claude/projects/*/*.jsonl"   # scanned for hook failures of our own hooks
+# extensions_dir = ""         # default <config dir>/ext (see Extension points)
+
+[tools]
+mep = "mep"                   # path or name of the miseenplace CLI
+notify_cmd = "notify-send -u critical -a hubkit"   # watchdog alerts: this command + message; "" = off
+
+[mep]
+# The optional `mep` task-list CLI. Set enabled = false if you do not use it.
+enabled = false               # default true
+timeout_s = 30                # default 30
+# data_dir = "~/Documents/mep-data"   # exported as MISEENPLACE_DIR for the adapter
+
+[watchdog]
+transcript_scan_hours = 24
+
+[stop_guard]
+# Log only. A final message ending in "?" or containing one of these, while an order is open,
+# writes a would_block row to <state>/stop-guard.jsonl. It never blocks.
+phrases = ["waits for your go", "say go", "want me to", "shall i"]
+
+[private]
+# Words that must never appear in the skill's own files (`hubkit doctor --check-clean`).
+# Keep your names, company and hosts here; this file stays on your machine.
+terms = []
+
+# Extension points (all optional):
+#   intents.toml   - add kinds (words, clocks, done_when evidence names, movement_files globs).
+#   ext/*.py       - in <config dir>/ext. Define any of:
+#                      status_lines(cfg) -> list[str]            extra lines in the status block
+#                      tick_checks(cfg, live_orders) -> list[{"key","msg"}]   extra watchdog alerts
+#   overlay.md     - free text rules that are yours: people, channels, accounts, repos, boxes.
+# Hooks (add to ~/.claude/settings.json; see the README "Hook setup"). Every key: docs/configuration.md.
+
+[slow]
+# Estimates and the slowness check (hub-internal). See docs/architecture.md.
+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          # 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
+
+[watcher]
+stuck_min = 30        # hub busy this long with live jobs = stuck
+unhandled_min = 10    # an alert this old and no hub heartbeat since = unhandled
+waiting_min = 3       # a peer waiting on a prompt this long = alert
+active_s = 120        # a busy holder whose transcript grew this recently is working
+watch_grace_min = 5   # live work with no watch running this long = alert
+notify_user = true    # platform default desktop notification for hub/peer alerts when notify_cmd is empty
+
+[routed]
+# repo_aliases = { fe = "owner/other-repo" }   # "fe 123" / "fe#123" name a PR in that repo, not the default one
+# Work the hub hands to peers/agents (SendMessage, Agent hooks). Also settable in intents.toml [routed].
+stall_min = 15            # nothing from the owner this long = STALLED
+review_words = ["review"] # items whose message/summary has one of these are reviews
+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"]   # never tracked
+min_chars = 200           # a message without a PR is work only from this length
+gh_timeout_s = 10
+queued_wait_min = 60      # work queued "after X" has no review clock until this long after the ask (or a review shows)
+reply_window_min = 60     # a hub reply to a peer that wrote this recently is not an ask
+repo = "owner/name"       # bare #N resolves against this
+owner_logins = {}         # owner name -> GitHub login, for peers who author PRs
+reviewer_logins = []      # empty = any non-author review counts
+skip_briefs = ["mep watch", "inbox watch"]  # standing watchers are never routed work

hubcore/data/hub/docs/architecture.md

@@ -0,0 +1,133 @@
+# Architecture
+
+hubkit is a set of Claude Code hooks plus a small CLI, all standard-library Python. Everything it knows is on disk in a state directory; the model is not trusted to remember.
+
+```
+ you (typed prompt, card answer)           peers / agents (SendMessage, Agent)
+          |                                              |
+          v                                              v
+   UserPromptSubmit hook                       PostToolUse hook "routed"
+   (prompt)  PostToolUse "answer"              (SendMessage|Agent)
+          |                                              |
+          v                                              v
+  +----------------+    opens/chases     +---------------------------+
+  |  orders.jsonl  |<--------------------|  work.json  (routed items) |
+  |  order ledger  |                     |  one per (owner, PR)       |
+  +-------+--------+                     +-------------+-------------+
+          |                                            |
+          |      +-------------------------------+     | gh reads: head, reviews
+          +----->|  tick / watch  (watchdog)     |<----+ transcript: last heard-from
+                 |  alerts.jsonl, status.json    |
+                 +---------------+---------------+
+                                 |
+          +----------------------+------------------------+
+          v                                               v
+   SessionStart / prompt hooks print                Stop hook = gate
+   the status block + OVERDUE / CORRECTION          blocks the turn end while the hub owes
+          |
+          v
+   hub session  --(learn.py add / promote / address)-->  learnings.md  --> overlay.md
+        ^                                                                       |
+        +----------------------- rules read at the next session ----------------+
+```
+
+## State and the bound hub
+
+State lives in `$HUBKIT_STATE`, else `$XDG_STATE_HOME/hubkit` (default `~/.local/state/hubkit`). It is refused when inside a git repository or the skill directory, so it is never committed. Files are append-only JSONL or written by atomic replace under an `flock`; every write goes through the redactor (`scripts/hubcore/redact.py`).
+
+`hubkit bind` records the hub as session id + pid + process start time (read from `/proc`), so a crashed hub frees the bind by itself. Every hook first asks `is_hub`: it is true only for the live, bound, interactive session. In any other session a hook prints nothing and exits 0. If hubkit fails to import, the hook exits 0 and appends to `import-errors.log`.
+
+## Hooks (`scripts/hubcore/hooks.py`)
+
+| Event | Hook | What it does |
+|---|---|---|
+| SessionStart | `session` | Prints the `hubkit:` status block. If the bind is dead and this session resumed the bound session id (or has the configured hub name in the bound cwd), re-binds and prints one line. Never takes over a live hub. |
+| UserPromptSubmit | `prompt` | Runs the intake on the typed prompt (see Orders), prints the order lines, `OVERDUE` clock breaches, the status block, and a `CORRECTION` line when the learn loop applies. |
+| PostToolUse `AskUserQuestion` | `answer` | A card answer goes through the same intake and human-only filter as a typed prompt, and closes `ask` work items. |
+| PostToolUse `SendMessage\|Agent` | `routed` | Records or refreshes a routed-work item (see Routed work). One `gh` baseline read per named PR, 3 s in total. |
+| Stop | `stop` | The gate. Prints JSON `{"decision": "block", "reason": ...}` while the hub owes something. |
+| PreToolUse `Bash` | `pretool` | Warn-only merge guard: `gh pr merge` with no live order and none of his typed words naming the PR adds a warning as additional context. Never denies. Register it yourself in `settings.json`. |
+| any | `record` | Schema canary. Every hub run writes the real payload's keys and value types (never values) to `payload-samples/`. |
+
+A hook failure is shown and logged (`hook-errors.jsonl`) only for the hub. The stop gate's own blocks are not counted as failures.
+
+## Orders (`orders.py`)
+
+An order is a row family in `orders.jsonl` (`open`, `move`, `hold`, `resume`, `cancel`, `chase`, `close`, `expire`), folded into one record per id. The kinds, their words, limits and `done_when` evidence names come from `intents.toml`.
+
+- **Intake.** Only human text counts: peer messages, task notifications and harness wrappers are filtered first (denylist of markers plus an `origin` check). A kind whose words match opens an order only from an imperative sentence (an `imperative` word present, not a question, not a `not_order_phrases` phrase). Otherwise the order is `unconfirmed`: no clock, expires after `unconfirmed_ttl_min` unless `hubkit order confirm`.
+- **Clock.** A first action is due within the kind's `first_action_min`; after that, movement (`order move`, or a touched `movement_files` glob) is due every `stall_min`. A deadline in the prompt ("in 30 min", "by 17:00") is parsed too.
+- **Holds.** Only explicit `hold_words` hold an order; `urgent_words` keep or restart the clock; `cancel_words` cancel. Long prompts (`verb_max_chars`) never hold or cancel.
+- **Chases.** A short prompt matching `intake.chase` while an order is open is recorded as a chase. Three chases print a stop-loss line.
+- **Close.** `order close` requires every evidence name the kind's `done_when` lists; `file:<path>` evidence must exist and be newer than the order. A closed order is archived under `archive/archive_<day>.jsonl`.
+
+## Routed work (`routed.py`)
+
+A routed item is one outcome per (owner, PR number), or per owner when no PR is named, in `work.json`.
+
+- **Tracked:** a message naming a PR (URL, `PR 12`, bare `#123` resolved against `routed.repo`) or at least `min_chars` characters, and background `Agent` launches whose brief asks for a result (`Done-when`, `Output`, a PR). **Not tracked:** acknowledgements, short messages without a PR, `skip_owners`, foreground agents, standing watchers (`skip_briefs`), and a reply to a peer who wrote to the hub within `reply_window_min`.
+- **Asks and chases.** Only a new brief is a new ask. Any later non-acknowledgement message to the same owner is a chase: it is counted, never resets the ask's clock, and clears a moved-head or old-head-verdict flag.
+- **Reviews.** A message naming a PR and a `review_words` word ("review #N", "needs a review", "can I get a review on #N") makes a review item, unless it opens with a change verb (fix, address, resolve, apply, ...) and the review word names an existing review ("fix the findings in his review of #N"), on a short clock (`review_stall_min`, hard `OVERDUE` at `review_overdue_min`). It closes itself, PR by PR, when GitHub shows a review by someone other than the author at the PR's current head (on a PR written by `user.github_login`, a COMMENT review with a body counts too, because the reviewer peer posts as that account; an empty-body COMMENT is an inline-thread reply and does not). A review on an older head never closes it. One PR per clock: a message naming several PRs is a queue; "after X's queue" phrasing delays the clock by `queued_wait_min`.
+- **Heard-from.** A peer message or task notification in the hub transcript, a review on the PR, or a background agent whose transcript or output file is still growing (`routed.activity_globs`) updates the last-heard time.
+- **Ladder.** Silence past `stall_min` climbs: step 1 a one-line state ask, step 2 a re-brief to another owner (not while the owner reported within the limit), step 3 tell the user. Every item shows one `NEXT:` action.
+
+## Watchdog (`status.py`)
+
+`hubkit tick` evaluates: no first action, no movement, passed deadline, unconfirmed expiry, a hold longer than `held_review_min`, routed-item ladders, hook failures found by scanning transcripts for failures of hubkit's own hooks, and extension checks. It repairs half-archived orders, rewrites `status.json`, appends `alerts.jsonl` with back-off (one alert per condition per order, repeats at 10, 20, 30 minutes) and runs `tools.notify_cmd`. It runs from cron (`--if-bound`) and inside `hubkit watch`.
+
+`hubkit watch` is the wake-up: the hub starts it in the background; it exits 0 printing `ALERT ...` on a new alert or backed-off repeat (which wakes an idle hub), and exits 3 after `--max-cycles` (re-arm it). A pidfile allows only one; a second exits 4.
+
+## Job records, estimates and the slowness check (`slow.py`)
+
+Internal to the hub; there is no report or verb for the user. Every live order and routed item has one record, rebuilt each tick into `status.json` and printed as one short `job ...` line in the `hubkit:` block (id, status, minutes in status / estimate, holder, and `SLOW: <why>` when over): the job, its status and when that status began, when it started, the estimate, the holder, and that it is not done.
+
+- **Estimate.** A routed item's brief may carry a line `Estimate: <n>m`. Without it the hook fills in the usual time for the item's step (review, fix push, work) and says `DEFAULTED` in its output. An order gets its estimate at its first `order move`. Estimates are kept as a list on the record (`estimates`); a new one is added beside the old (`hubkit work estimate`), so end of day can show estimate vs actual and how often a job was re-estimated.
+- **Usual time (baseline).** The median minutes per step over archived routed items and closed orders (`archive_*.jsonl`). With fewer than `slow.min_samples` samples it falls back to the configured stall limit (or `slow.order_default_min` for an order) and the line says `limit, N samples`.
+- **Overrun.** Time on the job (an order from its opening, a routed item from its start, a "hub pickup" from the owner's report) is past the estimate and past `slow.floor_min`. The tick adds one `SLOW <id> <step> <m>m, estimate <e>m; holder <h>; why: <signals>. NEXT: <action>` alert to the existing wake-up path. The why uses only real signals: the holder's session `status` and `waitingFor`, the oldest tool started and not yet answered and for how long, queued messages not yet taken, PR head movement, CI state (`gh`), and whether the session or agent transcript is alive. Only tool names, ids, times and queue operations are read from a transcript, never its text. With no signal the why says `unknown`. The alert key carries the cause, so it repeats only with the usual back-off or when the cause changes.
+- **Stop gate (the one exception to "the gate is unchanged").** A routed item or order with an estimate on record that is over it blocks the stop (`hubkit OVERRUN: SLOW ...`) until it is addressed: a chase to the holder, a re-brief of the same PRs to another owner, or `hubkit work estimate`. Items from before estimates existed alert but never block. A re-brief of an owner who reported within the limit is still advised against.
+- **End of day.** The self-reflection lists estimate vs actual per step and kind: count, mean estimate, mean actual, over-estimate count, re-estimates.
+
+## Watcher checks (`watcher.py`)
+
+Every tick (cron with `--if-bound`, or inside `hubkit watch`) also checks things outside the hub session, with live jobs as the trigger:
+
+- **Hub gone, stuck or not acting.** `hub:dead` (the bind is not a live process), `hub:stuck` (session `busy` longer than `watcher.stuck_min`), `hub:unhandled` (an alert older than `watcher.unhandled_min` and no hub heartbeat under `seen/` since).
+- **Peer waiting.** A session holding a live item whose `waitingFor` is set (or whose status is a waiting state) for `watcher.waiting_min` raises `peer:<name>:waiting` with the holder and the minutes.
+- **Watch and cron check each other.** A live job with no running watch raises `watch:dead` (the status block also tells the hub to re-arm it); a watch that finds `seen/cron` stale while the crontab runs hubkit raises `cron:dead`.
+- **Blockers.** An order's `block` record (on, fix, holder) turns a report into work: no fix or a stale fix alerts and gates the stop; only an `order result` clears it, and `order move` notes do not reset the idle clock of a blocked order. A new job sent to an owner who already holds one, while an order is open, prints a queue warning.
+- **Notification.** New alerts go to `tools.notify_cmd` when set. With none set, only `hub:*` and `peer:*` alerts use the platform default (`notify-send` on Linux, `osascript` on macOS, when installed). Nothing here ever posts to chat.
+- **False alarms.** A silent item is not a stall while it is `blocked_on` another live job (`hubkit work block`), or while its holder's session is `busy` and its transcript is still growing (for up to 3x the limit). A head moved by the owner's own newest commit is progress, not a moved head. Every stall alert names the holder's state (`holder: ...`).
+- **Short asks.** A short message to a peer is tracked when a request verb opens a sentence or it ends in a question; acknowledgements, status questions and thanks are not.
+- **PRs are keyed by repo and number.** `owner/repo#N`, a full URL, or `<alias> N` for a `routed.repo_aliases` entry name their repo; only a bare `#N` falls back to `routed.repo`.
+
+## Stop gate (`gate.py`)
+
+The Stop hook blocks the end of the turn, with the exact next action, while any of these holds:
+
+1. Routed work or an open order exists and no watch is running.
+2. A routed item needs action now (stalled, overdue, moved head).
+3. The final message gives a verdict on a PR of a review item while GitHub shows no counting review at its current head (a non-author review, or a COMMENT review with a body on a PR written by `user.github_login`). Awaiting wording ("waiting on the verdict") is not a verdict. Agent words are not evidence.
+4. A job with an estimate on record is past it and not yet addressed (see the slowness check).
+5. A blocker is not being solved (no fix running, fix past its limit), a STOP-LOSS has no result since, or the final message calls an open order blocked/down/failed/waiting while no order has a fix on record.
+6. The final message says done while his newest prompt is newer than the last `work done` and the last `hubkit asks ls`; or it calls something gone/lost/absent, or "a person's call", with no Read/Grep/Glob/Bash call in the turn (transcript read).
+7. The final message ends on a question (or holds a `stop_guard.phrases` phrase) and no `ask` work item says anything really waits on the user.
+
+## The learn loop
+
+This is the adaptive part. The mechanism, in the order it runs (`hooks.py`, `learnings.py`, `scripts/learn.py`):
+
+1. **Detect.** The prompt hook injects a `CORRECTION` line, with the quote, when a typed prompt matches a `[corrections] patterns` regex or repeats a recent prompt (word-set similarity at least `repeat_similarity` within `repeat_window_min`).
+2. **Record** (`learn.py add`). The hub records a class of mistake: kebab-case class, the gate it broke (G1 to G8 in SKILL.md), the exact quote, situation, wrong, right, evidence. A repeat of an existing class appends a dated `seen` line. Each entry stores a `basis` hash of the rule texts (overlay plus SKILL.md) at the time. Every field is redacted; edits are locked and atomic.
+3. **Promote** (`learn.py promote-candidates`, then `learn.py promote <class> --gate G --rule "..."`). A class seen two or more times is a candidate. Promoting writes one short rule line tagged `[<class>]` into your overlay under its gate. Personal rules stay out of the shared `SKILL.md`.
+4. **Address** (`learn.py address --class <c> --how "..."`). The class is marked fixed only if the rules changed since the entry was last seen **and** a rule line tagged `[<class>]` exists. Otherwise it is refused: a fix without a rule is not a fix.
+5. **Probation.** The status block shows at most five learnings seen in the last 30 days; an addressed class stays visible for 14 days as "probation". If the class is seen again after it was addressed, `hubkit eod` and `learn.py review` list it as regressed (a fix that did not work), and it is to be fixed the same day.
+
+hubkit does the detecting, storing, refusing and reporting; the hub model does the recording and the rule writing, so the loop only adapts as far as the hub follows it.
+
+## End of day (`hubkit eod`)
+
+Writes `eod/eod_<day>.md` from the record, with no model: orders opened, closed, cancelled, held and open; chases per order; finished work; alerts; hook errors; and the learnings between the archive and the new (new today, repeated, addressed and holding, addressed but repeated, seen twice and not addressed).
+
+## Extension points
+
+`<config dir>/ext/*.py` modules may define `status_lines(cfg) -> list[str]` (extra lines in the status block) and `tick_checks(cfg, live_orders) -> list[{"key", "msg"}]` (extra watchdog alerts). A broken extension is logged to `hook-errors.jsonl` and skipped.