Merge branch 'main' into codex/unknown-scope-contract

Co-authored-by: morluto <[email protected]>

docs/mcp-contracts.md

@@ -419,10 +419,18 @@ Automatically retained workflow questions include their immutable result
 Evidence ID. Distinct results retain independent questions and source links;
 repeating the same result does not create another unknown. Workflow Evidence
 keeps the original residual question text. Explicit `record_unknown` requests
-keep caller-selected identity and reject duplicate creation.
+keep caller-selected identity and reject duplicate creation. Explicit creation
+uses the active binary analysis target digest as `scope_digest`, or null when
+there is no active target. Supporting Evidence does not select the scope. Scope
+contributes to the stable unknown ID, so the same question can have different
+IDs under different scopes. Check the active target before recording a
+target-scoped unknown; creating one in a target-free session does not infer a
+target from its supporting Evidence.
 Duplicate creation is a nonretryable `invalid_request`; use the existing head
 or update it with its current `expected_revision`. A stale update remains a
-retryable `revision_conflict`.
+retryable `revision_conflict`. An `update_unknown` revision keeps the unknown’s
+original `scope_digest`. Its mutation Evidence subject is the active binary
+analysis target, or null without one, so it can differ from the unknown’s scope.
 
 If automatic question publication fails after a workflow completes,
 `details.workflow_unknown_publication` identifies the Evidence and states

src/contracts/sessionToolContracts.ts

@@ -158,12 +158,12 @@ export const SESSION_TOOL_CONTRACTS = [
   ),
   session(
     "record_unknown",
-    "Create one deterministic residual unknown and immutable mutation evidence. Validates all evidence and relationship references, and rejects duplicate stable identity.",
+    "Create one deterministic residual unknown and immutable mutation evidence. Its scope is the active binary analysis target digest, or null without an active target; supporting Evidence does not select the scope. Scope contributes to stable identity. Validates all evidence and relationship references, and rejects duplicate stable identity.",
     recordUnknownInputSchema,
   ),
   session(
     "update_unknown",
-    "Append one immutable full-state revision and mutation evidence. Requires exact expected_revision; stale concurrent writers fail instead of overwriting newer analysis.",
+    "Append one immutable full-state revision and mutation evidence. The unknown retains its original scope; the mutation Evidence subject is the active binary analysis target, or null without one, and can differ from that scope. Requires exact expected_revision; stale concurrent writers fail instead of overwriting newer analysis.",
     updateUnknownInputSchema,
   ),
   session(