atlas-workflow 0.9.2 → 0.9.3

package/hosts/zcode/skills/atlas-findings-repair/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: atlas-findings-repair
+description: Skill `atlas-findings-repair`. Corrige findings P0/P1/P2 retornados por `atlas-task-validator` dentro do boundary já executado, sem reabrir o plano completo. Use quando o orquestrador receber `fail` do validator (topologia sibling, única em todos os hosts) e precisar de um reparo enxuto, bounded e sem reusar `atlas-plan-execute`.
+---
+
+# Atlas Findings Repair
+
+Use esta skill apenas no caminho de recuperação pós-validator. Ela **não** substitui `atlas-plan-execute` nem `atlas-direct-execute`; serve só para corrigir findings bloqueantes já emitidos pelo `atlas-task-validator`.
+
+## Finalidade
+
+Corrigir findings P0/P1/P2 dentro do boundary atual com o menor contexto possível:
+
+- sem replanejar
+- sem carregar skill de execução
+- sem criar novas tasks
+- sem ampliar o escopo
+- sem despachar validator
+
+O orquestrador é dono do ciclo sibling em todos os hosts:
+
+1. executor inicial entrega `state_path`
+2. orquestrador roda `atlas-task-validator`
+3. se `fail`, orquestrador trava o ciclo em `repair_required`
+4. orquestrador chama `atlas_lock_validator(action=repair_start, state_path=...)`
+5. orquestrador despacha `atlas-findings-repair` com o pacote retornado pelo lock
+6. esta skill corrige e devolve `repair_complete`
+7. orquestrador fecha o lock com `repair_run_id`
+8. orquestrador roda o **2º e último** validator
+
+## Entrada obrigatória
+
+Receba do orquestrador:
+
+- `state_path`
+- findings estruturados do validator
+- `validator_attempt`
+- `repair_run_id`
+- `repair_budget: 1`
+
+Leia `atlas_run_state` como fonte primária do estado da run. O `state_path` continua sendo a fronteira canônica da slice.
+
+## Regras duras
+
+1. **Não carregar `atlas-plan-execute` nem `atlas-direct-execute`.**
+2. **Não reabrir o plano inteiro.** Corrija só o que os findings exigem.
+3. **Não aumentar boundary** sem evidência estrita de dependência técnica inevitável.
+4. **Não corrigir observações/P3 por capricho.** O foco é fechamento do `fail`.
+5. **Não despachar validator, review ou qualquer subagente.** O orquestrador faz isso.
+6. **Não iniciar terceiro ciclo.** Esta skill existe só entre validator 1 e validator 2.
+7. **Não trocar o `state_path`.** Atualize o arquivo original em lugar; redirecionar o boundary invalida a correlação do repair.
+8. **Não inventar correlação.** IDs devem existir no packet recebido, sem duplicatas; todo arquivo tocado pertence a pelo menos um `repair_evidence` recebido e nenhum arquivo extra é permitido.
+
+## Fluxo
+
+### 1. Ler o boundary
+
+Abra o `state_path` e extraia:
+
+- `files_changed`
+- `diff_stat`
+- `plan_path`
+- `boundary_refs`
+
+Leia do plano apenas o mínimo necessário:
+
+- Section 2 — invariantes
+- Section 6 — contratos técnicos
+- Section 8 — checklist
+
+Capture também `base_sha`, `head_sha`, `task_evidence`, `repair_evidence`, `worktree_baseline` e `worktree_final` do state.
+
+### 2. Ler os findings recebidos
+
+Trabalhe somente com findings de severidade:
+
+- `P0`
+- `P1`
+- `P2`
+
+Cada finding novo deve ter `id`, `failure_mode`, `evidence`, `recommendation` e `fix_validation`. `msg` é compatibilidade deprecated e não substitui esses campos.
+
+Se o pacote vier vazio, inconsistente ou sem finding reparável, pare em `blocked`.
+
+### 3. Montar contrato mínimo de reparo
+
+Antes de editar, reduza o trabalho a:
+
+- finding alvo
+- arquivos a tocar
+- invariante em risco
+- check focado
+- budget de reparo
+
+### 4. Corrigir de forma bounded
+
+Permissões:
+
+- corrigir arquivos do boundary
+- tocar arquivo adjacente apenas quando necessário para satisfazer contrato/invariante
+
+Proibições:
+
+- cleanup oportunista
+- refactor largo
+- nova feature
+- mudança fora da causa do finding
+
+### 5. Rodar gates focados
+
+Rode só validações coerentes com o diff:
+
+- teste alvo
+- lint/analyze/typecheck do pacote afetado
+- `git diff --check`
+
+Se o finding persistir por falta de decisão de produto, dependência externa ou widening de escopo, pare em `blocked`.
+
+### 6. Atualizar evidência
+
+Ao terminar:
+
+- atualize `files_changed` com todo arquivo tocado, inclusive novo/adjacente
+- recompute `head_sha` (`git rev-parse HEAD`) e `diff_stat`; preserve `base_sha`
+- preserve `worktree_baseline` e recapture `worktree_final` após o repair; derive o boundary completo do delta entre snapshots
+- acrescente `repair_evidence[]` no shape `{finding_id, files_touched, checks_run, status}`
+- garanta que cada `repair_evidence.files_touched` esteja em `files_changed`
+- mantenha a mesma slice
+- não invente novo run state paralelo
+
+### 7. Devolver resultado ao orquestrador
+
+Retorne saída curta e estruturada com:
+
+- `status: repair_complete | blocked`
+- `repair_run_id`
+- `state_path`
+- `files_touched`
+- `checks_run`
+- `repairs`: array `{finding_id, files_touched, checks_run, status: resolved|blocked}`
+- `residual_risk` (se houver)
+
+O orquestrador chamará `atlas_lock_validator(action=repair_complete, repair_run_id=..., state_path=<mesmo path original>)` e só então poderá despachar o validator final.
+Antes disso, ele deve ter aberto o slot com `atlas_lock_validator(action=repair_start, state_path=...)`; `repair_run_id` é obrigatório no fechamento.
+
+## Stop conditions
+
+Pare e reporte `blocked` quando:
+
+- finding exige reabrir decisão fechada
+- finding exige ampliar escopo além da slice
+- mesmo erro repete sem sinal novo
+- correção depende de ambiente ausente
+- pacote de findings não é confiável
+
+## Resultado esperado
+
+Esta skill deve ser menor e mais barata que um executor completo, mas ainda disciplinada. Ela repara findings; ela **não** “continua a execução”.

package/hosts/zcode/skills/atlas-findings-repair/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Atlas Findings Repair"
+  short_description: "Repair-only post-validator fixer for bounded findings"
+  default_prompt: "Use $atlas-findings-repair to fix the blocking validator findings inside the current slice boundary without reloading the full executor."
+
+policy:
+  allow_implicit_invocation: true

package/hosts/zcode/skills/atlas-plan-execute/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: atlas-plan-execute
+description: Executa planos produzidos por `atlas-plan-handoff` task-a-task com gates finitos e self-repair local pré-handoff (lint/tests/diff — máximo 2 passes por task). Ao concluir todas as tasks da slice, escreve o state file, para toda mutação e retorna `validator_handoff_required` ao orquestrador para validação fria sibling via `atlas-task-validator`. O orquestrador consome o veredito e decide sobre repair ou fechamento — este executor nunca valida o próprio trabalho nem processa resultado do validador. Use quando o cliente precisar implementar um plano sem derivar dos invariantes.
+---
+
+# Atlas Plan Execute
+
+Use this skill to turn a `atlas-plan-handoff` artifact into a controlled execution loop.
+
+Prefer finite, stage-based execution over continuous self-critique. The goal is to finish the task with high confidence, not to keep polishing indefinitely.
+
+---
+
+## Execution Model
+
+Operate as a bounded state machine:
+`ready` → `implementing` → `gating` → `repairing` (self-repair LOCAL, gates pré-handoff) → `task_done` → `validator_handoff_required` (or `blocked`).
+
+`repairing` cobre exclusivamente falhas de gates locais (lint, analyze, tests, diff-check) introduzidas pelo diff corrente — máximo 2 passes por task. O executor não entra em `repairing` pós-validação; qualquer repair pós-veredito é de responsabilidade do orquestrador via `atlas-findings-repair`. Após `task_done` para todas as tasks da slice, o executor escreve o state file e transita para `validator_handoff_required` — não existe `slice_validating` nem `slice_done` no escopo deste executor.
+
+## State persistence
+
+Use `atlas_run_state` as the primary source of run state. Do not read or write run ledger files directly. If the MCP is unavailable, report the gate as unprovable and abort instead of continuing with a silent file fallback.
+
+## Executor liveness checkpoints
+
+Depois de carregar esta skill e antes de qualquer discovery longo, emita um checkpoint MCP:
+
+```json
+atlas_lock_dispatch({
+  "action": "checkpoint",
+  "phase": "plan_execute",
+  "event": "executor_started"
+})
+```
+
+Em seguida, emita checkpoints materiais conforme avança:
+
+- `skill_loaded` — skill carregada e contrato reconhecido.
+- `plan_loaded` — plano/PRD de entrada lido.
+- `handoff_accepted` — `plan_path`, `state_path` alvo, boundary e tasks aceitos.
+- `task_started` — primeira task começou.
+- `first_write` — primeira mutação de workspace feita.
+- `state_path_created` — state file escrito antes de devolver `validator_handoff_required`.
+
+Se não conseguir emitir checkpoint por MCP, retorne `blocked`: liveness não é comprovável. Não fique em discovery/preflight interno sem checkpoint. O orquestrador trata ausência de checkpoint como `stalled` via Gate G12.
+
+## Plan path resolution
+
+Resolve plan paths in this order:
+
+1. `.atlas/plans/`
+2. `.cursor/plans/` with a deprecation warning
+3. `.codex/plans/` with a deprecation warning
+
+New or rewritten plan artifacts must use `.atlas/plans/`.
+
+## Host adapter
+
+This skill is host-agnostic. To resolve any host-specific verb (subagent dispatch, native todo tool, plan paths), call the MCP tool `atlas_capabilities` first and use the returned descriptor. Canonical reference: `packages/orchestrator/references/host-adapters.md`. Do not hardcode a host name in reasoning — read it from the descriptor.
+
+## Native todo mirror
+
+When entering `implementing` for the first time in a slice, mirror the plan tasks into the native todo surface named by `atlas_capabilities.todo_tool` (e.g. `TodoWrite` on Claude Code, `tasks` on Codex App). If `todo_tool` is `null`, proceed without a mirror — do not invent a tool.
+
+The plan is the SSoT. Map `ready` to `pending`, `implementing`/`gating` to `in_progress`, and `task_done` to `completed`. If todo state diverges, sync from the plan to todo, never from todo back to the plan. Do not create parallel todos that are not derived from plan task IDs.
+
+## Review gate
+
+`atlas-slice-review` is dispatched only when `--review` is present in the user command or executor arguments. Without `--review`, the orchestrator closes the slice upon receiving `pass` or `pass_with_observations` from the validator — this executor is not involved in that decision and never observes the validator verdict directly.
+
+## Entrada via modo `execute` (PRD D1/D13)
+
+Esta skill aceita entrada pelo modo `execute` do orquestrador: um `PLAN_*.md` pronto de pipeline curta, apontado diretamente e já reverificado na entrada (`atlas_verify_artifact` + TC) pelo orquestrador. **A entrada `execute` é o mesmo executor, com as mesmas garantias** — o contrato não muda: o state file (`.atlas/state/<run_id>/<slice>.json`) permanece **obrigatório** e o `atlas-task-validator` (validador frio, só `state_path`) permanece **obrigatório** antes do relatório final. Não há caminho de execução sem state file nem sem validador, em nenhum modo de entrada.
+
+---
+
+## Required Workflow
+
+### 1. Load the plan as an execution contract
+First, emit `executor_started`, then `skill_loaded`, before doing any long scan.
+
+Read the `atlas-plan-handoff` artifact. Extract at minimum:
+* **Execution metadata**: Prefix, mode, and validator options.
+* **Executive translation and PRD links** (from Section 1 — include path to PRD; cite `PRD §3` D* IDs, do not paste the full D* table).
+* **Execution invariants** (from Section 2).
+* **Current state at sprint opening** (from Section 4 — not Section 2).
+* **Pitfalls** (from Section 3).
+* **All execution tasks TNN** (from Section 5).
+* **Technical contracts** (from Section 6).
+* **Slices of execution** (from Section 7).
+* **Checklist for the validator** (from Section 8).
+
+Treat headings as semantic. If the plan uses equivalent wording but carries the same contract, continue. If the plan is missing the substance, stop and report. 
+The old Gate of Readiness (§15) and Handoff Prompt (§16) are **no longer required** in the compact template.
+If optional Section 9 (open questions / real blockers — **not** PRD §7 Apêndice/Referências) has active blocking items, stop execution and request clarification.
+
+When Section 8 checklist is thin, read **PRD §4–6** from the PRD path in the plan header for business acceptance.
+
+After the plan is loaded, emit `plan_loaded`. After validating the execution boundary and `state_path` target, emit `handoff_accepted`.
+
+### 2. Create a task-scoped execution contract
+Before editing code, write a short task contract for the current task only (objective, files, invariants, local checks, and repair budget).
+
+### 3. Implement in the smallest coherent slice
+Do not implement the entire feature before validating anything. Prefer one task at a time. Follow closed decisions from the plan.
+
+Before the first concrete task, emit `task_started`. After the first workspace mutation, emit `first_write`.
+
+### 4. Run a focused quality gate after each task slice
+Run only the checks that are relevant to the current diff and task risks (linter, analyze of the affected package, or tests).
+
+### 5. Repair only what the current diff introduced
+If the gate fails, classify the outcome as `fixable` (maximum 2 repair passes per task) or `blocked`.
+
+### 6. Enforce hard stop conditions
+Stop repair and move to `blocked` when budget is exhausted, the same failure repeats twice, or the fix requires reopening closed plan decisions.
+
+### 7. Close the task with evidence
+Mark a task complete and move to the next. Once all tasks are `completed`, write the state file and transition to `validator_handoff_required`.
+
+### 8. Write the state file and hand off to the orchestrator
+After all tasks in the current slice are complete, write the state file boundary. The cold validation runs as an isolated **sibling** dispatched by the orchestrator — never by this executor (see below).
+
+#### State file boundary
+
+Create `.atlas/state/<run_id>/<slice>.json` following `packages/templates/STATE_FILE_SCHEMA.md`:
+
+```json
+{
+  "run_id": "<run_id>",
+  "slice": "<slice id>",
+  "base_sha": "<base commit explícito do plano/handoff>",
+  "head_sha": "<git rev-parse HEAD ao fechar a execução>",
+  "contract_kind": "plan",
+  "tasks": ["T01"],
+  "files_changed": ["relative/path.ext"],
+  "diff_stat": "N files, +X -Y",
+  "plan_path": ".atlas/plans/<id>.plan.md",
+  "boundary_refs": ["§2.I1", "§6.1", "§8"],
+  "obligations": [],
+  "invariants": [{"id": "I1", "requirement": "<invariante>", "expected_evidence": ["<path/check>"]}],
+  "scenario_probes": [{"id": "S1", "scenario": "<cenário>", "expected": "<resultado>"}],
+  "risk_probes": [{"id": "R1", "risk": "<risco>", "probe": "<pergunta verificável>"}],
+  "validation_map": [{"obligation_ids": [], "checks": ["<comando>"], "status": "passed"}],
+  "task_evidence": [{"task": "T01", "files": ["relative/path.ext"], "checks": ["<comando>"], "result": "passed"}],
+  "repair_evidence": [],
+  "worktree_baseline": [{"path": "relative/preexisting.ext", "status": "M", "sha256": "<64 hex>"}],
+  "worktree_final": [{"path": "relative/preexisting.ext", "status": "M", "sha256": "<64 hex>"}],
+  "executed_at": "ISO8601",
+  "executor_skill": "atlas-plan-execute"
+}
+```
+
+Capture `base_sha` da referência explícita do plano/handoff; nunca infira pelo nome da branch. Antes da primeira mutação, capture `worktree_baseline`; imediatamente antes do handoff, capture `worktree_final`. `files_changed` e `task_evidence` representam exatamente `base_sha...head_sha` + delta entre snapshots. Dirty preexistente byte/status-idêntico fica fora; qualquer alteração posterior entra.
+
+Validation is always **sibling**, on every host. The validator is registered as a real subagent on every host, but this executor **never** dispatches it and never validates its own work. After tasks and local gates pass and the state file is written, this executor **stops mutation** and returns `validator_handoff_required` with the `state_path`. The orchestrator dispatches `atlas-task-validator` as the next isolated sibling phase, locks it via `atlas_lock_validator`, and — if the verdict is `fail` — dispatches `atlas-findings-repair` (not this executor) before the **2nd and last** validator.
+
+After writing the state file and before returning, emit `state_path_created` with the same `state_path`.
+Without this exact checkpoint, `atlas_lock_validator(start)` blocks in G12 and the orchestrator cannot dispatch the cold validator.
+
+The only handoff input is `state_path`. Do not paste the contract, diff, or task list inline. The validator reads everything it needs from the state file and the plan it points to. (`atlas_capabilities` is the runtime source of truth for the dispatch mechanism the orchestrator uses — see `references/host-adapters.md`.)
+
+**Finish all local work before the handoff — then stop idle.** Finish every local gate (lint, analyze, tests, `git diff --check`, diff-stat) and write the state file **before** returning the handoff. After returning `validator_handoff_required`, the executor must not mutate anything: the orchestrator now owns the slice, and any mutation here would change what the sibling validator reads and breaks determinism (same failure class as the orchestrator's G9).
+
+### 9. The orchestrator consumes the verdict
+This executor does not parse the validator output — the **orchestrator** does, deciding only from `verdict`:
+
+- `pass` / `pass_with_observations`: terminal — close the slice. Observations and `boundary_violations` returned alongside a non-`fail` verdict are reported residuals, never a trigger for another validator dispatch.
+- `fail`: the orchestrator opens `repair_start`, dispatches `atlas-findings-repair`, closes with `repair_run_id`, then runs the **2nd and last** validator (max 2 cycles total). This executor is not reused for the retry.
+
+Never decide by substring matching prose. Once the slice is closed, do not edit code, tests, or boundary files just to satisfy an observation; that reopens the slice and forces an avoidable re-validation. Real follow-up from an observation goes to the final report or a backlog item, not into an extra in-slice change.
+
+### 10. Report executor handoff
+Report only completed tasks, local validations, files changed, and `validator_handoff_required` with `state_path`. Validator verdict/cycles and final residuals belong exclusively to the orchestrator's final report.

package/hosts/zcode/skills/atlas-plan-execute/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Atlas Plan Execute"
+  short_description: "Bounded plan execution with gates (atlas-plan-execute)"
+  default_prompt: "Use $atlas-plan-execute to execute this handoff plan task by task with explicit invariants, focused validation, bounded self-repair, and clear stop conditions."
+
+policy:
+  allow_implicit_invocation: true

package/hosts/zcode/skills/atlas-plan-execute/references/plan-contract.md

@@ -0,0 +1,88 @@
+# Plan Contract
+
+Input plans must follow `atlas-plan-handoff` and align with `PLAN_TEMPLATE.md` / `BOUNDARY_PRD_PLAN.md` (compact template, sections 1–8). Locate both in the Atlas Workflow plugin bundle at `packages/templates/`; do not use workspace-local templates as primary sources.
+
+If `packages/templates/PLAN_TEMPLATE.md` or `packages/templates/BOUNDARY_PRD_PLAN.md` is absent from the bundle, stop with a clear `Template canônico ausente: <nome-do-template>` error. Do not fall back silently to old local, vault, or global copies.
+
+Legacy 15-section plans (handoff prompt, architecture impact block in PRD, etc.) are **not** the target format.
+
+## Required execution metadata
+
+Near the top of the artifact:
+
+- `Plan prefix: atlas`
+- `Execution mode: sequencial (T01→TN)` | `orchestrated-per-slice`
+- `Executor skill: atlas-plan-execute`
+- `Internal validator: atlas-task-validator`
+- `External review: atlas-slice-review` (optional)
+
+## Required plan sections (match by meaning)
+
+| § | Purpose |
+|---|---------|
+| 1 | Executive translation (`Tradução executiva`) — scope link to PRD, reference module, diffs vs mirror |
+| 2 | Execution invariants (derived from `PRD §3` — cite D* IDs, do not paste full table) |
+| 3 | Pitfalls (anti-pattern → fix) |
+| 4 | State at sprint opening (3–6 bullets; not a global file inventory) |
+| 5 | Execution tasks `#### T01.` … `TNN` |
+| 6 | Technical contracts (only where PRD → code is ambiguous) |
+| 8 | Validation and validator checklist (derived from `PRD §6` + §2 invariants) |
+
+Section 7 (Slices) is required only when `execution_mode: orchestrated-per-slice`.
+
+**Not required:** handoff prompt, planner readiness gate, full `project-rules` rules dump, full PRD scope copy, global touched-files inventory.
+
+**Optional:** section 9 open questions / real blockers (executor must stop if active blockers remain).
+
+## Minimum task shape (section 5)
+
+Each `#### TNN.` should include when applicable:
+
+- `Objetivo` / `Objective`
+- `Referência` (module or pattern — not a long path laundry list)
+- `Pré-condições` / `Preconditions`
+- `Mudança esperada` / `Expected change`
+- `Invariantes preservados`
+- `Não mudar` / `Não fazer` / `Do not do`
+- `Dependências` / `Dependencies`
+- `Riscos` (if not obvious)
+- `Critério de done` / `Done criteria`
+- `Validação local` / `Task-local validation` (command with package path)
+- `Quality gates` (optional on critical tasks)
+- `Casos mínimos` (test tasks only)
+
+Paths may appear in **Referência** or **Validação local**; prefer module-level pointers per boundary policy.
+
+## Executor consumption map
+
+| Contract need | Plan section |
+|---------------|--------------|
+| Translation, PRD links, reference module | §1 |
+| Execution invariants | §2 |
+| Pitfalls | §3 |
+| Current codebase state | §4 |
+| Tasks, done criteria, local validation | §5 |
+| Technical contracts | §6 |
+| Slice boundaries | §7 (orchestrated mode) |
+| Validator checklist | §8 |
+| Business acceptance (when §8 is thin) | PRD §4–6 (read PRD path from plan header) |
+
+## Why this matters
+
+Prefix and mode are part of the execution contract, not chat memory.
+
+If `Plan prefix` or `Execution mode` is missing, stop — do not guess the chain.
+
+Thin tasks (`refactor bootstrap` only) are not ready for gated execution; ask for a denser plan.
+
+Pitfalls, contracts, and invariants are binding — not commentary.
+
+## Parsing notes
+
+The bundled `extract_plan_contract.py` uses heading heuristics:
+
+- `#` … `####` headings
+- task headings `#### T01. …`
+- bullet lines `- …`
+
+Normalize non-standard plans before execution or extend the parser aliases.

package/hosts/zcode/skills/atlas-plan-execute/references/quality-gates.md

@@ -0,0 +1,60 @@
+# Quality Gates
+
+Choose the lightest gate that still protects the current task.
+
+## Gate selection order
+
+1. Prove the task with deterministic checks.
+2. Add semantic review against plan invariants.
+3. Add targeted runtime verification only when behavior changed in a way static checks cannot prove.
+4. Escalate to broader validation only when the task blast radius justifies it.
+
+## Common gate matrix
+
+### Pure refactor
+
+- targeted tests for touched modules
+- typecheck or analyze for touched package
+- diff scan for forbidden scope expansion
+
+### Contract or DTO change
+
+- compilation or typecheck
+- serialization or mapper tests if available
+- search for all consumers of renamed or reshaped fields
+- compare with plan constraints and declared contract
+- verify generated artifacts or localization files named by the plan before wiring consumers
+
+### UI-only change
+
+- component, widget, or snapshot tests when available
+- targeted runtime verification for changed flow
+- search for accessibility or localization regressions if the repo has such rules
+- verify role/permission gating when the plan distinguishes who can see or mutate related resources
+
+### State management or orchestration change
+
+- focused tests around the changed store, controller, or service
+- validation of loading, error, and success transitions
+- explicit invariant review so closed architectural decisions are not violated
+- rapid repeat-action or stale async check when the slice changes user-triggered operations
+
+### Data migration or cleanup
+
+- migration-specific validation
+- idempotency or rollback reasoning
+- stronger stop conditions if external systems are involved
+
+## What not to do
+
+- Do not run every available check after every edit.
+- Do not promote unrelated warnings into mandatory work.
+- Do not claim semantic safety from lint alone.
+- Do not keep retrying the same failing check with no code or environment change.
+- Do not repair by weakening a permission matrix, source-of-truth decision, or explicit negative scope.
+
+## Failure classification
+
+- `pass`: checks passed and no unresolved high-severity invariant break remains
+- `fixable`: a current-diff issue is clear and repair budget remains
+- `blocked`: repair would require scope change, external dependency, environment fix, or repeated speculative retries

package/hosts/zcode/skills/atlas-plan-execute/scripts/check_budget_state.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Track bounded repair attempts for a gated execution task."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class BudgetState:
+    task_id: str
+    max_attempts: int = 2
+    max_same_failure: int = 2
+    attempts: int = 0
+    same_failure_count: int = 0
+    last_failure_key: str = ""
+    blocked: bool = False
+
+
+def load_state(path: pathlib.Path) -> BudgetState:
+    if not path.exists():
+        raise FileNotFoundError(f"State file not found: {path}")
+    return BudgetState(**json.loads(path.read_text(encoding="utf-8")))
+
+
+def save_state(path: pathlib.Path, state: BudgetState) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(asdict(state), indent=2) + "\n", encoding="utf-8")
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    state = BudgetState(
+        task_id=args.task_id,
+        max_attempts=args.max_attempts,
+        max_same_failure=args.max_same_failure,
+    )
+    save_state(pathlib.Path(args.state_file), state)
+    print(json.dumps(asdict(state), indent=2))
+    return 0
+
+
+def cmd_record(args: argparse.Namespace) -> int:
+    path = pathlib.Path(args.state_file)
+    state = load_state(path)
+    state.attempts += 1
+
+    if args.failure_key:
+        if args.failure_key == state.last_failure_key:
+            state.same_failure_count += 1
+        else:
+            state.last_failure_key = args.failure_key
+            state.same_failure_count = 1
+
+    if state.attempts >= state.max_attempts or state.same_failure_count >= state.max_same_failure:
+        state.blocked = True
+
+    save_state(path, state)
+    print(json.dumps(asdict(state), indent=2))
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    state = load_state(pathlib.Path(args.state_file))
+    print(json.dumps(asdict(state), indent=2))
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init")
+    init_parser.add_argument("state_file")
+    init_parser.add_argument("task_id")
+    init_parser.add_argument("--max-attempts", type=int, default=2)
+    init_parser.add_argument("--max-same-failure", type=int, default=2)
+    init_parser.set_defaults(func=cmd_init)
+
+    record_parser = subparsers.add_parser("record")
+    record_parser.add_argument("state_file")
+    record_parser.add_argument("--failure-key", default="")
+    record_parser.set_defaults(func=cmd_record)
+
+    status_parser = subparsers.add_parser("status")
+    status_parser.add_argument("state_file")
+    status_parser.set_defaults(func=cmd_status)
+
+    args = parser.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())