create-agdf 0.8.1 → 0.8.3

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

@@ -62,16 +62,18 @@ 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. Render a separate localized Gate Transition Card 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 the card only into the question, button description or hidden tool context.
-4. Treat the operational Run Status Card as evaluation and audit input, not as the approval-time product surface. Do not paste its table, raw keys, machine statuses, evidence or diagnostic detail into the transition card.
-5. 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.
-6. 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.
-7. Ask exactly one question that names the selected `run_id` and `current_gate`.
-8. 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.
-9. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution; otherwise request the same exact approval in concise text.
-10. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
-11. 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.
-12. Persist accepted input only through the existing control-state workflow.
+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.
+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.
+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.
 
 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.
 
@@ -84,6 +86,13 @@ apply or safely return the native question on that attempt, switch immediately
 to the exact textual approval. Do not ask the user to request the buttons again
 and do not create a retry loop or simulated control.
 
+State the outcome visibly: `presented`, `unavailable_before_invocation`,
+`attempted_not_applied` or `unsafe_to_wait`. For every fallback, say in the
+configured locale why a native control was not usable, show the exact approval
+value and confirm that authority is unchanged. This transient outcome is not
+approval evidence. A new explicit user request may reopen the unchanged decision
+only after fresh run/gate/artefact revalidation; never retry automatically.
+
 Surface behavior:
 
 - Codex: invoke the native short-question/request-user-input control on the first eligible attempt when callable, ask one gate question and omit auto-resolution; if it is not rendered or applied, use exact text immediately.
@@ -184,10 +193,12 @@ Keep the result short and operational. Render the Runtime Contract's compact hum
 
 When an approval is missing, also include `Next gate after approval` and `Allowed after approval` exactly as constrained by the Runtime Contract. Keep forbidden outputs, evidence and next-skill detail in the concise surrounding text when relevant; they are not extra status-card rows.
 
-This operational status table is for status reporting. When the same response
-immediately requests a ready gate approval, replace the table in the visible
-approval experience with the Gate Transition Card defined above, then invoke
-the native question or exact-text fallback. Do not show both cards.
+This complete operational status table remains the status-reporting and detail
+surface. When the same response immediately requests a ready gate approval,
+render its six-field compact approval-time projection first, then the Gate
+Transition Card in the same immediately preceding assistant message, then
+invoke exactly one native question or exact-text fallback. Both cards derive
+from the same snapshot and are shown exactly once.
 
 If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
 List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.

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

@@ -28,6 +28,13 @@ QA-specific `decision` is exactly `pass | revise | block`.
 `pass` is allowed only when TP coverage, Brownfield fit, solution integrity, and relevant documentation/Context Graph impact are sufficiently evidenced.
 `sot_drift` must not pass silently as a warning.
 
+When post-CD+Tests review evidence exists, present the Runtime Contract's derived Quality
+Readiness projection before the detailed QA report: Plan coverage, Solution integrity, Code
+quality and QA decision in that order. Name `qa-gate` as the sole decision owner, show one
+decisive reason and one permissible next action, and keep detailed reports as evidence links or
+on-demand detail. The projection is non-authorizing and must not replace the Run Status Card,
+Gate Transition Card or the durable QA report.
+
 ## Rules
 1. No QA pass without strong evidence.
 2. TP is the reference, not merely working code.

package/lib/interaction-presentation.js

@@ -1,6 +1,15 @@
 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_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([
+  Object.freeze({ id: "plan_coverage", owner: "task-plan-review" }),
+  Object.freeze({ id: "solution_integrity", owner: "clean-implementation-review" }),
+  Object.freeze({ id: "code_quality", owner: "code-review" }),
+  Object.freeze({ id: "qa_decision", owner: "qa-gate" }),
+]);
 
 function plainObject(value) {
   return value && typeof value === "object" && !Array.isArray(value);
@@ -54,7 +63,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.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 === "primary.quality"
           ? budgets.description
           : budgets.label;
       if (Number.isInteger(budget) && value.length > budget) errors.push(`length_budget:${locale}:${key}`);
@@ -111,6 +120,45 @@ export function resolveHumanRunTitle({ currentArtefactHeading, urHeading, runCon
   return [currentArtefactHeading, urHeading, objective].map(stripMarkdown).find(Boolean) || normalizedRunTitle(runId);
 }
 
+function displaySafeTitle(value, fallback) {
+  const title = stripMarkdown(value).replace(/[\r\n]+/g, " ").replace(/\s+/g, " ").trim();
+  return (title || fallback).slice(0, 100);
+}
+
+export function buildRunCandidates(runs) {
+  return [...(runs ?? [])]
+    .filter((run) => run?.valid && run?.meta?.lifecycle === "active" && typeof run.run_id === "string")
+    .map((run) => {
+      const currentGate = run.control_state?.current_gate || run.meta?.current_gate || "unknown";
+      const title = resolveHumanRunTitle({
+        currentArtefactHeading: run.current_artefact_heading,
+        urHeading: run.ur_heading,
+        runContent: "",
+        runId: run.run_id,
+      });
+      return {
+        run_id: run.run_id,
+        display_title: displaySafeTitle(title, normalizedRunTitle(run.run_id)),
+        current_gate: currentGate,
+        next_allowed_action: String(run.control_state?.next_allowed_action ?? "").trim(),
+        revision_id: String(run.meta?.revision_id ?? "").trim(),
+      };
+    })
+    .sort((left, right) => left.display_title.localeCompare(right.display_title) || left.run_id.localeCompare(right.run_id));
+}
+
+export function buildInteractionAttempt({ interactionId, runId, currentGate, surface, attemptOutcome, expectedApproval, fallbackReason = "" }) {
+  if (!ATTEMPT_OUTCOMES.has(attemptOutcome)) throw new Error("invalid interaction attempt outcome");
+  if (!String(interactionId ?? "").trim() || !String(runId ?? "").trim() || !String(currentGate ?? "").trim())
+    throw new Error("interaction attempt identity missing");
+  return Object.freeze({
+    interaction_id: String(interactionId), run_id: String(runId), current_gate: String(currentGate),
+    surface: String(surface ?? "fallback"), attempt_outcome: attemptOutcome,
+    expected_approval: String(expectedApproval ?? ""), fallback_reason: String(fallbackReason ?? ""),
+    authorizes: false,
+  });
+}
+
 function safeArtefactPath(value) {
   const path = String(value ?? "").replace(/^`|`$/g, "").trim();
   if (!path || !/^[A-Za-z0-9._/-]+$/.test(path) || /^([a-z]+:|\/)/i.test(path)) return "";
@@ -163,7 +211,111 @@ export function normalizeInteractionOutcome(value, { expectedApproval, stale = f
   return "invalid";
 }
 
+export function buildApprovalOrientationSnapshot({
+  ready = false,
+  statusCard,
+  humanPresentation,
+  revisionId = "",
+  registry,
+  requestedLocale,
+} = {}) {
+  if (!ready || !plainObject(statusCard) || !plainObject(humanPresentation)) return null;
+  const gate = String(statusCard.current_gate ?? "").trim();
+  const runId = String(statusCard.run_id ?? "").trim();
+  const expectedApproval = `Approval: ${gate}`;
+  if (!REQUIRED_GATES.includes(gate) || !runId || statusCard.status !== "open" || statusCard.missing_approval !== expectedApproval) return null;
+
+  const locale = resolvePresentationLocale(registry, requestedLocale);
+  const pack = localePack(registry, locale);
+  const runTitle = String(humanPresentation.runTitle ?? "").trim() || normalizedRunTitle(runId);
+  const currentGateTitle = String(humanPresentation.gateTitle ?? "").trim() || gateTitle(registry, locale, gate);
+  const artefactRefs = Object.freeze([...(humanPresentation.artefactRefs ?? [])].map((ref) => Object.freeze({ ...ref })));
+  const statusFields = Object.freeze([
+    Object.freeze({ id: "selected_run", label: pack.statusCard.run, value: `${runTitle} · ${runId}` }),
+    Object.freeze({ id: "readiness_status", label: pack.statusCard.title, value: pack.interaction.ready }),
+    Object.freeze({ id: "current_gate", label: pack.statusCard.gate, value: `${gate} — ${currentGateTitle}` }),
+    Object.freeze({ id: "missing_approval", label: pack.statusCard.missing, value: expectedApproval }),
+    Object.freeze({ id: "next_action", label: pack.statusCard.step, value: pack.primary.actions[gate] ?? String(statusCard.next_step ?? "") }),
+    Object.freeze({ id: "quality_outlook", label: pack.statusCard.quality, value: pack.primary.quality }),
+  ]);
+  const options = Object.freeze(gateOptions(registry, locale, gate).map((option) => Object.freeze({ ...option })));
+
+  return Object.freeze({
+    schema_version: "1",
+    run_id: runId,
+    revision_id: String(revisionId ?? "").trim(),
+    current_gate: gate,
+    presentation_language: locale,
+    sequence: APPROVAL_SEQUENCE,
+    compact_status_card: Object.freeze({ title: pack.statusCard.title, fields: statusFields }),
+    gate_transition_card: Object.freeze({
+      title: `${currentGateTitle} · ${runTitle} · ${runId}`,
+      artefact_refs: artefactRefs,
+      ready: pack.interaction.ready,
+      approve_heading: pack.interaction.approveHeading,
+      exact_approval: expectedApproval,
+      approval_effect: pack.primary.afterApproval[gate] ?? pack.primary.actions[gate] ?? "",
+      next_heading: pack.interaction.nextHeading,
+      next_gate: String(statusCard.next_gate_after_approval ?? "none"),
+    }),
+    approval_interaction: Object.freeze({ expected_approval: expectedApproval, options, authorizes: false }),
+    authorizes: false,
+  });
+}
+
+export function attachApprovalOrientationSnapshot(statusCard, options = {}) {
+  if (!plainObject(statusCard)) throw new Error("approval orientation status card missing");
+  const snapshot = buildApprovalOrientationSnapshot({ ...options, statusCard });
+  Object.defineProperty(statusCard, "approvalOrientation", {
+    value: snapshot,
+    enumerable: false,
+  });
+  return snapshot;
+}
+
+function qualityStatus(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  return Object.hasOwn(QUALITY_STATUS_RANK, normalized) ? normalized : "unknown";
+}
+
+export function buildQualityReadiness({
+  planCoverage,
+  solutionIntegrity,
+  codeQuality,
+  qaDecision,
+  decisiveReason = "",
+  nextAction = "",
+} = {}) {
+  const values = [planCoverage, solutionIntegrity, codeQuality, qaDecision];
+  const rows = QUALITY_DIMENSIONS.map((dimension, index) => Object.freeze({
+    ...dimension,
+    status: qualityStatus(values[index]),
+  }));
+  const known = rows.filter((row) => row.status !== "unknown");
+  if (known.length === 0) return null;
+  const status = rows.some((row) => row.status === "unknown")
+    ? "revise"
+    : known.reduce((current, row) =>
+      QUALITY_STATUS_RANK[row.status] > QUALITY_STATUS_RANK[current] ? row.status : current,
+    "pass");
+  const decisiveRow = rows.find((row) => row.status === status && status !== "pass")
+    ?? rows.find((row) => row.id === "qa_decision")
+    ?? rows[0];
+  return Object.freeze({
+    status,
+    rows: Object.freeze(rows),
+    decisive_reason: String(decisiveReason ?? "").trim(),
+    decisive_dimension: decisiveRow.id,
+    next_action: String(nextAction ?? "").trim(),
+    decision_owner: "qa-gate",
+    authorizes: false,
+  });
+}
+
 export const interactionPresentationConstants = Object.freeze({
   artefactOrder: Object.freeze([...ARTEFACT_ORDER]),
   outcomes: Object.freeze([...OUTCOMES]),
+  attemptOutcomes: Object.freeze([...ATTEMPT_OUTCOMES]),
+  approvalSequence: APPROVAL_SEQUENCE,
+  qualityDimensions: QUALITY_DIMENSIONS,
 });

package/package.json

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