create-agdf 0.6.9 → 0.7.1

package/bin/create-agdf.js

@@ -3,7 +3,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
-import { dirname, join, posix, resolve } from "node:path";
+import { dirname, isAbsolute, join, posix, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import process from "node:process";
 import { searchInputFromControl } from "../lib/delivery-path-search/state-adapter.js";
@@ -32,14 +32,23 @@ const generatedRoot = join(packageRoot, "generated");
 const pluginDefinitionPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-plugin.definition.json");
 const pluginDefinition = JSON.parse(readFileSync(pluginDefinitionPath, "utf8"));
 const pluginInstallCommand = "npx --yes @agdf/cli@latest claude";
-const npmCommand = process.platform === "win32" ? process.execPath : "npm";
-const npmPrefixArgs = process.platform === "win32" ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")] : [];
+const testNpmCliPath = process.env.NODE_ENV === "test" ? process.env.AGDF_TEST_NPM_CLI_PATH || "" : "";
+const npmCommand = testNpmCliPath
+  ? process.execPath
+  : process.platform === "win32"
+    ? process.execPath
+    : "npm";
+const npmPrefixArgs = testNpmCliPath
+  ? [testNpmCliPath]
+  : process.platform === "win32"
+    ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")]
+    : [];
 const allowedTargets = new Set(["codex", "codex-repo", "claude", "copilot", "opencode", "opencode-status", "opencode-repo", "both", "init", "config", "doctor", "gate-check", "delivery-map", "delivery-path-search", "run-create", "run-migrate", "run-render-legacy"]);
 const agdfFragmentPath = "AGENTS.agdf.md";
 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"]);
+const internalStepArtefacts = new Set(["Brownfield Review", "Verified Change", "Brownfield Analysis", "CD+Tests", "CR"]);
 const deliveryRelationships = [
   { from: "UR", relationship: "approved_by", to: "Approval: UR", requiredBy: "UR" },
   { from: "PRD", relationship: "derived_from", to: "UR", requiredBy: "PRD" },
@@ -52,6 +61,7 @@ const nextSkillByGate = {
   "Brownfield Review": "brownfield-analysis",
   "Mode/Slice Decision": "gate-check",
   "Quick Task Execution": "none",
+  "Verified Change Execution": "gate-check",
   PRD: "gate-check",
   SD: "gate-check",
   TP: "gate-check",
@@ -62,21 +72,6 @@ const nextSkillByGate = {
   UAT: "delivery-closeout",
   OR: "release-or",
 };
-const gateProgressOrder = [
-  "UR",
-  "Brownfield Review",
-  "Mode/Slice Decision",
-  "Quick Task Execution",
-  "PRD",
-  "SD",
-  "TP",
-  "Brownfield Analysis",
-  "CD+Tests",
-  "CR",
-  "QA",
-  "UAT",
-  "OR",
-];
 const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.codex.skillPrefix}${skill.slug}`);
 const copilotSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.copilot.skillPrefix}${skill.slug}`);
 const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.skillPrefix}${skill.slug}`);
@@ -96,6 +91,7 @@ const codexPluginFiles = [
   join("plugins", "agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
   join("plugins", "agdf", "control", "templates", "artefacts", "UR.md"),
   join("plugins", "agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "VERIFIED_CHANGE.md"),
   join("plugins", "agdf", "control", "templates", "artefacts", "PRD.md"),
   join("plugins", "agdf", "control", "templates", "artefacts", "SD.md"),
   join("plugins", "agdf", "control", "templates", "artefacts", "TP.md"),
@@ -120,6 +116,7 @@ const controlFiles = [
   join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
   join(".agdf", "control", "templates", "artefacts", "UR.md"),
   join(".agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.md"),
+  join(".agdf", "control", "templates", "artefacts", "VERIFIED_CHANGE.md"),
   join(".agdf", "control", "templates", "artefacts", "PRD.md"),
   join(".agdf", "control", "templates", "artefacts", "SD.md"),
   join(".agdf", "control", "templates", "artefacts", "TP.md"),
@@ -151,6 +148,7 @@ const liveControlFiles = [
 const artefactTemplateFiles = [
   join(".agdf", "control", "templates", "artefacts", "UR.md"),
   join(".agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.md"),
+  join(".agdf", "control", "templates", "artefacts", "VERIFIED_CHANGE.md"),
   join(".agdf", "control", "templates", "artefacts", "PRD.md"),
   join(".agdf", "control", "templates", "artefacts", "SD.md"),
   join(".agdf", "control", "templates", "artefacts", "TP.md"),
@@ -481,6 +479,7 @@ function defaultOpenCodeConfigDir() {
 
 function installOpenCodeGlobalPlugin(configDir) {
   assertGlobalOpenCodeSurfaceWritable(configDir);
+  const previousPackage = resolveOpenCodePackage(configDir);
   const configPath = join(configDir, "opencode.json");
   let config = {};
 
@@ -528,15 +527,21 @@ function installOpenCodeGlobalPlugin(configDir) {
 
   mkdirSync(configDir, { recursive: true });
   try {
-    execFileSync(npmCommand, [...npmPrefixArgs, "install", "--silent", "--save-prod", "--prefix", configDir, packageRoot], { stdio: "pipe" });
+    const packageSpecifier = `${pluginDefinition.opencode.npmPackage}@${pluginDefinition.version}`;
+    execFileSync(npmCommand, [...npmPrefixArgs, "install", "--silent", "--save-prod", "--save-exact", packageSpecifier], {
+      cwd: configDir,
+      stdio: "pipe",
+    });
   } catch (error) {
     throw new Error(`Failed to install ${pluginDefinition.opencode.npmPackage} into the OpenCode config directory: ${(error.stderr || error.message).toString().trim()}`);
   }
   writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+  const installedPackage = resolveOpenCodePackage(configDir);
 
   return {
     configPath,
     added: !alreadyInstalled,
+    transition: openCodePackageTransition(previousPackage, installedPackage),
   };
 }
 
@@ -661,24 +666,64 @@ function isOpenCodeRepositorySurfacePresent(targetDir) {
 function resolveOpenCodePackage(configDir) {
   const packageName = pluginDefinition.opencode.npmPackage;
   try {
+    const resolvedPath = execFileSync(process.execPath, ["-e", `process.stdout.write(require.resolve(${JSON.stringify(packageName)}))`], {
+      cwd: configDir,
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+    let installedVersion = "";
+    try {
+      const packageManifest = JSON.parse(readFileSync(join(dirname(resolvedPath), "package.json"), "utf8"));
+      installedVersion = typeof packageManifest.version === "string" && packageManifest.version.trim() ? packageManifest.version.trim() : "";
+    } catch {
+      installedVersion = "";
+    }
     return {
       loadable: true,
-      path: execFileSync(process.execPath, ["-e", `process.stdout.write(require.resolve(${JSON.stringify(packageName)}))`], {
-        cwd: configDir,
-        encoding: "utf8",
-        stdio: "pipe",
-      }),
+      path: resolvedPath,
+      installed_version: installedVersion,
       error: "",
     };
   } catch (error) {
     return {
       loadable: false,
       path: "",
+      installed_version: "",
       error: (error.stderr || error.message || "package not resolvable").toString().trim(),
     };
   }
 }
 
+function openCodePackageVersionStatus(packageState) {
+  if (!packageState.loadable) return "unloadable";
+  if (!packageState.installed_version) return "unknown";
+  return packageState.installed_version === pluginDefinition.version ? "current" : "outdated";
+}
+
+function openCodePackageTransition(previousPackage, installedPackage) {
+  const previousVersion = previousPackage.loadable ? previousPackage.installed_version : "";
+  const installedVersion = installedPackage.loadable ? installedPackage.installed_version : "";
+  if (!installedVersion || (previousPackage.loadable && !previousVersion)) {
+    return {
+      previous_version: previousVersion,
+      installed_version: installedVersion,
+      status: "unknown",
+    };
+  }
+  if (!previousPackage.loadable) {
+    return {
+      previous_version: "",
+      installed_version: installedVersion,
+      status: "installed",
+    };
+  }
+  return {
+    previous_version: previousVersion,
+    installed_version: installedVersion,
+    status: previousVersion === installedVersion ? "unchanged" : "updated",
+  };
+}
+
 function evaluateGlobalOpenCodeSurface(configDir) {
   const paths = globalOpenCodeConfigPaths(configDir);
   const skillCount = globalOpenCodeSkillNames.filter((skillName) => existsSync(join(paths.skills, skillName, "SKILL.md"))).length;
@@ -693,12 +738,13 @@ function evaluateGlobalOpenCodeSurface(configDir) {
   };
 }
 
-function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir()) {
+function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(), transition = null) {
   const configPath = join(configDir, "opencode.json");
   const configState = readOpenCodeConfig(configPath);
   const plugins = Array.isArray(configState.config.plugin) ? configState.config.plugin : [];
   const globalConfigured = plugins.includes(pluginDefinition.opencode.npmPackage);
   const packageState = resolveOpenCodePackage(configDir);
+  const packageVersionStatus = openCodePackageVersionStatus(packageState);
   const globalNativeSurface = evaluateGlobalOpenCodeSurface(configDir);
   const sessionSignals = {
     active: process.env.AGDF_PLUGIN_ACTIVE === "1",
@@ -714,6 +760,8 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
   if (configState.parseError) findings.push(`OpenCode global config is not valid JSON: ${configState.parseError}`);
   if (!globalConfigured) findings.push(`OpenCode global config does not include ${pluginDefinition.opencode.npmPackage}.`);
   if (!packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is not loadable from the OpenCode config directory.`);
+  if (packageVersionStatus === "outdated") findings.push(`${pluginDefinition.opencode.npmPackage} version ${packageState.installed_version} is outdated; expected ${pluginDefinition.version}.`);
+  if (packageVersionStatus === "unknown" && packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is loadable but its installed version is unknown.`);
   if (!globalNativeSurface.complete) findings.push(`Global OpenCode native skill surface is incomplete (${globalNativeSurface.skill_count}/${globalNativeSurface.expected_skill_count} skills).`);
   if (!sessionSignals.active) findings.push("No active AGDF OpenCode session signal is visible in this process.");
   if (!repositorySurface) findings.push("Current repository does not contain the AGDF OpenCode surface.");
@@ -731,6 +779,10 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
       name: pluginDefinition.opencode.npmPackage,
       loadable: packageState.loadable,
       resolved_path: packageState.path,
+      installed_version: packageState.installed_version || null,
+      expected_version: pluginDefinition.version,
+      version_status: packageVersionStatus,
+      ...(transition ? { transition } : {}),
       error: packageState.error,
     },
     global_native_surface: globalNativeSurface,
@@ -744,7 +796,9 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
     },
     visible_entrypoint: repositorySurface ? `${pluginDefinition.opencode.skillPrefix}gate-check (native skill)` : "none until opencode-repo is installed for this repository",
     findings,
-    next_step: !globalNativeSurface.complete
+    next_step: packageVersionStatus !== "current"
+      ? "Run npx --yes @agdf/cli@latest opencode to install or repair the OpenCode package version."
+      : !globalNativeSurface.complete
       ? "Run npx --yes @agdf/cli@latest opencode to install or repair the global native OpenCode skill surface."
       : repositorySurface
       ? `Restart OpenCode if needed, then load ${pluginDefinition.opencode.skillPrefix}gate-check through the native skill tool for new build/change intent.`
@@ -764,6 +818,18 @@ function printOpenCodeStatus(report, json) {
   if (report.global_config.parse_error) console.log(`Config parse error: ${report.global_config.parse_error}`);
   console.log(`Package loadable: ${report.package.loadable ? "yes" : "no"}`);
   if (report.package.resolved_path) console.log(`Package path: ${report.package.resolved_path}`);
+  console.log(`Package version: ${report.package.installed_version || "unknown"}`);
+  console.log(`Expected version: ${report.package.expected_version}`);
+  console.log(`Version status: ${report.package.version_status}`);
+  if (report.package.transition?.status === "updated") {
+    console.log(`Version transition: ${report.package.transition.previous_version} -> ${report.package.transition.installed_version}`);
+  } else if (report.package.transition?.status === "installed") {
+    console.log(`Version transition: new install (${report.package.transition.installed_version || "unknown"})`);
+  } else if (report.package.transition?.status === "unchanged") {
+    console.log(`Version transition: unchanged (${report.package.transition.installed_version})`);
+  } else if (report.package.transition?.status === "unknown") {
+    console.log("Version transition: unknown");
+  }
   console.log(`Global native skills: ${report.global_native_surface.complete ? "complete" : "incomplete"} (${report.global_native_surface.skill_count}/${report.global_native_surface.expected_skill_count})`);
   console.log(`Global skill path: ${report.global_native_surface.path}`);
   console.log(`Session active signal: ${report.session.active ? "yes" : "no"}`);
@@ -1647,6 +1713,12 @@ function evaluateDoctor(targetDir, selection = {}) {
     }
 
     const runState = selectedRunState;
+    if (modeSliceDecision(runState) === "verified_change") {
+      const verifiedChange = evaluateVerifiedChange(targetDir, runState);
+      for (const finding of verifiedChange.findings) {
+        addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
+      }
+    }
     for (const finding of analyzeDurableGateArtefactConsistency(runState)) {
       addFinding(findings, finding.severity, finding.code, finding.message, finding.path, finding.next_step);
     }
@@ -1698,6 +1770,115 @@ function extractField(content, field) {
   return content.match(pattern)?.[1]?.trim() ?? "";
 }
 
+const verifiedChangeStatuses = new Set(["draft", "eligible", "executed", "escalated"]);
+const verifiedChangeEscalationTargets = new Set(["structured_slice", "structured_delivery"]);
+
+function parseVerifiedChangePathList(value) {
+  const cleaned = cleanStatusCell(value ?? "");
+  if (!cleaned || cleaned === "none") return [];
+  return cleaned.split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+function isSafeRepoRelativePath(value) {
+  if (!value || value === "none" || value.startsWith("/") || value.includes("\\")) return false;
+  const normalized = posix.normalize(value);
+  return normalized !== "." && normalized !== ".." && !normalized.startsWith("../") && normalized === value;
+}
+
+function gitPathList(targetDir, args) {
+  try {
+    return execFileSync("git", args, { cwd: targetDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+      .split("\n")
+      .map((item) => item.trim())
+      .filter(Boolean);
+  } 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: "" };
+  if (!isSafeRepoRelativePath(artefact.path)) return { status: "invalid", path: artefact.path, content: "", error: "record_path_invalid" };
+  const absolutePath = resolve(targetDir, artefact.path);
+  const relativePath = relative(resolve(targetDir), absolutePath);
+  if (isAbsolute(relativePath) || relativePath === ".." || relativePath.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || !existsSync(absolutePath)) {
+    return { status: "missing", path: artefact.path, content: "", error: "record_missing" };
+  }
+  return { status: "present", path: artefact.path, content: readFileSync(absolutePath, "utf8") };
+}
+
+function evaluateVerifiedChange(targetDir, runState) {
+  const record = readVerifiedChangeRecord(targetDir, runState);
+  const findings = [];
+  const add = (code, message, nextStep, severity = "revise") => findings.push({
+    severity,
+    code,
+    message,
+    path: record.path || runState.path,
+    next_step: nextStep,
+  });
+
+  if (record.status === "missing") {
+    return { status: "missing", record, findings };
+  }
+  if (record.status === "invalid") {
+    add("AGDF_VERIFIED_CHANGE_RECORD_PATH_INVALID", "Verified Change record path must be a repository-relative path inside the target repository.", "Link a stable repository-relative VERIFIED_CHANGE.md artefact from the selected run state.", "block");
+    return { status: "invalid", record, findings };
+  }
+
+  const status = cleanStatusCell(extractField(record.content, "status"));
+  const relatedUr = cleanStatusCell(extractField(record.content, "related_ur"));
+  const escalationTarget = cleanStatusCell(extractField(record.content, "escalation_target"));
+  const canonicalOwner = cleanStatusCell(extractField(record.content, "canonical_owner"));
+  const sourcePaths = parseVerifiedChangePathList(extractField(record.content, "allowed_source_paths"));
+  const derivedPaths = parseVerifiedChangePathList(extractField(record.content, "allowed_derived_paths"));
+  const prohibitedImpacts = cleanStatusCell(extractField(record.content, "prohibited_impacts"));
+  const propagationCommand = extractField(record.content, "propagation_command");
+  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 validationStatus = cleanStatusCell(extractField(record.content, "validation_status"));
+  const propagationStatus = cleanStatusCell(extractField(record.content, "propagation_status"));
+  const urArtefact = runState.artefacts.get("UR");
+
+  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.");
+  if (!verifiedChangeEscalationTargets.has(escalationTarget)) add("AGDF_VERIFIED_CHANGE_ESCALATION_INVALID", "Verified Change record must declare structured_slice or structured_delivery as its escalation target.", "Record the Brownfield-selected structured escalation target.");
+  if (!canonicalOwner || canonicalOwner.includes(",") || !isSafeRepoRelativePath(canonicalOwner)) add("AGDF_VERIFIED_CHANGE_OWNER_INVALID", "Verified Change requires exactly one repository-relative canonical_owner.", "Name one canonical owner path; otherwise escalate.");
+  if (sourcePaths.length === 0 || sourcePaths.some((path) => !isSafeRepoRelativePath(path))) add("AGDF_VERIFIED_CHANGE_SOURCE_PATHS_INVALID", "Verified Change requires non-empty normalized allowed_source_paths.", "Declare a bounded comma-separated source path list; otherwise escalate.");
+  if (derivedPaths.some((path) => !isSafeRepoRelativePath(path))) add("AGDF_VERIFIED_CHANGE_DERIVED_PATHS_INVALID", "Verified Change derived paths must be normalized repository-relative paths or none.", "Correct the derived path list or escalate.");
+  if (prohibitedImpacts !== "none") add("AGDF_VERIFIED_CHANGE_IMPACTS_INVALID", "Verified Change must declare prohibited_impacts: none after checking gates, permissions, security, persistence, architecture, external API, CLI and release behavior.", "Use the structured path when any prohibited impact applies.");
+  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.");
+
+  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");
+  } 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");
+  }
+
+  if (status === "executed") {
+    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.");
+  }
+
+  if (status === "escalated") return { status: "escalated", record, escalation_target: escalationTarget, findings };
+  if (findings.length > 0) return { status: "invalid", record, escalation_target: escalationTarget, findings };
+  return { status, record, escalation_target: escalationTarget, findings };
+}
+
 function cleanStatusCell(value) {
   return value.replace(/^`|`$/g, "").trim();
 }
@@ -1753,20 +1934,6 @@ function readRunState(targetDir, selection = {}) {
   };
 }
 
-function firstUnapprovedGate(approvals) {
-  for (const gate of userGateOrder) {
-    const status = approvals.get(gate)?.status ?? "";
-    if (status !== "approved" && status !== "not_applicable") return gate;
-  }
-  return "OR";
-}
-
-function normalizeCurrentGate(value, fallbackGate) {
-  if (isPlaceholderValue(value)) return fallbackGate;
-  const normalized = value.replace(/`/g, "").trim();
-  return normalized || fallbackGate;
-}
-
 function gateApprovalStatus(runState, gate) {
   if (!userGateOrder.includes(gate)) return "not_applicable";
   return runState.approvals.get(gate)?.status ?? "";
@@ -1820,7 +1987,9 @@ function analyzeDurableGateArtefactConsistency(runState) {
 function isInternalStepSatisfied(runState, step) {
   const artefact = runState.artefacts.get(step);
   if (!artefact) return false;
-  return artefact.status === "done" || artefact.status === "not_applicable";
+  if (artefact.status === "done") return true;
+  return artefact.status === "not_applicable"
+    && (step === "Brownfield Review" || step === "Brownfield Analysis");
 }
 
 function modeSliceDecision(runState) {
@@ -2039,15 +2208,6 @@ function buildStatusCard({
   };
 }
 
-function effectiveCurrentGate(runState, transitionDecision) {
-  if (transitionDecision.status !== "open") return transitionDecision.current_gate;
-  const explicitGate = normalizeCurrentGate(runState.current_gate, "");
-  const explicitIndex = gateProgressOrder.indexOf(explicitGate);
-  const fallbackIndex = gateProgressOrder.indexOf(transitionDecision.current_gate);
-  if (explicitIndex === -1 || fallbackIndex === -1) return transitionDecision.current_gate;
-  return explicitIndex > fallbackIndex ? explicitGate : transitionDecision.current_gate;
-}
-
 function durableArtefactBlock(gate, nextGate) {
   const label = gate === "QA" ? "QA report" : `${gate} artefact`;
   const stablePath = gate === "QA" ? ".agdf/control/artefacts/<key>/QA_REPORT.md" : `.agdf/control/artefacts/<key>/${gate}.md`;
@@ -2076,7 +2236,7 @@ function isGateSatisfied(runState, gate) {
   return isDurableGateArtefactSatisfied(runState, gate);
 }
 
-function transitionDecisionForRunState(runState) {
+function transitionDecisionForRunState(runState, verifiedChange = null) {
   if (gateApprovalStatus(runState, "UR") === "approved" && !isGateSatisfied(runState, "UR")) return durableArtefactBlock("UR", "PRD");
 
   if (!isGateSatisfied(runState, "UR")) {
@@ -2118,7 +2278,7 @@ function transitionDecisionForRunState(runState) {
         blocking_reason: "none",
         missing_approval: "none",
         allowed: [
-          "decide whether the approved UR is quick_task, structured_slice, structured_delivery or block",
+          "decide whether the approved UR is quick_task, verified_change, structured_slice, structured_delivery or block",
           "record scope reason, evidence and required next gate depth in the selected RUN_STATE.md",
           "choose the next required gate depth before drafting PRD or implementing",
         ],
@@ -2151,6 +2311,53 @@ function transitionDecisionForRunState(runState) {
       };
     }
 
+    if (modeDecision === "verified_change") {
+      const state = verifiedChange?.status ?? "missing";
+      const escalationTarget = verifiedChange?.escalation_target ?? "structured_slice";
+      if (state === "executed") {
+        return {
+          status: "open",
+          current_gate: "OR",
+          blocking_reason: "none",
+          missing_approval: "none",
+          allowed: ["use the Verified Change mini-closeout", "offer delivery closeout when requested"],
+          forbidden: ["create PRD, SD, TP, QA or UAT by ritual", "commit, push, open PR or release automatically"],
+          next_allowed_action: "Close the executed Verified Change with its compact record and offer delivery closeout; do not perform VCS actions automatically.",
+        };
+      }
+      if (state === "escalated" || (state === "invalid" && verifiedChangeEscalationTargets.has(escalationTarget))) {
+        return {
+          status: "open",
+          current_gate: "PRD",
+          blocking_reason: state === "escalated" ? "verified_change_escalated" : "verified_change_invalid_escalated",
+          missing_approval: "Approval: PRD",
+          allowed: ["draft the structured PRD required by the declared escalation target", "retain the Verified Change escalation evidence"],
+          forbidden: ["implement through Verified Change", "create SD or TP before PRD approval", "claim QA or release readiness"],
+          next_allowed_action: `Proceed as ${escalationTarget}: draft the required PRD and request exact approval: Approval: PRD.`,
+        };
+      }
+      if (state === "eligible") {
+        return {
+          status: "open",
+          current_gate: "Verified Change Execution",
+          blocking_reason: "none",
+          missing_approval: "none",
+          allowed: ["implement only declared source and derived paths", "run declared propagation and validation commands", "record execution evidence and mini-closeout"],
+          forbidden: ["touch unlisted paths", "add prohibited impacts", "claim QA, UAT or release readiness"],
+          next_allowed_action: "Implement only the eligible Verified Change record scope, then record passing propagation and validation evidence.",
+        };
+      }
+      return {
+        status: state === "missing" || state === "draft" ? "open" : "blocked",
+        current_gate: "Verified Change Execution",
+        blocking_reason: state === "invalid" ? "verified_change_invalid" : "verified_change_record_required",
+        missing_approval: "none",
+        allowed: ["create or refine the compact Verified Change record", "capture baseline paths", "prove fail-closed eligibility with doctor and gate-check"],
+        forbidden: ["implement candidate changes", "claim validation, QA, UAT or release readiness"],
+        next_allowed_action: "Create or repair VERIFIED_CHANGE.md, capture the baseline and satisfy every eligibility check before implementation; escalate when any condition cannot be proven.",
+      };
+    }
+
     return {
       status: "open",
       current_gate: "PRD",
@@ -2192,6 +2399,43 @@ function transitionDecisionForRunState(runState) {
     };
   }
 
+  const implementationStepsRequired = gateApprovalStatus(runState, "TP") === "approved";
+  if (implementationStepsRequired && !isInternalStepSatisfied(runState, "Brownfield Analysis")) {
+    return {
+      status: "open",
+      current_gate: "Brownfield Analysis",
+      blocking_reason: "none",
+      missing_approval: "none",
+      allowed: ["run Brownfield Analysis for the approved TP scope", "verify existing owners, reuse paths and regression risks"],
+      forbidden: ["implement before Brownfield evidence supports the approved TP path", "claim QA or release readiness"],
+      next_allowed_action: "Run Brownfield Analysis for the approved TP scope before CD+Tests.",
+    };
+  }
+
+  if (implementationStepsRequired && !isInternalStepSatisfied(runState, "CD+Tests")) {
+    return {
+      status: "open",
+      current_gate: "CD+Tests",
+      blocking_reason: "none",
+      missing_approval: "none",
+      allowed: ["implement the approved TP tasks", "run the approved test plan", "record implementation and test evidence"],
+      forbidden: ["claim QA pass", "request UAT approval", "release"],
+      next_allowed_action: "Implement the approved TP scope, run its tests, and record CD+Tests evidence before CR.",
+    };
+  }
+
+  if (implementationStepsRequired && !isInternalStepSatisfied(runState, "CR")) {
+    return {
+      status: "open",
+      current_gate: "CR",
+      blocking_reason: "none",
+      missing_approval: "none",
+      allowed: ["run mandatory code review", "record correctness, regression, security and maintainability findings", "fix blocking review findings"],
+      forbidden: ["claim QA pass", "request UAT approval", "release"],
+      next_allowed_action: "Run Code Review for the implemented TP scope and resolve blocking findings before QA.",
+    };
+  }
+
   if (gateApprovalStatus(runState, "QA") === "approved" && !isGateSatisfied(runState, "QA")) return durableArtefactBlock("QA", "UAT");
 
   if (isGateSatisfied(runState, "QA") && !isGateSatisfied(runState, "UAT")) {
@@ -2220,30 +2464,38 @@ function transitionDecisionForRunState(runState) {
 
   return {
     status: "open",
-    current_gate: "Brownfield Analysis",
+    current_gate: "QA",
     blocking_reason: "none",
-    missing_approval: "none",
-    allowed: ["run Brownfield Analysis for the approved TP scope", "verify existing owners, reuse paths and regression risks"],
-    forbidden: ["implement before Brownfield evidence supports the approved TP path", "claim QA or release readiness"],
-    next_allowed_action: "Run Brownfield Analysis for the approved TP scope before CD+Tests.",
+    missing_approval: "Approval: QA",
+    allowed: ["run QA gate", "persist or refine the QA report", "request exact QA approval"],
+    forbidden: ["request UAT approval", "release", "claim delivery readiness before QA approval and report evidence"],
+    next_allowed_action: "Run the QA gate, persist the QA report, and request exact approval: Approval: QA",
   };
 }
 
 function evaluateGateCheck(targetDir, selection = {}) {
   const doctorReport = evaluateDoctor(targetDir, selection);
   const runState = readRunState(targetDir, selection);
-  const transitionDecision = transitionDecisionForRunState(runState);
+  const verifiedChange = modeSliceDecision(runState) === "verified_change"
+    ? evaluateVerifiedChange(targetDir, runState)
+    : null;
+  const transitionDecision = transitionDecisionForRunState(runState, verifiedChange);
   const deliveryMap = analyzeDeliveryMap(runState);
   const doctorBlocker = doctorReport.findings.find((finding) => finding.severity === "block");
   const doctorRevise = doctorReport.findings.find((finding) => finding.severity === "revise");
+  const routesInvalidVerifiedChange = modeSliceDecision(runState) === "verified_change"
+    && verifiedChange?.status === "invalid"
+    && verifiedChangeEscalationTargets.has(verifiedChange.escalation_target);
 
   let status = transitionDecision.status;
-  let currentGate = effectiveCurrentGate(runState, transitionDecision);
+  let currentGate = transitionDecision.current_gate;
   let blockingReason = transitionDecision.blocking_reason;
   let missingApproval = transitionDecision.missing_approval;
   let allowed = transitionDecision.allowed;
   let forbidden = transitionDecision.forbidden;
-  let nextAllowedAction = isPlaceholderValue(runState.next_allowed_action)
+  let nextAllowedAction = modeSliceDecision(runState) === "verified_change"
+    ? transitionDecision.next_allowed_action
+    : isPlaceholderValue(runState.next_allowed_action)
     ? transitionDecision.next_allowed_action
     : runState.next_allowed_action;
 
@@ -2259,13 +2511,13 @@ function evaluateGateCheck(targetDir, selection = {}) {
     ];
     forbidden = ["create PRD", "create SD", "create TP", "run Brownfield Analysis", "implement code", "claim QA or release readiness"];
     nextAllowedAction = "Draft the minimal UR for the request in the response, then ask for exact approval: Approval: UR. Do not write a full .agdf/control scaffold unless durable control state or deterministic setup is explicitly needed.";
-  } else if (doctorBlocker) {
+  } else if (doctorBlocker && !routesInvalidVerifiedChange) {
     status = "blocked";
     blockingReason = doctorBlocker.code;
     allowed = ["repair the AGDF control scaffold", ...transitionDecision.allowed, "run doctor again"];
     forbidden = ["create later-gate artefacts beyond the current allowed gate", "implement gated work", "claim QA or release readiness"];
     nextAllowedAction = doctorBlocker.next_step;
-  } else if (doctorRevise) {
+  } else if (doctorRevise && !routesInvalidVerifiedChange) {
     status = "blocked";
     blockingReason = doctorRevise.code;
     allowed = [...new Set(["complete the current control-state fields", ...transitionDecision.allowed, "run doctor again"])];
@@ -2311,6 +2563,7 @@ function evaluateGateCheck(targetDir, selection = {}) {
       memory: deliveryMap.memory,
       findings: deliveryMap.findings,
     },
+    verified_change: verifiedChange,
     doctor_report: doctorReport,
   };
 }
@@ -2413,7 +2666,7 @@ function evaluateDeliveryMap(targetDir, selection = {}) {
   const runState = readRunState(targetDir, selection);
   const map = analyzeDeliveryMap(runState);
   const gateDecision = transitionDecisionForRunState(runState);
-  const currentGate = effectiveCurrentGate(runState, gateDecision);
+  const currentGate = gateDecision.current_gate;
 
   const severityRank = { block: 3, revise: 2, warn: 1 };
   const deliverySeverity = map.findings.reduce((max, finding) => Math.max(max, severityRank[finding.severity] ?? 0), 0);
@@ -2647,7 +2900,7 @@ async function main() {
       const result = installOpenCodeGlobalPlugin(configDir);
       installOpenCodeGlobalSurface(configDir);
       console.log(`AGDF OpenCode global plugin ${result.added ? "installed" : "already present"}: ${result.configPath}`);
-      const report = evaluateOpenCodeStatus(options.dir, configDir);
+      const report = evaluateOpenCodeStatus(options.dir, configDir, result.transition);
       printOpenCodeStatus(report, false);
       console.log("Restart OpenCode so it loads the updated global plugin config.");
     } catch (error) {

package/generated/.agdf/control/README.md

@@ -14,6 +14,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 | `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/Brownfield/PRD/SD/TP/QA/OR artefacts |
 | `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
 | `templates/artefacts/BROWNFIELD_REVIEW.md` | Template for the durable Brownfield Review and Mode/Slice Decision |
+| `templates/artefacts/VERIFIED_CHANGE.md` | Compact fail-closed record for an eligible Verified Change |
 | `templates/artefacts/PRD.md` | Template for the durable product requirements artefact |
 | `templates/artefacts/SD.md` | Template for the durable solution design artefact |
 | `templates/artefacts/TP.md` | Template for the durable task and test plan artefact |
@@ -84,7 +85,7 @@ npx --yes @agdf/cli@latest gate-check --json
 - The selected `runs/<run_id>/RUN_STATE.md` is the current run dashboard.
 - `config.json` stores the project preference for artefact and chat language; runtime rules stay English.
 - `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
-- Brownfield Review records the post-UR Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
+- Brownfield Review records the post-UR Mode/Slice Decision before PRD depth, Verified Change execution or Quick Task execution is chosen.
 - UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.
 - OR records the run closeout and next permissible step; it does not approve later gates.
 - `SOT_REGISTRY.md` decides which document owns which domain.