create-agdf 0.20.1 → 0.30.0

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-inspect/selection.js

@@ -1,9 +1,11 @@
 // Shared read-only selection policy for CLI and MCP; evaluation never writes control state.
 
-export const CONTROL_INSPECT_OPERATIONS = Object.freeze(["doctor", "gate-check", "delivery-map", "contract", "artifact-readiness", "operation-contract", "operation-status", "native-qualification", "presentation-document", "presentation-preview", "runtime-generations"]);
+export const ARTIFACT_READINESS_GATES = Object.freeze(['UR', 'PRD', 'SD', 'TP']);
+export const CONTROL_INSPECT_OPERATIONS = Object.freeze(["doctor", "gate-check", "delivery-map", "contract", "artifact-readiness", "authoring-inputs", "operation-contract", "operation-status", "native-qualification", "presentation-document", "presentation-preview", "runtime-generations", "project-state", "inventory", "planned-inventory", "planned-entry"]);
 export const ALL_ACTIVE_OPERATIONS = Object.freeze(["doctor", "delivery-map"]);
 export const VARIANT_OPERATION = "gate-check";
 export const MODULE_OPERATION = "contract";
+export const INVENTORY_OPERATION = "inventory";
 export const GATE_CHECK_VARIANTS = Object.freeze(["status-card", "approval-envelope"]);
 
 export class ReadSelectionError extends Error {
@@ -16,14 +18,18 @@ export class ReadSelectionError extends Error {
 
 // `operation` is the CLI command name or the MCP operation. Rules apply to every command so that a
 // write command carrying a read-only flag is rejected exactly as before the extraction.
-export function validateReadSelection({ operation, allActive = false, contractModule, variant } = {}) {
+export function validateReadSelection({ operation, allActive = false, contractModule, variant, runId, allowContractIndex = false } = {}) {
+  // The inventory always lists every run; a run selection would silently narrow it.
+  if (runId && [INVENTORY_OPERATION, 'planned-inventory', 'planned-entry'].includes(operation)) {
+    throw new ReadSelectionError("run_id", "--run is not supported by inventory; it lists every run");
+  }
   if (allActive && !ALL_ACTIVE_OPERATIONS.includes(operation)) {
     throw new ReadSelectionError("all_active", "--all-active is supported only by doctor and delivery-map");
   }
   if (contractModule !== undefined && ![MODULE_OPERATION, 'operation-contract', 'operation-status'].includes(operation)) {
     throw new ReadSelectionError("module", "--module is supported only by contract");
   }
-  if ([MODULE_OPERATION, 'operation-contract', 'operation-status'].includes(operation) && !contractModule) {
+  if ((operation === MODULE_OPERATION && !allowContractIndex || ['operation-contract', 'operation-status'].includes(operation)) && !contractModule) {
     throw new ReadSelectionError("module", "contract requires --module");
   }
   if (variant !== undefined && operation !== VARIANT_OPERATION) {

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-inspect/service.js

@@ -1,17 +1,21 @@
+import { baseResult, bindHostAction } from "./result.js";
+import { inspectArtefactRecordingMode } from '../control-state/run-artefact-recording.js';
+import { inspectProjectState } from './project-state.js';
 import process from "node:process";
 import { DISPATCH_RECOVERY } from "../interaction-catalog.js";
 import { buildStatusCard, evaluateGateCheck, postApprovalTransition, printApprovalEnvelope, printGateCheckReport } from "../control-evaluation/gate-check.js";
 import { evaluateDoctor } from "../control-evaluation/doctor.js";
 import { evaluateDeliveryMap } from "../control-evaluation/delivery-map.js";
-import { readRuntimeContract } from "../resources/contracts.js";
-import { renderSkillDispatchInputRecovery, renderSkillDispatchRecovery, renderTaskTargetOrientation, renderActiveRunInventory } from "../interaction-presentation.js";
+import { readRuntimeContract, runtimeContractModules } from "../resources/contracts.js";
+import { renderSkillDispatchInputRecovery, renderSkillDispatchRecovery, renderTaskTargetOrientation, renderActiveRunInventory, renderRunInventory } from "../interaction-presentation.js";
 import { resolveTaskTarget, TaskTargetInputError } from "../task-target-resolution.js";
 import { SKILL_DISPATCH_PRESENTATION_LANGUAGE_RECOVERY, SkillDispatchInputError, emptySkillDispatchTiming } from "../skill-dispatch/contract.js";
-import { CONTROL_INSPECT_CONTRACT_VERSION, CONTROL_INSPECT_SCHEMA_VERSION, ReadSelectionError, normalizeControlInspectInput, inspectContractHelp, PRESENTATION_CATALOG_MODULE } from "./contract.js";
-import { operationContract } from '../control-state/run-command-contract.js';
+import { CONTROL_INSPECT_CONTRACT_VERSION, CONTROL_INSPECT_SCHEMA_VERSION, ReadSelectionError, normalizeControlInspectInput, inspectContractHelp, OPERATION_CONTRACT_MODULES, PRESENTATION_CATALOG_MODULE } from "./contract.js";
+import { RUN_COMMAND_DESCRIPTORS, operationContract } from '../control-state/run-command-contract.js';
 import { inspectRunOperation } from '../control-state/run-operation-status.js';
 import { resolveControlCommandTarget } from '../control-state/approval-command-contract.js';
 import { readRunState } from '../control-evaluation/run-state.js';
+import { readRunInventory } from '../control-state/run-inventory-reader.js';
 import { inspectArtifactReadiness } from "./artifact-readiness.js";
 import { policyForRunContent } from '../control-evaluation/run-step-policy.js';
 import { parseRunState } from '../control-state/run-state-parser.js';
@@ -21,12 +25,19 @@ import { readPresentationDocument, readPresentationPreview, readPresentationCata
 import { sourceRevisionBoundary } from '../control-state/run-revision-boundary.js';
 import { sourceRevisionQualityFacts } from '../control-state/run-source-revisions.js';
 import { readHistoryBytes } from '../control-state/run-revision-history.js';
+import { creationRunId } from '../control-state/run-create-command.js';
+import { inspectAuthoringInputs } from './authoring-inputs.js';
+import { PLANNING_COMMAND_KINDS } from '../control-state/run-command-schema.js';
+import { inspectPlannedEntry, inspectPlannedOperation, plannedEntryPath } from '../control-state/planned-entry.js';
+import { controlPathPresent } from '../control-read/snapshot.js';
+import { inspectPlannedHandoffOperation } from '../control-state/planned-handoff.js';
+import { readPlannedInventory, readWorkInventory } from '../control-state/planned-inventory.js';
+import { readControlLayout, CURRENT_LAYOUT } from '../control-state/control-layout.js';
+import { existsSync } from '../control-read/fs.js';
+import { join } from 'node:path';
 
-// The MCP read tool is a projection over the existing evaluators. It calls exactly the functions the
-// CLI handlers call and returns their --json report. Draft preflight additionally composes those
-// existing content validators through its read-only Core owner; it adds no CLI command. It never writes,
-// never selects a run on its own and never prepares an approval binding. Evaluators run with the
-// dispatcher's dependency set: no git child process, so verified_change git observation is absent.
+// Read-only projection of canonical CLI evaluators and Core validators. It never
+// writes, selects a Run or prepares approval. Git observations are unavailable.
 
 const defaultNow = () => process.hrtime.bigint();
 const milliseconds = (start, end) => Number(end - start) / 1_000_000;
@@ -67,61 +78,6 @@ function runtimeEvidence(expectedVersion, evidence, env) {
   });
 }
 
-function baseResult({ outcome, operation, runtime, timing }) {
-  return {
-    schema_version: CONTROL_INSPECT_SCHEMA_VERSION,
-    contract_version: CONTROL_INSPECT_CONTRACT_VERSION,
-    outcome,
-    terminal: outcome !== "inspect_result",
-    authorizes: false,
-    operation: operation ?? null,
-    runtime,
-    target: null,
-    report: null,
-    presentation: null,
-    recovery: null,
-    host_action: null,
-    timing,
-    diagnostics: [],
-  };
-}
-
-function bindHostAction(result) {
-  if (result.outcome === "inspect_result") {
-    result.host_action = Object.freeze({
-      mode: "consume_report_and_continue",
-      source: result.presentation?.markdown ? "presentation.markdown" : "report",
-      ...(result.presentation?.markdown ? { text: result.presentation.markdown } : {}),
-      allow_surrounding_text: true,
-      may_request_run_or_evidence: false,
-    });
-  } else if (result.presentation?.markdown) {
-    result.host_action = Object.freeze({
-      mode: "transmit_presentation_verbatim_and_stop",
-      source: "presentation.markdown",
-      text: result.presentation.markdown,
-      allow_surrounding_text: false,
-      may_request_run_or_evidence: false,
-    });
-  } else {
-    result.host_action = Object.freeze({
-      mode: "transmit_recovery_verbatim_and_stop",
-      source: "recovery.action",
-      text: result.recovery?.action ?? "",
-      allow_surrounding_text: false,
-      may_request_run_or_evidence: false,
-    });
-  }
-  return Object.freeze(result);
-}
-
-export function createInspectFailureResult(code, runtime, action) {
-  const result = baseResult({ outcome: "evaluator_error", runtime, timing: emptySkillDispatchTiming() });
-  result.recovery = { action };
-  result.diagnostics = [{ code }];
-  return bindHostAction(result);
-}
-
 function gateCheckPresentation(report, variant, reEvaluate) {
   if (variant === "approval-envelope" || variant === "status-card") {
     const lines = [];
@@ -146,10 +102,11 @@ export function createControlInspectService(dependencies = {}) {
   const gateCheck = dependencies.evaluateGateCheck ?? evaluateGateCheck;
   const deliveryMap = dependencies.evaluateDeliveryMap ?? evaluateDeliveryMap;
   const readContract = dependencies.readRuntimeContract ?? readRuntimeContract;
+  const readModules = dependencies.runtimeContractModules ?? runtimeContractModules;
   const validateControlReadBoundary = dependencies.validateControlReadBoundary;
   const deliveryMapDependencies = Object.freeze({ evaluateDoctor: doctor, buildStatusCard, postApprovalTransition });
 
-  return function executeControlInspect(rawInput) {
+  return function executeControlInspect(rawInput, { signal } = {}) {
     const started = now();
     const timing = emptySkillDispatchTiming();
     const runtime = runtimeEvidence(rawInput.expectedVersion, dependencies.runtimeEvidence, env);
@@ -199,8 +156,35 @@ export function createControlInspectService(dependencies = {}) {
         timing.total_ms = round(milliseconds(started, now()));
         return bindHostAction(result);
       }
+      if (input.target_id && resolveControlCommandTarget(target.governance_target).target_id !== input.target_id) {
+        const result = baseResult({ outcome: 'invalid_input', operation: input.operation, runtime, timing });
+        result.target = target;
+        result.diagnostics = [{ code: 'target_binding_mismatch', field: 'target_id' }];
+        result.recovery = { action: renderInputRecovery({ field: 'target_id', allowedValues: [] },
+          { registry: rawInput.interactionLocales, requestedLocale: input.presentation_language }) };
+        timing.total_ms = round(milliseconds(started, now()));
+        return bindHostAction(result);
+      }
+      if (input.operation === 'doctor' && dependencies.observeDoctor) {
+        const controlStarted = now();
+        return Promise.resolve(dependencies.observeDoctor(target.governance_target, input, signal)).then(report => {
+          timing.control_ms = round(milliseconds(controlStarted, now()));
+          const result = baseResult({ outcome: 'inspect_result', operation: input.operation, runtime, timing });
+          result.target = target; result.report = report;
+          // Reuse the existing localized inventory only when this reply holds
+          // the complete inventory. Paged replies remain explicit scoped data;
+          // the agent follows every advertised cursor before summarizing them.
+          if (input.all_active && report.available && report.completeness === 'complete'
+            && report.inventory?.accounted_count === report.runs?.length + (report.invalid_entries?.length ?? 0)) {
+            const renderStarted = now();
+            result.presentation = renderActiveRunInventory(report, rawInput.interactionLocales, input.presentation_language);
+            timing.render_ms = round(milliseconds(renderStarted, now()));
+          }
+          timing.total_ms = round(milliseconds(started, now())); return bindHostAction(result);
+        });
+      }
       const controlStarted = now();
-      const { report, presentation, invalidModule } = stage(DISPATCH_RECOVERY.control_evaluation_failed, () => {
+      const { report, presentation, invalidModule, navigation } = stage(DISPATCH_RECOVERY.control_evaluation_failed, () => {
         validateControlReadBoundary?.(target.governance_target);
         const selection = {
           ...(input.run_id ? { runId: input.run_id } : {}),
@@ -208,11 +192,14 @@ export function createControlInspectService(dependencies = {}) {
         };
         switch (input.operation) {
           case 'presentation-document':
-          case 'presentation-preview':
-            return { report: (input.operation === 'presentation-preview' ? readPresentationPreview : readPresentationDocument)(target.governance_target, {
+          case 'presentation-preview': {
+            const report = (input.operation === 'presentation-preview' ? readPresentationPreview : readPresentationDocument)(target.governance_target, {
               runId: input.run_id, gate: input.gate, revisionId: input.expected_revision_id,
               presentationId: input.presentation_id, targetId: input.target_id, cursor: input.cursor,
-            }), presentation: null };
+            });
+            if (input.operation === 'presentation-document' && report.available) report.delivery_instruction = 'If full text is requested and an explicitly configured verified host renderer consumes these MCP pages, fetch all next_cursor pages with the exact original binding; let that renderer verify and output the bytes. Otherwise send this content verbatim in a user-visible agent message BEFORE fetching next_cursor, repeating in byte order. Tool output alone is not delivery. Retain already read pages. Never claim complete delivery from a successful read alone. Rendering is not human approval.';
+            return { report, presentation: null };
+          }
           case 'runtime-generations':
           case 'native-qualification': {
             const state = readRunState(target.governance_target, { runId: input.run_id });
@@ -228,11 +215,21 @@ export function createControlInspectService(dependencies = {}) {
                 next_operation: decision.next_operation, blocking_reason: decision.blocking_reason }, authorizes: false }, presentation: null };
           }
           case 'operation-contract': {
+            if (PLANNING_COMMAND_KINDS.includes(input.kind) && !input.run_id) {
+              const contract = operationContract(input.group, input.kind);
+              return { report: { ...contract, binding: { target_id: resolveControlCommandTarget(target.governance_target).target_id },
+                next_calls: [{ tool: input.group, kind: input.kind, instruction: contract.planning_capture?.instructions
+                  ?? 'Use the confirmed planning scope and original UUID; no Run/revision. Planning never approves a gate. Start a Run only from a deliberately selected complete source.' }] }, presentation: null };
+            }
+            if (['agdf_run', 'agdf_project'].includes(input.group) && !input.run_id) return { report: { ...operationContract(input.group, input.kind),
+              binding: { target_id: resolveControlCommandTarget(target.governance_target).target_id },
+              next_calls: [{ tool: input.group, kind: input.kind, instruction: input.group === 'agdf_project' ? 'Explicit fixed setup only. Use the confirmed existing Git root and one original UUID. No Run/revision, force, repair, install or approval.' : 'Use a new original operation UUID and confirmed title; there is no prior Run/revision.' }] }, presentation: null };
             const state = readRunState(target.governance_target, { runId: input.run_id });
             const targetId = resolveControlCommandTarget(target.governance_target).target_id;
             const valid = parseRunState(state.content, input.run_id).valid && state.meta?.revision_id === input.expected_revision_id
               && runSealState(target.governance_target, state.content).status === 'valid';
-            return { report: valid ? { ...operationContract(input.group, input.kind, { gate: input.gate }),
+            return { report: valid ? { ...operationContract(input.group, input.kind, { gate: input.gate ?? state.current_gate }),
+              ...(input.kind === 'artefact.record' ? { recording: inspectArtefactRecordingMode(state, input.gate ?? state.current_gate) } : {}),
               ...(input.contract_module === PRESENTATION_CATALOG_MODULE ? {
                 inspect_contract: inspectContractHelp(),
                 presentation_catalog: readPresentationCatalog(target.governance_target, { runId: input.run_id,
@@ -255,13 +252,46 @@ export function createControlInspectService(dependencies = {}) {
                   source_bindings: readArtefactBindings(state.content).active.map(row => ({ binding_id: row.binding_id, source: row.source, destination: row.destination, relationship: row.relationship })) }; })() }
               : { available: false, authorizes: false, reason: 'operation_binding_stale_or_invalid' }, presentation: null };
           }
+          case 'project-state':
+            return { report: inspectProjectState(target.governance_target, input, dependencies.gitObservation), presentation: null };
           case 'operation-status':
-            return { report: { ...inspectRunOperation(target.governance_target, { runId: input.run_id, operationId: input.operation_id, targetId: resolveControlCommandTarget(target.governance_target).target_id }), expected_revision_id: input.expected_revision_id }, presentation: null };
+            if (input.planning) return { report: input.contract_module.startsWith('run.create_from_planned/')
+              ? inspectPlannedHandoffOperation(target.governance_target, input.planning.plan_id, input.operation_id)
+              : inspectPlannedOperation(target.governance_target, input.planning.plan_id, input.operation_id), presentation: null };
+            if (input.contract_module.startsWith('project.initialize/')) return { report: inspectProjectState(target.governance_target, input, dependencies.gitObservation), presentation: null };
+            return { report: { ...inspectRunOperation(target.governance_target, { runId: input.run_id ?? creationRunId(input.operation_id), operationId: input.operation_id, targetId: resolveControlCommandTarget(target.governance_target).target_id }), expected_revision_id: input.expected_revision_id ?? null,
+              ...(!input.run_id ? { lookup_scope: 'run_creation', recovery_instruction: 'This target-only lookup is for Run creation. For a write to an existing Run, inspect operation-status with the original run_id, original expected_revision_id and the same original UUID in module. An unavailable creation lookup does not prove an approval effect. Never substitute a fresh UUID or infer success from a changed gate alone.' } : {}) }, presentation: null };
           case "artifact-readiness":
             return { report: inspectArtifactReadiness(target.governance_target, {
               runId: input.run_id, gate: input.gate, expectedRevisionId: input.expected_revision_id,
               presentationLanguage: input.presentation_language,
             }), presentation: null };
+          case 'authoring-inputs':
+            return { report: inspectAuthoringInputs(target.governance_target, input, { gitObservation: dependencies.gitObservation }), presentation: null };
+          case 'planned-inventory': {
+            const inventory = readPlannedInventory(target.governance_target, { language: input.presentation_language });
+            return { report: { ...inventory, available: inventory.state !== 'unavailable' }, presentation: null };
+          }
+          case 'planned-entry': {
+            const path = plannedEntryPath(input.planning.plan_id);
+            if (!controlPathPresent(target.governance_target, `${path}/UR.md`)) {
+              const inventory = readPlannedInventory(target.governance_target, { language: input.presentation_language });
+              const unavailable = inventory.state === 'unavailable', incomplete = existsSync(join(target.governance_target, path));
+              return { report: { available: false, state: unavailable ? 'unavailable' : 'missing',
+                reason: unavailable ? 'planning_store_unavailable' : incomplete ? 'planned_document_missing' : 'planned_entry_missing',
+                plan_id: input.planning.plan_id, authorizes: false,
+                ...(unavailable ? { findings: inventory.findings } : {}),
+                ...(!unavailable && !incomplete && input.planning.expected_digest === null ? { next_calls: [{ tool: 'agdf_inspect',
+                  arguments: { operation: 'authoring-inputs', working_directory: input.working_directory,
+                    target_source: input.target_source, primary_target: input.primary_target,
+                    presentation_language: input.presentation_language, planning: input.planning },
+                  instruction: 'Read the version-matched UR inputs before capture. Planning authoring needs no module, gate, Run or revision.' }] } : {}) }, presentation: null };
+            }
+            const entry = inspectPlannedEntry(target.governance_target, input.planning.plan_id, { presentationLanguage: input.presentation_language });
+            return { report: input.planning.expected_digest && input.planning.expected_digest !== entry.digest
+              ? { available: false, reason: 'planning_source_stale', plan_id: input.planning.plan_id, authorizes: false }
+              : { ...entry, available: true }, presentation: null };
+          }
           case "doctor": {
             const evaluated = doctor(target.governance_target, selection);
             return { report: evaluated, presentation: input.all_active
@@ -270,13 +300,50 @@ export function createControlInspectService(dependencies = {}) {
           case "gate-check": {
             const evaluate = () => gateCheck(target.governance_target, { ...selection, presentationLanguage: input.presentation_language });
             const evaluated = evaluate();
-            return { report: evaluated, presentation: gateCheckPresentation(evaluated, input.variant, evaluate) };
+            let navigation;
+            // Optional hints never replace the canonical report.
+            try {
+              if (input.run_id && input.target_source && input.primary_target && evaluated.status_card?.run_id === input.run_id) {
+                const revisionId = evaluated.status_card.runState?.meta?.revision_id;
+                const targetId = resolveControlCommandTarget(target.governance_target).target_id;
+                const common = Object.fromEntries(['presentation_language', 'working_directory', 'target_source', 'primary_target', 'run_id'].map(key => [key, input[key]]));
+                common.expected_revision_id = revisionId;
+                const catalog = readPresentationCatalog(target.governance_target, { runId: input.run_id, revisionId, targetId,
+                  gate: evaluated.current_gate, workingDirectory: input.working_directory, targetSource: input.target_source,
+                  primaryTarget: input.primary_target, language: input.presentation_language });
+                const kind = evaluated.next_operation?.operation_key;
+                const group = RUN_COMMAND_DESCRIPTORS[kind]?.group;
+                const nextCalls = [];
+                // Read the selected immutable document first. Operation help is
+                // optional and must not delay a user's read-only document task.
+                if (catalog.state === 'unique' && catalog.complete_scan && catalog.page_complete)
+                  nextCalls.push({ tool: 'agdf_inspect', arguments: catalog.candidates[0].read_arguments });
+                if (catalog.state !== 'unavailable' && group) nextCalls.push({ tool: 'agdf_inspect', arguments: {
+                  operation: 'operation-contract', ...common, module: `${group}/${kind}` } });
+                // An explicit reusable locator, not retained connection state or
+                // authority. Reuse passes through the ordinary target/Run checks.
+                const { expected_revision_id: _revision, ...readContext } = common;
+                navigation = { read_context: readContext, presentation_catalog: catalog, next_calls: nextCalls };
+              }
+            } catch { /* Advisory navigation unavailable. */ }
+            return { report: evaluated, navigation, presentation: gateCheckPresentation(evaluated, input.variant, evaluate) };
+          }
+          case "inventory": {
+            // Read-only inventory also works before control initialization. An
+            // existing config still goes through strict layout validation.
+            if (existsSync(join(target.governance_target, '.agdf/control/config.json'))
+              && readControlLayout(target.governance_target).layout === CURRENT_LAYOUT) return { report: readWorkInventory(target.governance_target, { language: input.presentation_language }), presentation: null };
+            const inventory = readRunInventory(target.governance_target, { language: input.presentation_language });
+            return { report: inventory, presentation: renderRunInventory(inventory, rawInput.interactionLocales, input.presentation_language) };
           }
           case "delivery-map": {
             const evaluated = deliveryMap(target.governance_target, selection, deliveryMapDependencies);
             return { report: evaluated, presentation: null };
           }
           case "contract": {
+            if (!input.contract_module) return { report: { available: true, modules: readModules(),
+              operation_modules: OPERATION_CONTRACT_MODULES, inspect_contract: inspectContractHelp(),
+              instruction: 'contract reads a listed runtime module. operation-contract reads an exact listed group/kind; omit planning, gate and Run/revision for creation help. Copy operation-specific arguments; never copy whole command bindings.', authorizes: false }, presentation: null };
             const read = readContract(input.contract_module, { pluginRoot: null });
             if (!read.ok) return { report: null, presentation: null, invalidModule: read };
             return { report: { module: read.module, content: read.content }, presentation: { markdown: read.content, authorizes: false } };
@@ -299,6 +366,7 @@ export function createControlInspectService(dependencies = {}) {
       result.target = target;
       result.report = report;
       result.presentation = presentation;
+      if (navigation) result.navigation = navigation;
       timing.total_ms = round(milliseconds(started, now()));
       return bindHostAction(result);
     } catch (error) {
@@ -317,3 +385,5 @@ export function createControlInspectService(dependencies = {}) {
     }
   };
 }
+
+export { createInspectFailureResult } from "./result.js";

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/compatibility.js

@@ -1,149 +1,59 @@
-import { lstatSync, readdirSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
-import { discoverRuns } from "../control-state/run-state-reader.js";
-import { directoryIdentity, regularFileSnapshot } from "../control-state/run-store-inspection.js";
-import { artefactFileDigest, listedArtefactPaths, pendingArtefactPaths, runSealState } from "../control-state/run-seal.js";
-import { inspectRunRecovery } from "../control-state/run-recovery.js";
-import { doctorRequiredFiles } from "../control-evaluation/required-files.js";
-import { inspectControlConfiguration } from "../control-state/control-configuration.js";
-import { hasSymlinkComponent } from "../control-state/contained-file.js";
-import { APPROVAL_GATES } from "../control-state/run-seal-compute.js";
-
-function entryExists(path) {
-  try { lstatSync(path); return true; } catch (error) {
-    if (error.code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-export function safeApprovalReset(approvals) {
-  return APPROVAL_GATES.every((gate) => approvals.some((approval) => approval.gate === gate))
-    && approvals.every((approval) => approval.status === "missing" && !approval.evidence);
-}
-
-function interruptedRecoveries(root, runId) {
-  const directory = join(root, ".agdf", "control", "runs", runId, "recovery-previews");
-  if (!entryExists(directory)) return [];
-  directoryIdentity(directory);
-  return readdirSync(directory).filter((name) => name.endsWith(".json")).map((name) => {
-    const journal = JSON.parse(regularFileSnapshot(join(directory, name)).content.toString("utf8"));
-    return journal.phase === "applying" ? { preview_id: journal.preview_id, confirmation: journal.confirmation,
-      prior_approvals: journal.prior_approvals, source_revision_id: journal.source_revision_id, next_gate: journal.next_gate,
-      journal: `.agdf/control/runs/${runId}/recovery-previews/${name}` } : null;
-  }).filter(Boolean);
-}
-
-export const CONTROL_MIGRATION_STATUSES = Object.freeze(["not_checked", "absent", "current", "migration_required", "repair_required"]);
-
+import { lstatSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { discoverRuns } from '../control-state/run-state-reader.js';
+import { directoryIdentity, regularFileSnapshot } from '../control-state/run-store-inspection.js';
+import { runSealState } from '../control-state/run-seal.js';
+import { requiredControlFiles } from '../control-evaluation/required-files.js';
+import { readControlLayout } from '../control-state/control-layout.js';
+import { inspectControlConfiguration } from '../control-state/control-configuration.js';
+
+const present = path => { try { lstatSync(path); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; } };
+export const CONTROL_COMPATIBILITY_STATUSES = Object.freeze(['not_checked', 'absent', 'current', 'unsupported', 'repair_required']);
 export function uncheckedControl() {
-  return { schema_version: 1, supported_control_state_version: 2, target: null,
-    status: "not_checked", runs: [], diagnostics: [], changes: [], authorizes: false };
+  return { schema_version: 1, supported_control_state_version: 4, supported_control_state_versions: [4], control_layout: null,
+    target: null, status: 'not_checked', runs: [], diagnostics: [], changes: [], authorizes: false };
 }
-
-// Repository compatibility is separate from delivery readiness and grants no gate authority.
-// Never search neighbouring repositories or infer a write target from a host configuration path.
-export function inspectControlMigration(root) {
+// Read-only compatibility, never migration or reset. Unsupported and corrupt
+// current state are distinct; neither classification creates write permission.
+export function inspectControlCompatibility(root) {
   if (!root) return uncheckedControl();
-  if (!isAbsolute(root)) throw new Error("AGDF_CONTROL_MIGRATION_TARGET_INVALID");
-  const result = { ...uncheckedControl(), target: root, status: "absent" };
-  const agdf = join(root, ".agdf");
+  if (!isAbsolute(root)) throw Error('AGDF_CONTROL_COMPATIBILITY_TARGET_INVALID');
+  const result = { ...uncheckedControl(), target: root, status: 'absent' };
   try {
-    if (!entryExists(agdf)) return result;
-    for (const path of [root, agdf, join(agdf, "control")]) {
-      try { directoryIdentity(path); } catch {
-        throw Object.assign(new Error("AGDF_CONTROL_PATH_INVALID"), { path });
-      }
-    }
-    const required = [join(".agdf", "control", "config.json"), join(".agdf", "control", "README.md"),
-      ...doctorRequiredFiles.filter((path) => !path.endsWith("AGDF_RUN.md"))];
-    for (const path of required) {
-      try { regularFileSnapshot(join(root, path)); } catch {
-        throw Object.assign(new Error("AGDF_CONTROL_SCAFFOLD_INCOMPLETE"), { path });
-      }
-    }
+    if (!present(join(root, '.agdf/control'))) return result;
+    for (const path of [root, join(root, '.agdf'), join(root, '.agdf/control')]) directoryIdentity(path);
+    result.control_layout = readControlLayout(root).layout;
+    for (const relative of ['.agdf/control/config.json', '.agdf/control/README.md', ...requiredControlFiles(root)])
+      regularFileSnapshot(join(root, relative));
     const configuration = inspectControlConfiguration(root);
-    if (!configuration.active) throw new Error(configuration.diagnostic);
-    const legacyPath = join(agdf, "control", "AGDF_RUN.md");
-    if (entryExists(legacyPath)) {
-      const legacy = regularFileSnapshot(legacyPath).content.toString("utf8");
-      if (!legacy.startsWith("<!-- AGDF LEGACY PROJECTION")) {
-        result.diagnostics.push({ code: "AGDF_LEGACY_MIGRATION_REQUIRED", path: ".agdf/control/AGDF_RUN.md" });
-      }
-    }
-    const runsPath = join(agdf, "control", "runs");
-    if (!entryExists(runsPath) && result.diagnostics.length) {
-      result.status = "migration_required";
-      return result;
-    }
-    directoryIdentity(runsPath);
+    if (!configuration.active) throw Error(configuration.diagnostic);
+    directoryIdentity(join(root, '.agdf/control/runs'));
     for (const run of discoverRuns(root)) {
+      const unsupported = run.findings.some(row => row.classification === 'unsupported_version');
       const entry = { run_id: run.run_id, control_state_version: run.meta?.control_state_version ?? null,
-        lifecycle: run.meta?.lifecycle ?? null, status: "current", seal_status: null,
-        safe_to_migrate: false, approvals: [], pending_recoveries: [], diagnostics: [] };
-      if (!run.valid) {
-        entry.status = "repair_required";
-        entry.diagnostics = run.findings;
-      } else {
+        status: unsupported ? 'unsupported' : !run.valid ? 'repair_required' : 'current', diagnostics: [...run.findings], pending_recoveries: [] };
+      if (run.valid) {
         const seal = runSealState(root, run.content);
-        entry.seal_status = seal.status;
-        const pending = new Set(pendingArtefactPaths(run.content));
-        const unresolved = listedArtefactPaths(run.content).filter((path) => {
-          const status = artefactFileDigest(root, path);
-          return status === "unresolved" || (status === "missing" && (!pending.has(path) || hasSymlinkComponent(root, path)));
-        });
-        if (run.meta.lifecycle !== "active" && seal.status === "unsealed") {
-          // Historical records remain non-authorizing evidence; installation does not reopen them
-          // or manufacture a retrospective integrity/approval attestation.
-          entry.status = "historical";
-        } else if (unresolved.length) {
-          entry.status = "repair_required";
-          entry.diagnostics = unresolved.map((path) => ({ code: "AGDF_RECOVERY_ARTEFACT_MISSING", path }));
-        } else if (seal.status === "unsealed" && run.meta.lifecycle === "active") {
-          const inspection = inspectRunRecovery(root, run.run_id, { inspectHistory: false });
-          entry.approvals = inspection.approvals;
-          entry.next_gate = inspection.next_gate_if_recovered;
-          entry.status = inspection.artefacts.every((file) => file.status === "valid" || file.planned) ? "migration_required" : "repair_required";
-          entry.safe_to_migrate = entry.status === "migration_required" && safeApprovalReset(inspection.approvals);
-          entry.diagnostics = inspection.artefacts.filter((file) => file.status !== "valid" && !file.planned)
-            .map((file) => ({ code: "AGDF_RECOVERY_ARTEFACT_PATH_INVALID", path: file.path }));
-        } else if (seal.status !== "valid") {
-          entry.status = "repair_required";
-          entry.diagnostics = [{ code: "AGDF_RUN_SEAL_INVALID", seal_status: seal.status }];
-        }
-        entry.pending_recoveries = interruptedRecoveries(root, run.run_id);
-        if (entry.pending_recoveries.length) {
-          entry.status = "repair_required";
-          entry.diagnostics.push({ code: "AGDF_RECOVERY_RESUME_REQUIRED" });
-        }
+        if (seal.status !== 'valid') { entry.status = 'repair_required'; entry.diagnostics.push({ code: 'AGDF_RUN_SEAL_INVALID', seal_status: seal.status }); }
+        else if (run.meta.lifecycle !== 'active') entry.status = 'historical';
       }
       result.runs.push(entry);
     }
-    result.status = result.runs.some((run) => run.status === "repair_required") ? "repair_required"
-      : result.diagnostics.length || result.runs.some((run) => run.status === "migration_required") ? "migration_required" : "current";
+    result.status = result.runs.some(run => run.status === 'unsupported') ? 'unsupported'
+      : result.runs.some(run => run.status === 'repair_required') ? 'repair_required' : 'current';
   } catch (error) {
-    result.status = "repair_required";
-    result.diagnostics.push({ code: String(error.code ?? error.message), ...(error.path ? { path: error.path } : {}) });
+    const code = String(error.code ?? error.message);
+    result.status = /LAYOUT_UNSUPPORTED|VERSION_UNSUPPORTED/u.test(code) ? 'unsupported' : 'repair_required';
+    result.diagnostics.push({ code, ...(error.path ? { path: error.path } : {}) });
   }
   return result;
 }
-
-export function assertControlMigration(value) {
-  if (!value || value.schema_version !== 1 || value.supported_control_state_version !== 2
-      || !CONTROL_MIGRATION_STATUSES.includes(value.status) || value.authorizes !== false
-      || !(value.target === null || (typeof value.target === "string" && isAbsolute(value.target)))
-      || (value.status === "not_checked" && value.target !== null)
-      || (value.status !== "not_checked" && value.target === null)
-      || !Array.isArray(value.runs) || !Array.isArray(value.diagnostics) || !Array.isArray(value.changes)) {
-    throw new Error("AGDF_CONTROL_MIGRATION_REPORT_INVALID");
-  }
-  if (value.repair && (value.repair.authorizes !== false || value.repair.target !== value.target
-      || !["needs_input", "deferred", "partial", "applied"].includes(value.repair.status)
-      || !Array.isArray(value.repair.diagnostics) || !Array.isArray(value.repair.items)
-      || value.repair.items.some((item) => typeof item.run_id !== "string" || typeof item.available !== "boolean"
-        || !["manual", "self_reference", "run_snapshot", "missing_artefacts"].includes(item.kind)
-        || !Array.isArray(item.sources) || !Array.isArray(item.required)))) {
-    throw new Error("AGDF_CONTROL_REPAIR_REPORT_INVALID");
-  }
+export function assertControlCompatibility(value) {
+  if (!value || value.schema_version !== 1 || value.supported_control_state_version !== 4
+    || JSON.stringify(value.supported_control_state_versions) !== '[4]' || !CONTROL_COMPATIBILITY_STATUSES.includes(value.status)
+    || value.authorizes !== false || !(value.target === null || typeof value.target === 'string' && isAbsolute(value.target))
+    || (value.status === 'not_checked') !== (value.target === null) || !Array.isArray(value.runs)
+    || !Array.isArray(value.diagnostics) || !Array.isArray(value.changes) || value.changes.length)
+    throw Error('AGDF_CONTROL_COMPATIBILITY_REPORT_INVALID');
   return value;
 }
-

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/contract.js

@@ -1,10 +1,10 @@
 import { isAbsolute } from "node:path";
-import { assertControlMigration } from "./compatibility.js";
+import { assertControlCompatibility } from "./compatibility.js";
 
 // Counts are presentation projections of the canonical inventory, never a stored policy.
 export function controlCounts(control) {
   return {
-    migration: control.runs.filter((run) => run.status === "migration_required" || run.pending_recoveries?.length === 1).length,
+    unsupported: control.runs.filter((run) => run.status === "unsupported").length,
     repair: control.runs.filter((run) => run.status === "repair_required" && run.pending_recoveries?.length !== 1).length,
     historical: control.runs.filter((run) => run.status === "historical").length,
   };
@@ -13,12 +13,12 @@ export function controlCounts(control) {
 export function assertMaintenanceResult(value, target = value?.target) {
   if (!value || value.schema_version !== 1 || value.authorizes !== false
       || typeof target !== "string" || !isAbsolute(target) || value.target !== target
-      || !["inspect", "guided"].includes(value.operation)
+      || value.operation !== "inspect"
       || !["complete", "unavailable", "not_checked"].includes(value.inspection_state)
-      || !["not_started", "deferred", "applied", "partial", "needs_input"].includes(value.maintenance_outcome)
+      || value.maintenance_outcome !== "not_started"
       || !Array.isArray(value.diagnostics)) throw new Error("AGDF_MAINTENANCE_RESULT_INVALID");
   if (value.inspection_state === "complete") {
-    assertControlMigration(value.compatibility);
+    assertControlCompatibility(value.compatibility);
     if (value.compatibility.target !== target
         || JSON.stringify(value.counts) !== JSON.stringify(controlCounts(value.compatibility))) {
       throw new Error("AGDF_MAINTENANCE_TARGET_MISMATCH");