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.
4.3 KiB
work/ - Workshop Layer
Scratch space for a task that does not fit in one session: the notes, extracts and plans an
agent produces on the way to a kb/ page. Tracked in git, and deleted when the task closes.
Quality goal: move the work forward, and carry the durable half out before it ends. Nothing here is knowledge yet.
Why this is not reports/
Both directories hold intermediate output, and they are opposites.
reports/ |
work/ |
|
|---|---|---|
| Content | Recomputable - wikitool lint regenerates it |
Judgment in progress - nothing can re-derive it |
| Git | Gitignored | Tracked |
| Lost on session end? | Nothing is lost | Everything would be |
A workshop exists precisely because a long ingest spans sessions, machines and days. Committing
it is the whole point; a gitignored workshop would be a reports/ directory with extra steps.
One run, one directory
work/<runkey>/
README.md # run key, goal, closing condition, checklist, open decisions
plan.md # the input tree cut into units, with a reason per cut
extract-<unit>.md
audit.md # only for audited units
README.md and plan.md are required. Everything else is free-form.
Run keys
The directory name is the run key. There is no second identifier - a run key stored somewhere else is a copy, and a copy drifts (the same reasoning as AGENTS.md invariant 2).
Derive it from the input path below raw/, with separators flattened and the prefix
ingest-:
raw/documents/handbook/ -> work/ingest-documents-handbook/
raw/articles/some-post/ -> work/ingest-articles-some-post/
Not the basename: raw/documents/handbook and raw/articles/handbook would collide.
A collision is an error, never an auto-suffix. If work/<runkey>/ already exists, that
means this tree is already being ingested - which is the condition the key exists to detect.
Resume the existing run or ask the user; do not create <runkey>-2.
A genuine second pass over the same tree - a re-ingest after the tree itself changed - is
<runkey>-<YYYY-MM-DD>, dated by the new run. The first run never carries a date, so resuming
it after midnight does not require guessing yesterday's.
A run with no raw input - a migration, a sweep across kb/, anything that is not an ingest -
names its key outright instead (for a migration, the procedure is
instructions/migrate-corpus.md):
tools/wikitool work new --key translate-kb-de -> work/translate-kb-de/
The ingest- prefix is reserved for derived keys, so the directory name always says which kind
of run produced it. Everything else is unchanged: same collision rule, same required files, same
one-key-one-directory identity. The reason such a run still opens a workshop is plan.md - the
written unit boundaries are what make taking a new WIKITOOL_SESSION_ID per unit legitimate
rather than a way around a gate refusal (instructions/gates.md).
tools/wikitool work new derives or normalizes the key, checks for the collision and scaffolds
the directory. Do not create a workshop by hand.
ls work/ is the index. Because names are path-derived, the filesystem already answers "what
is in flight" - there is no curated list to keep in sync, and none may be introduced.
Not a wiki collection
- No
type:frontmatter, no schema, noCOLLECTION.md. Workshop files are plain markdown. - No page ever links into
work/. A workshop is a sink, not a source: if something here is worth citing, promote it tokb/first. index rebuild,lint,provenanceandsearchdo not see this directory, and must not learn to.
Closing a run
- Every checklist item in
README.mdis done, or explicitly dropped with a reason. - The durable conclusions are in
kb/- pages, cross-references,## Not Extracted. - Delete the workshop directory.
tools/wikitool log appendrecords the run.
A run that leaves its conclusions only in work/ has lost them, exactly as in
reports/CONTRACT.md. The difference is only that here they survive
until step 3.
Publishing
Workshop files are committed like anything else, but they do not count toward the Mass-Update Gate - the gate protects published knowledge, and a directory that is deleted on closure is not that. See tools/CONTRACT.md for the exact rule.