@moreih29/nexus-core 0.4.0 → 0.6.0

package/conformance/README.md

@@ -105,18 +105,16 @@ Each fixture must contain exactly one of: `action` (single tool invocation), `ev
 
 ## Event-based (Lifecycle) Fixtures
 
-일부 state 파일(`runtime.json`, `agent-tracker.json`)은 MCP tool이 아니라 harness의 session hook이 관리한다. 이 파일들의 구조적 정확성을 검증하기 위해 `action` 대신 `event` 필드를 사용하는 lifecycle fixture를 사용한다.
+`agent-tracker.json`은 MCP tool이 아니라 harness의 session hook이 관리한다. 이 파일의 구조적 정확성을 검증하기 위해 `action` 대신 `event` 필드를 사용하는 lifecycle fixture를 사용한다.
 
 Event fixture는 "harness가 특정 event를 실행한 후 state 파일의 구조가 올바른가"를 선언적으로 명세한다. Tool invocation 없이 event 트리거만으로 postcondition을 검증한다.
 
 ### Event types
 
-`event.type`은 다음 5종 중 하나여야 한다:
+`event.type`은 다음 3종 중 하나여야 한다:
 
 | Event type | 책임 범위 |
 |---|---|
-| `session_start` | `runtime.json` 초기화, `agent-tracker.json` 빈 배열 생성 |
-| `session_end` | `runtime.json` 삭제, `agent-tracker.json` 삭제 |
 | `agent_spawn` | `agent-tracker.json`에 신규 항목 생성 (running 상태) |
 | `agent_complete` | `agent-tracker.json` 항목을 완료 상태로 전환 |
 | `agent_resume` | `agent-tracker.json` 재개 카운터 증가 및 상태 복귀 |
@@ -125,20 +123,20 @@ Event fixture는 "harness가 특정 event를 실행한 후 state 파일의 구
 
 ```json
 {
-  "test_id": "session_start_creates_runtime",
+  "test_id": "agent_spawn_creates_entry",
   "description": "...",
   "covers": {
     "state_schemas": {
-      "runtime.schema.json": ["teams_enabled", "active_plan_id"]
+      "agent-tracker.schema.json": ["harness_id", "agent_name", "agent_id", "status"]
     }
   },
   "event": {
-    "type": "session_start",
+    "type": "agent_spawn",
     "params": { ... }
   },
   "postcondition": {
     "state_files": {
-      ".nexus/state/runtime.json": { "$.teams_enabled": false }
+      ".nexus/state/agent-tracker.json": { "$[0].status": "running" }
     }
   }
 }
@@ -146,12 +144,10 @@ Event fixture는 "harness가 특정 event를 실행한 후 state 파일의 구
 
 ### Lifecycle fixture 목록
 
-`conformance/lifecycle/` 디렉토리에 5개 파일이 존재한다:
+`conformance/lifecycle/` 디렉토리에 3개 파일이 존재한다:
 
 | 파일 | Event type | 검증 대상 |
 |---|---|---|
-| `session-start.json` | `session_start` | `runtime.json` 초기화, `agent-tracker.json` 빈 배열 |
-| `session-end.json` | `session_end` | `runtime.json` 삭제, `agent-tracker.json` 삭제 |
 | `agent-spawn.json` | `agent_spawn` | `agent-tracker.json` 첫 항목 생성 (running 상태) |
 | `agent-complete.json` | `agent_complete` | `agent-tracker.json` 항목 완료 상태 전환 |
 | `agent-resume.json` | `agent_resume` | `agent-tracker.json` 재개 카운터 및 상태 복귀 |
@@ -170,6 +166,7 @@ Assertions are key/value objects where keys are JSONPath expressions and values
 | `"$.field": { "type": "number", "min": 1 }` | Numeric value >= 1 |
 | `"$.field": { "type": "string", "minLength": 5 }` | String with minimum length |
 | `".nexus/state/plan.json": null` | File must not exist |
+| `".nexus/state/artifacts/findings.md": {}` | File must exist; content not inspected (use for non-JSON artifacts like .md, .txt, binary files) |
 
 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`.
 
@@ -240,7 +237,10 @@ A conformance test runner does the following for each fixture:
    - 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.
 4. **Evaluate postconditions**:
    - Check `postcondition.return_value` assertions against the tool's return value.
-   - Check `postcondition.state_files` assertions against the actual file system state.
+   - Check `postcondition.state_files` assertions against the actual file system state. For each entry in `state_files`:
+     - Value is `null` → assert the file does NOT exist.
+     - Value is an empty object `{}` → assert the file EXISTS; do NOT parse content (use for non-JSON artifacts: .md, .txt, binary).
+     - Value is a non-empty object `{...}` → parse file as JSON and evaluate each JSONPath assertion against the parsed content.
    - If `postcondition.error` is `true`, the tool call must have produced an error.
    - If `postcondition.error_contains` is set, the error message must contain that substring.
 5. **Report** pass/fail per `test_id`.
@@ -277,29 +277,26 @@ for (const fixture of fixtures) {
 | `context` | Read or write .nexus/context/ knowledge files | `tools/context.json` |
 | `artifact_write` | Write an artifact output file | `tools/artifact-write.json` |
 
-### Lifecycle events (5/5 커버됨)
+### Lifecycle events (3/3 커버됨)
 
 | Event type | Fixture file |
 |---|---|
-| `session_start` | `lifecycle/session-start.json` |
-| `session_end` | `lifecycle/session-end.json` |
 | `agent_spawn` | `lifecycle/agent-spawn.json` |
 | `agent_complete` | `lifecycle/agent-complete.json` |
 | `agent_resume` | `lifecycle/agent-resume.json` |
 
 ### State-schema field coverage
 
-5개 state-schema의 모든 필드가 100% 커버된다:
+4개 state-schema의 모든 필드가 100% 커버된다:
 
 | Schema | 검증 도구 |
 |---|---|
 | `plan.schema.json` | `tools/plan-*.json` fixtures |
 | `tasks.schema.json` | `tools/task-*.json` fixtures |
 | `history.schema.json` | `tools/history-search.json`, `tools/task-close.json` |
-| `runtime.schema.json` | `lifecycle/session-*.json` fixtures |
 | `agent-tracker.schema.json` | `lifecycle/agent-*.json` fixtures |
 
-현재 validator 통과 결과: `✓ All state-schema fields covered: 5 schemas, 54 fields across 48 fixtures`
+Validator 통과 결과 예시: `✓ All state-schema fields covered: 4 schemas across fixture suite`
 
 ## Excluded tools
 

package/conformance/examples/plan.extension.schema.example.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "conformance/examples/plan.extension.schema.example.json",
+  "title": "Example: Harness-local plan state extension",
+  "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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["extends"],
+  "properties": {
+    "extends": {
+      "type": "string",
+      "const": "conformance/state-schemas/plan.schema.json",
+      "description": "Reference to the parent common-schema this extension supplements"
+    },
+    "harness_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Identifier of the harness that produced this extension file"
+    },
+    "harness_specific_field_example": {
+      "type": "string",
+      "description": "Placeholder — replace with your harness's actual extension fields as needed"
+    }
+  }
+}

package/conformance/lifecycle/README.md

@@ -6,12 +6,10 @@
 
 | Fixture | Event Type | 검증 대상 |
 |---|---|---|
-| `session-start.json` | `session_start` | `runtime.json` 초기화, `agent-tracker.json` 빈 배열 |
-| `session-end.json` | `session_end` | `runtime.json` 삭제, `agent-tracker.json` 삭제 |
 | `agent-spawn.json` | `agent_spawn` | `agent-tracker.json` 첫 항목 생성 (running 상태) |
 | `agent-complete.json` | `agent_complete` | `agent-tracker.json` 항목 완료 상태 전환 |
 | `agent-resume.json` | `agent_resume` | `agent-tracker.json` 재개 카운터 및 상태 복귀 |
 
 ## Tool-action 대신 Event 트리거 사용
 
-각 fixture는 `action` (tool invocation) 대신 `event` 필드를 사용한다. `runtime.json`과 `agent-tracker.json`은 harness의 session hook이 관리하며, MCP tool이 직접 쓰지 않는다. Event fixture는 "harness가 event를 실행한 후 state 파일의 구조가 올바른가"를 선언적으로 명세한다.
+각 fixture는 `action` (tool invocation) 대신 `event` 필드를 사용한다. `agent-tracker.json`은 harness의 session hook이 관리하며, MCP tool이 직접 쓰지 않는다. Event fixture는 "harness가 event를 실행한 후 state 파일의 구조가 올바른가"를 선언적으로 명세한다.

package/conformance/lifecycle/agent-complete.json

@@ -5,7 +5,8 @@
     "state_files": {
       ".nexus/state/agent-tracker.json": [
         {
-          "agent_type": "claude-nexus:engineer",
+          "harness_id": "claude-nexus",
+          "agent_name": "architect",
           "agent_id": "uuid-eng01",
           "started_at": "2026-04-13T00:00:00.000Z",
           "resume_count": 0,

package/conformance/lifecycle/agent-resume.json

@@ -5,7 +5,8 @@
     "state_files": {
       ".nexus/state/agent-tracker.json": [
         {
-          "agent_type": "claude-nexus:engineer",
+          "harness_id": "claude-nexus",
+          "agent_name": "architect",
           "agent_id": "uuid-eng01",
           "started_at": "2026-04-13T00:00:00.000Z",
           "resume_count": 0,

package/conformance/lifecycle/agent-spawn.json

@@ -3,18 +3,14 @@
   "description": "Verifies that agent_spawn appends a new running agent entry to agent-tracker.json with required fields initialized correctly",
   "precondition": {
     "state_files": {
-      ".nexus/state/runtime.json": {
-        "teams_enabled": true,
-        "session_started_at": "2026-04-13T00:00:00.000Z",
-        "plugin_version": "0.4.0"
-      },
       ".nexus/state/agent-tracker.json": []
     }
   },
   "event": {
     "type": "agent_spawn",
     "params": {
-      "agent_type": "claude-nexus:engineer",
+      "harness_id": "claude-nexus",
+      "agent_name": "architect",
       "agent_id": "uuid-eng01"
     },
     "description": "Harness spawns an agent instance and records its initial state in the agent registry"
@@ -23,7 +19,8 @@
     "state_files": {
       ".nexus/state/agent-tracker.json": {
         "$.length": 1,
-        "$[0].agent_type": "claude-nexus:engineer",
+        "$[0].harness_id": "claude-nexus",
+        "$[0].agent_name": "architect",
         "$[0].agent_id": "uuid-eng01",
         "$[0].started_at": { "type": "iso8601" },
         "$[0].resume_count": 0,
@@ -33,7 +30,7 @@
   },
   "covers": {
     "state_schemas": {
-      "agent-tracker.schema.json": ["agent_type", "agent_id", "started_at", "resume_count", "status"]
+      "agent-tracker.schema.json": ["harness_id", "agent_name", "agent_id", "started_at", "resume_count", "status"]
     }
   }
 }

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

@@ -15,7 +15,7 @@
     },
     "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", "summary", "title", "context", "deps"],
+  "uncovered_params": ["research_summary", "issue_id", "decision", "title", "context", "deps"],
   "precondition": {
     "state_files": {
       ".nexus/state/plan.json": null,
@@ -56,7 +56,7 @@
         "tool": "plan_decide",
         "params": {
           "issue_id": 1,
-          "summary": "Keep .nexus/state/ as the canonical location. Documented in state-schemas README."
+          "decision": "Keep .nexus/state/ as the canonical location. Documented in state-schemas README."
         }
       },
       "assert_return": {
@@ -78,7 +78,7 @@
         "tool": "plan_decide",
         "params": {
           "issue_id": 2,
-          "summary": "Ship a one-shot migration script as a standalone npm script. Document in RELEASING.md."
+          "decision": "Ship a one-shot migration script as a standalone npm script. Document in RELEASING.md."
         }
       },
       "assert_return": {

package/conformance/schema/fixture.schema.json

@@ -112,7 +112,7 @@
       "properties": {
         "state_files": {
           "type": "object",
-          "description": "Map of file path to 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" },
@@ -160,18 +160,18 @@
     },
     "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.",
+      "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": ["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."
+          "enum": ["agent_spawn", "agent_complete", "agent_resume"],
+          "description": "Lifecycle event type. agent_spawn/agent_complete/agent_resume: agent instance lifecycle."
         },
         "params": {
           "type": "object",
-          "description": "Optional event-specific parameters (e.g. agent_type and agent_id for agent_spawn)",
+          "description": "Optional event-specific parameters (e.g. harness_id, agent_name, and agent_id for agent_spawn)",
           "additionalProperties": true
         },
         "description": {
@@ -187,7 +187,7 @@
       "properties": {
         "state_files": {
           "type": "object",
-          "description": "Map of file path to 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": [
               {

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/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/plan-decide.json

@@ -1,7 +1,7 @@
 [
   {
     "test_id": "plan_decide_happy_path",
-    "description": "plan_decide marks an issue as decided and records the decision summary on the issue object",
+    "description": "plan_decide marks an issue as decided and records the decision text on the issue object",
     "covers": {
       "state_schemas": {
         "plan.schema.json": ["issues[].status", "issues[].decision"]
@@ -10,7 +10,7 @@
         "plan_decide": ["decided", "allComplete", "remaining"]
       }
     },
-    "uncovered_params": ["issue_id", "summary"],
+    "uncovered_params": ["issue_id", "decision"],
     "precondition": {
       "state_files": {
         ".nexus/state/plan.json": {
@@ -37,7 +37,7 @@
       "tool": "plan_decide",
       "params": {
         "issue_id": 1,
-        "summary": "Use declarative JSON with JSONPath assertions. Harness-neutral tool names only."
+        "decision": "Use declarative JSON with JSONPath assertions. Harness-neutral tool names only."
       }
     },
     "postcondition": {
@@ -63,7 +63,7 @@
         "plan.schema.json": []
       }
     },
-    "uncovered_params": ["issue_id", "summary"],
+    "uncovered_params": ["issue_id", "decision"],
     "precondition": {
       "state_files": {
         ".nexus/state/plan.json": null
@@ -73,7 +73,7 @@
       "tool": "plan_decide",
       "params": {
         "issue_id": 1,
-        "summary": "Some decision"
+        "decision": "Some decision"
       }
     },
     "postcondition": {
@@ -90,7 +90,7 @@
         "plan.schema.json": ["issues[].how_agents", "issues[].how_agents[]", "issues[].how_summary", "issues[].how_agent_ids"]
       }
     },
-    "uncovered_params": ["issue_id"],
+    "uncovered_params": ["issue_id", "decision"],
     "precondition": {
       "state_files": {
         ".nexus/state/plan.json": {
@@ -112,7 +112,7 @@
       "tool": "plan_decide",
       "params": {
         "issue_id": 1,
-        "summary": "Declarative JSON with JSONPath assertions, harness-neutral.",
+        "decision": "Declarative JSON with JSONPath assertions, harness-neutral.",
         "how_agents": ["architect", "postdoc"],
         "how_summary": {
           "architect": "JSONPath assertions provide harness-agnostic verifiability.",

package/conformance/tools/plan-start.json

@@ -4,7 +4,7 @@
     "description": "plan_start creates plan.json with correct structure when given a topic, issues, and research_summary",
     "covers": {
       "state_schemas": {
-        "plan.schema.json": ["id", "topic", "issues[].id", "issues[].title", "issues[].status", "research_summary", "created_at"]
+        "plan.schema.json": ["schema_version", "id", "topic", "issues[].id", "issues[].title", "issues[].status", "research_summary", "created_at"]
       },
       "return_value": {
         "plan_start": ["created", "plan_id", "topic", "issueCount"]

package/conformance/tools/task-add.json

@@ -4,7 +4,7 @@
     "description": "task_add creates tasks.json with the new task when no tasks.json existed, assigning id=1 and status=pending",
     "covers": {
       "state_schemas": {
-        "tasks.schema.json": ["tasks[].id", "tasks[].title", "tasks[].status", "tasks[].deps", "tasks[].approach", "tasks[].acceptance", "tasks[].risk", "tasks[].context", "tasks[].created_at"]
+        "tasks.schema.json": ["schema_version", "tasks[].id", "tasks[].title", "tasks[].status", "tasks[].deps", "tasks[].approach", "tasks[].acceptance", "tasks[].risk", "tasks[].context", "tasks[].created_at"]
       },
       "return_value": {
         "task_add": ["task"]

package/conformance/tools/task-close.json

@@ -5,6 +5,8 @@
     "covers": {
       "state_schemas": {
         "history.schema.json": [
+          "schema_version",
+          "cycles[].schema_version",
           "cycles[].completed_at",
           "cycles[].branch",
           "cycles[].plan",

package/docs/consumer-implementation-guide.md

@@ -97,7 +97,7 @@ A complete Nexus consumer comprises nine components. They have hard dependencies
 | # | Component | Description |
 |---|-----------|-------------|
 | 1 | `.nexus/` Directory Initialization | Create the required directory tree and `.gitignore` at session start |
-| 2 | State File Management | Read/write plan.json, tasks.json, history.json, runtime.json, agent-tracker.json |
+| 2 | State File Management | Read/write plan.json, tasks.json, history.json, agent-tracker.json |
 | 3 | MCP Tool Implementation | Concrete implementations of the 11 abstract Nexus tools |
 | 4 | Capability Mapping | Local file translating abstract capability IDs to concrete disallowed tools |
 | 5 | Agent Catalog | Load nexus-core agents, apply capability-map, register with harness |
@@ -159,7 +159,6 @@ Nexus state is split into two categories with different scopes, persistence, and
 ├── state/                    ← session-scoped (not git-tracked)
 │   ├── plan.json
 │   ├── tasks.json
-│   ├── runtime.json
 │   ├── agent-tracker.json
 │   ├── tool-log.jsonl
 │   ├── edit-tracker.json
@@ -182,9 +181,8 @@ At session start, your harness must:
 1. Create `.nexus/` if it does not exist.
 2. Create `.nexus/state/` if it does not exist.
 3. Write `.nexus/.gitignore` with content `state/` if the file does not exist.
-4. Write `.nexus/state/runtime.json` with session metadata (session ID, harness version, start timestamp).
-5. Initialize `.nexus/state/agent-tracker.json` as an empty array `[]`.
-6. Check for stale state files from a prior crashed session. If `plan.json` or `tasks.json` exist without a running session, warn the user that a previous session may not have closed cleanly.
+4. Initialize `.nexus/state/agent-tracker.json` as an empty array `[]`.
+5. Check for stale state files from a prior crashed session. If `plan.json` or `tasks.json` exist without a running session, warn the user that a previous session may not have closed cleanly.
 
 ### Key state files
 
@@ -192,7 +190,6 @@ At session start, your harness must:
 |------|-------|------------|------------|------------|
 | `state/plan.json` | Session | No | `plan_start` tool | `task_close` tool |
 | `state/tasks.json` | Session | No | `task_add` tool (first call) | `task_close` tool |
-| `state/runtime.json` | Session | No | session_start hook | session_end hook |
 | `state/agent-tracker.json` | Session | No | session_start hook | session_end hook |
 | `state/tool-log.jsonl` | Session | No | post_tool_use hook | session_end hook |
 | `state/edit-tracker.json` | Session | No | post_tool_use hook (first edit) | task_close / session_end |
@@ -200,7 +197,7 @@ At session start, your harness must:
 
 ### Schema validation
 
-JSON Schema definitions for all state files are available in `conformance/state-schemas/`. The schemas cover `plan.json`, `tasks.json`, `history.json`, `runtime.json`, and `agent-tracker.json`. Validate state files against these schemas in your test suite.
+JSON Schema definitions for all state files are available in `conformance/state-schemas/`. The schemas cover `plan.json`, `tasks.json`, `history.json`, and `agent-tracker.json`. Validate state files against these schemas in your test suite.
 
 For full lifecycle and tool access details, see [nexus-state-overview.md](./nexus-state-overview.md) and [nexus-layout.md](./nexus-layout.md).
 
@@ -526,7 +523,6 @@ Identify the equivalent events in your harness's plugin system and implement the
 **Expected consumer behavior:**
 - Create `.nexus/` and `.nexus/state/` directories if they do not exist.
 - Write `.nexus/.gitignore` with `state/` if it does not exist.
-- Write `.nexus/state/runtime.json` with session metadata: session ID, harness version, start timestamp, and any environment properties your harness tracks.
 - Initialize `.nexus/state/agent-tracker.json` as `[]`.
 - Check for stale state from a prior crashed session: if `plan.json` or `tasks.json` exist, warn the user that these may be leftover from an unclean shutdown.
 - Load the knowledge index: list files in `.nexus/memory/`, `.nexus/context/`, and `.nexus/rules/` to build the reference index that will be injected into subagent spawns.
@@ -555,7 +551,7 @@ Identify the equivalent events in your harness's plugin system and implement the
 **When it fires:** Lead spawns a subagent to execute a task.
 
 **Expected consumer behavior:**
-- Record the new agent entry in `agent-tracker.json`: `{ agent_type, agent_id, task_id, started_at }`.
+- Record the new agent entry in `agent-tracker.json`: `{ harness_id, agent_name, agent_id, task_id, started_at }`.
 - Inject the knowledge index into the subagent's initial context: the list of files in `.nexus/memory/`, `.nexus/context/`, and `.nexus/rules/` so the agent knows what project knowledge is available.
 - Apply capability restrictions: resolve `effective_capabilities` for this agent type and configure the subagent's tool access accordingly (see §6).
 - Apply the resume evaluation: check `owner_reuse_policy` on the task and the agent's `resume_tier` to determine whether to spawn fresh or resume a prior session (see §10).
@@ -607,7 +603,7 @@ Read-only tools (query tools, status reads) are never blocked by capability gate
 **Expected consumer behavior:**
 - Check for pending tasks: if `tasks.json` exists and contains incomplete tasks (status `pending` or `in_progress`), warn the user that the session is ending with unfinished work and suggest calling `task_close` to archive before exiting.
 - Check for an active plan: if `plan.json` exists, warn that the plan session will be lost if not archived.
-- Delete `runtime.json` and `agent-tracker.json` (session-scoped files that have no value beyond the session).
+- Delete `agent-tracker.json` (a session-scoped file that has no value beyond the session).
 - Optionally rotate or archive `tool-log.jsonl` if your harness supports log retention.
 - Do not delete `history.json`, `memory/`, `context/`, or `rules/` — these are project-scoped and must persist.
 
@@ -807,7 +803,7 @@ Implement tag detection in your `user_message` hook. When `[plan]` is detected,
 
 | Event | Minimum required behavior |
 |-------|--------------------------|
-| `session_start` | Create `.nexus/state/` directory; write `runtime.json`; initialize `agent-tracker.json` as `[]` |
+| `session_start` | Create `.nexus/state/` directory; initialize `agent-tracker.json` as `[]` |
 | `user_message` | Detect `[plan]` tag; load `skills/nx-plan/body.md`; inject into Lead's context |
 | `session_end` | Check for `tasks.json`; if present with incomplete tasks, warn the user |
 

package/docs/nexus-layout.md

@@ -11,7 +11,6 @@ This document is the canonical reference for the `.nexus/` directory structure u
 ├── state/                    ← session/branch-scoped (ephemeral)
 │   ├── plan.json
 │   ├── tasks.json
-│   ├── runtime.json
 │   ├── agent-tracker.json
 │   ├── tool-log.jsonl
 │   ├── edit-tracker.json
@@ -73,20 +72,6 @@ This document is the canonical reference for the `.nexus/` directory structure u
 
 ---
 
-#### `state/runtime.json`
-
-**Purpose.** Harness-internal session state that does not belong in plan or task records (e.g., active agent registrations, session-level flags).
-
-**Scope.** Session-scoped.
-
-**Git tracking.** Ignored.
-
-**Lifecycle.** Created at session start. Discarded at session end.
-
-**Owner.** Harness runtime.
-
----
-
 #### `state/agent-tracker.json`
 
 **Purpose.** Records which subagents have been spawned in the current session, their assigned tasks, and their resume-tier classification.