torben
dc688e5726
Files changed: - CHANGES.md - VERSION - instructions/gates.md - instructions/session-setup.md
73 lines
3.4 KiB
Markdown
73 lines
3.4 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: session-setup
|
|
description: 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):
|
|
|
|
```bash
|
|
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](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:
|
|
|
|
```bash
|
|
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](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](gates.md).
|