diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index d47b80ba..07710a8b 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -82,36 +82,36 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| CONF-01 | Phase [N] | Pending | -| CONF-02 | Phase [N] | Pending | -| CONF-03 | Phase [N] | Pending | -| CONF-04 | Phase [N] | Pending | -| ASSET-01 | Phase [N] | Pending | -| ASSET-02 | Phase [N] | Pending | -| ASSET-03 | Phase [N] | Pending | -| ASSET-04 | Phase [N] | Pending | -| STATE-01 | Phase [N] | Pending | -| STATE-02 | Phase [N] | Pending | -| STATE-03 | Phase [N] | Pending | -| STATE-04 | Phase [N] | Pending | -| SURF-01 | Phase [N] | Pending | -| SURF-02 | Phase [N] | Pending | -| SURF-03 | Phase [N] | Pending | -| SURF-04 | Phase [N] | Pending | -| AIC-01 | Phase [N] | Pending | -| AIC-02 | Phase [N] | Pending | -| AIC-03 | Phase [N] | Pending | -| AIC-04 | Phase [N] | Pending | -| MIG-01 | Phase [N] | Pending | -| MIG-02 | Phase [N] | Pending | -| MIG-03 | Phase [N] | Pending | -| MIG-04 | Phase [N] | Pending | +| CONF-01 | Phase 22 | Pending | +| CONF-02 | Phase 22 | Pending | +| CONF-03 | Phase 22 | Pending | +| CONF-04 | Phase 22 | Pending | +| ASSET-01 | Phase 23 | Pending | +| ASSET-02 | Phase 23 | Pending | +| ASSET-03 | Phase 23 | Pending | +| ASSET-04 | Phase 23 | Pending | +| STATE-01 | Phase 24 | Pending | +| STATE-02 | Phase 24 | Pending | +| STATE-03 | Phase 24 | Pending | +| STATE-04 | Phase 24 | Pending | +| SURF-01 | Phase 25 | Pending | +| SURF-02 | Phase 25 | Pending | +| SURF-03 | Phase 25 | Pending | +| SURF-04 | Phase 25 | Pending | +| AIC-01 | Phase 24 | Pending | +| AIC-02 | Phase 26 | Pending | +| AIC-03 | Phase 26 | Pending | +| AIC-04 | Phase 26 | Pending | +| MIG-01 | Phase 25 | Pending | +| MIG-02 | Phase 23 | Pending | +| MIG-03 | Phase 25 | Pending | +| MIG-04 | Phase 25 | Pending | **Coverage:** - v1 requirements: 24 total -- Mapped to phases: 0 -- Unmapped: 24 ⚠️ +- Mapped to phases: 24 +- Unmapped: 0 ✓ --- *Requirements defined: 2026-05-03* -*Last updated: 2026-05-03 after v1.6 requirements definition* +*Last updated: 2026-05-03 after v1.6 roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 1080281f..f06f78c5 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -1,8 +1,8 @@ -# Roadmap: PaperForge Lite +# Roadmap: PaperForge **Project kind:** brownfield-release-hardening -**Current milestone:** v1.5 — Obsidian Plugin Setup Integration -**Phase numbering:** Continuous (never restarts). v1.0 Phases 1-5, v1.1 Phases 6-8, v1.2 Phases 9-10, v1.3 Phases 11-12, v1.4 Phases 13-19, v1.5 Phases 20-21 +**Current milestone:** v1.6 — AI-Ready Literature Asset Foundation +**Phase numbering:** Continuous (never restarts). Previous milestone ended at Phase 21, so v1.6 begins at Phase 22. --- @@ -14,201 +14,100 @@ - ✅ **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 (planned) --- +## Overview + +v1.6 turns PaperForge's existing sync, OCR, deep-reading, status, plugin, and `formal-library.json` outputs into one coherent literature asset foundation. The milestone starts by unifying configuration truth, upgrades `formal-library.json` into the canonical derived asset index, derives lifecycle and health from real source artifacts, converges CLI/plugin/Base surfaces on that shared meaning, and then exposes traceable AI context packs on top of trustworthy assets. + ## Phases -
-✅ v1.0 MVP (Phases 1-5) — SHIPPED 2026-04-23 +**Phase Numbering:** +- Integer phases (22, 23, 24...): Planned milestone work +- Decimal phases (22.1, 22.2...): Urgent insertions after roadmap approval -### Phase 1: Config And Command Foundation -**Goal**: Stable commands and shared path/env resolution -**Plans**: 3/3 plans complete - -### Phase 2: PaddleOCR And PDF Path Hardening -**Goal**: Diagnosable, retryable OCR -**Plans**: 2/2 plans complete - -### Phase 3: Config-Aware Obsidian Bases -**Goal**: Real workflow Bases without hardcoded paths -**Plans**: 2/2 plans complete - -### Phase 4: End-To-End Onboarding And Validation -**Goal**: User can complete first-paper flow -**Plans**: 2/2 plans complete - -### Phase 5: Release Verification -**Goal**: Tests and docs prove ship readiness -**Plans**: 2/2 plans complete - -_Archived: `.planning/milestones/v1.0.md`_ - -
- -
-✅ v1.1 Sandbox Onboarding (Phases 6-8) — SHIPPED 2026-04-24 - -### Phase 6: Setup, CLI, And Diagnostics Consistency -**Goal**: Field names, env vars, export validation, HTTP 405 handling, vault prefill -**Plans**: 3/3 plans complete - -### Phase 7: Zotero PDF, Metadata, And State Repair -**Goal**: OCR meta validation, three-way divergence repair, PDF resolver tests -**Plans**: 2/2 plans complete - -### Phase 8: Deep Helper Deployment And Sandbox Regression Gate -**Goal**: Importability, fixtures, smoke tests, rollback -**Plans**: 2/2 plans complete - -_Archived: `.planning/milestones/v1.1.md`_ - -
- -
-✅ v1.2 Systematization & Cohesion (Phases 9-10) — SHIPPED 2026-04-24 - -### Phase 9: Command Unification & CLI Simplification -**Goal**: Unified `/pf-*` namespace, `paperforge sync` combined command -**Plans**: 2/2 plans complete - -### Phase 10: Documentation & Cohesion -**Goal**: Updated AGENTS.md, migration guide, consistency audit -**Plans**: 2/2 plans complete - -_Archived: `.planning/milestones/v1.2-ROADMAP.md`_ - -
- -
-✅ v1.3 Path Normalization & Architecture Hardening (Phases 11-12) — SHIPPED 2026-04-24 - -### Phase 11: Zotero Path Normalization -**Goal**: Parse 3 BBT formats, generate wikilinks, multi-attachment support -**Plans**: 1/1 plan complete -**Requirements**: ZPATH-01, ZPATH-02, ZPATH-03 - -### Phase 12: Architecture Cleanup -**Goal**: Eliminate module boundary leaks (pipeline/ → paperforge/worker/), migrate skills -**Plans**: 1/1 plan complete -**Requirements**: ARCH-01, ARCH-02 - -_Archived: `.planning/milestones/v1.3.md`_ - -
- -
-✅ v1.4 Code Health & UX Hardening (Phases 13-19) — SHIPPED 2026-04-28 - -### Phase 13: Logging Foundation -**Goal**: Structured logging, `--verbose` flag, zero behavioral change to user-facing output -**Requirements**: OBS-01, OBS-02, OBS-03 -**Plans**: 3/3 plans complete - -### Phase 14: Shared Utilities Extraction -**Goal**: Extract `_utils.py`, eliminate ~1,610 lines of duplication across 7 workers -**Requirements**: CH-01, CH-02, CH-05, TEST-03 -**Plans**: 2/2 plans complete - -### Phase 15: Deep-Reading Queue Merge -**Goal**: Single canonical `scan_library_records()` for both CLI and Agent consumers -**Requirements**: CH-03, CH-04 -**Plans**: 1/1 plan complete - -### Phase 16: Retry + Progress Bars -**Goal**: Resilient OCR with exponential backoff and user-visible progress indication -**Requirements**: UX-01, UX-02 -**Plans**: 2/2 plans complete - -### Phase 17: Dead Code Removal + Pre-Commit -**Goal**: Clean codebase validated by automated git hooks (ruff) -**Requirements**: CH-06, CH-07 -**Plans**: 1/1 plan complete - -### Phase 18: Documentation + CHANGELOG + UX Polish -**Goal**: Complete user/maintainer docs, auto_analyze_after_ocr, CHANGELOG, CONTRIBUTING -**Requirements**: DOC-01, DOC-02, DOC-03, UX-03 -**Plans**: 2/2 plans complete - -### Phase 19: Testing -**Goal**: E2E pipeline tests, setup wizard tests, `_utils.py` unit tests (317 passed, 2 skipped) -**Requirements**: TEST-01, TEST-02, TEST-04 -**Plans**: 3/3 plans complete - -_Note: Phase 20 (v1.4.2 "Headless Setup & Obsidian Plugin") was a placeholder. v1.5 expands this into a full plugin settings tab with setup integration — see Phases 20-21 below._ - -_Archived: `.planning/milestones/v1.4.md`_ - -
- -### ✅ v1.5 Obsidian Plugin Setup Integration (Complete) - -**Milestone Goal:** Move the entire PaperForge setup/configuration experience from terminal CLI into the Obsidian plugin's settings tab, so a new user downloads one plugin and completes full installation without touching a terminal. - -- [x] **Phase 20: Plugin Settings Shell & Persistence** — Obsidian settings tab with all setup fields, persistence across restarts, debounced saves (completed 2026-04-29) -- [x] **Phase 21: One-Click Install & Polished UX** — Install button with field validation, `spawn`-based subprocess orchestration, human-readable Chinese notices (completed 2026-04-29) - ---- +- [ ] **Phase 22: Configuration Truth & Compatibility** - Make `paperforge.json` the single runtime truth across CLI, workers, setup, and plugin. +- [ ] **Phase 23: Canonical Asset Index & Safe Rebuilds** - Upgrade `formal-library.json` into a rebuildable, atomic, per-paper asset index. +- [ ] **Phase 24: Derived Lifecycle, Health & Maturity** - Compute readiness, health findings, maturity, and next steps from source artifacts. +- [ ] **Phase 25: Surface Convergence, Doctor & Repair** - Make status, plugin dashboard, Base views, doctor, and repair consume the same canonical semantics. +- [ ] **Phase 26: Traceable AI Context Packs** - Generate explainable paper and collection context packs from canonical assets. ## Phase Details -### Phase 20: Plugin Settings Shell & Persistence -**Goal**: Users can access PaperForge configuration in Obsidian's Settings tab, edit all setup wizard fields, and settings survive restarts and tab switches — all without breaking the existing sidebar. -**Depends on**: Phase 19 (tested deployment pipeline exists) -**Requirements**: SETUP-01, SETUP-02, SETUP-03 +### Phase 22: Configuration Truth & Compatibility +**Goal**: Users can trust one authoritative PaperForge configuration across Python and plugin surfaces, including brownfield vaults with legacy config shapes. +**Depends on**: Phase 21 +**Requirements**: CONF-01, CONF-02, CONF-03, CONF-04 **Success Criteria** (what must be TRUE): - 1. User opens Obsidian Settings → Community Plugins → PaperForge (gear icon) and sees a settings tab with all 8 configuration fields grouped in logical sections with Chinese labels and tooltips - 2. User edits any text field, navigates to a different settings tab and returns — all edited values remain intact (in-memory state survives `display()` re-invocation without data loss) - 3. User fills in all fields, closes and re-opens Obsidian, and all values restore correctly from `data.json` — no data loss, corruption, or `TypeError` on null data - 4. First-time install (no prior `data.json`) loads gracefully with `DEFAULT_SETTINGS` values pre-filled — settings tab renders cleanly without JavaScript errors - 5. After registering the settings tab via `addSettingTab()`, the existing `PaperForgeStatusView` sidebar and command palette actions (`Sync Library`, `Run OCR`) continue functioning without regression + 1. User can inspect the effective runtime configuration and clearly see which values come from authoritative `paperforge.json` fields versus plugin UI cache fields. + 2. User can edit settings through the plugin or setup flow, then run `paperforge sync`, `paperforge ocr`, or `paperforge status` and observe the same resolved paths and runtime behavior. + 3. User can open an older vault with legacy top-level config keys and keep using existing commands successfully while PaperForge writes the normalized config shape going forward. + 4. User can change plugin settings without creating a second runtime truth that disagrees with Python-owned config resolution. **Plans**: TBD **UI hint**: yes -### Phase 21: One-Click Install & Polished UX -**Goal**: Users trigger full PaperForge setup with one click and receive step-by-step Chinese feedback via Obsidian notices — no terminal interaction required, no raw traceback exposure. -**Depends on**: Phase 20 (settings tab shell and persistence must exist before adding install behavior) -**Requirements**: INST-01, INST-02, INST-03, INST-04 +### Phase 23: Canonical Asset Index & Safe Rebuilds +**Goal**: Users can rebuild and safely refresh a canonical literature asset index from existing library-records, OCR outputs, formal notes, and repair results. +**Depends on**: Phase 22 +**Requirements**: ASSET-01, ASSET-02, ASSET-03, ASSET-04, MIG-02 **Success Criteria** (what must be TRUE): - 1. User fills in all required configuration fields and clicks "安装配置" — the full setup pipeline executes: `paperforge.json` is written, directories are created, environment checks pass, and agent configs are generated - 2. During setup execution, the Install button is visually disabled and displays "正在安装..." — clicking it again produces no duplicate subprocess (double-click prevention with `setDisabled(true)`) - 3. User sees step-by-step Chinese notice toasts throughout setup progress ("正在创建目录... ✓", "正在写入配置文件... ✓", "正在检查环境... ✓") — raw Python tracebacks or terminal stderr content is never displayed directly in the Notice - 4. User leaves a required field empty (e.g., Vault path) and clicks Install — receives a specific, friendly Chinese error notice (e.g., "未找到 Vault 路径，请检查设置") before any subprocess is spawned, preventing cryptic mid-install failures - 5. After setup completes (success or failure), the sidebar `PaperForgeStatusView` panel and command palette actions (`Sync Library`, `Run OCR`) continue working normally — settings tab code is strictly additive with zero coupling to sidebar internals -**Plans**: 2 plans (21-01, 21-02) + 1. User can rebuild `formal-library.json` from existing library-records, OCR outputs, and formal notes without manually repairing the index file itself. + 2. User can inspect the canonical index and see each paper represented once with stable identifiers, schema version, normalized paths, and provenance. + 3. After `sync`, `ocr`, `deep-reading`, or `repair`, user can refresh the index incrementally and see affected papers update without unrelated asset records being corrupted. + 4. If an index write is interrupted, the previous readable index remains intact and user can rerun the rebuild safely on Windows. + 5. During migration or rebuild, generated artifacts can be regenerated without losing hand-authored notes or user intent fields. +**Plans**: TBD + +### Phase 24: Derived Lifecycle, Health & Maturity +**Goal**: Users can understand each paper's lifecycle state, health findings, maturity level, and next best action from source-derived evidence instead of hand-edited status flags. +**Depends on**: Phase 23 +**Requirements**: STATE-01, STATE-02, STATE-03, STATE-04, AIC-01 +**Success Criteria** (what must be TRUE): + 1. User can see each paper's lifecycle state such as imported, indexed, PDF-ready, fulltext-ready, deep-read, and AI-context-ready, derived from actual source artifacts. + 2. User can see concrete health findings explaining why a paper is blocked, including PDF, path, OCR, note-link, and generated-asset evidence. + 3. User can see a recommended next step for a paper or collection, such as `sync`, `ocr`, `repair`, `/pf-deep`, or rebuild index. + 4. User can trust that readiness states are computed from source artifacts rather than hand-edited status fields. + 5. User can see a transparent maturity/workflow level with explainable criteria instead of a black-box score. +**Plans**: TBD + +### Phase 25: Surface Convergence, Doctor & Repair +**Goal**: Users see one consistent library-state model across `paperforge status`, doctor/repair flows, plugin dashboard, and generated Base views, with migration-safe repair paths. +**Depends on**: Phase 24 +**Requirements**: SURF-01, SURF-02, SURF-03, SURF-04, MIG-01, MIG-03, MIG-04 +**Success Criteria** (what must be TRUE): + 1. User sees the same lifecycle, health, maturity, and next-step meaning in `paperforge status`, plugin dashboard, and generated Base views because they all read the canonical index. + 2. User can use plugin dashboard actions as thin shells over CLI commands and get the same outcomes without JavaScript re-implementing lifecycle or health rules. + 3. User can run `paperforge doctor` or `paperforge repair` on an older vault and get explicit findings for stale configs, old index formats, old Base/templates, or partial OCR assets before those issues silently break workflows. + 4. User can repair source artifacts first and then rebuild derived state, and the repaired result is reflected across CLI, plugin, and Base surfaces without hand-editing the canonical index. + 5. If migration or rebuild fails, user has a documented and reversible rebuild path that restores working generated surfaces without losing notes or intent fields. +**Plans**: TBD **UI hint**: yes ---- +### Phase 26: Traceable AI Context Packs +**Goal**: Users can generate explainable, reusable AI context packs for one paper or a collection using only canonical, traceable PaperForge assets. +**Depends on**: Phase 25 +**Requirements**: AIC-02, AIC-03, AIC-04 +**Success Criteria** (what must be TRUE): + 1. User can generate an ask-this-paper or copy-context-pack bundle for a single paper that clearly lists included metadata, fulltext, note links, and provenance. + 2. User can generate a collection-level context pack from canonical assets without requiring hardcoded discipline-specific extraction schemas. + 3. User can only invoke AI context entry points when PaperForge can explain what source assets were included or why pack generation is blocked. + 4. User can trace every item in a context pack back to the originating PDF, OCR output, and formal note. +**Plans**: TBD ## Progress -**Execution Order:** Phases 20 → 21 are strictly sequential. Phase 20 provides the settings shell; Phase 21 adds install behavior on top. +**Execution Order:** Phases execute sequentially: 22 → 23 → 24 → 25 → 26. -| Phase | Milestone | Plans Complete | Status | Completed | -|-------|-----------|----------------|--------|-----------| -| 1. Config & Command Foundation | v1.0 | 3/3 | Complete | 2026-04-23 | -| 2. PaddleOCR & PDF Path Hardening | v1.0 | 2/2 | Complete | 2026-04-23 | -| 3. Config-Aware Obsidian Bases | v1.0 | 2/2 | Complete | 2026-04-23 | -| 4. End-To-End Onboarding | v1.0 | 2/2 | Complete | 2026-04-23 | -| 5. Release Verification | v1.0 | 2/2 | Complete | 2026-04-23 | -| 6. Setup & CLI Diagnostics | v1.1 | 3/3 | Complete | 2026-04-24 | -| 7. Zotero PDF & Metadata Repair | v1.1 | 2/2 | Complete | 2026-04-24 | -| 8. Deep Helper & Sandbox Gate | v1.1 | 2/2 | Complete | 2026-04-24 | -| 9. Command Unification & CLI | v1.2 | 2/2 | Complete | 2026-04-24 | -| 10. Documentation & Cohesion | v1.2 | 2/2 | Complete | 2026-04-24 | -| 11. Zotero Path Normalization | v1.3 | 1/1 | Complete | 2026-04-24 | -| 12. Architecture Cleanup | v1.3 | 1/1 | Complete | 2026-04-24 | -| 13. Logging Foundation | v1.4 | 3/3 | Complete | 2026-04-27 | -| 14. Shared Utils Extraction | v1.4 | 2/2 | Complete | 2026-04-27 | -| 15. Queue Merge | v1.4 | 1/1 | Complete | 2026-04-27 | -| 16. Retry + Progress | v1.4 | 2/2 | Complete | 2026-04-27 | -| 17. Dead Code + Pre-Commit | v1.4 | 1/1 | Complete | 2026-04-27 | -| 18. Docs + CHANGELOG + UX | v1.4 | 2/2 | Complete | 2026-04-27 | -| 19. Testing | v1.4 | 3/3 | Complete | 2026-04-28 | -| 20. Plugin Settings Shell & Persistence | v1.5 | 1/1 | Complete | 2026-04-29 | -| 21. One-Click Install & Polished UX | v1.5 | 2/2 | Complete | 2026-04-29 | -| 22. Install Wizard Modal | v1.5 | 0/0 | Planned | — | +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 22. Configuration Truth & Compatibility | 0/TBD | Not started | - | +| 23. Canonical Asset Index & Safe Rebuilds | 0/TBD | Not started | - | +| 24. Derived Lifecycle, Health & Maturity | 0/TBD | Not started | - | +| 25. Surface Convergence, Doctor & Repair | 0/TBD | Not started | - | +| 26. Traceable AI Context Packs | 0/TBD | Not started | - | --- -*Roadmap updated: 2026-04-29 — Phase 22 planned (settings/install separation)* +*Roadmap updated: 2026-05-03 for milestone v1.6 planning* diff --git a/.planning/STATE.md b/.planning/STATE.md index cead9388..ee42fa32 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,11 +2,11 @@ gsd_state_version: 1.0 milestone: v1.6 milestone_name: AI-Ready Literature Asset Foundation -status: Defining requirements -stopped_at: New milestone initialized +status: Ready to plan +stopped_at: Roadmap created for v1.6 last_updated: "2026-05-03" progress: - total_phases: 0 + total_phases: 5 completed_phases: 0 total_plans: 0 completed_plans: 0 @@ -19,53 +19,46 @@ progress: See: .planning/PROJECT.md (updated 2026-05-03) **Core value:** Researchers always know what papers they have, what state those papers are in, and whether each paper is reliably usable by AI with traceable fulltext, figures, notes, and source links. -**Current focus:** Milestone v1.6 definition +**Current focus:** Phase 22 — Configuration Truth & Compatibility ## Current Position -Phase: Not started (defining requirements) -Plan: — -Status: Defining requirements -Last activity: 2026-05-03 — Milestone v1.6 started +Phase: 22 of 26 (Configuration Truth & Compatibility) +Plan: 0 of TBD in current phase +Status: Ready to plan +Last activity: 2026-05-03 — Created v1.6 roadmap and traceability mapping + +Progress: [░░░░░░░░░░] 0% ## Performance Metrics **Velocity:** +- Total plans completed: 41 +- Average duration: Not yet tracked consistently +- Total execution time: Not yet tracked consistently -- Total plans completed: 38 (across Phases 1-19) -- Average duration: Not yet tracked -- Total execution time: Not yet tracked +**By Phase:** -**By Phase (most recent):** +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| 20. Plugin Settings Shell & Persistence | 1/1 | Not tracked | Not tracked | +| 21. One-Click Install & Polished UX | 2/2 | Not tracked | Not tracked | +| 22-26. v1.6 roadmap | 0/TBD | - | - | -| Phase | Milestone | Plans | Status | -|-------|-----------|-------|--------| -| 19. Testing | v1.4 | 3/3 | Complete | -| 20. Plugin Settings Shell | v1.5 | 3/3 | Complete | -| 21. One-Click Install | v1.5 | 2/2 | Planned | - -**Recent Trend:** v1.4 averaged ~1 day per phase. Target for v1.5 should be similar. - -*Updated after each plan completion* -| Phase 20 P20 | 2min | 3 tasks | 1 files | -| Phase 21 P21-01 | — | 3 tasks | 2 files | -| Phase 21 P21-02 | — | 2 tasks | 1 files | -| Phase 21-one-click-install-and-polished-ux P01 | 5 min | 3 tasks | 2 files | -| Phase 21-one-click-install-and-polished-ux P02 | 5 min | 2 tasks | 1 files | +**Recent Trend:** +- Last 5 plans: Not normalized in historical records +- Trend: Stable ## Accumulated Context ### Decisions -- **v1.5**: Settings tab in Obsidian plugin as setup entry point — eliminates terminal requirement; plugin becomes single download artifact. Zero new npm or Python dependencies. (See PROJECT.md Key Decisions) - +Decisions are logged in PROJECT.md Key Decisions table. Recent decisions affecting current work: -- **Phase 20**: Plugin settings use Obsidian's `PluginSettingTab` API, `loadData()`/`saveData()` for persistence, `Setting` form builder for UI. No TypeScript, no build system. Plugin is pure JS CommonJS (`paperforge/plugin/main.js`). -- **Phase 20-21**: Settings tab is purely additive — zero changes to existing `PaperForgeStatusView` sidebar or `ACTIONS[]` definitions. -- **Phase 21**: Subprocess orchestration uses `node:child_process.spawn` (not `exec`) for non-blocking setup execution with stdout/stderr parsing. -- [Phase 21-one-click-install-and-polished-ux]: Settings tab is purely additive — zero changes to PaperForgeStatusView sidebar or ACTIONS[] definitions -- [Phase 21-one-click-install-and-polished-ux]: Subprocess uses spawn (not exec) for stdout streaming, --headless (not --non-interactive), API key via --paddleocr-key flag +- v1.6 stays Python-first: config, lifecycle, health, maturity, and context-pack rules remain Python-owned. +- `formal-library.json` evolves into the canonical derived asset index rather than introducing a parallel index. +- Plugin remains a thin shell over CLI logic and canonical index outputs. ### Pending Todos @@ -73,12 +66,11 @@ None yet. ### Blockers/Concerns -- **Phase 20**: Critical pitfalls from research — debounced saves (500ms) prevent `data.json` corruption; `display()` lifecycle requires immediate in-memory update on change; `loadData()` null merge via `Object.assign({}, DEFAULTS, data || {})` -- **Phase 21**: Windows path encoding with spaces/Unicode requires `spawn` with proper quoting; raw stderr must be parsed into friendly Chinese messages before Notice display; button double-click prevention via `setDisabled(true)` +- Brownfield rollout must protect existing vaults, old Base templates, partial OCR assets, and legacy config shapes. +- AI context entry points should ship only after provenance and readiness are trustworthy. ## Session Continuity -Last session: 2026-05-02 -Last Activity: All 20 phases (01-21) learnings extracted — 355 items total (161 decisions, 75 lessons, 76 patterns, 43 surprises) -Stopped at: Completed Phase 21 (One-Click Install & Polished UX) — both plans delivered +Last session: 2026-05-03 00:00 +Stopped at: Roadmap creation complete; next step is `/gsd-plan-phase 22` Resume file: None