@cardor/agent-harness-kit 1.6.2 → 1.6.4

package/README.md

@@ -46,6 +46,7 @@ npx ahk init
     - [`ahk export`](#ahk-export)
   - [Files created by `ahk init`](#files-created-by-ahk-init)
     - [What each file does](#what-each-file-does)
+  - [Tasks schema](#tasks-schema)
   - [What you can customize](#what-you-can-customize)
     - [`agent-harness-kit.config.ts`](#agent-harness-kitconfigts)
     - [`health.sh`](#healthsh)
@@ -53,6 +54,7 @@ npx ahk init
     - [`.harness/feature_list.json`](#harnessfeature_listjson)
   - [MCP tools (for agents)](#mcp-tools-for-agents)
   - [Agent roles](#agent-roles)
+    - [MCP tool permissions by role](#mcp-tool-permissions-by-role)
   - [What to commit](#what-to-commit)
   - [Runtime compatibility](#runtime-compatibility)
   - [Contributing \& local development](#contributing--local-development)
@@ -577,56 +579,62 @@ Good acceptance criteria make the difference — the reviewer agent uses them to
 
 The harness exposes these tools via MCP. Agents use them instead of reading files directly.
 
-| Tool                      | Parameters                                      | Description                                                                                                                                             |
-| ------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tasks.get`               | `status?`                                       | List tasks, optionally filtered by `pending \| in_progress \| done \| blocked`                                                                          |
-| `tasks.claim`             | `id, agent`                                     | Atomically claim a pending task. Returns `task_already_claimed` if another agent got it first                                                           |
-| `tasks.update`            | `id, status`                                    | Change task status                                                                                                                                      |
-| `tasks.add`               | `title, slug?, description?, acceptance?`       | Create a new task directly from MCP (agents can queue work on the fly)                                                                                  |
-| `tasks.acceptance.update` | `criterionId`                                   | Mark an acceptance criterion as met. Criterion IDs come from `tasks.acceptance_get`                                                                     |
-| `actions.start`           | `taskId, agent`                                 | Start a new action, returns `actionId`                                                                                                                  |
-| `actions.write`           | `actionId, sectionType, content`                | Record a text section: `result \| tools_used \| blockers \| next_steps`. Does **not** populate the Files dashboard — use `actions.record_file` for that |
-| `actions.complete`        | `actionId, summary`                             | Close an action with a one-line summary                                                                                                                 |
-| `actions.get`             | `taskId`                                        | Full action history for a task (all agents, all sections)                                                                                               |
-| `actions.record_file`     | `actionId, filePath, operation, notes?`         | Register a file touch. The **only** way to populate the Files dashboard. `operation`: `read \| created \| modified \| deleted`                          |
-| `actions.record_tool`     | `actionId, toolName, argsJson?, resultSummary?` | Register a tool call. The **only** way to populate the Tools dashboard                                                                                  |
-| `docs.search`             | `query`                                         | Search the `docsPath` folder for content matching the query                                                                                             |
-| `tasks.acceptance_get`    | `taskId`    | Returns all acceptance criteria for a task with their `id`, `task_id`, `criterion` text, and `met` status. Use the returned `id` values with `tasks.acceptance.update` |
+| Tool                      | Parameters                                      | Description                                                                                                                                                            |
+| ------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tasks.get`               | `status?`                                       | List tasks, optionally filtered by `pending \| in_progress \| done \| blocked`                                                                                         |
+| `tasks.claim`             | `id, agent`                                     | Atomically claim a pending task. Returns `task_already_claimed` if another agent got it first                                                                          |
+| `tasks.update`            | `id, status`                                    | Change task status                                                                                                                                                     |
+| `tasks.add`               | `title, slug?, description?, acceptance?`       | Create a new task directly from MCP (agents can queue work on the fly)                                                                                                 |
+| `tasks.acceptance.update` | `criterionId`                                   | Mark an acceptance criterion as met. Criterion IDs come from `tasks.acceptance_get`                                                                                    |
+| `actions.start`           | `taskId, agent`                                 | Start a new action, returns `actionId`                                                                                                                                 |
+| `actions.write`           | `actionId, sectionType, content`                | Record a text section: `result \| tools_used \| blockers \| next_steps`. Does **not** populate the Files dashboard — use `actions.record_file` for that                |
+| `actions.complete`        | `actionId, summary`                             | Close an action with a one-line summary                                                                                                                                |
+| `actions.get`             | `taskId`                                        | Full action history for a task (all agents, all sections)                                                                                                              |
+| `actions.record_file`     | `actionId, filePath, operation, notes?`         | Register a file touch. The **only** way to populate the Files dashboard. `operation`: `read \| created \| modified \| deleted`                                         |
+| `actions.record_tool`     | `actionId, toolName, argsJson?, resultSummary?` | Register a tool call. The **only** way to populate the Tools dashboard                                                                                                 |
+| `docs.search`             | `query`                                         | Search the `docsPath` folder for content matching the query                                                                                                            |
+| `tasks.acceptance_get`    | `taskId`                                        | Returns all acceptance criteria for a task with their `id`, `task_id`, `criterion` text, and `met` status. Use the returned `id` values with `tasks.acceptance.update` |
+| `deps.snapshot`           | _(none)_                                        | Snapshot current `package.json` dependencies to `.harness/deps-lock.json`                                                                                              |
+| `deps.check`              | _(none)_                                        | Compare current `package.json` against `.harness/deps-lock.json`. Returns `{ significant, added, removed, majorBumps, advisory }`                                      |
 
 ---
 
 ## Agent roles
 
-| Role         | Responsibility                                                                                    |
-| ------------ | ------------------------------------------------------------------------------------------------- |
-| **lead**     | Decomposes the task into a plan, assigns sub-agents. Does not write code or read source files.    |
-| **explorer** | Reads and maps the codebase. Never writes files. Records every file read.                         |
-| **builder**  | Implements the plan. Only writes to `writablePaths`. Records every file modified.                 |
-| **reviewer** | Verifies all acceptance criteria are met. Approves or blocks. Runs health check before approving. |
+| Role           | Responsibility                                                                                                                              |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **lead**       | Decomposes the task into a plan, assigns sub-agents. Does not write code or read source files.                                              |
+| **explorer**   | Reads and maps the codebase. Never writes files. Records every file read.                                                                   |
+| **consultant** | Provides structured technical advisory after explorer. Runs conditionally. Never writes code. Writes advisory to harness via actions.write. |
+| **builder**    | Implements the plan. Only writes to `writablePaths`. Records every file modified.                                                           |
+| **reviewer**   | Verifies all acceptance criteria are met. Approves or blocks. Runs health check before approving.                                           |
 
 ### MCP tool permissions by role
 
 Each agent role has a scoped set of MCP tools enforced through the agent definition files.
 
-| Tool | lead | explorer | builder | reviewer |
-|---|:---:|:---:|:---:|:---:|
-| `tasks.get` | ✅ | ✅ | ✅ | ✅ |
-| `tasks.claim` | ✅ | ✅ | ✅ | ✅ |
-| `tasks.add` | ✅ | ❌ | ✅ | ✅ |
-| `tasks.update` | ✅ | ❌ | ✅ | ✅ |
-| `tasks.edit` | ✅ | ❌ | ✅ | ✅ |
-| `tasks.archive` / `unarchive` | ✅ | ❌ | ✅ | ✅ |
-| `tasks.acceptance_get` | ✅ | ✅ | ✅ | ✅ |
-| `tasks.acceptance.update` | ❌ | ❌ | ❌ | ✅ |
-| `actions.*` (all 6) | ✅ | ✅ | ✅ | ✅ |
-| `docs.search` | ✅ | ✅ | ✅ | ✅ |
-| `permissions.check` | ✅ | ✅ | ✅ | ✅ |
+| Tool                          | lead | explorer | consultant | builder | reviewer |
+| ----------------------------- | :--: | :------: | :--------: | :-----: | :------: |
+| `tasks.get`                   |  ✅  |    ✅    |     ✅     |   ✅    |    ✅    |
+| `tasks.claim`                 |  ✅  |    ✅    |     ✅     |   ✅    |    ✅    |
+| `tasks.add`                   |  ✅  |    ❌    |     ❌     |   ✅    |    ✅    |
+| `tasks.update`                |  ✅  |    ❌    |     ❌     |   ✅    |    ✅    |
+| `tasks.edit`                  |  ✅  |    ❌    |     ❌     |   ✅    |    ✅    |
+| `tasks.archive` / `unarchive` |  ✅  |    ❌    |     ❌     |   ✅    |    ✅    |
+| `tasks.acceptance_get`        |  ✅  |    ✅    |     ✅     |   ✅    |    ✅    |
+| `tasks.acceptance.update`     |  ❌  |    ❌    |     ❌     |   ❌    |    ✅    |
+| `actions.*` (all 6)           |  ✅  |    ✅    |     ✅     |   ✅    |    ✅    |
+| `docs.search`                 |  ✅  |    ✅    |     ✅     |   ✅    |    ✅    |
+| `permissions.check`           |  ✅  |    ✅    |     ❌     |   ✅    |    ✅    |
+| `deps.snapshot`               |  ❌  |    ❌    |     ✅     |   ❌    |    ❌    |
+| `deps.check`                  |  ❌  |    ❌    |     ✅     |   ❌    |    ❌    |
 
 **explorer** is read-only for task state — can query but cannot mutate status or mark criteria.  
 **reviewer** is the only role that can mark acceptance criteria as met (`tasks.acceptance.update`).  
-**lead** and **builder** have identical access, both excluding `tasks.acceptance.update`.
+**lead** and **builder** have identical access, both excluding `tasks.acceptance.update`.  
+**consultant** is advisory-only — reads code, writes to harness, and can call deps tools. Never modifies the codebase.
 
-`permissions.check` compares each `.claude/agents/*.md` tool list against the canonical constants in the package. Returns `{ in_sync: bool, agents: { lead, explorer, builder, reviewer } }` with per-agent `missing` and `extra` arrays. Run `ahk build --sync` to fix any drift.
+`permissions.check` compares each `.claude/agents/*.md` tool list against the canonical constants in the package. Returns `{ in_sync: bool, agents: { lead, explorer, consultant, builder, reviewer } }` with per-agent `missing` and `extra` arrays. Run `ahk build --sync` to fix any drift.
 
 ---
 

package/dist/agent-templates/builder.md

@@ -75,7 +75,7 @@ If you touched 5 files and made 12 tool calls, there must be 5 `actions.record_f
 actions.get(taskId)
 ```
 
-Read the lead's `result` section (the plan) and the explorer's `result` section (the analysis). Do not start until you understand both.
+Read ALL previous actions via `actions.get(taskId)` — including the lead's plan, the explorer's analysis, and the consultant's advisory (if present). Do not rely on the lead summary alone. This includes the consultant's advisory (if present) — read it before writing any code.
 
 ### 2. Register your action
 

package/dist/agent-templates/consultant.md

@@ -0,0 +1,77 @@
+---
+name: consultant
+description: >
+  Technical advisor agent for {{projectName}}. Runs after the explorer and before the builder.
+  Provides structured advisory — patterns, best practices, warnings, and risks — written
+  directly to the harness so the builder can read it via actions.get. Never writes code.
+tools:
+  - Read
+  - Bash
+---
+
+# Consultant Agent — {{projectName}}
+
+You are the **consultant agent** for `{{projectName}}`. Your job is to provide structured technical advisory based on the explorer's findings. You do not write code or modify files.
+
+---
+
+## !! ABSOLUTE CONSTRAINT !!
+
+**YOU ARE FORBIDDEN FROM MODIFYING THE CODEBASE IN ANY WAY.**
+
+Read files. Think. Write your advisory to the harness. That is all.
+
+---
+
+## Responsibilities
+
+- Read the explorer's output via `actions.get(taskId)`
+- Analyse the relevant code sections identified by the explorer
+- Produce a structured advisory covering: patterns to follow, pitfalls to avoid, best practices, risks
+- Record your advisory directly in the harness so the builder reads it without lead filtering
+
+---
+
+## Workflow
+
+### 1. Read context
+
+```
+actions.get(taskId)   → read explorer's analysis and lead's plan
+```
+
+### 2. Analyse
+
+Read the files the explorer mapped. Focus on:
+- Existing patterns the builder must follow for consistency
+- Known gotchas or constraints in the affected code
+- Any risks introduced by the proposed change (breaking changes, perf, security)
+- Whether the task touches dependencies — if so, note any implications
+
+### 3. Write advisory
+
+```
+actions.start(taskId, 'consultant')  → save actionId
+actions.write(actionId, 'result', '<your structured advisory>')
+```
+
+Structure your advisory with clear headings:
+- **Patterns to follow** — what existing conventions apply
+- **Risks & warnings** — what could go wrong
+- **Best practices** — what the builder should keep in mind
+- **Dependency notes** — only if task touches package.json or deps
+
+### 4. Complete
+
+```
+actions.complete(actionId, 'Advisory written — <one-line summary>')
+```
+
+---
+
+## Hard rules
+
+- **No file writes, no edits, no Bash that changes state.** Read only.
+- **Do not summarize or paraphrase** the explorer's output for the builder — add new insight.
+- **Be specific.** Vague advice like "be careful" is useless. Name the file, line, pattern.
+- **One action per session.** Open one action, write your advisory, close it.

package/dist/agent-templates/lead.md

@@ -91,6 +91,13 @@ Then call `permissions.check` — if `in_sync: false`, inform the user before pr
 > "Your agent permissions are outdated. Run `ahk build --sync` to update, or I can guide you."
 Wait for the user to acknowledge before continuing the session.
 
+Then run deps tracking:
+```
+deps.snapshot   → save current dependency state (creates .harness/deps-lock.json if missing)
+deps.check      → returns diff vs. last snapshot
+```
+Save the `deps.check` result — you'll use it in step 7 to decide whether to invoke the consultant.
+
 Then check session state via MCP:
 
 ```
@@ -139,6 +146,9 @@ Think through:
 - What are the acceptance criteria the reviewer will check?
 - If codebase changes are involved: does the builder need to update README or `docs/` files?
 - Does this task touch user-facing behavior (CLI commands, MCP tools, DB schema, config, agent permissions)? If yes, add an acceptance criterion: `README.md and/or docs/ updated to reflect the change`
+- **Always append, as the LAST acceptance criterion for every task, this mandatory criterion:**
+  > `Docs/README analysis: [describe whether docs/, README.md, or other documentation files need to reflect this change and what specifically — or explicitly state 'no update needed' with brief reasoning]`
+  The analysis is non-negotiable. The conclusion can be "no update needed" but the reasoning must be stated. The reviewer will block if this criterion is absent or if the builder's action summary is silent on docs.
 
 Record it:
 
@@ -156,13 +166,20 @@ actions.complete(actionId, 'Plan defined — delegating to explorer')
 
 ### 7. Delegate in order
 
-Invoke: **Explorer** → **Builder** → **Reviewer**
+Invoke: **Explorer** → **Consultant** (conditional) → **Builder** → **Reviewer**
 
 After each agent completes, read their output:
 ```
 actions.get(taskId)   → read the latest completed action and its sections
 ```
 
+**Invoke the Consultant when ANY of these are true:**
+- `deps.check` returned `significant: true`
+- `.harness/deps-lock.json` did not exist before this session (first task)
+- The task description mentions `package.json`, dependencies, or config files
+
+**Skip the Consultant** for routine feature/bug tasks where deps are unchanged.
+
 ### 8. Handle a Reviewer block
 
 If the reviewer blocks the task:

package/dist/agent-templates/reviewer.md

@@ -125,6 +125,7 @@ Then notify lead so the builder can be re-assigned.
 - **Be specific when blocking.** The builder must know exactly what to fix.
 - **Do not fix issues yourself.** Your job is to verify, not to implement.
 - **Do not approve under time pressure.** If the work is not ready, block it.
+- **Verify the mandatory docs/README analysis criterion.** Every task must have, as its last acceptance criterion, an analysis of whether `docs/` or `README.md` need updating. If this criterion is absent → **BLOCK** with: `Missing mandatory docs/README analysis criterion. Lead must add it before builder proceeds.` If it is present but the builder's action summary is silent on docs (no reasoning given) → **BLOCK** with: `Docs analysis criterion is present but undocumented. Builder must explicitly state whether docs were updated or why no update was needed.`
 
 ## What counts as a block
 
@@ -135,6 +136,7 @@ Then notify lead so the builder can be re-assigned.
 - Files modified outside the builder's allowed paths
 - Security issues introduced by the changes
 - The implementation does not match the lead's plan
+- Mandatory docs/README analysis criterion absent from the task, or present but not addressed in the builder's action summary
 
 ## Anti-patterns to avoid
 

package/dist/cli.js

@@ -131,12 +131,27 @@ var MCP_CLAUDE_PERMISSIONS_REVIEWER = [
   "mcp__agent-harness-kit__tasks_acceptance_get",
   "mcp__agent-harness-kit__docs_search"
 ];
+var MCP_CLAUDE_PERMISSIONS_CONSULTANT = [
+  "mcp__agent-harness-kit__actions_start",
+  "mcp__agent-harness-kit__actions_write",
+  "mcp__agent-harness-kit__actions_complete",
+  "mcp__agent-harness-kit__actions_get",
+  "mcp__agent-harness-kit__actions_record_file",
+  "mcp__agent-harness-kit__actions_record_tool",
+  "mcp__agent-harness-kit__tasks_get",
+  "mcp__agent-harness-kit__tasks_claim",
+  "mcp__agent-harness-kit__tasks_acceptance_get",
+  "mcp__agent-harness-kit__deps_snapshot",
+  "mcp__agent-harness-kit__deps_check",
+  "mcp__agent-harness-kit__docs_search"
+];
 var MCP_CLAUDE_PERMISSIONS = [
   .../* @__PURE__ */ new Set([
     ...MCP_CLAUDE_PERMISSIONS_LEAD,
     ...MCP_CLAUDE_PERMISSIONS_EXPLORER,
     ...MCP_CLAUDE_PERMISSIONS_BUILDER,
-    ...MCP_CLAUDE_PERMISSIONS_REVIEWER
+    ...MCP_CLAUDE_PERMISSIONS_REVIEWER,
+    ...MCP_CLAUDE_PERMISSIONS_CONSULTANT
   ])
 ];
 function mergeClaudeSettingsLocalJson(filePath) {
@@ -491,6 +506,9 @@ function agentExplorer(vars) {
 function agentBuilder(vars) {
   return loadAgentTemplate("builder", vars);
 }
+function agentConsultant(vars) {
+  return loadAgentTemplate("consultant", vars);
+}
 function agentReviewer(vars) {
   return loadAgentTemplate("reviewer", vars);
 }
@@ -548,10 +566,11 @@ function agentReviewerToml(vars) {
 }
 function translateFrontmatterForClaudeCode(md, agentName) {
   const permissionsMap = {
-    lead: MCP_CLAUDE_PERMISSIONS_LEAD,
-    explorer: MCP_CLAUDE_PERMISSIONS_EXPLORER,
-    builder: MCP_CLAUDE_PERMISSIONS_BUILDER,
-    reviewer: MCP_CLAUDE_PERMISSIONS_REVIEWER
+    lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
+    explorer: [...MCP_CLAUDE_PERMISSIONS_EXPLORER],
+    consultant: [...MCP_CLAUDE_PERMISSIONS_CONSULTANT],
+    builder: [...MCP_CLAUDE_PERMISSIONS_BUILDER],
+    reviewer: [...MCP_CLAUDE_PERMISSIONS_REVIEWER]
   };
   const permissions = permissionsMap[agentName] ?? MCP_CLAUDE_PERMISSIONS;
   const mcpLines = permissions.map((t) => `  - ${t}`).join("\n");
@@ -590,10 +609,11 @@ function slugify(title) {
   return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
 }
 var AGENT_TOOLS = {
-  lead: MCP_CLAUDE_PERMISSIONS_LEAD,
-  explorer: MCP_CLAUDE_PERMISSIONS_EXPLORER,
-  builder: MCP_CLAUDE_PERMISSIONS_BUILDER,
-  reviewer: MCP_CLAUDE_PERMISSIONS_REVIEWER
+  lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
+  explorer: [...MCP_CLAUDE_PERMISSIONS_EXPLORER],
+  consultant: [...MCP_CLAUDE_PERMISSIONS_CONSULTANT],
+  builder: [...MCP_CLAUDE_PERMISSIONS_BUILDER],
+  reviewer: [...MCP_CLAUDE_PERMISSIONS_REVIEWER]
 };
 async function syncAgentPermissions(cwd2) {
   for (const [agent, tools] of Object.entries(AGENT_TOOLS)) {
@@ -645,6 +665,7 @@ No tasks in progress.
     const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
     writeAgentFile(cwd2, ".claude/agents/lead.md", translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead"));
     writeAgentFile(cwd2, ".claude/agents/explorer.md", translateFrontmatterForClaudeCode(agentExplorer({ projectName, allowedPaths }), "explorer"));
+    writeAgentFile(cwd2, ".claude/agents/consultant.md", translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant"));
     writeAgentFile(cwd2, ".claude/agents/builder.md", translateFrontmatterForClaudeCode(agentBuilder({ projectName, writablePaths }), "builder"));
     writeAgentFile(cwd2, ".claude/agents/reviewer.md", translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer"));
     mergeClaudeMcpJson(join4(cwd2, ".mcp.json"), config.tools.mcp.port);
@@ -665,6 +686,7 @@ No tasks in progress.
     const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
     writeAgentFile(cwd2, ".claude/agents/lead.md", translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead"));
     writeAgentFile(cwd2, ".claude/agents/explorer.md", translateFrontmatterForClaudeCode(agentExplorer({ projectName, allowedPaths }), "explorer"));
+    writeAgentFile(cwd2, ".claude/agents/consultant.md", translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant"));
     writeAgentFile(cwd2, ".claude/agents/builder.md", translateFrontmatterForClaudeCode(agentBuilder({ projectName, writablePaths }), "builder"));
     writeAgentFile(cwd2, ".claude/agents/reviewer.md", translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer"));
     mergeClaudeMcpJson(join4(cwd2, ".mcp.json"), config.tools.mcp.port);
@@ -2353,7 +2375,7 @@ async function runReset(cwd2, opts) {
 }
 
 // src/core/mcp-server.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync7, statSync } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync9, readdirSync as readdirSync2, readFileSync as readFileSync7, statSync, writeFileSync as writeFileSync10 } from "fs";
 import { join as join15, resolve as resolve10 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -2366,10 +2388,11 @@ import {
 import { existsSync as existsSync10, readFileSync as readFileSync6 } from "fs";
 import { join as join14 } from "path";
 var CANONICAL = {
-  lead: MCP_CLAUDE_PERMISSIONS_LEAD,
-  explorer: MCP_CLAUDE_PERMISSIONS_EXPLORER,
-  builder: MCP_CLAUDE_PERMISSIONS_BUILDER,
-  reviewer: MCP_CLAUDE_PERMISSIONS_REVIEWER
+  lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
+  explorer: [...MCP_CLAUDE_PERMISSIONS_EXPLORER],
+  consultant: [...MCP_CLAUDE_PERMISSIONS_CONSULTANT],
+  builder: [...MCP_CLAUDE_PERMISSIONS_BUILDER],
+  reviewer: [...MCP_CLAUDE_PERMISSIONS_REVIEWER]
 };
 function parseToolsFromFrontmatter(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---/m);
@@ -2382,7 +2405,7 @@ function parseToolsFromFrontmatter(content) {
 function checkPermissionsSync(cwd2) {
   const agents = {};
   let in_sync = true;
-  for (const agent of ["lead", "explorer", "builder", "reviewer"]) {
+  for (const agent of ["lead", "explorer", "consultant", "builder", "reviewer"]) {
     const filePath = join14(cwd2, ".claude", "agents", `${agent}.md`);
     if (!existsSync10(filePath)) {
       const missing2 = CANONICAL[agent];
@@ -2631,6 +2654,16 @@ var TOOLS = [
     name: "permissions.check",
     description: "Check whether the .claude/agents/*.md tool permission lists are in sync with the current canonical permission constants. Returns per-agent diff with missing and extra tools. Call this at session start to detect outdated agent files after an ahk upgrade.",
     inputSchema: { type: "object", properties: {}, required: [] }
+  },
+  {
+    name: "deps.snapshot",
+    description: "Snapshot current package.json dependencies to .harness/deps-lock.json",
+    inputSchema: { type: "object", properties: {}, required: [] }
+  },
+  {
+    name: "deps.check",
+    description: "Compare current package.json against .harness/deps-lock.json and report changes",
+    inputSchema: { type: "object", properties: {}, required: [] }
   }
 ];
 async function startMcpServer(config, cwd2) {
@@ -2777,6 +2810,58 @@ async function dispatch(name, args, db, docsPath, cwd2) {
       const result = checkPermissionsSync(cwd2);
       return ok(JSON.stringify(result, null, 2));
     }
+    case "deps.snapshot": {
+      const pkgPath2 = join15(cwd2, "package.json");
+      if (!existsSync11(pkgPath2)) {
+        return ok("package.json not found in project root", true);
+      }
+      const pkg2 = JSON.parse(readFileSync7(pkgPath2, "utf8"));
+      const snapshot = {
+        capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        dependencies: pkg2.dependencies ?? {},
+        devDependencies: pkg2.devDependencies ?? {}
+      };
+      const harnessDir = join15(cwd2, ".harness");
+      mkdirSync9(harnessDir, { recursive: true });
+      writeFileSync10(join15(harnessDir, "deps-lock.json"), JSON.stringify(snapshot, null, 2), "utf8");
+      return ok(JSON.stringify({ message: "Snapshot saved to .harness/deps-lock.json", capturedAt: snapshot.capturedAt }));
+    }
+    case "deps.check": {
+      const pkgPath2 = join15(cwd2, "package.json");
+      const lockPath = join15(cwd2, ".harness", "deps-lock.json");
+      if (!existsSync11(pkgPath2)) {
+        return ok("package.json not found in project root", true);
+      }
+      if (!existsSync11(lockPath)) {
+        return ok(JSON.stringify({ status: "no-snapshot", message: "No deps-lock.json found. Run deps.snapshot first to establish a baseline." }));
+      }
+      const pkg2 = JSON.parse(readFileSync7(pkgPath2, "utf8"));
+      const lock = JSON.parse(readFileSync7(lockPath, "utf8"));
+      const current = { ...pkg2.dependencies ?? {}, ...pkg2.devDependencies ?? {} };
+      const previous = { ...lock.dependencies ?? {}, ...lock.devDependencies ?? {} };
+      const added = [];
+      const removed = [];
+      const majorBumps = [];
+      for (const [name2, version] of Object.entries(current)) {
+        if (!(name2 in previous)) {
+          added.push(`${name2}@${version}`);
+        } else {
+          const prevMajor = parseInt(previous[name2].replace(/^[\^~>=v]/, "").split(".")[0] ?? "0", 10);
+          const curMajor = parseInt(version.replace(/^[\^~>=v]/, "").split(".")[0] ?? "0", 10);
+          if (!isNaN(prevMajor) && !isNaN(curMajor) && curMajor > prevMajor) {
+            majorBumps.push({ name: name2, from: previous[name2], to: version });
+          }
+        }
+      }
+      for (const depName of Object.keys(previous)) {
+        if (!(depName in current)) {
+          removed.push(depName);
+        }
+      }
+      const significant = added.length > 0 || removed.length > 0 || majorBumps.length > 0;
+      const advisory = significant ? "Significant dependency changes detected. Consider running `pnpx autoskills` (or `npx autoskills` if pnpm is unavailable) to refresh agent skills. Clearing stale skills before re-running is recommended." : "No significant dependency changes detected.";
+      return ok(JSON.stringify({ significant, added, removed, majorBumps, advisory, snapshotDate: lock.capturedAt }));
+    }
     default:
       return ok(`Unknown tool: ${name}`, true);
   }
@@ -2934,7 +3019,7 @@ async function runStatus(cwd2, opts) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync11, readFileSync as readFileSync8 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync8 } from "fs";
 import { join as join16, resolve as resolve11 } from "path";
 import pc10 from "picocolors";
 async function runSync(cwd2, opts) {
@@ -2954,7 +3039,7 @@ async function runSync(cwd2, opts) {
   }
 }
 async function syncIn(featureListPath, db, dryRun) {
-  if (!existsSync11(featureListPath)) {
+  if (!existsSync12(featureListPath)) {
     console.log(pc10.dim(`feature_list.json not found at ${featureListPath} \u2014 skipping in-sync`));
     return;
   }
@@ -3045,14 +3130,14 @@ async function runTaskAdd(cwd2) {
 
 // src/commands/task/done.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync13 } from "fs";
 import { resolve as resolve12 } from "path";
 import pc12 from "picocolors";
 async function runTaskDone(cwd2, idOrSlug) {
   const config = await loadConfig(cwd2);
   if (config.health.required) {
     const scriptPath = resolve12(cwd2, config.health.scriptPath);
-    if (existsSync12(scriptPath)) {
+    if (existsSync13(scriptPath)) {
       const result = spawnSync2("bash", [scriptPath], { cwd: cwd2, stdio: "pipe", encoding: "utf8" });
       if (result.status !== 0) {
         console.error(pc12.red("\u2717 Health check failed \u2014 cannot mark task as done."));