create-agdf 0.8.4 → 0.8.6

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

@@ -63,29 +63,30 @@ For a ready `gate_approval`:
 1. Resolve exactly one selected run and evaluate the current gate.
 2. Confirm the required durable artefact is present and ready before presenting a question.
 3. Build one immutable, non-authorizing presentation snapshot from the selected evaluated run and current revision identity.
-4. Compose one Approval Orientation Envelope as one immediately preceding assistant message containing two distinct blocks. Render the compact localized approval-time Run Status Card first. It contains exactly selected run, readiness status, current gate, missing exact approval, one next action and quality outlook; omit raw keys, machine statuses, evidence, diagnostics and allowed/forbidden inventories.
+4. Compose one Approval Orientation Envelope as one immediately preceding assistant message containing two distinct blocks. Render the compact localized approval-time Run Status Card first. Its first visible line is the localized action-oriented gate title as a level-two Markdown heading or equivalent accessible host heading; generic AGDF/card labels and raw gate IDs cannot be the primary heading. It contains exactly selected run, readiness status, current gate, missing exact approval, one next action and quality outlook; omit raw keys, machine statuses, evidence, diagnostics and allowed/forbidden inventories.
 5. In the same assistant message, render a separate localized Gate Transition Card second, immediately before any native question or exact-text fallback. It includes the deterministic human run title and `UR · PRD · SD · TP` links from the selected run. Never put either card only into the question, button description or hidden tool context. Do not invoke the native question tool until the complete two-card envelope is visible.
 6. Compose the transition card as one human-readable gate title with `run_id`, one ready-for-decision line, one short approval-effect block and one short next-transition block. It must answer only: where am I, what does this decision do, and what happens next. Run and gate identity may anchor both cards; do not duplicate status rows, action inventories or the native question.
 7. Distinguish internal process steps from user decisions in natural language. For example, after `Approval: TP`, say that pre-implementation Brownfield Analysis runs next and that no further user action is required now; do not expose `next_user_gate: none` or `user_action_required: no`, and do not ask for a second approval for Brownfield Analysis.
 8. Ask exactly one question that names the selected `run_id` and `current_gate`.
 9. Offer options in stable order: exact `Approval: <GateName>`, localized revise and localized decline. Add explicit cancel only where supported after decline; otherwise host dismissal maps to cancel. Never preselect, skip, auto-submit or reorder an option.
 10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution; otherwise request the same exact approval in concise text.
-11. Render both cards once in that single complete assistant message. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
+11. Render both cards once in that single complete assistant message. Never merge, reverse, omit or duplicate them; the action heading does not replace either card. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
 12. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
 13. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
 14. Persist accepted input only through the existing control-state workflow.
 
-The ready-gate projection must expose `native_attempt_required: true`. Treat this as a mandatory
-orchestration instruction: after rendering the two cards, invoke the configured native question
-adapter exactly once before using the exact-text fallback. A hook, permission result or session
-context message cannot replace that attempt or supply its answer. For every non-ready interaction,
-the signal is absent or false and no approval control may be shown.
+Before 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,18 @@ 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.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
@@ -125,7 +138,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,18 @@
         "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",
+        "PRD": "Approve product requirements",
+        "SD": "Approve solution design",
+        "TP": "Approve task and test plan",
+        "QA": "Approve quality decision",
+        "UAT": "Accept delivery result"
       },
       "interaction": {
         "ready": "Ready for your decision",
@@ -120,6 +143,18 @@
           "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" }
+          }
         }
       }
     },
@@ -143,7 +178,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",
@@ -178,7 +225,18 @@
         "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",
+        "PRD": "Produktanforderungen freigeben",
+        "SD": "Lösungsdesign freigeben",
+        "TP": "Umsetzungsplan freigeben",
+        "QA": "Qualitätsentscheidung freigeben",
+        "UAT": "Ergebnis abnehmen"
       },
       "interaction": {
         "ready": "Bereit für deine Entscheidung",
@@ -235,6 +293,18 @@
           "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" }
+          }
         }
       }
     }

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