# Engine Check Agent Protocol

> Systematic, deterministic audit of the entire Recoil engine.
> Every check is numbered. Every check must be reported PASS/FAIL/WARN.
> No ad-hoc scanning. Work through each section mechanically.

---

## Why Numbered Checks Matter

Ad-hoc audits produce different results on every run because the LLM checks whatever catches its attention. This protocol eliminates that by enumerating every check with specific files, patterns, and pass/fail criteria. The agent MUST report a result for every numbered item.

---

## Step 0: Run Mechanical Pre-Check (ALWAYS FIRST)

```bash
python3 /tools/engine_check.py /path/to/recoil --json
```

This runs **53 deterministic checks** across 8 categories via modular check modules in `engine_checks/`:

| Category | Checks | Module | What It Covers |
|----------|--------|--------|----------------|
| Structural | 1-6 | `structural.py` | File inventory, chain, gates, constants sync, commands, orphans |
| Semantic | 7-18 | `semantic.py` | Stale values, counting, hooks, templates, examples, hardcoded, etc. |
| Deep Logic | 19-23 | `deep_logic.py` | JSON handling, thresholds, state fields, constants runtime, prose refs |
| GUI Integrity | 24-30 | `gui_integrity.py` | Routes, onclick, modules, standalone, launch, server, secrets |
| Visual Pipeline | 31-38 | `visual_pipeline.py` | Config loader, engine cost map, pricing, project config, LoRA registry |
| Dead Code | 39-42 | `dead_code.py` | Unreferenced tools, orphaned editors, unused imports, archive dupes |
| Documentation | 43-49 | `documentation.py` | CLAUDE.md tables, folder structure, cost figures, workflow guide sync |
| Security | 50-53 | `security.py` | API keys, env vars, path traversal, config secrets |

**Record the mechanical results.** The semantic audit below adds checks the script cannot perform.

**Modes:**
- `--quick` — Run only quick checks (chain, inventory, json, python, security) and STOP
- `--section gui` — Run only GUI integrity checks (24-30)
- `--section visual` — Run only visual pipeline checks (31-38)
- `--section dead` — Run only dead code checks (39-42)
- `--section docsync` — Run only documentation sync checks (43-49)
- `--section security` — Run only security checks (50-53)
- `--fix` — Run all checks, then apply safe auto-fixes (review with `git diff`)
- `--full` — Run all 53 checks (default)

---

## Section 1: Pipeline Gate Chain Verification

Walk the full pipeline and verify each phase transition has enforcement.

### 1.1 Development → Validation Gate

| Check | How to Verify | Pass Criteria |
|-------|--------------|---------------|
| 1.1.1 | Read `agents/validate_agent.md` | Has explicit pass/fail criteria |
| 1.1.2 | Read `agents/validate_agent.md` | References `validate_behavioral_dna.py` |
| 1.1.3 | Read `agents/validate_agent.md` | References `validate_arc.py` or arc validation |
| 1.1.4 | Read `.claude/skills/validate/SKILL.md` | References `validate_agent.md` |
| 1.1.5 | Read `WORKFLOW_SPEC.md` | Phase 2 (Validation) exists and describes gates |

### 1.2 Validation → Promotion Gate

| Check | How to Verify | Pass Criteria |
|-------|--------------|---------------|
| 1.2.1 | Read `agents/promote_agent.md` | Checks STATUS.md 34/34 before proceeding |
| 1.2.2 | Read `agents/promote_agent.md` | References behavioral DNA validation |
| 1.2.3 | Read `.claude/hooks/validate_behavioral_dna.py` | Script exists and has argparse |
| 1.2.4 | Read `WORKFLOW_SPEC.md` | Phase 3 (Promotion) has explicit gate |

### 1.3 Promotion → Treatment Gate

| Check | How to Verify | Pass Criteria |
|-------|--------------|---------------|
| 1.3.1 | Read `.claude/hooks/validate_pre_treatment.py` | Script exists and checks for bible/ files |
| 1.3.2 | Read `agents/treatment_agent.md` | References pre-treatment validation |
| 1.3.3 | Read `.claude/skills/treatment/SKILL.md` | Documents the hard gate |
| 1.3.4 | Read `WORKFLOW_SPEC.md` | Phase 4 (Treatment) mentions pre-treatment gate |

### 1.4 Treatment → Generation Gate

| Check | How to Verify | Pass Criteria |
|-------|--------------|---------------|
| 1.4.1 | Read `tools/validate_treatment.py` | Script exists with exit codes 0/1/2 |
| 1.4.2 | Read `.claude/hooks/validate_pre_generation.py` | Script exists and checks treatment.md |
| 1.4.3 | Read `.claude/hooks/enforce_context_load.py` | Script exists and checks .context_loaded flag |
| 1.4.4 | Read `WORKFLOW_SPEC.md` | Phase 5 (Treatment Validation) exists |

### 1.5 Per-Episode Validation Gate

| Check | How to Verify | Pass Criteria |
|-------|--------------|---------------|
| 1.5.1 | Read `tools/episode_metrics.py` | Has --json and --prompt modes |
| 1.5.2 | Read `tools/episode_metrics.py` | Checks word count, dialogue %, exchanges |
| 1.5.3 | Read `CLAUDE.md` | Documents mandatory per-episode validation |
| 1.5.4 | Read `.claude/hooks/episode_enforcement.py` | Script exists |

### 1.6 Batch Checkpoint Gate

| Check | How to Verify | Pass Criteria |
|-------|--------------|---------------|
| 1.6.1 | Read `.claude/hooks/save_checkpoint.py` | Script exists and creates checkpoint JSON |
| 1.6.2 | Read `.claude/hooks/validate_batch.py` | Script exists and validates batch |
| 1.6.3 | Read `skills/orchestration_process/SKILL.md` | Documents checkpoint protocol |

### 1.7 Breakdown → Visual Design Gate

| Check | How to Verify | Pass Criteria |
|-------|--------------|---------------|
| 1.7.1 | Read `tools/validate_breakdown.py` | Script exists with 3-tier validation |
| 1.7.2 | Read `agents/breakdown_agent.md` | References validate_breakdown.py as mandatory gate |
| 1.7.3 | Read `.claude/skills/visual-design/SKILL.md` | Lists breakdown.json as prerequisite |

### 1.8 Visual Design → Storyboard Gate

| Check | How to Verify | Pass Criteria |
|-------|--------------|---------------|
| 1.8.1 | Read `tools/validate_visual_bible.py` | Script exists with 3-tier validation |
| 1.8.2 | Read `agents/visual_design_agent.md` | References validate_visual_bible.py as mandatory gate |
| 1.8.3 | Read `WORKFLOW_SPEC.md` | Phase 9 (Visual Design) has validation gate section |

### 1.9 Storyboard → Generation Gate

| Check | How to Verify | Pass Criteria |
|-------|--------------|---------------|
| 1.9.1 | Read `tools/validate_storyboard.py` | Script exists with --json and --prompt modes |
| 1.9.2 | Read `agents/storyboard_agent.md` (AI Cinematographer) | References validate_storyboard.py as mandatory gate |
| 1.9.3 | Read `agents/storyboard_agent.md` (AI Cinematographer) | States "Do NOT proceed until is_valid: true" or equivalent |
| 1.9.4 | Read `agents/shotlist_agent.md` (Mechanical Specs) | Downstream agent exists and references storyboard_agent.md as upstream |

---

## Section 2: Skill-Agent-Validator Consistency

For EVERY skill in `.claude/skills/`, verify the chain is complete.

### Skills WITH agents (16 skills)

For each row: read the SKILL.md, verify it names the agent file. Read the agent file, verify it describes the correct workflow.

| # | Skill | Expected Agent | Has Validator? |
|---|-------|---------------|----------------|
| 2.1 | assess | assess_agent.md | No |
| 2.2 | breakdown | breakdown_agent.md | validate_breakdown.py |
| 2.3 | develop | develop_agent.md | No |
| 2.4 | dramatic-qc | dramatic_qc_agent.md | No |
| 2.5 | engine-check | engine_check_agent.md | engine_check.py |
| 2.6 | generate-orchestrated | orchestrator_agent.md | No |
| 2.7 | promote | promote_agent.md | No |
| 2.8 | rewrite | rewrite_agent.md | No |
| 2.9 | script-doctor | script_doctor_agent.md | No |
| 2.10 | showrunner | showrunner_agent.md | No |
| 2.11 | storyboard | storyboard_agent.md (AI Cinematographer) | validate_storyboard.py |
| 2.12 | thread | thread_agent.md | No |
| 2.13 | treatment | treatment_agent.md | validate_treatment.py |
| 2.14 | validate | validate_agent.md | No |
| 2.15 | visual-design | visual_design_agent.md | validate_visual_bible.py |
| 2.16 | revise | revision_agent.md | No |

**For each row, verify:**
- SKILL.md contains agent filename
- Agent .md file exists and is non-empty
- If validator column is filled: agent .md references that validator filename

### Skills WITHOUT agents (13 skills)

These skills execute inline (no separate agent protocol):

| # | Skill | Type |
|---|-------|------|
| 2.17 | autogenerate | Inline orchestration |
| 2.18 | batch | Sub-agent (internal) |
| 2.19 | camera-test | Inline validation |
| 2.20 | compile | Python script |
| 2.21 | editors | HTTP server + HTML editors |
| 2.22 | generate | Inline generation |
| 2.23 | golden-record | Python script |
| 2.24 | imagine | ComfyUI integration |
| 2.25 | listen | TTS pipeline |
| 2.26 | load-context | File reading |
| 2.27 | novella | Inline conversion |
| 2.28 | update-guides | Inline sync |
| 2.29 | validate-docs | Python script |

### Reference skills (7 skills in `skills/`)

Read-only reference material (no command interface):

| # | Skill | Purpose |
|---|-------|---------|
| 2.30 | calibration | GOOD/BAD calibration examples |
| 2.31 | dramatic_elements | Hook/cliffhanger taxonomy |
| 2.32 | format_v12 | V12 format specification |
| 2.33 | novella | Novella format reference |
| 2.34 | orchestration_process | Generation orchestration rules |
| 2.35 | relationship_earning | Relationship earning criteria |
| 2.36 | treatment | Treatment format reference |

**Total: 36 skills** (16 with agents + 13 inline + 7 reference)

**For each: verify SKILL.md exists and has Usage section.**

---

## Section 3: Python Tool Deep Review

For each Python tool in `tools/`, review logic and correctness. The mechanical pre-check already verified syntax; this section checks LOGIC.

### Validator Scripts (critical path)

These scripts gate pipeline progression. Errors here block or corrupt the pipeline.

| # | Script | Key Checks |
|---|--------|------------|
| 3.1 | `episode_metrics.py` | Word count logic: counts ALL words in file. Has --json, --prompt modes. Exit codes 0/1. |
| 3.2 | `validate_treatment.py` | Checks treatment.md structure. Has proper exit codes. |
| 3.3 | `validate_breakdown.py` | 3-tier validation (exit 0/1/2). Tier 1 docstring says "exit code 1", Tier 2 says "exit code 2". |
| 3.4 | `validate_visual_bible.py` | 3-tier validation. Checks HEX codes, lens package, characters, locations. |
| 3.5 | `validate_storyboard.py` | Beat coverage, script coverage (word-boundary matching), hallucination detection (set-based), shot integrity, dimension checks. |
| 3.6 | `validate_arc.py` | Arc structure validation. |
| 3.7 | `validate_docs.py` | Documentation consistency. |
| 3.8 | `validate_project.py` | Project validation. |
| 3.9 | `validate_treatment_batch.py` | Treatment batch validation. |

**For each validator, check:**
- Exit codes documented and correct (0=pass, 1=fail, 2=warnings)
- --json and --prompt modes exist where applicable
- File-not-found handling (doesn't crash on missing input)
- No hardcoded paths (uses arguments or relative paths)

### Generation/Processing Scripts

| # | Script | Key Checks |
|---|--------|------------|
| 3.10 | `compile_episodes.py` | Reads episodes, strips metadata, outputs .fountain. |
| 3.11 | `compile_treatment.py` | Treatment compilation. |
| 3.12 | `script_breakdown.py` | Extracts visual assets from episodes. Beat tracking uses per-line beat mapping (not stale current_beat). |
| 3.13 | `extract_treatment_batch.py` | Extracts batch section from treatment.md. |
| 3.14 | `golden_record.py` | Extracts/saves/loads ComfyUI parameters from PNG metadata. |
| 3.15 | `promote_project.py` | Creates scripting folder from development docs. |

### Orchestration Scripts

| # | Script | Key Checks |
|---|--------|------------|
| 3.16 | `init_orchestrator_state.py` | Creates orchestrator_state.json from treatment. |
| 3.17 | `update_orchestrator_state.py` | Updates state after each batch. |
| 3.18 | `generate_batch_summary.py` | Extracts batch metadata. |
| 3.19 | `orchestrator_verify.py` | Combined verification (threads, beats, patterns). |

### Verification Scripts

| # | Script | Key Checks |
|---|--------|------------|
| 3.20 | `verify_emotional_beats.py` | Emotional beat tracking. |
| 3.21 | `verify_pattern_variety.py` | Hook/cliffhanger pattern variety. |
| 3.22 | `verify_thread_continuity.py` | Thread plant/payoff tracking. |
| 3.23 | `track_threads.py` | Thread tracking utility. |

### Gate Scripts

| # | Script | Key Checks |
|---|--------|------------|
| 3.24 | `quality_gate.py` | Quality gate logic. |
| 3.25 | `transition_gate.py` | Phase transition gate. |
| 3.26 | `analyze_batch.py` | Batch analysis. |
| 3.27 | `engine_constants.py` | Constants module (importable). |

**For each script above:** Open and scan for:
- Dead code (unreachable branches, unused imports)
- Incorrect exit codes (swapped 1/2, missing sys.exit)
- Hardcoded paths that should be arguments
- Missing error handling on file I/O
- Logic errors in calculations (off-by-one, wrong comparisons)

---

## Section 4: Hook Script Review

For each hook in `.claude/hooks/`, review logic and wiring.

| # | Hook | Expected Trigger | Key Checks |
|---|------|-----------------|------------|
| 4.1 | `validate_behavioral_dna.py` | Pre-promotion | Validates characters.md behavioral DNA |
| 4.2 | `validate_pre_treatment.py` | Pre-treatment | Checks bible/ files exist after promotion |
| 4.3 | `validate_pre_generation.py` | Pre-generation | Checks treatment.md exists |
| 4.4 | `validate_batch.py` | Post-batch | Validates batch of 5 episodes |
| 4.5 | `validate_episode_arc.py` | Pre-promotion | Validates episode arc structure |
| 4.6 | `save_checkpoint.py` | Post-batch | Creates checkpoint + batch summary |
| 4.7 | `enforce_context_load.py` | Pre-write | Checks .context_loaded flag |
| 4.8 | `episode_enforcement.py` | Post-episode-write | Enforces episode validation |
| 4.9 | `baseline_comparison.py` | Post-batch | Compares against baseline |
| 4.10 | `checkpoint_reminder.py` | Periodic | Reminds about checkpoints |
| 4.11 | `dramatic_qc_gate.py` | Post-generation | Dramatic quality check |
| 4.12 | `quality_gate.py` | Post-episode | Quality gate |
| 4.13 | `transition_gate.py` | Phase transition | Gate enforcement |

**For each hook, check:**
- Script runs without import errors
- Has proper error handling (doesn't crash on missing files)
- Exit codes are correct
- No hardcoded project paths

---

## Section 5: Documentation Accuracy

### 5.1 WORKFLOW_SPEC.md vs Reality

Read `WORKFLOW_SPEC.md` and verify:

| # | Check | How to Verify |
|---|-------|---------------|
| 5.1.1 | Phase count matches pipeline | Count phases in WORKFLOW_SPEC, compare to actual pipeline stages |
| 5.1.2 | Each phase names correct command | Verify `/develop`, `/validate`, `/promote`, etc. match actual skill names |
| 5.1.3 | Each phase names correct gate script | Verify referenced .py scripts exist at stated paths |
| 5.1.4 | Visual production phases (8-10) are documented | Breakdown, Visual Design, Storyboard phases exist |
| 5.1.5 | Gate descriptions match actual script behavior | Sample 3 gates and compare spec description to script logic |

### 5.2 CLAUDE.md vs Reality

Read `CLAUDE.md` and verify:

| # | Check | How to Verify |
|---|-------|---------------|
| 5.2.1 | Commands table lists every skill | Cross-reference `.claude/skills/*/SKILL.md` against commands table |
| 5.2.2 | Python scripts table is complete | Cross-reference `tools/*.py` + `.claude/hooks/*.py` against table |
| 5.2.3 | Folder structure matches actual layout | Verify each listed directory exists |
| 5.2.4 | V12 constraints match CONSTANTS.md | Compare word count, dialogue %, exchanges, pattern limits |
| 5.2.5 | Pipeline order matches WORKFLOW_SPEC.md | Compare numbered steps |
| 5.2.6 | Skill file column paths are correct | Verify each path in the command reference table |

### 5.3 PRODUCTION_PIPELINE_GUIDE.md Accuracy

Read `docs/PRODUCTION_PIPELINE_GUIDE.md` and verify:

| # | Check | How to Verify |
|---|-------|---------------|
| 5.3.1 | Phase descriptions match WORKFLOW_SPEC | Compare each phase description |
| 5.3.2 | Commands mentioned match actual skills | Verify command names exist in .claude/skills/ |
| 5.3.3 | File paths are correct | Verify referenced paths exist |
| 5.3.4 | No contradictions with WORKFLOW_SPEC | Compare any numeric values or process descriptions |

### 5.4 Appendix Accuracy

| # | Check | How to Verify |
|---|-------|---------------|
| 5.4.1 | appendix_a hook/cliffhanger types match format_v12 SKILL.md | Compare type lists |
| 5.4.2 | appendix_e Flux 2 protocols match storyboard_schema.json | Compare field names, enums |
| 5.4.3 | appendix_e lens table matches CONSTANTS.md | Compare lens specs |
| 5.4.4 | appendix_c anchor types match develop_agent.md | Compare anchor type lists |
| 5.4.5 | appendix_d visual strategy matches breakdown_agent.md | Compare terminology |

---

## Section 6: Templates, Schemas, and Quality

### 6.1 Template Completeness

| # | Template | Check |
|---|----------|-------|
| 6.1.1 | `storyboard_schema.json` | Has version field, lens_package object, shots array with all required fields |
| 6.1.2 | `breakdown_schema.json` | Has characters, locations, props sections |
| 6.1.3 | `visual_bible_template.md` | Has all sections: Color Palette, Characters, Props, Locations, VFX, Lens Package, Lighting |
| 6.1.4 | `episode_arc_template.md` | Has 60 episode slots with one-liner, cliffhanger, type, intensity |
| 6.1.5 | `series_bible_template.md` | Has series overview, world, characters, theme sections |
| 6.1.6 | `state_template.json` | Has episode tracking, batch tracking fields |
| 6.1.7 | `STATUS_TEMPLATE.md` | Has 34 checklist items |
| 6.1.8 | Dev templates (6) | Each has section headers and placeholder guidance |

### 6.2 Schema-Code Consistency

| # | Check | How to Verify |
|---|-------|---------------|
| 6.2.1 | `storyboard_schema.json` version matches validate_storyboard.py expectations | Read both, compare |
| 6.2.2 | `breakdown_schema.json` structure matches script_breakdown.py output | Read both, compare field names |
| 6.2.3 | `batch_summary.schema.json` matches generate_batch_summary.py output | Read both, compare |
| 6.2.4 | `orchestrator_state.schema.json` matches init_orchestrator_state.py output | Read both, compare |

### 6.3 Quality Checks

| # | Check | How to Verify |
|---|-------|---------------|
| 6.3.1 | No TODO/FIXME in production .py files | Grep all tools/ and hooks/ .py files |
| 6.3.2 | No `print()` debug statements left in hooks | Grep hooks/ .py files for bare print() |
| 6.3.3 | All .py tools have docstrings | Check first triple-quote in each file |
| 6.3.4 | No duplicate files (same content, different names) | Check archive/ vs active files |
| 6.3.5 | No .old or .bak files in active directories | Glob for *.old, *.bak outside archive/ |

---

## Section 7: GUI/Editor Integrity (Automated — checks 24-30)

These checks run automatically via `engine_check.py --section gui`. The agent protocol documents what they verify for reference:

| # | Key | What It Checks |
|---|-----|----------------|
| 24 | `route_coverage` | fetch() URLs in HTML/JS that don't match any serve.py route |
| 25 | `onclick_defined` | onclick handlers in HTML referencing undefined JS functions |
| 26 | `editor_module_deps` | production_console.html missing a `<script>` import for a module file |
| 27 | `standalone_api_compat` | Standalone editors using inconsistent API path patterns |
| 28 | `launch_cleanup` | launch.sh not cleaning up backgrounded server PID on exit |
| 29 | `server_timeout` | voice_casting_server.py missing timeout on TTS generation |
| 30 | `secrets_in_html` | API keys/tokens hardcoded in HTML/JS files |

**When to run:** After editing any file in `editors/`.

---

## Section 8: Visual Pipeline Integrity (Automated — checks 31-38)

These checks run automatically via `engine_check.py --section visual`.

| # | Key | What It Checks |
|---|-----|----------------|
| 31 | `config_exports` | Importers expecting names that config_loader.py doesn't export |
| 32 | `engine_cost_map` | ENGINE_COST_MAP keys missing from pricing_rates.json |
| 33 | `pricing_completeness` | Models referenced in tracker.log() calls not in pricing_rates.json |
| 34 | `config_template` | Template keys diverging from DEFAULT_PROJECT_CONFIG |
| 35 | `rendering_directives` | breakdown.json rendering_directives missing expected fields |
| 36 | `cost_categories` | tracker.log(category=...) using categories not in CATEGORIES dict |
| 37 | `lora_registry` | LoRA registry with invalid structure or missing referenced files |
| 38 | `vb_template` | visual_bible_template.md sections not matching validator expectations |

**When to run:** After visual pipeline changes (config_loader, cost_tracker, pricing_rates, project_config).

---

## Section 9: Dead Code Detection (Automated — checks 39-42)

These checks run automatically via `engine_check.py --section dead`.

| # | Key | What It Checks |
|---|-----|----------------|
| 39 | `unreferenced_tools` | .py files in tools/ not referenced in any .md, skill, agent, or other .py |
| 40 | `orphaned_editors` | .html files in editors/ not reachable from console or docs |
| 41 | `unused_imports` | Python files importing modules they never use (WARN, not FAIL) |
| 42 | `archive_dupes` | Files in _archive/ that duplicate active files |

**When to run:** Periodic cleanup. `--fix` mode can auto-remove unused imports.

---

## Section 10: Documentation Sync (Automated — checks 43-49)

These checks run automatically via `engine_check.py --section docsync`.

| # | Key | What It Checks |
|---|-----|----------------|
| 43 | `scripts_table` | CLAUDE.md Python Scripts table lists files that don't exist (or missing real files) |
| 44 | `folder_structure` | Folder structure diagram diverged from actual directory tree |
| 45 | `cost_figures` | Cost figures in CLAUDE.md/WORKFLOW_GUIDE not matching pricing_rates.json |
| 46 | `guide_tools` | Tools table in WORKFLOW_GUIDE missing entries or listing deleted tools |
| 47 | `command_ref_paths` | Skill/agent file paths in COMMAND REFERENCE table that don't exist on disk |
| 48 | `validate_docs_issues` | Known validate_docs.py issues still present (renamed concepts, rule wording) |
| 49 | `built_vs_planned` | "What's Built" table claims BUILT for files that don't exist |

**When to run:** After doc updates, or as part of `/update-guides`.

---

## Section 11: Security Audit (Automated — checks 50-53)

These checks run automatically via `engine_check.py --section security`. Checks 50 and 53 are included in `--quick` mode.

| # | Key | What It Checks |
|---|-----|----------------|
| 50 | `api_keys` | API keys/tokens in tracked .py, .html, .js files (ElevenLabs, Google, OpenAI, Anthropic, fal.ai, AWS) |
| 51 | `env_discipline` | Scripts that hardcode API keys instead of using os.environ.get() |
| 52 | `path_traversal` | serve.py file-serving routes missing .resolve() + .startswith() protection |
| 53 | `secrets_in_configs` | JSON config files containing secret-like values |

**When to run:** Before any commit that touches credential-adjacent code. Included in `--quick` for pre-commit.

---

## Reporting Format

After completing all sections, produce a report in this exact format:

```
═══════════════════════════════════════════════════════════════
ENGINE CHECK REPORT
Date: [YYYY-MM-DD]
═══════════════════════════════════════════════════════════════

MECHANICAL PRE-CHECK (engine_check.py):
  File Inventory: [N]/[total] present
  Python Syntax: [N]/[total] valid
  JSON Syntax: [N]/[total] valid
  Skill→Agent Chain: [N]/[total] linked
  Constants Sync: [N]/[total] matched
  Placeholders: [N] found in production files
  Cross-References: [N] broken refs
  CLAUDE.md Commands: [N]/[total] documented

SECTION 1 — Pipeline Gate Chain:
  1.1.1 Development → Validation: [PASS/FAIL] [detail if fail]
  1.1.2 ...
  [every numbered item]

SECTION 2 — Skill-Agent Consistency:
  2.1 assess: [PASS/FAIL]
  2.2 breakdown: [PASS/FAIL]
  ...

SECTION 3 — Python Tool Review:
  3.1 episode_metrics.py: [PASS/FAIL] [detail if fail]
  ...

SECTION 4 — Hook Review:
  4.1 validate_behavioral_dna.py: [PASS/FAIL]
  ...

SECTION 5 — Documentation Accuracy:
  5.1.1 WORKFLOW_SPEC phase count: [PASS/FAIL]
  ...

SECTION 6 — Templates & Quality:
  6.1.1 storyboard_schema.json: [PASS/FAIL]
  ...

═══════════════════════════════════════════════════════════════
FINDINGS BY SEVERITY
═══════════════════════════════════════════════════════════════

CRITICAL (blocks pipeline):
  [#] [description] — [file] — [fix required]
  ...

MODERATE (affects quality):
  [#] [description] — [file] — [fix recommended]
  ...

LOW (cleanup):
  [#] [description] — [file] — [optional improvement]
  ...

═══════════════════════════════════════════════════════════════
SUMMARY
  Total checks: [N]
  Pass: [N]
  Fail: [N]
  Warn: [N]

  Sections clean: [list]
  Sections with issues: [list]
═══════════════════════════════════════════════════════════════
```

---

## Execution Strategy

### Full Audit (default)

1. Run `engine_check.py --json` for mechanical baseline
2. Spawn 6 parallel agents, each handling one section:

| Agent | Section | Files to Read |
|-------|---------|---------------|
| A | Section 1 (Gates) | WORKFLOW_SPEC.md, all agent .md files, all gate .py scripts |
| B | Section 2 (Skill-Agent) | All .claude/skills/*/SKILL.md, all agents/*.md |
| C | Section 3 (Python Tools) | All tools/*.py |
| D | Section 4 (Hooks) | All .claude/hooks/*.py |
| E | Section 5 (Docs) | WORKFLOW_SPEC.md, CLAUDE.md, PRODUCTION_PIPELINE_GUIDE.md, appendices |
| F | Section 6 (Templates) | All templates, schemas, quality grep |

3. Synthesize all results into the report format above
4. Classify findings by severity

### Section Mode

If `--section` specified, run mechanical pre-check + only the specified section's agent.

### Quick Mode

If `--quick`, run only `engine_check.py` and output the mechanical report. No semantic audit.

---

## Key Principles

1. **Every check is numbered.** Nothing can be skipped.
2. **Mechanical first.** The Python script catches deterministic issues before the LLM starts.
3. **Specific pass/fail criteria.** Not "check this looks right" but "verify X contains Y."
4. **Severity classification.** CRITICAL = blocks pipeline. MODERATE = affects quality. LOW = cleanup.
5. **Repeatable.** Running this twice should produce the same findings (minus any fixes applied between runs).