Skip to content

j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan/execute

deepworkplan-execute

Verified

Execute Lite or Full Deep Work Plans task-by-task — select validation from the actual surface, preserve state and evidence, recover safely, and finish with the Final Review.

FileKindSize
SKILL.mdskill md41.6 KB
delegation.mdmarkdown3.4 KB
orchestrator.mdmarkdown5.2 KB
team-agents.mdmarkdown2.8 KB
v6.mdmarkdown11.6 KB
# Execute — the v6 loop (contract, journal, scheduler, verified closure)

Read this file only when Step 2 of [`SKILL.md`](SKILL.md) detected a **v6
plan**: the plan folder carries a `manifest.json` whose `contract` pointer
resolves, a `contract.json`, or a `contracts/` revision chain. A v1/v2/v5
plan never enters this loop — it keeps the recorded lifecycle above
(RFC 9.2), and this pack never migrates it silently.

Everything not restated here keeps its v5 contract: the consent
checkpoints, the untrusted-content rule, the commit format, per-task
commits only after gates pass, and the Final Review order. What changes is
the **record layer and the closure discipline**: work is recorded in an
append-only journal, selection goes through the deterministic scheduler,
`observed` evidence is minted only by the shipped gate runner, and no task
closes on narrative.

## The one-line model

The **contract** (outcome + acceptance criteria + scope + envelope) is the
authority; the **journal** is the memory; **helpers** do the writing; the
**snapshot and views are projections** — never hand-edited. If the journal
and a generated file disagree, the journal wins and the file regenerates.

## Re-anchor (every task, cheap by construction)

Before selecting work, derive — never recall — where the plan stands:

```bash
python3 ../shared/ledger.py --plan <dir> inspect          # events, one line each
python3 ../shared/context_manifest.py --plan <dir> manifest --task <T-id> --md
```

The manifest carries the acceptance/authorization boundary verbatim
(pruning cannot drop it), the dead-end digest (failed gates, refusals —
retention-biased), and freshness: an `exit 1` means a summary no longer
matches its inputs — re-derive from the records, never patch the summary.
History beyond the manifest loads **only on its declared triggers** (a
task's `Read Before Starting`, a decision the digest points at).

## The task loop

For the task the scheduler selects (strict order, one at a time):

0. **Capacity** (agentkit addon enabled) — `python3 ../shared/swarm.py
   capacity --plan <dir> --pane <pane> [--context-pct N]` (pass the context
   share when the agent knows it) before each task and after any step longer than 20
   minutes. `continue` → go on; `prepare` → finish only a task you can
   finish, report `capacity=low`. `handoff` with reason `hysteresis` (your
   packet is already pending) → stop, never write another. A
   `pending_packet` from another pane → accept it through resume before
   working. Any other `handoff` → reach a safe
   point, `swarm.py handoff write` **once**, notify the lead, stop
   ([`../guide/swarm.md`](../guide/swarm.md) §17.3–§17.6). Capacity
   *unknown* is not *ok*: a CLI limit warning still means hand off.
1. **Select** — `python3 ../shared/scheduler.py ready <dir>`. The core is
   read-only: it refuses cycles, unmet prerequisites, already-complete
   tasks and any task whose declared invariants were never evaluated (or
   were evaluated before the current task start — D3-6). Its decision, not
   the model's, is the dispatch.
2. **Start** — `python3 ../shared/ledger.py --plan <dir> start --task <T-id>`.
   Refused (exit 3) until a materialization-time `approval` event cites the
   live `contract_id`, and refused (exit 3, a recorded `refusal`) while any
   of the task's declared `prerequisites` is not complete — the scheduler's
   `ready` order is enforced at start, not only advised (7.1.5); on start it records the task's starting fingerprint
   (revision + dirty state) — the control-pair old leg later materializes
   from exactly that record.
3. **Implement** the task's objective (its file is the work instruction;
   the skills and documentation decisions happen here as in Step 5 rule 2).
   On a v7 plan that grants `agent_delegation`, a `parallel_safe` task MAY
   be implemented by a delegate instead — read
   [`delegation.md`](delegation.md) first; its result is asserted until
   step 4 here observes it.
4. **Gate, through the runner** — for each criterion the task's
   `gate_intent` declares:
   `python3 ../shared/ledger.py --plan <dir> gate --task <T-id> --criterion <AC-id> --json '"<command>"'`
   (the command is a JSON string — the runner shell-executes exactly that
   text; an argv array executes directly with no shell). The helper
   executes the command itself (declared cwd/timeout, log kept under
   `gates/<task>/`), binds the run to the criterion, and reuses prior
   evidence only for the **same (task, criterion) on an equivalent
   fingerprint** — the command, the touched surface **and the whole working
   tree** (HEAD plus every changed or untracked path), so a fix anywhere
   runs fresh; `--no-reuse` always runs fresh. Another linkage runs fresh
   and records its own evidence. **Gates in a container:** declare the
   wrapper as a command class and run through it — `dck exec <service> -- <cmd>` with
   `dck` in `allowed_command_classes` (the runner executes the wrapper, so
   the result is still `observed`).
   Exit status is the gate's — `RAN: exit N` — and `REUSED` lines are
   equivalent-input replay, not a rerun. **Only this runner mints
   `observed` evidence**; an `append --type gate_run` is refused outright.
5. **Controlled criteria** — a criterion declared `controlled` closes only
   on a discriminating pair: `python3 ../shared/outcomes.py --plan <dir>
   control --task <T-id> --criterion <AC-id> --command '<cmd>'
   --artifact <path>`. Only (old FAIL, new PASS) closes; (PASS, PASS) is
   recorded non-discriminating; a dirty start or a non-git host records
   `control_unavailable` — never a synthesized old leg, and never a pass.
   **Asserted criteria** (a human review) close only through `python3
   ../shared/ledger.py --plan <dir> signoff --criterion <AC-id>
   --evidence-path <note> --authority <who>` — the human's sign-off,
   recorded `asserted`, never executed; an agent never signs off for a
   human (spec/V6_CONTRACT.md §3).
6. **Close criteria** — `python3 ../shared/outcomes.py --plan <dir> closure
   --task <T-id>` shows every criterion's state (satisfied / stale /
   waiting). A criterion satisfied only by pre-restart evidence is stale —
   the window reopens on restart.
7. **Complete (guarded closure)** — `python3 ../shared/ledger.py --plan
   <dir> complete --task <T-id>`. Refused (exit 4) while any criterion
   lacks in-window accepted evidence — the zero-test control — or while
   any declared invariant lacks a fresh evaluation: record `INV-<id>:
   pass` (or `INV-<id>: fail: <reason>`) as an observation at or after the
   task's start; the refusal is itself recorded. The exact line, one per
   declared invariant, after the task's start:
   `python3 ../shared/ledger.py --plan <dir> append --type observation
   --trust asserted --note "mediated by the agent self-check" --json
   '{"statement":"INV-<id>: pass"}'` (`asserted`: it is the agent's own
   evaluation, never `observed`; an agent never records a pass it did not
   check). Completion is **derived** (every criterion
   satisfied), never declared, so the snapshot shows `completed` exactly
   when the records support it.
8. **Project and render** — `python3 ../shared/ledger.py --plan <dir>
   project && python3 ../shared/views.py --plan <dir> render --all`.
   Both are deterministic over the records. A generated view that a human
   edited is never silently overwritten — render reports the divergence and
   you reconcile with `--reconcile human-wins|generated-wins --authority
   <who>` (the reconciliation is itself recorded). Update the human layer
   (task log, README task list, `PROGRESS.md`) in the same order as the v5
   loop: log → README → PROGRESS → commit. Never hand-edit `state.json` or
   `views/*.md` — they are projections.
9. **Envelope posture** (when the contract declares limits) —
   `python3 ../shared/resources.py --plan <dir> report` and `hold`. The
   report names each limit's effective mode honestly (journal-computed,
   host-metered, advisory with the reason); `hold` exits 1 while an
   enforced limit's latest `LIMIT: exhausted` observation stands. On
   exhaustion record it (`exhaust --limit <id> --detail …`), persist the
   incomplete checkpoint, and stop dispatch — recovery is an explicit
   `recover --limit <id>` observation, never a silent resume. A cancelled
   in-flight adaptation settles exactly once (`settle --key <seq-key>
   --disposition released|committed`); a conflicting second settlement is
   refused, not arbitrated.
10. **Routing posture** — `python3 ../shared/resources.py --plan <dir>
    routing` states fixed-model/switching and sequential/parallel from the
    contract grants **and** the host abilities. It is an authority
    statement, never an efficacy claim.

## Mid-run adaptations (the closed enumeration)

Retries, splits, reorders, inserts and strategy changes are **proposals**:
compose the proposal, then `python3 ../shared/scheduler.py authorize <dir>
--json '<proposal>'`. The deterministic core decides — scope, acceptance,
permission and envelope expansions are refused and the refusal recorded.
An authorized retry's declared impact lands in the envelope's pending side
automatically. A criterion's content is never carried by an adaptation —
changing acceptance is the amendment path (refine): `python3
../shared/ledger.py --plan <dir> amend --contract <draft> --authority
<who> --note <reason> --human-note <note>` (spec/V6_LIFECYCLE.md §5).

## Interruption and re-entry

Every step is idempotent or refusal-recorded, so re-entry is: re-anchor
(above), then continue at the first open criterion. An interrupted
**materialization** (manifest without contract, or contract without the
approval event) is completed by re-running `materialize` with the same
inputs — never by hand-writing the missing piece. An interrupted
**finalization** leaves the journal simply shorter: re-run project/render.
A torn journal tail repairs itself on the next writer open (recorded as
`journal_repair`). A stale `.ledger.lock` with no live writer is removed
only after checking no writer is active.

## Completion (zero work remaining)

When no task remains: render the views, produce the receipt
(`python3 ../shared/outcomes.py --plan <dir> receipt`) — it recomputes from
the records and changes when they change — and export the evidence chain
for durability (`python3 ../shared/ledger.py --plan <dir> export --dest
<dir>`), since `.dwp/` is conventionally gitignored. Then, if benchmark
mode is on for this repository, run
`python3 ../shared/benchmark.py report --plan <dir>` — the helper itself
decides enabled/disabled (one line when off) and is best-effort: it never
blocks completion. When that run announces a newly created
`learnings.json`, author its curated entries (category, anchor, finding,
proposal — spec section 10) before the Final Review. The Final Review then
runs unchanged from [`SKILL.md`](SKILL.md) Step 7 (security pass with the
required local review, final-state validation, skills and documentation
reconciliation, closure) — over the plan's full accumulated change set.
No handwritten success receipt: the receipt command's output, the
completion view and the exported manifest are the evidence.

## Degraded postures (honest, never blocking)

Missing Python → the record layer is **UNVERIFIED**, report it and stop
(no gate can run through the runner). A missing gate binary → the runner
records the failure; it is a blocker, not a pass. A host without metering
→ the affected limits report advisory with the reason; journal-computed
counters still enforce. An unknown counter family → advisory, the unit
named. Each degraded mode is surfaced by the helper that detects it —
record what it says, never round it up.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall