approval-md 0.0.1 → 0.1.0

package/schema/policy.schema.json

@@ -0,0 +1,481 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://approval.md/schema/policy.schema.json",
+  "$comment": "CC0 1.0. See schema/LICENSE.",
+  "title": "APPROVAL.md policy block",
+  "description": "SPEC.md §5: the parsed YAML of the single ```yaml approval-policy``` fenced block inside APPROVAL.md (or APPROVALS.md). Surrounding prose is ignored by the parser and never reaches this schema. SPEC.md §5.2 requires implementations to fail closed: a document rejected here means the runtime treats every class as `manual`, so this schema is deliberately closed (additionalProperties: false at every level) — an unrecognised key is a policy the author believed was in force and the runtime did not understand, which must be a hard error rather than a silent no-op.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "SPEC.md §5.1: policy format version, quoted in YAML so \"0.1\" stays a string rather than becoming the float 0.1. The only REQUIRED top-level key: a block with no version cannot be interpreted safely under any future format revision.",
+      "examples": ["0.1"]
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.1/§5.2: fallbacks applied to any action whose class matches no rule in `classes`.",
+      "properties": {
+        "autonomy": {
+          "$ref": "#/$defs/defaultAutonomy",
+          "description": "SPEC.md §5.2 (amended, APRV-127; widened, APRV-185): autonomy for actions matching no class rule. Fail-closed policies set this to `manual`. `supervised-live` is NOT admitted here: it is meaningless without a `live_rate`, there is no place on `defaults` to declare one, and a default rate this schema invented would be a gating fraction no author ever wrote. A policy that wants live sampling declares it on the class rules it means it for. `human-only` IS admitted (APRV-185), because it carries no key to be missing: an author who writes it here reserves every unnamed class to human hands, which is an explicit choice of maximal strictness rather than a level a runtime fell back to."
+        },
+        "channel": {
+          "type": "string",
+          "minLength": 1,
+          "description": "SPEC.md §5.1: default channel name used to surface approval requests. Expected to name a key of `channels`; cross-key consistency is a runtime check (SPEC.md §10.3), not a schema constraint.",
+          "examples": ["telegram", "web", "cli"]
+        },
+        "approval_ttl": {
+          "$ref": "#/$defs/duration",
+          "description": "SPEC.md §5.1: how long a pending request stays actionable before it expires. Duration string, `<positive integer><unit>` with unit in ms|s|m|h|d|w (e.g. \"24h\"). Integer-only and single-unit by design: compound forms (\"1h30m\") and fractional values (\"1.5h\") are rejected so every implementation parses the same string to the same number of milliseconds.",
+          "examples": ["24h"]
+        },
+        "token_delivery": {
+          "type": "string",
+          "enum": ["manual", "sealed"],
+          "description": "SPEC.md §10.4 (amended, APRV-105): how the raw execution token reaches the process that will spend it. `manual` (THE DEFAULT, and what an absent key means): the token is printed once on the granting surface and carried to the spender by a human. `sealed`: `approval request` also mints an ephemeral X25519 keypair per request, keeps the private half 0600 beside the log, and publishes the public half on `approval.requested` as `token_recipient_key`; the grant then seals the raw token to that key and records the ciphertext as `token_sealed`, so `approval wait` can hand the token back to the process that asked for it — across machines, with the log synced through git. The default is `manual` because the fail-closed reading of an absent key is the behaviour that requires a human, and because sealed delivery puts ciphertext in a public, permanent log. The keypair ADDRESSES and does not AUTHORIZE: a token still exists only after a human grant, still binds to the exact payload bytes, and is still single-use. What sealing changes is who can READ a minted token, which is the human's clipboard today.",
+          "default": "manual",
+          "examples": ["manual", "sealed"]
+        },
+        "on_expiry": {
+          "type": "string",
+          "enum": ["reject"],
+          "description": "SPEC.md §5.1/§5.2: what happens when `approval_ttl` elapses with no human decision. SPEC.md §5.1 defines exactly one value, `reject`, and §5.2 mandates failing closed — so the enum is closed to `reject` rather than speculatively admitting a permissive value such as `grant`. Widening this enum is a spec amendment, and a policy that names an unknown expiry action fails validation (and therefore falls back to all-`manual`) instead of silently expiring into an unintended behaviour."
+        }
+      }
+    },
+    "payload_retention": {
+      "$ref": "#/$defs/duration",
+      "description": "SPEC.md §5.2 (amended, APRV-38): how long payload bytes are kept in `.approval/payloads/` after the action they bind to reaches a terminal state (`executed`, `rejected`, `expired`, `revoked`). A payload older than this duration in a terminal state MAY be pruned; a payload whose action is still live is never prunable at any age, because the bytes are what a pending or granted approval binds to. Orphaned payloads (bytes with no recorded binding) are prunable regardless of this key. Omitting the key means retain indefinitely: the payload store holds the material evidence of what was approved, so forgetting it is an explicit operator choice rather than a default. Pruning is performed by the daemon and by nothing else, and each removal is recorded as a `payload.pruned` event. Policy vocabulary in v0.1: enforcement lands with the M5 daemon (APRV-41), so a policy may declare it before any runtime reads it.",
+      "examples": ["30d", "12w"]
+    },
+    "protected_paths": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "SPEC.md §5.2 (amended, APRV-107 and APRV-266): repo-relative paths whose edit the runtime classifies as `policy.edit`, or as a named `policy.edit` sub-class, so an agent editing them must go through the gate. ADDITIVE ONLY: the built-in protected set (APPROVAL.md, APPROVALS.md, CLAUDE.md, AGENTS.md, .npmrc, anything under .approval/, .claude/settings*, .github/workflows/) is protected whatever this list says or omits, because a policy that could shrink the protected surface would be a policy an agent could edit its way out of. Grammar: an entry is either a bare path string (APRV-107, meaning `policy.edit`) or an object `{path, class}` routing that path family to a `policy.edit` sub-class (APRV-266), so a project can give its specification, its CI configuration and its design directory each their own autonomy and live rate. A path is an exact file (`SPEC.md`, `docs/constitution.md`) or a directory prefix ending in `/` (`design/`). No globs, no negation, no absolute paths, no `..` — the classifier is a pure segment matcher, not a shell, and a pattern language it half-implemented would be a protection an author believed was in force and the runtime did not apply. Matching is by path segments and never resolves against a checkout, so it answers the same in a worktree as in the primary: an exact path matches a candidate whose TRAILING segments are that path (`SPEC.md` matches `SPEC.md`, `./SPEC.md` and `/abs/repo/SPEC.md`; a single-segment entry therefore also matches `docs/SPEC.md`, exactly as the built-in filenames match anywhere), and a directory prefix matches a candidate containing those segments as a contiguous run (`design/` matches `design/x.md` and `/abs/repo/design/sub/x.md`). Both directions err wide on purpose: a false positive costs one approval prompt, a false negative costs the property the gate exists to defend. What this schema CANNOT state is the routing floor: a route aimed at a built-in protected path must resolve at least as strictly as the `policy.edit` line itself, and a policy that breaks that is refused at load with the code `protected-route-floor`.",
+      "items": {
+        "$comment": "A `oneOf` over the two entry shapes, which costs a refusal-code change and is still the right spelling. A malformed path now answers `oneOf` with the `pattern` failure nested under it rather than `pattern` at the top, because every union construct this validator admits reports the union first: `if`/`then`/`else` on the entry type emits an `if` error the same way, and the flat form that would have avoided both — `pattern` and `minLength` at the item level, ignored for an object by JSON Schema's own rules — is refused by Ajv's `strictTypes`, which requires a declared type for those keywords. So the conformance suite's `schema-validation` moves to 2.0.0 for these two vectors; see conformance/README.md.",
+        "oneOf": [
+          { "$ref": "#/$defs/protectedPath" },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "class"],
+            "description": "SPEC.md §5.2 (amended, APRV-266): one path family routed to a named `policy.edit` sub-class, so that family carries its own autonomy and its own live rate. The sub-class is an ordinary §7 class and takes an ordinary `classes` line; a routed class with no line of its own inherits the `policy.edit` line.",
+            "properties": {
+              "path": { "$ref": "#/$defs/protectedPath" },
+              "class": {
+                "type": "string",
+                "pattern": "^policy\\.edit\\.[a-z][a-z0-9-]*$",
+                "description": "A `policy.edit` sub-class: exactly one extra lowercase segment under `policy.edit`. Four names are reserved with fixed meanings so two policies mean the same thing by them — `policy.edit.spec` (the governing specification), `policy.edit.harness` (agent instruction files and harness configuration that is not the hook itself), `policy.edit.ci` (continuous-integration and release configuration), `policy.edit.design` (design documents and decision records) — and an author may mint any other lowercase word beside them. The namespace is closed on purpose: a policy may not route a path to `policy.core`, to `log.mutate`, or to any class outside `policy.edit`, because those are the gate's own organs and the record of what happened, and a policy widening its own protected surface mints no authority over them (SPEC.md §11.1 invariant 9)."
+              }
+            }
+          }
+        ]
+      },
+      "examples": [
+        ["SPEC.md", "design/"],
+        [
+          { "path": "SPEC.md", "class": "policy.edit.spec" },
+          { "path": ".github/workflows/", "class": "policy.edit.ci" }
+        ]
+      ]
+    },
+    "approvers": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.1: map of approver id -> approver record. Ids are referenced by the `approvers` list on class rules.",
+      "propertyNames": { "$ref": "#/$defs/identifier" },
+      "patternProperties": {
+        "^[a-z0-9][a-z0-9_-]*$": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["channels"],
+          "description": "SPEC.md §5.1: a human who may decide requests, and the channels they can be reached on.",
+          "properties": {
+            "channels": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "description": "SPEC.md §5.1/§10.3: channel names this approver can decide on, e.g. [telegram, cli]. At least one, since an approver reachable nowhere can never grant.",
+              "items": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "classes": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.1/§5.2 and §7: map of side-effect class pattern -> rule. Keys are dotted class patterns; `*` is a single-segment wildcard and a trailing `.*` matches any depth. Matching is most-specific-first and, at equal specificity, the strictest autonomy wins — both are runtime concerns; the schema only constrains key shape and rule shape.",
+      "propertyNames": { "$ref": "#/$defs/classPattern" },
+      "patternProperties": {
+        "^(?:[a-z0-9][a-z0-9_-]*|\\*)(?:\\.(?:[a-z0-9][a-z0-9_-]*|\\*))*$": {
+          "$ref": "#/$defs/classRule"
+        }
+      }
+    },
+    "budgets": {
+      "type": "object",
+      "description": "SPEC.md §5.1/§5.2: named budget scopes. `global` is the scope every action is checked against; budgets are conjunctive (an action must pass its class limits AND the global budget) and consumption is computed from the log, never from a mutable counter. Additional named scopes are permitted and share the `global` shape.",
+      "additionalProperties": { "$ref": "#/$defs/budget" },
+      "properties": {
+        "global": {
+          "$ref": "#/$defs/budget",
+          "description": "SPEC.md §5.1: the repo-wide budget, e.g. { daily_usd: 100, daily_actions: 200 }."
+        }
+      }
+    },
+    "audit": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.2/§11: retrospective review settings for actions that executed without prior sign-off.",
+      "properties": {
+        "supervised_sample_rate": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "SPEC.md §5.2: fraction of `supervised` actions escalated for after-the-fact human review, as a proportion in [0, 1] (0 = never sample, 1 = review everything). Sample selection is reproducible by the operator and unpredictable to agents: HMAC-SHA-256 over the event hash using an operator-held secret (amended SPEC.md §5.2; enforcement lands with the M5 daemon). Amended APRV-183: this is the FALLBACK rate. A class rule may declare its own `retro_rate`, which governs that class instead; classes declaring none are sampled at this rate, and a policy that declares this key alone behaves exactly as it did before the per-class key existed."
+        },
+        "sampling_secret_env": {
+          "type": "string",
+          "minLength": 1,
+          "description": "SPEC.md §5.2/§11 (amended, APRV-38): name of the environment variable holding the operator's HMAC sampling secret. Named indirectly for the same reason channel credentials are (`chat_id_env`, `token_env`): agents may read APPROVAL.md, and a secret they can read is a sample they can predict and then steer their actions out of. The secret itself lives outside the repository and outside any agent-readable path; this policy carries the variable name only. Policy vocabulary in v0.1: the sampler that reads it lands with the M5 daemon.",
+          "examples": ["APPROVAL_SAMPLING_SECRET"]
+        },
+        "skew_tolerance": {
+          "$ref": "#/$defs/duration",
+          "description": "SPEC.md §8 (amended, APRV-58): how far a gate-typed event's `ts` may step backwards from the previous gate-typed event before verification reports a `gate-ts-regression` anomaly. Duration string, `<positive integer><unit>` with unit in ms|s|m|h|d|w, the same grammar `defaults.approval_ttl` uses. Absent means the reference runtime's 2 seconds, which is generous enough that ordinary clock disagreement between NTP-disciplined hosts is not reported and far below the skew a useful lie requires. Operators on one host may tighten it; operators across a WAN with poor time discipline may loosen it. This threshold is REPORT-ONLY: it changes which anomalies a verified log carries and never changes a verdict, an exit code, or an authorization, so widening it hides evidence from a human rather than permitting anything.",
+          "examples": ["250ms", "5s"]
+        },
+        "checkpoint_keys": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[A-Za-z0-9+/]+={0,2}$"
+          },
+          "uniqueItems": true,
+          "description": "SPEC.md §9 (amended, APRV-220): the PUBLIC halves of the keys permitted to sign a `log.checkpoint`, base64 DER SPKI, Ed25519. Unlike every other key-shaped field in this file this one holds the material itself rather than the name of a variable, because a public key is not a secret and the point of writing it here is that it is written somewhere a human has committed and attested: an agent that edited this list would leave a visible diff AND de-attest the policy, which stops every gate operation until a human re-attests. The private halves live in the credential vault and never appear in this file, in the log, or in any path an agent may read. A LIST rather than one key so that rotation can retain a retired key: a checkpoint signed by a key this list does not carry is refused (`checkpoint-key-unknown`), so removing a key that signed anything de-verifies the range it signed rather than tidying the file. Absent, empty, or unreadable means verification SKIPS the checkpoint check with a reason and never reports it as a pass.",
+          "examples": [["MCowBQYDK2VwAyEA9dqzvJnn0VtpD6ETeDRUsCn4l6MPyfaV9Xx6KN+e678="]]
+        },
+        "checkpoint_every": {
+          "$ref": "#/$defs/duration",
+          "description": "SPEC.md §9 (amended, APRV-220): how long a log may go without a human-signed checkpoint before verification says one is due. Duration string, `<positive integer><unit>` with unit in ms|s|m|h|d|w, the same grammar `defaults.approval_ttl` uses. Absent means the cadence is off and nothing is ever reported as due. REPORT-ONLY, and more strongly than `skew_tolerance` is: a lapsed cadence is a WARNING at every layer and there is no path from due to refused anywhere in this runtime. A human who has been away is not a forger, and a gate that refused a log for want of a tap is a gate whose operator turns the check off.",
+          "examples": ["24h", "7d"]
+        }
+      }
+    },
+    "daemon": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "APRV-217 (docs/proposals/incremental-prefix-proof.md): how the long-lived readers of this log prove a cached prefix before they reuse it. Read by `approval daemon run` and `approval up` and by nothing else: one-shot processes, the Claude Code hook included, always prove in full, and `approval log verify` and `approval doctor` never use the cache at all. Every key here is a LATENCY setting whose strictest value is the default, so a policy that omits the block, or the whole block, behaves exactly as the runtime did before it existed.",
+      "properties": {
+        "read_proof": {
+          "type": "string",
+          "enum": ["full", "incremental"],
+          "default": "full",
+          "description": "Which proof a repeat read runs over the prefix it already verified. `full` (THE DEFAULT, and what an absent key means): re-hash every byte of the proved prefix on every read and compare the digest, which is the APRV-43 behaviour byte for byte. `incremental`: carry the un-finalised SHA-256 state at the end of the prefix, feed it only the appended bytes, and re-prove the whole prefix on the cadence below. The cheap guards (schema key, file not shrunk, same-size-implies-same-mtime, head line byte-identical at its offset) run in both modes, and the appended tail is parsed, schema-checked and chain-walked in both. What `incremental` gives up, between full re-proofs, is the detection of a rewrite STRICTLY INSIDE the prefix that preserves the file length, the head line and the mtime — an edit only a party with write access to the log can make, who can already recompute a self-consistent forged chain because the chain is unkeyed. The default is `full` because it is the behaviour an operator has attested to, and moving it is a policy amendment like any other.",
+          "examples": ["full", "incremental"]
+        },
+        "full_reproof_every": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 50,
+          "description": "APRV-217: how many reads one full re-proof may cover under `read_proof: incremental`, the anchoring read included. `1` means every read hashes the whole prefix, which is `full` reached by another spelling. Ignored under `full`. Bounds the window in which an in-place rewrite of the prefix would be served from cache, together with `full_reproof_after`, whichever comes first.",
+          "examples": [50]
+        },
+        "full_reproof_after": {
+          "$ref": "#/$defs/duration",
+          "default": "60s",
+          "description": "APRV-217: how much wall-clock time one full re-proof may cover under `read_proof: incremental`. Duration string, `<positive integer><unit>` with unit in ms|s|m|h|d|w, the same grammar `defaults.approval_ttl` uses. Ignored under `full`. The binding bound on an idle daemon, where the read count grows slowly: at the default 30 s tick this makes every second tick re-prove in full.",
+          "examples": ["60s", "5m"]
+        }
+      }
+    },
+    "vault": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.2/§10.4 (amended, APRV-68): configuration for the encrypted credential vault adapters read from (`.approval/vault.enc`). Exactly one key, and it holds a NAME.",
+      "properties": {
+        "passphrase_env": {
+          "type": "string",
+          "minLength": 1,
+          "description": "SPEC.md §5.2/§10.4 (amended, APRV-68): name of the environment variable holding the vault passphrase, from which the AES-256-GCM key is derived by scrypt. Named indirectly for the same reason `audit.sampling_secret_env`, `chat_id_env` and `token_env` are: agents may read APPROVAL.md, and a passphrase they can read is a vault they can open. The passphrase itself lives outside the repository and outside any agent-readable path; this policy carries the variable name only. Absent means the runtime reads `APPROVAL_VAULT_PASSPHRASE`, because the variable's NAME is not a permission and an unnamed one must not lock an operator out of credentials they created.",
+          "examples": ["APPROVAL_VAULT_PASSPHRASE"]
+        }
+      }
+    },
+    "channels": {
+      "type": "object",
+      "description": "SPEC.md §5.1/§10.3: map of channel name -> channel configuration. Known channels are typed; unknown channel names are accepted as objects so a third-party transport plugin does not invalidate the whole policy (and, per §5.2, force everything to `manual`).",
+      "additionalProperties": { "type": "object" },
+      "properties": {
+        "telegram": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "SPEC.md §5.1/§11: Telegram channel. Credentials are named indirectly by environment variable — the policy file holds env var NAMES, never token values, because agents may read APPROVAL.md but must never reach channel credentials.",
+          "properties": {
+            "chat_id_env": {
+              "type": "string",
+              "minLength": 1,
+              "description": "SPEC.md §5.1: name of the environment variable holding the Telegram chat id.",
+              "examples": ["APPROVAL_TG_CHAT"]
+            },
+            "token_env": {
+              "type": "string",
+              "minLength": 1,
+              "description": "SPEC.md §5.1: name of the environment variable holding the Telegram bot token.",
+              "examples": ["APPROVAL_TG_TOKEN"]
+            },
+            "delivery": {
+              "type": "string",
+              "enum": ["paced", "burst"],
+              "default": "paced",
+              "description": "SPEC.md §10.3 (APRV-216): how a listener puts the pending set in front of the approver. `paced`, the default and what an absent key means, sends one summary line and the OLDEST pending request, then the next one once that request is decided, skipped, or passed over; the bot commands /queue, /skip and /next drive it. `burst` sends every pending request the process has not sent yet, on every cycle, behind the APRV-196 re-delivery banner. Neither mode changes what is pending: that is re-derived from the verified log on every cycle in both, and the order and the currently shown item are process memory whose loss costs a re-send and nothing else. The enum is closed because an unrecognised mode cannot be ordered against these two; a policy naming one fails validation, which fails closed to all-manual rather than to a guessed delivery.",
+              "examples": ["paced", "burst"]
+            },
+            "prompt": { "$ref": "#/$defs/promptLayout" }
+          }
+        },
+        "web": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "SPEC.md §5.1/§10.3: local web channel.",
+          "properties": {
+            "port": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 65535,
+              "description": "SPEC.md §5.1: TCP port for the local approval UI. Valid port range only; 0 (ephemeral) is excluded because the policy must name a port a human can navigate to.",
+              "examples": [4680]
+            },
+            "prompt": { "$ref": "#/$defs/promptLayout" }
+          }
+        },
+        "cli": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "SPEC.md §5.1/§10.3: the zero-config terminal channel. It needs no credential and no port, so until APRV-218 it had nothing to configure and the key did not exist; a policy that omits it is the norm and always will be.",
+          "properties": {
+            "prompt": { "$ref": "#/$defs/promptLayout" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "promptRow": {
+      "type": "string",
+      "enum": [
+        "action_key",
+        "task",
+        "class",
+        "command_breakdown",
+        "protected_path",
+        "policy_diff",
+        "policy_load",
+        "autonomy",
+        "provenance",
+        "state",
+        "requested_ts",
+        "waiting",
+        "ttl_remaining_ms",
+        "payload_hash",
+        "attestation",
+        "budgets",
+        "chain",
+        "token_delivery",
+        "est_cost_usd",
+        "gloss",
+        "summary",
+        "rationale",
+        "confidence"
+      ],
+      "description": "SPEC.md §5.2/§10.3 (APRV-218): one INFORMATIONAL row of a channel prompt, named by the `ChannelRequest` member it renders. The enum is closed for the reason `channels.telegram.delivery`'s is: a name this runtime cannot place is a row the author believes is in force that nothing reads, so it fails validation, which fails the policy closed to all-`manual` rather than to a silently ignored key. `fullPayload` is deliberately absent — the canonical rendering of SPEC.md §9 is not a row, it is rendered verbatim, and no layout key can reorder, shorten, or remove it."
+    },
+    "promptRows": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/promptRow" }
+    },
+    "promptLayout": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.2/§10.3 (APRV-218): which rows this channel's prompt shows, and in what order. Absent means the layout the channel ships, so every policy written before this key renders exactly as it did. A layout chooses among rows the approver READS; it cannot touch what the approver SIGNS. Three things stay out of its reach: the canonical payload block (not a row), the buttons (a prompt with no way to answer it is not a prompt), and the computed/claimed split, which is a property of the field rather than of the layout — `rows` reorders, and a channel partitions by kind afterwards, so a claimed line cannot be moved into the computed block.",
+      "properties": {
+        "rows": {
+          "$ref": "#/$defs/promptRows",
+          "description": "ORDER ONLY. The rows named here render in this order, ahead of every row not named; those keep their default relative order behind them. It is never a whitelist: a `ChannelRequest` widened by a later task must not lose a field to a list written before that field existed. Use `hide` to remove a row and `always` to add one.",
+          "examples": [["class", "command_breakdown", "task", "waiting"]]
+        },
+        "always": {
+          "$ref": "#/$defs/promptRows",
+          "description": "Visibility UP: a row this channel renders only when abnormal (Telegram's `autonomy`, `budgets` and `attestation`, per APRV-163), or not at all by default (Telegram's `task`, `state`, `chain`, `provenance`, `requested_ts`, `ttl_remaining_ms` and `payload_hash`, per APRV-143 and APRV-163), renders on every prompt instead. The anomaly mark stays a statement about the VALUE: a row forced on here carries it only when the value is in fact the reason to look.",
+          "examples": [["budgets", "task"]]
+        },
+        "hide": {
+          "$ref": "#/$defs/promptRows",
+          "description": "Visibility DOWN: the row never renders on this channel. Refused for the rows required for a decision — `action_key`, `class`, `command_breakdown`, `protected_path`, `policy_diff`, `policy_load` — and refused at policy load with the machine-readable keyword `prompt-row-required`, which fails the whole policy closed. `payload_hash` is NOT among them because the bound hash is stated inside the canonical block on every channel, so hiding the row removes a duplicate rather than the binding. Naming one row in both `always` and `hide` is refused rather than resolved by precedence: an author who wrote both believes one of them, and picking for them would be a guess.",
+          "examples": [["provenance", "chain", "requested_ts"]]
+        }
+      }
+    },
+    "autonomy": {
+      "type": "string",
+      "enum": ["human-only", "manual", "supervised-live", "supervised", "supervised-retro", "autonomous"],
+      "description": "SPEC.md §5.2 (amended, APRV-127; widened, APRV-185): autonomy level, strictest first — `human-only` (reserved to human hands: a person performs the action outside agent execution, so no agent may request it, be granted it, or run it, and every gate verb refuses it with the code `class-human-only`) > `manual` (human sign-off before every action) > `supervised-live` (a policy-declared fraction of actions blocks on the human gate exactly as `manual` does; the rest proceed) > `supervised-retro` (executes immediately, sampled for retrospective review) > `autonomous` (executes freely). `supervised` is the pre-APRV-127 spelling and is an ALIAS OF `supervised-retro`, so every policy written before the split keeps the meaning its author gave it; the runtime records a load-time note naming the alias rather than silently reinterpreting it. The enum is closed: an unrecognised level cannot be ordered against the others, so it must fail validation rather than be guessed at.",
+      "examples": ["human-only", "manual", "supervised-live", "supervised-retro"]
+    },
+    "liveRate": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "maximum": 1,
+      "description": "SPEC.md §5.2 (amended, APRV-127): the fraction of `supervised-live` actions in a class that BLOCK on the human gate before executing, as a proportion in (0, 1]. Selection is HMAC-SHA-256 over the action's `payload_hash` under the operator-held secret named by `audit.sampling_secret_env` — the same construction `audit.supervised_sample_rate` uses, reused rather than reinvented, so an agent cannot predict its own luck and an operator holding the secret can verify every selection after the fact. Determinism is a required property, not an implementation detail: identical payload bytes always select identically, so a retry cannot re-roll until it comes up unsampled. Zero is excluded because \"never gate live\" is spelled `autonomy: supervised-retro`, and 1 is admitted because \"gate every one of them\" is a legitimate, if verbose, way to say `manual` for a class an author expects to relax later.",
+      "examples": [0.01, 0.1]
+    },
+    "retroRate": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "maximum": 1,
+      "description": "SPEC.md §5.2 (amended, APRV-183): the fraction of a supervised class's executed actions drawn into the retrospective review backlog, as a proportion in (0, 1]. Overrides `audit.supervised_sample_rate` for this class and for nothing else; an absent key leaves the class on the global rate. Selection is the same construction the global rate uses, HMAC-SHA-256 over the subject record's event hash under the operator-held secret named by `audit.sampling_secret_env`, so there is one mechanism and one secret, and an operator holding that secret can recompute any verdict from the record's own hash. Zero is excluded because \"never review this class\" is a claim a policy makes by raising the class out of supervision, and a rate of 0 written here would read as a review budget the author meant to fill in; 1 is admitted because \"review every one of them\" is a legitimate setting for a small, high-consequence class.",
+      "examples": [0.25, 1]
+    },
+    "defaultAutonomy": {
+      "type": "string",
+      "enum": ["human-only", "manual", "supervised", "supervised-retro", "autonomous"],
+      "description": "SPEC.md §5.2 (amended, APRV-127; widened, APRV-185): the autonomy levels a policy may name as its DEFAULT. Identical to `autonomy` less `supervised-live`, which carries a required `live_rate` that `defaults` has nowhere to declare. `human-only` IS admitted, and the asymmetry with `supervised-live` is the reason: that level is excluded for a key `defaults` cannot hold, and `human-only` carries no key at all, so an author naming it here declares maximal strictness over everything the policy did not name — a statement a policy is entitled to make. It is NOT the fail-closed target. A policy that fails to load still resolves every class to `manual`, because a broken policy must stay recoverable through its own gate, and a file whose every class became `human-only` would put the repair for a typo behind a level that admits no gated repair."
+    },
+    "duration": {
+      "type": "string",
+      "pattern": "^[1-9][0-9]*(?:ms|s|m|h|d|w)$",
+      "description": "SPEC.md §5.1: duration string `<positive integer><unit>`, unit in ms|s|m|h|d|w. Leading zeros, zero durations, negatives, fractions, whitespace and compound forms are all rejected so parsing is unambiguous across implementations."
+    },
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_-]*$",
+      "description": "SPEC.md §5.1: lowercase identifier used for approver ids — starts alphanumeric, then alphanumerics, `_` or `-`. Case-insensitive collisions are excluded by construction."
+    },
+    "classPattern": {
+      "type": "string",
+      "pattern": "^(?:[a-z0-9][a-z0-9_-]*|\\*)(?:\\.(?:[a-z0-9][a-z0-9_-]*|\\*))*$",
+      "description": "SPEC.md §5.2 and §7: a side-effect class pattern — one or more dot-separated segments, each either a literal lowercase segment ([a-z0-9] then [a-z0-9_-]) or the wildcard `*`. Covers exact classes (`financial.spend`), trailing-depth wildcards (`read.*`), interior single-segment wildcards (`calendar.*.own`) and the bare `*`. Empty keys, empty segments (`read..write`), leading/trailing dots, uppercase and whitespace are rejected: an unmatchable key would be a rule the author believes is in force that can never fire."
+    },
+    "classRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["autonomy"],
+      "description": "SPEC.md §5.1: a class rule. The shorthand form is `{ autonomy }` alone; the full form adds `approvers` and `limits`. Both are this one shape — `autonomy` is always REQUIRED, since a rule without it cannot decide anything, and unknown keys are rejected so a typo'd constraint is never silently ignored.",
+      "allOf": [
+        {
+          "$comment": "SPEC.md §5.2 (amended, APRV-127): `live_rate` belongs to `supervised-live` and to nothing else. Required there, because a live mode with no fraction declares a control without saying how much of it runs, and the runtime would have to invent the number an author did not write. Forbidden everywhere else, because a rate sitting on a `manual`, `supervised-retro` or `autonomous` rule is a fraction its author believes is in force that nothing reads — the same silent no-op this schema's closed shape exists to prevent. APRV-185 adds `human-only` to that everywhere-else, and the `else` branch below already carries it with no new clause: a level whose actions no agent may take has no fraction of them to gate, so a `live_rate` written there is a control its author believes is running over a population of size zero.",
+          "if": {
+            "type": "object",
+            "properties": { "autonomy": { "const": "supervised-live" } },
+            "required": ["autonomy"]
+          },
+          "then": {
+            "type": "object",
+            "properties": { "live_rate": { "$ref": "#/$defs/liveRate" } },
+            "required": ["live_rate"]
+          },
+          "else": {
+            "type": "object",
+            "properties": { "live_rate": false }
+          }
+        },
+        {
+          "$comment": "SPEC.md §5.2 (amended, APRV-183): `retro_rate` is the per-class retrospective sampling rate, and it belongs to the levels that have a retrospective pool. OPTIONAL on `supervised`, `supervised-retro` and `supervised-live` — absent means the class is sampled at `audit.supervised_sample_rate`, so every policy written before this key keeps the rate its author configured. `supervised-live` admits it because the fraction the live draw does NOT gate executes and stays eligible for retrospective review, which is a real pool with a real rate. FORBIDDEN on `manual`, `autonomous` and (APRV-185) `human-only`, and forbidden as a LOAD ERROR rather than as a stated no-op, which is exactly how `live_rate` treats the levels it does not belong to: a `manual` class has no retrospective pool because every one of its actions was decided in advance, an `autonomous` class is not supervised at all, a `human-only` class has no agent execution to review, and a rate sitting on any of them is a review fraction its author believes is running that nothing reads. The `else` branch carries all three with no new clause, which is why the `if` enumerates the supervised levels rather than the forbidden ones.",
+          "if": {
+            "type": "object",
+            "properties": {
+              "autonomy": { "enum": ["supervised", "supervised-retro", "supervised-live"] }
+            },
+            "required": ["autonomy"]
+          },
+          "then": {
+            "type": "object",
+            "properties": { "retro_rate": { "$ref": "#/$defs/retroRate" } }
+          },
+          "else": {
+            "type": "object",
+            "properties": { "retro_rate": false }
+          }
+        }
+      ],
+      "properties": {
+        "autonomy": {
+          "$ref": "#/$defs/autonomy",
+          "description": "SPEC.md §5.2: autonomy for actions matching this class pattern."
+        },
+        "live_rate": { "$ref": "#/$defs/liveRate" },
+        "retro_rate": { "$ref": "#/$defs/retroRate" },
+        "approvers": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "SPEC.md §5.1: approver ids permitted to decide requests for this class. Ids are expected to be keys of the top-level `approvers` map; that cross-reference is a runtime check, not a schema constraint.",
+          "items": { "$ref": "#/$defs/identifier" }
+        },
+        "limits": {
+          "type": "object",
+          "minProperties": 1,
+          "description": "SPEC.md §5.1/§5.2: per-class ceilings, e.g. { per_action_usd: 25, daily_usd: 100 }. Limit names are open-ended (the taxonomy in §7 grows), but every value MUST be a positive number: zero or negative would express 'no action may ever pass', which is spelled `autonomy: manual` instead, and a non-numeric limit cannot participate in budget arithmetic. Two request-volume names are documented explicitly (SPEC.md §5.2) and are counts, hence integers: `max_pending` and `requests_per_hour`.",
+          "additionalProperties": { "$ref": "#/$defs/positiveNumber" },
+          "propertyNames": { "$ref": "#/$defs/identifier" },
+          "properties": {
+            "max_pending": {
+              "$ref": "#/$defs/positiveInteger",
+              "description": "SPEC.md §5.2: maximum simultaneously pending requests for this class; further requests are refused at intake with reason `queue-full`. A count, hence an integer. Policy vocabulary in v0.1: enforcement lands with M4/M5, so a policy may declare it before any runtime reads it."
+            },
+            "requests_per_hour": {
+              "$ref": "#/$defs/positiveInteger",
+              "description": "SPEC.md §5.2: rolling-window ceiling on request creation, evaluated per origin; excess is refused with reason `rate-limited` and logged. A count, hence an integer. The per-origin windowing (and enforcement generally) lands with M4/M5; v0.1 only accepts the vocabulary."
+            }
+          }
+        }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "description": "SPEC.md §5.1/§5.2: a budget scope. Budgets are conjunctive with class limits and are computed from the append-only log.",
+      "properties": {
+        "daily_usd": {
+          "$ref": "#/$defs/positiveNumber",
+          "description": "SPEC.md §5.1: maximum spend in USD per rolling day for this scope."
+        },
+        "daily_actions": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "description": "SPEC.md §5.1: maximum number of side-effecting actions per rolling day for this scope. A count, hence an integer."
+        },
+        "max_pending": {
+          "$ref": "#/$defs/positiveInteger",
+          "description": "SPEC.md §5.2: maximum simultaneously pending requests across this scope (the global counterpart of `limits.max_pending`); further requests are refused at intake with reason `queue-full`. A count, hence an integer. Policy vocabulary in v0.1: enforcement lands with M4/M5."
+        }
+      }
+    },
+    "positiveInteger": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "description": "A strictly positive whole number, used for counts (pending requests, requests per hour). Zero and negatives are rejected for the same reason as `positiveNumber`: an unreachable ceiling is spelled `autonomy: manual`, not `0`."
+    },
+    "positiveNumber": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "description": "A strictly positive number. Zero and negatives are rejected: budget and limit arithmetic treats them as unreachable ceilings, which policy authors express with `autonomy: manual`."
+    },
+    "protectedPath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.?(?:/|$))(?!.*//)[^*?\\[\\]{}\\\\\\s]+$",
+      "description": "A repo-relative path: exact file (`SPEC.md`) or directory prefix with a trailing `/` (`design/`). Leading `/`, `.`/`..` segments, whitespace and the glob characters `* ? [ ] { }` are rejected — each would be a path the matcher cannot honour literally, and silently ignoring one would leave the author believing a file is gated when it is not. Named as a `$def` since APRV-266 so the bare-string entry and the `path` of a routed entry are held to one grammar and cannot drift apart."
+    }
+  }
+}

package/schema/sample-record.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://approval.md/schema/sample-record.schema.json",
+  "$comment": "CC0 1.0. See schema/LICENSE.",
+  "title": "Sample record",
+  "description": "Exercise schema for the write-boundary validation harness. Not a runtime record type: it exists so the harness proves additionalProperties rejection and format enforcement end to end.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "ts"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Opaque record identifier."
+    },
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 timestamp."
+    },
+    "note": {
+      "type": "string",
+      "description": "Optional free-text note."
+    }
+  }
+}

package/schema/values.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://approval.md/schema/values.schema.json",
+  "$comment": "CC0 1.0. See schema/LICENSE.",
+  "title": "APPROVAL.md values block",
+  "description": "SPEC.md §5.3: the parsed YAML of the OPTIONAL second fenced block inside APPROVAL.md, marked ```yaml approval-values```. It is the human-to-agent direction of a file that until now carried control in one direction only: the policy block says what an agent may do, and this block says what the operator values and how they read what comes back. It is human-authored GUIDANCE and it is never policy. No enforcement path reads it — not routing, not policy matching, not the sampler, not budgets, not token minting, not execution — which is SPEC.md §11.1 invariant 10 (\"guidance never reaches enforcement\"), pinned by tests/values-inert.test.ts. A values block that fails this schema never makes the policy block unloadable; the two are parsed and judged independently, and the failure of guidance can never widen or narrow a class. Because the block lives inside APPROVAL.md, editing it changes the file's bytes and therefore invalidates the whole-file attestation, so a values edit goes through the same attestation ceremony as a policy edit (SPEC.md §5.3). Absence is a declaration, never a default: a file with no values block means the operator has declared no values here, and an agent-facing surface must render it as absence rather than inventing a neutral middle.\n\nThe key set is closed (additionalProperties: false at every level) for the same reason the policy block is: an unrecognised key is something the author believed was in force and the runtime did not understand. Keys deliberately REJECTED, recorded here so the rejection is reviewable rather than forgotten: (1) anything class-shaped or override-shaped — a `classes:` map, an `autonomy:`, a `defaults:`, an `overrides:` — because that is policy, and admitting a policy-shaped key into the guidance block would make invariant 10 unprovable: a static guard cannot show that guidance never reaches enforcement once guidance is allowed to LOOK like enforcement; (2) `priority` and `weight`, because a number invites arithmetic and there is no arithmetic to do here — nothing ranks, sums or thresholds these entries, and a field that suggests it does would be read as a knob; (3) `hate`, because a fourth standing grade invites an escalation ladder, and the standing lists are deliberately three (love/like/dislike). Intensity is carried where it is actually observed, by the event vocabulary's `reaction` (disliked|indifferent|liked|loved, SPEC.md §5.2), not by an ever-longer list of nouns in a static file.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "SPEC.md §5.3: values format version. The only REQUIRED key: a block with no version cannot be interpreted safely under a future format revision. It is an INTEGER here, unlike the policy block's quoted string version (\"0.1\"), and deliberately so. The policy version is quoted because it is a dotted format identifier that YAML would otherwise coerce to the float 0.1, losing the distinction between \"0.10\" and \"0.1\". This block has no dotted versions and never will: it is a small, closed key set that either is revision 1 or is a revision this runtime does not know, so a bare integer is the honest type and leaves nothing for YAML to coerce.",
+      "examples": [1]
+    },
+    "love": {
+      "$ref": "#/$defs/valueList",
+      "description": "SPEC.md §5.3: what the operator loves, in their own words. The strongest of the three standing grades. Guidance for an agent reading the file, never an input to any decision the runtime makes."
+    },
+    "like": {
+      "$ref": "#/$defs/valueList",
+      "description": "SPEC.md §5.3: what the operator likes. The middle standing grade, and the one that carries most of the ordinary content."
+    },
+    "dislike": {
+      "$ref": "#/$defs/valueList",
+      "description": "SPEC.md §5.3: what the operator dislikes. The negative standing grade. It is NOT a prohibition: a prohibition belongs in the policy block, where it is enforced; an entry here is a preference an agent should weigh in how it works, and a runtime that refused an action because of it would be enforcing guidance."
+    },
+    "wants": {
+      "$ref": "#/$defs/valueList",
+      "description": "SPEC.md §5.3: what the operator wants FROM the agent, as behaviour rather than as taste. Where love/like/dislike describe the operator, this describes the working relationship they are asking for. Examples: \"honest opinions on the work, including when you think a task is wrong\"; \"a journal entry of about five points per milestone\". Still guidance: nothing here is checked, counted, or enforced, and an agent that does not do these things is not refused by anything."
+    },
+    "responds": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "SPEC.md §5.3: how the operator reads and answers — the shape of the human end of the loop, so an agent can read silence, terseness or delay correctly. Deliberately a SINGLE SCALAR rather than a list: a list here would grow into a second rules document sitting beside the policy block, and the one thing this block must never become is a place where rules live outside the enforced file. One sentence or two, and no more room than that.",
+      "examples": [
+        "Usually within the hour on the phone; a bare 'ok' means yes and is not curtness."
+      ]
+    }
+  },
+  "$defs": {
+    "valueList": {
+      "type": "array",
+      "uniqueItems": true,
+      "maxItems": 20,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 200
+      },
+      "description": "SPEC.md §5.3: a standing list of short human-authored statements. Entries are unique (a repeated entry is an editing accident, and there is no counting here for a repeat to mean anything to) and capped at twenty of at most 200 characters each. The caps are not storage limits: this block is read by a person and by an agent's prompt, and a list long enough to need scrolling is one nobody reads, which is the failure mode guidance has instead of a validation error. An empty array is valid and says the operator considered this grade and had nothing to put in it."
+    }
+  }
+}