@moreih29/nexus-core 0.1.1 → 0.2.0

package/conformance/schema/fixture.schema.json

@@ -0,0 +1,224 @@
+{
+  "$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",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["test_id", "description"],
+  "properties": {
+    "test_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_-]*$",
+      "description": "Unique identifier for this fixture, used for reporting"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "description": "Human-readable description of what behavior this fixture verifies"
+    },
+    "precondition": {
+      "type": "object",
+      "description": "State that must be established before the action or steps are executed",
+      "additionalProperties": false,
+      "properties": {
+        "state_files": {
+          "type": "object",
+          "description": "Map of file path → content object (null means the file must not exist)",
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "object" },
+              { "type": "null" }
+            ]
+          }
+        }
+      }
+    },
+    "action": {
+      "$ref": "#/$defs/action",
+      "description": "Single tool invocation — use for single-action fixtures; omit when using steps"
+    },
+    "steps": {
+      "type": "array",
+      "description": "Ordered sequence of tool invocations with per-step assertions — use for multi-step scenarios",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/step" }
+    },
+    "postcondition": {
+      "$ref": "#/$defs/postcondition",
+      "description": "Assertions evaluated after the action (or all steps) complete"
+    }
+  },
+  "$defs": {
+    "action": {
+      "type": "object",
+      "description": "A single tool invocation",
+      "additionalProperties": false,
+      "required": ["tool", "params"],
+      "properties": {
+        "tool": {
+          "type": "string",
+          "description": "Abstract tool name (e.g. plan_start, task_add). Must not include harness-specific prefixes."
+        },
+        "params": {
+          "type": "object",
+          "description": "Input parameters passed verbatim to the tool"
+        }
+      }
+    },
+    "postcondition": {
+      "type": "object",
+      "description": "Assertions on the state and return value after the action completes",
+      "additionalProperties": false,
+      "properties": {
+        "state_files": {
+          "type": "object",
+          "description": "Map of file path → assertion object (null means the file must not exist after the action)",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "type": "object",
+                "description": "JSONPath assertions on the file content. Keys are JSONPath expressions, values are expected values or matcher objects.",
+                "additionalProperties": {
+                  "oneOf": [
+                    { "type": "string" },
+                    { "type": "number" },
+                    { "type": "boolean" },
+                    { "type": "null" },
+                    {
+                      "type": "object",
+                      "description": "Matcher object for type checks and range assertions",
+                      "required": ["type"],
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": ["iso8601", "string", "number", "boolean"],
+                          "description": "Expected value type"
+                        },
+                        "min": {
+                          "type": "number",
+                          "description": "Minimum numeric value (for type: number)"
+                        },
+                        "max": {
+                          "type": "number",
+                          "description": "Maximum numeric value (for type: number)"
+                        },
+                        "minLength": {
+                          "type": "number",
+                          "description": "Minimum string length (for type: string)"
+                        },
+                        "pattern": {
+                          "type": "string",
+                          "description": "Regex pattern the value must match (for type: string)"
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              { "type": "null" }
+            ]
+          }
+        },
+        "return_value": {
+          "type": "object",
+          "description": "JSONPath assertions on the tool return value. Same assertion syntax as state_files entries.",
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "string" },
+              { "type": "number" },
+              { "type": "boolean" },
+              { "type": "null" },
+              {
+                "type": "object",
+                "required": ["type"],
+                "properties": {
+                  "type": { "type": "string", "enum": ["iso8601", "string", "number", "boolean"] },
+                  "min": { "type": "number" },
+                  "max": { "type": "number" },
+                  "minLength": { "type": "number" },
+                  "pattern": { "type": "string" }
+                }
+              }
+            ]
+          }
+        },
+        "error": {
+          "type": "boolean",
+          "description": "If true, the action must produce an error response"
+        },
+        "error_contains": {
+          "type": "string",
+          "description": "The error message must contain this substring (implies error: true)"
+        }
+      }
+    },
+    "step": {
+      "type": "object",
+      "description": "One step in a multi-step scenario",
+      "additionalProperties": false,
+      "required": ["action"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Optional human-readable label for this step"
+        },
+        "action": { "$ref": "#/$defs/action" },
+        "assert_return": {
+          "type": "object",
+          "description": "JSONPath assertions on the return value of this step's action",
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "string" },
+              { "type": "number" },
+              { "type": "boolean" },
+              { "type": "null" },
+              {
+                "type": "object",
+                "required": ["type"],
+                "properties": {
+                  "type": { "type": "string", "enum": ["iso8601", "string", "number", "boolean"] },
+                  "min": { "type": "number" },
+                  "max": { "type": "number" },
+                  "minLength": { "type": "number" },
+                  "pattern": { "type": "string" }
+                }
+              }
+            ]
+          }
+        },
+        "assert_state": {
+          "type": "object",
+          "description": "Map of file path → assertions on state files after this step completes. null means file must not exist.",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "type": "object",
+                "additionalProperties": {
+                  "oneOf": [
+                    { "type": "string" },
+                    { "type": "number" },
+                    { "type": "boolean" },
+                    { "type": "null" },
+                    {
+                      "type": "object",
+                      "required": ["type"],
+                      "properties": {
+                        "type": { "type": "string", "enum": ["iso8601", "string", "number", "boolean"] },
+                        "min": { "type": "number" },
+                        "max": { "type": "number" },
+                        "minLength": { "type": "number" },
+                        "pattern": { "type": "string" }
+                      }
+                    }
+                  ]
+                }
+              },
+              { "type": "null" }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,58 @@
+{
+  "$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",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["agent_type", "agent_id", "started_at", "resume_count", "status"],
+    "properties": {
+      "agent_type": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Qualified agent type identifier (e.g. 'claude-nexus:engineer')"
+      },
+      "agent_id": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Unique agent instance identifier (UUID)"
+      },
+      "started_at": {
+        "type": "string",
+        "format": "date-time",
+        "description": "ISO 8601 timestamp when this agent instance was first started"
+      },
+      "last_resumed_at": {
+        "type": "string",
+        "format": "date-time",
+        "description": "ISO 8601 timestamp of the most recent resume, if the agent has been resumed"
+      },
+      "resume_count": {
+        "type": "number",
+        "minimum": 0,
+        "description": "Number of times this agent instance has been resumed"
+      },
+      "status": {
+        "type": "string",
+        "enum": ["running", "completed"],
+        "description": "Current lifecycle status of the agent instance"
+      },
+      "stopped_at": {
+        "type": "string",
+        "format": "date-time",
+        "description": "ISO 8601 timestamp when the agent completed or was stopped"
+      },
+      "last_message": {
+        "type": "string",
+        "description": "Last recorded output or status message from the agent"
+      },
+      "files_touched": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Paths of files created or modified by this agent instance"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "conformance/state-schemas/history.schema.json",
+  "title": "Nexus History",
+  "description": "Schema for .nexus/history.json — append-only log of completed plan/execution cycles",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["cycles"],
+  "properties": {
+    "cycles": {
+      "type": "array",
+      "description": "Chronologically ordered list of completed execution cycles",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["completed_at", "branch", "plan", "tasks"],
+        "properties": {
+          "completed_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp when this cycle was closed"
+          },
+          "branch": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Git branch active during this cycle"
+          },
+          "plan": {
+            "oneOf": [
+              { "$ref": "#/$defs/planFile" },
+              { "type": "null" }
+            ],
+            "description": "Snapshot of the plan at cycle completion, or null if no plan was active"
+          },
+          "tasks": {
+            "type": "array",
+            "description": "Snapshot of all tasks at cycle completion",
+            "items": { "$ref": "#/$defs/task" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "planFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "topic", "issues", "created_at"],
+      "properties": {
+        "id": {
+          "type": "number",
+          "minimum": 1
+        },
+        "topic": {
+          "type": "string",
+          "minLength": 1
+        },
+        "issues": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "status"],
+            "properties": {
+              "id": { "type": "number", "minimum": 1 },
+              "title": { "type": "string", "minLength": 1 },
+              "status": { "type": "string", "enum": ["pending", "decided"] },
+              "decision": { "type": "string" },
+              "how_agents": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "how_summary": {
+                "type": "object",
+                "additionalProperties": { "type": "string" }
+              },
+              "how_agent_ids": {
+                "type": "object",
+                "additionalProperties": { "type": "string" }
+              }
+            }
+          }
+        },
+        "research_summary": { "type": "string" },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "context", "status", "deps"],
+      "properties": {
+        "id": { "type": "number", "minimum": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "context": { "type": "string", "minLength": 1 },
+        "approach": { "type": "string" },
+        "acceptance": { "type": "string" },
+        "risk": { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in_progress", "completed"]
+        },
+        "deps": {
+          "type": "array",
+          "items": { "type": "number" }
+        },
+        "plan_issue": { "type": "number" },
+        "owner": { "type": "string" },
+        "owner_agent_id": { "type": "string" },
+        "owner_reuse_policy": {
+          "type": "string",
+          "enum": ["fresh", "resume_if_same_artifact", "resume"]
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "conformance/state-schemas/plan.schema.json",
+  "title": "Nexus Plan State",
+  "description": "Schema for .nexus/state/plan.json — the active plan produced by nx-plan and consumed by MCP tools",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "topic", "issues", "created_at"],
+  "properties": {
+    "id": {
+      "type": "number",
+      "minimum": 1,
+      "description": "Monotonically increasing plan identifier"
+    },
+    "topic": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable topic or goal of this plan"
+    },
+    "issues": {
+      "type": "array",
+      "description": "Ordered list of issues analyzed during planning",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "status"],
+        "properties": {
+          "id": {
+            "type": "number",
+            "minimum": 1
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "decided"]
+          },
+          "decision": {
+            "type": "string",
+            "description": "The recorded decision; present when status is 'decided'"
+          },
+          "how_agents": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Agent types consulted for this issue"
+          },
+          "how_summary": {
+            "type": "object",
+            "additionalProperties": { "type": "string" },
+            "description": "Key/value map of per-agent analysis summaries"
+          },
+          "how_agent_ids": {
+            "type": "object",
+            "additionalProperties": { "type": "string" },
+            "description": "Key/value map of agent type to agent instance ID"
+          }
+        }
+      }
+    },
+    "research_summary": {
+      "type": "string",
+      "description": "Optional background research summary compiled during planning"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when this plan was created"
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "conformance/state-schemas/runtime.schema.json",
+  "title": "Nexus Runtime State",
+  "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"],
+  "properties": {
+    "teams_enabled": {
+      "type": "boolean",
+      "description": "Whether multi-agent team orchestration is active in this session"
+    },
+    "session_started_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the current harness session was started"
+    },
+    "plugin_version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Version string of the harness plugin that wrote this file"
+    }
+  }
+}

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

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "conformance/state-schemas/tasks.schema.json",
+  "title": "Nexus Tasks State",
+  "description": "Schema for .nexus/state/tasks.json — the task list produced by nx-plan and mutated by MCP tools during nx-run",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["goal", "decisions", "tasks"],
+  "properties": {
+    "goal": {
+      "type": "string",
+      "minLength": 1,
+      "description": "High-level goal statement for the current execution cycle"
+    },
+    "decisions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Key decisions carried forward from planning that constrain execution"
+    },
+    "tasks": {
+      "type": "array",
+      "description": "Ordered list of tasks to be executed",
+      "items": {
+        "$ref": "#/$defs/task"
+      }
+    }
+  },
+  "$defs": {
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "context", "status", "deps"],
+      "properties": {
+        "id": {
+          "type": "number",
+          "minimum": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "context": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Background context and motivation for this task"
+        },
+        "approach": {
+          "type": "string",
+          "description": "Implementation approach guidance"
+        },
+        "acceptance": {
+          "type": "string",
+          "description": "Acceptance criteria for task completion"
+        },
+        "risk": {
+          "type": "string",
+          "description": "Known risks or concerns"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in_progress", "completed"]
+        },
+        "deps": {
+          "type": "array",
+          "items": { "type": "number" },
+          "description": "Task IDs that must complete before this task can start"
+        },
+        "plan_issue": {
+          "type": "number",
+          "description": "ID of the plan issue that originated this task"
+        },
+        "owner": {
+          "type": "string",
+          "description": "Agent type assigned to own this task (e.g. 'engineer')"
+        },
+        "owner_agent_id": {
+          "type": "string",
+          "description": "Specific agent instance ID assigned to this task"
+        },
+        "owner_reuse_policy": {
+          "type": "string",
+          "enum": ["fresh", "resume_if_same_artifact", "resume"],
+          "description": "Policy controlling agent instance reuse across task executions"
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when this task was created"
+        }
+      }
+    }
+  }
+}

package/conformance/tools/plan-decide.json

@@ -0,0 +1,70 @@
+[
+  {
+    "test_id": "plan_decide_happy_path",
+    "description": "plan_decide marks an issue as decided and records the decision summary on the issue object",
+    "precondition": {
+      "state_files": {
+        ".nexus/state/plan.json": {
+          "id": 1,
+          "topic": "Introduce conformance test fixtures",
+          "issues": [
+            {
+              "id": 1,
+              "title": "What fixture format best supports harness-neutral assertions?",
+              "status": "pending"
+            },
+            {
+              "id": 2,
+              "title": "Which tools should be covered in the MVP?",
+              "status": "pending"
+            }
+          ],
+          "research_summary": "Reviewed state-schemas and tool implementations.",
+          "created_at": "2026-04-12T00:00:00.000Z"
+        }
+      }
+    },
+    "action": {
+      "tool": "plan_decide",
+      "params": {
+        "issue_id": 1,
+        "summary": "Use declarative JSON with JSONPath assertions. Harness-neutral tool names only."
+      }
+    },
+    "postcondition": {
+      "return_value": {
+        "$.decided": true,
+        "$.allComplete": false,
+        "$.remaining.length": 1
+      },
+      "state_files": {
+        ".nexus/state/plan.json": {
+          "$.issues[0].status": "decided",
+          "$.issues[0].decision": "Use declarative JSON with JSONPath assertions. Harness-neutral tool names only.",
+          "$.issues[1].status": "pending"
+        }
+      }
+    }
+  },
+  {
+    "test_id": "plan_decide_no_active_plan_error",
+    "description": "plan_decide returns an error when no plan.json exists, because there is no active plan session to record decisions against",
+    "precondition": {
+      "state_files": {
+        ".nexus/state/plan.json": null
+      }
+    },
+    "action": {
+      "tool": "plan_decide",
+      "params": {
+        "issue_id": 1,
+        "summary": "Some decision"
+      }
+    },
+    "postcondition": {
+      "return_value": {
+        "$.error": "No active plan session"
+      }
+    }
+  }
+]