## Loop restore: converge and crank as control flow under the verdict
contract (ADR-0017)
Intent source: `docs/plans/2026-09-03-loop-restore.md` (in this PR).
Decision record:
`docs/adr/ADR-0017-loop-as-control-flow-not-knowledge.md`.
**Why.** The 2026-07-14 single-pass cut (`482307762`) removed the
iterate loop (discovery, crank, converge, evolve, the learn write-half)
together with the unproven compounding claim, although ADR-0011 demoted
only the latter. The control flow was never demoted, and its absence
showed on 2026-09-02, when a three-lane fix needed eight validators and
two stops because the contract had no repair phase. This restores the
loop as control flow and nothing else: no knowledge store, no `ao
converge`/`ao crank`, no evolve, no canary. ADR-0004 and ADR-0011 stay
in force.
**What changes.**
- **RPI gains a bounded repair phase.** On `FAIL` or `NOT_PROVEN` with
findings, repair and re-validate freshly under the convergence law:
caller-declared `repair_rounds` (default 2); open finding set keyed by
stable `findings[].id`, union across validator families, non-growing; no
closed id reopens; the subject digest changed or, for `NOT_PROVEN`, new
digest-bound evidence resolved a named gap. Converged = fresh PASS plus
cross-family PASS on risky surfaces. Plan and Implement keep their
single dispatch. `skills/rpi/scripts/run_once.py` models the law as pure
data (33 tests): rounds are validated for shape (digest required, no
duplicate ids, no PASS with findings, no FAIL without findings),
condition 4's evidence branch needs a NOT_PROVEN previous round, a
non-FAIL current round, new evidence, and a resolved finding, and a PASS
over unchanged bytes after a FAIL is a flip that reports NOT_PROVEN.
`workflows/rpi.js` runs validation as legs (spawned or external primary,
plus a caller-supplied `crossFamily.command` on risky surfaces) merged
worst-of with a union of stable ids; a risky surface without a
cross-family leg is `diversity_unsatisfied` and never converges or
enters repair; a failed repair or re-validation returns NOT_PROVEN with
no stale verdict. Validators return `subjectDigest`, stable finding ids,
and `evidenceRefs`.
- **crank returns as a thin wave executor** (113 lines): the caller
selects the wave and the repair bound, crank invokes RPI per lane
(parallel only on disjoint write and regen scopes), runs the wave
acceptance once, returns evidence, and stops. No retry, budget, queue,
claim, lease, Git, closure, or next-work ownership. Routing golden
`rq-07-wave-execution` ranks it first.
- **validate is cross-family by default on risky surfaces**
(`cli/internal/gates/**`, `scripts/check-*.sh`, `tests/**`,
`skills/*/scripts/**`, hook policies, `lib/**`, security-scanned paths)
with the LAW-0 dispatch table: Claude orchestrating uses read-only
`codex exec`; Codex orchestrating uses an interactive Claude session in
an NTM pane, never `claude -p`. No live adapter means
`diversity_unsatisfied`, which on a risky surface is `NOT_PROVEN`. The
full literal CI command set runs once on the final integrated subject;
routine rounds keep the receipt-driven freshness contract.
- **Conformance assertions flipped under ADR-0017 only:**
`scripts/check-cathedral-cut-conformance.py` (crank live; "Stop
regardless" replaced by positive canaries for the law's four conditions;
a bounded `for` loop that compares against `repair_rounds` is required
in `run_repair_phase`, and the gate executes the law's canaries against
the reference behavior), `workflows/rpi.js`,
`skills/rpi/scripts/validate.sh`,
`evals/agentops-core/rpi-behavior.json`,
`skills/rpi/references/rpi.feature`. Every single-pass public surface
(README, AGENTS.md, PRODUCT.md, CI-CD, agent-workflow-reference,
rpi-traversal, cli/README, quickstart and demo commands, the
operating-contract and product-boundary bats, the Codex-description
oracle) now states repair to convergence.
**Known approximation, disclosed.** The Claude conveyor has no
deterministic shell primitive, so changed paths are derived by the fresh
validator (git status and diff against the clean pre-run tree) and
unioned with the implementer's report; risk is classified over that
union and unreported paths are coverage findings. A validator is still a
model; runtime derivation outside every agent is a follow-up. Family
distinctness of the cross-family leg is asserted by the caller's choice
of command and not verified by the script.
**Not in scope.** Premortem stays a single advisory judge and Plan still
only names the first check (phase boundaries unchanged). No `verdict.v2`
or `rpi-report.v1` change. The loop's own effect on outcomes is
unmeasured and owed a seeded-defect probe, like the rest of the corpus.
**Evidence on the tip.** Regen check clean; full gate green with a
HEAD-built binary; CI's bats command green; Go build/vet/test green;
golangci-lint clean; security gate quick PASS; one fresh validator over
the whole diff; one cross-family read of the design before
implementation (13 findings folded) and two of the integrated diff (9
findings in round one, 11 by round two, 15 by round three, each round
repaired and re-reviewed; the fresh validator passed the tip after round
two and the final tip 1e8adb72d passed a fresh validator (14-scenario
independent harness of the law, full gate 71/71 with a HEAD-built
binary, CI bats 1164/0) and a cross-family read by Gemini 3.8 via AGY,
which closed all six remaining residues with no new findings; Codex was
unreachable at push time).
**Follow-ups filed from the final reviews, not blockers:** the JS
violation check tests growth before reopen while Python tests reopen
first (same stop, different label when both occur in one round);
`cli/testdata/compatibility-baseline/families/{demo,quickstart}/case.json`
assert help-text substrings Cobra never prints (pre-existing, no
consumer); runtime derivation of changed paths outside every agent in
the Claude conveyor.
Keep fresh author-distinct validation mandatory while making verdict and report persistence consumer-driven. Align the RPI/Validate contracts, executable behavior, current guidance, regression coverage, and generated projections; preserve the Gas City 1.4 cutover.
Add an --all-docs mode to check-doc-skill-refs.sh that scans the union of the
pinned doctrine files PLUS the full LIVE docs/** set (scripts/lib/docs-scope.sh),
ratcheted by a new filename-pinned shrink baseline
(scripts/.docs-skill-refs-baseline). Two-way ratchet: a non-baselined live doc
with a dead `/skill` ref FAILS; a baselined file that no longer offends FAILS
demanding a prune. Detection stays slash-syntax + headings only (never bare
skill names). Default (no-flag) behavior is byte-identical.
docs/SKILL-ROUTER.md (the curated router) is covered by --all-docs (a live
docs/** file, never baselined) so a dead ref there FAILS strict, without
perturbing the byte-identical default doc count.
seed.go docs.skill-refs row: Match widened to docs/** + the baseline + the lib;
Args set to [--all-docs --strict]. Burn-down (long-tail only): repointed retired
`/retro`->/post-mortem, `/vibe`->/validate, `/ratchet`->/flywheel,
`/research-multi`->/research, `/implement-wave`->/crank, and reworded the
retired `/dream` across 13 docs/levels + docs/workflows + docs/philosophy
pages, then pruned them from the baseline (91 -> 78 offenders). Owner-locked
pages (comparisons/getting-started/positioning) stay baselined.
Bats twin tests/scripts/check-doc-skill-refs-all-docs.bats covers all the modes.
Completes the staleness epic. 42 P2/P3 files converged to current truth
(bd→br, gascity/gt-sling/mayor→NTM+Agent Mail, daemon→substrate, hooks→hookless,
CI-authoritative→push-to-main local Go gate); GLOSSARY's 18 dead skills/* links
repaired to ../skills/<name>/SKILL.md (19 links, 0 broken); contracts/runbooks
that freeze retired-system nouns bannered RETIRED/HISTORICAL rather than rewritten.
Adds the Arc-7 ratchet — scripts/check-docs-no-retired-tech.sh — which scans all
live docs (260) for retired-subsystem commands/phrases and fails on regression.
A doc opts out by carrying a RETIRED/HISTORICAL/SUPERSEDED banner (or being an
ADR / migration / upgrade / index doc), and lines that describe a removal are not
flagged. Running it caught 12 stale refs the deep-read sweep missed — a
"CI is the authoritative gate" cluster (agentops-brief, primitive-chains,
INCIDENT-RUNBOOK, knowledge-flywheel, philosophy, software-factory), stale
hook-smoke in release-e2e-checklist, and GasCity descriptors in
contracts/index + SCHEMAS + strategic-direction — now fixed. Gate: PASS.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## What
Final slice of the **ag-lk80 doc-staleness epic**. Verified against the
repo.
**ag-ph6h remainder** (local-model / retired-infra framing):
- philosophy.md — "Local 8B (ollama)" Tier-1 caveated as
**optional/user-supplied** (AgentOps ships no model host); "/dream … Gas
City substrate" → out-of-session substrate (NTM + MCP + managed-agents).
- local-compute-routing.md — added a "**Design draft — NOT
implemented**" banner (the local-scout/local-review lanes don't exist as
skills; no local model host); bumped last-reviewed.
**ag-j4tw remainder** (dead test paths):
- testing-skills.md — `tests/_quarantine/claude-code` →
`tests/claude-code` (11 refs; verified that's the real dir with the
skill-test scripts).
- TESTING.md — removed/redirected 9 `tests/hooks/*.bats` refs (dir gone;
3.0 ships no hook scripts) → `tests/scripts/*.bats`; kept the real
git-hooks "Local Hooking" section.
## Verification
- `tests/hooks`=0, `tests/_quarantine/claude-code`=0 in the docs
- markdownlint → 0 errors; `validate-links.sh` → 0 broken (2903 checked)
Closes the last two open children of ag-lk80.
Closes-scenario: ag-ph6h#local-model
Closes-scenario: ag-j4tw#dead-test-paths
Bounded-context: BC1-Corpus
Evidence: docs/philosophy.md
Reframe two stale 2.x hook references in `docs/philosophy.md` to the
AgentOps 3.0 hookless model. Philosophy intact; only the stale hook
framing is corrected.
## Reframes
1. **"What This Is Not" (line 85)** — `the discipline enforced by the
hooks` → `the discipline enforced in CI`, plus an explicit sentence:
AgentOps 3.0 is hookless (skills + CLI guide the workflow, CI is the
authoritative gate); hooks are opt-in, author-it-yourself via the
`hooks-authoring` skill, never installed by default.
2. **"The Validated Thesis" (line 94)** — `10/12 \`ao doctor\` checks
passing with full 7/7 hook coverage` → `10/12 \`ao doctor\` checks
passing, with the full CI gate suite green`.
## Gates (all green)
- forbidden-phrase grep (`ao hooks install|hooks are the
architecture|hooks fire on every`): empty
- markdownlint `docs/philosophy.md`: clean
- mkdocs `--strict`: exit 0
- doc-release gate (`tests/docs/validate-doc-release.sh`): PASS
- diff stat: 1 file, +2 -2
Closes-scenario: ag-pgp#hookless-philosophy
Bounded-context: BC1-Corpus
Evidence: docs/philosophy.md
* docs(positioning): add assurance profile for agent factory rigor
* docs(positioning): frame goals as reconcile setpoints
* chore(scripts): suppress SC2034 on bd_out — set by run_capture via name-ref
Drive-by fix needed to push crank/soc-sx99 — pre-push shellcheck flagged
bd_out as unused in test-rpi-surface-smoke.sh, but it is set indirectly by
run_capture's name-ref pattern. Adds a targeted shellcheck disable comment.
The vertical `│` and corner `┘` on the "Better next session" loop sat
at column 70, one past "Gates" (which ends at column 69). The diagram
visually hung off the right edge.
Moved both to column 69 so the loop closes directly under the "s" of
"Gates". Rebalanced the horizontal fill (22 `─` before text, 21 after)
to preserve loop text centering.
Replaces the original 5-principles framing with the validated context
compiler thesis. Covers: environment problem, flywheel loop, .agents/
as universal format, tiered model, Brownian ratchet, and the Karpathy
bookkeeping insight. 98 lines, evidence-backed.
Five-month retrospective distilled into docs/philosophy.md (five validated
principles for building with coding agents) and a personal observations
section in the README. Links added to INDEX.md and README footer.
Bo