feat: vault hygiene — recalibrate oversized, add stub detector, vault-gardener remediation skill - #8
Merged
Merged
Conversation
The audit worklist was untrustworthy because oversized flagged 35% of the real vault: its 1200-token threshold sat near the median note size. Raise the default size_threshold to 4000 tokens (token percentiles on the real vault: p50 750, p90 3700, p95 5150), so it flags the genuinely-bloated top ~7% (350 -> 78 on that vault) rather than the median. Tunable per vault. Add a `stub` detector for near-empty notes worth merging or archiving, kept high-confidence to avoid new noise: a note is a stub only when its body is below stub_threshold tokens (default 20) AND it has zero outbound resolved links (a thin note that links out is an intentional map/index stub) AND it is not under the expected-orphan folders (Journal/Notes/Archives). On the real vault this is a tight 33 findings. Both are content detectors, unaffected by exclude_from_graph. Documented in CONFIG.md and the [health] config stanza. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The audit detectors surface findings but nothing acted on them, leaving a guilt-list. vault-gardener is the remediation counterpart: it reads the `hebb audit` worklist and, one finding at a time, proposes a concrete propose-diff-confirm fix, applies only after confirmation, and never deletes (archive-with-tombstone, git-backed, reversible). It is generic and defers folder/convention specifics to the vault's CLAUDE.md. Category playbook, highest-confidence first: ambiguous_link (disambiguate to a single target), para_drift (move done projects to the archive with a tombstone), stub (merge into a related note or archive). Dangling/unresolved links are left alone by default (usually intentional future-notes); oversized splitting is the heaviest case and only on request. Regulated/compliance notes are never archived or consolidated without explicit per-note confirmation. Auto-embeds and auto-installs via the existing plugin/skills enumeration; plugin README skill list refreshed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR shifts vault-health work toward practical “vault hygiene” by (1) recalibrating the oversized detector so it flags truly large notes, (2) adding a conservative stub detector for near-empty notes, and (3) introducing a vault-gardener skill to remediate audit findings via a confirm-before-apply workflow.
Changes:
- Raised the default oversized threshold from 1200 → 4000 tokens and updated config/docs/tests accordingly.
- Added a new
stubhealth detector (near-empty + no outbound resolved links + not under expected-orphan folders), plus CLI/help/type ordering updates. - Added a new
vault-gardenerremediation skill and documented it in the plugin README.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| plugin/skills/vault-gardener/SKILL.md | New skill documentation/playbook for remediating hebb audit findings. |
| plugin/README.md | Documents additional shipped skills including vault-gardener. |
| core/vaultconfig.go | Adds stub_threshold config + raises default size_threshold to 4000; updates config writer comments. |
| core/health.go | Adds stub finding type + detectStub implementation and runs it in the health pipeline. |
| core/health_test.go | Updates oversized tests for new default + adds focused stub-detector coverage and recalibration assertions. |
| core/graph_test.go | Adjusts oversized test fixture to exceed the new 4000-token default. |
| CONFIG.md | Updates config reference to new defaults and documents stub_threshold. |
| cli/health.go | Adds stub detector to help text and output ordering. |
| cli/health_test.go | Updates oversized fixture to exceed the new default threshold. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- The stub detector ran a COUNT(*) per candidate to check for outbound resolved links (an N+1 that would slow `hebb audit` on large vaults). Build the set of notes with a resolved outbound link in one query, then test membership in Go. - Update the Phase 2a comment to list all content detectors (it omitted the new stub detector and ambiguous_link). - vault-gardener skill: "revertable" -> "revertible". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Owner
Author
|
Thanks, all three addressed in the latest commit:
Stub detector tests still pass; full suite green. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pivots from the speculative durability track (Phase 3+) to practical vault hygiene that delivers value now. Grounded in measurements against the real ~1000-note vault.
Move 1 — make the audit worklist trustworthy
Recalibrate
oversized. It flagged 35% of the vault because the 1200-token threshold sat at the median note size (token percentiles: p50 750, p90 3700, p95 5150). Default raised to 4000 tokens, so it flags the genuinely-bloated top ~7% (350 → 78 on the real vault). Tunable per vault.Add a conservative
stubdetector. Near-empty notes worth merging or archiving, kept high-confidence to avoid new noise: body understub_thresholdtokens (default 20) AND zero outbound resolved links AND not under the expected-orphan folders. On the real vault this is a tight 33 findings.Move 2 — remediation, not just detection (
vault-gardenerskill)The detectors surfaced ~600 findings with no way to act on them.
vault-gardeneris the remediation counterpart: reads thehebb auditworklist and, one finding at a time, proposes a propose-diff-confirm fix, applies only after confirmation, and never deletes (archive-with-tombstone, git-backed, reversible). Generic; defers conventions to the vault'sCLAUDE.md.Category playbook (highest-confidence first):
ambiguous_link(disambiguate, 142 on the real vault),para_drift(archive done projects with a tombstone),stub(merge or archive). Dangling/unresolved links are left alone by default (intentional future-notes);oversizedsplitting is the heaviest case and on request only. Regulated/compliance notes are never archived or consolidated without explicit per-note confirmation.Auto-embeds and auto-installs via the existing
plugin/skillsenumeration.Real-vault audit, before → after
Deferred (deliberately)
Durability / Phase 3 (speculative, two-week experiment), dedup (needs the precision test first), broken-attachment and tag-hygiene linters (low volume / tags barely used on this vault).
Full suite green; verified end-to-end against the real vault (read-only, temp index).
🤖 Generated with Claude Code