@agentproto/governance 0.1.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,489 @@
1
+ # agentgovernance/v1
2
+
3
+ **Status:** alpha (1.0.0-alpha) · **Domain:** governance.sh · **License:** MIT
4
+ **Reference implementation:**
5
+ [@agentproto/governance](https://npmjs.com/package/@agentproto/governance)
6
+ **Repository:** https://github.com/agentproto/agentproto
7
+
8
+ ---
9
+
10
+ ## 1. Introduction
11
+
12
+ `agentgovernance/v1` is an **open file-format standard** for recording
13
+ approvals, audit logs, and autonomy policies as workspace files. It provides a
14
+ **vendor-neutral**, **filesystem-first**, **third-party-verifiable** primitive
15
+ for any system — human, agentic, or hybrid — that needs auditable decisions.
16
+
17
+ Three doctypes:
18
+
19
+ | Doctype | File path | Purpose |
20
+ | ------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
21
+ | `signature` | `<artifact>/../signatures/<signer>-<isoDate>.signature.json` | Universal approval primitive (one signature event per file) |
22
+ | `audit-event` | `<scope>/audit/audit-log.jsonl` (one line per event) | Append-only hash-chained event log |
23
+ | `policy` | `<scope>/policies/<slug>/POLICY.md` | Declarative autonomy rule |
24
+
25
+ A workspace receiving these files can validate every doctype + verify the audit
26
+ chain end-to-end **without our infrastructure** using the published
27
+ [hash-chain protocol](./src/spec/hash-chain/protocol.md). Third-party verifiers
28
+ can be implemented in any language.
29
+
30
+ ### 1.1 Why this is its own standard
31
+
32
+ The doctypes are **domain-agnostic**: `signature.json`, `audit-log.jsonl`,
33
+ `POLICY.md` reference no business concepts (no services, no engagements, no
34
+ counterparties). They describe pure governance primitives. Any workflow that
35
+ needs auditable approvals — clinician overrides, approve-to-publish flows,
36
+ AI-agent action gates, board votes — adopts `agentgovernance/v1` directly.
37
+
38
+ `agentgovernance/v1` is a **peer standard** to `agentcompanies/v1`
39
+ (companies.sh) and is **extended by** `agentagencies/v1` (agencies.sh).
40
+
41
+ ### 1.2 Conventions
42
+
43
+ All `agentgovernance/v1` files follow the conventions established by
44
+ [`agentcompanies/v1`](https://github.com/paperclipai/paperclip/blob/master/docs/companies/companies-spec.md):
45
+
46
+ - **Markdown canonical** with YAML frontmatter (for `POLICY.md`).
47
+ - **JSON canonical** for `signature.json` and `audit-log.jsonl` lines.
48
+ - **Slug-based references**, never database IDs.
49
+ - **`schema: agentgovernance/v1`** field on every doctype frontmatter / object.
50
+ - **Vendor-specific extensions** under `metadata.<vendor>.*`.
51
+ - **Git-native**: any git repository hosting these files is a valid governance
52
+ package.
53
+
54
+ A workspace using `agentgovernance/v1` doctypes does not need to be an
55
+ `agentcompanies/v1` package — it can be any folder containing the doctypes.
56
+
57
+ ---
58
+
59
+ ## 2. Doctype: `signature`
60
+
61
+ A signature is the universal approval primitive. Every approval — of an
62
+ agreement, a deliverable, an invoice, a policy override, an agent-issued action
63
+ — is a signature on an artifact, recorded as a JSON file alongside the artifact
64
+ being signed.
65
+
66
+ ### 2.1 File location
67
+
68
+ ```
69
+ <artifact-parent-dir>/signatures/<signer-kind>-<signer-slug>-<YYYY-MM-DD>.signature.json
70
+ ```
71
+
72
+ Example:
73
+
74
+ ```
75
+ engagements/2026-acme-website-redesign/signatures/operator-jeremy-2026-04-15.signature.json
76
+ ```
77
+
78
+ Multiple signatures by the same signer on the same artifact (e.g., re-issuance
79
+ after revocation) MUST use distinct timestamps. Append-only — files are not
80
+ deleted; revocation is a frontmatter mutation (`revokedAt`, `revokedReason`) or
81
+ a fresh file with `evidence` referencing the prior.
82
+
83
+ ### 2.2 Schema
84
+
85
+ ```typescript
86
+ {
87
+ "schema": "agentgovernance/v1",
88
+ "doctype": "signature",
89
+ "signer": "<kind>:<slug>", // canonical: "operator:jeremy", "counterparty:acme-corp", "agent:ai-paralegal"
90
+ "signerKind": "operator" | "user" | "counterparty" | "agent" | "external",
91
+ "signerEmail"?: string,
92
+ "artifactPath": "engagements/2026-acme/AGREEMENT.md", // workspace-relative
93
+ "documentHash": "<64-char hex SHA-256 of artifact bytes>",
94
+ "method": "typed_name" | "agent_confirm" | "click_through" | "esign_external",
95
+ "evidence": <method-specific shape>,
96
+ "signedAt": "2026-04-15T10:23:45.000Z",
97
+ "revokedAt"?: string,
98
+ "revokedReason"?: string,
99
+ "metadata"?: { ... }
100
+ }
101
+ ```
102
+
103
+ `evidence.kind` MUST equal `method` (enforced at validation time).
104
+
105
+ ### 2.3 Signing methods
106
+
107
+ #### 2.3.1 `typed_name`
108
+
109
+ Human types name + nonce on a tokenized portal page. Captures IP + UA +
110
+ timestamp + nonce.
111
+
112
+ ```json
113
+ {
114
+ "evidence": {
115
+ "kind": "typed_name",
116
+ "signerName": "Jeremy Doe",
117
+ "ipAddress": "192.0.2.1",
118
+ "userAgent": "Mozilla/5.0 …",
119
+ "nonce": "<one-shot URL token>",
120
+ "signedUrlToken": "<optional>"
121
+ }
122
+ }
123
+ ```
124
+
125
+ #### 2.3.2 `agent_confirm`
126
+
127
+ Agent records explicit confirmation. Evidence carries `modelId` +
128
+ `promptContextHash` + optional reasoning summary + conversation turn id. Agents
129
+ MUST have the `governance.sign_as_agent` skill (or app-level equivalent) granted
130
+ by a `POLICY.md`.
131
+
132
+ ```json
133
+ {
134
+ "evidence": {
135
+ "kind": "agent_confirm",
136
+ "modelId": "claude-sonnet-4-6",
137
+ "promptContextHash": "<64-char hex>",
138
+ "reasoningSummary": "Cap policy satisfied; under threshold.",
139
+ "conversationTurnId": "t_abc123",
140
+ "authorizedByPolicy": "auto-approve-quotes-under-200eur"
141
+ }
142
+ }
143
+ ```
144
+
145
+ #### 2.3.3 `click_through`
146
+
147
+ Single-click confirmation from a signed URL. Lightweight; suitable for
148
+ low-stakes approvals.
149
+
150
+ ```json
151
+ {
152
+ "evidence": {
153
+ "kind": "click_through",
154
+ "ipAddress": "192.0.2.1",
155
+ "userAgent": "Mozilla/5.0 …",
156
+ "signedUrlToken": "<one-shot>"
157
+ }
158
+ }
159
+ ```
160
+
161
+ #### 2.3.4 `esign_external`
162
+
163
+ Wraps an external e-signature provider (DocuSeal, HelloSign, etc.). The signed
164
+ PDF MUST be archived alongside the agreement.
165
+
166
+ ```json
167
+ {
168
+ "evidence": {
169
+ "kind": "esign_external",
170
+ "provider": "docuseal",
171
+ "externalRef": "<envelope-id>",
172
+ "signedPdfRef": "engagements/2026-acme/AGREEMENT.signed.pdf"
173
+ }
174
+ }
175
+ ```
176
+
177
+ ---
178
+
179
+ ## 3. Doctype: `audit-event` (audit-log.jsonl)
180
+
181
+ Each line of `<scope>/audit/audit-log.jsonl` is one audit event, encoded as a
182
+ single JSON object on one line. Lines are linked by an HMAC-SHA256 chain.
183
+
184
+ ### 3.1 Scope
185
+
186
+ The `<scope>` directory determines the chain's scope. Common scopes:
187
+
188
+ - `audit/audit-log.jsonl` — workspace / company-level events.
189
+ - `engagements/<slug>/audit/audit-log.jsonl` — engagement-scoped events
190
+ (recommended for `agentagencies/v1`).
191
+ - Any other folder may host its own log — there is no global registry.
192
+
193
+ Each scope has its own chain, its own genesis seed, and its own anchor cadence.
194
+
195
+ ### 3.2 Schema
196
+
197
+ ```typescript
198
+ {
199
+ "schema": "agentgovernance/v1",
200
+ "doctype": "audit-event",
201
+ "actorKind": "operator" | "user" | "counterparty" | "agent" | "system",
202
+ "actorId": <slug | null>, // null for actorKind=system
203
+ "entityType": "<known type or extension>",
204
+ "entityId": "<workspace path or governance-internal id>",
205
+ "action": "<entity>.<verb>", // lowercase, e.g., "signature.created"
206
+ "payload"?: { ... }, // action-specific
207
+ "prevSignature": "<64-char hex>", // chain link
208
+ "signature": "<64-char hex>", // chain link
209
+ "requestId"?: string,
210
+ "traceId"?: string,
211
+ "ipAddress"?: string,
212
+ "userAgent"?: string,
213
+ "createdAt": "<ISO-8601 UTC>",
214
+ "metadata"?: { ... }
215
+ }
216
+ ```
217
+
218
+ Implementations SHOULD use known `entityType` values (`signature`,
219
+ `audit-event`, `policy`, `approval`, plus any from `agentagencies/v1` or
220
+ `agentcompanies/v1` if those specs are in use). Implementations SHOULD NOT
221
+ introduce new types ad-hoc — vendor-specific events go under
222
+ `metadata.<vendor>.*`.
223
+
224
+ ### 3.3 Hash-chain protocol
225
+
226
+ See [`src/spec/hash-chain/protocol.md`](./src/spec/hash-chain/protocol.md) for
227
+ the full specification with reference test vectors.
228
+
229
+ Summary:
230
+
231
+ ```
232
+ signature_n = HMAC-SHA256(
233
+ key = secret_bytes,
234
+ data = prev_signature_hex_utf8 ‖ canonical_bytes(row_n_minus_signature)
235
+ )
236
+ ```
237
+
238
+ The first line uses the workspace genesis seed as `prev_signature`.
239
+
240
+ ### 3.4 External anchors
241
+
242
+ Periodically (default: every 1000 lines), the latest `signature` is published to
243
+ an external sink (S3 with object-lock, transparency log, public Git). A
244
+ workspace cannot rewrite history without invalidating an external anchor.
245
+
246
+ ---
247
+
248
+ ## 4. Doctype: `policy` (POLICY.md)
249
+
250
+ A POLICY.md is a declarative autonomy rule with YAML frontmatter and a markdown
251
+ body. Frontmatter is used by the policy engine; body is human/agent-readable
252
+ narrative.
253
+
254
+ ### 4.1 File location
255
+
256
+ ```
257
+ <scope>/policies/<slug>/POLICY.md
258
+ ```
259
+
260
+ ### 4.2 Frontmatter schema
261
+
262
+ ```yaml
263
+ schema: agentgovernance/v1
264
+ doctype: policy
265
+ slug: invoice-cap-500eur
266
+ name: Invoice cap 500 EUR
267
+ description:
268
+ Operators may issue invoices ≤ 500 EUR autonomously; founder signature
269
+ required above.
270
+ appliesTo:
271
+ - actorKind: operator
272
+ actionType: agency.issue_invoice
273
+ caps:
274
+ - field: amount
275
+ max: 500
276
+ currency: EUR
277
+ threshold: single # auto | single | all_of | any_of | weighted_threshold
278
+ requiredWeight: 0 # required when threshold=weighted_threshold
279
+ requiredSignatures:
280
+ - signer: operator:founder
281
+ method: typed_name
282
+ weight: 1 # only used by weighted_threshold
283
+ deadline: PT24H # ISO-8601 duration
284
+ escalation:
285
+ leadTime: PT2H
286
+ escalateTo: [operator:cofounder]
287
+ metadata:
288
+ agency:
289
+ appliesToServices: [emergency-callout, drain-cleaning]
290
+ ```
291
+
292
+ ### 4.3 Threshold semantics
293
+
294
+ | `threshold` | Resume condition |
295
+ | -------------------- | -------------------------------------------------------------------- |
296
+ | `auto` | Tool may proceed without signatures (action is logged but not gated) |
297
+ | `single` / `any_of` | Any one signature from `requiredSignatures` suffices |
298
+ | `all_of` | Every entry in `requiredSignatures` must sign |
299
+ | `weighted_threshold` | Sum of `weight` of collected signatures must reach `requiredWeight` |
300
+
301
+ ### 4.4 Wildcard signers
302
+
303
+ A `requiredSignatures` entry may use `*` as the slug to mean "any signer of this
304
+ kind":
305
+
306
+ ```yaml
307
+ requiredSignatures:
308
+ - signer: operator:*
309
+ method: typed_name
310
+ ```
311
+
312
+ This is satisfied by any operator's signature.
313
+
314
+ ---
315
+
316
+ ## 5. Contractual approval framework
317
+
318
+ The framework unifies what would otherwise be three concepts (signing legal
319
+ documents, approval gates, audit decisions) into one: **every approval is a
320
+ signature on an artifact**.
321
+
322
+ ### 5.1 Standard flow
323
+
324
+ A tool that needs approval for an action:
325
+
326
+ 1. **Drafts** the artifact representing the action (e.g., an `INVOICE.md` with
327
+ `status: pending_approval`).
328
+ 2. **Looks up** the matching `POLICY.md` (by `appliesTo.actorKind` +
329
+ `appliesTo.actionType`).
330
+ 3. **Sets** `requiredSignatures` on the artifact frontmatter from the policy.
331
+ 4. **Suspends** (workflow primitive — runtime-specific; see adapter packages).
332
+ 5. **Notifies** required signers (channel dispatcher — see
333
+ `agentagencies/v1.channels` or app-level equivalent).
334
+
335
+ When a signer (human OR agent) signs:
336
+
337
+ 1. The runtime writes a `signature.json` next to the artifact.
338
+ 2. The runtime appends an `audit-event` to the relevant `audit-log.jsonl` (with
339
+ `action: signature.created`).
340
+ 3. The runtime checks if all `requiredSignatures` are now collected per the
341
+ policy threshold.
342
+ 4. If yes, the suspended workflow resumes; the originally-suspended tool
343
+ finishes (artifact is finalized, side-effects fire).
344
+
345
+ ### 5.2 Pending-signature index
346
+
347
+ Implementations SHOULD maintain a regeneratable index file
348
+ `<workspace>/_index/pending-signatures.json` keyed by signer:
349
+
350
+ ```json
351
+ {
352
+ "version": "1",
353
+ "updatedAt": "2026-04-26T15:00:00.000Z",
354
+ "bySigner": {
355
+ "operator:founder": [
356
+ {
357
+ "artifactPath": "engagements/2026-acme/INVOICE.md",
358
+ "deadline": "2026-05-15T17:00:00.000Z",
359
+ "requestedAt": "2026-04-26T14:00:00.000Z",
360
+ "method": "typed_name",
361
+ "weight": 1
362
+ }
363
+ ]
364
+ }
365
+ }
366
+ ```
367
+
368
+ The index is **not authoritative** — it can be rebuilt at any time by walking
369
+ the workspace for artifacts with `requiredSignatures`. Its sole purpose is fast
370
+ operator-inbox queries.
371
+
372
+ ---
373
+
374
+ ## 6. Composition with other specs
375
+
376
+ `agentgovernance/v1` is independent. It can be adopted by any app:
377
+
378
+ ```
379
+ my-app/
380
+ ├── audit/audit-log.jsonl
381
+ ├── policies/<slug>/POLICY.md
382
+ ├── <some-artifact>.md
383
+ └── <some-artifact>.signatures/
384
+ └── operator-jeremy-2026-04-15.signature.json
385
+ ```
386
+
387
+ When composed with `agentcompanies/v1` (companies.sh):
388
+
389
+ - `actorKind: operator` corresponds to the org's `AGENTS.md` entries.
390
+ - Policies may reference operator slugs from the company package.
391
+
392
+ When composed with `agentagencies/v1` (agencies.sh):
393
+
394
+ - Engagement / agreement / deliverable / invoice artifacts use
395
+ `agentgovernance/v1.signature.json` for signing.
396
+ - Per-engagement audit logs become the canonical record of the engagement.
397
+
398
+ A workspace using `agentagencies/v1` MUST validate as a valid
399
+ `agentgovernance/v1` workspace wherever `signature.json`, `audit-log.jsonl`, or
400
+ `POLICY.md` files appear (SHALL clause).
401
+
402
+ ---
403
+
404
+ ## 7. SHALL / SHOULD / MAY
405
+
406
+ - **SHALL** Every `signature.json` MUST have `evidence.kind === method` (or
407
+ validators reject).
408
+ - **SHALL** Every `audit-log.jsonl` line MUST chain correctly per the hash-chain
409
+ protocol — verifiers report the first mismatch.
410
+ - **SHALL** `documentHash` MUST be lowercase 64-character hex of SHA-256 over
411
+ the artifact bytes at signing time.
412
+ - **SHALL** `signedAt` MUST be ISO-8601 with UTC timezone.
413
+ - **SHOULD** `audit-event.entityType` SHOULD use known values (no ad-hoc
414
+ strings).
415
+ - **SHOULD** `policies/<slug>/` SHOULD contain only `POLICY.md` and supporting
416
+ docs (no executable code).
417
+ - **MAY** Vendor-specific fields MAY appear under `metadata.<vendor>.*`.
418
+ - **MAY** Implementations MAY add fields to `payload`, `evidence`, `metadata`
419
+ objects for forward compatibility — readers MUST ignore unknown fields.
420
+
421
+ ---
422
+
423
+ ## 8. Vendor extensions
424
+
425
+ Vendor-specific runtime data goes under `metadata.<vendor>.*`. Examples:
426
+
427
+ ```yaml
428
+ # In a POLICY.md frontmatter
429
+ metadata:
430
+ mastra:
431
+ workflowId: "issue-invoice-with-cap"
432
+ guilde:
433
+ appliesToOperatorTeams: [billing, sales]
434
+ ```
435
+
436
+ Adapter packages (`@agentproto/governance-mastra`, etc.) are the consumer-facing
437
+ API for vendor-specific orchestration. The core spec stays vendor-neutral.
438
+
439
+ ---
440
+
441
+ ## 9. Versioning
442
+
443
+ This document specifies `agentgovernance/v1`, version 1.0.0-alpha.
444
+
445
+ Future minor versions (1.x) MAY add fields and methods (with non-breaking
446
+ semantics). Major versions (2.x) MAY change the chain protocol or doctype
447
+ shapes. Workspaces MUST emit the same version per file; mixing versions in one
448
+ chain is forbidden.
449
+
450
+ When version 1.0 stabilizes, this spec moves to https://agentproto.sh/docs/gov-1/v1.
451
+
452
+ ---
453
+
454
+ ## 10. Reference implementation
455
+
456
+ [@agentproto/governance](https://npmjs.com/package/@agentproto/governance) is the
457
+ reference TypeScript implementation, MIT-licensed. It ships:
458
+
459
+ - Zod schemas for all doctypes (`./doctypes`)
460
+ - Validators (`./validators`)
461
+ - Hash-chain protocol — compute + verify (`./hash-chain`)
462
+ - Canvakit renderers + templates for signing-portal / signature-card /
463
+ audit-timeline (`./renderers` after Phase 1)
464
+ - FS-only runtime helpers — `recordAuditEvent`, `signArtifact`,
465
+ `listPendingSignatures` (`./runtime`)
466
+
467
+ Test corpus lives in `test/fixtures/` and includes hash-chain test vectors that
468
+ any implementation MUST reproduce byte-for-byte.
469
+
470
+ ---
471
+
472
+ ## 11. Compatibility test corpus (TBD — Phase 1)
473
+
474
+ A frozen set of test vectors (input artifact bytes + secret + genesis seed →
475
+ expected canonical bytes + expected signature) will be published with v1.0
476
+ stable. Any implementation passing these vectors is interoperable with the
477
+ reference.
478
+
479
+ For alpha, integration tests in `src/spec/hash-chain/{compute,verify}.test.ts`
480
+ and `src/runtime/runtime.e2e.test.ts` document the expected behavior.
481
+
482
+ ---
483
+
484
+ ## 12. Acknowledgments
485
+
486
+ This spec extends the conventions of
487
+ [agentcompanies/v1](https://github.com/paperclipai/paperclip/blob/master/docs/companies/companies-spec.md)
488
+ (paperclipai). Hash-chain construction draws on RFC 8785 (JCS), classic
489
+ Merkle/append-only log designs, and transparency log practice.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jeremy (governance.sh)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,113 @@
1
+ # @agentproto/governance
2
+
3
+ `agentgovernance/v1` — the universal contractual approval framework, published
4
+ as the open standard at [governance.sh](https://agentproto.sh/docs/gov-1).
5
+
6
+ > ⚠️ **Alpha (v0.1).** Spec stabilizing. APIs may change pre-1.0.
7
+
8
+ ## Trust boundary (read this first)
9
+
10
+ `v0.1` ships an **honest internal building block**, not a fully-credible
11
+ contractual-approval product. Three pillars distinguish a credible standard from
12
+ this alpha; v0.1 has the first only:
13
+
14
+ | Pillar | v0.1 | Provided by |
15
+ | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
16
+ | **Bytes integrity** — "this artifact has not changed since signing" | ✅ SHA-256 of artifact bytes recorded in `signature.json`; runtime always re-hashes from disk | `@agentproto/governance-engine` |
17
+ | **Identity authenticity** — "the signer was actually who the file says" | ❌ The `signer` field is a declarative string. Anyone with FS write access can author a `signature.json` claiming any signer. | Cryptographic JWS over the signature payload, bound to a per-identity key. Roadmap M4. |
18
+ | **History integrity vs. workspace owner** — "the workspace owner cannot rewrite the chain undetected" | ❌ The hash chain is verifiable by anyone who has the file, but the workspace owner can rewrite the file and re-chain. No external witness in v0.1. | OpenTimestamps / RFC 3161 / on-chain anchor sink. Roadmap M5. |
19
+
20
+ **Use v0.1 in trusted contexts only**: an internal workspace where everyone with
21
+ FS write is already inside your trust boundary, and you want a structured record
22
+ of approvals that's portable, type-checkable, and machine-verifiable (within
23
+ that trust boundary). Do **not** use v0.1 where any of the following is true:
24
+
25
+ - The workspace owner is one of the parties whose signature you need to trust.
26
+ - Counterparties outside your trust boundary author `signature.json` files.
27
+ - A regulator, court, or external auditor will be asked to rely on the chain.
28
+
29
+ The roadmap to close all three pillars (cryptographic identity in M4, external
30
+ anchoring in M5, RFC 8785 / cross-language conformance in M6) is published in
31
+ [the agentproto spec series](https://agentik.net/docs/aip-7). v1.0 of the
32
+ package will not ship until those three are in place.
33
+
34
+ ## What this is
35
+
36
+ A small, vendor-neutral, filesystem-first standard for **recording approvals as
37
+ signatures, appending tamper-evident audit logs, and declaring autonomy
38
+ policies** — usable by any AI agent system that needs auditable decisions.
39
+
40
+ Three doctypes:
41
+
42
+ | Doctype | File | Purpose |
43
+ | ----------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
44
+ | `signature.json` | `<artifact>/signatures/<signer>-<date>.signature.json` | Universal approval primitive (typed_name, agent_confirm, click_through, esign_external) |
45
+ | `audit-log.jsonl` | `<scope>/audit/audit-log.jsonl` | Append-only, hash-chained event log |
46
+ | `POLICY.md` | `<scope>/policies/<slug>/POLICY.md` | Declarative autonomy rule (caps, thresholds, requiredSignatures-when-exceeded) |
47
+
48
+ The full spec is in [`AGENTGOVERNANCE.md`](./AGENTGOVERNANCE.md).
49
+
50
+ ## Why a peer standard
51
+
52
+ Governance doctypes are **domain-agnostic**: `signature.json`,
53
+ `audit-log.jsonl`, `POLICY.md` don't reference services, engagements, or
54
+ counterparties. Any workflow that needs an auditable approval — clinician
55
+ overrides, approve-to-publish flows, board votes, AI-agent actions — uses the
56
+ same files.
57
+
58
+ ## Why filesystem
59
+
60
+ A client receiving a workspace folder can verify every signature + the entire
61
+ audit chain **without our infrastructure** using the published
62
+ [hash-chain protocol](./src/spec/hash-chain/protocol.md). Third-party verifiers
63
+ can be implemented in any language.
64
+
65
+ ## Install
66
+
67
+ ```bash
68
+ npm install @agentproto/governance
69
+ ```
70
+
71
+ ## Subpath exports
72
+
73
+ ```ts
74
+ import {
75
+ signatureSchema,
76
+ auditEventSchema,
77
+ policySchema,
78
+ } from "@agentproto/governance/doctypes"
79
+ import {
80
+ computeChainSignature,
81
+ verifyChain,
82
+ } from "@agentproto/governance/hash-chain"
83
+ import {
84
+ validateSignature,
85
+ validateAuditEvent,
86
+ validatePolicy,
87
+ } from "@agentproto/governance/validators"
88
+ import {
89
+ recordAuditEvent,
90
+ signArtifact,
91
+ listPendingSignatures,
92
+ } from "@agentproto/governance/runtime"
93
+ ```
94
+
95
+ ## Vendor neutrality
96
+
97
+ This package depends only on `zod`, `gray-matter`, `yaml`, and Node's built-in
98
+ `crypto`. There are **zero imports** from Mastra, LangChain, Temporal, or any
99
+ other workflow runtime. Adapters live in separate packages:
100
+
101
+ - `@agentproto/governance-mastra` — Mastra suspend/resume hooks
102
+ - (future) `@agentproto/governance-langchain`, `@agentproto/governance-temporal`,
103
+ etc.
104
+
105
+ ## Status
106
+
107
+ This is the **canonical implementation** of `agentgovernance/v1`. The spec is
108
+ open; alternative implementations are welcome at
109
+ [governance.sh](https://agentproto.sh/docs/gov-1).
110
+
111
+ ## License
112
+
113
+ MIT
@@ -0,0 +1,3 @@
1
+
2
+ //# sourceMappingURL=chunk-5G463T6C.mjs.map
3
+ //# sourceMappingURL=chunk-5G463T6C.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-5G463T6C.mjs"}
@@ -0,0 +1,3 @@
1
+
2
+ //# sourceMappingURL=chunk-7GHDRKSD.mjs.map
3
+ //# sourceMappingURL=chunk-7GHDRKSD.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-7GHDRKSD.mjs"}