stylegallery 0.1.0

package/scripts/test-audit-evidence-freshness.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { cleanupFixture, completeSession, initializeConsumer } from "./page-evidence-fixture.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const auditor = path.join(repositoryRoot, "scripts", "audit-evidence-freshness.mjs");
+const calibration = path.join(repositoryRoot, "consumer-reference", "baselines", "calibration.json");
+const selectedCase = process.argv.find((argument) => argument === "--case") ? process.argv[process.argv.indexOf("--case") + 1] : null;
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-freshness-"));
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function run(args) {
+  const child = spawnSync(process.execPath, [auditor, ...args, "--json"], { cwd: repositoryRoot, encoding: "utf8" });
+  let report;
+  try {
+    report = JSON.parse(child.stdout);
+  } catch (error) {
+    report = null;
+  }
+  return { child, report };
+}
+
+function result(name, expected, actual, ok) {
+  return { actual, expected, name, ok };
+}
+
+function pageSchema() {
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://stylegallery.test/page-evidence-manifest.schema.json",
+    additionalProperties: false,
+    properties: {
+      record_kind: { const: "page_evidence_manifest" },
+      review_by: { format: "date-time", type: "string" },
+      schema_version: { const: "1.0" },
+    },
+    required: ["record_kind", "review_by", "schema_version"],
+    type: "object",
+  };
+}
+
+function pageFixture(file, reviewBy) {
+  writeJson(file, { record_kind: "page_evidence_manifest", review_by: reviewBy, schema_version: "1.0" });
+}
+
+function selected(cases) {
+  if (!selectedCase) return cases;
+  const match = cases.filter((testCase) => testCase.name === selectedCase);
+  if (match.length === 0) {
+    return [result(selectedCase, "known --case", { cases: cases.map((testCase) => testCase.name) }, false)];
+  }
+  return match;
+}
+
+const pageSchemaPath = path.join(tempRoot, "page-evidence-manifest.schema.json");
+writeJson(pageSchemaPath, pageSchema());
+const pagePreDeadline = path.join(tempRoot, "review-window.json");
+pageFixture(pagePreDeadline, "2026-07-27T00:00:00Z");
+const pagePastDeadline = path.join(tempRoot, "review-past-deadline.json");
+pageFixture(pagePastDeadline, "2026-07-20T00:00:00Z");
+const pageAtDeadline = path.join(tempRoot, "review-at-deadline.json");
+pageFixture(pageAtDeadline, "2026-07-21T00:00:00Z");
+const pageFresh = path.join(tempRoot, "review-fresh.json");
+pageFixture(pageFresh, "2026-08-20T00:00:00Z");
+const malformed = path.join(tempRoot, "malformed.json");
+fs.writeFileSync(malformed, '{"record_kind":"page_evidence_manifest","review_by":"not-a-date","schema_version":"1.0"}\n');
+const unknown = path.join(tempRoot, "unknown.json");
+writeJson(unknown, { record_kind: "unsupported_evidence_manifest", schema_version: "1.0" });
+const missing = path.join(tempRoot, "missing.json");
+const missingPageSchema = path.join(tempRoot, "missing-page-evidence-manifest.schema.json");
+const completedPageFixture = initializeConsumer();
+const completedPage = completeSession(completedPageFixture);
+if (completedPage.validate?.status !== 0) throw new Error(`full page fixture failed: ${JSON.stringify(completedPage.validate?.report ?? completedPage.finalize?.report)}`);
+const completeManifest = JSON.parse(fs.readFileSync(path.join(completedPage.session.artifactRoot, "page-evidence-manifest.json"), "utf8"));
+const impossibleDateRecords = [
+  ["impossible-session-started-at", (value) => { value.session.started_at = "2023-02-30T12:00:00Z"; }],
+  ["impossible-session-completed-at", (value) => { value.session.completed_at = "2023-02-30T12:00:00Z"; }],
+  ["impossible-manifest-completed-at", (value) => { value.completed_at = "2023-02-30T12:00:00Z"; }],
+  ["impossible-scenario-recorded-at", (value) => { value.scenarios[0].recorded_at = "2023-02-30T12:00:00Z"; }],
+].map(([name, mutate]) => {
+  const value = structuredClone(completeManifest);
+  mutate(value);
+  const file = path.join(tempRoot, `${name}.json`);
+  writeJson(file, value);
+  return { file, name };
+});
+
+const cases = [
+  (() => {
+    const actual = run(["--record", pageFresh, "--page-schema", pageSchemaPath, "--as-of", "2023-02-30T12:00:00Z", "--mode", "advisory"]);
+    return result("impossible-as-of", "exit nonzero with as_of_invalid", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status }, actual.child.status !== 0 && actual.report?.failures?.some((item) => item.code === "as_of_invalid"));
+  })(),
+  ...impossibleDateRecords.map(({ file, name }) => (() => {
+    const actual = run(["--record", file, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    return result(name, "exit nonzero with freshness_record_invalid", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status }, actual.child.status !== 0 && actual.report?.failures?.some((item) => item.code === "freshness_record_invalid"));
+  })()),
+  (() => {
+    const actual = run(["--record", calibration, "--as-of", "2026-07-01T00:00:00Z", "--mode", "advisory"]);
+    return result("fresh-calibration", "exit 0 with status fresh and no warnings", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status, statuses: actual.report?.records?.map((item) => item.status) }, actual.child.status === 0 && actual.report?.ok === true && actual.report.records[0]?.status === "fresh" && actual.report.warnings.length === 0);
+  })(),
+  (() => {
+    const actual = run(["--record", calibration, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    return result("expiring-calibration-advisory", "exit 0 with expiring status and evidence_expiring warning", { codes: actual.report?.warnings?.map((item) => item.code), status: actual.child.status, statuses: actual.report?.records?.map((item) => item.status) }, actual.child.status === 0 && actual.report?.ok === true && actual.report.records[0]?.status === "expiring" && actual.report.warnings.some((item) => item.code === "evidence_expiring"));
+  })(),
+  (() => {
+    const actual = run(["--record", calibration, "--as-of", "2026-07-28T00:00:00Z", "--mode", "advisory"]);
+    return result("expired-calibration-advisory", "exit 0 with expired status and warning", { codes: actual.report?.warnings?.map((item) => item.code), status: actual.child.status, statuses: actual.report?.records?.map((item) => item.status) }, actual.child.status === 0 && actual.report?.ok === true && actual.report.records[0]?.status === "expired" && actual.report.warnings.some((item) => item.code === "evidence_expired"));
+  })(),
+  (() => {
+    const actual = run(["--record", pagePreDeadline, "--page-schema", pageSchemaPath, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    return result("pre-deadline-page-advisory", "exit 0 with expiring status and evidence_expiring warning", { codes: actual.report?.warnings?.map((item) => item.code), status: actual.child.status, statuses: actual.report?.records?.map((item) => item.status) }, actual.child.status === 0 && actual.report?.ok === true && actual.report.records[0]?.status === "expiring" && actual.report.warnings.some((item) => item.code === "evidence_expiring"));
+  })(),
+  (() => {
+    const actual = run(["--record", pagePreDeadline, "--page-schema", pageSchemaPath, "--as-of", "2026-07-21T00:00:00Z", "--mode", "blocking"]);
+    return result("pre-deadline-review-window-blocking", "exit 0 with expiring status, advisory evidence_expiring warning, and no blocking failure", { failureCodes: actual.report?.failures?.map((item) => item.code), warningCodes: actual.report?.warnings?.map((item) => item.code), status: actual.child.status, statuses: actual.report?.records?.map((item) => item.status) }, actual.child.status === 0 && actual.report?.ok === true && actual.report.records[0]?.status === "expiring" && actual.report.warnings.some((item) => item.code === "evidence_expiring") && actual.report.failures.length === 0);
+  })(),
+  (() => {
+    const actual = run(["--record", pagePastDeadline, "--page-schema", pageSchemaPath, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    return result("review-due-page-advisory", "exit 0 with review_due status and evidence_review_due warning", { codes: actual.report?.warnings?.map((item) => item.code), status: actual.child.status, statuses: actual.report?.records?.map((item) => item.status) }, actual.child.status === 0 && actual.report?.ok === true && actual.report.records[0]?.status === "review_due" && actual.report.warnings.some((item) => item.code === "evidence_review_due"));
+  })(),
+  (() => {
+    const before = fs.readFileSync(calibration);
+    const actual = run(["--record", calibration, "--record", pagePreDeadline, "--page-schema", pageSchemaPath, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    const after = fs.readFileSync(calibration);
+    return result("repeated-record-and-source-immutability", "two records are audited and calibration bytes remain unchanged", { bytesUnchanged: before.equals(after), count: actual.report?.records?.length, status: actual.child.status }, actual.child.status === 0 && actual.report?.records?.length === 2 && before.equals(after));
+  })(),
+  (() => {
+    const actual = run(["--record", pageFresh, "--page-schema", pageSchemaPath, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    return result("fresh-page-review", "exit 0 with fresh page evidence", { status: actual.child.status, statuses: actual.report?.records?.map((item) => item.status) }, actual.child.status === 0 && actual.report?.records[0]?.status === "fresh");
+  })(),
+  (() => {
+    const actual = run(["--record", malformed, "--page-schema", pageSchemaPath, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    return result("malformed-advisory", "exit nonzero with freshness_record_invalid", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status }, actual.child.status !== 0 && actual.report?.ok === false && actual.report.failures.some((item) => item.code === "freshness_record_invalid"));
+  })(),
+  (() => {
+    const actual = run(["--record", unknown, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    return result("unknown-record-kind", "exit nonzero with freshness_record_invalid", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status }, actual.child.status !== 0 && actual.report?.failures.some((item) => item.code === "freshness_record_invalid"));
+  })(),
+  (() => {
+    const actual = run(["--record", missing, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    return result("unreadable-record", "exit nonzero with freshness_record_unreadable", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status }, actual.child.status !== 0 && actual.report?.failures.some((item) => item.code === "freshness_record_unreadable"));
+  })(),
+  (() => {
+    const actual = run(["--record", pagePreDeadline, "--page-schema", missingPageSchema, "--as-of", "2026-07-21T00:00:00Z", "--mode", "advisory"]);
+    return result("missing-page-schema", "exit nonzero with freshness_schema_missing", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status }, actual.child.status !== 0 && actual.report?.failures.some((item) => item.code === "freshness_schema_missing"));
+  })(),
+  (() => {
+    const actual = run(["--record", calibration, "--as-of", "2026-07-28T00:00:00Z", "--mode", "blocking"]);
+    return result("expired-calibration-blocking", "exit nonzero with evidence_expired", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status }, actual.child.status !== 0 && actual.report?.failures.some((item) => item.code === "evidence_expired"));
+  })(),
+  (() => {
+    const actual = run(["--record", pagePastDeadline, "--page-schema", pageSchemaPath, "--as-of", "2026-07-21T00:00:00Z", "--mode", "blocking"]);
+    return result("review-due-blocking", "exit nonzero with evidence_review_due", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status, statuses: actual.report?.records?.map((item) => item.status) }, actual.child.status !== 0 && actual.report?.ok === false && actual.report.records[0]?.status === "review_due" && actual.report.failures.some((item) => item.code === "evidence_review_due"));
+  })(),
+  (() => {
+    const actual = run(["--record", pageAtDeadline, "--page-schema", pageSchemaPath, "--as-of", "2026-07-21T00:00:00Z", "--mode", "blocking"]);
+    return result("page-at-review-deadline-blocking", "exit nonzero with review_due/evidence_review_due at the deadline", { codes: actual.report?.failures?.map((item) => item.code), status: actual.child.status, statuses: actual.report?.records?.map((item) => item.status) }, actual.child.status !== 0 && actual.report?.ok === false && actual.report.records[0]?.status === "review_due" && actual.report.failures.some((item) => item.code === "evidence_review_due"));
+  })(),
+];
+
+try {
+  const report = { ok: selected(cases).every((testCase) => testCase.ok), results: selected(cases) };
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  process.exitCode = report.ok ? 0 : 1;
+} finally {
+  cleanupFixture(completedPageFixture);
+  fs.rmSync(tempRoot, { force: true, recursive: true });
+}

package/scripts/test-component-state-sentinel.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cases = [
+  ["key_runtime_mismatch", "runtime-key-mismatch", "state_activation_key_parity", "action-focused"],
+  ["pressed_false", "runtime-pressed-false", "pressed_surface_mismatch", "toggle-focused-pressed"],
+  ["visual_ready", "runtime-visual-ready", "visual_surface_parity", "toggle-focused-pressed"],
+  ["unknown_scenario", "runtime-unknown-scenario", "state_runtime_unknown_scenario", "action-focused"],
+  ["expanded_ax_mismatch", "runtime-expanded-ax-mismatch", "expanded_surface_mismatch", "disclosure-expanded-loading"],
+  ["disabled_activation", "runtime-disabled-activation", "state_activation_key_parity", "action-disabled-busy"],
+];
+
+const results = cases.map(([name, mutation, expected, scenario]) => {
+  const child = spawnSync(
+    path.join(repositoryRoot, "node_modules", ".bin", "playwright"),
+    ["test", "tests/component-state-evidence.spec.mjs", "--project=chromium", "--reporter=line", "--grep", scenario],
+    { cwd: repositoryRoot, encoding: "utf8", env: { ...process.env, STATE_MUTATION: mutation } },
+  );
+  const output = `${child.stdout}\n${child.stderr}`;
+  return {
+    actual: { named: output.includes(expected), status: child.status },
+    expected,
+    name,
+    ok: child.status !== 0 && output.includes(expected),
+  };
+});
+
+const failures = results.filter((result) => !result.ok).map((result) => `missing_semantic:${result.name}:${result.expected}`);
+const report = { failures, ok: failures.length === 0, results };
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+if (!report.ok) process.exitCode = 1;

package/scripts/test-component-state-source-contract.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+  canonicalSourceManifest,
+  repositoryGitArgs,
+  sourceManifestMatches,
+} from "./capture-session-contract.mjs";
+import { compileSchemas } from "./component-state-contract.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const profileRoot = path.join(repositoryRoot, "design-engineering/reference-profiles/governed-local");
+const schemaRoot = path.join(repositoryRoot, "consumer-reference/schema");
+const first = canonicalSourceManifest(repositoryRoot, profileRoot);
+const second = canonicalSourceManifest(repositoryRoot, profileRoot);
+
+assert.equal(first.sha256, second.sha256, "source manifest digest must be deterministic");
+assert.deepEqual(first.files, second.files, "source manifest files must be stable");
+assert(first.files.some((entry) => entry.path === "tests/component-state-evidence.spec.mjs"), "capture browser code must be bound");
+assert(first.files.some((entry) => entry.path === "playwright.config.mjs"), "Playwright capture configuration must be bound");
+assert(first.files.some((entry) => entry.path === "package.json"), "capture dependency declarations must be bound");
+assert(first.files.some((entry) => entry.path === "package-lock.json"), "exact capture dependencies must be bound");
+assert(first.files.some((entry) => entry.path === "scripts/artifact-metadata.mjs"), "capture artifact metadata code must be bound");
+assert(first.files.some((entry) => entry.path === "scripts/visual-expectation-contract.mjs"), "visual expectation selection must be bound");
+assert(!first.files.some((entry) => entry.path === "scripts/finalize-component-state-evidence.mjs"), "post-capture finalization must not invalidate captured source identity");
+assert(!first.files.some((entry) => entry.path === "scripts/validate-component-state.mjs"), "post-capture enforcement must not invalidate captured source identity");
+assert(first.files.some((entry) => entry.path.endsWith("/profile.json")), "profile declarations must be bound");
+assert(first.files.some((entry) => entry.path.endsWith("/tokens.dtcg.json")), "profile token inputs must be bound");
+assert.equal(sourceManifestMatches(first, repositoryRoot, profileRoot), true, "canonical source manifest must match itself");
+const revisionArgs = repositoryGitArgs(repositoryRoot, "rev-parse", "HEAD");
+assert.deepEqual(revisionArgs, ["-c", `safe.directory=${repositoryRoot}`, "rev-parse", "HEAD"], "repository Git trust must be scoped to the exact checkout");
+assert.equal(
+  execFileSync("git", revisionArgs, {
+    cwd: repositoryRoot,
+    encoding: "utf8",
+    env: { ...process.env, GIT_TEST_ASSUME_DIFFERENT_OWNER: "1" },
+  }).trim(),
+  execFileSync("git", revisionArgs, { cwd: repositoryRoot, encoding: "utf8" }).trim(),
+  "repository Git reads must trust only the exact checkout when container ownership differs",
+);
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-source-contract-"));
+try {
+  const copiedProfiles = path.join(tempRoot, "profiles");
+  const copiedRepository = path.join(tempRoot, "repository");
+  fs.cpSync(profileRoot, copiedProfiles, { recursive: true });
+  for (const entry of first.files.filter((candidate) => !candidate.path.startsWith("profiles/"))) {
+    const source = path.join(repositoryRoot, entry.path);
+    const target = path.join(copiedRepository, entry.path);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(source, target);
+  }
+  const copied = canonicalSourceManifest(copiedRepository, copiedProfiles);
+  assert.equal(copied.sha256, first.sha256, "profile-root location must not change the source digest");
+  const tokenFile = path.join(copiedProfiles, "editorial/tokens.dtcg.json");
+  fs.appendFileSync(tokenFile, "\n");
+  assert.equal(sourceManifestMatches(copied, copiedRepository, copiedProfiles), false, "profile source drift must invalidate the manifest");
+  fs.copyFileSync(path.join(profileRoot, "editorial/tokens.dtcg.json"), tokenFile);
+  const configFile = path.join(copiedRepository, "playwright.config.mjs");
+  const config = fs.readFileSync(configFile, "utf8").replace("viewport: { height: 768, width: 1024 },", "deviceScaleFactor: 2,\n    viewport: { height: 768, width: 1024 },");
+  fs.writeFileSync(configFile, config);
+  assert.equal(sourceManifestMatches(copied, copiedRepository, copiedProfiles), false, "deviceScaleFactor drift must invalidate the source manifest before it can double screenshot pixels");
+
+  const copiedSchemas = path.join(tempRoot, "schemas");
+  fs.cpSync(schemaRoot, copiedSchemas, { recursive: true });
+  const captureSchema = path.join(copiedSchemas, "capture-session.schema.json");
+  const schemaSource = fs.readFileSync(captureSchema, "utf8");
+  fs.writeFileSync(captureSchema, schemaSource.replace('"title":', '"title": "shadowed title",\n  "title":'));
+  assert.throws(
+    () => compileSchemas(copiedSchemas),
+    (error) => error?.code === "component_schema_json_invalid" && error?.path === captureSchema,
+    "duplicate component schema properties must fail strict compilation with a named error",
+  );
+} finally {
+  fs.rmSync(tempRoot, { force: true, recursive: true });
+}
+
+process.stdout.write(`${JSON.stringify({ files: first.files.length, ok: true, sha256: first.sha256 }, null, 2)}\n`);

package/scripts/test-consumer-conformance-sentinel.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const availableCases = new Map([
+  ["overflow", { expected: "document_no_horizontal_overflow", grep: "@sentinel-overflow", mutation: "overflow" }],
+  ["clipped-focus", { expected: "focus_geometry_visible", grep: "@sentinel-clipped-focus", mutation: "clipped-focus" }],
+  ["low-contrast", { expected: "color-contrast", grep: "@sentinel-low-contrast", mutation: "low-contrast" }],
+  ["dialog-focus-leak", { expected: "dialog_focus_trap", grep: "@sentinel-dialog-focus-leak", mutation: "dialog-focus-leak" }],
+  ["console-error", { expected: "console_error_free", grep: "@sentinel-console-error", mutation: "console-error" }],
+  ["page-evidence-symlink", { expected: "page_evidence_output_symlink", pageEvidence: "symlink" }],
+  ["page-evidence-existing-output", { expected: "page_evidence_output_exists", pageEvidence: "existing-output" }],
+  ["ci-cleanup-symlink", { ciCleanup: true, expected: ".tmp must be a real directory" }],
+]);
+const selected = [];
+let json = false;
+const argumentFailures = [];
+
+for (let index = 2; index < process.argv.length; index += 1) {
+  const argument = process.argv[index];
+  if (argument === "--json") json = true;
+  else if (argument === "--case") {
+    const name = process.argv[index + 1];
+    if (!name || name.startsWith("--")) argumentFailures.push("--case requires a value");
+    else {
+      selected.push(name);
+      index += 1;
+    }
+  } else argumentFailures.push(`unsupported argument ${argument}`);
+}
+
+const names = selected.length > 0 ? [...new Set(selected)] : [...availableCases.keys()];
+for (const name of names) if (!availableCases.has(name)) argumentFailures.push(`unknown case ${name}`);
+
+function runPlaywright(grep, environment) {
+  return spawnSync(
+    path.join(repositoryRoot, "node_modules", ".bin", "playwright"),
+    ["test", "tests/consumer-conformance.spec.mjs", "--project=chromium", "--reporter=line", "--grep", grep],
+    {
+      cwd: repositoryRoot,
+      encoding: "utf8",
+      env: { ...process.env, ...environment },
+      maxBuffer: 4 * 1024 * 1024,
+    },
+  );
+}
+
+function runMutationControl(name, control) {
+  const child = runPlaywright(control.grep, { CONSUMER_CONFORMANCE_MUTATION: control.mutation });
+  const output = `${child.stdout}\n${child.stderr}`;
+  return {
+    actual: { named: output.includes(control.expected), status: child.status },
+    expected: control.expected,
+    name,
+    ok: child.status !== 0 && output.includes(control.expected),
+  };
+}
+
+function writeReceipt(root) {
+  const receipt = {
+    attempt: 1,
+    intended_scenario_ids: ["responsive-layout"],
+    nonce: "a".repeat(64),
+    repository: "changeroa/StyleGallery",
+    revision: "b".repeat(40),
+    run_id: "consumer-conformance-sentinel-run",
+    session_id: "consumer-conformance-sentinel-session",
+    source: { sha256: "c".repeat(64) },
+  };
+  fs.writeFileSync(path.join(root, "page-evidence-session.json"), `${JSON.stringify(receipt)}\n`, { flag: "wx" });
+}
+
+function runPageEvidenceControl(name, control) {
+  const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-page-evidence-sentinel-"));
+  const observations = [];
+  try {
+    for (const outputKind of ["captures", "runner"]) {
+      const caseRoot = path.join(temporaryRoot, outputKind);
+      const artifactRoot = path.join(caseRoot, "artifacts");
+      const outside = path.join(caseRoot, "outside");
+      fs.mkdirSync(artifactRoot, { recursive: true });
+      fs.mkdirSync(outside, { recursive: true });
+      writeReceipt(artifactRoot);
+
+      const filename = outputKind === "captures"
+        ? "responsive-layout-state-w1024-focus.png"
+        : "responsive-layout.json";
+      const outputPath = path.join(artifactRoot, outputKind, filename);
+      const outsidePath = path.join(outside, filename);
+      const marker = "do-not-overwrite";
+      if (control.pageEvidence === "symlink") fs.symlinkSync(outside, path.join(artifactRoot, outputKind), "dir");
+      else {
+        fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+        fs.writeFileSync(outputPath, marker, { flag: "wx" });
+      }
+
+      const child = runPlaywright("state-w1024-focus", {
+        CONSUMER_CONFORMANCE_CAPTURE_DIR: "",
+        CONSUMER_CONFORMANCE_MUTATION: "none",
+        PAGE_EVIDENCE_ARTIFACT_ROOT: artifactRoot,
+        PAGE_EVIDENCE_CASE_ID: "state-w1024-focus",
+        PAGE_EVIDENCE_SCENARIO_ID: "responsive-layout",
+      });
+      const output = `${child.stdout}\n${child.stderr}`;
+      observations.push({
+        named: output.includes(control.expected),
+        output_kind: outputKind,
+        outside_write: fs.existsSync(outsidePath),
+        preserved: control.pageEvidence === "existing-output" ? fs.readFileSync(outputPath, "utf8") === marker : true,
+        status: child.status,
+      });
+    }
+  } finally {
+    fs.rmSync(temporaryRoot, { force: true, recursive: true });
+  }
+
+  return {
+    actual: { observations },
+    expected: control.expected,
+    name,
+    ok: observations.every((observation) => observation.status !== 0 && observation.named && !observation.outside_write && observation.preserved),
+  };
+}
+
+function runCiCleanupControl(name, control) {
+  const workspace = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-ci-cleanup-sentinel-"));
+  const outside = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-ci-cleanup-outside-"));
+  const marker = path.join(outside, "consumer", "preserve.txt");
+  try {
+    fs.mkdirSync(path.dirname(marker), { recursive: true });
+    fs.writeFileSync(marker, "preserve\n", { flag: "wx" });
+    fs.symlinkSync(outside, path.join(workspace, ".tmp"), "dir");
+    const child = spawnSync(process.execPath, [path.join(repositoryRoot, "scripts", "run-consumer-page-evidence-ci.mjs"), "cleanup", "--consumer-root", ".tmp/consumer"], { cwd: workspace, encoding: "utf8" });
+    const output = `${child.stdout}\n${child.stderr}`;
+    return {
+      actual: { markerPreserved: fs.readFileSync(marker, "utf8") === "preserve\n", named: output.includes(control.expected), status: child.status },
+      expected: control.expected,
+      name,
+      ok: child.status !== 0 && output.includes(control.expected) && fs.readFileSync(marker, "utf8") === "preserve\n",
+    };
+  } finally {
+    fs.rmSync(workspace, { force: true, recursive: true });
+    fs.rmSync(outside, { force: true, recursive: true });
+  }
+}
+
+const results = argumentFailures.length === 0 ? names.map((name) => {
+  const control = availableCases.get(name);
+  return control.pageEvidence ? runPageEvidenceControl(name, control) : control.ciCleanup ? runCiCleanupControl(name, control) : runMutationControl(name, control);
+}) : [];
+
+const failures = [
+  ...argumentFailures.map((message) => `argument_invalid:${message}`),
+  ...results.filter((result) => !result.ok).map((result) => `missing_semantic:${result.name}:${result.expected}`),
+];
+const report = { failures, ok: failures.length === 0, results };
+if (json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+else if (report.ok) process.stdout.write(`consumer conformance sentinel passed ${results.length} mutation controls\n`);
+else process.stderr.write(`${failures.join("\n")}\n`);
+if (!report.ok) process.exitCode = 1;

package/scripts/test-consumer-reference-sentinel.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cases = [
+  ["hidden_layout", "hidden-layout", "computed_layout_visible"],
+  ["long_content_reflow", "long-content-reflow", "computed_long_content_reflow"],
+];
+
+const results = cases.map(([name, mutation, expected]) => {
+  const child = spawnSync(
+    path.join(repositoryRoot, "node_modules", ".bin", "playwright"),
+    ["test", "tests/consumer-reference-sentinels.spec.mjs", "--project=chromium", "--reporter=line"],
+    { cwd: repositoryRoot, encoding: "utf8", env: { ...process.env, SENTINEL_MUTATION: mutation } },
+  );
+  const output = `${child.stdout}\n${child.stderr}`;
+  return {
+    actual: { named: output.includes(expected), status: child.status },
+    expected,
+    name,
+    ok: child.status !== 0 && output.includes(expected),
+  };
+});
+
+const failures = results.filter((result) => !result.ok).map((result) => `missing_semantic:${result.name}:${result.expected}`);
+const report = { failures, ok: failures.length === 0, results };
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+if (!report.ok) process.exitCode = 1;

package/scripts/test-generate-consumer-reference-evidence.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourceRoot = path.join(repositoryRoot, "design-engineering/reference-profiles/governed-local");
+const generator = path.join(repositoryRoot, "scripts/generate-consumer-reference-evidence.mjs");
+
+function run(root, check = false, environment = {}) {
+  const args = [generator, "--root", root, "--json"];
+  if (check) args.push("--check");
+  const child = spawnSync(process.execPath, args, { cwd: repositoryRoot, encoding: "utf8", env: { ...process.env, ...environment } });
+  let report = { failures: [], ok: false, parse_error: true };
+  try { report = JSON.parse(child.stdout); } catch { report = { failures: [], ok: false, parse_error: true }; }
+  return { report, status: child.status };
+}
+
+function editJson(file, mutate) {
+  const value = JSON.parse(fs.readFileSync(file, "utf8"));
+  mutate(value);
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-pr5-generator-"));
+const results = [];
+
+function freshRoot(name) {
+  const root = path.join(tempRoot, name);
+  fs.cpSync(sourceRoot, root, { recursive: true });
+  return root;
+}
+
+function expectFailure(name, expected, root) {
+  const child = run(root, true);
+  results.push({ expected, name, ok: child.status > 0 && child.report.failures.some((failure) => failure.code === expected) });
+}
+
+function mutateGenerated(name, expected, mutate) {
+  const root = freshRoot(name);
+  run(root);
+  const file = path.join(root, "editorial/generated/state-matrix.md");
+  const lines = fs.readFileSync(file, "utf8").split("\n");
+  mutate(lines);
+  fs.writeFileSync(file, lines.join("\n"));
+  expectFailure(name, expected, root);
+}
+
+try {
+  const canonicalRoot = freshRoot("canonical");
+  const generated = run(canonicalRoot);
+  results.push({ expected: "canonical_generation", name: "canonical", ok: generated.status === 0 && generated.report.ok && generated.report.scaffold !== true });
+  const checked = run(canonicalRoot, true);
+  results.push({ expected: "deterministic_zero_drift", name: "check", ok: checked.status === 0 && checked.report.ok && checked.report.scaffold !== true });
+
+  mutateGenerated("stale", "generated_stale", (lines) => { lines.push("stale"); });
+  mutateGenerated("generated_unsorted", "generated_unsorted", (lines) => {
+    const first = lines.findIndex((line) => line.startsWith("| <code>"));
+    [lines[first], lines[first + 1]] = [lines[first + 1], lines[first]];
+  });
+  mutateGenerated("generated_duplicate", "generated_duplicate_row", (lines) => {
+    const first = lines.findIndex((line) => line.startsWith("| <code>"));
+    lines.splice(first + 1, 0, lines[first]);
+  });
+  mutateGenerated("generated_missing", "generated_missing_row", (lines) => {
+    const first = lines.findIndex((line) => line.startsWith("| <code>"));
+    lines.splice(first, 1);
+  });
+  mutateGenerated("source_count", "generated_source_count_mismatch", (lines) => {
+    const first = lines.findIndex((line) => line.startsWith("| <code>"));
+    lines.splice(first, 1);
+  });
+
+  const unsortedRoot = freshRoot("source_unsorted");
+  editJson(path.join(unsortedRoot, "editorial/states/button.states.json"), (value) => { value.scenarios.reverse(); });
+  expectFailure("source_unsorted", "source_unsorted", unsortedRoot);
+
+  const duplicateRoot = freshRoot("scenario_duplicate");
+  editJson(path.join(duplicateRoot, "editorial/states/button.states.json"), (value) => { value.scenarios.push({ ...value.scenarios[0] }); });
+  expectFailure("scenario_duplicate", "scenario_duplicate", duplicateRoot);
+
+  const missingRoot = freshRoot("fixture_scenario_missing");
+  editJson(path.join(missingRoot, "editorial/states/button.states.json"), (value) => { value.scenarios = value.scenarios.filter((scenario) => scenario.id !== "action-focused"); });
+  expectFailure("fixture_scenario_missing", "fixture_scenario_missing", missingRoot);
+
+  const injectionRoot = freshRoot("markdown_injection");
+  editJson(path.join(injectionRoot, "editorial/components/button.component.json"), (value) => { value.semantic_modes[0].element = "<script>alert(1)</script>|`\nnext"; });
+  const injection = run(injectionRoot);
+  const injectionOutput = fs.readFileSync(path.join(injectionRoot, "editorial/generated/keyboard-matrix.md"), "utf8");
+  results.push({
+    expected: "escaped_markdown_injection",
+    name: "markdown_injection",
+    ok: injection.status === 0
+      && injectionOutput.includes("&lt;script&gt;alert(1)&lt;/script&gt;&#124;&#96;<br>next")
+      && !injectionOutput.includes("<script>alert(1)</script>"),
+  });
+
+  const referenceRoot = freshRoot("canonical_reference_discovery");
+  fs.copyFileSync(path.join(referenceRoot, "editorial/components/button.component.json"), path.join(referenceRoot, "editorial/components/alternate.component.json"));
+  editJson(path.join(referenceRoot, "editorial/components/alternate.component.json"), (value) => { value.semantic_modes[0].element = "canonical alternate element"; });
+  editJson(path.join(referenceRoot, "editorial/profile.json"), (value) => { value.component_records = ["components/alternate.component.json"]; });
+  editJson(path.join(referenceRoot, "editorial/fixtures/button.fixture.json"), (value) => { value.component_record = "../components/alternate.component.json"; });
+  const reference = run(referenceRoot);
+  const referenceOutput = fs.readFileSync(path.join(referenceRoot, "editorial/generated/keyboard-matrix.md"), "utf8");
+  results.push({ expected: "canonical_profile_reference", name: "canonical_reference_discovery", ok: reference.status === 0 && referenceOutput.includes("canonical alternate element") });
+
+  const localeRoot = freshRoot("locale_determinism");
+  const firstLocale = run(localeRoot, false, { LANG: "C", LC_ALL: "C" });
+  const firstBytes = fs.readFileSync(path.join(localeRoot, "editorial/generated/state-matrix.md"));
+  const secondLocale = run(localeRoot, false, { LANG: "tr_TR.UTF-8", LC_ALL: "tr_TR.UTF-8" });
+  const secondBytes = fs.readFileSync(path.join(localeRoot, "editorial/generated/state-matrix.md"));
+  results.push({ expected: "locale_independent_bytes", name: "locale_determinism", ok: firstLocale.status === 0 && secondLocale.status === 0 && firstBytes.equals(secondBytes) });
+} finally {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+const failures = results.filter((result) => !result.ok).map((result) => `missing_semantic:${result.name}:${result.expected}`);
+const report = { failures, ok: failures.length === 0, results };
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+assert.equal(report.ok, true);