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 actor who transcribed or drafted the entry text (human or agent, per seed/CoulombResearchKernel.md §2.1/§4), written as human:<name> or agent:<name>,
• the date that text was added,
• for agent-drafted entries, the model/toolchain if relevant.

On a claim entry, that drafter/transcriber relation is the Added by field. Added by means who wrote the words of the entry. It does not mean who originated the position, and it does not mean who approved the commit. Approval is a different relation: a human can retain commit approval without being the source of the proposition and without being the drafter (manuscript.md §7 for CR-000). Do not record approval in Added by.

A claim entry must also record Position origin. seed/CoulombResearchKernel.md §4 treats "source asserts P" and "actor asserts P" as non-interchangeable, so a single drafter field cannot stand in for both. Use one of:

• source: <path> — the position is a transcription or close restatement of that source. Name the source. Do not attribute the position to the transcriber.
• actor: <id> — a Coulomb actor originated the position in this entry, rather than taking it from a source. This is "actor asserts P". Use it only when the record supports origination, not as the default for whoever typed the file.
• mixed — name the source the position comes from and the actor who added an operational reading the source does not already state. Say which is which.
• unrecorded — the files do not support the distinction. Do not guess.

Do not overwrite Added by, and do not delete a recorded origin, when a later actor edits an entry. Name that later actor and date on the wording they added, and append the change to revision-log.md.

Evidence and criticism entries are not claim positions. Their Added by or Critic field likewise names who wrote that entry. When an evidence entry draws on a source, its Source field records that source; it does not make the drafter the origin of a claim.

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.