create-agdf 0.14.4 → 0.20.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/preview-review.js

@@ -0,0 +1,136 @@
+import { readFileSync, statSync } from '../control-read/fs.js';
+import { containedRegularFile, hasSymlinkComponent, isSafeControlRelativePath } from './contained-file.js';
+import { canonicalJson, digest, exactObject, DIGEST_PATTERN } from './approval-command-contract.js';
+import { canonicalRunText } from './run-text.js';
+import { readAcceptanceCriteria } from '../control-evaluation/acceptance-criteria.js';
+import { renderPreview, PREVIEW_RENDER_LIMIT } from './preview-render.js';
+
+export const PREVIEW_LIMITS = Object.freeze({ descriptor: 16384, files: 32, file: 131072, total: 1048576, rendered: PREVIEW_RENDER_LIMIT, chunk: 131072 });
+export const PREVIEW_REVIEW_FORMAT = Object.freeze({ section: 'Preview Review', fence: 'json', schema_version: '1',
+  fields: Object.freeze(['schema_version', 'version', 'source_ur_digest', 'entry', 'files', 'review_task', 'scenarios', 'criterion_ids', 'open_questions']),
+  file_fields: Object.freeze(['path', 'digest', 'bytes', 'media_type']), limits: PREVIEW_LIMITS,
+  entry: '.agdf/control/artefacts/<run_id>/previews/<short-name-vN>/index.html', digest_rule: 'raw bytes for files; canonical approved UR text for source_ur_digest',
+});
+export const previewError = code => { throw Error(`preview_${code}`); };
+const text = (value, max = 1200) => typeof value === 'string' && !!value.trim() && value.length <= max && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/u.test(value);
+const media = new Set(['text/html', 'text/css', 'text/javascript', 'image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/svg+xml']);
+
+// Initial metadata only. Examples, later prose and code blocks cannot declare a requirement.
+export function previewRequirement(content) {
+  const header = String(content).replace(/^\uFEFF/u, '').split(/^##[ \t]/mu)[0];
+  const lines = header.split(/\r?\n/u), fields = [];
+  let fence = false;
+  for (const line of lines) {
+    if (/^\s*(?:```|~~~)/u.test(line)) { fence = !fence; continue; }
+    if (!fence && /^Preview requirement:/u.test(line)) fields.push(line.slice(20).trim());
+  }
+  if (fields.length > 1 || fields.some(value => !['none', 'before_prd_interactive'].includes(value))) previewError('requirement_invalid');
+  return fields[0] === 'before_prd_interactive';
+}
+
+// Reject duplicate JSON keys before JSON.parse can discard their first value.
+function uniqueJson(source) {
+  let offset = 0;
+  const ws = () => { while (/\s/u.test(source[offset] ?? '') && offset < source.length) ++offset; };
+  const string = () => {
+    const start = offset++;
+    while (offset < source.length) { const c = source[offset++]; if (c === '\\') ++offset; else if (c === '"') return JSON.parse(source.slice(start, offset)); }
+    previewError('descriptor_invalid');
+  };
+  const value = (depth = 0) => {
+    if (depth > 32) previewError('descriptor_invalid');
+    ws(); const c = source[offset];
+    if (c === '"') { string(); return; }
+    if (c === '{' || c === '[') {
+      ++offset; ws(); const end = c === '{' ? '}' : ']', names = new Set();
+      if (source[offset] === end) { ++offset; return; }
+      for (;;) {
+        ws();
+        if (c === '{') { if (source[offset] !== '"') previewError('descriptor_invalid'); const key = string(); if (names.has(key)) previewError('descriptor_duplicate_key'); names.add(key); ws(); if (source[offset++] !== ':') previewError('descriptor_invalid'); }
+        value(depth + 1); ws(); if (source[offset] === end) { ++offset; return; }
+        if (source[offset++] !== ',') previewError('descriptor_invalid');
+      }
+    }
+    const primitive = source.slice(offset).match(/^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/u)?.[0];
+    if (!primitive) previewError('descriptor_invalid'); offset += primitive.length;
+  };
+  try { value(); ws(); if (offset !== source.length) previewError('descriptor_invalid'); return JSON.parse(source); }
+  catch (error) { if (error.message.startsWith('preview_')) throw error; previewError('descriptor_invalid'); }
+}
+
+function descriptorSource(content) {
+  const lines = String(content).replace(/\r\n?/gu, '\n').split('\n');
+  let fence = null, section = false, seen = 0, collecting = false, closed = false, html = false;
+  const body = [];
+  for (const line of lines) {
+    if (collecting) { if (line === '```') { collecting = false; closed = true; } else body.push(line); continue; }
+    if (fence) { if (line.startsWith(fence)) fence = null; continue; }
+    if (/^<!--/u.test(line)) html = true;
+    if (html) { if (line.includes('-->')) html = false; continue; }
+    if (/^## /u.test(line)) { section = line.trim() === '## Preview Review'; if (section) ++seen; continue; }
+    if (section && line === '```json') { if (closed) previewError('descriptor_invalid'); collecting = true; continue; }
+    const mark = line.match(/^ {0,3}(`{3,}|~{3,})/u)?.[1];
+    if (mark) { fence = mark; if (section) previewError('descriptor_invalid'); continue; }
+    if (section && line.trim()) previewError('descriptor_invalid');
+  }
+  if (!seen) return null;
+  if (seen !== 1 || !closed || collecting) previewError('descriptor_invalid');
+  const source = body.join('\n');
+  if (Buffer.byteLength(source) > PREVIEW_LIMITS.descriptor) previewError('descriptor_limit');
+  return uniqueJson(source);
+}
+
+export function validatePreviewDescriptor(row, runId, criteria, urDigest) {
+  if (Buffer.byteLength(canonicalJson(row)) > PREVIEW_LIMITS.descriptor) previewError('descriptor_limit');
+  if (!exactObject(row, PREVIEW_REVIEW_FORMAT.fields)
+    || row.schema_version !== '1' || !/^[a-z][a-z0-9-]{0,63}-v[1-9][0-9]{0,5}$/u.test(row.version ?? '')
+    || !DIGEST_PATTERN.test(row.source_ur_digest ?? '') || urDigest && row.source_ur_digest !== urDigest
+    || !text(row.review_task) || !Array.isArray(row.scenarios) || !row.scenarios.length || row.scenarios.length > 16
+    || !row.scenarios.every(v => text(v, 240)) || !Array.isArray(row.open_questions) || row.open_questions.length > 16 || !row.open_questions.every(v => text(v))
+    || !Array.isArray(row.criterion_ids) || !row.criterion_ids.length || row.criterion_ids.length > 64
+    || new Set(row.criterion_ids).size !== row.criterion_ids.length || !row.criterion_ids.every(id => /^[A-Z][A-Z0-9-]*$/u.test(id) && (!criteria || criteria.includes(id)))
+    || !Array.isArray(row.files) || !row.files.length || row.files.length > PREVIEW_LIMITS.files) previewError('descriptor_invalid');
+  const prefix = `.agdf/control/artefacts/${runId}/previews/${row.version}/`;
+  if (row.entry !== prefix + 'index.html') previewError('entry_invalid');
+  let previous = '', total = 0;
+  for (const file of row.files) {
+    if (!exactObject(file, PREVIEW_REVIEW_FORMAT.file_fields) || !isSafeControlRelativePath(file.path)
+      || !file.path.startsWith(prefix) || /[%?#\s<>"']/u.test(file.path) || file.path <= previous
+      || !DIGEST_PATTERN.test(file.digest ?? '') || !Number.isSafeInteger(file.bytes) || file.bytes < 1 || file.bytes > PREVIEW_LIMITS.file
+      || !media.has(file.media_type)) previewError('file_binding_invalid');
+    previous = file.path; total += file.bytes;
+  }
+  if (total > PREVIEW_LIMITS.total || row.files.find(f => f.path === row.entry)?.media_type !== 'text/html') previewError('file_limit');
+  return row;
+}
+
+export function readPreviewBytes(root, path) {
+  if (hasSymlinkComponent(root, path)) previewError('path_unsafe');
+  const file = containedRegularFile(root, path);
+  if (file.status !== 'valid' || statSync(file.path).size > PREVIEW_LIMITS.file) previewError('file_unavailable');
+  const bytes = readFileSync(file.path);
+  if (bytes.length > PREVIEW_LIMITS.file) previewError('file_limit');
+  return bytes;
+}
+
+export function inspectPreviewReview(root, { runId, urContent, prdContent, readBytes = path => readPreviewBytes(root, path) }) {
+  const required = previewRequirement(urContent), descriptor = descriptorSource(prdContent);
+  if (!descriptor) { if (required) previewError('descriptor_missing'); return null; }
+  const criteria = readAcceptanceCriteria(prdContent);
+  if (criteria.diagnostics.length) previewError('criteria_invalid');
+  validatePreviewDescriptor(descriptor, runId, criteria.ids, digest(canonicalRunText(urContent)));
+  const files = descriptor.files.map(file => {
+    const bytes = readBytes(file.path);
+    if (!Buffer.isBuffer(bytes) || bytes.length !== file.bytes || digest(bytes) !== file.digest) previewError('file_changed');
+    return { ...file, data: bytes };
+  });
+  const html = renderPreview(descriptor, files);
+  if (Buffer.byteLength(html) > PREVIEW_LIMITS.rendered) previewError('render_limit');
+  return { descriptor, descriptor_digest: digest(canonicalJson(descriptor)), files, html, rendered_digest: digest(html), rendered_bytes: Buffer.byteLength(html) };
+}
+
+export function previewForState(root, state, { readBytes } = {}) {
+  const runId = state.run_id ?? state.meta?.run_id;
+  const read = type => { const path = state.artefacts.get(type)?.path?.replace(/^`|`$/gu, ''); return path ? (readBytes ? readBytes(path) : readPreviewBytes(root, path)).toString('utf8') : ''; };
+  return inspectPreviewReview(root, { runId, urContent: read('UR'), prdContent: read('PRD'), readBytes });
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/preview-snapshot.js

@@ -0,0 +1,108 @@
+import { closeSync, constants, fsyncSync, openSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { canonicalJson, digest, exactObject, DIGEST_PATTERN } from './approval-command-contract.js';
+import { PREVIEW_LIMITS, previewError, readPreviewBytes, validatePreviewDescriptor } from './preview-review.js';
+import { canonicalRunText } from './run-text.js';
+import { readFileSync, statSync } from '../control-read/fs.js';
+import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
+
+const prefix = (runId, id) => `.agdf/control/runs/${runId}/presentations/${id}`;
+export function previewSnapshotBinding(preview, runId, id) {
+  const start = prefix(runId, id), bytes = Buffer.from(preview.html);
+  const chunks = [];
+  for (let offset = 0; offset < bytes.length; offset += PREVIEW_LIMITS.chunk) {
+    const data = bytes.subarray(offset, offset + PREVIEW_LIMITS.chunk);
+    chunks.push({ snapshot: `${start}.preview-${chunks.length}`, bytes: data.length, digest: digest(data) });
+  }
+  return { descriptor: preview.descriptor, descriptor_digest: preview.descriptor_digest, renderer_policy: 1,
+    rendered_digest: preview.rendered_digest, rendered_bytes: preview.rendered_bytes,
+    files: preview.files.map((file, index) => ({ ...preview.descriptor.files[index], snapshot: `${start}.preview-file-${index}` })), chunks };
+}
+
+export function validPreviewSnapshot(row, runId, id) {
+  try {
+    if (!exactObject(row, ['descriptor', 'descriptor_digest', 'renderer_policy', 'rendered_digest', 'rendered_bytes', 'files', 'chunks'])
+      || row.renderer_policy !== 1 || row.descriptor_digest !== digest(canonicalJson(row.descriptor))
+      || !DIGEST_PATTERN.test(row.rendered_digest ?? '') || !Number.isSafeInteger(row.rendered_bytes)
+      || row.rendered_bytes < 1 || row.rendered_bytes > PREVIEW_LIMITS.rendered) return false;
+    validatePreviewDescriptor(row.descriptor, runId);
+    const start = prefix(runId, id);
+    if (!Array.isArray(row.files) || row.files.length !== row.descriptor.files.length
+      || row.files.some((file, index) => !exactObject(file, ['path', 'digest', 'bytes', 'media_type', 'snapshot'])
+        || file.snapshot !== `${start}.preview-file-${index}`
+        || canonicalJson(Object.fromEntries(Object.entries(file).filter(([key]) => key !== 'snapshot'))) !== canonicalJson(row.descriptor.files[index]))) return false;
+    if (!Array.isArray(row.chunks) || !row.chunks.length || row.chunks.length > 16
+      || row.chunks.some((chunk, index) => !exactObject(chunk, ['snapshot', 'bytes', 'digest']) || chunk.snapshot !== `${start}.preview-${index}`
+        || !Number.isSafeInteger(chunk.bytes) || chunk.bytes < 1 || chunk.bytes > PREVIEW_LIMITS.chunk || !DIGEST_PATTERN.test(chunk.digest ?? '')
+        || index < row.chunks.length - 1 && chunk.bytes !== PREVIEW_LIMITS.chunk)
+      || row.chunks.reduce((total, chunk) => total + chunk.bytes, 0) !== row.rendered_bytes) return false;
+    return true;
+  } catch { return false; }
+}
+
+export function publishPreviewSnapshot(root, record, preview, { resume = false, checkpoint = () => {} } = {}) {
+  const binding = record.preview_review;
+  if (!binding) return;
+  const html = Buffer.from(preview.html);
+  const outputs = [...binding.files.map((file, i) => ({ ...file, data: preview.files[i].data })),
+    ...binding.chunks.map((chunk, i) => ({ ...chunk, data: html.subarray(i * PREVIEW_LIMITS.chunk, i * PREVIEW_LIMITS.chunk + chunk.bytes) })),
+    { snapshot: prefix(record.run_id, record.presentation_id) + '.preview.html', digest: binding.rendered_digest, bytes: html.length, data: html }];
+  for (const output of outputs) {
+    let fd;
+    try { fd = openSync(join(root, output.snapshot), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600); }
+    catch (error) {
+      if (error.code !== 'EEXIST' || !resume) throw error;
+      const old = output.snapshot.endsWith('.html') ? readStandalone(root, record) : readPreviewBytes(root, output.snapshot);
+      if (old.length !== output.bytes || digest(old) !== output.digest) previewError('snapshot_invalid');
+      continue;
+    }
+    try { writeFileSync(fd, output.data); fsyncSync(fd); } finally { closeSync(fd); }
+    checkpoint('presentation_preview_file_published');
+  }
+}
+
+export function readPreviewSnapshot(root, record, { readBytes = path => readPreviewBytes(root, path), current = false } = {}) {
+  const row = record.preview_review;
+  if (record.schema_version !== 5 || !validPreviewSnapshot(row, record.run_id, record.presentation_id)) previewError('snapshot_invalid');
+  for (const file of row.files) {
+    const bytes = readBytes(file.snapshot);
+    if (!bytes || bytes.length !== file.bytes || digest(bytes) !== file.digest) previewError('snapshot_changed');
+    if (current) { const live = readBytes(file.path); if (!live || live.length !== file.bytes || digest(live) !== file.digest) previewError('file_changed'); }
+  }
+  const chunks = row.chunks.map(chunk => {
+    const bytes = readBytes(chunk.snapshot);
+    if (!bytes || bytes.length !== chunk.bytes || digest(bytes) !== chunk.digest) previewError('snapshot_changed');
+    return bytes;
+  });
+  const bytes = Buffer.concat(chunks);
+  if (bytes.length !== row.rendered_bytes || digest(bytes) !== row.rendered_digest) previewError('snapshot_changed');
+  return bytes;
+}
+
+export function validateCurrentPreviewRecord(root, record) {
+  if (record.schema_version !== 5) return;
+  readPreviewSnapshot(root, record, { current: true });
+  readStandalone(root, record);
+  const base = `.agdf/control/artefacts/${record.run_id}/`;
+  if (digest(readPreviewBytes(root, base + 'PRD.md')) !== record.document_digest
+    || digest(canonicalRunText(readPreviewBytes(root, base + 'UR.md').toString('utf8'))) !== record.preview_review.descriptor.source_ur_digest) previewError('source_changed');
+}
+
+// A checked full-document access copy. The immutable chunk set remains the
+// historical authority; archives reconstruct it without this derived cache.
+function readStandalone(root, record) {
+  const path = prefix(record.run_id, record.presentation_id) + '.preview.html', file = containedRegularFile(root, path);
+  if (hasSymlinkComponent(root, path) || file.status !== 'valid' || statSync(file.path).size !== record.preview_review.rendered_bytes) previewError('standalone_unavailable');
+  const bytes = readFileSync(file.path);
+  if (bytes.length > PREVIEW_LIMITS.rendered || digest(bytes) !== record.preview_review.rendered_digest) previewError('standalone_changed');
+  return bytes;
+}
+
+// Proof readers may be archive-bound. Never repair history with live filesystem bytes.
+export function previewProof(record, { rawFileDigest, fileDigest }) {
+  const row = record.preview_review;
+  if (!validPreviewSnapshot(row, record.run_id, record.presentation_id)) return false;
+  if (row.files.some(file => rawFileDigest(file.snapshot) !== file.digest || rawFileDigest(file.path) !== file.digest)
+    || row.chunks.some(chunk => rawFileDigest(chunk.snapshot) !== chunk.digest)) return false;
+  return fileDigest(`.agdf/control/artefacts/${record.run_id}/UR.md`) === row.descriptor.source_ur_digest;
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/qa-deviation-acceptance.js

@@ -0,0 +1,82 @@
+import { canonicalJson, digest, exactObject } from './approval-command-contract.js';
+import { inspectQaReports } from '../control-evaluation/qa-follow-up.js';
+import { interactionLocales } from '../resources/context.js';
+
+const fields = ['schema_version', 'reviewer', 'usage_scope', 'deviations'];
+const itemFields = ['finding_id', 'severity', 'risk', 'consequence', 'follow_up', 'owner'];
+const concrete = (value, limit = 600) => typeof value === 'string' && value.trim().length > 0
+  && value.length <= limit && !/^(?:tbd|todo|none|<)/iu.test(value.trim());
+const outcome = text => [...text.matchAll(/^- decision:[ \t]*(pass|passed|revise|block)[ \t]*$/gmu)].map(row => row[1]);
+
+// The existing QA report owns the proposal. It is never a second approval ledger,
+// a caller override flag, a passing test result or proof of native qualification.
+export function inspectQaDeviationAcceptance(root, state, readArtefact) {
+  const unavailable = reason => ({ eligible: false, accepted: false, reason });
+  const qa = state.artefacts.get('QA');
+  if (qa?.status !== 'revise' || !qa.path) return unavailable('qa_deviation_proposal_not_applicable');
+  const text = readArtefact(qa.path);
+  if (typeof text !== 'string' || !text.includes('## QA Deviation Acceptance')) return unavailable('qa_deviation_proposal_missing');
+  try {
+    if (!['UR', 'PRD', 'SD', 'TP'].every(gate => state.approvals.get(gate)?.status === 'approved')
+      || !['Brownfield Analysis', 'CD+Tests', 'CR', 'Clean Implementation Review', 'TP Review'].every(step => {
+        const row = state.artefacts.get(step) ?? state.artefacts.get({ CR: 'Code Review', 'Clean Implementation Review': 'Clean Review' }[step]);
+        return row?.path && ['done', ...(step === 'TP Review' ? ['revise'] : [])].includes(row.status);
+      })) return unavailable('qa_deviation_prerequisites_incomplete');
+    if (!['QA', 'CR', 'Clean Implementation Review', 'TP Review'].every(step =>
+      state.evidence_applicability?.by_step.get(step)?.applicability === 'current')) return unavailable('qa_deviation_evidence_not_current');
+    for (const step of ['CR', 'Clean Implementation Review']) {
+      const row = state.artefacts.get(step) ?? state.artefacts.get({ CR: 'Code Review', 'Clean Implementation Review': 'Clean Review' }[step]);
+      const decisions = outcome(readArtefact(row.path) ?? '');
+      if (decisions.length !== 1 || !['pass', 'passed'].includes(decisions[0])) return unavailable('qa_deviation_protected_review_not_pass');
+    }
+    if ([...(state.missing_evidence ?? []), ...(state.risks ?? [])].some(row => row.impact === 'block')) return unavailable('qa_deviation_hard_blocker');
+    const sections = text.split(/^## QA Deviation Acceptance\s*$/mu);
+    if (sections.length !== 2) return unavailable('qa_deviation_proposal_invalid');
+    const section = sections[1].split(/^## /mu)[0].trim();
+    const match = section.match(/^```json\s*\n([\s\S]*?)\n```$/u);
+    if (!match || Buffer.byteLength(match[1]) > 16000) return unavailable('qa_deviation_proposal_invalid');
+    const proposal = JSON.parse(match[1]);
+    if (!exactObject(proposal, fields) || proposal.schema_version !== '1' || !concrete(proposal.reviewer, 200)
+      || !concrete(proposal.usage_scope) || !Array.isArray(proposal.deviations) || !proposal.deviations.length || proposal.deviations.length > 16
+      || !proposal.deviations.every(row => exactObject(row, itemFields) && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(row.finding_id ?? '')
+        && ['low', 'medium'].includes(row.severity) && ['risk', 'consequence', 'follow_up', 'owner'].every(field => concrete(row[field])))) return unavailable('qa_deviation_proposal_invalid');
+    const ids = proposal.deviations.map(row => row.finding_id);
+    if (new Set(ids).size !== ids.length) return unavailable('qa_deviation_proposal_invalid');
+    const observations = inspectQaReports(root, state, state.run_id, 'revise', 64, true, { readArtefact });
+    if (observations.kind !== 'evidence' || observations.findings.some(row => row.target !== 'evidence_obligation')) return unavailable('qa_deviation_hard_blocker');
+    const described = new Map();
+    for (const row of observations.findings) {
+      const statement = canonicalJson({ target: row.target, evidence: row.evidence, action: row.action });
+      if (described.has(row.id) && described.get(row.id) !== statement) return unavailable('qa_deviation_scope_ambiguous');
+      described.set(row.id, statement);
+    }
+    const open = new Set(observations.findings.map(row => row.id));
+    if (open.size !== ids.length || ids.some(id => !open.has(id))) return unavailable('qa_deviation_scope_incomplete');
+    const acceptanceDigest = digest(`agdf-qa-deviation-acceptance/1\0${canonicalJson({ proposal, sources: observations.sources })}`);
+    const decided = state.presentation_decisions?.get('QA');
+    const acceptance = decided?.receipt?.effect?.qa_acceptance;
+    const accepted = state.approvals.get('QA')?.status === 'approved' && decided?.decided === true
+      && decided.action === 'approve' && acceptance?.kind === 'accepted_with_deviations' && acceptance.digest === acceptanceDigest
+      && canonicalJson(acceptance.deviation_ids) === canonicalJson(ids);
+    return { eligible: true, accepted, digest: acceptanceDigest, proposal, sources: observations.sources, qa_outcome: 'revise' };
+  } catch { return unavailable('qa_deviation_proposal_invalid'); }
+}
+
+export function qaDeviationPresentation(acceptance, language) {
+  if (!acceptance?.eligible) return null;
+  const german = String(language).toLowerCase().startsWith('de');
+  const labels = (german ? interactionLocales.locales.de : interactionLocales.locales.en).decisionCard;
+  const { proposal } = acceptance;
+  const summary = [acceptance.accepted ? labels.confirmedWithDeviations : labels.deviationAcceptanceIntro,
+    `${german ? 'Geltungsbereich' : 'Usage scope'}: ${proposal.usage_scope}`,
+    ...proposal.deviations.map(row => `- ${row.finding_id} (${german ? { low: 'gering', medium: 'mittel' }[row.severity] : row.severity}): ${row.risk}\n  ${german ? 'Folge' : 'Consequence'}: ${row.consequence}\n  ${german ? 'Nacharbeit' : 'Follow-up'}: ${row.follow_up}\n  ${german ? 'Verantwortlich' : 'Owner'}: ${row.owner}`),
+    acceptance.accepted ? (german
+      ? 'Diese Abweichungen wurden für die vorgelegte Fassung ausdrücklich akzeptiert. Der QA-Befund bleibt „Nachbessern“; fehlende Prüfungen und native Produktionsqualifikation sind nicht bestanden.'
+      : 'These deviations were explicitly accepted for the presented version. The QA result remains revise; missing tests and native production qualification are not marked passed.')
+      : (german ? 'Der QA-Befund bleibt „Nachbessern“. Mit deiner Freigabe akzeptierst du diese Abweichungen und deren Folgen; anschließend folgt UAT. Fehlende Prüfungen und native Produktionsqualifikation sind damit nicht bestanden.'
+        : 'The QA result remains revise. Your approval accepts these deviations and their consequences; UAT follows. Missing tests and native production qualification are not marked passed.')].join('\n\n');
+  return { kind: 'accepted_with_deviations', digest: acceptance.digest, summary,
+    approve_label: labels.approveWithDeviations, confirmed_label: labels.confirmedWithDeviations,
+    effect: german ? 'Du akzeptierst die aufgeführten Abweichungen. Als Nächstes folgt UAT.'
+      : 'You accept the listed deviations. UAT follows.' };
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/recording-formats.js

@@ -0,0 +1,29 @@
+// Field contracts shared by the existing recording/revision owners and selected Inspect
+// descriptors. These describe review input; they do not manufacture review findings.
+export const REVIEWED_REQUEST_FIELDS = Object.freeze(['schema_version', 'target_id', 'run_id', 'expected_revision_id', 'destination', 'source', 'relationship', 'review', 'update_draft']);
+export const REVIEW_PROOF_FIELDS = Object.freeze(['schema_version', 'target_id', 'run_id', 'relationship', 'destination', 'source', 'reviewer', 'reviewed']);
+export const REVISION_PROPOSAL_FIELDS = Object.freeze(['schema_version', 'target_id', 'run_id', 'expected_revision_id', 'operation_id', 'source_gate', 'reason', 'intended_change', 'sources', 'impact_assessment']);
+export const REVISION_IMPACT_FIELDS = Object.freeze(['reviewer', 'earliest_source', 'upstream', 'analyses', 'implementation_evidence', 'unresolved']);
+export const REVISION_UPSTREAM_FIELDS = Object.freeze(['type', 'path', 'digest', 'rationale']);
+export const REVISION_ANALYSIS_FIELDS = Object.freeze(['type', 'disposition', 'path', 'digest', 'reason']);
+export const REVISION_PROPOSAL_V2_FIELDS = Object.freeze([...REVISION_PROPOSAL_FIELDS, 'policy_version', 'initiating_phase', 'changed_statements', 'quality_assessment']);
+export const REVISION_STATEMENT_FIELDS = Object.freeze(['type', 'path', 'digest', 'statement', 'intended_change', 'reason']);
+export const REVISION_QUALITY_FIELDS = Object.freeze(['record', 'record_digest', 'operation_id', 'source_set_digest', 'sources', 'association', 'disposition', 'reason']);
+
+export const REVIEWED_REQUEST_FORMAT = Object.freeze({ schema_version: '1', fields: REVIEWED_REQUEST_FIELDS,
+  references: { destination: ['type', 'path', 'digest', 'status'], source: ['type', 'path', 'digest'], review: ['reviewer', 'path', 'digest'] },
+  relationship: 'Use the current gate relationship returned by this descriptor; source must be the current approved exact artefact.',
+  review_proof: { fields: REVIEW_PROOF_FIELDS, reviewed: true, equality: 'target/run/relationship/destination/source/reviewer must equal the reviewed request; hash the contained proof after canonical BOM removal and CRLF normalization' },
+  update_draft: 'false for first recording; true only for updating the same unapproved recorded draft with fresh reviewed mapping. Never update approved material.',
+  scope: 'All request, report and review proof paths belong to .agdf/control/artefacts/<run_id>/; each source is bounded to 131072 bytes.',
+  evidence: 'A real reviewed mapping is required. Authoring completeness alone does not prove derivation.' });
+export const REVISION_PROPOSAL_FORMAT = Object.freeze({ schema_version: '1', fields: REVISION_PROPOSAL_FIELDS,
+  supported_versions: ['1', '2'], expanded: { schema_version: '2', policy_version: 2, fields: REVISION_PROPOSAL_V2_FIELDS,
+    changed_statements: REVISION_STATEMENT_FIELDS, quality_assessment: REVISION_QUALITY_FIELDS,
+    initiating_phase: 'Actual current PRD/SD/TP/CD+Tests/QA/pending UAT; choose the earliest approved changed source, never by phase alone.',
+    quality: 'Cover every current registered analysis/result and evidence row exactly; bind report, source set, original operation and record digest. Unknown associations require reassess. Use the inspected current facts; no invented dependency proof.' },
+  impact_assessment: { fields: REVISION_IMPACT_FIELDS, upstream: REVISION_UPSTREAM_FIELDS, analyses: REVISION_ANALYSIS_FIELDS,
+    dispositions: ['retain', 'reassess'], unresolved: [], earliest_source: 'Must match source_gate; unchanged upstream needs actual rationale. UR requires reassess for both applicable analyses.' },
+  sources: 'Use the exact current sources returned by the existing preview boundary, in UR/PRD/SD/TP order; the eligible boundary determines the subset.',
+  preview: 'Read-only preview returns actual impact, preview_digest and the exact confirmation_selector. Do not derive authorization from a preview.',
+  recovery: 'Keep the original UUID, proposal and inspected pending digest/current recovery revision; never submit a new intent to repair the original.' });

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-artefact-recording.js

@@ -0,0 +1,81 @@
+import { readOperationSource } from "./run-operation-proof.js";
+import { randomUUID } from "node:crypto";
+import { canonicalJson, exactObject, resolveControlCommandTarget } from "./approval-command-contract.js";
+import { appendArtefactBinding, artefactBindingKey, readArtefactBindings, validArtefactBinding } from "./artefact-bindings.js";
+import { exactApprovedArtefacts, readContainedJson, validateBindingProof } from "./artefact-binding-proof.js";
+import { artefactFileDigest, computeRunSeals, runSealState } from "./run-seal.js";
+import { appendTableRow, upsertTableRow } from "./run-state-edits.js";
+import { relationshipForGate, sameRelationship } from "../control-evaluation/delivery-relationships.js";
+import { readFileSync } from "node:fs";
+import { containedRegularFile } from "./contained-file.js";
+import { readSourceRevisions } from "./run-source-revisions.js";
+import { REVIEWED_REQUEST_FIELDS } from './recording-formats.js';
+import { readReportDecision } from '../control-evaluation/report-decision.js';
+
+// Called by run-step with Run and Backlog locks already held. No approval or QA decision owner.
+export function prepareArtefactRecording(root, run, input, control, before) {
+  const fail = reason => { throw new Error(reason); };
+  const expected = relationshipForGate(input.gate);
+  const qaRecording = input.gate === 'QA' && before.current_gate === 'QA'
+    && (before.status === 'open' || before.status === 'blocked' && control.artefacts.get('QA')?.status === 'block');
+  if (readSourceRevisions(run.content).present && !qaRecording && before.missing_approval !== `Approval: ${input.gate}` && before.next_operation?.type !== "revise_gate_material") fail("AGDF_ARTEFACT_RECORDING_GATE_INVALID");
+  if (!expected || input.gate === "UR" || before.current_gate !== input.gate || before.status !== "open" && !qaRecording
+      || control.approvals.get(input.gate)?.status === "approved") fail("AGDF_ARTEFACT_RECORDING_GATE_INVALID");
+  const sourceRequest = input.requestBinding ? readOperationSource(root, input.runId, input.requestBinding) : null;
+  const command = readContainedJson(root, input.evidence);
+  if (!exactObject(command, REVIEWED_REQUEST_FIELDS)
+      || command.schema_version !== "1" || command.target_id !== resolveControlCommandTarget(root).target_id
+      || command.run_id !== input.runId || command.expected_revision_id !== input.revisionId
+      || typeof command.update_draft !== "boolean" || !exactObject(command.relationship, ["from", "relationship", "to"])
+      || !sameRelationship(command.relationship, expected)) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
+  const bindings = readArtefactBindings(run.content);
+  if (!bindings.valid) fail("AGDF_ARTEFACT_BINDINGS_INVALID");
+  const candidate = {
+    schema_version: input.operationId ? "2" : "1", binding_id: randomUUID(), target_id: command.target_id, run_id: input.runId,
+    relationship: command.relationship, destination: command.destination, source: command.source, review: command.review,
+    origin: "reviewed_mapping", operation: { id: input.operationId ?? randomUUID(), previous_revision_id: input.revisionId, resulting_revision_id: randomUUID(), revision: Number(run.meta.revision) + 1, ...(input.operationId ? { request_digest: input.requestDigest } : {}) }, supersedes: null,
+  };
+  const prior = bindings.latest.filter(item => artefactBindingKey(item) === artefactBindingKey(candidate));
+  if (prior.length > 1) fail("AGDF_ARTEFACT_BINDINGS_INVALID");
+  candidate.supersedes = prior[0]?.binding_id ?? null;
+  const source = control.artefacts.get(expected.to);
+  if (!validArtefactBinding(candidate) || !source || source.path !== command.source.path || source.status !== "approved"
+      || control.approvals.get(expected.to)?.status !== "approved" || !validateBindingProof(root, candidate)
+      || !exactApprovedArtefacts(root, control)) fail("AGDF_ARTEFACT_BINDING_PROOF_INVALID");
+  if (input.gate === "QA") {
+    const report = readFileSync(containedRegularFile(root, candidate.destination.path).path, "utf8");
+    if (readReportDecision(report) !== candidate.destination.status) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
+  }
+  const old = control.artefacts.get(input.gate);
+  if (old?.path && old.path !== candidate.destination.path) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
+  const seal = runSealState(root, run.content);
+  let draftChange = false;
+  if (seal.status === "content_changed" && command.update_draft && (old?.status === "draft"
+      || qaRecording && ['pass', 'revise', 'block'].includes(old?.status))
+      && prior.length === 1 && old.path === prior[0].destination.path && prior[0].destination.digest !== candidate.destination.digest) {
+    // Reconstruct the old aggregate seal using only the previously sealed draft digest.
+    // Every other bound file and the complete recorded body must still match that seal.
+    const restored = computeRunSeals(root, run.content, { artefactDigests: new Map([[old.path, prior[0].destination.digest]]) });
+    draftChange = restored.content_seal === seal.recorded.content_seal && restored.approval_seal === seal.recorded.approval_seal;
+  }
+  if (seal.status !== "valid" && !draftChange) fail("AGDF_RUN_SEAL_INVALID");
+  const rows = control.artefact_chain.filter(row => row.from === expected.from);
+  if (rows.length > 1 || rows.some(row => !sameRelationship(row, expected))) fail("AGDF_ARTEFACT_BINDING_PROOF_INVALID");
+  const evidence = `binding ${candidate.binding_id}; reviewed by ${candidate.review.reviewer}; ${candidate.review.path}`;
+  let text = upsertTableRow(run.content, "Artefacts", 0, input.gate, [input.gate, candidate.destination.path, candidate.destination.status, "Reviewed source binding recorded atomically"]);
+  text = text && upsertTableRow(text, "Artefact Chain", 0, expected.from, [expected.from, expected.relationship, expected.to, evidence]);
+  if (!text) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
+  text = appendArtefactBinding(text, candidate);
+  // Proof files are seal-bound too; historical proofs may not be silently rewritten on update.
+  text = upsertTableRow(text, "Artefacts", 0, `Binding proof ${candidate.binding_id}`, [`Binding proof ${candidate.binding_id}`, candidate.review.path, "done", "Subordinate reviewed mapping evidence"]);
+  text = text && appendTableRow(text, "Evidence", ["Artefact source binding", candidate.review.path, `${expected.from} ${expected.relationship} ${expected.to}; binding ${candidate.binding_id}; operation ${candidate.operation.id}; ${input.revisionId} -> ${candidate.operation.resulting_revision_id}`, "reviewed cooperative mapping"]);
+  if (!text) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
+  const snapshot = canonicalJson([candidate, command]);
+  return { text, receipt: candidate, nextRevisionId: candidate.operation.resulting_revision_id, allowContentChange: draftChange,
+    validateBeforeWrite: () => {
+      sourceRequest?.validate();
+      if (!validateBindingProof(root, candidate) || !exactApprovedArtefacts(root, control)
+          || canonicalJson([candidate, readContainedJson(root, input.evidence)]) !== snapshot
+          || artefactFileDigest(root, candidate.destination.path) !== candidate.destination.digest) fail("AGDF_ARTEFACT_BINDING_PROOF_INVALID");
+    } };
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-backlog-writer.js

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { parseRunState } from "./run-state-parser.js";
+import { runSealState } from "./run-seal.js";
+import { atomicWrite, withOwnedFileLock, writeRunLocked } from "./run-state-writer.js";
+import { commitRunStepLocked, recoverPendingRunStepLocked, readPendingRunStepJournal } from "./run-step-transaction.js";
+import { pendingRunStepIds } from "./run-step-pending.js";
+import { BACKLOG_RELATIVE_PATH, prepareRunBacklogOrSkip } from "./run-backlog.js";
+import { containedRegularFile, hasSymlinkComponent } from "./contained-file.js";
+import { randomUUID } from "node:crypto";
+import { existsSync } from 'node:fs';
+import { pendingRunStepPath } from './run-step-pending.js';
+import { assertSummarySources } from "../control-evaluation/run-work-summary.js";
+
+export function withRunBacklogLock(root, path, work, options = {}) {
+  const relativePath = relative(root, path).split(sep).join("/");
+  if (hasSymlinkComponent(root, relativePath) || containedRegularFile(root, relativePath).status !== "valid") throw Error("AGDF_RUN_PATH_INVALID");
+  // The Run path check covers the shared .agdf/control ancestors, so the sibling Backlog lock is
+  // contained. An unusable Backlog file itself is reported by the planner, not by the lock.
+  return withOwnedFileLock(path, () => {
+    return withOwnedFileLock(join(root, BACKLOG_RELATIVE_PATH), () => {
+      const run = parseRunState(readFileSync(path, "utf8"));
+      if (!run.valid) throw Error("AGDF_RUN_STATE_INVALID");
+      const other = pendingRunStepIds(root).find(id => id !== run.meta.run_id);
+      if (other) { const error = Error("AGDF_RUN_STEP_RECOVERY_REQUIRED"); error.pending_run_id = other; throw error; }
+      if (options.operationContext && existsSync(pendingRunStepPath(root, run.meta.run_id))) {
+        const pending = readPendingRunStepJournal(root, run.meta.run_id), expected = options.operationContext;
+        if (pending.schema_version !== 3 || pending.operation_id !== expected.operation_id || pending.kind !== expected.kind
+          || pending.target_id !== expected.target_id || pending.request_digest !== expected.request_digest) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
+      }
+      recoverPendingRunStepLocked(root, run.meta.run_id);
+      return work();
+    });
+  }, options);
+}
+
+// Both locks are held by the caller. The existing journal keeps receipt, seal, revision
+// and Backlog projection recoverable at the same Run commit point.
+export function writeRunWithBacklogLocked(root, path, content, revisionId, options = {}) {
+  const old = readFileSync(path, "utf8"), run = parseRunState(old);
+  if (!run.valid) throw Error("AGDF_RUN_STATE_INVALID");
+  if (run.meta.revision_id !== revisionId || options.expectedContent !== undefined && old !== options.expectedContent) throw Error("AGDF_STALE_RUN_REVISION");
+  const nextRevisionId = options.nextRevisionId ?? randomUUID();
+  const plan = prepareRunBacklogOrSkip(root, run.meta.run_id, content, path, nextRevisionId);
+  const withBacklog = state => ({ ...state, backlog: plan.status, backlog_reason: plan.reason ?? null });
+  const guard = () => { if (plan.summary) assertSummarySources(root, plan.summary); };
+  if (!plan.update && !options.operationContext) return withBacklog(writeRunLocked(path, content, revisionId, { ...options, nextRevisionId,
+    validateBeforeWrite: () => { options.validateBeforeWrite?.(); guard(); } }));
+  // Full gate/presentation evaluation still sees the original sealed Run, under both
+  // locks. The journal then rechecks its captured source digests and envelope at commit.
+  options.validateBeforeWrite?.();
+  return withBacklog(commitRunStepLocked(root, { runId: run.meta.run_id, runPath: path, content,
+    revisionId, expectedContent: old, backlog: plan.update, or: null,
+    operationContext: options.operationContext,
+    nextRevisionId,
+    writeOptions: { ...options, validateBeforeWrite: () => { options.validateDuringTransaction?.(); guard(); } }, afterWrite: options.afterWrite }));
+}
+
+export function writeRunWithBacklog(root, path, content, revisionId, options = {}) {
+  return withRunBacklogLock(root, path, () => writeRunWithBacklogLocked(root, path, content, revisionId, options));
+}
+
+// Explicit repair of a valid sealed Run's stale pointer needs only one atomic file write;
+// no fabricated Run revision, new approval or reader-side write is necessary.
+export function synchronizeRunBacklog(root, path, revisionId) {
+  return withRunBacklogLock(root, path, () => {
+    const content = readFileSync(path, "utf8"), run = parseRunState(content);
+    if (!run.valid) throw Error("AGDF_RUN_STATE_INVALID");
+    if (run.meta.revision_id !== revisionId) throw Error("AGDF_STALE_RUN_REVISION");
+    if (runSealState(root, content).status !== "valid") throw Error("AGDF_RUN_SEAL_INVALID");
+    const plan = prepareRunBacklogOrSkip(root, run.meta.run_id, content, path, revisionId);
+    if (plan.update) {
+      assertSummarySources(root, plan.summary);
+      if (readFileSync(path, "utf8") !== content || runSealState(root, content).status !== "valid"
+          || readFileSync(join(root, BACKLOG_RELATIVE_PATH), "utf8") !== plan.update.old) throw Error("AGDF_STALE_RUN_REVISION");
+      atomicWrite(join(root, BACKLOG_RELATIVE_PATH), plan.update.next);
+    }
+    return { meta: run.meta, backlog: plan.status, backlog_reason: plan.reason ?? null };
+  });
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-backlog.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { firstSection, tableCells, tableLine, tableLineIndexes } from "./run-state-edits.js";
+import { containedRegularFile, hasSymlinkComponent } from "./contained-file.js";
+import { policyForRunContent } from "../control-evaluation/run-step-policy.js";
+import { runWorkSummary } from "../control-evaluation/run-work-summary.js";
+import { recordBacklogSummary } from "./backlog-summary.js";
+import { parseRunState } from "./run-state-parser.js";
+
+export const BACKLOG_RELATIVE_PATH = ".agdf/control/MASTER_BACKLOG.md";
+const compactHeaders = ["priority", "key", "work item", "status", "artefacts", "current spec", "next step"];
+const legacyHeaders = ["prio", "key", "title", "status", "ur", "brownfield review", "prd", "sd", "tp", "qa", "or", "current spec", "notes"];
+const clean = value => value.replaceAll("`", "").trim();
+export const backlogTableLayout = headers => {
+  const normalized = headers.map(value => clean(value).toLowerCase()).join("\0");
+  return normalized === compactHeaders.join("\0") ? "compact" : normalized === legacyHeaders.join("\0") ? "legacy" : null;
+};
+const SKIPPABLE_BACKLOG_ERRORS = new Map([
+  ["AGDF_BACKLOG_PATH_INVALID", "backlog_path_invalid"],
+  ["AGDF_BACKLOG_LAYOUT_UNSUPPORTED", "backlog_layout_unsupported"],
+  ["AGDF_BACKLOG_IDENTITY_AMBIGUOUS", "backlog_identity_ambiguous"],
+]);
+
+// A saved projection of the same policy used by the Run writer, never UR metadata or a
+// reader-side claim of current readiness. Completion still belongs to explicit closeout.
+export function backlogStatusForPolicy(after) {
+  if (after.status === "blocked") return "Blocked";
+  if (after.current_gate === "UR") return "Needs UR";
+  if (after.current_gate === "Brownfield Review") return "Awaiting Brownfield Review";
+  if (["PRD", "SD", "TP"].includes(after.current_gate)) return `Awaiting ${after.current_gate}`;
+  if (["QA", "UAT"].includes(after.current_gate) && after.missing_approval === `Approval: ${after.current_gate}`) return `Awaiting ${after.current_gate}`;
+  if (after.current_gate === "OR") return "Awaiting OR";
+  if (["Brownfield Analysis", "CD+Tests", "CR", "Quick Task Execution", "Verified Change Execution", "Mode/Slice Decision"].includes(after.current_gate)) return `${after.current_gate} work pending`;
+  return "In Progress";
+}
+export const backlogStatusForSummary = (summary, after) =>
+  ["work_pending", "approval_pending", "closeout_pending"].includes(summary.kind)
+    ? backlogStatusForPolicy(after) : summary.status_label;
+
+export function assertBacklogPath(root) {
+  if (hasSymlinkComponent(root, BACKLOG_RELATIVE_PATH)
+      || existsSync(join(root, BACKLOG_RELATIVE_PATH)) && containedRegularFile(root, BACKLOG_RELATIVE_PATH).status !== "valid") {
+    throw Error("AGDF_BACKLOG_PATH_INVALID");
+  }
+}
+
+// Change only the addressed existing Active row. Keep title, links, order, other rows and
+// archive/planning placement intact. Unsupported layouts and ambiguous identities fail closed.
+export function prepareRunBacklog(root, runId, content, runPath, revisionId = parseRunState(content).meta.revision_id) {
+  assertBacklogPath(root);
+  const path = join(root, BACKLOG_RELATIVE_PATH);
+  if (!existsSync(path)) return { status: "missing", update: null };
+  const old = readFileSync(path, "utf8"), lines = old.split("\n");
+  if (Buffer.byteLength(old) > 2097152) throw Error("AGDF_BACKLOG_LAYOUT_UNSUPPORTED");
+  const section = firstSection(lines, "Active Backlog");
+  if (!section) throw Error("AGDF_BACKLOG_LAYOUT_UNSUPPORTED");
+  const indexes = tableLineIndexes(lines, section), layout = backlogTableLayout(tableCells(lines[indexes[0]] ?? ""));
+  const width = layout === "compact" ? compactHeaders.length : layout === "legacy" ? legacyHeaders.length : undefined;
+  if (!width || indexes.length < 2 || tableCells(lines[indexes[1]]).length !== width
+      || tableCells(lines[indexes[1]]).some(value => !/^:?-{3,}:?$/u.test(value))) throw Error("AGDF_BACKLOG_LAYOUT_UNSUPPORTED");
+  const matches = indexes.slice(2).filter(index => clean(tableCells(lines[index])[1] ?? "") === runId);
+  if (matches.length > 1) throw Error("AGDF_BACKLOG_IDENTITY_AMBIGUOUS");
+  if (!matches.length) return { status: "unlinked", update: null };
+  for (const [heading, column] of [["Planned / Parking Lot", 1], ["Completed / Superseded Pointers", 0]]) {
+    const other = firstSection(lines, heading);
+    if (other && tableLineIndexes(lines, other).slice(2).some(index => clean(tableCells(lines[index])[column] ?? "") === runId)) throw Error("AGDF_BACKLOG_IDENTITY_AMBIGUOUS");
+  }
+  const index = matches[0], cells = tableCells(lines[index]);
+  if (cells.length !== width) throw Error("AGDF_BACKLOG_LAYOUT_UNSUPPORTED");
+  const after = policyForRunContent(root, content, runPath);
+  const summary = runWorkSummary(root, content, runPath, after);
+  const status = backlogStatusForSummary(summary, after);
+  const next = summary.display_action;
+  cells[3] = status; cells[width - 1] = next;
+  lines[index] = tableLine(cells);
+  const updated = recordBacklogSummary(root, lines.join("\n"), runId, "Active Backlog", summary, revisionId);
+  return { status: old === updated ? "unchanged" : "updated", summary, update: old === updated ? null : { old, next: updated } };
+}
+
+// Approvals and run-update stay valid when the saved pointer cannot be synchronized. The
+// pointer is left untouched and the result names why; the doctor reports the backlog itself.
+export function prepareRunBacklogOrSkip(root, runId, content, runPath, revisionId) {
+  try { return prepareRunBacklog(root, runId, content, runPath, revisionId); }
+  catch (error) {
+    const reason = SKIPPABLE_BACKLOG_ERRORS.get(error?.message);
+    if (!reason) throw error;
+    return { status: "skipped", reason, update: null };
+  }
+}
+export const backlogSkip = plan => plan?.reason ? { backlog: plan.status, backlog_reason: plan.reason } : {};