@memnexus-ai/mx-agent-cli 0.1.293 → 0.1.294-next.0
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.
- package/dist/__tests__/config-sync.test.js +54 -1
- package/dist/__tests__/config-sync.test.js.map +1 -1
- package/dist/__tests__/decision-check.test.d.ts +2 -0
- package/dist/__tests__/decision-check.test.d.ts.map +1 -0
- package/dist/__tests__/decision-check.test.js +105 -0
- package/dist/__tests__/decision-check.test.js.map +1 -0
- package/dist/__tests__/harness-extract.test.d.ts +19 -0
- package/dist/__tests__/harness-extract.test.d.ts.map +1 -0
- package/dist/__tests__/harness-extract.test.js +566 -0
- package/dist/__tests__/harness-extract.test.js.map +1 -0
- package/dist/__tests__/harness-wiring.test.d.ts +16 -0
- package/dist/__tests__/harness-wiring.test.d.ts.map +1 -0
- package/dist/__tests__/harness-wiring.test.js +469 -0
- package/dist/__tests__/harness-wiring.test.js.map +1 -0
- package/dist/__tests__/report-format.test.d.ts +2 -0
- package/dist/__tests__/report-format.test.d.ts.map +1 -0
- package/dist/__tests__/report-format.test.js +219 -0
- package/dist/__tests__/report-format.test.js.map +1 -0
- package/dist/__tests__/standards-injection.test.d.ts +2 -0
- package/dist/__tests__/standards-injection.test.d.ts.map +1 -0
- package/dist/__tests__/standards-injection.test.js +157 -0
- package/dist/__tests__/standards-injection.test.js.map +1 -0
- package/dist/agent-config/hooks/auto-capture-precompact.sh +74 -4
- package/dist/agent-config/hooks/auto-capture-session-end.sh +106 -4
- package/dist/agent-config/hooks/auto-checkpoint.sh +75 -5
- package/dist/agent-config/hooks/observability-sync.sh +46 -9
- package/dist/commands/config-sync.d.ts +37 -0
- package/dist/commands/config-sync.d.ts.map +1 -1
- package/dist/commands/config-sync.js +36 -18
- package/dist/commands/config-sync.js.map +1 -1
- package/dist/commands/dashboard.d.ts.map +1 -1
- package/dist/commands/dashboard.js +10 -2
- package/dist/commands/dashboard.js.map +1 -1
- package/dist/commands/decision.d.ts +20 -0
- package/dist/commands/decision.d.ts.map +1 -0
- package/dist/commands/decision.js +54 -0
- package/dist/commands/decision.js.map +1 -0
- package/dist/commands/monitor.d.ts.map +1 -1
- package/dist/commands/monitor.js +8 -2
- package/dist/commands/monitor.js.map +1 -1
- package/dist/commands/report.d.ts +33 -0
- package/dist/commands/report.d.ts.map +1 -0
- package/dist/commands/report.js +73 -0
- package/dist/commands/report.js.map +1 -0
- package/dist/commands/start.d.ts +4 -0
- package/dist/commands/start.d.ts.map +1 -1
- package/dist/commands/start.js +6 -0
- package/dist/commands/start.js.map +1 -1
- package/dist/commands/update.d.ts +13 -1
- package/dist/commands/update.d.ts.map +1 -1
- package/dist/commands/update.js +50 -1
- package/dist/commands/update.js.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +67 -3
- package/dist/index.js.map +1 -1
- package/dist/lib/agent-session.d.ts +12 -0
- package/dist/lib/agent-session.d.ts.map +1 -1
- package/dist/lib/agent-session.js +183 -41
- package/dist/lib/agent-session.js.map +1 -1
- package/dist/lib/claude.d.ts +12 -0
- package/dist/lib/claude.d.ts.map +1 -1
- package/dist/lib/claude.js +29 -2
- package/dist/lib/claude.js.map +1 -1
- package/dist/lib/decision-check.d.ts +48 -0
- package/dist/lib/decision-check.d.ts.map +1 -0
- package/dist/lib/decision-check.js +149 -0
- package/dist/lib/decision-check.js.map +1 -0
- package/dist/lib/harness/console/announce.d.ts +45 -0
- package/dist/lib/harness/console/announce.d.ts.map +1 -0
- package/dist/lib/harness/console/announce.js +48 -0
- package/dist/lib/harness/console/announce.js.map +1 -0
- package/dist/lib/harness/console/announce.test.d.ts +2 -0
- package/dist/lib/harness/console/announce.test.d.ts.map +1 -0
- package/dist/lib/harness/console/announce.test.js +104 -0
- package/dist/lib/harness/console/announce.test.js.map +1 -0
- package/dist/lib/harness/console/by-session.d.ts +50 -0
- package/dist/lib/harness/console/by-session.d.ts.map +1 -0
- package/dist/lib/harness/console/by-session.js +83 -0
- package/dist/lib/harness/console/by-session.js.map +1 -0
- package/dist/lib/harness/console/by-session.test.d.ts +2 -0
- package/dist/lib/harness/console/by-session.test.d.ts.map +1 -0
- package/dist/lib/harness/console/by-session.test.js +86 -0
- package/dist/lib/harness/console/by-session.test.js.map +1 -0
- package/dist/lib/harness/console/console.d.ts +67 -0
- package/dist/lib/harness/console/console.d.ts.map +1 -0
- package/dist/lib/harness/console/console.js +373 -0
- package/dist/lib/harness/console/console.js.map +1 -0
- package/dist/lib/harness/console/console.test.d.ts +2 -0
- package/dist/lib/harness/console/console.test.d.ts.map +1 -0
- package/dist/lib/harness/console/console.test.js +269 -0
- package/dist/lib/harness/console/console.test.js.map +1 -0
- package/dist/lib/harness/console/decision-request.d.ts +32 -0
- package/dist/lib/harness/console/decision-request.d.ts.map +1 -0
- package/dist/lib/harness/console/decision-request.js +112 -0
- package/dist/lib/harness/console/decision-request.js.map +1 -0
- package/dist/lib/harness/console/decision-request.test.d.ts +2 -0
- package/dist/lib/harness/console/decision-request.test.d.ts.map +1 -0
- package/dist/lib/harness/console/decision-request.test.js +75 -0
- package/dist/lib/harness/console/decision-request.test.js.map +1 -0
- package/dist/lib/harness/console/fixtures.d.ts +16 -0
- package/dist/lib/harness/console/fixtures.d.ts.map +1 -0
- package/dist/lib/harness/console/fixtures.js +49 -0
- package/dist/lib/harness/console/fixtures.js.map +1 -0
- package/dist/lib/harness/console/index.d.ts +15 -0
- package/dist/lib/harness/console/index.d.ts.map +1 -0
- package/dist/lib/harness/console/index.js +14 -0
- package/dist/lib/harness/console/index.js.map +1 -0
- package/dist/lib/harness/console/rank.d.ts +73 -0
- package/dist/lib/harness/console/rank.d.ts.map +1 -0
- package/dist/lib/harness/console/rank.js +113 -0
- package/dist/lib/harness/console/rank.js.map +1 -0
- package/dist/lib/harness/console/rank.test.d.ts +2 -0
- package/dist/lib/harness/console/rank.test.d.ts.map +1 -0
- package/dist/lib/harness/console/rank.test.js +124 -0
- package/dist/lib/harness/console/rank.test.js.map +1 -0
- package/dist/lib/harness/console/render.d.ts +22 -0
- package/dist/lib/harness/console/render.d.ts.map +1 -0
- package/dist/lib/harness/console/render.js +65 -0
- package/dist/lib/harness/console/render.js.map +1 -0
- package/dist/lib/harness/console/render.test.d.ts +2 -0
- package/dist/lib/harness/console/render.test.d.ts.map +1 -0
- package/dist/lib/harness/console/render.test.js +96 -0
- package/dist/lib/harness/console/render.test.js.map +1 -0
- package/dist/lib/harness/console/replay-cli.test.d.ts +2 -0
- package/dist/lib/harness/console/replay-cli.test.d.ts.map +1 -0
- package/dist/lib/harness/console/replay-cli.test.js +96 -0
- package/dist/lib/harness/console/replay-cli.test.js.map +1 -0
- package/dist/lib/harness/console/replay.d.ts +36 -0
- package/dist/lib/harness/console/replay.d.ts.map +1 -0
- package/dist/lib/harness/console/replay.js +59 -0
- package/dist/lib/harness/console/replay.js.map +1 -0
- package/dist/lib/harness/console/replay.test.d.ts +2 -0
- package/dist/lib/harness/console/replay.test.d.ts.map +1 -0
- package/dist/lib/harness/console/replay.test.js +81 -0
- package/dist/lib/harness/console/replay.test.js.map +1 -0
- package/dist/lib/harness/console/turn-reader.d.ts +50 -0
- package/dist/lib/harness/console/turn-reader.d.ts.map +1 -0
- package/dist/lib/harness/console/turn-reader.js +184 -0
- package/dist/lib/harness/console/turn-reader.js.map +1 -0
- package/dist/lib/harness/console/turn-reader.test.d.ts +2 -0
- package/dist/lib/harness/console/turn-reader.test.d.ts.map +1 -0
- package/dist/lib/harness/console/turn-reader.test.js +108 -0
- package/dist/lib/harness/console/turn-reader.test.js.map +1 -0
- package/dist/lib/harness/console/types.d.ts +109 -0
- package/dist/lib/harness/console/types.d.ts.map +1 -0
- package/dist/lib/harness/console/types.js +2 -0
- package/dist/lib/harness/console/types.js.map +1 -0
- package/dist/lib/harness/contract.d.ts +229 -0
- package/dist/lib/harness/contract.d.ts.map +1 -0
- package/dist/lib/harness/contract.js +22 -0
- package/dist/lib/harness/contract.js.map +1 -0
- package/dist/lib/harness/credential.d.ts +23 -0
- package/dist/lib/harness/credential.d.ts.map +1 -0
- package/dist/lib/harness/credential.js +81 -0
- package/dist/lib/harness/credential.js.map +1 -0
- package/dist/lib/harness/credential.test.d.ts +2 -0
- package/dist/lib/harness/credential.test.d.ts.map +1 -0
- package/dist/lib/harness/credential.test.js +74 -0
- package/dist/lib/harness/credential.test.js.map +1 -0
- package/dist/lib/harness/evaluate.d.ts +390 -0
- package/dist/lib/harness/evaluate.d.ts.map +1 -0
- package/dist/lib/harness/evaluate.js +988 -0
- package/dist/lib/harness/evaluate.js.map +1 -0
- package/dist/lib/harness/evaluate.test.d.ts +2 -0
- package/dist/lib/harness/evaluate.test.d.ts.map +1 -0
- package/dist/lib/harness/evaluate.test.js +621 -0
- package/dist/lib/harness/evaluate.test.js.map +1 -0
- package/dist/lib/harness/extract.d.ts +152 -0
- package/dist/lib/harness/extract.d.ts.map +1 -0
- package/dist/lib/harness/extract.js +1601 -0
- package/dist/lib/harness/extract.js.map +1 -0
- package/dist/lib/harness/gate.d.ts +48 -0
- package/dist/lib/harness/gate.d.ts.map +1 -0
- package/dist/lib/harness/gate.js +60 -0
- package/dist/lib/harness/gate.js.map +1 -0
- package/dist/lib/harness/gate.test.d.ts +2 -0
- package/dist/lib/harness/gate.test.d.ts.map +1 -0
- package/dist/lib/harness/gate.test.js +111 -0
- package/dist/lib/harness/gate.test.js.map +1 -0
- package/dist/lib/harness/self-check.d.ts +59 -0
- package/dist/lib/harness/self-check.d.ts.map +1 -0
- package/dist/lib/harness/self-check.js +56 -0
- package/dist/lib/harness/self-check.js.map +1 -0
- package/dist/lib/harness/self-check.test.d.ts +2 -0
- package/dist/lib/harness/self-check.test.d.ts.map +1 -0
- package/dist/lib/harness/self-check.test.js +43 -0
- package/dist/lib/harness/self-check.test.js.map +1 -0
- package/dist/lib/harness/transcript.d.ts +65 -0
- package/dist/lib/harness/transcript.d.ts.map +1 -0
- package/dist/lib/harness/transcript.js +144 -0
- package/dist/lib/harness/transcript.js.map +1 -0
- package/dist/lib/harness/transcript.test.d.ts +2 -0
- package/dist/lib/harness/transcript.test.d.ts.map +1 -0
- package/dist/lib/harness/transcript.test.js +118 -0
- package/dist/lib/harness/transcript.test.js.map +1 -0
- package/dist/lib/harness-wiring.d.ts +145 -0
- package/dist/lib/harness-wiring.d.ts.map +1 -0
- package/dist/lib/harness-wiring.js +280 -0
- package/dist/lib/harness-wiring.js.map +1 -0
- package/dist/lib/report-format.d.ts +132 -0
- package/dist/lib/report-format.d.ts.map +1 -0
- package/dist/lib/report-format.js +317 -0
- package/dist/lib/report-format.js.map +1 -0
- package/dist/lib/standards.d.ts +90 -0
- package/dist/lib/standards.d.ts.map +1 -0
- package/dist/lib/standards.js +194 -0
- package/dist/lib/standards.js.map +1 -0
- package/dist/lib/terminal-ui.d.ts.map +1 -1
- package/dist/lib/terminal-ui.js +12 -1
- package/dist/lib/terminal-ui.js.map +1 -1
- package/dist/standards/decision-request.md +90 -0
- package/dist/standards/fail-loud-standard.md +495 -0
- package/dist/standards/report-format.md +120 -0
- package/dist/standards/writing-standard.md +240 -0
- package/package.json +3 -2
|
@@ -0,0 +1,120 @@
|
|
|
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.
|
|
@@ -0,0 +1,240 @@
|
|
|
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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@memnexus-ai/mx-agent-cli",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.294-next.0",
|
|
4
4
|
"description": "CLI for creating and managing AI agent teams",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -12,7 +12,8 @@
|
|
|
12
12
|
"start": "node dist/index.js",
|
|
13
13
|
"prepublishOnly": "npm run build",
|
|
14
14
|
"test": "vitest run",
|
|
15
|
-
"test:watch": "vitest"
|
|
15
|
+
"test:watch": "vitest",
|
|
16
|
+
"prepare": "node scripts/install-hooks.mjs"
|
|
16
17
|
},
|
|
17
18
|
"files": [
|
|
18
19
|
"dist/",
|