@nullsquare/agent-authority 0.4.5 → 0.4.7

package/README.md

@@ -6,64 +6,29 @@
 
 ### Give your agent a task, not your account.
 
-**Agent Authority turns a human-approved task into temporary execution authority, then keeps that authority bounded as the agent discovers resources, crosses tools, and performs side effects.**
+**Agent Authority is a small execution layer that lets an agent use existing account permissions only for the task the user actually gave it.**
 
-[Task Leases](docs/task-leases.md) · [Executable evidence](docs/evidence.md) · [Extractor conformance](docs/authority-extractor-conformance.md) · [Transport invariance](docs/transport-invariance.md) · [Google proof](docs/live-google-validation.md) · [Integration contract](docs/integration-contract.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
+[Quickstart](docs/quickstart.md) · [Task-first API](#task-first-api) · [Product proof gate](docs/product-proof.md) · [Task Leases](docs/task-leases.md) · [Durability](docs/durable-task-leases.md) · [Evidence](docs/evidence.md) · [Transport invariance](docs/transport-invariance.md) · [Roadmap](ROADMAP.md)
 
-> **Status: public pre-alpha / v0.4.4 Developer Preview.** Published on npm as `@nullsquare/agent-authority`. The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype, execution-bound derived facts, reviewed Google and GitHub authority extractors, two-provider conformance tests, Task-Lease-aware SDK/MCP/broker execution, a real Vercel AI SDK harness proof, approvals, revocation, idempotency, credential isolation, live GitHub proofs, CI and CodeQL. It is not production-ready yet.
+> **Status: public pre-alpha / v0.4.6 Developer Preview on npm.** The task-first API is published as `@nullsquare/agent-authority/task`. Agent Authority is not production-ready yet.
 
 </div>
 
-## Install
-
-Requires Node.js 20+.
-
-```bash
-npm install @nullsquare/agent-authority
-```
+## Why this exists
 
-## The problem
+A user gives an agent a narrow task:
 
-AI agents increasingly receive broad provider permissions so they can complete narrow human tasks.
-
-A user says:
-
-> **Handle the demo request in this email thread.**
-
-The agent may need to:
-
-```text
-Gmail -> read one thread
-          |
-          v
-       discover sender
-          |
-          v
-Calendar -> create one meeting with that sender
-          |
-          v
-Gmail -> reply in the originating thread
-```
+> **Handle this customer email.**
 
-The underlying OAuth connections may permit reading every email, creating meetings with anyone, or sending mail to anyone.
+But the connected account may give the application broad standing permission to read every email, create meetings with anyone, update any CRM record, or send mail to anyone.
 
-Traditional authorization answers:
+OAuth and IAM answer:
 
 > Can this application use Calendar?
 
-Agent Authority asks a narrower question immediately before the side effect:
+Agent Authority asks immediately before the effect:
 
-> **Is this exact effect justified by the task the human authorized?**
-
-## Task-bounded autonomy
-
-Agent Authority is trying to make this trade-off unnecessary:
-
-```text
-broad standing permissions
-        OR
-approve every tool call
-```
+> **Is this exact Calendar action justified by the task the user authorized?**
 
 The target is:
 
@@ -73,355 +38,391 @@ one meaningful task approval
         v
 temporary bounded authority
         |
-        +--> safe task actions proceed
-        +--> unrelated resources are blocked
-        +--> real authority expansion requires step-up
+        +--> useful task actions proceed normally
+        +--> authority may follow resources discovered through authorized work
+        +--> unrelated resources require step-up
         |
         v
-task completes -> authority disappears
+task completes -> task authority disappears
 ```
 
 The provider credential may continue to exist. The **task authority does not**.
 
-## The key idea: authority can follow trusted task data
-
-Many resources do not exist in the original prompt. The agent discovers them while working.
+## Install
 
-Agent Authority models this with a **Task Lease**:
+Requires Node.js 20+.
 
-```text
-Human-approved task
-        |
-        v
-  authority root
-  Gmail thread #91
-        |
- authorized read
-        |
-        +--> ALLOW receipt
-        +--> exact output hash evidence
-        |
-        v
- reviewed adapter extractor
-        |
-        v
- derived fact
- customer@example.com
-        |
-        v
- exact binding
- Calendar attendee must equal that sender
+```bash
+npm install @nullsquare/agent-authority
 ```
 
-A request for `customer@example.com` can proceed.
+## Fresh-install quickstart
 
-A request for `other@example.com` does not silently inherit the same authority. It becomes an **authority delta** and requires step-up.
+You can see the task-authority model without a repository checkout, provider credential, OAuth setup, custom extractor, or Mission JSON.
 
-This is **derived authority**: authority follows a resource discovered through authorized execution, but never broadens into a standing wildcard permission.
-
-See [Task Leases and Derived Authority](docs/task-leases.md).
+```bash
+mkdir agent-authority-quickstart
+cd agent-authority-quickstart
+npm init -y
+npm install @nullsquare/agent-authority
+curl -fsSL https://raw.githubusercontent.com/Null-Square/agent-authority/main/examples/quickstart.mjs -o quickstart.mjs
+node quickstart.mjs
+```
 
-## Core invariant
+Expected shape:
 
 ```text
-Task Lease authority <= Mission authority
+ALLOW -> task discovered issue #42 and the exact comment effect ran
+STEP-UP -> The task established authority for 42 but this action requested 7.
+PASS -> useful task work ran; unrelated standing permission did not become task authority
 ```
 
-The mission remains the ceiling. A Task Lease may narrow an action to resources discovered during the task, but it cannot grant an action that the mission already denies or never allowed.
+The quickstart uses the real published `createTask()` API and reviewed GitHub authority extractor. Only the provider callback is a local provider-shaped fixture so the first run needs no account.
 
-More generally:
+An automated blank-project gate independently installed `@nullsquare/agent-authority@0.4.6` from npm on Node 20 and ran this exact file successfully. That proves the current published package supports the documented path; it does **not** replace the still-open first-time-human under-10-minute adoption test.
 
-> **Authority may stay the same or shrink as it moves through agents, tools and transports. It must never silently grow.**
+### Next: make one real GitHub call, still with no credential
 
-## Run the derived-authority demo
-
-Requirements: Node.js 20+.
+From the same blank project:
 
 ```bash
-git clone https://github.com/Null-Square/agent-authority.git
-cd agent-authority
-npm install
-npm test
-npm run demo:task-lease
+curl -fsSL https://raw.githubusercontent.com/Null-Square/agent-authority/main/examples/quickstart-github-live.mjs -o quickstart-github-live.mjs
+node quickstart-github-live.mjs
 ```
 
-The demo performs this flow without provider credentials:
+Expected shape:
 
 ```text
-1. ALLOW read of one task-authorized Gmail thread
-2. derive sender email from that same Task Lease receipt
-3. ALLOW Calendar event for that sender
-4. REQUIRE_APPROVAL for a different attendee
-5. complete task
-6. DENY subsequent actions
+Standing GitHub permission -> repo.read
+Task authority -> Null-Square/agent-authority
+GitHub mode -> public API; no credential required
+ALLOW -> real GitHub returned Null-Square/agent-authority
+STEP-UP -> The task established authority for "Null-Square/agent-authority" but this action requested "octocat/Hello-World".
+PASS -> broader standing repo.read permission could not reach an unrelated repository for this task
 ```
 
-The side-effect callbacks for blocked actions never run.
+This deliberately models the account/app capability as broader than the task. Mission-level `repo.read` can read repositories generally, while the Task authority root allows this task to reach only `Null-Square/agent-authority`. The first request makes one real public GitHub `fetch()`; the unrelated repository is stopped before a second network call.
+
+A separate blank-project CI gate has passed this exact live path against npm `0.4.6`. Authenticated/private-repository onboarding remains separate follow-on work.
 
-The repository also includes a real Gmail → Calendar validation path and a reusable Google provider adapter. The strict path binds the derived sender to the exact guarded output before it becomes authority. See [Live Gmail → Calendar validation](docs/live-google-validation.md) and [Executable Evidence](docs/evidence.md).
+See [Fresh-install quickstart](docs/quickstart.md).
 
-v0.4.3 applied the **same evidence-derived authority primitive to GitHub**: a root-bound repository + fixture marker are used by the reviewed GitHub adapter to select one issue from a real `issue.list` response; `deriveFromEvidence()` establishes that exact issue number as downstream authority; one real comment mutation succeeds; unrelated and post-completion issue mutations never reach the provider. Google and GitHub are exercised by the same [authority extractor conformance contract](docs/authority-extractor-conformance.md).
+## Task-first API
 
-v0.4.4 adds the **transport-invariance proof**: one `execution-evidence-v1` derived fact is established under one Task Lease, then that exact lease and fact constrain ordinary `guard.run()`, the MCP gateway and brokered provider execution. The same allowed resource succeeds, an unrelated resource produces `authority_delta_required` with zero blocked callbacks/provider calls, and task completion produces `task_lease_completed` across all three paths. The repository also drives a real Vercel AI SDK `ToolLoopAgent` through `protectAiSdkTools()`: unrelated resources, unmapped executable tools and completed leases are surfaced as tool errors while the underlying side-effect counters remain zero. See [Task Lease transport invariance](docs/transport-invariance.md).
+The preferred developer surface is intentionally small:
 
-## Minimal developer API
+```text
+Task -> Effect -> Authority
+```
 
 ```js
-import { AuthorityRuntime } from '@nullsquare/agent-authority';
-import { createTaskLease } from '@nullsquare/agent-authority/task-lease';
-import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
-import { gmailThreadSenderAuthorityExtractor } from '@nullsquare/agent-authority/providers/google';
-
-const lease = createTaskLease({
-  mission,
-  request: 'Handle the demo request in thread:demo-91',
-  roots: [
-    { fact_id: 'fact:thread', kind: 'gmail.thread', value: 'thread:demo-91' }
-  ],
+import { createTask } from '@nullsquare/agent-authority/task';
+
+const task = createTask({
+  principal: 'user:me',
+  agent: 'agent:assistant',
+  request: 'Find issue #42 and leave one comment only on that issue',
+
+  permissions: {
+    github: {
+      allow: ['issue.list', 'issue.comment'],
+      deny: ['issue.close', 'repo.delete'],
+      constraints: { repository: ['acme/app'] }
+    }
+  },
+
+  authority: {
+    repository: {
+      kind: 'github.repository',
+      value: 'acme/app'
+    }
+  },
+
   bindings: [
     {
-      service: 'calendar',
-      action: 'event.create',
-      context_field: 'attendee_email',
-      fact_id: 'fact:sender-email'
+      service: 'github',
+      action: 'issue.list',
+      field: 'repository',
+      authority: 'repository'
     }
   ]
 });
 
-const guard = createTaskLeaseGuard({
-  lease,
-  runtime: new AuthorityRuntime()
+const discovery = await task.run({
+  service: 'github',
+  action: 'issue.list',
+  context: { repository: 'acme/app' }
+}, () => github.listIssues());
+
+const issue = task.authorityFrom(discovery, {
+  name: 'issue',
+  kind: 'github.issue.number',
+  from: 'repository',
+  extractor: selectedIssueExtractor
 });
 
-const read = await guard.run({
-  service: 'gmail',
-  action: 'thread.read',
-  context: { thread_id: 'thread:demo-91' }
-}, () => gmail.readThread('thread:demo-91'));
-
-const senderFact = lease.deriveFromEvidence({
-  fact_id: 'fact:sender-email',
-  kind: 'email.address',
-  from: ['fact:thread'],
-  receipt: read.receipt,
-  evidence: read.evidence,
-  output: read.output,
-  extractor: gmailThreadSenderAuthorityExtractor
+task.bind({
+  service: 'github',
+  action: 'issue.comment',
+  field: 'issue_number',
+  authority: 'issue'
 });
 
-await guard.run({
-  service: 'calendar',
-  action: 'event.create',
-  context: { attendee_email: senderFact.value }
-}, () => calendar.createEvent({ attendee: senderFact.value }));
+await task.run({
+  service: 'github',
+  action: 'issue.comment',
+  context: {
+    repository: 'acme/app',
+    issue_number: issue.value,
+    body: 'Handled.'
+  }
+}, () => github.comment(issue.value, 'Handled.'));
 ```
 
-`deriveFromEvidence()` does not accept the authority value. The reviewed extractor selects a normalized output field, and Task Lease resolves that value only after verifying that the output still matches the exact allowed execution evidence.
+If the agent changes `issue_number` to an unrelated issue, the callback does not run. Agent Authority returns an authority-delta step-up that can be explained to a human:
 
-The older `derive()` API remains available as the explicitly **host-trusted compatibility path**.
+```js
+try {
+  await task.run(unrelatedRequest, effect);
+} catch (error) {
+  console.log(task.explain(error).summary);
+}
+```
 
-The host keeps its existing SDK, connector and authentication. Agent Authority controls whether the effect may happen.
+Example output:
 
-## Three integration modes, one authority model
+```text
+The task established authority for 42 but this action requested 7.
+```
 
-Agent Authority is deliberately **not tied to MCP, OAuth, or one agent framework**.
+The task-first API is a facade over the existing Mission, Task Lease, execution-evidence and guard primitives. It does not weaken or replace them.
 
-### 1. In-process guard
+## Run the product demo
+
+From a checkout:
+
+```bash
+npm install
+npm run demo:task
+```
+
+The self-contained GitHub-shaped demo performs:
 
 ```text
-agent code -> guard.run() -> existing SDK / API
+1. authorized issue discovery
+2. exact guarded result becomes downstream authority
+3. comment on the discovered issue succeeds
+4. comment on an unrelated issue requires step-up
+5. blocked attempt executes zero provider callbacks
 ```
 
-Best when the application already owns the provider connection.
+The callback bodies are intentionally replaceable with the SDK/provider calls an application already uses.
 
-### 2. MCP gateway
+## Utility benchmark
+
+Security is necessary but not sufficient. Agent Authority also tracks whether normal agent work still succeeds without approval fatigue.
+
+```bash
+npm run benchmark:task
+```
+
+The first deterministic fixture measures:
+
+- normal task completion rate;
+- false approval rate;
+- true authority-delta step-up rate;
+- unauthorized effect rate;
+- provider effects required for completed tasks.
+
+Its current regression target is:
 
 ```text
-MCP host -> Agent Authority -> existing MCP server
+normal task completion rate = 100%
+false approval rate = 0%
+true authority-delta step-up rate = 100%
+unauthorized effect rate = 0%
 ```
 
-Best when the harness already speaks MCP. MCP is an integration transport, not the product identity.
+This is a deterministic product regression fixture, **not a real-world benchmark**. Real provider and harness workloads should replace or supplement it as adoption grows.
+
+See [Product proof gate](docs/product-proof.md).
+
+## The differentiated mechanism
 
-### 3. Brokered execution
+Many task resources are unknown when the user gives the instruction. They are discovered during execution.
+
+Agent Authority lets authority follow those resources only when the value comes from already-authorized work:
 
 ```text
-agent -> Agent Authority -> isolated credential -> provider
+human-approved task
+        |
+        v
+ authority root
+ repository = acme/app
+        |
+ authorized issue discovery
+        |
+        +--> ALLOW receipt
+        +--> exact output evidence
+        |
+ reviewed extractor
+        |
+        v
+ derived authority
+ issue = 42
+        |
+        v
+ later effect may bind issue_number == 42
 ```
 
-Best when the agent should not receive the provider credential at all.
-
-v0.4.4 demonstrates the **same Task Lease and authority fact across all three paths in-process**, plus the configured Vercel AI SDK `ToolLoopAgent` protected-tool path. M4 is complete at this execution-boundary level. A malicious host that deliberately exposes a separate unguarded tool or credential remains outside Agent Authority's security boundary.
-
-## What is implemented
-
-### Task authority
-
-- mission validation and deterministic `ALLOW / DENY / REQUIRE_APPROVAL`
-- explicit deny precedence
-- resource/context constraints
-- expiry and cumulative budgets
-- delegation attenuation
-- durable mission revocation
-- Task Lease prototype
-- explicit authority roots
-- same-lease provenance-bound derived facts
-- execution evidence binding an allowed receipt, request and exact output hash
-- strict `deriveFromEvidence()` path where the caller cannot provide the authority value
-- reviewed Gmail sender authority extractor bound to `gmail:thread.read`
-- reviewed GitHub selected-issue-number extractor bound to marker-scoped `github:issue.list`
-- shared Google/GitHub authority-extractor conformance suite
-- legacy host-trusted `derive()` compatibility path
-- required parent lineage and extraction selector
-- exact context-field bindings
-- authority-delta step-up signal
-- immediate task completion/expiry enforcement
-- Task Lease IDs/hashes in decision receipts
-
-### Enforcement
-
-- protocol-neutral `guard.run()` wrapper
-- blocked side effects never invoke their callback
-- successful guarded effects return separate execution evidence
-- Task-Lease-aware MCP gateway/proxy evaluation
-- Task-Lease-aware brokered execution via `ExecutingAuthorityRuntime.executeTaskLease()`
-- brokered execution evidence bound to Task-Lease receipts
-- SDK/MCP/broker transport-invariance conformance test
-- real Vercel AI SDK `ToolLoopAgent` protected-tool harness proof
-- unmapped executable AI SDK tools fail closed before their effect executes
-- one-time human approvals bound to exact request
-- mutation idempotency
-- conservative uncertain-state handling
-- signed harness action grants
-- MCP v2 read-only gateway/proxy
-
-### Credentials and runtime
-
-- persistent connection metadata
-- AES-256-GCM local encrypted secret store
-- safe reconnect cleanup
-- GitHub brokered execution without returning the token to the agent
-- GitHub REST mappings for repository access plus evidence-derived `issue.list` / `issue.comment`
-- Google REST provider mappings for Gmail thread reads and Calendar event mutations
-- short-lived signed local agent-instance tokens
-- local CLI/daemon
-
-### Engineering quality
-
-- adversarial authorization tests
-- execution-evidence substitution, tampering, replay, cross-lease and selector tests
-- the same provider-derived-authority conformance attacks against Google and GitHub
-- cross-transport invariance test for direct SDK, MCP and brokered execution
-- real AI SDK agent-loop tests for unauthorized, unmapped and completed-lease tool calls with zero underlying effects
-- Node 20 and Node 22 CI
-- coverage run
-- package checks
-- clean-consumer npm registry verification
-- live GitHub read and evidence-derived mutation proofs
-- CodeQL
-
-## What is different from OAuth, IAM and MCP authorization?
-
-Agent Authority is **not trying to replace them**.
-
-OAuth/IAM answer who or what may access a provider and with which standing scopes. MCP authorization protects an MCP transport. Agent Authority operates at a different boundary:
+A request for issue `42` can proceed.
+
+A request for issue `7` does not inherit the same authority simply because the underlying GitHub credential can access it.
+
+That is the core contribution we are testing:
+
+> **Authority may follow the task's proven execution path without becoming ambient account authority.**
+
+## Core invariant
 
 ```text
-human task
-    |
-    v
-temporary task authority
-    |
-    v
-exact agent-originated effect
-    |
-    +--> existing OAuth / IAM / MCP / SDK / CLI
+Task Lease authority <= Mission authority
 ```
 
-The project should consume existing identity/authentication mechanisms and emerging standards rather than invent another login or token format.
+The Mission remains the ceiling. Task authority may stay the same or shrink as work crosses tools, transports and durable state. It must never silently grow.
 
-The contribution we are testing is operational: **make task-scoped, provenance-aware least privilege usable inside ordinary agent stacks.**
+## Existing stack, not a replacement stack
 
-## Example use cases
+Agent Authority is not trying to replace OAuth, IAM, MCP, gateways or agent frameworks.
 
-### Support / sales
+```text
+agent reasoning
+      |
+      v
+Agent Authority
+      |
+      v
+existing SDK / MCP / gateway / OAuth / provider
+```
 
-> Handle this customer request.
+Three execution modes already share the same Task Lease semantics:
 
-Bind later actions to the customer, thread, ticket or meeting discovered from the authorized task path.
+```text
+in-process guard
+MCP gateway
+brokered provider execution
+```
+
+A real Vercel AI SDK `ToolLoopAgent` integration also exercises the protected-tool boundary. See [Transport invariance](docs/transport-invariance.md).
 
-### Finance
+## Durability
 
-> Refund the customer from this ticket, but never more than the original charge.
+For local workflows that must survive process restarts, pass a `JsonFileTaskLeaseStore` to the same task-first API:
 
-Discover customer -> order -> charge through authorized reads, then bind the refund to those concrete facts and amount ceiling.
+```js
+import { JsonFileTaskLeaseStore } from '@nullsquare/agent-authority/storage';
+import { createTask } from '@nullsquare/agent-authority/task';
+
+const store = new JsonFileTaskLeaseStore({
+  dir: config.paths.task_leases,
+  keyPath: config.paths.master_key
+});
 
-### Coding / operations
+const task = createTask({
+  ...taskDefinition,
+  store
+});
+```
 
-> Fix issue #42, open a PR, do not merge or deploy production.
+The task facade then uses the durable Task Lease session internally. Normal task calls do not change.
 
-Keep repo/issue/branch authority bounded as subagents and tools change.
+Durable state currently provides authenticated local recovery, exact Mission binding, atomic whole-state replacement, per-lease local locking, stale-writer compare-and-swap protection, durable completion/expiry, and refresh before authority evaluation.
 
-### Personal / company operating agents
+See [Durable Task Leases](docs/durable-task-leases.md).
 
-> Handle this email.
+## What is already proven
 
-Allow a natural workflow across mail, calendar, CRM and internal systems without turning every connected account into ambient agent authority.
+- deterministic allow / deny / require-approval decisions;
+- explicit deny precedence and Mission ceiling;
+- execution evidence bound to exact guarded output;
+- strict evidence-derived authority where callers do not provide the derived value;
+- reviewed Google Gmail-sender and GitHub selected-issue extractors;
+- shared two-provider adversarial conformance tests;
+- live GitHub read and evidence-derived comment mutation proofs;
+- connected Gmail -> Calendar smoke proof;
+- direct SDK / MCP / broker transport invariance;
+- real Vercel AI SDK protected-tool execution proof;
+- authenticated durable Task Lease recovery;
+- stale-writer/CAS and mission-alias protection;
+- automatic durable Task Lease sessions;
+- task-first public facade and deterministic utility regression gate;
+- self-contained support/communications and operations/finance product proofs;
+- blank-project fixture quickstart against the current npm package;
+- blank-project real public GitHub onboarding with broader standing permission and narrower task authority;
+- Node 20/22 CI, coverage, packed-consumer validation and CodeQL;
+- independent npm registry consumer verification.
 
-## Security principles
+The lower-level evidence is documented under `docs/` and remains available for security review.
 
-1. **Task before credential.** A provider token is not task authority.
-2. **Mission is the ceiling.** Task Leases cannot override explicit denies.
-3. **No side effect before authorization.** Denied and step-up actions never execute.
-4. **Authority lineage matters.** Provider-derived authority should bind the exact allowed receipt and guarded output to a reviewed extractor; legacy host-trusted derivation remains identifiable in provenance.
-5. **No silent resource expansion.** A different concrete resource becomes an authority delta.
-6. **Task authority ends with the task.** Completion and expiry are independent from provider credential lifetime.
-7. **Authority may shrink, never silently grow.** Delegation and transport changes must preserve non-amplification.
-8. **The evaluated request must be the executed request.** Request hashes, grants and idempotency protect the boundary.
-9. **Credentials stay out of model context where Agent Authority owns them.**
-10. **Security gaps are documented, not marketed away.**
+## Product direction
 
-See [SECURITY.md](SECURITY.md).
+The next product risk is **not lack of another security subsystem**. It is adoption and useful autonomy.
 
-## Current limitations
+Before deeper distributed/crypto infrastructure becomes a priority, Agent Authority should prove:
 
-This is still a validation implementation.
+1. a new developer can get a meaningful workflow running in under 10 minutes;
+2. coding, support/communications and operations/finance workflows all fit the task-first model;
+3. normal task completion stays high without approval spam;
+4. unrelated-resource effects still execute zero provider callbacks;
+5. at least one external developer adopts the package without project-author assistance.
 
-- Task Lease state is currently process-local.
-- Transport and harness proofs cover configured Agent Authority execution boundaries, not a malicious host that exposes a separate unguarded tool, credential, shell or network path.
-- `deriveFromEvidence()` proves consistency with the exact output returned through the trusted Agent Authority guard, but the output is not cryptographically attested by Gmail, GitHub, or another remote provider.
-- The legacy `derive()` API remains host-trusted for compatibility; audit provenance distinguishes it from `execution-evidence-v1` derivation.
-- Source-data changes do not yet automatically invalidate already-derived authority facts.
-- Bindings currently target top-level request context fields.
-- Approved authority deltas are surfaced but not automatically applied back into a live lease.
-- GitHub token-stdin is a developer bridge, not final browser OAuth onboarding.
-- The encrypted local vault is not an OS keychain/KMS/HSM backend.
-- Remote authenticated deployment and a production approval UX are not complete.
+See [Product proof gate](docs/product-proof.md) and [Roadmap](ROADMAP.md).
 
-These are follow-on validation problems. We are intentionally not solving them with a giant policy language or another agent framework.
+## Current limitations
 
-## What we are deliberately not building
+This is still a validation implementation.
 
-- another agent harness
-- another OAuth or identity protocol
-- an MCP replacement
-- a connector marketplace
-- a giant proprietary policy DSL
-- an enterprise dashboard before the enforcement primitive proves adoption
+- Durable persistence is a trusted-local-host reference backend, not distributed consensus or hostile-host containment.
+- Another worker can still change durable state after an `ALLOW` decision and before asynchronous remote provider I/O begins. Remote effect + receipt + Task Lease state are not one distributed transaction.
+- A crashed local worker may leave a per-lease lock requiring explicit recovery.
+- Transport/harness proofs do not contain a malicious host that deliberately exposes a separate unguarded tool, shell, network path or credential.
+- Provider outputs are evidence-bound inside the trusted Agent Authority runtime but are not provider-signed remote attestations.
+- Source-data changes do not yet automatically invalidate already-derived authority.
+- Approved authority deltas are surfaced but not automatically applied into a live durable task.
+- Current Task Lease bindings are exact equality. The finance proof therefore steps up for a partial refund as well as an over-refund; a derived numeric ceiling remains an evidence-driven product question rather than a general policy language.
+- Public GitHub onboarding is credential-free for read-only public repositories; authenticated/private-repository onboarding and production OAuth/KMS UX remain incomplete.
+- Remote authenticated deployment and production approval UX remain incomplete.
+
+These are real limitations. They are not reasons to build every possible infrastructure layer before product adoption is proven.
+
+## What we are deliberately not prioritizing now
+
+Unless a real workflow proves otherwise:
+
+- another agent harness;
+- a new OAuth/identity/token protocol;
+- an MCP replacement/control plane;
+- a connector marketplace;
+- a proprietary universal policy DSL;
+- distributed Task Lease databases;
+- provider-attestation protocol design;
+- A2A implementation;
+- dashboard-first enterprise product work.
 
 ## Contributing
 
-The best contribution is not another abstract feature. It is a real integration or adversarial case that answers:
+The most valuable contribution answers:
 
-> **Can this agent complete the intended task while being technically unable to use the same underlying account authority for an unrelated effect?**
+> **Can this agent complete the intended task while being technically unable to use the same standing account authority for an unrelated effect?**
 
-We especially want:
+Especially useful:
 
-- framework integrations around `guard.run()`;
-- trustworthy operation -> resource-context mappings;
-- Task Lease examples from real workflows;
+- real task-first workflows;
+- trustworthy operation -> resource mappings;
+- utility-regression cases that cause unnecessary approvals;
 - derived-authority / provenance attacks;
-- MCP and non-MCP conformance cases;
-- secure persistence and extraction-verification designs that stay simple.
+- transport or multi-worker attacks;
+- feedback from developers trying to integrate the package for the first time.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).