@mrciphersmith/keryx 0.2.70 → 0.2.71

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.cursor.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "workflow"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 # Feature Development (7-Phase)

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "2.0.0"
   category: "workflow"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 <SUBAGENT-STOP>

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

@@ -14,8 +14,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.3.0"
   category: "orchestration"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 # Flow Orchestrator
@@ -84,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"]
@@ -128,10 +128,21 @@ it already tried. The flow package does.
       ```
 
    5. Apply the Phase 4 attempt budget against the **persisted** count. If
-      `attempts.count` for the task has already reached six, 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. If the flow is `blocked`, read the blocking reason from `journal.md`,
+      `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.
 
@@ -231,8 +242,13 @@ did not exist and 24 completed flows shipped with an open task:
   `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`, or when its disposition is `skipped` with no recorded reason;
+- 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
@@ -346,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
@@ -392,18 +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,
+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.
-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
+
+   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:**

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.codex.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "implementation"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Task Implementer
@@ -284,7 +284,25 @@ npm run build-storybook   # Verify stories compile
 | Test failures | Fix failing tests, re-commit |
 | Story build failure | Fix story code, re-commit |
 
-Maximum 3 self-fix attempts per verification step. 
+Maximum 3 self-fix attempts per verification step.
+
+Three, and it is the same three `job-orchestrator` and `flow-orchestrator`
+use: one round bound, not four. *"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. Aider hardcodes `max_reflections = 3`;
+OpenHands' critic uses 3.
+
+**Stop earlier on repetition, whatever the count says.** If an attempt produces
+the same failure output as the previous attempt — the same failing test with the
+same message, the same type error at the same site — do NOT spend the remaining
+attempts. The counter cannot tell "converging slowly" from "stuck", and three
+identical outputs cost the whole budget to learn what the second one already
+said. Report the block instead, naming what repeated.
+
+
 **ROLLBACK POLICY**: If implementation fatally fails (e.g. tests still failing after 3 attempts or unresolvable compilation errors), you MUST run `git reset --hard` to clean the worktree before reporting the failure in Phase 6, unless explicitly instructed to leave it dirty.
 
 **5.5 Re-commit fixes if any:**

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.cursor.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "implementation"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Task Implementer
@@ -284,7 +284,25 @@ npm run build-storybook   # Verify stories compile
 | Test failures | Fix failing tests, re-commit |
 | Story build failure | Fix story code, re-commit |
 
-Maximum 3 self-fix attempts per verification step. 
+Maximum 3 self-fix attempts per verification step.
+
+Three, and it is the same three `job-orchestrator` and `flow-orchestrator`
+use: one round bound, not four. *"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. Aider hardcodes `max_reflections = 3`;
+OpenHands' critic uses 3.
+
+**Stop earlier on repetition, whatever the count says.** If an attempt produces
+the same failure output as the previous attempt — the same failing test with the
+same message, the same type error at the same site — do NOT spend the remaining
+attempts. The counter cannot tell "converging slowly" from "stuck", and three
+identical outputs cost the whole budget to learn what the second one already
+said. Report the block instead, naming what repeated.
+
+
 **ROLLBACK POLICY**: If implementation fatally fails (e.g. tests still failing after 3 attempts or unresolvable compilation errors), you MUST run `git reset --hard` to clean the worktree before reporting the failure in Phase 6, unless explicitly instructed to leave it dirty.
 
 **5.5 Re-commit fixes if any:**