@qontinui/shared-types 0.2.5 → 0.3.0

package/src/generated/index.ts

@@ -27,6 +27,11 @@ export type { ApiAssertionType } from './ApiAssertionType';
 export type { ApiContentType } from './ApiContentType';
 export type { ApiVariableExtraction } from './ApiVariableExtraction';
 export type { AppEvent } from './AppEvent';
+export type { AssertionMiss } from './AssertionMiss';
+export type { AssertionOutcome } from './AssertionOutcome';
+export type { AssertionResult } from './AssertionResult';
+export type { AssertionScope } from './AssertionScope';
+export type { AssertionSeverityCounts } from './AssertionSeverityCounts';
 export type { AvailableTransitionsResult } from './AvailableTransitionsResult';
 export type { BaseStepFields } from './BaseStepFields';
 export type { BatchComputeEmbeddingRequest } from './BatchComputeEmbeddingRequest';
@@ -34,8 +39,10 @@ export type { BatchComputeEmbeddingResponse } from './BatchComputeEmbeddingRespo
 export type { BatchEmbeddingResult } from './BatchEmbeddingResult';
 export type { BetweenIterations } from './BetweenIterations';
 export type { BoundingBox } from './BoundingBox';
+export type { BridgeFingerprint } from './BridgeFingerprint';
 export type { BuildPhaseConfig } from './BuildPhaseConfig';
 export type { BuiltinOverrideProposal } from './BuiltinOverrideProposal';
+export type { CandidateMiss } from './CandidateMiss';
 export type { CanonicalStep } from './CanonicalStep';
 export type { CanvasPanel } from './CanvasPanel';
 export type { CatchUpPolicy } from './CatchUpPolicy';
@@ -56,6 +63,8 @@ export type { ConditionScheduleConfig } from './ConditionScheduleConfig';
 export type { ConditionStatus } from './ConditionStatus';
 export type { Confidence } from './Confidence';
 export type { ConfidenceLevel } from './ConfidenceLevel';
+export type { ConjunctEvaluation } from './ConjunctEvaluation';
+export type { ConjunctRule } from './ConjunctRule';
 export type { Constraint } from './Constraint';
 export type { ConstraintCheck } from './ConstraintCheck';
 export type { ConstraintProposal } from './ConstraintProposal';
@@ -137,6 +146,7 @@ export type { ExitCheckResult } from './ExitCheckResult';
 export type { ExitStrategy } from './ExitStrategy';
 export type { ExportResult } from './ExportResult';
 export type { ExtendIterationsRequest } from './ExtendIterationsRequest';
+export type { FieldDiff } from './FieldDiff';
 export type { FileChange } from './FileChange';
 export type { Finding } from './Finding';
 export type { FindingActionType } from './FindingActionType';
@@ -167,6 +177,19 @@ export type { ImplementFixesConfig } from './ImplementFixesConfig';
 export type { IndividualCheckResult } from './IndividualCheckResult';
 export type { InitialStateRef } from './InitialStateRef';
 export type { InitialStatesSource } from './InitialStatesSource';
+export type { IrAssertion } from './IrAssertion';
+export type { IrAssertionTarget } from './IrAssertionTarget';
+export type { IrCrossRef } from './IrCrossRef';
+export type { IrElementCriteria } from './IrElementCriteria';
+export type { IrGroup } from './IrGroup';
+export type { IrMetadata } from './IrMetadata';
+export type { IrPageSpec } from './IrPageSpec';
+export type { IrProvenance } from './IrProvenance';
+export type { IrState } from './IrState';
+export type { IrStateCondition } from './IrStateCondition';
+export type { IrTransition } from './IrTransition';
+export type { IrTransitionAction } from './IrTransitionAction';
+export type { IrWaitSpec } from './IrWaitSpec';
 export type { IssueSeverity } from './IssueSeverity';
 export type { IssueSource } from './IssueSource';
 export type { IssueStatus } from './IssueStatus';
@@ -179,12 +202,22 @@ export type { JobStatus } from './JobStatus';
 export type { JobSummary } from './JobSummary';
 export type { LLMCostSummary } from './LLMCostSummary';
 export type { LLMMetrics } from './LLMMetrics';
+export type { LegacyAssertion } from './LegacyAssertion';
+export type { LegacyAssertionTarget } from './LegacyAssertionTarget';
+export type { LegacyGroup } from './LegacyGroup';
+export type { LegacyProcessStep } from './LegacyProcessStep';
+export type { LegacySpec } from './LegacySpec';
+export type { LegacyStateMachine } from './LegacyStateMachine';
+export type { LegacyStateMachineState } from './LegacyStateMachineState';
+export type { LegacyTransition } from './LegacyTransition';
 export type { LogSourceSelection } from './LogSourceSelection';
 export type { LoopInstanceStatus } from './LoopInstanceStatus';
 export type { LoopPhase } from './LoopPhase';
 export type { MatchAdjustment } from './MatchAdjustment';
 export type { MatchLocation } from './MatchLocation';
 export type { MatchMethod } from './MatchMethod';
+export type { MatchOutcome } from './MatchOutcome';
+export type { MatchedElement } from './MatchedElement';
 export type { McpCallRecord } from './McpCallRecord';
 export type { McpCallsResult } from './McpCallsResult';
 export type { McpConnectionRef } from './McpConnectionRef';
@@ -194,6 +227,7 @@ export type { McpToolCallResult } from './McpToolCallResult';
 export type { McpToolInfo } from './McpToolInfo';
 export type { McpToolInputSchema } from './McpToolInputSchema';
 export type { McpTransport } from './McpTransport';
+export type { MissReason } from './MissReason';
 export type { ModelCostBreakdown } from './ModelCostBreakdown';
 export type { ModelOverrideConfig } from './ModelOverrideConfig';
 export type { Monitor } from './Monitor';
@@ -228,18 +262,23 @@ export type { PipelineConfig } from './PipelineConfig';
 export type { PlaybackFrameRequest } from './PlaybackFrameRequest';
 export type { PlaywrightExecutionMode } from './PlaywrightExecutionMode';
 export type { Point } from './Point';
+export type { PolicyConjunct } from './PolicyConjunct';
+export type { PolicyEvaluation } from './PolicyEvaluation';
+export type { PolicyStatus } from './PolicyStatus';
 export type { PollingConfig } from './PollingConfig';
 export type { ProcessConfig } from './ProcessConfig';
 export type { ProcessState } from './ProcessState';
 export type { ProcessStatus } from './ProcessStatus';
 export type { PromptStep } from './PromptStep';
 export type { PromptStepPhase } from './PromptStepPhase';
+export type { ProposalStatus } from './ProposalStatus';
 export type { RAGDashboardStats } from './RAGDashboardStats';
 export type { RagCompletionEvent } from './RagCompletionEvent';
 export type { RagProcessingStatus } from './RagProcessingStatus';
 export type { RagProgressEvent } from './RagProgressEvent';
 export type { ReadConfigResponse } from './ReadConfigResponse';
 export type { RecommendationReviewDecisionPayload } from './RecommendationReviewDecisionPayload';
+export type { RecommendedState } from './RecommendedState';
 export type { ReflectionFixOutput } from './ReflectionFixOutput';
 export type { Region } from './Region';
 export type { RepositoryInactiveCondition } from './RepositoryInactiveCondition';
@@ -287,6 +326,12 @@ export type { SearchResultItem } from './SearchResultItem';
 export type { SearchStrategy } from './SearchStrategy';
 export type { SemanticSearchRequest } from './SemanticSearchRequest';
 export type { SemanticSearchResponse } from './SemanticSearchResponse';
+export type { SpecCheckConfidence } from './SpecCheckConfidence';
+export type { SpecCheckPolicy } from './SpecCheckPolicy';
+export type { SpecCheckResult } from './SpecCheckResult';
+export type { SpecCheckStepConfig } from './SpecCheckStepConfig';
+export type { SpecCheckSummary } from './SpecCheckSummary';
+export type { SpecValidation } from './SpecValidation';
 export type { StageCondition } from './StageCondition';
 export type { StageInput } from './StageInput';
 export type { StageOutput } from './StageOutput';
@@ -313,6 +358,7 @@ export type { StateMachineStateUpdate } from './StateMachineStateUpdate';
 export type { StateMachineTransition } from './StateMachineTransition';
 export type { StateMachineTransitionCreate } from './StateMachineTransitionCreate';
 export type { StateMachineTransitionUpdate } from './StateMachineTransitionUpdate';
+export type { StateMatchResult } from './StateMatchResult';
 export type { StateNodeData } from './StateNodeData';
 export type { StatesResponse } from './StatesResponse';
 export type { StdioConfig } from './StdioConfig';

package/src/index.ts

@@ -7,6 +7,11 @@
 // Render logging types
 export * from "./render-log";
 
+// Spec-check distinctness validation (Plan 04). Surfaced from the
+// auto-generated Rust mirror — see qontinui-schemas/rust/src/spec_check.rs.
+export type { SpecValidation } from "./generated/SpecValidation";
+export type { ProposalStatus } from "./generated/ProposalStatus";
+
 // State discovery types
 export * from "./discovery";
 

package/src/ui-bridge-ir/__tests__/projection.test.ts

@@ -13,6 +13,8 @@
 import { describe, expect, it } from "vitest";
 
 import type { IRDocument } from "../document";
+import type { IRElementCriteria } from "../element-criteria";
+import type { IRAssertion } from "../group";
 import {
   projectIRToBundledPage,
   projectLegacyToIR,
@@ -24,6 +26,74 @@ import {
 // Fixtures
 // ---------------------------------------------------------------------------
 
+/**
+ * Convert IR-shaped element criteria into the legacy criteria record stored on
+ * `IRAssertion.target.criteria`. Mirrors `projection.ts:convertCriteria`'s
+ * rename map (text -> textContent, ariaLabel -> accessibleName when no
+ * accessibleName is set, attributes -> dataAttributes). The forward projection
+ * passes `target.criteria` through verbatim into the legacy group output, so
+ * fixtures store criteria in their legacy on-disk shape.
+ */
+function toLegacyCriteria(c: IRElementCriteria): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (c.role !== undefined) out.role = c.role;
+  if (c.tagName !== undefined) out.tagName = c.tagName;
+  if (c.text !== undefined) out.textContent = c.text;
+  if (c.textContains !== undefined) out.textContains = c.textContains;
+  if (c.accessibleName !== undefined) {
+    out.accessibleName = c.accessibleName;
+  } else if (c.ariaLabel !== undefined) {
+    out.accessibleName = c.ariaLabel;
+  }
+  if (c.id !== undefined) out.id = c.id;
+  if (c.attributes !== undefined) out.dataAttributes = c.attributes;
+  return out;
+}
+
+/**
+ * Build the canonical IR-side assertion list for a state from a flat array of
+ * IR element criteria. Mirrors the shape the projection emits for state-derived
+ * groups so the fixtures stay terse — one criteria per assertion, with all the
+ * legacy required fields (id/category/severity/...) defaulted the same way the
+ * forward projection used to defaulted them when synthesizing assertions from
+ * `requiredElements`. Criteria are stored in legacy on-disk form (`textContent`,
+ * `accessibleName`, `dataAttributes`) because `IRAssertion.target.criteria` is
+ * already the legacy criteria record — the forward projection passes it through
+ * verbatim into `group.assertions[].target.criteria`.
+ */
+function assertionsFromCriteria(
+  stateId: string,
+  stateName: string,
+  criteria: IRElementCriteria[],
+): IRAssertion[] {
+  return criteria.map((c, index) => ({
+    id: `${stateId}-elem-${index}`,
+    description: `Required element ${index} for state ${stateName}`,
+    category: "element-presence",
+    severity: "critical",
+    assertionType: "exists",
+    target: {
+      type: "search",
+      criteria: toLegacyCriteria(c),
+      label: `Required element for ${stateName}`,
+    },
+    source: "ai-generated",
+    reviewed: false,
+    enabled: true,
+  }));
+}
+
+/**
+ * Pluck the legacy-criteria record off an assertion produced by the inverse
+ * projection. The IR side stores criteria in IR form post-inversion (the
+ * projection's `invertCriteria` renames `textContent -> text`,
+ * `dataAttributes -> attributes`), so the returned object is shaped like
+ * `IRElementCriteria`.
+ */
+function criteriaOf(assertion: IRAssertion): IRElementCriteria {
+  return assertion.target.criteria as unknown as IRElementCriteria;
+}
+
 /**
  * Slice of `qontinui-runner/src/specs/active.spec.uibridge.json` mapped back
  * to IR. Three to four states, transitions between them, a few criteria
@@ -44,21 +114,27 @@ const ACTIVE_PAGE_FIXTURE: IRDocument = {
       id: "idle",
       name: "Idle",
       description: "No workflow is running.",
-      requiredElements: [{ text: "No Active Workflow" }],
+      assertions: assertionsFromCriteria("idle", "Idle", [
+        { text: "No Active Workflow" },
+      ]),
       isInitial: true,
     },
     {
       id: "running",
       name: "Running",
       description: "A workflow is actively executing.",
-      requiredElements: [{ role: "button", text: "Stop" }],
+      assertions: assertionsFromCriteria("running", "Running", [
+        { role: "button", text: "Stop" },
+      ]),
       isInitial: false,
     },
     {
       id: "paused",
       name: "Paused",
       description: "The workflow is temporarily paused.",
-      requiredElements: [{ role: "button", ariaLabel: "Play" }],
+      assertions: assertionsFromCriteria("paused", "Paused", [
+        { role: "button", ariaLabel: "Play" },
+      ]),
       isInitial: false,
     },
     {
@@ -66,10 +142,10 @@ const ACTIVE_PAGE_FIXTURE: IRDocument = {
       name: "Breakpoint Paused",
       description:
         "A workflow step with breakpoint: true has completed; execution is suspended.",
-      requiredElements: [
+      assertions: assertionsFromCriteria("breakpoint-paused", "Breakpoint Paused", [
         { text: "Breakpoint" },
         { attributes: { "content-label": "breakpoint step" } },
-      ],
+      ]),
       isInitial: false,
     },
   ],
@@ -268,12 +344,12 @@ describe("projectIRToBundledPage — round-trip against active.spec", () => {
         {
           id: "first",
           name: "First",
-          requiredElements: [{ role: "heading" }],
+          assertions: assertionsFromCriteria("first", "First", [{ role: "heading" }]),
         },
         {
           id: "second",
           name: "Second",
-          requiredElements: [{ role: "button" }],
+          assertions: assertionsFromCriteria("second", "Second", [{ role: "button" }]),
         },
       ],
       transitions: [],
@@ -388,7 +464,7 @@ describe("projectIRToBundledPage — empty cases", () => {
         {
           id: "no-req",
           name: "No Required Elements",
-          requiredElements: [],
+          assertions: [],
         },
       ],
       transitions: [],
@@ -499,7 +575,7 @@ describe("projectIRToBundledPage — empty cases", () => {
         {
           id: "empty-text",
           name: "Empty Text",
-          requiredElements: [{ text: "" }],
+          assertions: assertionsFromCriteria("empty-text", "Empty Text", [{ text: "" }]),
         },
       ],
       transitions: [],
@@ -515,8 +591,16 @@ describe("projectIRToBundledPage — empty cases", () => {
       id: "p",
       name: "P",
       states: [
-        { id: "a", name: "A", requiredElements: [{ role: "heading" }] },
-        { id: "b", name: "B", requiredElements: [{ role: "heading" }] },
+        {
+          id: "a",
+          name: "A",
+          assertions: assertionsFromCriteria("a", "A", [{ role: "heading" }]),
+        },
+        {
+          id: "b",
+          name: "B",
+          assertions: assertionsFromCriteria("b", "B", [{ role: "heading" }]),
+        },
       ],
       transitions: [
         {
@@ -541,8 +625,16 @@ describe("projectIRToBundledPage — empty cases", () => {
       id: "p",
       name: "P",
       states: [
-        { id: "base", name: "Base", requiredElements: [{ role: "heading" }] },
-        { id: "modal", name: "Modal", requiredElements: [{ role: "dialog" }] },
+        {
+          id: "base",
+          name: "Base",
+          assertions: assertionsFromCriteria("base", "Base", [{ role: "heading" }]),
+        },
+        {
+          id: "modal",
+          name: "Modal",
+          assertions: assertionsFromCriteria("modal", "Modal", [{ role: "dialog" }]),
+        },
       ],
       transitions: [
         {
@@ -576,7 +668,7 @@ describe("projectIRToBundledPage — provenance + state metadata", () => {
         {
           id: "s",
           name: "S",
-          requiredElements: [{ role: "heading" }],
+          assertions: assertionsFromCriteria("s", "S", [{ role: "heading" }]),
           provenance: { source: "hand-authored", file: "p.tsx" },
         },
       ],
@@ -595,7 +687,7 @@ describe("projectIRToBundledPage — provenance + state metadata", () => {
         {
           id: "s",
           name: "S",
-          requiredElements: [{ role: "heading" }],
+          assertions: assertionsFromCriteria("s", "S", [{ role: "heading" }]),
         },
       ],
       transitions: [],
@@ -613,7 +705,7 @@ describe("projectIRToBundledPage — provenance + state metadata", () => {
         {
           id: "s",
           name: "S",
-          requiredElements: [{ role: "heading" }],
+          assertions: assertionsFromCriteria("s", "S", [{ role: "heading" }]),
           metadata: { description: "From metadata" },
         },
       ],
@@ -632,7 +724,7 @@ describe("projectIRToBundledPage — provenance + state metadata", () => {
         {
           id: "s",
           name: "S",
-          requiredElements: [{ role: "heading" }],
+          assertions: assertionsFromCriteria("s", "S", [{ role: "heading" }]),
         },
       ],
       transitions: [],
@@ -834,21 +926,21 @@ describe("projectLegacyToIR — basic shape", () => {
     expect(alpha.description).toBe("First group for the round-trip test.");
   });
 
-  it("sources requiredElements from group.assertions[].target.criteria", () => {
+  it("sources state.assertions[].target.criteria from group.assertions[].target.criteria (inverted)", () => {
     const ir = projectLegacyToIR(LEGACY_FIXTURE);
     const alpha = ir.states.find((s) => s.id === "alpha")!;
-    expect(alpha.requiredElements).toHaveLength(2);
-    expect(alpha.requiredElements[0]).toEqual({
+    expect(alpha.assertions).toHaveLength(2);
+    expect(criteriaOf(alpha.assertions[0]!)).toEqual({
       role: "heading",
       text: "Alpha",
     });
-    expect(alpha.requiredElements[1]).toEqual({ text: "Welcome" });
+    expect(criteriaOf(alpha.assertions[1]!)).toEqual({ text: "Welcome" });
   });
 
   it("inverts dataAttributes -> attributes and accessibleName passthrough", () => {
     const ir = projectLegacyToIR(LEGACY_FIXTURE);
     const beta = ir.states.find((s) => s.id === "beta")!;
-    expect(beta.requiredElements[0]).toEqual({
+    expect(criteriaOf(beta.assertions[0]!)).toEqual({
       role: "dialog",
       accessibleName: "Confirm",
     });

package/src/ui-bridge-ir/adapter.ts

@@ -114,10 +114,16 @@ const SUPPORTED_IR_VERSIONS = new Set<string>(["1.0"]);
  * incomingTransitions, crossRefs, visualRefs).
  */
 export function adaptIRState(state: IRState): AdaptedState {
+  // Project rich IR assertions down to the runtime's flat element-criteria
+  // list. The runtime engine (ui-bridge-auto's WorkflowConfig.StateConfig)
+  // doesn't carry per-element severity/category — those metadata fields stay
+  // IR-side, consumed by Spec-Check policies.
   const out: AdaptedState = {
     id: state.id,
     name: state.name,
-    requiredElements: state.requiredElements,
+    requiredElements: state.assertions.map(
+      (a) => a.target.criteria as unknown as IRElementCriteria,
+    ),
   };
   if (state.description !== undefined) out.description = state.description;
   if (state.excludedElements !== undefined) out.excludedElements = state.excludedElements;

package/src/ui-bridge-ir/ir.schema.json

@@ -95,7 +95,11 @@
         "file": { "type": "string" },
         "line": { "type": "integer", "minimum": 1 },
         "column": { "type": "integer", "minimum": 1 },
-        "pluginVersion": { "type": "string" }
+        "pluginVersion": { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": ["proposed", "pending", "promoted"]
+        }
       }
     },
     "IRCrossRef": {
@@ -146,15 +150,15 @@
     },
     "IRState": {
       "type": "object",
-      "required": ["id", "name", "requiredElements"],
+      "required": ["id", "name", "assertions"],
       "additionalProperties": false,
       "properties": {
         "id": { "type": "string" },
         "name": { "type": "string" },
         "description": { "type": "string" },
-        "requiredElements": {
+        "assertions": {
           "type": "array",
-          "items": { "$ref": "#/$defs/IRElementCriteria" }
+          "items": { "$ref": "#/$defs/IRAssertion" }
         },
         "excludedElements": {
           "type": "array",

package/src/ui-bridge-ir/primitives.ts

@@ -27,6 +27,14 @@ export interface IRProvenance {
   column?: number;
   /** Build-plugin version that produced this node, if applicable. */
   pluginVersion?: string;
+  /**
+   * Lifecycle status for the Stream E coverage-growth flywheel. Absent =
+   * implicitly `"promoted"` (legacy + on-disk specs that predate the field).
+   * Set to `"proposed"` by `spec_authoring`, `"pending"` when staged in
+   * `_pending/`, `"promoted"` after the 2-green sweep moves the file to
+   * `pages/<id>/`.
+   */
+  status?: "proposed" | "pending" | "promoted";
 }
 
 // ---------------------------------------------------------------------------

package/src/ui-bridge-ir/projection.ts

@@ -371,58 +371,13 @@ function convertCriteria(criteria: IRElementCriteria): LegacyCriteria {
 }
 
 /**
- * Build a single legacy assertion from a state + index + criteria.
- *
- * Always produces one assertion per requiredElement; the caller is responsible
- * for iterating `state.requiredElements`. Empty `requiredElements` produces an
- * empty `assertions[]` — legitimate legacy specs (e.g. architecture-only
- * groups in `graphql-infrastructure`, `activity-timeline`, `opik-integration`,
- * `watchers`) ship with empty `assertions[]`, and the inverse projection
- * round-trip must preserve that emptiness or `check-spec-pairing` flags an
- * assertion-count drift.
- */
-function buildAssertion(
-  state: IRState,
-  index: number,
-  criteria: IRElementCriteria,
-): LegacyAssertion {
-  const description =
-    state.metadata?.description ?? `Required element ${index} for state ${state.name}`;
-  const targetCriteria: LegacyCriteria = convertCriteria(criteria);
-  const assertion: LegacyAssertion = {
-    id: `${state.id}-elem-${index}`,
-    description,
-    category: "element-presence",
-    severity: "critical",
-    assertionType: "exists",
-    target: {
-      type: "search",
-      criteria: targetCriteria,
-      label: `Required element for ${state.name}`,
-    },
-    source: "ai-generated",
-    reviewed: false,
-    enabled: true,
-  };
-  if (state.precondition !== undefined) {
-    assertion.precondition = state.precondition;
-  }
-  return assertion;
-}
-
-/**
- * Build the legacy `groups[]` entry for one IR state. Emits exactly one
- * assertion per `requiredElement`; states with zero requiredElements project
- * to a group with an empty `assertions[]` array. Legacy consumers (runner
- * spec drift / verify, error monitor curator, AI session) tolerate empty
- * groups — multiple shipping legacy specs already use them for
- * architecture-only / documentation-only groups.
+ * Build the legacy `groups[]` entry for one IR state. With IrState.assertions
+ * carrying first-class assertion metadata (id/description/severity/category/
+ * target), this is now a direct shape-conversion per assertion — no more
+ * synthesizing IDs or defaulting severity.
  */
 function buildGroup(state: IRState): LegacyGroup {
-  const elems = state.requiredElements ?? [];
-  const assertions: LegacyAssertion[] = elems.map((c, i) =>
-    buildAssertion(state, i, c),
-  );
+  const assertions: LegacyAssertion[] = state.assertions.map(synthesizedAssertionToLegacy);
   return {
     id: state.id,
     name: state.name,
@@ -535,7 +490,10 @@ function buildStateMachineState(
     id: state.id,
     name: state.name,
     description: state.description ?? "",
-    elements: (state.requiredElements ?? []).map(convertCriteria),
+    // Project legacy `elements[]` from each assertion's target.criteria.
+    elements: state.assertions.map((a) =>
+      convertCriteria(a.target.criteria as IRElementCriteria),
+    ),
     isInitial,
     transitions: outgoing,
   };
@@ -680,11 +638,30 @@ function buildIRState(
   group: LegacyGroup,
   smState: LegacyStateMachineState | undefined,
 ): IRState {
-  // Always one requiredElement per assertion so the forward projection emits
-  // the same number of assertions on the round-trip.
-  const requiredElements: IRElementCriteria[] = group.assertions.map((a) =>
-    invertCriteria(a.target?.criteria),
-  );
+  // Map each LegacyAssertion to an IRAssertion, preserving id/description/
+  // severity/category. target.criteria is normalized via invertCriteria so
+  // the criteria shape matches what the IR side stores.
+  const assertions: IRAssertion[] = group.assertions.map((a) => {
+    const ir: IRAssertion = {
+      id: a.id,
+      description: a.description,
+      category: a.category,
+      severity: a.severity,
+      assertionType: a.assertionType,
+      target: {
+        type: "search",
+        criteria: invertCriteria(a.target?.criteria) as unknown as Record<string, unknown>,
+        label: a.target?.label ?? a.description,
+      },
+      source: a.source,
+      reviewed: a.reviewed,
+      enabled: a.enabled,
+    };
+    if (a.precondition !== undefined) {
+      ir.precondition = a.precondition;
+    }
+    return ir;
+  });
 
   const description =
     group.description !== undefined && group.description.length > 0
@@ -695,7 +672,7 @@ function buildIRState(
   const state: IRState = {
     id: group.id,
     name: smState?.name ?? group.name,
-    requiredElements,
+    assertions,
   };
   if (description !== undefined && description.length > 0) {
     state.description = description;

package/src/ui-bridge-ir/state.ts

@@ -7,6 +7,7 @@
  */
 
 import type { IRElementCriteria } from "./element-criteria";
+import type { IRAssertion } from "./group";
 import type { IRCrossRef, IRMetadata, IRProvenance, IRVisualRef } from "./primitives";
 
 /**
@@ -42,8 +43,14 @@ export interface IRState {
   description?: string;
 
   // Predicates (canonical) -----------------------------------------------
-  /** Element criteria that must ALL be satisfied for this state to be active. */
-  requiredElements: IRElementCriteria[];
+  /**
+   * State-scoped assertions. Each carries its own assertion_id, description,
+   * severity, category, and an IrElementCriteria target via target.criteria.
+   * Spec-Check (Plan 02) evaluates these against UI Bridge snapshots; policy
+   * filtering via `severity`/`category` is meaningful because each assertion
+   * carries its own metadata (no synthesized stubs).
+   */
+  assertions: IRAssertion[];
   /** Element criteria where NONE may be satisfied (any match disqualifies). */
   excludedElements?: IRElementCriteria[];
   /** Additional property checks on matched elements. */