From 575025c814fd5b7d9a93f8649787d76b17eb0803 Mon Sep 17 00:00:00 2001
From: Jonathan <64296013+Joncallim@users.noreply.github.com>
Date: Thu, 3 Sep 2026 01:06:20 +0800
Subject: [PATCH] docs: bound mutual Compose advisory

---
 docs/architecture/ARCHITECTURE.md | 19 +++++++++++++++++++
 docs/security/THREAT_MODEL.md     |  8 ++++++++
 docs/testing/TESTING_PLAN.md      |  8 ++++++++
 3 files changed, 35 insertions(+)

diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md
index f5bd909d..ee34ff9e 100644
--- a/docs/architecture/ARCHITECTURE.md
+++ b/docs/architecture/ARCHITECTURE.md
@@ -169,6 +169,25 @@ This rule reads no new host state and makes no new collection call. It is a
 cached, read-only projection of the already-published runtime map; mock mode
 has no runtime evidence and therefore cannot produce it.
 
+The mutual Compose-declaration advisory is even narrower. It emits once for an
+unordered pair only when each direction has exactly one fresh, matching
+Docker-recorded Compose declaration fact between the same two uniquely
+resolved Docker containers. Both version-1 observations must be the closed
+`docker_compose_depends_on` shape, must identify their respective source
+container, and must share the same collection instant and opaque Docker
+observation revision. The static recommendation is to review the declarations
+and remove an unintended mutual dependency. Its two evidence references are
+ordered to match the displayed direction and then its reciprocal direction;
+their identifiers and other provider material remain opaque.
+
+This is an advisory-only, deterministic, cached read-only projection. Missing,
+stale, timed-out, duplicate, malformed, non-Docker, self-referential, collided,
+or mismatched-observation facts suppress it, as does mock mode. It is not
+proof that a Compose file was accepted, that either dependency is required,
+that Compose start order ran, or that either container is ready or healthy. It
+does not establish traffic, deployment failure, causality, Internet
+reachability, compromise, or a security incident.
+
 Each rule carries only its exact triggering evidence references. The API
 validates the fixed vocabulary, static display text, and rule-specific evidence
 shape before publication, and the browser displays findings only when their
diff --git a/docs/security/THREAT_MODEL.md b/docs/security/THREAT_MODEL.md
index c84b5fbc..96726c0a 100644
--- a/docs/security/THREAT_MODEL.md
+++ b/docs/security/THREAT_MODEL.md
@@ -63,6 +63,14 @@ changes them:
   duplicate, collided, or non-Docker inputs are suppressed. It exposes no raw Compose content or
   identifiers beyond the existing opaque runtime references, and it does not claim dependency
   requiredness, readiness, health, traffic, start-order execution, root cause, or drift.
+- The mutual Compose-declaration advisory is also a cached read-only projection. It requires one
+  fresh, reciprocal Docker-recorded Compose declaration in each direction between the same two
+  unique Docker containers, from the same collection instant and opaque Docker observation
+  revision. Any missing, stale, duplicate, malformed, collided, non-Docker, self-referential, or
+  mismatched observation suppresses it, including all mock-mode data. It does not expose raw
+  Compose labels or configuration paths. It is not proof that a Compose file was accepted, that a
+  dependency is required, that start order ran, or that services are ready or healthy; it makes no
+  traffic, deployment-failure, causality, Internet-reachability, compromise, or incident claim.
 
 ## Main Risks And Protections
 
diff --git a/docs/testing/TESTING_PLAN.md b/docs/testing/TESTING_PLAN.md
index 8e6b268a..722c061f 100644
--- a/docs/testing/TESTING_PLAN.md
+++ b/docs/testing/TESTING_PLAN.md
@@ -24,6 +24,14 @@ containers, or services.
   collided, ambiguous, non-Docker, and non-matching-status inputs. These are projection tests:
   they add no collection and never assert requiredness, readiness, health, traffic, start-order,
   root-cause, or drift conclusions.
+- Mutual Compose-advisory tests require exactly one fresh reciprocal Docker-recorded declaration
+  in each direction between the same unique Docker containers, with matching collection instant
+  and opaque observation revision. They preserve the ordered two-fact evidence budget and stable
+  single-pair result while rejecting mock, missing, stale/timed-out, duplicate, malformed,
+  self-referential, collided, non-Docker, and mismatched-observation inputs. These tests verify a
+  static advisory projection only; they do not treat it as evidence that Compose accepted a file,
+  applied a start order, required either dependency, or established readiness, health, traffic,
+  deployment failure, causality, Internet reachability, or compromise.
 - Rust-owned JSON Schema and generated TypeScript declarations, Node-owned
   envelope/request/SSE schemas, and readable contract fixtures. The contract
   check fails on stale generated output, invalid fixtures, incomplete