v3.3.0 — Bilingual Compatibility & Audit Complete

Cross-Client Compatibility (4-round audit)

• English/Chinese script parity — double-link-builder now detects English roadmap filenames, writes English section headers, generates language-matched backlinks. English vaults no longer get Chinese headers or broken links.
• Numeric version sort — roadmap versions sorted by number (v10 > v2 > v1), not string order
• Bilingual auxiliary file filter — English Core Questions, Deep Research, and Controversy Analysis files excluded from note scanning (was Chinese-only)
• Incremental mode fix — title→path mapping for correct new/old note classification

Bug Fixes

• pypdf NameError — unified module import prevents crash when only pypdf is installed
• pypdf guard — \ check returns None instead of NameError
• Test isolation — English vault tests now use temp directories (no fixture pollution)
• Roadmap write-back — only rewrites file when actually modified

Quality

• 68 tests (up from 57)— 5 English fixture tests, 3 version sort tests, 3 auxiliary file filter tests
• 6 files synced to v3.3.0
• 0 test failures

Links

• Release page
• Dev.to

v3.2.0 — Multi-Format & State Reliability

New

• Multi-format support — Word (.docx), PowerPoint (.pptx), and HTML files are now recognized as input formats. The Agent's Read tool natively supports these formats; the change was removing implicit format restrictions in SKILL.md documentation.
• Key=value state parsing — Step 6.5 now reads stats from .obsidian-learning-progress.md using simple line.split('=') instead of rescanning files. No parser dependency, no YAML risk.

Code Audit (from v3.1.1)

• Removed 754 lines of dead/duplicated code
  • roadmap-editor.py (492 lines) — never called by any Phase
  • obsidian-structure.md (206 lines) — 80% redundant with SKILL.md
  • SKILL.md deduplication (56 lines) — 5 agent file cross-references cleaned up
• Fixed 6 audit issues — dead references, orphaned step numbering, file inventory accuracy, ambiguous headings

Quality

• 57 tests passing
• vf_version v3.2.0 synced across all files

Removed (754 lines)

• roadmap-editor.py (492 lines) — dead code
• obsidian-structure.md (206 lines) — 80% redundant
• SKILL.md deduplication (56 lines) — delegated to agents

Fixed (6 audit issues)

• Dead references removed, Phase 4.2b→4.2, file inventory updated, Step 2.1 disambiguated, Phase 4.4 added to overview, error handling wording

57 tests passing.

VaultForge v3.1.0

New — Achievement Share Cards

• Two styles, randomly selected at render time:
  • Style A — 1:1 square with graph view background + frosted stat panels
  • Style B — 3:1.8 portrait with hero image + inline stat dividers
• Language-aware slogans (English / 中文)
• Real Obsidian-style graph view as background (graph-bg.svg)
• QR code links to GitHub repo
• Share page with X / LinkedIn / Copy / Download buttons

Fixes

• Phase 3.1: ceil(n/10) agent distribution, 5-minute timeout for parallel dispatch fallback
• Phase 3.0b: context-extractor blank-line-tolerant parser + diagnostics
• Phase 4: unified step numbering (4.1→4.2→4.3, no more loop)
• Phase 4.1: scope fix — pass learning folder, not vault root
• Phase 6: explicit deep-research skill loading, MCP tool name fix
• Step 6.5: strict counting rules (scan files, never estimate)
• Step 6.5: source words from Phase 1.2, exclude MOC/roadmap from notes & links

Quality

• 58 tests · 7 cross-file contracts · vf_version v3.1.0 synced across all files

Links

• Release page
• Dev.to

VaultForge v3.0.0

VaultForge evolves from a one-shot PDF-to-notes tool into a continuous knowledge management system.

Core Capabilities

7-Phase Pipeline — Phase 0 vault scan detects existing notes and offers incremental, fresh, or skip modes. Phases 1-6 process materials with state machine resilience, atomic write protection, and five-type wikilink classification.

Incremental Learning — Add new materials to existing vaults. Only new content is processed; existing notes are protected by a three-tier ACL (pristine / user-modified / locked). New-to-existing wikilinks are suggested, not auto-written.

Reliability — Five-state state machine (draft → filling → filled → reviewed → needs_review) with crash recovery. Atomic writes (.md.tmp → verify → rename). Eight degradation paths. Automatic quality review with up to 2 repair attempts.

Quality — 58 automated tests. 7 cross-file contract tests. 16/16 audit items closed. 19/19 cross-file consistency checks. Bilingual support (English / 中文).

Links

• Release Page
• Design Story on Dev.to

v2.3.0 — Audit Complete

All 16 issues from the comprehensive v2.2.0 audit are now resolved.

This Release (M2, M3, L4)

• M2: Phase 0.2 file classification restructured to two-layer system (Status: NEW/DONE + Format: PDF/Markdown/Text). Phase 1.2 display updated.
• M3: Phase 0 Step 0.4 — degradation & error handling table (missing progress file, permission errors, hash mismatch, orphan notes, vf:true false positives).
• L4: CrossFileConsistencyTest class — 7 new cross-file invariant tests (vf_version consistency, naming convention, stale version banners, Phase 0 agent check, incremental_mode coverage, agent language requirement). Test suite: 51 → 58 tests.

Full Audit Resolution Summary

Files Changed (aggregate v2.2.0 → v2.3.0)

• SKILL.md (+53, +26, +49 lines across 3 releases)
• README.md (-version numbers)
• roadmap-generator.md (+35 lines)
• atomic-note-filler.md (+29, +29 lines across 2 releases)
• note-reviewer.md (+26 lines)
• file-structure-creator.md (+6 lines)
• templates.md (+2 lines)
• context-extractor.py (+18 lines)
• double-link-builder.py (+inc mode)
• test_skill_integrity.py (+86 lines, +7 tests)

v2.2.2 — Audit Fixes

Fixes 10 of 16 issues found in the comprehensive v2.2.0 audit.

CRITICAL Fixes

• C1: Roadmap naming unified to v1/v2/v3 convention across all files. Phase 0 added backward compat with legacy no-suffix format.
• C2: Removed all version numbers from README (no more stale v2.1 banners).
• C3: Defined vf_status value table (pristine/user_modified/locked). locked = user explicitly freezes note from auto-refresh.
• C4: Documented Phase 0 as main-agent-only orchestration (no separate sub-agent file needed).

HIGH Fixes

• H1: roadmap-generator.md Step 5 — file-based statistics parsing (H2/H3/bullet counts, proportion check, hierarchy check).
• H2: atomic-note-filler.md Phase 3 Entry Check — breakpoint recovery flow and context pre-extraction orchestration.
• H3: note-reviewer.md +2 review dimensions: Status Integrity (.tmp orphans, status completeness) and Wikilink Integrity (MOC↔atomic, roadmap↔MOC).

MEDIUM/LOW Fixes

• M1: Fixed {v1}/{v2} curly brace placeholders in templates.md.
• M4: Added vf_ frontmatter to Phase 2 blank note templates.
• L2: note-reviewer now checks vf_ fields in Obsidian Format.
• L3: SKILL.md Phase 3.3 passes incremental_mode to reviewer.
• L5: Phase 2.2 shared responsibility table for ## Related Notes content.

v2.2.0 — Pristine Note Refresh

Completes the incremental update loop: when new source material covers existing topics, VaultForge can now regenerate notes while preserving frontmatter.

How It Works

1. Detection (Phase 5.4): During Update Report generation, the agent compares each pristine note's topic against the new roadmap. Notes with matching topics AND more source pages are listed as refresh-eligible.

2. User Selection: After the Update Report, the user sees a checklist:

   📋 Notes eligible for refresh:
    1. [ ] digital-maturity-model.md — 8 new source pages
    2. [ ] five-stage-model.md — 3 new source pages
    Reply "refresh 1,2" to regenerate, or "skip" to ignore.
   

3. Execution (Phase 5.4b): For each selected note:

   • Frontmatter preserved (title, vf, vf_version, vf_status, tags, aliases)
   • date updated to current, vf_session set to refresh-YYYY-MM-DD
   • Body replaced with fresh content from expanded source pages
   • Atomic write protection (.md.tmp → verify → rename)

File Changes

• SKILL.md: Step 5.4b refresh flow (detection logic, user interaction, execution)
• agents/atomic-note-filler.md: Refresh Mode — frontmatter handling table, body replacement rules
• scripts/context-extractor.py: --note-filter for selective extraction
• README.md: updated pipeline and engineering guarantees

v2.1.0 — Incremental Update

New Feature: Incremental Update Mode

VaultForge can now update an existing knowledge base with new materials without touching user-edited notes.

Phase 0: Vault Scan — auto-detects existing vf notes, classifies files as NEW/DONE, offers incremental/fresh/skip.

Add-only rules — never renames, moves, or deletes existing files. Creates only what's new.

vf_ frontmatter — all notes now carry vf: true, vf_version, vf_status (pristine/user_modified/locked), vf_session for traceability.

Update Report — after incremental run, a VaultForge Update Report - {date}.md summarizes new files, wikilinks, refresh-eligible notes, and protected notes.

New→Old wikilinks — new-to-existing links are suggested (not auto-written), collected in a JSON file for user review.

File Changes

• SKILL.md: Phase 0 + incremental branches in Phase 1-5
• agents/file-structure-creator.md: add-only incremental instructions
• agents/atomic-note-filler.md: vf_ frontmatter standard
• agents/note-reviewer.md: incremental_mode parameter
• references/templates.md: Update Report template
• scripts/double-link-builder.py: --mode incremental with new-notes and output-suggestions
• README.md: v2.1 docs (Phase 0, incremental FAQ, 7-phase pipeline)
• tests/test_skill_integrity.py: fixed for Phase 0 numbering

Breaking: Renamed to VaultForge

• obsidian-learning → VaultForge
• Old repo URL auto-redirects

Internationalization

• English-first README with bilingual Chinese section
• Language selection at very first step (English / 中文)
• All agent instructions & reference files in English
• Section header mapping for bilingual note output

Engineering

• 5-state status machine for interruption recovery
• Atomic write ( → verify → rename)
• Context pre-extraction via
• Three-stage wikilink funnel (structural → TF-IDF → LLM), ~60-80% recall
• 51 automated tests across 3 test suites

Content Quality

• Bold-labeled section formatting
• Original text citations with 50-150 word quoted passage requirement
• H2 ≥ 2 H3 hierarchy constraint
• File-based roadmap statistics (no model self-report errors)

UX

• Language selection prompt is bilingual
• Phase 5.4 confirmation before Phase 6 deep research
• Core concepts table in README
• GitHub Topics: obsidian, ai-learning, atomic-notes, knowledge-management, agent-skill, note-taking, pdf-to-notes