soia-pkm-maintain-vault-health

soia-pkm-maintain-vault-health

Responsible for the vault'shealth diagnosis and map. It does not move, delete, or archive notes, does not configure AI hooks, and does not replace retrieval skills oriented toward content questions.

Customer-readable description

What this skill can do

Customer goal	Skill behavior	Whether it writes files by default
Check vault health	Scan dead links, duplicate filenames, primary tag drift, untagged items, expired articles, read failures, and report 20/50 section directory numbering drift	No
Rebuild knowledge base map	Generate a temporary preview first; overwrite the configured map file only after the user explicitly requests it	Preview no, yes after confirmation
vault weekly maintenance	Run health checks and summarize changes over the past 7 days; write the weekly brief as authorized	Default no

How customers use it

Provide the vault path; if you want to check primary tags, also provide a whitelist or set it in the private configuration. When only saying "check", output stdout/JSON and do not write to disk. Only write the corresponding artifact when the user explicitly requests "save weekly report" or "rebuild map".

Dependencies and installation

• Python 3 (pure stdlib) is a hard dependency of the script.
• soia-pkm-organize-article-moc is an optional follow-up: when categorization/MOC merging is found to be needed, hand it off, and this skill does not perform it.
• When the health check finds MOC drift, it is only allowed to call organize's rebuild_moc.py --full-rebuild --dry-run to perform a read-only precheck; if unknown topic is nonzero or large-scale deletion/modification is estimated, it must report and stop, and must not directly clear during the health check _MOC/。
• Recommended to install the entire soia-pkm-vault@soia plugin; a single skill can be installed from this repository.

Private configuration:

~/.config/soia-skills/soia-pkm-maintain-vault-health/config.yml
SOIA_PKM_VAULT_HEALTH_CONFIG_FILE=<custom-config-path>

Install the entire domain (Claude Code and Codex share the same domain plugin):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia

Install only this one skill:

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-maintain-vault-health -y

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it and it needs to be installed separately, see docs/install/workbuddy.md。

Private information and intermediate data

Scanning only reads the target vault; by default skips .git、.obsidian、.trash, hidden directories, and all symlinks. Reports must not print file body text, credentials, or environment variable values. Temporary previews are placed in the system temporary directory and can be deleted after completion; if the default map output escapes the vault via a symlink, writing will be refused.

Logs and completion receipt

The receipt must include the number of scanned files, the number excluded/unreadable, the number of findings by category, whether the map/weekly report was written, actual verification, and issues still requiring manual judgment.

Workflow A: Health check (read-only by default)

python3 scripts/lint_vault.py --vault <vault-path> --json

Tag policy defaultNot configured, in this case tag_policy_configured=false and do not judge any first tag as drift. When tag checking is needed, pass:

python3 scripts/lint_vault.py --vault <vault-path> --json \
  --tags "<primary-tag-a>,<primary-tag-b>"

Check results only indicate structural risks: duplicate filenames do not automatically equal errors; only when short wikilinks actually produce ambiguity should they be prioritized for repair. The link index covers Markdown, attachments,.base and other real files, and attachment dead links must not be skipped by extension.

Link determination has two fixed exceptions:

• Parse filenames by their full name first, then determine the extension;[[持续交付2.0]]、[[Fastjson-1.2.83]] notes like this that contain a decimal point must not be treated as missing attachments.
• frontmatter's topics / people is the category and attribution vocabulary; it does not require every term to have a note of the same name; wikilinks in these fields do not count as dead links.book、source, the body, and explicit attachment links must still point to real files.

When a nonexistent category/attribution is found, the organizing skill should keep it as plain text and state "no corresponding note yet"; do not batch-create empty notes just to make lint pass.

Spelling errors that can be uniquely matched may be listed separately in a plan when the user requests a fix; when there are multiple candidates, semantic categorization, or deletion needs, only report.

Zone 20/50 structure check

The health receipt must additionally report: whether the Zone 20 featured first-level directories contain only 10_主题知识、20_规范与手册、30_学习指南; the unnumbered count and duplicate-number count of all semantic second-level/third-level modules under these directories; whether legacy 10_融合分类still exists; whether historically imported first-level categories use 10_保险、20_读书、30_工作、40_技术、50_日记、60_生活、70_写作、80_学习、90_资源. Zone 50 first-level directories must be limited to 10_草稿、15_待审核、20_发布、90_归档, and ordinary semantic topic directories under them are likewise checked for unnumbered and duplicate numbers. Year/month/day,assets and other explicit resource directories and hidden plugin state directories should be listed separately as exceptions and not counted as unnumbered. When duplicates or unnumbered items are found, only generate a remediation checklist; do not automatically rename during the health check; turn to soia-pkm-manage-vault-lifecycle。

Workflow B: Rebuild the map

Preview first:

python3 scripts/gen_vault_map.py --vault <vault-path> --output <temporary-preview.md>
python3 scripts/gen_vault_map.py --vault <vault-path> --output <temporary-preview.md> --full   # 对 >40 文件目录逐条列出，供归档/迁移后人工核对

Only after user confirmation omit --output, write to SOIA_VAULT_MAP_OUTPUT or the default <vault>/20_资料库/OB知识库地图.md. After writing, rerun lint and confirm that the file/directory statistics in the map match the actual scan; if the vault has 20_资料库/资料库.base, then run the lifecycle skill's vault_index_verify.py to verify the file.inFolder root path. For the complete gate, see index-sync-contract.md。

Workflow C: Weekly maintenance

1. Run lint read-only, and use git history or file timestamps to tally changes over the past 7 days.
2. Clearly distinguish: determinable structural issues, design-intentional duplicates, and content issues requiring user judgment.
3. Write the weekly brief only when the user requests saving; the path is determined by the client vault's rules or configuration.
4. The brief always includes: scope and time, changes over the past 7 days, health findings, fixes performed, items for manual handling, verification.
5. If the inspection scope includes 90_系统归档/60_整理与迁移记录, additionally report: the number of directly mixed files, unnumbered semantic subdirectories, version chains (canonical/superseded), a machine list of references to nonexistent paths, and sensitive-field candidates; only report, do not automatically move, redact, or delete.
6. This skill does not move Inbox/workbench content; lifecycle triage turns to soia-pkm-manage-vault-lifecycle。

Boundaries

• Do not delete, move, rename, or archive notes.
• Do not treat PDF/Word/image attachments as directly readable Markdown; attachment body integrity turns to soia-pkm-clip-drive or an explicit OCR process for verification.
• Do not connect to Claude/Codex session logs; turn to soia-pkm-log-agent-sessions。
• Do not answer "what does the knowledge base have about X"; turn to soia-pkm-query-vault。
• Do not use a personal vault's tag table as a public default; tag policy is determined by client configuration.

Acceptance

• The tree hash remains unchanged before and after read-only runs, except for user-authorized artifacts.
• JSON is parseable and includes tag_policy_configured, six categories of findings,20_structure、50_structure and an unreadable summary.
• The map preview does not touch the vault; the formal map is written only after explicit authorization.
• The final receipt lists the commands actually run and the results, and does not treat "script exit 0" as the sole evidence.
• If rebuilding the map involves 20 zones, the receipt must simultaneously list whether the Base exists, whether each root path exists, and the map statistics; when the Base is not configured, explicitly write "not configured" and do not pretend that verification passed.