Add warranted agent architecture review docs

Author: FlowmemoryAI

README.md

@@ -260,8 +260,11 @@ Start here for review:
 
 - `docs/DEVELOPER_HANDOFF.md`
 - `docs/AGENT_FRAMEWORK_ARCHITECTURE.md`
+- `docs/ARCHITECTURE_DIAGRAMS.md`
+- `docs/THREAT_MODEL.md`
 - `docs/AGENT_RUNTIME.md`
 - `docs/AGENT_REGISTRY.md`
+- `docs/EVIDENCE_SCHEMA.md`
 - `docs/LAUNCH_CHECKLIST.md`
 - `specs/WarrantedAgentFramework.v0.md`
 

docs/ARCHITECTURE_DIAGRAMS.md

@@ -0,0 +1,81 @@
+# Architecture Diagrams
+
+## Framework Stack
+
+```mermaid
+flowchart LR
+  A[AgentManifest] --> B[WorkRequest]
+  B --> C[PolicyCard]
+  C --> D[AgentProposal]
+  D --> E[AgentRegistry]
+  E --> F[AgentRuntime]
+  F --> G[EvidenceSchema]
+  G --> H[FlowBond]
+  H --> I[BondLedger]
+  H --> J[FlowPulse]
+  J --> K[PulsePass]
+  K --> L[PrivateCompute]
+  L --> M[ScopedProof]
+  H --> N[FlowCompiler]
+```
+
+Core idea:
+
+```text
+The agent promise becomes a warranted machine history.
+```
+
+## Runtime Sequence
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant R as AgentRegistry
+  participant A as AgentAdapter
+  participant T as AgentRuntime
+  participant B as FlowBond
+  participant P as PulsePass
+
+  U->>R: WorkRequest
+  R-->>U: eligible warranted agents
+  U->>A: quote(request)
+  A-->>U: PolicyCard + AgentProposal
+  U->>T: run(policy)
+  T->>T: lock local bond
+  T->>A: execute(policy)
+  A-->>T: evidence envelopes
+  T->>B: settle(policy, outcome)
+  B-->>T: FlowPulse settlement
+  T->>P: store receipt
+  P-->>U: scoped proof
+```
+
+## Success Path
+
+```mermaid
+flowchart TD
+  A[Required evidence exists] --> B[Evidence fields pass schema]
+  B --> C[Obligation links match]
+  C --> D[Acceptance is true]
+  D --> E[FlowBond passes]
+  E --> F[Bond releases to agent]
+  F --> G[PulsePass stores success receipt]
+```
+
+## Failure Path
+
+```mermaid
+flowchart TD
+  A[Payment exists] --> B{Delivery evidence present?}
+  B -- No --> C[FlowBond fails]
+  B -- Yes --> D{Acceptance present?}
+  D -- No --> C
+  D -- Yes --> E{Obligation links match?}
+  E -- No --> C
+  C --> F[Bond pays user]
+  F --> G[PulsePass stores failed warranty receipt]
+```
+
+## Boundary
+
+These diagrams describe the local deterministic framework. They do not claim production custody, wallet enforcement, production verifier infrastructure, production settlement, zero-knowledge privacy, or work-quality proof.

docs/THREAT_MODEL.md

@@ -0,0 +1,101 @@
+# Threat Model
+
+FlowMemory Warranted Agents is strongest when the failure modes are explicit.
+
+The v0 framework is local and deterministic. It does not claim custody, wallet enforcement, production settlement, production verifier infrastructure, full privacy, zero-knowledge privacy, semantic truth, or work-quality proof.
+
+Within that boundary, the framework targets a real problem:
+
+```text
+An agent action can look valid while the machine history behind it is incomplete, mismatched, stale, or impossible.
+```
+
+## Threat: Generic Claims Without Evidence
+
+Risk:
+
+```text
+The agent says it completed the job, but no required evidence exists.
+```
+
+FlowMemory response:
+
+- PolicyCard defines required evidence.
+- EvidenceSchema checks local envelope fields.
+- FlowBond fails missing evidence.
+- PulsePass can carry the failed warranty receipt.
+
+## Threat: Payment Without Delivery
+
+Risk:
+
+```text
+Payment is observed, but the delivery envelope is missing.
+```
+
+FlowMemory response:
+
+- FlowBond emits `payment_without_delivery`.
+- The local bond outcome becomes `PAY_BOND_TO_USER`.
+- The failed warranty becomes a FlowPulse-style memory artifact.
+
+## Threat: Wrong Obligation Link
+
+Risk:
+
+```text
+Evidence exists, but it belongs to a different obligation.
+```
+
+FlowMemory response:
+
+- FlowBond checks obligation IDs.
+- Mismatched envelopes produce wrong-obligation violations.
+- FlowCompiler rejects analogous impossible histories.
+
+## Threat: Arbitrary Evidence Labels
+
+Risk:
+
+```text
+The agent submits a label named WorkDeliveryEnvelope without the required delivery fields.
+```
+
+FlowMemory response:
+
+- EvidenceSchema defines required fields.
+- Malformed local envelopes fail settlement.
+
+## Threat: Private History Exposure
+
+Risk:
+
+```text
+The user needs to prove a warranty state without revealing the full receipt history.
+```
+
+FlowMemory response:
+
+- PulsePass stores receipt history.
+- PrivateCompute reveals scoped predicates.
+- Raw receipts, raw user ID, exact action history, and private obligation IDs remain hidden in the local proof surface.
+
+## Threat: Overclaiming The System
+
+Risk:
+
+```text
+Public copy must not claim live custody, production settlement, semantic truth, or proof of work quality.
+```
+
+FlowMemory response:
+
+- ClaimGate scans README, docs, and specs.
+- CI runs the claim gate.
+- Risky phrases must appear only as guarded non-claims or boundary statements.
+
+## Strongest v0 Claim
+
+```text
+FlowMemory can make an agent promise inspectable as a deterministic receipt-bound machine history.
+```