# 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.