docs(references): PRD-0009 — book-citation grounding and Open Library enrichment#104
Conversation
…ry enrichment Draft PRD scoping how SP42 handles book citations, which the article-level verifier currently records as skipped (NonUrlSource). Three read-only-first layers: resolve via ISBN to Open Library / Internet Archive, ground claims against IA full-text scan OCR under the existing anti-fabrication gate, and offer sourced, operator-confirmed Open Library metadata enrichment reusing the ADR-0010 propose/confirm discipline. Indexed in the references README. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012u5MVp3vAN44KhsVg3vroY
Fold in the six decisions from design review: per-operator Open Library session (not a shared key); enrich existing records only (import deferred); structured fields relayed verbatim while a description may be model-synthesized only from a rich sourced context (adds Wikidata as a secondary authority); ground on the search-inside snippet (works even for lending-restricted scans); cited-page-first with whole-book fallback; and one thin read-contract ADR plus reuse of ADR-0010 for the write. Updates Proposal, DoD, Alternatives, Risks, and converts Open questions to Resolved. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012u5MVp3vAN44KhsVg3vroY
…plication) Research on existing Open Library <-> Wikidata data sharing (P648 linkage, OL's official Wikidata Integration pulling author data, cdrini/openlibrary-wikidata-bot) shows author-level sync is already owned by OL. Add a risk scoping this lane to edition-level, source-derived fields (ISBN/pages/subjects/cover/description) and putting author-biography enrichment out of scope, with a sibling pointer to the Wikidata write direction (PRD-0011/ADR-0017) which records the same de-dup and the FRBR work/edition sourcing rule. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012u5MVp3vAN44KhsVg3vroY
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9727043051
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…+ zero-hit verdict)
Two P2 review points, both correct:
- Layer 1 wrongly implied the ISBN comes from Citoid. The article extractor
drops no-URL refs before Citoid, and CitoidMetadata carries only URL-sidecar
fields, not ISBN — so book refs would still be skipped. Reword to require a new
cite-template identifier extractor that reads ISBN/OCLC/LCCN/OLID directly from
the citation's Parsoid data-mw (the ADR-0011 structured-extraction path), which
is exactly what lets a book ref stop being skipped{NonUrlSource}.
- Layer 2 conflated "searched, zero hits" with SourceUnavailable. Per ADR-0007,
SourceUnavailable is for no-usable-body only; an indexed scan searched with zero
matching snippets is not_supported (source exists, no supporting passage) —
otherwise genuine not-supported book citations are hidden from reviewers/stats.
Split the Layer 2 outcome and the DoD accordingly, with the keyword/OCR
false-negative caveat.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012u5MVp3vAN44KhsVg3vroY
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9bec133073
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Follow-up review caught two spots the previous fix missed: - Resolved Q4 still said "empty result set -> SourceUnavailable", contradicting the now-corrected Layer 2 and DoD. Align it: no usable body -> SourceUnavailable; indexed scan with zero matching snippets -> not_supported. - Resolved Q6 said "reuse ADR-0010 as-is" for the Open Library write, but ADR-0010's mechanism is MediaWiki-specific (WikitextNodeLocator/baserevid/wiki CSRF) and does not map to a field-level OL JSON change guarded by the OL record revision. Reword to two thin ADRs: a read-contract ADR and a separate OL apply-contract ADR that reuses ADR-0010's discipline but not its mechanism (the ADR-0017-over-ADR-0010 relationship), matching the header's non-wiki note. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012u5MVp3vAN44KhsVg3vroY
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 707f10fea9
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…sbn (PR #104) Codex review: openlibrary.org/isbn/:id is documented under "Import by ISBN" and can import-on-miss (stage/attempt an import), so it is not purely read-only — using it in Layer 1 would violate the "read-only, no auth" promise and the "enrich existing only" boundary. Switch resolution to a strictly side-effect-free read (Books API /api/books?bibkeys=ISBN: or the Read API), state that a miss is "no record" (never a create), add the caveat in Background, and update the DoD to verify a miss issues no import/write. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012u5MVp3vAN44KhsVg3vroY
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b108070c96
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d3810a10ae
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e65c2355a5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
3 participants
Summary
Adds a draft PRD (PRD-0009) scoping how SP42 handles book citations, which the
article-level verifier currently records as
skipped { NonUrlSource }(ADR-0011) —a book/ISBN yields no fetchable URL, so it is neither verified nor actionable today.
The PRD turns that dead end into two capabilities anchored on Internet Archive, in
three read-only-first layers:
Gated on a positive identifier; no title/author guessing.
claim on the returned verbatim snippet through the existing panel + ADR-0007
anti-fabrication gate, deep-link to the scanned page. This makes book citations
actually checkable.
Open Library record, reusing the ADR-0010 propose/confirm/refuse-on-drift
discipline against a new (non-MediaWiki) target.
Second commit folds in the six design-review decisions and converts Open questions
to Resolved. Doc is indexed in the references README. No code changes.
Type
Validation Required
Docs-only change (two Markdown files under
docs/); no source, build, or testsurface touched.
# nothing to run — no code changedRisk
Needs-an-ADR is checked as a forward note: the PRD proposes (resolved Q6) one
thin read-contract ADR (IA search-inside as a new grounding source + Wikidata as an
enrichment context source) plus reuse of ADR-0010 for the write. No ADR is required
to merge this draft PRD; it is flagged so the follow-on isn't lost.
Notes For Reviewers
nothing" line: structured fields are relayed verbatim, but a
descriptionmay bemodel-synthesized — only from a rich assembled sourced context (a linked
Wikidata item + Open Library/Citoid facts), shown with provenance. Framed as
grounded synthesis, not open-ended authorship, and recorded in Risks with a
candidate mechanical guardrail (per-sentence check against the assembled context)
to carry into the ADR.
you'd rather keep the MVP to OL + IA and treat Wikidata as a fast-follow, that's
a small scope trim.
docs/domains/references/prd/0008-bare-url-repair.mdis the closest prior art forthe propose/confirm posture; ADR-0011 is where book citations are currently
skipped. The PRD cross-references both.State: Draft— this PR exists to keep the design tracked, notto lock scope.
🤖 Generated with Claude Code
Generated by Claude Code