Ref Audit

ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. ref-audit v1.0 — recent: initial version. Then proceed.

The integrity health check for a reference scope. It answers "is the source of truth still canonical, well-formed, and honestly stamped?" It is read-only: it produces a report and prints a summary. It never edits (repairs/merges are /ref-reconcile, which is human-gated) — that is exactly what makes it autonomous-safe.

Read first: resources/layered-brains/COMPANY-BRAIN-SCHEMA.md (the enum + temporal contract) and resources/layered-brains/REFERENCE-SCOPE-SCHEMA.md (the reference-kind contract). This skill checks notes against those docs.

State Dependencies

The contract this audits

• provenance: every note must be provenance: reference. Anything else = a leak (a cognitive note crept in, or an insight was mis-filed here).
• type ∈ person · organization · product · agent · engagement · interaction.
• relationship ∈ (by type) person: self-team·client-contact·counsel·prospect·partner-contact; organization: self·client·prospect·partner·vendor·competitor·investor; product: own·competitor. agent/engagement/interaction carry no relationship.
• as_of: present + a valid YYYY-MM-DD.
• status ∈ active · superseded; a superseded note MUST have a superseded_by: "[[...]]" that resolves.
• partition rule: a relationship: competitor note belongs in market/; a transacted entity does not.
• links: every [[wiki-link]] resolves to an existing note; every entity has at least one relation (no orphans).

Process

Step 1 — Collect the family + frontmatter

cd $PROJECT_ROOT
SCOPE="${scope:-Company}"
ls Brain/$SCOPE/*/*.md | wc -l          # total entity notes

Step 2 — Run the checks (read-only)

Scan every Brain/$SCOPE/*/*.md. Use grep sweeps as the fast path, then Read the flagged notes to confirm:

cd Brain/Company
# provenance violations
for f in */*.md; do grep -qE '^provenance: reference$' "$f" || echo "PROVENANCE  $f"; done
# type enum violations
grep -rhoE '^type: .*' */*.md | sort -u        # eyeball against the allowed set
# missing as_of / bad date
for f in */*.md; do grep -qE '^as_of: [0-9]{4}-[0-9]{2}-[0-9]{2}$' "$f" || echo "AS_OF       $f"; done
# superseded without a superseded_by
for f in */*.md; do grep -qE '^status: superseded' "$f" && ! grep -qE '^superseded_by:' "$f" && echo "SUPERSEDED  $f"; done
# competitor sitting outside market/
grep -rlE '^relationship: competitor' */*.md | grep -v '^market/' | sed 's/^/PARTITION   /'

For dangling links and orphans, extract [[...]] targets across the family, resolve each against existing note basenames, and list unresolved targets + notes with zero in/out links:

# every wiki-link target used
grep -rhoE '\[\[[^]]+\]\]' */*.md | sed -E 's/\[\[([^]|#]+).*/\1/' | sort -u
# every existing entity basename
for f in */*.md; do basename "$f" .md; done | sort -u
# a target in the first list but not the second = dangling

For duplicate candidates, flag near-identical display names / aliases across sub-scopes (fuzzy) for /ref-reconcile to judge — do NOT merge here.

Step 3 — Write the report + summarise

Write resources/company-brain/reports/ref-audit-YYYY-MM-DD.md (create the dir if absent):

# Ref Audit — Company — YYYY-MM-DD
Total entity notes: N  (people · orgs · products · engagements · market)

## Violations
- Provenance: <count> [list]
- Type/relationship enum: <count> [list]
- Missing/invalid as_of: <count> [list]
- Status/superseded integrity: <count> [list]
- Partition (competitor outside market/): <count> [list]

## Link integrity
- Dangling links: <count> [note → missing target]
- Orphan entities (no relations): <count> [list]

## Duplicate candidates (for ref-reconcile)
- [[A]] ↔ [[B]] — same entity?

## Freshness (vs per-type SLA)
- Over SLA: <count> [note — as_of N days old vs Xd SLA]
- Next cohort to stale: <sub-scope> on <date>

## Verdict: CLEAN | N issues (M require ref-reconcile)

Print a one-screen summary + the report path. Do not fix anything.

Scope note (the audit/reconcile boundary): this skill checks structural link integrity only — every [[link]] resolves, no orphan. It deliberately does not flag relational asymmetry (A names [[B]] as client but B doesn't back-link) or conflicts (two notes contradict): most A→B links here are legitimately directional references (built on [[Trinity]], competitor of [[X]]), so a blanket reciprocity check would be almost all false positives. That judgment — relation vs reference — lives in /ref-reconcile Step 1, not here. A CLEAN verdict therefore means "well-formed and canonical," not "every link is mutual."

Verification

• Run against the live family → the total matches ls Brain/Company/*/*.md | wc -l (expect 53), and on the current data expect 0 provenance violations, 0 enum violations, 0 missing as_of (all 53 are provenance: reference, status: active, as_of-stamped).
• Any dangling links / orphans it finds are listed with the offending note and target.
• A report file exists at resources/company-brain/reports/ref-audit-<today>.md; no entity note was modified (git status shows only the new report).

This skill must refuse to

• Edit, merge, delete, or repair any entity note (report-only; hand fixes to /ref-reconcile).
• Write anything outside resources/company-brain/reports/.
• Crystallize, lifecycle-classify, or promote a record into a cognitive insight.