task-queue-workflow
Use when claiming task-db slices under task model v3.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- task-queue-workflow
- author
- Steadfaste Fleet
- version
- 1.0.0
- category
- devops
- metadata
- { "hermes": { "tags": [ "tasks", "task-model-v3", "orchestrator", "worker", "claim", "verify", "review", "board" ], "related_skills": [ "orch-bus-worker", "postgres-schema-design", "loop-governance", "change-test-loop" ] } }
- platforms
- [ "linux", "macos" ]
- description
- Use when claiming task-db slices under task model v3.
02 资源文件 1
- 参考文档references/v009-schema-lessons.md4.8 KB
03 SKILL.md 正文
Task Queue Workflow — Task Model v3 (orchestrator-intelligence / worker-execution)
When to Use
- Any agent claiming or executing a slice from the task queue
- Orchestrators decomposing stories, dispatching, or verifying completions
- Reading the task board or daily digest
- Design:
docs/design/task-model-v3.md; schema:ops/services/tasks/schema/(a version-gated runner; the highestvNNN__file present wins — see the migration pitfall below)
The Model
Two tiers, not role-locked domains (Luke 2026-08-24):
- Orchestrators (esther/moses) = the intelligence layer — decompose stories → planned slices, dispatch urgent work, VERIFY every completion. Strategy/research/verification/case-study authoring are orchestrator work.
- Every other agent = a general worker — may claim and execute ANY slice (build, refactor, research, docs, infra). No role-lock.
- A worker may claim any pending slice; only the orchestrator may verify.
Lifecycle
pending → (claim) → in_progress → (report) → review → (verify) → completed
└── (unclaim) ──┘ └── (verify --reject) → in_progress
review= worker-done-AWAITING-VERIFICATION. Not done, and nothing completes it for you. Verification is enforced in the DB rather than by convention:tasks.verify_sliceis SECURITY DEFINER with a moses/esther allowlist INSIDE the function, and no other profile holds EXECUTE on it — so a worker'spermission denied for function verify_sliceis permanent. It is not a retry hint, and it is not a signal that someone else is about to act. The scheduled orchestrator pass is what drains the queue, so confirm that pass exists on the host (hermes cron list) rather than assuming the documented schedule is installed: where it is absent, paused, or never fires, the slice sits inreviewindefinitely. So follow up in the SAME breath as the report — name the slice id and its evidence to moses/esther (bus, or escalate for a decision only the operator holds) — instead of stopping atreportand waiting. A slice stuck >24h in review gets auto-re-queued by the handler's stale sweep (Arm 3) — never auto-completed.- A description that names WHO may run a tool, without naming WHAT refused the caller or what to do next, invites the reader to assume a passive actor will do it. Agent-facing text (tool descriptions, check messages, warnings) must state the enforcement and the next ACTION: "only the orchestrator may run this, and no job does it automatically — report, then hand the slice over", never a bare label like "ORCHESTRATOR-ONLY". An agent that reads the label as "someone will pick this up" stops working on a slice nobody is coming for.
- The tasks store is HOST-LOCAL, so a peer's stuck slice is NOT yours to verify. The grants are
per-profile roles inside EACH host's own store, so
--board --repo ALLlists only YOUR host's rows: measured, an agent elsewhere reported a slice stuck inreviewwhile this host's fleet-wide board readIn review: none. "An orchestrator will clear it" is therefore true only where a verifier identity EXISTS on that host, and the drain has to be installed PER HOST — a sweep running here cannot reach a peer's store, and routing their slice to a remote orchestrator is not a mechanism that exists. Do not promise a peer host will act, and do not offer to verify it yourself: say which host must clear it. v017 (2026-11-08) gives the worker host's own session the sanctioned route: the ORCHESTRATOR records a per-slice verify grant there (via its SSH/psql path — the same one the L2 fleet test uses to apply schema) and the worker then verifies THAT slice itself.task-db.py verify-grant <id> --verifier mycortex_reader_<agent> --note "<why>"— slice-scoped, short-lived (1h default), one-shot (consumed on the first verify decision, approve or reject), audited (authorized_by + note). v018 (2026-11-09, operator steer "does Titus have to ask for a grant?"): a DESIGNATED verifier needs no grant at all for work it did NOT create — the operator setsTASKS_VERIFIER_ROLES=mycortex_reader_titus(comma-separated) in the host env; fleet-update GRANTstasks_verifierevery update, and the no-self-grade predicate (verify_capable_for: same rule in verify_slice AND the trigger) lets that session close any dispatch with zero asks while STILL refusing its own slices. The per-slice grant remains the only route for verifying your own work. For a host with no verifier route at all, escalate to the operator. - Widening WHO may verify WAS the schema decision, made at v017/v018 — capability + recorded
grants, never a config tweak.
is_orchestratoris nowpg_has_role(p_role, 'tasks_verifier', 'MEMBER')(the NOLOGIN role is granted by default to the orchestrator reader roles; the old moses/esther name list is gone — adding a permanent verifier is a GRANT, a data operation, via the operator'sTASKS_VERIFIER_ROLESenv).verify_sliceEXECUTE is widened to every profile role, andauthorize_verify(orchestrator-only) records the grant row that lets a worker close a slice. The reasonreviewexists is intact: a designated verifier cannot grade its OWN slice — every closure carries a recorded authorization (the capability excludes self-created slices — created_by <> profile_of(caller) — or the grant row's authorized_by + note) or falls into the refused class — so DON'T bypass the grant by completing your own slice: the trigger refuses review→completed on every write path unless verify_capable_for admits the caller for that slice.
Worker commands (any agent)
task-db.py list --claimable # the worker queue: pending slices, no assignee, by priority
task-db.py claim <slice-id> # atomic pending→in_progress, assignee=me (self-only)
task-db.py unclaim <slice-id> --reason "<gap>" # return to pending (blocker, tool gap) — never fake progress
task-db.py report <slice-id> --evidence "<test output / measured numbers>"
# in_progress→review, awaiting orchestrator verify
- Execute the orchestrator's PLAN (written in the slice content), don't improvise strategy. Too big or lacks a tool → unclaim with the gap named.
- Report with EVIDENCE, not prose (test output, measured numbers).
Orchestrator commands (esther/moses only)
task-db.py verify <slice-id> --approve --note "<what was checked>"
task-db.py verify <slice-id> --reject --note "<the gap>" # → back to in_progress
task-db.py verify-grant <slice-id> --verifier mycortex_reader_<agent> --note "<why>"
# v017: delegate ONE slice's
# verification to a worker-host
# session (see delegation above)
task-db.py list --board # counts + per-agent + review queue
task-db.py list --board --repo ALL # the FLEET view (explicit)
- Never trust a self-reported done. Verify the evidence is real (test output, measured numbers) before approving.
- Reject with the gap named — the slice returns to in_progress for the worker.
- Task queries are repo-scoped, STRICT by default (2026-10-19):
list,pending, the claimable/handed-out pools and--boardshow the CALLER's repo and NOTHING else — untagged (pre-tag) rows are excluded, because when the store is mostly untagged a scoped query returned the whole fleet backlog (the "too broad" report from a pi session). Two explicit switches widen it:--include-untagged(your repo + the untagged rows — use this when you are scanning the pool for untagged FLEET slices) and--repo ALL(the orchestrator's fleet-wide view; omitting the parameter is never the fleet view). A session whose repo cannot be resolved gets NOTHING, by design. A task you ADD with no--repoinherits your session repo, so it stays visible in your own strict view.
Automated layers (no manual action needed)
- orch-task-morning-pass — 07:00 KST: decompose stories → planned slices, dispatch urgent via bus.
- orch-task-evening-pass — 19:00 KST: verify all review slices.
- Stale sweep Arm 3 (agent-message-handler): review >24h → verify(false, 'verify-stale') re-queues to in_progress.
- Daily digest + board query satisfy the visibility requirement (Luke: "1) visibility for tasks easily viewable 2) agents working truly autonomously and efficiently").
Board maintenance — "how old is this task?" / "should we drop it?"
To answer age/staleness questions, the board MCP (task_board/task_list/
task_pending) and task-db.py list do NOT surface timestamps — query the
Postgres store directly with the read-only reader role:
docker exec -i mycortex-postgres psql -U mycortex_reader_<profile> -d mycortex \
-F'||' -c "SELECT status, kind, priority, left(created_at::text,10) AS created, \
left(status_changed_at::text,10) AS last_chg, \
round(extract(epoch from now()-created_at)/86400) AS age_days, left(content,60) \
FROM tasks.tasks WHERE status NOT IN ('completed','cancelled') AND \
(kind IN ('story','slice') OR kind IS NULL) ORDER BY created_at;"
- Reader role =
mycortex_reader_<profile>(never superuser); containermycortex-postgres; databasemycortex; tabletasks.tasks. Age columnscreated_at(age) andstatus_changed_at(last state move — use this, notupdated_at, to see real movement since a row'supdated_atupdates on any touch). The board's in_progress count is a snapshot; the table is the truth.
Drop decision — classify, don't mass-drop; actual deletion is the owner's call.
- Parked by design (owner explicitly deferred, or env-gated on a human/
restart window) → keep but re-tag to
blocked/waitingso the board reads honestly; do not burn cycles re-attempting. Parking REMOVES the row from the claim pool —claimtakespendingonly — so a parked slice comes back only through the parked→pendingarc. State the unblock condition in the row, or it parks indefinitely; preferwaitingfor a genuinely external dependency, and re-tag back topendingthe moment the condition clears rather than leaving it parked because nothing forced a decision. - Live work just untouched (in_progress with an assignee on an active workstream, stale 1–3 weeks) → poke/re-claim the owner, never cancel their work.
- Sequential backlog (slices gated on a prerequisite phase completing) →
normal backlog, not cruft. This binds the WORKER too: before claiming a slice, check that its
inputs EXIST — if every prerequisite slice is still
pending, the deliverable can only be invented, sounclaimwith the gap named and let the queue advance in order. Do not author the artifact from imagination to look productive (that is fabrication), and do notcancela client-facing deliverable to clear your board (the owner's call, and it destroys real work): release the claim and name the prerequisite that unblocks it. - Exact duplicates (two slices describing the same deliverable) → the only safe dedupe: keep the fuller plan, cancel the other, with explicit go.
- Scope-crossing work — CANCEL, don't improvise (standing Luke rule). A
slice whose real deliverable requires changing BASE Hermes, the
metrics/cost telemetry pipeline, or the fleet review-pipeline automation is
not slice work — those belong as an explicit upstream/base change (or
upstream PR), never a partial implement crammed into a task slice. Before
claiming a slice "do it yourself," check whether its genuine deliverable
crosses that boundary ("per-cron token/spend cost tagging", "model-tier
routing config", "auto-approve review automation" all do). When it does,
--status cancelledthe slice and flag the scope boundary for the owner rather than building. Pure business research (a brand audit, a competitor gap analysis) is safe to do inline — zero Hermes code.
Metadata correction — retagging a row (repo / project / tags / assignee)
update carries status/reason only, so the ONE sanctioned surface for changing a
row's metadata is:
task-db.py restore <json> # per row: the row's CURRENT values, with only the
# field(s) you are correcting changed
It writes through tasks.task_upsert() — the single write path. Never
UPDATE tasks.tasks SET repo = ... by raw SQL: that bypasses the function's
derivation CHECK and RLS path, and every orchestrator plan restates the rule.
- Restore PRESERVES the columns it does not carry.
repo,assignee,target,due,tagsandcorrelation_idare read back from the store and re-written when your JSON omits the key; only an explicit empty value ("tags": [],"repo": null) clears one. This is load-bearing: a restore written for an unrelated correction used to NULL all six, so "retag one column" was a data-loss operation and a tag could not be set after the fact at all. - Read every field you DO carry out of the store; never retype it —
sourceespecially, because restore defaults it tosessionand a storedmanualthen becomes a false statement about the row's provenance. - Snapshot → probe → batch → re-read. Snapshot the ids' full row state to a file, apply ONE row and read it back, then the rest, then re-read all of them and assert that no field outside the one you meant to change differs. The probe also costs one row if the statement is wrong.
- Group legacy/untagged rows by what the ROW says, not by who wrote it. A tag is
a claim about where the work lands: rows naming a file, migration, cron or doc of
repo X are
repo=X; client/content deliverables whose output is a document belong to no repo; mint-residue rows are cancels, not tags. Tagging by the writer's own session repo is the false-claim version of the same mistake.
Pitfalls
- verify is orchestrator-only — and so is the ARC it performs. Two layers, both
in the DB:
tasks.verify_slicechecksprofile_of(session_user) IN ('moses','esther')(workers getfalse, and no other profile holds EXECUTE on it at all), AND the BEFORE UPDATE triggertasks.check_transition()refusesreview → completedfor any non-orchestrator caller. The second layer exists because the FIRST one was bypassable: the arc itself is legal intransition_allowed(which is role-agnostic), so a worker that could write the row — its own personal slice, whosecreated_byit is — could complete it throughtask_update,task-db.py update --status completed, or raw SQL, with no verification ever happening. Self-graded work then wore the same status as verified work. Measured before the fix, on a scratch DB as a non-orchestrator role:task_upsert(p_id, p_status=>'completed')returned a UUID (rc=0) on a row the caller had just reported intoreview. Fixed in schema v014;review → in_progress(the reject/stale arc) stays open on purpose — it asserts nothing about verification and the 24h stale sweep re-queues through it. - A gate whose permission is a VALUE THE CALLER WRITES is convention, not enforcement.
The story gate was admitted by
tasks.transition_reason = 'story_auto_complete'— a session GUC any caller canset_config— so whoever could write the row could skip the gate. The fix shape: the trigger VERIFIES the precondition the legitimate path satisfies by construction (a story has no active slice) and ignores the reason entirely; the value keeps only its non-authorising use (event labelling). Auditing a gate, ask what a caller must WRITE to pass it — if the answer is a string it supplies, the gate is advisory. Note the identity check belongs in the TRIGGER, not intransition_allowed: that function is IMMUTABLE and role-agnostic, so it cannot see a caller, and removing the arc there would make the sanctioned function itself raise. task_upsert()PRE-CHECKStransition_allowed(), so a trigger rule tested through it can pass VACUOUSLY — and the arcs the matrix forbids are reachable only by RAW UPDATE. A RED test written astask_upsert(p_status=>'completed')on apendingstory never reaches the trigger: the fast-fail raises first, "the guard refused" passes, and the guard under test was never consulted. Put the row in the state the arc requires (e.g.in_progressfirst), and test BOTH the function path and a rawUPDATE tasks.tasks SET status='completed', "column"='done'— the raw path is the one the trigger actually gates. Assert the ROW STATE afterwards as well as the rc: a refusal that still changed the row is not a refusal.- A non-orchestrator probe role needs its own grants, and an honest worker cannot call
verify_sliceat all. v009 grantsclaim_slice/unclaim_slice/report_doneBY NAME to each profile role andverify_sliceto moses/esther only, so a scratchmycortex_reader_<probe>that is merely a member ofmycortex_readergetspermission denied for function claim_sliceuntil you grant those three explicitly, while itsverify_slicerefusal ispermission deniedrather thanfalse. Assert BOTH layers — grant it temporarily to observe the in-function allowlist returnfalse, then revoke — or the test reports the wrong mechanism. - Claim is self-only —
p_assigneemust equalprofile_of(session_user); you can claim only FOR YOURSELF, never assign work to others. - A claimed slice can't be re-claimed — the single claimer holds it until unclaim/report.
- A slice that is
pendingWITH an assignee is STRANDED: unclaimable and unwatched. The pool requiresassignee IS NULLand the row is notin_progress, so no worker can take it, nobody is working it, and the board still counts it as ordinary pending work. Assigning a slice is NOT the same as starting it. Find them withlist --assigned(MCPtask_list_handed_out); release them withunclaim <id> --reason "<why>", which now clears the assignee on a PENDING row as well as returning anin_progressone — a hand-off nobody started used to be unreleasable, which is how six slices sat stuck for six weeks. - A bare
pendingcount overstates the queue. It mixes claimable slices, assigned-but-unstarted slices, and stories (never claimable — the pool takes slices only). An actionable count is the split:pending (claimable)/pending (assigned, not started)/pending (story). A count nobody can act on is what hides rot inside it. - A cancel MOVES the row to
tasks.task_archive; it does not leavestatus='cancelled'intasks.tasks. Socount(*) FROM tasks.tasks WHERE status='cancelled'is 0 even when the cancellation worked — verify or audit a cancel againsttasks.task_archive(which carriesarchived_at). The live table is open work only. - The store is UTC; the host usually is not. A date filter written from the LOCAL calendar day is midnight UTC and silently excludes every row written earlier that UTC day — a 09:00 KST change lands on the previous UTC date. Filter on a UTC date or compare the timestamp, and check the boundary before believing a 0-row result (a cutoff only hours away from the data is the failure shape).
- A migration that is not in
fleet-update.sh'sregister()map is NEVER deployed — the register map IS the deploy. The version-gated runner only sees migrations present in the DEPLOYED schema dir, so an unregistered one leaves every host silently behind while the repo looks correct. Register each migration in the same change, then confirm the host reports the new version (task-db.py --apply-schemais a no-op at the right version). - The MCP status filter must accept every status the STORE uses. An enum
narrower than
STATUSESmakes those rows unqueryable through MCP: they exist, are counted nowhere, and cannot be asked for. Extend the tool enums in the same change that adds a status. - Changing what a QUERY returns is a CLASS change — sweep the writers and the
read-backs, not just the query. Consumers that WRITE with one scope and then
READ with a filter break silently when the filter is tightened: a probe/doctor
check that added its row untagged and read it back through a scoped list reports
a broken write path that is healthy, and a dedup guard that relied on seeing
those rows compares against an EMPTY set and stops guarding while still
"passing". Before shipping a scope change: grep for the add path (
cmd_add, the inbox/dream mints, everyaddinvocation) and for each reader that filters, fix them in the SAME cycle, and give a probe row the SAME label on the write and the read-back side. A unit test on the query alone cannot see any of it. - A mocked
psqlproves the call's SHAPE, not the SQL — exercise the real store once before committing. Casts and column types are invisible to a mock:p_session_idis TEXT whilep_parent_idis uuid in the SAME call, and an id list needs= ANY(ARRAY[?]::uuid[])or the store answersoperator does not exist: uuid = text. Hand-writing a second copy of an existing upsert call is how such a mistake happens — share ONE SQL constant across the writers, pin the casts in a test that renders the SQL with sentinel values, and make the first real write a probe on a single row. - Unclaim/claim/report work on YOUR OWN rows —
created_bymust match the caller; you can't unclaim or report someone else's work. - Schema v009+ required — these commands
_require_v4(schema 9). On an older host, runbash fleet-update.shfirst; the version-gated runner applies the pending migrations, and a migration missing fromregister()is never carried (see the migration pitfall below). - report/verify set the derivation column too — the functions keep the column-derivation CHECK in sync; hand-written UPDATEs that don't will fail.
- review ≠ done — reporting puts work in a queue, it does not close it. The orchestrator's evening pass is the closer.
- A peer reporting "N stuck delegations / nothing claimable" is usually a
wrong-lane mis-route, not lost work — verify the fleet DB before
re-delivering. When a worker says its queue holds delegation rows that
consumed with
correlation_id=Noneand never became claimable, do NOT take "re-deliver the slices" at face value (a reply that duplicates or re-mis-routes is the worst outcome). Querytasks.tasksfor the cited slice IDs first: if the real rows exist and are already correctly homed (created_by=orchestrator,source=manual, scope=fleet, under their owning story and the right lane), the peer's copies are orphaned tracking residue from a delegation pointed at the wrong agent type (e.g. content-marketing slices handed to a staging-ops agent with a null correlation_id). The fix is the peer ARCHIVES its copies (they are not its deliverables, not claimable, not actionable) + you confirm the real work is intact — never a re-delivery. Judge the lane from the slice subject, not from the peer's framing.
Compete mode (opt-in, orchestrator)
Slices can run as parallel candidates: orch-compete-run.py <slice-id> --plan "APPROACH: ..." (≥2 approaches). Candidates judged DETERMINISTICALLY:
acceptance criteria met → fewest adversarial findings → lowest cost →
fastest. Never "which sounds better" (consistent with O4 autonomy rules).
References
references/v009-schema-lessons.md— the SQL/RLS gotchas behind the schema (SECURITY DEFINER + session_user, column-derivation CHECK, guarded grants)docs/design/task-model-v3.md— the full design
04 同仓库更多 Skills
macbook-linux-maintenance
Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.
governance-regression-triage
Triage a host's governance issues: what changed.
enforcement-immutability
Use when enforcement files lose their immutable flag.
steadfaste-fleet-repo-deploy
Use when committing to the steadfaste-fleet repo.
steadfaste-fleet-maintenance
Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.
fleet-preflight
DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its "Repo-Specific Pre-Flight" section covers git search, Hermes boundary, and deployment verification.