@geraldmaron/construct 1.5.1 → 1.5.3

package/lib/knowledge/rag.mjs

@@ -68,27 +68,47 @@ function loadObservationChunks(rootDir) {
   }
 }
 
+// The host project is the reserved origin: no target id, a `self` project key.
+// Registered content targets carry their own origin (targetId, provider,
+// projectKey, ref); the corpus builder stamps per-file `relPath` onto both.
+
+const SELF_ORIGIN = Object.freeze({ targetId: null, provider: 'self', projectKey: 'self', ref: null });
+
+function withOrigin(chunk, origin, relPath) {
+  return { ...chunk, origin: { ...origin, relPath: relPath ?? chunk.origin?.relPath ?? null } };
+}
+
 /**
- * Load markdown files from a directory tree as indexable chunks.
+ * Load markdown files from a directory tree as indexable chunks. `origin`, when
+ * given, tags every chunk with its source project and per-file relative path so
+ * cross-project retrieval can attribute and filter the result; `baseDir`
+ * anchors the relative path (defaults to `dir`).
  */
-function loadMarkdownChunks(dir, source) {
+function loadMarkdownChunks(dir, source, { origin = null, baseDir = dir } = {}) {
   if (!fs.existsSync(dir)) return [];
   const chunks = [];
   const walk = (d) => {
     for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
       const full = path.join(d, entry.name);
-      if (entry.isDirectory()) { walk(full); continue; }
+      if (entry.isDirectory()) {
+        if (entry.name === '.git' || entry.name === 'node_modules') continue;
+        walk(full);
+        continue;
+      }
       if (!entry.name.endsWith('.md')) continue;
       try {
         const content = fs.readFileSync(full, 'utf8');
         const titleMatch = content.match(/^#\s+(.+)/m);
+        const relPath = path.relative(baseDir, full);
+        const idScope = origin?.targetId ? `${origin.targetId}:` : '';
         chunks.push({
-          id: `${source}:${path.relative(process.cwd(), full)}`,
+          id: `${source}:${idScope}${path.relative(process.cwd(), full)}`,
           source,
           title: titleMatch ? titleMatch[1].trim() : entry.name,
           body: content,
           filePath: full,
           createdAt: fs.statSync(full).mtime.toISOString(),
+          ...(origin ? { origin: { ...origin, relPath } } : {}),
         });
       } catch { /* skip unreadable */ }
     }
@@ -174,15 +194,33 @@ function loadKnowledgeChunks(rootDir) {
 
 /**
  * Build a full in-memory corpus from all sources.
- * Each chunk gets an embedding vector for cosine scoring.
+ * Each chunk gets an embedding vector for cosine scoring and an `origin` tag.
+ *
+ * The single-`rootDir` signature is preserved for existing callers: passing a
+ * string (or nothing) indexes only the host project, whose chunks carry the
+ * reserved self origin. Passing `roots` — content-capable target roots resolved
+ * via lib/sources/content-roots.mjs — folds each registered project's markdown
+ * into the same corpus, every chunk attributed to its source project so
+ * retrieval can cite and filter across projects (bead construct-760c.2).
+ *
+ * @param {string} [rootDir]
+ * @param {object} [opts]
+ * @param {{dir: string, origin: object}[]} [opts.roots] — extra content roots
  */
-export function buildCorpus(rootDir = process.cwd()) {
-  const chunks = [
+export function buildCorpus(rootDir = process.cwd(), { roots = [] } = {}) {
+  const hostChunks = [
     ...loadObservationChunks(rootDir),
     ...loadArtifactChunks(rootDir),
     ...loadSnapshotChunks(rootDir),
     ...loadKnowledgeChunks(rootDir),
-  ];
+  ].map((chunk) => withOrigin(chunk, SELF_ORIGIN, chunk.filePath ? path.relative(rootDir, chunk.filePath) : null));
+
+  const rootChunks = [];
+  for (const { dir, origin } of roots) {
+    rootChunks.push(...loadMarkdownChunks(dir, 'target', { origin, baseDir: dir }));
+  }
+
+  const chunks = [...hostChunks, ...rootChunks];
 
   // Embed each chunk
   return chunks.map((chunk) => ({
@@ -261,8 +299,11 @@ export function assembleContext(chunks) {
 
   for (const chunk of chunks) {
     const preview = chunk.body?.slice(0, CHUNK_PREVIEW) || '';
+    const projectKey = chunk.origin?.projectKey;
     const meta = [
       chunk.source && `source:${chunk.source}`,
+      projectKey && projectKey !== 'self' && `project:${projectKey}`,
+      chunk.origin?.relPath && `path:${chunk.origin.relPath}`,
       chunk.role && `role:${chunk.role}`,
       chunk.category && `category:${chunk.category}`,
       chunk.createdAt && `date:${chunk.createdAt.slice(0, 10)}`,
@@ -302,7 +343,7 @@ export async function ask(question, { rootDir = process.cwd(), corpus, dryRun =
   if (dryRun) {
     return {
       answer: null,
-      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score })),
+      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score, origin: c.origin ?? null })),
       query: question,
     };
   }
@@ -333,7 +374,7 @@ export async function ask(question, { rootDir = process.cwd(), corpus, dryRun =
       .join('\n\n');
     return {
       answer: `[Claude CLI unavailable — showing retrieved context]\n\n${fallback}`,
-      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score })),
+      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score, origin: c.origin ?? null })),
       query: question,
       cliMissing: true,
     };
@@ -341,7 +382,7 @@ export async function ask(question, { rootDir = process.cwd(), corpus, dryRun =
 
   return {
     answer: (result.stdout || '').trim(),
-    sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score })),
+    sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score, origin: c.origin ?? null })),
     query: question,
   };
 }

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.' },
         },