Repo tidy-up from 2026-09-28 feedback (part 8/9)

.claude/skills/mapping-audit/SKILL.md

@@ -34,7 +34,7 @@ wants to know if any existing mapping is now stale.
   CL ID's current marker-axiom support as `confirmed` (directly asserted),
   `inferred_only`, or `no_marker_axiom`, from
   `reports/cl_pro_relationships.tsv`.
-- `reports/literature/*.md` and `reports/pro_marker_species_support.tsv` — the
+- `literature/evidence.tsv` (prefer `verified = yes` rows) and `reports/pro_marker_species_support.tsv` — the
   literature side of the evidence a mapping might rely on, especially for
   species-specific marker claims.
 - `uv run soulcap-match --req-excl ... --ideal-excl ... --req-pheno ...

.claude/skills/pro-marker-species-support/SKILL.md

@@ -30,11 +30,14 @@ axioms are added.
   already carries a species qualifier (`(mouse)`/`(human)`). Run via
   `uv run python -c "..."` or a short driver script — not a CLI (deliberately;
   see the module docstring).
-- `reports/literature/*.md` — the Milestone 2 literature reports. **Check
-  these first, always.** They already contain verbatim-quoted, hook-validated
-  evidence for 7 cell families (NK, ILC, DC, iNKT, T cell, B cell, gdT/MAIT),
-  and reusing a quote from here is strictly better than a fresh search: it's
-  already vetted, and it's free.
+- `literature/evidence.tsv` — the Milestone 2 evidence table (one row per
+  cell type, marker and quote). **Check it first, always.** It covers 7 cell
+  families (NK, ILC, DC, iNKT, T cell, B cell, gdT/MAIT). Prefer rows with
+  `verified = yes` (quote matched exactly in the paper's full text); treat
+  `no` rows as unconfirmed and don't reuse them without checking the paper.
+  Reusing a verified quote is strictly better than a fresh search. The
+  original narrative reports are archived in
+  `archive/2026-09_literature_narratives/` for provenance only.
 - `data/citation_mgr.csv` (synced Citation Mgr tab) — per-family seed papers
   for families without an M2 report yet (as of this run: basophil,
   granulocyte, mast cell, monocyte, neutrophil, MDSC).
@@ -72,9 +75,10 @@ refreshing rather than re-running everything.
 
 For each pair (or each CL cell type's group of pairs, sharing a seed set):
 
-1. **Search the relevant `reports/literature/*.md` file** for the marker's
-   CD synonym or PR label. If a verbatim blockquote already covers it, reuse
-   that quote and citation directly — `evidence_source: m2_literature_report`.
+1. **Search `literature/evidence.tsv`** (`marker_token`, `cell_type_label`)
+   for the marker's CD synonym or PR label. If a `verified = yes` row covers
+   it, reuse that quote and citation directly —
+   `evidence_source: m2_literature_report`, `source_ref: literature/evidence.tsv#<evidence_id>`.
 2. **If Asta is reachable and no M2 coverage exists**, run `citation-traversal`
    seeded from `data/citation_mgr.csv`'s row for that family —
    `evidence_source: citation_traversal`.
@@ -124,7 +128,7 @@ Append to `reports/pro_marker_species_support.tsv`
 | `evidence_source` | `m2_literature_report` / `citation_traversal` / `europepmc_search` / `none`. |
 | `citation` | Author/year/PMID/DOI, plus a trailing `-- ` caveat clause when the quote's context doesn't exactly match the pair's cell type/subset (e.g. a naive-T marker's only evidence coming from a Treg paper) — say so rather than let the row imply a cleaner match than it is. |
 | `quote` | The verbatim substring itself. |
-| `source_ref` | `reports/literature/<file>.md` for M2 reuse, an EuropePMC article URL for a fresh search, or `reports/citation_traversal/<run_id>/` for a traversal — or, for `insufficient_evidence`, a one-line note on what was tried. |
+| `source_ref` | `literature/evidence.tsv#<evidence_id>` for M2 reuse (older rows cite `archive/2026-09_literature_narratives/<file>.md`), an EuropePMC article URL for a fresh search, or `reports/citation_traversal/<run_id>/` for a traversal — or, for `insufficient_evidence`, a one-line note on what was tried. |
 
 ## Step 5 — flag real findings
 

.claude/skills/roadmap-status-sync/SKILL.md

@@ -24,7 +24,7 @@ changes a milestone's completion state.
 - `uv run soulcap-sync` — re-pull the Google Sheet before checking anything
   that depends on its current column set (this is a network call and
   overwrites the gitignored `data/` cache — safe, but mention you're doing it).
-- File/row counts under `marker_mappings/`, `reports/`, `reports/literature/`.
+- File/row counts under `marker_mappings/`, `reports/`, `literature/`.
 - `gh issue view <N>` — for the CL term corrections table, whose "Status"
   column tracks upstream `obophenotype/cell-ontology` issues that this repo
   doesn't control the resolution of.
@@ -37,7 +37,7 @@ disk, every time:
 | Milestone | Evidence to check | How to read it |
 |---|---|---|
 | M1 — marker → protein → gene | `marker_mappings/marker_protein_gene.csv` exists and has rows | Empty/missing → ⬜. Has rows but visibly incomplete (spot-check a few marker tokens from `data/marker_combinations.csv` against it) → 🟡. Covers essentially all distinct tokens → ✅. |
-| M2 — literature support | Count `reports/literature/*.md` files against the distinct `Category` values in `data/citation_mgr.csv` (re-sync first if `data/` looks stale) | 0 files → ⬜. Some but not all categories covered → 🟡 (state the fraction, e.g. "8/14"). All categories covered → ✅. |
+| M2 — literature support | Count distinct `cell_type_label` families in `literature/evidence.tsv` against the distinct `Category` values in `data/citation_mgr.csv` (re-sync first if `data/` looks stale); also report how many rows are `verified = yes` | 0 files → ⬜. Some but not all categories covered → 🟡 (state the fraction, e.g. "8/14"). All categories covered → ✅. |
 | M3 — audit curated mappings | Whether the Google Sheet now has dedicated broad/exact-match and comment columns beyond today's `Type of Match` (assay-type, not CL-match-type), `OLS CL identifier`, and `CL Mapping Notes` — check the freshly-synced sheet's actual column headers, don't assume from the column *names* alone (`Type of Match` sounds relevant but is not the same field per the roadmap's own note) | Columns still absent → stays ⛔, but if the `mapping-audit` skill has since made a drift/evidence-based audit possible without those columns, say so explicitly rather than leaving it a flat "blocked with nothing happening." | 
 | M4 — candidate mappings | Row count in `reports/candidate_cl_mappings.sssom.tsv` (minus header) against total rows in `data/marker_combinations.csv` (minus header) | Partial coverage → 🟡 with the fraction. All SOULCAP rows covered (including documented "no reasonable match" cases logged in `gaps.tsv`, which count as resolved, not missing) → ✅. |
 | CL term corrections table | `gh issue view <N>` for each row's linked repo issue, and the upstream `obophenotype/cell-ontology` issue if linked | If the upstream issue is closed/merged, the table's "Status" cell is stale — update it. |
@@ -72,7 +72,7 @@ same way when an upstream issue has moved.
 - M2's category list comes from `data/citation_mgr.csv`'s `Category` column,
   which mixes true cell-type families (NK cell, B cell, monocyte, ...) with at
   least one cross-cutting method category (`immunoprofiling`) that doesn't map
-  to a single `reports/literature/*.md` file — don't count it against M2's
+  to a single evidence family — don't count it against M2's
   denominator; use judgment on any other ambiguous category the same way.
 - A "done" `data/` count is only as fresh as the last `uv run soulcap-sync` —
   always re-sync before trusting M2/M3/M4 numbers if the last sync date is

.claude/skills/soulcap-cl-matching/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: soulcap-cl-matching
-description: Propose a Cell Ontology (CL) match for a SOULCAP cell type (one, several, or all of them) using both marker-axiom scoring and name-based lexical search, cross-checking the two before trusting either, and writing the result into reports/candidate_cl_mappings.md with rationale and evidence. Invoke when asked to map/match a SOULCAP cell type to CL, propose a CL ID, or extend Milestone 4 candidate mappings.
+description: Propose a Cell Ontology (CL) match for a SOULCAP cell type (one, several, or all of them) using both marker-axiom scoring and name-based lexical search, cross-checking the two before trusting either, and recording the result as a row in mappings/curated_mappings.tsv (then regenerating reports with soulcap-sssom) with rationale and evidence. Invoke when asked to map/match a SOULCAP cell type to CL, propose a CL ID, or extend Milestone 4 candidate mappings.
 ---
 
 You propose SOULCAP → Cell Ontology (CL) mappings the way they were actually
@@ -109,32 +109,44 @@ because it needed an OR-group marker check
 
 ## Step 4 — write the result
 
-Append an entry to `reports/candidate_cl_mappings.md` following the existing
-format (one `##` section per cell type or closely related family):
+Record the decision as a row in
+[`mappings/curated_mappings.tsv`](../../../mappings/curated_mappings.tsv), then
+regenerate the outputs:
 
-```markdown
-## <Abbreviation> — <Full Name>
-
-**SOULCAP definition:** <marker columns, briefly>
-
-| Field | Value |
-|---|---|
-| Proposed CL term | <label> |
-| Proposed CL ID | `CL:XXXXXXX` |
-| Match type | Exact / Broad |
-
-**Rationale:** <why this term, referencing marker matches AND/OR lexical
-agreement, and calling out anything that had to be verified by hand>
-
-**Evidence:** <marker→gene table entries, literature quotes if available from
-reports/literature/, `soulcap-match` rank/score>
+```bash
+uv run soulcap-sssom
 ```
 
-If a candidate is genuinely uncertain (e.g. the SOULCAP profile doesn't test
-a marker needed to distinguish two otherwise-equal CL candidates), say so
-explicitly — mark it **tentative** and name the alternatives, rather than
-picking one silently. See the `ILCp` entry in `candidate_cl_mappings.md` for
-the pattern.
+This rewrites `reports/candidate_cl_mappings.sssom.tsv`, the readable
+`reports/candidate_cl_mappings.md`, and the provenance sidecar. **Never edit
+`reports/candidate_cl_mappings.md` directly** — it is generated, and hand edits
+are overwritten on the next export. See [mappings/README.md](../../../mappings/README.md)
+for the column rules.
+
+- `subject_id`: the cell type's permanent `SOULCAP:SCnnnnnn` ID from
+  `mappings/soulcap_entities.tsv`. If the cell type has no entity row, stop and
+  ask; never invent or renumber IDs.
+- To change an existing proposal, edit its row; add a new row only for a
+  subject with no proposal yet.
+- `abbreviation`, `subject_label`: as in the entity registry.
+- `cl_id`, `cl_label`: verified via OLS4 (Step 3), exact label.
+- `match_type`: `Exact` (proposed equivalence), `Broad` (CL is broader),
+  `Narrow` (CL is narrower) or `Related`.
+- `uncertain`: set it (and name the alternatives in `note`) when the profile
+  can't distinguish between CL candidates. Don't pick one silently.
+- `review_status`: always `needs_review`. Only a human curator changes it.
+- `note`: the rationale — why this term, marker matches and/or lexical
+  agreement, and anything verified by hand. Include the `soulcap-match`
+  rank/score.
+- `lexical_evidence`, `literature_evidence`, `curator_evidence`: structured
+  evidence, kept separate. Literature evidence must be verbatim quotes with
+  PMID/DOI, citing rows of `literature/evidence.tsv` by `evidence_id` (prefer
+  `verified = yes`); leave it blank rather than invent a citation.
+- `evidence_source`: where the evidence lives (file path or URL).
+- Leave `evidence_override` blank; it is historical provenance only.
+
+Marker evidence (matches, contradictions, unknowns) is computed by
+`soulcap-sssom` from the source profile — don't write it by hand.
 
 ## Step 5 — flag anything wrong in either resource