Audit Loop Scaffold

Audit loop scaffold

Contract

Inputs

Templates must be sourced from cobusgreyling/loop-engineering at revision d03dcb92. No other skill, module, AGENTS file, or planning artifact is required.

Procedure

1. Resolve loop_dir to an absolute path. Fail with loop_dir_unavailable if it does not exist or is not a directory. Done when: loop_dir resolves to an existing directory.
2. Read the four template files into memory. Fail with template_unavailable if any template cannot be read. Done when: all four templates are in memory.
3. List every file in loop_dir at depth 1 (direct children only). Done when: the direct-child file list is complete.
4. Back up pre-write state for the four auto-fixable files. For each name (STATE.md, gate.yaml, loop-budget.md, loop-run-log.md): if the target file exists, record its content and hash; if it does not exist, record its absence. This backup is the rollback source. Done when: pre-write state for all four auto-fixable files is recorded, including absence states.
5. Converge the four files to template content. For each auto-fixable name: a. Compute the target path as loop_dir/<name>. b. If the target does not exist or its hash differs from the template hash, write the template content to the target path. c. Record the write in the action log with before/after hashes (before hash is null for newly created files). Done when: every auto-fixable file matches its template or is written from it, and before/after hashes are recorded.
6. For every other file in loop_dir not in the auto-fixable set: compute the file hash. If the hash matches none of the four template hashes, record the file path and hash in the drift report. Done when: every non-auto-fixable drifted file is in the drift report.
7. Verify every written auto-fixable file matches its template byte-for-byte by re-reading and comparing hashes. If any verification fails, roll back every file written in step 5 to its pre-write content from the step 4 backup: restore existing files to their recorded content, and delete files that were newly created (whose pre-write state was absence). Fail with auto_fix_verify_failed. Done when: every written file matches its template byte-for-byte.
8. Assert: every auto-fixable file matches its template; every other drifted file is in the drift report. If the assertion fails, fail with non_converged. Done when: the assertion holds.
9. Return the complete drift report. Done when: the drift report is returned.

Failure and recovery

On any failure, the result reports exactly what was attempted, what succeeded, and what must be done manually.

Output

{
  "status": "converged" | "non_converged" | "blocked",
  "loop_dir": "<resolved absolute path>",
  "auto_fixed": [
    {
      "file": "STATE.md" | "gate.yaml" | "loop-budget.md" | "loop-run-log.md",
      "before_hash": "<hex or null>",
      "after_hash": "<hex>"
    }
  ],
  "drift_reported": [
    {
      "file": "<relative path>",
      "hash": "<hex>"
    }
  ],
  "failure": "<failure class or null>",
  "failing_files": ["<file name>"],
  "action_log": [
    {
      "file": "STATE.md" | "gate.yaml" | "loop-budget.md" | "loop-run-log.md",
      "before_hash": "<hex or null>",
      "after_hash": "<hex or null>"
    }
  ],
  "converged": true | false
}