create-agdf 0.8.6 → 0.8.9

package/bin/create-agdf.js

@@ -1531,6 +1531,13 @@ function filled(value) {
   return Boolean(value && !isPlaceholderValue(value) && value.trim() !== "");
 }
 
+function runSelectionRecovery(target) {
+  const directSelection = "Pass --run <run_id> or set AGDF_RUN_ID to select the intended run";
+  return ["doctor", "delivery-map"].includes(target)
+    ? `${directSelection}, or use --all-active to evaluate every active run independently.`
+    : `${directSelection}.`;
+}
+
 function parseQualityContracts(content) {
   const parsed = JSON.parse(content);
   if (!Array.isArray(parsed.contracts) || parsed.contracts.length === 0) {
@@ -1627,7 +1634,7 @@ function evaluateDoctor(targetDir, selection = {}) {
         selectedRunState.resolution_error.split(":")[0] || "AGDF_ACTIVE_RUN_UNRESOLVED",
         `Run selection failed: ${selectedRunState.resolution_error}`,
         runPath,
-        "Pass --run <run_id> or set AGDF_RUN_ID to select the intended run, or use --all-active to evaluate every active run independently.",
+        runSelectionRecovery(selection.target),
       );
     } else {
       const currentGateLine = run.match(/^- current_gate:[^\S\r\n]*(.*)$/m)?.[1]?.trim() ?? "";
@@ -2344,6 +2351,12 @@ const BREADCRUMB_PATH_TEMPLATES = {
 
 const BREADCRUMB_STANDARD_GATES = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 
+function isReadyUserGateApproval({ status, currentGate, missingApproval }) {
+  return status === "open"
+    && BREADCRUMB_STANDARD_GATES.includes(currentGate)
+    && missingApproval === `Approval: ${currentGate}`;
+}
+
 function buildBreadcrumbPath(modeSliceDecision, currentGate, runState) {
   const gates = BREADCRUMB_PATH_TEMPLATES[modeSliceDecision] ?? ["UR"];
   return gates.map((gate) => {
@@ -2381,7 +2394,7 @@ function buildStatusCard({
 }) {
   const qualityOutlook = deriveQualityOutlook(runState, findings);
   const postApproval = postApprovalTransition(missingApproval);
-  const isUserGateApproval = missingApproval !== "none";
+  const isUserGateApproval = isReadyUserGateApproval({ status, currentGate, missingApproval });
   const lifecycle = extractField(runState.content ?? "", "lifecycle") || "unknown";
   const nativeAttemptRequired = false;
   const interactionKind = status === "open" && isUserGateApproval ? "gate_approval" : status === "blocked" ? "blocked" : "status";
@@ -2529,9 +2542,9 @@ function transitionDecisionForRunState(runState, verifiedChange = null) {
 
   if (!isGateSatisfied(runState, "UR")) {
     return {
-      status: "blocked",
+      status: "open",
       current_gate: "UR",
-      blocking_reason: "missing_exact_approval",
+      blocking_reason: "none",
       missing_approval: "Approval: UR",
       allowed: ["clarify user need", "formulate and persist UR", "record evidence", "request exact UR approval"],
       forbidden: ["create PRD", "create SD", "create TP", "run Brownfield Analysis", "implement code", "claim QA or release readiness"],
@@ -2847,7 +2860,7 @@ function evaluateGateCheck(targetDir, selection = {}) {
     enumerable: false,
   });
   attachApprovalOrientationSnapshot(statusCard, {
-    ready: status === "open" && missingApproval === `Approval: ${currentGate}`,
+    ready: isReadyUserGateApproval({ status, currentGate, missingApproval }),
     humanPresentation,
     revisionId: extractField(runState.content ?? "", "revision_id"),
     registry: interactionLocales,
@@ -3280,4 +3293,9 @@ async function main() {
   printNextSteps(options.target, options.dir, files, wroteAgentsFragment, wroteOpenCodeConfigFragment, removedOpenCodeAgents);
 }
 
-await main();
+try {
+  await main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/generated/.github/skills/agdf-clean-implementation-review/SKILL.md

@@ -91,6 +91,11 @@ Use this compact structure:
 - `revise`: solution works but contains avoidable fallback, unclear ownership, or missing evidence.
 - `block`: solution creates a second SoT, a second owner, unbounded fallback, or masks unresolved product semantics.
 
+### Compact Chat Output
+
+At `pass`: one line — `Clean Review: pass — <one-line summary>`.
+At `revise`/`block`: show the specific fallback/workaround/parallel-structure risk with file references.
+
 ## Forbidden
 This skill must not:
 

package/generated/.github/skills/agdf-code-review/SKILL.md

@@ -84,6 +84,11 @@ Use this compact structure:
 - `block`: a hard defect, security risk, data-integrity risk, or unresolved critical uncertainty remains.
 - `not_applicable`: no code changes were present for review.
 
+### Compact Chat Output
+
+At `pass`: one line — `Code Review: pass — <one-line summary>`.
+At `revise`/`block`: show blocking findings with file references. Full report remains in durable file or inline evidence as specified.
+
 ## Forbidden
 This skill must not:
 

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

@@ -69,7 +69,7 @@ For a ready `gate_approval`:
 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.
+10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution and can transport `exact_option_value` or `separate_label_and_value`; never invoke a `decorated_label_only` adapter. Otherwise request the same exact approval in concise text.
 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.
@@ -88,7 +88,7 @@ For the transition card, use the complete resolved locale pack. The initial Germ
 
 The primary option is derived exactly as `Approval: <GateName>` from the evaluated current gate; only explanatory copy and non-authoritative outcome labels are localized. Concrete localized copy belongs to the user-facing interaction layer or the approved delivery artefact, not to English runtime rules.
 
-Make exactly one native-attempt for the ready gate. If the host does not render,
+Make exactly one native-attempt for the eligible ready gate. If the host does not render,
 apply or safely return the native question on that attempt, switch immediately
 to the exact textual approval. Do not ask the user to request the buttons again
 and do not create a retry loop or simulated control.
@@ -102,7 +102,7 @@ only after fresh run/gate/artefact revalidation; never retry automatically.
 
 Surface behavior:
 
-- Codex: invoke the native short-question/request-user-input control on the first eligible attempt when callable, ask one gate question and omit auto-resolution; if it is not rendered or applied, use exact text immediately.
+- Codex: invoke the native short-question/request-user-input control only when preflight proves `exact_option_value` or `separate_label_and_value`, and omit auto-resolution. The canonical `decorated_label_only` capability must use exact text without invoking the adapter. `Approval: <GateName> (Recommended)` is never a valid option or approval.
 - Claude Code: invoke `AskUserQuestion` on the first eligible attempt only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if it is not rendered or applied, use exact text immediately. Claude permissions and `ExitPlanMode` remain separate.
 - OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
 - Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
@@ -125,6 +125,17 @@ After each accepted gate approval is persisted, emit exactly one narration line
 
 When rendering the compact human Run Status Card, collapse internal sub-states (`verified_change` sub-states, `context_graph_required_action`, `multi_scope_state`) to stable human labels. `escalated`, `open_gap` and `blocked` remain explicitly visible. The full machine/audit projection retains all raw values unchanged. See the Runtime Contract §Internal-State Collapse for the complete mapping table.
 
+### On-Demand "Why?" Response
+
+When the user asks "why?" or "Warum?" at any gate or internal step, respond with a `status` interaction (not `gate_approval`):
+
+1. Pull the curated rationale from `gateRationale()` in the resolved locale.
+2. Compose one fulfilled line from the selected run's Approvals table and artefact status.
+3. Compose one protects-against line from the gate's rationale and the existing `primary.actions` copy.
+4. Do not show approval controls. Do not advance any gate. Do not merge with the approval envelope.
+
+The response is deterministic: same gate, same question, same answer. The `gate_approval` options remain exactly `approve | revise | decline | cancel`; no "why" option is added. See the Runtime Contract §Gate-Rationale-Registry and §On-Demand "Why?" Interaction for the full contract.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
@@ -221,6 +232,7 @@ from the same snapshot and are shown exactly once.
 
 If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
 List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.
+See the Runtime Contract §Chat and Tool-Call Discipline for tool-call batching and skill output compaction rules.
 
 ## Forbidden
 This skill must not:

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

@@ -98,7 +98,12 @@
         "declineLabel": "Decline",
         "declineDescription": "Reject this gate deliberately; authority remains unchanged.",
         "cancelLabel": "Cancel",
-        "cancelDescription": "Close this decision without approving or declining it."
+        "cancelDescription": "Close this decision without approving or declining it.",
+        "why": {
+          "label": "Why?",
+          "fulfilledPrefix": "Fulfilled:",
+          "protectsPrefix": "Protects against:"
+        }
       },
       "artefacts": {
         "notYetCreated": "not yet created"
@@ -156,6 +161,20 @@
             "UAT": { "agentNext": "Agent prepares the delivery report" }
           }
         }
+      },
+      "gateRationale": {
+        "UR": "UR clarifies what you want, why and for whom — before anything gets built that nobody needed.",
+        "PRD": "PRD defines product behavior before the solution design locks it in.",
+        "SD": "Solution design fixes ownership, architecture and dependencies — before code makes them permanent.",
+        "TP": "Task plan makes acceptance criteria and tests binding, so QA can measure later.",
+        "QA": "QA evaluates real evidence before a release relies on assumptions.",
+        "UAT": "UAT requires deliberate acceptance before the run counts as delivered.",
+        "Brownfield Review": "Checks whether existing systems, owners and conventions are affected, so nothing breaks or duplicates.",
+        "Mode/Slice Decision": "Decides the proportionate delivery scope, so the process fits the change — not the other way around.",
+        "Brownfield Analysis": "Verifies reuse paths, owners and regression risk before code exists.",
+        "CD+Tests": "Implementation and tests produce evidence — not just code.",
+        "CR": "Code review is mandatory before QA decides.",
+        "OR": "The delivery report makes the run auditable — not just claimed."
       }
     },
     "de": {
@@ -248,7 +267,12 @@
         "declineLabel": "Ablehnen",
         "declineDescription": "Dieses Gate bewusst ablehnen; die Berechtigung bleibt unverändert.",
         "cancelLabel": "Abbrechen",
-        "cancelDescription": "Diese Entscheidung ohne Freigabe oder Ablehnung schließen."
+        "cancelDescription": "Diese Entscheidung ohne Freigabe oder Ablehnung schließen.",
+        "why": {
+          "label": "Warum?",
+          "fulfilledPrefix": "Erfüllt:",
+          "protectsPrefix": "Schützt vor:"
+        }
       },
       "artefacts": {
         "notYetCreated": "noch nicht erstellt"
@@ -306,6 +330,20 @@
             "UAT": { "agentNext": "Agent bereitet den Lieferbericht vor" }
           }
         }
+      },
+      "gateRationale": {
+        "UR": "UR klärt, was du willst, warum und für wen — bevor etwas gebaut wird, das niemand brauchte.",
+        "PRD": "PRD definiert das Produktverhalten, bevor das Lösungsdesign es zementiert.",
+        "SD": "Lösungsdesign legt Ownership, Architektur und Abhängigkeiten fest — bevor Code sie faktisch zementiert.",
+        "TP": "Taskplan macht Akzeptanzkriterien und Tests verbindlich, damit QA später messen kann.",
+        "QA": "QA bewertet die echten Nachweise, bevor eine Freigabe auf Vermutungen basiert.",
+        "UAT": "UAT verlangt eine bewusste Abnahme, bevor der Lauf als geliefert gilt.",
+        "Brownfield Review": "Prüft, ob bestehende Systeme, Owners und Konventionen betroffen sind, damit nichts kaputt geht oder doppelt entsteht.",
+        "Mode/Slice Decision": "Entscheidet den angemessenen Lieferumfang, damit der Prozess zur Veränderung passt — nicht umgekehrt.",
+        "Brownfield Analysis": "Verifiziert Wiederverwendung, Owners und Regressionstests, bevor Code existiert.",
+        "CD+Tests": "Implementierung und Tests liefern Nachweise — nicht nur Code.",
+        "CR": "Code-Review ist verpflichtend, bevor QA entscheidet.",
+        "OR": "Der Lieferbericht macht den Lauf auditierbar — nicht nur behauptet."
       }
     }
   }

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

@@ -102,6 +102,12 @@ Use this shape:
 
 If Context Graph impact is relevant, include the fields from `../agdf-runtime-contract.md`.
 
+### Compact Chat Output
+
+At `pass`: one line — `QA: pass — <one-line summary>`. Reference the durable QA report
+path. Do not show the Quality Readiness projection or evidence inventory in chat.
+At `revise`/`block`: show the decisive dimension, reason and next action.
+
 ## Decision Guidance
 - `pass`: required TP tasks are done, evidence is strong, no blocking Brownfield or solution-integrity risk remains.
 - `revise`: implementation is plausible but missing evidence, partial tasks, UX gaps, or fixable integrity issues remain.

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

@@ -402,6 +402,42 @@ When a skill creates or updates `.agdf/control/` files, gate artefacts, reviews,
 Do not paste full control files, full artefact bodies, full templates or full generated reports into the chat unless the user explicitly asks to see the full content.
 For larger or more formal work, create or update the durable artefacts fully, then reference them by path and summarize what changed.
 
+### Chat and Tool-Call Discipline
+
+Chat output shows decisions and outcomes. Files show evidence and detail. The agent
+minimises both the number of tool calls and the amount of accompanying chat text. This
+is surface-agnostic: it changes agent behaviour and framework text, not host rendering.
+Whether a host renders a tool-call block visibly is a host concern; the framework ensures
+the agent makes fewer calls and produces less text around them.
+
+Skill output compaction:
+
+- QA, Code Review, TP Review and Clean Implementation Review output is 1 line at `pass`:
+  `<skill>: pass — <one-line summary>`.
+- At `revise`/`block`: the decisive dimension, reason and next action. The Quality
+  Readiness projection is shown only at `revise`/`block`, not at `pass`.
+- Full reports remain in durable files; the chat references the path.
+
+Tool-call batching:
+
+- `RUN_STATE.md` is written once per user gate approval, not once per field change. The
+  agent keeps intermediate state in memory between gate approvals and writes the complete
+  updated state in one operation.
+- The agent does not `read` existing artefacts for format reference. Skill instructions
+  carry the format/structure inline. If a specific existing artefact must be inspected
+  for content (not format), the read has no accompanying commentary.
+- Artefact writes are silent: the agent names the path and a 1-line summary only when an
+  artefact is first created or significantly changed — not on every state update.
+- Validation commands (tests, integrity, diff) show pass/fail only. Full output appears
+  only on failure.
+
+Always visible:
+
+- Gate decisions (Run Status Card, Gate Transition Card, approval question).
+- Post-acceptance narration (1 line per gate transition).
+- Delivery summary (UAT/OR compact summary).
+- Errors, blockers and evidence at `revise`/`block`.
+
 ## Relevant Run
 
 A relevant run is any run that changes durable state, creates or updates an AGDF artefact, changes code or runtime behaviour, performs a gate decision, blocks on a governance condition, produces QA/UAT/release evidence, or closes a delivery slice.
@@ -497,6 +533,9 @@ with safe deliberate waiting. Decorated-only, missing, conflicting or unknown ca
 `unavailable_before_invocation`; unsafe waiting fails closed to `unsafe_to_wait`. Both expose false and use
 exact text without invoking the adapter. A report-only CLI evaluation has no verified current host adapter
 and therefore exposes false. Hooks may prepare context but must not answer, approve or replace an eligible attempt.
+An adapter that requires a visible suffix such as `(Recommended)` on its approving option is
+`decorated_label_only`: do not invoke it for an AGDF gate. `Approval: <GateName> (Recommended)` is never a
+valid AGDF approval option or authorization value; use the undecorated exact-text fallback instead.
 
 The first eligible native-attempt has a single bounded outcome: the declared
 host control is presented, or the agent immediately uses the exact-text
@@ -518,7 +557,7 @@ Surface adapter rules:
 
 | Surface | Native question adapter | Gate-safe use | Technical permission boundary |
 |---|---|---|---|
-| Codex | native `request_user_input` or equivalent short-question control when callable | on the first eligible attempt, present one gate question with auto-resolution omitted; if unavailable or not applied, use exact text without retry | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
+| Codex | native `request_user_input` or equivalent short-question control when callable | invoke only when preflight proves `exact_option_value` or `separate_label_and_value`; the current canonical `decorated_label_only` capability uses exact text without invoking the adapter | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
 | Claude Code | `AskUserQuestion` | on the first eligible attempt, use only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if unavailable or not applied, use exact text without retry | Claude permissions and `ExitPlanMode` are not AGDF approval. |
 | OpenCode | built-in `question` | use with exact approval/revise/cancel options when `permission.question` permits it; explicit user deny selects exact-text fallback | `once`, `always`, `reject`, permission suggestions and auto mode are technical outcomes only. |
 | Fallback or non-interactive | concise exact text | wait for a new explicit user response; never synthesize or auto-resolve one | Host-specific technical permission remains separate. |
@@ -545,6 +584,39 @@ fallback and human CLI output use the configured project chat language from
 
 The locale changes presentation only. It must not change gate meaning, option ordering, readiness, validation, revalidation or persistence. Host-provided free-text labels and skip actions are not AGDF-owned approval options and must never advance a gate.
 
+### Gate-Rationale-Registry
+
+The locale registry contains a deterministic, localized `gateRationale` section with one
+curated one-liner per gate and internal step. The agent retrieves rationale strings via
+the `gateRationale()` function; it does not generate rationale prose. Rationale strings
+are the same across invocations for the same gate and locale.
+
+The registry covers all user gates (`UR`, `PRD`, `SD`, `TP`, `QA`, `UAT`) and all internal
+steps (`Brownfield Review`, `Mode/Slice Decision`, `Brownfield Analysis`, `CD+Tests`, `CR`,
+`OR`). Each string stays within the declared `lengthBudgets.description` budget. Key parity
+across locale packs is enforced by the existing `validateLocaleRegistry` baseline
+comparison.
+
+A one-liner cannot explain the full protective function. The user needs enough to accept
+that the gate makes sense, not the complete rationale. Deeper context is available on
+demand through the "Why?" interaction.
+
+### On-Demand "Why?" Interaction
+
+When the user asks "why?" at any gate or internal step, the agent responds with a `status`
+interaction containing the curated rationale (Gate-Rationale-Registry) plus one line of
+fulfilled/protects context composed from existing state.
+
+- The response is deterministic, non-authorizing, and does not display approval controls.
+- It is a separate `status` interaction, never merged with the `gate_approval` sequence.
+- The `gate_approval` options remain exactly `approve | revise | decline | cancel`; no
+  "why" option is added.
+- The response never breaks `APPROVAL_SEQUENCE` or `validateApprovalOrientationSnapshot`.
+- Default output is unchanged when the user does not ask.
+- The fulfilled line is composed from the selected run's Approvals table and artefact
+  status; the protects-against line is composed from the gate's rationale and existing
+  `primary.actions` copy. The agent does not generate new prose.
+
 ### Human Decision Presentation Contract
 
 The primary user surface is a pure projection of the selected canonical run.

package/generated/.github/skills/agdf-task-plan-review/SKILL.md

@@ -105,6 +105,11 @@ Evidence confidence:
 - `medium`
 - `low`
 
+### Compact Chat Output
+
+At `pass`: one line — `TP Review: pass — <X>/<total> tasks fully_done`.
+At `revise`/`block`: show incomplete tasks with missing evidence.
+
 ## Forbidden
 This skill must not:
 

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

@@ -98,7 +98,12 @@
         "declineLabel": "Decline",
         "declineDescription": "Reject this gate deliberately; authority remains unchanged.",
         "cancelLabel": "Cancel",
-        "cancelDescription": "Close this decision without approving or declining it."
+        "cancelDescription": "Close this decision without approving or declining it.",
+        "why": {
+          "label": "Why?",
+          "fulfilledPrefix": "Fulfilled:",
+          "protectsPrefix": "Protects against:"
+        }
       },
       "artefacts": {
         "notYetCreated": "not yet created"
@@ -156,6 +161,20 @@
             "UAT": { "agentNext": "Agent prepares the delivery report" }
           }
         }
+      },
+      "gateRationale": {
+        "UR": "UR clarifies what you want, why and for whom — before anything gets built that nobody needed.",
+        "PRD": "PRD defines product behavior before the solution design locks it in.",
+        "SD": "Solution design fixes ownership, architecture and dependencies — before code makes them permanent.",
+        "TP": "Task plan makes acceptance criteria and tests binding, so QA can measure later.",
+        "QA": "QA evaluates real evidence before a release relies on assumptions.",
+        "UAT": "UAT requires deliberate acceptance before the run counts as delivered.",
+        "Brownfield Review": "Checks whether existing systems, owners and conventions are affected, so nothing breaks or duplicates.",
+        "Mode/Slice Decision": "Decides the proportionate delivery scope, so the process fits the change — not the other way around.",
+        "Brownfield Analysis": "Verifies reuse paths, owners and regression risk before code exists.",
+        "CD+Tests": "Implementation and tests produce evidence — not just code.",
+        "CR": "Code review is mandatory before QA decides.",
+        "OR": "The delivery report makes the run auditable — not just claimed."
       }
     },
     "de": {
@@ -248,7 +267,12 @@
         "declineLabel": "Ablehnen",
         "declineDescription": "Dieses Gate bewusst ablehnen; die Berechtigung bleibt unverändert.",
         "cancelLabel": "Abbrechen",
-        "cancelDescription": "Diese Entscheidung ohne Freigabe oder Ablehnung schließen."
+        "cancelDescription": "Diese Entscheidung ohne Freigabe oder Ablehnung schließen.",
+        "why": {
+          "label": "Warum?",
+          "fulfilledPrefix": "Erfüllt:",
+          "protectsPrefix": "Schützt vor:"
+        }
       },
       "artefacts": {
         "notYetCreated": "noch nicht erstellt"
@@ -306,6 +330,20 @@
             "UAT": { "agentNext": "Agent bereitet den Lieferbericht vor" }
           }
         }
+      },
+      "gateRationale": {
+        "UR": "UR klärt, was du willst, warum und für wen — bevor etwas gebaut wird, das niemand brauchte.",
+        "PRD": "PRD definiert das Produktverhalten, bevor das Lösungsdesign es zementiert.",
+        "SD": "Lösungsdesign legt Ownership, Architektur und Abhängigkeiten fest — bevor Code sie faktisch zementiert.",
+        "TP": "Taskplan macht Akzeptanzkriterien und Tests verbindlich, damit QA später messen kann.",
+        "QA": "QA bewertet die echten Nachweise, bevor eine Freigabe auf Vermutungen basiert.",
+        "UAT": "UAT verlangt eine bewusste Abnahme, bevor der Lauf als geliefert gilt.",
+        "Brownfield Review": "Prüft, ob bestehende Systeme, Owners und Konventionen betroffen sind, damit nichts kaputt geht oder doppelt entsteht.",
+        "Mode/Slice Decision": "Entscheidet den angemessenen Lieferumfang, damit der Prozess zur Veränderung passt — nicht umgekehrt.",
+        "Brownfield Analysis": "Verifiziert Wiederverwendung, Owners und Regressionstests, bevor Code existiert.",
+        "CD+Tests": "Implementierung und Tests liefern Nachweise — nicht nur Code.",
+        "CR": "Code-Review ist verpflichtend, bevor QA entscheidet.",
+        "OR": "Der Lieferbericht macht den Lauf auditierbar — nicht nur behauptet."
       }
     }
   }

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

@@ -402,6 +402,42 @@ When a skill creates or updates `.agdf/control/` files, gate artefacts, reviews,
 Do not paste full control files, full artefact bodies, full templates or full generated reports into the chat unless the user explicitly asks to see the full content.
 For larger or more formal work, create or update the durable artefacts fully, then reference them by path and summarize what changed.
 
+### Chat and Tool-Call Discipline
+
+Chat output shows decisions and outcomes. Files show evidence and detail. The agent
+minimises both the number of tool calls and the amount of accompanying chat text. This
+is surface-agnostic: it changes agent behaviour and framework text, not host rendering.
+Whether a host renders a tool-call block visibly is a host concern; the framework ensures
+the agent makes fewer calls and produces less text around them.
+
+Skill output compaction:
+
+- QA, Code Review, TP Review and Clean Implementation Review output is 1 line at `pass`:
+  `<skill>: pass — <one-line summary>`.
+- At `revise`/`block`: the decisive dimension, reason and next action. The Quality
+  Readiness projection is shown only at `revise`/`block`, not at `pass`.
+- Full reports remain in durable files; the chat references the path.
+
+Tool-call batching:
+
+- `RUN_STATE.md` is written once per user gate approval, not once per field change. The
+  agent keeps intermediate state in memory between gate approvals and writes the complete
+  updated state in one operation.
+- The agent does not `read` existing artefacts for format reference. Skill instructions
+  carry the format/structure inline. If a specific existing artefact must be inspected
+  for content (not format), the read has no accompanying commentary.
+- Artefact writes are silent: the agent names the path and a 1-line summary only when an
+  artefact is first created or significantly changed — not on every state update.
+- Validation commands (tests, integrity, diff) show pass/fail only. Full output appears
+  only on failure.
+
+Always visible:
+
+- Gate decisions (Run Status Card, Gate Transition Card, approval question).
+- Post-acceptance narration (1 line per gate transition).
+- Delivery summary (UAT/OR compact summary).
+- Errors, blockers and evidence at `revise`/`block`.
+
 ## Relevant Run
 
 A relevant run is any run that changes durable state, creates or updates an AGDF artefact, changes code or runtime behaviour, performs a gate decision, blocks on a governance condition, produces QA/UAT/release evidence, or closes a delivery slice.
@@ -497,6 +533,9 @@ with safe deliberate waiting. Decorated-only, missing, conflicting or unknown ca
 `unavailable_before_invocation`; unsafe waiting fails closed to `unsafe_to_wait`. Both expose false and use
 exact text without invoking the adapter. A report-only CLI evaluation has no verified current host adapter
 and therefore exposes false. Hooks may prepare context but must not answer, approve or replace an eligible attempt.
+An adapter that requires a visible suffix such as `(Recommended)` on its approving option is
+`decorated_label_only`: do not invoke it for an AGDF gate. `Approval: <GateName> (Recommended)` is never a
+valid AGDF approval option or authorization value; use the undecorated exact-text fallback instead.
 
 The first eligible native-attempt has a single bounded outcome: the declared
 host control is presented, or the agent immediately uses the exact-text
@@ -518,7 +557,7 @@ Surface adapter rules:
 
 | Surface | Native question adapter | Gate-safe use | Technical permission boundary |
 |---|---|---|---|
-| Codex | native `request_user_input` or equivalent short-question control when callable | on the first eligible attempt, present one gate question with auto-resolution omitted; if unavailable or not applied, use exact text without retry | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
+| Codex | native `request_user_input` or equivalent short-question control when callable | invoke only when preflight proves `exact_option_value` or `separate_label_and_value`; the current canonical `decorated_label_only` capability uses exact text without invoking the adapter | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
 | Claude Code | `AskUserQuestion` | on the first eligible attempt, use only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if unavailable or not applied, use exact text without retry | Claude permissions and `ExitPlanMode` are not AGDF approval. |
 | OpenCode | built-in `question` | use with exact approval/revise/cancel options when `permission.question` permits it; explicit user deny selects exact-text fallback | `once`, `always`, `reject`, permission suggestions and auto mode are technical outcomes only. |
 | Fallback or non-interactive | concise exact text | wait for a new explicit user response; never synthesize or auto-resolve one | Host-specific technical permission remains separate. |
@@ -545,6 +584,39 @@ fallback and human CLI output use the configured project chat language from
 
 The locale changes presentation only. It must not change gate meaning, option ordering, readiness, validation, revalidation or persistence. Host-provided free-text labels and skip actions are not AGDF-owned approval options and must never advance a gate.
 
+### Gate-Rationale-Registry
+
+The locale registry contains a deterministic, localized `gateRationale` section with one
+curated one-liner per gate and internal step. The agent retrieves rationale strings via
+the `gateRationale()` function; it does not generate rationale prose. Rationale strings
+are the same across invocations for the same gate and locale.
+
+The registry covers all user gates (`UR`, `PRD`, `SD`, `TP`, `QA`, `UAT`) and all internal
+steps (`Brownfield Review`, `Mode/Slice Decision`, `Brownfield Analysis`, `CD+Tests`, `CR`,
+`OR`). Each string stays within the declared `lengthBudgets.description` budget. Key parity
+across locale packs is enforced by the existing `validateLocaleRegistry` baseline
+comparison.
+
+A one-liner cannot explain the full protective function. The user needs enough to accept
+that the gate makes sense, not the complete rationale. Deeper context is available on
+demand through the "Why?" interaction.
+
+### On-Demand "Why?" Interaction
+
+When the user asks "why?" at any gate or internal step, the agent responds with a `status`
+interaction containing the curated rationale (Gate-Rationale-Registry) plus one line of
+fulfilled/protects context composed from existing state.
+
+- The response is deterministic, non-authorizing, and does not display approval controls.
+- It is a separate `status` interaction, never merged with the `gate_approval` sequence.
+- The `gate_approval` options remain exactly `approve | revise | decline | cancel`; no
+  "why" option is added.
+- The response never breaks `APPROVAL_SEQUENCE` or `validateApprovalOrientationSnapshot`.
+- Default output is unchanged when the user does not ask.
+- The fulfilled line is composed from the selected run's Approvals table and artefact
+  status; the protects-against line is composed from the gate's rationale and existing
+  `primary.actions` copy. The agent does not generate new prose.
+
 ### Human Decision Presentation Contract
 
 The primary user surface is a pure projection of the selected canonical run.

package/generated/.opencode/skills/agdf-clean-implementation-review/SKILL.md

@@ -91,6 +91,11 @@ Use this compact structure:
 - `revise`: solution works but contains avoidable fallback, unclear ownership, or missing evidence.
 - `block`: solution creates a second SoT, a second owner, unbounded fallback, or masks unresolved product semantics.
 
+### Compact Chat Output
+
+At `pass`: one line — `Clean Review: pass — <one-line summary>`.
+At `revise`/`block`: show the specific fallback/workaround/parallel-structure risk with file references.
+
 ## Forbidden
 This skill must not:
 

package/generated/.opencode/skills/agdf-code-review/SKILL.md

@@ -84,6 +84,11 @@ Use this compact structure:
 - `block`: a hard defect, security risk, data-integrity risk, or unresolved critical uncertainty remains.
 - `not_applicable`: no code changes were present for review.
 
+### Compact Chat Output
+
+At `pass`: one line — `Code Review: pass — <one-line summary>`.
+At `revise`/`block`: show blocking findings with file references. Full report remains in durable file or inline evidence as specified.
+
 ## Forbidden
 This skill must not:
 

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

@@ -69,7 +69,7 @@ For a ready `gate_approval`:
 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.
+10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution and can transport `exact_option_value` or `separate_label_and_value`; never invoke a `decorated_label_only` adapter. Otherwise request the same exact approval in concise text.
 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.
@@ -88,7 +88,7 @@ For the transition card, use the complete resolved locale pack. The initial Germ
 
 The primary option is derived exactly as `Approval: <GateName>` from the evaluated current gate; only explanatory copy and non-authoritative outcome labels are localized. Concrete localized copy belongs to the user-facing interaction layer or the approved delivery artefact, not to English runtime rules.
 
-Make exactly one native-attempt for the ready gate. If the host does not render,
+Make exactly one native-attempt for the eligible ready gate. If the host does not render,
 apply or safely return the native question on that attempt, switch immediately
 to the exact textual approval. Do not ask the user to request the buttons again
 and do not create a retry loop or simulated control.
@@ -102,7 +102,7 @@ only after fresh run/gate/artefact revalidation; never retry automatically.
 
 Surface behavior:
 
-- Codex: invoke the native short-question/request-user-input control on the first eligible attempt when callable, ask one gate question and omit auto-resolution; if it is not rendered or applied, use exact text immediately.
+- Codex: invoke the native short-question/request-user-input control only when preflight proves `exact_option_value` or `separate_label_and_value`, and omit auto-resolution. The canonical `decorated_label_only` capability must use exact text without invoking the adapter. `Approval: <GateName> (Recommended)` is never a valid option or approval.
 - Claude Code: invoke `AskUserQuestion` on the first eligible attempt only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if it is not rendered or applied, use exact text immediately. Claude permissions and `ExitPlanMode` remain separate.
 - OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
 - Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
@@ -125,6 +125,17 @@ After each accepted gate approval is persisted, emit exactly one narration line
 
 When rendering the compact human Run Status Card, collapse internal sub-states (`verified_change` sub-states, `context_graph_required_action`, `multi_scope_state`) to stable human labels. `escalated`, `open_gap` and `blocked` remain explicitly visible. The full machine/audit projection retains all raw values unchanged. See the Runtime Contract §Internal-State Collapse for the complete mapping table.
 
+### On-Demand "Why?" Response
+
+When the user asks "why?" or "Warum?" at any gate or internal step, respond with a `status` interaction (not `gate_approval`):
+
+1. Pull the curated rationale from `gateRationale()` in the resolved locale.
+2. Compose one fulfilled line from the selected run's Approvals table and artefact status.
+3. Compose one protects-against line from the gate's rationale and the existing `primary.actions` copy.
+4. Do not show approval controls. Do not advance any gate. Do not merge with the approval envelope.
+
+The response is deterministic: same gate, same question, same answer. The `gate_approval` options remain exactly `approve | revise | decline | cancel`; no "why" option is added. See the Runtime Contract §Gate-Rationale-Registry and §On-Demand "Why?" Interaction for the full contract.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
@@ -221,6 +232,7 @@ from the same snapshot and are shown exactly once.
 
 If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
 List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.
+See the Runtime Contract §Chat and Tool-Call Discipline for tool-call batching and skill output compaction rules.
 
 ## Forbidden
 This skill must not:

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

@@ -102,6 +102,12 @@ Use this shape:
 
 If Context Graph impact is relevant, include the fields from `../../agdf-runtime-contract.md`.
 
+### Compact Chat Output
+
+At `pass`: one line — `QA: pass — <one-line summary>`. Reference the durable QA report
+path. Do not show the Quality Readiness projection or evidence inventory in chat.
+At `revise`/`block`: show the decisive dimension, reason and next action.
+
 ## Decision Guidance
 - `pass`: required TP tasks are done, evidence is strong, no blocking Brownfield or solution-integrity risk remains.
 - `revise`: implementation is plausible but missing evidence, partial tasks, UX gaps, or fixable integrity issues remain.

package/generated/.opencode/skills/agdf-task-plan-review/SKILL.md

@@ -105,6 +105,11 @@ Evidence confidence:
 - `medium`
 - `low`
 
+### Compact Chat Output
+
+At `pass`: one line — `TP Review: pass — <X>/<total> tasks fully_done`.
+At `revise`/`block`: show incomplete tasks with missing evidence.
+
 ## Forbidden
 This skill must not:
 

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

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

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

@@ -98,7 +98,12 @@
         "declineLabel": "Decline",
         "declineDescription": "Reject this gate deliberately; authority remains unchanged.",
         "cancelLabel": "Cancel",
-        "cancelDescription": "Close this decision without approving or declining it."
+        "cancelDescription": "Close this decision without approving or declining it.",
+        "why": {
+          "label": "Why?",
+          "fulfilledPrefix": "Fulfilled:",
+          "protectsPrefix": "Protects against:"
+        }
       },
       "artefacts": {
         "notYetCreated": "not yet created"
@@ -156,6 +161,20 @@
             "UAT": { "agentNext": "Agent prepares the delivery report" }
           }
         }
+      },
+      "gateRationale": {
+        "UR": "UR clarifies what you want, why and for whom — before anything gets built that nobody needed.",
+        "PRD": "PRD defines product behavior before the solution design locks it in.",
+        "SD": "Solution design fixes ownership, architecture and dependencies — before code makes them permanent.",
+        "TP": "Task plan makes acceptance criteria and tests binding, so QA can measure later.",
+        "QA": "QA evaluates real evidence before a release relies on assumptions.",
+        "UAT": "UAT requires deliberate acceptance before the run counts as delivered.",
+        "Brownfield Review": "Checks whether existing systems, owners and conventions are affected, so nothing breaks or duplicates.",
+        "Mode/Slice Decision": "Decides the proportionate delivery scope, so the process fits the change — not the other way around.",
+        "Brownfield Analysis": "Verifies reuse paths, owners and regression risk before code exists.",
+        "CD+Tests": "Implementation and tests produce evidence — not just code.",
+        "CR": "Code review is mandatory before QA decides.",
+        "OR": "The delivery report makes the run auditable — not just claimed."
       }
     },
     "de": {
@@ -248,7 +267,12 @@
         "declineLabel": "Ablehnen",
         "declineDescription": "Dieses Gate bewusst ablehnen; die Berechtigung bleibt unverändert.",
         "cancelLabel": "Abbrechen",
-        "cancelDescription": "Diese Entscheidung ohne Freigabe oder Ablehnung schließen."
+        "cancelDescription": "Diese Entscheidung ohne Freigabe oder Ablehnung schließen.",
+        "why": {
+          "label": "Warum?",
+          "fulfilledPrefix": "Erfüllt:",
+          "protectsPrefix": "Schützt vor:"
+        }
       },
       "artefacts": {
         "notYetCreated": "noch nicht erstellt"
@@ -306,6 +330,20 @@
             "UAT": { "agentNext": "Agent bereitet den Lieferbericht vor" }
           }
         }
+      },
+      "gateRationale": {
+        "UR": "UR klärt, was du willst, warum und für wen — bevor etwas gebaut wird, das niemand brauchte.",
+        "PRD": "PRD definiert das Produktverhalten, bevor das Lösungsdesign es zementiert.",
+        "SD": "Lösungsdesign legt Ownership, Architektur und Abhängigkeiten fest — bevor Code sie faktisch zementiert.",
+        "TP": "Taskplan macht Akzeptanzkriterien und Tests verbindlich, damit QA später messen kann.",
+        "QA": "QA bewertet die echten Nachweise, bevor eine Freigabe auf Vermutungen basiert.",
+        "UAT": "UAT verlangt eine bewusste Abnahme, bevor der Lauf als geliefert gilt.",
+        "Brownfield Review": "Prüft, ob bestehende Systeme, Owners und Konventionen betroffen sind, damit nichts kaputt geht oder doppelt entsteht.",
+        "Mode/Slice Decision": "Entscheidet den angemessenen Lieferumfang, damit der Prozess zur Veränderung passt — nicht umgekehrt.",
+        "Brownfield Analysis": "Verifiziert Wiederverwendung, Owners und Regressionstests, bevor Code existiert.",
+        "CD+Tests": "Implementierung und Tests liefern Nachweise — nicht nur Code.",
+        "CR": "Code-Review ist verpflichtend, bevor QA entscheidet.",
+        "OR": "Der Lieferbericht macht den Lauf auditierbar — nicht nur behauptet."
       }
     }
   }

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

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.8.6",
+  "version": "0.8.9",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",

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

@@ -402,6 +402,42 @@ When a skill creates or updates `.agdf/control/` files, gate artefacts, reviews,
 Do not paste full control files, full artefact bodies, full templates or full generated reports into the chat unless the user explicitly asks to see the full content.
 For larger or more formal work, create or update the durable artefacts fully, then reference them by path and summarize what changed.
 
+### Chat and Tool-Call Discipline
+
+Chat output shows decisions and outcomes. Files show evidence and detail. The agent
+minimises both the number of tool calls and the amount of accompanying chat text. This
+is surface-agnostic: it changes agent behaviour and framework text, not host rendering.
+Whether a host renders a tool-call block visibly is a host concern; the framework ensures
+the agent makes fewer calls and produces less text around them.
+
+Skill output compaction:
+
+- QA, Code Review, TP Review and Clean Implementation Review output is 1 line at `pass`:
+  `<skill>: pass — <one-line summary>`.
+- At `revise`/`block`: the decisive dimension, reason and next action. The Quality
+  Readiness projection is shown only at `revise`/`block`, not at `pass`.
+- Full reports remain in durable files; the chat references the path.
+
+Tool-call batching:
+
+- `RUN_STATE.md` is written once per user gate approval, not once per field change. The
+  agent keeps intermediate state in memory between gate approvals and writes the complete
+  updated state in one operation.
+- The agent does not `read` existing artefacts for format reference. Skill instructions
+  carry the format/structure inline. If a specific existing artefact must be inspected
+  for content (not format), the read has no accompanying commentary.
+- Artefact writes are silent: the agent names the path and a 1-line summary only when an
+  artefact is first created or significantly changed — not on every state update.
+- Validation commands (tests, integrity, diff) show pass/fail only. Full output appears
+  only on failure.
+
+Always visible:
+
+- Gate decisions (Run Status Card, Gate Transition Card, approval question).
+- Post-acceptance narration (1 line per gate transition).
+- Delivery summary (UAT/OR compact summary).
+- Errors, blockers and evidence at `revise`/`block`.
+
 ## Relevant Run
 
 A relevant run is any run that changes durable state, creates or updates an AGDF artefact, changes code or runtime behaviour, performs a gate decision, blocks on a governance condition, produces QA/UAT/release evidence, or closes a delivery slice.
@@ -497,6 +533,9 @@ with safe deliberate waiting. Decorated-only, missing, conflicting or unknown ca
 `unavailable_before_invocation`; unsafe waiting fails closed to `unsafe_to_wait`. Both expose false and use
 exact text without invoking the adapter. A report-only CLI evaluation has no verified current host adapter
 and therefore exposes false. Hooks may prepare context but must not answer, approve or replace an eligible attempt.
+An adapter that requires a visible suffix such as `(Recommended)` on its approving option is
+`decorated_label_only`: do not invoke it for an AGDF gate. `Approval: <GateName> (Recommended)` is never a
+valid AGDF approval option or authorization value; use the undecorated exact-text fallback instead.
 
 The first eligible native-attempt has a single bounded outcome: the declared
 host control is presented, or the agent immediately uses the exact-text
@@ -518,7 +557,7 @@ Surface adapter rules:
 
 | Surface | Native question adapter | Gate-safe use | Technical permission boundary |
 |---|---|---|---|
-| Codex | native `request_user_input` or equivalent short-question control when callable | on the first eligible attempt, present one gate question with auto-resolution omitted; if unavailable or not applied, use exact text without retry | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
+| Codex | native `request_user_input` or equivalent short-question control when callable | invoke only when preflight proves `exact_option_value` or `separate_label_and_value`; the current canonical `decorated_label_only` capability uses exact text without invoking the adapter | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
 | Claude Code | `AskUserQuestion` | on the first eligible attempt, use only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if unavailable or not applied, use exact text without retry | Claude permissions and `ExitPlanMode` are not AGDF approval. |
 | OpenCode | built-in `question` | use with exact approval/revise/cancel options when `permission.question` permits it; explicit user deny selects exact-text fallback | `once`, `always`, `reject`, permission suggestions and auto mode are technical outcomes only. |
 | Fallback or non-interactive | concise exact text | wait for a new explicit user response; never synthesize or auto-resolve one | Host-specific technical permission remains separate. |
@@ -545,6 +584,39 @@ fallback and human CLI output use the configured project chat language from
 
 The locale changes presentation only. It must not change gate meaning, option ordering, readiness, validation, revalidation or persistence. Host-provided free-text labels and skip actions are not AGDF-owned approval options and must never advance a gate.
 
+### Gate-Rationale-Registry
+
+The locale registry contains a deterministic, localized `gateRationale` section with one
+curated one-liner per gate and internal step. The agent retrieves rationale strings via
+the `gateRationale()` function; it does not generate rationale prose. Rationale strings
+are the same across invocations for the same gate and locale.
+
+The registry covers all user gates (`UR`, `PRD`, `SD`, `TP`, `QA`, `UAT`) and all internal
+steps (`Brownfield Review`, `Mode/Slice Decision`, `Brownfield Analysis`, `CD+Tests`, `CR`,
+`OR`). Each string stays within the declared `lengthBudgets.description` budget. Key parity
+across locale packs is enforced by the existing `validateLocaleRegistry` baseline
+comparison.
+
+A one-liner cannot explain the full protective function. The user needs enough to accept
+that the gate makes sense, not the complete rationale. Deeper context is available on
+demand through the "Why?" interaction.
+
+### On-Demand "Why?" Interaction
+
+When the user asks "why?" at any gate or internal step, the agent responds with a `status`
+interaction containing the curated rationale (Gate-Rationale-Registry) plus one line of
+fulfilled/protects context composed from existing state.
+
+- The response is deterministic, non-authorizing, and does not display approval controls.
+- It is a separate `status` interaction, never merged with the `gate_approval` sequence.
+- The `gate_approval` options remain exactly `approve | revise | decline | cancel`; no
+  "why" option is added.
+- The response never breaks `APPROVAL_SEQUENCE` or `validateApprovalOrientationSnapshot`.
+- Default output is unchanged when the user does not ask.
+- The fulfilled line is composed from the selected run's Approvals table and artefact
+  status; the protects-against line is composed from the gate's rationale and existing
+  `primary.actions` copy. The agent does not generate new prose.
+
 ### Human Decision Presentation Contract
 
 The primary user surface is a pure projection of the selected canonical run.

package/generated/plugins/agdf/skills/clean-implementation-review/SKILL.md

@@ -91,6 +91,11 @@ Use this compact structure:
 - `revise`: solution works but contains avoidable fallback, unclear ownership, or missing evidence.
 - `block`: solution creates a second SoT, a second owner, unbounded fallback, or masks unresolved product semantics.
 
+### Compact Chat Output
+
+At `pass`: one line — `Clean Review: pass — <one-line summary>`.
+At `revise`/`block`: show the specific fallback/workaround/parallel-structure risk with file references.
+
 ## Forbidden
 This skill must not:
 

package/generated/plugins/agdf/skills/code-review/SKILL.md

@@ -84,6 +84,11 @@ Use this compact structure:
 - `block`: a hard defect, security risk, data-integrity risk, or unresolved critical uncertainty remains.
 - `not_applicable`: no code changes were present for review.
 
+### Compact Chat Output
+
+At `pass`: one line — `Code Review: pass — <one-line summary>`.
+At `revise`/`block`: show blocking findings with file references. Full report remains in durable file or inline evidence as specified.
+
 ## Forbidden
 This skill must not:
 

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

@@ -69,7 +69,7 @@ For a ready `gate_approval`:
 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.
+10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution and can transport `exact_option_value` or `separate_label_and_value`; never invoke a `decorated_label_only` adapter. Otherwise request the same exact approval in concise text.
 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.
@@ -88,7 +88,7 @@ For the transition card, use the complete resolved locale pack. The initial Germ
 
 The primary option is derived exactly as `Approval: <GateName>` from the evaluated current gate; only explanatory copy and non-authoritative outcome labels are localized. Concrete localized copy belongs to the user-facing interaction layer or the approved delivery artefact, not to English runtime rules.
 
-Make exactly one native-attempt for the ready gate. If the host does not render,
+Make exactly one native-attempt for the eligible ready gate. If the host does not render,
 apply or safely return the native question on that attempt, switch immediately
 to the exact textual approval. Do not ask the user to request the buttons again
 and do not create a retry loop or simulated control.
@@ -102,7 +102,7 @@ only after fresh run/gate/artefact revalidation; never retry automatically.
 
 Surface behavior:
 
-- Codex: invoke the native short-question/request-user-input control on the first eligible attempt when callable, ask one gate question and omit auto-resolution; if it is not rendered or applied, use exact text immediately.
+- Codex: invoke the native short-question/request-user-input control only when preflight proves `exact_option_value` or `separate_label_and_value`, and omit auto-resolution. The canonical `decorated_label_only` capability must use exact text without invoking the adapter. `Approval: <GateName> (Recommended)` is never a valid option or approval.
 - Claude Code: invoke `AskUserQuestion` on the first eligible attempt only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if it is not rendered or applied, use exact text immediately. Claude permissions and `ExitPlanMode` remain separate.
 - OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
 - Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
@@ -125,6 +125,17 @@ After each accepted gate approval is persisted, emit exactly one narration line
 
 When rendering the compact human Run Status Card, collapse internal sub-states (`verified_change` sub-states, `context_graph_required_action`, `multi_scope_state`) to stable human labels. `escalated`, `open_gap` and `blocked` remain explicitly visible. The full machine/audit projection retains all raw values unchanged. See the Runtime Contract §Internal-State Collapse for the complete mapping table.
 
+### On-Demand "Why?" Response
+
+When the user asks "why?" or "Warum?" at any gate or internal step, respond with a `status` interaction (not `gate_approval`):
+
+1. Pull the curated rationale from `gateRationale()` in the resolved locale.
+2. Compose one fulfilled line from the selected run's Approvals table and artefact status.
+3. Compose one protects-against line from the gate's rationale and the existing `primary.actions` copy.
+4. Do not show approval controls. Do not advance any gate. Do not merge with the approval envelope.
+
+The response is deterministic: same gate, same question, same answer. The `gate_approval` options remain exactly `approve | revise | decline | cancel`; no "why" option is added. See the Runtime Contract §Gate-Rationale-Registry and §On-Demand "Why?" Interaction for the full contract.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
@@ -221,6 +232,7 @@ from the same snapshot and are shown exactly once.
 
 If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
 List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.
+See the Runtime Contract §Chat and Tool-Call Discipline for tool-call batching and skill output compaction rules.
 
 ## Forbidden
 This skill must not:

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

@@ -102,6 +102,12 @@ Use this shape:
 
 If Context Graph impact is relevant, include the fields from `../../meta/agdf-runtime-contract.md`.
 
+### Compact Chat Output
+
+At `pass`: one line — `QA: pass — <one-line summary>`. Reference the durable QA report
+path. Do not show the Quality Readiness projection or evidence inventory in chat.
+At `revise`/`block`: show the decisive dimension, reason and next action.
+
 ## Decision Guidance
 - `pass`: required TP tasks are done, evidence is strong, no blocking Brownfield or solution-integrity risk remains.
 - `revise`: implementation is plausible but missing evidence, partial tasks, UX gaps, or fixable integrity issues remain.

package/generated/plugins/agdf/skills/task-plan-review/SKILL.md

@@ -105,6 +105,11 @@ Evidence confidence:
 - `medium`
 - `low`
 
+### Compact Chat Output
+
+At `pass`: one line — `TP Review: pass — <X>/<total> tasks fully_done`.
+At `revise`/`block`: show incomplete tasks with missing evidence.
+
 ## Forbidden
 This skill must not:
 

package/lib/interaction-presentation.js

@@ -64,7 +64,7 @@ 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.startsWith("primary.narration.") || key === "primary.quality"
+        : key.includes("Description") || key.includes("fallbackReasons") || key.startsWith("primary.actions.") || key.startsWith("primary.afterApproval.") || key.startsWith("primary.narration.") || key.startsWith("gateRationale.") || key.startsWith("interaction.why.") || key === "primary.quality"
           ? budgets.description
           : budgets.label;
       if (Number.isInteger(budget) && value.length > budget) errors.push(`length_budget:${locale}:${key}`);
@@ -97,6 +97,10 @@ export function gateTitle(registry, requestedLocale, gate) {
   return localePack(registry, requestedLocale).gateTitles[gate] || String(gate || "");
 }
 
+export function gateRationale(registry, requestedLocale, gate) {
+  return localePack(registry, requestedLocale).gateRationale?.[gate] || String(gate || "");
+}
+
 function stripMarkdown(value) {
   return String(value ?? "")
     .replace(/^#+\s*/, "")

package/package.json

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