--- name: "spectre-execute" description: "Execute tasks/plans with checks/reviews/proof. Use after planning/resume. Not for planning, unplanned fixes, or pruning." user-invocable: true --- # execute Preserve parallelism, authority, gates, repair. ## Inputs - `$ARGUMENTS`: path; `--origin plan|fix`; `--preflight-plan `; wave hints; `--orchestrated`; orchestrated-only `--finalization-owner parent`. Default owner: `self`. - `--review-profile final-only`, valid only with `--orchestrated --finalization-owner parent`; it defers intermediate review and requires the orchestrating caller to invoke `Skill(spectre-code_review)` exactly once; caller owns sequencing, never semantic review. - `structured`: execute index + resolvable `tasks.json`; malformed structured input escalates, never becomes a plan. - `fix-source`: bug-report path/root or identifying content—not `--origin`—selects `fix`; load `references/fix-source.md`, not Plan preparation. - `plan-direct`: explicit readable plan, including paths, Plan handoff markers, and legacy `Execution Mode: direct` headers. The explicit supplied plan wins over ambient task artifacts and enters this preparation contract. - No path: use existing same-run source evidence first, then a plan at the confirmed root, then structured-only fallback. No-path selected plans receive this preparation before dispatch. Never infer from branch/recency. - `--preflight-plan ` remains a preparation-depth hint, not authorization, classification, or task-graph switch; a depth hint must not create authority pause. `Execution Mode: direct` is a legacy coordination hint. No selected readable plan needs a completeness/header ceremony. ## Working Set - Reuse a managed `FEATURE_ROOT` only when explicit/current-thread evidence ties it to this work (physical directory wins; never branch/recency/lifecycle/scans); distinct work ignores ambient roots. Otherwise, including on collision, standalone MUST first load and follow `@skill-spectre:spectre-feature-root` through DONE; orchestrated calls escalate. Keep writes beneath it and pass it unchanged. - Keep the invocation checkout. - Structured detail precedence: declared `Tasks JSON` → adjacent `tasks.json` → sibling `.tasks.json`; else escalate. Read whole; detail targeted slices. - Structured/plan-direct read `references/telemetry.md`, start/resume local event run with origin, follow primary/worker authority. Local workflow store is the sole lifecycle/progress authority; plans/tasks immutable. Summaries retain origin/shape/category/elapsed/aggregate tokens; Plan-direct emits events. Telemetry failure degrades observation, never delivery authority. - `SCOPE_DOCS`: manifest paths or scope/UX/research cited by the plan. - On first selected readable-plan use/resume, read `references/plan-direct.md` for preparation state. On the first verification failure, review finding, E2E gap, or proof failure, read `references/repair-policy.md`. - Maintain compact verification ledger by HEAD, check id, changed/dependency surface, result, attribution, disposition; controls reruns. Never persist raw output or per-wave evidence/checkpoint/report files. ## Outputs + DONE - Commit implementation batches/canonical artifacts. Task/plan immutable; Execute evidence/state local/uncommitted. - `self`: one final comprehensive review; proof ends `PASS`. - `parent`: `IMPLEMENTATION_READY` + `ACCEPTANCE_PENDING` manifest; no final review, proof, or acceptance claim. With `--review-profile final-only`, every phase records `final-only` and the parent receives `FINAL_REVIEW_PENDING`. - DONE: selected work/adaptations `done|skipped`; current affected verification; each phase `final-only` or reviewed once for recorded compounding risk; every finding dispositioned; no safe authorized work or stale/uncovered final surface; self final review + end-only proof when applicable; no primary-authored planned work; structured telemetry complete or honestly `degraded`. ## Method / guardrails - **Plan preparation.** For selected readable plans, resolve root, plan, Scope, depth/state before run creation. Reuse applicable `task_context.md` assessment by plan/authority hashes; after scope-safe byte-only review edits, rebind if topology/uncertainty is unchanged; reroute only if absent/materially invalidated. Missing assessment dispatches `Skill(spectre-plan-route)` to a fresh child agent for one classification. Hash-bound observed size, never depth, decides Plan Review: XS/S record `review:not-required:` and skip; M+ reuse a closed correctness+simplification chain only with external-attempt/recorded-failure+fallback provenance, completed route/reports, finalized plan hash/disposition, and protected files unchanged; reject route-only/interrupted/`NOT DONE`; else resume hash-valid or user-decided partial correctness or dispatch `${CLAUDE_PLUGIN_ROOT}/skills/spectre-execute/references/plan-review.md --auto-apply scope-safe --orchestrated` once to fresh child. Review-worthy risk reclassifies M+; no hidden XS/S exception. Mechanical repairs stay local; semantic corrections use child. Scope/explicit-design changes remain withheld; scope-safe result proceeds without a second user gate. ATOMIC/DIRECT use the bounded local workstream/Active Wave pattern. For STRUCTURED, pass finalized plan path/hash, closed review evidence, and assessment depth; STRUCTURED dispatches a fresh child with `${CLAUDE_PLUGIN_ROOT}/skills/spectre-execute/references/create-tasks.md --orchestrated` (L → standard, XL → comprehensive). No automatic task review; when a user explicitly requests a task-graph audit, load `${CLAUDE_PLUGIN_ROOT}/skills/spectre-execute/references/task-review.md`. Select only a validated pair bound to finalized plan and closed review chain. For all preparation children, consume child DONE inside the same Execute run before proceeding. 2. **Resolve and resume.** Persistent execution authority: on initial entry and every continuation/resume, including after compaction, reload this contract with original source arguments and continue the same durable run; never implement from memory or substitute another workflow. Rebuild the frontier from the store: `run start` with original `--source` returns the same `runId`; `run status --run-id --json` reports it. Compare selected source/preparation hashes before trusting mappings; `references/plan-direct.md` owns hash-bound pair reuse and source-mode continuity. Fresh structured selection persists its resolved JSON event source so resubmitting the plan resumes the same run. Trust only `completed`/`skipped`; every other value is redo-or-verify. `INVALID_TASK_TRANSITION` means the log is ahead: re-read, never force. Source order alone does not block concurrent dispatch; detail only the ready frontier. 3. **Batch and dispatch.** Read `references/parallel-scheduling.md` before first dispatch; apply it to every source and frontier. Waves guide; phases bound review. Batch at most three sequential parents or bounded plan-direct workstreams. Assign plan-required real-input probes to `@spectre:dev` before dependent implementation; independent ready work may proceed. Require a sanitized real capture/fixture and observed result against the plan's stop condition; static inference cannot replace them. Every source-owned workstream, including single/sequential work, goes to `@spectre:dev`; the primary only orchestrates, verifies, accepts, and records state; it never implements planned work. For `risk`, use Claude `claude-opus-5-5` or Codex `gpt-6-sol`; otherwise defaults. Give exact assignment, context, threatened invariant, and shared contract; omit unrelated ids. Structured dispatch includes exact ``. Require the worker to load `${CLAUDE_PLUGIN_ROOT}/skills/spectre-execute/references/tdd.md`, run focused checks, commit, return compressed insights, and report E2E `Complete|Gap|Adaptation`. 4. **Gate accepted batches.** Before any reviewer, the primary independently runs affected lint/typecheck/build and native focused non-harness tests selected from the returned diff and demonstrated dependency/consumer boundaries; gate batches while other assignments remain in flight, letting early parents ride the next covering gate. Never run a repository baseline/root suite, full app harness, benchmark, or broad qualification here. Record stable check ids/result against current HEAD without raw output or new evidence files. Attribute failures and follow `references/repair-policy.md`; implementation reports are leads only. 5. **Capture boundaries.** After exact run/work identity, invoke `Skill(spectre-work-record)` once at start with truthful intent/scope. Workers return compact findings/evidence; after each accepted batch primary invokes `Skill(spectre-capture)` only for qualifying reusable knowledge. For meaningful blocked handoff/resolved resumption, invoke `Skill(spectre-work-record)`; never task, batch, check, review, commit, or routine-progress update. At terminal completion `run finish` first, then invoke `Skill(spectre-work-record)` once with truthful seven-section account and `--source-run-id `; capturing earlier leaves a start-only delivery receipt Ship can never select. Authorized successful `self` sends `execution: finalized` with `remainingWork: "None."`, independent of Ship, any PR, and later review/CI/merge/closure; `parent` stays `IMPLEMENTATION_READY`/`ACCEPTANCE_PENDING`; blocked/failed/incomplete runs stay non-final with truthful residual work. Capture failure does not block verification, review, proof, lifecycle authority, or delivery; return recovery input. 6. **Record and adapt.** Record accepted completion only in local state; emit primary completion against passing gate; worker submission never acceptance. Never mutate source task/plan artifacts for lifecycle state. Add/split/skip/reorder only source-required derivative work; amend the canonical graph only when its definition was wrong. New derivatives join when assigned. 7. **Route intermediate review by compounding risk or final-only profile.** With `--review-profile final-only`, record each verified completed phase as `final-only` without loading review routing or dispatching a reviewer. Otherwise a phase may be reviewed only after all source-owned tasks/workstreams and adaptations are `done|skipped` under current affected verification; completion alone is not a trigger. On first phase completion, read `references/review-routing.md`. - Inputs: phase diff/commits/files, risk, scope, verbatim requirement/AC slices—not dev rationale, pending phases, unrelated files. - Check named risk, Defined → Connected → Reachable, E2E completeness, security/correctness, dead/orphaned outputs, duplicate sources, old active paths. - Return `CLEAN` or evidence-backed CRITICAL/HIGH with `file:line`, invariant, observable scenario, evidence chain, smallest in-thread fix. Persist only local route/dispositions, never an intermediate review report. Follow repair policy: one consolidated pass, affected verification, no repair re-review. 8. **Repeat** until the selected completion projection is satisfied. ## Finalization Compute coverage from the ledger. Run only stale or uncovered checks; never blanket-rerun cumulative verification or a root suite. Expensive harness/performance/full qualification runs only for the final relevant candidate unless a source task produces a prerequisite or product-consumed qualification artifact blocking downstream work. Cache by `candidate definition hash = relevant inputs + scenario/config + command`; permit one run per hash, rerun only after changed inputs or diagnosed infrastructure invalidation. - `parent`: require wave gates/review dispositions. Return diff/base, commits/files, test roots, coverage, review route, repair ledger, requirement slices, findings, and `ACCEPTANCE_PENDING`; add `FINAL_REVIEW_PENDING` for final-only, requiring one opposite-runtime-first `Skill(spectre-code_review)` before proof. The manifest names `${CLAUDE_PLUGIN_ROOT}/skills/spectre-execute/references/proof.md` and its tuple-bound Validate step as pending acceptance; parent mode ends here and the caller owns that sequence. - `self`: invoke `Skill(spectre-code_review)` exactly once, high effort, over cumulative diff + requirements/scope without implementer rationale. Structured mode passes completed requirement/AC slices; plan-direct passes `PLAN_SOURCE` plus relevant `EXECUTION_STATE` evidence as routing only. It owns delivery/reachability, scope-creep, dead-computation, old-path, and single-source audits. Record its result as a review gate. Give attributable CRITICAL/HIGH one consolidated repair pass, affected verification, and honest dispositions. - After review dispositions are recorded, load `${CLAUDE_PLUGIN_ROOT}/skills/spectre-execute/references/proof.md` once over the final authoritative source and current candidate. This reference invokes `Skill(spectre-validate) --orchestrated` with the same source, resolved `FEATURE_ROOT`, and complete `BASE_SHA`/`HEAD_SHA`/`DIFF_SHA256` tuple, then observes uncovered journeys. Persist validation report, status, and tuple in Proof; a `PASS` requires status `Complete` for the exact current tuple. Any `Partial`, `Dead Code`, or `Missing` requirement blocks aggregate PASS and follows the existing repair policy, with fresh current-candidate validation after repair. A genuine authority block is reported truthfully. Parent `ACCEPTANCE_PENDING` names this Proof reference and tuple-bound validation as its pending acceptance step. Static validation and observed journeys remain distinct. Record Proof as the final acceptance gate; after repair, use targeted rechecks from `references/repair-policy.md` before another full current-candidate Proof pass; do not terminalize until aggregate `PASS` or every remainder is `NEEDS_AUTHORITY`. Formatting, lint, artifact, rebase, or commit-only changes do not trigger reproof. Finish structured runs with the truthful terminal event. - After that authoritative terminal status, follow the telemetry reference to emit one non-authoritative `plan.execution_outcome`; Plan/Execute artifact joins use SHA-256 hashes of raw artifact file bytes, and join failure only degrades telemetry. ## Handoff Parent: machine `IMPLEMENTATION_READY`/`ACCEPTANCE_PENDING` (+ `FINAL_REVIEW_PENDING`), no table. Self terminal: returns counts/coverage/review/dispositions/owner/proof/findings/`RUN_ID`/telemetry. Companion opens same resolved local file beside conversation; outside same clickable link/no failure; Never publish/share proof. | Handoff | Details | |---|---| | 🧭 **Current phase** | Complete/recovery. | | 📦 **What was just done** | Delivery/impact. | | ▶️ **Proposed next step** | Render resolved action. | | 🔎 **Review proof** | Render Markdown [Review proof](/absolute/resolved-feature-root/proof/proof.html); substitute absolute FEATURE_ROOT. | `What was just done` contains delivered capability + user impact only; must not include test/review/proof verdicts. Put counts/coverage/review/dispositions/owner/RUN_ID/telemetry outside the table. High → Fix; coverage or any other closeout → `/spectre:spectre-ship`; blocked/failed → same table/exact resolved recovery action. ## Escalate-If - Missing/malformed structured index/task detail → rerun `/spectre:spectre-execute ` from the original readable plan; if no readable plan exists, report `NEEDS_AUTHORITY` against the malformed source. - Unreadable source, Scope change, unresolved correctness Blocker/High, explicit-design contradiction, unavailable authority, or invalid generated pair → `NEEDS_AUTHORITY` before task generation/delivery. - Invalid parent ownership; `--review-profile final-only` without an orchestrated caller that explicitly owns the one final `Skill(spectre-code_review)` invocation; unsafe/unrelated prompt slice; conflicting acceptance; unavailable authority/capability; required scope change; or unauthorized destructive action. - Never escalate solely for check failure, unavailable/red baseline, review/proof finding, diff growth, or related-file changes; continue independent work and terminalize only when every remaining non-PASS row is `NEEDS_AUTHORITY`.