- #13: Critical — swap delete/write order in _complete_one (write new
vectors before deleting old ones) to prevent data loss on write failure
- #12: Add logger.warning() to 3 resume-skip except blocks so silent
re-embed fallbacks are observable
- #14: Add lightweight HNSW query probe to _assert_collections_healthy
- #11: Log collection query failures in merge_retrieve instead of silent
continue
- #16: Reuse provider across payloads in encode_paper_job — one creation
per worker per paper instead of per payload
Workstream X: 11 papers audited across 6 layout classes,
5 verified via vision subagents. 6 real bug patterns identified
with code locations and root cause analysis.
Bug patterns:
A - _is_obviously_formal_figure_caption heuristic too aggressive
(ocr_roles.py:193)
B - Cross-column figure asset mis-assignment ignores boundaries
(ocr_figures.py:704)
C - Render frontmatter skip silently drops authors/affiliations
(ocr_render.py)
D - Two-column same-page boundary body→backmatter zone pollution
(ocr_document.py)
E - Frontmatter headings misclassified (ocr_roles.py)
F - Supplementary-only PDFs not handled
Full report: docs/superpowers/analysis/2026-07-05-layout-truth-audit-findings.md
Also: codebase-memory-mcp 0.8.1 installed and repo indexed.
Separate audiences: README as navigation entry, getting-started as canonical tutorial,
troubleshooting as failure recovery, AGENTS as agent-only operating contract,
COMMANDS as pure reference, maintainer-guide for release/versioning/architecture.
- Move Better BibTeX auto-export to post-install step (exports dir created by setup)
- Clarify wizard overview: show resources_dir/literature_dir/control_dir hierarchy
- Fix post-install flow order: BBT export → enable plugin → dashboard → sync
- Split do_ocr and analyze marks into separate steps (OCR before deep-reading)
- Mark all literature flags via Base views, not manual file editing
- Make installer incremental: preserve existing files, only create missing ones
- Remove destructive junction/link deletion in TUI wizard
- Merge .env instead of overwriting; skip overwrite for AGENTS.md, docs, plugin
- Update TUI, headless, and plugin completion output to match corrected flow
- Add regression test for non-destructive setup behavior
- Add Path Resolution section to AGENTS.md with BBT format table,
wikilink rules, junction setup instructions, and multi-attachment handling
- Update Library Record frontmatter example with new fields:
pdf_path (wikilink), bbt_path_raw, zotero_storage_key, attachment_count,
supplementary, path_error
- Add ADR-011: Zotero Path Normalization Strategy documenting D-01 through D-08
- Fix dead links in ARCHITECTURE.md and planning research files
- Add scripts/consistency_audit.py with 4 automated checks
- Check 1: No old command names in active code/docs
- Check 2: No paperforge_lite references in Python code
- Check 3: No dead internal links in markdown
- Check 4: Command docs have required sections
Fix violations found by audit:
- Update paperforge/ocr_diagnostics.py error messages to use new commands
- Update pipeline/worker/literature_pipeline.py generated content to use /pf-deep
- Update scripts/welcome.py to recommend /pf-deep
- Update skills/literature-qa/prompt_deep_subagent.md title to /pf-deep
- Update skills/literature-qa/scripts/ld_deep.py docstrings to /pf-deep
- Fix dead links in docs/COMMANDS.md and command/*.md
- Update AGENTS.md migration section to reference MIGRATION-v1.2.md
- Update paperforge/cli.py module docstring to use current commands
- Delete templates/文献阅读.md (frontmatter is hardcoded in pipeline)
- Remove template deployment from setup.py
- Update README.md and AGENTS.md references
