reflection-check 0.0.1

package/dist/core/target-ir.js

@@ -0,0 +1,85 @@
+export function compileReflectionTargets(config) {
+    const targets = [];
+    const browser = config.contracts.browser;
+    if (browser && browser.enabled !== false) {
+        for (const route of browser.routes) {
+            targets.push({
+                id: route.id,
+                family: 'browser-route',
+                source: 'reflection-config',
+                runModes: ['smoke', 'full'],
+                blocking: browser.blocking ?? true,
+                route: {
+                    path: route.path,
+                    ...(route.name ? { name: route.name } : {}),
+                    viewports: route.viewports,
+                    expects: route.expects
+                },
+                browser: {
+                    baseUrl: browser.baseUrl,
+                    maskSelectors: browser.maskSelectors ?? []
+                }
+            });
+        }
+        for (const visualCase of browser.visualSmoke ?? []) {
+            targets.push({
+                id: visualCase.id,
+                family: 'route-visual',
+                source: 'reflection-config',
+                runModes: ['smoke', 'full'],
+                blocking: visualCase.blocking === true || visualCase.strict === true,
+                route: {
+                    path: visualCase.route
+                },
+                visual: {
+                    viewport: visualCase.viewport,
+                    baseline: visualCase.baseline,
+                    ...(visualCase.baselineRoot ? { baselineRoot: visualCase.baselineRoot } : {}),
+                    ...(visualCase.threshold !== undefined ? { threshold: visualCase.threshold } : {})
+                }
+            });
+        }
+    }
+    const component = config.contracts.component;
+    if (component && component.enabled !== false) {
+        for (const componentCase of component.cases) {
+            targets.push({
+                id: componentCase.id,
+                family: 'component-visual',
+                source: 'reflection-config',
+                runModes: ['visual', 'full'],
+                blocking: componentCase.blocking === true || componentCase.strict === true,
+                story: {
+                    storyId: componentCase.storyId,
+                    statePolicy: componentCase.browserState ? 'browser-forced-with-stabilization' : 'story-controlled',
+                    ...(componentCase.stateNote ? { stateNote: componentCase.stateNote } : {}),
+                    ...(componentCase.browserState ? { browserState: componentCase.browserState } : {})
+                },
+                visual: {
+                    viewport: componentCase.viewport ?? 'component',
+                    baseline: componentCase.baseline,
+                    ...(componentCase.baselineRoot ? { baselineRoot: componentCase.baselineRoot } : {}),
+                    ...(componentCase.threshold !== undefined ? { threshold: componentCase.threshold } : {})
+                }
+            });
+        }
+    }
+    const design = config.contracts.design;
+    if (design && design.enabled !== false) {
+        for (const designCommand of design.commands) {
+            targets.push({
+                id: designCommand.id,
+                family: 'design-command',
+                source: 'reflection-config',
+                runModes: ['design', 'full'],
+                blocking: designCommand.blocking ?? true,
+                command: {
+                    command: designCommand.command,
+                    ...(designCommand.cwd ? { cwd: designCommand.cwd } : {})
+                }
+            });
+        }
+    }
+    return { project: config.project, targets };
+}
+//# sourceMappingURL=target-ir.js.map

package/dist/core/target-ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-ir.js","sourceRoot":"","sources":["../../src/core/target-ir.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { defineReflection } from './core/define-reflection.js';
+export type { ReflectionConfig, ReflectionConfigInput, RunMode } from './core/config.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { defineReflection } from './core/define-reflection.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/integrations/playwright/browser-manager.d.ts

@@ -0,0 +1,2 @@
+import { type Browser } from 'playwright';
+export declare function launchBrowser(): Promise<Browser>;

package/dist/integrations/playwright/browser-manager.js

@@ -0,0 +1,5 @@
+import { chromium } from 'playwright';
+export async function launchBrowser() {
+    return chromium.launch({ headless: true });
+}
+//# sourceMappingURL=browser-manager.js.map

package/dist/integrations/playwright/browser-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-manager.js","sourceRoot":"","sources":["../../../src/integrations/playwright/browser-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAgB,MAAM,YAAY,CAAC;AAEpD,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,OAAO,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7C,CAAC"}

package/dist/integrations/playwright/context-factory.d.ts

@@ -0,0 +1,7 @@
+import type { Browser, BrowserContext } from 'playwright';
+export type ViewportName = 'desktop' | 'mobile' | 'tablet' | 'component';
+export declare function resolveViewport(viewport: string): {
+    width: number;
+    height: number;
+};
+export declare function createBrowserContext(browser: Browser, viewport: string): Promise<BrowserContext>;

package/dist/integrations/playwright/context-factory.js

@@ -0,0 +1,19 @@
+const viewportPresets = {
+    desktop: { width: 1440, height: 900 },
+    mobile: { width: 390, height: 844 },
+    tablet: { width: 820, height: 1180 },
+    component: { width: 390, height: 220 }
+};
+export function resolveViewport(viewport) {
+    return viewportPresets[viewport] ?? viewportPresets.desktop;
+}
+export async function createBrowserContext(browser, viewport) {
+    return browser.newContext({
+        viewport: resolveViewport(viewport),
+        deviceScaleFactor: 1,
+        locale: 'en-US',
+        timezoneId: 'Europe/Stockholm',
+        colorScheme: 'light'
+    });
+}
+//# sourceMappingURL=context-factory.js.map

package/dist/integrations/playwright/context-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-factory.js","sourceRoot":"","sources":["../../../src/integrations/playwright/context-factory.ts"],"names":[],"mappings":"AAIA,MAAM,eAAe,GAA4D;IAC/E,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IACrC,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;IACnC,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IACpC,SAAS,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;CACvC,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,eAAe,CAAC,QAAwB,CAAC,IAAI,eAAe,CAAC,OAAO,CAAC;AAC9E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAgB,EAAE,QAAgB;IAC3E,OAAO,OAAO,CAAC,UAAU,CAAC;QACxB,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC;QACnC,iBAAiB,EAAE,CAAC;QACpB,MAAM,EAAE,OAAO;QACf,UAAU,EAAE,kBAAkB;QAC9B,WAAW,EAAE,OAAO;KACrB,CAAC,CAAC;AACL,CAAC"}

package/dist/integrations/playwright/trace-policy.d.ts

@@ -0,0 +1,5 @@
+export type TracePolicy = {
+    trace: 'off' | 'retain-on-failure' | 'on';
+    video: 'off' | 'retain-on-failure' | 'on';
+};
+export declare function createTracePolicy(overrides?: Partial<TracePolicy>): TracePolicy;

package/dist/integrations/playwright/trace-policy.js

@@ -0,0 +1,7 @@
+export function createTracePolicy(overrides = {}) {
+    return {
+        trace: overrides.trace ?? 'off',
+        video: overrides.video ?? 'off'
+    };
+}
+//# sourceMappingURL=trace-policy.js.map

package/dist/integrations/playwright/trace-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-policy.js","sourceRoot":"","sources":["../../../src/integrations/playwright/trace-policy.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,iBAAiB,CAAC,YAAkC,EAAE;IACpE,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,KAAK;QAC/B,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,KAAK;KAChC,CAAC;AACJ,CAAC"}

package/dist/integrations/storybook/index-json.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+declare const StorybookEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodString;
+    importPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const StorybookIndexSchema: z.ZodObject<{
+    entries: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodString;
+        importPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StorybookEntry = z.output<typeof StorybookEntrySchema>;
+export type StorybookIndex = z.output<typeof StorybookIndexSchema>;
+export declare function loadStorybookIndex(baseUrl: string): Promise<StorybookIndex>;
+export {};

package/dist/integrations/storybook/index-json.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+const StorybookEntrySchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    name: z.string().min(1),
+    type: z.string().min(1),
+    importPath: z.string().optional()
+});
+const StorybookIndexSchema = z.object({
+    entries: z.record(z.string(), StorybookEntrySchema)
+});
+export async function loadStorybookIndex(baseUrl) {
+    const indexUrl = new URL('index.json', normalizeBaseUrl(baseUrl));
+    let response;
+    try {
+        response = await fetch(indexUrl, { cache: 'no-store' });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Reflection Storybook setup/config error: failed to load ${indexUrl.toString()}: ${message}`);
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(`Reflection Storybook setup/config error: failed to load ${indexUrl.toString()}: HTTP ${response.status}`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Reflection Storybook setup/config error: invalid JSON from ${indexUrl.toString()}: ${message}`);
+    }
+    const parsed = StorybookIndexSchema.safeParse(payload);
+    if (!parsed.success) {
+        const details = parsed.error.issues.map((issue) => `${issue.path.join('.') || 'index'}: ${issue.message}`).join('; ');
+        throw new Error(`Reflection Storybook setup/config error: invalid ${indexUrl.toString()}: ${details}`);
+    }
+    return parsed.data;
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+}
+//# sourceMappingURL=index-json.js.map

package/dist/integrations/storybook/index-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-json.js","sourceRoot":"","sources":["../../../src/integrations/storybook/index-json.ts"],"names":[],"mappings":"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"}

package/dist/integrations/storybook/server.d.ts

@@ -0,0 +1,8 @@
+import { type ManagedServer, type ServerConfig, type StartManagedServerOptions } from '../../core/server-manager.js';
+import { type StorybookIndex } from './index-json.js';
+export type StorybookServer = {
+    baseUrl: string;
+    index: StorybookIndex;
+    server: ManagedServer;
+};
+export declare function startStorybookServer(config: ServerConfig, options?: StartManagedServerOptions): Promise<StorybookServer>;

package/dist/integrations/storybook/server.js

@@ -0,0 +1,23 @@
+import { startManagedServer } from '../../core/server-manager.js';
+import { loadStorybookIndex } from './index-json.js';
+export async function startStorybookServer(config, options = {}) {
+    const server = await startManagedServer({
+        ...config,
+        readyUrl: storybookIndexUrl(config.readyUrl)
+    }, options);
+    try {
+        return {
+            baseUrl: config.readyUrl,
+            index: await loadStorybookIndex(config.readyUrl),
+            server
+        };
+    }
+    catch (error) {
+        await server.stop();
+        throw error;
+    }
+}
+function storybookIndexUrl(baseUrl) {
+    return new URL('index.json', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`).toString();
+}
+//# sourceMappingURL=server.js.map

package/dist/integrations/storybook/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/integrations/storybook/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAyE,MAAM,8BAA8B,CAAC;AACzI,OAAO,EAAE,kBAAkB,EAAuB,MAAM,iBAAiB,CAAC;AAQ1E,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAoB,EACpB,UAAqC,EAAE;IAEvC,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC;QACE,GAAG,MAAM;QACT,QAAQ,EAAE,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC;KAC7C,EACD,OAAO,CACR,CAAC;IAEF,IAAI,CAAC;QACH,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,QAAQ;YACxB,KAAK,EAAE,MAAM,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC;YAChD,MAAM;SACP,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAe;IACxC,OAAO,IAAI,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;AAC3F,CAAC"}

package/dist/integrations/storybook/story-url.d.ts

@@ -0,0 +1,2 @@
+import type { StorybookIndex } from './index-json.js';
+export declare function resolveStoryUrl(index: StorybookIndex, baseUrl: string, storyId: string): string;

package/dist/integrations/storybook/story-url.js

@@ -0,0 +1,13 @@
+export function resolveStoryUrl(index, baseUrl, storyId) {
+    const entry = index.entries[storyId];
+    if (!entry || entry.type !== 'story') {
+        throw new Error(`Reflection Storybook setup/config error: storyId "${storyId}" was not found or is not a story in ${new URL('index.json', normalizeBaseUrl(baseUrl)).toString()}`);
+    }
+    const url = new URL('iframe.html', normalizeBaseUrl(baseUrl));
+    url.searchParams.set('id', entry.id);
+    return url.toString();
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+}
+//# sourceMappingURL=story-url.js.map

package/dist/integrations/storybook/story-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"story-url.js","sourceRoot":"","sources":["../../../src/integrations/storybook/story-url.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,eAAe,CAAC,KAAqB,EAAE,OAAe,EAAE,OAAe;IACrF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,qDAAqD,OAAO,wCAAwC,IAAI,GAAG,CACzG,YAAY,EACZ,gBAAgB,CAAC,OAAO,CAAC,CAC1B,CAAC,QAAQ,EAAE,EAAE,CACf,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,aAAa,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IACrC,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAe;IACvC,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC;AACzD,CAAC"}

package/dist/utils/process.d.ts

@@ -0,0 +1,9 @@
+export type ManagedProcessOptions = {
+    cwd?: string;
+    logPath?: string;
+};
+export type ManagedProcess = {
+    pid: number | undefined;
+    stop: () => Promise<void>;
+};
+export declare function spawnManagedProcess(command: string, options?: ManagedProcessOptions): Promise<ManagedProcess>;

package/dist/utils/process.js

@@ -0,0 +1,69 @@
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createRedactionTransform } from '../core/redaction.js';
+export async function spawnManagedProcess(command, options = {}) {
+    let logStream;
+    if (options.logPath) {
+        await mkdir(dirname(options.logPath), { recursive: true });
+        logStream = createWriteStream(options.logPath, { flags: 'a' });
+    }
+    const spawnOptions = {
+        detached: true,
+        shell: true,
+        stdio: 'pipe'
+    };
+    if (options.cwd) {
+        spawnOptions.cwd = options.cwd;
+    }
+    const child = spawn(command, spawnOptions);
+    child.stdin?.end();
+    if (logStream) {
+        child.stdout?.pipe(createRedactionTransform()).pipe(logStream, { end: false });
+        child.stderr?.pipe(createRedactionTransform()).pipe(logStream, { end: false });
+    }
+    return {
+        pid: child.pid,
+        stop: () => stopChildProcess(child, logStream)
+    };
+}
+async function stopChildProcess(child, logStream) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        await closeLogStream(logStream);
+        return;
+    }
+    await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) {
+                killProcessGroup(child, 'SIGKILL');
+            }
+        }, 1_000);
+        child.once('close', () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+        killProcessGroup(child, 'SIGTERM');
+    });
+    await closeLogStream(logStream);
+}
+function killProcessGroup(child, signal) {
+    if (!child.pid) {
+        return;
+    }
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch {
+        child.kill(signal);
+    }
+}
+async function closeLogStream(logStream) {
+    if (!logStream || logStream.closed || logStream.destroyed) {
+        return;
+    }
+    await new Promise((resolve) => {
+        logStream.end(resolve);
+    });
+}
+//# sourceMappingURL=process.js.map

package/dist/utils/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../src/utils/process.ts"],"names":[],"mappings":"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"}

package/docs/agent-workflows.md

@@ -0,0 +1,146 @@
+# Agent workflows
+
+Reflection is meant to give agents an evidence gate for rendered UI work. Agents should use it to observe and report, not to silently heal visual changes.
+
+## Core agent loop
+
+Before claiming frontend work is complete:
+
+```bash
+reflection doctor
+reflection run --config reflection.config.ts --mode smoke
+reflection review --json
+```
+
+`reflection doctor` is currently a lightweight setup check. Treat `reflection run --config ...` as the command that exercises project contracts.
+
+If the project uses a non-default config path or report root, pass it explicitly:
+
+```bash
+reflection doctor
+reflection run --config path/to/reflection.config.ts --mode smoke --report-dir .reflection
+reflection review --report-dir .reflection --json
+```
+
+## How to interpret review JSON
+
+Treat the review summary as the handoff contract:
+
+- `status: "pass"` — validation passed.
+- `status: "pass-with-review"` — blocking checks passed, but the agent must summarize review items and artifact paths.
+- `status: "fail"` — blocking failures must be fixed before completion.
+- Tool/configuration errors mean the validation did not complete; report the blocker and fix setup when in scope.
+
+A good completion message includes:
+
+- commands run;
+- status;
+- report path;
+- blocking failures, if any;
+- review items, if any;
+- artifact paths for changed/failing UI;
+- whether any baseline update was dry-run only or human-approved non-dry.
+
+## Baseline update policy for agents
+
+Agents may propose a baseline update only with a dry run:
+
+```bash
+reflection update --route <routeId> --from-run latest --dry-run
+reflection update --case <routeVisualCaseId> --from-run latest --dry-run
+```
+
+`reflection update` currently targets route-level `visualSmoke` baselines. Component visual baseline promotion is still a manual review/copy step.
+
+Do not run non-dry `reflection update` unless the human explicitly approves that exact target.
+
+Never run `reflection update` in CI.
+
+After a human-approved non-dry update:
+
+1. Inspect the git diff.
+2. Report exactly which baseline files changed.
+3. Re-run `reflection run` and `reflection review --json` if the task requires proof that the new baseline now passes.
+
+## Handling `pass-with-review`
+
+`pass-with-review` is useful. It means the functional/browser contract did not block, but some artifact needs human attention.
+
+For visual diffs, include:
+
+- check id;
+- target route/story and viewport;
+- expected image path;
+- actual image path;
+- diff image path;
+- threshold metadata if present;
+- whether the case is review-only or strict/blocking.
+
+Do not hide review items behind "tests passed". The review item is the reason Reflection exists.
+
+## Suggested agent-file section
+
+Repository agent files should include a short pointer, not a copy of this whole guide.
+
+Supported files to update, in order of preference:
+
+- existing `AGENTS.md`;
+- existing `CLAUDE.md`;
+- existing `.github/copilot-instructions.md`;
+- existing `copilot-instructions.md`;
+- create `AGENTS.md` only if none exists.
+
+Suggested section:
+
+````md
+## Reflection validation
+
+Use Reflection as the UI evidence gate before claiming frontend work is complete.
+
+Run:
+
+```bash
+reflection doctor
+reflection run --config reflection.config.ts --mode smoke
+reflection review --json
+```
+
+Rules:
+
+- Treat blocking failures as task blockers.
+- Summarize review items with artifact paths for the human.
+- Use `reflection update --route <routeId> --from-run latest --dry-run` only to propose intentional visual changes.
+- Do not run non-dry `reflection update` unless the human explicitly approves it.
+- Never run `reflection update` in CI.
+
+Full protocol: `docs/validation-process.md`.
+````
+
+## CI workflow
+
+CI should run Reflection and upload artifacts, but never update baselines:
+
+```bash
+reflection doctor
+reflection run --ci --config reflection.config.ts --mode smoke
+reflection review --report-dir artifacts/reflection --json
+```
+
+`reflection run --ci` writes to `artifacts/reflection` by default, so pass the same report root to `review`.
+
+Upload the report root even on failure:
+
+```text
+artifacts/reflection/**
+```
+
+See `docs/ci.md` for current CI-specific defaults and exit codes.
+
+## Common mistakes
+
+- Treating generated evidence screenshots as baselines.
+- Running non-dry `reflection update` without human approval.
+- Ignoring `pass-with-review` because the shell exit code is `0`.
+- Deleting run artifacts before reporting the artifact paths.
+- Copying long Reflection instructions into multiple agent files and letting them drift.
+- Forgetting `--report-dir` when reviewing a CI or custom-root run.