From 53e3527e0bc6ea9a67bf4d975e75673bc9df536b Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Wed, 9 Sep 2026 20:41:51 +0200 Subject: [PATCH] docs: docs toc im Fehlerkontrakt, docs-verify-Zeile nennt die TOC-Pruefung, --major-Kriterium in tools/README.md korrigiert Files changed: - CHANGES.md - VERSION - tools/CONTRACT.md - tools/README.md --- CHANGES.md | 13 ++++++++++++- VERSION | 2 +- tools/CONTRACT.md | 5 +++-- tools/README.md | 10 ++++++++-- 4 files changed, 24 insertions(+), 6 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index c408e58..582dac7 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -35,7 +35,7 @@ dev-checkout concern - readable here, never shipped as something to parse. --- -## 5.0.0-beta.1 - 2026-09-09 - TOC-Pflicht fuer Referenzdateien ueber 100 Zeilen; session-setup.md/gates.md nennen die tatsaechliche Budget-Ausnahmeliste (schliesst #73, #76) +## 5.0.0-beta.2 - 2026-09-09 - tools/CONTRACT.md: docs toc im Fehlerkontrakt, docs-verify-Zeile nennt die TOC-Pruefung; tools/README.md korrigiert das --major-Kriterium **Author:** Torben Nehmer @@ -54,6 +54,7 @@ dev-checkout concern - readable here, never shipped as something to parse. - SKILL.md-Sanierung: Checklisten, Kommandolisten, wiki-status-Hard-Rule, wiki-query-Filingpruefung (#70, #74, #75, #78) - Ausgelieferte Doku zitiert keine Issue-Nummern mehr, docs verify prueft es (schliesst #77) - TOC-Pflicht fuer Referenzdateien ueber 100 Zeilen; session-setup.md/gates.md nennen die tatsaechliche Budget-Ausnahmeliste (schliesst #73, #76) +- tools/CONTRACT.md: docs toc im Fehlerkontrakt, docs-verify-Zeile nennt die TOC-Pruefung; tools/README.md korrigiert das --major-Kriterium **Migration:** none required - Betrifft nur AGENTS.md, die Stage-/Collection-Contracts und instructions/; kb/-Inhalt bleibt unberuehrt, keine Migration noetig. @@ -916,6 +917,16 @@ zählt wie jedes mutierende Kommando. Beide Dateien verweisen jetzt auf die List in `tools/CONTRACT.md`, statt sie mit einer falschen Faustregel zu umschreiben. Kein Versionsbezug — reine Prosa-Korrektur, im selben Bump mitgeführt. +Nachgezogen in `-beta.2`, weil `docs verify` die eigene Dokumentationstreue nur +für die *Existenz* einer Kommandozeile prüft, nicht für deren Inhalt: die +`docs verify`-Zeile in `tools/CONTRACT.md` nennt jetzt die TOC-Prüfung, die +Fehlerkontrakt-Tabelle bekommt die fehlende `docs toc`-Zeile (Schritt 3 in +`tools/README.md` § Adding a command verlangt beide Tabellen, geprüft wird nur +eine), und `tools/README.md` § Adding a command Schritt 5 nannte als +`--major`-Kriterium „wenn bestehender Inhalt migriert werden muss" — was +`instructions/dev/version-parts.md` ausdrücklich verneint und was dieser Bump +selbst widerlegt: grenzüberschreitend mit `--no-migration`. + Schließt #73, #76. --- diff --git a/VERSION b/VERSION index 9e25fc0..1ece2a2 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -5.0.0-beta.1 +5.0.0-beta.2 diff --git a/tools/CONTRACT.md b/tools/CONTRACT.md index 7889962..6da9e41 100644 --- a/tools/CONTRACT.md +++ b/tools/CONTRACT.md @@ -84,7 +84,7 @@ tools/wikitool --help | `instructions sync [--force]` | Publish every `instructions//SKILL.md` into `.agents/skills/` and `.claude/skills/` as **copies**, and delete published skills whose source is gone. Both targets are gitignored, so a fresh clone runs this once - see `instructions/bootstrap.md`. Re-running is also how a drifted copy is repaired: the source always wins. `--force` is required only to replace a target directory that is not a published skill at all (no `SKILL.md` in it) | | `instructions verify` | Check the instruction layer: flat instructions validate against `types/instruction.schema.yaml`, each `SKILL.md` carries the frontmatter its harness reads, every published copy is byte-identical to its source, no instruction is left that nothing references, and nothing under `instructions/dev/` is referenced from outside it (a `` block is exempt - see [instructions/CONTRACT.md](../instructions/CONTRACT.md)). Missing *every* copy is reported as "run sync", not as drift - that is a clean checkout | | `instructions list [--json]` | List the flat instructions with their descriptions. This is how the layer is discovered; `search` deliberately covers `kb/` only | -| `docs verify` | Check the docs that mirror the code: every CLI command documented here (and vice versa), every directory under `kb/` has a `COLLECTION.md` and no directory outside it does, every collection declaring `profile:` and a `required_by_stack:` that agrees with the stack's own list, `kb/CONVENTIONS.md` naming all three tool-owned section headings if it exists at all, every stage contract present, no pre-migration `type: entity` blocks left in the contracts, the `.gitignore` canaries clear in both directions (nothing ignored under `raw/`/`kb/`, `incoming/` ignored, everything ignored under `reports/` and the published skill directories), and no `.md`/`.template` file `dist export` would ship citing an issue number - the tracker exists only in the origin repo, so such a number in a distributed instance is a reference its reader can neither resolve nor recognise as unresolvable (a `` region is exempt: it is already gone from the text the check reads, which is the export plan's, not the working tree's). The name is about documentation parity, not about the `docs/` directory - it neither reads nor requires one, the same way `kb/` predates the collection it now checks | +| `docs verify` | Check the docs that mirror the code: every CLI command documented here (and vice versa), every directory under `kb/` has a `COLLECTION.md` and no directory outside it does, every collection declaring `profile:` and a `required_by_stack:` that agrees with the stack's own list, `kb/CONVENTIONS.md` naming all three tool-owned section headings if it exists at all, every stage contract present, no pre-migration `type: entity` blocks left in the contracts, the `.gitignore` canaries clear in both directions (nothing ignored under `raw/`/`kb/`, `incoming/` ignored, everything ignored under `reports/` and the published skill directories), and no `.md`/`.template` file `dist export` would ship citing an issue number - the tracker exists only in the origin repo, so such a number in a distributed instance is a reference its reader can neither resolve nor recognise as unresolvable (a `` region is exempt: it is already gone from the text the check reads, which is the export plan's, not the working tree's), and every reference file `docs toc` covers carrying the current table-of-contents region for its own headings - missing and stale are one check, because the generator is idempotent. The name is about documentation parity, not about the `docs/` directory - it neither reads nor requires one, the same way `kb/` predates the collection it now checks | | `docs toc [--apply]` | Create, refresh or remove the generated table-of-contents region (`` ... ``, placed after the title and before the first `##`) on every reference file over 100 lines that `AGENTS.md`, a stage/collection contract, or the flat `instructions/**.md` form covers - the scope Anthropic's skill-authoring guidance names for a file previewed rather than read in full. Dry-run by default (prints which files would change); `--apply` writes. `docs verify` checks the result stays current the same way it checks every other generated-from-code copy | | `eval sessions [--json]` | List the sessions that have a trace under `reports/telemetry/`, most recent first. Read-only and exempt from the Iteration Budget Gate | | `eval score [--session ] [--json] [--markdown out.md] [--save] [--fail-on-error]` | Score one traced session: structural state from `lint`'s own checks (L1) plus trajectory rules over the trace (L2) - was a refused call repeated unchanged, was a gate flag passed without that gate having refused anything, did a publish of `kb/` pages go unlogged. Defaults to the current session. `--save` writes `reports/evals//.{json,md}`. Read-only over `kb/` and exempt from the budget; see [../EVALS.md](../EVALS.md) | @@ -214,7 +214,8 @@ is atomic, and whether a retry is safe. | `raw accept --replaces` | More than one incoming file, `--page` also given, the incoming filename differs from the target's, the target does not lie under `raw/` or does not exist, the incoming file sits under a different type directory than the target, or the target has more than one owning source page | No - one `unlink()` + one `rename()`, no page write | Fix the named argument and retry once. Every check runs before the filesystem is touched, so a refusal leaves both files exactly as they were | | `types list` / `types describe` | Unknown type name | Read-only | Fix the name and retry | | `instructions sync` / `verify` / `list` | Nothing found under `instructions/`, a malformed instruction or `SKILL.md`, a published copy that drifted from its source, an instruction nothing references (or, for `manual: true`, one that IS linked from AGENTS.md or a skill and so risks running implicitly), something under `instructions/dev/` referenced from outside it and outside a dist:strip block, or (sync) a target directory that is not a published skill and `--force` was not passed | `sync` rewrites one directory per target (idempotent); `verify`/`list` are read-only | Fix the flagged file, then re-run. For drift, re-run `sync`: the source under `instructions/` always wins, and a published copy is never edited directly | -| `docs verify` | A command, contract, or type-form mismatch was found, or a shipped `.md`/`.template` cites an issue number | Read-only | Fix the documentation it names, then re-run. For an issue reference: say what was decided instead of pointing at where, or move the pointer behind a `` block | +| `docs verify` | A command, contract, or type-form mismatch was found, a shipped `.md`/`.template` cites an issue number, or a reference file's table-of-contents region is missing or stale | Read-only | Fix the documentation it names, then re-run. For an issue reference: say what was decided instead of pointing at where, or move the pointer behind a `` block. For a table of contents: run `docs toc --apply` - never hand-write the region | +| `docs toc` | Never fails on content: a file with no `##` heading, or one at or under the threshold, is simply left without a region | `--apply` rewrites each named file in place, one at a time and idempotently, so a re-run after an interruption converges rather than doubling a region; the dry-run form is read-only | Nothing to fix - re-run with `--apply` to write what the dry run listed. If `docs verify` still reports a stale region afterwards, the file's `##` headings changed in between; run it again | | `dist export` | Target exists and is not empty, is not a directory, or the tree has no readable `VERSION` | Yes - nothing is written until every file is planned | Point `` at an empty (or new) directory and retry. Never merge into a non-empty one by hand | | `dist upgrade` | Missing local `VERSION`/`.wikitool-release.json`(`files`)/`.wikitool-kb.json`, a migration already outstanding against the installed machinery, a dirty working tree, a source with no `VERSION`/stamp/`files` block, a source version that is older than, equal to, or (without `--pre`) a pre-release relative to the installed one, or one or more locally changed files without `--keep-local` | **Yes for the refusal cases above - nothing is written.** Once writing starts it is a plain sequential file copy with no partial-state cleanup: an interruption mid-copy (killed process, disk full) can leave the tree part-old, part-new | For every refusal above: fix the named precondition and retry - none of them are transient. For locally changed files: reconcile them by hand and retry, or re-run with `--keep-local` to proceed and leave them untouched (repeatable - it reports the same files again on every subsequent run until they stop diverging). An interrupted write is not resumed automatically; compare the tree against the printed classification and finish or revert by hand | | `version show` / `version notes` | `VERSION` is missing or unparseable; for `notes`, no `CHANGES.md` entry names the version asked for | Read-only | Fix `VERSION`, or write the changelog entry (`version bump` writes its heading). Safe to retry | diff --git a/tools/README.md b/tools/README.md index 0780913..ce3ed0c 100644 --- a/tools/README.md +++ b/tools/README.md @@ -89,8 +89,14 @@ bound at import time - `KB_DIR` and friends follow whatever `ROOT` currently is. does not need a CLI runner - and a Typer callback called directly from a test receives `OptionInfo` objects, not values, for any argument the test omits. 5. Raise the version: `wikitool version bump --minor --title "..."` for a new - command (`--patch` for a fix, `--major` when existing content has to be - migrated, which then also needs a document under `instructions/migrations/`). + command (`--patch` for a fix, `--major` when the new version is **not a + drop-in replacement** - a renamed flag or artefact, a stricter check that + newly fails on content an instance already had, anything needing hand-work + after the copy). Content migration is one way to land there, not the + definition of it: a `--major` may well ship `--no-migration`, and one that + does migrate also needs a document under `instructions/migrations/`. The + full test is `instructions/dev/version-parts.md` - read it before choosing + `--major`. A new command reaches every future instance, and CI's version gate refuses a stack change that moved no version.