docs(evals): bring the reference pages back, superseded parts only #306

Merged

coilysiren merged 1 commit from aos/claude/eval-refs-restore into main

2026-08-18 16:25:56 +00:00

coilyco-ops commented

2026-08-18 16:18:04 +00:00

Member

Fixes what #305 got wrong. I read "pick one page" as delete the rest. The three reference pages were a bibliography, not legacy eval prose, and only their defects needed superseding.

Restored with the defects fixed rather than the content dropped:

eval-ref-platforms.md carried ### Source and what it says and how it relates to this eval and source and what it says and how it relates to this eval, a run-on left by an earlier mechanical merge. Split into Source / What it says / How it relates, matching the Inspect section. RULERS gained the same three where it had none.
eval-references.md linked all six reference names at whole pages, so every one landed at the top of a page instead of its entry. They carry anchors now, and its See also no longer points at itself and at the merged-away pipeline page.
eval-ref-papers.md came back unchanged apart from reflow and a See also.

eval-pipeline.md stays merged, because that page really was superseded: its orchestration, dataset derivation, and export sections are evaluation.md now, and restoring it would put the duplication back. Four things it carried alone were dropped in #305 and come back here as prose in evaluation.md rather than as a page: the agent-compose.eval-export.v1 format name, the #213 round-trip argument, the deploy#572 target, and why evalkit-check runs from scripts/evalkit-check.sh rather than a pre-commit hook (that config is managed by agentic-os, so a hand-added hook is lost on sync). The recognized secret shapes come back too.

evaluation.md keeps a References section, now a pointer, so the two-of-each-kind framing and the convergence argument live on the index page that owns them. It stays the one page about the evals.

Docs count 36 to 39, under the 40 cap. pre-commit run --all-files passes.

🤖 Generated with Claude Code

Fixes what #305 got wrong. I read "pick one page" as delete the rest. The three reference pages were a bibliography, not legacy eval prose, and only their defects needed superseding. **Restored with the defects fixed rather than the content dropped:** * `eval-ref-platforms.md` carried `### Source and what it says and how it relates to this eval and source and what it says and how it relates to this eval`, a run-on left by an earlier mechanical merge. Split into Source / What it says / How it relates, matching the Inspect section. RULERS gained the same three where it had none. * `eval-references.md` linked all six reference names at whole pages, so every one landed at the top of a page instead of its entry. They carry anchors now, and its See also no longer points at itself and at the merged-away pipeline page. * `eval-ref-papers.md` came back unchanged apart from reflow and a See also. **`eval-pipeline.md` stays merged**, because that page really was superseded: its orchestration, dataset derivation, and export sections are `evaluation.md` now, and restoring it would put the duplication back. Four things it carried alone were dropped in #305 and come back here as prose in `evaluation.md` rather than as a page: the `agent-compose.eval-export.v1` format name, the #213 round-trip argument, the deploy#572 target, and why `evalkit-check` runs from `scripts/evalkit-check.sh` rather than a pre-commit hook (that config is managed by agentic-os, so a hand-added hook is lost on sync). The recognized secret shapes come back too. `evaluation.md` keeps a References section, now a pointer, so the two-of-each-kind framing and the convergence argument live on the index page that owns them. It stays the one page about the evals. Docs count 36 to 39, under the 40 cap. `pre-commit run --all-files` passes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

coilyco-ops added 1 commit

2026-08-18 16:18:04 +00:00

docs(evals): bring the reference pages back, superseded parts only

ci / test (pull_request) Successful in 52s

Details

8e71c55ddd

#305 read "pick one page" as delete the rest, and that was wrong. The three
reference pages were a bibliography, not legacy eval prose, and only their
defects needed superseding.

Restores eval-references.md, eval-ref-papers.md, and eval-ref-platforms.md with
the defects fixed rather than the content dropped:

* eval-ref-platforms.md carried `### Source and what it says and how it relates
  to this eval and source and what it says and how it relates to this eval`, a
  run-on from an earlier mechanical merge. Split into Source / What it says /
  How it relates, matching the Inspect section, and RULERS gained the same three
  where it had none.
* eval-references.md linked six reference names at whole pages, so every one
  landed at the top. They now carry anchors, and its See also no longer points
  at itself and at the merged-away pipeline page.

eval-pipeline.md stays merged, because that page really was superseded: its
orchestration, dataset derivation, and export sections are evaluation.md now.
Four things it carried alone were dropped in #305 and come back here rather
than as a page: the export payload format name, the #213 round-trip argument,
the deploy#572 target, and why evalkit-check runs from a script rather than a
pre-commit hook. The recognized secret shapes come back too.

evaluation.md keeps its own References section as a pointer, so the framing and
the convergence argument live on the index page that owns them.

Docs count 36 to 39, under the 40 cap.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-18 16:18:04 +00:00