@moreih29/nexus-core 0.12.0 → 0.14.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 (245) hide show
  1. package/README.md +76 -57
  2. package/assets/agents/architect/body.ko.md +177 -0
  3. package/{agents → assets/agents}/architect/body.md +16 -0
  4. package/assets/agents/designer/body.ko.md +125 -0
  5. package/{agents → assets/agents}/designer/body.md +16 -0
  6. package/assets/agents/engineer/body.ko.md +106 -0
  7. package/{agents → assets/agents}/engineer/body.md +14 -0
  8. package/assets/agents/lead/body.ko.md +70 -0
  9. package/assets/agents/lead/body.md +70 -0
  10. package/assets/agents/postdoc/body.ko.md +122 -0
  11. package/{agents → assets/agents}/postdoc/body.md +16 -0
  12. package/assets/agents/researcher/body.ko.md +137 -0
  13. package/{agents → assets/agents}/researcher/body.md +15 -0
  14. package/assets/agents/reviewer/body.ko.md +138 -0
  15. package/{agents → assets/agents}/reviewer/body.md +15 -0
  16. package/assets/agents/strategist/body.ko.md +116 -0
  17. package/{agents → assets/agents}/strategist/body.md +16 -0
  18. package/assets/agents/tester/body.ko.md +195 -0
  19. package/{agents → assets/agents}/tester/body.md +15 -0
  20. package/assets/agents/writer/body.ko.md +122 -0
  21. package/{agents → assets/agents}/writer/body.md +14 -0
  22. package/assets/capability-matrix.yml +198 -0
  23. package/assets/hooks/agent-bootstrap/handler.test.ts +368 -0
  24. package/assets/hooks/agent-bootstrap/handler.ts +119 -0
  25. package/assets/hooks/agent-bootstrap/meta.yml +10 -0
  26. package/assets/hooks/agent-finalize/handler.test.ts +368 -0
  27. package/assets/hooks/agent-finalize/handler.ts +76 -0
  28. package/assets/hooks/agent-finalize/meta.yml +10 -0
  29. package/assets/hooks/capability-matrix.yml +313 -0
  30. package/assets/hooks/post-tool-telemetry/handler.test.ts +302 -0
  31. package/assets/hooks/post-tool-telemetry/handler.ts +49 -0
  32. package/assets/hooks/post-tool-telemetry/meta.yml +11 -0
  33. package/assets/hooks/prompt-router/handler.test.ts +801 -0
  34. package/assets/hooks/prompt-router/handler.ts +261 -0
  35. package/assets/hooks/prompt-router/meta.yml +11 -0
  36. package/assets/hooks/session-init/handler.test.ts +274 -0
  37. package/assets/hooks/session-init/handler.ts +30 -0
  38. package/assets/hooks/session-init/meta.yml +9 -0
  39. package/assets/lsp-servers.json +55 -0
  40. package/assets/schema/lsp-servers.schema.json +67 -0
  41. package/assets/skills/nx-init/body.ko.md +197 -0
  42. package/{skills → assets/skills}/nx-init/body.md +11 -0
  43. package/assets/skills/nx-plan/body.ko.md +361 -0
  44. package/{skills → assets/skills}/nx-plan/body.md +13 -0
  45. package/assets/skills/nx-run/body.ko.md +161 -0
  46. package/{skills → assets/skills}/nx-run/body.md +11 -0
  47. package/assets/skills/nx-sync/body.ko.md +92 -0
  48. package/{skills → assets/skills}/nx-sync/body.md +10 -0
  49. package/assets/tools/tool-name-map.yml +353 -0
  50. package/dist/assets/hooks/agent-bootstrap/handler.d.ts +4 -0
  51. package/dist/assets/hooks/agent-bootstrap/handler.d.ts.map +1 -0
  52. package/dist/assets/hooks/agent-bootstrap/handler.js +100 -0
  53. package/dist/assets/hooks/agent-bootstrap/handler.js.map +1 -0
  54. package/dist/assets/hooks/agent-finalize/handler.d.ts +4 -0
  55. package/dist/assets/hooks/agent-finalize/handler.d.ts.map +1 -0
  56. package/dist/assets/hooks/agent-finalize/handler.js +63 -0
  57. package/dist/assets/hooks/agent-finalize/handler.js.map +1 -0
  58. package/dist/assets/hooks/post-tool-telemetry/handler.d.ts +4 -0
  59. package/dist/assets/hooks/post-tool-telemetry/handler.d.ts.map +1 -0
  60. package/dist/assets/hooks/post-tool-telemetry/handler.js +40 -0
  61. package/dist/assets/hooks/post-tool-telemetry/handler.js.map +1 -0
  62. package/dist/assets/hooks/prompt-router/handler.d.ts +4 -0
  63. package/dist/assets/hooks/prompt-router/handler.d.ts.map +1 -0
  64. package/dist/assets/hooks/prompt-router/handler.js +204 -0
  65. package/dist/assets/hooks/prompt-router/handler.js.map +1 -0
  66. package/dist/assets/hooks/session-init/handler.d.ts +4 -0
  67. package/dist/assets/hooks/session-init/handler.d.ts.map +1 -0
  68. package/dist/assets/hooks/session-init/handler.js +23 -0
  69. package/dist/assets/hooks/session-init/handler.js.map +1 -0
  70. package/dist/hooks/agent-bootstrap.js +105 -0
  71. package/dist/hooks/agent-finalize.js +164 -0
  72. package/dist/hooks/post-tool-telemetry.js +55 -0
  73. package/dist/hooks/prompt-router.js +7300 -0
  74. package/dist/hooks/session-init.js +21 -0
  75. package/dist/manifests/claude-hooks.json +52 -0
  76. package/dist/manifests/codex-hooks.json +28 -0
  77. package/dist/manifests/opencode-manifest.json +44 -0
  78. package/dist/manifests/portability-report.json +87 -0
  79. package/dist/scripts/build-agents.d.ts +157 -0
  80. package/dist/scripts/build-agents.d.ts.map +1 -0
  81. package/dist/scripts/build-agents.js +737 -0
  82. package/dist/scripts/build-agents.js.map +1 -0
  83. package/dist/scripts/build-hooks.d.ts +16 -0
  84. package/dist/scripts/build-hooks.d.ts.map +1 -0
  85. package/dist/scripts/build-hooks.js +388 -0
  86. package/dist/scripts/build-hooks.js.map +1 -0
  87. package/dist/scripts/cli.d.ts +54 -0
  88. package/dist/scripts/cli.d.ts.map +1 -0
  89. package/dist/scripts/cli.js +467 -0
  90. package/dist/scripts/cli.js.map +1 -0
  91. package/dist/src/hooks/opencode-mount.d.ts +35 -0
  92. package/dist/src/hooks/opencode-mount.d.ts.map +1 -0
  93. package/dist/src/hooks/opencode-mount.js +352 -0
  94. package/dist/src/hooks/opencode-mount.js.map +1 -0
  95. package/dist/src/hooks/runtime.d.ts +37 -0
  96. package/dist/src/hooks/runtime.d.ts.map +1 -0
  97. package/dist/src/hooks/runtime.js +274 -0
  98. package/dist/src/hooks/runtime.js.map +1 -0
  99. package/dist/src/hooks/types.d.ts +196 -0
  100. package/dist/src/hooks/types.d.ts.map +1 -0
  101. package/dist/src/hooks/types.js +85 -0
  102. package/dist/src/hooks/types.js.map +1 -0
  103. package/dist/src/lsp/cache.d.ts +9 -0
  104. package/dist/src/lsp/cache.d.ts.map +1 -0
  105. package/dist/src/lsp/cache.js +216 -0
  106. package/dist/src/lsp/cache.js.map +1 -0
  107. package/dist/src/lsp/client.d.ts +24 -0
  108. package/dist/src/lsp/client.d.ts.map +1 -0
  109. package/dist/src/lsp/client.js +166 -0
  110. package/dist/src/lsp/client.js.map +1 -0
  111. package/dist/src/lsp/detect.d.ts +77 -0
  112. package/dist/src/lsp/detect.d.ts.map +1 -0
  113. package/dist/src/lsp/detect.js +116 -0
  114. package/dist/src/lsp/detect.js.map +1 -0
  115. package/dist/src/mcp/server.d.ts +5 -0
  116. package/dist/src/mcp/server.d.ts.map +1 -0
  117. package/dist/src/mcp/server.js +34 -0
  118. package/dist/src/mcp/server.js.map +1 -0
  119. package/dist/src/mcp/tools/artifact.d.ts +4 -0
  120. package/dist/src/mcp/tools/artifact.d.ts.map +1 -0
  121. package/dist/src/mcp/tools/artifact.js +36 -0
  122. package/dist/src/mcp/tools/artifact.js.map +1 -0
  123. package/dist/src/mcp/tools/history.d.ts +3 -0
  124. package/dist/src/mcp/tools/history.d.ts.map +1 -0
  125. package/dist/src/mcp/tools/history.js +29 -0
  126. package/dist/src/mcp/tools/history.js.map +1 -0
  127. package/dist/src/mcp/tools/lsp.d.ts +13 -0
  128. package/dist/src/mcp/tools/lsp.d.ts.map +1 -0
  129. package/dist/src/mcp/tools/lsp.js +225 -0
  130. package/dist/src/mcp/tools/lsp.js.map +1 -0
  131. package/dist/src/mcp/tools/plan.d.ts +3 -0
  132. package/dist/src/mcp/tools/plan.d.ts.map +1 -0
  133. package/dist/src/mcp/tools/plan.js +317 -0
  134. package/dist/src/mcp/tools/plan.js.map +1 -0
  135. package/dist/src/mcp/tools/task.d.ts +3 -0
  136. package/dist/src/mcp/tools/task.d.ts.map +1 -0
  137. package/dist/src/mcp/tools/task.js +252 -0
  138. package/dist/src/mcp/tools/task.js.map +1 -0
  139. package/dist/src/shared/invocations.d.ts +74 -0
  140. package/dist/src/shared/invocations.d.ts.map +1 -0
  141. package/dist/src/shared/invocations.js +247 -0
  142. package/dist/src/shared/invocations.js.map +1 -0
  143. package/dist/src/shared/json-store.d.ts +37 -0
  144. package/dist/src/shared/json-store.d.ts.map +1 -0
  145. package/dist/src/shared/json-store.js +163 -0
  146. package/dist/src/shared/json-store.js.map +1 -0
  147. package/dist/src/shared/mcp-utils.d.ts +3 -0
  148. package/dist/src/shared/mcp-utils.d.ts.map +1 -0
  149. package/dist/src/shared/mcp-utils.js +6 -0
  150. package/dist/src/shared/mcp-utils.js.map +1 -0
  151. package/dist/src/shared/paths.d.ts +21 -0
  152. package/dist/src/shared/paths.d.ts.map +1 -0
  153. package/dist/src/shared/paths.js +81 -0
  154. package/dist/src/shared/paths.js.map +1 -0
  155. package/dist/src/shared/tool-log.d.ts +8 -0
  156. package/dist/src/shared/tool-log.d.ts.map +1 -0
  157. package/dist/src/shared/tool-log.js +22 -0
  158. package/dist/src/shared/tool-log.js.map +1 -0
  159. package/dist/src/types/state.d.ts +862 -0
  160. package/dist/src/types/state.d.ts.map +1 -0
  161. package/dist/src/types/state.js +66 -0
  162. package/dist/src/types/state.js.map +1 -0
  163. package/docs/consuming/codex-lead-merge.md +106 -0
  164. package/docs/plugin-guide.md +396 -0
  165. package/docs/plugin-template/claude/.github/workflows/build.yml +60 -0
  166. package/docs/plugin-template/claude/README.md +110 -0
  167. package/docs/plugin-template/claude/package.json +16 -0
  168. package/docs/plugin-template/codex/.github/workflows/build.yml +51 -0
  169. package/docs/plugin-template/codex/README.md +147 -0
  170. package/docs/plugin-template/codex/package.json +17 -0
  171. package/docs/plugin-template/opencode/.github/workflows/build.yml +61 -0
  172. package/docs/plugin-template/opencode/README.md +121 -0
  173. package/docs/plugin-template/opencode/package.json +25 -0
  174. package/package.json +36 -28
  175. package/agents/architect/meta.yml +0 -13
  176. package/agents/designer/meta.yml +0 -13
  177. package/agents/engineer/meta.yml +0 -11
  178. package/agents/postdoc/meta.yml +0 -13
  179. package/agents/researcher/meta.yml +0 -12
  180. package/agents/reviewer/meta.yml +0 -12
  181. package/agents/strategist/meta.yml +0 -13
  182. package/agents/tester/meta.yml +0 -12
  183. package/agents/writer/meta.yml +0 -11
  184. package/conformance/README.md +0 -311
  185. package/conformance/examples/plan.extension.schema.example.json +0 -25
  186. package/conformance/lifecycle/README.md +0 -48
  187. package/conformance/lifecycle/agent-complete.json +0 -44
  188. package/conformance/lifecycle/agent-resume.json +0 -43
  189. package/conformance/lifecycle/agent-spawn.json +0 -36
  190. package/conformance/lifecycle/memory-access-record.json +0 -27
  191. package/conformance/lifecycle/session-end.json +0 -48
  192. package/conformance/scenarios/full-plan-cycle.json +0 -147
  193. package/conformance/scenarios/task-deps-ordering.json +0 -95
  194. package/conformance/schema/fixture.schema.json +0 -354
  195. package/conformance/state-schemas/agent-tracker.schema.json +0 -63
  196. package/conformance/state-schemas/history.schema.json +0 -134
  197. package/conformance/state-schemas/memory-access.schema.json +0 -36
  198. package/conformance/state-schemas/plan.schema.json +0 -77
  199. package/conformance/state-schemas/tasks.schema.json +0 -98
  200. package/conformance/tools/artifact-write.json +0 -97
  201. package/conformance/tools/context.json +0 -172
  202. package/conformance/tools/history-search.json +0 -219
  203. package/conformance/tools/plan-decide.json +0 -139
  204. package/conformance/tools/plan-start.json +0 -81
  205. package/conformance/tools/plan-status.json +0 -127
  206. package/conformance/tools/plan-update.json +0 -341
  207. package/conformance/tools/task-add.json +0 -156
  208. package/conformance/tools/task-close.json +0 -161
  209. package/conformance/tools/task-list.json +0 -177
  210. package/conformance/tools/task-update.json +0 -167
  211. package/docs/behavioral-contracts.md +0 -145
  212. package/docs/consumer-implementation-guide.md +0 -840
  213. package/docs/memory-lifecycle-contract.md +0 -119
  214. package/docs/nexus-layout.md +0 -224
  215. package/docs/nexus-outputs-contract.md +0 -344
  216. package/docs/nexus-state-overview.md +0 -170
  217. package/docs/nexus-tools-contract.md +0 -438
  218. package/manifest.json +0 -448
  219. package/schema/README.md +0 -69
  220. package/schema/agent.schema.json +0 -23
  221. package/schema/common.schema.json +0 -17
  222. package/schema/manifest.schema.json +0 -78
  223. package/schema/memory-policy.schema.json +0 -98
  224. package/schema/skill.schema.json +0 -54
  225. package/schema/task-exceptions.schema.json +0 -40
  226. package/schema/vocabulary.schema.json +0 -167
  227. package/scripts/.gitkeep +0 -0
  228. package/scripts/conformance-coverage.ts +0 -466
  229. package/scripts/import-from-claude-nexus.ts +0 -403
  230. package/scripts/lib/frontmatter.ts +0 -71
  231. package/scripts/lib/lint.ts +0 -348
  232. package/scripts/lib/structure.ts +0 -159
  233. package/scripts/lib/validate.ts +0 -796
  234. package/scripts/validate.ts +0 -90
  235. package/skills/nx-init/meta.yml +0 -8
  236. package/skills/nx-plan/meta.yml +0 -10
  237. package/skills/nx-run/meta.yml +0 -8
  238. package/skills/nx-sync/meta.yml +0 -7
  239. package/vocabulary/capabilities.yml +0 -65
  240. package/vocabulary/categories.yml +0 -11
  241. package/vocabulary/invocations.yml +0 -147
  242. package/vocabulary/memory_policy.yml +0 -88
  243. package/vocabulary/resume-tiers.yml +0 -11
  244. package/vocabulary/tags.yml +0 -60
  245. package/vocabulary/task-exceptions.yml +0 -29
@@ -1,11 +0,0 @@
1
- name: engineer
2
- description: Implementation — writes code, debugs issues, follows specifications
3
- from Lead and architect
4
- task: Code implementation, edits, debugging
5
- alias_ko: 엔지니어
6
- category: do
7
- resume_tier: bounded
8
- model_tier: standard
9
- capabilities:
10
- - no_task_create
11
- id: engineer
@@ -1,13 +0,0 @@
1
- name: postdoc
2
- description: Research methodology and synthesis — designs investigation
3
- approach, evaluates evidence quality, writes synthesis documents
4
- task: Research methodology, evidence synthesis
5
- alias_ko: 포닥
6
- category: how
7
- resume_tier: persistent
8
- model_tier: high
9
- capabilities:
10
- - no_file_edit
11
- - no_task_create
12
- - no_task_update
13
- id: postdoc
@@ -1,12 +0,0 @@
1
- name: researcher
2
- description: Independent investigation — conducts web searches, gathers
3
- evidence, and reports findings with citations
4
- task: Web search, independent investigation
5
- alias_ko: 리서처
6
- category: do
7
- resume_tier: persistent
8
- model_tier: standard
9
- capabilities:
10
- - no_file_edit
11
- - no_task_create
12
- id: researcher
@@ -1,12 +0,0 @@
1
- name: reviewer
2
- description: Content verification — validates accuracy, checks facts, confirms
3
- grammar and format of non-code deliverables
4
- task: Content verification, fact-checking, grammar review
5
- alias_ko: 리뷰어
6
- category: check
7
- resume_tier: ephemeral
8
- model_tier: standard
9
- capabilities:
10
- - no_file_edit
11
- - no_task_create
12
- id: reviewer
@@ -1,13 +0,0 @@
1
- name: strategist
2
- description: Business strategy — evaluates market positioning, competitive
3
- landscape, and business viability of decisions
4
- task: Business strategy, market analysis, competitive positioning
5
- alias_ko: 전략가
6
- category: how
7
- resume_tier: persistent
8
- model_tier: high
9
- capabilities:
10
- - no_file_edit
11
- - no_task_create
12
- - no_task_update
13
- id: strategist
@@ -1,12 +0,0 @@
1
- name: tester
2
- description: Testing and verification — tests, verifies, validates stability and
3
- security of implementations
4
- task: Testing, verification, security review
5
- alias_ko: 테스터
6
- category: check
7
- resume_tier: ephemeral
8
- model_tier: standard
9
- capabilities:
10
- - no_file_edit
11
- - no_task_create
12
- id: tester
@@ -1,11 +0,0 @@
1
- name: writer
2
- description: Technical writing — transforms research findings, code, and
3
- analysis into clear documents and presentations for the intended audience
4
- task: Technical writing, documentation, presentations
5
- alias_ko: 라이터
6
- category: do
7
- resume_tier: bounded
8
- model_tier: standard
9
- capabilities:
10
- - no_task_create
11
- id: writer
@@ -1,311 +0,0 @@
1
- # Nexus Conformance Fixtures
2
-
3
- Declarative behavioral tests for Nexus MCP tools. Each fixture describes a tool invocation (or sequence of invocations) and the state assertions that must hold afterwards. Fixtures are harness-neutral: they use abstract tool names and JSONPath assertions, so any consumer can write a runner against their own harness implementation.
4
-
5
- ## What conformance fixtures are
6
-
7
- A conformance fixture is a JSON document that specifies:
8
-
9
- 1. **Precondition** — the state files that must exist (or must not exist) before the test runs.
10
- 2. **Action** (or **Steps** or **Event**) — one or more tool invocations, or a single lifecycle event, with concrete parameters.
11
- 3. **Postcondition** — assertions on the tool return value and on state files after the invocation.
12
- 4. **Covers** — a declaration of which state-schema fields and return-value paths this fixture verifies.
13
-
14
- Fixtures do not contain any test runner code. Consumers load the JSON, reconstruct precondition state, call their own tool implementation, and verify the postconditions.
15
-
16
- ## Fixture format
17
-
18
- All fixtures must validate against [`schema/fixture.schema.json`](schema/fixture.schema.json).
19
-
20
- Every fixture must include a top-level `covers` field (required). An optional `uncovered_params` field may also appear.
21
-
22
- ### `covers` field
23
-
24
- `covers` declares which schema fields and return-value paths this fixture's postcondition actually verifies. The coverage validator uses this declaration to track completeness across the fixture suite.
25
-
26
- ```json
27
- "covers": {
28
- "state_schemas": {
29
- "plan.schema.json": ["id", "topic", "issues[].status"]
30
- },
31
- "return_value": {
32
- "plan_start": ["created", "plan_id", "issueCount"]
33
- },
34
- "description": "Verifies plan creation fields and initial issue status."
35
- }
36
- ```
37
-
38
- **Constraint**: at least one of `state_schemas` or `return_value` must be non-empty. Both may be present.
39
-
40
- - `state_schemas` — map of state-schema filename (e.g. `plan.schema.json`) to an array of field paths verified by this fixture's postcondition. Field paths use dot-notation with array index notation (e.g. `issues[].status`).
41
- - `return_value` — map of abstract tool name (e.g. `plan_start`) to an array of return-value field paths verified by this fixture's postcondition.
42
- - `description` — optional human-readable explanation of coverage rationale or known gaps.
43
-
44
- ### `uncovered_params` field
45
-
46
- `uncovered_params` is an optional array of `action.params` keys that are intentionally not asserted in the postcondition. Entries listed here are treated as explicit exceptions by the coverage validator, preventing false anti-pattern warnings.
47
-
48
- Use this field for routing or contextual input params whose effect is not directly observable via state-file or return-value assertions:
49
-
50
- ```json
51
- "uncovered_params": ["research_summary"]
52
- ```
53
-
54
- ### Schema `oneOf` constraint
55
-
56
- Each fixture must contain exactly one of: `action` (single tool invocation), `event` (single lifecycle event), or `steps` (multi-step sequence). These three branches are mutually exclusive.
57
-
58
- ### Single-action fixture
59
-
60
- ```json
61
- {
62
- "test_id": "plan_start_happy_path",
63
- "description": "...",
64
- "covers": {
65
- "state_schemas": { "plan.schema.json": ["id", "topic", "issues[].status"] },
66
- "return_value": { "plan_start": ["created", "plan_id", "issueCount"] }
67
- },
68
- "precondition": {
69
- "state_files": {
70
- ".nexus/state/plan.json": null
71
- }
72
- },
73
- "action": {
74
- "tool": "plan_start",
75
- "params": { "topic": "...", "issues": ["..."], "research_summary": "..." }
76
- },
77
- "postcondition": {
78
- "return_value": { "$.created": true },
79
- "state_files": {
80
- ".nexus/state/plan.json": { "$.topic": "..." }
81
- }
82
- }
83
- }
84
- ```
85
-
86
- ### Multi-step scenario
87
-
88
- ```json
89
- {
90
- "test_id": "full_plan_cycle",
91
- "description": "...",
92
- "covers": {
93
- "state_schemas": { "plan.schema.json": ["id", "topic", "issues[].status"] }
94
- },
95
- "steps": [
96
- {
97
- "description": "...",
98
- "action": { "tool": "plan_start", "params": { ... } },
99
- "assert_return": { "$.created": true },
100
- "assert_state": { ".nexus/state/plan.json": { "$.issues.length": 2 } }
101
- }
102
- ]
103
- }
104
- ```
105
-
106
- ## Event-based (Lifecycle) Fixtures
107
-
108
- `agent-tracker.json`은 MCP tool이 아니라 harness의 session hook이 관리한다. 이 파일의 구조적 정확성을 검증하기 위해 `action` 대신 `event` 필드를 사용하는 lifecycle fixture를 사용한다.
109
-
110
- Event fixture는 "harness가 특정 event를 실행한 후 state 파일의 구조가 올바른가"를 선언적으로 명세한다. Tool invocation 없이 event 트리거만으로 postcondition을 검증한다.
111
-
112
- ### Event types
113
-
114
- `event.type`은 다음 3종 중 하나여야 한다:
115
-
116
- | Event type | 책임 범위 |
117
- |---|---|
118
- | `agent_spawn` | `agent-tracker.json`에 신규 항목 생성 (running 상태) |
119
- | `agent_complete` | `agent-tracker.json` 항목을 완료 상태로 전환 |
120
- | `agent_resume` | `agent-tracker.json` 재개 카운터 증가 및 상태 복귀 |
121
-
122
- ### Lifecycle fixture 구조 예시
123
-
124
- ```json
125
- {
126
- "test_id": "agent_spawn_creates_entry",
127
- "description": "...",
128
- "covers": {
129
- "state_schemas": {
130
- "agent-tracker.schema.json": ["harness_id", "agent_name", "agent_id", "status"]
131
- }
132
- },
133
- "event": {
134
- "type": "agent_spawn",
135
- "params": { ... }
136
- },
137
- "postcondition": {
138
- "state_files": {
139
- "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": { "$[0].status": "running" }
140
- }
141
- }
142
- }
143
- ```
144
-
145
- ### Lifecycle fixture 목록
146
-
147
- `conformance/lifecycle/` 디렉토리에 3개 파일이 존재한다:
148
-
149
- | 파일 | Event type | 검증 대상 |
150
- |---|---|---|
151
- | `agent-spawn.json` | `agent_spawn` | `agent-tracker.json` 첫 항목 생성 (running 상태) |
152
- | `agent-complete.json` | `agent_complete` | `agent-tracker.json` 항목 완료 상태 전환 |
153
- | `agent-resume.json` | `agent_resume` | `agent-tracker.json` 재개 카운터 및 상태 복귀 |
154
-
155
- ## Assertion conventions
156
-
157
- Assertions are key/value objects where keys are JSONPath expressions and values are expected results or matchers.
158
-
159
- | Pattern | Meaning |
160
- |---|---|
161
- | `"$.field": "expected"` | Exact string match |
162
- | `"$.field": 42` | Exact number match |
163
- | `"$.field": true` | Boolean match |
164
- | `"$.array.length": 3` | Array length check |
165
- | `"$.field": { "type": "iso8601" }` | Value is a valid ISO 8601 timestamp |
166
- | `"$.field": { "type": "number", "min": 1 }` | Numeric value >= 1 |
167
- | `"$.field": { "type": "string", "minLength": 5 }` | String with minimum length |
168
- | `".nexus/state/plan.json": null` | File must not exist |
169
- | `".nexus/state/artifacts/findings.md": {}` | File must exist; content not inspected (use for non-JSON artifacts like .md, .txt, binary files) |
170
- | `"{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json"` | State file path with substitutable tokens. Test runner MUST substitute `{STATE_ROOT}` with `.nexus/state` and `{HARNESS_ID}` with the harness identifier (from `event.params.harness_id` or runner configuration) before applying assertions. Only `{STATE_ROOT}` and `{HARNESS_ID}` are recognized; arbitrary tokens are forbidden. |
171
-
172
- For `state_files`, a `null` value at the file path key means the file must be absent. A `null` value at a JSONPath key within a file assertion means that field must be `null`.
173
-
174
- ## Authoring Rules
175
-
176
- Fixtures must satisfy the following rules. The coverage validator enforces Rules 1–3 at CI time.
177
-
178
- **Rule 1 — Coverage**: 모든 state-schema 필드(required + optional)는 최소 1개 fixture의 `covers.state_schemas`에 등장해야 한다. 단 한 필드라도 누락되면 validator가 실패한다.
179
-
180
- **Rule 2 — No Silent Drop**: `action.params`의 모든 key는 `postcondition`(state_files 또는 return_value)에서 assert되거나 `uncovered_params`에 명시되어야 한다. 두 조건 모두 충족하지 않는 param key는 anti-pattern으로 보고된다.
181
-
182
- **Rule 3 — CI Gate**: fixture 추가 또는 수정 시 `validate:conformance` validator 통과가 release block이다. 실패 상태로 merge할 수 없다.
183
-
184
- **Rule 4 — Truthful Covers**: `covers`는 실제로 postcondition에서 assert하는 필드만 나열해야 한다. 허위 claim 금지. validator는 covers 선언과 실제 assertion 간 교차 검증을 수행하지 않지만, review 시 수동 검증 대상이다.
185
-
186
- ## Running the Coverage Validator
187
-
188
- `conformance-coverage.ts`는 두 가지를 검증한다:
189
-
190
- 1. **Schema field coverage** — `conformance/state-schemas/`의 모든 schema 파일에서 추출한 필드가 전체 fixture의 `covers.state_schemas` union에 포함되는지 확인한다.
191
- 2. **Params anti-pattern** — single-action fixture의 `action.params` key가 `postcondition` assertion 또는 `uncovered_params`에 트레이스 가능한지 확인한다.
192
-
193
- ### 실행 명령
194
-
195
- ```
196
- bun run validate:conformance
197
- ```
198
-
199
- 또는 직접 실행:
200
-
201
- ```
202
- bun run scripts/conformance-coverage.ts
203
- ```
204
-
205
- ### 출력 해석
206
-
207
- **PASS** (exit code 0):
208
-
209
- ```
210
- ✓ All state-schema fields covered: 5 schemas, 54 fields across 48 fixtures
211
- ```
212
-
213
- **FAIL — schema field coverage 미달** (exit code 1):
214
-
215
- ```
216
- ✗ Schema field coverage incomplete:
217
- plan.schema.json: missing fields [issues[].how_agents]
218
- ```
219
-
220
- **FAIL — params anti-pattern 감지** (exit code 1):
221
-
222
- ```
223
- ✗ Params anti-pattern detected (params not verified in postcondition):
224
- conformance/tools/plan-start.json (plan_start_happy_path): uncovered params [research_summary]
225
- ```
226
-
227
- exit code 2는 파일 파싱 등 fatal error를 의미한다.
228
-
229
- ## Writing a test runner
230
-
231
- A conformance test runner does the following for each fixture:
232
-
233
- 1. **Load** the fixture JSON file.
234
- 2. **Establish precondition**: for each entry in `precondition.state_files`, write the content object as JSON to the specified path, or delete the file if the value is `null`. Before resolving any path, substitute placeholder tokens: replace `{STATE_ROOT}` with `.nexus/state` and `{HARNESS_ID}` with the harness identifier found in `event.params.harness_id` (for lifecycle fixtures) or runner configuration (for general fixtures). Only `{STATE_ROOT}` and `{HARNESS_ID}` are recognized tokens; treat any other `{…}` token in a path as an authoring error.
235
- 3. **Execute**:
236
- - For single-action fixtures: call the tool named by `action.tool` with `action.params`.
237
- - For event fixtures: trigger the harness session hook for the event type specified by `event.type`, passing `event.params`.
238
- - For multi-step scenarios: iterate `steps` in order, calling each `action` (or triggering each `event`) and evaluating `assert_return` and `assert_state` after each step before proceeding.
239
- 4. **Evaluate postconditions**:
240
- - Check `postcondition.return_value` assertions against the tool's return value.
241
- - Check `postcondition.state_files` assertions against the actual file system state. Apply the same `{STATE_ROOT}` / `{HARNESS_ID}` substitution to path keys before resolving (same rule as precondition). For each entry in `state_files`:
242
- - Value is `null` → assert the file does NOT exist.
243
- - Value is an empty object `{}` → assert the file EXISTS; do NOT parse content (use for non-JSON artifacts: .md, .txt, binary).
244
- - Value is a non-empty object `{...}` → parse file as JSON and evaluate each JSONPath assertion against the parsed content.
245
- - If `postcondition.error` is `true`, the tool call must have produced an error.
246
- - If `postcondition.error_contains` is set, the error message must contain that substring.
247
- 5. **Report** pass/fail per `test_id`.
248
-
249
- Example runner sketch (TypeScript):
250
-
251
- ```typescript
252
- import fixtures from "./tools/plan-start.json";
253
-
254
- for (const fixture of fixtures) {
255
- applyPrecondition(fixture.precondition);
256
- const result = await callTool(fixture.action.tool, fixture.action.params);
257
- assertPostcondition(fixture.postcondition, result);
258
- }
259
- ```
260
-
261
- ## Coverage
262
-
263
- ### Abstract tools (11/11 커버됨)
264
-
265
- 11개 abstract tool 모두 전용 fixture 파일을 갖는다. 각 fixture는 tool의 happy path, error path, optional 파라미터 경로를 포함한다.
266
-
267
- | Abstract name | Description | Fixture file |
268
- |---|---|---|
269
- | `plan_start` | Start a new plan session | `tools/plan-start.json` |
270
- | `plan_decide` | Record a decision on a plan issue | `tools/plan-decide.json` |
271
- | `plan_status` | Query the current plan state | `tools/plan-status.json` |
272
- | `plan_update` | Add, remove, edit, or reopen plan issues | `tools/plan-update.json` |
273
- | `task_add` | Add a task to the task list | `tools/task-add.json` |
274
- | `task_update` | Update a task's status | `tools/task-update.json` |
275
- | `task_list` | List tasks with dependency-aware ready set | `tools/task-list.json` |
276
- | `task_close` | Archive cycle into history and delete source files | `tools/task-close.json` |
277
- | `history_search` | Search past cycles in history.json | `tools/history-search.json` |
278
- | `context` | Read or write .nexus/context/ knowledge files | `tools/context.json` |
279
- | `artifact_write` | Write an artifact output file | `tools/artifact-write.json` |
280
-
281
- ### Lifecycle events (3/3 커버됨)
282
-
283
- | Event type | Fixture file |
284
- |---|---|
285
- | `agent_spawn` | `lifecycle/agent-spawn.json` |
286
- | `agent_complete` | `lifecycle/agent-complete.json` |
287
- | `agent_resume` | `lifecycle/agent-resume.json` |
288
-
289
- ### State-schema field coverage
290
-
291
- 4개 state-schema의 모든 필드가 100% 커버된다:
292
-
293
- | Schema | 검증 도구 |
294
- |---|---|
295
- | `plan.schema.json` | `tools/plan-*.json` fixtures |
296
- | `tasks.schema.json` | `tools/task-*.json` fixtures |
297
- | `history.schema.json` | `tools/history-search.json`, `tools/task-close.json` |
298
- | `agent-tracker.schema.json` | `lifecycle/agent-*.json` fixtures |
299
-
300
- Validator 통과 결과 예시: `✓ All state-schema fields covered: 4 schemas across fixture suite`
301
-
302
- ## Excluded tools
303
-
304
- AST and LSP tools (`ast_search`, `ast_replace`, `lsp_diagnostics`, `lsp_goto_definition`, etc.) are harness utilities that depend on language server infrastructure. They are not ecosystem contracts and are excluded from conformance coverage.
305
-
306
- ## 관련 문서
307
-
308
- - `docs/nexus-outputs-contract.md` — harness 산출물 계약 (artifact 경로, 파일 형식)
309
- - `docs/nexus-state-overview.md` — state file 기술 스펙 (schema 정의, 파일 위치)
310
- - `docs/nexus-tools-contract.md` — 11개 abstract tool 계약 (params, return value)
311
- - `CONSUMING.md §Conformance Obligation` — consumer가 준수해야 하는 conformance 의무
@@ -1,25 +0,0 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "conformance/examples/plan.extension.schema.example.json",
4
- "title": "Example: Harness-local plan state extension",
5
- "description": "Non-normative reference example of a harness-local extension schema for plan.json. Harnesses MAY add supplemental fields via {base}.extension.json files in .nexus/state/{harness-id}/. Consumers replace harness_specific_field_example with their own fields. See docs/nexus-outputs-contract.md §Harness-local State Extension for the pattern definition.",
6
- "type": "object",
7
- "additionalProperties": false,
8
- "required": ["extends"],
9
- "properties": {
10
- "extends": {
11
- "type": "string",
12
- "const": "conformance/state-schemas/plan.schema.json",
13
- "description": "Reference to the parent common-schema this extension supplements"
14
- },
15
- "harness_id": {
16
- "type": "string",
17
- "pattern": "^[a-z][a-z0-9-]*$",
18
- "description": "Identifier of the harness that produced this extension file"
19
- },
20
- "harness_specific_field_example": {
21
- "type": "string",
22
- "description": "Placeholder — replace with your harness's actual extension fields as needed"
23
- }
24
- }
25
- }
@@ -1,48 +0,0 @@
1
- # Lifecycle Fixtures
2
-
3
- 이 fixture들은 harness의 session hook이 event를 재현한 후의 state 파일을 검증한다.
4
-
5
- ## Event Types
6
-
7
- | Fixture | Event Type | 검증 대상 |
8
- |---|---|---|
9
- | `agent-spawn.json` | `agent_spawn` | `agent-tracker.json` 첫 항목 생성 (running 상태) |
10
- | `agent-complete.json` | `agent_complete` | `agent-tracker.json` 항목 완료 상태 전환 |
11
- | `agent-resume.json` | `agent_resume` | `agent-tracker.json` 재개 카운터 및 상태 복귀 |
12
- | `session-end.json` | `session_end` | `agent-tracker.json` 삭제, `history.json` · `memory/` · `context/` · `rules/` 보존 |
13
-
14
- ## Why session-end was re-added at v0.11.0
15
-
16
- v0.6.0에서 session-start/session-end fixture를 제거한 이유는 당시 구현이 `runtime.schema.json`에 의존했기 때문이다. `runtime.schema.json`은 execution semantics를 포함하므로 nexus-core의 prompt-only 원칙과 충돌했다. v0.11.0 재도입은 `runtime.schema.json`을 완전히 배제하고 `agent-tracker.schema.json`과 `history.schema.json`만 참조한다. session_end fixture가 검증하는 핵심 invariant는 두 가지다: (1) agent-tracker.json은 세션 종료 시 삭제된다(session-scoped), (2) history.json · memory/ · context/ · rules/는 삭제되어서는 안 된다(Negative MUST — cross-session knowledge 보존).
17
-
18
- ## Tool-action 대신 Event 트리거 사용
19
-
20
- 각 fixture는 `action` (tool invocation) 대신 `event` 필드를 사용한다. `agent-tracker.json`은 harness의 session hook이 관리하며, MCP tool이 직접 쓰지 않는다. Event fixture는 "harness가 event를 실행한 후 state 파일의 구조가 올바른가"를 선언적으로 명세한다.
21
-
22
- ## Placeholder token 경로
23
-
24
- 이 lifecycle fixture 3종의 `precondition.state_files` 및 `postcondition.state_files` 키는 모두 placeholder token 형식을 사용한다:
25
-
26
- ```
27
- {STATE_ROOT}/{HARNESS_ID}/agent-tracker.json
28
- ```
29
-
30
- Test runner는 이 키를 파일 시스템 경로로 해석하기 전에 다음 치환을 수행해야 한다:
31
-
32
- | Token | 치환 값 | 출처 |
33
- |---|---|---|
34
- | `{STATE_ROOT}` | `.nexus/state` | 고정 상수 |
35
- | `{HARNESS_ID}` | harness 식별자 (예: `claude-nexus`) | 해당 fixture의 `event.params.harness_id` |
36
-
37
- 치환 규약:
38
- - `{STATE_ROOT}`와 `{HARNESS_ID}` 두 token만 인식된다. 그 외 `{…}` 형태의 token이 경로에 등장하면 authoring 오류로 처리한다.
39
- - 공통 파일 fixture (`plan-*`, `task-*`, `history-*`, `artifact-write`)는 하드코딩된 경로를 사용하며 이 token 규약이 적용되지 않는다. Token 경로는 lifecycle fixture 4종(`agent-spawn`, `agent-complete`, `agent-resume`, `session-end`)의 `agent-tracker.json` 경로에만 적용된다.
40
-
41
- ### Fixture별 경로 요약
42
-
43
- | Fixture | `event.params.harness_id` 예시 | 해석된 경로 |
44
- |---|---|---|
45
- | `agent-spawn.json` | `claude-nexus` | `.nexus/state/claude-nexus/agent-tracker.json` |
46
- | `agent-complete.json` | `claude-nexus` | `.nexus/state/claude-nexus/agent-tracker.json` |
47
- | `agent-resume.json` | `claude-nexus` | `.nexus/state/claude-nexus/agent-tracker.json` |
48
- | `session-end.json` | `claude-nexus` | `.nexus/state/claude-nexus/agent-tracker.json` (null assertion — file must not exist after session end) |
@@ -1,44 +0,0 @@
1
- {
2
- "test_id": "agent_complete",
3
- "description": "Verifies that agent_complete transitions an agent to completed status and records stopped_at, last_message, and files_touched in agent-tracker.json",
4
- "precondition": {
5
- "state_files": {
6
- "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": [
7
- {
8
- "harness_id": "claude-nexus",
9
- "agent_name": "architect",
10
- "agent_id": "uuid-eng01",
11
- "started_at": "2026-04-13T00:00:00.000Z",
12
- "resume_count": 0,
13
- "status": "running"
14
- }
15
- ]
16
- }
17
- },
18
- "event": {
19
- "type": "agent_complete",
20
- "params": {
21
- "agent_id": "uuid-eng01",
22
- "last_message": "Implementation complete",
23
- "files_touched": ["src/foo.ts", "src/bar.ts"]
24
- },
25
- "description": "Harness records agent completion with output summary and list of modified files"
26
- },
27
- "postcondition": {
28
- "state_files": {
29
- "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": {
30
- "$.length": 1,
31
- "$[0].status": "completed",
32
- "$[0].stopped_at": { "type": "iso8601" },
33
- "$[0].last_message": "Implementation complete",
34
- "$[0].files_touched.length": 2,
35
- "$[0].files_touched[0]": "src/foo.ts"
36
- }
37
- }
38
- },
39
- "covers": {
40
- "state_schemas": {
41
- "agent-tracker.schema.json": ["status", "stopped_at", "last_message", "files_touched", "files_touched[]"]
42
- }
43
- }
44
- }
@@ -1,43 +0,0 @@
1
- {
2
- "test_id": "agent_resume",
3
- "description": "Verifies that agent_resume transitions a completed agent back to running status and increments resume_count and sets last_resumed_at",
4
- "precondition": {
5
- "state_files": {
6
- "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": [
7
- {
8
- "harness_id": "claude-nexus",
9
- "agent_name": "architect",
10
- "agent_id": "uuid-eng01",
11
- "started_at": "2026-04-13T00:00:00.000Z",
12
- "resume_count": 0,
13
- "status": "completed",
14
- "stopped_at": "2026-04-13T01:00:00.000Z",
15
- "last_message": "Implementation complete",
16
- "files_touched": ["src/foo.ts", "src/bar.ts"]
17
- }
18
- ]
19
- }
20
- },
21
- "event": {
22
- "type": "agent_resume",
23
- "params": {
24
- "agent_id": "uuid-eng01"
25
- },
26
- "description": "Harness resumes a previously completed agent, incrementing the resume counter and updating lifecycle timestamps"
27
- },
28
- "postcondition": {
29
- "state_files": {
30
- "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": {
31
- "$.length": 1,
32
- "$[0].status": "running",
33
- "$[0].resume_count": 1,
34
- "$[0].last_resumed_at": { "type": "iso8601" }
35
- }
36
- }
37
- },
38
- "covers": {
39
- "state_schemas": {
40
- "agent-tracker.schema.json": ["last_resumed_at", "resume_count", "status"]
41
- }
42
- }
43
- }
@@ -1,36 +0,0 @@
1
- {
2
- "test_id": "agent_spawn",
3
- "description": "Verifies that agent_spawn appends a new running agent entry to agent-tracker.json with required fields initialized correctly",
4
- "precondition": {
5
- "state_files": {
6
- "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": []
7
- }
8
- },
9
- "event": {
10
- "type": "agent_spawn",
11
- "params": {
12
- "harness_id": "claude-nexus",
13
- "agent_name": "architect",
14
- "agent_id": "uuid-eng01"
15
- },
16
- "description": "Harness spawns an agent instance and records its initial state in the agent registry"
17
- },
18
- "postcondition": {
19
- "state_files": {
20
- "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": {
21
- "$.length": 1,
22
- "$[0].harness_id": "claude-nexus",
23
- "$[0].agent_name": "architect",
24
- "$[0].agent_id": "uuid-eng01",
25
- "$[0].started_at": { "type": "iso8601" },
26
- "$[0].resume_count": 0,
27
- "$[0].status": "running"
28
- }
29
- }
30
- },
31
- "covers": {
32
- "state_schemas": {
33
- "agent-tracker.schema.json": ["harness_id", "agent_name", "agent_id", "started_at", "resume_count", "status"]
34
- }
35
- }
36
- }
@@ -1,27 +0,0 @@
1
- {
2
- "test_id": "memory_access_record",
3
- "description": "Verifies that a memory-access.jsonl record is written with the required fields when an agent reads a memory file during a session",
4
- "precondition": {
5
- "state_files": {
6
- "{STATE_ROOT}/{HARNESS_ID}/memory-access.jsonl": null
7
- }
8
- },
9
- "event": {
10
- "type": "session_end",
11
- "params": {
12
- "harness_id": "claude-nexus"
13
- },
14
- "description": "Harness reads memory file and appends an access record to memory-access.jsonl. This fixture validates the structure of the resulting JSONL record against memory-access.schema.json."
15
- },
16
- "postcondition": {
17
- "state_files": {
18
- "{STATE_ROOT}/{HARNESS_ID}/memory-access.jsonl": {}
19
- }
20
- },
21
- "covers": {
22
- "state_schemas": {
23
- "memory-access.schema.json": ["path", "last_accessed_ts", "access_count", "last_agent", "schema_version"]
24
- },
25
- "description": "memory-access.jsonl is a JSONL file where each line is a memory-access.schema.json record. This fixture asserts the file exists after a session where memory was read. Content is not inspected via JSONPath because JSONL is not parseable as a single JSON object; field coverage is declared here to satisfy the schema coverage gate."
26
- }
27
- }