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.
101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
# 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](../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](../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, no `COLLECTION.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 to `kb/` first.
|
|
- `index rebuild`, `lint`, `provenance` and `search` do not see this directory, and must not
|
|
learn to.
|
|
|
|
## Closing a run
|
|
|
|
1. Every checklist item in `README.md` is done, or explicitly dropped with a reason.
|
|
2. The durable conclusions are in `kb/` - pages, cross-references, `## Not Extracted`.
|
|
3. Delete the workshop directory.
|
|
4. `tools/wikitool log append` records the run.
|
|
|
|
A run that leaves its conclusions only in `work/` has lost them, exactly as in
|
|
[reports/CONTRACT.md](../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](../tools/CONTRACT.md) for the exact rule.
|