create-agdf 0.8.4 → 0.8.5

package/generated/.github/skills/agdf-gate-check/SKILL.md

@@ -63,14 +63,14 @@ For a ready `gate_approval`:
 1. Resolve exactly one selected run and evaluate the current gate.
 2. Confirm the required durable artefact is present and ready before presenting a question.
 3. Build one immutable, non-authorizing presentation snapshot from the selected evaluated run and current revision identity.
-4. Compose one Approval Orientation Envelope as one immediately preceding assistant message containing two distinct blocks. Render the compact localized approval-time Run Status Card first. It contains exactly selected run, readiness status, current gate, missing exact approval, one next action and quality outlook; omit raw keys, machine statuses, evidence, diagnostics and allowed/forbidden inventories.
+4. Compose one Approval Orientation Envelope as one immediately preceding assistant message containing two distinct blocks. Render the compact localized approval-time Run Status Card first. Its first visible line is the localized action-oriented gate title as a level-two Markdown heading or equivalent accessible host heading; generic AGDF/card labels and raw gate IDs cannot be the primary heading. It contains exactly selected run, readiness status, current gate, missing exact approval, one next action and quality outlook; omit raw keys, machine statuses, evidence, diagnostics and allowed/forbidden inventories.
 5. In the same assistant message, render a separate localized Gate Transition Card second, immediately before any native question or exact-text fallback. It includes the deterministic human run title and `UR · PRD · SD · TP` links from the selected run. Never put either card only into the question, button description or hidden tool context. Do not invoke the native question tool until the complete two-card envelope is visible.
 6. Compose the transition card as one human-readable gate title with `run_id`, one ready-for-decision line, one short approval-effect block and one short next-transition block. It must answer only: where am I, what does this decision do, and what happens next. Run and gate identity may anchor both cards; do not duplicate status rows, action inventories or the native question.
 7. Distinguish internal process steps from user decisions in natural language. For example, after `Approval: TP`, say that pre-implementation Brownfield Analysis runs next and that no further user action is required now; do not expose `next_user_gate: none` or `user_action_required: no`, and do not ask for a second approval for Brownfield Analysis.
 8. Ask exactly one question that names the selected `run_id` and `current_gate`.
 9. Offer options in stable order: exact `Approval: <GateName>`, localized revise and localized decline. Add explicit cancel only where supported after decline; otherwise host dismissal maps to cancel. Never preselect, skip, auto-submit or reorder an option.
 10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution; otherwise request the same exact approval in concise text.
-11. Render both cards once in that single complete assistant message. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
+11. Render both cards once in that single complete assistant message. Never merge, reverse, omit or duplicate them; the action heading does not replace either card. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
 12. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
 13. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
 14. Persist accepted input only through the existing control-state workflow.

package/generated/.github/skills/agdf-interaction-locales.json

@@ -65,6 +65,14 @@
         "CR": "Code review",
         "OR": "Delivery report"
       },
+      "gateActionTitles": {
+        "UR": "Approve user requirements",
+        "PRD": "Approve product requirements",
+        "SD": "Approve solution design",
+        "TP": "Approve task and test plan",
+        "QA": "Approve quality decision",
+        "UAT": "Accept delivery result"
+      },
       "interaction": {
         "ready": "Ready for your decision",
         "approveHeading": "Approve now",
@@ -180,6 +188,14 @@
         "CR": "Code-Review",
         "OR": "Lieferbericht"
       },
+      "gateActionTitles": {
+        "UR": "Nutzeranforderung freigeben",
+        "PRD": "Produktanforderungen freigeben",
+        "SD": "Lösungsdesign freigeben",
+        "TP": "Umsetzungsplan freigeben",
+        "QA": "Qualitätsentscheidung freigeben",
+        "UAT": "Ergebnis abnehmen"
+      },
       "interaction": {
         "ready": "Bereit für deine Entscheidung",
         "approveHeading": "Jetzt freigeben",

package/generated/.github/skills/agdf-runtime-contract.md

@@ -181,6 +181,14 @@ before invoking any native question tool or emitting an exact-text approval
 request. Splitting the cards across separate assistant turns or invoking the
 tool after only one card is a failed interaction, not a valid presentation.
 
+The first visible line of that envelope is the localized action-oriented title
+of the current user gate, rendered as a level-two Markdown heading or equivalent
+accessible host heading inside the compact approval-time Run Status Card.
+`AGDF Status`, `Run Status Card`, `Gate Transition Card`, raw gate identifiers
+and machine values are semantic or diagnostic labels only and must not become
+the primary heading. The action title appears exactly once and does not replace,
+merge or reorder either required card block.
+
 The compact approval-time Run Status Card contains exactly six operational
 fields: selected run, readiness status, current gate, missing exact approval,
 one next action and quality outlook. It uses localized human-readable labels

package/generated/.opencode/agdf-interaction-locales.json

@@ -65,6 +65,14 @@
         "CR": "Code review",
         "OR": "Delivery report"
       },
+      "gateActionTitles": {
+        "UR": "Approve user requirements",
+        "PRD": "Approve product requirements",
+        "SD": "Approve solution design",
+        "TP": "Approve task and test plan",
+        "QA": "Approve quality decision",
+        "UAT": "Accept delivery result"
+      },
       "interaction": {
         "ready": "Ready for your decision",
         "approveHeading": "Approve now",
@@ -180,6 +188,14 @@
         "CR": "Code-Review",
         "OR": "Lieferbericht"
       },
+      "gateActionTitles": {
+        "UR": "Nutzeranforderung freigeben",
+        "PRD": "Produktanforderungen freigeben",
+        "SD": "Lösungsdesign freigeben",
+        "TP": "Umsetzungsplan freigeben",
+        "QA": "Qualitätsentscheidung freigeben",
+        "UAT": "Ergebnis abnehmen"
+      },
       "interaction": {
         "ready": "Bereit für deine Entscheidung",
         "approveHeading": "Jetzt freigeben",

package/generated/.opencode/agdf-runtime-contract.md

@@ -181,6 +181,14 @@ before invoking any native question tool or emitting an exact-text approval
 request. Splitting the cards across separate assistant turns or invoking the
 tool after only one card is a failed interaction, not a valid presentation.
 
+The first visible line of that envelope is the localized action-oriented title
+of the current user gate, rendered as a level-two Markdown heading or equivalent
+accessible host heading inside the compact approval-time Run Status Card.
+`AGDF Status`, `Run Status Card`, `Gate Transition Card`, raw gate identifiers
+and machine values are semantic or diagnostic labels only and must not become
+the primary heading. The action title appears exactly once and does not replace,
+merge or reorder either required card block.
+
 The compact approval-time Run Status Card contains exactly six operational
 fields: selected run, readiness status, current gate, missing exact approval,
 one next action and quality outlook. It uses localized human-readable labels

package/generated/.opencode/skills/agdf-gate-check/SKILL.md

@@ -63,14 +63,14 @@ For a ready `gate_approval`:
 1. Resolve exactly one selected run and evaluate the current gate.
 2. Confirm the required durable artefact is present and ready before presenting a question.
 3. Build one immutable, non-authorizing presentation snapshot from the selected evaluated run and current revision identity.
-4. Compose one Approval Orientation Envelope as one immediately preceding assistant message containing two distinct blocks. Render the compact localized approval-time Run Status Card first. It contains exactly selected run, readiness status, current gate, missing exact approval, one next action and quality outlook; omit raw keys, machine statuses, evidence, diagnostics and allowed/forbidden inventories.
+4. Compose one Approval Orientation Envelope as one immediately preceding assistant message containing two distinct blocks. Render the compact localized approval-time Run Status Card first. Its first visible line is the localized action-oriented gate title as a level-two Markdown heading or equivalent accessible host heading; generic AGDF/card labels and raw gate IDs cannot be the primary heading. It contains exactly selected run, readiness status, current gate, missing exact approval, one next action and quality outlook; omit raw keys, machine statuses, evidence, diagnostics and allowed/forbidden inventories.
 5. In the same assistant message, render a separate localized Gate Transition Card second, immediately before any native question or exact-text fallback. It includes the deterministic human run title and `UR · PRD · SD · TP` links from the selected run. Never put either card only into the question, button description or hidden tool context. Do not invoke the native question tool until the complete two-card envelope is visible.
 6. Compose the transition card as one human-readable gate title with `run_id`, one ready-for-decision line, one short approval-effect block and one short next-transition block. It must answer only: where am I, what does this decision do, and what happens next. Run and gate identity may anchor both cards; do not duplicate status rows, action inventories or the native question.
 7. Distinguish internal process steps from user decisions in natural language. For example, after `Approval: TP`, say that pre-implementation Brownfield Analysis runs next and that no further user action is required now; do not expose `next_user_gate: none` or `user_action_required: no`, and do not ask for a second approval for Brownfield Analysis.
 8. Ask exactly one question that names the selected `run_id` and `current_gate`.
 9. Offer options in stable order: exact `Approval: <GateName>`, localized revise and localized decline. Add explicit cancel only where supported after decline; otherwise host dismissal maps to cancel. Never preselect, skip, auto-submit or reorder an option.
 10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution; otherwise request the same exact approval in concise text.
-11. Render both cards once in that single complete assistant message. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
+11. Render both cards once in that single complete assistant message. Never merge, reverse, omit or duplicate them; the action heading does not replace either card. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
 12. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
 13. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
 14. Persist accepted input only through the existing control-state workflow.

package/generated/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",

package/generated/plugins/agdf/meta/agdf-interaction-locales.json

@@ -65,6 +65,14 @@
         "CR": "Code review",
         "OR": "Delivery report"
       },
+      "gateActionTitles": {
+        "UR": "Approve user requirements",
+        "PRD": "Approve product requirements",
+        "SD": "Approve solution design",
+        "TP": "Approve task and test plan",
+        "QA": "Approve quality decision",
+        "UAT": "Accept delivery result"
+      },
       "interaction": {
         "ready": "Ready for your decision",
         "approveHeading": "Approve now",
@@ -180,6 +188,14 @@
         "CR": "Code-Review",
         "OR": "Lieferbericht"
       },
+      "gateActionTitles": {
+        "UR": "Nutzeranforderung freigeben",
+        "PRD": "Produktanforderungen freigeben",
+        "SD": "Lösungsdesign freigeben",
+        "TP": "Umsetzungsplan freigeben",
+        "QA": "Qualitätsentscheidung freigeben",
+        "UAT": "Ergebnis abnehmen"
+      },
       "interaction": {
         "ready": "Bereit für deine Entscheidung",
         "approveHeading": "Jetzt freigeben",

package/generated/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
@@ -97,6 +97,8 @@
           "decline"
         ],
         "dismissOutcome": "cancel",
+        "canonicalValueTransport": false,
+        "authorizationPath": "exact_text",
         "technicalPermissionOwner": "codex_host"
       },
       "claude": {
@@ -109,6 +111,8 @@
           "decline"
         ],
         "dismissOutcome": "cancel",
+        "canonicalValueTransport": false,
+        "authorizationPath": "exact_text",
         "technicalPermissionOwner": "claude_host"
       },
       "opencode": {
@@ -121,6 +125,8 @@
           "decline"
         ],
         "dismissOutcome": "cancel",
+        "canonicalValueTransport": false,
+        "authorizationPath": "exact_text",
         "technicalPermissionOwner": "opencode_host"
       },
       "fallback": {
@@ -133,6 +139,8 @@
           "decline",
           "cancel"
         ],
+        "canonicalValueTransport": true,
+        "authorizationPath": "exact_text",
         "technicalPermissionOwner": "host_specific"
       }
     }

package/generated/plugins/agdf/meta/agdf-runtime-contract.md

@@ -181,6 +181,14 @@ before invoking any native question tool or emitting an exact-text approval
 request. Splitting the cards across separate assistant turns or invoking the
 tool after only one card is a failed interaction, not a valid presentation.
 
+The first visible line of that envelope is the localized action-oriented title
+of the current user gate, rendered as a level-two Markdown heading or equivalent
+accessible host heading inside the compact approval-time Run Status Card.
+`AGDF Status`, `Run Status Card`, `Gate Transition Card`, raw gate identifiers
+and machine values are semantic or diagnostic labels only and must not become
+the primary heading. The action title appears exactly once and does not replace,
+merge or reorder either required card block.
+
 The compact approval-time Run Status Card contains exactly six operational
 fields: selected run, readiness status, current gate, missing exact approval,
 one next action and quality outlook. It uses localized human-readable labels

package/generated/plugins/agdf/skills/gate-check/SKILL.md

@@ -63,14 +63,14 @@ For a ready `gate_approval`:
 1. Resolve exactly one selected run and evaluate the current gate.
 2. Confirm the required durable artefact is present and ready before presenting a question.
 3. Build one immutable, non-authorizing presentation snapshot from the selected evaluated run and current revision identity.
-4. Compose one Approval Orientation Envelope as one immediately preceding assistant message containing two distinct blocks. Render the compact localized approval-time Run Status Card first. It contains exactly selected run, readiness status, current gate, missing exact approval, one next action and quality outlook; omit raw keys, machine statuses, evidence, diagnostics and allowed/forbidden inventories.
+4. Compose one Approval Orientation Envelope as one immediately preceding assistant message containing two distinct blocks. Render the compact localized approval-time Run Status Card first. Its first visible line is the localized action-oriented gate title as a level-two Markdown heading or equivalent accessible host heading; generic AGDF/card labels and raw gate IDs cannot be the primary heading. It contains exactly selected run, readiness status, current gate, missing exact approval, one next action and quality outlook; omit raw keys, machine statuses, evidence, diagnostics and allowed/forbidden inventories.
 5. In the same assistant message, render a separate localized Gate Transition Card second, immediately before any native question or exact-text fallback. It includes the deterministic human run title and `UR · PRD · SD · TP` links from the selected run. Never put either card only into the question, button description or hidden tool context. Do not invoke the native question tool until the complete two-card envelope is visible.
 6. Compose the transition card as one human-readable gate title with `run_id`, one ready-for-decision line, one short approval-effect block and one short next-transition block. It must answer only: where am I, what does this decision do, and what happens next. Run and gate identity may anchor both cards; do not duplicate status rows, action inventories or the native question.
 7. Distinguish internal process steps from user decisions in natural language. For example, after `Approval: TP`, say that pre-implementation Brownfield Analysis runs next and that no further user action is required now; do not expose `next_user_gate: none` or `user_action_required: no`, and do not ask for a second approval for Brownfield Analysis.
 8. Ask exactly one question that names the selected `run_id` and `current_gate`.
 9. Offer options in stable order: exact `Approval: <GateName>`, localized revise and localized decline. Add explicit cancel only where supported after decline; otherwise host dismissal maps to cancel. Never preselect, skip, auto-submit or reorder an option.
 10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution; otherwise request the same exact approval in concise text.
-11. Render both cards once in that single complete assistant message. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
+11. Render both cards once in that single complete assistant message. Never merge, reverse, omit or duplicate them; the action heading does not replace either card. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
 12. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
 13. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
 14. Persist accepted input only through the existing control-state workflow.

package/lib/interaction-presentation.js

@@ -70,6 +70,7 @@ export function validateLocaleRegistry(registry) {
     }
     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 +180,10 @@ 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 executeNativeApprovalAttempt({ ready = false, orientationSnapshot, 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 (typeof invokeNative !== "function") return Object.freeze({ attempted: false, outcome: "unavailable_before_invocation", reason: "adapter_unavailable", authorizes: false });
   let adapterResult;
   try {
@@ -280,6 +283,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 +302,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 +320,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 });

package/package.json

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