diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md index 30be52f..a3b63cc 100644 --- a/docs/user/cli-reference.md +++ b/docs/user/cli-reference.md @@ -521,21 +521,21 @@ but before the source reaches terminal state, the next `quay tick` recovers the cancel intent and writes the same source-side `retargeted` audit context from the linked clone. -`task resnapshot` re-baselines a task's frozen `ticket_snapshot` — the -definition of done the reviewer enforces. It re-fetches the task's Linear -ticket, re-parses the `quay-config` block, re-composes the snapshot with the -same code path enqueue uses, and replaces the single per-task `ticket_snapshot` -artifact both worker and reviewer read (no version skew). Use it when an -operator has edited the live ticket to change scope mid-flight: the frozen -snapshot otherwise keeps the reviewer enforcing the stale acceptance criteria. -It emits a `ticket_resnapshotted` audit event carrying the required `--reason` -and a before/after diff of the snapshot, and it invalidates the latest review -verdict (superseding a standing `approved` / `changes_requested`) so the next -`quay tick` runs a fresh review against the new snapshot rather than being -blocked by a stale verdict. Running it when the ticket is unchanged is a safe, -still-audited no-op: the event is recorded but the artifact is not rewritten and -no verdict is invalidated. The command requires the Linear adapter to be -configured, and the task must have an `external_ref`. +`task resnapshot` re-baselines a task's frozen `ticket_snapshot` and current +`task_objective` — the definition of done the reviewer enforces and the +objective worker/reviewer prompts load. It re-fetches the task's Linear ticket, +re-parses the `quay-config` block, and re-composes both artifacts with the same +code path enqueue uses. Use it when an operator has edited the live ticket to +change scope mid-flight: without a resnapshot, later prompts keep enforcing the +stale acceptance criteria. It emits a `ticket_resnapshotted` audit event +carrying the required `--reason` and a before/after diff of the snapshot, and it +invalidates the latest review verdict (superseding a standing `approved` / +`changes_requested`) so the next `quay tick` runs a fresh review against the new +snapshot and objective rather than being blocked by a stale verdict. Running it +when the ticket is unchanged is a safe, still-audited no-op: the event is +recorded but the artifacts are not rewritten and no verdict is invalidated. The +command requires the Linear adapter to be configured, and the task must have an +`external_ref`. ## Submit Brief diff --git a/docs/user/concepts.md b/docs/user/concepts.md index 053c590..594063c 100644 --- a/docs/user/concepts.md +++ b/docs/user/concepts.md @@ -27,9 +27,10 @@ Before enqueueing work, the operator must: At enqueue time, Quay fetches the effective base branch, creates a local branch named `quay/`, creates a worktree from `origin/`, runs the repo `install_cmd`, stores the task-level `task_objective` artifact (the raw -original brief) plus the first attempt's `brief` and `final_prompt` artifacts, -and creates the first pending attempt. The effective base branch is the repo -default unless a task-level override is supplied. +initial brief) plus the first attempt's `brief` and `final_prompt` artifacts, +and creates the first pending attempt. `task resnapshot` can append a newer +task-level objective after the live ticket changes. The effective base branch is +the repo default unless a task-level override is supplied. ## Work Items, Runs, And Attempts @@ -61,8 +62,8 @@ Every attempt has: - A reason, such as `initial`, `ci_fail`, `crash`, `review`, or `blocker_resolved`. -- A `brief` artifact: a structured composed prompt body with the original - task objective (rendered from the task-level `task_objective` artifact), +- A `brief` artifact: a structured composed prompt body with the current + task objective (rendered from the newest task-level `task_objective` artifact), the current attempt's guidance, and any diagnostics for this attempt. - A `final_prompt` artifact: for code-worker attempts, Quay's worker preamble followed by the composed `brief`; for review attempts, Quay's static @@ -91,7 +92,7 @@ A supervisor lock prevents overlapping ticks and serializes side effects with Artifacts are snapshots of data that crosses a boundary, such as: - `ticket_snapshot` -- `task_objective` (task-level; the raw original brief, source of every later attempt's stable objective section) +- `task_objective` (task-level; the canonical brief used by later prompt objective sections) - `brief` (per-attempt composed body) - `final_prompt` (worker preamble + `brief`, or reviewer protocol + guidance + review `brief`) diff --git a/docs/user/monitoring-and-artifacts.md b/docs/user/monitoring-and-artifacts.md index ea9fe7e..c7ba286 100644 --- a/docs/user/monitoring-and-artifacts.md +++ b/docs/user/monitoring-and-artifacts.md @@ -81,9 +81,9 @@ binary and invalid UTF-8 artifacts such as `malformed_signal`. | Kind | Meaning | | --- | --- | -| `ticket_snapshot` | Snapshot of source ticket/context at enqueue time. | -| `task_objective` | Stable original task brief, written once at enqueue and reused by every later code-worker attempt as the canonical objective. Task-level (no `attempt_id`). | -| `brief` | Per-attempt composed prompt body: a structured `` block pointing at the task-level `task_objective` artifact, a `` block (initial instruction, retry/respawn template, or orchestrator-submitted brief), and an optional `` block (CI excerpt, review comments, conflict slice, etc.). The raw original brief lives in `task_objective`, not here. | +| `ticket_snapshot` | Snapshot of source ticket/context. Enqueue writes the first task-level row; `task resnapshot` can append a newer task-level snapshot after the live ticket changes. | +| `task_objective` | Canonical task brief reused by later code-worker and reviewer prompts. Enqueue writes the first task-level row; `task resnapshot` can append a newer task-level objective. | +| `brief` | Per-attempt composed prompt body: a structured `` block pointing at the current task-level `task_objective` artifact, a `` block (initial instruction, retry/respawn template, or orchestrator-submitted brief), and an optional `` block (CI excerpt, review comments, conflict slice, etc.). The current task objective lives in `task_objective`, not here. | | `final_prompt` | Code-worker attempts: worker preamble plus the attempt's composed `brief`. Review attempts: static reviewer protocol, reviewer guidance, then the review `brief`. | | `session_log` | Captured tmux output. | | `usage` | JSON usage envelope captured per attempt. `.quay-usage.json` is stored verbatim when present; otherwise Codex `--json` JSONL in `.quay-tool-trace.log` can synthesize normalized model/token totals. |