uidex 0.10.0 → 0.11.0

package/dist/scan/index.cjs

@@ -55,13 +55,9 @@ __export(scan_exports, {
   extractUidexExports: () => extractUidexExports,
   findWorkspaceRoot: () => findWorkspaceRoot,
   globToRegExp: () => globToRegExp,
-  isLegacyBaseline: () => isLegacyBaseline,
   loadCoverageBaseline: () => loadCoverageBaseline,
   matchUrlToRoute: () => matchUrlToRoute,
   mergeStates: () => mergeStates,
-  migrateBaseline: () => migrateBaseline,
-  migrateLegacyBaseline: () => migrateLegacyBaseline,
-  migrateLegacyFields: () => migrateLegacyFields,
   parseConfig: () => parseConfig,
   parseCoverageBaseline: () => parseCoverageBaseline,
   pathToId: () => pathToId,
@@ -110,6 +106,7 @@ var ALLOWED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "exclude",
   "output",
   "flows",
+  "resolve",
   "audit",
   "conventions",
   "statesManifest",
@@ -128,24 +125,32 @@ var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set([
   "scopeLeak",
   "coverage",
   "acceptance",
+  "surfaces",
+  "requireAcceptance",
   "states",
   "pageCoverage",
   "stateMatrix",
   "severity"
 ]);
 var DIAGNOSTIC_CODES = [
+  "acceptance-ambiguous",
+  "acceptance-duplicate-id",
+  "acceptance-orphaned",
+  "acceptance-outdated",
   "acceptance-uncovered",
   "acknowledged-elsewhere",
   "competing-uidex-export",
   "component-state-uncaptured",
   "core-kind",
+  "covers-missing-rev",
   "duplicate-id",
   "dynamic-attr",
   "dynamic-flow-reference",
+  "feature-missing-acceptance",
+  "feature-surface-uncaptured",
+  "feature-surface-unreferenced",
   "gen-missing",
   "gen-stale",
-  "legacy-acknowledge-field",
-  "legacy-coverage-baseline",
   "matrix-backlog",
   "missing-element-annotation",
   "missing-state-capture",
@@ -180,14 +185,14 @@ var SEVERITY_LEVELS = /* @__PURE__ */ new Set(["error", "warning", "info", "off"
 function fail(msg) {
   throw new ConfigError(`Invalid .uidex.json: ${msg}`);
 }
-function assertObject(value, path13) {
+function assertObject(value, path14) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    fail(`${path13} must be an object`);
+    fail(`${path14} must be an object`);
   }
 }
-function assertStringArray(value, path13) {
+function assertStringArray(value, path14) {
   if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
-    fail(`${path13} must be a string[]`);
+    fail(`${path14} must be a string[]`);
   }
 }
 function validateConfig(raw) {
@@ -244,6 +249,23 @@ function validateConfig(raw) {
   if (raw.workspace !== void 0 && raw.workspace !== false && typeof raw.workspace !== "string") {
     fail(`"workspace" must be a path string or false`);
   }
+  if (raw.resolve !== void 0) {
+    assertObject(raw.resolve, "resolve");
+    for (const key of Object.keys(raw.resolve)) {
+      if (key !== "aliases") fail(`unknown key "${key}" in resolve`);
+    }
+    const aliases = raw.resolve.aliases;
+    if (aliases === void 0) {
+      fail(`resolve.aliases is required when "resolve" is present`);
+    }
+    assertObject(aliases, "resolve.aliases");
+    for (const [alias, target] of Object.entries(aliases)) {
+      if (alias.length === 0) fail(`resolve.aliases keys must be non-empty`);
+      if (typeof target !== "string") {
+        fail(`resolve.aliases["${alias}"] must be a string`);
+      }
+    }
+  }
   if (raw.audit !== void 0) {
     assertObject(raw.audit, "audit");
     for (const key of Object.keys(raw.audit)) {
@@ -304,6 +326,7 @@ function validateConfig(raw) {
     exclude: raw.exclude,
     output: raw.output,
     flows: raw.flows,
+    resolve: raw.resolve,
     audit: raw.audit,
     conventions: raw.conventions,
     statesManifest: raw.statesManifest,
@@ -831,7 +854,6 @@ var CORE_SET = new Set(CORE_STATE_KINDS);
 function isCoreKind(scope) {
   return CORE_SET.has(scope);
 }
-var PLACEHOLDER_REASON = "TODO: why can this never be captured?";
 function isPlaceholderReason(reason) {
   return typeof reason === "string" && /^\s*TODO\b/i.test(reason);
 }
@@ -909,28 +931,6 @@ function parseCoverageBaseline(raw) {
   }
   return { version: 2, acknowledge };
 }
-function isLegacyBaseline(raw) {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return false;
-  const r = raw;
-  if ("acknowledge" in r) return false;
-  return "uncapturedPages" in r || "missingKinds" in r;
-}
-function migrateBaseline(legacy) {
-  const acknowledge = {};
-  const at = (route) => acknowledge[route] ??= {};
-  for (const route of legacy.uncapturedPages ?? []) {
-    if (typeof route === "string") at(route)[ACK_ALL] = { type: "backlog" };
-  }
-  for (const [route, kinds] of Object.entries(legacy.missingKinds ?? {})) {
-    if (!Array.isArray(kinds)) continue;
-    for (const kind of kinds) {
-      if (typeof kind === "string" && isCoreKind(kind)) {
-        at(route)[kind] = { type: "backlog" };
-      }
-    }
-  }
-  return { version: 2, acknowledge };
-}
 function serializeCoverageBaseline(baseline) {
   const routes = Object.keys(baseline.acknowledge).sort();
   const ordered = {};
@@ -964,24 +964,21 @@ var ALLOWED_FIELDS = {
     "acceptance",
     "states",
     "acknowledge",
-    "capture",
-    "waivers",
     "description"
   ]),
   // A page's `acknowledge` accepts both scope shapes: `"*"` (the whole route)
   // and a core kind (one cell of its matrix). A feature/widget has no route, so
   // the core-kind matrix is meaningless there and only `"*"` is accepted —
   // giving a component a scoped opt-out instead of forcing you to delete its
-  // whole `states` block. `capture` / `waivers` are REMOVED; they stay parseable
-  // only so `--fix` can rewrite them into `acknowledge` (see MIGRATION below).
+  // whole `states` block.
   feature: /* @__PURE__ */ new Set([
     "feature",
     "name",
     "features",
+    "surfaces",
     "acceptance",
     "states",
     "acknowledge",
-    "capture",
     "description"
   ]),
   primitive: /* @__PURE__ */ new Set(["primitive", "name", "description"]),
@@ -991,20 +988,19 @@ var ALLOWED_FIELDS = {
     "acceptance",
     "states",
     "acknowledge",
-    "capture",
     "description"
   ]),
   region: /* @__PURE__ */ new Set(["region", "name", "description"]),
   flow: /* @__PURE__ */ new Set(["flow", "notFlow", "name", "description"])
 };
 var ACK_FIELDS = /* @__PURE__ */ new Set(["type", "reason"]);
+var ACCEPTANCE_FIELDS = /* @__PURE__ */ new Set(["id", "rev", "text"]);
 var STATE_FIELDS = /* @__PURE__ */ new Set([
   "name",
   "kind",
   "acceptance",
   "description"
 ]);
-var CORE_STATE_KINDS2 = new Set(CORE_STATE_KINDS);
 var STATE_KINDS = /* @__PURE__ */ new Set([...CORE_STATE_KINDS, "variant"]);
 var FALSEABLE = /* @__PURE__ */ new Set([
   "page",
@@ -1370,7 +1366,8 @@ function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
   } else {
     id = readIdField(idValue, kind, idField);
   }
-  const acceptance = readStringArrayField(byKey, "acceptance")?.values;
+  const criterionIds = /* @__PURE__ */ new Set();
+  const acceptance = readAcceptanceField(byKey, criterionIds);
   const description = readStringField(byKey, "description");
   const name = readStringField(byKey, "name");
   if (name === "") {
@@ -1396,11 +1393,10 @@ function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
   }
   const featuresField = kind === "page" || kind === "feature" ? readStringArrayField(byKey, "features") : void 0;
   const widgetsField = kind === "page" ? readStringArrayField(byKey, "widgets") : void 0;
-  const states = kind === "page" || kind === "feature" || kind === "widget" ? readStatesField(byKey) : void 0;
+  const surfacesField = kind === "feature" ? readStringArrayField(byKey, "surfaces") : void 0;
+  const states = kind === "page" || kind === "feature" || kind === "widget" ? readStatesField(byKey, criterionIds) : void 0;
   const stateBearing = kind === "page" || kind === "feature" || kind === "widget";
   const acknowledge = stateBearing ? readAcknowledgeField(byKey, kind === "page") : void 0;
-  const legacyCapture = stateBearing ? readBooleanField(byKey, "capture") : void 0;
-  const legacyWaivers = kind === "page" ? readWaiversField(byKey) : void 0;
   const notFlow = kind === "flow" && discriminator === "notFlow" ? true : void 0;
   const metadata = {
     source: "ts-export",
@@ -1423,14 +1419,14 @@ function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
     metadata.widgets = widgetsField.values;
     metadata.widgetSpans = widgetsField.spans;
   }
+  if (surfacesField) {
+    metadata.surfaces = surfacesField.values;
+    metadata.surfaceSpans = surfacesField.spans;
+  }
   if (states?.length) metadata.states = states;
   if (acknowledge && Object.keys(acknowledge).length > 0) {
     metadata.acknowledge = acknowledge;
   }
-  if (legacyCapture !== void 0) metadata.legacyCapture = legacyCapture;
-  if (legacyWaivers && Object.keys(legacyWaivers).length > 0) {
-    metadata.legacyWaivers = legacyWaivers;
-  }
   if (notFlow) metadata.notFlow = true;
   if (typeof id === "string" && idValue.kind === "string") {
     metadata.idSpan = idValue.span;
@@ -1546,47 +1542,111 @@ function readAcknowledgeField(byKey, isPage) {
   }
   return out2;
 }
-function readWaiversField(byKey) {
-  const entry = byKey.get("waivers");
+function acceptanceSlug(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).slice(0, 8).join("-");
+}
+function readAcceptanceField(byKey, seen) {
+  const entry = byKey.get("acceptance");
   if (!entry) return void 0;
-  if (entry.value.kind !== "object") {
+  return readAcceptanceItems(entry, seen);
+}
+function readAcceptanceItems(entry, seen) {
+  if (entry.value.kind !== "array") {
     throw new ExtractError(
       "uidex-export-invalid-field",
-      "`waivers` must be an object mapping a core kind to a reason.",
+      "`acceptance` must be an array of strings or `{ id, rev?, text }` objects.",
       entry.value.pos
     );
   }
-  const waivers = {};
-  for (const e of entry.value.entries) {
-    if (!CORE_STATE_KINDS2.has(e.key)) {
+  const criteria = [];
+  for (const item of entry.value.items) {
+    let criterion;
+    if (item.kind === "string") {
+      if (item.value.length === 0) {
+        throw new ExtractError(
+          "uidex-export-invalid-field",
+          "An `acceptance` entry is an empty string.",
+          item.pos
+        );
+      }
+      const id = acceptanceSlug(item.value);
+      if (!id) {
+        throw new ExtractError(
+          "uidex-export-invalid-field",
+          `Acceptance text "${item.value}" contains no alphanumeric characters to derive an id from; use the object form with an explicit \`id\`.`,
+          item.pos
+        );
+      }
+      criterion = { id, rev: 1, text: item.value };
+    } else if (item.kind === "object") {
+      const fieldByKey = /* @__PURE__ */ new Map();
+      for (const e of item.entries) {
+        if (!ACCEPTANCE_FIELDS.has(e.key)) {
+          throw new ExtractError(
+            "uidex-export-invalid-field",
+            `Unknown field "${e.key}" in an \`acceptance\` entry. Allowed: ${[
+              ...ACCEPTANCE_FIELDS
+            ].sort().join(", ")}.`,
+            e.value.pos
+          );
+        }
+        fieldByKey.set(e.key, e);
+      }
+      const id = readStringField(fieldByKey, "id");
+      if (id === void 0 || id.length === 0) {
+        throw new ExtractError(
+          "uidex-export-invalid-field",
+          "An object `acceptance` entry needs a non-empty string `id`.",
+          item.pos
+        );
+      }
+      if (id.includes("@")) {
+        throw new ExtractError(
+          "uidex-export-invalid-field",
+          `acceptance id "${id}" must not contain "@" \u2014 it is reserved for the \`@<rev>\` pin in \`uidexCovers\` claims.`,
+          item.pos
+        );
+      }
+      const text = readStringField(fieldByKey, "text");
+      if (text === void 0 || text.length === 0) {
+        throw new ExtractError(
+          "uidex-export-invalid-field",
+          `acceptance "${id}" needs a non-empty string \`text\`.`,
+          item.pos
+        );
+      }
+      let rev = 1;
+      const revEntry = fieldByKey.get("rev");
+      if (revEntry) {
+        if (revEntry.value.kind !== "number" || !Number.isInteger(revEntry.value.value) || revEntry.value.value < 1) {
+          throw new ExtractError(
+            "uidex-export-invalid-field",
+            `acceptance "${id}" \`rev\` must be a positive integer.`,
+            revEntry.value.pos
+          );
+        }
+        rev = revEntry.value.value;
+      }
+      criterion = { id, rev, text };
+    } else {
       throw new ExtractError(
         "uidex-export-invalid-field",
-        `waiver key "${e.key}" is not a core kind; only ${[...CORE_STATE_KINDS2].join(", ")} participate in the matrix.`,
-        e.keyPos
+        "`acceptance` items must be strings or `{ id, rev?, text }` objects.",
+        item.pos
       );
     }
-    if (e.value.kind !== "string" || e.value.value.length === 0) {
+    if (seen.has(criterion.id)) {
       throw new ExtractError(
-        "uidex-export-invalid-field",
-        `waiver "${e.key}" needs a non-empty reason (why the route cannot render this kind).`,
-        e.value.pos
+        "acceptance-duplicate-id",
+        `Duplicate acceptance criterion id "${criterion.id}"; each criterion id must be unique within the entity.`,
+        item.pos,
+        "Give the criterion an explicit distinct `id` (object form) \u2014 two string criteria can slug to the same id."
       );
     }
-    waivers[e.key] = e.value.value;
+    seen.add(criterion.id);
+    criteria.push(criterion);
   }
-  return waivers;
-}
-function readBooleanField(byKey, name) {
-  const entry = byKey.get(name);
-  if (!entry) return void 0;
-  if (entry.value.kind !== "boolean") {
-    throw new ExtractError(
-      "uidex-export-invalid-field",
-      `\`${name}\` must be a boolean.`,
-      entry.value.pos
-    );
-  }
-  return entry.value.value;
+  return criteria;
 }
 function readStringField(byKey, name) {
   const entry = byKey.get(name);
@@ -1625,7 +1685,7 @@ function readStringArrayField(byKey, name) {
   }
   return { values, spans };
 }
-function readStatesField(byKey) {
+function readStatesField(byKey, criterionIds) {
   const entry = byKey.get("states");
   if (!entry) return void 0;
   if (entry.value.kind !== "array") {
@@ -1675,8 +1735,11 @@ function readStatesField(byKey) {
         }
         state.kind = kind;
       }
-      const acceptance = readStringArrayField(fieldByKey, "acceptance")?.values;
-      if (acceptance) state.acceptance = acceptance;
+      const accEntry = fieldByKey.get("acceptance");
+      if (accEntry) {
+        const acceptance = readAcceptanceItems(accEntry, criterionIds);
+        if (acceptance.length > 0) state.acceptance = acceptance;
+      }
       const description = readStringField(fieldByKey, "description");
       if (description) state.description = description;
     } else {
@@ -1732,20 +1795,21 @@ function isNode2(value) {
 }
 
 // src/scanner/scan/flow-facts.ts
-function collectFlowFacts(parsed, content) {
+function collectFlowFacts(parsed, content, displayPath) {
   if (parsed.program === null || !content.includes("test.describe")) {
-    return [];
+    return { facts: [], diagnostics: [] };
   }
   const facts = [];
+  const diagnostics = [];
   walkAst(parsed.program, (node) => {
     if (node.type !== "CallExpression") return void 0;
-    const fact = readTaggedDescribe(node, parsed);
+    const fact = readTaggedDescribe(node, parsed, diagnostics, displayPath);
     if (fact) facts.push(fact);
     return void 0;
   });
-  return facts;
+  return { facts, diagnostics };
 }
-function readTaggedDescribe(call, parsed) {
+function readTaggedDescribe(call, parsed, diagnostics, displayPath) {
   const callee = call.callee;
   if (!callee || callee.type !== "MemberExpression" || !isIdentifier(callee.object, "test") || !isIdentifier(callee.property, "describe")) {
     return null;
@@ -1756,13 +1820,83 @@ function readTaggedDescribe(call, parsed) {
   if (!hasFlowTag(args[1])) return null;
   const body = args[2];
   const { calls, dynamicCalls } = body ? collectUidexCalls(body, parsed) : { calls: [], dynamicCalls: [] };
+  const covers = body ? collectCoversClaims(body, parsed, title, diagnostics, displayPath) : [];
   return {
     title,
     line: parsed.lineAt(call.start),
     calls,
-    ...dynamicCalls.length > 0 ? { dynamicCalls } : {}
+    ...dynamicCalls.length > 0 ? { dynamicCalls } : {},
+    ...covers.length > 0 ? { covers } : {}
   };
 }
+function collectCoversClaims(body, parsed, flowTitle, diagnostics, displayPath) {
+  const covers = [];
+  walkAst(body, (node) => {
+    if (node.type !== "CallExpression") return void 0;
+    if (!isIdentifier(node.callee, "uidexCovers")) return void 0;
+    const line = parsed.lineAt(node.start);
+    const args = node.arguments ?? [];
+    const entity = stringLiteralValue(args[0]);
+    if (entity === null) {
+      diagnostics.push({
+        code: "covers-missing-rev",
+        severity: "error",
+        message: `\`uidexCovers(\u2026)\` in flow "${flowTitle}" needs a static string entity id as its first argument.`,
+        file: displayPath,
+        line,
+        hint: 'Write `uidexCovers("<entityId>", "<criterionId>@<rev>")` with string literals.'
+      });
+      return void 0;
+    }
+    if (args.length < 2) {
+      diagnostics.push({
+        code: "covers-missing-rev",
+        severity: "error",
+        message: `\`uidexCovers("${entity}")\` in flow "${flowTitle}" names no criterion; a claim covers nothing without at least one \`"<criterionId>@<rev>"\` argument.`,
+        file: displayPath,
+        line,
+        hint: 'List the criteria this flow verifies: `uidexCovers("<entityId>", "<criterionId>@<rev>", ...)`.'
+      });
+      return void 0;
+    }
+    for (const arg of args.slice(1)) {
+      const claimLine = parsed.lineAt(arg.start);
+      const raw = stringLiteralValue(arg);
+      const at = raw === null ? -1 : raw.lastIndexOf("@");
+      if (raw === null || at <= 0) {
+        diagnostics.push({
+          code: "covers-missing-rev",
+          severity: "error",
+          message: `\`uidexCovers(\u2026)\` claim ${raw === null ? "" : `"${raw}" `}in flow "${flowTitle}" is missing its \`@<rev>\` pin.`,
+          file: displayPath,
+          line: claimLine,
+          hint: 'Pin the criterion rev \u2014 `uidexCovers("<entityId>", "<criterionId>@<rev>")` \u2014 so a later rev bump surfaces this claim as outdated.'
+        });
+        continue;
+      }
+      const revStr = raw.slice(at + 1);
+      if (!/^[1-9]\d*$/.test(revStr)) {
+        diagnostics.push({
+          code: "covers-missing-rev",
+          severity: "error",
+          message: `\`uidexCovers(\u2026)\` claim "${raw}" in flow "${flowTitle}" has an invalid rev "@${revStr}"; the rev must be a positive integer (no leading zeros).`,
+          file: displayPath,
+          line: claimLine,
+          hint: 'Write the pin as `"<criterionId>@<rev>"` with a positive integer rev, e.g. `"gated@1"`.'
+        });
+        continue;
+      }
+      covers.push({
+        entity,
+        criterion: raw.slice(0, at),
+        rev: Number(revStr),
+        line: claimLine
+      });
+    }
+    return void 0;
+  });
+  return covers;
+}
 function hasFlowTag(node) {
   if (!node || node.type !== "ObjectExpression") return false;
   for (const prop of node.properties ?? []) {
@@ -2154,11 +2288,13 @@ function extract(files) {
     const out2 = { file, annotations: [] };
     out2.annotations = extractOne(file, parsed, out2);
     if (exports2.length > 0) out2.metadata = exports2;
+    const flowFacts = collectFlowFacts(parsed, file.content, file.displayPath);
+    diagnostics.push(...flowFacts.diagnostics);
     if (diagnostics.length > 0) out2.diagnostics = diagnostics;
-    const flows = collectFlowFacts(parsed, file.content);
-    if (flows.length > 0) out2.flows = flows;
+    if (flowFacts.facts.length > 0) out2.flows = flowFacts.facts;
     const imports = collectImportFacts(parsed);
     if (imports.length > 0) out2.imports = imports;
+    if (containsJsx(parsed)) out2.hasJsx = true;
     return out2;
   });
 }
@@ -2183,6 +2319,32 @@ function extractOne(file, parsed, out2) {
   }
   return annotations;
 }
+function containsJsx(parsed) {
+  if (parsed.program === null) return false;
+  let found = false;
+  walkAst(parsed.program, (node) => {
+    if (node.type === "JSXElement" || node.type === "JSXFragment") {
+      found = true;
+      return false;
+    }
+    if (node.type === "CallExpression" && isCreateElementCallee(node.callee)) {
+      found = true;
+      return false;
+    }
+    return void 0;
+  });
+  return found;
+}
+function isCreateElementCallee(callee) {
+  const node = callee;
+  if (!node) return false;
+  if (node.type === "Identifier") return String(node.name) === "createElement";
+  if (node.type === "MemberExpression") {
+    const prop = node.property;
+    return prop?.type === "Identifier" && String(prop.name) === "createElement";
+  }
+  return false;
+}
 function collectImportFacts(parsed) {
   if (parsed.program === null) return [];
   const out2 = [];
@@ -2215,6 +2377,21 @@ function collectImportFacts(parsed) {
       names
     });
   }
+  walkAst(parsed.program, (node) => {
+    if (node.type !== "ImportExpression") return void 0;
+    const source = node.source;
+    if (!source || source.type !== "Literal") return void 0;
+    if (typeof source.value !== "string") return void 0;
+    out2.push({
+      specifier: source.value,
+      line: parsed.lineAt(node.start),
+      span: { start: node.start, end: node.end },
+      isTypeOnly: false,
+      names: [],
+      dynamic: true
+    });
+    return void 0;
+  });
   return out2;
 }
 
@@ -2386,6 +2563,7 @@ function buildMetaFromExport(exp) {
   if (exp.acceptance?.length) meta.acceptance = exp.acceptance;
   if (exp.features?.length) meta.features = exp.features;
   if (exp.widgets?.length) meta.widgets = exp.widgets;
+  if (exp.surfaces?.length) meta.surfaces = exp.surfaces;
   if (exp.states?.length) {
     meta.states = exp.states.map((s) => ({
       name: s.name,
@@ -2799,7 +2977,8 @@ function resolve2(ctx) {
           id: flowExport.id,
           loc: base.loc,
           touches: base.touches,
-          steps: base.steps
+          steps: base.steps,
+          ...base.covers ? { covers: base.covers } : {}
         };
         registry.add(flow);
       } else {
@@ -2847,20 +3026,42 @@ function computeScope(displayPath) {
   return null;
 }
 function flowsFromFacts(ff) {
-  return (ff.flows ?? []).map((fact) => ({
-    kind: "flow",
-    id: kebab(fact.title),
-    loc: { file: ff.file.displayPath, line: fact.line },
-    touches: dedupe(fact.calls.map((c) => c.id)),
-    steps: fact.calls.filter((c) => c.action).map((c) => ({ entityId: c.id, action: c.action }))
-  }));
+  return (ff.flows ?? []).map((fact) => {
+    const covers = dedupeBy(
+      (fact.covers ?? []).map((c) => ({
+        entity: c.entity,
+        criterion: c.criterion,
+        rev: c.rev
+      })),
+      (c) => `${c.entity} ${c.criterion} ${c.rev}`
+    );
+    return {
+      kind: "flow",
+      id: kebab(fact.title),
+      loc: { file: ff.file.displayPath, line: fact.line },
+      touches: dedupe(fact.calls.map((c) => c.id)),
+      steps: fact.calls.filter((c) => c.action).map((c) => ({ entityId: c.id, action: c.action })),
+      ...covers.length > 0 ? { covers } : {}
+    };
+  });
+}
+function dedupeBy(arr, key) {
+  const seen = /* @__PURE__ */ new Set();
+  const out2 = [];
+  for (const item of arr) {
+    const k = key(item);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out2.push(item);
+  }
+  return out2;
 }
 function dedupe(arr) {
   return Array.from(new Set(arr));
 }
 
 // src/scanner/scan/audit.ts
-var path6 = __toESM(require("path"), 1);
+var path7 = __toESM(require("path"), 1);
 
 // src/scanner/scan/component-coverage.ts
 var COMPOSED_KINDS = ["widget", "feature"];
@@ -2915,141 +3116,6 @@ function checkComponentCoverage(registry, manifest) {
   return diagnostics;
 }
 
-// src/scanner/scan/migrate-acknowledge.ts
-var CORE = CORE_STATE_KINDS;
-function orderScopes(scopes) {
-  const rank = (s) => s === ACK_ALL ? -1 : CORE.indexOf(s);
-  return [...scopes].sort((a, b) => rank(a) - rank(b));
-}
-function renderKey(scope) {
-  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(scope) ? scope : JSON.stringify(scope);
-}
-function renderAck(a) {
-  const parts = [`type: ${JSON.stringify(a.type)}`];
-  if (a.reason) parts.push(`reason: ${JSON.stringify(a.reason)}`);
-  return `{ ${parts.join(", ")} }`;
-}
-function renderAcknowledge(entries, indent) {
-  const inner = indent + "  ";
-  const lines = orderScopes(Object.keys(entries)).map(
-    (scope) => `${inner}${renderKey(scope)}: ${renderAck(entries[scope])},`
-  );
-  return ["acknowledge: {", ...lines, `${indent}}`].join("\n");
-}
-function indentAt(content, offset) {
-  const lineStart = content.lastIndexOf("\n", offset - 1) + 1;
-  const m = /^[ \t]*/.exec(content.slice(lineStart, offset));
-  return m ? m[0] : "";
-}
-function plannedEntries(m) {
-  const entries = {};
-  if (m.legacyCapture === false) {
-    entries[ACK_ALL] = {
-      type: "impossible",
-      reason: m.description || PLACEHOLDER_REASON
-    };
-  }
-  for (const kind of CORE) {
-    const reason = m.legacyWaivers?.[kind];
-    if (reason) entries[kind] = { type: "impossible", reason };
-  }
-  return entries;
-}
-function migrateLegacyFields(ef) {
-  const out2 = [];
-  const { content, sourcePath, displayPath } = ef.file;
-  for (const m of ef.metadata ?? []) {
-    const legacy = [];
-    if (m.legacyWaivers) legacy.push("waivers");
-    if (m.legacyCapture !== void 0) legacy.push("capture");
-    if (legacy.length === 0) continue;
-    const fields = legacy.join(" and ");
-    const base = {
-      severity: "error",
-      code: "legacy-acknowledge-field",
-      file: displayPath,
-      line: m.loc.line
-    };
-    if (m.acknowledge) {
-      out2.push({
-        ...base,
-        message: `\`${fields}\` was replaced by \`acknowledge\`, and this declaration already has an \`acknowledge\` field`,
-        hint: `Merge the remaining \`${fields}\` entries into \`acknowledge\` by hand and delete them; --fix will not merge two maps for you.`
-      });
-      continue;
-    }
-    const entries = plannedEntries(m);
-    const edits = [];
-    const present = legacy.map((f) => ({ f, prop: m.fieldPropSpans?.[f], del: m.fieldSpans?.[f] })).filter((x) => x.prop && x.del).sort((a, b) => a.prop.start - b.prop.start);
-    if (present.length !== legacy.length) {
-      out2.push({
-        ...base,
-        message: `\`${fields}\` was replaced by \`acknowledge\`, but the field spans needed to rewrite it are unavailable`,
-        hint: "Rewrite the declaration by hand: `acknowledge: { <scope>: { type, reason? } }`."
-      });
-      continue;
-    }
-    const [anchor, ...rest] = present;
-    if (Object.keys(entries).length === 0) {
-      edits.push({
-        path: sourcePath,
-        start: anchor.del.start,
-        end: anchor.del.end,
-        replacement: ""
-      });
-    } else {
-      edits.push({
-        path: sourcePath,
-        start: anchor.prop.start,
-        end: anchor.prop.end,
-        replacement: renderAcknowledge(
-          entries,
-          indentAt(content, anchor.prop.start)
-        )
-      });
-    }
-    for (const r of rest) {
-      edits.push({
-        path: sourcePath,
-        start: r.del.start,
-        end: r.del.end,
-        replacement: ""
-      });
-    }
-    out2.push({
-      ...base,
-      message: `\`${fields}\` was replaced by the unified \`acknowledge\` field`,
-      hint: `Run \`uidex scan --fix\` to rewrite it${m.legacyCapture === false && !m.description ? ", then replace the TODO reason it plants \u2014 `capture: false` carried no explanation and `impossible` requires one" : ""}.`,
-      fix: {
-        description: `Rewrite \`${fields}\` as \`acknowledge\``,
-        edits
-      }
-    });
-  }
-  return out2;
-}
-function migrateLegacyBaseline(opts) {
-  if (!isLegacyBaseline(opts.parsed)) return void 0;
-  return {
-    code: "legacy-coverage-baseline",
-    severity: "error",
-    message: `coverage baseline "${opts.displayPath}" uses the removed \`uncapturedPages\` / \`missingKinds\` shape`,
-    file: opts.displayPath,
-    hint: "Run `uidex scan --fix` to rewrite it as `acknowledge` entries of type `backlog` (identical content, new shape \u2014 no capture run needed).",
-    fix: {
-      description: `Rewrite ${opts.displayPath} as an \`acknowledge\` baseline`,
-      edits: [
-        {
-          path: opts.path,
-          start: 0,
-          end: opts.raw.length,
-          replacement: serializeCoverageBaseline(migrateBaseline(opts.parsed))
-        }
-      ]
-    }
-  };
-}
-
 // src/scanner/scan/page-coverage.ts
 function compileRoute(pattern) {
   const segs = pattern.split("/").filter(Boolean);
@@ -3071,11 +3137,11 @@ function compileRoute(pattern) {
   return { test: (url) => re.test(url), specificity };
 }
 function matchUrlToRoute(url, routePaths) {
-  const path13 = stripQuery(url);
+  const path14 = stripQuery(url);
   let best = null;
   for (const rp of routePaths) {
     const { test, specificity } = compileRoute(rp);
-    if (!test(path13)) continue;
+    if (!test(path14)) continue;
     if (!best || specificity > best.specificity)
       best = { path: rp, specificity };
   }
@@ -3483,6 +3549,182 @@ function computeMatrixBacklog(registry, manifest) {
   return out2;
 }
 
+// src/scanner/scan/surface-check.ts
+var path6 = __toESM(require("path"), 1);
+var EXT_CANDIDATES = [
+  "",
+  ".tsx",
+  ".ts",
+  ".jsx",
+  ".js",
+  "/index.tsx",
+  "/index.ts",
+  "/index.jsx",
+  "/index.js"
+];
+function checkFeatureSurfaces(registry, extracted, config) {
+  const declarations = [];
+  for (const ef of extracted) {
+    for (const m of ef.metadata ?? []) {
+      if (m.kind !== "feature") continue;
+      if (typeof m.id !== "string") continue;
+      if (!m.surfaces || m.surfaces.length === 0) continue;
+      if (m.acknowledge?.["*"]) continue;
+      declarations.push({
+        ef,
+        id: m.id,
+        surfaces: m.surfaces,
+        surfaceSpans: m.surfaceSpans,
+        line: m.loc.line ?? 1
+      });
+    }
+  }
+  if (declarations.length === 0) return [];
+  const fileSet = /* @__PURE__ */ new Set();
+  const jsxFiles = /* @__PURE__ */ new Set();
+  for (const ef of extracted) {
+    fileSet.add(ef.file.displayPath);
+    if (ef.hasJsx) jsxFiles.add(ef.file.displayPath);
+  }
+  const aliases = Object.entries(config.resolve?.aliases ?? {}).sort(
+    (a, b) => b[0].length - a[0].length
+  );
+  const resolveSpecifier = (importer, spec) => {
+    const bases = [];
+    if (spec.startsWith("./") || spec.startsWith("../")) {
+      bases.push(path6.posix.join(path6.posix.dirname(importer), spec));
+    } else {
+      const alias = aliases.find(([prefix]) => spec.startsWith(prefix));
+      if (alias) {
+        bases.push(alias[1] + spec.slice(alias[0].length));
+      } else if (aliases.length === 0) {
+        if (spec.startsWith("@/") || spec.startsWith("~/")) {
+          bases.push("src/" + spec.slice(2));
+        }
+      }
+      bases.push(spec);
+    }
+    const hits = [];
+    for (const base of bases) {
+      const normalized = path6.posix.normalize(base);
+      for (const ext of EXT_CANDIDATES) {
+        const candidate = normalized + ext;
+        if (fileSet.has(candidate)) hits.push(candidate);
+      }
+    }
+    return hits;
+  };
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const ef of extracted) {
+    const targets = [];
+    for (const imp of ef.imports ?? []) {
+      if (imp.isTypeOnly) continue;
+      targets.push(...resolveSpecifier(ef.file.displayPath, imp.specifier));
+    }
+    if (targets.length > 0) adjacency.set(ef.file.displayPath, targets);
+  }
+  const inDir = (file, dir) => file === dir || file.startsWith(dir + "/");
+  const reachesDir = (seeds, dir) => {
+    const queue = [...seeds];
+    const visited = new Set(queue);
+    while (queue.length > 0) {
+      const current = queue.pop();
+      if (inDir(current, dir) && jsxFiles.has(current)) return true;
+      for (const next of adjacency.get(current) ?? []) {
+        if (visited.has(next)) continue;
+        visited.add(next);
+        queue.push(next);
+      }
+    }
+    return false;
+  };
+  const featuresConvention = config.conventions?.features === void 0 ? DEFAULT_CONVENTIONS.features : config.conventions.features;
+  const featureGlob = typeof featuresConvention === "string" ? featuresConvention : null;
+  const diagnostics = [];
+  for (const decl of declarations) {
+    const declPath = decl.ef.file.displayPath;
+    const featureDir = (featureGlob !== null ? extractFeatureDir(declPath, featureGlob) : null) ?? path6.posix.dirname(declPath);
+    for (let i = 0; i < decl.surfaces.length; i++) {
+      const pageId = decl.surfaces[i];
+      const line = decl.surfaceSpans?.[i] ? lineOfOffset(decl.ef.file.content, decl.surfaceSpans[i].start) : decl.line;
+      const page = registry.get("page", pageId) ?? registry.matchPattern("page", pageId);
+      if (!page) {
+        diagnostics.push({
+          code: "unknown-reference",
+          severity: "warning",
+          message: `Feature "${decl.id}" declares a surface on unknown page "${pageId}"`,
+          file: decl.ef.file.displayPath,
+          line,
+          entity: { kind: "feature", id: decl.id },
+          hint: `No page with id "${pageId}" exists in the registry; fix the reference or add the page.`
+        });
+        continue;
+      }
+      const pageFile = page.loc?.file;
+      if (!pageFile) continue;
+      const seeds = [pageFile];
+      if (path6.posix.basename(pageFile) === WELL_KNOWN_FILES.page) {
+        const dir = path6.posix.dirname(pageFile);
+        for (const f of fileSet) {
+          if (f !== pageFile && path6.posix.dirname(f) === dir) seeds.push(f);
+        }
+      }
+      if (reachesDir(seeds, featureDir)) continue;
+      diagnostics.push({
+        code: "feature-surface-unreferenced",
+        severity: "warning",
+        message: `Feature "${decl.id}" declares page "${pageId}" as a surface, but nothing reachable from ${pageFile} references a component file in ${featureDir}/`,
+        file: decl.ef.file.displayPath,
+        line,
+        entity: { kind: "feature", id: decl.id },
+        hint: `This is a static tripwire, not proof either way: verify page "${pageId}" really mounts a component from ${featureDir}/ (and that the import resolves within the scanned sources), or remove "${pageId}" from the feature's \`surfaces\`.`
+      });
+    }
+  }
+  return diagnostics;
+}
+function checkFeatureSurfaceCaptures(registry, manifest) {
+  const routes = registry.list("route");
+  if (routes.length === 0) return [];
+  const routePaths = routes.map((r) => r.path);
+  const captured = manifest.captured ?? [];
+  const diagnostics = [];
+  for (const feature of registry.list("feature")) {
+    const surfaces = feature.meta?.surfaces ?? [];
+    if (surfaces.length === 0) continue;
+    if (entityAcknowledge(feature.meta)) continue;
+    const coveredRoutes = /* @__PURE__ */ new Set();
+    for (const c of captured) {
+      if (c.kind !== "feature" || c.entity !== feature.id) continue;
+      const route = routeForCapture(c, routes, routePaths);
+      if (route) coveredRoutes.add(route);
+    }
+    for (const pageId of surfaces) {
+      const pageRoutes = routes.filter((r) => r.page === pageId);
+      if (pageRoutes.length === 0) continue;
+      if (pageRoutes.some((r) => coveredRoutes.has(r.path))) continue;
+      const routeList = pageRoutes.map((r) => `"${r.path}"`).join(", ");
+      diagnostics.push({
+        code: "feature-surface-uncaptured",
+        severity: "warning",
+        message: `Feature "${feature.id}" declares page "${pageId}" as a surface, but no capture rendered the feature on ${pageRoutes.length === 1 ? `route ${routeList}` : `any of its routes (${routeList})`}`,
+        file: feature.loc?.file,
+        line: feature.loc?.line,
+        entity: { kind: "feature", id: feature.id },
+        hint: `Author a states capture spec that renders feature "${feature.id}" on page "${pageId}" (a capture with kind "feature" driving ${routeList}), or acknowledge the feature with \`acknowledge: { "*": \u2026 }\`.`
+      });
+    }
+  }
+  return diagnostics;
+}
+function lineOfOffset(content, offset) {
+  let line = 1;
+  for (let i = 0; i < offset && i < content.length; i++) {
+    if (content[i] === "\n") line++;
+  }
+  return line;
+}
+
 // src/scanner/scan/audit.ts
 function audit(opts) {
   const diagnostics = [];
@@ -3490,6 +3732,8 @@ function audit(opts) {
   const check = opts.check ?? false;
   const lint = opts.lint ?? false;
   const acceptanceEnabled = config.audit?.acceptance ?? true;
+  const surfacesEnabled = config.audit?.surfaces ?? true;
+  const requireAcceptanceEnabled = config.audit?.requireAcceptance ?? true;
   const scopeLeakEnabled = config.audit?.scopeLeak ?? true;
   const coverageEnabled = config.audit?.coverage ?? true;
   const statesEnabled = config.audit?.states ?? true;
@@ -3502,8 +3746,6 @@ function audit(opts) {
   for (const ef of opts.flowExtracted ?? []) {
     if (ef.diagnostics) diagnostics.push(...ef.diagnostics);
   }
-  for (const ef of extracted) diagnostics.push(...migrateLegacyFields(ef));
-  if (opts.baselineDiagnostic) diagnostics.push(opts.baselineDiagnostic);
   for (const ef of extracted) {
     for (const m of ef.metadata ?? []) {
       for (const [scope, ack] of Object.entries(m.acknowledge ?? {})) {
@@ -3588,9 +3830,66 @@ function audit(opts) {
     }
   }
   if (lint && acceptanceEnabled) {
-    for (const kind of ["widget", "feature", "page"]) {
+    const flowEntities = registry.list("flow");
+    const acceptanceKinds = ["widget", "feature", "page"];
+    const claims = /* @__PURE__ */ new Map();
+    const addClaim = (kind, entityId, criterion, claim) => {
+      const key = `${kind}:${entityId}`;
+      let byCrit = claims.get(key);
+      if (!byCrit) {
+        byCrit = /* @__PURE__ */ new Map();
+        claims.set(key, byCrit);
+      }
+      let list = byCrit.get(criterion);
+      if (!list) {
+        list = [];
+        byCrit.set(criterion, list);
+      }
+      list.push(claim);
+    };
+    for (const flow of flowEntities) {
+      for (const c of flow.covers ?? []) {
+        const candidates = acceptanceKinds.flatMap((k) => {
+          const e = registry.get(k, c.entity);
+          return e ? [e] : [];
+        });
+        const matching = candidates.filter(
+          (e) => entityCriteria(e).some((crit) => crit.id === c.criterion)
+        );
+        if (matching.length === 0) {
+          diagnostics.push({
+            code: "acceptance-orphaned",
+            severity: "warning",
+            message: `Flow "${flow.id}" covers criterion "${c.criterion}" on "${c.entity}", but ${candidates.length > 0 ? `no criterion with that id exists on ${candidates.map((e) => `${e.kind} "${c.entity}"`).join(" or ")}` : `no page/feature/widget "${c.entity}" exists`}`,
+            file: flow.loc.file,
+            line: flow.loc.line,
+            entity: { kind: "flow", id: flow.id },
+            hint: "Remove the stale uidexCovers claim, or fix the entity/criterion id it names."
+          });
+          continue;
+        }
+        if (matching.length > 1) {
+          diagnostics.push({
+            code: "acceptance-ambiguous",
+            severity: "warning",
+            message: `Flow "${flow.id}" covers criterion "${c.criterion}" on "${c.entity}", which matches ${matching.map((e) => `${e.kind} "${c.entity}"`).join(" and ")}; the claim credits all of them`,
+            file: flow.loc.file,
+            line: flow.loc.line,
+            entity: { kind: "flow", id: flow.id },
+            hint: "The claim syntax carries no kind, so a criterion id shared by same-id entities cannot be told apart \u2014 rename one entity or criterion id to disambiguate."
+          });
+        }
+        for (const target of matching) {
+          addClaim(target.kind, target.id, c.criterion, {
+            flowId: flow.id,
+            rev: c.rev
+          });
+        }
+      }
+    }
+    for (const kind of acceptanceKinds) {
       for (const e of registry.list(kind)) {
-        const criteria = e.meta?.acceptance ?? [];
+        const criteria = entityCriteria(e);
         if (criteria.length === 0) {
           if (kind === "widget") {
             diagnostics.push({
@@ -3605,14 +3904,27 @@ function audit(opts) {
           }
           continue;
         }
-        const flowIds = e.meta?.flows ?? [];
-        if (flowIds.length === 0) {
-          const hint = kind === "widget" ? `uidex scaffold widget ${e.id}` : `Add a Playwright flow under e2e/** that touches ${kind} "${e.id}" (tag the describe with @uidex:flow)`;
-          for (const c of criteria) {
+        const entityClaims = claims.get(`${kind}:${e.id}`);
+        for (const c of criteria) {
+          const critClaims = entityClaims?.get(c.id) ?? [];
+          const stale = critClaims.filter((cl) => cl.rev !== c.rev);
+          for (const cl of stale) {
+            diagnostics.push({
+              code: "acceptance-outdated",
+              severity: "warning",
+              message: `Flow "${cl.flowId}" covers ${kind} "${e.id}" criterion "${c.id}" at rev ${cl.rev}, but the criterion is now rev ${c.rev}`,
+              file: e.loc?.file,
+              line: e.loc?.line,
+              entity: { kind, id: e.id },
+              hint: `Re-verify the flow against the current criterion text, then update its claim to \`uidexCovers("${e.id}", "${c.id}@${c.rev}")\`.`
+            });
+          }
+          if (critClaims.length === 0) {
+            const hint = kind === "widget" ? `uidex scaffold widget ${e.id}, then claim it with \`uidexCovers("${e.id}", "${c.id}@${c.rev}")\`` : `Add a Playwright flow under e2e/** that touches ${kind} "${e.id}" (tag the describe with @uidex:flow) and claim the criterion with \`uidexCovers("${e.id}", "${c.id}@${c.rev}")\``;
             diagnostics.push({
               code: "acceptance-uncovered",
               severity: "warning",
-              message: `${kind} "${e.id}" has acceptance criterion not covered by any flow: "${c}"`,
+              message: `${kind} "${e.id}" has acceptance criterion "${c.id}" not covered by any flow: "${c.text}"`,
               file: e.loc?.file,
               line: e.loc?.line,
               entity: { kind, id: e.id },
@@ -3623,7 +3935,31 @@ function audit(opts) {
       }
     }
   }
+  if (lint && surfacesEnabled) {
+    diagnostics.push(...checkFeatureSurfaces(registry, extracted, config));
+  }
+  if (lint && surfacesEnabled && opts.capturedStates) {
+    diagnostics.push(
+      ...checkFeatureSurfaceCaptures(registry, opts.capturedStates)
+    );
+  }
+  if (lint && requireAcceptanceEnabled) {
+    for (const e of registry.list("feature")) {
+      if (entityCriteria(e).length > 0) continue;
+      diagnostics.push({
+        code: "feature-missing-acceptance",
+        severity: "warning",
+        message: `Feature "${e.id}" declares no acceptance criteria`,
+        file: e.loc?.file,
+        line: e.loc?.line,
+        entity: { kind: "feature", id: e.id },
+        hint: `Add \`acceptance: [...]\` to the feature's \`export const uidex\` \u2014 observable outcomes, not implementation. They feed \`uidex scaffold feature ${e.id}\` and the acceptance-uncovered gate.`
+      });
+    }
+  }
   if (lint) {
+    const featuresConvention = config.conventions?.features === void 0 ? DEFAULT_CONVENTIONS.features : config.conventions.features;
+    const featureGlob = typeof featuresConvention === "string" ? featuresConvention : null;
     const scannedPaths = new Set(files.map((f) => f.displayPath));
     for (const ef of extracted) {
       if (!ef.metadata) continue;
@@ -3632,10 +3968,24 @@ function audit(opts) {
         if (typeof m.id !== "string") continue;
         const filePath = ef.file.displayPath;
         const wellKnownName = WELL_KNOWN_FILES[m.kind];
-        if (path6.posix.basename(filePath) === wellKnownName) continue;
-        const dir = path6.posix.dirname(filePath);
+        if (path7.posix.basename(filePath) === wellKnownName) continue;
+        const featureDir = m.kind === "feature" && featureGlob !== null ? extractFeatureDir(filePath, featureGlob) : null;
+        const dir = featureDir ?? path7.posix.dirname(filePath);
         const wellKnownPath = dir === "." ? wellKnownName : `${dir}/${wellKnownName}`;
         if (scannedPaths.has(wellKnownPath)) continue;
+        const inConventionDir = featureDir !== null;
+        if (inConventionDir) {
+          diagnostics.push({
+            code: "prefer-well-known-file",
+            severity: "error",
+            message: `Feature "${m.id}" metadata lives on ${filePath}; a feature in a convention-derived directory must declare its metadata in ${wellKnownPath}`,
+            file: filePath,
+            line: m.loc.line,
+            entity: { kind: "feature", id: m.id },
+            hint: `Move the \`export const uidex\` block to ${wellKnownPath} and remove it from ${filePath}.`
+          });
+          continue;
+        }
         const kindLabel = m.kind === "page" ? "Page" : "Feature";
         diagnostics.push({
           code: "prefer-well-known-file",
@@ -3719,6 +4069,7 @@ function audit(opts) {
       const displayPath = ef.file.displayPath;
       for (const imp of ef.imports ?? []) {
         if (imp.isTypeOnly) continue;
+        if (imp.dynamic) continue;
         const baseName2 = imp.specifier.split("/").pop() ?? "";
         const primitive = byName.get(
           baseName2.replace(/\.(tsx|ts|jsx|js|mjs|cjs)$/, "").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()
@@ -3836,7 +4187,7 @@ function audit(opts) {
               severity: "warning",
               message: `\`export const uidex\` in ${ef.file.displayPath} references unknown ${refKind} "${refId}"`,
               file: ef.file.displayPath,
-              line: spans?.[i] ? lineOfOffset(ef.file.content, spans[i].start) : m.loc.line,
+              line: spans?.[i] ? lineOfOffset2(ef.file.content, spans[i].start) : m.loc.line,
               hint: `No ${refKind} with id "${refId}" exists in the registry; fix the reference or add the ${refKind}.`
             });
           }
@@ -3883,13 +4234,21 @@ function audit(opts) {
   };
   return { diagnostics: governed, summary };
 }
-function lineOfOffset(content, offset) {
+function lineOfOffset2(content, offset) {
   let line = 1;
   for (let i = 0; i < offset && i < content.length; i++) {
     if (content[i] === "\n") line++;
   }
   return line;
 }
+function entityCriteria(e) {
+  const meta = e.meta;
+  if (!meta) return [];
+  return [
+    ...meta.acceptance ?? [],
+    ...(meta.states ?? []).flatMap((s) => s.acceptance ?? [])
+  ];
+}
 var TAG_FALLBACK_ID = {
   a: "link",
   button: "button",
@@ -4334,10 +4693,16 @@ function emit(opts) {
     '  export type CoreStateKind = "loading" | "empty" | "populated" | "error"'
   );
   t.push('  export type StateKind = CoreStateKind | "variant"');
+  t.push("  export interface AcceptanceCriterion {");
+  t.push("    id: string");
+  t.push("    rev?: number");
+  t.push("    text: string");
+  t.push("  }");
+  t.push("  export type Acceptance = readonly (string | AcceptanceCriterion)[]");
   t.push("  export interface State {");
   t.push("    name: string");
   t.push("    kind?: StateKind");
-  t.push("    acceptance?: readonly string[]");
+  t.push("    acceptance?: Acceptance");
   t.push("    description?: string");
   t.push("  }");
   t.push('  export type AcknowledgeScope = CoreStateKind | "*"');
@@ -4359,7 +4724,7 @@ function emit(opts) {
   t.push("    name?: string");
   t.push("    features?: readonly FeatureId[]");
   t.push("    widgets?: readonly WidgetId[]");
-  t.push("    acceptance?: readonly string[]");
+  t.push("    acceptance?: Acceptance");
   t.push("    states?: readonly (string | State)[]");
   t.push("    acknowledge?: Acknowledge");
   t.push("    description?: string");
@@ -4368,7 +4733,8 @@ function emit(opts) {
   t.push("    feature: FeatureId | false");
   t.push("    name?: string");
   t.push("    features?: readonly FeatureId[]");
-  t.push("    acceptance?: readonly string[]");
+  t.push("    surfaces?: readonly PageId[]");
+  t.push("    acceptance?: Acceptance");
   t.push("    states?: readonly (string | State)[]");
   t.push("    acknowledge?: ComponentAcknowledge");
   t.push("    description?: string");
@@ -4381,7 +4747,7 @@ function emit(opts) {
   t.push("  export interface Widget {");
   t.push("    widget: WidgetId");
   t.push("    name?: string");
-  t.push("    acceptance?: readonly string[]");
+  t.push("    acceptance?: Acceptance");
   t.push("    states?: readonly (string | State)[]");
   t.push("    acknowledge?: ComponentAcknowledge");
   t.push("    description?: string");
@@ -4480,7 +4846,7 @@ function parseGitHubRef(ref) {
 
 // src/scanner/scan/scaffold.ts
 var fs4 = __toESM(require("fs"), 1);
-var path7 = __toESM(require("path"), 1);
+var path8 = __toESM(require("path"), 1);
 function scaffoldWidgetSpec(opts) {
   return scaffoldSpec({
     registry: opts.registry,
@@ -4504,9 +4870,9 @@ function scaffoldSpec(opts) {
   if (!entity) {
     throw new Error(`${capitalize(kind)} "${id}" not found in registry`);
   }
-  const criteria = entity.meta?.acceptance ?? [];
+  const criteria = entityCriteria(entity);
   const filename = kind === "widget" ? `widget-${id}.spec.ts` : `flow-${id}.spec.ts`;
-  const outputPath = path7.resolve(outDir, filename);
+  const outputPath = path8.resolve(outDir, filename);
   if (fs4.existsSync(outputPath) && !force) {
     return {
       outputPath,
@@ -4515,8 +4881,8 @@ function scaffoldSpec(opts) {
       reason: `spec already exists at ${outputPath}; pass --force to overwrite`
     };
   }
-  const content = renderSpec({ id, criteria, fixtureImport });
-  fs4.mkdirSync(path7.dirname(outputPath), { recursive: true });
+  const content = renderSpec({ id, entityId: id, criteria, fixtureImport });
+  fs4.mkdirSync(path8.dirname(outputPath), { recursive: true });
   fs4.writeFileSync(outputPath, content, "utf8");
   return { outputPath, written: true, skipped: false };
 }
@@ -4543,8 +4909,9 @@ function renderSpec(args) {
     ]);
   } else {
     for (const criterion of args.criteria) {
-      stub(criterion, [
-        "// TODO: drive this criterion, then remove `.fixme` to arm the test."
+      stub(`${criterion.id}: ${criterion.text}`, [
+        "// TODO: drive this criterion, then remove `.fixme` to arm the test",
+        `// and claim it: uidexCovers(${JSON.stringify(args.entityId)}, ${JSON.stringify(`${criterion.id}@${criterion.rev}`)})`
       ]);
     }
   }
@@ -4555,36 +4922,29 @@ function renderSpec(args) {
 
 // src/scanner/scan/pipeline.ts
 var fs5 = __toESM(require("fs"), 1);
-var path8 = __toESM(require("path"), 1);
+var path9 = __toESM(require("path"), 1);
 var DEFAULT_STATES_MANIFEST2 = "uidex-states.json";
 var DEFAULT_COVERAGE_BASELINE = "uidex-coverage-baseline.json";
 function loadCoverageBaseline(configDir, config) {
   const rel = config.coverageBaseline ?? DEFAULT_COVERAGE_BASELINE;
-  const abs = path8.resolve(configDir, rel);
+  const abs = path9.resolve(configDir, rel);
   let raw;
   try {
     raw = fs5.readFileSync(abs, "utf8");
   } catch {
-    return {};
+    return void 0;
   }
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    return {};
+    return void 0;
   }
-  const legacy = migrateLegacyBaseline({
-    path: abs,
-    raw,
-    parsed,
-    displayPath: rel
-  });
-  if (legacy) return { legacy };
-  return { baseline: parseCoverageBaseline(parsed) ?? void 0 };
+  return parseCoverageBaseline(parsed) ?? void 0;
 }
 function loadCapturedStates(configDir, config) {
   const rel = config.statesManifest ?? DEFAULT_STATES_MANIFEST2;
-  const abs = path8.resolve(configDir, rel);
+  const abs = path9.resolve(configDir, rel);
   let raw;
   try {
     raw = fs5.readFileSync(abs, "utf8");
@@ -4642,11 +5002,11 @@ function runOne(dc, opts) {
     gitContext
   });
   const typesRel = config.output;
-  const typesPath = path8.resolve(configDir, typesRel);
+  const typesPath = path9.resolve(configDir, typesRel);
   const dataRel = dataOutputPath(config.output);
-  const dataPath = path8.resolve(configDir, dataRel);
+  const dataPath = path9.resolve(configDir, dataRel);
   const locsRel = locsOutputPath(config.output);
-  const locsPath = path8.resolve(configDir, locsRel);
+  const locsPath = path9.resolve(configDir, locsRel);
   let typesOnDisk = null;
   let dataOnDisk = null;
   let locsOnDisk = null;
@@ -4659,11 +5019,10 @@ function runOne(dc, opts) {
     (ef) => (ef.diagnostics?.length ?? 0) > 0
   );
   const capturedStates = opts.capturedStates ?? loadCapturedStates(configDir, config);
-  const loadedBaseline = opts.coverageBaseline ? { baseline: opts.coverageBaseline } : loadCoverageBaseline(configDir, config);
-  const coverageBaseline = loadedBaseline.baseline;
+  const coverageBaseline = opts.coverageBaseline ?? loadCoverageBaseline(configDir, config);
   const workspace = opts.workspace ?? resolveWorkspace({ configDir, config });
   let auditResult;
-  if (opts.check || opts.lint || resolved.diagnostics.length > 0 || hasExtractDiagnostics || loadedBaseline.legacy) {
+  if (opts.check || opts.lint || resolved.diagnostics.length > 0 || hasExtractDiagnostics) {
     auditResult = audit({
       registry: resolved.registry,
       extracted,
@@ -4687,7 +5046,6 @@ function runOne(dc, opts) {
       locsOutputPath: locsRel,
       capturedStates,
       coverageBaseline,
-      baselineDiagnostic: loadedBaseline.legacy,
       workspace
     });
   }
@@ -4716,7 +5074,7 @@ function readOrNull(p2) {
 }
 function writeArtifact(artifact) {
   if (readOrNull(artifact.outputPath) === artifact.generated) return false;
-  fs5.mkdirSync(path8.dirname(artifact.outputPath), { recursive: true });
+  fs5.mkdirSync(path9.dirname(artifact.outputPath), { recursive: true });
   fs5.writeFileSync(artifact.outputPath, artifact.generated, "utf8");
   return true;
 }
@@ -4728,7 +5086,7 @@ function writeScanResult(result) {
 }
 function coverageBaselinePath(result) {
   const rel = result.config.coverageBaseline ?? DEFAULT_COVERAGE_BASELINE;
-  return path8.resolve(result.configDir, rel);
+  return path9.resolve(result.configDir, rel);
 }
 
 // src/scanner/scan/states-merge.ts
@@ -4764,7 +5122,7 @@ function mergeStates(committed, partial) {
 
 // src/scanner/scan/fix.ts
 var fs6 = __toESM(require("fs"), 1);
-var path9 = __toESM(require("path"), 1);
+var path10 = __toESM(require("path"), 1);
 function applyFixes(diagnostics) {
   const entries = [];
   for (const d of diagnostics) {
@@ -4823,10 +5181,10 @@ function applyFixes(diagnostics) {
     if (entry.skippedReason) continue;
     for (const create of entry.createFiles) {
       if (fs6.existsSync(create.path)) {
-        entry.skippedReason = `${path9.basename(create.path)} already exists`;
+        entry.skippedReason = `${path10.basename(create.path)} already exists`;
         continue;
       }
-      fs6.mkdirSync(path9.dirname(create.path), { recursive: true });
+      fs6.mkdirSync(path10.dirname(create.path), { recursive: true });
       fs6.writeFileSync(create.path, create.content, "utf8");
     }
     if (entry.skippedReason) continue;
@@ -5011,23 +5369,23 @@ function renameEntity(opts) {
 
 // src/scanner/scan/cli.ts
 var fs9 = __toESM(require("fs"), 1);
-var path12 = __toESM(require("path"), 1);
+var path13 = __toESM(require("path"), 1);
 
 // src/scanner/scan/ai/index.ts
 var p = __toESM(require("@clack/prompts"), 1);
 
 // src/scanner/scan/ai/providers/claude.ts
 var fs8 = __toESM(require("fs"), 1);
-var path11 = __toESM(require("path"), 1);
+var path12 = __toESM(require("path"), 1);
 
 // src/scanner/scan/ai/templates.ts
 var fs7 = __toESM(require("fs"), 1);
-var path10 = __toESM(require("path"), 1);
+var path11 = __toESM(require("path"), 1);
 function templatePath(rel) {
   const candidates = [
-    path10.resolve(__dirname, "../../templates", rel),
+    path11.resolve(__dirname, "../../templates", rel),
     // dist/cli/cli.cjs         → ../../templates
-    path10.resolve(__dirname, "../../../../templates", rel)
+    path11.resolve(__dirname, "../../../../templates", rel)
     // src/scanner/scan/ai → ../../../../templates
   ];
   for (const c of candidates) {
@@ -5075,7 +5433,7 @@ var claudeProvider = {
   async install({ cwd, force }) {
     const changes = [];
     for (const file of SKILL_FILES) {
-      const dest = path11.join(cwd, file.dest);
+      const dest = path12.join(cwd, file.dest);
       const exists = fs8.existsSync(dest);
       if (exists && !force) {
         changes.push({
@@ -5085,7 +5443,7 @@ var claudeProvider = {
         });
         continue;
       }
-      fs8.mkdirSync(path11.dirname(dest), { recursive: true });
+      fs8.mkdirSync(path12.dirname(dest), { recursive: true });
       fs8.writeFileSync(dest, readTemplate(file.template));
       changes.push({
         path: file.dest,
@@ -5093,21 +5451,21 @@ var claudeProvider = {
       });
     }
     for (const rel of LEGACY_FILES) {
-      const dest = path11.join(cwd, rel);
+      const dest = path12.join(cwd, rel);
       if (fs8.existsSync(dest)) {
         fs8.unlinkSync(dest);
         changes.push({ path: rel, action: "removed" });
       }
     }
-    cleanupEmpty(path11.join(cwd, ".claude/commands/uidex"));
-    cleanupEmpty(path11.join(cwd, ".claude/commands"));
-    cleanupEmpty(path11.join(cwd, ".claude/rules"));
+    cleanupEmpty(path12.join(cwd, ".claude/commands/uidex"));
+    cleanupEmpty(path12.join(cwd, ".claude/commands"));
+    cleanupEmpty(path12.join(cwd, ".claude/rules"));
     return { changes };
   },
   async uninstall({ cwd }) {
     const changes = [];
     for (const file of SKILL_FILES) {
-      const dest = path11.join(cwd, file.dest);
+      const dest = path12.join(cwd, file.dest);
       if (!fs8.existsSync(dest)) {
         changes.push({ path: file.dest, action: "skipped", reason: "absent" });
         continue;
@@ -5115,19 +5473,19 @@ var claudeProvider = {
       fs8.unlinkSync(dest);
       changes.push({ path: file.dest, action: "removed" });
     }
-    cleanupEmpty(path11.join(cwd, ".claude/skills/uidex/references"));
-    cleanupEmpty(path11.join(cwd, ".claude/skills/uidex"));
-    cleanupEmpty(path11.join(cwd, ".claude/skills"));
+    cleanupEmpty(path12.join(cwd, ".claude/skills/uidex/references"));
+    cleanupEmpty(path12.join(cwd, ".claude/skills/uidex"));
+    cleanupEmpty(path12.join(cwd, ".claude/skills"));
     for (const rel of LEGACY_FILES) {
-      const dest = path11.join(cwd, rel);
+      const dest = path12.join(cwd, rel);
       if (fs8.existsSync(dest)) {
         fs8.unlinkSync(dest);
         changes.push({ path: rel, action: "removed" });
       }
     }
-    cleanupEmpty(path11.join(cwd, ".claude/commands/uidex"));
-    cleanupEmpty(path11.join(cwd, ".claude/commands"));
-    cleanupEmpty(path11.join(cwd, ".claude/rules"));
+    cleanupEmpty(path12.join(cwd, ".claude/commands/uidex"));
+    cleanupEmpty(path12.join(cwd, ".claude/commands"));
+    cleanupEmpty(path12.join(cwd, ".claude/rules"));
     return { changes };
   }
 };
@@ -5340,7 +5698,7 @@ function helpText2() {
     "  --check               Verify the on-disk gen file matches a fresh scan; exit non-zero on drift (read-only)",
     "  --lint                Run lint diagnostics (missing annotations, scope leak, duplicate ids, coverage)",
     "  --audit               Equivalent to --check --lint (read-only)",
-    "  --fix                 Apply machine-generated fixes (add data-uidex to unannotated interactive elements, drop empty names, migrate waivers/capture to acknowledge), then rescan and write",
+    "  --fix                 Apply machine-generated fixes (add data-uidex to unannotated interactive elements, drop empty names), then rescan and write",
     "  --update-baseline     Regenerate the coverage baseline (uidex-coverage-baseline.json) as `acknowledge` backlog entries",
     "  --json                Emit JSON diagnostics on stdout",
     "  --force               (scaffold) overwrite existing spec",
@@ -5348,7 +5706,7 @@ function helpText2() {
   ].join("\n");
 }
 function runInit(cwd, w) {
-  const configPath = path12.join(cwd, CONFIG_FILENAME);
+  const configPath = path13.join(cwd, CONFIG_FILENAME);
   if (fs9.existsSync(configPath)) {
     w.err(`.uidex.json already exists at ${configPath}`);
     return w.result(1);
@@ -5360,7 +5718,7 @@ function runInit(cwd, w) {
   };
   fs9.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   w.out(`Created ${configPath}`);
-  const gitignorePath = path12.join(cwd, ".gitignore");
+  const gitignorePath = path13.join(cwd, ".gitignore");
   const entry = "*.gen.*";
   if (fs9.existsSync(gitignorePath)) {
     const existing = fs9.readFileSync(gitignorePath, "utf8");
@@ -5418,7 +5776,7 @@ function runScanCommand(cwd, flags, w) {
       const acknowledge = {};
       const merge = (from) => {
         for (const [route, scopes] of Object.entries(from)) {
-          acknowledge[route] = { ...acknowledge[route] ?? {}, ...scopes };
+          acknowledge[route] = { ...acknowledge[route], ...scopes };
         }
       };
       merge(computePageBacklog(r.registry, manifest));
@@ -5506,7 +5864,7 @@ function runScaffold(cwd, args, flags, w) {
   for (const r of results) {
     const entity = r.registry.get(scaffoldKind, id);
     if (!entity) continue;
-    const outDir = path12.resolve(r.configDir, "e2e");
+    const outDir = path13.resolve(r.configDir, "e2e");
     const result = scaffoldSpec({
       registry: r.registry,
       kind: scaffoldKind,
@@ -5541,8 +5899,8 @@ function runStates(cwd, args, w) {
   let merged = 0;
   for (const { configDir, config } of configs) {
     const rel = config.statesManifest ?? "uidex-states.json";
-    const target = path12.resolve(configDir, rel);
-    const partial = explicitPartial ? path12.resolve(cwd, explicitPartial) : target.replace(/\.json$/i, "") + ".partial.json";
+    const target = path13.resolve(configDir, rel);
+    const partial = explicitPartial ? path13.resolve(cwd, explicitPartial) : target.replace(/\.json$/i, "") + ".partial.json";
     const committedRaw = readJson(target);
     const partialRaw = readJson(partial);
     if (!partialRaw) continue;
@@ -5554,7 +5912,7 @@ function runStates(cwd, args, w) {
     fs9.writeFileSync(target, JSON.stringify(result.manifest, null, 2) + "\n");
     merged++;
     w.out(
-      `Merged ${path12.basename(partial)} \u2192 ${rel}: ${result.added.length} added, ${result.updated.length} updated, ${result.manifest.captured.length} total`
+      `Merged ${path13.basename(partial)} \u2192 ${rel}: ${result.added.length} added, ${result.updated.length} updated, ${result.manifest.captured.length} total`
     );
     for (const k of result.added) w.out(`  + ${k}`);
     for (const k of result.updated) w.out(`  ~ ${k}`);
@@ -5647,13 +6005,9 @@ function createWriter() {
   extractUidexExports,
   findWorkspaceRoot,
   globToRegExp,
-  isLegacyBaseline,
   loadCoverageBaseline,
   matchUrlToRoute,
   mergeStates,
-  migrateBaseline,
-  migrateLegacyBaseline,
-  migrateLegacyFields,
   parseConfig,
   parseCoverageBaseline,
   pathToId,