agentsys 5.8.3 → 5.8.5

package/CHANGELOG.md

@@ -9,6 +9,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.8.5] - 2026-04-23
+
+### Fixed
+- **Hardcoded developer paths in web-ctl skills** (#333) - replaced 76 occurrences of `/Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js` with `~/.agentsys/...` across `.kiro/skills/web-auth/SKILL.md` (16 sites) and `.kiro/skills/web-browse/SKILL.md` (60 sites). The original absolute path only existed on the maintainer's machine, so every CLI example silently failed for any other user. The portable form matches the install path documented in `meta/skills/maintain-cross-platform/SKILL.md` and works for both shell copy-paste and agent execution (Bash tool's `bash -c` performs tilde expansion).
+- **`prepare` lifecycle hook auto-installed git hooks on every `npm install`** (#334) - moved hook installation from npm's `prepare` script to an explicit `setup-hooks` script so consumers no longer get hooks injected as a side effect of `npm install`. Documented opt-in flow in `CONTRIBUTING.md`. Also removed the no-op pre-commit placeholder (it just wrote a comment file - lib/ sync is handled by agent-core CI now), so only the actually-active pre-push hook (preflight + `/enhance` reminder + release-tag validation) is installed.
+- **`npm version` lifecycle dropped downstream version stamps** (#339, #342) - replaced `git add -A` (which would sweep unrelated working-tree changes into the version commit) with an explicit allowlist covering every file `stamp-version.js` writes plus npm's own lockfile and `CHANGELOG.md`: `package.json`, `package-lock.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `site/content.json`, `CHANGELOG.md`. Preserves the original intent (no working-tree sweep) while keeping all version manifests consistent after `npm version`. (CHANGELOG.md added per gemini-code-assist review on #342 - the developer manually edits CHANGELOG before each release, so it must be in the allowlist or `npm version`'s auto-commit drops the changelog entry.)
+
+### Changed
+- **`js-yaml` dependency range tightened from `^4.1.1` to `~4.1.1`** (#335) - blocks unintended `4.x` minor bumps while still allowing `4.1.x` patch updates so runtime security fixes flow in automatically. Lockfile root entry synced to match.
+
+## [5.8.4] - 2026-04-20
+
+### Fixed
+- **tasks.json atomic optimistic locking** (#331) - Concurrent `/next-task` and `/ship` runs could silently lose claims or leave stale registry entries due to unguarded read-modify-write on `tasks.json`. Fix uses `_version` + per-write `_writerId` optimistic locking (mirrors existing `flow.json` pattern): write atomically via rename, re-read and verify both fields match before declaring success, retry up to 5× with jitter on mismatch.
+- **tasks.json schema unification** - `worktree-manager` wrote `{ version, tasks[] }` while `workflow-state.js` read `{ active }`, causing claim exclusion in `discover-tasks` to always return an empty set. Unified schema is `{ active, tasks[], _version, _writerId }` with on-read normalization of both legacy formats — no migration needed.
+- **Silent corruption risk** - `readTasks()` now throws on corrupted JSON instead of returning a safe default, preventing `updateTasks` from silently overwriting potentially recoverable data.
+- **Agent prompt raw file writes** - `worktree-manager` Phase 6 and Cleanup Reference replaced inline `fs.writeFileSync` with `workflowState.claimTask()` / `workflowState.releaseTask()` library calls that are atomic and retry-safe.
+
+### Added
+- `updateTasks(mutatorFn)` - optimistic-lock loop for `tasks.json` mutations (mirrors `updateFlow`)
+- `claimTask(entry, projectPath)` - atomic upsert into `tasks[]` registry for worktree-manager
+- `releaseTask(taskId, projectPath)` - atomic removal from `tasks[]` registry for ship/abort; idempotent
+
 ## [5.8.3] - 2026-04-11
 
 ### Fixed

package/README.md

@@ -19,8 +19,8 @@
 </p>
 
 <p align="center">
-  <b>19 plugins · 47 agents · 40 skills (across all repos) · 30k lines of lib code · 3,583 tests · 5 platforms</b><br>
-  <em>Plugins distributed as standalone repos under <a href="https://github.com/agent-sh">agent-sh</a> org — agentsys is the marketplace &amp; installer</em>
+  <b>19 plugins · 49 agents · 41 skills (across all repos) · 30k lines of lib code · 3,507 tests · 5 platforms</b><br>
+  <em>Plugins distributed as standalone repos under <a href="https://github.com/agent-sh">agent-sh</a> org - agentsys is the marketplace &amp; installer</em>
 </p>
 
 <p align="center">
@@ -38,14 +38,14 @@
 
 ---
 
-AI models can write code. That's not the hard part anymore. The hard part is everything around it — task selection, branch management, code review, artifact cleanup, CI, PR comments, deployment. **AgentSys is the runtime that orchestrates agents to handle all of it** — structured pipelines, gated phases, specialized agents, and persistent state that survives session boundaries.
+AI models can write code. That's not the hard part anymore. The hard part is everything around it - task selection, branch management, code review, artifact cleanup, CI, PR comments, deployment. **AgentSys is the runtime that orchestrates agents to handle all of it** - structured pipelines, gated phases, specialized agents, and persistent state that survives session boundaries.
 
 ---
-> Building custom skills, agents, hooks, or MCP tools? [agnix](https://github.com/agent-sh/agnix) is the CLI + LSP linter that catches config errors before they fail silently - real-time IDE validation, auto suggestions, auto-fix, and 385 rules for Claude Code, Codex, OpenCode, Cursor, Kiro, Copilot, Gemini CLI, Cline, Windsurf, Roo Code, Amp, and more.
+> Building custom skills, agents, hooks, or MCP tools? [agnix](https://github.com/agent-sh/agnix) is the CLI + LSP linter that catches config errors before they fail silently - real-time IDE validation, auto suggestions, auto-fix, and 399 rules for Claude Code, Codex, OpenCode, Cursor, Kiro, Copilot, Gemini CLI, Cline, Windsurf, Roo Code, Amp, and more.
 
 ## What This Is
 
-An agent orchestration system — 19 plugins, 47 agents, and 40 skills that compose into structured pipelines for software development. Each plugin lives in its own standalone repo under the [agent-sh](https://github.com/agent-sh) org. agentsys is the marketplace and installer that ties them together.
+An agent orchestration system - 19 plugins, 49 agents (39 file-based + 10 role-based specialists in audit-project), and 41 skills that compose into structured pipelines for software development. Each plugin lives in its own standalone repo under the [agent-sh](https://github.com/agent-sh) org. agentsys is the marketplace and installer that ties them together.
 
 Each agent has a single responsibility, a specific model assignment, and defined inputs/outputs. Pipelines enforce phase gates so agents can't skip steps. State persists across sessions so work survives interruptions.
 
@@ -57,8 +57,8 @@ The system runs on Claude Code, OpenCode, Codex CLI, Cursor, and Kiro. Install v
 
 **Code does code work. AI does AI work.**
 
-- **Detection**: regex, AST analysis, static analysis—fast, deterministic, no tokens wasted
-- **Judgment**: LLM calls for synthesis, planning, review—where reasoning matters
+- **Detection**: regex, AST analysis, static analysis - fast, deterministic, no tokens wasted
+- **Judgment**: LLM calls for synthesis, planning, review - where reasoning matters
 - **Result**: 77% fewer tokens for [/drift-detect](#drift-detect) vs multi-agent approaches, certainty-graded findings throughout
 
 **Certainty levels exist because not all findings are equal:**
@@ -118,7 +118,7 @@ The investment shifts from model spend to pipeline design. Better prompts, riche
 | [`/next-task`](#next-task) | Task workflow: discovery, implementation, PR, merge |
 | [`/prepare-delivery`](#prepare-delivery) | Pre-ship quality gates: deslop, review, validation, docs sync |
 | [`/gate-and-ship`](#gate-and-ship) | Quality gates then ship (/prepare-delivery + /ship) |
-| [`/agnix`](#agnix) | Lint agent configurations (385 rules) |
+| [`/agnix`](#agnix) | Lint agent configurations (399 rules) |
 | [`/ship`](#ship) | PR creation, CI monitoring, merge |
 | [`/deslop`](#deslop) | Clean AI slop patterns |
 | [`/perf`](#perf) | Performance investigation with baselines and profiling |
@@ -142,7 +142,7 @@ Each command works standalone. Together, they compose into end-to-end pipelines.
 
 ## Skills
 
-40 skills included across the plugins:
+41 skills included across the plugins:
 
 | Category | Skills |
 |----------|--------|
@@ -157,6 +157,7 @@ Each command works standalone. Together, they compose into end-to-end pipelines.
 | **Web** | `web-auth`, `web-browse` |
 | **Release** | `release` |
 | **Analysis** | `drift-analysis`, `repo-intel` |
+| **Linting** | `agnix` |
 
 **External skill plugins** (standalone repos, installed separately):
 
@@ -175,7 +176,7 @@ Skills are the reusable implementation units. Agents invoke skills; commands orc
 | [The Approach](#the-approach) | Why it's built this way |
 | [Benchmarks](#benchmarks) | Sonnet + agentsys vs raw Opus |
 | [Commands](#commands) | All 20 commands overview |
-| [Skills](#skills) | 40 skills across plugins |
+| [Skills](#skills) | 41 skills across plugins |
 | [Skill-Only Plugins](#skill-only-plugins) | glide-mq and other non-command plugins |
 | [Command Details](#command-details) | Deep dive into each command |
 | [How Commands Work Together](#how-commands-work-together) | Standalone vs integrated |
@@ -328,7 +329,7 @@ agnix catches these issues before they cause problems.
 | **Best Practices** | Tool restrictions, model selection, trigger phrase quality |
 | **Cross-Platform** | Compatibility across Claude Code, Codex, OpenCode, Cursor, Kiro, Copilot, Gemini CLI, Cline, Windsurf, Roo Code, Amp, and more |
 
-**385 validation rules** (102 auto-fixable) derived from:
+**399 validation rules** (126 auto-fixable) derived from:
 - Official tool specifications (Claude Code, Codex CLI, OpenCode, Cursor, Kiro, GitHub Copilot, Gemini CLI, Cline, Windsurf, Roo Code, Amp, and more)
 - Research papers on agent reliability and prompt injection
 - Real-world testing across 500+ repositories
@@ -442,7 +443,7 @@ If something can't be fixed, the workflow replies explaining why and resolves th
 
 ### /deslop
 
-**Purpose:** Finds AI slop—debug statements, placeholder text, verbose comments, TODOs—and removes it.
+**Purpose:** Finds AI slop - debug statements, placeholder text, verbose comments, TODOs - and removes it.
 
 **How detection works:**
 
@@ -613,13 +614,14 @@ Findings are collected and categorized by severity (critical/high/medium/low). A
 
 **Purpose:** Analyzes your prompts, plugins, agents, docs, hooks, and skills for improvement opportunities.
 
-**Seven analyzers run in parallel:**
+**Eight analyzers run in parallel:**
 
 | Analyzer | What it checks |
 |----------|----------------|
 | plugin-enhancer | Plugin structure, MCP tool definitions, security patterns |
 | agent-enhancer | Agent frontmatter, prompt quality |
 | claudemd-enhancer | CLAUDE.md/AGENTS.md structure, token efficiency |
+| cross-file-enhancer | Cross-file consistency (tools vs frontmatter, duplicate rules, conflicts) |
 | docs-enhancer | Documentation readability, RAG optimization |
 | prompt-enhancer | Prompt engineering patterns, clarity, examples |
 | hooks-enhancer | Hook frontmatter, structure, safety |
@@ -656,7 +658,7 @@ Findings are collected and categorized by severity (critical/high/medium/low). A
 - AST symbol mapping: exports, functions, classes, imports
 - Project metadata and health metrics
 
-Output is cached at `{state-dir}/repo-intel.json` and `{state-dir}/repo-map.json`.
+Output is cached at `{state-dir}/repo-intel.json` (external repo-intel plugin) and `{state-dir}/repo-map.json` (agentsys internal repo-map library). `{state-dir}` is `.claude/`, `.opencode/`, or `.codex/` depending on your platform.
 
 **Why it matters:**
 
@@ -678,7 +680,7 @@ Backed by [agent-analyzer](https://github.com/agent-sh/agent-analyzer) Rust bina
 
 ### /sync-docs
 
-**Purpose:** Sync documentation with actual code changes—find outdated refs, update CHANGELOG, flag stale examples.
+**Purpose:** Sync documentation with actual code changes - find outdated refs, update CHANGELOG, flag stale examples.
 
 **The problem it solves:**
 
@@ -958,7 +960,7 @@ No per-turn overhead - it reads transcripts that Claude Code already saves.
 **What happens when you run it:**
 
 1. **Collect** (68ms median) - Pure JavaScript scans manifest, structure, README, CI, git info. Normal depth adds CLAUDE.md/AGENTS.md and repo-intel. No LLM tokens.
-2. **Synthesize** - Opus agent produces a structured overview: tech stack, key files, active areas, conventions
+2. **Synthesize** - Sonnet agent produces a structured overview: tech stack, key files, active areas, conventions
 3. **Guide** - Interactive Q&A: ask about specific files, areas, or patterns
 
 **74% fewer tokens** than manual onboarding. Validated on 100 repos across JS/TS, Rust, Go, Python, C/C++, Java, and Deno.
@@ -981,7 +983,7 @@ No per-turn overhead - it reads transcripts that Claude Code already saves.
 /onboard --depth=deep       # Include AST data
 ```
 
-**Agent:** onboard-agent (opus model)
+**Agent:** onboard-agent (sonnet model)
 
 [Full documentation →](https://github.com/agent-sh/onboard)
 
@@ -994,7 +996,7 @@ No per-turn overhead - it reads transcripts that Claude Code already saves.
 **What happens when you run it:**
 
 1. **Collect** - Gathers project data + contributor signals (test gaps, doc drift, bugspots, good-first areas, open issues). Validated on 100 repos.
-2. **Match** - Opus agent asks about developer background and matches skills to project needs
+2. **Match** - Sonnet agent asks about developer background and matches skills to project needs
 3. **Guide** - For each recommendation: reads code, explains what needs doing, gives a concrete first step
 
 **Matching:**
@@ -1015,7 +1017,7 @@ No per-turn overhead - it reads transcripts that Claude Code already saves.
 /can-i-help --depth=deep          # Include AST data
 ```
 
-**Agent:** can-i-help-agent (opus model)
+**Agent:** can-i-help-agent (sonnet model)
 
 [Full documentation →](https://github.com/agent-sh/can-i-help)
 
@@ -1092,7 +1094,7 @@ Same principle as good code: single responsibility. The exploration-agent explor
 
 **2. Pipeline with gates, not a monolith**
 
-Same principle as DevOps. Each step must pass before the next begins. Can't push before review. Can't merge before CI passes. Hooks enforce this—agents literally cannot skip phases.
+Same principle as DevOps. Each step must pass before the next begins. Can't push before review. Can't merge before CI passes. Hooks enforce this - agents literally cannot skip phases.
 
 **3. Tools do tool work, agents do agent work**
 
@@ -1235,7 +1237,7 @@ The system is built on research, not guesswork.
 - Instruction following reliability
 
 **Testing:**
-- 3,583 tests passing
+- 3,507 tests passing
 - Drift-detect validated on 1,000+ repositories
 - E2E workflow testing across all commands
 - Cross-platform validation (Claude Code, OpenCode, Codex CLI, Cursor, Kiro)

package/lib/state/workflow-state.js

@@ -117,62 +117,248 @@ function getTasksPath(projectPath = process.cwd()) {
 }
 
 /**
- * Read tasks.json from main project
- * Returns { active: null } if file doesn't exist or is corrupted
- * Logs critical error on corruption to prevent silent data loss
+ * Read tasks.json from main project.
+ *
+ * Unified schema (v2):
+ *   { active: null|Object, tasks: [], _version: number }
+ *
+ * - active: single active workflow entry (set by createFlow / cleared by completeWorkflow)
+ * - tasks:  worktree claim registry (set by worktree-manager / cleared by ship or --abort)
+ * - _version: monotonic counter for optimistic locking (managed by writeTasks)
+ * - _writerId: per-write unique token used by updateTasks to detect concurrent wins
+ *
+ * Legacy formats are normalized on read — no migration script needed.
+ * Throws on corruption so callers can decide whether to abort or recover,
+ * rather than silently overwriting potentially recoverable data.
+ *
+ * @param {string} projectPath
+ * @returns {{ active: null|Object, tasks: Array, _version: number, _writerId?: string }}
+ * @throws {Error} If tasks.json exists but cannot be parsed
  */
 function readTasks(projectPath = process.cwd()) {
   const tasksPath = getTasksPath(projectPath);
   if (!fs.existsSync(tasksPath)) {
-    return { active: null };
+    return { active: null, tasks: [], _version: 0 };
   }
+  const raw = fs.readFileSync(tasksPath, 'utf8');
+  let data;
   try {
-    const data = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
-    // Normalize legacy format that may not have 'active' field
-    if (!Object.prototype.hasOwnProperty.call(data, 'active')) {
-      return { active: null };
-    }
-    return data;
+    data = JSON.parse(raw);
   } catch (e) {
-    console.error(`[CRITICAL] Corrupted tasks.json at ${tasksPath}: ${e.message}`);
-    return { active: null };
+    throw new Error(`[CRITICAL] Corrupted tasks.json at ${tasksPath}: ${e.message}. File must be repaired or deleted manually before writes are allowed.`);
   }
+  // Normalize: ensure every field exists (handles legacy { active } and legacy { version, tasks[] })
+  return {
+    active: Object.prototype.hasOwnProperty.call(data, 'active') ? data.active : null,
+    tasks: Array.isArray(data.tasks) ? data.tasks : [],
+    _version: typeof data._version === 'number' ? data._version : 0,
+    _writerId: typeof data._writerId === 'string' ? data._writerId : undefined
+  };
 }
 
 /**
- * Write tasks.json to main project
+ * Write tasks.json atomically.
+ * Increments _version and stamps a unique _writerId per write.
+ *
+ * Both fields are used by updateTasks to verify it was the winning writer:
+ * if two processes both read _version N, both write _version N+1 (last
+ * renameSync wins), the loser re-reads and finds a _writerId that does not
+ * match its own — it knows it lost and retries.
+ *
+ * @returns {string} The _writerId stamped into this write
  */
 function writeTasks(tasks, projectPath = process.cwd()) {
   ensureStateDir(projectPath);
+  const copy = structuredClone(tasks);
+  copy._version = (copy._version || 0) + 1;
+  copy._writerId = crypto.randomBytes(8).toString('hex');
   const tasksPath = getTasksPath(projectPath);
-  writeJsonAtomic(tasksPath, tasks);
-  return true;
+  writeJsonAtomic(tasksPath, copy);
+  return copy._writerId;
 }
 
 /**
- * Set active task in main project
+ * Apply a mutation to tasks.json with optimistic locking.
+ *
+ * Uses _version + _writerId to detect wins in concurrent-writer races:
+ *   1. Read current state, snapshot _version
+ *   2. Apply mutatorFn(clone) → new state; skip write if state unchanged
+ *   3. Stamp a unique writerId, write atomically (increments _version)
+ *   4. Re-read: if _version === initialVersion + 1 AND _writerId matches → we won
+ *   5. Otherwise another writer raced us → back off with jitter, retry
+ *
+ * @param {function(Object): Object} mutatorFn - Pure function that receives a
+ *   deep clone of current tasks state and returns the desired new state.
+ *   Must not have side effects; may be called multiple times on retry.
+ * @param {string} projectPath
+ * @returns {boolean} true on success, false after MAX_RETRIES exhausted or on corruption
+ */
+function updateTasks(mutatorFn, projectPath = process.cwd()) {
+  const MAX_RETRIES = 5;
+
+  let current;
+  try {
+    current = readTasks(projectPath);
+  } catch (e) {
+    console.error(`[ERROR] updateTasks: cannot read tasks.json — ${e.message}`);
+    return false;
+  }
+
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    const initialVersion = current._version || 0;
+
+    let updated;
+    try {
+      updated = mutatorFn(structuredClone(current));
+    } catch (e) {
+      console.error(`[ERROR] updateTasks: mutatorFn threw on attempt ${attempt + 1}: ${e.message}`);
+      return false;
+    }
+
+    // Skip write if mutatorFn made no changes — avoids spurious version bumps
+    if (JSON.stringify(updated) === JSON.stringify(current)) {
+      return true;
+    }
+
+    // Carry forward the pre-write version so writeTasks increments it by exactly 1
+    updated._version = initialVersion;
+
+    const writerId = writeTasks(updated, projectPath);
+
+    // Verify we won: version must be exactly initialVersion + 1 AND writerId must match ours.
+    // If another process also wrote _version: initialVersion + 1, only one writerId survives.
+    let afterWrite;
+    try {
+      afterWrite = readTasks(projectPath);
+    } catch (e) {
+      console.error(`[ERROR] updateTasks: tasks.json corrupted after write on attempt ${attempt + 1}: ${e.message}`);
+      return false;
+    }
+
+    if (afterWrite._version === initialVersion + 1 && afterWrite._writerId === writerId) {
+      return true;
+    }
+
+    // Lost the race — retry from the current on-disk state
+    if (attempt < MAX_RETRIES - 1) {
+      const delay = Math.floor(Math.random() * 50) + 10;
+      sleepForRetry(delay);
+      try {
+        current = readTasks(projectPath);
+      } catch (e) {
+        console.error(`[ERROR] updateTasks: tasks.json corrupted during retry ${attempt + 1}: ${e.message}`);
+        return false;
+      }
+    }
+  }
+
+  const tasksPath = getTasksPath(projectPath);
+  let lastVersion = '(unreadable)';
+  try { lastVersion = readTasks(projectPath)._version; } catch {}
+
+  // Final fallback: if a concurrent writer happened to apply the exact same
+  // mutation (idempotent operations like releaseTask on an already-absent entry),
+  // treat the outcome as a success rather than reporting a spurious failure.
+  let latest;
+  try { latest = readTasks(projectPath); } catch {}
+  if (latest) {
+    // Re-run the mutator on what's on disk; if the result is identical to
+    // what's already there, our desired state is already achieved.
+    try {
+      const wouldBe = mutatorFn(structuredClone(latest));
+      // Normalize _version/_writerId before comparing content
+      wouldBe._version = latest._version;
+      wouldBe._writerId = latest._writerId;
+      if (JSON.stringify(wouldBe) === JSON.stringify(latest)) {
+        return true;
+      }
+    } catch {}
+  }
+
+  console.error(
+    `[ERROR] updateTasks: all ${MAX_RETRIES} attempts failed due to concurrent writers on ${tasksPath}. ` +
+    `Another agent process is modifying the registry simultaneously. ` +
+    `Last known _version: ${lastVersion}. ` +
+    `Suggested recovery: wait for the competing process to finish, then retry the operation.`
+  );
+  return false;
+}
+
+/**
+ * Set active task in main project (uses optimistic locking)
  */
 function setActiveTask(task, projectPath = process.cwd()) {
-  const tasks = readTasks(projectPath);
-  tasks.active = {
-    ...task,
-    startedAt: new Date().toISOString()
-  };
-  return writeTasks(tasks, projectPath);
+  return updateTasks(tasks => {
+    tasks.active = { ...task, startedAt: new Date().toISOString() };
+    return tasks;
+  }, projectPath);
 }
 
 /**
- * Clear active task
+ * Clear active task (uses optimistic locking)
  */
 function clearActiveTask(projectPath = process.cwd()) {
-  const tasks = readTasks(projectPath);
-  tasks.active = null;
-  return writeTasks(tasks, projectPath);
+  return updateTasks(tasks => {
+    tasks.active = null;
+    return tasks;
+  }, projectPath);
+}
+
+/**
+ * Claim a task in the registry (uses optimistic locking).
+ * Used by worktree-manager; replaces the raw fs.writeFileSync inline in agent prompts.
+ *
+ * @param {Object} entry - { id, source, title, branch, worktreePath, claimedBy }
+ * @param {string} projectPath
+ */
+function claimTask(entry, projectPath = process.cwd()) {
+  if (!entry || !entry.id) {
+    console.error('[ERROR] claimTask: entry.id is required');
+    return false;
+  }
+  return updateTasks(tasks => {
+    const idx = tasks.tasks.findIndex(t => t.id === entry.id);
+    const record = {
+      ...entry,
+      status: 'claimed',
+      claimedAt: entry.claimedAt || new Date().toISOString(),
+      lastActivityAt: new Date().toISOString()
+    };
+    if (idx >= 0) {
+      tasks.tasks[idx] = record;
+    } else {
+      tasks.tasks.push(record);
+    }
+    return tasks;
+  }, projectPath);
+}
+
+/**
+ * Release a claimed task from the registry (uses optimistic locking).
+ * Used by ship and --abort; replaces the raw fs.writeFileSync inline cleanup.
+ *
+ * @param {string} taskId
+ * @param {string} projectPath
+ */
+function releaseTask(taskId, projectPath = process.cwd()) {
+  if (!taskId) {
+    console.error('[ERROR] releaseTask: taskId is required');
+    return false;
+  }
+  return updateTasks(tasks => {
+    const before = tasks.tasks.length;
+    tasks.tasks = tasks.tasks.filter(t => t.id !== taskId);
+    if (tasks.tasks.length === before) {
+      // Not found — that's fine, idempotent
+      console.error(`[WARN] releaseTask: task ${taskId} was not found in tasks.json registry. It may have already been released or never claimed.`);
+    }
+    return tasks;
+  }, projectPath);
 }
 
 /**
- * Check if there's an active task
- * Uses != null to catch both null and undefined (legacy format safety)
+ * Check if there's an active task.
+ * Uses != null to catch both null and undefined (legacy format safety).
  */
 function hasActiveTask(projectPath = process.cwd()) {
   const tasks = readTasks(projectPath);
@@ -548,8 +734,11 @@ module.exports = {
   getTasksPath,
   readTasks,
   writeTasks,
+  updateTasks,
   setActiveTask,
   clearActiveTask,
+  claimTask,
+  releaseTask,
   hasActiveTask,
 
   // Flow (worktree)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsys",
-  "version": "5.8.3",
+  "version": "5.8.5",
   "description": "A modular runtime and orchestration system for AI agents - works with Claude Code, OpenCode, and Codex CLI",
   "main": "lib/platform/detect-platform.js",
   "type": "commonjs",
@@ -37,8 +37,8 @@
     "bump": "node bin/dev-cli.js bump",
     "detect": "node bin/dev-cli.js detect",
     "verify": "node bin/dev-cli.js verify",
-    "version": "node scripts/stamp-version.js && git add -A",
-    "prepare": "node bin/dev-cli.js setup-hooks"
+    "version": "node scripts/stamp-version.js && git add package.json package-lock.json .claude-plugin/plugin.json .claude-plugin/marketplace.json site/content.json CHANGELOG.md",
+    "setup-hooks": "node bin/dev-cli.js setup-hooks"
   },
   "repository": {
     "type": "git",
@@ -82,7 +82,7 @@
   },
   "dependencies": {
     "agentsys": "^5.0.0",
-    "js-yaml": "^4.1.1"
+    "js-yaml": "~4.1.1"
   },
   "devDependencies": {
     "jest": "^29.7.0"

package/scripts/generate-docs.js

@@ -109,7 +109,8 @@ const STATIC_SKILLS = [
   { plugin: 'audit-project', name: 'audit-project' },
   { plugin: 'glidemq', name: 'glide-mq' },
   { plugin: 'glidemq', name: 'glide-mq-migrate-bullmq' },
-  { plugin: 'glidemq', name: 'glide-mq-migrate-bee' }
+  { plugin: 'glidemq', name: 'glide-mq-migrate-bee' },
+  { plugin: 'agnix', name: 'agnix' }
 ];
 
 // Purpose mapping for architecture table
@@ -192,7 +193,7 @@ function generateCommandsTable(commands) {
     'next-task': 'Task workflow: discovery, implementation, PR, merge',
     'prepare-delivery': 'Pre-ship quality gates: deslop, review, validation, docs sync',
     'gate-and-ship': 'Quality gates then ship (/prepare-delivery + /ship)',
-    'agnix': 'Lint agent configurations (385 rules)',
+    'agnix': 'Lint agent configurations (399 rules)',
     'ship': 'PR creation, CI monitoring, merge',
     'deslop': 'Clean AI slop patterns',
     'perf': 'Performance investigation with baselines and profiling',
@@ -395,9 +396,34 @@ function generateAgentCounts(agents, plugins) {
 /**
  * Update counts in site/content.json programmatically.
  */
-// Static counts for cross-repo plugins not discoverable locally
-const STATIC_PLUGIN_COUNT = 19;
-const STATIC_AGENT_COUNT = 47;
+// Static counts for cross-repo plugins not discoverable locally.
+// Per-plugin file-based agent counts. Update this map when agents are added/removed
+// in a plugin repo - it's the canonical source for the STATIC_AGENT_COUNT fallback.
+const STATIC_PLUGIN_AGENT_COUNTS = {
+  'next-task': 8,
+  'prepare-delivery': 3,
+  'gate-and-ship': 0,
+  'ship': 1,
+  'deslop': 1,
+  'audit-project': 0,
+  'drift-detect': 1,
+  'enhance': 8,
+  'sync-docs': 1,
+  'repo-intel': 1,
+  'perf': 6,
+  'learn': 1,
+  'agnix': 1,
+  'consult': 1,
+  'debate': 1,
+  'web-ctl': 1,
+  'skillers': 2,
+  'onboard': 1,
+  'can-i-help': 1
+};
+const STATIC_PLUGIN_COUNT = Object.keys(STATIC_PLUGIN_AGENT_COUNTS).length;
+const STATIC_FILE_BASED_AGENT_COUNT = Object.values(STATIC_PLUGIN_AGENT_COUNTS).reduce((sum, count) => sum + count, 0);
+// Total = file-based + role-based (audit-project specialists, spawned dynamically)
+const STATIC_AGENT_COUNT = STATIC_FILE_BASED_AGENT_COUNT + ROLE_BASED_AGENT_COUNT;
 
 function updateSiteContent(plugins, agents, skills) {
   const contentPath = path.join(ROOT_DIR, 'site', 'content.json');
@@ -652,6 +678,8 @@ module.exports = {
   PURPOSE_MAP,
   ROLE_BASED_AGENT_COUNT,
   STATIC_SKILLS,
+  STATIC_PLUGIN_AGENT_COUNTS,
   STATIC_PLUGIN_COUNT,
+  STATIC_FILE_BASED_AGENT_COUNT,
   STATIC_AGENT_COUNT
 };

package/scripts/setup-hooks.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 /**
  * Setup git hooks for development
- * - pre-commit: Placeholder (lib/ sync handled by agent-core CI)
  * - pre-push: Runs preflight checks, /enhance reminder, release validation
  */
 
@@ -9,13 +8,8 @@ const fs = require('fs');
 const path = require('path');
 
 const hookDir = path.join(__dirname, '..', '.git', 'hooks');
-const preCommitPath = path.join(hookDir, 'pre-commit');
 const prePushPath = path.join(hookDir, 'pre-push');
 
-const preCommitHook = `#!/bin/sh
-# Pre-commit hook (lib/ sync now handled by agent-core)
-`;
-
 const prePushHook = `#!/bin/sh
 # Pre-push validations:
 # 1. Run preflight checks (validators + gap checks)
@@ -135,14 +129,6 @@ function main() {
     return 0;
   }
 
-  try {
-    fs.writeFileSync(preCommitPath, preCommitHook, { mode: 0o755 });
-    console.log('Git pre-commit hook installed');
-  } catch (err) {
-    // Non-fatal - might not have write permissions
-    console.warn('Could not install pre-commit hook:', err.message);
-  }
-
   try {
     fs.writeFileSync(prePushPath, prePushHook, { mode: 0o755 });
     console.log('Git pre-push hook installed (release tag validation)');