create-agdf 0.30.0 → 0.32.0

package/runtime/core/lib/companion/run-view.js

@@ -0,0 +1,227 @@
+// Companion run view (SD SDD-001, SDD-002): a read-only projection of the unchanged gate-check
+// report of each run, beside the run inventory of one project root. It never re-derives a gate
+// rule: status fields are copied from the status card verbatim, so every consumer of the run
+// view sees exactly what the status card shows. Nothing here writes or authorizes.
+import { existsSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { readFileSync, statSync } from '../control-read/fs.js';
+import { captureControlScope } from '../control-read/snapshot.js';
+import { containedRegularFile, hasSymlinkComponent, isSafeControlRelativePath } from '../control-state/contained-file.js';
+import { parseControlState } from '../control-state/run-state-parser.js';
+import { runIdentity } from '../control-state/run-title.js';
+import { localizedDecisionFields } from '../control-evaluation/decision-content-readiness.js';
+import { evaluateGateCheck } from '../control-evaluation/gate-check.js';
+import { readRunInventory } from '../control-state/run-inventory-reader.js';
+import { runFolderEntries } from '../control-state/run-state-reader.js';
+import { readArtefactBindings } from '../control-state/artefact-bindings.js';
+import { readEvidenceBindings } from '../control-state/evidence-bindings.js';
+import { runRelativePath } from '../control-state/run-identity.js';
+import { artefactFileDigest } from '../control-state/run-seal-compute.js';
+import { boundedCode } from '../control-inspect/run-classification.js';
+import { localizeBlockingCondition, localizeOperationalValue } from '../interaction-presentation.js';
+import { interactionLocales, resolveArtifactPresentationLanguages } from '../resources/context.js';
+import { deriveFigureState } from './figure-state.js';
+
+export const RUN_VIEW_SCHEMA = 'run-view/1';
+export const DIAGNOSIS_REASONS = Object.freeze(['run_version_unsupported', 'run_state_invalid', 'too_large', 'missing']);
+// The reader's findings for a run folder without a readable run state: the path finding of
+// run-state-reader.js (invalidRun) and the inventory's finding for a run without text (run-inventory.js).
+const MISSING_CODES = new Set(['AGDF_RUN_PATH_INVALID', 'AGDF_RUN_STATE_UNAVAILABLE']);
+// The classifications run-state-resolver.js treats as unsupported (AGDF_RUN_VERSION_UNSUPPORTED).
+const UNSUPPORTED_CLASSIFICATIONS = new Set(['unsupported_version', 'unsupported_layout']);
+
+// Per-run reason of an unreadable run (SD SDD-003) from the reader findings: unsupported by their
+// classification, as run-state-resolver.js and the cockpit decide it (CR finding CIR-03), missing
+// when only the missing-state findings are present, otherwise invalid. Core reports no size bound
+// of its own, so an oversized run state is reported with the reason Core gives it; too_large stays
+// reserved for such a bound (contradiction C1).
+export function diagnosisReason(findings) {
+  if (findings.some(finding => UNSUPPORTED_CLASSIFICATIONS.has(finding.classification))) return 'run_version_unsupported';
+  if (findings.length && findings.every(finding => MISSING_CODES.has(finding.code))) return 'missing';
+  return 'run_state_invalid';
+}
+
+export function projectDiagnosis(entries) {
+  const unreadable = entries.filter(entry => !entry.valid).map(entry => ({ run_id: entry.run_id, reason: entry.unreadable_reason ?? 'run_state_invalid', codes: entry.findings }));
+  const by_reason = Object.fromEntries(DIAGNOSIS_REASONS.map(reason => [reason, unreadable.filter(row => row.reason === reason).length]));
+  return { unreadable, counts: { unreadable: unreadable.length, readable: entries.length - unreadable.length, by_reason } };
+}
+
+const NAMING_TEXT_LIMIT = 500;
+const UR_READ_LIMIT = 131072;
+const bounded = value => (typeof value === 'string' && value.length > NAMING_TEXT_LIMIT ? `${value.slice(0, NAMING_TEXT_LIMIT - 1)}…` : value);
+
+// How a run names itself to a person, read inside the run's own snapshot: the stable title of the
+// shared Run title rule (registered UR heading, then the authored Objective; a bare Run ID is no
+// title) and the goal in the display language. Where display and artefact language differ, the goal
+// is the one the UR's localized approval summary states. An unreadable UR leaves both to the Run document.
+export function readRunNaming(root, runId, language = 'en') {
+  let content;
+  try { content = readFileSync(join(root, runRelativePath(runId, '', 'RUN_STATE.md')), 'utf8'); } catch { return null; }
+  let urHeading = '', localizedGoal = null;
+  try {
+    const path = String(parseControlState(content).artefacts.get('UR')?.path ?? '').replace(/^`|`$/gu, '').trim();
+    if (isSafeControlRelativePath(path) && path.startsWith('.agdf/control/') && !hasSymlinkComponent(root, path)) {
+      const file = containedRegularFile(root, path);
+      if (file.status === 'valid' && statSync(file.path).size <= UR_READ_LIMIT) {
+        const text = readFileSync(file.path, 'utf8');
+        urHeading = (text.match(/^#\s+(.+)$/mu)?.[1] ?? '').replace(/^UR:\s*/iu, '').trim();
+        const sourceLanguage = resolveArtifactPresentationLanguages(root, language).artifact_language;
+        localizedGoal = localizedDecisionFields('UR', text, { locale: String(language).split('-')[0], sourceLanguage, path }).fields.goal ?? null;
+      }
+    }
+  } catch (error) { if (error?.code === 'source_changed') throw error; }
+  const identity = runIdentity({ runId, runContent: content, urHeading });
+  return { run_title: identity.title_source === 'run_id' ? null : bounded(identity.title),
+    run_title_source: identity.title_source, goal: bounded(localizedGoal ?? identity.objective) };
+}
+
+// One run entry: inventory facts plus, when evaluated, the status card fields of its report.
+// `naming` is readRunNaming's result for an evaluated run; without it the inventory names the run.
+export function projectRunEntry(inventoryEntry, report, { registry = interactionLocales, language = 'en', naming = null } = {}) {
+  const authored = inventoryEntry.title_source === 'objective' ? inventoryEntry.title ?? null : null;
+  const base = {
+    run_id: inventoryEntry.run_id,
+    title: inventoryEntry.title ?? null,
+    // The stable human title, the same at every gate; null while only the Run ID could name the run.
+    run_title: naming ? naming.run_title : authored,
+    run_title_source: naming?.run_title_source ?? (authored ? 'objective' : 'run_id'),
+    // The goal in the display language where the UR states one, otherwise the authored objective.
+    goal: naming ? naming.goal : inventoryEntry.objective ?? null,
+    // The authored objective only, from the shared Run title rule; a template objective or a
+    // bare Run ID is no goal (CR finding C2).
+    objective: inventoryEntry.objective ?? null,
+    lifecycle: inventoryEntry.lifecycle ?? null,
+    valid: inventoryEntry.valid !== false,
+    revision: inventoryEntry.revision ?? null,
+    revision_id: inventoryEntry.revision_id ?? null,
+    last_activity: inventoryEntry.last_activity?.at ?? null,
+    findings: (inventoryEntry.findings ?? []).map(finding => finding.code),
+  };
+  if (!base.valid) base.unreadable_reason = diagnosisReason(inventoryEntry.findings ?? []);
+  // A run whose evaluation threw is reported with the bounded reason, never as an idle run (CR A7).
+  if (report?.evaluation_error) return withFigure({ ...base, evaluated: false, evaluation_error: report.evaluation_error });
+  if (!report?.status_card) return withFigure({ ...base, evaluated: false });
+  const card = report.status_card;
+  return withFigure({
+    ...base,
+    title: card.humanPresentation?.runTitle ?? base.title,
+    evaluated: true,
+    completion_confirmed: base.lifecycle === 'completed' && report.completion?.fulfilled === true,
+    status: card.status,
+    current_gate: card.current_gate,
+    path: card.breadcrumb.map(({ gate, status }) => ({ gate, status })),
+    missing_approval: card.missing_approval,
+    blocking_reason: card.blocking_condition,
+    blocking_text: localizeBlockingCondition(card.blocking_condition, { registry, requestedLocale: language }) ?? card.blocking_condition,
+    next_step: card.next_step,
+    next_step_text: localizeOperationalValue(card.next_step, { registry, requestedLocale: language }) ?? card.next_step,
+    user_action_required: card.user_action_required,
+    doctor_status: report.doctor_status,
+    mode: card.mode_slice_decision ?? card.mode ?? null,
+  });
+}
+const withFigure = entry => ({ ...entry, figure: deriveFigureState(entry) });
+
+// Pure assembly of the versioned view from already evaluated parts.
+export function projectRunView({ root, language, store, entries }) {
+  return {
+    schema_version: RUN_VIEW_SCHEMA,
+    root,
+    language,
+    store,
+    diagnosis: projectDiagnosis(entries.filter(entry => entry.listed !== false)),
+    runs: entries,
+    authorizes: false,
+  };
+}
+
+// Drift warnings (SD SDD-008, PRD AC-008): documents the run state binds with a recorded digest
+// (effective artefact binding destination, latest evidence report per path) whose file now has another
+// canonical digest from the node digest owner. Declared input files of a recording are not kept in
+// the run state, so only bound documents are compared (contradiction C5 of this run). An unreadable
+// run state yields no warning; the status card reports it.
+export function readRunDrift(root, runId) {
+  let content;
+  try { content = readFileSync(join(root, runRelativePath(runId, '', 'RUN_STATE.md')), 'utf8'); } catch { return []; }
+  const declared = new Map();
+  const artefacts = readArtefactBindings(content);
+  // A binding a recorded source revision invalidated is superseded for Core, so its document being
+  // re-drafted is no drift (CR finding A5).
+  for (const receipt of artefacts.valid ? artefacts.active ?? [] : []) {
+    declared.set(receipt.destination.path, { document: receipt.destination.type, digest: receipt.destination.digest });
+  }
+  const evidence = readEvidenceBindings(content);
+  for (const row of evidence.valid ? evidence.bindings : []) {
+    declared.set(row.report.path, { document: row.report.path.split('/').at(-1).replace(/\.md$/u, ''), digest: row.report.digest });
+  }
+  const drift = [];
+  for (const [path, { document, digest }] of declared) {
+    const current = artefactFileDigest(root, path);
+    if (current === digest) continue;
+    drift.push({ document, path, recorded_digest: digest, current_digest: /^sha256:/u.test(current) ? current : null });
+  }
+  return drift;
+}
+
+// Active runs are evaluated; terminal and unreadable runs are summarized unless requested by id, so
+// neither a large history nor many unreadable runs cost one evaluation per run. An unreadable run's
+// reason and figure come from the inventory findings.
+const needsEvaluation = (entry, requested) => requested.has(entry.run_id) || (entry.valid && entry.lifecycle === 'active');
+
+// A write that lands during a capture invalidates it (source_changed); the read is repeated a bounded
+// number of times before the change is reported (CR delta review RV-1).
+export const CAPTURE_ATTEMPTS = 3;
+export function captured(readRoot, project, capture = captureControlScope) {
+  for (let attempt = 1; ; attempt += 1) {
+    try { return capture(readRoot, view => project(view.root)).data; }
+    catch (error) { if (error?.code !== 'source_changed' || attempt >= CAPTURE_ATTEMPTS) throw error; }
+  }
+}
+
+// Reads inside bounded, revalidated control snapshots (TP T-002, SD section 4: captureControlScope,
+// CR finding CIR-01): the inventory in one snapshot and each evaluated run with its drift in its own,
+// so a read-boundary failure of one run (a linked file, a document outside the control folder, a read
+// limit) marks only that run and the readable runs stay listed (SDD-003, RV-2). The root is resolved
+// first, as MCP canonicalizes its target, so a junction or symlinked project root reads like its
+// target; the view keeps the caller's spelling (RV-3). A missing root has no control folder (RV-5).
+export function readRunView(root, { language = 'en', runIds = [] } = {}) {
+  const empty = store => projectRunView({ root, language, store, entries: [] });
+  if (!existsSync(root)) return empty({ status: 'no_control', reason: null });
+  let readRoot;
+  try { readRoot = realpathSync(root); } catch (error) { return empty({ status: 'unavailable', reason: boundedCode(error) }); }
+  const requested = new Set(runIds);
+  const evaluate = runId => {
+    try {
+      return captured(readRoot, base => {
+        const report = evaluateGateCheck(base, { runId, ignoreRunIdEnv: true, presentationLanguage: language });
+        return { report, drift: report?.status_card ? readRunDrift(base, runId) : null, naming: readRunNaming(base, runId, language) };
+      });
+    } catch (error) { return { report: { evaluation_error: boundedCode(error) }, drift: null, naming: null }; }
+  };
+  const entryOf = (inventoryEntry, evaluated) => {
+    const entry = projectRunEntry(inventoryEntry, evaluated?.report ?? null, { language, naming: evaluated?.naming ?? null });
+    return entry.evaluated && entry.valid !== false && evaluated.drift ? { ...entry, drift: evaluated.drift } : entry;
+  };
+  let inventory = null, store;
+  try {
+    inventory = captured(readRoot, base => readRunInventory(base, { language, observe: false }));
+    store = { status: inventory.state === 'absent' ? 'no_control' : 'ok', reason: null };
+  } catch (error) {
+    store = { status: 'unavailable', reason: boundedCode(error) };
+    // An unsupported layout lists no run, but its run folders can be counted, so a consumer names count
+    // and reason instead of "no open runs" (PRD AC-002, TP T-004). A failing count leaves the field out.
+    if (store.reason === 'control_layout_unsupported') {
+      try { store.run_folders = captured(readRoot, base => runFolderEntries(base).length); } catch { /* count unknown */ }
+    }
+  }
+  const listed = inventory?.runs ?? [];
+  const entries = listed.map(entry => entryOf(entry, needsEvaluation(entry, requested) ? evaluate(entry.run_id) : null));
+  for (const runId of requested) {
+    if (listed.some(entry => entry.run_id === runId)) continue;
+    // Requested but not listed by the inventory (for example behind an unsupported layout):
+    // evaluated for its card, never counted in the diagnosis of listed runs.
+    entries.push({ ...entryOf({ run_id: runId, findings: [] }, evaluate(runId)), valid: null, listed: false });
+  }
+  return projectRunView({ root, language, store, entries });
+}

package/runtime/core/lib/control-evaluation/acceptance-criteria.js

@@ -4,6 +4,8 @@ const CRITERION_ID = /^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*$/u;
 export const ACCEPTANCE_CRITERIA_FORMAT = Object.freeze({
   section: "Acceptance Criteria", declaration: "criterion_id: <stable id>",
   fields: "semicolon-separated inline fields or following bullet key: value lines",
+  description_fields: Object.freeze(["observable_success", "visible_feedback", "expected_effective_state"]),
+  description_rule: "For same-language approval rendering, provide at least one nonempty description field separately. Never concatenate field names or infer their meaning from combined keys.",
   id_pattern: CRITERION_ID.source,
   examples: Object.freeze([
     "## Acceptance Criteria\n- criterion_id: AC-001; observable_success: Saved choice remains selected",

package/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/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/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/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/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/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/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/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);