镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/task-delivery.md ↗
Structured task delivery
Every business task keeps its existing tasks.id, queue, claim, project computer and publication rules. task_records adds a versioned contract, execution checkpoints, advisory guide selections, delivery candidate and acceptance. task_history retains contract/candidate/checkpoint/acceptance changes; database triggers capture task creation and state changes for every kind, including future task kinds. Waiting reasons describe paused/waiting states, while an earlier failure remains historical during active execution. Old records explicitly say legacy_unknown; no historical acceptance is fabricated.
Task contracts define what to deliver; optional procedural guidance uses the role’s bound Skill bundle and read_skill (see role configuration). Skills never change the contract, required evidence or permissions. record_progress persists completed facts and a next action during execution; read_task_history retrieves factual observations and checkpoints for context reconstruction without exposing a model conversation. Coordination and scope-difference tools remain task-record operations. Executors of generic tasks deliver through tools: submit_report hands a structured report and artifact references to independent acceptance, and the writes the task holds add open_pull_request, post_review and github_write (see task coordination); tasks created before #814 keep submit_delivery. A pull_request delivery needs a passing independent QA on the same candidate unless the project turned that gate off (项目设置 → 能力上限, delivery_gates.pull_request_qa); without it the project's test command still has to pass on that candidate, and a project without a test command keeps QA. Trusted workflows still control tools and GitHub writes. Old guide selections/read events remain audit history; new runs have no guide discovery or selection protocol, and ignore the retired playbook_request input.
A delivery candidate binds the contract revision, versioned artifact references, raw tool evidence and separately labeled executor claims. Large observations use bounded previews and hash-bound references; the evaluator can page through originals with read_evidence. Evidence is not silently reattributed from an earlier attempt to the current tree. Code candidates retain Git trees/commits pinned by artifact refs so ordinary Git garbage collection cannot discard recorded versions; non-code tasks may deliver reports without a PR or SHA. The framework invokes an independent evaluator with a new message list and no executor conversation. It can inspect files and run verification only when the existing workflow permits shell use. Code/file candidates are checked out into a separate verification workspace from the submitted Git object; executor edits after submission and the executor's agent/session directory are not copied. Copied commands naming the old executor workspace receive a recoverable tool error; commands should use paths relative to the candidate checkout. This is a path-correction boundary, not an OS sandbox. Reports carry original source files and evidence references rather than the executor's model mailboxes. Acceptance requests use a separate accounting prefix. A retry can discover compact raw observations from previous verification of this exact candidate and contract and page their originals through read_evidence. Old-candidate verification is not offered; no verifier model conversation or private reasoning is inherited. The new verifier still forms its own judgment.
| Acceptance | Task action |
|---|---|
| pass | Complete after the specified delivery endpoint succeeds |
| pass_with_issues | Complete and retain concrete nonblocking observations; do not schedule more work |
| return | Give concrete gaps back to execution and evaluate a new candidate |
| insufficient_evidence | Give missing evidence back to execution and re-evaluate |
| needs_human | Record the precise decision/authority needed; other tasks continue |
Core incompleteness, missing mandatory evidence, unacceptable risk, or unresolved blocking gaps cannot pass. Return material executable gaps to the same task; missing necessary raw proof is insufficient evidence. Concrete authority/choice conflicts that prevent the requested outcome take precedence as needs_human. A report endpoint and an actual action/configuration endpoint are distinct: documenting unfinished work cannot satisfy a required final action.
Acceptance judges whether the requested result is correct, safe and usable. Checks must address a mandatory criterion or a concrete risk that could change the verdict. Reuse applicable raw observations instead of repeating successful verification or reviewing unchanged details without a new concern. Wording, section numbering, incidental diff counts, supplementary scratch artifacts and hypothetical future improvements do not block delivery unless they materially mislead the user or prevent use/verification of the requested result. Do not create extra reports, explanation files or validators merely to satisfy acceptance.
These proportionality and authorization principles are part of the common framework instructions, including for projects with saved custom role prompts. They include the bot's rule for other people's work: a role changes an issue or pull request someone else opened (its title, body, labels, assignees, state or anything else) only when its author or a maintainer explicitly asked for that change in its body or a comment on it, and a label is never such a request; no role pushes to, rebases or force-pushes someone else's branch, including a fork's, and none plans or delegates work that breaks this. Comments, review findings and the classification labels the project's review rules ask for are how the bot reports on that work. A bot pull request for someone else's issue does not change that issue. The rule is a prompt rule, judged by the role; only follow-up planning checks it in code, in a narrower form. Project persona instructions remain intact; the default QA template adds the detailed verdict guidance.
Residuals retain a description, evidence, user impact, nonblocking rationale and possible improvement goal/criteria in the acceptance record. They do not create tasks, grant authorization, or require the user to resolve optional work. A new execution needs an explicit request or plan. The same rule applies to existing ordinary/legacy follow-up tasks, so they cannot continue a residual chain. Core defects remain repairable within the original task; this policy does not turn a required fix into an optional observation.
Existing follow-up links and accepted artifacts remain queryable. Legacy follow-up executors and evaluators can read versioned parent and sibling artifacts through read_related_artifact, scoped to the same original delivery family and repository. Reads use the submitted Git object, never the mutable working copy, and are attributed to the reader. Drafts carry explicit unaccepted status and can be independently checked without peer approval. No source checkout is automatically overwritten and no new write/publication rights are granted.
Before publication an accepted verdict is staged. The original task is still running. Only when the publication endpoint succeeds does an atomic local transaction finalize acceptance, retain its observations, and complete the original task. Failed/uncertain external writes retain the existing publisher reconciliation behavior. SQLite does not pretend to make GitHub writes atomic. Repeated finalization preserves the recorded verdict without scheduling tasks. Candidate or contract changes invalidate staged/old decisions. Cancellation fences late acceptance.
Ordinary request executors reserve the final turns of their existing execution budget for artifact writing/progress/submission; exploration tools close for that attempt and the last turn requests a structured submission. This is an honest handoff, not approval: missing work remains visible to independent acceptance. Other execution profiles retain their existing tools and budgets. Remediation is bounded to three decisions. Re-submitting an identical rejected candidate exits as no progress. The evaluator reserves its final turns for typed submit_acceptance, which returns one of the five business decisions. Its internal evaluation_incomplete signal becomes a bounded infrastructure fault (no acceptance decision/round), never a sixth business result or a fabricated evidence rejection. A malformed verdict can receive at most two schema-feedback corrections within the same fresh evaluation context, reusing its observations. Core/evidence/risk conditions remain unchanged; repeated invalid results retain the existing finite evaluation-fault exit. An outage during evaluation is an infrastructure fault, not a rejection; the existing backoff/recovery mechanism remains. History reconstruction starts with recent factual observations and offers pagination metadata for older facts, without model conversations. An execution failure also attempts a guarded checkpoint of the latest files, including late writes made before a progress call. Progress checkpoints retain an unpublished Git tree at the current contract/base revision. A new attempt restores it only when both still match, retaining the original workspace for provenance. Agent prompts carry the task record with the candidate's artifacts and evidence as references only (kind/reference/version, source/version/verified), as the Manager prompt and the console already do; the evidence holds the full log of every command and file read of the submitting attempt, so embedding it made every request of the next attempt carry that attempt's logs (109 commands, about 290 KB, put a review's first request at 116k tokens). Executors read the bodies on demand with read_task_history; acceptance reads them with read_evidence. The evaluator and a follow-up task (its parent-delivery.json) get a bounded candidate: a field of an artifact's content over 16 KB is replaced by its size (a files artifact lists every file of the workspace, 1.5 MB for a 9,500-file repository, which put an evaluator's first request over 2 MiB), and evidence previews are kept newest first within 128 KB, with older entries reduced to their source for read_evidence. Structured history and candidate records survive restart; an ordinary request stopped after candidate submission resumes acceptance rather than redoing execution.
Interfaces
- Existing
GET /api/tasks/:idnow includestask.structuredand chronological structuredhistory. The console shows goal, contract revision, endpoint, next action, guide selections, acceptance, recorded nonblocking observations and any historical follow-up links. POST /api/taskscreates an ordinary request using{repository_id, request, contract:{goal,scope,criteria,endpoint}}. Existing repository access control and project enablement apply. No untrusted request supplies credentials or tools. This executor delivers local artifacts/reports; it has no merge/push/release tools.- A CI change is a development task like any other (#931).
workflow_changes: true(only with areviewable_pull_requestendpoint) records that a person with the project's configuration rights confirmed the task may change.github/workflows/; agents'create_taskand management commands from any source but the console cannot set it (workflow_changes_need_person). Only such a task's bot branch push asks GitHub for Workflows, and only where the installation grants it; every other push, and everygithub_write, lacks it, so GitHub refuses a branch that changes workflows. The workflow changes on the default branch only when people merge the PR. PATCH /api/tasks/:id/contractrevises a paused/unpublished task with{expected_revision,contract}and resumes it. It preserves revision history and invalidates previous candidates; running, completed or externally published tasks cannot be silently rewritten.GET /api/repositories/:id/contextreads durable project facts.PATCHaccepts{expected_revision,facts:[{source,fact}]}with repository access checks and revision conflict detection. Facts retain provenance and are task data, not permission changes.
The production backend remains Docker. Local execution is explicit opt-in for development and is not an OS sandbox: commands run as the host user. Do not expose it as isolation for untrusted code.
Validation
test/task-lifecycle.test.mjs covers universal records, revisions, all outcomes, guide version use, transaction fault injection, idempotency, finite remediation, cancellation and actual SQLite close/reopen. test/task-acceptance.test.mjs drives the real evaluator through a local model endpoint, checks message isolation/tool narrowing, evidence retrieval, accounting, outage recovery and request authorization. test/agent-process.test.mjs exercises same-task remediation through the publication mailbox and verifies that nonblocking observations survive delivery without creating work. Legacy related-artifact and trace fixtures verify that historical links remain readable without restarting a chain. test/local-manager.test.mjs verifies candidate checkout isolation with real Git/runner operations. Existing publication and scheduling fixtures inject an explicit fake evaluator; these tests do not claim semantic model validation.
SSE transport framing has its own bounded wire allowance; assembled model content remains capped at 2 MiB. The existing 8192-token output default remains; only trusted control-plane callers can supply a bounded larger budget (up to 32768), and the new DeepSeek request/evaluation callers use 16384 so reasoning cannot consume the entire final-verdict allowance. A model-supplied max_tokens field does not change the trusted limit.
The Docker manager allowlist forwards the acceptance/source/restore operations, validates their source workspace ids before execution, and uses the same long-operation timeout policy as checkout. This boundary is tested separately from the opt-in local backend.