# 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-` | `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 `-`, where `` 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 `-`; a paper directory under `papers/` is named `paper-` 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:` or `agent:`, - 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.