Bo
2207c5b278
> **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).
4.4 KiB
Optional Learning Loop
Status: design, not implementation. The schemas and the contract on this page exist on disk. The reducer they describe does not. Read this page as a declared shape for a loop that may be built, never as a description of something running.
AgentOps core ends when Validate returns a fresh judgment and RPI reports it. Learning and durable verdict storage are deliberately off the critical path.
What is implemented
One thing: the learn
skill, an optional, caller-invoked consumer of durable verdict.v2
collections. It is a skill — prose an agent follows — with no CLI command and
no scheduled or automatic invocation behind it.
Invoked, learn summarizes recurring evidence across a caller-supplied verdict
collection and may propose a candidate deterministic check for later human or
caller evaluation. Its own contract bounds the output hard:
When the caller asks for a durable artifact, write the observations under
.agents/scratch/learn/and return the path; otherwise return them inline. The write is advisory and TTL'd — it is never a source of record, and its absence never changes whether a candidate is valid.
.agents/scratch/ is disposable state by ADR-0016:
rebuildable or expirable, never authority. So the implemented half of this loop
reads durable evidence and writes only to a tier that nothing is allowed to
trust.
learn does not:
- change a completed verdict;
- repair or re-plan work;
- choose a next invocation;
- activate a rule or deterministic check;
- mutate Git, a tracker, or delivery state; or
- block RPI when its own storage or analysis is unavailable.
What is designed but not built
The reduction from repeated Validate findings to an advisory producer-rule candidate — group finding observations by defect class, count distinct objectives, emit one candidate per recurring class. That reduction is specified in the producer-defect recurrence contract and typed by three schemas:
| Schema | Declares | Consumers |
|---|---|---|
schemas/finding-observation.v1.schema.json |
one evidence-backed finding observation | none |
schemas/producer-rule-candidate.v1.schema.json |
one advisory producer-rule candidate | none |
schemas/learning.v1.schema.json |
a learning record | none |
"None" is literal. A search across cli/ and scripts/ finds no code that
reads, writes, or validates against any of the three; the only non-schema hits
in the repository are scripts/insert-schema-practices.py (which tags every
schema's practices field and knows nothing about their content), the two
contract pages, and dated audit records. No SKILL.md — learn included —
cites them either, so nothing instructs an agent to emit these shapes by hand.
The schemas stay on disk deliberately: they are the declared contract if the loop is ever built. They are not evidence that it was.
Why the write half is gone
The compounding claim it was meant to serve was never proven, and the machinery was cut rather than kept as a green-looking shell:
- ADR-0004 — the corpus moat is unproven; do not position on it.
- ADR-0011 — escape-corpus compounding is structurally data-starved: a competent membrane catches at review, so escapes are rare by construction.
- ADR-0014 — the catch-to-producer route, superseded by the Cathedral Cut. Its commands, automatic routing, receipts, and producer-side mutation are not active product behavior.
- ADR-0016 — one authority per claim; projections and scratch are never authoritative.
ao flywheel and the whole knowledge-compounding command family were removed
with that cut; see MIGRATION.md for the per-verb replacements.
If you want the loop
Promotion from an observed pattern into a skill, test, or repository rule is a separate caller-authorized change with its own Plan, Implement, and Validate cycle. That is the currently supported path, and it is a human-driven one. It preserves the useful compounding idea without making bookkeeping a condition for finishing ordinary work — and without a metric that reports compounding nobody measured.