ennodia 0.1.1 → 0.2.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.
Files changed (46) hide show
  1. package/CONTRIBUTING.md +60 -36
  2. package/README.md +74 -58
  3. package/bench/README.md +7 -5
  4. package/bench/bug-recall/run.ts +12 -4
  5. package/bin/ennodia +23 -2
  6. package/docs/assets/agents/mcp.svg +1 -1
  7. package/docs/assets/orchestration-pipeline.svg +4 -3
  8. package/docs/comparisons/agent-frameworks.md +15 -10
  9. package/docs/comparisons/autogen.md +20 -15
  10. package/docs/comparisons/chathub.md +15 -14
  11. package/docs/comparisons/index.md +30 -22
  12. package/docs/comparisons/langgraph.md +19 -12
  13. package/docs/comparisons/mixture-of-agents.md +20 -17
  14. package/docs/comparisons/model-merging.md +7 -5
  15. package/docs/comparisons/openrouter.md +30 -22
  16. package/docs/concepts/compositional-audits.md +16 -13
  17. package/docs/concepts/data-governance.md +31 -15
  18. package/docs/concepts/how-ennodia-works.md +48 -22
  19. package/docs/concepts/interfaces-and-core.md +19 -6
  20. package/docs/concepts/second-opinions.md +20 -20
  21. package/docs/getting-started.md +55 -27
  22. package/docs/guides/agent-skills.md +16 -13
  23. package/docs/guides/budgets-and-limits.md +30 -20
  24. package/docs/guides/running-better-audits.md +50 -44
  25. package/docs/index.md +60 -37
  26. package/docs/install.md +41 -32
  27. package/docs/reference/benchmarks.md +6 -4
  28. package/docs/reference/controlled-english.md +130 -0
  29. package/docs/reference/ennodia-io.md +28 -22
  30. package/docs/reference/mcp-tools.md +244 -87
  31. package/docs/reference/supported-harnesses.md +9 -9
  32. package/package.json +7 -5
  33. package/src/advisor.ts +685 -0
  34. package/src/budget.ts +25 -6
  35. package/src/cli.ts +1 -1
  36. package/src/compare.ts +248 -52
  37. package/src/compositional.ts +18 -0
  38. package/src/core.ts +547 -16
  39. package/src/harnesses.ts +33 -2
  40. package/src/index.ts +38 -0
  41. package/src/plan-advice.ts +601 -0
  42. package/src/runs.ts +74 -9
  43. package/src/server.ts +312 -46
  44. package/src/skills.ts +131 -11
  45. package/src/tasks.ts +192 -22
  46. package/src/version.ts +1 -1
@@ -1,24 +1,26 @@
1
1
  ---
2
- title: Running Better Audits
3
- description: How to ask Ennodia for audits that catch user-facing product problems, not only consistency issues.
2
+ title: Better Audits
3
+ description: How Ennodia audits can detect product problems that users see, not only consistency issues.
4
4
  ---
5
5
 
6
- Ennodia can ask several agents for review, but the result still depends on the
7
- audit rubric. A vague request such as "audit the website" often turns into a
8
- consistency pass: broken links, mismatched docs, release metadata, type errors,
9
- and copy drift. That is useful, but it does not prove the page is clear to a
10
- first-time visitor.
6
+ Ennodia can request review from multiple agents. The result still depends on the
7
+ audit rubric. A vague request such as "audit the website" often produces a
8
+ consistency pass.
9
+
10
+ This pass can find broken links, mismatched documentation, release metadata errors, type
11
+ errors, and copy drift. It does not prove that the page is clear to a first-time
12
+ visitor.
11
13
 
12
14
  ## Quick Recipe
13
15
 
14
- Use a source-grounded audit when the answer depends on docs, standards, package
15
- behavior, or another product's public surface:
16
+ Use a source-grounded audit for answers that depend on documentation,
17
+ standards, package behavior, or another product's public surface:
16
18
 
17
19
  ```json
18
20
  {
19
21
  "tool": "ennodia_run",
20
22
  "arguments": {
21
- "prompt": "Audit these docs against the linked primary sources. Separate facts from judgment and recommend exact edits.",
23
+ "prompt": "Audit this documentation against the linked primary sources. Separate facts from judgment and recommend exact edits.",
22
24
  "mode": "parallel",
23
25
  "compare": true,
24
26
  "skillIds": ["source-grounded-audit"]
@@ -26,8 +28,8 @@ behavior, or another product's public surface:
26
28
  }
27
29
  ```
28
30
 
29
- Install the skill first if the harness has not seen it yet. See
30
- [Using Agent Skills](/docs/guides/agent-skills/).
31
+ Install the skill first if the harness does not have it. See
32
+ [Agent Skills](/docs/guides/agent-skills/).
31
33
 
32
34
  ## Pick the Audit Mode
33
35
 
@@ -35,63 +37,67 @@ Name the failure mode you want reviewers to catch.
35
37
 
36
38
  | Audit mode | Main question |
37
39
  | --- | --- |
38
- | Consistency | Do the docs, website, package metadata, and behavior agree? |
40
+ | Consistency | Do the documentation, website, package metadata, and behavior agree? |
39
41
  | Conversion | Would a first-time visitor understand why to install this? |
40
- | Visual QA | Does the rendered page look balanced on desktop and mobile? |
42
+ | Visual quality assurance (QA) | Does the rendered page look balanced on desktop and mobile? |
41
43
  | Accessibility | Can the page be navigated and understood with assistive technology? |
42
44
  | Release | Can the package be published, installed, and launched safely? |
43
45
 
44
46
  Use separate passes when the stakes are different. A page can pass consistency
45
47
  and still fail conversion.
46
48
 
47
- For a large review, split the work into focused slices instead of sending the
48
- entire prompt to every reviewer. See
49
+ For a large review, split the work into focused slices. Do not send the entire
50
+ prompt to each reviewer. See
49
51
  [Compositional Audits](/docs/concepts/compositional-audits/).
50
52
 
51
53
  ## Landing Page Rubric
52
54
 
53
- For landing pages, ask each reviewer to answer these questions:
55
+ For landing pages, require each reviewer to answer these questions:
54
56
 
55
57
  - Can a first-time visitor explain what the product does within ten seconds?
56
58
  - Is the reason to install visible in the hero or first section?
57
59
  - Is the install path visible before architecture details?
58
- - Does the page use user language instead of maintainer language?
60
+ - Does the page use user language and avoid maintainer language?
59
61
  - Are screenshots or rendered viewports available for visual judgment?
60
- - Does the final section strengthen trust instead of ending on defensive copy?
62
+ - Does the final section strengthen trust and avoid defensive copy?
61
63
 
62
- For Ennodia itself, prefer `mode: "parallel"` and `compare: true` for this kind
63
- of review. A single source-only answer is not enough for product-facing pages.
64
+ For Ennodia, use `mode: "parallel"` and `compare: true` for this type of review.
65
+ A single source-only answer is not sufficient for product pages.
64
66
 
65
67
  ## Include Rendered Evidence
66
68
 
67
- Source-only review misses visual problems. Before asking Ennodia to judge a
68
- website, include desktop and mobile screenshots or ask a harness with browser
69
+ Source-only review misses visual problems. Before an Ennodia website review,
70
+ include desktop and mobile screenshots. You can also use a harness with browser
69
71
  access to inspect the rendered page.
70
72
 
71
- Rendered evidence catches problems such as oversized logos, unbalanced hero
72
- spacing, text that feels too large or too small, delayed content, and accidental
73
- visual hierarchy.
73
+ Rendered evidence can show oversized logos, unbalanced hero space, incorrect
74
+ text size, delayed content, and accidental visual hierarchy.
75
+
76
+ When local files matter, include the file paths and a short text description.
77
+ Then inspect the child outputs for access errors.
74
78
 
75
- When screenshots or other local files matter, include both the file paths and a
76
- short text description. Then check the child outputs for access errors. If a
77
- harness cannot read the files, stage them somewhere it can access and rerun; do
78
- not treat that failure as a normal design review.
79
+ If a harness cannot read the files, put them in an accessible location and run
80
+ the task again. Do not treat that failure as a normal design review.
79
81
 
80
82
  ## Ground Standards in Sources
81
83
 
82
- When the audit depends on an external standard, registry convention, or product
83
- behavior, include the sources in the prompt and ask reviewers to separate facts
84
- from judgment. Otherwise a model council can confidently optimize the wrong
85
- model of the world.
84
+ Include primary sources when an audit depends on an external standard, registry
85
+ convention, or product behavior. Require reviewers to separate facts from
86
+ judgment.
87
+
88
+ Without these sources, a model council can confidently use an incorrect model
89
+ of the world.
90
+
91
+ Agent Skills are one cautionary example. They are not an Ennodia-private prompt
92
+ format. They are portable `SKILL.md` folders.
86
93
 
87
- Agent Skills are the cautionary example: they are not an Ennodia-private prompt
88
- format. They are portable `SKILL.md` folders discovered by tools such as Codex,
89
- Claude Code, OpenCode, and Antigravity in native locations. A useful audit for
90
- skills must start from those product docs before recommending an Ennodia API.
94
+ Tools such as Codex, Claude Code, OpenCode, and Antigravity discover these
95
+ folders in native locations. Reviewers must read that product documentation
96
+ before they recommend an Ennodia application programming interface (API).
91
97
 
92
- The bundled `source-grounded-audit` skill exists for this case. Install it into
93
- the harnesses you use for standards-sensitive audits, then ask Ennodia to use
94
- that skill when the answer depends on external docs.
98
+ The bundled `source-grounded-audit` skill supports this case. Install it in the
99
+ harnesses that perform standards-sensitive audits. Then tell Ennodia to use the
100
+ skill when the answer depends on external documentation.
95
101
 
96
102
  ## Good Prompt Shape
97
103
 
@@ -107,11 +113,11 @@ If screenshots are available, judge the rendered page too.
107
113
 
108
114
  Return:
109
115
  1. The top conversion blockers, prioritized.
110
- 2. Whether the first viewport explains what this is and why to install it.
116
+ 2. If the first viewport explains what this is and why to install it.
111
117
  3. Exact replacement copy for weak sections.
112
118
  4. Visual changes needed for desktop and mobile.
113
119
  5. Which issues a consistency-only audit would miss.
114
120
  ```
115
121
 
116
- The last item matters. It forces the reviewer to state the limits of the audit,
117
- which helps decide whether another pass is needed.
122
+ The last item makes the reviewer state the audit limits. This information helps
123
+ you decide if another pass is necessary.
package/docs/index.md CHANGED
@@ -1,72 +1,89 @@
1
1
  ---
2
2
  title: What is Ennodia?
3
- description: Start here to understand Ennodia, choose the right setup path, and find the docs page for your task.
3
+ description: Start here to understand Ennodia, select an installation path, and find the documentation page for your task.
4
4
  ---
5
5
 
6
- Ennodia is a local MCP server for multi-agent review. Your primary AI agent can
7
- ask other installed agent CLIs for help, inspect what happened, and let a model
8
- compare the answers before you get one result.
6
+ Ennodia is a local Model Context Protocol (MCP) server for multi-agent review.
7
+ Your primary artificial intelligence (AI) agent can request help from installed
8
+ agent command-line interfaces (CLIs).
9
9
 
10
- It is useful when one agent is already working and the task is important enough
11
- to spend extra model work on review, planning, diagnosis, or comparison.
12
- Ennodia is deliberation-class tooling: a run usually takes minutes, and Compare
13
- adds a serial judge pass plus a serial synthesizer pass after child agents
14
- finish.
10
+ The primary agent can inspect the work. It can use a Judge and Result Advisor to
11
+ compare the answers.
12
+
13
+ An optional Plan Advisor can first propose a bounded team. It cannot execute the
14
+ proposal.
15
+
16
+ Use Ennodia when one agent has a task that needs additional review, a plan, a
17
+ diagnosis, or a comparison. A run usually takes minutes.
18
+
19
+ Compare adds a serial Judge pass and a serial Result Advisor pass after the
20
+ child agents finish.
15
21
 
16
22
  ## The Problem Ennodia Solves
17
23
 
18
- The primary problem is single-model judgment as a single point of failure. One
19
- agent can miss the risky bug, accept a weak plan, or hallucinate confidence.
20
- For important work, you often want independent second opinions and a record of
21
- what each reviewer actually did.
24
+ Single-model judgment can be a single point of failure. One agent can miss a
25
+ risky bug, accept a weak plan, or report false confidence.
26
+
27
+ Important work can require independent second opinions and a record of each
28
+ reviewer's work.
22
29
 
23
- The enabling asset is that many developers already pay for several independent
24
- agent subscriptions — Codex, Claude Code, Antigravity, OpenCode, and others.
25
- Ennodia turns the installed CLIs on one machine into a review panel your
26
- primary agent can use, without new accounts, API keys, or vendor migration:
30
+ Many developers have independent agent subscriptions. Examples include Codex,
31
+ Claude Code, Antigravity, and OpenCode. Ennodia makes their installed CLIs a
32
+ review panel for the primary agent.
27
33
 
28
- - Agents reach Ennodia through MCP, the protocol agents already speak.
29
- - Model-led Compare produces a structured disagreement map and final synthesis.
34
+ This process does not require new accounts or a vendor migration. It does not
35
+ require new application programming interface (API) keys.
36
+
37
+ - Agents reach Ennodia through MCP, a protocol that the agents support.
38
+ - A Plan Advisor can propose inert harness, model, and skill assignments. A
39
+ separate explicit call must launch the validated plan.
40
+ - Model-led Compare uses a Judge for the disagreement map and a Result Advisor
41
+ for the recommended answer.
30
42
  - One shared core discovers harnesses, plans routes, checks local preflight
31
43
  limits, tracks tasks, and keeps the trace visible.
32
- - The separate Ennodia IO package is an experimental app-facing appendix.
44
+ - The separate Ennodia IO package is an experimental appendix for apps.
33
45
 
34
46
  ## Why People Use It
35
47
 
36
48
  Ennodia:
37
49
 
38
50
  - discovers supported local harnesses automatically
39
- - uses the CLIs, installs, subscriptions, and model choices you already have
51
+ - uses your installed CLIs, subscriptions, and model choices
40
52
  - estimates preflight input-token budgets and enforces local caps on that
41
53
  estimate
42
- - keeps child task IDs, status, ETA, output, failures, Compare state, and run
43
- history visible, including terminal receipts across server restarts
44
- - lets a model judge and synthesize parallel answers
54
+ - keeps child task identifiers (IDs), status, estimated completion time,
55
+ output, failures, Compare state, and run
56
+ history visible
57
+ - can retain terminal receipts across server restarts
58
+ - lets a Judge inspect parallel answers and a Result Advisor combine the
59
+ findings
45
60
  - uses native Agent Skills through harness-visible `SKILL.md` folders
46
61
 
47
- Durable model and skill preference memory is roadmap work. Terminal run history
48
- is persisted locally under `~/.ennodia/history/` by default; live in-progress
49
- state remains process-local.
62
+ Durable model and skill preference memory is roadmap work. By default, Ennodia
63
+ stores terminal run history under `~/.ennodia/history/`. Live in-progress state
64
+ remains process-local.
50
65
 
51
66
  ## Choose Your Path
52
67
 
53
- | If you want to... | Start here |
68
+ | Task | Page |
54
69
  | --- | --- |
55
- | Ask an agent to install Ennodia for you | [Installation for Agents](./install/) |
56
- | Set it up manually or work from a checkout | [Quickstart](./getting-started/) |
70
+ | Request Ennodia installation from an agent | [Installation for Agents](./install/) |
71
+ | Install it manually or work from a checkout | [Quickstart](./getting-started/) |
57
72
  | Estimate or limit a costly run | [Budgets and Limits](./guides/budgets-and-limits/) |
58
- | Install or use `source-grounded-audit` and other skills | [Using Agent Skills](./guides/agent-skills/) |
73
+ | Install or use `source-grounded-audit` and other skills | [Agent Skills](./guides/agent-skills/) |
59
74
  | Understand the run lifecycle | [How Ennodia Works](./concepts/how-ennodia-works/) |
75
+ | Request a bounded team proposal before work | [How Ennodia Works](./concepts/how-ennodia-works/#plan-advisor) |
60
76
  | Use panels for second opinions | [Second Opinions as Infrastructure](./concepts/second-opinions/) |
61
77
  | Understand local storage and data movement | [Data Governance](./concepts/data-governance/) |
62
78
  | Understand Core, <span class="agent-logo agent-logo--mcp" aria-hidden="true"></span>MCP, and experimental IO | [Interfaces and Core](./concepts/interfaces-and-core/) |
63
79
  | Split a large review into smaller shards | [Compositional Audits](./concepts/compositional-audits/) |
64
80
  | Call the exact <span class="agent-logo agent-logo--mcp" aria-hidden="true"></span>MCP tools | [MCP Tools](./reference/mcp-tools/) |
65
- | Call Ennodia from a local HTTP app | [Ennodia IO](./reference/ennodia-io/) |
66
- | Check harness IDs and setup notes | [Supported Harnesses](./reference/supported-harnesses/) |
81
+ | Call Ennodia from a local web app | [Ennodia IO](./reference/ennodia-io/) |
82
+ | Check harness identifiers and installation notes | [Supported Harnesses](./reference/supported-harnesses/) |
83
+ | Use the ASD-STE100 rules and approved Ennodia terms | [Controlled English](./reference/controlled-english/) |
67
84
  | Inspect benchmark receipts | [Benchmarks](./reference/benchmarks/) |
68
- | Decide whether Ennodia fits your workflow | [Comparisons](./comparisons/) |
69
- | Get better output from model-led Compare | [Running Better Audits](./guides/running-better-audits/) |
85
+ | Decide if Ennodia fits your workflow | [Comparisons](./comparisons/) |
86
+ | Get better output from model-led Compare | [Better Audits](./guides/running-better-audits/) |
70
87
 
71
88
  ## First Useful Run
72
89
 
@@ -77,5 +94,11 @@ state remains process-local.
77
94
  5. Poll `ennodia_get_run` until it reaches `succeeded`, `failed`, or
78
95
  `cancelled`.
79
96
 
80
- The user should not need to manually grade every child answer unless they want
81
- to inspect the trace.
97
+ The user does not normally need to grade each child answer. The trace remains
98
+ available for inspection.
99
+
100
+ For a team proposal, call `ennodia_start_plan_advice`. Then poll
101
+ `ennodia_get_plan_advice`. A ready result is only validated data.
102
+
103
+ Call `ennodia_start_advised_plan` with the returned plan digest once to start the
104
+ work.
package/docs/install.md CHANGED
@@ -1,11 +1,10 @@
1
1
  ---
2
2
  title: Installation for Agents
3
- description: A copy-paste setup page for agents installing Ennodia into Codex, Claude Code, OpenCode, Antigravity, and other MCP clients.
3
+ description: A copy-paste installation page for agents that install Ennodia in Codex, Claude Code, OpenCode, Antigravity, and other Model Context Protocol (MCP) clients.
4
4
  ---
5
5
 
6
- This page is for the agent doing the setup. If the user gave you this link, the
7
- goal is to install Ennodia as a local MCP server and turn it on in the MCP
8
- client they use.
6
+ This page is for the agent that does the installation. Install Ennodia as a local Model
7
+ Context Protocol (MCP) server. Then enable it in the user's MCP client.
9
8
 
10
9
  ## Copy-Paste Prompt
11
10
 
@@ -15,18 +14,18 @@ try-ennodia.cherninlab.com
15
14
 
16
15
  ## Install Command
17
16
 
18
- Use the npm package for normal MCP client setup:
17
+ Use the npm package for normal MCP client installation:
19
18
 
20
19
  ```sh
21
20
  npx -y ennodia
22
21
  ```
23
22
 
24
- Requires Bun `1.3.14` or newer. `npx` downloads Ennodia; Bun runs it. If the
25
- client supports Bun directly, `bunx ennodia` is also fine.
23
+ Ennodia requires Bun `1.3.14` or newer. `npx` downloads Ennodia. Bun runs it.
24
+ If the client supports Bun directly, use `bunx ennodia`.
26
25
 
27
- ## MCP Config
26
+ ## MCP Configuration
28
27
 
29
- Add this server to the user's MCP client config:
28
+ Add this server to the user's MCP client configuration:
30
29
 
31
30
  ```json
32
31
  {
@@ -54,7 +53,7 @@ For a local Ennodia checkout, use:
54
53
 
55
54
  ## First Agent Checks
56
55
 
57
- After configuring MCP, call these tools:
56
+ After MCP configuration, call these tools:
58
57
 
59
58
  1. `ennodia_list_harnesses`
60
59
  2. `ennodia_estimate_budget`
@@ -62,35 +61,44 @@ After configuring MCP, call these tools:
62
61
  4. `ennodia_run`
63
62
  5. `ennodia_get_run`
64
63
 
65
- `ennodia_list_harnesses` should show which local tools are available — see the
66
- current adapter list and IDs in
64
+ `ennodia_list_harnesses` shows the available local tools. See the current
65
+ adapter list and identifiers (IDs) in
67
66
  [Supported Harnesses](/docs/reference/supported-harnesses/).
68
67
 
69
- ## What You Are Installing
68
+ ## Installed Components
70
69
 
71
- Ennodia is a local MCP server. It lets the user's main agent ask other installed
72
- agent CLIs for help during the same task.
70
+ Ennodia is a local MCP server. It lets the user's main agent request help from
71
+ other installed agent command-line interface (CLI) programs during the same task.
73
72
 
74
- The important part is not "many agents" by itself. Ennodia works with existing
75
- local installs, subscriptions, and model choices. It discovers supported CLIs,
76
- starts child tasks, tracks status and output, estimates the input-token budget,
77
- and can ask a model to compare the answers before returning one result.
73
+ The number of agents is not the primary benefit. Ennodia uses current local
74
+ installs, subscriptions, and model choices. It discovers supported CLI programs and
75
+ starts child tasks. It also tracks status and output.
78
76
 
79
- Ennodia is asynchronous by design. A primary agent can start a run, keep working,
80
- and later poll `ennodia_get_run` for exact status, ETA, child task IDs, Compare
81
- state, failures, and the final answer.
77
+ Ennodia estimates the input-token budget. A Judge can compare the answers. A
78
+ Result Advisor can then recommend one result.
79
+
80
+ An optional Plan Advisor can propose harness, model, and skill assignments. It
81
+ cannot start them. A separate explicit call must start the validated plan.
82
+
83
+ Ennodia is asynchronous by design. A primary agent can start a run and continue
84
+ its main task. It can later poll `ennodia_get_run` for status and estimated
85
+ completion time.
86
+
87
+ The result also contains child task IDs, Compare state, failures, and the final
88
+ answer.
82
89
 
83
90
  Tell the user a real run can take minutes. Compare adds two serial model passes
84
91
  after the selected child agents finish.
85
92
 
86
93
  ## Example Requests
87
94
 
88
- Use Ennodia when the user is intentionally spending more model work to get a
89
- better answer than one agent usually gives.
95
+ Use Ennodia when the user permits more model work to get a better answer than
96
+ one agent usually gives.
90
97
 
91
98
  ```text
92
- Use Ennodia to ask several available agents to review this bug fix. Compare the
93
- answers, name disagreements, and return the highest-risk issue first.
99
+ Use Ennodia to request a review from multiple available agents.
100
+ Compare the answers for this bug fix.
101
+ Name the disagreements and return the highest-risk issue first.
94
102
  ```
95
103
 
96
104
  ```text
@@ -99,19 +107,20 @@ Compare the plans and tell me which assumptions each model made.
99
107
  ```
100
108
 
101
109
  ```text
102
- Use Ennodia twice: once with source-grounded-audit and once without it. Compare
103
- what the skill changed before recommending the final docs edit.
110
+ Use Ennodia twice.
111
+ Use source-grounded-audit for the first run, but not for the second run.
112
+ Compare the results before you recommend the final documentation edit.
104
113
  ```
105
114
 
106
- Compare is model-led. The user should not have to manually judge parallel
107
- answers unless they want to inspect the trace.
115
+ Compare is model-led. The user does not normally need to judge the parallel
116
+ answers. The trace remains available for inspection.
108
117
 
109
118
  ## Optional Next Steps
110
119
 
111
120
  - Use [Budgets and Limits](/docs/guides/budgets-and-limits/) before costly
112
121
  parallel runs.
113
- - Use [Using Agent Skills](/docs/guides/agent-skills/) before passing
122
+ - Use [Agent Skills](/docs/guides/agent-skills/) before you pass
114
123
  `skillIds` such as `source-grounded-audit`.
115
124
  - Use [Supported Harnesses](/docs/reference/supported-harnesses/) when a local
116
- CLI is missing, unrunnable, or using the wrong model ID.
125
+ CLI is missing, not runnable, or has the wrong model ID.
117
126
  - Use [MCP Tools](/docs/reference/mcp-tools/) for exact parameter shapes.
@@ -4,8 +4,8 @@ description: Deterministic benchmark snapshots for Ennodia's multi-agent bug-rec
4
4
  ---
5
5
 
6
6
  The first benchmark is `multi-model-bug-recall`: TypeScript review fixtures with
7
- committed bug oracles. It measures whether a condition recalls required
8
- findings and avoids known false-positive traps.
7
+ committed bug oracles. It measures required-finding recall for a condition and
8
+ checks for known false-positive traps.
9
9
 
10
10
  ## Current Snapshot
11
11
 
@@ -19,6 +19,8 @@ bun run bench:bug-recall -- --out /tmp/ennodia-benchmark-snapshot
19
19
 
20
20
  Mode: fixture, using committed reference outputs.
21
21
 
22
+ The F1 score combines recall and precision. FP means false positive.
23
+
22
24
  | Condition | Cases | Recall | Precision | F1 | High recall | FP traps |
23
25
  | --- | ---: | ---: | ---: | ---: | ---: | ---: |
24
26
  | `claude-code-solo` | 4 | 87.5% | 100% | 93.3% | 100% | 0 |
@@ -47,8 +49,8 @@ does not launch child agents:
47
49
  bun run bench:bug-recall
48
50
  ```
49
51
 
50
- Live mode starts real local harnesses and varies with installed CLI versions,
51
- models, account state, and machine configuration:
52
+ Live mode starts real local harnesses and varies with installed command-line
53
+ interface (CLI) versions, models, account state, and machine configuration:
52
54
 
53
55
  ```sh
54
56
  bun run bench:bug-recall:live -- --fixture 001-missing-await
@@ -0,0 +1,130 @@
1
+ ---
2
+ title: Controlled English
3
+ description: Ennodia terminology and writing rules for ASD-STE100 Issue 9.
4
+ ---
5
+
6
+ # Controlled English
7
+
8
+ Ennodia documentation uses ASD-STE100 Issue 9 as its writing standard.
9
+ This policy applies to the README, documentation, website text, and visible asset text.
10
+
11
+ Commands, API fields, status values, model IDs, and quoted interface text are data.
12
+ Keep this data exact, even when its text does not use controlled English.
13
+
14
+ ## Writing Rules
15
+
16
+ - Use American English.
17
+ - Use active voice when the agent is known.
18
+ - Give one instruction in each procedural sentence.
19
+ - Use 20 words or fewer in a procedural sentence.
20
+ - Use 25 words or fewer in a descriptive sentence.
21
+ - Use six sentences or fewer in one paragraph.
22
+ - Do not use semicolons.
23
+ - Do not use a contraction.
24
+ - Use one approved term for each concept.
25
+ - Define a necessary abbreviation at its first use on each independent page.
26
+ - Preserve exact product names, commands, paths, model IDs, and API fields.
27
+
28
+ The landing page uses `AI makes mistakes` as an approved fixed tagline.
29
+ Define `artificial intelligence (AI)` in the sentence directly below it.
30
+
31
+ Automated checks can find some defects, but they cannot certify compliance.
32
+ A human reviewer must confirm meaning, grammar, and correct technical use.
33
+
34
+ ## Ennodia Termbase
35
+
36
+ The Ennodia project approves the following terms for its software documentation.
37
+ Use the listed meaning and part of speech.
38
+
39
+ | Term | Type | Approved meaning |
40
+ | --- | --- | --- |
41
+ | Ennodia | technical noun | The software product in this repository. |
42
+ | artificial intelligence (AI) | technical noun | Software that produces or evaluates model output. |
43
+ | AI makes mistakes | approved tagline | The exact Ennodia landing-page headline. Keep this phrase unchanged. |
44
+ | Model Context Protocol (MCP) | technical noun | The protocol that exposes Ennodia tools to a compatible client. |
45
+ | command-line interface (CLI) | technical noun | A text interface that accepts commands. |
46
+ | application programming interface (API) | technical noun | A defined interface that software uses to exchange data. |
47
+ | Hypertext Transfer Protocol (HTTP) | technical noun | The protocol that Ennodia IO uses for local requests. |
48
+ | user interface (UI) | technical noun | The visible controls and output that a user can operate. |
49
+ | Ennodia IO | product name | The separate local HTTP package for Ennodia. |
50
+ | harness | technical noun | An Ennodia adapter that starts one supported local CLI. |
51
+ | model | technical noun | A named AI model that a harness can select. |
52
+ | large language model (LLM) | technical noun | A model that processes and produces language or code. |
53
+ | Agent Skill | technical noun | Installed instructions that a compatible harness can load. |
54
+ | skill | technical noun | The short form of Agent Skill after the full term appears. |
55
+ | task | technical noun | One harness process that Ennodia starts and tracks. |
56
+ | worker | technical noun | A task that performs one assigned part of a plan. |
57
+ | worker pool | technical noun | A defined group of workers with the same assignment type. |
58
+ | slice | technical noun | One focused part of a compositional task. |
59
+ | plan | technical noun | Validated data that defines ordered worker tasks. |
60
+ | plan digest | technical noun | A hash that identifies the exact validated plan. |
61
+ | inventory | technical noun | The runnable harnesses and installed skills that Ennodia finds. |
62
+ | inventory fingerprint | technical noun | A hash that identifies one inventory state. |
63
+ | Plan Advisor | technical noun | The role that proposes a bounded plan as inert data. |
64
+ | Judge | technical noun | The Compare role that maps agreements, conflicts, and risks. |
65
+ | Result Advisor | technical noun | The Compare role that recommends an answer from available evidence. |
66
+ | Compare | technical noun or verb | The Ennodia operation that uses a Judge and a Result Advisor. |
67
+ | run | technical noun or verb | A tracked orchestration, or the action that starts it. |
68
+ | receipt | technical noun | A bounded record of tasks, events, results, and execution data. |
69
+ | route | technical noun or verb | A harness selection, or the action that selects a harness. |
70
+ | poll | technical verb | To request current status at controlled intervals. |
71
+ | review | technical noun or verb | An inspection of code, documentation, or model output for defects. |
72
+ | standard input/output (stdio) | technical noun | The paired input and output streams of an MCP server process. |
73
+ | standard input (stdin) | technical noun | The input stream of a local process. |
74
+ | standard output (stdout) | technical noun | The normal output stream of a local process. |
75
+ | standard error (stderr) | technical noun | The error output stream of a local process. |
76
+ | token | technical noun | A model input or output unit. |
77
+ | budget | technical noun | A caller limit for tasks or estimated input tokens. |
78
+ | provider | technical noun | A company or service that supplies a model or harness. |
79
+ | subscription | technical noun | A provider plan that can set access or usage limits. |
80
+ | quota | technical noun | A provider limit on available usage. |
81
+ | estimated time of arrival (ETA) | technical noun | An estimate of the time until a task ends. |
82
+ | Cross-Origin Resource Sharing (CORS) | technical noun | An HTTP mechanism that controls browser access from another origin. |
83
+ | bring your own key (BYOK) | technical noun | An app pattern that uses credentials supplied by the user. |
84
+ | Codex | product name | The OpenAI coding-agent product. |
85
+ | Claude Code | product name | The Anthropic coding-agent product. |
86
+ | Antigravity | product name | The Google coding-agent CLI used by Ennodia. |
87
+ | Gemini | product name | A Google model family. |
88
+ | GPT | product name | An OpenAI model family. |
89
+ | OpenCode | product name | A supported coding-agent CLI. |
90
+ | Kilo Code | product name | A supported coding-agent CLI. |
91
+ | Hermes Agent | product name | A supported coding-agent CLI. |
92
+ | Kiro CLI | product name | A supported coding-agent CLI. |
93
+ | Cline | product name | A supported coding-agent CLI. |
94
+ | AutoGen | product name | An external multi-agent framework. |
95
+ | ChatHub | product name | An external multi-model comparison product. |
96
+ | LangGraph | product name | An external agent workflow framework. |
97
+ | OpenRouter | product name | An external model routing service. |
98
+ | Mixture-of-Agents | technical noun | An external multi-model inference method. |
99
+ | model merging | technical noun | A method that combines model parameters. |
100
+ | fine-tuning | technical noun | A method that adapts a model with additional training. |
101
+ | mergekit | product name | An external toolkit for model merging. |
102
+ | npm | product name | The package registry and command-line tool for JavaScript packages. |
103
+ | JavaScript Registry (JSR) | product name | The registry that distributes the Ennodia JavaScript package. |
104
+ | Model Context Protocol Registry | product name | The official registry for MCP server metadata. |
105
+ | GitHub Actions | product name | The service that runs Ennodia release and deployment workflows. |
106
+ | Cloudflare Pages | product name | The service that hosts the Ennodia website. |
107
+ | Astro | product name | The framework that builds the Ennodia website. |
108
+ | Starlight | product name | The Astro documentation framework used by the Ennodia website. |
109
+ | Semantic Versioning (SemVer) | technical noun | The version format that identifies compatible and incompatible releases. |
110
+ | JSON Lines | technical noun | A text format that stores one JSON value on each line. |
111
+ | JavaScript Object Notation (JSON) | technical noun | A structured text format for data exchange. |
112
+ | YAML | technical noun | A structured text format that Ennodia uses for Agent Skill metadata. |
113
+ | OpenID Connect (OIDC) | technical noun | The identity protocol used for tokenless registry publication from GitHub Actions. |
114
+ | identifier (ID) | technical noun | A value that uniquely identifies an Ennodia object. |
115
+ | F1 score | technical noun | The harmonic mean of precision and recall in a benchmark. |
116
+ | false positive (FP) | technical noun | A reported finding that the benchmark oracle does not require. |
117
+ | TypeScript | product name | The typed programming language used by Ennodia. |
118
+ | benchmark | technical noun or verb | A repeatable quality test, or the action that runs that test. |
119
+
120
+ Use `Plan Advisor` and `Result Advisor` in full.
121
+ Do not use `Advisor` alone when the role can be unclear.
122
+
123
+ Legacy fields can contain `synthesizer` or `synthesis` in their exact names.
124
+ Use `Result Advisor` for the current public role.
125
+
126
+ ## Source
127
+
128
+ Use the official [ASD-STE100 Issue 9 standard](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf).
129
+ The ASD Simplified Technical English Maintenance Group controls that standard.
130
+ Do not copy its dictionary into this repository.