atomic-control

Files (1)

• SKILL.md

SKILL.md (first lines)

# atomic-control

> Status: SUSPENDED. This skill must not invoke Atomic-Control unless OpenCode
> explicitly changes `CURRENT_PLAN` to select the atomic-control backend and
> re-enables the MCP configuration. Codex cannot authorize that transition.

Use this skill to drive the PLAN_100 88-node audit loop via the atomic-control MCP server.

## Tools (5 tools)

| Tool | Purpose | Key Parameters |
|---|---|---|
| `atomic_get_status` | Check system health: active epoch, contract drift, verify_chain | none |
| `atomic_get_task` | Acquire lease and get next node. Returns `write_scope` (allowed paths). | none |
| `atomic_submit_result` | Submit evidence, close lease, commit to worktree | `lease_id`, `changed_paths`, `root_cause`, `test_command`, `classification` (optional, default "CURRENT_PASS") |
| `atomic_validate_result` | Run 6-check validation on a result (VALIDATE/REPAIR nodes) | `lease_id` |
| `atomic_abort` | Release a stuck lease (recovery from timeout/failure) | `lease_id`, `reason` |

## Black-Box Boundary

### FORBIDDEN (AI must never touch)

- `C:\ProgramData\AtomicControl\` (DB, keys, logs, state)
- `atomic_control/` (CLI source code, dispatcher, validation, state store)
- `contracts/plan_contract.json` (the contract itself)
- Any `sqlite3`, `subprocess`, or file operation targeting the above
- Direct DB INSERT/UPDATE/DELETE via any mechanism
- Manual creation of receipts, TRANSITION events, or lease state

### ALLOWED (AI may touch)

- 5 MCP tools: `atomic_get_status`, `atomic_get_task`, `atomic_submit_result`, `atomic_validate_result`, `atomic_abort`
- `plan100_workspace/.evidence/{node}/` evidence files (via MCP tools only)
- `python -m unittest atomic_control.tests.*` (collect test output as evidence, read-only)
- Reading validation error messages from MCP tool responses

### VIOLATION

Any AI action outside the ALLOWED set **voids the audit run**. The chain is untrustworthy if the AI directly manipulated DB state, source code, or the contract.

## Loop Logic

```
atomic_get_status  ──→  ok=True, status=CLEAN?
        │
        ▼
atomic_get_task  ──→  lease_id, node, card_type, write_scope, task
        │
        ▼
[Do real work: run tests, gather concrete evidence via MCP tool output]
        │
        ▼
atomic_submit_result(lease_id, changed_paths, root_cause, test_command)
        │   ├── commit evidence to worktree
        │   ├── Path format: .evidence/{node}/file.md (NOT plan100_workspace/.evidence/...)
        │   ├── AUDIT/HANDOFF/DECISION/DIAGNOSIS/...: task-close immediately
        │   └── VALIDATE/REPAIR: return COMMITTED_NOT_CLOSED, defer close
        ▼
[If VALIDATE/REPAIR: atomic_validate_result(lease_id)]
        │   ├── validation passed → task-close with CURRENT_PASS
        │   ├── schema/structural failure → task-close with BLOCKED
        │   └── validation failed (quality issue) → card_type-aware classification:
        │       ├── VALIDATE node → FAIL_VALIDATE → contract routes to DIAGNOSIS
        │       ├── REPAIR node   → FAIL_REPAIR   → contract routes to DIAGNOSIS
        │       └── other types   → FAIL_HANDOFF
        ▼
[MANDATORY after-validate protocol]  ← AD-03
        │   ├── Read result["result"]["checks"] list
        │   ├── Read result["result"]["errors"] list
        │   ├── If write_scope_check failed: paths are outside write_scope.
        │   │   Check atomic_get_task's write_scope field for allowed paths.
        │   │   Use .evidence/{node}/... format (relative to plan100_workspace).
        │   ├── If formal_check failed: ensure receipt_id != lease_id
        │   │   and receipt_id does NOT start with stub_/fake_/preview_
        │   ├── If lint_check/test_check failed: fix evidence file quality
        │   ├── If validation passed=false (quality issues):
        │   │   DO NOT retry the same node. The contract routes FAIL_VALIDATE
        │   │   and FAIL_REPAIR to a DIAGNOSIS node. Let the contract handle
        │   │   routing by calling atomic_get_task to continue the loop.
        │   │   The full route is: FAIL_* → DIAGNOSIS → DECISION → VALIDATE/REPAIR.
        │   ├── If the SAME node fails 3 times across separate leases:
        │   │   call atomic_abort(lease_id, reason) and report
        │   │   STOP_NEEDS_HUMAN; do NOT retry a 4th time
        │   └── If errors include UNMAPPED_CLASSIFICATION: halt, this is
        │       a contract / mcp_server bug, not a user error
        ▼
[Check result["result"]["commit_sha"] is non-empty AND validation passed]  ← AD-01
        │
        ▼
Loop back to atomic_get_task
```

## Card Type Actions

### AUDIT
Gather **real** source evidence. Must provide non-empty `changed_paths` (list of evidence file paths).
**Required**: evidence_refs must be a non-empty list.
**Evidence quality requirement**: each evidence file must contain concrete findings — file paths reviewed, specific code patterns checked, test commands run, and actual results. Do **not** write generic statements like "validation passed" or "audit complete".

### VALIDATE
1. Run the provided `test_command` and capture its actual output.
2. Read validation error messages from previous MCP tool responses as evidence.
3. Create evidence files that include the actual test output and specific observations from validation output.
4. Submit result — this will commit but **not** close the lease for VALIDATE/REPAIR.
5. Call `atomic_validate_result`. If validation fails, the contract routes to DIAGNOSIS.
**Note**: `atomic_submit_result` defers `task-close` for VALIDATE/REPAIR; `atomic_validate_result` determines the final classification and routing.

### REPAIR
Same as VALIDATE: run tests, gather concrete evidence, submit, then `atomic_validate_result`.
**IMPORTANT**: Use `test_command` that does NOT conflict with the running epoch:
- `python -m pytest atomic_control/tests/test_atomic_audit.py -v` (audit tests only, no state conflict)
- `python -m pytest atomic_control/tests/test_cli_audit_semantic_chain.py -v` (semantic chain tests)
- Do NOT run `test_integration.py` as it modifies the production DB and conflicts with the active epoch.

### HANDOFF
Submit phase transition evidence. Must have non-empty `changed_paths`.
Verifies that mapping points to correct next phase.

### DIAGNOSIS

From linjuhon/codex-personal-skills, MIT.

More from linjuhon/codex-personal-skills