create-agdf 0.8.5 → 0.8.7

package/bin/create-agdf.js

@@ -63,6 +63,7 @@ const openCodeConfigFragmentPath = "opencode.agdf.json";
 const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 const durableGateArtefacts = new Set(["UR", "PRD", "SD", "TP", "QA"]);
 const internalStepArtefacts = new Set(["Brownfield Review", "Verified Change", "Brownfield Analysis", "CD+Tests", "TP Review", "Clean Implementation Review", "Clean Review", "CR", "Code Review"]);
+const closeoutArtefacts = new Set(["OR"]);
 const deliveryRelationships = [
   { from: "UR", relationship: "approved_by", to: "Approval: UR", requiredBy: "UR" },
   { from: "PRD", relationship: "derived_from", to: "UR", requiredBy: "PRD" },
@@ -1754,6 +1755,9 @@ function evaluateDoctor(targetDir, selection = {}) {
     for (const finding of analyzeDurableGateArtefactConsistency(runState)) {
       addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
     }
+    for (const finding of analyzeArtefactRoleConsistency(targetDir, runState)) {
+      addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
+    }
     for (const finding of analyzeDeliveryMap(runState).findings) {
       addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
     }
@@ -1828,6 +1832,14 @@ function gitPathList(targetDir, args) {
   }
 }
 
+function gitValue(targetDir, args) {
+  try {
+    return execFileSync("git", args, { cwd: targetDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
 function readVerifiedChangeRecord(targetDir, runState) {
   const artefact = runState.artefacts.get("Verified Change");
   if (!artefact?.path || isPlaceholderValue(artefact.path)) return { status: "missing", path: "", content: "" };
@@ -1870,9 +1882,14 @@ function evaluateVerifiedChange(targetDir, runState) {
   const validationCommands = extractField(record.content, "validation_commands");
   const baselineTracked = parseVerifiedChangePathList(extractField(record.content, "baseline_tracked_paths"));
   const baselineUntracked = parseVerifiedChangePathList(extractField(record.content, "baseline_untracked_paths"));
+  const baselineCommit = cleanStatusCell(extractField(record.content, "baseline_commit"));
+  const executionChangedPaths = parseVerifiedChangePathList(extractField(record.content, "execution_changed_paths"));
+  const executionScopeStatus = cleanStatusCell(extractField(record.content, "execution_scope_status"));
   const validationStatus = cleanStatusCell(extractField(record.content, "validation_status"));
   const propagationStatus = cleanStatusCell(extractField(record.content, "propagation_status"));
   const urArtefact = runState.artefacts.get("UR");
+  const lifecycle = extractField(runState.content, "lifecycle") || "active";
+  const runId = extractField(runState.content, "run_id") || "";
 
   if (!verifiedChangeStatuses.has(status)) add("AGDF_VERIFIED_CHANGE_STATUS_INVALID", "Verified Change record must use status draft, eligible, executed or escalated.", "Set a supported record status or escalate to the declared structured target.");
   if (!isSafeRepoRelativePath(relatedUr) || relatedUr !== urArtefact?.path) add("AGDF_VERIFIED_CHANGE_RELATED_UR_INVALID", "Verified Change record must link exactly to the selected run's repository-relative UR artefact.", "Set related_ur to the selected run's durable UR artefact path.");
@@ -1884,24 +1901,49 @@ function evaluateVerifiedChange(targetDir, runState) {
   if (!validationCommands || validationCommands === "none") add("AGDF_VERIFIED_CHANGE_VALIDATION_MISSING", "Verified Change requires at least one deterministic validation command.", "Record a deterministic acceptance or consistency check, or escalate.");
   if (derivedPaths.length > 0 && (!propagationCommand || propagationCommand === "none")) add("AGDF_VERIFIED_CHANGE_PROPAGATION_MISSING", "Derived paths require a deterministic propagation command.", "Record the propagation command or escalate.");
   if (!extractField(record.content, "baseline_tracked_paths") || !extractField(record.content, "baseline_untracked_paths")) add("AGDF_VERIFIED_CHANGE_BASELINE_MISSING", "Verified Change requires both tracked and untracked baseline path fields, using none when empty.", "Capture the worktree baseline before marking the record eligible.");
+  if (["eligible", "executed"].includes(status) && !/^[0-9a-f]{40,64}$/i.test(baselineCommit)) add("AGDF_VERIFIED_CHANGE_BASELINE_COMMIT_INVALID", "Eligible or executed Verified Change requires a full Git baseline_commit.", "Capture the current full Git commit id before eligibility or escalate.");
+
+  if (["eligible", "executed"].includes(status) && lifecycle !== "completed" && /^[0-9a-f]{40,64}$/i.test(baselineCommit)) {
+    const currentHead = gitValue(targetDir, ["rev-parse", "HEAD"]);
+    if (!currentHead) {
+      add("AGDF_VERIFIED_CHANGE_BASELINE_COMMIT_UNAVAILABLE", "Active Verified Change requires a readable current Git HEAD for baseline identity validation.", "Restore Git repository access or use the structured path.", "block");
+    } else if (baselineCommit !== currentHead) {
+      add("AGDF_VERIFIED_CHANGE_BASELINE_COMMIT_MISMATCH", "Active Verified Change baseline_commit does not match the current Git HEAD.", "Recapture the baseline before eligibility or escalate; do not reuse a stale or fabricated baseline identity.", "block");
+    }
+  }
 
   const allowedPaths = new Set([...sourcePaths, ...derivedPaths]);
   const baselinePaths = new Set([...baselineTracked, ...baselineUntracked]);
   const dirtyCandidate = [...allowedPaths].find((path) => baselinePaths.has(path));
   if (dirtyCandidate) add("AGDF_VERIFIED_CHANGE_BASELINE_CANDIDATE_DIRTY", `Declared candidate path is already dirty at baseline: ${dirtyCandidate}.`, "Escalate or start from a clean candidate path; do not adopt pre-existing edits.", "block");
 
-  const currentTracked = gitPathList(targetDir, ["diff", "HEAD", "--name-only"]);
-  const currentUntracked = gitPathList(targetDir, ["ls-files", "--others", "--exclude-standard"]);
-  if (currentTracked === null || currentUntracked === null) {
-    add("AGDF_VERIFIED_CHANGE_GIT_BASELINE_UNAVAILABLE", "Verified Change requires a readable Git worktree for scoped baseline validation.", "Use the structured path or restore Git worktree access.", "block");
+  const permittedControlPaths = new Set([record.path, runState.path, ".agdf/control/MASTER_BACKLOG.md"]);
+  const runArtefactPrefix = `.agdf/control/artefacts/${runId}/`;
+  for (const artefact of runState.artefacts.values()) {
+    if (artefact.path_format === "invalid") continue;
+    if (isSafeRepoRelativePath(artefact.path) && artefact.path.startsWith(runArtefactPrefix)) permittedControlPaths.add(artefact.path);
+  }
+
+  if (!(lifecycle === "completed" && status === "executed")) {
+    const currentTracked = gitPathList(targetDir, ["diff", "HEAD", "--name-only"]);
+    const currentUntracked = gitPathList(targetDir, ["ls-files", "--others", "--exclude-standard"]);
+    if (currentTracked === null || currentUntracked === null) {
+      add("AGDF_VERIFIED_CHANGE_GIT_BASELINE_UNAVAILABLE", "Verified Change requires a readable Git worktree for scoped baseline validation.", "Use the structured path or restore Git worktree access.", "block");
+    } else {
+      const introduced = [...new Set([...currentTracked, ...currentUntracked])].filter((path) => !baselinePaths.has(path)).sort();
+      const unexpected = introduced.filter((path) => !allowedPaths.has(path) && !permittedControlPaths.has(path));
+      if (unexpected.length > 0) add("AGDF_VERIFIED_CHANGE_SCOPE_ESCAPE", `Verified Change introduced unlisted path(s): ${unexpected.join(", ")}.`, "Mark the record escalated and continue at the declared structured target.", "block");
+      if (status === "executed" && JSON.stringify(introduced) !== JSON.stringify([...executionChangedPaths].sort())) {
+        add("AGDF_VERIFIED_CHANGE_EXECUTION_SCOPE_MISMATCH", "Executed Verified Change execution_changed_paths must equal the post-baseline changed-path set.", "Record the exact changed paths or escalate.", "block");
+      }
+    }
   } else {
-    const currentPaths = new Set([...currentTracked, ...currentUntracked]);
-    const permittedControlPaths = new Set([record.path, runState.path, ".agdf/control/MASTER_BACKLOG.md"]);
-    const unexpected = [...currentPaths].filter((path) => !baselinePaths.has(path) && !allowedPaths.has(path) && !permittedControlPaths.has(path));
-    if (unexpected.length > 0) add("AGDF_VERIFIED_CHANGE_SCOPE_ESCAPE", `Verified Change introduced unlisted path(s): ${unexpected.join(", ")}.`, "Mark the record escalated and continue at the declared structured target.", "block");
+    const unsafeExecutionPath = executionChangedPaths.find((path) => !isSafeRepoRelativePath(path) || (!allowedPaths.has(path) && !permittedControlPaths.has(path)));
+    if (unsafeExecutionPath) add("AGDF_VERIFIED_CHANGE_EXECUTION_SCOPE_INVALID", `Recorded execution path is outside the eligible scope: ${unsafeExecutionPath}.`, "Correct the historical execution snapshot or escalate.", "block");
   }
 
   if (status === "executed") {
+    if (executionChangedPaths.length === 0 || !executionChangedPaths.some((path) => allowedPaths.has(path)) || executionScopeStatus !== "pass") add("AGDF_VERIFIED_CHANGE_EXECUTION_EVIDENCE_MISSING", "Executed Verified Change requires a non-empty execution_changed_paths set containing a declared source/derived path and execution_scope_status: pass.", "Record complete execution-scope evidence or escalate.");
     if (validationStatus !== "pass") add("AGDF_VERIFIED_CHANGE_VALIDATION_EVIDENCE_MISSING", "Executed Verified Change requires validation_status: pass.", "Record passing deterministic validation evidence or escalate.");
     if (derivedPaths.length > 0 && propagationStatus !== "pass") add("AGDF_VERIFIED_CHANGE_PROPAGATION_EVIDENCE_MISSING", "Executed Verified Change with derived paths requires propagation_status: pass.", "Record successful propagation evidence or escalate.");
   }
@@ -1936,6 +1978,7 @@ function readRunState(targetDir, selection = {}) {
           const controlState = parseControlState(run.content, {
             userGates: userGateOrder,
             internalSteps: [...internalStepArtefacts],
+            closeoutArtefacts: [...closeoutArtefacts],
           });
           return {
             ...run,
@@ -1974,6 +2017,7 @@ function readRunState(targetDir, selection = {}) {
   const parsed = parseControlState(content, {
     userGates: userGateOrder,
     internalSteps: [...internalStepArtefacts],
+    closeoutArtefacts: [...closeoutArtefacts],
   });
 
   return {
@@ -2033,6 +2077,51 @@ function analyzeDurableGateArtefactConsistency(runState) {
   return findings;
 }
 
+function analyzeArtefactRoleConsistency(targetDir, runState) {
+  const findings = [];
+  for (const [type, artefact] of runState.artefacts) {
+    if (artefact.path_format === "invalid") {
+      findings.push({
+        severity: "block",
+        code: "AGDF_ARTEFACT_PATH_FORMAT_INVALID",
+        message: `${type} uses an invalid artefact path cell (${artefact.path_reason}).`,
+        path: runState.path,
+        next_step: "Use a plain repository-relative path or one complete Markdown code span.",
+      });
+    } else if (artefact.path && !isSafeRepoRelativePath(artefact.path)) {
+      findings.push({
+        severity: "block",
+        code: "AGDF_ARTEFACT_PATH_INVALID",
+        message: `${type} must use a normalized repository-relative artefact path.`,
+        path: runState.path,
+        next_step: "Remove absolute, traversal, unsupported-backslash or otherwise non-normalized path text.",
+      });
+    }
+  }
+  const rolesByPath = new Map();
+  for (const [type, artefact] of runState.artefacts) {
+    if (!artefact.path) continue;
+    rolesByPath.set(artefact.path, [...(rolesByPath.get(artefact.path) ?? []), type]);
+  }
+  for (const [path, roles] of rolesByPath) {
+    if (roles.length < 2) continue;
+    const allowedRoles = new Set(["Brownfield Review", "Verified Change", "OR"]);
+    if (modeSliceDecision(runState) !== "verified_change" || roles.some((role) => !allowedRoles.has(role))) {
+      findings.push({ severity: "block", code: "AGDF_ARTEFACT_ROLE_ALIAS_INVALID", message: `Artefact path is reused across incompatible roles: ${roles.join(", ")}.`, path, next_step: "Use distinct artefacts or a lifecycle-consistent Verified Change compact record." });
+      continue;
+    }
+    const record = readVerifiedChangeRecord(targetDir, runState);
+    if (record.status !== "present") continue;
+    const recordStatus = cleanStatusCell(extractField(record.content, "status"));
+    const brownfieldComplete = extractField(record.content, "decision") === "verified_change" && filled(extractField(record.content, "scope_reason")) && filled(extractField(record.content, "evidence"));
+    const miniCloseoutComplete = ["delivered", "intentionally_not_delivered", "residual_risk", "next_step"].every((field) => filled(extractField(record.content, field)));
+    if (roles.includes("Brownfield Review") && (runState.artefacts.get("Brownfield Review")?.status !== "done" || !brownfieldComplete)) findings.push({ severity: "block", code: "AGDF_VERIFIED_CHANGE_BROWNFIELD_ROLE_INVALID", message: "Consolidated Brownfield Review role is incomplete.", path, next_step: "Complete Brownfield Selection before eligibility." });
+    if (roles.includes("Verified Change") && runState.artefacts.get("Verified Change")?.status !== recordStatus) findings.push({ severity: "block", code: "AGDF_VERIFIED_CHANGE_ROLE_STATUS_MISMATCH", message: "Verified Change artefact row status does not match the compact record.", path, next_step: "Align the run-state row and record status." });
+    if (roles.includes("OR") && runState.artefacts.get("OR")?.status === "done" && (recordStatus !== "executed" || !miniCloseoutComplete)) findings.push({ severity: "block", code: "AGDF_VERIFIED_CHANGE_OR_ROLE_INVALID", message: "Consolidated OR is complete before execution and Mini-Closeout evidence are complete.", path, next_step: "Complete execution and Mini-Closeout evidence before marking OR done." });
+  }
+  return findings;
+}
+
 function isInternalStepSatisfied(runState, step) {
   const artefact = runState.artefacts.get(step);
   if (!artefact) return false;
@@ -2244,6 +2333,40 @@ function postApprovalTransition(missingApproval) {
   };
 }
 
+const BREADCRUMB_PATH_TEMPLATES = {
+  structured_delivery: ["UR", "PRD", "SD", "TP", "QA", "UAT"],
+  structured_slice: ["UR", "PRD", "SD", "TP", "QA", "UAT"],
+  verified_change: ["UR", "Verified Change", "OR"],
+  quick_task: ["UR", "Quick Task"],
+  block: ["UR", "Block"],
+  undecided: ["UR"],
+};
+
+const BREADCRUMB_STANDARD_GATES = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
+
+function buildBreadcrumbPath(modeSliceDecision, currentGate, runState) {
+  const gates = BREADCRUMB_PATH_TEMPLATES[modeSliceDecision] ?? ["UR"];
+  return gates.map((gate) => {
+    if (BREADCRUMB_STANDARD_GATES.includes(gate)) {
+      if (gateApprovalStatus(runState, gate) === "approved") return { gate, status: "fulfilled" };
+      if (gate === currentGate) return { gate, status: "current" };
+      return { gate, status: "open" };
+    }
+    if (gate === currentGate) return { gate, status: "current" };
+    if ((gate === "Verified Change" || gate === "Quick Task") && currentGate === "OR")
+      return { gate, status: "fulfilled" };
+    if (gate === "Verified Change" && modeSliceDecision === "verified_change")
+      return { gate, status: "current" };
+    if (gate === "Quick Task" && modeSliceDecision === "quick_task")
+      return { gate, status: "current" };
+    if (gate === "Block" && modeSliceDecision === "block")
+      return { gate, status: "current" };
+    if (gate === "OR" && currentGate === "OR")
+      return { gate, status: "current" };
+    return { gate, status: "open" };
+  });
+}
+
 function buildStatusCard({
   status,
   currentGate,
@@ -2260,7 +2383,8 @@ function buildStatusCard({
   const postApproval = postApprovalTransition(missingApproval);
   const isUserGateApproval = missingApproval !== "none";
   const lifecycle = extractField(runState.content ?? "", "lifecycle") || "unknown";
-  const nativeAttemptRequired = status === "open" && isUserGateApproval;
+  const nativeAttemptRequired = false;
+  const interactionKind = status === "open" && isUserGateApproval ? "gate_approval" : status === "blocked" ? "blocked" : "status";
   return {
     run_id: extractField(runState.content ?? "", "run_id") || "unknown",
     presentation_language: chatLanguage,
@@ -2270,6 +2394,11 @@ function buildStatusCard({
     status,
     current_gate: currentGate,
     mode_slice_decision: runState.mode_slice_decision?.decision || "undecided",
+    breadcrumb: buildBreadcrumbPath(
+      runState.mode_slice_decision?.decision || "undecided",
+      currentGate,
+      runState,
+    ),
     allowed_now: allowed,
     forbidden_now: forbidden,
     blocking_condition: blockingReason || "none",
@@ -2284,8 +2413,10 @@ function buildStatusCard({
     next_skill: nextSkillByGate[currentGate] ?? "gate-check",
     next_step: nextAllowedAction,
     quality_outlook: qualityOutlook,
-    interaction_kind: nativeAttemptRequired ? "gate_approval" : status === "blocked" ? "blocked" : "status",
+    interaction_kind: interactionKind,
     native_attempt_required: nativeAttemptRequired,
+    native_preflight_outcome: isUserGateApproval ? "unavailable_before_invocation" : "not_applicable",
+    native_preflight_reason: isUserGateApproval ? "capability_missing" : "none",
   };
 }
 

package/generated/.agdf/control/templates/artefacts/VERIFIED_CHANGE.md

@@ -13,11 +13,21 @@ Status: `draft | eligible | executed | escalated`
 - prohibited_impacts: none
 - propagation_command: none
 - validation_commands:
+- baseline_commit:
 - baseline_tracked_paths: none
 - baseline_untracked_paths: none
+- execution_changed_paths: none
+- execution_scope_status: pending
 - validation_status: pending
 - propagation_status: not_applicable
 
+## Brownfield Selection
+
+- mode: post_ur_review
+- decision: verified_change
+- scope_reason:
+- evidence:
+
 ## Eligibility Assertions
 
 | Condition | Evidence | Status |

package/generated/.github/skills/agdf-brownfield-analysis/SKILL.md

@@ -26,14 +26,14 @@ When `.agdf/control/` is present, persist or link `post_ur_review` output under
 
 ## Modes
 
-- `post_ur_review`: use after approved durable UR to size and route the work. Output must decide `quick_task`, `structured_slice`, `structured_delivery`, or `block` with scope reason and evidence.
+- `post_ur_review`: use after approved durable UR to size and route the work. Output must decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery`, or `block` with scope reason and evidence.
 - `pre_implementation_analysis`: use after approved durable TP to verify the implementation path before `CD+Tests`. Output must focus on reuse path, owners, regression risk, test impact and minimal clean implementation.
 
 Do not mix both modes silently. Name the active mode in the output.
 
 ## Rules
 1. Brownfield first: understand the existing codebase before PRD/SD decisions when existing-system impact is possible, and again before implementation.
-2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen.
+2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen.
 3. Reuse-before-create: prefer existing modules, services, components, tables, endpoints, tests, and configuration.
 4. Minimal clean slice: choose the smallest durable intervention, not merely the smallest technical diff.
 5. No silent parallel structures.
@@ -106,7 +106,7 @@ Use a concise structure:
 ## Brownfield Analysis
 - mode: post_ur_review | pre_implementation_analysis
 - decision: pass | revise | block | not_applicable
-- mode_slice_decision: quick_task | structured_slice | structured_delivery | block
+- mode_slice_decision: quick_task | verified_change | structured_slice | structured_delivery | block
 - required_next_gate: none | PRD | SD | TP | Brownfield Analysis
 - artefact: .agdf/control/artefacts/<key>/BROWNFIELD_REVIEW.md | none
 - scope:

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

@@ -75,17 +75,18 @@ For a ready `gate_approval`:
 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 projecting a ready gate, evaluate adapter callability, deliberate wait safety and canonical
+approval-value transport. Expose `native_attempt_required: true` only when that preflight proves
+`exact_option_value` or `separate_label_and_value` transport with safe deliberate waiting. Decorated-only,
+missing, conflicting or unknown capability exposes false and `unavailable_before_invocation`; unsafe
+waiting exposes false and `unsafe_to_wait`. In both cases use exact text without invoking the adapter.
+A hook, permission result or session context message cannot replace an eligible attempt or supply its answer.
 
 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.
 
-The primary option remains exactly `Approval: SD`; 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.
+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,
 apply or safely return the native question on that attempt, switch immediately
@@ -112,6 +113,29 @@ A free-form response must still exactly match the current gate's approval formul
 
 Every primary chat card shows the selected run's `UR`, `PRD`, `SD` and `TP` in that order. Render an existing canonical path as a readable link and a missing artefact as localized non-link text; never guess paths. Resolve the human run title from current artefact heading, approved UR heading, Objective, then normalized `run_id`. Status, blocked, clarification and internal-step interactions use the same locale and artefact projection but do not show approval buttons. Keep raw process keys and machine status values in JSON or audit detail.
 
+### Breadcrumb Rendering
+
+The compact human Run Status Card includes a single-line path-derived breadcrumb showing the user's position in the delivery journey. Derive it from the Mode/Slice Decision and the Approvals table — not a fixed template. Use `✓` for fulfilled, `●` for current, `○` for open, separated by ` · `. Non-applicable gates are absent. See the Runtime Contract §Breadcrumb for the path templates and the derived `breadcrumb` array.
+
+### Post-Acceptance Transition Narration
+
+After each accepted gate approval is persisted, emit exactly one narration line using the template `<what was satisfied> → <what the agent does next internally> → <user action: yes/no>`. This generalizes the existing TP pattern (step 7 above) to every gate advancement. The narration is post-acceptance only: it never appears in the same message as the Gate Transition Card, never contains the `Approval:` value, and never repeats the decision's effect. For internal steps (Brownfield Review, Brownfield Analysis), state what the agent does next and that no user action is required, without exposing `next_user_gate: none` or asking for a second approval. See the Runtime Contract §Post-Acceptance Transition Narration for the full contract.
+
+### Internal-State Collapse in the Human Card
+
+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.
@@ -125,7 +149,7 @@ Every primary chat card shows the selected run's `UR`, `PRD`, `SD` and `TP` in t
 10. Approval of one user gate permits work on the next allowed gate artefact or required internal step only; it never skips directly to implementation.
 11. New product semantics, functional change or user-visible behaviour change requires a durable UR in `.agdf/control/` or a linked authoritative repository SoT before Brownfield Review, PRD, SD, TP, Brownfield Analysis or implementation.
 12. Approval text and durable artefact presence are separate requirements for UR, PRD, SD, TP and QA report decisions. Approval text without the corresponding persisted or linked artefact keeps the current gate at that gate.
-13. After Brownfield Review, decide the process size before drafting PRD or implementing: `quick_task | structured_slice | structured_delivery | block`.
+13. After Brownfield Review, decide the process size before drafting PRD or implementing: `quick_task | verified_change | structured_slice | structured_delivery | block`.
 14. The Mode/Slice Decision must be visible and evidenced before any Quick Task execution, PRD shortcut or implementation. A decision value without scope reason and evidence is still missing.
 15. Missing or incomplete control state must not push setup work back to the user. For a fresh request, draft the current minimal artefact in the response and request the exact approval. Initialize or write `.agdf/control/` only when durable control state is explicitly requested, already live for the repository, or required for a deterministic CLI/CI setup path. Implementation remains forbidden.
 16. Branch names, uncommitted diffs, generated summaries and chat history are not sufficient scope proof when durable artefacts or approvals are missing or conflicting.

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

@@ -28,7 +28,19 @@
         "lifecycle": "Delivery status",
         "allowed": "Allowed now",
         "forbidden": "Forbidden now",
-        "artefacts": "Artefacts"
+        "artefacts": "Artefacts",
+        "breadcrumb": "Path",
+        "breadcrumbFulfilled": "\u2713",
+        "breadcrumbCurrent": "\u25cf",
+        "breadcrumbOpen": "\u25cb",
+        "breadcrumbSeparator": " \u00b7 "
+      },
+      "internalStateLabels": {
+        "verifiedChange": "Compact change under review",
+        "verifiedChangeEscalated": "Escalated to structured delivery",
+        "contextGraphMaintained": "Project memory maintained",
+        "contextGraphOpenGap": "Graph gap open",
+        "multiScopeBlocked": "Ambiguous scope, clarification needed"
       },
       "qualityReadiness": {
         "title": "Quality Readiness",
@@ -63,7 +75,10 @@
         "Brownfield Analysis": "Implementation preparation",
         "CD+Tests": "Implementation and tests",
         "CR": "Code review",
-        "OR": "Delivery report"
+        "OR": "Delivery report",
+        "Verified Change": "Verified change",
+        "Quick Task": "Quick task",
+        "Block": "Block"
       },
       "gateActionTitles": {
         "UR": "Approve user requirements",
@@ -83,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"
@@ -128,7 +148,33 @@
           "TP": "Run pre-implementation Brownfield Analysis; implementation starts only if it passes.",
           "QA": "Prepare the user-acceptance decision; release remains blocked.",
           "UAT": "Prepare the delivery report; version-control and release actions still require explicit instruction."
+        },
+        "narration": {
+          "gateSatisfied": "{gate} approved",
+          "noAction": "no user action required now",
+          "gates": {
+            "UR": { "agentNext": "Agent runs Brownfield Review next" },
+            "PRD": { "agentNext": "Agent drafts the Solution Design next" },
+            "SD": { "agentNext": "Agent drafts the Task and Test Plan next" },
+            "TP": { "agentNext": "Agent runs pre-implementation Brownfield Analysis next" },
+            "QA": { "agentNext": "Agent prepares the user-acceptance decision", "userAction": "user acceptance decision next" },
+            "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": {
@@ -151,7 +197,19 @@
         "lifecycle": "Lieferstatus",
         "allowed": "Jetzt erlaubt",
         "forbidden": "Aktuell verboten",
-        "artefacts": "Artefakte"
+        "artefacts": "Artefakte",
+        "breadcrumb": "Pfad",
+        "breadcrumbFulfilled": "\u2713",
+        "breadcrumbCurrent": "\u25cf",
+        "breadcrumbOpen": "\u25cb",
+        "breadcrumbSeparator": " \u00b7 "
+      },
+      "internalStateLabels": {
+        "verifiedChange": "Kompakte Änderung wird geprüft",
+        "verifiedChangeEscalated": "Eskaliert zu structured delivery",
+        "contextGraphMaintained": "Projektgedächtnis wird gepflegt",
+        "contextGraphOpenGap": "Graph-Lücke offen",
+        "multiScopeBlocked": "Mehrdeutiger Scope, Klärung nötig"
       },
       "qualityReadiness": {
         "title": "Quality Readiness",
@@ -186,7 +244,10 @@
         "Brownfield Analysis": "Implementierungsvorbereitung",
         "CD+Tests": "Implementierung und Tests",
         "CR": "Code-Review",
-        "OR": "Lieferbericht"
+        "OR": "Lieferbericht",
+        "Verified Change": "Verified Change",
+        "Quick Task": "Quick Task",
+        "Block": "Block"
       },
       "gateActionTitles": {
         "UR": "Nutzeranforderung freigeben",
@@ -206,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"
@@ -251,7 +317,33 @@
           "TP": "Die Brownfield-Analyse vor der Implementierung durchführen; die Implementierung startet nur nach bestandenem Ergebnis.",
           "QA": "Die Nutzerabnahme vorbereiten; die Veröffentlichung bleibt gesperrt.",
           "UAT": "Den Lieferbericht vorbereiten; Versionskontroll- und Veröffentlichungsaktionen benötigen weiterhin eine ausdrückliche Anweisung."
+        },
+        "narration": {
+          "gateSatisfied": "{gate} genehmigt",
+          "noAction": "keine Nutzeraktion erforderlich",
+          "gates": {
+            "UR": { "agentNext": "Agent führt Brownfield Review als Nächstes durch" },
+            "PRD": { "agentNext": "Agent entwirft als Nächstes das Lösungsdesign" },
+            "SD": { "agentNext": "Agent entwirft als Nächstes den Aufgaben- und Testplan" },
+            "TP": { "agentNext": "Agent führt Brownfield-Analyse vor Implementierung durch" },
+            "QA": { "agentNext": "Agent bereitet die Nutzerabnahme vor", "userAction": "Nutzerabnahme als Nächstes" },
+            "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-release-or/SKILL.md

@@ -43,9 +43,10 @@ Use the Runtime Contract definition of `Relevant Run` to decide whether OR is ma
 9. End with the immediately permissible next step.
 10. `CD+Tests` is not completion.
 11. When moving a backlog item to Completed or Superseded, use the canonical human-readable table and link the final OR with a document-relative Markdown link.
-12. Keep machine status normalization in the CLI; do not write internal snake_case status values into the human-facing backlog.
-13. Reconcile Context Graph impact before clean closeout: report `context_graph_reconciliation: resolved | not_applicable | open_gap`.
-14. If Context Graph work remains unresolved, report it as an explicit open gap and do not describe the run as cleanly handoff-ready.
+12. For an executed `verified_change`, a lifecycle-consistent complete Mini-Closeout in the linked `VERIFIED_CHANGE.md` is the compact OR target; do not require a separate `OR.md` by ritual.
+13. Keep machine status normalization in the CLI; do not write internal snake_case status values into the human-facing backlog.
+14. Reconcile Context Graph impact before clean closeout: report `context_graph_reconciliation: resolved | not_applicable | open_gap`.
+15. If Context Graph work remains unresolved, report it as an explicit open gap and do not describe the run as cleanly handoff-ready.
 15. After writing or updating `MASTER_BACKLOG.md`, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before closeout. See the AGDF control scaffold's `MASTER_BACKLOG.md` template Rules section for the canonical status/artefact label vocabulary.
 
 ## When To Use