mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
fix: harden verified delivery resumption
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
Magnus Hedemark
co-authored by
factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
parent
8d6e0407e0
commit
28d17b8a27
@@ -1326,7 +1326,7 @@
|
||||
"./verified-delivery"
|
||||
],
|
||||
"strict": false,
|
||||
"description": "Deliver an authorized change end to end — implement, verify, open the PR, merge, and confirm post-merge state — using live-state gates, durable interruption handoffs, and live-state-first resumption. Use when a user grants end-to-end delivery authority for a specific change and the work may cross tool-call limits, context exhaustion, worker loss, or session interruptions before the delivery boundary is reached. Do not use for plain fixes with no delivery directive, for granting merge or post-merge authority the user did not grant, or for designing release pipelines (use release-engineering for that)."
|
||||
"description": "Implement and deliver an authorized change end to end — verify, open the PR, merge, and confirm post-merge state — using live-state gates, durable interruption handoffs, and live-state-first resumption. Use when a user grants end-to-end delivery authority for a specific change and the work may cross tool-call limits, context exhaustion, worker loss, or session interruptions before the delivery boundary is reached. Do not use for plain fixes with no delivery directive, for granting merge or post-merge authority the user did not grant, or for designing release pipelines (use release-engineering for that)."
|
||||
},
|
||||
{
|
||||
"name": "vllm",
|
||||
|
||||
@@ -148,7 +148,7 @@
|
||||
- [travel-guide](travel-guide/SKILL.md): Create personalized, source-grounded travel dossiers from a destination, dates, duration, travelers, and constraints. Ask only the questions that change the plan, use explicitly permitted personal context without exposing it, research current logistics, and produce a cited, visually coherent PDF or responsive companion web page. Use when someone wants an individualized itinerary, trip brief, travel field guide, or shareable travel website. Do not use for real-time booking, ticket purchasing, visa or legal advice, or generic destination summaries without a specific traveler and trip.
|
||||
- [vercel-eve](vercel-eve/SKILL.md): Build, develop, deploy, self-host, secure, and troubleshoot durable backend AI agents with Vercel Eve. Use when creating an Eve agent, adding tools, skills, subagents, channels, schedules, sandboxing, durable sessions, observability, or deploying Eve on Vercel or a Node host. Do not use for the separate Vercel AI SDK Agent APIs such as ToolLoopAgent or WorkflowAgent; use an AI SDK-specific skill for those.
|
||||
- [verification-methodology](verification-methodology/SKILL.md): Verify work against explicit criteria using direct, source-faithful evidence, reproducible checks, and clear verdicts. Use before declaring an artifact, implementation, or claim complete; do not use for exploratory research without pass/fail criteria.
|
||||
- [verified-delivery](verified-delivery/SKILL.md): Deliver an authorized change end to end — implement, verify, open the PR, merge, and confirm post-merge state — using live-state gates, durable interruption handoffs, and live-state-first resumption. Use when a user grants end-to-end delivery authority for a specific change and the work may cross tool-call limits, context exhaustion, worker loss, or session interruptions before the delivery boundary is reached. Do not use for plain fixes with no delivery directive, for granting merge or post-merge authority the user did not grant, or for designing release pipelines (use release-engineering for that).
|
||||
- [verified-delivery](verified-delivery/SKILL.md): Implement and deliver an authorized change end to end — verify, open the PR, merge, and confirm post-merge state — using live-state gates, durable interruption handoffs, and live-state-first resumption. Use when a user grants end-to-end delivery authority for a specific change and the work may cross tool-call limits, context exhaustion, worker loss, or session interruptions before the delivery boundary is reached. Do not use for plain fixes with no delivery directive, for granting merge or post-merge authority the user did not grant, or for designing release pipelines (use release-engineering for that).
|
||||
- [vllm](vllm/SKILL.md): Operate, configure, benchmark, and troubleshoot vLLM inference servers: Docker and Kubernetes deployment, quantization-aware model configuration (tensor parallelism, KV cache), OpenAI-compatible API serving, throughput and latency benchmarking, continuous batching tuning, GPU operation, and upgrade/rollback. Use when deploying or running a vLLM server (vllm serve, vllm/vllm-openai), sizing a model and its KV cache for GPUs, selecting quantization and parallelism, serving via /v1 endpoints, measuring serving throughput or latency, tuning batching, or diagnosing GPU, OOM, or startup failures in a vLLM deployment. Do not use for model training, fine-tuning, evaluation-set design, or engine-selection methodology (that is ml-engineering), or for operating the llama.cpp stack with GGUF models (that is llama-cpp); other inference engines (TGI, Ollama, Triton) are out of scope.
|
||||
- [web-accessibility](web-accessibility/SKILL.md): Design, build, and review accessible web interfaces with native semantics, keyboard and focus behavior, forms and recovery, responsive input, motion, assistive-technology testing, and WCAG 2.2-informed evidence. Use for a11y, WCAG, ARIA, screen-reader, keyboard, focus, dialog, form, widget, or accessibility review work across frameworks.
|
||||
- [woodpecker-ci](woodpecker-ci/SKILL.md): Operate Woodpecker CI from installation through production troubleshooting: configure servers and agents, connect Forgejo/Gitea or another forge, write and validate pipelines, manage secrets and plugins, use Docker or Kubernetes backends, run the CLI, and diagnose failed builds. Use when setting up, administering, or debugging Woodpecker CI.
|
||||
|
||||
+30
-17
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: verified-delivery
|
||||
description: >-
|
||||
Deliver an authorized change end to end — implement, verify, open the PR, merge,
|
||||
Implement and deliver an authorized change end to end — verify, open the PR, merge,
|
||||
and confirm post-merge state — using live-state gates, durable interruption
|
||||
handoffs, and live-state-first resumption. Use when a user grants end-to-end
|
||||
delivery authority for a specific change and the work may cross tool-call
|
||||
@@ -31,6 +31,15 @@ Delivery proceeds only under an explicit user directive that names the change
|
||||
and the gates it authorizes. Never infer permission from context, tone, or a
|
||||
partial handoff.
|
||||
|
||||
> Confirm the target, scope, and rollback path before acting. Read-only
|
||||
> discovery may proceed without confirmation.
|
||||
|
||||
Apply this confirmation before the first mutation, including on resumption.
|
||||
The target names the repository and PR when one exists, the scope names the
|
||||
next authorized gated steps, and the rollback path states how the next
|
||||
mutation can be reversed or contained. A handoff records this confirmation;
|
||||
it does not widen it.
|
||||
|
||||
- The directive states which gated steps are authorized (for example: open a
|
||||
PR, merge when CI is green and reviews are satisfied, verify post-merge).
|
||||
- Steps outside the stated boundary stop at their gate with the exact missing
|
||||
@@ -83,20 +92,23 @@ reported clearly. A remaining-steps report is never terminal success for an
|
||||
end-to-end directive.
|
||||
|
||||
The handoff is machine-readable JSON stored durably: by default as a file at
|
||||
`.verified-delivery/handoff.json` in the repository working tree (kept
|
||||
untracked so it never becomes part of the delivered change); alternatively in
|
||||
a fenced machine-readable block in the PR description, or in host-provided
|
||||
durable storage when configured. The record names its own store. Durability
|
||||
means the next re-entry can find and read it without user assistance.
|
||||
`.verified-delivery/handoff.json` in the repository working tree, excluded
|
||||
locally from Git and checked as untracked before every commit; alternatively
|
||||
in a fenced machine-readable block in the PR description after confirming
|
||||
that external disclosure and its rollback path, or in host-provided durable
|
||||
storage when configured. The record names its own store. Durability means the
|
||||
next re-entry can find and read it without user assistance.
|
||||
|
||||
Required fields — `directive` (verbatim user directive), `authorization_boundary`
|
||||
(gates authorized, and anything explicitly out of scope), `repository` (remote
|
||||
identity), `pull_request` (PR identity or null), `head_sha` (head at handoff
|
||||
time), `completed_steps` (gates done, with SHA-bound evidence), `pending_steps`
|
||||
(next authorized gated steps in order), `watchers` (active watcher, process,
|
||||
or worker identifiers, or empty), `stop_reason` (observed interruption class),
|
||||
`status` (`open` or `closed`), and `updated_at`. The full field schema,
|
||||
durability rules, and worked examples are in
|
||||
Required fields — `schema` (handoff schema version), `status` (`open` or
|
||||
`closed`), `store` (durable location), `directive` (verbatim user directive),
|
||||
`authorization_boundary` (gates authorized, and anything explicitly out of
|
||||
scope), `repository` (remote identity), `pull_request` (PR identity or null),
|
||||
`branch` (delivery branch), `head_sha` (head at handoff time),
|
||||
`completed_steps` (gates done, with SHA-bound evidence), `pending_steps` (next
|
||||
authorized gated steps in order), `watchers` (active watcher, process, or
|
||||
worker identifiers, or empty), `stop_reason` (observed interruption class),
|
||||
and `updated_at`. The full field schema, durability rules, and worked examples
|
||||
are in
|
||||
[references/interruption-handoff.md](references/interruption-handoff.md).
|
||||
|
||||
## Resumption on re-entry
|
||||
@@ -134,9 +146,10 @@ Stop and report the exact reason, taking no further action, when:
|
||||
request, not a resume);
|
||||
- the handoff is corrupt — unparseable, missing required fields, or
|
||||
internally inconsistent;
|
||||
- the handoff is stale — the PR was merged, closed, or rolled back by
|
||||
someone else, the repository does not match, or the recorded authorization
|
||||
no longer applies;
|
||||
- the handoff is stale — the PR was closed without the recorded change,
|
||||
rolled back, merged with a conflicting head, the repository does not match,
|
||||
or the recorded authorization no longer applies; a matching completed merge
|
||||
with authorized post-merge verification pending is reconciled and resumed;
|
||||
- authorization for the next step is absent or ambiguous;
|
||||
- live state is ambiguous — a gate result or the merge state cannot be
|
||||
determined.
|
||||
|
||||
@@ -10,13 +10,21 @@ A handoff is durable when the next re-entry can find and read it without user
|
||||
assistance. Choose the first available store:
|
||||
|
||||
1. **Repository working-tree file (default).** `.verified-delivery/handoff.json`
|
||||
in the repository root. Keep it untracked so it never becomes part of the
|
||||
delivered change. Survives session and worker replacement on the same
|
||||
working tree.
|
||||
in the repository root. Before writing it, add the exact path to the
|
||||
worktree's private Git exclusion file (`.git/info/exclude`, resolving the
|
||||
worktree git directory when `.git` is a file). Before every commit, verify
|
||||
with `git status --short --untracked-files=all` and `git diff --cached
|
||||
--name-only` that the handoff is neither tracked nor staged. Do not proceed
|
||||
while it appears in either output. This keeps the record out of broad
|
||||
staging commands while allowing it to survive session and worker
|
||||
replacement on the same working tree.
|
||||
2. **PR description block.** A fenced machine-readable block in the PR
|
||||
description, usable when a PR exists and working-tree state may not
|
||||
survive (ephemeral runners, disposable containers). Survives local loss
|
||||
because it lives on the forge.
|
||||
survive (ephemeral runners, disposable containers). Because this publishes
|
||||
the verbatim directive and watcher metadata to forge readers, confirm the
|
||||
PR target, disclosed scope, and rollback path (restoring the prior
|
||||
description) before writing it. Survives local loss because it lives on
|
||||
the forge.
|
||||
3. **Host-provided durable storage**, when the host documents a store that
|
||||
survives session and worker replacement.
|
||||
|
||||
@@ -114,10 +122,14 @@ resumption at that boundary with the exact reason reported:
|
||||
- **Authorization current** — the recorded `authorization_boundary` still
|
||||
reflects a directive the user has not withdrawn. Otherwise: absent or
|
||||
ambiguous authorization.
|
||||
- **Live state consistent** — the PR (when recorded) exists and is open, and
|
||||
the merge state is determinable. A PR merged or closed by someone else, or
|
||||
a rolled-back change, makes the handoff stale: the recorded pending steps
|
||||
no longer describe reality.
|
||||
- **Live state consistent** — the PR (when recorded) exists and its merge
|
||||
state is determinable. If it is open, continue normal reconciliation. If it
|
||||
was merged while `post-merge-verify` remains pending, verify that the merge
|
||||
contains the recorded head and matches the authorized change, record the
|
||||
merge as completed, and resume post-merge verification. A PR closed without
|
||||
that change, a merge containing a conflicting head, or a rolled-back change
|
||||
makes the handoff stale because the recorded pending steps no longer
|
||||
describe reality.
|
||||
- **Head reconciliation** — if the live branch head differs from
|
||||
`head_sha`, head-bound evidence in `completed_steps` is invalid. Re-verify
|
||||
CI and review on the new head, update `head_sha` and `completed_steps`,
|
||||
|
||||
Reference in New Issue
Block a user