@work-graph/cli 0.2.0

package/vendor/src/memoryRecordWriter.mjs

@@ -0,0 +1,243 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+export const MEMORY_RECORD_JOURNAL_SCHEMA = 'memory-record.journal.v1';
+export const MEMORY_RECORD_JOURNAL_APPEND_SCHEMA = 'memory-record.journal.append.v1';
+export const MEMORY_RECORD_JOURNAL_READ_SCHEMA = 'memory-record.journal.read.v1';
+export const DEFAULT_MEMORY_RECORD_JOURNAL_PATH = 'work/memory-records.jsonl';
+
+const POLICY_ALLOWED_TRANSITION_STATUSES = new Set(['done', 'verified']);
+
+function stableMemoryId(sourceWorkItem, type, summary) {
+  const slug = String(summary ?? '').toLowerCase().replace(/[^a-z0-9]+/gu, '-').slice(0, 32);
+  return `mem:${sourceWorkItem}:${type}:${slug || 'record'}`;
+}
+
+function inferMemoryType(item) {
+  const searchable = `${item.title} ${item.goal} ${item.vector}`.toLowerCase();
+  if (/risk|риск/u.test(searchable)) {
+    return 'risk';
+  }
+
+  if (/invariant|инвариант/u.test(searchable)) {
+    return 'invariant';
+  }
+
+  if (/decision|решени/u.test(searchable)) {
+    return 'decision';
+  }
+
+  if (/architecture|архитектур/u.test(searchable)) {
+    return 'architecture-fact';
+  }
+
+  return 'evidence-summary';
+}
+
+export function buildMemoryRecordFromWorkItem(item, options = {}) {
+  if (item === undefined || item === null) {
+    throw new TypeError('item is required');
+  }
+
+  const type = options.type ?? inferMemoryType(item);
+  const summary = options.summary ?? (item.goal || item.title || item.id);
+  const status = options.status ?? (options.reviewRequired === false ? 'active' : 'draft');
+  const evidenceIds = (item.evidence ?? []).map((_, index) => `${item.id}:legacy-evidence:${index + 1}`);
+
+  return {
+    schema: 'memory-record.v1',
+    id: options.id ?? stableMemoryId(item.id, type, summary),
+    type,
+    summary: String(summary).trim(),
+    sourceWorkItem: item.id,
+    confidence: options.confidence ?? 'medium',
+    status,
+    updatedAt: options.updatedAt ?? null,
+    basisLink: item.basis ? `work:${item.id}:basis` : '',
+    vectorLink: item.vector ? `work:${item.id}:vector` : '',
+    goalLink: item.goal ? `work:${item.id}:goal` : '',
+    evidenceIds: [...evidenceIds].sort(compareText),
+    relatedFiles: [...(item.targetFiles ?? [])].sort(compareText),
+    relatedTasks: [...(item.dependsOn ?? [])].sort(compareText),
+    reviewRequired: status === 'draft' || status === 'needs-review',
+    dedupKey: `${item.id}\0${type}\0${summary}`,
+  };
+}
+
+export function buildMemoryRecordCandidatesFromItems(items, options = {}) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('items must be an array');
+  }
+
+  const doneStatuses = new Set(['done', 'verified']);
+  const candidates = items
+    .filter((item) => doneStatuses.has(item.status))
+    .map((item) => buildMemoryRecordFromWorkItem(item, options))
+    .sort((left, right) => compareText(left.id, right.id));
+
+  const seen = new Set();
+  const deduped = [];
+  for (const record of candidates) {
+    if (seen.has(record.dedupKey)) {
+      continue;
+    }
+
+    seen.add(record.dedupKey);
+    deduped.push(record);
+  }
+
+  return {
+    schema: 'memory-record.candidates.v1',
+    count: deduped.length,
+    reviewRequired: true,
+    records: deduped,
+  };
+}
+
+export function validateMemoryJournalTransition(transition) {
+  if (!transition || typeof transition !== 'object') {
+    throw new TypeError('transition is required for memory journal append');
+  }
+
+  const { kind, sourceWorkItem, toStatus } = transition;
+  if (kind !== 'work-item-status') {
+    throw new Error(`unsupported memory journal transition kind: ${String(kind)}`);
+  }
+
+  if (!sourceWorkItem) {
+    throw new TypeError('transition.sourceWorkItem is required');
+  }
+
+  if (!POLICY_ALLOWED_TRANSITION_STATUSES.has(toStatus)) {
+    throw new Error(`memory journal append blocked: transition toStatus must be done or verified, got ${String(toStatus)}`);
+  }
+
+  return true;
+}
+
+function normalizeJournalRecord(record, transition, options = {}) {
+  if (!record || record.schema !== 'memory-record.v1') {
+    throw new TypeError('each journal record must use schema memory-record.v1');
+  }
+
+  if (record.sourceWorkItem !== transition.sourceWorkItem) {
+    throw new Error(`memory journal record ${record.id} sourceWorkItem must match transition.sourceWorkItem`);
+  }
+
+  const updatedAt = options.appendedAt ?? new Date().toISOString();
+  return {
+    ...record,
+    updatedAt: record.updatedAt ?? updatedAt,
+  };
+}
+
+export function buildMemoryJournalEntry(record, transition, options = {}) {
+  validateMemoryJournalTransition(transition);
+  const appendedAt = options.appendedAt ?? new Date().toISOString();
+
+  return {
+    schema: MEMORY_RECORD_JOURNAL_SCHEMA,
+    appendedAt,
+    transition: {
+      kind: transition.kind,
+      sourceWorkItem: transition.sourceWorkItem,
+      fromStatus: transition.fromStatus ?? null,
+      toStatus: transition.toStatus,
+    },
+    record: normalizeJournalRecord(record, transition, { appendedAt }),
+  };
+}
+
+export async function readMemoryRecordJournal(options = {}) {
+  const journalPath = resolve(options.cwd ?? process.cwd(), options.journalPath ?? DEFAULT_MEMORY_RECORD_JOURNAL_PATH);
+
+  let text = '';
+  try {
+    text = await readFile(journalPath, 'utf8');
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      return {
+        schema: MEMORY_RECORD_JOURNAL_READ_SCHEMA,
+        journalPath,
+        entryCount: 0,
+        entries: [],
+        records: [],
+      };
+    }
+
+    throw error;
+  }
+
+  const entries = text
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line, index) => {
+      const parsed = JSON.parse(line);
+      if (parsed.schema !== MEMORY_RECORD_JOURNAL_SCHEMA) {
+        throw new Error(`invalid memory journal entry at line ${index + 1}: expected ${MEMORY_RECORD_JOURNAL_SCHEMA}`);
+      }
+
+      return parsed;
+    });
+
+  const latestById = new Map();
+  for (const entry of entries) {
+    latestById.set(entry.record.id, entry.record);
+  }
+
+  const records = [...latestById.values()].sort((left, right) => compareText(left.id, right.id));
+
+  return {
+    schema: MEMORY_RECORD_JOURNAL_READ_SCHEMA,
+    journalPath,
+    entryCount: entries.length,
+    entries,
+    records,
+  };
+}
+
+export function mergeMemoryJournalWithCandidates(candidates, journalRecords) {
+  const candidateList = Array.isArray(candidates) ? candidates : [];
+  const journalList = Array.isArray(journalRecords) ? journalRecords : [];
+  const merged = new Map();
+
+  for (const record of candidateList) {
+    merged.set(record.id, record);
+  }
+
+  for (const record of journalList) {
+    merged.set(record.id, record);
+  }
+
+  return [...merged.values()].sort((left, right) => compareText(left.id, right.id));
+}
+
+export async function appendMemoryRecordJournal(records, journalPath, options = {}) {
+  if (!Array.isArray(records) || records.length === 0) {
+    throw new TypeError('records must be a non-empty array');
+  }
+
+  validateMemoryJournalTransition(options.transition);
+
+  const resolvedPath = resolve(options.cwd ?? process.cwd(), journalPath ?? DEFAULT_MEMORY_RECORD_JOURNAL_PATH);
+  const appendedAt = options.appendedAt ?? new Date().toISOString();
+  const entries = records.map((record) => buildMemoryJournalEntry(record, options.transition, { appendedAt }));
+
+  if (options.dryRun !== true) {
+    await mkdir(dirname(resolvedPath), { recursive: true });
+    for (const entry of entries) {
+      await appendFile(resolvedPath, `${JSON.stringify(entry)}\n`, 'utf8');
+    }
+  }
+
+  return {
+    schema: MEMORY_RECORD_JOURNAL_APPEND_SCHEMA,
+    journalPath: resolvedPath,
+    appended: entries.length,
+    entries,
+    records: entries.map((entry) => entry.record),
+  };
+}

package/vendor/src/memoryWorkerSlice.mjs

@@ -0,0 +1,238 @@
+import {
+  buildMemoryRecordCandidatesFromItems,
+  mergeMemoryJournalWithCandidates,
+  readMemoryRecordJournal,
+} from './memoryRecordWriter.mjs';
+
+export const MEMORY_WORKER_SLICE_SCHEMA = 'memory-record.worker-slice.v1';
+
+const TYPE_PRIORITY = [
+  'invariant',
+  'decision',
+  'architecture-fact',
+  'domain-fact',
+  'evidence-summary',
+  'risk',
+  'open-question',
+  'provider-capability',
+  'user-preference',
+];
+
+const DEFAULT_MAX_RECORDS = 12;
+const DEFAULT_MAX_CHARS = 4000;
+const DEFAULT_MAX_RELATED_FILES = 8;
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+function typePriorityIndex(type) {
+  const index = TYPE_PRIORITY.indexOf(type);
+  return index === -1 ? TYPE_PRIORITY.length : index;
+}
+
+function statusPriority(status) {
+  if (status === 'active') {
+    return 0;
+  }
+
+  if (status === 'needs-review') {
+    return 1;
+  }
+
+  if (status === 'draft') {
+    return 2;
+  }
+
+  return 3;
+}
+
+function isRecordRelevant(record, task, itemById) {
+  if (record.sourceWorkItem === task.id) {
+    return true;
+  }
+
+  if (record.relatedTasks?.includes(task.id)) {
+    return true;
+  }
+
+  const targetFiles = new Set(task.targetFiles ?? []);
+  if (record.relatedFiles?.some((path) => targetFiles.has(path))) {
+    return true;
+  }
+
+  for (const dependencyId of task.dependsOn ?? []) {
+    if (record.sourceWorkItem === dependencyId) {
+      return true;
+    }
+
+    const dependency = itemById.get(dependencyId);
+    if (dependency?.dependsOn?.includes(record.sourceWorkItem)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function sortRecords(records) {
+  return [...records].sort((left, right) => {
+    const byType = typePriorityIndex(left.type) - typePriorityIndex(right.type);
+    if (byType !== 0) {
+      return byType;
+    }
+
+    const byStatus = statusPriority(left.status) - statusPriority(right.status);
+    if (byStatus !== 0) {
+      return byStatus;
+    }
+
+    return compareText(left.id, right.id);
+  });
+}
+
+function applyBudget(records, options = {}) {
+  const maxRecords = Number.isInteger(options.maxRecords) && options.maxRecords > 0
+    ? options.maxRecords
+    : DEFAULT_MAX_RECORDS;
+  const maxChars = Number.isInteger(options.maxChars) && options.maxChars > 0
+    ? options.maxChars
+    : DEFAULT_MAX_CHARS;
+  const maxRelatedFiles = Number.isInteger(options.maxRelatedFiles) && options.maxRelatedFiles > 0
+    ? options.maxRelatedFiles
+    : DEFAULT_MAX_RELATED_FILES;
+
+  const selected = [];
+  let summaryChars = 0;
+  const relatedFiles = new Set();
+
+  for (const record of sortRecords(records)) {
+    if (selected.length >= maxRecords) {
+      break;
+    }
+
+    const nextSummaryChars = summaryChars + String(record.summary ?? '').length;
+    if (nextSummaryChars > maxChars && selected.length > 0) {
+      continue;
+    }
+
+    const nextRelatedFiles = [...relatedFiles];
+    for (const path of record.relatedFiles ?? []) {
+      if (!nextRelatedFiles.includes(path)) {
+        nextRelatedFiles.push(path);
+      }
+    }
+
+    if (nextRelatedFiles.length > maxRelatedFiles && selected.length > 0) {
+      continue;
+    }
+
+    selected.push(record);
+    summaryChars = nextSummaryChars;
+    for (const path of record.relatedFiles ?? []) {
+      relatedFiles.add(path);
+    }
+  }
+
+  return {
+    records: selected,
+    truncated: selected.length < records.length,
+    summaryChars,
+    relatedFileCount: relatedFiles.size,
+  };
+}
+
+export function selectMemoryRecordsForTask(items, taskId, options = {}) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('items must be an array');
+  }
+
+  const task = items.find((item) => item.id === taskId);
+  if (task === undefined) {
+    throw new Error(`unknown task id: ${taskId}`);
+  }
+
+  const itemById = new Map(items.map((item) => [item.id, item]));
+  const derivedCandidates = buildMemoryRecordCandidatesFromItems(items, options.memoryOptions).records;
+  const candidates = options.memoryRecords
+    ?? mergeMemoryJournalWithCandidates(derivedCandidates, options.journalRecords ?? []);
+
+  const relevant = candidates.filter((record) => {
+    if (record.status === 'retired') {
+      return false;
+    }
+
+    return isRecordRelevant(record, task, itemById);
+  });
+
+  return applyBudget(relevant, options);
+}
+
+export function buildMemoryWorkerSliceForTask(items, taskId, options = {}) {
+  const selection = selectMemoryRecordsForTask(items, taskId, options);
+
+  return {
+    schema: MEMORY_WORKER_SLICE_SCHEMA,
+    taskId,
+    truncated: selection.truncated,
+    recordCount: selection.records.length,
+    summaryChars: selection.summaryChars,
+    relatedFileCount: selection.relatedFileCount,
+    budget: {
+      maxRecords: options.maxRecords ?? DEFAULT_MAX_RECORDS,
+      maxChars: options.maxChars ?? DEFAULT_MAX_CHARS,
+      maxRelatedFiles: options.maxRelatedFiles ?? DEFAULT_MAX_RELATED_FILES,
+    },
+    records: selection.records.map((record) => ({
+      id: record.id,
+      type: record.type,
+      summary: record.summary,
+      status: record.status,
+      confidence: record.confidence,
+      sourceWorkItem: record.sourceWorkItem,
+      relatedFiles: [...(record.relatedFiles ?? [])].sort(compareText),
+      relatedTasks: [...(record.relatedTasks ?? [])].sort(compareText),
+      reviewRequired: Boolean(record.reviewRequired),
+    })),
+    sourceInputs: [
+      'memory-record.candidates.v1',
+      'memory-contract-v1',
+      ...(options.journalRecords?.length ? ['memory-record.journal.v1'] : []),
+    ],
+  };
+}
+
+export async function buildMemoryWorkerSliceForTaskWithJournal(items, taskId, options = {}) {
+  let journalRecords = options.journalRecords;
+
+  if (journalRecords === undefined && options.journalPath) {
+    const journal = await readMemoryRecordJournal({
+      cwd: options.cwd,
+      journalPath: options.journalPath,
+    });
+    journalRecords = journal.records;
+  }
+
+  return buildMemoryWorkerSliceForTask(items, taskId, {
+    ...options,
+    journalRecords,
+  });
+}
+
+export function formatMemoryWorkerSliceForPrompt(slice) {
+  if (!slice || slice.schema !== MEMORY_WORKER_SLICE_SCHEMA) {
+    return '';
+  }
+
+  if (!Array.isArray(slice.records) || slice.records.length === 0) {
+    return '';
+  }
+
+  const lines = [
+    'Project memory slice (bounded, memory-contract-v1):',
+    `task=${slice.taskId} records=${slice.recordCount}${slice.truncated ? ' truncated=true' : ''}`,
+    ...slice.records.map((record) =>
+      `- [${record.type}/${record.status}] ${record.summary} (from ${record.sourceWorkItem}, confidence=${record.confidence})`,
+    ),
+  ];
+
+  return lines.join('\n');
+}

package/vendor/src/migrateStepToBvc.mjs

@@ -0,0 +1,133 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+import { swapBvcExtension } from './bvcFileFormat.mjs';
+
+const DEFAULT_SCAN_ROOTS = Object.freeze([
+  'architecture',
+  'charter',
+  'protocols',
+  'intent',
+  'work',
+  'rules',
+  'ui',
+  'domains',
+  'plans',
+  'skills',
+  'tests',
+]);
+
+/** @type {Set<string>} */
+export const STEP_RENAME_SKIP_RELATIVE_PATHS = new Set([
+  'tests/conformance/minimal.en.step',
+]);
+
+/**
+ * @param {string} filePath
+ */
+export function isStepMigrationCandidate(filePath) {
+  return String(filePath).toLowerCase().endsWith('.step');
+}
+
+/**
+ * @param {string} filePath
+ * @param {{ preferCanon?: boolean }} [options]
+ */
+export function stepToBvcTargetPath(filePath, options = {}) {
+  if (!isStepMigrationCandidate(filePath)) {
+    return null;
+  }
+  return swapBvcExtension(filePath, options);
+}
+
+/**
+ * @param {string[]} filePaths
+ * @param {{ preferCanon?: boolean }} [options]
+ */
+export function buildStepToBvcMigrationPlan(filePaths, options = {}) {
+  /** @type {Array<{ from: string, to: string }>} */
+  const renames = [];
+
+  for (const filePath of filePaths) {
+    const to = stepToBvcTargetPath(filePath, options);
+    if (to === null || to === filePath) {
+      continue;
+    }
+    renames.push({ from: filePath, to });
+  }
+
+  renames.sort((left, right) => left.from.localeCompare(right.from, 'en', { sensitivity: 'variant' }));
+  return renames;
+}
+
+/**
+ * @param {string} directory
+ * @param {{ cwd?: string, roots?: string[] }} [options]
+ */
+export async function collectStepFilesUnderRoots(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const roots = options.roots ?? DEFAULT_SCAN_ROOTS;
+  /** @type {string[]} */
+  const files = [];
+
+  async function walk(relativeDir) {
+    const absoluteDir = join(cwd, relativeDir);
+    let entries;
+    try {
+      entries = await readdir(absoluteDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const relativePath = join(relativeDir, entry.name).replace(/\\/g, '/');
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist') {
+          continue;
+        }
+        await walk(relativePath);
+        continue;
+      }
+      if (entry.isFile() && isStepMigrationCandidate(relativePath)) {
+        if (STEP_RENAME_SKIP_RELATIVE_PATHS.has(relativePath)) {
+          continue;
+        }
+        files.push(relativePath);
+      }
+    }
+  }
+
+  for (const root of roots) {
+    const absoluteRoot = join(cwd, root);
+    try {
+      const rootStat = await stat(absoluteRoot);
+      if (!rootStat.isDirectory()) {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    await walk(root);
+  }
+
+  files.sort((left, right) => left.localeCompare(right, 'en', { sensitivity: 'variant' }));
+  return files;
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ roots?: string[], paths?: string[] }} [options]
+ */
+export async function buildDefaultStepToBvcMigrationPlan(cwd, options = {}) {
+  const explicitPaths = (options.paths ?? [])
+    .map((entry) => relative(cwd, entry).replace(/\\/g, '/'))
+    .filter((entry) => entry && !entry.startsWith('..'));
+
+  const filePaths = explicitPaths.length > 0
+    ? explicitPaths
+    : await collectStepFilesUnderRoots({ cwd, roots: options.roots });
+
+  return buildStepToBvcMigrationPlan(filePaths);
+}
+
+export { DEFAULT_SCAN_ROOTS };