Nuke Exec

Nuke Exec

The family's one executor (map: references/family-map.md — producers spec/audit/review feed it; verify closes behind it). It runs in one of two input modes, resolved at preflight:

• spec mode — the argument is a path to a family spec (fix-spec.md from nuke-audit/nuke-review, spec.md from nuke-spec, an escalation spec from nuke-verify, or any file following references/fix-spec-template.md). Executed phase by phase until everything meets the quality bar recorded in the spec's executor context.
• task mode — the argument is task text (or a brief file that is not a family spec). Preflight distills it into a contract — 2–5 falsifiable done-criteria plus non-goals — and the contract is executed as a single phase. No spec required; the contract stands in for one.

Core principle — asymmetric verification: weak generation + strong verification + fix loop = strong output. Validators are always one tier above implementers.

Arguments

[mode] — light | full | plan. If omitted: spec mode uses the mode: recorded in the spec header, defaulting to light; task mode defaults to light. plan runs preflight, prints the plan block, and STOPS — nothing is written. <input> — a spec path → spec mode; anything else (inline text, a notes/brief file) → task mode. The spec-mode test is countable, never judged: the file has an ## Executor context heading, at least one ### Batch heading, and Accept: lines — all three, or it is treated as a task brief and the downgrade is named in the plan block, never silent. --ask — pause at the preflight plan for confirmation; default is no gate — the plan prints and the run starts (references/preflight.md).

Modes

Tier vocabulary (clerk/worker/session/top) and per-platform mechanics: references/model-tiers.md. Respect the fallback: platforms without per-agent overrides → every role inherits the session model.

Everything else is shared between input modes: the per-phase loop, the progress file, the gates discipline, and the report.

Mandates

1. Respect the mode and the tier table. Never silently upgrade or downgrade a role's tier. Light never spawns a validation wave where one validator suffices; full never shrinks a wave to save tokens.
2. Main context stays thin. The orchestrator reads only the spec or contract, the progress file, and agent summaries. All implementation and validation detail lives inside subagents.
3. Fix everything. Every task, every severity — including low and info. Skipping anything is failure, not triage.
4. Implementers never validate their own work. Validation is always fresh agents, one tier above.
5. No git add / git commit / git stash. No .bak files. The working tree is left for human review.
6. Evidence before claims. No success statement without pasted gate output — verbatim, never summarized — and per-task validated acceptance criteria.
7. Escalate instead of guessing. An implementer whose task's Accept: (or done-criterion) is not mechanically checkable (grep, test run, or quoted line) stops and returns the task to the orchestrator with the ambiguity named — it never improvises an interpretation.
8. Escalate instead of stretching (task mode). More than 5 done-criteria, contradictory requirements, or >~10 files → STOP and recommend nuke-spec (spec → exec). A hard design call → nuke-think before dispatch. Implementers never receive a vague ask — a cheap model amplifies vagueness into invention.
9. The ledger precedes the wave. No implementation wave dispatches before the plan block has printed and exec-plan.md (or task mode's plan.md), exec-progress.md with every phase listed as pending, and exec.md exist on disk. Any of them missing, or exec-progress.md listing fewer phases than the spec → back to Phase 0. None of this waits on the user — materialize, then move, same turn.

Phase 0 — Preflight

Read references/preflight.md and run its steps. Preflight never asks — the plan prints and the run starts (--ask is the only gate, plan the only stop) — but it always materializes before it moves: the run ledger below is written to disk first, wave 1 dispatches immediately after, in the same turn.

Spec mode:

1. Read the spec fully. It is self-contained: executor context (quality bar + tier assignments), per-path-prefix Gates table, file-type → skill map, dependency-ordered phases, batches, tasks, coverage map including U-### unverified entries.
2. Re-measure every task yourself — files touched and touched-file mass (wc -l, run now) against the tier ceilings in references/fix-spec-template.md rule 8. Never trust the spec's own sizing: an architect that wrote oversized tasks did not flag them either. Any task over the executing tier's ceiling → apply the nuke-split protocol inline now (seam rules and all), write <spec>.split.md next to the original, execute that instead, and note split: applied inline (N tasks → M) in the plan block. Oversized work is never handed to an implementer that cannot hold it — and never bounced back to the user to go run nuke-split by hand.
3. If an exec-progress.md (or a legacy fix-progress.md) exists next to the spec, resume from the first incomplete phase instead of starting over.

Task mode:

1. Contract (Mandate 8): distill the task into 2–5 falsifiable done-criteria, non-goals, and constraints from the repo's instruction files — read now, not recalled. A brief file is consumed as-is when its criteria are falsifiable. No resolvable contract → ask the user.
2. Shape the work: read the files the task will touch (orchestrator-level skim: exports, structure — not full contents into context); cut the file plan into batches of disjoint files at the worker ceilings of references/fix-spec-template.md rule 8 (≤3 files per task, ≤3 tasks per batch — one concern ≈ one file as the target, the same cut nuke-split makes on specs). The contract + batches form a single-phase plan executed by the shared loop below.

Both modes — baseline. Resolve the per-path-prefix gates table and the file-type → skill map (references/stack-adapters.md; spec mode reads them from the spec), run every matching row once, then act by row:

The run ledger — materialized in order, then the wave (Mandate 9):

1. Print the plan block with the full round breakdown — always printed, never asked about (gate only with --ask; plan → print and stop):

   ## Nuke Preflight — nuke-exec (spec mode)
   spec: .nuke/2026-07-02-141530-src-engine/fix-spec.md · mode: light
   phases: 3 · batches: 7 · tasks: 19 · re-measured: 0 oversized (wc -l)
   phase 1 (structural): 1.A [T-001..T-003] · 1.B [T-004..T-005]
   phase 2 (extractions): 2.A [T-006..T-010] · 2.B [T-011..T-014] · 2.C [T-015..T-016]
   phase 3 (tests + docs): 3.A [T-017..T-019]
   tiers: implementers worker · validators session · final sweep session
   skill map: .ts → typescript-best-practices · .tsx → react-senior-guide
   baseline: tests PASS · typecheck PASS · lint FAIL (2 errors → adopted as T-000)
   estimate: exec band — ~10–16 agents (7 implementers + per-phase validators + fix cycles)
   

   Task mode: the phase lines are replaced by the contract (done-criteria + non-goals) and its batch list.

2. Write the preflight record: spec mode → exec-plan.md next to the spec (never plan.md, so a spec run's own plan.md survives); task mode → plan.md in a fresh run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-exec-<slug>/, on collision append -2, -3, ….

3. Write exec-progress.md beside it, prepopulated with EVERY phase, its batches, and its task range — all pending (format below; task mode: the contract as one phase with its batches). This is the file resume reads — a run that skipped it cannot be resumed.

4. Write exec.md next to that — the evidence record: per-batch results, validator verdicts per cycle, gate outputs verbatim, final verdict. The Report reads from exec.md; exec-progress.md tracks phase state.

5. Dispatch wave 1 — same turn, nothing to wait for.

Progress format (exec-progress.md)

Written at Phase 0 exactly in this shape — every phase listed before any of them runs, all pending. Updated after EVERY validation cycle (the Cycles column), not just at phase completion, and reprinted to the user at each phase boundary.

# Exec Progress
input: fix-spec.md (spec mode) | mode: light | started: 2026-07-02
baseline: tests PASS · typecheck PASS · lint FAIL (2 errors — adopted as task T-000)

| Phase | Batches | Tasks | Status | Cycles | Notes |
|---|---|---|---|---|---|
| 1 — structural | 1.A, 1.B | T-001..T-005 | pending | — | |
| 2 — extractions | 2.A, 2.B, 2.C | T-006..T-016 | pending | — | |
| 3 — tests + docs | 3.A | T-017..T-019 | pending | — | |

Per-phase loop

For each phase in spec order (task mode: the contract is one phase):

1. Implementation wave — one subagent per batch, all batches of the phase in parallel (they touch disjoint files by construction). Each implementer receives:
   • the spec's Executor context block + only its own tasks, copied verbatim — task text, file lists, and Accept: lines exactly as the spec wrote them, never paraphrased by the orchestrator; paraphrase is where constraints die (task mode: the contract verbatim + its batch)
   • write ownership of only its batch's files
   • the mandatory skill list for its file types from the file-type → skill map, plus the nuke-lean charter — load before writing
   • return format: per task → status, files changed with line refs, deviations from the spec or contract; a non-checkable Accept: → escalate per Mandate 7
2. Validation — fresh subagents one tier above the implementers, never the implementers (light: one session validator for the whole phase; full: a top wave). Validators receive the spec or contract, the diff, and repo access — never the implementers' reasoning; the missing anchoring is the design:
   • per task: acceptance criteria (task mode: done-criteria, met | partial | unmet) verified mechanically with file:line evidence and a quoted line each
   • re-audit of every changed file against the quality bar — hunting issues the changes introduced (new duplication, new slop, broken callers of changed contracts, regressions, convention drift) via the four charter bundles of references/lens-catalog.md over the diff and its blast radius. Findings use the family schema (lens + severity + justification, file:line, quoted source, numbered trace, proposed fix, refutation attempt); a finding missing a field is invalid and must not be reported
   • re-judge every U-### entry the coverage map routes to this phase (spec mode): real → add to the fix loop as a task; not real → close with a written reason in exec-progress.md
   • run the Gates-table rows matching the phase's changed path prefixes, full output captured
3. Fix loop — any failed criterion, failed gate, escalated task, or new finding of any severity → dispatch fix subagents with the exact findings → re-run validation; bump the phase's Cycles column in exec-progress.md every cycle. Repeat until clean. Cap per phase (light: 3 cycles, full: 5) — if hit, stop, record honest status in exec-progress.md, and report the remaining issues. Never proceed past a dirty phase.
4. Mark the phase done in exec-progress.md only when validation is fully clean, and reprint the progress table to the user before dispatching the next phase.

Final verification

After the last phase:

1. Every Gates-table row — capture outputs verbatim.
2. Final sweep over the complete changed-file set, per the mode table above.
   • Completeness checklist: every T-### / done-criterion done, every coverage-map ID (F-###/REQ-###) resolved, every U-### fixed or closed-with-reason, no .bak files, no debug leftovers, no commented-out code.
3. Anything found → one more fix loop, then re-sweep.

Report

• Input mode, the final exec-progress.md table verbatim, issue counts fixed per phase, U-### dispositions (spec mode)
• Gate outputs (verbatim — no summaries in place of evidence)
• Append the run's calibration line to .nuke/calibration.log (format in references/preflight.md)
• Verdict: "CLEAN — every task validated, all gates pass, working tree ready for review (nothing committed)" — or the honest list of remaining blockers and exactly where the run stopped
• Task mode: recommend nuke-verify with the contract as intent when the user wants an independent second pass on the delegated build.

Orchestration notes

• Claude Code: Workflow tool (phases map to phase(), batches to parallel(), the fix loop to a while-loop) or parallel Agent calls with run_in_background. Pass model/effort per agent from the tier table in references/model-tiers.md. With --ask: the gate via AskUserQuestion, options run / switch mode / narrow scope.
• Codex / OpenCode / Cursor / other CLIs: spawn subagents per batch, mapping tiers to their model flags. Sequential fallback: one batch at a time, each in a FRESH context, same validation protocol.
• If the environment offers isolated worktrees and two batches unexpectedly conflict, isolate them; otherwise serialize the conflicting batches — never let two agents write the same file concurrently.