@cardor/agent-harness-kit 1.5.2 → 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/agent-templates/reviewer.md

@@ -119,6 +119,7 @@ Then notify lead so the builder can be re-assigned.
 
 - **Run health.sh before approving.** No exceptions.
 - **Check every acceptance criterion.** Not just the obvious ones.
+- **Use `tasks.acceptance.get(taskId)` to retrieve criterion ids.** Call this before `tasks.acceptance.update()` when you do not already have criterion ids from `tasks.get`.
 - **Call `tasks.acceptance.update()` for each criterion.** Never skip this step.
 - **Never self-approve partial work.** All criteria must be met, not most.
 - **Be specific when blocking.** The builder must know exactly what to fix.