@thehammer/danx-dashboard-mcp 0.1.95 → 0.1.97

package/dist/bridge.js

@@ -568,14 +568,23 @@ function classifyAdmissionRefusal(refusal) {
     }
     return null;
 }
-const EXIT_NEVER_RESTART = new Set([
+// DX-3028 (code-review + architecture-review finding) — typed against
+// `ListenStopReason` (the closed union `scope_narrowed` aside — see that
+// type's own docblock), NOT bare `Set<string>`: a typo'd member here used to
+// have zero compile-time signal, silently falling into the generic
+// `degrade-server-fixable` default below — exactly the kind of drift this
+// safety-critical classification can least afford. `satisfies readonly
+// ListenStopReason[]` on each array is what makes a typo a build error.
+const EXIT_NEVER_RESTART_LIST = [
     "no_connection_record",
     "not_connected",
     "superseded",
     "replaced",
     "session_is_worker",
-]);
-const DEGRADE_NO_HEARTBEAT = new Set(["credential_unavailable", "credential_mismatch"]);
+];
+const EXIT_NEVER_RESTART = new Set(EXIT_NEVER_RESTART_LIST);
+const DEGRADE_NO_HEARTBEAT_LIST = ["credential_unavailable", "credential_mismatch"];
+const DEGRADE_NO_HEARTBEAT = new Set(DEGRADE_NO_HEARTBEAT_LIST);
 export function degradePolicyFor(reason) {
     if (EXIT_NEVER_RESTART.has(reason))
         return "exit";
@@ -796,6 +805,14 @@ export async function runBridge(options, deps) {
         if (!readyEmitted) {
             readyEmitted = true;
             const inventory = await fetchPlanInventory(options, deps);
+            // DX-3028 (AC1, code-review + architecture-review finding) — this is
+            // the ONE place `lastInventoryOk` is ever written; the 15s heartbeat
+            // reads it on every "streaming" tick (see `heartbeatTick` above). Must
+            // agree with the SAME `ready` record's own `degraded` decision below —
+            // a heartbeat reporting `inventory:"ok"` while the `ready` record just
+            // told the operator `degraded:true` would be exactly the untruthful
+            // state AC1 exists to prevent.
+            lastInventoryOk = inventory.kind === "ok";
             if (inventory.kind === "ok") {
                 deps.write({
                     type: "ready",
@@ -919,6 +936,18 @@ export async function runBridge(options, deps) {
         }
     }
 }
+/**
+ * DX-3028 — the ONE real `scheduleInterval` implementation, shared by
+ * `runBridge`'s deps AND `runBridgeCommand`'s own start-time
+ * `degrade-no-heartbeat` keep-alive (see the comment at that call site for
+ * why the latter needs one too). A single real `setInterval`/`clearInterval`
+ * pair, so the two call sites can never drift into two different ideas of
+ * what "the real process's interval" means.
+ */
+function realScheduleInterval(tick, ms) {
+    const timer = setInterval(tick, ms);
+    return { stop: () => clearInterval(timer) };
+}
 /** The bin's `bridge` subcommand, wired to the real process. */
 export async function runBridgeCommand(argv, env = process.env, 
 /** Test seam: the home the session's connection record is read from. */
@@ -950,14 +979,28 @@ resolveFrom = {}) {
         process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
         if (!degraded)
             return 1;
-        // DX-3028 (AC2) — `credential_unavailable` / `credential_mismatch`:
-        // this process has no credential it can authenticate a heartbeat with
-        // (see `settle`'s identical `degrade-no-heartbeat` branch), so it sends
-        // none and idles until the plugin kills and restarts it fresh on a
-        // watched-path change. `return`ed directly (never `await`ed then fallen
-        // through) so TypeScript's definite-assignment check for `options` below
-        // sees this branch as never reaching that line, which is also true at
-        // runtime — this promise never settles.
+        // DX-3028 (AC2, architecture-review finding) — `credential_unavailable` /
+        // `credential_mismatch`: this process has no credential it can
+        // authenticate a heartbeat with (see `settle`'s identical
+        // `degrade-no-heartbeat` branch), so it sends none — but it MUST still
+        // genuinely idle until the plugin kills and restarts it fresh on a
+        // watched-path change, exactly like the runtime `settle()` path does.
+        // The runtime path stays alive because ITS heartbeat `setInterval` (in
+        // `runBridge`, started before its mint loop) is already registered with
+        // libuv by the time it degrades; THIS path is reached before `runBridge`
+        // (and its interval) ever exists, so a bare `return new Promise(() => {})`
+        // here registers no handle at all — Node has nothing left pending once
+        // the call stack unwinds and the process exits almost immediately,
+        // defeating the "idles forever" contract `BridgeOptions.watchedPaths`
+        // exists to serve (DX-2953's watchdog only ever gets a chance to act on
+        // a process that is actually still running). `realScheduleInterval()`
+        // gives it the same kind of keep-alive handle the runtime path gets for
+        // free, ticking a no-op (there is nothing truthful to heartbeat here).
+        realScheduleInterval(() => { }, HEARTBEAT_INTERVAL_MS);
+        // `return`ed directly (never `await`ed then fallen through) so
+        // TypeScript's definite-assignment check for `options` below sees this
+        // branch as never reaching that line, which is also true at runtime —
+        // this promise never settles.
         return new Promise(() => {
             /* deliberately never settles */
         });
@@ -969,9 +1012,6 @@ resolveFrom = {}) {
         now: Date.now,
         readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
         requestTimeoutMs: REQUEST_TIMEOUT_MS,
-        scheduleInterval: (tick, ms) => {
-            const timer = setInterval(tick, ms);
-            return { stop: () => clearInterval(timer) };
-        },
+        scheduleInterval: realScheduleInterval,
     });
 }

package/dist/handlers.js

@@ -215,6 +215,12 @@ export async function issueCreate(client, args, defaultBoard) {
         type: args.type,
         title: args.title,
         description: args.description,
+        // DX-3006 — forwarded UNCONDITIONALLY, alongside the other required
+        // fields, never behind an `if (… !== undefined)` like the optional ones
+        // below. Zod has already refused a call that omitted it, so there is
+        // nothing to coalesce here: whatever the caller decided, including an
+        // explicit null, is what the route receives.
+        plan: args.plan,
     };
     if (args.summary !== undefined)
         body.summary = args.summary;
@@ -226,8 +232,8 @@ export async function issueCreate(client, args, defaultBoard) {
         body.effort_level = args.effort_level;
     if (args.list_id !== undefined)
         body.list_id = args.list_id;
-    if (args.gate_decisions !== undefined)
-        body.gate_decisions = args.gate_decisions;
+    if (args.quality_gates !== undefined)
+        body.quality_gates = args.quality_gates;
     // DX-1895 (explicit-only) — forward the caller's explicit auto-triage
     // decision; the server stamps false when absent (never auto-triaged).
     // Per-child flags ride along inside phase_children entries verbatim.
@@ -677,42 +683,41 @@ export async function issueSolution(client, args) {
     }
 }
 /**
- * Flip a single card's per-card quality-gate `required` flag via
- * POST /api/issues/:id/quality-gates/:gate {required} — the same write the
+ * Put ONE quality gate on a card, or take it off, via
+ * POST /api/issues/:id/quality-gates/:gate {action} — the same write the
  * dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY
- * post-create path to mark a gate required/not — `issue_create` carries
- * `gate_decisions` at birth, and `issue_edit` rejects gate keys; without
- * this tool an agent that created a card cannot turn a gate on afterward.
+ * post-create path to change a card's gates: `issue_create` names them at
+ * birth via `quality_gates`, and `issue_edit` rejects gate keys.
  *
  * `gate` is a registry name (`plan-dependency` | `plan-architecture` |
  * `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality`).
- * An unknown gate is a 400 from the server (never a silent no-op).
+ * An unknown gate is a 400 from the server (never a silent no-op), as is a
+ * card whose type is never gated (`Epic` / `Feature` / `Task`).
  *
- * Board requirement is TRI-STATE per gate, NOT a binary on/off
- * (`board_quality_gate_settings.default_state`): `required` = always runs
- * (this per-card flag is irrelevant); `optional` = ENABLED, runs WHEN this
- * per-card flag is true (per-card opt-in — `optional` is NOT "off");
- * `disabled` = never runs (this flag is inert). So flipping `required:true`
- * here launches the gate when the board state is `required` OR `optional`;
- * it is inert ONLY when the board state is `disabled`. Source of truth:
- * `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.
+ * DX-3015 — there is no board tri-state to reason about any more. A gate is on
+ * the card or it is not, and every gate on a card is required, so `add` always
+ * means "this gate now runs on this card" and `remove` always means it does
+ * not. What the board still owns is the DEFAULT SET a NEW card is born with;
+ * it has no say over a card that already exists.
  *
- * `effort_level` (DX-1760) is an independent sibling write: present (incl.
- * `null`) sets `card_quality_gates.effort_level`; omitted leaves it untouched.
+ * Because of that, the response is plain `{issue}`. The old body carried
+ * `{applied, effective, reason}` because the per-card flag was only one of
+ * three inputs and the board could silently make the write a no-op — with the
+ * tri-state gone, the write IS the outcome and those fields would be constants.
  *
- * **Effectiveness echo.** The server response body is `{issue, applied: true,
- * effective, reason}`, not just `{issue}` — `client.request()` passes it
- * through VERBATIM (see `http-client.ts`'s header doc: "the envelope
- * passthrough is load-bearing"), so no transform is needed here for the
- * calling agent to see `effective` (what `isGateEffectivelyRequired` resolves
- * to right after this write, per the tri-state rule above) and `reason`
- * (`null` when it matches the `required` value just sent, otherwise which
- * board state overrode it). This closes the gap where a 200 alone could not
- * tell a fully-honored write from one the board's `required`/`disabled`
- * state made a complete no-op.
+ * `note` records why the gate is on the card; `effort_level` (DX-1760) sets
+ * `card_quality_gates.effort_level` (`null` clears a prior override). Both are
+ * `add`-only — the server 400s either one alongside `remove`, since a removed
+ * gate has no row to carry them.
+ *
+ * Re-adding a gate the card already carries updates `note`/`effort_level` and
+ * leaves any recorded verdict untouched, so `add` is never a way to quietly
+ * clear a `fail`. `remove` DOES discard the row and its verdict.
  */
 export async function issueQualityGate(client, args) {
-    const body = { required: args.required };
+    const body = { action: args.action };
+    if (args.note !== undefined)
+        body.note = args.note;
     if (args.effort_level !== undefined)
         body.effort_level = args.effort_level;
     return client.request({

package/dist/index.js

@@ -362,24 +362,32 @@ server.tool("issue_get",
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
-server.tool("issue_create", 'Create a card via POST /api/issues. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `gate_decisions` is REQUIRED when the board has an OPTIONAL quality gate for the card\'s type: a missing one fails closed with 400 `{error, required_gate_decisions:[...]}` naming each gate — retry with one `{gate, enabled, note}` per listed gate. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child: true only when it should enter automatic triage/dispatch without human review; absent → false.', {
+server.tool("issue_create", '`plan` is REQUIRED on every create (DX-3006): pass "mine" to put the card on THIS session\'s connected plan, or null when it deliberately belongs to no plan. There is no default and no inference — a card that names no plan is one nobody following the work can see, which is why the answer has to be given rather than omitted. "mine" while this session is on no plan is refused (409 session_not_connected) and creates NO card; a plan id is not accepted (a card is only ever created onto your own connected plan). This replaces the plan_add_card follow-up at creation time; plan_add_card remains for putting an EXISTING card on a plan. ' +
+    'Create a card via POST /api/issues. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `quality_gates` names the gates this card carries BEYOND the board\'s default set for its type — one `{gate, note?}` each. Omit it for just the board defaults; a gate you do not name simply is not on the card (there is no optional gate and nothing fails closed for going unnamed). Add one later with `issue_quality_gate`. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child: true only when it should enter automatic triage/dispatch without human review; absent → false.', {
     type: z.enum(ISSUE_TYPES),
     title: z.string().min(1).describe(TITLE_DESCRIBE),
     summary: z.string().min(1).optional().describe(SUMMARY_DESCRIBE),
     description: z.string().describe(DESCRIPTION_DESCRIBE),
+    // DX-3006 — REQUIRED and nullable, deliberately. `.nullable()` WITHOUT
+    // `.optional()` is the whole point: the caller must supply the key, and
+    // `null` is a legitimate answer it has to give on purpose. Adding
+    // `.optional()` here silently restores the hole this field closes.
+    plan: z
+        .literal("mine")
+        .nullable()
+        .describe('"mine" = attach to the plan THIS session is connected to; null = deliberately no plan. REQUIRED — decide per card. A plan id is not accepted: a card is only ever created onto your own connected plan, so there is no id to name.'),
     parent_id: z.string().nullable().optional(),
     ac: z.array(z.object({ title: z.string().min(1) })).optional(),
     effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     list_id: z.string().min(1).nullable().optional(),
-    gate_decisions: z
+    quality_gates: z
         .array(z.object({
         gate: z.string().min(1),
-        enabled: z.boolean(),
-        note: z.string(),
+        note: z.string().optional(),
         effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     }))
         .optional()
-        .describe("One {gate, enabled, note} per board-OPTIONAL gate of the card's type: `enabled` = does it run on this card, `note` = why. Board `required` gates always run and `disabled` never do; neither takes a decision (naming one → 400). Optional `effort_level` overrides a `plan-*` gate's reviewer rung."),
+        .describe("The gates this card carries BEYOND the board's default set for its type — one {gate, note?} each, `note` = why it applies here. Every gate on a card is required; a gate you do not name is not on the card at all (not displayed, not counted, never run), and omitting this field entirely is normal. Optional `effort_level` overrides a `plan-*` gate's reviewer rung."),
     phase_children: z
         .array(z.object({
         type: z.enum(NON_EPIC_TYPES),
@@ -392,15 +400,14 @@ server.tool("issue_create", 'Create a card via POST /api/issues. Board-scoped; s
         description: z.string().describe(DESCRIPTION_DESCRIBE),
         ac: z.array(z.object({ title: z.string().min(1) })).optional(),
         effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
-        gate_decisions: z
+        quality_gates: z
             .array(z.object({
             gate: z.string().min(1),
-            enabled: z.boolean(),
-            note: z.string(),
+            note: z.string().optional(),
             effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
         }))
             .optional()
-            .describe("Same as the root gate_decisions, resolved against THIS child's type."),
+            .describe("Same as the root quality_gates, resolved against THIS child's type."),
         triage_enabled: z
             .boolean()
             .optional()
@@ -593,7 +600,7 @@ server.tool("issue_retire_branch", "Mark a card's own `card/<id>` branch RETIRED
     ...boardField,
 }, async (args) => jsonResult(await issueRetireBranch(client, args)));
 // ---------------- issue_quality_gate ----------------
-server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the only post-create way (issue_create takes gate_decisions; issue_edit refuses gate keys). PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate → 400. The board state per gate is tri-state: `required` always runs, `optional` runs WHEN this flag is true (optional is NOT off), `disabled` never runs. Optional `effort_level` overrides a `plan-*` gate's reviewer rung (null clears it). The write always succeeds and returns `{issue, applied: true, effective, reason}` — read `effective` (does the gate now run) and `reason` (why the board overrode your value), not just the 200. Board-scoped; see `board`.", {
+server.tool("issue_quality_gate", "Put one quality gate ON a card, or take it OFF, via POST /api/issues/:id/quality-gates/:gate {action} — the only post-create way (issue_create names gates in quality_gates; issue_edit refuses gate keys). A gate is on the card or it does not exist for it; every gate on a card is required, so `add` means it now runs and `remove` means it is gone (not displayed, not counted). Adding a gate at any time is fully supported — that is what this tool is for. PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate → 400; a never-gated card type (Epic/Feature/Task) → 400. `note` (why it applies) and `effort_level` (overrides a `plan-*` gate's reviewer rung; null clears it) are `add`-only — passing either with `remove` → 400. Re-adding a gate the card already has updates note/effort and KEEPS its verdict; `remove` discards the row and any verdict on it. Board-scoped; see `board`.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",
@@ -603,12 +610,18 @@ server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via P
         "code-architecture",
         "code-quality",
     ]),
-    required: z.boolean(),
+    action: z
+        .enum(["add", "remove"])
+        .describe("add = put this gate on the card; remove = take it off."),
+    note: z
+        .string()
+        .optional()
+        .describe("Why this gate applies to this card. `add` only."),
     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) — POST vs PATCH on the same resource, 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, REQUIRED at >= 20 characters for `pass`/`fail` (shorter → 400), ignored for `pending`. Record the REAL reviewer finding, not a rubber stamp — a human-attributed override, stamped with the operator actor, standing in for a reviewer dispatch. A manual verdict is a PURE row write: no side effects — a manual `fail` never blocks the card and a manual `pass` never releases a dispatch. Unknown gate → 400; bad status → 400; unknown card → 404. Board-scoped; see `board`.", {
+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 puts a gate ON or OFF the card (does this gate apply at all), THIS one records the VERDICT (did it pass) — POST vs PATCH on the same resource, 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, REQUIRED at >= 20 characters for `pass`/`fail` (shorter → 400), ignored for `pending`. Record the REAL reviewer finding, not a rubber stamp — a human-attributed override, stamped with the operator actor, standing in for a reviewer dispatch. A manual verdict is a PURE row write: no side effects — a manual `fail` never blocks the card and a manual `pass` never releases a dispatch. Unknown gate → 400; bad status → 400; unknown card → 404. Board-scoped; see `board`.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.95",
+  "version": "0.1.97",
   "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",