/hns-workflow-ci-loop

name: hns-workflow-ci-loop
description: >
  Unified CI watch + auto-fix loop skill. Polls gh pr checks after /moai sync PR creation,
  classifies required vs auxiliary failures, attempts safe automated patches (max 3 iterations),
  and escalates semantic failures to the user. Use for CI loop workflow — NOT for general
  loop iteration patterns (see moai-workflow-loop).

when_to_use: >
  Use for the CI watch and auto-fix loop after /moai sync PR creation:
  polling gh pr checks, classifying required vs auxiliary failures, safe
  automated patch attempts (max 3 iterations), and escalation of semantic
  failures.

license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Bash, Read
user-invocable: false
metadata:
  version: "0.1.0"
  category: "workflow"
  status: "active"
  updated: "2026-05-22"
  tags: "ci, watch, autofix, polling, github-actions, required-checks, force-push-prohibited"

progressive_disclosure:
  enabled: true
  level1_tokens: 120
  level2_tokens: 5000

CI Loop (`hns-workflow-ci-loop`)

Unified CI watch + auto-fix loop. The orchestrator invokes this skill after `/moai sync` Phase 4 (`gh pr create`) returns a PR number. The skill polls required checks, classifies failures into mechanical vs semantic, attempts safe patches up to 3 iterations, and escalates semantic failures via AskUserQuestion.

Quick Reference

**Trigger**: `/moai sync` Phase 4 PR-create returns a PR number, or an existing PR needs CI monitoring.

**Two phases, one skill**: 1. **Watch** — Poll `gh pr checks` every 30s, classify required vs auxiliary via `.github/required-checks.yml` SSoT; exit on green/fail/timeout. 2. **Auto-fix** — On required-fail (exit 2), receive JSON handoff, run up to 3 patch iterations, escalate semantic failures immediately.

**One-liner**:

MOAI_CIWATCH_GH=gh sh scripts/ci-watch/run.sh <PR_NUMBER> <BRANCH>

**Exit codes**:

• `0` — all required passed → ready-to-merge AskUserQuestion
• `1` — fatal error → surface remediation
• `2` — required failure → JSON handoff → auto-fix phase
• `3` — 30-min hard timeout → blocker message, return control

**HARD invariants**:

• AskUserQuestion is orchestrator-only — CLI, shell scripts, and the `manager-develop` (cycle_type=autofix) subagent MUST NOT call it.
• Force-push is absolutely prohibited (`--force`, `-f`, `--force-with-lease` all banned).
• Max 3 auto-fix iterations; iteration 4+ triggers mandatory blocking AskUserQuestion.
• Semantic failures (race, deadlock, panic, assertion) are never auto-patched.
• Protected files: `.env*`, credentials, `.claude/settings*.json`, `.github/required-checks.yml`,

`scripts/ci-watch/run.sh`.

Implementation Guide

Phase 1 — Watch Loop

**Polling cadence**: 30 seconds minimum (GitHub API rate-limit). Override via `CIWATCH_POLL_INTERVAL` env, never below 30 in production. Test mode uses `MOAI_CIWATCH_NO_SLEEP=1` (single-tick exit).

**30-minute hard timeout**: `CIWATCH_TIMEOUT_SECONDS=1800` default. On timeout, exit 3. Do not auto-restart.

**Required vs auxiliary**: Required checks live in `.github/required-checks.yml` `branches.<pattern>.contexts`. Auxiliary checks listed under `auxiliary:` MUST NOT block ready-to-merge. Hardcoding check names in scripts is prohibited.

**State file**: `.moai/state/ci-watch-active.flag` (YAML). Tracks `pr_number`, `started_at`, `heartbeat_at`, `required_checks`, `abort_requested`. Heartbeat staleness > 90s allows takeover. Abort: `moai pr watch --abort`.

**Background watch standardization**: For long-running PRs (5+ min), use `gh pr checks <PR> --watch` invoked via `run_in_background: true`. Sleep + poll loops are prohibited — they block the orchestrator's main session.

**Status report format** (stderr, state-change ticks only, no ANSI):

[ci-watch] PR #<N>: required 4/6 pass, 2 pending; advisory 0 fail

**Handoff schema on exit 2** — JSON with stable fields: `prNumber`, `branch`, `failedChecks[]` (each entry `{name, runId, logUrl}`), `auxiliaryFailCount`, `totalRequired`. Field stability: `name`, `runId`, `logUrl` are stable contract — do not rename. Schema source: the CI-watch handoff struct.

Phase 2 — Auto-Fix Loop

**Entry condition**: `ci-watch` exit 2 + valid JSON handoff. State file: `.moai/state/ci-autofix-<PR>.json` (PR-scoped, 24-hour staleness threshold).

**OQ2 cadence matrix** (single source of truth for iteration behavior):

• iter 1, any mechanical sub_class → confirm + apply via AskUserQuestion (1st option =

"Apply patch (Recommended)").

• iter 1, semantic/unknown → escalate (no patch attempt) via AskUserQuestion with

diagnosis report.

• iter 2-3, mechanical + sub_class=trivial → silent apply + log (no AskUserQuestion).
• iter 2-3, mechanical + sub_class=non-trivial → confirm + apply via AskUserQuestion.
• iter 2-3, semantic/unknown → escalate (no patch) via AskUserQuestion.
• iter 4+ → mandatory blocking AskUserQuestion (no timer, options: manual fix / revise

SPEC / abandon PR).

"trivial" = whitespace, gofmt/goimports, import-order (matches `classify.sh` `RX_TRIVIAL_*`).

**Patch commit rule**: Every patch = new commit. Format: `fix(ci): auto-fix <classification> failure (iter <N>)`. After push, re-invoke `scripts/ci-watch/run.sh` to restart the watch loop.

**Iteration 4+ escalation** (mandatory blocking, no silent timeout): 1. (Recommended) Manual fix — investigate and fix manually 2. Revise SPEC — revise the SPEC and restart implementation 3. Abandon PR — close the PR and abandon this approach

**`manager-develop` (cycle_type=autofix) spawn prompt** injects: handoff JSON, classification + sub_class, failed CI log + PR diff, mode directive (mechanical → propose unified-diff patch; semantic/unknown → return diagnosis only, no patch). HARD: no AskUserQuestion call from the subagent — return Markdown only.

**Audit log**: `.moai/logs/ci-autofix/<PR-NNN>-<YYYY-MM-DD>.md`. Append-only. Each iteration records classification, sub_class, action, patch_sha, escalation_reason.

Pro