approval-md 0.2.0 → 0.4.0

package/schema/fixtures/event/valid/harness-kind-hermes.json

@@ -0,0 +1,23 @@
+{
+  "seq": 56,
+  "ts": "2026-09-20T09:41:12Z",
+  "event": "task.registered",
+  "task": "hook:hermes-sess-1:toolu-16",
+  "actor": "agent:hermes",
+  "payload": {
+    "state": "proposed",
+    "actions": [
+      {
+        "class": "deps.add",
+        "summary": "npm install --save-dev oxlint",
+        "idempotency_key": "hook:hermes-sess-1:toolu-16:deps.add",
+        "payload_hash": "4d0a9c2b7e5f13860ad4c9b217e3f508cc61a7d2394b8e05f7ca61d3b8092e4f"
+      }
+    ],
+    "harness": "hermes",
+    "harness_version": "hermes 0.21.3"
+  },
+  "alg": "sha256/jcs",
+  "prev": "7d925ec380b14fa6c05e971b3d4287ac6fb015e93c2a480df6b1e7c05a83942f",
+  "hash": "e1f6a30c4d7b92815ac0fe43b6d258907cb14fe2839a5d07f4cb62e1a9350b7d"
+}

package/schema/fixtures/event/valid/harness-kind-muse.json

@@ -0,0 +1,23 @@
+{
+  "seq": 55,
+  "ts": "2026-09-19T08:18:59Z",
+  "event": "task.registered",
+  "task": "hook:muse-sess-1:toolu-15",
+  "actor": "agent:muse",
+  "payload": {
+    "state": "proposed",
+    "actions": [
+      {
+        "class": "deps.add",
+        "summary": "npm install --save-dev oxlint",
+        "idempotency_key": "hook:muse-sess-1:toolu-15:deps.add",
+        "payload_hash": "4d0a9c2b7e5f13860ad4c9b217e3f508cc61a7d2394b8e05f7ca61d3b8092e4f"
+      }
+    ],
+    "harness": "muse",
+    "harness_version": "muse-bin-1.3.0-R3233.1"
+  },
+  "alg": "sha256/jcs",
+  "prev": "c6410d97b28e53fa0716d8c4b93e250fa8d17c6b4093e5ad21fc80b7e5943d1a",
+  "hash": "7d925ec380b14fa6c05e971b3d4287ac6fb015e93c2a480df6b1e7c05a83942f"
+}

package/schema/fixtures/policy/invalid/daemons-malformed-id.json

@@ -0,0 +1,10 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "daemons": ["Village-Goa-1"],
+  "classes": {
+    "communicate.email.external": { "autonomy": "manual" }
+  }
+}

package/schema/fixtures/policy/invalid/senders-half-keyed.json

@@ -0,0 +1,20 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "channel": "telegram",
+    "approval_ttl": "30m",
+    "on_expiry": "reject"
+  },
+  "approvers": {
+    "carter": {
+      "channels": ["telegram"],
+      "senders": {
+        "telegram": "sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
+      }
+    }
+  },
+  "classes": {
+    "communicate.email.external": { "autonomy": "manual" }
+  }
+}

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

@@ -14,7 +14,7 @@
   "classes": {
     "read.*": { "autonomy": "autonomous" },
     "files.write.workspace": { "autonomy": "autonomous" },
-    "calendar.write.own": { "autonomy": "supervised" },
+    "calendar.write.own": { "autonomy": "supervised-retro" },
     "communicate.email.draft": { "autonomy": "autonomous" },
     "communicate.email.external": {
       "autonomy": "manual",

package/schema/fixtures/policy/valid/daemons-allowlist.json

@@ -0,0 +1,19 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "channel": "telegram",
+    "approval_ttl": "30m",
+    "on_expiry": "reject"
+  },
+  "approvers": {
+    "carter": {
+      "channels": ["telegram", "cli"],
+      "senders": { "telegram": "5551234567" }
+    }
+  },
+  "daemons": ["daemon-3f2a9c11", "village-goa-1"],
+  "classes": {
+    "communicate.email.external": { "autonomy": "manual" }
+  }
+}

package/schema/fixtures/policy/valid/senders-keyed.json

@@ -0,0 +1,24 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "channel": "telegram",
+    "approval_ttl": "30m",
+    "on_expiry": "reject"
+  },
+  "approvers": {
+    "carter": {
+      "channels": ["telegram", "cli"],
+      "senders": {
+        "telegram": "hmac-sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
+      }
+    },
+    "dana": {
+      "channels": ["telegram"],
+      "senders": { "telegram": "5551234567" }
+    }
+  },
+  "classes": {
+    "communicate.email.external": { "autonomy": "manual" }
+  }
+}

package/schema/fixtures/policy-md/invalid/schema-invalid-agent-may-request.md

@@ -0,0 +1,21 @@
+# Approval Policy
+
+Two invalid spellings of `agent_may_request` (APRV-445): a string where a
+boolean belongs, and `true` on a `human-only` rule, which is inert to agents
+and may not be opened to them. Either alone fails the whole policy closed:
+`schema-invalid`.
+
+```yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual
+
+classes:
+  intent.publish.inferred.index:
+    autonomy: manual
+    agent_may_request: "yes"
+  account.credential:
+    autonomy: human-only
+    agent_may_request: true
+```

package/schema/fixtures/policy-md/valid/agent-may-request.md

@@ -0,0 +1,24 @@
+# Approval Policy
+
+`agent_may_request` (APRV-445) opens `approval propose` to classes the operator
+declares by name. The family line opens the branch; each member is still a line
+of its own, and the closed member says no for itself.
+
+```yaml approval-policy
+version: "0.1"
+
+defaults:
+  autonomy: manual
+  approval_ttl: 72h
+
+classes:
+  intent.publish.*:
+    autonomy: manual
+    agent_may_request: true
+  intent.publish.inferred.index: { autonomy: manual }
+  intent.publish.stated.index: { autonomy: autonomous }
+  intent.publish.closed:
+    autonomy: manual
+    agent_may_request: false
+  communicate.email.external: { autonomy: manual }
+```

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

@@ -19,7 +19,7 @@ approvers:
 classes:
   read.*:                       { autonomy: autonomous }
   files.write.workspace:        { autonomy: autonomous }
-  calendar.write.own:           { autonomy: supervised }
+  calendar.write.own:           { autonomy: supervised-retro }
   communicate.email.draft:      { autonomy: autonomous }
   communicate.email.external:
     autonomy: manual

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

@@ -19,7 +19,7 @@ approvers:
 classes:
   read.*:                       { autonomy: autonomous }
   files.write.workspace:        { autonomy: autonomous }
-  calendar.write.own:           { autonomy: supervised }
+  calendar.write.own:           { autonomy: supervised-retro }
   communicate.email.draft:      { autonomy: autonomous }
   communicate.email.external:
     autonomy: manual
@@ -55,7 +55,7 @@ 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
+version: "0.2"
 
 love:
   - seeing the real change, not a description of it
@@ -64,16 +64,14 @@ love:
 like:
   - success reported first, caveats after
   - small reviewable commits
+  - honest opinions on the work, including when you think a task is wrong
+  - a journal entry of about five points per milestone
 
 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."
+communication: "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/values/invalid/class-shaped.json

@@ -1,5 +1,5 @@
 {
-  "version": 1,
+  "version": "0.2",
   "like": ["small reviewable commits"],
   "classes": {
     "message.send": {

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

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

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

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

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

@@ -1,5 +1,5 @@
 {
-  "version": 1,
+  "version": "0.2",
   "like": [
     "preference 01",
     "preference 02",

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

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

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

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

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

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

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

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

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

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

package/schema/fixtures/values/valid/full.json

@@ -1,20 +1,18 @@
 {
-  "version": 1,
+  "version": "0.2",
   "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"
+    "small reviewable commits",
+    "honest opinions on the work, including when you think a task is wrong",
+    "a journal entry of about five points per milestone"
   ],
   "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."
+  "communication": "Usually within the hour on the phone; a bare 'ok' means yes and is not curtness."
 }

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

@@ -1 +1 @@
-{ "version": 1 }
+{ "version": "0.2" }

package/schema/fixtures/values-md/invalid/schema-invalid.md

@@ -19,7 +19,7 @@ approvers:
 classes:
   read.*:                       { autonomy: autonomous }
   files.write.workspace:        { autonomy: autonomous }
-  calendar.write.own:           { autonomy: supervised }
+  calendar.write.own:           { autonomy: supervised-retro }
   communicate.email.draft:      { autonomy: autonomous }
   communicate.email.external:
     autonomy: manual
@@ -52,8 +52,10 @@ Everything after the block is prose again and is ignored by the parser.
 ## What I value
 
 The block below parses as YAML and is refused by values.schema.json: `version`
-is the string "1" rather than the integer 1, and `classes` is a policy-shaped
-key the closed schema does not admit.
+is the string "1" rather than the string "0.2", and `classes` is a policy-shaped
+key the closed schema does not admit. The version here is a STRING on purpose,
+so this fixture reaches the schema: a numeric version is refused earlier, by
+name, as `version-unsupported` (APRV-336).
 
 ```yaml approval-values
 version: "1"

package/schema/fixtures/values-md/invalid/two-blocks.md

@@ -19,7 +19,7 @@ approvers:
 classes:
   read.*:                       { autonomy: autonomous }
   files.write.workspace:        { autonomy: autonomous }
-  calendar.write.own:           { autonomy: supervised }
+  calendar.write.own:           { autonomy: supervised-retro }
   communicate.email.draft:      { autonomy: autonomous }
   communicate.email.external:
     autonomy: manual
@@ -55,7 +55,7 @@ Two values blocks: two answers to one question. The reader refuses rather than
 picking one on document order.
 
 ```yaml approval-values
-version: 1
+version: "0.2"
 like:
   - success reported first, caveats after
 ```
@@ -63,7 +63,7 @@ like:
 And, further down the file, a second one somebody pasted in later.
 
 ```yaml approval-values
-version: 1
+version: "0.2"
 like:
   - the opposite of the above
 ```

package/schema/fixtures/values-md/invalid/unterminated.md

@@ -19,7 +19,7 @@ approvers:
 classes:
   read.*:                       { autonomy: autonomous }
   files.write.workspace:        { autonomy: autonomous }
-  calendar.write.own:           { autonomy: supervised }
+  calendar.write.own:           { autonomy: supervised-retro }
   communicate.email.draft:      { autonomy: autonomous }
   communicate.email.external:
     autonomy: manual
@@ -56,6 +56,6 @@ file; this reader will not, because the truncated tail of a block is
 indistinguishable from a complete one.
 
 ```yaml approval-values
-version: 1
+version: "0.2"
 like:
   - success reported first, caveats after

package/schema/fixtures/values-md/invalid/version-1.md

@@ -0,0 +1,69 @@
+# 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-retro }
+  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 the FIRST revision of the values format: `version` is the
+integer 1 and it carries a `wants:` list. APRV-336 folded `wants` into `like`
+and moved the version to the quoted string "0.2", so this block is refused with
+`version-unsupported` and a message naming the two edits.
+
+```yaml approval-values
+version: 1
+like:
+  - success reported first, caveats after
+
+wants:
+  - say when you are stuck rather than guessing a fourth time
+```
+
+Prose again after the block. The policy above loads exactly as it does in every
+other fixture here: a values failure is never a policy failure.

package/schema/fixtures/values-md/invalid/version-unquoted.md

@@ -0,0 +1,64 @@
+# 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-retro }
+  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 the current revision written without quotes. YAML reads the
+dotted identifier as the float 0.2, which is why the version is quoted at all,
+so the reader refuses it with `version-unsupported` and the quotes as the fix.
+
+```yaml approval-values
+version: 0.2
+like:
+  - success reported first, caveats after
+```
+
+Prose again after the block, ignored by both readers.

package/schema/fixtures/values-md/invalid/yaml-error.md

@@ -19,7 +19,7 @@ approvers:
 classes:
   read.*:                       { autonomy: autonomous }
   files.write.workspace:        { autonomy: autonomous }
-  calendar.write.own:           { autonomy: supervised }
+  calendar.write.own:           { autonomy: supervised-retro }
   communicate.email.draft:      { autonomy: autonomous }
   communicate.email.external:
     autonomy: manual
@@ -55,7 +55,7 @@ The block below is not YAML: the second entry is indented into a mapping that
 was never opened.
 
 ```yaml approval-values
-version: 1
+version: "0.2"
 like:
   - success reported first
     key: value

package/schema/fixtures/values-md/valid/absent.md

@@ -19,7 +19,7 @@ approvers:
 classes:
   read.*:                       { autonomy: autonomous }
   files.write.workspace:        { autonomy: autonomous }
-  calendar.write.own:           { autonomy: supervised }
+  calendar.write.own:           { autonomy: supervised-retro }
   communicate.email.draft:      { autonomy: autonomous }
   communicate.email.external:
     autonomy: manual

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

@@ -19,7 +19,7 @@ approvers:
 classes:
   read.*:                       { autonomy: autonomous }
   files.write.workspace:        { autonomy: autonomous }
-  calendar.write.own:           { autonomy: supervised }
+  calendar.write.own:           { autonomy: supervised-retro }
   communicate.email.draft:      { autonomy: autonomous }
   communicate.email.external:
     autonomy: manual
@@ -55,7 +55,7 @@ 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
+version: "0.2"
 
 love:
   - seeing the real change, not a description of it
@@ -64,16 +64,14 @@ love:
 like:
   - success reported first, caveats after
   - small reviewable commits
+  - honest opinions on the work, including when you think a task is wrong
+  - a journal entry of about five points per milestone
 
 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."
+communication: "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.