# Artifact formats

What gets written in a topic folder. How sessions run is [method.md](method.md). Every file belongs to a named class; never let one masquerade as another.

| Class | What |
| --- | --- |
| 1 — raw dumps | lossless sweep output, one file per lane + critic |
| 2 — synthesis | opinionated analysis over the raw; filed, never chat-only |
| 3 — goal track | what we're trying to achieve; from user intent, not sweeps |
| canon | the ratified deliverable, own subfolder + `00-INDEX.md` |
| spine / clips / auxiliaries | README, `references/`, bibliographies-matrices-built-artifacts |

A ratified class-3 doc **is** the goal-track canon — never double-book it under canon.

**The two audiences**: every artifact serves exactly one reader — the **operator** (human) or the **agent** (main line, sub-agents, downstream syntheses). Operator-facing artifacts (syntheses, goal track, canon, auxiliaries the user reads) are **self-contained**: written in full verbosity, the substance of every cited item expanded inline in prose — summarized in place where full expansion would bloat — never lane IDs, item codes, or link trails the reader must chase. Agent-facing artifacts (raw dumps, and the referential twin of any operator doc) stay maximally cross-referenced: stable IDs, links, the citation grammar. When one document must serve both, it **forks**: the readable edition keeps the canonical name and slot; the referential twin lives in the topic's `machine/` subfolder and remains the citation-of-record (verification, adjudication, and downstream citing run against the twin). Each opens with a one-line pointer to the other; ratification stamps land on the readable edition and are mirrored onto the twin; the twins are the same content in two registers, never allowed to drift — a substantive change lands in both or is a break. Numbered handles the user disposes by (open questions, register items) survive in the readable edition — they are dialogue handles, not citations. The register itself is governed by the workspace style registry `metadata/writing-styles/`: one operator-owned file per register, `reading.md` the default for documents presented to the operator, others (`blog.md`, `email.md`, …) when the operator names one; a named-but-missing style is drafted from the operator's instructions in the moment, filed there unratified, and applied. Grandfathering applies: existing referential artifacts stand; fork on next touch or user request.

**Banner**: class 1/2/3 artifacts and auxiliaries open with an H1 + `>` blockquote banner: **class · derivation (links + scale) · method · ISO date · ratification status**. Status applies to 2/3/auxiliaries only — raw dumps are immutable, never ratified. Exempt: canon (its own `**Status:**` line / orientation paragraph) and clips (two-line header).

**Status vocabulary**: `**DRAFT — not yet ratified**` / `Not yet user-ratified` · `(ratified YYYY-MM-DD)` — at doc, section, or extract granularity · `**Superseded note (YYYY-MM-DD):** … kept as record` · `deferred — blocked on <gate>` vs the exclusion grades.

**Immutability**: raw dumps immutable once filed (corrections land in critic or synthesis) · unratified syntheses may be rewritten in place as v2, recorded in provenance · ratified material changes by dated append or supersession only · nothing valuable is deleted — superseded → banner + keep; a retired topic → `git mv` to `archived/`, dated archive banner, kept frozen as record; broken → flagged; closed threads → struck through. Every lifecycle event carries an ISO date.

## The topic README

Routes and records, never duplicates the research. Sections in order (first and last invariant):

1. `# <folder-slug> — <subtitle>`
2. **Topic definition** — subject, driving question (user's words verbatim), standing scope decisions (dated). If canon exists, a bold pointer line at the very top.
3. `## TL;DR of current understanding` — present-tense verdict, **rewritten in place** (the one non-append-only section); ratification status inline per claim; closes with `Full argument: [00-synthesis.md]` when a lead synthesis exists.
4. `## Provenance chain` — numbered, **append-only**. Entry: `N. **YYYY-MM-DD — <3–8 word headline>.** <body>` — one entry per **event**, not per session. Body: trigger (user quoted verbatim for rulings) · what ran (telemetry) · what was filed (links) · dispositions · adjudications (counts + reasons) · closing status. Never edited into a new story — a break gets a new entry.
5. `Folder map: [metadata.md](metadata.md)` — a pointer line only. The map itself is **`metadata.md`**, beside the README: one line per file (name + what it is + class/status; breakage flagged there, file kept; bulk directories one line total). Rewritten in place — the map is state, not record.
6. `## Open threads` — every item **deferred** (with its blocker; point at the synthesis's numbered questions when awaiting the user) or **excluded** (graded). Retired threads struck through: `~~<thread>~~ **Excluded by decision** (YYYY-MM-DD, provenance entry N).`

Seed at creation: title, definition, empty Open threads, and the `metadata.md` map. Every state-changing session: append provenance, rewrite TL;DR, reconcile the map and threads. Pre-codification topics grow the missing spine when next touched — one dated catch-up entry, not invented history.

## Raw dumps — filing sweeps

The lossless appendix of record; everything downstream cites into it. Never distill-and-discard.

- One sweep = one folder: `research-<slug>/` (web) or `surveys/` (codebase). Only lane files + critic inside. Files `01-<lane>.md` … `NN-completeness-critic.md`, critic always last; gap-fill files continue the sequence. Script filing: word-boundary filename truncation; check briefs for leaked placeholders.
- **Lane file**: banner (same template across the sweep) · charter incl. what it deliberately does **not** cover (a sibling owns it) · **verdict first** · shared dissection template across lanes · **stable item IDs** (`A1`, `H3`) so downstream cites precisely · sourcing (web: every figure dated; conflicts → both numbers with dates; secondary sources flagged; closing `## Sources` with URL + access date; codebase: file paths) · exclusion notes, so absence ≠ oversight.
- **The critic**: reads all lanes in full, then coverage audit (severity-ordered, naming the sweep-design bias behind each hole) · cross-lane contradictions (adjudicated or flagged) · verification spot-checks of load-bearing claims · convergence vs tension (2+ lanes agree → settled input; tensions → user decisions) · prioritized follow-up briefs. Critic fetches are clipped to `references/`.
- **Gap-fills**: one lane per critic finding worth closing now, same folder, numbering continued, banner naming the finding it answers.
- Provenance is split: file banner = method + date; README entry = agents + model + results (model lives only there). Citation grammar downstream: lane / item ID / `file:line` — a claim that can't be cited this way means the raw layer failed.

## Synthesis

Discussion material, not canon: a verdict the user can react to, every claim traceable to the raw record. The lead working doc takes the `00-` slot at topic root; it may grow chapters `00-`…`NN-` in production order, each banner stating which distinct question it answers vs the earlier ones.

Skeleton: `## The verdict` first (1–3 sentences, load-bearing clause bolded) · **what holds / what breaks** · evidence spine (numbered bold-led findings citing lanes/IDs/`file:line`, weighted by convergence counts) · **pushback register** — the user's own framing adjudicated item by item: vindicated / broken / reframed; filed, not softened · stable IDs on disposable units (T1…, H1…, B1…) · epistemics (confidence flags, data hygiene before canon, sweep-quality note) · judgment record (overrules with citations; "undecidable — user to ratify or commission") · `## Open questions for reaction` **always last** — numbered, each disposable (accept / reframe / exclude / defer), recommendation attached where you have one. These become the README's Open threads by reference.

Lifecycle: filed "Not yet user-ratified" → broken pre-ratification: rewritten **in place** as v2 (versioned title, break in provenance) → broken by a sibling: the newer file declares "what this breaks", the older stays but gets flagged in the folder map → superseded by canon: dated superseded banner, **kept**. Partial ratification is stamped at the granularity it happens. Synthesis argues from evidence and ends in questions; canon states settled method and ends in exclusions.

## The goal track

When a topic has a **goal**, not just a subject: a parallel doc recording what we are trying to achieve — from the user's intent, never from sweeps. Draft it as soon as the goal appears (late drafting is a repair). Only the user ratifies.

- Two shapes: **vision narrative** (the goal state as a story, as if it already exists: thesis → numbered journey sections → closing "why it compounds") or **intent charter** (`What we are trying to achieve` → `Overarching goals` → `The questions this topic must answer` → `What done looks like` → `Excluded by decision`, dated → `Open intent — only the user can fill these`).
- Placement: single doc at topic root (`mental-model.md`) or a subfolder (`vision/`) if it will grow. The README states the split in one line — "sweeps describe what *is*; this track describes what we're *building*".
- Voice: present-tense declarative about the future, in the user's vocabulary; no hedging, no evidence citations. **Divergence flags are mandatory** wherever reality differs, kept out of the body: `## Grounding notes` at the bottom (ratified narrative kept clean) or inline `⚑ *Divergence flag:*` (draft whose divergence is under deliberation).
- Ratified, it **is** the goal-track canon. Updated, not superseded: a resolved flag becomes changed intent (edit the body + dated provenance entry — the one sanctioned edit into ratified material) or changed plan (keep the flag, date the disposition).

## Canon

The user-ratified deliverable — settled, never exploratory. Own subfolder (`<topic>/playbook/`), zero-padded numbered chapters, `00` reserved for the index.

`00-INDEX.md`, in order: H1 · `**Status:**` (state + ISO date · one-line distillation provenance · source-of-truth declaration: "this directory, not the sweeps") · `## Scope and exclusions` (excluded-by-decision vs deferred, distinguished; a later-canonized deferral gets its bullet rewritten) · `## The axioms` (numbered; bold one-sentence lead + a line of elaboration; **append-only** under dated introducers — never renumber) · chapter table (`# | chapter | concern`, linked) · `## Conventions`.

Chapters: H1 = short noun title, no number (the number lives in the filename) · bold orientation first paragraph ("**Pass N of the method.** Input: … Output: …"; post-ratification additions carry the date + a link to the grounding sweep) · self-contained, declarative present tense, cross-linked to siblings, axioms cited by number · named patterns: **bold name** + `**Definition:**` / `**When to use:**` / consequence + real product examples — the user's coined word is the canonical name; credit external frameworks, claim originals explicitly · deliberate closer: `## Anti-patterns` (commonest), "Output of this pass" (pipelines), or "Known whitespace" (catalogs).

Canonization checklist (only on explicit ratification): survivors in the user's reframed language → axioms appended under a dated introducer; chapter table updated → stale "deferred" stubs rewired → dated superseded banner on the outdated synthesis, kept → README reconciled (provenance entry, canon pointer line up top, Open threads) + `TOPICS.md`.

## References and auxiliaries

- **`references/` clips** — sources surfaced in discussion, clipped losslessly: one file per source, kebab-case title slug, header first (`Source URL: <url>` / `Retrieved: YYYY-MM-DD`), faithful markdown, quotes verbatim; optional curator's blockquote stating the clip's role. Clips only — sweep output stays in its sweep folder.
- **Auxiliaries** (bibliographies, matrices, built artifacts) fit no class — don't force one; self-describe via banner with an explicit class disclaimer ("not sweep output") + ratification status. Bibliography: thread-grouped H2s, `**Author, *Title* (year)** — why it matters here`, `★` priority reads, closing "Suggested reading order". Matrix: banner (source, validation, acceptance), glyph legend (`■ solid · ▫ partial · † dead · blank`), column key linking the source doc, "Reading notes" closer, unratified membership rules flagged. Built artifact: its own buildable subfolder inside the topic — a deliverable, not a record; any embedded re-cut of a canon/vision doc names its source-of-truth and is regenerated, never edited into a fork.
- The README folder map annotates every auxiliary; the provenance chain records its creation and validation.