@moreih29/nexus-core 0.8.0 → 0.10.0

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

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

package/docs/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-layout.md

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

package/docs/nexus-outputs-contract.md

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

package/docs/nexus-state-overview.md

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

package/docs/nexus-tools-contract.md

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

package/manifest.json

@@ -1,6 +1,6 @@
 {
-  "nexus_core_version": "0.8.0",
-  "nexus_core_commit": "254efc7d8f4f52e45b548706dd42389fdb9801b2",
+  "nexus_core_version": "0.10.0",
+  "nexus_core_commit": "23c72e53a32308b015eb90468dee3cb6e80eb655",
   "schema_contract_version": "2.0",
   "agents": [
     {
@@ -20,19 +20,34 @@
       "body_hash": "sha256:85f9a3de419f32cdae284436eb1d902bff19a2230c50fe3068ffc642949a63b7"
     },
     {
-      "name": "reviewer",
-      "description": "Content verification — validates accuracy, checks facts, confirms grammar and format of non-code deliverables",
-      "task": "Content verification, fact-checking, grammar review",
-      "alias_ko": "리뷰어",
-      "category": "check",
-      "resume_tier": "ephemeral",
+      "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"
       ],
-      "id": "reviewer",
-      "body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
+      "id": "engineer",
+      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
+    },
+    {
+      "name": "designer",
+      "description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
+      "task": "UI/UX design, interaction patterns, user experience",
+      "alias_ko": "디자이너",
+      "category": "how",
+      "resume_tier": "persistent",
+      "model_tier": "high",
+      "capabilities": [
+        "no_file_edit",
+        "no_task_create",
+        "no_task_update"
+      ],
+      "id": "designer",
+      "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
     },
     {
       "name": "strategist",
@@ -51,20 +66,19 @@
       "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
     },
     {
-      "name": "designer",
-      "description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
-      "task": "UI/UX design, interaction patterns, user experience",
-      "alias_ko": "디자이너",
-      "category": "how",
-      "resume_tier": "persistent",
-      "model_tier": "high",
+      "name": "reviewer",
+      "description": "Content verification — validates accuracy, checks facts, confirms grammar and format of non-code deliverables",
+      "task": "Content verification, fact-checking, grammar review",
+      "alias_ko": "리뷰어",
+      "category": "check",
+      "resume_tier": "ephemeral",
+      "model_tier": "standard",
       "capabilities": [
         "no_file_edit",
-        "no_task_create",
-        "no_task_update"
+        "no_task_create"
       ],
-      "id": "designer",
-      "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
+      "id": "reviewer",
+      "body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
     },
     {
       "name": "researcher",
@@ -81,20 +95,6 @@
       "id": "researcher",
       "body_hash": "sha256:fc79bafec05503327bd51a0b84b6e642d304bd79c45b78db6448b112793c143e"
     },
-    {
-      "name": "engineer",
-      "description": "Implementation — writes code, debugs issues, follows specifications from Lead and architect",
-      "task": "Code implementation, edits, debugging",
-      "alias_ko": "엔지니어",
-      "category": "do",
-      "resume_tier": "bounded",
-      "model_tier": "standard",
-      "capabilities": [
-        "no_task_create"
-      ],
-      "id": "engineer",
-      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
-    },
     {
       "name": "postdoc",
       "description": "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents",
@@ -142,6 +142,19 @@
     }
   ],
   "skills": [
+    {
+      "name": "nx-run",
+      "description": "Execution — user-directed agent composition.",
+      "summary": "Execution — user-directed agent composition",
+      "triggers": [
+        "run"
+      ],
+      "harness_docs_refs": [
+        "resume_invocation"
+      ],
+      "id": "nx-run",
+      "body_hash": "sha256:0e2c443efceeab4621709a85cd4e2ba50471d2e850680c655d776cbb62814549"
+    },
     {
       "name": "nx-init",
       "description": "Project onboarding — scan, mission, essentials, context generation",
@@ -175,20 +188,7 @@
         "resume_invocation"
       ],
       "id": "nx-plan",
-      "body_hash": "sha256:cd7a5fd1815530be6ffad18358a1295d1f74ef8a24132e75b73522c106eb6ae5"
-    },
-    {
-      "name": "nx-run",
-      "description": "Execution — user-directed agent composition.",
-      "summary": "Execution — user-directed agent composition",
-      "triggers": [
-        "run"
-      ],
-      "harness_docs_refs": [
-        "resume_invocation"
-      ],
-      "id": "nx-run",
-      "body_hash": "sha256:0e2c443efceeab4621709a85cd4e2ba50471d2e850680c655d776cbb62814549"
+      "body_hash": "sha256:083ce49c06f8d3e4a0299aa8eb8e33460b68d6a277fe356b4db9635c21016aff"
     }
   ],
   "vocabulary": {
@@ -302,14 +302,16 @@
         "trigger": "[m]",
         "type": "inline_action",
         "handler": "memory_store",
-        "description": "Stores a lesson or reference to .nexus/memory/"
+        "description": "Stores a lesson or reference to .nexus/memory/",
+        "prose_guidance": "저장 admission 기준 — 코드/웹에서 다시 얻을 수 없는 정보만 저장한다. memory 파일의 naming, category, lifecycle 운영 정책은 vocabulary/memory_policy.yml과 docs/memory-lifecycle-contract.md를 canonical source로 참조한다.\n"
       },
       {
         "id": "m-gc",
         "trigger": "[m:gc]",
         "type": "inline_action",
         "handler": "memory_gc",
-        "description": "Garbage-collects .nexus/memory/ by merging or removing stale entries"
+        "description": "Garbage-collects .nexus/memory/ by merging or removing stale entries",
+        "prose_guidance": "gc 트리거 조건 평가, merge 판단, forgetting policy 집행은 vocabulary/memory_policy.yml에 정의된 원칙을 따르고 구체 임계값은 consumer-local 설정으로 결정한다.\n"
       },
       {
         "id": "rule",
@@ -346,7 +348,101 @@
         "description": "Ask the user a structured question with selectable options.",
         "intent": "structured_user_prompt",
         "fallback_behavior": "If the harness lacks a structured question tool (e.g., opencode-nexus),\npresent the question as prose followed by the options enumerated as a\nnumbered list, then await the user's free-form reply. The LLM is\nexpected to map the reply to the most appropriate option or treat it\nas a free-form answer if no options were given.\n"
+      },
+      {
+        "id": "memory_read_observation",
+        "description": "Harness-local observation of an agent reading a file under .nexus/memory/. This invocation captures the moment a memory file's content is loaded into an agent's context. It is not the read action itself — the read is performed by the harness's file-read primitive — but the observation event emitted by the harness after the read completes.\n",
+        "intent": "memory_read_observation",
+        "fallback_behavior": "If the harness cannot observe file-read events (no equivalent hook), memory access tracking is unavailable and forgetting decisions must rely on manual inspection via the [m:gc] tag. Automatic deletion policies requiring access metadata are consequently not enabled in such harnesses.\n"
+      }
+    ],
+    "task_exceptions": [
+      {
+        "id": "docs_only.coherent",
+        "description": "A batch of documentation files that all address the same scheme, decision, or structural change and should be treated as a single coherent unit.",
+        "applies_when": "all changed files are .md or frontmatter-only, and share one common scheme, decision, or structural change",
+        "treatment": "bundle into 1 writer task + 1 reviewer pair; file count / line count thresholds waived; state coherence claim in task approach field",
+        "rationale": "e.g., updating agent frontmatter files after a new field is introduced; files share the same change intent"
+      },
+      {
+        "id": "docs_only.independent",
+        "description": "A set of documentation files where each file addresses a distinct topic with no cross-reference dependency.",
+        "applies_when": "each .md file addresses a distinct topic with no cross-reference dependency",
+        "treatment": "N parallel writer tasks (one per file), each paired with 1 reviewer task; file count threshold waived per-task",
+        "rationale": "e.g., separate proposal drafts; each file is independently consumed"
+      },
+      {
+        "id": "same_file_bundle",
+        "description": "Two or more decomposed sub-tasks that would each modify the same target file, requiring merger to avoid conflicts.",
+        "applies_when": "two or more sub-tasks in the decomposition would each modify the same target file",
+        "treatment": "merge sub-tasks into a single task under one owner with a structured prompt listing each sub-task's requirements; the merged task counts as 1 task and 1 artifact cluster; does not apply when sub-tasks are sequenced (A's output feeds B) — those remain separate with a deps relationship",
+        "rationale": "parallel subagents targeting the same file cause merge conflicts"
+      },
+      {
+        "id": "generated_artifacts",
+        "description": "Files that are build output and do not represent independent authoring decisions.",
+        "applies_when": "files are build output (e.g., paths declared as build outputs in the harness's build configuration)",
+        "treatment": "excluded from task count, artifact cluster file count, and line count calculations; committed as part of the task that triggers their generation",
+        "rationale": "generated files do not represent independent authoring decisions"
+      }
+    ],
+    "memory_policy": {
+      "categories": [
+        {
+          "id": "empirical",
+          "prefix": "empirical-",
+          "description": "Empirically verified findings — observations and measurements that 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.\n"
+        },
+        {
+          "id": "external",
+          "prefix": "external-",
+          "description": "External constraints and references — requirements imposed by upstream dependencies, third-party API limits, vendor documentation quotations, and any knowledge that originates outside the project. May become stale if the upstream source changes.\n"
+        },
+        {
+          "id": "pattern",
+          "prefix": "pattern-",
+          "description": "Tactical operational patterns — recurring cycle-level recipes, routing heuristics, and procedural knowledge developed through work on the project. Architectural or design-level patterns belong in .nexus/context/, not here.\n"
+        }
+      ],
+      "naming": {
+        "pattern": "^[a-z0-9][a-z0-9-]*\\.md$",
+        "description": "Memory filenames are lowercase kebab-case .md files. The name should be a descriptive topic of 2–4 words. An optional category prefix from the categories section above may precede the topic. Version numbers and dates must not appear in filenames — temporal information belongs inside the file.\n",
+        "optional_prefix": true
+      },
+      "access_tracking": {
+        "observation_primitive": "file_read",
+        "scope": ".nexus/memory/",
+        "description": "Harnesses observe the moment an agent reads a memory file. Save events, directory scans (glob, grep), and mentions of the path in prose are not observation events. The set of events observed determines the accumulated access record.\n",
+        "information_accumulated": [
+          {
+            "name": "last_access_timestamp",
+            "meaning": "Wall-clock time of the most recent read event. Field name is harness-local; the canonical schema for storage is conformance/state-schemas/memory-access.schema.json.\n"
+          },
+          {
+            "name": "access_count",
+            "meaning": "Cumulative count of read events observed for this file since tracking began.\n"
+          },
+          {
+            "name": "last_reader_identity",
+            "meaning": "Identifier of the most recent reader (agent id or equivalent). Harness-local value domain.\n"
+          }
+        ],
+        "storage_contract_reference": "conformance/state-schemas/memory-access.schema.json"
+      },
+      "forgetting": {
+        "manual_gate_default": true,
+        "description": "Manual gc (triggered by the [m:gc] tag) is the default forgetting path. Automatic deletion is opt-in per consumer and never runs without explicit enablement.\n",
+        "automatic_deletion_structure": {
+          "principle": "minimum_three_signal_intersection",
+          "description": "If a consumer enables automatic deletion, the policy must require the simultaneous satisfaction of at least three independent signals — for example, elapsed time since last access, cycles since last read, and cumulative access count. Single-signal automatic deletion is prohibited. The specific signal thresholds are consumer-local and must be set to match the project's cycle cadence.\n"
+        },
+        "recoverable_deletion_requirement": "git_commit",
+        "recoverable_deletion_description": "Every memory file deletion must be recorded as a git commit. The commit message should include a recovery path that allows the file to be reconstructed via git history. Specific commit message format is consumer-local.\n"
+      },
+      "merge": {
+        "principle": "merge_before_create",
+        "description": "When a new memory save candidate substantively overlaps an existing file in topic and category, merging the new content into the existing file is preferred over creating a new file. Specific overlap-detection criteria (for example, keyword match thresholds) are consumer-local.\n"
       }
-    ]
+    }
   }
 }

package/package.json

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

package/schema/manifest.schema.json

@@ -63,13 +63,15 @@
     "vocabulary": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["capabilities", "categories", "resume_tiers", "tags", "invocations"],
+      "required": ["capabilities", "categories", "resume_tiers", "tags", "invocations", "task_exceptions", "memory_policy"],
       "properties": {
         "capabilities": { "type": "array" },
         "categories": { "type": "array" },
         "resume_tiers": { "type": "array" },
         "tags": { "type": "array" },
-        "invocations": { "type": "array" }
+        "invocations": { "type": "array" },
+        "task_exceptions": { "type": "array" },
+        "memory_policy": { "type": "object" }
       }
     }
   }

package/schema/memory-policy.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://moreih29/nexus-core/schema/memory-policy.schema.json",
+  "title": "Nexus Memory Policy",
+  "description": "Schema for vocabulary/memory_policy.yml — canonical memory policy for .nexus/memory/.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["categories", "naming", "access_tracking", "forgetting", "merge"],
+  "properties": {
+    "categories": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "prefix", "description"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "prefix": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "naming": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pattern", "description", "optional_prefix"],
+      "properties": {
+        "pattern": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "optional_prefix": { "type": "boolean" }
+      }
+    },
+    "access_tracking": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "observation_primitive",
+        "scope",
+        "description",
+        "information_accumulated",
+        "storage_contract_reference"
+      ],
+      "properties": {
+        "observation_primitive": { "type": "string", "minLength": 1 },
+        "scope": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "information_accumulated": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "meaning"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "meaning": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "storage_contract_reference": { "type": "string", "minLength": 1 }
+      }
+    },
+    "forgetting": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "manual_gate_default",
+        "description",
+        "automatic_deletion_structure",
+        "recoverable_deletion_requirement",
+        "recoverable_deletion_description"
+      ],
+      "properties": {
+        "manual_gate_default": { "type": "boolean" },
+        "description": { "type": "string", "minLength": 1 },
+        "automatic_deletion_structure": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["principle", "description"],
+          "properties": {
+            "principle": { "type": "string", "minLength": 1 },
+            "description": { "type": "string", "minLength": 1 }
+          }
+        },
+        "recoverable_deletion_requirement": { "type": "string", "minLength": 1 },
+        "recoverable_deletion_description": { "type": "string", "minLength": 1 }
+      }
+    },
+    "merge": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["principle", "description"],
+      "properties": {
+        "principle": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schema/task-exceptions.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://moreih29/nexus-core/schema/task-exceptions.schema.json",
+  "title": "Nexus Task Exceptions vocabulary file",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["task_exceptions"],
+  "properties": {
+    "task_exceptions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "description", "applies_when", "treatment", "rationale"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)?$"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1
+          },
+          "applies_when": {
+            "type": "string",
+            "minLength": 1
+          },
+          "treatment": {
+            "type": "string",
+            "minLength": 1
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/schema/vocabulary.schema.json

@@ -70,7 +70,8 @@
         "description": { "$ref": "common.schema.json#/$defs/description" },
         "skill": { "$ref": "common.schema.json#/$defs/id" },
         "handler": { "type": "string", "minLength": 1 },
-        "variants": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+        "variants": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "prose_guidance": { "type": "string", "minLength": 40 }
       },
       "if": {
         "properties": { "type": { "const": "skill" } },
@@ -137,6 +138,30 @@
       "properties": {
         "invocations": { "type": "array", "items": { "$ref": "#/$defs/invocationEntry" } }
       }
-    }
+    },
+    "taskExceptionEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "description", "applies_when", "treatment", "rationale"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)?$"
+        },
+        "description": { "type": "string", "minLength": 1 },
+        "applies_when": { "type": "string", "minLength": 1 },
+        "treatment": { "type": "string", "minLength": 1 },
+        "rationale": { "type": "string", "minLength": 1 }
+      }
+    },
+    "taskExceptionFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_exceptions"],
+      "properties": {
+        "task_exceptions": { "type": "array", "items": { "$ref": "#/$defs/taskExceptionEntry" } }
+      }
+    },
+    "memoryPolicyFile": { "$ref": "memory-policy.schema.json" }
   }
 }

package/scripts/lib/validate.ts

@@ -81,12 +81,30 @@ interface InvocationEntry {
   fallback_behavior: string;
 }
 
+interface TaskExceptionEntry {
+  id: string;
+  description: string;
+  applies_when: string;
+  treatment: string;
+  rationale: string;
+}
+
+interface MemoryPolicy {
+  categories: unknown[];
+  naming: unknown;
+  access_tracking: unknown;
+  forgetting: unknown;
+  merge: unknown;
+}
+
 interface Vocab {
   capabilities: CapabilityEntry[];
   categories: SimpleEntry[];
   resume_tiers: SimpleEntry[];
   tags: TagEntry[];
   invocations: InvocationEntry[];
+  task_exceptions: TaskExceptionEntry[];
+  memory_policy: MemoryPolicy;
 }
 
 interface ManifestAgent extends AgentMeta {
@@ -116,6 +134,8 @@ interface Manifest {
     resume_tiers: SimpleEntry[];
     tags: TagEntry[];
     invocations: ManifestInvocationEntry[];
+    task_exceptions: TaskExceptionEntry[];
+    memory_policy: MemoryPolicy;
   };
 }
 
@@ -129,6 +149,8 @@ interface LoadedSchemas {
   skillValidator: ValidateFunction;
   vocabValidator: ValidateFunction;
   manifestValidator: ValidateFunction;
+  taskExceptionValidator: ValidateFunction;
+  memoryPolicyValidator: ValidateFunction;
 }
 
 let cachedSchemas: LoadedSchemas | null = null;
@@ -152,12 +174,14 @@ export async function loadSchemas(root: string): Promise<void> {
   addFormats(ajv);
   ajvErrors(ajv);
 
-  const [commonRaw, agentRaw, skillRaw, vocabRaw, manifestRaw] = await Promise.all([
+  const [commonRaw, agentRaw, skillRaw, vocabRaw, manifestRaw, taskExceptionSchemaRaw, memoryPolicySchemaRaw] = await Promise.all([
     readFile(path.join(schemaDir, 'common.schema.json'), 'utf8'),
     readFile(path.join(schemaDir, 'agent.schema.json'), 'utf8'),
     readFile(path.join(schemaDir, 'skill.schema.json'), 'utf8'),
     readFile(path.join(schemaDir, 'vocabulary.schema.json'), 'utf8'),
     readFile(path.join(schemaDir, 'manifest.schema.json'), 'utf8'),
+    readFile(path.join(schemaDir, 'task-exceptions.schema.json'), 'utf8'),
+    readFile(path.join(schemaDir, 'memory-policy.schema.json'), 'utf8'),
   ]);
 
   const commonSchema = JSON.parse(commonRaw) as Record<string, unknown>;
@@ -165,6 +189,8 @@ export async function loadSchemas(root: string): Promise<void> {
   const skillSchema = JSON.parse(skillRaw) as Record<string, unknown>;
   const vocabSchema = JSON.parse(vocabRaw) as Record<string, unknown>;
   const manifestSchema = JSON.parse(manifestRaw) as Record<string, unknown>;
+  const taskExceptionSchema = JSON.parse(taskExceptionSchemaRaw) as Record<string, unknown>;
+  const memoryPolicySchema = JSON.parse(memoryPolicySchemaRaw) as Record<string, unknown>;
 
   ajv.addSchema(commonSchema);
   ajv.addSchema(vocabSchema);
@@ -210,6 +236,8 @@ export async function loadSchemas(root: string): Promise<void> {
   const resumeTierValidator = await ajv.compileAsync(resumeTierFileSchema);
   const tagValidator = await ajv.compileAsync(tagFileSchema);
   const invocationValidator = await ajv.compileAsync(invocationFileSchema);
+  const taskExceptionValidator = await ajv.compileAsync(taskExceptionSchema);
+  const memoryPolicyValidator = await ajv.compileAsync(memoryPolicySchema);
 
   const manifestAjv = new Ajv2020({
     strict: false,
@@ -233,10 +261,12 @@ export async function loadSchemas(root: string): Promise<void> {
     // Store vocabulary validators and manifest as composite
     vocabValidator: capabilityValidator, // placeholder — we handle vocab separately below
     manifestValidator,
+    taskExceptionValidator,
+    memoryPolicyValidator,
   };
 
   // Store all vocab validators for internal use
-  _vocabValidators = { capabilityValidator, categoryValidator, resumeTierValidator, tagValidator, invocationValidator };
+  _vocabValidators = { capabilityValidator, categoryValidator, resumeTierValidator, tagValidator, invocationValidator, taskExceptionValidator, memoryPolicyValidator };
 }
 
 interface VocabValidators {
@@ -245,6 +275,8 @@ interface VocabValidators {
   resumeTierValidator: ValidateFunction;
   tagValidator: ValidateFunction;
   invocationValidator: ValidateFunction;
+  taskExceptionValidator: ValidateFunction;
+  memoryPolicyValidator: ValidateFunction;
 }
 
 let _vocabValidators: VocabValidators | null = null;
@@ -559,15 +591,17 @@ async function loadVocab(root: string): Promise<{ vocab: Vocab | null; results:
     return data as T;
   }
 
-  const [capData, catData, resumeData, tagData, invocationData] = await Promise.all([
+  const [capData, catData, resumeData, tagData, invocationData, taskExceptionData, memoryPolicyData] = await Promise.all([
     loadYaml<{ capabilities: CapabilityEntry[] }>('capabilities.yml', _vocabValidators.capabilityValidator),
     loadYaml<{ categories: SimpleEntry[] }>('categories.yml', _vocabValidators.categoryValidator),
     loadYaml<{ resume_tiers: SimpleEntry[] }>('resume-tiers.yml', _vocabValidators.resumeTierValidator),
     loadYaml<{ tags: TagEntry[] }>('tags.yml', _vocabValidators.tagValidator),
     loadYaml<{ invocations: InvocationEntry[] }>('invocations.yml', _vocabValidators.invocationValidator),
+    loadYaml<{ task_exceptions: TaskExceptionEntry[] }>('task-exceptions.yml', _vocabValidators.taskExceptionValidator),
+    loadYaml<MemoryPolicy>('memory_policy.yml', _vocabValidators.memoryPolicyValidator),
   ]);
 
-  if (!capData || !catData || !resumeData || !tagData || !invocationData) {
+  if (!capData || !catData || !resumeData || !tagData || !invocationData || !taskExceptionData || !memoryPolicyData) {
     return { vocab: null, results };
   }
 
@@ -578,6 +612,8 @@ async function loadVocab(root: string): Promise<{ vocab: Vocab | null; results:
       resume_tiers: resumeData.resume_tiers,
       tags: tagData.tags,
       invocations: invocationData.invocations,
+      task_exceptions: taskExceptionData.task_exceptions,
+      memory_policy: memoryPolicyData,
     },
     results,
   };
@@ -636,6 +672,8 @@ export async function generateManifest(
       resume_tiers: vocab.resume_tiers,
       tags: vocab.tags,
       invocations: invocationSummaries,
+      task_exceptions: vocab.task_exceptions,
+      memory_policy: vocab.memory_policy,
     },
   };
 }

package/skills/nx-plan/body.md

@@ -220,12 +220,21 @@ All issues decided → generate the plan document (tasks.json) immediately:
    | Design analysis / review | **architect** etc. HOW | Technical trade-off judgment |
    | Sequential edits to same file | **lead** | Parallel subagents risk conflict |
 
-   **Verification auto-pairing** — create separate verification tasks:
-   - Any task with `owner: "engineer"` + `acceptance` field → pair a **tester** task (verify acceptance criteria)
-   - Any task with `owner: "writer"` → pair a **reviewer** task (verify deliverable)
-   - Paired verification tasks are linked via `deps` to the original task
+   **Primary metric — artifact-coherence**: a well-scoped task targets a single artifact or a tightly coupled artifact cluster and makes a single coherent change. A change is coherent when (a) it can be described in one sentence, (b) reverting it leaves all other artifacts consistent, and (c) its acceptance can be verified by inspecting its outputs alone.
 
-   **DO/CHECK decomposition principle**: DO category agents (engineer, writer, researcher) and CHECK category agents (tester, reviewer) operate on artifact-level scope and accumulate less per-task context than HOW category agents. When a task involves multiple independent artifacts (several files, several verification targets, multiple research questions), decompose the task across multiple parallel DO/CHECK subagents rather than bundling them into a single subagent. Single-subagent bundles risk context exhaustion with no wall-clock benefit over parallel decomposition. HOW agents benefit from consolidated context and should generally remain as single sessions. Task granularity is assessed per-task by the plan author, not declared per-agent in meta.yml.
+   **Verification auto-pairing (conditional)** — create a CHECK task only when the DO task's acceptance includes the appropriate verification trigger:
+   - `owner: "engineer"` + acceptance contains a runtime-behavior criterion → pair a **tester** task.
+   - `owner: "writer"` + acceptance contains a verifiable deliverable criterion → pair a **reviewer** task.
+   - Exclusions: pure refactor (behavior-preserving), type-only changes, docs-adjacent tasks (.md or frontmatter-only, classified under `docs_only` entries in `vocabulary/task-exceptions.yml`), and researcher tasks. Researcher tasks never receive an auto-paired CHECK — research outputs feed Lead or HOW agents directly, not tester or reviewer.
+   - Paired verification tasks are linked via `deps` to the original task.
+
+   **Exception catalog**: task decomposition exceptions are defined in `vocabulary/task-exceptions.yml` (`docs_only.coherent`, `docs_only.independent`, `same_file_bundle`, `generated_artifacts`). When an exception applies to a task, record its id in the task's `context` field so downstream tooling can trace the classification.
+
+   **Dedup Layer 1 (plan-time static merge)**: before finalizing the task list, scan draft tasks for overlapping target_files. Overlapping tasks are merged into a single owner task via the `same_file_bundle` exception from `vocabulary/task-exceptions.yml` to prevent parallel write conflicts during execution.
+
+   **DO/CHECK decomposition principle**: DO agents (engineer, writer, researcher) and CHECK agents (tester, reviewer) accumulate less per-task context than HOW agents. When a task involves multiple independent artifacts, decompose across multiple parallel DO/CHECK subagents rather than bundling. HOW agents benefit from consolidated context and should generally remain as single sessions. Parallel decomposition is worthwhile when there are at least three independent artifacts; below that, bundling under one owner is preferable to avoid parallelization overhead.
+
+   **HOW decomposition rule**: split HOW analysis across multiple subagents only when the issue crosses different rows of the domain-agent mapping table (architect vs designer vs strategist vs postdoc). Sub-concerns within a single domain row belong in one HOW session.
 
 4. **Populate tasks.json** via `nx_task_add`:
    - Set `goal` from the plan topic

package/vocabulary/invocations.yml

@@ -114,3 +114,34 @@ invocations:
       numbered list, then await the user's free-form reply. The LLM is
       expected to map the reply to the most appropriate option or treat it
       as a free-form answer if no options were given.
+
+  - id: memory_read_observation
+    description: >
+      Harness-local observation of an agent reading a file under .nexus/memory/.
+      This invocation captures the moment a memory file's content is loaded into
+      an agent's context. It is not the read action itself — the read is performed
+      by the harness's file-read primitive — but the observation event emitted by
+      the harness after the read completes.
+    intent: memory_read_observation
+    semantic_params:
+      - name: file_path
+        description: Absolute or project-relative path to the memory file that was read.
+        required: true
+      - name: reader_identity
+        description: Opaque identifier of the agent or subject that performed the read.
+        required: true
+      - name: observed_at
+        description: ISO 8601 timestamp of the observation event.
+        required: true
+    prose_guidance: >
+      Harnesses that wish to track memory access to support informed gc decisions
+      should implement this observation by hooking into their filesystem read
+      primitive and emitting the event after a read under .nexus/memory/ completes.
+      Writes and directory scans are excluded. The accumulated records are persisted
+      per conformance/state-schemas/memory-access.schema.json at
+      .nexus/state/{harness_id}/memory-access.jsonl.
+    fallback_behavior: >
+      If the harness cannot observe file-read events (no equivalent hook), memory
+      access tracking is unavailable and forgetting decisions must rely on manual
+      inspection via the [m:gc] tag. Automatic deletion policies requiring access
+      metadata are consequently not enabled in such harnesses.

package/vocabulary/memory_policy.yml

@@ -0,0 +1,88 @@
+# Canonical memory policy vocabulary for .nexus/memory/.
+# Defines categories, naming conventions, access tracking semantics,
+# forgetting policy, and merge preference.
+# Consumers (claude-nexus, opencode-nexus) read this file; specific thresholds
+# and enforcement mechanics are consumer-local.
+
+categories:
+  - id: empirical
+    prefix: empirical-
+    description: >
+      Empirically verified findings — observations and measurements that 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.
+  - id: external
+    prefix: external-
+    description: >
+      External constraints and references — requirements imposed by upstream
+      dependencies, third-party API limits, vendor documentation quotations, and
+      any knowledge that originates outside the project. May become stale if
+      the upstream source changes.
+  - id: pattern
+    prefix: pattern-
+    description: >
+      Tactical operational patterns — recurring cycle-level recipes, routing
+      heuristics, and procedural knowledge developed through work on the project.
+      Architectural or design-level patterns belong in .nexus/context/, not here.
+
+naming:
+  pattern: "^[a-z0-9][a-z0-9-]*\\.md$"
+  description: >
+    Memory filenames are lowercase kebab-case .md files. The name should be a
+    descriptive topic of 2–4 words. An optional category prefix from the
+    categories section above may precede the topic. Version numbers and dates
+    must not appear in filenames — temporal information belongs inside the file.
+  optional_prefix: true
+
+access_tracking:
+  observation_primitive: file_read
+  scope: .nexus/memory/
+  description: >
+    Harnesses observe the moment an agent reads a memory file. Save events,
+    directory scans (glob, grep), and mentions of the path in prose are not
+    observation events. The set of events observed determines the accumulated
+    access record.
+  information_accumulated:
+    - name: last_access_timestamp
+      meaning: >
+        Wall-clock time of the most recent read event. Field name is harness-local;
+        the canonical schema for storage is conformance/state-schemas/memory-access.schema.json.
+    - name: access_count
+      meaning: >
+        Cumulative count of read events observed for this file since tracking began.
+    - name: last_reader_identity
+      meaning: >
+        Identifier of the most recent reader (agent id or equivalent). Harness-local
+        value domain.
+  storage_contract_reference: conformance/state-schemas/memory-access.schema.json
+
+forgetting:
+  manual_gate_default: true
+  description: >
+    Manual gc (triggered by the [m:gc] tag) is the default forgetting path.
+    Automatic deletion is opt-in per consumer and never runs without explicit
+    enablement.
+  automatic_deletion_structure:
+    principle: minimum_three_signal_intersection
+    description: >
+      If a consumer enables automatic deletion, the policy must require the
+      simultaneous satisfaction of at least three independent signals — for
+      example, elapsed time since last access, cycles since last read, and
+      cumulative access count. Single-signal automatic deletion is prohibited.
+      The specific signal thresholds are consumer-local and must be set to
+      match the project's cycle cadence.
+  recoverable_deletion_requirement: git_commit
+  recoverable_deletion_description: >
+    Every memory file deletion must be recorded as a git commit. The commit
+    message should include a recovery path that allows the file to be
+    reconstructed via git history. Specific commit message format is
+    consumer-local.
+
+merge:
+  principle: merge_before_create
+  description: >
+    When a new memory save candidate substantively overlaps an existing file
+    in topic and category, merging the new content into the existing file is
+    preferred over creating a new file. Specific overlap-detection criteria
+    (for example, keyword match thresholds) are consumer-local.

package/vocabulary/tags.yml

@@ -36,12 +36,21 @@ tags:
     type: inline_action
     handler: memory_store
     description: "Stores a lesson or reference to .nexus/memory/"
+    prose_guidance: >
+      저장 admission 기준 — 코드/웹에서 다시 얻을 수 없는 정보만 저장한다.
+      memory 파일의 naming, category, lifecycle 운영 정책은
+      vocabulary/memory_policy.yml과 docs/memory-lifecycle-contract.md를
+      canonical source로 참조한다.
 
   - id: m-gc
     trigger: "[m:gc]"
     type: inline_action
     handler: memory_gc
     description: "Garbage-collects .nexus/memory/ by merging or removing stale entries"
+    prose_guidance: >
+      gc 트리거 조건 평가, merge 판단, forgetting policy 집행은
+      vocabulary/memory_policy.yml에 정의된 원칙을 따르고
+      구체 임계값은 consumer-local 설정으로 결정한다.
 
   - id: rule
     trigger: "[rule]"

package/vocabulary/task-exceptions.yml

@@ -0,0 +1,29 @@
+# Canonical exception rules for task decomposition and counting.
+# Each entry defines a condition under which standard task decomposition rules
+# are suspended or modified, along with the alternative treatment to apply.
+# Consumers apply these exceptions during nx-plan task synthesis.
+
+task_exceptions:
+  - id: docs_only.coherent
+    description: "A batch of documentation files that all address the same scheme, decision, or structural change and should be treated as a single coherent unit."
+    applies_when: "all changed files are .md or frontmatter-only, and share one common scheme, decision, or structural change"
+    treatment: "bundle into 1 writer task + 1 reviewer pair; file count / line count thresholds waived; state coherence claim in task approach field"
+    rationale: "e.g., updating agent frontmatter files after a new field is introduced; files share the same change intent"
+
+  - id: docs_only.independent
+    description: "A set of documentation files where each file addresses a distinct topic with no cross-reference dependency."
+    applies_when: "each .md file addresses a distinct topic with no cross-reference dependency"
+    treatment: "N parallel writer tasks (one per file), each paired with 1 reviewer task; file count threshold waived per-task"
+    rationale: "e.g., separate proposal drafts; each file is independently consumed"
+
+  - id: same_file_bundle
+    description: "Two or more decomposed sub-tasks that would each modify the same target file, requiring merger to avoid conflicts."
+    applies_when: "two or more sub-tasks in the decomposition would each modify the same target file"
+    treatment: "merge sub-tasks into a single task under one owner with a structured prompt listing each sub-task's requirements; the merged task counts as 1 task and 1 artifact cluster; does not apply when sub-tasks are sequenced (A's output feeds B) — those remain separate with a deps relationship"
+    rationale: "parallel subagents targeting the same file cause merge conflicts"
+
+  - id: generated_artifacts
+    description: "Files that are build output and do not represent independent authoring decisions."
+    applies_when: "files are build output (e.g., paths declared as build outputs in the harness's build configuration)"
+    treatment: "excluded from task count, artifact cluster file count, and line count calculations; committed as part of the task that triggers their generation"
+    rationale: "generated files do not represent independent authoring decisions"