@inkobytes/nexus 1.0.7 → 1.0.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.0.8 - 2026-06-10
+
+- Added a shared protocol wording source so `nexus init`, `nexus doctor`, README repair, and tests stay aligned.
+- Tightened generated agent protocol around required continuity/latest-memory reads and claim-before-read/edit behavior.
+- Added `nexus hooks install --agent all` for installing Codex, Claude, and Gemini guard hooks in one pass.
+
 ## 1.0.7 - 2026-06-06
 
 - Added `nexus install-skill` to install the bundled Nexus skill into `~/.agents/skills/nexus`.

package/README.md

@@ -133,6 +133,12 @@ Memory folders are month-based from the start, for example:
 .gemini/memories/2026-May/
 ```
 
+Memory indexes stay newest-first and link to entries with one-line outcomes:
+
+```md
+- [2026-06-09-1430-hook-protocol-fix](2026-June/2026-06-09-1430-hook-protocol-fix.md) - tightened hook claim guidance
+```
+
 If you only want to inspect an existing repo before changing anything, run:
 
 ```bash
@@ -253,6 +259,25 @@ nexus install-skill --target ~/.agents/skills/nexus
 
 By default, Nexus copies `skills/nexus` from the published package into `~/.agents/skills/nexus`. Restart or refresh your agent session after installing so its skill registry can discover the new `nexus` skill.
 
+### `nexus hooks install --agent @codex|@claude|@gemini|all [--target <path>] [--force]`
+
+Install an agent-specific local guard hook.
+
+```bash
+nexus hooks install --agent @codex
+nexus hooks install --agent @claude
+nexus hooks install --agent @gemini
+nexus hooks install --agent all
+```
+
+Hooks block writes in Nexus repos until the exact target path is claimed, then give the agent a compact recovery command. Each hook uses the matching claim handle, so Codex sees `@codex`, Claude sees `@claude`, and Gemini sees `@gemini`.
+
+Use `--agent all` to install the default Codex, Claude, and Gemini hooks in one pass. `--target` is only for single-agent installs.
+
+Hook installation writes outside the repo, so `nexus doctor --fix` does not install hooks. Use `nexus doctor --hooks` to report missing, foreign, wrong-agent, or current hooks.
+
+See [docs/hooks.md](./docs/hooks.md) for install targets and behavior.
+
 ### `nexus ledger [--json]`
 
 Show completed task entries from `_NEXUS_LEDGER.md`.
@@ -425,7 +450,7 @@ The agent rule of thumb:
 1. Run `nexus start` when entering an existing repo; it does not replace claim/release.
 2. Read `_NEXUS_CONSTITUTION.md`.
 3. Read `USER.md` when present.
-4. Read continuity and latest memory when present.
+4. Read continuity and latest memory at session start, `nexus start`, or resume.
 5. Read `_NEXUS_QUEUE.md` before taking follow-on work.
 6. Claim before touching shared project files.
 7. Release each claimed tracked file as soon as it reaches a coherent checkpoint.
@@ -465,6 +490,8 @@ Nexus ships an agent skill at `skills/nexus/SKILL.md`.
 
 The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> work -> release -> next`.
 
+Generated agent protocol text lives in `src/lib/protocolText.js`. Update that module first when changing shared protocol wording, then run doctor/init tests so scaffolded guides, README repair, and the bundled skill stay aligned.
+
 ## Legacy Helper Transition
 
 Older Nexus experiments used shell helpers:

package/bin/nexus.js

@@ -19,6 +19,7 @@ const COMMANDS = {
   metrics: () => import('../src/commands/metrics.js'),
   ledger: () => import('../src/commands/ledger.js'),
   drill: () => import('../src/commands/drill.js'),
+  hooks: () => import('../src/commands/hooks.js'),
   soul: () => import('../src/commands/soul.js'),
   'install-skill': () => import('../src/commands/install-skill.js'),
   chmod: () => import('../src/commands/chmod.js'),
@@ -26,7 +27,7 @@ const COMMANDS = {
   help: () => import('../src/commands/help.js'),
 };
 
-const VERSION = '1.0.7';
+const VERSION = '1.0.8';
 const COLORS = createColors();
 
 const args = argv.slice(2);
@@ -76,6 +77,7 @@ function printHelp() {
     ['chmod [--list] [--init]', 'Show or set promptCHMOD permissions'],
     ['db <backup|list|restore|schedule>', 'Database backup and recovery'],
     ['drill <list|show|run|report>', 'Inspect or run protocol drills'],
+    ['hooks install --agent @handle|all', 'Install agent-specific local guard hooks'],
     ['soul [--file <path>] [--status | --remove]', 'Manage local soul overlay in agent files'],
     ['install-skill [--target <path>] [--force]', 'Install bundled Nexus skill into ~/.agents/skills'],
     ['help', 'Show this help'],
@@ -91,6 +93,8 @@ function printHelp() {
     'nexus metrics --json',
     'nexus ledger backfill',
     'nexus drill show wrong-repo-push',
+    'nexus hooks install --agent @codex',
+    'nexus hooks install --agent all',
     'nexus install-skill',
     'nexus claim src/lib/components/login/ @claude "Building login UI"',
     'nexus release src/lib/components/login/ "feat: login form component"',

package/docs/hooks.md

@@ -0,0 +1,94 @@
+# Nexus Hooks
+
+Nexus hooks are optional local guardrails for agent CLIs. They block file writes in Nexus repos until the target path has a matching Nexus claim.
+
+Hooks are useful because agent instruction files can be forgotten after context compaction. The hook gives the agent a short recovery command instead of letting it edit around the protocol.
+
+## Install
+
+```bash
+nexus hooks install --agent @codex
+nexus hooks install --agent @claude
+nexus hooks install --agent @gemini
+nexus hooks install --agent all
+```
+
+Supported agents:
+
+- `@codex`
+- `@claude`
+- `@gemini`
+
+Each installed hook bakes in the matching claim handle, so a Codex hook says `@codex`, a Claude hook says `@claude`, and a Gemini hook says `@gemini`.
+
+Use `--agent all` to install all default Codex, Claude, and Gemini hooks in one pass. `--target` is only available for a single agent because each agent has a different default file.
+
+## Default Targets
+
+```text
+@codex  -> ~/.codex/hooks/pre_tool_use_guard.py
+@claude -> ~/.claude/hooks/nexus_pre_tool_use_guard.py
+@gemini -> ~/.gemini/hooks/nexus_pre_tool_use_guard.py
+```
+
+Use `--target` when your agent CLI needs a different hook path:
+
+```bash
+nexus hooks install --agent @codex --target ~/.codex/hooks/pre_tool_use_guard.py
+```
+
+If a hook file already exists, Nexus does not overwrite it unless it is already a current Nexus hook. Use `--force` only after reviewing the existing file:
+
+```bash
+nexus hooks install --agent @codex --force
+```
+
+## What The Hook Blocks
+
+The hook looks for writes to files in a Nexus repo. If the file is not claimed, it denies the tool call with a compact message:
+
+```text
+CLAIM FIRST: README.md
+cd /path/to/repo && nexus claim README.md @codex "Describe the edit"
+Retry edit. No workaround.
+```
+
+For multiple files, it adds:
+
+```text
+If multiple files are listed, claim each exact path.
+```
+
+The hook discovers the Nexus repo root from the target path or current working directory. It checks the real Nexus lock path encoding, including nested paths such as `docs~2Fguide.md.lock`.
+
+## Claim Exemptions
+
+The hook allows agent-local continuity and memory handoff files without a claim:
+
+- `.codex/CONTINUITY.md`
+- `.codex/memories/`
+- `.claude/CONTINUITY.md`
+- `.claude/memories/`
+- `.gemini/CONTINUITY.md`
+- `.gemini/memories/`
+
+Agent instruction files such as `.codex/AGENTS.md`, `.claude/CLAUDE.md`, and `.gemini/GEMINI.md` still require claim/release when they are shared project files.
+
+## Doctor Check
+
+Hook installation writes outside the repo, so `nexus doctor --fix` does not install or replace hooks.
+
+To audit hook status explicitly:
+
+```bash
+nexus doctor --hooks
+```
+
+Doctor reports whether each supported agent hook is:
+
+- `current`
+- `missing`
+- `foreign`
+- `wrong-agent`
+
+Use `nexus hooks install --agent <handle>` to install or refresh a hook.

package/docs/nexus-dynamic-governed-loops.md

@@ -0,0 +1,135 @@
+# Nexus Dynamic and Governed Loops Graphic Brief
+
+## Core Insight
+
+Nexus is dynamic before approval and deterministic after approval.
+
+The system already supports dynamism because agents can discover issues, propose work, shape tasks, and surface dependencies. That dynamism is easy to miss because the execution loop is intentionally governed and repeatable.
+
+## Graphic Goal
+
+Create a clear visual that explains how Nexus handles both:
+
+- dynamic discovery, planning, and proposal
+- governed execution through approved queue work
+
+The graphic should help users understand that Nexus is not a free-roaming autonomous agent system. It is a coordination workflow where agents can think and propose freely, but can only execute approved scoped work.
+
+## Suggested Diagram Structure
+
+Show two connected loops with a visible approval boundary between them.
+
+### Loop 1: Dynamic Discovery Loop
+
+Labels:
+
+1. Idea or observation
+2. Inspect context
+3. Find issue or opportunity
+4. Propose task
+5. Shape scope, files, dependencies, tradeoffs
+6. Wait for approval
+
+Tone:
+
+- exploratory
+- generative
+- allowed to be dynamic
+- no file-changing execution unless separately approved and claimed
+
+### Boundary: Approval Gate
+
+Main label:
+
+> Dynamic before approval. Deterministic after approval.
+
+Supporting labels:
+
+- human review
+- `Review: approved`
+- `Approved by: human`
+- `Auto-flow: yes`
+- task contract is complete
+
+This gate should visually separate proposal from execution.
+
+### Loop 2: Governed Execution Loop
+
+Labels:
+
+1. Ready Queue
+2. `nexus next @agent`
+3. `nexus claim <path> @agent "intent"`
+4. Work inside claimed surface
+5. Validate
+6. `nexus release <path> "message"`
+7. Standup/report if useful
+8. Next safe task or Standby
+
+Tone:
+
+- deterministic
+- repeatable
+- file-scoped
+- approval-bound
+- safe for multi-agent concurrency
+
+## Key Message
+
+Agents may discover and propose freely.
+Agents may execute only approved scoped work.
+
+## What The Graphic Should Prevent
+
+- Thinking Nexus is only a rigid task runner.
+- Thinking Nexus lets agents freely invent and execute work.
+- Treating `nexus next` as an ideation engine.
+- Treating proposed work as executable work.
+- Forgetting the approval boundary.
+
+## Possible Formats
+
+- Mermaid draft for README
+- FigJam/Figma system map
+- Dashboard explainer panel
+- README hero diagram
+- Short docs page with the two-loop graphic and examples
+
+## Draft Mermaid Shape
+
+```mermaid
+flowchart LR
+  subgraph Discovery["Dynamic Discovery Loop"]
+    A[Idea or observation] --> B[Inspect context]
+    B --> C[Find issue or opportunity]
+    C --> D[Propose task]
+    D --> E[Shape scope, files, dependencies, tradeoffs]
+  end
+
+  E --> Gate{Approval Gate}
+
+  Gate -->|Review approved + Auto-flow yes| R[Ready Queue]
+  Gate -->|Needs planning or approval| D
+
+  subgraph Execution["Governed Execution Loop"]
+    R --> N[nexus next @agent]
+    N --> CL[nexus claim path @agent intent]
+    CL --> W[Work inside claimed surface]
+    W --> V[Validate]
+    V --> REL[nexus release path message]
+    REL --> S[Standup or report]
+    S --> N
+  end
+
+  N -->|No safe task| Standby[Standby]
+```
+
+## Later Design Notes
+
+- Make the discovery loop feel more fluid than the execution loop.
+- Make the approval gate visually prominent.
+- Use different colors for "propose" versus "execute", but keep the overall palette restrained.
+- The primary caption should be short enough to remember:
+
+> Dynamic before approval. Deterministic after approval.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkobytes/nexus",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Multi-agent coordination CLI for coding agents sharing a local repository",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
   "files": [
     "bin/",
     "src/",
+    "docs/",
     "drills/",
     "skills/",
     "nexus-dashboard/",

package/skills/nexus/SKILL.md

@@ -7,12 +7,14 @@ description: Use in repos coordinated by the Nexus CLI, especially when _NEXUS_C
 
 Nexus CLI is the coordination engine. This skill is only the agent playbook.
 
+If the user, repo, or hook says Nexus is active, treat this skill as mandatory workflow. It is not optional advice.
+
 ## Loop
 
 1. Run `nexus start`; set `NEXUS_AGENT` for your CLI, or pass `--agent @agy|@claude|@codex|@gemini`. Start is orientation only, not permission to edit.
 2. Read `_NEXUS_CONSTITUTION.md`.
 3. Read `USER.md` if present for local user preferences.
-4. Read continuity and latest memory when present.
+4. Read continuity and latest memory at session start, `nexus start`, or resume.
 5. Read `_NEXUS_QUEUE.md` and `_NEXUS_STANDUP.md`.
 6. Choose user-assigned work or `nexus next @Agent`; do not free-roam into `Auto-flow: no`.
 7. Claim exact shared files before reading/editing:
@@ -22,14 +24,15 @@ Nexus CLI is the coordination engine. This skill is only the agent playbook.
    ```
 
 8. Treat claim output as current file state. Ignore cached file memory when contents matter.
-9. Work only inside the claimed surface and run focused validation.
-10. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:
+9. If a hook blocks access because a path is unclaimed, stop and claim that exact path. Do not work around the hook with another command, cached content, or manual git operation.
+10. Work only inside the claimed surface and run focused validation.
+11. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:
 
    ```bash
    nexus release <path> "short commit message"
    ```
 
-11. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.
+12. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.
 
 ## Queue Items
 
@@ -62,6 +65,9 @@ When adding work to `_NEXUS_QUEUE.md`, keep tasks dashboard-parseable and immedi
 - Use `nexus doctor` for audit/repair, not as the normal startup command.
 - Use CLI/model names as lock handles: `@agy`, `@claude`, `@codex`, `@gemini`.
 - Agent-local continuity and memory files are claim-exempt unless the user says otherwise.
+- Continuity is the compaction-safe session ledger; latest memory is required startup/resume context.
+- Memory indexes use monthly folders and newest-first Markdown links with one-line outcomes.
+- Shared generated protocol wording is sourced from `src/lib/protocolText.js`; update that first, then run doctor/init tests.
 - When using subagents or parallel workers, the lead agent owns the repo effects: claim the full path scope, pass boundaries down, re-read affected files, and mention delegated work in release or standup notes.
 - Avoid parallel `nexus release`.
 - Do not install packages younger than 14 days; if age is unknown, ask.