agentleFS
Seth090502Seth090502/osanwe-public/.agents/skills/vault/SKILL.md

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

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
  1. Very specific:

    NEVER delete files. Move-to-archive only (.claude/skills/_archive/ per .agents/skills/AGENTS.md).

    line 21
  2. Distinctive:

    All findings cite specific files + line numbers.

    line 23
  3. Distinctive:

    Use: post-deprecation health check (after major skill changes), weekly vault-integrity sweep, before-/-after substantial multi-file …

    line 31
  4. Very specific:

    Default with no arguments: audit.

    line 54
  5. Very specific:

    U1 residency gate (orchestration economics, AGENTS.md): Run python tools/run-share.py --current-context FIRST.

    line 64
  6. Very specific:

    Use the Agent tool with subagent_type vault-classifier-sweep.

    line 112
  7. Distinctive:

    All 9 classifier keys present (even if empty arrays)

    line 115
  8. Very specific:

    Check forbidden domain: field absent

    line 144
  9. Very specific:

    Check tags do NOT use forbidden namespaces (domain/*, type/*)

    line 145
  10. Very specific:

    Check status: value within enum (active/paused/done/dropped/stub/deprecated/draft/complete/stale)

    line 146
  11. Very specific:

    Read _templates/daily.md; verify all 9 canonical sections present (Market Pulse / Observations / Decisions / Commitments / Insights / …

    line 168
  12. Distinctive:

    if any GATE finding present, score hard-clamped to <= 90 (surfaces hook-bypass)

    line 194
  13. Distinctive:

    All findings reference specific file paths (not vague "some files")

    line 244
  14. Very specific:

    Write OUTPUT_PATH (audit report).

    line 281
  15. Very specific:

    Read prior wiki/maintenance/stats-*.md last 3 reports.

    line 337
  16. Very specific:

    If absent: HALT with diagnostic Daily note for <today> missing -- bash tools/session-start.sh should have created.

    line 345
  17. Distinctive:

    Read body; verify all 9 canonical sections present

    line 348
  18. Very specific:

    Verify --apply <issue-id-list> arg present.

    line 386
  19. Very specific:

    Read MOST_RECENT_AUDIT_PATH.

    line 390
  20. Distinctive:

    If any Edit fails, IMMEDIATE HALT, F11 stays on

    line 419
  21. Very specific:

    Write the refresh report + sidecar, F14 narrow stage, atomic commit, F17 verify, F11 clear -- then the audit-mode Phase P peripheral …

    line 463

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 wraps tools/vault-audit.py --json and 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 --json directly) as the normal path, reported as mode: 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)

SyntaxBehavior
/vault or /vault auditDefault; read-only integrity audit; 9 classifiers; report + sidecar
/vault statsQuantitative dashboard; 18 statistics; Brier-style continuity score
/vault dailyToday'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 refreshRef-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
--confirmBlock 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-peripheralWrite 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.

  1. Parse args + flags.
  2. Resolve today's ISO date.
  3. Resolve OUTPUT_PATH = wiki/maintenance/audit-<today>.md.
  4. Same-day collision check: if exists, default -HHMM variant; --replace reserved.
  5. F11 collision check (.claude/state/auto-commit-disabled exists -> 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 print

Phase C -- F11 set + parallel context load

  1. touch .claude/state/auto-commit-disabled BEFORE any Write.
  2. Build EXPECTED_ARCHIVED set: 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.
  3. Build KNOWN_DEPRECATIONS set: parse Calendar/decisions/decision-log.md for entries containing "Deprecate" / "deprecated" / "moved to _archive".
  4. 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.
  5. Build CANONICAL_FRONTMATTER_FIELDS: categories (plural list), type (optional), tags (plural), status (enum), created (ISO), updated (ISO), related (wikilinks).
  6. Build FORBIDDEN_FRONTMATTER_FIELDS: domain (stripped per AGENTS.md schema), legacy fields.
  7. 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)
  • totals object with gate, hard_drift, soft_drift counts
  • score integer 0-100
  • score_floor_check in {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):

  1. Broken wikilinks (CRITICAL) -- regex extract [[target]]; verify target file exists; report unresolved
  2. Missing frontmatter (CRITICAL) -- check first line ---; report files lacking frontmatter
  3. Frontmatter-schema (forbidden fields) (GATE) -- forbidden domain: field + domain/* / type/* tag namespaces (the script's detect_forbidden_frontmatter; the fuller categories-plural / status-enum check runs inline at Phase E)
  4. Orphan detection (WARNING) -- entity files with <2 inbound wikilinks; exclude templates + archive folders
  5. Stale refs (WARNING) -- Atlas/sources/*/ref-*.md with updated: >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 categories is 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.md historical 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 Run activity 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)

  1. F11 set
  2. OUTPUT_PATH collision resolved (-HHMM if needed)
  3. Frontmatter complete and schema-compliant on report
  4. =1 finding category populated OR explicit "vault clean" rendered

  5. All findings reference specific file paths (not vague "some files")
  6. Severity classification on every finding (CRITICAL / WARNING / INFO)
  7. FOLLOWUPS:skills block syntactically valid; tied to specific issue IDs
  8. Vault-health composite score computed; rationale included
  9. Continuity comparison vs prior audit (when prior exists) populated
  10. EXPECTED_ARCHIVED exclude-list applied (no false-positive deprecation flags)
  11. CANONICAL_DAILY_SCHEMA reference embedded for template-drift Classifier 9
  12. ASCII-only on report body + sidecar (Pattern 22)
  13. related: field has 3-5 wikilinks (hot, [[knowledge-moc]], peer audit reports if any)
  14. Symmetric back-link plan (hot last_audit bump; sessions-log entry)
  15. Path-guard: no proposed Write targets .raw/, private/, finance/, credentials/
  16. Sessions-log entry composed per canonical schema
  17. hot.md last_audit field present (add if missing)
  18. 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:

  1. H1 + Generated stamp + audit scope
  2. Executive Summary (composite score + finding-count-by-severity)
  3. CRITICAL Findings (with file paths, line numbers, fix recommendations)
  4. WARNING Findings
  5. INFO Findings
  6. Continuity vs Prior Audit (when applicable)
  7. FOLLOWUPS:skills block
  8. 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

  1. Write OUTPUT_PATH (audit report).
  2. Write OUTPUT_PATH-meta.json (sidecar).
  3. F14 narrow stage: git add exactly these 2 files.
  4. F.halt: if either fails, HALT IMMEDIATELY; F11 stays on; structured report; no partial commit.

Phase P -- Peripheral updates (skip if --no-peripheral)

  1. 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]]
  2. hot.md frontmatter bump: last_audit: <today> (add if absent).
  3. hot.md last_audit_score: <N> field (NEW; tracks vault-health continuity).
  4. F14 narrow-stage all touched files; atomic commit vault: audit -- score <N>/100 -- <C>C/<W>W/<I>I.
  5. F17 verify: post-commit git log -1 --format=%B | grep -c Co-Authored-By MUST be 0.
  6. 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

  1. file-counts-by-top-level-path (Atlas / Calendar / Efforts / wiki / private / docs / .agents/skills/ canon active / .claude/skills/_archive)
  2. word-counts-by-top-level-path (with kepano 150-line exception annotation)
  3. entity-coverage (held tickers vs entity-note presence)
  4. ref-doc-coverage (Built vs stub from knowledge-moc table vs frontmatter status)
  5. freshness-distribution (<7d / <30d / <90d / >90d per top-level path)
  6. session-log-entry-count (rolling 30d)
  7. daily-note-continuity-score (1.0 = no gaps; weighted by day-of-week expectations)
  8. skill-invocation-frequency (parsed from session-log entries)
  9. brier-calibration-carry (prior 30d /vault stats predictions vs current state)
  10. avg-wikilinks-per-file
  11. outbound-link-orphans (files with 0 outbound)
  12. inbound-link-orphans (files with 0 inbound; excluding templates/archives)
  13. MOC-coverage-percentage (per MOC: linked-files / total-domain-files)
  14. thesis-essay-activity (mention count per thesis/*)
  15. archive-skill-count (read-only sanity)
  16. active-vs-archived-skill-ratio
  17. 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>.md exists?
  • 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 S1 style 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 Run section
  • 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_result block (paired by tool_use_id to a Bash tool_use that invoked python tools/vault-audit.py --json) appears in the transcript AND that tool_result's content contains JSON with "score": N where 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 Bash tool_use invocation of python tools/vault-audit.py --json and a corresponding tool_result block. Do not stop on partial progress; do not stop on inferred-pass without the structured tool_result block visible. The Haiku-class evaluator reads the structured transcript representation (tool_use/tool_result objects with paired tool_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 clean

The 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_PATH via Glob wiki/maintenance/audit-*.md sort 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_PATH resolution, -HHMM collision 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 /deep candidates 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 elementv2 fate
wiki/meta/vault-*.md output pathDEPRECATED -- 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 scanEXPANDED to 9 classifiers; Classifiers 6-9 NEW (frontmatter-schema, deprecated-references, daily-continuity, template-drift)
Thesis weights inline in /vault refreshMOVED 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

FailurePhaseSymptomRecovery
F11 collisionAanother skill in-flightWait OR rm .claude/state/auto-commit-disabled if confirmed orphan
Same-day collisionAOUTPUT_PATH existsDefault -HHMM; user can --replace
vault-audit.py failureD (audit)script exits non-zeroHALT; surface stderr; suggest manual classifier 1-5 fallback (rare; script is stable)
No Agent tool in the harnessD (audit)non-dispatching harnessRun Phase D.1 python tools/vault-audit.py --json as the normal path; report mode: inline (no Agent tool)
Audit too old for repairC (repair)most-recent audit >7dWarn; user explicitly confirms or runs fresh /vault audit first
Issue ID not found in auditC (repair)--apply <id> doesn't match any audit findingHALT; show valid IDs from audit
Pre-Output gate failureKany of 18 invariants violatedHALT with item-specific diagnostic; F11 stays on
ASCII byte >127Lnon-ASCII in NEW contentReplace and retry; do NOT proceed
Mid-batch Write failureOfirst Write succeeded, second failedF.halt; F11 stays on; structured report; user git checkout -- <orphan> or fix-and-retry
Body-preservation sha256 violationH (repair)Edit changed content outside intended insertion siteF.halt; back out the Edit; sha256-preserving retry
Daily-note absentA (daily)today's daily missingHALT with diagnostic; do NOT recreate (canonical path is session-start.sh)
Schema-drift on today's dailyD (daily)<9 sections presentreport; offer /vault repair --apply S1
F17 verify failPCo-Authored-By in commit bodygit 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)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.