create-agdf 0.8.5 → 0.8.6

package/generated/plugins/agdf/skills/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/plugins/agdf/skills/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 `plugin/meta/agdf-interaction-locales.json`: exact complete pack, language subtag, then English fallback. German and English are initial packs, not a closed language list. Keep `Approval: <GateName>` exactly unchanged in every language, and do not mix presentation languages within one interaction. Labels and descriptions use the same resolved locale; host-owned UI chrome remains host-owned and may use a different language.
 
 For the transition card, use the complete resolved locale pack. The initial German pack includes `Bereit für deine Entscheidung`, `Jetzt freigeben` and `Danach`; the initial English pack includes `Ready for your decision`, `Approve now` and `Next`. Keep each card in one locale. Use a localized human-readable gate title rather than an internal status label, while leaving the exact gate identifier and approval value unchanged. Do not render a Markdown table, dashboard rows, raw control-state keys, diagnostic codes, evidence lists, a duplicated gate question or a false user gate in the approval-time card.
 
-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/plugins/agdf/skills/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/lib/control-state/run-state-parser.js

@@ -76,6 +76,24 @@ function rows(s) {
 function clean(v = "") {
   return v.replace(/^`|`$/g, "").trim();
 }
+export function parseArtefactPathCell(value = "") {
+  const raw = String(value).trim();
+  if (!raw) return { raw, path: "", format: "plain", reason: "empty" };
+  const ticks = [...raw].filter((character) => character === "`").length;
+  if (ticks === 0) return { raw, path: raw, format: "plain", reason: "none" };
+  if (ticks === 2 && raw.startsWith("`") && raw.endsWith("`")) {
+    const path = raw.slice(1, -1).trim();
+    if (path && !path.includes("`")) return { raw, path, format: "code_span", reason: "none" };
+  }
+  return {
+    raw,
+    path: "",
+    format: "invalid",
+    reason: ticks === 1 || raw.startsWith("`") !== raw.endsWith("`")
+      ? "unmatched_delimiter"
+      : "embedded_delimiter",
+  };
+}
 function meaningful(v = "") {
   return Boolean(v && !(v.startsWith("`") && v.includes("|")));
 }
@@ -96,7 +114,7 @@ function dataRows(c, h, header) {
 }
 export function parseControlState(
   content,
-  { userGates = [], internalSteps = [] } = {},
+  { userGates = [], internalSteps = [], closeoutArtefacts = [] } = {},
 ) {
   const approvals = new Map();
   for (const h of ["Approvals", "Gate Checklist"])
@@ -111,8 +129,17 @@ export function parseControlState(
     }
   const artefacts = new Map();
   for (const [t, p, s, n] of rows(section(content, "Artefacts"))) {
-    if (userGates.includes(t) || internalSteps.includes(t))
-      artefacts.set(t, { path: p ?? "", status: clean(s), notes: n ?? "" });
+    if (userGates.includes(t) || internalSteps.includes(t) || closeoutArtefacts.includes(t)) {
+      const parsedPath = parseArtefactPathCell(p ?? "");
+      artefacts.set(t, {
+        path: parsedPath.path,
+        status: clean(s),
+        notes: n ?? "",
+        raw_path: parsedPath.raw,
+        path_format: parsedPath.format,
+        path_reason: parsedPath.reason,
+      });
+    }
   }
   const mapRows = (h, header, fn) => dataRows(content, h, header).map(fn);
   const mode = section(content, "Mode/Slice Decision").trim()

package/lib/interaction-presentation.js

@@ -2,6 +2,7 @@ const REQUIRED_GATES = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 const ARTEFACT_ORDER = ["UR", "PRD", "SD", "TP"];
 const OUTCOMES = new Set(["approve", "revise", "decline", "cancel", "no_response", "timeout", "empty", "invalid", "stale"]);
 const ATTEMPT_OUTCOMES = new Set(["presented", "unavailable_before_invocation", "attempted_not_applied", "unsafe_to_wait"]);
+const APPROVAL_VALUE_TRANSPORTS = new Set(["exact_option_value", "separate_label_and_value", "decorated_label_only", "unknown"]);
 const APPROVAL_SEQUENCE = Object.freeze(["run_status_card", "gate_transition_card", "approval_interaction"]);
 const QUALITY_STATUS_RANK = { pass: 0, warn: 1, revise: 2, block: 3 };
 const QUALITY_DIMENSIONS = Object.freeze([
@@ -63,7 +64,7 @@ export function validateLocaleRegistry(registry) {
     for (const [key, value] of visibleStrings(pack)) {
       if (!value.trim()) errors.push(`empty_copy:${locale}:${key}`);
       const budget = key.startsWith("gateTitles.") ? budgets.title
-        : key.includes("Description") || key.includes("fallbackReasons") || key.startsWith("primary.actions.") || key.startsWith("primary.afterApproval.") || key === "primary.quality"
+        : key.includes("Description") || key.includes("fallbackReasons") || key.startsWith("primary.actions.") || key.startsWith("primary.afterApproval.") || key.startsWith("primary.narration.") || key === "primary.quality"
           ? budgets.description
           : budgets.label;
       if (Number.isInteger(budget) && value.length > budget) errors.push(`length_budget:${locale}:${key}`);
@@ -180,10 +181,31 @@ export function reconcileRunScope({ requestText = "", scopeKey = "", runs = [] }
   return Object.freeze({ outcome: matches[0].lifecycle === "active" ? "active_match" : "completed_match", matches, reason: "exact_match" });
 }
 
-export function executeNativeApprovalAttempt({ ready = false, orientationSnapshot, invokeNative, fallback } = {}) {
+export function evaluateNativeApprovalCapability({ staticCapability, runtimeCapability } = {}) {
+  const staticValue = staticCapability?.approvalValueTransport;
+  const runtimeValue = runtimeCapability?.approvalValueTransport;
+  if (runtimeCapability && staticCapability && (runtimeValue !== staticValue || runtimeCapability.waitSafety !== staticCapability.waitSafety)) {
+    return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unavailable_before_invocation", reason: "capability_conflict", evidence_source: "runtime" });
+  }
+  const capability = runtimeCapability ?? staticCapability;
+  const evidenceSource = runtimeCapability ? "runtime" : staticCapability ? "static" : "none";
+  if (!capability || !APPROVAL_VALUE_TRANSPORTS.has(capability.approvalValueTransport)) return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unavailable_before_invocation", reason: "capability_missing", evidence_source: evidenceSource });
+  if (capability.waitSafety === "unsafe") return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unsafe_to_wait", reason: "unsafe_wait", evidence_source: evidenceSource });
+  if (capability.waitSafety !== "deliberate_no_auto_resolution") return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unavailable_before_invocation", reason: "capability_missing", evidence_source: evidenceSource });
+  if (!new Set(["exact_option_value", "separate_label_and_value"]).has(capability.approvalValueTransport)) return Object.freeze({ eligible: false, native_attempt_required: false, preflight_outcome: "unavailable_before_invocation", reason: capability.approvalValueTransport === "decorated_label_only" ? "decorated_only" : "capability_missing", evidence_source: evidenceSource });
+  return Object.freeze({ eligible: true, native_attempt_required: true, preflight_outcome: "eligible_for_invocation", reason: capability.approvalValueTransport === "exact_option_value" ? "exact_transport" : "separate_value_transport", evidence_source: evidenceSource });
+}
+
+export function executeNativeApprovalAttempt({ ready = false, orientationSnapshot, capabilityPreflight, invokeNative, fallback } = {}) {
   if (!ready) return Object.freeze({ attempted: false, outcome: "unavailable_before_invocation", reason: "gate_not_ready", authorizes: false });
   const preflight = validateApprovalOrientationSnapshot(orientationSnapshot);
   if (!preflight.valid) return Object.freeze({ attempted: false, outcome: "unavailable_before_invocation", reason: "orientation_preflight_failed", authorizes: false });
+  if (!capabilityPreflight?.eligible) {
+    const outcome = capabilityPreflight?.preflight_outcome === "unsafe_to_wait" ? "unsafe_to_wait" : "unavailable_before_invocation";
+    const reason = capabilityPreflight?.reason || "capability_missing";
+    if (typeof fallback === "function") fallback({ outcome, reason });
+    return Object.freeze({ attempted: false, outcome, reason, authorizes: false });
+  }
   if (typeof invokeNative !== "function") return Object.freeze({ attempted: false, outcome: "unavailable_before_invocation", reason: "adapter_unavailable", authorizes: false });
   let adapterResult;
   try {
@@ -395,6 +417,66 @@ export function buildQualityReadiness({
   });
 }
 
+export function collapseInternalState(
+  { modeSliceDecision = "", verifiedChangeState = "", contextGraphRequiredAction = "", multiScopeState = "" } = {},
+  registry,
+  requestedLocale,
+) {
+  const pack = localePack(registry, requestedLocale);
+  const labels = pack.internalStateLabels || {};
+  const result = {};
+  if (modeSliceDecision === "verified_change") {
+    if (verifiedChangeState === "escalated") {
+      result.verified_change = labels.verifiedChangeEscalated || "Escalated to structured delivery";
+    } else if (["missing", "draft", "invalid", "eligible", "executed"].includes(verifiedChangeState)) {
+      result.verified_change = labels.verifiedChange || "Compact change under review";
+    }
+  }
+  if (contextGraphRequiredAction === "open_gap") {
+    result.context_graph = labels.contextGraphOpenGap || "Graph gap open";
+  } else if (["link", "update", "create", "resolve_drift"].includes(contextGraphRequiredAction)) {
+    result.context_graph = labels.contextGraphMaintained || "Project memory maintained";
+  }
+  if (multiScopeState === "blocked") {
+    result.multi_scope = labels.multiScopeBlocked || "Ambiguous scope, clarification needed";
+  }
+  return result;
+}
+
+export function buildBreadcrumb(breadcrumb, registry, requestedLocale) {
+  if (!Array.isArray(breadcrumb)) return "";
+  const pack = localePack(registry, requestedLocale);
+  const cardLabels = pack.statusCard || {};
+  const titles = pack.gateTitles || {};
+  const sep = cardLabels.breadcrumbSeparator || " \u00b7 ";
+  const symbols = {
+    fulfilled: cardLabels.breadcrumbFulfilled || "\u2713",
+    current: cardLabels.breadcrumbCurrent || "\u25cf",
+    open: cardLabels.breadcrumbOpen || "\u25cb",
+  };
+  return breadcrumb
+    .map((entry) => {
+      const title = titles[entry.gate] || entry.gate;
+      const symbol = symbols[entry.status] || symbols.open;
+      return `${title} ${symbol}`;
+    })
+    .join(sep);
+}
+
+export function buildTransitionNarration(gate, registry, requestedLocale) {
+  const pack = localePack(registry, requestedLocale);
+  const narration = pack.primary?.narration || {};
+  const gateTitles = pack.gateTitles || {};
+  const gateTitle = gateTitles[gate] || gate;
+  const gateConfig = narration.gates?.[gate] || {};
+  const agentNext = gateConfig.agentNext || "";
+  const userAction = gateConfig.userAction || narration.noAction || "no user action required now";
+  if (!agentNext) return "";
+  const gateSatisfiedTemplate = narration.gateSatisfied || "{gate} approved";
+  const gateSatisfied = gateSatisfiedTemplate.replace("{gate}", gateTitle);
+  return `${gateSatisfied} \u2192 ${agentNext} \u2192 ${userAction}`;
+}
+
 export const interactionPresentationConstants = Object.freeze({
   artefactOrder: Object.freeze([...ARTEFACT_ORDER]),
   outcomes: Object.freeze([...OUTCOMES]),

package/package.json

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