create-agdf 0.8.5 → 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

@@ -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,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,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",
@@ -128,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" }
+          }
         }
       }
     },
@@ -151,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",
@@ -186,7 +225,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",
@@ -251,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

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

@@ -36,10 +36,12 @@ After `Approval: UR`, Brownfield Review may select `verified_change` only when a
 1. exactly one repository-relative canonical owner and bounded source/derived paths;
 2. no gate, permission, security, persistence, architecture, external API, CLI or release behavior impact;
 3. deterministic propagation when derived paths exist, plus at least one deterministic validation command;
-4. tracked and untracked worktree baseline paths captured before eligibility, with no candidate path already dirty; and
+4. a full baseline commit plus tracked and untracked worktree baseline paths captured before eligibility, with no candidate path already dirty; and
 5. an explicit `structured_slice` or `structured_delivery` escalation target.
 
-The record is the compact eligibility, execution and mini-closeout artefact. A missing, failed, unknown or ambiguous field/check must fail closed: mark the record `escalated` and continue at its declared structured target. Unrelated paths already dirty at baseline remain isolated; newly introduced unlisted paths invalidate the compact path. An executed record requires passing validation evidence and, where applicable, passing propagation evidence.
+The record is the compact Brownfield selection, eligibility, execution and mini-closeout artefact. The selected run may link the same normalized record path as Brownfield Review, Verified Change and OR only in `verified_change` mode and only with lifecycle-consistent role states; separate Brownfield and OR files remain supported. Permitted control paths derive only from recognized, explicitly linked artefacts beneath the selected run's own artefact directory.
+
+A missing, failed, unknown or ambiguous field/check must fail closed: mark the record `escalated` and continue at its declared structured target. Unrelated paths already dirty at baseline remain isolated; newly introduced unlisted paths invalidate the compact path. An executed record requires a machine-readable exact changed-path snapshot with passing scope status, passing validation evidence and, where applicable, passing propagation evidence. Active runs compare that snapshot with the current post-baseline worktree. Completed executed runs validate the persisted snapshot and record evidence without being retroactively invalidated by later unrelated live-worktree changes.
 
 ### Non-Normative Trivial Change Boundary
 
@@ -145,6 +147,65 @@ and `Allowed after approval` when a missing approval exists, `Next step` and
 `Quality outlook`. Keep mode, forbidden actions, evidence and next-skill detail
 in the surrounding control artefact when they are relevant.
 
+### Breadcrumb
+
+The compact human Run Status Card may include a single-line path-derived breadcrumb that
+shows the user's position in the delivery journey. It is derived from the Mode/Slice
+Decision and the Approvals table — not a fixed template.
+
+| Mode/Slice | Breadcrumb gates |
+|---|---|
+| structured_delivery / structured_slice | `UR · PRD · SD · TP · QA · UAT` |
+| verified_change | `UR · Verified Change · OR` |
+| quick_task | `UR · Quick Task` |
+| block | `UR · Block` |
+
+- `✓` fulfilled, `●` current, `○` open.
+- Non-applicable gates are absent (no `–` placeholders, no thinned standard template).
+- `verified_change` is one collapsed node, not a degraded standard route.
+- The breadcrumb is a derived, non-authorising projection. It does not add a new gate
+  model or override the Gate Transition Model.
+- The machine-readable `status_card` JSON may carry a derived `breadcrumb` array
+  `[{gate, status}]` for the presentation layer; this is additive and does not replace
+  any existing field.
+
+### Post-Acceptance Transition Narration
+
+After each accepted gate approval, the agent emits exactly one status line using the
+template:
+
+```text
+<what was satisfied> → <what the agent does next internally> → <user action: yes/no>
+```
+
+This narration is temporally and structurally separate from the Gate Transition Card:
+
+- The Gate Transition Card is **pre-approval** (in the orientation envelope); it is
+  subjunctive and contains the exact `Approval:` value.
+- The narration is **post-acceptance** (after the gate advanced); it is indicative and
+  does not contain the `Approval:` value.
+- Both never appear in the same assistant message.
+- The narration does not repeat the decision's effect (the card's job) and uses its own
+  template, not the card's three-question form.
+- For internal steps (Brownfield Review, Brownfield Analysis), the narration states what
+  the agent does next and that no user action is required, without exposing
+  `next_user_gate: none` or asking for a second approval.
+
+### Internal-State Collapse
+
+The derived-projection principle above applies explicitly to internal sub-states. The
+full Run Status Card (machine/audit projection) keeps all fields unchanged. Only the
+compact human card collapses internal sub-states to stable human labels:
+
+| Internal sub-state | Human label | Stays explicit |
+|---|---|---|
+| `verified_change`: missing/draft/invalid/eligible/executed | "Compact change under review" | `escalated` → "Escalated to structured delivery" |
+| `context_graph_required_action`: link/update/create/resolve_drift | "Project memory maintained" | `open_gap` → "Graph gap open" |
+| `multi_scope_state`: clear/ambiguous | (not shown) | `blocked` → "Ambiguous scope, clarification needed" |
+
+`open_gap` and `escalated` remain explicitly visible. The full machine projection retains
+all raw values unchanged.
+
 ## Quality Readiness Projection
 
 After CD+Tests, when any of the four review/QA artefacts exists, surfaces may show one compact
@@ -398,7 +459,7 @@ interaction_kind: clarification | tool_permission | gate_approval | blocked | st
 surface: codex | claude | opencode | fallback
 run_id: required for gate_approval
 current_gate: required for gate_approval
-native_attempt_required: true only for an eligible gate_approval before the first adapter attempt
+native_attempt_required: true only after ready-gate and adapter-capability preflight prove exact value transport and safe deliberate waiting
 prompt: required
 options: required for a structured question
 effects: required when the interaction can cause side effects
@@ -429,11 +490,13 @@ Before presenting `gate_approval`, the agent must:
 6. reject missing evidence, ambiguous or wrong run, wrong gate, stale state and any response that is no longer valid;
 7. persist an accepted approval only through the existing control-state workflow.
 
-For an eligible `gate_approval`, `native_attempt_required` is a mandatory orchestration signal. The
-agent must make exactly one configured native adapter attempt after the two orientation cards and
-before any exact-text fallback. Hooks may prepare context but must not answer, approve or replace
-the adapter attempt. The signal is absent or false for clarification, blocked, status-only,
-internal-step and non-ready interactions.
+For a ready `gate_approval`, interaction kind and native capability are separate. Evaluate callability,
+deliberate wait safety and canonical approval-value transport before invocation. `native_attempt_required`
+is true only when current evidence proves `exact_option_value` or `separate_label_and_value` transport
+with safe deliberate waiting. Decorated-only, missing, conflicting or unknown capability fails closed to
+`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.
 
 The first eligible native-attempt has a single bounded outcome: the declared
 host control is presented, or the agent immediately uses the exact-text