create-agdf 0.30.0 → 0.31.0

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/closeout-readiness.js

@@ -24,6 +24,24 @@ export function closeoutContext(text) {
 }
 export const closeoutContextDigest = text => digest(`agdf-closeout-context/1\0${canonicalJson(closeoutContext(text))}`);
 
+// Bindings a structured OR states; the same tables drive the check and the
+// expectations returned with a refusal.
+const OR_SOURCE_FIELDS = Object.freeze({ related_ur: 'UR', related_prd: 'PRD', related_sd: 'SD', related_tp: 'TP', related_qa_report: 'QA' });
+const OR_GATE_ROWS = Object.freeze(['UR', 'PRD', 'SD', 'TP', 'Brownfield Review', 'Brownfield Analysis', 'CD+Tests', 'CR', 'QA', 'UAT']);
+const OR_MEMORY_TARGETS = Object.freeze(['context_graph', 'sot_registry', 'scope_artifact', 'open_questions', 'none']);
+const gateRowExpectation = (state, type) => ({
+  status: state.approvals.has(type) ? state.approvals.get(type).status : state.artefacts.get(type)?.status,
+  reference: state.artefacts.get(type)?.path || state.approvals.get(type)?.evidence,
+});
+function structuredOrExpectations(state, route) {
+  return {
+    fields: { ...Object.fromEntries(Object.entries(OR_SOURCE_FIELDS).map(([field, type]) => [field, state.artefacts.get(type)?.path ?? null])),
+      mode_slice_decision: route, current_gate: 'OR', decision: 'pass', required_approval: 'none' },
+    gate_state_rows: Object.fromEntries(OR_GATE_ROWS.map(type => [type, gateRowExpectation(state, type)])),
+    memory_target: OR_MEMORY_TARGETS, memory_fields: 'memory_reason and memory_refs need concrete text',
+  };
+}
+
 // Shared observation of registered OR and prepared OR candidates. Legacy reports retain
 // their documented formats; the new writer additionally requires the complete template.
 export function evaluateCloseoutReadiness(state, report, readArtefact, { prepared = false } = {}) {
@@ -85,14 +103,13 @@ export function evaluateCloseoutReadiness(state, report, readArtefact, { prepare
         ...Object.keys(context), 'next_allowed_action', 'required_approval', 'forbidden_until_then']) {
         if ([...report.matchAll(new RegExp(`^- ${field}:[ \\t]*(.*)$`, 'gmu'))].length !== 1) fail('or_field_ambiguous:' + field);
       }
-      for (const [field, type] of Object.entries({ related_ur: 'UR', related_prd: 'PRD', related_sd: 'SD', related_tp: 'TP', related_qa_report: 'QA' })) {
+      for (const [field, type] of Object.entries(OR_SOURCE_FIELDS)) {
         if (value(report, field) !== state.artefacts.get(type)?.path) fail('or_source_reference_invalid:' + field);
       }
       if (value(report, 'mode_slice_decision') !== route || value(report, 'current_gate') !== 'OR' || value(report, 'decision') !== 'pass') fail('or_control_binding_invalid');
       const gateRows = tableRows(markdownSection(report, 'Gate State')).filter(row => row[0] !== 'Gate or step');
-      for (const type of ['UR', 'PRD', 'SD', 'TP', 'Brownfield Review', 'Brownfield Analysis', 'CD+Tests', 'CR', 'QA', 'UAT']) {
-        const rows = gateRows.filter(row => row[0] === type), expected = state.approvals.has(type) ? state.approvals.get(type).status : state.artefacts.get(type)?.status;
-        const reference = state.artefacts.get(type)?.path || state.approvals.get(type)?.evidence;
+      for (const type of OR_GATE_ROWS) {
+        const rows = gateRows.filter(row => row[0] === type), { status: expected, reference } = gateRowExpectation(state, type);
         if (rows.length !== 1 || rows[0][1] !== expected || !concrete(rows[0][2])
           || cleanStatusCell(rows[0][2]) !== cleanStatusCell(reference)) fail('or_gate_state_unconfirmed:' + type);
       }
@@ -101,11 +118,12 @@ export function evaluateCloseoutReadiness(state, report, readArtefact, { prepare
         if (!concrete(text) || /<[^>]+>|\|[ \t]*\|/u.test(text)) fail('or_section_incomplete:' + section);
       }
       for (const section of ['Missing Evidence', 'Risks And Open Items']) if (/\|\s*(?:revise|block)\s*\|/u.test(markdownSection(report, section))) fail('or_required_obligation_open:' + section);
-      if (!['context_graph', 'sot_registry', 'scope_artifact', 'open_questions', 'none'].includes(context.memory_target)
+      if (!OR_MEMORY_TARGETS.includes(context.memory_target)
         || !concrete(context.memory_reason) || !concrete(context.memory_refs)) fail('or_knowledge_decision_incomplete');
       if (value(report, 'required_approval') !== 'none') fail('or_required_approval_open');
     }
   }
   return { ready: findings.length === 0, findings, route, context_digest: closeoutContextDigest(report),
-    parent_reconciliation: parent ?? null, programme_aggregation: programme ?? null };
+    parent_reconciliation: parent ?? null, programme_aggregation: programme ?? null,
+    ...(prepared && structured && findings.length ? { expected: structuredOrExpectations(state, route) } : {}) };
 }

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/gate-check.js

@@ -9,7 +9,8 @@ import { isGateSatisfied, transitionDecisionForRunState } from "./gate-policy.js
 import { effectiveNextAllowedAction } from "./next-action.js";
 import { evaluateVerifiedChange, extractField, verifiedChangeEscalationTargets } from "./verified-change.js";
 import { gateApprovalStatus, isInternalStepSatisfied, modeSliceDecision, readArtefactHeading, readRunState, resolvedArtefactFile } from "./run-state.js";
-import { renderReviewableApproval } from "../control-state/run-presentation-render.js";
+import { evaluateApprovalSummaryReadiness, renderApprovalSummaryIssue, renderReviewableApproval } from "../control-state/run-presentation-render.js";
+import { readFileSync } from "../control-read/fs.js";
 import { evaluateUrReadiness } from "./ur-readiness.js";
 import { inspectDefinitionSources } from "./definition-sources.js";
 import { evaluatePrdReadiness } from "./prd-readiness.js";
@@ -427,31 +428,58 @@ export function evaluateGateCheck(targetDir, selection = {}, dependencies = {})
   if (status === "open" && prdReadiness && transitionDecision.next_operation?.type !== "reassess_source_analysis" && isGateSatisfied(runState, "UR") && isInternalStepSatisfied(runState, "Brownfield Review")
       && ["structured_delivery", "structured_slice"].includes(modeSliceDecision(runState))) {
     const inputFacts = inspectDefinitionSources(targetDir, runState, extractField(runState.content, "run_id"), "PRD", ["UR", "Brownfield Review"]);
-    if (inputFacts.issue) prdReadiness = { ready: false, open_decisions: [...prdReadiness.open_decisions,
+    if (inputFacts.issue) prdReadiness = { ...prdReadiness, ready: false, source_issue: inputFacts.issue, open_decisions: [...prdReadiness.open_decisions,
       renderDefinitionSourceRecovery(inputFacts.issue, { registry: interactionLocales, requestedLocale: presentationLocale })] };
   }
   if (status === "open" && currentGate === "PRD" && prdReadiness && !prdReadiness.ready) {
     status = "blocked";
+    const checks = prdReadiness.readiness_checks;
     blockingReason = "AGDF_PRD_DECISIONS_OPEN";
+    if (checks?.decisions_ready) {
+      const sourceCriteriaIncomplete = !checks.approval_summary.ready && [
+        "approval_summary_criterion_content_missing", "approval_summary_source_criteria_invalid",
+        "approval_summary_source_criteria_duplicate", "approval_summary_criteria_missing",
+      ].includes(checks.approval_summary.reason);
+      blockingReason = prdReadiness.source_issue || !checks.preview_ready || !checks.criteria_ready || sourceCriteriaIncomplete
+        ? "AGDF_PRD_READINESS_INCOMPLETE" : "AGDF_APPROVAL_SUMMARY_INCOMPLETE";
+    }
     allowed = ["complete the listed PRD readiness items together and record a new run revision"];
     forbidden = [...forbidden, "present or approve PRD before required decisions and acceptance criteria are ready"];
     // Fixed text keeps the card localizable; detailed gaps travel separately in prd_readiness.open_decisions.
     nextAllowedAction = "complete the open PRD readiness items together, then record the revision through the inspected current recording operation";
   }
-  const sdReadiness = currentGate === "SD" && approvalArtefactReady ? evaluateSdReadiness(targetDir, runState) : null;
-  const traceabilityReadiness = status === "open" && approvalArtefactReady && currentGate === "SD"
+  let sdReadiness = currentGate === "SD" && approvalArtefactReady ? evaluateSdReadiness(targetDir, runState) : null;
+  let traceabilityReadiness = status === "open" && approvalArtefactReady && currentGate === "SD"
     ? evaluateSdTraceability(targetDir, runState)
     : status === "open" && approvalArtefactReady && currentGate === "TP"
       ? evaluateTpTraceability(targetDir, runState)
       : null;
-  if (status === "open" && sdReadiness && !sdReadiness.ready) {
+  // Presentation readiness belongs to the existing authoring gate, not to the
+  // traceability grammar. Use the same summary owner as preflight and rendering
+  // before a registered SD/TP draft can bypass its author and request approval.
+  let approvalSummaryReadiness = null;
+  if (status === "open" && approvalArtefactReady && ["SD", "TP"].includes(currentGate)) {
+    const path = runState.artefacts.get(currentGate).path;
+    const file = resolvedArtefactFile(targetDir, path);
+    const languages = resolveArtifactPresentationLanguages(targetDir, presentationLocale);
+    const summary = evaluateApprovalSummaryReadiness(currentGate, readFileSync(file, "utf8"), languages, { path });
+    if (!summary.ready) {
+      approvalSummaryReadiness = summary;
+      const issue = renderApprovalSummaryIssue(summary, { path, presentationLanguage: presentationLocale });
+      if (currentGate === "SD") sdReadiness = { ...sdReadiness, ready: false, decisions_ready: sdReadiness.ready,
+        open_decisions: [...sdReadiness.open_decisions, issue] };
+      else traceabilityReadiness = { ...traceabilityReadiness, ready: false, traceability_ready: traceabilityReadiness.ready,
+        open_items: [...traceabilityReadiness.open_items, issue] };
+    }
+  }
+  if (status === "open" && sdReadiness && !sdReadiness.ready && sdReadiness.decisions_ready !== true) {
     status = "blocked";
     blockingReason = "AGDF_SD_DECISIONS_OPEN";
     allowed = ["complete the listed SD readiness items together and record a new run revision"];
     forbidden = [...forbidden, "present or approve SD before required design decisions are ready"];
     nextAllowedAction = "complete the open SD readiness items together, then record the revision with the shared artefact writer";
   }
-  if (status === "open" && traceabilityReadiness && !traceabilityReadiness.ready) {
+  if (status === "open" && traceabilityReadiness && !traceabilityReadiness.ready && traceabilityReadiness.traceability_ready !== true) {
     status = "blocked";
     blockingReason = currentGate === "SD" ? "AGDF_SD_TRACEABILITY_INCOMPLETE" : "AGDF_TP_TRACEABILITY_INCOMPLETE";
     allowed = [currentGate === "SD"
@@ -462,6 +490,15 @@ export function evaluateGateCheck(targetDir, selection = {}, dependencies = {})
       ? "complete the listed SD traceability rows, then record the revision through the inspected current recording operation"
       : "complete the listed TP traceability rows, then record the revision through the inspected current recording operation";
   }
+  if (status === "open" && approvalSummaryReadiness) {
+    status = "blocked";
+    blockingReason = "AGDF_APPROVAL_SUMMARY_INCOMPLETE";
+  }
+  if (blockingReason === "AGDF_APPROVAL_SUMMARY_INCOMPLETE") {
+    allowed = ["complete the current artefact approval summary and record a new run revision"];
+    forbidden = [...forbidden, "present or approve the current artefact before its required approval summary is ready"];
+    nextAllowedAction = "complete the current artefact approval summary, then record the revision through the inspected current recording operation";
+  }
   if (status === "open" && /^Approval: /u.test(missingApproval) && !approvalArtefactReady) {
     allowed = allowed.filter((action) => !/^request exact .* approval$/iu.test(action));
     if (/request exact approval: Approval: /iu.test(nextAllowedAction)) {
@@ -662,6 +699,7 @@ export function evaluateGateCheck(targetDir, selection = {}, dependencies = {})
     ...(prdReadiness ? { prd_readiness: prdReadiness } : {}),
     ...(sdReadiness ? { sd_readiness: sdReadiness } : {}),
     ...(traceabilityReadiness ? { traceability_readiness: traceabilityReadiness } : {}),
+    ...(approvalSummaryReadiness ? { approval_summary_readiness: approvalSummaryReadiness } : {}),
     next_gate_after_approval: postApproval.next_gate_after_approval,
     allowed_after_approval: postApproval.allowed_after_approval,
     allowed,

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/gate-policy-inputs.js

@@ -6,6 +6,8 @@ export function extractField(content, field) {
 
 export const verifiedChangeEscalationTargets = new Set(["structured_slice", "structured_delivery"]);
 export const STRUCTURED_REQUIRED_REVIEWS = Object.freeze(['TP Review', 'Clean Implementation Review']);
+// The skill that owns each required review report.
+export const REVIEW_SKILLS = Object.freeze({ 'TP Review': 'task-plan-review', 'Clean Implementation Review': 'clean-implementation-review' });
 // `Clean Review` is the supported legacy name of the Clean Implementation Review row.
 export const reviewArtefactType = (state, step) => step === 'Clean Implementation Review' && !state.artefacts.get(step)?.path
   && state.artefacts.get('Clean Review')?.path ? 'Clean Review' : step;

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/gate-policy-pure.js

@@ -1,6 +1,6 @@
 import { extractField, verifiedChangeEscalationTargets } from "./gate-policy-inputs.js";
 import { gateApprovalStatus, gateArtefactStatus, isDurableGateArtefactSatisfied, isInternalStepSatisfied, modeSliceDecision } from "./run-state-policy.js";
-import { STRUCTURED_REQUIRED_REVIEWS, reviewArtefactType } from "./gate-policy-inputs.js";
+import { REVIEW_SKILLS, STRUCTURED_REQUIRED_REVIEWS, reviewArtefactType } from "./gate-policy-inputs.js";
 
 
 // Shared policy over prepared facts. The Core supplies its validated receipt reader;
@@ -310,8 +310,9 @@ function gateDecisionForRunState(runState, verifiedChange = null) {
   const acceptedPlanDeviation = runState.qa_acceptance?.eligible || runState.qa_acceptance?.accepted;
   const structuredBeforeQaApproval = ["structured_slice", "structured_delivery"].includes(modeSliceDecision(runState))
     && gateApprovalStatus(runState, "QA") !== "approved";
-  if (structuredBeforeQaApproval && STRUCTURED_REQUIRED_REVIEWS.some(step => !isInternalStepSatisfied(runState, reviewArtefactType(runState, step))
-        && !(step === "TP Review" && acceptedPlanDeviation && runState.artefacts.get(step)?.status === "revise"))) {
+  const pendingReview = structuredBeforeQaApproval && STRUCTURED_REQUIRED_REVIEWS.find(step => !isInternalStepSatisfied(runState, reviewArtefactType(runState, step))
+    && !(step === "TP Review" && acceptedPlanDeviation && runState.artefacts.get(step)?.status === "revise"));
+  if (pendingReview) {
     return {
       status: "open",
       current_gate: "QA",
@@ -320,6 +321,9 @@ function gateDecisionForRunState(runState, verifiedChange = null) {
       allowed: ["record TP Review and Clean Implementation Review", "run QA gate"],
       forbidden: ["request QA approval", "request UAT approval", "release", "claim delivery readiness"],
       next_allowed_action: "Record TP Review and Clean Implementation Review before requesting Approval: QA.",
+      // Names the review owed next so authoring offers that report's forms, not the QA report's.
+      next_operation: { type: "record_required_review", skill_id: REVIEW_SKILLS[pendingReview], operation_key: "review.record",
+        actor: "agent", effect: "preparation", gate: "QA", internal_step: pendingReview },
     };
   }
   // A QA report recorded before current evidence (for example reviews recorded after it)

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/prd-readiness.js

@@ -22,7 +22,8 @@ export function evaluatePrdReadiness(targetDir, runState, { presentationLanguage
     return { ready: false, open_decisions: ["Approval Decisions table is empty or malformed"] };
   }
   const open = [];
-  try { previewForState(targetDir, runState); } catch (error) { open.push(error.message); }
+  let previewReady = true, previewIssue;
+  try { previewForState(targetDir, runState); } catch (error) { previewReady = false; previewIssue = error.message; }
   const seen = new Set();
   const incomplete = (value) => !value || /^(?:<|tbd\b|to confirm\b)/iu.test(value);
   for (const [decision, timing, status, resolution, owner, ...extra] of rows.slice(2)) {
@@ -38,6 +39,8 @@ export function evaluatePrdReadiness(targetDir, runState, { presentationLanguage
   // [ \t] rather than \s: an empty Owner line must not capture the following line.
   const owner = content.match(/^Owner:[ \t]*(.*)$/mu)?.[1]?.trim();
   if (incomplete(owner) || /\bto confirm\b|named individual/iu.test(owner)) open.unshift("Named PRD owner");
+  const decisionsReady = open.length === 0;
+  if (!previewReady) open.unshift(previewIssue);
   const criteria = evaluatePrdCriteriaReadiness(content);
   open.push(...criteria.open_items);
   // Use the presentation owner's validator before a registered draft can take the ready route.
@@ -47,5 +50,7 @@ export function evaluatePrdReadiness(targetDir, runState, { presentationLanguage
   if (!summary.ready) open.push(renderApprovalSummaryIssue(summary, {
     path, presentationLanguage: languages.presentation_language,
   }));
-  return { ready: open.length === 0, open_decisions: open };
+  return { ready: open.length === 0, open_decisions: open,
+    readiness_checks: { decisions_ready: decisionsReady, preview_ready: previewReady, criteria_ready: criteria.ready,
+      approval_summary: summary } };
 }

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/report-decision.js

@@ -222,6 +222,15 @@ export function readAuthoredContent(text, profile, { locale, sourceLanguage } =
   return sections === 1 && (spec.paragraph ? lines.length : Object.keys(fields).length) ? spec.paragraph ? lines.join(' ') : fields : null;
 }
 
+// Authoring guidance owned next to the parser that enforces it. Only a level-1
+// title's metadata or a level-2 "Decision" section carries the result; a
+// "## Code Review" style heading closes the readable metadata block.
+export const REPORT_DECISION_FORMAT = Object.freeze({
+  section: '## Decision',
+  field: '- decision: <pass|revise|block>',
+  instruction: 'State the result in a level-2 "## Decision" section whose first line is "- decision: <value>". The value must equal the decision supplied when recording. A result under any other heading is not read.',
+});
+
 // Observe an authored technical result, never decide or approve QA. The closed
 // internal opt-in preserves analysis not_applicable; QA's domain stays unchanged.
 export function readReportDecision(text, { allowNotApplicable = false } = {}) {

package/generated/plugins/copilot/agdf/runtime/create-agdf/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/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/ur-readiness.js

@@ -37,10 +37,13 @@ export function evaluateUrContentReadiness(content, { languages, path = 'UR.md',
     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 summary = evaluateApprovalSummaryReadiness("UR", content, languages);
   if (!summary.ready) open.push(summary.required_heading);
@@ -48,5 +51,15 @@ export function evaluateUrContentReadiness(content, { languages, path = 'UR.md',
   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/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-inspect/artifact-readiness.js

@@ -9,7 +9,7 @@ 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';
@@ -26,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];
@@ -88,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' });