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
This commit is contained in:
@@ -9,6 +9,23 @@ instead of action.
|
||||
`instructions/` is not a pipeline stage and not a collection. It is part of the control plane,
|
||||
alongside [AGENTS.md](../AGENTS.md).
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [Two forms, three reference tiers](#two-forms-three-reference-tiers)
|
||||
- [`instructions/migrations/`](#instructionsmigrations)
|
||||
- [`instructions/dev/`](#instructionsdev)
|
||||
- [Publishing](#publishing)
|
||||
- [Writing an instruction](#writing-an-instruction)
|
||||
- [A skill's H1 is a name, not an imperative](#a-skills-h1-is-a-name-not-an-imperative)
|
||||
- [Reference depth: bundled files, not repo-wide contracts](#reference-depth-bundled-files-not-repo-wide-contracts)
|
||||
- [When a skill carries a copy-in checklist](#when-a-skill-carries-a-copy-in-checklist)
|
||||
- [How much reasoning a step may carry](#how-much-reasoning-a-step-may-carry)
|
||||
- [Instruction duality](#instruction-duality)
|
||||
- [Single source](#single-source)
|
||||
- [What does not belong here](#what-does-not-belong-here)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Two forms, three reference tiers
|
||||
|
||||
| Form | File | Loaded by |
|
||||
|
||||
@@ -17,6 +17,21 @@ session worth keeping" is the user's, not the agent's. Nothing links to this fil
|
||||
`AGENTS.md` or a skill, and nothing should - a link there is exactly how a deliberate procedure
|
||||
stops being deliberate.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [Where a session's output belongs](#where-a-sessions-output-belongs)
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [1. Cut the session into topics](#1-cut-the-session-into-topics)
|
||||
- [2. Fix the fidelity before writing a word](#2-fix-the-fidelity-before-writing-a-word)
|
||||
- [3. Write each transcript](#3-write-each-transcript)
|
||||
- [4. File what is still open, before ingesting](#4-file-what-is-still-open-before-ingesting)
|
||||
- [5. Ingest, one transcript at a time](#5-ingest-one-transcript-at-a-time)
|
||||
- [6. Verify the set, not just the last one](#6-verify-the-set-not-just-the-last-one)
|
||||
- [Decision points](#decision-points)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Where a session's output belongs
|
||||
|
||||
Three surfaces, three jobs. Collapsing them is the failure this procedure exists to prevent.
|
||||
|
||||
@@ -30,6 +30,15 @@ the `/code-review` effort dial and the `Agent` tool's `model:` override have no
|
||||
other harnesses this repo supports (Codex CLI, GitHub Copilot CLI, Mistral Vibe). See
|
||||
[instructions/CONTRACT.md](CONTRACT.md) for that split.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
Before spawning a subagent with an explicit `model:` override, before picking a `/code-review`
|
||||
|
||||
@@ -20,6 +20,18 @@ This instruction exists only in the dev repo. A distributed instance has no
|
||||
issues at that URL, which is exactly why `dist export` excludes
|
||||
`instructions/dev/` wholesale (see [tools/CONTRACT.md](../../tools/CONTRACT.md)).
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [Incoming stubs](#incoming-stubs)
|
||||
- [Renames and other decay in the tracker](#renames-and-other-decay-in-the-tracker)
|
||||
- [Citing an issue in the repo](#citing-an-issue-in-the-repo)
|
||||
- [What no tool checks](#what-no-tool-checks)
|
||||
- [Decision points](#decision-points)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
- Something is worth doing but not now. Open an issue; do not write it down in
|
||||
|
||||
@@ -19,6 +19,17 @@ the first CI run that ever reached pytest, in a container that had no such confi
|
||||
(Gitea #8). Two more tests of the same kind were written afterwards, by someone who had read
|
||||
that issue first - which is the argument for a fixture rather than a rule.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [What the fixture already neutralizes](#what-the-fixture-already-neutralizes)
|
||||
- [Which tree a test writes into](#which-tree-a-test-writes-into)
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## What the fixture already neutralizes
|
||||
|
||||
Do not re-do any of this per test; it is done for you, per test, via `monkeypatch`.
|
||||
|
||||
@@ -20,6 +20,17 @@ Two questions decide a version bump, and they are **not the same question**:
|
||||
Getting these backwards is how a genuinely breaking change ships as a MINOR. It happened once
|
||||
already (see the case study at the end), which is why this file exists.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [The candidate model](#the-candidate-model)
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
- [Case study: 2.0.0](#case-study-200)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## The candidate model
|
||||
|
||||
Between two releases the stack carries **one running candidate**, not a fresh version per
|
||||
|
||||
@@ -21,6 +21,15 @@ first place: a schema `default:` that the compiler applied whenever nobody
|
||||
disagreed, silently turning the least specific value into the collection point for everything
|
||||
unclear.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
- A `wikitool lint` advisory finding reports pages sitting in a subtype's catch-all value (for
|
||||
|
||||
+16
-1
@@ -19,6 +19,17 @@ Read the exit code first - it says which of these applies:
|
||||
| 42 | User clearance required | Reproduce the command's output in your reply, stop. See below. |
|
||||
| 1 | Validation error, or a budget/loop refusal | Read the `ERROR` line; fix and retry once, or stop and escalate. |
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [Exit 42: user clearance required](#exit-42-user-clearance-required)
|
||||
- [Publish-Remote Gate](#publish-remote-gate)
|
||||
- [Mass-Update Gate blind spot: `upstream merge`](#mass-update-gate-blind-spot-upstream-merge)
|
||||
- [Iteration Budget Gate and loop-breaker](#iteration-budget-gate-and-loop-breaker)
|
||||
- [Taking a new session id](#taking-a-new-session-id)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Exit 42: user clearance required
|
||||
|
||||
A `wikitool` command that exits **42** is not reporting an error. It is refusing to act until a
|
||||
@@ -159,7 +170,11 @@ When it trips:
|
||||
at exactly the limit it is refused too. The only way past is `--override-budget` on the
|
||||
command you actually need to run, and only with the user's approval.
|
||||
|
||||
`wikitool search` is exempt from this budget entirely: retrieval is reading, not iterating.
|
||||
A dozen commands are exempt from this budget entirely - `search` and `doctor` because retrieval
|
||||
and diagnosis are reading, not iterating, plus the read-only forms of `links`, `cite`, `budget`,
|
||||
`eval`, `version`, `migrate` and `upstream verify`. The exemption is that fixed allowlist in
|
||||
[tools/CONTRACT.md](../tools/CONTRACT.md), not a "does not change the wiki" rule of thumb: `lint`
|
||||
only writes to gitignored `reports/` and still counts, because it is not on the list.
|
||||
|
||||
### Taking a new session id
|
||||
|
||||
|
||||
@@ -19,6 +19,16 @@ Derived from translating all 248 pages on 2026-08-29. Every entry below is a dec
|
||||
made wrong at least once first - each cost a correction pass across published pages, which is why
|
||||
they are written down instead of re-derived.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [Stays English](#stays-english)
|
||||
- [Settled German](#settled-german)
|
||||
- [Field labels](#field-labels)
|
||||
- [Register](#register)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Stays English
|
||||
|
||||
Established technical terms are not Germanized, in prose or in headings:
|
||||
|
||||
@@ -9,6 +9,16 @@ A tree too big for one ingest is cut into units before anything is written, and
|
||||
read, promoted and published on its own. The plan and the intermediate extracts live in a
|
||||
`work/` workshop, so the run survives across sessions and days instead of having to fit in one.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Tiers](#tiers)
|
||||
- [Steps](#steps)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
Any one of these is enough:
|
||||
|
||||
@@ -19,6 +19,24 @@ verbatim - so every instance that wanted something else edited a stack file, and
|
||||
merge handed the stack's answer back. What binds is now the instance's; what ships is this
|
||||
catalogue, and it binds nothing.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [Language profiles](#language-profiles)
|
||||
- [`german`](#german)
|
||||
- [`english`](#english)
|
||||
- [Writing a third one](#writing-a-third-one)
|
||||
- [Collection profiles](#collection-profiles)
|
||||
- [`entities`](#entities)
|
||||
- [`concepts`](#concepts)
|
||||
- [`sources`](#sources)
|
||||
- [`comparisons`](#comparisons)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
- Setting up a new instance: the KB-language step of
|
||||
|
||||
@@ -17,6 +17,25 @@ rendered verbatim into the page body, so it is never translated - not in a Germa
|
||||
any other. Which words a page is *written* in stays [kb/CONVENTIONS.md](../kb/CONVENTIONS.md)'s;
|
||||
this is not one of them.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [The invariant every label obeys](#the-invariant-every-label-obeys)
|
||||
- [Direction is authored, never mirrored](#direction-is-authored-never-mirrored)
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [The catalogue](#the-catalogue)
|
||||
- [Operational](#operational)
|
||||
- [Realization](#realization)
|
||||
- [Conceptual](#conceptual)
|
||||
- [Lineage](#lineage)
|
||||
- [Evidence](#evidence)
|
||||
- [Universal](#universal)
|
||||
- [Extending it](#extending-it)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## The invariant every label obeys
|
||||
|
||||
Every label completes, with the page carrying the link as the grammatical subject:
|
||||
|
||||
@@ -19,6 +19,15 @@ serves, and how that checkout stays current. What it exposes and why is in
|
||||
lives - that is private infrastructure and this is a public repository. What is here is
|
||||
everything an operator needs that is *true of the software* rather than of one installation.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
- Standing something up for a consumer that is not a terminal on this machine.
|
||||
|
||||
@@ -16,6 +16,16 @@ defects this way - a dropped citation that silently unsourced a claim, a dropped
|
||||
invented one, and a translated H1 - and three of the four had unchanged link *sets* and only
|
||||
changed counts.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [Decision points](#decision-points)
|
||||
- [Writing the migration document](#writing-the-migration-document)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
A change that would otherwise be applied to more than a handful of pages by hand, or any change
|
||||
|
||||
@@ -24,6 +24,16 @@ that file rather than from `tools/chemenu/sections.py`.
|
||||
`kb/comparisons/` is touched. What changes are the contracts beside them, which is why this is
|
||||
`mechanical` and takes minutes rather than a workshop.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [How to tell a migrated instance from an unmigrated one](#how-to-tell-a-migrated-instance-from-an-unmigrated-one)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
After installing 3.0.0 machinery over an instance that was on 2.x, when `tools/wikitool doctor`
|
||||
|
||||
@@ -27,6 +27,16 @@ and every tool-owned body region changes. It is `assisted` because there is no m
|
||||
mapping free-text German onto a 35-label catalogue is a judgment call per edge, and a large
|
||||
minority of the old labels are reverse directions that under the new model are not stored at all.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [How to tell a migrated page from an unmigrated one](#how-to-tell-a-migrated-page-from-an-unmigrated-one)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
After installing 4.0.0 over an instance on 3.x. `tools/wikitool migrate status` names it, and
|
||||
|
||||
@@ -17,6 +17,17 @@ saves the whole update procedure afterwards.
|
||||
**Read this before, not after, the first `publish`.** The gate in step 4 is the thing that makes
|
||||
the arrangement safe, and adding it later means the window it closes was open in between.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [Why a clone rather than a tarball](#why-a-clone-rather-than-a-tarball)
|
||||
- [Steps](#steps)
|
||||
- [Taking a stack update](#taking-a-stack-update)
|
||||
- [Where stack development happens](#where-stack-development-happens)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Why a clone rather than a tarball
|
||||
|
||||
`INSTALL.md`'s "Eine Instanz aktualisieren" is `cp -r` as an upgrade strategy: copy `tools/`,
|
||||
|
||||
@@ -15,7 +15,8 @@ shell inherits an unrelated count.
|
||||
|
||||
## Steps
|
||||
|
||||
Run this **once per working session**, before the first `wikitool` call that changes anything:
|
||||
Run this **once per working session**, before the first `wikitool` call that is not exempt from
|
||||
the budget (see § Scope for what that means):
|
||||
|
||||
```bash
|
||||
export WIKITOOL_SESSION_ID="wiki-$(date +%s)"
|
||||
@@ -56,7 +57,15 @@ refusal. See [gates.md](gates.md).
|
||||
|
||||
## Scope
|
||||
|
||||
Read-only retrieval (`wikitool search`) is exempt from the budget and needs no setup. This
|
||||
matters only for commands that change the wiki.
|
||||
**The exemption is a fixed allowlist, not "read-only" or "does not change the wiki."** A command
|
||||
needs this setup unless it is one of the dozen `tools/CONTRACT.md` marks exempt in its command
|
||||
table (`search`, `doctor`, `links show`, `cite id`, `budget status`, the read-only forms of
|
||||
`eval`, `version`, `migrate` and `upstream verify`) - that table, not a rule of thumb here, is
|
||||
the single list.
|
||||
|
||||
`lint` is the case that breaks the "changes the wiki" reading: it only writes to `reports/`,
|
||||
which is gitignored, so it looks side-effect-free - but it is not on the allowlist and is counted
|
||||
like any mutating command. A skill that calls only exempt commands needs no session id; a skill
|
||||
that calls `lint` alone still does.
|
||||
|
||||
The limits themselves, and what to do when one trips, are in [gates.md](gates.md).
|
||||
|
||||
@@ -11,6 +11,14 @@ zu einer funktionsfähigen, eigenständigen Wiki-Instanz - mit eigenem Git-Repo,
|
||||
Identität und (optional) eigenem Remote. Am Ende ist die Instanz committet, verifiziert und
|
||||
bereit für den ersten `Ingest`.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [Wann anwenden](#wann-anwenden)
|
||||
- [Schritte](#schritte)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Wann anwenden
|
||||
|
||||
- Der Nutzer möchte eine neue, leere Wiki-Instanz aufsetzen (eigenes Thema, anderer Nutzer).
|
||||
|
||||
Reference in New Issue
Block a user