/moai-lane-watchdog

name: moai-lane-watchdog
description: >
  One lane stall watchdog iteration: measure lane progress on three
  channels, classify the stall cause, apply the remedy or resolve the
  judgment through the decision ladder — instead of waiting on a reply —
  then record the outcome and report. Reads the unified --auto doctrine at
  .claude/rules/moai/workflow/auto-semantics.md for the ladder, the gate
  inventory, and the record formats.
when_to_use: >
  Use when a loop iteration re-awakens a lane session (the awaken rule: the
  watchdog pass runs BEFORE card work resumes), when a lane shows no
  progress across the watch window, or when a lane needs a judgment to
  proceed and no reply has arrived.
license: Apache-2.0
compatibility: Designed for Claude Code and Codex sessions
allowed-tools: Read, Grep, Glob, Bash(git rev-parse:*), Bash(git status:*), Bash(git log:*), Bash(stat:*), Bash(ls:*), Bash(test:*), Bash(moai integration status:*)
user-invocable: false
metadata:
  version: "1.0.0"
  category: "workflow"
  status: "active"
  tags: "watchdog, stall, lane, ladder, decision-ladder, unattended, auto"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true

Lane Stall Watchdog — One Iteration

One watchdog pass for a lane session (a factory lane running under `moai cc` / `moai glm` / `moai codex`). The law — the ladder, the outcome transitions, the gate inventory, the view–SSOT rule, the record formats — lives in `.claude/rules/moai/workflow/auto-semantics.md`. Read that doctrine before the first pass and whenever a step below needs its detail; this body is the executable procedure.

0. Never prompt

The watchdog never asks the operator a question and never answers an approval gate on anyone's behalf. Everything that would have been a question becomes either a resolved judgment (the ladder) or an explicit wait record. A keep-set gate — environment-impossible, operator-held, or an irreversible external-shared operation — is never satisfied here: the recheck reads the gate surface, and finding no change, it re-records the wait and yields.

1. Measure progress

Three channels (doctrine §3–4):

• **HEAD**: `git rev-parse --short HEAD` in the lane's own worktree.
• **evidence mtimes**: the newest mtime across `.moai/reports/<card-id>/`

and the active SPEC's `progress.md`.

• **integration-window state**: `moai integration status`.

Compare against the previous snapshot at `.moai/state/watchdog/<card-id>.json` (fields: `observed_at`, `head_sha`, `evidence_mtime_max`, `window_state`). The lane is stalled only when ALL THREE channels are unchanged AND the previous observation is at least N minutes old. N defaults to 15 minutes and is a per-invocation parameter — never a config key. No previous snapshot → record a fresh one, no stall verdict (fail-open first observation). One channel moving is progress — evidence mtime advancing without a commit included: end the iteration with a one-line status — unless the lane itself is parked on a delegate (§3.5): then the movement is the delegate's, and the deliverable read in §3.5 decides, not this rule. Write the new snapshot after the verdict.

2. Classify the cause

| Cause | Signature | |---|---| | **awaited-judgment** | the lane stopped where a judgment was needed (a gate, a verdict, a choice) and no reply arrived | | **blocked-by** | the card waits on a predecessor card; the predecessor's landing state is the open question | | **shell-error** | the lane halted on an unadjudicated command failure (a non-zero exit with no recorded disposition) | | **accidental-stop** | the session died or was interrupted mid-card — an API error (a 429) ends the turn with no further model action — and no deliberate stop was recorded | | **awaited-delegate** | the lane parked on delegated work — a spawned agent's report, a background run's completion — and the report or notice has not arrived; an `available` idle notice that promised a later report counts, because that agent sends nothing more unless it is messaged |

No stall / progress detected → end the iteration.

3. Apply the remedy

3.1 awaited-judgment — the decision ladder

Resolve through the ladder IN ORDER (doctrine §6–7). Availability failures fail-open downward; negative or inconclusive verdicts never auto-proceed, and at an authority gate they fail closed.

1. **Disk evidence** — read the deciding artifact directly: audit verdict files, the card's progress record, plan-audit verdicts, evidence paths. Evidence shows proceed → resume. Evidence shows do-not-proceed → record the wait; never proceed against evidence. Unreadable or absent → step 2. 2. **Decision board** — run `moai decision read --scope card:<id>` (the card's rulings plus every standing ruling; doctrine §11: the append-only board under the moai home, keyed by the project). A recorded judgment → follow it. A judgment that says wait → explicit wait record (with an id; doctrine §14). A record whose `resolves` names an open wait ends that wait. `board=absent` / `board=empty` → step 3; never wait on the board being filled. While a wait on the leader stays open, keep the one-shot short recheck of doctrine §14 armed. 3. **Audit cross** — run one `moai` MCP audit tool (`codex_audit`, `glm_audit`, `claude_audit`, or `audit_multi`) for an independent second opinion. Positive → proceed per verdict. Negative → fail-closed: no proceed; record + escalate to step 5. Tool absent → step 4. Inconclusive → record it, → step 4. 4. **jev_ask** — only while `workflow.jev.enabled` is true; a bounded proceed / retry / wait judgment with repeatable, side-effect-free parameters; never for completion, merge, or queue outcomes. Gated off or unavailable → step 5 (fail-open by design). 5. **Lead chat** — last resort. Record the explicit wait (§5 below), then yield.

Write a decision record naming whichever step resolved the judgment (§5 below).

3.2 blocked-by

Read the b