@cardor/agent-harness-kit 1.6.0 → 1.6.2

package/README.md

@@ -172,6 +172,7 @@ Regenerates `AGENTS.md` and provider-specific files from your `agent-harness-kit
 ```bash
 ahk build
 ahk build --watch    # watch mode: rebuilds automatically on config changes
+ahk build --sync     # sync tools: frontmatter in .claude/agents/*.md to match current permission constants
 ```
 
 ---
@@ -186,6 +187,8 @@ ahk dashboard --port 8080      # custom port
 ahk dashboard --no-open        # start server without opening browser
 ```
 
+If the requested port (default `4242`) is already in use, `ahk dashboard` automatically tries up to 10 sequential ports (e.g. `4242 → 4243 → … → 4251`). The actual port opened is printed to the console. If all 10 ports are exhausted, the command exits with a clear error message showing which port range was attempted.
+
 The dashboard includes:
 
 | View            | What it shows                                                               |
@@ -409,6 +412,12 @@ your-project/
 
 ---
 
+## Tasks schema
+
+The `tasks` table includes an `updated_at` timestamp column, set on creation and automatically updated on every status change. On first run after upgrading from an older version, existing rows are backfilled with `COALESCE(completed_at, started_at, created_at)`. Tasks returned by `tasks.get` are ordered by status priority (pending → in_progress → blocked → done) then by `updated_at` descending.
+
+---
+
 ## What you can customize
 
 ### `agent-harness-kit.config.ts`
@@ -574,7 +583,7 @@ The harness exposes these tools via MCP. Agents use them instead of reading file
 | `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.get`                                                                                |
+| `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                                                                                                                 |
@@ -582,6 +591,7 @@ The harness exposes these tools via MCP. Agents use them instead of reading file
 | `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` |
 
 ---
 
@@ -594,6 +604,30 @@ The harness exposes these tools via MCP. Agents use them instead of reading file
 | **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` | ✅ | ✅ | ✅ | ✅ |
+
+**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`.
+
+`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.
+
 ---
 
 ## What to commit

package/dist/agent-templates/builder.md

@@ -99,13 +99,34 @@ The explorer identified how this codebase works. Use those patterns. Do not intr
 
 If tests fail, fix them before completing your action. Do not leave the codebase in a broken state.
 
-### 6. Sync README and docs after codebase changes
+### 6. Sync README and docs — MANDATORY
 
-If your changes affect public APIs, CLI commands, configuration, or any user-facing behavior, update the relevant sections of `README.md` and any files under `./docs/` to reflect the new state.
+Before completing your action, you **must** check whether any user-facing behavior changed and update docs accordingly. This step is not optional.
 
-- Do not leave docs describing behavior that no longer exists.
-- Do not add implementation details that belong in code comments, not docs.
-- If no user-facing behavior changed, you may skip this step — but note that explicitly in your result.
+**Step 1 — Search actively:**
+```bash
+grep -n "your-feature-keyword" README.md docs/**/*.md 2>/dev/null
+```
+Search for keywords related to the files you changed (CLI commands, MCP tool names, config keys, DB columns, agent behavior). Read any matching sections.
+
+**Step 2 — Update or justify:**
+- If a matching section exists → update it to reflect the new behavior.
+- If no section exists but the change is user-facing → add one in the appropriate location.
+- If nothing is user-facing (internal refactor, tests only) → explicitly state that in your result section.
+
+**What counts as user-facing:**
+- New or changed CLI commands or flags
+- New or changed MCP tools
+- Changes to DB schema visible to users
+- Changes to agent permissions or behavior
+- New config options
+
+**Step 3 — Report in your result section:**
+Always end your result with one of:
+- `Docs updated: README.md lines X–Y (description of what changed)`
+- `No docs update needed: this change is internal only ([specific reason])`
+
+Never leave this blank or skip it silently.
 
 ### 7. Record your result
 

package/dist/agent-templates/lead.md

@@ -87,6 +87,10 @@ bash health.sh
 
 If exit code ≠ 0 → **stop immediately**. Report the health failure and do not proceed.
 
+Then call `permissions.check` — if `in_sync: false`, inform the user before proceeding:
+> "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 check session state via MCP:
 
 ```
@@ -134,6 +138,7 @@ Think through:
 - What exactly should the builder implement?
 - 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`
 
 Record it:
 

package/dist/cli.js

@@ -589,6 +589,32 @@ function appendGitignore(cwd2) {
 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
+};
+async function syncAgentPermissions(cwd2) {
+  for (const [agent, tools] of Object.entries(AGENT_TOOLS)) {
+    const filePath = join3(cwd2, ".claude", "agents", `${agent}.md`);
+    if (!existsSync2(filePath)) {
+      console.log(`  ${agent}.md not found \u2014 skipping`);
+      continue;
+    }
+    const content = readFileSync3(filePath, "utf-8");
+    const toolsBlock = `tools:
+${tools.map((t) => `  - ${t}`).join("\n")}
+`;
+    const updated = content.replace(/tools:\n(?:  - [^\n]+\n)*/m, toolsBlock);
+    if (updated === content) {
+      console.log(`  ${agent}.md already in sync`);
+    } else {
+      writeFileSync3(filePath, updated, "utf-8");
+      console.log(`  ${agent}.md updated`);
+    }
+  }
+}
 
 // src/core/materializer/claude-code.ts
 var ClaudeCodeMaterializer = class {
@@ -789,6 +815,9 @@ function getMaterializer(provider) {
 // src/commands/build.ts
 async function runBuild(cwd2, opts) {
   await buildOnce(cwd2);
+  if (opts.sync) {
+    await syncAgentPermissions(cwd2);
+  }
   if (opts.watch) {
     p.log.info(`Watching agent-harness-kit.config.ts for changes...`);
     watch(cwd2, { recursive: false }, async (_, filename) => {
@@ -1642,7 +1671,7 @@ async function openDB(config, cwd2) {
     const { MySQLDriver } = await import("./mysql-THKQOXIS.js");
     driver = new MySQLDriver(dbConfig);
   } else {
-    const { SQLiteDriver } = await import("./sqlite-XBEJJ5T2.js");
+    const { SQLiteDriver } = await import("./sqlite-KWYK4IJW.js");
     if (dbConfig.type !== "sqlite") {
       throw new Error("Invalid database type");
     }
@@ -2324,14 +2353,56 @@ async function runReset(cwd2, opts) {
 }
 
 // src/core/mcp-server.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync6, statSync } from "fs";
-import { join as join14, resolve as resolve10 } from "path";
+import { readdirSync as readdirSync2, readFileSync as readFileSync7, statSync } 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";
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
+
+// src/core/permissions-check.ts
+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
+};
+function parseToolsFromFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/m);
+  if (!match) return [];
+  const fm = match[1];
+  const toolsMatch = fm.match(/^tools:\n((?:  - [^\n]+\n?)*)/m);
+  if (!toolsMatch) return [];
+  return toolsMatch[1].split("\n").map((l) => l.trim().replace(/^- /, "")).filter((l) => l.startsWith("mcp__"));
+}
+function checkPermissionsSync(cwd2) {
+  const agents = {};
+  let in_sync = true;
+  for (const agent of ["lead", "explorer", "builder", "reviewer"]) {
+    const filePath = join14(cwd2, ".claude", "agents", `${agent}.md`);
+    if (!existsSync10(filePath)) {
+      const missing2 = CANONICAL[agent];
+      agents[agent] = { ok: false, missing: missing2, extra: [] };
+      in_sync = false;
+      continue;
+    }
+    const content = readFileSync6(filePath, "utf-8");
+    const installed = parseToolsFromFrontmatter(content);
+    const canonical = CANONICAL[agent];
+    const missing = canonical.filter((t) => !installed.includes(t));
+    const extra = installed.filter((t) => !canonical.includes(t));
+    const ok2 = missing.length === 0 && extra.length === 0;
+    if (!ok2) in_sync = false;
+    agents[agent] = { ok: ok2, missing, extra };
+  }
+  return { in_sync, agents };
+}
+
+// src/core/mcp-server.ts
 var VERSION = "0.1.0";
 var TOOLS = [
   {
@@ -2555,6 +2626,11 @@ var TOOLS = [
       },
       required: ["id"]
     }
+  },
+  {
+    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: [] }
   }
 ];
 async function startMcpServer(config, cwd2) {
@@ -2569,7 +2645,7 @@ async function startMcpServer(config, cwd2) {
     const { name, arguments: args } = request.params;
     const a = args ?? {};
     try {
-      const result = await dispatch(name, a, db, docsPath);
+      const result = await dispatch(name, a, db, docsPath, cwd2);
       return result;
     } catch (err) {
       return ok(`Error: ${err instanceof Error ? err.message : String(err)}`, true);
@@ -2578,7 +2654,7 @@ async function startMcpServer(config, cwd2) {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
-async function dispatch(name, args, db, docsPath) {
+async function dispatch(name, args, db, docsPath, cwd2) {
   switch (name) {
     case "actions.start": {
       const taskId = num(args, "taskId");
@@ -2697,6 +2773,10 @@ async function dispatch(name, args, db, docsPath) {
       const task2 = await db.unarchiveTask(id);
       return ok(JSON.stringify(task2));
     }
+    case "permissions.check": {
+      const result = checkPermissionsSync(cwd2);
+      return ok(JSON.stringify(result, null, 2));
+    }
     default:
       return ok(`Unknown tool: ${name}`, true);
   }
@@ -2709,7 +2789,7 @@ function searchDocs(docsPath, query, maxResults = 10) {
     for (const file of files) {
       if (results.length >= maxResults) break;
       try {
-        const content = readFileSync6(file, "utf8");
+        const content = readFileSync7(file, "utf8");
         const lines = content.split("\n");
         for (let i = 0; i < lines.length; i++) {
           const lower = lines[i].toLowerCase();
@@ -2730,7 +2810,7 @@ function collectMarkdownFiles(dir) {
   const files = [];
   try {
     for (const entry of readdirSync2(dir)) {
-      const full = join14(dir, entry);
+      const full = join15(dir, entry);
       const stat = statSync(full);
       if (stat.isDirectory()) {
         files.push(...collectMarkdownFiles(full));
@@ -2764,6 +2844,18 @@ async function runServe(cwd2, opts) {
   }
   process.stderr.write(`[agent-harness-kit] MCP server starting (stdio)
 `);
+  const syncResult = checkPermissionsSync(cwd2);
+  if (!syncResult.in_sync) {
+    const affected = Object.entries(syncResult.agents).filter(([, r]) => !r.ok).map(([name, r]) => {
+      const parts = [];
+      if (r.missing.length) parts.push(`missing: ${r.missing.map((t) => t.replace("mcp__agent-harness-kit__", "")).join(", ")}`);
+      if (r.extra.length) parts.push(`extra: ${r.extra.map((t) => t.replace("mcp__agent-harness-kit__", "")).join(", ")}`);
+      return `${name} (${parts.join("; ")})`;
+    }).join("\n   ");
+    process.stderr.write(`[agent-harness-kit] Agent permissions out of sync. Run: ahk build --sync
+   ${affected}
+`);
+  }
   await startMcpServer(config, cwd2);
 }
 
@@ -2842,13 +2934,13 @@ async function runStatus(cwd2, opts) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync10, readFileSync as readFileSync7 } from "fs";
-import { join as join15, resolve as resolve11 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync8 } from "fs";
+import { join as join16, resolve as resolve11 } from "path";
 import pc10 from "picocolors";
 async function runSync(cwd2, opts) {
   const config = await loadConfig(cwd2);
   const direction = opts.direction ?? "both";
-  const featureListPath = resolve11(join15(cwd2, config.storage.dir, "feature_list.json"));
+  const featureListPath = resolve11(join16(cwd2, config.storage.dir, "feature_list.json"));
   const db = await openDB(config, cwd2);
   try {
     if (direction === "in" || direction === "both") {
@@ -2862,13 +2954,13 @@ async function runSync(cwd2, opts) {
   }
 }
 async function syncIn(featureListPath, db, dryRun) {
-  if (!existsSync10(featureListPath)) {
+  if (!existsSync11(featureListPath)) {
     console.log(pc10.dim(`feature_list.json not found at ${featureListPath} \u2014 skipping in-sync`));
     return;
   }
   let seeds;
   try {
-    seeds = JSON.parse(readFileSync7(featureListPath, "utf8"));
+    seeds = JSON.parse(readFileSync8(featureListPath, "utf8"));
   } catch (err) {
     console.error(pc10.red(`Failed to parse feature_list.json: ${err}`));
     process.exit(1);
@@ -2953,14 +3045,14 @@ async function runTaskAdd(cwd2) {
 
 // src/commands/task/done.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync12 } 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 (existsSync11(scriptPath)) {
+    if (existsSync12(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."));
@@ -3133,10 +3225,10 @@ async function runTaskList(cwd2, opts) {
 
 // src/core/package-data.ts
 import { createRequire } from "module";
-import { dirname as dirname5, join as join16 } from "path";
+import { dirname as dirname5, join as join17 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var require2 = createRequire(import.meta.url);
-var pkgPath = join16(dirname5(fileURLToPath3(import.meta.url)), "..", "package.json");
+var pkgPath = join17(dirname5(fileURLToPath3(import.meta.url)), "..", "package.json");
 var pkg = require2(pkgPath);
 
 // src/core/update-check.ts
@@ -3180,7 +3272,7 @@ program.name("ahk").description("agent-harness-kit \u2014 CLI scaffolding for mu
 program.command("init").description("Scaffold a harness interactively in the current directory").option("--name <name>", "Project name (skip prompt)").option("--provider <provider>", "AI provider: claude-code | opencode (skip prompt)").option("--docs <path>", "Docs folder path (skip prompt)").option("--tasks <adapter>", "Task adapter: local | jira | linear (skip prompt)").action(async (opts) => {
   await runInit(cwd, opts);
 });
-program.command("build").description("Regenerate AGENTS.md and provider files from agent-harness-kit.config.ts").option("--watch", "Rebuild on config changes").action(async (opts) => {
+program.command("build").description("Regenerate AGENTS.md and provider files from agent-harness-kit.config.ts").option("--watch", "Rebuild on config changes").option("--sync", "Sync tools: frontmatter in existing .claude/agents/*.md to match current permission constants").action(async (opts) => {
   await runBuild(cwd, opts);
 });
 program.command("health").description("Run health.sh and report result").action(async () => {