create-agdf 0.14.5 → 0.20.1

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

@@ -0,0 +1,237 @@
+import { READ_LIMITS } from '../control-read/snapshot.js';
+
+// A bounded report grammar, not a general Markdown parser. Only initial metadata
+// and the first scalar block of an explicit H2 decision section author a result.
+const metadata = new Set(['decision', 'status', 'gate', 'gate approval', 'based on',
+  'date', 'owner', 'type', 'mode', 'reviewer', 'reviewed_at', 'run_id', 'source_revision',
+  'traceability contract']);
+const voidTags = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr']);
+const rawTags = new Set(['script', 'style', 'textarea']);
+const tagStart = /<\/?([a-z][a-z0-9:-]*)(?=[\s/>])/iyu;
+
+function specialHtmlEnd(text, at) {
+  const special = text.startsWith('<!--', at) ? [4, '-->']
+    : text.startsWith('<![CDATA[', at) ? [9, ']]>']
+      : text.startsWith('<?', at) ? [2, '?>'] : null;
+  if (!special) return null;
+  const end = text.indexOf(special[1], at + special[0]);
+  return end < 0 ? text.length : end + special[1].length;
+}
+
+// Consume markup with quote-aware tags and nesting. Uncertain termination keeps
+// the remainder excluded; apparent tags in attributes/comments never close it.
+function htmlEnd(text, start) {
+  const stack = [];
+  let cursor = start;
+  do {
+    const raw = stack.at(-1);
+    if (rawTags.has(raw)) {
+      const close = new RegExp(`</${raw}[\\t \\n]*>`, 'igu');
+      close.lastIndex = cursor;
+      const match = close.exec(text);
+      if (!match) return text.length;
+      cursor = close.lastIndex; stack.pop();
+      continue;
+    }
+    const at = text.indexOf('<', cursor);
+    if (at < 0) return text.length;
+    const special = specialHtmlEnd(text, at);
+    if (special !== null) { cursor = special; continue; }
+    tagStart.lastIndex = at;
+    const tag = tagStart.exec(text);
+    const declaration = text.startsWith('<!', at);
+    if (!tag && !declaration) return text.length;
+    let end = tag ? tagStart.lastIndex : at + 2, quote = null, brackets = 0;
+    for (; end < text.length; end++) {
+      const char = text[end];
+      if (quote) { if (char === quote) quote = null; }
+      else if (char === '"' || char === "'") quote = char;
+      else if (char === '<' && declaration && brackets) {
+        const nested = specialHtmlEnd(text, end);
+        if (nested !== null) end = nested - 1;
+      }
+      else if (declaration && char === '[') brackets++;
+      else if (declaration && char === ']') { if (!brackets) return text.length; brackets--; }
+      else if (char === '>' && !brackets) break;
+      else if (char === '<' && (!declaration || !brackets)) return text.length;
+    }
+    if (end === text.length || quote) return text.length;
+    cursor = end + 1;
+    if (declaration) continue;
+    const name = tag[1].toLowerCase(), closing = text[at + 1] === '/';
+    if (closing) {
+      if (!/^[\t \n]*$/u.test(text.slice(tagStart.lastIndex, end)) || stack.at(-1) !== name) return text.length;
+      stack.pop();
+    // In HTML, '/>' does not close a non-void element (including raw blocks).
+    } else if (!voidTags.has(name)) stack.push(name);
+  } while (stack.length);
+  return cursor;
+}
+
+// Ignore escaped and inline-code '<' characters. An unmatched inline-code opener
+// conservatively masks the rest of this line; it cannot author a scalar field.
+function markupIndex(line, start = 0, limit = line.length) {
+  let ticks = 0;
+  for (let i = start; i < limit; i++) {
+    if (line[i] === '\\') { i++; continue; }
+    if (line[i] === '`') {
+      let end = i + 1;
+      while (end < limit && line[end] === '`') end++;
+      const count = end - i;
+      if (!ticks) ticks = count;
+      else if (ticks === count) ticks = 0;
+      i = end - 1;
+    } else if (!ticks && line[i] === '<') return i;
+  }
+  return -1;
+}
+
+// One lexical owner for the result observer and closed decision-content profiles.
+// Boundary events also exclude lazy continuations: a closed block cannot reopen
+// on a blank or an apparent field; only an actual admitted heading reopens it.
+function* reportLines(text) {
+  let fence = null, skipUntil = 0;
+  let offset = 0;
+  for (const line of text.split('\n')) {
+    const start = offset; offset += line.length + 1;
+    if (start < skipUntil) continue;
+    const unfenced = line.replace(/^(?:[ \t]*>[ \t]?)+/u, '')
+      .replace(/^[ \t]*(?:[-+*]|\d+[.)])[ \t]+/u, '');
+    const markers = unfenced.match(/^ {0,3}(`{3,}|~{3,})([^\n]*)$/u);
+    if (fence) {
+      if (markers && markers[1][0] === fence.kind && markers[1].length >= fence.length && !markers[2].trim()) fence = null;
+      continue;
+    }
+    if (markers) {
+      fence = { kind: markers[1][0], length: markers[1].length };
+      yield { boundary: true }; continue;
+    }
+    const heading = line.match(/^(#{1,6})[\t ]+([^\n]+)$/u);
+    let name;
+    if (heading) {
+      name = heading[2].trim(); let end = name.length;
+      while (end && name[end - 1] === '#') end--;
+      if (end < name.length && end && /[\t ]/u.test(name[end - 1])) name = name.slice(0, end).trimEnd();
+    }
+    let html = markupIndex(line);
+    yield { line, level: heading?.[1].length, name, markup: html >= 0 };
+    if (html >= 0) {
+      // Also consume sibling markup on the final line, not just the first tag.
+      let end = start + html, lineEnd = start + line.length;
+      do {
+        end = htmlEnd(text, end);
+        if (end > lineEnd) {
+          const newline = text.indexOf('\n', end);
+          lineEnd = newline < 0 ? text.length : newline;
+        }
+        html = markupIndex(text, end, lineEnd);
+        if (html < 0) { skipUntil = lineEnd + 1; break; }
+        end = html;
+      } while (end < text.length);
+      if (end >= text.length) skipUntil = text.length;
+    }
+  }
+}
+
+function* authoredFields(text) {
+  let active = true, titleAllowed = true;
+  for (const row of reportLines(text)) {
+    if (row.boundary) { active = false; titleAllowed = false; continue; }
+    if (!row.line.trim()) continue;
+    if (row.level) {
+      if (!(titleAllowed && row.level === 1)) active = row.level === 2 && /^(?:\d+\.[\t ]+)?(?:QA[\t ]+)?Decision$/iu.test(row.name);
+      titleAllowed = false;
+    } else {
+      const scalar = active && row.line.match(/^(?:- )?([a-z][a-z_ -]*):[\t ]*([^\n]*)$/iu);
+      if (scalar && metadata.has(scalar[1].toLowerCase())) {
+        titleAllowed = false;
+        if (/^(?:decision|status)$/iu.test(scalar[1])) yield [scalar[1], scalar[2]];
+      } else { active = false; titleAllowed = false; }
+    }
+    if (row.markup) { active = false; titleAllowed = false; }
+  }
+}
+
+const summaryFields = new Set(['problem', 'ziel', 'goal', 'betroffene', 'users', 'umfang', 'scope', 'abnahme', 'acceptance', 'offen', 'open questions',
+  'qa-ergebnis', 'qa result', 'umsetzung', 'implementation', 'nachweise', 'evidence', 'ergebnis', 'delivered result', 'grenzen', 'qualification limits',
+  'risiken', 'risks', 'nächster schritt', 'next step', 'quellen und abgrenzung', 'risiken und klärung',
+  'entscheidung', 'decision', 'tp-abdeckung', 'task plan coverage', 'lücken', 'missing evidence']);
+const contentProfiles = Object.freeze({
+  objective: { heading: /^Objective$/iu, paragraph: true },
+  goal: { heading: /^(?:\d+\.[\t ]+)?Goal$/iu, paragraph: true },
+  result: { heading: /^(?:\d+\.[\t ]+)?TP Coverage$/iu, fields: ['delivered_result'] },
+  limits: { heading: /^(?:\d+\.[\t ]+)?Missing Evidence$/iu, fields: ['qualification_limits'] },
+  risks: { heading: /^(?:\d+\.[\t ]+)?Risks$/iu, fields: ['delivery_risks'] },
+});
+
+// Closed internal profiles only; no caller-selected heading/regex or Markdown API.
+export function readAuthoredContent(text, profile, { locale, sourceLanguage } = {}) {
+  // Run history uses the shared capture bound; reports retain their smaller limit.
+  // Scan the full Run so later duplicate Objectives still fail closed.
+  const limit = profile === 'objective' ? READ_LIMITS.file : 131072;
+  if (typeof text !== 'string' || Buffer.byteLength(text) > limit) return null;
+  if (profile === 'title') {
+    for (const row of reportLines(text.replace(/\r\n?/gu, '\n'))) if (row.level === 1 && !row.markup) return row.name;
+    return null;
+  }
+  const localizedGoal = profile === 'localized_goal';
+  const localized = profile === 'localized' || localizedGoal;
+  // Fields are keyed by the display locale; the source may be any well-formed language tag.
+  const spec = localized && ['en', 'de'].includes(locale) && /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u.test(sourceLanguage ?? '')
+    ? { heading: new RegExp('^AGDF Approval Summary \\(' + locale + ';[\\t ]*source=' + sourceLanguage + '\\)$', 'iu'), fields: null, paragraph: localizedGoal }
+    : contentProfiles[profile];
+  if (!spec) return null;
+  // Legacy label, unchanged value; normalize before duplicate checks.
+  const summaryKey = key => localized && locale === 'de' && key === 'ziel und betroffene' ? 'ziel' : key;
+  let active = false, sectionActive = false, sections = 0, started = false;
+  const lines = [], fields = {};
+  for (const row of reportLines(text.replace(/\r\n?/gu, '\n'))) {
+    if (row.boundary || row.markup) { active = false; continue; }
+    if (row.level) {
+      active = row.level === 2 && spec.heading.test(row.name); sectionActive = active; started = false;
+      if (active && ++sections !== 1) return null;
+      continue;
+    }
+    // Legacy prose uses the first paragraph verbatim, without inference/translation.
+    // Any named field requires scalar reading; mixed/malformed fields cannot fall back.
+    if (localizedGoal && sectionActive) {
+      const key = summaryKey(row.line.match(/^(?:- )?([\p{L}][\p{L}\p{N}_ -]*):[\t ]*/u)?.[1].toLowerCase());
+      if (key && (summaryFields.has(key) || /^ac-[a-z0-9-]+$/iu.test(key))) return null;
+    }
+    if (!active) continue;
+    if (!row.line.trim()) { if (spec.paragraph && started) active = false; continue; }
+    if (spec.paragraph) {
+      if (/^(?:\s|[-+*>]|\d+[.)][\t ])/u.test(row.line)) { active = false; continue; }
+      started = true; lines.push(row.line.trim());
+    } else {
+      // A localized summary may carry labels outside the closed field set, including a
+      // qualified label such as `Problem (Messlücke):`. Such a labelled line is skipped,
+      // so field order never decides readability; any other line still closes the block.
+      const scalar = row.line.match(localized
+        ? /^(?:- )?([\p{L}][\p{L}\p{N}_ -]*?)([\t ]*\([^()\n]*\))?:[\t ]*([^\n]*)$/u
+        : /^(?:- )?([\p{L}][\p{L}\p{N}_ -]*)():[\t ]*([^\n]*)$/u);
+      const key = summaryKey(scalar && (localized ? scalar[1].trimEnd() : scalar[1]).toLowerCase());
+      const known = key && !scalar[2] && (localized ? summaryFields.has(key) || /^ac-[a-z0-9-]+$/iu.test(key) : spec.fields.includes(key));
+      if (localized && key && !known) continue;
+      if (!known) { active = false; continue; }
+      if (Object.hasOwn(fields, key)) return null;
+      fields[key] = scalar[3].trim(); started = true;
+    }
+  }
+  return sections === 1 && (spec.paragraph ? lines.length : Object.keys(fields).length) ? spec.paragraph ? lines.join(' ') : fields : null;
+}
+
+// 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 } = {}) {
+  if (typeof text !== 'string') return null;
+  const results = new Set();
+  for (const [field, raw] of authoredFields(text.replace(/\r\n?/gu, '\n'))) {
+    const value = raw.trim().replace(/^`([^`]+)`$/u, '$1').toLowerCase();
+    const result = value === 'passed' ? 'pass' : value;
+    if (['pass', 'revise', 'block'].includes(result) || allowNotApplicable === true && result === 'not_applicable') results.add(result);
+    else if (field.toLowerCase() === 'decision') return null;
+  }
+  return results.size === 1 ? [...results][0] : null;
+}

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

@@ -0,0 +1,51 @@
+// Policy over prepared Run facts; no filesystem reads or state preparation.
+import { filled, isPlaceholderValue } from "./shared.js";
+
+export const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
+export const durableGateArtefacts = new Set(["UR", "PRD", "SD", "TP", "QA"]);
+export const internalStepArtefacts = new Set(["Brownfield Review", "UX Intent Definition", "Verified Change", "Brownfield Analysis", "CD+Tests", "TP Review", "Clean Implementation Review", "Clean Review", "CR", "Code Review"]);
+export const closeoutArtefacts = new Set(["OR"]);
+
+export function gateApprovalStatus(runState, gate) {
+  if (!userGateOrder.includes(gate)) return "not_applicable";
+  return runState.approvals.get(gate)?.status ?? "";
+}
+
+export function gateArtefactStatus(runState, gate) {
+  if (!userGateOrder.includes(gate)) return { status: "not_applicable", path: "" };
+  return runState.artefacts.get(gate) ?? { status: "", path: "" };
+}
+
+export function isDurableGateArtefactSatisfied(runState, gate) {
+  if (!durableGateArtefacts.has(gate)) return true;
+  const artefact = gateArtefactStatus(runState, gate);
+  if (!artefact.path || isPlaceholderValue(artefact.path)) return false;
+  if (gate === "QA") return artefact.status === "pass" || artefact.status === "passed" || runState.qa_acceptance?.accepted === true;
+  return artefact.status === "approved";
+}
+
+export function expectedDurableArtefactStatuses(gate) {
+  return gate === "QA" ? ["pass", "passed"] : ["approved"];
+}
+
+export function describeDurableArtefactStatuses(gate) {
+  return expectedDurableArtefactStatuses(gate).map((status) => `\`${status}\``).join(" or ");
+}
+
+export function isInternalStepSatisfied(runState, step) {
+  const artefact = runState.artefacts.get(step);
+  if (!artefact) return false;
+  const associated = runState.evidence_applicability?.by_step.get(step);
+  if (associated && associated.applicability !== 'current') return false;
+  if (artefact.status === "done") return true;
+  return artefact.status === "not_applicable"
+    && (step === "Brownfield Review" || step === "Brownfield Analysis");
+}
+
+export function modeSliceDecision(runState) {
+  const decision = runState.mode_slice_decision?.decision ?? "";
+  const scopeReason = runState.mode_slice_decision?.scope_reason ?? "";
+  const evidence = runState.mode_slice_decision?.evidence ?? "";
+  if (!decision || isPlaceholderValue(decision) || !filled(scopeReason) || !filled(evidence)) return "undecided";
+  return decision;
+}

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

@@ -1,28 +1,29 @@
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { userGateOrder, durableGateArtefacts, internalStepArtefacts, closeoutArtefacts, gateApprovalStatus, gateArtefactStatus, expectedDurableArtefactStatuses, describeDurableArtefactStatuses, modeSliceDecision } from "./run-state-policy.js";
+export { userGateOrder, durableGateArtefacts, internalStepArtefacts, closeoutArtefacts, gateApprovalStatus, gateArtefactStatus, isDurableGateArtefactSatisfied, expectedDurableArtefactStatuses, describeDurableArtefactStatuses, isInternalStepSatisfied, modeSliceDecision } from "./run-state-policy.js";
+import { presentationDecisionState, approvedMaterialFindings, approvalMaterialTypes, reviewCorrections } from '../control-state/presentation-decision.js';
+import { inspectQaDeviationAcceptance } from '../control-state/qa-deviation-acceptance.js';
+import { createHash } from "node:crypto";
+import { canonicalRunText } from "../control-state/run-seal-compute.js";
+import { existsSync, readFileSync } from "../control-read/fs.js";
+import { join } from "node:path";
 import process from "node:process";
-import { parseControlState, resolveRuns } from "../control-state/index.js";
+import { parseControlState, parseRunState } from "../control-state/run-state-parser.js";
+import { resolveRuns } from "../control-state/run-state-resolver.js";
 import { validateRunIdentity } from "../control-state/run-identity.js";
 import { buildRunCandidates } from "../interaction-presentation.js";
 import { cleanStatusCell, filled, isPlaceholderValue, readTargetFile } from "./shared.js";
 import { extractField, isSafeRepoRelativePath, readVerifiedChangeRecord } from "./verified-change.js";
-
-export const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
-export const durableGateArtefacts = new Set(["UR", "PRD", "SD", "TP", "QA"]);
-export const internalStepArtefacts = new Set(["Brownfield Review", "Verified Change", "Brownfield Analysis", "CD+Tests", "TP Review", "Clean Implementation Review", "Clean Review", "CR", "Code Review"]);
-export const closeoutArtefacts = new Set(["OR"]);
+import { containedRegularFile } from "../control-state/contained-file.js";
+import { readSourceRevisions } from "../control-state/run-source-revisions.js";
+import { evidenceApplicability, STRUCTURED_REQUIRED_REVIEWS } from '../control-state/evidence-bindings.js';
+import { evaluateCloseoutReadiness } from './closeout-readiness.js';
+import { evaluateReconciliationState } from './parent-reconciliation.js';
 
 export function resolvedArtefactFile(targetDir, rawPath) {
   const normalizedPath = String(rawPath ?? "").replace(/^`|`$/g, "").trim();
-  if (!normalizedPath || isAbsolute(normalizedPath) || normalizedPath.includes("<") || normalizedPath.includes(">")) return "";
-  const absolutePath = resolve(targetDir, normalizedPath);
-  if (relative(targetDir, absolutePath).startsWith("..") || !existsSync(absolutePath)) return "";
-  try {
-    const realPath = realpathSync(absolutePath);
-    return relative(realpathSync(targetDir), realPath).startsWith("..") || !statSync(realPath).isFile() ? "" : realPath;
-  } catch {
-    return "";
-  }
+  if (normalizedPath.includes("<") || normalizedPath.includes(">")) return "";
+  const result = containedRegularFile(targetDir, normalizedPath);
+  return result.status === "valid" ? result.path : "";
 }
 
 export function readArtefactHeading(targetDir, artefact) {
@@ -35,6 +36,75 @@ export function readArtefactHeading(targetDir, artefact) {
   }
 }
 
+// One preparation boundary for both saved and proposed Run content. Callers that
+// inspect an immutable archive provide its own artefact reader, never current bytes.
+export function prepareRunContentState(targetDir, content, path = "", { readArtefact, proposedArtefacts = new Map() } = {}) {
+  if (!(proposedArtefacts instanceof Map)) throw Error("proposed_artefacts_invalid");
+  const normalizedOverlay = new Map();
+  for (const [name, row] of proposedArtefacts) {
+    if (typeof name !== "string" || !isSafeRepoRelativePath(name) || typeof row?.content !== "string"
+        || row.digest !== `sha256:${createHash("sha256").update(canonicalRunText(row.content)).digest("hex")}`) throw Error("proposed_artefacts_invalid");
+    normalizedOverlay.set(name, row.content);
+  }
+  const overlayReader = normalizedOverlay.size ? name => {
+    if (normalizedOverlay.has(name)) return normalizedOverlay.get(name);
+    if (readArtefact) return readArtefact(name);
+    const file = resolvedArtefactFile(targetDir, name);
+    return file ? readFileSync(file, "utf8") : undefined;
+  } : readArtefact;
+  const parsed = parseControlState(content, {
+    userGates: userGateOrder,
+    internalSteps: [...internalStepArtefacts],
+    closeoutArtefacts: [...closeoutArtefacts],
+  });
+  if ([...normalizedOverlay.keys()].some(name => !name.startsWith(`.agdf/control/artefacts/${parsed.run_id}/`))) throw Error("proposed_artefacts_invalid");
+  const state = { path, content, ...parsed, meta: parseRunState(content).meta };
+  const evidenceReader = overlayReader ?? (name => {
+    const file = resolvedArtefactFile(targetDir, name);
+    return file ? readFileSync(file, 'utf8') : undefined;
+  });
+  const presentationDecisions = new Map(userGateOrder.map(gate => [gate, presentationDecisionState(targetDir, state, gate, { readArtefact: overlayReader })]));
+  // Reviews recorded after a QA approval whose receipt proves it never saw them (late closeout path).
+  const qaMaterial = approvalMaterialTypes(state, 'QA');
+  const lateReviewTypes = qaMaterial.status === 'recorded' ? STRUCTURED_REQUIRED_REVIEWS.filter(type => !qaMaterial.types.has(type)) : [];
+  // Reviews corrected at OR after the UAT approval (receipt-proven, presentation-decision.js).
+  const evidence = evidenceApplicability(state, evidenceReader, { lateReviewTypes, reviewCorrections: reviewCorrections(state) });
+  // The reconciliation owner consumes relationship declarations, not another
+  // parent's evaluated closeout. Resolve its captured bytes without recursively
+  // evaluating a parent/child cycle. Archived reads never borrow live Run bytes.
+  const reconciliation = evaluateReconciliationState(state, {
+    loadRun: id => {
+      const name = `.agdf/control/runs/${id}/RUN_STATE.md`;
+      const bytes = readArtefact ? readArtefact(name) : resolveRuns(targetDir, { runIdArg: id }).run.content;
+      return typeof bytes === 'string' ? { content: bytes, ...parseControlState(bytes, {
+        userGates: userGateOrder, internalSteps: [...internalStepArtefacts], closeoutArtefacts: [...closeoutArtefacts],
+      }) } : null;
+    },
+    resolveFile: name => typeof evidenceReader(name) === 'string',
+  });
+  const qaAcceptance = inspectQaDeviationAcceptance(targetDir, {
+    ...state, evidence_applicability: evidence, presentation_decisions: presentationDecisions,
+  }, evidenceReader);
+  const or = state.artefacts.get('OR');
+  let closeoutEvidence = { ready: false, findings: ['or_unavailable'] };
+  try { if (or?.path && or.status === 'done') closeoutEvidence = evaluateCloseoutReadiness({ ...state, qa_acceptance: qaAcceptance, reconciliation_state: reconciliation, evidence_applicability: evidence }, evidenceReader(or.path), evidenceReader); }
+  catch { closeoutEvidence = { ready: false, findings: ['or_observation_unavailable'] }; }
+  return {
+    ...state,
+    evidence_applicability: evidence,
+    qa_acceptance: qaAcceptance,
+    reconciliation_state: reconciliation,
+    closeout_evidence: closeoutEvidence,
+    presentation_decisions: presentationDecisions,
+    approval_material_findings: approvedMaterialFindings(state, presentationDecisions),
+    source_revision_ux_required: sourceRevisionUxRequired(targetDir, state, { readArtefact: overlayReader }),
+    identity_findings: validateRunIdentity({
+      runId: extractField(content, "run_id").replace(/^`|`$/g, ""),
+      revisionId: extractField(content, "revision_id").replace(/^`|`$/g, ""),
+    }),
+  };
+}
+
 export function readRunState(targetDir, selection = {}) {
   let runPath = join(".agdf", "control", "AGDF_RUN.md");
   const canonicalRoot = join(targetDir, ".agdf", "control", "runs");
@@ -44,7 +114,7 @@ export function readRunState(targetDir, selection = {}) {
     try {
       const selected = resolveRuns(targetDir, {
         runIdArg: selection.runId,
-        runIdEnv: process.env.AGDF_RUN_ID,
+        runIdEnv: selection.ignoreRunIdEnv ? undefined : process.env.AGDF_RUN_ID,
       });
       runPath = selected.run.path.startsWith(targetDir)
         ? selected.run.path.slice(targetDir.length + 1)
@@ -93,47 +163,19 @@ export function readRunState(targetDir, selection = {}) {
   }
 
   const content = readTargetFile(targetDir, runPath);
-  const parsed = parseControlState(content, {
-    userGates: userGateOrder,
-    internalSteps: [...internalStepArtefacts],
-    closeoutArtefacts: [...closeoutArtefacts],
-  });
-
-  return {
-    path: runPath,
-    content,
-    ...parsed,
-    identity_findings: validateRunIdentity({
-      runId: extractField(content, "run_id").replace(/^`|`$/g, ""),
-      revisionId: extractField(content, "revision_id").replace(/^`|`$/g, ""),
-    }),
-  };
-}
-
-export function gateApprovalStatus(runState, gate) {
-  if (!userGateOrder.includes(gate)) return "not_applicable";
-  return runState.approvals.get(gate)?.status ?? "";
-}
-
-export function gateArtefactStatus(runState, gate) {
-  if (!userGateOrder.includes(gate)) return { status: "not_applicable", path: "" };
-  return runState.artefacts.get(gate) ?? { status: "", path: "" };
+  return prepareRunContentState(targetDir, content, runPath, { readArtefact: selection.readArtefact });
 }
 
-export function isDurableGateArtefactSatisfied(runState, gate) {
-  if (!durableGateArtefacts.has(gate)) return true;
-  const artefact = gateArtefactStatus(runState, gate);
-  if (!artefact.path || isPlaceholderValue(artefact.path)) return false;
-  if (gate === "QA") return artefact.status === "pass" || artefact.status === "passed";
-  return artefact.status === "approved";
-}
-
-export function expectedDurableArtefactStatuses(gate) {
-  return gate === "QA" ? ["pass", "passed"] : ["approved"];
-}
-
-export function describeDurableArtefactStatuses(gate) {
-  return expectedDurableArtefactStatuses(gate).map((status) => `\`${status}\``).join(" or ");
+export function sourceRevisionUxRequired(targetDir, state, { readArtefact } = {}) {
+  if (!readSourceRevisions(state.content ?? "").present) return false;
+  const review = state.artefacts.get("Brownfield Review");
+  if (review?.status !== "done") return false;
+  if (readArtefact) {
+    const content = readArtefact(review.path);
+    return typeof content === "string" && extractField(content, "ux_intent_definition_required") === "yes";
+  }
+  const file = resolvedArtefactFile(targetDir, review.path);
+  return Boolean(file && extractField(readFileSync(file, "utf8"), "ux_intent_definition_required") === "yes");
 }
 
 export function analyzeDurableGateArtefactConsistency(runState) {
@@ -143,6 +185,7 @@ export function analyzeDurableGateArtefactConsistency(runState) {
     if (gateApprovalStatus(runState, gate) !== "approved") continue;
 
     const artefact = gateArtefactStatus(runState, gate);
+    if (gate === 'QA' && runState.qa_acceptance?.accepted === true) continue;
     if (!artefact.path || isPlaceholderValue(artefact.path) || !artefact.status) continue;
 
     const expectedStatuses = expectedDurableArtefactStatuses(gate);
@@ -188,6 +231,14 @@ export function analyzeArtefactRoleConsistency(targetDir, runState) {
   }
   for (const [path, roles] of rolesByPath) {
     if (roles.length < 2) continue;
+    // CR and Clean Review are supported names for the same review roles, not separate artefacts.
+    const aliases = new Map([["CR", "Code Review"], ["Clean Review", "Clean Implementation Review"]]);
+    const canonicalRoles = new Set(roles.map((role) => aliases.get(role) ?? role));
+    if (canonicalRoles.size === 1) {
+      const statuses = new Set(roles.map((role) => runState.artefacts.get(role)?.status));
+      if (statuses.size > 1) findings.push({ severity: "block", code: "AGDF_ARTEFACT_ROLE_ALIAS_INVALID", message: `Artefact aliases have conflicting statuses: ${roles.join(", ")}.`, path, next_step: "Use one consistent status for aliases of the same artefact role." });
+      continue;
+    }
     const allowedRoles = new Set(["Brownfield Review", "Verified Change", "OR"]);
     if (modeSliceDecision(runState) !== "verified_change" || roles.some((role) => !allowedRoles.has(role))) {
       findings.push({ severity: "block", code: "AGDF_ARTEFACT_ROLE_ALIAS_INVALID", message: `Artefact path is reused across incompatible roles: ${roles.join(", ")}.`, path, next_step: "Use distinct artefacts or a lifecycle-consistent Verified Change compact record." });
@@ -204,20 +255,3 @@ export function analyzeArtefactRoleConsistency(targetDir, runState) {
   }
   return findings;
 }
-
-export function isInternalStepSatisfied(runState, step) {
-  const artefact = runState.artefacts.get(step);
-  if (!artefact) return false;
-  if (artefact.status === "done") return true;
-  return artefact.status === "not_applicable"
-    && (step === "Brownfield Review" || step === "Brownfield Analysis");
-}
-
-export function modeSliceDecision(runState) {
-  const decision = runState.mode_slice_decision?.decision ?? "";
-  const scopeReason = runState.mode_slice_decision?.scope_reason ?? "";
-  const evidence = runState.mode_slice_decision?.evidence ?? "";
-  if (!decision || isPlaceholderValue(decision) || !filled(scopeReason) || !filled(evidence)) return "undecided";
-  return decision;
-}
-

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

@@ -0,0 +1,20 @@
+import { transitionDecisionForRunState } from "./gate-policy.js";
+import { modeSliceDecision, prepareRunContentState } from "./run-state.js";
+import { evaluateVerifiedChange } from "./verified-change.js";
+
+// Evaluates the gate policy for unsaved run-state text, so run-step can store the deterministic
+// current gate, next action and forbidden list together with the step it records.
+export function policyForRunContent(targetDir, content, runPath = "", preparation = {}) {
+  const runState = prepareRunContentState(targetDir, content, runPath, preparation);
+  const verifiedChange = modeSliceDecision(runState) === "verified_change" ? evaluateVerifiedChange(targetDir, runState, {}) : null;
+  const decision = transitionDecisionForRunState(runState, verifiedChange);
+  return Object.freeze({
+    status: decision.status,
+    current_gate: decision.current_gate,
+    missing_approval: decision.missing_approval,
+    next_allowed_action: decision.next_allowed_action,
+    forbidden: Object.freeze([...decision.forbidden]),
+    next_operation: decision.next_operation,
+    completion: decision.completion,
+  });
+}