@work-graph/cli 0.2.0

package/vendor/src/gfsOverlayProjectPassport.mjs

@@ -0,0 +1,235 @@
+import { access, constants, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+export const GFS_OVERLAY_PASSPORT_SCHEMA = 'gfs.overlay.project.passport.v1';
+
+export const GFS_OVERLAY_READ_ORDER = ['disk-canonical', 'gfs-overlay-suffix', 'json-snapshot-projection'];
+
+export const GFS_OVERLAY_OPTIONAL_PATHS = [
+  {
+    id: 'passport-slice-b64',
+    logicalPath: '.iohasc/cache/passport-slice.b64',
+    format: 'base64-flatbuffers',
+    encoding: 'transport',
+    status: 'deferred',
+  },
+  {
+    id: 'passport-slice-gbc',
+    logicalPath: '.iohasc/cache/passport-slice.gbc',
+    format: 'flatbuffers',
+    encoding: 'binary',
+    status: 'deferred',
+  },
+  {
+    id: 'module-registry-json',
+    logicalPath: '.iohasc/cache/iohasc-gbc-module-registry.json',
+    format: 'json',
+    encoding: 'utf-8',
+    status: 'optional-overlay',
+  },
+  {
+    id: 'trace-link-slice-b64',
+    logicalPath: '.iohasc/cache/trace-link-slice.b64',
+    format: 'base64-flatbuffers',
+    encoding: 'transport',
+    status: 'deferred',
+  },
+  {
+    id: 'cm-trace-link-slices-json',
+    logicalPath: '.iohasc/cache/cm-trace-link-slices.v1.json',
+    format: 'json',
+    encoding: 'utf-8',
+    status: 'optional-overlay',
+  },
+  {
+    id: 'pvrg-node-descriptions-json',
+    logicalPath: '.iohasc/cache/pvrg-node-descriptions.v1.json',
+    format: 'json',
+    encoding: 'utf-8',
+    status: 'optional-overlay',
+  },
+];
+
+export const GFS_MANDATORY_FALLBACK_PROJECTIONS = [
+  {
+    id: 'workgraph-snapshot',
+    schema: 'workgraph.snapshot.v1',
+    source: 'parseWorkItems(work/backlog.bvc)',
+    required: true,
+  },
+  {
+    id: 'intent-tree-parity',
+    schema: 'intent.hierarchy.snapshot.v1',
+    source: 'intent tree migration equivalence',
+    required: true,
+  },
+  {
+    id: 'operator-shell',
+    schema: 'operator-shell.snapshot.v2',
+    source: 'buildOperatorShellProjection',
+    required: true,
+  },
+  {
+    id: 'architecture-snapshot',
+    schema: 'architecture.snapshot.v1',
+    source: 'buildArchitectureSnapshot (on demand)',
+    required: false,
+  },
+];
+
+export function buildGfsOverlayReadContract() {
+  const optionalPaths = [...GFS_OVERLAY_OPTIONAL_PATHS].sort((left, right) => compareText(left.id, right.id));
+
+  return {
+    schema: 'gfs.overlay.read-contract.v1',
+    readOrder: [...GFS_OVERLAY_READ_ORDER],
+    diskFirst: true,
+    overlayNeverCanonicalWithoutWorkItem: true,
+    utf8JsonOverlayPaths: optionalPaths.filter((entry) => entry.encoding === 'utf-8'),
+    deferredBinaryPaths: optionalPaths.filter((entry) => entry.status === 'deferred'),
+    optionalOverlayPaths: optionalPaths.filter((entry) => entry.status === 'optional-overlay'),
+    donorReference: '../project/src/iohascGbc/gfsFileContentOverlay.ts',
+  };
+}
+
+export function buildGfsOverlayProjectPassport() {
+  const mandatoryFallback = [...GFS_MANDATORY_FALLBACK_PROJECTIONS].sort((left, right) => compareText(left.id, right.id));
+  const readContract = buildGfsOverlayReadContract();
+
+  return {
+    schema: GFS_OVERLAY_PASSPORT_SCHEMA,
+    status: 'optional-deferred',
+    readContract,
+    mandatoryFallback: {
+      required: true,
+      projections: mandatoryFallback,
+      requiredProjectionIds: mandatoryFallback.filter((entry) => entry.required).map((entry) => entry.id),
+    },
+    agentContextPolicy: {
+      withoutGfs: 'JSON snapshots + .bvc canon only',
+      withGfs: 'merge overlay bytes after disk-first check; never wipe disk canon',
+    },
+    relatedProtocols: ['gbc-gvm-zig-deferral-boundary', 'gfs-overlay-project-passport-v1'],
+  };
+}
+
+export function evaluateGfsOverlayFallbackPolicy(passport = buildGfsOverlayProjectPassport()) {
+  const requiredProjections = passport.mandatoryFallback.projections.filter((entry) => entry.required);
+
+  return {
+    schema: 'gfs.overlay.fallback-policy.v1',
+    ok: passport.mandatoryFallback.required === true
+      && requiredProjections.length >= 2
+      && passport.readContract.diskFirst === true
+      && passport.readContract.overlayNeverCanonicalWithoutWorkItem === true,
+    requiredProjectionCount: requiredProjections.length,
+  };
+}
+
+export const GFS_PROJECT_PASSPORT_DISK_PATH = '.iohasc/project-passport.v1.json';
+export const GFS_OVERLAY_PILOT_READ_SCHEMA = 'gfs.overlay.pilot-read.v1';
+
+export const GFS_OVERLAY_PILOT_PREREQUISITES = [
+  'Disk canonical: .iohasc/project-passport.v1.json under repo root (or fixture cwd)',
+  'Optional GFS mount: set gfsOverlayRoot to overlay directory mirroring logical paths',
+  'Without GFS: mandatory JSON fallback projections from buildGfsOverlayProjectPassport()',
+  'Binary b64/gbc overlay paths remain deferred; pilot reads UTF-8 JSON only',
+];
+
+async function readJsonFileIfPresent(absolutePath, source) {
+  try {
+    await access(absolutePath, constants.R_OK);
+    const text = await readFile(absolutePath, 'utf8');
+    return {
+      ok: true,
+      source,
+      absolutePath,
+      payload: JSON.parse(text),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      source,
+      absolutePath,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function readDiskCanonicalProjectPassport(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const logicalPath = options.logicalPath ?? GFS_PROJECT_PASSPORT_DISK_PATH;
+  const absolutePath = resolve(cwd, logicalPath);
+  const readResult = await readJsonFileIfPresent(absolutePath, 'disk-canonical');
+
+  return {
+    ...readResult,
+    logicalPath,
+  };
+}
+
+export async function readGfsOverlayPassportPilot(options = {}) {
+  const passport = buildGfsOverlayProjectPassport();
+  const cwd = options.cwd ?? process.cwd();
+  const diskRead = await readDiskCanonicalProjectPassport({ ...options, cwd });
+
+  if (diskRead.ok) {
+    return {
+      schema: GFS_OVERLAY_PILOT_READ_SCHEMA,
+      ok: true,
+      readPath: 'disk-canonical',
+      gfsMounted: false,
+      passportSchema: diskRead.payload?.schemaVersion ?? diskRead.payload?.schema ?? null,
+      absolutePath: diskRead.absolutePath,
+      prerequisites: [...GFS_OVERLAY_PILOT_PREREQUISITES],
+    };
+  }
+
+  if (options.gfsOverlayRoot) {
+    const overlayPath = resolve(cwd, options.gfsOverlayRoot, GFS_PROJECT_PASSPORT_DISK_PATH);
+    const overlayRead = await readJsonFileIfPresent(overlayPath, 'gfs-overlay-suffix');
+    if (overlayRead.ok) {
+      return {
+        schema: GFS_OVERLAY_PILOT_READ_SCHEMA,
+        ok: true,
+        readPath: 'gfs-overlay-suffix',
+        gfsMounted: true,
+        passportSchema: overlayRead.payload?.schemaVersion ?? overlayRead.payload?.schema ?? null,
+        absolutePath: overlayRead.absolutePath,
+        prerequisites: [...GFS_OVERLAY_PILOT_PREREQUISITES],
+      };
+    }
+  }
+
+  const fallbackRead = options.fallbackRoot
+    ? await readDiskCanonicalProjectPassport({ cwd: resolve(cwd, options.fallbackRoot) })
+    : diskRead;
+
+  if (fallbackRead.ok) {
+    return {
+      schema: GFS_OVERLAY_PILOT_READ_SCHEMA,
+      ok: true,
+      readPath: 'json-snapshot-projection',
+      gfsMounted: false,
+      fallback: true,
+      passportSchema: fallbackRead.payload?.schemaVersion ?? fallbackRead.payload?.schema ?? null,
+      absolutePath: fallbackRead.absolutePath,
+      mandatoryFallbackProjectionIds: passport.mandatoryFallback.requiredProjectionIds,
+      prerequisites: [...GFS_OVERLAY_PILOT_PREREQUISITES],
+    };
+  }
+
+  return {
+    schema: GFS_OVERLAY_PILOT_READ_SCHEMA,
+    ok: true,
+    readPath: 'json-snapshot-projection',
+    gfsMounted: false,
+    fallback: true,
+    passportSchema: null,
+    mandatoryFallbackProjectionIds: passport.mandatoryFallback.requiredProjectionIds,
+    prerequisites: [...GFS_OVERLAY_PILOT_PREREQUISITES],
+    note: 'No disk passport; contract-only fallback projections apply',
+  };
+}

package/vendor/src/globalStepPathToBvcReferences.mjs

@@ -0,0 +1,196 @@
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+/** Files that must keep literal `.step` for legacy dual-read API/tests. */
+export const STEP_PATH_REPLACE_SKIP_FILES = new Set([
+  'src/bvcFileFormat.mjs',
+  'src/migrateStepToBvc.mjs',
+  'tests/bvcDualExtension.test.mjs',
+  'tests/migrateStepToBvc.test.mjs',
+  'tests/bvcSpecPackage.test.mjs',
+  'tests/bvcFormatCli.test.mjs',
+  'tests/conformance/minimal.en.step',
+  'tests/conformance/minimal.en.bvc',
+  'src/globalStepPathToBvcReferences.mjs',
+  'packages/bvc-spec/index.js',
+  'dist/bvc-spec-github/index.js',
+]);
+
+export const STEP_PATH_REPLACE_SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  'dist',
+  'playwright-report',
+  'test-results',
+]);
+
+const TEXT_EXTENSIONS = new Set([
+  '.bvc',
+  '.step',
+  '.md',
+  '.mdc',
+  '.mjs',
+  '.js',
+  '.json',
+  '.jsonl',
+  '.ts',
+  '.tsx',
+  '.yaml',
+  '.yml',
+  '.txt',
+]);
+
+/**
+ * Replace filesystem path suffix `.step` → `.bvc` in prose and labels.
+ * Preserves ../project/* paths (ioHasC sibling repo still on .step).
+ * @param {string} text
+ */
+export function replaceStepPathReferencesInText(text) {
+  /** @type {string[]} */
+  const externalStepPaths = [];
+  let out = String(text).replace(/(\.\.\/project[^\s'"),#\]]*?)\.step\b/g, (match) => {
+    const token = `__EXTERNAL_STEP_PATH_${externalStepPaths.length}__`;
+    externalStepPaths.push(match);
+    return token;
+  });
+
+  /** Protect prose mentions of the legacy extension before path rewrites. */
+  const legacyExtTokens = [];
+  out = out.replace(/\blegacy \.step\b/gi, () => {
+    const token = `__LEGACY_EXT_${legacyExtTokens.length}__`;
+    legacyExtTokens.push('legacy .step');
+    return token;
+  });
+  out = out.replace(/`\.step`/g, () => {
+    const token = `__LEGACY_EXT_${legacyExtTokens.length}__`;
+    legacyExtTokens.push('`.step`');
+    return token;
+  });
+
+  out = out.replace(/\.work\.step\b/g, '.work.bvc');
+  out = out.replace(/\.intent\.step\b/g, '.intent.bvc');
+  out = out.replace(/\.compiler\.step\b/g, '.compiler.bvc');
+  out = out.replace(/\.step\b/g, '.bvc');
+
+  for (let index = 0; index < legacyExtTokens.length; index += 1) {
+    const restored = legacyExtTokens[index];
+    out = out.replace(`__LEGACY_EXT_${index}__`, restored);
+  }
+
+  for (let index = 0; index < externalStepPaths.length; index += 1) {
+    out = out.replace(`__EXTERNAL_STEP_PATH_${index}__`, externalStepPaths[index]);
+  }
+
+  return out;
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ apply?: boolean, roots?: string[] }} [options]
+ */
+export async function collectTextFilesForStepPathReplace(cwd, options = {}) {
+  const roots = options.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, '/');
+      const base = relativePath.replace(/^\.\//, '');
+
+      if (entry.isDirectory()) {
+        if (STEP_PATH_REPLACE_SKIP_DIRS.has(entry.name)) {
+          continue;
+        }
+        await walk(relativePath);
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      if (STEP_PATH_REPLACE_SKIP_FILES.has(base)) {
+        continue;
+      }
+
+      const ext = entry.name.includes('.') ? entry.name.slice(entry.name.lastIndexOf('.')) : '';
+      if (!TEXT_EXTENSIONS.has(ext)) {
+        continue;
+      }
+
+      files.push(base);
+    }
+  }
+
+  for (const root of roots) {
+    const absoluteRoot = join(cwd, root);
+    try {
+      const rootStat = await stat(absoluteRoot);
+      if (!rootStat.isDirectory() && root !== '.') {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    await walk(root === '.' ? '.' : root);
+  }
+
+  files.sort((left, right) => left.localeCompare(right, 'en', { sensitivity: 'variant' }));
+  return files;
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ apply?: boolean, roots?: string[] }} [options]
+ */
+export async function runGlobalStepPathToBvcReferences(cwd, options = {}) {
+  const apply = options.apply === true;
+  const files = await collectTextFilesForStepPathReplace(cwd, options);
+  /** @type {Array<{ path: string, changed: boolean }>} */
+  const report = [];
+
+  for (const filePath of files) {
+    const absolutePath = join(cwd, filePath);
+    const before = await readFile(absolutePath, 'utf8');
+    const after = replaceStepPathReferencesInText(before);
+    const changed = before !== after;
+    report.push({ path: filePath, changed });
+    if (changed && apply) {
+      await writeFile(absolutePath, after, 'utf8');
+    }
+  }
+
+  return {
+    schema: 'global-step-path-to-bvc-references.v1',
+    apply,
+    scanned: files.length,
+    changed: report.filter((entry) => entry.changed).length,
+    files: report.filter((entry) => entry.changed),
+  };
+}
+
+/**
+ * Extended rename roots for residual `.bvc` artifacts.
+ */
+export const FULL_BVC_RENAME_ROOTS = Object.freeze([
+  'architecture',
+  'charter',
+  'protocols',
+  'intent',
+  'work',
+  'rules',
+  'ui',
+  'domains',
+  'plans',
+  'skills',
+  'tests',
+]);

package/vendor/src/goldenPath.mjs

@@ -0,0 +1,69 @@
+import { claimNext, recordEvidence, transitionStatus } from './workGraphRuntime.mjs';
+
+/** Agent loop phases aligned with protocols/agent-state-machine-v1.bvc */
+export const AGENT_LOOP_PHASES = [
+  'observe',
+  'plan',
+  'claim',
+  'act',
+  'verify',
+  'record',
+  'stop',
+];
+
+/**
+ * Deterministic golden path: claim ready task -> act evidence -> verify -> done.
+ * No LLM, no filesystem — exercises Work Graph runtime policy only.
+ *
+ * @param {Array<{ id: string, status: string, evidence?: string[], targetFiles?: string[], labels?: object, dependsOn?: string[] }>} items
+ * @param {{ taskId?: string }} [options]
+ */
+export function runDeterministicGoldenPath(items, options = {}) {
+  const steps = [];
+  let pool = items.map((item) => ({ ...item, evidence: [...(item.evidence || [])], labels: { ...item.labels } }));
+
+  steps.push({ phase: 'observe', detail: 'read snapshot', itemCount: pool.length });
+
+  const target = options.taskId
+    ? pool.find((item) => item.id === options.taskId)
+    : claimNext(pool);
+
+  if (!target) {
+    return { ok: false, steps, error: 'no_claimable_task', finalItems: pool };
+  }
+
+  steps.push({ phase: 'plan', detail: 'select task ' + target.id, taskId: target.id });
+
+  let current = transitionStatus(target, 'claimed');
+  pool = replaceItem(pool, target.id, current);
+  steps.push({ phase: 'claim', detail: 'transition to claimed', taskId: current.id, status: current.status });
+
+  current = recordEvidence(current, 'change: updated ' + (current.targetFiles?.[0] || 'artifact') + ' for golden path');
+  pool = replaceItem(pool, current.id, current);
+  steps.push({ phase: 'act', detail: 'record change evidence', evidenceCount: current.evidence.length });
+
+  current = transitionStatus(current, 'verify', {
+    evidence: 'verify: npm run test:deterministic scheduled for golden path task',
+  });
+  pool = replaceItem(pool, current.id, current);
+  steps.push({ phase: 'verify', detail: 'transition to verify', status: current.status });
+
+  current = transitionStatus(current, 'done', {
+    evidence: 'test: npm run test:deterministic exit_code=0 golden-path',
+  });
+  pool = replaceItem(pool, current.id, current);
+  steps.push({ phase: 'record', detail: 'transition to done with verification evidence', status: current.status });
+  steps.push({ phase: 'stop', detail: 'golden path complete', taskId: current.id });
+
+  return {
+    ok: current.status === 'done' && current.evidence.length >= 3,
+    steps,
+    finalItems: pool,
+    taskId: current.id,
+  };
+}
+
+/** @param {typeof items} pool @param {string} id @param {object} nextItem */
+function replaceItem(pool, id, nextItem) {
+  return pool.map((item) => (item.id === id ? nextItem : item));
+}