create-byan-agent 2.25.0 → 2.27.0

package/install/templates/_byan/mcp/byan-mcp-server/lib/leantime-fd-core.js

@@ -0,0 +1,205 @@
+// Pure decision core for the FD -> Leantime auto-sync hook.
+//
+// WHY a separate pure module: a Claude Code hook is an I/O shell (stdin payload,
+// network, disk) that is awkward to unit-test. The risky logic — which Leantime
+// calls a phase transition implies, and the idempotence that stops duplicates —
+// lives here with ZERO I/O, so every transition is testable as a data
+// transform. The shell (.claude/hooks/leantime-fd-sync.js) feeds this the parsed
+// fd-state + the sidecar map and executes the returned intents against
+// lib/leantime-sync.js.
+//
+// State-coupling: this module reads fd-state echoed by the MCP tool; it does not
+// read or write fd-state.json. The Leantime id mapping is the caller's sidecar.
+
+// The two FD MCP tools whose result carries the post-transition fd-state.
+export const FD_ADVANCE = 'byan_fd_advance';
+export const FD_UPDATE = 'byan_fd_update';
+
+// Recognize the FD tool regardless of the mcp__<server>__ prefix or snake/camel
+// casing; the endsWith fallback keeps it working if the server key is renamed.
+export function fdToolKind(toolName) {
+  if (typeof toolName !== 'string') return null;
+  if (toolName === FD_ADVANCE || toolName.endsWith(`__${FD_ADVANCE}`) || toolName.endsWith(FD_ADVANCE)) {
+    return 'advance';
+  }
+  if (toolName === FD_UPDATE || toolName.endsWith(`__${FD_UPDATE}`) || toolName.endsWith(FD_UPDATE)) {
+    return 'update';
+  }
+  return null;
+}
+
+// Parse the fd-state the MCP tool echoed. The byan_fd_* handlers return
+// JSON.stringify(state); an MCP tool_response wraps it as
+// { content: [{ type:'text', text:'<json>' }] }. Accept that envelope, a raw
+// JSON string, or an already-parsed object. Returns the state object, or null
+// when the shape is unrecognized (the shell then degrades to a file fallback).
+export function parseFdState(toolResponse) {
+  if (!toolResponse) return null;
+  let candidate = toolResponse;
+  if (candidate && typeof candidate === 'object' && Array.isArray(candidate.content)) {
+    const textPart = candidate.content.find((p) => p && typeof p.text === 'string');
+    if (textPart) candidate = textPart.text;
+  }
+  if (typeof candidate === 'string') {
+    try {
+      candidate = JSON.parse(candidate);
+    } catch {
+      return null;
+    }
+  }
+  if (candidate && typeof candidate === 'object' && typeof candidate.phase === 'string') {
+    return candidate;
+  }
+  return null;
+}
+
+// FD phase order. Used to gate task creation to DISPATCH-onward (a feature's
+// task carries its assigned specialist, set at DISPATCH) and to recognize
+// terminal phases.
+const PHASE_RANK = {
+  DISCOVERY: 0,
+  BRAINSTORM: 1,
+  PRUNE: 2,
+  DISPATCH: 3,
+  BUILD: 4,
+  REVIEW: 5,
+  VALIDATE: 6,
+  REFACTOR: 7,
+  DOC: 8,
+  COMPLETED: 9,
+  ABORTED: 9,
+};
+
+function lastReviewStatus(state) {
+  const arr = Array.isArray(state.review_findings) ? state.review_findings : [];
+  for (let i = arr.length - 1; i >= 0; i -= 1) {
+    if (arr[i] && typeof arr[i].status === 'string') return arr[i].status;
+  }
+  return null;
+}
+
+// The board column the mapped tasks should reflect for the current fd-state.
+// Board-wide (not per-feature): a BYAN FD builds its backlog together, and the
+// per-item backlog status is agent-maintained and can lag a phase. Mirrors the
+// SKILL section 2.5 fire points. Returns a column name or null (no move).
+export function columnForState(state) {
+  switch (state.phase) {
+    case 'ABORTED':
+      return null; // leave the board verbatim: the diagnostic of where it died
+    case 'COMPLETED':
+      return 'done';
+    case 'DOC':
+      return 'review'; // validated, awaiting the COMPLETED sweep to done
+    case 'BUILD':
+      return 'doing';
+    case 'REFACTOR':
+      return 'blocked';
+    case 'VALIDATE': {
+      const v = state.validate_verdict;
+      if (v && v.status === 'KO') return 'blocked';
+      if (v && v.status === 'OK') return 'review';
+      return 'doing';
+    }
+    case 'REVIEW': {
+      const last = lastReviewStatus(state);
+      if (last === 'needs-rework') return 'blocked';
+      if (last === 'ready-for-validate') return 'review';
+      return 'doing';
+    }
+    default:
+      // DISCOVERY, BRAINSTORM, PRUNE, DISPATCH
+      return 'todo';
+  }
+}
+
+// Decide the ordered Leantime intents for one hook fire. Reconcile-from-state:
+// each fire (re)ensures the project exists, ensures every backlog task exists
+// (DISPATCH onward), and drives all mapped tasks to the column the current
+// fd-state implies. Idempotence is the sidecar's job — project_ensure/task_create
+// are emitted only when the id is absent, so a dropped call last fire is retried
+// and a duplicate is not created.
+//
+//   args: { toolName, state, sidecar, assignUserConfigured }
+//   sidecar: { projectId?, tasks?: { <backlogId>: taskId } } for THIS fd_id
+//   returns: { skip?: reason, intents: [...] }
+//
+// Intent ops (the shell maps each to a leantime-sync call):
+//   { op:'project_ensure', name, slug, details }
+//   { op:'assign_user' }                              // only if configured (shell sequences it after project_ensure)
+//   { op:'task_create', backlogId, headline }
+//   { op:'task_move', backlogId, column }
+export function decideActions({ toolName, state, sidecar = {}, assignUserConfigured = false } = {}) {
+  const kind = fdToolKind(toolName);
+  if (!kind) return { skip: 'not-fd-tool', intents: [] };
+  if (!state || typeof state.phase !== 'string') return { skip: 'no-state', intents: [] };
+
+  const projectName =
+    (state.project_context && state.project_context.name) || state.feature_name || null;
+  if (!projectName) return { skip: 'no-project-name', intents: [] };
+
+  const intents = [];
+  const tasks = sidecar.tasks || {};
+
+  // 1. Ensure the project. Emitted only when the sidecar has no projectId yet.
+  if (!sidecar.projectId) {
+    intents.push({
+      op: 'project_ensure',
+      name: projectName,
+      slug: (state.project_context && state.project_context.slug) || undefined,
+      details: `BYAN FD ${state.fd_id || ''} — auto-synced board.`.trim(),
+    });
+    if (assignUserConfigured) intents.push({ op: 'assign_user' });
+  }
+
+  const rank = PHASE_RANK[state.phase] ?? 0;
+  const backlog = Array.isArray(state.backlog) ? state.backlog : [];
+
+  // 2. Create a task per backlog item once the FD has reached DISPATCH (the task
+  //    then carries the dispatched specialist). Skipped items are not created.
+  if (rank >= PHASE_RANK.DISPATCH && state.phase !== 'ABORTED') {
+    for (const item of backlog) {
+      if (!item || !item.id) continue;
+      if (item.status === 'skipped') continue;
+      if (!tasks[item.id]) {
+        intents.push({ op: 'task_create', backlogId: item.id, headline: item.title || item.id });
+      }
+    }
+  }
+
+  // 3. Move every task (already-mapped + just-created) to the column the current
+  //    state implies. ABORTED yields no column -> no move. To bound RPC volume
+  //    (byan_fd_update fires several times per phase), moves are emitted only when
+  //    the target column changed since the last applied fire (sidecar.lastColumn),
+  //    OR a task was just created, OR the prior fire left a move unsynced
+  //    (sidecar.moveFailed) so a dropped move self-heals on the next event.
+  const column = columnForState(state);
+  const createdThisFire = intents.some((i) => i.op === 'task_create');
+  const moveNeeded = column && (column !== sidecar.lastColumn || createdThisFire || sidecar.moveFailed === true);
+  if (moveNeeded) {
+    const seen = new Set();
+    for (const item of backlog) {
+      if (!item || !item.id || item.status === 'skipped') continue;
+      // a just-created task is moved in the same fire; an already-mapped one is
+      // reconciled to the current column (self-heals a dropped earlier move).
+      const willExist = tasks[item.id] || intents.some((i) => i.op === 'task_create' && i.backlogId === item.id);
+      if (willExist && !seen.has(item.id)) {
+        intents.push({ op: 'task_move', backlogId: item.id, column });
+        seen.add(item.id);
+      }
+    }
+    // tasks in the sidecar that are no longer in the backlog still get swept to a
+    // terminal column on COMPLETED, so the board does not strand a renamed item.
+    if (state.phase === 'COMPLETED') {
+      for (const backlogId of Object.keys(tasks)) {
+        if (!seen.has(backlogId)) {
+          intents.push({ op: 'task_move', backlogId, column });
+          seen.add(backlogId);
+        }
+      }
+    }
+  }
+
+  // `column` is the current target; the shell persists it as sidecar.lastColumn so
+  // the next fire can skip a redundant move sweep.
+  return { intents, column };
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/leantime-sync.js

@@ -0,0 +1,415 @@
+// BYAN <-> Leantime sync layer.
+//
+// Leantime (self-hosted project-management tool) is the authority for the
+// projects/tasks that the FD workflow mirrors. This module is the only place
+// that talks to the Leantime JSON-RPC API; the FD skill drives it through the
+// byan_leantime_* MCP tools, never by importing this file from a workflow.
+//
+// Best-effort, like lib/strict-sync.js: a missing token/base, an unreachable
+// instance, a non-2xx, a JSON-RPC error envelope, or a non-JSON (HTML login)
+// body degrades to { ok:false, synced:false, reason } and never throws. A down
+// Leantime must not break an FD phase transition.
+//
+// API shape (Leantime JSON-RPC 2.0):
+//   POST <base>/api/jsonrpc  with header  x-api-key: <token>
+//   body { jsonrpc:"2.0", id, method:"leantime.rpc.<domain>.<method>", params }
+//   Auth is the x-api-key header ONLY — never the byan_/ApiKey/Bearer scheme.
+//
+// Method names + param wrapping are read from the Leantime master source (L2).
+// The single METHODS table below is the one place to correct them once the F0
+// live-verify (one real POST with a Personal Access Token) confirms the wire
+// format against projets.acadenice.com. Items tagged VERIFY@F0 are the ones the
+// recon could not confirm without a live call.
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const RPC_PATH = '/api/jsonrpc';
+
+// Canonical FD lifecycle columns. Resolved to per-project Leantime status ids at
+// call time via resolveStatusMap (Leantime statuses are configurable per project,
+// so a fixed int map would drift). Mirrors lib/kanban.js COLUMNS.
+const COLUMNS = ['todo', 'doing', 'blocked', 'review', 'done'];
+
+// Single source of truth for the JSON-RPC method names (L2: Leantime master
+// Projects.php / Tickets.php). Correct here after F0 if the live wire differs.
+const METHODS = {
+  addProject: 'leantime.rpc.projects.addProject',
+  getAllProjects: 'leantime.rpc.projects.getAllProjects',
+  getUsersAssignedToProject: 'leantime.rpc.projects.getUsersAssignedToProject',
+  addTicket: 'leantime.rpc.tickets.addTicket',
+  updateTicket: 'leantime.rpc.tickets.updateTicket',
+  getTicket: 'leantime.rpc.tickets.getTicket', // VERIFY@F0 (single-ticket getter name)
+  getAllTickets: 'leantime.rpc.tickets.getAll',
+  getStatusLabels: 'leantime.rpc.tickets.getStatusLabels',
+  getAllClients: 'leantime.rpc.clients.getAllClients',
+  // F0-confirmed (Leantime 3.7.1 source): the JSON-RPC resolves SERVICE methods
+  // only. editUserProjectRelations is keyed by USER and RECONCILES the user's
+  // project list (adds the absent, deletes those not passed), so
+  // assignUserToProject reads the full list first. getProjectsAssignedToUser is
+  // that read.
+  editUserProjectRelations: 'leantime.rpc.projects.editUserProjectRelations',
+  getProjectsAssignedToUser: 'leantime.rpc.projects.getProjectsAssignedToUser',
+};
+
+// Conservative fallback when resolveStatusMap cannot read the project's labels
+// (Leantime default seed: 3=new). Confirmed/overridden at F0. Used only as a
+// last resort so a status move degrades to a plausible id rather than throwing.
+const DEFAULT_STATUS_MAP = {
+  todo: 3,
+  doing: 1,
+  blocked: 4,
+  review: 2,
+  done: 0,
+};
+
+function apiBase() {
+  return (process.env.LEANTIME_API_URL || '').replace(/\/+$/, '');
+}
+
+function apiToken() {
+  return process.env.LEANTIME_API_TOKEN || '';
+}
+
+// Leantime authenticates the JSON-RPC API with its own header, NOT an
+// Authorization scheme. Reusing the byan_/ApiKey/Bearer switch would send a
+// header Leantime ignores -> the call goes through unauthenticated (likely a
+// 401, or a fall-through to the HTML login that the non_json guard catches; the
+// exact code is confirmed at F0, see VERIFY@F0).
+function authHeader(token) {
+  if (!token) return {};
+  return { 'x-api-key': token };
+}
+
+export function syncEnabled({ token = apiToken(), base = apiBase() } = {}) {
+  return Boolean(token && base);
+}
+
+// Low-level JSON-RPC call. Best-effort, never throws.
+// Returns { ok, synced, reason?, data?, status?, error?, hint? }.
+export async function rpc(
+  method,
+  params = {},
+  { base = apiBase(), token = apiToken(), fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS, id = 'byan' } = {},
+) {
+  if (!base) return { ok: false, synced: false, reason: 'no_base' };
+  if (!token) return { ok: false, synced: false, reason: 'no_token' };
+  if (typeof fetchImpl !== 'function') return { ok: false, synced: false, reason: 'no_fetch' };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`${base}${RPC_PATH}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...authHeader(token) },
+      body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      return { ok: false, synced: false, reason: `http_${res.status}`, status: res.status };
+    }
+
+    // Wrong-host guard (the BYAN_API_URL lesson): Leantime serves the HTML app
+    // AND the JSON-RPC API on the same domain. A 200 carrying HTML means
+    // LEANTIME_API_URL points at the UI, not the API. A parse failure (or a
+    // non-object body) is treated as a wrong-host/non-JSON response, never read
+    // as an empty result.
+    const contentType = (res.headers && typeof res.headers.get === 'function'
+      ? (res.headers.get('content-type') || '')
+      : '').toLowerCase();
+    let data = null;
+    try {
+      data = await res.json();
+    } catch {
+      data = null;
+    }
+    if (data === null || typeof data !== 'object') {
+      const hint = contentType.includes('text/html')
+        ? 'Expected JSON-RPC, got HTML. LEANTIME_API_URL likely points at the Leantime UI, not the /api/jsonrpc backend.'
+        : 'Expected a JSON-RPC envelope.';
+      return { ok: false, synced: false, reason: 'non_json', hint };
+    }
+
+    // `error` carries the Leantime envelope verbatim for the caller's own logic;
+    // a caller logging to a shared file must record `reason` only, never `error`,
+    // to keep a server message (which could echo input) out of the log.
+    if (data.error) {
+      return { ok: false, synced: false, reason: 'rpc_error', error: data.error, status: res.status };
+    }
+    // Leantime returns { jsonrpc, id, result }. `result` may legitimately be
+    // false/0/'' on a failed-but-200 op, so expose it verbatim.
+    return { ok: true, synced: true, status: res.status, data: data.result };
+  } catch (err) {
+    return {
+      ok: false,
+      synced: false,
+      reason: err && err.name === 'AbortError' ? 'timeout' : 'network_error',
+      error: err ? err.message : String(err),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// addProject takes `array $values`; addTicket takes `$values`. The recon read
+// the named PHP arg as the params key (params:{values:{...}}). F0 (2026-06-15)
+// confirmed live that the server expects params:{values:{...}} for both.
+function wrapValues(values) {
+  return { values };
+}
+
+// Leantime project/ticket ids are positive auto-increment integers. rpc() exposes
+// a falsy JSON-RPC result verbatim (a 200 carrying result false/0/'' is a
+// failed-but-not-errored op), so a create path must reject a non-positive id
+// instead of persisting it back into fd-state as a real id.
+function isValidId(v) {
+  if (typeof v === 'boolean') return false;
+  const n = Number(v);
+  if (Number.isFinite(n)) return n > 0;
+  return typeof v === 'string' && v.length > 0;
+}
+
+// Leantime's addProject / addTicket return the new id wrapped in a
+// single-element array (result:[id]) on 3.7.x, confirmed live at F0
+// (2026-06-15: addProject -> [69], addTicket -> [770]). Other shapes give a
+// scalar id or an { id } object. Normalize all three to the scalar id, so a
+// create does not propagate an array (isValidId would accept Number([69])===69)
+// and does not mis-read [id].id as undefined.
+function firstId(data) {
+  if (Array.isArray(data)) return data.length ? data[0] : undefined;
+  if (data && typeof data === 'object') return data.id;
+  return data;
+}
+
+// Idempotent create-or-fetch of a Leantime project from the FD project_context.
+// Matches an existing project by exact name first (so re-running an FD or a
+// REFACTOR loop does not duplicate). Returns { ok, id, created, synced, reason }.
+export async function ensureProject({ name, slug, clientId, details } = {}, opts = {}) {
+  const term = name || slug;
+  if (!term) return { ok: false, synced: false, reason: 'no_name' };
+
+  const existing = await rpc(METHODS.getAllProjects, {}, opts);
+  if (existing.ok && Array.isArray(existing.data)) {
+    const hit = existing.data.find((p) => p && (p.name === term || p.name === name || p.name === slug));
+    if (hit) return { ok: true, synced: true, id: hit.id, created: false };
+  } else if (!existing.ok) {
+    // A failed list (not an empty one) means "is it absent?" is unknown. Creating
+    // here would mint a duplicate on the next FD re-run that hits the same
+    // transient error, breaking the idempotency contract. Surface the failure.
+    return { ...existing, created: false };
+  }
+
+  const resolvedClientId = clientId != null ? clientId : await resolveClientId(opts);
+  const created = await rpc(
+    METHODS.addProject,
+    wrapValues({ name: term, clientId: resolvedClientId, details: details || `Created by BYAN FD (slug: ${slug || term}).` }),
+    opts,
+  );
+  if (!created.ok) return created;
+  const newId = firstId(created.data);
+  if (!isValidId(newId)) {
+    return { ok: false, synced: false, reason: 'create_rejected', data: created.data };
+  }
+  return { ok: true, synced: true, id: newId, created: true };
+}
+
+// Create one Leantime task from an FD backlog item. Returns the new task id in
+// `id` so the caller can store it back into fd-state (idempotency lives in the
+// caller: create-only-if the backlog item has no leantime_task_id yet).
+export async function createTask(
+  { projectId, headline, description, status, priority, editorId, tags, type = 'task' } = {},
+  opts = {},
+) {
+  if (!projectId) return { ok: false, synced: false, reason: 'no_project_id' };
+  if (!headline) return { ok: false, synced: false, reason: 'no_headline' };
+
+  const values = { projectId, headline, type };
+  if (description != null) values.description = description;
+  if (status != null) values.status = status;
+  if (priority != null) values.priority = priority;
+  // Default the assignee to the configured human (LEANTIME_ASSIGN_USER_ID) so an
+  // auto-created task shows on a person's board, not only the API service user.
+  const resolvedEditor = editorId != null ? editorId : assignUserId();
+  if (resolvedEditor != null) values.editorId = resolvedEditor;
+  if (tags != null) values.tags = tags;
+
+  const res = await rpc(METHODS.addTicket, wrapValues(values), opts);
+  if (!res.ok) return res;
+  // addTicket returns the new id wrapped in a single-element array
+  // (result:[id], confirmed live at F0); other shapes give a scalar or { id }.
+  const id = firstId(res.data);
+  // A 200 with a falsy result is a failed-but-not-errored add, not a new id;
+  // do not persist it back into fd-state as a real task id.
+  if (!isValidId(id)) {
+    return { ok: false, synced: false, reason: 'create_rejected', data: res.data };
+  }
+  return { ok: true, synced: true, id };
+}
+
+// Move a task to a lifecycle column. Resolves the column to the project's status
+// id, then updates the ticket (Leantime has no dedicated status-change RPC).
+export async function moveTask({ taskId, projectId, column, status }, opts = {}) {
+  if (!taskId) return { ok: false, synced: false, reason: 'no_task_id' };
+  let statusId = status;
+  if (statusId == null) {
+    if (!COLUMNS.includes(column)) return { ok: false, synced: false, reason: 'bad_column' };
+    const map = await resolveStatusMap({ projectId }, opts);
+    statusId = map[column];
+    // resolveStatusMap leaves a column undefined rather than collapse it onto an
+    // id already claimed by another column. Surface that instead of sending an
+    // undefined status (which JSON.stringify would silently drop from the body).
+    if (statusId == null) return { ok: false, synced: false, reason: 'unresolved_status' };
+  }
+  return rpc(METHODS.updateTicket, wrapValues({ id: taskId, status: statusId }), opts);
+}
+
+// Set the assignee/editor of a task (mirror of byan_kanban_assign).
+export async function assignTask({ taskId, editorId }, opts = {}) {
+  if (!taskId) return { ok: false, synced: false, reason: 'no_task_id' };
+  if (editorId == null) return { ok: false, synced: false, reason: 'no_editor_id' };
+  return rpc(METHODS.updateTicket, wrapValues({ id: taskId, editorId }), opts);
+}
+
+export async function getTask({ taskId }, opts = {}) {
+  if (!taskId) return { ok: false, synced: false, reason: 'no_task_id' };
+  return rpc(METHODS.getTicket, { id: taskId }, opts);
+}
+
+// List a project's tasks grouped by lifecycle column (mirror of byan_kanban_get).
+export async function getBoard({ projectId }, opts = {}) {
+  if (!projectId) return { ok: false, synced: false, reason: 'no_project_id' };
+  const res = await rpc(METHODS.getAllTickets, { searchCriteria: { currentProject: projectId } }, opts);
+  if (!res.ok) return res;
+  const tickets = Array.isArray(res.data) ? res.data : [];
+  const map = await resolveStatusMap({ projectId }, opts);
+  const byStatusId = {};
+  // Skip an undefined sid: resolveStatusMap may leave a column unmapped (a
+  // would-collide default), and byStatusId[undefined] would coerce to the string
+  // key 'undefined', shadowing the 'todo' fallback for a genuinely null-status
+  // ticket. Only real status ids become keys.
+  for (const [col, sid] of Object.entries(map)) if (sid != null) byStatusId[sid] = col;
+  const board = Object.fromEntries(COLUMNS.map((c) => [c, []]));
+  for (const t of tickets) {
+    const col = byStatusId[t && t.status] || 'todo';
+    board[col].push(t);
+  }
+  return { ok: true, synced: true, data: board };
+}
+
+// Build a COLUMN -> Leantime status-id map for a project. Reads the project's
+// configured status labels and matches them to the canonical columns by label
+// substring; falls back to DEFAULT_STATUS_MAP when the labels cannot be read,
+// so a move degrades to a plausible id rather than throwing.
+export async function resolveStatusMap({ projectId } = {}, opts = {}) {
+  const res = await rpc(METHODS.getStatusLabels, projectId != null ? { projectId } : {}, opts);
+  if (!res.ok || !res.data || typeof res.data !== 'object') return { ...DEFAULT_STATUS_MAP };
+
+  // res.data is typically { <statusId>: { name, ... } }. Match by name.
+  const entries = Object.entries(res.data);
+  // Short, ambiguous needles match on a word boundary so a custom label like
+  // 'Renewal' (contains 'new') is not mis-claimed; longer distinctive needles
+  // stay plain substrings.
+  const WORD_NEEDLES = new Set(['new', 'wip', 'qa']);
+  const labelHas = (label, n) => (WORD_NEEDLES.has(n) ? new RegExp(`\\b${n}\\b`).test(label) : label.includes(n));
+  const find = (...needles) => {
+    for (const [sid, meta] of entries) {
+      const label = String((meta && (meta.name || meta.label)) || '').toLowerCase();
+      if (needles.some((n) => labelHas(label, n))) return Number(sid);
+    }
+    return undefined;
+  };
+  const map = {
+    todo: find('todo', 'new', 'backlog', 'to do'),
+    doing: find('progress', 'doing', 'wip'),
+    blocked: find('block', 'hold'),
+    review: find('review', 'qa', 'test'),
+    done: find('done', 'closed', 'complete'),
+  };
+  // Fill any unmatched column from the conservative default, but do not reuse an
+  // id already claimed by a real label-matched column: two FD columns collapsing
+  // onto one status id would mis-bucket the board and mis-target a move (e.g.
+  // review and done both -> 2 when a project defines only 'Done'). A column that
+  // would only collide stays undefined; getBoard routes an unmapped status to
+  // 'todo' and moveTask surfaces 'unresolved_status'.
+  const claimed = new Set(Object.values(map).filter((v) => v != null));
+  for (const col of COLUMNS) {
+    if (map[col] != null) continue;
+    const fallback = DEFAULT_STATUS_MAP[col];
+    if (!claimed.has(fallback)) {
+      map[col] = fallback;
+      claimed.add(fallback);
+    }
+  }
+  return map;
+}
+
+// Resolve a clientId for addProject (a project with no client may be orphaned).
+// Prefers LEANTIME_CLIENT_ID, else the first client the API returns, else 1.
+export async function resolveClientId(opts = {}) {
+  const fromEnv = process.env.LEANTIME_CLIENT_ID;
+  if (fromEnv) return Number(fromEnv);
+  const res = await rpc(METHODS.getAllClients, {}, opts);
+  if (res.ok && Array.isArray(res.data) && res.data.length > 0) {
+    return res.data[0].id != null ? res.data[0].id : 1;
+  }
+  return 1;
+}
+
+// Resolve a valid editor/assignee id for a project (first assigned user).
+export async function resolveEditorId({ projectId } = {}, opts = {}) {
+  if (!projectId) return null;
+  const res = await rpc(METHODS.getUsersAssignedToProject, { projectId }, opts);
+  if (res.ok && Array.isArray(res.data) && res.data.length > 0) {
+    return res.data[0].id != null ? res.data[0].id : null;
+  }
+  return null;
+}
+
+// The configured human Leantime user id (LEANTIME_ASSIGN_USER_ID), or null. Used
+// to make auto-created projects/tasks visible to a person: an API key creates
+// them as a service user, hidden from a human's project selector until related.
+export function assignUserId() {
+  const v = process.env.LEANTIME_ASSIGN_USER_ID;
+  const n = Number(v);
+  return v && Number.isFinite(n) && n > 0 ? n : null;
+}
+
+// Relate a human user to a project so the project shows in their selector.
+//
+// SAFETY (F0, Leantime 3.7.1 source): the only RPC-reachable write,
+// editUserProjectRelations, is keyed by USER and RECONCILES — it deletes every
+// relation NOT in the list it is handed. Passing a bare [projectId] would
+// unassign the user from all their other projects. So this reads the user's
+// CURRENT projects (projectStatus 'all') and writes the union. FAIL-CLOSED: if
+// that read fails, returns empty, or is only partially parseable, it does NOT
+// write (a partial list could drop real memberships) and surfaces a reason.
+export async function assignUserToProject({ projectId, userId } = {}, opts = {}) {
+  const uid = userId != null ? userId : assignUserId();
+  if (uid == null) return { ok: false, synced: false, reason: 'no_assign_user' };
+  if (!projectId) return { ok: false, synced: false, reason: 'no_project_id' };
+
+  const current = await rpc(METHODS.getProjectsAssignedToUser, { userId: uid, projectStatus: 'all' }, opts);
+  if (!current.ok) return { ok: false, synced: false, reason: 'assign_read_failed' };
+  const raw = Array.isArray(current.data) ? current.data : [];
+  const ids = raw
+    .map((p) => (p && p.id != null ? Number(p.id) : null))
+    .filter((n) => Number.isFinite(n) && n > 0);
+  // Fail-closed on an empty read: "no projects" and a partial/failed read are
+  // indistinguishable here, and writing an incomplete list would delete real
+  // memberships. A human is in practice already on >= 1 project.
+  if (ids.length === 0) return { ok: false, synced: false, reason: 'assign_read_empty' };
+  // Fail-closed on a partially-parseable read: if any row did not yield a positive
+  // id, the read shape is not trusted. editUserProjectRelations reconciles, so
+  // writing the parsed subset would drop the memberships behind the unparsed rows.
+  if (ids.length !== raw.length) return { ok: false, synced: false, reason: 'assign_read_partial' };
+  if (ids.includes(Number(projectId))) return { ok: true, synced: true, alreadyAssigned: true };
+
+  const res = await rpc(
+    METHODS.editUserProjectRelations,
+    { id: uid, projects: [...ids, Number(projectId)] },
+    opts,
+  );
+  if (!res.ok) return res;
+  return { ok: true, synced: true, assigned: true, userId: uid, projectId: Number(projectId) };
+}
+
+export { COLUMNS, METHODS, DEFAULT_STATUS_MAP };

package/install/templates/_byan/mcp/byan-mcp-server/lib/precommit-gate.js

@@ -4,7 +4,7 @@ import { fetchSession, syncEnabled } from './strict-sync.js';
 // BYAN Strict Mode pre-commit gate.
 //
 // The final, platform-agnostic net. Claude Code has in-session hooks; Codex
-// and Copilot do not. This gate runs at commit time on every platform, so an
+// does not. This gate runs at commit time on every platform, so an
 // agent that engaged strict mode but bailed on verification cannot land the
 // commit.
 //