Main Resource Map — Evidence and Verification Audit

Branch: development (based on origin/main @ 1b414d9, plus charter commit)
Date: 2026-06-13
Scope: Forensic review of how the working Resource Map on main handles sources, evidence, verification, access, and relationships. No fixes applied.

1. Branch and repository state

Check	Result
`development` based on current `origin/main`	Yes — merge-base is `1b414d9`
Files vs `main` except charter	Only `docs/development-branch-charter.md` differs from `main`
`main` modified	No

All facility data, YAML catalogs, scripts, and docs/ mirror on development match main.

2. What GitHub `main` deploys to the Raspberry Pi

The Pi does not run sync_docs.sh or regenerate pages. It pulls committed content from main and builds the static site.

Deployed artifacts on main:

Path	Role
`docs/`	MkDocs source directory (`mkdocs.yml` sets `docs_dir: docs`)
`mkdocs.yml`	Site configuration (Material theme, nav, search)
`requirements.txt`	Python deps for `mkdocs build`

Typical Pi workflow (inferred from repo docs and charter):

git pull origin main
mkdocs build          # or mkdocs build --strict
# serve static output from site/

Authoring workflow (maintainers, before push to main):

# Edit resources/*.md and/or data/*.yaml
./sync_docs.sh        # runs apply_* scripts, regenerates indexes/reports, copies resources/ → docs/
mkdocs build --strict
git commit && git push origin main

Important: The public site reads docs/resources/, not resources/ directly. sync_docs.sh copies resources/* into docs/resources/. Committed docs/ is what the Pi builds. Source files in resources/ and data/ are the edit targets; docs/ is the publish mirror.

GitHub Pages is not configured (README.md). The demo is private/local hosting on the Pi.

3. Current evidence architecture

The map uses a hybrid model: structured YAML for some fields, human-authored markdown for others, with scripts bridging YAML → page sections.

┌─────────────────────────────────────────────────────────────────┐
│  Authoring sources (tracked in git)                             │
├─────────────────────────────────────────────────────────────────┤
│  resources/<PREFIX>/<ID>.md   — prose, contacts, relationships  │
│  data/resource_access.yaml    — access level, URLs, rationale   │
│  data/resource_verification.yaml — status, confidence, evidence │
│  data/resource_equipment.yaml — equipment tables, source_note     │
│  data/people.yaml             — person registry + per-link evidence │
│  data/course_resource_links.yaml — documented course/facility links │
│  data/grants.yaml + *\_links.yaml — grant layer (graph-oriented) │
│  data/publications.yaml + *\_links.yaml                           │
│  data/outputs.yaml + *\_links.yaml                                │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ./sync_docs.sh  (or refresh_all.py)
                              │
┌─────────────────────────────────────────────────────────────────┐
│  Generated / injected page sections                             │
├─────────────────────────────────────────────────────────────────┤
│  ## Summary badges        ← apply_summary_status.py (YAML)      │
│  ## Access status         ← apply_access.py (YAML)              │
│  ## Verification        ← apply_verification.py (YAML)        │
│  ## Equipment             ← apply_equipment.py (YAML)           │
│  ## People & contacts     ← apply_people.py (person_resource_links) │
│  ## Related courses       ← apply_course_links.py (YAML)      │
│  ## Documented facility links ← apply_course_links.py (YAML)   │
└─────────────────────────────────────────────────────────────────┘
                              │
                    cp resources/* → docs/resources/*
                              │
                         mkdocs build → site/

Coverage (78 non-course facility/partner resources)

Catalog	Entries	Missing resources
`resource_access.yaml`	78	0
`resource_verification.yaml`	78	0
`resource_equipment.yaml`	partial	only resources with equipment blocks

Verification distribution

Status	Count
`likely` (~)	59
`confirmed` (✓)	9
`needs_review` (?)	9
`archived` (✕)	1

Access distribution

Level	Count
yellow (negotiated)	65
unknown	7
green (open)	4
red (restricted)	2

4. Current verification architecture

Source of truth: data/resource_verification.yaml

Fields per resource: status, symbol, confidence_score, rationale, evidence (list), last_verified, optional review_flags, next_step

Injection: scripts/apply_verification.py writes or replaces ## Verification on each resources/<PREFIX>/<ID>.md page:

Status and confidence
Rationale (human-readable summary)
Evidence bullet list
Last verified date
Also updates **Last Verified:** in ## Summary

Summary badges: scripts/apply_summary_status.py + scripts/status_badges.py combine access level (🟢🟡🔴⚪) and verification symbol (✓ ~ ? ✕) from YAML into ## Summary.

QA report: scripts/generate_verification_report.py → docs/reports/verification-review.md (not in site nav).

What verification measures: Primarily whether the resource still appears active and accurately described — not the same question as who may use it (that is access).

5. Current access architecture

Source of truth: data/resource_access.yaml

Fields per resource: level, rationale, access_url, contact_name, contact_email, source_urls, verification_date, optional review_flags

Injection: scripts/apply_access.py → ## Access status section.

Overlap with verification: Both carry dates and rationale text. Access holds source URLs and contact channels; verification holds evidence list and confidence. Content often references the same official pages but is stored separately. Access verification_date is independent of verification last_verified (usually aligned manually).

QA report: scripts/generate_access_report.py → docs/reports/access-status-review.md

6. Current source URL handling

Location	Origin	On public page?
`## Access status` → Source URLs	`resource_access.yaml`	Yes
`## Verification` → Evidence (may include URLs)	`resource_verification.yaml`	Yes
`## Contacts (resource-level)`	Hand-authored markdown in `resources/`	Yes
`## Source URL`	Boilerplate pointer (“see Contacts above”)	Yes, low value
Course/facility link blocks	`course_resource_links.yaml`	Yes, when links exist
Person profile URLs	`people.yaml` → `apply_people.py`	Yes, in People & contacts
Grant/publication/output links	`*_links.yaml`	No — graph/export only

Pattern: Official URLs are duplicated across Access (structured), Contacts (markdown), and sometimes Verification evidence. The dedicated ## Source URL section adds little beyond Contacts.

7. Current relationship evidence handling

Relationships exist in several parallel representations with different evidence rigor:

Relationship type	Structured evidence	On public page	Graph export
Person → resource	`people.yaml` (`evidence_file`, `evidence_text`) → `person_resource_links.yaml`	Names/roles only; evidence hidden	Yes (`edges_person_resource.csv`, 169 of 209 links)
Course → resource	`course_resource_links.yaml` (rationale + source_urls)	Yes (`## Related courses`)	No dedicated edge file
Facility → facility	`course_resource_links.yaml` `facility_links` (1 link)	Yes when injected	No
Resource → resource (general)	Prose only in `## Documented Relationships` + bullet list in `## Linked Relationship IDs`	Yes (narrative + links, ~204 bullets)	No
Grant → resource	`grant_resource_links.yaml`	No	Yes (`edges_grant_resource.csv`)
Publication → resource	`publication_resource_links.yaml`	No	Yes (with `include_in_graph` flags)
Output → resource	`output_resource_links.yaml`	No	Yes

Person links: scripts/build_person_resource_links.py derives person_resource_links.yaml from people.yaml. scripts/person_link_rules.py applies conservative include_in_graph / include_in_public_site rules. Evidence text is rich in YAML but not rendered on facility pages.

Resource-resource links: Maintained as markdown prose and ID lists. No resource_resource_links.yaml. export_graph_tables.py does not parse ## Linked Relationship IDs — only person, grant, publication, and output edges attach to resource nodes.

8. Facility page review (five examples)

CSH-016 — Grice Laboratory

Field	Where displayed	Source
Source URLs	`## Access status`	YAML (`apply_access.py`)
Evidence text	`## Verification` bullets; equipment `_Source:` line	YAML
Verification status	`## Summary` badge; `## Verification`	YAML
Access rationale	`## Access status`	YAML
Contacts	`## Contacts (resource-level)`; `## People & contacts`	Markdown + `people.yaml`
Relationships	`## Documented Relationships` (prose); `## Linked Relationship IDs` (3 links)	Markdown (no per-link evidence)

Publication PUB-009 appears in verification evidence YAML but not as a structured publication link on the page.

CSH-017 — Karver Laboratory

Same pattern as CSH-016. Cross-lab collaboration with Grice/Southern appears in ## Documented Relationships prose and affiliated-faculty entries in people.yaml (evidence on graph export, not on page). Grant GRL-001 links Karver lab in grant_resource_links.yaml (not surfaced on page).

CSH-001 — Chemistry Core Instrumentation & Machine Shop

Richest example: multiple official CSH URLs in Access and Contacts; long equipment table from resource_equipment.yaml; nine linked resources in ## Linked Relationship IDs without individual evidence. Director/chair relationships from catalog evidence in people.yaml.

CDM-001 — Idea Realization Lab (CDM)

Only confirmed (~9 total) resource with high confidence (94). Verification evidence list includes live URLs. Documented course links (CSE 201, CSE 301) injected from YAML with full rationale and source URLs — best-practice relationship evidence on the public page.

EXT-003 — Advanced Photon Source (non-CSH)

External partner template: ## Organization, ## Relationship to DePaul, collaboration prose, ## Collaborative documents table with Source column. Access/verification from YAML. Person contact (Laurent Chapon) from registry without profile URL on page. Resource-resource links to CSH-005/007/001 are markdown bullets only.

9. Diagnosis: what is the current problem?

The main map is not missing evidence overall. The problem is inconsistent structure and downstream availability:

Issue	Severity	Detail
Evidence stored in YAML but not consistently surfaced	High	Person-link `evidence_text` exists in YAML/graph but not on public pages
Relationship evidence missing for resource↔resource edges	High	~204 linked IDs + prose; only 1 facility-facility link in YAML; no graph export
Evidence stored only in prose	Medium	`## Documented Relationships` and Notes carry evidence that YAML/graph cannot consume
Verification evidence mixed with access evidence	Medium	Overlapping rationale and dates; URLs primarily in access, bullets in verification
Dual-source drift risk	Medium	Contacts/relationships in markdown vs access/verification in YAML can diverge
Publish mirror lag	Low	`resources/` vs `docs/resources/` can differ cosmetically until `sync_docs.sh`
Graph richer than public site for some layers	By design	Grants/publications/outputs have evidence in YAML but intentionally not on pages
mkdocs strict build fails	Operational	7 broken links in `docs/reports/` (see §11)

Primary gap for next-phase intake: The successful original workflow (rich sources → synthesis → human judgment → pages) produced good public prose, but relationship and person-link evidence is split between invisible YAML and unstructured markdown. Graph export cannot reconstruct resource↔resource topology from the public site alone.

This is not a case for regex faculty scraping. It is a case for structured, evidence-backed link records that feed both page generation and downstream export — following the course_resource_links.yaml and person_resource_links.yaml patterns.

10. What already works well (do not disturb)

YAML-driven access and verification — 100% coverage, conservative statuses, injected sections, summary badges.
sync_docs.sh pipeline — clear, repeatable, documented in README.md.
people.yaml + person_resource_links.yaml — evidence_text, confidence, graph inclusion flags, display policy in site_display.yaml.
course_resource_links.yaml — exemplar for evidence-backed edges with source URLs on pages.
Conservative graph export rules — person_link_rules.py, vague-evidence filtering for publications/outputs.
Field standard in resource-map-index.md — governance, naming policy, external partner template.
Separation of public display vs graph — include_in_public_site / include_in_graph flags.
MkDocs Material site — working demo with equipment index, unit tables, search.

11. What is fragile

Hand-maintained ## Linked Relationship IDs — no evidence fields; not exported to graph.
Regex-based section patching in apply_*.py — ordering assumptions; brittle if section headings change.
Hardcoded equipment verify date (May 28, 2026 in apply_equipment.py) — not tied to YAML last_verified.
Redundant ## Source URL boilerplate — adds maintenance without information.
docs/reports/ broken links — mkdocs build --strict fails (7 warnings).
Grant/publication evidence on verification lists (e.g. PUB-009 on CSH-016) without corresponding structured link visibility on pages.
Local-only data/ grant PDFs — referenced in evidence_file paths but not in git; reproducibility depends on local files.

12. What should be made more structured (future work)

resource_resource_links.yaml (or equivalent) — modeled on course_resource_links.yaml: from_id, to_id, relationship, rationale, source_urls, evidence_text, include_in_graph, include_on_page.
Surface person-link evidence on review artifacts — not necessarily on public pages; human reviewers need to see YAML evidence without opening raw files.
Unify source URL registry — single canonical URL list per resource, referenced by access, verification, and contacts generation.
Align equipment last_verified with resource verification pass dates from YAML.
Intake proposal format — AI-assisted synthesis produces proposed YAML + markdown diffs with evidence citations, human approves, then sync_docs.sh runs.

13. Recommended next changes (implementation order)

Step 1 — Inventory and formalize edge types (no new UI yet)
Document all relationship categories and pick one YAML schema for resource↔resource edges. Migrate the single existing facility_links entry and a pilot set (e.g. CSH-016/017/001 cluster) from markdown bullets to structured links.

Step 2 — Review-facing evidence bundle
Before any Flask app: a simple script or markdown report that, per resource ID, dumps access + verification + person-link evidence + structured relationships in one place for human review.

Step 3 — AI-assisted intake prototype
Restore the successful pattern: paste or attach rich source material → LLM proposes structured YAML/markdown changes with evidence citations → human edits/approves → sync_docs.sh → mkdocs build --strict.

Step 4 — Graph export extension
Once resource↔resource links are structured, add edges_resource_resource.csv to export_graph_tables.py.

Defer: Regex faculty scraper, Neo4j as source of truth, autonomous YAML writes, replacing MkDocs.

14. Build and link check results

git status          # clean except new audit file (and local untracked .neo4j/, graph/)
mkdocs build --strict   # FAILED — 7 warnings (strict mode aborts)

No dedicated internal link checker in the repository (no CI, no lychee/linkcheck config).

mkdocs build --strict failures (pre-existing on main):

File	Issue
`docs/reports/README.md`	Broken link to `../../graph_queries/README.md` (2×)
`docs/reports/ragmap_answers/*.md` (5 files)	Broken link to `internal-data-wishlist.md` (wrong relative path)

Absolute links in docs/demo/*.md produce INFO messages but do not fail strict mode.

15. Key file reference

File	Purpose
`data/resource_verification.yaml`	Verification source of truth
`data/resource_access.yaml`	Access classification source of truth
`data/resource_equipment.yaml`	Equipment tables and source notes
`data/people.yaml`	Person registry with per-association evidence
`data/person_resource_links.yaml`	Generated person↔resource edges
`data/course_resource_links.yaml`	Documented course↔resource and facility↔facility links
`data/site_display.yaml`	Public-site display policy for people contacts
`resources/*/.md`	Authoring source for resource pages
`docs/resources/*/.md`	Published mirror (Pi builds this)
`sync_docs.sh`	Regenerate and copy to `docs/`
`scripts/apply_access.py`	Inject access sections
`scripts/apply_verification.py`	Inject verification sections
`scripts/apply_equipment.py`	Inject equipment sections
`scripts/apply_people.py`	Inject people contacts
`scripts/export_graph_tables.py`	CSV export for graph tooling
`mkdocs.yml`	Site structure