Skip to content

feat: organize-wiki companion skill organizes the paper library with the user - #91

Merged
917Dhj merged 2 commits into
developfrom
feat/organize-wiki
Nov 7, 2026
Merged

917Dhj merged 2 commits into
developfrom
feat/organize-wiki

Conversation

@917Dhj

@917Dhj 917Dhj commented Nov 7, 2026

Copy link
Copy Markdown
Owner

Summary

A new companion skill, organize-wiki (整理知识库), keeps the paper library in domain folders the user agrees with. It writes <Vault>/DeepPaperNote/domains.md, the convention DeepPaperNote's router (#90) reads.

SKILL.md
  1. Read the library      scan_library.py      read-only: domains, papers + tag status, anomalies,
                                                 domains file, research memory
  2. Agree on the convention  interview rounds  merge / split / rename / add, with evidence
  3. Plan the changes         grouped plan      folder changes · moves · tag fixes · structure ·
                                                 needs your judgment
  4. Preview, confirm, apply  organize.py preview -> apply --expected-digest
  5. Report                                      log path; "undo --latest" restores
skills/organize-wiki/
├── SKILL.md, README.md, agents/openai.yaml
├── references/file-contract.md   # layout, domains file, scan, plan, log
└── scripts/                      # standard library only, no DeepPaperNote imports
    ├── wiki_vault.py             # vault lookup, frontmatter, vault lock
    ├── domains_file.py           # parse / render domains.md
    ├── scan_library.py           # read-only scan
    └── organize.py               # preview · apply · undo · verify

What apply does

  • It takes the vault lock first; this is .deeppapernote.lock, the same lock DeepPaperNote holds while saving.
  • It refuses unless the plan digest from preview still matches the library and the plan.
  • It moves only whole paper folders, plus flattening nested folders and wrapping loose files. It never renames a paper folder or a note, so links by file name keep working.
  • It rewrites [[…]] and ](…) links that spell out a moved path, everywhere in the vault.
  • It normalizes papers/ tags: the new domain's tag comes first, the tag of the domain being left is dropped, and any other papers/X becomes the topic tag X. Notes without frontmatter are moved but never edited.
  • It logs every step with the file's text before the change, so undo --latest can restore it. Undo first checks every touched file and changes nothing if any of them was edited since.

DeepPaperNote side

  • The final report suggests organize-wiki when a save creates a new domain.
  • domain-routing.md names organize-wiki as the owner of the domains file.
  • A cross-skill test checks that DeepPaperNote's parser reads what organize-wiki writes, in both languages.
  • README (en/zh) and CHANGELOG list the new skill.

Evidence

  • Tests: python3 -m pytest -q reports 1746 passed; before this change the count was 1719.
    • 26 new tests in skills/organize-wiki/tests cover the scan, preview, apply, undo, verify, refusals, the lock, and stale-preview refusal.
    • 1 new cross-skill compatibility test was added.
  • Acceptance on a full copy of the maintainer's real vault (840 MB, 117 paper folders): scan → preview → apply → verify → undo, with byte-level snapshots before apply and after undo.
Before After apply
Domains 12 10, all listed in domains.md
Tags conforming 31 58
Mismatched / multiple papers/ tags 14 / 12 0 / 0
Notes without frontmatter (left alone) 44 44
Anomalies 5 3 (images/index.md, report-only by design)
  • verify reported no issues after apply.
  • DeepPaperNote's domain_overview read the new convention.
  • After undo --latest, all 4,024 paths matched the pre-apply snapshot byte for byte. The only addition is the log folder, which is kept by design.
  • The first round found one gap, now fixed and covered by tests: notes inside a nested folder did not count toward the paper's tag status.

Merge Danger

Door: two-way. The skill only acts when the user invokes it and confirms the preview, and every reorganization can be undone.

Blast Radius: user's vault. A confirmed apply moves folders and edits notes across the vault. The guards are the preview, the digest check, the shared lock, rollback on failure, and logged undo.

🤖 Generated with Claude Code

917Dhj and others added 2 commits November 7, 2026 10:57
…the user

The agent reads the library and the research memory, agrees on the domain
convention with the user in short rounds, and plans folder changes, moves,
tag fixes, and structure repairs. scripts/organize.py previews the plan
without writing, applies it under the vault lock only with the previewed
digest, rewrites path links, normalizes papers/ tags, writes
<Vault>/DeepPaperNote/domains.md, logs every step, and undoes the last
reorganization when the touched files are unchanged.

DeepPaperNote's final report suggests organize-wiki when a save creates a
domain, and a cross-skill test keeps the domains file readable by
DeepPaperNote's router.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Non-ASCII JSON on stdout raised UnicodeEncodeError under cp1252. The tests
now run the scripts with PYTHONIOENCODING=cp1252 to catch this on every OS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@917Dhj
917Dhj merged commit ec0436f into develop Nov 7, 2026
3 checks passed
@917Dhj
917Dhj deleted the feat/organize-wiki branch November 9, 2026 07:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant