torben
dc688e5726
Files changed: - CHANGES.md - VERSION - instructions/gates.md - instructions/session-setup.md
3.4 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 is not exempt from
the budget (see § Scope for what that means):
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
The exemption is an 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. One entry on it, version regrade, is exempt only in its bare listing form and
counted when it is given positions to regrade; every other entry is exempt however it is called.
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.