Addresses a batch of documentation improvements identified in a full-docs
audit. The goal is to reduce newcomer friction from dead links and missing
canonical references, and to give skill/plugin authors explicit pages for
hooks, schemas, and version migration that were previously implied only by
source code.
Navigation fixes:
- docs/INDEX.md and docs/newcomer-guide.md pointed to the wrong path for
the CLI reference (cli/commands.md vs. the real cli/docs/COMMANDS.md).
Replace with the canonical github URL so both mkdocs and raw-GitHub
readers land on the file.
- INDEX.md Getting Started section now opens with a "pick your path"
router so evaluators, installers, contributors, and upgraders don't
have to triangulate across three overlapping entry points.
- Link docs/getting-started/index.md from INDEX.md (was previously
orphaned) and add an "Install verification" block pointing at ao doctor.
New pages:
- docs/HOOKS.md: user-facing orientation covering lifecycle events,
install/uninstall, customization env vars, and common failure modes,
pointing to cli/docs/HOOKS.md for the deep technical reference.
- docs/SCHEMAS.md: catalog of every JSON Schema under schemas/ and
lib/schemas/, grouped by manifest vs. runtime artifact vs. internal
contract, with validation commands.
- docs/UPGRADING.md: action-required version migration guide. Seeds
Unreleased (2.38.x) and 2.37.x sections covering strict delegation,
--no-lifecycle -> --no-scaffold rename, Olympus bridge removal,
swarm-evidence schema enforcement, and pre-mortem gate tightening.
Reference quality:
- GLOSSARY.md: 11 new terms (.agents/, MEMORY.md, Compact/PreCompact,
Compile, Context Window, Discovery, Dream/Overnight Run alias,
Flywheel Health, Harvest, Holdout, RPI Phase, Session Lifecycle).
- troubleshooting.md: three new failure-mode sections (pre-mortem gate,
go-test-precommit block, context-window compaction recovery).
- CONTRIBUTING.md: escalates the sync-skill-counts.sh requirement from
an easily-missed sentence to a bold callout with CI-failure rationale.
mkdocs.yml: registers the three new pages in nav so they're reachable
from the published site and pass strict build.
Validation:
- tests/docs/validate-links.sh: 1553 links checked, 0 broken.
- tests/docs/validate-doc-release.sh: PASS.
- scripts/docs-build.sh --check: new docs introduce 0 warnings (the
single remaining preexisting warning about index.md is out of scope).
Close the skills/skills-codex ecosystem gaps surfaced by the recent audit:
- docs/SKILLS.md now lists all 69 skills. Added an "Additional Skills" table
covering the 21 previously undocumented entries (autodev, bootstrap, compile,
deps, design, discovery, goals, grafana-platform-dashboard, harvest, perf,
push, readme, red-team, refactor, reverse-engineer-rpi, review, scaffold,
scenario, security, security-suite, test). Removed stale `/knowledge` router
alias and nonexistent `extract` internal-table row.
- Added `scripts/validate.sh` behavioral contracts to the 16 skills that lacked
one (autodev, bootstrap, deps, design, discovery, dream, harvest, llm-wiki,
perf, red-team, refactor, review, scaffold, scenario, test, validation).
Each encodes skill-specific assertions beyond the frontmatter check. Coverage:
53/69 -> 69/69.
- Fixed `scripts/check-codex-parity-drift.sh` which was a silent no-op: it
passed a non-existent --check flag to audit-codex-parity.py, swallowed the
argparse error via `|| true`, then grep'd for strings the audit never emits.
Now uses the exit code + JSON output and correctly fails on drift.
- Added `scripts/check-skill-size.sh` (warn>500, fail>800 lines) to flag
oversized SKILL.md files that should decompose into references/*.md. Current
state: 6 warnings (crank/implement/post-mortem/release/swarm/vibe), 0 fails.
Hygiene sweep: heal.sh --strict clean, codex parity audit clean, 69/69
validators green, size-lint reports no failures.
https://claude.ai/code/session_014AgjT36REb94fjL7sxrnFf
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.
Previous landing was too abstract ("operational layer") and buried the
skills behind a catalog link. Rewrite to:
## docs/index.md
- Open with the concrete problem: "Coding agents don't do their own
bookkeeping" → session 15 rediscovers session 1's lessons without
AgentOps
- Add "The primary use case" section with the 4-layer table (bookkeeping,
validation, primitives, flows) and the flywheel diagram
- Add "See It Work" section with actual terminal examples of /council
and /rpi so readers see what the system does, not just what it is
- Add "The headline skills" table with 9 skills + "use it when" framing
(matches README.md)
- Add "Advanced: Day Loop and Night Loop" explaining /evolve and /dream
- Tabbed install blocks for Claude Code / Codex / OpenCode + ao CLI
## docs/_hooks/gen_skill_pages.py — skills/index.md generator
- Replace generic "Featured Workflows" with the same 9-skill headline
table + use-case framing (consistent with landing and README)
- Reorganize complete catalog into 8 family groups (Validation, Flows,
Bookkeeping, Session, Product, Utility, Platform, PR workflow) so
readers can navigate 69 skills by purpose instead of alphabet
- "Related references" card block moved to the bottom
Both pages now answer "what is this and which skills do I try first"
before linking to the exhaustive catalog.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Docs site — boshu2.github.io/agentops
- Replace Jekyll minima with MkDocs Material (slate dark palette default)
- Landing hero scoped to .landing-hero (no gradient bleed on inner pages)
- Section landings (getting-started, architecture, reference, contracts, levels) with narrative ledes
- Generate skill catalog + per-skill pages from skills/*/SKILL.md at build
- Generate CLI reference from cli/docs/ at build (fails build on missing source)
- Fix every internal link via one-shot migration (scripts/migrations/2026-04-19-fix-docs-links.py)
- Wire mkdocs build --strict into pre-push gate (Check 25a)
- Replace .github/workflows/pages.yml with .github/workflows/docs.yml (actions/deploy-pages)
- README + docs/CONTRIBUTING updated with docs-build toolchain on-ramp
- tests/docs/validate-links.sh patched to understand mkdocs-generated paths
## RPI orchestrator strict-delegation contract
- Strict sub-skill delegation is now the default for /rpi, /discovery, /validation. No --full flag — always on.
- Canonical contract in skills/shared/references/strict-delegation-contract.md (plus Codex mirror)
- Forged learning with detection phrases + corrective actions (ao-inject-ready)
- Rename --no-lifecycle -> --no-scaffold in /discovery (Claude + Codex) with deprecation alias through v2.40.0
- Harden inline-work hotspots with orchestrator-owned markers in /crank STEPS 3a.3, 6.5, 8.7 + Inline Work Policy footer
- Flag consistency: --auto and --interactive scopes documented; --complexity syntax formalized
- CHANGELOG [Unreleased] documents + scaffolds; runtime hook enforcement explicitly deferred
## fix(hooks): go-test-precommit skips when no Go files staged
- Previously ran go vet + go build unconditionally, blocking non-Go commits when Go toolchain was missing or at a different version
- Now checks staged diff and exits cleanly if no *.go or go.{mod,sum,work} files are staged
- Applied to both hooks/ (source) and cli/embedded/hooks/ (synced)
Provenance: full RPI lifecycle with strict delegation at every phase boundary (Phase 1 Skill(discovery) -> Phase 2 Skill(crank) -> Phase 3 Skill(validation) -> Skill(vibe), Skill(post-mortem), Skill(retro)).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Defines a tracked contract for swarm worker result files living under
.agents/swarm/results/<task>.json. These files were implicitly shaped
but never validated — misshapen packets could silently break crank
result ingestion.
- schemas/swarm-evidence.schema.json: JSON Schema. Required: task,
status, files_changed, notes. Optional: tests, gate, evidence,
before/after counters. additionalProperties=true permits task-specific
extensions.
- scripts/validate-swarm-evidence.sh: jq-based validator accepting a
file or directory. ajv fallback when available. Exit 0 pass, 1 fail.
- docs/contracts/swarm-evidence.md: human-readable contract doc with
example and schema link. Added to docs/INDEX.md catalog.
- scripts/pre-push-gate.sh: new section 26b ('swarm evidence schema')
invokes the validator on every push.
- scripts/check-contract-compatibility.sh: extended ref resolution to
also search schemas/ so docs/contracts/*.md can cite
schemas/*.schema.json without tripping the cataloguing check.
Consumes ag-yhr 'Implement executable swarm evidence schema validation'.
{subject}-decision-tree.md (matches docs/skills-decision-tree.md).
Rationale: groups by subject alphabetically; keeps decision-tree as
suffix rather than noisy prefix duplicated across files.
Create docs/skills-decision-tree.md as the single source of truth for
"which skill do I need?". Replace duplicate tables in harvest SKILL.md,
knowledge-activation SKILL.md, and skills-codex mirrors with a pointer
link. Add INDEX.md entry.
Four files used to carry the same table; future edits now go in one
place. Quickstart already surfaces the individual skills under its
GIT=false + GLOBAL_AGENTS=true branch, so it does not need the
expanded reference — it is the entry point, not the index.
Closes na-pmx1.7.
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.
Adds a blocking windows-smoke job, native PowerShell smoke script, Windows docs updates, and moves a Unix-only RPI lock permission test out of the Windows test path.
Adds a Windows PowerShell installer for ao, documents the Windows install path, fixes Windows-specific ao/runtime test issues, and removes the CI ripgrep dependency from the Codex override coverage validator.
Operationalizes the "pre-flight council validation against stale inherited
scope" pattern that caught the na-h61 M8 estimate inflation in the same
session. Five items from the summary table in today's retrospective.
## New flags
/council --evidence (alias --tdd)
Every finding must include 2+ test_assertions (grep, stat, go test, ...)
that would mechanically prove the finding is real. Consolidation clamps
verdict to WARN if any finding lacks assertions. Schema version bumps
3 → 4. See skills/council/references/evidence-mode.md for the full
schema, judge prompt additions, and a worked example.
/council --commit-ready
Also writes the consolidated report to docs/council-log/YYYY-MM-DD-
<mode>-<target-slug>.md (in addition to the transient .agents/council/
path). Use when the verdict is load-bearing for a merged commit and
the provenance should survive rebases. See docs/council-log/README.md.
/rpi --from=implementation --discovery-artifact=<path>
Explicit "external discovery" entry point. When discovery has already
been done by an upstream /council --evidence run (or a hand-written
plan), pass the path and /rpi validates the artifact, extracts scope
into an execution packet, and proceeds straight to /crank. See
skills/rpi/references/discovery-artifact-mode.md. Formalizes the
improvised pattern used in the na-h61 session earlier today.
## New planning rule
skills/plan/references/stale-scope-validation.md
"Re-validate inherited scope estimates against HEAD before acting on
deferred beads, handoff docs, or prior-session plans." Referenced from
skills/plan/SKILL.md and skills/pre-mortem/SKILL.md. Includes the
concrete na-h61 case study (395 LOC estimate collapsed to ~300 LOC
once the council verified the staging infra already existed).
## New committable council artifact path
docs/council-log/
README.md documents the convention and retention policy.
2026-04-11-validate-m8-assumption-validation.md is the canonical
example — the consolidation that caught the na-h61 scope inflation,
now in git history so any future session can re-verify the reasoning.
## Files
skills/council/SKILL.md (+3 lines — new flags)
skills/council/references/evidence-mode.md (new, ~180 lines)
skills/rpi/SKILL.md (+3 lines — new flag)
skills/rpi/references/discovery-artifact-mode.md (new, ~130 lines)
skills/plan/SKILL.md (+1 line — rule ref)
skills/plan/references/stale-scope-validation.md (new, ~100 lines)
skills/pre-mortem/SKILL.md (+1 line — rule ref)
docs/council-log/README.md (new, ~90 lines)
docs/council-log/2026-04-11-validate-m8-... (new, canonical example)
Follows the same-session retrospective request from the user after
closing na-h61. The CLI half (ao beads verify|lint|harvest) ships in a
separate commit.
Council parity: skills-codex/{council,rpi,plan,pre-mortem}/ exists and
is now drifted. Sync deferred per the CLAUDE.md deprecation note on
sync-codex-native-skills.sh — manual edit required, tracked as a
follow-up. Skill-lint remains pre-existing RED on main (unchanged by
this commit).
Reorder the Dream RunLoop iteration body so fitness is measured against
the staging tree BEFORE cp.Commit() instead of against the already-mutated
live tree after. Under strict mode, a regression halt now fires before
the live ~/.agents/ is ever touched — external observers never see a
regressed state.
## What changed
Before (Option B):
REDUCE → COMMIT → VerifyMetadataRoundTripPostCommit → MEASURE → DELTA → HALT
On regression: status=halted-on-regression-POST-commit, NO rollback,
live tree already mutated.
After (Option A, this commit):
REDUCE → MEASURE (against cp.StagingDir) → DELTA → HALT (with Rollback)
→ COMMIT → VerifyMetadataRoundTripPostCommit
On strict-mode regression/plateau: cp.Rollback() discards staging,
status=halted-on-regression-PRE-commit, live tree untouched.
## Why the original 395 LOC estimate was inflated
Prior session deferred M8 as a ~395 LOC architectural change requiring
dedicated --complexity=full --mixed council. This session's pre-flight
council validation (3-judge --tdd mode) discovered that the staging
infrastructure already existed in the codebase:
* cp.StagingDir is a full mirror of .agents/ subpaths
(checkpoint.go:194-223)
* REDUCE already writes into cp.StagingDir (reduce.go:186)
* cp.Rollback() is safe at any state (checkpoint.go:345)
* cp.StagingDir/.agents/ is a valid cwd for corpus.Compute — no
signature change needed
The actual fix was a sequencing bug, not missing infrastructure.
Real size: ~300 LOC (code + tests + docs). Real re-plumbing: 1 existing
test (TestRunLoop_RegressionHaltStrict status assertion), well under
the pre-agreed 5-broken-tests abort gate.
## Files
cli/internal/overnight/types.go
+ StatusHaltedOnRegressionPreCommit (new enum value)
+ Validate() + IsCorpusCompounded() switches updated
+ StatusHaltedOnRegressionPostCommit kept for backward compat with
persisted pre-M8 iterations
cli/internal/overnight/loop.go
- Removed old COMMIT block at former loop.go:332-348
- Removed old post-commit metadata check at former 350-360
- Added new MEASURE block at former position, pointing RunMeasure at
cp.StagingDir via a local RunLoopOptions copy
- Added cp.Rollback() to the measure-error branch
- Added cp.Rollback() + StatusHaltedOnRegressionPreCommit to the strict
regression halt branch (and removed writeCommittedButFlaggedMarker,
which was post-commit-specific)
- Added cp.Rollback() + StatusHaltedOnRegressionPreCommit to the strict
plateau halt branch
- Inserted new COMMIT block + post-commit metadata check AFTER the
warn-only rescue path, before the per-iter persist+append
- Warn-only rescue path itself unchanged (tolerated regressions still
commit; that's the whole point of warn-only)
cli/internal/overnight/loop_fitness_injection_test.go
+ TestM8_StrictRegression_HaltsPreCommit (T1 — the core wiring)
+ TestM8_StagingDiscardedOnPreCommitHalt (T2 — proves Rollback fired)
+ TestM8_HappyPath_CommitsNormally (T4 — pass-through not broken)
~ TestRunLoop_RegressionHaltStrict — status assertion updated to
StatusHaltedOnRegressionPreCommit
~ TestRunLoop_WarnOnlyBudgetExhausted — same update; budget-exhausted
fall-through to strict halt now uses PreCommit (consistency invariant)
docs/contracts/dream-run-contract.md
+ Iteration structure now documents 4 stages with Option A sequencing
+ Halt conditions table updated with new iter status values
+ Historical note explains the shift + why PostCommit status is kept
## Test results
* 4 new M8 tests pass
* 2 existing tests updated + pass
* Full overnight package green
* Full cli test suite green (go test ./...)
* Race detector clean (go test -race ./internal/overnight/...)
* go vet clean
* Scope gate: 1 broken existing test (< 5 abort threshold)
## Dream RunLoop Correctness epic status
M1-M7 + M8 + M9 all landed. Epic complete. M9 ratchet upgrade (warn→fail)
still gated on 1-2 clean post-679552ae main runs; na-h61 was the last
deferred item.
Closes: na-h61
Refs: .agents/council/2026-04-11-m8-assumption-validation-consolidated.md
.agents/council/2026-04-11-m8-assumption-validation-judge{1,2}.md
The legacy "rolled-back" string at loop.go carried two fundamentally
different semantics at two producer sites:
loop.go REDUCE pre-commit failure — corpus NOT on disk
loop.go post-commit regression halt — corpus IS on disk
The second was a LIE: the label claimed rollback while cp.Commit()
had already compounded the corpus into the live tree. Operators
reading the morning report saw "rolled-back" and assumed no-op,
when in fact the mutation was permanent.
Fix: introduce a 5-value IterationStatus enum in types.go with
StatusRolledBackPreCommit and StatusHaltedOnRegressionPostCommit
as distinct constants. Update both producer sites. Add a
committed-but-flagged marker file in iteration_store.go that
operators can find via directory listing. Fix the Micro-epic 2
rehydration logic to use IsCorpusCompounded as the baseline
predicate (closing the known-limitation documented at
.agents/council/2026-04-10-pre-mortem-microepic-2-cycle-history.md
#pm-20260410-m2-005).
Ship the Status Precedence Truth Table in docs/contracts/dream-report.md
so the enum semantics are documented, not tribal.
Touches:
- cli/internal/overnight/types.go (IterationStatus enum + Validate + IsCorpusCompounded)
- cli/internal/overnight/loop.go (rename + rehydration predicate update + other status literals)
- cli/internal/overnight/iteration_store.go (marker helpers)
- cli/internal/overnight/overnight_e2e_test.go (predicate update)
- cli/cmd/ao/overnight.go (explicit string() cast at the Steps boundary)
- docs/contracts/dream-report.md (enum + truth table + historical note)
- Test additions: 4 L1 enum + 4 L1 marker + 3 L2 rehydration/hash invariant
The TestRunLoop_LiveTreeHashInvariant test lands the StatusDone case
only; follow-up fixture engineering for the other 4 status values is
tracked in bd issue na-1iv.
Plan: .agents/plans/2026-04-10-microepic-3-status-enum.md
Pre-mortem: .agents/council/2026-04-10-pre-mortem-microepic-3-status-enum.md
Closes known-limitation from .agents/council/2026-04-10-pre-mortem-microepic-2-cycle-history.md
Writes each Dream iteration to <outputDir>/<runID>/iterations/iter-N.json
via atomic CreateTemp -> Sync -> Rename -> fsyncDir, and rehydrates prior
iterations at RunLoop startup so a crashed or MEASURE-failed run resumes
with full history and a correct prevSnapshot baseline.
Fixes the 2026-02-22 evolve-overnight failure mode where a crashed run
silently lost iteration history and restarted from a fresh baseline.
Also fixes the pre-existing IterationID contract drift at loop.go:145:
the documented format at types.go:10 is "<run-id>-iter-<N>" but the
runtime generated just "iter-N". Now matches the documented contract.
Touches:
- cli/internal/overnight/iteration_store{.go,_test.go} (new)
- cli/internal/overnight/loop_testhooks.go (new; test-only fault hook)
- cli/internal/overnight/loop_resume_test.go (new; L2 resume + ID regression)
- cli/internal/overnight/loop.go (persist + rehydrate + ID fix + plateau replay)
- cli/internal/overnight/types.go (add required RunID field)
- cli/internal/overnight/{stages,boundary,overnight_e2e}_test.go (set RunID)
- cli/cmd/ao/overnight.go (wire summary.RunID into RunLoopOptions)
- docs/contracts/dream-report.md, docs/contracts/dream-run-contract.md
- skills/dream/SKILL.md, skills-codex/dream/SKILL.md (+ regen codex hashes)
Prevents direct recurrence of the 115-cycle runaway from 2026-02-22.
Plan: .agents/plans/2026-04-10-microepic-2-cycle-history.md
Pre-mortem: .agents/council/2026-04-10-pre-mortem-microepic-2-cycle-history.md
Dream nightly compounder plan rev 2, Wave 5 (Issues 11, 12, 13)
executed by two parallel workers.
Issue 11 — L2 e2e tests + 150+ learning fixture + frozen v1 reader:
- NEW cli/internal/overnight/fixture/gen_fixture.go: deterministic
fixture generator producing 150 learnings + 20 findings + 5
patterns + 3 knowledge files with realistic metadata distribution
(maturity mix 0.50/0.30/0.15/0.05, source_bead on 60%, utility
0.1-0.9, mtime spanning 180 days). Parked at fixture/ not
testdata/ because Go excludes testdata/ from package resolution.
Two non-obvious tunings: pseudo-random hex bodies avoid dedup
trigram overlap, and pattern[0] embeds all learning filenames to
avoid orphan pruning during REDUCE.
- NEW cli/internal/overnight/overnight_e2e_test.go: three L2 tests
driving INGEST + REDUCE + MEASURE against the full 150-learning
fixture. TestRunLoop_L2_FullIteration_CorpusQualityMoves asserts
catalog build, checkpoint, stage-order, metadata round-trip,
findings routed, next-work.jsonl written, and fitness vector
populated. TestRunLoop_L2_MetadataStripDetected exercises the
pm-005 regression at L2 scale with checkpoint rollback.
TestRunLoop_L2_CompoundFilterCliff_DoesNotSilentlyKillCorpus is
the pm-015 guard: asserts no corpus-quality metric drops by more
than 0.30 between iterations (the "cliff" threshold from
2026-04-02-flywheel-quality-fixes).
- NEW cli/cmd/ao/testdata/v1_reader/summary_v1.go: frozen v1
reader struct snapshot of overnightSummary at 2026-04-09 HEAD.
Only struct definitions, no methods, to prevent drift.
- EXTENDED cli/cmd/ao/overnight_test.go: added
TestRunOvernight_SchemaV2IsV1BackwardCompatible (pm-008 fix).
Constructs a minimal v2 summary, marshals it, unmarshals into
the frozen v1 reader, and asserts every v1 field is populated.
Previous tests untouched.
Issue 12 — Contract v2 bumps:
- docs/contracts/dream-run-contract.md: new v2 iteration-loop
section. Documents INGEST -> REDUCE -> MEASURE, the 5
checkpointed subpaths, 5 halt conditions, 5 anti-goals, 6 new
flags, startup recovery protocol, and the pm-011 concurrency
guard. V1 content + Wave 2's "Retrieval-bench determinism"
subsection preserved.
- docs/contracts/dream-report.md: Schema v2 section documenting
the 4 new top-level fields (iterations, fitness_delta,
plateau_reason, regression_reason) and the IterationSummary
shape (14 fields). Explicit backward-compat guarantee
referencing TestRunOvernight_SchemaV2IsV1BackwardCompatible.
Issue 13 — Skill docs:
- skills/dream/SKILL.md: added Compounding Loop (v2) section with
anti-goals, 3 new /dream start examples, iteration sub-summary
bullet in Output, Delineation vs /evolve table. 207/250 line
budget.
- skills/harvest/SKILL.md: nightly-usage blockquote pointing at
/dream start as the primary nightly driver and noting the
.agents/overnight/run.lock refusal during Dream runs.
- skills/evolve/SKILL.md: Delineation vs /dream section
(identical verbatim table to dream/SKILL.md — must be kept in
sync). Pointer added in See Also.
Verification:
- go build ./... OK
- go vet ./... OK
- go test ./internal/overnight/... all green (e2e + unit)
- go test ./cmd/ao/ all green (incl. schema v2 backward-compat)
- heal.sh --strict clean
- check-contract-compatibility.sh 0 failures / 0 warnings
Follow-up flagged (not blocking): skills-codex/ parity for dream/
harvest/evolve needs a pass of scripts/audit-codex-parity.sh +
regen-codex-hashes.sh to propagate the markdown changes.
Refs: plan Issues 11/12/13, pre-mortem pm-008/011/012/015.
Dream nightly compounder (plan rev 2). Lands Wave 1 skeleton and
Wave 2 parallel components per the file-conflict matrix.
Wave 1 — cli/internal/overnight/ skeleton:
- doc.go with package contract + anti-goals (no code mutation, no
/rpi, no git ops, no symlinks, no swarm)
- types.go with RunLoopOptions and normalize() defaults (2h budget,
6h max, K=2 plateau window, 0.05 regression floor, 512MB checkpoint
cap, 12h stale-lock threshold)
- loop.go with public RunLoop surface (stub for Wave 3 stage drivers)
Wave 2 — independent components (zero file overlap, 6 workers):
- checkpoint.go: two-phase-commit staging overlay with marker-file
crash-recovery protocol. VerifyMetadataRoundTrip computes set-diff
over ALL frontmatter keys (pm-005 fix — no hardcoded allowlist)
- fitness.go / plateau.go: FitnessSnapshot.Delta with per-metric
floors; PlateauState with K=2 minimum (pm-FEAS-08) and noisy-sample
absorption
- findings_router.go: scans .agents/findings/f-*.md, dedups against
next-work.jsonl by finding ID, regex-gates registry.json and
README.md (pm-MISS-06 fix)
- queue.go: evolve pinned-queue format parser
- cli/internal/lifecycle/close_loop.go: extracted from
cli/cmd/ao/flywheel_close_loop.go (pm-001 fix — the original plan
mis-identified feedback_loop.go as a close-loop stub;
feedback_loop.go is untouched). Dependency-injected ExecuteCloseLoop
lets Dream's REDUCE call close-loop in-process. cmd/ao adapter
preserves byte-for-byte stdout compatibility.
- cli/internal/corpus/: new package computing FitnessVector from the
local corpus. Dedicated cli/cmd/ao/corpus.go CLI (pm-002 fix —
corpus-quality stays OUT of the goals Directive subsystem).
- retrieval_bench.go + dream-run-contract.md: documented existing
determinism (pm-012 fix — no --seed flag added, would be dead work).
Tests: 58 new tests across internal/overnight, internal/corpus,
and internal/lifecycle, all L1 unit tests per AI-native test shape.
All passing. 50+ pre-existing close-loop-adjacent cmd/ao tests
preserved unmodified.
Build: go build ./... OK, go vet ./... OK, all three new package
test suites green.
Refs: .agents/plans/2026-04-09-dream-nightly-compounder.md (rev 2),
.agents/council/2026-04-09-pre-mortem-dream-nightly-compounder.md
(attempt 1 FAIL → 15 findings patched → attempt 2 WARN/PROCEED).
Boden Fuller