light-citation

# Citation — stage 10

Make every author-used reference traceable, real, correctly identified, and
honestly connected to the claim it is supposed to support. Treat formatting,
metadata existence, publication-integrity facts, and semantic support as four
different questions.

Read [`citation-resource-map.md`](citation-resource-map.md) before a full
manuscript audit. Read
[`references/registry_contract.md`](references/registry_contract.md) before
producing or consuming the canonical registry. Read
[`references/locator_audit.md`](references/locator_audit.md) before judging
claim support.

## Stage contract

- Consume paper-writing's `light.paper_claims.v1`, exact claim/source locators,
  current claim text hashes, reviewer-bound citation-support hashes,
  manuscript, figures/tables, supplement, and reference candidates.
- Reuse literature-search provenance as input evidence; independently verify
  the references the author actually keeps.
- Emit `light.citation_registry.v1`, BibTeX, CSL JSON, source-level evidence,
  failure records, claim-edge review, citekey audit, and
  `light.findings.v1(producer=citation)`.
- Keep stage 10's only critical gate `citation_verify`: confirmed missing works
  and chimeric citations. Metadata conflicts, unavailable sources, claim
  relevance, formatting, and publication-update alerts are warn/skip.
- Fix citation failures inside stage 10. `ROUTES` has no key 10; never invent a
  back-edge.
- Hand `references.bib`, `citekey-audit.json`, registry and `delivery.json` to
  typesetting. Typesetting compiles and checks keys; it does not re-decide
  authenticity. `delivery.json` must declare `status` and per-deliverable
  `sha256:` hashes so typesetting can reject stale or edited handoffs.

## Non-negotiable rules

1. Never invent a reference, DOI, author, year, venue, citekey, locator or
   support verdict.
2. Never call a network failure, rate limit, 5xx, authentication failure, or
   index miss “this work does not exist.”
3. Assign `CONFIRMED-MISSING` only when DOI Registration Agency explicitly
   reports non-existence and Crossref plus DataCite both return 404/410.
4. Assign `CONFIRMED` only when registration metadata and at least one
   independent field source confirm the work. Otherwise retain
   `UNAVAILABLE` or `UNRESOLVED`.
5. Preserve every source's title/authors/year/venue/identifier value. Select
   canonical fields from the registration agency; never use fuzzy matching to
   overwrite the original citation.
6. Treat a real DOI paired with conflicting title/authors/year as a possible
   chimeric citation. Multi-core-field conflict is critical; one ambiguous
   field mismatch is a warning for manual review.
7. Read publication updates in the correct direction: the affected original
   carries Crossref `updated-by`; the notice carries inverse `update-to`.
8. Record retraction/correction/expression-of-concern facts and alerts, then
   hand integrity judgment and wording to research-ethics. Do not rebuild its
   ethics gate.
9. Never equate metadata confirmation or “A cites B” with “B supports claim
   C.” `SUPPORTS` requires a locator-backed semantic review.
10. Keep the core path local/free or public/no-key. OpenAlex and keyed
    Semantic Scholar are optional coverage enhancements; commercial managers,
    institutional databases, and browser plugins are never required.

## Execute the author workflow

### 1. Inventory every reference occurrence

Use the claim map, manuscript, figures/tables and supplement together:

```bash
python scripts/citation_registry.py \
  --claim-map claim_plan.json \
  --draft paper.tex \
  --figure figure_notes.md \
  --supplement supplement.md \
  --refs-spec citation_input.json \
  --out-dir citation-delivery
```

Preserve `claim_id`, exact claim, claim locator, artifact path, occurrence
locator, citekey and raw identifier. Use
[`templates/citation_input.json`](templates/citation_input.json) when the
project has no reference spec.

### 2. Normalize without erasing versions

Normalize DOI, arXiv, PMID, ISBN and URL. Deduplicate exact works. Keep arXiv,
accepted manuscript, versioned dataset and published DOI as explicit versions
under one work only when the inputs establish the relationship. If not
established, keep them separate and mark the relationship unresolved.

### 3. Verify with independent sources

```bash
python scripts/verify_refs.py \
  --spec citation_input.json \
  --self-author Smith \
  --out verify.json
```

Use Crossref or DataCite as the registration source. Use PubMed, Semantic
Scholar, or configured OpenAlex as the independent field source. Keep each
endpoint, HTTP status, outcome, timestamp and returned fields in
`source_evidence`，并保存实际参与判定的 normalized-field SHA-256。Crossref polite-pool
email、OpenAlex/Semantic Scholar key 只用于请求，绝不写入 endpoint、registry 或日志。

Interpret status exactly:

| Status | Meaning | Action |
|---|---|---|
| `CONFIRMED` | registration source + independent field source | eligible for canonical BibTeX/CSL |
| `CONFIRMED-MISSING` | DOI RA explicit non-existence + Crossref/DataCite 404 | critical; replace or delete |
| `UNAVAILABLE` | transport/rate/auth/5xx prevents lookup | retry or use another free source |
| `UNRESOLVED` | partial evidence or second source incomplete | investigate; do not call verified |

### 4. Resolve field conflicts and chimeras

Compare the author's cited title, authors and year against registration
metadata. Inspect `field_conflicts` source by source. Keep the user's raw
citation unchanged until a human resolves the conflict.

Treat these as chimeric critical:

- real identifier plus conflicts in at least two of title/authors/year;
- title matches but the cited author list adds an author absent from the
  registered work.

Treat a single title translation, subtitle, year-online/year-print difference,
author omission or ordering issue as metadata warning unless corroborating
evidence establishes a chimera.

### 5. Record publication updates

Inspect `publicatio