Skip to content

Promotion review governance update

Branch: development Date: 2026-06-14 Status: Active IKaC policy (effective immediately) Scope: Governance and workflow updates only — no source packets processed, no corpus content modified, no resources or relationships created. Related: Repository-wide refactor governance · Source Packet Workflow · Source Evaluation and Evidence Policy · Candidate preservation implementation report

Background

The hard-technology candidate review (2026-06-14) demonstrated that candidate preservation alone is insufficient. Five important facilities and laboratories were first preserved only as candidates:

  • Cybersecurity Clinic
  • CoBaAB Lab
  • Connolly Lab
  • VARC Lab
  • ATLAS (Argonne)

After targeted evidence discovery from institutional sources, all five were promoted into the corpus. Had the workflow stopped at "candidate preserved," that knowledge would have remained invisible to the Resource Map indefinitely.

This update makes promotion review required workflow, not an optional follow-up.

Rule added: PROMOTION DISCOVERY RULE

When any source produces new candidate facilities, laboratories, centers, institutes, clinics, equipment collections, technical capabilities, external facilities, programs, courses, partners, people, or relationships:

  1. Preserve the candidate with full provenance.
  2. Automatically perform targeted evidence discovery using appropriate high-confidence sources (institutional websites, faculty profiles, lab/center/ facility/project/department/grant pages, ORCID, Google Scholar, ResearchGate, Web of Science, Scopus, DOI-linked publications, official partner websites, and other sources permitted by source-evaluation-policy.md).
  3. Capture all newly discovered evidence as sources with provenance.
  4. Re-evaluate every candidate after evidence discovery.
  5. Promote candidates when promotion criteria are satisfied.
  6. Create or update all required entities (facilities, laboratories, centers, equipment collections, people, grants, publications, outputs, external partners, capabilities, programs, courses).
  7. Create all evidence-backed typed relationships.
  8. Evaluate and add reciprocal hyperlinks and relationship visibility where appropriate.
  9. Preserve unresolved candidates with rationale.
  10. Record: sources reviewed, sources imported, candidates promoted, candidates deferred, relationships added, reciprocal links added, remaining evidence gaps.

Governance clarification

  • Candidate preservation is the beginning of promotion review, not the end.
  • A source is not considered fully processed until either promotion review has been completed, or promotion review has been explicitly deferred with justification recorded in the refactor report.
  • The evidence bar is unchanged. Facility / lab / equipment / access / ownership claims still require institutional or project evidence. Promotion discovery raises the obligation to look; it does not lower the threshold to promote.
  • External partners may have internal structure. Large partners (e.g. a national lab) may contain multiple sub-facilities reached through different agreements and contacts; the implicated sub-facility and access pathway must be recorded rather than assumed.

Files modified

File Change
docs/reports/repository-wide-refactor-governance.md Added the Promotion Discovery Rule section (10 steps), a "Definition of fully processed" subsection, refactor-output section N (promotion review summary), and a forward-looking note in the candidate-preservation rule and bottom line.
docs/source-packet-workflow.md Added a required Promotion review subsection and step 4/5 to the required-refactor list; reconciled the Phase 2 paragraph that previously framed promotion as deferred; added section N to the refactor-output table; updated the lifecycle diagram and added a "processed only after promotion review" note.
docs/source-evaluation-policy.md Added a Targeted evidence discovery (promotion review) section (permitted sources table + rules), a promotion-review row to the repository-wide evaluation table, and section N to refactor-report requirements.
sources/inbox/_template/refactor_prompt.md Added the PROMOTION DISCOVERY RULE block, section N output requirement, and updated the post-refactor reviewer checklist.
sources/inbox/_template/evidence_checklist.md Added a Promotion review table and an evidence-quality-gate checkbox requiring promotion review per candidate.
intake_app/packet.py Added the PROMOTION DISCOVERY RULE block and section N to the auto-generated Cursor refactor prompt; updated the Task line to require promotion review.
intake_app/tests/test_packet.py Asserted the new guardrail phrases (promotion discovery rule, targeted evidence discovery, promotion review summary, not fully processed until promotion review).
docs/reports/audit-driven-refactor-policy.md Cross-referenced the Promotion Discovery Rule so audit-accompanying packets also run promotion review (section N).
docs/reports/candidate-preservation-implementation-report.md Added a "superseded framing" note clarifying that automatic capture is the first step and promotion review is now mandatory.
docs/reports/README.md Indexed this report.
mkdocs.yml Added this report to the Reports navigation.

No files under resources/, data/ (corpus), grants, people, publications, outputs, or graph exports were modified. This is a governance/workflow-only change.

Rules added

  1. Promotion Discovery Rule (10 steps) — mandatory targeted evidence discovery and re-evaluation for every preserved candidate.
  2. "Fully processed" definition — a source is processed only when promotion review is completed or explicitly deferred with recorded justification.
  3. Refactor-output section N — a required promotion-review summary (sources reviewed/ imported, candidates promoted/deferred, relationships + reciprocal links added, remaining gaps).
  4. Unchanged evidence bar + external-partner structure clarifications.

Workflow changes

  • The refactor lifecycle now includes an explicit promotion review stage between "proposed diffs" and "human approval."
  • The generated Cursor prompt (intake app) and the static template both instruct the editor to run promotion review and produce section N.
  • The evidence checklist now closes with a promotion-review gate, so a packet cannot be marked done at "candidates preserved."
  • Reviewers now check section N (alongside A, L, M) when inspecting the diff.

Remaining manual steps

These steps are not yet automated and remain human/agent responsibilities during a refactor:

  1. Targeted web/scholarly discovery — the agent must actively search permitted sources for each candidate; there is no automated crawler (and the workflow remains "not a scraper").
  2. Capturing discovered evidence as a source packet with provenance before citing it.
  3. Promotion decisions and page/relationship creation — still human-reviewed; the extract_candidates.py --promote tool only moves registry records, it does not create resource pages or typed relationships.
  4. Entity resolution for relationship candidates (source/target) remains manual (see Phase 2 report § Remaining gaps).
  5. Reciprocity suggestion automation (Phase 3) is still future work; reciprocal links are currently added by hand during promotion review.

Future source-processing behavior

For every future source ingestion and repository-wide refactor:

  1. Read the whole source; assess the whole repository (unchanged).
  2. Classify discoveries (evidence-backed update · candidate · rejected) (unchanged).
  3. Preserve candidates with provenance (unchanged).
  4. New: run promotion review on every candidate — targeted evidence discovery, capture-with-provenance, re-evaluate, promote what is evidenced, create entities and evidence-backed typed relationships, add reciprocal links.
  5. New: record section N, or explicitly defer promotion review with justification.
  6. A source is reported as fully processed only after step 4/5.

The net effect: candidates become work items with a required follow-up, not a terminal state. The five hard-technology promotions that previously required an explicit second request will now happen as part of standard processing.