@thehammer/danx-dashboard-mcp 0.1.37 → 0.1.39

package/README.md

@@ -17,7 +17,7 @@ BOARD-ONLY (DX-1171): board is the first-level concept; repo is DERIVED from boa
 
 ## Tool surface
 
-All exposed as `mcp__danx_dashboard__<name>` once wired through the workspace `mcp.template.json`.
+All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `mcp.template.json`.
 
 | Tool | HTTP | Notes |
 |---|---|---|

package/dist/handlers.js

@@ -156,6 +156,9 @@ export async function issueEdit(client, args) {
     });
 }
 export async function issueTransition(client, args) {
+    if (args.action === "pickup" && args.manual && !args.assigned_agent) {
+        throw new Error("issue_transition({action:'pickup', manual:true}) requires assigned_agent — DX-2282: pass the resolved agent/profile name claiming this card.");
+    }
     const { id, board, ...body } = args;
     return client.request({
         method: "POST",
@@ -410,6 +413,53 @@ export async function issueQualityGate(client, args) {
         board: args.board,
     });
 }
+/**
+ * Stamp an operator MANUAL quality-gate verdict via
+ * PATCH /api/issues/:id/quality-gates/:gate {status, message} — the same write
+ * the dashboard Gates-tab Pass / Fail / Revert controls perform (DX-1373).
+ *
+ * SIBLING, NOT A REPLACEMENT, of `issueQualityGate` above: they are two
+ * distinct operations on one resource, mirroring the server's own verb split.
+ * POST flips the per-card `required` FLAG (does this gate run at all); PATCH
+ * stamps the VERDICT (did it pass). Neither substitutes for the other, which
+ * is why this is a separate tool rather than an overloaded mode on the
+ * existing one (CLAUDE.md Core Principle 2 — no dual-shape).
+ *
+ * DX-2222 — why this tool has to exist. A card cannot reach Done while any
+ * required POST gate row is not `pass` (`issue_transition complete` refuses
+ * 409 with `failed_gate: "quality_gate_post"`). Until now the ONLY way to
+ * write a verdict was the worker route `src/worker/quality-gate-route.ts`,
+ * authed by the per-dispatch `DANX_AGENT_TOKEN` that exists only INSIDE a
+ * spawned dispatch. An operator/host session (`issue_transition pickup
+ * {manual:true}`, DX-946) has no such token, so it could pick a card up and
+ * do the work but never close it — every manually-claimed card stranded In
+ * Progress, and each stranded card then projects `conflict_on` / `waiting_on`
+ * gates onto the ToDo queue, stalling dispatch for cards nobody is working.
+ *
+ * This route is the RIGHT one to expose for that: its handler
+ * (`src/issues/write/quality-gate-verdict.ts`) is a pure, dispatch-less row
+ * write authed by the ordinary per-user dashboard bearer — explicitly "NOT
+ * the dispatch token — there is no dispatch behind a manual stamp". It does
+ * NOT fire the worker route's per-dispatch side effects (`gate_release` on
+ * pass, `block` on fail), so a manual verdict can never release or block a
+ * dispatch that does not exist.
+ *
+ * Fail-loud (CP1), all server-side: unknown `gate` → 400; `status` outside
+ * pass/fail/pending → 400; a pass/fail whose `message` is under 20 characters
+ * → 400, because the note IS the accountability record for a human override.
+ * `pending` reverts a prior verdict and clears the message.
+ */
+export async function issueQualityGateVerdict(client, args) {
+    const body = { status: args.status };
+    if (args.message !== undefined)
+        body.message = args.message;
+    return client.request({
+        method: "PATCH",
+        path: `/${encodeURIComponent(args.id)}/quality-gates/${encodeURIComponent(args.gate)}`,
+        body,
+        board: args.board,
+    });
+}
 export async function issueRetro(client, args) {
     const { id, board, ...body } = args;
     return client.request({

package/dist/index.js

@@ -8,7 +8,7 @@
  * tool here POSTs/GETs against the dashboard, which atomically applies
  * the change via the transactional layer and publishes SSE.
  *
- * Tool surface (all exposed as `mcp__danx_dashboard__<name>` once wired
+ * Tool surface (all exposed as `mcp__danx-dashboard__<name>` once wired
  * through the workspace `mcp.template.json`):
  *
  *   - issue_list             GET    /api/issues
@@ -22,6 +22,8 @@
  *   - issue_dependency       POST/DELETE /api/issues/:id/dependencies[/:did]
  *   - issue_requires_human   POST/DELETE /api/issues/:id/requires-human
  *   - issue_quality_gate     POST   /api/issues/:id/quality-gates/:gate
+ *   - issue_quality_gate_verdict
+ *                            PATCH  /api/issues/:id/quality-gates/:gate
  *   - issue_retro            PUT    /api/issues/:id/retro
  *   - issue_attach           POST   /api/issues/:id/attachments (reads a local file)
  *   - repo_knowledge_get     GET    /api/repo-knowledge
@@ -55,7 +57,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
-import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueRequiresHuman, issueRetro, issueTransition, issueTriage, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueTransition, issueTriage, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -305,13 +307,18 @@ server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues
     ...boardField,
 }, async (args) => jsonResult(await issueEdit(client, args)));
 // ---------------- issue_transition ----------------
-server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issues/:id/transition. **THIS IS THE ONLY WAY TO MOVE A CARD'S LIFECYCLE STATE** — DX-835 separated card lifecycle (this tool) from dispatch finalization (`mcp__danxbot__danxbot_complete`). The worker no longer infers card moves from `danxbot_complete.status`; agents that want the card to move MUST call this tool BEFORE calling `danxbot_complete`. Actions: ready (Review→ToDo), pickup (ToDo→In Progress — server checks every dispatch gate: ready_at, blocked_at, requires_human_reason, depends_on partners terminal, conflict_on partners idle; refuses 409 with failed_gate naming the cause; pass manual:true for OPERATOR-SESSION self-pickup — stamps dispatch_kind 'manual', bypasses every card-flow gate except terminal/deleted/already-dispatched, and the worker NEVER auto-transitions the card: no orphan-heal rollback, no Epic auto-rollup — use this whenever the work happens in YOUR current session rather than a worker dispatch, DX-946), rollback_pickup, **complete** (stamps completed_at — moves card to Done; this is YOUR explicit decision, not a side effect of danxbot_complete; REFUSES 409 on Epic if any phase child non-terminal — see non_terminal_phases[]; ALSO refuses 409 with failed_gate 'quality_gate_post' + failed_post_gates[] while any required POST quality gate row != pass — DX-1177), cancel (stamps cancelled_at — terminal), **block** (requires non-empty reason — stamps blocked_at + blocked_reason + clears dispatch; USE THIS when the CARD itself cannot proceed without human intervention; distinct from env-fault dispatch failures which use `danxbot_complete({status:'failed'})`), unblock, archive (parks to Backlog, clears ready_at), reopen (terminal→active, clears completed_at/cancelled_at/archived_at). Terminal cards refuse every action except reopen. Ladder timestamps preserved — forward stamps never clear earlier ones (CLAUDE.md Core Principle 2).", {
+server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issues/:id/transition. **THIS IS THE ONLY WAY TO MOVE A CARD'S LIFECYCLE STATE** — DX-835 separated card lifecycle (this tool) from dispatch finalization (`mcp__danxbot__danxbot_complete`). The worker no longer infers card moves from `danxbot_complete.status`; agents that want the card to move MUST call this tool BEFORE calling `danxbot_complete`. Actions: ready (Review→ToDo), pickup (ToDo→In Progress — server checks every dispatch gate: ready_at, blocked_at, requires_human_reason, depends_on partners terminal, conflict_on partners idle; refuses 409 with failed_gate naming the cause; pass manual:true for OPERATOR-SESSION self-pickup — stamps dispatch_kind 'manual', bypasses every card-flow gate except terminal/deleted/already-dispatched, and the worker NEVER auto-transitions the card: no orphan-heal rollback, no Epic auto-rollup — use this whenever the work happens in YOUR current session rather than a worker dispatch, DX-946), rollback_pickup, **complete** (stamps completed_at — moves card to Done; this is YOUR explicit decision, not a side effect of danxbot_complete; REFUSES 409 on Epic if any phase child non-terminal — see non_terminal_phases[]; ALSO refuses 409 with failed_gate 'quality_gate_post' + failed_post_gates[] while any required POST quality gate row != pass — DX-1177), cancel (stamps cancelled_at — terminal), **block** (requires non-empty reason — stamps blocked_at + blocked_reason + clears dispatch; USE THIS when the CARD itself cannot proceed without human intervention; distinct from env-fault dispatch failures which use `danxbot_complete({status:'failed'})`), unblock, archive (parks to Backlog, clears ready_at), reopen (terminal→active, clears completed_at/cancelled_at/archived_at). Terminal cards refuse every action except reopen. Ladder timestamps preserved — forward stamps never clear earlier ones (CLAUDE.md Core Principle 2). **DX-2282 — `assigned_agent` is REQUIRED on every `manual:true` pickup call from a dispatched agent**: the server resolves your MCP-tool bearer to the single synthetic identity shared by EVERY dispatch, which cannot stand in as 'who claimed this' — pass the resolved agent/profile name explicitly (never omit it, never pass the generic dispatch identity itself) or the call is refused 409.", {
     id: z.string().min(1),
     action: z.enum(TRANSITION_ACTIONS),
     reason: z.string().optional(),
     summary: z.string().optional(),
     dispatch_id: z.string().min(1).optional(),
     manual: z.boolean().optional(),
+    assigned_agent: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("DX-2282 — REQUIRED when manual:true (operator/dispatched-agent self-pickup): the resolved agent/profile name claiming this card. Must be an explicit, distinguishing identity — never omitted, never the generic shared dispatch-token identity — or the pickup is refused 409."),
     ...boardField,
 }, async (args) => jsonResult(await issueTransition(client, args)));
 // ---------------- issue_triage ----------------
@@ -388,6 +395,21 @@ server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate
     effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGate(client, args)));
+// ---------------- issue_quality_gate_verdict ----------------
+server.tool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate VERDICT via PATCH /api/issues/:id/quality-gates/:gate {status, message} — the same write the dashboard Gates-tab Pass / Fail / Revert controls perform (DX-1373). SIBLING of `issue_quality_gate`, not a replacement: that one flips the per-card `required` FLAG (does this gate run at all), THIS one records the VERDICT (did it pass) — the server exposes them as POST vs PATCH on the same resource and neither substitutes for the other. **Use this to close out a card you picked up with `issue_transition pickup {manual:true}`** (DX-946 operator-session self-pickup): `issue_transition complete` REFUSES 409 (`failed_gate: \"quality_gate_post\"`, `failed_post_gates[]`) while any required POST gate (`code-quality` / `code-test-quality` / `code-architecture`) is not `pass`, so without a verdict a manually-claimed card can never reach Done — it strands In Progress and its `conflict_on` / `waiting_on` edges then stall OTHER cards' dispatch. `status`: `pass` | `fail` | `pending` (revert a prior verdict, clears the message). `message` is the accountability record for the override and is REQUIRED at >= 20 characters for `pass`/`fail` (shorter → 400); it is ignored for `pending`. Record the REAL reviewer finding here, not a rubber stamp — this is a human-attributed override, stamped with the operator actor, and it is what a later reader sees instead of a reviewer dispatch. A manual verdict is a PURE row write: unlike the worker's in-dispatch gate route it fires NO side effects — a manual `fail` never blocks the card and a manual `pass` never releases a dispatch. Unknown gate → 400; status outside the three values → 400; unknown card → 404. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
+    id: z.string().min(1),
+    gate: z.enum([
+        "plan-dependency",
+        "plan-architecture",
+        "plan-tdd",
+        "code-test-quality",
+        "code-architecture",
+        "code-quality",
+    ]),
+    status: z.enum(["pass", "fail", "pending"]),
+    message: z.string().optional(),
+    ...boardField,
+}, async (args) => jsonResult(await issueQualityGateVerdict(client, args)));
 // ---------------- issue_retro ----------------
 server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retro. Body: {good, bad, action_item_ids[], commits[], tests[]}. REFUSES 409 unless the card is terminal (completed_at OR cancelled_at) — retro ships when work concludes. Replace semantics: good/bad upsert; action_item_ids[] + commits[] + tests[] soft-delete prior live rows and insert with fresh ordinals. action_item_ids[] entries MUST match <PREFIX>-N. commits[] entries take {sha, subject?}. tests[] (DX-1646) is REQUIRED (empty array allowed — the \"ran no tests\" case): one row per test GROUP that ran (a whole suite/class — name the group, do NOT list individual unit tests) or per individual e2e test (kind:'e2e', listed explicitly since they are few + expensive). Each row: {name, kind:'group'|'e2e', num_tests, num_passing_tests, duration_ms} required; num_assertions + num_passing_assertions NULLABLE (vitest surfaces no assertion totals — pass null or omit).", {
     id: z.string().min(1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "Stdio MCP server wrapping danxbot's dashboard /api/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
   "license": "MIT",
   "type": "module",