@moreih29/nexus-core 0.10.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/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/manifest.json

@@ -1,6 +1,6 @@
 {
-  "nexus_core_version": "0.10.0",
-  "nexus_core_commit": "23c72e53a32308b015eb90468dee3cb6e80eb655",
+  "nexus_core_version": "0.11.0",
+  "nexus_core_commit": "7d32c9e06ec206980cbc1399d29c8cb754cd0d5a",
   "schema_contract_version": "2.0",
   "agents": [
     {
@@ -19,20 +19,6 @@
       "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": "designer",
       "description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
@@ -50,20 +36,18 @@
       "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
     },
     {
-      "name": "strategist",
-      "description": "Business strategy — evaluates market positioning, competitive landscape, and business viability of decisions",
-      "task": "Business strategy, market analysis, competitive positioning",
-      "alias_ko": "전략가",
-      "category": "how",
-      "resume_tier": "persistent",
-      "model_tier": "high",
+      "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_file_edit",
-        "no_task_create",
-        "no_task_update"
+        "no_task_create"
       ],
-      "id": "strategist",
-      "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
+      "id": "engineer",
+      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
     },
     {
       "name": "reviewer",
@@ -80,6 +64,22 @@
       "id": "reviewer",
       "body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
     },
+    {
+      "name": "strategist",
+      "description": "Business strategy — evaluates market positioning, competitive landscape, and business viability of decisions",
+      "task": "Business strategy, market analysis, competitive positioning",
+      "alias_ko": "전략가",
+      "category": "how",
+      "resume_tier": "persistent",
+      "model_tier": "high",
+      "capabilities": [
+        "no_file_edit",
+        "no_task_create",
+        "no_task_update"
+      ],
+      "id": "strategist",
+      "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
+    },
     {
       "name": "researcher",
       "description": "Independent investigation — conducts web searches, gathers evidence, and reports findings with citations",
@@ -142,19 +142,6 @@
     }
   ],
   "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",
@@ -189,6 +176,20 @@
       ],
       "id": "nx-plan",
       "body_hash": "sha256:083ce49c06f8d3e4a0299aa8eb8e33460b68d6a277fe356b4db9635c21016aff"
+    },
+    {
+      "name": "nx-run",
+      "description": "Execution — user-directed agent composition.",
+      "summary": "Execution — user-directed agent composition",
+      "triggers": [
+        "run"
+      ],
+      "harness_docs_refs": [
+        "resume_invocation",
+        "nexus_hook_mapping"
+      ],
+      "id": "nx-run",
+      "body_hash": "sha256:0e2c443efceeab4621709a85cd4e2ba50471d2e850680c655d776cbb62814549"
     }
   ],
   "vocabulary": {

package/package.json

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

package/skills/nx-run/meta.yml

@@ -5,4 +5,5 @@ triggers:
   - run
 harness_docs_refs:
   - resume_invocation
+  - nexus_hook_mapping
 id: nx-run