First public release, published as one snapshot. What changed between versions is in CHANGELOG.md. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
134 lines
9.6 KiB
Markdown
134 lines
9.6 KiB
Markdown
# Repair gate
|
|
|
|
`repair_gate.py` is the judge of the repair command (`python3 -m okfwiki.krepair`, order 34, contracts K18 and K19).
|
|
It was written and run RED before the command existed (order 34, session A). It calls no model.
|
|
|
|
```
|
|
python3 gates/repair_gate.py --manifest gates/repair.manifest.json -- python3 -m okfwiki.krepair
|
|
```
|
|
|
|
The command after `--` is the program each case's arguments are appended to; it runs from the repository root.
|
|
Exit 0 GREEN (every case passed), 1 RED, 2 the gate could not run.
|
|
|
|
## What it builds
|
|
|
|
The gate builds its own collection from the fixtures in `gates/repair/`, with the frozen tools only: `kblocks order`
|
|
and `blocks`, `kpack skeleton`, `pack` and `accept` (two packs of three sources), `kassemble build --at
|
|
2026-01-01T00:00:00Z`, `klink accept` and `kassemble build --links`. No generated page is in git.
|
|
|
|
- `kilder/`: a K1 source root made by `okfwiki.sources freeze` from text written for the gate about beekeeping: three
|
|
docs pages (`docs-en-hive.md`, `docs-en-honey.md`, `docs-en-swarm.md`) and one release note
|
|
(`release-v2.1.0.md`). Nothing in it comes from any documentation (CLAUDE.md rule 3).
|
|
- `fragments/pack-1.json`, `pack-2.json`: the compiler's output for the two packs, written by hand: 19 fragments,
|
|
three main pages and five homes.
|
|
- `links.json`: the five links of the base, by page, sentence text, anchor and target.
|
|
- `agent.md`, `agent-shared.md`: the agent files the task cases give `--agent`; the second shares a run of eleven words
|
|
with a line of a source.
|
|
- `stubs/`: three commands that must each turn the gate RED (below).
|
|
|
|
The base has eight pages (`hive`, `frames`, `brood`, `smoker`, `water`, `honey-harvest`, `swarming`,
|
|
`queen-cells`), 20 claims and five links, and must come out with no auditor finding and criterion 1 at 20 of 20, or
|
|
the gate cannot run. It holds what the cases need: a fragment of two sentences, a merged fragment, two fragments with
|
|
context quotes, history from the release note, two fragments in two concepts that share one footnote, two equal
|
|
sentences on one page (the second linked), a page with one fragment and a link to it, a main page with one fragment
|
|
and a page whose home it is, and a main page that stands on history alone once its own source's fragment goes.
|
|
|
|
## What it measures
|
|
|
|
Every case runs in a fresh copy of the base. For each case, by the gate's own code and apart from the command's
|
|
report:
|
|
|
|
1. **Exit code and refusal codes.** Each step's exit code is the case's (0 done, 1 refused). The codes are read from
|
|
the lines `refused: <code> <claim or record>` on stdout or stderr; the set must be the case's, and a line that names
|
|
no claim or record fails. The codes are listed with their meaning in the manifest's `refusal_codes`.
|
|
2. **The pages.** A case that writes is built with `kassemble build --links --replace --at 2026-01-02T00:00:00Z`; the
|
|
concept pages whose bytes differ from the base (`index.md` and `log.md` left out; a page gone counts) must be
|
|
exactly the case's `pages_changed`, and the pages gone exactly its `pages_gone`.
|
|
3. **The claims.** The frozen `claims.extract` runs on both collections. The (id, `excerpt_sha256`) pairs that are
|
|
gone and those that are new must be, by id, exactly the claims the case names in `claims_before` and
|
|
`claims_after`; so every other claim keeps its id and its `excerpt_sha256`. Where a case gives `excerpts`, the
|
|
claim must show exactly those (file, line) excerpts in that order.
|
|
4. **The auditor and criterion 1.** The frozen auditor's findings on the result, as (check, file), are exactly the
|
|
case's `findings` (most cases: none), and criterion 1 is N of N with no claim left without a key.
|
|
5. **The links.** The links file after the build holds exactly the base records, without the case's `links_removed`
|
|
and with its `links_added` (page, sentence key, anchor, target), and every record's `at` points at its anchor in its
|
|
sentence on the built page.
|
|
6. **The command's diff.** After a `fix`, the gate runs `diff --old <base> --new <result> --sources --repairs
|
|
WORK/K-work/repairs.json --out DIR`: exit 0, `ids.json` (`{"ids": [...]}`, the form `claims calls --ids` reads)
|
|
must hold exactly the new and changed claim ids the gate measured, and `sider.json` (`{"pages": [...]}`) exactly
|
|
the changed pages.
|
|
7. **Nothing written on a refusal.** A refused step changes no file in the work folder, the links file, the collection
|
|
or the output folder (sha256 of each tree before and after). `task` and `linkset` change none of the first three.
|
|
No case may change the sources or the copy of the old collection.
|
|
|
|
`task` cases: every `<task>.parts.json` in the output folder is `{"parts": [paths], "answer": path}`; every part
|
|
exists and is at most `kpack.PART_CHARS` characters; no two tasks share an answer path; each listed fragment's
|
|
footnote stands in exactly one task, and that task holds the page title, every sentence of the fragment, its quote,
|
|
its context quote and lines of its block that the case names.
|
|
|
|
`linkset` cases: the output folder holds `group-<n>.sentences.json` (the `okf-wiki/link-sentences/1` form `klink task
|
|
--sentences` reads) and `group-<n>.catalogue` (one id per line) per group; the frozen `klink task` runs on each pair;
|
|
the sentences of all groups are exactly the candidates; and each candidate's catalogue holds its current target.
|
|
|
|
## Where the denominator comes from
|
|
|
|
Every page, sentence, link and finding a case expects is written by hand in `repair.manifest.json` from the sources in
|
|
`gates/repair/kilder/`: pages by name, claims as sentence text with its occurrence `n` on the page (counted from 0, as
|
|
klink counts), links as page, sentence text, anchor and target. The gate turns a sentence into its claim id with the
|
|
frozen `klink.key_text` (the first 16 hex characters of its sha256, plus `-<n>`), and a fragment into its footnote with
|
|
the frozen `kassemble.label`, from its file, span, quote and mark. Nothing is taken from the command.
|
|
|
|
The findings of the three removal cases follow from K2 as written: a main-topic source no page lists in `x-main-for`
|
|
is `main-page-missing`, and a page that is not a main page and has no link from one is `no-main-page-link`. When the
|
|
main page `swarming` goes, its source has no main page and `queen-cells`, whose home it was, has no link from a main
|
|
page; when `honey-harvest` loses its only fragment from `docs-en-honey.md`, kassemble writes no `x-main-for` (a main
|
|
page record counts only for a source the page cites), so the source has no main page and the page is no main page and
|
|
has no home.
|
|
|
|
## The formats the gate fixes
|
|
|
|
The command did not exist when the gate was written, so the gate fixes what K18 leaves open, and the command follows
|
|
it:
|
|
|
|
- Answers (`okf-wiki/repair-answers/1`): `{"schema", "answers": [{"concept_id", "footnote": "s…", "action": "replace",
|
|
"fragments": [{"text", "quote", "anchor": {"file", "start", "end"}, "provenance", "context"?}]} | {"concept_id",
|
|
"footnote", "action": "remove"}]}`.
|
|
- A repair list in K17's schema, rendered from the base: each claim with its id, `excerpt_sha256`, page, line, mark,
|
|
kind (`docs` or `notes`), its excerpts as `sources` (`kilde/<file>`, line), origin `o33` and its reasons; each link
|
|
candidate with the base record's `at`, origin `o33-kandidat`. `claims_sha256` is the sha256 of the base's claim list
|
|
(`claims list` output, given as `--claims`); `verdicts_sha256` is the sha256 of no bytes.
|
|
- `<task>.parts.json`, `group-<n>.sentences.json` and `group-<n>.catalogue`, `ids.json` and `sider.json` as above.
|
|
- Command arguments: `--page` and `--to` are page files (`hive.md`), `--sentence` a sentence key.
|
|
|
|
## The cases
|
|
|
|
32 cases: 20 that write (replace one with one and with two, a two-sentence fragment, a merged fragment, a release-note
|
|
fragment, context kept and context replaced, remove one, remove the last on a page and on a main page, remove the last
|
|
from a source on its main page, a shared footnote, equal sentences, a repair that makes a sentence equal to a later
|
|
one, a link whose anchor stays and one whose anchor goes, unlink, relink, two repairs in one file, identity), one task,
|
|
one linkset, and ten refusals (a quote not verbatim beside a good answer, a quote from another source, an unknown key,
|
|
a collection built before the last repair, two answers for one fragment, a stale list, an agent file that shares eight
|
|
words, a relink to a page that does not exist, an unlink with the wrong `at` and with the wrong anchor). Each case says
|
|
in `what` what it tries.
|
|
|
|
## The stubs and the gate's own test
|
|
|
|
`gates/tests/test_repair_gate.py` shows that each stub turns the gate RED with no case passed: `noop.py` (does
|
|
nothing, exit 0), `refuse_all.py` (`refused: x`, exit 1, writes nothing) and `touch_generated.py` (gives every page a
|
|
new `generated.at`; the rebuild keeps it, so the identity case sees every page changed). It also shows that a changed,
|
|
missing or extra fixture stops the gate (exit 2), that a missing command and a missing module are RED, and it tries
|
|
the checks a command cannot be run against yet with handmade outputs (task, linkset, a refusal, a link command).
|
|
|
|
```
|
|
python3 -m unittest discover -s gates/tests -p 'test_repair_gate.py'
|
|
```
|
|
|
|
## Not measured
|
|
|
|
- The command's `diff` after `unlink` and `relink`: K18 gives them no work folder, so they write no repairs log, and
|
|
the gate checks their pages, claims and links but not a diff.
|
|
- `linkset`'s refusal of a stale list: K18 gives it no `--claims`; its cases give a list with the hash of the base's
|
|
claim list.
|
|
- A fragment whose block alone is over `kpack.PART_CHARS` (task exit 2), and the instructions' own eight-word check:
|
|
the command's unit tests try them.
|
|
- The repairs log's content: only through the command's `diff`.
|