# v2.5.0 Source-Backed Deal Intake Implementation Plan

> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.

**Goal:** Release v2.5.0 with a usable source-backed extraction review flow: upload XLSX/CSV rent rolls and T12s, review persisted candidate fields with provenance, approve/apply selected fields, and tag/publish the release.

**Architecture:** The parser already emits candidate fields and `applySourceExtraction()` already writes approved/applied fields into deal state. This plan adds the missing persisted review retrieval path, improves the Documents UX so review-ready documents can be reopened after refresh, tightens type/test coverage, then updates public release surfaces and tags `v2.5.0` after PR/main CI pass.

**Tech Stack:** Node/npm, React + TypeScript dashboard, local REST API in `dashboard/server/watcher.ts`, workspace persistence in `dashboard/server/workspace-service.ts`, parser fixtures/tests via `tsx`, GitHub PR/release via `gh`.

---

## Task 1: Add persisted extraction preview read path

**Objective:** Let the UI reopen a stored extraction preview for a `review_ready` or `applied` document without re-running the parser.

**Files:**
- Modify: `dashboard/server/workspace-service.ts`
- Modify: `dashboard/server/watcher.ts`
- Test: `scripts/workspace-service.test.mjs` or extend a new focused script

**Steps:**
1. Write a failing service/API test that extracts a fixture document, clears local preview state conceptually, then calls a new persisted extraction read function/endpoint and expects an enriched preview with `currentValue`, `conflict`, source refs, and candidate/applied review statuses.
2. Run the test and verify it fails because the function/route does not exist.
3. Add `getSourceExtraction(context, dealId, documentId)` in `workspace-service.ts`:
   - validate workspace/deal exists,
   - validate document exists,
   - read `extractions/:documentId.json`,
   - enrich fields with current deal values using existing enrichment helper,
   - return the preview.
4. Add `GET /api/deals/:dealId/documents/:documentId/extraction` in `watcher.ts`.
5. Run focused test and dashboard server build.

## Task 2: Add frontend hook state for active extraction review

**Objective:** Provide explicit frontend actions to load/reopen persisted extraction previews and avoid relying only on transient `lastExtraction`.

**Files:**
- Modify: `dashboard/src/hooks/useDealWorkspace.ts`
- Modify: `dashboard/src/types/workspace.ts`

**Steps:**
1. Write/extend a focused hook/API behavior test if test harness exists; otherwise add a lightweight static/contract assertion in a Node script for endpoint path constants and type shape.
2. Add `activeExtraction`/`lastExtraction` state and `loadExtraction(documentId)` that calls the new GET endpoint.
3. Keep `extractDocument(documentId)` setting the same active extraction after POST.
4. Keep `applyExtraction(...)` clearing active extraction after successful apply.
5. Update `ApplyExtractionResult` to match backend response shape or remove stale fields.

## Task 3: Improve Documents tab review actions and provenance display

**Objective:** Make review-ready documents operationally usable: explicit review buttons, persistent preview reopening, and stronger source evidence in the field cards.

**Files:**
- Modify: `dashboard/src/components/DealWorkspace.tsx`
- Optional modify: `dashboard/src/components/DealCockpitSidebar.tsx`

**Steps:**
1. Write failing UI/e2e assertions where possible:
   - review-ready document shows `Review Fields`,
   - clicking it renders `extraction-preview`,
   - field cards show parser/source location/hash evidence,
   - apply button says `Approve & Apply Selected Fields`.
2. Update `DocumentIntakePanel` props to accept `onLoadExtraction` and pass it from `DealWorkspace`.
3. For document states:
   - `not-started`/`uploaded`: show `Preview Extraction`,
   - `review_ready`: show `Review Fields`,
   - `applied`: show `View Applied Evidence`,
   - `extraction-pending`/`parser-unavailable`/`parse_failed`: show clear status copy.
4. Update `ExtractionPreviewPanel` to show provenance lines:
   - parser ID/version,
   - sheet/row/column or line/page,
   - short file hash,
   - raw snippet/value where available.
5. Rename primary action copy to `Approve & Apply Selected Fields` to be honest about combined semantics.

## Task 4: Add/reinforce backend approval/application tests

**Objective:** Prove approval/application persists audit metadata and launch readiness sees approved source-backed fields.

**Files:**
- Create/modify: `scripts/workspace-service.test.mjs`
- Modify: `package.json`
- Modify: `.github/workflows/ci.yml`
- Modify: `scripts/demo-verify.js`

**Steps:**
1. Create a deterministic test workspace from fixture XLSX files.
2. Upload/save fixture docs through service calls or API helpers.
3. Extract rent roll and T12.
4. Apply selected fields with conflict confirmation when needed.
5. Assert:
   - `deal.json` values changed,
   - document status becomes `applied`,
   - extraction fields become `applied`,
   - `approved-fields.json` includes `sourceRef`, `approvedAt`, `appliedAt`, parser metadata, and file hash,
   - launch readiness source coverage counts approved fields.
6. Add `npm run test:workspace` and include it in `demo:verify`/CI if deterministic.

## Task 5: Update v2.5.0 release/version surfaces

**Objective:** Make the release public-facing and taggable as `v2.5.0 - Source-Backed Deal Intake`.

**Files:**
- Modify: `package.json`
- Modify: `dashboard/package.json`
- Modify: `dashboard/package-lock.json`
- Create: `RELEASE_NOTES_v2.5.0.md`
- Modify: `README.md`
- Modify: `ROADMAP.md`
- Modify: `docs/QUICK-DEMO.md`
- Modify: `docs/DEMO-JOURNEY.md`
- Modify: `docs/ISSUE-SEEDS.md`

**Steps:**
1. Bump package versions from `2.4.0` to `2.5.0`.
2. Add `RELEASE_NOTES_v2.5.0.md` with sections matching existing release-note pattern.
3. Add README release journey row for v2.5.0.
4. Update “What’s New” to v2.5.0 focusing on Source-Backed Deal Intake, guided demo, swarm goal console, and runtime comparison.
5. Update docs that say “current v2.4” to v2.5.0 or version-neutral wording.
6. Move already-shipped post-v2.4 roadmap items under v2.5.0 baseline; leave PDF/OCR, richer parser fixtures, separate approval-only workflow, and Node 24 Actions hardening as post-v2.5.

## Task 6: Browser/operator review loop

**Objective:** Visually verify the Documents UX behaves like a usable operator workflow, not just a compiled feature.

**Files:**
- Modify any UI files needed based on observed defects.

**Steps:**
1. Run `npm run demo`.
2. Start `npm run dashboard` in background.
3. Use browser tools to open `http://localhost:5173`.
4. Navigate to the deterministic workspace Documents tab.
5. If possible, upload/use fixture XLSX docs and exercise extraction review.
6. Capture/check the changed screen visually.
7. Patch visual/product defects immediately.
8. Rerun `npm --prefix dashboard run build` and relevant tests.

## Task 7: Final validation, PR, merge, tag, GitHub Release

**Objective:** Ship via PR, verify CI, merge, tag `v2.5.0`, and create GitHub Release marked Latest.

**Commands:**
```bash
git diff --check
npm run demo:verify
npm --prefix dashboard run test:e2e
npm --prefix dashboard audit --omit=dev --audit-level=high
```

**PR/release flow:**
1. Commit branch with conventional message.
2. Push `feat/v2.5-source-backed-review`.
3. Open PR with test plan.
4. Watch PR CI.
5. Merge with squash and delete branch.
6. Pull main and watch main CI.
7. Tag merge commit:
   ```bash
   git tag -a v2.5.0 -m "v2.5.0 - Source-Backed Deal Intake"
   git push origin v2.5.0
   ```
8. Create GitHub Release:
   ```bash
   gh release create v2.5.0 --repo ahacker-1/cre-acquisition-orchestrator --title "v2.5.0 - Source-Backed Deal Intake" --notes-file RELEASE_NOTES_v2.5.0.md --latest
   ```
9. Verify `gh release list` shows v2.5.0 as Latest.
