@moreih29/nexus-core 0.12.0 → 0.13.0

package/conformance/scenarios/full-plan-cycle.json

@@ -1,147 +0,0 @@
-{
-  "test_id": "full_plan_cycle",
-  "description": "Verifies the complete plan → decide → task_add → close lifecycle across 5 sequential tool invocations",
-  "covers": {
-    "state_schemas": {
-      "plan.schema.json": ["id", "topic", "issues[].id", "issues[].title", "issues[].status", "issues[].decision", "research_summary", "created_at"],
-      "tasks.schema.json": ["goal", "decisions", "tasks[].id", "tasks[].title", "tasks[].status", "tasks[].plan_issue"],
-      "history.schema.json": ["cycles[].completed_at", "cycles[].plan", "cycles[].plan.issues[].status", "cycles[].tasks[].id"]
-    },
-    "return_value": {
-      "plan_start": ["created", "plan_id", "issueCount"],
-      "plan_decide": ["decided", "allComplete", "remaining"],
-      "task_add": ["task.id", "task.status", "task.plan_issue"],
-      "task_close": ["closed", "archived.plan", "archived.decisions", "archived.tasks", "total_cycles"]
-    },
-    "description": "End-to-end lifecycle scenario: plan/task/history state transitions and each tool's return value across 5 sequential invocations."
-  },
-  "uncovered_params": ["research_summary", "issue_id", "decision", "title", "context", "deps"],
-  "precondition": {
-    "state_files": {
-      ".nexus/state/plan.json": null,
-      ".nexus/state/tasks.json": null
-    }
-  },
-  "steps": [
-    {
-      "description": "Start a new plan with 2 issues",
-      "action": {
-        "tool": "plan_start",
-        "params": {
-          "topic": "Refactor state persistence layer",
-          "issues": [
-            "Should state files live in .nexus/state/ or project root?",
-            "What is the migration path for existing users?"
-          ],
-          "research_summary": "Surveyed 3 consumer repos. All use .nexus/state/ already. Migration: provide a one-shot relocate script."
-        }
-      },
-      "assert_return": {
-        "$.created": true,
-        "$.plan_id": { "type": "number", "min": 1 },
-        "$.issueCount": 2
-      },
-      "assert_state": {
-        ".nexus/state/plan.json": {
-          "$.topic": "Refactor state persistence layer",
-          "$.issues.length": 2,
-          "$.issues[0].status": "pending",
-          "$.issues[1].status": "pending"
-        }
-      }
-    },
-    {
-      "description": "Decide issue 1 — confirm .nexus/state/ location",
-      "action": {
-        "tool": "plan_decide",
-        "params": {
-          "issue_id": 1,
-          "decision": "Keep .nexus/state/ as the canonical location. Documented in state-schemas README."
-        }
-      },
-      "assert_return": {
-        "$.decided": true,
-        "$.allComplete": false,
-        "$.remaining.length": 1
-      },
-      "assert_state": {
-        ".nexus/state/plan.json": {
-          "$.issues[0].status": "decided",
-          "$.issues[0].decision": "Keep .nexus/state/ as the canonical location. Documented in state-schemas README.",
-          "$.issues[1].status": "pending"
-        }
-      }
-    },
-    {
-      "description": "Decide issue 2 — confirm migration path; all issues now decided",
-      "action": {
-        "tool": "plan_decide",
-        "params": {
-          "issue_id": 2,
-          "decision": "Ship a one-shot migration script as a standalone npm script. Document in RELEASING.md."
-        }
-      },
-      "assert_return": {
-        "$.decided": true,
-        "$.allComplete": true
-      },
-      "assert_state": {
-        ".nexus/state/plan.json": {
-          "$.issues[0].status": "decided",
-          "$.issues[1].status": "decided"
-        }
-      }
-    },
-    {
-      "description": "Add a task derived from plan issue 1",
-      "action": {
-        "tool": "task_add",
-        "params": {
-          "title": "Update state-schemas README for .nexus/state/ location",
-          "context": "Decision from plan: .nexus/state/ is the canonical location. Document this clearly.",
-          "deps": [],
-          "plan_issue": 1,
-          "goal": "Land refactored state persistence layer with migration support"
-        }
-      },
-      "assert_return": {
-        "$.task.id": 1,
-        "$.task.status": "pending",
-        "$.task.plan_issue": 1
-      },
-      "assert_state": {
-        ".nexus/state/tasks.json": {
-          "$.goal": "Land refactored state persistence layer with migration support",
-          "$.tasks.length": 1,
-          "$.tasks[0].id": 1,
-          "$.tasks[0].plan_issue": 1
-        }
-      }
-    },
-    {
-      "description": "Close the cycle — archive plan and tasks into history, delete source files",
-      "action": {
-        "tool": "task_close",
-        "params": {}
-      },
-      "assert_return": {
-        "$.closed": true,
-        "$.archived.plan": true,
-        "$.archived.decisions": 2,
-        "$.archived.tasks": 1,
-        "$.total_cycles": { "type": "number", "min": 1 }
-      },
-      "assert_state": {
-        ".nexus/state/plan.json": null,
-        ".nexus/state/tasks.json": null,
-        ".nexus/history.json": {
-          "$.cycles.length": { "type": "number", "min": 1 },
-          "$.cycles[-1].plan.topic": "Refactor state persistence layer",
-          "$.cycles[-1].plan.issues.length": 2,
-          "$.cycles[-1].tasks.length": 1,
-          "$.cycles[-1].completed_at": { "type": "iso8601" }
-        }
-      }
-    }
-  ]
-}

package/conformance/scenarios/task-deps-ordering.json

@@ -1,95 +0,0 @@
-{
-  "test_id": "task_deps_ordering",
-  "description": "Verifies that dependency ordering is enforced by task_list: a task with an incomplete dep is not ready, and becomes ready after the dep is completed",
-  "covers": {
-    "state_schemas": {
-      "tasks.schema.json": ["goal", "tasks[].id", "tasks[].title", "tasks[].status", "tasks[].deps"]
-    },
-    "return_value": {
-      "task_add": ["task.id", "task.status", "task.deps"],
-      "task_list": ["summary.total", "summary.ready", "summary.completed"],
-      "task_update": ["task.id", "task.status"]
-    },
-    "description": "Dependency-aware ready set computation: validates that task_list correctly unblocks dependents after prerequisites complete."
-  },
-  "uncovered_params": ["title", "context", "goal"],
-  "precondition": {
-    "state_files": {
-      ".nexus/state/tasks.json": null
-    }
-  },
-  "steps": [
-    {
-      "description": "Add task A with no dependencies",
-      "action": {
-        "tool": "task_add",
-        "params": {
-          "title": "Task A — foundation work",
-          "context": "Must complete before Task B can start",
-          "deps": [],
-          "goal": "Validate dependency ordering"
-        }
-      },
-      "assert_return": {
-        "$.task.id": 1,
-        "$.task.status": "pending",
-        "$.task.deps.length": 0
-      }
-    },
-    {
-      "description": "Add task B that depends on task A (id=1)",
-      "action": {
-        "tool": "task_add",
-        "params": {
-          "title": "Task B — requires A",
-          "context": "Can only start after Task A is completed",
-          "deps": [1]
-        }
-      },
-      "assert_return": {
-        "$.task.id": 2,
-        "$.task.status": "pending",
-        "$.task.deps.length": 1,
-        "$.task.deps[0]": 1
-      }
-    },
-    {
-      "description": "List tasks — only task A should be ready because task B's dep is not complete",
-      "action": {
-        "tool": "task_list",
-        "params": {}
-      },
-      "assert_return": {
-        "$.summary.total": 2,
-        "$.summary.ready.length": 1,
-        "$.summary.ready[0]": 1
-      }
-    },
-    {
-      "description": "Mark task A as completed",
-      "action": {
-        "tool": "task_update",
-        "params": {
-          "id": 1,
-          "status": "completed"
-        }
-      },
-      "assert_return": {
-        "$.task.id": 1,
-        "$.task.status": "completed"
-      }
-    },
-    {
-      "description": "List tasks again — task B should now be ready because its dep (A) is completed",
-      "action": {
-        "tool": "task_list",
-        "params": {}
-      },
-      "assert_return": {
-        "$.summary.ready.length": 1,
-        "$.summary.ready[0]": 2,
-        "$.summary.completed": 1
-      }
-    }
-  ]
-}

package/conformance/schema/fixture.schema.json

@@ -1,354 +0,0 @@
-{
-  "$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. 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", "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",
-      "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"
-    },
-    "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",
-      "additionalProperties": false,
-      "properties": {
-        "state_files": {
-          "type": "object",
-          "description": "Map of file path to content object. File path keys may contain placeholder tokens that a conformance runner must expand before resolving paths. Allowed tokens: {STATE_ROOT} (the root directory for all harness state, e.g. '.nexus/state') and {HARNESS_ID} (the harness identifier, resolved from event.params.harness_id or equivalent context). No other arbitrary tokens are permitted. Example key: '{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json'. null value = 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" },
-              { "type": "null" }
-            ]
-          }
-        }
-      }
-    },
-    "action": {
-      "$ref": "#/$defs/action",
-      "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 or lifecycle events with per-step assertions — use for multi-step scenarios; mutually exclusive with action and event",
-      "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"
-        }
-      }
-    },
-    "event": {
-      "type": "object",
-      "description": "A lifecycle event that triggers harness-level behavior without a direct tool call. Used for verifying agent-tracker.json state changes.",
-      "additionalProperties": false,
-      "required": ["type"],
-      "properties": {
-        "type": {
-          "type": "string",
-          "enum": ["agent_spawn", "agent_complete", "agent_resume", "session_end"],
-          "description": "Lifecycle event type. agent_spawn/agent_complete/agent_resume: agent instance lifecycle. session_end: session teardown — agent-tracker.json deleted, history/memory/context/rules preserved."
-        },
-        "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",
-      "additionalProperties": false,
-      "properties": {
-        "state_files": {
-          "type": "object",
-          "description": "Map of file path to assertion object. File path keys may contain placeholder tokens that a conformance runner must expand before resolving paths. Allowed tokens: {STATE_ROOT} and {HARNESS_ID} only — no other arbitrary tokens are permitted. See precondition.state_files for token semantics. 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": [
-              {
-                "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. Each step must contain exactly one of: action (tool invocation) or event (lifecycle event).",
-      "additionalProperties": false,
-      "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",
-          "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 to 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

@@ -1,63 +0,0 @@
-{
-  "$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. 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": ["harness_id", "started_at"],
-    "properties": {
-      "harness_id": {
-        "type": "string",
-        "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",
-        "minLength": 1,
-        "description": "Harness-specific opaque agent instance identifier. Format is defined by the writing harness (UUID, composite string, etc.). Consumers MUST treat the value as opaque — do not parse or infer agent identity across harness namespaces."
-      },
-      "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"
-      }
-    }
-  }
-}