@moreih29/nexus-core 0.9.0 → 0.11.0

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"