@moreih29/nexus-core 0.11.0 → 0.13.0

package/docs/consumer-implementation-guide.md

@@ -1,852 +0,0 @@
-# Nexus Consumer Implementation Guide
-
-**Version:** nexus-core 0.2.0
-**Audience:** Developers building a Nexus consumer harness from scratch.
-
----
-
-## Table of Contents
-
-1. [Overview](#1-overview)
-2. [Prerequisites](#2-prerequisites)
-3. [Component Map and Build Order](#3-component-map-and-build-order)
-4. [State File Management](#4-state-file-management)
-5. [MCP Tool Implementation](#5-mcp-tool-implementation)
-6. [Capability Handling](#6-capability-handling)
-7. [Agent Catalog Construction](#7-agent-catalog-construction)
-8. [Skill Activation Architecture](#8-skill-activation-architecture)
-9. [Hook Event Lifecycle](#9-hook-event-lifecycle)
-10. [Subagent Orchestration Model](#10-subagent-orchestration-model)
-11. [Conformance Verification](#11-conformance-verification)
-12. [Minimum Viable Consumer](#12-minimum-viable-consumer)
-
----
-
-## 1. Overview
-
-A **Nexus consumer** is an execution-layer harness that reads nexus-core and orchestrates agents on behalf of the user. nexus-core is the authoring layer: it defines prompts, metadata, vocabulary, schemas, conformance fixtures, and documentation. The consumer is the runtime layer: it implements tool execution, spawns agents, enforces capability gates, and manages session state.
-
-### What nexus-core provides
-
-- **Agent prompts** — `agents/{id}/body.md`, harness-neutral behavioral specifications for each agent role
-- **Skill prompts** — `skills/{id}/body.md`, full behavioral specifications for each skill
-- **Metadata** — `agents/{id}/meta.yml` and `skills/{id}/meta.yml`, structured descriptions of each agent and skill
-- **Manifest** — `manifest.json`, a single-file snapshot of all agents, skills, and vocabulary for the current version
-- **Vocabulary** — `vocabulary/capabilities.yml`, `tags.yml`, `resume-tiers.yml`, `categories.yml`, abstract definitions of the Nexus semantic model
-- **Schemas** — `schema/*.json`, JSON Schema definitions for all data structures
-- **Conformance fixtures** — `conformance/tools/*.json` and `conformance/scenarios/*.json`, declarative behavioral tests
-- **Documentation** — `docs/`, normative specifications for tools, state files, layout, and behavioral contracts
-
-### What the consumer builds
-
-- **Runtime orchestration** — session start/end logic, cycle management, state file creation and cleanup
-- **Tool implementation** — concrete implementations of the 11 abstract Nexus tools
-- **Hook system** — lifecycle event handlers that fire at well-defined points in the session
-- **Capability mapping** — a local file that translates abstract capability IDs to concrete disallowed tools in your harness
-- **Agent catalog** — your harness's agent registration, populated from nexus-core agent definitions
-- **Skill dispatcher** — tag detection and skill body injection
-- **Subagent orchestration** — spawn, context injection, resume evaluation, result collection
-- **UI integration** — your harness's plugin registration, command system, and inter-process communication
-
-### How to use this guide
-
-Read this guide cover to cover before writing any code. The sections are ordered by build dependency: later sections assume the structures established by earlier ones. Jumping ahead and implementing subagent orchestration before state file management or tool implementation is defined will produce integration failures that are difficult to diagnose.
-
-Cross-reference the normative specifications linked throughout. This guide describes what to build and in what order; the linked documents define the precise contracts your implementation must satisfy.
-
----
-
-## 2. Prerequisites
-
-### Package installation
-
-Install nexus-core as a development dependency. It is not shipped to end users — it is consumed at build time by your harness.
-
-```
-npm install --save-dev @moreih29/nexus-core
-```
-
-After installation, the package is available at `node_modules/@moreih29/nexus-core/`. All paths in this guide referencing nexus-core files resolve from that root.
-
-### Knowledge prerequisites
-
-Before building a consumer, you must be familiar with:
-
-1. **Your harness's plugin system** — how to register tools that the LLM can call, how hooks are declared and fire, and how to inject content into the LLM's context (system prompt, tool response, or user message prefix).
-2. **Your harness's agent/subprocess model** — how to spawn an isolated LLM session, how to pass initial context, and how to receive the result.
-3. **JSON and YAML** — all nexus-core metadata files are YAML or JSON; all state files are JSON.
-
-### Primary entry points
-
-Begin your implementation by reading these files in order:
-
-1. `manifest.json` — the complete catalog of agents, skills, and vocabulary for the installed version. This is your primary lookup source; most implementation tasks start here.
-2. `docs/nexus-tools-contract.md` — normative specifications for all 11 tools: parameters, return values, side effects, and error conditions. Read this before implementing any tool.
-3. `docs/nexus-state-overview.md` — lifecycle and tool access table for every state file.
-4. `docs/nexus-layout.md` — the canonical `.nexus/` directory structure your harness must create.
-5. `docs/behavioral-contracts.md` — state machines, permission model, resume tier semantics, and the `manual_only` contract.
-
----
-
-## 3. Component Map and Build Order
-
-A complete Nexus consumer comprises nine components. They have hard dependencies: some components cannot be implemented until others are in place. Build them in the order shown.
-
-### Components
-
-| # | Component | Description |
-|---|-----------|-------------|
-| 1 | `.nexus/` Directory Initialization | Create the required directory tree and `.gitignore` at session start |
-| 2 | State File Management | Read/write plan.json, tasks.json, history.json, agent-tracker.json |
-| 3 | MCP Tool Implementation | Concrete implementations of the 11 abstract Nexus tools |
-| 4 | Capability Mapping | Local file translating abstract capability IDs to concrete disallowed tools |
-| 5 | Agent Catalog | Load nexus-core agents, apply capability-map, register with harness |
-| 6 | Skill Dispatcher | Detect bracket tags, load skill body.md, inject into LLM context |
-| 7 | Hook/Gate System | Lifecycle event handlers: session_start, user_message, pre_tool_use, etc. |
-| 8 | Subagent Orchestration | Spawn isolated LLM sessions, pass context, collect results, evaluate resume |
-| 9 | Conformance Verification | Run fixtures against your tool implementations to verify interoperability |
-
-### Dependency graph
-
-```
-Directory Init → State File Mgmt → MCP Tools → Capability Mapping
-                                             → Agent Catalog → Skill Dispatcher
-                                             → Hook/Gate System → Subagent Orchestration
-                                                                → Conformance Verification
-```
-
-**Directory Init** must precede everything: state files cannot be written if the directory does not exist.
-
-**State File Management** must precede tool implementation: tools read and write specific files at specific paths. Without knowing the file layout, tool implementation cannot be completed.
-
-**MCP Tools** must precede Capability Mapping, Agent Catalog, and Hook/Gate: the capability-map is only useful once the tools it restricts are implemented; the agent catalog is validated against the tool set; hooks reference both.
-
-**Capability Mapping** must precede Agent Catalog: effective capabilities are computed by merging canonical capabilities with consumer additions, and that merge requires the capability-map to be defined.
-
-**Agent Catalog** must precede Skill Dispatcher: the dispatcher injects skill body alongside agent context; the agent registration format must exist first.
-
-**Hook/Gate System** must precede Subagent Orchestration: hooks fire during agent spawn and completion; the hook contracts must be defined before the orchestration logic can reference them.
-
-**Subagent Orchestration** must precede Conformance Verification: end-to-end scenario fixtures test the full lifecycle, including agent spawning.
-
-### Build order within components
-
-Within MCP Tools, implement in this recommended order:
-
-1. `plan_start`, `plan_decide` — the core planning pair; all planning workflows depend on them
-2. `plan_status`, `plan_update` — planning query and mutation
-3. `task_add`, `task_list`, `task_update`, `task_close` — execution lifecycle
-4. `history_search`, `context`, `artifact_write` — support and reporting
-
-This order matches the dependency chain within the planning/execution lifecycle. Implement and test each tool against its conformance fixtures before moving to the next.
-
----
-
-## 4. State File Management
-
-Nexus state is split into two categories with different scopes, persistence, and git-tracking rules. Your implementation must respect these boundaries exactly.
-
-### Two-category model
-
-**Session-scoped state** lives in `.nexus/state/`. It is created at session start, updated throughout the session, and deleted at session end or cycle close. It must never be git-tracked. Your `.nexus/.gitignore` must contain `state/` to enforce this.
-
-**Project-scoped content** lives directly under `.nexus/` (outside `state/`). It persists across sessions and git branches. It is git-tracked and committed to the repository.
-
-### Directory tree
-
-```
-.nexus/
-├── state/                    ← session-scoped (not git-tracked)
-│   ├── plan.json
-│   ├── tasks.json
-│   ├── tool-log.jsonl
-│   ├── artifacts/
-│   └── {harness-id}/         ← harness namespace (see §Harness-local State Extension)
-│       └── agent-tracker.json
-├── history.json              ← project-scoped (git-tracked, append-only)
-├── memory/                   ← project-scoped (git-tracked)
-│   └── *.md
-├── context/                  ← project-scoped (git-tracked, nx-sync managed)
-│   └── *.md
-├── rules/                    ← project-scoped (git-tracked, user-defined)
-│   └── *.md
-└── .gitignore
-```
-
-### Initialization sequence
-
-At session start, your harness must:
-
-1. Create `.nexus/` if it does not exist.
-2. Create `.nexus/state/` if it does not exist.
-3. Write `.nexus/.gitignore` with content `state/` if the file does not exist.
-4. Create `.nexus/state/{harness-id}/` if it does not exist, then initialize `.nexus/state/{harness-id}/agent-tracker.json` as an empty array `[]`. (`{harness-id}` is the last segment of your npm package name; see [nexus-outputs-contract.md §Shared filename convention](./nexus-outputs-contract.md) for the namespace convention.)
-5. Check for stale state files from a prior crashed session. If `plan.json` or `tasks.json` exist without a running session, warn the user that a previous session may not have closed cleanly.
-
-### Key state files
-
-| File | Scope | Git-tracked | Created by | Deleted by |
-|------|-------|------------|------------|------------|
-| `state/plan.json` | Session | No | `plan_start` tool | `task_close` tool |
-| `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 |
-| `history.json` | Project | Yes | `plan_start` or `task_close` (first archive) | Never |
-
-### Schema validation
-
-JSON Schema definitions for all state files are available in `conformance/state-schemas/`. The schemas cover `plan.json`, `tasks.json`, `history.json`, and `agent-tracker.json`. Validate state files against these schemas in your test suite.
-
-For full lifecycle and tool access details, see [nexus-state-overview.md](./nexus-state-overview.md) and [nexus-layout.md](./nexus-layout.md).
-
----
-
-## 5. MCP Tool Implementation
-
-The 11 Nexus abstract tools are the interface between the LLM and Nexus state. Your harness implements each one concretely. nexus-core specifies behavior; you choose the registration name, prefix, and implementation mechanism.
-
-### The 11 abstract tool names
-
-| Abstract name | Function |
-|---------------|----------|
-| `plan_start` | Create a new planning session |
-| `plan_status` | Query the current plan state |
-| `plan_update` | Add, remove, edit, or reopen plan issues |
-| `plan_decide` | Record a decision on a plan issue |
-| `task_add` | Add a task to the active task list |
-| `task_list` | List tasks with dependency-aware ready set |
-| `task_update` | Update a task's status |
-| `task_close` | Archive the current cycle to history.json and delete session state files |
-| `history_search` | Search past cycles in history.json |
-| `context` | Read active session context (branch, task summary, decisions) |
-| `artifact_write` | Write a named artifact file to the session artifact directory |
-
-### Tool naming
-
-nexus-core uses abstract names only. Your harness chooses its own registration names. For example, a harness might register `plan_start` as `nx_plan_start`, or a plugin system might prefix it as `mcp__plugin_name_nx__plan_start`. The name you use internally is your decision. The behavioral contract — parameters, return values, side effects, error conditions — is fixed by nexus-core and must not vary.
-
-### Implementation contract
-
-For every tool, implement exactly the parameter schema, return shape, and side effects documented in [nexus-tools-contract.md](./nexus-tools-contract.md). Do not add undocumented parameters or return fields that callers may depend on. Do not omit required return fields.
-
-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` 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.
-
-### Implementation order
-
-Implement in this sequence:
-
-1. `plan_start`, `plan_decide` — validates state file management; these are the most frequently tested tools
-2. `plan_status`, `plan_update` — complete the planning surface
-3. `task_add`, `task_list`, `task_update`, `task_close` — execution lifecycle; `task_close` is the cleanup path
-4. `history_search`, `context`, `artifact_write` — support tools; implement after the core tools are passing conformance
-
-After each tool pair, run the relevant fixtures from `conformance/tools/` before continuing.
-
-For full parameter schemas, return value shapes, and error conditions, see [nexus-tools-contract.md](./nexus-tools-contract.md).
-
----
-
-## 6. Capability Handling
-
-Capabilities restrict which tools a subagent may call. nexus-core defines capabilities in abstract semantic terms. Your harness translates them into concrete tool blocklists.
-
-### Canonical capability definitions
-
-Read `vocabulary/capabilities.yml`. Each capability has:
-
-- `id` — the canonical identifier (e.g., `no_file_edit`)
-- `intent` — a machine-readable semantic class (e.g., `workspace_write_denial`)
-- `blocks_semantic_classes` — the list of semantic operation classes this capability forbids
-- `prose_guidance` — a human-readable description of exactly which tool behaviors are blocked and which are not
-
-The four canonical capabilities in nexus-core 0.2.0:
-
-| ID | Intent | Blocks |
-|----|--------|--------|
-| `no_file_edit` | `workspace_write_denial` | `file_creation`, `file_modification`, `file_deletion`, `partial_file_edit`, `structured_document_edit` |
-| `no_task_create` | `task_pipeline_append_denial` | `nexus_task_creation` |
-| `no_task_update` | `task_pipeline_mutate_denial` | `nexus_task_state_transition`, `nexus_task_metadata_modification` |
-| `no_shell_exec` | `shell_execution_denial` | `shell_command_exec`, `subprocess_spawn`, `interactive_shell_session` |
-
-### Local capability-map
-
-Create a consumer-owned capability-map file that translates each capability ID and semantic class to the concrete tool names in your harness. The format is your choice; the following YAML structure is a workable pattern:
-
-```yaml
-# capability-map.yml  (consumer-owned, not part of nexus-core)
-no_file_edit:
-  disallowed_tools:
-    - YourEditTool
-    - YourWriteTool
-    - YourDeleteTool
-    - YourPatchTool
-    - YourNotebookCellEditTool
-  mapped_classes:
-    - file_creation
-    - file_modification
-    - file_deletion
-    - partial_file_edit
-    - structured_document_edit
-
-no_task_create:
-  disallowed_tools:
-    - YourTaskAddTool      # your harness's concrete registration name for task_add
-  mapped_classes:
-    - nexus_task_creation
-
-no_task_update:
-  disallowed_tools:
-    - YourTaskUpdateTool   # your harness's concrete registration name for task_update
-    - YourTaskCloseTool    # your harness's concrete registration name for task_close
-  mapped_classes:
-    - nexus_task_state_transition
-    - nexus_task_metadata_modification
-
-no_shell_exec:
-  disallowed_tools:
-    - YourShellTool
-    - YourSubprocessTool
-  mapped_classes:
-    - shell_command_exec
-    - subprocess_spawn
-    - interactive_shell_session
-```
-
-### Effective capability computation
-
-When building an agent's effective restriction set, apply the additive-only merge rule defined in [behavioral-contracts.md §4](./behavioral-contracts.md):
-
-```
-effective_capabilities(agent) = canonical_capabilities(agent) ∪ consumer_additions(agent)
-```
-
-- `canonical_capabilities` is the `capabilities` array in `agents/{id}/meta.yml` (the nexus-core definition).
-- `consumer_additions` is a harness-local set you define for agents where you want stricter restrictions.
-
-**You may add capabilities. You must not remove canonical capabilities.** Removing `no_file_edit` from an agent that carries it canonically violates the nexus-core design intent. If nexus-core later adds a capability that your consumer already applies locally, the overlap is harmless — the union is idempotent.
-
-### Applying the capability-map
-
-When registering an agent for a subagent session:
-
-1. Read the agent's `capabilities` array from `manifest.json` or `agents/{id}/meta.yml`.
-2. Merge with any consumer additions for that agent ID.
-3. For each capability in the merged set, look up `disallowed_tools` in your capability-map.
-4. Build the union of all disallowed tools across all capabilities.
-5. Pass this union to your harness's agent-registration mechanism as the set of tools the agent may not call.
-
-### CI coverage assertion
-
-In your test suite, verify that every `blocks_semantic_classes` value across all entries in `vocabulary/capabilities.yml` has at least one mapped tool in your capability-map. This catches omissions when nexus-core adds new semantic classes in a future version.
-
----
-
-## 7. Agent Catalog Construction
-
-The agent catalog is your harness's internal registry of all Nexus agent roles, populated from nexus-core agent definitions and augmented with harness-specific context.
-
-### Reading agent definitions
-
-Start with `manifest.json`. The `agents` array contains one entry per agent role with these fields:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | string | Canonical agent identifier (e.g., `engineer`) |
-| `name` | string | Display name |
-| `description` | string | One-line role description |
-| `category` | `"how" \| "do" \| "check"` | Role category |
-| `resume_tier` | `"persistent" \| "bounded" \| "ephemeral"` | Session persistence behavior |
-| `model_tier` | `"high" \| "standard"` | Abstract model selection signal |
-| `capabilities` | `string[]` | Canonical capability IDs |
-| `body_hash` | string | SHA-256 hash of body.md for integrity verification |
-
-For full metadata, read `agents/{id}/meta.yml`. For the agent's prompt content, read `agents/{id}/body.md`.
-
-### Transformation pipeline
-
-For each agent in `manifest.json`:
-
-1. **Read body.md** from `agents/{id}/body.md`. This is the prompt you will inject into the agent's LLM context.
-2. **Compute effective_capabilities** by merging canonical capabilities with your consumer additions (see §6).
-3. **Resolve disallowed tools** by applying your capability-map to `effective_capabilities`.
-4. **Map model_tier** to a concrete model identifier: `high` → your harness's high-capability model, `standard` → your harness's standard model. This mapping is consumer-owned.
-5. **Register** the agent in your harness's agent system with the resolved prompt, model, and tool restrictions.
-
-### Neutral body + harness context synthesis
-
-`body.md` is deliberately harness-neutral. It says things like "report to Lead" without specifying the concrete mechanism. This is intentional: the same body works across claude-nexus and opencode-nexus because each harness injects the mechanism alongside the body.
-
-Your harness must inject harness-specific tool awareness when activating an agent. Concretely:
-
-- body.md says: "report to Lead"
-- Your harness injects alongside it: "To report to Lead, use [your harness's inter-agent communication tool]."
-
-- body.md says: "save your output using the artifact tool"
-- Your harness injects alongside it: "The artifact tool in this harness is registered as [your concrete tool name]."
-
-The `harness_docs_refs` field in `skills/{id}/meta.yml` signals which harness-specific topics should be surfaced when injecting context for that skill. For example, `nx-plan` and `nx-run` both declare `harness_docs_refs: [resume_invocation]` — meaning your harness should inject documentation about how agent resume works in your specific system when those skills are active.
-
-### Nine agent roles
-
-nexus-core 0.2.0 defines these nine agents:
-
-| ID | Category | Resume tier | Canonical capabilities |
-|----|----------|-------------|------------------------|
-| `architect` | how | persistent | no_file_edit, no_task_create, no_task_update |
-| `designer` | how | persistent | no_file_edit, no_task_create, no_task_update |
-| `postdoc` | how | persistent | no_file_edit, no_task_create, no_task_update |
-| `strategist` | how | persistent | no_file_edit, no_task_create, no_task_update |
-| `engineer` | do | bounded | no_task_create |
-| `writer` | do | bounded | no_task_create |
-| `researcher` | do | persistent | no_file_edit, no_task_create |
-| `tester` | check | ephemeral | no_file_edit, no_task_create |
-| `reviewer` | check | ephemeral | no_file_edit, no_task_create |
-
-All nine roles must be registered in your catalog. A consumer that omits an agent prevents Lead from using that role in plans and run cycles.
-
----
-
-## 8. Skill Activation Architecture
-
-Skills are behavioral specifications that change how Lead operates. Skill activation transforms the LLM's operating mode by injecting a new body.md as its primary instruction set. The activation flow has six stages.
-
-### Full activation flow
-
-```
-User types "[plan] analyze the architecture"
-     |
-     v
-1. Tag Detection
-   - The consumer's user_message hook (or equivalent) intercepts the message
-   - Scan the message text for bracket tag patterns defined in vocabulary/tags.yml
-   - "[plan]" matches: id=plan, type=skill, skill=nx-plan
-     |
-     v
-2. Routing by type
-   - type=skill       → proceed to skill body loading (step 3)
-   - type=inline_action → call the handler tool directly; do not load a skill body
-                          Example: "[d]" → call plan_decide tool immediately
-     |
-     v
-3. Skill Body Loading
-   - Read skills/{skill_id}/body.md from the nexus-core package
-   - This file is the skill's complete behavioral specification
-   - 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
-   - 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
-     |
-     v
-5. Skill Active State
-   - Skill remains active until one of:
-     a. Session ends — all skills deactivate
-     b. Another skill is activated — replacement (e.g., [plan] → [run] transition)
-     c. The skill's own deactivation condition is met
-        Example: nx-plan completes (all issues decided) → user types [run] to transition
-   - While active, the skill's body governs Lead's behavior
-     |
-     v
-6. manual_only Handling
-   - Before exposing skills to LLM natural-language detection, check meta.yml
-   - If manual_only=true: NEVER include in auto-detection candidate list
-   - Only activate on explicit user trigger: slash command or bracket tag typed by user
-   - Applies to: nx-init, nx-setup in nexus-core 0.2.0
-   - See: behavioral-contracts.md §6
-```
-
-### Tag variants
-
-Tags may include variant suffixes. The `variants` field in `vocabulary/tags.yml` lists valid variant tokens for each tag.
-
-Example: `plan` has `variants: ["auto"]`. This means `[plan:auto]` is a valid trigger that activates the same `nx-plan` skill but passes `auto` as a mode flag. Your consumer must:
-
-1. Detect `[plan:auto]` as a variant of the `plan` tag.
-2. Activate the same `nx-plan` skill body.
-3. Pass the variant string (`auto`) to the skill activation logic as an argument or injected parameter.
-
-The `rule` tag has `variants: ["*"]`, meaning any suffix is valid: `[rule:frontend]`, `[rule:testing]`, etc. Capture the suffix and pass it to the `rule_store` handler.
-
-### Inline actions
-
-Tags with `type=inline_action` do not load a skill body. They trigger a direct tool call.
-
-| Tag | Handler | Effect |
-|-----|---------|--------|
-| `[d]` | `nx_plan_decide` | Immediately calls plan_decide with the user's decision text |
-| `[m]` | `memory_store` | Stores the current lesson to `.nexus/memory/` |
-| `[m:gc]` | `memory_gc` | Garbage-collects `.nexus/memory/` |
-| `[rule]` | `rule_store` | Stores a rule to `.nexus/rules/` |
-
-For inline actions, extract the relevant content from the user's message (the text following the tag) and pass it as the tool parameter. No skill body is loaded; no LLM mode change occurs.
-
-### Natural-language trigger detection
-
-Natural-language trigger detection — recognizing that a user's message implies a skill activation even without a bracket tag — is **consumer-owned**. nexus-core does not define, distribute, or maintain natural-language pattern lists.
-
-The canonical trigger for every tag is the explicit bracket form in `vocabulary/tags.yml`. Any other activation form (recognizing "let's plan this" as equivalent to `[plan]`) is a consumer extension. Different consumers may implement different patterns. This divergence is explicitly acceptable per [behavioral-contracts.md §7](./behavioral-contracts.md).
-
----
-
-## 9. Hook Event Lifecycle
-
-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:
-
-- **(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.
-
-### 8 lifecycle events
-
-#### `session_start`
-
-**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:**
-- **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 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:**
-- **SHOULD** scan the message text for bracket tags. Match against all triggers defined in `vocabulary/tags.yml`.
-- For each matched tag:
-  - **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.
-- **SHOULD** pass the message to Lead without modification if no tags are matched.
-
----
-
-#### `subagent_spawn`
-
-**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:**
-- **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 (harness runtime may expose this as `SubagentStop`, `agent.completed`, a subagent-exit hook, or equivalent).
-
-**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.
-
----
-
-#### `pre_tool_use`
-
-**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:**
-- **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.
-
----
-
-#### `post_tool_use`
-
-**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.
-- **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 session is terminating (harness runtime may expose this as `Stop`, `session.end`, a shutdown hook, or equivalent).
-
-**Expected consumer behavior:**
-- **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 runtime compresses the context window (harness runtime may expose this as `PostCompact`, `context.compacted`, a post-compact hook, or equivalent).
-
-**Expected consumer behavior:**
-- **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`.
-- **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.
-
----
-
-## 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.
-
-### Spawn model
-
-When Lead assigns a task to an agent, the consumer:
-
-1. Creates an isolated LLM session for the agent. The isolation mechanism is implementation-specific: a subprocess, an API call to a sandboxed session, a parallel conversation thread, or any other approach your harness supports.
-2. Injects the agent's `body.md` as the agent's system prompt or initial context. This is the agent's identity and behavioral specification.
-3. Applies tool restrictions derived from `effective_capabilities` (see §6). The agent session must not have access to tools in its disallowed set.
-4. Passes the task's structured context as the agent's working prompt.
-5. Waits for the agent to complete and collects the result.
-
-### Context passing
-
-Pass task context to the agent in this structured format:
-
-```
-TASK: {task.title}
-
-CONTEXT:
-{task.context}
-
-APPROACH:
-{task.approach}
-
-ACCEPTANCE:
-{task.acceptance}
-```
-
-Omit sections whose fields are absent (not all tasks have `approach` or `acceptance` defined). The `task_list` tool returns the full task structure including all optional fields.
-
-Also inject:
-- The knowledge index: file paths in `.nexus/memory/`, `.nexus/context/`, `.nexus/rules/`
-- Harness-specific tool name mapping: which of your harness's concrete tool names correspond to the abstract nexus operations the agent's body.md may reference
-- Any `harness_docs_refs` from the active skill's meta.yml
-
-### Result collection
-
-The agent produces output: file changes, artifact files, reports, or analysis. How the result is returned to Lead is consumer-decided. Common patterns:
-
-- **Return value** — the subagent session's final message is returned as a string; Lead reads it directly.
-- **Shared filesystem** — the agent writes to `.nexus/state/artifacts/` via the `artifact_write` tool; Lead reads the file.
-- **Message passing** — the agent sends a structured message to Lead via your harness's inter-agent communication mechanism; Lead receives and acts on it.
-
-The body.md of each agent specifies that it should "report to Lead" — whatever concrete mechanism you implement, ensure that the agent's output reaches Lead before the subagent session closes.
-
-Lead is the only coordinator. Subagents do not communicate directly with each other. All inter-agent communication flows through Lead.
-
-### Resume model
-
-Before spawning an agent, evaluate whether to spawn fresh or resume a prior session. The evaluation follows three inputs:
-
-**1. `owner_reuse_policy` from `tasks.json`** (per-task override, highest priority):
-
-| Value | Effect |
-|-------|--------|
-| `fresh` | Always spawn fresh; ignore resume_tier |
-| `resume_if_same_artifact` | Resume only if same agent, same target files, no intervening edits |
-| `resume` | Always resume if a prior session is available |
-| absent | Fall back to the agent's default resume_tier |
-
-**2. Agent `resume_tier` from `manifest.json`** (default behavior):
-
-| Tier | Behavior |
-|------|----------|
-| `ephemeral` | Always spawn fresh. Independent verification requires no prior context. Applies to: tester, reviewer. |
-| `bounded` | Resume only when: same owner identity, same target files, no intervening edits by others. Re-read target files at session start. Applies to: engineer, writer. |
-| `persistent` | Resume by default within the same run session. Cross-task reuse allowed. Applies to: architect, designer, postdoc, strategist, researcher. |
-
-**3. Resume gating**:
-
-Before attempting to resume, verify that your harness supports the resume mechanism for the current context. If the mechanism is unavailable (the harness cannot reopen a prior session, or no session ID was recorded for this agent), fall back to a fresh spawn silently. Do not surface a resume failure as an error to the user.
-
-For `bounded` agents evaluating resume eligibility:
-- Check `.nexus/state/{harness-id}/agent-tracker.json` for the prior agent ID assigned to this task.
-- 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).
-
-### Inter-agent communication boundary
-
-Subagents communicate results to Lead. Lead is responsible for all coordination. No direct subagent-to-subagent communication is defined or permitted by the nexus-core model.
-
-If your harness exposes an inter-agent communication tool, it must be available to Lead and may be made available to subagents for the purpose of reporting back to Lead. Subagents must not use it to route work to other subagents — that is Lead's responsibility.
-
----
-
-## 11. Conformance Verification (Required)
-
-Consumers MUST pass all conformance fixtures to claim nexus-core compatibility. This is not optional — it is the mechanism by which cross-harness interoperability is guaranteed. Non-conforming implementations may produce state files that other Nexus ecosystem components cannot read, or exhibit behavioral divergence that breaks plan/task lifecycle assumptions.
-
-### Fixture types
-
-**Tool fixtures** (`conformance/tools/*.json`) — single-action tests for individual tools. Each fixture specifies:
-- `precondition` — which state files must exist or must not exist before the test
-- `action` — the tool name and parameters to call
-- `postcondition` — assertions on the return value and state file contents after the call
-
-**Scenario fixtures** (`conformance/scenarios/*.json`) — multi-step tests for end-to-end lifecycle flows. Each fixture specifies a sequence of steps, each with an action and assertions. Scenarios cover flows such as a full plan cycle and dependency-ordered task execution.
-
-Available fixture files in nexus-core 0.2.0:
-
-| File | Coverage |
-|------|----------|
-| `conformance/tools/plan-start.json` | `plan_start` happy path and edge cases |
-| `conformance/tools/plan-decide.json` | `plan_decide` decision recording |
-| `conformance/tools/task-add.json` | `task_add` creation and first-time initialization |
-| `conformance/tools/task-close.json` | `task_close` archiving and state file deletion |
-| `conformance/scenarios/full-plan-cycle.json` | Complete plan → decide → task → close lifecycle |
-| `conformance/scenarios/task-deps-ordering.json` | Dependency-ordered task readiness computation |
-
-### Writing a test runner
-
-A conformance test runner:
-
-1. Loads a fixture JSON file.
-2. Establishes the precondition: writes or deletes state files as specified.
-3. Calls your harness's implementation of the named tool with the fixture's parameters.
-4. Evaluates postconditions using JSONPath assertions against the return value and state files.
-5. Reports pass/fail per `test_id`.
-
-Assertion keys in postconditions are JSONPath expressions. A `null` value at a file path key means the file must not exist. A `null` value at a JSONPath key means that field must be `null`.
-
-The fixture format schema is at `conformance/schema/fixture.schema.json`.
-
-For runner implementation patterns and a TypeScript sketch, see [conformance/README.md](../conformance/README.md).
-
-### CI integration
-
-Add the conformance test runner to your CI pipeline. Conformance failures MUST block release. Do not merge harness changes that break conformance — a conformance failure means your implementation diverges from the Nexus ecosystem contract.
-
-Conformance verification is distinct from your harness's own unit tests. Run both.
-
----
-
-## 12. Minimum Viable Consumer
-
-The smallest working Nexus session requires exactly these components. Build this first, verify it works end to end, then expand incrementally.
-
-### Tools (4 minimum)
-
-| Abstract name | Purpose |
-|---------------|---------|
-| `plan_start` | Create a planning session |
-| `plan_decide` | Record decisions on plan issues |
-| `task_add` | Add tasks to the execution list |
-| `task_close` | Archive the cycle and clean up session state |
-
-This set covers the complete plan → decide → add tasks → close cycle. Implement these four tools first, run their conformance fixtures, and verify the full cycle before adding more tools.
-
-### Agent (1 minimum)
-
-Register the `engineer` agent:
-
-- **body.md**: `agents/engineer/body.md`
-- **resume_tier**: `bounded`
-- **capabilities**: `no_task_create`
-- **model_tier**: `standard`
-
-Engineer is the execution agent. With engineer alone, Lead can delegate implementation tasks and collect results.
-
-### Skill (1 minimum)
-
-Activate `nx-plan` when the user types `[plan]`:
-
-- **body.md**: `skills/nx-plan/body.md`
-- **trigger**: `[plan]` (from `vocabulary/tags.yml`)
-- **type**: `skill`
-
-Implement tag detection in your `user_message` hook. When `[plan]` is detected, load `skills/nx-plan/body.md` and inject it into Lead's context.
-
-### Hook events (3 minimum)
-
-| Event | Minimum required behavior |
-|-------|--------------------------|
-| `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. 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)
-
-| File | Why it is required |
-|------|--------------------|
-| `plan.json` | Written by `plan_start`; read by `plan_decide` |
-| `tasks.json` | Written by `task_add`; archived by `task_close` |
-| `history.json` | Written by `task_close`; the permanent project record |
-
-### What this gives you
-
-A minimum viable consumer supports this complete cycle:
-
-1. User types `[plan] let's plan the feature` → `nx-plan` skill activates
-2. Lead runs a planning session, calls `plan_start`, calls `plan_decide` for each issue
-3. Lead calls `task_add` to create implementation tasks
-4. Lead spawns engineer subagent with task context
-5. Engineer completes the work
-6. Lead calls `task_close` to archive the cycle
-
-### Incremental expansion path
-
-Add components in this order after verifying the MVC:
-
-1. **`[run]` skill + `nx-run` body** — adds structured execution orchestration; Lead gets the full delegation protocol for parallel task assignment
-2. **Remaining 7 agents** — researcher, architect, postdoc, strategist, designer, writer, tester, reviewer; adds parallel analysis and verification roles
-3. **Remaining 7 tools** — `plan_status`, `plan_update`, `task_list`, `task_update`, `history_search`, `context`, `artifact_write`; completes the full tool surface
-4. **All 8 hook events** — adds `subagent_spawn`, `subagent_complete`, `pre_tool_use`, `post_tool_use`, `context_compact` for full lifecycle management
-5. **Conformance suite** — run all fixtures in `conformance/tools/` and `conformance/scenarios/` before marking the harness production-ready
-6. **`[sync]` skill** — adds `nx-sync` for keeping `.nexus/context/` synchronized with project state
-
-Do not add the `[sync]`, `nx-init`, or `nx-setup` skills until the core planning and execution lifecycle is verified. These skills depend on the project state infrastructure built by the earlier components.