@moreih29/nexus-core 0.9.0 → 0.11.0

package/README.md

@@ -11,29 +11,30 @@ Nexus 생태계는 세 층위로 나뉩니다. `nexus-core`는 가장 아래, **
 ```
 Supervision   (reserved)
                 │  read-only
-Execution     claude-nexus ↔ opencode-nexus
+Execution     claude-nexus ↔ opencode-nexus ↔ codex-nexus
                 │  read-only
 Authoring     nexus-core   ← 이 저장소
 ```
 
-현재 active 소비자는 두 Execution layer 하네스(`claude-nexus`, `opencode-nexus`)이며, 모두 `nexus-core`를 **read-only**로 참조합니다. Supervision layer는 외부 감독자 consumer를 위해 예약된 자리입니다(과거 nexus-code 프로젝트가 이 layer를 구현했으나 2026-04-14 archived).
+현재 active 소비자는 세 Execution layer 하네스(`claude-nexus`, `opencode-nexus`, `codex-nexus`)이며, 모두 `nexus-core`를 **read-only**로 참조합니다. Supervision layer는 외부 감독자 consumer를 위해 예약된 자리입니다(과거 nexus-code 프로젝트가 이 layer를 구현했으나 2026-04-14 archived).
 
 | Consumer | Layer | 하는 일 |
 |---|---|---|
 | [`claude-nexus`](https://github.com/moreih29/claude-nexus) | Execution | Claude Code 하네스 위에서 에이전트 조립·디스패치 |
 | [`opencode-nexus`](https://github.com/moreih29/opencode-nexus) | Execution | OpenCode 하네스 위에서 에이전트 조립·디스패치 |
+| [`codex-nexus`](https://github.com/moreih29/codex-nexus) | Execution | Codex 하네스 위에서 에이전트 조립·디스패치 |
 
 ## For Consumer Repositories
 
-> 이 저장소는 **외부 사용자가 직접 설치하는 플러그인이 아닙니다**. Nexus 하네스(`claude-nexus`, `opencode-nexus`)를 사용하려면 해당 저장소의 안내를 따르세요.
+> 이 저장소는 **외부 사용자가 직접 설치하는 플러그인이 아닙니다**. Nexus 하네스(`claude-nexus`, `opencode-nexus`, `codex-nexus`)를 사용하려면 해당 저장소의 안내를 따르세요.
 
-Consumer 저장소(`claude-nexus`, `opencode-nexus`)의 LLM 에이전트가 `@moreih29/nexus-core` 버전 업그레이드를 처리해야 하는 경우, **[CONSUMING.md](./CONSUMING.md)**의 Upgrade Protocol을 참조하세요.
+Consumer 저장소(`claude-nexus`, `opencode-nexus`, `codex-nexus`)의 LLM 에이전트가 `@moreih29/nexus-core` 버전 업그레이드를 처리해야 하는 경우, **[CONSUMING.md](./CONSUMING.md)**의 Upgrade Protocol을 참조하세요.
 
 CONSUMING.md는 LLM 에이전트 전용 문서입니다. 사람 독자는 이 README가 더 유용합니다.
 
 ## 이 저장소는 무엇이 **아닌가**
 
-`nexus-core`는 **외부 사용자가 직접 설치하는 플러그인이 아닙니다.** Nexus 하네스(`claude-nexus`, `opencode-nexus`)를 사용하고 싶다면 해당 저장소의 안내를 따르세요. `nexus-core`는 그 두 하네스가 내부적으로 공유하는 자산입니다.
+`nexus-core`는 **외부 사용자가 직접 설치하는 플러그인이 아닙니다.** Nexus 하네스(`claude-nexus`, `opencode-nexus`, `codex-nexus`)를 사용하고 싶다면 해당 저장소의 안내를 따르세요. `nexus-core`는 그 세 하네스가 내부적으로 공유하는 자산입니다.
 
 ## 범위
 
@@ -69,7 +70,7 @@ CONSUMING.md는 LLM 에이전트 전용 문서입니다. 사람 독자는 이 RE
 
 ## Status
 
-v0.7.1 (2026-04-14). 최신 release: agent-tracker namespace isolation (v0.7.0, GH #16) + nexus-code archived cleanup (v0.7.1). 상세 변경 이력은 [CHANGELOG.md](./CHANGELOG.md) 참조.
+v0.11.0 (2026-04-17). 최신 release: 훅 컨텍스트 주입 가이드 governance 재정립 (GH #21/#22/#23 — 3 consumer drift 대응). 상세 변경 이력은 [CHANGELOG.md](./CHANGELOG.md) 참조.
 
 ## References
 

package/conformance/lifecycle/README.md

@@ -9,6 +9,11 @@
 | `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` 재개 카운터 및 상태 복귀 |
+| `session-end.json` | `session_end` | `agent-tracker.json` 삭제, `history.json` · `memory/` · `context/` · `rules/` 보존 |
+
+## Why session-end was re-added at v0.11.0
+
+v0.6.0에서 session-start/session-end fixture를 제거한 이유는 당시 구현이 `runtime.schema.json`에 의존했기 때문이다. `runtime.schema.json`은 execution semantics를 포함하므로 nexus-core의 prompt-only 원칙과 충돌했다. v0.11.0 재도입은 `runtime.schema.json`을 완전히 배제하고 `agent-tracker.schema.json`과 `history.schema.json`만 참조한다. session_end fixture가 검증하는 핵심 invariant는 두 가지다: (1) agent-tracker.json은 세션 종료 시 삭제된다(session-scoped), (2) history.json · memory/ · context/ · rules/는 삭제되어서는 안 된다(Negative MUST — cross-session knowledge 보존).
 
 ## Tool-action 대신 Event 트리거 사용
 
@@ -31,7 +36,7 @@ Test runner는 이 키를 파일 시스템 경로로 해석하기 전에 다음
 
 치환 규약:
 - `{STATE_ROOT}`와 `{HARNESS_ID}` 두 token만 인식된다. 그 외 `{…}` 형태의 token이 경로에 등장하면 authoring 오류로 처리한다.
-- 공통 파일 fixture (`plan-*`, `task-*`, `history-*`, `artifact-write`)는 하드코딩된 경로를 사용하며 이 token 규약이 적용되지 않는다. Token 경로는 lifecycle fixture 3종에만 적용된다.
+- 공통 파일 fixture (`plan-*`, `task-*`, `history-*`, `artifact-write`)는 하드코딩된 경로를 사용하며 이 token 규약이 적용되지 않는다. Token 경로는 lifecycle fixture 4종(`agent-spawn`, `agent-complete`, `agent-resume`, `session-end`)의 `agent-tracker.json` 경로에만 적용된다.
 
 ### Fixture별 경로 요약
 
@@ -40,3 +45,4 @@ Test runner는 이 키를 파일 시스템 경로로 해석하기 전에 다음
 | `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` |
+| `session-end.json` | `claude-nexus` | `.nexus/state/claude-nexus/agent-tracker.json` (null assertion — file must not exist after session end) |

package/conformance/lifecycle/memory-access-record.json

@@ -0,0 +1,27 @@
+{
+  "test_id": "memory_access_record",
+  "description": "Verifies that a memory-access.jsonl record is written with the required fields when an agent reads a memory file during a session",
+  "precondition": {
+    "state_files": {
+      "{STATE_ROOT}/{HARNESS_ID}/memory-access.jsonl": null
+    }
+  },
+  "event": {
+    "type": "session_end",
+    "params": {
+      "harness_id": "claude-nexus"
+    },
+    "description": "Harness reads memory file and appends an access record to memory-access.jsonl. This fixture validates the structure of the resulting JSONL record against memory-access.schema.json."
+  },
+  "postcondition": {
+    "state_files": {
+      "{STATE_ROOT}/{HARNESS_ID}/memory-access.jsonl": {}
+    }
+  },
+  "covers": {
+    "state_schemas": {
+      "memory-access.schema.json": ["path", "last_accessed_ts", "access_count", "last_agent", "schema_version"]
+    },
+    "description": "memory-access.jsonl is a JSONL file where each line is a memory-access.schema.json record. This fixture asserts the file exists after a session where memory was read. Content is not inspected via JSONPath because JSONL is not parseable as a single JSON object; field coverage is declared here to satisfy the schema coverage gate."
+  }
+}

package/conformance/lifecycle/session-end.json

@@ -0,0 +1,48 @@
+{
+  "test_id": "session_end",
+  "description": "Verifies that session_end deletes agent-tracker.json while preserving history.json and the memory/context/rules knowledge directories",
+  "precondition": {
+    "state_files": {
+      "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": [
+        {
+          "harness_id": "claude-nexus",
+          "agent_name": "architect",
+          "agent_id": "uuid-eng01",
+          "started_at": "2026-04-13T00:00:00.000Z",
+          "resume_count": 0,
+          "status": "completed",
+          "stopped_at": "2026-04-13T01:00:00.000Z",
+          "last_message": "Implementation complete",
+          "files_touched": ["src/foo.ts"]
+        }
+      ],
+      ".nexus/history.json": {},
+      ".nexus/memory/lessons.md": {},
+      ".nexus/context/architecture.md": {},
+      ".nexus/rules/project.md": {}
+    }
+  },
+  "event": {
+    "type": "session_end",
+    "params": {
+      "harness_id": "claude-nexus"
+    },
+    "description": "Harness teardown on session close: agent-tracker registry is deleted (session-scoped), while history, memory, context, and rules are retained across sessions"
+  },
+  "postcondition": {
+    "state_files": {
+      "{STATE_ROOT}/{HARNESS_ID}/agent-tracker.json": null,
+      ".nexus/history.json": {},
+      ".nexus/memory/lessons.md": {},
+      ".nexus/context/architecture.md": {},
+      ".nexus/rules/project.md": {}
+    }
+  },
+  "covers": {
+    "state_schemas": {
+      "agent-tracker.schema.json": ["harness_id", "agent_name", "agent_id", "started_at", "resume_count", "status", "stopped_at", "last_message", "files_touched[]"],
+      "history.schema.json": ["cycles"]
+    },
+    "description": "session_end fixture verifies the deletion boundary: agent-tracker.json (session-scoped) is deleted, history.json existence is asserted via empty-object check (file must exist, content not re-validated here). memory/context/rules files are verified present via empty-object check, confirming the do-not-delete MUST constraint. agent-tracker fields are listed here for completeness; leaf-field coverage is already established by agent-spawn/agent-complete/agent-resume fixtures."
+  }
+}

package/conformance/schema/fixture.schema.json

@@ -166,8 +166,8 @@
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["agent_spawn", "agent_complete", "agent_resume"],
-          "description": "Lifecycle event type. agent_spawn/agent_complete/agent_resume: agent instance lifecycle."
+          "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",

package/conformance/state-schemas/memory-access.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://moreih29/nexus-core/conformance/state-schemas/memory-access.schema.json",
+  "title": "Memory Access Record",
+  "description": "Schema for a single line in .nexus/state/{harness_id}/memory-access.jsonl — each JSONL line is a JSON object satisfying this schema. Upsert key is `path`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["path", "last_accessed_ts", "access_count", "last_agent"],
+  "properties": {
+    "path": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Absolute path to the memory file that was read. Typically resolved under .nexus/memory/."
+    },
+    "last_accessed_ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the most recent read event for this file."
+    },
+    "access_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cumulative count of read events observed for this file since tracking began in this harness."
+    },
+    "last_agent": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Opaque harness-specific identifier for the agent (or equivalent subject) that performed the most recent read."
+    },
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Optional migration anchor, aligned with other state schemas introduced in v0.5.0."
+    }
+  }
+}

package/docs/consumer-implementation-guide.md

@@ -503,11 +503,15 @@ The canonical trigger for every tag is the explicit bracket form in `vocabulary/
 
 Hooks are the consumer's mechanism for responding to lifecycle events. nexus-core defines 8 abstract events. The names are harness-neutral; each harness maps them to its own event API.
 
+### Relationship to harness-native knowledge surfaces
+
+Consumer harnesses typically maintain a harness-native primary knowledge surface — for example, a system-prompt layer, a persistent session notice, or a harness banner injected before every LLM call. The hook events and their guidance in §9 are **complementary to** this harness-native surface, not a replacement for it. When §9 says "inject X at hook Y", the concrete injection path may live in the harness-native surface if that produces an equivalent effect. What matters is that the described information reaches the agent at the described moment — the delivery mechanism is consumer-local.
+
 ### Event mapping examples
 
 Different harnesses expose these events under different names:
 
-- **Claude Code**: `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `PreToolUse`, `PostToolUse`, `Stop`, `PostCompact`
+- **(illustrative, non-normative)** **Claude Code**: `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `PreToolUse`, `PostToolUse`, `Stop`, `PostCompact`
 - **OpenCode**: its own hook API names — map accordingly when building an OpenCode consumer
 
 Identify the equivalent events in your harness's plugin system and implement the expected behaviors below.
@@ -516,69 +520,66 @@ Identify the equivalent events in your harness's plugin system and implement the
 
 #### `session_start`
 
-**When it fires:** The harness launches or the user begins a new session.
+**When it fires:** A new agent session begins (harness runtime may expose this as `SessionStart`, `session.created`, an init hook, or equivalent).
 
 **Expected consumer behavior:**
-- Create `.nexus/` and `.nexus/state/` directories if they do not exist.
-- Write `.nexus/.gitignore` with `state/` if it does not exist.
-- 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.
+- **SHOULD** create `.nexus/` and `.nexus/state/` directories if they do not exist.
+- **SHOULD** write `.nexus/.gitignore` with `state/` if it does not exist.
+- **MUST** 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.
 
 ---
 
 #### `user_message`
 
-**When it fires:** The user submits a message to Lead.
+**When it fires:** The user submits a message and it is about to be processed (harness runtime may expose this as `UserPromptSubmit`, `message.received`, an on-input hook, or equivalent).
 
 **Expected consumer behavior:**
-- Scan the message text for bracket tags. Match against all triggers defined in `vocabulary/tags.yml`.
+- **SHOULD** scan the message text for bracket tags. Match against all triggers defined in `vocabulary/tags.yml`.
 - For each matched tag:
-  - If `type=skill`: activate the skill (see §8, steps 3–5). Do not proceed with normal message handling for that tag.
-  - If `type=inline_action`: call the handler tool immediately. The user's message following the tag is the input.
-- After tag routing, inject contextual guidance into Lead's available context before LLM inference begins:
+  - **SHOULD** activate the skill if `type=skill` (see §8, steps 3–5). Do not proceed with normal message handling for that tag.
+- **SHOULD** inject contextual guidance into Lead's available context before LLM inference begins:
   - Current plan status: if `plan.json` exists, summarize pending vs. decided issues.
   - Task progress: if `tasks.json` exists, summarize total/completed/pending counts and the ready-task set.
-  - Knowledge file counts: number of files in `.nexus/memory/`, `.nexus/context/`, `.nexus/rules/`.
-- If no tags are matched, pass the message to Lead without modification.
+- **SHOULD** pass the message to Lead without modification if no tags are matched.
 
 ---
 
 #### `subagent_spawn`
 
-**When it fires:** Lead spawns a subagent to execute a task.
+**When it fires:** A subagent is created and about to begin execution (harness runtime may expose this as `SubagentStart`, `agent.spawned`, a subagent-init hook, or equivalent).
 
 **Expected consumer behavior:**
-- 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).
-- Pass the structured task context to the agent: title, context, approach, and acceptance criteria (see §10, Context Passing).
+- **MUST** record the new agent entry in `.nexus/state/{harness-id}/agent-tracker.json`: `{ harness_id, agent_name, agent_id, started_at }`.
+- **SHOULD** 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.
+- **SHOULD** apply capability restrictions: resolve `effective_capabilities` for this agent type and configure the subagent's tool access accordingly (see §6).
+- **SHOULD** 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).
 
 ---
 
 #### `subagent_complete`
 
-**When it fires:** A subagent finishes its assigned work and returns control to Lead.
+**When it fires:** A subagent finishes its assigned work and returns control (harness runtime may expose this as `SubagentStop`, `agent.completed`, a subagent-exit hook, or equivalent).
 
 **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 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`.
+- **MUST** update `.nexus/state/{harness-id}/agent-tracker.json`: set `status=completed`, record `stopped_at` timestamp.
+- **MUST** 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.
+- **MAY** maintain a separate `edit-tracker.json` for cross-session file-touch history, updating it here. This is not a nexus-core requirement; it is a harness-local optimization.
+- **SHOULD** surface an unfinished-task warning when the stopping agent has tasks left in `pending` or `in_progress` state. This pattern is observed across consumers and aids recovery; the warning may be injected into Lead's context or surfaced as a reminder.
+- **MAY** update the task status in `tasks.json` when the agent was assigned a specific task. Note: this responsibility may alternatively be fulfilled at the Lead or tool-contract layer rather than the hook surface.
 
 ---
 
 #### `pre_tool_use`
 
-**When it fires:** A tool is about to execute.
+**When it fires:** A tool call has been issued and is about to execute (harness runtime may expose this as `PreToolUse`, `tool.before`, a pre-call interceptor, or equivalent).
 
 **Expected consumer behavior:**
-- Gate enforcement for unplanned file edits: if `tasks.json` does not exist and the tool is a file-editing tool, block the call and return an error explaining that edits outside of a planned task cycle are disallowed. This prevents unplanned workspace changes.
-- Capability gate: check whether the current agent (Lead or a subagent) has the requested tool in its disallowed set. If so, block the call and return an appropriate error.
-- Any other pre-condition checks your harness requires (rate limits, sandbox policies, etc.).
+- **SHOULD** enforce a gate for unplanned file edits: if `tasks.json` does not exist and the tool is a file-editing tool, block the call and return an error explaining that edits outside of a planned task cycle are disallowed. This prevents unplanned workspace changes.
+- **Capability invariant (MUST)**: disallowed tools MUST NOT execute. **Enforcement layer (consumer choice)**: The abstract invariant holds regardless of enforcement layer. Consumers may enforce at the hook, in static agent config (frontmatter/TOML/disallowedTools), at a framework-level gate, or any combination — the choice is consumer-local. What nexus-core requires is the invariant, not the enforcement mechanism.
+- **MAY** apply any other pre-condition checks your harness requires (rate limits, sandbox policies, etc.).
+
+> **SHOULD note on block reason**: When a tool call is blocked, the `reason` field returned to the LLM is consumed as operational guidance for the next action. Consumers SHOULD compose the `reason` as actionable, directive text rather than a generic error message.
 
 Read-only tools (query tools, status reads) are never blocked by capability gates. Only tools with primary write effects are subject to capability restrictions.
 
@@ -586,41 +587,53 @@ Read-only tools (query tools, status reads) are never blocked by capability gate
 
 #### `post_tool_use`
 
-**When it fires:** A tool has executed and returned a result.
+**When it fires:** A tool call has completed and a result is available (harness runtime may expose this as `PostToolUse`, `tool.after`, a post-call interceptor, or equivalent).
 
 **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.
-- (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.
+- **SHOULD** append a log entry to `.nexus/state/tool-log.jsonl`: timestamp, agent_id, tool name, file path (if a file was touched), result status. (This practice is observed across all consumers; nexus-core does not yet define a schema for this file — tracked for v0.11.0.)
+- **MAY** record the file path and agent_id in `edit-tracker.json` if your harness maintains it for cross-session file-touch history. 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.
+- **MAY** record the error in the log for diagnostic purposes if the tool result indicates an error. Do not suppress error results.
 
 ---
 
 #### `session_end`
 
-**When it fires:** The user closes the harness or the session terminates.
+**When it fires:** The session is terminating (harness runtime may expose this as `Stop`, `session.end`, a shutdown hook, or equivalent).
 
 **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 `.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.
+- **SHOULD** warn the user if `tasks.json` exists and contains incomplete tasks (status `pending` or `in_progress`), that the session is ending with unfinished work and suggest calling `task_close` to archive before exiting.
+- **SHOULD** delete `.nexus/state/{harness-id}/agent-tracker.json` (a session-scoped file that has no value beyond the session).
+- **MAY** rotate or archive `tool-log.jsonl` if your harness supports log retention.
+- **MUST NOT** delete `history.json`, `memory/`, `context/`, or `rules/` — these are project-scoped and must persist across sessions.
+- **SHOULD** prompt or block with an "all tasks completed — call `task_close` to archive" reminder when `tasks.json` shows all tasks completed but the cycle has not been archived via `task_close`. Run-cycle closure is a recoverability boundary.
 
 ---
 
 #### `context_compact`
 
-**When it fires:** The LLM's context window is compressed (older messages are truncated to make room for new content).
+**When it fires:** The runtime compresses the context window (harness runtime may expose this as `PostCompact`, `context.compacted`, a post-compact hook, or equivalent).
 
 **Expected consumer behavior:**
-- Re-inject the critical session snapshot that was lost in compression:
+- **SHOULD** re-inject the critical session snapshot that was lost in compression:
   - Active skill/mode: which skill is currently active (plan, run, sync, or none).
   - 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 `.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.
+- **SHOULD** restore state from the state files on disk. Context compaction is a context loss event; the LLM cannot reconstruct session state from its compressed context alone.
+- **SHOULD** read state files fresh from disk — do not rely on in-memory caches that may also have been cleared.
+
+---
+
+### 9.X Appendix: Hook Event Runtime Mapping (consumer-owned)
+
+Each consumer harness MUST publish a mapping document at `harness-content/nexus-hook-mapping.md` in its own repository, listing how its runtime hook surface maps to the 8 conceptual events in §9.
+
+nexus-core does not mirror these mappings — they are owned and maintained per consumer. This appendix is a registry pointer, not a copy.
+
+- **harness_docs_refs token**: `nexus_hook_mapping`
+- **Expected location in consumer repo**: `harness-content/nexus-hook-mapping.md`
+- **Descriptive, not normative**: the consumer mapping document reflects current harness implementation. Verify against the consumer repo for the current mapping — this appendix does not guarantee specific contents.
 
 ---
 

package/docs/memory-lifecycle-contract.md

@@ -0,0 +1,119 @@
+# Memory Lifecycle Contract
+
+This document defines the canonical operating principles for the `.nexus/memory/` layer. It sits alongside `vocabulary/memory_policy.yml`, which is the machine-readable form of the same rules. Where `memory_policy.yml` states principles as structured data for consumer tooling to parse, this document provides authoritative prose for implementers. The boundary between canonical and consumer-local is consistent across both: nexus-core owns the principles; consumers own all thresholds, formats, and enforcement mechanics.
+
+---
+
+## 1. Canonical Principles
+
+### 1.1 Read-Event Observation
+
+An agent observes a memory file at the moment it reads that file's contents. That read event — and only that event — is the unit of observation for access tracking.
+
+Write events, directory scans (glob, grep), and path mentions in prose are not observation events. An agent that lists `.nexus/memory/` to decide which file to read has not yet observed anything. The observation is recorded when the file is opened and its content is consumed.
+
+This distinction matters because memory is meant to capture what has actually been used, not what has been found or referenced. Stale detection and gc decisions depend on a signal that reflects genuine use, not incidental proximity.
+
+### 1.2 Three Information Types Accumulated
+
+For each memory file, three pieces of information are accumulated across read events: (1) the wall-clock time of the most recent read, (2) the cumulative count of reads observed since tracking began, and (3) the identity of the most recent reader.
+
+These three values constitute the access record for a file. They are stored in `.nexus/state/{harness_id}/memory-access.jsonl` — one JSONL line per file, upserted on each observation. The canonical field names and types are defined in `conformance/state-schemas/memory-access.schema.json`; that schema is the authoritative source for storage format. Value domains for the reader identity field are harness-local.
+
+Together, these three values give consumers the signals they need to reason about whether a memory file remains actively useful or has drifted into disuse.
+
+### 1.3 Manual Gate as Default
+
+Automatic deletion is off by default. The normal path for removing stale memory files is the `[m:gc]` tag, which the user invokes manually. User intent is the final arbiter of what gets removed.
+
+Automatic deletion is an opt-in capability. A consumer may enable it, but must do so explicitly. No consumer should assume automatic deletion is active unless they have deliberately configured it.
+
+This default reflects a conservative stance: the cost of accidentally losing a still-relevant memory file is higher than the cost of retaining an unused one. Manual gc preserves human judgment in the loop.
+
+### 1.4 Three-Signal Intersection for Automatic Deletion
+
+When a consumer enables automatic deletion, the policy must require the simultaneous satisfaction of at least three independent signals before a file is eligible for removal. No single signal, however strong, is sufficient on its own.
+
+The three signals should be drawn from independent dimensions — for example: elapsed time since last access, number of work cycles completed since last read, and cumulative access count since tracking began. Requiring intersection across independent dimensions reduces the risk of false positives caused by a single anomalous period (a long vacation, an unusually dense sprint, an early-lifecycle file that has never yet been needed).
+
+The specific thresholds for each signal are consumer-local, calibrated to the project's cycle cadence and team working patterns. nexus-core specifies the structural requirement — three independent signals — not the magnitudes.
+
+### 1.5 Git-Backed Recoverable Deletion
+
+Every memory file deletion must be recorded as a git commit. Deletion without a corresponding commit is not permitted.
+
+The commit should include enough information in its message that a reader can reconstruct the recovery path — for example, the git command needed to restore the file from history. Including an explicit recovery path in the commit message is recommended; it reduces the cognitive load on anyone who later discovers the deletion was premature. The exact format of the commit message is consumer-local.
+
+This requirement ensures that no memory deletion is silent. The project history serves as a safety net, and the act of committing forces an intentional moment before content is removed from the active workspace.
+
+### 1.6 Merge-Before-Create
+
+When a new memory save candidate substantively overlaps an existing file in topic and category, the existing file should be extended rather than a new file created. Proliferation of near-duplicate files degrades the utility of the memory layer: duplicates force readers to reconcile redundant content and make gc harder to reason about.
+
+The concrete criteria for deciding whether two topics overlap — keyword thresholds, semantic distance, structural similarity — are consumer-local. nexus-core requires the preference for merging; it does not specify the matching algorithm.
+
+---
+
+## 2. Category Boundaries
+
+Memory files are organized into three categories defined in `vocabulary/memory_policy.yml`. Each category has a `prefix-` naming convention that makes the file's type visible in directory listings.
+
+### 2.1 `empirical-`
+
+Files in this category contain empirically verified findings: observations and measurements the project has confirmed through its own experimentation. Examples include runtime behavior observations, testing-derived structural facts, and operational measurements that cannot be inferred from documentation alone.
+
+Empirical memory captures what the project has learned by doing. It is distinct from external references (what others have said) and from patterns (what the project has found effective as procedure).
+
+### 2.2 `external-`
+
+Files in this category contain external constraints and references: requirements imposed by upstream dependencies, third-party API limits, vendor documentation quotations, and knowledge that originates outside the project.
+
+External memory may become stale if the upstream source changes. This is the category most likely to require periodic review against current upstream state.
+
+### 2.3 `pattern-`
+
+Files in this category contain tactical operational patterns: recurring cycle-level recipes, routing heuristics, and procedural knowledge developed through work on the project.
+
+The scope of this category is explicitly tactical. Architectural or design-level patterns do not belong here. If a finding rises to the level of architectural principle or design rationale — something that shapes how the project is structured rather than how day-to-day work is executed — it belongs in `.nexus/context/`, not in `memory/`.
+
+### 2.4 Relation to `context/` and `rules/`
+
+`.nexus/memory/` and `.nexus/context/` serve different purposes and should not be confused.
+
+`memory/` holds project-accumulated working knowledge: empirical findings, external references, and tactical patterns that agents draw on during active work. These files are created via `[m]` and managed via `[m:gc]`. They are subject to the gc lifecycle defined in this document.
+
+`.nexus/context/` holds design principles, architectural philosophy, and onboarding materials — documents that define the project's enduring structure and intent. Primer-style documents (documents that introduce the project's goals, vocabulary, or design decisions to a new reader) belong in `context/`, not in `memory/`. The gc lifecycle does not apply to `context/` files; they are maintained by `[sync]` and represent stable project knowledge rather than accumulated working observations.
+
+`.nexus/rules/` holds enforceable project rules. These are not memory entries and are not subject to this lifecycle.
+
+---
+
+## 3. Consumer Responsibility
+
+The principles in §1 are canonical. Everything below is consumer-local — decisions that each consumer makes independently, calibrated to their own project, harness, and team cadence. nexus-core does not prescribe values for any of the following items.
+
+Consumers determine:
+
+- The specific threshold for each signal used in automatic deletion (for example: how much time elapsed, how many cycles completed, what access count constitutes "unused")
+- File and directory size criteria, if any, used in gc decisions
+- The frequency or trigger conditions for `[m:gc]` invocations in normal workflow
+- The git commit message format for deletion commits, beyond the recommendation that a recovery path be included
+- Whether access counts are re-incremented in resumed sessions (i.e., whether a resumed context that re-reads a file adds to the count or not)
+- The keyword overlap threshold, semantic distance measure, or other matching criteria used to decide whether merge-before-create applies
+- Whether additional filename prefix categories beyond the canonical three are introduced for project-specific use
+
+Consumers may configure automatic deletion, but must not treat it as active unless they have explicitly opted in. All other gc path decisions remain under user control by default.
+
+---
+
+## 4. Reference
+
+Related vocabulary and files:
+
+- `vocabulary/memory_policy.yml` — machine-readable canonical form of the principles in this document
+- `vocabulary/tags.yml` — `[m]` and `[m:gc]` tag definitions
+- `vocabulary/invocations.yml` — `memory_read_observation` primitive
+- `conformance/state-schemas/memory-access.schema.json` — access log schema (canonical field names and types)
+- `docs/nexus-outputs-contract.md §Shared filename convention` — `memory-access.jsonl` registration and location convention
+- `docs/behavioral-contracts.md` — other behavioral contracts in nexus-core
+- `.nexus/context/boundaries.md` — why specific thresholds are not canonical (거절 근거 및 Authoring layer 정체성)

package/docs/nexus-outputs-contract.md

@@ -113,6 +113,33 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 
 ---
 
+### `memory-access.jsonl` — memory 파일 접근 기록
+
+**경로**: `.nexus/state/{harness_id}/memory-access.jsonl`
+
+**책임 주체**: 각 consumer 하네스의 memory-read observation hook. 어떤 MCP tool도 이 파일에 직접 write해서는 안 된다.
+
+**생성 trigger**: 하네스가 `.nexus/memory/` 하위 파일의 읽기 이벤트를 관측할 때 MUST path-upsert 방식으로 기록해야 한다. 파일이 없으면 첫 관측 시 MUST 생성해야 한다.
+
+**삭제 trigger**: 하네스 `[m:gc]` 핸들러가 gc 정책(merge/delete)을 실행할 때 관리한다. gc 주기 및 보존 정책은 consumer 하네스가 결정한다.
+
+**Schema reference**: `conformance/state-schemas/memory-access.schema.json` (JSONL 형식 — 각 줄이 하나의 line-object이며 schema를 만족해야 한다. upsert key는 `path`).
+
+**Interop requirement**:
+- 하네스는 `memory-access.jsonl`을 기록할 때 MUST 각 JSONL line이 `conformance/state-schemas/memory-access.schema.json`에 유효한 객체여야 한다.
+- upsert key `path`는 MUST `.nexus/memory/` 하위 파일의 경로를 담아야 한다.
+- `last_accessed_ts` 필드는 MUST ISO 8601 형식을 사용해야 한다.
+- `last_agent` 필드는 MUST harness-scoped opaque string으로 취급해야 한다 — 다른 하네스가 생성한 값을 parse하거나 구조를 추론하는 것은 MUST NOT 허용되어서는 안 된다.
+- 두 consumer가 동일 schema로 기록하면 향후 공동 사용 프로젝트에서 access log를 병합할 수 있다. 병합 시 `path`를 동등 키로 사용하며 `access_count`는 합산한다.
+- `memory-access.jsonl`은 MUST NOT git-tracked 상태로 commit되어서는 안 된다.
+- 관련 vocabulary: `vocabulary/memory_policy.yml`, `vocabulary/invocations.yml`의 `memory_read_observation` primitive, `vocabulary/tags.yml`의 [m]/[m:gc] entries.
+
+**Conformance fixture reference**: 해당 없음. `memory-access.jsonl`은 MCP tool behavioral fixture 범위 외에 있으며 하네스 memory-read observation hook이 전적으로 책임진다.
+
+§Shared filename convention 섹션도 참조하라.
+
+---
+
 ## Agent-produced 산출물 (ephemeral)
 
 ### `artifacts/` 디렉토리 — 에이전트 생성 파일
@@ -216,6 +243,7 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 ├── artifacts/
 ├── claude-nexus/                      ← namespace 디렉토리
 │   ├── agent-tracker.json             ← shared-purpose file (§Shared filename convention)
+│   ├── memory-access.jsonl            ← shared-purpose file (§Shared filename convention)
 │   ├── plan.extension.json            ← plan.json의 확장 (priority, estimated_effort 등)
 │   ├── tasks.extension.json
 │   ├── history.extension.json         ← 하네스 자체 archive
@@ -224,6 +252,7 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 │   └── tool-log.jsonl
 └── opencode-nexus/                    ← sibling 하네스 namespace 디렉토리
     ├── agent-tracker.json             ← shared-purpose file (동일 파일명, harness-local)
+    ├── memory-access.jsonl            ← shared-purpose file (동일 파일명, harness-local)
     └── ...
 ```
 
@@ -268,6 +297,7 @@ nexus-core는 shared-purpose file에 대해 **최소 공통 schema contract**를
 | 파일명 | schema | 목적 | 최초 적용 |
 |---|---|---|---|
 | `agent-tracker.json` | `conformance/state-schemas/agent-tracker.schema.json` | 에이전트 인스턴스 lifecycle tracking | v0.7.0 |
+| `memory-access.jsonl` | `conformance/state-schemas/memory-access.schema.json` | memory 파일 읽기 이벤트 누적 기록 — informed gc 판단의 신호 기반 | v0.10.0 |
 
 향후 신규 shared-purpose file을 추가할 때는 반드시 이 섹션에 등록해야 한다. 등록 없이 여러 하네스가 동일 파일명을 독립적으로 사용하는 것은 MUST NOT 허용되어서는 안 된다.