Adopt schema-validated structured record reviews

.claude/skills/curate-yaml-record/SKILL.md

@@ -6,21 +6,181 @@ metadata:
   category: curation
   requires_database: false
   requires_internet: true
-  version: 1.0.0
+  version: 2.0.0
 ---
 
 # Curate one CommunityMech YAML record
 
+## Structured Review Output
+
+For every new review or audit, follow
+[docs/record-reviews.md](../../../docs/record-reviews.md) and
+[the local profile](../../../docs/record-review-profile.md).
+Capture exact targets and input hashes before judging, preserve this skill's
+native rubric, rule IDs, scores and evidence requirements, then author the
+structured assessment and run:
+
+```bash
+uv run python scripts/record_review.py inspect --targets /tmp/review-targets.yaml
+uv run python scripts/record_review.py validate /tmp/completed-review.yaml
+uv run python scripts/record_review.py save --content /tmp/completed-review.yaml
+```
+
+Choose session-unique temporary paths. Save authoritative YAML and derived
+Markdown under `reviews/structured/<timestamp>-<slug>/`; link both in the
+final response. This output contract supersedes prose-only report examples.
+A single record uses `kind: record`; batches declare exact selection,
+population, reviewed targets and limits. Categories also state boundary decisions.
+Every reviewed target must have an assessment. Keep P1-P4 and other native
+severity/rule information with a justified common severity, and metric definitions,
+scales and denominators. Do not infer scientific approval from a native score.
+
+Raw provider drafts and deterministic validator/scan reports are diagnostic
+inputs, not completed scientific reviews. Use `scientific_review: false`
+for deterministic-only or provenance-only assessments; mark required unavailable
+checks and incomplete coverage explicitly. A valid bundle does not change native
+status, clear release holds, authorize edits, or append curation history.
+For audit-only requests, stop after assessment and persistence; any application
+steps below require curation intent.
+
 Produce a defensible community or taxon record and an explicit account of what
 is supported, corrected, missing, and genuinely unknown. Search results and raw
 research reports are leads; only inspected sources can support a claim.
 
+## Shared Contract
+
+<!-- canonical:begin the-contract -->
+Produce a defensible record and an explicit account of four things: what is
+**supported**, what was **corrected**, what is **still unresolved**, and what is
+**genuinely unknown**. The last two are different — a gap you searched for and
+could not close is a finding; a gap you did not look at is not.
+
+**One target.** Resolve exactly one record before touching anything. If a label
+matches several, or a request names a family rather than a member, stop and
+disambiguate. Silently substituting a similar record is the error that no later
+check catches, because everything downstream is then correct about the wrong
+thing.
+
+**Audit preserves scientific inputs. Curation authorises edits to the named
+record only.** A review or audit request changes no scientific record, status,
+or curation history. It does save a new timestamped structured review through
+`docs/record-reviews.md` and the native rubric in `docs/record-review-profile.md`.
+A curate, improve, complete, correct or add-evidence request authorises local edits to that record and the smallest
+maintained path its provenance requires — not to neighbours, not to whatever
+else looked wrong on the way.
+
+**Search results are leads. Only an inspected source supports a claim.** A
+search hit, a deep-research report, a rendered page, and a generated artifact are
+each somewhere to look, and none is evidence. Evidence is text you read in the
+source, attached to the narrowest assertion it actually supports.
+<!-- canonical:end the-contract -->
+
+## Shared Boundaries
+
+<!-- canonical:begin boundaries -->
+- **A generated artifact is never the fix.** Pages, merged products, exports and
+  derived indexes are outputs. Correct the input or rule that owns the value and
+  regenerate; patching the output makes it look right once and diverge on the
+  next build.
+- **No outbound action without explicit authorisation for that action.** Do not
+  launch paid research, contact an author, or create or edit a GitHub issue, PR
+  or comment because curation seemed to call for it. Authorisation to curate a
+  record is not authorisation to spend or to speak.
+- **Absence is not evidence of falsity, and coverage is not a goal.** Never
+  infer that an unstated optional property is false. Never fill an optional
+  slot to make the record look more complete. An empty field the source does
+  not address is correct.
+- **Search before declaring anything absent — and search past `.gitignore`.**
+  Before treating a record, evidence source, decision row or overlay as missing,
+  search for its identifier, label and slug with an ignore-independent tool
+  (`rg --no-ignore --hidden`, `grep -r`, or `find`). Ordinary search skips
+  ignored files, so an ordinary miss is a search over a subset, not a result.
+- **Preserve unrelated work.** Use a branch, and a separate worktree when the
+  checkout is dirty or occupied by something else.
+<!-- canonical:end boundaries -->
+
+## Shared Evidence Standard
+
+<!-- canonical:begin evidence-standard -->
+- Each claim is its own object. A definition, an example, a relation and a
+  mechanism edge are separate assertions; attach a source to the narrowest one
+  it supports, never to the record as a whole.
+- Resolve every DOI, PMID and CURIE, and read enough of the source to establish
+  support for the *exact* claim and scope. A matching string from the wrong
+  paper, or an unrelated sentence from the right one, is not support.
+- A snippet is short verbatim text from the source. Interpretation belongs in a
+  notes field, never inside the quotation.
+- **The kind of source is part of the citation.** A database assertion, a
+  primary experiment, a review, a prediction and a search snippet are different
+  strengths of support. Cite each as what it is; never present a database row
+  or a review as if it were the primary study.
+- Association and prediction do not establish mechanism or causality. Do not
+  let a co-occurrence or a computed score become a mechanism edge.
+- **A near-miss is not a match.** Never ground to a CURIE or canonical label
+  because it looks plausible, and never use a broader or related term as an
+  exact identity. Unresolved stays unresolved, recorded as such, until a source
+  resolves it.
+- **Evidence about one thing supports a claim about that thing.** Do not
+  generalise one organism, strain, protein instance, construct or experiment
+  into a family-wide, universal or "optimal" claim. Scope inflation is the most
+  common way a true observation becomes a false record.
+- Keep conflicts. When sources disagree, record both and the disagreement; do
+  not resolve it by omission.
+- A bounded search that found nothing is a result. Report it as "not found,
+  searched X" rather than leaving the field silently empty.
+<!-- canonical:end evidence-standard -->
+
+## Shared Write Contract
+
+<!-- canonical:begin writing-back -->
+**Write only through the path that preserves formatting and records history.**
+Never hand-edit a curated YAML with a text editor or a generic dump: canonical
+key order, quoting and derived metadata are what make the corpus diffable, and a
+dump destroys them in one save.
+
+Repositories in this fleet do this in three different, equally correct ways, and
+which one applies is a property of the corpus:
+
+- **Direct guarded write** — a narrowly scoped mutator loads the record, asserts
+  its identity, changes only the reviewed nodes, appends a curation event, and
+  writes through the repository's validated writer.
+- **Registered editor** — no generic writer exists on purpose; in-place changes
+  use text-preserving operations through an editor that is registered and
+  behaviourally tested, and the writer audit rejects anything else.
+- **Regenerate from inputs** — the record is a build product. The fix goes into
+  the decision row, term request, overlay or source inventory that owns the
+  value, and the record is regenerated; the YAML is never edited directly.
+
+The section below says which one this repository uses and names the exact
+functions or files. Do not guess from a sibling.
+
+Inspect the diff before committing. Whole-file presentation churn — reordered
+keys, requoted strings, a hundred lines changed to alter one value — means the
+write path was bypassed; abandon and repair rather than commit it.
+<!-- canonical:end writing-back -->
+
+## Shared History And Attribution
+
+<!-- canonical:begin history-and-attribution -->
+- Use `curator="claude"` when no curator identity was supplied. **Never
+  attribute an agent's judgement to the user.** The history entry is a record
+  of who decided, and it will be read when the decision is questioned.
+- Mark LLM assistance where the schema records it.
+- **Do not append a history event when nothing substantive changed.** A
+  no-op event is noise that makes real events harder to find.
+- The history entry describes the actual diff. If the corpus derives status or
+  history from inputs, never set them directly — change the input.
+- A REVIEWED status means a human reviewed it. Do not invent one, and do not
+  promote to it on the strength of an agent pass.
+<!-- canonical:end history-and-attribution -->
+
 ## Boundaries
 
 - Resolve one target under `kb/communities/`, `data/isolates/`, or `kb/taxa/`.
   If a name matches several communities, experiments, or taxon records, stop
   and disambiguate before editing.
-- An audit/review request is read-only. Curate, improve, complete, correct, or
+- Audit/review preserves scientific inputs and saves a new structured review.
+  Curate, improve, complete, correct, or
   add-evidence requests authorize local edits to the named record and the
   smallest necessary history/generated-product paths.
 - Do not generalize a strain pair, enrichment, synthetic consortium, or

.claude/skills/evidence-curation/SKILL.md

@@ -10,6 +10,37 @@ tags: [evidence, snippets, literature, pmid, doi, references, repair, curation]
 
 # Evidence Curation Skill
 
+## Assessed Review Handoff
+
+For an evidence review or audit, delegate the final assessment to
+[review-communities](../review-communities/SKILL.md), following
+[docs/record-reviews.md](../../../docs/record-reviews.md) and
+[the local profile](../../../docs/record-review-profile.md).
+Use the registered review-communities route as the saved `skill`; preserve
+per-record P1-P4 findings, both native scores, and assertion-level evidence.
+For each interaction or causal edge keep participants, direction, mechanism,
+experimental context, exact source locator and inspected verbatim snippet.
+Distinguish abstract, full text and supplementary evidence.
+
+Extraction, network checks and repair suggestions are diagnostic inputs, not
+completed scientific review or snippet approval. A deterministic-only
+assessment uses `scientific_review: false`. No producer draft may be promoted
+without actual source assessment. Missing evidence remains a scoped gap.
+Save final assessed YAML plus derived Markdown under
+`reviews/structured/<timestamp>-<slug>/` and link both:
+
+```bash
+uv run python scripts/record_review.py inspect --targets /tmp/evidence-targets.yaml
+uv run python scripts/record_review.py validate /tmp/completed-evidence-review.yaml
+uv run python scripts/record_review.py save --content /tmp/completed-evidence-review.yaml
+```
+
+Use session-unique temporary paths. Audit-only requests run no repair/apply
+commands and change no scientific records, status or history. The repair
+workflows below require explicit curation intent and the native guarded writer.
+Paid/LLM research or repair additionally requires explicit authorization;
+the assessment handoff does not invoke or recreate a research producer.
+
 ## Overview
 
 CommunityMech community records require evidence-backed claims: each interaction,
@@ -22,7 +53,7 @@ This skill covers the full evidence lifecycle:
 - **Review** — manual literature review and snippet approval
 - **Validate** — confirm evidence passes schema and reference checks
 
-**Run from `CommunityMech/CommunityMech/` directory.**
+**Run from the repository root.**
 
 ---
 
@@ -65,7 +96,7 @@ python scripts/apply_pmc_conversions.py
 # 5. Normalize reference formats (PMID: prefix, DOI capitalization)
 python scripts/fix_reference_formats.py
 
-# 6. Run review-communities to check remaining issues
+# 6. Network diagnostics only; then hand off to review-communities above
 communitymech audit-network
 ```
 
@@ -77,13 +108,8 @@ communitymech audit-network
 # Extract snippets from a PDF
 python scripts/curate_evidence_with_pdfs.py --pdf path/to/paper.pdf
 
-# Quick literature review for a specific community
-python scripts/quick_literature_review.py --community CommunityMech:000042
-
-# Full literature review with scoring
-python scripts/review_literature.py --community CommunityMech:000042
-
-# Apply suggested fixes after review
+# Assess extracted evidence through review-communities and the common saver.
+# Apply suggested fixes only after separately authorized curation review.
 python scripts/apply_suggested_snippets.py
 python scripts/apply_suggested_fixes.py
 ```
@@ -102,8 +128,6 @@ python scripts/apply_suggested_fixes.py
 | `scripts/apply_pmc_conversions.py` | PMC ID → PMID conversion |
 | `scripts/handle_special_references.py` | Edge cases (preprints, books, datasets) |
 | `scripts/curate_evidence_with_pdfs.py` | PDF-backed snippet extraction |
-| `scripts/quick_literature_review.py` | Fast per-community literature scan |
-| `scripts/review_literature.py` | Full literature review with scoring |
 | `scripts/analyze_literature_report.py` | Analyze review results |
 | `scripts/analyze_review_cases.py` | Categorize review case types |
 | `scripts/apply_suggested_snippets.py` | Apply auto-suggested snippet text |
@@ -141,11 +165,13 @@ All API calls respect rate limits; no API key required for PubMed.
 Always run validation after evidence changes:
 
 ```bash
-# Full schema + reference validation
+# Network diagnostics; this is not full schema + reference validation
 communitymech audit-network
 
-# Or use review-communities skill
-# (checks evidence references as part of full QA)
+# Separate schema and reference checks for the actual reviewed record:
+just validate-strict <record-path>
+just validate-references-explained <record-path>
+# Then use review-communities for the assessed review and shared persistence.
 ```
 
 ---
@@ -163,8 +189,9 @@ communitymech audit-network
 - May be preprint DOI — use `handle_special_references.py`
 
 **"Missing evidence entirely":**
-- Run `quick_literature_review.py` to find candidate papers
-- Or use LLM: `communitymech repair-network --community CommunityMech:XXXXXX`
+- Hand off to `review-communities` to assess inspected sources or record a gap.
+- Do not run paid/LLM producers without explicit authorization. Suggestions
+  remain unassessed leads until the source and exact assertion are checked.
 
 ---
 

.claude/skills/review-communities/SKILL.md

@@ -9,6 +9,38 @@ created: 2026-03-16
 
 # Review Communities Skill
 
+## Structured Review Output
+
+For every new review or audit, follow
+[docs/record-reviews.md](../../../docs/record-reviews.md) and
+[the local profile](../../../docs/record-review-profile.md).
+Capture exact targets and input hashes before judging, preserve this skill's
+native rubric, rule IDs, scores and evidence requirements, then author the
+structured assessment and run:
+
+```bash
+uv run python scripts/record_review.py inspect --targets /tmp/review-targets.yaml
+uv run python scripts/record_review.py validate /tmp/completed-review.yaml
+uv run python scripts/record_review.py save --content /tmp/completed-review.yaml
+```
+
+Choose session-unique temporary paths. Save authoritative YAML and derived
+Markdown under `reviews/structured/<timestamp>-<slug>/`; link both in the
+final response. This output contract supersedes prose-only report examples.
+A single record uses `kind: record`; batches declare exact selection,
+population, reviewed targets and limits. Categories also state boundary decisions.
+Every reviewed target must have an assessment. Keep P1-P4 and other native
+severity/rule information with a justified common severity, and metric definitions,
+scales and denominators. Do not infer scientific approval from a native score.
+
+Raw provider drafts and deterministic validator/scan reports are diagnostic
+inputs, not completed scientific reviews. Use `scientific_review: false`
+for deterministic-only or provenance-only assessments; mark required unavailable
+checks and incomplete coverage explicitly. A valid bundle does not change native
+status, clear release holds, authorize edits, or append curation history.
+For audit-only requests, stop after assessment and persistence; any application
+steps below require curation intent.
+
 ## Overview
 
 The **Review Communities** skill provides quality assurance for ontology-mapped microbial
@@ -101,7 +133,8 @@ source attribution (CultureMech vs community_curated).
 
 ### 6. Full Quality Control
 ```bash
-just qc   # validate-all + validate-terms-all + validate-references-all + lint + test
+just qc   # native schema/cross-field, taxonomy, terms, lint and test gates
+just qc-references  # separate reference/evidence check; may need network access
 ```
 
 ### Claude Code-Assisted Review
@@ -154,7 +187,7 @@ Issues are graded by priority. Full definitions (checks, impact, fixes) are in
 The skill drives existing `just` recipes:
 
 ```
-qc: validate-all validate-terms-all validate-references-all lint test
+qc / qc-references                                               # distinct gates
 validate[-all] / validate-terms[-all] / validate-references[-all]   # validation
 audit-network / check-network-quality                               # network integrity
 link-media-dry / link-media / link-media-report                     # growth media

.claude/skills/review-communities/reference/execution-protocol.md

@@ -99,6 +99,13 @@ for line in validation_output:
 
 ### Step 4: Report Issues to User
 
+Save the assessed observation using [docs/record-reviews.md](../../../../docs/record-reviews.md)
+and `uv run python scripts/record_review.py save --content /tmp/completed-review.yaml`
+after input inspection and validation. Use session-unique temporary paths.
+The template below is a diagnostic presentation example, not the final output
+contract. A review-only invocation ends after saving its structured bundle;
+the apply/history steps require separately authorized curation.
+
 ```markdown
 ## Validation Report: {community_name}
 

.claude/skills/review-communities/reference/metrics-and-reports.md

@@ -92,6 +92,13 @@ def calculate_validation_score(validation_summary):
 
 ## Validation Reports
 
+The examples below illustrate native metrics and diagnostic summaries.
+New final reviews follow [docs/record-reviews.md](../../../../docs/record-reviews.md)
+and use the shared saver for YAML plus derived Markdown. Preserve both score
+definitions above in assessment metrics; keep findings and evidence per record
+and per interaction/causal edge. A high score or a clean network scan is not
+scientific approval.
+
 ### Text Report Format
 
 ```markdown