create-agdf 0.20.2 → 0.30.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/skill-dispatch/delivery-run-assignment.js

@@ -1,16 +1,16 @@
-import { discoverRuns } from "../control-state/run-state-reader.js";
+import { discoverRuns, readSelectedRun } from "../control-state/run-state-reader.js";
 import { assertCanonicalRunStore } from "../control-state/run-store-inspection.js";
 import { artefactFileDigest, runSealState } from "../control-state/run-seal.js";
 import { containedRegularFile } from "../control-state/contained-file.js";
-import { duplicateArtefactRowTypes, parseControlState } from "../control-state/run-state-parser.js";
-import { closeoutArtefacts, internalStepArtefacts, readArtefactHeading, userGateOrder } from "../control-evaluation/run-state.js";
+import { duplicateArtefactRowTypes } from "../control-state/run-state-parser.js";
+import { prepareRunContentState, readArtefactHeading } from "../control-evaluation/run-state.js";
 import { buildRunCandidates } from "../interaction-presentation.js";
 
 // Scope matching belongs to the coding agent. This leaf supplies canonical evidence only;
 // neither candidate count, recency nor AGDF_RUN_ID binds a delivery request to a run.
-export function readDeliveryRunInventory(targetDir) {
+export function readDeliveryRunInventory(targetDir, { runId } = {}) {
   assertCanonicalRunStore(targetDir);
-  const runs = discoverRuns(targetDir);
+  const runs = runId ? [readSelectedRun(targetDir, runId)] : discoverRuns(targetDir);
   const findings = runs.filter((run) => !run.valid)
     .flatMap((run) => run.findings.map((finding) => ({ ...finding, run_id: run.run_id })));
   const candidates = [];
@@ -24,11 +24,7 @@ export function readDeliveryRunInventory(targetDir) {
       findings.push({ code: "AGDF_RUN_ASSIGNMENT_SEAL_INVALID", run_id: run.run_id, path: run.path, seal_status: seal.status });
       continue;
     }
-    const state = parseControlState(run.content, {
-      userGates: userGateOrder,
-      internalSteps: [...internalStepArtefacts],
-      closeoutArtefacts: [...closeoutArtefacts],
-    });
+    const state = prepareRunContentState(targetDir, run.content, run.path);
     const ur = state.artefacts.get("UR");
     const urPath = ur?.path || null;
     if ((!urPath && (state.current_gate !== "UR" || state.approvals.get("UR")?.status === "approved"))

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/skill-dispatch/mcp-continuation.js

@@ -0,0 +1,64 @@
+import { readRunState } from '../control-evaluation/run-state.js';
+import { inspectArtefactRecordingMode } from '../control-state/run-artefact-recording.js';
+import { resolveControlCommandTarget } from '../control-state/approval-command-contract.js';
+
+// Transport guidance over existing routes; code, tests and Git remain external.
+export function mcpControlContinuation(input, result, availableGroups = []) {
+  // A new Run over MCP is created by agdf_run/run.create; point at its contract instead of a retry.
+  if (result.terminal && result.diagnostics?.[0]?.code === 'AGDF_NEW_RUN_OPERATION_REQUIRED' && result.recovery
+      && availableGroups.includes('agdf_run') && result.target?.governance_target)
+    return { ...result, recovery: { ...result.recovery, next_calls: [{ tool: 'agdf_inspect', arguments: { operation: 'operation-contract',
+      module: 'agdf_run/run.create', presentation_language: input.presentationLanguage, working_directory: input.workingDirectory,
+      primary_target: result.target.governance_target, target_source: input.targetSource } }] } };
+  if (result.terminal || !result.continuation || !result.target?.governance_target) return result;
+  const continuation = result.continuation, root = result.target.governance_target;
+  const run = continuation.run_id ?? result.control?.run_id, revision = continuation.revision_id ?? result.control?.revision_id;
+  const targetId = resolveControlCommandTarget(root).target_id;
+  const common = { presentation_language: input.presentationLanguage, working_directory: input.workingDirectory,
+    primary_target: root, target_source: input.targetSource };
+  const bound = { ...common, run_id: run, expected_revision_id: revision };
+  const inspect = (operation, extra = {}, bind = true) => ({ tool: 'agdf_inspect', arguments: { operation, ...(bind ? bound : common), ...extra } });
+  const { steps, template_path, artifact_path, ...retained } = continuation;
+  let recording;
+  if (['prd_definition', 'sd_definition', 'tp_definition'].includes(continuation.phase))
+    recording = inspectArtefactRecordingMode(readRunState(root, { runId: run, ignoreRunIdEnv: true }), result.control.current_gate);
+  let nextCalls, requiredGroups = [], instruction = continuation.instruction ?? '';
+  if (continuation.phase === 'planned_ur_definition') {
+    requiredGroups = ['agdf_record'];
+    nextCalls = continuation.next_calls;
+    instruction += ' Use planned_material.stage and the planning scope; do not substitute Run material or a shell writer.';
+  } else if (continuation.phase === 'run_missing' || continuation.phase === 'resolve_delivery_run') {
+    requiredGroups = ['agdf_run'];
+    nextCalls = [inspect('operation-contract', { module: 'agdf_run/run.create' }, false)];
+    instruction = continuation.phase === 'resolve_delivery_run'
+      ? instruction.replace('choose an unused run_id and redispatch with intake: true and intake_mode: new', 'call agdf_run/run.create with a new original operation UUID and semantic title; resume its returned Run/revision')
+      : 'Create independent work via agdf_run/run.create with the requested semantic title and one original UUID. Resume returned Run/revision. No validator or user ID question.';
+  } else if (run && revision) {
+    const phase = continuation.phase;
+    const kind = phase === 'presentation_required' ? 'presentation.prepare'
+      : phase === 'compact_closeout' || phase === 'closeout' ? 'closeout.record'
+      : phase === 'ur_definition' && continuation.draft_registered ? 'ur_draft.replace'
+      : ['prd_definition', 'sd_definition', 'tp_definition', 'required_gate_artifact'].includes(phase) ? 'artefact.record'
+      : phase === 'verified_change_record' || phase === 'compact_implementation' && continuation.mode === 'verified_change' ? 'verified_change.record' : 'step.record';
+    const group = kind === 'presentation.prepare' ? 'agdf_prepare' : kind === 'closeout.record' ? 'agdf_closeout'
+      : kind === 'ur_draft.replace' ? 'agdf_revise' : 'agdf_record';
+    requiredGroups = kind === 'presentation.prepare' ? [group] : [group, 'agdf_record'];
+    nextCalls = [inspect('authoring-inputs'), inspect('operation-contract', { module: `${group}/${kind}` })];
+    instruction = phase === 'presentation_required'
+      ? 'Prepare this gate via agdf_prepare/presentation.prepare, then presentation.deliver: default markdown, optional non-primary decision-view. Forward selected text once. Wait for a NEW deliberate response; earlier replies cannot approve it.'
+      : `${instruction} Typed MCP: read every authoring-inputs page for current templates/sources. Stage UTF-8 via agdf_record/material.stage: begin, parts <=16 KiB, seal. Use returned references with ${group}/${kind}; operation-contract supplies fields. Attest mappings only after source review. All four modes: control uses MCP; editing/tests/Git stay external. Redispatch this Run/returned revision. Use the inspected current control operation when these groups are available.`;
+    if (continuation.mode === 'verified_change') instruction = instruction.replace(/through the existing record\/run-update owner/gu, 'through verified_change.record phase execution')
+      .replace(/Complete the linked Verified Change Mini-Closeout.*?Git-aware CLI evaluation\./u, 'Stage the linked Verified Change Mini-Closeout and use closeout.record with its exact confirmation; the Core checks actual Git observations.');
+  }
+  const missing = [...new Set(requiredGroups)].filter(group => !availableGroups.includes(group));
+  if (missing.length && continuation.phase === 'planned_ur_definition') return { ...result,
+    continuation: { ...continuation, control_transport: 'unavailable', missing_mcp_groups: missing,
+      instruction: 'Planning Core capability is unavailable in this host. Enable the compatible AGDF Core record group before any mutation. No shell-writing or Run-intake fallback.' } };
+  if (missing.length) return { ...result, presentation: continuation.phase === 'presentation_required' ? null : result.presentation,
+    continuation: { ...continuation, control_transport: 'cli_fallback', missing_mcp_groups: missing,
+      transport_reason: 'required_mcp_group_unavailable' } };
+  return { ...result, presentation: continuation.phase === 'presentation_required' ? null : result.presentation,
+    continuation: { ...retained, instruction, control_transport: 'typed_mcp', external_execution: ['source edits', 'actual tests', 'Git operations'],
+      ...(recording ? { recording, instruction: instruction + ' ' + recording.instruction } : {}),
+      ...(nextCalls ? { next_calls: nextCalls } : {}) } };
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/skill-dispatch/prd-definition.js

@@ -1,12 +1,13 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { extractField } from "../control-evaluation/verified-change.js";
 import { ARTEFACT_TEMPLATE_IDS, resolveArtefactTemplatePath } from "../resources/artefact-templates.js";
 import { resolveArtifactPresentationLanguages } from "../resources/context.js";
 
 // Pure routing over already evaluated control and contained source facts; never a writer or gate.
-export function prdDefinitionPhase(targetDir, control, input, sources) {
+export function prdDefinitionEligible(control, input) {
   const state = control?.status_card?.runState;
   if (control?.next_operation?.type === "reassess_source_analysis") return null;
-  if (input.ur_action !== undefined || input.sd_action !== undefined || input.tp_action !== undefined || !input.run_id || control?.status_card?.run_id !== input.run_id || !state || !sources
+  if (input.ur_action !== undefined || input.sd_action !== undefined || input.tp_action !== undefined || !input.run_id || control?.status_card?.run_id !== input.run_id || !state
       || control.current_gate !== "PRD" || !["open", "blocked"].includes(control.status)
       || !["none", "Approval: PRD"].includes(control.missing_approval)
       || !["none", "AGDF_PRD_DECISIONS_OPEN"].includes(control.blocking_reason)
@@ -17,15 +18,23 @@ export function prdDefinitionPhase(targetDir, control, input, sources) {
       || !["done", "not_applicable"].includes(state.artefacts.get("Brownfield Review")?.status)
       || !["structured_delivery", "structured_slice"].includes(state.mode_slice_decision?.decision)) return null;
   if (input.skill_id !== "prd-definition" && !(input.intake || input.continue_delivery)) return null;
-  const revisionId = extractField(state.content ?? "", "revision_id");
-  if (!revisionId) return null;
-  const artifactPath = `.agdf/control/artefacts/${input.run_id}/PRD.md`;
+  const artifactPath = `${runDocumentPath(input.run_id, '')}/PRD.md`;
   const artefact = state.artefacts.get("PRD");
   const registered = artefact?.status === "draft";
   if (artefact?.status === "approved" || (registered
       && String(artefact.path ?? "").replace(/^`|`$/gu, "") !== artifactPath)) return null;
   if (registered && input.skill_id !== "prd-definition" && input.prd_action !== "revise"
       && control.prd_readiness?.ready !== false) return null;
+  return true;
+}
+
+export function prdDefinitionPhase(targetDir, control, input, sources) {
+  if (!sources || !prdDefinitionEligible(control, input)) return null;
+  const state = control.status_card.runState;
+  const revisionId = extractField(state.content ?? "", "revision_id");
+  if (!revisionId) return null;
+  const artifactPath = `${runDocumentPath(input.run_id, '')}/PRD.md`;
+  const registered = state.artefacts.get("PRD")?.status === "draft";
   return Object.freeze({
     phase: "prd_definition", skill_id: "prd-definition", governance_target: targetDir,
     run_id: input.run_id, revision_id: revisionId,

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/skill-dispatch/sd-definition.js

@@ -1,3 +1,4 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { extractField } from "../control-evaluation/verified-change.js";
 import { ARTEFACT_TEMPLATE_IDS, resolveArtefactTemplatePath } from "../resources/artefact-templates.js";
 import { resolveArtifactPresentationLanguages } from "../resources/context.js";
@@ -20,7 +21,7 @@ export function sdDefinitionPhase(targetDir, control, input, sources) {
   if (input.skill_id !== "sd-definition" && !(input.intake || input.continue_delivery)) return null;
   const revisionId = extractField(state.content ?? "", "revision_id");
   if (!revisionId) return null;
-  const artifactPath = `.agdf/control/artefacts/${input.run_id}/SD.md`;
+  const artifactPath = `${runDocumentPath(input.run_id, '')}/SD.md`;
   const artefact = state.artefacts.get("SD");
   const registered = artefact?.status === "draft";
   if (artefact?.status === "approved" || (registered

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/skill-dispatch/service.js

@@ -1,7 +1,9 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { inspectDefinitionSources } from "../control-evaluation/definition-sources.js";
 import { prdDefinitionPhase } from "./prd-definition.js";
 import { sdDefinitionPhase } from "./sd-definition.js";
 import { tpDefinitionPhase } from "./tp-definition.js";
+import { inspectAuthoringInputs } from '../control-inspect/authoring-inputs.js';
 import { compactContinuation } from "./compact-continuation.js";
 import process from "node:process";
 import { extractField } from "../control-evaluation/verified-change.js";
@@ -47,21 +49,28 @@ function judgementTemplateId(skillId, currentGate) {
 }
 
 class SkillDispatchRuntimeError extends Error {
-  constructor(code, details = "") {
+  constructor(code, details = "", cause = null) {
     super(code);
     this.name = "SkillDispatchRuntimeError";
     this.code = code;
     this.details = details;
+    this.cause_code = cause;
   }
 }
 
+// Only a bare AGDF finding code is safe to surface; free-form messages may carry paths or content.
+const AGDF_CAUSE_PATTERN = /^AGDF_[A-Z0-9_]+$/u;
+const agdfCause = (error) => [error?.code, error?.message].find((value) => typeof value === "string" && AGDF_CAUSE_PATTERN.test(value)) ?? null;
+const blockingFindingCodes = (control) => [...new Set((control?.doctor_report?.findings ?? [])
+  .filter((finding) => finding.severity === "block").map((finding) => finding.code).filter(Boolean))];
+
 const presentationRecovery = (control) => String(control?.presentation_diagnostics?.approval_presentation_recovery ?? "").trim();
 
 function runDispatchStage(code, callback) {
   try {
     return callback();
-  } catch {
-    throw new SkillDispatchRuntimeError(code);
+  } catch (error) {
+    throw new SkillDispatchRuntimeError(code, "", agdfCause(error));
   }
 }
 
@@ -207,14 +216,14 @@ function controlSnapshot(report, { includeCandidateRuns = false } = {}) {
   });
 }
 
-export function createSkillDispatchFailure({ skill, runtime, timing, code, details, interactionLocales,
+export function createSkillDispatchFailure({ skill, runtime, timing, code, details, cause, interactionLocales,
   presentationLanguage, renderRecovery = renderSkillDispatchRecovery }) {
   const result = baseResult({ outcome: "evaluator_error", terminal: true, skill, runtime, timing });
   let action;
   try { action = renderRecovery({ code }, { registry: interactionLocales, requestedLocale: presentationLanguage }); }
   catch { action = null; }
   result.recovery = { action: [action ?? "Repair the installed locale registry and retry once.", details].filter(Boolean).join("\n\n") };
-  result.diagnostics = [{ code: artefactTemplateErrors.has(code) ? code : `dispatch_${code}` }];
+  result.diagnostics = [{ code: artefactTemplateErrors.has(code) ? code : `dispatch_${code}`, ...(cause ? { cause } : {}) }];
   return bindHostAction(result);
 }
 
@@ -287,6 +296,26 @@ export function createSkillDispatchService(dependencies = {}) {
       }
 
       const controlStarted = now();
+      if (input.planning) {
+        validateControlReadBoundary?.(target.governance_target);
+        const source = inspectAuthoringInputs(target.governance_target, input);
+        if (!source.available) throw Error(source.reason);
+        const result = baseResult({ outcome: 'skill_continuation', terminal: false, skill, runtime, timing });
+        result.target = target;
+        result.control = { scope: 'planning', planning: input.planning, current_gate: null, authorizes: false };
+        result.continuation = { phase: 'planned_ur_definition', skill_id: 'ur-definition', governance_target: target.governance_target,
+          planning: input.planning, ...resolveArtifactPresentationLanguages(target.governance_target, input.presentation_language),
+          ...(dependencies.readSkillRuntimeContracts ? { runtime_contracts: dependencies.readSkillRuntimeContracts('ur-definition') } : {}),
+          instruction: 'Use the shared ur-definition semantics in planning mode only. Read all current authoring-inputs pages and the exact planned writer contract. Capture or refine one unapproved UR and minimal metadata; incomplete drafts are permitted. Stage only planning-scoped UR material. No Run, PRD, SD, TP, gate presentation or approval is created. Return the saved source and remaining clarification. Start delivery only on a later explicit source-bound handoff request.',
+          next_calls: [{ tool: 'agdf_inspect', arguments: { operation: 'authoring-inputs', working_directory: input.working_directory,
+            primary_target: target.governance_target, target_source: input.target_source, presentation_language: input.presentation_language, planning: input.planning } },
+          { tool: 'agdf_inspect', arguments: { operation: 'operation-contract', module: `agdf_record/${source.recording.kind}`,
+            working_directory: input.working_directory, primary_target: target.governance_target, target_source: input.target_source, presentation_language: input.presentation_language } }],
+        };
+        timing.control_ms = round(milliseconds(controlStarted, now())); timing.total_ms = round(milliseconds(started, now()));
+        timing.wrapper_ms = round(wrapperMilliseconds(now, env));
+        return bindHostAction(result);
+      }
       const assignmentResult = (candidates, reason) => {
         const result = baseResult({ outcome: "intake_continuation", terminal: false, skill, runtime, timing });
         result.target = target;
@@ -300,7 +329,7 @@ export function createSkillDispatchService(dependencies = {}) {
         let candidates;
         try {
           validateControlReadBoundary?.(target.governance_target);
-          candidates = readRunInventory(target.governance_target);
+          candidates = readRunInventory(target.governance_target, input.run_id ? { runId: input.run_id } : {});
         } catch (error) {
           const code = error.code === "AGDF_CANONICAL_SCAFFOLD_REQUIRED" ? "intake_scaffold_required"
             : error.code === "AGDF_RUN_ASSIGNMENT_INVENTORY_INVALID" ? "run_assignment_inventory_invalid" : null;
@@ -341,15 +370,20 @@ export function createSkillDispatchService(dependencies = {}) {
         : null;
       } catch (error) {
         const code = error.message === "AGDF_RUN_COLLISION" ? "AGDF_RUN_COLLISION"
-          : error.code === "AGDF_CANONICAL_SCAFFOLD_REQUIRED" ? "AGDF_CANONICAL_SCAFFOLD_REQUIRED" : null;
-        // Only the two known intake refusals are reported as such; anything else keeps its real class.
-        if (!code) throw new SkillDispatchRuntimeError(DISPATCH_RECOVERY.control_evaluation_failed);
+          : error.code === "AGDF_CANONICAL_SCAFFOLD_REQUIRED" ? "AGDF_CANONICAL_SCAFFOLD_REQUIRED"
+            : error.message === "AGDF_NEW_RUN_OPERATION_REQUIRED" ? "AGDF_NEW_RUN_OPERATION_REQUIRED" : null;
+        // Only the known intake refusals are reported as such; anything else keeps its real class.
+        if (!code) throw new SkillDispatchRuntimeError(DISPATCH_RECOVERY.control_evaluation_failed, "", agdfCause(error));
         const result = baseResult({ outcome: "control_result", terminal: true, skill, runtime, timing });
         result.target = target;
         result.control = controlSnapshot(control);
-        result.diagnostics = [{ code }];
+        // The expected run-selection blockers explain why doctor reports the target as blocked.
+        const blockers = blockingFindingCodes(control);
+        result.diagnostics = [{ code, ...(blockers.length ? { blockers } : {}),
+          ...(code === "AGDF_NEW_RUN_OPERATION_REQUIRED" ? { run_id: input.run_id, expected_run_id: "run-<uuid>" } : {}) }];
         result.recovery = { action: renderRecovery({ code: code === "AGDF_RUN_COLLISION" ? DISPATCH_RECOVERY.intake_run_collision
-          : DISPATCH_RECOVERY.intake_scaffold_required }, { registry: rawInput.interactionLocales, requestedLocale: input.presentation_language }) };
+          : code === "AGDF_NEW_RUN_OPERATION_REQUIRED" ? DISPATCH_RECOVERY.intake_run_id_invalid
+            : DISPATCH_RECOVERY.intake_scaffold_required }, { registry: rawInput.interactionLocales, requestedLocale: input.presentation_language }) };
         return bindHostAction(result);
       }
       const urPhase = input.prd_action || input.sd_action || input.tp_action ? null : urDefinitionPhase(target.governance_target, control, input);
@@ -638,7 +672,7 @@ export function createSkillDispatchService(dependencies = {}) {
           run_id: result.control.run_id,
           revision_id: result.control.revision_id,
           presentation_language: input.presentation_language,
-          artifact_path: `.agdf/control/artefacts/${result.control.run_id}/VERIFIED_CHANGE.md`,
+          artifact_path: `${runDocumentPath(result.control.run_id, '')}/VERIFIED_CHANGE.md`,
           template_path: resolveArtefactTemplatePath(ARTEFACT_TEMPLATE_IDS.VERIFIED_CHANGE),
           instruction: "Create or repair the compact Verified Change record only through its existing gate-check/evaluator owner. Use the supplied plugin-owned template and canonical run-local artifact path, capture the required baseline, and prove every eligibility condition before implementation. Redispatch gate-check for the same run; never add another skill or route.",
           ...(dependencies.readSkillRuntimeContracts ? {
@@ -686,7 +720,7 @@ export function createSkillDispatchService(dependencies = {}) {
           result.continuation = Object.freeze({ phase: 'required_gate_artifact', skill_id: owner,
             governance_target: target.governance_target, run_id: result.control.run_id, revision_id: result.control.revision_id,
             presentation_language: input.presentation_language,
-            ...(!orientationOnly && unapprovedQa ? { artifact_path: `.agdf/control/artefacts/${result.control.run_id}/QA_REPORT.md`,
+            ...(!orientationOnly && unapprovedQa ? { artifact_path: `${runDocumentPath(result.control.run_id, '')}/QA_REPORT.md`,
               template_path: resolveArtefactTemplatePath(ARTEFACT_TEMPLATE_IDS.QA_REPORT) } : {}),
             instruction: `${control.presentation_diagnostics.approval_presentation_recovery}\nComplete only this bound Run's permitted unapproved content through its existing writer; preserve approved intent and all protected sources. Record the current revision and redispatch the same Run once. An unchanged failure stops; no earlier reply is approval.`,
             ...(dependencies.readSkillRuntimeContracts ? { runtime_contracts: runDispatchStage(DISPATCH_RECOVERY.runtime_contracts_unavailable, () => dependencies.readSkillRuntimeContracts(owner)) } : {}),
@@ -750,7 +784,7 @@ export function createSkillDispatchService(dependencies = {}) {
       const nextSkillId = control.status_card?.next_skill;
       const routeNextSkill = input.continue_delivery && !control.approval_presentation?.markdown
         && !control.completion?.fulfilled
-        && extractField(control.status_card?.runState?.content ?? "", "lifecycle") !== "completed"
+        && !["completed", "superseded", "abandoned"].includes(extractField(control.status_card?.runState?.content ?? "", "lifecycle"))
         && nextSkillId && nextSkillId !== "none"
         && (control.current_gate !== "QA" || control.missing_approval === "Approval: QA");
       if (routeNextSkill) skill = buildSkillDispatchRegistry(dependencies.pluginDefinition?.skillSet ?? rawInput.skillSet).get(nextSkillId) ?? skill;
@@ -827,6 +861,7 @@ export function createSkillDispatchService(dependencies = {}) {
       timing.total_ms = round(milliseconds(started, now()));
       timing.wrapper_ms = round(wrapperMilliseconds(now, env));
       return createSkillDispatchFailure({ skill, runtime, timing, code: recoveryCode, details: error?.details,
+        cause: error instanceof SkillDispatchRuntimeError ? error.cause_code : agdfCause(error),
         interactionLocales: rawInput.interactionLocales, presentationLanguage: input.presentation_language, renderRecovery });
     }
   };

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/skill-dispatch/tp-definition.js

@@ -1,3 +1,4 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { extractField } from "../control-evaluation/verified-change.js";
 import { ARTEFACT_TEMPLATE_IDS, resolveArtefactTemplatePath } from "../resources/artefact-templates.js";
 import { resolveArtifactPresentationLanguages } from "../resources/context.js";
@@ -22,7 +23,7 @@ export function tpDefinitionPhase(targetDir, control, input, sources) {
   if (input.skill_id !== "tp-definition" && !(input.intake || input.continue_delivery)) return null;
   const revisionId = extractField(state.content ?? "", "revision_id");
   if (!revisionId) return null;
-  const artifactPath = `.agdf/control/artefacts/${input.run_id}/TP.md`;
+  const artifactPath = `${runDocumentPath(input.run_id, '')}/TP.md`;
   const artefact = state.artefacts.get("TP");
   const registered = artefact?.status === "draft";
   if (artefact?.status === "approved" || (registered

package/generated/plugins/agdf/runtime/runtime-manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1",
   "generated": true,
   "source": "create-agdf/cli",
-  "version": "0.20.2",
+  "version": "0.30.0",
   "entrypoint": "create-agdf/bin/agdf-validator.js",
-  "digest": "c5e31f9ebf057b4fd18244e276f2262fe0fa6bc40d120ace72d69bdf421a41d1"
+  "digest": "9aaeff075f433f26d5b474e9b60887a189074c18fef5e62840920b30e4433073"
 }

package/generated/plugins/agdf/scripts/check-runtime-integrity.mjs

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, join, relative, resolve } from "node:path";
@@ -149,7 +150,6 @@ const syncPackageAssetsPath = sourceMode ? join(repoRoot, "scripts", "sync-packa
 const syncPluginRuntimePath = sourceMode ? join(repoRoot, "scripts", "sync-plugin-runtime.js") : null;
 const createAgdfOpenCodeInstallerPath = sourceMode ? join(repoRoot, "packages", "cli", "lib", "installers", "opencode.js") : null;
 const openCodeNpmPluginPath = sourceMode ? join(repoRoot, "packages", "cli", "opencode-plugin.js") : null;
-const activeRunStatePath = sourceMode ? join(repoRoot, ".agdf", "control", "AGDF_RUN.md") : null;
 const rootLicensePath = sourceMode ? join(repoRoot, "LICENSE") : null;
 const pluginLicensePath = join(pluginRoot, "LICENSE");
 const controlRoot = join(pluginRoot, "control");
@@ -160,8 +160,6 @@ let expectedSkills = [];
 const expectedControlFiles = [
   "README.md",
   "templates/RUN_STATE.md",
-  "templates/AGDF_RUN.md",
-  "templates/MASTER_BACKLOG.md",
   "templates/SOT_REGISTRY.md",
   "templates/CONTEXT_GRAPH.md",
   "templates/AGENT_QUALITY_CONTRACTS.json",
@@ -717,6 +715,7 @@ for (const requiredRuntimeFile of sourceMode ? [] : [
   "runtime/create-agdf/lib/runtime/validator-application.js",
   "runtime/create-agdf/lib/runtime/plugin-provenance.js",
   "runtime/create-agdf/lib/cli/validation-handlers.js",
+  "runtime/create-agdf/lib/cli/planned-command.js",
 ]) assertFile(join(pluginRoot, requiredRuntimeFile), `focused surface-local runtime module ${requiredRuntimeFile}`);
 if (!sourceMode && isFile(localRuntimeEntrypointPath)) {
   const probe = spawnSync(process.execPath, [localRuntimeEntrypointPath, "--resolve-only", "--json"], { encoding: "utf8" });
@@ -1086,17 +1085,17 @@ for (const [surface, expectedTransport] of [["codex", "exact_option_value"], ["c
 }
 for (const required of [
   "Before presenting `gate_approval` for any user gate",
-  "one immediately preceding assistant message",
-  "one immutable,\nnon-authorizing presentation snapshot",
+  "one immutable Markdown decision document",
+  "Older versions retain their original envelope/snapshot/approval proof",
   "### Human Decision Presentation Contract",
   "Never guess a path or emit a broken link",
   "A localized label, description, option position, recommendation style or host action never authorizes a gate",
-  "renders the complete operational Run Status Card exactly once, between the compact approval-time Run Status Card and the Gate Transition Card",
-  "may carry the missing approval as audit data",
+  "presentation.deliver selects ui_primary only",
+  "operational Run Status Card and Gate Transition Card remain deterministic read/audit projections",
 ]) {
   if (!runtimeContract.includes(required)) failures.push(`interaction contract ownership boundary missing: ${required}`);
 }
-const gateTransitionCard = sectionAfterHeading(runtimeContract, "Gate Transition Card");
+const primaryDecisionDocument = sectionAfterHeading(runtimeContract, "Prepared decision presentation");
 for (const pattern of [
   "| Status |",
   "- allowed_now:",
@@ -1105,7 +1104,7 @@ for (const pattern of [
   "Question:",
   "Next user gate: Brownfield Analysis",
 ]) {
-  if (gateTransitionCard.includes(pattern)) failures.push(`Gate Transition Card must not render approval-time pattern: ${pattern}`);
+  if (primaryDecisionDocument.includes(pattern)) failures.push(`Primary decision document must not render approval-time pattern: ${pattern}`);
 }
 
 if (pluginDefinition) {
@@ -1485,6 +1484,7 @@ if (sourceMode && isFile(openCodeNpmPluginPath)) {
     failures.push("OpenCode npm plugin must reserve its only session-created toast for version drift");
   }
 
+  let activeProbeRoot;
   try {
     const expectedIdentity = {
       owner: "request_activation_contract",
@@ -1529,8 +1529,16 @@ if (sourceMode && isFile(openCodeNpmPluginPath)) {
       failures.push("inactive OpenCode compaction must emit zero bytes");
     }
 
+    // A source checkout need not contain live control. Keep the probe independent
+    // of its governing Runs and exercise activation against disposable current control.
+    activeProbeRoot = realpathSync(mkdtempSync(join(tmpdir(), "agdf-integrity-active-")));
+    const git = spawnSync("git", ["init", "-q", activeProbeRoot], { encoding: "utf8" });
+    if (git.status !== 0) throw new Error(`activation fixture repository initialization failed: ${git.stderr}`);
+    const initialized = spawnSync(process.execPath, [join(repoRoot, "packages", "cli", "bin", "create-agdf.js"),
+      "init", "--dir", activeProbeRoot, "--language", "en", "--json"], { encoding: "utf8" });
+    if (initialized.status !== 0) throw new Error(`current activation fixture initialization failed: ${initialized.stderr || initialized.stdout}`);
     const activeHooks = await AGDFPlugin({
-      directory: repoRoot,
+      directory: activeProbeRoot,
       client: {
         app: { async log() { return {}; } },
         tui: { async showToast() { return {}; } },
@@ -1585,6 +1593,8 @@ if (sourceMode && isFile(openCodeNpmPluginPath)) {
     }
   } catch (error) {
     failures.push(`OpenCode npm plugin Request Activation integrity probe failed: ${error.message}`);
+  } finally {
+    if (activeProbeRoot) rmSync(activeProbeRoot, { recursive: true, force: true });
   }
 }
 
@@ -1632,7 +1642,37 @@ if (pluginDefinition) {
   }
 }
 
-if (!sourceMode && installationProvenance?.profile_id === "copilot-runtime-plugin") {
+// The AGDF companion is Claude-only (SDD-01, SDD-02): its build-only descriptor owns the runtime Claude
+// manifest's hooks declaration; the Codex manifest, the shared hooks, the shared definition and the
+// Copilot profile never reference it.
+const companionFiles = ["companion.json", "hooks.json", "register.mjs", "assignment.mjs", "figure.mjs", "gate-bar.mjs",
+  "localization.mjs", "notice.mjs", "persistence.mjs", "run-state.mjs", "state.mjs", "view.mjs", "locales.json"];
+const copilotRuntimeProfile = !sourceMode && installationProvenance?.profile_id === "copilot-runtime-plugin";
+const companionRoot = sourceMode ? join(pluginRoot, "host-templates", "claude", "companion") : join(pluginRoot, "companion");
+const mentionsCompanion = (value) => /companion/iu.test(JSON.stringify(value ?? null));
+if (copilotRuntimeProfile) {
+  if (isDirectory(join(pluginRoot, "companion"))) failures.push("Copilot runtime plugin must not contain the Claude companion");
+} else {
+  for (const file of companionFiles) assertFile(join(companionRoot, file), `Claude companion file ${file}`);
+  const descriptorPath = join(companionRoot, "companion.json");
+  const descriptor = isFile(descriptorPath) ? readJson(descriptorPath, "Claude companion descriptor") : null;
+  if (JSON.stringify(descriptor) !== JSON.stringify({ schema_version: 1, hooks: "./companion/hooks.json" })) {
+    failures.push("Claude companion descriptor must declare exactly ./companion/hooks.json");
+  }
+  const companionHooksPath = join(companionRoot, "hooks.json");
+  const companionHooks = isFile(companionHooksPath) ? readJson(companionHooksPath, "Claude companion hooks") : null;
+  if (JSON.stringify(companionHooks) !== JSON.stringify({ modules: ["./register.mjs"] })) {
+    failures.push("Claude companion hooks must load only ./register.mjs");
+  }
+  if (claudePlugin && (sourceMode ? Object.hasOwn(claudePlugin, "hooks") : claudePlugin.hooks !== descriptor?.hooks)) {
+    failures.push("Claude plugin manifest must declare the companion only in the runtime profile, from its descriptor");
+  }
+}
+if (mentionsCompanion(codexPlugin)) failures.push("Codex plugin manifest must not reference the Claude companion");
+if (mentionsCompanion(hooksConfig)) failures.push("shared plugin hooks must not reference the Claude companion");
+if (mentionsCompanion(pluginDefinition)) failures.push("shared AGDF plugin definition must not reference the Claude companion");
+
+if (copilotRuntimeProfile) {
   const copilotPlugin = isFile(copilotPluginPath) ? readJson(copilotPluginPath, "Copilot plugin manifest") : null;
   const copilotHooks = isFile(copilotHooksPath) ? readJson(copilotHooksPath, "Copilot plugin hooks") : null;
   if (!copilotPlugin) failures.push("installed runtime plugin must include root plugin.json for GitHub Copilot");
@@ -2101,7 +2141,7 @@ for (const relativePath of expectedControlFiles) {
   assertFile(join(controlRoot, relativePath), `plugins/agdf/control/${relativePath}`);
 }
 
-const runTemplatePath = join(controlRoot, "templates", "AGDF_RUN.md");
+const runTemplatePath = join(controlRoot, "templates", "RUN_STATE.md");
 const contextGraphTemplatePath = join(controlRoot, "templates", "CONTEXT_GRAPH.md");
 const sotRegistryTemplatePath = join(controlRoot, "templates", "SOT_REGISTRY.md");
 const qualityContractsPath = join(controlRoot, "templates", "AGENT_QUALITY_CONTRACTS.json");
@@ -2110,23 +2150,17 @@ const uxIntentTemplatePath = join(controlRoot, "templates", "artefacts", "UX_INT
 const prdTemplatePath = join(controlRoot, "templates", "artefacts", "PRD.md");
 const verifiedChangeTemplatePath = join(controlRoot, "templates", "artefacts", "VERIFIED_CHANGE.md");
 const orTemplatePath = join(controlRoot, "templates", "artefacts", "OR.md");
-const backlogTemplatePath = join(controlRoot, "templates", "MASTER_BACKLOG.md");
 
 if (isFile(runTemplatePath)) {
   const runTemplate = read(runTemplatePath);
-  for (const required of ["current_gate", "next allowed action", "Missing Evidence", "Mode / Slice Decision", "transparency_note", "Artefact Chain", "context_graph_impact", "context_graph_reconciliation", "quality_outlook"]) {
-    if (!runTemplate.includes(required)) failures.push(`AGDF_RUN.md missing control field: ${required}`);
-  }
-  assertContextGraphReconciliation("AGDF_RUN.md template", runTemplate, { allowTemplatePlaceholders: true });
-  const runStatusCard = sectionAfterHeading(runTemplate, "Run Status Card");
-  for (const label of ["Status", "Current gate", "Allowed now", "Blocked by", "Missing approval", "Next step", "Quality outlook"]) {
-    if (!runStatusCard.includes(`| ${label} |`)) failures.push(`AGDF_RUN.md Run Status Card missing readable label: ${label}`);
+  for (const required of ['version-4', 'Objective', 'Mode/Slice Decision', 'Relationships', 'quality_outlook']) {
+    if (!runTemplate.includes(required)) failures.push(`RUN_STATE.md missing current authored field: ${required}`);
   }
-  for (const extraLabel of ["Mode", "Mode / slice", "Forbidden now", "Evidence", "Next skill"]) {
-    if (runStatusCard.includes(`| ${extraLabel} |`)) failures.push(`AGDF_RUN.md Run Status Card is not compact: ${extraLabel}`);
+  for (const heading of ['Approvals', 'Artefacts', 'Artefact Chain', 'Evidence', 'Current Control State']) {
+    if (runTemplate.includes(`## ${heading}\n`)) failures.push(`RUN_STATE.md persists derived table: ${heading}`);
   }
-  for (const rawField of ["allowed_now", "forbidden_now", "blocking_condition", "next_skill", "next_step", "quality_outlook"]) {
-    if (runStatusCard.includes(`- ${rawField}:`)) failures.push(`AGDF_RUN.md Run Status Card exposes raw field: ${rawField}`);
+  for (const retired of ['AGDF_RUN.md', 'MASTER_BACKLOG.md']) {
+    if (isFile(join(controlRoot, 'templates', retired))) failures.push(`Retired control template remains: ${retired}`);
   }
 }
 
@@ -2147,20 +2181,6 @@ if (isFile(orTemplatePath)) {
   }
 }
 
-if (isFile(backlogTemplatePath)) {
-  const backlogTemplate = read(backlogTemplatePath);
-  for (const required of [
-    "| Priority | Key | Work item | Status | Artefacts | Current spec | Next step |",
-    "| Key | Work item | Final status | Historical record | Outcome |",
-    "document-relative Markdown link",
-  ]) {
-    if (!backlogTemplate.includes(required)) failures.push(`MASTER_BACKLOG.md missing human-readable backlog contract: ${required}`);
-  }
-  if (backlogTemplate.includes("| Prio | Key | Title | Status | UR |")) {
-    failures.push("MASTER_BACKLOG.md must not use the legacy wide layout as its canonical template");
-  }
-}
-
 if (isFile(contextGraphTemplatePath)) {
   const contextGraphTemplate = read(contextGraphTemplatePath);
   for (const required of ["Admission Rules", "exit criterion", "Relationship Language", "evidenced_by"]) {
@@ -2314,9 +2334,7 @@ if (isFile(orTemplatePath)) {
   assertContextGraphReconciliation("OR.md template", orTemplate, { allowTemplatePlaceholders: true });
 }
 
-if (isFile(activeRunStatePath)) {
-  assertContextGraphReconciliation(".agdf/control/AGDF_RUN.md", read(activeRunStatePath));
-}
+
 
 assertContextGraphReconciliation("Context Graph open-gap fixture", [
   "- context_graph_impact: link_only",

package/generated/plugins/agdf/scripts/instruction-footprint.mjs

@@ -29,7 +29,8 @@ export const INSTRUCTION_FOOTPRINT_SURFACE_IDS = Object.freeze([
 // irrelevant to the schema digest. A semantic change requires an explicitly reviewed validator
 // update, not a silent limit increase, condition weakening or dispatch rewrite.
 const AUTHORIZED_SCHEMA_V1_FINGERPRINT = "43d1bbd0760fd6957676ca8f31995411be3cfa76a7d9fd064d56d8d0676478a7";
-const AUTHORIZED_TERMINAL_DISPATCH_FINGERPRINT = "a6c88ba3da4a022d0910f59b0bbf1d88726dcbc8077bba0ae6bd00b3bfd9b9e0";
+// UR MCP-R02/MCP-R03: typed transport guidance changes; terminal stop semantics remain exact.
+const AUTHORIZED_TERMINAL_DISPATCH_FINGERPRINT = "4ace6aaf4412e09ac7b350e62bd20d575e8f61eea816db71a9eb47492d7142c4";
 const AUTHORIZED_OPENCODE_EAGER_FINGERPRINTS = Object.freeze({
   canonical: "f4241ee566b2e2528a6c031281135561b411ac14602958bfdc3219a28db52f3f",
   global: "166e07d217fd8d8e7f6734c0c8e509e59b09d24828a5dd6132f546b55d99629c",
@@ -539,18 +540,17 @@ function validateSurfaceStructure({ surfaceId, record, canonicalKernel, expected
         && typeof control.status === "string" && control.status.length > 0
         && control.authorizes === false
         && (control.inspection_state === "unavailable" ? control.counts === null : (
-          control.counts && Object.keys(control.counts).sort().join(",") === "historical,migration,repair"
+          control.counts && Object.keys(control.counts).sort().join(",") === "current,unsupported"
           && Object.values(control.counts).every((count) => Number.isSafeInteger(count) && count >= 0)
         ))
         && (!Object.hasOwn(control, "notice") || (typeof control.notice === "string" && invocation))
         && (!Object.hasOwn(control, "invocation") || (
           invocation && Object.keys(invocation).sort().join(",") === "argv,authorizes,executable"
           && isAbsoluteInstructionPath(invocation.executable) && invocation.authorizes === false
-          && Array.isArray(invocation.argv) && invocation.argv.length === 7
+          && Array.isArray(invocation.argv) && invocation.argv.length === 6
           && isAbsoluteInstructionPath(invocation.argv[0])
           && invocation.argv[1] === "control-maintenance" && invocation.argv[2] === "--dir"
-          && invocation.argv[3] === control.target && invocation.argv[4] === "--guided"
-          && invocation.argv[5] === "--language" && /^[A-Za-z0-9-]{1,24}$/u.test(invocation.argv[6])
+          && invocation.argv[3] === control.target && invocation.argv[4] === "--language" && /^[A-Za-z0-9-]{1,24}$/u.test(invocation.argv[5])
         ))
       );
       if (