Auto Fix Subsystem

Auto-Fix Subsystem

v2.0 — Watches every gh pr merge and npm run build:* you run, verifies the deploy, and dispatches a Haiku fixer if anything fails.

The full deep-dive lives in the repo at docs/deploy-fix.md. This page is the wiki-friendly summary.

TL;DR

gh pr merge --squash --admin
        │
        ▼ PostToolUse:Bash hook
bin/ops-deploy-fix-merge-trigger
        │
        ▼ background fork
scripts/ops-deploy-monitor.sh
        │
        ├─► poll deploy GitHub Actions run
        ├─► curl /health on success
        ├─► curl /version, compare SHA
        └─► on failure:
              ├── transient?  → gh run rerun
              └── real?       → dispatch headless Haiku deploy-fixer

The same pattern fires for npm run build:* via bin/ops-deploy-fix-build-trigger, dispatching a build-fixer agent.

Components

Path	Role
hooks/hooks.json	Wires both PostToolUse:Bash triggers + the npm run build:* if matcher.
bin/ops-deploy-fix-merge-trigger	Hook handler for merges. Parses, gates, forks the monitor.
bin/ops-deploy-fix-build-trigger	Hook handler for failing local builds.
scripts/ops-deploy-monitor.sh	Long-lived background watcher per merge.
scripts/lib/deploy-fix-common.sh	Shared helpers — lock, budget, dedup, transient classifier, notify.
prompts/deploy-fix.md / prompts/build-fix.md	Legacy prompt templates (kept for reference; dispatch now uses --agent flag).
agents/deploy-fixer.md / agents/build-fixer.md	Pre-installed specialist agents.
config/post-merge-services.example.json	Plugin-default service registry.
skills/ops-deploy-fix/SKILL.md	/ops:deploy-fix user-facing skill.
tests/test-deploy-fix-hooks.sh	45 assertions / 11 cases.

Service registry (layered)

project   .claude/post-merge-services.json
              ▲ overrides
user      ~/.claude/config/post-merge-services.json
              ▲ overrides
plugin    config/post-merge-services.example.json

Schema:

{
  "your-org/your-api:dev": {
    "health_url": "https://api-dev.example.com/health",
    "version_url": "https://api-dev.example.com/version",
    "deploy_workflow": "deploy-staging.yml",
    "served_sha_jq": ".commit.sha"
  }
}

Guards

1. Single-flight lock per repo — concurrent merges queue.
2. Hourly budget cap — max_fixes_per_hour (default 3, range 0..20).
3. Content-hash dedup — identical failures don't spawn duplicate agents.
4. Transient classifier — npm registry blips, DNS, OOM, rate-limits → gh run rerun instead of agent.

/ops:deploy-fix skill

Subcommand	Purpose
/ops:deploy-fix	Live status — running monitors, today's history, budget remaining.
/ops:deploy-fix tail <run-id>	Stream the monitor log.
/ops:deploy-fix configure	Open the layered service registry.
/ops:deploy-fix test	Dry-run the merge-trigger hook.

Configuration

See Configuration for the full toggle table. Master switch: deploy_fix_enabled (default true).

See also

• Specialized Agents — deploy-fixer and build-fixer are pre-installed specialists.
• Configuration — every userConfig toggle.
• Setup Wizard — Step 6.5a configures this subsystem.
• Repo deep dive: docs/deploy-fix.md.