create-agdf 0.14.4 → 0.20.0

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

@@ -1,5 +1,10 @@
-import { extractField, verifiedChangeEscalationTargets } from './verified-change.js';
-import { gateApprovalStatus, gateArtefactStatus, isDurableGateArtefactSatisfied, isInternalStepSatisfied, modeSliceDecision } from './run-state.js';
+import { extractField, verifiedChangeEscalationTargets } from "./verified-change.js";
+import { gateApprovalStatus, gateArtefactStatus, isDurableGateArtefactSatisfied, isInternalStepSatisfied, modeSliceDecision } from "./run-state-policy.js";
+import { readSourceRevisions } from "../control-state/run-source-revisions.js";
+import { STRUCTURED_REQUIRED_REVIEWS, reviewArtefactType } from "../control-state/evidence-bindings.js";
+
+// Compatible display text. Execution consumes the semantic operation, never this sentence.
+export const CD_TESTS_NEXT_ALLOWED_ACTION = "Implement the approved TP scope, run its tests, and record CD+Tests evidence before CR.";
 
 function durableArtefactBlock(gate, nextGate) {
   const label = gate === "QA" ? "QA report" : `${gate} artefact`;
@@ -34,7 +39,7 @@ function qaNonPassDecision(runState) {
   return status === "revise" || status === "block" ? status : null;
 }
 
-export function transitionDecisionForRunState(runState, verifiedChange = null) {
+function gateDecisionForRunState(runState, verifiedChange = null) {
   if (gateApprovalStatus(runState, "UR") === "approved" && !isGateSatisfied(runState, "UR")) return durableArtefactBlock("UR", "PRD");
 
   if (!isGateSatisfied(runState, "UR")) {
@@ -44,14 +49,36 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
       blocking_reason: "none",
       missing_approval: "Approval: UR",
       allowed: ["clarify user need", "formulate and persist UR", "record evidence", "request exact UR approval"],
-      forbidden: ["create PRD", "create SD", "create TP", "run Brownfield Analysis", "implement code", "claim QA or release readiness"],
-      next_allowed_action: "Clarify the user requirement, persist the UR, and request exact approval: Approval: UR",
+      forbidden: ["create later-gate artefacts beyond the current allowed gate", "run Brownfield Analysis as implementation preparation", "implement code", "claim QA or release readiness"],
+      next_allowed_action: "Fill the current UR control state, persist the UR draft, and request exact approval: Approval: UR.",
     };
   }
 
   if (gateApprovalStatus(runState, "PRD") === "approved" && !isGateSatisfied(runState, "PRD")) return durableArtefactBlock("PRD", "SD");
 
-  if (!isGateSatisfied(runState, "PRD")) {
+  const revision = readSourceRevisions(runState.content ?? "").receipts.at(-1);
+  const reassessment = type => revision?.analyses.some(row => row.type === type && row.disposition === "reassess");
+  const renewedBrownfield = reassessment("Brownfield Review") && (!isInternalStepSatisfied(runState, "Brownfield Review")
+    || !["structured_slice", "structured_delivery"].includes(modeSliceDecision(runState)));
+  if (renewedBrownfield && revision.source_gate !== "UR" && isInternalStepSatisfied(runState, "Brownfield Review")
+      && !["undecided", "structured_slice", "structured_delivery"].includes(modeSliceDecision(runState))) {
+    return { status: "blocked", current_gate: "Mode/Slice Decision", blocking_reason: "mode_slice_decision_blocked", missing_approval: "none",
+      allowed: ["resolve the analytical route under the retained approved UR"], forbidden: ["implement code", "skip renewed source approvals"],
+      next_allowed_action: "Resolve the Brownfield Review blocker before choosing a delivery path." };
+  }
+  if ((reassessment("UX Intent Definition") || runState.source_revision_ux_required) && !isInternalStepSatisfied(runState, 'UX Intent Definition')
+      && isInternalStepSatisfied(runState, "Brownfield Review") && ["structured_slice", "structured_delivery"].includes(modeSliceDecision(runState))) {
+    return {
+      status: "open", current_gate: revision.source_gate === "UR" ? "PRD" : revision.source_gate,
+      blocking_reason: "none", missing_approval: "none",
+      allowed: ["reassess UX intent under the current approved UR and reviewed analytical context", "record the renewed analysis before dependent authoring"],
+      forbidden: ["draft or approve a dependent source before analytical reassessment", "implement code", "claim QA or release readiness"],
+      next_allowed_action: "Reassess UX intent under the current approved UR before dependent source authoring.",
+      next_operation: { type: "reassess_source_analysis", skill_id: "ux-intent-definition", analysis: "UX Intent Definition" },
+    };
+  }
+
+  if (!isGateSatisfied(runState, "PRD") || renewedBrownfield) {
     if (!isInternalStepSatisfied(runState, "Brownfield Review")) {
       return {
         status: "open",
@@ -113,6 +140,13 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
           next_allowed_action: "Use delivery closeout only when an operative VCS handoff is explicitly requested.",
         };
       }
+      if (isInternalStepSatisfied(runState, "CR")) return {
+        status: "open", current_gate: "Quick Task Execution", blocking_reason: "none", missing_approval: "none",
+        allowed: ["produce OR or delivery closeout"],
+        forbidden: ["repeat Quick Task execution", "commit, push, open PR or release automatically"],
+        next_allowed_action: "Produce delivery closeout or requested handoff; do not perform VCS actions automatically.",
+        next_operation: { type: "record_closeout", skill_id: "release-or", operation_key: "closeout.record", actor: "agent", effect: "closeout", gate: "Quick Task Execution" },
+      };
       return {
         status: "open",
         current_gate: "Quick Task Execution",
@@ -121,6 +155,7 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
         allowed: ["implement the narrow approved UR scope", "run relevant checks", "record evidence and close with OR-lite"],
         forbidden: ["expand scope beyond the Brownfield Review decision", "create broad PRD/SD/TP artefacts by ritual", "claim QA or release readiness without evidence"],
         next_allowed_action: "Proceed as a Quick Task within the Brownfield Review scope and record verification evidence.",
+        next_operation: { type: "implement_compact_scope", skill_id: "gate-check", operation_key: "implementation.execute", actor: "agent", effect: "implementation", gate: "Quick Task Execution" },
       };
     }
 
@@ -158,6 +193,7 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
           allowed: ["implement only declared source and derived paths", "run declared propagation and validation commands", "record execution evidence and mini-closeout"],
           forbidden: ["touch unlisted paths", "add prohibited impacts", "claim QA, UAT or release readiness"],
           next_allowed_action: "Implement only the eligible Verified Change record scope, then record passing propagation and validation evidence.",
+          next_operation: { type: "implement_compact_scope", skill_id: "gate-check", operation_key: "implementation.execute", actor: "agent", effect: "implementation", gate: "Verified Change Execution" },
         };
       }
       return {
@@ -167,7 +203,7 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
         missing_approval: "none",
         allowed: ["create or refine the compact Verified Change record", "capture baseline paths", "prove fail-closed eligibility with doctor and gate-check"],
         forbidden: ["implement candidate changes", "claim validation, QA, UAT or release readiness"],
-        next_allowed_action: "Create or repair VERIFIED_CHANGE.md, capture the baseline and satisfy every eligibility check before implementation; escalate when any condition cannot be proven.",
+        next_allowed_action: "Create or repair VERIFIED_CHANGE.md, capture the baseline and satisfy every eligibility check before implementation; escalate if any condition is unproven.",
       };
     }
 
@@ -233,7 +269,7 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
       missing_approval: "none",
       allowed: ["implement the approved TP tasks", "run the approved test plan", "record implementation and test evidence"],
       forbidden: ["claim QA pass", "request UAT approval", "release"],
-      next_allowed_action: "Implement the approved TP scope, run its tests, and record CD+Tests evidence before CR.",
+      next_allowed_action: CD_TESTS_NEXT_ALLOWED_ACTION,
     };
   }
 
@@ -250,7 +286,7 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
   }
 
   const qaNonPass = qaNonPassDecision(runState);
-  if (qaNonPass) {
+  if (qaNonPass && !runState.qa_acceptance?.eligible) {
     const blocked = qaNonPass === "block";
     return {
       status: blocked ? "blocked" : "open",
@@ -262,11 +298,43 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
         : ["revise the implementation against the QA findings", "refresh CD+Tests and mandatory reviews", "rerun QA with refreshed evidence"],
       forbidden: ["request QA approval", "request UAT approval", "release", "claim delivery readiness"],
       next_allowed_action: blocked
-        ? "Resolve or route the blocking QA findings through their authoritative owner, then rerun the required delivery steps. Do not request Approval: QA from a block report."
+        ? "Resolve or route the blocking QA findings via their authoritative owner, then rerun the required steps. Do not request Approval: QA from a block report."
         : "Resolve the QA revise findings, refresh CD+Tests and reviews, then rerun QA. Do not request Approval: QA from a revise report.",
     };
   }
 
+  // The qa-gate forbids a QA pass without review evidence and closeout requires both
+  // reviews. Until they are recorded the QA approval request is withheld.
+  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"))) {
+    return {
+      status: "open",
+      current_gate: "QA",
+      blocking_reason: "none",
+      missing_approval: "none",
+      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.",
+    };
+  }
+  // A QA report recorded before current evidence (for example reviews recorded after it)
+  // would stay stale through closeout; QA is rerun before its approval request.
+  const qaAssociation = runState.evidence_applicability?.by_step.get("QA");
+  if (structuredBeforeQaApproval && runState.artefacts.get("QA")?.path && qaAssociation && qaAssociation.applicability !== "current") {
+    return {
+      status: "open",
+      current_gate: "QA",
+      blocking_reason: "none",
+      missing_approval: "none",
+      allowed: ["run QA gate", "persist or refine the QA report"],
+      forbidden: ["request QA approval", "request UAT approval", "release", "claim delivery readiness"],
+      next_allowed_action: "Rerun QA against the current evidence before requesting Approval: QA.",
+    };
+  }
+
   if (gateApprovalStatus(runState, "QA") === "approved" && !isGateSatisfied(runState, "QA")) return durableArtefactBlock("QA", "UAT");
 
   if (isGateSatisfied(runState, "QA") && !isGateSatisfied(runState, "UAT")) {
@@ -303,3 +371,66 @@ export function transitionDecisionForRunState(runState, verifiedChange = null) {
     next_allowed_action: "Run the QA gate, persist the QA report, and request exact approval: Approval: QA",
   };
 }
+
+// The same policy supplies machine meaning and compatible prose. These operations
+// describe eligibility; they are neither user approval nor an invocation authority.
+function semanticOperation(decision) {
+  if (decision.next_operation) return { ...decision.next_operation,
+    operation_key: decision.next_operation.operation_key ?? decision.next_operation.type,
+    actor: decision.next_operation.actor ?? "agent", effect: decision.next_operation.effect ?? "preparation" };
+  if (decision.status === "blocked") return { type: "resolve_control_blocker", operation_key: "control.resolve",
+    actor: "agent", effect: "none", gate: decision.current_gate };
+  const key = {
+    "Brownfield Review": ["analyse_existing_system", "brownfield-analysis", "analysis.brownfield_review", "preparation"],
+    "Mode/Slice Decision": ["resolve_delivery_route", "brownfield-analysis", "analysis.route", "preparation"],
+    "Brownfield Analysis": ["prepare_implementation", "brownfield-analysis", "analysis.brownfield_implementation", "preparation"],
+    "CD+Tests": ["implement_approved_plan", "gate-check", "implementation.execute", "implementation"],
+    "CR": ["review_implementation", "code-review", "review.code", "preparation"],
+    "QA": ["evaluate_quality", "qa-gate", "quality.evaluate", "preparation"],
+    "OR": ["record_closeout", "release-or", "closeout.record", "closeout"],
+  }[decision.current_gate];
+  if (key) return { type: key[0], skill_id: key[1], operation_key: key[2], actor: "agent", effect: key[3], gate: decision.current_gate };
+  if (decision.current_gate === "UAT") return { type: "human_gate_decision", operation_key: "approval.record",
+    actor: "human", effect: "decision", gate: "UAT" };
+  if (["UR", "PRD", "SD", "TP"].includes(decision.current_gate)) return { type: "author_gate_artifact",
+    operation_key: "artefact.author", actor: "agent", effect: "preparation", gate: decision.current_gate };
+  return { type: "resolve_control_state", operation_key: "control.resolve", actor: "agent", effect: "none", gate: decision.current_gate };
+}
+
+export function transitionDecisionForRunState(runState, verifiedChange = null) {
+  const decision = gateDecisionForRunState(runState, verifiedChange);
+  const lifecycle = extractField(runState.content ?? "", "lifecycle") || runState.meta?.lifecycle || "unknown";
+  if (runState.approval_material_findings?.length) return { ...decision, status: 'blocked', missing_approval: 'none', blocking_reason: 'approved_material_sources_changed',
+    allowed: ['inspect the changed approved sources through their existing revision/recovery owner'], forbidden: [...decision.forbidden, 'continue from an unconfirmed old approval'],
+    next_allowed_action: 'Resolve the changed approved material through its existing source/recovery owner; do not infer a fresh approval.',
+    next_operation: { type: 'resolve_control_blocker', operation_key: 'control.resolve', actor: 'agent', effect: 'none', gate: decision.current_gate },
+    completion: { status: lifecycle === 'completed' ? 'unconfirmed' : 'pending', gate: 'OR', fulfilled: false } };
+  if (lifecycle === "completed") {
+    const or = runState.artefacts.get("OR");
+    const route = modeSliceDecision(runState);
+    const fulfilled = decision.current_gate === "OR" && decision.status !== "blocked"
+      && or?.status === "done" && Boolean(or.path)
+      && (route === 'verified_change' ? verifiedChange?.status === 'executed' : runState.closeout_evidence?.ready === true)
+      && ["structured_slice", "structured_delivery", "quick_task", "verified_change"].includes(route);
+    if (fulfilled) return { ...decision, status: "pass", missing_approval: "none", blocking_reason: "none",
+      allowed: ["prepare an explicitly requested VCS handoff"], forbidden: ["repeat completed Run work", "perform VCS or release actions automatically"],
+      next_allowed_action: "Run completed; prepare a VCS handoff only when explicitly requested.",
+      next_operation: null, completion: { status: "completed", gate: "OR", fulfilled: true, vcs_handoff: "explicit_request_required" } };
+    return { ...decision, status: "blocked", missing_approval: "none", blocking_reason: "completed_run_obligations_unconfirmed",
+      allowed: ["inspect the inconsistent completion and route it to its existing recovery owner"],
+      forbidden: ["repeat completed work automatically", "claim clean completion", "perform VCS or release actions automatically"],
+      next_allowed_action: "Resolve the inconsistent completed Run obligations before claiming a clean closeout.",
+      next_operation: { type: "resolve_control_blocker", operation_key: "control.resolve", actor: "agent", effect: "none", gate: decision.current_gate },
+      completion: { status: "unconfirmed", gate: "OR", fulfilled: false } };
+  }
+  const decided = runState.presentation_decisions?.get(decision.current_gate);
+  if (decided?.decided && runState.approvals.get(decision.current_gate)?.status !== 'approved') return { ...decision,
+    blocking_reason: decided.reason ?? 'presentation_version_decided', missing_approval: 'none', presentation_decision: decided,
+    allowed: ['revise the current material through its existing authoring or remediation owner'],
+    forbidden: [...decision.forbidden, 'approve unchanged decided material', 'invalidate approved upstream sources without supported revision'],
+    next_allowed_action: 'Revise the decided material through its existing owner, register the changed version and obtain a fresh presentation and deliberate decision.',
+    next_operation: { type: 'revise_gate_material', operation_key: 'artefact.author', actor: 'agent', effect: 'preparation', gate: decision.current_gate, skill_id: decided.owner },
+    completion: { status: 'pending', gate: 'OR', fulfilled: false } };
+  return { ...decision, next_operation: semanticOperation(decision),
+    completion: { status: "pending", gate: "OR", fulfilled: false } };
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/markdown-table.js

@@ -0,0 +1,40 @@
+// Shared bounded table observation; callers retain their own semantic policy.
+export function section(markdown, title) {
+  const lines = markdown.replace(/\r\n?/gu, "\n").split("\n");
+  const wanted = title.toLowerCase();
+  const start = lines.findIndex((line) => {
+    const heading = line.match(/^#{2,6}\s+(?:\d+\.\s*)?(.+?)\s*#*\s*$/u);
+    return heading?.[1]?.trim()?.toLowerCase() === wanted;
+  });
+  if (start < 0) return null;
+  const level = (lines[start].match(/^#+/u) ?? [""])[0].length;
+  let end = start + 1;
+  while (end < lines.length) {
+    const next = lines[end].match(/^(#{2,6})\s+/u);
+    if (next && next[1].length <= level) break;
+    end += 1;
+  }
+  return lines.slice(start + 1, end).join("\n");
+}
+
+export function tableRows(markdown, title, requiredColumns) {
+  const body = section(markdown, title);
+  if (body === null) return { rows: [], error: `${title} section is missing` };
+  const lines = body.split("\n");
+  for (let index = 0; index < lines.length - 1; index += 1) {
+    const headerLine = lines[index].trim();
+    if (!headerLine.startsWith("|") || !/^\|?[\s:|-]+\|?$/u.test(lines[index + 1].trim())) continue;
+    const headers = headerLine.replace(/^\||\|$/gu, "").split("|").map((cell) => cell.trim().toLowerCase().replace(/[^a-z0-9]+/gu, "_").replace(/^_|_$/gu, ""));
+    if (!requiredColumns.every((column) => headers.includes(column))) continue;
+    const rows = [];
+    for (let cursor = index + 2; cursor < lines.length; cursor += 1) {
+      const line = lines[cursor].trim();
+      if (!line.startsWith("|")) break;
+      if (/^\|?[\s:|-]+\|?$/u.test(line)) continue;
+      const cells = line.replace(/^\||\|$/gu, "").split("|").map((cell) => cell.trim().replace(/^`|`$/gu, ""));
+      rows.push(Object.fromEntries(headers.map((header, cellIndex) => [header, cells[cellIndex] ?? ""])));
+    }
+    return { rows, error: null };
+  }
+  return { rows: [], error: `${title} table is missing or malformed` };
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/next-action.js

@@ -0,0 +1,32 @@
+import { localePack } from "../interaction-presentation.js";
+import { interactionLocales } from "../resources/context.js";
+import { isPlaceholderValue } from "./shared.js";
+import { extractField } from "./verified-change.js";
+
+// Canonical order of the gates the transition policy reports; alternative compact paths sit
+// between routing and PRD.
+const GATE_ORDER = ["UR", "Brownfield Review", "Mode/Slice Decision", "Quick Task Execution", "Verified Change Execution",
+  "PRD", "SD", "TP", "Brownfield Analysis", "CD+Tests", "CR", "QA", "UAT", "OR"];
+const gateIndex = (value) => GATE_ORDER.indexOf(String(value ?? "").replace(/`/gu, "").trim());
+// Every system-generated next step is a registered operational value; hand-authored text is not.
+const CANONICAL_TEXTS = new Set(Object.values(localePack(interactionLocales, "en").operationalValues ?? {}).map((value) => String(value).trim()));
+
+// True when an active run still stores a generated next step of an earlier gate, for example after
+// an internal step was recorded without refreshing the derived control fields. Backward moves,
+// unknown gates and hand-authored text keep the stored next step (fail closed).
+export function storedNextActionStale(runState, decision) {
+  if (extractField(runState.content ?? "", "lifecycle") !== "active") return false;
+  const stored = gateIndex(runState.current_gate), evaluated = gateIndex(decision.current_gate);
+  if (stored < 0 || evaluated <= stored) return false;
+  const text = String(runState.next_allowed_action ?? "").trim();
+  return CANONICAL_TEXTS.has(text) && text !== decision.next_allowed_action;
+}
+
+// A stored next step refines the evaluated gate unless it is a stale generated step.
+export function storedNextActionApplies(runState, decision) {
+  return !isPlaceholderValue(runState.next_allowed_action) && !storedNextActionStale(runState, decision);
+}
+
+export function effectiveNextAllowedAction(runState, decision) {
+  return storedNextActionApplies(runState, decision) ? runState.next_allowed_action : decision.next_allowed_action;
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/normalized-gaps.js

@@ -0,0 +1,105 @@
+import { readRuntimeContract } from '../resources/contracts.js';
+import { cleanStatusCell } from './shared.js';
+import { extractField } from './verified-change.js';
+// Consume the sole normative route table rather than introduce a second type-to-route map.
+export function declaredRoutes() {
+  const contract = readRuntimeContract('quality');
+  if (!contract.ok) return new Map();
+  const text = contract.content;
+  const body = text.split('## Normalized Review Gaps')[1]?.split(/^## /mu)[0] ?? '';
+  const routes = new Map();
+  for (const line of body.split('\n')) {
+    const row = line.match(/^\|\s*`([a-z_]+)`\s*\|[^|]*\|(.+)\|\s*$/u);
+    if (!row) continue;
+    const targets = [...row[2].matchAll(/`([^`]+)`/gu)].flatMap(m => m[1].split('|').map(v => v.trim()));
+    routes.set(row[1], targets);
+  }
+  return routes;
+}
+
+export const NORMALIZED_GAP_COLUMNS = Object.freeze(['finding_id', 'gap_type', 'routing_target', 'gap_status', 'evidence', 'required_next_step']);
+const PLACEHOLDER = /^(?:none|tbd|todo|<)/iu, ACTION_PLACEHOLDER = /^(?:tbd|todo|<)/iu;
+
+// Field-level form of the contract rules, each with a stable rule id; an empty list is a valid row.
+export function normalizedGapProblems(row, routes = declaredRoutes()) {
+  if (row.length !== NORMALIZED_GAP_COLUMNS.length) return [{ field: 'row', expected: `the columns ${NORMALIZED_GAP_COLUMNS.join(' | ')}`, rule: 'row_cells' }];
+  const [id, gap, target, status, evidence, action] = row, problems = [];
+  // Resolved rows retain their classification and concrete resolution evidence, but do not
+  // route new corrective work: action and assessment obligations apply to open findings.
+  const open = status === 'open';
+  const add = (field, expected, rule = field) => problems.push({ field, expected, rule });
+  if (routes.size !== 6) add('gap_type', 'the Normalized Review Gaps contract to be readable', 'contract');
+  if (!id || id.length > 128) add('finding_id', 'a stable id of at most 128 characters');
+  if (!routes.has(gap)) add('gap_type', `one of ${[...routes.keys()].join(', ')}`);
+  else if (!routes.get(gap).includes(target)) add('routing_target', `one of ${routes.get(gap).join(', ')} for ${gap}`);
+  if (!['open', 'resolved'].includes(status)) add('gap_status', 'open or resolved');
+  if (!evidence || evidence.length > 4096 || PLACEHOLDER.test(evidence)) add('evidence', 'concrete source, test, observation or missing proof, not none, tbd, todo or a placeholder');
+  if (!action || action.length > 2048 || ACTION_PLACEHOLDER.test(action) || open && /^none(?:\b|$)/iu.test(action)) add('required_next_step', 'exactly one executable action for an open finding (a resolved finding may state none), not tbd, todo or a placeholder');
+  if (gap === 'requirements_gap' && target === 'UR' && !/changed (?:user )?(?:intent|scope)/iu.test(evidence)) add('evidence', 'evidence of changed user intent or scope for a requirements_gap routed to UR', 'requirements_gap_ur');
+  if (open && gap === 'emergent_risk' && !/earliest[- ]owner assessment/iu.test(evidence)) add('evidence', 'an explicit earliest-owner assessment for an open emergent_risk', 'emergent_risk_assessment');
+  return problems;
+}
+
+export function validNormalizedGap(row, routes = declaredRoutes()) {
+  return normalizedGapProblems(row, routes).length === 0;
+}
+
+// Table entries in document order; the scan stops at the first malformed header or row, so
+// consumers that stop at the first problem keep their order of findings.
+export function readNormalizedFindings(content) {
+  const entries = [];
+  let active = false, header = false;
+  for (const line of String(content ?? '').split('\n')) {
+    if (!line.trim().startsWith('|')) { active = false; continue; }
+    if (/^\|(?:\s*:?-+:?\s*\|)+\s*$/u.test(line.trim())) continue;
+    const row = line.trim().replace(/^\||\|$/gu, '').split('|').map(cleanStatusCell);
+    if (row.includes('finding_id') || row.filter(cell => NORMALIZED_GAP_COLUMNS.includes(cell)).length > 1) {
+      if (row.join('|') !== NORMALIZED_GAP_COLUMNS.join('|')) { entries.push({ kind: 'malformed_header', row }); break; }
+      active = true; header = true; continue;
+    }
+    if (!active) continue;
+    if (row.length !== NORMALIZED_GAP_COLUMNS.length) { entries.push({ kind: 'malformed_row', row }); break; }
+    entries.push({ kind: 'row', row });
+  }
+  return { header, entries };
+}
+
+// Per-source rules that closeout and the QA follow-up apply (inspectQaReports), as a full list
+// of diagnostics so a writer can refuse a review or QA report before anything depends on it.
+export function reviewFindingDiagnostics(review, content, { decision, routes = declaredRoutes() } = {}) {
+  const diagnostics = [], ids = new Set();
+  const add = (finding_id, field, expected, rule) => diagnostics.push({ review, finding_id, field, expected, rule });
+  const scan = readNormalizedFindings(content);
+  for (const entry of scan.entries) {
+    if (entry.kind === 'malformed_header') add(null, 'table', `the header | ${NORMALIZED_GAP_COLUMNS.join(' | ')} |`, 'table_header');
+    else if (entry.kind === 'malformed_row') add(entry.row[0] || null, 'row', `${NORMALIZED_GAP_COLUMNS.length} cells per finding row`, 'row_cells');
+    else {
+      const id = entry.row[0];
+      if (ids.has(id)) add(id, 'finding_id', 'a finding id used only once', 'duplicate_id');
+      ids.add(id);
+      for (const problem of normalizedGapProblems(entry.row, routes)) add(id || null, problem.field, problem.expected, problem.rule);
+    }
+  }
+  const stated = ['revise', 'block'].includes(decision) || review === 'QA' && decision && decision !== 'pass' ? decision : extractField(content, 'decision');
+  if ((!scan.header || !ids.size) && ['revise', 'block'].includes(stated)) {
+    add(null, 'table', `a normalized findings table with at least one finding for a ${stated} decision`, 'findings_missing');
+  }
+  return diagnostics;
+}
+
+// The content with the required_next_step cell of the named findings blanked: exactly the cell
+// a correction at OR may change (run-operation-proof.js). Invisible trailing whitespace of lines
+// and of the file is not content.
+export function maskFindingCells(content, ids) {
+  let active = false;
+  return String(content ?? '').replace(/\r\n?/gu, '\n').trimEnd().split('\n').map(rawLine => {
+    const line = rawLine.trimEnd();
+    if (!line.trim().startsWith('|')) { active = false; return line; }
+    if (/^\|(?:\s*:?-+:?\s*\|)+\s*$/u.test(line.trim())) return line;
+    const row = line.trim().replace(/^\||\|$/gu, '').split('|').map(cleanStatusCell);
+    if (row.includes('finding_id') || row.filter(cell => NORMALIZED_GAP_COLUMNS.includes(cell)).length > 1) {
+      active = row.join('|') === NORMALIZED_GAP_COLUMNS.join('|');
+      return line;
+    }
+    return active && row.length === NORMALIZED_GAP_COLUMNS.length && ids.has(row[0]) ? `| ${row.slice(0, 5).join(' | ')} | * |` : line;
+  }).join('\n');}

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

@@ -0,0 +1,51 @@
+import { readFileSync } from "../control-read/fs.js";
+import { resolvedArtefactFile } from "./run-state.js";
+import { evaluatePrdCriteriaReadiness } from "./traceability-readiness.js";
+import { resolveArtifactPresentationLanguages } from "../resources/context.js";
+import { evaluateApprovalSummaryReadiness, renderApprovalSummaryIssue } from "../control-state/run-presentation-render.js";
+import { previewForState } from '../control-state/preview-review.js';
+
+export const PRD_DECISION_FORMAT = Object.freeze({ section: "Approval Decisions", columns: Object.freeze(["Decision", "Timing", "Status", "Resolution", "Owner"]),
+  timings: Object.freeze(["before_prd", "later_sd", "later_tp"]), statuses: Object.freeze(["resolved", "open", "deferred"]), owner_field: "Owner:" });
+
+// PRD product decisions are explicit data. Free-form risk prose cannot safely establish
+// whether a decision was resolved before the user saw an approval card.
+export function evaluatePrdReadiness(targetDir, runState, { presentationLanguage } = {}) {
+  const path = resolvedArtefactFile(targetDir, runState.artefacts.get("PRD")?.path);
+  if (!path) return { ready: false, open_decisions: ["PRD artefact is missing"] };
+  const content = readFileSync(path, "utf8");
+  const section = content.split(/^## Approval Decisions\s*$/mu)[1]?.split(/^## /mu)[0];
+  if (!section) return { ready: false, open_decisions: ["Approval Decisions section is missing"] };
+  const rows = section.split(/\r?\n/u).filter((line) => line.trim().startsWith("|"))
+    .map((line) => line.split("|").slice(1, -1).map((cell) => cell.trim()));
+  if (rows.length < 3 || rows[0].join("|") !== PRD_DECISION_FORMAT.columns.join("|")) {
+    return { ready: false, open_decisions: ["Approval Decisions table is empty or malformed"] };
+  }
+  const open = [];
+  try { previewForState(targetDir, runState); } catch (error) { open.push(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)) {
+    if (!decision || seen.has(decision) || extra.length || !PRD_DECISION_FORMAT.timings.includes(timing)
+        || !PRD_DECISION_FORMAT.statuses.includes(status)) {
+      open.push(decision || "Malformed decision row");
+      continue;
+    }
+    seen.add(decision);
+    if (incomplete(owner) || (timing === "before_prd" && (status !== "resolved" || incomplete(resolution)))
+        || (timing !== "before_prd" && incomplete(resolution))) open.push(decision);
+  }
+  // [ \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 criteria = evaluatePrdCriteriaReadiness(content);
+  open.push(...criteria.open_items);
+  // Use the presentation owner's validator before a registered draft can take the ready route.
+  // This keeps an own, unapproved formatting correction with the existing PRD authoring owner.
+  const languages = resolveArtifactPresentationLanguages(targetDir, presentationLanguage);
+  const summary = evaluateApprovalSummaryReadiness("PRD", content, languages);
+  if (!summary.ready) open.push(renderApprovalSummaryIssue(summary, {
+    path, presentationLanguage: languages.presentation_language,
+  }));
+  return { ready: open.length === 0, open_decisions: open };
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/qa-follow-up.js

@@ -0,0 +1,83 @@
+import { readFileSync } from '../control-read/fs.js';
+import { containedRegularFile, hasSymlinkComponent } from '../control-state/contained-file.js';
+import { posix } from 'node:path';
+import { extractField } from './verified-change.js';
+import { declaredRoutes, normalizedGapProblems, readNormalizedFindings } from './normalized-gaps.js';
+import { isGateSatisfied } from './gate-policy.js';
+import { isInternalStepSatisfied } from './run-state-policy.js';
+import { createHash } from 'node:crypto';
+import { readReportDecision } from './report-decision.js';
+
+// Review reports a QA report references explicitly; they are inspected like recorded reviews.
+export function qaReportReferences(content, qaPath) {
+  const refs = [...content.matchAll(/\[([^\]]+)\]\(([^)]+)\)/gu)].filter(m => /review|\bCR\b/iu.test(m[1] + ' ' + m[2]) && /\.md(?:#.*)?$/iu.test(m[2])).map(m => [m[1], m[2].split('#')[0]]);
+  for (const m of content.matchAll(/^- (tp_review|clean_implementation_review|code_review):[ \t]*`?([^`\r\n]+)`?[ \t]*$/gmu)) refs.push([m[1], m[2].trim()]);
+  return refs.map(([label, ref]) => ({ type: `QA reference: ${label}`, path: ref.startsWith('.agdf/') ? ref : posix.join(posix.dirname(qaPath), ref) }));
+}
+
+export function evaluateQaFollowUp(root, state, runId, maxSources = Infinity, strictUtf8 = false) {
+  const stop = reason => ({ kind: 'blocked', reason, findings: [], sources: [] });
+  if (!['UR', 'PRD', 'SD', 'TP'].every(gate => isGateSatisfied(state, gate))
+      || !['Brownfield Analysis', 'CD+Tests', 'CR'].every(step => isInternalStepSatisfied(state, step))) return stop('Current approved sources and completed implementation/reviews are required.');
+  const qa = state.artefacts.get('QA');
+  if (qa?.status !== 'revise') return stop('Only the current revise report permits this follow-up.');
+  return inspectQaReports(root, state, runId, 'revise', maxSources, strictUtf8);
+}
+
+// Shared registered-source and normalized-finding validation. Only the wrapper above routes
+// corrective work; pass/block observations here cannot approve or revoke a gate.
+// `proposed` maps run artefact paths to the content a pending write publishes, so a projection of
+// the committed state reads it instead of the current file.
+export function inspectQaReports(root, state, runId, expectedDecision, maxSources = Infinity, strictUtf8 = false, { readArtefact, proposed } = {}) {
+  const observations = [];
+  const stop = reason => ({ kind: 'blocked', reason, findings: [], sources: observations });
+  const routes = declaredRoutes();
+  if (routes.size !== 6) return stop('Normalized review-gap contract is unavailable.');
+  const findings = [], reports = new Set();
+  const sources = ['QA', 'TP Review', 'Clean Implementation Review', 'Clean Review', 'CR', 'Code Review'].map(type => ({ type, ...state.artefacts.get(type) }));
+  for (const artefact of sources) {
+    const { type } = artefact;
+    const path = String(artefact.path ?? '').replace(/^`|`$/gu, '');
+    if (!path) { if (type === 'QA') return stop('Current QA report is missing.'); else continue; }
+    const overlay = proposed?.get(path), external = readArtefact || typeof overlay === 'string';
+    if (posix.normalize(path) !== path || strictUtf8 && /[%?#]/u.test(path)
+        || !path.startsWith(`.agdf/control/artefacts/${runId}/`) || !external && hasSymlinkComponent(root, path)) return stop(`Unsafe review source: ${type}.`);
+    const file = external ? null : containedRegularFile(root, path);
+    if (file && file.status !== 'valid') return stop(`Review source unavailable: ${type}.`);
+    if (reports.has(path)) continue;
+    if (reports.size >= maxSources) return stop('Review source limit exceeded.');
+    reports.add(path);
+    const captured = typeof overlay === 'string' ? overlay : readArtefact ? readArtefact(path) : null;
+    if (external && typeof captured !== 'string') return stop(`Review source unavailable: ${type}.`);
+    const bytes = external ? Buffer.from(captured) : readFileSync(file.path);
+    observations.push({ path, digest: 'sha256:' + createHash('sha256').update(bytes).digest('hex'), state: 'available' });
+    if (strictUtf8 && bytes.length > 262144) return stop(`Review source exceeds the bounded input size: ${type}.`);
+    let content;
+    try { content = strictUtf8 ? new TextDecoder('utf-8', { fatal: true }).decode(bytes) : bytes.toString('utf8'); }
+    catch { return stop(`Review source encoding unsupported: ${type}.`); }
+    if (content.length > 262144) return stop(`Review source exceeds the bounded input size: ${type}.`);
+    if (type === 'QA') {
+      if (readReportDecision(content) !== expectedDecision) return stop('QA report decision contradicts its current recording.');
+      // Explicit QA references are inputs too; missing or unsafe references cannot be ignored.
+      sources.push(...qaReportReferences(content, path));
+    }
+    const scan = readNormalizedFindings(content), headerFound = scan.header;
+    const seen = new Set();
+    for (const entry of scan.entries) {
+      if (entry.kind === 'malformed_header') return stop(`Malformed normalized finding header: ${type}.`);
+      if (entry.kind === 'malformed_row') return stop(`Malformed normalized finding row: ${type}.`);
+      const row = entry.row, [id, , target, status, evidence, action] = row;
+      const problems = seen.has(id) ? [{ field: 'finding_id', expected: 'a finding id used only once', rule: 'duplicate_id' }] : normalizedGapProblems(row, routes);
+      if (problems.length) return { ...stop(`Invalid or contradictory normalized finding: ${type}/${id || 'missing id'}.`), invalid: { review: type, finding_id: id || null, problems } };
+      seen.add(id);
+      if (status === 'open' && findings.length >= 64) return stop('Too many open findings for a bounded follow-up; consolidate the authoritative review first.');
+      if (status === 'open') findings.push({ id, target, evidence, action, path });
+    }
+    if ((!headerFound || !seen.size) && (type === 'QA' && expectedDecision !== 'pass' || ['revise', 'block'].includes(artefact.status) || ['revise', 'block'].includes(extractField(content, 'decision')))) return stop(`Normalized findings are missing: ${type}.`);
+  }
+  if (!findings.length && expectedDecision === 'pass') return { kind: 'none', findings, reason: '', sources: observations };
+  if (!findings.length) return stop('QA revise has no valid open normalized finding; inspect its decisive obligation before corrective work.');
+  const upstreamTargets = [...new Set(findings.map(f => f.target).filter(target => !['CD+Tests', 'evidence_obligation'].includes(target)))];
+  if (upstreamTargets.length) return { kind: 'upstream', findings, reason: `Resolve the earliest source-owner decision (${upstreamTargets.join(', ')}) before dependent implementation.`, sources: observations };
+  return { kind: findings.some(f => f.target === 'CD+Tests') ? 'implementation' : 'evidence', findings, reason: '', sources: observations };
+}