Repository-wide refactor governance
Branch: development
Status: Active IKaC policy (effective immediately)
Related: Source Packet Workflow · Source Evaluation and Evidence Policy · Grant ingestion governance · Repository-wide refactor audit
Core principle
Every source packet is a potential update to the entire institutional knowledge repository.
The Resource Map is not a set of isolated silos (grants database, people registry, publication index). It is one hypertext knowledge corpus whose layers (resources/, data/*.yaml) must stay mutually consistent, evidence-backed, and navigable.
A packet's intake channel or primary source type (annual report, faculty profile, lab page, publication DOI, administrative PDF) describes how the material arrived — not which layers may be updated.
What is forbidden
A source packet must never be treated as:
| Forbidden frame | Wrong behavior |
|---|---|
| Grant-only | Parse awards; ignore lab names, equipment, programs, people |
| People-only | Update people.yaml; ignore publications, grants, facilities mentioned |
| Publication-only | Register DOIs; ignore affiliations, facilities, funding acknowledgments |
| Facility-only | Edit one resource page; ignore grants, people, outputs in the same source |
| Equipment-only | Append instrument rows; ignore access policy, directors, related labs |
Bulk scripts that write to a single layer without a full impact assessment and candidate preservation are a governance violation unless explicitly scoped as assistive extraction with human refactor review.
Full impact assessment (required)
Before proposing corpus edits, every refactor must evaluate whether the source could affect:
| Layer | Examples |
|---|---|
| People | Identity, affiliation, ORCID, expertise, registry gaps |
| Facilities / laboratories | Named labs, centers, rooms, access, verification |
| Equipment | Instruments, platforms, capabilities |
| Centers / institutes / programs | UNI-, EXT-, institutional programs |
| Courses | Documented course ↔ facility links |
| Grants / awards | Internal and external funding |
| Publications | DOI registry, authorship, facility acknowledgments |
| Outputs | Software, datasets, creative works |
| External partners | EXT-* edges, collaborative awards |
| Relationships | Person↔resource, grant↔resource, publication↔resource, reciprocity |
| Hyperlinks & reciprocity | Inline links, return links, narrative cross-refs |
| Evidence quality | Verification status, provenance chains, needs_review flags |
Record the assessment in refactor_output.md section L (see Source Packet Workflow).
Knowledge classification (three categories)
Every discovery from a source packet must be classified:
1. Evidence-backed repository update
Evidence is sufficient for incorporation into the corpus (YAML and/or resources/ prose).
Examples: verified DOI + authorship → publications.yaml; official lab page naming McGowan room → access/verification update; ORS listing with PI + amount → grant record.
2. Candidate knowledge
Evidence suggests a resource, facility, equipment item, capability, relationship, person, center, or program but is insufficient for promotion.
Candidates must be preserved, not discarded.
Required for each candidate (in extracted/candidates.yaml or section M of refactor_output.md):
| Field | Required |
|---|---|
candidate_type |
e.g. facility, equipment, laboratory, person, grant, relationship, program, capability |
label |
Human-readable name as stated in source |
evidence_snippet |
Quoted or tightly paraphrased text |
evidence_file |
Path within packet |
suggested_corpus_target |
e.g. new CSH page, CDM-011, people.yaml, defer |
promotion_status |
candidate (default) · needs_review · deferred |
reason_not_promoted |
Why evidence is insufficient today |
Examples: AGIF project title names "Immersion Lab" but no registry page exists; grant PDF names college but not lab; faculty profile mentions collaborator at external university.
3. Rejected claim
Evidence does not support the claim after review.
Record in section G (relationships considered but rejected) with reason. Rejection is not the same as candidacy — reject when the source does not actually assert the claim.
Candidate preservation rule
No facility, equipment, laboratory, center, capability, or relationship signal may be silently discarded merely because the source entered through a grant workflow, publication workflow, faculty workflow, or administrative workflow.
If evidence is insufficient for promotion:
- Preserve as candidate (section M /
extracted/candidates.yaml). - Preserve provenance (packet path, page, date, capture hash).
- Preserve evidence snippet (quoted text).
- Preserve source reference (
evidence_filein packet).
Silence is not acceptable audit practice.
Candidate preservation is not the end of processing. It is the beginning of promotion review.
PROMOTION DISCOVERY RULE (mandatory)
The hard-technology candidate review (2026-06-14) demonstrated that candidate preservation alone loses knowledge: facilities and laboratories (Cybersecurity Clinic, CoBaAB Lab, Connolly Lab, VARC Lab, ATLAS) were first preserved as candidates, then promoted into the corpus only after targeted evidence discovery from institutional sources. That behavior is now required workflow, not an optional follow-up.
When any source produces new candidate facilities, laboratories, centers, institutes, clinics, equipment collections, technical capabilities, external facilities, programs, courses, partners, people, or relationships, the refactor must:
- Preserve the candidate with full provenance (per the candidate-preservation rule above).
- Automatically perform targeted evidence discovery using appropriate high-confidence sources permitted by Source Evaluation and Evidence Policy — institutional websites, faculty profiles, laboratory pages, center/facility pages, project pages, department pages, grant-related pages, ORCID, Google Scholar, ResearchGate, Web of Science, Scopus, DOI-linked publications, and official partner websites.
- Capture all newly discovered evidence as sources with provenance (a source
packet /
source_snapshotcapture — never an unsourced claim). - Re-evaluate every candidate after evidence discovery.
- Promote candidates when promotion criteria are satisfied.
- Create or update all required entities — facilities, laboratories, centers, equipment collections, people, grants, publications, outputs, external partners, capabilities, programs, courses.
- Create all evidence-backed typed relationships.
- Evaluate and add reciprocal hyperlinks and relationship visibility where appropriate.
- Preserve unresolved candidates with rationale (
reason_not_promoted). - Record in the refactor report (section N): sources reviewed, sources imported, candidates promoted, candidates deferred, relationships added, reciprocal links added, and remaining evidence gaps.
Definition of "fully processed"
A source is not considered fully processed until either:
- promotion review has been completed (steps 1–10 above), or
- promotion review has been explicitly deferred with justification recorded in the refactor report (section N).
Promotion criteria are unchanged: facility / laboratory / equipment / access / ownership claims still require institutional or project evidence, not a single grant-title mention or topic similarity. Promotion discovery raises the obligation to look; it does not lower the evidence bar.
Relationship to layer-specific governance
Layer-specific policies still apply when that layer is implicated:
| Policy | When it applies |
|---|---|
| Grant ingestion governance | Source documents awards — apply grant existence / PI / facility linkage rules |
| Publication intake rules | Source documents scholarly works |
| Output intake rules | Source documents non-publication outputs |
| Audit-driven refactor policy | Acting on audit reports (not discovery) |
These policies constrain how to write to a layer; they do not limit whether other layers must be assessed.
Refactor output (additional sections)
Standard sections A–K remain as in Source Packet Workflow. Add:
L. Full Resource Map impact assessment
For each layer in the impact table, state:
- Reviewed: yes / no / not applicable
- Evidence-backed updates proposed: count + summary
- Candidates preserved: count + summary
- Rejected claims: count + summary
M. Candidate knowledge registry
Table or YAML index of all category 2 items with provenance fields listed above.
N. Promotion review summary (required — see Promotion Discovery Rule)
Record the outcome of promotion review for the candidates in section M:
- Sources reviewed during targeted evidence discovery
- Sources imported (new captures with provenance)
- Candidates promoted (→ new/updated IDs)
- Candidates deferred (with
reason_not_promoted) - Relationships added (typed edges)
- Reciprocal links added
- Remaining evidence gaps
If promotion review is deferred rather than completed, state that explicitly here with justification (see "Definition of fully processed").
Scripts and automation
Automated parsers (e.g. ORS/AGIF intake scripts) may accelerate evidence-backed updates to specific layers when run under human review. They must:
- Emit candidate indices for unresolved signals (facilities, people, relationships).
- Never be described as completing a "packet refactor."
- Document scope in script header: assistive layer merge; full refactor still required per this policy.
See Repository-wide refactor audit for current drift.
Bottom line
Intake type ≠ refactor scope.
Read the whole source. Assess the whole repository. Promote what is evidenced; preserve what is hinted; reject what is unsupported.
Preservation is not the finish line. Every preserved candidate triggers the Promotion Discovery Rule: discover targeted evidence, re-evaluate, and promote what becomes evidenced. A source is fully processed only when promotion review is completed or explicitly deferred with justification.