@geraldmaron/construct 1.5.0 → 1.5.2

package/lib/knowledge/search.mjs

@@ -28,6 +28,10 @@ import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
 import { homedir } from 'node:os';
 
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { resolveEffectiveSourceTargetsFromConfig } from '../config/source-targets.mjs';
+import { resolveContentRoots, expandProjectsFilter, SELF_PROJECT_KEY } from '../sources/content-roots.mjs';
+
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = join(MODULE_DIR, '..', '..');
 
@@ -43,7 +47,7 @@ const REPO_ROOT = join(MODULE_DIR, '..', '..');
  * surfaces alongside (and ahead of) the bundled Construct docs. When
  * projectRoot equals repoRoot or is absent, only the bundled set is searched.
  */
-function buildSourceList(repoRoot = REPO_ROOT, projectRoot = null) {
+function buildSourceList(repoRoot = REPO_ROOT, projectRoot = null, { targetRoots = [] } = {}) {
   const sources = [];
 
   const priority = [
@@ -125,6 +129,24 @@ function buildSourceList(repoRoot = REPO_ROOT, projectRoot = null) {
     }
   }
 
+  // Registered content targets (B1): directory targets and synced corpus caches.
+  // Each markdown file joins the corpus tagged with its target's structured
+  // origin, so retrieval can attribute and filter hits by source project. Priority
+  // 1 puts registered project docs on the same tier as the host project's own.
+
+  for (const root of targetRoots) {
+    if (!existsSync(root.dir)) continue;
+    for (const file of walkMarkdown(root.dir)) {
+      sources.push({
+        path: file,
+        rel: relative(root.dir, file),
+        priority: 1,
+        source: 'target',
+        origin: { ...root.origin, relPath: relative(root.dir, file), kind: 'target' },
+      });
+    }
+  }
+
   return sources;
 }
 
@@ -313,14 +335,37 @@ function buildObservationChunks(rootDir) {
  * @param {string} [opts.rootDir]      — data dir where .cx/observations/ lives (default: homedir())
  * @returns {KnowledgeSearchResult}
  */
-export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, rootDir, tags, tagMatch = 'any' } = {}) {
+export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, rootDir, tags, tagMatch = 'any', projects, env = process.env } = {}) {
   if (!query || typeof query !== 'string') {
     return { ok: false, query: query ?? '', totalChunks: 0, hits: [], sources: [], message: 'query is required' };
   }
 
   const root = repoRoot ?? REPO_ROOT;
   const dataDir = rootDir ?? (process.env.CX_DATA_DIR?.trim() || homedir());
-  const sources = buildSourceList(root, rootDir);
+
+  // Registered content targets contribute to the corpus whenever the project has
+  // any (resolved from its config). A `projects` filter narrows retrieval to the
+  // named source projects; `self` is the reserved host-project key, `all` every
+  // content target. An unknown project id is a hard error (R3), never a silent
+  // empty result.
+  let targetRoots = [];
+  let projectFilter = null;
+  if (rootDir) {
+    const { config } = loadProjectConfig(rootDir, env);
+    const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+    targetRoots = resolveContentRoots(targets, { projectRoot: rootDir });
+    if (projects !== undefined && projects !== null && String(projects).trim() !== '') {
+      try {
+        projectFilter = expandProjectsFilter(projects, targets);
+      } catch (err) {
+        return { ok: false, query, totalChunks: 0, hits: [], sources: [], message: err.message };
+      }
+    }
+  } else if (projects !== undefined && projects !== null && String(projects).trim() !== '') {
+    return { ok: false, query, totalChunks: 0, hits: [], sources: [], message: 'projects filter requires a project root (rootDir)' };
+  }
+
+  const sources = buildSourceList(root, rootDir, { targetRoots });
 
   // Build corpus from docs + operator knowledge
   const allChunks = [];
@@ -356,17 +401,35 @@ export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, roo
 
   const idf = buildIdf(queryTokens, filteredChunks);
 
+  // A chunk's structured origin: registered targets carry it directly from
+  // buildSourceList; host/bundled chunks resolve to the reserved self project.
+  const originFor = (chunk) => chunk.source.origin ?? {
+    targetId: null,
+    provider: 'self',
+    projectKey: SELF_PROJECT_KEY,
+    relPath: chunk.source.rel,
+    ref: null,
+    kind: chunk.source.source || 'bundled',
+  };
+
+  const inFilter = (origin) => {
+    if (!projectFilter) return true;
+    if (origin.targetId == null) return projectFilter.includeSelf;
+    return projectFilter.ids.has(origin.targetId);
+  };
+
   const scored = filteredChunks
-    .map(chunk => ({ chunk, score: scoreChunk(chunk, queryTokens, idf) }))
+    .map(chunk => ({ chunk, origin: originFor(chunk), score: scoreChunk(chunk, queryTokens, idf) }))
     .filter(({ score }) => score >= minScore)
+    .filter(({ origin }) => inFilter(origin))
     .sort((a, b) => b.score - a.score)
     .slice(0, topK);
 
-  const hits = scored.map(({ chunk, score }) => ({
+  const hits = scored.map(({ chunk, origin, score }) => ({
     text: chunk.text,
     heading: chunk.heading,
     file: chunk.source.rel,
-    origin: chunk.source.source || 'bundled',
+    origin,
     score: Math.round(score * 100) / 100,
     lineStart: chunk.lineStart,
   }));

package/lib/knowledge/synthesis.mjs

@@ -0,0 +1,157 @@
+/**
+ * lib/knowledge/synthesis.mjs — cross-project synthesis (bead construct-760c.4→.3).
+ *
+ * Map-reduce over the B2 multi-root corpus so a user can ask one question across
+ * several registered projects — "summarize each project's docs", "how do these
+ * strategies converge" — and get an answer that names its sources (no
+ * fabrication: every cross-project claim traces to an origin the reader can
+ * re-verify).
+ *
+ *   MAP    — per project, retrieve the chunks most relevant to the ask from that
+ *            project's content root only, and extract them as an attributed
+ *            section. This pass is retrieval-only (no model call), so it is
+ *            deterministic and free — the cheap-tier goal taken to its limit.
+ *   REDUCE — one synthesis pass over the per-project sections that draws the
+ *            convergence/divergence across projects, each claim carrying an
+ *            origin citation. This is the single model call.
+ *
+ * `dryRun` stops after MAP and returns the fully assembled context (per-project
+ * sections + a citation table + the reduce prompt) with zero model output — the
+ * deterministic, CI-testable preview surface. An unknown project id is a hard
+ * error before any model call (R3).
+ */
+
+import { spawnSync } from 'node:child_process';
+
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { resolveEffectiveSourceTargetsFromConfig } from '../config/source-targets.mjs';
+import { resolveContentRoots, expandProjectsFilter } from '../sources/content-roots.mjs';
+import { getTemplate } from '../mcp/tools/skills.mjs';
+import { buildCorpus, retrieve } from './rag.mjs';
+
+const PER_PROJECT_TOPK = 6;
+const SECTION_PREVIEW = 500;
+
+function citationLabel(origin) {
+  const rel = origin?.relPath || '(unknown)';
+  return `${origin?.projectKey || origin?.targetId || 'project'}:${rel}`;
+}
+
+// Retrieval-only map: a single-root corpus filtered to this project's own
+// chunks, then top-K for the ask. Sorting the roots and keying each corpus to a
+// single origin keeps the assembly deterministic across runs (AC3).
+async function mapProject(root, ask, { cwd, topK }) {
+  const corpus = buildCorpus(cwd, { roots: [root] })
+    .filter((c) => c.origin?.targetId === root.origin.targetId);
+  const hits = await retrieve(ask, corpus, { topK });
+  return { root, hits };
+}
+
+function renderProjectSection({ root, hits }) {
+  const id = root.origin.targetId;
+  if (!hits.length) {
+    return `## Project: ${id}\n\n_No content matched the query in this project._`;
+  }
+  const blocks = hits.map((h) => {
+    const preview = (h.body || '').slice(0, SECTION_PREVIEW).trim();
+    return `- **${h.title}** — \`${citationLabel(h.origin)}\`\n\n  ${preview.replace(/\n+/g, ' ')}`;
+  });
+  return `## Project: ${id}\n\n${blocks.join('\n\n')}`;
+}
+
+function renderCitationTable(mapped) {
+  const rows = [];
+  for (const { root, hits } of mapped) {
+    for (const h of hits) {
+      rows.push(`| ${root.origin.targetId} | ${h.origin?.relPath || '(unknown)'} | ${h.title} |`);
+    }
+  }
+  if (!rows.length) return '## Citations\n\n_No sources matched._';
+  return `## Citations\n\n| Project | Path | Title |\n|---|---|---|\n${rows.join('\n')}`;
+}
+
+// Template shapes the convergence section only (AC2): when one resolves, its
+// section headings scaffold the reduce; otherwise a default convergence shape.
+function convergenceHeadings(template, rootDir) {
+  if (!template) return ['Convergence', 'Divergence', 'Recommendation'];
+  const resolved = getTemplate({ name: template }, { ROOT_DIR: rootDir });
+  if (resolved?.error || !resolved?.content) return ['Convergence', 'Divergence', 'Recommendation'];
+  const headings = [...resolved.content.matchAll(/^##\s+(.+)$/gm)].map((m) => m[1].trim());
+  return headings.length ? headings : ['Convergence', 'Divergence', 'Recommendation'];
+}
+
+function buildReducePrompt({ ask, sections, headings }) {
+  const headingBlock = headings.map((h) => `## ${h}`).join('\n');
+  return `You are synthesizing across multiple projects. Answer the question using ONLY the per-project context below. Every cross-project claim MUST cite its source as \`project:path\` (the labels shown). If a project lacks relevant content, say so — do not invent.
+
+Question: ${ask}
+
+${sections}
+
+Produce a synthesis with these sections (keep the per-project attribution above intact):
+${headingBlock}`;
+}
+
+/**
+ * Assemble the multi-project context and, unless dryRun, synthesize an answer.
+ *
+ * @param {object} opts
+ * @param {string} opts.projects   CSV / array project filter (all | self | ids)
+ * @param {string} opts.ask        the synthesis question
+ * @param {string} [opts.cwd]
+ * @param {object} [opts.env]
+ * @param {string} [opts.template] optional template name shaping the reduce
+ * @param {boolean} [opts.dryRun]  stop after MAP, return assembled context only
+ * @param {number} [opts.topK]     per-project retrieval depth
+ * @param {string} [opts.rootDir]  construct repo root (for template resolution)
+ * @returns {Promise<{ok, ask, projects, context, citations, prompt, answer, sources}>}
+ */
+export async function synthesize({ projects, ask, cwd = process.cwd(), env = process.env, template = null, dryRun = false, topK = PER_PROJECT_TOPK, rootDir } = {}) {
+  if (!ask || typeof ask !== 'string' || !ask.trim()) {
+    return { ok: false, message: 'a synthesis question (--ask) is required' };
+  }
+
+  const { config } = loadProjectConfig(cwd, env);
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+  const allRoots = resolveContentRoots(targets, { projectRoot: cwd });
+
+  let selectedIds;
+  try {
+    const filter = expandProjectsFilter(projects ?? 'all', targets);
+    selectedIds = filter.ids;
+  } catch (err) {
+    return { ok: false, message: err.message };
+  }
+
+  const roots = allRoots
+    .filter((r) => selectedIds.has(r.origin.targetId))
+    .sort((a, b) => a.origin.targetId.localeCompare(b.origin.targetId));
+
+  if (!roots.length) {
+    return { ok: false, message: `no content-capable projects resolved for "${projects ?? 'all'}" — register a directory or synced corpus target first` };
+  }
+
+  const mapped = [];
+  for (const root of roots) {
+    mapped.push(await mapProject(root, ask, { cwd, topK }));
+  }
+
+  const sections = mapped.map(renderProjectSection).join('\n\n');
+  const citations = renderCitationTable(mapped);
+  const headings = convergenceHeadings(template, rootDir || cwd);
+  const prompt = buildReducePrompt({ ask, sections: `${sections}\n\n${citations}`, headings });
+
+  const context = `# Cross-project synthesis: ${ask}\n\n${sections}\n\n${citations}`;
+  const sourceList = mapped.flatMap(({ root, hits }) =>
+    hits.map((h) => ({ project: root.origin.targetId, path: h.origin?.relPath || null, title: h.title })));
+
+  if (dryRun) {
+    return { ok: true, ask, projects: roots.map((r) => r.origin.targetId), context, citations, prompt, answer: null, sources: sourceList };
+  }
+
+  const result = spawnSync('claude', ['--print', prompt], { encoding: 'utf8', timeout: 120_000, env: { ...env } });
+  if (result.error || result.status !== 0) {
+    return { ok: true, ask, projects: roots.map((r) => r.origin.targetId), context, citations, prompt, answer: `[claude CLI unavailable — showing assembled context]\n\n${context}`, sources: sourceList, cliMissing: true };
+  }
+  return { ok: true, ask, projects: roots.map((r) => r.origin.targetId), context, citations, prompt, answer: (result.stdout || '').trim(), sources: sourceList };
+}

package/lib/mcp/server.mjs

@@ -215,7 +215,7 @@ const CORE_TOOL_NAMES = new Set([
   'orchestration_policy', 'orchestration_run', 'get_skill', 'get_template', 'search_skills', 'knowledge_search',
   'memory_search', 'project_context', 'summarize_diff', 'find_tool',
   'author_artifact', 'document_export', 'publish_run', 'artifact_workflow',
-  'workflow_invoke', 'triage_recommend', 'orchestration_readiness',
+  'triage_recommend', 'orchestration_readiness',
 ]);
 
 const KNOWN_TOOL_NAMES = new Set(ALL_TOOL_DEFS.map((t) => t.name));
@@ -325,7 +325,7 @@ export async function dispatchToolByName(name, args = {}) {
     else if (name === 'provider_write') result = await providerWrite(args, { rootDir: opts.ROOT_DIR });
     else if (name === 'knowledge_search') {
       const { knowledgeSearch } = await import('../knowledge/search.mjs');
-      result = knowledgeSearch({ query: args.query, topK: args.top_k, repoRoot: args.repo_root, rootDir: args.root_dir });
+      result = knowledgeSearch({ query: args.query, topK: args.top_k, repoRoot: args.repo_root, rootDir: args.root_dir, projects: args.projects });
     }
     else if (name === 'document_export') {
       const { detect, exportMarkdown } = await import('../document-export.mjs');

package/lib/mcp/tool-definitions-workflow.mjs

@@ -9,6 +9,8 @@
  * lib/mcp/server.mjs concatenates every slice and applies
  * withSafetyEnvelope (lib/mcp/tool-safety.mjs) at load time.
  */
+import { MODEL_TIERS } from '../model-tiers.mjs';
+
 export const TOOL_DEFS_WORKFLOW = [
     {
       name: 'publish_detect',
@@ -56,7 +58,8 @@ export const TOOL_DEFS_WORKFLOW = [
           query: { type: 'string', description: 'Natural-language question or keyword (e.g. "what is construct", "how does embed mode work", "provider authority guard", "slack configuration", "open Jira issues").' },
           top_k: { type: 'number', description: 'Max excerpts to return (default: 5).' },
           repo_root: { type: 'string', description: 'Repo root override (default: auto-detected from server location).' },
-          root_dir: { type: 'string', description: 'Data directory where .cx/observations/ lives (default: home directory). Pass this to search embed observations from a custom data dir.' },
+          root_dir: { type: 'string', description: 'Data directory where .cx/observations/ lives (default: home directory). Pass this to search embed observations from a custom data dir, and to resolve registered content targets for cross-project search.' },
+          projects: { type: 'string', description: 'Restrict retrieval to specific registered source projects: a comma-separated list of target ids, "all" for every content target, or "self" for the host project. Requires root_dir. An unknown id is a hard error, not an empty result. Each hit carries a structured origin {targetId, provider, projectKey, relPath, ref, kind} for attribution.' },
         },
       },
     },
@@ -231,15 +234,28 @@ export const TOOL_DEFS_WORKFLOW = [
     {
       name: 'author_artifact',
       outputSchema: { type: 'object' },
-      description: 'Materialize a typed Construct artifact you have drafted (prd, prd-platform, prd-business, meta-prd, adr, rfc, research-brief, evidence-brief, runbook) to disk and run the release gate. YOU draft the full markdown — start with a single # title and include the type\'s required ## sections (call get_template first for the shape) — and pass it as draft_markdown; the canonical file is written and the gate verdict + errors are returned so you can fix and re-call. This is the Construct author→materialize→validate pass for supported hosts.',
+      description: 'Materialize a typed Construct artifact you have drafted (prd, prd-platform, prd-business, meta-prd, adr, rfc, research-brief, evidence-brief, runbook, a project-registered custom class, or adhoc) to disk and run the release gate. YOU draft the full markdown — start with a single # title and include the type\'s required ## sections (call get_template first for the shape) — and pass it as draft_markdown; the canonical file is written and the gate verdict + errors are returned so you can fix and re-call. For a one-off with no fixed shape, pass artifact_type "adhoc" with title + instructions (no draft_markdown needed). An unknown, unregistered non-adhoc class returns a classification/registration prompt instead of a draft. This is the Construct author→materialize→validate pass for supported hosts.',
       inputSchema: {
         type: 'object',
         properties: {
-          draft_markdown: { type: 'string', description: 'The complete artifact markdown you authored. Must start with one # title line and contain the required ## sections for the type.' },
-          artifact_type: { type: 'string', description: 'Artifact type (prd, meta-prd, adr, rfc, research-brief, evidence-brief, runbook, …). Defaults to prd; inferred from subject when omitted.' },
+          draft_markdown: { type: 'string', description: 'The complete artifact markdown you authored. Must start with one # title line and contain the required ## sections for the type. Required for a normal author pass; omit for adhoc or dry_run.' },
+          artifact_type: { type: 'string', description: 'Artifact type (prd, meta-prd, adr, rfc, research-brief, evidence-brief, runbook, a registered custom class, or adhoc). Defaults to prd; inferred from subject when omitted.' },
           subject: { type: 'string', description: 'Short subject/title hint (e.g. "OIDC integration") used for the filename and type inference.' },
+          title: { type: 'string', description: 'Required for adhoc: the artifact title.' },
+          instructions: { type: 'string', description: 'Required for adhoc: what the one-off document should cover. Its structure follows these instructions; the release gate still applies.' },
+          for_type: { type: 'string', description: 'Optional adhoc hint: if this names a registered class, the call is redirected to that class instead of authoring adhoc.' },
+          dry_run: { type: 'boolean', description: 'Preview mode: draft from the resolved template (or the adhoc scaffold) without a supplied draft, then run the gate. Default false.' },
+          context_targets: {
+            type: 'array',
+            description: 'Optional registered source-target ids (or {id, role}) to bind this author pass to for cross-project context (B3). Each id must exist in sources.targets[] — an unknown id is a hard error before authoring. The multi-project synthesis context is assembled deterministically and woven into the authoring input so the artifact can draw on and cite each project (project:path).',
+            items: {
+              oneOf: [
+                { type: 'string' },
+                { type: 'object', required: ['id'], properties: { id: { type: 'string' }, role: { type: 'string' } } },
+              ],
+            },
+          },
         },
-        required: ['draft_markdown'],
       },
     },
     {
@@ -250,7 +266,7 @@ export const TOOL_DEFS_WORKFLOW = [
         type: 'object',
         properties: {
           workflow_type: { type: 'string', description: 'Workflow type hint (e.g. evidence-ingest, prd-draft, architecture-review). Selects a tier when requested_tier is absent.' },
-          requested_tier: { type: 'string', enum: ['reasoning', 'standard', 'fast'], description: 'Desired tier; overrides the workflow-type hint.' },
+          requested_tier: { type: 'string', enum: [...MODEL_TIERS], description: 'Desired tier; overrides the workflow-type hint.' },
           host: { type: 'string', description: 'Host/IDE identifier (advisory).' },
           host_model: { type: 'string', description: 'Model the host is currently using (e.g. anthropic/claude-sonnet-4-6).' },
           host_provider: { type: 'string', description: 'Provider family the host uses, when no host_model is given.' },
@@ -323,7 +339,7 @@ export const TOOL_DEFS_WORKFLOW = [
           host: { type: 'string', description: 'Host/IDE identifier (advisory).' },
           host_model: { type: 'string', description: 'Model the host is currently using, for model resolution.' },
           host_provider: { type: 'string', description: 'Provider family the host uses, when no host_model is given.' },
-          requested_tier: { type: 'string', enum: ['reasoning', 'standard', 'fast'], description: 'Desired model tier; overrides the workflow-type hint.' },
+          requested_tier: { type: 'string', enum: [...MODEL_TIERS], description: 'Desired model tier; overrides the workflow-type hint.' },
           capabilities: { type: 'array', items: { type: 'string' }, description: 'Optional required capabilities; unverifiable ones are returned as warnings.' },
           allow_cross_provider_fallback: { type: 'boolean', description: 'Permit model fallback outside the host provider family (default false).' },
         },
@@ -346,6 +362,18 @@ export const TOOL_DEFS_WORKFLOW = [
           host_provider: { type: 'string', description: 'Provider family the host uses, for model resolution.' },
           file_count: { type: 'number', description: 'Optional planning hint: number of files in scope.' },
           module_count: { type: 'number', description: 'Optional planning hint: number of modules in scope.' },
+          context_targets: {
+            type: 'array',
+            description: 'Optional registered source targets to bind this run to for context (e.g. [{"id":"proj-app"},{"id":"jira-core","role":"tracker"}]). Each id must exist in sources.targets[] — an unknown id is rejected at plan time before any task is built, never a silent skip. `role` is an optional free-form hint. Resolved bindings are persisted on the run record and returned as contextBindings. Omit for today\'s implicit source resolution.',
+            items: {
+              type: 'object',
+              required: ['id'],
+              properties: {
+                id: { type: 'string', description: 'A registered source-target id.' },
+                role: { type: 'string', description: 'Optional free-form role hint (e.g. "tracker", "reference").' },
+              },
+            },
+          },
           wait: { type: 'boolean', description: 'Wait for the run to reach a terminal state and return task output (default true). false returns the runId immediately to poll with orchestration_status.' },
           timeout_ms: { type: 'number', description: 'Max time to wait when wait=true (default 120000). On timeout the runId is returned to poll.' },
         },

package/lib/mcp/tools/artifact-author.mjs

@@ -5,23 +5,48 @@
  * the drafted typed-artifact markdown,
  * which gets materialized to its canonical path and run through the release gate.
  * Returns the path and a structured verdict so the agent can fix and re-call.
- * allowScaffold stays off — a real draft is required, never an empty scaffold.
+ *
+ * Type resolution respects the manifest gate. A registered class (builtin,
+ * user/project overlay, or the sanctioned `adhoc`) proceeds; an unknown
+ * non-adhoc class returns a classification/registration result instead of
+ * silently becoming a PRD. `adhoc` needs an explicit title + instructions and
+ * is not a bypass for a known class — naming a registered type through adhoc
+ * is redirected. allowScaffold stays off for a real author pass (a real draft
+ * is required); `dry_run` flips it on to preview the resolved template or the
+ * adhoc scaffold through the same gate without a live model.
  */
 import { runConstructArtifactLoop } from '../../artifact-loop-core.mjs';
+import { resolveArtifactType } from '../../artifact-manifest.mjs';
+import { ADHOC_TYPE } from '../../artifact-manifest-overlay.mjs';
+import { loadProjectConfig } from '../../config/project-config.mjs';
+import { resolveContextBindings } from '../../orchestration/context-bindings.mjs';
+import { synthesize } from '../../knowledge/synthesis.mjs';
 
-export async function authorArtifact(args = {}, { ROOT_DIR } = {}) {
-  const draftMarkdown = args.draft_markdown || args.draft || '';
-  const cwd = args.cwd || process.cwd();
-  const result = await runConstructArtifactLoop({
-    draftMarkdown,
-    artifactType: args.artifact_type,
-    text: args.subject || args.text || '',
-    cwd,
-    rootDir: ROOT_DIR,
-    explicit: true,
-    allowScaffold: false,
-  });
+// context_targets binds an author pass to registered source projects (B3): the
+// ids are validated the same way orchestration runs validate theirs (unknown id
+// → hard error before any authoring), and the multi-project synthesis context is
+// assembled deterministically (dry-run map) and woven into the authoring input so
+// the artifact draws on — and cites — every named project.
+async function resolveContextBlock(args, cwd) {
+  const contextTargets = args.context_targets;
+  if (contextTargets == null || (Array.isArray(contextTargets) && contextTargets.length === 0)) {
+    return { ok: true, block: '', bindings: [] };
+  }
+  const { config } = loadProjectConfig(cwd);
+  let bindings;
+  try {
+    bindings = resolveContextBindings(contextTargets, { config, cwd });
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  const ask = String(args.subject || args.text || args.instructions || args.title || 'synthesize across the bound projects').trim();
+  const projects = bindings.map((b) => b.id).join(',');
+  const synth = await synthesize({ projects, ask, cwd, dryRun: true });
+  const block = synth.ok ? `\n\n## Cross-project context (cite as project:path)\n\n${synth.context}` : '';
+  return { ok: true, block, bindings };
+}
 
+function toResult(result) {
   return {
     ok: Boolean(result.ok),
     artifact_type: result.artifactType,
@@ -34,3 +59,91 @@ export async function authorArtifact(args = {}, { ROOT_DIR } = {}) {
     summary: result.summary,
   };
 }
+
+async function authorAdhoc(args, { ROOT_DIR, cwd, dryRun, contextBlock = '' }) {
+  const title = String(args.title || '').trim();
+  const instructions = String(args.instructions || '').trim();
+  if (!title || !instructions) {
+    return {
+      ok: false,
+      artifact_type: ADHOC_TYPE,
+      status: 'invalid-request',
+      errors: ['adhoc requires an explicit title and instructions'],
+      guidance: 'Call author_artifact with {type:"adhoc", title, instructions}. For a registered class, pass its type instead.',
+    };
+  }
+
+  // Guard R3: adhoc is for genuinely unstructured one-offs. When the caller
+  // names a registered class (via `for_type` or an exact-match title), redirect
+  // to that class so adhoc never becomes a bypass for a gated type.
+  const namedType = String(args.for_type || '').trim().toLowerCase() || title.toLowerCase();
+  const named = resolveArtifactType(namedType, { rootDir: ROOT_DIR, cwd });
+  if (named.status === 'registered' && named.type !== ADHOC_TYPE) {
+    return {
+      ok: false,
+      artifact_type: ADHOC_TYPE,
+      status: 'redirect',
+      redirect_to: named.type,
+      warnings: [`'${named.type}' is a registered class; author it directly instead of via adhoc.`],
+      guidance: `Call author_artifact with {type:"${named.type}", ...} to use its template and release gate.`,
+    };
+  }
+
+  const draftMarkdown = args.draft_markdown || args.draft || '';
+  const result = await runConstructArtifactLoop({
+    draftMarkdown,
+    artifactType: ADHOC_TYPE,
+    titleOverride: title,
+    instructions,
+    text: `${args.subject || args.text || instructions}${contextBlock}`,
+    cwd,
+    rootDir: ROOT_DIR,
+    explicit: true,
+    allowScaffold: dryRun || !draftMarkdown,
+  });
+  return toResult(result);
+}
+
+export async function authorArtifact(args = {}, { ROOT_DIR } = {}) {
+  const cwd = args.cwd || process.cwd();
+  const dryRun = args.dry_run === true || args.scaffold === true;
+  const requestedType = String(args.artifact_type || '').trim().toLowerCase();
+
+  const ctx = await resolveContextBlock(args, cwd);
+  if (!ctx.ok) {
+    return { ok: false, artifact_type: requestedType || null, status: 'invalid-context-target', errors: [ctx.error] };
+  }
+
+  if (requestedType === ADHOC_TYPE || requestedType === 'ad-hoc' || requestedType === 'free-form' || requestedType === 'freeform') {
+    return authorAdhoc(args, { ROOT_DIR, cwd, dryRun, contextBlock: ctx.block });
+  }
+
+  // Gate intact (R4): an explicitly requested class that resolves to nothing
+  // registered gets the classification/registration answer, not a PRD.
+  if (requestedType) {
+    const resolved = resolveArtifactType(requestedType, { rootDir: ROOT_DIR, cwd });
+    if (resolved.status !== 'registered') {
+      return {
+        ok: false,
+        artifact_type: requestedType,
+        status: 'unrecognized',
+        classification_required: true,
+        errors: [`Document class '${requestedType}' is not registered.`],
+        guidance: `${resolved.guidance} Register it with \`construct templates register ${requestedType}\`, or author a one-off with {type:"adhoc", title, instructions}.`,
+      };
+    }
+  }
+
+  const draftMarkdown = args.draft_markdown || args.draft || '';
+  const result = await runConstructArtifactLoop({
+    draftMarkdown,
+    artifactType: args.artifact_type,
+    text: `${args.subject || args.text || ''}${ctx.block}`,
+    cwd,
+    rootDir: ROOT_DIR,
+    explicit: true,
+    allowScaffold: dryRun,
+  });
+
+  return toResult(result);
+}

package/lib/mcp/tools/orchestration-run.mjs

@@ -73,6 +73,7 @@ export function shapeRun(run) {
     suggestedWorkflowType: run.plan?.suggestedWorkflowType ?? null,
     researchExecutionPolicy: run.plan?.researchExecutionPolicy ?? null,
     specialists: run.plan?.specialists ?? [],
+    contextBindings: run.contextBindings ?? [],
     tasks: (run.tasks || []).map((t) => ({
       id: t.id, role: t.role, status: t.status, executor: t.executor,
       output: t.output ?? null, reasoning: t.reasoning ?? null, error: t.error ?? null,
@@ -85,6 +86,7 @@ export function shapeRun(run) {
       // never be confused with a construct-verified provider execution.
       ...(t.hostPrompt ? { system: t.hostPrompt.system, user: t.hostPrompt.user } : {}),
       ...(t.provenanceSource ? { provenanceSource: t.provenanceSource } : {}),
+      ...(t.evidenceGate ? { evidenceGate: t.evidenceGate } : {}),
     })),
   };
 }
@@ -118,6 +120,7 @@ function toRequest(args) {
     hostProvider: args.host_provider,
     fileCount: args.file_count,
     moduleCount: args.module_count,
+    contextTargets: args.context_targets,
   };
 }
 

package/lib/mcp/tools/skills.mjs

@@ -290,11 +290,28 @@ export async function orchestrationPolicy(args) {
     }
   }
 
+  // A plan is not a tool. Weak models otherwise infer a tool name from
+  // suggestedWorkflowType (e.g. research-synthesis → an invented
+  // `research_synthesis` tool) or freelance raw host tools, bypassing the
+  // governed specialist chain and its anti-fabrication persona. Hand back an
+  // explicit, machine-actionable next step so the caller executes the plan
+  // through orchestration_run instead of guessing. Omitted for the immediate
+  // track, which needs no orchestration. worker_backend is left unset so the
+  // project's configured backend (free/host/inline) is honored — never forced.
+  const nextAction = route.track !== 'immediate'
+    ? {
+      tool: 'orchestration_run',
+      arguments: { request: args?.request || '' },
+      instruction: 'Execute this plan by calling the orchestration_run tool with the request above. suggestedWorkflowType is a plan label, not a tool — do not call it, and do not freelance raw web/file tools in its place.',
+    }
+    : null;
+
   return {
     ...route,
     specialistCatalog: buildSpecialistCatalog(),
     approvalRequired,
     terminalStates: TERMINAL_STATES,
+    nextAction,
     draftTask,
     handoffPacket,
     ...(contextPackets ? { contextPackets } : {}),

package/lib/model-cheapest-provider.mjs

@@ -22,6 +22,7 @@ import path from 'node:path';
 import { getProviderModelCatalog, PROVIDER_FAMILY_TIERS } from './model-router.mjs';
 import { getPricingForModels, formatPricingLabel } from './model-pricing.mjs';
 import { configDir } from './config/xdg.mjs';
+import { isModelTier } from './model-tiers.mjs';
 
 const CHEAPEST_PREF_KEY = 'CHEAPEST_PROVIDER_ENABLED';
 const CHEAPEST_CHECKED_KEY = 'CHEAPEST_PROVIDER_CHECKED';
@@ -47,7 +48,7 @@ const ENV_PATH = path.join(configDir(), 'config.env');
  * }>}
  */
 export async function selectCheapestProvider(tier, opts = {}) {
-  if (!['reasoning', 'standard', 'fast'].includes(tier)) {
+  if (!isModelTier(tier)) {
     return { providerId: null, providerLabel: null, modelId: null, configuredProviders: [], rankedList: [] };
   }