holocron/docs/adr/0028-research-doc-names-the-research-registry.md

Research doc: names one Research registry; entries without one declare none and a Basis:

Status: accepted (2026-09-21). Resolves #121. Extends ADR-0004's INFO level: it keeps INFO for the case where a check cannot run and promotes the case where it ran and found a mismatch.

Each entry in a skill's references/sources.md carries a Research doc: field. The spec (skill-author/references/create.md) says it names the plugin's research sources.md, the file whose ## H2 headings are the source slugs. The corpus did something else: 29 of 30 mismatched entries pointed at a research topic doc annotated (whole-document reference), and 6 values were not a single path (comma-separated lists and shell brace expansion, plus a semicolon pair in gitea-releases). Checks 7 and 8 of validate-provenance.sh look the slug up as an H2 in the named file, so 36 entries reported INFO and nothing failed. Measured by running the script over all 38 skill directories (27 with a references/sources.md, 11 without), since nothing else runs it over the corpus.

We decided that Research doc: names exactly one Research registry (the term is in CONTEXT.md), as the spec always said. Slug-to-H2 lookup in the registry is the only provenance link that can be verified deterministically; a topic doc has no per-source H2 to check against. A link to the topic doc that digested a source stays as free-text annotation and is not checked.

Considered options

Q1 — what Research doc: refers to.

• (a) The Research registry (chosen). Check 7 stays as designed (check 8 is retired, see Q6); the 29 entries repoint mechanically.
• (b) The topic docs a source fed into (rejected). Matches what the authors wrote, and is arguably the more useful pointer for a reader. Rejected because it changes the spec and the checker, and the slug check has nothing to run against.
• (c) Both, as two fields (rejected). Doubles the schema for a link nobody gates on.

Q2 — how an entry with no registry declares that honestly.

• (a) Research doc: none plus a Basis: field (chosen). Basis: takes repeated bullets of repo paths (ADRs, core/instructions/*.md, a live example) and is checked for existence only. research_doc_is_none already parses none, and git-workflow already writes it. Same shape as #111: there was no honest way to declare the truthful thing.
• (b) A non-corpus path stays legal in Research doc: (rejected). Leaves one field meaning two things depending on its value, and the INFO it produces can never be cleared.
• (c) Move non-corpus entries out of sources.md (rejected). A larger restructure than the issue warrants.

Lists are not needed under Q1(a): the four pc-author and pc-run brace expansions are one registry, and the gitea-releases pair collapses to one registry. Brace expansion and semicolon pairs are rejected outright, since nothing expands them in a markdown field.

Q3 — tier once the grammar is settled.

• (b) FAIL when the path resolves and check 7 finds a mismatch; INFO when the path does not resolve (chosen). Check 8 is not part of this: see Q6. A topic doc in Research doc: is now simply wrong and is a FAIL. An unresolvable path stays INFO because skill-file-structure.md treats sources.md pointers as development-time, and a deployed copy of a skill outside this repo will not have the research docs. This repo's own corpus is audited from the authoring source, where every path resolves.
• (a) Everything stays INFO (rejected). Under ADR-0004 INFO implies no action, which is how 36 mismatches went unnoticed.
• (c) Everything FAIL (rejected). Fails a correctly-provenanced skill audited from a deployed copy, which the file-structure exemption exists to prevent.

Q4 — enforcement. A corpus-wide sweep gate lands in the same change: a test or pre-push hook that runs validate-provenance.sh over every plugins/*/.apm/skills/*/ and fails on any FAIL. Deferring it was rejected because without a caller the FAIL tier is inert; nothing but check-scope-walkup-sync.sh (on fixtures) invokes the validator today.

Q5 — parser parity. parse_research_doc accepts the bullet spelling (- **Research doc:**) as parse_contributing_files already does, with a regression test. parse_status was removed from the validator during this change, so it gets no test. Included because it is the same failure shape as #111 and #118 (a parser returns "nothing found", the caller reads it as "nothing declared"), sits in the same file, and gitea-releases already writes the unhyphenated form.

Q6 — what happens to check 8. Found unsatisfiable during the migration, after Q3 was decided. Check 8 requires every extracted slug in the research doc to appear in the skill's sources.md. That worked while entries pointed at topic docs, and was dormant. Under Q1(a) the named file is a registry shared by many skills (git/sources.md backs seven), and nothing ties a registry slug to one skill, so every skill would fail permanently. The direction that matters, that each slug a skill lists exists in the registry, is already check 7.

• (a) Retire check 8 (chosen). Check 7 is the FAIL. Under registry semantics check 8 has no satisfiable meaning.
• (b) Keep it as an INFO (rejected). Recreates the noise ADR-0004 warns about: an observation with no action that every skill emits forever.
• (c) Redefine it as a registry-side coverage report (rejected for now). "Registry slugs that no skill uses" is a coherent check, but it is a report across all skills and separate work from this issue.

Q7 — Basis: paths that no longer exist. Found in the same migration: git-commits and git-workflow cite core/instructions/git.md and commits.md, deleted in 5deed07. An existence check on every Basis: bullet would fail them.

• (a) A bullet annotated (removed in <sha>) skips the existence check (chosen). The check stays for live paths, which is what catches a renamed ADR, and deletion becomes an explicit, auditable annotation. The annotation is anchored at the end of the value and the sha is 7-40 hex characters. Weakness: the annotation can be written on any bullet to avoid the check. Verifying the sha with git cat-file -e would close that; the user decided against it as over-engineering for three bullets, so the sha is format-checked only, not verified.
• (b) Basis: becomes free prose with no existence check (rejected). Gives up the one check that catches a renamed or moved ADR.
• (c) Drop those Basis: lines and keep none with a prose reason (rejected). Loses the machine-readable record of what the entry was drawn from.

Form: one path per bullet, - **Basis:** <path> repeated, not a header with sub-bullets.

Q8 — the lint entry with no verifiable basis. house-vale-3-15-2-repro in vale-config and vale-run said none and claimed six behaviours were "established by running it against purpose-built fixtures in this repo". No such fixture or test exists in the tree or in history: the entry was added in d1afdbe with no test files, and the only vale test ever deleted (4de5b6b) guards an unrelated E100. Under Q2 it FAILed for a missing Basis:.

• (e) Remove the entry and its source_keys citations (chosen, as the interim state). The stated basis was false, so there is nothing honest to declare. The behavioural rules stay in the skills; only the provenance claim goes. The gate needs no allowlist.
• (a) Basis: tests/test-vale-wrap.sh (rejected). Backs about one of six claims and overstates the rest.
• (b) Commit reproduction fixtures (chosen, supersedes the interim removal). The user decided to commit real Vale reproduction fixtures under plugins/lint rather than soften the wording. The house-vale-3-15-2-repro claim is restored only once it is backed by committed fixtures, and it names them via Basis: (with Research doc: none). Until they land, the claim stays absent.
• (c) Allow none without Basis: for "house-verified" entries (rejected). Reopens Q2 and gives an escape hatch for unverified claims.
• (d) Keep the entry and allowlist the two skills in the gate (rejected). Keeps a false claim in place and adds a list that can rot.

configuration-reference.md still says its rows were "reproduced against Vale 3.15.2"; that wording now has no provenance entry behind it and is left for a separate decision.

Consequences

• About 40 references/sources.md entries migrate: roughly 30 repoint from a topic doc to the registry, about 4 move to Research doc: none with a Basis: list (provider-adapter-author, git-commits org-commit-conventions, agentsmd-audit governance-secrets-hard-prohibition, git-workflow), and the gitea-releases pair collapses to one path.
• Basis: is a new field: create.md step 6, skill-file-structure.md and the validator's usage text must state it, and the validator must check that each listed path exists, except a bullet annotated (removed in <sha>). Each Basis: path is one bullet.
• Check 7 gains a FAIL tier for resolved-path mismatches. INFO remains for a path that does not resolve. A topic doc named in Research doc: is no longer legal: it is a FAIL, since a topic doc has no per-source ## H2 to check the slug against.
• Check 8 is retired: remove it from lib-provenance-skill.sh, its usage text and the tests, and drop its mention from skill-file-structure.md and create.md where present.
• The corpus-wide sweep is a new gate: register it in docs/spec/gates.md and .pre-commit-config.yaml. The corpus must be migrated in the same change or the suite goes red.
• The validator rejects an absolute path or one that escapes the repo with .. in Research doc: and Basis:, and rejects a Research doc: value with internal whitespace, backticks, or a comma list.
• Reversing this means re-migrating the same entries, which is why it is recorded.