@kbediako/codex-orchestrator 0.1.0

package/dist/scripts/design/pipeline/toolkit/tokens.js

@@ -0,0 +1,456 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadDesignContext } from '../context.js';
+import { appendToolkitArtifacts, ensureToolkitState, loadDesignRunState, saveDesignRunState, upsertStage, upsertToolkitContext } from '../state.js';
+import { stageArtifacts } from '../../../../orchestrator/src/persistence/ArtifactStager.js';
+import { buildRetentionMetadata } from './common.js';
+import { computeColorPalette, computeFontFamilies, normalizeSentenceSpacing } from './snapshot.js';
+async function main() {
+    const context = await loadDesignContext();
+    const state = await loadDesignRunState(context.statePath);
+    const stageId = 'design-toolkit-tokens';
+    const toolkitState = ensureToolkitState(state);
+    const contexts = toolkitState.contexts;
+    if (contexts.length === 0) {
+        upsertStage(state, {
+            id: stageId,
+            title: 'Toolkit token + style guide generation',
+            status: 'skipped',
+            notes: ['No toolkit contexts available. Run the extract stage first.']
+        });
+        await saveDesignRunState(context.statePath, state);
+        console.log('[design-toolkit-tokens] skipped — no contexts found');
+        return;
+    }
+    const retention = toolkitState.retention ?? {
+        days: state.retention?.days ?? 30,
+        autoPurge: state.retention?.autoPurge ?? false,
+        policy: state.retention?.policy ?? 'design.config.retention'
+    };
+    const tmpRoot = join(tmpdir(), `design-toolkit-tokens-${Date.now()}`);
+    await mkdir(tmpRoot, { recursive: true });
+    const artifacts = [];
+    const failures = [];
+    let processed = 0;
+    for (const entry of contexts) {
+        try {
+            const outputs = await buildTokenOutputs({ entry, repoRoot: context.repoRoot, tmpRoot });
+            const tokensRetention = buildRetentionMetadata(retention, new Date());
+            const stagedTokens = await stageArtifacts({
+                taskId: context.taskId,
+                runId: context.runId,
+                artifacts: [
+                    {
+                        path: relative(process.cwd(), outputs.tokensPath),
+                        description: `Token bundle for ${entry.slug}`
+                    }
+                ],
+                options: {
+                    relativeDir: `design-toolkit/tokens/${entry.slug}`,
+                    overwrite: true
+                }
+            });
+            const stagedGuide = await stageArtifacts({
+                taskId: context.taskId,
+                runId: context.runId,
+                artifacts: [
+                    {
+                        path: relative(process.cwd(), outputs.styleGuidePath),
+                        description: `Style guide for ${entry.slug}`
+                    }
+                ],
+                options: {
+                    relativeDir: `design-toolkit/styleguide/${entry.slug}`,
+                    overwrite: true
+                }
+            });
+            artifacts.push({
+                id: `${entry.slug}-tokens`,
+                stage: 'tokens',
+                status: 'succeeded',
+                relative_path: stagedTokens[0].path,
+                description: `Design tokens for ${entry.slug}`,
+                retention: tokensRetention,
+                metrics: {
+                    token_count: outputs.tokenCount,
+                    semantic_alias_count: outputs.semanticCount
+                }
+            });
+            artifacts.push({
+                id: `${entry.slug}-styleguide`,
+                stage: 'styleguide',
+                status: 'succeeded',
+                relative_path: stagedGuide[0].path,
+                description: `Style guide for ${entry.slug}`,
+                retention: tokensRetention,
+                metrics: {
+                    styleguide_pages: outputs.pageCount
+                }
+            });
+            upsertToolkitContext(state, {
+                ...entry,
+                tokensPath: stagedTokens[0].path,
+                styleguidePath: stagedGuide[0].path
+            });
+            processed += 1;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            failures.push(`${entry.slug}: ${message}`);
+            console.error(`[design-toolkit-tokens] failed for ${entry.slug}: ${message}`);
+        }
+    }
+    if (artifacts.length > 0) {
+        appendToolkitArtifacts(state, artifacts);
+    }
+    const status = failures.length === 0 && processed > 0 ? 'succeeded' : 'failed';
+    upsertStage(state, {
+        id: stageId,
+        title: 'Toolkit token + style guide generation',
+        status,
+        notes: failures.length > 0 ? failures : undefined,
+        metrics: {
+            context_count: contexts.length,
+            processed
+        },
+        artifacts: artifacts.map((artifact) => ({
+            relative_path: artifact.relative_path,
+            stage: artifact.stage,
+            status: artifact.status,
+            description: artifact.description ?? undefined
+        }))
+    });
+    await saveDesignRunState(context.statePath, state);
+    if (status === 'failed') {
+        throw new Error('Token or style guide generation failed.');
+    }
+    console.log(`[design-toolkit-tokens] generated tokens for ${processed} contexts`);
+}
+async function buildTokenOutputs(options) {
+    const { entry, repoRoot, tmpRoot } = options;
+    const desiredColorCount = 16;
+    const aggregatedCss = await loadAggregatedCss(entry, repoRoot);
+    const paletteFromFile = await loadPaletteFromFile(entry, repoRoot);
+    const palettePreview = Array.isArray(entry.palettePreview) ? mergeUniqueStrings(entry.palettePreview) : [];
+    const runtimeCanvasColors = Array.isArray(entry.runtimeCanvasColors) ? mergeUniqueStrings(entry.runtimeCanvasColors) : [];
+    const cssColors = computeColorPalette(aggregatedCss);
+    const palette = buildPalette(mergeUniqueStrings([...paletteFromFile, ...palettePreview, ...cssColors, ...runtimeCanvasColors]), desiredColorCount);
+    const sections = await loadSections(entry, repoRoot);
+    const cssFonts = computeFontFamilies(aggregatedCss);
+    const capturedFonts = Array.isArray(entry.fontFamilies) ? mergeUniqueStrings(entry.fontFamilies) : [];
+    const runtimeFonts = Array.isArray(entry.resolvedFonts) ? mergeUniqueStrings(entry.resolvedFonts) : [];
+    const mergedFonts = mergeUniqueStrings([...cssFonts, ...capturedFonts, ...runtimeFonts]);
+    const semanticColors = deriveSemanticColors(palette);
+    const semanticTokens = buildSemanticTokens(palette, semanticColors);
+    const tokens = {
+        "$schema": "https://design-tokens.github.io/community-group/format/module.json",
+        tokenSetOrder: ['global', 'semantic'],
+        global: {
+            color: buildColorTokens(palette),
+            radius: {
+                sm: { value: '4px' },
+                md: { value: '8px' },
+                lg: { value: '16px' }
+            },
+            spacing: {
+                xs: { value: '4px' },
+                sm: { value: '8px' },
+                md: { value: '16px' },
+                lg: { value: '24px' }
+            }
+        },
+        semantic: semanticTokens,
+        metadata: {
+            source: entry.url,
+            reference: entry.referenceUrl ?? entry.url,
+            css_path: entry.snapshotCssPath ?? null,
+            palette_sources: {
+                file: paletteFromFile.length,
+                extracted: cssColors.length,
+                preview: palettePreview.length,
+                runtime_canvas: runtimeCanvasColors.length
+            },
+            generated_at: new Date().toISOString(),
+            fonts: mergedFonts,
+            runtime_fonts: runtimeFonts,
+            palette_sample: palette.slice(0, 8),
+            runtime_canvas_colors: runtimeCanvasColors
+        }
+    };
+    const cssVariables = buildCssVariables(entry.slug, palette, semanticColors);
+    const styleGuide = buildStyleGuide(entry, palette, mergedFonts, sections, runtimeFonts, runtimeCanvasColors, semanticColors, {
+        paletteFromFileCount: paletteFromFile.length,
+        palettePreviewCount: palettePreview.length,
+        cssColorCount: cssColors.length
+    });
+    const slugDir = join(tmpRoot, entry.slug);
+    await mkdir(slugDir, { recursive: true });
+    const tokensPath = join(slugDir, 'tokens.json');
+    const cssPath = join(slugDir, 'tokens.css');
+    const styleGuidePath = join(slugDir, 'STYLE_GUIDE.md');
+    await Promise.all([
+        writeFile(tokensPath, JSON.stringify(tokens, null, 2), 'utf8'),
+        writeFile(cssPath, `:root\n{\n${cssVariables}\n}\n`, 'utf8'),
+        writeFile(styleGuidePath, styleGuide, 'utf8')
+    ]);
+    return {
+        tokensPath,
+        cssPath,
+        styleGuidePath,
+        tokenCount: palette.length,
+        semanticCount: Object.keys(semanticTokens).length,
+        pageCount: 1
+    };
+}
+async function loadAggregatedCss(entry, repoRoot) {
+    if (!entry.snapshotCssPath) {
+        return '';
+    }
+    try {
+        const absolute = join(repoRoot, entry.snapshotCssPath);
+        return await readFile(absolute, 'utf8');
+    }
+    catch (error) {
+        console.warn(`[design-toolkit-tokens] Failed to read aggregated CSS for ${entry.slug}:`, error);
+        return '';
+    }
+}
+async function loadPaletteFromFile(entry, repoRoot) {
+    if (!entry.palettePath) {
+        return [];
+    }
+    try {
+        const absolute = join(repoRoot, entry.palettePath);
+        const raw = await readFile(absolute, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+            return parsed
+                .map((value) => (typeof value === 'string' ? value.trim() : null))
+                .filter((value) => Boolean(value));
+        }
+    }
+    catch (error) {
+        console.warn(`[design-toolkit-tokens] Failed to read palette for ${entry.slug}:`, error);
+    }
+    return [];
+}
+async function loadSections(entry, repoRoot) {
+    if (!entry.sectionsPath) {
+        return [];
+    }
+    try {
+        const absolute = join(repoRoot, entry.sectionsPath);
+        const raw = await readFile(absolute, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed
+            .map((section) => ({
+            title: normalizeSentenceSpacing(section.title ?? 'Section')
+                .replace(/\s+/g, ' ')
+                .trim() || 'Section',
+            description: normalizeSentenceSpacing(section.description ?? '')
+                .replace(/\s+/g, ' ')
+                .trim()
+        }))
+            .filter((section) => section.description.length > 0);
+    }
+    catch (error) {
+        console.warn(`[design-toolkit-tokens] Failed to read sections for ${entry.slug}:`, error);
+    }
+    return [];
+}
+function buildPalette(candidates, desired) {
+    const normalized = mergeUniqueStrings(candidates.map(normalizeHexColor));
+    if (normalized.length >= desired) {
+        return normalized.slice(0, desired);
+    }
+    if (normalized.length === 0) {
+        return ['#111111', '#ffffff'].slice(0, desired);
+    }
+    const padded = [...normalized];
+    const anchor = normalized[normalized.length - 1];
+    padded.push(...padPalette(anchor, desired - normalized.length));
+    return padded.slice(0, desired);
+}
+function padPalette(anchor, additional) {
+    const rgb = hexToRgb(anchor);
+    if (!rgb) {
+        return Array.from({ length: additional }, () => anchor);
+    }
+    const { h, s, l } = rgbToHsl(rgb.r, rgb.g, rgb.b);
+    const results = [];
+    for (let step = 1; step <= additional; step += 1) {
+        const offset = Math.min(0.45, step * 0.08);
+        const lightness = Math.min(1, Math.max(0, l + (step % 2 === 0 ? -offset : offset)));
+        results.push(hslToHex(h, s, lightness));
+    }
+    return results;
+}
+function normalizeHexColor(value) {
+    if (!value.startsWith('#')) {
+        return value;
+    }
+    return value.length === 4
+        ? `#${value[1]}${value[1]}${value[2]}${value[2]}${value[3]}${value[3]}`.toLowerCase()
+        : value.toLowerCase();
+}
+function buildStyleGuide(entry, palette, fonts, sections, runtimeFonts, runtimeCanvasColors, semanticColors, paletteSources) {
+    const paletteList = palette.map((hex) => `- ${hex}`).join('\n');
+    const fontList = fonts.map((font) => `- ${font}`).join('\n');
+    const runtimeFontList = runtimeFonts.map((font) => `- ${font}`).join('\n');
+    const runtimeCanvasList = runtimeCanvasColors.map((hex) => `- ${hex}`).join('\n');
+    const sectionList = sections.length > 0
+        ? sections.map((section) => `- **${section.title}** — ${section.description}`).join('\n')
+        : '- (No sections detected)';
+    const canvasSection = runtimeCanvasList ? `\n## Canvas Samples\n${runtimeCanvasList}\n` : '\n';
+    const runtimeFontSection = runtimeFontList ? `\n## Resolved Typekit Fonts\n${runtimeFontList}\n` : '\n';
+    const paletteSourceNotes = [
+        `- Aggregated CSS colors: ${paletteSources.cssColorCount}`,
+        `- Palette file swatches: ${paletteSources.paletteFromFileCount}`,
+        `- Preview sample swatches: ${paletteSources.palettePreviewCount}`
+    ].join('\n');
+    return `# ${entry.slug} Style Guide\n\nGenerated tokens for ${entry.url}.\n\n## Palette\n${paletteList}\n\n## Semantic Roles\n- Background: ${semanticColors.background}\n- Foreground: ${semanticColors.foreground}\n- Accent: ${semanticColors.accent}\n\n## Palette Inputs\n${paletteSourceNotes}${canvasSection}\n## Typography (CSS)\n${fontList}${runtimeFontSection}\n## Layout Sections\n${sectionList}\n`;
+}
+function mergeUniqueStrings(values) {
+    const unique = [];
+    const seen = new Set();
+    for (const value of values) {
+        const text = typeof value === 'string' ? value.trim() : '';
+        if (!text || seen.has(text)) {
+            continue;
+        }
+        seen.add(text);
+        unique.push(text);
+    }
+    return unique;
+}
+function deriveSemanticColors(palette) {
+    if (palette.length === 0) {
+        return { foreground: '#0b0b0b', background: '#ffffff', accent: '#1d4ed8' };
+    }
+    const scoring = palette.map((hex) => {
+        const rgb = hexToRgb(hex);
+        if (!rgb) {
+            return { hex, lightness: 0.5, saturation: 0.5 };
+        }
+        const { l, s } = rgbToHsl(rgb.r, rgb.g, rgb.b);
+        return { hex, lightness: l, saturation: s };
+    });
+    const background = scoring.reduce((lightest, current) => (current.lightness > lightest.lightness ? current : lightest));
+    const foreground = scoring.reduce((darkest, current) => (current.lightness < darkest.lightness ? current : darkest));
+    const accentCandidate = scoring
+        .filter((entry) => entry.hex !== background.hex && entry.hex !== foreground.hex)
+        .reduce((vibrant, current) => (current.saturation > vibrant.saturation ? current : vibrant), scoring[0]);
+    return {
+        foreground: foreground.hex,
+        background: background.hex,
+        accent: accentCandidate.hex
+    };
+}
+function buildSemanticTokens(palette, semantic) {
+    const alias = (hex) => {
+        const index = palette.findIndex((value) => value.toLowerCase() === hex.toLowerCase());
+        if (index >= 0) {
+            return `{global.color.color-${index + 1}.value}`;
+        }
+        return hex;
+    };
+    return {
+        foreground: { value: alias(semantic.foreground) },
+        background: { value: alias(semantic.background) },
+        accent: { value: alias(semantic.accent) }
+    };
+}
+function buildColorTokens(palette) {
+    return Object.fromEntries(palette.map((hex, idx) => [`color-${idx + 1}`, { value: hex }]));
+}
+function buildCssVariables(slug, palette, semantic) {
+    const colors = palette.map((hex, idx) => `  --${slug}-color-${idx + 1}: ${hex};`);
+    const semanticVars = [
+        `  --${slug}-background: ${semantic.background};`,
+        `  --${slug}-foreground: ${semantic.foreground};`,
+        `  --${slug}-accent: ${semantic.accent};`
+    ];
+    return [...colors, ...semanticVars].join('\n');
+}
+function hexToRgb(hex) {
+    const normalized = normalizeHexColor(hex);
+    if (!/^#([0-9a-f]{6})$/i.test(normalized)) {
+        return null;
+    }
+    const value = normalized.slice(1);
+    return {
+        r: parseInt(value.slice(0, 2), 16),
+        g: parseInt(value.slice(2, 4), 16),
+        b: parseInt(value.slice(4, 6), 16)
+    };
+}
+function rgbToHsl(r, g, b) {
+    const nr = r / 255;
+    const ng = g / 255;
+    const nb = b / 255;
+    const max = Math.max(nr, ng, nb);
+    const min = Math.min(nr, ng, nb);
+    const delta = max - min;
+    let h = 0;
+    if (delta !== 0) {
+        if (max === nr) {
+            h = ((ng - nb) / delta) % 6;
+        }
+        else if (max === ng) {
+            h = (nb - nr) / delta + 2;
+        }
+        else {
+            h = (nr - ng) / delta + 4;
+        }
+    }
+    h = Math.round(h * 60);
+    if (h < 0) {
+        h += 360;
+    }
+    const l = (max + min) / 2;
+    const s = delta === 0 ? 0 : delta / (1 - Math.abs(2 * l - 1));
+    return { h, s, l };
+}
+function hslToHex(h, s, l) {
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = l - c / 2;
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    if (h >= 0 && h < 60) {
+        r = c;
+        g = x;
+    }
+    else if (h >= 60 && h < 120) {
+        r = x;
+        g = c;
+    }
+    else if (h >= 120 && h < 180) {
+        g = c;
+        b = x;
+    }
+    else if (h >= 180 && h < 240) {
+        g = x;
+        b = c;
+    }
+    else if (h >= 240 && h < 300) {
+        r = x;
+        b = c;
+    }
+    else {
+        r = c;
+        b = x;
+    }
+    const toHex = (value) => {
+        const scaled = Math.round((value + m) * 255);
+        return scaled.toString(16).padStart(2, '0');
+    };
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+main().catch((error) => {
+    console.error('[design-toolkit-tokens] failed to generate tokens');
+    console.error(error instanceof Error ? error.stack ?? error.message : error);
+    process.exitCode = 1;
+});

package/dist/scripts/design/pipeline/visual-regression.js

@@ -0,0 +1,137 @@
+import { spawn } from 'node:child_process';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadDesignContext } from './context.js';
+import { appendArtifacts, loadDesignRunState, saveDesignRunState, upsertStage } from './state.js';
+import { stageArtifacts } from '../../../orchestrator/src/persistence/ArtifactStager.js';
+const DESIGN_SYSTEM_DIR = 'packages/design-system';
+const SUMMARY_FILE = join(DESIGN_SYSTEM_DIR, '.codex', 'visual-regression-summary.json');
+async function main() {
+    const context = await loadDesignContext();
+    const state = await loadDesignRunState(context.statePath);
+    const stageId = 'design-visual-regression';
+    const designSystemExists = await pathExists(DESIGN_SYSTEM_DIR);
+    if (!designSystemExists) {
+        upsertStage(state, {
+            id: stageId,
+            title: 'Visual regression tests',
+            status: 'skipped',
+            notes: ['packages/design-system not present; skipping visual regression']
+        });
+        await saveDesignRunState(context.statePath, state);
+        console.log('[design-visual-regression] skipped — packages/design-system not found');
+        return;
+    }
+    const exitCode = await runVisualRegression();
+    const summaryData = await loadSummaryData(exitCode);
+    const tmpRoot = join(tmpdir(), `design-visual-${Date.now()}`);
+    await mkdir(tmpRoot, { recursive: true });
+    const tempFile = join(tmpRoot, 'visual-regression-summary.json');
+    await writeFile(tempFile, JSON.stringify(summaryData, null, 2), 'utf8');
+    const [staged] = await stageArtifacts({
+        taskId: context.taskId,
+        runId: context.runId,
+        artifacts: [
+            {
+                path: relative(process.cwd(), tempFile),
+                description: 'Visual regression summary'
+            }
+        ],
+        options: {
+            relativeDir: 'design/visual-regression',
+            overwrite: true
+        }
+    });
+    const artifact = {
+        stage: 'visual-regression',
+        status: exitCode === 0 ? 'succeeded' : 'failed',
+        relative_path: staged.path,
+        type: 'visual-regression-summary',
+        description: 'Visual regression results',
+        metadata: summaryData.report ? { report: summaryData.report } : undefined
+    };
+    appendArtifacts(state, [artifact]);
+    upsertStage(state, {
+        id: stageId,
+        title: 'Visual regression tests',
+        status: exitCode === 0 ? 'succeeded' : 'failed',
+        metrics: {
+            status: exitCode === 0 ? 'passed' : 'failed',
+            total: summaryData.metrics.total,
+            failed: summaryData.metrics.failed
+        },
+        artifacts: [
+            {
+                relative_path: staged.path,
+                stage: 'visual-regression',
+                status: exitCode === 0 ? 'succeeded' : 'failed',
+                description: 'visual-regression-summary.json'
+            }
+        ]
+    });
+    await saveDesignRunState(context.statePath, state);
+    const statusText = exitCode === 0 ? 'passed' : 'failed';
+    console.log(`[design-visual-regression] ${statusText}; summary staged at ${staged.path}`);
+}
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function runVisualRegression() {
+    return new Promise((resolve) => {
+        const child = spawn('npm', ['--prefix', DESIGN_SYSTEM_DIR, 'run', 'test:visual'], {
+            stdio: 'inherit'
+        });
+        child.on('close', (code) => {
+            resolve(code ?? 1);
+        });
+        child.on('error', () => {
+            resolve(1);
+        });
+    });
+}
+async function loadSummaryData(exitCode) {
+    try {
+        const raw = await readFile(SUMMARY_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        const metrics = parsed.metrics ?? {
+            total: exitCode === 0 ? 1 : 1,
+            failed: exitCode === 0 ? 0 : 1,
+            passed: exitCode === 0 ? 1 : 0
+        };
+        return {
+            generatedAt: new Date().toISOString(),
+            status: exitCode === 0 ? 'passed' : 'failed',
+            metrics: {
+                total: metrics.total ?? (exitCode === 0 ? 1 : 1),
+                failed: metrics.failed ?? (exitCode === 0 ? 0 : 1),
+                passed: metrics.passed ?? (exitCode === 0 ? 1 : 0)
+            },
+            report: parsed.report
+        };
+    }
+    catch {
+        return {
+            generatedAt: new Date().toISOString(),
+            status: exitCode === 0 ? 'passed' : 'failed',
+            metrics: {
+                total: exitCode === 0 ? 0 : 1,
+                failed: exitCode === 0 ? 0 : 1,
+                passed: exitCode === 0 ? 1 : 0
+            },
+            report: null
+        };
+    }
+}
+main().catch((error) => {
+    console.error('[design-visual-regression] failed to execute visual regression tests');
+    console.error(error instanceof Error ? error.stack ?? error.message : error);
+    process.exitCode = 1;
+});

package/dist/scripts/design/pipeline/write-artifacts.js

@@ -0,0 +1,61 @@
+import { loadDesignContext } from './context.js';
+import { ensureToolkitState, loadDesignRunState, saveDesignRunState, upsertStage } from './state.js';
+import { writeDesignSummary } from '../../../packages/shared/design-artifacts/writer.js';
+async function main() {
+    const context = await loadDesignContext();
+    const state = await loadDesignRunState(context.statePath);
+    const stageId = 'design-artifact-writer';
+    const toolkitState = ensureToolkitState(state);
+    const retention = state.retention ?? {
+        days: 30,
+        autoPurge: false,
+        policy: 'design.config.retention'
+    };
+    const privacy = state.privacy ?? {
+        allowThirdParty: false,
+        requireApproval: true,
+        maskSelectors: [],
+        approver: null
+    };
+    const result = await writeDesignSummary({
+        context: {
+            taskId: context.taskId,
+            runId: context.runId,
+            manifestPath: context.manifestPath,
+            repoRoot: context.repoRoot
+        },
+        stages: state.stages,
+        artifacts: state.artifacts,
+        configSnapshot: state.configSnapshot ?? null,
+        retention,
+        privacy,
+        approvals: state.approvals,
+        metrics: state.metrics,
+        designPlan: state.designPlan ?? undefined,
+        designGuardrail: state.designGuardrail ?? undefined,
+        designHistory: state.designHistory ?? undefined,
+        designStyleProfile: state.designStyleProfile ?? undefined,
+        designMetrics: state.designMetrics ?? undefined,
+        toolkitArtifacts: toolkitState.artifacts,
+        toolkitSummary: toolkitState.summary ?? undefined,
+        outDir: context.outRoot,
+        now: new Date()
+    });
+    toolkitState.summary =
+        result.summary.design_toolkit_summary ?? null;
+    upsertStage(state, {
+        id: stageId,
+        title: 'Persist design artifact summary',
+        status: 'succeeded',
+        metrics: {
+            summary_path: result.summaryPath
+        }
+    });
+    await saveDesignRunState(context.statePath, state);
+    console.log(`[design-artifact-writer] summary written to ${result.summaryPath}`);
+}
+main().catch((error) => {
+    console.error('[design-artifact-writer] failed to persist design artifact summary');
+    console.error(error instanceof Error ? error.stack ?? error.message : error);
+    process.exitCode = 1;
+});