Clarify AgentPass product positioning hierarchy

README.md

@@ -1,23 +1,24 @@
 # AgentPass
 
-**Open interoperability and conformance for action-bound AI agent authorization.**
+**Action authorization and execution assurance for AI agents.**
 
-AgentPass is an open reference implementation, action-control boundary, and
-conformance project that sits outside the agent loop. It checks tool calls
-before execution and preserves durable records of what was proposed,
-authorized, executed, observed, and assessed.
+AgentPass is an action-control and evidence layer that sits outside the agent
+loop. It decides whether a specific tool call may execute and preserves durable
+records of what was proposed, authorized, executed, observed, and assessed.
 
-Its standards role is deliberately narrow: compose existing identity,
-delegation, workload, policy, and signing standards into independently
-verifiable evidence for a specific agent action. AgentPass does not define a
-general agent identity or replace IAM, OAuth, MCP authorization, AuthZEN,
-SPIFFE, WIMSE, OPA, Cedar, or provider business authorization. See
-[Interoperability Positioning](docs/interoperability-positioning.md).
+> AgentPass controls consequential AI agent actions and produces independently
+> verifiable evidence of what was authorized and executed.
 
 ```text
 Agent proposes tool call -> AgentPass checks policy + state -> allow / deny / challenge
 ```
 
+Identity, workload, and policy systems provide inputs to that decision.
+AgentPass composes them at the action boundary and adds stateful enforcement,
+provider-verifiable authorization evidence, and execution assurance. Its open
+conformance work demonstrates interoperability; it is not the product category.
+See [Project Positioning](docs/positioning.md).
+
 The runtime decision remains the core enforcement point. The current
 implementation also includes versioned intent contracts, execution evidence,
 verified outcome observations, immutable evidence snapshots and final
@@ -390,19 +391,20 @@ AgentPass currently includes:
 
 ## Roadmap Focus
 
-Near-term work has four public tracks:
-
-1. Action-bound authorization interoperability: executable MCP conformance
-   cases, provider-verifier behavior, negative fixtures, implementation
-   profiles, and demonstrations with independent implementations.
-2. Production-grade intent observability and assurance: canonical evidence
-   contracts, action-boundary lifecycle hardening, OpenTelemetry causal
-   tracing, correlation, measurement profiles, independent control assessment,
-   complete population accounting, immutable assessment revisions, privacy,
-   migration, and conformance.
-3. Provider trust enforcement with production receipts and contract drift
-   detection.
-4. Framework and workflow wrappers selected from adopter demand.
+Near-term work follows three product layers:
+
+1. **Runtime authorization and control:** policy enforcement, approvals,
+   budgets, data-flow controls, idempotency, replay protection, and integrations
+   at agent, workflow, gateway, and provider boundaries.
+2. **Portable provider trust and interoperability:** signed action-bound
+   evidence, independent provider verification, contract drift detection,
+   conformance cases, profiles, and multi-implementation demonstrations.
+3. **Execution and outcome assurance:** linked execution receipts, immutable
+   evidence, verified observations, causal traces, intent evaluation, and
+   comparable assurance metrics.
+
+Framework wrappers and conformance suites are delivery mechanisms within these
+layers, not separate product categories.
 
 The [Action Gate Roadmap](docs/action-gate-roadmap.md) tracks adopter-facing
 product demonstrations. The public

docs/action-gate-roadmap.md

@@ -4,9 +4,12 @@ This roadmap documents the near-term product direction for AgentPass.
 
 The positioning target is:
 
-> AgentPass is the runtime action gate for AI agents before they call tools,
-> send messages, move money, update records, deploy code, or touch sensitive
-> data.
+> AgentPass controls consequential AI agent actions and produces independently
+> verifiable evidence of what was authorized and executed.
+
+The action gate is the core product boundary inside the broader category of
+action authorization and execution assurance. The canonical message hierarchy
+is in [Project Positioning](positioning.md).
 
 The developer problem is not only agent identity. Builders already have agents,
 tools, API keys, MCP servers, workflow engines, and model calls. What they lack
@@ -67,7 +70,25 @@ agent loop. The stronger product story is:
 
 Recommended public line:
 
-> AgentPass is a runtime guard for AI agent tool calls.
+> AgentPass is an action authorization guard for AI agent tool calls.
+
+## Three-Layer Product Roadmap
+
+The roadmap uses the same three product layers as the README and canonical
+positioning:
+
+1. **Runtime authorization and control:** stop unsafe, unauthorized, duplicate,
+   or unapproved actions at the execution boundary.
+2. **Portable provider trust and interoperability:** let downstream providers
+   independently verify action-bound authorization evidence across trust
+   boundaries.
+3. **Execution and outcome assurance:** link authorization to execution,
+   independently observed outcomes, and durable assessment evidence.
+
+Framework wrappers distribute the runtime boundary. Conformance suites test
+portable provider trust. Observability supplies operational context for
+assurance. They advance these layers rather than forming separate product
+categories.
 
 ## Roadmap
 

docs/interoperability-positioning.md

@@ -1,7 +1,9 @@
 # AgentPass Interoperability Positioning
 
-AgentPass is an open reference implementation and conformance project for
-action-bound authorization of AI agent operations.
+Interoperability and conformance are the open ecosystem strategy for
+AgentPass's broader product category: action authorization and execution
+assurance for AI agents. The canonical product hierarchy is defined in
+[Project Positioning](positioning.md).
 
 Its focus is the provider trust boundary:
 

docs/positioning.md

@@ -0,0 +1,125 @@
+# AgentPass Project Positioning
+
+## Category
+
+**Action authorization and execution assurance for AI agents.**
+
+AgentPass is an action-control and evidence layer outside the agent loop. It
+decides whether a specific agent action may execute and preserves durable,
+independently verifiable evidence of what was authorized and executed.
+
+The canonical one-sentence promise is:
+
+> AgentPass controls consequential AI agent actions and produces independently
+> verifiable evidence of what was authorized and executed.
+
+## Product Hierarchy
+
+### 1. Runtime Authorization And Control
+
+This is the core product. AgentPass evaluates the exact tool, arguments,
+resource, principal, agent, job state, approval, budget, data-flow boundary,
+and prior execution state immediately before dispatch. It can allow, deny, or
+challenge the action and can prevent unsafe retries and duplicate effects.
+
+### 2. Portable Provider Trust And Interoperability
+
+This is the cross-boundary differentiator. Signed, action-bound authorization
+evidence lets an MCP server, SaaS API, or other provider independently verify
+the decision before applying its own business authorization. Public mappings,
+fixtures, reference verifiers, and conformance suites make that behavior
+testable across implementations.
+
+### 3. Execution And Outcome Assurance
+
+This completes the lifecycle. Provider execution receipts, immutable evidence,
+verified observations, causal traces, and intent assessments establish what
+happened after authorization and whether the intended outcome was achieved
+within constraints.
+
+The layers compose as:
+
+```text
+Identity and workload context
+  -> runtime authorization and control
+  -> portable provider verification
+  -> execution and outcome assurance
+```
+
+## Capability Story
+
+Lead with operational control:
+
+- stateful policy at the tool-execution boundary;
+- exact-action approvals and step-up authorization;
+- idempotency, replay protection, budgets, and circuit breakers;
+- PII and sensitive-data movement controls; and
+- explainable decisions and durable audit evidence.
+
+Then explain the differentiator:
+
+- authorization evidence bound to the exact action;
+- independent verification across organizational or provider boundaries;
+- linked execution closure and outcome evidence; and
+- open interoperability fixtures and conformance tests.
+
+## Audience Entry Points
+
+| Audience | Lead with |
+|---|---|
+| Enterprise and security teams | Control consequential agent actions with policy, approvals, state, and audit |
+| Agent and application developers | Add a small authorization boundary around existing tool calls |
+| MCP gateway and platform builders | Enforce consistent action policy before forwarding `tools/call` |
+| SaaS, API, and MCP providers | Independently verify action-specific authorization before mutation |
+| Risk, compliance, and assurance teams | Link authorization, execution, observations, and assessment evidence |
+| Standards and open-source communities | Reusable mappings, test vectors, profiles, and implementation feedback |
+
+## Standards And Open-Source Strategy
+
+Identity establishes the actors. Policy decides. AgentPass enforces and proves
+the authority for a specific action, then links it to execution evidence.
+
+AgentPass reuses OIDC, OAuth, AuthZEN, SPIFFE, WIMSE, MCP authorization, JOSE,
+HTTP Message Signatures, Shared Signals, and provenance work where applicable.
+Its standards role is to contribute mappings, negative fixtures, reference
+implementations, conformance tests, and narrowly scoped profiles before
+proposing new vocabulary.
+
+Conformance is how AgentPass proves portability; it is not the product
+category. Passing an AgentPass suite means agreement with experimental
+AgentPass reference cases, not certification by an external standards body.
+
+## What AgentPass Is Not
+
+AgentPass is not:
+
+- an identity provider or universal agent registry;
+- a new DID method or OAuth replacement;
+- a replacement for MCP authorization, AuthZEN, SPIFFE, WIMSE, OPA, or Cedar;
+- a substitute for provider business authorization;
+- a prompt-safety system controlled by the model; or
+- an observability product that merely records an action after it occurs.
+
+## Messaging Guardrails
+
+- Lead with concrete actions and failure modes, not abstract agent identity.
+- Describe identity as an input to authorization, not the product category.
+- Describe provider verification as the differentiator, not the entire product.
+- Describe conformance and standards participation as the ecosystem strategy.
+- Use “deterministic” only for enforceable policy and state transitions, not
+  model behavior.
+- Preserve experimental labels and avoid unsupported certification claims.
+
+## Current Proof
+
+The repository already demonstrates the hierarchy through:
+
+- local guards, MCP adapters, gateways, approvals, and stateful controls;
+- provider contracts, JWS/JWKS receipts, provider middleware, and conformance
+  cases; and
+- execution receipts, evidence snapshots, verified observations, and intent
+  assurance.
+
+The next external proof milestone is two independent providers passing the same
+public action-authorization suite without AgentPass-specific coordination at
+runtime.

docs/standards-alignment.md

@@ -1,10 +1,11 @@
 # Standards Alignment
 
-AgentPass aligns with distributed identity and authorization standards as an
-open reference implementation and conformance project for action-bound
-authorization. It does not create a general agent identity or replace those
-standards. The detailed project boundary is in
-[Interoperability Positioning](interoperability-positioning.md).
+AgentPass's product category is action authorization and execution assurance,
+as defined in [Project Positioning](positioning.md). Within its standards work,
+AgentPass acts as an open reference implementation and conformance project for
+action-bound authorization. It does not create a general agent identity or
+replace existing identity and authorization standards. The detailed standards
+boundary is in [Interoperability Positioning](interoperability-positioning.md).
 
 For the current field-level mapping across AuthZEN, OAuth, WIMSE, SPIFFE, MCP,
 authorization-evidence proposals, and execution provenance, see the

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "agentpass"
 version = "0.2.0"
-description = "Authorization contracts, policy checks, and receipts for AI agent tool calls across MCP gateways, SaaS APIs, and enterprise systems."
+description = "Action authorization, runtime controls, and independently verifiable execution evidence for AI agent tool calls."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "Apache-2.0" }

tests/test_positioning_docs.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent.parent
+README = (ROOT / "README.md").read_text(encoding="utf-8")
+POSITIONING = (ROOT / "docs" / "positioning.md").read_text(encoding="utf-8")
+ROADMAP = (ROOT / "docs" / "action-gate-roadmap.md").read_text(encoding="utf-8")
+INTEROPERABILITY = (ROOT / "docs" / "interoperability-positioning.md").read_text(
+    encoding="utf-8"
+)
+STANDARDS = (ROOT / "docs" / "standards-alignment.md").read_text(encoding="utf-8")
+PYPROJECT = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+
+CATEGORY = "Action authorization and execution assurance for AI agents."
+PROMISE = (
+    "AgentPass controls consequential AI agent actions and produces independently\n"
+    "> verifiable evidence of what was authorized and executed."
+)
+LAYERS = [
+    "Runtime authorization and control",
+    "Portable provider trust and interoperability",
+    "Execution and outcome assurance",
+]
+
+
+def test_readme_leads_with_product_category_and_canonical_positioning():
+    assert README.startswith(f"# AgentPass\n\n**{CATEGORY}**")
+    assert PROMISE in README
+    assert "[Project Positioning](docs/positioning.md)" in README
+    assert (
+        "conformance work demonstrates interoperability; it is not the product category"
+        in README
+    )
+    assert (ROOT / "docs" / "positioning.md").is_file()
+
+
+def test_canonical_positioning_contains_required_hierarchy_and_boundaries():
+    assert f"**{CATEGORY}**" in POSITIONING
+    assert PROMISE in POSITIONING
+    for heading in [
+        "## Product Hierarchy",
+        "## Capability Story",
+        "## Audience Entry Points",
+        "## Standards And Open-Source Strategy",
+        "## What AgentPass Is Not",
+        "## Messaging Guardrails",
+    ]:
+        assert heading in POSITIONING
+    for audience in [
+        "Enterprise and security teams",
+        "Agent and application developers",
+        "MCP gateway and platform builders",
+        "SaaS, API, and MCP providers",
+        "Standards and open-source communities",
+    ]:
+        assert audience in POSITIONING
+    assert "Conformance is how AgentPass proves portability" in POSITIONING
+    assert "not certification by an external standards body" in POSITIONING
+
+
+def test_readme_and_roadmap_share_the_three_product_layers():
+    assert "[Project Positioning](positioning.md)" in ROADMAP
+    for layer in LAYERS:
+        assert layer in README
+        assert layer in ROADMAP
+        assert layer.title() in POSITIONING
+    assert "Framework wrappers and conformance suites are delivery mechanisms" in README
+    assert "They advance these layers rather than forming separate product" in ROADMAP
+
+
+def test_interoperability_and_package_metadata_support_product_positioning():
+    assert "open ecosystem strategy" in INTEROPERABILITY
+    assert "[Project Positioning](positioning.md)" in INTEROPERABILITY
+    assert (
+        "AgentPass's product category is action authorization and execution assurance"
+        in STANDARDS
+    )
+    assert "Within its standards work" in STANDARDS
+    assert (
+        'description = "Action authorization, runtime controls, and independently '
+        'verifiable execution evidence for AI agent tool calls."'
+    ) in PYPROJECT
+
+
+def test_changed_positioning_documents_have_valid_local_links():
+    documents = [
+        ROOT / "README.md",
+        ROOT / "docs" / "positioning.md",
+        ROOT / "docs" / "interoperability-positioning.md",
+        ROOT / "docs" / "standards-alignment.md",
+    ]
+    for document in documents:
+        text = document.read_text(encoding="utf-8")
+        for link in re.findall(r"!?\[[^\]]*\]\(([^)]+)\)", text):
+            path = link.split("#", 1)[0]
+            if not path or "://" in path or path.startswith("mailto:"):
+                continue
+            assert (document.parent / path).exists(), f"broken link in {document}: {link}"