create-agdf 0.7.0 → 0.7.2

package/README.md

@@ -1,8 +1,34 @@
 # create-agdf
 
-Bootstrap AGDF repository instructions and a machine-checkable control loop for one repository.
+Bootstrap AGDF into the coding-agent surface and repository where work actually happens. It installs or generates the surface-specific guidance, skills and optional durable control files that help teams make scope, approvals, evidence and delivery state visible.
 
-## Usage
+AGDF is useful when AI-assisted work can affect an existing system and a team needs a traceable answer to: what is allowed next, who approved it and what evidence supports it. It is deliberately not a substitute for engineering judgement, security review, tests, product ownership or human acceptance. For the framework's fit, limits and examples, start with the [project overview](../README.md).
+
+## Quick start
+
+If you use Codex, this is the recommended first installation:
+
+```bash
+npx --yes @agdf/cli@latest codex
+```
+
+Restart Codex, open a new task in the repository you want to work in, and describe the intended change. AGDF starts with the smallest permitted governance step; it does not make implementation automatic.
+
+Use a different target when Codex is not your agent surface:
+
+| Surface or goal | Start with | What it gives you |
+|---|---|---|
+| Claude Code | `npx --yes @agdf/cli@latest claude` | The AGDF plugin for Claude Code. |
+| OpenCode, user-wide discovery | `npx --yes @agdf/cli@latest opencode` | The npm plugin and global native skills; repository governance remains opt-in. |
+| OpenCode, one repository | `npx --yes @agdf/cli@latest opencode-repo` | Repository instructions, native skills, permissions and control templates. |
+| GitHub Copilot | `npm create agdf@latest -- copilot` | Repository instructions, visible skills and control templates. |
+| Durable control state in an existing setup | `npx --yes @agdf/cli@latest init` | Live `.agdf/control/` state when the repository explicitly needs it. |
+
+For prerequisites, all surface-specific flows and operational boundaries, use the authoritative [installation guide](../INSTALL.md). Do not run `init` merely to ask a fresh question: an agent can first clarify the request and ask for `Approval: UR` when durable control state is needed.
+
+## Full command reference
+
+The commands below are the complete package reference. The Quick Start above is the recommended entry point; these commands cover the remaining surfaces, repository-local variants and validation paths.
 
 Preferred long-term CLI shape:
 
@@ -53,7 +79,7 @@ If no language is provided, `create-agdf` derives the preference from the local
 - `copilot` writes `AGENTS.md`, Copilot custom instructions under `.github/`, visible repository skills under `.github/skills/`, and AGDF control templates under `.agdf/control/`
 - `opencode` installs the AGDF npm plugin and nine native skills as a user-wide OpenCode surface
 - `opencode-status` reports OpenCode global config, package loadability, global native-skill completeness, session signals and repository surface presence
-- `opencode-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed native OpenCode skills under `.opencode/skills/`, explicit edit/bash/skill permissions, and AGDF control templates under `.agdf/control/`
+- `opencode-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed native OpenCode skills under `.opencode/skills/`, explicit question/edit/bash/skill permissions, and AGDF control templates under `.agdf/control/`
 - `both` writes the Codex repository-local marketplace plus the Copilot-facing repository files
 - `config` writes or updates only `.agdf/control/config.json` for an already installed plugin or an existing repository
 
@@ -84,9 +110,9 @@ Use the `opencode-repo` target when AGDF should be available to OpenCode from re
 npm create agdf@latest -- opencode-repo
 ```
 
-OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config, plus repository instructions from `.opencode/AGDF.md`, explicit `edit`/`bash`/`skill` permissions and canonical `agdf-` project skills under `.opencode/skills/`. Global adapters use the collision-safe `agdf-global-` prefix. AGDF for OpenCode has a global discoverability layer installed with `npx --yes @agdf/cli@latest opencode` and a repository-local governance surface generated by `opencode-repo`.
+OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config, plus repository instructions from `.opencode/AGDF.md`, explicit `question`/`edit`/`bash`/`skill` permissions and canonical `agdf-` project skills under `.opencode/skills/`. Global adapters use the collision-safe `agdf-global-` prefix. AGDF for OpenCode has a global discoverability layer installed with `npx --yes @agdf/cli@latest opencode` and a repository-local governance surface generated by `opencode-repo`.
 Those generated skills load on demand through OpenCode's native `skill` tool. Use `agdf-gate-check` first for new build/change intent or unclear approval.
-If `opencode.json` already exists, AGDF keeps it unchanged and writes `opencode.agdf.json` as a merge fragment.
+The built-in `question` tool can present a gate choice, but `.agdf/control/` and exact post-response validation remain authoritative; technical permission and auto-mode outcomes never approve an AGDF gate. If `opencode.json` already exists, AGDF keeps it unchanged and writes `opencode.agdf.json` as a merge fragment. Preserve any explicit `permission.question` decision when reviewing that fragment; `deny` uses exact-text fallback.
 The global layer makes the nine native AGDF skills discoverable, but does not activate repository governance by itself. Global skills fail closed until the current repository has `.opencode/AGDF.md`, `.opencode/skills/agdf-gate-check/SKILL.md` and `.agdf/control/`. Use `opencode-repo` to write that repository surface.
 
 ## Control scaffold
@@ -203,6 +229,18 @@ npm run test:routing
 
 The routing test installs `both` into a temporary target repository and checks that plugin routing stays unprefixed while Copilot routing receives the configured `agdf-` prefix.
 
+## Project, contribution and support
+
+This README is the package guide. Keep framework rationale, limits and examples in the [project overview](../README.md); keep target-specific installation in [INSTALL.md](../INSTALL.md); and use [RELEASE.md](../RELEASE.md) only when maintaining a published AGDF release.
+
+Non-sensitive feedback, examples and contributions are welcome through [GitHub Issues](https://github.com/ArndtGold/ai-native-governance-delivery-framework/issues). To validate a local package change before proposing it, run:
+
+```bash
+npm --prefix create-agdf run smoke-test
+```
+
+The repository is licensed under [Apache-2.0](../LICENSE). No separate public `CONTRIBUTING.md`, `SECURITY.md` or private security-reporting channel is currently published. Do not treat a public issue as a private vulnerability disclosure.
+
 ## Publishing
 
 The repository publishes this package and the primary user-facing `@agdf/cli` wrapper as one coupled AGDF release.

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";
@@ -48,7 +48,7 @@ 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", "Brownfield Analysis", "CD+Tests", "CR"]);
+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" },
@@ -61,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",
@@ -90,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"),
@@ -114,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"),
@@ -145,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"),
@@ -510,9 +514,10 @@ function installOpenCodeGlobalPlugin(configDir) {
   if (!nextConfig.instructions.includes("AGDF.md")) nextConfig.instructions.push("AGDF.md");
 
   if (nextConfig.permission === undefined) {
-    nextConfig.permission = { skill: { "agdf-*": "allow" } };
+    nextConfig.permission = { question: "allow", skill: { "agdf-*": "allow" } };
   } else if (nextConfig.permission && typeof nextConfig.permission === "object" && !Array.isArray(nextConfig.permission)) {
     nextConfig.permission = { ...nextConfig.permission };
+    if (nextConfig.permission.question === undefined) nextConfig.permission.question = "allow";
     if (nextConfig.permission.skill === undefined) {
       nextConfig.permission.skill = { "agdf-*": "allow" };
     } else if (nextConfig.permission.skill && typeof nextConfig.permission.skill === "object" && !Array.isArray(nextConfig.permission.skill)) {
@@ -1161,7 +1166,7 @@ function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOp
   }
   if (target === "opencode-repo") {
     if (wroteOpenCodeConfigFragment) {
-      console.log(`- Existing opencode.json detected. Merge ${openCodeConfigFragmentPath} into your current opencode.json so OpenCode loads .opencode/AGDF.md.`);
+      console.log(`- Existing opencode.json detected. Review ${openCodeConfigFragmentPath} and merge its owned entries so OpenCode loads .opencode/AGDF.md; preserve an explicit permission.question decision.`);
     }
     console.log(`- OpenCode will install the ${pluginDefinition.opencode.npmPackage} npm plugin from opencode.json at startup.`);
     console.log("- Optional: also add create-agdf to ~/.config/opencode/opencode.json plugin[] for a user-wide OpenCode hook.");
@@ -1709,6 +1714,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);
     }
@@ -1760,6 +1771,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();
 }
@@ -2117,7 +2237,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")) {
@@ -2159,7 +2279,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",
         ],
@@ -2192,6 +2312,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",
@@ -2310,10 +2477,16 @@ function transitionDecisionForRunState(runState) {
 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 = transitionDecision.current_gate;
@@ -2321,7 +2494,9 @@ function evaluateGateCheck(targetDir, selection = {}) {
   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;
 
@@ -2337,13 +2512,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"])];
@@ -2389,6 +2564,7 @@ function evaluateGateCheck(targetDir, selection = {}) {
       memory: deliveryMap.memory,
       findings: deliveryMap.findings,
     },
+    verified_change: verifiedChange,
     doctor_report: doctorReport,
   };
 }

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.

package/generated/.agdf/control/templates/AGDF_RUN.md

@@ -4,8 +4,8 @@
 
 - run_id:
 - started_at:
-- mode: `quick_task | structured_delivery`
-- current_gate: `none | UR | Brownfield Review | Mode/Slice Decision | PRD | SD | TP | Quick Task Execution | Brownfield Analysis | CD+Tests | CR | QA | UAT | OR`
+- mode: `quick_task | verified_change | structured_delivery`
+- current_gate: `none | UR | Brownfield Review | Mode/Slice Decision | PRD | SD | TP | Quick Task Execution | Verified Change Execution | Brownfield Analysis | CD+Tests | CR | QA | UAT | OR`
 - decision: `pass | revise | block | in_progress`
 - owner:
 
@@ -68,6 +68,7 @@ Valid approval format for new runs: `Approval: <GateName>`.
 | SD |  | `draft | approved | superseded | not_applicable` |  |
 | TP |  | `draft | approved | superseded | not_applicable` |  |
 | Brownfield Review |  | `missing | draft | done | not_applicable | superseded` |  |
+| Verified Change |  | `missing | draft | eligible | executed | escalated` |  |
 | Review |  | `missing | done | not_applicable` |  |
 | QA |  | `missing | pass | revise | block | not_applicable` |  |
 | OR |  | `missing | done | not_applicable` |  |
@@ -77,7 +78,7 @@ Valid approval format for new runs: `Approval: <GateName>`.
 Set this after Brownfield Review. Do not assume the full gate chain before the existing-system impact is understood.
 Quick Task execution or implementation is not allowed until this decision is visible with scope reason and evidence.
 
-- decision: `undecided | quick_task | structured_slice | structured_delivery | block`
+- decision: `undecided | quick_task | verified_change | structured_slice | structured_delivery | block`
 - required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
 - scope_reason:
 - evidence:

package/generated/.agdf/control/templates/RUN_STATE.md

@@ -43,6 +43,7 @@ Describe the trustworthy outcome.
 |---|---|---|---|
 | UR |  | draft |  |
 | Brownfield Review |  | missing |  |
+| Verified Change |  | missing |  |
 | PRD |  | missing |  |
 | SD |  | missing |  |
 | TP |  | missing |  |
@@ -53,7 +54,7 @@ Describe the trustworthy outcome.
 
 ## Mode/Slice Decision
 
-- decision:
+- decision: `quick_task | verified_change | structured_slice | structured_delivery | block`
 - required_next_gate:
 - scope_reason:
 - evidence:

package/generated/.agdf/control/templates/artefacts/BROWNFIELD_REVIEW.md

@@ -37,7 +37,7 @@ What approved UR scope is being sized and routed?
 
 ## Mode / Slice Decision
 
-- decision: `quick_task | structured_slice | structured_delivery | block`
+- decision: `quick_task | verified_change | structured_slice | structured_delivery | block`
 - required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
 - scope_reason:
 - evidence:

package/generated/.agdf/control/templates/artefacts/VERIFIED_CHANGE.md

@@ -0,0 +1,48 @@
+# Verified Change: <Title>
+
+Status: `draft | eligible | executed | escalated`
+
+## Record
+
+- status: draft
+- related_ur:
+- escalation_target: `structured_slice | structured_delivery`
+- canonical_owner:
+- allowed_source_paths:
+- allowed_derived_paths: none
+- prohibited_impacts: none
+- propagation_command: none
+- validation_commands:
+- baseline_tracked_paths: none
+- baseline_untracked_paths: none
+- validation_status: pending
+- propagation_status: not_applicable
+
+## Eligibility Assertions
+
+| Condition | Evidence | Status |
+|---|---|---|
+| Exactly one canonical owner |  | `pass | fail` |
+| Source and derived paths are bounded |  | `pass | fail` |
+| No gate, permission, security, persistence, architecture, external API, CLI or release impact |  | `pass | fail` |
+| Deterministic propagation is defined when derived paths exist |  | `pass | fail | not_applicable` |
+| Deterministic validation is defined |  | `pass | fail` |
+| Candidate paths are clean at baseline |  | `pass | fail` |
+
+## Execution Evidence
+
+| Evidence | Source | Result |
+|---|---|---|
+| Changed paths since baseline |  | `pass | fail` |
+| Propagation command |  | `pass | fail | not_applicable` |
+| Validation commands |  | `pass | fail` |
+
+## Mini-Closeout
+
+- delivered:
+- intentionally_not_delivered:
+- escalation_result: none
+- residual_risk: none
+- next_step:
+
+This compact record is valid only for a Brownfield-selected `verified_change`. Any missing, failed or ambiguous condition must set `status: escalated` and continue at `escalation_target`.

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

@@ -52,6 +52,32 @@ npx --yes @agdf/cli@latest delivery-map --json
 
 The CLI reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
 
+## Native Interaction Path
+
+Use the Runtime Contract's Native Interaction Contract to classify every candidate interaction as `clarification`, `tool_permission` or `gate_approval` before selecting a host control.
+
+Prefer inspection over asking. Do not invoke a structured question for status reporting, facts available in the repository, routine read-only work or a gate that is not ready. Do not repeatedly prompt for the same non-ready gate.
+
+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. Ask exactly one question that names the selected `run_id` and `current_gate`.
+4. Offer the exact approving option `Approval: <GateName>` plus bounded revise and cancel/decline outcomes.
+5. 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.
+6. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
+7. 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.
+8. Persist accepted input only through the existing control-state workflow.
+
+Surface behavior:
+
+- Codex: use the native short-question/request-user-input control when callable, ask one gate question and omit auto-resolution.
+- Claude Code: use `AskUserQuestion` only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; otherwise use exact text. Claude permissions and `ExitPlanMode` remain separate.
+- OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
+- Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
+
+A free-form response must still exactly match the current gate's approval formula after revalidation. Revise, decline and cancel never advance the gate. Native presentation, host permission and plan approval are inputs or separate authority domains, never durable AGDF authority.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
@@ -72,6 +98,7 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 17. If multiple active scopes are plausible, list the evidenced competing lines and keep the current step at scope clarification or the earliest common safe gate.
 18. When maintaining `MASTER_BACKLOG.md`, use its canonical compact columns, readable status labels and document-relative Markdown links. Do not expose raw long paths or internal snake_case statuses in the human-facing table. The canonical status/artefact label vocabulary is defined in the AGDF control scaffold's `MASTER_BACKLOG.md` template Rules section; do not invent other labels.
 19. Preserve legacy backlog compatibility through the CLI parser; do not create a second surface-specific backlog format.
+20. Native interaction must follow the Runtime Contract's interaction envelope, readiness check, deliberate-user-input requirement and post-response revalidation boundary.
 
 ## Gate Evaluation