coulomb-research/docs/ResearchArtifactConvention.md

# Research Artifact Convention

## Purpose

This document defines the identifier, file-layout, and provenance conventions
for Coulomb-native research artifacts: research programs, papers, and their
paper-local claims, evidence, and criticism. It implements the M0 exit
criterion in `seed/CoulombResearchMilestonePlan.md` ("Coulomb Research can
register and evolve one internal research paper with versioned artifacts and
explicit publication state").

The design rationale for these object types lives in the seed documents; this
file is the concrete, implementation-facing convention, not a restatement of
the kernel. See:

- `seed/CoulombResearchKernel.md` — why Paper, Program, Claim, and Evidence
  are derived views over the kernel primitives (Actor, Proposition, Evidence,
  Action, Resource), not kernel primitives themselves.
- `seed/PublicationInterface.md` — publication stages (P1/P2/P3) and the
  publication adapter.
- `seed/CoulombResearchMilestonePlan.md` — the milestone sequence this
  convention supports (M0–M5 in particular).

## 1. Identifier Namespaces

Coulomb Research uses three distinct, non-interchangeable identifier
namespaces. An identifier from one namespace must never be reused as, or
confused with, an identifier from another.

| Namespace | Pattern | Example | Scope | Meaning |
| --- | --- | --- | --- | --- |
| Research program | `RP-NNN` | `RP-000` | facility-wide | A research program: a sustained line of inquiry that hosts one or more papers. |
| Paper | `CR-NNN` | `CR-000` | facility-wide | A single Coulomb-native research paper (manuscript + claims + evidence + criticism + publication state), belonging to exactly one program. |
| Paper-local object | `CR-NNN-<T><NNN>` | `CR-000-C001` | scoped to one paper | A claim, evidence item, or criticism item addressable within one paper. |
| Implementation work | `CR-WP-NNNN` | `CR-WP-0002` | facility-wide | A workplan implementing repository/software infrastructure, tracked in `workplans/`. |

**These namespaces are disjoint by construction:**

- `RP-NNN` and `CR-NNN` both use the `CR`/`RP` prefixes but are never
  zero-padded to the same width by coincidence — programs use `RP-`, papers
  use `CR-`. A number appearing in both (e.g. `RP-000` and `CR-000`) refers
  to *different objects that happen to share a sequence position*, not the
  same object. `RP-000` is the "Researching Research" program; `CR-000` is
  Paper Zero, its first paper.
- `CR-NNN` (a paper) and `CR-WP-NNNN` (a workplan) are visually similar but
  serve different purposes: a paper is a research artifact with epistemic
  content (claims, evidence, a publication stage); a workplan is
  implementation bookkeeping (tasks, status, a State Hub UUID). `CR-000` is
  never itself the subject of a `CR-WP-*` task's *content* — a workplan may
  reference a paper ID in its text, but the paper's own claim/evidence/
  criticism ledger lives in the paper's own files, not in a workplan.
  Numbering is independent: `CR-000` and `CR-WP-0002` do not need to align
  and will not stay aligned as each sequence grows.

### 1.1 Paper-local object IDs

Within a single paper, addressable claims, evidence items, and criticisms
use the pattern `<paper-id>-<T><NNN>`, where `<T>` selects the object type:

| Type letter | Object | Example |
| --- | --- | --- |
| `C` | Claim | `CR-000-C001` |
| `E` | Evidence | `CR-000-E001` |
| `X` | Criticism | `CR-000-X001` |

`NNN` is a zero-padded, monotonically increasing sequence, scoped per type
per paper (so `CR-000-C001`...`CR-000-C00N` and `CR-000-E001`...`CR-000-E00M`
number independently). IDs are never renumbered or reused after being
assigned, even if the underlying claim is later withdrawn or superseded —
withdrawal is recorded as a state change (see §4), not a deletion.

Cross-references between paper-local objects and program- or paper-level
objects (e.g. "evidence `CR-000-E003` bears on claim `CR-000-C002`") are
written inline in `evidence.md` and `criticism.md` using the full ID, so a
reference resolves unambiguously even outside the file's own paper context.

## 2. File Layout

```text
research/
├── programs/
│   └── RP-000-researching-research/
│       ├── INTENT.md          # why this program exists, its scope
│       ├── questions.md       # the open questions the program tracks
│       └── papers/
│           └── paper-000/     # directory name mirrors the paper id (CR-000 → paper-000)
│               ├── README.md          # paper summary + links to the other files
│               ├── manuscript.md      # the paper text/outline
│               ├── claims.md          # CR-000-C001, CR-000-C002, ...
│               ├── evidence.md        # CR-000-E001, ...; each entry states what it bears on
│               ├── criticism.md       # CR-000-X001, ...; each entry states what it challenges
│               ├── revision-log.md    # dated log of substantive manuscript revisions
│               └── publication.yaml   # publication stage/state metadata (§3)
└── registry/
    └── papers.yaml         # facility-level index of all papers (id, program, stage, version, status)
```

Rules:

- A program directory is named `<RP-id>-<slug>`; a paper directory under
  `papers/` is named `paper-<NNN>` matching the numeric suffix of its
  `CR-NNN` ID (so `CR-000` lives at `.../papers/paper-000/`). The directory
  name is a filesystem-safe mirror of the ID, not an independent identifier;
  the authoritative ID is the `paper_id` field in `publication.yaml`.
- A paper belongs to exactly one program directory. If a paper's research
  trajectory later spans multiple programs, that is a program-design
  decision to make explicitly (e.g. via a new workplan), not an implicit
  file move.
- The facility-level `research/registry/papers.yaml` is the single
  authoritative index of which papers exist; see §5.

## 3. Publication Metadata

Every paper carries a `publication.yaml` recording its publication stage per
`seed/PublicationInterface.md` §4. At M0/M1, every paper starts and remains
at stage P1 (internal circulation):

```yaml
paper_id: CR-000
research_program: RP-000
publication_stage: P1
publication_state: internal-circulation
version: "0.1"
```

**P1 internal-only metadata is distinct from "the manuscript is finished."**
`publication_stage: P1` / `publication_state: internal-circulation` describes
*who may see the artifact and under what expectations* (collaborator
review, mutable revisions, no venue-compliance obligation — see
`seed/PublicationInterface.md` §4). It says nothing about whether the
manuscript content itself is a complete draft, an outline with labeled gaps,
or a full v0.1. A paper skeleton created under M0 (outline manuscript,
explicitly labeled conjectures, no fabricated evidence) is legitimately
`publication_state: internal-circulation` from the moment it exists in the
repository — internal-circulation is the *default resting state* for
work-in-progress, not a milestone reached after the draft is polished. A
distinct, later, and heavier step — an actual internal circulation *release*
(e.g. notifying collaborators, per M7) — is a publication *event* layered on
top of this state, not implied by the state field alone. This convention
does not define that release workflow; it is out of scope for M0.

Advancing a paper beyond P1 (to P2 external preprint or P3 venue candidate)
follows `seed/PublicationInterface.md` §4 and is out of scope for M0/M1.

## 4. Provenance

Every claim, evidence item, and criticism entry should record, inline in its
own file entry, at minimum:

- the authoring actor (human or agent, per `seed/CoulombResearchKernel.md`
  §2.1/§4), written as `human:<name>` or `agent:<name>`,
- the date it was added,
- for agent-authored entries, the model/toolchain if relevant.

This is a lightweight, file-embedded application of the kernel's provenance
requirement (`seed/CoulombResearchKernel.md` §4) — it does not introduce a
database or a separate provenance object. State changes (a claim marked
contested, superseded, or withdrawn; a criticism marked resolved) are
appended to `revision-log.md` with a date and actor, never edited in place
by deleting the prior state.

## 5. Registry

`research/registry/papers.yaml` lists every registered paper with the
minimal fields needed to discover and cross-check it, following the M5
example format in `seed/CoulombResearchMilestonePlan.md`:

```yaml
papers:
  - id: CR-000
    title: >
      Coulomb Research: A Minimal Self-Improving Architecture
      for Human-AI Co-Creation Science
    program: RP-000
    stage: P1
    version: "0.1"
    status: internal-circulation
    path: research/programs/RP-000-researching-research/papers/paper-000/
```

The registry is Git-versioned and hand-maintained at this milestone (per the
M5 design principle: no database until the research process demonstrates a
need for one). A registry entry's `stage`, `version`, and `status` fields
must agree with the corresponding paper's own `publication.yaml`; validating
that agreement is part of registering or updating any paper (see
`workplans/CR-WP-0002-research-facility-skeleton.md` task T03).

## 6. Validation

`scripts/validate_research_registry.py` checks that `research/registry/papers.yaml`
parses, that paper ids are unique, that each entry's path resolves and
contains a `publication.yaml`, that registry `stage`/`version`/`status`
agree with each paper's own `publication.yaml`, and that relative Markdown
links inside a paper's own files resolve. It is a single script, not a test
framework or package, because the artifact set at this milestone is a
handful of small, hand-authored files — a proportionate validation tool for
that scale. Its only dependency is PyYAML. Run it with:

```bash
python3 scripts/validate_research_registry.py
```

Run this after any change to the registry or to a paper's `publication.yaml`
or Markdown files, and before running the repository's Repo Manager sync.

## 7. What This Convention Does Not Cover

Consistent with the M0 non-goals, this convention does not define: a
database or service layer, an external publication workflow, a forum, a
reputation or scoring mechanism, or automated ID assignment tooling. IDs are
assigned by the author registering the artifact, by hand, following the
patterns above.