@agenticprimitives/devkit 0.0.0-alpha.1

package/rules/demo-person-org-distinct.md

@@ -0,0 +1,40 @@
+# A demo person is never also their organization
+
+**Applies to every demo identity** in this repo and every derived roster (`engage`, `skills`, `uupg`).
+
+## One sentence
+
+A Person Smart Agent and an Organization Smart Agent are different classes (ADR-0046). **Never
+point both labels at the same address** — not as a seed shortcut, not “his own SA”, not to make
+`isOperator(address)` cheaper.
+
+## Why this keeps getting re-derived
+
+An org that is “just the person” skips a deploy. The operator check then compares the caller to
+that one address and everything goes green. Home’s workspace switcher then walks the person as
+if they were a parent org (`you → unnamed → unnamed → workspace`), Gather27 treats David’s
+home as Gather, and stewardship/vault gates cannot tell custody of a person from custody of
+an org.
+
+The check that would have caught it is “are these two addresses equal?” — not “does the demo
+sign in.”
+
+## The pattern
+
+1. **Person SA** = the human demo identity (`alice`, `david`, …).
+2. **Org SA** = a second, deployed account the person *custodies*. Named. Own vault.
+3. **Stewardship** = `org → person` (and Home’s related-orgs link). Custody of the org’s
+   key is not the org.
+4. Operator / allow-lists compare the **person** address (or a dedicated operator list),
+   never reuse the org field.
+
+```ts
+// ❌ BAD — one address, two classes
+{ handle: 'david', sa: '0xfd13…', org: '0xfd13…', orgName: 'Gather' }
+
+// ✅ GOOD — Alice already looks like this
+{ handle: 'alice', sa: '0xc35c…', org: '0xe261…', orgName: 'Missio Nexus' }
+```
+
+Roster of record: [`demo/personas.json`](../../../demo/personas.json).
+Enforced by `pnpm check:demo-person-org-distinct`.

package/rules/external-registry-integrations.md

@@ -0,0 +1,15 @@
+# External Registry Boundary
+
+Agentic Primitives builds its own Ring 0 intent, discovery, registry, and agent-card standards in `packages/*`, `apps/contracts`, and `specs/*`.
+
+Integrations with ERC-8004, GoDaddy ANS, Hashgraph/HCS registries, DNS-AID, OASF, Veramo, hosted discovery APIs, indexers, explorers, and registry publication/sync services belong in external repos that import `@agenticprimitives/*`.
+
+Do not add protocol-specific integration code, conformance adapters, registry clients, publication flows, hosted-service wiring, or external protocol vocabulary as package semantics inside primitive packages or contracts.
+
+It is acceptable to study those systems and port generic design principles: signed cards, binding proofs, registry lifecycle, skill claims, validation hooks, transparency logs, fee-gated inboxes, and discovery metadata. When doing so, express them as AP-native primitives with AP-native vocabulary and stable extension points.
+
+Default direction:
+
+- Build AP-native signed agent cards, registry-kit contracts, skill/attestation schemas, intent/resolution/matching primitives, and fulfillment evidence in this repo.
+- Put ERC-8004/ANS/HCS/DNS/OASF/MCP Registry bridges and publication adapters in sibling integration repos.
+- If a feature name or type only exists to satisfy one external protocol, route it out of Ring 0.

package/rules/hard-rules.md

@@ -0,0 +1,50 @@
+# Hard rules (root CLAUDE.md)
+
+- **Smart Agent address is the canonical identifier.** Every person, org, service agent, and treasury IS its ERC-4337 SA address. Names, profiles, ERC-8004 entries, ANS handles, HCS topics — all facets pointing AT the canonical address. Cross-package APIs take `Address`, not names. See [ADR-0010](docs/architecture/decisions/0010-smart-agent-canonical-identifier.md) + [spec 220](specs/220-agent-identity-bootstrap.md) for the bootstrap process (deploy → forced-unique name → custody → optional facets).
+- **Every Smart Agent is a Person, an Organization, or a Service — nothing else.** PROV-O's trichotomy (`prov:Person`/`prov:Organization`/`prov:SoftwareAgent`), mirrored by `AgentType = 'person' | 'org' | 'service'` in `@agenticprimitives/types`. Treasury, indexer, relay, marketplace, data-source are **Service roles** (profile `serviceType` / app-level kinds), never new classes; UI groups by class and labels by role; app kinds map DOWN to a class, never up into the enum ([ADR-0046](docs/architecture/decisions/0046-agent-classification-person-org-service.md), specs 217/225 §6). **A demo person SA is never also their org SA** — do not reuse “his own SA” as the organization ([agent-rules/demo-person-org-distinct.md](docs/architecture/agent-rules/demo-person-org-distinct.md), `pnpm check:demo-person-org-distinct`).
+- **Canonical identity persists; credentials rotate.** Passkeys, SIWE EOAs, hardware wallets are control credential facets — replaceable, not the identity. Credential add / replace / remove is a custody-policy-governed operation (trustee quorum, guardian quorum, multi-credential self-recovery, or multi-sig), NEVER a delegation. The SA address NEVER changes during credential recovery. Delegations issued by the SA remain valid after rotation. See [ADR-0011](docs/architecture/decisions/0011-credential-recovery-and-re-association.md) + [spec 221](specs/221-credential-recovery.md).
+- **Specs precede non-trivial code.** New `specs/2XX-*.md` before architecture changes; the spec is the architect-of-record.
+- **Always check smart-agent first.** Before designing any non-trivial capability look at the analog in `/home/barb/smart-agent`. New specs MUST include a "Reference: smart-agent patterns to port" section. Deliberate divergence must say why.
+- **Package boundaries** are one-directional: `types ← identity-auth ← agent-account ← delegation ← mcp-runtime`, plus `key-custody → delegation`, `tool-policy → mcp-runtime`, and the custody-layer fork `types ← custody` (depended on by `agent-account` and `delegation`; see [spec 213](specs/213-custody-layer-carve-out.md) for the firewall). No back-edges. `tool-policy` and `types` are transport-agnostic (no MCP/A2A/LangChain/Vercel imports).
+- **`AgentAccount.sol` is an ERC-7579 modular core — custody governance is a module; sessions + spend are inlined in v1 (ARCH-H4, honest state).** The custody surface (threshold / guardians / recovery / approvals) IS an installed EXECUTOR module (`CustodyPolicy`), and account-governance ops route through it (spec 300). But session acceptance and spend limits are currently INLINED in `AgentAccount.sol` (spend exists only as a delegation-layer caveat, not an account hook), and `MODULE_TYPE_FALLBACK` is unsupported — so the "everything is a module" framing is aspirational for those two. The direction (extract `SessionKeyValidator`, then a spend hook) stands, but do NOT assert sessions/spend are already modules. `specs/209` is the taxonomy target of record; when extracting a module, update it + this rule together. See memory `feedback_erc7579_module_architecture`.
+- **HTTPS is required; mTLS is optional; admission is always required.** The normative external profile is A2A over HTTPS. mTLS is *additive transport evidence* on a separate hostname (`mtls.<host>`) — it never establishes owning person, organization, canonical agent, relationship, delegation, purpose, capability, consent, or policy, and never lets a request skip a stage. SPIFFE is an optional workload binding, not identity: which agent a workload may act as is a signed `WorkloadIdentityBinding`, never an inference from a trust-domain path. MCP is a PRIVATE capability interface behind an admitted runtime, absent from every Agent Card (`demo-mcp`'s public `/mcp`+`/mcp/native` are a labelled, deliberately non-conformant interop demo). Optional transports, brokers and workload-identity systems are leaf bindings that depend INWARD; core never depends outward. Ordering that must never invert: `certificate → transport evidence → optional workload binding → application authentication → canonical resolution → Admission` ([ADR-0057](docs/architecture/decisions/0057-a2a-over-https-admission-mtls-optional.md) + [spec 339](specs/339-agentic-primitives-edge-https-admission.md); gate `check:optional-package-boundaries`).
+- **DO-local storage is a SERVING-PLANE concern; the vault is the RECORD.** Durable Object storage
+  (`state.storage` / `state.storage.sql`) exists for ordering, cursors, receipts, request-id ledgers,
+  projections and caches — things that are derived, rebuildable, and needed at request latency. It MUST
+  NOT become the home of durable private records, message bodies, grants, or any self-sovereign data.
+  Those live in the owner's vault behind demo-mcp, where per-record delegation scope is enforced
+  (ADR-0055). **The drift to refuse is DO-local quietly becoming the person/org vault store** — it
+  arrives as a performance argument and leaves you with a second enforcement point, a second authority
+  model, and records nobody can carry to another Home. The test for any new DO table: *if this DO were
+  wiped, is the loss a rebuild or a bereavement?* A rebuild is fine; a bereavement means it belonged in
+  the vault. Applies to `InteractionsDO` and to `PrincipalGatewayDO` alike — the latter constructs a
+  DO-SQL vault internally, which is why an app MUST inject the MCP-backed one rather than inherit it
+  from a constructor ([ADR-0055](docs/architecture/decisions/0055-vaults-are-the-canonical-system-of-record-for-content.md)).
+- **Define the capability model ONCE; generate the UX behaviour AND the agent surfaces from it.** Never
+  build the UX and then separately teach Ask how the application works. The Ask in Home drives everything
+  the Home UX drives because both are projections of one semantic definition: the **ontology** (how the
+  domain is shaped) + the **capability** (ADR-0051 id + label — what the agent advertises) + the
+  **SKILL.md execution contract** (`SkillExecutionContractV1` — risk, requirement type, `resourceArg`/
+  `authorityArg`, approvals, evidence, spec-360 `effects`), joined by the `~/skills` compiler into an
+  `AgentHarnessDefinitionV1` and consumed — never authored — here. From that one model come the Ask's tool
+  set, the published vocabulary, the A2A card skills, each act's mandate requirement and risk floor, what
+  follows the act, and the Home affordance. **If adding a feature means writing an invoker AND a vocabulary
+  entry AND a UI handler, the model is not doing its job.** The bugs this is made of: a Treasury playbook
+  that promised "every payment leaves a receipt" into a field nothing read, so money moved and neither
+  party was told; and `skills:includesSkill` compiled from a hand-kept `CAPABILITY_PROFILE` table instead
+  of the contract a domain author wrote. **Behaviour is generated; authority never is** — a generated
+  surface is consulted by no verifier (spec 354 §1 / ADR-0041). Hand-adding a `CAPABILITY_PROFILE` row is
+  the anti-pattern; the fallback warns per capability so it stays visible.
+  ([agent-rules/one-capability-model-generates-both.md](docs/architecture/agent-rules/one-capability-model-generates-both.md), specs 354/355/359)
+- **Domain relationships live in the ONTOLOGY, not in prompts, SKILL.md files or app tables.** A claim about how the domain is shaped — "a treasury belongs to the agent that holds it", "an inbox belongs to a person", "an organization pays from its own balance" — goes in `packages/ontology/tbox/*.ttl` with a comment saying what it means and what it is NOT, and code binds to it BY IRI (`packages/ontology/src/party-roles.ts`). `pnpm check:ontology-bindings` fails the build when an IRI is not declared in the T-box or is the wrong kind: the code may not invent domain vocabulary. **A string-similarity heuristic standing in for a modelled relationship is the specific failure this prevents** — the Ask once looked for a treasury whose NAME resembled its owner's (`alice` → `alice.treasury`), which the ontology never claimed and the estate does not do, so paying "alice" dead-ended because hers is `alice2.treasury`. A planner prompt is the most tempting place to write a domain rule and the worst place to keep one: prompts say how to BEHAVE, the ontology says how the world is SHAPED, and prompt text should be rendered from the binding ([spec 355](specs/355-ontology-driven-ask-and-orchestration.md) + [agent-rules/ontology-drives-behavior.md](docs/architecture/agent-rules/ontology-drives-behavior.md)).
+- **No third-party multi-sig.** We ship our own; port patterns from Safe (signature packing) but no runtime deps.
+- **Per-package context budget:** `CLAUDE.md` ≤ 60 lines, `AUDIT.md` ≤ 150 lines, `README.md` ≤ 1800 words. If you're tempted to bloat one, fix the package shape.
+- **No `eth_getLogs` in product read paths.** Package and app hot paths use `readContract` only; chain history and human-readable reverse strings come from on-chain storage, an explicit indexer, or app cache — never inline log scans ([ADR-0012](docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md)). No exceptions: the last walker (`agent-naming` `reverseResolve` log fallback) was removed once spec/222 `reverseResolveString` landed.
+- **No silent fallbacks.** A read/auth path has exactly ONE mechanism. If the canonical path has no answer it returns `null`/empty or throws — it does NOT escalate to a second, different, more expensive mechanism (`try fast catch slow`, empty-result → log walk, strong-check → weak-check). Empty is an answer, not a trigger. Bounded retries of the *same* call and cache-first reads (cache holds the canonical answer) are fine; switching mechanism is not ([ADR-0013](docs/architecture/decisions/0013-no-silent-fallbacks.md)).
+- **The discovery knowledge base holds ONLY public, on-chain-derivable data.** The GraphDB A-box (projected by `demo-discovery-indexer`, read by `demo-discovery-mcp`/`-a2a`) is a world-readable read tier — populate it ONLY with facts any party could reproduce from on-chain state, transactions, or event logs (naming, registry entries, profile, relationships, attestations, custodian/passkey membership from `CustodianAdded`/`PasskeyAdded` logs). NEVER per-viewer state, session/credential secrets, off-chain/relying-app-local data, vault contents, PII, or private linkage ([ADR-0025](docs/architecture/decisions/0025-related-agents-are-private-vault-credentials.md)) — not even hashed, not even temporarily, not even to make a check faster. No secret-derived rows: any opaque form (e.g. custody membership as `sha256(credential‖smartAgent)`) MUST be a public, unsalted, on-chain-*reproducible* function — no server pepper. The indexer is the only writer; consumer services MUST NOT write viewer-/request-derived facts back. The claim: reading the whole KB reveals nothing reading the chain wouldn't ([ADR-0040](docs/architecture/decisions/0040-knowledge-base-only-public-onchain-data.md)).
+- **On the A2A→MCP hop, Web3 is the authority; MCP OAuth is only the ingress envelope.** When an A2A service agent calls an MCP service, the authorization decision is ALWAYS the Web3 chain — on-chain delegation + signature validation (ERC-1271/6492/ECDSA/WebAuthn via `UniversalSignatureValidator`) + entitlement + tool policy (+ key-release grant + audit for data) — re-run server-side against the principal SA. We ship MCP's OAuth (RFC 9728 bearer / protected-resource metadata) as a generic ingress *adapter* so external MCP clients interoperate, but the bearer is at most a transport envelope: it carries only `ap_principal` + a `ap_grant_ref`/`ap_grant_hash` to an encrypted grant bundle, NEVER delegation/entitlement payload or field-level authority. Do NOT let OAuth drift inward: field/record access is never encoded in scopes (`vault:read` ≠ "decrypt all PII"), OAuth claims (`scope`/`aud`/`client_id`) are never trusted *as* the grant, an inbound MCP token is never reused for the next hop (fresh token / RFC 8693 exchange), and the Web3 gates are never skipped because "OAuth already authenticated the caller." For internal A2A→MCP hops the public OAuth ingress may be absent/skipped (the A2A bridge handles MCP tokens server-side, never exposing them downstream) — the delegation+signature+entitlement+policy gates are not. One mechanism (ADR-0013): OAuth-fail rejects, it does not fall back to a weaker token-trust path. When the standard and the substrate conflict, the substrate wins. ERC-4337 SA-bound, signature-verified, on-chain-revocable delegation is our differentiator from OAuth — never trade it for an opaque issuer-granted scope ([ADR-0041](docs/architecture/decisions/0041-web3-authority-not-oauth-on-a2a-to-mcp.md) + [spec 277](specs/277-mcp-delegated-vault-authorization.md) + [spec 269](specs/269-async-delegation-authorized-a2a.md) + [spec 270](specs/270-del-001-activation.md)).
+- **Agentic architecture: first-party web expresses INTENTS to an A2A agent; it NEVER drives MCP directly.** A2A is the orchestration / intelligence / discovery layer — it discovers which capability satisfies a declarative goal, plans (planner/LLM/LangChain), assembles authority (delegation/entitlement), and composes MCP tools AS PRIMITIVES. A first-party UI (demo-web-pro, demo-sso-next) says "rebalance the treasury" / "read Alice's PII for purpose X" — a goal, not a tool name, payload, or call sequence — and posts it to an a2a agent. **`web → (edge) → MCP /tools|/mcp|/mcp/native` directly is the anti-pattern (RPC with extra steps) for first-party apps.** The public MCP ingress (`/mcp`, `/mcp/native`) is interop for EXTERNAL agents/clients only; the Act6 OAuth/Native panels are external-MCP-client *demonstrations of a primitive*, NOT a product-UX model (keep them labelled as such). **Orchestration is a Ring-0 primitive, not external** — the agentic loop (intent→plan→compose→observe→re-plan), the planner/reasoner PORT, and the tool/skill model live in a pure `packages/*` orchestration core; ONLY the concrete LLM-framework binding (LangChain/OpenAI/Anthropic SDK) lives in a dedicated in-repo adapter behind the port — the `chain-state` + `chain-state-viem` pattern (ADR-0037 exiles protocol-conformance + deployed-infra, NOT libraries). `service-agent` stays the deterministic compile/run target; the Ring-0 orchestration core PRODUCES its plans. Apps wire model creds/config; they don't re-implement the loop. The edge is orthogonal: it admits, it does not orchestrate (ADR-0043). Honest tension: the first-party web↔a2a surface is RPC-shaped TODAY (`/session/*`, `/account/*`, `/mcp/person/pii` — verbs); the intent layer (A2A messages/tasks against `A2aTaskDO` + `service-agent` plans) is the objective — build NEW first-party surfaces intent-first; the relayer verbs are legacy. Enforced by review + `check:no-direct-mcp-in-web` (browser-app source; allowlist the labelled external-client demo panels) ([ADR-0044](docs/architecture/decisions/0044-a2a-is-the-agentic-orchestration-layer.md) + [docs/architecture/principles.md](docs/architecture/principles.md)).
+- **Packages are GENERIC trust building blocks; white-label / vertical / deployment code lives in apps.** `packages/*` are reusable + vertical-agnostic. They MUST NOT contain (a) **branding / vertical content** — faith vocabulary (ministry, congregation, discipleship, parish, denomination, gospel, scripture — **`church`/`circle` are the one carve-out: Ring-0 derived AGENT TYPES since 2026-08-30, ADR-0061 amendment; the KIND is generic, the content is not**), white-label/product names, marketing copy, themes; (b) **vertical-specific flows** — faith onboarding steps, impact-portal features; (c) **deployment specifics** — concrete hostnames (`impact-agent.me`/`.io`), the `demo.agent` subregistry, hosting providers (`*.pages.dev`/`*.workers.dev`/`vercel`), host/subdomain parsing. All of that is the **app** layer's job, supplied as an **app-level white-label config object** (spec 234) the generic core consumes. The `.agent` TLD itself is the naming protocol (owned by `agent-naming`) and is allowed. Enforced by `pnpm check:no-domain-in-packages` (hostnames + `demo.agent` + faith vocab) + `check:forbidden-terms`; the rest is doctrine ([ADR-0021](docs/architecture/decisions/0021-generic-packages-vs-white-label-apps.md)). Each app centralizes its domain/white-label literals in one module (e.g. `src/lib/domain.ts`), never scattered.
+
+- **Many-registries hypothesis: be what registries are built FROM, not a tenant of one.** Hundreds of (mostly vertical) agent registries will exist; no horizontal winner. Ring 0 ships a generic **registry kit** — SA-anchored registry contracts with pluggable membership/validation hooks, discovery/registry SDK, signed agent-card + binding-proof standards — drawing concepts from ERC-8004/HCS as design inputs, never conformance targets. Specific registries (vertical or 8004/ANS/HCS bridges) are external consumers of the kit ([ADR-0038](docs/architecture/decisions/0038-many-registries-hypothesis-registry-building-primitives.md)).
+- **This repo is Ring 0: primitives only. Integration + product-UX layers live in EXTERNAL repos.** Code that speaks someone else's protocol (ERC-8004 sync, ANS/DNS, HCS/UAID, OASF, Veramo) or runs as deployed infra (indexer, discovery API, explorer) belongs in sibling repos (`agentic-trust`, `agent-indexer`, `agent-explorer`, `oasf`) that import `@agenticprimitives/*` — never the reverse. Ring 0's job is expressive extension points (SA-signed cards, attestation schemas, complete events), not bridges. Learn from ERC-8004/HCS/sibling repos; port *primitive* patterns in, route *conformance* code out ([ADR-0037](docs/architecture/decisions/0037-primitives-pure-repo-external-integration-and-ux-layers.md)).

package/rules/one-capability-model-generates-both.md

@@ -0,0 +1,82 @@
+# One capability model. Generate the UX and the agent surfaces from it — never teach them separately
+
+**Canonical rule — all agents.** Specs: [354](../../../specs/354-archetype-driven-agent-behavior.md)
+(playbooks), [355](../../../specs/355-ontology-driven-ask-and-orchestration.md) (ontology drives
+behaviour), [352](../../../specs/352-ask-capability-program.md)/[353](../../../specs/353-app-scoped-ask.md)
+(the Ask). Gates: `pnpm check:agent-skills`, `pnpm check:ontology-bindings`.
+
+## The rule
+
+> **Define the application's capability model ONCE. Generate both the UX behaviour and the agent
+> skill/discovery surfaces from that same semantic definition.**
+>
+> **Never build the UX first and then separately teach Ask how the application works.**
+
+The Ask in Home must be able to drive **everything the Home UX can drive** — and that equivalence is not
+achieved by writing the feature twice. It is achieved because both are projections of one model:
+
+| Layer | What it is | Who owns it |
+| --- | --- | --- |
+| **Ontology** (`packages/ontology/tbox/*.ttl`) | how the domain is SHAPED — the classes, the relations, the record bindings | this repo, bound by IRI |
+| **Capability** (ADR-0051 id + label) | what the agent ADVERTISES it can do — the branding/discovery half | the domain's Build → Capabilities |
+| **SKILL.md execution contract** (`SkillExecutionContractV1`) | HOW it runs — risk, requirement type, which arg carries the resource, which arg names whose authority, approvals policy, evidence, effects | the domain's Build → Skills |
+| **Compiled definition** (`AgentHarnessDefinitionV1`) | the two joined, by digest | `~/skills` compiler; consumed, never authored, by this repo |
+
+From that one model come **all** of:
+
+- the **Ask's tool set** (`scopedActionTools` ∩ the playbook's capability ids),
+- the **published vocabulary** a surface builds its scope from (`/harness/vocabulary?agent=`),
+- the **A2A agent card** skills and the discovery projection,
+- the **mandate requirement** each act asks for, and the **risk floor** it cannot go under,
+- **what follows the act** (spec 360 declared effects — the receipt, the notification),
+- and the **UX affordance** in Home.
+
+A button and an ask that do the same thing must be reading the same declaration. If adding a feature
+means writing an invoker *and then* adding it to a vocabulary list *and then* adding a UI handler, the
+model is not doing its job — that triplication is the smell this rule names.
+
+## Why — the bugs this rule is made of
+
+**Money moved and nobody was told.** The Treasury playbook said *"every payment leaves a receipt"* in its
+`evidence:` frontmatter. That compiled into `evidenceRequirements` — and **nothing read that field.** The
+UX had been built (a payment happens) and the declaration was decoration. A person paid another person
+and neither got so much as a message. (Spec 360 §0.)
+
+**The archetype's skills drove nothing.** `skills:includesSkill` was read into `ArchetypeFacts.skills`,
+and `compileArchetype` never referenced it — every runtime shape came from `CAPABILITY_PROFILE`, a
+hand-maintained TypeScript table. The Build → Skills area let a domain author write a contract that no
+running agent would ever consult.
+
+**The cost is quadratic and it compounds.** Membership took a day of hand-built readers, parsers and
+gates; the payment fan-out took a week. The Home spans nine domains. At the artisanal rate — build the
+UX, then teach the Ask, then teach discovery — covering them is quarters of work that competitors ship
+as configuration (spec 359 §0).
+
+## What it looks like when followed
+
+Adding *"notify the payee on transfer"* is an **`effects:` block in a SKILL.md** — not an invoker change,
+not a UI handler, not a new Ask verb. The compiler carries it into the definition, the harness discharges
+it, and the receipt appears in both parties' vaults and their thread.
+
+Reassigning a treasury agent to a read-only Bookkeeper archetype removes payments from **both** the Ask's
+offers and its published vocabulary, with **no code change** and no change to any authority gate.
+
+## The line this rule does NOT cross
+
+**Behaviour is generated; authority never is.** A capability model says what an agent KNOWS HOW to do and
+what a surface may OFFER. It grants nothing. The mandate, its caveats, and the on-chain enforcers decide
+what MAY happen, and no generated surface is consulted by a verifier (spec 354 §1, spec 353 §4,
+ADR-0041). Generating the UX and the agent surfaces from one model makes them *honest about the same
+things* — it must never make either of them *authoritative*.
+
+## How to comply
+
+1. Model the domain fact in the T-box; bind it by IRI (`ontology-drives-behavior.md`).
+2. Declare the capability (id + label) in the domain — the advertisement.
+3. Write the SKILL.md execution contract for the skill that realises it — risk, requirement, args,
+   approvals, evidence, effects. Link it to the archetype (`skills:includesSkill`).
+4. Let the compiler produce the definition. **Do not** hand-add a row to `CAPABILITY_PROFILE`; that table
+   is a fallback for capabilities no skill defines yet, and every use of it emits a warning naming the
+   capability, so the remaining hand-kept rows stay visible rather than quietly permanent.
+5. Consume the definition in the Ask, the vocabulary, the card and the UX. If a surface needs something
+   the definition cannot express, **extend the contract schema** — do not special-case the surface.

package/rules/ontology-drives-behavior.md

@@ -0,0 +1,58 @@
+# Domain relationships live in the ontology, not in prompts or tables
+
+**Canonical rule — all agents.** Cursor mirror: `.cursor/rules/ontology-drives-behavior.mdc`.
+Spec: [355](../../../specs/355-ontology-driven-ask-and-orchestration.md). Gate: `pnpm check:ontology-bindings`.
+
+## The rule
+
+**A claim about how the domain is shaped belongs in `packages/ontology/tbox/*.ttl`, bound by IRI from
+code. It does not belong in a prompt, a SKILL.md, a lookup table in an app, or an inline heuristic.**
+
+If behaviour depends on a fact like *"a treasury belongs to the agent that holds it"*, *"an inbox belongs
+to a person"*, or *"an organization pays from its own balance"* — that fact is ontology. Name the term,
+say in its `rdfs:comment` what it means and what it does NOT mean, then bind to its IRI.
+
+## Why — the bug this rule is made of
+
+The Ask had to turn *"send alice 20 USDC"* into an address. It used a rule nobody had written down: **look
+for a treasury whose NAME resembles the person's** — `alice` → `alice.treasury`.
+
+Nothing in the ontology said that. Nothing in the estate did it either: Alice's treasury is called
+`alice2.treasury`. The guess found nothing, and a payment that should have worked dead-ended with a
+question the person could not answer.
+
+The real relationship — *the treasury is chartered under the person who holds it* — existed as a `parent`
+field in one app's records, a suffix table in another, and a sentence in a prompt. Three encodings of one
+fact, none of them checkable against each other, and the one the resolver used was wrong.
+
+**A string-similarity heuristic standing in for a modelled relationship is the specific failure this rule
+exists to prevent.** It is seductive because it works in the demo data and it is unfalsifiable in code.
+
+## How to comply
+
+1. **Model it.** Add the class or property to the T-box with a comment that says what it means, and — for
+   anything near authority — what it is *not*. `ap:charteredUnder` says plainly: never authority; the
+   child holds its own custody; a resolver may follow it, a verifier may not read it as permission.
+2. **Bind by IRI.** Reference it from `packages/ontology/src/party-roles.ts` (or the equivalent binding
+   for your concern), never by re-describing it.
+3. **Let the gate hold you to it.** `check:ontology-bindings` fails the build when an IRI is not declared
+   in the T-box, or is declared as the wrong kind. The code may not invent domain vocabulary.
+4. **Mirror it.** The `~/skills` `agentic-trust` T-box grounds on AP terms; add the `at:` counterpart with
+   `rdfs:seeAlso` and push it to GraphDB (`scripts/sync_ontology.py push`).
+
+## Applies especially to LLM-facing surfaces
+
+A planner prompt is the most tempting place to write a domain rule and the worst place to keep one: it is
+invisible to every gate, it drifts silently, and a model will apply it confidently to cases it was never
+meant for. **Prompts say how to behave; the ontology says how the world is shaped.** When a prompt needs a
+domain fact, it should be rendered FROM the ontology binding (as the Ask's party words and type
+preferences now are), not written into the prose.
+
+## Drift triggers — STOP
+
+- *"Just check if the name starts with…"* — **HARD STOP.** That is a relationship. Model it.
+- *"Add it to the system prompt so the planner knows"* — **STOP.** Add it to the T-box and render the
+  prompt from the binding.
+- *"A table in this app is simpler than a new ontology term"* — it is, once. It is a second opinion about
+  the domain from then on, and this rule exists because one of those was wrong in production.
+- *"The ontology doesn't have a term for this"* — then the term is missing. Adding it IS the work.

package/rules/service-agent-signing.md

@@ -0,0 +1,84 @@
+# Service-agent A2A signing: the key is a DELEGATE, never the identity
+
+**Applies to every service that signs A2A messages as an agent identity** — in this repo and in every
+derived repo (`verifiable-content-demo`, `skills`, and any future one).
+
+## One sentence
+
+A relying service NEVER custodies the agent identity it acts as: the identity is custodied outside
+the service, a **ceremony** mints a narrow **wire** (`identity SA → the service's KMS session key`),
+and the service signs with the session key and presents the wire — so possession of the service's
+credentials can never be possession of the identity.
+→ ADR-0019 · [spec 329 §3.1](../../../specs/329-consultability-and-routing.md) · `apps/demo-a2a/src/session-wire.ts`
+
+## Why this keeps getting re-derived (read this part)
+
+The existing rail — `pnpm check:no-app-private-keys` — stops at *"use KMS, don't hold a raw key."*
+**That check passes for the wrong architecture.** An app can use KMS correctly, hold no raw key, and
+still be the custodian: if the KMS key IS the identity's key, whoever holds the service-account
+credential can sign anything as that identity, forever, with nothing to revoke.
+
+"No held key" is not the property. **"Not the custodian" is the property.** They are not the same
+sentence, and every time only the first one is written down, the second is re-derived — usually
+wrongly, and usually with passing tests.
+
+## The pattern
+
+1. **The identity is custodied outside the service.** A named account (`<name>.impact`) whose
+   custodian is a person or org, reachable through a Home ceremony. Not the relying app.
+2. **A ceremony mints the wire.** The custodian signs `identity SA → the service's KMS session key`:
+   `allowedMethods` = **exactly one** skill selector (never `A2A_ANY_SKILL`), `allowedTargets` pinned,
+   timestamp-bounded. The service stores the wire; it is a credential, not a secret.
+3. **The service signs with the session key and wraps.** `wrapSessionSignature(wire, sig)` →
+   the `0x51` session-wrapped form. The KMS key signs each digest on demand; no raw key at rest.
+4. **The gate verifies per message**, fail-closed: delegator === the claimed signer, wire live,
+   one selector matching the requested skill, ECDSA recovers to the wire's delegate, wire
+   ERC-1271-valid against the delegator, wire **unrevoked on-chain**.
+
+## What this buys, stated as the difference
+
+| | key IS the identity | key is a DELEGATE (this rule) |
+| --- | --- | --- |
+| custody | the relying service | the named account's custodian, outside it |
+| compromise | you are that agent, for anything, forever | a delegate, only where a wire says so |
+| revocation | re-mint the identity + every grant naming it | the custodian revokes one wire |
+| audit | "the service signed" | "this session key signed under this wire" |
+
+## What it does NOT buy — say this out loud
+
+**The GCP service-account secret does not disappear.** `demo-bible-mcp` and `impact-a2a` both carry
+`GCP_SERVICE_ACCOUNT_JSON` as a wrangler secret, and that is correct. The secret still exists; what
+changes is what it controls — a revocable delegate instead of an identity. Anyone who expects this
+pattern to remove the secret has misread it and will "fix" it back the wrong way.
+
+## Two implementations to copy, not reinvent
+
+- **`verifiable-content-demo`, the content-signer ceremony.** The issuer SA is custodied by its owner;
+  the ceremony signs a leaf `issuer SA → KMS key address`; the corpus service stores it and signs with
+  the key, and a verifier "roots trust in the SA (ERC-1271) while the signer is the HSM key"
+  (`apps/demo-bible-a2a/src/index.ts`).
+- **`demo-a2a`, the session wire.** An org's DO holds no org key; `signAsOrg` signs with the
+  interactions-session KMS key and wraps with the steward-minted wire (`src/session-wire.ts`).
+
+`session-wire.ts` is **skill-agnostic** — pass the skill to pin, never hardcode one. It was
+consult-only for a while, and that is exactly what forced the next service toward custodying its own
+identity because "there was no other path".
+
+## Rules
+
+1. **Never configure a KMS key as the service's own agent identity.** If a service signs as
+   `X_AGENT_SA`, the key it signs with must be a delegate of `X_AGENT_SA`, not `X_AGENT_SA` itself.
+2. **Signing an A2A message as an identity requires a wire.** `hashA2aMessage(...)` + a bare signer,
+   with no wire presented, is the violation. Reviewers: grep for that pair.
+3. **One selector per wire, never `A2A_ANY_SKILL`.** A wire is per-rail. Pin the skill the request
+   names wherever the request names one.
+4. **The wire is stored, the identity is not.** A service may hold wires (they are revocable and
+   narrow). It may never hold anything that grants the identity itself.
+5. **No new signing path without naming its custodian.** If you cannot say who custodies the identity
+   and how they revoke, the design is not finished.
+
+## Before writing any of it
+
+`ls ~/agenticprimitives/packages` and grep the two implementations above. Both problems — the
+ceremony and the wrapped signature — are solved; the cost of checking is two greps, and the cost of
+skipping it has twice been an identity that had to be withdrawn.

package/rules/sidecar.json

@@ -0,0 +1,13 @@
+{
+  "$comment": "Projection metadata per rule in the corpus (399 §3.4): the .mdc frontmatter Cursor reads, and whether the rule has a Cursor mirror today. Bodies come from the source; this file never carries rule text.",
+  "coordination-vs-orchestration": { "description": "Coordination (between agents, discovery, capability level) vs orchestration (within agent, SKILL.md + tools)", "alwaysApply": true, "cursor": true },
+  "demo-person-org-distinct": { "description": "A demo person SA is never also their organization SA (ADR-0046)", "alwaysApply": true, "cursor": true },
+  "external-registry-integrations": { "description": "Keep external registry integrations out of primitive packages", "alwaysApply": true, "cursor": true },
+  "ontology-drives-behavior": { "description": "Domain relationships live in the ontology T-box, not in prompts or app tables (spec 355)", "alwaysApply": true, "cursor": true },
+  "service-agent-signing": { "description": "Service agents sign with a DELEGATE key under a ceremony-minted wire — never custody the identity they act as (ADR-0019)", "alwaysApply": true, "cursor": true },
+  "skill-terminology": { "description": "Capability as canonical noun; qualify every standards-specific \"skill\" (ADR-0050, ADR-0051)", "globs": ["**/*"], "alwaysApply": true, "cursor": true },
+  "vault-and-ontology": { "description": "Prefer vault-backed authority and standards-based ontology patterns", "alwaysApply": true, "cursor": true },
+  "one-capability-model-generates-both": { "description": "Define the capability model once; UX behaviour and agent surfaces are generated from it (specs 354/355/359)", "alwaysApply": true, "cursor": false },
+  "vault-records-are-ontology-shaped": { "description": "Vault records are ontology-shaped: record keys bind to T-box classes by IRI", "alwaysApply": true, "cursor": false },
+  "hard-rules": { "description": "The root CLAUDE.md hard rules (canonical identifier, no silent fallbacks, generic packages, web → A2A, vault is the record)", "alwaysApply": true, "cursor": false }
+}

package/rules/skill-terminology.md

@@ -0,0 +1,76 @@
+# Capability terminology (ADR-0050 + ADR-0051)
+
+**Capability** is the stable semantic noun. Bare **skill** is ambiguous — always qualify.
+
+## One sentence
+
+OASF skills **classify** capabilities; A2A AgentSkills **advertise** capabilities; Agent Skill packages **implement** procedural knowledge for capabilities.
+
+## Layer map
+
+| Layer | Term | Standards object |
+| --- | --- | --- |
+| Canonical | **CapabilityDefinition** | AP-owned semantic outcome |
+| Classification | **OASF skill taxon** | OASF record taxonomy |
+| Advertisement | **A2A AgentSkill** / **A2A advertised capability** | Agent Card `skills[]` |
+| Playbook | **Agent Skill package** / **SKILL.md package** | Agent Skills standard |
+| Operation | **MCP tool** | Typed executable invocation |
+| Credential | **capability claim** / **SkillClaimCredential** | Private VC (spec 251) |
+
+## Packages
+
+| Package | Meaning |
+| --- | --- |
+| `@agenticprimitives/capability-claims` | Capability claim VCs + vocabulary types |
+| `@agenticprimitives/agent-skills` | **Deprecated alias** — re-exports `capability-claims` |
+
+`@agenticprimitives/capability-claims` is **not** Agent Skill packages (`SKILL.md`).
+
+## Ontology
+
+| Namespace | Canonical | Deprecated alias |
+| --- | --- | --- |
+| `aps:` | `CapabilityDefinition`, `CapabilityGrounding` | `AgentSkillDefinition`, `SkillGrounding` |
+| `apguide:` | `AgentSkillPackage` | `AgentGuidanceSkill` |
+
+## Style rule
+
+Outside code implementing a particular standard's types, **skill must have a qualifier**.
+
+| Avoid | Use |
+| --- | --- |
+| register the skill | register the **OASF skill taxon** / publish the **A2A AgentSkill** |
+| load the skill | load the **Agent Skill package** |
+| verify the skill | verify the **capability claim credential** |
+
+## UI
+
+Prefer **Capabilities** with sub-sections: advertised, classifications, runtime playbooks, operations, credentials.
+
+**Source:** ADR-0051, vocabulary-map.md, spec 325 §2.2 (see agent-rules/README.md).
+
+## The advertisement layer is CAPABILITY (ADR-0051, 2026-09-01)
+
+Three names. One meaning each. They are not interchangeable and the collision between them is the whole
+reason this rule exists.
+
+| Name | What it is | Where the word `skills` is allowed |
+| --- | --- | --- |
+| **Capability** (`AdvertisedCapabilityV1`) | What the agent CAN DO. The word in the profile, the vault, on chain, in discovery, in every UI. | — |
+| **Protocol features** (`ProtocolFeatureSetV1`) | A2A's streaming / push / extensions flags. The wire calls this object `capabilities`, which is the collision. | — |
+| **Agent Skill package / playbook** | SKILL.md procedural guidance for a harness. | — |
+
+`skill` without a qualifier means **playbook only**. `skills[]` is A2A's name for capabilities and is
+legitimate in exactly two places: `@agenticprimitives/agent-profile/a2a` (the wire types and the projector
+that writes them) and a raw-JSON inspector showing a steward the literal document. Anywhere else it is a
+defect. Enforced by `pnpm check:capability-vocabulary`.
+
+**The system of record is `profile.capabilities[]`.** The A2A card's `skills[]` and ARD's `capabilities[]`
+are projections of it; the A2A projector is their only writer. On chain the record is `atl:capabilities`
+(ids only — the chain proves WHICH capabilities are claimed, not their prose). `atl:skills` is that same
+rail under its old name: read when the new one is empty, never written. That is a documented migration,
+not a fallback (ADR-0013) — same contract, same owner, same value, only the key moved.
+
+What this replaced, and why it mattered: the card editor had a section titled **Capabilities** holding
+protocol flags, next to one titled **Skills** holding what the agent can do. Backwards twice over, in the
+one screen where a steward decides what the world sees.

package/rules/vault-and-ontology.md

@@ -0,0 +1,8 @@
+# Vault Storage And Ontology
+
+- Do not introduce app-local persistent storage for durable authority state when a vault-backed record or Agentic Primitives rail should own it. This includes membership, invitations, roles, reports, relationships, attestations, discussions, messages, onboarding state, and access decisions.
+- Treat D1, KV, R2, Durable Objects, local JSON, and app-specific ledgers as caches, indexes, queues, or runtime infrastructure only. Durable domain truth belongs in person/org/service vault records, Home/a2a rails, MCP vault records, chain state, or package-owned canonical stores.
+- Model onboarding and membership with standards-aligned situations: pending invite/request situation first, then approved/accepted membership or role situation. Approval writes canonical relationships, delegations, entitlements, rosters, attestations, or vault records.
+- Smart Agent address is the canonical identifier. Agent names, email addresses, display names, handles, registry entries, and UI labels are facets used for lookup/contact, never canonical membership identity.
+- Prefer existing specs, ADRs, package ontologies, PROV/VC/delegation/relationship semantics, and Agentic Primitives vocabulary before creating new fields or classes.
+- Do not create one-off app hacks that bypass ontology relationships, vault authorization, delegation verification, package boundaries, or a2a/mcp data routes. If a needed class/property/pattern is missing, update the spec/ontology first and implement against that standard.

package/rules/vault-records-are-ontology-shaped.md

@@ -0,0 +1,85 @@
+# Vault records are ontology-shaped, so a question can read them without interpreting them
+
+**Canonical rule — all agents.** Spec: [356 §2.1](../../../specs/356-ontology-grounded-vault-questions.md).
+Gate: `pnpm check:ontology-bindings`. Ledger: `npx tsx scripts/vault-ontology-coverage.mts`.
+Sibling rule: [ontology-drives-behavior](ontology-drives-behavior.md) — that one is about BEHAVIOUR;
+this one is about the DATA the behaviour reads.
+
+## The rule
+
+**A record an agent stores should be readable BY the ontology, not interpreted INTO it.** Two halves:
+
+1. **The KEY binds to a class.** `org.membership:member:<sa>` IS an `aporg:OrganizationMembership`.
+   Declared in `packages/ontology/src/vault-records.ts`, checked against the T-box at build.
+2. **The FIELDS are the properties.** `memberAgent`, `organizationAgent`, `hasRoleAssignment` — the same
+   names the T-box uses, declared in the binding's `properties` map and checked the same way.
+
+When both hold, "who are the members" is a lookup. When they do not, something has to know that `orgAgent`
+means the member here and the organization there — and that something is a person reading code, or a model
+guessing. Both were happening.
+
+## Entity or index — say which
+
+A binding carries a `role`:
+
+- `entity` (default) — a THING the ontology describes. A question may be answered from it.
+- `index` — a projection over entities: an index, a cursor, a name map, an event log. **Never askable.**
+  A question answered from an index is a question answered from a cache, and the cache is what goes
+  stale (ADR-0055).
+
+A record type in neither list is UNCLASSIFIED — a gap, not a decision. The ledger prints those.
+
+## What this prevents, concretely
+
+- **Membership existed in the T-box and nowhere in a vault** (finding ORG-MEM-1). Invitations were being
+  read as membership, which the T-box explicitly forbids — an invitation is an *enrollment instrument*,
+  and satisfying one creates no membership. The only complete roster was a Home KV cache of a record
+  nothing ever wrote.
+- **A reader guessed a shape and was believed.** `directory.data` is an array; the roster reader asked for
+  `doc.listings` and answered "0 members" for every organization, forever. Zero is plausible.
+- **Bindings invented vocabulary.** `apcoord:EndeavorEvent` and `aps:` (for `skill#`) were both wrong and
+  both shipped, because the gate did not read record bindings until 2026-09-05.
+
+## Rules
+
+- **Never invent a class to make a binding compile.** Add the term to the T-box with the comment saying
+  what it means and what it is NOT, or bind to the term that already says it. If neither fits, the record
+  stays unclassified and appears in the ledger — that is the honest state.
+- **One parser per record shape.** A shape belongs in one module every reader shares
+  (`directory-rows.ts`, `relationship-rows.ts`), because a reader that guesses will guess plausibly.
+- **A binding narrows what a question can MEAN; it never widens what an asker may SEE.** Authority stays
+  the delegation, per record, where it always was (spec 277, ADR-0041).
+- **Write the record where the agent that must answer for it can read it.** Membership belongs in the
+  organization's own vault — not in a Home cache, and not only in the member's.
+
+## The anchor is `~/skills/ontology/agentic-trust`
+
+**That ontology is the anchor, and it is kept current.** It is the browsable, cross-domain T-box behind
+GraphDB (`skills-contexts`, served at skills.faithnet.io) that faith, family-office, commerce and the
+rest align to. Its own header states the relationship — *"stay grounded in, never fork"* — and it cites
+this repo's namespaces by `rdfs:seeAlso` wherever it restates one of our ideas in its own shape.
+
+**A term that says how the DOMAIN is shaped belongs in both.** Add it here (bound by IRI, checked by
+`check:ontology-bindings`), then reflect it there in that repo's shape with `rdfs:seeAlso` back to our
+IRI, cluster it in `clusters.ttl`, and push:
+
+```bash
+npx tsx scripts/check-skills-ontology-sync.ts          # what is here and not there
+cd ~/skills && GRAPHDB_USER=… GRAPHDB_PASSWORD=… python3 scripts/sync_ontology.py push --direct
+```
+
+**Where the line runs.** Not "domain vs implementation" — that reading is too coarse and got the
+registry wrong. **A value two parties must AGREE ON belongs in the anchor; one only our own code passes
+to itself does not.** A registry's binding-proof hash, card digest and lifecycle-log chaining look like
+implementation and are nothing of the sort: a registry is a STANDARDS SURFACE (spec 279 / ADR-0038, the
+ARD and ACP work), and an implementor of the standard has to agree with us on exactly those terms. As of
+2026-09-05 all 946 terms are reflected. The judgement is a person's;
+the report exists to make the list short enough to make it. A concept only the implementation knows is a
+concept the anchor cannot cluster, show, or reason over beside the domain ontologies, which is most of
+the reason the anchor exists.
+
+## Where the gaps are
+
+`npx tsx scripts/vault-ontology-coverage.mts alice nathan bob` surveys the live estate and prints every
+record family, bound or not. It is a report rather than a build gate: it needs real vaults. Run it after
+adding a record type, and bind what it lists.

package/spec.md

@@ -0,0 +1,11 @@
+# @agenticprimitives/devkit — package spec
+
+Spec of record: [specs/399-repository-split-program.md](../../specs/399-repository-split-program.md) §3.3 (gates as
+CLIs), §3.4 (rules projection), §3.1/§5.2 (`ap upgrade`), and [specs/398-agentic-primitives-ux-strategy.md](../../specs/398-agentic-primitives-ux-strategy.md)
+§10 (the Developer Kit: commands, `agentic.lock.json`, coding-agent projections). Decision: [ADR-0063](../../docs/architecture/decisions/0063-ring-0-is-packages-and-contracts-products-live-in-their-own-repos.md)
+§1 (the kit stays with the packages) and §8 (doctrine travels as data, drift by digest).
+
+Owns: the doctor rule registry (399 §2.3 ids), the rule config schema and the Ring-0 reference layout, the rules
+projection and its sidecar, the lock document, the upgrade planner, and the dispatchers. Does not own: any
+conformance suite (`a2a`, `mcp-protocol`), the live-gates runner (`evaluation`), the product-repo template
+(`create-app`), or any rule TEXT (the corpus is synced in from `docs/architecture/agent-rules`).