torben
18ae28f918
Chemenu kompiliert Rohnotizen zu einem verlinkten, quellengebundenen Wiki: raw/ -> types/ + tools/ -> kb/ -> reports/. Was mechanisch ist, macht tools/wikitool; was Urteil braucht, macht ein Agent unter Contracts, deren Grenzen in Code durchgesetzt sind statt im Prompt. Dieser Commit ist der Startpunkt der oeffentlichen Historie. Die vorherige Entwicklung fand in einer privaten Instanz statt und ist nicht Teil dieses Repositorys; ihre Erzaehlung steht vollstaendig in CHANGES.md, das mit 44 Eintraegen von 0.1.0 bis 2.1.0 erhalten geblieben ist. Der mitgelieferte Korpus ist ein Testbett und eine Demo: 170 Seiten ueber den Stack selbst - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Er dokumentiert das Werkzeug mit den eigenen Mitteln des Werkzeugs. Lizenz: AGPL-3.0 fuer den Stack (tools/, types/), CC-BY-4.0 fuer die Inhalte. Die Grenze zwischen beiden ist der Dateiplan, den dist export berechnet - siehe NOTICE.
2.6 KiB
type, name, description
| type | name | description |
|---|---|---|
| types/instruction.md | session-setup | Scope the wikitool iteration budget to the task by exporting a stable session id before the first tool call. |
Scope the session budget
Every wikitool call is counted against a per-session iteration budget. A "session" is keyed
by WIKITOOL_SESSION_ID, falling back to the parent process id when that variable is unset.
Without an explicit id, the budget is scoped to whichever shell happened to run the command, so a task spanning several terminals is counted as several sessions - and one that reuses a shell inherits an unrelated count.
Steps
Run this once per working session, before the first wikitool call that changes anything:
export WIKITOOL_SESSION_ID="wiki-$(date +%s)"
tools/wikitool sync
Check the current state at any time with tools/wikitool budget status, which is never
counted against the budget itself and prints the id it is counting under.
Why sync here, not just at publish time. publish already pulls before it pushes, but a
session that runs many wikitool calls before its first publish (an ingest, a multi-page
update) would otherwise build all of that work against whatever the local clone happened to
hold when the session started - stale by however long the previous sync was, on a repo more
than one machine or session writes to. Running sync first shrinks that window to the start of
the session instead of discovering the drift only at the very end.
sync fetches the remote and fast-forwards or rebases automatically when that is safe; it
never commits and never pushes. Exit 42 (rebase-review)? Same as any exit 42 - read the
diff it prints, judge whether it conflicts with what you are about to do, summarize that to the
user, then tools/wikitool sync --confirm-rebase <token> before continuing. See
gates.md.
Multi-unit runs
A task planned as several units - a tree ingest, where each unit produces its own source page
and its own publish - takes one id per unit, derived from the workshop's run key:
export WIKITOOL_SESSION_ID="ingest-documents-handbook/u3"
The run key, the workshop directory name and the session id are then the same string, so the
checklist in work/<runkey>/README.md and the budget state cannot disagree about where the
run stands.
A new id may only be taken at a unit boundary recorded in plan.md - never after a gate
refusal. See 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 limits themselves, and what to do when one trips, are in gates.md.