@moreih29/nexus-core 0.8.0 → 0.9.0

package/docs/consumer-implementation-guide.md

@@ -160,8 +160,6 @@ Nexus state is split into two categories with different scopes, persistence, and
 │   ├── plan.json
 │   ├── tasks.json
 │   ├── tool-log.jsonl
-│   ├── edit-tracker.json
-│   ├── reopen-tracker.json
 │   ├── artifacts/
 │   └── {harness-id}/         ← harness namespace (see §Harness-local State Extension)
 │       └── agent-tracker.json
@@ -193,7 +191,6 @@ At session start, your harness must:
 | `state/tasks.json` | Session | No | `task_add` tool (first call) | `task_close` tool |
 | `state/{harness-id}/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 |
 | `history.json` | Project | Yes | `plan_start` or `task_close` (first archive) | Never |
 
 ### Schema validation
@@ -235,7 +232,7 @@ For every tool, implement exactly the parameter schema, return shape, and side e
 Specific requirements to enforce:
 
 - `plan_start`: when a prior `plan.json` exists, archive it to `history.json` before creating the new session. Failure to archive on replace will cause data loss.
-- `task_close`: delete `plan.json`, `tasks.json`, `edit-tracker.json`, and `reopen-tracker.json` after archiving. Leaving these files causes stale state on next session.
+- `task_close`: delete `plan.json` and `tasks.json` after archiving. Leaving these files causes stale state on next session. Files such as `edit-tracker.json` and `reopen-tracker.json` are harness-local concerns and are not managed by `task_close`; delete them in your session_end hook if your harness maintains them.
 - `artifact_write`: create `.nexus/state/artifacts/` on demand if it does not exist. Do not require the directory to pre-exist.
 - `context`: return `{ active: false }` (for plan_status) or `{ exists: false }` (for task_list) when the relevant state file is absent. Do not return an error.
 
@@ -567,8 +564,8 @@ Identify the equivalent events in your harness's plugin system and implement the
 
 **Expected consumer behavior:**
 - Update `.nexus/state/{harness-id}/agent-tracker.json`: set `status=completed`, record `stopped_at` timestamp.
-- Compute `files_touched` from your tool-log or the subagent's tool usage record. Record which files were created or modified.
-- Update `edit-tracker.json` with the files touched by this agent. This data feeds the bounded-tier resume evaluation on subsequent spawns.
+- Compute `files_touched` from your tool-log or the subagent's tool usage record. Record which files were created or modified in the `files_touched` array of the agent's `agent-tracker.json` entry. This field is the authoritative source for bounded-tier resume evaluation.
+- (Optional, harness-local) If your harness maintains a separate `edit-tracker.json` for cross-session file-touch history, update it here. This is not a nexus-core requirement; it is a harness-local optimization.
 - Check if the completed task has pending acceptance criteria that were not verified. If the task has `acceptance` defined and no `tester` or `reviewer` subagent has been scheduled, surface a reminder to Lead.
 - Update the task status in `tasks.json` via the `task_update` tool: set to `completed`.
 
@@ -593,7 +590,7 @@ Read-only tools (query tools, status reads) are never blocked by capability gate
 
 **Expected consumer behavior:**
 - Append a log entry to `.nexus/state/tool-log.jsonl`: timestamp, agent_id, tool name, file path (if a file was touched), result status.
-- If the tool was a file-editing tool, update `edit-tracker.json`: record the file path and the agent_id that modified it. This is the data source for bounded-tier resume evaluation.
+- (Optional, harness-local) If your harness maintains `edit-tracker.json`, record the file path and agent_id here. This is a harness-local optimization and is not required by nexus-core. The `files_touched` array in `agent-tracker.json` is the nexus-core-defined record of which files an agent touched.
 - If the tool result indicates an error, record the error in the log for diagnostic purposes. Do not suppress error results.
 
 ---
@@ -704,8 +701,8 @@ Before attempting to resume, verify that your harness supports the resume mechan
 
 For `bounded` agents evaluating resume eligibility:
 - Check `.nexus/state/{harness-id}/agent-tracker.json` for the prior agent ID assigned to this task.
-- Check `edit-tracker.json` to determine if any other agent has modified the target files since the last session.
-- If any intervening edit is found, use a fresh spawn regardless of `owner_reuse_policy`.
+- Scan the `files_touched` arrays of all other completed agents in `agent-tracker.json`. If any other agent has touched the same target files since the last session, treat that as an intervening edit and use a fresh spawn regardless of `owner_reuse_policy`. The `files_touched` field is defined in `state-schemas/agent-tracker.schema.json` and is the nexus-core-defined source for this check.
+- If your harness additionally maintains `edit-tracker.json` for finer-grained cross-session tracking, you may consult it as a supplemental heuristic, but it is not required by nexus-core.
 
 Full resume tier definitions are in [behavioral-contracts.md §3](./behavioral-contracts.md).
 
@@ -807,7 +804,7 @@ Implement tag detection in your `user_message` hook. When `[plan]` is detected,
 |-------|--------------------------|
 | `session_start` | Create `.nexus/state/{harness-id}/` 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 |
+| `session_end` | Check for `tasks.json`; if present with incomplete tasks, warn the user. If the harness maintains local tracker files (e.g. `edit-tracker.json`, `reopen-tracker.json`), delete them here — see the `session_end` subsection in §9 for full details. |
 
 ### State files (3 minimum)
 

package/docs/nexus-layout.md

@@ -12,13 +12,15 @@ This document is the canonical reference for the `.nexus/` directory structure u
 │   ├── plan.json
 │   ├── tasks.json
 │   ├── tool-log.jsonl
-│   ├── edit-tracker.json
-│   ├── reopen-tracker.json
 │   ├── artifacts/
 │   ├── claude-nexus/         ← harness-namespaced directory (example)
-│   │   └── agent-tracker.json
+│   │   ├── agent-tracker.json
+│   │   ├── edit-tracker.json
+│   │   └── reopen-tracker.json
 │   └── opencode-nexus/       ← harness-namespaced directory (example)
-│       └── agent-tracker.json
+│       ├── agent-tracker.json
+│       ├── edit-tracker.json
+│       └── reopen-tracker.json
 ├── history.json              ← project-scoped (git-tracked, append-only)
 ├── memory/                   ← project-scoped (git-tracked)
 │   └── *.md
@@ -103,7 +105,7 @@ This document is the canonical reference for the `.nexus/` directory structure u
 
 ---
 
-#### `state/edit-tracker.json`
+#### `state/{harness-id}/edit-tracker.json`
 
 **Purpose.** Tracks which files have been edited in the current session. Used by the bounded resume tier to detect intervening edits before allowing agent reuse.
 
@@ -111,13 +113,13 @@ This document is the canonical reference for the `.nexus/` directory structure u
 
 **Git tracking.** Ignored.
 
-**Lifecycle.** Created on first file edit. Cleared at session end.
+**Lifecycle.** Created on first file edit. Cleared at session end by the consumer harness session hook.
 
-**Owner.** Harness file-edit hooks.
+**Owner.** Consumer harness session hook. Not managed by any nexus-core MCP tool.
 
 ---
 
-#### `state/reopen-tracker.json`
+#### `state/{harness-id}/reopen-tracker.json`
 
 **Purpose.** Records tasks or plan issues that have been reopened within the current cycle, to prevent infinite reopen loops.
 
@@ -125,9 +127,9 @@ This document is the canonical reference for the `.nexus/` directory structure u
 
 **Git tracking.** Ignored.
 
-**Lifecycle.** Created on first reopen event. Cleared at cycle end.
+**Lifecycle.** Created on first reopen event. Cleared at cycle end by the consumer harness session hook.
 
-**Owner.** Task and plan lifecycle tools.
+**Owner.** Consumer harness session hook. Not managed by any nexus-core MCP tool.
 
 ---
 

package/docs/nexus-outputs-contract.md

@@ -101,8 +101,8 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 **Schema reference**: `conformance/state-schemas/agent-tracker.schema.json`
 
 **Interop requirement**:
-- 하네스는 `agent-tracker.json`을 기록할 때 MUST `conformance/state-schemas/agent-tracker.schema.json`에 유효한 JSON을 기록해야 한다.
-- MUST required 2 필드(`harness_id`, `started_at`)를 포함해야 한다.
+- 하네스는 `agent-tracker.json`을 기록할 때 MUST `conformance/state-schemas/agent-tracker.schema.json`에 유효한 JSON을 기록해야 한다. 파일의 top-level 구조는 배열(`[]`)이며 각 원소가 하나의 에이전트 인스턴스 entry이다.
+- 각 entry는 MUST required 2 필드(`harness_id`, `started_at`)를 포함해야 한다.
 - SHOULD cross-harness display/liveness를 위한 추가 필드(`agent_name`, `status`)를 제공한다.
 - `owner_agent_id`는 MUST harness-scoped opaque string으로 취급되어야 한다 — 다른 하네스의 `agent_id`를 parse하거나 추론하는 것은 MUST NOT 허용되어서는 안 된다. `agent_id`는 하네스별 내부 식별자이며 cross-harness 해석 대상이 아니다.
 - `agent-tracker.json`은 MUST NOT git-tracked 상태로 commit되어서는 안 된다.
@@ -195,7 +195,6 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 - **MUST NOT**: 다른 하네스의 namespace 디렉토리에 쓰거나 읽는다.
 - **MUST NOT**: `{harness-id}/` 하위에서 공통 schema 파일명(plan.json, tasks.json, history.json)을 재사용한다. 예: `.nexus/state/claude-nexus/plan.json` 금지.
 - **허용**: `.nexus/state/claude-nexus/agent-tracker.json` ✓ — shared-purpose file이며 §Shared filename convention에 등록된 첫 사례. 공통 schema 파일명 재사용 금지 규칙의 예외가 아니라, shared-purpose 유형으로 별도 분류된다.
-- **예외**: v0.3.x 이하에 루트 경로로 등록된 legacy 2종(`edit-tracker.json`, `reopen-tracker.json`)은 `task_close` tool 계약에 묶여 있어 backward-compat으로 루트 유지 허용한다. 신규 파일에는 예외 편승 금지.
 
 ### Archive 정책
 
@@ -220,16 +219,14 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 │   ├── plan.extension.json            ← plan.json의 확장 (priority, estimated_effort 등)
 │   ├── tasks.extension.json
 │   ├── history.extension.json         ← 하네스 자체 archive
-│   ├── edit-tracker.json              ← 독립 파일
-│   ├── reopen-tracker.json            ← 독립 파일
+│   ├── edit-tracker.json              ← 하네스 독립 파일
+│   ├── reopen-tracker.json            ← 하네스 독립 파일
 │   └── tool-log.jsonl
 └── opencode-nexus/                    ← sibling 하네스 namespace 디렉토리
     ├── agent-tracker.json             ← shared-purpose file (동일 파일명, harness-local)
     └── ...
 ```
 
-(루트 레벨 `edit-tracker.json`/`reopen-tracker.json`은 legacy carve-out으로 v0.3.x 이하 호환 유지)
-
 ### Reference example
 
 `conformance/examples/plan.extension.schema.example.json`에 non-normative 참조 예시가 있다. 이 파일은 다음 요소를 보여준다:

package/docs/nexus-state-overview.md

@@ -102,7 +102,7 @@ The Nexus state layout is divided into two categories:
 
 **Purpose.** Tracks agent instance activity during the session — which agents were spawned, their instance IDs, and what artifacts they touched. Used by the harness to evaluate `owner_reuse_policy` on subsequent `task_add` calls and to support agent resume. Each harness writes its own file under a harness-specific subdirectory, keeping records isolated across harness namespaces.
 
-**Schema.** The file contains a JSON object. Required fields: `harness_id` (string, identifies the writing harness) and `started_at` (ISO 8601 timestamp of session start). The following fields are optional: `agent_id`, `tasks`, `artifacts`, and any harness-defined extension fields.
+**Schema.** The file contains a JSON array. Each entry is an object representing one spawned agent instance. Required fields per entry: `harness_id` (string, identifies the writing harness) and `started_at` (ISO 8601 timestamp when the agent instance was first started). The following fields are optional per entry: `agent_name`, `agent_id`, `last_resumed_at`, `resume_count`, `status`, `stopped_at`, `last_message`, and `files_touched`. Harness-defined extension fields are not permitted — `additionalProperties` is false per the schema.
 
 The `agent_id` field, when present, is a harness-specific opaque agent instance identifier. Its format is defined by the writing harness (for example, a UUID, a composite string, or another harness-native scheme). Consumers of this file treat the value as opaque — they do not parse it or infer agent identity across harness namespaces.
 

package/docs/nexus-tools-contract.md

@@ -326,13 +326,14 @@ None.
 | `total_cycles` | `number` | Total number of cycles in `history.json` after closure |
 | `memoryHint.taskCount` | `number` | Number of tasks in the closed cycle |
 | `memoryHint.decisionCount` | `number` | Number of decided issues in the closed cycle |
-| `memoryHint.hadLoopDetection` | `boolean` | `true` if the edit tracker recorded three or more edits to any single file during the cycle |
 | `memoryHint.cycleTopics` | `string[]` | Non-empty strings from `plan.topic` and `tasks.goal` |
 
 ### Side Effects
 
 - Appends a cycle record to `.nexus/history.json` (creating the file if absent). The record contains `completed_at`, `branch`, `plan` (full `PlanFile` or `null`), and `tasks` (full `Task[]`).
-- Deletes the following session-scoped files if they exist: `plan.json`, `tasks.json`, `edit-tracker.json`, `reopen-tracker.json` (all within `.nexus/state/`).
+- Deletes the following session-scoped files if they exist: `plan.json`, `tasks.json` (all within `.nexus/state/`).
+
+Harness-local tracker files (`edit-tracker.json`, `reopen-tracker.json`, and any other files under `.nexus/state/{harness-id}/`) are not managed by `task_close`. Their lifecycle is the responsibility of consumer harness session hooks.
 
 ### Error Conditions
 

package/manifest.json

@@ -1,6 +1,6 @@
 {
-  "nexus_core_version": "0.8.0",
-  "nexus_core_commit": "254efc7d8f4f52e45b548706dd42389fdb9801b2",
+  "nexus_core_version": "0.9.0",
+  "nexus_core_commit": "ff5fb5de66dc2bf5f45dfba141901ccca7eb48e9",
   "schema_contract_version": "2.0",
   "agents": [
     {
@@ -19,6 +19,22 @@
       "id": "architect",
       "body_hash": "sha256:85f9a3de419f32cdae284436eb1d902bff19a2230c50fe3068ffc642949a63b7"
     },
+    {
+      "name": "designer",
+      "description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
+      "task": "UI/UX design, interaction patterns, user experience",
+      "alias_ko": "디자이너",
+      "category": "how",
+      "resume_tier": "persistent",
+      "model_tier": "high",
+      "capabilities": [
+        "no_file_edit",
+        "no_task_create",
+        "no_task_update"
+      ],
+      "id": "designer",
+      "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
+    },
     {
       "name": "reviewer",
       "description": "Content verification — validates accuracy, checks facts, confirms grammar and format of non-code deliverables",
@@ -34,6 +50,20 @@
       "id": "reviewer",
       "body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
     },
+    {
+      "name": "engineer",
+      "description": "Implementation — writes code, debugs issues, follows specifications from Lead and architect",
+      "task": "Code implementation, edits, debugging",
+      "alias_ko": "엔지니어",
+      "category": "do",
+      "resume_tier": "bounded",
+      "model_tier": "standard",
+      "capabilities": [
+        "no_task_create"
+      ],
+      "id": "engineer",
+      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
+    },
     {
       "name": "strategist",
       "description": "Business strategy — evaluates market positioning, competitive landscape, and business viability of decisions",
@@ -50,22 +80,6 @@
       "id": "strategist",
       "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
     },
-    {
-      "name": "designer",
-      "description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
-      "task": "UI/UX design, interaction patterns, user experience",
-      "alias_ko": "디자이너",
-      "category": "how",
-      "resume_tier": "persistent",
-      "model_tier": "high",
-      "capabilities": [
-        "no_file_edit",
-        "no_task_create",
-        "no_task_update"
-      ],
-      "id": "designer",
-      "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
-    },
     {
       "name": "researcher",
       "description": "Independent investigation — conducts web searches, gathers evidence, and reports findings with citations",
@@ -81,20 +95,6 @@
       "id": "researcher",
       "body_hash": "sha256:fc79bafec05503327bd51a0b84b6e642d304bd79c45b78db6448b112793c143e"
     },
-    {
-      "name": "engineer",
-      "description": "Implementation — writes code, debugs issues, follows specifications from Lead and architect",
-      "task": "Code implementation, edits, debugging",
-      "alias_ko": "엔지니어",
-      "category": "do",
-      "resume_tier": "bounded",
-      "model_tier": "standard",
-      "capabilities": [
-        "no_task_create"
-      ],
-      "id": "engineer",
-      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
-    },
     {
       "name": "postdoc",
       "description": "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents",
@@ -142,6 +142,19 @@
     }
   ],
   "skills": [
+    {
+      "name": "nx-run",
+      "description": "Execution — user-directed agent composition.",
+      "summary": "Execution — user-directed agent composition",
+      "triggers": [
+        "run"
+      ],
+      "harness_docs_refs": [
+        "resume_invocation"
+      ],
+      "id": "nx-run",
+      "body_hash": "sha256:0e2c443efceeab4621709a85cd4e2ba50471d2e850680c655d776cbb62814549"
+    },
     {
       "name": "nx-init",
       "description": "Project onboarding — scan, mission, essentials, context generation",
@@ -176,19 +189,6 @@
       ],
       "id": "nx-plan",
       "body_hash": "sha256:cd7a5fd1815530be6ffad18358a1295d1f74ef8a24132e75b73522c106eb6ae5"
-    },
-    {
-      "name": "nx-run",
-      "description": "Execution — user-directed agent composition.",
-      "summary": "Execution — user-directed agent composition",
-      "triggers": [
-        "run"
-      ],
-      "harness_docs_refs": [
-        "resume_invocation"
-      ],
-      "id": "nx-run",
-      "body_hash": "sha256:0e2c443efceeab4621709a85cd4e2ba50471d2e850680c655d776cbb62814549"
     }
   ],
   "vocabulary": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moreih29/nexus-core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Nexus ecosystem Authoring layer — canonical prompts, neutral metadata, and vocabulary shared by Nexus harnesses",
   "license": "MIT",
   "repository": {