@mrciphersmith/keryx 0.2.69 → 0.2.71

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/SKILL.md

@@ -12,10 +12,10 @@ triggers:
   - "managed implementation"
 metadata:
   author: "MrCipherSmith"
-  version: "1.2.0"
+  version: "1.3.0"
   category: "orchestration"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 # Flow Orchestrator
@@ -54,9 +54,10 @@ Flow state lives in `.metaproject/flows/<flow-id>/`.
 
 CLI-owned files:
 
-- `flow.json` - never edit by hand.
+- `flow.json` - never edit by hand (read it freely; write only via the CLI).
 - status transitions - only through `keryx flow ...`.
 - task status - only through `keryx flow task done ...`.
+- task attempt counts - only through `keryx flow task attempt ...`.
 - frozen acceptance criteria changes - only through
   `keryx flow ac update <id> --reason "<why>"`.
 
@@ -83,8 +84,8 @@ flowchart TD
   H -- "yes" --> I{"Ask user how to finish"}
   I -- "create PR" --> J["create PR and run review/fix loop"]
   J --> K{"review clean, PR mergeable?"}
-  K -- "no, attempts < 6" --> J
-  K -- "no, attempts = 6" --> R["enrich context and change fix strategy"]
+  K -- "no, attempts < 3" --> J
+  K -- "no, attempts = 3 or repetition detected" --> R["enrich context and change fix strategy"]
   R --> J
   K -- "yes" --> L["merge PR into recorded base branch"]
   L --> M["keryx flow implemented --pr"]
@@ -96,7 +97,68 @@ flowchart TD
 
 ## Phase 0: Route And Resume
 
-1. Run `keryx flow list`.
+### 0.0 State Resumption Check
+
+The input contract accepts `mode: "resume"`; this is the procedure behind it.
+Run it before asking the user anything, on **every** invocation — not only when
+`mode` is `resume`. A session that restarts mid-flow remembers nothing of what
+it already tried. The flow package does.
+
+1. Run `keryx flow list`. Any flow whose status is `in-progress`,
+   `implemented`, `completing`, or `blocked` is an interrupted flow.
+2. If one exists, ASK the user, with the concrete numbers, once:
+   "Found an in-flight flow `<id>` '<title>' (status `<status>`, tasks
+   `<done>/<total>`). Resume it, or start a new flow?" Never guess.
+3. If resume:
+   1. Run `keryx flow status <id>` and read the flow package —
+      `description.md`, `plan.md`, `context.md`, `journal.md`, and the frozen
+      `acceptance-criteria.md`.
+   2. Read `.metaproject/flows/<dir>/flow.json` (read-only; it stays CLI-owned)
+      and take `tasks[].attempts.count` and `tasks[].attempts.log` for every
+      task that is not `done`. **That is the attempt count. Never count
+      attempts from your own context** — a resumed session's context starts at
+      zero while the real count does not, and a loop bound computed from zero
+      is not a bound.
+   3. Resume at the first task whose `status` is not `done`, respecting
+      `dependsOn` order.
+   4. Before dispatching a worker for that task, record the attempt:
+
+      ```bash
+      keryx flow task attempt <id> <Tn> --outcome started --detail "resumed after session restart"
+      ```
+
+   5. Apply the Phase 4 attempt budget against the **persisted** count. If
+      `attempts.count` for the task has already reached **three**, do not
+      re-dispatch the same approach: go to the re-planning step (Phase 4, PR
+      review/fix loop, step 4) and record the decision in `journal.md`.
+   6. Run the repetition check before spending an attempt, whatever the count
+      says:
+
+      ```bash
+      keryx review loop --flow <id> --task <Tn>
+      ```
+
+      A non-zero exit means the same finding has recurred or two consecutive
+      rounds produced identical output. Go straight to the re-planning step.
+      Do not spend the remaining attempts on the same approach because the
+      budget has some left — that is the failure this check exists to catch.
+   7. If the flow is `blocked`, read the blocking reason from `journal.md`,
+      resolve or escalate it, then `keryx flow unblock <id>`.
+4. If the user wants a new flow, continue at 0.1.
+
+Record attempts as they happen, not only on resume:
+
+```bash
+keryx flow task attempt <id> <Tn> --outcome started|failed|blocked [--detail "<what happened>"]
+```
+
+`attempts.count` is append-only and lives in `flow.json`. A counter that lives
+only in the orchestrator's context resets to zero exactly when the loop bound
+matters most, which makes it not a counter.
+
+### 0.1 Route
+
+1. Reuse the `keryx flow list` output from 0.0.
 2. If an active flow obviously matches the user request, use it.
 3. If multiple active flows could match, ask one concise question.
 4. If no flow exists and the request is multi-step, create one:
@@ -169,10 +231,33 @@ agree at all - the change could not work in production. The check had been
 identified correctly and then skipped, because nothing made skipping it
 visible.
 
-Tasks are the mechanism that already exists for this: `flow complete` gates
-on them, so an unrun verification step keeps the flow open instead of being
+Tasks are the mechanism for this. `keryx flow complete` runs a `tasks` gate
+over them, so an unrun verification step keeps the flow open instead of being
 quietly dropped.
 
+Know the gate's exact scope, because for years this file claimed a gate that
+did not exist and 24 completed flows shipped with an open task:
+
+- the gate is **opt-in per flow package**, keyed on `gates.tasks` in
+  `flow.json`, which `keryx flow init` writes for every flow it creates. A
+  package created before the gate landed does not carry the flag, and for it
+  the gate reports `skipped` and blocks nothing;
+- a task fails the gate when its status is not `done`; when its disposition is
+  `failed`; when its disposition is `blocked` (terminal, but the work did not
+  happen — and the harness emits this disposition on its own for a run that
+  ended blocked); when its disposition is `skipped` with no recorded reason; or
+  when its disposition is a value this build does not recognise. An
+  unrecognised disposition FAILS rather than falling through: a gate whose
+  default for the unknown case is "pass" is not a gate;
+- to close a task as deliberately not needed, record why:
+
+  ```bash
+  keryx flow task done <id> <Tn> --disposition skipped --reason "<why it was not needed>"
+  ```
+
+Read the `tasks` line in the `flow complete` output. If it says `skipped`, the
+gate did not run and the task list is yours to verify by hand.
+
 Then freeze and start:
 
 ```bash
@@ -258,9 +343,17 @@ properly formatted `subagent-result`.
 | `DONE_WITH_CONCERNS` | Accept, record every concern in `journal.md`, decide continue vs. add a fix task, then `flow task done`. Never silently drop concerns. |
 | `NEEDS_CONTEXT` | Do not fail. Enrich `context_refs`/`files_to_read` from gdgraph/gdctx/wiki/memory, then re-dispatch the same `dispatch_id`. |
 | `BLOCKED` | `keryx flow block <id> --reason "<worker reason>"`; resolve or escalate one concise question, then `flow unblock` and re-dispatch. |
-| `FAILED` | Retry once with the same dispatch. If it fails again, block the flow and surface the error to the user. |
+| `FAILED` | Emitted by harness **child** workers (`src/harness/child/contract.ts`), never by skill workers — `task-implementer` maps its own `failed` onto `BLOCKED`. Retry once with the same dispatch. If it fails again, block the flow and surface the error to the user. |
 
-Carry `run_id`/`dispatch_id` across retries so the flow journal stays traceable.
+Carry `run_id`/`dispatch_id` across retries so the flow journal stays traceable,
+and record every dispatch against the task's persisted counter so a session
+restart does not reset the budget:
+
+```bash
+keryx flow task attempt <id> <Tn> --outcome started --detail "<dispatch_id>"
+# on a BLOCKED or unusable reply, before re-dispatching:
+keryx flow task attempt <id> <Tn> --outcome blocked --detail "<worker reason>"
+```
 
 ## Phase 3: Verification And Review
 
@@ -269,7 +362,23 @@ Before accepting implementation:
 1. Run focused tests for touched scope.
 2. Run `code-verifier`.
 3. Run `keryx health run` when Code Health is enabled.
-4. Run `review-orchestrator` with relevant domains.
+4. Check the bounds, then run `review-orchestrator` with relevant domains.
+
+   ```bash
+   keryx review budget --spent <usd-so-far> --outstanding <subagents you already have in flight>
+   ```
+
+   A non-zero exit means the spend ceiling (3 USD by default) has been reached:
+   **stop and ask the user** rather than dispatching another fan-out.
+
+   `--outstanding` is the part that matters here. `review-orchestrator`
+   dispatches reviewers in parallel and runs *nested* under this skill, and
+   keryx cannot observe subagents in another process. Passing the count you
+   already have in flight is the only thing that makes the concurrency cap mean
+   anything across the nesting; omit it and the cap bounds the reviewer fan-out
+   alone, which the review record then states plainly rather than implying
+   otherwise.
+
 5. If findings require code changes, dispatch fix work through `task-implementer`
    and record the fix task in the flow.
 6. Close the skill-learning loop (see `rules/core/skill-lifecycle.mdc`). Collect
@@ -315,15 +424,45 @@ How should this flow end?
    branch state.
 2. If findings or required check failures remain, create or update a flow fix
    task, dispatch `task-implementer`, push the fix, and run review again.
-3. Allow at most six review/fix attempts for the current approach. Count an
-   attempt when review/check results are available, including a clean result.
-4. If attempt six is not clean, do not blindly repeat the same loop. Enrich
-   context from the findings, affected graph, relevant wiki, and
-   health/testing artifacts; identify the likely cycle cause; choose a
-   materially different fix strategy or split the work into narrower tasks;
-   record the decision in `journal.md`; then continue with the enriched
-   context.
-5. Never merge while findings or required checks remain unresolved. If the
+3. Allow at most **three** review/fix attempts for the current approach. Count
+   an attempt when review/check results are available, including a clean result,
+   and record it with `keryx flow task attempt <id> <Tn> --outcome ...` so the
+   count survives a session restart. Read the budget from that task's
+   `attempts.count` in `flow.json`, never from this session's memory.
+
+   Three, and the same three that `task-implementer` and `job-orchestrator`
+   already use. This skill said six, which was an outlier with nothing behind
+   it. The evidence converges on three: *"the first three to four repair
+   iterations account for most achievable gains"*
+   ([arXiv:2607.05197](https://arxiv.org/abs/2607.05197)); correctness falls
+   **0.820 -> 0.673** across two forced revisions while cumulative ever-correct
+   is **0.847** ([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)) — the
+   agent finds the fix and then destroys it, throwing away ~15 points by not
+   stopping. Aider hardcodes `max_reflections = 3`; OpenHands' critic uses 3.
+   Rounds four through six were not buying convergence; they were buying
+   regressions.
+
+4. **Before** spending an attempt, and regardless of how much budget is left,
+   run the repetition check:
+
+   ```bash
+   keryx review loop --flow <id> --task <Tn>
+   ```
+
+   It escalates (non-zero exit) when the same finding recurs in two rounds, or
+   two consecutive rounds produce identical review output. It reads the review
+   packages on disk and the persisted `attempts.count`, not this session's
+   memory, and it deliberately never reads the remaining budget — an agent
+   emitting the identical failing output three times must be caught on the
+   second, not after the budget runs out.
+
+5. If the third attempt is not clean, **or the repetition check escalated
+   earlier**, do not blindly repeat the same loop. Enrich context from the
+   findings, affected graph, relevant wiki, and health/testing artifacts;
+   identify the likely cycle cause; choose a materially different fix strategy
+   or split the work into narrower tasks; record the decision in `journal.md`;
+   then continue with the enriched context.
+6. Never merge while findings or required checks remain unresolved. If the
    re-planned approach still cannot produce a mergeable PR, leave the flow
    `in-progress` and report the blocker instead of forcing completion.
 

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/SKILL.codex.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "analysis"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Issue Analyzer

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/SKILL.cursor.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "analysis"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Issue Analyzer

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/SKILL.md

@@ -12,8 +12,8 @@ metadata:
   version: "1.1.0"
   category: "analysis"
   agent_worthy: true
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Issue Analyzer

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/SKILL.opencode.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "analysis"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Issue Analyzer

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/SKILL.zed.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "analysis"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Issue Analyzer

package/src/gdskills/bundled/skills/orchestration/job-documenter/SKILL.codex.md

@@ -10,8 +10,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "documentation"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Job Documenter

package/src/gdskills/bundled/skills/orchestration/job-documenter/SKILL.cursor.md

@@ -10,8 +10,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "documentation"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Job Documenter

package/src/gdskills/bundled/skills/orchestration/job-documenter/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: job-documenter
+model_tier: light
 description: "Use when a job folder needs to be initialized, or analysis/report/review documents need to be created or updated in jobs/."
 triggers:
   - "Document job"
@@ -10,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "documentation"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 <SUBAGENT-STOP>

package/src/gdskills/bundled/skills/orchestration/job-documenter/SKILL.opencode.md

@@ -10,8 +10,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "documentation"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Job Documenter

package/src/gdskills/bundled/skills/orchestration/job-documenter/SKILL.zed.md

@@ -10,8 +10,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "documentation"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Job Documenter

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.codex.md

@@ -23,8 +23,8 @@ metadata:
   author: "MrCipherSmith"
   version: "3.2.0"
   category: "orchestration"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 <SUBAGENT-STOP>
@@ -971,8 +971,22 @@ Review complete:
 
 Only runs if NEEDS_FIX is true. Default max: **3 iterations** (`max_review_iterations`).
 
+Three is the shared round bound: `task-implementer`, `flow-orchestrator` and
+this skill all use it. *"The first three to four repair iterations account for
+most achievable gains"* ([arXiv:2607.05197](https://arxiv.org/abs/2607.05197));
+correctness falls **0.820 -> 0.673** across two forced revisions while
+cumulative ever-correct is **0.847**
+([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)). Aider hardcodes
+`max_reflections = 3`; OpenHands' critic uses 3.
+
+The bound is a ceiling, not a target. Repetition ends the loop earlier and
+**regardless of remaining iterations** — a counter cannot tell "converging
+slowly" from "stuck", and an agent emitting the identical failing output three
+times spends the whole budget before anything notices.
+
 ```
 UNRESOLVED_FINDINGS = all CRITICAL + WARNING findings from step 2.6
+PREVIOUS_REVIEW_OUTPUT = <the review output from step 2.6>
 
 FOR iteration in [1, 2, 3]:
   IF NOT NEEDS_FIX: BREAK
@@ -992,8 +1006,19 @@ FOR iteration in [1, 2, 3]:
   6. Recompute NEEDS_FIX from new findings
   7. Update UNRESOLVED_FINDINGS = remaining CRITICAL + WARNING
 
-IF still NEEDS_FIX after max iterations:
-  Log "Unresolved after <N> iterations" with finding list → continue to checks
+  8. STUCK CHECK — runs before the next iteration and ignores the budget:
+     IF any finding identity is in UNRESOLVED_FINDINGS for the SECOND iteration
+        OR the new review output is identical to PREVIOUS_REVIEW_OUTPUT
+     THEN log "stuck: <what repeated>" and BREAK, even with iterations left.
+     Identity is the finding's dedupe_key when it has one, otherwise
+     reviewer + file + symbol + problem — never the display id, which is
+     per-report and would fire on every second iteration whatever happened.
+  9. PREVIOUS_REVIEW_OUTPUT = the new review output
+
+IF still NEEDS_FIX after max iterations, or the stuck check broke the loop:
+  Log "Unresolved after <N> iterations" with finding list, and say WHICH of the
+  two ended it — a budget exhausted and a loop detected call for different next
+  steps → continue to checks
 ```
 
 **Fix prompt escalation pattern:**

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.cursor.md

@@ -23,8 +23,8 @@ metadata:
   author: "MrCipherSmith"
   version: "3.2.0"
   category: "orchestration"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 <SUBAGENT-STOP>
@@ -971,8 +971,22 @@ Review complete:
 
 Only runs if NEEDS_FIX is true. Default max: **3 iterations** (`max_review_iterations`).
 
+Three is the shared round bound: `task-implementer`, `flow-orchestrator` and
+this skill all use it. *"The first three to four repair iterations account for
+most achievable gains"* ([arXiv:2607.05197](https://arxiv.org/abs/2607.05197));
+correctness falls **0.820 -> 0.673** across two forced revisions while
+cumulative ever-correct is **0.847**
+([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)). Aider hardcodes
+`max_reflections = 3`; OpenHands' critic uses 3.
+
+The bound is a ceiling, not a target. Repetition ends the loop earlier and
+**regardless of remaining iterations** — a counter cannot tell "converging
+slowly" from "stuck", and an agent emitting the identical failing output three
+times spends the whole budget before anything notices.
+
 ```
 UNRESOLVED_FINDINGS = all CRITICAL + WARNING findings from step 2.6
+PREVIOUS_REVIEW_OUTPUT = <the review output from step 2.6>
 
 FOR iteration in [1, 2, 3]:
   IF NOT NEEDS_FIX: BREAK
@@ -992,8 +1006,19 @@ FOR iteration in [1, 2, 3]:
   6. Recompute NEEDS_FIX from new findings
   7. Update UNRESOLVED_FINDINGS = remaining CRITICAL + WARNING
 
-IF still NEEDS_FIX after max iterations:
-  Log "Unresolved after <N> iterations" with finding list → continue to checks
+  8. STUCK CHECK — runs before the next iteration and ignores the budget:
+     IF any finding identity is in UNRESOLVED_FINDINGS for the SECOND iteration
+        OR the new review output is identical to PREVIOUS_REVIEW_OUTPUT
+     THEN log "stuck: <what repeated>" and BREAK, even with iterations left.
+     Identity is the finding's dedupe_key when it has one, otherwise
+     reviewer + file + symbol + problem — never the display id, which is
+     per-report and would fire on every second iteration whatever happened.
+  9. PREVIOUS_REVIEW_OUTPUT = the new review output
+
+IF still NEEDS_FIX after max iterations, or the stuck check broke the loop:
+  Log "Unresolved after <N> iterations" with finding list, and say WHICH of the
+  two ended it — a budget exhausted and a loop detected call for different next
+  steps → continue to checks
 ```
 
 **Fix prompt escalation pattern:**

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -23,8 +23,8 @@ metadata:
   author: "MrCipherSmith"
   version: "3.2.0"
   category: "orchestration"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 <SUBAGENT-STOP>
@@ -973,8 +973,22 @@ Review complete:
 
 Only runs if NEEDS_FIX is true. Default max: **3 iterations** (`max_review_iterations`).
 
+Three is the shared round bound: `task-implementer`, `flow-orchestrator` and
+this skill all use it. *"The first three to four repair iterations account for
+most achievable gains"* ([arXiv:2607.05197](https://arxiv.org/abs/2607.05197));
+correctness falls **0.820 -> 0.673** across two forced revisions while
+cumulative ever-correct is **0.847**
+([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)). Aider hardcodes
+`max_reflections = 3`; OpenHands' critic uses 3.
+
+The bound is a ceiling, not a target. Repetition ends the loop earlier and
+**regardless of remaining iterations** — a counter cannot tell "converging
+slowly" from "stuck", and an agent emitting the identical failing output three
+times spends the whole budget before anything notices.
+
 ```
 UNRESOLVED_FINDINGS = all CRITICAL + WARNING findings from step 2.6
+PREVIOUS_REVIEW_OUTPUT = <the review output from step 2.6>
 
 FOR iteration in [1, 2, 3]:
   IF NOT NEEDS_FIX: BREAK
@@ -994,8 +1008,19 @@ FOR iteration in [1, 2, 3]:
   6. Recompute NEEDS_FIX from new findings
   7. Update UNRESOLVED_FINDINGS = remaining CRITICAL + WARNING
 
-IF still NEEDS_FIX after max iterations:
-  Log "Unresolved after <N> iterations" with finding list → continue to checks
+  8. STUCK CHECK — runs before the next iteration and ignores the budget:
+     IF any finding identity is in UNRESOLVED_FINDINGS for the SECOND iteration
+        OR the new review output is identical to PREVIOUS_REVIEW_OUTPUT
+     THEN log "stuck: <what repeated>" and BREAK, even with iterations left.
+     Identity is the finding's dedupe_key when it has one, otherwise
+     reviewer + file + symbol + problem — never the display id, which is
+     per-report and would fire on every second iteration whatever happened.
+  9. PREVIOUS_REVIEW_OUTPUT = the new review output
+
+IF still NEEDS_FIX after max iterations, or the stuck check broke the loop:
+  Log "Unresolved after <N> iterations" with finding list, and say WHICH of the
+  two ended it — a budget exhausted and a loop detected call for different next
+  steps → continue to checks
 ```
 
 **Fix prompt escalation pattern:**

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.opencode.md

@@ -23,8 +23,8 @@ metadata:
   author: "MrCipherSmith"
   version: "3.2.0"
   category: "orchestration"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 <SUBAGENT-STOP>
@@ -971,8 +971,22 @@ Review complete:
 
 Only runs if NEEDS_FIX is true. Default max: **3 iterations** (`max_review_iterations`).
 
+Three is the shared round bound: `task-implementer`, `flow-orchestrator` and
+this skill all use it. *"The first three to four repair iterations account for
+most achievable gains"* ([arXiv:2607.05197](https://arxiv.org/abs/2607.05197));
+correctness falls **0.820 -> 0.673** across two forced revisions while
+cumulative ever-correct is **0.847**
+([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)). Aider hardcodes
+`max_reflections = 3`; OpenHands' critic uses 3.
+
+The bound is a ceiling, not a target. Repetition ends the loop earlier and
+**regardless of remaining iterations** — a counter cannot tell "converging
+slowly" from "stuck", and an agent emitting the identical failing output three
+times spends the whole budget before anything notices.
+
 ```
 UNRESOLVED_FINDINGS = all CRITICAL + WARNING findings from step 2.6
+PREVIOUS_REVIEW_OUTPUT = <the review output from step 2.6>
 
 FOR iteration in [1, 2, 3]:
   IF NOT NEEDS_FIX: BREAK
@@ -992,8 +1006,19 @@ FOR iteration in [1, 2, 3]:
   6. Recompute NEEDS_FIX from new findings
   7. Update UNRESOLVED_FINDINGS = remaining CRITICAL + WARNING
 
-IF still NEEDS_FIX after max iterations:
-  Log "Unresolved after <N> iterations" with finding list → continue to checks
+  8. STUCK CHECK — runs before the next iteration and ignores the budget:
+     IF any finding identity is in UNRESOLVED_FINDINGS for the SECOND iteration
+        OR the new review output is identical to PREVIOUS_REVIEW_OUTPUT
+     THEN log "stuck: <what repeated>" and BREAK, even with iterations left.
+     Identity is the finding's dedupe_key when it has one, otherwise
+     reviewer + file + symbol + problem — never the display id, which is
+     per-report and would fire on every second iteration whatever happened.
+  9. PREVIOUS_REVIEW_OUTPUT = the new review output
+
+IF still NEEDS_FIX after max iterations, or the stuck check broke the loop:
+  Log "Unresolved after <N> iterations" with finding list, and say WHICH of the
+  two ended it — a budget exhausted and a loop detected call for different next
+  steps → continue to checks
 ```
 
 **Fix prompt escalation pattern:**

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.zed.md

@@ -23,8 +23,8 @@ metadata:
   author: "MrCipherSmith"
   version: "3.2.0"
   category: "orchestration"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 <SUBAGENT-STOP>
@@ -971,8 +971,22 @@ Review complete:
 
 Only runs if NEEDS_FIX is true. Default max: **3 iterations** (`max_review_iterations`).
 
+Three is the shared round bound: `task-implementer`, `flow-orchestrator` and
+this skill all use it. *"The first three to four repair iterations account for
+most achievable gains"* ([arXiv:2607.05197](https://arxiv.org/abs/2607.05197));
+correctness falls **0.820 -> 0.673** across two forced revisions while
+cumulative ever-correct is **0.847**
+([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)). Aider hardcodes
+`max_reflections = 3`; OpenHands' critic uses 3.
+
+The bound is a ceiling, not a target. Repetition ends the loop earlier and
+**regardless of remaining iterations** — a counter cannot tell "converging
+slowly" from "stuck", and an agent emitting the identical failing output three
+times spends the whole budget before anything notices.
+
 ```
 UNRESOLVED_FINDINGS = all CRITICAL + WARNING findings from step 2.6
+PREVIOUS_REVIEW_OUTPUT = <the review output from step 2.6>
 
 FOR iteration in [1, 2, 3]:
   IF NOT NEEDS_FIX: BREAK
@@ -992,8 +1006,19 @@ FOR iteration in [1, 2, 3]:
   6. Recompute NEEDS_FIX from new findings
   7. Update UNRESOLVED_FINDINGS = remaining CRITICAL + WARNING
 
-IF still NEEDS_FIX after max iterations:
-  Log "Unresolved after <N> iterations" with finding list → continue to checks
+  8. STUCK CHECK — runs before the next iteration and ignores the budget:
+     IF any finding identity is in UNRESOLVED_FINDINGS for the SECOND iteration
+        OR the new review output is identical to PREVIOUS_REVIEW_OUTPUT
+     THEN log "stuck: <what repeated>" and BREAK, even with iterations left.
+     Identity is the finding's dedupe_key when it has one, otherwise
+     reviewer + file + symbol + problem — never the display id, which is
+     per-report and would fire on every second iteration whatever happened.
+  9. PREVIOUS_REVIEW_OUTPUT = the new review output
+
+IF still NEEDS_FIX after max iterations, or the stuck check broke the loop:
+  Log "Unresolved after <N> iterations" with finding list, and say WHICH of the
+  two ended it — a budget exhausted and a loop detected call for different next
+  steps → continue to checks
 ```
 
 **Fix prompt escalation pattern:**