vault
Skill0 starsChanged 53 days agoMITView on GitHub
Vault integrity audit and maintenance. Use when asked if the vault is clean, to audit before a commit, or to check broken wikilinks, missing frontmatter, orphans, and stale refs -- and for the vault-health score. 9 classifiers via tools/vault-audit.py; 5 modes: audit, stats, daily, repair, refresh; 95/100 floor; never deletes. Not backup/restic freshness; not a lookup of note or template CONTENT.
12 other projects use a version of this.
Adopted by
Most recently taken up by
- Aidas-dev/k8s-agent-skillstheir own version, first seen Nov 16, 2026
- kriscard/Skillstheir own version, first seen Oct 28, 2026
- crsmithdev/alephtheir own version, first seen Oct 15, 2026
- abevz/devops-skillstheir own version, first seen Oct 15, 2026
- G1Joshi/Agent-Skillstheir own version, first seen Oct 13, 2026
- joelhooks/joelclawtheir own version, first seen Oct 8, 2026
Other versions12 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 12
- joelhooks/joelclaw★ 65same name
- G1Joshi/Agent-Skills★ 15same name
- kriscard/Skills★ 15same name
- AnYejun/blind-vault★ 12same name
- Aidas-dev/k8s-agent-skills★ 4same name
- burakolgun/vault-anything★ 4same name
- magnusrodseth/dotfiles★ 3same name
- M1hairu/skills★ 2same name
- TeamHelix-AI/helix★ 1same name
- yiyaw-lab/agent-armor★ 1same name
2 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. 0 are common, 7 are distinctive, and 14 are very specific to this project.
0
Common
Most of the 10 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
NEVER delete files. Move-to-archive only (.claude/skills/_archive/ per .agents/skills/AGENTS.md).
- Distinctive: line 23
All findings cite specific files + line numbers.
- Distinctive: line 31
Use: post-deprecation health check (after major skill changes), weekly vault-integrity sweep, before-/-after substantial multi-file …
- Very specific: line 54
Default with no arguments: audit.
- Very specific: line 64
U1 residency gate (orchestration economics, AGENTS.md): Run python tools/run-share.py --current-context FIRST.
- Very specific: line 112
Use the Agent tool with subagent_type vault-classifier-sweep.
- Distinctive: line 115
All 9 classifier keys present (even if empty arrays)
- Very specific: line 144
Check forbidden domain: field absent
- Very specific: line 145
Check tags do NOT use forbidden namespaces (domain/*, type/*)
- Very specific: line 146
Check status: value within enum (active/paused/done/dropped/stub/deprecated/draft/complete/stale)
- Very specific: line 168
Read _templates/daily.md; verify all 9 canonical sections present (Market Pulse / Observations / Decisions / Commitments / Insights / …
- Distinctive: line 194
if any GATE finding present, score hard-clamped to <= 90 (surfaces hook-bypass)
- Distinctive: line 244
All findings reference specific file paths (not vague "some files")
- Very specific: line 281
Write OUTPUT_PATH (audit report).
- Very specific: line 337
Read prior wiki/maintenance/stats-*.md last 3 reports.
- Very specific: line 345
If absent: HALT with diagnostic Daily note for <today> missing -- bash tools/session-start.sh should have created.
- Distinctive: line 348
Read body; verify all 9 canonical sections present
- Very specific: line 386
Verify --apply <issue-id-list> arg present.
- Very specific: line 390
Read MOST_RECENT_AUDIT_PATH.
- Distinctive: line 419
If any Edit fails, IMMEDIATE HALT, F11 stays on
- Very specific: line 463
Write the refresh report + sidecar, F14 narrow stage, atomic commit, F17 verify, F11 clear -- then the audit-mode Phase P peripheral …
“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Quality Rules
- Audit operations are READ-ONLY. Repair operations require explicit user confirmation per fix.
- NEVER delete files. Move-to-archive only (
.claude/skills/_archive/per.agents/skills/AGENTS.md). - Reports include severity classification, not just enumeration: CRITICAL / WARNING / INFO.
- All findings cite specific files + line numbers; no vague "some files have issues".
- Continuity scoring uses Brier-style calibration across runs (read prior 3 stats reports for trend).
- Daily-note operations are idempotent: same input -> same output -> zero diff on re-run.
- Repair-mode classification is conservative: anything ambiguous routes to NEEDS-CONFIRM, not SAFE-AUTO.
- The audit sweep is MANDATORY when specified by phase (audit MODE Phase D). Harness-conditional dispatch: when the harness exposes an Agent tool, dispatch
vault-classifier-sweep(it wrapstools/vault-audit.py --jsonand returns a structured findings JSON; the parent skill dispatches and validates the return); when the harness exposes NO Agent tool, execute the documented inline fallback (python tools/vault-audit.py --jsondirectly) as the normal path, reported asmode: inline (no Agent tool)-- not a DEVIATION. Only the mechanism varies; the sweep itself never varies. On an Agent-tool harness, pre-emptive skip based on judgment ("script will probably work fine inline", "JSON parsing not worth the dispatch overhead") is FORBIDDEN and surfaces in the Phase L audit report as DEVIATION (not "fallback"). Legitimate fallback fires ONLY on (a) contract violation -- subagent return missing required JSON keys, OR (b) actual dispatch failure -- timeout, rate limit, tool-denial, hard subagent crash. Quality preserved by additive design: the direct script invocation remains as fallback for legitimate dispatch failures.
When to use / not
Use: post-deprecation health check (after major skill changes), weekly vault-integrity sweep, before-/-after substantial multi-file refactors, ref-doc staleness audit pre-/deep invocation, daily-note schema verification.
Not for: cross-domain pattern recognition (use /spark), session-end retrospective (use /retro), morning briefing (use /brief), document onboarding (use /enrich), claim extraction (use /ingest), task-list rollup (the /tasks skill is archived -- no live replacement), off-machine backup freshness (restic/B2 status is out of scope -- see the backup runbook, not this skill).
Output is diagnostic + recommended fixes; mutation requires explicit repair --apply <ids> after audit.
Mode routing (Pattern 6 deterministic; invocation modes)
| Syntax | Behavior |
/vault or /vault audit | Default; read-only integrity audit; 9 classifiers; report + sidecar |
/vault stats | Quantitative dashboard; 18 statistics; Brier-style continuity score |
/vault daily | Today's daily-note presence + schema verification; report state to stdout |
/vault daily --append "<text>" | Append text to today's ## Sessions Run section (sha256-preserved) |
/vault repair --apply <issue-id-list> | Mutation; consumes most recent audit report; per-fix confirmation |
/vault refresh | Ref-doc staleness ranker; thesis-weighted priority report |
/vault refresh --scope <domain> | Narrow refresh to one domain (investing / meta) |
--preview (modal flag) | Phases A-N in memory; render to stdout; SKIP all writes; F11 never set |
--confirm | Block before each Write |
--since <date-or-sha> | (audit/stats only) Explicit baseline override for stats deltas |
--scope <path> | (audit/refresh) Narrow scan to one top-level subtree |
--no-peripheral | Write report file + sidecar only; skip Phase P peripheral updates |
Default with no arguments: audit.
Process
Audit mode is the canonical reference. Stats / daily / repair / refresh modes share Phase A/B/C/L/N/O scaffolding; mode-specific logic in Phase D-K.
MODE: audit (default) -- 15 atomic operations
Phase A -- Pre-flight
U1 residency gate (orchestration economics, AGENTS.md). Run
python tools/run-share.py --current-context FIRST. Exit 1 means the session is
carrying more resident context than this run should re-pay on every turn: report
the number, recommend /clear + re-invoke in a fresh session, and proceed only if
the operator says to. Cost basis: cache_read is ~82% of frontier cost and equals
the sum over turns of the resident prefix, so a heavy run started at 500K residency
costs multiples of the same run started fresh. This is a RECOMMENDATION, not a HALT
-- never block work the operator asked for; make the price visible before it is paid.
- Parse args + flags.
- Resolve today's ISO date.
- Resolve
OUTPUT_PATH=wiki/maintenance/audit-<today>.md. - Same-day collision check: if exists, default
-HHMMvariant;--replacereserved. - F11 collision check (
.claude/state/auto-commit-disabledexists -> HALT).
Phase B -- State-transition print (BEFORE F11)
Emit planned reads + planned writes + collision-handled output path to stdout. Format:
/vault audit -- planned state transition:
reads: tools/vault-audit.py output (5 classifiers); .claude/skills/_archive/ (deprecation exclude-list);
Calendar/daily/ (continuity check); _templates/daily.md (drift check); knowledge-moc.md (MOC-coverage)
writes:
- wiki/maintenance/audit-`<today>`[-HHMM].md (NEW)
- wiki/maintenance/audit-`<today>`[-HHMM]-meta.json (NEW sidecar)
- Calendar/decisions/sessions-log.md (append)
- wiki/hot.md (last_audit frontmatter bump if any CRITICAL findings)
F11 set after this printPhase C -- F11 set + parallel context load
touch .claude/state/auto-commit-disabledBEFORE any Write.- Build
EXPECTED_ARCHIVEDset: DERIVE it from the live.claude/skills/_archive/folder listing (never a hardcoded pair); currently includes /research, /review (2026-04-26) plus /corpus, /telemetry, /tasks and withheld personal skills (2026-07-06 cut), plus prior version-bumped tombstones. - Build
KNOWN_DEPRECATIONSset: parseCalendar/decisions/decision-log.mdfor entries containing "Deprecate" / "deprecated" / "moved to _archive". - Build
CANONICAL_DAILY_SCHEMA: 9 sections per_templates/daily.md(schema owner) + AGENTS.md: Market Pulse / Observations / Decisions / Commitments / Insights / Sessions Run / Cross-References / Tasks / Log. - Build
CANONICAL_FRONTMATTER_FIELDS: categories (plural list), type (optional), tags (plural), status (enum), created (ISO), updated (ISO), related (wikilinks). - Build
FORBIDDEN_FRONTMATTER_FIELDS:domain(stripped per AGENTS.md schema), legacy fields. - Build
FORBIDDEN_TAG_NAMESPACES:domain/*,type/*.
Phase D -- Classifiers 1-5 (harness-conditional dispatch + script fallback)
Classifiers 1-5 come from tools/vault-audit.py. D.0 is the dispatched path (Agent-tool harnesses); D.1 is the direct-script path -- the normal path on a harness with no Agent tool, and the fallback everywhere else. Exactly one of the two runs.
Phase D.0 -- DELEGATED dispatch to vault-classifier-sweep (PREFERRED path where an Agent tool exists; Phase C wiring 2026-05-02)
MANDATORY (per Quality Rules) on any harness exposing an Agent tool: dispatch first, no pre-emptive skip. The subagent (Opus max for compute discipline) wraps tools/vault-audit.py --json and returns structured findings JSON keyed by classifier with severity tier per finding plus composite score.
Use the Agent tool with subagent_type vault-classifier-sweep. Pass input: {scope: "<--scope value or 'all'>"}. Expected return: JSON with keys broken_wikilinks, missing_frontmatter, frontmatter_schema, orphan_detection, stale_refs, deprecated_skill_refs, daily_continuity, template_drift, moc_coverage, totals, score, score_floor_check, failures.
Validate subagent return:
- All 9 classifier keys present (even if empty arrays)
totalsobject withgate,hard_drift,soft_driftcountsscoreinteger 0-100score_floor_checkin {PASS,WARN,BREACH}- ISO timestamp present
- Severity tier strict:
GATE | HARD DRIFT | SOFT DRIFT(uppercase) per finding
On contract violation OR dispatch failure: fall through to the Phase D.1 inline script invocation below. Surface the fallback in the Phase L audit report.
On dispatch success: parse the returned JSON; classifiers 1-5 are populated by the script. Phases E-I below populate classifiers 6-9 inline (they are not part of the script). Skip the inline python tools/vault-audit.py invocation.
Phase D.1 -- Direct script invocation (INLINE FALLBACK; the NORMAL path on a harness with no Agent tool, otherwise runs ONLY if Phase D.0 failed)
Execute python tools/vault-audit.py --json (the --json script computes 5 of the 9 canonical classifiers -- broken-wikilinks, missing-frontmatter, frontmatter-schema, orphan-detection, stale-refs -- plus the X1-X8 extension classifiers and the composite score; deprecated-skill-references, daily-continuity, template-drift, and MOC-coverage are NOT in the script and are populated inline by Phases E-I):
- Broken wikilinks (CRITICAL) -- regex extract
[[target]]; verify target file exists; report unresolved - Missing frontmatter (CRITICAL) -- check first line
---; report files lacking frontmatter - Frontmatter-schema (forbidden fields) (GATE) -- forbidden
domain:field +domain/*/type/*tag namespaces (the script'sdetect_forbidden_frontmatter; the fuller categories-plural / status-enum check runs inline at Phase E) - Orphan detection (WARNING) -- entity files with <2 inbound wikilinks; exclude templates + archive folders
- Stale refs (WARNING) --
Atlas/sources/*/ref-*.mdwithupdated:>30 days; thesis-weighted annotation
Plus score-affecting HARD extensions X1 (session-artifact-gaps) + X2 (skill-body-length), and advisory SOFT extensions X3/X5 (count-drift), X6 (analysis-quality), X7 (stale-commitments), X8 (provenance-coverage). MOC-coverage gaps appear only in the script's markdown report (outgoing-link counts), never in --json.
Capture script output; parse into structured findings list. Report the mechanism honestly in Phase L: mode: dispatched | mode: inline (no Agent tool) | mode: inline fallback (<contract violation | dispatch failure>) | DEVIATION.
Phase E -- Classifier 6: Frontmatter-schema violations (NEW; INLINE)
Glob **/*.md (excluding .git/, node_modules/, _archive/, .checkpoints/, .obsidian/, .smart-env/):
- Extract frontmatter; check
categoriesis a plural LIST (not scalar string) - Check forbidden
domain:field absent - Check tags do NOT use forbidden namespaces (
domain/*,type/*) - Check
status:value within enum (active/paused/done/dropped/stub/deprecated/draft/complete/stale) - Severity: WARNING
Phase F -- Classifier 7: Deprecated-skill references (NEW; INLINE)
Grep vault for active-skill-list deprecations. The detection set MUST be derived from the .claude/skills/_archive/ listing, not hardcoded: currently /research, /review (2026-04-26) plus /corpus, /telemetry, /tasks and withheld personal skills (2026-07-06 cut). Exclude:
.claude/skills/_archive/(expected-archived)docs/VAULT-HANDOFF-V*.md(institutional history)Calendar/decisions/decision-log.md(decision audit trail)AGENTS.mdhistorical sections
Pattern: \b/(research|review|corpus|telemetry|tasks)\b plus skill-invocation form (use /research) etc. -- build the alternation from the .claude/skills/_archive/ listing rather than hardcoding this pair (this PROSE set is the /vault inline detection; the tools/vault-audit.py script-side classifier remains a /gate b BACKLOG item). Report any matches outside excluded paths. Severity: INFO (not breaking; cleanup candidate).
Phase G -- Classifier 8: Daily-note continuity (NEW; INLINE)
List Calendar/daily/*.md for past 30 days; sort by date; detect missing dates in sequence:
- Day-of-week awareness: weekend gaps acceptable IF no
Sessions Runactivity expected - Sample known good cadence from prior 90 days for baseline
- Severity: INFO; report gap dates + count
Phase H -- Classifier 9: Template-drift (NEW; INLINE)
Read _templates/daily.md; verify all 9 canonical sections present (Market Pulse / Observations / Decisions / Commitments / Insights / Sessions Run / Cross-References / Tasks / Log). Severity: WARNING if any missing.
(Verified 2026-07-13: _templates/daily.md carries all 9 canonical sections -- no template drift. The earlier 7-section state was remediated.)
Phase I -- Severity rollup + FOLLOWUPS:skills emission
Group findings by severity (CRITICAL / WARNING / INFO); for each, generate concrete one-line FOLLOWUPS entry tied to specific file paths. Block bounded to <=8 entries total. Examples:
<!-- FOLLOWUPS:skills -->
- [CRITICAL] /vault repair --apply L1-L7 -- 7 broken wikilinks in wiki/entities/tickers/ (trigger: NOW)
- [WARNING] /enrich candidate -- 12 files missing categories: field; batch-add via /vault repair --apply F1-F12 (trigger: EOW)
- [WARNING] /vault repair --apply T1 -- _templates/daily.md missing 3 canonical sections (Commitments, Cross-References, Log) (trigger: NOW)
- [INFO] /retro candidate -- 7 daily-note continuity gaps in past 21 days; consider session-cadence retro (trigger: EOW)
- [INFO] /vault repair --apply D1-D3 -- 3 deprecated-skill references outside expected paths; safe-auto cleanup (trigger: EOW)
<!-- /FOLLOWUPS:skills -->Empty case: (no followup skills recommended; vault clean).
Phase J -- Composite vault-health score (v2.2 -- 95-floor)
Tier-weighted score (0-100; 95-floor architecture per Plan #2 in
wiki/research/vault-prevention-architecture-2026-04-27.md):
GATE classifiers (must-be-zero; broken-wikilinks, missing-frontmatter, frontmatter-schema, template-drift):
- per finding: -5; cap -10
- if any GATE finding present, score hard-clamped to <= 90 (surfaces hook-bypass)
HARD DRIFT classifiers (orphan-detection, stale-refs):
- per finding: -1; cap -5
SOFT DRIFT classifiers (deprecated-skill-references, daily-continuity, MOC-coverage):
- per finding: 0 (advisory only; surfaced in INFO section + FOLLOWUPS:skills + meta.json soft_drift_count field; ZERO score impact)
Continuity adjustment: +/-2 (declining/improving trend across prior 3 audits); suppressed when raw_pre_trend < 97 OR any GATE finding (avoids double-counting drift already conveyed by HARD DRIFT and prevents trend penalty pulling clean state below 95).
Major-rehabilitation bonus: REMOVED (was a v2.1 calibration-era band-aid; the new 95 floor makes it unnecessary).
Floor invariant: 95/100 in steady state. The only path below 95 is a GATE breach, which surfaces as a 90-cap. Industry pattern: SonarQube quality gates separate must-be-zero gate metrics from headline maintainability rating; CodeClimate weights findings by remediation-effort (GATE=seconds, HARD=minutes, SOFT=hours-to-never); Vault Physician 0-100 gauge with color-coded green/yellow/red based on weighted classifier severity.
Formula:
raw_pre_trend = 100 + max(GATE_n * -5, -10) + max(HARD_n * -1, -5) + 0
if raw_pre_trend >= 97 AND GATE_n == 0:
raw = raw_pre_trend + trend(+/-2)
else:
raw = raw_pre_trend
score = clamp(0, 100, raw)
if GATE_n > 0: score = min(score, 90)Calibration history:
- v2.1 (post-2026-04-26): canonical -10/-3/-1 weights, +5/+10 trend bonuses, -50/-25/-10 caps. Mathematical floor under that scheme was ~80/100 with full GATE blocking because INFO-class drift could accrue -10 cap.
- v2.2 (post-2026-04-28): tier-weighted (GATE/HARD DRIFT/SOFT DRIFT). SOFT DRIFT exerts zero score gravity, raising the floor to 95. Aligns with industry practice (SonarQube quality gate, Vault Physician 0-100 gauge, CodeClimate technical-debt ratio).
SOFT DRIFT findings still emit FOLLOWUPS:skills entries with [SOFT-DRIFT] severity tag. The score does not punish them, but the action recommendation is preserved. This separates "how clean is the vault" (the score) from "what should be cleaned next" (FOLLOWUPS).
Phase K -- Pre-Output HALT gate (18-item invariant check)
- F11 set
OUTPUT_PATHcollision resolved (-HHMMif needed)- Frontmatter complete and schema-compliant on report
=1 finding category populated OR explicit "vault clean" rendered
- All findings reference specific file paths (not vague "some files")
- Severity classification on every finding (CRITICAL / WARNING / INFO)
- FOLLOWUPS:skills block syntactically valid; tied to specific issue IDs
- Vault-health composite score computed; rationale included
- Continuity comparison vs prior audit (when prior exists) populated
- EXPECTED_ARCHIVED exclude-list applied (no false-positive deprecation flags)
- CANONICAL_DAILY_SCHEMA reference embedded for template-drift Classifier 9
- ASCII-only on report body + sidecar (Pattern 22)
related:field has 3-5 wikilinks (hot, [[knowledge-moc]], peer audit reports if any)- Symmetric back-link plan (hot last_audit bump; sessions-log entry)
- Path-guard: no proposed Write targets
.raw/,private/,finance/,credentials/ - Sessions-log entry composed per canonical schema
- hot.md
last_auditfield present (add if missing) - F17 Co-Authored-By absent in planned commit
Phase L -- ASCII pre-write scan (Pattern 22)
Byte-scan all NEW content. HALT on byte >127. Replace em-dash, smart quotes, ellipsis with ASCII. Record the Phase D sweep mechanism (dispatched / inline no-Agent-tool / inline fallback / DEVIATION) in the report.
Phase M -- Compose audit report + meta.json sidecar
Per ref-output-templates.md schema. Body sections:
- H1 + Generated stamp + audit scope
- Executive Summary (composite score + finding-count-by-severity)
- CRITICAL Findings (with file paths, line numbers, fix recommendations)
- WARNING Findings
- INFO Findings
- Continuity vs Prior Audit (when applicable)
- FOLLOWUPS:skills block
- Footer (calibration line)
Phase N -- Final verification
Re-read composed body; re-run gate items 4, 7, 12; confirm internal references.
Phase O -- Atomic write
- Write
OUTPUT_PATH(audit report). - Write
OUTPUT_PATH-meta.json(sidecar). - F14 narrow stage:
git addexactly these 2 files. - F.halt: if either fails, HALT IMMEDIATELY; F11 stays on; structured report; no partial commit.
Phase P -- Peripheral updates (skip if --no-peripheral)
Sessions-log entry:
### YYYY-MM-DD -- /vault audit -- score <N>/100 - **Domain:** meta/skill-infrastructure - **Findings:** <C> CRITICAL, <W> WARNING, <I> INFO - **Followup skills:** `<count>` (`<comma-list>`) - **Artifacts:** audit-`<date>`[-HHMM] - **Related:** hot | [[knowledge-moc]]- hot.md frontmatter bump:
last_audit: <today>(add if absent). - hot.md
last_audit_score: <N>field (NEW; tracks vault-health continuity). - F14 narrow-stage all touched files; atomic commit
vault: audit -- score <N>/100 -- <C>C/<W>W/<I>I. - F17 verify: post-commit
git log -1 --format=%B | grep -c Co-Authored-ByMUST be 0. - F11 clear:
rm .claude/state/auto-commit-disabled.
MODE: stats -- 10 atomic operations
Same Phase A/B/C/K/L/N/O/P scaffolding. Mode-specific Phases D-J:
Phase D-J: 18 statistic blocks per ref-stats-catalog.md
- file-counts-by-top-level-path (Atlas / Calendar / Efforts / wiki / private / docs /
.agents/skills/canon active /.claude/skills/_archive) - word-counts-by-top-level-path (with kepano 150-line exception annotation)
- entity-coverage (held tickers vs entity-note presence)
- ref-doc-coverage (Built vs stub from knowledge-moc table vs frontmatter status)
- freshness-distribution (<7d / <30d / <90d / >90d per top-level path)
- session-log-entry-count (rolling 30d)
- daily-note-continuity-score (1.0 = no gaps; weighted by day-of-week expectations)
- skill-invocation-frequency (parsed from session-log entries)
- brier-calibration-carry (prior 30d /vault stats predictions vs current state)
- avg-wikilinks-per-file
- outbound-link-orphans (files with 0 outbound)
- inbound-link-orphans (files with 0 inbound; excluding templates/archives)
- MOC-coverage-percentage (per MOC: linked-files / total-domain-files)
- thesis-essay-activity (mention count per
thesis/*) - archive-skill-count (read-only sanity)
- active-vs-archived-skill-ratio
- tools-script-inventory (count + last-modified per tool)
Skill counts are taken ONCE from the canonical tree (.agents/skills/) plus any skill whose canon is still a migration-window pointer stub (counted from .claude/skills/); the generated .claude/skills/<name>/ mirrors of migrated skills are NEVER double-counted.
Each statistic with formula in ref-stats-catalog.md; thesis-importance weights for prioritization.
Continuity Brier scoring (NEW; mirrors /brief)
Read prior wiki/maintenance/stats-*.md last 3 reports. Each report's meta.json includes predicted_30d_trend field. Score current state against predictions: (predicted - actual)^2. Surface calibration_score_30d in stats report header.
Output: wiki/maintenance/stats-<today>[-HHMM].md + sidecar; sessions-log entry; hot.md last_stats: <today> bump.
MODE: daily -- 8 atomic operations
Phase A: Pre-flight (presence check)
Calendar/daily/<today>.mdexists?- If absent: HALT with diagnostic
Daily note for <today> missing -- bash tools/session-start.sh should have created. Run manually OR restart session.Do NOT recreate from /vault (canonical creation path is the SessionStart hook).
Phase B-D: Schema verification
- Read body; verify all 9 canonical sections present
- Drift detection: report missing sections; offer
/vault repair --apply S1style fix codes
Phase E: State surface
- Count items per section
- Show oldest unchecked Commitment age (if any)
- Show Cross-References count
Phase F-G: --append flag handling (only when present)
- F11 Phase C set
- Body-preservation sha256 capture
- Append
[HH:MM] <text>to## Sessions Runsection - sha256 verify content outside that section unchanged
- Atomic commit; F11 clear
Phase H: Stdout state report
Output: stdout state report (no file write unless --append).
MODE: repair -- 12 atomic operations (mutation discipline)
Recommended /goal wrapper (B1 integration; Claude Code v2.1.139+ feature; skip where the harness has no equivalent)
When fixing the vault back to floor (score >= 95 AND tiers.gate.count == 0) requires multiple audit-repair cycles -- common when a repair fix introduces a new finding, or when NEEDS-CONFIRM rejections leave residual GATE -- wrap the entire repeat-invocation pattern in /goal. This makes the loop EXPLICIT and AUDITABLE via transcript evidence, and the Haiku-class evaluator enforces a structured halt condition that resists worker-text fabrication.
Canonical condition string (insert verbatim; do NOT regress to a weaker variant; R8 mitigation):
Halt only when a Bash
tool_resultblock (paired bytool_use_idto a Bashtool_usethat invokedpython tools/vault-audit.py --json) appears in the transcript AND that tool_result's content contains JSON with"score": Nwhere N >= 95 AND"tiers": {"gate": {"count": 0, ...}}. Worker-generated text claiming the audit passed is INSUFFICIENT; only a paired (tool_use_id->tool_result) block counts as evidence. Each iteration must produce a fresh Bashtool_useinvocation ofpython tools/vault-audit.py --jsonand a correspondingtool_resultblock. Do not stop on partial progress; do not stop on inferred-pass without the structuredtool_resultblock visible. The Haiku-class evaluator reads the structured transcript representation (tool_use/tool_result objects with pairedtool_use_id), not rendered text.
Anti-gaming primitive: harness-emitted tool_use_id / tool_result pairing CANNOT be fabricated by the worker (only the harness emits those records). A worker that fabricates a passing audit in prose cannot also fabricate the paired tool_result block. This closes the R8 condition-gaming risk where a Haiku-class evaluator might accept "appears done" text without true verification.
Recommended invocation shape (user-side):
/goal "<canonical condition string above>" Iterate /vault audit + /vault repair --apply `<ids>` cycles until cleanThe repair mode below remains single-pass-atomic per invocation. /goal sits ABOVE the skill, orchestrating multiple skill invocations until the structured evidence condition fires. On a harness with no /goal equivalent, the user re-invokes /vault audit + /vault repair --apply <ids> manually until the same structured evidence condition holds -- the halt condition is unchanged.
Phase A: Pre-flight
- Verify
--apply <issue-id-list>arg present; if absent HALT with usage hint - Build
MOST_RECENT_AUDIT_PATHviaGlob wiki/maintenance/audit-*.mdsort by mtime descending
Phase B: Load the most recent audit report
- Read
MOST_RECENT_AUDIT_PATH; parse issue IDs from the FOLLOWUPS:skills block + the classifier sections
Phase C: Match requested IDs
- HALT if any ID not found
- Warn if audit is >7 days old (state may have drifted)
Phase D: Classify each fix by safety
- SAFE-AUTO: missing frontmatter field add,
updated:bump, wikilink correction WHEN target unambiguous (single-candidate basename), template-drift fix - NEEDS-CONFIRM: file rename, file move, content modification, MOC link insertion, batch frontmatter rewrite
- BLOCKED: any deletion (move-to-archive only via
.claude/skills/_archive/)
Phase E: Per-fix preview
- Each fix shows diff (current state vs proposed state)
- SAFE-AUTO fixes batched into single preview block
- NEEDS-CONFIRM fixes presented individually
Phase F: Explicit user confirmation
- One prompt per NEEDS-CONFIRM
- One batch-yes for all SAFE-AUTO
Phase G: F11 set
touch .claude/state/auto-commit-disabled-- only AFTER user confirmation, and BEFORE any Write
Phase H: Atomic apply
- Execute all confirmed fixes as single atomic commit
- Body-preservation sha256 invariants on every Edit
- Path-guard mechanical check on every Write target (defense in depth)
Phase I: Mid-batch F.halt
- If any Edit fails, IMMEDIATE HALT, F11 stays on
- Structured report (succeeded / failed / not-attempted)
- No partial commit
Phase J: Repair audit log
- Write
wiki/maintenance/repair-<date>[-HHMM].md - List each issue ID, classification, action, before/after sha256
- F14 narrow-stage all touched files
Phase K: Atomic commit
- Prefix
vault: repair -- <X> SAFE-AUTO + <Y> CONFIRMED applied - F17 verify
Phase L: F11 clear
rm .claude/state/auto-commit-disabled
MODE: refresh -- 8 atomic operations
Phase A: Pre-flight
- Same as audit Phase A (args + flags, today's ISO date,
OUTPUT_PATHresolution,-HHMMcollision check, F11 collision check)
Phase B: State-transition print
- Same as audit Phase B: emit planned reads + planned writes + collision-handled output path to stdout BEFORE F11 is set
Phase C: F11 set + load all Atlas/sources/*/ref-*.md AND every skill ref doc
Skill ref docs: glob BOTH .agents/skills/*/ref-*.md (canon) and .claude/skills/*/ref-*.md (generated mirrors + still-unmigrated skills), then dedupe by <skill>/<ref-filename> keeping the canon copy -- so a migrated skill's ref doc is ranked ONCE.
Phase D: Compute staleness
- Per ref doc: days elapsed since its
updated:frontmatter date
Phase E: Compute path-activity-since-update
- For each ref doc, count files in same domain subtree created/modified after ref-doc's
updated:date - Signals ref doc may be missing recent findings
Phase F: Compute priority score
priority = days_stale * path_activity * thesis_importance_weight- Weights from
ref-stats-catalog.md: theme-alpha=1.5, theme-beta=1.2, theme-gamma=1.0, theme-delta=1.0, theme-epsilon=0.8, meta=1.1 (personal domains carry their own weights and are not included in this copy)
Phase G: Compose ranked refresh report
- Output:
wiki/maintenance/refresh-<today>[-HHMM].md - FOLLOWUPS:skills block emits
/deepcandidates for top-3 priority refs (Pattern 21 candidates)
Phase H: Atomic write + Phase P peripheral
- Write the refresh report + sidecar, F14 narrow stage, atomic commit, F17 verify, F11 clear -- then the audit-mode Phase P peripheral updates (sessions-log entry; hot.md bump), skipped under
--no-peripheral
Audit classifier reference
9 classifiers with detection rules + severity tiers + safe vs needs-confirm repair patterns in ref-audit-classifiers.md (~600-900 lines). The Phase D-H sections above list classifier names + severity; the ref doc holds full detection logic + repair-classification rules + worked examples per classifier.
Statistics catalog reference
18 statistics with formulas + thesis-importance weights + Brier-score calibration mechanics in ref-stats-catalog.md (~400-600 lines). Stats mode Phase D-J lists statistic names; the ref doc holds computation logic + freshness-bucket boundaries.
Output schema reference
Canonical frontmatter + body section order + meta.json schema for audit / stats / refresh / repair reports + daily-note 9-section schema in ref-output-templates.md (~300-400 lines). All output paths and formats specified there.
Migration note (v1 -> v2)
| v1 element | v2 fate |
wiki/meta/vault-*.md output path | DEPRECATED -- new path wiki/maintenance/. Old reports left in place; v2 audit skips reading them. |
/vault health (mode name) | RENAMED /vault audit; old name accepted as alias with deprecation warning |
/vault report (mode name) | RENAMED /vault stats |
/vault fix (mode name) | RENAMED /vault repair --apply <ids>; explicit issue IDs replace open-ended interactive |
| 7-step health scan | EXPANDED to 9 classifiers; Classifiers 6-9 NEW (frontmatter-schema, deprecated-references, daily-continuity, template-drift) |
| Thesis weights inline in /vault refresh | MOVED to ref-stats-catalog.md |
Daily template recreate (v1 step in /vault daily) | REMOVED -- canonical creation path is tools/session-start.sh; /vault daily HALTs if missing rather than recreating (avoid divergence) |
Coordination with other skills
- /retro -- session-end retro consumes /vault FOLLOWUPS:skills; sessions-log entry parsed for continuity
- /enrich -- /vault audit surfaces frontmatter-schema fixes as /enrich candidates; /enrich's onboarding can introduce broken back-links that /vault audit detects
- /spark -- /vault stats output feeds /spark Class 8 (tool-skill usage pattern) detection; /spark FOLLOWUPS may surface /vault candidates for meta-pattern detection
- /deep -- /vault refresh top-3 priority refs become /deep candidates (Pattern 21 Deep Research recomposition)
- /brief -- /vault stats vault-health-score read by /brief Phase B as one input to overall-state assessment
- /ingest -- distinct skill (transformational); /vault is preservational + diagnostic
- /invest -- /vault audit checks its output paths for orphans + frontmatter compliance
Path-guards (mechanical)
NEVER write to: .raw/, private/, finance/, credentials/. NEVER delete (move-to-archive only via .claude/skills/_archive/ per .agents/skills/AGENTS.md). All writes route through wiki/maintenance/ (audit/stats/refresh/repair reports), Calendar/decisions/sessions-log.md (append), Calendar/daily/ (today only, Sessions Run section append for --append), wiki/hot.md (last_audit/last_stats frontmatter bump), _templates/daily.md (template-drift repair only via /vault repair --apply T1).
Tag vocabulary guardrail
Audit report tags: topic/vault-maintenance, topic/integrity, topic/<mode-stem> (e.g., topic/audit). Forbidden: domain/*, type/*. Frontmatter MUST have categories: [wiki] and type: report.
Failure taxonomy
| Failure | Phase | Symptom | Recovery |
| F11 collision | A | another skill in-flight | Wait OR rm .claude/state/auto-commit-disabled if confirmed orphan |
| Same-day collision | A | OUTPUT_PATH exists | Default -HHMM; user can --replace |
| vault-audit.py failure | D (audit) | script exits non-zero | HALT; surface stderr; suggest manual classifier 1-5 fallback (rare; script is stable) |
| No Agent tool in the harness | D (audit) | non-dispatching harness | Run Phase D.1 python tools/vault-audit.py --json as the normal path; report mode: inline (no Agent tool) |
| Audit too old for repair | C (repair) | most-recent audit >7d | Warn; user explicitly confirms or runs fresh /vault audit first |
| Issue ID not found in audit | C (repair) | --apply <id> doesn't match any audit finding | HALT; show valid IDs from audit |
| Pre-Output gate failure | K | any of 18 invariants violated | HALT with item-specific diagnostic; F11 stays on |
| ASCII byte >127 | L | non-ASCII in NEW content | Replace and retry; do NOT proceed |
| Mid-batch Write failure | O | first Write succeeded, second failed | F.halt; F11 stays on; structured report; user git checkout -- <orphan> or fix-and-retry |
| Body-preservation sha256 violation | H (repair) | Edit changed content outside intended insertion site | F.halt; back out the Edit; sha256-preserving retry |
| Daily-note absent | A (daily) | today's daily missing | HALT with diagnostic; do NOT recreate (canonical path is session-start.sh) |
| Schema-drift on today's daily | D (daily) | <9 sections present | report; offer /vault repair --apply S1 |
| F17 verify fail | P | Co-Authored-By in commit body | git commit --amend to remove |
Examples
Example 1: default audit (post-deprecation health check)
/vault -> reads vault state including _archive/ deprecation list; runs 9 classifiers (5 wrapped from script + 4 inline); composes audit report + sidecar; surfaces FOLLOWUPS for any CRITICAL/WARNING findings; updates sessions-log + hot.md last_audit + last_audit_score. Use after major skill changes (like the 2026-04-26 /research + /review deprecation).
Example 2: stats with continuity scoring
/vault stats -> computes 18 statistics; reads prior 3 stats reports for Brier calibration; reports vault-health trend (improving / stable / declining); writes wiki/maintenance/stats-2026-04-26.md. Use weekly for vault-health continuity tracking.
Example 3: daily-note schema verification
/vault daily -> reports today's note state; flags missing canonical sections; surfaces /vault repair candidates for schema fixes. No file write unless --append.
Example 4: repair after audit
/vault audit -> finds 7 broken wikilinks (L1-L7) + 12 missing frontmatter (F1-F12) + 3 deprecated-references (D1-D3) + 1 template-drift (T1).
Then: /vault repair --apply L1-L3,F1-F12,T1 -> classifies (L1-L3 mixed; F1-F12 SAFE-AUTO; T1 SAFE-AUTO); per-fix preview; user confirms NEEDS-CONFIRM individually + batch-yes for SAFE-AUTO; atomic apply; repair audit log written.
Example 5: refresh ranking
/vault refresh -> reads all 23 ref docs; computes staleness * path-activity * thesis-weight; ranks; FOLLOWUPS surfaces /deep candidates for top-3 priority. Use before next /deep invocation to choose highest-leverage Pattern 21 onboarding target.
Example 6: scoped audit
/vault audit --scope Atlas/concepts/investing/theses/ -> narrows scan to thesis essays only; useful for thesis-evolution-aware audits before /challenge invocations.
Related skills
/retro-- session-end retrospective; consumes /vault FOLLOWUPS/enrich-- consumes /vault FOLLOWUPS frontmatter-schema fix candidates/spark-- consumes /vault stats vault-health-score; surfaces /vault FOLLOWUPS for meta-pattern detection/deep-- consumes /vault refresh top-3 ref docs (Pattern 21 candidates)/brief-- reads /vault stats vault-health-score as one input/tasks-- archived skill (was a Tasks-plugin wrapper; not vault-integrity)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

