create-agdf 0.20.2 → 0.31.0

package/runtime/core/lib/control-evaluation/run-work-summary.js

@@ -1,3 +1,4 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { createHash } from 'node:crypto';
 import { readFileSync } from '../control-read/fs.js';
 import { containedRegularFile, hasSymlinkComponent, isSafeControlRelativePath } from '../control-state/contained-file.js';
@@ -6,7 +7,7 @@ import { effectiveNextAllowedAction } from './next-action.js';
 import { evaluateQaFollowUp, inspectQaReports } from './qa-follow-up.js';
 import { prepareRunContentState, modeSliceDecision } from './run-state.js';
 import { extractField } from './verified-change.js';
-import { summaryLabel } from './backlog-vocabulary.js';
+import { summaryLabel } from './work-vocabulary.js';
 import { readReportDecision } from './report-decision.js';
 
 // Shared projection; never invokes gate-check, changes control or grants permission. `proposed`
@@ -22,20 +23,21 @@ export function runWorkSummary(root, content, runPath = '', decision = policyFor
     sources: [], limitations: [], authorizes: false };
   summary.evidence_applicability = Object.fromEntries(['current', 'superseded', 'applicability_unknown'].map(group => [group,
     state.evidence_applicability[group].map(row => ({ path: row.report?.path ?? row.source, step: row.step ?? null, reason: row.reason, available: row.available }))]));
-  if (lifecycle === 'completed') summary.kind = decision.completion?.fulfilled ? 'completed' : 'unconfirmed';
+  if (['superseded', 'abandoned'].includes(lifecycle)) { summary.kind = 'run_ended'; summary.display_action = decision.next_allowed_action; }
+  else if (lifecycle === 'completed') summary.kind = decision.completion?.fulfilled ? 'completed' : 'unconfirmed';
   else if (decision.status === 'blocked') summary.kind = 'unconfirmed';
   else if (decision.current_gate === 'OR') summary.kind = 'closeout_pending';
   else if (decision.missing_approval !== 'none') summary.kind = 'approval_pending';
   const qa = state.artefacts.get('QA');
   const structured = ['structured_slice', 'structured_delivery'].includes(modeSliceDecision(state));
-  const qaRelevant = structured && (qa?.path || ['QA', 'UAT', 'OR'].includes(decision.current_gate));
+  const qaRelevant = summary.kind !== 'run_ended' && structured && (qa?.path || ['QA', 'UAT', 'OR'].includes(decision.current_gate));
   const unconfirmed = reason => { summary.kind = 'source_unconfirmed'; summary.limitations.push(reason);
     summary.display_action = decision.next_allowed_action; };
   if (qaRelevant) {
     summary.qa_outcome = 'unconfirmed';
     const path = String(qa?.path ?? '').replace(/^`|`$/gu, '');
     if (!path) { summary.kind = 'qa_report_pending'; summary.qa_outcome = 'missing'; }
-    else if (!isSafeControlRelativePath(path) || /[%?#]/u.test(path) || !path.startsWith(`.agdf/control/artefacts/${runId}/`)
+    else if (!isSafeControlRelativePath(path) || /[%?#]/u.test(path) || !path.startsWith(`${runDocumentPath(runId, '')}/`)
         || hasSymlinkComponent(root, path)) unconfirmed('qa_source_unsafe');
     else {
       const overlay = proposed?.get(path), file = typeof overlay === 'string' ? null : containedRegularFile(root, path);

package/runtime/core/lib/control-evaluation/shared-value.js

@@ -0,0 +1,7 @@
+export function isPlaceholderValue(value) {
+  return !value || (value.startsWith("`") && value.includes("|"));
+}
+
+export function filled(value) {
+  return Boolean(value && !isPlaceholderValue(value) && value.trim() !== "");
+}

package/runtime/core/lib/control-evaluation/shared.js

@@ -1,6 +1,7 @@
+export { filled, isPlaceholderValue } from "./shared-value.js";
+import { filled, isPlaceholderValue } from "./shared-value.js";
 import { existsSync, readFileSync } from "../control-read/fs.js";
-import { join, posix } from "node:path";
-import { SUMMARY_LABELS } from "./backlog-vocabulary.js";
+import { join } from "node:path";
 
 export function cleanStatusCell(value) {
   return (value ?? "").replace(/\x60/g, "").trim();
@@ -42,261 +43,13 @@ export function tableRows(content) {
     });
 }
 
-const compactBacklogHeaders = ["priority", "key", "work item", "status", "artefacts", "current spec", "next step"];
-const legacyBacklogHeaders = ["prio", "key", "title", "status", "ur", "brownfield review", "prd", "sd", "tp", "qa", "or", "current spec", "notes"];
-const backlogStatusLabels = new Map([
-  ...Object.entries(SUMMARY_LABELS).map(([code, labels]) => [labels[0].toLowerCase(), code]),
-  ...["Brownfield Analysis", "CD+Tests", "CR", "Quick Task Execution", "Verified Change Execution", "Mode/Slice Decision"]
-    .map(phase => [`${phase.toLowerCase()} work pending`, "work_pending"]),
-  ["needs ur", "needs_ur"],
-  ["awaiting brownfield review", "awaiting_brownfield_review"],
-  ["awaiting prd", "awaiting_prd"],
-  ["awaiting prd approval", "awaiting_prd_approval"],
-  ["awaiting sd", "awaiting_sd"],
-  ["awaiting sd approval", "awaiting_sd_approval"],
-  ["awaiting tp", "awaiting_tp"],
-  ["awaiting tp approval", "awaiting_tp_approval"],
-  ["in progress", "in_progress"],
-  ["blocked", "blocked"],
-  ["awaiting qa", "awaiting_qa"],
-  ["awaiting uat", "awaiting_uat"],
-  ["awaiting or", "awaiting_or"],
-  ["completed", "completed"],
-  ["superseded", "superseded"],
-  ["abandoned", "abandoned"],
-]);
-const backlogArtefactLabels = new Map([
-  ["ur", "ur"],
-  ["brownfield", "brownfield_review"],
-  ["prd", "prd"],
-  ["sd", "sd"],
-  ["tp", "tp"],
-  ["qa", "qa"],
-  ["or", "or"],
-]);
-const backlogScopeLabels = new Map([
-  ["framework-maintenance", "framework_maintenance"],
-  ["external-delivery", "external_delivery"],
-]);
-
-export function normalizeBacklogHeader(value) {
-  return value.replace(/`/g, "").trim().toLowerCase();
-}
-
-export function markdownLink(value) {
-  const match = value.trim().match(/^\[([^\]]+)\]\(([^)]+)\)$/);
-  return match ? { label: match[1].trim(), target: match[2].trim() } : null;
-}
-
-export function resolvedBacklogLinkTarget(target) {
-  if (!target
-    || target.startsWith("/")
-    || target.includes("\\")
-    || /^[a-z][a-z0-9+.-]*:/i.test(target)) {
-    return null;
-  }
-  const resolved = posix.normalize(posix.join(".agdf/control", target));
-  if (resolved === ".." || resolved.startsWith("../")) return null;
-  return resolved;
-}
-
-export function normalizedBacklogLinkTarget(value, findings, backlogPath, label) {
-  const link = markdownLink(value);
-  if (!link) return value.trim();
-  const resolved = resolvedBacklogLinkTarget(link.target);
-  if (!resolved) {
-    if (findings) {
-      addFinding(
-        findings,
-        "revise",
-        "AGDF_BACKLOG_LINK_TARGET_INVALID",
-        `Backlog ${label} link must be relative to MASTER_BACKLOG.md: ${link.target || "<empty>"}.`,
-        backlogPath,
-        "Use a document-relative artefact target such as artefacts/<key>/UR.md.",
-      );
-    }
-    return link.target;
-  }
-  return resolved;
-}
-
-export function normalizeBacklogStatus(value, findings, backlogPath) {
-  const cleaned = cleanStatusCell(value ?? "");
-  const lookup = cleaned.replaceAll("_", " ").toLowerCase();
-  const normalized = backlogStatusLabels.get(lookup);
-  if (normalized) return normalized;
-  if (/^[a-z][a-z0-9_]*$/.test(cleaned)) return cleaned;
-  if (findings && filled(cleaned)) {
-    addFinding(
-      findings,
-      "revise",
-      "AGDF_BACKLOG_STATUS_UNKNOWN",
-      `MASTER_BACKLOG.md uses an unknown human status label: ${cleaned}.`,
-      backlogPath,
-      "Use a documented human status label or a supported legacy snake_case value.",
-    );
-  }
-  return cleaned;
-}
-
-export function normalizeBacklogScope(workItem, findings, backlogPath) {
-  const match = (workItem ?? "").match(/^\[([^\]]+)\]/);
-  if (!match) return undefined;
-  const cleaned = match[1].trim();
-  const lookup = cleaned.replaceAll("_", " ").toLowerCase().replaceAll(" ", "-");
-  const normalized = backlogScopeLabels.get(lookup);
-  if (normalized) return normalized;
-  if (findings) {
-    addFinding(
-      findings,
-      "revise",
-      "AGDF_BACKLOG_SCOPE_LABEL_UNKNOWN",
-      `MASTER_BACKLOG.md uses an unknown Work item scope tag: [${cleaned}].`,
-      backlogPath,
-      "Use [framework-maintenance] or [external-delivery], or remove the bracketed tag.",
-    );
-  }
-  return cleaned;
-}
-
-export function emptyBacklogPointer() {
-  return {
-    prio: "",
-    key: "",
-    title: "",
-    scope: "",
-    status: "",
-    ur: "",
-    brownfield_review: "",
-    prd: "",
-    sd: "",
-    tp: "",
-    qa: "",
-    or: "",
-    current_spec: "",
-    notes: "",
-  };
-}
-
-export function parseCompactArtefacts(value, pointer, findings, backlogPath) {
-  if (!filled(value)) return;
-  const seen = new Set();
-  for (const entry of value.split(/\s+·\s+/)) {
-    const link = markdownLink(entry);
-    if (!link) {
-      if (findings) {
-        addFinding(
-          findings,
-          "revise",
-          "AGDF_BACKLOG_ARTEFACT_LINK_INVALID",
-          `Compact Artefacts entry is not a Markdown link: ${entry}.`,
-          backlogPath,
-          "Use [UR](artefacts/<key>/UR.md) style links separated by a middle dot.",
-        );
-      }
-      continue;
-    }
-    const field = backlogArtefactLabels.get(link.label.toLowerCase());
-    if (!field) {
-      if (findings) {
-        addFinding(
-          findings,
-          "revise",
-          "AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN",
-          `Compact Artefacts uses an unknown label: ${link.label}.`,
-          backlogPath,
-          "Use UR, Brownfield, PRD, SD, TP, QA or OR.",
-        );
-      }
-      continue;
-    }
-    if (seen.has(field)) {
-      if (findings) {
-        addFinding(
-          findings,
-          "revise",
-          "AGDF_BACKLOG_ARTEFACT_LABEL_DUPLICATE",
-          `Compact Artefacts repeats the ${link.label} link.`,
-          backlogPath,
-          "Keep exactly one link per artefact type.",
-        );
-      }
-      continue;
-    }
-    seen.add(field);
-    pointer[field] = normalizedBacklogLinkTarget(entry, findings, backlogPath, link.label);
-  }
-}
-
-export function parseBacklogSection(section, findings = null, backlogPath = ".agdf/control/MASTER_BACKLOG.md") {
-  const rows = tableRows(section);
-  if (rows.length === 0) return [];
-  const headers = rows[0].map(normalizeBacklogHeader);
-  const layout = headers.join("|") === compactBacklogHeaders.join("|")
-    ? "compact"
-    : headers.join("|") === legacyBacklogHeaders.join("|")
-      ? "legacy"
-      : "unknown";
-
-  if (layout === "unknown") {
-    if (findings) {
-      addFinding(
-        findings,
-        "revise",
-        "AGDF_BACKLOG_LAYOUT_UNKNOWN",
-        `MASTER_BACKLOG.md uses an unsupported table layout: ${headers.join(", ")}.`,
-        backlogPath,
-        "Use the canonical compact layout or the supported legacy 13-column layout.",
-      );
-    }
-    return [];
-  }
-
-  return rows.slice(1)
-    .filter((cells) => cells.some((cell) => filled(cell)))
-    .map((cells) => {
-      const pointer = emptyBacklogPointer();
-      if (layout === "legacy") {
-        [
-          pointer.prio,
-          pointer.key,
-          pointer.title,
-          pointer.status,
-          pointer.ur,
-          pointer.brownfield_review,
-          pointer.prd,
-          pointer.sd,
-          pointer.tp,
-          pointer.qa,
-          pointer.or,
-          pointer.current_spec,
-          pointer.notes,
-        ] = cells.map((cell) => cell ?? "");
-        pointer.status = normalizeBacklogStatus(pointer.status, findings, backlogPath);
-        return pointer;
-      }
-
-      pointer.prio = cells[0] ?? "";
-      pointer.key = cleanStatusCell(cells[1] ?? "");
-      pointer.title = cells[2] ?? "";
-      pointer.scope = normalizeBacklogScope(cells[2], findings, backlogPath) ?? "";
-      pointer.status = normalizeBacklogStatus(cells[3], findings, backlogPath);
-      parseCompactArtefacts(cells[4] ?? "", pointer, findings, backlogPath);
-      pointer.current_spec = normalizedBacklogLinkTarget(cells[5] ?? "", findings, backlogPath, "Current spec");
-      pointer.notes = cells[6] ?? "";
-      return pointer;
-    });
-}
-
 export function hasFilledTableRow(content, firstCellPattern) {
   return tableRows(content)
     .filter((cells) => firstCellPattern.test(cells[0] ?? ""))
     .some((cells) => cells.slice(1).some((cell) => cell && !cell.startsWith("`")));
 }
 
-export function isPlaceholderValue(value) {
-  return !value || (value.startsWith("`") && value.includes("|"));
-}
+
 
 export function hasFilledEvidenceRow(content) {
   const evidenceSection = content.match(/## Evidence([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "";
@@ -323,9 +76,7 @@ export function markdownSection(content, heading) {
   return content.match(new RegExp(`(?:^|\\n)## ${escaped}\\s*\\n([\\s\\S]*?)(?:\\n## |\\n# |$)`))?.[1] ?? "";
 }
 
-export function filled(value) {
-  return Boolean(value && !isPlaceholderValue(value) && value.trim() !== "");
-}
+
 
 export function runSelectionRecovery(target) {
   const directSelection = "Pass --run <run_id> or set AGDF_RUN_ID to select the intended run";

package/runtime/core/lib/control-evaluation/tp-planning.js

@@ -1,3 +1,4 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { readFileSync } from '../control-read/fs.js';
 import { section } from './markdown-table.js';
 import { readSdDecisionRows } from './sd-readiness.js';
@@ -53,8 +54,8 @@ function sourceValid(root, state, reference) {
     && artefactFileDigest(root, source.path) === digest && readFileSync(file.path, 'utf8').includes(statement);
 }
 function resolutionValid(root, state, id, reference) {
-  const match = reference.match(/^(\.agdf\/control\/artefacts\/[^ ]+) @ (sha256:[0-9a-f]{64})$/u);
-  if (!match || !match[1].startsWith(`.agdf/control/artefacts/${state.run_id}/`) || hasSymlinkComponent(root, match[1])) return false;
+  const match = reference.match(/^(\.agdf\/control\/runs\/[^ ]+) @ (sha256:[0-9a-f]{64})$/u);
+  if (!match || !match[1].startsWith(`${runDocumentPath(state.run_id, '')}/`) || hasSymlinkComponent(root, match[1])) return false;
   const file = containedRegularFile(root, match[1]);
   if (file.status !== 'valid' || artefactFileDigest(root, match[1]) !== match[2] || !readFileSync(file.path, 'utf8').includes(id)) return false;
   const evidence = readEvidenceBindings(state.content);

package/runtime/core/lib/control-evaluation/traceability-readiness.js

@@ -45,6 +45,49 @@ function designDecisionIds(value) {
   return text.split(",").map((item) => item.trim().toUpperCase());
 }
 
+const JSON_TYPE_METAVARIABLE = /^<(?:uuid|string|non-empty string|number|integer|(?:positive|non-negative) (?:integer|number)|boolean|null|object|array)>$/iu;
+
+// Only typed JSON string values in an explicitly labelled schema/example are
+// metavariables. Literal JSON keys may name words such as "todo"; angle-bracket
+// key prompts, unknown values, arbitrary code and author fields stay checked.
+function schemaExampleText(code) {
+  let parsed;
+  try { parsed = JSON.parse(code); } catch { return code; }
+  if (parsed === null || typeof parsed !== 'object') return code;
+  return code.replace(/"(?:\\.|[^"\\])*"/gu, (quoted, offset) => {
+    const key = /^[ \t]*:/u.test(code.slice(offset + quoted.length));
+    const value = JSON.parse(quoted);
+    if (key && !/<[^>]+>/u.test(value)) return '"literal-key"';
+    return JSON.stringify(!key && JSON_TYPE_METAVARIABLE.test(value) ? value.slice(1, -1) : value);
+  });
+}
+
+// A quoted command such as `done <id>` is concrete CLI syntax. Schema examples
+// are permitted only in the decision clause, never instead of its rationale or
+// consequence. The source text itself is never changed.
+function unfinishedDecisionPrompts(value, { schemaExamples = false } = {}) {
+  const text = value.replace(/`([^`\n]+)`/gu, (span, code, offset) => {
+    if (/^[a-z][a-z0-9._/-]*(?:[ \t]+(?:--?[a-z0-9][a-z0-9_-]*|[a-z0-9._/-]+|<[a-z][a-z0-9_-]*>))+$/iu.test(code))
+      return code.replace(/<([a-z][a-z0-9_-]*)>/giu, '$1');
+    if (schemaExamples && /\b(?:(?:json[ \t]+)?schema(?:[ \t]+example)?|json[ \t]+example)[ \t]*[:=]?[ \t]*$/iu.test(value.slice(0, offset)))
+      return schemaExampleText(code);
+    return span;
+  });
+  // Preserve the original unfinished-field prefix guard even when an author
+  // has not closed its opening angle bracket yet.
+  return [...new Set(text.match(/<[^>]+>|^<[^>\s;]*|\b(?:tbd|to confirm|todo)\b/giu) ?? [])];
+}
+
+function decisionClauses(detail) {
+  // Semicolons or field-looking strings inside literal examples cannot declare
+  // the required author fields. Keep character offsets into the original text.
+  const labels = [...detail.replace(/`[^`\n]+`/gu, span => '_'.repeat(span.length))
+    .matchAll(/(?:^|;[ \t]*)(rationale|consequence|trade-off):[ \t]*/giu)];
+  return [{ field: 'decision', text: detail.slice(0, labels[0]?.index ?? detail.length).trim() },
+    ...labels.map((label, index) => ({ field: label[1].toLowerCase() === 'rationale' ? 'rationale' : 'consequence',
+      text: detail.slice(label.index + label[0].length, labels[index + 1]?.index ?? detail.length).trim() }))];
+}
+
 function architectureDecisionIds(markdown) {
   const body = section(markdown, "Architecture Decisions");
   const openItems = [];
@@ -54,7 +97,7 @@ function architectureDecisionIds(markdown) {
   for (const line of body.split("\n").map((item) => item.trim()).filter((item) => /^[-*]\s+/u.test(item))) {
     const decision = line.replace(/^[-*]\s+/u, "").trim();
     if (/^none\b/iu.test(decision)) {
-      if (!reasonedNone(decision) || /<[^>]+>|\b(?:tbd|to confirm|todo)\b/iu.test(decision)) {
+      if (!reasonedNone(decision) || unfinishedDecisionPrompts(decision).length) {
         openItems.push("State why no binding SD decision is needed after 'none'");
       }
       if (none || ids.length) openItems.push("SD cannot combine 'none' with binding design decisions");
@@ -70,12 +113,18 @@ function architectureDecisionIds(markdown) {
     if (none) openItems.push("SD cannot combine 'none' with binding design decisions");
     if (ids.includes(id)) openItems.push(`Duplicate SD design decision ID: ${id}`);
     ids.push(id);
-    const detail = match[2];
-    const rationale = detail.match(/(?:^|;\s*)rationale:\s*([^;]+)/iu)?.[1]?.trim();
-    const consequence = detail.match(/(?:^|;\s*)(?:consequence|trade-off):\s*([^;]+)/iu)?.[1]?.trim();
-    if (unfinished(detail) || /<[^>]+>|\b(?:tbd|to confirm|todo)\b/iu.test(detail)
-        || unfinished(rationale) || unfinished(consequence)) {
-      openItems.push(`SD design decision ${id} needs a concrete rationale and consequence`);
+    const clauses = decisionClauses(match[2]);
+    for (const field of ['decision', 'rationale', 'consequence']) {
+      const declarations = clauses.filter(clause => clause.field === field);
+      if (declarations.length > 1)
+        openItems.push(`SD design decision ${id} needs exactly one nonempty ${field}: field; found ${declarations.length} declarations`);
+      else if (!declarations.length || !declarations[0].text)
+        openItems.push(field === 'decision' ? `SD design decision ${id} needs a concrete decision statement`
+          : `SD design decision ${id} is missing a nonempty ${field}: field`);
+    }
+    for (const clause of clauses) {
+      const prompts = unfinishedDecisionPrompts(clause.text, { schemaExamples: clause.field === 'decision' });
+      if (prompts.length) openItems.push(`SD design decision ${id} contains unresolved author prompts in ${clause.field}: ${prompts.slice(0, 8).map(token => JSON.stringify(token)).join(', ')}${prompts.length > 8 ? ` (${prompts.length - 8} more)` : ''}`);
     }
   }
   if (!ids.length && !none) openItems.push("List binding SD decisions by SDD ID, or record a reasoned none");
@@ -192,7 +241,7 @@ export function evaluateTpTraceability(targetDir, runState) {
     for (const column of ["expected_result", "evidence"]) if (unfinished(row[column])) openItems.push(`TP scenario ${scenario || "without id"} needs ${column}`);
     const expectedDecisions = decisionsByCriterion.get(criterion) ?? [];
     if (expectedDecisions.length) {
-      if (!expectedDecisions.includes(decision)) openItems.push(`TP scenario ${scenario || "without id"} must reference an SD decision for ${criterion}`);
+      if (!expectedDecisions.includes(decision)) openItems.push(`TP scenario ${scenario || "without id"} for ${criterion} has design_decision_id ${decision || "empty"}; set that table column to one of the mapped SD IDs: ${expectedDecisions.join(", ")}. Scenario prose cannot replace this cell.`);
       else {
         if (!verifiedDecisions.has(criterion)) verifiedDecisions.set(criterion, new Set());
         verifiedDecisions.get(criterion).add(decision);

package/runtime/core/lib/control-evaluation/ur-readiness.js

@@ -23,25 +23,43 @@ export function evaluateUrReadiness(targetDir, runState, { presentationLanguage
   const path = resolvedArtefactFile(targetDir, runState.artefacts.get("UR")?.path);
   if (!path) return null;
   const content = readFileSync(path, "utf8");
+  return evaluateUrContentReadiness(content, { languages: resolveArtifactPresentationLanguages(targetDir, presentationLanguage), path });
+}
+
+// Shared authoring semantics for Run and pre-Run planning; planning explicitly
+// requires the current clarification contract rather than legacy marker absence.
+export function evaluateUrContentReadiness(content, { languages, path = 'UR.md', requireClarification = false } = {}) {
   try { previewRequirement(content); } catch (error) { return { ready: false, legacy: false, open_items: [error.message] }; }
   const markers = content.match(/^Requirements clarification:[^\r\n]*$/gmu) ?? [];
-  if (!markers.length) return { ready: true, legacy: true, open_items: [] };
+  if (!markers.length && !requireClarification) return { ready: true, legacy: true, open_items: [] };
   const open = markers.length === 1 && markers[0].trim() === UR_AUTHORING_FORMAT.readiness_contract ? [] : ["Requirements clarification"];
   const blocks = content.split(/^##[ \t]+/mu).slice(1).map(block => {
     const [heading, ...body] = block.split(/\r?\n/u);
     return { heading: heading.replace(/^\d+\.[ \t]*/u, "").trim(), body: body.join("\n").trim() };
   });
+  const placeholders = {};
   for (const section of sections) {
     const matches = blocks.filter(block => block.heading === section);
     const body = matches[0]?.body ?? "";
-    if (matches.length !== 1 || !body || templatePrompts.has(body) || /<[^>]+>|^(?:tbd|todo|to confirm)[ \t]*$/imu.test(body)) open.push(section);
+    const unfinished = unfinishedPlaceholders(body);
+    if (unfinished.length) placeholders[section] = unfinished;
+    if (matches.length !== 1 || !body || templatePrompts.has(body) || unfinished.length || /^(?:tbd|todo|to confirm)[ \t]*$/imu.test(body)) open.push(section);
   }
-  const languages = resolveArtifactPresentationLanguages(targetDir, presentationLanguage);
   const summary = evaluateApprovalSummaryReadiness("UR", content, languages);
   if (!summary.ready) open.push(summary.required_heading);
   // Name the unreadable field and its expected line, not only the section heading.
   if (summary.reason === "approval_summary_field_unreadable") open.push(renderApprovalSummaryIssue(summary, {
     path, presentationLanguage: languages.presentation_language,
   }));
-  return { ready: open.length === 0, legacy: false, open_items: open, approval_summary: summary };
+  return { ready: open.length === 0, legacy: false, open_items: open, approval_summary: summary,
+    ...(Object.keys(placeholders).length ? { unfinished_placeholders: placeholders } : {}) };
+}
+
+// Inline code may name syntax metavariables, as in `node wordfreq.js <file>` or
+// `<word> <count>`. A single identifier in angle brackets inside a code span is
+// literal notation; prose placeholders and spaced prompts such as `<why ...>`
+// stay unfinished. The UR template carries no code-span prompts to hide.
+function unfinishedPlaceholders(body) {
+  const notation = body.replace(/`([^`\n]+)`/gu, (_span, code) => code.replace(/<[\p{L}][\p{L}\p{N}_-]*>/gu, ""));
+  return [...new Set(notation.match(/<[^>]+>/gu) ?? [])];
 }

package/runtime/core/lib/control-evaluation/verified-change.js

@@ -1,14 +1,12 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { readFileSync } from "../control-read/fs.js";
 import { containedRegularFile, isSafeControlRelativePath } from "../control-state/contained-file.js";
 import { cleanStatusCell, isPlaceholderValue } from "./shared.js";
 
-export function extractField(content, field) {
-  const pattern = new RegExp(`^- ${field}:[^\\S\\r\\n]*(.*)$`, "m");
-  return content.match(pattern)?.[1]?.trim() ?? "";
-}
+export { extractField, verifiedChangeEscalationTargets } from "./gate-policy-inputs.js";
+import { extractField, verifiedChangeEscalationTargets } from "./gate-policy-inputs.js";
 
 export const verifiedChangeStatuses = new Set(["draft", "eligible", "executed", "escalated"]);
-export const verifiedChangeEscalationTargets = new Set(["structured_slice", "structured_delivery"]);
 
 export function parseVerifiedChangePathList(value) {
   const cleaned = cleanStatusCell(value ?? "");
@@ -20,10 +18,12 @@ export function isSafeRepoRelativePath(value) {
   return isSafeControlRelativePath(value);
 }
 
-export function readVerifiedChangeRecord(targetDir, runState) {
+export function readVerifiedChangeRecord(targetDir, runState, proposedArtefacts) {
   const artefact = runState.artefacts.get("Verified Change");
   if (!artefact?.path || isPlaceholderValue(artefact.path)) return { status: "missing", path: "", content: "" };
   if (!isSafeRepoRelativePath(artefact.path)) return { status: "invalid", path: artefact.path, content: "", error: "record_path_invalid" };
+  const proposed = proposedArtefacts?.get(artefact.path);
+  if (proposed) return { status: 'present', path: artefact.path, content: proposed.content };
   const result = containedRegularFile(targetDir, artefact.path);
   if (result.status !== "valid") {
     if (result.status === "invalid") return { status: "invalid", path: artefact.path, content: "", error: "record_path_invalid" };
@@ -35,7 +35,7 @@ export function readVerifiedChangeRecord(targetDir, runState) {
 export function evaluateVerifiedChange(targetDir, runState, dependencies = {}) {
   const gitPathList = dependencies.gitPathList ?? (() => null);
   const gitValue = dependencies.gitValue ?? (() => null);
-  const record = readVerifiedChangeRecord(targetDir, runState);
+  const record = readVerifiedChangeRecord(targetDir, runState, dependencies.proposedArtefacts);
   const findings = [];
   const add = (code, message, nextStep, severity = "revise") => findings.push({
     severity,
@@ -99,8 +99,8 @@ export function evaluateVerifiedChange(targetDir, runState, dependencies = {}) {
   const dirtyCandidate = [...allowedPaths].find((path) => baselinePaths.has(path));
   if (dirtyCandidate) add("AGDF_VERIFIED_CHANGE_BASELINE_CANDIDATE_DIRTY", `Declared candidate path is already dirty at baseline: ${dirtyCandidate}.`, "Escalate or start from a clean candidate path; do not adopt pre-existing edits.", "block");
 
-  const permittedControlPaths = new Set([record.path, runState.path, ".agdf/control/MASTER_BACKLOG.md"]);
-  const runArtefactPrefix = `.agdf/control/artefacts/${runId}/`;
+  const permittedControlPaths = new Set([record.path, runState.path]);
+  const runArtefactPrefix = `${runDocumentPath(runId, '')}/`;
   for (const artefact of runState.artefacts.values()) {
     if (artefact.path_format === "invalid") continue;
     if (isSafeRepoRelativePath(artefact.path) && artefact.path.startsWith(runArtefactPrefix)) permittedControlPaths.add(artefact.path);
@@ -120,6 +120,8 @@ export function evaluateVerifiedChange(targetDir, runState, dependencies = {}) {
       }
     }
   } else {
+    // Completed pre-cutover records may legitimately retain the old projection
+    // in their immutable execution snapshot. Active work has no such exemption.
     const unsafeExecutionPath = executionChangedPaths.find((path) => !isSafeRepoRelativePath(path) || (!allowedPaths.has(path) && !permittedControlPaths.has(path)));
     if (unsafeExecutionPath) add("AGDF_VERIFIED_CHANGE_EXECUTION_SCOPE_INVALID", `Recorded execution path is outside the eligible scope: ${unsafeExecutionPath}.`, "Correct the historical execution snapshot or escalate.", "block");
   }

package/{generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/backlog-vocabulary.js → runtime/core/lib/control-evaluation/work-vocabulary.js}

@@ -1,7 +1,7 @@
 // Descriptive saved labels only. Gate policy and QA remain the decision owners.
 export const SUMMARY_KINDS = Object.freeze(['work_pending', 'approval_pending', 'qa_report_pending',
   'qa_evidence_open', 'qa_correction_open', 'qa_source_decision', 'qa_blocked', 'source_unconfirmed',
-  'closeout_pending', 'completed', 'unconfirmed']);
+  'closeout_pending', 'completed', 'unconfirmed', 'run_ended']);
 export const SUMMARY_LABELS = Object.freeze({
   work_pending: ['Work pending', 'Arbeit offen'], approval_pending: ['Approval pending', 'Freigabe ausstehend'],
   qa_report_pending: ['QA report pending', 'QA-Bericht ausstehend'],
@@ -10,6 +10,6 @@ export const SUMMARY_LABELS = Object.freeze({
   qa_source_decision: ['QA source decision required', 'QA: vorgelagerte Entscheidung erforderlich'],
   qa_blocked: ['QA blocked', 'QA blockiert'], source_unconfirmed: ['Source unconfirmed', 'Quelle nicht bestätigt'],
   closeout_pending: ['Closeout pending', 'Abschluss offen'], completed: ['Completed', 'Abgeschlossen'],
-  unconfirmed: ['Unconfirmed', 'Nicht bestätigt'],
+  unconfirmed: ['Unconfirmed', 'Nicht bestätigt'], run_ended: ['Run ended', 'Run beendet'],
 });
 export const summaryLabel = (kind, language = 'en') => SUMMARY_LABELS[kind]?.[language === 'de' ? 1 : 0] ?? SUMMARY_LABELS.unconfirmed[language === 'de' ? 1 : 0];

package/runtime/core/lib/control-inspect/artifact-readiness.js

@@ -1,3 +1,4 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { readFileSync } from '../control-read/fs.js';
 import { join } from 'node:path';
 import { captureControlScope } from '../control-read/snapshot.js';
@@ -8,12 +9,13 @@ import { evaluateUrReadiness } from '../control-evaluation/ur-readiness.js';
 import { evaluateSdReadiness } from '../control-evaluation/sd-readiness.js';
 import { evaluateSdTraceability, evaluateTpTraceability } from '../control-evaluation/traceability-readiness.js';
 import { resolveArtifactPresentationLanguages } from '../resources/context.js';
-import { evaluateApprovalSummaryReadiness } from '../control-state/run-presentation-render.js';
+import { evaluateApprovalSummaryReadiness, renderApprovalSummaryIssue } from '../control-state/run-presentation-render.js';
 import { artefactFileDigest, runSealState } from '../control-state/run-seal.js';
 import { containedRegularFile, hasSymlinkComponent } from '../control-state/contained-file.js';
 import { extractField } from '../control-evaluation/verified-change.js';
 
-export const ARTIFACT_READINESS_GATES = Object.freeze(['UR', 'PRD', 'SD', 'TP']);
+import { ARTIFACT_READINESS_GATES } from './selection.js';
+export { ARTIFACT_READINESS_GATES };
 
 // Describes the original author's findings; it does not validate or change gate policy.
 export function describeArtifactReadiness(result) {
@@ -24,7 +26,8 @@ export function describeArtifactReadiness(result) {
     'approval_summary_criteria_incomplete', 'approval_summary_user_goal_missing', 'approval_summary_scope_missing',
     'approval_summary_decisions_missing', 'approval_summary_criterion_content_missing', 'approval_summary_content_missing']);
   let findings = result.diagnostics.filter(row => names.has(row.code));
-  const readinessOwner = { AGDF_UR_REQUIREMENTS_INCOMPLETE: 'ur', AGDF_PRD_DECISIONS_OPEN: 'prd',
+  const readinessOwner = { AGDF_UR_REQUIREMENTS_INCOMPLETE: 'ur', AGDF_PRD_DECISIONS_OPEN: 'prd', AGDF_PRD_READINESS_INCOMPLETE: 'prd',
+    AGDF_APPROVAL_SUMMARY_INCOMPLETE: { PRD: 'prd', SD: 'sd', TP: 'traceability' }[result.gate],
     AGDF_SD_DECISIONS_OPEN: 'sd', AGDF_SD_TRACEABILITY_INCOMPLETE: 'traceability', AGDF_TP_TRACEABILITY_INCOMPLETE: 'traceability' };
   const key = readinessOwner[result.blocking_reason];
   const details = key && result.current_gate === result.gate && result.readiness_details?.[key];
@@ -42,7 +45,7 @@ export function describeArtifactReadiness(result) {
 
 // Runs only inside the caller's bounded captured view. Both consumers use these same validators.
 export function projectArtifactReadiness(root, { runId, gate, expectedRevisionId, presentationLanguage }) {
-  const path = `.agdf/control/artefacts/${runId}/${gate}.md`;
+  const path = `${runDocumentPath(runId, '')}/${gate}.md`;
   const targetRoot = root;
   const diagnostics = [], checks = [];
   let state, revision = null, digest = null;
@@ -86,7 +89,8 @@ export function projectArtifactReadiness(root, { runId, gate, expectedRevisionId
   const languages = resolveArtifactPresentationLanguages(targetRoot, presentationLanguage);
   const summary = evaluateApprovalSummaryReadiness(gate, content, languages);
   checks.push({ name: 'approval_summary', ...summary });
-  if (!summary.ready) diagnostics.push({ code: summary.reason, message: `Prepare ${summary.required_heading} using the existing summary rules.` });
+  if (!summary.ready) diagnostics.push({ code: summary.reason,
+    message: renderApprovalSummaryIssue(summary, { path, presentationLanguage: languages.presentation_language }) });
   // Supply only an in-memory draft pointer; no Run, approval or binding is written.
   const candidate = { ...state, artefacts: new Map(state.artefacts) };
   candidate.artefacts.set(gate, { path, status: 'draft' });
@@ -108,7 +112,7 @@ export function projectArtifactReadiness(root, { runId, gate, expectedRevisionId
 // Standalone authoring preflight retains its original captured/read-only report contract.
 export function inspectArtifactReadiness(root, input) {
   const { runId, gate, expectedRevisionId } = input;
-  const path = `.agdf/control/artefacts/${runId}/${gate}.md`;
+  const path = `${runDocumentPath(runId, '')}/${gate}.md`;
   try {
     return captureControlScope(root, view => projectArtifactReadiness(view.root, input)).data;
   } catch (error) {