@geraldmaron/construct 1.0.20 → 1.0.23

package/lib/hooks/orchestration-dispatch-guard.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/orchestration-dispatch-guard.mjs — backstop against solo-authoring an orchestrated deliverable.
+ *
+ * The orchestration_policy tool classifies a request into immediate / focused /
+ * orchestrated. An orchestrated verdict means the orchestrator must dispatch the
+ * specialist chain (cx-architect, cx-security, cx-devil-advocate, …) before
+ * authoring the deliverable — not write it solo. The persona instructs this, but
+ * instruction is not enforcement: this hook is the Claude-only barrier.
+ *
+ * Three roles, one file, branched on event + tool:
+ *  - PostToolUse on *orchestration_policy: record the verdict. orchestrated →
+ *    {pending:true,dispatched:false}; immediate/focused → cleared. Each new
+ *    classification resets state for the new request.
+ *  - PostToolUse on a dispatch tool (*orchestration_run, *worker_run, Task) →
+ *    {dispatched:true}: the chain is running, authoring is now legitimate.
+ *  - PreToolUse on Write|Edit|MultiEdit → block (exit 2) when a substantial
+ *    documentation/strategy deliverable is authored while pending && !dispatched.
+ *
+ * Scoped to documentation/strategy artifacts (.md outside the routine planning
+ * and tracking files), not code — solo code authoring is harder to separate
+ * from legitimate pre-dispatch scaffolding, so it is left to the persona
+ * contract rather than over-blocked here. Only the deterministic
+ * orchestrated-but-not-dispatched case blocks. Fails open on any internal error.
+ *
+ * @p95ms 8
+ * @maxBlockingScope orchestrated deliverable authoring without prior dispatch
+ *
+ * @lifecycle PreToolUse, PostToolUse
+ * @matcher Write|Edit|MultiEdit, mcp__.*__orchestration_policy, mcp__.*__orchestration_run, mcp__.*__worker_run, Task
+ * @exits 0 = pass · 2 = block (author after dispatch instead)
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, basename, relative, isAbsolute } from 'path';
+
+const STALE_MS = 2 * 60 * 60 * 1000;
+const SUBSTANTIAL_CHARS = 1500;
+const SUBSTANTIAL_LINES = 40;
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const event = input?.hook_event_name || '';
+const toolName = input?.tool_name || '';
+const cwd = input?.cwd || process.cwd();
+
+function statePath(root) {
+  return join(root, '.cx', 'runtime', 'orchestration-guard.json');
+}
+
+function readState(root) {
+  try { return JSON.parse(readFileSync(statePath(root), 'utf8')); } catch { return null; }
+}
+
+function writeState(root, state) {
+  try {
+    mkdirSync(join(root, '.cx', 'runtime'), { recursive: true });
+    writeFileSync(statePath(root), JSON.stringify(state));
+  } catch { /* fail open */ }
+}
+
+// The marker only lives inside an already-initialized construct project; never
+// seed .cx into a project that does not have it.
+
+function hasCx(root) {
+  return existsSync(join(root, '.cx'));
+}
+
+function isPolicyTool(name) {
+  return /orchestration_policy$/.test(name);
+}
+
+function isDispatchTool(name) {
+  return name === 'Task' || /orchestration_run$/.test(name) || /worker_run$/.test(name);
+}
+
+// PostToolUse: a classification verdict updates the marker. orchestrated arms
+// the guard; immediate/focused disarms it. The verdict text can be nested in an
+// MCP content envelope, so match against the stringified response.
+
+if (event === 'PostToolUse' && isPolicyTool(toolName)) {
+  if (!hasCx(cwd)) process.exit(0);
+  const blob = JSON.stringify(input?.tool_response ?? '').replace(/\\/g, '');
+  const orchestrated = /"track"\s*:\s*"orchestrated"/.test(blob);
+  if (orchestrated) writeState(cwd, { pending: true, dispatched: false, ts: Date.now() });
+  else writeState(cwd, { pending: false, ts: Date.now() });
+  process.exit(0);
+}
+
+if (event === 'PostToolUse' && isDispatchTool(toolName)) {
+  if (!hasCx(cwd)) process.exit(0);
+  const state = readState(cwd);
+  if (state?.pending) writeState(cwd, { ...state, dispatched: true });
+  process.exit(0);
+}
+
+// PreToolUse on an authoring tool: block only the deterministic failure — a
+// substantial documentation/strategy deliverable authored while a fresh
+// orchestrated verdict is pending and no dispatch has run.
+
+if (event === 'PreToolUse' && /^(Write|Edit|MultiEdit)$/.test(toolName)) {
+  if (!hasCx(cwd)) process.exit(0);
+  const state = readState(cwd);
+  if (!state?.pending || state?.dispatched) process.exit(0);
+  if (typeof state.ts === 'number' && Date.now() - state.ts > STALE_MS) process.exit(0);
+
+  const ti = input?.tool_input || {};
+  const filePath = ti.file_path || ti.filePath || '';
+  if (!isDeliverableArtifact(filePath, cwd)) process.exit(0);
+
+  const authored = authoredContent(toolName, ti);
+  const lineCount = authored ? authored.split('\n').length : 0;
+  if (authored.length < SUBSTANTIAL_CHARS && lineCount < SUBSTANTIAL_LINES) process.exit(0);
+
+  process.stderr.write(
+    '⛔ orchestration-dispatch-guard: orchestration_policy classified this request as ORCHESTRATED, '
+    + 'but no specialist dispatch (orchestration_run / Task) has run yet.\n'
+    + 'You may not author the deliverable solo. Emit the task-packet and dispatch the chain '
+    + '(e.g. cx-architect owns structure, cx-security challenges the credential/state model, '
+    + 'cx-devil-advocate pressure-tests the approach), then synthesize their verdicts in Construct\'s voice.\n'
+    + 'If this write IS post-dispatch synthesis, run the dispatch tool first so the guard clears.\n',
+  );
+  process.exit(2);
+}
+
+process.exit(0);
+
+// A deliverable is a markdown doc/strategy artifact outside the routine
+// planning and tracking files. Code paths are intentionally excluded — see
+// the file header.
+
+function isDeliverableArtifact(filePath, root) {
+  if (!filePath || !/\.mdx?$/.test(filePath)) return false;
+  let rel = filePath;
+  try { rel = isAbsolute(filePath) ? relative(root, filePath) : filePath; } catch { rel = filePath; }
+  rel = rel.replace(/\\/g, '/');
+  if (rel.startsWith('..')) return false;
+  if (rel.startsWith('.cx/')) return false;
+  const base = basename(rel).toLowerCase();
+  const routine = new Set(['plan.md', 'changelog.md', 'readme.md', 'agents.md', 'contributing.md']);
+  if (routine.has(base)) return false;
+  if (rel.startsWith('.cx/handoffs/') || rel.includes('/handoffs/')) return false;
+  return true;
+}
+
+function authoredContent(name, ti) {
+  if (name === 'Write') return String(ti.content ?? '');
+  if (name === 'Edit') return String(ti.new_string ?? '');
+  if (name === 'MultiEdit' && Array.isArray(ti.edits)) {
+    return ti.edits.map((e) => String(e?.new_string ?? '')).join('\n');
+  }
+  return '';
+}

package/lib/hooks/pre-push-gate.mjs

@@ -116,18 +116,27 @@ if (isGhPrCreate || isGhPrEdit) {
   echo();
 }
 
-// git push: refuse claude/* unconditionally.
-
-if (/\bclaude\//.test(command)) {
+// git push: refuse agent-prefixed branches. Match the branch name(s) actually
+// being pushed — the current branch plus any explicit refspec — anchored at the
+// start, so a `.claude/agents` path argument anywhere in the command does not
+// trip the gate.
+
+const AGENT_BRANCH_PREFIX = /^(claude|cursor|copilot|codex|aider|devin)\//;
+const pushTargets = [currentBranch()];
+const pushArgs = (command.match(/\bgit\s+push\b([^|;&\n]*)/)?.[1] || '')
+  .trim().split(/\s+/).filter((a) => a && !a.startsWith('-'));
+for (const arg of pushArgs.slice(1)) pushTargets.push(arg.split(':').pop());
+
+if (pushTargets.some((b) => b && AGENT_BRANCH_PREFIX.test(b))) {
   process.stderr.write(
-    `[pre-push-gate] Refusing to push a claude/* branch to remote (user policy).\n` +
+    `[pre-push-gate] Refusing to push an agent-prefixed branch to remote (user policy).\n` +
     `  Use a non-agent branch name.\n`,
   );
   emitRoleEvent({
     type: 'push_gate.fail',
-    summary: 'claude/* branch push refused',
+    summary: 'agent-prefixed branch push refused',
     hookInput: input,
-    context: { command },
+    context: { command, pushTargets },
   });
   process.exit(2);
 }

package/lib/hooks/stop-notify.mjs

@@ -155,8 +155,16 @@ const costLogPath = join(home, '.cx', 'session-cost.jsonl');
 const lastAgentPath = join(home, '.cx', 'last-agent.json');
 const checkpointPath = join(home, '.cx', 'transcript-checkpoints.json');
 
+// Consume-clear like warn-flags/files-changed below: a TS result is reported
+// once, not re-fired on every subsequent no-op Stop. stop-typecheck rewrites
+// the file each turn it actually runs.
 let tsResult = 'unchecked';
-try { tsResult = existsSync(tsResultPath) ? readFileSync(tsResultPath, 'utf8').trim() : 'unchecked'; } catch { /* non-critical */ }
+try {
+  if (existsSync(tsResultPath)) {
+    tsResult = readFileSync(tsResultPath, 'utf8').trim() || 'unchecked';
+    writeFileSync(tsResultPath, 'unchecked');
+  }
+} catch { /* non-critical */ }
 
 let warnings = [];
 try {
@@ -326,25 +334,32 @@ try {
   }
 } catch { /* review is best-effort */ }
 
+// Stop fires per-turn, so a desktop banner only earns the interruption when the
+// turn produced something actionable: files changed or a warning to review.
+// A bare "TS OK" (the sticky-pass default on a no-op turn) is noise — the ledger
+// and session bookkeeping above still run; only the banner is suppressed.
 const platform = process.platform;
-try {
-  if (platform === 'darwin') {
-    const escaped = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-    const titleEsc = title.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-    execSync(`osascript -e 'display notification "${escaped}" with title "${titleEsc}"'`, {
-      timeout: 5000,
-      stdio: 'pipe',
-    });
-  } else if (platform === 'linux') {
-    execSync(`notify-send "${title}" "${body.replace(/"/g, '\\"')}"`, {
-      timeout: 5000,
-      stdio: 'pipe',
-    });
-  } else {
+const shouldNotify = (hasWarnings || fileCount > 0) && Boolean(body);
+if (shouldNotify) {
+  try {
+    if (platform === 'darwin') {
+      const escaped = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+      const titleEsc = title.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+      execSync(`osascript -e 'display notification "${escaped}" with title "${titleEsc}"'`, {
+        timeout: 5000,
+        stdio: 'pipe',
+      });
+    } else if (platform === 'linux') {
+      execSync(`notify-send "${title}" "${body.replace(/"/g, '\\"')}"`, {
+        timeout: 5000,
+        stdio: 'pipe',
+      });
+    } else {
+      process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
+    }
+  } catch {
     process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
   }
-} catch {
-  process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
 }
 
 process.exit(0);

package/lib/hooks/stop-typecheck.mjs

@@ -31,8 +31,11 @@ const pending = existsSync(tcPath)
   ? readFileSync(tcPath, 'utf8').split('\n').filter(Boolean)
   : [];
 
+// No files queued means no typecheck ran this turn — record 'unchecked', not a
+// misleading 'pass'. A stale 'pass' here is what made stop-notify fire a bare
+// "TS OK" banner on every no-op turn.
 if (pending.length === 0) {
-  try { writeFileSync(tsResultPath, 'pass'); } catch { /* best effort */ }
+  try { writeFileSync(tsResultPath, 'unchecked'); } catch { /* best effort */ }
   process.exit(0);
 }
 
@@ -55,8 +58,10 @@ function findTsConfig(startDir) {
 const startDir = dirname(pending[0]);
 const tsconfig = findTsConfig(startDir);
 
+// Files were edited but no tsconfig governs them — the typecheck couldn't run,
+// so the honest state is 'unchecked', not 'pass'.
 if (!tsconfig) {
-  try { writeFileSync(tsResultPath, 'pass'); } catch { /* best effort */ }
+  try { writeFileSync(tsResultPath, 'unchecked'); } catch { /* best effort */ }
   process.exit(0);
 }
 

package/lib/host-capabilities.mjs

@@ -118,6 +118,15 @@ function detectCopilotAvailability(homeDir = os.homedir()) {
   return { hasFiles };
 }
 
+// `capability` is the honest, normalized functional classification per host:
+//   full-native      — the host runs a multi-specialist chain itself (native
+//                       dispatch or config-driven agents): Claude Code, OpenCode.
+//   mcp-orchestrated  — no native subagent primitive, but the host calls the
+//                       `orchestration_run` MCP tool to reach the same orchestrated
+//                       outcome via the daemon: Codex, VS Code, Cursor, Copilot.
+//   prompt-only       — neither native dispatch nor MCP; instruction files only.
+//                       No supported 2026 host is prompt-only.
+
 export function detectHostCapabilities() {
   const claudeRaw = commandVersion("claude");
   const claudeVersion = parseClaudeVersion(claudeRaw);
@@ -135,6 +144,7 @@ export function detectHostCapabilities() {
       availability: claudeRaw ? "installed" : "missing",
       version: claudeRaw,
       orchestration: claudeTeamsSupported ? "full-multi-agent" : "primary-plus-subagents",
+      capability: "full-native",
       promptableWorkers: claudeTeamsSupported,
       sharedTaskRuntime: claudeTeamsSupported,
       lifecycleHooks: ["SubagentStop", "TeammateIdle", "TaskCreated", "TaskCompleted", "Stop"],
@@ -151,6 +161,7 @@ export function detectHostCapabilities() {
       availability: opencodeRaw ? "installed" : "missing",
       version: opencodeRaw,
       orchestration: "primary-plus-subagents",
+      capability: "full-native",
       promptableWorkers: false,
       sharedTaskRuntime: "tracker-plus-plan",
       lifecycleHooks: ["session.error", "session.idle", "tool.execute.before", "tool.execute.after"],
@@ -165,12 +176,13 @@ export function detectHostCapabilities() {
       availability: codexRaw ? "installed" : "missing",
       version: codexRaw,
       orchestration: "profile-and-mcp",
+      capability: "mcp-orchestrated",
       promptableWorkers: false,
       sharedTaskRuntime: "tracker-plus-plan",
       lifecycleHooks: [],
       notes: [
-        "Use Construct profiles, MCP project/memory tools, and the active session.",
-        "Native profile switching is not automatic; continue in-session when dispatch is unavailable.",
+        "Run a full multi-specialist chain via the `orchestration_run` MCP tool (start `construct dashboard`).",
+        "Use Construct profiles, MCP project/memory tools, and the active session for single-pass work.",
       ],
     },
     {
@@ -178,12 +190,13 @@ export function detectHostCapabilities() {
       availability: vscode.version || vscode.hasSettings ? "installed" : "missing",
       version: vscode.version,
       orchestration: "copilot-mcp",
+      capability: "mcp-orchestrated",
       promptableWorkers: false,
       sharedTaskRuntime: "editor-session",
       lifecycleHooks: [],
       notes: [
-        "Construct manages GitHub Copilot MCP registrations in user settings when a VS Code settings.json already exists.",
-        "VS Code is an editor surface, not Construct's primary multi-agent runtime.",
+        "Run a full multi-specialist chain via the `orchestration_run` MCP tool in Copilot agent mode (start `construct dashboard`).",
+        "Construct's MCP servers load from `.vscode/mcp.json` (project) and the user-profile `mcp.json` (global, only when it already exists).",
       ],
     },
     {
@@ -191,12 +204,13 @@ export function detectHostCapabilities() {
       availability: cursor.version || cursor.hasConfig ? "installed" : "missing",
       version: cursor.version,
       orchestration: "mcp-only",
+      capability: "mcp-orchestrated",
       promptableWorkers: false,
       sharedTaskRuntime: "editor-session",
       lifecycleHooks: [],
       notes: [
-        "Construct manages Cursor MCP registrations in ~/.cursor/mcp.json when that file exists.",
-        "Cursor agent profiles are not generated today; use Construct through MCP-backed tools and shared project state.",
+        "Run a full multi-specialist chain via the `orchestration_run` MCP tool (start `construct dashboard`).",
+        "Construct manages Cursor MCP registrations in `.cursor/mcp.json` (project) and `~/.cursor/mcp.json` (global, when it already exists).",
       ],
     },
     {
@@ -204,12 +218,13 @@ export function detectHostCapabilities() {
       availability: copilot.hasFiles ? "installed" : "missing",
       version: null,
       orchestration: "prompt-profiles",
+      capability: "mcp-orchestrated",
       promptableWorkers: false,
       sharedTaskRuntime: "editor-session",
       lifecycleHooks: [],
       notes: [
-        "Construct writes reusable prompt profiles under ~/.github/prompts/ plus a managed block in ~/.github/copilot-instructions.md.",
-        "Copilot does not expose Construct-style subagent dispatch; use the generated profiles for focused passes.",
+        "Copilot agent mode runs Construct's MCP tools — use `orchestration_run` for a real multi-specialist chain (start `construct dashboard`).",
+        "Construct also writes reusable prompt profiles under `.github/prompts/` for single-pass role work.",
       ],
     },
   ];
@@ -224,6 +239,7 @@ export function printHostCapabilities(hosts = detectHostCapabilities()) {
   for (const host of hosts) {
     console.log("");
     console.log(`${host.host}: ${host.availability}${host.version ? ` (${host.version})` : ""}`);
+    console.log(`  capability: ${host.capability}`);
     console.log(`  orchestration: ${host.orchestration}`);
     console.log(`  promptable workers: ${host.promptableWorkers === true ? "yes" : "no"}`);
     console.log(`  shared task runtime: ${host.sharedTaskRuntime === true ? "native" : host.sharedTaskRuntime || "none"}`);

package/lib/host-disposition.mjs

@@ -0,0 +1,76 @@
+/**
+ * lib/host-disposition.mjs — single source of truth for the disposition of
+ * every artifact Construct creates in a host project (ADR-0027 §1).
+ *
+ * `IGNORED_PATTERNS` enumerates machine-specific, sync-regenerated artifacts
+ * that must never be committed; the init `.gitignore` writer and the
+ * `gitignore-coverage` reconciliation both read from here, and uninstall /
+ * adapter-prune consume `ADAPTER_DIRS`. Keep this 1:1 with the host-relevant
+ * subset of Construct's own repo .gitignore so forward-fix and backward-repair
+ * never diverge.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Adapter directories `construct sync` regenerates per host platform. Each
+// carries machine-specific absolute paths (MCP server paths, env-resolved
+// tokens) and is recreated on demand, so none is durable repo state.
+
+export const ADAPTER_DIRS = ['.claude', '.codex', '.cursor', '.vscode', '.opencode'];
+
+// Every artifact whose disposition is `ignored`. A trailing slash marks a
+// directory. `.construct/` is the per-project launcher (host scope only — the
+// Construct repo itself tracks `.construct/version`, hence the divergence from
+// the repo .gitignore for that one entry).
+
+export const IGNORED_PATTERNS = [
+  '.cx/',
+  '.claude/',
+  '.codex/',
+  '.cursor/',
+  '.vscode/',
+  '.opencode/',
+  '.construct/',
+  '.mcp.json',
+  '.github/prompts/',
+  '.github/copilot-instructions.md',
+  'config.env',
+  'embed.yaml',
+  'plan.md',
+  'inbox/',
+];
+
+// A pattern counts as already-ignored when an existing line matches it exactly,
+// matches its bare/slashed form, or is a broader `*` / `**` catch-all.
+
+export function isPatternIgnored(pattern, presentLines) {
+  const present = presentLines instanceof Set ? presentLines : new Set(presentLines);
+  if (present.has('*') || present.has('**')) return true;
+  const bare = pattern.replace(/\/$/, '');
+  return present.has(pattern) || present.has(bare) || present.has(`${bare}/`) || present.has(`${bare}/**`);
+}
+
+// Patterns from IGNORED_PATTERNS not yet covered by `content` (a .gitignore body).
+
+export function missingIgnorePatterns(content) {
+  const present = new Set((content || '').split('\n').map((l) => l.trim()));
+  return IGNORED_PATTERNS.filter((p) => !isPatternIgnored(p, present));
+}
+
+// Detection: a package.json declaring this as the `construct` package. Used
+// to prevent `construct init` and `construct sync` from misapplying host
+// project rules (like ignoring .construct/) to the Construct repository itself.
+
+export function isConstructPackageRepo(dir) {
+  try {
+    const pkgPath = path.join(dir, 'package.json');
+    if (!fs.existsSync(pkgPath)) return false;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (!pkg) return false;
+    if (pkg.name === 'construct' || pkg.name === '@geraldmaron/construct') return true;
+    return pkg.bin && (pkg.bin === 'bin/construct' || (typeof pkg.bin === 'object' && pkg.bin.construct === 'bin/construct'));
+  } catch {
+    return false;
+  }
+}

package/lib/ingest/provider-extract.mjs

@@ -114,7 +114,7 @@ async function callAnthropic({ model, apiKey, content, fetchImpl }) {
 async function callOpenRouter({ model, apiKey, content, fetchImpl }) {
   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/construct' },
+    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', 'HTTP-Referer': 'https://github.com/geraldmaron/construct' },
     body: JSON.stringify({
       model: model.replace(/^openrouter\//, ''),
       max_tokens: MAX_OUTPUT_TOKENS,

package/lib/ingest/strategy.mjs

@@ -15,12 +15,21 @@
 
 import { resolveSetting } from '../config/project-config.mjs';
 import { resolveEmbeddedModel } from '../embedded-contract/model-resolve.mjs';
+import { resolveExecution } from '../embedded-contract/execution.mjs';
 
 export const INGEST_STRATEGIES = ['adapter', 'provider'];
 export const INGEST_FALLBACKS = ['none', 'provider', 'adapter'];
 
+// Orchestration is a second, independent axis from extraction (adapter|provider):
+// `prompt-only` runs ingest as a deterministic extraction pass; `orchestrated`
+// engages the Construct specialist chain for the evidence-ingest workflow. Both
+// axes coexist — extraction is HOW bytes become text, orchestration is WHETHER
+// specialists process the result.
+export const INGEST_ORCHESTRATION_STRATEGIES = ['prompt-only', 'orchestrated'];
+
 export const DEFAULT_INGEST_STRATEGY = 'adapter';
 export const DEFAULT_INGEST_FALLBACK = 'none';
+export const DEFAULT_INGEST_ORCHESTRATION = 'prompt-only';
 
 function coerceEnum(value, allowed) {
   if (typeof value !== 'string') return null;
@@ -55,11 +64,13 @@ function resolveProviderModel({ env, registryPath }) {
  * @param {object} opts
  * @param {object} [opts.config]      loaded project config object
  * @param {Record<string,string>} [opts.env]
- * @param {string} [opts.override]    explicit strategy override (CLI flag)
+ * @param {string} [opts.override]    explicit extraction strategy override (CLI flag)
+ * @param {string} [opts.orchestrationOverride] explicit orchestration override (CLI flag)
+ * @param {string} [opts.cwd]
  * @param {string} [opts.registryPath]
- * @returns {{strategy:string, fallback:string, model:(string|null), provider:(string|null), modelResolution:(object|null)}}
+ * @returns {{strategy:string, fallback:string, orchestration:string, model:(string|null), provider:(string|null), modelResolution:(object|null), execution:object}}
  */
-export function resolveIngestStrategy({ config = null, env = process.env, override = null, registryPath = null } = {}) {
+export function resolveIngestStrategy({ config = null, env = process.env, override = null, orchestrationOverride = null, cwd = process.cwd(), registryPath = null } = {}) {
   const overrideStrategy = coerceEnum(override, INGEST_STRATEGIES);
 
   const fromSettings = resolveSetting({
@@ -82,14 +93,35 @@ export function resolveIngestStrategy({ config = null, env = process.env, overri
   });
   const fallback = coerceEnum(fallbackSetting.value, INGEST_FALLBACKS) || DEFAULT_INGEST_FALLBACK;
 
+  const orchestrationSetting = resolveSetting({
+    config,
+    jsonPath: 'ingest.orchestration',
+    env,
+    envKey: 'CONSTRUCT_INGEST_ORCHESTRATION',
+    defaultValue: DEFAULT_INGEST_ORCHESTRATION,
+  });
+  const orchestration = coerceEnum(orchestrationOverride, INGEST_ORCHESTRATION_STRATEGIES)
+    || coerceEnum(orchestrationSetting.value, INGEST_ORCHESTRATION_STRATEGIES)
+    || DEFAULT_INGEST_ORCHESTRATION;
+
   const needsProviderModel = strategy === 'provider' || fallback === 'provider';
   const modelResolution = needsProviderModel ? resolveProviderModel({ env, registryPath }) : null;
 
+  // The execution-capability contract is the single source of truth for whether
+  // the ingest workflow will actually orchestrate; reuse it rather than deriving
+  // a second answer here.
+  const { warnings, modelResolution: _drop, ...execution } = resolveExecution(
+    { workflowType: INGEST_WORKFLOW_TYPE, requestedStrategy: orchestration },
+    { env, cwd, registryPath },
+  );
+
   return {
     strategy,
     fallback,
+    orchestration,
     model: modelResolution?.model || null,
     provider: modelResolution?.provider || null,
     modelResolution,
+    execution,
   };
 }

package/lib/init-docs.mjs

@@ -785,7 +785,7 @@ async function main() {
       process.stdout.write(`[init:docs] skipping .cx/inbox/ — ${inboxDecision.reason}. Run with --force to scaffold anyway.\n`);
       skipped.push('.cx/inbox/ (deferred to existing intake)');
     } else {
-      writeIfMissing(path.join(target, '.cx', 'inbox', '.gitkeep'), '');
+      fs.mkdirSync(path.join(target, '.cx', 'inbox'), { recursive: true });
     }
   }