@topogram/cli 0.3.63 → 0.3.65

package/src/agent-ops/query-builders/auth.js

@@ -0,0 +1,375 @@
+export function formatAuthClaimValueInline(value) {
+  return value == null ? "_dynamic_" : `${value}`;
+}
+
+export function normalizeReviewGroupSelector(id) {
+  const normalized = String(id || "");
+  if (normalized.startsWith("projection_review:")) {
+    return `projection-review:${normalized.slice("projection_review:".length)}`;
+  }
+  if (normalized.startsWith("ui_review:")) {
+    return `ui-review:${normalized.slice("ui_review:".length)}`;
+  }
+  if (normalized.startsWith("workflow_review:")) {
+    return `workflow-review:${normalized.slice("workflow_review:".length)}`;
+  }
+  return null;
+}
+
+export function buildHintLabel(hintType, hint) {
+  if (hintType === "permission") {
+    return `permission ${hint.permission}`;
+  }
+  if (hintType === "claim") {
+    return `claim ${hint.claim} = ${formatAuthClaimValueInline(hint.claim_value)}`;
+  }
+  return `ownership ${hint.ownership} ownership_field ${hint.ownership_field}`;
+}
+
+export function flattenHints(candidateModelBundles = []) {
+  const hintGroups = [
+    {
+      collection: "auth_permission_hints",
+      hintType: "permission",
+      action: "apply_projection_permission_patch"
+    },
+    {
+      collection: "auth_claim_hints",
+      hintType: "claim",
+      action: "apply_projection_auth_patch"
+    },
+    {
+      collection: "auth_ownership_hints",
+      hintType: "ownership",
+      action: "apply_projection_ownership_patch"
+    }
+  ];
+  return candidateModelBundles.flatMap((bundle) =>
+    hintGroups.flatMap(({ collection, hintType, action }) =>
+      (bundle[collection] || []).map((hint) => ({
+        bundle: bundle.slug,
+        hint_type: hintType,
+        hint_label: buildHintLabel(hintType, hint),
+        confidence: hint.confidence || null,
+        related_capabilities: hint.related_capabilities || [],
+        closure_state: hint.closure_state || "unresolved",
+        closure_reason: hint.closure_reason || null,
+        why_inferred: hint.why_inferred || hint.explanation || null,
+        review_guidance: hint.review_guidance || null,
+        projection_patch_action: action
+      }))
+    )
+  );
+}
+
+export function flattenAuthRoleFollowup(candidateModelBundles = []) {
+  return candidateModelBundles.flatMap((bundle) =>
+    (bundle.auth_role_guidance || []).map((entry) => ({
+      bundle: bundle.slug,
+      role_id: entry.role_id,
+      confidence: entry.confidence || null,
+      followup_action: entry.followup_action || null,
+      followup_label: entry.followup_label || null,
+      followup_reason: entry.followup_reason || null,
+      review_guidance: entry.review_guidance || null,
+      related_capabilities: entry.related_capabilities || [],
+      related_docs: entry.related_docs || []
+    }))
+  );
+}
+
+export function buildHighRiskBundles(bundlePriorities = []) {
+  return (bundlePriorities || [])
+    .filter((bundle) => bundle.auth_closure_summary?.status === "high_risk")
+    .map((bundle) => ({
+      bundle: bundle.bundle,
+      auth_closure: bundle.auth_closure_summary || null,
+      auth_aging: bundle.auth_aging_summary || null,
+      next_review_group: bundle.next_review_groups?.[0]
+        ? {
+            id: bundle.next_review_groups[0].id,
+            type: bundle.next_review_groups[0].type || null,
+            reason: bundle.next_review_groups[0].reason || null,
+            selector: normalizeReviewGroupSelector(bundle.next_review_groups[0].id)
+          }
+        : null,
+      bundle_review_selector: bundle.recommend_bundle_review_selector || null,
+      from_plan_ready: Boolean(bundle.recommend_from_plan)
+    }));
+}
+
+export function buildBundleReviewSummary(bundle) {
+  if (!bundle) {
+    return null;
+  }
+  return {
+      bundle: bundle.bundle,
+      auth_closure: bundle.auth_closure_summary || null,
+      auth_aging: bundle.auth_aging_summary || null,
+      next_review_group: bundle.next_review_groups?.[0]
+        ? {
+            id: bundle.next_review_groups[0].id,
+            type: bundle.next_review_groups[0].type || null,
+            reason: bundle.next_review_groups[0].reason || null,
+            selector: normalizeReviewGroupSelector(bundle.next_review_groups[0].id)
+          }
+        : null,
+      bundle_review_selector: bundle.recommend_bundle_review_selector || null,
+      from_plan_ready: Boolean(bundle.recommend_from_plan)
+    };
+}
+
+export function buildRecommendedSteps({ highRiskBundles, authRoleFollowup, nextBundle }) {
+  const priorityBundles = [];
+  if (nextBundle?.bundle) {
+    priorityBundles.push(nextBundle.bundle);
+  }
+  for (const bundle of highRiskBundles || []) {
+    if (!priorityBundles.includes(bundle.bundle)) {
+      priorityBundles.push(bundle.bundle);
+    }
+  }
+
+  const highRiskMap = new Map((highRiskBundles || []).map((bundle) => [bundle.bundle, bundle]));
+  const roleMap = new Map();
+  for (const entry of authRoleFollowup || []) {
+    if (!roleMap.has(entry.bundle)) {
+      roleMap.set(entry.bundle, []);
+    }
+    roleMap.get(entry.bundle).push(entry);
+  }
+
+  const steps = [];
+  for (const bundleId of priorityBundles) {
+    const bundle = highRiskMap.get(bundleId);
+    if (!bundle) {
+      continue;
+    }
+    const nextReviewSelector = bundle.next_review_group?.selector || null;
+    if (nextReviewSelector?.startsWith("projection-review:")) {
+      steps.push({
+        bundle: bundle.bundle,
+        action: "review_projection_group",
+        selector: nextReviewSelector,
+        reason: bundle.next_review_group.reason || "Projection review is still required before auth hints can be adopted safely."
+      });
+    } else if (bundle.bundle_review_selector) {
+      steps.push({
+        bundle: bundle.bundle,
+        action: "review_bundle",
+        selector: bundle.bundle_review_selector,
+        reason: bundle.next_review_group?.reason || "Bundle review is the safest next step before promoting auth-sensitive changes."
+      });
+    }
+
+    for (const entry of roleMap.get(bundle.bundle) || []) {
+      if (entry.followup_action === "promote_role") {
+        steps.push({
+          bundle: bundle.bundle,
+          action: "promote_role_first",
+          selector: null,
+          reason: entry.followup_reason || `Promote role ${entry.role_id} before promoting related auth-sensitive changes.`
+        });
+      } else if (entry.followup_action === "link_role_to_docs") {
+        steps.push({
+          bundle: bundle.bundle,
+          action: "patch_docs_first",
+          selector: null,
+          reason: entry.followup_reason || `Patch docs for role ${entry.role_id} before promoting related auth-sensitive changes.`
+        });
+      }
+    }
+
+    if (bundle.from_plan_ready) {
+      steps.push({
+        bundle: bundle.bundle,
+        action: "run_from_plan_write",
+        selector: "from-plan",
+        reason: "Reviewed auth-sensitive items are ready to promote through from-plan adoption."
+      });
+    }
+  }
+  return steps;
+}
+
+export function buildAuthHintsQueryPayload(report, adoptionStatus) {
+  const candidateModelBundles = report?.candidate_model_bundles || [];
+  const bundlePriorities = adoptionStatus?.bundle_priorities || report?.bundle_priorities || [];
+  const allHints = flattenHints(candidateModelBundles);
+  const authRoleFollowup = flattenAuthRoleFollowup(candidateModelBundles);
+  const highRiskBundles = buildHighRiskBundles(bundlePriorities);
+  const staleHighRiskBundles = highRiskBundles.filter((bundle) => bundle.auth_aging?.escalationLevel === "stale_high_risk");
+  const bundlesWithHints = candidateModelBundles.filter((bundle) =>
+    (bundle.auth_permission_hints || []).length > 0 ||
+    (bundle.auth_claim_hints || []).length > 0 ||
+    (bundle.auth_ownership_hints || []).length > 0
+  );
+
+  const hintClosureCounts = allHints.reduce(
+    (acc, hint) => {
+      if (hint.closure_state === "adopted") {
+        acc.adopted += 1;
+      } else if (hint.closure_state === "deferred") {
+        acc.deferred += 1;
+      } else {
+        acc.unresolved += 1;
+      }
+      return acc;
+    },
+    { adopted: 0, deferred: 0, unresolved: 0 }
+  );
+
+  const bundleClosureCounts = candidateModelBundles.reduce(
+    (acc, bundle) => {
+      const status = bundle.operator_summary?.authClosureSummary?.status || "no_auth_hints";
+      acc[status] = (acc[status] || 0) + 1;
+      return acc;
+    },
+    { no_auth_hints: 0, mostly_closed: 0, partially_closed: 0, high_risk: 0 }
+  );
+
+  return {
+    type: "auth_hints_query",
+    workspace: report?.workspace || adoptionStatus?.workspace || null,
+    summary: {
+      total_bundles_with_auth_hints: bundlesWithHints.length,
+      hint_closure_counts: hintClosureCounts,
+      bundle_auth_closure_counts: bundleClosureCounts,
+      stale_high_risk_bundle_count: staleHighRiskBundles.length
+    },
+    high_risk_bundles: highRiskBundles,
+    stale_high_risk_bundles: staleHighRiskBundles,
+    unresolved_hints: allHints.filter((hint) => hint.closure_state === "unresolved"),
+    deferred_hints: allHints.filter((hint) => hint.closure_state === "deferred"),
+    adopted_hints: allHints.filter((hint) => hint.closure_state === "adopted"),
+    auth_role_followup: authRoleFollowup,
+    recommended_steps: buildRecommendedSteps({
+      highRiskBundles,
+      authRoleFollowup,
+      nextBundle: adoptionStatus?.next_bundle || null
+    })
+  };
+}
+
+export function buildProjectionPatchActionsForBundle(hints = []) {
+  const actions = new Map();
+  for (const hint of hints) {
+    const actionId = hint.projection_patch_action;
+    if (!actionId) {
+      continue;
+    }
+    if (!actions.has(actionId)) {
+      actions.set(actionId, {
+        action: actionId,
+        hint_types: [],
+        hint_labels: []
+      });
+    }
+    const entry = actions.get(actionId);
+    if (hint.hint_type && !entry.hint_types.includes(hint.hint_type)) {
+      entry.hint_types.push(hint.hint_type);
+    }
+    if (hint.hint_label && !entry.hint_labels.includes(hint.hint_label)) {
+      entry.hint_labels.push(hint.hint_label);
+    }
+  }
+  return [...actions.values()];
+}
+
+export function buildBundleRecommendedSteps({ bundle, authRoleFollowup = [] }) {
+  if (!bundle) {
+    return [];
+  }
+
+  const steps = [];
+  const nextReviewSelector = bundle.next_review_group?.selector || null;
+  if (nextReviewSelector?.startsWith("projection-review:")) {
+    steps.push({
+      bundle: bundle.bundle,
+      action: "review_projection_group",
+      selector: nextReviewSelector,
+      reason: bundle.next_review_group.reason || "Projection review is still required before auth hints can be adopted safely."
+    });
+  } else if (bundle.bundle_review_selector) {
+    steps.push({
+      bundle: bundle.bundle,
+      action: "review_bundle",
+      selector: bundle.bundle_review_selector,
+      reason: bundle.next_review_group?.reason || "Bundle review is the safest next step before promoting auth-sensitive changes."
+    });
+  }
+
+  for (const entry of authRoleFollowup || []) {
+    if (entry.followup_action === "promote_role") {
+      steps.push({
+        bundle: bundle.bundle,
+        action: "promote_role_first",
+        selector: null,
+        reason: entry.followup_reason || `Promote role ${entry.role_id} before promoting related auth-sensitive changes.`
+      });
+    } else if (entry.followup_action === "link_role_to_docs") {
+      steps.push({
+        bundle: bundle.bundle,
+        action: "patch_docs_first",
+        selector: null,
+        reason: entry.followup_reason || `Patch docs for role ${entry.role_id} before promoting related auth-sensitive changes.`
+      });
+    }
+  }
+
+  if (bundle.from_plan_ready) {
+    steps.push({
+      bundle: bundle.bundle,
+      action: "run_from_plan_write",
+      selector: "from-plan",
+      reason: "Reviewed auth-sensitive items are ready to promote through from-plan adoption."
+    });
+  }
+
+  return steps;
+}
+
+export function buildAuthReviewPacketPayload(report, adoptionStatus, bundleSlug) {
+  const candidateModelBundles = report?.candidate_model_bundles || [];
+  const bundlePriorities = adoptionStatus?.bundle_priorities || report?.bundle_priorities || [];
+  const targetBundle = candidateModelBundles.find((bundle) => bundle.slug === bundleSlug) || null;
+  if (!targetBundle) {
+    return null;
+  }
+
+  const bundlePriority = bundlePriorities.find((bundle) => bundle.bundle === bundleSlug) || null;
+  const allBundleHints = flattenHints([targetBundle]);
+  const unresolvedHints = allBundleHints.filter((hint) => hint.closure_state === "unresolved");
+  const deferredHints = allBundleHints.filter((hint) => hint.closure_state === "deferred");
+  const adoptedHints = allBundleHints.filter((hint) => hint.closure_state === "adopted");
+  const authRoleFollowup = flattenAuthRoleFollowup([targetBundle]);
+  const projectionPatchActions = buildProjectionPatchActionsForBundle([...unresolvedHints, ...deferredHints, ...adoptedHints]);
+  const highRiskBundle = buildBundleReviewSummary(bundlePriority) || {
+    bundle: bundleSlug,
+    auth_closure: targetBundle.operator_summary?.authClosureSummary || null,
+    auth_aging: targetBundle.operator_summary?.authAging || null,
+    next_review_group: null,
+    bundle_review_selector: null,
+    from_plan_ready: false
+  };
+
+  return {
+    type: "auth_review_packet_query",
+    workspace: report?.workspace || adoptionStatus?.workspace || null,
+    bundle: bundleSlug,
+    auth_closure: highRiskBundle.auth_closure,
+    auth_aging: highRiskBundle.auth_aging,
+    next_review_selector: highRiskBundle.next_review_group?.selector || null,
+    bundle_review_selector: highRiskBundle.bundle_review_selector || null,
+    from_plan_ready: Boolean(highRiskBundle.from_plan_ready),
+    unresolved_hints: unresolvedHints,
+    deferred_hints: deferredHints,
+    adopted_hints: adoptedHints,
+    auth_role_followup: authRoleFollowup,
+    projection_patch_actions: projectionPatchActions,
+    recommended_steps: buildBundleRecommendedSteps({
+      bundle: highRiskBundle,
+      authRoleFollowup
+    })
+  };
+}

package/src/agent-ops/query-builders/change-risk/change-plan.js

@@ -0,0 +1,123 @@
+import {
+  stableSortedStrings,
+  summarizeDiffArtifact
+} from "../common.js";
+import {
+  buildGeneratorTargets,
+  buildProjectionImpacts
+} from "../projection-impacts.js";
+import {
+  buildMaintainedImpacts
+} from "../maintained-risk.js";
+
+export function classifyChangePlan(changePlan, diffArtifact, projectionImpacts, generatorTargets, maintainedImpacts) {
+  const focusKind = changePlan.focus?.kind || null;
+  const semanticSections = diffArtifact
+    ? ["entities", "capabilities", "components", "rules", "workflows", "journeys", "shapes", "projections"]
+        .filter((section) => (diffArtifact[section] || []).length > 0)
+    : [];
+  let classification = "context_review";
+  if (diffArtifact) {
+    classification = semanticSections.length > 0 ? "semantic_diff" : "diff_without_semantic_change";
+  } else if (focusKind === "projection") {
+    classification = "projection_focused_change";
+  } else if (focusKind === "capability" || focusKind === "entity") {
+    classification = "surface_closure_review";
+  }
+  if (maintainedImpacts.maintained_code_likely_impacted) {
+    classification = `${classification}_with_maintained_followup`;
+  }
+
+  return {
+    classification,
+    selected_mode: changePlan.mode,
+    focus: changePlan.focus,
+    has_diff_baseline: Boolean(diffArtifact),
+    semantic_sections_changed: semanticSections,
+    affected_projection_count: projectionImpacts.length,
+    affected_output_count: maintainedImpacts.affected_outputs.length,
+    affected_seam_count: maintainedImpacts.affected_seams.length,
+    recommended_generator_count: generatorTargets.length,
+    maintained_code_likely_impacted: maintainedImpacts.maintained_code_likely_impacted
+  };
+}
+
+export function buildAlignmentRecommendations(changePlan, projectionImpacts, generatorTargets, maintainedImpacts) {
+  const recommendations = [
+    {
+      action: "inspect_semantic_scope",
+      order: 1,
+      reason: changePlan.diff_summary
+        ? "Review the semantic diff and affected projection closure before regenerating downstream surfaces."
+        : "Review the selected surface and its projection closure before regenerating downstream surfaces."
+    }
+  ];
+
+  if (projectionImpacts.length > 0) {
+    recommendations.push({
+      action: "regenerate_projection_targets",
+      order: 2,
+      reason: `Regenerate the recommended targets for ${projectionImpacts.length} affected projection(s).`,
+      targets: stableSortedStrings(generatorTargets.map((entry) => entry.target))
+    });
+  }
+
+  if (maintainedImpacts.maintained_code_likely_impacted) {
+    recommendations.push({
+      action: "review_maintained_followup",
+      order: 3,
+      reason: "Maintained code is likely impacted, so human-owned seams should be reviewed after regeneration.",
+      maintained_files_in_scope: maintainedImpacts.maintained_files_in_scope,
+      affected_outputs: stableSortedStrings(maintainedImpacts.affected_outputs.map((output) => output.output_id)),
+      affected_seams: stableSortedStrings(maintainedImpacts.affected_seams.map((seam) => seam.seam_id || seam.label))
+    });
+  }
+
+  recommendations.push({
+    action: "run_verification_targets",
+    order: maintainedImpacts.maintained_code_likely_impacted ? 4 : 3,
+    reason: "Run the smallest recommended proof set once generated and maintained surfaces are aligned.",
+    verification_targets: changePlan.verification_targets || null,
+    output_verification_targets: maintainedImpacts.affected_outputs.map((output) => ({
+      output_id: output.output_id,
+      verification_targets: output.verification_targets || null
+    }))
+  });
+
+  return recommendations;
+}
+
+export function buildChangePlanPayload({ graph, taskModeArtifact, sliceArtifact, diffArtifact, maintainedBoundaryArtifact }) {
+  const basePayload = {
+    type: "change_plan_query",
+    mode: taskModeArtifact.mode,
+    focus: sliceArtifact?.focus || taskModeArtifact.summary?.selected_surface || null,
+    summary: taskModeArtifact.summary || null,
+    preferred_context_artifacts: taskModeArtifact.preferred_context_artifacts || [],
+    next_action: taskModeArtifact.next_action || null,
+    review_boundary: sliceArtifact?.review_boundary || null,
+    ownership_boundary: sliceArtifact?.ownership_boundary || taskModeArtifact.ownership_boundary || null,
+    write_scope: taskModeArtifact.write_scope || sliceArtifact?.write_scope || null,
+    verification_targets: taskModeArtifact.verification_targets || sliceArtifact?.verification_targets || null,
+    maintained_boundary: maintainedBoundaryArtifact || null,
+    diff_summary: summarizeDiffArtifact(diffArtifact)
+  };
+
+  const projectionImpacts = graph ? buildProjectionImpacts(graph, { sliceArtifact, diffArtifact }) : [];
+  const generatorTargets = graph ? buildGeneratorTargets(graph, projectionImpacts, diffArtifact) : [];
+  const maintainedImpacts = buildMaintainedImpacts({
+    diffArtifact,
+    maintainedBoundaryArtifact,
+    sliceArtifact,
+    verificationTargets: basePayload.verification_targets
+  });
+
+  return {
+    ...basePayload,
+    change_summary: classifyChangePlan(basePayload, diffArtifact, projectionImpacts, generatorTargets, maintainedImpacts),
+    projection_impacts: projectionImpacts,
+    generator_targets: generatorTargets,
+    maintained_impacts: maintainedImpacts,
+    alignment_recommendations: buildAlignmentRecommendations(basePayload, projectionImpacts, generatorTargets, maintainedImpacts)
+  };
+}

package/src/agent-ops/query-builders/change-risk/import-plan.js

@@ -0,0 +1,49 @@
+import { buildImportMaintainedRisk } from "../maintained-risk.js";
+import { buildImportPlanNextAction } from "../workflow-presets-core.js";
+import { buildPresetGuidanceSummary } from "./risk.js";
+
+export function buildImportPlanPayload(adoptionPlan, taskModeArtifact, maintainedBoundaryArtifact = null, workflowPresetState = null) {
+  const importMaintained = buildImportMaintainedRisk(adoptionPlan.imported_proposal_surfaces || [], maintainedBoundaryArtifact);
+  const importNextAction = buildImportPlanNextAction(taskModeArtifact.next_action || null, workflowPresetState);
+  const presetGuidanceSummary = buildPresetGuidanceSummary(workflowPresetState, null);
+  return {
+    type: "import_plan_query",
+    summary: taskModeArtifact.summary || null,
+    adoption_state_vocabulary: adoptionPlan.adoption_state_vocabulary || [],
+    next_action: importNextAction,
+    write_scope: taskModeArtifact.write_scope || null,
+    verification_targets: taskModeArtifact.verification_targets || null,
+    review_groups: adoptionPlan.approved_review_groups || [],
+    staged_items: adoptionPlan.staged_items || [],
+    accepted_items: adoptionPlan.accepted_items || [],
+    rejected_items: adoptionPlan.rejected_items || [],
+    requires_human_review: adoptionPlan.requires_human_review || [],
+    proposal_surfaces: importMaintained.proposal_surfaces,
+    maintained_risk: importMaintained.maintained_risk,
+    maintained_seam_review_summary: importMaintained.maintained_seam_review_summary,
+    preset_guidance_summary: presetGuidanceSummary,
+    active_preset_ids: presetGuidanceSummary.active_preset_ids,
+    preset_blockers: presetGuidanceSummary.preset_blockers,
+    recommended_preset_action: presetGuidanceSummary.recommended_preset_action,
+    workflow_presets: workflowPresetState || {
+      provider: [],
+      team: [],
+      active_provider_count: 0,
+      active_team_count: 0,
+      workflow_preset_surfaces: [],
+      workflow_preset_refresh_summary: {
+        type: "workflow_preset_diff_query",
+        diffs: [],
+        summary: {
+          diff_count: 0,
+          new_count: 0,
+          unchanged_count: 0,
+          changed_count: 0,
+          locally_customized_count: 0,
+          orphaned_customization_count: 0,
+          requires_fresh_review_count: 0
+        }
+      }
+    }
+  };
+}