pin-audit

name: pin-audit description: Use when checking pin graph health. Runs lib/pins/audit to detect dangling relations, duplicates, invalid entities, stale entries, and orphans, then presents a ranked report.

Run a read-only health check over the pin knowledge graph by calling audit(input, opts?) from lib/pins/audit.ts.

Invocation

bun "${CLAUDE_SKILL_DIR}/scripts/audit.ts"

audit is read-only. It does not write, delete, or modify any file.

now omission disables stale detection. When opts.now is absent, detectStale skips every entity — no stale findings will appear in the report. Always pass { now: new Date() } unless you intentionally want to suppress staleness.

Detector set and severity

Findings are ordered highest-signal first in report.findings:

Rank	Type	Severity	What it means
1	`dangling`	error	A relation's `target` id is absent from the in-scope entity set. Primary signal — fix before anything else.
2	`duplicate`	error	Two entities share the same `source_url`.
3	`invalid`	error	Entity fails schema `validate()`.
4	`stale`	error	Entity exceeds its tier threshold (tier1=180d, tier2=90d, tier3=30d). `reference` type uses `checked_at ?? created_at` (falls back to `created_at` when `checked_at` is absent); all other types use `created_at`.
5	`orphan`	warning	Entity has no outgoing relations. Soft signal only — never a violation.

Dangling relations are the primary check: a broken link is a structural defect; an isolated node is merely informational.

Presenting results

Group findings by severity: errors first, then warnings.
Within errors, preserve the ranked order above (dangling, duplicate, invalid, stale).
For each finding, report: type, entityId, and message. For dangling, also include targetId. For duplicate, also include conflictsWith.
Treat orphan findings as soft warnings at the end of the report, not violations requiring action.
If findings is empty, report "audit clean — no issues found".