design-harness

# design-harness — the human adjudicates, the agent runs errands

Markdown is the **single source of truth**; the canvas HTML, every layer index, and the
location registry are projections, rebuildable at any time. Judgment comes only from the
human; you lay out options and evidence and run the errands — never adjudicate in the
human's place.

## Structure

### Workspace layout

```
<workspace>/
├── target.md             the human's acceptance criteria; source of the output form
├── logs.md               append-only change ledger (see "Disciplines · Ledger")
├── index.md              workspace entry point
├── sources/<type>/*.md   ① evidence: one source, one card
├── ideas/*.md            ② judgments (archive/ holds archived cards)
├── output/…              ③ assembly; internal structure set by the chosen output form
└── board/*.md            free surface: one file, one board
```

A host may hold many workspaces under any directory names; the sole registry is
`.design-harness/config.json` at the host root — discovery trusts the registry, never
the directory name.

Every layer also carries an `index.md`, grouped under tag headings (`## TAG: one line on
why they belong together`), unclassified cards flat at the end after a `---` divider and
an *unclassified* marker. Search goes through the indexes; there is no classification
layer.

### Three layers + the free surface

1. **sources/ — evidence.** One source, one card, filed under `sources/<type>/`. The
   agent ingests and grades freely, and invents the type directories itself — no preset
   list; name them after what the source is (papers, github, podcasts, …), adding
   directories as needed. The directory name projects verbatim as the card's badge on
   the canvas.
2. **ideas/ — judgments.** **Judgment comes only from the human**: decision judgments the
   human voices in conversation are transcribed into idea cards automatically, and the
   human can simply ask for a card to be added; the agent transcribes, never invents.
   Two states: live (the file exists) and archived (moved into `ideas/archive/`, never
   deleted). A new idea repeating an old card's judgment merges automatically; a
   conflicting one puts both on the board for the human to pick.
3. **output/ — assembly, the convergent layer.** **First assembly is human-initiated**;
   its form comes from [references/output-forms/](references/output-forms/system-design.md)
   and the human's `target.md`. Ideas diverge, output converges: output changes only on
   the human's word (see "Workflow · Sync").

One free surface besides: **board/** — the human's own boards, one markdown file per
board (comparison matrices, theme grids, any scratch reasoning). **No schema, no
required fields** — this freedom belongs to the human; edit only when asked ("lay these
three sources out as a comparison").

### Card schema and templates

- A card = **frontmatter + title + summary**. No fixed sections; references are inline
  links in the summary.
- `ideas/` cards (including `archive/`): frontmatter **requires `id` and `type`**;
  `tags` and `conflicts` optional (see "Exactly three structured facts"). No status
  field — the file's existence is the live state, sitting under `archive/` is the
  archived state.
- `sources/` cards: frontmatter optional; when present only `tags` is read.
- `board/` documents: **no schema**. The board is **terminal**: it may reference any
  layer, but sources/ideas/output must never reference the board — distill a board's
  conclusions into idea cards.

idea card template:

```markdown
---
id: <kebab-slug, matching the filename>
type: idea
tags: [<at most one; omit the whole line>]
conflicts: [<ids of prior cards this judgment contends with; omit when none>]
---

# <the judgment in one sentence>

<Summary: what the judgment says and why; the evidence and prior cards it stands on as
inline links.>
```

source card template:

```markdown
---
tags: [<at most one; the whole frontmatter may be omitted>]
---

# <source name + one-line characterization>

<Core content + relevance to this project; the original provenance (arXiv/URL/date/
authors) as inline links.>
```

target template:

```markdown
# target — acceptance criteria for the output

## Purpose
(One paragraph: what this workspace decides, for whom, and where the boundaries are.)

## Current requirements
- (One checkable requirement per line.)

## Fulfilment map
- (Requirement → output file mapping, updated with each assembly.)
```

### Exactly three structured facts

1. **References** — inline markdown links in the card body. Forward only: a link points
   at the evidence or prior cards this card stands on, never at supporters. "Who cites
   me" is a projection-derived backlink, never written down. **Acyclic**: mutual
   references mean the two cards should merge, or one edge is a mistakenly written
   backlink — delete it.
2. **Tags** — single level, **at most one per card**, optional. A card that truly
   belongs to two tags is two cards: split it. No tag just means unclassified. Tags may
   be proposed by the human or assigned by the agent.
3. **Conflict** — the optional `conflicts: [<other card's id>]` in the **newer** card's
   frontmatter, declaring a judgment conflict with prior cards (written on the new card
   only, acyclic, same direction as references). The field lives exactly as long as the
   conflict: the human's adjudication removes it — archive the loser and the edge
   vanishes with the card; rewrite in place and the entry is deleted. The indexes'
   pending-conflict annotations derive from this field.

Everything else — backlinks, distances, coordinates, clusters, index groupings — is
derived and never enters the truth.

### Rendering contract — the engine's minimum

Everything projection needs. **This section is the engine; everything else in this file
is methodology**, freely reconfigurable per schema — one engine serves many thin
schemas, a new scenario is a new schema configuration rather than a