@inkobytes/nexus 1.0.7 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.1.0 - 2026-06-11
+
+- Added `nexus halt "<reason>"` / `nexus resume` circuit breaker: claim, release, and next refuse while `.nexus/HALT` is present, the dashboard shows a halted banner, and resume is human-gated by convention.
+- Added a release verification gate: when `release.verifyCommand` is set in `.nexus/config.json`, `nexus release` runs it before staging and refuses to commit on failure, keeping the claim. `--no-verify` is allowed only at autonomy level 0 and logged to standup.
+- Added `autonomy` level (0–2) to `.nexus/config.json`; `nexus doctor` now warns when autonomy 1+ has no `verifyCommand` (Loop Readiness check).
+- Dashboard now binds 127.0.0.1 by default; LAN exposure requires the explicit `--lan` flag.
+- Fixed `nexus db restore` writing nested database files to the repo root: the backup manifest now stores repo-relative paths and restores round-trip exactly.
+- Removed shell interpolation from mysql backup/restore; `DATABASE_URL` is passed as literal arguments, never through `sh -c`.
+- Aligned promptCHMOD messaging and docs to "advisory contract, not mechanically enforced," with the x-bit threat model documented honestly.
+- CLI version is now read from `package.json` at runtime, and `prepublishOnly: npm test` blocks publishing on a failing suite.
+- Added GitHub Actions CI running tests and `npm pack --dry-run` on Node 18/20/22.
+
+## 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

@@ -1,30 +1,30 @@
 # @inkobytes/nexus
 
-Run more than one AI coding agent in the same project without them stepping on each other.
+[![CI](https://github.com/carmelyne/inkobytes-nexus/actions/workflows/ci.yml/badge.svg)](https://github.com/carmelyne/inkobytes-nexus/actions/workflows/ci.yml)
 
-The hard part starts when they are working at the same time.
+Shared awareness and traffic control for Codex, Claude, Gemini, and other SOTA coding agents working on the same branch.
 
-Nexus gives the repo a simple traffic system:
+Nexus helps multiple top-level coding agents share one local checkout without stepping on each other. It gives them local repo state they can all understand: who is working on what, why a file is locked, what was released, and what is safe to do next.
+
+The loop is intentionally small:
 
 ```text
 start -> claim -> work -> release -> next
 ```
 
-Agents use Nexus to say:
-
-- "I am working on this file."
-- "This is why I claimed it."
-- "This task is done."
-- "These are the files I changed."
-- "Here is what the next agent should know."
-
-Everything stays local in the repo. No server. No database. No cloud dashboard. Just files, Git, and a small CLI.
+Nexus is intentionally boring:
 
-Nexus is focused on one specific problem: multiple AI coding agents working at the same time in one local checkout, with explicit file claims, queue state, release receipts, and handoff notes.
+- no daemon
+- no cloud service
+- no database
+- no branch choreography requirement
+- just files, Git, hooks, and a small CLI
 
 ## Why Nexus Exists
 
-If two agents touch the same files, things get messy fast:
+The hard part starts when powerful agents work at the same time.
+
+If Codex, Claude, Gemini, Cursor, or another coding agent touch the same branch without shared state:
 
 - one agent may overwrite another agent's work
 - one agent may commit files it did not mean to commit
@@ -34,14 +34,26 @@ If two agents touch the same files, things get messy fast:
 
 With Nexus, Git still stores the code history. Nexus tracks the operational state around Git: who claimed what, what task they are doing, what got released, and what another agent should read next.
 
+Nexus is not only traffic control. It gives agents shared situational awareness:
+
+- what each agent is working on, and why they claimed it
+- which files are locked right now
+- what the queue says is safe to pick up next
+- what was released, and by whom
+- what needs human attention
+
+Codex knows what Claude is doing. Claude knows why Gemini claimed that directory. Nobody works blind.
+
 ## What Nexus Is And Is Not
 
 Nexus is:
 
-- a way for agents to reserve files before editing them
+- shared awareness for multiple SOTA coding agents on one branch
+- file claims before shared reads and edits
+- local guard hooks that block unclaimed writes
 - a queue so agents know what is safe to pick up next
 - a release command that commits only the claimed path
-- a standup and report log humans can read
+- standup, report, and ledger files humans can read
 - a local dashboard over the same repo files
 - preventive drills for known multi-agent failure cases
 
@@ -67,11 +79,11 @@ npx @inkobytes/nexus help
 
 Requires Node.js 18 or newer.
 
-## What's New In 1.0.1
+## What's New In 1.0.8
 
-- Colorized `nexus help` output for easier scanning in the terminal
-- Built-in `nexus completion zsh` support for shell completions
-- Bundled `nexus install-skill` support for installing the Nexus agent skill into `~/.agents/skills`
+- Shared protocol wording keeps `nexus init`, `nexus doctor`, README repair, and tests aligned.
+- Generated agent guides now require continuity/latest-memory reads at session start, `nexus start`, or resume.
+- `nexus hooks install --agent all` installs Codex, Claude, and Gemini guard hooks in one pass.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the release summary.
 
@@ -91,13 +103,16 @@ In a Git repo:
 
 ```bash
 nexus init
-nexus start
+nexus hooks install --agent all
+nexus start --agent @codex
 nexus claim README.md @codex "try Nexus on one file"
 nexus release README.md "docs: try Nexus"
 ```
 
 `nexus start` is orientation only. The edit loop is `claim -> work -> release`.
 
+Hooks are the enforcement layer. Without hooks, Nexus is a coordination protocol agents follow. With hooks, unclaimed writes are blocked and the agent gets the exact claim command to run.
+
 `nexus init` creates the Nexus coordination files:
 
 - `_NEXUS.md` - live blackboard showing active locks
@@ -133,6 +148,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
@@ -219,16 +240,32 @@ nexus start
 
 Start reports only local facts: repo path, branch, last commits, dirty files, active locks, and the continuity/memory path for the selected model scope. Start is orientation only, not clearance to edit; agents still claim before shared reads/edits and release when done. Set `NEXUS_AGENT=@claude`, `@codex`, `@gemini`, or `@agy` so agents can run plain `nexus start`; `--agent` is available as an override.
 
-### `nexus dashboard --serve [--port <port>]`
+### `nexus dashboard --serve [--port <port>] [--lan]`
 
 Serve a read-only local Nexus dashboard to see progress and issues.
 
 ```bash
 nexus dashboard --serve
 nexus dashboard --serve --port 13787
+nexus dashboard --serve --lan
 ```
 
-The dashboard prints both `127.0.0.1` and local-network URLs when available, then shows repo health, active locks, queue items, recent standup lines, recent release notes, and dirty git files. It uses local files as the source of truth and updates the page through server-sent events. The default port is `13787`; if that port is already in use, Nexus tries `13788`, `13789`, and so on. Passing `--port` uses that exact port.
+The dashboard shows repo health, active locks, queue items, recent standup lines, recent release notes, and dirty git files. It uses local files as the source of truth and updates the page through server-sent events. The default port is `13787`; if that port is already in use, Nexus tries `13788`, `13789`, and so on. Passing `--port` uses that exact port.
+
+By default the dashboard binds `127.0.0.1`, so it is reachable only from your machine. The dashboard has no authentication and exposes repo coordination state (paths, branch, dirty files, lock intents, standup history), so network exposure is opt-in: pass `--lan` to bind all interfaces and print local-network URLs for other devices. Only use `--lan` on networks you trust.
+
+### `nexus halt "<reason>"` and `nexus resume`
+
+Repo-wide circuit breaker for agent swarms.
+
+```bash
+nexus halt "queue drift detected, need human review"
+nexus resume
+```
+
+`nexus halt` writes `.nexus/HALT` with the reason, timestamp, and initiator. While it exists, `claim`, `release`, and `next` refuse with the halt reason and instruct agents to log a standup line and stand by. The dashboard shows a prominent halted banner. One command stops the swarm, repo-wide, instantly.
+
+Any agent or human may halt — an agent that detects swarm-level trouble should be able to stop everyone. Only humans resume: `nexus resume` refuses inside recognized agent sessions (`CLAUDECODE=1` or `NEXUS_AGENT` set). Like promptCHMOD, that check is an advisory contract honored at session level, not mechanical enforcement — a process that lies about its identity can bypass it. The audit trail, not the gate, is the real guarantee.
 
 ### `nexus completion zsh`
 
@@ -253,6 +290,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`.
@@ -334,6 +390,20 @@ If Git's index is temporarily locked by another release, Nexus waits briefly and
 
 Each release appends a repo-local receipt to `_NEXUS_REPORT.md`. If the released path is listed on a completed queue task and the release message names that task id, Nexus also appends one deduplicated completed-task entry to `_NEXUS_LEDGER.md`.
 
+#### Release verification gate
+
+Set `release.verifyCommand` in `.nexus/config.json` to make every release prove itself first:
+
+```json
+{
+  "release": { "verifyCommand": "npm test" }
+}
+```
+
+When configured, `nexus release` runs the command before staging. On failure it refuses to commit, keeps your claim so you can fix and retry, prints the last lines of output, and appends a `[BLOCKED]` line to standup. Loop principle: agents must not compound on unverified commits.
+
+`--no-verify` skips the gate but is only allowed at autonomy level 0 (supervised), and the skip is logged loudly to standup. At autonomy 1 or higher, `--no-verify` is refused and `nexus doctor` warns whenever no `verifyCommand` is configured.
+
 ### `nexus standup "<dated message>"`
 
 Append a validated standup line to `_NEXUS_STANDUP.md`.
@@ -425,7 +495,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 +535,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:
@@ -493,14 +565,6 @@ git status --short
 
 ## Design Notes
 
-Nexus is intentionally boring:
-
-- no daemon
-- no cloud service
-- no database
-- no private hidden coordination channel
-- no branch choreography requirement
-
 The current storage substrate is Git. Future Nexit planning explores agent-native zones, inspection, publish, and recall, but Nexus keeps today's release path stable.
 
 ## Development

package/bin/nexus.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { argv, exit } from 'process';
+import { readFileSync } from 'fs';
 
 const COMMANDS = {
   init: () => import('../src/commands/init.js'),
@@ -19,14 +20,17 @@ 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'),
   db: () => import('../src/commands/db.js'),
+  halt: () => import('../src/commands/halt.js'),
+  resume: () => import('../src/commands/resume.js'),
   help: () => import('../src/commands/help.js'),
 };
 
-const VERSION = '1.0.7';
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')).version;
 const COLORS = createColors();
 
 const args = argv.slice(2);
@@ -75,7 +79,10 @@ function printHelp() {
     ['ledger [--json|backfill]', 'Show or backfill completed task ledger'],
     ['chmod [--list] [--init]', 'Show or set promptCHMOD permissions'],
     ['db <backup|list|restore|schedule>', 'Database backup and recovery'],
+    ['halt "<reason>"', 'Stop the swarm: claim/release/next refuse'],
+    ['resume', 'Lift a halt (human-owned by convention)'],
     ['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,12 +98,15 @@ 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"',
     'nexus standup "2026-06-01 08:38 AM @codex [DONE]: Updated tests"',
     'nexus clean --stale',
     'nexus next @claude',
+    'nexus halt "queue drift detected, need human review"',
   ];
 
   const width = Math.max(...commands.map(([left]) => left.length)) + 2;

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/nexus-dashboard/index.html

@@ -70,6 +70,10 @@
             </div>
           </div>
         </header>
+        <div id="halt-banner" hidden style="background:#7f1d1d;border:1px solid #ef4444;color:#fecaca;padding:14px 18px;border-radius:10px;margin-bottom:16px;font-weight:600;">
+          <span style="margin-right:8px;">⛔</span><span id="halt-text"></span>
+          <div id="halt-meta" style="font-weight:400;opacity:.85;margin-top:4px;font-size:.85em;"></div>
+        </div>
         <div id="health-alert" class="health-alert" hidden>
           <div class="health-alert-inner">
             <span class="health-alert-icon">🔴</span>
@@ -173,6 +177,16 @@
         // Always update the timestamp — it's benign
         document.getElementById('updated').textContent = 'Updated ' + new Date(data.generatedAt).toLocaleTimeString();
 
+        // Halt banner always reflects current state, even with a popover open
+        const haltBanner = document.getElementById('halt-banner');
+        if (data.halt) {
+          haltBanner.hidden = false;
+          document.getElementById('halt-text').textContent = 'SWARM HALTED — ' + data.halt.reason;
+          document.getElementById('halt-meta').textContent = 'since ' + data.halt.at + ' by ' + data.halt.by + ' — claim, release, and next refuse until a human runs nexus resume';
+        } else {
+          haltBanner.hidden = true;
+        }
+
         // Don't re-render DOM while user has a popover open or is working in DevTools
         if (document.querySelector('.task-popover:popover-open')) return;
         document.getElementById('repo').textContent = data.repo + ' . ' + data.branch;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@inkobytes/nexus",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Multi-agent coordination CLI for coding agents sharing a local repository",
   "type": "module",
   "bin": {
     "nexus": "bin/nexus.js"
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js"
+    "test": "node --test test/**/*.test.js",
+    "prepublishOnly": "npm test"
   },
   "keywords": [
     "ai",
@@ -33,6 +34,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.

package/src/commands/chmod.js

@@ -1,6 +1,9 @@
 /**
  * nexus chmod — manage the promptCHMOD permission matrix.
- * Human-controlled only: blocks unverified sessions from editing.
+ * Advisory contract honored at session start, not mechanically enforced:
+ * the matrix is human-owned by convention, and the session gate below is an
+ * env-var check any process can set in one line. It deters accidental edits;
+ * it cannot stop a process that lies about its identity.
  *
  * r = read for reference
  * w = modify (claim/release already enforces this)
@@ -59,12 +62,13 @@ export default function chmod(args) {
     process.exit(1);
   }
 
-  // Human-only gate — ties into agent-identity trust detection
+  // Session gate — advisory by design: these env vars are settable by any
+  // process, so this deters accidental edits, nothing more.
   const trustSource = process.env.CLAUDECODE === '1' ? 'harness'
     : process.env.NEXUS_AGENT ? 'operator'
     : 'unverified';
   if (trustSource === 'unverified') {
-    console.error('[ERROR] nexus chmod requires a verified session (CLAUDECODE=1 or NEXUS_AGENT set).\nThe permission matrix is human-controlled — agents cannot self-elevate.');
+    console.error('[ERROR] nexus chmod expects a recognized session (CLAUDECODE=1 or NEXUS_AGENT set).\nThe matrix is human-owned by convention; this gate is advisory, not enforcement.\nHumans can edit _NEXUS_CHMOD.md directly.');
     process.exit(1);
   }