@topogram/cli 0.3.63 → 0.3.65

package/src/workflows/reconcile/adoption-plan/projection-patches.js

@@ -0,0 +1,177 @@
+// @ts-check
+
+import { ensureTrailingNewline } from "../../../text-helpers.js";
+
+/** @param {any[]} lines @param {string} blockName @returns {any} */
+export function ensureProjectionBlock(lines, blockName) {
+  const startIndex = lines.findIndex((/** @type {any} */ line) => new RegExp(`^\\s*${blockName}\\s*\\{\\s*$`).test(line));
+  if (startIndex !== -1) {
+    let endIndex = -1;
+    for (let index = startIndex + 1; index < lines.length; index += 1) {
+      if (/^\s*\}\s*$/.test(lines[index])) {
+        endIndex = index;
+        break;
+      }
+    }
+    if (endIndex !== -1) {
+      return { lines, startIndex, endIndex };
+    }
+  }
+  const insertBeforeStatus = lines.findIndex((/** @type {any} */ line) => /^\s*status\s+\w+/.test(line));
+  const insertIndex = insertBeforeStatus === -1 ? lines.length : insertBeforeStatus;
+  const blockLines = ["", `  ${blockName} {`, "  }"];
+  lines.splice(insertIndex, 0, ...blockLines);
+  return {
+    lines,
+    startIndex: insertIndex + 1,
+    endIndex: insertIndex + 2
+  };
+}
+
+/** @param {any[]} lines @param {any[]} capabilityIds @returns {any} */
+export function ensureProjectionRealizes(lines, capabilityIds) {
+  const startIndex = lines.findIndex((/** @type {any} */ line) => /^\s*realizes\s*\[/.test(line));
+  if (startIndex === -1) {
+    return { changed: false, lines };
+  }
+  let endIndex = startIndex;
+  while (endIndex < lines.length && !/\]/.test(lines[endIndex])) {
+    endIndex += 1;
+  }
+  if (endIndex >= lines.length) {
+    return { changed: false, lines };
+  }
+  /** @type {any[]} */
+  const existingItems = [];
+  for (let index = startIndex; index <= endIndex; index += 1) {
+    const text = lines[index]
+      .replace(/^\s*realizes\s*\[/, "")
+      .replace(/\]\s*$/, "")
+      .trim();
+    if (!text) {
+      continue;
+    }
+    for (const item of text.split(",").map((/** @type {any} */ entry) => entry.trim()).filter(Boolean)) {
+      existingItems.push(item);
+    }
+  }
+  const merged = [...new Set([...existingItems, ...(capabilityIds || [])])];
+  if (merged.length === existingItems.length) {
+    return { changed: false, lines };
+  }
+  const replacement = ["  realizes [", ...merged.map((/** @type {any} */ item, /** @type {any} */ index) => `    ${item}${index === merged.length - 1 ? "" : ","}`), "  ]"];
+  lines.splice(startIndex, endIndex - startIndex + 1, ...replacement);
+  return { changed: true, lines };
+}
+
+/** @param {string} baseContents @param {WorkflowRecord} item @returns {any} */
+export function applyProjectionAuthPatchToTopogram(baseContents, item) {
+  const lines = String(baseContents || "").replace(/\r\n/g, "\n").split("\n");
+  const capabilities = [...new Set(item.related_capabilities || [])];
+  let changed = false;
+
+  const realizesResult = ensureProjectionRealizes(lines, capabilities);
+  changed = changed || realizesResult.changed;
+
+  if (item.projection_surface === "authorization") {
+    const block = ensureProjectionBlock(lines, "authorization");
+    for (const capabilityId of capabilities) {
+      const lineIndex = lines.findIndex((/** @type {any} */ line, /** @type {any} */ index) =>
+        index > block.startIndex &&
+        index < block.endIndex &&
+        new RegExp(`^\\s*${capabilityId}(\\s|$)`).test(line)
+      );
+      if (item.suggested_action === "apply_projection_ownership_patch") {
+        const ownershipFragment = `ownership ${item.ownership}${item.ownership_field ? ` ownership_field ${item.ownership_field}` : ""}`;
+        if (lineIndex !== -1) {
+          if (!/\bownership\s+/.test(lines[lineIndex])) {
+            lines[lineIndex] = `${lines[lineIndex].trimEnd()} ${ownershipFragment}`;
+            changed = true;
+          }
+          continue;
+        }
+        lines.splice(block.endIndex, 0, `    ${capabilityId} ${ownershipFragment}`);
+        block.endIndex += 1;
+        changed = true;
+        continue;
+      }
+
+      if (item.suggested_action === "apply_projection_permission_patch") {
+        const permissionFragment = `permission ${item.permission}`;
+        if (lineIndex !== -1) {
+          if (!/\bpermission\s+/.test(lines[lineIndex])) {
+            lines[lineIndex] = `${lines[lineIndex].trimEnd()} ${permissionFragment}`;
+            changed = true;
+          }
+          continue;
+        }
+        lines.splice(block.endIndex, 0, `    ${capabilityId} ${permissionFragment}`);
+        block.endIndex += 1;
+        changed = true;
+        continue;
+      }
+
+      const claimFragment = `claim ${item.claim}${item.claim_value != null ? ` claim_value ${item.claim_value}` : ""}`;
+      if (lineIndex !== -1) {
+        if (!/\bclaim\s+/.test(lines[lineIndex])) {
+          lines[lineIndex] = `${lines[lineIndex].trimEnd()} ${claimFragment}`;
+          changed = true;
+        }
+        continue;
+      }
+      lines.splice(block.endIndex, 0, `    ${capabilityId} ${claimFragment}`);
+      block.endIndex += 1;
+      changed = true;
+    }
+  }
+
+  if (item.projection_surface === "visibility_rules") {
+    const block = ensureProjectionBlock(lines, "visibility_rules");
+    for (const capabilityId of capabilities) {
+      if (item.suggested_action === "apply_projection_permission_patch") {
+        const hasExistingPermissionRule = lines.some((/** @type {any} */ line, /** @type {any} */ index) =>
+          index > block.startIndex &&
+          index < block.endIndex &&
+          new RegExp(`^\\s*action\\s+${capabilityId}\\s+visible_if\\s+permission\\s+${item.permission}(\\s|$)`).test(line)
+        );
+        if (hasExistingPermissionRule) {
+          continue;
+        }
+        const hasAnyVisibilityRule = lines.some((/** @type {any} */ line, /** @type {any} */ index) =>
+          index > block.startIndex &&
+          index < block.endIndex &&
+          new RegExp(`^\\s*action\\s+${capabilityId}\\s+visible_if\\s+`).test(line)
+        );
+        if (hasAnyVisibilityRule) {
+          continue;
+        }
+        lines.splice(block.endIndex, 0, `    action ${capabilityId} visible_if permission ${item.permission}`);
+        block.endIndex += 1;
+        changed = true;
+        continue;
+      }
+
+      const hasExistingClaimRule = lines.some((/** @type {any} */ line, /** @type {any} */ index) =>
+        index > block.startIndex &&
+        index < block.endIndex &&
+        new RegExp(`^\\s*action\\s+${capabilityId}\\s+visible_if\\s+claim\\s+${item.claim}(\\s|$)`).test(line)
+      );
+      if (hasExistingClaimRule) {
+        continue;
+      }
+      const hasAnyVisibilityRule = lines.some((/** @type {any} */ line, /** @type {any} */ index) =>
+        index > block.startIndex &&
+        index < block.endIndex &&
+        new RegExp(`^\\s*action\\s+${capabilityId}\\s+visible_if\\s+`).test(line)
+      );
+      if (hasAnyVisibilityRule) {
+        continue;
+      }
+      lines.splice(block.endIndex, 0, `    action ${capabilityId} visible_if claim ${item.claim}${item.claim_value != null ? ` claim_value ${item.claim_value}` : ""}`);
+      block.endIndex += 1;
+      changed = true;
+    }
+  }
+
+  return changed ? ensureTrailingNewline(lines.join("\n")) : baseContents;
+}

package/src/workflows/reconcile/adoption-plan/reasons.js

@@ -0,0 +1,107 @@
+// @ts-check
+
+/** @param {WorkflowRecord} step @returns {any} */
+export function reasonForAdoptionItem(step) {
+  switch (step.action) {
+    case "promote_actor":
+      return "Promote this imported actor into canonical Topogram.";
+    case "promote_role":
+      return "Promote this imported role into canonical Topogram.";
+    case "promote_entity":
+      return "No canonical entity exists for this imported concept.";
+    case "promote_enum":
+      return step.target ? `Promote this enum to support merged concept ${step.target}.` : "Promote this imported enum into canonical Topogram.";
+    case "promote_shape":
+      return step.target ? `Promote this shape to support concept ${step.target}.` : "Promote this imported shape into canonical Topogram.";
+    case "promote_capability":
+      return "Promote this imported capability into canonical Topogram.";
+    case "promote_widget":
+      return "Promote this imported reusable UI widget into canonical Topogram.";
+    case "merge_capability_into_existing_entity":
+      return `Adopt this capability while preserving the existing canonical entity ${step.target}.`;
+    case "promote_doc":
+      return "Promote this imported companion doc into canonical Topogram docs.";
+    case "promote_workflow_doc":
+      return "Promote this imported workflow doc into canonical Topogram workflow docs.";
+    case "promote_workflow_decision":
+      return "Promote this imported workflow decision into canonical Topogram decisions.";
+    case "promote_verification":
+      return "Promote this imported verification into canonical Topogram verifications.";
+    case "promote_ui_report":
+      return "Promote this imported UI review report into canonical Topogram docs.";
+    case "apply_projection_permission_patch":
+      return `Apply inferred permission-based auth rules to canonical projection ${step.target}.`;
+    case "apply_projection_auth_patch":
+      return `Apply inferred claim-based auth rules to canonical projection ${step.target}.`;
+    case "apply_projection_ownership_patch":
+      return `Apply inferred ownership-based auth rules to canonical projection ${step.target}.`;
+    case "apply_doc_link_patch":
+      return "Apply this suggested actor/role metadata update to an existing canonical doc.";
+    case "apply_doc_metadata_patch":
+      return "Apply this suggested safe metadata update to an existing canonical doc.";
+    case "skip_duplicate_shape":
+      return step.target ? `Skip this shape because it duplicates canonical shape ${step.target}.` : "Skip this shape because it duplicates existing canonical surface.";
+    default:
+      return "Review this adoption suggestion before applying it.";
+  }
+}
+
+/** @param {WorkflowRecord} step @returns {any} */
+export function recommendationForAdoptionItem(step) {
+  if (step.action === "apply_doc_link_patch") {
+    return `Update \`${step.target}\` with the suggested related actor/role links.`;
+  }
+  if (step.action === "apply_doc_metadata_patch") {
+    return `Update \`${step.target}\` with the suggested safe metadata changes.`;
+  }
+  if (step.action === "apply_projection_permission_patch") {
+    return `Update \`${step.target}\` with inferred permission auth rules for ${(step.related_capabilities || []).map((/** @type {any} */ item) => `\`${item}\``).join(", ") || "the related capabilities"}.`;
+  }
+  if (step.action === "apply_projection_auth_patch") {
+    return `Update \`${step.target}\` with inferred claim auth rules for ${(step.related_capabilities || []).map((/** @type {any} */ item) => `\`${item}\``).join(", ") || "the related capabilities"}.`;
+  }
+  if (step.action === "apply_projection_ownership_patch") {
+    return `Update \`${step.target}\` with inferred ownership auth rules for ${(step.related_capabilities || []).map((/** @type {any} */ item) => `\`${item}\``).join(", ") || "the related capabilities"}.`;
+  }
+  if (step.action === "promote_widget") {
+    return "Promote this reviewed widget candidate before binding or reusing it from canonical projections.";
+  }
+  if (!["promote_actor", "promote_role"].includes(step.action)) {
+    return null;
+  }
+  const kindLabel = step.action === "promote_actor" ? "actor" : "role";
+  /** @type {any[]} */
+  const linkHints = [];
+  if ((step.related_docs || []).length > 0) {
+    linkHints.push(`link to docs ${step.related_docs.map((/** @type {any} */ item) => `\`${item}\``).join(", ")}`);
+  }
+  if ((step.related_capabilities || []).length > 0) {
+    linkHints.push(`check capabilities ${step.related_capabilities.map((/** @type {any} */ item) => `\`${item}\``).join(", ")}`);
+  }
+  return `Promote this ${kindLabel}${step.confidence ? ` (${step.confidence})` : ""}${linkHints.length ? ` and ${linkHints.join("; ")}` : ""}.`;
+}
+
+/** @param {WorkflowRecord} item @returns {any} */
+export function formatDocLinkSuggestionInline(item) {
+  return `doc \`${item.doc_id}\`` +
+    `${item.add_related_actors?.length ? ` add-actors=${item.add_related_actors.map((/** @type {any} */ entry) => `\`${entry}\``).join(", ")}` : ""}` +
+    `${item.add_related_roles?.length ? ` add-roles=${item.add_related_roles.map((/** @type {any} */ entry) => `\`${entry}\``).join(", ")}` : ""}` +
+    `${item.add_related_capabilities?.length ? ` add-capabilities=${item.add_related_capabilities.map((/** @type {any} */ entry) => `\`${entry}\``).join(", ")}` : ""}` +
+    `${item.add_related_rules?.length ? ` add-rules=${item.add_related_rules.map((/** @type {any} */ entry) => `\`${entry}\``).join(", ")}` : ""}` +
+    `${item.add_related_workflows?.length ? ` add-workflows=${item.add_related_workflows.map((/** @type {any} */ entry) => `\`${entry}\``).join(", ")}` : ""}` +
+    `${item.patch_rel_path ? ` draft=\`${item.patch_rel_path}\`` : ""}`;
+}
+
+/** @param {WorkflowRecord} item @returns {any} */
+export function formatDocDriftSummaryInline(item) {
+  return `doc \`${item.doc_id}\` (${item.recommendation_type}) fields=${item.differing_fields.map((/** @type {any} */ entry) => entry.field).join(", ")} confidence=${item.imported_confidence}`;
+}
+
+/** @param {WorkflowRecord} item @returns {any} */
+export function formatDocMetadataPatchInline(item) {
+  return `doc \`${item.doc_id}\`` +
+    `${item.summary ? " set-summary=yes" : ""}` +
+    `${item.success_outcome ? " set-success_outcome=yes" : ""}` +
+    `${item.actors?.length ? ` add-actors=${item.actors.map((/** @type {any} */ entry) => `\`${entry}\``).join(", ")}` : ""}` +
+    `${item.patch_rel_path ? ` draft=\`${item.patch_rel_path}\`` : ""}`;
+}

package/src/workflows/reconcile/adoption-plan.js

@@ -0,0 +1,32 @@
+// @ts-check
+
+export { ADOPT_SELECTORS, buildAdoptionPlan } from "./adoption-plan/build.js";
+export {
+  adoptionStatusForStep,
+  blockingDependenciesForProjectionImpacts,
+  blockingDependenciesForUiImpacts,
+  blockingDependenciesForWorkflowImpacts,
+  projectionImpactsForAdoptionItem
+} from "./adoption-plan/dependencies.js";
+export {
+  buildCanonicalAdoptionOutputs,
+  buildPromotedCanonicalItems,
+  readAdoptionPlan
+} from "./adoption-plan/outputs.js";
+export {
+  canonicalDisplayPathForItem,
+  canonicalRelativePathForItem,
+  candidateSourcePathForItem
+} from "./adoption-plan/paths.js";
+export {
+  applyProjectionAuthPatchToTopogram,
+  ensureProjectionBlock,
+  ensureProjectionRealizes
+} from "./adoption-plan/projection-patches.js";
+export {
+  formatDocDriftSummaryInline,
+  formatDocLinkSuggestionInline,
+  formatDocMetadataPatchInline,
+  reasonForAdoptionItem,
+  recommendationForAdoptionItem
+} from "./adoption-plan/reasons.js";

package/src/workflows/reconcile/auth/closures.js

@@ -0,0 +1,115 @@
+// @ts-check
+
+/** @param {any[]} items @returns {any} */
+export function summarizeHintClosureState(items) {
+  const statuses = (items || []).map((/** @type {any} */ item) => item.status).filter(Boolean);
+  if (statuses.length === 0) {
+    return {
+      closure_state: "unresolved",
+      closure_reason: "No reviewed projection patch has been applied for this inferred auth hint yet."
+    };
+  }
+  if (statuses.every((/** @type {any} */ status) => status === "applied")) {
+    return {
+      closure_state: "adopted",
+      closure_reason: "All matching projection patch actions for this inferred auth hint have been applied."
+    };
+  }
+  if (statuses.every((/** @type {any} */ status) => ["applied", "approved", "skipped"].includes(status))) {
+    return {
+      closure_state: "deferred",
+      closure_reason: "This inferred auth hint has been reviewed or intentionally held back, but not every matching projection patch has been applied yet."
+    };
+  }
+  return {
+    closure_state: "unresolved",
+    closure_reason: "At least one matching projection patch for this inferred auth hint is still blocked on review or waiting to be applied."
+  };
+}
+
+/** @param {WorkflowRecord} bundle @param {any[]} planItems @returns {any} */
+export function annotateBundleAuthHintClosures(bundle, planItems) {
+  const bundleItems = (planItems || []).filter((/** @type {any} */ item) => item.bundle === bundle.slug);
+  const annotatedPermissions = (bundle.authPermissionHints || []).map((/** @type {any} */ hint) => ({
+    ...hint,
+    ...summarizeHintClosureState(bundleItems.filter((/** @type {any} */ item) =>
+      item.suggested_action === "apply_projection_permission_patch" &&
+      item.permission === hint.permission
+    ))
+  }));
+  const annotatedClaims = (bundle.authClaimHints || []).map((/** @type {any} */ hint) => ({
+    ...hint,
+    ...summarizeHintClosureState(bundleItems.filter((/** @type {any} */ item) =>
+      item.suggested_action === "apply_projection_auth_patch" &&
+      item.claim === hint.claim &&
+      item.claim_value === (Object.prototype.hasOwnProperty.call(hint, "claim_value") ? hint.claim_value : null)
+    ))
+  }));
+  const annotatedOwnerships = (bundle.authOwnershipHints || []).map((/** @type {any} */ hint) => ({
+    ...hint,
+    ...summarizeHintClosureState(bundleItems.filter((/** @type {any} */ item) =>
+      item.suggested_action === "apply_projection_ownership_patch" &&
+      item.ownership === hint.ownership &&
+      item.ownership_field === hint.ownership_field
+    ))
+  }));
+  return {
+    ...bundle,
+    authPermissionHints: annotatedPermissions,
+    authClaimHints: annotatedClaims,
+    authOwnershipHints: annotatedOwnerships
+  };
+}
+
+/** @param {WorkflowRecord} bundle @returns {any} */
+export function buildAuthHintClosureSummary(bundle) {
+  const hints = [
+    ...(bundle.authPermissionHints || []),
+    ...(bundle.authClaimHints || []),
+    ...(bundle.authOwnershipHints || [])
+  ];
+  const counts = hints.reduce(
+    (/** @type {any} */ acc, /** @type {any} */ hint) => {
+      const state = hint.closure_state || "unresolved";
+      if (state === "adopted") {
+        acc.adopted += 1;
+      } else if (state === "deferred") {
+        acc.deferred += 1;
+      } else {
+        acc.unresolved += 1;
+      }
+      return acc;
+    },
+    { total: hints.length, adopted: 0, deferred: 0, unresolved: 0 }
+  );
+  if (counts.total === 0) {
+    return {
+      status: "no_auth_hints",
+      label: "no auth hints",
+      reason: "This bundle does not currently carry inferred permission, claim, or ownership hints.",
+      ...counts
+    };
+  }
+  if (counts.unresolved === 0 && counts.deferred === 0) {
+    return {
+      status: "mostly_closed",
+      label: "mostly closed",
+      reason: "All inferred auth hints for this bundle have been adopted into canonical projection rules.",
+      ...counts
+    };
+  }
+  if (counts.unresolved === 0) {
+    return {
+      status: "partially_closed",
+      label: "partially closed",
+      reason: "Every inferred auth hint has been reviewed, but at least one is still intentionally deferred instead of adopted.",
+      ...counts
+    };
+  }
+  return {
+    status: "high_risk",
+    label: "high risk",
+    reason: "At least one inferred auth hint is still unresolved, so the recovered auth story for this bundle is not closed yet.",
+    ...counts
+  };
+}

package/src/workflows/reconcile/auth/formatters.js

@@ -0,0 +1,142 @@
+// @ts-check
+
+/** @param {string} text @param {any[]} patterns @returns {any} */
+export function authClaimPatternMatches(text, patterns = []) {
+  return patterns.some((/** @type {any} */ pattern) => pattern.test(text));
+}
+
+/** @param {any[]} entries @param {any[]} patterns @param {any} toText @returns {any} */
+export function collectAuthClaimSignalMatches(entries, patterns, toText) {
+  return (entries || []).filter((/** @type {any} */ entry) => authClaimPatternMatches(toText(entry), patterns));
+}
+
+/** @param {string} value @returns {any} */
+export function formatAuthClaimValueInline(value) {
+  return value == null ? "_dynamic_" : `\`${value}\``;
+}
+
+/** @param {WorkflowRecord} hint @returns {any} */
+export function formatAuthClaimHintInline(hint) {
+  return `claim \`${hint.claim}\` = ${formatAuthClaimValueInline(hint.claim_value)} (${hint.confidence})`;
+}
+
+/** @param {WorkflowRecord} hint @returns {any} */
+export function formatAuthPermissionHintInline(hint) {
+  return `permission \`${hint.permission}\` (${hint.confidence})`;
+}
+
+/** @param {WorkflowRecord} hint @returns {any} */
+export function formatAuthOwnershipHintInline(hint) {
+  return `ownership \`${hint.ownership}\` field \`${hint.ownership_field}\` (${hint.confidence})`;
+}
+
+/** @param {WorkflowRecord} hint @returns {any} */
+export function describeAuthPermissionWhyInferred(hint) {
+  /** @type {any[]} */
+  const signals = [];
+  if (hint?.evidence?.capability_hits) {
+    signals.push(`${hint.evidence.capability_hits} secured capability match${hint.evidence.capability_hits === 1 ? "" : "es"}`);
+  }
+  if (hint?.evidence?.route_hits) {
+    signals.push(`${hint.evidence.route_hits} route/resource match${hint.evidence.route_hits === 1 ? "" : "es"}`);
+  }
+  if (hint?.evidence?.doc_hits) {
+    signals.push(`${hint.evidence.doc_hits} imported doc or policy match${hint.evidence.doc_hits === 1 ? "" : "es"}`);
+  }
+  if (hint?.evidence?.provenance_hits) {
+    signals.push(`${hint.evidence.provenance_hits} auth middleware or policy hint${hint.evidence.provenance_hits === 1 ? "" : "s"}`);
+  }
+  if (signals.length === 0) {
+    return hint?.explanation || "Imported auth evidence suggests a permission rule may gate this surface.";
+  }
+  return `${hint?.explanation || "Imported auth evidence suggests a permission rule may gate this surface."} This inference is based on ${signals.join(", ")}.`;
+}
+
+/** @param {WorkflowRecord} hint @returns {any} */
+export function buildAuthPermissionReviewGuidance(hint) {
+  return `Confirm whether permission \`${hint.permission}\` should gate the related auth-sensitive capabilities before promoting this bundle into canonical auth rules or UI visibility.`;
+}
+
+/** @param {WorkflowRecord} hint @returns {any} */
+export function describeAuthClaimWhyInferred(hint) {
+  /** @type {any[]} */
+  const signals = [];
+  if (hint?.evidence?.capability_hits) {
+    signals.push(`${hint.evidence.capability_hits} secured capability match${hint.evidence.capability_hits === 1 ? "" : "es"}`);
+  }
+  if (hint?.evidence?.route_hits) {
+    signals.push(`${hint.evidence.route_hits} route match${hint.evidence.route_hits === 1 ? "" : "es"}`);
+  }
+  if (hint?.evidence?.participant_hits) {
+    signals.push(`${hint.evidence.participant_hits} participant match${hint.evidence.participant_hits === 1 ? "" : "es"}`);
+  }
+  if (hint?.evidence?.doc_hits) {
+    signals.push(`${hint.evidence.doc_hits} imported doc match${hint.evidence.doc_hits === 1 ? "" : "es"}`);
+  }
+  if (signals.length === 0) {
+    return hint?.explanation || "Imported auth-related evidence suggests this claim may matter here.";
+  }
+  return `${hint?.explanation || "Imported auth-related evidence suggests this claim may matter here."} This inference is based on ${signals.join(", ")}.`;
+}
+
+/** @param {WorkflowRecord} hint @returns {any} */
+export function buildAuthClaimReviewGuidance(hint) {
+  const claimTarget = `claim \`${hint.claim}\` = ${formatAuthClaimValueInline(hint.claim_value)}`;
+  return `Confirm whether ${claimTarget} should gate the related auth-sensitive capabilities before promoting this bundle into canonical auth rules or UI visibility.`;
+}
+
+/** @param {WorkflowRecord} hint @returns {any} */
+export function describeAuthOwnershipWhyInferred(hint) {
+  /** @type {any[]} */
+  const signals = [];
+  if (hint?.evidence?.field_hits) {
+    signals.push(`${hint.evidence.field_hits} ownership-style field match${hint.evidence.field_hits === 1 ? "" : "es"}`);
+  }
+  if (hint?.evidence?.capability_hits) {
+    signals.push(`${hint.evidence.capability_hits} secured lifecycle/detail capability match${hint.evidence.capability_hits === 1 ? "" : "es"}`);
+  }
+  if (hint?.evidence?.doc_hits) {
+    signals.push(`${hint.evidence.doc_hits} imported doc match${hint.evidence.doc_hits === 1 ? "" : "es"}`);
+  }
+  if (signals.length === 0) {
+    return hint?.explanation || "Imported field and auth evidence suggests ownership-based access control may matter here.";
+  }
+  return `${hint?.explanation || "Imported field and auth evidence suggests ownership-based access control may matter here."} This inference is based on ${signals.join(", ")}.`;
+}
+
+/** @param {WorkflowRecord} hint @returns {any} */
+export function buildAuthOwnershipReviewGuidance(hint) {
+  return `Confirm whether field \`${hint.ownership_field}\` should drive \`${hint.ownership}\` access for the related auth-sensitive capabilities before promoting this bundle into canonical auth rules or UI visibility.`;
+}
+
+/** @param {WorkflowRecord} entry @returns {any} */
+export function formatAuthRoleGuidanceInline(entry) {
+  return `role \`${entry.role_id}\` (${entry.confidence})`;
+}
+
+/** @param {WorkflowRecord} entry @returns {any} */
+export function buildAuthRoleReviewGuidance(entry) {
+  if (entry.followup_action === "promote_role") {
+    return `Promote role \`${entry.role_id}\` first, then confirm it remains the primary participant for the related auth-sensitive capabilities before promoting linked auth changes from this bundle.`;
+  }
+  if (entry.followup_action === "link_role_to_docs") {
+    const docList = (entry.followup_doc_ids || []).length
+      ? ` docs ${(entry.followup_doc_ids || []).map((/** @type {any} */ item) => `\`${item}\``).join(", ")}`
+      : " the existing canonical docs";
+    return `Link role \`${entry.role_id}\` into${docList} before promoting more auth-sensitive changes from this bundle.`;
+  }
+  return `Confirm whether role \`${entry.role_id}\` should remain the primary participant for the related auth-sensitive capabilities before promoting role or auth changes from this bundle.`;
+}
+
+/** @param {WorkflowRecord} entry @returns {any} */
+export function formatAuthRoleFollowupInline(entry) {
+  if (entry.followup_action === "promote_role") {
+    return "promote role";
+  }
+  if (entry.followup_action === "link_role_to_docs") {
+    return entry.followup_doc_ids?.length
+      ? `link role to docs ${(entry.followup_doc_ids || []).map((/** @type {any} */ item) => `\`${item}\``).join(", ")}`
+      : "link role to docs";
+  }
+  return "review only";
+}