approval-md 0.2.0 → 0.4.0

package/schema/policy.schema.json

@@ -85,6 +85,21 @@
         ]
       ]
     },
+    "read_scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.2 (amended, APRV-347): the directories an agent's reads may stay inside. Reads outside every root classify `read.file.out_of_scope`, both for shell readers (`cat`, `head`, `tail`, `sed -n`, `grep`, `rg`, `ls`, `find`, and kin) and for a harness read tool that names a path (Claude Code's `Read`, `Glob` and `Grep`). ADDITIVE ONLY, exactly as `protected_paths` is: the built-in roots — the GATE ROOT (the directory holding this policy file), the session scratchpad, and the system temp root — are in scope whatever this block says or omits, because a runtime that could be denied its own policy, log and workspace could not run at all, and a policy able to shrink its own read scope would be a policy an agent could narrow until nothing was gated. Omitting the block entirely means the built-in roots alone, which is the common case and the whole of the muse jail: a session whose `APPROVAL.md` sits in `~/dev/muse` has `~/dev/muse` as its gate root and every sibling under `~/dev` is out of scope with no grammar here at all. An unparseable value is refused at load like every other key in this closed schema, and a refused policy means every class is `manual` (SPEC.md §5.2, fail closed).",
+      "properties": {
+        "roots": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "Extra directories whose reads stay ordinary `read.shell`. An absolute path is taken as written; a relative path is resolved against the gate root, so a policy stays portable between a checkout and a clone of it. Each entry is compared by PATH SEGMENT after the runtime resolves it, so a symlink cannot smuggle a read out of a root and `/dev/muse-other` does not match a root of `/dev/muse`. No globs and no negation: a pattern language half-implemented here would be a scope the author believed was in force and the runtime did not apply.",
+          "items": { "$ref": "#/$defs/readRoot" },
+          "examples": [["/Users/carter/dev/shared-fixtures"], ["../vendor"]]
+        }
+      },
+      "examples": [{ "roots": ["/opt/reference-corpus"] }]
+    },
     "approvers": {
       "type": "object",
       "additionalProperties": false,
@@ -103,11 +118,60 @@
               "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 }
+            },
+            "senders": {
+              "type": "object",
+              "minProperties": 1,
+              "additionalProperties": false,
+              "description": "SPEC.md §5.2/§10.3 (amended, APRV-324): the transport account ids this person decides from, per channel. ADDITIVE and OPTIONAL: a policy that declares none behaves exactly as every build before this key existed, recording each decision against the actor the listener process was launched with. Declaring the first mapping for a channel is what turns enforcement on for that channel — from then on a sender that channel authenticates and this block does not name is REFUSED (`sender-unmapped`) rather than attributed to the listener's own identity, because a fallback there would let anyone who can reach the configured chat approve as the operator. Written person to sender rather than sender to person, so each human's identity is in one place and a duplicate id is visible on the page; the runtime inverts it at lookup and REFUSES a policy in which two approvers claim one id (`sender-ambiguous`, a load failure, so every class resolves `manual`). The value is the transport's own attribution and never a name the sender chose: for `telegram` it is the numeric `callback_query.from.id`, as a string, and never `from.username`, which is mutable and reusable and would transfer an identity with a handle. This block is an operator ASSERTION that an account belongs to a person, which is what the `policy.core` attestation ceremony makes accountable; it is not, and cannot be, proof of personhood.",
+              "propertyNames": { "$ref": "#/$defs/senderChannel" },
+              "properties": {
+                "telegram": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^(?:[0-9]+|hmac-sha256:[0-9a-f]{64})$",
+                  "description": "The Telegram account this person decides from, in one of two forms (SPEC.md §5.2, APRV-324 and APRV-370).\n\nRAW: the account id the Bot API reports as `callback_query.from.id`, as a decimal string. Digits only, because a `@handle` here would be a mapping key the transport never sends and `from.username` is mutable and reusable.\n\nKEYED: `hmac-sha256:<64 lowercase hex>`, the HMAC-SHA-256 of that same decimal string under an operator-held key named by `APPROVAL_SENDER_KEY`, minted by `approval setup sender-key`. It exists because a policy and a log that are PUBLISHED disclose the account otherwise, once in the file and then on every decision. A plain unkeyed digest would not fix that: a Telegram id is a short decimal number and the whole space is enumerable on a laptop, so the digest has to be keyed to be a digest of anything.\n\nThe form is per entry: a policy may carry both while a migration is in progress, and they cannot collide, since a decimal id can never look like the prefixed form. A channel mapped in the keyed form with no key in the listener's environment REFUSES every decision on that channel (`sender-key-unavailable`) rather than falling back to a raw comparison, because without the key the runtime can compute no digest and therefore cannot run the ambiguity check the mapping rests on. The key is not an authenticator: nothing about the gate's safety rests on its secrecy, and losing it costs the ability to resolve accounts, never the ability to refuse.",
+                  "examples": [
+                    "12345678",
+                    "hmac-sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
+                  ]
+                },
+                "edgeos": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^(?:[A-Za-z0-9][A-Za-z0-9._-]{0,127}|hmac-sha256:[0-9a-f]{64})$",
+                  "description": "The EdgeOS account this person decides from, in one of two forms (SPEC.md §5.2/§10.3, APRV-455, on the ground APRV-324 laid for `telegram`).\n\nRAW: the stable human id the EdgeOS identity service returns from `/humans/me` for the session the person authenticated in, as a string. The runtime treats it as OPAQUE and compares it byte for byte; the grammar admits what such an id is made of (an ASCII letter or digit, then up to 127 letters, digits, `.`, `_` or `-`), which covers a UUID and a decimal id alike. It holds no `:` and no whitespace, so a raw id can never be mistaken for the keyed form and can never contain the separator the runtime's sender index uses. Never an email address or a display name: those are chosen or changed by the person, and a mapping keyed on one would transfer an identity with an edit.\n\nKEYED: `hmac-sha256:<64 lowercase hex>`, the HMAC-SHA-256 of that same id under the operator-held `APPROVAL_SENDER_KEY`, exactly as for `telegram` and for the same reason: a published policy and a published log otherwise disclose the account.\n\nThe id reaches the runtime through `approval channel relay`, whose authenticated caller (the operator's control plane, holding `APPROVAL_RELAY_SECRET`) reports which EdgeOS session made the gesture. The daemon trusts that report the way it trusts the Telegram Bot API's `from.id`: it is operator trust in a relay, stated as such, and the resident cannot choose the id the relay attributes to them.",
+                  "examples": [
+                    "4f1c2a9e-7b3d-4e8a-9c21-5d6e7f8a9b0c",
+                    "hmac-sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
+                  ]
+                }
+              },
+              "examples": [
+                { "telegram": "12345678" },
+                {
+                  "telegram": "hmac-sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
+                },
+                { "telegram": "12345678", "edgeos": "4f1c2a9e-7b3d-4e8a-9c21-5d6e7f8a9b0c" }
+              ]
             }
           }
         }
       }
     },
+    "daemons": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "SPEC.md §5.2 (amended, APRV-383): the daemon instance ids permitted to append to this log. An ALLOWLIST, and the counterpart of `approvers` one layer down: that key says which humans may decide, this one says which daemon processes may write the records of those decisions down.\n\nIt exists for the hosted case (`design/hosted-daemon-identity.md`): when one party runs the daemon for another, records the daemon appends carry `daemon` (see `event.schema.json`) naming the instance that wrote them, and this list is how the tenant's own attested policy states which of them it expects. A daemon whose id this list does not name is refused AT THE WRITE BOUNDARY with `daemon-not-allowed` and writes nothing.\n\nABSENT means NO RESTRICTION, not an empty list: a policy that never declares the key behaves exactly as every policy written before it existed, and the daemon-written records still carry their id. An empty array is a policy that admits no daemon at all, which is a thing an author may say and the runtime will enforce.\n\nWhat being LISTED buys is nothing (SPEC.md §11.1 invariant 4). The id is self-reported by the writing process, so it may only ever cost a daemon the ability to write: no verdict, autonomy, budget, floor, sampling draw, token or TTL reads this key or the record field, and a hostile host holding the tenant's log handle is not what this defends against. What it catches is a daemon started against the wrong tenant's log, a second daemon nobody meant to leave running, and a rebuilt container whose id changed, each of which used to write records indistinguishable from the intended daemon's.\n\nIt is a top-level key rather than a member of the `daemon` block below, and the distinction is worth the two names: `daemon` (singular) is how THIS daemon reads a log it already may write, every key in it a latency setting whose strictest value is the default, while `daemons` (plural) is an ENFORCEMENT key deciding WHICH daemons may write at all. Read only from an ATTESTED policy, like every other fact a refusal is derived from.",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 64,
+        "pattern": "^[a-z0-9][a-z0-9._-]*$",
+        "description": "One daemon instance id, in the same grammar the `daemon` record field carries: lowercase letters, digits, `.`, `-` and `_`, starting with a letter or digit. Either an id the operator declared in that daemon's launch environment through `APPROVAL_DAEMON_ID`, or the derived `daemon-<instance id>` form that `approval status` and `approval doctor` print for the instance they are run against."
+      },
+      "examples": [["daemon-3f2a9c11"], ["village-goa-1", "village-goa-2"]]
+    },
     "classes": {
       "type": "object",
       "additionalProperties": false,
@@ -173,7 +237,7 @@
     "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.",
+      "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. Not to be confused with the top-level `daemons` list above (APRV-383), which is an enforcement key naming WHICH daemon instances may append to this log; this block is how a daemon that may already write reads.",
       "properties": {
         "read_proof": {
           "type": "string",
@@ -328,7 +392,7 @@
     "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.",
+      "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 a DEPRECATED ALIAS OF `supervised-retro` (APRV-335), 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, and reports it in its health surfaces. Write `supervised-retro`: the bare spelling is admitted here for compatibility and a future version of this schema removes 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": {
@@ -348,7 +412,7 @@
     "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."
+      "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. The bare `supervised` is admitted here on the same terms it is admitted there, as the DEPRECATED ALIAS of `supervised-retro` (APRV-335): a policy that names it still defaults to retrospective supervision, the runtime notes the spelling at load and in its health surfaces, and a future version of this schema removes it. `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",
@@ -360,6 +424,12 @@
       "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."
     },
+    "senderChannel": {
+      "type": "string",
+      "enum": ["telegram", "edgeos"],
+      "description": "SPEC.md §10.3 (amended, APRV-324; widened, APRV-455): a channel whose transport attributes a gesture to an account id, and therefore the only kind of channel an `approvers.<id>.senders` entry may name. `telegram` qualifies because the Bot API reports `callback_query.from.id`, which the sender cannot choose. `edgeos` qualifies on the same ground: the gesture arrives through `approval channel relay`, authenticated by a shared secret from the daemon's launch environment, from a control plane that attributes it to the EdgeOS `/humans/me` id of the session the person signed in with, which the person cannot choose either. In both cases the daemon trusts the relay's report of who acted, and that is operator trust (APRV-422: no hosted service has authority over decisions; the relay carries a person's gesture and decides nothing). `web` and `cli` are deliberately absent: an unauthenticated form post names nobody and a local process names whoever runs it, so a sender mapping for either would be a binding the runtime cannot check and an identity key the channel cannot support.",
+      "examples": ["telegram", "edgeos"]
+    },
     "classPattern": {
       "type": "string",
       "pattern": "^(?:[a-z0-9][a-z0-9_-]*|\\*)(?:\\.(?:[a-z0-9][a-z0-9_-]*|\\*))*$",
@@ -369,7 +439,7 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["autonomy"],
-      "description": "SPEC.md §5.1: a class rule. The shorthand form is `{ autonomy }` alone; the full form may add rates, `allow_irreversible`, `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.",
+      "description": "SPEC.md §5.1: a class rule. The shorthand form is `{ autonomy }` alone; the full form may add rates, `allow_irreversible`, `agent_may_request`, `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.",
@@ -421,6 +491,22 @@
               }
             }
           }
+        },
+        {
+          "$comment": "SPEC.md §5.2 (amended, APRV-445): `agent_may_request: true` opens the `propose` verb to a class an operator declared, so the level it sits on must be one an agent may ask about. Refused on `human-only` as a load error: a human-only class is inert to agents (SPEC.md §11.1 invariant 9), and a flag saying an agent may file a request for one is a door the gate would only slam. False is admitted everywhere as the explicit spelling of the default.",
+          "if": {
+            "type": "object",
+            "properties": { "agent_may_request": { "const": true } },
+            "required": ["agent_may_request"]
+          },
+          "then": {
+            "type": "object",
+            "properties": {
+              "autonomy": {
+                "enum": ["supervised-live", "supervised", "supervised-retro", "autonomous", "manual"]
+              }
+            }
+          }
         }
       ],
       "properties": {
@@ -434,6 +520,10 @@
           "type": "boolean",
           "description": "SPEC.md §5.2/§7 (amended, APRV-317): explicit permission for truthful `reversible: false` actions matching this rule to retain its nonmanual autonomy. Omission or false preserves the manual floor. Every equally most-specific matching rule must say true; defaults and action metadata cannot supply it."
         },
+        "agent_may_request": {
+          "type": "boolean",
+          "description": "SPEC.md §5.2 (amended, APRV-445): whether an agent may open a request in this class with `approval propose`, naming the class itself and carrying its payload inline. Absent and false mean no. It is read two ways and only these two: on a key that names the class EXACTLY, and on a declared family key `<prefix>.*` the class falls under. `propose` additionally requires the class to be an exact key of `classes`, so a wildcard rule alone never makes a class proposable; the exact key's own value wins when it states one, and otherwise the most specific family that states one decides. Adding or changing it is a policy edit like any other and takes a human re-attestation, which voids pending requests (`policy-drift`)."
+        },
         "approvers": {
           "type": "array",
           "minItems": 1,
@@ -496,6 +586,12 @@
       "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."
+    },
+    "readRoot": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^*?\\[\\]{}\\\\\\s$~]+$",
+      "description": "A directory whose reads stay in scope (APRV-347). Absolute, or relative to the gate root. The glob characters `* ? [ ] { }`, whitespace, `$` and a leading `~` are rejected for the same reason `protectedPath` rejects them: this runtime compares path segments and expands nothing, so a value it would have to expand is one an author believes is in force and the runtime does not apply. Unlike `protectedPath`, an absolute path and `..` segments are both ALLOWED, because a read root may legitimately sit beside the gate root (`../vendor`) or anywhere on the machine — a root widens the scope and is resolved on disk before it is compared, where `..` has a meaning."
     }
   }
 }

package/schema/values.schema.json

@@ -3,16 +3,16 @@
   "$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.",
+  "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; (4) `wants`, which the first revision carried for what the operator asks of the agent as behaviour, folded into `like` by APRV-336. A request about behaviour and a preference about the output are graded by the same person in the same way, and one list is easier to keep true than two whose boundary has to be re-decided on every edit.",
   "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]
+      "type": "string",
+      "const": "0.2",
+      "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 a QUOTED STRING, spelled exactly as the policy block's version is (\"0.1\"), because the two blocks live in one file and are read by one person: two version styles in one document is a detail an author has to remember rather than one they can see, and a block that says `version: 1` beside a block that says `version: \"0.1\"` invites the reader to conclude the values block is four revisions ahead. The quotes are load-bearing. A dotted identifier written bare is a FLOAT to YAML, so `version: 0.2` parses as the number 0.2, which loses the distinction between \"0.20\" and \"0.2\" and is refused by this schema; the loader refuses it by name, with the quoting as the fix. (APRV-336 replaced the integer 1 of the first revision; a block still carrying it is refused by the values loader alone and never by the policy loader.)",
+      "examples": ["0.2"]
     },
     "love": {
       "$ref": "#/$defs/valueList",
@@ -26,14 +26,10 @@
       "$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": {
+    "communication": {
       "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.",
+      "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. (Named `responds` in the first revision; renamed by APRV-336, which also freed the word from the `approval feedback` verb it collided with.)",
       "examples": [
         "Usually within the hour on the phone; a bare 'ok' means yes and is not curtness."
       ]

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

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