uidex 0.9.0 → 0.11.0

package/dist/scan/index.js

@@ -27,10 +27,12 @@ var ALLOWED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "exclude",
   "output",
   "flows",
+  "resolve",
   "audit",
   "conventions",
   "statesManifest",
-  "coverageBaseline"
+  "coverageBaseline",
+  "workspace"
 ]);
 var ALLOWED_SOURCE_KEYS = /* @__PURE__ */ new Set(["rootDir", "include", "exclude", "prefix"]);
 var ALLOWED_CONVENTIONS_KEYS = /* @__PURE__ */ new Set([
@@ -44,21 +46,74 @@ var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set([
   "scopeLeak",
   "coverage",
   "acceptance",
+  "surfaces",
+  "requireAcceptance",
   "states",
   "pageCoverage",
-  "stateMatrix"
+  "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",
+  "matrix-backlog",
+  "missing-element-annotation",
+  "missing-state-capture",
+  "orphan-state-capture",
+  "page-backlog",
+  "page-captured",
+  "page-no-capture",
+  "parse-error",
+  "placeholder-reason",
+  "prefer-well-known-file",
+  "rename",
+  "scope-leak",
+  "spread-attr",
+  "stale-acknowledgment",
+  "stale-page-baseline",
+  "uidex-export-ambiguous-kind",
+  "uidex-export-duplicate-field",
+  "uidex-export-duplicate-state",
+  "uidex-export-empty-name",
+  "uidex-export-invalid-field",
+  "uidex-export-invalid-literal",
+  "uidex-export-missing-kind",
+  "uidex-export-satisfies-mismatch",
+  "uidex-export-unknown-field",
+  "unknown-reference",
+  "widget-id-mismatch",
+  "widget-missing-acceptance",
+  "widget-missing-dom"
+];
+var DIAGNOSTIC_CODE_SET = new Set(DIAGNOSTIC_CODES);
+var SEVERITY_LEVELS = /* @__PURE__ */ new Set(["error", "warning", "info", "off"]);
 function fail(msg) {
   throw new ConfigError(`Invalid .uidex.json: ${msg}`);
 }
-function assertObject(value, path12) {
+function assertObject(value, path14) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    fail(`${path12} must be an object`);
+    fail(`${path14} must be an object`);
   }
 }
-function assertStringArray(value, path12) {
+function assertStringArray(value, path14) {
   if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
-    fail(`${path12} must be a string[]`);
+    fail(`${path14} must be a string[]`);
   }
 }
 function validateConfig(raw) {
@@ -112,11 +167,47 @@ function validateConfig(raw) {
   if (raw.coverageBaseline !== void 0 && typeof raw.coverageBaseline !== "string") {
     fail(`"coverageBaseline" must be a string`);
   }
+  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)) {
       if (!ALLOWED_AUDIT_KEYS.has(key)) fail(`unknown key "${key}" in audit`);
       const v = raw.audit[key];
+      if (key === "severity") {
+        assertObject(v, "audit.severity");
+        for (const [code, level] of Object.entries(v)) {
+          if (!DIAGNOSTIC_CODE_SET.has(code)) {
+            fail(
+              `unknown diagnostic code "${code}" in audit.severity (a typo here would silently leave that gate at its default severity)`
+            );
+          }
+          if (typeof level !== "string" || !SEVERITY_LEVELS.has(level)) {
+            fail(
+              `audit.severity["${code}"] must be one of "error", "warning", "info", "off"`
+            );
+          }
+        }
+        continue;
+      }
       if (typeof v !== "boolean") fail(`audit.${key} must be a boolean`);
     }
   }
@@ -156,10 +247,12 @@ function validateConfig(raw) {
     exclude: raw.exclude,
     output: raw.output,
     flows: raw.flows,
+    resolve: raw.resolve,
     audit: raw.audit,
     conventions: raw.conventions,
     statesManifest: raw.statesManifest,
-    coverageBaseline: raw.coverageBaseline
+    coverageBaseline: raw.coverageBaseline,
+    workspace: raw.workspace
   };
 }
 function parseConfig(json) {
@@ -209,9 +302,11 @@ function tryReadConfig(configPath) {
 function discover(options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const maxDepth = options.maxDepth ?? MAX_DEPTH;
+  const all = options.all ?? false;
   const rootMatch = tryReadConfig(path.join(cwd, CONFIG_FILENAME));
-  if (rootMatch) return [rootMatch];
+  if (rootMatch && !all) return [rootMatch];
   const results = [];
+  if (rootMatch) results.push(rootMatch);
   const queue = [[cwd, 0]];
   while (queue.length > 0) {
     const [dir, depth] = queue.shift();
@@ -315,6 +410,26 @@ function toPosix(p2) {
 function matchesAny(rel, patterns) {
   return patterns.some((g) => globToRegExp(g).test(rel));
 }
+function createSourceMatcher(sources, options) {
+  const { cwd, globalExcludes = [], includeTests = false } = options;
+  const baseDefaults = includeTests ? BASE_EXCLUDES : DEFAULT_EXCLUDES;
+  const compiled = sources.map((source) => ({
+    absRoot: path2.resolve(cwd, source.rootDir),
+    includes: source.include?.length ? source.include : DEFAULT_INCLUDES,
+    excludes: [...baseDefaults, ...globalExcludes, ...source.exclude ?? []]
+  }));
+  return (absFile) => {
+    const abs = path2.resolve(absFile);
+    return compiled.some(({ absRoot, includes, excludes }) => {
+      const rel = toPosix(path2.relative(absRoot, abs));
+      if (rel.length === 0 || rel.startsWith("../") || path2.isAbsolute(rel)) {
+        return false;
+      }
+      if (matchesAny(rel, excludes)) return false;
+      return matchesAny(rel, includes);
+    });
+  };
+}
 function walk(sources, options) {
   const { cwd, globalExcludes = [], includeTests = false } = options;
   const out2 = [];
@@ -648,6 +763,109 @@ function createRegistry() {
   };
 }
 
+// src/scanner/scan/acknowledge.ts
+var ACK_ALL = "*";
+var ACK_SCOPES = [ACK_ALL, ...CORE_STATE_KINDS];
+var COMPONENT_ACK_SCOPES = [ACK_ALL];
+var AUTHORABLE_ACK_TYPES = [
+  "impossible",
+  "backlog"
+];
+var CORE_SET = new Set(CORE_STATE_KINDS);
+function isCoreKind(scope) {
+  return CORE_SET.has(scope);
+}
+function isPlaceholderReason(reason) {
+  return typeof reason === "string" && /^\s*TODO\b/i.test(reason);
+}
+function describeAck(a) {
+  if (a.type === "captured-elsewhere") {
+    return a.by ? `captured-elsewhere (${a.by})` : "captured-elsewhere";
+  }
+  return a.reason ? `${a.type} ("${a.reason}")` : a.type;
+}
+function originHint(a, page) {
+  if (a.origin === "baseline") {
+    return "Prune it with `uidex scan --update-baseline` so the backlog reflects reality.";
+  }
+  if (a.origin === "workspace") {
+    return "This is computed from the workspace; it resolves itself once the sibling capture changes.";
+  }
+  const where = page ? ` on page "${page}"` : "";
+  return `Remove the \`acknowledge.${a.scope}\` entry${where} \u2014 a capture contradicts it.`;
+}
+function toResolved(map, origin, into) {
+  for (const [scope, ack] of Object.entries(map ?? {})) {
+    into.set(scope, { ...ack, scope, origin });
+  }
+}
+function routeAcknowledge(registry, baseline, route, page) {
+  const out2 = /* @__PURE__ */ new Map();
+  toResolved(baseline?.acknowledge?.[route], "baseline", out2);
+  if (page) {
+    toResolved(registry.get("page", page)?.meta?.acknowledge, "source", out2);
+  }
+  return out2;
+}
+function entityAcknowledge(meta, capturedElsewhereBy) {
+  const source = meta?.acknowledge?.[ACK_ALL];
+  if (source) return { ...source, scope: ACK_ALL, origin: "source" };
+  if (capturedElsewhereBy) {
+    return {
+      type: "captured-elsewhere",
+      by: capturedElsewhereBy,
+      scope: ACK_ALL,
+      origin: "workspace"
+    };
+  }
+  return void 0;
+}
+function readAck(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const r = raw;
+  if (r.type !== "impossible" && r.type !== "backlog") return void 0;
+  const out2 = { type: r.type };
+  if (typeof r.reason === "string" && r.reason.length > 0) out2.reason = r.reason;
+  return out2;
+}
+function parseCoverageBaseline(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const r = raw;
+  const ackRaw = r.acknowledge;
+  if (!ackRaw || typeof ackRaw !== "object" || Array.isArray(ackRaw))
+    return null;
+  const acknowledge = {};
+  for (const [route, scopesRaw] of Object.entries(
+    ackRaw
+  )) {
+    if (!scopesRaw || typeof scopesRaw !== "object" || Array.isArray(scopesRaw))
+      continue;
+    const scopes = {};
+    for (const [scope, ackVal] of Object.entries(
+      scopesRaw
+    )) {
+      if (scope !== ACK_ALL && !isCoreKind(scope)) continue;
+      const ack = readAck(ackVal);
+      if (ack) scopes[scope] = ack;
+    }
+    if (Object.keys(scopes).length > 0) acknowledge[route] = scopes;
+  }
+  return { version: 2, acknowledge };
+}
+function serializeCoverageBaseline(baseline) {
+  const routes = Object.keys(baseline.acknowledge).sort();
+  const ordered = {};
+  for (const route of routes) {
+    const scopes = baseline.acknowledge[route];
+    const sorted = {};
+    for (const scope of ACK_SCOPES) {
+      if (scopes[scope]) sorted[scope] = scopes[scope];
+    }
+    ordered[route] = sorted;
+  }
+  return JSON.stringify({ version: 2, acknowledge: ordered }, null, 2) + "\n";
+}
+
 // src/scanner/scan/extract-uidex-export.ts
 var KIND_DISCRIMINATORS = [
   "page",
@@ -666,33 +884,44 @@ var ALLOWED_FIELDS = {
     "widgets",
     "acceptance",
     "states",
-    "capture",
-    "waivers",
+    "acknowledge",
     "description"
   ]),
-  // `capture` / `waivers` are route-scoped, and only a page maps to a route — so
-  // they are page-only (the gates read them off the page). A feature/widget that
-  // sets them gets an `uidex-export-unknown-field` error rather than a silent no-op.
+  // 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.
   feature: /* @__PURE__ */ new Set([
     "feature",
     "name",
     "features",
+    "surfaces",
     "acceptance",
     "states",
+    "acknowledge",
     "description"
   ]),
   primitive: /* @__PURE__ */ new Set(["primitive", "name", "description"]),
-  widget: /* @__PURE__ */ new Set(["widget", "name", "acceptance", "states", "description"]),
+  widget: /* @__PURE__ */ new Set([
+    "widget",
+    "name",
+    "acceptance",
+    "states",
+    "acknowledge",
+    "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",
@@ -936,7 +1165,8 @@ function objectLit(node, content, p2, pos, span) {
       key,
       value,
       keyPos,
-      span: removalSpan(content, prop.start, prop.end)
+      span: removalSpan(content, prop.start, prop.end),
+      propSpan: { start: prop.start, end: prop.end }
     });
   }
   return { kind: "object", entries, pos, span };
@@ -1057,7 +1287,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 === "") {
@@ -1083,9 +1314,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 capture = kind === "page" ? readBooleanField(byKey, "capture") : void 0;
-  const waivers = kind === "page" ? readWaiversField(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 notFlow = kind === "flow" && discriminator === "notFlow" ? true : void 0;
   const metadata = {
     source: "ts-export",
@@ -1108,16 +1340,26 @@ 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 (capture !== void 0) metadata.capture = capture;
-  if (waivers && Object.keys(waivers).length > 0) metadata.waivers = waivers;
+  if (acknowledge && Object.keys(acknowledge).length > 0) {
+    metadata.acknowledge = acknowledge;
+  }
   if (notFlow) metadata.notFlow = true;
   if (typeof id === "string" && idValue.kind === "string") {
     metadata.idSpan = idValue.span;
   }
   const fieldSpans = {};
-  for (const entry of value.entries) fieldSpans[entry.key] = entry.span;
+  const fieldPropSpans = {};
+  for (const entry of value.entries) {
+    fieldSpans[entry.key] = entry.span;
+    fieldPropSpans[entry.key] = entry.propSpan;
+  }
   metadata.fieldSpans = fieldSpans;
+  metadata.fieldPropSpans = fieldPropSpans;
   return metadata;
 }
 function readIdField(value, kind, fieldName) {
@@ -1147,47 +1389,185 @@ function readIdField(value, kind, fieldName) {
     value.pos
   );
 }
-function readWaiversField(byKey) {
-  const entry = byKey.get("waivers");
+function readAcknowledgeField(byKey, isPage) {
+  const entry = byKey.get("acknowledge");
   if (!entry) return void 0;
   if (entry.value.kind !== "object") {
     throw new ExtractError(
       "uidex-export-invalid-field",
-      "`waivers` must be an object mapping a core kind to a reason.",
+      '`acknowledge` must be an object mapping a scope (`"*"` or a core kind) to `{ type, reason? }`.',
       entry.value.pos
     );
   }
-  const waivers = {};
+  const out2 = {};
   for (const e of entry.value.entries) {
-    if (!CORE_STATE_KINDS2.has(e.key)) {
+    const scopes = isPage ? ACK_SCOPES : COMPONENT_ACK_SCOPES;
+    if (!scopes.includes(e.key)) {
       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.`,
+        `acknowledge scope "${e.key}" is not valid here; expected ${scopes.map((s) => `"${s}"`).join(", ")}${isPage ? "" : " (core-kind scopes are page-only \u2014 the state matrix is route-scoped)"}.`,
         e.keyPos
       );
     }
-    if (e.value.kind !== "string" || e.value.value.length === 0) {
+    if (e.value.kind !== "object") {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `acknowledge "${e.key}" must be an object \`{ type, reason? }\`.`,
+        e.value.pos
+      );
+    }
+    const fieldByKey = /* @__PURE__ */ new Map();
+    for (const f of e.value.entries) {
+      if (!ACK_FIELDS.has(f.key)) {
+        throw new ExtractError(
+          "uidex-export-invalid-field",
+          `Unknown field "${f.key}" in an \`acknowledge\` entry. Allowed: ${[...ACK_FIELDS].sort().join(", ")}.`,
+          f.value.pos
+        );
+      }
+      fieldByKey.set(f.key, f);
+    }
+    const type = readStringField(fieldByKey, "type");
+    if (type === void 0) {
       throw new ExtractError(
         "uidex-export-invalid-field",
-        `waiver "${e.key}" needs a non-empty reason (why the route cannot render this kind).`,
+        `acknowledge "${e.key}" needs a \`type\`: ${AUTHORABLE_ACK_TYPES.map((t) => `"${t}"`).join(" or ")}.`,
         e.value.pos
       );
     }
-    waivers[e.key] = e.value.value;
+    if (type === "captured-elsewhere") {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        '`type: "captured-elsewhere"` cannot be authored; the workspace computes it from the sibling app that captured the declaration.',
+        fieldByKey.get("type").value.pos,
+        "Remove the entry \u2014 if a sibling app really captures this, the workspace reports it as `acknowledged-elsewhere` on its own."
+      );
+    }
+    if (type !== "impossible" && type !== "backlog") {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `acknowledge \`type\` must be ${AUTHORABLE_ACK_TYPES.map((t) => `"${t}"`).join(" or ")} (got "${type}").`,
+        fieldByKey.get("type").value.pos
+      );
+    }
+    const reason = readStringField(fieldByKey, "reason");
+    if (type === "impossible" && (reason === void 0 || reason.length === 0)) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `acknowledge "${e.key}" is \`type: "impossible"\` and needs a non-empty \`reason\` (why this can NEVER be rendered/captured).`,
+        e.value.pos,
+        'If it merely has not been captured yet, that is `type: "backlog"` \u2014 which needs no reason.'
+      );
+    }
+    out2[e.key] = reason ? { type, reason } : { type };
   }
-  return waivers;
+  return out2;
 }
-function readBooleanField(byKey, name) {
-  const entry = byKey.get(name);
+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 !== "boolean") {
+  return readAcceptanceItems(entry, seen);
+}
+function readAcceptanceItems(entry, seen) {
+  if (entry.value.kind !== "array") {
     throw new ExtractError(
       "uidex-export-invalid-field",
-      `\`${name}\` must be a boolean.`,
+      "`acceptance` must be an array of strings or `{ id, rev?, text }` objects.",
       entry.value.pos
     );
   }
-  return entry.value.value;
+  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",
+        "`acceptance` items must be strings or `{ id, rev?, text }` objects.",
+        item.pos
+      );
+    }
+    if (seen.has(criterion.id)) {
+      throw new ExtractError(
+        "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."
+      );
+    }
+    seen.add(criterion.id);
+    criteria.push(criterion);
+  }
+  return criteria;
 }
 function readStringField(byKey, name) {
   const entry = byKey.get(name);
@@ -1226,7 +1606,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") {
@@ -1276,8 +1656,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 {
@@ -1333,20 +1716,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;
@@ -1357,13 +1741,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 ?? []) {
@@ -1755,11 +2209,13 @@ function extract(files) {
     const out2 = { file, annotations: [] };
     out2.annotations = extractOne(file, parsed, out2);
     if (exports.length > 0) out2.metadata = exports;
+    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;
   });
 }
@@ -1784,6 +2240,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 = [];
@@ -1816,6 +2298,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;
 }
 
@@ -1987,6 +2484,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,
@@ -1995,9 +2493,8 @@ function buildMetaFromExport(exp) {
       ...s.description ? { description: s.description } : {}
     }));
   }
-  if (exp.capture === false) meta.capture = false;
-  if (exp.waivers && Object.keys(exp.waivers).length > 0) {
-    meta.waivers = exp.waivers;
+  if (exp.acknowledge && Object.keys(exp.acknowledge).length > 0) {
+    meta.acknowledge = exp.acknowledge;
   }
   return Object.keys(meta).length > 0 ? meta : void 0;
 }
@@ -2342,6 +2839,45 @@ function resolve2(ctx) {
     };
     registry.add(element);
   }
+  const ancestorsById = /* @__PURE__ */ new Map();
+  const fileById = /* @__PURE__ */ new Map();
+  for (const a of allAnnotations) {
+    if (!fileById.has(a.id)) fileById.set(a.id, a.file);
+    if (a.ancestors?.length) {
+      const prev = ancestorsById.get(a.id) ?? [];
+      ancestorsById.set(a.id, [...prev, ...a.ancestors.map((x) => x.id)]);
+    }
+  }
+  const ownersByFile = /* @__PURE__ */ new Map();
+  const addOwner = (file, id) => {
+    ownersByFile.set(file, [...ownersByFile.get(file) ?? [], id]);
+  };
+  const featureDirs = [];
+  for (const f of registry.list("feature")) {
+    const loc = f.loc?.file;
+    if (!loc) continue;
+    const dir = loc.endsWith("/") ? loc.slice(0, -1) : path4.posix.dirname(loc);
+    featureDirs.push({ dir, id: f.id });
+  }
+  for (const p2 of registry.list("page")) {
+    if (p2.loc?.file) addOwner(p2.loc.file, p2.id);
+  }
+  const ownersFor = (file) => {
+    const out2 = [...ownersByFile.get(file) ?? []];
+    for (const { dir, id } of featureDirs) {
+      if (file === dir || file.startsWith(`${dir}/`)) out2.push(id);
+    }
+    return out2;
+  };
+  const expandTouches = (ids) => {
+    const out2 = new Set(ids);
+    for (const id of ids) {
+      for (const anc of ancestorsById.get(id) ?? []) out2.add(anc);
+      const file = fileById.get(id);
+      if (file) for (const owner of ownersFor(file)) out2.add(owner);
+    }
+    return [...out2];
+  };
   if (ctx.flowFiles && conventions.flows) {
     for (const ff of ctx.flowFiles) {
       const notFlowExport = (ff.metadata ?? []).find(
@@ -2351,7 +2887,10 @@ function resolve2(ctx) {
       const flowExport = (ff.metadata ?? []).find(
         (m) => m.kind === "flow" && typeof m.id === "string"
       );
-      const derived = flowsFromFacts(ff);
+      const derived = flowsFromFacts(ff).map((f) => ({
+        ...f,
+        touches: expandTouches(f.touches)
+      }));
       if (flowExport && typeof flowExport.id === "string" && derived.length === 1) {
         const base = derived[0];
         const flow = {
@@ -2359,7 +2898,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 {
@@ -2407,20 +2947,95 @@ 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
-import * as path5 from "path";
+import * as path7 from "path";
+
+// src/scanner/scan/component-coverage.ts
+var COMPOSED_KINDS = ["widget", "feature"];
+function composedStateEntities(registry, page) {
+  const meta = registry.get("page", page)?.meta;
+  if (!meta) return [];
+  const out2 = [];
+  for (const kind of COMPOSED_KINDS) {
+    const ids = (kind === "widget" ? meta.widgets : meta.features) ?? [];
+    for (const id of ids) {
+      const e = registry.get(kind, id);
+      if (!e?.meta?.states?.length) continue;
+      if (e.meta.acknowledge?.[ACK_ALL]) continue;
+      out2.push({ kind, id });
+    }
+  }
+  return out2;
+}
+function capturedStatesFor(captured, kind, id) {
+  const out2 = /* @__PURE__ */ new Set();
+  for (const c of captured) {
+    if (c.entity !== id) continue;
+    if (c.kind !== void 0 && c.kind !== kind && c.kind !== "page") continue;
+    out2.add(c.state);
+  }
+  return out2;
+}
+function checkComponentCoverage(registry, manifest) {
+  const routes = registry.list("route");
+  if (routes.length === 0) return [];
+  const captured = manifest.captured ?? [];
+  const diagnostics = [];
+  for (const route of routes) {
+    if (registry.get("page", route.page)?.meta?.acknowledge?.[ACK_ALL]) continue;
+    for (const { kind, id } of composedStateEntities(registry, route.page)) {
+      const entity = registry.get(kind, id);
+      const declared = entity.meta.states.map((s) => s.name);
+      const shot = capturedStatesFor(captured, kind, id);
+      const missing = declared.filter((s) => !shot.has(s));
+      if (missing.length === 0) continue;
+      diagnostics.push({
+        code: "component-state-uncaptured",
+        severity: "info",
+        message: `route "${route.path}" composes ${kind} "${id}", whose state(s) [${missing.join(", ")}] no capture produced`,
+        file: entity.loc?.file,
+        line: entity.loc?.line,
+        entity: { kind, id },
+        hint: `Capture the missing state(s) for "${id}", or drop them from its \`states\` if they no longer exist. This is the integration view: an isolated component capture never proves the state renders correctly INSIDE "${route.path}".`
+      });
+    }
+  }
+  return diagnostics;
+}
 
 // src/scanner/scan/page-coverage.ts
 function compileRoute(pattern) {
@@ -2443,11 +3058,11 @@ function compileRoute(pattern) {
   return { test: (url) => re.test(url), specificity };
 }
 function matchUrlToRoute(url, routePaths) {
-  const path12 = stripQuery(url);
+  const path14 = stripQuery(url);
   let best = null;
   for (const rp of routePaths) {
     const { test, specificity } = compileRoute(rp);
-    if (!test(path12)) continue;
+    if (!test(path14)) continue;
     if (!best || specificity > best.specificity)
       best = { path: rp, specificity };
   }
@@ -2478,29 +3093,49 @@ function checkPageCoverage(registry, manifest, baseline) {
   if (routes.length === 0) return [];
   const routePaths = routes.map((r) => r.path);
   const captured = manifest.captured ?? [];
-  const optedOut = /* @__PURE__ */ new Set();
-  for (const r of routes) {
-    const page = registry.get("page", r.page);
-    if (page?.meta?.capture === false) optedOut.add(r.path);
-  }
   const covered = /* @__PURE__ */ new Set();
   for (const c of captured) {
     const route = routeForCapture(c, routes, routePaths);
     if (route) covered.add(route);
   }
-  const baselineSet = new Set(baseline?.uncapturedPages ?? []);
   const diagnostics = [];
   for (const r of routes) {
-    if (covered.has(r.path) || optedOut.has(r.path)) continue;
+    const ack = routeAcknowledge(registry, baseline, r.path, r.page).get(
+      ACK_ALL
+    );
     const loc = registry.get("page", r.page)?.loc;
-    if (baselineSet.has(r.path)) {
+    if (covered.has(r.path)) {
+      if (ack?.type === "impossible") {
+        diagnostics.push({
+          code: "stale-acknowledgment",
+          severity: "warning",
+          message: `page "${r.page}" acknowledges "*" as ${describeAck(ack)}, but route "${r.path}" is captured`,
+          file: loc?.file,
+          line: loc?.line,
+          entity: { kind: "page", id: r.page },
+          hint: originHint(ack, r.page)
+        });
+      } else if (ack?.type === "backlog") {
+        diagnostics.push({
+          code: "page-captured",
+          severity: "warning",
+          message: `route "${r.path}" is now captured but is still acknowledged as backlog`,
+          file: loc?.file,
+          line: loc?.line,
+          hint: originHint(ack, r.page)
+        });
+      }
+      continue;
+    }
+    if (ack?.type === "impossible") continue;
+    if (ack?.type === "backlog") {
       diagnostics.push({
         code: "page-backlog",
         severity: "info",
         message: `route "${r.path}" has no visual-states capture (acknowledged backlog)`,
         file: loc?.file,
         line: loc?.line,
-        hint: `Capture it (drive the route in a states spec) and it drops off the baseline, or opt it out with \`export const uidex = { page: "${r.page}", capture: false }\`.`
+        hint: `Capture it (drive the route in a states spec) and it drops off the baseline, or \u2014 if it can NEVER be captured \u2014 say so with \`acknowledge: { "*": { type: "impossible", reason: "\u2026" } }\` on page "${r.page}".`
       });
       continue;
     }
@@ -2511,46 +3146,155 @@ function checkPageCoverage(registry, manifest, baseline) {
       file: loc?.file,
       line: loc?.line,
       entity: { kind: "route", id: r.path },
-      hint: `Capture the route in a states spec, opt it out with \`export const uidex = { page: "${r.page}", capture: false }\`, or grandfather it as acknowledged backlog with \`uidex scan --update-baseline\` (the baseline change lands in the diff for review).`
+      hint: `Capture the route in a states spec; or if it can NEVER be captured add \`acknowledge: { "*": { type: "impossible", reason: "why" } }\` to page "${r.page}"; or record it as debt with \`uidex scan --update-baseline\` (which writes \`{ type: "backlog" }\`, visible in the diff for review).`
+    });
+  }
+  for (const b of Object.keys(baseline?.acknowledge ?? {})) {
+    if (routePaths.includes(b)) continue;
+    diagnostics.push({
+      code: "stale-page-baseline",
+      severity: "warning",
+      message: `coverage baseline acknowledges "${b}", which is not a route in the registry`,
+      hint: `Remove it from the baseline (\`uidex scan --update-baseline\`); the route no longer exists.`
     });
   }
-  for (const b of baselineSet) {
-    if (!routePaths.includes(b)) {
-      diagnostics.push({
-        code: "stale-page-baseline",
-        severity: "warning",
-        message: `coverage baseline lists "${b}", which is not a route in the registry`,
-        hint: `Remove it from the baseline (\`uidex scan --update-baseline\`); the route no longer exists.`
-      });
-    } else if (covered.has(b) || optedOut.has(b)) {
-      diagnostics.push({
-        code: "page-captured",
-        severity: "warning",
-        message: `route "${b}" is now captured but is still in the coverage baseline`,
-        hint: `Prune it with \`uidex scan --update-baseline\` so the backlog reflects reality.`
-      });
-    }
-  }
   return diagnostics;
 }
-function computePageBaseline(registry, manifest) {
-  const uncaptured = [];
+function computePageBacklog(registry, manifest) {
+  const out2 = {};
   for (const d of checkPageCoverage(registry, manifest, {
-    uncapturedPages: []
+    version: 2,
+    acknowledge: {}
   })) {
-    if (d.code === "page-no-capture" && d.entity) uncaptured.push(d.entity.id);
+    if (d.code === "page-no-capture" && d.entity) {
+      out2[d.entity.id] = { [ACK_ALL]: { type: "backlog" } };
+    }
+  }
+  return out2;
+}
+
+// src/scanner/scan/workspace.ts
+import * as fs3 from "fs";
+import * as path5 from "path";
+var WORKSPACE_MARKERS = [
+  "pnpm-workspace.yaml",
+  "pnpm-workspace.yml",
+  "turbo.json",
+  "lerna.json",
+  "nx.json",
+  ".git"
+];
+var MAX_ASCENT = 8;
+var DEFAULT_STATES_MANIFEST = "uidex-states.json";
+function captureKey(kind, entity) {
+  return `${kind ?? ""}|${entity}`;
+}
+function hasMarker(dir) {
+  return WORKSPACE_MARKERS.some((m) => fs3.existsSync(path5.join(dir, m)));
+}
+function findWorkspaceRoot(configDir) {
+  let dir = path5.resolve(configDir);
+  for (let i = 0; i < MAX_ASCENT; i++) {
+    const parent = path5.dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+    if (hasMarker(dir)) return dir;
+  }
+  return void 0;
+}
+function captureKeys(manifest) {
+  const out2 = /* @__PURE__ */ new Set();
+  for (const c of manifest?.captured ?? []) {
+    out2.add(captureKey(c.kind, c.entity));
+  }
+  return out2;
+}
+function readManifest(configDir, config) {
+  const rel = config.statesManifest ?? DEFAULT_STATES_MANIFEST;
+  let raw;
+  try {
+    raw = fs3.readFileSync(path5.resolve(configDir, rel), "utf8");
+  } catch {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.captured)) return void 0;
+    const captured = [];
+    for (const entry of parsed.captured) {
+      if (!entry || typeof entry !== "object") continue;
+      const c = entry;
+      if (typeof c.entity !== "string" || typeof c.state !== "string") continue;
+      const rec = { entity: c.entity, state: c.state };
+      if (typeof c.kind === "string") rec.kind = c.kind;
+      captured.push(rec);
+    }
+    return { captured };
+  } catch {
+    return void 0;
+  }
+}
+function toApp(dc) {
+  return {
+    name: path5.basename(dc.configDir),
+    configDir: dc.configDir,
+    configPath: dc.configPath,
+    registers: createSourceMatcher(dc.config.sources, {
+      cwd: dc.configDir,
+      globalExcludes: dc.config.exclude
+    }),
+    captured: captureKeys(readManifest(dc.configDir, dc.config))
+  };
+}
+function resolveWorkspace(opts) {
+  const { configDir, config } = opts;
+  if (config.workspace === false) return void 0;
+  const root = typeof config.workspace === "string" ? path5.resolve(configDir, config.workspace) : findWorkspaceRoot(configDir);
+  if (!root) return void 0;
+  const configs = opts.configs ?? discover({ cwd: root, all: true });
+  const self = path5.resolve(configDir, CONFIG_FILENAME);
+  const siblings = configs.filter((dc) => path5.resolve(dc.configPath) !== self).map(toApp);
+  if (siblings.length === 0) return void 0;
+  return { root, siblings };
+}
+function capturedElsewhere(workspace, absFile, kind, id) {
+  if (!workspace || !absFile) return void 0;
+  for (const app of workspace.siblings) {
+    if (!app.registers(absFile)) continue;
+    if (app.captured.has(captureKey(kind, id)) || app.captured.has(captureKey(void 0, id))) {
+      return app.name;
+    }
   }
-  return { uncapturedPages: uncaptured.sort() };
+  return void 0;
 }
 
 // src/scanner/scan/state-coverage.ts
 var STATE_KINDS2 = ["page", "feature", "widget"];
-function declaredStateEntities(registry) {
+function declaredStateEntities(registry, opts, ungated) {
   const out2 = [];
   for (const kind of STATE_KINDS2) {
     for (const e of registry.list(kind)) {
       const states = e.meta?.states;
       if (!states || states.length === 0) continue;
+      const absFile = e.loc?.file ? opts.resolveSourcePath?.(e.loc.file) : void 0;
+      const ack = entityAcknowledge(
+        e.meta,
+        capturedElsewhere(opts.workspace, absFile, kind, e.id)
+      );
+      if (ack) {
+        if (ack.origin === "workspace") {
+          ungated.push({
+            code: "acknowledged-elsewhere",
+            severity: "info",
+            message: `${kind} "${e.id}" declares states that no capture here produced, but sibling app "${ack.by}" registers the same declaration and captured it (${describeAck(ack)})`,
+            file: e.loc?.file,
+            line: e.loc?.line,
+            entity: { kind, id: e.id },
+            hint: `This is the workspace answering, not a guess: "${ack.by}" sources the declaring file and its manifest has a capture for "${e.id}". Set \`workspace: false\` in .uidex.json to gate it here anyway.`
+          });
+        }
+        continue;
+      }
       out2.push({
         kind,
         id: e.id,
@@ -2561,18 +3305,31 @@ function declaredStateEntities(registry) {
   }
   return out2;
 }
-function captureMatchesEntity(cap, ent) {
+function unreliablePageKinds(registry, captured) {
+  const out2 = /* @__PURE__ */ new Set();
+  for (const c of captured) {
+    if (c.kind !== "page") continue;
+    if (registry.get("page", c.entity)) continue;
+    out2.add(c.entity);
+  }
+  return out2;
+}
+function captureMatchesEntity(cap, ent, unreliable = EMPTY) {
   if (cap.entity !== ent.id) return false;
-  return cap.kind === void 0 || cap.kind === ent.kind;
+  if (cap.kind === void 0) return true;
+  if (cap.kind === ent.kind) return true;
+  return cap.kind === "page" && unreliable.has(cap.entity);
 }
-function checkStateCoverage(registry, manifest) {
+var EMPTY = /* @__PURE__ */ new Set();
+function checkStateCoverage(registry, manifest, opts = {}) {
   const diagnostics = [];
-  const declared = declaredStateEntities(registry);
   const captured = manifest.captured ?? [];
+  const unreliable = unreliablePageKinds(registry, captured);
+  const declared = declaredStateEntities(registry, opts, diagnostics);
   for (const ent of declared) {
     for (const state of ent.states) {
       const hit = captured.some(
-        (c) => captureMatchesEntity(c, ent) && c.state === state
+        (c) => captureMatchesEntity(c, ent, unreliable) && c.state === state
       );
       if (hit) continue;
       diagnostics.push({
@@ -2587,7 +3344,9 @@ function checkStateCoverage(registry, manifest) {
     }
   }
   for (const cap of captured) {
-    const candidates = declared.filter((ent2) => captureMatchesEntity(cap, ent2));
+    const candidates = declared.filter(
+      (ent2) => captureMatchesEntity(cap, ent2, unreliable)
+    );
     if (candidates.length === 0) continue;
     const declaredSomewhere = candidates.some(
       (ent2) => ent2.states.includes(cap.state)
@@ -2631,36 +3390,35 @@ function coreKindsByRoute(registry, manifest) {
   }
   return byRoute;
 }
-function pageWaivers(registry, routePage) {
-  return registry.get("page", routePage)?.meta?.waivers ?? {};
-}
-function isOptedOut(registry, page) {
-  return page ? registry.get("page", page)?.meta?.capture === false : false;
-}
 function checkStateMatrix(registry, manifest, baseline) {
   const routes = registry.list("route");
   if (routes.length === 0) return [];
   const pageOf = new Map(routes.map((r) => [r.path, r.page]));
   const captured = coreKindsByRoute(registry, manifest);
-  const baselined = baseline?.missingKinds ?? {};
   const diagnostics = [];
   for (const [route, kinds] of captured) {
     const page = pageOf.get(route);
-    if (isOptedOut(registry, page)) continue;
-    const waivers = page ? pageWaivers(registry, page) : {};
+    const ack = routeAcknowledge(registry, baseline, route, page);
     const loc = page ? registry.get("page", page)?.loc : void 0;
-    const baselinedKinds = new Set(baselined[route] ?? []);
+    const all = ack.get(ACK_ALL);
+    if (all) {
+      if (all.type === "impossible") {
+        diagnostics.push(staleDiagnostic(all, route, page, loc));
+      }
+      continue;
+    }
     for (const kind of CORE_KINDS) {
       if (kinds.has(kind)) continue;
-      if (waivers[kind]) continue;
-      if (baselinedKinds.has(kind)) {
+      const entry = ack.get(kind);
+      if (entry?.type === "impossible") continue;
+      if (entry?.type === "backlog") {
         diagnostics.push({
           code: "matrix-backlog",
           severity: "info",
-          message: `route "${route}" does not render core kind "${kind}" (acknowledged MISSING_KINDS backlog)`,
+          message: `route "${route}" does not render core kind "${kind}" (acknowledged backlog)`,
           file: loc?.file,
           line: loc?.line,
-          hint: `Capture the "${kind}" state for "${route}", waive it (\`waivers: { ${kind}: "why it can't" }\` on the page), or leave it in the baseline.`
+          hint: `Capture the "${kind}" state for "${route}", or if the route CANNOT render it change the acknowledgment to \`{ type: "impossible", reason: "why it can't" }\`.`
         });
         continue;
       }
@@ -2671,44 +3429,221 @@ function checkStateMatrix(registry, manifest, baseline) {
         file: loc?.file,
         line: loc?.line,
         entity: { kind: "route", id: route },
-        hint: `Capture the "${kind}" state, or if the route cannot render it add \`export const uidex = { page: "${page}", waivers: { ${kind}: "why it can't" } }\`, or grandfather it via \`uidex scan --update-baseline\` (the baseline change lands in the diff for review).`
+        hint: `Capture the "${kind}" state; or if the route CANNOT render it, add \`acknowledge: { ${kind}: { type: "impossible", reason: "why it can't" } }\` to page "${page}"; or record it as debt with \`uidex scan --update-baseline\` (which writes \`{ type: "backlog" }\`, visible in the diff for review).`
       });
     }
+    for (const [scope, entry] of ack) {
+      if (scope === ACK_ALL || !kinds.has(scope)) continue;
+      diagnostics.push(staleDiagnostic(entry, route, page, loc));
+    }
   }
+  return diagnostics;
+}
+function staleDiagnostic(entry, route, page, loc) {
+  const what = entry.scope === ACK_ALL ? `route "${route}" is captured` : `route "${route}" does render core kind "${entry.scope}"`;
+  return {
+    code: "stale-acknowledgment",
+    severity: "warning",
+    message: `${page ? `page "${page}"` : `route "${route}"`} acknowledges "${entry.scope}" as ${describeAck(entry)}, but ${what}`,
+    file: loc?.file,
+    line: loc?.line,
+    ...page ? { entity: { kind: "page", id: page } } : {},
+    hint: originHint(entry, page)
+  };
+}
+function computeMatrixBacklog(registry, manifest) {
+  const routes = registry.list("route");
+  const pageOf = new Map(routes.map((r) => [r.path, r.page]));
+  const captured = coreKindsByRoute(registry, manifest);
+  const out2 = {};
   for (const [route, kinds] of captured) {
     const page = pageOf.get(route);
-    if (!page || isOptedOut(registry, page)) continue;
-    const waivers = pageWaivers(registry, page);
-    const loc = registry.get("page", page)?.loc;
-    for (const kind of Object.keys(waivers)) {
-      if (kinds.has(kind)) {
+    const ack = routeAcknowledge(registry, void 0, route, page);
+    if (ack.has(ACK_ALL)) continue;
+    const scopes = {};
+    for (const kind of CORE_KINDS) {
+      if (kinds.has(kind) || ack.has(kind)) continue;
+      scopes[kind] = { type: "backlog" };
+    }
+    if (Object.keys(scopes).length > 0) out2[route] = scopes;
+  }
+  return out2;
+}
+
+// src/scanner/scan/surface-check.ts
+import * as path6 from "path";
+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: "stale-waiver",
+          code: "unknown-reference",
           severity: "warning",
-          message: `page "${page}" waives core kind "${kind}", but route "${route}" does render it`,
-          file: loc?.file,
-          line: loc?.line,
-          entity: { kind: "page", id: page },
-          hint: `Remove the "${kind}" waiver \u2014 the route renders that kind, so the waiver's reason is stale.`
+          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 computeMissingKinds(registry, manifest) {
+function checkFeatureSurfaceCaptures(registry, manifest) {
   const routes = registry.list("route");
-  const pageOf = new Map(routes.map((r) => [r.path, r.page]));
-  const captured = coreKindsByRoute(registry, manifest);
-  const out2 = {};
-  for (const [route, kinds] of captured) {
-    const page = pageOf.get(route);
-    if (isOptedOut(registry, page)) continue;
-    const waivers = page ? pageWaivers(registry, page) : {};
-    const missing = CORE_KINDS.filter((k) => !kinds.has(k) && !waivers[k]);
-    if (missing.length > 0) out2[route] = missing;
+  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 out2;
+  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
@@ -2718,6 +3653,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;
@@ -2730,6 +3667,21 @@ function audit(opts) {
   for (const ef of opts.flowExtracted ?? []) {
     if (ef.diagnostics) diagnostics.push(...ef.diagnostics);
   }
+  for (const ef of extracted) {
+    for (const m of ef.metadata ?? []) {
+      for (const [scope, ack] of Object.entries(m.acknowledge ?? {})) {
+        if (!isPlaceholderReason(ack.reason)) continue;
+        diagnostics.push({
+          code: "placeholder-reason",
+          severity: "warning",
+          message: `acknowledge "${scope}" still has the migration's placeholder reason ("${ack.reason}")`,
+          file: ef.file.displayPath,
+          line: m.loc.line,
+          hint: `Replace it with why this can NEVER be captured \u2014 or, if it merely has not been captured yet, change the type to "backlog" (which needs no reason).`
+        });
+      }
+    }
+  }
   if (check && opts.generated !== void 0) {
     const outRel = opts.outputPath ?? config.output;
     const fresh = normalizeForCheck(opts.generated);
@@ -2799,9 +3751,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({
@@ -2816,14 +3825,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 },
@@ -2834,7 +3856,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;
@@ -2843,10 +3889,24 @@ function audit(opts) {
         if (typeof m.id !== "string") continue;
         const filePath = ef.file.displayPath;
         const wellKnownName = WELL_KNOWN_FILES[m.kind];
-        if (path5.posix.basename(filePath) === wellKnownName) continue;
-        const dir = path5.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",
@@ -2930,6 +3990,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()
@@ -3047,7 +4108,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}.`
             });
           }
@@ -3058,33 +4119,57 @@ function audit(opts) {
     }
   }
   if (lint && statesEnabled && opts.capturedStates) {
-    diagnostics.push(...checkStateCoverage(registry, opts.capturedStates));
+    const sourceByDisplay = new Map(
+      files.map((f) => [f.displayPath, f.sourcePath])
+    );
+    diagnostics.push(
+      ...checkStateCoverage(registry, opts.capturedStates, {
+        workspace: opts.workspace,
+        resolveSourcePath: (displayPath) => sourceByDisplay.get(displayPath)
+      })
+    );
   }
   if (lint && pageCoverageEnabled && opts.capturedStates) {
     diagnostics.push(
-      ...checkPageCoverage(registry, opts.capturedStates, opts.pageBaseline)
+      ...checkPageCoverage(registry, opts.capturedStates, opts.coverageBaseline)
     );
   }
+  if (lint && statesEnabled && opts.capturedStates) {
+    diagnostics.push(...checkComponentCoverage(registry, opts.capturedStates));
+  }
   if (lint && stateMatrixEnabled && opts.capturedStates) {
     diagnostics.push(
-      ...checkStateMatrix(registry, opts.capturedStates, {
-        missingKinds: opts.pageBaseline?.missingKinds ?? {}
-      })
+      ...checkStateMatrix(registry, opts.capturedStates, opts.coverageBaseline)
     );
   }
+  const overrides = config.audit?.severity ?? {};
+  const governed = diagnostics.flatMap((d) => {
+    const level = overrides[d.code];
+    if (level === void 0) return [d];
+    if (level === "off") return [];
+    return [{ ...d, severity: level }];
+  });
   const summary = {
-    errors: diagnostics.filter((d) => d.severity === "error").length,
-    warnings: diagnostics.filter((d) => d.severity === "warning").length
+    errors: governed.filter((d) => d.severity === "error").length,
+    warnings: governed.filter((d) => d.severity === "warning").length
   };
-  return { diagnostics, summary };
+  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",
@@ -3404,6 +4489,30 @@ ${body}
 `;
 }
 var OPAQUE_ID_UNIONS = /* @__PURE__ */ new Set(["ElementId"]);
+function stateEntities(list) {
+  return list.map((e) => ({
+    id: e.id,
+    states: (e.meta?.states ?? []).map((s) => s.name)
+  }));
+}
+function emitStateMap(groups) {
+  const lines = ["export interface UidexStates {"];
+  for (const g of groups) {
+    const withStates = g.entities.filter((e) => e.states.length > 0);
+    if (withStates.length === 0) {
+      lines.push(`  ${g.kind}: never`);
+      continue;
+    }
+    lines.push(`  ${g.kind}: {`);
+    for (const e of [...withStates].sort((a, b) => a.id.localeCompare(b.id))) {
+      const states = [...new Set(e.states)].sort().map((s) => JSON.stringify(s)).join(" | ");
+      lines.push(`    ${JSON.stringify(e.id)}: ${states}`);
+    }
+    lines.push("  }");
+  }
+  lines.push("}");
+  return lines.join("\n") + "\n";
+}
 function emitId(name, ids) {
   if (OPAQUE_ID_UNIONS.has(name)) {
     return `export type ${name} = string & { readonly __uidex?: ${JSON.stringify(name)} }
@@ -3491,36 +4600,64 @@ function emit(opts) {
   );
   t.push(emitId("StateId", [...stateNames]));
   t.push("");
+  t.push("// ---- declared state space (kind \u2192 entity \u2192 its own states) ----");
+  t.push(
+    emitStateMap([
+      { kind: "page", entities: stateEntities(pages) },
+      { kind: "feature", entities: stateEntities(features) },
+      { kind: "widget", entities: stateEntities(widgets) }
+    ])
+  );
   t.push("// ---- authoring-surface shape types ----");
   t.push("export namespace Uidex {");
   t.push(
     '  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 Waivers = Partial<Record<CoreStateKind, string>>");
+  t.push('  export type AcknowledgeScope = CoreStateKind | "*"');
+  t.push("  export interface Impossible {");
+  t.push('    type: "impossible"');
+  t.push("    reason: string");
+  t.push("  }");
+  t.push("  export interface Backlog {");
+  t.push('    type: "backlog"');
+  t.push("    reason?: string");
+  t.push("  }");
+  t.push("  export type Acknowledgment = Impossible | Backlog");
+  t.push(
+    "  export type Acknowledge = Partial<Record<AcknowledgeScope, Acknowledgment>>"
+  );
+  t.push('  export type ComponentAcknowledge = { "*"?: Acknowledgment }');
   t.push("  export interface Page {");
   t.push("    page: PageId | false");
   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("    capture?: boolean");
-  t.push("    waivers?: Waivers");
+  t.push("    acknowledge?: Acknowledge");
   t.push("    description?: string");
   t.push("  }");
   t.push("  export interface Feature {");
   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");
   t.push("  }");
   t.push("  export interface Primitive {");
@@ -3531,8 +4668,9 @@ 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");
   t.push("  }");
   t.push("  export interface Region {");
@@ -3628,8 +4766,8 @@ function parseGitHubRef(ref) {
 }
 
 // src/scanner/scan/scaffold.ts
-import * as fs3 from "fs";
-import * as path6 from "path";
+import * as fs4 from "fs";
+import * as path8 from "path";
 function scaffoldWidgetSpec(opts) {
   return scaffoldSpec({
     registry: opts.registry,
@@ -3653,10 +4791,10 @@ 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 = path6.resolve(outDir, filename);
-  if (fs3.existsSync(outputPath) && !force) {
+  const outputPath = path8.resolve(outDir, filename);
+  if (fs4.existsSync(outputPath) && !force) {
     return {
       outputPath,
       written: false,
@@ -3664,9 +4802,9 @@ function scaffoldSpec(opts) {
       reason: `spec already exists at ${outputPath}; pass --force to overwrite`
     };
   }
-  const content = renderSpec({ id, criteria, fixtureImport });
-  fs3.mkdirSync(path6.dirname(outputPath), { recursive: true });
-  fs3.writeFileSync(outputPath, content, "utf8");
+  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 };
 }
 function capitalize(s) {
@@ -3674,25 +4812,28 @@ function capitalize(s) {
 }
 function renderSpec(args) {
   const lines = [];
-  lines.push(
-    `import { test, expect } from ${JSON.stringify(args.fixtureImport)}`
-  );
+  lines.push(`import { test } from ${JSON.stringify(args.fixtureImport)}`);
   lines.push("");
   lines.push(
     `test.describe(${JSON.stringify(args.id)}, { tag: "@uidex:flow" }, () => {`
   );
-  if (args.criteria.length === 0) {
-    lines.push(`  test("TODO: add acceptance criteria", async () => {`);
-    lines.push(`    // TODO`);
+  const stub = (title, body) => {
+    lines.push(`  test.fixme(${JSON.stringify(title)}, async ({ uidex }) => {`);
+    for (const l of body) lines.push(`    ${l}`);
+    lines.push(`    void uidex`);
     lines.push(`  })`);
+    lines.push("");
+  };
+  if (args.criteria.length === 0) {
+    stub("TODO: add acceptance criteria", [
+      "// Declare `acceptance: [...]` on the entity, then re-run scaffold."
+    ]);
   } else {
     for (const criterion of args.criteria) {
-      lines.push(`  test(${JSON.stringify(criterion)}, async ({ uidex }) => {`);
-      lines.push(`    // TODO: implement criterion`);
-      lines.push(`    void uidex`);
-      lines.push(`    expect(true).toBe(true)`);
-      lines.push(`  })`);
-      lines.push("");
+      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}`)})`
+      ]);
     }
   }
   lines.push("})");
@@ -3701,47 +4842,33 @@ function renderSpec(args) {
 }
 
 // src/scanner/scan/pipeline.ts
-import * as fs4 from "fs";
-import * as path7 from "path";
-var DEFAULT_STATES_MANIFEST = "uidex-states.json";
+import * as fs5 from "fs";
+import * as path9 from "path";
+var DEFAULT_STATES_MANIFEST2 = "uidex-states.json";
 var DEFAULT_COVERAGE_BASELINE = "uidex-coverage-baseline.json";
-function loadPageBaseline(configDir, config) {
+function loadCoverageBaseline(configDir, config) {
   const rel = config.coverageBaseline ?? DEFAULT_COVERAGE_BASELINE;
-  const abs = path7.resolve(configDir, rel);
+  const abs = path9.resolve(configDir, rel);
   let raw;
   try {
-    raw = fs4.readFileSync(abs, "utf8");
+    raw = fs5.readFileSync(abs, "utf8");
   } catch {
     return void 0;
   }
+  let parsed;
   try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || !Array.isArray(parsed.uncapturedPages)) return void 0;
-    const uncapturedPages = parsed.uncapturedPages.filter(
-      (p2) => typeof p2 === "string"
-    );
-    let missingKinds;
-    const mkRaw = parsed.missingKinds;
-    if (mkRaw && typeof mkRaw === "object" && !Array.isArray(mkRaw)) {
-      const mk = {};
-      for (const [route, kinds] of Object.entries(mkRaw)) {
-        if (Array.isArray(kinds)) {
-          mk[route] = kinds.filter((k) => typeof k === "string");
-        }
-      }
-      missingKinds = mk;
-    }
-    return { uncapturedPages, ...missingKinds ? { missingKinds } : {} };
+    parsed = JSON.parse(raw);
   } catch {
     return void 0;
   }
+  return parseCoverageBaseline(parsed) ?? void 0;
 }
 function loadCapturedStates(configDir, config) {
-  const rel = config.statesManifest ?? DEFAULT_STATES_MANIFEST;
-  const abs = path7.resolve(configDir, rel);
+  const rel = config.statesManifest ?? DEFAULT_STATES_MANIFEST2;
+  const abs = path9.resolve(configDir, rel);
   let raw;
   try {
-    raw = fs4.readFileSync(abs, "utf8");
+    raw = fs5.readFileSync(abs, "utf8");
   } catch {
     return void 0;
   }
@@ -3760,7 +4887,7 @@ function loadCapturedStates(configDir, config) {
       if (typeof c.route === "string") rec.route = c.route;
       captured.push(rec);
     }
-    return { captured };
+    return typeof parsed.generatedAt === "string" ? { captured, generatedAt: parsed.generatedAt } : { captured };
   } catch {
     return void 0;
   }
@@ -3796,11 +4923,11 @@ function runOne(dc, opts) {
     gitContext
   });
   const typesRel = config.output;
-  const typesPath = path7.resolve(configDir, typesRel);
+  const typesPath = path9.resolve(configDir, typesRel);
   const dataRel = dataOutputPath(config.output);
-  const dataPath = path7.resolve(configDir, dataRel);
+  const dataPath = path9.resolve(configDir, dataRel);
   const locsRel = locsOutputPath(config.output);
-  const locsPath = path7.resolve(configDir, locsRel);
+  const locsPath = path9.resolve(configDir, locsRel);
   let typesOnDisk = null;
   let dataOnDisk = null;
   let locsOnDisk = null;
@@ -3813,7 +4940,8 @@ function runOne(dc, opts) {
     (ef) => (ef.diagnostics?.length ?? 0) > 0
   );
   const capturedStates = opts.capturedStates ?? loadCapturedStates(configDir, config);
-  const pageBaseline = opts.pageBaseline ?? loadPageBaseline(configDir, config);
+  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) {
     auditResult = audit({
@@ -3838,7 +4966,8 @@ function runOne(dc, opts) {
       locsOnDisk,
       locsOutputPath: locsRel,
       capturedStates,
-      pageBaseline
+      coverageBaseline,
+      workspace
     });
   }
   return {
@@ -3859,15 +4988,15 @@ function runOne(dc, opts) {
 }
 function readOrNull(p2) {
   try {
-    return fs4.readFileSync(p2, "utf8");
+    return fs5.readFileSync(p2, "utf8");
   } catch {
     return null;
   }
 }
 function writeArtifact(artifact) {
   if (readOrNull(artifact.outputPath) === artifact.generated) return false;
-  fs4.mkdirSync(path7.dirname(artifact.outputPath), { recursive: true });
-  fs4.writeFileSync(artifact.outputPath, artifact.generated, "utf8");
+  fs5.mkdirSync(path9.dirname(artifact.outputPath), { recursive: true });
+  fs5.writeFileSync(artifact.outputPath, artifact.generated, "utf8");
   return true;
 }
 function writeScanResult(result) {
@@ -3876,14 +5005,45 @@ function writeScanResult(result) {
   const wroteLocs = writeArtifact(result.locs);
   return wroteTypes || wroteData || wroteLocs;
 }
-function pageBaselinePath(result) {
+function coverageBaselinePath(result) {
   const rel = result.config.coverageBaseline ?? DEFAULT_COVERAGE_BASELINE;
-  return path7.resolve(result.configDir, rel);
+  return path9.resolve(result.configDir, rel);
+}
+
+// src/scanner/scan/states-merge.ts
+function keyOf(c) {
+  return `${c.kind ?? "page"} ${c.entity} ${c.state}`;
+}
+function mergeStates(committed, partial) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const c of committed.captured ?? []) byKey.set(keyOf(c), c);
+  const updated = [];
+  const added = [];
+  for (const c of partial.captured ?? []) {
+    const k = keyOf(c);
+    (byKey.has(k) ? updated : added).push(k);
+    byKey.set(k, c);
+  }
+  const captured = [...byKey.values()].sort(
+    (a, b) => a.entity.localeCompare(b.entity) || a.state.localeCompare(b.state)
+  );
+  return {
+    manifest: {
+      ...committed,
+      captured,
+      // The merged file is only as fresh as its OLDEST evidence: rows carried
+      // over from the committed manifest were not re-verified by this run, so
+      // claiming the partial's newer stamp would defeat the staleness check.
+      ...committed.generatedAt ? { generatedAt: committed.generatedAt } : {}
+    },
+    updated: updated.sort(),
+    added: added.sort()
+  };
 }
 
 // src/scanner/scan/fix.ts
-import * as fs5 from "fs";
-import * as path8 from "path";
+import * as fs6 from "fs";
+import * as path10 from "path";
 function applyFixes(diagnostics) {
   const entries = [];
   for (const d of diagnostics) {
@@ -3916,7 +5076,7 @@ function applyFixes(diagnostics) {
   for (const [filePath, edits] of editsByFile) {
     let content;
     try {
-      content = fs5.readFileSync(filePath, "utf8");
+      content = fs6.readFileSync(filePath, "utf8");
     } catch {
       for (const e of edits) e.entry.skippedReason ??= "file is unreadable";
       continue;
@@ -3936,22 +5096,22 @@ function applyFixes(diagnostics) {
       const edit = kept[i];
       content = content.slice(0, edit.start) + edit.replacement + content.slice(edit.end);
     }
-    if (kept.length > 0) fs5.writeFileSync(filePath, content, "utf8");
+    if (kept.length > 0) fs6.writeFileSync(filePath, content, "utf8");
   }
   for (const entry of entries) {
     if (entry.skippedReason) continue;
     for (const create of entry.createFiles) {
-      if (fs5.existsSync(create.path)) {
-        entry.skippedReason = `${path8.basename(create.path)} already exists`;
+      if (fs6.existsSync(create.path)) {
+        entry.skippedReason = `${path10.basename(create.path)} already exists`;
         continue;
       }
-      fs5.mkdirSync(path8.dirname(create.path), { recursive: true });
-      fs5.writeFileSync(create.path, create.content, "utf8");
+      fs6.mkdirSync(path10.dirname(create.path), { recursive: true });
+      fs6.writeFileSync(create.path, create.content, "utf8");
     }
     if (entry.skippedReason) continue;
     for (const del of entry.deleteFiles) {
       try {
-        fs5.unlinkSync(del);
+        fs6.unlinkSync(del);
       } catch {
       }
     }
@@ -4129,29 +5289,29 @@ function renameEntity(opts) {
 }
 
 // src/scanner/scan/cli.ts
-import * as fs8 from "fs";
-import * as path11 from "path";
+import * as fs9 from "fs";
+import * as path13 from "path";
 
 // src/scanner/scan/ai/index.ts
 import * as p from "@clack/prompts";
 
 // src/scanner/scan/ai/providers/claude.ts
-import * as fs7 from "fs";
-import * as path10 from "path";
+import * as fs8 from "fs";
+import * as path12 from "path";
 
 // src/scanner/scan/ai/templates.ts
-import * as fs6 from "fs";
-import * as path9 from "path";
+import * as fs7 from "fs";
+import * as path11 from "path";
 function templatePath(rel) {
   const candidates = [
-    path9.resolve(__dirname, "../../templates", rel),
+    path11.resolve(__dirname, "../../templates", rel),
     // dist/cli/cli.cjs         → ../../templates
-    path9.resolve(__dirname, "../../../../templates", rel)
+    path11.resolve(__dirname, "../../../../templates", rel)
     // src/scanner/scan/ai → ../../../../templates
   ];
   for (const c of candidates) {
     try {
-      fs6.accessSync(c, fs6.constants.R_OK);
+      fs7.accessSync(c, fs7.constants.R_OK);
       return c;
     } catch {
       continue;
@@ -4163,7 +5323,7 @@ function templatePath(rel) {
   );
 }
 function readTemplate(rel) {
-  return fs6.readFileSync(templatePath(rel), "utf8");
+  return fs7.readFileSync(templatePath(rel), "utf8");
 }
 
 // src/scanner/scan/ai/providers/claude.ts
@@ -4194,8 +5354,8 @@ var claudeProvider = {
   async install({ cwd, force }) {
     const changes = [];
     for (const file of SKILL_FILES) {
-      const dest = path10.join(cwd, file.dest);
-      const exists = fs7.existsSync(dest);
+      const dest = path12.join(cwd, file.dest);
+      const exists = fs8.existsSync(dest);
       if (exists && !force) {
         changes.push({
           path: file.dest,
@@ -4204,56 +5364,56 @@ var claudeProvider = {
         });
         continue;
       }
-      fs7.mkdirSync(path10.dirname(dest), { recursive: true });
-      fs7.writeFileSync(dest, readTemplate(file.template));
+      fs8.mkdirSync(path12.dirname(dest), { recursive: true });
+      fs8.writeFileSync(dest, readTemplate(file.template));
       changes.push({
         path: file.dest,
         action: exists ? "overwritten" : "created"
       });
     }
     for (const rel of LEGACY_FILES) {
-      const dest = path10.join(cwd, rel);
-      if (fs7.existsSync(dest)) {
-        fs7.unlinkSync(dest);
+      const dest = path12.join(cwd, rel);
+      if (fs8.existsSync(dest)) {
+        fs8.unlinkSync(dest);
         changes.push({ path: rel, action: "removed" });
       }
     }
-    cleanupEmpty(path10.join(cwd, ".claude/commands/uidex"));
-    cleanupEmpty(path10.join(cwd, ".claude/commands"));
-    cleanupEmpty(path10.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 = path10.join(cwd, file.dest);
-      if (!fs7.existsSync(dest)) {
+      const dest = path12.join(cwd, file.dest);
+      if (!fs8.existsSync(dest)) {
         changes.push({ path: file.dest, action: "skipped", reason: "absent" });
         continue;
       }
-      fs7.unlinkSync(dest);
+      fs8.unlinkSync(dest);
       changes.push({ path: file.dest, action: "removed" });
     }
-    cleanupEmpty(path10.join(cwd, ".claude/skills/uidex/references"));
-    cleanupEmpty(path10.join(cwd, ".claude/skills/uidex"));
-    cleanupEmpty(path10.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 = path10.join(cwd, rel);
-      if (fs7.existsSync(dest)) {
-        fs7.unlinkSync(dest);
+      const dest = path12.join(cwd, rel);
+      if (fs8.existsSync(dest)) {
+        fs8.unlinkSync(dest);
         changes.push({ path: rel, action: "removed" });
       }
     }
-    cleanupEmpty(path10.join(cwd, ".claude/commands/uidex"));
-    cleanupEmpty(path10.join(cwd, ".claude/commands"));
-    cleanupEmpty(path10.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 };
   }
 };
 function cleanupEmpty(dir) {
   try {
-    const entries = fs7.readdirSync(dir);
-    if (entries.length === 0) fs7.rmdirSync(dir);
+    const entries = fs8.readdirSync(dir);
+    if (entries.length === 0) fs8.rmdirSync(dir);
   } catch {
   }
 }
@@ -4422,6 +5582,8 @@ async function run(opts) {
         return runScaffold(cwd, positional.slice(1), flags, writer);
       case "rename":
         return runRename(cwd, positional.slice(1), flags, writer);
+      case "states":
+        return runStates(cwd, positional.slice(1), writer);
       case "ai": {
         const result = await runAiCommand({
           cwd,
@@ -4450,6 +5612,7 @@ function helpText2() {
     "  scan [flags]          Run the scanner pipeline",
     "  scaffold <widget|page|feature> <id>  Emit a Playwright spec from declared acceptance",
     "  rename <element|widget|region> <old-id> <new-id>  Rename an id everywhere (DOM attr, flows, exports)",
+    "  states merge [partial]  Fold a filtered run's *.partial.json into the committed manifest",
     "  ai <install|uninstall|providers>  Manage AI assistant integrations",
     "",
     "Flags:",
@@ -4457,15 +5620,15 @@ function helpText2() {
     "  --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), then rescan and write",
-    "  --update-baseline     Regenerate the page-coverage baseline (uidex-coverage-baseline.json) from the current uncaptured routes",
+    "  --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",
     ""
   ].join("\n");
 }
 function runInit(cwd, w) {
-  const configPath = path11.join(cwd, CONFIG_FILENAME);
-  if (fs8.existsSync(configPath)) {
+  const configPath = path13.join(cwd, CONFIG_FILENAME);
+  if (fs9.existsSync(configPath)) {
     w.err(`.uidex.json already exists at ${configPath}`);
     return w.result(1);
   }
@@ -4474,16 +5637,16 @@ function runInit(cwd, w) {
     sources: [{ rootDir: "src" }],
     output: "src/uidex.gen.ts"
   };
-  fs8.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+  fs9.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   w.out(`Created ${configPath}`);
-  const gitignorePath = path11.join(cwd, ".gitignore");
+  const gitignorePath = path13.join(cwd, ".gitignore");
   const entry = "*.gen.*";
-  if (fs8.existsSync(gitignorePath)) {
-    const existing = fs8.readFileSync(gitignorePath, "utf8");
+  if (fs9.existsSync(gitignorePath)) {
+    const existing = fs9.readFileSync(gitignorePath, "utf8");
     const hasEntry = existing.split("\n").some((line) => line.trim() === entry);
     if (!hasEntry) {
       const needsNewline = existing.length > 0 && !existing.endsWith("\n");
-      fs8.appendFileSync(
+      fs9.appendFileSync(
         gitignorePath,
         `${needsNewline ? "\n" : ""}${entry}
 `,
@@ -4492,7 +5655,7 @@ function runInit(cwd, w) {
       w.out(`Appended ${entry} to ${gitignorePath}`);
     }
   } else {
-    fs8.writeFileSync(gitignorePath, `${entry}
+    fs9.writeFileSync(gitignorePath, `${entry}
 `, "utf8");
     w.out(`Created ${gitignorePath} with ${entry}`);
   }
@@ -4531,20 +5694,25 @@ function runScanCommand(cwd, flags, w) {
   if (updateBaseline) {
     for (const r of results) {
       const manifest = r.capturedStates ?? { captured: [] };
-      const pageBaseline = computePageBaseline(r.registry, manifest);
-      const missingKinds = computeMissingKinds(r.registry, manifest);
-      const baseline = {
-        ...pageBaseline,
-        ...Object.keys(missingKinds).length > 0 ? { missingKinds } : {}
+      const acknowledge = {};
+      const merge = (from) => {
+        for (const [route, scopes] of Object.entries(from)) {
+          acknowledge[route] = { ...acknowledge[route], ...scopes };
+        }
       };
-      const p2 = pageBaselinePath(r);
-      fs8.writeFileSync(p2, JSON.stringify(baseline, null, 2) + "\n");
-      const kindGaps = Object.values(missingKinds).reduce(
-        (n, ks) => n + ks.length,
+      merge(computePageBacklog(r.registry, manifest));
+      merge(computeMatrixBacklog(r.registry, manifest));
+      const baseline = { version: 2, acknowledge };
+      const p2 = coverageBaselinePath(r);
+      fs9.writeFileSync(p2, serializeCoverageBaseline(baseline));
+      const entries = Object.values(acknowledge);
+      const pages = entries.filter((s) => s["*"]).length;
+      const kindGaps = entries.reduce(
+        (n, s) => n + Object.keys(s).filter((k) => k !== "*").length,
         0
       );
       w.out(
-        `Wrote ${p2} \u2014 ${baseline.uncapturedPages.length} uncaptured page(s), ${kindGaps} missing core-kind(s) baselined`
+        `Wrote ${p2} \u2014 ${pages} uncaptured page(s), ${kindGaps} missing core-kind(s) acknowledged as backlog`
       );
     }
     return w.result(0);
@@ -4617,7 +5785,7 @@ function runScaffold(cwd, args, flags, w) {
   for (const r of results) {
     const entity = r.registry.get(scaffoldKind, id);
     if (!entity) continue;
-    const outDir = path11.resolve(r.configDir, "e2e");
+    const outDir = path13.resolve(r.configDir, "e2e");
     const result = scaffoldSpec({
       registry: r.registry,
       kind: scaffoldKind,
@@ -4638,6 +5806,53 @@ function runScaffold(cwd, args, flags, w) {
   return w.result(1);
 }
 var RENAME_KINDS = /* @__PURE__ */ new Set(["element", "widget", "region"]);
+function runStates(cwd, args, w) {
+  const [sub, explicitPartial] = args;
+  if (sub !== "merge") {
+    w.err("Usage: uidex states merge [partial-manifest]");
+    return w.result(1);
+  }
+  const configs = discover({ cwd });
+  if (configs.length === 0) {
+    w.err(`No ${CONFIG_FILENAME} found under ${cwd}`);
+    return w.result(1);
+  }
+  let merged = 0;
+  for (const { configDir, config } of configs) {
+    const rel = config.statesManifest ?? "uidex-states.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;
+    if (!committedRaw) {
+      w.err(`No committed manifest at ${rel}; nothing to merge into`);
+      return w.result(1);
+    }
+    const result = mergeStates(committedRaw, partialRaw);
+    fs9.writeFileSync(target, JSON.stringify(result.manifest, null, 2) + "\n");
+    merged++;
+    w.out(
+      `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}`);
+  }
+  if (merged === 0) {
+    w.out("No partial manifest found; nothing to merge.");
+  }
+  return w.result(0);
+}
+function readJson(p2) {
+  try {
+    const parsed = JSON.parse(fs9.readFileSync(p2, "utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    const m = parsed;
+    return Array.isArray(m.captured) ? m : null;
+  } catch {
+    return null;
+  }
+}
 function runRename(cwd, args, flags, w) {
   const [kind, oldId, newId] = args;
   if (!kind || !RENAME_KINDS.has(kind) || !oldId || !newId) {
@@ -4685,35 +5900,47 @@ function createWriter() {
   };
 }
 export {
+  ACK_ALL,
+  ACK_SCOPES,
   CONFIG_FILENAME,
   ConfigError,
   DEFAULT_CONVENTIONS,
+  DIAGNOSTIC_CODES,
   applyFixes,
   audit,
+  capturedElsewhere,
+  checkComponentCoverage,
   checkPageCoverage,
   checkStateCoverage,
   checkStateMatrix,
   compileRoute,
-  computeMissingKinds,
-  computePageBaseline,
+  computeMatrixBacklog,
+  computePageBacklog,
+  coverageBaselinePath,
   detectRoutes,
   discover,
   emit,
+  entityAcknowledge,
   extract,
   extractUidexExports,
+  findWorkspaceRoot,
   globToRegExp,
-  loadPageBaseline,
+  loadCoverageBaseline,
   matchUrlToRoute,
-  pageBaselinePath,
+  mergeStates,
   parseConfig,
+  parseCoverageBaseline,
   pathToId,
   renameEntity,
   resolve2 as resolve,
   resolveGitContext,
+  resolveWorkspace,
+  routeAcknowledge,
   run as runCli,
   runScan,
   scaffoldSpec,
   scaffoldWidgetSpec,
+  serializeCoverageBaseline,
   validateConfig,
   walk,
   writeScanResult