source-kit — source acquisition + stable summary + audit

Owns everything between "a citation key exists in <unit>/references.bib" and "the claim it supports is verified against local fulltext." The pipeline:

acquire → store → identity audit → stable summary → [select for a task] → support review
                    ↘ record verdicts to refs/audit/<key>.jsonl, ratchet the level (§8)

When to use

• A new entry is added to <unit>/references.bib and its fulltext must be saved.
• A think-tank / CDN URL won't fetch (403, "Just a moment…", challenge page).
• Building a claim-to-source map before an evidence-heavy draft.
• Writing or correcting a per-source summary that later agents use to judge relevance and jump back to the original passage.
• Reviewing whether each cited claim is actually backed by its local source.

Pairs with

• cite-check — mechanical format + key consistency (the gate). source-kit checks whether a source supports a claim; cite-check checks the citation's form. Run cite-check last, never as the only review.
• house-style reference/content-integrity.md — the integrity rules cited claims must honor (disputed claims stay disputes, speculation labeled, citations stay attached, do-not-misphrase, match source language).

0. Where a source lives — unit first, library on reuse

A course repo has two tiers, and a source's files exist in exactly one of them:

• Look before you fetch. Search library/references.bib and the other units' bib files for the work first. Keys are unique across the course repo, and ./fw check-citations fails on a duplicate — a second copy of a source means a second, diverging audit history.
• New sources land in the unit. Scans pull in many sources that never get cited; the library stays useful only if it holds what is actually shared.
• Promote on reuse: ./fw refs promote <key> moves the transcript, the audit log, the bib entry, and the manifest line into library/ in one git mv. Run it when a second unit wants the source; never copy the files.
• Below, <unit>/refs/… means the source's current home — read library/refs/… for a promoted source.

1. Acquire & store

When a new entry lands in <unit>/references.bib, save its fulltext under <unit>/refs/ so para. and p. locators can be verified during writing. Markdown (<unit>/refs/<citation_key>.md) is the preferred form.

1. Fetch the source from the url or doi field in the bib entry.
2. PDFs → <unit>/refs/<citation_key>.pdf. PDF→Markdown conversion is out of scope here — use an available extractor that preserves page markers, with OCR when needed; pdf-to-markdown is an optional integration. Without extraction, retain the original and mark transcription pending rather than claiming fulltext has been verified.
3. Other types (DOCX, HTML save, EPUB) → save the fulltext directly as <unit>/refs/<citation_key>.md, preserving paragraph structure.
4. Paywalled, but the institution's library licenses it → most journal articles a course needs are in this case, so try the library proxy before recording a source as inaccessible. The route is the authenticated-fetch skill (in older installs, tier 5 of robust-web-fetch): the agent downloads PDFs inside a signed-in browser session, merging chaptered ebooks. Run ./fw check-login before asking the author for anything: exit 0 means a login recipe and a filled credential file already exist on this machine, so the author has done their part — sign in with the skill's stored-credential login <site> and download straight away, because stopping to ask someone who already set this up only stalls the unit until they come back. Ask the author to sign in by hand in the visible window only when the check exits 1, or when that one login attempt fails and the page it stopped on gives no cause you can fix (a login form whose own script had not finished is a recipe fault to fix, not a reason to ask). Open <Library proxy><publisher-url> using the Library proxy row of COURSE.md; when the row is missing, ask the author for their library's EZproxy login prefix and record it there, since every later unit needs it too. If the skill is unavailable, ask the author to download the file by hand. A landing page that says the institution has no access means exactly that — fall back to the next branch rather than retrying.
5. Paywalled / inaccessible → create <unit>/refs/<citation_key>.md noting that, with whatever metadata is available (title, abstract, etc.). Do not fabricate content.

Originals are not tracked in git. The raw fulltext files (*.pdf, *.epub, *.html) under <unit>/refs/ are gitignored; their bytes live in a GitHub Release managed by ./fw refs-snapshot, pinned by the committed library/refs/MANIFEST.tsv (one manifest and one Release for the whole course: path relative to the course root + sha256 + release tag). Transcripts (*.md) and audit logs (audit/*.jsonl) stay in git.

• After fetching a new original: ./fw refs-snapshot push, then commit the updated MANIFEST.tsv alongside the bib/transcript change.
• To verify a source against its transcript on a machine without the file: ./fw refs-snapshot pull <key> (sha256-verified on download).
• push never drops a manifest row for an original this machine lacks. To drop a source on purpose, ./fw refs-snapshot forget <path> (the asset stays in the Release).
• ./fw refs-snapshot status shows missing/modified originals. Sources are immutable — a MODIFIED verdict means something is wrong; investigate, never re-push over it silently.

Two live tracking files are scaffolded into <unit>/refs/ — they hold the full conventions, so follow them rather than duplicating here. If a unit lacks them (it predates the scaffold, or sources are landing in library/refs/ first), copy them from .framework/assets/scaffold/refs/ before the first fetch, so the fetch has somewhere to record what it learned:

• DOWNLOADS.md — the job queue: what's still to fetch, why each blocked entry is blocked, Wayback snapshot IDs, and which robust-web-fetch tier won.
• README.md — current retention: what is now local (full text / PDF / landing-page-only / inaccessible / deprecated). Do not track PDF→Markdown progress here; that's pdf2md's concern.

2. Blocked downloads and institutional login

When curl, wget, or a built-in fetcher returns 403 or a "Just a moment…" challenge, use robust-web-fetch if available. Its original-file strategies are curl-cffi → Wayback → camoufox. Web-page printing requires an explicit --rendered-pdf; --html-fallback permits a Markdown substitute after the original-file attempts fail. Keep those artifact types distinct, because an abstract or login page printed into a PDF is not the publisher's fulltext.

For a known EZproxy, institutional login, or interactive challenge, use authenticated-fetch directly if available. ./fw check-login says whether a stored-credential login is already configured: when it is, sign in with it without waiting for the author; when it is not, the author signs in through a dedicated visible browser. Either way, subsequent downloads use that session and preserve the proxy-rewritten links. It depends on browser-cdp for browser lifecycle and robust-web-fetch for validation. Missing institutional entitlement remains an access limitation; record it rather than retrying indefinitely.

Request --json and record the actual output path, method, artifact type, final source URL, and archive timestamp in DOWNLOADS.md Notes, omitting session tokens or signed access parameters. Inspect status and complete: an explicitly allowed partial chapter merge exits 3 and lists missing URLs; it must not become a complete-book retention entry. Compare the supplied chapter list with the table of contents, because the tool only knows the URLs it was given. content_verified: false means source identity and claim support still require the audit below, even when the PDF structure is valid.

Resolve external skills through host discovery, because their install paths are not part of this framework. If unavailable, use the host's browser/archive capabilities or record the source as blocked; report missing checks and never count a challenge, landing page, or partial download as verified fulltext.

3. Landing page vs. direct asset URL

Think-tank citation URLs (CSIS, RAND, CNAS, FDD, …) almost always point to a landing page (HTML abstract + download button), not the report PDF. Before fetching:

1. Decide what the claim needs. A landing-page abstract rarely backs a substantive claim — if the citation supports a specific argument, you need the report body.
2. Parse the landing-page DOM for the underlying asset URL (typical patterns: csis-website-prod.s3.amazonaws.com/.../<slug>.pdf, s3.us-east-1.amazonaws.com/files.cnas.org/.../<slug>.pdf, rand.org/content/dam/rand/pubs/.../<slug>.pdf) and fetch that. S3/CDN PDFs usually clear robust-web-fetch tier 1 (curl-cffi); landing pages often need Wayback or camoufox. Skipping this produces silent "full text" classifications that are really abstract shells.
3. Record both URLs: citation URL (landing page) in the bib url =; direct asset URL as a % Direct report PDF: <url> comment above the entry and in DOWNLOADS.md. In README.md, distinguish Landing page markdown from Full text markdown — landing-page-only is not full text.

4. Bib metadata

For sources with a visible "last updated" timestamp on the page, the bib date = should be the source's own update date, not a Wayback snapshot date or your fetch date. Snapshot IDs live in DOWNLOADS.md Notes, not in the bib.

5. Stable per-source summary — source proxy, not task draft

Once the newest identity verdict is genuine, write one complete summary at <unit>/notes/<key>.md (or the unit that is doing the reading when the source lives in library/). It is a stable proxy for the work: later agents read it first to judge whether the source is relevant and to find the original passage quickly, then verify the passage in refs/<key>.md or the PDF before citing. The summary is not itself a citable source and never replaces that final support check.

A useful summary lets a reader understand the work on its own. Preserve:

• the bibliographic key and exact work/edition summarized;
• background, research problem, concepts and assumptions;
• the argument in the author's order, including mechanisms and scope;
• evidence, examples, methods, limitations and conclusion;
• page or paragraph locators precise enough to reopen the original.

Follow reference/summary-template.md. Two of its sections come first because they serve a reader who is learning to write research as well as one triaging sources:

• 論文骨架 (paper skeleton) breaks the work into the parts of a research article — question, interlocutor and gap, claims and stated hypotheses, argument steps in the author's order, evidence and method, conclusion and contribution, self-declared scope and limits — then adds the summarizer's observations on how the piece is written, labelled as such.
• 作者與學術位置 (author and field position) records the author's affiliation as printed in the work, the earlier work the author self-cites, and the author's school and contribution. A biography from outside the work needs its own cited source; the summarizer's characterization of the contribution is labelled, because a later agent may otherwise cite it as the author's.

Spell out each abbreviation at its first use in the file as 全名（縮寫）; each file is read on its own.

Write it source-centred, not assignment-centred. Do not trim, reorder or rewrite it for this week's theme, one presentation's time limit, or a later claim; those choices belong in the downstream task Model. When the source has not changed, its substantive summary does not change either. Edit it only to correct a demonstrated misunderstanding, omission, mistranscription or wrong locator (or to identify a genuinely different edition), and re-check every downstream passage that used the corrected point. Mechanical formatting may change without changing the account of the source.

The summary's claim is fidelity, so review it against the original before calling it complete. Record that review where the unit tracks work; do not turn the summary into an audit verdict, because identity and support have the narrower meanings in §8.

6. Source audit — BEFORE long drafts

For journal, thesis, and evidence-heavy homework or policy analysis, audit sources before drafting. Do not write the full argument first and verify afterward.

1. Build a claim-to-source map for the core argument.
2. Separate source roles:
   • Incident facts → direct reports, official releases, datasets, court filings, primary news reports.
   • Official policy / law / guidance → government, regulator, agency, or institutional documents.
   • Think-tank / scholarly interpretation → framing and analysis, not a substitute for incident or policy facts.
3. Confirm each central claim has ≥1 source that is reachable, correctly titled, and precise enough for the claim being made.
4. Record retention status in <unit>/refs/README.md (full text / PDF only / source-role note / inaccessible / deprecated).
5. If the audit changes the actual corpus, update the title, methodology, bibliography, and comparison dimensions together before expanding the draft.
6. When a source contributes a framework but you reject part of its argument (adopt its lens, not its specific event attributions), state the scope of adoption in-text where the citation appears, so a reader can't assume the rest came along.

7. Source review — AFTER drafting

Reviewing references means cross-reading each cited claim against the local <unit>/refs/<key>.md/.pdf — not just running check-citations.py. The script confirms keys resolve; it does not confirm the source supports the claim.

1. For each citation, open the ref file and locate the supporting passage. If the local file is a landing-page abstract (not the report body), treat support as unverified until the report PDF is fetched (§3).
2. Watch for silent gaps: landing-page md mislabeled Full text markdown in README.md, citation URLs that now redirect elsewhere, or date = fields that no longer match the source's current update timestamp.
3. Run cite-check (./fw check-citations <unit>) last, as a consistency pass — never as the only review.

8. Recording verdicts & the bib-quality ratchet — /bib_audit

The audit (§6) and review (§7) produce judgments, not just prose. Record each as an append-only line in the per-key log <unit>/refs/audit/<key>.jsonl — one file per source, never rewritten (a correction is a new line with a later ts). This is the machine source of truth ./fw check-bib reads; there is no consolidated report. Full model + schema: docs/bib-lifecycle.md.

Two verdict kinds:

• identity — is the local transcript the cited work itself? genuine · review-of (a review/summary of the work — the wrong document) · stub (right work, too thin) · wrong-file · missing.
• support — does it back the claim? backed · weak · contradicts. A support line always carries "unit":"<unit-name>": support is a judgment about one claim in one unit, so ./fw check-bib <unit> counts only that unit's lines. An identity line has no unit — it is a fact about the source and every unit inherits it, which is why a promoted source is never re-audited for identity. Record a support verdict only against a transcript whose newest identity is genuine. When the local file is a review, a stub, or the wrong file, you have not read the cited work, so any support verdict — including contradicts — would be a judgment about some other document, and it would sit in the log as the key's support state after the real text replaces the file. Put what the wrong document says in the identity line's evidence and in your reply to the author instead.

{"ts":"2026-07-06T17:04:10+08:00","actor":"<model/person>","key":"<key>","check":"identity","verdict":"genuine","evidence":"<pages checked / why>"}

Take ts from the clock at write time (date +%Y-%m-%dT%H:%M:%S%z) rather than composing it by hand. Current state is "newest line per check", so a hand-written timestamp that lands in the future is the one mistake a later correction line cannot supersede — it keeps winning until real time passes it. If you do write one, fix it before the file is committed and tell the author you did; once committed, the file is append-only with no exceptions.

The loop (drive it with the ratchet, don't audit blind):

1. ./fw check-bib <unit> --todo → the exact keys blocking the next quality level (L1 has-local-text → L2 genuine-identity → L3 locators-backed → L4 claims-supported).
2. For each blocking key, actually open the transcript and judge. Fan-out is safe: one subagent per key, each appends to its own audit/<key>.jsonl — the per-key partition means concurrent auditors never conflict.
3. Append the verdict line(s). Honesty guard — before you may write identity: genuine: confirm the transcript's title/container matches the bib entry and is not headed "Review of…". A byte-clean transcript is not proof of identity; a review of the work passes every mechanical check, so only this judgment catches it. When unsure, write review-of/stub, not genuine.
4. ./fw check-bib <unit> --assert=L<n> to confirm the level clears, then raise required_bib_level in WORK.json so the floor ratchets and dirt can't re-enter.

9. Quality profile — ./fw score-bib

check-bib answers whether a source backs the claim made from it. It cannot answer whether that source is the right kind of thing to be carrying the claim: a party's press release backs its own quoted figure perfectly and is still the wrong place to rest a finding. That judgment has nowhere to be derived from, so it is written by hand into <unit>/bib-scores.yml — each key scored 0–3 on authority, fitness, load, independence, and recency_fit (./fw score-bib --help has the axis definitions and the sidecar's format; library/bib-scores.yml holds the same axes for promoted sources, and a unit's entry wins axis by axis because load is a fact about one manuscript).

./fw score-bib <unit> turns the sidecar into a portfolio view (class, perspective, year band, language, citation concentration by source family) and five worklists. Act on them in this order:

1. UPGRADE / CORROBORATE — load-bearing with low authority. Either find a stronger source or add a primary corroborant; this is where a chapter is most likely to fall under questioning.
2. POSITION-EVIDENCE CHECK — load-bearing and from a party to the events. The fix is usually in the prose, not the bib: frame the claim as that party's position or action rather than as neutral fact.
3. TRANSCRIPTION RISK, STALE RISK, PARK / CUT — keep the 轉述／轉引 flags, re-date what is presented as current, drop what nothing cites.

Run it after an audit round rather than per key: it is a view of the whole set, and the portfolio half only means something once most keys are scored. A key with no sidecar entry scores 0 on every axis but recency_fit, so it surfaces in PARK / CUT instead of passing unnoticed — score the keys the argument rests on first.