feat: proposal archive/restore governance, knowledge derived status, documents live polling, yellow archive UI

backend/alembic/versions/add_archived_proposal_status.py

@@ -0,0 +1,32 @@
+"""add ARCHIVED to proposal_status enum
+
+Adds the ARCHIVED value to the proposal_status PostgreSQL enum type.
+ARCHIVED means "deferred / parked for later review" — the human is
+explicitly saying "I don't want to decide this right now."
+
+Revision ID: add_archived_proposal_status
+Revises: repair_rejected_items
+Create Date: 2026-08-17
+"""
+
+from alembic import op
+
+
+revision = "add_archived_proposal_status"
+down_revision = "repair_rejected_items"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute(
+        "ALTER TYPE proposal_status "
+        "ADD VALUE IF NOT EXISTS 'ARCHIVED'"
+    )
+
+
+def downgrade() -> None:
+    # PostgreSQL does not support removing a value directly
+    # from an enum type. A downgrade would require recreating
+    # the enum and migrating the column.
+    pass

backend/app/api/activity.py

@@ -211,6 +211,17 @@ def list_activity(
                     "proposal_type": p.proposal_type.value,
                 },
             })
+        if p.status == ProposalStatus.ARCHIVED and p.reviewed_at:
+            events.append({
+                "id": f"proposal-archived-{p.id}",
+                "type": "proposal_archived",
+                "message": f"Proposal archived: {p.summary[:80]}",
+                "timestamp": p.reviewed_at.isoformat(),
+                "metadata": {
+                    "proposal_id": str(p.id),
+                    "proposal_type": p.proposal_type.value,
+                },
+            })
 
     # ------------------------------------------------------------------
     # Commit events

backend/app/api/knowledge.py

@@ -30,6 +30,21 @@ def _knowledge_response(item: KnowledgeItem) -> dict:
             "source_type": ev.source_type,
         })
 
+    # Include the most recent proposal info for governance context
+    proposal_info = None
+    if item.proposals:
+        # Get the most recent proposal (by created_at or just first)
+        latest_proposal = sorted(
+            item.proposals,
+            key=lambda p: p.created_at or "",
+            reverse=True,
+        )[0]
+        proposal_info = {
+            "id": str(latest_proposal.id),
+            "status": latest_proposal.status.value,
+            "proposal_type": latest_proposal.proposal_type.value,
+        }
+
     return {
         "id": str(item.id),
         "workspace_id": str(item.workspace_id),
@@ -42,6 +57,7 @@ def _knowledge_response(item: KnowledgeItem) -> dict:
         "attributes": item.attributes,
         "confidence": item.confidence,
         "status": item.status.value,
+        "proposal": proposal_info,
         "evidence": evidence_list,
         "created_at": item.created_at,
         "updated_at": item.updated_at,
@@ -75,11 +91,40 @@ def list_knowledge(
     )
 
     if status:
-        try:
-            ks = KnowledgeStatus(status.upper())
-            query = query.filter(KnowledgeItem.status == ks)
-        except ValueError:
-            pass
+        status_upper = status.upper()
+
+        # Special case: "ARCHIVED" means knowledge items whose CREATE
+        # proposal has been archived (parked for later review).
+        # The knowledge item itself is still PENDING in the DB.
+        if status_upper == "ARCHIVED":
+            from app.models.proposal import Proposal, ProposalStatus, ProposalType
+            query = (
+                query
+                .join(Proposal, Proposal.knowledge_item_id == KnowledgeItem.id)
+                .filter(
+                    Proposal.proposal_type == ProposalType.CREATE,
+                    Proposal.status == ProposalStatus.ARCHIVED,
+                )
+            )
+        elif status_upper == "PENDING":
+            # PENDING means genuinely untouched — PENDING knowledge with
+            # a PENDING proposal (not archived, not decided).
+            from app.models.proposal import Proposal, ProposalStatus, ProposalType
+            query = (
+                query
+                .filter(KnowledgeItem.status == KnowledgeStatus.PENDING)
+                .join(Proposal, Proposal.knowledge_item_id == KnowledgeItem.id)
+                .filter(
+                    Proposal.proposal_type == ProposalType.CREATE,
+                    Proposal.status == ProposalStatus.PENDING,
+                )
+            )
+        else:
+            try:
+                ks = KnowledgeStatus(status_upper)
+                query = query.filter(KnowledgeItem.status == ks)
+            except ValueError:
+                pass
 
     if type:
         try:

backend/app/api/proposals.py

@@ -86,4 +86,44 @@ def reject_proposal(
         comments=request.comments if request else None,
     )
 
-    return review
+    return review
+
+
+@router.post(
+    "/{proposal_id}/archive",
+    response_model=ProposalResponse,
+)
+def archive_proposal(
+    proposal_id: UUID,
+    request: ReviewRequest | None = None,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    service = ProposalReviewService(db)
+
+    proposal = service.archive(
+        proposal_id=proposal_id,
+        user_id=current_user.id,
+        comments=request.comments if request else None,
+    )
+
+    return proposal
+
+
+@router.post(
+    "/{proposal_id}/restore",
+    response_model=ProposalResponse,
+)
+def restore_proposal(
+    proposal_id: UUID,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    service = ProposalReviewService(db)
+
+    proposal = service.restore(
+        proposal_id=proposal_id,
+        user_id=current_user.id,
+    )
+
+    return proposal

backend/app/models/proposal.py

@@ -30,6 +30,7 @@ class ProposalStatus(str, enum.Enum):
     PENDING = "PENDING"
     APPROVED = "APPROVED"
     REJECTED = "REJECTED"
+    ARCHIVED = "ARCHIVED"
 
 
 class Proposal(Base):

backend/app/services/proposal_review_service.py

@@ -115,6 +115,57 @@ class ProposalReviewService:
 
         return relevant
 
+    def _get_archived_for_document_version(
+        self,
+        workspace_id: uuid.UUID,
+        document_version_id: uuid.UUID,
+    ) -> list[Proposal]:
+        """
+        Return ARCHIVED proposals associated with a specific document version.
+        Same logic as get_pending_for_document_version but for ARCHIVED status.
+        """
+        knowledge_items = (
+            self.db.query(KnowledgeItem.id)
+            .filter(
+                KnowledgeItem.workspace_id == workspace_id,
+                KnowledgeItem.document_version_id == document_version_id,
+            )
+            .all()
+        )
+
+        knowledge_item_ids = {
+            str(item_id)
+            for (item_id,) in knowledge_items
+        }
+
+        if not knowledge_item_ids:
+            return []
+
+        proposals = (
+            self.db.query(Proposal)
+            .filter(
+                Proposal.workspace_id == workspace_id,
+                Proposal.status == ProposalStatus.ARCHIVED,
+            )
+            .all()
+        )
+
+        relevant = []
+        for proposal in proposals:
+            if (
+                proposal.knowledge_item_id is not None
+                and str(proposal.knowledge_item_id) in knowledge_item_ids
+            ):
+                relevant.append(proposal)
+                continue
+
+            changes = proposal.proposed_changes or {}
+            source_id = changes.get("source_knowledge_item_id")
+            if source_id and str(source_id) in knowledge_item_ids:
+                relevant.append(proposal)
+
+        return relevant
+
     def _get_proposal_document_version_id(
         self,
         proposal: Proposal,
@@ -188,6 +239,16 @@ class ProposalReviewService:
         if pending:
             return
 
+        # Also check for ARCHIVED proposals — they are unresolved
+        # (parked for later), so the workflow should not resume.
+        archived = self._get_archived_for_document_version(
+            proposal.workspace_id,
+            document_version_id,
+        )
+
+        if archived:
+            return
+
         from app.repositories.workflow_repository import (
             WorkflowRepository,
         )
@@ -212,6 +273,41 @@ class ProposalReviewService:
         finally:
             executor.close()
     
+    def _pause_workflow_if_needed(
+        self,
+        proposal: Proposal,
+    ) -> None:
+        """
+        If a proposal is being restored and its workflow has already
+        moved past WAITING_FOR_REVIEW, revert the workflow back to
+        WAITING_FOR_REVIEW so the proposal appears in the review queue.
+        """
+        document_version_id = (
+            self._get_proposal_document_version_id(proposal)
+        )
+
+        if document_version_id is None:
+            return
+
+        from app.repositories.workflow_repository import (
+            WorkflowRepository,
+        )
+
+        workflow_repository = WorkflowRepository(self.db)
+
+        workflow = workflow_repository.get_by_document_version(
+            document_version_id
+        )
+
+        if workflow is None:
+            return
+
+        # Only revert COMPLETED workflows back to review.
+        # RUNNING/FAILED/CANCELLED should not be touched.
+        if workflow.status == WorkflowStatus.COMPLETED:
+            workflow.status = WorkflowStatus.WAITING_FOR_REVIEW
+            workflow.completed_at = None
+    
     def approve(
         self,
         proposal_id: uuid.UUID,
@@ -298,6 +394,78 @@ class ProposalReviewService:
             self.db.rollback()
             raise
 
+    # ------------------------------------------------------------------
+    # Archive / Restore
+    # ------------------------------------------------------------------
+
+    def archive(
+        self,
+        proposal_id: uuid.UUID,
+        user_id: uuid.UUID,
+        comments: str | None = None,
+    ) -> Proposal:
+        """
+        Park a proposal for later review.
+
+        Valid from PENDING or ARCHIVED (idempotent).
+        Does NOT mutate the underlying knowledge item.
+        """
+        proposal = self._get_proposal(
+            proposal_id,
+            user_id,
+        )
+
+        self._ensure_archivable(proposal)
+
+        try:
+            proposal.status = ProposalStatus.ARCHIVED
+            proposal.reviewed_at = datetime.now(timezone.utc)
+
+            self.db.commit()
+            self.db.refresh(proposal)
+
+            return proposal
+        except Exception:
+            self.db.rollback()
+            raise
+
+    def restore(
+        self,
+        proposal_id: uuid.UUID,
+        user_id: uuid.UUID,
+    ) -> Proposal:
+        """
+        Restore an archived proposal back to PENDING for review.
+
+        Valid only from ARCHIVED.
+        If the workflow has already completed/resumed, revert it
+        to WAITING_FOR_REVIEW so the proposal appears in the
+        review queue again.
+        """
+        proposal = self._get_proposal(
+            proposal_id,
+            user_id,
+        )
+
+        self._ensure_archived(proposal)
+
+        try:
+            proposal.status = ProposalStatus.PENDING
+            proposal.reviewed_at = None
+
+            # Revert the workflow to WAITING_FOR_REVIEW if it has
+            # moved past review (e.g., completed because all proposals
+            # were archived/resolved).
+            self._pause_workflow_if_needed(proposal)
+
+            self.db.commit()
+            self.db.refresh(proposal)
+
+            return proposal
+        except Exception:
+            self.db.rollback()
+            raise
+
     # ------------------------------------------------------------------
     # Rejection side-effects
     # ------------------------------------------------------------------
@@ -514,12 +682,47 @@ class ProposalReviewService:
         self,
         proposal: Proposal,
     ) -> None:
-        if proposal.status != ProposalStatus.PENDING:
+        """Allow approve/reject from PENDING or ARCHIVED states."""
+        if proposal.status not in (
+            ProposalStatus.PENDING,
+            ProposalStatus.ARCHIVED,
+        ):
             raise HTTPException(
                 status_code=409,
                 detail="Proposal has already been reviewed.",
             )
 
+    def _ensure_archivable(
+        self,
+        proposal: Proposal,
+    ) -> None:
+        """Allow archiving from PENDING only. Already-ARCHIVED is idempotent."""
+        if proposal.status == ProposalStatus.ARCHIVED:
+            return  # idempotent
+        if proposal.status != ProposalStatus.PENDING:
+            raise HTTPException(
+                status_code=409,
+                detail=(
+                    f"Cannot archive a proposal with status "
+                    f"'{proposal.status.value}'. "
+                    "Only PENDING proposals can be archived."
+                ),
+            )
+
+    def _ensure_archived(
+        self,
+        proposal: Proposal,
+    ) -> None:
+        if proposal.status != ProposalStatus.ARCHIVED:
+            raise HTTPException(
+                status_code=409,
+                detail=(
+                    f"Cannot restore a proposal with status "
+                    f"'{proposal.status.value}'. "
+                    "Only ARCHIVED proposals can be restored."
+                ),
+            )
+
     def _verify_workspace_access(
         self,
         workspace_id: uuid.UUID,

backend/tests/test_proposal_archive.py

@@ -0,0 +1,524 @@
+"""
+Phase 2 Proposal Archive/Restore Lifecycle Tests
+=================================================
+
+Tests the ARCHIVED proposal state and its transitions.
+
+ISOLATION: Creates a dedicated test workspace, user, and all
+associated records. Never uses existing workspaces.
+
+Covers:
+- CREATE + ARCHIVE → proposal ARCHIVED, knowledge stays PENDING
+- ARCHIVED CREATE + RESTORE → proposal PENDING again
+- ARCHIVED CREATE + APPROVE → knowledge becomes ACTIVE
+- ARCHIVED CREATE + REJECT → proposal REJECTED, knowledge REJECTED
+- UPDATE + ARCHIVE → knowledge unchanged
+- ARCHIVED UPDATE + RESTORE → proposal PENDING again
+- ARCHIVED UPDATE + APPROVE → knowledge updated
+- ARCHIVED UPDATE + REJECT → knowledge unchanged
+- Invalid: APPROVED → ARCHIVE (409)
+- Invalid: REJECTED → ARCHIVE (409)
+- Invalid: PENDING → RESTORE (409)
+- Invalid: REJECTED → RESTORE (409)
+- Idempotent: ARCHIVED → ARCHIVE (no error)
+- Sentinel: pre-existing data unchanged
+"""
+import sys
+import os
+import uuid
+from datetime import datetime, timezone
+
+import pytest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from app.database.database import SessionLocal
+from app.models.commit import Commit
+from app.models.document import Document
+from app.models.document_version import DocumentVersion, DocumentVersionStatus
+from app.models.knowledge_item import KnowledgeItem, KnowledgeStatus, KnowledgeType
+from app.models.proposal import Proposal, ProposalStatus, ProposalType
+from app.models.review import Review
+from app.models.user import User
+from app.models.workspace import Workspace
+from app.services.proposal_review_service import ProposalReviewService
+
+
+_TEST_RUN_ID = uuid.uuid4().hex[:8]
+
+
+# ------------------------------------------------------------------
+# Fixtures
+# ------------------------------------------------------------------
+
+@pytest.fixture(scope="module")
+def db():
+    session = SessionLocal()
+    yield session
+    session.close()
+
+
+@pytest.fixture(scope="module")
+def isolated_env(db):
+    """Fully isolated test environment."""
+    test_user = User(
+        username=f"archive_test_user_{_TEST_RUN_ID}",
+        email=f"archive_{_TEST_RUN_ID}@test.docweave.local",
+        hashed_password="not_a_real_hash",
+        role="operator",
+    )
+    db.add(test_user)
+    db.flush()
+
+    test_workspace = Workspace(
+        name=f"archive_test_workspace_{_TEST_RUN_ID}",
+        description="Isolated workspace for archive lifecycle tests",
+        created_by=test_user.id,
+    )
+    db.add(test_workspace)
+    db.flush()
+
+    test_doc = Document(
+        workspace_id=test_workspace.id,
+        title=f"archive_test_doc_{_TEST_RUN_ID}",
+        document_type="GENERAL",
+    )
+    db.add(test_doc)
+    db.flush()
+
+    test_version = DocumentVersion(
+        document_id=test_doc.id,
+        version_number=1,
+        filename=f"archive_test_{_TEST_RUN_ID}.txt",
+        file_type=".txt",
+        checksum=f"archive_{_TEST_RUN_ID}",
+        storage_path=f"/tmp/archive_test_{_TEST_RUN_ID}.txt",
+        status=DocumentVersionStatus.PROCESSED,
+        uploaded_by=test_user.id,
+    )
+    db.add(test_version)
+    db.commit()
+
+    yield {
+        "user": test_user,
+        "workspace": test_workspace,
+        "doc": test_doc,
+        "version": test_version,
+    }
+
+    # Cleanup
+    try:
+        db.query(Commit).filter(
+            Commit.workspace_id == test_workspace.id
+        ).delete(synchronize_session=False)
+        proposal_ids_subq = db.query(Proposal.id).filter(
+            Proposal.workspace_id == test_workspace.id
+        )
+        db.query(Review).filter(
+            Review.proposal_id.in_(proposal_ids_subq)
+        ).delete(synchronize_session=False)
+        db.query(Proposal).filter(
+            Proposal.workspace_id == test_workspace.id
+        ).delete(synchronize_session=False)
+        db.query(KnowledgeItem).filter(
+            KnowledgeItem.workspace_id == test_workspace.id
+        ).delete(synchronize_session=False)
+        db.query(DocumentVersion).filter(
+            DocumentVersion.id == test_version.id
+        ).delete(synchronize_session=False)
+        db.query(Document).filter(
+            Document.id == test_doc.id
+        ).delete(synchronize_session=False)
+        db.query(Workspace).filter(
+            Workspace.id == test_workspace.id
+        ).delete(synchronize_session=False)
+        db.query(User).filter(
+            User.id == test_user.id
+        ).delete(synchronize_session=False)
+        db.commit()
+    except Exception:
+        db.rollback()
+
+
+@pytest.fixture()
+def test_db():
+    session = SessionLocal()
+    yield session
+    session.close()
+
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+def _create_item(db, workspace, version, status=KnowledgeStatus.PENDING):
+    item = KnowledgeItem(
+        workspace_id=workspace.id,
+        document_version_id=version.id,
+        type=KnowledgeType.CLAIM,
+        title=f"Archive Test {uuid.uuid4().hex[:8]}",
+        value="Test value for archive lifecycle",
+        summary="Test summary",
+        confidence=0.9,
+        status=status,
+    )
+    db.add(item)
+    db.commit()
+    db.refresh(item)
+    return item
+
+
+def _create_proposal(db, workspace, item, proposal_type, proposed_changes=None):
+    proposal = Proposal(
+        workspace_id=workspace.id,
+        knowledge_item_id=item.id if item else None,
+        proposal_type=proposal_type,
+        status=ProposalStatus.PENDING,
+        summary=f"Archive test {proposal_type.value} {uuid.uuid4().hex[:6]}",
+        rationale="Testing archive lifecycle",
+        proposed_changes=proposed_changes or {"title": "test", "value": "test"},
+    )
+    db.add(proposal)
+    db.commit()
+    db.refresh(proposal)
+    return proposal
+
+
+# ------------------------------------------------------------------
+# CREATE + ARCHIVE
+# ------------------------------------------------------------------
+
+def test_create_archive(test_db, isolated_env):
+    """Archiving a CREATE proposal parks it; knowledge stays PENDING."""
+    env = isolated_env
+    item = _create_item(test_db, env["workspace"], env["version"])
+    proposal = _create_proposal(test_db, env["workspace"], item, ProposalType.CREATE)
+
+    service = ProposalReviewService(test_db)
+    result = service.archive(
+        proposal_id=proposal.id,
+        user_id=env["user"].id,
+    )
+
+    test_db.refresh(item)
+    test_db.refresh(proposal)
+
+    assert proposal.status == ProposalStatus.ARCHIVED
+    assert proposal.reviewed_at is not None
+    assert item.status == KnowledgeStatus.PENDING  # NOT changed
+
+
+# ------------------------------------------------------------------
+# ARCHIVED CREATE + RESTORE
+# ------------------------------------------------------------------
+
+def test_archived_create_restore(test_db, isolated_env):
+    """Restoring an archived CREATE proposal returns it to PENDING."""
+    env = isolated_env
+    item = _create_item(test_db, env["workspace"], env["version"])
+    proposal = _create_proposal(test_db, env["workspace"], item, ProposalType.CREATE)
+
+    service = ProposalReviewService(test_db)
+    service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+
+    test_db.refresh(proposal)
+    assert proposal.status == ProposalStatus.ARCHIVED
+
+    service.restore(proposal_id=proposal.id, user_id=env["user"].id)
+
+    test_db.refresh(proposal)
+    assert proposal.status == ProposalStatus.PENDING
+    assert proposal.reviewed_at is None
+
+
+# ------------------------------------------------------------------
+# ARCHIVED CREATE + APPROVE
+# ------------------------------------------------------------------
+
+def test_archived_create_approve(test_db, isolated_env):
+    """Approving directly from ARCHIVED promotes knowledge to ACTIVE."""
+    env = isolated_env
+    item = _create_item(test_db, env["workspace"], env["version"])
+    proposal = _create_proposal(test_db, env["workspace"], item, ProposalType.CREATE)
+
+    service = ProposalReviewService(test_db)
+    service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+
+    commit = service.approve(
+        proposal_id=proposal.id,
+        user_id=env["user"].id,
+        comments="Approved from archived",
+    )
+
+    test_db.refresh(item)
+    test_db.refresh(proposal)
+
+    assert proposal.status == ProposalStatus.APPROVED
+    assert item.status == KnowledgeStatus.ACTIVE
+    assert commit is not None
+
+
+# ------------------------------------------------------------------
+# ARCHIVED CREATE + REJECT
+# ------------------------------------------------------------------
+
+def test_archived_create_reject(test_db, isolated_env):
+    """Rejecting directly from ARCHIVED marks proposal REJECTED, knowledge REJECTED."""
+    env = isolated_env
+    item = _create_item(test_db, env["workspace"], env["version"])
+    proposal = _create_proposal(test_db, env["workspace"], item, ProposalType.CREATE)
+
+    service = ProposalReviewService(test_db)
+    service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+
+    review = service.reject(
+        proposal_id=proposal.id,
+        user_id=env["user"].id,
+        comments="Rejected from archived",
+    )
+
+    test_db.refresh(item)
+    test_db.refresh(proposal)
+
+    assert proposal.status == ProposalStatus.REJECTED
+    assert item.status == KnowledgeStatus.REJECTED
+    assert review is not None
+
+
+# ------------------------------------------------------------------
+# UPDATE + ARCHIVE
+# ------------------------------------------------------------------
+
+def test_update_archive(test_db, isolated_env):
+    """Archiving an UPDATE proposal leaves existing knowledge unchanged."""
+    env = isolated_env
+    target = _create_item(test_db, env["workspace"], env["version"], status=KnowledgeStatus.ACTIVE)
+    source = _create_item(test_db, env["workspace"], env["version"])
+    original_value = target.value
+
+    proposal = _create_proposal(
+        test_db, env["workspace"], target, ProposalType.UPDATE,
+        proposed_changes={
+            "existing": {"value": target.value},
+            "proposed": {"value": "Should not be applied yet"},
+            "source_knowledge_item_id": str(source.id),
+        },
+    )
+
+    service = ProposalReviewService(test_db)
+    service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+
+    test_db.refresh(target)
+    test_db.refresh(proposal)
+
+    assert proposal.status == ProposalStatus.ARCHIVED
+    assert target.status == KnowledgeStatus.ACTIVE
+    assert target.value == original_value
+
+
+# ------------------------------------------------------------------
+# ARCHIVED UPDATE + RESTORE
+# ------------------------------------------------------------------
+
+def test_archived_update_restore(test_db, isolated_env):
+    """Restoring an archived UPDATE returns it to PENDING."""
+    env = isolated_env
+    target = _create_item(test_db, env["workspace"], env["version"], status=KnowledgeStatus.ACTIVE)
+    proposal = _create_proposal(
+        test_db, env["workspace"], target, ProposalType.UPDATE,
+        proposed_changes={
+            "existing": {"value": target.value},
+            "proposed": {"value": "Maybe later"},
+            "source_knowledge_item_id": str(uuid.uuid4()),
+        },
+    )
+
+    service = ProposalReviewService(test_db)
+    service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+    service.restore(proposal_id=proposal.id, user_id=env["user"].id)
+
+    test_db.refresh(proposal)
+    assert proposal.status == ProposalStatus.PENDING
+
+
+# ------------------------------------------------------------------
+# ARCHIVED UPDATE + APPROVE
+# ------------------------------------------------------------------
+
+def test_archived_update_approve(test_db, isolated_env):
+    """Approving directly from ARCHIVED applies the update."""
+    env = isolated_env
+    target = _create_item(test_db, env["workspace"], env["version"], status=KnowledgeStatus.ACTIVE)
+    source = _create_item(test_db, env["workspace"], env["version"])
+
+    proposal = _create_proposal(
+        test_db, env["workspace"], target, ProposalType.UPDATE,
+        proposed_changes={
+            "existing": {"value": target.value},
+            "proposed": {"value": "Applied from archived", "confidence": 0.99},
+            "source_knowledge_item_id": str(source.id),
+        },
+    )
+
+    service = ProposalReviewService(test_db)
+    service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+
+    commit = service.approve(
+        proposal_id=proposal.id,
+        user_id=env["user"].id,
+    )
+
+    test_db.refresh(target)
+    test_db.refresh(source)
+
+    assert target.value == "Applied from archived"
+    assert target.confidence == 0.99
+    assert source.status == KnowledgeStatus.SUPERSEDED
+    assert commit is not None
+
+
+# ------------------------------------------------------------------
+# ARCHIVED UPDATE + REJECT
+# ------------------------------------------------------------------
+
+def test_archived_update_reject(test_db, isolated_env):
+    """Rejecting from ARCHIVED leaves existing knowledge unchanged."""
+    env = isolated_env
+    target = _create_item(test_db, env["workspace"], env["version"], status=KnowledgeStatus.ACTIVE)
+    original_value = target.value
+
+    proposal = _create_proposal(
+        test_db, env["workspace"], target, ProposalType.UPDATE,
+        proposed_changes={
+            "existing": {"value": target.value},
+            "proposed": {"value": "Should never apply"},
+        },
+    )
+
+    service = ProposalReviewService(test_db)
+    service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+    service.reject(proposal_id=proposal.id, user_id=env["user"].id)
+
+    test_db.refresh(target)
+    assert target.status == KnowledgeStatus.ACTIVE
+    assert target.value == original_value
+
+
+# ------------------------------------------------------------------
+# Invalid: APPROVED → ARCHIVE (409)
+# ------------------------------------------------------------------
+
+def test_cannot_archive_approved(test_db, isolated_env):
+    """Cannot archive an already-approved proposal."""
+    env = isolated_env
+    item = _create_item(test_db, env["workspace"], env["version"])
+    proposal = _create_proposal(test_db, env["workspace"], item, ProposalType.CREATE)
+
+    service = ProposalReviewService(test_db)
+    service.approve(proposal_id=proposal.id, user_id=env["user"].id)
+
+    from fastapi import HTTPException
+    with pytest.raises(HTTPException) as exc_info:
+        service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+    assert exc_info.value.status_code == 409
+
+
+# ------------------------------------------------------------------
+# Invalid: REJECTED → ARCHIVE (409)
+# ------------------------------------------------------------------
+
+def test_cannot_archive_rejected(test_db, isolated_env):
+    """Cannot archive an already-rejected proposal."""
+    env = isolated_env
+    item = _create_item(test_db, env["workspace"], env["version"])
+    proposal = _create_proposal(test_db, env["workspace"], item, ProposalType.CREATE)
+
+    service = ProposalReviewService(test_db)
+    service.reject(proposal_id=proposal.id, user_id=env["user"].id)
+
+    from fastapi import HTTPException
+    with pytest.raises(HTTPException) as exc_info:
+        service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+    assert exc_info.value.status_code == 409
+
+
+# ------------------------------------------------------------------
+# Invalid: PENDING → RESTORE (409)
+# ------------------------------------------------------------------
+
+def test_cannot_restore_pending(test_db, isolated_env):
+    """Cannot restore a PENDING proposal (it's not archived)."""
+    env = isolated_env
+    item = _create_item(test_db, env["workspace"], env["version"])
+    proposal = _create_proposal(test_db, env["workspace"], item, ProposalType.CREATE)
+
+    service = ProposalReviewService(test_db)
+
+    from fastapi import HTTPException
+    with pytest.raises(HTTPException) as exc_info:
+        service.restore(proposal_id=proposal.id, user_id=env["user"].id)
+    assert exc_info.value.status_code == 409
+
+
+# ------------------------------------------------------------------
+# Invalid: REJECTED → RESTORE (409)
+# ------------------------------------------------------------------
+
+def test_cannot_restore_rejected(test_db, isolated_env):
+    """Cannot restore a REJECTED proposal."""
+    env = isolated_env
+    item = _create_item(test_db, env["workspace"], env["version"])
+    proposal = _create_proposal(test_db, env["workspace"], item, ProposalType.CREATE)
+
+    service = ProposalReviewService(test_db)
+    service.reject(proposal_id=proposal.id, user_id=env["user"].id)
+
+    from fastapi import HTTPException
+    with pytest.raises(HTTPException) as exc_info:
+        service.restore(proposal_id=proposal.id, user_id=env["user"].id)
+    assert exc_info.value.status_code == 409
+
+
+# ------------------------------------------------------------------
+# Idempotent: ARCHIVED → ARCHIVE (no error)
+# ------------------------------------------------------------------
+
+def test_archive_idempotent(test_db, isolated_env):
+    """Archiving an already-archived proposal is idempotent."""
+    env = isolated_env
+    item = _create_item(test_db, env["workspace"], env["version"])
+    proposal = _create_proposal(test_db, env["workspace"], item, ProposalType.CREATE)
+
+    service = ProposalReviewService(test_db)
+    service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+
+    # Second archive should not raise
+    result = service.archive(proposal_id=proposal.id, user_id=env["user"].id)
+
+    test_db.refresh(proposal)
+    assert proposal.status == ProposalStatus.ARCHIVED
+
+
+# ------------------------------------------------------------------
+# Sentinel: pre-existing data unchanged
+# ------------------------------------------------------------------
+
+def test_sentinel_no_real_data_modified(test_db, isolated_env):
+    """Verify no KnowledgeItem outside our test workspace was modified."""
+    env = isolated_env
+    from sqlalchemy import text
+
+    result = test_db.execute(text("""
+        SELECT COUNT(*) FROM knowledge_items
+        WHERE workspace_id != :ws_id
+          AND updated_at > :threshold
+    """), {
+        "ws_id": str(env["workspace"].id),
+        "threshold": env["workspace"].created_at,
+    })
+
+    modified_count = result.scalar()
+    assert modified_count == 0, (
+        f"{modified_count} knowledge items outside the test workspace were "
+        f"modified during this test run. Test isolation is broken."
+    )

frontend/src/api/proposals.js

@@ -28,3 +28,19 @@ export async function approveProposal(proposalId, comments = null) {
 export async function rejectProposal(proposalId, comments = null) {
     return apiRequest(`/proposals/${proposalId}/reject`, "POST", { comments });
 }
+
+/**
+ * POST /proposals/{proposal_id}/archive
+ * → ProposalResponse
+ */
+export async function archiveProposal(proposalId, comments = null) {
+    return apiRequest(`/proposals/${proposalId}/archive`, "POST", { comments });
+}
+
+/**
+ * POST /proposals/{proposal_id}/restore
+ * → ProposalResponse
+ */
+export async function restoreProposal(proposalId) {
+    return apiRequest(`/proposals/${proposalId}/restore`, "POST");
+}

frontend/src/components/proposals/ProposalCard.jsx

@@ -11,11 +11,16 @@ const TYPE_TONE = {
     SPLIT: "info",
 };
 
+const STATUS_TONE = {
+    PENDING: "default",
+    APPROVED: "success",
+    REJECTED: "danger",
+    ARCHIVED: "info",
+};
+
 // Confirmed field sets per proposal_type, from real API responses:
 // - UPDATE: { existing: {...}, proposed: {...}, source_knowledge_item_id }
 // - CREATE: { type, title, value, summary, attributes, confidence } (flat)
-// Anything outside these known keys, or any other proposal_type
-// (DELETE/MERGE/SPLIT — shape not yet observed), falls back to raw JSON.
 const COMPARE_FIELDS = [
     { key: "value", label: "Value" },
     { key: "summary", label: "Summary" },
@@ -139,16 +144,22 @@ function ProposedChanges({ proposalType, changes }) {
 }
 
 /**
- * One PENDING proposal with Approve/Reject actions.
- * proposal shape matches ProposalResponse (app/schemas/proposal.py) exactly:
- * id, workspace_id, knowledge_item_id, proposal_type, status, summary,
- * rationale, proposed_changes, created_at, reviewed_at.
+ * Proposal card with context-appropriate actions:
+ *
+ * PENDING:   Approve / Reject / Archive
+ * ARCHIVED:  Restore (returns to PENDING for review)
+ * APPROVED:  Read-only history
+ * REJECTED:  Read-only history
  */
-export function ProposalCard({ proposal, onApprove, onReject, busy }) {
+export function ProposalCard({ proposal, onApprove, onReject, onArchive, onRestore, busy }) {
     const [comments, setComments] = useState("");
     const [showComments, setShowComments] = useState(false);
     const [showDetails, setShowDetails] = useState(false);
 
+    const isPending = proposal.status === "PENDING";
+    const isArchived = proposal.status === "ARCHIVED";
+    const isReviewable = isPending || isArchived;
+
     return (
         <Card>
             <CardBody>
@@ -156,6 +167,11 @@ export function ProposalCard({ proposal, onApprove, onReject, busy }) {
                     <Badge tone={TYPE_TONE[proposal.proposal_type] || "default"}>
                         {PROPOSAL_TYPE_LABELS[proposal.proposal_type] || proposal.proposal_type}
                     </Badge>
+                    {!isPending && (
+                        <Badge tone={STATUS_TONE[proposal.status] || "default"}>
+                            {proposal.status}
+                        </Badge>
+                    )}
                     <span className="dw-proposal-card__timestamp">
                         {new Date(proposal.created_at).toLocaleString()}
                     </span>
@@ -181,7 +197,7 @@ export function ProposalCard({ proposal, onApprove, onReject, busy }) {
                     />
                 )}
 
-                {showComments && (
+                {isReviewable && showComments && (
                     <textarea
                         className="dw-proposal-card__textarea"
                         value={comments}
@@ -191,35 +207,80 @@ export function ProposalCard({ proposal, onApprove, onReject, busy }) {
                     />
                 )}
 
-                <div className="dw-proposal-card__actions">
-                    <Button
-                        size="sm"
-                        variant="primary"
-                        loading={busy === "approve"}
-                        disabled={Boolean(busy)}
-                        onClick={() => onApprove(proposal.id, comments || null)}
-                    >
-                        Approve
-                    </Button>
-                    <Button
-                        size="sm"
-                        variant="danger"
-                        loading={busy === "reject"}
-                        disabled={Boolean(busy)}
-                        onClick={() => onReject(proposal.id, comments || null)}
-                    >
-                        Reject
-                    </Button>
-                    <Button
-                        size="sm"
-                        variant="ghost"
-                        disabled={Boolean(busy)}
-                        onClick={() => setShowComments((v) => !v)}
-                    >
-                        {showComments ? "Hide comment" : "Add comment"}
-                    </Button>
-                </div>
+                {/* PENDING: Approve / Reject / Archive */}
+                {isPending && (
+                    <div className="dw-proposal-card__actions">
+                        <Button
+                            size="sm"
+                            variant="primary"
+                            loading={busy === "approve"}
+                            disabled={Boolean(busy)}
+                            onClick={() => onApprove?.(proposal.id, comments || null)}
+                        >
+                            Approve
+                        </Button>
+                        <Button
+                            size="sm"
+                            variant="danger"
+                            loading={busy === "reject"}
+                            disabled={Boolean(busy)}
+                            onClick={() => onReject?.(proposal.id, comments || null)}
+                        >
+                            Reject
+                        </Button>
+                        <Button
+                            size="sm"
+                            variant="warning"
+                            loading={busy === "archive"}
+                            disabled={Boolean(busy)}
+                            onClick={() => onArchive?.(proposal.id, comments || null)}
+                        >
+                            Archive
+                        </Button>
+                        <Button
+                            size="sm"
+                            variant="ghost"
+                            disabled={Boolean(busy)}
+                            onClick={() => setShowComments((v) => !v)}
+                        >
+                            {showComments ? "Hide comment" : "Add comment"}
+                        </Button>
+                    </div>
+                )}
+
+                {/* ARCHIVED: Restore */}
+                {isArchived && (
+                    <div className="dw-proposal-card__actions">
+                        <Button
+                            size="sm"
+                            variant="primary"
+                            loading={busy === "restore"}
+                            disabled={Boolean(busy)}
+                            onClick={() => onRestore?.(proposal.id)}
+                        >
+                            Restore to review
+                        </Button>
+                        <Button
+                            size="sm"
+                            variant="primary"
+                            loading={busy === "approve"}
+                            disabled={Boolean(busy)}
+                            onClick={() => onApprove?.(proposal.id, comments || null)}
+                        >
+                            Approve
+                        </Button>
+                        <Button
+                            size="sm"
+                            variant="danger"
+                            loading={busy === "reject"}
+                            disabled={Boolean(busy)}
+                            onClick={() => onReject?.(proposal.id, comments || null)}
+                        >
+                            Reject
+                        </Button>
+                    </div>
+                )}
             </CardBody>
         </Card>
     );
-}
+}

frontend/src/components/proposals/ProposalReviewList.jsx

@@ -1,12 +1,12 @@
 import { useCallback, useEffect, useState } from "react";
-import { listPendingProposals, approveProposal, rejectProposal } from "../../api/proposals";
+import { listPendingProposals, approveProposal, rejectProposal, archiveProposal, restoreProposal } from "../../api/proposals";
 import { ProposalCard } from "./ProposalCard";
 import { LoadingState, EmptyState } from "../ui";
 
 /**
  * Fetches and renders PENDING proposals for a workspace, with real
- * approve/reject actions. If documentVersionId is provided, results
- * are scoped to that document version.
+ * approve/reject/archive actions. If documentVersionId is provided,
+ * results are scoped to that document version.
  *
  * State is never cached locally: every mount and every decision refetches
  * from the API, so a refresh always reflects real backend state.
@@ -50,8 +50,12 @@ export function ProposalReviewList({ workspaceId, documentVersionId, onDecision
         try {
             if (action === "approve") {
                 await approveProposal(proposalId, comments);
-            } else {
+            } else if (action === "reject") {
                 await rejectProposal(proposalId, comments);
+            } else if (action === "archive") {
+                await archiveProposal(proposalId, comments);
+            } else if (action === "restore") {
+                await restoreProposal(proposalId);
             }
             onDecision?.();
             // Refresh in background to sync with server
@@ -92,6 +96,8 @@ export function ProposalReviewList({ workspaceId, documentVersionId, onDecision
                     busy={busyId === proposal.id ? busyAction : null}
                     onApprove={(id, c) => handleDecision("approve", id, c)}
                     onReject={(id, c) => handleDecision("reject", id, c)}
+                    onArchive={(id, c) => handleDecision("archive", id, c)}
+                    onRestore={(id) => handleDecision("restore", id, null)}
                 />
             ))}
         </div>

frontend/src/components/ui/Button.css

@@ -72,6 +72,16 @@
   color: #ffffff;
 }
 
+.dw-btn--warning {
+  background: rgba(234, 179, 8, 0.15);
+  border-color: transparent;
+  color: #eab308;
+}
+.dw-btn--warning:hover:not(:disabled) {
+  background: #eab308;
+  color: #000000;
+}
+
 .dw-btn__icon {
   display: inline-flex;
   align-items: center;

frontend/src/components/ui/Button.jsx

@@ -3,7 +3,7 @@ import { Spinner } from "./Spinner";
 import "./Button.css";
 
 /**
- * variant: "primary" | "secondary" | "ghost" | "danger"
+ * variant: "primary" | "secondary" | "ghost" | "danger" | "warning"
  * size: "sm" | "md"
  */
 export const Button = forwardRef(function Button(

frontend/src/pages/Activity.jsx

@@ -13,6 +13,7 @@ const TYPE_LABELS = {
     proposal_created: "Proposal Created",
     proposal_approved: "Proposal Approved",
     proposal_rejected: "Proposal Rejected",
+    proposal_archived: "Proposal Archived",
     commit_created: "Commit Created",
 };
 
@@ -24,6 +25,7 @@ const TYPE_TONE = {
     proposal_created: "info",
     proposal_approved: "success",
     proposal_rejected: "danger",
+    proposal_archived: "info",
     commit_created: "success",
 };
 

frontend/src/pages/Dashboard.jsx

@@ -24,6 +24,7 @@ const EVENT_ICONS = {
     proposal_created: "📝",
     proposal_approved: "✓",
     proposal_rejected: "✗",
+    proposal_archived: "📦",
     commit_created: "💾",
 };
 

frontend/src/pages/Documents.jsx

@@ -7,25 +7,55 @@ import { WORKFLOW_STATUS_LABELS } from "../utils/labels";
 import "./Documents.css";
 
 const STATUS_TONE = {
-    PENDING: "default", RUNNING: "accent", WAITING_FOR_REVIEW: "warning",
-    COMPLETED: "success", FAILED: "danger", CANCELLED: "info",
+    PENDING: "default",
+    RUNNING: "accent",
+    WAITING_FOR_REVIEW: "warning",
+    COMPLETED: "success",
+    FAILED: "danger",
+    CANCELLED: "info",
 };
 
+const ACTIVE_STATUSES = new Set(["PENDING", "RUNNING"]);
+const POLL_INTERVAL = 3000;
+
 function FileIcon({ filename }) {
     const ext = (filename || "").split(".").pop()?.toLowerCase() || "";
-    const map = { pdf: "pdf", docx: "doc", doc: "doc", txt: "txt", csv: "csv", xlsx: "xls", xls: "xls", png: "img", jpg: "img", jpeg: "img" };
+    const map = {
+        pdf: "pdf",
+        docx: "doc",
+        doc: "doc",
+        txt: "txt",
+        csv: "csv",
+        xlsx: "xls",
+        xls: "xls",
+        png: "img",
+        jpg: "img",
+        jpeg: "img",
+    };
     const type = map[ext] || "txt";
-    return <span className={`dw-table__file-icon dw-table__file-icon--${type}`}>{ext.slice(0, 3)}</span>;
+
+    return (
+        <span className={`dw-table__file-icon dw-table__file-icon--${type}`}>
+            {ext.slice(0, 3)}
+        </span>
+    );
 }
 
 function ConfidenceInline({ value }) {
-    if (value == null) return <span style={{ color: "var(--color-text-muted)" }}>—</span>;
+    if (value == null) {
+        return <span style={{ color: "var(--color-text-muted)" }}>—</span>;
+    }
+
     const pct = Math.round(value * 100);
     const cls = pct >= 85 ? "high" : pct >= 60 ? "med" : "low";
+
     return (
         <span className="dw-table__confidence">
             <span className="dw-table__confidence-bar">
-                <span className={`dw-table__confidence-fill dw-table__confidence-fill--${cls}`} style={{ width: `${pct}%` }} />
+                <span
+                    className={`dw-table__confidence-fill dw-table__confidence-fill--${cls}`}
+                    style={{ width: `${pct}%` }}
+                />
             </span>
             <span>{pct}%</span>
         </span>
@@ -36,6 +66,8 @@ export default function Documents() {
     const { workspace, loading: wsLoading, error: wsError } = useWorkspace();
     const navigate = useNavigate();
     const fileInputRef = useRef(null);
+    const pollTimerRef = useRef(null);
+
     const [uploading, setUploading] = useState(false);
     const [documents, setDocuments] = useState([]);
     const [docsLoading, setDocsLoading] = useState(true);
@@ -44,47 +76,163 @@ export default function Documents() {
     const [search, setSearch] = useState("");
 
     const loadDocuments = useCallback(async () => {
-        if (!workspace) return;
-        setDocsLoading(true);
+        if (!workspace) return [];
+
         try {
             const result = await listDocuments(workspace.id);
-            if (Array.isArray(result)) setDocuments(result);
-        } catch { /* silent */ } finally { setDocsLoading(false); }
+
+            if (Array.isArray(result)) {
+                setDocuments(result);
+                return result;
+            }
+        } catch {
+            // Silent refresh failure. The next poll/load can recover.
+        }
+
+        return [];
     }, [workspace]);
 
-    useEffect(() => { loadDocuments(); }, [loadDocuments]);
+    /*
+     * Initial document load.
+     */
+    useEffect(() => {
+        if (!workspace) return;
 
-    const handleUpload = useCallback(async (e) => {
-        const files = Array.from(e.target.files || []);
-        if (!files.length || !workspace) return;
-        setUploading(true); setUploadError(null);
-        try {
-            const result = await uploadDocuments(workspace.id, files);
-            if (result?.detail) { setUploadError(result.detail); return; }
-            await loadDocuments();
-        } catch { setUploadError("Upload failed."); }
-        finally { setUploading(false); e.target.value = ""; }
-    }, [workspace, loadDocuments]);
+        let cancelled = false;
+
+        const initialLoad = async () => {
+            setDocsLoading(true);
+
+            try {
+                const result = await listDocuments(workspace.id);
+
+                if (!cancelled && Array.isArray(result)) {
+                    setDocuments(result);
+                }
+            } catch {
+                // Silent initial-load failure.
+            } finally {
+                if (!cancelled) {
+                    setDocsLoading(false);
+                }
+            }
+        };
+
+        initialLoad();
+
+        return () => {
+            cancelled = true;
+        };
+    }, [workspace]);
+
+    /*
+     * Poll while any document is actively processing.
+     *
+     * This keeps the Documents page synchronized with workflow state:
+     *
+     * PENDING/RUNNING
+     *       ↓
+     * WAITING_FOR_REVIEW / COMPLETED / FAILED
+     *
+     * Polling stops automatically once there are no active documents.
+     */
+    useEffect(() => {
+        if (!workspace) return;
+
+        const hasActiveDocuments = documents.some((doc) =>
+            ACTIVE_STATUSES.has(doc.workflow_status)
+        );
+
+        if (!hasActiveDocuments) {
+            if (pollTimerRef.current) {
+                clearTimeout(pollTimerRef.current);
+                pollTimerRef.current = null;
+            }
+            return;
+        }
+
+        pollTimerRef.current = setTimeout(async () => {
+            const latest = await loadDocuments();
+
+            /*
+             * The next render will decide whether another poll is necessary
+             * based on the updated document statuses.
+             */
+            if (!latest.some((doc) => ACTIVE_STATUSES.has(doc.workflow_status))) {
+                if (pollTimerRef.current) {
+                    clearTimeout(pollTimerRef.current);
+                    pollTimerRef.current = null;
+                }
+            }
+        }, POLL_INTERVAL);
+
+        return () => {
+            if (pollTimerRef.current) {
+                clearTimeout(pollTimerRef.current);
+                pollTimerRef.current = null;
+            }
+        };
+    }, [workspace, documents, loadDocuments]);
+
+    const handleUpload = useCallback(
+        async (e) => {
+            const files = Array.from(e.target.files || []);
+
+            if (!files.length || !workspace) return;
+
+            setUploading(true);
+            setUploadError(null);
+
+            try {
+                const result = await uploadDocuments(workspace.id, files);
+
+                if (result?.detail) {
+                    setUploadError(result.detail);
+                    return;
+                }
+
+                await loadDocuments();
+            } catch {
+                setUploadError("Upload failed.");
+            } finally {
+                setUploading(false);
+                e.target.value = "";
+            }
+        },
+        [workspace, loadDocuments]
+    );
 
     const handleDelete = (e, doc) => {
         e.stopPropagation();
         e.preventDefault();
-        // Optimistically remove from UI immediately
+
+        // Optimistically remove from UI immediately.
         setDocuments((prev) => prev.filter((d) => d.id !== doc.id));
-        deleteDocument(doc.id).catch(() => loadDocuments()); // revert on failure
+
+        deleteDocument(doc.id).catch(() => loadDocuments());
     };
 
     const handleRetry = (e, doc) => {
         e.stopPropagation();
+
         retryDocument(doc.id).then(loadDocuments);
     };
 
-    // Filter + search
+    // Filter + search.
     let filtered = documents;
-    if (filter !== "all") filtered = filtered.filter((d) => d.workflow_status === filter);
+
+    if (filter !== "all") {
+        filtered = filtered.filter(
+            (d) => d.workflow_status === filter
+        );
+    }
+
     if (search.trim()) {
         const q = search.toLowerCase();
-        filtered = filtered.filter((d) => d.filename?.toLowerCase().includes(q));
+
+        filtered = filtered.filter((d) =>
+            d.filename?.toLowerCase().includes(q)
+        );
     }
 
     const FILTERS = [
@@ -97,7 +245,9 @@ export default function Documents() {
 
     const columns = [
         {
-            key: "filename", label: "Document", sortable: true,
+            key: "filename",
+            label: "Document",
+            sortable: true,
             render: (val, row) => (
                 <span className="dw-table__filename-cell">
                     <FileIcon filename={val} />
@@ -106,33 +256,99 @@ export default function Documents() {
             ),
         },
         {
-            key: "document_type", label: "Type", sortable: true, width: "90px",
-            render: (val) => <span style={{ fontSize: "var(--text-xs)", color: "var(--color-text-muted)" }}>{val || "—"}</span>,
+            key: "document_type",
+            label: "Type",
+            sortable: true,
+            width: "90px",
+            render: (val) => (
+                <span
+                    style={{
+                        fontSize: "var(--text-xs)",
+                        color: "var(--color-text-muted)",
+                    }}
+                >
+                    {val || "—"}
+                </span>
+            ),
         },
         {
-            key: "uploaded_at", label: "Uploaded", sortable: true, width: "160px",
-            render: (val) => <span style={{ fontSize: "var(--text-xs)" }}>{val ? new Date(val).toLocaleString() : "—"}</span>,
+            key: "uploaded_at",
+            label: "Uploaded",
+            sortable: true,
+            width: "160px",
+            render: (val) => (
+                <span style={{ fontSize: "var(--text-xs)" }}>
+                    {val ? new Date(val).toLocaleString() : "—"}
+                </span>
+            ),
         },
         {
-            key: "workflow_status", label: "Status", sortable: true, width: "120px",
-            render: (val) => val ? <Badge tone={STATUS_TONE[val] || "default"}>{WORKFLOW_STATUS_LABELS[val] || val}</Badge> : <span style={{ color: "var(--color-text-muted)" }}>—</span>,
+            key: "workflow_status",
+            label: "Status",
+            sortable: true,
+            width: "120px",
+            render: (val) =>
+                val ? (
+                    <Badge tone={STATUS_TONE[val] || "default"}>
+                        {WORKFLOW_STATUS_LABELS[val] || val}
+                    </Badge>
+                ) : (
+                    <span
+                        style={{
+                            color: "var(--color-text-muted)",
+                        }}
+                    >
+                        —
+                    </span>
+                ),
         },
         {
-            key: "actions", label: "", width: "100px", align: "right",
+            key: "actions",
+            label: "",
+            width: "100px",
+            align: "right",
             render: (_, row) => (
                 <span className="dw-table__actions">
-                    <button className="dw-table__action-btn dw-table__action-btn--retry" title="Retry" onClick={(e) => handleRetry(e, row)}>↻</button>
+                    <button
+                        className="dw-table__action-btn dw-table__action-btn--retry"
+                        title="Retry"
+                        onClick={(e) => handleRetry(e, row)}
+                    >
+                        ↻
+                    </button>
+
                     {row.workflow_id && (
-                        <button className="dw-table__action-btn" title="View workflow" onClick={(e) => { e.stopPropagation(); navigate(`/workflows/${row.workflow_id}`); }}>→</button>
+                        <button
+                            className="dw-table__action-btn"
+                            title="View workflow"
+                            onClick={(e) => {
+                                e.stopPropagation();
+                                navigate(`/workflows/${row.workflow_id}`);
+                            }}
+                        >
+                            →
+                        </button>
                     )}
-                    <button className="dw-table__action-btn dw-table__action-btn--danger" title="Delete" onClick={(e) => handleDelete(e, row)}>×</button>
+
+                    <button
+                        className="dw-table__action-btn dw-table__action-btn--danger"
+                        title="Delete"
+                        onClick={(e) => handleDelete(e, row)}
+                    >
+                        ×
+                    </button>
                 </span>
             ),
         },
     ];
 
-    if (wsLoading) return <LoadingState label="Loading..." />;
-    if (wsError) return <EmptyState title="Error" description={wsError} />;
+    if (wsLoading) {
+        return <LoadingState label="Loading..." />;
+    }
+
+    if (wsError) {
+        return <EmptyState title="Error" description={wsError} />;
+    }
 
     return (
         <div className="dw-page">
@@ -140,16 +356,39 @@ export default function Documents() {
                 <div className="dw-docs__header-row">
                     <div>
                         <h1>Documents</h1>
-                        <p>Your source files. Upload documents to extract and govern knowledge.</p>
+                        <p>
+                            Your source files. Upload documents to extract and
+                            govern knowledge.
+                        </p>
                     </div>
+
                     <div>
-                        <input ref={fileInputRef} type="file" multiple onChange={handleUpload} style={{ display: "none" }} disabled={uploading} />
-                        <Button loading={uploading} onClick={() => fileInputRef.current?.click()}>+ Upload</Button>
+                        <input
+                            ref={fileInputRef}
+                            type="file"
+                            multiple
+                            onChange={handleUpload}
+                            style={{ display: "none" }}
+                            disabled={uploading}
+                        />
+
+                        <Button
+                            loading={uploading}
+                            onClick={() =>
+                                fileInputRef.current?.click()
+                            }
+                        >
+                            + Upload
+                        </Button>
                     </div>
                 </div>
             </header>
 
-            {uploadError && <div className="dw-docs__error">{uploadError}</div>}
+            {uploadError && (
+                <div className="dw-docs__error">
+                    {uploadError}
+                </div>
+            )}
 
             {/* Controls row */}
             <div className="dw-docs__controls">
@@ -159,17 +398,29 @@ export default function Documents() {
                     value={search}
                     onChange={(e) => setSearch(e.target.value)}
                 />
+
                 <div className="dw-docs__filters">
                     {FILTERS.map((f) => (
                         <button
                             key={f.key}
-                            className={`dw-docs__filter ${filter === f.key ? "dw-docs__filter--active" : ""}`}
+                            className={`dw-docs__filter ${
+                                filter === f.key
+                                    ? "dw-docs__filter--active"
+                                    : ""
+                            }`}
                             onClick={() => setFilter(f.key)}
                         >
                             {f.label}
+
                             {f.key !== "all" && (
                                 <span className="dw-docs__filter-count">
-                                    {documents.filter((d) => d.workflow_status === f.key).length}
+                                    {
+                                        documents.filter(
+                                            (d) =>
+                                                d.workflow_status ===
+                                                f.key
+                                        ).length
+                                    }
                                 </span>
                             )}
                         </button>
@@ -182,14 +433,29 @@ export default function Documents() {
                 <div className="dw-docs__pills">
                     {filter !== "all" && (
                         <span className="dw-docs__pill">
-                            {FILTERS.find((f) => f.key === filter)?.label}
-                            <button onClick={() => setFilter("all")}>×</button>
+                            {
+                                FILTERS.find(
+                                    (f) => f.key === filter
+                                )?.label
+                            }
+
+                            <button
+                                onClick={() => setFilter("all")}
+                            >
+                                ×
+                            </button>
                         </span>
                     )}
+
                     {search && (
                         <span className="dw-docs__pill">
                             "{search}"
-                            <button onClick={() => setSearch("")}>×</button>
+
+                            <button
+                                onClick={() => setSearch("")}
+                            >
+                                ×
+                            </button>
                         </span>
                     )}
                 </div>
@@ -201,10 +467,13 @@ export default function Documents() {
                 <DataTable
                     columns={columns}
                     data={filtered}
-                    onRowClick={(row) => row.workflow_id && navigate(`/workflows/${row.workflow_id}`)}
+                    onRowClick={(row) =>
+                        row.workflow_id &&
+                        navigate(`/workflows/${row.workflow_id}`)
+                    }
                     emptyMessage="No documents found."
                 />
             )}
         </div>
     );
-}
+}

frontend/src/pages/Knowledge.jsx

@@ -2,10 +2,12 @@ import { useCallback, useEffect, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { useWorkspace } from "../hooks/useWorkspace";
 import { listKnowledge } from "../api/knowledge";
+import { restoreProposal } from "../api/proposals";
 import {
     Card,
     CardBody,
     Badge,
+    Button,
     LoadingState,
     EmptyState,
     Glossary,
@@ -32,7 +34,7 @@ const STATUS_TONE = {
     PENDING: "default",
     CONFLICTED: "warning",
     SUPERSEDED: "info",
-    ARCHIVED: "info",
+    ARCHIVED: "warning",
     REJECTED: "danger",
 };
 
@@ -144,6 +146,22 @@ export default function Knowledge() {
         }
     }, [workspace, typeFilter, statusFilter]);
 
+    const handleRestore = useCallback(async (proposalId, itemId) => {
+        // Optimistically remove from list immediately
+        setItems((prev) => prev.filter((i) => i.id !== itemId));
+
+        try {
+            await restoreProposal(proposalId);
+        } catch {
+            // On failure, reload to restore correct state
+            const result = await listKnowledge(workspace.id, {
+                type: typeFilter || undefined,
+                status: statusFilter || undefined,
+            });
+            if (Array.isArray(result)) setItems(result);
+        }
+    }, [workspace, typeFilter, statusFilter]);
+
     useEffect(() => {
         load();
     }, [load]);
@@ -212,7 +230,15 @@ export default function Knowledge() {
                 />
             ) : (
                 <div className="dw-knowledge__list">
-                    {items.map((item) => (
+                    {items.map((item) => {
+                        // Derive display status from proposal state
+                        const displayStatus =
+                            item.proposal?.status === "ARCHIVED"
+                                ? "ARCHIVED"
+                                : item.status;
+                        const isArchived = item.proposal?.status === "ARCHIVED";
+
+                        return (
                         <Card
                             key={item.id}
                             interactive
@@ -234,12 +260,12 @@ export default function Knowledge() {
 
                                     <Badge
                                         tone={
-                                            STATUS_TONE[item.status] ||
+                                            STATUS_TONE[displayStatus] ||
                                             "default"
                                         }
                                     >
-                                        {KNOWLEDGE_STATUS_LABELS[item.status] ||
-                                            item.status}
+                                        {KNOWLEDGE_STATUS_LABELS[displayStatus] ||
+                                            displayStatus}
                                     </Badge>
 
                                     <ConfidenceBar
@@ -278,9 +304,25 @@ export default function Knowledge() {
                                         </span>
                                     )}
                                 </div>
+
+                                {isArchived && item.proposal?.id && (
+                                    <div className="dw-knowledge__item-actions">
+                                        <Button
+                                            size="sm"
+                                            variant="warning"
+                                            onClick={(e) => {
+                                                e.stopPropagation();
+                                                handleRestore(item.proposal.id, item.id);
+                                            }}
+                                        >
+                                            Restore to review
+                                        </Button>
+                                    </div>
+                                )}
                             </CardBody>
                         </Card>
-                    ))}
+                        );
+                    })}
                 </div>
             )}
         </div>

frontend/src/pages/KnowledgeDetail.jsx

@@ -19,7 +19,7 @@ const STATUS_TONE = {
     PENDING: "default",
     CONFLICTED: "warning",
     SUPERSEDED: "info",
-    ARCHIVED: "info",
+    ARCHIVED: "warning",
     REJECTED: "danger",
 };
 

frontend/src/utils/labels.js

@@ -94,6 +94,7 @@ export const GLOSSARY = {
         { term: "Review Requested", description: "The system paused and asked for human input." },
         { term: "Proposal Approved", description: "A human accepted a proposed knowledge change." },
         { term: "Proposal Rejected", description: "A human declined a proposed change." },
+        { term: "Proposal Archived", description: "A proposal was deferred for later review." },
         { term: "Commit Created", description: "An approved change was written to the knowledge register." },
     ],
     settings: [