# Milestone: v1.1 Sandbox Onboarding Hardening

**Status:** COMPLETE
**Date:** 2026-04-24
**Commits:** 110+ (from v1.0 tag to v1.1)
**Requirements:** 24 total (21 Complete, 3 Partial)

---

## Goal

Make the GitHub README + sandbox path behave like a real first-time user flow, with no silent setup stalls, contradictory diagnostics, unresolved mock Zotero PDFs, or broken `/LD-deep` prepare commands.

## Accomplishments by Phase

### Phase 6: Setup, CLI, And Diagnostics Consistency

**Duration:** 2026-04-23
**Commits:** `187af3b`, `1d8478c`, `31cce82`, and earlier Phase 6 commits

| Task | What | Status |
|------|------|--------|
| SETUP-01/02 | Wizard UX flow, `--vault` prefill, no terminal stall | Complete |
| SETUP-03 | `python -m paperforge` fallback documented | Complete |
| SETUP-04/05 | `paperforge paths --json` emits correct paths; command docs use same field names | Complete |
| DIAG-01 | Doctor validates per-domain JSON exports (not only `library.json`) | Complete |
| DIAG-02 | Canonical env var `PADDLEOCR_API_TOKEN` consistent across setup/worker/doctor | Complete |
| DIAG-03 | Doctor reports deployed worker path matching resolver contract | Complete |
| DIAG-04 | OCR doctor distinguishes HTTP 405 from bad URL | Complete |

### Phase 7: Zotero PDF, Metadata, And State Repair

**Duration:** 2026-04-23 to 2026-04-24
**Commits:** `981f5fa`, `6052c82`, `d0ba1da`, `ff12515`, `1f817a5`, `bef53fc`

| Task | What | Status |
|------|------|--------|
| META-01/02 | `first_author` and `journal` populated in library-records from BBT export | Complete |
| STATE-01/02 | `validate_ocr_meta()` ensures OCR state consistency; `run_deep_reading()` validates before trusting status | Complete |
| STATE-03/04 | `paperforge deep-reading --verbose` prints queues; `paperforge repair` identifies blocked/ready records | Complete |
| Repair command | `paperforge repair [--verbose] [--fix]` detects and fixes three-way state divergence | Complete |
| ZPATH-01/02/03 | BBT bare `KEY/KEY.pdf` → `storage:KEY/KEY.pdf` normalization | **Partial** — deferred to future phase |

**Partial requirements:** ZPATH-01/02/03 — `resolve_pdf_path()` handles `storage:` paths correctly, but BBT bare paths are not auto-normalized in `load_export_rows()`. Workaround: configure BBT to emit `storage:` prefix, or ensure PDFs are in resolvable absolute/vault-relative paths.

### Phase 8: Deep Helper Deployment And Sandbox Regression Gate

**Duration:** 2026-04-24 (~45 min)
**Commits:** `fa51cf7`, `afa19eb`, `802d34b`, `766ed1e`, `b1cfe4f`, `3b929b1`

| Task | What | Status |
|------|------|--------|
| DEEP-04 | `ld_deep.py` runs from deployed Vault without `PYTHONPATH` | Complete |
| DEEP-05 | `/LD-deep` queue examples use existing paths and field names | Complete |
| DEEP-06 | `prepare_deep_reading` generates `figure-map.json`, `chart-type-map.json`, and `## 🔍 精读` scaffold | Complete |
| REG-01 | Sandbox smoke test covers setup layout → selection sync → index refresh → OCR preflight → deep-reading queue → `ld_deep.py prepare` | Complete |
| REG-02 | Smoke assertions cover all manual audit regressions | Complete |
| REG-03 | README, INSTALLATION.md, AGENTS.md, command files consistent with smoke tests | Complete |
| Rollback | `prepare_deep_reading` rolls back partial writes on failure | Complete |

---

## Test Coverage

| Test File | Tests | What |
|-----------|-------|------|
| `tests/test_smoke.py` | 14 | Setup wizard, doctor, import, prepare, queue, docs, metadata, PDF paths |
| `tests/test_prepare_rollback.py` | 3 | Rollback on figure-map failure and scaffold failure |
| `tests/test_repair.py` | 20 | Three-way divergence detection, dry-run vs fix, edge cases |
| `tests/test_pdf_resolver.py` | 8+ | PDF path resolution (absolute, relative, junction, storage) |
| `tests/test_ocr_state_machine.py` | 10+ | OCR job transitions (pending/queued/done/error/blocked/nopdf) |
| `tests/test_base_preservation.py` | - | Base view preservation (Phase 3) |
| `tests/test_base_views.py` | - | Base view generation (Phase 3) |

**Total:** 55+ tests (17 new in v1.1)

---

## Key Decisions

1. **Config precedence:** explicit overrides > env > JSON nested > JSON top-level > defaults
2. **Canonical PaddleOCR env var:** `PADDLEOCR_API_TOKEN`
3. **CLI exit codes:** int return for testability; worker functions imported at module level for patchability
4. **Python 3.14 workaround:** `importlib.util` with `sys.modules` pre-registration for dataclass compatibility
5. **Deterministic fixtures:** generated once and committed; generation script available but not run in CI
6. **Rollback pattern:** track written files, save original state, clean up on exception (not full filesystem snapshot)
7. **Repair idempotency:** dry-run by default; `--fix` required for actual repairs

---

## Files Changed

### New
- `tests/conftest.py`
- `tests/test_smoke.py`
- `tests/test_prepare_rollback.py`
- `tests/test_repair.py`
- `tests/test_pdf_resolver.py`
- `tests/sandbox/generate_ocr_fixture.py`
- `tests/sandbox/exports/骨科.json`
- `tests/sandbox/ocr-complete/TSTONE001/*` (fixture files)

### Modified
- `pipeline/worker/scripts/literature_pipeline.py` — validate_ocr_meta, run_repair, doctor importability
- `skills/literature-qa/scripts/ld_deep.py` — rollback, quote stripping
- `paperforge/cli.py` — repair subcommand
- `paperforge/ocr_diagnostics.py` — HTTP 405 handling
- `AGENTS.md` — repair command reference, fallback command
- `docs/INSTALLATION.md` — fallback command
- `command/ld-deep.md` — field name consistency

---

## Known Limitations

1. **BBT bare path normalization:** Not auto-converted in `load_export_rows()`. Requires BBT to emit `storage:` prefix or manual path configuration.
2. **Repair scan scaling:** O(n*m) per-record rglob in large vaults. Acceptable for current use cases.
3. **Pre-existing test failures:** `test_base_preservation.py` and `test_base_views.py` have `ModuleNotFoundError: No module named 'pipeline'` — import path issues from Phase 3, unrelated to v1.1 scope.

---

## Verification

- [x] All new tests pass (`pytest tests/test_smoke.py tests/test_prepare_rollback.py tests/test_repair.py -v`)
- [x] No live PaddleOCR API calls in any test
- [x] Fixtures committed and deterministic
- [x] `paperforge repair --verbose` runs without crashes
- [x] `paperforge doctor` validates importability, env names, per-domain exports
- [x] `paperforge --help` shows `repair` subcommand
- [x] Phase summaries exist for all phases (1-8)
- [x] Requirements traceability updated (21/24 Complete, 3/24 Partial)

---

## Next Milestone Candidates

| Option | Focus |
|--------|-------|
| v1.2 | BBT bare path normalization + PDF resolver integration test |
| v1.2 | Repair scan performance + caching for large vaults |
| v1.2 | OCR provider abstraction (beyond PaddleOCR) |
| v1.2 | Scheduled worker automation without agent session |
| v1.2 | Dashboard note summarizing pipeline health |

---

*Milestone v1.1 completed: 2026-04-24*
*Total phases: 8 (6, 7, 8 for v1.1)*
*Total commits since v1.0: 110+*
