uidex 0.8.0 → 0.10.0

package/dist/scan/index.js

@@ -30,7 +30,8 @@ var ALLOWED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "audit",
   "conventions",
   "statesManifest",
-  "coverageBaseline"
+  "coverageBaseline",
+  "workspace"
 ]);
 var ALLOWED_SOURCE_KEYS = /* @__PURE__ */ new Set(["rootDir", "include", "exclude", "prefix"]);
 var ALLOWED_CONVENTIONS_KEYS = /* @__PURE__ */ new Set([
@@ -46,19 +47,64 @@ var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set([
   "acceptance",
   "states",
   "pageCoverage",
-  "stateMatrix"
+  "stateMatrix",
+  "severity"
 ]);
+var DIAGNOSTIC_CODES = [
+  "acceptance-uncovered",
+  "acknowledged-elsewhere",
+  "competing-uidex-export",
+  "component-state-uncaptured",
+  "core-kind",
+  "duplicate-id",
+  "dynamic-attr",
+  "dynamic-flow-reference",
+  "gen-missing",
+  "gen-stale",
+  "legacy-acknowledge-field",
+  "legacy-coverage-baseline",
+  "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, path13) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    fail(`${path12} must be an object`);
+    fail(`${path13} must be an object`);
   }
 }
-function assertStringArray(value, path12) {
+function assertStringArray(value, path13) {
   if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
-    fail(`${path12} must be a string[]`);
+    fail(`${path13} must be a string[]`);
   }
 }
 function validateConfig(raw) {
@@ -112,11 +158,30 @@ 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.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`);
     }
   }
@@ -135,7 +200,13 @@ function validateConfig(raw) {
       fail(`conventions.features must be a string or false`);
     }
     if (c.pages !== void 0 && c.pages !== false && c.pages !== "auto") {
-      fail(`conventions.pages must be "auto" or false`);
+      const p2 = c.pages;
+      const routesDir = typeof p2 === "object" && p2 !== null && !Array.isArray(p2) ? p2.routesDir : void 0;
+      if (typeof p2 !== "object" || p2 === null || Array.isArray(p2) || Object.keys(p2).some((k) => k !== "routesDir") || typeof routesDir !== "string" || routesDir.length === 0) {
+        fail(
+          `conventions.pages must be "auto", false, or { routesDir: string }`
+        );
+      }
     }
     if (c.flows !== void 0 && c.flows !== false) {
       assertStringArray(c.flows, "conventions.flows");
@@ -153,7 +224,8 @@ function validateConfig(raw) {
     audit: raw.audit,
     conventions: raw.conventions,
     statesManifest: raw.statesManifest,
-    coverageBaseline: raw.coverageBaseline
+    coverageBaseline: raw.coverageBaseline,
+    workspace: raw.workspace
   };
 }
 function parseConfig(json) {
@@ -203,9 +275,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();
@@ -309,6 +383,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 = [];
@@ -642,6 +736,132 @@ 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);
+}
+var PLACEHOLDER_REASON = "TODO: why can this never be captured?";
+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 isLegacyBaseline(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return false;
+  const r = raw;
+  if ("acknowledge" in r) return false;
+  return "uncapturedPages" in r || "missingKinds" in r;
+}
+function migrateBaseline(legacy) {
+  const acknowledge = {};
+  const at = (route) => acknowledge[route] ??= {};
+  for (const route of legacy.uncapturedPages ?? []) {
+    if (typeof route === "string") at(route)[ACK_ALL] = { type: "backlog" };
+  }
+  for (const [route, kinds] of Object.entries(legacy.missingKinds ?? {})) {
+    if (!Array.isArray(kinds)) continue;
+    for (const kind of kinds) {
+      if (typeof kind === "string" && isCoreKind(kind)) {
+        at(route)[kind] = { type: "backlog" };
+      }
+    }
+  }
+  return { version: 2, acknowledge };
+}
+function serializeCoverageBaseline(baseline) {
+  const routes = Object.keys(baseline.acknowledge).sort();
+  const ordered = {};
+  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",
@@ -660,26 +880,41 @@ var ALLOWED_FIELDS = {
     "widgets",
     "acceptance",
     "states",
+    "acknowledge",
     "capture",
     "waivers",
     "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. `capture` / `waivers` are REMOVED; they stay parseable
+  // only so `--fix` can rewrite them into `acknowledge` (see MIGRATION below).
   feature: /* @__PURE__ */ new Set([
     "feature",
     "name",
     "features",
     "acceptance",
     "states",
+    "acknowledge",
+    "capture",
     "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",
+    "capture",
+    "description"
+  ]),
   region: /* @__PURE__ */ new Set(["region", "name", "description"]),
   flow: /* @__PURE__ */ new Set(["flow", "notFlow", "name", "description"])
 };
+var ACK_FIELDS = /* @__PURE__ */ new Set(["type", "reason"]);
 var STATE_FIELDS = /* @__PURE__ */ new Set([
   "name",
   "kind",
@@ -930,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 };
@@ -1078,8 +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 stateBearing = kind === "page" || kind === "feature" || kind === "widget";
+  const acknowledge = stateBearing ? readAcknowledgeField(byKey, kind === "page") : void 0;
+  const legacyCapture = stateBearing ? readBooleanField(byKey, "capture") : void 0;
+  const legacyWaivers = kind === "page" ? readWaiversField(byKey) : void 0;
   const notFlow = kind === "flow" && discriminator === "notFlow" ? true : void 0;
   const metadata = {
     source: "ts-export",
@@ -1103,15 +1341,25 @@ function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
     metadata.widgetSpans = widgetsField.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 (legacyCapture !== void 0) metadata.legacyCapture = legacyCapture;
+  if (legacyWaivers && Object.keys(legacyWaivers).length > 0) {
+    metadata.legacyWaivers = legacyWaivers;
+  }
   if (notFlow) metadata.notFlow = true;
   if (typeof id === "string" && idValue.kind === "string") {
     metadata.idSpan = idValue.span;
   }
   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) {
@@ -1141,6 +1389,80 @@ function readIdField(value, kind, fieldName) {
     value.pos
   );
 }
+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",
+      '`acknowledge` must be an object mapping a scope (`"*"` or a core kind) to `{ type, reason? }`.',
+      entry.value.pos
+    );
+  }
+  const out2 = {};
+  for (const e of entry.value.entries) {
+    const scopes = isPage ? ACK_SCOPES : COMPONENT_ACK_SCOPES;
+    if (!scopes.includes(e.key)) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `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 !== "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",
+        `acknowledge "${e.key}" needs a \`type\`: ${AUTHORABLE_ACK_TYPES.map((t) => `"${t}"`).join(" or ")}.`,
+        e.value.pos
+      );
+    }
+    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 out2;
+}
 function readWaiversField(byKey) {
   const entry = byKey.get("waivers");
   if (!entry) return void 0;
@@ -1820,13 +2142,26 @@ import * as path4 from "path";
 var PAGE_BASENAME = /^page\.(tsx|ts|jsx|js|mjs|cjs)$/;
 var PAGES_ROUTER_BASENAME = /\.(tsx|ts|jsx|js|mjs|cjs)$/;
 var ROUTE_BASENAME = /^route\.(tsx|ts|jsx|js|mjs|cjs)$/;
-function detectRoutes(files) {
+function detectRoutes(files, options = {}) {
   const out2 = [];
   const seen = /* @__PURE__ */ new Set();
+  const routesDir = options.routesDir ? options.routesDir.replace(/^\.?\/+/, "").replace(/\/+$/, "") : null;
+  const routesDirParts = routesDir ? routesDir.split("/") : null;
   for (const f of files) {
     const rel = f.displayPath;
     const parts = rel.split("/");
     const base = parts[parts.length - 1];
+    if (routesDirParts) {
+      const end = dirEndIndex(parts, routesDirParts);
+      if (end === -1 || end > parts.length - 1) continue;
+      if (!PAGES_ROUTER_BASENAME.test(base)) continue;
+      const routePath = routesStylePath(
+        parts.slice(end, parts.length - 1),
+        base
+      );
+      if (routePath !== null) push(out2, seen, routePath, f.displayPath);
+      continue;
+    }
     const appIdx = parts.indexOf("app");
     if (appIdx !== -1 && PAGE_BASENAME.test(base)) {
       const routeSegments = parts.slice(appIdx + 1, parts.length - 1);
@@ -1853,15 +2188,11 @@ function detectRoutes(files) {
     }
     const routesIdx = parts.indexOf("routes");
     if (routesIdx !== -1 && PAGES_ROUTER_BASENAME.test(base)) {
-      const segs = parts.slice(routesIdx + 1);
-      const last = segs[segs.length - 1];
-      if (last.startsWith("_")) continue;
-      const normalized = [
-        ...segs.slice(0, -1),
-        base.replace(/\.[^.]+$/, "")
-      ].filter((s) => s !== "index" && s !== "__root");
-      const routePath = formatNextAppPath(normalized);
-      push(out2, seen, routePath, f.displayPath);
+      const routePath = routesStylePath(
+        parts.slice(routesIdx + 1, parts.length - 1),
+        base
+      );
+      if (routePath !== null) push(out2, seen, routePath, f.displayPath);
       continue;
     }
   }
@@ -1877,6 +2208,63 @@ function formatNextAppPath(segments) {
   if (kept.length === 0) return "/";
   return "/" + kept.join("/");
 }
+function dirEndIndex(parts, dirParts) {
+  if (dirParts.length === 0) return 0;
+  for (let i = 0; i + dirParts.length <= parts.length; i++) {
+    let match = true;
+    for (let j = 0; j < dirParts.length; j++) {
+      if (parts[i + j] !== dirParts[j]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) return i + dirParts.length;
+  }
+  return -1;
+}
+function routesStylePath(dirSegs, base) {
+  const fileSegs = splitFlatSegments(base.replace(/\.[^.]+$/, ""));
+  const leaf = fileSegs[fileSegs.length - 1];
+  if (leaf.startsWith("_")) return null;
+  const rawSegs = [...dirSegs, ...fileSegs];
+  if (rawSegs.some((s) => s.startsWith("-"))) return null;
+  if (rawSegs[0] === "api") return null;
+  return formatTanStackPath(rawSegs);
+}
+function splitFlatSegments(name) {
+  const segs = [];
+  let cur = "";
+  let depth = 0;
+  for (const ch of name) {
+    if (ch === "[") depth++;
+    else if (ch === "]") depth = Math.max(0, depth - 1);
+    if (ch === "." && depth === 0) {
+      segs.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  segs.push(cur);
+  return segs;
+}
+function formatTanStackPath(segments) {
+  const kept = [];
+  for (const seg of segments) {
+    if (!seg) continue;
+    if (seg === "index" || seg === "route" || seg === "__root") continue;
+    if (seg.startsWith("_")) continue;
+    if (seg.startsWith("(") && seg.endsWith(")")) continue;
+    kept.push(normalizeTanStackSegment(seg.replace(/_$/, "")));
+  }
+  if (kept.length === 0) return "/";
+  return "/" + kept.join("/");
+}
+function normalizeTanStackSegment(seg) {
+  if (seg === "$") return "[...splat]";
+  if (seg.startsWith("$")) return `[${seg.slice(1)}]`;
+  return seg.replace(/\[([^\]]*)\]/g, "$1");
+}
 function pathToId(routePath) {
   if (routePath === "/") return "root";
   return routePath.replace(/^\/+/, "").replace(/\[\.{3}([^\]]+)\]/g, "$1").replace(/\[([^\]]+)\]/g, "$1").replace(/\//g, "-").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
@@ -1923,9 +2311,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;
 }
@@ -1972,9 +2359,12 @@ function resolve2(ctx) {
   function metaWithComposes(kind, id, base) {
     const composes = directChildren.get(`${kind}:${id}`);
     if (!composes || composes.length === 0) return base;
-    return { ...base ?? {}, composes };
+    return { ...base, composes };
   }
-  const routes = conventions.pages === "auto" ? detectRoutes(ctx.extracted.map((e) => e.file)) : [];
+  const routes = conventions.pages === false ? [] : detectRoutes(
+    ctx.extracted.map((e) => e.file),
+    conventions.pages === "auto" ? {} : { routesDir: conventions.pages.routesDir }
+  );
   const handledPageFiles = /* @__PURE__ */ new Set();
   for (const route of routes) {
     const routeDir = path4.posix.dirname(route.file);
@@ -2267,6 +2657,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(
@@ -2276,7 +2705,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 = {
@@ -2345,7 +2777,195 @@ function dedupe(arr) {
 }
 
 // src/scanner/scan/audit.ts
-import * as path5 from "path";
+import * as path6 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/migrate-acknowledge.ts
+var CORE = CORE_STATE_KINDS;
+function orderScopes(scopes) {
+  const rank = (s) => s === ACK_ALL ? -1 : CORE.indexOf(s);
+  return [...scopes].sort((a, b) => rank(a) - rank(b));
+}
+function renderKey(scope) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(scope) ? scope : JSON.stringify(scope);
+}
+function renderAck(a) {
+  const parts = [`type: ${JSON.stringify(a.type)}`];
+  if (a.reason) parts.push(`reason: ${JSON.stringify(a.reason)}`);
+  return `{ ${parts.join(", ")} }`;
+}
+function renderAcknowledge(entries, indent) {
+  const inner = indent + "  ";
+  const lines = orderScopes(Object.keys(entries)).map(
+    (scope) => `${inner}${renderKey(scope)}: ${renderAck(entries[scope])},`
+  );
+  return ["acknowledge: {", ...lines, `${indent}}`].join("\n");
+}
+function indentAt(content, offset) {
+  const lineStart = content.lastIndexOf("\n", offset - 1) + 1;
+  const m = /^[ \t]*/.exec(content.slice(lineStart, offset));
+  return m ? m[0] : "";
+}
+function plannedEntries(m) {
+  const entries = {};
+  if (m.legacyCapture === false) {
+    entries[ACK_ALL] = {
+      type: "impossible",
+      reason: m.description || PLACEHOLDER_REASON
+    };
+  }
+  for (const kind of CORE) {
+    const reason = m.legacyWaivers?.[kind];
+    if (reason) entries[kind] = { type: "impossible", reason };
+  }
+  return entries;
+}
+function migrateLegacyFields(ef) {
+  const out2 = [];
+  const { content, sourcePath, displayPath } = ef.file;
+  for (const m of ef.metadata ?? []) {
+    const legacy = [];
+    if (m.legacyWaivers) legacy.push("waivers");
+    if (m.legacyCapture !== void 0) legacy.push("capture");
+    if (legacy.length === 0) continue;
+    const fields = legacy.join(" and ");
+    const base = {
+      severity: "error",
+      code: "legacy-acknowledge-field",
+      file: displayPath,
+      line: m.loc.line
+    };
+    if (m.acknowledge) {
+      out2.push({
+        ...base,
+        message: `\`${fields}\` was replaced by \`acknowledge\`, and this declaration already has an \`acknowledge\` field`,
+        hint: `Merge the remaining \`${fields}\` entries into \`acknowledge\` by hand and delete them; --fix will not merge two maps for you.`
+      });
+      continue;
+    }
+    const entries = plannedEntries(m);
+    const edits = [];
+    const present = legacy.map((f) => ({ f, prop: m.fieldPropSpans?.[f], del: m.fieldSpans?.[f] })).filter((x) => x.prop && x.del).sort((a, b) => a.prop.start - b.prop.start);
+    if (present.length !== legacy.length) {
+      out2.push({
+        ...base,
+        message: `\`${fields}\` was replaced by \`acknowledge\`, but the field spans needed to rewrite it are unavailable`,
+        hint: "Rewrite the declaration by hand: `acknowledge: { <scope>: { type, reason? } }`."
+      });
+      continue;
+    }
+    const [anchor, ...rest] = present;
+    if (Object.keys(entries).length === 0) {
+      edits.push({
+        path: sourcePath,
+        start: anchor.del.start,
+        end: anchor.del.end,
+        replacement: ""
+      });
+    } else {
+      edits.push({
+        path: sourcePath,
+        start: anchor.prop.start,
+        end: anchor.prop.end,
+        replacement: renderAcknowledge(
+          entries,
+          indentAt(content, anchor.prop.start)
+        )
+      });
+    }
+    for (const r of rest) {
+      edits.push({
+        path: sourcePath,
+        start: r.del.start,
+        end: r.del.end,
+        replacement: ""
+      });
+    }
+    out2.push({
+      ...base,
+      message: `\`${fields}\` was replaced by the unified \`acknowledge\` field`,
+      hint: `Run \`uidex scan --fix\` to rewrite it${m.legacyCapture === false && !m.description ? ", then replace the TODO reason it plants \u2014 `capture: false` carried no explanation and `impossible` requires one" : ""}.`,
+      fix: {
+        description: `Rewrite \`${fields}\` as \`acknowledge\``,
+        edits
+      }
+    });
+  }
+  return out2;
+}
+function migrateLegacyBaseline(opts) {
+  if (!isLegacyBaseline(opts.parsed)) return void 0;
+  return {
+    code: "legacy-coverage-baseline",
+    severity: "error",
+    message: `coverage baseline "${opts.displayPath}" uses the removed \`uncapturedPages\` / \`missingKinds\` shape`,
+    file: opts.displayPath,
+    hint: "Run `uidex scan --fix` to rewrite it as `acknowledge` entries of type `backlog` (identical content, new shape \u2014 no capture run needed).",
+    fix: {
+      description: `Rewrite ${opts.displayPath} as an \`acknowledge\` baseline`,
+      edits: [
+        {
+          path: opts.path,
+          start: 0,
+          end: opts.raw.length,
+          replacement: serializeCoverageBaseline(migrateBaseline(opts.parsed))
+        }
+      ]
+    }
+  };
+}
 
 // src/scanner/scan/page-coverage.ts
 function compileRoute(pattern) {
@@ -2368,11 +2988,11 @@ function compileRoute(pattern) {
   return { test: (url) => re.test(url), specificity };
 }
 function matchUrlToRoute(url, routePaths) {
-  const path12 = stripQuery(url);
+  const path13 = stripQuery(url);
   let best = null;
   for (const rp of routePaths) {
     const { test, specificity } = compileRoute(rp);
-    if (!test(path12)) continue;
+    if (!test(path13)) continue;
     if (!best || specificity > best.specificity)
       best = { path: rp, specificity };
   }
@@ -2403,29 +3023,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;
     }
@@ -2436,46 +3076,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 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.`
-      });
-    }
+  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.`
+    });
   }
   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;
   }
-  return { uncapturedPages: uncaptured.sort() };
+}
+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 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,
@@ -2486,18 +3235,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({
@@ -2512,7 +3274,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)
@@ -2556,36 +3320,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;
       }
@@ -2596,42 +3359,43 @@ 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 [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)) {
-        diagnostics.push({
-          code: "stale-waiver",
-          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.`
-        });
-      }
+    for (const [scope, entry] of ack) {
+      if (scope === ACK_ALL || !kinds.has(scope)) continue;
+      diagnostics.push(staleDiagnostic(entry, route, page, loc));
     }
   }
   return diagnostics;
 }
-function computeMissingKinds(registry, manifest) {
+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 (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;
+    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;
 }
@@ -2655,6 +3419,23 @@ function audit(opts) {
   for (const ef of opts.flowExtracted ?? []) {
     if (ef.diagnostics) diagnostics.push(...ef.diagnostics);
   }
+  for (const ef of extracted) diagnostics.push(...migrateLegacyFields(ef));
+  if (opts.baselineDiagnostic) diagnostics.push(opts.baselineDiagnostic);
+  for (const ef of extracted) {
+    for (const m of ef.metadata ?? []) {
+      for (const [scope, ack] of Object.entries(m.acknowledge ?? {})) {
+        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);
@@ -2768,8 +3549,8 @@ 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 (path6.posix.basename(filePath) === wellKnownName) continue;
+        const dir = path6.posix.dirname(filePath);
         const wellKnownPath = dir === "." ? wellKnownName : `${dir}/${wellKnownName}`;
         if (scannedPaths.has(wellKnownPath)) continue;
         const kindLabel = m.kind === "page" ? "Page" : "Feature";
@@ -2983,25 +3764,41 @@ 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) {
   let line = 1;
@@ -3329,6 +4126,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)} }
@@ -3416,6 +4237,14 @@ 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(
@@ -3428,7 +4257,20 @@ function emit(opts) {
   t.push("    acceptance?: readonly string[]");
   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");
@@ -3436,8 +4278,7 @@ function emit(opts) {
   t.push("    widgets?: readonly WidgetId[]");
   t.push("    acceptance?: readonly string[]");
   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 {");
@@ -3446,6 +4287,7 @@ function emit(opts) {
   t.push("    features?: readonly FeatureId[]");
   t.push("    acceptance?: readonly string[]");
   t.push("    states?: readonly (string | State)[]");
+  t.push("    acknowledge?: ComponentAcknowledge");
   t.push("    description?: string");
   t.push("  }");
   t.push("  export interface Primitive {");
@@ -3458,6 +4300,7 @@ function emit(opts) {
   t.push("    name?: string");
   t.push("    acceptance?: readonly string[]");
   t.push("    states?: readonly (string | State)[]");
+  t.push("    acknowledge?: ComponentAcknowledge");
   t.push("    description?: string");
   t.push("  }");
   t.push("  export interface Region {");
@@ -3553,8 +4396,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 path7 from "path";
 function scaffoldWidgetSpec(opts) {
   return scaffoldSpec({
     registry: opts.registry,
@@ -3580,8 +4423,8 @@ function scaffoldSpec(opts) {
   }
   const criteria = entity.meta?.acceptance ?? [];
   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 = path7.resolve(outDir, filename);
+  if (fs4.existsSync(outputPath) && !force) {
     return {
       outputPath,
       written: false,
@@ -3590,8 +4433,8 @@ function scaffoldSpec(opts) {
     };
   }
   const content = renderSpec({ id, criteria, fixtureImport });
-  fs3.mkdirSync(path6.dirname(outputPath), { recursive: true });
-  fs3.writeFileSync(outputPath, content, "utf8");
+  fs4.mkdirSync(path7.dirname(outputPath), { recursive: true });
+  fs4.writeFileSync(outputPath, content, "utf8");
   return { outputPath, written: true, skipped: false };
 }
 function capitalize(s) {
@@ -3599,25 +4442,27 @@ 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, [
+        "// TODO: drive this criterion, then remove `.fixme` to arm the test."
+      ]);
     }
   }
   lines.push("})");
@@ -3626,47 +4471,40 @@ 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 path8 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 = path8.resolve(configDir, rel);
   let raw;
   try {
-    raw = fs4.readFileSync(abs, "utf8");
+    raw = fs5.readFileSync(abs, "utf8");
   } catch {
-    return void 0;
+    return {};
   }
+  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 {};
   }
+  const legacy = migrateLegacyBaseline({
+    path: abs,
+    raw,
+    parsed,
+    displayPath: rel
+  });
+  if (legacy) return { legacy };
+  return { baseline: 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 = path8.resolve(configDir, rel);
   let raw;
   try {
-    raw = fs4.readFileSync(abs, "utf8");
+    raw = fs5.readFileSync(abs, "utf8");
   } catch {
     return void 0;
   }
@@ -3685,7 +4523,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;
   }
@@ -3721,11 +4559,11 @@ function runOne(dc, opts) {
     gitContext
   });
   const typesRel = config.output;
-  const typesPath = path7.resolve(configDir, typesRel);
+  const typesPath = path8.resolve(configDir, typesRel);
   const dataRel = dataOutputPath(config.output);
-  const dataPath = path7.resolve(configDir, dataRel);
+  const dataPath = path8.resolve(configDir, dataRel);
   const locsRel = locsOutputPath(config.output);
-  const locsPath = path7.resolve(configDir, locsRel);
+  const locsPath = path8.resolve(configDir, locsRel);
   let typesOnDisk = null;
   let dataOnDisk = null;
   let locsOnDisk = null;
@@ -3738,9 +4576,11 @@ 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 loadedBaseline = opts.coverageBaseline ? { baseline: opts.coverageBaseline } : loadCoverageBaseline(configDir, config);
+  const coverageBaseline = loadedBaseline.baseline;
+  const workspace = opts.workspace ?? resolveWorkspace({ configDir, config });
   let auditResult;
-  if (opts.check || opts.lint || resolved.diagnostics.length > 0 || hasExtractDiagnostics) {
+  if (opts.check || opts.lint || resolved.diagnostics.length > 0 || hasExtractDiagnostics || loadedBaseline.legacy) {
     auditResult = audit({
       registry: resolved.registry,
       extracted,
@@ -3763,7 +4603,9 @@ function runOne(dc, opts) {
       locsOnDisk,
       locsOutputPath: locsRel,
       capturedStates,
-      pageBaseline
+      coverageBaseline,
+      baselineDiagnostic: loadedBaseline.legacy,
+      workspace
     });
   }
   return {
@@ -3784,15 +4626,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(path8.dirname(artifact.outputPath), { recursive: true });
+  fs5.writeFileSync(artifact.outputPath, artifact.generated, "utf8");
   return true;
 }
 function writeScanResult(result) {
@@ -3801,14 +4643,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 path8.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 path9 from "path";
 function applyFixes(diagnostics) {
   const entries = [];
   for (const d of diagnostics) {
@@ -3841,7 +4714,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;
@@ -3861,22 +4734,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 = `${path9.basename(create.path)} already exists`;
         continue;
       }
-      fs5.mkdirSync(path8.dirname(create.path), { recursive: true });
-      fs5.writeFileSync(create.path, create.content, "utf8");
+      fs6.mkdirSync(path9.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 {
       }
     }
@@ -4054,29 +4927,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 path12 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 path11 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 path10 from "path";
 function templatePath(rel) {
   const candidates = [
-    path9.resolve(__dirname, "../../templates", rel),
+    path10.resolve(__dirname, "../../templates", rel),
     // dist/cli/cli.cjs         → ../../templates
-    path9.resolve(__dirname, "../../../../templates", rel)
+    path10.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;
@@ -4088,7 +4961,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
@@ -4119,8 +4992,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 = path11.join(cwd, file.dest);
+      const exists = fs8.existsSync(dest);
       if (exists && !force) {
         changes.push({
           path: file.dest,
@@ -4129,56 +5002,56 @@ var claudeProvider = {
         });
         continue;
       }
-      fs7.mkdirSync(path10.dirname(dest), { recursive: true });
-      fs7.writeFileSync(dest, readTemplate(file.template));
+      fs8.mkdirSync(path11.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 = path11.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(path11.join(cwd, ".claude/commands/uidex"));
+    cleanupEmpty(path11.join(cwd, ".claude/commands"));
+    cleanupEmpty(path11.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 = path11.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(path11.join(cwd, ".claude/skills/uidex/references"));
+    cleanupEmpty(path11.join(cwd, ".claude/skills/uidex"));
+    cleanupEmpty(path11.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 = path11.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(path11.join(cwd, ".claude/commands/uidex"));
+    cleanupEmpty(path11.join(cwd, ".claude/commands"));
+    cleanupEmpty(path11.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 {
   }
 }
@@ -4347,6 +5220,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,
@@ -4375,22 +5250,23 @@ 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:",
     "  --check               Verify the on-disk gen file matches a fresh scan; exit non-zero on drift (read-only)",
     "  --lint                Run lint diagnostics (missing annotations, scope leak, duplicate ids, coverage)",
     "  --audit               Equivalent to --check --lint (read-only)",
-    "  --fix                 Apply machine-generated fixes (add data-uidex to unannotated interactive elements, drop empty names), then rescan and write",
-    "  --update-baseline     Regenerate the page-coverage baseline (uidex-coverage-baseline.json) from the current uncaptured routes",
+    "  --fix                 Apply machine-generated fixes (add data-uidex to unannotated interactive elements, drop empty names, migrate waivers/capture to acknowledge), then rescan and write",
+    "  --update-baseline     Regenerate the coverage baseline (uidex-coverage-baseline.json) as `acknowledge` backlog entries",
     "  --json                Emit JSON diagnostics on stdout",
     "  --force               (scaffold) overwrite existing spec",
     ""
   ].join("\n");
 }
 function runInit(cwd, w) {
-  const configPath = path11.join(cwd, CONFIG_FILENAME);
-  if (fs8.existsSync(configPath)) {
+  const configPath = path12.join(cwd, CONFIG_FILENAME);
+  if (fs9.existsSync(configPath)) {
     w.err(`.uidex.json already exists at ${configPath}`);
     return w.result(1);
   }
@@ -4399,16 +5275,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 = path12.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}
 `,
@@ -4417,7 +5293,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}`);
   }
@@ -4456,20 +5332,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);
@@ -4542,7 +5423,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 = path12.resolve(r.configDir, "e2e");
     const result = scaffoldSpec({
       registry: r.registry,
       kind: scaffoldKind,
@@ -4563,6 +5444,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 = path12.resolve(configDir, rel);
+    const partial = explicitPartial ? path12.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 ${path12.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) {
@@ -4610,35 +5538,51 @@ 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,
+  isLegacyBaseline,
+  loadCoverageBaseline,
   matchUrlToRoute,
-  pageBaselinePath,
+  mergeStates,
+  migrateBaseline,
+  migrateLegacyBaseline,
+  migrateLegacyFields,
   parseConfig,
+  parseCoverageBaseline,
   pathToId,
   renameEntity,
   resolve2 as resolve,
   resolveGitContext,
+  resolveWorkspace,
+  routeAcknowledge,
   run as runCli,
   runScan,
   scaffoldSpec,
   scaffoldWidgetSpec,
+  serializeCoverageBaseline,
   validateConfig,
   walk,
   writeScanResult