stack: TOC-Pflicht fuer Referenzdateien ueber 100 Zeilen (docs toc); session-setup.md/gates.md nennen die tatsaechliche Budget-Ausnahmeliste (schliesst #73, #76)

Files changed: - AGENTS.md - CHANGES.md - VERSION - instructions/CONTRACT.md - instructions/capture-session.md - instructions/claude-code-model-selection.md - instructions/dev/issue-tracking.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - instructions/evolve-subtypes.md - instructions/gates.md - instructions/german-terminology.md - instructions/ingest-large-tree.md - instructions/kb-profiles.md - instructions/link-taxonomy.md - instructions/mcp-read-server.md - instructions/migrate-corpus.md - instructions/migrations/3.0.0-authoring-conventions.md - instructions/migrations/4.0.0-link-taxonomy.md - instructions/private-instance.md - instructions/session-setup.md - instructions/setup-instance.md - kb/CONTRACT.md - kb/CONVENTIONS.md - kb/concepts/COLLECTION.md - raw/CONTRACT.md - tools/CONTRACT.md - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/instructions_cmd.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_instructions_cmd.py - tools/chemenu/tests/test_toc.py - tools/chemenu/toc.py - types/type-spec.md
2026-09-09 20:38:42 +02:00
parent a51d7a322f
commit 2c4c2b1c7c
34 changed files with 929 additions and 15 deletions
@@ -8,6 +8,19 @@ using these commands is mandatory; this file is the full reference. Changes to
 `wikitool` itself are tracked in the repo root [`CHANGES.md`](../CHANGES.md),
 not here.

+<!-- wikitool:toc -->
+## Contents
+
+- [Setup (one time)](#setup-one-time)
+- [Usage](#usage)
+- [Commands](#commands)
+- [Design notes](#design-notes)
+- [Tests](#tests)
+- [Error contracts](#error-contracts)
+- [Maintenance schedule](#maintenance-schedule)
+- [Future considerations (not implemented)](#future-considerations-not-implemented)
+<!-- /wikitool:toc -->
+
 ## Setup (one time)

 Full bootstrap for a fresh clone - including publishing the skills, which are not
@@ -72,6 +85,7 @@ tools/wikitool <command> --help
 | `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 `<!-- dist:strip-start/end -->` 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 `<!-- dist:strip-start/end -->` 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 toc [--apply]` | Create, refresh or remove the generated table-of-contents region (`<!-- wikitool:toc -->` ... `<!-- /wikitool:toc -->`, 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 <id>] [--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/<date>/<session>.{json,md}`. Read-only over `kb/` and exempt from the budget; see [../EVALS.md](../EVALS.md) |
 | `dist export <target> [--dry-run] [--source-repo U] [--source-commit SHA] [--release-url U] [--update-url U]` | Write a contentless, distributable copy of this repo's machinery into an empty `<target>` directory: `AGENTS.md`/`README.md`/`EVALS.md` with any `<!-- dist:strip-start -->...<!-- dist:strip-end -->` region removed, `instructions/` (minus `instructions/dev/`), `types/` (the `root: kb` page type-specs and their schemas re-keyed as `.template`, the stack's own verbatim), `docs/` verbatim, `tools/` (no venv/caches), the `.github/hooks/`+`.vibe/` session-tracing config plus `.claude/settings.json`, `kb/CONTRACT.md` (no pages, no areas), empty `raw/{articles,documents,notes,assets}/` and the
@@ -251,4 +265,4 @@ Run by the LLM through the skills, on this cadence:
  [INSTALL.md](../INSTALL.md) § "Eine Instanz aktualisieren". The `files` block
  of `.wikitool-release.json` is the groundwork - it records what the machinery
  looked like at install time, which is the only way to tell a file the
-  instance edited from one it merely received.
+  instance edited from one it merely received.