create-agdf 0.8.4 → 0.8.6

package/lib/interaction-presentation.js

@@ -2,6 +2,7 @@ const REQUIRED_GATES = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 const ARTEFACT_ORDER = ["UR", "PRD", "SD", "TP"];
 const OUTCOMES = new Set(["approve", "revise", "decline", "cancel", "no_response", "timeout", "empty", "invalid", "stale"]);
 const ATTEMPT_OUTCOMES = new Set(["presented", "unavailable_before_invocation", "attempted_not_applied", "unsafe_to_wait"]);
+const APPROVAL_VALUE_TRANSPORTS = new Set(["exact_option_value", "separate_label_and_value", "decorated_label_only", "unknown"]);
 const APPROVAL_SEQUENCE = Object.freeze(["run_status_card", "gate_transition_card", "approval_interaction"]);
 const QUALITY_STATUS_RANK = { pass: 0, warn: 1, revise: 2, block: 3 };
 const QUALITY_DIMENSIONS = Object.freeze([
@@ -63,13 +64,14 @@ export function validateLocaleRegistry(registry) {
     for (const [key, value] of visibleStrings(pack)) {
       if (!value.trim()) errors.push(`empty_copy:${locale}:${key}`);
       const budget = key.startsWith("gateTitles.") ? budgets.title
-        : key.includes("Description") || key.includes("fallbackReasons") || key.startsWith("primary.actions.") || key.startsWith("primary.afterApproval.") || key === "primary.quality"
+        : key.includes("Description") || key.includes("fallbackReasons") || key.startsWith("primary.actions.") || key.startsWith("primary.afterApproval.") || key.startsWith("primary.narration.") || key === "primary.quality"
           ? budgets.description
           : budgets.label;
       if (Number.isInteger(budget) && value.length > budget) errors.push(`length_budget:${locale}:${key}`);
     }
     for (const key of REQUIRED_GATES) {
       if (typeof pack.gateTitles?.[key] !== "string" || !pack.gateTitles[key].trim()) errors.push(`missing_gate_title:${locale}:${key}`);
+      if (typeof pack.gateActionTitles?.[key] !== "string" || !pack.gateActionTitles[key].trim()) errors.push(`missing_gate_action_title:${locale}:${key}`);
     }
   }
   if (JSON.stringify(registry?.optionOrder) !== JSON.stringify(["approve", "revise", "decline", "cancel"])) errors.push("option_order");
@@ -179,8 +181,31 @@ export function reconcileRunScope({ requestText = "", scopeKey = "", runs = [] }
   return Object.freeze({ outcome: matches[0].lifecycle === "active" ? "active_match" : "completed_match", matches, reason: "exact_match" });
 }
 
-export function executeNativeApprovalAttempt({ ready = false, invokeNative, fallback } = {}) {
+export function evaluateNativeApprovalCapability({ staticCapability, runtimeCapability } = {}) {
+  const staticValue = staticCapability?.approvalValueTransport;
+  const runtimeValue = runtimeCapability?.approvalValueTransport;
+  if (runtimeCapability && staticCapability && (runtimeValue !== staticValue || runtimeCapability.waitSafety !== staticCapability.waitSafety)) {
+    return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unavailable_before_invocation", reason: "capability_conflict", evidence_source: "runtime" });
+  }
+  const capability = runtimeCapability ?? staticCapability;
+  const evidenceSource = runtimeCapability ? "runtime" : staticCapability ? "static" : "none";
+  if (!capability || !APPROVAL_VALUE_TRANSPORTS.has(capability.approvalValueTransport)) return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unavailable_before_invocation", reason: "capability_missing", evidence_source: evidenceSource });
+  if (capability.waitSafety === "unsafe") return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unsafe_to_wait", reason: "unsafe_wait", evidence_source: evidenceSource });
+  if (capability.waitSafety !== "deliberate_no_auto_resolution") return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unavailable_before_invocation", reason: "capability_missing", evidence_source: evidenceSource });
+  if (!new Set(["exact_option_value", "separate_label_and_value"]).has(capability.approvalValueTransport)) return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unavailable_before_invocation", reason: capability.approvalValueTransport === "decorated_label_only" ? "decorated_only" : "capability_missing", evidence_source: evidenceSource });
+  return Object.freeze({ eligible: true, native_attempt_required: true, preflight_outcome: "eligible_for_invocation", reason: capability.approvalValueTransport === "exact_option_value" ? "exact_transport" : "separate_value_transport", evidence_source: evidenceSource });
+}
+
+export function executeNativeApprovalAttempt({ ready = false, orientationSnapshot, capabilityPreflight, invokeNative, fallback } = {}) {
   if (!ready) return Object.freeze({ attempted: false, outcome: "unavailable_before_invocation", reason: "gate_not_ready", authorizes: false });
+  const preflight = validateApprovalOrientationSnapshot(orientationSnapshot);
+  if (!preflight.valid) return Object.freeze({ attempted: false, outcome: "unavailable_before_invocation", reason: "orientation_preflight_failed", authorizes: false });
+  if (!capabilityPreflight?.eligible) {
+    const outcome = capabilityPreflight?.preflight_outcome === "unsafe_to_wait" ? "unsafe_to_wait" : "unavailable_before_invocation";
+    const reason = capabilityPreflight?.reason || "capability_missing";
+    if (typeof fallback === "function") fallback({ outcome, reason });
+    return Object.freeze({ attempted: false, outcome, reason, authorizes: false });
+  }
   if (typeof invokeNative !== "function") return Object.freeze({ attempted: false, outcome: "unavailable_before_invocation", reason: "adapter_unavailable", authorizes: false });
   let adapterResult;
   try {
@@ -280,6 +305,7 @@ export function buildApprovalOrientationSnapshot({
   const pack = localePack(registry, locale);
   const runTitle = String(humanPresentation.runTitle ?? "").trim() || normalizedRunTitle(runId);
   const currentGateTitle = String(humanPresentation.gateTitle ?? "").trim() || gateTitle(registry, locale, gate);
+  const primaryHeading = String(pack.gateActionTitles?.[gate] ?? "").trim();
   const artefactRefs = Object.freeze([...(humanPresentation.artefactRefs ?? [])].map((ref) => Object.freeze({ ...ref })));
   const statusFields = Object.freeze([
     Object.freeze({ id: "selected_run", label: pack.statusCard.run, value: `${runTitle} · ${runId}` }),
@@ -298,8 +324,15 @@ export function buildApprovalOrientationSnapshot({
     current_gate: gate,
     presentation_language: locale,
     sequence: APPROVAL_SEQUENCE,
-    compact_status_card: Object.freeze({ title: pack.statusCard.title, fields: statusFields }),
+    compact_status_card: Object.freeze({
+      semantic_block: "run_status_card",
+      title: primaryHeading,
+      primary_heading: primaryHeading,
+      primary_heading_level: 2,
+      fields: statusFields,
+    }),
     gate_transition_card: Object.freeze({
+      semantic_block: "gate_transition_card",
       title: `${currentGateTitle} · ${runTitle} · ${runId}`,
       artefact_refs: artefactRefs,
       ready: pack.interaction.ready,
@@ -309,11 +342,32 @@ export function buildApprovalOrientationSnapshot({
       next_heading: pack.interaction.nextHeading,
       next_gate: String(statusCard.next_gate_after_approval ?? "none"),
     }),
-    approval_interaction: Object.freeze({ expected_approval: expectedApproval, options, authorizes: false }),
+    approval_interaction: Object.freeze({ semantic_block: "approval_interaction", expected_approval: expectedApproval, options, authorizes: false }),
     authorizes: false,
   });
 }
 
+export function validateApprovalOrientationSnapshot(snapshot) {
+  const errors = [];
+  if (!plainObject(snapshot)) return Object.freeze({ valid: false, errors: Object.freeze(["snapshot_missing"]) });
+  if (JSON.stringify(snapshot.sequence) !== JSON.stringify(APPROVAL_SEQUENCE)) errors.push("sequence");
+  if (snapshot.compact_status_card?.semantic_block !== "run_status_card") errors.push("run_status_card");
+  if (snapshot.gate_transition_card?.semantic_block !== "gate_transition_card") errors.push("gate_transition_card");
+  if (snapshot.approval_interaction?.semantic_block !== "approval_interaction") errors.push("approval_interaction");
+  const heading = String(snapshot.compact_status_card?.primary_heading ?? "").trim();
+  if (!heading || snapshot.compact_status_card?.primary_heading_level !== 2) errors.push("primary_heading");
+  if (String(snapshot.compact_status_card?.title ?? "").trim() !== heading) errors.push("primary_heading_owner");
+  if (/^(?:(?:agdf[- ]?status(?: card|karte)?|run status card|gate transition card)(?:\b|\s*[-:—·])|(?:UR|PRD|SD|TP|QA|UAT)(?:\s*[-:—·]|$))/i.test(heading)) errors.push("generic_primary_heading");
+  const fieldIds = snapshot.compact_status_card?.fields?.map((field) => field?.id);
+  if (JSON.stringify(fieldIds) !== JSON.stringify(["selected_run", "readiness_status", "current_gate", "missing_approval", "next_action", "quality_outlook"])) errors.push("status_fields");
+  const expectedApproval = `Approval: ${String(snapshot.current_gate ?? "").trim()}`;
+  if (!REQUIRED_GATES.includes(snapshot.current_gate)
+    || snapshot.gate_transition_card?.exact_approval !== expectedApproval
+    || snapshot.approval_interaction?.expected_approval !== expectedApproval
+    || snapshot.approval_interaction?.options?.[0]?.value !== expectedApproval) errors.push("canonical_approval");
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze(errors) });
+}
+
 export function attachApprovalOrientationSnapshot(statusCard, options = {}) {
   if (!plainObject(statusCard)) throw new Error("approval orientation status card missing");
   const snapshot = buildApprovalOrientationSnapshot({ ...options, statusCard });
@@ -363,6 +417,66 @@ export function buildQualityReadiness({
   });
 }
 
+export function collapseInternalState(
+  { modeSliceDecision = "", verifiedChangeState = "", contextGraphRequiredAction = "", multiScopeState = "" } = {},
+  registry,
+  requestedLocale,
+) {
+  const pack = localePack(registry, requestedLocale);
+  const labels = pack.internalStateLabels || {};
+  const result = {};
+  if (modeSliceDecision === "verified_change") {
+    if (verifiedChangeState === "escalated") {
+      result.verified_change = labels.verifiedChangeEscalated || "Escalated to structured delivery";
+    } else if (["missing", "draft", "invalid", "eligible", "executed"].includes(verifiedChangeState)) {
+      result.verified_change = labels.verifiedChange || "Compact change under review";
+    }
+  }
+  if (contextGraphRequiredAction === "open_gap") {
+    result.context_graph = labels.contextGraphOpenGap || "Graph gap open";
+  } else if (["link", "update", "create", "resolve_drift"].includes(contextGraphRequiredAction)) {
+    result.context_graph = labels.contextGraphMaintained || "Project memory maintained";
+  }
+  if (multiScopeState === "blocked") {
+    result.multi_scope = labels.multiScopeBlocked || "Ambiguous scope, clarification needed";
+  }
+  return result;
+}
+
+export function buildBreadcrumb(breadcrumb, registry, requestedLocale) {
+  if (!Array.isArray(breadcrumb)) return "";
+  const pack = localePack(registry, requestedLocale);
+  const cardLabels = pack.statusCard || {};
+  const titles = pack.gateTitles || {};
+  const sep = cardLabels.breadcrumbSeparator || " \u00b7 ";
+  const symbols = {
+    fulfilled: cardLabels.breadcrumbFulfilled || "\u2713",
+    current: cardLabels.breadcrumbCurrent || "\u25cf",
+    open: cardLabels.breadcrumbOpen || "\u25cb",
+  };
+  return breadcrumb
+    .map((entry) => {
+      const title = titles[entry.gate] || entry.gate;
+      const symbol = symbols[entry.status] || symbols.open;
+      return `${title} ${symbol}`;
+    })
+    .join(sep);
+}
+
+export function buildTransitionNarration(gate, registry, requestedLocale) {
+  const pack = localePack(registry, requestedLocale);
+  const narration = pack.primary?.narration || {};
+  const gateTitles = pack.gateTitles || {};
+  const gateTitle = gateTitles[gate] || gate;
+  const gateConfig = narration.gates?.[gate] || {};
+  const agentNext = gateConfig.agentNext || "";
+  const userAction = gateConfig.userAction || narration.noAction || "no user action required now";
+  if (!agentNext) return "";
+  const gateSatisfiedTemplate = narration.gateSatisfied || "{gate} approved";
+  const gateSatisfied = gateSatisfiedTemplate.replace("{gate}", gateTitle);
+  return `${gateSatisfied} \u2192 ${agentNext} \u2192 ${userAction}`;
+}
+
 export const interactionPresentationConstants = Object.freeze({
   artefactOrder: Object.freeze([...ARTEFACT_ORDER]),
   outcomes: Object.freeze([...OUTCOMES]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [