create-agdf 0.8.1 → 0.8.2

package/bin/create-agdf.js

@@ -27,6 +27,7 @@ import {
 } from "../lib/control-state/index.js";
 import {
   buildArtefactRefs,
+  buildRunCandidates,
   canonicalizeLanguageTag,
   formatArtefactRefs,
   gateTitle,
@@ -1916,6 +1917,7 @@ function readRunState(targetDir, selection = {}) {
   let runPath = join(".agdf", "control", "AGDF_RUN.md");
   const canonicalRoot = join(targetDir, ".agdf", "control", "runs");
   let resolutionError;
+  let candidateRuns = [];
   if (existsSync(canonicalRoot)) {
     try {
       const selected = resolveRuns(targetDir, {
@@ -1927,6 +1929,21 @@ function readRunState(targetDir, selection = {}) {
         : selected.run.path;
     } catch (error) {
       resolutionError = error.message;
+      if (resolutionError.startsWith("AGDF_ACTIVE_RUN_AMBIGUOUS")) {
+        const active = resolveRuns(targetDir, { allActive: true }).runs.map((run) => {
+          const controlState = parseControlState(run.content, {
+            userGates: userGateOrder,
+            internalSteps: [...internalStepArtefacts],
+          });
+          return {
+            ...run,
+            control_state: controlState,
+            current_artefact_heading: readArtefactHeading(targetDir, controlState.artefacts.get(controlState.current_gate)),
+            ur_heading: readArtefactHeading(targetDir, controlState.artefacts.get("UR")),
+          };
+        });
+        candidateRuns = buildRunCandidates(active);
+      }
     }
   }
   if (resolutionError || !existsSync(join(targetDir, runPath))) {
@@ -1946,6 +1963,7 @@ function readRunState(targetDir, selection = {}) {
       quality_outlook: "",
       source_scope: {},
       memory: {},
+      candidate_runs: candidateRuns,
       resolution_error: resolutionError,
     };
   }
@@ -2333,6 +2351,10 @@ function isGateSatisfied(runState, gate) {
   return isDurableGateArtefactSatisfied(runState, gate);
 }
 
+function qaRevisionRequired(runState) {
+  return gateArtefactStatus(runState, "QA").status === "revise";
+}
+
 function transitionDecisionForRunState(runState, verifiedChange = null) {
   if (gateApprovalStatus(runState, "UR") === "approved" && !isGateSatisfied(runState, "UR")) return durableArtefactBlock("UR", "PRD");
 
@@ -2533,6 +2555,18 @@ function transitionDecisionForRunState(runState, verifiedChange = null) {
     };
   }
 
+  if (qaRevisionRequired(runState)) {
+    return {
+      status: "open",
+      current_gate: "QA",
+      blocking_reason: "qa_revise_required",
+      missing_approval: "none",
+      allowed: ["revise the implementation against the QA findings", "refresh CD+Tests and mandatory reviews", "rerun QA with refreshed evidence"],
+      forbidden: ["request QA approval", "request UAT approval", "release", "claim delivery readiness"],
+      next_allowed_action: "Resolve the QA revise findings, refresh CD+Tests and reviews, then rerun QA. Do not request Approval: QA from a revise report.",
+    };
+  }
+
   if (gateApprovalStatus(runState, "QA") === "approved" && !isGateSatisfied(runState, "QA")) return durableArtefactBlock("QA", "UAT");
 
   if (isGateSatisfied(runState, "QA") && !isGateSatisfied(runState, "UAT")) {
@@ -2658,6 +2692,7 @@ function evaluateGateCheck(targetDir, selection = {}) {
     doctor_summary: doctorReport.summary,
     evidence_refs: runState.evidence_refs,
     quality_outlook: deriveQualityOutlook(runState, deliveryMap.findings),
+    candidate_runs: runState.candidate_runs ?? [],
     status_card: statusCard,
     delivery_map: {
       relationships: deliveryMap.relationships,

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

@@ -84,6 +84,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.

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

@@ -382,6 +382,15 @@ host control is presented, or the agent immediately uses the exact-text
 fallback. A host that does not apply the control does not trigger a second
 native prompt. AGDF must not simulate or force host-owned presentation.
 
+An eligible interaction must make its presentation outcome visible and
+distinguishable: `presented`, `unavailable_before_invocation`,
+`attempted_not_applied`, or `unsafe_to_wait`. This is transient presentation
+evidence only, never a persisted approval, selected-run authority or substitute
+for post-response revalidation. A textual fallback names the outcome, gives the
+exact approval value and confirms that authority is unchanged. A fresh explicit
+user request may reopen the unchanged decision after revalidation; it is not an
+automatic retry.
+
 A free-form native response is valid only when the existing exact-approval validator accepts it for the current gate after revalidation. A localized label, description, option position, recommendation style or host action never authorizes a gate. Revise, decline and cancel outcomes never advance a gate.
 
 Surface adapter rules:

package/generated/.opencode/agdf-runtime-contract.md

@@ -382,6 +382,15 @@ host control is presented, or the agent immediately uses the exact-text
 fallback. A host that does not apply the control does not trigger a second
 native prompt. AGDF must not simulate or force host-owned presentation.
 
+An eligible interaction must make its presentation outcome visible and
+distinguishable: `presented`, `unavailable_before_invocation`,
+`attempted_not_applied`, or `unsafe_to_wait`. This is transient presentation
+evidence only, never a persisted approval, selected-run authority or substitute
+for post-response revalidation. A textual fallback names the outcome, gives the
+exact approval value and confirms that authority is unchanged. A fresh explicit
+user request may reopen the unchanged decision after revalidation; it is not an
+automatic retry.
+
 A free-form native response is valid only when the existing exact-approval validator accepts it for the current gate after revalidation. A localized label, description, option position, recommendation style or host action never authorizes a gate. Revise, decline and cancel outcomes never advance a gate.
 
 Surface adapter rules:

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

@@ -84,6 +84,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.

package/generated/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",

package/generated/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
@@ -140,46 +140,55 @@
   "skillSet": [
     {
       "slug": "delivery-path-search",
+      "discovery": "optional",
       "useFor": "high-impact planning decisions with several plausible next delivery steps before implementation",
       "boundary": "read-only advisory search; never grants gate permission or replaces gate-check"
     },
     {
       "slug": "brownfield-analysis",
+      "discovery": "automatic",
       "useFor": "after gate-check permits Brownfield Review or implementation preparation, before non-trivial changes in existing systems",
       "boundary": "clarifies reuse, owners, risks and Mode/Slice Decision; never bypasses gate-check; Brownfield Review is not implementation permission"
     },
     {
       "slug": "clean-implementation-review",
+      "discovery": "automatic",
       "useFor": "inspect workarounds, fallbacks, parallel structures or symptom fixes",
       "boundary": "not a TP or QA substitute"
     },
     {
       "slug": "code-review",
+      "discovery": "automatic",
       "useFor": "mandatory CR step after code changes, focused on defects, regression and security findings",
       "boundary": "does not replace TP review, clean review or QA"
     },
     {
       "slug": "delivery-closeout",
+      "discovery": "automatic",
       "useFor": "commit/PR-near handoff after QA/OR/UAT",
       "boundary": "never performs VCS actions automatically"
     },
     {
       "slug": "gate-check",
+      "discovery": "start_here",
       "useFor": "new build/change intent, unclear approval, Structured Delivery, later-gate artefact requested",
       "boundary": "does not create later artefacts or skip Mode/Slice Decision after Brownfield Review"
     },
     {
       "slug": "qa-gate",
+      "discovery": "automatic",
       "useFor": "final QA decision",
       "boundary": "only instance for `pass | revise | block`"
     },
     {
       "slug": "release-or",
+      "discovery": "automatic",
       "useFor": "auditable closeout for every relevant run",
       "boundary": "not a QA substitute"
     },
     {
       "slug": "task-plan-review",
+      "discovery": "automatic",
       "useFor": "after implementation and before QA, verify TP coverage",
       "boundary": "no final QA decision"
     }

package/generated/plugins/agdf/meta/agdf-runtime-contract.md

@@ -382,6 +382,15 @@ host control is presented, or the agent immediately uses the exact-text
 fallback. A host that does not apply the control does not trigger a second
 native prompt. AGDF must not simulate or force host-owned presentation.
 
+An eligible interaction must make its presentation outcome visible and
+distinguishable: `presented`, `unavailable_before_invocation`,
+`attempted_not_applied`, or `unsafe_to_wait`. This is transient presentation
+evidence only, never a persisted approval, selected-run authority or substitute
+for post-response revalidation. A textual fallback names the outcome, gives the
+exact approval value and confirms that authority is unchanged. A fresh explicit
+user request may reopen the unchanged decision after revalidation; it is not an
+automatic retry.
+
 A free-form native response is valid only when the existing exact-approval validator accepts it for the current gate after revalidation. A localized label, description, option position, recommendation style or host action never authorizes a gate. Revise, decline and cancel outcomes never advance a gate.
 
 Surface adapter rules:

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

@@ -84,6 +84,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.

package/lib/interaction-presentation.js

@@ -1,6 +1,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"]);
 
 function plainObject(value) {
   return value && typeof value === "object" && !Array.isArray(value);
@@ -111,6 +112,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 "";
@@ -166,4 +206,5 @@ export function normalizeInteractionOutcome(value, { expectedApproval, stale = f
 export const interactionPresentationConstants = Object.freeze({
   artefactOrder: Object.freeze([...ARTEFACT_ORDER]),
   outcomes: Object.freeze([...OUTCOMES]),
+  attemptOutcomes: Object.freeze([...ATTEMPT_OUTCOMES]),
 });

package/package.json

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