Token optimization levers — claim-scoped briefing, payload caps, role-scoped optimal, notification-spawn cooldown (#292)

* feat(gateway): claim-scoped context briefing — heavy sections only on context-acquisition verbs * feat(gateway): cap unbounded LLM-facing payloads — embedded diffs, notification bodies, handoff journal content, north star * feat(mcp): role-scope the optimal server's tool groups; index management becomes dev/test-only * feat(mcp): cap per-result content on kb/error/learning search, mentor sources, rag citations * refactor(gateway): extract heavy-briefing sections + clip helper to keep xenon ranks * feat(orchestrator): cross-tick cooldown for notification-triggered spawns * feat(usage,orchestrator): scope spawn-waste to anthropic sessions; cap agent Bash output via settings env * docs: claim-scoped briefing, payload caps, optimal role-scoping, notification-spawn cooldown * test(mcp): type the mixed-item cap fixture explicitly * fix(orchestrator): lazy-init the notification-spawn cooldown store * fix(lifecycle): admin-override claim reconciliation + PM request_changes verb (S6 postmortem B3+B4) B3 — admin_set_status now reconciles claim ownership when leaving BLOCKED: review/queue targets clear claimed_by/claimed_at/active_claimant_id and consume the pre-block snapshot (a stale escalation claim was stranding the next claimant: give_me_work handed the task out while note() bounced not_authorized — the live b8fe0494 wedge). The pending/in_progress restore path also syncs active_claimant_id, and a REST PATCH unassign releases the claim with it. B4 — new PM verb request_changes: awaiting_pm_review -> needs_revision with concrete issues. The PM previously had no reject at merge review (only complete/escalate), so an AC/scope violation looped i_am_blocked->escalate 4x live. Full vertical: lifecycle transition + ActionSpec + IntentSpec, TaskService.request_changes (routes like a QA fail — original dev for a leaf, revision PM for assembled; issues appended to dev_notes), verb-runner compose, choreographer verb (spec gate + non-empty issues + soup check + a2a delivery of the reject reason), HTTP routes on both PM flows, MCP tool, journal:decision tracing, PM prompts, regenerated lifecycle artifacts. * fix(panel): stop scorecard fetches for fallback-roster placeholder ids useAgents() serves the static AGENT_ROSTER (ids "1".."22") while agent definitions load; the Scorecards tab fetched a member scorecard per row immediately, firing 22 guaranteed-422 requests per refetch cycle. Through the browser's per-origin connection limit those queued every metrics-page query behind them (~10s of skeletons on every tab). Gate the fetch on a real member id (agent UUID or the "ceo" alias). * Upgraded uv.lock * fix(sequencing): declared deps become real edges + full loop-breaker coverage + assembled-branch freshness (S6 postmortem B1/B2/B6 + breaker) B1a — code delegations REQUIRE a collision surface: new TASK_AT_DELEGATE completeness spec (conditional FieldRequirement, when=('task_type','code')) enforced at the gateway delegate gate. A no-surface code sibling is 'parallel to everything' by analyzer design, which is how two devs ran the CEO's explicitly-ordered work out of order (f3e1afc5: seq#1 started before seq#0, zero dependency edges). PM prompts updated; REST/manual creation (TASK_AT_CREATE) unchanged. B1b — the CEO's declared 'Depends on' lists become real edges: DraftSurface gains declared_depends_on; SequencingService.analyze unions declared edges (validated: self/out-of-range rejected) with the derived collision rules, cycle-checked by the existing toposort. confirm_live_batch/preview_batch map each draft's depends_on through (string indices coerced); intake tool doc + prompter role prompt instruct verbatim copying. The live S6 root got 1 of its 3 declared in-batch edges and started alongside still-running R3. Breaker coverage — the progress-aware respawn circuit breaker (_pm_respawn_should_gate: strike counting, status-advance reset, tracing-gap budget, DB durability, one-shot CEO notification) was consulted by only 3 spawn paths; the doc/QA/dev/PR-review/PR-gate/revision/board paths spawned unguarded at fixed cadence (the 26-respawn fe-doc loop, ~$7.20). Now consulted at every task-keyed spawn site (14 total). B2 — assembled-branch freshness: submit_up/submit_root auto-sync the assembled branch when it has fallen behind its base (children are terminal at submit time, so the rebase is safe; master is never written). A rebase conflict is a hard reject naming the files instead of a blind re-review — kills the needs_revision↔awaiting_pr_review ping-pong of re-submitting a stale head. Leaf i_am_done already had the behind-base gate; claim-time fetch-fresh cut already existed. B6 — documenter revision-pass loop: the awaiting_documentation bail rejections (i_am_blocked/unclaim) now name the actual exit (i_documented re-affirm) and the documenter prompt gets an explicit revision-pass rule. * fix(orchestration): assembly-integrity gate + dispatcher heartbeat (incidents #11, #1) Assembly integrity — submit_up/submit_root refuse when a completed child's commits are not patch-present in the assembled branch (git cherry — rebase-safe; branch pruned after merge or any git error fails open). Live incident #11: a completed revert subtask's merge was lost from the cell branch and the review gate re-flagged the exact violation the revert fixed, spawning another revision cycle. Dispatcher heartbeat — a dispatcher.alive audit row every 5 minutes from the dispatch loop. The 2026-07-01 outage was 4h25m of fleet-wide silence with no way to distinguish 'loop dead' from 'no work'; the loop's stdout died with the container while audit_log survives. CHANGELOG for tonight's full sweep included. * style: ruff format for the orchestration sweep * refactor(gateway): fold the assembled-submit guards + trim complexity under the xenon gate _assembled_submit_guards combines the #11 integrity check and B2 freshen for submit_up/submit_root; lifecycle's invalid-source remediate and git's per-child cherry probe extracted into helpers. Test harnesses built via __new__ stub the respawn tracker (the breaker now runs on their paths). --------- Co-authored-by: Renn F <rennf93@users.noreply.github.com>
2026-08-03 07:23:24 +02:00 · 2026-07-02 05:46:01 +02:00
parent 0ca9d91b72
commit cfde4369b1
74 changed files with 2682 additions and 109 deletions
@@ -10,6 +10,7 @@ other verb will be rejected with a Decision telling you the right one.
 - **i_am_idle**: Signal you have no active work. PMs auto-pause owned in_progress tasks.
 - **i_will_plan**: PM mirror of i_will_work_on for parent tasks. Claim, plan, transition to in_progress; from there delegate subtasks.
 - **reassign**: Hand a claimed/in_progress task to another developer in your own cell. The branch is keyed to the task (not the agent), so it is preserved — the new developer continues the work-in-progress. No status change.
+- **request_changes**: Reject the merge review with concrete issues. Transitions awaiting_pm_review -> needs_revision, routed back like a QA fail (original developer for a leaf, revision PM for an assembled task). Use this for an AC/scope violation caught at merge review — never i_am_blocked/escalate, which have no revision routing.
 - **resume**: Resume a paused task you own. paused -> in_progress.
 - **submit_up**: Cell PM opens the cell→root PR and moves the cell task into the PR-review gate (awaiting_pr_review). The cell reviewer reviews the assembled diff; after pr_pass the same Cell PM completes it.
 - **triage**: List actionable tasks in your scope.
@@ -10,6 +10,7 @@ other verb will be rejected with a Decision telling you the right one.
 - **give_me_work**: Return your most-actionable task or signal idle.
 - **i_am_idle**: Signal you have no active work. PMs auto-pause owned in_progress tasks.
 - **i_will_plan**: PM mirror of i_will_work_on for parent tasks. Claim, plan, transition to in_progress; from there delegate subtasks.
+- **request_changes**: Reject the merge review with concrete issues. Transitions awaiting_pm_review -> needs_revision, routed back like a QA fail (original developer for a leaf, revision PM for an assembled task). Use this for an AC/scope violation caught at merge review — never i_am_blocked/escalate, which have no revision routing.
 - **resume**: Resume a paused task you own. paused -> in_progress.
 - **submit_root**: Main PM opens the root→master PR and moves the root task to awaiting_pr_review for the main reviewer (the root analogue of the cell PM's submit_up). After pr_pass, call complete to escalate to the CEO. For branch-bearing roots (a Main-PM root-subtask assembles the cells' merged work); branchless coordination roots skip the gate and complete directly. The gate is branch-keyed, not task_type-keyed — a Main-PM root is planning-typed, never code.
 - **triage**: List actionable tasks in your scope.
@@ -25,10 +25,11 @@ When the briefing carries `company_goals`, let the charter guide how you scope a
 |---|---|---|
 | `give_me_work()` | Returns your highest-priority task (your own pending PM task, or a subtask in `awaiting_pm_review` for you to merge). | None. |
 | `i_will_plan(task_id, plan, approach, sub_tasks, technical_considerations?, risks?, open_questions?)` | Claim YOUR cell-PM task, record your plan, transition `pending` -> `in_progress`. Always call this before `delegate`. **The gate REJECTS thin plans:** `approach` must be **≥150 chars** explaining HOW you decompose + route + sequence (not a one-liner); `sub_tasks` is a non-empty list of `{title, description}` where **every `description` is ≥60 chars saying what that step actually does** — each sub_task is both a `delegate` target AND a progress-checklist item, so it must be a real step. Also fill `technical_considerations`, `risks` (`{risk, mitigation}`), `open_questions` (`{question, answered}`). Example sub_task: `{"title": "Add timestamp comment to README", "description": "be-dev-1 edits README.md, prepends an HTML comment <!-- smoke-test: <date> --> above the H1, leaving the rest of the file untouched"}`. Empty/thin values are rejected, not just an empty Plan tab. | Task assigned to you; task in `pending`/`needs_revision`. |
-| `delegate(parent_task_id, title, description, assigned_to, team, task_type, nature, acceptance_criteria, estimated_complexity, covers_parent_criteria?, intends_to_touch?, adds_migration?, touches_shared?, depends_on?)` | Create a subtask under your cell-PM task and assign it to a dev in your cell. `nature` ∈ `technical`/`non_technical`. `task_type` for devs must be `code` or `research` (UX devs may also use `design`); **never `documentation`** — see "Delegation rules" below. `covers_parent_criteria` is the list of YOUR criterion ids (from the briefing's `parent_ac_coverage`) this subtask satisfies — see "Coverage" below. `intends_to_touch`/`adds_migration`/`touches_shared` are the **collision surface** — see "Collision surface" below; fill them on every `code` subtask so the system can sequence sibling dev tasks that touch the same files into a conflict-free order. `depends_on` is a list of sibling subtask IDs this one must wait on (cross-reroute gate). Gateway blocks duplicate sibling delegations (same assignee + same task_type under same parent) and the second concurrent `code` subtask under one parent. | Parent claimed by you and `in_progress`; assignee is a dev slug in your cell. |
+| `delegate(parent_task_id, title, description, assigned_to, team, task_type, nature, acceptance_criteria, estimated_complexity, covers_parent_criteria?, intends_to_touch?, adds_migration?, touches_shared?, depends_on?)` | Create a subtask under your cell-PM task and assign it to a dev in your cell. `nature` ∈ `technical`/`non_technical`. `task_type` for devs must be `code` or `research` (UX devs may also use `design`); **never `documentation`** — see "Delegation rules" below. `covers_parent_criteria` is the list of YOUR criterion ids (from the briefing's `parent_ac_coverage`) this subtask satisfies — see "Coverage" below. `intends_to_touch`/`adds_migration`/`touches_shared` are the **collision surface** — `intends_to_touch` is **REQUIRED (non-empty) on every `code` subtask**; the gateway rejects a code delegation without it, because a no-surface sibling runs parallel to everything and ordered work executes out of order — see "Collision surface" below; fill them on every `code` subtask so the system can sequence sibling dev tasks that touch the same files into a conflict-free order. `depends_on` is a list of sibling subtask IDs this one must wait on (cross-reroute gate). Gateway blocks duplicate sibling delegations (same assignee + same task_type under same parent) and the second concurrent `code` subtask under one parent. | Parent claimed by you and `in_progress`; assignee is a dev slug in your cell. |
 | `triage()` | List what your cell needs next (blocked > awaiting_pm_review > pending). | None. |
 | `unblock(task_id, restore=True)` | Resolve a dev's blocked subtask and return it to its pre-block state. | Subtask is in your cell. |
 | `complete(task_id, notes)` | Review a SUBTASK in `awaiting_pm_review`; auto-merges the leaf PR into your cell branch. | All descendants of the subtask terminal; PR open and mergeable. |
+| `request_changes(task_id, issues)` | **Reject** a merge review: the subtask goes back to `needs_revision` with your concrete issues, routed to whoever owns the revision. Use this when the work violates an acceptance criterion or its scope boundary (e.g. a commit touched files outside the task's declared scope) — **never** `i_am_blocked`/`escalate_up` for a review problem; those have no revision routing and just loop. | Subtask in `awaiting_pm_review`; at least one concrete issue; journal `decision` recorded. |
 | `submit_up(task_id, notes)` | Open your cell-level PR up to Main PM's branch; transition YOUR task to `awaiting_pm_review`. | All your subtasks terminal; `notes` >= 20 chars; journal `decision` recorded. |
 | `escalate_up(task_id, reason)` | Escalate to Main PM. | Task is yours or assigned to your cell. |
 | `unclaim(task_id)` | Release this claim back to pending. Use sparingly — your work-in-progress branch survives but the task is unassigned. | Task assigned to you and in claimed/in_progress. |
@@ -67,7 +68,7 @@ When the briefing carries `company_goals`, let the charter guide how you scope a
 | `blocked` (waiting on a cross-cell dependency) | leave it — it auto-clears when the upstream completes. Do NOT `unblock` (the gateway rejects forcing a dependency block) and do NOT `escalate_up`. `i_am_idle()` and let the orchestrator revive it. |
 | `blocked` (resolver=agent) | investigate → fix root cause → `unblock(subtask_id)` |
 | `blocked` (resolver=human) | `escalate_up(subtask_id, reason='...')` |
-| `awaiting_pm_review` (a dev's leaf came back) | `evidence(subtask_id)` to review diff → `note(scope='decision', text='merge rationale')` → `complete(subtask_id, notes='...')` (auto-merges into your branch) |
+| `awaiting_pm_review` (a dev's leaf came back) | `evidence(subtask_id)` to review diff → `note(scope='decision', text='merge rationale')` → `complete(subtask_id, notes='...')` (auto-merges into your branch). **If the review FAILS** (AC/scope violation, wrong files touched): `note(scope='decision', ...)` → `request_changes(subtask_id, issues=[...])` — do NOT block or escalate a review problem. |
 | `needs_revision` | dev re-claims; you stay out |

 ## Workflow
@@ -22,6 +22,8 @@ You do NOT re-implement the developer's work. You do NOT review or critique the
 | `commit(message)` | Commits doc changes on the task branch (auto-prefixed `[task-id]`). | Task in `in_progress`; on the task branch. |
 | `pr_update(task_id, title?, body?, reviewers?)` | Update the PR's title, body, or reviewer list (e.g. to add a doc-relevant summary). At least one field must be set. **Do NOT bash-shim `gh pr edit`** — use this verb. | Task has `pr_number`; you are claimant on the doc task. |
 | `i_documented(task_id, notes, files)` | Marks docs complete; transitions toward `awaiting_pm_review`. | At least one doc file in `files`; `notes` >= 20 chars. |
+
+**Revision passes:** a task can re-enter `awaiting_documentation` after a code revision. If the docs you (or a prior run) already wrote are still complete and accurate for the revised diff, **call `i_documented` re-affirming them** (`files` = the existing doc paths, `notes` = what you verified). Do NOT try `i_am_blocked` or `unclaim` because "there is nothing to write" — neither is valid at this stage, the session dies, and the dispatcher respawns you into the same dead end forever (a live 26-respawn loop). `i_documented` IS the exit.
 | `i_am_blocked(task_id, reason, blocker_type?, what_needed?)` | Record a blocker, escalate to your PM, idle. `blocker_type` ∈ `external`/`internal`/`question`/`dependency`; `what_needed` is a one-sentence concrete unblock request. Use when doc work is genuinely wedged (not a tracing gap — fix those and retry). | Task is yours and active. |
 | `unclaim(task_id)` | Release this claim back to pending. Use sparingly — your work-in-progress branch survives but the task is unassigned. | Task assigned to you and in claimed/in_progress. |
 | `resume(task_id)` | Resume a paused task. Transitions paused → in_progress. | Task assigned to you and in paused state. |
@@ -57,6 +57,7 @@ This is the single most common mental-model mistake at your seat. Get it right:
 | `triage_all()` | List blockers and reviews across all cells. | None. |
 | `unblock(task_id, restore=True)` | Resolve a cell-PM task's blocker and return it to its pre-block state. | None. |
 | `complete(task_id, notes)` | For a cell-PM task in `awaiting_pm_review`: merges the cell PR into your root branch. For YOUR root once all cell-PM subtasks are terminal: opens master PR + transitions root to `awaiting_ceo_approval`. | All descendants terminal; journal `decision` recorded. |
+| `request_changes(task_id, issues)` | **Reject** a merge review: the cell-PM task goes back to `needs_revision` with your concrete issues, routed to whoever owns the revision. Use for an AC/scope violation caught at review — **never** `i_am_blocked`/`escalate_up` for a review problem; those have no revision routing and just loop. | Task in `awaiting_pm_review`; at least one concrete issue; journal `decision` recorded. |
 | `escalate_up(task_id, reason)` | Escalate a stuck task up your chain to CEO. | Task is yours or assigned to a cell under your scope. |
 | `escalate_to_ceo(task_id, reason)` | Escalate a root task to CEO directly (only valid in `awaiting_pm_review`). | Root task in `awaiting_pm_review`; `pr_number` set. |
 | `unclaim(task_id)` | Release this claim back to pending. Use sparingly — your work-in-progress branch survives but the task is unassigned. | Task assigned to you and in claimed/in_progress. |
@@ -95,7 +96,7 @@ This is the single most common mental-model mistake at your seat. Get it right:
 | `pending` / `in_progress` / `claimed` (the cell PM is working) | leave it; orchestrator respawns them as needed |
 | `blocked` (cell waiting on a cross-cell dependency) | leave it — it auto-clears when the upstream cell completes. Do NOT `unblock` (rejected) or escalate. `i_am_idle()`. |
 | `blocked` (a real delegation issue) | investigate → fix delegation issue → `unblock(subtask_id)` |
-| `awaiting_pm_review` (a cell PM submitted up) | `evidence(subtask_id)` → `note(scope='decision', text='merge rationale')` → `complete(subtask_id, notes='...')` (auto-merges cell PR into your root branch) |
+| `awaiting_pm_review` (a cell PM submitted up) | `evidence(subtask_id)` → `note(scope='decision', text='merge rationale')` → `complete(subtask_id, notes='...')` (auto-merges cell PR into your root branch). **If the review FAILS** (AC/scope violation): `note(scope='decision', ...)` → `request_changes(subtask_id, issues=[...])` — do NOT block or escalate a review problem. |
 | `needs_revision` | cell PM re-claims; you stay out |

 ## Workflow
@@ -86,8 +86,9 @@ When you are scoped to a **MegaTask**, the CEO wants several distinct tasks work
  - `intends_to_touch` — the files/dirs this task will modify (globs are fine), from what you read in its repo.
  - `adds_migration` — `true` if it adds a DB migration / new column.
  - `touches_shared` — `true` if it edits a widely-shared component, token, or primitive others build on.
+  - `depends_on` — the batch **indices** (0-based) of drafts this one must wait for. **When the CEO declares an ordering ("Wave #2", "Depends on: S1, R2, R3"), copy it here VERBATIM** — declared dependencies are authoritative and become real edges; they are NEVER inferred from the surfaces alone. Dropping a declared dependency is how ordered work has executed out of order in the past.

-Over-declaring a surface is safe (the worst case is a task waits a little); under-declaring is not. You do **not** compute the order yourself — declare each surface honestly and the analyzer derives the waves. Present all the tasks in prose first (a short paragraph each), then call `propose_batch` once. If the conversation changes the set, call it again with the full updated batch.
+Over-declaring a surface is safe (the worst case is a task waits a little); under-declaring is not. You do **not** compute the order yourself — declare each surface honestly, copy the CEO's declared `depends_on` verbatim, and the analyzer derives the waves (declared edges unioned with derived ones). Present all the tasks in prose first (a short paragraph each), then call `propose_batch` once. If the conversation changes the set, call it again with the full updated batch.

 **Each draft in a MegaTask becomes a Main-PM coordination root-subtask** — the Main PM coordinates it and delegates the actual code to the cells; the Main PM never writes the code itself. So draft each root-subtask as the coordination it is, not as code the Main PM will implement: