Kontia/Implementation fix.md

Implementation Goal
Deliver a single, continuous evidence flow so users do not re-upload PDFs across M4->M5->M8->M9->M10, and always see the right document lineage.

Target User Flow (after changes)

User analyzes source docs in M4 from M3 or M5 context.
User opens M5 and gets only relevant extracted requirements.
User creates M8 contract from M5 and contract gets proposal PDF continuity automatically.
User opens M9 from M8 with contractId preserved through diagnosis and case creation.
User opens M10 and sees live dossier with file-level links, freshness state, and clear traceability.
Phase Plan

Phase 1: Fix Critical Continuity Breaks
Stop unrelated M4 history fallback in M5 extraction when proposal has no linked source.
Persist and use contractId in legal diagnosis finalization.
Replace M9 contract selector from “IDs from existing cases” to “actual contracts list”.
Files: workflow extract API, M5 detail page, legal diagnosis start, legal diagnosis answer, M9 view, M9 page.
Phase 2: M5->M8 Document Reuse (No Reupload)
On M8 autocreate, auto-copy latest proposal PDF into ContractDocument.
Extend M8 extraction endpoint to accept sourceProposalId without mandatory new file upload.
Add “Use proposal PDF from M5” action in M8 upload tab.
Files: M8 page, contract extract API, contracts view, contract storage, proposal storage.
Phase 3: Complete Contract Document UX
Wire existing /api/contracts/upload into M8 UI.
Show contract documents list in M8 cards.
Add delete endpoint for contract documents and surface actions in UI.
Files: contracts upload API, contracts view, contracts API folder.
Phase 4: M10 Live Dossier + File-Level Traceability
Make dossier load strategy explicit (live default, snapshot optional).
Add freshness metadata (generatedAt, isStale, source indicator).
Extend dossier payload from counts to include document-level entries and link targets.
Render proposals/contracts/legal sections with drill-down and links in M10.
Files: audits server, audits types, expediente API, M10 view.
Phase 5: Secure Download Endpoints
Add proposal document download endpoint.
Add contract document download endpoint.
Enforce ownership checks and safe storage path resolution.
Files: proposals API folder, contracts API folder, proposal delete route pattern.
Phase 6: Continuity Safeguards and Observability
Add structured logs for handoffs (sourceProposalId, contractId, history source used).
Add continuity warnings in UI when source context is missing.
Add “why this file” trace badges where extraction picks source docs.
Files: M4 view, M5 workflow view, M8 view, M10 view.
Phase 7: Tests and Release Gates
Add integration tests for full continuity path M4->M5->M8->M9->M10.
Add regression tests for “wrong history picked” and “diagnosis loses contractId”.
Add API tests for download ownership and safe path rules.
Keep existing npm test, npm run lint, npm run build as mandatory gate.
Files: lib tests root, component tests root.
Acceptance Criteria

No forced reupload from M5 to M8 when proposal PDF exists.
Legal cases created via diagnosis stay linked to selected contract.
M5 never uses unrelated M4 history for extraction.
M10 shows live, fresh dossier state and file-level evidence traceability.
Users can securely download proposal/contract evidence from module context.
End-to-end continuity test passes for M4->M10.
Execution Order (Critical Path)

Phase 1
Phase 2
Phase 4
Phase 5
Phase 3
Phase 6
Phase 7
Estimated Delivery

Phase 1-2: 2-3 days
Phase 3-5: 2-3 days
Phase 6-7: 1-2 days
Total: ~1 week of focused implementation
If you want, I can start immediately with Phase 1 and push the exact code changes in that order.

Progress Update

Date: 2026-04-09
Phase 1 Status: Completed

Completed in Phase 1

- M5 extraction continuity guard: removed unrelated M4 history fallback when proposal has no linked `sourceLicitationId`.
- M5 detail continuity guard: history context now loads only when tied to the same linked `sourceLicitationId`.
- M9 diagnosis continuity: diagnosis start now validates and persists `contractId` in diagnosis context.
- M9 diagnosis finalization continuity: legal case auto-created from diagnosis now reuses persisted `contractId` (with ownership validation).
- M9 contract selector source: selector options now come from actual M8 contracts instead of contract IDs inferred from existing legal cases.

Validation Run

- `npm test`: passed (22 files, 61 tests).
- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
- `npm run build`: passed (Next.js production build succeeded).

Next Planned Step

- Phase 2: M5 -> M8 document reuse (no reupload).

Progress Update

Date: 2026-04-09
Phase 2 Status: Completed

Completed in Phase 2

- M8 autocreate continuity: when opening M8 from M5 (`autocreate=1`), the flow now auto-links the latest proposal PDF into `ContractDocument` (deduplicated).
- M8 extraction endpoint continuity: `/api/contracts/extract` now accepts `sourceProposalId` without mandatory file upload.
- M8 extraction source handling: route can analyze either uploaded PDF or proposal PDF; it preserves `sourceProposalId` on contract create/update.
- M8 proposal PDF reuse UI: added explicit action in upload tab to "Usar PDF de propuesta de M5" with proposal selector and timestamped file labels.
- Shared continuity utilities:
  - Safe proposal document read helper in proposal storage.
  - Proposal->contract continuity helper for latest PDF lookup and deduplicated linking.

Validation Run (Phase 2)

- `npm test`: passed (22 files, 61 tests).
- `npm run build`: passed (Next.js production build succeeded).
- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).

Next Planned Step

- Phase 4: M10 live dossier + file-level traceability (per critical path order).

Progress Update

Date: 2026-04-14
Phase 4 Status: Completed

Completed in Phase 4

- Dossier load strategy is now explicit in M10:
  - API and UI support `live` (default) and `snapshot` (optional) loading.
  - M10 now shows requested strategy vs actual source used.
- Freshness metadata added and surfaced:
  - `generatedAt`, `isStale`, `source`, `snapshotId`, `staleAfterMinutes`.
  - Snapshot generation returns synchronized freshness metadata.
- Dossier payload upgraded from aggregate-only counts to file-level traceability:
  - M5 proposals now include `documentEntries` with links and trace labels.
  - M8 contracts now include `documentEntries` with links, kind, and lineage to source proposal when available.
  - M9 legal cases now include `documentEntries` with links and trace labels to legal context/contract continuity.
- M10 UI drill-down completed:
  - Separate sections for proposals/contracts/legal with per-record links.
  - Per-file expandable trace blocks showing mime, size/date, trace reason, and actionable links.

Validation Run (Phase 4)

- `npm test`: passed (23 files, 67 tests).
- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
- `npm run build`: passed (Next.js production build succeeded).

Next Planned Step

- Phase 5: secure download endpoints for proposal and contract evidence.

Progress Update

Date: 2026-04-14
Phase 5 Status: Completed

Completed in Phase 5

- Added secure proposal evidence download endpoint:
  - `GET /api/proposals/[id]/documents/[documentId]`.
  - Enforces ownership (`proposalId` + `documentId` + `userId`) before file access.
  - Uses safe storage path guard and bounded file read helper.
  - Returns attachment headers with safe filename handling.
- Added secure contract evidence download endpoint:
  - `GET /api/contracts/[id]/documents/[documentId]`.
  - Enforces ownership via contract relation (`contract.userId`).
  - Uses new safe contract document read helper with path traversal protection.
  - Returns attachment headers with safe filename handling.
- Added safe contract storage read helper:
  - `readStoredContractDocumentFile(...)` with canonical path validation and size guard.
- M10 file-level traceability now exposes direct secure download links for proposal and contract evidence from dossier context.

Validation Run (Phase 5)

- `npm test`: passed (23 files, 67 tests).
- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
- `npm run build`: passed (Next.js production build succeeded).

Next Planned Step

- Phase 3: complete contract document UX (wire upload UI, show docs in M8 cards, add delete endpoint/actions).

Progress Update

Date: 2026-04-14
Phase 3 Status: Completed

Completed in Phase 3

- M8 upload UX now wires existing `/api/contracts/upload`:
  - Added explicit "Adjuntar documento al contrato (sin IA)" flow in M8 upload tab.
  - Supports selecting contract target, document kind, and PDF file.
- Contract document cards in M8 now include document list and actions:
  - File name, kind, size, and timestamp shown per document.
  - Direct download action per file.
  - Delete action per file.
- Added contract document delete endpoint:
  - `DELETE /api/contracts/[id]/documents/[documentId]`.
  - Enforces ownership via `contract.userId`.
  - Removes both storage file and DB row with safe path handling.

Validation Run (Phase 3)

- `npm test`: passed (23 files, 67 tests).
- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
- `npm run build`: passed (Next.js production build succeeded).

Next Planned Step

- Phase 6: continuity safeguards and observability.

Progress Update

Date: 2026-04-15
Phase 6 Status: Completed

Completed in Phase 6

- Added structured continuity handoff logs across critical APIs:
  - `m4_to_m5_*` events in `/api/proposals/[id]/workflow/extract`.
  - `m5_to_m8_*` events in `/api/contracts/extract`.
  - `m8_to_m9_*` events in `/api/legal/diagnosis/start`.
  - `m9_*` continuity events in `/api/legal/diagnosis/answer`.
- Added page-level observability for M5->M8 autocreate in `/gestion-contratos`:
  - Logs for autocreate request, proposal resolution, contract target resolution, proposal PDF lookup, and link outcomes.
- Added continuity safeguards and operator-facing warnings in UI:
  - M4 (`normative-analysis-view`): warning when no linked source context.
  - M5 (`proposal-workflow-view`): warning when no M4 context for extraction.
  - M8 (`contracts-management-view`): warnings for missing proposal PDFs and contracts without `sourceProposalId`.
  - M10 (`preventive-dossier-view`): warnings derived from incomplete dossier component evidence.
- Added explicit traceability badges (`Por que este archivo`) where file/source selection affects continuity in M4, M5, M8, and M10.

Validation Note (Phase 6)

- Continuity observability changes were carried into Phase 7 release-gate validation and passed together with final gates.

Next Planned Step

- Phase 7: tests and release gates.

Progress Update

Date: 2026-04-15
Phase 7 Status: Completed

Completed in Phase 7

- Added integration continuity test for M4->M5->M8->M9->M10 dossier lineage:
  - `src/lib/audits/__tests__/dossier-continuity.integration.test.ts`.
  - Verifies proposal->contract->legal continuity links and evidence trace payload in M10.
- Added regression test for "wrong history picked" continuity break:
  - `src/app/api/proposals/[id]/workflow/extract/route.test.ts`.
  - Verifies extraction is blocked when no linked M4 source and no uploaded PDF.
- Added regression test for "diagnosis loses contractId":
  - `src/app/api/legal/diagnosis/answer/route.test.ts`.
  - Verifies finalization preserves persisted `contractId` and links the auto-created legal case to that contract.
- Added API security tests for download ownership/path safety:
  - `src/app/api/proposals/[id]/documents/[documentId]/route.test.ts`.
  - `src/app/api/contracts/[id]/documents/[documentId]/route.test.ts`.
  - Verifies 404 on non-owned/missing document and 400 on invalid storage path.
- Fixed JSX parsing safety in M8 continuity messaging (`M5->M8`) to keep lint/build green.

Validation Run (Phase 7)

- `npm test`: passed (28 files, 74 tests).
- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
- `npm run build`: passed (Next.js production build succeeded).

Next Planned Step

- Planned implementation phases (1-7) are complete. Ready for QA/UAT and deployment checklist.