# Roadmap: PaperForge

**Current milestone:** v1.9 Frontmatter Rationalization & Library-Record Deprecation — Planned
**Phase numbering:** Continuous. v1.8 partial ended at Phase 36. v1.9 begins at Phase 37.

---

## Milestones

- ✅ **v1.0 MVP** — Phases 1-5 (shipped 2026-04-23)
- ✅ **v1.1 Sandbox Onboarding** — Phases 6-8 (shipped 2026-04-24)
- ✅ **v1.2 Systematization & Cohesion** — Phases 9-10 (shipped 2026-04-24)
- ✅ **v1.3 Path Normalization & Architecture Hardening** — Phases 11-12 (shipped 2026-04-24)
- ✅ **v1.4 Code Health & UX Hardening** — Phases 13-19 (shipped 2026-04-28)
- ✅ **v1.5 Obsidian Plugin Setup Integration** — Phases 20-21 (shipped 2026-04-29)
- ✅ **v1.6 AI-Ready Literature Asset Foundation** — Phases 22-26 (shipped 2026-05-04)
- ✅ **v1.7 Context-Aware Dashboard** — Phases 27-30 (shipped 2026-05-04)
- 📋 **v1.8 AI Discussion & Deep-Reading Dashboard** — Phases 31-36 (partial — 2/6 phases complete, paused for v1.9)
- 📋 **v1.9 Frontmatter Rationalization & Library-Record Deprecation** — Phases 37-41 (planned)

*Archive: `.planning/milestones/`*

---

## Phases

<details>
<summary>✅ v1.6 AI-Ready Literature Asset Foundation (Phases 22-26) — SHIPPED 2026-05-04</summary>

- [x] Phase 22: Configuration Truth & Compatibility (3/3)
- [x] Phase 23: Canonical Asset Index & Safe Rebuilds (3/3)
- [x] Phase 24: Derived Lifecycle, Health & Maturity (2/2)
- [x] Phase 25: Surface Convergence, Doctor & Repair (3/3)
- [x] Phase 26: Traceable AI Context Packs (3/3)

</details>

<details>
<summary>✅ v1.7 Context-Aware Dashboard (Phases 27-30) — SHIPPED 2026-05-04</summary>

- [x] Phase 27: Component Library (2/2)
- [x] Phase 28: Dashboard Shell & Context Detection (2/2)
- [x] Phase 29: Per-Paper View (1/1)
- [x] Phase 30: Collection View (1/1)

</details>

<details>
<summary>📋 v1.8 AI Discussion & Deep-Reading Dashboard (Phases 31-36) — PAUSED</summary>

- [ ] Phase 31: Bug Fixes — Restore version display; remove meaningless "ai" UI row
- [ ] Phase 32: Deep-Reading Mode Detection — Plugin routes deep-reading.md to dedicated dashboard mode
- [ ] Phase 33: Deep-Reading Dashboard Rendering — Status bar, Pass 1 summary, empty-state AI Q&A card
- [x] Phase 34: Jump to Deep Reading Button — Per-paper dashboard card links to deep-reading.md (completed 2026-05-06)
- [x] Phase 35: AI Discussion Recorder — Python module writes discussion.md + discussion.json into ai/ (completed 2026-05-06)
- [ ] Phase 36: Integration Verification — End-to-end pipeline verified with CJK encoding and vault.adapter.read

</details>

### 📋 v1.9 Frontmatter Rationalization & Library-Record Deprecation (Planned)

**Milestone Goal:** Deprecate the library-records tracking layer, converge all state into formal note frontmatter + per-workspace paper-meta.json, fix Base view field gaps, and stabilize workspace folder construction for both new and upgrading users.

- [ ] **Phase 37: Frontmatter Rationalization** — Slim formal note frontmatter; create per-workspace paper-meta.json; remove library_record_markdown()
- [ ] **Phase 38: Workspace Stabilization** — Direct workspace creation; fulltext bridging; path unification; doctor integrity
- [ ] **Phase 39: Base View Fix** — Remove ghost fields; restore workflow flags; repoint folder filter; regenerate .base files
- [ ] **Phase 40: Library-Record Deprecation** — Skip creation for new users; lossless migration for upgraders; sync stop
- [ ] **Phase 41: Plugin Dashboard Sync** — Verify all components; fix version badge; align lifecycle keys; CSS audit

---

## Phase Details

### Phase 37: Frontmatter Rationalization
**Goal**: Formal note frontmatter is slimmed to identity fields + workflow flags + pdf_path; all internal/derived data moves to per-workspace paper-meta.json.
**Depends on**: Nothing (first phase of v1.9 — builds on v1.8 partial state)
**Requirements**: FM-01, FM-02, FM-03, FM-04, FM-05, FM-06, FM-07
**Success Criteria** (what must be TRUE):
  1. Running `paperforge sync` on a new paper writes formal note frontmatter containing only identity fields (title, year, journal, first_author, doi, pmid, zotero_key, domain, abstract, tags), workflow flags (has_pdf, do_ocr, analyze, ocr_status, deep_reading_status), and pdf_path — no workspace path fields, no OCR infrastructure fields.
  2. Running `paperforge sync` creates `paper-meta.json` in the paper's workspace directory containing ocr_job_id, ocr_md_path, ocr_json_path, the full health dict, maturity breakdown, paperforge_version, and a migrated_from field (when upgrading from library-records).
  3. `_build_entry()` writes the slimmed frontmatter fields into formal notes; the full internal state (workspace paths, OCR details, derived state) remains only in the canonical index JSON and paper-meta.json.
  4. `library_record_markdown()` is removed from the codebase — running `paperforge sync` produces zero new library-record .md files, and git grep confirms zero callers of the removed function.
  5. The existing test suite (317+ tests) passes with no regressions after frontmatter field changes, and formal notes generated by the new `_build_entry()` open correctly in Obsidian with readable frontmatter.

**Plans**: TBD

### Phase 38: Workspace Stabilization
**Goal**: Workspace directories are created directly on first sync; fulltext content is bridged from OCR output; path construction is unified across Python modules.
**Depends on**: Phase 37
**Requirements**: WS-01, WS-02, WS-03, WS-04, WS-05
**Success Criteria** (what must be TRUE):
  1. Running `paperforge sync` on a newly added paper creates the workspace directory (`Literature/<domain>/<key> - <Title>/`) and writes the formal note directly inside it — no flat-first-then-migrate intermediate state.
  2. After OCR completes, the fulltext content at `<system_dir>/PaperForge/ocr/<key>/fulltext.md` is copied or symlinked to the workspace `fulltext.md` path declared in the canonical index entry, and the file is readable in Obsidian.
  3. `discussion.py` reads the workspace `ai_path` from the canonical index entry via `_build_ai_dir()` — independent path reconstruction logic is removed from discussion.py, and git grep confirms zero hardcoded `ai/` path construction in the module.
  4. `migrate_to_workspace()` copies OCR output to workspace `fulltext.md` when migrating old flat notes that have `ocr_status: done` — upgrading users do not lose existing fulltext on migration.
  5. `paperforge doctor` reports workspace integrity issues: missing workspace directories for indexed papers, missing fulltext.md when ocr_status=done, and path construction mismatches between the index and actual disk state.

**Plans**: TBD

### Phase 39: Base View Fix
**Goal**: Obsidian Base views show all workflow flags (has_pdf, do_ocr, analyze, ocr_status), point to the Literature/ folder, and exclude unwritten ghost fields.
**Depends on**: Phase 37
**Requirements**: BASE-01, BASE-02, BASE-03, BASE-04, BASE-05
**Success Criteria** (what must be TRUE):
  1. Opening any Base view in Obsidian shows no `lifecycle`, `maturity_level`, or `next_step` columns — these are dashboard-owned fields that have no .md writer and must not appear in Base views.
  2. All Base views display `has_pdf`, `do_ocr`, `analyze`, and `ocr_status` as filterable columns with correct Chinese display names (e.g., "有PDF", "需OCR", "需分析", "OCR状态"), and toggling these values in the Base view modifies the underlying formal note frontmatter.
  3. Every Base view's folder filter targets `<literature_dir>/<domain>` (e.g., `Literature/骨科/`) instead of `<control_dir>/<domain>` (e.g., `LiteratureControl/library-records/骨科/`).
  4. All 8 workflow views (控制面板, 推荐分析, 待OCR, OCR完成, 待深度阅读, 深度阅读完成, 正式卡片, 全记录) display correct data matching the workflow states defined in formal note frontmatter, with the same filter/sort logic as the current master-branch Base views.
  5. Running `paperforge sync` regenerates all .base files with the corrected properties and folder filters, and opening them in Obsidian shows the expected content without property errors or empty columns.

**Plans**: TBD
**UI hint**: yes

### Phase 40: Library-Record Deprecation
**Goal**: New users never see library-records; upgrading users get automatic lossless migration on first sync; sync stops all library-record generation.
**Depends on**: Phase 39
**Requirements**: LRD-01, LRD-02, LRD-03, LRD-04, LRD-05
**Success Criteria** (what must be TRUE):
  1. A clean install (no existing `<control_dir>/library-records/` directory) runs `paperforge sync` end-to-end without creating `library-records/` — the directory never appears in the vault, and new users never encounter it.
  2. An upgrading user with existing library-record files runs `paperforge sync` and all user-facing workflow flags (has_pdf, do_ocr, analyze, ocr_status, deep_reading_status, recommend_analyze) are merged into corresponding formal notes — spot-checking random library-records confirms frontmatter values match the migrated formal notes.
  3. After migration (or on clean install), running `paperforge sync` for any paper — newly added from Zotero or previously indexed — produces zero new library-record .md files anywhere in the vault.
  4. `run_index_refresh()` orphaned-record cleanup logic operates against formal notes in `<literature_dir>/` — formal notes without a matching Zotero entry are detected and reported with the existing orphan-handling behavior (no silent data loss).
  5. `paperforge doctor` detects a stale `<control_dir>/library-records/` directory, reports the number of files found, and outputs a recommendation to manually delete it (with a `--cleanup-library-records` flag suggestion), without automatically deleting user data.

**Plans**: TBD

### Phase 41: Plugin Dashboard Sync
**Goal**: Plugin dashboard renders correctly in all modes after frontmatter rationalization and workspace stabilization; version badge shows real version; lifecycle keys match Python output; all CSS component styles are present.
**Depends on**: Phase 37, Phase 38
**Requirements**: PLG-01, PLG-02, PLG-03, PLG-04, PLG-05, PLG-06
**Success Criteria** (what must be TRUE):
  1. Opening the PaperForge dashboard in Obsidian after `paperforge sync` shows correct aggregated stats — paper count, fulltext-ready count, deep-read count — in all three modes (global, per-paper, collection) without JavaScript console errors.
  2. All Quick Action buttons (Open Fulltext, Jump to Deep Reading, Copy Context, Copy Collection Context) resolve workspace paths correctly from the canonical index and open the expected files when clicked — file-not-found errors produce an Obsidian Notice instead of a silent failure.
  3. Dashboard lifecycle stepper (6 stages), health matrix (2x2 grid), maturity gauge (6 segments), and lifecycle bar chart render correctly in all three modes with data matching the canonical index entries — visual inspection confirms no regressions from the reference vault dashboard.
  4. Plugin version badge in the header displays the actual `paperforge_version` from `formal-library.json` envelope (e.g., "v1.9.0") on first load — no stale `v—` placeholder; the version updates when `formal-library.json` is modified.
  5. All JS lifecycle key references use `deep_read_done` and `ai_context_ready` matching Python `compute_lifecycle()` output — git grep in `paperforge/plugin/` confirms zero instances of bare `deep_read` or `ai_ready` as standalone lifecycle state keys.
  6. Plugin CSS file contains all dashboard component style classes (`paperforge-metric-card`, `paperforge-lifecycle-stepper`, `paperforge-health-matrix`, `paperforge-maturity-gauge`, `paperforge-bar-chart`, `paperforge-collection-view`, `paperforge-paper-view`, `paperforge-next-step-card`, `paperforge-paper-actions`, `paperforge-mode-deepreading`, `paperforge-loading-skeleton`) and these classes render with correct visual styling in Obsidian dark and light themes.

**Plans**: TBD
**UI hint**: yes

---

## Progress

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 34. Jump to Deep Reading Button | 1/1 | Complete | 2026-05-06 |
| 35. AI Discussion Recorder | 1/1 | Complete | 2026-05-06 |
| 37. Frontmatter Rationalization | 0/TBD | Not started | - |
| 38. Workspace Stabilization | 0/TBD | Not started | - |
| 39. Base View Fix | 0/TBD | Not started | - |
| 40. Library-Record Deprecation | 0/TBD | Not started | - |
| 41. Plugin Dashboard Sync | 0/TBD | Not started | - |

---

*Roadmap updated: 2026-05-07 — v1.9 milestone planned*
