claude-code-workflow 7.2.26 → 7.2.28

package/.claude/skills/team-visual-a11y/specs/typography-scale.md

@@ -0,0 +1,165 @@
+# Typography Accessibility Standards
+
+Reference guide for typography readability analysis. Used by typo-auditor and fix-implementer roles.
+
+## Font Stack Hierarchy
+
+| Purpose | Category | Example | Usage |
+|---------|----------|---------|-------|
+| Display | Serif | Cormorant Garamond, Georgia, serif | Headings, hero text |
+| Body | Sans-serif | Instrument Sans, Inter, system-ui, sans-serif | Paragraphs, UI text |
+| Mono | Monospace | Space Grotesk, Fira Code, monospace | Code blocks, labels |
+
+### System Font Stack (Fallback)
+
+```css
+--font-body: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+--font-mono: ui-monospace, "Cascadia Code", "Fira Code", Menlo, monospace;
+```
+
+## Responsive Size Scale
+
+### clamp() Formula Pattern
+
+```css
+/* clamp(minimum, preferred, maximum) */
+/* preferred = slope * 100vw + intercept */
+/* slope = (max - min) / (max-viewport - min-viewport) */
+```
+
+### Recommended Scale
+
+| Element | clamp() Value | Min (320px) | Max (1400px) | WCAG |
+|---------|--------------|-------------|-------------|------|
+| Hero | `clamp(2.5rem, 7vw, 4.5rem)` | 40px | 72px | -- |
+| Section title | `clamp(1.75rem, 4vw, 2.5rem)` | 28px | 40px | -- |
+| H1 | `clamp(2rem, 5vw, 3rem)` | 32px | 48px | -- |
+| H2 | `clamp(1.5rem, 3vw, 2.25rem)` | 24px | 36px | -- |
+| H3 | `clamp(1.25rem, 2vw, 1.75rem)` | 20px | 28px | -- |
+| Body | `clamp(1rem, 1vw + 0.875rem, 1.25rem)` | 16px | 20px | 1.4.4 |
+| Small/caption | 14px (fixed floor) | 14px | 14px | 1.4.4 |
+
+### Absolute Minimums
+
+| Element | Minimum | Rationale |
+|---------|---------|-----------|
+| Body text | 16px | WCAG 1.4.4 baseline readability |
+| Small text / caption | 14px | Absolute floor for legibility |
+| Interactive labels | 14px | Touch/click target readability |
+
+**Never**: Set body text below 14px at any viewport width.
+
+## Line Height Scale
+
+| Element Type | Range | Optimal | Rationale |
+|-------------|-------|---------|-----------|
+| Body text | 1.5 - 1.75 | 1.625 | WCAG 1.4.12, optimal readability |
+| Headings | 1.1 - 1.3 | 1.2 | Tight for visual impact, still readable |
+| Code blocks | 1.5 - 1.7 | 1.6 | Generous for scanning |
+| Buttons/labels | 1.2 - 1.5 | 1.3 | Compact UI element |
+| Lists | 1.4 - 1.6 | 1.5 | Slightly tighter than body |
+
+### Line Height Rules
+
+- Use unitless values (not px or em) for proper inheritance
+- `line-height: 1.5` (unitless) is preferred over `line-height: 24px` (fixed)
+- WCAG 1.4.12 requires text to remain readable at 1.5x font-size line-height
+
+## Letter Spacing Scale
+
+| Element Type | Range | Optimal | Notes |
+|-------------|-------|---------|-------|
+| Display headings | -0.02em to 0 | -0.015em | Tight for visual weight |
+| Body text | 0 (default) | 0 | Browser default is optimal |
+| Uppercase labels | 0.05em - 0.1em | 0.08em | Open for legibility |
+| Monospace code | 0.08em - 0.15em | 0.1em | Wide for character distinction |
+| Small caps | 0.05em - 0.08em | 0.06em | Slight opening |
+
+### WCAG 1.4.12 Override Requirements
+
+Content must remain readable when user applies:
+- Letter spacing: 0.12em
+- Word spacing: 0.16em
+- These overrides should not cause content overflow or overlap
+
+## Reading Width
+
+| Metric | Optimal | Acceptable | Flag |
+|--------|---------|-----------|------|
+| Characters per line | 66ch | 45-75ch | < 45 (too narrow) or > 75 (too wide) |
+| Container max-width | 65ch | 60ch-75ch | > 80ch |
+| Content column width | Up to 900px | Up to 1000px | > 1000px without columns |
+
+### Implementation
+
+```css
+/* Preferred: ch-based */
+.content { max-width: 70ch; }
+
+/* Alternative: px-based */
+.content { max-width: 700px; }
+
+/* With centering */
+.content {
+  max-width: 70ch;
+  margin-inline: auto;
+  padding-inline: 1rem;
+}
+```
+
+## Font Loading Strategy
+
+### font-display Values
+
+| Value | Behavior | Recommended For |
+|-------|----------|----------------|
+| `swap` | Show fallback immediately, swap when loaded | Body text |
+| `optional` | Show fallback, swap only if already cached | Display/decorative fonts |
+| `fallback` | Brief invisible period (~100ms), then fallback | Important fonts |
+| `block` | Invisible text up to 3s | Avoid for body text |
+| `auto` | Browser decides | Avoid (unpredictable) |
+
+### Best Practices
+
+```css
+/* Body font: swap for immediate readability */
+@font-face {
+  font-family: "Body Font";
+  src: url("body.woff2") format("woff2");
+  font-display: swap;
+}
+
+/* Display font: optional to prevent layout shift */
+@font-face {
+  font-family: "Display Font";
+  src: url("display.woff2") format("woff2");
+  font-display: optional;
+}
+```
+
+### Preloading Critical Fonts
+
+```html
+<link rel="preload" href="/fonts/body.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+### Fallback Stack Requirements
+
+- Every custom font must have a system fallback
+- Fallback should have similar metrics (x-height, width) to minimize layout shift
+- Use `size-adjust`, `ascent-override`, `descent-override` for metric matching
+
+## Responsive Typography Checklist
+
+| # | Check | Standard | Method |
+|---|-------|----------|--------|
+| 1 | Body text >= 16px at 320px | WCAG 1.4.4 | Computed style at mobile viewport |
+| 2 | No text below 14px at any viewport | Best practice | Search for font-size values |
+| 3 | clamp() min >= 14px | Best practice | Parse clamp() functions |
+| 4 | Line-height unitless | Best practice | Search for px/em line-height |
+| 5 | Body line-height 1.5-1.75 | WCAG 1.4.12 | Computed style check |
+| 6 | Reading width 45-75ch | Best practice | Measure container + font size |
+| 7 | font-display: swap on body | Best practice | Parse @font-face rules |
+| 8 | System fallback defined | Best practice | Parse font-family stacks |
+| 9 | 200% zoom no overflow | WCAG 1.4.4 | Zoom test |
+| 10 | Text spacing override safe | WCAG 1.4.12 | Apply overrides, check layout |

package/.claude/skills/team-visual-a11y/specs/wcag-matrix.md

@@ -0,0 +1,133 @@
+# WCAG 2.1 Criteria Matrix
+
+Reference matrix for visual accessibility audit. Maps WCAG success criteria to audit methods and responsible roles.
+
+## Criteria Covered by This Team
+
+| Criterion | Level | Automated | Manual | Check Method | Primary Role |
+|-----------|-------|-----------|--------|-------------|-------------|
+| 1.4.3 Contrast (Minimum) | AA | Yes | - | Color ratio calculation (4.5:1 normal, 3:1 large) | color-auditor |
+| 1.4.6 Contrast (Enhanced) | AAA | Yes | - | Color ratio calculation (7:1 normal, 4.5:1 large) | color-auditor |
+| 1.4.11 Non-text Contrast | AA | Partial | Yes | UI component border/fill contrast >= 3:1 | color-auditor |
+| 1.4.4 Resize Text | AA | Yes | - | 200% zoom, no content loss | typo-auditor |
+| 1.4.12 Text Spacing | AA | Partial | Yes | Override line-height 1.5x, letter-spacing 0.12em, word-spacing 0.16em | typo-auditor |
+| 2.1.1 Keyboard | A | Partial | Yes | Tab through all interactive elements | focus-auditor |
+| 2.1.2 No Keyboard Trap | A | - | Yes | Tab can escape all contexts (except intentional traps with Escape) | focus-auditor |
+| 2.4.1 Bypass Blocks | A | Yes | - | Skip link present and functional | focus-auditor |
+| 2.4.3 Focus Order | A | - | Yes | Logical tab sequence | focus-auditor |
+| 2.4.7 Focus Visible | AA | Partial | Yes | Visible focus indicator on all interactive elements | focus-auditor |
+| 2.4.11 Focus Not Obscured (Min) | AA | - | Yes | Focus indicator not hidden by overlays, sticky headers | focus-auditor |
+| 2.5.8 Target Size (Minimum) | AA | Yes | - | Minimum 24x24px CSS pixel touch targets | focus-auditor |
+| 4.1.2 Name, Role, Value | A | Yes | - | ARIA roles, labels, and states on interactive elements | focus-auditor |
+| 4.1.3 Status Messages | AA | Partial | Yes | aria-live regions for dynamic status updates | focus-auditor |
+
+## Audit Method Legend
+
+| Method | Description |
+|--------|-------------|
+| Automated | Can be verified programmatically (CSS parsing, contrast calculation) |
+| Manual | Requires human judgment or runtime interaction |
+| Partial | Automated detection of presence, manual verification of correctness |
+
+## Criterion Details
+
+### 1.4.3 Contrast (Minimum) - AA
+
+**Requirement**: Text and images of text have a contrast ratio of at least 4.5:1 (3:1 for large text).
+
+**Large text definition**: >= 18pt (24px) or >= 14pt bold (18.66px bold).
+
+**Exceptions**: Decorative text, logos, inactive UI components.
+
+**Check**: Extract foreground/background colors -> calculate contrast ratio -> compare against threshold.
+
+### 1.4.6 Contrast (Enhanced) - AAA
+
+**Requirement**: Text has contrast ratio of at least 7:1 (4.5:1 for large text).
+
+**Check**: Same as 1.4.3 but with higher thresholds.
+
+### 1.4.11 Non-text Contrast - AA
+
+**Requirement**: UI components and graphical objects have at least 3:1 contrast against adjacent colors.
+
+**Applies to**: Buttons, inputs, icons, focus indicators, charts, custom controls.
+
+**Check**: Extract border/fill colors of UI components -> calculate contrast against background.
+
+### 1.4.4 Resize Text - AA
+
+**Requirement**: Text can be resized up to 200% without loss of content or functionality.
+
+**Check**: Zoom to 200% -> verify no horizontal scrolling, no content clipping, no overlap.
+
+### 1.4.12 Text Spacing - AA
+
+**Requirement**: Content must remain readable when user overrides:
+- Line height to 1.5x font size
+- Paragraph spacing to 2x font size
+- Letter spacing to 0.12x font size
+- Word spacing to 0.16x font size
+
+**Check**: Apply overrides via JavaScript/CSS -> verify no content loss or overlap.
+
+### 2.1.1 Keyboard - A
+
+**Requirement**: All functionality available via keyboard (Enter, Space, Tab, Arrow keys, Escape).
+
+**Check**: Tab to every interactive element -> activate with Enter/Space -> navigate composites with Arrows.
+
+### 2.1.2 No Keyboard Trap - A
+
+**Requirement**: Keyboard focus can be moved away from any component using standard keys.
+
+**Exception**: Modal dialogs that trap focus intentionally (must have Escape to exit).
+
+**Check**: Tab forward and backward through all elements -> verify escape from all containers.
+
+### 2.4.1 Bypass Blocks - A
+
+**Requirement**: Mechanism to bypass repeated content blocks (skip links, landmarks, headings).
+
+**Check**: Verify skip link as first focusable element, target exists, focus moves correctly.
+
+### 2.4.3 Focus Order - A
+
+**Requirement**: Focus order preserves meaning and operability (logical sequence).
+
+**Check**: Tab through page -> verify order matches visual/reading order.
+
+### 2.4.7 Focus Visible - AA
+
+**Requirement**: Keyboard focus indicator is visible on all interactive elements.
+
+**Check**: Tab to each element -> verify visible outline/border/shadow change.
+
+### 2.4.11 Focus Not Obscured (Minimum) - AA
+
+**Requirement**: Focused element is not entirely hidden by other content (sticky headers, overlays, banners).
+
+**Check**: Tab through elements near sticky/fixed positioned elements -> verify focus indicator partially visible.
+
+### 2.5.8 Target Size (Minimum) - AA
+
+**Requirement**: Interactive targets are at least 24x24 CSS pixels, or have adequate spacing.
+
+**Exceptions**: Inline links within text, user agent default controls, essential presentation.
+
+**Check**: Measure interactive element dimensions -> verify >= 24x24px or adequate spacing.
+
+### 4.1.2 Name, Role, Value - A
+
+**Requirement**: All UI components have accessible name, role, and state programmatically determined.
+
+**Check**: Verify interactive elements have:
+- Accessible name (text content, aria-label, aria-labelledby)
+- Appropriate role (native HTML or ARIA role)
+- Current state (aria-expanded, aria-pressed, aria-selected, aria-checked)
+
+### 4.1.3 Status Messages - AA
+
+**Requirement**: Status messages can be programmatically determined through role or properties without receiving focus.
+
+**Check**: Verify dynamic content updates use `aria-live` or appropriate roles (`status`, `alert`, `log`).

package/.codex/skills/investigate/agents/investigator.md

@@ -0,0 +1,392 @@
+# Investigator Agent
+
+Executes all 5 phases of the systematic debugging investigation under the Iron Law methodology. Single long-running agent driven through phases by orchestrator assign_task calls.
+
+## Identity
+
+- **Type**: `investigation`
+- **Role File**: `~/.codex/skills/investigate/agents/investigator.md`
+- **task_name**: `investigator`
+- **Responsibility**: Full 5-phase investigation execution — evidence collection, pattern search, hypothesis testing, minimal fix, verification
+- **fork_context**: false
+- **Reasoning Effort**: high
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern before any phase execution
+- Read the phase file at the start of each phase before executing that phase's steps
+- Collect concrete evidence before forming any theories (evidence-first)
+- Check `confirmed_root_cause` exists before executing Phase 4 (Iron Law gate)
+- Track 3-strike counter accurately in Phase 3
+- Implement only minimal fix — change only what addresses the confirmed root cause
+- Add a regression test that fails without the fix and passes with it
+- Write the final debug report to `.workflow/.debug/` using the schema in `~/.codex/skills/investigate/specs/debug-report-format.md`
+- Produce structured output after each phase, then await next assign_task
+
+### MUST NOT
+
+- Skip MANDATORY FIRST STEPS role loading
+- Proceed to Phase 4 without `confirmed_root_cause` (Iron Law violation)
+- Modify production code during Phases 1-3 (read-only investigation)
+- Count a rejected hypothesis as a strike if it yielded new actionable insight
+- Refactor, add features, or change formatting beyond the minimal fix
+- Change more than 3 files without written justification
+- Proceed past Phase 3 BLOCKED status
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Bash` | Shell execution | Run tests, reproduce bug, detect test framework, run full test suite |
+| `Read` | File read | Read source files, test files, phase docs, role files |
+| `Write` | File write | Write debug report to `.workflow/.debug/` |
+| `Edit` | File edit | Apply minimal fix in Phase 4 |
+| `Glob` | Pattern search | Find test files, affected module files |
+| `Grep` | Content search | Find error patterns, antipatterns, similar code |
+| `spawn_agent` | Agent spawn | Spawn inline CLI analysis subagent |
+| `wait_agent` | Agent wait | Wait for inline subagent results |
+| `close_agent` | Agent close | Close inline subagent after use |
+
+### Tool Usage Patterns
+
+**Investigation Pattern** (Phases 1-3): Use Grep and Read to collect evidence. No Write or Edit.
+
+**Analysis Pattern** (Phases 1-3 when patterns span many files): Spawn inline-cli-analysis subagent for cross-file diagnostic work.
+
+**Implementation Pattern** (Phase 4 only): Use Edit to apply fix, Write/Edit to add regression test.
+
+**Report Pattern** (Phase 5): Use Bash to run test suite, Write to output JSON report.
+
+---
+
+## Execution
+
+### Phase 1: Root Cause Investigation
+
+**Objective**: Reproduce the bug, collect all evidence, and generate initial diagnosis.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Bug description, symptoms, error messages, context |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/01-root-cause-investigation.md` |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/01-root-cause-investigation.md` before executing.
+2. Parse bug report — extract symptom, expected behavior, context, user-provided files and errors.
+3. Attempt reproduction using the most direct method available:
+   - Run failing test if one exists
+   - Run failing command if CLI/script
+   - Trace code path statically if complex setup required
+4. Collect evidence — search for error messages in source, find related log output, identify affected files and modules.
+5. Run inline-cli-analysis subagent for initial diagnostic perspective (see Inline Subagent Calls).
+6. Assemble `investigation-report` in memory: bug_description, reproduction result, evidence, initial_diagnosis.
+7. Output Phase 1 summary and await assign_task for Phase 2.
+
+**Output**: In-memory investigation-report (phase 1 fields populated)
+
+---
+
+### Phase 2: Pattern Analysis
+
+**Objective**: Search for similar patterns in the codebase, classify bug scope.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Phase 2 instruction |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/02-pattern-analysis.md` |
+| investigation-report | Yes | Phase 1 output in context |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/02-pattern-analysis.md` before executing.
+2. Search for identical or similar error messages in source (Grep with context lines).
+3. Search for the same exception/error type across the codebase.
+4. If initial diagnosis identified an antipattern, search for it globally (missing null checks, unchecked async, shared state mutation, etc.).
+5. Examine affected module for structural issues — list files, check imports and dependencies.
+6. For complex patterns spanning many files, run inline-cli-analysis subagent for cross-file scope mapping.
+7. Classify scope: `isolated` | `module-wide` | `systemic` with justification.
+8. Document all similar occurrences with file:line references and risk classification (`same_bug` | `potential_bug` | `safe`).
+9. Add `pattern_analysis` section to investigation-report in memory.
+10. Output Phase 2 summary and await assign_task for Phase 3.
+
+**Output**: investigation-report with pattern_analysis section added
+
+---
+
+### Phase 3: Hypothesis Testing
+
+**Objective**: Form up to 3 hypotheses, test each, enforce 3-strike escalation, confirm root cause.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Phase 3 instruction |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/03-hypothesis-testing.md` |
+| investigation-report | Yes | Phase 1-2 output in context |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/03-hypothesis-testing.md` before executing.
+2. Form up to 3 ranked hypotheses from Phase 1-2 evidence. Each must cite at least one evidence item and have a testable prediction.
+3. Initialize strike counter at 0.
+4. Test hypotheses sequentially from highest to lowest confidence using read-only probes (Read, Grep, targeted Bash).
+5. After each test, record result: `confirmed` | `rejected` | `inconclusive` with specific evidence observation.
+
+   **Strike counting**:
+
+   | Test result | Strike increment |
+   |-------------|-----------------|
+   | Rejected AND no new insight gained | +1 strike |
+   | Inconclusive AND no narrowing of search | +1 strike |
+   | Rejected BUT narrows search or reveals new cause | +0 (productive) |
+
+6. If strike counter reaches 3 — STOP immediately. Output escalation block (see 3-Strike Escalation Output below). Set status BLOCKED.
+7. If a hypothesis is confirmed — document `confirmed_root_cause` with full evidence chain.
+8. Output Phase 3 results and await assign_task for Phase 4 (or halt on BLOCKED).
+
+**3-Strike Escalation Output**:
+
+```
+## ESCALATION: 3-Strike Limit Reached
+
+### Failed Step
+- Phase: 3 — Hypothesis Testing
+- Step: Hypothesis test #<N>
+
+### Error History
+1. Attempt 1: <H1 description>
+   Test: <what was checked>
+   Result: <rejected/inconclusive> — <why>
+2. Attempt 2: <H2 description>
+   Test: <what was checked>
+   Result: <rejected/inconclusive> — <why>
+3. Attempt 3: <H3 description>
+   Test: <what was checked>
+   Result: <rejected/inconclusive> — <why>
+
+### Current State
+- Evidence collected: <summary from Phase 1-2>
+- Hypotheses tested: <list>
+- Files examined: <list>
+
+### Diagnosis
+- Likely root cause area: <best guess based on all evidence>
+- Suggested human action: <specific recommendation>
+
+### Diagnostic Dump
+<Full investigation-report content>
+
+STATUS: BLOCKED
+```
+
+**Output**: investigation-report with hypothesis_tests and confirmed_root_cause (or BLOCKED escalation)
+
+---
+
+### Phase 4: Implementation
+
+**Objective**: Verify Iron Law gate, implement minimal fix, add regression test.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Phase 4 instruction |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/04-implementation.md` |
+| investigation-report | Yes | Must contain confirmed_root_cause |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/04-implementation.md` before executing.
+
+2. **Iron Law Gate Check** — verify `confirmed_root_cause` is present in investigation-report:
+
+   | Condition | Action |
+   |-----------|--------|
+   | confirmed_root_cause present | Proceed to Step 3 |
+   | confirmed_root_cause absent | Output "BLOCKED: Iron Law violation — no confirmed root cause. Return to Phase 3." Halt. |
+
+3. Plan the minimal fix before writing any code. Document: description, files to change, change types, estimated lines.
+
+   | Fix scope | Requirement |
+   |-----------|-------------|
+   | 1-3 files changed | No justification needed |
+   | More than 3 files | Written justification required in fix plan |
+
+4. Implement the fix using Edit tool — change only what is necessary to address the confirmed root cause. No refactoring, no style changes to unrelated code.
+5. Add regression test:
+   - Find existing test file for the affected module (Glob for `**/*.test.{ts,js,py}` or `**/test_*.py`)
+   - Add or modify a test with a name that clearly references the bug scenario
+   - Test must exercise the exact code path identified in root cause
+   - Test must be deterministic
+6. Re-run the original reproduction case from Phase 1. Verify it now passes.
+7. Add `fix_applied` section to investigation-report in memory.
+8. Output Phase 4 summary and await assign_task for Phase 5.
+
+**Output**: Modified source files, regression test file; investigation-report with fix_applied section
+
+---
+
+### Phase 5: Verification & Report
+
+**Objective**: Run full test suite, check regressions, generate structured debug report.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Phase 5 instruction |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/05-verification-report.md` |
+| investigation-report | Yes | All phases populated |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/05-verification-report.md` before executing.
+2. Detect and run the project's test framework:
+   - Check for `package.json` (npm test)
+   - Check for `pytest.ini` / `pyproject.toml` (pytest)
+   - Check for `go.mod` (go test)
+   - Check for `Cargo.toml` (cargo test)
+3. Record test results: total, passed, failed, skipped. Note if regression test passed.
+4. Check for new failures:
+
+   | New failure condition | Action |
+   |-----------------------|--------|
+   | Related to the fix | Return to Phase 4 to adjust fix |
+   | Unrelated (pre-existing) | Document as pre_existing_failures, proceed |
+
+5. Generate debug report JSON following schema in `~/.codex/skills/investigate/specs/debug-report-format.md`. Populate all required fields from investigation-report phases.
+6. Create output directory and write report:
+   ```
+   Bash: mkdir -p .workflow/.debug
+   ```
+   Filename: `.workflow/.debug/debug-report-<YYYY-MM-DD>-<slug>.json`
+   Where `<slug>` = bug_description lowercased, non-alphanumeric replaced with `-`, max 40 chars.
+7. Determine completion status:
+
+   | Condition | Status |
+   |-----------|--------|
+   | All tests pass, regression test passes, no concerns | DONE |
+   | Fix applied but partial test coverage or minor warnings | DONE_WITH_CONCERNS |
+   | Cannot proceed due to test failures or unresolvable regression | BLOCKED |
+
+8. Output completion status block.
+
+**Output**: `.workflow/.debug/debug-report-<date>-<slug>.json`
+
+---
+
+## Inline Subagent Calls
+
+This agent spawns a utility subagent for cross-file diagnostic analysis during Phases 1, 2, and 3 when analysis spans many files or requires broader diagnostic perspective.
+
+### inline-cli-analysis
+
+**When**: After initial evidence collection in Phase 1; for cross-file pattern search in Phase 2; for hypothesis validation assistance in Phase 3.
+
+**Agent File**: `~/.codex/agents/cli-explore-agent.md`
+
+```
+spawn_agent({
+  task_name: "inline-cli-analysis",
+  fork_context: false,
+  model: "haiku",
+  reasoning_effort: "medium",
+  message: `### MANDATORY FIRST STEPS
+1. Read: ~/.codex/agents/cli-explore-agent.md
+
+<analysis task description — e.g.:
+PURPOSE: Diagnose root cause of bug from collected evidence
+TASK: Analyze error context | Trace data flow | Identify suspicious code patterns
+MODE: analysis
+CONTEXT: @<affected_files> | Evidence: <error_messages_and_traces>
+EXPECTED: Top 3 likely root causes ranked by evidence strength
+CONSTRAINTS: Read-only analysis | Focus on <affected_module>>
+
+Expected: Structured findings with file:line references`
+})
+const result = wait_agent({ targets: ["inline-cli-analysis"], timeout_ms: 180000 })
+close_agent({ target: "inline-cli-analysis" })
+```
+
+Substitute the analysis task description with phase-appropriate content:
+- Phase 1: Initial diagnosis from error evidence
+- Phase 2: Cross-file pattern search and scope mapping
+- Phase 3: Hypothesis validation assistance
+
+### Result Handling
+
+| Result | Action |
+|--------|--------|
+| Success | Integrate findings into investigation-report, continue |
+| Timeout / Error | Continue without subagent result, log warning in investigation-report |
+
+---
+
+## Structured Output Template
+
+After each phase, output the following structure before awaiting the next assign_task:
+
+```
+## Phase <N> Complete
+
+### Summary
+- <one-sentence status of what was accomplished>
+
+### Findings
+- <Finding 1>: <specific description with file:line reference>
+- <Finding 2>: <specific description with file:line reference>
+
+### Investigation Report Update
+- Fields updated: <list of fields added/modified this phase>
+- Key data: <most important finding from this phase>
+
+### Status
+<AWAITING_NEXT_PHASE | BLOCKED: <reason> | DONE>
+```
+
+Final Phase 5 output follows Completion Status Protocol:
+
+```
+## STATUS: DONE
+
+**Summary**: Fixed <bug_description> — root cause was <root_cause_summary>
+
+### Details
+- Phases completed: 5/5
+- Root cause: <confirmed_root_cause>
+- Fix: <fix_description>
+- Regression test: <test_name> in <test_file>
+
+### Outputs
+- Debug report: <reportPath>
+- Files changed: <list>
+- Tests added: <list>
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Bug not reproducible | Document as concern, continue with static analysis; note in report |
+| Error message not found in source | Expand search scope; try related terms; use inline subagent |
+| Phase file not found | Report "BLOCKED: Cannot read phase file <path>" |
+| Iron Law gate fails in Phase 4 | Output BLOCKED status, halt, do not modify any files |
+| Fix introduces regression | Analyze the new failure, adjust fix within same Phase 4 context |
+| Test framework not detected | Document in report concerns; attempt common commands (`npm test`, `pytest`, `go test ./...`) |
+| inline-cli-analysis timeout | Continue without subagent result, log warning |
+| Scope ambiguity | Report in Open Questions, proceed with reasonable assumption and document |