create-agdf 0.8.3 → 0.8.5

package/bin/create-agdf.js

@@ -2259,10 +2259,14 @@ function buildStatusCard({
   const qualityOutlook = deriveQualityOutlook(runState, findings);
   const postApproval = postApprovalTransition(missingApproval);
   const isUserGateApproval = missingApproval !== "none";
+  const lifecycle = extractField(runState.content ?? "", "lifecycle") || "unknown";
+  const nativeAttemptRequired = status === "open" && isUserGateApproval;
   return {
     run_id: extractField(runState.content ?? "", "run_id") || "unknown",
     presentation_language: chatLanguage,
     mode: extractField(runState.content ?? "", "mode") || "unknown",
+    lifecycle,
+    delivery_state: lifecycle === "completed" && currentGate === "OR" ? "completed_closeout_pending" : lifecycle,
     status,
     current_gate: currentGate,
     mode_slice_decision: runState.mode_slice_decision?.decision || "undecided",
@@ -2280,6 +2284,8 @@ function buildStatusCard({
     next_skill: nextSkillByGate[currentGate] ?? "gate-check",
     next_step: nextAllowedAction,
     quality_outlook: qualityOutlook,
+    interaction_kind: nativeAttemptRequired ? "gate_approval" : status === "blocked" ? "blocked" : "status",
+    native_attempt_required: nativeAttemptRequired,
   };
 }
 
@@ -2736,6 +2742,8 @@ function evaluateGateCheck(targetDir, selection = {}) {
     doctor_summary: doctorReport.summary,
     evidence_refs: runState.evidence_refs,
     quality_outlook: deriveQualityOutlook(runState, deliveryMap.findings),
+    interaction_kind: statusCard.interaction_kind,
+    native_attempt_required: statusCard.native_attempt_required,
     candidate_runs: runState.candidate_runs ?? [],
     status_card: statusCard,
     delivery_map: {
@@ -2764,6 +2772,7 @@ function printGateCheckStatusCard(report) {
   console.log(`${labels.run}: ${card.run_id}`);
   console.log(`${labels.humanTitle}: ${presentation.runTitle}`);
   console.log(`${labels.gate}: ${card.current_gate} — ${presentation.gateTitle}`);
+  console.log(`${labels.lifecycle}: ${primary.lifecycle[card.delivery_state] ?? primary.lifecycle.unknown}`);
   console.log(`${labels.artefacts}: ${formatArtefactRefs(presentation.artefactRefs)}`);
   console.log(`${labels.blocked}: ${card.blocking_condition === "none" ? primary.none : primary.blocked}`);
   console.log(`${labels.missing}: ${card.missing_approval === "none" ? primary.none : card.missing_approval}`);

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

@@ -63,18 +63,24 @@ 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.
 
+The ready-gate projection must expose `native_attempt_required: true`. Treat this as a mandatory
+orchestration instruction: after rendering the two cards, invoke the configured native question
+adapter exactly once before using the exact-text fallback. A hook, permission result or session
+context message cannot replace that attempt or supply its answer. For every non-ready interaction,
+the signal is absent or false and no approval control may be shown.
+
 Before composing the question, resolve the configured chat locale from `.agdf/control/config.json` through `../agdf-interaction-locales.json`: exact complete pack, language subtag, then English fallback. German and English are initial packs, not a closed language list. Keep `Approval: <GateName>` exactly unchanged in every language, and do not mix presentation languages within one interaction. Labels and descriptions use the same resolved locale; host-owned UI chrome remains host-owned and may use a different language.
 
 For the transition card, use the complete resolved locale pack. The initial German pack includes `Bereit für deine Entscheidung`, `Jetzt freigeben` and `Danach`; the initial English pack includes `Ready for your decision`, `Approve now` and `Next`. Keep each card in one locale. Use a localized human-readable gate title rather than an internal status label, while leaving the exact gate identifier and approval value unchanged. Do not render a Markdown table, dashboard rows, raw control-state keys, diagnostic codes, evidence lists, a duplicated gate question or a false user gate in the approval-time card.

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

@@ -25,6 +25,7 @@
         "skill": "Next skill",
         "step": "Next step",
         "quality": "Quality outlook",
+        "lifecycle": "Delivery status",
         "allowed": "Allowed now",
         "forbidden": "Forbidden now",
         "artefacts": "Artefacts"
@@ -64,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",
@@ -91,6 +100,13 @@
         "none": "none",
         "blocked": "current gate prerequisites",
         "quality": "Keep the presentation contract, evidence and gate authority aligned.",
+        "lifecycle": {
+          "active": "in progress",
+          "completed_closeout_pending": "completed — delivery closeout pending",
+          "completed": "completed",
+          "blocked": "blocked",
+          "unknown": "status not available"
+        },
         "actions": {
           "UR": "Clarify and approve the user requirements.",
           "Brownfield Review": "Review existing owners and choose the smallest safe delivery path.",
@@ -132,6 +148,7 @@
         "skill": "Nächster Skill",
         "step": "Nächster Schritt",
         "quality": "Qualitätsausblick",
+        "lifecycle": "Lieferstatus",
         "allowed": "Jetzt erlaubt",
         "forbidden": "Aktuell verboten",
         "artefacts": "Artefakte"
@@ -171,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",
@@ -198,6 +223,13 @@
         "none": "keine",
         "blocked": "Voraussetzungen des aktuellen Gates",
         "quality": "Präsentationsvertrag, Nachweise und Gate-Berechtigung konsistent halten.",
+        "lifecycle": {
+          "active": "in Arbeit",
+          "completed_closeout_pending": "abgeschlossen — Abschluss offen",
+          "completed": "abgeschlossen",
+          "blocked": "blockiert",
+          "unknown": "Status nicht verfügbar"
+        },
         "actions": {
           "UR": "Nutzeranforderungen klären und freigeben.",
           "Brownfield Review": "Bestehende Owner prüfen und den kleinsten sicheren Lieferweg wählen.",

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
@@ -390,6 +398,7 @@ interaction_kind: clarification | tool_permission | gate_approval | blocked | st
 surface: codex | claude | opencode | fallback
 run_id: required for gate_approval
 current_gate: required for gate_approval
+native_attempt_required: true only for an eligible gate_approval before the first adapter attempt
 prompt: required
 options: required for a structured question
 effects: required when the interaction can cause side effects
@@ -420,6 +429,12 @@ Before presenting `gate_approval`, the agent must:
 6. reject missing evidence, ambiguous or wrong run, wrong gate, stale state and any response that is no longer valid;
 7. persist an accepted approval only through the existing control-state workflow.
 
+For an eligible `gate_approval`, `native_attempt_required` is a mandatory orchestration signal. The
+agent must make exactly one configured native adapter attempt after the two orientation cards and
+before any exact-text fallback. Hooks may prepare context but must not answer, approve or replace
+the adapter attempt. The signal is absent or false for clarification, blocked, status-only,
+internal-step and non-ready interactions.
+
 The first eligible native-attempt has a single bounded outcome: the declared
 host control is presented, or the agent immediately uses the exact-text
 fallback. A host that does not apply the control does not trigger a second

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

@@ -25,6 +25,7 @@
         "skill": "Next skill",
         "step": "Next step",
         "quality": "Quality outlook",
+        "lifecycle": "Delivery status",
         "allowed": "Allowed now",
         "forbidden": "Forbidden now",
         "artefacts": "Artefacts"
@@ -64,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",
@@ -91,6 +100,13 @@
         "none": "none",
         "blocked": "current gate prerequisites",
         "quality": "Keep the presentation contract, evidence and gate authority aligned.",
+        "lifecycle": {
+          "active": "in progress",
+          "completed_closeout_pending": "completed — delivery closeout pending",
+          "completed": "completed",
+          "blocked": "blocked",
+          "unknown": "status not available"
+        },
         "actions": {
           "UR": "Clarify and approve the user requirements.",
           "Brownfield Review": "Review existing owners and choose the smallest safe delivery path.",
@@ -132,6 +148,7 @@
         "skill": "Nächster Skill",
         "step": "Nächster Schritt",
         "quality": "Qualitätsausblick",
+        "lifecycle": "Lieferstatus",
         "allowed": "Jetzt erlaubt",
         "forbidden": "Aktuell verboten",
         "artefacts": "Artefakte"
@@ -171,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",
@@ -198,6 +223,13 @@
         "none": "keine",
         "blocked": "Voraussetzungen des aktuellen Gates",
         "quality": "Präsentationsvertrag, Nachweise und Gate-Berechtigung konsistent halten.",
+        "lifecycle": {
+          "active": "in Arbeit",
+          "completed_closeout_pending": "abgeschlossen — Abschluss offen",
+          "completed": "abgeschlossen",
+          "blocked": "blockiert",
+          "unknown": "Status nicht verfügbar"
+        },
         "actions": {
           "UR": "Nutzeranforderungen klären und freigeben.",
           "Brownfield Review": "Bestehende Owner prüfen und den kleinsten sicheren Lieferweg wählen.",

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
@@ -390,6 +398,7 @@ interaction_kind: clarification | tool_permission | gate_approval | blocked | st
 surface: codex | claude | opencode | fallback
 run_id: required for gate_approval
 current_gate: required for gate_approval
+native_attempt_required: true only for an eligible gate_approval before the first adapter attempt
 prompt: required
 options: required for a structured question
 effects: required when the interaction can cause side effects
@@ -420,6 +429,12 @@ Before presenting `gate_approval`, the agent must:
 6. reject missing evidence, ambiguous or wrong run, wrong gate, stale state and any response that is no longer valid;
 7. persist an accepted approval only through the existing control-state workflow.
 
+For an eligible `gate_approval`, `native_attempt_required` is a mandatory orchestration signal. The
+agent must make exactly one configured native adapter attempt after the two orientation cards and
+before any exact-text fallback. Hooks may prepare context but must not answer, approve or replace
+the adapter attempt. The signal is absent or false for clarification, blocked, status-only,
+internal-step and non-ready interactions.
+
 The first eligible native-attempt has a single bounded outcome: the declared
 host control is presented, or the agent immediately uses the exact-text
 fallback. A host that does not apply the control does not trigger a second

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

@@ -63,18 +63,24 @@ 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.
 
+The ready-gate projection must expose `native_attempt_required: true`. Treat this as a mandatory
+orchestration instruction: after rendering the two cards, invoke the configured native question
+adapter exactly once before using the exact-text fallback. A hook, permission result or session
+context message cannot replace that attempt or supply its answer. For every non-ready interaction,
+the signal is absent or false and no approval control may be shown.
+
 Before composing the question, resolve the configured chat locale from `.agdf/control/config.json` through `../../agdf-interaction-locales.json`: exact complete pack, language subtag, then English fallback. German and English are initial packs, not a closed language list. Keep `Approval: <GateName>` exactly unchanged in every language, and do not mix presentation languages within one interaction. Labels and descriptions use the same resolved locale; host-owned UI chrome remains host-owned and may use a different language.
 
 For the transition card, use the complete resolved locale pack. The initial German pack includes `Bereit für deine Entscheidung`, `Jetzt freigeben` and `Danach`; the initial English pack includes `Ready for your decision`, `Approve now` and `Next`. Keep each card in one locale. Use a localized human-readable gate title rather than an internal status label, while leaving the exact gate identifier and approval value unchanged. Do not render a Markdown table, dashboard rows, raw control-state keys, diagnostic codes, evidence lists, a duplicated gate question or a false user gate in the approval-time card.

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

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.8.3",
+  "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

@@ -25,6 +25,7 @@
         "skill": "Next skill",
         "step": "Next step",
         "quality": "Quality outlook",
+        "lifecycle": "Delivery status",
         "allowed": "Allowed now",
         "forbidden": "Forbidden now",
         "artefacts": "Artefacts"
@@ -64,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",
@@ -91,6 +100,13 @@
         "none": "none",
         "blocked": "current gate prerequisites",
         "quality": "Keep the presentation contract, evidence and gate authority aligned.",
+        "lifecycle": {
+          "active": "in progress",
+          "completed_closeout_pending": "completed — delivery closeout pending",
+          "completed": "completed",
+          "blocked": "blocked",
+          "unknown": "status not available"
+        },
         "actions": {
           "UR": "Clarify and approve the user requirements.",
           "Brownfield Review": "Review existing owners and choose the smallest safe delivery path.",
@@ -132,6 +148,7 @@
         "skill": "Nächster Skill",
         "step": "Nächster Schritt",
         "quality": "Qualitätsausblick",
+        "lifecycle": "Lieferstatus",
         "allowed": "Jetzt erlaubt",
         "forbidden": "Aktuell verboten",
         "artefacts": "Artefakte"
@@ -171,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",
@@ -198,6 +223,13 @@
         "none": "keine",
         "blocked": "Voraussetzungen des aktuellen Gates",
         "quality": "Präsentationsvertrag, Nachweise und Gate-Berechtigung konsistent halten.",
+        "lifecycle": {
+          "active": "in Arbeit",
+          "completed_closeout_pending": "abgeschlossen — Abschluss offen",
+          "completed": "abgeschlossen",
+          "blocked": "blockiert",
+          "unknown": "Status nicht verfügbar"
+        },
         "actions": {
           "UR": "Nutzeranforderungen klären und freigeben.",
           "Brownfield Review": "Bestehende Owner prüfen und den kleinsten sicheren Lieferweg wählen.",

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

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.8.3",
+  "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
@@ -390,6 +398,7 @@ interaction_kind: clarification | tool_permission | gate_approval | blocked | st
 surface: codex | claude | opencode | fallback
 run_id: required for gate_approval
 current_gate: required for gate_approval
+native_attempt_required: true only for an eligible gate_approval before the first adapter attempt
 prompt: required
 options: required for a structured question
 effects: required when the interaction can cause side effects
@@ -420,6 +429,12 @@ Before presenting `gate_approval`, the agent must:
 6. reject missing evidence, ambiguous or wrong run, wrong gate, stale state and any response that is no longer valid;
 7. persist an accepted approval only through the existing control-state workflow.
 
+For an eligible `gate_approval`, `native_attempt_required` is a mandatory orchestration signal. The
+agent must make exactly one configured native adapter attempt after the two orientation cards and
+before any exact-text fallback. Hooks may prepare context but must not answer, approve or replace
+the adapter attempt. The signal is absent or false for clarification, blocked, status-only,
+internal-step and non-ready interactions.
+
 The first eligible native-attempt has a single bounded outcome: the declared
 host control is presented, or the agent immediately uses the exact-text
 fallback. A host that does not apply the control does not trigger a second

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

@@ -63,18 +63,24 @@ 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.
 
+The ready-gate projection must expose `native_attempt_required: true`. Treat this as a mandatory
+orchestration instruction: after rendering the two cards, invoke the configured native question
+adapter exactly once before using the exact-text fallback. A hook, permission result or session
+context message cannot replace that attempt or supply its answer. For every non-ready interaction,
+the signal is absent or false and no approval control may be shown.
+
 Before composing the question, resolve the configured chat locale from `.agdf/control/config.json` through `plugin/meta/agdf-interaction-locales.json`: exact complete pack, language subtag, then English fallback. German and English are initial packs, not a closed language list. Keep `Approval: <GateName>` exactly unchanged in every language, and do not mix presentation languages within one interaction. Labels and descriptions use the same resolved locale; host-owned UI chrome remains host-owned and may use a different language.
 
 For the transition card, use the complete resolved locale pack. The initial German pack includes `Bereit für deine Entscheidung`, `Jetzt freigeben` and `Danach`; the initial English pack includes `Ready for your decision`, `Approve now` and `Next`. Keep each card in one locale. Use a localized human-readable gate title rather than an internal status label, while leaving the exact gate identifier and approval value unchanged. Do not render a Markdown table, dashboard rows, raw control-state keys, diagnostic codes, evidence lists, a duplicated gate question or a false user gate in the approval-time card.

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");
@@ -147,6 +148,59 @@ export function buildRunCandidates(runs) {
     .sort((left, right) => left.display_title.localeCompare(right.display_title) || left.run_id.localeCompare(right.run_id));
 }
 
+export function normalizeReconciliationText(value) {
+  return String(value ?? "")
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[._:/\\-]+/g, " ")
+    .replace(/[^\p{L}\p{N}\s]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function reconcileRunScope({ requestText = "", scopeKey = "", runs = [] } = {}) {
+  const requested = normalizeReconciliationText(scopeKey || requestText);
+  if (!requested) return Object.freeze({ outcome: "match_uncertain", matches: [], reason: "scope_input_missing" });
+  const matches = [...(runs ?? [])]
+    .filter((run) => run?.valid && ["active", "completed"].includes(run?.meta?.lifecycle) && typeof run.run_id === "string")
+    .filter((run) => {
+      const keys = [run.scope_key, run.display_title, run.current_artefact_heading, run.ur_heading]
+        .map(normalizeReconciliationText)
+        .filter(Boolean);
+      return keys.includes(requested);
+    })
+    .map((run) => Object.freeze({
+      run_id: run.run_id,
+      lifecycle: run.meta.lifecycle,
+      display_title: displaySafeTitle(run.display_title || run.ur_heading || run.run_id, normalizedRunTitle(run.run_id)),
+      current_gate: run.control_state?.current_gate || run.meta?.current_gate || "unknown",
+    }))
+    .sort((left, right) => left.run_id.localeCompare(right.run_id));
+  if (matches.length !== 1) return Object.freeze({ outcome: matches.length ? "match_uncertain" : "no_match", matches, reason: matches.length > 1 ? "multiple_exact_matches" : "no_exact_match" });
+  return Object.freeze({ outcome: matches[0].lifecycle === "active" ? "active_match" : "completed_match", matches, reason: "exact_match" });
+}
+
+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 {
+    adapterResult = invokeNative();
+  } catch (error) {
+    adapterResult = { outcome: "attempted_not_applied", reason: String(error?.message || "adapter_error") };
+  }
+  const outcome = ATTEMPT_OUTCOMES.has(adapterResult?.outcome)
+    ? adapterResult.outcome
+    : adapterResult?.presented === true || adapterResult?.applied === true
+      ? "presented"
+      : "attempted_not_applied";
+  const reason = String(adapterResult?.reason || "").trim();
+  if (outcome !== "presented" && typeof fallback === "function") fallback({ outcome, reason });
+  return Object.freeze({ attempted: true, outcome, reason, authorizes: false });
+}
+
 export function buildInteractionAttempt({ interactionId, runId, currentGate, surface, attemptOutcome, expectedApproval, fallbackReason = "" }) {
   if (!ATTEMPT_OUTCOMES.has(attemptOutcome)) throw new Error("invalid interaction attempt outcome");
   if (!String(interactionId ?? "").trim() || !String(runId ?? "").trim() || !String(currentGate ?? "").trim())
@@ -229,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}` }),
@@ -247,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,
@@ -258,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.3",
+  "version": "0.8.5",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [