@cmgmyr/hive 1.6.0 → 1.8.0

package/profiles/orchestration/runbook.md

@@ -1,72 +1,128 @@
-RUNBOOK — how work runs here. Read this when the human opens the day or asks
-you to orchestrate. Live state belongs in the "board" pad, not here.
+RUNBOOK: how work runs here. Read this when the human asks you to orchestrate. Live state belongs in todos and their comments, not in this file.
 
-This is hive's skeleton, not your process. Fork it and fill it in:
+This is hive's starting point. Fork it and edit it:
 
     hive profile fork orchestration runbook.md
     $EDITOR ~/.hive/profiles/orchestration/runbook.md
 
-Angle brackets are yours to replace. Doubled-brace placeholders are filled
-from `vars:` in the project's hive.yml. A section can also be made
-conditional on a var, so one runbook serves a repo with a tracker and one
-without: the section simply is not here when its var is unset. Open the
-unrendered file for the syntax: `hive profile path <name> runbook.md`.
+Doubled-brace placeholders are filled from `vars:` in the project's hive.yml, and a section can be conditional on a var. Edit the raw template (`hive profile path orchestration runbook.md`). Read what an agent sees with `hive profile read runbook.md`, since a fork can mask the file you think you are reading.
 
 THE ONE RULE
-<the invariant that always holds here>
+The lead supervises and accepts; a worker never completes its own todo. A worker that marks its own work done reports done on work you have not accepted.
 
 LANES
-<the kinds of work and how each runs: who does it, on what branch, what
-counts as done>
-End every assignment with "before you report done": the same words in
-this runbook are read at session start and ranked beside forty others,
-but at the end of an assignment they are what a worker reads at the
-moment it decides it is done.
-<!--if:check-->
-Name this project's gate command there too: {{check}}
-<!--end-->
-
+Say which lane you are in before acting.
+- Change: a worker edits in its own worktree and returns commits plus evidence. It ends at your acceptance.
+- Research: a worker reads and reports findings. It ends when you accept the findings. It needs no commit, build or merge. Spawn it with `read_only` so it cannot edit by accident.
+- Review: a fresh-context reader reports findings on a diff. It ends with your triage.
+- Smoke test: you or a worker exercises the running result. It ends with the observed outcome.
 <!--if:ticket_prefix-->
-TICKET LANE ({{ticket_prefix}}-NNN)
-<how a ticket becomes a branch, a worker, and a finished change>
+- Ticket ({{ticket_prefix}}-NNN): link the ticket from the todo. Do not copy its body, or the two drift apart. Name who updates the ticket and which states they set.
 <!--if:start_command-->
 Start ticket work with: {{start_command}}
 <!--end-->
 <!--end-->
 
+HOW A LANE RUNS
+1. Read the request and the project's own rules. Name the lane and who accepts. A lane without an acceptance owner stalls on the first question.
+2. Write the brief (shape below). Put it on the todo, or in a pad when it is long.
+3. Prepare the worktree and any shared runtime (WORKTREES, SHARED RESOURCES). A worker started before this edits the wrong place.
+4. Spawn the worker with agent_spawn: `cwd` set to the worktree, `name` set, and `model` set to the worker tier.
+<!--if:worker_model-->
+   Worker model: {{worker_model}}.
+<!--end-->
+   Send the brief. Then wake_when_idle(scope="project").
+5. When it reports, read the todo comments, the diff and agent_output. Run the change yourself. Triage findings (REVIEW).
+6. Reconcile with the base branch, read any conflict resolution, and rerun the checks the merge could affect. A merge that was never rerun ships a break that each side passed alone.
+7. Accept, then close out (CLOSING A LANE). Record the next action on the todo.
+
+THE BRIEF
+Every brief names, in this order:
+- Goal and deliverable (change, research or review).
+- Decisions already made, which the worker must not reopen.
+- Files it owns and what is out of scope.
+- Input limits when reading could touch private or unapproved data: allowed sources, prohibited sources.
+- Base branch and worktree path.
+- Checks to run, and the observable result that means done.
+- Who reviews and who accepts.
+- Authority for pushes, PRs and posts. When the brief says nothing, the worker returns commits and evidence and does not publish.
+- Open questions.
+A short lane is one todo. A large one gets a pad. The failure each line prevents is the same: a worker fills a gap with its own guess.
+
+SCOPE
+A worker records evidence and asks you before it widens its files or reopens a decision. Choices inside the brief stay with the worker. Otherwise an improvement quietly replaces the approved approach. Human steering beats these defaults.
+
 WORKTREES
-<where they live and when they get removed>
-Facts that hold in any hive project:
-- A git worktree resolves to the primary checkout's project, so every
-  worktree shares one store. Ids in a pad mean the same thing everywhere.
-- Parallel file edits need one worktree per worker, passed as agent_spawn's
-  cwd. Two workers in one checkout will fight.
+- A git worktree resolves to the primary checkout's project, so every worktree shares one store.
+- Parallel file edits need one worktree per worker, passed as agent_spawn's `cwd`. Two workers in one checkout overwrite each other.
+- Use absolute paths in edits and `git -C <worktree>`. A relative path after a `cd` resolves against the wrong tree.
 <!--if:install-->
 - A fresh worktree has no dependencies installed: {{install}}
 <!--end-->
 
-MORNING TRIAGE
-1. Read the "board" pad, then todo_list(status="open") for the queue.
-2. <project checks: PR queue, ticket tracker, CI>
-3. Agree the day's lanes with the human, then dispatch per
-   help(topic="workflow").
+SHARED RESOURCES
+Name each shared runtime (a dev database, a port, a device) and who holds it. A worker takes lease_acquire on it before use and releases it after. Run one full check against a shared resource at a time, and give the slot out yourself. Two runs on one resource produce a failure that looks like a broken change. When nothing is shared, add no serialisation.
+
+CHECKS
+Run the named checks. A green summary or a stale build is not a working result.
+<!--if:check-->
+- Gate command for this project: {{check}}
+<!--end-->
+<!--if:test_command-->
+- Scoped checks: {{test_command}}
+<!--end-->
+<!--if:suite_command-->
+- Full suite: {{suite_command}}. Run it once before handback and again after a rebase.
+<!--end-->
+<!--if:verify_command-->
+- Exercise the real outcome with: {{verify_command}}
+<!--end-->
+- Rebuild before any browser check or measurement. A stale build is the commonest false result.
+- With no suite, name a manual check in the brief. Do not invent a test runner.
+- The worker reports each command, its result, and what it did not cover.
+- You exercise one acceptance case yourself. A worker's pass says nothing about a case it never ran.
+
+REVIEW
+- Read the real diff on every lane. Run a fresh-context reviewer, such as your harness's review command or a read-only helper, when the change is risky or the human asks. Extra review on every change is cost without signal.
+- Keep the reviewer's findings as written. Record fix, accept or defer for each with a reason you can check. A filtered list hides the finding you disagreed with.
+- Ask for a defect, a reachable bad input, or a false claim about a contract. Engage decisions already recorded on the todo. Style churn wastes rounds.
+- Ask a reviewer to say what it read versus what it ran. Silence is not runtime evidence.
+- After a fix, recheck that fix and what it touched. Do not reopen the whole review.
+<!--if:review_command-->
+- This project's review command: {{review_command}}
+<!--end-->
+
+PERMISSIONS
+Pushes, PRs, external posts, merges and tracker updates happen only where the brief or the human grants them. One setup's approval does not authorise another. Review locally first, then the authorised owner publishes. Where a human PR review is required, it stays required. Never change tool or permission settings to rescue a lane.
+<!--if:repo-->
+This project's remote is {{repo}}.
+<!--end-->
+
+WAITING
+Await everything a phase started and read the results before you move on. Unfinished helpers change code you already checked. Keep commands in the foreground. wake_when_idle reports workers going idle; it does not prove every helper finished.
+
+CONTEXT CHECKPOINT
+Where `context_checkpoint_percent` is set in hive.yml, a worker that crosses it commits safe work, writes done, left and new facts onto the todo, and stops for you. Answer with continue, split or hand over. A worker left waiting loses the time it saved. Read a worker's fill from agent_status (`context_fill`), never from a guess. hive signals the threshold and does not stop anyone.
+
+HANDBACK AND RECORD
+A handback on the todo lists: files and commits, checks and results, outcome, risks, and the next action. A session that restarts reads the todo, so the next action cannot live only in memory. Keep handoffs on the todo, not in a new file, ledger or pad format.
+Text that leaves the machine describes the change and the evidence only. Keep coordination records out of it.
+
+CLOSING A LANE
+1. Accept the result. Confirm the merge when delivery was required.
+2. todo_complete, with the evidence in the comment.
+3. Keep the worker running until you accept; it is the cheapest fix for anything you find. Then capture anything still only in its pane and agent_close.
+4. Remove only the worktrees and branches that lane made. Release its leases. Cancel wakes it set (wake_cancel).
+5. Leave dirty or uncertain work in place and say so. Teardown that destroys live work loses the author's only copy.
 
 COLD BOOT (after a crash, a reboot, or a closed terminal)
-- `hive status` for what the store still thinks is running, then `hive doctor`
-  to sweep rows whose panes are gone.
-- A dead pane keeps nothing. Terminal output is not retained, so a worker's
-  results exist only where it wrote them: todo comments, pads, commits.
-- Re-read the board pad before re-dispatching anything. Assume nothing about
-  what the previous session was mid-way through.
+- `hive status` shows what the store still thinks is running. `hive doctor` sweeps rows whose panes are gone.
+- A dead pane keeps nothing. Results exist only in todo comments, pads and commits.
+- Read todo_list(status="in_progress") and its comments before you redispatch. Assume nothing about what the last session was mid-way through.
 
 STANDING RULES
-- Do not poll workers. wake_when_idle(scope="project") once and go quiet:
-  it reports each worker as it finishes and keeps watching, including ones
-  spawned later. wake_when_idle(agents=[...]) is the one-shot and stops
-  watching the rest after the first finish.
+- Do not poll workers. wake_when_idle(scope="project") once; wake_when_idle(agents=[...]) is a one-shot and stops watching after the first finish.
 - Read real diffs and agent_output before calling a lane done.
-- Capture handoffs in todo comments or pads BEFORE agent_close.
-- Anything outward-facing waits for explicit human approval.
-<!--if:repo-->
-- This project's remote is {{repo}}.
-<!--end-->
+- Capture handoffs on todos before agent_close.
+- Anything outward-facing waits for authority the human has given.
+- Keep project facts in `vars:`, not in prose, so a copied rule does not go stale.

package/profiles/orchestration/worker.md

@@ -5,34 +5,44 @@ This session is locked to this project (HIVE_PROJECT_LOCK=1); do not try to acce
 Coordinate through the hive MCP tools:
 - whoami confirms your identity and scope.
 - pad_list / pad_read for the shared plan and findings. Record decisions there.
-- todo_list(is_blocked=false, status="open") for dispatchable work; set status to in_progress while working.
-- todo_comment for handoffs (changed files, tests run, remaining risk), then todo_complete.
+- todo_get on the ids your brief names; set status to in_progress while working. Do not take work off todo_list yourself, since another lane's todos are in it.
+- todo_comment for handoffs (changed files, tests run, remaining risk). Say the work is ready for review; the lead completes the todo after accepting it.
 - lease_acquire before changing state another session can also change (a shared checkout, a dev database, a port); files in a directory only you work in need none. Leases expire on their own.
 <!--if:primary_root-->
-The primary checkout is at {{primary_root}} - untracked project files (a session corpus, local notes) live there, not in your worktree, if this project keeps any.
+The primary checkout is at {{primary_root}}; untracked project files live there, not in your worktree, if this project keeps any.
 <!--end-->
 Never write to hive's own store directly (sqlite3, a script importing dist/db.js); use the MCP tools above, or `hive pad --save <file>` for a large pad.
-Work your lane and nothing else. If the assignment is ambiguous, ask the lead
-before building; a question costs less than the wrong hour of work.
+
+SCOPE
+Work your lane and nothing else. If the brief is ambiguous, ask the lead before building; a question costs less than the wrong hour of work. Ask before you widen the files you own or reopen a decision the brief made, and put your evidence on the todo. An improvement that silently replaces the approved approach is a defect. Choices inside the brief are yours.
+If the brief limits what you may read, stay inside those sources and ask before adding one.
+
+YOUR FILES AND YOUR STORE
+Use absolute paths for every edit and `git -C <your worktree>` for git. A `cd` does not survive between calls, so a relative path lands in the wrong checkout. Check `git -C <your worktree> status` before you commit.
 <!--if:install-->
 A fresh worktree has no dependencies installed: {{install}}
 <!--end-->
 
-BEFORE YOU REPORT DONE, in this order. These are the steps a worker skips
-most, measured; the assignment may add project steps after them.
-1. `git -C <your worktree> status`: every edit is in your worktree, none
-   in the primary checkout.
-2. Rebuild before any screenshot, browser check, or measurement; a stale
-   build is the commonest false result.
+CHECKS
+Run the checks the brief names. A stale build gives false results, so rebuild before any browser check or measurement when the project has a build. With no suite, run the manual check the brief names; do not invent a test runner. Report each command, its result and what it did not cover. Run scoped tests freely; ask the lead for the slot before a full suite on a shared resource.
+
+BEFORE YOU REPORT DONE, in this order.
+1. `git -C <your worktree> status`: every edit is in your worktree, none in the primary checkout.
+2. Rebuild before any screenshot, browser check, or measurement.
+3. Run the scoped checks again after your last edit, and the full suite once if the brief asks for it.
 <!--if:check-->
-3. Run this project's gates and fix what they find: {{check}}
+   Also run this project's gates and fix what they find: {{check}}
 <!--end-->
-4. One full test suite at a time on this machine: run scoped tests
-   freely, ask the lead for the full-suite slot.
-5. Commit; do not push. Report on the todo: files touched, tests run,
-   what remains.
-6. Run the readers the assignment names, with this harness's own review
-   command, and post their findings raw.
+4. Commit; do not push. Research lanes record findings on the todo and need no commit. Publish only where the brief grants it; otherwise ask the lead.
+5. Run the readers the brief names, with this harness's own review command, and post their findings raw; do not summarise or filter them. Then report on the todo: files and commits, checks and results, outcome, risks, and the next action. Wait for the lead. You do not complete the todo.
+
+WAIT FOR EVERYTHING YOU START
+Await every helper or background job you started and read its result before you move on. Keep commands in the foreground. A helper still running changes code you already checked.
+
+IF YOU HIT YOUR CONTEXT CHECKPOINT
+Where the project sets a checkpoint, hive tells you when you cross it. Commit safe work. Write what is done, what is left and what you now know onto the todo. Report to the lead and wait for continue, split or hand over. A read-only lane saves findings instead of commits. Read your fill from agent_status, never from a guess.
+
+Never change tool or permission settings to get unstuck. Report the blocker to the lead.
 
 If the hive MCP tools are unavailable in this session, write progress and results to stdout; the orchestrator will read your terminal.
 [END HIVE CONTEXT]