create-agdf 0.13.8 → 0.14.2

package/generated/submissions/openai/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.13.8",
+  "version": "0.14.2",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Control layer for governed AI-assisted delivery.",
@@ -50,7 +50,10 @@
   },
   "copilot": {
     "skillPrefix": "agdf-",
-    "runtimeContractFileName": "agdf-runtime-contract.md"
+    "runtimeContractFileName": "agdf-runtime-contract.md",
+    "pluginManifest": "plugin.json",
+    "skills": "copilot-skills/",
+    "hooks": "hooks/copilot-hooks.json"
   },
   "opencode": {
     "skillPrefix": "agdf-",
@@ -87,6 +90,7 @@
     "surfaces": {
       "codex": "native-hook-review",
       "claude": "exact-command-rule",
+      "copilot": "plugin-hook-review",
       "opencode": "plugin-internal",
       "portable-skills": "manual-external-required"
     }
@@ -143,6 +147,21 @@
         "authorizationPath": "exact_text",
         "technicalPermissionOwner": "claude_host"
       },
+      "copilot": {
+        "questionAdapter": "exact_text",
+        "availability": "always",
+        "gateSafety": "wait_for_deliberate_user_input",
+        "explicitOutcomes": [
+          "approve",
+          "revise",
+          "decline",
+          "cancel"
+        ],
+        "approvalValueTransport": "exact_option_value",
+        "waitSafety": "deliberate_no_auto_resolution",
+        "authorizationPath": "exact_text",
+        "technicalPermissionOwner": "copilot_host"
+      },
       "opencode": {
         "questionAdapter": "question",
         "availability": "when_permission_question_allows",
@@ -292,6 +311,11 @@
         "installable": true,
         "machineValidation": "local_exact_version_digest"
       },
+      "copilot-runtime-plugin": {
+        "runtime": "required",
+        "installable": true,
+        "machineValidation": "local_exact_version_digest_inventory"
+      },
       "opencode-config-local": {
         "runtime": "config_local_package",
         "installable": true,

package/generated/submissions/openai/agdf/meta/copilot-payload-baseline.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "profile_id": "copilot-runtime-plugin",
+  "max_files": 78,
+  "max_bytes": 539607,
+  "rationale": "Reviewed Copilot-only manifest, ten prefixed skills, required contracts, exact-version runtime and evidence-plane separation. Any further increase requires review."
+}

package/generated/submissions/openai/agdf/submission/openai/availability.md

@@ -1,6 +1,6 @@
 # Availability Decision Record
 
-- release: `0.13.8`
+- release: `0.14.2`
 - decision_state: `pending`
 - decision_owner: verified publisher
 - countries: not selected

package/generated/submissions/openai/agdf/submission/openai/capability-matrix.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "releaseVersion": "0.13.8",
+  "releaseVersion": "0.14.2",
   "evidenceStates": [
     "common",
     "codex-specific",

package/generated/submissions/openai/agdf/submission/openai/inventory.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "releaseVersion": "0.13.8",
-  "digest": "3ada0c5f03ca8fa3d40b54c6682b617e651baea5db6926d07131fa29ea9fcb3a",
+  "releaseVersion": "0.14.2",
+  "digest": "0c78d217817ca7cec6cd2e8638e3a4fa678a7dc4c954119606f5f954bd1a2ca2",
   "files": [
     {
       "path": ".codex-plugin/plugin.json",
-      "sha256": "133bc0840f1be89ea0c3eb0909a26f758104ce0834da31e91a8fdf648102e296"
+      "sha256": "0eccc7ed08162a4f4437c7ccfbdd9145a9034b4ab6de44f5565ca608989d5c4a"
     },
     {
       "path": "assets/agdf-icon.svg",
@@ -29,7 +29,7 @@
     },
     {
       "path": "meta/agdf-plugin.definition.json",
-      "sha256": "d2b9b8f0134b9747be82f0fa1e9a99dd02a785aa8663514eb8bcc0648727fbf3"
+      "sha256": "ba636c3e224125df8f2dedde215b00473174b1a02fdeecbf91da1a262dcde778"
     },
     {
       "path": "meta/agdf-runtime-contract.md",
@@ -75,6 +75,10 @@
       "path": "meta/contracts/task-target-resolution.md",
       "sha256": "3d078596b02360c34e40a6529e063b9c89c62c490be374507fb2046543c380e8"
     },
+    {
+      "path": "meta/copilot-payload-baseline.json",
+      "sha256": "ab87e177288c36a056cccc583c78fd57b50fd82517a56276a009345e065ec1d6"
+    },
     {
       "path": "skills/brownfield-analysis/SKILL.md",
       "sha256": "4ca65f8efe0b50d6c7b625f6355ec2961fe91affa154b9d1e91dfe1334bcaf99"
@@ -157,23 +161,23 @@
     },
     {
       "path": "submission/openai/availability.md",
-      "sha256": "1f3dd7874e1e3243ebeee6688fe5fb61a56b11db4212d02791e882e5cc82ee51"
+      "sha256": "57e428da0faf2a48f459796781b4f5b472dc10e1cea957f6078404bf6e7a184b"
     },
     {
       "path": "submission/openai/capability-matrix.json",
-      "sha256": "f2e0e6e056f734b06942f5357d3aceb0750107d4989ced101a8aecb302e2f262"
+      "sha256": "203b63da20727ac116fe816893c669725d46ff67388a934fa17cda68ea97f09a"
     },
     {
       "path": "submission/openai/listing.json",
-      "sha256": "3fda29f5f5544d677f1cf26b7f566773f9e0c1ff0dfca689b0eeabf44d59ea9e"
+      "sha256": "29c2a8865f69e227d746548b487422135b7165c4c5aa4f92ed414b220dd21151"
     },
     {
       "path": "submission/openai/release-notes.md",
-      "sha256": "bfd777b576a5387866df286a80fdc8b42552da45742fbe4c73f9a928c0320ef9"
+      "sha256": "fcacfc5c8382ae589871359a3467dafac700822928999e680a106c484cc7044e"
     },
     {
       "path": "submission/openai/reviewer-cases.json",
-      "sha256": "df9946827c4102cd8eaedbfa4a6dd234098f85c82aa6d481c1634c7647362b2c"
+      "sha256": "e1ffc93e955edfab9a95cfaf0437badbf5f4741763cb0161f3de6b0e23c8bb27"
     }
   ]
 }

package/generated/submissions/openai/agdf/submission/openai/listing.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "releaseVersion": "0.13.8",
+  "releaseVersion": "0.14.2",
   "submissionType": "skills",
   "identity": {
     "technicalId": "agdf",

package/generated/submissions/openai/agdf/submission/openai/readiness.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "releaseVersion": "0.13.8",
+  "releaseVersion": "0.14.2",
   "candidateState": "repository_ready",
   "submissionReady": false,
   "submissionBlockers": [
@@ -16,7 +16,7 @@
     },
     "bundle": {
       "state": "pass",
-      "detail": "43 inventoried files; inventory digest 3ada0c5f03ca8fa3d40b54c6682b617e651baea5db6926d07131fa29ea9fcb3a"
+      "detail": "44 inventoried files; inventory digest 0c78d217817ca7cec6cd2e8638e3a4fa678a7dc4c954119606f5f954bd1a2ca2"
     },
     "installed_host": {
       "state": "unverified",

package/generated/submissions/openai/agdf/submission/openai/readiness.md

@@ -1,6 +1,6 @@
 # AGDF Public Plugin Readiness
 
-- release: `0.13.8`
+- release: `0.14.2`
 - candidate_state: `repository_ready`
 - submission_ready: `false`
 
@@ -9,7 +9,7 @@
 | Class | State | Detail |
 |---|---|---|
 | repository | pass | canonical contract and deterministic source checks |
-| bundle | pass | 43 inventoried files; inventory digest 3ada0c5f03ca8fa3d40b54c6682b617e651baea5db6926d07131fa29ea9fcb3a |
+| bundle | pass | 44 inventoried files; inventory digest 0c78d217817ca7cec6cd2e8638e3a4fa678a7dc4c954119606f5f954bd1a2ca2 |
 | installed_host | unverified | PPD-L02 and PPD-L03 not performed |
 | portal | unverified | unverified |
 | post_publication | unverified | not published |

package/generated/submissions/openai/agdf/submission/openai/release-notes.md

@@ -1,4 +1,4 @@
-# AGDF 0.13.8 — Initial OpenAI Public Plugin Candidate
+# AGDF 0.14.2 — Initial OpenAI Public Plugin Candidate
 
 This candidate packages the canonical AGDF workflow skills for public discovery in ChatGPT and
 Codex. It helps users assess delivery fit, preserve explicit human approvals, inspect existing-system

package/generated/submissions/openai/agdf/submission/openai/reviewer-cases.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "releaseVersion": "0.13.8",
+  "releaseVersion": "0.14.2",
   "cases": [
     {
       "id": "positive-proportional-fit",

package/lib/cli/application.js

@@ -17,6 +17,7 @@ import {
 } from "../installers/opencode.js";
 import {
   installClaudeGlobalPlugin,
+  installCopilotGlobalPlugin,
   installCodexGlobalPlugin,
 } from "../installers/plugin-installers.js";
 import {
@@ -30,7 +31,7 @@ import { printGeneralStatus, printLifecycleResult } from "../lifecycle/presentat
 import { createLifecycleResult, globalInstallRestartAction, lifecycleFailure } from "../lifecycle/result.js";
 import { prepareInstallConsent, persistInstallConsent, retainCurrentInstallConsent, runtimeCheckStatus, setRuntimeChecksManual } from "../runtime-check-consent/service.js";
 import { evaluateGeneralStatus } from "../lifecycle/status.js";
-import { agdfFragmentPath, generatedFilesForTarget } from "../scaffold/plan.js";
+import { generatedFilesForTarget } from "../scaffold/plan.js";
 import { printNextSteps } from "../scaffold/presentation.js";
 import { assertGeneratedWritePlan, writeGeneratedFile } from "../scaffold/write.js";
 import { renderUsage, resolveCommand, validateCommandOptions } from "./command-registry.js";
@@ -38,19 +39,19 @@ import { CliUsageError, parseArgs } from "./parse-args.js";
 import { pluginDefinition } from "./runtime-context.js";
 import { createValidationHandlers } from "./validation-handlers.js";
 
-function createHandlers({ io, env, exec, prepare, openCodePackageSource, askRuntimeCheckDecision, interactive }) {
+function createHandlers({ io, env, exec, packagedCopilotExec, prepare, openCodePackageSource, copilotSettingsPath, askRuntimeCheckDecision, interactive }) {
   const installerAdapters = {
     ...(exec ? { exec } : {}),
+    ...(packagedCopilotExec ? { packagedCopilotExec } : {}),
     ...(prepare ? { prepare } : {}),
+    ...(copilotSettingsPath ? { copilotSettingsPath } : {}),
     ...(env.AGDF_DATA_DIR ? { dataRoot: env.AGDF_DATA_DIR } : {}),
   };
   const scaffoldHandler = (options) => runScaffold(options, io);
   return new Map([
     ...createValidationHandlers(io),
     ["codex-repo", scaffoldHandler],
-    ["copilot", scaffoldHandler],
     ["opencode-repo", scaffoldHandler],
-    ["both", scaffoldHandler],
     ["init", scaffoldHandler],
     ["config", scaffoldHandler],
     ["run-create", (options) => {
@@ -141,6 +142,56 @@ function createHandlers({ io, env, exec, prepare, openCodePackageSource, askRunt
         return 1;
       }
     }],
+    ["copilot", async (options) => {
+      const surface = "copilot";
+      try {
+        const consent = await installConsentDecision(surface, options, { io, askRuntimeCheckDecision, interactive, dataRoot: installerAdapters.dataRoot });
+        if (consent.decision === "cancel") return printCancelledConsent(surface, options, io);
+        printInstallProgress(surface, options, io, interactive);
+        const installed = installCopilotGlobalPlugin({
+          ...installerAdapters,
+        });
+        const finalizedConsent = finalizeInstallConsent(consent, { surface, installed, dataRoot: installerAdapters.dataRoot });
+        if (installed.declarativeConfigured) {
+          printLifecycleResult(createLifecycleResult({
+            operation: "install", result: "partial", surface, scope: "global",
+            version: { expected: installed.expectedVersion, installed: null, status: "unknown" },
+            verification: { status: "configured_pending_restart", evidence: installed.evidence },
+            installation: { status: "configured_pending_restart" },
+            activation: { status: "pending_restart" },
+            runtime_checks: finalizedConsent.state,
+            restart: { required: true, reason: "host_reload" },
+            next_action: { kind: "restart", text: "Restart GitHub Copilot. Then verify AGDF in Plugins and the agdf- skills in a fresh session." },
+          }), { json: options.json, compact: !options.verbose, io });
+          return 0;
+        }
+        if (installed.manualHandoff) {
+          printLifecycleResult(createLifecycleResult({
+            operation: "install", result: "partial", surface, scope: "global",
+            version: { expected: installed.expectedVersion, installed: null, status: "unknown" },
+            verification: { status: "unavailable", evidence: installed.evidence },
+            installation: { status: "not_verified" },
+            activation: { status: "not_verified" },
+            runtime_checks: finalizedConsent.state,
+            restart: { required: false, reason: "none" },
+            next_action: { kind: "manual_install", text: `In GitHub Copilot, run /plugins install ${installed.pluginRoot}. Then run /restart and verify /plugins list and /skills list.` },
+            failure: { phase: "executable", message: "Copilot CLI was not available; no plugin installation was performed." },
+          }), { json: options.json, compact: !options.verbose, io });
+          return 1;
+        }
+        printLifecycleResult(installResult(installed, {
+          restartRequired: true,
+          nextAction: installNextAction(surface, finalizedConsent.state, globalInstallRestartAction(surface).text),
+          runtimeChecks: finalizedConsent.state,
+          consentFailure: finalizedConsent.failure,
+        }), { json: options.json, compact: !options.verbose, io });
+        printVerboseHostOutput(installed, options, io);
+        return installed.verificationStatus === "healthy" ? 0 : 1;
+      } catch (error) {
+        printInstallFailure(surface, error, options, io, "copilot");
+        return 1;
+      }
+    }],
     ["opencode", async (options) => {
       const configDir = options.dirExplicit ? options.dir : defaultOpenCodeConfigDir();
       try {
@@ -230,6 +281,9 @@ function installNextAction(surface, runtimeChecks, fallback) {
   if (surface === "codex" && runtimeChecks.requested === "enabled" && runtimeChecks.effective === "decision_required") {
     return "Restart Codex, then approve the AGDF session hook when Codex asks.";
   }
+  if (surface === "copilot" && runtimeChecks.requested === "enabled" && runtimeChecks.effective === "decision_required") {
+    return "Restart GitHub Copilot, then review the AGDF session hook when Copilot asks.";
+  }
   return fallback;
 }
 
@@ -313,6 +367,7 @@ function printInstallConsentDisclosure(disclosure, retained, io) {
 
 function installSurfaceLabel(surface) {
   if (surface === "claude") return "Claude Code";
+  if (surface === "copilot") return "GitHub Copilot";
   if (surface === "opencode") return "OpenCode";
   return "Codex";
 }
@@ -356,7 +411,7 @@ function printVerboseHostOutput(installed, options, io) {
   for (const output of installed.nativeOutput) io.log(output);
 }
 
-function printInstallFailure(surface, error, options, io) {
+function printInstallFailure(surface, error, options, io, command = surface) {
   const report = lifecycleFailure({
     operation: "install",
     surface,
@@ -364,7 +419,7 @@ function printInstallFailure(surface, error, options, io) {
     phase: error.phase || "plugin_operation",
     message: error.message,
     evidence: [error.evidence ?? {}],
-    nextAction: `Resolve the ${error.phase || "plugin operation"} failure and rerun npx --yes @agdf/cli@latest ${surface}.`,
+    nextAction: `Resolve the ${error.phase || "plugin operation"} failure and rerun npx --yes @agdf/cli@latest ${command}.`,
   });
   if (options.json) printLifecycleResult(report, { json: true, io });
   else {
@@ -445,7 +500,6 @@ function runUninstall(options, { io, env, exec }) {
 
 function runScaffold(options, io) {
   const files = generatedFilesForTarget(options.target, options.dir, options.force, options.language);
-  const wroteAgentsFragment = files.some((file) => file.path === agdfFragmentPath);
   let removedOpenCodeAgents = [];
 
   try {
@@ -460,7 +514,7 @@ function runScaffold(options, io) {
     return 1;
   }
 
-  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, removedOpenCodeAgents, { verbose: options.verbose, json: options.json, io });
+  printNextSteps(options.target, options.dir, files, removedOpenCodeAgents, { verbose: options.verbose, json: options.json, io });
   return 0;
 }
 
@@ -500,8 +554,10 @@ export async function runCli(argv = process.argv.slice(2), adapters = {}) {
     io,
     env,
     exec: adapters.exec,
+    packagedCopilotExec: adapters.packagedCopilotExec,
     prepare: adapters.prepare,
     openCodePackageSource: adapters.openCodePackageSource,
+    copilotSettingsPath: adapters.copilotSettingsPath,
     askRuntimeCheckDecision: adapters.askRuntimeCheckDecision ?? defaultAskRuntimeCheckDecision,
     interactive: adapters.interactive ?? (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)),
   }).get(command.handler);

package/lib/cli/command-registry.js

@@ -13,15 +13,14 @@ export const commandRegistry = Object.freeze([
   command("codex", { preferred: [""], scaffold: [""] }),
   command("codex-repo", { preferred: [""], scaffold: [""] }),
   command("claude", { preferred: [""], scaffold: [""] }),
-  command("copilot", { preferred: [""], scaffold: [""] }),
+  command("copilot", { preferred: [""] }),
   command("opencode", { preferred: [""], scaffold: [""] }),
   command("opencode-status", { preferred: [""], scaffold: [""] }),
   command("status", { preferred: [" [--surface <surface>] [--run <run_id>] [--json]"] }),
-  command("runtime-checks", { preferred: [" <status|enable|manual> --surface <codex|claude|opencode> [--json]"] }),
+  command("runtime-checks", { preferred: [" <status|enable|manual> --surface <codex|claude|copilot|opencode> [--json]"] }),
   command("disable", { preferred: [" --surface <surface> [--scope repository] [--dir <path>]"] }),
   command("uninstall", { preferred: [" --surface <surface> --scope global [--confirm]"] }),
   command("opencode-repo", { preferred: [""], scaffold: [""] }),
-  command("both", { scaffold: [""] }),
   command("init", { preferred: [""], scaffold: [""] }),
   command("config", { scaffold: [" --language de"] }),
   command("doctor", { local: [""], scaffold: [""], legacy: [" --json"] }),
@@ -66,11 +65,11 @@ export function validateCommandOptions(options) {
     throw new Error("uninstall requires explicit --scope global");
   }
   if (options.confirm && options.target !== "uninstall") throw new Error("--confirm is supported only by uninstall");
-  if (options.runtimeChecksDecision && !["codex", "claude", "opencode"].includes(options.target)) {
-    throw new Error("--runtime-checks is supported only by codex, claude and opencode installation commands");
+  if (options.runtimeChecksDecision && !["codex", "claude", "copilot", "opencode"].includes(options.target)) {
+    throw new Error("--runtime-checks is supported only by codex, claude, copilot and opencode installation commands");
   }
-  if (options.target === "runtime-checks" && !["codex", "claude", "opencode"].includes(options.surface)) {
-    throw new Error("runtime-checks requires --surface codex, claude or opencode");
+  if (options.target === "runtime-checks" && !["codex", "claude", "copilot", "opencode"].includes(options.surface)) {
+    throw new Error("runtime-checks requires --surface codex, claude, copilot or opencode");
   }
   if (options.approvalEnvelope && options.target !== "gate-check") throw new Error("--approval-envelope is supported only by gate-check");
   if (options.approvalEnvelope && (options.json || options.statusCard || options.allActive)) {

package/lib/installers/copilot-precedence.js

@@ -0,0 +1,34 @@
+function skillNames(values, field) {
+  if (!Array.isArray(values) || values.some((value) => typeof value !== "string" || !value.trim())) {
+    throw new Error(`AGDF_COPILOT_PRECEDENCE_INVALID: ${field}`);
+  }
+  const normalized = values.map((value) => value.trim());
+  if (new Set(normalized).size !== normalized.length) throw new Error(`AGDF_COPILOT_PRECEDENCE_DUPLICATE: ${field}`);
+  return new Set(normalized);
+}
+
+export function diagnoseCopilotSkillPrecedence({ declaredPluginSkills, projectSkills = [], personalSkills = [] } = {}) {
+  const plugin = skillNames(declaredPluginSkills, "declaredPluginSkills");
+  const project = skillNames(projectSkills, "projectSkills");
+  const personal = skillNames(personalSkills, "personalSkills");
+  const skills = [...plugin].sort().map((name) => {
+    const projectMatch = project.has(name);
+    const personalMatch = personal.has(name);
+    return Object.freeze({
+      name,
+      effective_source: projectMatch ? "project" : personalMatch ? "personal" : "plugin",
+      plugin_loaded: !projectMatch && !personalMatch,
+      collisions: Object.freeze([
+        ...(projectMatch ? ["project"] : []),
+        ...(personalMatch ? ["personal"] : []),
+      ]),
+      mutation: "none",
+    });
+  });
+  return Object.freeze({
+    schema_version: 1,
+    precedence: Object.freeze(["project", "personal", "plugin"]),
+    skills: Object.freeze(skills),
+    destructive_override: false,
+  });
+}

package/lib/installers/copilot-settings.js

@@ -0,0 +1,84 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import process from "node:process";
+import { renameSyncWithRetry } from "../fs-swap.js";
+
+export function defaultCopilotSettingsPath({ env = process.env, home = homedir() } = {}) {
+  return join(resolve(env.COPILOT_HOME || join(home, ".copilot")), "settings.json");
+}
+
+export function readCopilotSettings(path = defaultCopilotSettingsPath()) {
+  if (!existsSync(path)) return { exists: false, settings: {} };
+  const stats = lstatSync(path);
+  if (!stats.isFile() || stats.isSymbolicLink()) throw new Error("AGDF_COPILOT_SETTINGS_UNOWNED_PATH");
+  try {
+    const settings = JSON.parse(readFileSync(path, "utf8"));
+    if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error("not an object");
+    if (settings.enabledPlugins !== undefined
+        && (!settings.enabledPlugins || typeof settings.enabledPlugins !== "object" || Array.isArray(settings.enabledPlugins))) {
+      throw new Error("enabledPlugins must be an object");
+    }
+    return { exists: true, settings };
+  } catch (error) {
+    throw new Error(`AGDF_COPILOT_SETTINGS_INVALID: ${error.message}`);
+  }
+}
+
+function atomicSettingsWrite(path, settings) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.agdf-tmp-${process.pid}`;
+  const backup = `${path}.agdf-backup-${process.pid}`;
+  const hadPrevious = existsSync(path);
+  const mode = hadPrevious ? lstatSync(path).mode & 0o777 : 0o600;
+  writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode });
+  if (process.platform !== "win32") chmodSync(temp, mode);
+  try {
+    if (hadPrevious && process.platform === "win32") renameSyncWithRetry(path, backup);
+    renameSyncWithRetry(temp, path);
+    if (hadPrevious && process.platform === "win32") rmSync(backup, { force: true });
+  } catch (error) {
+    try { rmSync(temp, { force: true }); } catch {}
+    if (hadPrevious && process.platform === "win32" && existsSync(backup) && !existsSync(path)) renameSyncWithRetry(backup, path);
+    throw error;
+  }
+}
+
+export function configureCopilotDeclarativePlugin({ path = defaultCopilotSettingsPath(), pluginRoot }) {
+  if (typeof pluginRoot !== "string" || !pluginRoot.trim() || !isAbsolute(pluginRoot)) {
+    throw new Error("AGDF_COPILOT_PLUGIN_SPEC_INVALID");
+  }
+  const spec = resolve(pluginRoot);
+  if (!existsSync(spec) || !lstatSync(spec).isDirectory() || lstatSync(spec).isSymbolicLink()) {
+    throw new Error("AGDF_COPILOT_PLUGIN_SPEC_UNAVAILABLE");
+  }
+  const before = readCopilotSettings(path);
+  const next = structuredClone(before.settings);
+  next.enabledPlugins = { ...(next.enabledPlugins ?? {}), [spec]: true };
+  atomicSettingsWrite(path, next);
+  const verified = readCopilotSettings(path);
+  if (verified.settings.enabledPlugins?.[spec] !== true) throw new Error("AGDF_COPILOT_SETTINGS_VERIFICATION_FAILED");
+  return {
+    status: "configured_pending_restart",
+    reason: "host_activation_unverified",
+    path,
+    spec,
+    rollback() {
+      if (before.exists) atomicSettingsWrite(path, before.settings);
+      else rmSync(path, { force: true });
+    },
+  };
+}
+
+export function revokeCopilotDeclarativePlugin({ path = defaultCopilotSettingsPath(), pluginRoot }) {
+  const before = readCopilotSettings(path);
+  if (!before.exists) return { status: "not_configured", path };
+  const spec = resolve(pluginRoot);
+  const next = structuredClone(before.settings);
+  if (next.enabledPlugins && Object.hasOwn(next.enabledPlugins, spec)) {
+    delete next.enabledPlugins[spec];
+    if (Object.keys(next.enabledPlugins).length === 0) delete next.enabledPlugins;
+    atomicSettingsWrite(path, next);
+  }
+  return { status: "removed", path, spec };
+}