@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/validator.mjs

@@ -7,9 +7,9 @@
  * before they mutate persistent state.
  */
 import { loadRegistry } from './registry/loader.mjs';
-import { fileURLToPath, pathToFileURL } from 'node:url';
 import { existsSync, readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join } from 'node:path';
+import { packageRoot, isMainModule } from './roots.mjs';
 
 const VALID_TIERS = new Set(['reasoning', 'standard', 'fast']);
 const VALID_REASONING_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh']);
@@ -54,7 +54,7 @@ function validateStringArray(errors, value, label, validValues = null) {
 
 export function validateRegistry(reg, options = {}) {
   const errors = [];
-  const rootDir = options.rootDir ?? join(__dirname, '..');
+  const rootDir = options.rootDir ?? packageRoot;
 
   // Handle unified registry format (v2) - convert specialists from object to array
   // and extract orchestrator from specialists
@@ -252,9 +252,7 @@ export function validateRegistry(reg, options = {}) {
   return { valid: errors.length === 0, errors, summary };
 }
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   const reg = loadRegistry();
   const result = validateRegistry(reg);
   if (result.valid) {

package/lib/worker/entrypoint.mjs

@@ -29,6 +29,7 @@ import { FilesystemTaskGraphStore } from '../task-graph/store.mjs';
 import { runJob } from './run.mjs';
 import { evidenceFromJobResult, recordEvidence, blockedPacket } from './evidence.mjs';
 import { emitTraceEvent, newTraceId } from './trace.mjs';
+import { isMainModule } from '../roots.mjs';
 
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_IDLE_TIMEOUT_SECONDS = 300;
@@ -211,7 +212,7 @@ export async function runWorkerLoop({
 }
 
 // CLI entrypoint when invoked directly (the Dockerfile.worker CMD).
-const invokedDirectly = import.meta.url === `file://${process.argv[1]}`;
+const invokedDirectly = isMainModule(import.meta.url);
 if (invokedDirectly) {
   const args = parseArgs(process.argv);
   const workspace = args.workspace || process.env.CONSTRUCT_WORKSPACE || process.cwd();

package/lib/worker/run.mjs

@@ -28,12 +28,12 @@ import path from 'node:path';
 
 import { emitTraceEvent, newTraceId, newSpanId } from './trace.mjs';
 import { ensureDiskWrite, warnBudgetOnce } from '../resources/budget.mjs';
+import { resolveStateDir } from '../state-root.mjs';
 
 const DEFAULT_TIMEOUT_SECONDS = 300;
-const ARTIFACTS_SUBDIR = '.cx/runtime/worker';
 
 function artifactsDir(rootDir) {
-  return path.join(rootDir, ARTIFACTS_SUBDIR);
+  return resolveStateDir(rootDir, 'runtime', 'worker');
 }
 
 function buildRestrictedEnv(allowedKeys = []) {

package/lib/worker/trace.mjs

@@ -5,8 +5,9 @@
  * job → evidence record together via traceId + spanId. Events land in two
  * places concurrently:
  *
- *   1. `.cx/traces/<YYYY-MM-DD>.jsonl` — append-only local JSONL. Always on,
- *      no credentials required. Tail live, archive, or replay.
+ *   1. `<stateRoot>/traces/<YYYY-MM-DD>.jsonl` (ADR-0066: machine-scoped, not
+ *      project-local) — append-only local JSONL. Always on, no credentials
+ *      required. Tail live, archive, or replay.
  *   2. Optional remote export — selected by CONSTRUCT_TRACE_BACKEND. Each
  *      unique traceId triggers one trace-create plus an event-create per
  *      emitted event. Failures never throw because observability must not
@@ -26,16 +27,13 @@
  *   memory.written         — durable memory record persisted
  */
 
-import { existsSync, mkdirSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 
 import { createTelemetryClient } from '../telemetry/client.mjs';
-import { ensureCxDir } from '../project-init-shared.mjs';
 import { appendWithRotationSync } from '../logging/rotate.mjs';
 import { ensureDiskWrite, warnBudgetOnce } from '../resources/budget.mjs';
-
-const TRACE_SUBDIR = '.cx/traces';
+import { resolveStateDir } from '../state-root.mjs';
 
 // GitHub rejects single files > 100 MB. Keep every trace shard strictly
 // under 100 MB so an accidental commit + push doesn't brick the repo. Cap
@@ -69,7 +67,7 @@ export const TRACE_EVENT_TYPES = [
 ];
 
 export function traceDir(rootDir) {
-  return path.join(rootDir, TRACE_SUBDIR);
+  return resolveStateDir(rootDir, 'traces');
 }
 
 function todayShard() {
@@ -166,10 +164,6 @@ export function emitTraceEvent({
   }
 
   const dir = traceDir(rootDir);
-  if (!existsSync(dir)) {
-    ensureCxDir(rootDir);
-    mkdirSync(dir, { recursive: true });
-  }
 
   const event = {
     traceId: traceId || newTraceId(),

package/lib/workflow-state.mjs

@@ -11,6 +11,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
 import { routeRequest } from "./orchestration-policy.mjs";
+import { isMainModule } from './roots.mjs';
 
 const PHASES = ["research", "plan", "implement", "validate", "operate"];
 const VALID_STATUS = new Set(["todo", "in-progress", "blocked", "blocked_needs_user", "blocked_needs_executive", "done", "skipped"]);
@@ -55,6 +56,42 @@ function now() {
   return new Date().toISOString();
 }
 
+// rules/common/no-fabrication.md requires evidence a reader can re-verify.
+// A bare non-empty string ("did stuff") tells nobody how to check it, so the
+// done-gate below must look past mere presence to a re-verifiable shape: a
+// runnable command, a file path, a URL, a test reference, or a named
+// specialist's structured verdict (the "cx-reviewer: APPROVED" / "cx-qa: 42
+// tests passing" attestation format this workflow already standardizes on —
+// see tests/concierge-routing.test.mjs).
+
+const VERIFICATION_URL_RE = /https?:\/\/\S+/i;
+const VERIFICATION_FILE_RE = /[\w.-]*\/[\w./-]+\.\w+|\b[\w-]+\.(mjs|cjs|js|ts|tsx|jsx|py|rb|go|java|json|ya?ml|sh|md)\b/i;
+const VERIFICATION_COMMAND_RE = /\b(npm|yarn|pnpm|npx|node|python3?|pytest|go test|make|cargo|mvn|gradle|rspec|jest|vitest|bd)\b\s+\S/i;
+const VERIFICATION_TEST_RE = /\b[\w-]+\.(test|spec)\.\w+\b|\btest\(['"]/i;
+const VERIFICATION_ATTESTATION_RE = /\b(cx-[\w-]+|reviewer|qa|security|tester)\s*:\s*(APPROVED|PASS(?:ED)?|FAIL(?:ED)?|BLOCKED|REJECTED|\d+\s*(?:tests?|assertions?|%|percent))/i;
+
+function isReverifiableEvidence(entry) {
+  const text = typeof entry === "string" ? entry : entry == null ? "" : JSON.stringify(entry);
+  if (!text.trim()) return false;
+  return (
+    VERIFICATION_URL_RE.test(text) ||
+    VERIFICATION_FILE_RE.test(text) ||
+    VERIFICATION_COMMAND_RE.test(text) ||
+    VERIFICATION_TEST_RE.test(text) ||
+    VERIFICATION_ATTESTATION_RE.test(text)
+  );
+}
+
+function hasReverifiableEvidence(entries) {
+  return Array.isArray(entries) && entries.some(isReverifiableEvidence);
+}
+
+// The done-gate applies to every phase where "done" claims real work occurred
+// (research/plan tasks close on written artifacts the workflow already tracks
+// elsewhere, not on independently re-verifiable evidence).
+
+const VERIFICATION_GATED_PHASES = new Set(["implement", "validate", "operate"]);
+
 function slugify(value) {
   return String(value || "workflow")
     .toLowerCase()
@@ -220,7 +257,7 @@ export function buildTaskPacketFromIntent(request, options = {}) {
   const defaults = {
     title: options.title || request || "User-requested task",
     phase: options.phase || (route.intent === "research" ? "research" : route.intent === "fix" ? "implement" : route.intent === "evaluation" ? "validate" : route.intent === "implementation" ? "implement" : "implement"),
-    owner: options.owner || (route.workCategory === "analysis" ? "cx-architect" : route.workCategory === "writing" ? "cx-docs-keeper" : route.workCategory === "visual" ? "cx-designer" : route.workCategory === "deep" ? "cx-engineer" : "cx-engineer"),
+    owner: options.owner || (route.workCategory === "analysis" ? "cx-architect" : route.workCategory === "writing" ? "cx-operations" : route.workCategory === "visual" ? "cx-designer" : route.workCategory === "deep" ? "cx-engineer" : "cx-engineer"),
     status: "todo",
     dependsOn: options.dependsOn || [],
     files: options.files || [],
@@ -237,7 +274,6 @@ export function buildTaskPacketFromIntent(request, options = {}) {
       workCategory: route.workCategory,
       track: route.track,
       specialists: route.specialists || [],
-      dispatchPlan: route.dispatchPlan || null,
       request: String(request || ""),
     },
   };
@@ -413,7 +449,7 @@ export function addTasksFromPlan(root, markdown, options = {}) {
 
 export function updateTask(root, key, patch) {
   const workflow = loadWorkflow(root);
-  if (!workflow) throw new Error("No .cx/workflow.json found. Run `construct workflow init` first.");
+  if (!workflow) throw new Error("No .cx/workflow.json found. Run `construct workflow new` first.");
   const cleanPatch = Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined));
   let found = false;
   workflow.tasks = (workflow.tasks || []).map((task) => {
@@ -433,14 +469,20 @@ export function updateTask(root, key, patch) {
   if (cleanPatch.status && !VALID_STATUS.has(cleanPatch.status)) throw new Error(`Invalid status: ${cleanPatch.status}`);
   if (cleanPatch.status === "done") {
     const task = workflow.tasks.find((t) => t.key === key);
-    if (task && task.phase === "implement" && workflow.alignment?.verificationRequiredBeforeDone !== false) {
+    if (task && VERIFICATION_GATED_PHASES.has(task.phase) && workflow.alignment?.verificationRequiredBeforeDone !== false) {
       const mergedVerification = cleanPatch.verification ?? task.verification ?? [];
       if (mergedVerification.length === 0) {
         throw new Error(
-          `Cannot mark implement-phase task "${key}" as done without verification evidence. ` +
+          `Cannot mark ${task.phase}-phase task "${key}" as done without verification evidence. ` +
           `Add cx-reviewer and cx-qa results to task.verification before marking done.`
         );
       }
+      if (!hasReverifiableEvidence(mergedVerification)) {
+        throw new Error(
+          `Cannot mark ${task.phase}-phase task "${key}" as done: verification evidence is not re-verifiable. ` +
+          `Add a runnable command, file path, URL, test reference, or a cx-reviewer/cx-qa attestation.`
+        );
+      }
     }
   }
   if (cleanPatch.status === "in-progress" || cleanPatch.status === "blocked_needs_user") workflow.currentTaskKey = key;
@@ -454,7 +496,7 @@ export function transitionPhase(root, phase, status = "in-progress") {
   phase = normalizePhase(phase);
   if (!phase) throw new Error(`Invalid phase: ${phase}`);
   const workflow = loadWorkflow(root);
-  if (!workflow) throw new Error("No .cx/workflow.json found. Run `construct workflow init` first.");
+  if (!workflow) throw new Error("No .cx/workflow.json found. Run `construct workflow new` first.");
   workflow.phase = phase;
   workflow.phases = workflow.phases || {};
   for (const p of PHASES) {
@@ -469,7 +511,7 @@ export function alignmentFindings(workflow) {
     return [{
       severity: "HIGH",
       issue: "No .cx/workflow.json found",
-      fix: "Run `construct workflow init \"<title>\"` at the project root."
+      fix: "Run `construct workflow new \"<title>\"` at the project root."
     }];
   }
   const findings = [];
@@ -503,6 +545,8 @@ export function alignmentFindings(workflow) {
     }
     if (task.status === "done" && (!Array.isArray(task.verification) || task.verification.length === 0)) {
       findings.push({ severity: "HIGH", task: task.key, issue: "Done task has no verification evidence", fix: "Record commands, checks, or review evidence before marking done." });
+    } else if (task.status === "done" && Array.isArray(task.verification) && task.verification.length > 0 && VERIFICATION_GATED_PHASES.has(task.phase) && !hasReverifiableEvidence(task.verification)) {
+      findings.push({ severity: "HIGH", task: task.key, issue: "Done task's verification evidence is not re-verifiable", fix: "Record a runnable command, file path, URL, test reference, or a cx-reviewer/cx-qa attestation." });
     }
     for (const dep of task.dependsOn || []) {
       const depTask = tasks.find((candidate) => candidate.key === dep);
@@ -780,7 +824,7 @@ export function runWorkflowCli(argv = process.argv.slice(2), root = process.cwd(
   throw new Error(`Unknown workflow subcommand: ${command}`);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   try {
     runWorkflowCli(process.argv.slice(2), process.cwd());
   } catch (error) {

package/lib/workflows/liveness.mjs

@@ -0,0 +1,203 @@
+/**
+ * lib/workflows/liveness.mjs — workflow manifest liveness validation (LMCP-C11).
+ *
+ * Schema validation (validate.mjs) covers shape only: required fields, types,
+ * compatVersion. A roleChain entry naming a specialist that does not exist, a
+ * workflow whose handoff chain loops back on itself, and a workflow no surface
+ * can ever invoke all pass schema validation and fail only when a user
+ * actually runs the workflow. checkWorkflowLiveness runs four checks per
+ * manifest, over the already-loaded manifest list and the pack-aware merged
+ * specialist registry (LMCP-E1 precedence: project > pack > builtin, via
+ * loadAllPacks):
+ *
+ *   1. roleChain resolution   — every role resolves to an installed specialist.
+ *   2. skill existence        — every skill the resolved specialists declare
+ *                                exists on disk (the concrete capability a
+ *                                resolved roleChain entry brings with it).
+ *   3. acyclic handoff graph  — the roleChain's sequential handoffs
+ *                                (chain[i] -> chain[i+1]) never loop back to
+ *                                an earlier role in the same workflow.
+ *   4. surface/mode reachability — every workflow declares at least one
+ *                                surface and one mode, so some entrypoint can
+ *                                reach it.
+ *
+ * Returns { violations } without throwing and without classifying severity.
+ * Every violation — a bad roleChain entry, a missing skill file, a handoff
+ * cycle, or an unreachable workflow — is reported as a plain message; the
+ * caller (lib/graph/validate.mjs) applies mode policy uniformly, matching
+ * the existing C2 convention: liveness reports facts, the graph validator
+ * classifies error vs warning per deployment mode.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadAllPacks } from '../packs/loader.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Root of the Construct package (parent of lib/); skills/ lives here, not under an arbitrary project rootDir. */
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+/**
+ * Build the set of installed specialist ids (pack-aware, E1 precedence) and a
+ * lookup from bare role id ("architect") to specialist skills, by reading the
+ * merged pack list's specialists/org directories directly. loadAllPacks()
+ * already applies builtin < user < project precedence; the core pack's
+ * specialists come from specialists/org/specialists on rootDir.
+ *
+ * @param {{ rootDir?: string, packRoots?: string[] }} opts
+ * @returns {{ specialistIds: Set<string>, skillsByRole: Map<string, string[]> }}
+ */
+function resolveSpecialistRegistry({ rootDir = process.cwd() } = {}) {
+  const { packs } = loadAllPacks({ rootDir });
+
+  const specialistIds = new Set();
+  const skillsByRole = new Map();
+
+  for (const pack of packs) {
+    const ids = Array.isArray(pack.specialists) ? pack.specialists : [];
+    for (const id of ids) specialistIds.add(id);
+
+    const sourceDir = pack._sourceDir || pack._packDir;
+    if (!sourceDir) continue;
+
+    for (const id of ids) {
+      const specPath = join(sourceDir, 'specialists', `${id}.json`);
+      if (!existsSync(specPath)) continue;
+      try {
+        const raw = JSON.parse(readFileSync(specPath, 'utf8'));
+        const roleId = id.startsWith('cx-') ? id.slice(3) : id;
+        skillsByRole.set(roleId, Array.isArray(raw.skills) ? raw.skills : []);
+      } catch {
+        // Malformed specialist file — resolution failure surfaces separately
+        // via roleChain checks when the role is referenced; skip here.
+      }
+    }
+  }
+
+  return { specialistIds, skillsByRole };
+}
+
+/**
+ * Normalize a roleChain entry to the registry-prefixed specialist id.
+ * roleChain entries are bare role ids ("architect"); the registry stores
+ * "cx-architect". Entries already carrying the prefix pass through.
+ *
+ * @param {string} role
+ * @returns {string}
+ */
+function specialistIdFor(role) {
+  return role.startsWith('cx-') ? role : `cx-${role}`;
+}
+
+/**
+ * Detect a cycle in the sequential handoff graph of a roleChain: nodes are
+ * distinct roles, edges are chain[i] -> chain[i+1]. A role that reappears
+ * later in the same chain after handing off to a different role creates a
+ * back-edge, forming a cycle (e.g. [a, b, a] => a->b, b->a).
+ *
+ * @param {string[]} roleChain
+ * @returns {boolean}
+ */
+function hasHandoffCycle(roleChain) {
+  const edges = new Map();
+  for (let i = 0; i < roleChain.length - 1; i++) {
+    const from = roleChain[i];
+    const to = roleChain[i + 1];
+    if (from === to) continue;
+    if (!edges.has(from)) edges.set(from, new Set());
+    edges.get(from).add(to);
+  }
+
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map();
+  for (const node of roleChain) if (!color.has(node)) color.set(node, WHITE);
+
+  function visit(node) {
+    color.set(node, GRAY);
+    for (const next of edges.get(node) || []) {
+      const c = color.get(next);
+      if (c === GRAY) return true;
+      if (c === WHITE && visit(next)) return true;
+    }
+    color.set(node, BLACK);
+    return false;
+  }
+
+  for (const node of color.keys()) {
+    if (color.get(node) === WHITE && visit(node)) return true;
+  }
+  return false;
+}
+
+/**
+ * checkWorkflowLiveness(manifests, opts)
+ *
+ * Runs the four liveness checks over an already-loaded, already
+ * schema-validated manifest list. Manifests missing roleChain/surfaces/modes
+ * entirely are skipped for the checks that need them — schema validation
+ * already flags genuinely malformed manifests; liveness only adds checks
+ * schema validation cannot express.
+ *
+ * @param {object[]} manifests - Loaded manifests, each carrying `_filePath`.
+ * @param {{ rootDir?: string, packRoots?: string[], packageRoot?: string }} [opts]
+ *   rootDir selects the project whose pack tiers are merged (specialist
+ *   resolution); packageRoot (defaults to the Construct install) is where
+ *   skills/ is read from for the skill-existence check.
+ * @returns {{ violations: string[] }}
+ */
+export function checkWorkflowLiveness(manifests, opts = {}) {
+  const violations = [];
+
+  const { specialistIds, skillsByRole } = resolveSpecialistRegistry(opts);
+
+  for (const manifest of manifests) {
+    // Embed manifests are a workflow specialization scheduled by the embed
+    // daemon, not reached through a surface+mode entrypoint or a role chain —
+    // their liveness is enforced by the embed-capability loader, so the
+    // executable-workflow liveness checks below do not apply.
+    if (manifest.type === 'embed') continue;
+
+    const label = manifest._filePath || manifest.id || '(unknown manifest)';
+    const roleChain = Array.isArray(manifest.roleChain) ? manifest.roleChain : [];
+
+    // Check 1: roleChain resolution against the pack-aware merged registry.
+    for (const role of roleChain) {
+      const specId = specialistIdFor(role);
+      if (!specialistIds.has(specId)) {
+        violations.push(`${label}: roleChain entry '${role}' does not resolve to an installed specialist (expected '${specId}')`);
+      }
+    }
+
+    // Check 2: skill existence for every resolved role's declared skills.
+    // skills/ is a package-level resource (shared across projects), so it
+    // resolves against packageRoot, not the project rootDir.
+    const packageRoot = opts.packageRoot || PACKAGE_ROOT;
+    for (const role of roleChain) {
+      const skills = skillsByRole.get(role);
+      if (!skills) continue;
+      for (const skillId of skills) {
+        const skillPath = join(packageRoot, 'skills', `${skillId}.md`);
+        if (!existsSync(skillPath)) {
+          violations.push(`${label}: role '${role}' declares skill '${skillId}' with no matching file at skills/${skillId}.md`);
+        }
+      }
+    }
+
+    // Check 3: acyclic handoff graph.
+    if (roleChain.length > 1 && hasHandoffCycle(roleChain)) {
+      violations.push(`${label}: roleChain contains a circular handoff (${roleChain.join(' -> ')})`);
+    }
+
+    // Check 4: reachability from at least one declared surface and mode.
+    const surfaces = Array.isArray(manifest.surfaces) ? manifest.surfaces : [];
+    const modes = Array.isArray(manifest.modes) ? manifest.modes : [];
+    if (surfaces.length === 0 || modes.length === 0) {
+      violations.push(`${label}: workflow '${manifest.id}' is unreachable — declares ${surfaces.length === 0 ? 'no surfaces' : `surfaces [${surfaces.join(', ')}]`} and ${modes.length === 0 ? 'no modes' : `modes [${modes.join(', ')}]`}`);
+    }
+  }
+
+  return { violations };
+}

package/lib/workflows/loader.mjs

@@ -0,0 +1,177 @@
+/**
+ * lib/workflows/loader.mjs — workflow manifest directory loader and merger.
+ *
+ * Three manifest tiers exist: builtin (shipped with Construct in
+ * lib/embedded-contract/workflows/), pack (in {pack_root}/workflows/), and
+ * project (in .cx/workflows/). Project manifests take highest precedence;
+ * pack manifests override builtin.
+ *
+ * `loadWorkflowManifestsFromDir` reads every *.manifest.json in a directory and
+ * validates each one. Errors are collected without throwing. `mergeWorkflowManifests`
+ * merges up to three tiers by id. `resolveWorkflowManifestDirs` returns the
+ * canonical paths for each tier.
+ *
+ * Provenance (LMCP-D3): every loaded manifest carries `_source` ('builtin' |
+ * 'pack' | 'project') and `_filePath`. When a higher tier overrides a lower
+ * tier's id, `mergeWorkflowManifests` records the overridden entries on the
+ * winner as `_shadowedBy` so a caller (e.g. `construct graph explain`) can
+ * show which source won and what it overrode without re-reading disk.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { validateWorkflowManifest } from './validate.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Root of the Construct package (parent of lib/). */
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+/**
+ * loadWorkflowManifestsFromDir(dirPath, { strict } = {})
+ *
+ * Reads all `*.manifest.json` files in dirPath, validates each one, and
+ * returns a result object. Files that fail JSON parsing or validation are
+ * collected in `errors`; valid manifests are collected in `manifests`.
+ *
+ * When `strict` is true, manifests are validated with the strict-mode
+ * hardening checks (unknown field rejection).
+ *
+ * @param {string} dirPath - Absolute path to search.
+ * @param {{ strict?: boolean, source?: string }} [opts]
+ * @returns {{ manifests: object[], errors: string[] }}
+ */
+export function loadWorkflowManifestsFromDir(dirPath, { strict = false, source = 'unknown' } = {}) {
+  const manifests = [];
+  const errors = [];
+
+  if (!dirPath || !existsSync(dirPath)) {
+    return { manifests, errors };
+  }
+
+  let entries;
+  try {
+    entries = readdirSync(dirPath, { withFileTypes: true });
+  } catch (err) {
+    errors.push(`${dirPath}: failed to read directory (${err.message})`);
+    return { manifests, errors };
+  }
+
+  const manifestFiles = entries
+    .filter((e) => e.isFile() && e.name.endsWith('.manifest.json'))
+    .map((e) => join(dirPath, e.name))
+    .sort();
+
+  for (const filePath of manifestFiles) {
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+    } catch (err) {
+      errors.push(`${filePath}: failed to parse JSON (${err.message})`);
+      continue;
+    }
+
+    const result = validateWorkflowManifest(parsed, { filePath, strict });
+    if (!result.valid) {
+      errors.push(...result.errors);
+      continue;
+    }
+
+    manifests.push({ ...parsed, _filePath: filePath, _source: source });
+  }
+
+  return { manifests, errors };
+}
+
+/**
+ * mergeWorkflowManifests(builtin, pack, project)
+ *
+ * Merges three manifest arrays by `id`. Precedence (highest wins): project >
+ * pack > builtin. When multiple tiers declare the same id, only the
+ * highest-precedence entry is kept.
+ *
+ * @param {object[]} builtin
+ * @param {object[]} pack
+ * @param {object[]} project
+ * @returns {object[]}
+ */
+export function mergeWorkflowManifests(builtin = [], pack = [], project = []) {
+  const map = new Map();
+  const shadowed = new Map();
+
+  const layer = (list) => {
+    for (const m of list) {
+      const existing = map.get(m.id);
+      if (existing) {
+        const log = shadowed.get(m.id) || [];
+        log.push({ source: existing._source || 'unknown', filePath: existing._filePath || null });
+        shadowed.set(m.id, log);
+      }
+      map.set(m.id, m);
+    }
+  };
+
+  // Load lowest priority first so higher priority layers overwrite.
+  layer(builtin);
+  layer(pack);
+  layer(project);
+
+  for (const [id, winner] of map) {
+    const log = shadowed.get(id);
+    if (log?.length) winner._shadowedBy = log;
+  }
+
+  return [...map.values()];
+}
+
+/**
+ * resolveWorkflowManifestDirs({ rootDir, packRoots })
+ *
+ * Returns the canonical directory paths for each workflow manifest tier.
+ *
+ * @param {{ rootDir?: string, packRoots?: string[] }} opts
+ * @returns {{ builtin: string, pack: string[], project: string }}
+ */
+export function resolveWorkflowManifestDirs({ rootDir = process.cwd(), packRoots = [] } = {}) {
+  return {
+    builtin: join(PACKAGE_ROOT, 'lib', 'embedded-contract', 'workflows'),
+    pack: (packRoots || []).map((pr) => join(pr, 'workflows')),
+    project: join(rootDir, '.cx', 'workflows'),
+  };
+}
+
+/**
+ * loadAllWorkflows(opts)
+ *
+ * Convenience function that discovers, loads, and merges all workflow manifests
+ * across all three tiers. Returns the merged list of manifests and any errors
+ * encountered.
+ *
+ * @param {{ rootDir?: string, packRoots?: string[], strict?: boolean }} opts
+ * @returns {{ workflows: object[], errors: string[] }}
+ */
+export function loadAllWorkflows(opts = {}) {
+  const { rootDir, packRoots = [], strict = false } = opts;
+  const errors = [];
+
+  const dirs = resolveWorkflowManifestDirs({ rootDir, packRoots });
+
+  const builtin = loadWorkflowManifestsFromDir(dirs.builtin, { strict, source: 'builtin' });
+  errors.push(...builtin.errors);
+
+  const packManifests = [];
+  for (const packDir of dirs.pack) {
+    const result = loadWorkflowManifestsFromDir(packDir, { strict, source: 'pack' });
+    packManifests.push(...result.manifests);
+    errors.push(...result.errors);
+  }
+
+  const project = loadWorkflowManifestsFromDir(dirs.project, { strict, source: 'project' });
+  errors.push(...project.errors);
+
+  const workflows = mergeWorkflowManifests(builtin.manifests, packManifests, project.manifests);
+
+  return { workflows, errors };
+}