@geraldmaron/construct 1.2.2 → 1.3.0

package/bin/construct-postinstall.mjs

@@ -26,7 +26,6 @@ import { fileURLToPath } from 'node:url';
 import { stageProjectAdapters } from '../lib/install/stage-project.mjs';
 import { syncProjectAdapters } from '../lib/adapters-sync.mjs';
 import { missingIgnorePatterns, isConstructPackageRepo } from '../lib/host-disposition.mjs';
-import { sanitizeNpmSpawnEnv } from '../lib/npm-spawn-env.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(HERE, '..');
@@ -74,27 +73,7 @@ try {
     } catch (err) {
       fail(`Tool-repo adapter sync failed: ${err.message}`, 'Run `npm run adapters` manually.');
     }
-    const chatBuild = spawnSync('npm', ['run', 'build:chat'], {
-      cwd: PKG_ROOT,
-      stdio: 'inherit',
-      env: sanitizeNpmSpawnEnv(process.env),
-    });
-    if (chatBuild.status !== 0) {
-      fail('Ink TUI build failed', 'Run `npm run build:chat` manually.');
-    } else {
-      log('built apps/chat/dist/tui.mjs');
-    }
 
-    const dashBuild = spawnSync('npm', ['run', 'build:dashboard'], {
-      cwd: PKG_ROOT,
-      stdio: 'inherit',
-      env: sanitizeNpmSpawnEnv(process.env),
-    });
-    if (dashBuild.status !== 0) {
-      fail('Dashboard build failed', 'Run `npm run build:dashboard` manually.');
-    } else {
-      log('built lib/server/static/ (dashboard)');
-    }
     process.exit(0);
   }
 } catch { /* fall through */ }

package/commands/work/optimize-prompts.md

@@ -12,7 +12,7 @@ Optimize prompt fragments and overlays, not the runtime orchestration policy. If
 
 ## Required steps
 
-1. **Read current prompt**: read the agent's prompt from `specialists/registry.json` (or its `promptFile`)
+1. **Read current prompt**: read the agent's prompt from `specialists/org` (or its `promptFile`)
 2. **Fetch recent scores**: GET `{CONSTRUCT_TELEMETRY_URL}/api/public/scores?name=quality&limit=200`
 3. **Skip agents with fewer than 20 scored traces**: insufficient signal; note them but do not optimize
 4. **Diagnose failure patterns**: analyze low-scoring traces, identify top 3 recurring patterns

package/examples/distribution/sources/adr.md

@@ -19,11 +19,11 @@ last_verified_at: 2026-06-22
 
 ## Problem
 
-Distribution exports (PDF, HTML, deck, PPTX) and dashboard/chat surfaces drifted when typography moved from retired font families to Space Grotesk and JetBrains Mono. Docs and templates cited stale names; some apps still declared unused npm font packages. Operators could not tell which file was canonical for brand behavior.
+Distribution exports (PDF, HTML, deck, PPTX) and interactive host surfaces drifted when typography moved from retired font families to Space Grotesk and JetBrains Mono. Docs and templates cited stale names; some apps still declared unused npm font packages. Operators could not tell which file was canonical for brand behavior.
 
 ## Context
 
-Construct ships a monochrome ink ramp and bundled OFL fonts under `templates/distribution/fonts/`. Chat and dashboard consume the same tokens via `lib/brand-tokens.mjs` and `lib/chat/design-tokens.mjs`. Profile-specific intake terminology flows through `lib/profiles/rebrand.mjs`.
+Construct ships a monochrome ink ramp and bundled OFL fonts under `templates/distribution/fonts/`. Published artifacts and interactive hosts consume the same tokens via `lib/brand-tokens.mjs`. Profile-specific intake terminology flows through `lib/scopes/rebrand.mjs`.
 
 ```mermaid
 flowchart LR

package/examples/seed-observations/decisions.md

@@ -33,4 +33,4 @@ Hook guards for workflow, drive, bootstrap, and task behavior are expressed as Y
 
 ## Registry as Single Source of Truth
 
-`specialists/registry.json` is the canonical definition for all agents on all platforms (Claude Code, OpenCode, Codex, Copilot). `construct sync` regenerates all platform-specific files from the registry. Never edit generated files directly: edits are overwritten on the next sync.
+`specialists/org` is the canonical definition for all agents on all platforms (Claude Code, OpenCode, Codex, Copilot). `construct sync` regenerates all platform-specific files from the registry. Never edit generated files directly: edits are overwritten on the next sync.

package/lib/artifact-loop-core.mjs

@@ -0,0 +1,412 @@
+/**
+ * lib/artifact-loop-core.mjs — Surface-neutral Construct artifact loop core.
+ *
+ * Intent resolution, typed-artifact drafting helpers, workflow-plan invocation,
+ * on-disk materialization, and the release gate — with zero host UI imports so
+ * the MCP server and supported hosts share one author→materialize→validate path.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { findConstructRoot, getArtifactEntry } from './artifact-manifest.mjs';
+import { validateArtifactRelease } from './artifact-release-gate.mjs';
+import { detectDocAuthoringIntent, resolveDocTypeMention } from './orchestration-policy.mjs';
+import { invokeWorkflow } from './embedded-contract/workflow-invoke.mjs';
+import { getTemplate } from './mcp/tools/skills.mjs';
+
+const LOOP_INTENT_RE = [
+  /\brun (?:it )?through (?:the )?(?:actual )?construct (?:artifact )?loop\b/i,
+  /\brun (?:this|that|it) through construct\b/i,
+  /\b(execute|run) (?:the )?(?:artifact|prd) (?:pipeline|workflow|gate)\b/i,
+  /\bconstruct(?:\s+artifact)?\s+loop\b/i,
+  /\bthrough the construct (?:artifact )?loop\b/i,
+];
+
+const LOOP_DOC_GATE_RE = /\b(?:loop|release gate|artifact gate|artifact validate)\b/i;
+const AUTHOR_VERBS_RE = /\b(write|writing|draft|drafting|create|creating|author|authoring|produce|producing|compose|composing|prepare|preparing|generate|generating)\b/i;
+const VALIDATE_FOLLOWUP_RE = /\b(run|execute|push|send|put)\b.*\b(?:it|this|that|the draft)\b.*\b(?:through|via)\b/i;
+const QUESTION_PREFIX_RE = /^\s*(what|how|why|when|where|who|which|is|are|does|do|can|could|should|would|tell me about|explain)\b/i;
+
+const OUTPUT_DIR_BY_TYPE = {
+  prd: 'docs/specs/prd',
+  'prd-platform': 'docs/prd-platform',
+  'prd-business': 'docs/prd-business',
+  'meta-prd': 'docs/meta-prd',
+  adr: 'docs/decisions/adr',
+  rfc: 'docs/decisions/rfc',
+  'research-brief': '.cx/research',
+  'evidence-brief': '.cx/knowledge/internal/evidence-briefs',
+  runbook: 'docs/runbooks',
+  strategy: '.cx',
+};
+
+const WORKFLOW_BY_TYPE = {
+  prd: 'prd-draft',
+  'prd-platform': 'prd-draft',
+  'prd-business': 'prd-draft',
+  'meta-prd': 'prd-draft',
+  adr: 'architecture-review',
+  rfc: 'architecture-review',
+};
+
+export function lastAssistantBody(turnBlocks = []) {
+  for (let i = turnBlocks.length - 1; i >= 0; i--) {
+    const item = turnBlocks[i];
+    if (item?.kind === 'turn' && item.block?.assistant?.trim()) {
+      return item.block.assistant.trim();
+    }
+  }
+  return null;
+}
+
+export function lastUserBody(turnBlocks = []) {
+  for (let i = turnBlocks.length - 1; i >= 0; i--) {
+    const item = turnBlocks[i];
+    if (item?.kind === 'turn' && item.block?.userText?.trim()) {
+      return item.block.userText.trim();
+    }
+  }
+  return null;
+}
+
+function combinedContext(text, turnBlocks) {
+  const parts = [String(text || ''), lastUserBody(turnBlocks), lastAssistantBody(turnBlocks)].filter(Boolean);
+  return parts.join('\n');
+}
+
+function mentionsConstructLoop(text) {
+  return LOOP_INTENT_RE.some((re) => re.test(text));
+}
+
+function isQuestion(text) {
+  const t = String(text || '').trim();
+  return QUESTION_PREFIX_RE.test(t) || /\?\s*$/.test(t);
+}
+
+function isValidateFollowUp(text) {
+  return VALIDATE_FOLLOWUP_RE.test(text)
+    || /\b(?:run|execute)\b.*\b(?:artifact|release)\s+gate\b/i.test(text)
+    || /\bvalidate (?:the )?(?:draft|artifact|prd)\b/i.test(text);
+}
+
+export function hasSubstantialDraft(turnBlocks = []) {
+  const draft = lastAssistantBody(turnBlocks);
+  return Boolean(draft && normalizeDraftMarkdown(draft).length >= 400 && /^#\s+/m.test(normalizeDraftMarkdown(draft)));
+}
+
+/**
+ * Resolve whether the user wants to author+loop or validate an existing draft.
+ * Returns null when the message should follow the normal host path.
+ */
+export function resolveArtifactLoopRequest(text, { turnBlocks = [], explicit = false } = {}) {
+  const t = String(text || '').trim();
+  if (!t) return null;
+
+  const loopMention = explicit || mentionsConstructLoop(t);
+  const docIntent = detectDocAuthoringIntent(combinedContext(t, turnBlocks));
+  const hybridLoopDoc = !loopMention && Boolean(docIntent) && LOOP_DOC_GATE_RE.test(t);
+
+  if (!loopMention && !hybridLoopDoc) return null;
+  if (!explicit && isQuestion(t)) return null;
+
+  const artifactType = resolveLoopArtifactType(t, turnBlocks);
+  const hasDraft = hasSubstantialDraft(turnBlocks);
+  const wantsAuthor = Boolean(
+    explicit && t.replace(/^\/loop\s*/i, '').trim()
+    || detectDocAuthoringIntent(t)
+    || docIntent
+    || AUTHOR_VERBS_RE.test(t),
+  );
+
+  if (hasDraft && (isValidateFollowUp(t) || (!wantsAuthor && loopMention))) {
+    return { mode: 'validate', artifactType };
+  }
+
+  if (wantsAuthor) {
+    return { mode: 'author', artifactType };
+  }
+
+  if (hasDraft) {
+    return { mode: 'validate', artifactType };
+  }
+
+  return null;
+}
+
+export function detectConstructLoopIntent(text, { turnBlocks = [], explicit = false } = {}) {
+  return resolveArtifactLoopRequest(text, { turnBlocks, explicit }) !== null;
+}
+
+export function resolveLoopArtifactType(text, turnBlocks) {
+  const blob = combinedContext(text, turnBlocks);
+  let type = detectDocAuthoringIntent(blob)?.docType || resolveDocTypeMention(blob) || 'prd';
+  const platformSignals = /\bplatform prd\b|\bteam mode\b|\bteam deployments\b|\benterprise\b|\boidc\b|\bsso\b|\bapi contract\b/i.test(blob);
+  if (platformSignals && (type === 'prd' || !type)) type = 'prd-platform';
+  if (/\bbusiness prd\b|\bmarket\b|\bpricing strategy\b/i.test(blob)) type = 'prd-business';
+  if (/\bmeta[\s-]prd\b/i.test(blob)) type = 'meta-prd';
+  return type;
+}
+
+function extractLoopSubject(userText) {
+  return String(userText || '')
+    .replace(/^\/loop\s*/i, '')
+    .replace(/\b(?:use |the )?construct(?:\s+artifact)?\s+loop\b/gi, '')
+    .replace(/\b(?:to|and)\s+(?:write|draft|create|generate|author|compose|produce|prepare)\b/gi, '')
+    .replace(/\b(?:write|draft|create|generate|author|compose|produce|prepare)\b/gi, '')
+    .replace(/\b(?:a|an|the)\s+/gi, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+export function buildArtifactAuthoringPrompt({
+  userText,
+  artifactType,
+  rootDir,
+  gateErrors = [],
+} = {}) {
+  const root = rootDir || findConstructRoot();
+  const entry = getArtifactEntry(artifactType, { rootDir: root });
+  const subject = extractLoopSubject(userText) || 'the requested topic';
+  const sectionHeadings = (entry?.structureRequirements || [])
+    .map((section) => `## ${section}`)
+    .join('\n');
+  const visualLines = (entry?.visualRequirements || []).map((req) => {
+    if (req.check === 'artifact-has-mermaid') {
+      return `- Include a fenced \`\`\`mermaid\`\`\` block with a ${req.diagram || 'flowchart'} diagram`;
+    }
+    if (req.check === 'artifact-table-has-columns' && Array.isArray(req.columns)) {
+      return `- Include a markdown table with columns: ${req.columns.join(' | ')} (with at least one data row)`;
+    }
+    return `- Satisfy visual requirement: ${req.id}`;
+  });
+  let templateExcerpt = '';
+  try {
+    const tmpl = getTemplate({ name: artifactType }, { ROOT_DIR: root });
+    if (tmpl?.content) {
+      templateExcerpt = tmpl.content.split('\n').slice(0, 40).join('\n');
+    }
+  } catch { /* template excerpt is best-effort */ }
+
+  const gateBlock = gateErrors.length
+    ? `\nPrevious draft failed the release gate. Fix every item:\n${gateErrors.map((e) => `- ${e}`).join('\n')}\n`
+    : '';
+
+  return `${String(userText || '').trim()}
+
+Produce a complete ${artifactType} markdown document for: ${subject}.
+${gateBlock}
+Required structure (use these ## headings):
+${sectionHeadings || '## Problem\n## Goals and non-goals\n## Success metrics'}
+
+Visual requirements:
+${visualLines.length ? visualLines.join('\n') : '- Include a mermaid flowchart and a metrics table when applicable'}
+
+Content rules:
+- Start with a single # title line
+- Write at least three prose paragraphs (not lists/tables alone) across the document
+- Use repo tools to find relevant paths before claiming facts; cite file paths or URLs
+- Mark unsupported claims [unverified]
+- Output only the document markdown (no preamble)
+
+Template reference (shape only):
+${templateExcerpt || '(no template excerpt)'}`;
+}
+
+function slugify(title) {
+  return String(title)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 56) || 'draft';
+}
+
+function extractTitle(draft, fallback = 'draft-artifact') {
+  if (!draft) return fallback;
+  const normalized = normalizeDraftMarkdown(draft);
+  const prd = normalized.match(/^#\s+(?:PRD:\s*)?(.+)$/m);
+  if (prd?.[1]) return prd[1].trim();
+  const h1 = normalized.match(/^#\s+(.+)$/m);
+  if (h1?.[1]) return h1[1].trim();
+  return fallback;
+}
+
+function todayStamp() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function outputPathForType(artifactType, slug, cwd) {
+  const relDir = OUTPUT_DIR_BY_TYPE[artifactType] || 'docs/specs/prd';
+  const fileName = artifactType === 'adr'
+    ? `ADR-draft-${slug}.md`
+    : `${todayStamp()}-${slug}.md`;
+  return path.join(cwd, relDir, fileName);
+}
+
+function fillTemplate(template, { title, date }) {
+  return template
+    .replace(/\{title\}/g, title)
+    .replace(/\{YYYY-MM-DD\}/g, date)
+    .replace(/\{name\}/g, 'cx-product-manager');
+}
+
+export function ensureFrontmatter(body, artifactType) {
+  if (/^---\r?\n[\s\S]*?\r?\n---/.test(body)) return body;
+  return `---
+artifactType: ${artifactType}
+status: draft
+owner: cx-product-manager
+last_verified_at: ${todayStamp()}
+---
+
+${body.trim()}\n`;
+}
+
+export function normalizeDraftMarkdown(draft) {
+  let text = String(draft || '').trim();
+  const fenced = text.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/i);
+  if (fenced) text = fenced[1].trim();
+  return text;
+}
+
+export function extractArtifactMarkdown(text) {
+  const normalized = normalizeDraftMarkdown(text);
+  if (!normalized) return null;
+  const idx = normalized.search(/^#\s+/m);
+  if (idx < 0) return null;
+  const doc = normalized.slice(idx).trim();
+  if (doc.length < 200) return null;
+  return doc;
+}
+
+function buildDraftBody({ artifactType, title, draftFromHost, draftMarkdown, rootDir, allowScaffold = true }) {
+  const source = draftMarkdown || (draftFromHost ? normalizeDraftMarkdown(draftFromHost) : null);
+  if (source && source.length >= 200 && /^#\s+/m.test(source)) {
+    return ensureFrontmatter(source, artifactType);
+  }
+  if (!allowScaffold) return null;
+  const tmpl = getTemplate({ name: artifactType }, { ROOT_DIR: rootDir });
+  if (tmpl?.content) {
+    return fillTemplate(tmpl.content, { title, date: todayStamp() });
+  }
+  return ensureFrontmatter(`# ${title}\n\n## Summary\n\nDraft scaffold — expand from workflow plan and evidence.\n`, artifactType);
+}
+
+export async function runConstructArtifactLoop({
+  text = '',
+  turnBlocks = [],
+  cwd = process.cwd(),
+  rootDir,
+  explicit = false,
+  artifactType: artifactTypeOverride,
+  draftMarkdown,
+  allowScaffold = true,
+} = {}) {
+  const root = rootDir || findConstructRoot(cwd);
+  const draftFromHost = draftMarkdown ? null : lastAssistantBody(turnBlocks);
+  const resolvedDraft = draftMarkdown || extractArtifactMarkdown(draftFromHost);
+  const artifactType = artifactTypeOverride || resolveLoopArtifactType(text, turnBlocks);
+  const title = extractTitle(
+    resolvedDraft || draftFromHost,
+    explicit ? (extractLoopSubject(text) || 'draft-artifact') : 'draft-artifact',
+  );
+  const slug = slugify(title);
+  const outPath = outputPathForType(artifactType, slug, cwd);
+  const workflowType = WORKFLOW_BY_TYPE[artifactType] || 'prd-draft';
+  const input = [
+    `Artifact loop: ${artifactType}`,
+    `Title: ${title}`,
+    resolvedDraft || draftFromHost
+      ? `Draft excerpt:\n${(resolvedDraft || draftFromHost).slice(0, 4000)}`
+      : String(text),
+  ].join('\n\n');
+
+  const invokePlan = await invokeWorkflow({
+    workflowType,
+    input,
+    approvalMode: 'proposal-only',
+    trace: true,
+  });
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  const body = buildDraftBody({
+    artifactType,
+    title,
+    draftFromHost,
+    draftMarkdown: resolvedDraft,
+    rootDir: root,
+    allowScaffold,
+  });
+  if (!body) {
+    const relPath = path.relative(cwd, outPath);
+    return {
+      ok: false,
+      artifactType,
+      path: null,
+      relPath,
+      title,
+      slug,
+      workflowType,
+      invokePlan,
+      validation: { ok: false, errors: ['No draft content to materialize'], warnings: [] },
+      summary: 'Release gate: not run — no draft content to materialize.',
+      draftMissing: true,
+      overlay: {
+        intent: 'doc-authoring',
+        workCategory: 'artifact-loop',
+        track: 'orchestrated',
+        specialists: (invokePlan?.selectedRoles || ['product-manager', 'architect']).map((r) => `cx-${r}`),
+        dispatchSummary: `artifact loop: ${artifactType} → validate`,
+      },
+    };
+  }
+  fs.writeFileSync(outPath, body.endsWith('\n') ? body : `${body}\n`);
+
+  const validation = validateArtifactRelease({
+    filePath: outPath,
+    type: artifactType,
+    cwd,
+    rootDir: root,
+  });
+
+  const relPath = path.relative(cwd, outPath);
+  const gateStatus = validation.ok
+    ? 'PASS'
+    : `FAIL (${validation.errors.length} error${validation.errors.length === 1 ? '' : 's'})`;
+  const summary = validation.ok
+    ? [
+      `Wrote ${relPath} (${artifactType}).`,
+      `Release gate: ${gateStatus}`,
+      invokePlan?.selectedRoles?.length
+        ? `Workflow plan (${workflowType}): ${invokePlan.selectedRoles.map((r) => `cx-${r}`).join(' → ')}`
+        : `Workflow plan (${workflowType}): ${invokePlan?.status || 'proposed'}`,
+      'Next: address gate findings, run specialists per plan, then `construct publish` if distributing.',
+    ].join('\n')
+    : [
+      `Draft failed release gate for ${relPath} (${artifactType}).`,
+      `Release gate: ${gateStatus}`,
+      invokePlan?.selectedRoles?.length
+        ? `Workflow plan (${workflowType}): ${invokePlan.selectedRoles.map((r) => `cx-${r}`).join(' → ')}`
+        : `Workflow plan (${workflowType}): ${invokePlan?.status || 'proposed'}`,
+      'Next: fix gate errors below, re-run `/loop` or `construct artifact validate`.',
+    ].join('\n');
+
+  return {
+    ok: validation.ok,
+    artifactType,
+    path: outPath,
+    relPath,
+    title,
+    slug,
+    workflowType,
+    invokePlan,
+    validation,
+    summary,
+    overlay: {
+      intent: 'doc-authoring',
+      workCategory: 'artifact-loop',
+      track: 'orchestrated',
+      specialists: (invokePlan?.selectedRoles || ['product-manager', 'architect']).map((r) => `cx-${r}`),
+      dispatchSummary: `artifact loop: ${artifactType} → validate`,
+    },
+  };
+}

package/lib/artifact-manifest.mjs

@@ -10,6 +10,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { resolveActiveScope } from './scopes/loader.mjs';
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EMPTY_MANIFEST = { version: 1, artifacts: {} };
@@ -233,6 +234,11 @@ export function resolveToneForArtifact(type, { cwd = process.cwd(), rootDir } =
   const brand = loadBrandVoice(cwd);
   const override = brand?.toneOverride?.[type];
   if (override) return override;
+  try {
+    const scope = resolveActiveScope(cwd);
+    const scopeTone = scope?.toneDefaults?.[type];
+    if (scopeTone) return scopeTone;
+  } catch { /* scope optional */ }
   return entry?.toneDefault ?? 'direct';
 }
 

package/lib/artifact-release-gate.mjs

@@ -7,7 +7,9 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import { lintDocStructure, lintDocVisuals } from './templates/visual-requirements.mjs';
+import { lintDocPresentationFile } from './templates/doc-presentation.mjs';
 import { getArtifactEntry, resolveToneForArtifact } from './artifact-manifest.mjs';
 import { lintFile } from './comment-lint.mjs';
 import {
@@ -44,6 +46,112 @@ function countCitations(body) {
   return hits.size;
 }
 
+export function dedupeGateErrors(errors = []) {
+  return [...new Set((errors || []).filter(Boolean))];
+}
+
+function validateArtifactBodyCore({
+  body,
+  resolvedType,
+  entry,
+  cwd,
+  rootDir,
+  reviewersSeen,
+  filePath = null,
+}) {
+  const gate = entry.releaseGate ?? {};
+  const errors = [];
+  const warnings = [];
+  const rawBody = String(body || '');
+  const stripped = rawBody.replace(/^---\n[\s\S]*?\n---\n/, '');
+  const bodyWithoutComments = stripped.replace(/<!--[\s\S]*?-->/g, '');
+
+  if (gate.structuralLint !== false && filePath) {
+    errors.push(...lintDocStructure(filePath, resolvedType));
+    errors.push(...lintDocVisuals(filePath, resolvedType));
+    const presentation = lintDocPresentationFile(filePath, resolvedType);
+    errors.push(...presentation.errors);
+    warnings.push(...presentation.warnings);
+  }
+
+  if (gate.citationLint) {
+    const isShippedTemplate = filePath?.includes(`${path.sep}templates${path.sep}docs${path.sep}`);
+    if (!isShippedTemplate) {
+      if (filePath) {
+        const lint = lintFile(filePath);
+        const artifactIssues = [...(lint.errors ?? []), ...(lint.warnings ?? [])].filter((w) => w.kind === 'artifact');
+        for (const issue of artifactIssues) errors.push(issue.message || String(issue));
+      }
+      const citations = countCitations(bodyWithoutComments);
+      const unverified = /\[unverified\]/i.test(bodyWithoutComments);
+      if (citations < 1 && !unverified) {
+        errors.push('citationLint: no verifiable sources or [unverified] markers');
+      }
+    }
+  }
+
+  const minProse = gate.proseMinimum ?? 0;
+  if (minProse > 0) {
+    const prose = countProseParagraphs(bodyWithoutComments);
+    if (prose < minProse) {
+      errors.push(`proseMinimum: ${prose} paragraphs (need ${minProse})`);
+    }
+  }
+
+  if (filePath) {
+    const missing = missingRequiredReviewers({
+      docType: resolvedType,
+      filePath,
+      rootDir,
+      cwd,
+      reviewersSeen,
+    });
+    if (missing.length > 0) {
+      warnings.push(`requiredReviewers not seen in agent log: ${missing.join(', ')}`);
+    }
+  }
+
+  return {
+    ok: dedupeGateErrors(errors).length === 0,
+    errors: dedupeGateErrors(errors),
+    warnings,
+    tone: resolveToneForArtifact(resolvedType, { cwd, rootDir }),
+    type: resolvedType,
+    filePath,
+  };
+}
+
+export function validateArtifactBody({
+  body,
+  type,
+  cwd = process.cwd(),
+  rootDir,
+  reviewersSeen,
+} = {}) {
+  const resolvedType = type;
+  const entry = getArtifactEntry(resolvedType, { rootDir });
+  if (!entry) {
+    return { ok: false, errors: [`Unknown artifact type: ${resolvedType}`], warnings: [], tone: null };
+  }
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cx-artifact-gate-'));
+  const filePath = path.join(tmpDir, 'draft.md');
+  try {
+    fs.writeFileSync(filePath, body.endsWith('\n') ? body : `${body}\n`);
+    return validateArtifactBodyCore({
+      body,
+      resolvedType,
+      entry,
+      cwd,
+      rootDir,
+      reviewersSeen,
+      filePath,
+    });
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
 export function validateArtifactRelease({
   filePath,
   type,
@@ -81,60 +189,18 @@ export function validateArtifactRelease({
     };
   }
 
-  const gate = entry.releaseGate ?? {};
-  const errors = [];
-  const warnings = [];
   const raw = fs.readFileSync(filePath, 'utf8');
-  const body = raw.replace(/^---\n[\s\S]*?\n---\n/, '');
-
-  if (gate.structuralLint !== false) {
-    errors.push(...lintDocStructure(filePath, resolvedType));
-    errors.push(...lintDocVisuals(filePath, resolvedType));
-  }
 
-  if (gate.citationLint) {
-    const isShippedTemplate = filePath.includes(`${path.sep}templates${path.sep}docs${path.sep}`);
-    if (!isShippedTemplate) {
-      const lint = lintFile(filePath);
-      const artifactIssues = [...(lint.errors ?? []), ...(lint.warnings ?? [])].filter((w) => w.kind === 'artifact');
-      for (const issue of artifactIssues) errors.push(issue.message || String(issue));
-      const citations = countCitations(body);
-      const unverified = /\[unverified\]/i.test(body);
-      if (citations < 1 && !unverified) {
-        errors.push('citationLint: no verifiable sources or [unverified] markers');
-      }
-    }
-  }
-
-  const minProse = gate.proseMinimum ?? 0;
-  if (minProse > 0) {
-    const prose = countProseParagraphs(body);
-    if (prose < minProse) {
-      errors.push(`proseMinimum: ${prose} paragraphs (need ${minProse})`);
-    }
-  }
-
-  const missing = missingRequiredReviewers({
-    docType: resolvedType,
-    filePath,
-    rootDir,
+  const result = validateArtifactBodyCore({
+    body: raw,
+    resolvedType,
+    entry,
     cwd,
+    rootDir,
     reviewersSeen,
-  });
-  if (missing.length > 0) {
-    warnings.push(`requiredReviewers not seen in agent log: ${missing.join(', ')}`);
-  }
-
-  const tone = resolveToneForArtifact(resolvedType, { cwd, rootDir });
-
-  return {
-    ok: errors.length === 0,
-    errors,
-    warnings,
-    tone,
-    type: resolvedType,
     filePath,
-  };
+  });
+  return { ...result, filePath };
 }
 
 export async function runArtifactValidateCli(args = []) {