f48d088c08
A live task burned 5+ hours because every exit was locked. unclaim now works from verifying and needs_revision (service guard + lifecycle edge); the circuit breaker and the i_am_done push-failure remediate name the working chain ending in unclaim(); sync_branch(stash=true) clears the DIRTY_WORKSPACE dead-end (pop-conflict preserves the stash); blocking a task QA already owns now says to idle instead of listing states; the orchestrator auto-block logs real errors and skips states where blocking is meaningless instead of force-blocking them. declare_coverage (cell/main PM) retroactively stamps parent-AC refs on a child that implements them -- closing the roll-up deadlock where the declaring child was cancelled and its re-delegated replacement completed the work uncredited. Cancelling a ref-declaring child now warns and surfaces the orphaned criteria. Co-authored-by: Renn F <rennf93@users.noreply.github.com>
8.2 KiB
Intent Verbs (gateway-facing surface)
claim_doc_task
Claim awaiting_documentation. Returns evidence inline.
Allowed roles: documenter
Composes: (no atomic actions)
claim_gate_review
Claim an assembled-PR review task (awaiting_pr_review) WITHOUT transitioning it — mirrors QA's claim_review. The assembled diff and the parent task's acceptance criteria are returned inline.
Allowed roles: pr_reviewer
Composes: (no atomic actions)
claim_pr_review
Claim an inbound external-PR review task and start work. pending -> claimed -> in_progress.
Allowed roles: pr_reviewer
Composes: claim → start
Preconditions: external_review_state
claim_review
Claim a task in awaiting_qa for review. Returns evidence inline.
Allowed roles: qa
Composes: (no atomic actions)
complete
Cell PM merges the PR (leaf into the cell branch, or the gated cell→root PR into the root branch) + transitions to completed; Main PM escalates the root to the CEO (who merges root→master). The merge runs BEFORE the complete transition: TaskService.complete asserts the PR is already merged, so the choreographer verb body (cell_pm_complete / main_pm_complete) owns the merge-first ordering — no trailing pr_merge side_effect is declared here.
Allowed roles: cell_pm, main_pm
Composes: complete
declare_coverage
Stamp parent acceptance criteria onto an existing child's parent_ac_refs after the fact — for a replacement child whose delegate omitted covers_parent_criteria. No status change; the verb body owns ownership + criterion validation.
Allowed roles: cell_pm, main_pm
Composes: (no atomic actions)
delegate
Create a subtask under the current task. Validates the delegation chain (main_pm->cell_pm; cell_pm->its team's devs) and the assignee-vs-task_type rule (Cell PMs get planning-typed tasks; devs get code/research, UX devs also design). documentation is NOT delegatable — the lifecycle auto-creates the doc phase after the code subtask passes QA.
Allowed roles: cell_pm, main_pm
Composes: create_subtask
escalate_to_ceo
Escalate to CEO with reason. Transitions to awaiting_ceo_approval.
Allowed roles: head_marketing, main_pm, product_owner
Composes: escalate_to_ceo
escalate_up
Escalate to your role's escalation_target.
Allowed roles: cell_pm, main_pm
Composes: (no atomic actions)
Preconditions: non_terminal
fail_review
Fail QA with concrete issues. Transitions to needs_revision.
Allowed roles: qa
Composes: qa_fail
give_me_work
Return your most-actionable task or signal idle.
Allowed roles: cell_pm, developer, documenter, main_pm, pr_reviewer, qa
Composes: (no atomic actions)
i_am_blocked
Escalate to PM. Logs a struggle journal entry.
Allowed roles: developer, documenter, qa
Composes: block
i_am_done
Submit work for QA. Auto-runs in_progress->verifying then verifying->awaiting_qa. Strict - PR must be open (call open_pr first) and >=1 commit.
Allowed roles: developer
Composes: submit_verification → submit_qa
Preconditions: commits>=1, owns_task
i_am_idle
Signal you have no active work. PMs auto-pause owned in_progress tasks.
Allowed roles: auditor, cell_pm, developer, documenter, head_marketing, main_pm, pr_reviewer, product_owner, prompter, qa, secretary
Composes: (no atomic actions)
i_documented
Signal docs complete. Transitions to awaiting_pm_review.
Allowed roles: documenter
Composes: docs_complete
i_will_plan
PM mirror of i_will_work_on for parent tasks. Claim, plan, transition to in_progress; from there delegate subtasks.
Allowed roles: cell_pm, main_pm
Composes: claim → set_plan → start
Preconditions: plan
i_will_work_on
Claim a task, set the plan, and transition to in_progress. Atomic - preconditions checked before any state mutation.
Allowed roles: developer
Composes: claim → set_plan → start
Preconditions: plan
open_pr
Push the branch and open a PR. Atomic - preconditions (assignee, >=1 commit, no prior PR) checked BEFORE any git operation. After success, call i_am_done.
Allowed roles: developer
Composes: (no atomic actions)
Side effects: push_branch, create_pr
Preconditions: commits>=1, no_prior_pr, owns_task, pr_open_state
pass_review
Pass QA. Transitions awaiting_qa -> awaiting_documentation.
Allowed roles: qa
Composes: qa_pass
post_pr_review
Post one complete change-request to the external PR and finish the review task. in_progress -> completed.
Allowed roles: pr_reviewer
Composes: pr_review_done
pr_fail
Fail the assembled-PR review with concrete issues. Transitions awaiting_pr_review -> needs_revision, routed back like a QA fail.
Allowed roles: pr_reviewer
Composes: pr_fail
pr_pass
Pass the assembled-PR review. Transitions awaiting_pr_review -> awaiting_pm_review so the PM can merge.
Allowed roles: pr_reviewer
Composes: pr_pass
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.
Allowed roles: cell_pm
Composes: (no atomic actions)
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.
Allowed roles: cell_pm, main_pm
Composes: request_changes
resume
Resume a paused task you own. paused -> in_progress.
Allowed roles: cell_pm, developer, documenter, main_pm, qa
Composes: resume
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.
Allowed roles: main_pm
Composes: submit_for_review
Pre side effects: create_root_pr
Preconditions: root_not_code
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.
Allowed roles: cell_pm
Composes: submit_for_review
Pre side effects: create_pr
sync_branch
Rebase your task's branch onto its current base THROUGH the gate (raw git is denied). Use when your branch has fallen behind its base — e.g. a sibling task's PR merged into the parent branch while you worked. Fetches origin, rebases head onto base, and force-pushes (with-lease). No DB state change. On conflicts the rebase is aborted and the conflicted files are returned — resolve by hand, commit, then sync_branch again. Pass stash=True to auto-stash uncommitted changes instead of refusing DIRTY_WORKSPACE; they are restored after the rebase.
Allowed roles: developer
Composes: (no atomic actions)
Preconditions: owns_task, sync_branch_state
triage
List actionable tasks in your scope.
Allowed roles: auditor, cell_pm, head_marketing, main_pm, product_owner
Composes: (no atomic actions)
triage_all
List actionable tasks across all teams (Main PM only).
Allowed roles: main_pm
Composes: (no atomic actions)
unblock
PM unblocks a blocked task; restores pre-block state.
Allowed roles: cell_pm, main_pm
Composes: unblock
unclaim
Voluntarily release a claim back to pending. The work-in-progress branch is preserved. A PR reviewer who claimed an external review (in_progress) or a gate review (awaiting_pr_review) and cannot finish releases the claim here rather than wedging the lane until the stale-claim reaper.
Allowed roles: cell_pm, developer, documenter, main_pm, pr_reviewer, qa
Composes: (no atomic actions)