F5: write-lit-review skill driven by the house Guides - #45
Open
frastlin wants to merge 5 commits into
Open
Conversation
Overturns the B5 dir/cite_key decoupling (signed off 2026-06-30): a paper's directory name must now equal its cite_key. - lint_paper_schema.py: new DIR_KEY_MISMATCH violation (exit 2) when a paper dir name != its derived cite_key. - rename_to_cite_key.py: dry-run-by-default migration that renames mismatched dirs to their cite_key and rewrites every reference (index.md, _reader_done.tsv, keymap.tsv, ../<dir>/notes.md links and [[dir]] wikilinks in sibling files). - paper-reader/SKILL.md: name new paper dirs from the cite_key so they are born compliant; metadata rule now requires dir == cite_key. - build_keymap.py: docstring records the new invariant; keymap.tsv is now an identity cache. - README: document rename_to_cite_key.py. Tests: DirKeyMismatchTests (mismatch reported, match passes, year-differs-but- key-matches, main() exits 2) + test_rename_to_cite_key.py (plan, dry-run touches nothing, write renames + rewrites refs with no dangling links, idempotent). Closes #34 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012MKtQ1Dfg5qYWhobNKk7jP
lint_paper_schema.py already implemented the substance (required files, abstract.md verbatim+interpretation sections, exit 2). This is the hardening + wiring the feature asked for. - lint_paper_schema.py: add a PEP 723 block (pyyaml) so it is uv-runnable as a gate; docstring states it is the single source of truth for completeness (F3). - Reconcile skills/lint-paper/SKILL.md: abstract.md and citations.md are now REQUIRED (not "recommended"), abstract.md must carry both sections, and a new Step 3 runs the mechanical linter as the authoritative, exit-2 gate so the two linters can never drift. - Wire the gate as a mandatory final step in process-new-papers, ingest-new-papers, and ingest-collection: a non-zero exit hard-blocks the wave before drafting. - sync_skill_launchers.py: add lint_paper_schema.py launchers for those four skills; regenerated (drift test green). Tests: focused ABSTRACT_MISSING, CITATIONS_MISSING, ABSTRACT_SECTIONS (missing-interpretation), and main()-exits-2-on-incomplete coverage. Closes #35. Depends on #34 (F4 DIR_KEY_MISMATCH ships in the same gate). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012MKtQ1Dfg5qYWhobNKk7jP
…apers/ Two scripts each covered one edge (lit_review.py verify = draft<->bibtex symmetry; verify_citations.py resolve = @key->dir but always exit 0). Neither enforced the full invariant, so a key could pass verify, sit in the bibtex, and still have no paper behind it. - lit_review.py: new `gate` subcommand. For the cited-key set it computes MISSING_FROM_BIBTEX (cited but not declared) and MISSING_FROM_PAPERS (does not resolve to a dir, OR the dir fails the F3 completeness gate), prints each offending key with its citing sentence, and exits 2 if any bucket is non-empty. "Present in papers/" = resolves AND passes F3 (2026-06-30 decision); the F3 check is delegated to lint_paper_schema (lazy import keeps verify/build stdlib-only). PEP 723 gains pyyaml for the gate path. - verify-citations/SKILL.md: document the gate as a REQUIRED pre-ship Step 0, run before faithfulness grading; add a lit_review.py launcher so it is runnable. Tests: test_presence_gate.py — missing-from-papers (names key + citing sentence), missing-from-bibtex, clean-draft-exit-0, resolves-but-fails-F3 (missing abstract). Closes #36. Depends on #34 (identity) and #35 (the F3 gate it delegates to). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012MKtQ1Dfg5qYWhobNKk7jP
Nothing verified external existence: verify_citations.py grades faithfulness
against local notes, lit_review.py and the F2 gate check local presence. A
citation could be locally consistent and still point at a work that does not
exist.
- verify_citations_real.py (new): per-citation reality check.
* Fast path (DOI/URL present): resolve the identifier (Crossref content
negotiation for DOIs, <title>/citation_title for URLs) and match
title+author+year -- NO scholarly search is issued.
* Fallback (no DOI/URL): scholarly title search (Crossref) requiring title
fuzzy ratio >= 0.9 with +/-1 year tolerance.
* Verdicts REAL / MISMATCH / NOT_FOUND / UNVERIFIED (transient errors are
never silently passed); exits 2 on any MISMATCH/NOT_FOUND.
* Speed: a key whose papers/ metadata.json carries a verified verification
stamp is matched locally with no network; checks run concurrently; REAL
verdicts are stamped back into metadata.json. Google Scholar is never scraped.
* Network resolvers are isolated, mockable seams.
- paper_db_manifest.py: record the optional `verification` metadata block so the
F7 stamp schema is coordinated and never displaces cite_key.
- README: document verify_citations_real.py.
Tests (mocked, offline): DOI title-match (asserts no search call), DOI 404,
DOI title-mismatch, UNVERIFIED on timeout, title-only fallback match, NOT_FOUND,
local-stamp-skips-network, and main() exit 2 / exit 0.
Closes #37. Runs after F2; final gate inside F5 and F6.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012MKtQ1Dfg5qYWhobNKk7jP
No skill authored a review; research gathers input, verify-citations/lit_review only check an already-written draft. This adds the writing skill. - skills/write-lit-review/SKILL.md: ordered procedure with --mode full | intro. Reads the relevant vendored guide in full, runs the guide's intake questions, selects relevant papers from papers/ by tag/topic (reusing index.md + tags.yaml), drafts with the guide's structure + phrasing bank citing ONLY resolvable @keys, assembles citations.bibtex, then runs the gate chain: F2 presence gate -> lit_review verify -> verify-citations faithfulness -> F7 reality check. Includes a summary of how the exemplars open (intro guide section 10) per the decision to summarize rather than vendor the exemplar PDFs. - guides/: the two house guides vendored verbatim (full 27.5KB, intro 45.5KB); the skill reads these, never a machine-local odrive path. - sync_skill_launchers.py: launchers for lit_review.py, export_bibtex.py, verify_citations_real.py so the gate chain is runnable from the skill. - README: add a Writing and verification section. Tests: test_write_lit_review_smoke.py asserts SKILL.md + both guides are vendored and non-empty, and that build -> F2 gate exits 0 on a resolvable-key fixture (the mechanical assembly + gate handoff works end to end). Closes #38. Depends on #34, #35, #36, #37 (consumes a linted corpus; the gate chain wires F2/F7/verify-citations). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012MKtQ1Dfg5qYWhobNKk7jP
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #38.
What & why
No skill writes a review:
researchgathers web input, andverify-citations/lit_review.pyonly check an already-written draft. This adds the authoring skill that operationalizes the house writing guides.Changes
skills/write-lit-review/SKILL.md— an ordered, executable procedure with a--mode full | introargument:papers/by tag/topic, reusingindex.md+tags.yaml; read each candidate'snotes.md/abstract.md.@keys that resolve topapers/.citations.bibtex(export_bibtex.pyfiltered, orlit_review.py build).lit_review.py verify→ verify-citations → F7 reality check. All must pass before "done."Includes a short summary of how the exemplars open (intro guide §10), per the decision to summarize rather than vendor the exemplar PDFs.
guides/— the two house guides vendored verbatim (full 27.5 KB, intro 45.5 KB). The skill reads these, never a machine-localodrivepath.tools/sync_skill_launchers.py— launchers forlit_review.py,export_bibtex.py,verify_citations_real.pyso the gate chain is runnable from the skill.Tests (TDD)
test_write_lit_review_smoke.py: asserts theSKILL.mdand both guides are vendored and non-empty, and thatlit_review.py build→ F2 gate exits 0 on a resolvable-key fixture (the mechanical assembly + gate handoff works end to end).Full suite green:
193 passed, 65 subtests.Dependencies
Fifth in build order. Consumes a linted corpus (#34, #35) and emits drafts checked by the gates (#36, #37). Core building block for F6.
🤖 Generated with Claude Code