@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/graph/staleness.mjs

@@ -1,44 +1,275 @@
 /**
- * lib/graph/staleness.mjs — dependency graph seed-hash staleness checks.
+ * lib/graph/staleness.mjs — per-source seed-hash staleness checks (LMCP-C6).
  *
- * Compares the hash of registry/contracts/workflow seed files against the
- * hash stored at last graph build (.cx/graph/meta.json). Shared by Oracle,
- * the doctor graph-staleness watcher, and PostToolUse advisories.
+ * `hashFiles`/GRAPH_SEED_FILES (build-from-registry.mjs) hash a flat file list
+ * and cannot see inside a directory — the historical seed list has always
+ * included whole-directory entries (specialists/org, docs) which `readFileSync`
+ * silently treats as always-missing, so a change inside the directory never
+ * moved the hash. `hashSourceGroup` fixes this by walking directories
+ * recursively and hashing every file's relative path plus contents; a single
+ * flat file hashes the same way. `SOURCE_GROUPS` names each seed source
+ * (registry, overlays, specialists/org, plugin dirs, provider manifests,
+ * workflow manifests) as its own group so `checkGraphStaleness` can report
+ * exactly which source drifted, not just that something did. The legacy
+ * combined `sourceHash` (single hash over the flat GRAPH_SEED_FILES list) is
+ * preserved for existing consumers (lib/oracle/read-model.mjs) that compare
+ * against it directly.
+ *
+ * `checkExecutionStaleness` (LMCP-C9) is a second, independent staleness
+ * dimension: source-hash staleness above asks "did the seeds change since
+ * the graph was built"; execution staleness asks "has this workflow actually
+ * run recently". A workflow can be source-fresh and execution-stale (nothing
+ * changed, but no one has run it in months) or the reverse, so the two are
+ * reported side by side rather than merged into one boolean. A workflow with
+ * zero runtime-evidence ever (lib/graph/runtime-evidence.mjs) is flagged
+ * `neverExecuted: true` distinctly from `stale: true` — the former is "no
+ * evidence exists", the latter is "evidence exists but has aged past the
+ * threshold" — so a caller never has to infer one from the absence of data
+ * that could equally mean the other.
  */
 
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
 import { hashFiles } from './build-from-registry.mjs';
 import { loadGraph } from './store.mjs';
+import { resolveManifestDirs } from '../extensions/loader.mjs';
+import { resolveWorkflowManifestDirs } from '../workflows/loader.mjs';
+import { computeLastExecutionByWorkflow } from './runtime-evidence.mjs';
+import { listWorkflowDefs } from '../embedded-contract/workflow-defs.mjs';
 
 export const GRAPH_SEED_FILES = [
   'registry/capabilities.json',
   'specialists/org',
   'lib/embedded-contract/workflow-defs.mjs',
+  'lib/extensions/manifest-schema.mjs',
+  'lib/extensions/loader.mjs',
+  'lib/extensions/validate.mjs',
+  'lib/extensions/manifests',
+  'docs',
+  'lib/registry/assemble.mjs',
 ];
 
+function walkFiles(absPath) {
+  let st;
+  try { st = statSync(absPath); } catch { return null; }
+  if (st.isFile()) return [absPath];
+  if (!st.isDirectory()) return null;
+  const out = [];
+  const stack = [absPath];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile()) out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Hash a named group of seed paths (files and/or directories), recursing into
+ * directories so an edit anywhere inside moves the hash. Missing paths hash
+ * as a stable sentinel rather than throwing, so an optional seed (e.g. a
+ * project override file that may not exist) does not abort hashing.
+ *
+ * @param {string} rootDir
+ * @param {string[]} rels — repo-relative file or directory paths.
+ * @returns {string} 16-hex-char digest.
+ */
+export function hashSourceGroup(rootDir, rels) {
+  const h = createHash('sha256');
+  for (const rel of rels) {
+    const abs = path.join(rootDir, rel);
+    const files = walkFiles(abs);
+    if (!files) { h.update(`${rel}\0missing`); continue; }
+    for (const filePath of files) {
+      const relToRoot = path.relative(rootDir, filePath);
+      h.update(relToRoot);
+      try { h.update(readFileSync(filePath)); } catch { h.update('\0unreadable'); }
+    }
+  }
+  return h.digest('hex').slice(0, 16);
+}
+
+/**
+ * Named seed-source groups making up the full graph seed set: registry
+ * catalog + overlays, specialists/org, plugin (pack) directories, provider
+ * manifests (builtin + user + project), and workflow manifests (builtin +
+ * project; pack tiers are resolved per-pack root so are not enumerable here).
+ *
+ * @param {string} rootDir
+ * @returns {Record<string,string[]>}
+ */
+export function sourceGroups(rootDir) {
+  const manifestDirs = resolveManifestDirs({ rootDir });
+  const workflowDirs = resolveWorkflowManifestDirs({ rootDir });
+
+  return {
+    registry: ['registry/capabilities.json', 'lib/registry/assemble.mjs', 'lib/registry/loader.mjs'],
+    overlays: [
+      path.join('.cx', 'org'),
+      path.join('.cx', 'unified-registry.json'),
+    ],
+    specialistsOrg: ['specialists/org'],
+    plugins: [path.join('.cx', 'packs'), 'lib/packs/manifests'],
+    providerManifests: [
+      manifestDirs.builtin,
+      manifestDirs.user,
+      manifestDirs.project,
+      path.join('.cx', 'providers.json'),
+    ].map((p) => path.isAbsolute(p) ? path.relative(rootDir, p) : p),
+    workflowManifests: [
+      workflowDirs.builtin,
+      workflowDirs.project,
+      'lib/embedded-contract/workflow-defs.mjs',
+    ].map((p) => path.isAbsolute(p) ? path.relative(rootDir, p) : p),
+  };
+}
+
+/**
+ * @param {string} rootDir
+ * @returns {Record<string,string>} hash per named source group.
+ */
+export function computeSourceHashes(rootDir) {
+  const groups = sourceGroups(rootDir);
+  const out = {};
+  for (const [name, rels] of Object.entries(groups)) {
+    out[name] = hashSourceGroup(rootDir, rels);
+  }
+  return out;
+}
+
 /**
  * @param {string} rootDir — project root holding .cx/graph/.
- * @returns {{ present: boolean, stale: boolean, staleReason: string|null, currentHash?: string, storedHash?: string|null }}
+ * @returns {{
+ *   present: boolean,
+ *   stale: boolean,
+ *   staleReason: string|null,
+ *   staleSources: string[],
+ *   currentHash?: string,
+ *   storedHash?: string|null,
+ * }}
  */
 export function checkGraphStaleness(rootDir) {
   const graph = loadGraph(rootDir);
   if (!graph.exists) {
-    return { present: false, stale: false, staleReason: null };
+    return { present: false, stale: false, staleReason: null, staleSources: [] };
   }
 
   try {
     const current = hashFiles(rootDir, GRAPH_SEED_FILES);
     const stored = graph.meta?.sourceHash ?? null;
-    if (stored && current !== stored) {
+
+    const currentSources = computeSourceHashes(rootDir);
+    const storedSources = graph.meta?.sourceHashes ?? null;
+    const staleSources = [];
+    if (storedSources) {
+      for (const name of Object.keys(currentSources)) {
+        if (currentSources[name] !== storedSources[name]) staleSources.push(name);
+      }
+    }
+
+    const stale = staleSources.length > 0 || (stored != null && current !== stored && !storedSources);
+    if (stale) {
+      const reason = staleSources.length > 0
+        ? `source(s) changed since last build: ${staleSources.join(', ')}`
+        : 'registry/contracts/workflow seeds changed since last build';
       return {
         present: true,
         stale: true,
-        staleReason: 'registry/contracts/workflow seeds changed since last build',
+        staleReason: reason,
+        staleSources,
         currentHash: current,
         storedHash: stored,
       };
     }
-    return { present: true, stale: false, staleReason: null, currentHash: current, storedHash: stored };
+    return { present: true, stale: false, staleReason: null, staleSources: [], currentHash: current, storedHash: stored };
   } catch {
-    return { present: true, stale: false, staleReason: null };
+    return { present: true, stale: false, staleReason: null, staleSources: [] };
   }
 }
+
+/**
+ * Default execution-staleness threshold: a workflow with runtime evidence
+ * older than this many days is flagged stale. Overridable per-workflow via
+ * the `thresholds` option (keyed by workflow type), so a high-churn workflow
+ * can demand fresher evidence than a rarely-invoked one.
+ */
+export const EXECUTION_STALENESS_DEFAULT_THRESHOLD_DAYS = 30;
+
+function ageDays(timestamp, now) {
+  const then = Date.parse(timestamp);
+  if (!Number.isFinite(then)) return null;
+  return (now - then) / (1000 * 60 * 60 * 24);
+}
+
+/**
+ * Per-workflow execution-staleness (LMCP-C9): how long since a workflow's
+ * last runtime-evidence edge (lib/graph/runtime-evidence.mjs), against a
+ * per-workflow threshold. A workflow with no evidence at all is reported
+ * `neverExecuted: true` and `stale: false` — distinct from a workflow whose
+ * evidence exists but has aged past the threshold (`stale: true`,
+ * `neverExecuted: false`) — so the two conditions are never conflated.
+ *
+ * @param {string} rootDir — project root; runs are read from its machine-scoped
+ * state root (ADR-0066), not a project-relative path.
+ * @param {{ thresholds?: Record<string,number>, now?: number }} [opts]
+ * @returns {{
+ *   workflows: Record<string, {
+ *     lastExecution: { timestamp: string, outcome: string, runId: string }|null,
+ *     neverExecuted: boolean,
+ *     stale: boolean,
+ *     ageDays: number|null,
+ *     thresholdDays: number,
+ *   }>,
+ *   neverExecuted: string[],
+ *   staleWorkflows: string[],
+ * }}
+ */
+export function checkExecutionStaleness(rootDir, { thresholds = {}, now = Date.now() } = {}) {
+  const lastExecutionByWorkflow = computeLastExecutionByWorkflow(rootDir);
+
+  const workflows = {};
+  const neverExecuted = [];
+  const staleWorkflows = [];
+
+  for (const wf of listWorkflowDefs()) {
+    const lastExecution = lastExecutionByWorkflow[wf.type] ?? null;
+    const thresholdDays = thresholds[wf.type] ?? EXECUTION_STALENESS_DEFAULT_THRESHOLD_DAYS;
+
+    if (!lastExecution) {
+      neverExecuted.push(wf.type);
+      workflows[wf.type] = {
+        lastExecution: null,
+        neverExecuted: true,
+        stale: false,
+        ageDays: null,
+        thresholdDays,
+      };
+      continue;
+    }
+
+    const age = ageDays(lastExecution.timestamp, now);
+    const stale = age !== null && age > thresholdDays;
+    if (stale) staleWorkflows.push(wf.type);
+
+    workflows[wf.type] = {
+      lastExecution,
+      neverExecuted: false,
+      stale,
+      ageDays: age,
+      thresholdDays,
+    };
+  }
+
+  return {
+    workflows,
+    neverExecuted: neverExecuted.sort(),
+    staleWorkflows: staleWorkflows.sort(),
+  };
+}

package/lib/graph/store.mjs

@@ -3,15 +3,22 @@
  *
  * The substrate for Construct's living dependency matrix. Nodes are typed
  * entities (file, module, workflow, capability, test, contract, surface,
- * skill, rule) addressed by canonical ids of the form `type:key`. Edges are
- * directed and carry a relation kind (imports, realizes, validates, covers,
- * exposes, governed_by, uses, embeds, co_changes) and a provenance source
- * (registry, import-graph, co-change, override).
+ * skill, rule, provider, tool, pack, doc, specialist, runtime-evidence) addressed
+ * by canonical ids of the form `type:key`. Edges are directed and carry a
+ * relation kind (imports, realizes, validates, covers, exposes, governed_by,
+ * uses, embeds, co_changes, contains, requires, documents, evidenced_by,
+ * owned_by) and a provenance source
+ * (registry, import-graph, co-change, override, corpus-annotation, runtime-evidence).
  *
  * Persisted under `.cx/graph/` as deterministic JSONL so a graph round-trips
  * losslessly and diffs cleanly: nodes.jsonl (sorted by id), edges.jsonl
  * (sorted by from,rel,to), meta.json (generatedAt, sourceHash, counts).
  * Dependency-free and pure-JS per ADR-0001.
+ *
+ * `reads` (LMCP-E4): specialist --reads--> provider, seeded from pack
+ * `embedBindings` grants (build-from-registry.mjs). Makes the embed
+ * authority-guard's per-specialist read/search grant visible in
+ * `construct graph`/`construct matrix` rather than living only in pack JSON.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
@@ -19,13 +26,15 @@ import path from 'node:path';
 
 export const NODE_TYPES = new Set([
   'file', 'module', 'workflow', 'capability', 'test', 'contract', 'surface', 'skill', 'rule',
+  'provider', 'tool', 'pack', 'doc', 'specialist', 'runtime-evidence', 'embed',
 ]);
 
 export const EDGE_RELS = new Set([
   'imports', 'realizes', 'validates', 'covers', 'exposes', 'governed_by', 'uses', 'embeds', 'co_changes', 'contains',
+  'requires', 'documents', 'evidenced_by', 'owned_by', 'reads', 'secures',
 ]);
 
-export const EDGE_SOURCES = new Set(['registry', 'import-graph', 'co-change', 'override']);
+export const EDGE_SOURCES = new Set(['registry', 'import-graph', 'co-change', 'override', 'corpus-annotation', 'runtime-evidence', 'embed-manifest']);
 
 const STORE_SUBDIR = path.join('.cx', 'graph');
 
@@ -98,11 +107,17 @@ function countBy(items, key) {
  * Persist a full graph (regenerate semantics). Nodes and edges are normalized
  * and sorted; meta records counts and the caller-supplied source hash.
  *
+ * `sourceHashes` (LMCP-C6) is an optional `{ [sourceName]: hash }` map recording
+ * a hash per seed source (registry, overlays, specialists/org, plugins,
+ * provider manifests, workflow manifests) alongside the single combined
+ * `sourceHash`, so staleness detection can name which source drifted instead
+ * of only reporting "something changed".
+ *
  * @param {string} rootDir
- * @param {{ nodes: object[], edges: object[], generatedAt?: string, sourceHash?: string }} graph
+ * @param {{ nodes: object[], edges: object[], generatedAt?: string, sourceHash?: string, sourceHashes?: Record<string,string> }} graph
  * @returns {{ nodeCount: number, edgeCount: number, dir: string }}
  */
-export function writeGraph(rootDir, { nodes = [], edges = [], generatedAt = null, sourceHash = null } = {}) {
+export function writeGraph(rootDir, { nodes = [], edges = [], generatedAt = null, sourceHash = null, sourceHashes = null } = {}) {
   const dir = graphDir(rootDir);
   mkdirSync(dir, { recursive: true });
   const normNodes = normalizeNodes(nodes);
@@ -110,8 +125,10 @@ export function writeGraph(rootDir, { nodes = [], edges = [], generatedAt = null
   writeAtomic(nodesPath(rootDir), normNodes.map((n) => JSON.stringify(n)).join('\n') + (normNodes.length ? '\n' : ''));
   writeAtomic(edgesPath(rootDir), normEdges.map((e) => JSON.stringify(e)).join('\n') + (normEdges.length ? '\n' : ''));
   const meta = {
+    schemaVersion: 1,
     generatedAt,
     sourceHash,
+    sourceHashes: sourceHashes || null,
     nodeCount: normNodes.length,
     edgeCount: normEdges.length,
     nodesByType: countBy(normNodes, 'type'),

package/lib/graph/validate.mjs

@@ -0,0 +1,161 @@
+/**
+ * lib/graph/validate.mjs — living-graph structural validation.
+ *
+ * validateGraph() checks workflow→provider→tool requires-edges, provider-manifest
+ * disk presence, doc-file existence, capability test coverage (LMCP-C5,
+ * sourced from lib/graph/gaps.mjs so `graph validate` and
+ * `graph missing-tests` never disagree), workflow-manifest liveness
+ * (roleChain resolution, skill existence, acyclic handoffs, surface/mode
+ * reachability — LMCP-C11, lib/workflows/liveness.mjs), and workflow
+ * surface parity (declared `surfaces` vs actual CLI/MCP/SDK registration —
+ * LMCP-D4, lib/workflows/surface-parity.mjs), classifying each gap
+ * as error vs warning per deployment mode (solo lenient, team/enterprise
+ * strict). Backs `construct graph validate`.
+ */
+
+import { loadGraph, nodesByType, dependenciesOf, dependentsOf } from './store.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { loadAllWorkflows } from '../workflows/loader.mjs';
+import { checkWorkflowLiveness } from '../workflows/liveness.mjs';
+import { checkSurfaceParity } from '../workflows/surface-parity.mjs';
+import { findMissingTestCapabilities } from './gaps.mjs';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+const MANIFESTS_REL_DIR = path.join('lib', 'extensions', 'manifests');
+
+export function nodeParts(id) {
+  const colon = id.indexOf(':');
+  return colon === -1 ? { type: null, key: id } : { type: id.slice(0, colon), key: id.slice(colon + 1) };
+}
+
+export function validateGraph(rootDir, { strict = false, deploymentMode } = {}) {
+  const graph = loadGraph(rootDir);
+  if (!graph.exists) {
+    return { valid: false, errors: ['no graph found — run construct graph build first'], warnings: [], infos: [] };
+  }
+
+  const mode = deploymentMode || getDeploymentMode(process.env, { cwd: rootDir });
+  const isStrict = mode === 'team' || mode === 'enterprise' || strict;
+
+  const errors = [];
+  const warnings = [];
+  const infos = [];
+
+  const workflowNodes = nodesByType(graph, 'workflow');
+  for (const wf of workflowNodes) {
+    const embeddingCaps = dependentsOf(graph, wf.id, 'embeds');
+    for (const capId of embeddingCaps) {
+      const usedToolIds = dependenciesOf(graph, capId, 'uses')
+        .filter(id => id.startsWith('provider:'));
+      for (const providerId of usedToolIds) {
+        const providerToolIds = dependenciesOf(graph, providerId, 'requires');
+        const hasRequiredTools = providerToolIds.some(toolId =>
+          dependenciesOf(graph, capId, 'requires').includes(toolId)
+        );
+        if (!hasRequiredTools) {
+          const providerName = nodeParts(providerId).key;
+          const msg = `workflow '${wf.name || wf.id}' embeds capability '${capId}' missing 'requires' edge to provider tools for '${providerName}'`;
+          if (isStrict) errors.push(msg); else warnings.push(msg);
+        }
+      }
+    }
+  }
+
+  const providerNodes = nodesByType(graph, 'provider');
+  for (const provider of providerNodes) {
+    const providerName = provider.attrs?.id || nodeParts(provider.id).key;
+    const manifestPath = path.join(rootDir, MANIFESTS_REL_DIR, `${providerName}.manifest.json`);
+    if (!existsSync(manifestPath)) {
+      const msg = `provider '${provider.id}' has no manifest on disk at ${path.relative(rootDir, manifestPath)}`;
+      if (isStrict) errors.push(msg); else warnings.push(msg);
+    }
+  }
+
+  const docNodes = nodesByType(graph, 'doc');
+  for (const doc of docNodes) {
+    const docRel = doc.attrs?.path || nodeParts(doc.id).key;
+    if (docRel) {
+      const resolved = path.isAbsolute(docRel) ? docRel : path.join(rootDir, docRel);
+      if (!existsSync(resolved)) {
+        const msg = `doc '${doc.id}' references file '${resolved}' that does not exist`;
+        if (isStrict) errors.push(msg); else warnings.push(msg);
+      }
+    }
+  }
+
+  // Capability test coverage (LMCP-C5): sourced from the same
+  // findMissingTestCapabilities the `missing-tests` gap query uses, so the
+  // two never drift out of consistency with each other.
+  const gaps = findMissingTestCapabilities(rootDir);
+  for (const capId of gaps.capabilities) {
+    const msg = `capability '${capId}' has zero validating tests`;
+    if (isStrict) errors.push(msg); else warnings.push(msg);
+  }
+  for (const wfId of gaps.workflows) {
+    const msg = `workflow '${wfId}' has zero validated embedding capability`;
+    if (isStrict) errors.push(msg); else warnings.push(msg);
+  }
+
+  // Embed-node integrity (LMCP-P6): every binding an embed manifest declares
+  // must resolve to a real node. A `uses`/`owned_by`/`governed_by` edge whose
+  // target node is absent is a broken binding — the manifest names a provider,
+  // specialist, or contract that does not exist in the graph — and is drift the
+  // C8 gate must catch. An embed with zero validating tests is treated like an
+  // untested capability so presets cannot silently lose coverage.
+  const embedTargetRels = [
+    ['uses', 'provider'],
+    ['owned_by', 'specialist'],
+    ['governed_by', 'contract'],
+  ];
+  for (const embed of nodesByType(graph, 'embed')) {
+    for (const [rel, kind] of embedTargetRels) {
+      for (const targetId of dependenciesOf(graph, embed.id, rel)) {
+        if (!graph.nodes.has(targetId)) {
+          const msg = `embed '${embed.name || embed.id}' binds ${kind} '${targetId}' which has no node in the graph`;
+          if (isStrict) errors.push(msg); else warnings.push(msg);
+        }
+      }
+    }
+    if (dependentsOf(graph, embed.id, 'validates').length === 0) {
+      const msg = `embed '${embed.name || embed.id}' has zero validating tests`;
+      if (isStrict) errors.push(msg); else warnings.push(msg);
+    }
+  }
+
+  // Security-coverage edge integrity (LMCP-N8): a `@secures <id>` tag that
+  // names a workflow/embed with no node is a typo'd or stale link that would
+  // silently contribute zero coverage — flag the dangling target.
+  for (const edge of graph.edges) {
+    if (edge.rel !== 'secures') continue;
+    if (!graph.nodes.has(edge.to)) {
+      const msg = `security test '${edge.from}' @secures '${edge.to}' which has no node in the graph`;
+      if (isStrict) errors.push(msg); else warnings.push(msg);
+    }
+  }
+
+  // Workflow liveness (LMCP-C11): schema validation only checks shape; these
+  // checks catch a roleChain naming a nonexistent specialist, a circular
+  // handoff, or a workflow no surface/mode can reach — failures that
+  // otherwise surface only at workflow-run time.
+  const { workflows } = loadAllWorkflows({ rootDir });
+  const { violations } = checkWorkflowLiveness(workflows, { rootDir });
+  for (const msg of violations) {
+    if (isStrict) errors.push(msg); else warnings.push(msg);
+  }
+
+  // Workflow surface parity (LMCP-D4): a manifest's declared `surfaces` must
+  // match its actual CLI/MCP registration (both wrap the same invokeWorkflow
+  // core, so any undeclared divergence is a real authoring drift, not a
+  // runtime possibility) — an undeclared mismatch is always an error,
+  // regardless of deployment mode, since it is never a matter of team policy.
+  const { errors: surfaceErrors, infos: surfaceInfos } = checkSurfaceParity(workflows);
+  errors.push(...surfaceErrors);
+  infos.push(...surfaceInfos);
+
+  infos.push('degraded_by check: not yet implemented (no degraded_by edges in C1 scope)');
+  infos.push('evidenced_by edges: sourced from persisted orchestration runs (LMCP-C9, see lib/graph/runtime-evidence.mjs and `graph explain`)');
+
+  const valid = errors.length === 0;
+  return { valid, errors, warnings, infos };
+}

package/lib/headhunt.mjs

@@ -16,6 +16,7 @@ import { selectOption } from './tty-prompts.mjs';
 import { resolveActiveScope } from './scopes/loader.mjs';
 import { classifyObjectiveForScope } from './scopes/teams.mjs';
 import { loadRegistry } from './registry/loader.mjs';
+import { isMainModule } from './roots.mjs';
 
 const OVERLAY_DIRNAME = 'domain-overlays';
 const PROMOTION_DIRNAME = 'promotion-requests';
@@ -102,7 +103,7 @@ export function classifyOverlay(objective = '', explicitTeam = '', { cwd = proce
   if (/runbook|docs|documentation|guide|onboard/.test(text)) {
     return {
       focus: 'documentation',
-      attachTo: ['cx-docs-keeper', 'cx-researcher'],
+      attachTo: ['cx-operations', 'cx-researcher'],
       teamFocus: 'operations-group',
       recommendedTeam: 'operations-group',
     };
@@ -292,10 +293,10 @@ export function promoteHeadhunt(id, { cwd = process.cwd(), owner = null } = {})
     attachTo: overlayEntry.record.attachTo,
     focus: overlayEntry.record.focus,
     sourceOverlay: overlayEntry.filePath,
-    reviewFlow: ['cx-architect', 'cx-devil-advocate', 'cx-docs-keeper'],
+    reviewFlow: ['cx-architect', 'cx-reviewer', 'cx-operations'],
     challenge: {
       required: true,
-      owner: 'cx-devil-advocate',
+      owner: 'cx-reviewer',
       status: 'pending',
       reason: 'Persistent capabilities must be challenged before promotion.',
     },
@@ -313,7 +314,7 @@ export function updatePromotionChallenge(id, { cwd = process.cwd(), status, note
   const requestPath = path.join(getPromotionDir(root), `${id}.json`);
   const request = readJsonIfExists(requestPath);
   if (!request) throw new Error(`Unknown promotion request: ${id}`);
-  request.challenge = request.challenge || { required: true, owner: 'cx-devil-advocate', status: 'pending' };
+  request.challenge = request.challenge || { required: true, owner: 'cx-reviewer', status: 'pending' };
   if (status) request.challenge.status = status;
   if (note) request.challenge.note = note;
   request.updatedAt = new Date().toISOString();
@@ -539,7 +540,7 @@ export async function runHeadhunt({ args = [], cwd = process.cwd(), homeDir = os
       promotionGates: buildPromotionGates(),
       challenge: permanence === 'temporary' ? null : {
         required: true,
-        owner: 'cx-devil-advocate',
+        owner: 'cx-reviewer',
         status: 'pending',
         reason: 'Promotion requests must be challenged before any persistent capability is added.',
       },
@@ -587,10 +588,10 @@ export async function runHeadhunt({ args = [], cwd = process.cwd(), homeDir = os
         attachTo: classification.attachTo,
         focus: classification.focus,
         sourceOverlay: overlayJsonPath,
-        reviewFlow: ['cx-architect', 'cx-devil-advocate', 'cx-docs-keeper'],
+        reviewFlow: ['cx-architect', 'cx-reviewer', 'cx-operations'],
         challenge: {
           required: true,
-          owner: 'cx-devil-advocate',
+          owner: 'cx-reviewer',
           status: 'pending',
           reason: 'Promotion requests must be challenged before any persistent capability is added.',
         },
@@ -617,7 +618,7 @@ export async function runHeadhunt({ args = [], cwd = process.cwd(), homeDir = os
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   runHeadhunt({ args: process.argv.slice(2) }).catch((error) => {
     process.stderr.write(`Error: ${error.message}\n`);
     process.exit(1);

package/lib/health-check.mjs

@@ -12,6 +12,7 @@ import path from 'node:path';
 import { existsSync, readFileSync, chmodSync } from 'node:fs';
 import { extractOpRef, hasAnySecret, hasSecret } from './providers/secret-resolver.mjs';
 import { configDir } from './config/xdg.mjs';
+import { getDeploymentMode } from './deployment-mode.mjs';
 
 const isWindows = os.platform() === 'win32';
 
@@ -61,16 +62,22 @@ export async function checkPrerequisites(options = {}) {
   const missing = [];
   const warnings = [];
   
-  // Check Docker
+  // Docker is required only when the deployment mode uses Docker worker pools (team/enterprise).
+  // Solo mode uses embedded LanceDB + Git-backed state; Postgres was removed, so Docker is optional.
+  const deploymentMode = getDeploymentMode(process.env);
+  const dockerRequired = deploymentMode === 'team' || deploymentMode === 'enterprise';
+
   const dockerVersion = getVersion('docker');
   const hasDocker = !!dockerVersion;
   checks.push({
     name: 'Docker',
-    required: true,
+    required: dockerRequired,
     installed: hasDocker,
     version: dockerVersion,
-    why: 'Required for managed Postgres; trace capture works locally without Docker',
-    install: isWindows 
+    why: dockerRequired
+      ? 'Required for Docker worker pool in team/enterprise mode'
+      : 'Optional in solo mode (required for team/enterprise)',
+    install: isWindows
       ? 'https://docs.docker.com/desktop/install/windows-install/'
       : 'https://docs.docker.com/get-docker/',
   });
@@ -403,9 +410,10 @@ export async function quickHealthCheck(options = {}) {
   const { homeDir, showCredentials = false } = options;
   
   const critical = [];
-  
-  // Silent Docker check
-  if (!commandExists('docker')) {
+
+  // Docker is only critical in team/enterprise mode where Docker worker pools are required.
+  const deployMode = getDeploymentMode(process.env);
+  if ((deployMode === 'team' || deployMode === 'enterprise') && !commandExists('docker')) {
     critical.push('Docker');
   }
   

package/lib/hook-health.mjs

@@ -436,7 +436,7 @@ export function formatHealthStatus(health) {
     output += `\nCRITICAL ISSUES:\n`;
     output += `The following hooks are critical and not functioning:\n`;
     output += health.criticalFailed.join(', ') + '\n';
-    output += `\nRecommendation: Run \`construct doctor hooks --fix\` to attempt repair\n`;
+    output += `\nRecommendation: Run \`construct hooks:health --fix\` to attempt repair\n`;
   }
   
   return output;