## 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.
> **Review findings closed.** The re-check's residue (`perl -pibak`
bundled-cluster bypass) is applied in `2675bb383`: the perl alternation
accepts any non-space run after the in-place flag, a new FIRE bats
proves the deny, 48/48 policy-dispatch bats green, codex twins
regenerated. Merging on Bo's instruction.
## What
Five semantic lanes from the 2026-08-23 estate audit, each implemented
in an isolated worktree and independently validated by a fresh context,
plus one integration-fixup commit.
**1. Goals: the zero-denominator green is dead** (`estate/goals-honest`)
`GOALS.md` lost its Gates table in the 07-14 cut, so `ao goals validate`
reported `Valid: true` with `GoalCount: 0` in the release smoke on every
push. Now: zero parsed goals ⇒ `Valid: false` with an actionable error
(RED test first); `GOALS.md` carries a real 6-row Gates table whose
every `Check` was executed via `ao goals measure` before shipping;
`goals-affects-files.yaml` pruned of dead ids; the smoke asserts
`goal_count ≥ 1`. Two of the eight fitness properties
(behavior-before-activity, stop-boundary) have no executable check yet —
disclosed in GOALS.md rather than faked.
**2. Front door: the contract file gets a map** (`estate/front-door`)
`AGENTS.md` had zero build/test commands and zero layout — the Go
mechanics lived only in `.claude/rules/go.md`, which Codex (the declared
default runtime) never loads. Added a terse "Repository map and
mechanics" section; compressed the architecture-poetry opener to plain
language; README opens with what-it-does, the maintainer binary install
moved to `docs/install-day2-ops.md`, and the quickstart now ends with an
invitation to open an issue with your verdict. Deleted the dead
`.claude/CLAUDE-base.md` + `build-claude.py` pipeline (zero consumers
since June). `CLAUDE.md` remains a symlink to `AGENTS.md`.
**3. Hooks: first policy that guards the user's invariant**
(`estate/hooks-invariant`)
All four shipped policies guarded this repo's own artifacts. New
`core.verdicts:hand-edit` denies Edit/Write/Bash hand-writes into
`.agents/ao/verdicts/**` — verdicts are content-addressed evidence
written only by the validate flow. RED committed before GREEN
(`d264682c0`); bats prove deny on hand-writes and allow on reads,
intents, and the sanctioned `validate.py` writer. The lane shipped with
in-place editors disclosed as un-matched; the cross-family review
treated that as a blocker and the gap is closed in this PR (see below).
**4. bdd-foundry stops instructing dead commands**
(`estate/workflows-fix`)
The R4 phase told agents to run `ao yield emit`; Phase 5 said pull
holdouts via `ao scenario`; comments cited `ao membrane derive-checks` —
all tombstoned, so R4 failed on every run. Emission is dropped per the
tombstone's guidance (observation stays in the workflow result), Phase 5
grades in-run ground truth plus any caller-supplied register scenarios,
and the lane's initially-overreaching "there is no external holdout
register" wording was caught by its validator and corrected in
integration. Bonus: `workflow-scripts-syntax.yml` globbed the gitignored
`.claude/workflows/` (matched nothing in CI since inception) — now
checks the tracked `workflows/` tree.
**5. Docs honesty: retired vocabulary stops reading as live**
(`estate/docs-honesty`)
`intel_scope` removed from all 24 source SKILL.md + fixture + template +
tutorial (declared by half the corpus, read by zero Go); the schema
keeps accepting it for old-shape third-party skills but now
self-describes as deprecated. `docs/SKILL-API.md` no longer presents
`INTEL`/flywheel/forge/push/ratchet as live.
`docs/knowledge-flywheel.md` states design-vs-implemented truthfully.
ADR-0014's dead link fixed. 25 drifted `images/gemini/skills/` copies
re-synced byte-identical per that bundle's own README contract. All
codex projections regenerated once at integration (`regen-all.sh
--check` passes).
## Evidence
- `cd cli && go test ./...` exit 0 · 4 skill validators PASS ·
`policy-dispatch.bats` + `cross-runtime-hook-baseline.bats` PASS ·
`check-doc-hooks-drift` + `check-hookless-cold-start` PASS ·
`validate-goal-count` PASS · `node --check` on all 8 workflow scripts
PASS · `regen-all.sh --check` PASS
- From repo root: `ao goals validate --json` → `valid: true, goal_count:
6`; from a wrong cwd it now fails closed instead of reporting green.
- Each lane branch carries its own commits; merge commits preserve the
lane structure. Fresh per-lane validators re-ran every suite themselves;
the one FAIL each (workflows wording, cross-lane doc fallout) was fixed
in the integration commit, not waived.
## Cross-family review (Codex, fresh context)
First pass: **FAIL** with one blocker — the new verdict guard explicitly
excluded in-place editors, so `sed -i` silently mutated digest-named
evidence (dispatcher probe returned exit 0). Repaired in `f53945c26`
(one bounded round): three FIRE bats observed RED before the matcher
landed (in-place sed, in-place perl, file deletion), two negative bats
prove reads never fire; policy rationale and SKILL.md updated; codex
twins regenerated; 47/47 bats green. Everything else in the first pass
was affirmed (goals behavior, symlink/build bar, zero retired verbs in
workflows, byte-identical gemini copies, current projections). Focused
re-check: blocker confirmed closed via the dispatcher probe; one regex
corner (`perl -pibak`, header note above) stopped the loop under the
spiral rule.
## Follow-ups (not in this PR)
- `workflows/bdd-foundry.js` `SKILL` constant points at
`skills/behavior-first-planning/SKILL.md`, which was retired in v3.3 —
every phase prompt references a dead path (pre-existing). Needs a design
call: restore the phase discipline inline or repoint honestly.
- Verdict-guard: the noclobber override redirect (`>|`) remains the one
disclosed unmatched write shape.
- `docs/UPGRADING.md` note for third parties still declaring
`intel_scope` (schema accepts, nothing reads).
Executes docs/plans/2026-08-07-agentops-operations-layer-alignment.md:
AgentOps is the operations layer for agentic engineering; the federated
integration graph is the topology, the semantic work-and-proof protocol
is the contract, and RPI is the standard one-experiment traversal.
Retires the ao flywheel command family and all knowledge-flywheel
product state, tombstones the seven-move operating-loop workflow,
narrows ao init and the .agents state writers to declared destinations,
renames the core architecture page to rpi-traversal.md with a
compatibility redirect, aligns AGENTS.md, 25 skills, public and package
copy, regenerates every owned projection, and strengthens the
conformance gates with planted-negative proofs.
Both the alignment subject and the follow-up gate-bookkeeping commit
carry fresh author-distinct validation PASS verdicts with empty
not_checked scope.
Test-Removal-Reason: dead knowledge-flywheel and session-store surfaces were deleted with their tests (operations-layer alignment)
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.
Resolves every spellbreaking finding (the blocker + all 13 majors) from
the 3.3.0 release-readiness audit
([docs/audits/release-readiness-3.3-2026-07-20.md](docs/audits/release-readiness-3.3-2026-07-20.md),
included in this PR).
## Finding → fix map
**CLI self-documentation (M1–M3)**
- **M1** `ao robot-docs` prescribed removed `ao inject` → line removed
from the canonical agent workflow; `inject` added to the removed-command
hint table **and** the MIGRATION.md map (drift test
`TestRemovedVerbsHaveMigrationRows` enforces the pair).
- **M2** `ao config --help` documented ~14 env vars for removed
subsystems (RPI/Dream/Council/tiers) → help text and the `--show` env
panel pruned to the 5 vars the binary consumes; mirrored list in
`internal/config` pruned identically.
- **M3** `ao flywheel status` read only legacy `.agents/<section>` while
`ao doctor fix` migrates learnings to canonical `.agents/ao/learnings` →
new `quality.KnowledgeSectionDirs` dual-roots every knowledge reader
(tier counts, new/stale artifacts, retros, health delta, utility, loop
metrics, retrievable-citation stats — plus the golden-signals readers
`ComputeResearchClosure`/`ComputeReuseConcentration` that the fresh
verification pass caught as missed). Sandbox-proven twice: a learning
existing only under `.agents/ao/learnings` appears in all metrics, and a
research file only under `.agents/ao/research` flips closure from
`starved/0` to `unmined/1 orphan`.
**Release story (M4–M6)**
- **M4** CHANGELOG `[3.3.0]` omitted post-07-17 surfaces → folded in `ao
eval` (#921), default-build `ao flywheel`, the PreToolUse policy engine,
and the #919 cleanup; date moved to 2026-07-20; `docs/CHANGELOG.md`
re-synced (changelog.sync gate green).
- **M5** MIGRATION.md attributed `ao eval` to a nonexistent "3.4" → now
"returned in 3.3".
- **M6** four release surfaces claimed a 50-skill corpus vs 48
everywhere real → all counts now 48 (CHANGELOG ×2, docs/3.3.md,
release-notes page ×2).
**Install story (M7 — product decision by Bo)**
npx first (universal — installs into all coding agents), **plugins for
Claude Code/Codex encouraged**, checkout + `ao skills link` as the
source-tracked/contributor path; curl installers stay tombstones.
Harmonized across README, UPGRADING, install-day2-ops, MIGRATION,
3.3.md, CHANGELOG, the release-notes page, all six installer tombstone
messages (`install.sh` + claude/codex/agy/opencode/`codex.ps1`), and the
site's CLI page. All "legacy migration-only / not the recommended path"
plugin branding removed.
**Docs site (B1, M8–M12)**
- **B1** generated site CLI page instructed a tombstoned curl installer,
nonexistent `ao rpi phased`, and wrong skills dir → `emit_index()`
rewritten to the real install menu + a quickstart of commands that
exist; semantic loop correctly attributed to skills.
- **M8** deploy workflow's `--strict` contradicted mkdocs.yml's declared
non-strict policy and aborted the build → flag dropped (lychee +
validate-links.sh own link checking).
- **M9** site banner said "AgentOps 2.x" → now 3.3.
- **M10** ~176 internal files (audits/plans/handoffs/… + TEMP scratch
doc) published and dominated search → `exclude_docs` extended; built
site verified free of them; search index 4,751 → 2,444 entries.
- **M11/M12** newcomer-guide skill links and all six SCHEMAS.md links
404'd on the site → absolute GitHub URLs (resolve on both GitHub and the
site). The fresh verification pass found the same class on
`docs/contracts/index.md` (nav-listed),
`docs/contracts/corpus-learning-seam.md`,
`docs/templates/slice-validation.md`, and five
`docs/architecture/gas-city-factory.md` links into now-excluded
`docs/audits/` — all repointed to absolute GitHub URLs.
- Also from the verification pass: robot-docs exit-code table no longer
says "bead claimed" (removed concept), and the docs.yml comment now
cites the link checker that actually runs
(`tests/docs/validate-links.sh` via doc-release checks) instead of
lychee.
**Skills corpus (M13)**
- rch skill instructed 5 nonexistent scripts + 8 nonexistent reference
files as recovery steps → pruned to the 7 real references; the
wire-level `printf | rch` probe replaces the phantom `protocol_test.sh`;
codex twin regenerated (parity gates green).
## Verification
- `go vet` clean; **full test suite 60/60 packages pass** (includes the
new-shape flywheel/quality/config tests and the inject↔MIGRATION drift
test).
- **`ao gate check --full --scope worktree`: 67/67 pass, 0 warnings**
over this exact change set (changelog sync, shellcheck on the edited
installer, skill mesh + codex parity, manifests/schema/triggers,
provenance chain).
- `scripts/regen-all.sh --check`: all generated projections current.
- Rebuilt binary re-exercised: `robot-docs` clean, `ao inject` tombstone
live, config help clean, flywheel sandbox proof above.
- `mkdocs build` exit 0; warnings 84 → 46 (remainder is the accepted
out-of-tree-link class per mkdocs.yml's declared policy).
- Fresh-context adversarial verification workflow over all four fix
groups (results in session log).
## Known residuals (deliberately out of scope)
- `ao config models` subcommand still renders tier config (its two env
vars ARE consumed; `COUNCIL_CLAUDE_MODEL` in its display list is not —
follow-up).
- Same-class single-rooted readers off the flywheel path:
`learning.coherence` gate glob (`.agents/learnings/**` only),
`quality.CountConstraints`, config `Paths` defaults feeding eval sandbox
deny-lists.
- `scripts/docs-build.sh` still uses `--strict` with its own allowlist
(not wired into any workflow or gate).
- Audit minors 1–8 (rc fallback version string, `config --show`
legacy-fallback display, `ao init` vs doctor layout, doctor's `ao beads
dir` hint, dead `tracker:` key in the example config, doc-skill phantom
scripts, ROADMAP dead links, documentation-index root links).
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>
Squash merge image consolidation after CI repair.\n\nValidated by GitHub Actions: changes, lint, codex-parity, skills-integrity, skill-gates, contracts-sync, correctness on Ubuntu and Windows, security, eval, skill-eval, doctrine-proof, process-hygiene, and summary. Cursor Bugbot was pending/advisory; main has no branch protection/rules requiring it.
A6 from the 2026-05-16 BDD/Gherkin/XP loop audit: intent-issue.md and
slice-validation.md placeholders pointed pre-mortem evidence at
.agents/research/*.md, but /pre-mortem writes
.agents/council/YYYY-MM-DD-pre-mortem-*.md. Fixes copy drift that
taught new loop users the wrong artifact path.
Closes soc-z3qo.5
Introduce the CDLC operating loop as the execution discipline that runs
through the existing DDD/hexagonal seams, refactor 15 process skills to
billboard shape per the agreed tier line caps, and land the DDD frontmatter
v2 backfill (consumes/produces/context_rel) that was in flight on this
branch.
Doctrine + templates:
- docs/architecture/operating-loop.md: operational spine (BDD intent ->
vertical slices -> conflict-free wave -> bead acceptance -> evidence)
- docs/templates/intent-issue.md: BDD-shaped intent issue template
- docs/templates/slice-validation.md: per-slice validation plan template
- docs/cdlc.md: new section linking the conceptual seven phases to the
operating loop; operating-loop.md added to companion docs
- docs/templates/README.md + docs/documentation-index.md: catalog updates
- GOALS.md Directive #12: BDD intent + vertical slice decomposition gate
- .agents/research/2026-05-15-cdlc-dojo-doctrine.md (gitignored, local-only):
compact doctrine source for the maintainer
Process-skill sweep (15 skills):
- "Loop position" section added to: rpi, discovery, plan, implement, crank,
validation, brainstorm, pre-mortem, council, swarm, autodev, post-mortem,
forge, retro, vibe.
- Billboard refactor: bulk procedural content extracted from SKILL.md to
per-skill references/*.md for discovery, validation, implement, crank,
swarm, post-mortem, vibe (5,632 -> 3,205 SKILL.md lines, -43%, with
every new references/*.md linked back from its SKILL.md per the repo
gate).
- Restored ACT.3/ACT.4 sections in post-mortem after the billboard pass to
keep validate-next-work-contract-parity.sh green.
Validation:
- tests/skills/lint-skills.sh: all 15 PASS within declared tier caps
- scripts/audit-codex-parity.sh: PASS for all 15
- scripts/validate-next-work-contract-parity.sh: PASS
- scripts/pre-push-gate.sh --fast: PASS (0 failures, 50 skipped)
- cli/embedded mirror synced via 'cd cli && make sync-hooks'
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The dream-end-user-coverage gate (GOALS.md Directive #8 / soc-hxnr.6) demands
a stock schedule example, but its previous canonical at .agents/schedule.yaml.example
is gitignored under the no-tracked-agents policy — so the gate had no
propagatable file to assert on and stayed red across environments.
Promote the example to docs/templates/schedule.yaml.example (alongside the
existing operator-facing templates), update the gate to prefer that path and
fall back to the operator's runtime .agents/ copy, and re-anchor the
testdata mirror's source-of-truth comment.
Add TestParser_StockExampleMirrorMatchesCanonical to lock the mirror to the
canonical via the parser — drift in name/cron/job_type fails the build, so
operators always get the same schedules the parser tests cover.
docs/INDEX.md (contract catalog) and docs/index.md (MkDocs landing) shared the
same case-folded name on case-insensitive filesystems, leaving the working tree
in a phantom-modified state and breaking contract-compatibility-gate when the
script read whichever file the OS resolved at run time.
Resolves TASK-1 + TASK-2 of .agents/plans/2026-04-26-resolve-docs-index-case-collision.md:
- Move catalog content from HEAD:docs/INDEX.md into docs/documentation-index.md
- Repoint contract validators (scripts/check-contract-compatibility.sh,
scripts/contract-orphans-allowlist.txt) and their tests at the new path
- Update navigation references across README.md, AGENTS.md, CLAUDE.md, and the
docs/ tree (newcomer-guide, CONTRIBUTING, CI-CD, plans/, positioning/,
templates/, contract examples)
- Replace stale docs/README.md mentions in CLAUDE.md / AGENTS.md / repo-execution
profile example with docs/index.md (the actual MkDocs landing)
Verification:
- bash scripts/check-contract-compatibility.sh -> 0 failures, 24 contracts catalogued
- bash tests/scripts/test-contract-compatibility-gate.sh -> 7/7 PASS (verified pre-rebase)
- bash tests/skills/test-repo-native-orchestration.sh -> 28/28 PASS (verified pre-rebase)
- git ls-files | awk casefold-dup scan -> empty
TASK-3 (casefold-collision guard script) and TASK-4 (worktree disposition) from
the plan remain to be done in a follow-up.
Bo