@moreih29/nexus-core 0.11.0 → 0.12.0

package/docs/consumer-implementation-guide.md

@@ -439,12 +439,19 @@ User types "[plan] analyze the architecture"
    - Also read skills/{skill_id}/meta.yml to check for harness_docs_refs
      |
      v
-4. LLM Context Injection
-   - Inject the body.md content into the LLM's operating context
-   - HOW to inject is consumer's decision:
-     a. System prompt injection — most common; replaces or appends to the system prompt
-     b. Tool-response injection — return body.md as a tool response the LLM reads
-     c. User-message prefix — prepend body.md to the next user message
+4. Skill Activation
+   - Consumers SHOULD prefer the harness's native skill-registration 
+     or command-dispatch primitive — any mechanism by which the harness 
+     natively exposes user-invocable behavioral modes to the LLM — 
+     over raw prompt concatenation. The skill body.md content becomes 
+     the registered skill's operating specification.
+   - Only when no such native primitive exists, fall back to context injection:
+     a. System prompt injection
+     b. Tool-response injection
+     c. User-message prefix
+   - The name and concrete shape of the native primitive are consumer-owned;
+     nexus-core specifies only that such a mechanism, when available, is 
+     the preferred activation path.
    - Also inject harness-specific context for any harness_docs_refs declared in meta.yml
    - The body.md content BECOMES the LLM's operating instructions for this skill
      |
@@ -505,16 +512,11 @@ Hooks are the consumer's mechanism for responding to lifecycle events. nexus-cor
 
 ### 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.
+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. Each bullet in §9 describes behavior the consumer implements in hook handler code — specifying what prompt context should be injected at the hook's firing moment. These specifications are authored for consumer developers; nexus-core does not inject §9 prose itself into LLM runtime context.
 
 ### Event mapping examples
 
-Different harnesses expose these events under different names:
-
-- **(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.
+Different harnesses expose these events under different names. Identify the equivalent events in your harness's plugin system and implement the expected behaviors below.
 
 ### 8 lifecycle events
 
@@ -564,7 +566,6 @@ Identify the equivalent events in your harness's plugin system and implement the
 **Expected consumer behavior:**
 - **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.
 
@@ -590,8 +591,7 @@ Read-only tools (query tools, status reads) are never blocked by capability gate
 **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:**
-- **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.
+- **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 — schema definition pending.)
 - **MAY** record the error in the log for diagnostic purposes if the tool result indicates an error. Do not suppress error results.
 
 ---
@@ -625,18 +625,6 @@ Read-only tools (query tools, status reads) are never blocked by capability gate
 
 ---
 
-### 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.
-
----
-
 ## 10. Subagent Orchestration Model
 
 Subagent orchestration is the mechanism by which Lead delegates work to specialized agents. nexus-core specifies the behavioral contracts; the implementation mechanism is consumer-decided.

package/manifest.json

@@ -1,6 +1,6 @@
 {
-  "nexus_core_version": "0.11.0",
-  "nexus_core_commit": "7d32c9e06ec206980cbc1399d29c8cb754cd0d5a",
+  "nexus_core_version": "0.12.0",
+  "nexus_core_commit": "f2aae4883f354d1d0e5ee06f163c96c2b0f9bea3",
   "schema_contract_version": "2.0",
   "agents": [
     {
@@ -50,25 +50,10 @@
       "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
     },
     {
-      "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"
-      ],
-      "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": "전략가",
+      "name": "postdoc",
+      "description": "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents",
+      "task": "Research methodology, evidence synthesis",
+      "alias_ko": "포닥",
       "category": "how",
       "resume_tier": "persistent",
       "model_tier": "high",
@@ -77,8 +62,8 @@
         "no_task_create",
         "no_task_update"
       ],
-      "id": "strategist",
-      "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
+      "id": "postdoc",
+      "body_hash": "sha256:da9b8c2568b8b5812abed6d6324139f814379d48dc63cdc5d0b5b263f5407814"
     },
     {
       "name": "researcher",
@@ -96,10 +81,25 @@
       "body_hash": "sha256:fc79bafec05503327bd51a0b84b6e642d304bd79c45b78db6448b112793c143e"
     },
     {
-      "name": "postdoc",
-      "description": "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents",
-      "task": "Research methodology, evidence synthesis",
-      "alias_ko": "포닥",
+      "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"
+      ],
+      "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",
@@ -108,8 +108,8 @@
         "no_task_create",
         "no_task_update"
       ],
-      "id": "postdoc",
-      "body_hash": "sha256:da9b8c2568b8b5812abed6d6324139f814379d48dc63cdc5d0b5b263f5407814"
+      "id": "strategist",
+      "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
     },
     {
       "name": "tester",
@@ -154,16 +154,6 @@
       "id": "nx-init",
       "body_hash": "sha256:b828a974ab4722dd7f1d15a4338d1380fdae47cd42c1bd4a5539277075efb6fc"
     },
-    {
-      "name": "nx-sync",
-      "description": "Context knowledge synchronization — scans project state and updates .nexus/context/ design documents",
-      "summary": "Context knowledge synchronization",
-      "triggers": [
-        "sync"
-      ],
-      "id": "nx-sync",
-      "body_hash": "sha256:3ee8dd780d53f2e04472de6c701e16bc1fbde7f2ce9ed4e680b7cd2010530a22"
-    },
     {
       "name": "nx-plan",
       "description": "Structured multi-perspective analysis to decompose issues, align on decisions, and produce an enriched plan before execution. Plan only — does not execute.",
@@ -185,11 +175,20 @@
         "run"
       ],
       "harness_docs_refs": [
-        "resume_invocation",
-        "nexus_hook_mapping"
+        "resume_invocation"
       ],
       "id": "nx-run",
       "body_hash": "sha256:0e2c443efceeab4621709a85cd4e2ba50471d2e850680c655d776cbb62814549"
+    },
+    {
+      "name": "nx-sync",
+      "description": "Context knowledge synchronization — scans project state and updates .nexus/context/ design documents",
+      "summary": "Context knowledge synchronization",
+      "triggers": [
+        "sync"
+      ],
+      "id": "nx-sync",
+      "body_hash": "sha256:3ee8dd780d53f2e04472de6c701e16bc1fbde7f2ce9ed4e680b7cd2010530a22"
     }
   ],
   "vocabulary": {

package/package.json

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

package/scripts/lib/validate.ts

@@ -645,6 +645,7 @@ export async function generateManifest(
       return { ...meta, body_hash };
     })
   );
+  agentEntries.sort((a, b) => a.id.localeCompare(b.id));
 
   const skillEntries: ManifestSkill[] = await Promise.all(
     skills.map(async ({ meta, dir }) => {
@@ -652,6 +653,7 @@ export async function generateManifest(
       return { ...meta, body_hash };
     })
   );
+  skillEntries.sort((a, b) => a.id.localeCompare(b.id));
 
   const invocationSummaries: ManifestInvocationEntry[] = vocab.invocations.map((inv) => ({
     id: inv.id,

package/skills/nx-run/meta.yml

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