@work-graph/cli 0.2.0

package/vendor/src/unifiedLinkageProjection.mjs

@@ -0,0 +1,264 @@
+import { parseTraceLinksV1, scanReverseTraceMarkers } from './workGraphRuntime.mjs';
+import { buildWorkItemTraceEnvelope } from './workItemTraceEnvelope.mjs';
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+const DEFAULT_MAX_LINKS = 48;
+const DEFAULT_MAX_REFS = 64;
+
+function inferLinkageRefKind(ref, sourceLabel = '') {
+  const value = String(ref ?? '').trim();
+  if (value === '') {
+    return 'file';
+  }
+
+  if (sourceLabel === 'trace.source_step' || sourceLabel === 'work.source_step' || /\.bvc$/u.test(value)) {
+    return 'step';
+  }
+
+  if (value.startsWith('work:')) {
+    return 'work';
+  }
+
+  return 'file';
+}
+
+function pushLinkageRef(refs, seen, entry) {
+  const ref = String(entry.ref ?? '').trim();
+  if (ref === '') {
+    return;
+  }
+
+  const key = `${entry.kind}\0${ref}\0${entry.source ?? ''}`;
+  if (seen.has(key)) {
+    return;
+  }
+
+  seen.add(key);
+  refs.push({
+    kind: entry.kind,
+    ref,
+    label: entry.label ?? ref,
+    source: entry.source ?? '',
+    relation: entry.relation ?? '',
+  });
+}
+
+export function buildWorkItemLinkageDrilldown(workId, items, options = {}) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('items must be an array');
+  }
+
+  const normalizedWorkId = String(workId ?? '').trim();
+  if (normalizedWorkId === '') {
+    throw new TypeError('workId is required');
+  }
+
+  const itemById = new Map(items.map((item) => [item.id, item]));
+  const task = itemById.get(normalizedWorkId);
+  if (task === undefined) {
+    throw new Error(`unknown task id: ${normalizedWorkId}`);
+  }
+
+  const maxLinks = Number.isInteger(options.maxLinks) && options.maxLinks > 0
+    ? options.maxLinks
+    : DEFAULT_MAX_LINKS;
+  const maxRefs = Number.isInteger(options.maxRefs) && options.maxRefs > 0
+    ? options.maxRefs
+    : DEFAULT_MAX_REFS;
+
+  const linkage = options.linkage ?? buildUnifiedLinkageProjectionV1(items, options);
+  const envelope = buildWorkItemTraceEnvelope(task);
+  const links = linkage.links.filter((link) =>
+    link.sourceWorkId === normalizedWorkId
+    || (link.from.kind === 'work' && link.from.id === normalizedWorkId)
+    || (link.to.kind === 'work' && link.to.id === normalizedWorkId),
+  );
+
+  const refs = [];
+  const seen = new Set();
+
+  for (const path of envelope.targetFiles) {
+    pushLinkageRef(refs, seen, {
+      kind: 'file',
+      ref: path,
+      label: path,
+      source: 'work.target_files',
+      relation: 'targets',
+    });
+  }
+
+  if (envelope.sourceStep !== '') {
+    pushLinkageRef(refs, seen, {
+      kind: 'step',
+      ref: envelope.sourceStep,
+      label: envelope.sourceStep,
+      source: 'trace.source_step',
+      relation: 'references',
+    });
+  }
+
+  for (const [labelKey, values] of Object.entries(envelope.traceRefs)) {
+    for (const value of values) {
+      pushLinkageRef(refs, seen, {
+        kind: inferLinkageRefKind(value, labelKey),
+        ref: value,
+        label: value,
+        source: labelKey,
+        relation: 'references',
+      });
+    }
+  }
+
+  for (const link of links) {
+    if (link.to.kind === 'work' && link.to.id !== normalizedWorkId && itemById.has(link.to.id)) {
+      const related = itemById.get(link.to.id);
+      pushLinkageRef(refs, seen, {
+        kind: 'work',
+        ref: link.to.id,
+        label: related?.title ? `${related.title} (${link.to.id})` : link.to.id,
+        source: link.sourceLabel ?? link.relation,
+        relation: link.relation,
+      });
+    }
+
+    if (link.to.kind === 'file') {
+      const fileRef = link.to.locator?.path ?? link.to.id;
+      pushLinkageRef(refs, seen, {
+        kind: 'file',
+        ref: fileRef,
+        label: fileRef,
+        source: link.sourceLabel ?? link.relation,
+        relation: link.relation,
+      });
+    }
+
+    if (link.from.kind === 'work' && link.from.id !== normalizedWorkId && itemById.has(link.from.id)) {
+      const related = itemById.get(link.from.id);
+      pushLinkageRef(refs, seen, {
+        kind: 'work',
+        ref: link.from.id,
+        label: related?.title ? `${related.title} (${link.from.id})` : link.from.id,
+        source: link.sourceLabel ?? link.relation,
+        relation: link.relation,
+      });
+    }
+  }
+
+  for (const marker of linkage.markers ?? []) {
+    if (marker.endpoint?.kind === 'work' && marker.endpoint.id === normalizedWorkId) {
+      pushLinkageRef(refs, seen, {
+        kind: 'file',
+        ref: `${marker.sourcePath}:${marker.line}`,
+        label: `${marker.sourcePath}:${marker.line}`,
+        source: 'reverse_marker',
+        relation: 'references',
+      });
+    }
+  }
+
+  const sortedRefs = refs
+    .sort((left, right) => compareText(`${left.kind}\0${left.ref}`, `${right.kind}\0${right.ref}`))
+    .slice(0, maxRefs);
+  const sortedLinks = links
+    .sort((left, right) => compareText(left.id, right.id))
+    .slice(0, maxLinks);
+
+  return {
+    schema: 'workgraph.work-item-linkage-drilldown.v1',
+    workId: normalizedWorkId,
+    envelope,
+    linkCount: sortedLinks.length,
+    refCount: sortedRefs.length,
+    truncated: links.length > sortedLinks.length || refs.length > sortedRefs.length,
+    links: sortedLinks,
+    refs: sortedRefs,
+  };
+}
+
+export function buildUnifiedLinkageProjectionV1(items, options = {}) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('items must be an array');
+  }
+
+  const traceLinks = (options.traceLinks ?? parseTraceLinksV1(items)).map((link) => ({
+    id: link.id,
+    from: link.from,
+    to: link.to,
+    relation: link.relation,
+    evidence: [...(link.evidence ?? [])].sort(compareText),
+    status: link.status,
+    source: link.source,
+    confidence: link.confidence,
+    sourceWorkId: link.sourceWorkId,
+    sourceLabel: link.sourceLabel,
+    sourceRef: link.sourceRef,
+  }));
+
+  const reverseMarkers = (options.reverseMarkers ?? scanReverseTraceMarkers(options.fileContentsByPath ?? {})).map((marker) => ({
+    ref: marker.ref,
+    endpoint: marker.endpoint,
+    sourcePath: marker.sourcePath,
+    line: marker.line,
+  }));
+
+  const planningEdges = items.flatMap((item) => {
+    const targetEdges = (item.targetFiles ?? []).map((path) => ({
+      id: `plan:${item.id}:targets:${path}`,
+      from: { kind: 'work', id: item.id },
+      to: { kind: 'file', id: path, locator: { path } },
+      relation: 'targets',
+      evidence: [],
+      status: 'pending',
+      source: 'derived_projection',
+      confidence: 'low',
+      sourceWorkId: item.id,
+      sourceLabel: 'work.target_files',
+      sourceRef: path,
+    }));
+
+    const dependencyEdges = (item.dependsOn ?? []).map((dependencyId) => ({
+      id: `plan:${item.id}:depends_on:${dependencyId}`,
+      from: { kind: 'work', id: item.id },
+      to: { kind: 'work', id: dependencyId },
+      relation: 'depends_on',
+      evidence: [],
+      status: 'linked',
+      source: 'derived_projection',
+      confidence: 'high',
+      sourceWorkId: item.id,
+      sourceLabel: 'work.depends_on',
+      sourceRef: dependencyId,
+    }));
+
+    const parentId = String(item.parentId ?? item.labels?.['work.parent_id'] ?? '').trim();
+    const parentEdges = parentId === '' ? [] : [{
+      id: `plan:${item.id}:parent_of:${parentId}`,
+      from: { kind: 'work', id: parentId },
+      to: { kind: 'work', id: item.id },
+      relation: 'parent_of',
+      evidence: [],
+      status: 'linked',
+      source: 'derived_projection',
+      confidence: 'high',
+      sourceWorkId: item.id,
+      sourceLabel: 'work.parent_id',
+      sourceRef: parentId,
+    }];
+
+    return [...targetEdges, ...dependencyEdges, ...parentEdges];
+  });
+
+  const links = [...traceLinks, ...planningEdges].sort((left, right) => compareText(left.id, right.id));
+  const markers = [...reverseMarkers].sort((left, right) => compareText(`${left.sourcePath}\0${left.line}\0${left.ref}`, `${right.sourcePath}\0${right.line}\0${right.ref}`));
+
+  return {
+    schema: 'unified-linkage.projection.v1',
+    generatedFrom: options.generatedFrom ?? 'workgraph.snapshot.v1',
+    generatedAt: options.generatedAt ?? null,
+    linkCount: links.length,
+    markerCount: markers.length,
+    links,
+    markers,
+    consumers: ['architectureSnapshot', 'verificationLoop', 'pvrgTaskScope', 'backlogUiDerivedGraph'],
+  };
+}

package/vendor/src/verificationLoop.mjs

@@ -0,0 +1,206 @@
+import { buildCodegenVerificationGate } from './codegenEvidence.mjs';
+
+/** @typedef {'deterministic' | 'optional-env' | 'optional-llm'} VerificationTier */
+/** @typedef {'passed' | 'pending' | 'blocked' | 'not_run' | 'failed'} VerificationStatus */
+
+/** @type {Array<{ id: string, tier: VerificationTier, title: string, command: string, gateTaskIds: string[], evidenceHints: string[] }>} */
+export const VERIFICATION_MATRIX = [
+  {
+    id: 'formatter-roundtrip',
+    tier: 'deterministic',
+    title: 'Roundtrip форматтера Step Atom',
+    command: 'npm run test:deterministic',
+    gateTaskIds: ['implement-step-atom-formatter'],
+    evidenceHints: ['formatter', 'roundtrip', 'npm test'],
+  },
+  {
+    id: 'workgraph-runtime',
+    tier: 'deterministic',
+    title: 'Политика runtime Work Graph',
+    command: 'npm run test:deterministic',
+    gateTaskIds: ['implement-workgraph-minimal-runtime'],
+    evidenceHints: ['claimNext', 'transitionStatus', 'npm test'],
+  },
+  {
+    id: 'trace-links-v1',
+    tier: 'deterministic',
+    title: 'Валидатор Trace Links v1',
+    command: 'npm run test:deterministic',
+    gateTaskIds: ['implement-step-code-trace-link-validator'],
+    evidenceHints: ['Trace Links', 'validateTraceLinksV1', 'npm test'],
+  },
+  {
+    id: 'ui-server-smoke',
+    tier: 'deterministic',
+    title: 'Smoke UI-сервера backlog',
+    command: 'npm run test:deterministic',
+    gateTaskIds: ['implement-workgraph-minimal-runtime', 'implement-schematic-visualization-view-mvp'],
+    evidenceHints: ['workGraphBacklogUiServer', 'renderBacklogHtml', 'npm test'],
+  },
+  {
+    id: 'golden-path-runtime',
+    tier: 'deterministic',
+    title: 'Сценарий golden path runtime',
+    command: 'npm run test:deterministic',
+    gateTaskIds: ['golden-path-test'],
+    evidenceHints: ['goldenPath', 'runDeterministicGoldenPath', 'npm test'],
+  },
+  {
+    id: 'onebase-gross-profit-static',
+    tier: 'deterministic',
+    title: 'OneBase: статическая проверка артефакта валовой прибыли',
+    command: 'npm run test:deterministic',
+    gateTaskIds: ['onebase-implement-gross-profit-warehouse-dimension'],
+    evidenceHints: ['verifyOnebaseGrossProfitWarehouseArtifacts', 'валовая_прибыль', 'ДвВП.Склад'],
+  },
+  {
+    id: 'onebase-go-test',
+    tier: 'optional-env',
+    title: 'OneBase golden path (go test)',
+    command: 'npm run test:optional:onebase',
+    gateTaskIds: ['onebase-verification-command', 'onebase-implement-gross-profit-warehouse-dimension'],
+    evidenceHints: ['go test', 'go version', 'CommandNotFoundException', 'blocked evidence'],
+  },
+  {
+    id: 'onebase-config-check',
+    tier: 'optional-env',
+    title: 'OneBase config check (CLI)',
+    command: 'npm run test:optional:onebase-check',
+    gateTaskIds: ['wire-onebase-cli-tools-parity', 'implement-onebase-check-verification-gate'],
+    evidenceHints: ['onebase check', 'config-check', 'cli_command_unavailable', 'skipped'],
+  },
+  {
+    id: 'lowcode-arch-scaffold',
+    tier: 'optional-env',
+    title: 'Low-code: verify scaffold arch-rules',
+    command: 'npm run verify:lowcode',
+    gateTaskIds: ['implement-lowcode-scaffold-cli-mvp'],
+    evidenceHints: ['scaffold:arch-rules', 'arch-rules.bvc', 'manifest.json'],
+  },
+  {
+    id: 'onebase-llm-scenario',
+    tier: 'optional-llm',
+    title: 'OneBase: сценарий с реальной LLM',
+    command: 'вручную / будущий optional eval',
+    gateTaskIds: ['onebase-posting-rule-golden-path'],
+    evidenceHints: ['real LLM', 'tool-call', 'optional'],
+  },
+];
+
+/**
+ * @param {{ items?: Array<{ id: string, status: string, evidence?: string[], blocker?: string, title?: string, nextAction?: string }> }} workGraphSnapshot
+ */
+export function buildVerificationSummary(workGraphSnapshot, options = {}) {
+  const items = Array.isArray(options.items) ? options.items : (workGraphSnapshot?.items ?? []);
+  const itemById = new Map(items.map((item) => [item.id, item]));
+
+  const matrix = VERIFICATION_MATRIX.map((row) => ({
+    ...row,
+    status: deriveMatrixRowStatus(row, itemById),
+    gateTasks: row.gateTaskIds.map((taskId) => summarizeGateTask(itemById.get(taskId))),
+  }));
+
+  const tierCounts = summarizeTierCounts(matrix);
+  const onebaseGate = matrix.find((row) => row.id === 'onebase-go-test') ?? null;
+  const codegenGate = buildCodegenVerificationGate(items);
+
+  return {
+    schema: 'verification.summary.v1',
+    tierCounts,
+    matrix,
+    onebaseGate: onebaseGate
+      ? {
+          status: onebaseGate.status,
+          preflightCommand: 'go version',
+          primaryCommand: 'go test ./...',
+          cwd: '../onebase',
+          blockedTaskId: items.find((item) => item.id === 'onebase-implement-gross-profit-warehouse-dimension' && item.status === 'blocked')?.id ?? null,
+        }
+      : null,
+    codegenGate,
+    policy: {
+      deterministicCommand: 'npm run test:deterministic',
+      optionalOnebaseCommand: 'npm run test:optional:onebase',
+      optionalOnebaseCheckCommand: 'npm run test:optional:onebase-check',
+      protocolPath: 'protocols/rebuild-verification-loop.bvc',
+    },
+  };
+}
+
+/**
+ * @param {typeof VERIFICATION_MATRIX[number]} row
+ * @param {Map<string, object>} itemById
+ * @returns {VerificationStatus}
+ */
+function deriveMatrixRowStatus(row, itemById) {
+  const gateTasks = row.gateTaskIds.map((id) => itemById.get(id)).filter(Boolean);
+  if (gateTasks.length === 0) return 'pending';
+
+  if (row.tier === 'optional-llm') {
+    return gateTasks.some((task) => task.status === 'done' && hasEvidenceMatch(task, row.evidenceHints))
+      ? 'passed'
+      : 'not_run';
+  }
+
+  if (row.tier === 'optional-env') {
+    const blocked = gateTasks.find((task) => task.status === 'blocked');
+    if (blocked && mentionsAny(blocked, ['go', 'PATH', 'CommandNotFound', 'blocked evidence'])) {
+      return 'blocked';
+    }
+    if (gateTasks.some((task) => task.status === 'done' && hasEvidenceMatch(task, row.evidenceHints))) {
+      return 'passed';
+    }
+    return gateTasks.some((task) => task.status === 'done') ? 'pending' : 'not_run';
+  }
+
+  const allDone = row.gateTaskIds.every((taskId) => {
+    const task = itemById.get(taskId);
+    return task && ['done', 'verified'].includes(task.status);
+  });
+  if (!allDone) return 'pending';
+
+  const evidenceOk = gateTasks.some((task) => hasEvidenceMatch(task, row.evidenceHints) || (task.evidence || []).length > 0);
+  return evidenceOk ? 'passed' : 'pending';
+}
+
+/** @param {object | undefined} task */
+function summarizeGateTask(task) {
+  if (!task) {
+    return { id: null, status: 'missing', evidenceCount: 0 };
+  }
+  return {
+    id: task.id,
+    status: task.status,
+    title: task.title,
+    evidenceCount: (task.evidence || []).length,
+  };
+}
+
+/** @param {object} task @param {string[]} hints */
+function hasEvidenceMatch(task, hints) {
+  const haystack = [(task.evidence || []).join('\n'), task.blocker, task.nextAction].filter(Boolean).join('\n').toLowerCase();
+  return hints.some((hint) => haystack.includes(hint.toLowerCase()));
+}
+
+/** @param {object} task @param {string[]} needles */
+function mentionsAny(task, needles) {
+  const haystack = [(task.evidence || []).join('\n'), task.blocker, task.nextAction, task.title].filter(Boolean).join('\n').toLowerCase();
+  return needles.some((needle) => haystack.includes(needle.toLowerCase()));
+}
+
+/** @param {Array<{ tier: VerificationTier, status: VerificationStatus }>} matrix */
+function summarizeTierCounts(matrix) {
+  const countTier = (tier) => ({
+    passed: matrix.filter((row) => row.tier === tier && row.status === 'passed').length,
+    pending: matrix.filter((row) => row.tier === tier && row.status === 'pending').length,
+    blocked: matrix.filter((row) => row.tier === tier && row.status === 'blocked').length,
+    notRun: matrix.filter((row) => row.tier === tier && row.status === 'not_run').length,
+    total: matrix.filter((row) => row.tier === tier).length,
+  });
+
+  return {
+    deterministic: countTier('deterministic'),
+    optionalEnv: countTier('optional-env'),
+    optionalLlm: countTier('optional-llm'),
+  };
+}

package/vendor/src/workGraphBacklogPersist.mjs

@@ -0,0 +1,234 @@
+import { readFile, rename, writeFile } from 'node:fs/promises';
+
+const STEP_ATOM_PATTERN = /^#([^\n<]+)<\[\n([\s\S]*?)\n\]>/gmu;
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function findWorkItemAtomSpan(backlogText, workId) {
+  if (typeof backlogText !== 'string') {
+    throw new TypeError('backlogText must be a string');
+  }
+
+  const normalizedWorkId = String(workId ?? '').trim();
+  if (normalizedWorkId === '') {
+    throw new TypeError('workId must be a non-empty string');
+  }
+
+  for (const match of backlogText.matchAll(STEP_ATOM_PATTERN)) {
+    const body = match[2];
+    const idMatch = body.match(/^\s*work\.id:\s*(.+)$/m);
+    if (idMatch?.[1]?.trim() === normalizedWorkId) {
+      return {
+        start: match.index,
+        end: match.index + match[0].length,
+        atomName: match[1],
+        body,
+        fullMatch: match[0],
+      };
+    }
+  }
+
+  return null;
+}
+
+function upsertLabelLine(body, key, value) {
+  const pattern = new RegExp(`^(\\s*)${escapeRegex(key)}:\\s*.+$`, 'm');
+  const line = `  ${key}: ${value}`;
+
+  if (pattern.test(body)) {
+    return body.replace(pattern, line);
+  }
+
+  const labelsMatch = body.match(/^(\s*)Метки:\s*$/m);
+  if (labelsMatch) {
+    const insertAt = labelsMatch.index + labelsMatch[0].length;
+    return `${body.slice(0, insertAt)}\n${line}${body.slice(insertAt)}`;
+  }
+
+  return `${body.trimEnd()}\n\nМетки:\n${line}`;
+}
+
+function removeLabelLine(body, key) {
+  const pattern = new RegExp(`^\\s*${escapeRegex(key)}:\\s*.+\\n?`, 'm');
+  return body.replace(pattern, '');
+}
+
+function parseEvidenceLinesFromBody(body) {
+  const lines = [];
+  let inEvidence = false;
+
+  for (const rawLine of body.split(/\r?\n/u)) {
+    const trimmed = rawLine.trim();
+
+    if (trimmed === 'Свидетельства:') {
+      inEvidence = true;
+      continue;
+    }
+
+    if (!inEvidence) {
+      continue;
+    }
+
+    if (trimmed === '') {
+      continue;
+    }
+
+    if (/^[A-Za-zА-Яа-яЁё_]+:$/u.test(trimmed) && trimmed !== 'критерии_готовности:') {
+      inEvidence = false;
+      continue;
+    }
+
+    if (/^-\s*/u.test(trimmed) || rawLine.startsWith('  ')) {
+      lines.push(trimmed.replace(/^-\s*/u, '').trim());
+      continue;
+    }
+
+    inEvidence = false;
+  }
+
+  return lines;
+}
+
+function appendEvidenceLines(body, newLines) {
+  const existing = new Set(parseEvidenceLinesFromBody(body));
+  const toAdd = newLines
+    .map((line) => String(line ?? '').trim())
+    .filter((line) => line !== '' && !existing.has(line));
+
+  if (toAdd.length === 0) {
+    return body;
+  }
+
+  const formatted = toAdd.map((line) => `  - ${line}`);
+  const evidenceHeader = body.match(/^(\s*)Свидетельства:\s*$/m);
+
+  if (!evidenceHeader) {
+    return `${body.trimEnd()}\n\nСвидетельства:\n${formatted.join('\n')}`;
+  }
+
+  const bodyLines = body.split(/\r?\n/u);
+  let evidenceStartIdx = -1;
+  let insertIdx = -1;
+
+  for (let index = 0; index < bodyLines.length; index += 1) {
+    if (bodyLines[index].trim() === 'Свидетельства:') {
+      evidenceStartIdx = index;
+      insertIdx = index + 1;
+      continue;
+    }
+
+    if (evidenceStartIdx < 0 || index <= evidenceStartIdx) {
+      continue;
+    }
+
+    const trimmed = bodyLines[index].trim();
+    if (trimmed === '') {
+      continue;
+    }
+
+    if (/^[A-Za-zА-Яа-яЁё_]+:$/u.test(trimmed) && trimmed !== 'критерии_готовности:') {
+      break;
+    }
+
+    if (/^-\s*/u.test(trimmed) || bodyLines[index].startsWith('  ')) {
+      insertIdx = index + 1;
+      continue;
+    }
+
+    break;
+  }
+
+  bodyLines.splice(insertIdx, 0, ...formatted);
+  return bodyLines.join('\n');
+}
+
+export function patchWorkItemAtomBody(body, item) {
+  if (!item || typeof item !== 'object') {
+    throw new TypeError('item must be an object');
+  }
+
+  let next = upsertLabelLine(body, 'work.status', item.status);
+
+  if (item.status === 'blocked' && item.blocker) {
+    next = upsertLabelLine(next, 'work.blocker', item.blocker);
+  } else {
+    next = removeLabelLine(next, 'work.blocker');
+    next = removeLabelLine(next, 'work.blocked_reason');
+  }
+
+  if (Array.isArray(item.evidence) && item.evidence.length > 0) {
+    next = appendEvidenceLines(next, item.evidence);
+  }
+
+  const activeClaimStatuses = new Set(['claimed', 'doing', 'in_progress']);
+  if (activeClaimStatuses.has(item.status)) {
+    const claimedBy = String(item.labels?.['work.claimed_by'] ?? '').trim();
+    const leaseUntil = String(item.labels?.['work.claim_lease_until'] ?? '').trim();
+    if (claimedBy !== '') {
+      next = upsertLabelLine(next, 'work.claimed_by', claimedBy);
+    }
+    if (leaseUntil !== '') {
+      next = upsertLabelLine(next, 'work.claim_lease_until', leaseUntil);
+    }
+  } else {
+    next = removeLabelLine(next, 'work.claimed_by');
+    next = removeLabelLine(next, 'work.claim_lease_until');
+  }
+
+  return next;
+}
+
+export function patchWorkItemInBacklogText(backlogText, item) {
+  const span = findWorkItemAtomSpan(backlogText, item.id);
+  if (!span) {
+    throw new Error(`work item atom not found: ${item.id}`);
+  }
+
+  const patchedBody = patchWorkItemAtomBody(span.body, item);
+  const patchedAtom = `#${span.atomName}<[\n${patchedBody}\n]>`;
+  return `${backlogText.slice(0, span.start)}${patchedAtom}${backlogText.slice(span.end)}`;
+}
+
+export async function writeBacklogTextAtomically(backlogPath, backlogText) {
+  const tempPath = `${backlogPath}.tmp`;
+  await writeFile(tempPath, backlogText, 'utf8');
+  await rename(tempPath, backlogPath);
+}
+
+export function appendWorkItemAtomToBacklogText(backlogText, atomText) {
+  if (typeof backlogText !== 'string') {
+    throw new TypeError('backlogText must be a string');
+  }
+
+  const atom = String(atomText ?? '').trim();
+  if (atom === '') {
+    throw new TypeError('atomText must be a non-empty string');
+  }
+
+  const trimmedBacklog = backlogText.trimEnd();
+  return `${trimmedBacklog}\n\n${atom}\n`;
+}
+
+export async function persistWorkItemUpdateToBacklogFile(options = {}) {
+  const backlogPath = options.backlogPath;
+  if (!backlogPath) {
+    throw new TypeError('backlogPath is required');
+  }
+
+  const item = options.item;
+  if (!item?.id) {
+    throw new TypeError('item.id is required');
+  }
+
+  const sourceText = options.backlogText ?? await readFile(backlogPath, 'utf8');
+  const newText = patchWorkItemInBacklogText(sourceText, item);
+  await writeBacklogTextAtomically(backlogPath, newText);
+
+  return {
+    path: backlogPath,
+    workId: item.id,
+    status: item.status,
+  };
+}