@work-graph/cli 0.2.0

package/vendor/src/workItemEpicCascade.mjs

@@ -0,0 +1,176 @@
+import {
+  attachDerivedWorkItemHierarchy,
+  DONE_STATUSES,
+  readWorkItemKind,
+} from './workItemHierarchy.mjs';
+import { transitionStatus } from './workGraphRuntime.mjs';
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+function replaceWorkItem(items, updatedItem) {
+  return items.map((entry) => (entry.id === updatedItem.id ? updatedItem : entry));
+}
+
+/**
+ * @param {Array<{ id: string, status?: string, childIds?: string[] }>} items
+ * @param {string} rootId
+ */
+export function collectOpenDescendantWorkItems(items, rootId) {
+  const enriched = attachDerivedWorkItemHierarchy(items);
+  const itemById = new Map(enriched.map((entry) => [entry.id, entry]));
+  /** @type {Array<{ id: string, status?: string }>} */
+  const open = [];
+  /** @type {string[]} */
+  const queue = [...(itemById.get(rootId)?.childIds ?? [])];
+  const visited = new Set();
+
+  while (queue.length > 0) {
+    const childId = queue.shift();
+    if (childId === undefined || visited.has(childId)) {
+      continue;
+    }
+    visited.add(childId);
+
+    const child = itemById.get(childId);
+    if (!child) {
+      continue;
+    }
+
+    for (const nestedId of child.childIds ?? []) {
+      queue.push(nestedId);
+    }
+
+    if (!DONE_STATUSES.has(String(child.status ?? '').trim())) {
+      open.push(child);
+    }
+  }
+
+  return open.sort((left, right) => compareText(left.id, right.id));
+}
+
+/**
+ * @param {Array<import('./workGraphRuntime.mjs').WorkItem>} items
+ * @param {import('./workGraphRuntime.mjs').WorkItem} item
+ * @param {string} targetStatus
+ * @param {{ evidence?: string, cascadeEvidence?: string, reason?: string, blocker?: string }} [options]
+ */
+export function transitionWorkItemWithEpicCascade(items, item, targetStatus, options = {}) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('items must be an array');
+  }
+  if (!item?.id) {
+    throw new TypeError('item.id is required');
+  }
+
+  if (readWorkItemKind(item) !== 'epic' || !DONE_STATUSES.has(targetStatus)) {
+    const updated = transitionStatus(item, targetStatus, {
+      reason: options.reason,
+      blocker: options.blocker,
+      evidence: options.evidence,
+      allItems: items,
+    });
+    return {
+      items: replaceWorkItem(items, updated),
+      updatedItems: [updated],
+      cascadedChildIds: [],
+    };
+  }
+
+  let working = items.map((entry) => ({ ...entry }));
+  /** @type {string[]} */
+  const cascadedChildIds = [];
+  const cascadeEvidence = String(
+    options.cascadeEvidence ?? `cascade: parent epic ${item.id} → ${targetStatus}`,
+  ).trim();
+  const openDescendants = collectOpenDescendantWorkItems(working, item.id);
+
+  for (const child of openDescendants) {
+    const currentChild = working.find((entry) => entry.id === child.id);
+    if (!currentChild) {
+      continue;
+    }
+    const updatedChild = transitionStatus(currentChild, targetStatus, {
+      evidence: cascadeEvidence,
+      allItems: working,
+    });
+    working = replaceWorkItem(working, updatedChild);
+    cascadedChildIds.push(updatedChild.id);
+  }
+
+  const currentEpic = working.find((entry) => entry.id === item.id) ?? item;
+  const updatedEpic = transitionStatus(currentEpic, targetStatus, {
+    reason: options.reason,
+    blocker: options.blocker,
+    evidence: options.evidence,
+    allItems: working,
+  });
+  working = replaceWorkItem(working, updatedEpic);
+
+  return {
+    items: working,
+    updatedItems: [
+      ...working.filter((entry) => cascadedChildIds.includes(entry.id)),
+      updatedEpic,
+    ],
+    cascadedChildIds,
+  };
+}
+
+/**
+ * Repair drift: epic already done/verified while descendants remain open.
+ *
+ * @param {Array<import('./workGraphRuntime.mjs').WorkItem>} items
+ * @param {string} epicId
+ * @param {{ cascadeEvidence?: string, targetStatus?: string }} [options]
+ */
+export function closeOpenDescendantsForDoneEpic(items, epicId, options = {}) {
+  const epic = items.find((entry) => entry.id === epicId);
+  if (!epic || readWorkItemKind(epic) !== 'epic' || !DONE_STATUSES.has(String(epic.status ?? '').trim())) {
+    return {
+      items,
+      updatedItems: [],
+      cascadedChildIds: [],
+    };
+  }
+
+  const targetStatus = options.targetStatus ?? epic.status;
+  let working = items.map((entry) => ({ ...entry }));
+  /** @type {string[]} */
+  const cascadedChildIds = [];
+  const cascadeEvidence = String(
+    options.cascadeEvidence ?? `cascade: reconcile epic ${epic.id} already ${targetStatus}`,
+  ).trim();
+
+  for (const child of collectOpenDescendantWorkItems(working, epic.id)) {
+    const currentChild = working.find((entry) => entry.id === child.id);
+    if (!currentChild) {
+      continue;
+    }
+    const updatedChild = transitionStatus(currentChild, targetStatus, {
+      evidence: cascadeEvidence,
+      allItems: working,
+    });
+    working = replaceWorkItem(working, updatedChild);
+    cascadedChildIds.push(updatedChild.id);
+  }
+
+  return {
+    items: working,
+    updatedItems: working.filter((entry) => cascadedChildIds.includes(entry.id)),
+    cascadedChildIds,
+  };
+}
+
+/**
+ * @param {Array<import('./workGraphRuntime.mjs').WorkItem>} items
+ */
+export function findDoneEpicsWithOpenDescendants(items) {
+  return attachDerivedWorkItemHierarchy(items)
+    .filter((item) => readWorkItemKind(item) === 'epic' && DONE_STATUSES.has(String(item.status ?? '').trim()))
+    .map((epic) => ({
+      epicId: epic.id,
+      openChildIds: collectOpenDescendantWorkItems(items, epic.id).map((child) => child.id),
+    }))
+    .filter((entry) => entry.openChildIds.length > 0)
+    .sort((left, right) => compareText(left.epicId, right.epicId));
+}

package/vendor/src/workItemExecutionGate.mjs

@@ -0,0 +1,78 @@
+import { PIPELINE_VERDICTS } from './workItemDecisionPipeline.mjs';
+
+const EXECUTION_TARGET_STATUSES = new Set(['ready', 'claimed', 'doing', 'in_progress']);
+
+export function hasWorkItemAnalysis(item) {
+  return String(item?.analysis ?? '').trim().length > 0;
+}
+
+export function workItemDecisionVerdict(item) {
+  const verdict = String(item?.labels?.['work.decision.verdict'] ?? '').trim();
+  return PIPELINE_VERDICTS.includes(verdict) ? verdict : null;
+}
+
+export function evaluateWorkItemExecutionGate(item) {
+  if (!item) {
+    return {
+      allowed: false,
+      code: 'work_item_missing',
+      message: 'WorkItem not found',
+    };
+  }
+
+  if (!hasWorkItemAnalysis(item)) {
+    return {
+      allowed: false,
+      code: 'missing_analysis',
+      message:
+        'Нет анализа в атоме задачи. В Cursor: get_work_item → анализ целесообразности (до исполнения) → record_work_item_analysis.',
+    };
+  }
+
+  const verdict = workItemDecisionVerdict(item);
+  if (verdict === null) {
+    return {
+      allowed: false,
+      code: 'missing_decision',
+      message:
+        'Нет утверждения (useful/harmful/defer). В Cursor: record_work_item_decision после анализа.',
+    };
+  }
+
+  if (verdict === 'defer') {
+    return {
+      allowed: false,
+      code: 'verdict_defer',
+      message: 'Задача отложена (defer). Исполнение запрещено до пересмотра и нового useful.',
+    };
+  }
+
+  if (verdict === 'harmful') {
+    return {
+      allowed: false,
+      code: 'verdict_harmful',
+      message: 'Задача отклонена (harmful). Исполнение запрещено.',
+    };
+  }
+
+  return {
+    allowed: true,
+    code: 'ok',
+    message: '',
+    verdict,
+  };
+}
+
+export function assertWorkItemExecutionAllowed(item) {
+  const gate = evaluateWorkItemExecutionGate(item);
+  if (!gate.allowed) {
+    const error = new Error(gate.message);
+    error.code = gate.code;
+    throw error;
+  }
+  return gate;
+}
+
+export function statusChangeRequiresExecutionGate(status) {
+  return EXECUTION_TARGET_STATUSES.has(String(status ?? '').trim());
+}

package/vendor/src/workItemHierarchy.mjs

@@ -0,0 +1,226 @@
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+export const WORK_ITEM_KINDS = ['epic', 'task', 'subtask'];
+export const DEFAULT_WORK_ITEM_KIND = 'task';
+export const DONE_STATUSES = new Set(['done', 'verified']);
+
+export function normalizeWorkItemKind(value) {
+  const kind = String(value ?? '').trim().toLowerCase();
+  if (kind === '') {
+    return DEFAULT_WORK_ITEM_KIND;
+  }
+  return kind;
+}
+
+export function isValidWorkItemKind(value) {
+  const kind = String(value ?? '').trim().toLowerCase();
+  return kind === '' || WORK_ITEM_KINDS.includes(kind);
+}
+
+export function readWorkItemParentId(item) {
+  return String(item?.parentId ?? item?.labels?.['work.parent_id'] ?? '').trim();
+}
+
+export function readWorkItemKind(item) {
+  return normalizeWorkItemKind(item?.itemKind ?? item?.labels?.['work.item_kind']);
+}
+
+export function buildChildIdsByParentId(items) {
+  const childIdsByParent = new Map();
+
+  for (const item of items) {
+    const parentId = readWorkItemParentId(item);
+    if (parentId === '') {
+      continue;
+    }
+
+    if (!childIdsByParent.has(parentId)) {
+      childIdsByParent.set(parentId, []);
+    }
+    childIdsByParent.get(parentId).push(item.id);
+  }
+
+  for (const childIds of childIdsByParent.values()) {
+    childIds.sort(compareText);
+  }
+
+  return childIdsByParent;
+}
+
+export function attachDerivedWorkItemHierarchy(items) {
+  const childIdsByParent = buildChildIdsByParentId(items);
+
+  return items.map((item) => ({
+    ...item,
+    parentId: readWorkItemParentId(item),
+    itemKind: readWorkItemKind(item),
+    childIds: [...(childIdsByParent.get(item.id) ?? [])],
+  }));
+}
+
+export function hasWorkItemParentCycle(itemId, itemById) {
+  const visited = new Set();
+  let current = itemId;
+
+  while (current !== '') {
+    if (visited.has(current)) {
+      return true;
+    }
+    visited.add(current);
+    current = readWorkItemParentId(itemById.get(current));
+  }
+
+  return false;
+}
+
+export function lintWorkItemHierarchyIssues(items) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('items must be an array');
+  }
+
+  const issues = [];
+  const itemById = new Map(items.map((item) => [item.id, item]));
+  const childIdsByParent = buildChildIdsByParentId(items);
+
+  for (const item of items) {
+    const parentId = readWorkItemParentId(item);
+    const rawKind = String(item?.labels?.['work.item_kind'] ?? item?.itemKind ?? '').trim().toLowerCase();
+    const itemKind = readWorkItemKind(item);
+
+    if (rawKind !== '' && !WORK_ITEM_KINDS.includes(rawKind)) {
+      issues.push({
+        severity: 'error',
+        code: 'invalid_item_kind',
+        message: `Invalid work.item_kind "${rawKind}" for ${item.id}`,
+        workId: item.id,
+        itemKind: rawKind,
+      });
+    }
+
+    if (parentId === item.id) {
+      issues.push({
+        severity: 'error',
+        code: 'self_parent',
+        message: `WorkItem cannot be its own parent: ${item.id}`,
+        workId: item.id,
+      });
+      continue;
+    }
+
+    if (parentId !== '' && !itemById.has(parentId)) {
+      issues.push({
+        severity: 'error',
+        code: 'missing_parent',
+        message: `Missing parent "${parentId}" for ${item.id}`,
+        workId: item.id,
+        parentId,
+      });
+    }
+
+    if (parentId !== '' && hasWorkItemParentCycle(item.id, itemById)) {
+      issues.push({
+        severity: 'error',
+        code: 'parent_cycle',
+        message: `Parent cycle detected for ${item.id}`,
+        workId: item.id,
+        parentId,
+      });
+    }
+
+    for (const dependencyId of item.dependsOn ?? []) {
+      const dependency = itemById.get(dependencyId);
+      if (dependency !== undefined && readWorkItemParentId(dependency) === item.id) {
+        issues.push({
+          severity: 'error',
+          code: 'parent_depends_on_child',
+          message: `Parent ${item.id} depends_on child ${dependencyId}`,
+          workId: item.id,
+          dependencyId,
+        });
+      }
+    }
+
+    if (itemKind === 'epic' && (childIdsByParent.get(item.id) ?? []).length === 0) {
+      issues.push({
+        severity: 'warning',
+        code: 'epic_without_children',
+        message: `Epic ${item.id} has no child WorkItems`,
+        workId: item.id,
+        itemKind,
+      });
+    }
+
+    if (itemKind === 'epic' && DONE_STATUSES.has(String(item.status ?? '').trim())) {
+      const rollup = summarizeWorkItemHierarchyRollup(item, items);
+      if (rollup.openChildIds.length > 0) {
+        issues.push({
+          severity: 'warning',
+          code: 'epic_done_open_children',
+          message: `Epic ${item.id} is done but child WorkItems remain open (${rollup.openChildIds.join(', ')})`,
+          workId: item.id,
+          openChildIds: rollup.openChildIds,
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+export function summarizeWorkItemHierarchyRollup(item, items) {
+  const enriched = attachDerivedWorkItemHierarchy(items);
+  const fullItem = enriched.find((candidate) => candidate.id === item.id) ?? item;
+  const childIds = fullItem.childIds ?? [];
+  if (childIds.length === 0) {
+    return {
+      childCount: 0,
+      doneChildCount: 0,
+      openChildIds: [],
+      closeBlocked: false,
+    };
+  }
+
+  const itemById = new Map(enriched.map((entry) => [entry.id, entry]));
+  const openChildIds = childIds.filter((childId) => {
+    const child = itemById.get(childId);
+    return child !== undefined && !DONE_STATUSES.has(child.status);
+  });
+
+  return {
+    childCount: childIds.length,
+    doneChildCount: childIds.length - openChildIds.length,
+    openChildIds,
+    closeBlocked: openChildIds.length > 0,
+  };
+}
+
+export function evaluateParentCloseGate(items, item, targetStatus) {
+  if (!DONE_STATUSES.has(String(targetStatus ?? '').trim())) {
+    return { ok: true };
+  }
+
+  const rollup = summarizeWorkItemHierarchyRollup(item, items);
+  if (!rollup.closeBlocked) {
+    return { ok: true, rollup };
+  }
+
+  return {
+    ok: false,
+    code: 'parent_close_blocked_open_children',
+    message: `Cannot close ${item.id}: open child WorkItems remain (${rollup.openChildIds.join(', ')})`,
+    workId: item.id,
+    openChildIds: rollup.openChildIds,
+    rollup,
+  };
+}
+
+export function assertParentCloseAllowed(items, item, targetStatus) {
+  const gate = evaluateParentCloseGate(items, item, targetStatus);
+  if (!gate.ok) {
+    const error = new Error(gate.message);
+    error.code = gate.code;
+    error.openChildIds = gate.openChildIds;
+    throw error;
+  }
+  return gate;
+}

package/vendor/src/workItemProseLint.mjs

@@ -0,0 +1,133 @@
+/**
+ * Lint human prose in WorkItem sections — робототекст и англоязычный жаргон.
+ */
+
+const PROSE_FIELDS = ['basis', 'vector', 'goal', 'checks', 'analysis', 'decision'];
+
+/** @type {Array<{ code: string, pattern: RegExp, hint: string }>} */
+export const WORK_ITEM_JARGON_PATTERNS = [
+  { code: 'jargon_closing_analysis', pattern: /\bclosing analysis\b/ui, hint: '«итоговый разбор после эпика»' },
+  { code: 'jargon_canon_colon', pattern: /\bCanon:/ui, hint: '«канон:» или опиши по-русски' },
+  { code: 'jargon_evidence_word', pattern: /\bevidence\b/ui, hint: '«свидетельства» / «подтверждение»' },
+  { code: 'jargon_upstream', pattern: /\bupstream\b/ui, hint: '«вышестоящие зависимости»' },
+  { code: 'jargon_feeds_epics', pattern: /\bfeeds_epics\b/ui, hint: '«питает эпики» или «связан с эпиком»' },
+  { code: 'jargon_track_letter', pattern: /\bTrack [A-D]\b/ui, hint: 'нумерованные шаги по-русски' },
+  { code: 'jargon_rationale', pattern: /\brationale\b/ui, hint: '«обоснование»' },
+  { code: 'jargon_published', pattern: /\bpublished\b/ui, hint: '«опубликован»' },
+  { code: 'jargon_scope_drift', pattern: /\bscope drift\b/ui, hint: '«размывание границ»' },
+  { code: 'jargon_actionable', pattern: /\bactionable\b/ui, hint: '«можно брать в работу»' },
+  { code: 'jargon_outcomes', pattern: /\bOutcomes\b/ui, hint: '«результаты»' },
+  { code: 'template_stoit_zavesti', pattern: /Стоит завести «/u, hint: 'пиши Зачем:, не шаблон create_work_item' },
+  { code: 'template_tselesoobraznost', pattern: /Целесообразность:/u, hint: 'используй Зачем: / Когда: / Риск:' },
+  { code: 'template_depends_on_eq', pattern: /depends_on=/u, hint: '«зависит от: …» по-русски' },
+  { code: 'template_upstream_deps', pattern: /upstream-зависимостей/u, hint: '«зависимостей выше по цепочке»' },
+  { code: 'template_intake_razbor', pattern: /разбор материалов приёма/u, hint: 'конкретная формулировка вместо шаблона' },
+  { code: 'jargon_doc_published', pattern: /\bdoc published\b/ui, hint: '«документ опубликован»' },
+  { code: 'jargon_epic_closed', pattern: /\bepic closed with evidence\b/ui, hint: '«эпик закрыт, свидетельства приложены»' },
+  { code: 'jargon_journal_entry', pattern: /\bjournal entry\b/ui, hint: '«запись в журнале»' },
+  { code: 'jargon_closing_entry', pattern: /\bclosing entry\b/ui, hint: '«итоговая запись»' },
+  { code: 'title_an_closing_epic', pattern: /AN-\d+\s+closing:/ui, hint: '«Закрыть разбор AN-n после эпика …»' },
+];
+
+const TITLE_ENGLISH_LEAD = /^(?:UI|CLI|ADR|Runbook|Tests?|Implement|Write|Decide|Docs|Track)\b/u;
+
+function proseBlob(item) {
+  const parts = [];
+  for (const field of PROSE_FIELDS) {
+    parts.push(...sectionToLines(item[field]));
+  }
+  const title = String(item.title ?? item.labels?.['work.title'] ?? '').trim();
+  if (title) {
+    parts.push(title);
+  }
+  return parts.join('\n');
+}
+
+function sectionToLines(value) {
+  if (Array.isArray(value)) {
+    return value.map((line) => String(line).trim()).filter(Boolean);
+  }
+  return String(value ?? '')
+    .split(/\n+/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function checkLines(field, lines, workId, issues) {
+  const normalized = sectionToLines(lines);
+
+  if (field === 'checks' && normalized.length > 0 && normalized.length < 2) {
+    issues.push({
+      severity: 'warning',
+      code: 'short_checks_count',
+      message: `Проверки для ${workId}: нужно минимум 2 пункта, сейчас ${normalized.length}`,
+      workId,
+      field,
+    });
+  }
+
+  for (const line of normalized) {
+    if (field === 'checks' && line.length > 0 && line.length < 20) {
+      issues.push({
+        severity: 'warning',
+        code: 'short_check_line',
+        message: `Проверки для ${workId}: пункт слишком короткий (${line.length} симв.): «${line.slice(0, 40)}»`,
+        workId,
+        field,
+      });
+    }
+  }
+}
+
+/**
+ * @param {{ id?: string, title?: string, basis?: string[], vector?: string[], goal?: string[], checks?: string[], analysis?: string[], decision?: string[], labels?: Record<string, string> }} item
+ */
+export function evaluateWorkItemProseLint(item) {
+  const issues = [];
+  const workId = item.id ?? item.labels?.['work.id'] ?? '';
+
+  for (const field of PROSE_FIELDS) {
+    checkLines(field, item[field], workId, issues);
+  }
+
+  const title = String(item.title ?? item.labels?.['work.title'] ?? '').trim();
+  if (TITLE_ENGLISH_LEAD.test(title)) {
+    issues.push({
+      severity: 'warning',
+      code: 'english_lead_title',
+      message: `work.title для ${workId} начинается с английского шаблона: «${title}»`,
+      workId,
+      field: 'title',
+    });
+  }
+
+  for (const { code, pattern, hint } of WORK_ITEM_JARGON_PATTERNS) {
+    if (code.startsWith('title_') && title !== '' && pattern.test(title)) {
+      issues.push({
+        severity: 'warning',
+        code: `work_item_prose_jargon_${code}`,
+        message: `work.title для ${workId}: ${hint}`,
+        workId,
+        field: 'title',
+      });
+    }
+  }
+
+  const blob = proseBlob(item);
+  for (const { code, pattern, hint } of WORK_ITEM_JARGON_PATTERNS) {
+    if (code.startsWith('title_')) {
+      continue;
+    }
+    if (pattern.test(blob)) {
+      issues.push({
+        severity: 'warning',
+        code: `work_item_prose_jargon_${code}`,
+        message: `Робототекст/жаргон в ${workId}: ${hint} (pattern ${code})`,
+        workId,
+        field: 'prose',
+      });
+    }
+  }
+
+  return issues;
+}