approval-md 0.2.0 → 0.3.0

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.

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,6 +118,31 @@
               "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"
+                  ]
+                }
+              },
+              "examples": [
+                { "telegram": "12345678" },
+                {
+                  "telegram": "hmac-sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
+                }
+              ]
             }
           }
         }
@@ -328,7 +368,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 +388,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 +400,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"],
+      "description": "SPEC.md §10.3 (amended, APRV-324): 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. `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"]
+    },
     "classPattern": {
       "type": "string",
       "pattern": "^(?:[a-z0-9][a-z0-9_-]*|\\*)(?:\\.(?:[a-z0-9][a-z0-9_-]*|\\*))*$",
@@ -496,6 +542,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" }