approval-md 0.0.1 → 0.2.0

package/schema/fixtures/policy/valid/human-only.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.1",
+  "defaults": { "autonomy": "human-only" },
+  "classes": {
+    "account.credential": { "autonomy": "human-only" },
+    "vcs.history.rewrite": { "autonomy": "human-only", "approvers": ["alice"] },
+    "read.*": { "autonomy": "autonomous" }
+  }
+}

package/schema/fixtures/policy/valid/minimal.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  }
+}

package/schema/fixtures/policy/valid/protected-paths.json

@@ -0,0 +1,10 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "protected_paths": ["SPEC.md", "design/"],
+  "classes": {
+    "policy.edit": { "autonomy": "manual" }
+  }
+}

package/schema/fixtures/policy/valid/record-namespace.json

@@ -0,0 +1,13 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "channel": "cli"
+  },
+  "classes": {
+    "record.write.stage": { "autonomy": "supervised" },
+    "record.categorize": { "autonomy": "manual" },
+    "record.archive": { "autonomy": "supervised" },
+    "record.*": { "autonomy": "manual" }
+  }
+}

package/schema/fixtures/policy/valid/request-volume-limits.json

@@ -0,0 +1,26 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "channel": "telegram",
+    "approval_ttl": "24h",
+    "on_expiry": "reject"
+  },
+  "approvers": {
+    "carter": { "channels": ["telegram", "cli"] }
+  },
+  "classes": {
+    "communicate.email.external": {
+      "autonomy": "manual",
+      "approvers": ["carter"],
+      "limits": { "max_pending": 5, "requests_per_hour": 20 }
+    },
+    "record.write.stage": {
+      "autonomy": "supervised",
+      "limits": { "max_pending": 50 }
+    }
+  },
+  "budgets": {
+    "global": { "daily_actions": 200, "max_pending": 25 }
+  }
+}

package/schema/fixtures/policy/valid/retention-and-sampling-secret.json

@@ -0,0 +1,16 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "approval_ttl": "24h",
+    "on_expiry": "reject"
+  },
+  "payload_retention": "30d",
+  "classes": {
+    "record.write.stage": { "autonomy": "supervised" }
+  },
+  "audit": {
+    "supervised_sample_rate": 0.1,
+    "sampling_secret_env": "APPROVAL_SAMPLING_SECRET"
+  }
+}

package/schema/fixtures/policy/valid/skew-tolerance.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "approval_ttl": "24h",
+    "on_expiry": "reject"
+  },
+  "classes": {
+    "record.write.stage": { "autonomy": "supervised" }
+  },
+  "audit": {
+    "supervised_sample_rate": 0.1,
+    "skew_tolerance": "250ms"
+  }
+}

package/schema/fixtures/policy/valid/vault-passphrase-env.json

@@ -0,0 +1,14 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "approval_ttl": "24h",
+    "on_expiry": "reject"
+  },
+  "classes": {
+    "communicate.email.external": { "autonomy": "manual" }
+  },
+  "vault": {
+    "passphrase_env": "APPROVAL_VAULT_PASSPHRASE"
+  }
+}

package/schema/fixtures/policy/valid/wildcards.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "approval_ttl": "7d"
+  },
+  "classes": {
+    "*": { "autonomy": "manual" },
+    "read.*": { "autonomy": "autonomous" },
+    "calendar.*.own": { "autonomy": "supervised" },
+    "files.write.*": { "autonomy": "supervised" },
+    "*.delete": { "autonomy": "manual" },
+    "communicate.*.*": { "autonomy": "manual" }
+  }
+}

package/schema/fixtures/policy-md/invalid/alias-bomb.md

@@ -0,0 +1,15 @@
+# Approval Policy
+
+A billion-laughs document: nested anchors whose aliases expand
+multiplicatively. The loader caps alias expansion (MAX_ALIAS_COUNT), so
+this fails closed as `yaml-error` instead of exhausting memory.
+
+```yaml approval-policy
+version: "0.1"
+a: &a ["lol", "lol", "lol", "lol", "lol", "lol", "lol", "lol", "lol"]
+b: &b [*a, *a, *a, *a, *a, *a, *a, *a, *a]
+c: &c [*b, *b, *b, *b, *b, *b, *b, *b, *b]
+d: &d [*c, *c, *c, *c, *c, *c, *c, *c, *c]
+e: &e [*d, *d, *d, *d, *d, *d, *d, *d, *d]
+f: [*e, *e, *e, *e, *e, *e, *e, *e, *e]
+```

package/schema/fixtures/policy-md/invalid/no-fence.md

@@ -0,0 +1,7 @@
+# Approval Policy
+
+All prose, no machine-readable block. Fails closed: `no-block`.
+
+version: "0.1"
+defaults:
+  autonomy: autonomous

package/schema/fixtures/policy-md/invalid/protected-route-not-a-subclass.md

@@ -0,0 +1,16 @@
+# Approval Policy
+
+A routing that tries to leave the `policy.edit` namespace. `protected_paths` may
+widen the protected surface and name its own sub-classes under `policy.edit`; it
+mints no authority over the gate's own organs or over the record of what
+happened (SPEC.md §11.1 invariant 9), so this file is rejected at the schema.
+
+```yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual
+
+protected_paths:
+  - { path: design/, class: files.write.workspace }
+```

package/schema/fixtures/policy-md/invalid/schema-invalid-autonomy.md

@@ -0,0 +1,16 @@
+# Approval Policy
+
+Well-formed YAML, invalid policy: `autonomy: yolo` is not one of the three
+levels the closed enum in `policy.schema.json` admits. An unrecognised
+autonomy level cannot be ordered against the others, so the whole policy
+fails closed: `schema-invalid`.
+
+```yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual
+
+classes:
+  financial.spend: { autonomy: yolo }
+```

package/schema/fixtures/policy-md/invalid/schema-invalid-read-proof.md

@@ -0,0 +1,17 @@
+# Approval Policy
+
+Well-formed YAML, invalid policy: `read_proof: incrementel` is not one of the
+two proofs the closed enum in `policy.schema.json` admits. The author believed
+they had configured the reader and the runtime would have understood nothing,
+so the whole policy fails closed (`schema-invalid`) and every class is
+`manual` — the same treatment any misspelt key gets.
+
+```yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual
+
+daemon:
+  read_proof: incrementel
+```

package/schema/fixtures/policy-md/invalid/two-fences.md

@@ -0,0 +1,19 @@
+# Approval Policy
+
+Two machine-readable blocks. SPEC.md §5 allows exactly one, so this fails
+closed: `multiple-blocks`. Merging them would mean guessing which one the
+author meant to be in force.
+
+```yaml approval-policy
+version: "0.1"
+defaults:
+  autonomy: manual
+```
+
+Some prose in between.
+
+```yaml approval-policy
+version: "0.1"
+defaults:
+  autonomy: autonomous
+```

package/schema/fixtures/policy-md/invalid/unclosed-fence.md

@@ -0,0 +1,11 @@
+# Approval Policy
+
+The policy fence is never closed, so the file ends mid-block. A truncated
+policy is indistinguishable from a complete one, so this fails closed
+rather than being silently closed at end of file.
+
+```yaml approval-policy
+version: "0.1"
+defaults:
+  autonomy: manual
+  channel: cli

package/schema/fixtures/policy-md/invalid/wrong-info-string.md

@@ -0,0 +1,11 @@
+# Approval Policy
+
+The only fenced block is tagged ```yaml, not ```yaml approval-policy. A
+bare yaml block is documentation, not policy, so nothing here is in force
+and the load fails closed: `no-block`.
+
+```yaml
+version: "0.1"
+defaults:
+  autonomy: autonomous
+```

package/schema/fixtures/policy-md/invalid/yaml-syntax-error.md

@@ -0,0 +1,13 @@
+# Approval Policy
+
+The block is fenced correctly but is not well-formed YAML: an unterminated
+flow sequence plus a stray flow mapping indicator.
+
+```yaml approval-policy
+version: "0.1"
+defaults:
+  autonomy: manual
+approvers:
+  carter:
+    channels: [cli, telegram
+```

package/schema/fixtures/policy-md/precedence/both/APPROVAL.md

@@ -0,0 +1,7 @@
+# Approval Policy (APPROVAL.md — takes precedence)
+
+```yaml approval-policy
+version: "0.1"
+defaults:
+  channel: from-approval-md
+```

package/schema/fixtures/policy-md/precedence/both/APPROVALS.md

@@ -0,0 +1,7 @@
+# Approval Policy (APPROVALS.md — must lose to APPROVAL.md)
+
+```yaml approval-policy
+version: "0.1"
+defaults:
+  channel: from-approvals-md
+```

package/schema/fixtures/policy-md/precedence/fallback-only/APPROVALS.md

@@ -0,0 +1,7 @@
+# Approval Policy (APPROVALS.md only — the accepted fallback filename)
+
+```yaml approval-policy
+version: "0.1"
+defaults:
+  channel: from-approvals-md
+```

package/schema/fixtures/policy-md/valid/canonical.md

@@ -0,0 +1,50 @@
+# Approval Policy
+
+Agents working in this project handle my life admin. Anything that leaves
+the machine gets declared, and the classes below say what I sign off on.
+
+```yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual          # unknown/undeclared classes require sign-off
+  channel: telegram
+  approval_ttl: 24h         # pending requests expire
+  on_expiry: reject
+
+approvers:
+  alice:
+    channels: [telegram, cli]
+
+classes:
+  read.*:                       { autonomy: autonomous }
+  files.write.workspace:        { autonomy: autonomous }
+  calendar.write.own:           { autonomy: supervised }
+  communicate.email.draft:      { autonomy: autonomous }
+  communicate.email.external:
+    autonomy: manual
+    approvers: [alice]
+  financial.spend:
+    autonomy: manual
+    approvers: [alice]
+    limits: { per_action_usd: 25, daily_usd: 100 }
+  public.post:                  { autonomy: manual }
+  data.delete:                  { autonomy: manual }
+  account.auth:                 { autonomy: manual }
+
+budgets:
+  global: { daily_usd: 100, daily_actions: 200 }
+
+audit:
+  supervised_sample_rate: 0.10   # fraction of supervised actions escalated
+                                 # for retrospective human review
+
+channels:
+  telegram:
+    chat_id_env: APPROVAL_TG_CHAT
+    token_env: APPROVAL_TG_TOKEN
+  web:
+    port: 4680
+```
+
+Everything after the block is prose again and is ignored by the parser.

package/schema/fixtures/policy-md/valid/daemon-read-proof.md

@@ -0,0 +1,18 @@
+# Approval Policy
+
+A policy that configures the long-lived readers' prefix proof (APRV-217). The
+`daemon` block is latency only: it names which proof a repeat read runs over a
+prefix it already verified, and how often the whole prefix is re-proved
+regardless. Nothing here reaches a verdict, a class, or an autonomy level.
+
+```yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual
+
+daemon:
+  read_proof: incremental
+  full_reproof_every: 20
+  full_reproof_after: "30s"
+```

package/schema/fixtures/policy-md/valid/minimal.md

@@ -0,0 +1,3 @@
+```yaml approval-policy
+version: "0.1"
+```

package/schema/fixtures/policy-md/valid/prose-lookalikes.md

@@ -0,0 +1,54 @@
+# Approval Policy — decoys everywhere
+
+Prose can talk about the format without being the format. For example a
+policy sets
+
+version: "9.9"
+
+defaults:
+  autonomy: autonomous
+
+at the top level, and none of those lines are inside a fence, so none of
+them are policy.
+
+Here is a nested example, wrapped in a four-backtick block so the inner
+three-backtick fence is literal content and not a fence of its own:
+
+````markdown
+```yaml approval-policy
+version: "9.9"
+defaults:
+  autonomy: autonomous
+```
+````
+
+And here is an indented code block (four spaces, no fence at all), which
+CommonMark treats as literal text:
+
+    ```yaml approval-policy
+    version: "9.9"
+    defaults:
+      autonomy: autonomous
+    ```
+
+A fenced block with a different info string is also not policy:
+
+```yaml
+version: "9.9"
+defaults:
+  autonomy: autonomous
+```
+
+The one real block follows, with surrounding whitespace in its info string:
+
+```   yaml approval-policy   
+version: "0.1"
+
+defaults:
+  autonomy: manual
+  channel: cli
+  approval_ttl: 2h
+  on_expiry: reject
+```
+
+Trailing prose, ignored.

package/schema/fixtures/policy-md/valid/routed-protected-paths.md

@@ -0,0 +1,49 @@
+# Approval Policy
+
+This project's protected surfaces do not all deserve the same amount of a
+human's attention. The specification is amended rarely and consequentially, the
+release workflow is where an agent could arrange to publish something nobody
+read, and the design directory is a notebook. Since APRV-266 a `protected_paths`
+entry may say which of those a path is, and each one takes its own line below.
+
+```yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual
+  channel: telegram
+  approval_ttl: 24h
+  on_expiry: reject
+
+protected_paths:
+  - SPEC.md
+  - { path: design/, class: policy.edit.design }
+  - { path: .github/workflows/, class: policy.edit.ci }
+  - { path: docs/constitution.md, class: policy.edit.spec }
+
+approvers:
+  alice:
+    channels: [telegram, cli]
+
+classes:
+  read.*: { autonomy: autonomous }
+  policy.edit:
+    autonomy: supervised-live
+    live_rate: 0.1
+    approvers: [alice]
+  # Looser than the `policy.edit` line, and allowed to be: `design/` is not a
+  # path the runtime protects on its own, so the routing floor does not reach it.
+  policy.edit.design: { autonomy: supervised }
+  # Stricter, which is always allowed. `.github/workflows/` IS a built-in
+  # `policy.edit` path, so the floor requires at least the line's own strictness.
+  policy.edit.ci:
+    autonomy: manual
+    approvers: [alice]
+
+budgets:
+  global: { daily_usd: 100, daily_actions: 200 }
+```
+
+`policy.edit.spec` has no line of its own, so it inherits the `policy.edit`
+line: `docs/constitution.md` stays supervised-live at 0.1 until somebody says
+otherwise, which is what adopting a routing should cost.

package/schema/fixtures/policy-md/valid/with-values.md

@@ -0,0 +1,79 @@
+# Approval Policy
+
+Agents working in this project handle my life admin. Anything that leaves
+the machine gets declared, and the classes below say what I sign off on.
+
+```yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual          # unknown/undeclared classes require sign-off
+  channel: telegram
+  approval_ttl: 24h         # pending requests expire
+  on_expiry: reject
+
+approvers:
+  alice:
+    channels: [telegram, cli]
+
+classes:
+  read.*:                       { autonomy: autonomous }
+  files.write.workspace:        { autonomy: autonomous }
+  calendar.write.own:           { autonomy: supervised }
+  communicate.email.draft:      { autonomy: autonomous }
+  communicate.email.external:
+    autonomy: manual
+    approvers: [alice]
+  financial.spend:
+    autonomy: manual
+    approvers: [alice]
+    limits: { per_action_usd: 25, daily_usd: 100 }
+  public.post:                  { autonomy: manual }
+  data.delete:                  { autonomy: manual }
+  account.auth:                 { autonomy: manual }
+
+budgets:
+  global: { daily_usd: 100, daily_actions: 200 }
+
+audit:
+  supervised_sample_rate: 0.10   # fraction of supervised actions escalated
+                                 # for retrospective human review
+
+channels:
+  telegram:
+    chat_id_env: APPROVAL_TG_CHAT
+    token_env: APPROVAL_TG_TOKEN
+  web:
+    port: 4680
+```
+
+Everything after the block is prose again and is ignored by the parser.
+
+## What I value
+
+The block below is guidance, never policy. Nothing in it grants anything, and
+no part of the runtime reads it to decide.
+
+```yaml approval-values
+version: 1
+
+love:
+  - seeing the real change, not a description of it
+  - a runbook I can paste into a terminal
+
+like:
+  - success reported first, caveats after
+  - small reviewable commits
+
+dislike:
+  - prose where a command would do
+  - being asked to approve something I cannot see
+
+wants:
+  - honest opinions on the work, including when you think a task is wrong
+  - a journal entry of about five points per milestone
+
+responds: "Usually within the hour on the phone; a bare 'ok' means yes and is not curtness."
+```
+
+Prose again after the block, ignored by both readers.

package/schema/fixtures/sample-record/invalid/bad-date-time.json

@@ -0,0 +1,4 @@
+{
+  "id": "rec_0004",
+  "ts": "2026-13-45T99:99:99Z"
+}

package/schema/fixtures/sample-record/invalid/missing-required-field.json

@@ -0,0 +1,3 @@
+{
+  "ts": "2026-08-04T21:45:00Z"
+}

package/schema/fixtures/sample-record/invalid/unknown-top-level-field.json

@@ -0,0 +1,5 @@
+{
+  "id": "rec_0003",
+  "ts": "2026-08-04T21:45:00Z",
+  "unexpected": "undeclared top-level fields must be rejected"
+}

package/schema/fixtures/sample-record/invalid/wrong-type.json

@@ -0,0 +1,4 @@
+{
+  "id": 4005,
+  "ts": "2026-08-04T21:45:00Z"
+}

package/schema/fixtures/sample-record/valid/minimal.json

@@ -0,0 +1,4 @@
+{
+  "id": "rec_0001",
+  "ts": "2026-08-04T21:45:00Z"
+}

package/schema/fixtures/sample-record/valid/with-note.json

@@ -0,0 +1,5 @@
+{
+  "id": "rec_0002",
+  "ts": "2026-08-04T21:45:00.123+02:00",
+  "note": "offset timestamps and optional fields are accepted"
+}

package/schema/fixtures/values/invalid/class-shaped.json

@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "like": ["small reviewable commits"],
+  "classes": {
+    "message.send": {
+      "autonomy": "autonomous"
+    }
+  }
+}

package/schema/fixtures/values/invalid/duplicate-entry.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "dislike": ["prose where a command would do", "prose where a command would do"]
+}

package/schema/fixtures/values/invalid/non-string-item.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "love": ["a runbook I can paste into a terminal", 7]
+}

package/schema/fixtures/values/invalid/over-cap.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "like": [
+    "preference 01",
+    "preference 02",
+    "preference 03",
+    "preference 04",
+    "preference 05",
+    "preference 06",
+    "preference 07",
+    "preference 08",
+    "preference 09",
+    "preference 10",
+    "preference 11",
+    "preference 12",
+    "preference 13",
+    "preference 14",
+    "preference 15",
+    "preference 16",
+    "preference 17",
+    "preference 18",
+    "preference 19",
+    "preference 20",
+    "preference 21"
+  ]
+}

package/schema/fixtures/values/invalid/unknown-key.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "like": ["small reviewable commits"],
+  "priority": 3
+}

package/schema/fixtures/values/invalid/version-string.json

@@ -0,0 +1 @@
+{ "version": "1" }

package/schema/fixtures/values/valid/empty-lists.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "love": [],
+  "like": [],
+  "dislike": [],
+  "wants": []
+}