Grant ingestion and knowledge governance

Branch: development
Status: Active IKaC policy
Related: Source Evaluation and Evidence Policy · Repository-wide refactor governance · Grant data intake template · Grant ingestion filter audit · Source Packet Workflow

Scope (read first)

This policy governs grant-layer evidence decisions when a source documents awards. It does not define packet scope.

A grant report, ORS listing, or award PDF still requires repository-wide refactor per Repository-wide refactor governance: assess people, facilities, equipment, publications, and relationships; preserve unresolved signals as candidates.

Core principle: unresolved knowledge is still knowledge

A grant or award supported by a reliable source may enter the corpus even when:

the PI is not yet in people.yaml,
co-PIs are not resolved,
facility or resource links are not yet established.

Do not discard evidence-backed awards because person or facility resolution is incomplete.

Do not invent people, person_id values, facility links, or collaboration edges to “complete” a record.

Represent gaps explicitly so they can be resolved in a later packet without re-losing the award.

This policy complements — does not replace — conservative rules for facility ownership, equipment use, and person↔person collaboration edges (see publication-intake-rules.md, grants-layer-review.md).

Three separate evidence questions

Treat these as independent decisions on every grant intake:

Question	What it asks	May proceed without the others?
Grant existence	Did a reliable source document this award (title, funder, PI name as stated, dates, amount)?	Yes — this is the primary gate.
PI identity resolution	Does the named PI map to a unique `people.yaml` entry?	No — grant may still be recorded with unresolved PI.
Facility / resource linkage	Does the source explicitly connect the award to a registry resource (`CDM-`, `CSH-`, …)?	No — grant may exist with `resource_links: not_supported` or `unresolved`.

Collapsing these questions causes institutional knowledge loss (e.g. dropping hundreds of ORS listing rows because people.yaml lacks the PI).

Preferred status dimensions

Use these labels in evidence_checklist.md, refactor_output.md, and grant notes until schema fields are formalized in YAML.

Grant evidence (`grant_evidence_status`)

Status	Meaning
`verified`	Primary source lists award with PI, funder, title, and dates/amount; featured narrative or official listing.
`probable`	Listing present but one field weak (amount ambiguous, dates partial, title truncated by PDF).
`needs_review`	Conflicting rows, duplicate suspected, or parser confidence low — human must confirm before graph export.

Maps to existing confidence (high / medium / low) and verification_status on grant records; prefer needs_review over silent omission.

Person identity (`person_identity_status` per named investigator)

Status	Meaning
`resolved`	`person_id` assigned; name matches `people.yaml` with evidence.
`unresolved`	Name (and optional affiliation) from source only; no registry match yet.
`ambiguous`	Multiple registry candidates or homonym risk; list candidates in notes — do not pick one without evidence.

Rules:

Record person_name and role (pi, co_pi, …) from the source.
Add person_id only when identity is resolved.
Never fabricate PER-### IDs.

Resource links (`resource_links_status` on the grant)

Status	Meaning
`resolved`	One or more `grant_resource_links.yaml` entries (or `related_resources` with evidence) tie the grant to registry resources.
`unresolved`	Source hints at a lab, center, or partner but naming is insufficient for a registry ID — document in notes and packet index.
`not_supported`	Source documents the award but does not support a facility/resource edge (most extramural listings).

Facility edges still require explicit lab/facility naming — not college, unit, or topic alone (Source Evaluation Policy).

Corpus representation (current and target)

Allowed today (manual / refactor)

data/grants.yaml already supports investigators without person_id when evidenced (e.g. external RFUMS PIs on DePaul collaborative sub-awards):

people:
  - person_name: Example External PI
    role: pi
    notes: Named in award PDF; not in DePaul people registry.
  - person_id: PER-016
    person_name: Thiru Ramaraj
    role: co_pi

person_grant_links.yaml rows should be created only when person_id is resolved. Unresolved PIs stay on the grant record until a people packet resolves them.

Target grant record notes (until schema fields added)

When PI is unresolved, include in grant notes:

person_identity_status: unresolved (PI Last, First from ORS FY2025 listing)
resource_links_status: not_supported
grant_evidence_status: verified

Optional future YAML fields (implementation phase — not required yet): person_identity_status, resource_links_status, grant_evidence_status at grant or per-person level.

Refactor and bulk-intake behavior

Do

Add GRA-* records for evidence-backed awards even when PI is unresolved.
Preserve full parsed indices in packet extracted/ (e.g. tier indices, dedupe keys, source PDF paths).
List unresolved awards in refactor_output.md section F (candidates) and propose grant rows when the source is reliable.
Count and report: grants added, PIs resolved vs unresolved, facility links added vs deferred.
Defer person_grant_links.yaml until person_id is resolved.
Defer grant_resource_links.yaml until facility evidence is resolved.

Do not

Drop awards from the corpus solely because the PI is absent from people.yaml.
Invent person_id, co-PIs, or EXT-* / facility links from funder name or “Collaborative Research” title alone.
Create person↔person collaboration edges from co-PI or coauthorship signals.
Treat tier-C / “non-registry” parser output as non-knowledge — it is unresolved knowledge, not rejected knowledge.

Bulk sources (e.g. ORS annual reports)

Parse all listing rows → packet extracted/.
Classify each row on the three evidence questions (existence / identity / resource).
Apply resolved rows to data/grants.yaml + PGL + GRL as today.
Apply unresolved-PI rows to data/grants.yaml only (no PGL until identity packet).
Report counts in refactor_output.md and grant-ingestion-filter-audit.md-style summary.

See Grant ingestion filter audit for current script behavior and recommended code changes.

Relationship to other layers

Layer	Unresolved PI	Unresolved facility
`grants.yaml`	Allowed (`person_name` only)	Allowed (empty `related_resources`)
`person_grant_links.yaml`	Defer	N/A
`grant_resource_links.yaml`	N/A	Defer until explicit naming
`people.yaml`	Do not auto-create	N/A
Graph export (`PI_ON`)	Export only when PGL exists with resolved `person_id`	`SUPPORTS_RESOURCE` only when GRL exists
Public site	Grant detail may stay internal / graph-only per display policy	Unchanged

Checklist for grant packets

Copy into evidence_checklist.md or refactor section B:

[ ] Grant existence: which rows are verified / probable / needs_review?
[ ] Person identity: resolved / unresolved / ambiguous counts per PI name?
[ ] Resource links: resolved / unresolved / not_supported counts?
[ ] Grants added to data/grants.yaml (including unresolved PI)?
[ ] PGL added only for resolved person_id?
[ ] GRL added only for explicit facility naming?
[ ] Unresolved rows indexed in packet extracted/ with source PDF + dedupe key?
[ ] No person↔person edges invented?

Lessons encoded (ORS annual reports, 2026-06-14)

~865 deduped award rows from six PDFs; ~723 excluded from corpus because apply logic required registry person_id — institutional knowledge loss under old practice.
36 collaborative-signal awards with unresolved PIs were indexed in tier_c_unmatched_or_weak.yaml but not merged into grants.yaml.
Policy change: those rows are candidates for grant records with person_identity_status: unresolved, not discard pile.
Implementation of bulk merge for unresolved PIs is deferred — see audit note implementation plan.