@memnexus-ai/mx-agent-cli 0.1.294-next.0 → 0.1.294

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. package/dist/__tests__/config-sync.test.js +1 -54
  2. package/dist/__tests__/config-sync.test.js.map +1 -1
  3. package/dist/agent-config/hooks/auto-capture-precompact.sh +256 -74
  4. package/dist/agent-config/hooks/auto-capture-session-end.sh +254 -106
  5. package/dist/agent-config/hooks/auto-checkpoint.sh +5 -75
  6. package/dist/agent-config/hooks/observability-sync.sh +9 -46
  7. package/dist/commands/config-sync.d.ts +0 -37
  8. package/dist/commands/config-sync.d.ts.map +1 -1
  9. package/dist/commands/config-sync.js +18 -36
  10. package/dist/commands/config-sync.js.map +1 -1
  11. package/dist/commands/dashboard.d.ts.map +1 -1
  12. package/dist/commands/dashboard.js +2 -10
  13. package/dist/commands/dashboard.js.map +1 -1
  14. package/dist/commands/monitor.d.ts.map +1 -1
  15. package/dist/commands/monitor.js +2 -8
  16. package/dist/commands/monitor.js.map +1 -1
  17. package/dist/commands/start.d.ts +0 -4
  18. package/dist/commands/start.d.ts.map +1 -1
  19. package/dist/commands/start.js +0 -6
  20. package/dist/commands/start.js.map +1 -1
  21. package/dist/commands/update.d.ts +1 -13
  22. package/dist/commands/update.d.ts.map +1 -1
  23. package/dist/commands/update.js +1 -50
  24. package/dist/commands/update.js.map +1 -1
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js +3 -67
  27. package/dist/index.js.map +1 -1
  28. package/dist/lib/agent-session.d.ts +0 -12
  29. package/dist/lib/agent-session.d.ts.map +1 -1
  30. package/dist/lib/agent-session.js +41 -183
  31. package/dist/lib/agent-session.js.map +1 -1
  32. package/dist/lib/claude.d.ts +0 -12
  33. package/dist/lib/claude.d.ts.map +1 -1
  34. package/dist/lib/claude.js +2 -29
  35. package/dist/lib/claude.js.map +1 -1
  36. package/dist/lib/terminal-ui.d.ts.map +1 -1
  37. package/dist/lib/terminal-ui.js +1 -12
  38. package/dist/lib/terminal-ui.js.map +1 -1
  39. package/package.json +2 -3
  40. package/dist/__tests__/decision-check.test.d.ts +0 -2
  41. package/dist/__tests__/decision-check.test.d.ts.map +0 -1
  42. package/dist/__tests__/decision-check.test.js +0 -105
  43. package/dist/__tests__/decision-check.test.js.map +0 -1
  44. package/dist/__tests__/harness-extract.test.d.ts +0 -19
  45. package/dist/__tests__/harness-extract.test.d.ts.map +0 -1
  46. package/dist/__tests__/harness-extract.test.js +0 -566
  47. package/dist/__tests__/harness-extract.test.js.map +0 -1
  48. package/dist/__tests__/harness-wiring.test.d.ts +0 -16
  49. package/dist/__tests__/harness-wiring.test.d.ts.map +0 -1
  50. package/dist/__tests__/harness-wiring.test.js +0 -469
  51. package/dist/__tests__/harness-wiring.test.js.map +0 -1
  52. package/dist/__tests__/report-format.test.d.ts +0 -2
  53. package/dist/__tests__/report-format.test.d.ts.map +0 -1
  54. package/dist/__tests__/report-format.test.js +0 -219
  55. package/dist/__tests__/report-format.test.js.map +0 -1
  56. package/dist/__tests__/standards-injection.test.d.ts +0 -2
  57. package/dist/__tests__/standards-injection.test.d.ts.map +0 -1
  58. package/dist/__tests__/standards-injection.test.js +0 -157
  59. package/dist/__tests__/standards-injection.test.js.map +0 -1
  60. package/dist/commands/decision.d.ts +0 -20
  61. package/dist/commands/decision.d.ts.map +0 -1
  62. package/dist/commands/decision.js +0 -54
  63. package/dist/commands/decision.js.map +0 -1
  64. package/dist/commands/report.d.ts +0 -33
  65. package/dist/commands/report.d.ts.map +0 -1
  66. package/dist/commands/report.js +0 -73
  67. package/dist/commands/report.js.map +0 -1
  68. package/dist/lib/decision-check.d.ts +0 -48
  69. package/dist/lib/decision-check.d.ts.map +0 -1
  70. package/dist/lib/decision-check.js +0 -149
  71. package/dist/lib/decision-check.js.map +0 -1
  72. package/dist/lib/harness/console/announce.d.ts +0 -45
  73. package/dist/lib/harness/console/announce.d.ts.map +0 -1
  74. package/dist/lib/harness/console/announce.js +0 -48
  75. package/dist/lib/harness/console/announce.js.map +0 -1
  76. package/dist/lib/harness/console/announce.test.d.ts +0 -2
  77. package/dist/lib/harness/console/announce.test.d.ts.map +0 -1
  78. package/dist/lib/harness/console/announce.test.js +0 -104
  79. package/dist/lib/harness/console/announce.test.js.map +0 -1
  80. package/dist/lib/harness/console/by-session.d.ts +0 -50
  81. package/dist/lib/harness/console/by-session.d.ts.map +0 -1
  82. package/dist/lib/harness/console/by-session.js +0 -83
  83. package/dist/lib/harness/console/by-session.js.map +0 -1
  84. package/dist/lib/harness/console/by-session.test.d.ts +0 -2
  85. package/dist/lib/harness/console/by-session.test.d.ts.map +0 -1
  86. package/dist/lib/harness/console/by-session.test.js +0 -86
  87. package/dist/lib/harness/console/by-session.test.js.map +0 -1
  88. package/dist/lib/harness/console/console.d.ts +0 -67
  89. package/dist/lib/harness/console/console.d.ts.map +0 -1
  90. package/dist/lib/harness/console/console.js +0 -373
  91. package/dist/lib/harness/console/console.js.map +0 -1
  92. package/dist/lib/harness/console/console.test.d.ts +0 -2
  93. package/dist/lib/harness/console/console.test.d.ts.map +0 -1
  94. package/dist/lib/harness/console/console.test.js +0 -269
  95. package/dist/lib/harness/console/console.test.js.map +0 -1
  96. package/dist/lib/harness/console/decision-request.d.ts +0 -32
  97. package/dist/lib/harness/console/decision-request.d.ts.map +0 -1
  98. package/dist/lib/harness/console/decision-request.js +0 -112
  99. package/dist/lib/harness/console/decision-request.js.map +0 -1
  100. package/dist/lib/harness/console/decision-request.test.d.ts +0 -2
  101. package/dist/lib/harness/console/decision-request.test.d.ts.map +0 -1
  102. package/dist/lib/harness/console/decision-request.test.js +0 -75
  103. package/dist/lib/harness/console/decision-request.test.js.map +0 -1
  104. package/dist/lib/harness/console/fixtures.d.ts +0 -16
  105. package/dist/lib/harness/console/fixtures.d.ts.map +0 -1
  106. package/dist/lib/harness/console/fixtures.js +0 -49
  107. package/dist/lib/harness/console/fixtures.js.map +0 -1
  108. package/dist/lib/harness/console/index.d.ts +0 -15
  109. package/dist/lib/harness/console/index.d.ts.map +0 -1
  110. package/dist/lib/harness/console/index.js +0 -14
  111. package/dist/lib/harness/console/index.js.map +0 -1
  112. package/dist/lib/harness/console/rank.d.ts +0 -73
  113. package/dist/lib/harness/console/rank.d.ts.map +0 -1
  114. package/dist/lib/harness/console/rank.js +0 -113
  115. package/dist/lib/harness/console/rank.js.map +0 -1
  116. package/dist/lib/harness/console/rank.test.d.ts +0 -2
  117. package/dist/lib/harness/console/rank.test.d.ts.map +0 -1
  118. package/dist/lib/harness/console/rank.test.js +0 -124
  119. package/dist/lib/harness/console/rank.test.js.map +0 -1
  120. package/dist/lib/harness/console/render.d.ts +0 -22
  121. package/dist/lib/harness/console/render.d.ts.map +0 -1
  122. package/dist/lib/harness/console/render.js +0 -65
  123. package/dist/lib/harness/console/render.js.map +0 -1
  124. package/dist/lib/harness/console/render.test.d.ts +0 -2
  125. package/dist/lib/harness/console/render.test.d.ts.map +0 -1
  126. package/dist/lib/harness/console/render.test.js +0 -96
  127. package/dist/lib/harness/console/render.test.js.map +0 -1
  128. package/dist/lib/harness/console/replay-cli.test.d.ts +0 -2
  129. package/dist/lib/harness/console/replay-cli.test.d.ts.map +0 -1
  130. package/dist/lib/harness/console/replay-cli.test.js +0 -96
  131. package/dist/lib/harness/console/replay-cli.test.js.map +0 -1
  132. package/dist/lib/harness/console/replay.d.ts +0 -36
  133. package/dist/lib/harness/console/replay.d.ts.map +0 -1
  134. package/dist/lib/harness/console/replay.js +0 -59
  135. package/dist/lib/harness/console/replay.js.map +0 -1
  136. package/dist/lib/harness/console/replay.test.d.ts +0 -2
  137. package/dist/lib/harness/console/replay.test.d.ts.map +0 -1
  138. package/dist/lib/harness/console/replay.test.js +0 -81
  139. package/dist/lib/harness/console/replay.test.js.map +0 -1
  140. package/dist/lib/harness/console/turn-reader.d.ts +0 -50
  141. package/dist/lib/harness/console/turn-reader.d.ts.map +0 -1
  142. package/dist/lib/harness/console/turn-reader.js +0 -184
  143. package/dist/lib/harness/console/turn-reader.js.map +0 -1
  144. package/dist/lib/harness/console/turn-reader.test.d.ts +0 -2
  145. package/dist/lib/harness/console/turn-reader.test.d.ts.map +0 -1
  146. package/dist/lib/harness/console/turn-reader.test.js +0 -108
  147. package/dist/lib/harness/console/turn-reader.test.js.map +0 -1
  148. package/dist/lib/harness/console/types.d.ts +0 -109
  149. package/dist/lib/harness/console/types.d.ts.map +0 -1
  150. package/dist/lib/harness/console/types.js +0 -2
  151. package/dist/lib/harness/console/types.js.map +0 -1
  152. package/dist/lib/harness/contract.d.ts +0 -229
  153. package/dist/lib/harness/contract.d.ts.map +0 -1
  154. package/dist/lib/harness/contract.js +0 -22
  155. package/dist/lib/harness/contract.js.map +0 -1
  156. package/dist/lib/harness/credential.d.ts +0 -23
  157. package/dist/lib/harness/credential.d.ts.map +0 -1
  158. package/dist/lib/harness/credential.js +0 -81
  159. package/dist/lib/harness/credential.js.map +0 -1
  160. package/dist/lib/harness/credential.test.d.ts +0 -2
  161. package/dist/lib/harness/credential.test.d.ts.map +0 -1
  162. package/dist/lib/harness/credential.test.js +0 -74
  163. package/dist/lib/harness/credential.test.js.map +0 -1
  164. package/dist/lib/harness/evaluate.d.ts +0 -390
  165. package/dist/lib/harness/evaluate.d.ts.map +0 -1
  166. package/dist/lib/harness/evaluate.js +0 -988
  167. package/dist/lib/harness/evaluate.js.map +0 -1
  168. package/dist/lib/harness/evaluate.test.d.ts +0 -2
  169. package/dist/lib/harness/evaluate.test.d.ts.map +0 -1
  170. package/dist/lib/harness/evaluate.test.js +0 -621
  171. package/dist/lib/harness/evaluate.test.js.map +0 -1
  172. package/dist/lib/harness/extract.d.ts +0 -152
  173. package/dist/lib/harness/extract.d.ts.map +0 -1
  174. package/dist/lib/harness/extract.js +0 -1601
  175. package/dist/lib/harness/extract.js.map +0 -1
  176. package/dist/lib/harness/gate.d.ts +0 -48
  177. package/dist/lib/harness/gate.d.ts.map +0 -1
  178. package/dist/lib/harness/gate.js +0 -60
  179. package/dist/lib/harness/gate.js.map +0 -1
  180. package/dist/lib/harness/gate.test.d.ts +0 -2
  181. package/dist/lib/harness/gate.test.d.ts.map +0 -1
  182. package/dist/lib/harness/gate.test.js +0 -111
  183. package/dist/lib/harness/gate.test.js.map +0 -1
  184. package/dist/lib/harness/self-check.d.ts +0 -59
  185. package/dist/lib/harness/self-check.d.ts.map +0 -1
  186. package/dist/lib/harness/self-check.js +0 -56
  187. package/dist/lib/harness/self-check.js.map +0 -1
  188. package/dist/lib/harness/self-check.test.d.ts +0 -2
  189. package/dist/lib/harness/self-check.test.d.ts.map +0 -1
  190. package/dist/lib/harness/self-check.test.js +0 -43
  191. package/dist/lib/harness/self-check.test.js.map +0 -1
  192. package/dist/lib/harness/transcript.d.ts +0 -65
  193. package/dist/lib/harness/transcript.d.ts.map +0 -1
  194. package/dist/lib/harness/transcript.js +0 -144
  195. package/dist/lib/harness/transcript.js.map +0 -1
  196. package/dist/lib/harness/transcript.test.d.ts +0 -2
  197. package/dist/lib/harness/transcript.test.d.ts.map +0 -1
  198. package/dist/lib/harness/transcript.test.js +0 -118
  199. package/dist/lib/harness/transcript.test.js.map +0 -1
  200. package/dist/lib/harness-wiring.d.ts +0 -145
  201. package/dist/lib/harness-wiring.d.ts.map +0 -1
  202. package/dist/lib/harness-wiring.js +0 -280
  203. package/dist/lib/harness-wiring.js.map +0 -1
  204. package/dist/lib/report-format.d.ts +0 -132
  205. package/dist/lib/report-format.d.ts.map +0 -1
  206. package/dist/lib/report-format.js +0 -317
  207. package/dist/lib/report-format.js.map +0 -1
  208. package/dist/lib/standards.d.ts +0 -90
  209. package/dist/lib/standards.d.ts.map +0 -1
  210. package/dist/lib/standards.js +0 -194
  211. package/dist/lib/standards.js.map +0 -1
  212. package/dist/standards/decision-request.md +0 -90
  213. package/dist/standards/fail-loud-standard.md +0 -495
  214. package/dist/standards/report-format.md +0 -120
  215. package/dist/standards/writing-standard.md +0 -240
@@ -1,120 +0,0 @@
1
- # Report format
2
-
3
- **Status:** Active. Injected into every team's `CLAUDE.local.md` on every conversation turn.
4
- **Enforced by:** `mx-agent report check`, which refuses a report missing a section.
5
- **Skeleton:** `mx-agent report new`, which writes the seven headings for you.
6
-
7
- ## Why this file exists
8
-
9
- Across 12 real sessions and 190 moments where an agent needed the operator, 3 reached him.
10
- 25 of the 28 moments classed as an explicit question were agents writing that they needed a
11
- decision, in prose, into a channel nobody reads. The source is
12
- `docs/fleet-behavior-from-transcripts.md` finding 3c.
13
-
14
- The same repository gained roughly forty commits and nine documents in two days, and the
15
- person it was written for asked four times what the work was. Volume is not legibility. The
16
- defect is the format, so the format is the fix.
17
-
18
- Two sections do most of the work. Section 3 makes a finding challengeable, because it
19
- states the command a reader can re-run. Section 5 makes a wrong finding cheap to overturn,
20
- because it tells the reader where to poke first. This repository arrived at section 3 by
21
- accident, after publishing eight figures in one week that were correct against the wrong
22
- thing.
23
-
24
- ---
25
-
26
- ## The seven sections
27
-
28
- The block below is the text injected into every conversation turn.
29
-
30
- <!-- behavioral-start -->
31
-
32
- Every report answers these seven, in this order, with these headings. The framework refuses
33
- a report that omits one or leaves one empty.
34
-
35
- **1. What I was asked.** One sentence, plus the rung of the goal ladder it serves. Name
36
- Level 1, Level 2 or Level 3 from `.mx-agent/goals.md`. An agent that cannot name its rung
37
- has an assignment nobody can evaluate, and that is a reason to stop and ask.
38
-
39
- **2. What I did.** The actions, not the reasoning. What you ran, read, wrote and changed.
40
-
41
- **3. What I found.** Each claim states the command, the file and line, or the query that
42
- produced it. A claim with no source is an opinion and belongs in section 4. This is the
43
- section that makes a finding challengeable, and it is the one that catches your own errors
44
- before a reader does.
45
-
46
- **4. What I am not sure about.** State it rather than omitting it. Passed, failed and
47
- could-not-run are three outcomes, and anything you could not run belongs here by name.
48
-
49
- **5. What would change my mind.** The specific observation that would overturn each
50
- finding. Not "more data". Name the file, the run, or the number that would do it. A finding
51
- with nothing in this section is a finding nobody can cheaply check.
52
-
53
- **6. What I need from you.** A decision, or the word Nothing. Do not write a question into
54
- prose elsewhere and hope it is read. This section is the channel.
55
-
56
- **7. What I would do next.** What you would pick up, and why that and not something else.
57
-
58
- Write to `mx-agent-system/standards/writing-standard.md` while filling these in. Both are
59
- injected together and they apply to the same text.
60
-
61
- <!-- behavioral-end -->
62
-
63
- ---
64
-
65
- ## What the framework checks
66
-
67
- `mx-agent report check <file>` refuses when any of these hold. It mirrors the provisioning
68
- refusal for a roleguide with no behavioral block: the check runs at the moment a person is
69
- looking, and it refuses rather than warns.
70
-
71
- | Check | Refuses when |
72
- |---|---|
73
- | Section present | One of the seven headings is absent |
74
- | Section order | The headings appear out of order |
75
- | Section non-empty | A heading has no body under it |
76
- | Goal rung | Section 1 names no level from `.mx-agent/goals.md` |
77
- | Evidence | Section 3 states no command, path or `file:line` |
78
- | Duplicates | A heading appears more than once |
79
-
80
- The check reads headings tolerantly. Any heading level works, the leading number is
81
- optional, and matching ignores case and trailing punctuation. A report is refused for
82
- missing a section, never for formatting one.
83
-
84
- ### What it does not check
85
-
86
- It cannot tell whether a command in section 3 is the command that produced the number. That
87
- is the failure mode `.mx-agent/lessons.md` L2 records, and only re-running catches it.
88
-
89
- It cannot tell whether section 5 names a real disconfirming observation or a placeholder. A
90
- reader can, in one glance, which is the point of putting it in a fixed position.
91
-
92
- It does not read your prose for the writing standard. Nothing counts em dashes or banned
93
- verbs at check time.
94
-
95
- ---
96
-
97
- ## The skeleton
98
-
99
- `mx-agent report new` writes the seven headings with a one-line prompt under each. The
100
- headings come from one list in `mx-agent-system/cli/src/lib/report-format.ts`, and a test
101
- asserts this document names the same seven, so the two cannot drift.
102
-
103
- ---
104
-
105
- ## Worked example of section 3
106
-
107
- Weak, and it would pass the check while failing the reader:
108
-
109
- > The guards refuse most of what they should.
110
-
111
- Strong:
112
-
113
- > The guards refuse 28.6% of the commands they exist to refuse: 502 of 1,756, net of 287
114
- > `GIT_EXPERT=1` overrides. Zero could not run.
115
- > `node evidence-tools/guard-replay/summary.mjs "$STAGE"`
116
- > Method and full tables in `docs/guard-coverage.md`.
117
-
118
- The second version states the number, the denominator, what was excluded from it, the
119
- command, and where the method is written down. It also separates could-not-run from
120
- refused. A reader who doubts it has five ways in. A reader of the first has none.
@@ -1,240 +0,0 @@
1
- # Writing standard
2
-
3
- **Status:** Active. Injected into every team's `CLAUDE.local.md` on every conversation turn.
4
- **Owner:** the product owner of this repository.
5
- **Applies to:** every document, report, commit message and pull request body an agent writes.
6
-
7
- ## Why this file exists
8
-
9
- These rules ran on one person's memory until 2026-08-18. Agents learned them by being
10
- corrected during conversation. Every new agent then rediscovered them the same way, and
11
- the corrections cost a turn each.
12
-
13
- The measured case for writing them down is in this repository's own history. The four
14
- documents written after the rules were stated contain zero em dashes. The markdown written
15
- before them contains 647, and 39 uses of the five banned verbs survive today.
16
-
17
- ```sh
18
- grep -ro "—" --include=*.md docs product .mx-agent proof-of-concepts | wc -l # 647
19
- grep -rowE "arrives|carries|sits|lands|flows" --include=*.md \
20
- docs product .mx-agent proof-of-concepts | wc -l # 39
21
- grep -c "—" docs/legibility-plan.md .mx-agent/goals.md .mx-agent/lessons.md \
22
- product/mx-agent-prd.md # 0 each
23
- ```
24
-
25
- Run on 2026-08-18 at commit `817a4ef`.
26
-
27
- A rule nobody applies twice is an opinion. `product/mx-agent-prd.md:268` records the
28
- pattern: when we built a mechanism, teams followed the practice, and when we only wrote a
29
- rule, they stopped. So this file is injected rather than filed.
30
-
31
- ---
32
-
33
- ## The rules
34
-
35
- The block below is the text injected into every conversation turn. It starts at the marker
36
- so that the injected copy states the rules and nothing else.
37
-
38
- <!-- behavioral-start -->
39
-
40
- **1. No em dashes.** Use a comma, a colon, or two sentences.
41
-
42
- **2. No metaphor. A noun must be able to do the verb.** Ask whether the subject could
43
- perform the action. A finding cannot carry. A limit cannot sit. A message cannot land.
44
-
45
- **3. No motion or possession verbs for things that cannot move or hold.** The five that
46
- recur here are `arrives`, `carries`, `sits`, `lands`, `flows`. Replace with what is true:
47
- is, holds, states, records, bundles, stays, exists, reads.
48
-
49
- **4. Name the thing rather than foreshadowing it.** Do not write "there is a problem here"
50
- before the problem. State it, then explain it. Delete every sentence whose only job is to
51
- announce the next one.
52
-
53
- **5. No meta-commentary.** Do not describe the document inside the document. Do not defend
54
- choices nobody questioned. Do not say what you are about to do.
55
-
56
- **6. Active voice.** Name the actor. "Nothing fences pull request content" beats "pull
57
- request content arrives unfenced". If the actor is unknown, that absence is the finding.
58
-
59
- **7. Few adjectives.** An adjective that survives is one a reader could disagree with and
60
- check. Cut the rest. Prefer the number to the adjective.
61
-
62
- **8. Data before anecdote.** Lead with the measurement. The story explains the number, and
63
- it never stands in for one.
64
-
65
- **9. Every figure states a referenceable source.** A number publishes with the command, the
66
- file and line, or the query that produced it. Eight figures in this repository were correct
67
- against the wrong thing in one week, and the source line is what made them findable.
68
- See `.mx-agent/lessons.md` L2.
69
-
70
- **10. No weasel words.** Ban `essentially`, `arguably`, `fairly`, `quite`, `somewhat`,
71
- `it seems`, `it appears`, `in some sense`, `a number of`. State the claim, or state the
72
- uncertainty as its own sentence with a reason.
73
-
74
- **11. Never disparage another company, product or person.** Describe what a system does and
75
- what it does not do. Comparison is allowed. Contempt is not.
76
-
77
- **12. Assume internal writing becomes external.** A customer, an auditor or a court may
78
- read it. That changes nothing you would write honestly, and it removes everything you would
79
- not defend out loud.
80
-
81
- **13. Around 14 words per sentence.** Long sentences hide the actor and the claim. A
82
- sentence over 25 words is usually two sentences.
83
-
84
- **14. Report could-not-run as its own outcome.** Passed, failed and could-not-run are three
85
- results. Collapsing the third into either of the others is the defect in
86
- `mx-agent-system/standards/fail-loud-standard.md`.
87
-
88
- <!-- behavioral-end -->
89
-
90
- ---
91
-
92
- ## Corrections from this repository
93
-
94
- Each pair below is a real commit on `docs/mx-agent-prd`. The rule is abstract and the
95
- correction is not, so read these first.
96
-
97
- ### Rule 3, possession verbs
98
-
99
- | | |
100
- |---|---|
101
- | Before | `node_modules` **carries** Linux bindings |
102
- | After | `node_modules` **holds** Linux bindings |
103
- | Commit | `817a4ef`, `.mx-agent/lessons.md` |
104
-
105
- | | |
106
- |---|---|
107
- | Before | What share of findings **carry** a re-runnable source |
108
- | After | What share of findings **state** a re-runnable source |
109
- | Commit | `452c786`, `docs/legibility-plan.md` |
110
-
111
- | | |
112
- |---|---|
113
- | Before | the half that runs on every session, and it **carries none of it** |
114
- | After | the half that runs on every session, and it **records none of that** |
115
- | Commit | `0101a4a`, `docs/outcomes-from-git.md` |
116
-
117
- | | |
118
- |---|---|
119
- | Before | SDK version tracks the build it **carries** |
120
- | After | SDK version tracks the build it **bundles** |
121
- | Commit | `a03426d`, `proof-of-concepts/poc-1b-current-sdk.md` |
122
-
123
- The replacement is never one word for all four. Each takes the verb that is literally true
124
- of that subject. A directory holds, a finding states, a capture records, a package bundles.
125
-
126
- ### Rule 3, motion verbs
127
-
128
- | | |
129
- |---|---|
130
- | Before | Review comments hold the sharpest reasoning and **sit the furthest** from the code |
131
- | After | Review comments hold the sharpest reasoning and **are the furthest** from the code |
132
- | Commit | `7849351`, `product/mx-agent-prd.md` |
133
-
134
- | | |
135
- |---|---|
136
- | Before | text planted once can **sit unused** and then steer a session weeks later |
137
- | After | text planted once can **stay unused** and then steer a session weeks later |
138
- | Commit | `7849351`, `product/mx-agent-prd.md` |
139
-
140
- | | |
141
- |---|---|
142
- | Before | the limit **sits** far below what the hardware can handle |
143
- | After | the limit **is** far below what the hardware can handle |
144
- | Commit | `99c1197`, `product/mx-agent-prd.md` |
145
-
146
- ### Rule 2, metaphor
147
-
148
- | | |
149
- |---|---|
150
- | Before | Memory is not one feature **sitting next to** the others. It **sits underneath** them. |
151
- | After | Memory is not one feature **among** the others. **The others depend on it.** |
152
- | Commit | `99c1197`, `product/mx-agent-prd.md` |
153
-
154
- | | |
155
- |---|---|
156
- | Before | an unusual rule can **carry a decision written as code** |
157
- | After | an unusual rule can **express its decision as code** |
158
- | Commit | `99c1197`, `product/mx-agent-prd.md` |
159
-
160
- | | |
161
- |---|---|
162
- | Before | Sorting them by whether they have to **sit in the path of** an action and refuse it |
163
- | After | Sorting them by whether they have to **intercept** an action and refuse it |
164
- | Commit | `7849351`, `product/mx-agent-prd.md` |
165
-
166
- The last pair shows why the rule pays. The metaphor took five words and the accurate verb
167
- took one, and the accurate verb is also the word the code uses.
168
-
169
- ### Rule 6, active voice
170
-
171
- | | |
172
- |---|---|
173
- | Before | **Issue, pull-request, and dependency content arrive unfenced.** |
174
- | After | **Nothing fences issue, pull-request, or dependency content.** |
175
- | Commit | `99c1197`, `product/mx-agent-prd.md` |
176
-
177
- | | |
178
- |---|---|
179
- | Before | so the delegation limits, the prior-art requirement, and the decision authority **arrive with every turn** |
180
- | After | so **the model reads** the delegation limits, the prior-art requirement, and the decision authority **on every turn** |
181
- | Commit | `99c1197`, `product/mx-agent-prd.md` |
182
-
183
- Both corrections replace a motion verb and name an actor at the same time. That is the
184
- usual case. A sentence that needs `arrives` is usually a sentence with no subject in it.
185
-
186
- | | |
187
- |---|---|
188
- | Before | 13 agent definitions that each **carry** their own tool limits |
189
- | After | 13 agent definitions that each **declare** their own tool limits |
190
- | Commit | `99c1197`, `product/mx-agent-prd.md` |
191
-
192
- ### Rule 5, meta-commentary
193
-
194
- | | |
195
- |---|---|
196
- | Before | None of these were silently copied in to make the dependency "work," and none were silently broken. They are recorded here as split points. |
197
- | After | They are recorded here as split points. |
198
- | Commit | `99c1197`, `COUPLINGS.md` |
199
-
200
- The deleted sentence answered an accusation nobody made. It also used scare quotes, which
201
- are rule 10 wearing punctuation.
202
-
203
- ### Rule 9, every figure states a source
204
-
205
- The strongest example is a failure rather than a correction. Transcript size was published
206
- as 138 MB because `find -exec du -cb | tail -1` returns the last batch instead of the sum.
207
- The real figure is 2.26 GB. A write count inflated fivefold because a regex counted
208
- `2>/dev/null` as a write.
209
-
210
- Both were found by re-running the command next to the number. Neither was findable from the
211
- number alone. `.mx-agent/lessons.md` L2 holds the full list.
212
-
213
- ---
214
-
215
- ## How to apply rule 2 in one step
216
-
217
- Read your sentence and ask whether the subject could do the verb if you filmed it.
218
-
219
- - "The finding carries the evidence." A finding has no hands. Fails.
220
- - "The console records the decision." A program writes a record. Passes.
221
- - "The cost sits at $15.51." A number does not sit. Fails.
222
- - "The cost is $15.51." Passes.
223
-
224
- The test takes two seconds and catches rules 2, 3 and 6 together.
225
-
226
- ---
227
-
228
- ## What this standard does not cover
229
-
230
- It says nothing about document structure. The seven-section report format is a separate
231
- artifact, `mx-agent-system/standards/report-format.md`, and the framework enforces that one
232
- by refusing a report rather than by injection alone.
233
-
234
- It says nothing about code comments. The 647 em dashes measured above are mostly in source
235
- comments and in documents written before 2026-08-18. Nothing sweeps them, and this standard
236
- does not ask you to. Apply it to what you write.
237
-
238
- It sets no target for how often the operator asks for something in plainer language.
239
- `docs/legibility-plan.md` names that as the measure and records three requests in one
240
- session on 2026-08-18. Nothing collects it yet.