Skip to content

Hypertext & Reciprocity Audit

Branch: development
Date: 2026-06-13
Scope: All facility resource pages (CDM-*, CSH-*, MUS-*, ART-*, EXT-*, UNI-*, TTS-*) — 78 pages in resources/. Course pages (CUR-*) excluded.
Related: Audit-driven refactor policy · Grice Cluster Review · Source Packet Workflow · Main Evidence & Verification Audit

Implementing these findings: follow audit-driven-refactor-policy.md. Audit findings are not evidence; surface and link relationships already supported by in-repo sources only.

Executive summary

The map has a strong YAML evidence layer (person–resource, publication–resource, grant–resource links with evidence_text) and a working person→resource injection (apply_people.py → ## People & contacts with role labels and profile links). Resource↔resource reciprocity is partial: 60 directed edges in ## Linked Relationship IDs lack a return link, often by design (program hubs, buildings, external partners) but sometimes as fixable gaps (lab clusters, admin relationships).

There are no person hub pages (PER-*.md). Person reciprocity is therefore one-way on the public site: labs link to people (profile + email + relationship role), but people do not have a browsable page listing their labs. Registry reciprocity lives in data/people.yaml and data/person_resource_links.yaml only.

Publication and grant hypertext on resource pages is thin despite rich YAML: 3 of 4 graph-included publication–resource links are invisible on target pages; grant edges are intentionally internal.

Audit method

Automated pass over resources/*/*.md plus cross-check against:

  • data/person_resource_links.yaml (include_in_public_site)
  • data/publication_resource_links.yaml (include_in_graph)
  • data/grant_resource_links.yaml, data/output_resource_links.yaml, data/course_resource_links.yaml
  • data/site_display.yaml (people_contacts.enabled: true)

Checks performed:

  1. Person in YAML public links ↔ rendered ## People & contacts
  2. Resource ID in prose ↔ markdown link and/or ## Linked Relationship IDs
  3. Linked-list edge A→B ↔ B→A reciprocity
  4. Multi-affiliation person ↔ cross-links between their labs
  5. Graph-included publication–resource links ↔ visible on resource page (PUB id or DOI)
  6. Named person in body text ↔ profile/mailto link (outside People section)

Architecture: what “reciprocity” can mean here

Link type Outbound (public MD) Inbound / reciprocal today Evidence on page
Person → lab People & contacts on lab page (name, role, email, DePaul profile) No person page; people.yaml associated_resources only Role visible; evidence_text not shown on page
Lab → lab Documented Relationships + Linked Relationship IDs Manual; 60 asymmetric linked-list edges Narrative + sometimes DOI; not always inline source URL
Program hub → labs e.g. CDM-015 → CDM-001/004/005… Labs do not link back to CDM-015 (6/6 one-way) Program page cites catalog; labs cite own evidence
Building → labs CSH-003 ↔ many McGowan labs Partial reciprocity Location evidence in YAML
External → DePaul EXT-003 → CSH-007, CSH-005… DePaul labs rarely link back to EXT-* EXT notes omit PI names by policy
Publication → resource Rare on pages PRL in YAML DOI in YAML; often missing on EXT/CSH pages
Grant → resource Not on public pages Internal graph only CSV / internal sources
Output → resource Not on pages YAML only Faculty profiles, news
Course → facility 2 documented links Facility pages may not link to CUR-* course_resource_links.yaml
Equipment catalog 51/78 pages link equipment-index.md Index does not link back to each resource Category anchors
Unit indexes units/*.md (7 files) Not systematically reciprocal with every resource Unit-level prose

Person ↔ resource

What works

  • 178 person–resource links with include_in_public_site: true.
  • 0 gaps where a public-link person is missing from that resource’s ## People & contacts section (with people_contacts.enabled: true).
  • Relationship nature is visible in People section: Director, Faculty lead, Affiliated faculty, etc. (from apply_people.py labels).

Gaps & limits

  1. No person hub pages. A reader on CSH-016 sees Kyle Grice with role and profile link, but cannot navigate to a single “Kyle A. Grice” resource page listing CSH-016, grants, publications, and collaborations. Reciprocity is data-layer only (people.yaml).

  2. evidence_text not surfaced. Rich provenance (office, methods, coauthorship) exists in YAML but not in rendered HTML/MkDocs. Reviewers must open raw YAML.

  3. Access “Contact name” vs People section (34 cases). Many pages use unit desks (CSH front desk, IRL Loop campus, Camera Vault) in Access metadata while People section lists named faculty. This is correct policy (prefer unit channel for access) but can look like a person gap when the contact name is not a registry person.

  4. Multi-lab faculty without cross-lab links (37 pairs). Example: Filipo Sharevski is on CDM-004, CDM-007, CDM-008, CDM-015 but those lab pages do not cross-link each other. A reader landing on CDM-007 may not discover CDM-008 (Secure Design Lab) unless they follow the person’s DePaul profile externally.

  5. Named in prose without link (2 cases). EXT-011 mentions David Hanley and Jacob Furst in body text without profile links (they may be absent from People section on that partner page).

  6. 29 person–resource links hidden from public site (include_in_public_site: false) but may remain in graph exports — intentional for admin/grant anchors, but creates public vs graph hypertext split.

Resource ↔ resource

Reciprocity statistics

  • 60 directed edges in ## Linked Relationship IDs where target B does not list A back.
  • 1 prose mention of a resource ID without link/list entry (EXT-009 mentions EXT-010 in Documented Relationships without hyperlink).

Categories (asymmetric edges)

Category Count Typical pattern Reciprocal expected?
Other (lab/admin/instrument) 21 CSH-006→CSH-001, CSH-013→CSH-007 Often yes for peer labs
University unit (UNI-*) 15 UNI-011→CDM-001, UNI-012→UNI-004 Selective (centers → constituents)
Program hub 13 CDM-015→labs, CSH-010→UNI-012 Often intentional one-way
External partner 11 CSH-013→EXT-003, EXT-→UNI- Partner policy; EXT pages omit PIs

Hub example: CDM-015 (Robotics / ISE / physical computing)

Links out to CDM-001, CDM-003, CDM-004, CDM-005, CDM-016, CDM-017. None link back to CDM-015. This is a curriculum aggregator, not a physical lab — one-way hub may be correct, but students browsing CDM-004 (CyberLabs) never see the program context unless they search.

Lab cluster (post–Grice refresh)

CSH-016 / CSH-017 / CSH-001 cluster is in good shape after June 2026 refresh:

  • Reciprocal: 016↔017, 016↔001, 017↔001, 016↔003, 017↔003, 017↔018.
  • Inline links + DOIs in Notes/Documented Relationships (PUB-009, PUB-014, PUB-035, PUB-036).
  • CSH-017 includes CSH-002 in Linked IDs (prior gap closed).
  • Do not add CSH-016↔CSH-018 without direct evidence (Grice Cluster Review).

Relationship nature visibility

  • All 78 facility pages have a non-empty ## Documented Relationships section.
  • Best pages combine relationship verb + target link + evidence (CSH-017: “joint FRET-substrate projects with Southern Lab … documented in PUB-013 … DOI”).
  • Weaker pages list IDs only in ## Linked Relationship IDs without narrative relationship type in prose.

Publications, grants, outputs (YAML vs pages)

Resource Publication On page? Notes
EXT-003 PUB-002, PUB-010 No Strong YAML evidence (APS trial run); EXT policy omits PI names; no DOI on page
CSH-018 PUB-013 No Cited on CSH-017 with DOI; Southern lab page silent
PRL-PUB-001/002 EXT-003 — Graph edge exists; human page does not

Only 3 facility pages reference PUB-* at all; 2 include doi.org links (CSH-016, CSH-017 after Grice refresh).

Grants

  • 2 bare GRA-* / GRL-* mentions on facility pages total.
  • Grant–resource edges live in YAML; internal permission keeps them off public pages — correct, but graph-aware readers see edges MkDocs readers do not.

Outputs

  • 0 OUT-* references on facility pages; output–resource links exist in YAML only.

Beyond person↔lab and lab↔lab:

  1. Person ↔ publication — person_publication_links.yaml; almost never linked from resource prose (only PUB DOIs on CSH-016/017).
  2. Person ↔ grant — graph only; include_grant_pis: false in site display.
  3. Person ↔ output — exhibitions, software, datasets; no MD hypertext.
  4. Publication ↔ publication — none (no citation network in MD).
  5. Grant ↔ grant — none.
  6. Resource ↔ course (CUR-*) — only 2 course_resource_links.yaml entries (CDM-001); 187 course pages without facility backlinks.
  7. Resource ↔ equipment line item — equipment blocks link to category in equipment-index.md, not to specific resource_equipment.yaml line IDs.
  8. Resource ↔ unit index — units/cdm.md, units/csh.md; not generated from link YAML.
  9. Resource ↔ source packet — e.g. CSH-016 verification cites sources/inbox/2026-06-13-kyle-grice-faculty-profile-2 (good provenance); inconsistent elsewhere.
  10. Resource ↔ external partner agreement — MOU/agreement docs mentioned in index policy; rarely linked.
  11. Candidate entities — refactor prompts require listing not-yet-modeled entities; no standard MD block for “candidate additions.”
  12. ORCID / DOI registry — new in people.yaml / publications.yaml; not yet in resource MD hypertext.
  13. Graph-only vs public-site edges — 29 hidden person links; publication/grant edges with include_in_graph false vs true.
  14. Reciprocal equipment search hints — HTML comments <!-- equipment-search: … --> for site search; not human-visible links.

Traceability to source

Surface Source visible on page?
Access / Verification sections Yes — Source URLs, evidence bullets
People & contacts Partial — profile URL; not evidence_file / evidence_text
Documented Relationships Mixed — narrative + DOI when curated (CSH-017); often no URL
Linked Relationship IDs No — bare links; relationship type in list title only
Publications on page Good when present — DOI links
Grants / internal CSV Hidden by policy

Recommendation: When adding a hyperlink, pair it with relationship type + shortest evidence pointer (DOI, profile URL, or sources/inbox/… packet path) in the same sentence — matching CSH-017’s PUB-013 pattern.

Priority findings (actionable)

High value, low risk

  1. Surface graph-included publication–resource evidence on pages where policy allows — especially CSH-018 + PUB-013 (mirror CSH-017 citation); EXT-003 + PUB-002/PUB-010 with “external user facility” framing and DOI (no PI names required).
  2. Inline relationship narrative for entries that exist only in ## Linked Relationship IDs (relationship verb + source).
  3. Fix EXT-009 → EXT-010 prose mention with markdown link (only pure prose-orphan found).

Medium value; policy decision needed

  1. Program hub backlinks — e.g. CDM-004 “Used by Robotics B.S. (CDM-015)” one line + link, if catalog evidence supports.
  2. Multi-lab cross-links for same PI — optional “Same faculty lead: CDM-008” on CDM-007 when people.yaml shows shared director (avoid inferring collaboration).
  3. Person evidence visibility — optional collapsible or review-only block quoting evidence_text (or link to packet).

Low priority / defer

  1. Person hub pages — new page type or generated index from people.yaml (schema + MkDocs nav decision).
  2. Grant/output hypertext on public pages — blocked by internal-data policy unless permission flags added.
  3. Full reciprocity (60 edges) — many are intentional; pursue reciprocity by edge category, not blanket symmetry.

Do not do without new evidence

  1. Lab↔lab links for topical similarity only (e.g. CSH-016↔CSH-018).
  2. Reciprocal EXT↔lab edges that imply DePaul ownership of external facilities.

Suggested reciprocity rules (for refactors)

  1. Peer labs (shared building, shared PI, coauthored work): bidirectional Linked ID + one sentence citing evidence on each page.
  2. Program → lab: one-way OK; optional single back-link from lab to program when catalog names the lab.
  3. Building (CSH-003) ↔ occupant labs: bidirectional when occupancy is documented.
  4. Person ↔ lab: lab page must list person in People section when include_in_public_site; person “hub” is profile URL until PER pages exist.
  5. Publication ↔ resource: if publication_resource_links.yaml has include_in_graph: true, page should cite DOI + relationship (uses, produced_by, acknowledges).
  6. External partner: link to DePaul labs that documented facility use; do not require partner page to list every DePaul PI.

Tooling gaps

  • ## Linked Relationship IDs and ## People & contacts are hand-maintained or script-injected but not validated for reciprocity in refresh_all.py.
  • Consider a scripts/audit_hypertext.py report (this audit’s logic) in CI or post-refresh, emitting warnings like publication-resource visibility and asymmetric lab-cluster edges.

Bottom line

Person→lab links on resource pages are complete and labeled for public-site person edges. True bidirectional hypertext is weak for people (no person pages) and mixed for resources (60 asymmetric edges, often intentional hubs). The largest evidence visibility gap is YAML-backed publications and grants that graph tools see but MkDocs readers do not. The Grice/Karver cluster is the current best-practice template for relationship prose + DOI + reciprocal lab links.

Regenerate automated counts: run the audit snippet in commit history or add scripts/audit_hypertext.py.