@moreih29/nexus-core 0.3.0 → 0.5.0

package/conformance/schema/fixture.schema.json

@@ -2,10 +2,36 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "fixture.schema.json",
   "title": "Nexus Conformance Test Fixture",
-  "description": "Declarative test case for Nexus MCP tool behavioral verification",
+  "description": "Declarative test case for Nexus MCP tool behavioral verification. Each fixture must declare exactly one of: action (single tool invocation), event (single lifecycle event), or steps (multi-step sequence).",
   "type": "object",
   "additionalProperties": false,
-  "required": ["test_id", "description"],
+  "required": ["test_id", "description", "covers"],
+  "oneOf": [
+    {
+      "required": ["action"],
+      "properties": {
+        "action": true,
+        "event": false,
+        "steps": false
+      }
+    },
+    {
+      "required": ["event"],
+      "properties": {
+        "action": false,
+        "event": true,
+        "steps": false
+      }
+    },
+    {
+      "required": ["steps"],
+      "properties": {
+        "action": false,
+        "event": false,
+        "steps": true
+      }
+    }
+  ],
   "properties": {
     "test_id": {
       "type": "string",
@@ -17,6 +43,68 @@
       "minLength": 10,
       "description": "Human-readable description of what behavior this fixture verifies"
     },
+    "covers": {
+      "type": "object",
+      "description": "Declaration of which schema fields and return value paths this fixture verifies. At least one of state_schemas or return_value must be non-empty.",
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "properties": {
+            "state_schemas": {
+              "minProperties": 1
+            }
+          },
+          "required": ["state_schemas"]
+        },
+        {
+          "properties": {
+            "return_value": {
+              "minProperties": 1
+            }
+          },
+          "required": ["return_value"]
+        }
+      ],
+      "properties": {
+        "state_schemas": {
+          "type": "object",
+          "description": "Map of state-schema filename (e.g. 'plan.schema.json') to array of field paths verified by this fixture's postcondition. Field paths use dot-notation with array index notation (e.g. 'issues[].status').",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[^ ]+$",
+              "description": "Field path within the named schema (e.g. 'id', 'issues[].status', 'issues[].how_agents')"
+            }
+          }
+        },
+        "return_value": {
+          "type": "object",
+          "description": "Map of abstract tool name (e.g. 'plan_start') to array of return-value field paths verified by this fixture's postcondition.",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[^ ]+$",
+              "description": "Field path within the tool's return value (e.g. 'created', 'plan_id', 'issueCount')"
+            }
+          }
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional human-readable explanation of coverage rationale or known gaps"
+        }
+      }
+    },
+    "uncovered_params": {
+      "type": "array",
+      "description": "Params intentionally excluded from postcondition verification. Validators treat entries here as explicit exceptions rather than coverage gaps, preventing false anti-pattern warnings.",
+      "items": {
+        "type": "string",
+        "pattern": "^[^ ]+$",
+        "description": "Parameter name from the action or event params that is deliberately not verified"
+      }
+    },
     "precondition": {
       "type": "object",
       "description": "State that must be established before the action or steps are executed",
@@ -24,7 +112,7 @@
       "properties": {
         "state_files": {
           "type": "object",
-          "description": "Map of file path → content object (null means the file must not exist)",
+          "description": "Map of file path to content object. null = file must not exist; empty object {} = file must exist but content is not inspected (use for non-JSON artifacts like .md, .txt, binary files); non-empty object = precondition content written as-is (typically JSON).",
           "additionalProperties": {
             "oneOf": [
               { "type": "object" },
@@ -36,11 +124,15 @@
     },
     "action": {
       "$ref": "#/$defs/action",
-      "description": "Single tool invocation — use for single-action fixtures; omit when using steps"
+      "description": "Single tool invocation — use for single-action fixtures; mutually exclusive with event and steps"
+    },
+    "event": {
+      "$ref": "#/$defs/event",
+      "description": "Single lifecycle event — use for event-based fixtures that require no tool call; mutually exclusive with action and steps"
     },
     "steps": {
       "type": "array",
-      "description": "Ordered sequence of tool invocations with per-step assertions — use for multi-step scenarios",
+      "description": "Ordered sequence of tool invocations or lifecycle events with per-step assertions — use for multi-step scenarios; mutually exclusive with action and event",
       "minItems": 1,
       "items": { "$ref": "#/$defs/step" }
     },
@@ -66,6 +158,28 @@
         }
       }
     },
+    "event": {
+      "type": "object",
+      "description": "A lifecycle event that triggers harness-level behavior without a direct tool call. Used for verifying runtime.json and agent-tracker.json state changes.",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["session_start", "session_end", "agent_spawn", "agent_complete", "agent_resume"],
+          "description": "Lifecycle event type. session_start/session_end: harness session lifecycle; agent_spawn/agent_complete/agent_resume: agent instance lifecycle."
+        },
+        "params": {
+          "type": "object",
+          "description": "Optional event-specific parameters (e.g. harness_id, agent_name, and agent_id for agent_spawn)",
+          "additionalProperties": true
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional human-readable explanation of the event and its expected effect"
+        }
+      }
+    },
     "postcondition": {
       "type": "object",
       "description": "Assertions on the state and return value after the action completes",
@@ -73,7 +187,7 @@
       "properties": {
         "state_files": {
           "type": "object",
-          "description": "Map of file path → assertion object (null means the file must not exist after the action)",
+          "description": "Map of file path to assertion object. null = file must not exist after the action; empty object {} = file must exist but content is not inspected (use for non-JSON artifacts like .md, .txt, binary files); non-empty object = JSONPath assertions on parsed JSON content.",
           "additionalProperties": {
             "oneOf": [
               {
@@ -155,15 +269,31 @@
     },
     "step": {
       "type": "object",
-      "description": "One step in a multi-step scenario",
+      "description": "One step in a multi-step scenario. Each step must contain exactly one of: action (tool invocation) or event (lifecycle event).",
       "additionalProperties": false,
-      "required": ["action"],
+      "oneOf": [
+        {
+          "required": ["action"],
+          "properties": {
+            "action": true,
+            "event": false
+          }
+        },
+        {
+          "required": ["event"],
+          "properties": {
+            "action": false,
+            "event": true
+          }
+        }
+      ],
       "properties": {
         "description": {
           "type": "string",
           "description": "Optional human-readable label for this step"
         },
         "action": { "$ref": "#/$defs/action" },
+        "event": { "$ref": "#/$defs/event" },
         "assert_return": {
           "type": "object",
           "description": "JSONPath assertions on the return value of this step's action",
@@ -189,7 +319,7 @@
         },
         "assert_state": {
           "type": "object",
-          "description": "Map of file path → assertions on state files after this step completes. null means file must not exist.",
+          "description": "Map of file path to assertions on state files after this step completes. null means file must not exist.",
           "additionalProperties": {
             "oneOf": [
               {

package/conformance/state-schemas/agent-tracker.schema.json

@@ -2,17 +2,22 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "conformance/state-schemas/agent-tracker.schema.json",
   "title": "Nexus Agent Tracker",
-  "description": "Schema for .nexus/state/agent-tracker.json — registry of spawned agent instances tracked across a session",
+  "description": "Schema for .nexus/state/agent-tracker.json — registry of spawned agent instances tracked across a session. No schema_version field: this file is session-scoped and deleted on session end — migration anchor not required.",
   "type": "array",
   "items": {
     "type": "object",
     "additionalProperties": false,
-    "required": ["agent_type", "agent_id", "started_at", "resume_count", "status"],
+    "required": ["harness_id", "agent_name", "agent_id", "started_at", "resume_count", "status"],
     "properties": {
-      "agent_type": {
+      "harness_id": {
         "type": "string",
-        "minLength": 1,
-        "description": "Qualified agent type identifier (e.g. 'claude-nexus:engineer')"
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "description": "Identifier of the harness that spawned this agent."
+      },
+      "agent_name": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "description": "Neutral agent id as defined in nexus-core agents/{id}/meta.yml (e.g. 'architect', 'engineer')."
       },
       "agent_id": {
         "type": "string",

package/conformance/state-schemas/history.schema.json

@@ -7,14 +7,24 @@
   "additionalProperties": false,
   "required": ["cycles"],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "nexus-core version that introduced this schema shape (e.g. '0.5'). Optional in v0.5.0 — candidate for required in v1.0.0 (Phase 2 entry)."
+    },
     "cycles": {
       "type": "array",
       "description": "Chronologically ordered list of completed execution cycles",
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["completed_at", "branch", "plan", "tasks"],
+        "required": ["completed_at", "branch", "plan", "tasks", "schema_version"],
         "properties": {
+          "schema_version": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+$",
+            "description": "Version tag recorded at the time this cycle was archived. Required for every cycle as history.json accumulates across nexus-core versions."
+          },
           "completed_at": {
             "type": "string",
             "format": "date-time",

package/conformance/state-schemas/plan.schema.json

@@ -7,6 +7,11 @@
   "additionalProperties": false,
   "required": ["id", "topic", "issues", "created_at"],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "nexus-core version that introduced this schema shape (e.g. '0.5'). Optional in v0.5.0 — candidate for required in v1.0.0 (Phase 2 entry)."
+    },
     "id": {
       "type": "number",
       "minimum": 1,

package/conformance/state-schemas/runtime.schema.json

@@ -5,8 +5,13 @@
   "description": "Schema for .nexus/state/runtime.json — ephemeral runtime configuration written by the harness at session start",
   "type": "object",
   "additionalProperties": false,
-  "required": ["teams_enabled", "session_started_at", "plugin_version"],
+  "required": ["teams_enabled", "session_started_at", "harness_id", "harness_version"],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "nexus-core version that introduced this schema shape (e.g. '0.5'). Optional in v0.5.0 — candidate for required in v1.0.0 (Phase 2 entry)."
+    },
     "teams_enabled": {
       "type": "boolean",
       "description": "Whether multi-agent team orchestration is active in this session"
@@ -16,10 +21,14 @@
       "format": "date-time",
       "description": "ISO 8601 timestamp when the current harness session was started"
     },
-    "plugin_version": {
+    "harness_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Identifier of the harness that owns this runtime state (e.g. 'claude-nexus', 'opencode-nexus'). Free string — nexus-core does not enumerate harnesses."
+    },
+    "harness_version": {
       "type": "string",
-      "minLength": 1,
-      "description": "Version string of the harness plugin that wrote this file"
+      "description": "Semver-like version string of the harness plugin that wrote this file."
     }
   }
 }

package/conformance/state-schemas/tasks.schema.json

@@ -7,6 +7,11 @@
   "additionalProperties": false,
   "required": ["goal", "decisions", "tasks"],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "nexus-core version that introduced this schema shape (e.g. '0.5'). Optional in v0.5.0 — candidate for required in v1.0.0 (Phase 2 entry)."
+    },
     "goal": {
       "type": "string",
       "minLength": 1,

package/conformance/tools/artifact-write.json

@@ -0,0 +1,97 @@
+[
+  {
+    "test_id": "artifact_write_first",
+    "description": "artifact_write creates the artifacts directory and writes the file when no artifacts directory exists, returning success:true and a path ending in the filename",
+    "covers": {
+      "return_value": {
+        "artifact_write": ["success", "path"]
+      }
+    },
+    "uncovered_params": ["filename", "content"],
+    "precondition": {
+      "state_files": {
+        ".nexus/state/artifacts/findings.md": null
+      }
+    },
+    "action": {
+      "tool": "artifact_write",
+      "params": {
+        "filename": "findings.md",
+        "content": "# Findings\n\nInitial research findings for the conformance test suite."
+      }
+    },
+    "postcondition": {
+      "return_value": {
+        "$.success": true,
+        "$.path": { "type": "string", "pattern": "findings\\.md$" }
+      },
+      "state_files": {
+        ".nexus/state/artifacts/findings.md": {}
+      }
+    }
+  },
+  {
+    "test_id": "artifact_write_overwrite",
+    "description": "artifact_write overwrites an existing artifact file and returns success:true without error",
+    "covers": {
+      "return_value": {
+        "artifact_write": ["success", "path"]
+      }
+    },
+    "uncovered_params": ["filename", "content"],
+    "precondition": {
+      "state_files": {
+        ".nexus/state/artifacts/existing.md": {
+          "content": "old content"
+        }
+      }
+    },
+    "action": {
+      "tool": "artifact_write",
+      "params": {
+        "filename": "existing.md",
+        "content": "new content"
+      }
+    },
+    "postcondition": {
+      "return_value": {
+        "$.success": true,
+        "$.path": { "type": "string", "pattern": "existing\\.md$" }
+      },
+      "state_files": {
+        ".nexus/state/artifacts/existing.md": {}
+      }
+    }
+  },
+  {
+    "test_id": "artifact_write_creates_directory",
+    "description": "artifact_write auto-creates the .nexus/state/artifacts/ directory when it does not exist and then writes the file successfully",
+    "covers": {
+      "return_value": {
+        "artifact_write": ["success", "path"]
+      }
+    },
+    "uncovered_params": ["filename", "content"],
+    "precondition": {
+      "state_files": {
+        ".nexus/state/artifacts/synthesis.md": null
+      }
+    },
+    "action": {
+      "tool": "artifact_write",
+      "params": {
+        "filename": "synthesis.md",
+        "content": "# Synthesis\n\nCross-cycle pattern analysis."
+      }
+    },
+    "postcondition": {
+      "return_value": {
+        "$.success": true,
+        "$.path": { "type": "string", "pattern": "synthesis\\.md$" }
+      },
+      "state_files": {
+        ".nexus/state/artifacts/synthesis.md": {}
+      }
+    }
+  }
+]

package/conformance/tools/context.json

@@ -0,0 +1,172 @@
+[
+  {
+    "test_id": "context_no_tasks",
+    "description": "context returns activeMode:null and an empty decisions array with a valid branch string when tasks.json does not exist",
+    "covers": {
+      "return_value": {
+        "context": ["activeMode", "branch", "decisions"]
+      }
+    },
+    "precondition": {
+      "state_files": {
+        ".nexus/state/tasks.json": null
+      }
+    },
+    "action": {
+      "tool": "context",
+      "params": {}
+    },
+    "postcondition": {
+      "return_value": {
+        "$.activeMode": null,
+        "$.branch": { "type": "string", "minLength": 1 },
+        "$.decisions.length": 0
+      }
+    }
+  },
+  {
+    "test_id": "context_with_tasks",
+    "description": "context returns activeMode:team, the goal, and a tasksSummary with the correct total when tasks.json exists with a goal and 2 tasks",
+    "covers": {
+      "state_schemas": {
+        "tasks.schema.json": ["goal", "tasks[].id", "tasks[].status"]
+      },
+      "return_value": {
+        "context": ["activeMode", "goal", "tasksSummary.total", "tasksSummary.completed", "tasksSummary.pending"]
+      }
+    },
+    "precondition": {
+      "state_files": {
+        ".nexus/state/tasks.json": {
+          "goal": "Deliver conformance fixture suite",
+          "decisions": [],
+          "tasks": [
+            {
+              "id": 1,
+              "title": "Write fixture schema",
+              "context": "Define the JSON Schema",
+              "status": "completed",
+              "deps": [],
+              "created_at": "2026-04-13T00:00:00.000Z"
+            },
+            {
+              "id": 2,
+              "title": "Write tool fixtures",
+              "context": "Create per-tool fixture files",
+              "status": "pending",
+              "deps": [1],
+              "created_at": "2026-04-13T00:00:00.000Z"
+            }
+          ]
+        }
+      }
+    },
+    "action": {
+      "tool": "context",
+      "params": {}
+    },
+    "postcondition": {
+      "return_value": {
+        "$.activeMode": "team",
+        "$.goal": "Deliver conformance fixture suite",
+        "$.tasksSummary.total": 2
+      }
+    }
+  },
+  {
+    "test_id": "context_with_decisions",
+    "description": "context returns a decisions array with length 2 when decisions.json contains 2 entries alongside an active tasks.json",
+    "covers": {
+      "return_value": {
+        "context": ["decisions"]
+      }
+    },
+    "precondition": {
+      "state_files": {
+        ".nexus/state/tasks.json": {
+          "goal": "Deliver conformance fixture suite",
+          "decisions": [
+            "Use declarative JSONPath assertions for harness neutrality.",
+            "One tool per fixture file to keep scope bounded."
+          ],
+          "tasks": [
+            {
+              "id": 1,
+              "title": "Write fixture schema",
+              "context": "Define the JSON Schema",
+              "status": "completed",
+              "deps": [],
+              "created_at": "2026-04-13T00:00:00.000Z"
+            }
+          ]
+        }
+      }
+    },
+    "action": {
+      "tool": "context",
+      "params": {}
+    },
+    "postcondition": {
+      "return_value": {
+        "$.decisions.length": 2
+      }
+    }
+  },
+  {
+    "test_id": "context_tasks_summary_breakdown",
+    "description": "context computes tasksSummary correctly when the task list contains 1 completed, 1 pending, and 1 in_progress task",
+    "covers": {
+      "state_schemas": {
+        "tasks.schema.json": ["tasks[].status"]
+      },
+      "return_value": {
+        "context": ["tasksSummary.total", "tasksSummary.completed", "tasksSummary.pending"]
+      }
+    },
+    "precondition": {
+      "state_files": {
+        ".nexus/state/tasks.json": {
+          "goal": "Summary breakdown validation",
+          "decisions": [],
+          "tasks": [
+            {
+              "id": 1,
+              "title": "Done task",
+              "context": "Already finished",
+              "status": "completed",
+              "deps": [],
+              "created_at": "2026-04-13T00:00:00.000Z"
+            },
+            {
+              "id": 2,
+              "title": "Pending task",
+              "context": "Not yet started",
+              "status": "pending",
+              "deps": [],
+              "created_at": "2026-04-13T00:00:00.000Z"
+            },
+            {
+              "id": 3,
+              "title": "Active task",
+              "context": "Currently being worked on",
+              "status": "in_progress",
+              "deps": [],
+              "created_at": "2026-04-13T00:00:00.000Z"
+            }
+          ]
+        }
+      }
+    },
+    "action": {
+      "tool": "context",
+      "params": {}
+    },
+    "postcondition": {
+      "return_value": {
+        "$.tasksSummary.total": 3,
+        "$.tasksSummary.completed": 1,
+        "$.tasksSummary.pending": 1
+      }
+    }
+  }
+]