permdock 0.0.0 → 0.1.0

package/schemas/openapi/overlay-1.1.json

@@ -0,0 +1,79 @@
+{
+  "$id": "https://spec.openapis.org/overlay/1.1/schema/2026-04-01",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "The description of Overlay v1.1.x documents",
+  "type": "object",
+  "properties": {
+    "overlay": {
+      "type": "string",
+      "pattern": "^1\\.1\\.\\d+$"
+    },
+    "info": {
+      "$ref": "#/$defs/info-object"
+    },
+    "extends": {
+      "type": "string",
+      "format": "uri-reference"
+    },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/action-object"
+      }
+    }
+  },
+  "required": ["overlay", "info", "actions"],
+  "$ref": "#/$defs/specification-extensions",
+  "unevaluatedProperties": false,
+  "$defs": {
+    "info-object": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        }
+      },
+      "required": ["title", "version"],
+      "$ref": "#/$defs/specification-extensions",
+      "unevaluatedProperties": false
+    },
+    "action-object": {
+      "type": "object",
+      "properties": {
+        "target": {
+          "type": "string",
+          "pattern": "^\\$"
+        },
+        "description": {
+          "type": "string"
+        },
+        "update": {
+          "type": ["string", "boolean", "object", "array", "number", "null"]
+        },
+        "copy": {
+          "type": "string"
+        },
+        "remove": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "required": ["target"],
+      "$ref": "#/$defs/specification-extensions",
+      "unevaluatedProperties": false
+    },
+    "specification-extensions": {
+      "patternProperties": {
+        "^x-": true
+      }
+    }
+  }
+}

package/schemas/supabase-claims-v1.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.dev/schemas/supabase-claims-v1.json",
+  "title": "PermDock claims in a Supabase access token",
+  "description": "The claims the permdock supabase hook writes and the SQL helpers and subjectFromSupabase read, plus the OAuth claims subjectFromSupabase maps to the actor and delegation. Other claims pass through. Each hook claim may also sit under app_metadata. supabaseClaims() in permdock/supabase validates the same shape; tenant_id is the default rls.tenantClaim.",
+  "type": "object",
+  "allOf": [{ "$ref": "#/$defs/permdockClaims" }],
+  "properties": {
+    "client_id": {
+      "description": "The OAuth client of a third-party app; becomes actor.id when there is no act claim.",
+      "type": "string"
+    },
+    "scope": {
+      "description": "OAuth scopes, space-separated or as a list; becomes delegation.scopes.",
+      "anyOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "act": { "$ref": "#/$defs/act" },
+    "app_metadata": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/permdockClaims" }]
+    }
+  },
+  "$defs": {
+    "permdockClaims": {
+      "type": "object",
+      "properties": {
+        "user_role": {
+          "description": "Global roles: one name, a list, or null for none.",
+          "anyOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } },
+            { "type": "null" }
+          ]
+        },
+        "roles": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "memberships": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/membership" }
+        },
+        "memberships_truncated": {
+          "description": "true when the size budget cut memberships or attrs.",
+          "type": "boolean"
+        },
+        "tenant_id": {
+          "description": "The active tenant (the default rls.tenantClaim): the canonical text of one instance of the first scope.",
+          "type": "string"
+        },
+        "attrs": {
+          "description": "Allow-listed server-owned attributes, read as principal.claims.attrs.<key>.",
+          "type": "object"
+        },
+        "authz_ver": {
+          "description": "The principal's authorization version.",
+          "type": "integer"
+        }
+      }
+    },
+    "act": {
+      "description": "RFC 8693 actor chain: the outermost sub is the current actor, each nested act a prior one. The outermost kind names the actor: none is an OAuth client or agent, support a support session (needs session_id), impersonation an admin acting as the user.",
+      "type": "object",
+      "required": ["sub"],
+      "properties": {
+        "sub": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["support", "impersonation"] },
+        "session_id": { "type": "string", "minLength": 1 },
+        "read_only": { "type": "boolean" },
+        "reason": { "type": "string" },
+        "act": { "$ref": "#/$defs/act" }
+      },
+      "if": {
+        "required": ["kind"],
+        "properties": { "kind": { "const": "support" } }
+      },
+      "then": { "required": ["session_id"] }
+    },
+    "membership": {
+      "type": "object",
+      "required": ["roles"],
+      "properties": {
+        "scope": { "type": "string" },
+        "id": {
+          "description": "Canonical text of the scope instance id (uuid::text for a uuid column); compared exactly, never lower-cased.",
+          "type": "string"
+        },
+        "within": {
+          "description": "The id of every ancestor scope instance, by scope name.",
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "on": {
+          "type": "object",
+          "required": ["resource", "id"],
+          "properties": {
+            "resource": { "type": "string" },
+            "id": { "type": "string" }
+          }
+        },
+        "tenant": { "type": "string" },
+        "team": { "type": "string" },
+        "roles": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "via": { "type": "string" },
+        "expiresAt": {
+          "description": "Seconds since the epoch.",
+          "type": "number"
+        },
+        "grantedBy": { "type": "string" },
+        "reason": { "type": "string" },
+        "member": {
+          "description": "The subgroup a membership source's group fills.",
+          "type": "object",
+          "required": ["group"],
+          "properties": { "group": { "type": "string", "minLength": 1 } }
+        },
+        "managedBy": { "const": "idp" },
+        "entitlements": { "type": "array", "items": { "type": "string" } },
+        "grants": {
+          "description": "Custom roles in compact form, read by the helpers in jwt mode.",
+          "type": "object"
+        }
+      },
+      "anyOf": [
+        { "required": ["scope", "id"] },
+        { "required": ["tenant"] },
+        { "required": ["team"] },
+        { "required": ["on"] }
+      ]
+    }
+  }
+}

package/schemas/supabase-manifest-v1.json

@@ -0,0 +1,217 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.dev/schemas/supabase-manifest-v1.json",
+  "title": "PermDock Supabase hook manifest v1",
+  "description": "What `permdock supabase inspect --json` prints and `--out` writes: the generated hook, the SQL helpers, the claims, the membership sources and the columns that decide them. Fields are only added within v1.",
+  "type": "object",
+  "required": [
+    "$schema",
+    "version",
+    "hook",
+    "helpers",
+    "tenantClaim",
+    "budget",
+    "claims",
+    "authzVersion",
+    "memberships",
+    "rls",
+    "decidingColumns",
+    "markers"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "https://permdock.dev/schemas/supabase-manifest-v1.json"
+    },
+    "version": { "const": 1 },
+    "hook": {
+      "type": "object",
+      "required": ["schema", "function", "out"],
+      "properties": {
+        "schema": { "$ref": "#/$defs/identifier" },
+        "function": { "const": "custom_access_token_hook" },
+        "out": { "type": "string" }
+      }
+    },
+    "helpers": {
+      "type": "object",
+      "required": ["schema", "functions"],
+      "properties": {
+        "schema": { "$ref": "#/$defs/identifier" },
+        "functions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/helperName" }
+        }
+      }
+    },
+    "tenantClaim": { "$ref": "#/$defs/identifier" },
+    "budget": {
+      "type": "object",
+      "required": ["bytes", "measure"],
+      "properties": {
+        "bytes": { "type": "integer", "minimum": 1 },
+        "measure": { "type": "string" }
+      }
+    },
+    "claims": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "source", "budget"],
+        "properties": {
+          "name": { "$ref": "#/$defs/identifier" },
+          "source": {
+            "type": "string",
+            "pattern": "^(permdock|[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*)$"
+          },
+          "budget": { "type": "boolean" }
+        }
+      }
+    },
+    "authzVersion": { "type": "boolean" },
+    "authzVersionBump": {
+      "type": "object",
+      "required": ["schema", "function", "args"],
+      "properties": {
+        "schema": { "$ref": "#/$defs/identifier" },
+        "function": { "const": "permdock_bump_authz_version_for" },
+        "args": { "const": "p_users uuid[]" }
+      }
+    },
+    "memberships": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/membership" }
+    },
+    "rls": {
+      "type": "object",
+      "required": [
+        "schema",
+        "mode",
+        "tenantClaim",
+        "scopes",
+        "helpers",
+        "memberships"
+      ],
+      "properties": {
+        "schema": { "$ref": "#/$defs/identifier" },
+        "mode": { "enum": ["jwt", "database"] },
+        "tenantClaim": { "$ref": "#/$defs/identifier" },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "type"],
+            "properties": {
+              "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
+              "type": { "type": "string" },
+              "within": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }
+            }
+          }
+        },
+        "helpers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "args", "returns", "execute"],
+            "properties": {
+              "name": { "$ref": "#/$defs/helperName" },
+              "args": { "type": "string" },
+              "returns": { "type": "string" },
+              "execute": {
+                "type": "array",
+                "items": {
+                  "enum": ["anon", "authenticated", "supabase_auth_admin"]
+                }
+              }
+            }
+          }
+        },
+        "memberships": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/membership" }
+        }
+      }
+    },
+    "decidingColumns": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+      }
+    },
+    "markers": {
+      "type": "object",
+      "required": ["hook", "grants"],
+      "properties": {
+        "hook": { "const": "v1" },
+        "grants": { "const": "v1" }
+      }
+    }
+  },
+  "$defs": {
+    "membership": {
+      "type": "object",
+      "required": ["table", "user", "scope", "id", "role", "columns"],
+      "properties": {
+        "table": {
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "user": { "$ref": "#/$defs/column" },
+        "scope": { "$ref": "#/$defs/value" },
+        "id": { "$ref": "#/$defs/column" },
+        "role": { "$ref": "#/$defs/value" },
+        "within": {
+          "oneOf": [
+            { "$ref": "#/$defs/column" },
+            {
+              "type": "object",
+              "required": ["columns"],
+              "additionalProperties": false,
+              "properties": {
+                "columns": {
+                  "type": "object",
+                  "additionalProperties": { "$ref": "#/$defs/identifier" }
+                }
+              }
+            }
+          ]
+        },
+        "via": { "$ref": "#/$defs/value" },
+        "expiresAt": { "$ref": "#/$defs/column" },
+        "columns": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/identifier" }
+        }
+      }
+    },
+    "identifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "helperName": {
+      "type": "string",
+      "pattern": "^(permdock_has|permitted_[a-z][a-z0-9_]*_ids|member_[a-z][a-z0-9_]*_ids(_for)?)$"
+    },
+    "column": {
+      "type": "object",
+      "required": ["column"],
+      "additionalProperties": false,
+      "properties": { "column": { "$ref": "#/$defs/identifier" } }
+    },
+    "value": {
+      "oneOf": [
+        { "$ref": "#/$defs/column" },
+        {
+          "type": "object",
+          "required": ["value"],
+          "additionalProperties": false,
+          "properties": {
+            "value": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ]
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/permdock/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: permdock
+description: Explains how PermDock decides and routes to the right PermDock skill. Use first for any work with permdock, typed permissions, roles or access control in a TypeScript app, when a check is denied and the reason is unclear, when reading a Decision, denial reason or doctor code, when looking up current PermDock identifiers through the docs MCP, or when choosing between the permdock-wire, permdock-audit, permdock-agents, permdock-approvals, permdock-tenancy, permdock-data and permdock-credentials skills.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.dev/docs/for-ai-agents
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock
+
+PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents. Permissions are defined once, decided in process, compiled to queries and RLS, and serialised to client snapshots ([for AI agents](https://permdock.dev/docs/for-ai-agents)). This skill holds the model every other PermDock skill assumes, and says which one to load.
+
+## Inputs (find out before starting)
+
+- Whether the app already has `permissions.ts`, `policy.ts` and a `createPermDock` factory file. None means start with `permdock-wire`.
+- The task: set up, review, or one area (agents, approvals, tenants, queries and RLS, tokens and keys).
+- Whether the `permdock` binary runs in the repo (`pnpm exec permdock doctor`).
+
+## Invariants
+
+1. **Fail-closed.** Anything unknown, invalid or thrown denies. `can()` never throws. A `Decision` is only `granted`, `denied` or `approval-required`.
+2. **Deny overrides allow.** Allows OR together; any matching `deny` wins.
+3. **References, not strings.** Pass `permissions.post.update`; strings appear only as `.key` / `.scope` on the wire, in catalogs and in audit.
+4. **Authentication is upstream.** Core never verifies a token. The subject comes from a `subjectFrom*` resolver or the server session, never from a request body, an unsigned header, a CLI flag or model output.
+5. **Server and client stay apart.** `policy.ts` and `createPermDock` never reach a client entry (doctor PD001); clients read snapshots, and a client check is a hint the server repeats.
+6. **Portable first.** Conditions that the in-memory evaluator, `where()` and RLS all understand beat closures.
+7. **The Cloud is optional.** No decision waits on PermDock Cloud; every hosted feature is an interface with an in-process default.
+
+## Workflow
+
+1. **Pick the skill.** Install the one the task needs with `npx skills add ScaleDockHQ/PermDock --skill <name>` (or all of them with `npx skills add ScaleDockHQ/PermDock`, or `pnpm exec permdock skills install` to match the installed package version):
+
+   | Task                                                    | Skill                  |
+   | ------------------------------------------------------- | ---------------------- |
+   | Add PermDock, first guard, limits, plans, CLI checks    | `permdock-wire`        |
+   | Review an app or a pull request                         | `permdock-audit`       |
+   | Agent tool calls, actors, delegation, A2A, WebMCP       | `permdock-agents`      |
+   | Human approval, approvers, quorum, resume               | `permdock-approvals`   |
+   | Named scopes, memberships, ownership, custom roles      | `permdock-tenancy`     |
+   | ORM queries, generated RLS, relationship graphs, parity | `permdock-data`        |
+   | Access tokens, API keys, service accounts, share links  | `permdock-credentials` |
+
+   ✓ The skill for the task is loaded, and `permdock-wire` has run first if the app has no factory file.
+
+2. **Look identifiers up, never guess them.** Read the owning page through the docs MCP (`https://permdock.dev/mcp`, tools `search`, `list_pages` and `get_page`), or append `.md` to any `https://permdock.dev/docs/...` URL. Every public name follows the [naming convention](https://permdock.dev/docs/getting-started/naming).
+   ✓ Each identifier written into the app appears on a docs page or in `node_modules/permdock`.
+3. **Read a decision.** `decide()` returns `{ outcome, denials: [{ reason, ... }], alternatives }`. `reason` is one of the closed list on [decisions](https://permdock.dev/docs/concepts/decisions); `alternatives` are permissions on the same resource the subject does hold. HTTP adapters answer RFC 9457 Problem Details ([errors](https://permdock.dev/docs/concepts/errors)); for the format, defer to the `problem-details` spec skill (`npx skills add ScaleDockHQ/scaledock-skills --skill problem-details`).
+   ✓ Each denial the user asked about is named by its reason.
+4. **Explain an unexpected denial.** Run `permdock.explain(permission, data)` in a test or a script. `trace.denies[0]` is the deny that won (give denies a `name` so it reads as a rule), `trace.allows` the allows it overrode, `trace.skipped` the grants passed over and why ([explain](https://permdock.dev/docs/concepts/decisions#explain)). The trace never reaches the decision log. To preview a plan before acting, `simulate([[permission, data], ...])` returns every decision.
+   ✓ The cause is a named grant, condition or missing input, not a guess.
+5. **Check the project.** Run `pnpm exec permdock doctor` (`--json` for machine output). Each finding has a stable `PD0xx` code and a one-line fix ([doctor](https://permdock.dev/docs/cli/doctor)); the topic skills name the codes for their area.
+   ✓ `permdock doctor` reports no error.
+
+## Verify before done
+
+- [ ] No identifier was written from memory; each one is on a docs page or in the package.
+- [ ] Nothing reads a subject, tenant, membership or approval token from model output, a request body or an unsigned header.
+- [ ] `policy.ts` is imported only from server code.
+- [ ] The topic skill used for the task has its Verify list passing.
+
+## Reference index
+
+- Skills: `permdock-wire`, `permdock-audit`, `permdock-agents`, `permdock-approvals`, `permdock-tenancy`, `permdock-data`, `permdock-credentials`, all from `npx skills add ScaleDockHQ/PermDock --skill <name>`.
+- Docs: [for AI agents](https://permdock.dev/docs/for-ai-agents), [naming](https://permdock.dev/docs/getting-started/naming), [policies](https://permdock.dev/docs/concepts/policies), [decisions](https://permdock.dev/docs/concepts/decisions), [threat model](https://permdock.dev/docs/security/threat-model), [doctor](https://permdock.dev/docs/cli/doctor), `https://permdock.dev/llms.txt`.

package/skills/permdock-agents/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: permdock-agents
+description: Guards AI agent tool calls with PermDock subjects, actors and delegation. Use when wiring tool maps in permdock/ai-sdk, permdock/claude-agent, permdock/openai, permdock/eve or permdock/mcp, separating the user (principal) from the agent (actor), declaring a delegation option or policy delegations, publishing an A2A Agent Card with permdock/a2a, registering WebMCP tools with permdock/webmcp, verifying Web Bot Auth signers as actors, or when agent calls are denied with no-delegation or not-delegated.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.dev/docs/security/delegation
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock agents
+
+An agent call has a principal (the user whose grants are evaluated), an actor (the agent making the call) and a delegation (what the user handed over). The decision is the principal's grants intersected with the delegation ([delegation](https://permdock.dev/docs/security/delegation)). Set up `permissions.ts`, `policy.ts` and the factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+
+## Inputs (find out, or ask before starting)
+
+- Runtimes in use: AI SDK, Claude Agent SDK, OpenAI Agents SDK, Eve, an MCP server, an A2A agent, WebMCP tools in a web page, signed bot traffic over HTTP.
+- Where the principal comes from: the host session, a verified token, the runtime's session (Eve).
+- Where the actor id comes from: runtime context, `authInfo.clientId`, an Agent Card, a request signature.
+- What the user delegates, per call (scopes, `authorizationDetails`, GNAP `access`) or as standing policy ("members let the Eve agent read and update posts").
+- Which tools are destructive or move money.
+
+## Invariants
+
+1. Subject and actor come from the host session or verified transport auth, never from tool arguments, a task body, a header the client sets, or model output.
+2. An actor with no delegation is denied every check with `no-delegation`. Delegate explicit scopes, never the principal's whole role.
+3. Delegation only narrows. A policy delegation is a ceiling, a token delegation on the same call must also cover the permission, and a `deny` or an `approval` still applies.
+4. One permission per tool. An instance action loads its row through `data` from parsed arguments; a collection permission (`list`, `create`) on a handler that reads `args.id` is a bug.
+5. Tool lists are hints. `capabilityMiddleware`, `guardTools`, MCP list filtering, the A2A extended card, `mayUse` and WebMCP registration hide tools; the server adapter still decides each call.
+6. A failed Web Bot Auth signature throws `InvalidSignatureError`; it never becomes an anonymous actor.
+7. Protocol rules come from the spec skills (`npx skills add ScaleDockHQ/scaledock-skills --skill <name>`): `mcp-authorization` for MCP auth, `a2a` for Agent Cards, `webmcp` for page tools, `web-bot-auth` for signatures, `owasp-agentic` for the threat checklist.
+
+## Workflow
+
+1. **Name the three parts per surface.** Write down the principal source, the actor source and the delegation source for each runtime from the Inputs. The adapter table on [delegation](https://permdock.dev/docs/security/delegation#how-adapters-fill-actor-and-delegation) shows what each adapter fills itself (MCP and A2A read token scopes; in-process runtimes take a `delegation` option).
+   ✓ Every surface has all three, and none reads from model-controlled input.
+2. **Map the tools.** Use the runtime's `createPermDock` with `subject`, `actor` and a `tools` map, and pass the returned hook to the runtime. -> [references/runtimes.md](references/runtimes.md)
+   ✓ Every tool the agent can call has a `permission`, and every instance permission has a `data` loader that parses its arguments.
+3. **Delegate.** Per call, return `{ scopes: [permissions.post.update.scope] }` (or `authorizationDetails`) from the `delegation` option. As standing policy, declare it once on the policy:
+
+   ```ts
+   definePolicy(permissions, {
+     roles: [member],
+     delegations: [
+       {
+         from: roles.member,
+         to: actor("eve"),
+         permissions: [permissions.post.read, permissions.post.update],
+       },
+     ],
+     subject,
+   });
+   ```
+
+   `from` takes a role, `authenticated()`, a plan or `assurance()`. `to` is an actor kind, or `{ kind, id }` for one agent. A permission outside the ceiling is denied with `not-delegated`.
+   ✓ The agent is granted a delegated tool, and denied with `not-delegated` or `no-delegation` for anything else.
+
+4. **Gate destructive tools.** Put `approval: { by }` on each destructive or money-moving grant and pass a `store` to the adapter. Follow the `permdock-approvals` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-approvals`).
+   ✓ A destructive tool returns the runtime's approval outcome instead of running.
+5. **Wire the agent-facing surfaces.** A2A: serve `agentCard()` publicly, `extendedAgentCard(auth)` behind auth, and `protectSkill` on the task endpoint. WebMCP: `registerTools` from a snapshot, with the server re-checking. Web Bot Auth: `webBotAuth: (request) => verifyWebBotAuth(request, { verify: true, keys })` on the HTTP adapter. -> [references/runtimes.md](references/runtimes.md)
+   ✓ Each surface passes the Verify list of its spec skill.
+6. **Test.** Add scenario tests with `permdock/testing` for one delegated grant, one `not-delegated` denial and one approval per destructive tool ([scenario testing](https://permdock.dev/docs/guides/scenario-testing)). Then review with the `permdock-audit` skill, which reports ASI02 and ASI03 per adapter.
+   ✓ The tests pass and the audit has no blocker.
+
+## Verify before done
+
+- [ ] No `subject`, `actor`, tenant or approval token is read from tool arguments, a task body or model output.
+- [ ] Every in-process agent adapter sets `delegation`, or a policy `delegations` entry covers its actor kind.
+- [ ] Every instance tool has a `data` loader; no collection permission guards a handler that reads one row.
+- [ ] MCP servers set `resource` to their own URL; Claude Agent `mcp__` tools come only from `mcpSources`.
+- [ ] WebMCP and capability filtering are backed by a server-side check on the same permission.
+- [ ] Every destructive tool returns `approval-required`, and the `permdock-approvals` Verify list passes.
+
+## Reference index
+
+- [references/runtimes.md](references/runtimes.md): factory shapes and outcome mapping for AI SDK, Claude Agent SDK, Eve, OpenAI Agents SDK, MCP, A2A, WebMCP, Web Bot Auth and `permdock/terminal`.
+- Docs: [delegation](https://permdock.dev/docs/security/delegation), [subject](https://permdock.dev/docs/concepts/subject), [OWASP Agentic mapping](https://permdock.dev/docs/security/owasp-agentic), adapter pages under `https://permdock.dev/docs/adapters/<name>`.