stylegallery 0.1.0

package/scripts/consumer-evidence-governance-contract.mjs

@@ -0,0 +1,210 @@
+import { immutableActionPins } from "./governance-policy-contract.mjs";
+import { workflowActionFailures } from "./workflow-action-contract.mjs";
+
+const validatePath = ".github/workflows/validate.yml";
+const freshnessPath = ".github/workflows/evidence-freshness.yml";
+
+function workflowJob(workflow, id) {
+  const marker = `  ${id}:\n`;
+  const start = workflow.indexOf(marker);
+  if (start === -1) return "";
+  const remainder = workflow.slice(start + marker.length);
+  const next = remainder.search(/^  [a-zA-Z0-9_-]+:/m);
+  return marker + (next === -1 ? remainder : remainder.slice(0, next));
+}
+
+function missing(relative, content, fragments) {
+  return fragments.flatMap(([fragment, label = fragment]) => content.includes(fragment) ? [] : [`${relative}: missing ${label}`]);
+}
+
+function missingCommands(relative, content, fragments) {
+  const commands = content.split("\n").map((line) => line.trim()).filter(Boolean);
+  return fragments.flatMap(([fragment, label = fragment]) => commands.some((command) => {
+    let candidate = command;
+    const assignment = /^[A-Za-z_][A-Za-z0-9_]*=(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s]+)?\s+/;
+    if (candidate.startsWith("env ")) candidate = candidate.slice(4);
+    while (true) {
+      const withoutUnset = candidate.replace(/^-u\s+[A-Za-z_][A-Za-z0-9_]*\s+/, "");
+      if (withoutUnset !== candidate) {
+        candidate = withoutUnset;
+        continue;
+      }
+      const withoutAssignment = candidate.replace(assignment, "");
+      if (withoutAssignment === candidate) break;
+      candidate = withoutAssignment;
+    }
+    if (candidate !== fragment && !candidate.startsWith(`${fragment} `)) return false;
+    const suffix = candidate.slice(fragment.length);
+    return !/(?:&&|\|\||[;&|])/.test(suffix);
+  }) ? [] : [`${relative}: missing ${label}`]);
+}
+
+function hasIf(lines, indentation) {
+  const pattern = new RegExp(`^ {${indentation}}(?:-\\s+)?["']?if["']?:\\s*`);
+  return lines.some((line) => pattern.test(line));
+}
+
+function hasLiteralDisabledIf(lines, indentation) {
+  const pattern = new RegExp(`^ {${indentation}}(?:-\\s+)?["']?if["']?:\\s*(?:false|['"]false['"]|\\$\\{\\{\\s*false\\s*\\}\\})(?:\\s+#.*)?$`, "i");
+  return lines.some((line) => pattern.test(line));
+}
+
+function executableRunText(workflow) {
+  const lines = workflow.split("\n");
+  const commands = [];
+  const stepsLine = lines.findIndex((line) => /^\s*steps:\s*$/.test(line));
+  if (stepsLine === -1) return "";
+  const stepsIndent = lines[stepsLine].match(/^\s*/)[0].length;
+  for (let index = stepsLine + 1; index < lines.length;) {
+    const start = lines[index].match(new RegExp(`^ {${stepsIndent + 2}}-\\s+`));
+    if (!start) {
+      if (lines[index].trim() && lines[index].match(/^\s*/)[0].length <= stepsIndent) break;
+      index += 1;
+      continue;
+    }
+    let end = index + 1;
+    while (end < lines.length && !new RegExp(`^ {${stepsIndent + 2}}-\\s+`).test(lines[end]) && (!lines[end].trim() || lines[end].match(/^\s*/)[0].length > stepsIndent)) end += 1;
+    const step = lines.slice(index, end);
+    if (!hasIf(step, stepsIndent + 2) && !hasIf(step, stepsIndent + 4)) {
+      const runIndex = step.findIndex((line) => new RegExp(`^(?: {${stepsIndent + 2}}-\\s+| {${stepsIndent + 4}})run:`).test(line));
+      if (runIndex !== -1) {
+        const match = step[runIndex].match(/^\s*(?:-\s+)?run:\s*(.*)$/);
+        const scalar = match[1].replace(/\s+#.*$/, "").trim();
+        if (scalar && !["|", ">", "|-", ">-"].includes(scalar)) commands.push(scalar);
+        if (["|", ">", "|-", ">-"].includes(scalar)) {
+          const blockCommands = [];
+          let heredoc;
+          for (const raw of step.slice(runIndex + 1)) {
+            const command = raw.trim();
+            if (!command || command.startsWith("#")) continue;
+            if (heredoc) {
+              if (command === heredoc) heredoc = undefined;
+              continue;
+            }
+            const opener = command.match(/<<-?\s*['"]?([A-Za-z0-9_]+)['"]?/);
+            blockCommands.push(command.replace(/\s+#.*$/, "").trim());
+            if (opener) heredoc = opener[1];
+          }
+          if (scalar.startsWith(">")) commands.push(blockCommands.join(" "));
+          else commands.push(...blockCommands);
+        }
+      }
+    }
+    index = end;
+  }
+  const logicalCommands = [];
+  let logical = "";
+  for (const command of commands) {
+    logical = logical ? `${logical} ${command}` : command;
+    if (logical.endsWith("\\")) {
+      logical = logical.slice(0, -1).trimEnd();
+      continue;
+    }
+    logicalCommands.push(logical);
+    logical = "";
+  }
+  if (logical) logicalCommands.push(logical);
+  return logicalCommands.join("\n");
+}
+
+export function consumerEvidenceGovernanceFailures({ evidence, freshnessWorkflow, governance, validationWorkflow }) {
+  const failures = [];
+  failures.push(...missing("GOVERNANCE.md", governance, [
+    ["scheduled_stale_audit: deferred"],
+    ["scheduled_evidence_audit: active_advisory"],
+    ["Decision: run a weekly advisory audit only for evidence records that already declare `expires_at` or `review_by`."],
+    ["No repository-wide maximum age or inferred time-to-live applies."],
+    ["Malformed records and auditor failures remain blocking even though due-date findings are advisory."],
+    [freshnessPath],
+    ["Monday at 05:00 UTC"],
+  ]));
+  failures.push(...missing("quality/evidence/executable-evidence.md", evidence, [
+    ["Explicit evidence deadlines are audited weekly without inventing a repository-wide maximum age."],
+    ["Malformed records and auditor failures remain blocking even though due-date findings are advisory."],
+  ]));
+  const validationCommands = executableRunText(workflowJob(validationWorkflow, "validate"));
+  failures.push(...missingCommands(`${validatePath}: validate`, validationCommands, [
+    ["node -c scripts/consumer-evidence-governance-contract.mjs"],
+    ["node -c scripts/json-schema-formats.mjs"],
+    ["node -c scripts/consumer-conformance-contract.mjs"],
+    ["node -c scripts/validate-consumer-conformance.mjs"],
+    ["node -c scripts/test-validate-consumer-conformance.mjs"],
+    ["node -c consumer-reference/fixtures/consumer-conformance/e2e-fixture.mjs"],
+    ["node -c scripts/page-evidence-contract.mjs"],
+    ["node -c scripts/page-evidence-fixture.mjs"],
+    ["node -c scripts/create-page-evidence-session.mjs"],
+    ["node -c scripts/finalize-page-evidence.mjs"],
+    ["node -c scripts/validate-page-evidence.mjs"],
+    ["node -c scripts/test-validate-page-evidence.mjs"],
+    ["node -c scripts/audit-evidence-freshness.mjs"],
+    ["node -c scripts/test-audit-evidence-freshness.mjs"],
+    ["node -c tests/fixtures/consumer-conformance-scenarios.mjs"],
+    ["node -c tests/helpers/render-consumer-conformance.mjs"],
+    ["node -c tests/consumer-conformance.spec.mjs"],
+    ["node -c scripts/test-consumer-conformance-sentinel.mjs"],
+    ["node scripts/test-validate-consumer-conformance.mjs --case valid-runtime-proof --json"],
+    ["node scripts/test-validate-consumer-conformance.mjs --json"],
+    ["node scripts/test-validate-page-evidence.mjs --json"],
+    ["node scripts/test-audit-evidence-freshness.mjs --json"],
+    [`node -e 'JSON.parse(require("fs").readFileSync("consumer-reference/schema/consumer-conformance-record.schema.json"))'`],
+    [`node -e 'JSON.parse(require("fs").readFileSync("consumer-reference/schema/page-evidence-session.schema.json"))'`],
+    [`node -e 'JSON.parse(require("fs").readFileSync("consumer-reference/schema/page-evidence-manifest.schema.json"))'`],
+  ]));
+
+  const blocking = workflowJob(validationWorkflow, "consumer-conformance");
+  if (!blocking) failures.push(`${validatePath}: missing consumer-conformance job`);
+  else {
+    if (hasLiteralDisabledIf(blocking.split("\n"), 4)) failures.push(`${validatePath}: consumer-conformance job must be enabled`);
+    if (hasIf(blocking.split("\n"), 4)) failures.push(`${validatePath}: consumer-conformance job must be unconditional`);
+    if (hasIf(blocking.split("\n"), 6) || hasIf(blocking.split("\n"), 8)) failures.push(`${validatePath}: consumer-conformance: required command steps must be unconditional`);
+    if (/^\s+continue-on-error:/m.test(blocking)) failures.push(`${validatePath}: consumer-conformance must be blocking`);
+    failures.push(...missing(`${validatePath}: consumer-conformance`, blocking, [
+      ["mcr.microsoft.com/playwright:v1.61.0-noble@sha256:57b65fdc9ceabe0ef613124c7bbe2babcf9362c4d85e382fe3b03604e84b428a"],
+    ]));
+    failures.push(...missingCommands(`${validatePath}: consumer-conformance`, executableRunText(blocking), [
+      ["npx playwright test tests/consumer-conformance.spec.mjs --project=chromium --reporter=line"],
+      ["node scripts/test-consumer-conformance-sentinel.mjs --json"],
+    ]));
+  }
+  const capture = workflowJob(validationWorkflow, "consumer-page-evidence");
+  if (!capture) failures.push(`${validatePath}: missing consumer-page-evidence job`);
+  else {
+    if (!/^\s+continue-on-error:\s*true\s*$/m.test(capture)) failures.push(`${validatePath}: consumer-page-evidence must be nonblocking`);
+    failures.push(...missing(`${validatePath}: consumer-page-evidence`, capture, [
+      ["CONSUMER_CONFORMANCE_CAPTURE_DIR: .tmp/consumer-page-evidence"],
+      ["actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02"],
+      ["retention-days: 14"],
+    ]));
+    failures.push(...missingCommands(`${validatePath}: consumer-page-evidence`, executableRunText(capture), [
+      ["node scripts/create-page-evidence-session.mjs"],
+      ["npx playwright test tests/consumer-conformance.spec.mjs --project=chromium --reporter=line"],
+      ["node scripts/finalize-page-evidence.mjs"],
+      ["node scripts/validate-page-evidence.mjs"],
+    ]));
+  }
+
+  failures.push(...missing(freshnessPath, freshnessWorkflow, [
+    ["workflow_dispatch:"],
+    ["cron: '0 5 * * 1'", "Monday 05:00 UTC schedule"],
+    ["contents: read"],
+    ["persist-credentials: false"],
+    ["evidence-freshness-report.json", "JSON report"],
+    ["::warning file=", "GitHub warning emission"],
+    ["if: always()", "always-upload evidence"],
+    ["actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02", "immutable upload action"],
+    ["retention-days: 14", "14-day retention"],
+  ]));
+  failures.push(...missing(freshnessPath, executableRunText(freshnessWorkflow), [
+    ["scripts/audit-evidence-freshness.mjs", "freshness auditor"],
+    ["--record consumer-reference/baselines/calibration.json", "explicit calibration record inventory"],
+    ["--mode advisory"],
+  ]));
+  if (/continue-on-error\s*:/i.test(freshnessWorkflow)) failures.push(`${freshnessPath}: continue-on-error is forbidden because malformed records and tool failures must block`);
+  for (const pin of immutableActionPins) {
+    if ((pin.includes("actions/checkout") || pin.includes("actions/setup-node") || pin.includes("actions/upload-artifact")) && !freshnessWorkflow.includes(pin)) {
+      failures.push(`${freshnessPath}: missing immutable action pin ${pin}`);
+    }
+  }
+  failures.push(...workflowActionFailures(freshnessWorkflow, freshnessPath));
+  return failures;
+}

package/scripts/consumer-reference-case-runner.mjs

@@ -0,0 +1,93 @@
+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 { validateItemSchema } from "./consumer-reference-schema.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const validator = path.join(repositoryRoot, "scripts", "validate-consumer-reference.mjs");
+const itemPath = "consumer-reference/fixtures/item.json";
+
+function findingCodes(output) {
+  if (!Array.isArray(output.failures)) return [];
+  return output.failures.flatMap((failure) => {
+    if (typeof failure === "string") return [failure];
+    return typeof failure?.code === "string" ? [failure.code] : [];
+  });
+}
+
+function writeFixture(testCase, baseItem) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), `stylegallery-consumer-reference-${testCase.name}-`));
+  let externalRoot;
+  const item = Object.hasOwn(testCase, "value") ? structuredClone(testCase.value) : structuredClone(baseItem);
+  testCase.mutate?.(item);
+  const files = {
+    "CATALOG.md": "# Catalog\n",
+    [itemPath]: `${JSON.stringify(item, null, 2)}\n`,
+    "layout/index.md": testCase.layout ?? "# Layout\n",
+    "patterns/index.md": "# Patterns\n",
+    "quality/handoff.md": "Implementation handoff:\nConsumer reference: not_applicable\nConsumer reference reason: This fixture has no consumer-specific reference record.\n",
+    "scripts/pattern-data.mjs": testCase.patternData ?? "export const patterns = [];\n",
+    ...(testCase.extraFiles ?? {}),
+  };
+  for (const [relative, content] of Object.entries(files)) {
+    const target = path.join(root, relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+  }
+  if (testCase.link) {
+    const link = path.join(root, "consumer-reference", "fixtures", "redirect.json");
+    if (testCase.link === "inside") {
+      fs.symlinkSync(path.join(root, itemPath), link);
+    } else {
+      externalRoot = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-consumer-reference-outside-"));
+      const external = path.join(externalRoot, "record.json");
+      fs.writeFileSync(external, "{}\n");
+      fs.symlinkSync(external, link);
+    }
+  }
+  if (testCase.itemLink) {
+    const itemTarget = path.join(root, itemPath);
+    fs.rmSync(itemTarget);
+    if (testCase.itemLink === "inside") {
+      const actual = path.join(root, "consumer-reference", "fixtures", "actual-item.json");
+      fs.writeFileSync(actual, `${JSON.stringify(item, null, 2)}\n`);
+      fs.symlinkSync(actual, itemTarget);
+    } else {
+      externalRoot = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-consumer-reference-item-outside-"));
+      const external = path.join(externalRoot, "item.json");
+      fs.writeFileSync(external, `${JSON.stringify(item, null, 2)}\n`);
+      fs.symlinkSync(external, itemTarget);
+    }
+  }
+  return { externalRoot, item, root };
+}
+
+export function makeConsumerReferenceCaseRunner({ baseItem, schema }) {
+  return function runCase(testCase) {
+    const fixture = writeFixture(testCase, baseItem);
+    try {
+      const child = spawnSync(process.execPath, [validator, "--item", itemPath, "--json"], {
+        cwd: fixture.root,
+        encoding: "utf8",
+      });
+      const output = JSON.parse(child.stdout);
+      const codes = findingCodes(output);
+      const accepted = child.status === 0 && output.ok && output.scaffold !== true;
+      const rejected = child.status !== 0 && !output.ok && codes.includes(testCase.expect);
+      const schemaCodes = validateItemSchema(fixture.item, schema).map((finding) => finding.code);
+      const schemaParity = testCase.schemaValid === undefined || (schemaCodes.length === 0) === testCase.schemaValid;
+      return {
+        actual: { codes, ok: output.ok, scaffold: output.scaffold === true, schemaCodes, status: child.status },
+        expected: testCase.expect ?? "ok:true and exit:0",
+        name: testCase.name,
+        ok: (testCase.expect === null ? accepted : rejected) && schemaParity,
+        rules: testCase.rules ?? [],
+      };
+    } finally {
+      fs.rmSync(fixture.root, { force: true, recursive: true });
+      if (fixture.externalRoot) fs.rmSync(fixture.externalRoot, { force: true, recursive: true });
+    }
+  };
+}

package/scripts/consumer-reference-schema.mjs

@@ -0,0 +1,155 @@
+const fieldCodes = {
+  artifact_mode: "artifact_mode_invalid",
+  default: "profile_default_forbidden",
+  example_only: "profile_example_only_required",
+  fixture_independence: "fixture_independence_related",
+  id: "item_id_invalid",
+  layout_source_sha: "profile_layout_source_sha_required",
+  local_foundations: "profile_foundations_path_required",
+  maturity: "maturity_invalid",
+  profile_kind: "profile_kind_governed_local",
+  related_fixture_set_id: "profile_related_fixture_set_required",
+  removal_trigger: "removal_trigger_invalid",
+  replacement: "replacement_invalid",
+  review_independence: "review_independence_single_account",
+  schema_version: "schema_version_invalid",
+  tokens: "profile_tokens_path_required",
+};
+
+export function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function scalarMatches(value, definition) {
+  if (definition.type === "string" && typeof value !== "string") return false;
+  if (definition.minLength !== undefined && Array.from(value).length < definition.minLength) return false;
+  if (definition.pattern !== undefined && !new RegExp(definition.pattern).test(value)) return false;
+  if (definition.const !== undefined && value !== definition.const) return false;
+  return definition.enum === undefined || definition.enum.includes(value);
+}
+
+function unknownProperties(value, definitions) {
+  return Object.keys(value).filter((key) => !Object.hasOwn(definitions, key));
+}
+
+function missingProperties(value, required) {
+  return required.filter((key) => !Object.hasOwn(value, key));
+}
+
+function validateProfileObjects(item, schema, add) {
+  if (Object.hasOwn(item, "profile_kind")) {
+    const governed = schema.allOf.find((rule) => rule.if?.required?.includes("profile_kind"))?.then;
+    for (const property of governed?.required ?? []) if (!Object.hasOwn(item, property)) add("profile_field_required", `governed profile requires ${property}`);
+    for (const property of ["component_records", "evidence_records", "fixture_records", "generated_records", "state_records"]) {
+      if (!Object.hasOwn(item, property)) continue;
+      const value = item[property];
+      const definition = schema.properties[property];
+      const validItems = Array.isArray(value) && value.every((entry) => {
+        if (definition.items.const !== undefined) return entry === definition.items.const;
+        return definition.items.enum.includes(entry);
+      });
+      if (!Array.isArray(value) || value.length < definition.minItems || new Set(value).size !== value.length || !validItems) add("profile_reference_array_invalid", `${property} does not satisfy the governed profile schema`);
+    }
+  }
+  if (Object.hasOwn(item, "environment_assumptions")) {
+    const environment = item.environment_assumptions;
+    const definition = schema.properties.environment_assumptions;
+    if (!isPlainObject(environment)) {
+      add("profile_environment_object_required", "environment_assumptions must be an object");
+    } else {
+      for (const property of unknownProperties(environment, definition.properties)) add("profile_environment_property_unknown", `unknown environment assumption ${property}`);
+      if (!Object.hasOwn(environment, "user_agent_styles") || !scalarMatches(environment.user_agent_styles, definition.properties.user_agent_styles)) add("profile_ua_assumption_required", "user_agent_styles must be a non-empty string");
+      const reset = environment.reset;
+      if (!isPlainObject(reset)) {
+        add("profile_reset_assumptions_required", "reset assumptions must be an object");
+      } else {
+        for (const property of unknownProperties(reset, definition.properties.reset.properties)) add("profile_reset_property_unknown", `unknown reset assumption ${property}`);
+        for (const property of definition.properties.reset.required) {
+          if (!Object.hasOwn(reset, property) || !scalarMatches(reset[property], definition.properties.reset.properties[property])) add("profile_reset_assumptions_required", `reset requires ${property}`);
+        }
+      }
+    }
+  }
+  if (Object.hasOwn(item, "selection")) {
+    const selection = item.selection;
+    const definition = schema.properties.selection;
+    if (!isPlainObject(selection)) {
+      add("profile_selection_object_required", "selection must be an object");
+    } else {
+      for (const property of unknownProperties(selection, definition.properties)) add("profile_selection_property_unknown", `unknown selection property ${property}`);
+      for (const property of definition.required) {
+        if (!Object.hasOwn(selection, property) || !scalarMatches(selection[property], definition.properties[property])) add("profile_explicit_selection_required", `selection requires ${property}`);
+      }
+    }
+  }
+}
+
+export function validateItemSchema(item, schema) {
+  const findings = [];
+  const add = (code, message) => findings.push({ code, message });
+  if (!isPlainObject(item)) {
+    add("item_object_required", "item must be a JSON object");
+    return findings;
+  }
+
+  for (const property of unknownProperties(item, schema.properties)) {
+    add("item_property_unknown", `unknown item property ${property}`);
+  }
+  for (const property of missingProperties(item, schema.required)) {
+    add(property === "handoff" ? "handoff_required" : "item_field_required", `missing required field ${property}`);
+  }
+  for (const [property, code] of Object.entries(fieldCodes)) {
+    if (Object.hasOwn(item, property) && !scalarMatches(item[property], schema.properties[property])) {
+      add(code, `${property} does not satisfy the item schema`);
+    }
+  }
+
+  if (Object.hasOwn(item, "owner")) {
+    const definition = schema.properties.owner;
+    if (!isPlainObject(item.owner)) {
+      add("owner_object_required", "owner must be an object");
+    } else {
+      for (const property of unknownProperties(item.owner, definition.properties)) add("owner_property_unknown", `unknown owner property ${property}`);
+      for (const property of missingProperties(item.owner, definition.required)) add(property === "name" ? "owner_name_required" : "owner_enforcement_placeholder", `owner requires ${property}`);
+      if (Object.hasOwn(item.owner, "enforcement") && !scalarMatches(item.owner.enforcement, definition.properties.enforcement)) add("owner_enforcement_placeholder", "owner.enforcement must be placeholder");
+      if (Object.hasOwn(item.owner, "name") && !scalarMatches(item.owner.name, definition.properties.name)) add("owner_name_invalid", "owner.name must be a non-empty string");
+    }
+  }
+
+  if (Object.hasOwn(item, "support")) {
+    const definition = schema.properties.support;
+    if (!isPlainObject(item.support)) {
+      add("support_object_required", "support must be an object");
+    } else {
+      for (const property of unknownProperties(item.support, definition.properties)) add("support_property_unknown", `unknown support property ${property}`);
+      for (const property of missingProperties(item.support, definition.required)) add("support_status_required", `support requires ${property}`);
+      if (Object.hasOwn(item.support, "status") && !scalarMatches(item.support.status, definition.properties.status)) add("support_status_invalid", "support.status must be active or ended");
+    }
+  }
+
+  if (Object.hasOwn(item, "handoff")) {
+    if (!isPlainObject(item.handoff)) {
+      add("handoff_object_required", "handoff must be an object");
+    } else {
+      const variants = schema.properties.handoff.oneOf;
+      const definition = variants.find((candidate) => candidate.properties.status.const === item.handoff.status);
+      if (!definition) {
+        add("handoff_status_invalid", "handoff status must be declared or not_applicable");
+      } else {
+        for (const property of unknownProperties(item.handoff, definition.properties)) add("handoff_property_unknown", `unknown handoff property ${property}`);
+        for (const property of missingProperties(item.handoff, definition.required)) add(property === "record" ? "record_required" : "not_applicable_reason_sentence", `handoff requires ${property}`);
+        if (definition.properties.record && Object.hasOwn(item.handoff, "record") && !scalarMatches(item.handoff.record, definition.properties.record)) add("record_schema_invalid", "record does not satisfy the schema path pattern");
+        if (definition.properties.reason && Object.hasOwn(item.handoff, "reason") && !scalarMatches(item.handoff.reason, definition.properties.reason)) add("not_applicable_reason_sentence", "not_applicable requires the schema sentence rule");
+      }
+    }
+  }
+
+  validateProfileObjects(item, schema, add);
+
+  if (item.maturity === "stable" && item.support?.status === "ended") add("stable_support_ended", "stable maturity cannot have ended support");
+  if (item.maturity === "deprecated") {
+    if (!Object.hasOwn(item, "replacement") || !Object.hasOwn(item, "removal_trigger")) add("deprecated_migration_required", "deprecated items require replacement and removal_trigger");
+  }
+  if (typeof item.review_independence === "boolean") add("review_independence_boolean", "review_independence does not accept boolean aliases");
+  return findings;
+}

package/scripts/create-component-state-session.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+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 { chromium } from "playwright";
+import {
+  canonicalIntended,
+  canonicalSourceManifest,
+  dirtyRelevantSources,
+  repositoryGitArgs,
+  sha256,
+} from "./capture-session-contract.mjs";
+import { compileSchemas } from "./component-state-contract.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const options = {
+  json: false,
+  output: undefined,
+  profileRoot: path.join(repositoryRoot, "design-engineering/reference-profiles/governed-local"),
+};
+const failures = [];
+
+for (let index = 2; index < process.argv.length; index += 1) {
+  const argument = process.argv[index];
+  if (argument === "--json") options.json = true;
+  else if (["--output", "--root"].includes(argument)) {
+    const value = process.argv[index + 1];
+    if (!value) failures.push({ code: "argument_value_required", message: `${argument} requires a value`, path: "<cli>" });
+    else {
+      if (argument === "--output") options.output = path.resolve(value);
+      if (argument === "--root") options.profileRoot = path.resolve(value);
+      index += 1;
+    }
+  } else failures.push({ code: "argument_unknown", message: `unsupported argument ${argument}`, path: "<cli>" });
+}
+
+if (!options.output) failures.push({ code: "argument_value_required", message: "--output is required", path: "<cli>" });
+else if (path.basename(options.output) !== "capture-session.json") failures.push({ code: "capture_session_path_invalid", message: "receipt filename must be capture-session.json", path: options.output });
+else if (fs.existsSync(options.output)) failures.push({ code: "capture_session_replay", message: "capture session receipt already exists and cannot be overwritten", path: options.output });
+
+function git(...args) {
+  return execFileSync("git", repositoryGitArgs(repositoryRoot, ...args), { cwd: repositoryRoot, encoding: "utf8" }).trim();
+}
+
+const executable = chromium.executablePath();
+const revisionSegment = executable.split(path.sep).find((segment) => /^chromium(?:_headless_shell)?-\d+$/.test(segment));
+const packageJson = JSON.parse(fs.readFileSync(path.join(repositoryRoot, "package.json"), "utf8"));
+const intended = canonicalIntended(options.profileRoot, failures);
+const revision = git("rev-parse", "HEAD");
+if (process.env.GITHUB_SHA && process.env.GITHUB_SHA !== revision) failures.push({ code: "capture_revision_mismatch", message: `GITHUB_SHA ${process.env.GITHUB_SHA} does not match checked-out HEAD ${revision}`, path: repositoryRoot });
+let source;
+try {
+  source = canonicalSourceManifest(repositoryRoot, options.profileRoot);
+  const dirty = dirtyRelevantSources(repositoryRoot, options.profileRoot);
+  if (dirty.length > 0) failures.push({ code: "capture_source_dirty", message: `relevant capture sources must be committed: ${dirty.join(", ")}`, path: repositoryRoot });
+} catch (error) {
+  failures.push({ code: "capture_source_unreadable", message: error instanceof Error ? error.message : String(error), path: options.profileRoot });
+}
+const receipt = {
+  attempt: Number(process.env.GITHUB_RUN_ATTEMPT ?? 1),
+  branch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || git("branch", "--show-current") || "detached",
+  environment: {
+    browser: execFileSync(executable, ["--version"], { encoding: "utf8" }).trim(),
+    browser_revision: revisionSegment ?? path.basename(executable),
+    container_image: process.env.SENTINEL_CONTAINER_IMAGE ?? `local-host:${os.release()}`,
+    kind: "browser",
+    lockfile_sha256: sha256(fs.readFileSync(path.join(repositoryRoot, "package-lock.json"))),
+    node: process.version,
+    platform: process.platform === "linux" && process.arch === "x64" ? "linux/amd64" : `${process.platform}/${process.arch}`,
+    playwright: packageJson.devDependencies["@playwright/test"],
+    viewport: "1024x768",
+  },
+  intended,
+  nonce: crypto.randomBytes(32).toString("hex"),
+  record_kind: "component_state_capture_session",
+  repository: process.env.GITHUB_REPOSITORY ?? "changeroa/StyleGallery",
+  revision,
+  schema_version: "1.0",
+  session_id: crypto.randomUUID(),
+  source,
+  started_at: new Date().toISOString(),
+};
+
+const schemas = compileSchemas(path.join(repositoryRoot, "consumer-reference/schema"));
+if (!schemas.capture(receipt)) {
+  for (const error of schemas.capture.errors ?? []) failures.push({ code: "capture_session_schema_invalid", message: `${error.instancePath || "/"} ${error.message}`, path: options.output ?? "<cli>" });
+}
+if (failures.length === 0) {
+  fs.mkdirSync(path.dirname(options.output), { recursive: true });
+  fs.writeFileSync(options.output, `${JSON.stringify(receipt, null, 2)}\n`);
+}
+const result = { failures, intendedArtifacts: intended.reduce((sum, profile) => sum + profile.scenarios.reduce((count, scenario) => count + scenario.channels.length, 0), 0), ok: failures.length === 0, receipt: options.output };
+if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+else if (result.ok) process.stdout.write(`created component-state capture session ${receipt.session_id}\n`);
+else process.stderr.write(`${failures.map((failure) => `${failure.code}: ${failure.path}: ${failure.message}`).join("\n")}\n`);
+if (!result.ok) process.exitCode = 1;