create-agdf 0.8.2 → 0.8.4

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

@@ -62,16 +62,24 @@ 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.
+
+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 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.
 
@@ -191,10 +199,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

@@ -2,6 +2,14 @@ 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);
@@ -55,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}`);
@@ -139,6 +147,57 @@ export function buildRunCandidates(runs) {
     .sort((left, right) => left.display_title.localeCompare(right.display_title) || left.run_id.localeCompare(right.run_id));
 }
 
+export function normalizeReconciliationText(value) {
+  return String(value ?? "")
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[._:/\\-]+/g, " ")
+    .replace(/[^\p{L}\p{N}\s]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function reconcileRunScope({ requestText = "", scopeKey = "", runs = [] } = {}) {
+  const requested = normalizeReconciliationText(scopeKey || requestText);
+  if (!requested) return Object.freeze({ outcome: "match_uncertain", matches: [], reason: "scope_input_missing" });
+  const matches = [...(runs ?? [])]
+    .filter((run) => run?.valid && ["active", "completed"].includes(run?.meta?.lifecycle) && typeof run.run_id === "string")
+    .filter((run) => {
+      const keys = [run.scope_key, run.display_title, run.current_artefact_heading, run.ur_heading]
+        .map(normalizeReconciliationText)
+        .filter(Boolean);
+      return keys.includes(requested);
+    })
+    .map((run) => Object.freeze({
+      run_id: run.run_id,
+      lifecycle: run.meta.lifecycle,
+      display_title: displaySafeTitle(run.display_title || run.ur_heading || run.run_id, normalizedRunTitle(run.run_id)),
+      current_gate: run.control_state?.current_gate || run.meta?.current_gate || "unknown",
+    }))
+    .sort((left, right) => left.run_id.localeCompare(right.run_id));
+  if (matches.length !== 1) return Object.freeze({ outcome: matches.length ? "match_uncertain" : "no_match", matches, reason: matches.length > 1 ? "multiple_exact_matches" : "no_exact_match" });
+  return Object.freeze({ outcome: matches[0].lifecycle === "active" ? "active_match" : "completed_match", matches, reason: "exact_match" });
+}
+
+export function executeNativeApprovalAttempt({ ready = false, invokeNative, fallback } = {}) {
+  if (!ready) return Object.freeze({ attempted: false, outcome: "unavailable_before_invocation", reason: "gate_not_ready", authorizes: false });
+  if (typeof invokeNative !== "function") return Object.freeze({ attempted: false, outcome: "unavailable_before_invocation", reason: "adapter_unavailable", authorizes: false });
+  let adapterResult;
+  try {
+    adapterResult = invokeNative();
+  } catch (error) {
+    adapterResult = { outcome: "attempted_not_applied", reason: String(error?.message || "adapter_error") };
+  }
+  const outcome = ATTEMPT_OUTCOMES.has(adapterResult?.outcome)
+    ? adapterResult.outcome
+    : adapterResult?.presented === true || adapterResult?.applied === true
+      ? "presented"
+      : "attempted_not_applied";
+  const reason = String(adapterResult?.reason || "").trim();
+  if (outcome !== "presented" && typeof fallback === "function") fallback({ outcome, reason });
+  return Object.freeze({ attempted: true, outcome, reason, authorizes: false });
+}
+
 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())
@@ -203,8 +262,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.2",
+  "version": "0.8.4",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [