Skip to content

Latest commit

 

History

History
205 lines (159 loc) · 17.2 KB

messages.md

File metadata and controls

205 lines (159 loc) · 17.2 KB

Messages

Every line a script or hook prints for a person to read: in a session's transcript, in /sdlc:dispatch's background output, or in a worker's own log. Exact wording is quoted; <...> marks what varies. Grouped by the situation you'd be looking at it in.

Dispatch needs you

supervise.py prints these lines and exits when a person is needed, or when a newer supervisor took over. /sdlc:dispatch restarts the supervisor right away (so the rest of the work keeps going), then acts on each line:

Line Meaning What to do
blocked <task> awaiting-review: <gate> a human review gate is open and no worker is running for the task /sdlc:review <task>
blocked <task> stopped: <comment> the worker ended without finishing; <comment> is its last comment /sdlc:recover <task>
blocked <task> failed: <comment> the worker's session ended in error; <comment> is its last comment /sdlc:recover <task>
blocked <task> pr-opened: <url> an epic-pr integration task's pull request is open review and merge the pull request yourself; sdlc closes the task once it's merged
blocked <task> not started: <reason> run-task.sh refused to start the task; see run-task.sh can't start for <reason>'s shapes fix the named problem, then dispatch again
new-work <task> <task>... ready tasks exist outside the ids /sdlc:dispatch was given and not labelled auto (labelled work is started without a line) /sdlc:dispatch asks whether to add them
taken over a supervisor with a higher generation took the lock nothing; the newer one keeps going
supervisor <generation> already running a higher-generation supervisor already holds the lock; this run exits without starting anything nothing; /sdlc:dispatch reports it and doesn't restart

Workers at a glance (/sdlc:status, /sdlc:stop, /sdlc:dispatch)

workers.py prints one block per dispatched, non-closed task:

Shape State What it adds What to do
<id> running on <host> started <T> ago last output <T> ago "<title>" running nothing nothing, or /sdlc:logs <task> to watch progress
<id> crashed on <host> started <T> ago last output <T> ago "<title>" crashed session:, transcript:, worktree:, commits since <base>:, uncommitted:, log:, worker runs:, result:, last events:, stderr:, machine booted: /sdlc:dispatch resumes it automatically when the cause looks gone, or reports why not; /sdlc:recover <task> after reading the evidence
<id> stopped on <host> worktree <path> "<title>" stopped last comment: <comment> /sdlc:recover <task>
<id> failed on <host> worktree <path> "<title>" failed last comment: <comment> /sdlc:recover <task>
<id> awaiting-review on <host> worktree <path> "<title>" awaiting review gate: <gate>, review: /sdlc:review <task> /sdlc:review <task>
<id> pr-opened on <host> worktree <path> "<title>" pr-opened pull request: <url>, waiting for its merge merge the pull request
no dispatched task in progress — — nothing

/sdlc:status adds one line per task needing attention, naming the same next steps.

Inbox (/sdlc:inbox)

inbox.py prints one block per item waiting on a person, oldest first, each followed by link: and next: lines:

Shape Kind link: next:
<task> review since <T> ago "<title>" an open human review gate finish-task.py opened the worktree path, or missing /sdlc:review <task>
<task> gate since <T> ago "<title>" any other open human gate blocking the task the gate's reason bd gate resolve <gate>
<task> pull request since <T> ago "<title>" an open gh:pr gate the pull request URL merge it; the task closes once merged
<task> stopped since <T> ago "<title>" a worker that ended without finishing its last comment, or none, plus /sdlc:logs <task> /sdlc:recover <task>
<task> failed since <T> ago "<title>" a worker whose session ended in error its last comment, or none, plus /sdlc:logs <task> /sdlc:recover <task>
<task> crashed since <T> ago "<title>" a claimed task with no live worker and no outcome recorded the worker log's path /sdlc:dispatch resumes it, or /sdlc:recover <task>
<task> permissions since <T> ago "<title>" a task whose latest attempt was denied tool calls (dispatch_permission_denials) the suggested rules, comma-separated, e.g. Bash(cargo test:*), Bash(git status:*) add them to permissions.allow in the project .claude/settings.json
inbox empty — — nothing

Suggested rules: a Bash command gives one Bash(<prog>:*) per component (split on &&, ||, ;, |, newlines), or Bash(<prog> <sub>:*) for git, npm, cargo, bd, pnpm, yarn, go, docker, kubectl and gh. Interpreters (python, node, ruby, perl), wrappers (sh, bash, env, sudo, xargs, timeout, nohup), commands with a heredoc, and the Write and Edit tools give none; any other tool gives its bare name. A task with no suggestion isn't listed.

A line ends with seen by <actor> when /sdlc:inbox --all shows an item someone already marked seen (/sdlc:inbox seen <task>); a seen item is otherwise hidden until its state changes. See dispatch_seen.

finish-task.py's exit codes

Run by the worker itself. Exit 1 and 3 messages print to stdout, so they land in the worker's own log; exit 2 prints to stderr (a usage problem, not normally seen by a person).

Exit Situation Message shape Who acts, and how
0 merged and closed merged <id> into <base> and closed it, then closed <parent_id> / closed epic <epic> for any cascade nothing
0 (epic-pr) pull request opened opened <url> for <epic>; <id> and <epic> close once the pull request is merged merge the pull request
1 uncommitted tracked files not merged: uncommitted changes to tracked files: <files>. Commit or discard them. worker commits or discards, runs again
1 agent review requested changes not merged: review round <N> requested changes:\n<findings>\nFix them, commit, and run this again. worker fixes the findings, runs again
1 agent review didn't complete not merged: the review didn't complete (<timed out after 900s|exited <N>|returned no verdict>); run this again worker runs again
1 rebase conflict not merged: rebasing <branch> onto <base> conflicts in: <files>. Run git rebase <base>, resolve the conflicts, then run this again. worker resolves, runs again
1 verify failed after rebase not merged: verify for <target> failed after rebasing onto <base>: <verify output> worker fixes the check (verify failure shows the same shape)
1 verify failed, nothing to merge (e.g. an analysis task) not merged: verify for <target> failed: <verify output> worker fixes the check
1 merge failed not merged: merge into <base> failed: <stderr> worker investigates the merge conflict or wt error
1 epic-pr: pre-merge checks failed not merged: the project's pre-merge checks failed: <output> worker fixes the checks
1 epic-pr: push failed not merged: pushing <branch> to origin failed: <output> worker investigates the push error
1 epic-pr: opening the pull request failed not merged: opening the pull request failed: <output> worker investigates the gh pr create error
1 counting commits failed not merged: counting commits since <base> failed: <stderr> worker investigates
3 pre-merge checks unapproved needs a person: the project's pre-merge checks aren't approved on this machine; a person runs wt config approvals add in <main_root>. Record it with bd comments add <id> and stop. run wt config approvals add once, in the main checkout
3 human review pending needs a person: <id> waits for a human review (gate <gate>). Stop now: you'll be resumed after the review. /sdlc:review <task>
3 agent review rounds exhausted needs a person: the review still requests changes after 3 rounds\n<findings> /sdlc:review <task>, or fix by hand and /sdlc:recover <task> → Finish

verify.sh failure

Same output whether run by finish-task.py, by /sdlc:verify, or by hand:

verify <check-id>: <check command>
<the check's captured stdout and stderr>
verify <check-id> failed

to stderr:

reproduce: cd <worktree> && <check command>
narrow it down (one test, or the system by hand) before fixing; use a debugging skill if one is installed
debug: <custom.dispatch.debug hint>          (only when set)

An epic's pre-merge step instead prints pre-merge checks: wt hook pre-merge, then <output> and pre-merge checks failed. Success prints <id> passed.

What to do: /sdlc:verify <id> reproduces this on demand; it reads the output and the commits since the failing task merged, and says which change broke which check.

run-task.sh can't start

Printed to stderr as error: <reason>; the last line becomes not started: <reason> in a supervisor's wake line.

Reason What to do
unknown integration mode <mode> (direct, epic-merge, epic-pr) fix custom.dispatch.integration or the epic's dispatch_integration
<id> is an epic: dispatch its tasks dispatch the epic's tasks, not the epic
<id> is <status>, expected open the task isn't ready to start (already claimed, closed, or similar)
<id> has no metadata.verify add a verify command, or --role integration/analysis
<id> waits for <blockers> those tasks must close first
no branch <target> create the target branch, or fix custom.dispatch.target
<id> integrates <epic>, whose other tasks aren't closed: <pending> close the epic's other tasks first
epic-pr mode needs a git remote named origin / epic-pr mode needs the gh CLI add the remote, or install gh
could not claim <id> a bd update --claim race; try again
the project's hooks aren't approved on this machine; a person runs wt config approvals add in <root> run wt config approvals add once, in the main checkout
could not create the worktree for <branch>: <wt error> read the wt error and fix it
no worktree for branch <branch> the worktree creation silently didn't produce one; investigate wt
could not start the worker claude failed to launch; check its own error

Stopping and resetting

Message Printed by Meaning What to do
<id>: no running worker / <id>: no running worker under it stop-task.sh nothing to stop nothing
finished <id> stop-task.sh the worker had already merged and closed the task before the stop landed nothing to recover
stopped <id> stop-task.sh the worker ended; dispatch_state=stopped, comment Stopped by a person. /sdlc:recover <task>
reset <id> reset-task.sh the task is fully reopened, every dispatch_* key cleared /sdlc:dispatch picks it up like new

Human review, resumed

Message Printed by Meaning What to do
resumed <id> resume-reviewed.sh the reviewed task's worker resumed to read the verdict nothing
not resumed <id>: <reason> resume-reviewed.sh the gate closed, but resuming the worker itself failed; dispatch_state is restored to awaiting-review /sdlc:recover <task>
resumed <task> <worktree> <log> resume-task.sh (via start-worker.sh) a crashed worker resumed nothing
error: <id> has no dispatched worker to resume (status <status>, dispatch_state: <state>) resume-task.sh usage error: the task isn't in a resumable state check the task's actual state
error: the worker for <id> is still running resume-task.sh a process already holds the session nothing; it isn't actually crashed
error: no worktree for branch <branch> / error: no transcript for session <session> resume-task.sh the worktree or the Claude transcript is gone /sdlc:recover <task> → Start over

Pull requests

Message Printed by Meaning What to do
closed <id> (then closed <epic> if it was the last task) close-prs.sh the pull request merged; the integration task, and possibly the epic, closed nothing
stopped <id> close-prs.sh the pull request closed without merging; comment pull request <pr> closed without merging /sdlc:recover <task>

/sdlc:clean

clean.sh always lists; --apply also removes. One line per leftover:

Line Reason
worktree <branch> closed task, worktree and branch left behind a merge finished but the worktree was never removed
worktree <branch> open task with no dispatch_branch, worktree left behind (reset) the task was reset while its worktree stayed
branch <branch> closed task, branch left behind with no worktree the branch survived removal (not an ancestor of its base after a rebase), or the worktree was removed by hand
queue <branch> held by <holder>, no running process a worker died mid-merge, still holding the branch's merge queue
error: could not remove the worktree for <branch> / error: could not delete branch <branch> --apply itself failed on that item

clean.sh never lists the main checkout, a claimed task's worktree, or a task whose dispatch_state is stopped, failed or awaiting-review — those need /sdlc:recover or a review first.

/sdlc:analyse

Output Meaning What to do
(nothing) this branch head was already analysed nothing
busy <epic> an open epic is already analysing or refactoring this branch wait for it to finish
clean <sha> no function crosses custom.dispatch.ccn/function_length at that commit nothing
created <epic> <task> a refactor epic and its analysis task were filed /sdlc:dispatch <epic>
error: metrics.sh failed:\n<output> lizard isn't installed, or crashed install lizard (pip install lizard)

Worker guardrails (hooks)

These fire inside a worker session (DISPATCH_TASK set); a person doesn't run the denied command, but reads these to understand why a worker keeps retrying through finish-task.py instead.

worker-guard.sh denies a PreToolUse Bash call and returns this reason:

Denied command shape Reason given
bd close / bd done Workers don't close issues with bd. Run <finish>: it merges and closes the task, and the epic when it is done.
bd update --status closed Workers don't close issues with bd. Run <finish>: it merges and closes the task.
wt merge Workers don't merge with wt. Run <finish>: it rebases, verifies and merges through the merge queue.
git ... push Workers don't push. Run <finish>: it merges, or pushes and opens the PR in epic-pr mode.
gh pr merge Workers don't merge PRs. Run <finish>: it merges through the merge queue.
bd gate resolve / bd gate close Workers don't resolve review gates. A person runs bd gate resolve after reviewing.
setting review or dispatch_review* metadata Workers don't set the review verdict. <finish> manages review and dispatch_review* metadata.

worker-stop.sh blocks a worker's first attempt to end while its task is still claimed and open with no comment since it was dispatched: Task <id> isn't closed. Commit your work and run <finish>. If you can't finish, record what's missing with: bd comments add <id> "<what's missing>". A second attempt is let through.

Merge queue waits

Message Printed by Meaning What to do
waiting for the <branch> merge queue, held by <holder> merge-queue.sh acquire printed once while it polls for the queue wait; it retries for up to 1800s by default
error: timed out waiting for the <branch> merge queue merge-queue.sh acquire nothing freed it in time check what holds it (/sdlc:clean lists a stuck one)
error: no merge queue for <branch> (run: merge-queue.sh ensure <branch>) merge-queue.sh acquire the queue was never created shouldn't happen through normal dispatch; run ensure

Logs

logs.py (/sdlc:logs, /sdlc:recover's own lookup):

Message Meaning
<task> was never dispatched no session, and no .wt failure file either
<task> has no recorded dispatch session; the worktree failed before one was kept: the worktree creation itself failed; the .wt file's contents follow
(no log at <path>) / (unreadable log <path>) the expected log file is missing or unreadable
error: --follow needs a terminal --follow was used outside an interactive terminal

record-task.sh itself, once a worker ends, prints one summary line: <state> <id> · $<cost> · <M>m<SS>s · <agents-or-models> · event <event-id>, with · worktree kept, see <log>.remove appended if removing a merged task's worktree failed. no result for <id> in <log>: the worker didn't end normally (exit 1) means the process died without a result line — the task stays crashed for the next dispatch to find.