feat(workflows-mcp): add validate/invalidate_knowledge tools with enum .value bugfix

Adds validate_knowledge and invalidate_knowledge MCP tools and ops, enabling
the full USER_VALIDATED authority lifecycle: store → validate → invalidate → forget.

- validate_knowledge: promotes existing propositions to USER_VALIDATED (archive-immune)
- invalidate_knowledge: revokes USER_VALIDATED, demoting back to AGENT; forget then works normally
- Fix: all Authority/LifecycleState enum refs in f-string SQL now use .value to prevent
  Python 3.11+ str-enum repr ("Authority.AGENT") being written to the DB instead of "AGENT"
- Tests: TestValidateOperation, TestInvalidateOperation, TestUserValidatedImmunity (137 passing)
- Docs: README updated with block ops 6-7 and full MCP tool reference

Author: ibacalu

README.md

@@ -670,7 +670,30 @@ Returns clean content only (no metadata) in `context_text`, ready for LLM prompt
       source_name: "deprecated-docs"
     created_before: "2025-01-01"
 ```
-Returns `archived_count` and `skipped_count` in the output.
+Returns `archived_count` and `skipped_count`. `USER_VALIDATED` propositions are immune and counted in `skipped_count`.
+
+**6. Validate — Grant a proposition permanent archive immunity:**
+```yaml
+- id: pin_finding
+  type: Knowledge
+  inputs:
+    op: validate
+    proposition_ids:
+      - "uuid-of-reviewed-fact"
+```
+Promotes `authority` to `USER_VALIDATED` in-place, preserving the original UUID, creator, and category associations. Returns `validated_count`.
+
+**7. Invalidate — Revoke USER_VALIDATED immunity:**
+```yaml
+- id: revoke_outdated
+  type: Knowledge
+  inputs:
+    op: invalidate
+    proposition_ids:
+      - "uuid-of-outdated-fact"
+    reason: "superseded by new measurement from 2026-03-21"
+```
+Demotes authority back to `AGENT` and logs an `INVALIDATED` audit entry with the reason. After this, `forget` can archive the proposition normally. Returns `invalidated_count`.
 
 **6. Chaining Operations — Store, search, and cleanup in one workflow:**
 ```yaml
@@ -839,6 +862,8 @@ When you configure workflows-mcp, your AI assistant gets these tools:
 
 - **store_knowledge** - Persist a new fact with auto-computed embedding
   - `content`, `source`, `confidence` (default 0.8), `categories`
+  - `authority`: `AGENT` (default), `EXTRACTED`, `COMMUNITY_SUMMARY`, or `USER_VALIDATED`
+  - `lifecycle_state`: `ACTIVE` (default) or `QUARANTINED`
 
 - **recall_knowledge** - Filter-based retrieval (no semantic search)
   - `source`, `categories`, `lifecycle_state`, `min_confidence`, `limit`, `order`
@@ -848,6 +873,18 @@ When you configure workflows-mcp, your AI assistant gets these tools:
   - By filter: `source` (exact or prefix `*`), `created_before`, `created_after`
   - At least one of `proposition_ids` or `source` must be provided
   - `reason` (optional, for audit trail)
+  - `USER_VALIDATED` propositions are immune and reported in `skipped_count`
+
+- **validate_knowledge** - Grant a proposition permanent archive immunity
+  - `proposition_ids` (required): UUIDs to promote to `USER_VALIDATED` authority
+  - In-place update — preserves UUID, creator, timestamp, and category associations
+  - Returns `validated_count`
+
+- **invalidate_knowledge** - Revoke USER_VALIDATED immunity
+  - `proposition_ids` (required): UUIDs to demote back to `AGENT` authority
+  - `reason` (optional, for audit trail)
+  - After invalidation, `forget_knowledge` can archive the proposition normally
+  - Returns `invalidated_count`
 
 - **knowledge_context** - Token-budgeted context assembly for LLM prompts
   - `query`, `source`, `categories`, `max_tokens`, `diversity`

src/workflows_mcp/engine/executors_knowledge.py

@@ -117,7 +117,7 @@ class KnowledgeInput(BlockInput):
         ```
     """
 
-    op: Literal["search", "store", "recall", "forget", "context", "validate"] = Field(
+    op: Literal["search", "store", "recall", "forget", "context", "validate", "invalidate"] = Field(
         description="Operation to perform",
     )
 
@@ -278,6 +278,8 @@ def validate_op_fields(self) -> KnowledgeInput:
             )
         if self.op == "validate" and not self.proposition_ids:
             raise ValueError("'proposition_ids' is required for op='validate'")
+        if self.op == "invalidate" and not self.proposition_ids:
+            raise ValueError("'proposition_ids' is required for op='invalidate'")
         if self.path is not None and not self.source:
             raise ValueError("'source' is required when 'path' is provided")
         return self
@@ -319,8 +321,9 @@ class KnowledgeOutput(BlockOutput):
     archived_count: int = Field(default=0, description="Number archived")
     skipped_count: int = Field(default=0, description="Number skipped (immune)")
 
-    # Validate output
+    # Validate / Invalidate output
     validated_count: int = Field(default=0, description="Number promoted to USER_VALIDATED")
+    invalidated_count: int = Field(default=0, description="Number demoted from USER_VALIDATED")
 
     # Context output
     context_text: str = Field(default="", description="Clean content assembled text")
@@ -401,6 +404,7 @@ async def execute(  # type: ignore[override]
                 "recall": self._op_recall,
                 "forget": self._op_forget,
                 "validate": self._op_validate,
+                "invalidate": self._op_invalidate,
                 "context": self._op_context,
             }
             handler = op_handlers[inputs.op]
@@ -1005,7 +1009,7 @@ async def _op_forget(
                     archived_by = ${len(ids) + 1}::uuid,
                     archive_reason = ${len(ids) + 2}
                 WHERE id IN ({placeholders})
-                  AND authority != '{Authority.USER_VALIDATED}'
+                  AND authority != '{Authority.USER_VALIDATED.value}'
                 RETURNING id
             """
             result = await backend.query(
@@ -1055,7 +1059,7 @@ async def _op_forget(
                 archived_by = ${param_offset + 1}::uuid,
                 archive_reason = ${param_offset + 2}
             WHERE {where_sql}
-              AND authority != '{Authority.USER_VALIDATED}'
+              AND authority != '{Authority.USER_VALIDATED.value}'
             RETURNING id
         """
         params.extend([str(archived_by) if archived_by else None, archive_reason])
@@ -1114,9 +1118,9 @@ async def _op_validate(
         placeholders = ", ".join(f"${i + 1}::uuid" for i in range(len(ids)))
         update_sql = f"""
             UPDATE knowledge_propositions
-            SET authority = '{Authority.USER_VALIDATED}'
+            SET authority = '{Authority.USER_VALIDATED.value}'
             WHERE id IN ({placeholders})
-              AND lifecycle_state != '{LifecycleState.ARCHIVED}'
+              AND lifecycle_state != '{LifecycleState.ARCHIVED.value}'
             RETURNING id
         """
         result = await backend.query(update_sql, tuple(ids))
@@ -1137,6 +1141,59 @@ async def _op_validate(
 
         return KnowledgeOutput(success=True, validated_count=validated)
 
+    async def _op_invalidate(
+        self,
+        inputs: KnowledgeInput,
+        context: Execution,
+        backend: Any,
+    ) -> KnowledgeOutput:
+        """Revoke USER_VALIDATED authority, demoting proposition to AGENT trust level.
+
+        This is the deliberate counterpart to _op_validate. After invalidation the
+        proposition is no longer archive-immune and can be archived via _op_forget.
+        Demotes to AGENT (not deleted) so the content and audit trail are preserved.
+
+        SECURITY: Records invalidated_by and logs INVALIDATED to audit table.
+        """
+        ids: list[str] = []
+        if isinstance(inputs.proposition_ids, str):
+            ids = [s.strip() for s in inputs.proposition_ids.split(",") if s.strip()]
+        elif isinstance(inputs.proposition_ids, list):
+            ids = inputs.proposition_ids
+
+        if not ids:
+            return KnowledgeOutput(success=True, invalidated_count=0)
+
+        invalidated_by = _get_audit_user_id(context)
+        auth_method = _get_auth_method(context)
+        user_string = _get_user_string_id(context)
+
+        placeholders = ", ".join(f"${i + 1}::uuid" for i in range(len(ids)))
+        update_sql = f"""
+            UPDATE knowledge_propositions
+            SET authority = '{Authority.AGENT.value}'
+            WHERE id IN ({placeholders})
+              AND authority = '{Authority.USER_VALIDATED.value}'
+            RETURNING id
+        """
+        result = await backend.query(update_sql, tuple(ids))
+        invalidated = len(result.rows) if result and result.rows else 0
+
+        if invalidated > 0:
+            invalidated_ids = [row["id"] for row in result.rows]
+            for prop_id in invalidated_ids:
+                await self._log_audit_entry(
+                    backend=backend,
+                    proposition_id=prop_id,
+                    action="INVALIDATED",
+                    performed_by=invalidated_by,
+                    auth_method=auth_method,
+                    user_string=user_string,
+                    metadata={"reason": inputs.reason, "method": "explicit_ids"},
+                )
+
+        return KnowledgeOutput(success=True, invalidated_count=invalidated)
+
     async def _op_context(
         self,
         inputs: KnowledgeInput,

src/workflows_mcp/tools_knowledge.py

@@ -621,6 +621,66 @@ async def validate_knowledge(
 
         return _json_response({"validated_count": result.validated_count})
 
+    @mcp_server.tool(
+        annotations=ToolAnnotations(
+            title="Invalidate Knowledge",
+            readOnlyHint=False,
+            destructiveHint=False,
+            idempotentHint=True,
+            openWorldHint=True,
+        )
+    )
+    async def invalidate_knowledge(
+        proposition_ids: Annotated[
+            list[str],
+            Field(description="UUIDs of USER_VALIDATED propositions to revoke"),
+        ],
+        reason: Annotated[
+            str | None,
+            Field(
+                description="Reason for revoking validation (for audit trail)",
+                default=None,
+            ),
+        ],
+        *,
+        ctx: AppContextType,
+    ) -> CallToolResult:
+        """
+        Revoke USER_VALIDATED authority, demoting propositions back to AGENT trust level.
+
+        WHEN TO USE: When a previously human-validated fact is no longer true or has
+        been superseded. After invalidation the proposition loses archive immunity and
+        can be removed with forget_knowledge. The content and full audit trail are
+        preserved — the audit log records that this was once USER_VALIDATED and when
+        and why that was revoked.
+
+        Only propositions currently holding USER_VALIDATED authority are affected.
+        Propositions with any other authority are silently skipped (idempotent).
+
+        PARAMETERS:
+        - proposition_ids: List of proposition UUIDs to invalidate
+        - reason: Optional reason for revocation (stored in audit trail)
+
+        RETURNS: {invalidated_count: N}
+
+        SEE ALSO: validate_knowledge (grant immunity), forget_knowledge (archive after invalidation)
+        """
+        from .engine.executors_knowledge import KnowledgeExecutor, KnowledgeInput
+
+        execution = _create_knowledge_execution(ctx)
+        executor = KnowledgeExecutor()
+        inputs = KnowledgeInput(
+            op="invalidate",
+            proposition_ids=proposition_ids,
+            reason=reason,
+        )
+        result = await executor.execute(inputs, context=execution)
+
+        if not result.success:
+            return _json_response({"status": "failure", "error": result.error})
+
+        return _json_response({"invalidated_count": result.invalidated_count})
+
     @mcp_server.tool(
         annotations=ToolAnnotations(
             title="Knowledge Context",