create-agdf 0.20.2 → 0.30.0

package/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/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/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/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/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/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/.agdf/control/templates/AGDF_RUN.md

@@ -1,139 +0,0 @@
-# AGDF Run State
-
-## Run Meta
-
-- run_id:
-- started_at:
-- mode: `quick_task | verified_change | structured_delivery`
-- current_gate: `none | UR | Brownfield Review | Mode/Slice Decision | PRD | SD | TP | Quick Task Execution | Verified Change Execution | Brownfield Analysis | CD+Tests | CR | QA | UAT | OR`
-- decision: `pass | revise | block | in_progress`
-- owner:
-
-## Objective
-
-What outcome is this run trying to make trustworthy?
-
-## Current Control State
-
-| Question | Answer |
-|---|---|
-| What is known? |  |
-| What is approved? |  |
-| What is missing? |  |
-| What is the next allowed action? |  |
-| What is explicitly forbidden right now? |  |
-
-## Source And Scope State
-
-- normative_instruction_source:
-- multi_scope_state: `clear | ambiguous | blocked`
-- active_scope_evidence:
-- competing_scope_lines:
-- branch_workspace_evidence:
-- branch_workspace_scope_effect: `supports | conflicts | insufficient | not_checked`
-
-## Run Status Card
-
-This is a compact projection of the control state. It does not replace gate-check, QA, OR or approvals.
-
-| Run status | Value |
-|---|---|
-| Status |  |
-| Current gate |  |
-| Allowed now |  |
-| Blocked by |  |
-| Missing approval |  |
-| Next step |  |
-| Quality outlook |  |
-
-## Approvals
-
-Valid approval format for new runs: `Approval: <GateName>`.
-
-| Gate | Status | Evidence |
-|---|---|---|
-| UR | `missing | approved | not_applicable` |  |
-| PRD | `missing | approved | not_applicable` |  |
-| SD | `missing | approved | not_applicable` |  |
-| TP | `missing | approved | not_applicable` |  |
-| QA | `missing | approved | not_applicable` |  |
-| UAT | `missing | approved | not_applicable` |  |
-
-## Artefacts
-
-| Type | Path | Status | Notes |
-|---|---|---|---|
-| UR |  | `draft | approved | superseded | not_applicable` |  |
-| PRD |  | `draft | approved | superseded | not_applicable` |  |
-| SD |  | `draft | approved | superseded | not_applicable` |  |
-| TP |  | `draft | approved | superseded | not_applicable` |  |
-| Brownfield Review |  | `missing | draft | done | not_applicable | superseded` |  |
-| Verified Change |  | `missing | draft | eligible | executed | escalated` |  |
-| Review |  | `missing | done | not_applicable` |  |
-| QA |  | `missing | pass | revise | block | not_applicable` |  |
-| OR |  | `missing | done | not_applicable` |  |
-
-## Mode / Slice Decision
-
-Set this after Brownfield Review. Do not assume the full gate chain before the existing-system impact is understood.
-Quick Task execution or implementation is not allowed until this decision is visible with scope reason and evidence.
-
-- decision: `undecided | quick_task | verified_change | structured_slice | structured_delivery | block`
-- required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
-- scope_reason:
-- evidence:
-- transparency_note:
-
-## Artefact Chain
-
-Keep the active work item traceable. A gate may open only when the previous gate has both exact approval and a durable or linked artefact.
-
-| From | Relationship | To | Evidence |
-|---|---|---|---|
-| UR | `approved_by` | `Approval: UR` |  |
-| PRD | `derived_from` | UR |  |
-| SD | `derived_from` | PRD |  |
-| TP | `derived_from` | SD |  |
-| QA_REPORT | `tests` | TP |  |
-
-## Evidence
-
-| Evidence | Source | Covers | Strength |
-|---|---|---|---|
-|  |  |  | `direct | indirect | weak` |
-
-## Missing Evidence
-
-| Missing evidence | Impact | Required next step |
-|---|---|---|
-|  | `warn | revise | block` |  |
-
-## Risks
-
-| Risk | Impact | Mitigation or owner |
-|---|---|---|
-|  | `warn | revise | block` |  |
-
-## Context Graph Impact
-
-- context_graph_impact: `none | link_only | update_existing_node | new_node_required | sot_drift`
-- context_graph_refs:
-- context_graph_reconciliation: `resolved | not_applicable | open_gap`
-- context_graph_required_action: `none | link | update | create | resolve_drift`
-- context_graph_gate_effect: `none | warning | revise | block`
-- context_graph_evidence:
-
-## Knowledge Persistence Decision
-
-- memory_target: `context_graph | sot_registry | scope_artifact | open_questions | none`
-- memory_reason:
-- memory_refs:
-
-## Closeout
-
-- delivered:
-- not_delivered:
-- verification_performed:
-- unverified:
-- next_allowed_action:
-- quality_outlook:

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

@@ -1,39 +0,0 @@
-# AGDF Master Backlog
-
-This file is the living control pointer for active AGDF delivery work. Detailed UR, Brownfield Review, PRD, SD, TP, QA and OR artefacts should live in stable paths and be linked from here.
-
-## Rules
-
-1. New product semantics, functional change or user-visible behaviour change starts as a new UR draft in a stable local artefact path, for example `.agdf/control/artefacts/<key>/UR.md`, unless an authoritative repository SoT already exists and is linked here.
-2. `Approval: UR` adds or updates exactly one steering row with a document-relative Markdown link to the UR.
-3. Brownfield Review is created for the same work item after UR approval when existing-system impact must be sized before PRD depth or Quick Task execution.
-4. PRD, SD, TP and QA report artefacts are created for the same work item after the previous gate is approved and persisted or linked.
-5. `Approval: PRD`, `Approval: SD`, `Approval: TP` and `Approval: QA` require the corresponding durable artefact or linked repository SoT before the next gate can open.
-6. Generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved" does not update a gate. Only `Approval: <GateName>` does.
-7. Keep only steering-relevant work in `Active Backlog`.
-8. Every active item has exactly one linked current spec and a visible linked artefact chain.
-9. Historical artefacts remain linkable but do not override the current pointer.
-10. If an item is superseded, mark the replacement.
-11. If active work grows beyond roughly ten items, triage the backlog.
-12. `Status` must be one of the human-readable labels normalized by `packages/core/lib/control-evaluation/shared.js`: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Awaiting OR, Completed, Superseded, Abandoned. Generated observations also use Work pending, Approval pending, QA report pending, QA evidence open, QA correction open, QA source decision required, QA blocked, Source unconfirmed, Closeout pending, Unconfirmed, and phase-specific Brownfield Analysis/CD+Tests/CR/Quick Task Execution/Verified Change Execution/Mode/Slice Decision work pending. The parser module is authoritative; this list only mirrors it for readability.
-13. `Artefacts` link labels must be one of the labels normalized by the same parser module: `ur`, `brownfield`, `prd`, `sd`, `tp`, `qa`, `or` (case-insensitive). Do not invent other labels such as a raw artefact filename.
-14. After writing or updating this file, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before treating the edit as done.
-15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `packages/core/lib/control-evaluation/shared.js` is authoritative for the accepted values.
-16. After writing or updating this file, also resolve any `AGDF_BACKLOG_SCOPE_LABEL_UNKNOWN` finding, which fires only for a present-but-unrecognized bracketed tag, never for an absent one.
-
-17. Core writers may place a bounded `agdf-backlog-summary-v1` comment after a complete table, separated by a blank line. It records the addressed row, target, actual Run revision, observation time and consumed source digests; it never authorizes. Preserve it with its row. Older rows remain readable without it. Invalid/foreign/ambiguous observations remain visibly unconfirmed; reading does not synchronize or scan all Runs.
-
-## Active Backlog
-
-| Priority | Key | Work item | Status | Artefacts | Current spec | Next step |
-|---:|---|---|---|---|---|---|
-
-## Planned / Parking Lot
-
-| Priority | Key | Work item | Status | Artefacts | Current spec | Next step |
-|---:|---|---|---|---|---|---|
-
-## Completed / Superseded Pointers
-
-| Key | Work item | Final status | Historical record | Outcome |
-|---|---|---|---|---|

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

@@ -1,139 +0,0 @@
-# AGDF Run State
-
-## Run Meta
-
-- run_id:
-- started_at:
-- mode: `quick_task | verified_change | structured_delivery`
-- current_gate: `none | UR | Brownfield Review | Mode/Slice Decision | PRD | SD | TP | Quick Task Execution | Verified Change Execution | Brownfield Analysis | CD+Tests | CR | QA | UAT | OR`
-- decision: `pass | revise | block | in_progress`
-- owner:
-
-## Objective
-
-What outcome is this run trying to make trustworthy?
-
-## Current Control State
-
-| Question | Answer |
-|---|---|
-| What is known? |  |
-| What is approved? |  |
-| What is missing? |  |
-| What is the next allowed action? |  |
-| What is explicitly forbidden right now? |  |
-
-## Source And Scope State
-
-- normative_instruction_source:
-- multi_scope_state: `clear | ambiguous | blocked`
-- active_scope_evidence:
-- competing_scope_lines:
-- branch_workspace_evidence:
-- branch_workspace_scope_effect: `supports | conflicts | insufficient | not_checked`
-
-## Run Status Card
-
-This is a compact projection of the control state. It does not replace gate-check, QA, OR or approvals.
-
-| Run status | Value |
-|---|---|
-| Status |  |
-| Current gate |  |
-| Allowed now |  |
-| Blocked by |  |
-| Missing approval |  |
-| Next step |  |
-| Quality outlook |  |
-
-## Approvals
-
-Valid approval format for new runs: `Approval: <GateName>`.
-
-| Gate | Status | Evidence |
-|---|---|---|
-| UR | `missing | approved | not_applicable` |  |
-| PRD | `missing | approved | not_applicable` |  |
-| SD | `missing | approved | not_applicable` |  |
-| TP | `missing | approved | not_applicable` |  |
-| QA | `missing | approved | not_applicable` |  |
-| UAT | `missing | approved | not_applicable` |  |
-
-## Artefacts
-
-| Type | Path | Status | Notes |
-|---|---|---|---|
-| UR |  | `draft | approved | superseded | not_applicable` |  |
-| PRD |  | `draft | approved | superseded | not_applicable` |  |
-| SD |  | `draft | approved | superseded | not_applicable` |  |
-| TP |  | `draft | approved | superseded | not_applicable` |  |
-| Brownfield Review |  | `missing | draft | done | not_applicable | superseded` |  |
-| Verified Change |  | `missing | draft | eligible | executed | escalated` |  |
-| Review |  | `missing | done | not_applicable` |  |
-| QA |  | `missing | pass | revise | block | not_applicable` |  |
-| OR |  | `missing | done | not_applicable` |  |
-
-## Mode / Slice Decision
-
-Set this after Brownfield Review. Do not assume the full gate chain before the existing-system impact is understood.
-Quick Task execution or implementation is not allowed until this decision is visible with scope reason and evidence.
-
-- decision: `undecided | quick_task | verified_change | structured_slice | structured_delivery | block`
-- required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
-- scope_reason:
-- evidence:
-- transparency_note:
-
-## Artefact Chain
-
-Keep the active work item traceable. A gate may open only when the previous gate has both exact approval and a durable or linked artefact.
-
-| From | Relationship | To | Evidence |
-|---|---|---|---|
-| UR | `approved_by` | `Approval: UR` |  |
-| PRD | `derived_from` | UR |  |
-| SD | `derived_from` | PRD |  |
-| TP | `derived_from` | SD |  |
-| QA_REPORT | `tests` | TP |  |
-
-## Evidence
-
-| Evidence | Source | Covers | Strength |
-|---|---|---|---|
-|  |  |  | `direct | indirect | weak` |
-
-## Missing Evidence
-
-| Missing evidence | Impact | Required next step |
-|---|---|---|
-|  | `warn | revise | block` |  |
-
-## Risks
-
-| Risk | Impact | Mitigation or owner |
-|---|---|---|
-|  | `warn | revise | block` |  |
-
-## Context Graph Impact
-
-- context_graph_impact: `none | link_only | update_existing_node | new_node_required | sot_drift`
-- context_graph_refs:
-- context_graph_reconciliation: `resolved | not_applicable | open_gap`
-- context_graph_required_action: `none | link | update | create | resolve_drift`
-- context_graph_gate_effect: `none | warning | revise | block`
-- context_graph_evidence:
-
-## Knowledge Persistence Decision
-
-- memory_target: `context_graph | sot_registry | scope_artifact | open_questions | none`
-- memory_reason:
-- memory_refs:
-
-## Closeout
-
-- delivered:
-- not_delivered:
-- verification_performed:
-- unverified:
-- next_allowed_action:
-- quality_outlook: