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

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):

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:

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:

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.