create-agdf 0.30.0 → 0.32.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/decision-content-placeholder.js

@@ -2,8 +2,11 @@
 // run inventory and other `node:`-free readers share the same rule.
 const prompts = new Set(['describe the trustworthy outcome.', 'what outcome should become possible?',
   'which tp tasks are fully done, partially done or not done?', 'what remains unverified?', 'which risks remain and what is their impact?']);
+// A bare generated Run ID (`run-<operation uuid>`) names the Run but states no outcome.
+const generatedRunId = /^run-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
 export function isDecisionContentPlaceholder(value) {
   if (typeof value !== 'string') return true;
   const text = value.trim().replace(/^`([^`]+)`$/u, '$1').replace(/\s+/gu, ' ').toLowerCase();
-  return !text || prompts.has(text) || /^(?:todo|tbd|<[^>]+>|(?:draft|done|ready|blocked|pass|revise|block)(?:\s*\|\s*(?:draft|done|ready|blocked|pass|revise|block))+)$/.test(text);
+  return !text || prompts.has(text) || generatedRunId.test(text)
+    || /^(?:todo|tbd|<[^>]+>|(?:draft|done|ready|blocked|pass|revise|block)(?:\s*\|\s*(?:draft|done|ready|blocked|pass|revise|block))+)$/.test(text);
 }

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";
@@ -158,7 +159,7 @@ export function isReadyUserGateApproval({ status, currentGate, missingApproval }
 
 function buildBreadcrumbPath(modeSliceDecision, currentGate, runState) {
   const gates = BREADCRUMB_PATH_TEMPLATES[modeSliceDecision] ?? ["UR"];
-  return gates.map((gate) => {
+  return gates.map((gate, index) => {
     if (BREADCRUMB_STANDARD_GATES.includes(gate)) {
       if (gateApprovalStatus(runState, gate) === "approved") return { gate, status: "fulfilled" };
       if (gate === currentGate) return { gate, status: "current" };
@@ -169,6 +170,10 @@ function buildBreadcrumbPath(modeSliceDecision, currentGate, runState) {
     if (gate === currentGate) return { gate, status: "current" };
     if ((gate === "Verified Change" || gate === "Compact Delivery") && currentGate === "OR")
       return { gate, status: "fulfilled" };
+    // A path has one current entry: while an earlier gate is still the current one (a stored route
+    // with an unapproved UR), the route entry after it is open, not current by its route.
+    if (gates.slice(0, index).some((earlier) => earlier === currentGate && gateApprovalStatus(runState, earlier) !== "approved"))
+      return { gate, status: "open" };
     if (gate === "Verified Change" && modeSliceDecision === "verified_change")
       return { gate, status: "current" };
     if (gate === "Compact Delivery" && modeSliceDecision === "quick_task")
@@ -427,31 +432,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 +494,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 +703,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' });