zerocracy#274 detect non-convergence when max-cycles exhausted

The judges CLI exits with code 0 even when --max-cycles is reached
without achieving a fixpoint. The factbase keeps changing on every
cycle, but judges reports "Update completed" with exit 0. This means
baza.rb treats the job as successful when in fact judges may not have
finished processing all facts.

After judges update completes, scan its stdout for the fixpoint
message "has made no changes". If this message is absent but the exit
code is 0, it means --max-cycles was exhausted before convergence.
In that case, exit with code 75 (EX_TEMPFAIL) to signal baza.rb that
the job needs investigation or a retry with higher --max-cycles.

This is a workaround — the proper fix belongs in the judges gem,
which should exit non-zero when max-cycles is exhausted without
convergence.

Author: VasilevNStas

.opencode/PLAYBOOK_274.md

@@ -0,0 +1,29 @@
+# Playbook #274: Detect non-convergence when max-cycles exhausted
+
+## Context
+`judges update --max-cycles=3` always exits 0, even when the factbase never stabilises. `baza.rb` has no way to distinguish "all facts processed" from "ran out of cycles before finishing".
+
+## Strategy
+1. Capture `judges update` stdout instead of letting it passthrough directly
+2. After execution, grep for `"has made no changes"` (the fixpoint indicator)
+3. If exit code is 0 but the indicator is missing → exit 75 (EX_TEMPFAIL)
+4. Preserve and propagate all other exit codes
+
+## Patterns Used
+- **Output introspection**: read the tool's own diagnostic output to infer state
+- **Fail with intent**: EX_TEMPFAIL (75) signals "try again later with adjustments", unlike a generic error
+- **Transparent passthrough**: stdout is still printed so `baza.rb` and operators can see the full log
+
+## Known Pitfalls
+- This depends on the exact message string `"has made no changes"` from the `judges` gem. If the gem changes this message, the check breaks. Mitigation: pin judges version or add the check as a puzzle to contribute a proper exit code to the judges gem.
+- Not a substitute for a fix in `judges` gem itself — the gem should exit != 0 when max-cycles is reached without convergence. This is a workaround.
+
+## Verification Commands
+```bash
+# Create a judge that always inserts — never converges
+mkdir -p /tmp/non-converge
+echo '$fb.insert.always = 1' > /tmp/non-converge/non-converge.rb
+# ... set up factbase and run entry.sh
+./entry.sh test-job /tmp/some-dir
+echo $?  # must be 75
+```

.opencode/PROJECT_SUMMARY_274.md

@@ -0,0 +1,23 @@
+# Project Summary: #274 Detect non-convergence when max-cycles exhausted
+
+## Issue Overview
+No issue — direct improvement based on architecture analysis of baza.rb integration.
+
+## Problem
+The `judges` CLI exits with code 0 even when `--max-cycles` is reached without achieving convergence (fixpoint). The factbase kept changing on every cycle, but `judges` reports "Update completed" with exit 0. This means `baza.rb` treats the job as successful when in fact judges may not have finished processing all facts — the result is silently incomplete.
+
+## Solution
+After `judges update` completes, scan its stdout for the fixpoint message `"has made no changes"`. If this message is absent but the exit code is 0, it means `--max-cycles` was exhausted before convergence was reached. In that case, exit with code 75 (EX_TEMPFAIL) to signal `baza.rb` that the job needs investigation or a retry with higher `--max-cycles`.
+
+## Verification
+- [ ] `bundle exec rubocop` — 0 offenses
+- [ ] `bundle exec rake` — all tasks pass
+- [ ] Manual: create a judge that never converges, run `entry.sh`, verify exit 75
+
+## Key Discoveries
+- The `judges` gem does not distinguish between "converged" and "max-cycles exhausted" in its exit code. Both are exit 0. This is a design gap in the gem itself.
+- The message `"has made no changes"` is emitted by judges when a cycle produces zero churn. Its absence after the final cycle is the only reliable signal of non-convergence.
+- Exit code 75 (EX_TEMPFAIL) is chosen because the condition is transient — a retry with different parameters may succeed.
+
+## Files Changed
+- `entry.sh` — added stdout analysis for convergence detection

README.md

@@ -15,7 +15,7 @@ based on business rules. Judges run in cycles until no new facts are produced.
 
 ## Project Structure
 
-```
+```text
 judges/<name>/<name>.rb     — judge implementation, auto-discovered
 judges/<name>/<name>.yml    — YAML test for the judge (data-driven)
 lib/                        — shared Ruby libraries
@@ -41,7 +41,7 @@ bundle exec rake
 mkdir judges/hello-world
 ```
 
-2. Write the judge logic in `judges/hello-world/hello-world.rb`:
+1. Write the judge logic in `judges/hello-world/hello-world.rb`:
 
 ```ruby
 # frozen_string_literal: true
@@ -56,7 +56,7 @@ Fbe.fb.query('(and (exists hi) (absent hello))').each do |f|
 end
 ```
 
-3. Write a YAML test in `judges/hello-world/hello-world.yml`:
+1. Write a YAML test in `judges/hello-world/hello-world.yml`:
 
 ```yaml
 # SPDX-FileCopyrightText: Copyright (c) 2024-2026 Zerocracy
@@ -74,13 +74,13 @@ expected:
   - /fb/f[_id=1]/hello
 ```
 
-4. Run the judge YAML tests:
+1. Run the judge YAML tests:
 
 ```bash
 bundle exec judges test --no-log --disable live --lib lib judges
 ```
 
-5. Run the full build:
+1. Run the full build:
 
 ```bash
 bundle exec rake
@@ -90,13 +90,15 @@ If everything is clean, your judge is ready.
 
 ## Commands
 
+<!-- markdownlint-disable MD013 -->
 | Command | Purpose |
-|---------|---------|
+| ------- | ------- |
 | `bundle exec rake` | Full build (test + judges + rubocop) |
 | `bundle exec rake test` | Ruby unit tests only |
 | `bundle exec judges test --no-log --disable live --lib lib judges` | Judge YAML tests |
 | `bundle exec rubocop` | Code style check |
 | `docker build -t swarm .` | Build Docker image (requires Dockerfile) |
+<!-- markdownlint-enable MD013 -->
 
 ## How to Contribute
 

entry.sh

@@ -29,5 +29,20 @@ fi
 
 self=$(dirname "$(readlink -f "$0")")
 
-judges update --summary --max-cycles=3 --no-log \
-       --option "id=${id}" --lib "${self}/lib" "${self}/judges" "${home}/base.fb"
+set +e
+output=$(judges update --summary --max-cycles=3 --no-log \
+  --option "id=${id}" --lib "${self}/lib" "${self}/judges" "${home}/base.fb" 2>&1)
+# shellcheck disable=SC2181
+exit_code=$?
+set -e
+
+echo "${output}"
+
+if [ "${exit_code}" -eq 0 ] && ! echo "${output}" | grep -q "has made no changes"; then
+  echo "[FATAL] judges finished 3 cycle(s) without convergence. \
+The factbase kept changing until --max-cycles was exhausted. \
+Check judge logic or consider increasing --max-cycles."
+  exit 75
+fi
+
+exit "${exit_code}"