create-agdf 0.14.5 → 0.20.0

package/runtime/core/lib/control-evaluation/run-work-summary.js

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from '../control-read/fs.js';
+import { containedRegularFile, hasSymlinkComponent, isSafeControlRelativePath } from '../control-state/contained-file.js';
+import { policyForRunContent } from './run-step-policy.js';
+import { effectiveNextAllowedAction } from './next-action.js';
+import { evaluateQaFollowUp, inspectQaReports } from './qa-follow-up.js';
+import { prepareRunContentState, modeSliceDecision } from './run-state.js';
+import { extractField } from './verified-change.js';
+import { summaryLabel } from './backlog-vocabulary.js';
+import { readReportDecision } from './report-decision.js';
+
+// Shared projection; never invokes gate-check, changes control or grants permission. `proposed`
+// maps run artefact paths to the content a pending write publishes before its precommit check.
+export function runWorkSummary(root, content, runPath = '', decision = policyForRunContent(root, content, runPath), { proposed } = {}) {
+  const state = prepareRunContentState(root, content, runPath);
+  const runId = extractField(content, 'run_id'), lifecycle = extractField(content, 'lifecycle');
+  const policyOnly = modeSliceDecision(state) === 'verified_change' || /## Source Revisions\b/u.test(content);
+  const summary = { kind: 'work_pending', phase: decision.current_gate, qa_outcome: 'not_applicable', lifecycle,
+    recorded_approvals: [...state.approvals].filter(([, row]) => row.status === 'approved').map(([gate]) => gate),
+    decisive_obligation: null, open_obligation_count: 0,
+    display_action: policyOnly ? decision.next_allowed_action : effectiveNextAllowedAction(state, decision),
+    sources: [], limitations: [], authorizes: false };
+  summary.evidence_applicability = Object.fromEntries(['current', 'superseded', 'applicability_unknown'].map(group => [group,
+    state.evidence_applicability[group].map(row => ({ path: row.report?.path ?? row.source, step: row.step ?? null, reason: row.reason, available: row.available }))]));
+  if (lifecycle === 'completed') summary.kind = decision.completion?.fulfilled ? 'completed' : 'unconfirmed';
+  else if (decision.status === 'blocked') summary.kind = 'unconfirmed';
+  else if (decision.current_gate === 'OR') summary.kind = 'closeout_pending';
+  else if (decision.missing_approval !== 'none') summary.kind = 'approval_pending';
+  const qa = state.artefacts.get('QA');
+  const structured = ['structured_slice', 'structured_delivery'].includes(modeSliceDecision(state));
+  const qaRelevant = structured && (qa?.path || ['QA', 'UAT', 'OR'].includes(decision.current_gate));
+  const unconfirmed = reason => { summary.kind = 'source_unconfirmed'; summary.limitations.push(reason);
+    summary.display_action = decision.next_allowed_action; };
+  if (qaRelevant) {
+    summary.qa_outcome = 'unconfirmed';
+    const path = String(qa?.path ?? '').replace(/^`|`$/gu, '');
+    if (!path) { summary.kind = 'qa_report_pending'; summary.qa_outcome = 'missing'; }
+    else if (!isSafeControlRelativePath(path) || /[%?#]/u.test(path) || !path.startsWith(`.agdf/control/artefacts/${runId}/`)
+        || hasSymlinkComponent(root, path)) unconfirmed('qa_source_unsafe');
+    else {
+      const overlay = proposed?.get(path), file = typeof overlay === 'string' ? null : containedRegularFile(root, path);
+      if (file && file.status !== 'valid') unconfirmed('qa_source_unavailable');
+      else {
+        const bytes = file ? readFileSync(file.path) : Buffer.from(overlay);
+        let text = '';
+        try { if (bytes.length > 262144) throw Error(); text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); }
+        catch { unconfirmed('qa_source_unsupported'); }
+        const authoredDecision = readReportDecision(text);
+        summary.sources.push({ path, digest: 'sha256:' + createHash('sha256').update(bytes).digest('hex'), state: 'available' });
+        const normalized = value => value === 'passed' ? 'pass' : value;
+        if (bytes.length > 262144 || !authoredDecision || authoredDecision !== normalized(qa.status)) unconfirmed('qa_decision_unconfirmed');
+        else {
+          summary.qa_outcome = normalized(qa.status);
+          const association = state.evidence_applicability.by_step.get('QA');
+          if (association && association.applicability !== 'current') {
+            unconfirmed('qa_evidence_association_not_current');
+          }
+          else if (qa.status === 'revise' && state.qa_acceptance?.accepted) {
+            // Human acceptance does not change the original QA outcome or mark tests passed.
+            summary.qa_acceptance = { kind: 'accepted_with_deviations', digest: state.qa_acceptance.digest,
+              deviation_ids: state.qa_acceptance.proposal.deviations.map(row => row.finding_id) };
+            summary.open_obligation_count = state.qa_acceptance.proposal.deviations.length;
+            summary.sources = state.qa_acceptance.sources;
+          }
+          else if (qa.status === 'revise' && state.qa_acceptance?.eligible) {
+            summary.kind = 'approval_pending'; summary.sources = state.qa_acceptance.sources;
+            summary.open_obligation_count = state.qa_acceptance.proposal.deviations.length;
+            summary.qa_acceptance = { kind: 'deviation_acceptance_pending', digest: state.qa_acceptance.digest };
+          }
+          else if (qa.status === 'revise') {
+            const followUp = evaluateQaFollowUp(root, state, runId, 64, true);
+            summary.sources = followUp.sources;
+            if (followUp.kind === 'blocked') unconfirmed(followUp.reason);
+            else {
+              summary.kind = { evidence: 'qa_evidence_open', implementation: 'qa_correction_open', upstream: 'qa_source_decision' }[followUp.kind];
+              const decisive = followUp.findings.find(f => followUp.kind === 'upstream' ? !['CD+Tests', 'evidence_obligation'].includes(f.target)
+                : followUp.kind === 'implementation' ? f.target === 'CD+Tests' : true);
+              summary.decisive_obligation = { id: decisive.id, routing_target: decisive.target, action: decisive.action, source_path: decisive.path };
+              summary.open_obligation_count = followUp.findings.length;
+              summary.display_action = decisive.action + (followUp.kind === 'upstream' ? ' Resolve the source-owner decision before dependent work.' : ' Then rerun QA with refreshed evidence.');
+            }
+          } else {
+            const observation = inspectQaReports(root, state, runId, normalized(qa.status), 64, true, { proposed });
+            summary.sources = observation.sources;
+            if (observation.kind === 'blocked' || qa.status !== 'block' && observation.findings.length) unconfirmed(observation.reason || 'open_review_findings_contradict_pass');
+            else if (qa.status === 'block') { summary.kind = 'qa_blocked'; summary.display_action = decision.next_allowed_action; }
+          }
+        }
+      }
+    }
+  }
+  if (summary.sources.length > 64) { summary.sources = summary.sources.slice(0, 64); unconfirmed('source_limit'); }
+  if (Buffer.byteLength(JSON.stringify(summary)) > 60000) {
+    summary.decisive_obligation = null; summary.open_obligation_count = 0; summary.sources = [];
+    summary.evidence_applicability = { current: [], superseded: [], applicability_unknown: [] };
+    summary.limitations = ['summary_size_limit']; summary.kind = 'source_unconfirmed';
+    summary.display_action = 'Inspect the current Run and its registered sources before recording a bounded backlog summary.';
+  }
+  return Object.freeze({ ...summary, status_label: summaryLabel(summary.kind) });
+}
+
+// Recheck only already consumed safe sources at the existing mutation precommit boundary.
+export function assertSummarySources(root, summary) {
+  for (const source of summary.sources) {
+    const file = containedRegularFile(root, source.path);
+    if (file.status !== 'valid' || hasSymlinkComponent(root, source.path)
+      || 'sha256:' + createHash('sha256').update(readFileSync(file.path)).digest('hex') !== source.digest) throw Error('AGDF_STALE_RUN_REVISION');
+  }
+}

package/runtime/core/lib/control-evaluation/sd-readiness.js

@@ -0,0 +1,56 @@
+import { readFileSync } from "../control-read/fs.js";
+import { resolvedArtefactFile } from "./run-state.js";
+
+export const SD_DECISIONS_CONTRACT = "Design Decisions contract: sd-decisions-v1";
+export const SD_DECISION_FORMAT = Object.freeze({ contract: SD_DECISIONS_CONTRACT, section: "Design Decisions",
+  columns: Object.freeze(["Decision", "Timing", "Status", "Resolution", "Owner"]), timings: Object.freeze(["before_sd", "later_tp"]),
+  statuses: Object.freeze(["resolved", "open", "deferred"]) });
+
+function sdDecisionTable(content) {
+  const markers = [...content.matchAll(/^Design Decisions contract:[ \t]*(.*)$/gmu)];
+  const headings = [...content.matchAll(/^## Design Decisions[ \t]*$/gmu)];
+  if (headings.length !== 1) return { markers, headings, lines: [], rows: [] };
+  const body = content.slice(headings[0].index + headings[0][0].length).split(/^## /mu)[0];
+  const lines = body.split("\n").filter(line => line.trim().startsWith("|"));
+  const rows = lines.map(line => line.trim().slice(1, -1).split("|").map(cell => cell.trim()));
+  return { markers, headings, lines, rows };
+}
+
+export function readSdDecisionRows(markdown) {
+  const readiness = evaluateSdDecisionContent(markdown);
+  if (!readiness.ready) return { valid: false, rows: [] };
+  const { rows } = sdDecisionTable(markdown.replace(/\r\n?/gu, "\n"));
+  return { valid: true, rows: rows.slice(2).map(([decision, timing, status, resolution, owner]) => ({ decision, timing, status, resolution, owner })) };
+}
+
+// Explicit declared decision state only; semantic completeness still needs review.
+export function evaluateSdDecisionContent(markdown) {
+  const content = markdown.replace(/\r\n?/gu, "\n");
+  const { markers, headings, lines, rows } = sdDecisionTable(content);
+  if (!markers.length && !headings.length) return { ready: true, open_decisions: [], contract: "legacy" };
+  const fail = message => ({ ready: false, open_decisions: [message], contract: "sd-decisions-v1" });
+  if (markers.length !== 1 || markers[0][1].trim() !== "sd-decisions-v1")
+    return fail("Declare exactly one supported Design Decisions contract: sd-decisions-v1");
+  if (headings.length !== 1) return fail("Declare exactly one Design Decisions section");
+  if (rows.length < 3 || rows[0].join("|") !== SD_DECISION_FORMAT.columns.join("|")
+      || !/^\|[\s:|-]+\|$/u.test(lines[1].trim()) || lines.some(line => !line.trim().endsWith("|")))
+    return fail("Design Decisions table is empty or malformed");
+  const incomplete = value => !value || /^(?:<|tbd\b|todo\b|to confirm\b|none\b)/iu.test(value);
+  const open = [], seen = new Set();
+  for (const [decision, timing, status, resolution, owner, ...extra] of rows.slice(2)) {
+    if (incomplete(decision) || seen.has(decision) || extra.length
+        || !SD_DECISION_FORMAT.timings.includes(timing) || !SD_DECISION_FORMAT.statuses.includes(status)) {
+      open.push(decision || "Malformed design decision row");
+      continue;
+    }
+    seen.add(decision);
+    if (incomplete(owner) || incomplete(resolution) || (timing === "before_sd" && status !== "resolved")) open.push(decision);
+  }
+  return { ready: open.length === 0, open_decisions: open, contract: "sd-decisions-v1" };
+}
+
+export function evaluateSdReadiness(targetDir, runState) {
+  const file = resolvedArtefactFile(targetDir, runState.artefacts.get("SD")?.path);
+  return file ? evaluateSdDecisionContent(readFileSync(file, "utf8"))
+    : { ready: false, open_decisions: ["SD artefact is missing"], contract: "not_linked" };
+}

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

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "../control-read/fs.js";
 import { join, posix } from "node:path";
+import { SUMMARY_LABELS } from "./backlog-vocabulary.js";
 
 export function cleanStatusCell(value) {
   return (value ?? "").replace(/\x60/g, "").trim();
@@ -44,6 +45,9 @@ export function tableRows(content) {
 const compactBacklogHeaders = ["priority", "key", "work item", "status", "artefacts", "current spec", "next step"];
 const legacyBacklogHeaders = ["prio", "key", "title", "status", "ur", "brownfield review", "prd", "sd", "tp", "qa", "or", "current spec", "notes"];
 const backlogStatusLabels = new Map([
+  ...Object.entries(SUMMARY_LABELS).map(([code, labels]) => [labels[0].toLowerCase(), code]),
+  ...["Brownfield Analysis", "CD+Tests", "CR", "Quick Task Execution", "Verified Change Execution", "Mode/Slice Decision"]
+    .map(phase => [`${phase.toLowerCase()} work pending`, "work_pending"]),
   ["needs ur", "needs_ur"],
   ["awaiting brownfield review", "awaiting_brownfield_review"],
   ["awaiting prd", "awaiting_prd"],
@@ -342,4 +346,3 @@ export function parseQualityContracts(content) {
   }
   return parsed;
 }
-

package/runtime/core/lib/control-evaluation/tp-planning.js

@@ -0,0 +1,118 @@
+import { readFileSync } from '../control-read/fs.js';
+import { section } from './markdown-table.js';
+import { readSdDecisionRows } from './sd-readiness.js';
+import { declaredRoutes, validNormalizedGap, NORMALIZED_GAP_COLUMNS } from './normalized-gaps.js';
+import { artefactFileDigest } from '../control-state/run-seal-compute.js';
+import { containedRegularFile, hasSymlinkComponent } from '../control-state/contained-file.js';
+import { readEvidenceBindings } from '../control-state/evidence-bindings.js';
+
+export const TP_PLANNING_FORMAT = Object.freeze({
+  contract: 'Planning Decisions contract: tp-decisions-v1',
+  columns: ['decision', 'source', 'status', 'resolution', 'owner'],
+  clarification_columns: NORMALIZED_GAP_COLUMNS,
+  detail_columns: ['finding_id', 'planning_decision', 'question', 'blocking_reason', 'required_answer', 'owner', 'source_ref', 'resolution_evidence'],
+});
+const filled = value => typeof value === 'string' && !!value.trim() && value.length <= 4096 && !/^(?:<|tbd\b|todo\b|none\b)/iu.test(value);
+
+// New declared format only: containers do not supply machine-readable decisions.
+function visibleText(text) {
+  let fence = null, html = false;
+  return text.replace(/\r\n?/gu, '\n').split('\n').map(line => {
+    const mark = line.match(/^ {0,3}(`{3,}|~{3,})/u)?.[1];
+    if (mark) { if (!fence) fence = mark; else if (mark[0] === fence[0] && mark.length >= fence.length) fence = null; return ''; }
+    if (fence) return '';
+    if (/^ {0,3}</u.test(line)) html = true;
+    if (html) { if (/^ {0,3}<\//u.test(line) || /-->\s*$/u.test(line)) html = false; return ''; }
+    return /^(?: {4}|\t| {0,3}>)/u.test(line) ? '' : line;
+  }).join('\n');
+}
+function table(content, title, columns) {
+  const headings = [...content.matchAll(/^#{2,6} (?:\d+\. )?(.+?)\s*$/gmu)].filter(m => m[1] === title);
+  if (headings.length !== 1) return null;
+  const body = section(content, title), bodyLines = body.split('\n').map(line => line.trim()).filter(Boolean);
+  const start = bodyLines.findIndex(line => line.startsWith('|'));
+  if (start < 0) return null;
+  let end = start;
+  while (end < bodyLines.length && bodyLines[end].startsWith('|')) end += 1;
+  if (bodyLines.slice(end).some(line => line.startsWith('|'))) return null;
+  const lines = bodyLines.slice(start, end);
+  if (lines.length < 3 || lines.some(line => !/^\|.*\|$/u.test(line))) return null;
+  const cells = line => line.slice(1, -1).split('|').map(c => c.trim());
+  if (cells(lines[0]).map(c => c.toLowerCase()).join('|') !== columns.join('|') || !/^\|[\s:|-]+\|$/u.test(lines[1])) return null;
+  const rows = lines.slice(2).map(cells);
+  if (rows.some(row => row.length !== columns.length)) return null;
+  return rows.map(row => Object.fromEntries(columns.map((column, i) => [column, row[i]])));
+}
+function sourceValid(root, state, reference) {
+  const match = reference.match(/^(UR|PRD|SD): (.+) @ (sha256:[0-9a-f]{64})$/u);
+  if (!match) return false;
+  const [, type, statement, digest] = match, source = state.artefacts.get(type);
+  const file = source && containedRegularFile(root, source.path);
+  return source?.status === 'approved' && state.approvals.get(type)?.status === 'approved'
+    && file?.status === 'valid' && !hasSymlinkComponent(root, source.path)
+    && artefactFileDigest(root, source.path) === digest && readFileSync(file.path, 'utf8').includes(statement);
+}
+function resolutionValid(root, state, id, reference) {
+  const match = reference.match(/^(\.agdf\/control\/artefacts\/[^ ]+) @ (sha256:[0-9a-f]{64})$/u);
+  if (!match || !match[1].startsWith(`.agdf/control/artefacts/${state.run_id}/`) || hasSymlinkComponent(root, match[1])) return false;
+  const file = containedRegularFile(root, match[1]);
+  if (file.status !== 'valid' || artefactFileDigest(root, match[1]) !== match[2] || !readFileSync(file.path, 'utf8').includes(id)) return false;
+  const evidence = readEvidenceBindings(state.content);
+  return evidence.valid && evidence.bindings.some(binding => binding.step === 'evidence'
+    && binding.report.path === match[1] && binding.report.digest === match[2]
+    && ['UR', 'PRD', 'SD'].every(type => {
+      const source = binding.sources.find(s => s.type === type), current = state.artefacts.get(type);
+      return source?.status === 'approved' && current?.status === 'approved'
+        && source.path === current.path && source.digest === artefactFileDigest(root, current.path);
+    }));
+}
+
+// Read-only facts. Gate evaluation remains the sole readiness/permission owner.
+export function evaluateTpPlanningContent(root, state, sd, original) {
+  const open = [], clarifications = [], content = visibleText(original);
+  const markers = [...content.matchAll(/^Planning Decisions contract:\s*(.*)$/gmu)];
+  const declared = !!markers.length || /^#{2,6} (?:\d+\. )?Planning Decisions\s*$/mu.test(content);
+  const done = () => ({ declared, open_items: [...new Set(open)], clarifications });
+  if (!declared) return done();
+  if (markers.length !== 1 || markers[0][1] !== 'tp-decisions-v1') { open.push('Declare exactly one Planning Decisions contract: tp-decisions-v1'); return done(); }
+  const decisions = table(content, 'Planning Decisions', TP_PLANNING_FORMAT.columns);
+  if (!decisions?.length) { open.push('Planning Decisions table is missing or malformed'); return done(); }
+  const sdFacts = readSdDecisionRows(sd), expected = sdFacts.rows.filter(row => row.timing === 'later_tp').map(row => `SD: ${row.decision}`);
+  if (!sdFacts.valid) open.push('Upstream SD decision facts are invalid');
+  const names = new Map(), covered = new Set();
+  for (const row of decisions) {
+    if (!filled(row.decision) || names.has(row.decision) || !filled(row.resolution) || !filled(row.owner)
+        || !['open', 'resolved'].includes(row.status) || row.source !== 'TP' && (!expected.includes(row.source) || covered.has(row.source))) open.push(`Invalid planning decision: ${row.decision}`);
+    names.set(row.decision, row);
+    if (row.source !== 'TP') covered.add(row.source);
+    if (row.status === 'open') open.push(`Open planning decision: ${row.decision}`);
+  }
+  for (const source of expected) if (!covered.has(source)) open.push(`Resolve deferred ${source}`);
+  const hasRequests = /^#{2,6} (?:\d+\. )?Clarification Requests\s*$/mu.test(content), hasDetails = /^#{2,6} (?:\d+\. )?Clarification Details\s*$/mu.test(content);
+  if (!hasRequests && !hasDetails) return done();
+  const findings = table(content, 'Clarification Requests', NORMALIZED_GAP_COLUMNS);
+  const details = table(content, 'Clarification Details', TP_PLANNING_FORMAT.detail_columns);
+  if (!findings?.length || !details?.length) { open.push('Clarification Requests and Details tables must be complete'); return done(); }
+  const routes = declaredRoutes(), ids = new Set();
+  for (const row of findings) {
+    const id = row.finding_id, values = NORMALIZED_GAP_COLUMNS.map(key => row[key]);
+    const matches = details.filter(detail => detail.finding_id === id), detail = matches[0];
+    const decision = names.get(detail?.planning_decision);
+    const valid = !ids.has(id) && validNormalizedGap(values, routes) && ['UR', 'PRD', 'SD', 'TP', 'evidence_obligation'].includes(row.routing_target)
+      && matches.length === 1 && TP_PLANNING_FORMAT.detail_columns.slice(0, -1).every(key => filled(detail[key]))
+      && decision && sourceValid(root, state, detail.source_ref);
+    ids.add(id);
+    if (!valid) { open.push(`Invalid clarification assignment/details/source: ${id}`); continue; }
+    if (row.gap_status === 'resolved') {
+      if (decision.status !== 'resolved' || !resolutionValid(root, state, id, detail.resolution_evidence)) open.push(`Clarification requires current recorded answer/source evidence: ${id}`);
+      continue;
+    }
+    open.push(`Material clarification ${id}: ${detail.question}`);
+    if (decision.status !== 'open') { open.push(`Keep clarification planning decision open: ${id}`); continue; }
+    clarifications.push({ finding_id: id, gate: row.routing_target,
+      question: detail.question, blocking_reason: detail.blocking_reason, required_answer: detail.required_answer,
+      owner: detail.owner, source_ref: detail.source_ref });
+  }
+  if (details.some(detail => !ids.has(detail.finding_id))) open.push('Clarification detail references unknown finding');
+  return done();
+}

package/runtime/core/lib/control-evaluation/traceability-readiness.js

@@ -0,0 +1,212 @@
+import { readAcceptanceCriteria } from "./acceptance-criteria.js";
+export { readAcceptanceCriteria, ACCEPTANCE_CRITERIA_FORMAT } from "./acceptance-criteria.js";
+import { section, tableRows } from "./markdown-table.js";
+import { evaluateTpPlanningContent } from "./tp-planning.js";
+import { readFileSync } from "../control-read/fs.js";
+import { resolvedArtefactFile } from "./run-state.js";
+
+export const TRACEABILITY_CONTRACT = "Traceability contract: criteria-chain-v1";
+
+const TASK_ID = /^T-[A-Z0-9]+(?:-[A-Z0-9]+)*$/u;
+const SCENARIO_ID = /^SCN-[A-Z0-9]+(?:-[A-Z0-9]+)*$/u;
+const DESIGN_DECISION_ID = /^SDD-[A-Z0-9]+(?:-[A-Z0-9]+)*$/u;
+
+export const TP_AUTHORING_FORMAT = Object.freeze({ declaration: TRACEABILITY_CONTRACT,
+  tasks: Object.freeze({ section: 'Task List', columns: Object.freeze(['task_id', 'task']), id_pattern: TASK_ID.source }),
+  verification: Object.freeze({ section: 'Verification Traceability', columns: Object.freeze(['criterion_id', 'design_decision_id', 'task_id', 'scenario_id', 'expected_result', 'evidence']), scenario_id_pattern: SCENARIO_ID.source, design_decision_id_pattern: DESIGN_DECISION_ID.source,
+    cell_rule: 'One design_decision_id per row; criterion_id/scenario_id pairs are unique. Use separate applicable scenarios for additional design decisions.',
+    table_rule: 'Rows must remain contiguous under their declared Markdown table header.',
+    required_coverage: 'Every PRD criterion and every SD decision associated with that criterion needs a declared task, scenario, observable expected_result and evidence.' }),
+});
+
+function artifactText(targetDir, runState, type) {
+  const path = resolvedArtefactFile(targetDir, runState.artefacts.get(type)?.path);
+  return path ? readFileSync(path, "utf8") : null;
+}
+
+
+const acceptanceCriteria = readAcceptanceCriteria;
+
+
+function unfinished(value) {
+  const text = String(value ?? "").trim();
+  return !text || /^(?:<|tbd\b|to confirm\b|todo\b)/iu.test(text);
+}
+
+function reasonedNone(value) {
+  const text = String(value ?? "").trim();
+  if (!/^(?:none|n\/a|not applicable)\b/iu.test(text)) return false;
+  return /^(?:none|n\/a|not applicable)\s*(?:[:—-]\s*.+)$/iu.test(text);
+}
+
+function designDecisionIds(value) {
+  const text = String(value ?? "").trim();
+  if (reasonedNone(text) && !/^(?:none|n\/a|not applicable)$/iu.test(text)) return [];
+  return text.split(",").map((item) => item.trim().toUpperCase());
+}
+
+function architectureDecisionIds(markdown) {
+  const body = section(markdown, "Architecture Decisions");
+  const openItems = [];
+  const ids = [];
+  let none = false;
+  if (body === null) return { ids, none, openItems: ["SD Architecture Decisions section is missing"] };
+  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)) {
+        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");
+      none = true;
+      continue;
+    }
+    const match = decision.match(/^(SDD-[A-Z0-9]+(?:-[A-Z0-9]+)*)\s*:\s*(.+)$/iu);
+    if (!match) {
+      openItems.push("Each binding SD decision needs a stable SDD-... ID and rationale");
+      continue;
+    }
+    const id = match[1].toUpperCase();
+    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`);
+    }
+  }
+  if (!ids.length && !none) openItems.push("List binding SD decisions by SDD ID, or record a reasoned none");
+  return { ids, none, openItems };
+}
+
+function addCriterionCoverageErrors(openItems, criterionIds, rows, { exactlyOnce }) {
+  const expected = new Set(criterionIds);
+  const counts = new Map();
+  for (const row of rows) {
+    const id = String(row.criterion_id ?? "").trim().toUpperCase();
+    if (!id || !expected.has(id)) {
+      openItems.push(`Unknown or missing criterion_id in traceability table: ${id || "empty"}`);
+      continue;
+    }
+    counts.set(id, (counts.get(id) ?? 0) + 1);
+  }
+  for (const id of criterionIds) {
+    const count = counts.get(id) ?? 0;
+    if (!count) openItems.push(`PRD criterion ${id} is not mapped`);
+    else if (exactlyOnce && count !== 1) openItems.push(`PRD criterion ${id} must have exactly one SD mapping`);
+  }
+}
+
+export function evaluatePrdCriteriaReadiness(markdown) {
+  if (!markdown.includes(TRACEABILITY_CONTRACT)) return { ready: true, open_items: [], contract: "legacy" };
+  const criteria = acceptanceCriteria(markdown);
+  return { ready: criteria.openItems.length === 0, open_items: criteria.openItems, diagnostics: criteria.diagnostics, contract: "criteria-chain-v1" };
+}
+
+export function evaluateSdTraceability(targetDir, runState) {
+  const prd = artifactText(targetDir, runState, "PRD");
+  const sd = artifactText(targetDir, runState, "SD");
+  if (!sd) return { ready: true, open_items: [], contract: "not_linked" };
+  if (!prd?.includes(TRACEABILITY_CONTRACT) && !sd.includes(TRACEABILITY_CONTRACT)) {
+    return { ready: true, open_items: [], contract: "legacy" };
+  }
+  const openItems = [];
+  if (!prd) openItems.push("Approved PRD artefact is missing for SD traceability");
+  if (!prd?.includes(TRACEABILITY_CONTRACT)) openItems.push("PRD must declare the criteria-chain-v1 traceability contract");
+  if (!sd.includes(TRACEABILITY_CONTRACT)) openItems.push("SD must retain the criteria-chain-v1 traceability contract");
+  const criteria = acceptanceCriteria(prd ?? "");
+  openItems.push(...criteria.openItems);
+  const architecture = architectureDecisionIds(sd);
+  openItems.push(...architecture.openItems);
+  const required = ["criterion_id", "design_response", "source_of_truth", "design_decision_ids", "compatibility_risk"];
+  const table = tableRows(sd, "Acceptance Traceability", required);
+  if (table.error) openItems.push(table.error);
+  const mappedDecisions = new Set();
+  for (const row of table.rows) {
+    for (const column of required.slice(1)) if (unfinished(row[column])) openItems.push(`SD mapping for ${row.criterion_id || "an acceptance criterion"} needs ${column}`);
+    const decisions = designDecisionIds(row.design_decision_ids);
+    if (!decisions.length && !reasonedNone(row.design_decision_ids)) openItems.push(`SD mapping for ${row.criterion_id || "an acceptance criterion"} needs an SDD-... id or a reasoned none`);
+    for (const id of decisions) {
+      if (!DESIGN_DECISION_ID.test(id)) openItems.push(`Invalid SD design_decision_id: ${id}`);
+      else mappedDecisions.add(id);
+    }
+  }
+  addCriterionCoverageErrors(openItems, criteria.ids, table.rows, { exactlyOnce: true });
+  for (const id of architecture.ids) if (!mappedDecisions.has(id)) openItems.push(`SD design decision ${id} is not mapped to a PRD criterion`);
+  for (const id of mappedDecisions) if (!architecture.ids.includes(id)) openItems.push(`SD mapping references undeclared decision ${id}`);
+  if (architecture.none && mappedDecisions.size) openItems.push("SD acceptance mappings must use reasoned none when Architecture Decisions records none");
+  return { ready: openItems.length === 0, open_items: [...new Set(openItems)], contract: "criteria-chain-v1" };
+}
+
+export function evaluateTpTraceability(targetDir, runState) {
+  const prd = artifactText(targetDir, runState, "PRD");
+  const sd = artifactText(targetDir, runState, "SD");
+  const tp = artifactText(targetDir, runState, "TP");
+  if (!tp) return { ready: true, open_items: [], contract: "not_linked" };
+  const planning = evaluateTpPlanningContent(targetDir, runState, sd ?? "", tp);
+  const strict = planning.declared || [prd, sd, tp].some((content) => content?.includes(TRACEABILITY_CONTRACT));
+  if (!strict) return { ready: true, open_items: [], contract: "legacy" };
+  const openItems = [];
+  if (!prd?.includes(TRACEABILITY_CONTRACT)) openItems.push("PRD must declare the criteria-chain-v1 traceability contract");
+  if (!sd?.includes(TRACEABILITY_CONTRACT)) openItems.push("SD must retain the criteria-chain-v1 traceability contract");
+  if (!tp.includes(TRACEABILITY_CONTRACT)) openItems.push("TP must retain the criteria-chain-v1 traceability contract");
+  const criteria = acceptanceCriteria(prd ?? "");
+  openItems.push(...criteria.openItems);
+  const sdReadiness = evaluateSdTraceability(targetDir, runState);
+  if (!sdReadiness.ready) openItems.push(...sdReadiness.open_items.map((item) => `Upstream SD: ${item}`));
+  const decisionTable = tableRows(sd ?? "", "Acceptance Traceability", ["criterion_id", "design_response", "source_of_truth", "design_decision_ids", "compatibility_risk"]);
+  if (decisionTable.error) openItems.push(`Upstream SD: ${decisionTable.error}`);
+  const decisionsByCriterion = new Map();
+  for (const row of decisionTable.rows) decisionsByCriterion.set(String(row.criterion_id ?? "").toUpperCase(), designDecisionIds(row.design_decision_ids));
+
+  const taskTable = tableRows(tp, TP_AUTHORING_FORMAT.tasks.section, TP_AUTHORING_FORMAT.tasks.columns);
+  if (taskTable.error) openItems.push(taskTable.error);
+  const taskIds = new Set();
+  for (const row of taskTable.rows) {
+    const id = String(row.task_id ?? "").trim().toUpperCase();
+    if (!TASK_ID.test(id)) openItems.push(`Invalid TP task_id: ${id || "empty"}`);
+    else if (taskIds.has(id)) openItems.push(`Duplicate TP task_id: ${id}`);
+    else taskIds.add(id);
+    if (unfinished(row.task)) openItems.push(`TP task ${id || "without id"} needs a task description`);
+  }
+
+  const required = TP_AUTHORING_FORMAT.verification.columns;
+  const verification = tableRows(tp, TP_AUTHORING_FORMAT.verification.section, required);
+  if (verification.error) openItems.push(verification.error);
+  addCriterionCoverageErrors(openItems, criteria.ids, verification.rows, { exactlyOnce: false });
+  const scenarios = new Set();
+  const verifiedDecisions = new Map();
+  for (const row of verification.rows) {
+    const criterion = String(row.criterion_id ?? "").trim().toUpperCase();
+    const task = String(row.task_id ?? "").trim().toUpperCase();
+    const scenario = String(row.scenario_id ?? "").trim().toUpperCase();
+    const decision = String(row.design_decision_id ?? "").trim().toUpperCase();
+    if (!taskIds.has(task)) openItems.push(`TP scenario ${scenario || "without id"} references unknown task_id: ${task || "empty"}`);
+    if (!SCENARIO_ID.test(scenario)) openItems.push(`Invalid TP scenario_id: ${scenario || "empty"}`);
+    const scenarioKey = `${criterion}:${scenario}`;
+    if (scenarios.has(scenarioKey)) openItems.push(`Duplicate TP scenario mapping: ${scenarioKey}`);
+    scenarios.add(scenarioKey);
+    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}`);
+      else {
+        if (!verifiedDecisions.has(criterion)) verifiedDecisions.set(criterion, new Set());
+        verifiedDecisions.get(criterion).add(decision);
+      }
+    } else if (!reasonedNone(decision)) {
+      openItems.push(`TP scenario ${scenario || "without id"} needs the mapped SDD-... id or a reasoned none`);
+    }
+  }
+  for (const [criterion, expectedDecisions] of decisionsByCriterion) {
+    for (const decision of expectedDecisions) {
+      if (!verifiedDecisions.get(criterion)?.has(decision)) openItems.push(`SD decision ${decision} for ${criterion} has no TP verification scenario`);
+    }
+  }
+  openItems.push(...planning.open_items);
+  return { ready: openItems.length === 0, open_items: [...new Set(openItems)], contract: "criteria-chain-v1",
+    ...(planning.clarifications.length ? { clarifications: planning.clarifications } : {}) };
+}

package/runtime/core/lib/control-evaluation/ur-readiness.js

@@ -0,0 +1,47 @@
+import { readFileSync } from "../control-read/fs.js";
+import { resolvedArtefactFile } from "./run-state.js";
+import { resolveArtifactPresentationLanguages } from "../resources/context.js";
+import { evaluateApprovalSummaryReadiness, renderApprovalSummaryIssue } from "../control-state/run-presentation-render.js";
+import { previewRequirement } from '../control-state/preview-review.js';
+
+export const UR_AUTHORING_FORMAT = Object.freeze({
+  sections: Object.freeze(["Problem", "Goal", "Affected Users", "Scope", "Non-Goals", "Acceptance Signals", "Existing Source Of Truth", "Risks And Unknowns", "Next Step"]),
+  readiness_contract: "Requirements clarification: complete", legacy: "legacy documents remain subject to their existing readiness rules",
+  preview_requirement: Object.freeze({ field: 'Preview requirement', placement: 'initial metadata before first section',
+    values: Object.freeze(['none', 'before_prd_interactive']), legacy: 'unmarked existing URs remain unchanged' }),
+});
+const sections = UR_AUTHORING_FORMAT.sections;
+const templatePrompts = new Set([
+  "What user, business or operational problem should be solved?", "What outcome should become possible?",
+  "Which people or roles experience the problem and benefit from the outcome?", "What is included in this first slice?",
+  "What is explicitly not part of this UR?", "How will we know the need is clear enough for PRD?",
+  "Which existing repository artefacts, docs, code paths or decisions must be respected?",
+  "Which questions must Brownfield Review, PRD, SD or later implementation-preparation Brownfield Analysis clarify?",
+]);
+// Marker absence preserves legacy compatibility; completeness does not prove semantic approval.
+export function evaluateUrReadiness(targetDir, runState, { presentationLanguage } = {}) {
+  const path = resolvedArtefactFile(targetDir, runState.artefacts.get("UR")?.path);
+  if (!path) return null;
+  const content = readFileSync(path, "utf8");
+  try { previewRequirement(content); } catch (error) { return { ready: false, legacy: false, open_items: [error.message] }; }
+  const markers = content.match(/^Requirements clarification:[^\r\n]*$/gmu) ?? [];
+  if (!markers.length) return { ready: true, legacy: true, open_items: [] };
+  const open = markers.length === 1 && markers[0].trim() === UR_AUTHORING_FORMAT.readiness_contract ? [] : ["Requirements clarification"];
+  const blocks = content.split(/^##[ \t]+/mu).slice(1).map(block => {
+    const [heading, ...body] = block.split(/\r?\n/u);
+    return { heading: heading.replace(/^\d+\.[ \t]*/u, "").trim(), body: body.join("\n").trim() };
+  });
+  for (const section of sections) {
+    const matches = blocks.filter(block => block.heading === section);
+    const body = matches[0]?.body ?? "";
+    if (matches.length !== 1 || !body || templatePrompts.has(body) || /<[^>]+>|^(?:tbd|todo|to confirm)[ \t]*$/imu.test(body)) open.push(section);
+  }
+  const languages = resolveArtifactPresentationLanguages(targetDir, presentationLanguage);
+  const summary = evaluateApprovalSummaryReadiness("UR", content, languages);
+  if (!summary.ready) open.push(summary.required_heading);
+  // Name the unreadable field and its expected line, not only the section heading.
+  if (summary.reason === "approval_summary_field_unreadable") open.push(renderApprovalSummaryIssue(summary, {
+    path, presentationLanguage: languages.presentation_language,
+  }));
+  return { ready: open.length === 0, legacy: false, open_items: open, approval_summary: summary };
+}

package/{generated/plugins/agdf/runtime/create-agdf → runtime/core}/lib/control-evaluation/verified-change.js

@@ -1,6 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
-import { execFileSync } from "node:child_process";
-import { isAbsolute, posix, relative, resolve } from "node:path";
+import { readFileSync } from "../control-read/fs.js";
+import { containedRegularFile, isSafeControlRelativePath } from "../control-state/contained-file.js";
 import { cleanStatusCell, isPlaceholderValue } from "./shared.js";
 
 export function extractField(content, field) {
@@ -18,43 +17,24 @@ export function parseVerifiedChangePathList(value) {
 }
 
 export function isSafeRepoRelativePath(value) {
-  if (!value || value === "none" || value.startsWith("/") || value.includes("\\")) return false;
-  const normalized = posix.normalize(value);
-  return normalized !== "." && normalized !== ".." && !normalized.startsWith("../") && normalized === value;
-}
-
-export function gitPathList(targetDir, args) {
-  try {
-    return execFileSync("git", args, { cwd: targetDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
-      .split("\n")
-      .map((item) => item.trim())
-      .filter(Boolean);
-  } catch {
-    return null;
-  }
-}
-
-export function gitValue(targetDir, args) {
-  try {
-    return execFileSync("git", args, { cwd: targetDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-  } catch {
-    return null;
-  }
+  return isSafeControlRelativePath(value);
 }
 
 export function readVerifiedChangeRecord(targetDir, runState) {
   const artefact = runState.artefacts.get("Verified Change");
   if (!artefact?.path || isPlaceholderValue(artefact.path)) return { status: "missing", path: "", content: "" };
   if (!isSafeRepoRelativePath(artefact.path)) return { status: "invalid", path: artefact.path, content: "", error: "record_path_invalid" };
-  const absolutePath = resolve(targetDir, artefact.path);
-  const relativePath = relative(resolve(targetDir), absolutePath);
-  if (isAbsolute(relativePath) || relativePath === ".." || relativePath.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || !existsSync(absolutePath)) {
+  const result = containedRegularFile(targetDir, artefact.path);
+  if (result.status !== "valid") {
+    if (result.status === "invalid") return { status: "invalid", path: artefact.path, content: "", error: "record_path_invalid" };
     return { status: "missing", path: artefact.path, content: "", error: "record_missing" };
   }
-  return { status: "present", path: artefact.path, content: readFileSync(absolutePath, "utf8") };
+  return { status: "present", path: artefact.path, content: readFileSync(result.path, "utf8") };
 }
 
-export function evaluateVerifiedChange(targetDir, runState) {
+export function evaluateVerifiedChange(targetDir, runState, dependencies = {}) {
+  const gitPathList = dependencies.gitPathList ?? (() => null);
+  const gitValue = dependencies.gitValue ?? (() => null);
   const record = readVerifiedChangeRecord(targetDir, runState);
   const findings = [];
   const add = (code, message, nextStep, severity = "revise") => findings.push({