feat: export guidelines - the guideline pages as a generated GUIDELINES.md, pushed into the captured repositories behind the Guideline Push Gate (#179)
CI / verify (push) Successful in 5m40s
CI / pwsh (push) Successful in 1m59s
Release / release (push) Successful in 35s

Files changed:
- AGENTS.md
- CHANGES.md
- README.md
- VERSION
- docs/why-gates-are-code.md
- instructions/gates.md
- instructions/kb-profiles.md
- kb/CONTRACT.md
- kb/CONVENTIONS.md
- kb/CONVENTIONS.md.template
- raw/CONTRACT.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/export_cmd.py
- tools/chemenu/commands/page_ops.py
- tools/chemenu/commands/raw_cmd.py
- tools/chemenu/commands/search.py
- tools/chemenu/guideline_export.py
- tools/chemenu/kb_scan.py
- tools/chemenu/repo_capture.py
- tools/chemenu/search/filters.py
- tools/chemenu/tests/test_cli.py
- tools/chemenu/tests/test_export_guidelines.py

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
torbenandClaude Opus 5.5 committed 2026-10-06 06:48:07 +02:00
1 parent ccede04b97
commit 283cdae8be
25 files changed
+1753 -68

No files matched your search

+19 -1
View File
@@ -13,7 +13,7 @@ how it works, so it is identical everywhere and `dist export` ships it verbatim.
**What an instance decides for itself is next door, in
[kb/CONVENTIONS.md](CONVENTIONS.md)** - the language pages are written in, the headings its two
generated regions render under, the naming forms, the tone, the hedging rule. That file binds exactly as this one does; it is simply owned by the instance
generated regions render under, the naming forms, the tone, the hedging rule, which pages leave the wiki as guidelines. That file binds exactly as this one does; it is simply owned by the instance
rather than by the stack, so the distribution ships only its `.template` and the instance writes
the real one. Read both, plus the target collection's `kb/<name>/COLLECTION.md` (also
instance-owned), before writing or editing a page.
@@ -40,6 +40,7 @@ looks like) are in neither - they belong to the type-specs and are printed by
- [Generated regions](#generated-regions)
- [Linking](#linking)
- [Provenance and citation](#provenance-and-citation)
- [Pages that leave the wiki: guidelines](#pages-that-leave-the-wiki-guidelines)
- [What does not belong here](#what-does-not-belong-here)
<!-- /wikitool:toc -->
@@ -329,6 +330,23 @@ Every claim is either traceable to a raw file or explicitly marked as not.
If no raw file or existing page backs an answer, say so explicitly rather than synthesizing
one - and never file the synthesized version back into the wiki.
## Pages that leave the wiki: guidelines
`tools/wikitool export guidelines` renders a selection of pages into one generated
`GUIDELINES.md` and, behind the Guideline Push Gate, writes it into the captured repositories that
opted in ([raw/CONTRACT.md](../raw/CONTRACT.md#getting-a-repository-in-raw-capture)). Which pages
that is, is not decided here: the stack defines no type and no field for a guideline, and the
selection - a set of `search` predicates - is written down in
[kb/CONVENTIONS.md](CONVENTIONS.md) by the instance.
What the stack does decide is how a page reads once it has left. The export is mechanical:
frontmatter, the generated links and footnotes regions and every citation marker are dropped,
`[[Title|Text]]` becomes `Text` and `[[Title]]` becomes `Title`, and code is left untouched. So a
guideline has to stand on its own in another repository - without its links to follow and without
the sources behind it - and an edit to one reaches every target repository on the next export.
The file there is never edited by hand: the next export overwrites it, so a correction goes into
the page.
## What does not belong here
- Raw source material - it stays immutable under `raw/`.
+13
View File
@@ -35,6 +35,7 @@ those regions and nothing else. Nothing matches on this text.
- [Tone](#tone)
- [Relationship labels](#relationship-labels)
- [Hedging](#hedging)
- [Guidelines for other repositories](#guidelines-for-other-repositories)
- [Keeping this file honest](#keeping-this-file-honest)
<!-- /wikitool:toc -->
@@ -140,6 +141,18 @@ carry, not against a threshold.
This is `SOUL.md`'s existing standard ("Was nicht belegt ist, ist nicht gewusst, nur vermutet -
und wird auch so benannt"), applied to `kb/` without a number competing next to it.
## Guidelines for other repositories
`tools/wikitool export guidelines` renders the pages this filter selects into one generated
`GUIDELINES.md` for the repositories this instance captured (`raw/CONTRACT.md`). The stack defines
no type or field for a guideline - which pages are guidelines is this instance's decision, and it
is written down here and nowhere else.
**The filter is `--tag guideline`.** A page carries the tag when its content is a rule an agent
working in another repository should follow there as it stands - written so that it reads without
its links and citations, because the export turns `[[links]]` into plain text and drops every
footnote. No page in this corpus carries it yet.
## Keeping this file honest
Change it when a convention actually changes. `sections:` is safe to change at any time - the
+11
View File
@@ -34,6 +34,7 @@ marker pair, so a rename re-renders words and nothing else.
- [Tone](#tone)
- [Relationship labels](#relationship-labels)
- [Hedging](#hedging)
- [Guidelines for other repositories](#guidelines-for-other-repositories)
- [Keeping this file honest](#keeping-this-file-honest)
<!-- /wikitool:toc -->
@@ -112,6 +113,16 @@ sourced claim, in the KB language.}
(`raw/CONTRACT.md`'s `authority` axis) from one resting on `opinion`, and how it signals
disagreement between sources.}
## Guidelines for other repositories
`tools/wikitool export guidelines` renders the pages this filter selects into one generated
`GUIDELINES.md` for the repositories this instance captured (`raw/CONTRACT.md`). The stack defines
no type or field for a guideline - which pages are guidelines is this instance's decision, and it
is written down here and nowhere else.
{The selection, as `search` predicates - for example `--tag guideline` - or "none" if this
instance exports no guidelines.}
## Keeping this file honest
Change it when a convention actually changes. `wikitool doctor` FAILs on a missing or unfilled