rogerwilco 0.2.0__tar.gz

rogerwilco-0.2.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: rogerwilco
+Version: 0.2.0
+Summary: Program-run checks around an AI agent's irreversible actions: typed handoff lines, a readback the sender checks, and a done report checked against the plan.
+Author-email: Adam Field <adam@crox.io>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://rogerwilco.crox.io
+Project-URL: Documentation, https://rogerwilco.crox.io/quickstart
+Project-URL: Research, https://rogerwilco.crox.io/research
+Project-URL: Source, https://github.com/afieldofdreams/rogerwilco
+Keywords: ai-agents,agents,llm,handoff,readback,guardrails,multi-agent,mcp,payments,protocol
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: rogerwilco/LICENSE
+License-File: rogerwilco/NOTICE
+Dynamic: license-file
+
+# rogerwilco
+
+One-line, typed, closed-vocabulary messages for handing work between AI agents, with a readback the sender can verify.
+
+```
+RW1 HO research-01 from=research to=writer item=gh:crox/site#42 ask=DRAFT due=20261002 pri=2 // hero copy, 120 words
+RW1 RB writer-01 re=research-01 from=writer to=research item=gh:crox/site#42 ask=DRAFT due=20261002 h=f209197fa615
+RW1 DN writer-03 re=research-01 from=writer to=research item=gh:crox/site#42 out=OK art=sha256:9f3e1c // v1, 118 words
+```
+
+Agents hand work to each other in prose today. Prose hides state, can't be validated, and gets misread silently. Most of the cost is fixed by discipline (facts once, files by reference, deltas only, closed options for the human), which the skill states in English first; the syntax exists so that code can check the discipline is being kept. rogerwilco puts the facts in slots, keeps reasoning in a bounded tail, and makes the receiver read the handoff back before it owns the work. The sender checks the readback in code across five tiers: receipt, integrity, echo, comprehension, where the receiver derives the acceptance criteria from the brief and the sender compares them with the ones it kept to itself, and execution, where before an irreversible act the receiver reads back the values it will act with and, afterwards, reports the values the tool executed. ATC phraseology for the envelope, teach-back for the instruction.
+
+The name is the radio call. *Roger*: received. *Wilco*: understood, and will comply. Those are two different claims, and the protocol makes the receiver prove both before the sender lets go of the work: the receipt tier is roger, the comprehension tier is wilco. A handoff whose readback passes is said to be wilco.
+
+It is content, not transport. It rides inside an MCP tool result, an A2A message part, a chat turn, a queue message or a log line. The receiving agent needs nothing installed: a 400-token legend in its prompt is enough to read and reply.
+
+## Install and integrate
+
+```
+pip install rogerwilco
+```
+
+Python 3.10+, standard library only. Three checks go around anything an agent does that cannot be undone:
+
+```python
+import rogerwilco as rw
+
+problems, notes = rw.check_ho(ho, record, "pay")                    # 1. the job's line against the approved record, before sending
+problems, notes = rw.check_rb_full(ho, statement, "pay")            # 2. the tool's statement of what it will do, before it acts
+problems, notes = rw.check_dn(ho, dn, "pay", rb_line=statement)     # 3. what it did, against the plan, afterwards
+```
+
+Empty `problems` means go; anything else means stop. The integration guide, with a runnable two-phase payment tool and a
+brief to hand your coding agent, is at **https://rogerwilco.crox.io/quickstart**. For a model doing the integration:
+https://rogerwilco.crox.io/llms-full.txt. The evidence, seven pre-registered studies: https://rogerwilco.crox.io/research.
+
+## Use it with Claude
+
+This repo is an [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview). Install it and Claude will use rogerwilco whenever it delegates to a subagent or receives a line that starts with `RW1`.
+
+- **Claude Code**: copy the `rogerwilco/` folder into `.claude/skills/` in your project (or `~/.claude/skills/` for all projects).
+- **Claude.ai and the Claude apps**: zip the `rogerwilco/` folder and upload it under Settings, Capabilities, Skills.
+- **Any other agent**: put the output of `python3 scripts/rogerwilco.py legend` in its system prompt.
+
+## What's in the folder
+
+| Path | What |
+|---|---|
+| `SKILL.md` | The instructions Claude follows. Short by design. |
+| `references/SPEC.md` | The protocol, version RW1 v0.1: grammar, eight message types, slots, codes, five rules, the five-tier readback, the checks before and after an irreversible act, JSON form, profiles. |
+| `scripts/rogerwilco.py` | Reference codec, standard library only: validate, encode, JSON twin, `make-rb`, `check-rb`, `check-ho`, `check-dn`, digest, legend, lint. |
+| `profiles/core.json` | The core vocabulary. |
+| `profiles/pform.json` | An example domain profile (a knowledge-graph workflow). Copy it to make your own. `pay.json` (accounts payable, with execution slots) and `clin.json` (clinical assertions) are the profiles the studies used. |
+| `tests/conformance.jsonl` | 80 codec cases (parse, readback, presend, done, digest) plus 6 agent-behaviour cases. |
+| `tests/test_conformance.py` | Runner. An implementation is conformant when it passes. |
+
+## The eight types
+
+`HO` handoff · `RB` readback · `AQ` ask · `AN` answer · `ST` status · `DN` done · `UN` unable · `FL` fail
+
+## The five rules
+
+1. No handover without readback.
+2. Never guess: unknown code, reply `UN why=UNK`.
+3. Every reply carries `re=`.
+4. Facts in slots, reasoning in the tail.
+5. The line and its JSON form are the same message.
+
+## Why these choices
+
+They come from a 240-message study of five wire formats and from reading real agent logs (September 2026). Keyed form beat positional because a small model miscounted positional columns in one run of two. Three-letter codes beat glyphs because glyph savings were tokenizer-dependent and the legend cost 1.7x more. Readback exists because every error observed was a misread of a neighbouring field, which an echo catches at the boundary. The execution level and the done check exist because the execution readback study found faults in the sender's draft and in the tool, and none in the receiver's reading on current models. The tail is bounded because real agent logs were 50% process narration and 26% narrated field changes. Details in `references/SPEC.md` section 10.
+
+## Conformance
+
+```
+python3 tests/test_conformance.py
+python3 tests/test_conformance.py --agent replies.jsonl   # score an agent's replies to the five agent cases
+```
+
+## Status
+
+v0.1, draft. The core vocabulary is small on purpose; extend it through a profile, not by editing the core. Issues and profiles welcome.
+
+Apache License 2.0, copyright Croxio Ltd; see LICENSE and NOTICE. Built by Adam Field. Lineage: M-Form (medical-record compression, 2025) to P-Form (knowledge-graph handoffs, April 2026) to rogerwilco (September 2026).

rogerwilco-0.2.0/README.md

@@ -0,0 +1,58 @@
+# rogerwilco
+
+Roger: received. Wilco: understood, and will comply.
+
+One-line, typed, closed-vocabulary messages for handing work between AI agents, with a readback the sender verifies in code before it lets go of the work.
+
+```
+RW1 HO research-01 from=research to=writer item=gh:crox/site#42 ask=DRAFT due=20261002 pri=2 // hero copy, 120 words
+RW1 RB writer-01 re=research-01 from=writer to=research item=gh:crox/site#42 ask=DRAFT due=20261002 h=f209197fa615
+RW1 DN writer-03 re=research-01 from=writer to=research item=gh:crox/site#42 out=OK art=sha256:9f3e1c // v1, 118 words
+```
+
+Agents hand work to each other in prose today. Prose hides state, cannot be validated, and gets misread silently. rogerwilco puts the facts in slots, keeps reasoning in a bounded tail or an artifact, and makes the receiver read the handoff back before it owns it. The readback is checked in five tiers: receipt and integrity (roger), echo, comprehension and execution (wilco); before an irreversible act the handover is checked against the record, and after it the done report is checked against the plan. It is content, not transport: it rides inside an MCP tool result, an A2A part, a chat turn, a queue message or a log line.
+
+## Install
+
+```
+pip install rogerwilco          # the codec and the `rogerwilco` command; standard library only
+```
+
+Until the package is on PyPI: `pip install git+https://github.com/afieldofdreams/rogerwilco`. The site at [rogerwilco.crox.io](https://rogerwilco.crox.io) has a two-minute start.
+
+## Three things in this repo
+
+| Folder | What | Start here |
+|---|---|---|
+| [`rogerwilco/`](rogerwilco/) | The protocol as a Claude Agent Skill: `SKILL.md`, the spec, the reference codec (standard library only), profiles, conformance tests. Copy the folder into `.claude/skills/` or upload it as a skill. | [`rogerwilco/README.md`](rogerwilco/README.md) |
+| [`app/`](app/) | The hosted checks: REST endpoints, a remote MCP server (validate, gate, check_rb, make_rb, check_ho, check_dn, legend, to_json), the site and the docs. Runs at [rogerwilco.crox.io](https://rogerwilco.crox.io). Add the MCP server by URL to any agent that has no shell. | [`app/README.md`](app/README.md) |
+| [`research/`](research/) | The evidence: a five-format wire study, a readback pilot with planted faults, a multi-agent month-end close with human-in-the-loop escalation (28 runs), a clinical translation study (144 translations against 422 gold assertions), a readback and set-back study (114 trials) and a pre-registered execution readback study (2,762 trials). Corpora, harnesses, raw logs and results pages. | [`research/README.md`](research/README.md) |
+
+## Quick start
+
+```
+# validate a line
+python3 rogerwilco/scripts/rogerwilco.py validate "RW1 HO a-1 from=a to=b item=x:1 ask=DRAFT"
+
+# sender side: check a readback across the five tiers
+python3 rogerwilco/scripts/rogerwilco.py check-rb "<HO line>" "<RB line>" --profile pay
+
+# before an irreversible act, the handover against the record; after it, the done report against the plan
+python3 rogerwilco/scripts/rogerwilco.py check-ho "<HO line>" '{"amt": "5400.00", "acct": "40-12-88/61102938"}' --profile pay
+python3 rogerwilco/scripts/rogerwilco.py check-dn "<HO line>" "<DN line>" --profile pay
+
+# legend for another agent's system prompt (about 400 tokens for core, more with a profile)
+python3 rogerwilco/scripts/rogerwilco.py legend --profile pay
+
+# conformance
+python3 rogerwilco/tests/test_conformance.py
+
+# the hosted app, locally
+pip install -r app/requirements.txt && uvicorn app.main:app --reload
+```
+
+## Status
+
+v0.1, draft. The core vocabulary is small on purpose; extend it through a profile, not by editing the core. Issues and profiles welcome.
+
+Apache License 2.0, copyright Croxio Ltd; see LICENSE and NOTICE. Built by Adam Field. Lineage: M-Form (medical-record compression, 2025) to P-Form (knowledge-graph handoffs, April 2026) to rogerwilco (September 2026).

rogerwilco-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rogerwilco"
+version = "0.2.0"
+description = "Program-run checks around an AI agent's irreversible actions: typed handoff lines, a readback the sender checks, and a done report checked against the plan."
+readme = "rogerwilco/README.md"
+license = "Apache-2.0"
+license-files = ["rogerwilco/LICENSE", "rogerwilco/NOTICE"]
+requires-python = ">=3.10"
+authors = [{name = "Adam Field", email = "adam@crox.io"}]
+keywords = ["ai-agents", "agents", "llm", "handoff", "readback", "guardrails", "multi-agent", "mcp", "payments", "protocol"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://rogerwilco.crox.io"
+Documentation = "https://rogerwilco.crox.io/quickstart"
+Research = "https://rogerwilco.crox.io/research"
+Source = "https://github.com/afieldofdreams/rogerwilco"
+
+[project.scripts]
+rogerwilco = "rogerwilco.scripts.rogerwilco:main"
+
+[tool.setuptools]
+packages = ["rogerwilco", "rogerwilco.scripts"]
+
+[tool.setuptools.package-data]
+rogerwilco = ["profiles/*.json", "SKILL.md", "references/*.md", "tests/*", "NOTICE"]

rogerwilco-0.2.0/rogerwilco/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

rogerwilco-0.2.0/rogerwilco/NOTICE

@@ -0,0 +1,8 @@
+rogerwilco
+Copyright 2026 Croxio Ltd
+
+This product includes software developed by Croxio Ltd (https://crox.io).
+
+Licensed under the Apache License, Version 2.0 (see LICENSE). As section 6 of the licence says, it does not grant
+permission to use the names "rogerwilco" or "RW1", or Croxio Ltd's trade names or marks, except to describe the
+origin of the work.

rogerwilco-0.2.0/rogerwilco/README.md

@@ -0,0 +1,84 @@
+# rogerwilco
+
+One-line, typed, closed-vocabulary messages for handing work between AI agents, with a readback the sender can verify.
+
+```
+RW1 HO research-01 from=research to=writer item=gh:crox/site#42 ask=DRAFT due=20261002 pri=2 // hero copy, 120 words
+RW1 RB writer-01 re=research-01 from=writer to=research item=gh:crox/site#42 ask=DRAFT due=20261002 h=f209197fa615
+RW1 DN writer-03 re=research-01 from=writer to=research item=gh:crox/site#42 out=OK art=sha256:9f3e1c // v1, 118 words
+```
+
+Agents hand work to each other in prose today. Prose hides state, can't be validated, and gets misread silently. Most of the cost is fixed by discipline (facts once, files by reference, deltas only, closed options for the human), which the skill states in English first; the syntax exists so that code can check the discipline is being kept. rogerwilco puts the facts in slots, keeps reasoning in a bounded tail, and makes the receiver read the handoff back before it owns the work. The sender checks the readback in code across five tiers: receipt, integrity, echo, comprehension, where the receiver derives the acceptance criteria from the brief and the sender compares them with the ones it kept to itself, and execution, where before an irreversible act the receiver reads back the values it will act with and, afterwards, reports the values the tool executed. ATC phraseology for the envelope, teach-back for the instruction.
+
+The name is the radio call. *Roger*: received. *Wilco*: understood, and will comply. Those are two different claims, and the protocol makes the receiver prove both before the sender lets go of the work: the receipt tier is roger, the comprehension tier is wilco. A handoff whose readback passes is said to be wilco.
+
+It is content, not transport. It rides inside an MCP tool result, an A2A message part, a chat turn, a queue message or a log line. The receiving agent needs nothing installed: a 400-token legend in its prompt is enough to read and reply.
+
+## Install and integrate
+
+```
+pip install rogerwilco
+```
+
+Python 3.10+, standard library only. Three checks go around anything an agent does that cannot be undone:
+
+```python
+import rogerwilco as rw
+
+problems, notes = rw.check_ho(ho, record, "pay")                    # 1. the job's line against the approved record, before sending
+problems, notes = rw.check_rb_full(ho, statement, "pay")            # 2. the tool's statement of what it will do, before it acts
+problems, notes = rw.check_dn(ho, dn, "pay", rb_line=statement)     # 3. what it did, against the plan, afterwards
+```
+
+Empty `problems` means go; anything else means stop. The integration guide, with a runnable two-phase payment tool and a
+brief to hand your coding agent, is at **https://rogerwilco.crox.io/quickstart**. For a model doing the integration:
+https://rogerwilco.crox.io/llms-full.txt. The evidence, seven pre-registered studies: https://rogerwilco.crox.io/research.
+
+## Use it with Claude
+
+This repo is an [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview). Install it and Claude will use rogerwilco whenever it delegates to a subagent or receives a line that starts with `RW1`.
+
+- **Claude Code**: copy the `rogerwilco/` folder into `.claude/skills/` in your project (or `~/.claude/skills/` for all projects).
+- **Claude.ai and the Claude apps**: zip the `rogerwilco/` folder and upload it under Settings, Capabilities, Skills.
+- **Any other agent**: put the output of `python3 scripts/rogerwilco.py legend` in its system prompt.
+
+## What's in the folder
+
+| Path | What |
+|---|---|
+| `SKILL.md` | The instructions Claude follows. Short by design. |
+| `references/SPEC.md` | The protocol, version RW1 v0.1: grammar, eight message types, slots, codes, five rules, the five-tier readback, the checks before and after an irreversible act, JSON form, profiles. |
+| `scripts/rogerwilco.py` | Reference codec, standard library only: validate, encode, JSON twin, `make-rb`, `check-rb`, `check-ho`, `check-dn`, digest, legend, lint. |
+| `profiles/core.json` | The core vocabulary. |
+| `profiles/pform.json` | An example domain profile (a knowledge-graph workflow). Copy it to make your own. `pay.json` (accounts payable, with execution slots) and `clin.json` (clinical assertions) are the profiles the studies used. |
+| `tests/conformance.jsonl` | 80 codec cases (parse, readback, presend, done, digest) plus 6 agent-behaviour cases. |
+| `tests/test_conformance.py` | Runner. An implementation is conformant when it passes. |
+
+## The eight types
+
+`HO` handoff · `RB` readback · `AQ` ask · `AN` answer · `ST` status · `DN` done · `UN` unable · `FL` fail
+
+## The five rules
+
+1. No handover without readback.
+2. Never guess: unknown code, reply `UN why=UNK`.
+3. Every reply carries `re=`.
+4. Facts in slots, reasoning in the tail.
+5. The line and its JSON form are the same message.
+
+## Why these choices
+
+They come from a 240-message study of five wire formats and from reading real agent logs (September 2026). Keyed form beat positional because a small model miscounted positional columns in one run of two. Three-letter codes beat glyphs because glyph savings were tokenizer-dependent and the legend cost 1.7x more. Readback exists because every error observed was a misread of a neighbouring field, which an echo catches at the boundary. The execution level and the done check exist because the execution readback study found faults in the sender's draft and in the tool, and none in the receiver's reading on current models. The tail is bounded because real agent logs were 50% process narration and 26% narrated field changes. Details in `references/SPEC.md` section 10.
+
+## Conformance
+
+```
+python3 tests/test_conformance.py
+python3 tests/test_conformance.py --agent replies.jsonl   # score an agent's replies to the five agent cases
+```
+
+## Status
+
+v0.1, draft. The core vocabulary is small on purpose; extend it through a profile, not by editing the core. Issues and profiles welcome.
+
+Apache License 2.0, copyright Croxio Ltd; see LICENSE and NOTICE. Built by Adam Field. Lineage: M-Form (medical-record compression, 2025) to P-Form (knowledge-graph handoffs, April 2026) to rogerwilco (September 2026).

rogerwilco-0.2.0/rogerwilco/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: rogerwilco
+description: Typed one-line messages for handing work between agents, reading a handoff back, asking bounded questions, and reporting done, unable or failed. Use whenever you hand work to another agent or subagent, receive a message starting with RW1, or need a receipt for what was agreed between agents.
+---
+
+# rogerwilco
+
+Roger: received. Wilco: understood and will comply. Agents hand work to each other in one typed line instead of a paragraph, and the receiver proves both before it owns the work. Facts go in slots, reasoning goes in the tail, and the receiver reads the line back before it owns the work. Full spec: `references/SPEC.md`.
+
+## The discipline comes first
+
+Seven rules carry most of the value, and a team can adopt them in plain English before it adopts the syntax. In a 28-run study, prose written under these rules cut inter-agent traffic to a third of free prose and the principal's reading to 40%; the line syntax matched that and added verification, and when the lines replaced the working files it cut the files the agents pass around from 22k tokens a run to under 2k.
+
+1. **Facts once, in a fixed shape.** Each item on its own line with its identifiers, amounts and your decision.
+2. **Reasoning by reference, facts by translation.** Anything longer than a short paragraph goes in a file; the message carries the path, not a paraphrase. A source document (an email, an invoice, a ticket) is translated once, at the edge, into one line that carries every fact in a slot and points back at the source (`src=email:7`); when the lines carry the facts, nobody writes a working file to restate them.
+3. **State by delta.** Once an item has been reported, mention it again only when something about it changed.
+4. **Acknowledge a handoff before you start.** Say what you received and the deadline.
+5. **Escalate as a question with a closed list of options.** The item, the amounts, the decision needed, and the answers the human may give. Do not escalate what the policy leaves to you.
+6. **Ask, answer, finish.** Bounded questions, direct answers, an explicit done.
+7. **No preamble, no recap.**
+
+The lines below are those rules made checkable by code: a validator refuses a malformed message, a closed vocabulary refuses an invented option, a digest proves a handoff arrived intact. Use them wherever a smaller or mixed set of models is doing the work, before an irreversible step, wherever the log will be read by someone who has to trust it, and at the edge where source documents enter the system.
+
+## When to use
+
+- You are delegating work to another agent, subagent or role.
+- You receive a line that starts with `RW1`.
+- You need to ask another agent a question with a bounded answer.
+- You are reporting that delegated work is done, that you cannot take it, or that it failed.
+- You are escalating a decision to a human with a fixed set of options.
+
+Do not use it for the work itself. Drafts, specs and analysis stay as normal content; the line points at them.
+
+## The line
+
+```
+RW1 <TYPE> <id> [re=<id>] from=<agent> to=<agent> [item=<ref>] [key=value ...] [// tail]
+```
+
+- First three tokens are positional: version `RW1`, the type, your message id: `<yourname>-<n>`, unique in the conversation (`from=writer` sends `writer-1`, `writer-2`, ...; the validator refuses any other shape).
+- Everything else is `key=value`, any order. No spaces inside values. Lists join with `+`. Dates are `YYYYMMDD`.
+- ` // ` starts the tail: free text, 300 characters max. Longer content becomes an artifact you reference with `art=`.
+- `item` is a reference to the thing under discussion: `gh:owner/repo#42`, `pensive:4102`, `url:...`, `file:...`, `sha256:...`.
+- `to=human` escalates to the human principal.
+
+## Eight types
+
+| Type | Use | Required |
+|---|---|---|
+| `HO` | hand work over | `from to item ask` |
+| `RB` | read a handoff back: what you received and what you understood | `re from to item ask`, `due` if the HO had one, every slot the HO names in `rb=`, `acc` when the HO says `rb=acc` or `rb=plan` (`do` too for `plan`), and the profile's execution slots for the ask when it says `rb=exec` |
+| `AQ` | ask a bounded question | `from to need` and `opts` when `need=ENUM` |
+| `AN` | answer | `re from to val` |
+| `ST` | report a state change, no handover | `from to item` |
+| `DN` | done | `re from to item out`, and after an act asked with `rb=exec` the execution slots with the values as executed |
+| `UN` | unable, will not take it | `re from to why` |
+| `FL` | took it and it failed | `re from to item why` |
+
+Optional slots: `rb` readback level on an HO: `echo` (default), `all`, `acc`, `plan`, `exec`, plus slot names to echo (`rb=acc+pri`) · `keys` on an HO: the constraint keys the sender will check (`keys=len+lang+must+no`), so the receiver reports those dimensions · `acc` acceptance criteria as `key:value` tokens (`len:120w+lang:uk+must:monday-problem+no:em-dash`) · `do` what you will produce · `not` what you exclude · `asm` assumptions you are making · `h` digest of the HO, code-side receivers only · `due` `by` (dates) · `pri` 1–5, 1 highest · `conf` L/M/H · `keep` agents staying involved · `art` artifact refs · `ctx` earlier message ids · `eta` · `pct` 0–100 · `blk` blockers · `alt` alternative agent · `next` suggested next ask · `retry` Y/N.
+
+## Codes
+
+- `ask`: `REVIEW` `DRAFT` `DECIDE` `RESEARCH` `BUILD` `FIX` `SUMM` `PLAN` `TEST` `EXTRACT`
+- `why`: `NOCAP` no capability · `NOCTX` missing context · `PERM` not permitted · `BUSY` · `CONFLICT` owned elsewhere · `DUP` · `VER` bad version · `UNK` unknown code · `SCOPE` · `ERR` · `TIMEOUT`
+- `out`: `OK` `PARTIAL` `NOOP`
+- `need`: `ENUM` `TEXT` `NUM` `DATE` `YESNO`. For `TEXT`, reply `val=tail` and put the answer in the tail.
+
+- `acc` keys, a closed set: `len` (unit suffix: `120w` words, `800c` chars, `2p` pages, `10s` slides) · `fmt` (`md` `docx` `json` `csv` `html`) · `lang` (`uk` `us` `fr`) · `tone` (`plain` `formal` `casual` `technical`) · `voice` (`we` `i` `you` `third`) · `aud` · `out` (`copy` `spec` `dataset` `pr` `report`) · `by` (date) · `src` · `scope` · `must` · `no`. `must`, `no`, `scope` and `src` may repeat. For `must` and `no` values, use the brief's own words, hyphenated, no spaces (`must:monday-problem`, `no:em-dash`). Do not invent keys; a key outside the set is not compared.
+
+A profile adds domain codes and slots; a message using one carries `p=<profile>`. Profiles live in `profiles/`. Without `p=`, only the codes above are valid. A profile may name execution slots for an ask (the pay profile: `sup amt cur kind acct paid ref apref` for `PAY`, `sup acct eff apref prev` for `CHGBANK`, `sup addr amt cur paid ref` for `SEND`); those are what `rb=exec` reads back and what the DN reports. A profile may close the answer vocabulary with an `ans` enum (the pay profile has `APPROVE DECLINE HOLD REJECT CALLBACK`): then every `AQ need=ENUM` takes its `opts` from it and every `AN val` is one of them, so a human or a policy engine can answer without decoding invented words.
+
+## Five rules
+
+1. **No handover without readback.** Set the level per handoff, not per team: `rb=exec` before an irreversible act such as releasing a payment, changing a payee or sending anything external, where the profile names execution slots for the ask, and `rb=all` (every slot echoed) where it does not; the default envelope echo (`item`, `ask`, `due`) for everything else; `rb=acc` when the instruction lives in a brief. After you send an HO, you still own the item until the receiver's RB passes your check: it echoes `item`, `ask`, `due` and anything you named in `rb=`, with the same decoded values, and if you asked `rb=acc` its `acc=` matches the criteria you wrote down before sending. If it does not pass, re-send the HO with `re=` pointing at the bad RB. No RB by your deadline: re-send with `re=` pointing at the original; a receiver that already read it back replies `UN why=DUP`. When you receive an HO, send the RB before doing anything else, echoing the values exactly as you read them; if you have code, add `h=` from `make-rb`.
+   **Before an irreversible act, three checks.** Build the HO from the record by code, or check it against the record before you send it (`check-ho`): a value that differs from the record, a value the record holds that the line omits, or a missing `rb=exec` stops the line going out. When you receive an HO with `rb=exec`, read back the execution slots with the values you will actually use, resolved from your own records where the HO does not give them (the account on file; for a bank change, the account you are replacing in `prev=`); if a value you resolved contradicts the HO, ask instead of acting. As the sender, check a resolved value against your record, and clear the act with `AN val=Y` only when the readback passes. After the act, report what the tool did, not what you meant: the DN carries the same slots with the values from the tool's result, and the sender checks it against the plan (`check-dn`). That done check is the only loop that catches a tool doing something other than what it was told. Where the act tool can prepare before it commits, the readback is the tool's prepared statement, not your own values: relay the line the tool printed unchanged, compare it first with the call you made and abandon and ask if they differ, and commit only the token the sender confirmed.
+   **Readback is comprehension, not recall.** Echoing slots proves you saw them. When the HO says `rb=acc` or `rb=plan`, read the brief and any `art=` it points at, derive the acceptance criteria yourself, and send them as `acc=` (`len:120w+tone:plain+no:em-dash+must:monday-problem`); add `do=` for `plan`; put anything you are excluding in `not=` and anything the brief left open in `asm=`; paraphrase the task in the tail. The sender compares your `acc=` by key with criteria it kept to itself: a different value is a contradiction and a missing key is a gap, both fail the readback; an extra key is an assumption the sender will confirm. When you send an HO whose instruction lives in the tail or an artifact, ask for `rb=acc`, name the keys you will check with `keys=` (dimensions only, never the values), and write your criteria down first using the closed key set.
+2. **Never guess.** Unknown version, type or code: reply `UN why=UNK` (or `why=VER`) and name the code in the tail. `UNK` describes the message; do not substitute `NOCAP` or `SCOPE`, which describe you. An AQ always gets an AN (or a UN); never leave a question unanswered because you are busy.
+3. **Every reply carries `re=`.** RB, AN, DN, UN, FL always. Reconstruct threads from ids, not from position.
+4. **Facts in slots, reasoning in the tail.** If a fact has a slot, it goes in the slot. Tail is 300 characters max.
+5. **One message, two forms.** The line and its JSON twin are equivalent (see SPEC §6). Use whichever your side handles better; the codec maps between them.
+
+## Worked exchange
+
+```
+RW1 HO research-01 from=research to=writer item=gh:crox/site#42 ask=DRAFT due=20261002 pri=2 conf=M keep=research // hero copy, 120 words, no em dashes
+RW1 RB writer-01 re=research-01 from=writer to=research item=gh:crox/site#42 ask=DRAFT due=20261002 h=c40bba4360dc
+RW1 AQ writer-02 re=research-01 from=writer to=research item=gh:crox/site#42 need=ENUM opts=formal+plain+punchy // tone?
+RW1 AN research-02 re=writer-02 from=research to=writer val=plain
+RW1 DN writer-03 re=research-01 from=writer to=research item=gh:crox/site#42 out=OK art=sha256:9f3e1c // v1, 118 words
+```
+
+Comprehension readback (sender asked `rb=acc` and kept `len:120w+tone:plain+no:em-dash+must:monday-problem`):
+
+```
+RW1 HO research-03 from=research to=writer item=gh:crox/site#42 ask=DRAFT due=20261002 rb=acc keys=len+tone+must+no art=url:https://example.com/brief // hero copy, 120 words, plain tone, no em dashes, must name the reader's Monday problem
+RW1 RB writer-05 re=research-03 from=writer to=research item=gh:crox/site#42 ask=DRAFT due=20261002 acc=len:120w+tone:plain+must:monday-problem+no:em-dash do=copy // landing hero, 120 words, plain, lead with the Monday problem
+```
+
+Before an irreversible act (pay profile; the HO was checked against the approval record before it went, the RB carries the execution slots, the DN carries the values the payment tool returned):
+
+```
+RW1 HO scheduler-1 p=pay from=scheduler to=payer item=inv:MD-2026-057 ask=PAY rb=exec sup=marlow amt=5400.00 cur=GBP kind=GROSS acct=40-12-88/61102938 paid=20261002 ref=MD-2026-057 apref=FD-0929
+RW1 RB payer-1 re=scheduler-1 from=payer to=scheduler item=inv:MD-2026-057 ask=PAY p=pay h=a7a82de76607 sup=marlow amt=5400.00 cur=GBP kind=GROSS acct=40-12-88/61102938 paid=20261002 ref=MD-2026-057 apref=FD-0929
+RW1 AN scheduler-2 re=payer-1 p=pay from=scheduler to=payer val=Y // readback matches the approved run; proceed
+RW1 DN payer-2 re=scheduler-1 p=pay from=payer to=scheduler item=inv:MD-2026-057 out=OK sup=marlow amt=5400.00 cur=GBP kind=GROSS acct=40-12-88/61102938 paid=20261002 ref=MD-2026-057 apref=FD-0929 // as executed, from the payment tool
+```
+
+Refusing: `RW1 UN writer-04 re=research-01 from=writer to=research item=gh:crox/site#42 why=NOCTX alt=copywriter // no style guide on file`
+
+Escalating: `RW1 AQ triage-09 from=triage to=human item=pensive:4664 need=ENUM opts=RETIRE+ACTIVATE+PARK by=20261005 // stale 15d; default PARK`
+
+## Validate when you can
+
+If you have a shell, check every line you send or receive:
+
+```
+python3 scripts/rogerwilco.py validate "RW1 HO a-1 from=a to=b item=x:1 ask=DRAFT"
+python3 scripts/rogerwilco.py make-rb "<HO line>" <your-id> [--acc "k:v+k:v" --do copy]   # readback with h= digest
+python3 scripts/rogerwilco.py check-rb "<HO line>" "<RB line>" [--profile pay] [--expect-acc "k:v+k:v"]   # sender side: receipt, integrity, echo, comprehension, execution
+python3 scripts/rogerwilco.py check-ho "<HO line>" '{"amt": "5400.00", ...}' --profile pay   # before an irreversible act: the HO against the record
+python3 scripts/rogerwilco.py check-dn "<HO line>" "<DN line>" --profile pay [--rb "<RB line>"]   # after it: the done report against the plan
+python3 scripts/rogerwilco.py to-json "<line>"  |  from-json '<json>'
+python3 scripts/rogerwilco.py legend [--profile pay] [--lean]      # legend for another agent's prompt; --lean drops the comprehension-readback keys (about 1,200 tokens with the pay profile)
+```
+
+If you have no shell, read the line against the table above and apply rule 2.
+
+## Giving it to another agent
+
+Put the output of `legend` (or this file) in the other agent's system prompt. That is all the other side needs; it does not have to install anything.