@moreih29/nexus-core 0.6.0 → 0.7.0

package/conformance/README.md

@@ -136,7 +136,7 @@ Event fixture는 "harness가 특정 event를 실행한 후 state 파일의 구
   },
   "postcondition": {
     "state_files": {
-      ".nexus/state/agent-tracker.json": { "$[0].status": "running" }
+      "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": { "$[0].status": "running" }
     }
   }
 }
@@ -167,6 +167,7 @@ Assertions are key/value objects where keys are JSONPath expressions and values
 | `"$.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) |
+| `"{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json"` | State file path with substitutable tokens. Test runner MUST substitute `{STATE_ROOT}` with `.nexus/state` and `{HARNESS_ID}` with the harness identifier (from `event.params.harness_id` or runner configuration) before applying assertions. Only `{STATE_ROOT}` and `{HARNESS_ID}` are recognized; arbitrary tokens are forbidden. |
 
 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`.
 
@@ -230,14 +231,14 @@ exit code 2는 파일 파싱 등 fatal error를 의미한다.
 A conformance test runner does the following for each fixture:
 
 1. **Load** the fixture JSON file.
-2. **Establish precondition**: for each entry in `precondition.state_files`, write the content object as JSON to the specified path, or delete the file if the value is `null`.
+2. **Establish precondition**: for each entry in `precondition.state_files`, write the content object as JSON to the specified path, or delete the file if the value is `null`. Before resolving any path, substitute placeholder tokens: replace `{STATE_ROOT}` with `.nexus/state` and `{HARNESS_ID}` with the harness identifier found in `event.params.harness_id` (for lifecycle fixtures) or runner configuration (for general fixtures). Only `{STATE_ROOT}` and `{HARNESS_ID}` are recognized tokens; treat any other `{…}` token in a path as an authoring error.
 3. **Execute**:
    - For single-action fixtures: call the tool named by `action.tool` with `action.params`.
    - For event fixtures: trigger the harness session hook for the event type specified by `event.type`, passing `event.params`.
    - 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. For each entry in `state_files`:
+   - Check `postcondition.state_files` assertions against the actual file system state. Apply the same `{STATE_ROOT}` / `{HARNESS_ID}` substitution to path keys before resolving (same rule as precondition). 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.

package/conformance/lifecycle/README.md

@@ -13,3 +13,30 @@
 ## Tool-action 대신 Event 트리거 사용
 
 각 fixture는 `action` (tool invocation) 대신 `event` 필드를 사용한다. `agent-tracker.json`은 harness의 session hook이 관리하며, MCP tool이 직접 쓰지 않는다. Event fixture는 "harness가 event를 실행한 후 state 파일의 구조가 올바른가"를 선언적으로 명세한다.
+
+## Placeholder token 경로
+
+이 lifecycle fixture 3종의 `precondition.state_files` 및 `postcondition.state_files` 키는 모두 placeholder token 형식을 사용한다:
+
+```
+{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json
+```
+
+Test runner는 이 키를 파일 시스템 경로로 해석하기 전에 다음 치환을 수행해야 한다:
+
+| Token | 치환 값 | 출처 |
+|---|---|---|
+| `{STATE_ROOT}` | `.nexus/state` | 고정 상수 |
+| `{HARNESS_ID}` | harness 식별자 (예: `claude-nexus`) | 해당 fixture의 `event.params.harness_id` |
+
+치환 규약:
+- `{STATE_ROOT}`와 `{HARNESS_ID}` 두 token만 인식된다. 그 외 `{…}` 형태의 token이 경로에 등장하면 authoring 오류로 처리한다.
+- 공통 파일 fixture (`plan-*`, `task-*`, `history-*`, `artifact-write`)는 하드코딩된 경로를 사용하며 이 token 규약이 적용되지 않는다. Token 경로는 lifecycle fixture 3종에만 적용된다.
+
+### Fixture별 경로 요약
+
+| Fixture | `event.params.harness_id` 예시 | 해석된 경로 |
+|---|---|---|
+| `agent-spawn.json` | `claude-nexus` | `.nexus/state/claude-nexus/agent-tracker.json` |
+| `agent-complete.json` | `claude-nexus` | `.nexus/state/claude-nexus/agent-tracker.json` |
+| `agent-resume.json` | `claude-nexus` | `.nexus/state/claude-nexus/agent-tracker.json` |

package/conformance/lifecycle/agent-complete.json

@@ -3,7 +3,7 @@
   "description": "Verifies that agent_complete transitions an agent to completed status and records stopped_at, last_message, and files_touched in agent-tracker.json",
   "precondition": {
     "state_files": {
-      ".nexus/state/agent-tracker.json": [
+      "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": [
         {
           "harness_id": "claude-nexus",
           "agent_name": "architect",
@@ -26,7 +26,7 @@
   },
   "postcondition": {
     "state_files": {
-      ".nexus/state/agent-tracker.json": {
+      "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": {
         "$.length": 1,
         "$[0].status": "completed",
         "$[0].stopped_at": { "type": "iso8601" },

package/conformance/lifecycle/agent-resume.json

@@ -3,7 +3,7 @@
   "description": "Verifies that agent_resume transitions a completed agent back to running status and increments resume_count and sets last_resumed_at",
   "precondition": {
     "state_files": {
-      ".nexus/state/agent-tracker.json": [
+      "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": [
         {
           "harness_id": "claude-nexus",
           "agent_name": "architect",
@@ -27,7 +27,7 @@
   },
   "postcondition": {
     "state_files": {
-      ".nexus/state/agent-tracker.json": {
+      "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": {
         "$.length": 1,
         "$[0].status": "running",
         "$[0].resume_count": 1,

package/conformance/lifecycle/agent-spawn.json

@@ -3,7 +3,7 @@
   "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/agent-tracker.json": []
+      "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": []
     }
   },
   "event": {
@@ -17,7 +17,7 @@
   },
   "postcondition": {
     "state_files": {
-      ".nexus/state/agent-tracker.json": {
+      "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": {
         "$.length": 1,
         "$[0].harness_id": "claude-nexus",
         "$[0].agent_name": "architect",

package/conformance/schema/fixture.schema.json

@@ -112,7 +112,7 @@
       "properties": {
         "state_files": {
           "type": "object",
-          "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).",
+          "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" },
@@ -187,7 +187,7 @@
       "properties": {
         "state_files": {
           "type": "object",
-          "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.",
+          "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": [
               {

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

@@ -7,7 +7,7 @@
   "items": {
     "type": "object",
     "additionalProperties": false,
-    "required": ["harness_id", "agent_name", "agent_id", "started_at", "resume_count", "status"],
+    "required": ["harness_id", "started_at"],
     "properties": {
       "harness_id": {
         "type": "string",
@@ -22,7 +22,7 @@
       "agent_id": {
         "type": "string",
         "minLength": 1,
-        "description": "Unique agent instance identifier (UUID)"
+        "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",

package/docs/consumer-implementation-guide.md

@@ -159,11 +159,12 @@ Nexus state is split into two categories with different scopes, persistence, and
 ├── state/                    ← session-scoped (not git-tracked)
 │   ├── plan.json
 │   ├── tasks.json
-│   ├── agent-tracker.json
 │   ├── tool-log.jsonl
 │   ├── edit-tracker.json
 │   ├── reopen-tracker.json
-│   └── artifacts/
+│   ├── artifacts/
+│   └── {harness-id}/         ← harness namespace (see §Harness-local State Extension)
+│       └── agent-tracker.json
 ├── history.json              ← project-scoped (git-tracked, append-only)
 ├── memory/                   ← project-scoped (git-tracked)
 │   └── *.md
@@ -181,7 +182,7 @@ 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. Initialize `.nexus/state/agent-tracker.json` as an empty array `[]`.
+4. Create `.nexus/state/{harness-id}/` if it does not exist, then initialize `.nexus/state/{harness-id}/agent-tracker.json` as an empty array `[]`. (`{harness-id}` is the last segment of your npm package name; see [nexus-outputs-contract.md §Shared filename convention](./nexus-outputs-contract.md) for the namespace convention.)
 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
@@ -190,7 +191,7 @@ 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/agent-tracker.json` | Session | No | session_start hook | session_end hook |
+| `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 |
@@ -523,7 +524,8 @@ 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.
-- Initialize `.nexus/state/agent-tracker.json` as `[]`.
+- Create `.nexus/state/{harness-id}/` if it does not exist, then initialize `.nexus/state/{harness-id}/agent-tracker.json` as `[]`. `agent-tracker.json` is a shared-purpose session file whose path is namespaced per harness to prevent cross-harness collisions (see [nexus-outputs-contract.md §Shared filename convention](./nexus-outputs-contract.md)).
+- On v0.7.0+, harnesses SHOULD silently remove any legacy `.nexus/state/agent-tracker.json` (root) at session start. The file is session-scoped and legacy records are safely discarded.
 - 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.
 
@@ -551,7 +553,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`: `{ harness_id, agent_name, agent_id, task_id, started_at }`.
+- Record the new agent entry in `.nexus/state/{harness-id}/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).
@@ -564,7 +566,7 @@ Identify the equivalent events in your harness's plugin system and implement the
 **When it fires:** A subagent finishes its assigned work and returns control to Lead.
 
 **Expected consumer behavior:**
-- Update `agent-tracker.json`: set `status=completed`, record `stopped_at` timestamp.
+- 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.
 - 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.
@@ -603,7 +605,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 `agent-tracker.json` (a session-scoped file that has no value beyond the session).
+- Delete `.nexus/state/{harness-id}/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.
 
@@ -619,7 +621,7 @@ Read-only tools (query tools, status reads) are never blocked by capability gate
   - Plan status: if `plan.json` exists, re-inject the issue list with pending/decided status.
   - Task progress: if `tasks.json` exists, re-inject the task list with status and ready-task set.
   - Knowledge file index: re-inject the list of files in `.nexus/memory/`, `.nexus/context/`, `.nexus/rules/`.
-  - Active agent list: re-inject which subagents are currently tracked in `agent-tracker.json`.
+  - Active agent list: re-inject which subagents are currently tracked in `.nexus/state/{harness-id}/agent-tracker.json`.
 - Context compaction is a context loss event. The LLM cannot reconstruct session state from its compressed context alone. Your consumer must restore state from the state files on disk.
 - Read state files fresh from disk — do not rely on in-memory caches that may also have been cleared.
 
@@ -701,7 +703,7 @@ Before spawning an agent, evaluate whether to spawn fresh or resume a prior sess
 Before attempting to resume, verify that your harness supports the resume mechanism for the current context. If the mechanism is unavailable (the harness cannot reopen a prior session, or no session ID was recorded for this agent), fall back to a fresh spawn silently. Do not surface a resume failure as an error to the user.
 
 For `bounded` agents evaluating resume eligibility:
-- Check `agent-tracker.json` for the prior agent ID assigned to this task.
+- 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`.
 
@@ -803,7 +805,7 @@ Implement tag detection in your `user_message` hook. When `[plan]` is detected,
 
 | Event | Minimum required behavior |
 |-------|--------------------------|
-| `session_start` | Create `.nexus/state/` directory; initialize `agent-tracker.json` as `[]` |
+| `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 |
 

package/docs/nexus-layout.md

@@ -11,11 +11,14 @@ This document is the canonical reference for the `.nexus/` directory structure u
 ├── state/                    ← session/branch-scoped (ephemeral)
 │   ├── plan.json
 │   ├── tasks.json
-│   ├── agent-tracker.json
 │   ├── tool-log.jsonl
 │   ├── edit-tracker.json
 │   ├── reopen-tracker.json
-│   └── artifacts/
+│   ├── artifacts/
+│   ├── claude-nexus/         ← harness-namespaced directory (example)
+│   │   └── agent-tracker.json
+│   └── opencode-nexus/       ← harness-namespaced directory (example)
+│       └── agent-tracker.json
 ├── history.json              ← project-scoped (git-tracked, append-only)
 ├── memory/                   ← project-scoped (git-tracked)
 │   └── *.md
@@ -72,15 +75,15 @@ This document is the canonical reference for the `.nexus/` directory structure u
 
 ---
 
-#### `state/agent-tracker.json`
+#### `state/{harness-id}/agent-tracker.json`
 
-**Purpose.** Records which subagents have been spawned in the current session, their assigned tasks, and their resume-tier classification.
+**Purpose.** Records which subagents have been spawned in the current session, their assigned tasks, and their resume-tier classification. Each harness writes into its own subdirectory under `state/` (for example, `state/claude-nexus/` or `state/opencode-nexus/`), keeping agent-tracker records isolated across harness namespaces.
 
 **Scope.** Session-scoped.
 
 **Git tracking.** Ignored.
 
-**Lifecycle.** Created when the first subagent is spawned. Cleared at session end.
+**Lifecycle.** Created when the first subagent is spawned in the session. The harness creates the `{harness-id}/` subdirectory if it does not already exist. Cleared at session end.
 
 **Owner.** Harness agent-management layer.
 

package/docs/nexus-outputs-contract.md

@@ -18,7 +18,7 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 | 카테고리 | 책임 주체 | 예시 파일 |
 |---|---|---|
 | Tool-produced | MCP tool 계약 (nexus-tools-contract.md 정의) | `plan.json`, `tasks.json`, `history.json` |
-| Harness-produced | Session hook (하네스 구현 책임) | `agent-tracker.json` |
+| Harness-produced | Session hook (하네스 구현 책임) | `.nexus/state/{harness-id}/agent-tracker.json` |
 | Agent-produced (ephemeral) | `artifact_write` 도구 (에이전트가 호출) | `artifacts/*.md` (등 임의 파일명) |
 
 카테고리 간 경계는 "누가 파일을 만드는가"로 정의된다. MCP tool이 직접 write하면 Tool-produced, 하네스 hook이 세션 초기화·종료 시 관리하면 Harness-produced, 에이전트가 `artifact_write`를 통해 기록하면 Agent-produced다.
@@ -90,6 +90,8 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 
 ### `agent-tracker.json` — 에이전트 인스턴스 추적
 
+**경로**: `.nexus/state/{harness-id}/agent-tracker.json`
+
 **책임 주체**: Session hook (하네스 구현 책임). 어떤 MCP tool도 이 파일에 직접 write해서는 안 된다.
 
 **생성 trigger**: 하네스는 세션 초기화 시 MUST `agent-tracker.json`을 생성해야 한다. 파일 구조는 세션 중 에이전트 인스턴스 spawn 정보를 기록할 수 있어야 한다.
@@ -100,11 +102,15 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 
 **Interop requirement**:
 - 하네스는 `agent-tracker.json`을 기록할 때 MUST `conformance/state-schemas/agent-tracker.schema.json`에 유효한 JSON을 기록해야 한다.
-- `task_add` 도구가 `owner_agent_id` 필드를 읽어 harness에 전달하는 방식으로 간접 연계된다. 하네스는 이 연계가 동작하도록 MUST `owner_agent_id` 기반 agent 재개 로직을 구현해야 한다.
+- 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되어서는 안 된다.
 
 **Conformance fixture reference**: 해당 없음. `agent-tracker.json`은 MCP tool behavioral fixture 범위 외에 있으며 하네스 session hook이 전적으로 책임진다.
 
+§Shared filename convention 섹션도 참조하라.
+
 ---
 
 ## Agent-produced 산출물 (ephemeral)
@@ -142,7 +148,7 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 
 4. **append-only ledger 보전**: `history.json`은 모든 하네스 간에 MUST append-only로 처리되어야 한다. 기존 cycle 레코드를 수정하거나 삭제하는 하네스는 cross-harness 호환성 보장 대상에서 제외된다.
 
-5. **session-scoped 파일 격리**: `plan.json`, `tasks.json`, `agent-tracker.json`, `artifacts/` 디렉토리는 MUST git-tracked 상태로 commit되어서는 안 된다. 이 파일들은 세션 범위에 속하며 프로젝트 영구 기록이 아니다. 하네스는 MUST `.gitignore`에 이 경로들을 포함해야 한다.
+5. **session-scoped 파일 격리**: `plan.json`, `tasks.json`, `{harness-id}/agent-tracker.json`, `artifacts/` 디렉토리는 MUST git-tracked 상태로 commit되어서는 안 된다. 이 파일들은 세션 범위에 속하며 프로젝트 영구 기록이 아니다. `agent-tracker.json`은 각 하네스의 namespace 하위(`{harness-id}/agent-tracker.json`)에 위치하지만 session-scoped 속성은 동일하게 적용된다. 하네스는 MUST `.gitignore`에 이 경로들을 포함해야 한다.
 
 6. **Tool 이름 참조 금지**: 산출물 파일 내용 안에 harness-specific tool 이름(하네스별 MCP prefix, 하네스별 도구 식별자 등)을 MUST NOT 기록해서는 안 된다. 산출물은 harness-neutral해야 한다.
 
@@ -152,13 +158,16 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 
 하네스가 nexus-core 공통 schema로 수렴되지 않는 자체 state 파일을 필요로 할 때의 normative 규약이다.
 
-### 3 파일 유형 분류
+### 4 파일 유형 분류
 
-| 유형 | 경로 패턴 | Schema 소유 | Lifecycle 책임 |
-|---|---|---|---|
-| 공통 state | `.nexus/state/{name}.json` | nexus-core `conformance/state-schemas/` | nexus-core MCP tool |
-| 하네스 extension | `.nexus/state/{harness-id}/{base}.extension.json` | 하네스 repo `state-schemas/` | 하네스 session hook |
-| 하네스 독립 파일 | `.nexus/state/{harness-id}/{any}.json` | 하네스 repo `state-schemas/` | 하네스 session hook |
+| 유형 | 경로 패턴 | Schema 소유 | Lifecycle 책임 | 예시 |
+|---|---|---|---|---|
+| 공통 state | `.nexus/state/{name}.json` | nexus-core `conformance/state-schemas/` | nexus-core MCP tool | `plan.json`, `tasks.json` |
+| shared-purpose 공통 state (harness-local) | `.nexus/state/{harness-id}/{shared-base}.json` | nexus-core `conformance/state-schemas/` | 하네스 session hook | `agent-tracker.json` |
+| 하네스 extension | `.nexus/state/{harness-id}/{base}.extension.json` | 하네스 repo `state-schemas/` | 하네스 session hook | `plan.extension.json` |
+| 하네스 독립 파일 | `.nexus/state/{harness-id}/{any}.json` | 하네스 repo `state-schemas/` | 하네스 session hook | `edit-tracker.json` |
+
+**shared-purpose 공통 state**는 두 개 이상의 하네스가 같은 목적으로 같은 파일명을 사용하되 각자의 harness-local namespace에 두는 파일 유형이다. nexus-core가 최소 공통 schema contract를 선언하고 각 하네스 session hook이 lifecycle 책임을 진다. §Shared filename convention 섹션이 이 유형의 normative 정의를 제공한다.
 
 ### Harness-id 식별 규약
 
@@ -185,7 +194,8 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 - **MUST**: 하네스 고유 파일(독립 파일 + extension)은 모두 `.nexus/state/{harness-id}/` 하위에만 배치한다.
 - **MUST NOT**: `.nexus/state/` 루트에 신규 하네스 파일을 추가한다.
 - **MUST NOT**: 다른 하네스의 namespace 디렉토리에 쓰거나 읽는다.
-- **MUST NOT**: `{harness-id}/` 하위에서 공통 schema 파일명(plan.json, tasks.json, history.json, agent-tracker.json)을 재사용한다. 예: `.nexus/state/claude-nexus/plan.json` 금지.
+- **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 정책
@@ -205,15 +215,18 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 .nexus/state/
 ├── plan.json                          ← 공통, strict
 ├── tasks.json
-├── agent-tracker.json
 ├── artifacts/
-└── claude-nexus/                      ← namespace 디렉토리
-    ├── plan.extension.json            ← plan.json의 확장 (priority, estimated_effort 등)
-    ├── tasks.extension.json
-    ├── history.extension.json         ← 하네스 자체 archive
-    ├── edit-tracker.json              ← 독립 파일
-    ├── reopen-tracker.json            ← 독립 파일
-    └── tool-log.jsonl
+├── claude-nexus/                      ← namespace 디렉토리
+│   ├── agent-tracker.json             ← shared-purpose file (§Shared filename convention)
+│   ├── plan.extension.json            ← plan.json의 확장 (priority, estimated_effort 등)
+│   ├── tasks.extension.json
+│   ├── history.extension.json         ← 하네스 자체 archive
+│   ├── 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 이하 호환 유지)
@@ -230,6 +243,44 @@ consumer는 이 파일을 starting point로 삼아 자신의 실제 extension
 
 ---
 
+## Shared filename convention
+
+이 섹션은 `rule:harness-state-namespace`가 참조하는 referred source다.
+
+### 정의
+
+**shared-purpose file**이란 두 개 이상의 하네스가 **같은 목적**(예: agent lifecycle tracking)을 위해 **같은 파일명**으로 **각자의 harness-local namespace**에 두는 파일이다. 공통 state(`plan.json`, `tasks.json`)와 달리 단일 공유 경로가 아니라 하네스별 namespace 하위에 각각 존재한다.
+
+nexus-core는 shared-purpose file에 대해 **최소 공통 schema contract**를 선언한다. 이 contract는 cross-harness aggregator(예: nexus-code의 Supervision UI)가 여러 하네스의 파일을 일관되게 읽을 수 있도록 보장한다.
+
+### 최소 공통 필드 contract
+
+| 레벨 | 필드 | 타입 / 패턴 | 설명 |
+|---|---|---|---|
+| MUST (required) | `harness_id` | string, pattern `^[a-z][a-z0-9-]*$` | 이 파일을 기록한 하네스 식별자 |
+| MUST (required) | `started_at` | string, ISO 8601 | 세션 시작 시각 |
+| SHOULD (recommended) | `agent_name` | string | cross-harness display를 위한 에이전트 표시명 |
+| SHOULD (recommended) | `status` | string | cross-harness liveness 판단을 위한 상태값 |
+| MAY (extension) | 하네스별 자유 필드 | — | schema `additionalProperties: false` 범위 내에서 optional로 선언된 항목만 허용 |
+
+### agent_id opaque 속성
+
+`owner_agent_id` 및 모든 agent 식별자 필드는 MUST harness-scoped opaque string으로 취급해야 한다. 다른 하네스가 생성한 `agent_id`를 parse하거나 내부 구조를 추론하는 것은 MUST NOT 허용되어서는 안 된다. aggregator는 `agent_id`를 display key 또는 equality check 용도로만 사용하며, 하네스별 식별자 구조에 의존해서는 안 된다.
+
+### 등록된 shared-purpose 파일
+
+| 파일명 | schema | 목적 | 최초 적용 |
+|---|---|---|---|
+| `agent-tracker.json` | `conformance/state-schemas/agent-tracker.schema.json` | 에이전트 인스턴스 lifecycle tracking | v0.7.0 |
+
+향후 신규 shared-purpose file을 추가할 때는 반드시 이 섹션에 등록해야 한다. 등록 없이 여러 하네스가 동일 파일명을 독립적으로 사용하는 것은 MUST NOT 허용되어서는 안 된다.
+
+### Supervision(nexus-code) aggregation 전제
+
+nexus-code가 cross-harness aggregation을 구현할 경우, `.nexus/state/*/agent-tracker.json` glob 모델로 각 하네스의 파일을 개별적으로 읽는다. 단일 공통 경로 파일 모델이 아니다. 이 glob 모델이 동작하려면 각 하네스가 정확히 `{harness-id}/agent-tracker.json` 경로에 파일을 기록해야 한다.
+
+---
+
 ## Conformance 의무와의 연결
 
 ### CONSUMING.md §Conformance Obligation
@@ -240,7 +291,7 @@ fixture 통과 = schema field 100% coverage ≠ 산출물 제어 의무 이행.
 
 fixture는 도구 호출의 반환값과 state file postcondition을 검증하지만, 아래 항목은 fixture만으로 검증되지 않는다.
 
-- Harness-produced 산출물(`agent-tracker.json`)의 생성·삭제 타이밍
+- Harness-produced 산출물(`{harness-id}/agent-tracker.json`)의 생성·삭제 타이밍
 - Cross-harness interop 의무(다른 하네스가 생성한 파일을 읽을 수 있는가)
 - Forward-compatible schema 유지 의무
 - git-tracking 격리 의무
@@ -251,7 +302,7 @@ fixture는 도구 호출의 반환값과 state file postcondition을 검증하
 
 `conformance/README.md`가 정의하는 schema field coverage 의무: 모든 state-schema field는 최소 하나의 fixture의 `covers` 항목에 등장해야 한다. 이 의무는 fixture suite가 schema 전체를 검증함을 보장한다.
 
-본 문서는 이 의무가 **Tool-produced 산출물에 대해서만** 적용됨을 명시한다. Harness-produced 산출물(`agent-tracker.json`)의 field coverage는 하네스 자체 테스트 suite의 책임이다.
+본 문서는 이 의무가 **Tool-produced 산출물에 대해서만** 적용됨을 명시한다. Harness-produced 산출물(`{harness-id}/agent-tracker.json`)의 field coverage는 하네스 자체 테스트 suite의 책임이다.
 
 schema field가 신규 추가되었을 때, nexus-core 관리자는 MUST 해당 field를 cover하는 fixture를 추가하거나 기존 fixture를 갱신해야 한다. field를 schema에 추가하면서 fixture를 갱신하지 않는 것은 coverage 의무 위반이다.
 

package/docs/nexus-state-overview.md

@@ -91,7 +91,7 @@ The Nexus state layout is divided into two categories:
 
 ---
 
-### `.nexus/state/agent-tracker.json`
+### `.nexus/state/{harness-id}/agent-tracker.json`
 
 | Attribute | Value |
 |-----------|-------|
@@ -100,13 +100,17 @@ The Nexus state layout is divided into two categories:
 | Created by | Session start (harness hook) |
 | Deleted by | Session end (harness hook) |
 
-**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.
+**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.
 
-**Creation trigger.** Initialized by the harness at session start.
+**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.
+
+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.
+
+**Creation trigger.** Initialized by the harness at session start. The harness creates the `{harness-id}/` subdirectory if it does not already exist.
 
 **Deletion trigger.** Removed by the harness upon session teardown.
 
-**Tool access.** Managed exclusively by harness hooks. No Nexus MCP tool listed in this specification writes to this file; `task_add` reads the `owner_agent_id` field from tasks to inform the harness, but does not access `agent-tracker.json` directly.
+**Tool access.** Managed exclusively by harness hooks. No Nexus MCP tool listed in this specification writes to this file. When `task_add` records an `owner_agent_id` on a task, it stores the value as received from the harness without parsing or interpreting it — the value is passed through opaquely to the harness on subsequent reads.
 
 ---
 

package/manifest.json

@@ -1,6 +1,6 @@
 {
-  "nexus_core_version": "0.6.0",
-  "nexus_core_commit": "bcde383b56308b86006babe73f87fed9222c0761",
+  "nexus_core_version": "0.7.0",
+  "nexus_core_commit": "ea8c194dc2e6f358317af252d3823d3f58ce757d",
   "schema_contract_version": "2.0",
   "agents": [
     {
@@ -19,6 +19,20 @@
       "id": "architect",
       "body_hash": "sha256:85f9a3de419f32cdae284436eb1d902bff19a2230c50fe3068ffc642949a63b7"
     },
+    {
+      "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": "reviewer",
       "description": "Content verification — validates accuracy, checks facts, confirms grammar and format of non-code deliverables",
@@ -35,20 +49,19 @@
       "body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
     },
     {
-      "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",
+      "name": "researcher",
+      "description": "Independent investigation — conducts web searches, gathers evidence, and reports findings with citations",
+      "task": "Web search, independent investigation",
+      "alias_ko": "리서처",
+      "category": "do",
       "resume_tier": "persistent",
-      "model_tier": "high",
+      "model_tier": "standard",
       "capabilities": [
         "no_file_edit",
-        "no_task_create",
-        "no_task_update"
+        "no_task_create"
       ],
-      "id": "designer",
-      "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
+      "id": "researcher",
+      "body_hash": "sha256:fc79bafec05503327bd51a0b84b6e642d304bd79c45b78db6448b112793c143e"
     },
     {
       "name": "strategist",
@@ -67,33 +80,20 @@
       "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
     },
     {
-      "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": "researcher",
-      "description": "Independent investigation — conducts web searches, gathers evidence, and reports findings with citations",
-      "task": "Web search, independent investigation",
-      "alias_ko": "리서처",
-      "category": "do",
+      "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": "standard",
+      "model_tier": "high",
       "capabilities": [
         "no_file_edit",
-        "no_task_create"
+        "no_task_create",
+        "no_task_update"
       ],
-      "id": "researcher",
-      "body_hash": "sha256:fc79bafec05503327bd51a0b84b6e642d304bd79c45b78db6448b112793c143e"
+      "id": "designer",
+      "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
     },
     {
       "name": "postdoc",
@@ -155,6 +155,19 @@
       "id": "nx-run",
       "body_hash": "sha256:6c8d1a36626d4034209ff83780dec6238297ec4710612441b2ef09daac714ca8"
     },
+    {
+      "name": "nx-plan",
+      "description": "Structured multi-perspective analysis to decompose issues, align on decisions, and produce an enriched plan before execution. Plan only — does not execute.",
+      "summary": "Structured planning — subagent-based analysis, deliberate decisions, produce execution plan",
+      "triggers": [
+        "plan"
+      ],
+      "harness_docs_refs": [
+        "resume_invocation"
+      ],
+      "id": "nx-plan",
+      "body_hash": "sha256:85b858089bd3dc276be61baa3f5265bc107a85470f169983e710fecb404bb4b1"
+    },
     {
       "name": "nx-sync",
       "description": "Context knowledge synchronization — scans project state and updates .nexus/context/ design documents",
@@ -175,19 +188,6 @@
       ],
       "id": "nx-init",
       "body_hash": "sha256:3c8230ecc0f87c541ec0ff80492a28f28bf173d0b9781901adadfae69a54b8ed"
-    },
-    {
-      "name": "nx-plan",
-      "description": "Structured multi-perspective analysis to decompose issues, align on decisions, and produce an enriched plan before execution. Plan only — does not execute.",
-      "summary": "Structured planning — subagent-based analysis, deliberate decisions, produce execution plan",
-      "triggers": [
-        "plan"
-      ],
-      "harness_docs_refs": [
-        "resume_invocation"
-      ],
-      "id": "nx-plan",
-      "body_hash": "sha256:85b858089bd3dc276be61baa3f5265bc107a85470f169983e710fecb404bb4b1"
     }
   ],
   "vocabulary": {

package/package.json

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