@geraldmaron/construct 1.0.20 → 1.0.23

package/lib/orchestration/worker.mjs

@@ -0,0 +1,215 @@
+/**
+ * lib/orchestration/worker.mjs — provider-backed worker backend for the local
+ * orchestration runtime.
+ *
+ * The inline backend (runtime.mjs) PREPARES a specialist task and stops short of
+ * model reasoning (ADR-0020). The provider backend closes that gap: it EXECUTES
+ * one specialist task by calling the configured provider/model with the
+ * specialist's persona prompt as system context and the run's request as the
+ * user turn, returning the model's real output (ADR-0021). Because it genuinely
+ * runs the model, the prepare-only disclaimer does not apply to provider-executed
+ * tasks — runtime.mjs records `task.output` and `executor='provider:<provider>:<model>'`
+ * so a host can distinguish prepared from executed work.
+ *
+ * Provider selection mirrors lib/ingest/provider-extract.mjs: Anthropic
+ * `/v1/messages` for Claude-family models, OpenRouter `/v1/chat/completions`
+ * otherwise; key resolution reads env (ANTHROPIC_API_KEY / OPENROUTER_API_KEY)
+ * and augments with ambient dotenv only when the caller did not inject an
+ * explicit env (hermetic-when-explicit). `fetchImpl` is injectable so the path is
+ * exercised end to end against a mock provider without a live key. Failures
+ * surface as structured codes (PROVIDER_KEY_MISSING, PROVIDER_MODEL_UNRESOLVED,
+ * PROVIDER_EXECUTION_FAILED) rather than opaque HTTP errors.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export const INLINE = 'inline';
+export const PROVIDER = 'provider';
+export const WORKER_BACKEND_SET = [INLINE, PROVIDER];
+
+const MAX_OUTPUT_TOKENS = 2048;
+
+// Extended-thinking budget requested only when a caller opts into reasoning
+// capture (chainOfThought !== 'hidden'). Anthropic requires budget_tokens < the
+// turn's max_tokens, so the budget is added on top of the output ceiling.
+
+const REASONING_BUDGET_TOKENS = 1024;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PROMPTS_DIR = join(HERE, '..', '..', 'specialists', 'prompts');
+
+function providerError(code, reason, remediation) {
+  const err = new Error(reason);
+  err.code = code;
+  err.remediation = remediation;
+  return err;
+}
+
+function isAnthropic(provider, model) {
+  return /anthropic|claude/i.test(provider || '') || /claude/i.test(model || '');
+}
+
+// Extended-thinking shape is model-specific. Opus 4.8 / 4.7 REJECT the legacy
+// `{type:'enabled', budget_tokens}` form with a 400 and require adaptive
+// thinking; Opus 4.6 and Sonnet 4.6 recommend adaptive too. Only genuinely
+// older models (Sonnet 4.5 and earlier) still take the budget form. On adaptive
+// models `display:'summarized'` is required, or returned thinking blocks carry
+// empty text. (Source: claude-api skill — extended/adaptive thinking; ADR-0030.)
+
+function anthropicThinkingConfig(model) {
+  const adaptive = /(opus-4-(?:[6-9]|\d\d)|sonnet-4-(?:[6-9]|\d\d))/i.test(model || '');
+  return adaptive
+    ? { type: 'adaptive', display: 'summarized' }
+    : { type: 'enabled', budget_tokens: REASONING_BUDGET_TOKENS };
+}
+
+// Key resolution mirrors provider-extract: env first, then the two cheap dotenv
+// files, and only when the caller did not inject an explicit env. A caller that
+// passes its own env object (embedded callers, tests) is authoritative and
+// hermetic — ambient discovery is suppressed so a developer's real key never
+// bleeds into a test run.
+
+function resolveKey(varName, env, allowAmbient) {
+  if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
+  if (!allowAmbient) return null;
+  for (const file of [join(homedir(), '.construct', 'config.env'), join(homedir(), '.env')]) {
+    try {
+      if (!existsSync(file)) continue;
+      const m = readFileSync(file, 'utf8').match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
+      if (m && m[1]) return m[1].trim();
+    } catch { /* unreadable dotenv is not authoritative */ }
+  }
+  return null;
+}
+
+// The persona prompt is the specialist's system context. It lives in
+// specialists/prompts/cx-<role>.md; absent that file, a minimal role-named system
+// prompt keeps the backend functional rather than failing on a missing persona.
+
+function loadPersona(role) {
+  const slug = String(role || '').replace(/^cx-/, '');
+  const file = join(PROMPTS_DIR, `cx-${slug}.md`);
+  try {
+    if (existsSync(file)) return readFileSync(file, 'utf8');
+  } catch { /* unreadable persona falls back to the minimal prompt */ }
+  return `You are the ${slug} specialist. Execute your part of the request within your role and return your result directly.`;
+}
+
+function buildUserPrompt({ task, run }) {
+  const summary = run?.request?.summary || '';
+  const reason = task?.reason ? `\n\nWhy you were dispatched: ${task.reason}` : '';
+  const handoff = task?.handoffContract ? `\nHandoff contract: ${task.handoffContract}` : '';
+  return `Request: ${summary}${reason}${handoff}\n\nDo your part of this request as the ${String(task?.role || '').replace(/^cx-/, '')} specialist. Return your result directly.`;
+}
+
+async function bodyExcerpt(res) {
+  try {
+    return (await res.text()).slice(0, 200);
+  } catch {
+    return '';
+  }
+}
+
+// OpenRouter normalizes reasoning into a plaintext `reasoning` string and/or a
+// structured `reasoning_details` array (text / summary / encrypted entries). We
+// read the plaintext first, then assemble any readable detail entries; encrypted
+// carriers have no displayable text and are skipped.
+
+function extractOpenRouterReasoning(message) {
+  if (typeof message.reasoning === 'string' && message.reasoning.trim()) return message.reasoning.trim();
+  const details = Array.isArray(message.reasoning_details) ? message.reasoning_details : [];
+  return details.map((d) => d?.text || d?.summary || '').filter(Boolean).join('\n').trim();
+}
+
+async function callAnthropic({ model, apiKey, system, user, fetchImpl, reasoning }) {
+  const thinking = reasoning ? anthropicThinkingConfig(model) : null;
+  const body = {
+    model: model.replace(/^anthropic\//, ''),
+    max_tokens: thinking ? MAX_OUTPUT_TOKENS + REASONING_BUDGET_TOKENS : MAX_OUTPUT_TOKENS,
+    system,
+    messages: [{ role: 'user', content: [{ type: 'text', text: user }] }],
+  };
+  if (thinking) body.thinking = thinking;
+  const res = await fetchImpl('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXECUTION_FAILED', `Anthropic specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and ANTHROPIC_API_KEY, or set orchestration.workerBackend to "inline".');
+  }
+  const data = await res.json();
+  const blocks = data.content || [];
+  const output = blocks.filter((b) => b && b.type === 'text').map((b) => b.text).join('');
+  const thought = blocks.filter((b) => b && b.type === 'thinking').map((b) => b.thinking || '').join('').trim();
+  return { output, reasoning: thought };
+}
+
+async function callOpenRouter({ model, apiKey, system, user, fetchImpl, reasoning }) {
+  const body = {
+    model: model.replace(/^openrouter\//, ''),
+    max_tokens: MAX_OUTPUT_TOKENS,
+    messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+  };
+  // Enable reasoning when wanted; explicitly exclude it otherwise — some models
+  // (e.g. Gemini) return reasoning by default, which would leak in hidden mode.
+  // An empty `{}` is a no-op on OpenRouter; `{enabled:true}` is the on switch.
+  body.reasoning = reasoning ? { enabled: true } : { exclude: true };
+  const res = await fetchImpl('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', 'HTTP-Referer': 'https://github.com/geraldmaron/construct' },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXECUTION_FAILED', `OpenRouter specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and OPENROUTER_API_KEY, or set orchestration.workerBackend to "inline".');
+  }
+  const data = await res.json();
+  const message = data.choices?.[0]?.message || {};
+  return { output: message.content || '', reasoning: reasoning ? extractOpenRouterReasoning(message) : '' };
+}
+
+/**
+ * Execute one specialist task via the configured provider/model.
+ *
+ * @param {object} opts
+ * @param {object} opts.task            the run task (carries role, reason, handoffContract)
+ * @param {object} opts.run             the run (carries request summary)
+ * @param {string} opts.model           resolved provider model id
+ * @param {string} [opts.provider]      resolved provider id (selects the API)
+ * @param {Record<string,string>} [opts.env]
+ * @param {Function} [opts.fetchImpl]   injectable fetch (for tests)
+ * @param {string} [opts.chainOfThought] reasoning disclosure mode: `hidden` (default,
+ *        no reasoning requested) | `surface` | `telemetry_only` (both request and
+ *        return the model's reasoning for the caller to display or record)
+ * @returns {Promise<{output:string, reasoning:string, model:string, provider:string, characters:number}>}
+ */
+export async function runTaskViaProvider({ task, run, model, provider = null, env = process.env, fetchImpl = globalThis.fetch, chainOfThought = 'hidden' } = {}) {
+  if (!model) throw providerError('PROVIDER_MODEL_UNRESOLVED', 'Provider worker backend selected but no model resolved.', 'Configure the model tier registry so a model resolves, or set orchestration.workerBackend to "inline".');
+  if (typeof fetchImpl !== 'function') throw providerError('PROVIDER_NO_FETCH', 'No fetch implementation available for provider execution.', 'Run on a runtime with global fetch (Node 18+) or inject fetchImpl.');
+
+  const anthropic = isAnthropic(provider, model);
+  const keyVar = anthropic ? 'ANTHROPIC_API_KEY' : 'OPENROUTER_API_KEY';
+  const apiKey = resolveKey(keyVar, env, env === process.env);
+  if (!apiKey) {
+    throw providerError('PROVIDER_KEY_MISSING', `No API key for ${anthropic ? 'Anthropic' : 'OpenRouter'} specialist execution.`, `Set ${keyVar}, or set orchestration.workerBackend to "inline".`);
+  }
+
+  const system = loadPersona(task?.role);
+  const user = buildUserPrompt({ task, run });
+  const wantsReasoning = chainOfThought !== 'hidden';
+  const { output, reasoning } = anthropic
+    ? await callAnthropic({ model, apiKey, system, user, fetchImpl, reasoning: wantsReasoning })
+    : await callOpenRouter({ model, apiKey, system, user, fetchImpl, reasoning: wantsReasoning });
+
+  const text = output || '';
+  return {
+    output: text,
+    reasoning: wantsReasoning ? (reasoning || '') : '',
+    model,
+    provider: anthropic ? 'anthropic' : 'openrouter',
+    characters: text.length,
+  };
+}

package/lib/orchestration-policy.mjs

@@ -370,9 +370,9 @@ export function formatOverlaySelection(roleFlavors) {
 export function detectRiskFlags(request = '') {
   const text = String(request).toLowerCase();
   return {
-    architecture: containsAny(text, ['architecture', 'interface contract', 'api contract', 'dependency', 'module boundary', 'data model', 'indexing', 'retrieval design']),
-    security: containsAny(text, ['security', 'permission', 'secret', 'privacy', 'payment', 'authentication', 'authorization']),
-    dataIntegrity: containsAny(text, ['migration', 'data', 'sync', 'consistency', 'state']),
+    architecture: containsAny(text, ['architecture', 'interface contract', 'api contract', 'dependency', 'module boundary', 'data model', 'indexing', 'retrieval design', 'terraform', 'infrastructure', 'iac', 'provisioning', 'blast radius', 'rollout', 'deployment strategy']),
+    security: containsAny(text, ['security', 'permission', 'secret', 'privacy', 'payment', 'authentication', 'authorization', 'credential', 'oidc', 'iam', 'access token']),
+    dataIntegrity: containsAny(text, ['migration', 'data', 'sync', 'consistency', 'state', 'tfstate', 'drift']),
     ui: containsAny(text, ['ui', 'ux', 'design system', 'screen', 'layout', 'visual', 'onboarding']) && !containsAny(text, ['requirements']),
     docs: containsAny(text, ['docs', 'readme', 'runbook', 'adr']),
     ai: containsAny(text, ['llm', ' agent', 'prompt', 'rag', 'model behavior', 'retrieval', 'embedding', 'vector']),
@@ -594,6 +594,30 @@ export function buildDispatchPlan({ track, intent, specialists = [] }) {
   return `Plan: ${phases.join(' → ')}.`;
 }
 
+// Format active flavor overlays into a one-line trace, e.g.
+//   "Overlays: architect=platform (matched kubernetes, infra), engineer=ai (matched llm, agent)"
+
+export function formatOverlayTrace(roleFlavors = {}, request = '') {
+  const text = String(request).toLowerCase();
+  const active = Object.entries(roleFlavors).filter(([, flavor]) => flavor);
+  if (active.length === 0) return '';
+  const FLAVOR_KEYWORDS = {
+    architect: ['agent', 'rag', 'retrieval', 'embedding', 'integration', 'webhook', 'warehouse', 'schema', 'sso', 'rbac', 'platform', 'kubernetes', 'infra'],
+    productManager: ['platform', 'api', 'enterprise', 'ai product', 'agent', 'growth', 'activation'],
+    qa: ['agent', 'prompt', 'api', 'sdk', 'pipeline', 'etl', 'ui', 'ux', 'accessibility'],
+    security: ['prompt injection', 'privacy', 'pii', 'dependency', 'cloud', 'iam', 'auth', 'xss', 'csrf'],
+    dataAnalyst: ['experiment', 'a/b', 'telemetry', 'metric', 'funnel'],
+    dataEngineer: ['vector', 'embedding', 'warehouse', 'pipeline', 'etl', 'pgvector'],
+    engineer: ['llm', 'agent', 'rag', 'kubernetes', 'k8s', 'terraform', 'infra', 'docker', 'pipeline', 'etl', 'data model'],
+  };
+  const parts = active.map(([role, flavor]) => {
+    const kws = (FLAVOR_KEYWORDS[role] || []).filter((kw) => text.includes(kw));
+    const matched = kws.slice(0, 3).join(', ');
+    return matched ? `${role}=${flavor} (matched ${matched})` : `${role}=${flavor}`;
+  });
+  return `Overlays: ${parts.join(', ')}`;
+}
+
 export function routeRequest(options = {}) {
   const intent = classifyIntent(options.request);
   const riskFlags = detectRiskFlags(options.request);

package/lib/parity.mjs

@@ -18,7 +18,7 @@
  *   opencode  ~/.config/opencode/opencode.json (agent table)
  *   codex     ~/.codex/agents/*.toml
  *   copilot   ~/.github/prompts/*.prompt.md
- *   vscode    VS Code user settings (github.copilot.mcpServers)
+ *   vscode    VS Code user mcp.json (servers)
  *   cursor    ~/.cursor/mcp.json
  */
 
@@ -30,6 +30,38 @@ import { fileURLToPath } from 'node:url';
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(MODULE_DIR, '..');
 
+// VS Code and Cursor user settings are JSONC: line/block comments and trailing
+// commas are valid and common. Strict JSON.parse rejects them, producing a
+// false "unreadable" parity failure on a perfectly valid editor config. This
+// strips comments string-aware (so `//` inside a "https://…" value survives)
+// and drops trailing commas before parsing.
+
+function parseJsonc(text) {
+  let out = '';
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (inString) {
+      out += ch;
+      if (escaped) escaped = false;
+      else if (ch === '\\') escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; out += ch; continue; }
+    if (ch === '/' && next === '/') { while (i < text.length && text[i] !== '\n') i += 1; out += '\n'; continue; }
+    if (ch === '/' && next === '*') { i += 2; while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1; i += 1; continue; }
+    out += ch;
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1'));
+}
+
+function readJsoncFile(file) {
+  return parseJsonc(fs.readFileSync(file, 'utf8'));
+}
+
 function loadRegistry(rootDir = ROOT_DIR) {
   const file = path.join(rootDir, 'specialists', 'registry.json');
   return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -90,57 +122,68 @@ function checkFileSurface({ surface, kind, dir, extension, expected }) {
   };
 }
 
-function getVSCodeSettingsPaths(homeDir) {
+function getVSCodeUserMcpPaths(homeDir) {
   const platform = os.platform();
   if (platform === 'darwin') {
     return [
-      path.join(homeDir, 'Library', 'Application Support', 'Code', 'User', 'settings.json'),
-      path.join(homeDir, 'Library', 'Application Support', 'Code - Insiders', 'User', 'settings.json'),
+      path.join(homeDir, 'Library', 'Application Support', 'Code', 'User', 'mcp.json'),
+      path.join(homeDir, 'Library', 'Application Support', 'Code - Insiders', 'User', 'mcp.json'),
     ];
   }
   if (platform === 'linux') {
     return [
-      path.join(homeDir, '.config', 'Code', 'User', 'settings.json'),
-      path.join(homeDir, '.config', 'Code - Insiders', 'User', 'settings.json'),
+      path.join(homeDir, '.config', 'Code', 'User', 'mcp.json'),
+      path.join(homeDir, '.config', 'Code - Insiders', 'User', 'mcp.json'),
     ];
   }
   if (platform === 'win32') {
     const appData = process.env.APPDATA ?? path.join(homeDir, 'AppData', 'Roaming');
     return [
-      path.join(appData, 'Code', 'User', 'settings.json'),
-      path.join(appData, 'Code - Insiders', 'User', 'settings.json'),
+      path.join(appData, 'Code', 'User', 'mcp.json'),
+      path.join(appData, 'Code - Insiders', 'User', 'mcp.json'),
     ];
   }
   return [];
 }
 
 function checkClaude(registry, { homeDir = os.homedir() } = {}) {
-  const expected = entriesForSurface(registry, 'claude');
+  // Global ~/.claude/agents ships no agent — the project orchestrator is the
+  // front door, and a global agent doubles in editors that read both scopes
+  // (VS Code). The expected user-scope set is therefore empty.
   return checkFileSurface({
     surface: 'claude',
     kind: 'agents',
     dir: path.join(homeDir, '.claude', 'agents'),
     extension: '.md',
-    expected,
+    expected: [],
   });
 }
 
+const OPENCODE_BUILTIN_AGENTS = new Set(['title', 'summary', 'compaction']);
+
 function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
   const file = path.join(homeDir, '.config', 'opencode', 'opencode.json');
   if (!fs.existsSync(file)) return { surface: 'opencode', kind: 'agents', status: 'absent', file };
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    config = readJsoncFile(file);
   } catch (err) {
     return { surface: 'opencode', kind: 'agents', status: 'unreadable', file, error: err.message };
   }
   const expected = entriesForSurface(registry, 'opencode');
-  const actual = Object.keys(config.agent || config.agents || {});
+  const actual = Object.keys(config.agent || config.agents || {})
+    .filter((id) => !OPENCODE_BUILTIN_AGENTS.has(id));
   const { missing, extra } = diffSets(expected, actual);
+
+  // OpenCode's own system agents (title/summary/compaction) are filtered from
+  // `actual` above, so any remaining extra is real drift here. checkParity then
+  // reclassifies drift → legacy-install when every extra is a registry cx-*
+  // specialist (a soft upgrade state), via reclassifyLegacy.
+
   return {
     surface: 'opencode',
     kind: 'agents',
-    status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
+    status: (missing.length === 0 && extra.length === 0) ? 'ok' : 'drift',
     file,
     expectedCount: expected.length,
     actualCount: actual.length,
@@ -177,19 +220,27 @@ function checkCopilot(registry, { homeDir = os.homedir() } = {}) {
 }
 
 function checkVSCode(registry, { homeDir = os.homedir() } = {}) {
-  const paths = getVSCodeSettingsPaths(homeDir).filter((settingsPath) => fs.existsSync(settingsPath));
-  if (paths.length === 0) return { surface: 'vscode', kind: 'mcps', status: 'absent', paths };
   const expected = Object.keys(registry.mcpServers ?? {}).filter((id) => id !== 'memory');
   const actualSet = new Set();
-  for (const settingsPath of paths) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-      for (const id of Object.keys(settings['github.copilot.mcpServers'] ?? {})) actualSet.add(id);
-    } catch (err) {
-      return { surface: 'vscode', kind: 'mcps', status: 'unreadable', file: settingsPath, error: err.message };
-    }
+  const paths = [];
+
+  // An empty or hand-malformed user `mcp.json` is a normal VS Code state (a
+  // 0-byte file is common) — global Construct MCP is opt-in there, so an
+  // unparseable file counts as "not configured", not a hard parity failure.
+
+  for (const mcpPath of getVSCodeUserMcpPaths(homeDir)) {
+    if (!fs.existsSync(mcpPath)) continue;
+    if (!fs.readFileSync(mcpPath, 'utf8').trim()) continue;
+    let config;
+    try { config = readJsoncFile(mcpPath); } catch { continue; }
+    paths.push(mcpPath);
+    for (const id of Object.keys(config.servers ?? {})) actualSet.add(id);
   }
-  const actual = [...actualSet].sort();
+  if (paths.length === 0) return { surface: 'vscode', kind: 'mcps', status: 'absent', paths };
+
+  // `memory` is the optional local cm bridge — sync writes it, but it is not
+  // required (excluded from `expected`), so it must not count as drift-extra.
+  const actual = [...actualSet].filter((id) => id !== 'memory').sort();
   const { missing, extra } = diffSets(expected, actual);
   return {
     surface: 'vscode',
@@ -208,12 +259,12 @@ function checkCursor(registry, { homeDir = os.homedir() } = {}) {
   if (!fs.existsSync(file)) return { surface: 'cursor', kind: 'mcps', status: 'absent', file };
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    config = readJsoncFile(file);
   } catch (err) {
     return { surface: 'cursor', kind: 'mcps', status: 'unreadable', file, error: err.message };
   }
   const expected = Object.keys(registry.mcpServers ?? {}).filter((id) => id !== 'memory');
-  const actual = Object.keys(config.mcpServers ?? {});
+  const actual = Object.keys(config.mcpServers ?? {}).filter((id) => id !== 'memory');
   const { missing, extra } = diffSets(expected, actual);
   return {
     surface: 'cursor',
@@ -235,7 +286,10 @@ function checkCursor(registry, { homeDir = os.homedir() } = {}) {
 function legacyUserScopeRoster(registry) {
   const prefix = registry.prefix || 'cx';
   const specialists = (registry.specialists || []).map((s) => `${prefix}-${s.name}`);
-  return new Set(specialists);
+  // The front-door agent is project-scoped too now, so a leftover `construct.md`
+  // in user-scope `.claude/agents` is a soft upgrade state, not real drift.
+  const frontDoor = registry.orchestrator?.name ? [registry.orchestrator.name] : [];
+  return new Set([...specialists, ...frontDoor]);
 }
 
 /**

package/lib/policy/unified-gates.mjs

@@ -0,0 +1,96 @@
+// lib/policy/unified-gates.mjs
+// Single policy declaration for all enforcement layers
+
+export const POLICIES = {
+  commentStyle: {
+    id: 'comment-style',
+    description: 'Comments must follow project standards',
+    layers: ['write', 'commit', 'ci'],
+    bypass: 'CONSTRUCT_SKIP_COMMENT_STYLE',
+    critical: false,
+  },
+  docCoupling: {
+    id: 'doc-coupling',
+    description: 'Code changes require documentation updates',
+    layers: ['commit', 'push'],
+    bypass: 'CONSTRUCT_SKIP_DOCS',
+    critical: false,
+  },
+  secretScan: {
+    id: 'secret-scan',
+    description: 'No secrets in committed code',
+    layers: ['commit', 'push', 'ci'],
+    bypass: 'CONSTRUCT_SKIP_SECRET_SCAN',
+    critical: true,
+  },
+  ciStatus: {
+    id: 'ci-status',
+    description: 'CI must be green before push',
+    layers: ['push', 'session-end'],
+    bypass: 'CONSTRUCT_SKIP_CI_CHECK',
+    critical: true,
+  },
+};
+
+export class UnifiedGateEngine {
+  constructor(options = {}) {
+    this.env = options.env || process.env;
+  }
+  
+  isBypassed(policyId) {
+    const policy = POLICIES[policyId];
+    if (!policy) return { bypassed: false };
+    
+    if (policy.bypass && this.env[policy.bypass] === '1') {
+      return { bypassed: true, envVar: policy.bypass };
+    }
+    
+    if (this.env.CONSTRUCT_SKIP_ALL_GATES === '1') {
+      return { bypassed: true, envVar: 'CONSTRUCT_SKIP_ALL_GATES' };
+    }
+    
+    return { bypassed: false };
+  }
+  
+  async evaluateLayer(layer, context = {}) {
+    const results = [];
+    
+    for (const [id, policy] of Object.entries(POLICIES)) {
+      if (policy.layers.includes(layer)) {
+        const bypass = this.isBypassed(id);
+        results.push({
+          policy: id,
+          passed: bypass.bypassed || true,
+          bypassed: bypass.bypassed,
+          bypassEnvVar: bypass.envVar,
+          critical: policy.critical,
+        });
+      }
+    }
+    
+    const failed = results.filter(r => !r.passed && r.critical);
+    
+    return {
+      layer,
+      passed: failed.length === 0,
+      canProceed: failed.length === 0,
+      results,
+      summary: `${results.filter(r => r.passed).length}/${results.length} passed`,
+    };
+  }
+}
+
+export async function checkGates(layer, context = {}, options = {}) {
+  const engine = new UnifiedGateEngine(options);
+  return await engine.evaluateLayer(layer, context);
+}
+
+export function listPolicies() {
+  return Object.entries(POLICIES).map(([id, policy]) => ({
+    id,
+    description: policy.description,
+    layers: policy.layers,
+    bypass: policy.bypass,
+    critical: policy.critical,
+  }));
+}