fix: resolve workflow linking on resume, update proposals auto-commit, and validation baseline rules

backend/app/agents/validation.py

@@ -114,9 +114,16 @@ class RuleValidationAgent:
         failures = []
 
         for proposal in proposals:
-            changes = proposal.proposed_changes or {}
+            changes = getattr(proposal, "proposed_changes", None) or {}
             proposed = changes.get("proposed", changes)
-            evidence = proposed.get("evidence")
+            evidence = proposed.get("evidence") or changes.get("evidence")
+
+            ki = getattr(proposal, "knowledge_item", None)
+            if not evidence and ki and getattr(ki, "evidence", None):
+                evidence = [
+                    {"quote": getattr(ev, "quote", ""), "page_number": getattr(ev, "page_number", None)}
+                    for ev in ki.evidence
+                ]
 
             if not evidence:
                 failures.append(
@@ -132,8 +139,8 @@ class RuleValidationAgent:
                         ),
                         "operator": "required_evidence",
                         "message": (
-                            "Proposal does not contain evidence metadata "
-                            "in proposed_changes."
+                            "Proposal does not contain required evidence quote "
+                            "or citation metadata."
                         ),
                         "proposal_ids": [str(proposal.id)],
                     }
@@ -389,22 +396,27 @@ class RuleValidationAgent:
 
         workspace_id = proposals[0].workspace_id
 
-        # Check if workspace has existing knowledge
+        # Check if workspace has existing active baseline knowledge
         try:
             from app.database.database import SessionLocal
-            from app.models.knowledge_item import KnowledgeItem
+            from app.models.knowledge_item import KnowledgeItem, KnowledgeStatus
             from app.services.embedding_service import EmbeddingService
 
             db = SessionLocal()
             try:
-                existing_count = (
-                    db.query(KnowledgeItem)
-                    .filter(KnowledgeItem.workspace_id == workspace_id)
-                    .count()
+                # Query only ACTIVE (previously committed) items, excluding uncommitted PENDING items
+                existing_items = (
+                    db.query(KnowledgeItem.title, KnowledgeItem.value)
+                    .filter(
+                        KnowledgeItem.workspace_id == workspace_id,
+                        KnowledgeItem.status == KnowledgeStatus.ACTIVE,
+                    )
+                    .limit(50)
+                    .all()
                 )
 
-                # If workspace is empty, pass everything (first doc defines topic)
-                if existing_count == 0:
+                # If workspace has no active baseline knowledge yet, pass (first doc establishes baseline)
+                if not existing_items:
                     return [
                         {
                             "status": "PASS",
@@ -418,8 +430,8 @@ class RuleValidationAgent:
                             ),
                             "operator": "topic_relevance",
                             "message": (
-                                "No existing knowledge to compare against. "
-                                "First documents define the workspace topic."
+                                "No prior active knowledge to compare against. "
+                                "First documents establish the workspace baseline."
                             ),
                             "proposal_ids": [
                                 str(p.id) for p in proposals
@@ -429,14 +441,6 @@ class RuleValidationAgent:
 
                 # Use embedding service for semantic similarity
                 embedding_service = EmbeddingService()
-
-                # Get existing knowledge titles+values for comparison
-                existing_items = (
-                    db.query(KnowledgeItem.title, KnowledgeItem.value)
-                    .filter(KnowledgeItem.workspace_id == workspace_id)
-                    .limit(50)
-                    .all()
-                )
                 existing_text = " ".join(
                     f"{item.title} {item.value}" for item in existing_items
                 )

backend/app/api/workflows.py

@@ -92,7 +92,7 @@ def _sync_workflow_review_state(workflow: WorkflowRun, db: Session) -> None:
                 finally:
                     executor.close()
             except Exception:
-                workflow.status = WorkflowStatus.COMPLETED
+                workflow.status = WorkflowStatus.FAILED
                 if not workflow.completed_at:
                     workflow.completed_at = datetime.now(timezone.utc)
                 db.commit()

backend/app/services/proposal_review_service.py

@@ -262,7 +262,7 @@ class ProposalReviewService:
             executor.resume(workflow)
         except Exception:
             from datetime import datetime, timezone
-            workflow.status = WorkflowStatus.COMPLETED
+            workflow.status = WorkflowStatus.FAILED
             if not workflow.completed_at:
                 workflow.completed_at = datetime.now(timezone.utc)
             self.db.commit()

backend/app/services/reconciliation_service.py

@@ -154,6 +154,17 @@ class ReconciliationService:
         ):
             return
 
+        evidence_list = [
+            {
+                "quote": ev.quote,
+                "page_number": ev.page_number,
+                "section": ev.section,
+                "confidence": ev.confidence,
+                "source_type": ev.source_type,
+            }
+            for ev in (item.evidence or [])
+        ]
+
         proposal = Proposal(
             workspace_id=workspace_id,
             knowledge_item_id=item.id,
@@ -171,6 +182,7 @@ class ReconciliationService:
                 "summary": item.summary,
                 "attributes": item.attributes,
                 "confidence": item.confidence,
+                "evidence": evidence_list,
             },
         )
 
@@ -189,6 +201,17 @@ class ReconciliationService:
         ):
             return
 
+        evidence_list = [
+            {
+                "quote": ev.quote,
+                "page_number": ev.page_number,
+                "section": ev.section,
+                "confidence": ev.confidence,
+                "source_type": ev.source_type,
+            }
+            for ev in (new_item.evidence or [])
+        ]
+
         proposal = Proposal(
             workspace_id=workspace_id,
             knowledge_item_id=existing_item.id,
@@ -211,12 +234,15 @@ class ReconciliationService:
                     "summary": new_item.summary,
                     "attributes": new_item.attributes,
                     "confidence": new_item.confidence,
+                    "evidence": evidence_list,
                 },
+                "evidence": evidence_list,
                 "source_knowledge_item_id": str(new_item.id),
             },
         )
 
         self.db.add(proposal)
+
     @staticmethod
     def _normalize(value: str | None) -> str:
         if not value:
@@ -224,4 +250,4 @@ class ReconciliationService:
 
         words = value.lower().strip().split()
 
-        return " ".join(sorted(words))
+        return " ".join(words)

backend/app/workflow/graph.py

@@ -1,4 +1,4 @@
-from __future__ import annotations
+from __future__ import annotations
 
 from sqlalchemy.orm import Session
 from langgraph.graph import END, START, StateGraph
@@ -226,10 +226,10 @@ def build_workflow(
         "complete",
     )
 
-    # After human approval/resume, continue to completion.
+    # After human approval/resume, route through link before completion.
     graph.add_edge(
         "human_review",
-        "complete",
+        "link",
     )
 
     graph.add_edge(

backend/app/workflow/nodes/complete.py

@@ -19,10 +19,11 @@ def complete(
     """
     from sqlalchemy.orm import Session
     from app.database.database import SessionLocal
-    from app.models.proposal import Proposal, ProposalStatus
+    from app.models.proposal import Proposal, ProposalStatus, ProposalType
     from app.models.knowledge_item import KnowledgeItem, KnowledgeStatus
     from app.models.commit import Commit
     from datetime import datetime, timezone
+    import uuid
     import logging
 
     _log = logging.getLogger(__name__)
@@ -80,14 +81,11 @@ def complete(
             tracker.end_stage("complete")
             return state
 
-        proposals = (
-            db.query(Proposal)
-            .filter(
-                Proposal.workspace_id == state.workspace_id,
-                Proposal.knowledge_item_id.in_(ki_ids),
-                Proposal.status == ProposalStatus.PENDING,
-            )
-            .all()
+        from app.services.proposal_review_service import ProposalReviewService
+        review_service = ProposalReviewService(db)
+        proposals = review_service.get_pending_for_document_version(
+            workspace_id=state.workspace_id,
+            document_version_id=state.document_version_id,
         )
 
         _log.info(
@@ -102,6 +100,30 @@ def complete(
             proposal.status = ProposalStatus.APPROVED
             proposal.reviewed_at = now
 
+            if proposal.proposal_type == ProposalType.UPDATE and proposal.knowledge_item_id:
+                target_item = db.query(KnowledgeItem).filter(KnowledgeItem.id == proposal.knowledge_item_id).first()
+                if target_item:
+                    changes = proposal.proposed_changes or {}
+                    proposed = changes.get("proposed", {})
+                    if "value" in proposed:
+                        target_item.value = proposed["value"]
+                    if "summary" in proposed:
+                        target_item.summary = proposed["summary"]
+                    if "attributes" in proposed:
+                        target_item.attributes = proposed["attributes"]
+                    if "confidence" in proposed:
+                        target_item.confidence = proposed["confidence"]
+                    target_item.status = KnowledgeStatus.ACTIVE
+
+                    source_id = changes.get("source_knowledge_item_id")
+                    if source_id:
+                        try:
+                            src_item = db.query(KnowledgeItem).filter(KnowledgeItem.id == uuid.UUID(str(source_id))).first()
+                            if src_item:
+                                src_item.status = KnowledgeStatus.SUPERSEDED
+                        except Exception:
+                            pass
+
             commit = Commit(
                 workspace_id=proposal.workspace_id,
                 proposal_id=proposal.id,
@@ -111,7 +133,7 @@ def complete(
             )
             db.add(commit)
 
-        # Promote knowledge items to ACTIVE
+        # Promote remaining PENDING knowledge items for this doc version to ACTIVE
         for ki in knowledge_items:
             if ki.status == KnowledgeStatus.PENDING:
                 ki.status = KnowledgeStatus.ACTIVE

backend/app/workflow/nodes/validate.py

@@ -35,13 +35,26 @@ def validate(
     new_item_ids = {str(item.id) for item in new_items}
 
     if not new_item_ids:
-        state.validation_results = []
+        error_msg = state.metadata.get("extraction_error") or "No knowledge items were extracted from this document."
+        has_err = bool(state.metadata.get("extraction_error"))
+        state.validation_results = [
+            {
+                "status": "FAIL" if has_err else "WARNING",
+                "severity": "HIGH",
+                "rule_id": None,
+                "rule_name": "Extraction Verification",
+                "rule_type": None,
+                "operator": None,
+                "message": error_msg,
+                "proposal_ids": [],
+            }
+        ]
         state.metadata["validation_summary"] = {
-            "status": "PASS",
-            "rules_evaluated": 0,
+            "status": "FAIL" if has_err else "WARNING",
+            "rules_evaluated": 1,
             "proposals_evaluated": 0,
-            "failures": 0,
-            "warnings": 0,
+            "failures": 1 if has_err else 0,
+            "warnings": 0 if has_err else 1,
         }
         tracker.end_stage("validation")
         return state

backend/tests/test_mcp_e2e.py

@@ -77,6 +77,7 @@ def test_mcp_e2e():
         print("   PASS")
 
         # 5. Get workflow status (use an existing workflow if available)
+        workflow_id = None
         if result:
             workflow_id = result[0]["workflow_id"]
             print(f"\n5. get_workflow_status ({workflow_id[:8]}...)")

docs/one-pager.md

@@ -1,40 +0,0 @@
-# DocWeave — One Page
-
-## What I Built
-
-DocWeave is an agentic document intelligence platform that transforms unstructured documents into a governed knowledge register. It processes PDFs through an AI pipeline (extract, chunk, embed, extract knowledge, reconcile, validate, decide) and either auto-commits verified knowledge or pauses for human review — depending on configurable validation rules.
-
-Think of it as "GitHub for documents": every knowledge change is proposed, validated against rules, reviewed if needed, and committed with full audit trail.
-
-## Who It's For
-
-Teams that manage large document corpora and need structured, searchable, auditable knowledge — compliance officers, research groups, clinical teams, legal departments. Anyone who's ever said "I know we read this somewhere but can't find which document said it."
-
-## Results
-
-- **End-to-end processing**: Upload a PDF, get structured knowledge items (ENTITY, CLAIM, METHOD, METRIC, OBSERVATION) with verbatim evidence quotes and confidence scores in 20-45 seconds.
-- **Zero-loss batch extraction**: Documents of any size are batched and processed sequentially — no data is truncated or lost.
-- **Human-in-the-loop**: 4 configurable validation operators (min_confidence, required_evidence, allowed_proposal_types, topic_relevance) determine auto-commit vs. human review.
-- **Crash resilience**: LangGraph checkpointing means workflows survive server restarts. Graceful shutdown waits for active work; auto-resume picks up orphaned workflows.
-- **MCP integration**: 15-tool Model Context Protocol server lets AI agents drive the full lifecycle programmatically.
-- **Deployed**: Frontend on Vercel, backend on HuggingFace Spaces (Docker), database on Neon PostgreSQL (Singapore).
-
-## Key Trade-Offs
-
-| Decision | Why |
-|----------|-----|
-| **Background threads (not Celery)** | Simpler deployment, no Redis/broker needed. Trade-off: limited to single-server horizontal scaling. Acceptable for a demo/small team tool. |
-| **Groq free tier LLM** | Zero cost, fast inference. Trade-off: strict request size limits on free org tier — knowledge extraction requires small batches. A paid tier or self-hosted model removes this. |
-| **Ephemeral file storage on HF** | Files don't persist across container restarts. Trade-off: retry on old docs fails. Acceptable because production would use S3/GCS. Demo works for freshly uploaded docs. |
-| **sentence-transformers local embeddings** | No external API dependency, runs on CPU. Trade-off: ~300MB memory footprint, can't run on 512MB servers (Render free tier). Works fine on HF Spaces (16GB RAM). |
-| **PostgreSQL for everything (vectors + relational)** | Single database, pgvector handles vector search. Trade-off: not as fast as dedicated vector DBs (Pinecone, Weaviate) at scale. Perfectly adequate for <100K documents. |
-| **Native JSON mode (not tool calling)** | More reliable structured output from Groq/Qwen/Llama models. Trade-off: less strict schema enforcement than OpenAI function calling. Mitigated by robust JSON parsing with fallbacks. |
-
-## What I'd Add With More Time
-
-- Persistent cloud storage (S3) for uploaded documents
-- WebSocket-based real-time progress (currently polls)
-- Multi-user collaboration with role-based access
-- Knowledge graph visualization (entity relationship map)
-- Automatic conflict resolution using LLM reasoning
-- PDF annotation overlay showing where each knowledge item was extracted from