create-agdf 0.20.2 → 0.31.0

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

@@ -1,3 +1,5 @@
+import { runDocumentPath, runHistoryPath } from './run-identity.js';
+import { resolutionRecord } from './input-resolution.js';
 import { validDecisionMaterial, decisionMaterialVersion } from './decision-material-contract.js';
 import { TextDecoder } from 'node:util';
 import { canonicalJson, digest, COOPERATIVE_ASSURANCE, DIGEST_PATTERN, exactObject } from './approval-command-contract.js';
@@ -5,39 +7,68 @@ import { REVISION_ID_PATTERN, RUN_ID_PATTERN, APPROVAL_GATES } from './run-ident
 import { isSafeControlRelativePath } from './contained-file.js';
 
 const fields = ['schema_version', 'kind', 'operation_id', 'request_digest', 'target_id', 'run_id', 'expected_revision_id', 'created_at', 'producer', 'assurance', 'effect'];
-export const RUN_OPERATION_KINDS = Object.freeze(['step.record', 'presentation_decision.record', 'prd_revision.reopen', 'closeout.record']);
+export const RUN_OPERATION_VERSION = '4';
+export const RUN_OPERATION_KINDS = Object.freeze(['run.create', 'run.create_from_planned', 'ur_draft.replace', 'step.record', 'presentation_decision.record', 'prd_revision.reopen', 'closeout.record', 'lifecycle_close.record']);
+export const ENDED_LIFECYCLES = Object.freeze(['superseded', 'abandoned']);
 const uuid = value => typeof value === 'string' && REVISION_ID_PATTERN.test(value);
 const hash = value => typeof value === 'string' && DIGEST_PATTERN.test(value);
 const text = (value, max = 8192) => typeof value === 'string' && value.length <= max && !/\0/u.test(value);
 const source = (value, runId) => exactObject(value, ['path', 'digest']) && isSafeControlRelativePath(value.path)
-  && value.path.startsWith(`.agdf/control/artefacts/${runId}/`) && hash(value.digest);
+  && value.path.startsWith(`${runDocumentPath(runId, '')}/`) && hash(value.digest);
+// One bounded table-safe line for typed closure facts.
+export const closureLine = (value, max) => text(value, max) && value.trim() === value && Boolean(value) && !/[|\u0000-\u001f\u007f]/u.test(value);
+const validSuccessor = (value, runId) => exactObject(value, ['kind', 'value', 'verified']) && (value.kind === 'run'
+  ? value.verified === true && RUN_ID_PATTERN.test(value.value) && value.value !== runId : value.kind === 'reference' && value.verified === false && closureLine(value.value, 512));
+// The confirming person is a cooperative local Git statement, never proof of a human identity.
+const validConfirmer = value => exactObject(value, ['statement']) ? value.statement === 'unknown'
+  : exactObject(value, ['name', 'email', 'statement']) && value.statement === 'cooperative' && (value.name !== null || value.email !== null)
+    && [value.name, value.email].every(item => item === null || closureLine(item, 256));
 function validRecord(receipt) {
   const r = receipt.effect.record;
-  if (receipt.kind === 'step.record') return exactObject(r, ['step', 'source', 'status', 'covers', 'source_set_digest'])
-    && ['ur', 'route', 'review', 'evidence', 'Brownfield Review', 'UX Intent Definition', 'Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR'].includes(r.step)
-    && source(r.source, receipt.run_id) && ['done', 'revise', 'block', 'not_applicable'].includes(r.status)
-    && text(r.covers, 1024) && hash(r.source_set_digest);
+  if (receipt.kind === 'run.create') return exactObject(r, ['title']) && text(r.title, 1024) && r.title.trim()
+    && !/[\r\n|]/u.test(r.title) && receipt.run_id === `run-${receipt.operation_id}`;
+  if (receipt.kind === 'run.create_from_planned') return exactObject(r, ['title', 'planned', 'snapshot'])
+    && text(r.title, 1024) && Boolean(r.title.trim()) && !/[\r\n\u2028\u2029]/u.test(r.title)
+    && receipt.run_id === `run-${receipt.operation_id}` && exactObject(r.planned, ['plan_id', 'path', 'digest'])
+    && RUN_ID_PATTERN.test(r.planned.plan_id ?? '') && r.planned.path === `.agdf/control/planned/${r.planned.plan_id}/UR.md` && hash(r.planned.digest)
+    && exactObject(r.snapshot, ['path', 'digest', 'raw_digest']) && r.snapshot.path === runHistoryPath(receipt.run_id, 'planning/UR.md')
+    && r.snapshot.digest === r.planned.digest && hash(r.snapshot.raw_digest);
+  if (['step.record', 'ur_draft.replace'].includes(receipt.kind)) return exactObject(r, ['evidence_binding_id', 'status', 'covers'])
+    && r.evidence_binding_id === receipt.operation_id && uuid(r.evidence_binding_id)
+    && ['done', 'revise', 'block', 'not_applicable', 'eligible', 'executed', 'escalated'].includes(r.status) && text(r.covers, 1024);
   if (receipt.kind === 'presentation_decision.record') return exactObject(r, ['gate', 'presentation_id', 'presentation_digest', 'material_version', 'material_sources', 'action', 'comment', 'owner', 'artefact_digest'])
     && APPROVAL_GATES.includes(r.gate) && uuid(r.presentation_id) && hash(r.presentation_digest) && hash(r.material_version)
     && validDecisionMaterial(r.material_sources, receipt.run_id) && r.material_version === decisionMaterialVersion(receipt.run_id, r.gate, r.material_sources) && ['request_change', 'reject'].includes(r.action) && text(r.comment) && Buffer.byteLength(r.comment) <= 8192 && (r.action !== 'request_change' || r.comment.trim())
     && text(r.owner, 128) && r.owner.trim() && (r.gate === 'UAT' ? r.artefact_digest === null : hash(r.artefact_digest));
+  if (receipt.kind === 'closeout.record' && r.mode === 'verified_change') return exactObject(r, ['mode', 'verified_change', 'lifecycle', 'context_evidence_digest', 'confirmation_digest'])
+    && source(r.verified_change, receipt.run_id) && r.verified_change.path === `${runDocumentPath(receipt.run_id, '')}/VERIFIED_CHANGE.md`
+    && r.lifecycle === 'completed' && hash(r.context_evidence_digest) && hash(r.confirmation_digest);
   if (receipt.kind === 'closeout.record') return exactObject(r, ['or', 'lifecycle', 'context_evidence_digest', 'confirmation_digest'])
-    && source(r.or, receipt.run_id) && r.or.path === `.agdf/control/artefacts/${receipt.run_id}/OR.md`
+    && source(r.or, receipt.run_id) && r.or.path === `${runDocumentPath(receipt.run_id, '')}/OR.md`
     && r.lifecycle === 'completed' && hash(r.context_evidence_digest) && hash(r.confirmation_digest);
+  if (receipt.kind === 'lifecycle_close.record') return exactObject(r, ['lifecycle', 'reason', 'successor', 'confirmed_by', 'preview'])
+    && ENDED_LIFECYCLES.includes(r.lifecycle) && closureLine(r.reason, 1024)
+    && (r.lifecycle === 'abandoned' ? r.successor === null : validSuccessor(r.successor, receipt.run_id)) && validConfirmer(r.confirmed_by)
+    && exactObject(r.preview, ['id', 'digest']) && /^[0-9a-f]{8}$/u.test(r.preview.id) && hash(r.preview.digest);
   if (receipt.kind === 'prd_revision.reopen') return exactObject(r, ['prd', 'archive', 'confirmation_digest']) && source(r.prd, receipt.run_id)
-    && r.prd.path === `.agdf/control/artefacts/${receipt.run_id}/PRD.md`
-    && exactObject(r.archive, ['path', 'digest']) && r.archive.path === `.agdf/control/runs/${receipt.run_id}/revisions/${receipt.operation_id}/manifest.json`
+    && r.prd.path === `${runDocumentPath(receipt.run_id, '')}/PRD.md`
+    && exactObject(r.archive, ['path', 'digest']) && r.archive.path === runHistoryPath(receipt.run_id, `revisions/${receipt.operation_id}/manifest.json`)
     && hash(r.archive.digest) && hash(r.confirmation_digest)
     && r.confirmation_digest === digest(earlyPrdConfirmation(receipt.run_id, receipt.expected_revision_id, receipt.operation_id, r.prd.digest));
   return false;
 }
 export const earlyPrdConfirmation = (runId, revisionId, operationId, prdDigest) => `Reopen PRD: ${runId} ${revisionId} ${operationId} ${prdDigest}`;
 export function validRunOperation(receipt) {
-  return exactObject(receipt, fields) && receipt.schema_version === '1' && RUN_OPERATION_KINDS.includes(receipt.kind)
+  receipt = resolutionRecord(receipt);
+  if (!receipt) return false;
+  const plannedCreation = receipt?.kind === 'run.create_from_planned';
+  const creation = receipt?.kind === 'run.create' || plannedCreation;
+  return exactObject(receipt, fields) && receipt.schema_version === RUN_OPERATION_VERSION && RUN_OPERATION_KINDS.includes(receipt.kind)
     && uuid(receipt.operation_id) && hash(receipt.request_digest) && hash(receipt.target_id) && RUN_ID_PATTERN.test(receipt.run_id ?? '')
-    && uuid(receipt.expected_revision_id) && exactObject(receipt.effect, ['previous_revision_id', 'resulting_revision_id', 'revision', 'record'])
+    && (creation ? receipt.expected_revision_id === null : uuid(receipt.expected_revision_id)) && exactObject(receipt.effect, ['previous_revision_id', 'resulting_revision_id', 'revision', 'record'])
     && receipt.effect.previous_revision_id === receipt.expected_revision_id && uuid(receipt.effect.resulting_revision_id)
-    && receipt.effect.resulting_revision_id !== receipt.expected_revision_id && Number.isSafeInteger(receipt.effect.revision) && receipt.effect.revision >= 2
+    && receipt.effect.resulting_revision_id !== receipt.expected_revision_id && Number.isSafeInteger(receipt.effect.revision)
+    && (creation ? receipt.effect.revision === 1 : receipt.effect.revision >= 2)
     && exactObject(receipt.producer, ['contract', 'package_version']) && receipt.producer.contract === 'run-command/1' && text(receipt.producer.package_version, 128) && receipt.producer.package_version
     && canonicalJson(receipt.assurance) === canonicalJson(COOPERATIVE_ASSURANCE)
     && typeof receipt.created_at === 'string' && /^\d{4}-\d{2}-\d{2}T.*Z$/u.test(receipt.created_at) && Number.isFinite(Date.parse(receipt.created_at)) && Boolean(validRecord(receipt));
@@ -52,7 +83,7 @@ export function readRunOperations(content) {
   while (end < lines.length && !/^#{1,2} /u.test(lines[end])) end++;
   const body = lines.slice(start + 1, end).map(line => line.trim()).filter(Boolean);
   if (body[0] !== '- schema_version: 1' || body[1] !== '| operation_id | request_digest | receipt |' || !/^\|[-:|\s]+\|$/u.test(body[2] ?? '')) return invalid();
-  const receipts = [], ids = new Set(), revisions = new Set(); let revision = 1;
+  const receipts = [], ids = new Set(), revisions = new Set(); let revision = 0;
   for (const line of body.slice(3)) {
     const cells = line.match(/^\| ([^|]+) \| ([^|]+) \| ([A-Za-z0-9_-]+) \|$/u);
     if (!cells || cells[3].length > 131072) return invalid();
@@ -78,3 +109,29 @@ export function assertRunOperationsChange(current, candidate, appended) {
   if (!before.valid || !after.valid || after.present !== (before.present || Boolean(appended))
     || canonicalJson(after.receipts) !== canonicalJson(appended ? [...before.receipts, appended] : before.receipts)) throw Error('AGDF_RUN_OPERATIONS_CHANGED');
 }
+
+// Lifecycle and closure facts of an ended Run. The sealed receipt is the record; a missing or
+// unreadable receipt still leaves the Run ended and is reported as unavailable.
+const lifecycleOf = content => String(content).match(/^- lifecycle:[ \t]*(\S+)[ \t]*\r?$/mu)?.[1] ?? null;
+export function runClosure(content) {
+  const lifecycle = lifecycleOf(content);
+  if (!ENDED_LIFECYCLES.includes(lifecycle)) return null;
+  const operations = readRunOperations(content), receipt = operations.valid ? operations.receipts.filter(row => row.kind === 'lifecycle_close.record').at(-1) : undefined;
+  const r = receipt?.effect.record;
+  return { outcome: lifecycle, closed_at: receipt?.created_at ?? null, reason: r?.reason ?? null, successor: r?.successor ?? null,
+    confirmed_by: r?.confirmed_by ?? null, operation_id: receipt?.operation_id ?? null, preview: r?.preview ?? null, receipt: receipt ? 'recorded' : 'unavailable' };
+}
+export const RUN_ENDED_NEXT_ACTION = 'Start a new run; it may reference the ended run.';
+export const closureSuccessorText = successor => successor ? ` by ${successor.value}${successor.verified ? '' : ' (unverified reference)'}` : '';
+// The archived closure outcome of an ended Run: successor and reason, or the reason alone.
+export const closureOutcomeText = (outcome, successor, reason) => outcome === 'superseded'
+  ? `Superseded${closureSuccessorText(successor)}: ${reason ?? 'reason unavailable'}` : `Abandoned: ${reason ?? 'reason unavailable'}`;
+export const closureBacklogRecord = runId => `[RUN_STATE](runs/${runId}/RUN_STATE.md)`;
+export function endedRunMessage(runId, closure) {
+  const successor = closure.successor ? ` by ${closure.successor.value}${closure.successor.verified ? '' : ' (unverified reference)'}` : '';
+  return `Run ${runId} was closed as ${closure.outcome}${successor}${closure.closed_at ? ` on ${closure.closed_at.slice(0, 10)}` : ''}; it accepts no further delivery operation. ${RUN_ENDED_NEXT_ACTION}`;
+}
+export function assertRunNotEnded(content) {
+  const closure = runClosure(content);
+  if (closure) throw Object.assign(Error('AGDF_RUN_LIFECYCLE_ENDED'), { closure });
+}

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

@@ -1,5 +1,6 @@
-import { join } from 'node:path';
-import { existsSync, lstatSync, readFileSync, unlinkSync } from 'node:fs';
+import { runDocumentPath, runEvidencePath } from './run-identity.js';
+import { join, dirname } from 'node:path';
+import { existsSync, lstatSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { exactObject } from './approval-command-contract.js';
 import { hasSymlinkComponent } from './contained-file.js';
@@ -10,11 +11,15 @@ export const INTERNAL_STEP_FILES = Object.freeze({
   'Brownfield Analysis': 'BROWNFIELD_ANALYSIS.md', 'CD+Tests': 'CD_TESTS.md', 'TP Review': 'TP_REVIEW.md',
   'Clean Implementation Review': 'CLEAN_IMPLEMENTATION_REVIEW.md', CR: 'CODE_REVIEW.md',
 });
-const permitted = new Set(['UR.md', 'OR.md', ...Object.values(INTERNAL_STEP_FILES)]);
+const documentNames = new Set(['UR.md', 'OR.md', 'PRD.md', 'SD.md', 'TP.md', 'QA_REPORT.md', 'VERIFIED_CHANGE.md', ...Object.values(INTERNAL_STEP_FILES)]);
+function allowedPath(runId, path) {
+  const documents = `${runDocumentPath(runId, '')}/`, evidence = `${runEvidencePath(runId, '')}/`;
+  return typeof path === 'string' && (path.startsWith(documents) && documentNames.has(path.slice(documents.length))
+    || path.startsWith(evidence) && /^EVIDENCE-[0-9a-f]{64}\.(?:md|json)$/u.test(path.slice(evidence.length)));
+}
 export const outputBytesDigest = text => text === null ? null : 'sha256:' + createHash('sha256').update(text, 'utf8').digest('hex');
 export function ownedOutputPath(root, runId, path) {
-  const prefix = `.agdf/control/artefacts/${runId}/`;
-  if (typeof path !== 'string' || !path.startsWith(prefix) || !permitted.has(path.slice(prefix.length)) || hasSymlinkComponent(root, path)) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
+  if (!allowedPath(runId, path) || hasSymlinkComponent(root, path)) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
   return join(root, path);
 }
 export function ownedOutputText(root, runId, path) {
@@ -24,10 +29,9 @@ export function ownedOutputText(root, runId, path) {
   return new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(file));
 }
 export function validOwnedOutputs(runId, outputs) {
-  const prefix = `.agdf/control/artefacts/${runId}/`;
-  return Array.isArray(outputs) && outputs.length <= 2 && new Set(outputs.map(row => row?.path)).size === outputs.length
+  return Array.isArray(outputs) && outputs.length <= 1 && new Set(outputs.map(row => row?.path)).size === outputs.length
     && outputs.every(row => exactObject(row, ['path', 'old', 'next', 'old_digest', 'next_digest'])
-      && typeof row.path === 'string' && row.path.startsWith(prefix) && permitted.has(row.path.slice(prefix.length))
+      && allowedPath(runId, row.path)
       && (row.old === null || typeof row.old === 'string') && typeof row.next === 'string'
       && Buffer.byteLength(row.next) <= 131072 && (row.old === null || Buffer.byteLength(row.old) <= 131072)
       && row.old_digest === outputBytesDigest(row.old) && row.next_digest === outputBytesDigest(row.next));
@@ -37,6 +41,14 @@ export function prepareOwnedOutput(root, runId, path, next) {
   if (!validOwnedOutputs(runId, [row])) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED'); return row;
 }
 export function publishOwnedOutputs(root, journal, checkpoint) {
+  if (journal.outputs.length) {
+    for (const relative of [...new Set(journal.outputs.map(row => row.path.slice(0, row.path.lastIndexOf('/'))))]) {
+      const directory = join(root, relative);
+      if (hasSymlinkComponent(root, relative)) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
+      if (!existsSync(directory)) { mkdirSync(directory, { mode: 0o700 }); fsyncDirectory(dirname(directory)); }
+      if (!lstatSync(directory).isDirectory() || lstatSync(directory).isSymbolicLink()) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
+    }
+  }
   for (const row of journal.outputs) {
     if (ownedOutputText(root, journal.run_id, row.path) !== row.old) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
     atomicWrite(ownedOutputPath(root, journal.run_id, row.path), row.next, { checkpoint: stage => checkpoint(`output_${stage}`) });
@@ -51,7 +63,7 @@ export function recoverOwnedOutputs(root, journal, committed) {
       if (text !== row.old && text !== row.next) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
       if (text !== row.old) {
         const file = ownedOutputPath(root, journal.run_id, row.path);
-        if (row.old === null) { unlinkSync(file); fsyncDirectory(join(root, `.agdf/control/artefacts/${journal.run_id}`)); }
+        if (row.old === null) { unlinkSync(file); fsyncDirectory(dirname(file)); }
         else atomicWrite(file, row.old);
       }
     }

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

@@ -1,36 +1,28 @@
-// Immutable envelope validation is shared by live and archived proofs.
-import { digest as hash, exactObject, DIGEST_PATTERN } from "./approval-command-contract.js";
-import { validPreviewSnapshot } from "./preview-snapshot.js";
-
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
-const recovery = "Run run-present for the current run/gate/revision, show its exact presentation, then wait for a NEW deliberate user response. Never bind an earlier reply retroactively.";
-
-export { UUID as PRESENTATION_ID_PATTERN, recovery as PRESENTATION_RECOVERY };
-
-// Rechecks the immutable presentation envelope without evaluating a Run hidden by its
-// own pending journal. Full policy/binding validation must precede transaction intent.
-// Pure record check is also consumed inside captured read-only observations.
+import { resolutionRecord } from './input-resolution.js';
+import { digest as hash, exactObject, DIGEST_PATTERN } from './approval-command-contract.js';
+import { validPreviewSnapshot } from './preview-snapshot.js';
+import { REVISION_ID_PATTERN } from './run-identity.js';
+export const PRESENTATION_RECORD_VERSION = 7;
+export { REVISION_ID_PATTERN as PRESENTATION_ID_PATTERN } from './run-identity.js';
+export const PRESENTATION_RECOVERY = 'Run run-present for the current run/gate/revision, show its exact presentation, then wait for a NEW deliberate user response. Never bind an earlier reply retroactively.';
 export function validateRunPresentationEnvelope(envelope, { runId, gate, revisionId, presentationId }) {
-  const { record, digest } = envelope ?? {};
-  if (!record || ![1, 2, 3, 4, 5].includes(record.schema_version) || record.presentation_id !== presentationId
-      || record.run_id !== runId || record.gate !== gate || record.revision_id !== revisionId
-      || digest !== hash(JSON.stringify(record)) || !Number.isFinite(Date.parse(record.created_at))) {
-    return { reason: "presentation_binding_invalid", recovery };
-  }
-  if (record.schema_version === 2 && (!exactObject(envelope, ['record', 'digest'])
-    || !exactObject(record, ['schema_version', 'presentation_id', 'operation_id', 'request_digest', 'created_at', 'run_id', 'gate', 'revision_id', 'content_digest', 'artefact_digest', 'summary_digest', 'presentation_language', 'presentation_digest'])
-    || record.operation_id !== presentationId || !UUID.test(record.operation_id) || !DIGEST_PATTERN.test(record.request_digest ?? ''))) return { reason: 'presentation_binding_invalid', recovery };
-  if ([3, 4, 5].includes(record.schema_version) && (!exactObject(envelope, ['record', 'digest'])
-    || !exactObject(record, ['schema_version', 'presentation_id', ...(record.operation_id ? ['operation_id', 'request_digest'] : []),
-      'created_at', 'run_id', 'gate', 'revision_id', 'content_digest', 'artefact_digest', 'summary_digest', 'presentation_language',
-      'presentation_digest', 'document_digest', 'document_bytes', 'document_language', ...(record.schema_version === 4 ? ['qa_acceptance'] : []), ...(record.schema_version === 5 ? ['preview_review'] : [])])
-    || record.operation_id && (record.operation_id !== presentationId || !UUID.test(record.operation_id) || !DIGEST_PATTERN.test(record.request_digest ?? ''))
+  const invalid = () => ({ reason: 'presentation_binding_invalid', recovery: PRESENTATION_RECOVERY });
+  const record = resolutionRecord(envelope?.record);
+  if (!record || !exactObject(envelope, ['record', 'digest']) || record.schema_version !== PRESENTATION_RECORD_VERSION
+    || !exactObject(record, ['schema_version', 'presentation_id', 'operation_id', 'request_digest', 'created_at', 'run_id', 'gate', 'revision_id',
+      'content_digest', 'artefact_digest', 'summary_digest', 'presentation_language', 'presentation_digest',
+      'document_digest', 'document_bytes', 'document_language', ...(record.qa_acceptance ? ['qa_acceptance'] : []), ...(record.preview_review ? ['preview_review'] : [])])
+    || record.presentation_id !== presentationId || record.operation_id !== presentationId || !REVISION_ID_PATTERN.test(presentationId ?? '')
+    || record.run_id !== runId || record.gate !== gate || record.revision_id !== revisionId
+    || ![record.request_digest, record.content_digest, record.summary_digest, record.presentation_digest, record.document_digest].every(value => DIGEST_PATTERN.test(value ?? ''))
+    || !DIGEST_PATTERN.test(record.artefact_digest ?? '')
+    || envelope.digest !== hash(JSON.stringify(envelope.record)) || !Number.isFinite(Date.parse(record.created_at))
     || !/^[a-z]{2}(?:-[A-Za-z0-9]{2,8})*$/u.test(record.document_language ?? '')
-    || !DIGEST_PATTERN.test(record.document_digest ?? '') || !Number.isInteger(record.document_bytes)
-    || record.document_bytes < 1 || record.document_bytes > 131072)) return { reason: 'presentation_binding_invalid', recovery };
-  if (record.schema_version === 4 && (gate !== 'QA' || !exactObject(record.qa_acceptance, ['kind', 'digest'])
-    || record.qa_acceptance.kind !== 'accepted_with_deviations' || !DIGEST_PATTERN.test(record.qa_acceptance.digest ?? ''))) return { reason: 'presentation_binding_invalid', recovery };
-  if (record.schema_version === 5 && (gate !== 'PRD' || !validPreviewSnapshot(record.preview_review, runId, presentationId))) return { reason: 'presentation_binding_invalid', recovery };
-  return { presentationId, digest, record };
+    || typeof record.presentation_language !== 'string' || !record.presentation_language
+    || !Number.isInteger(record.document_bytes) || record.document_bytes < 1 || record.document_bytes > 131072
+    || record.presentation_digest !== record.document_digest) return invalid();
+  if (record.qa_acceptance && (gate !== 'QA' || !exactObject(record.qa_acceptance, ['kind', 'digest'])
+    || record.qa_acceptance.kind !== 'accepted_with_deviations' || !DIGEST_PATTERN.test(record.qa_acceptance.digest ?? ''))) return invalid();
+  if (record.preview_review && (gate !== 'PRD' || !validPreviewSnapshot(record.preview_review, runId, presentationId))) return invalid();
+  return { presentationId, digest: envelope.digest, record: envelope.record };
 }
-

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

@@ -1,4 +1,4 @@
-import { readAcceptanceCriteria } from "../control-evaluation/traceability-readiness.js";
+import { readAcceptanceCriteria, ACCEPTANCE_CRITERIA_FORMAT, TRACEABILITY_CONTRACT } from "../control-evaluation/traceability-readiness.js";
 import { createHash } from "node:crypto";
 import { readFileSync } from "../control-read/fs.js";
 import { basename } from "node:path";
@@ -43,6 +43,14 @@ export function presentationVersionComparison(root, state, gate, currentDigest)
 const MAX_APPROVAL_ARTEFACT_BYTES = 131072;
 const MAX_LOCALIZED_SUMMARY_ITEM_CHARS = 1200;
 const MAX_LOCALIZED_SUMMARY_CHARS = 24000;
+const PRD_LOCALIZED_SUMMARY_FIELDS = Object.freeze([
+  { pattern: /^(?:[-*]\s*)?(?:Nutzerziel|User intent|Ziel|Goal)\s*:/iu,
+    de: '- Ziel:', en: '- Goal:', reason: 'approval_summary_user_goal_missing' },
+  { pattern: /^(?:[-*]\s*)?(?:Umfang|Scope|Produktumfang|Product scope)\s*:/iu,
+    de: '- Umfang:', en: '- Scope:', reason: 'approval_summary_scope_missing' },
+  { pattern: /^(?:[-*]\s*)?(?:Entscheidungen|Decisions|Geklärte Entscheidungen|Resolved decisions|Offene Entscheidungen|Open decisions)\s*:/iu,
+    de: '- Entscheidungen:', en: '- Decisions:', reason: 'approval_summary_decisions_missing', conditional: true },
+]);
 const SUMMARY_SECTIONS = Object.freeze({
   UR: [
     ["Problem", /problem|need|anlass/iu], ["Ziel", /goal|objective|ziel/iu],
@@ -83,8 +91,13 @@ const SUMMARY_LABELS_EN = Object.freeze({
 export const hash = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
 
 function compactSummaryText(value) {
-  return value.replace(/\[([^\]]+)\]\([^)]*\)/gu, "$1").replace(/`([^`]+)`/gu, "$1")
-    .replace(/<[^>]+>/gu, "").replace(/\s+/gu, " ").trim();
+  // Markup outside code spans is dropped. A code span naming syntax such as
+  // `node app.js <file>` keeps its backticks: unwrapped, Markdown would treat
+  // <file> as an HTML tag and the reader would lose it.
+  return value.replace(/\[([^\]]+)\]\([^)]*\)/gu, "$1")
+    .split(/(`[^`]+`)/u)
+    .map(part => /^`[^`]+`$/u.test(part) ? (part.includes("<") ? part : part.slice(1, -1)) : part.replace(/<[^>]+>/gu, ""))
+    .join("").replace(/\s+/gu, " ").trim();
 }
 
 function userFacingSummaryText(value) {
@@ -111,14 +124,14 @@ function substantiveMarkdown(markdown) {
   return markdown.replace(/^## AGDF Approval Summary \([^\r\n]*\)\s*\r?\n[\s\S]*?(?=^#{1,2}\s|(?![\s\S]))/gmu, "");
 }
 
-function criterionEntries(markdown) {
-  const parsed = readAcceptanceCriteria(substantiveMarkdown(markdown));
+function criterionEntries(markdown, source) {
+  const parsed = readAcceptanceCriteria(substantiveMarkdown(markdown), { source });
   if (parsed.diagnostics.length) throw Object.assign(new Error("approval_summary_source_criteria_invalid"), { diagnostics: parsed.diagnostics });
   return parsed.entries;
 }
 
 function criterionDescription(entry) {
-  for (const field of ["observable_success", "visible_feedback", "expected_effective_state"]) {
+  for (const field of ACCEPTANCE_CRITERIA_FORMAT.description_fields) {
     const value = String(entry.fields[field] ?? "").trim();
     if (value) return capitalizeSummary(compactSummaryText(value));
   }
@@ -158,16 +171,35 @@ function validateLocalizedSummaryBlock(gate, block, sourceMarkdown, sourceLangua
     if (summaryIds.some((id) => !sourceSet.has(id))) throw new Error("approval_summary_criteria_unknown");
     if (summaryIds.length !== sourceIds.length || sourceIds.some((id) => !summaryIds.includes(id)))
       throw new Error("approval_summary_criteria_incomplete");
-    if (!lines.some((line) => /^(?:[-*]\s*)?(?:Nutzerziel|User intent|Ziel|Goal)\s*:/iu.test(line)))
-      throw new Error("approval_summary_user_goal_missing");
-    if (!lines.some((line) => /^(?:[-*]\s*)?(?:Umfang|Scope|Produktumfang|Product scope)\s*:/iu.test(line)))
-      throw new Error("approval_summary_scope_missing");
     const decisions = approvalDecisionEntries(sourceMarkdown);
-    if (decisions.length && !lines.some((line) => /^(?:[-*]\s*)?(?:Entscheidungen|Decisions|Geklärte Entscheidungen|Resolved decisions|Offene Entscheidungen|Open decisions)\s*:/iu.test(line)))
-      throw new Error("approval_summary_decisions_missing");
+    for (const field of PRD_LOCALIZED_SUMMARY_FIELDS)
+      if ((!field.conditional || decisions.length) && !lines.some(line => field.pattern.test(line))) throw new Error(field.reason);
   }
 }
 
+// Syntax guidance comes from the presentation owner, never inferred product
+// content. An incomplete source remains readable through its authoring route.
+export function approvalSummaryAuthoringFormat(gate, markdown, languages) {
+  if (!languages.approval_summary_required || !['UR', 'PRD', 'SD', 'TP', 'QA'].includes(gate)) return null;
+  const locale = languages.presentation_language.toLowerCase().startsWith('de') ? 'de' : 'en';
+  const format = { heading: languages.approval_summary_heading, body_required: true,
+    required_fields: localizedDecisionFields(gate, '', { locale, sourceLanguage: languages.artifact_language }).gaps.map(gap => gap.expected),
+    instruction: 'Use the exact heading and a nonempty authored summary in the presentation language. Required fields are separate list declarations with concrete content; a heading or generic criteria paragraph does not replace them. This is syntax guidance, never supplied product content, review or approval.' };
+  if (gate === 'PRD') {
+    const decisions = approvalDecisionEntries(markdown);
+    format.required_fields = PRD_LOCALIZED_SUMMARY_FIELDS.filter(field => !field.conditional || decisions.length).map(field => field[locale]);
+    format.conditional_fields = [{ field: PRD_LOCALIZED_SUMMARY_FIELDS.find(field => field.conditional)[locale],
+      when: 'Required when the source PRD contains Approval Decisions rows.' }];
+    try {
+      const entries = criterionEntries(markdown);
+      format.criterion_fields = entries.map(entry => `- ${entry.id}:`);
+      format.criteria_state = entries.length ? 'available' : 'not_declared';
+    } catch { format.criterion_fields = []; format.criteria_state = 'source_invalid'; }
+    format.criteria_instruction = 'For every exact criterion_id in the authored PRD, write one separate list item beginning with that ID followed by a colon, exactly once. Retain the source IDs; do not combine them in a generic criteria item. If IDs are not yet available, complete the source criteria first.';
+  }
+  return format;
+}
+
 function requiredLocalizedSummary(gate, markdown, languages, { path } = {}) {
   if (!languages.approval_summary_required) return null;
   const blocks = localizedSummaryBlocks(markdown).filter(block => block.locale === languages.presentation_language);
@@ -186,6 +218,11 @@ function requiredLocalizedSummary(gate, markdown, languages, { path } = {}) {
 export function evaluateApprovalSummaryReadiness(gate, markdown, languages, { path } = {}) {
   try {
     requiredLocalizedSummary(gate, markdown, languages, { path });
+    if (gate === "PRD" && markdown.includes(TRACEABILITY_CONTRACT)
+        && languages.artifact_language === languages.presentation_language.split("-")[0]) {
+      artifactSummary(gate, markdown, { language: languages.presentation_language,
+        sourceLanguage: languages.artifact_language, artefactPath: path });
+    }
     return Object.freeze({ ready: true, required_heading: languages.approval_summary_heading, reason: null });
   } catch (error) {
     if (!String(error.message).startsWith("approval_summary_")) throw error;
@@ -197,12 +234,25 @@ export function evaluateApprovalSummaryReadiness(gate, markdown, languages, { pa
 export function renderApprovalSummaryIssue(summary, { path, presentationLanguage }) {
   const locale = resolvePresentationLocale(interactionLocales, presentationLanguage);
   const pack = localePack(interactionLocales, locale), german = locale.split("-")[0] === "de";
-  const expected = {
-    approval_summary_user_goal_missing: german ? "- Ziel:" : "- Goal:",
-    approval_summary_scope_missing: german ? "- Umfang:" : "- Scope:",
-    approval_summary_decisions_missing: german ? "- Entscheidungen:" : "- Decisions:",
-    approval_summary_field_unreadable: summary.diagnostics?.map(row => row.expected).join("` · `") || undefined,
-  }[summary.reason] ?? summary.required_heading;
+  if (summary.reason === "approval_summary_criterion_content_missing") {
+    const fields = ACCEPTANCE_CRITERIA_FORMAT.description_fields.map(field => `\`${field}\``).join(" / ");
+    const locations = (summary.diagnostics ?? []).map(row =>
+      `- ${row.criterion_id}${row.line ? ` (${german ? 'Zeile' : 'line'} ${row.line})` : ''}`).join("\n");
+    return [
+      `${german ? 'PRD-Quellkriterien korrigieren' : 'Correct PRD source criteria'}: \`${path}\``,
+      `${pack.statusCard.summaryReason}: \`${summary.reason}\``,
+      locations,
+      german
+        ? `Je betroffenem Kriterium mindestens eines dieser Felder einzeln und mit Inhalt angeben: ${fields}. Zusammengesetzte Feldnamen werden nicht aufgeteilt.`
+        : `For each affected criterion, provide at least one separate nonempty field: ${fields}. Combined field names are not split.`,
+      german
+        ? 'Eine zusätzliche AGDF Approval Summary ersetzt diese Quellfelder nicht. Die Kriterien-IDs und den fachlichen Inhalt erhalten; über den bestehenden Autorpfad korrigieren und erneut prüfen.'
+        : 'An additional AGDF Approval Summary does not replace these source fields. Preserve criterion IDs and product intent; correct through the existing authoring route and recheck.',
+    ].filter(Boolean).join("\n");
+  }
+  const expected = PRD_LOCALIZED_SUMMARY_FIELDS.find(field => field.reason === summary.reason)?.[german ? 'de' : 'en']
+    ?? (summary.reason === 'approval_summary_field_unreadable' ? summary.diagnostics?.map(row => row.expected).join("` · `") || undefined : undefined)
+    ?? summary.required_heading;
   return [
     `${pack.statusCard.summaryRecovery}: \`${path}\``,
     `${pack.statusCard.summaryReason}: \`${summary.reason}\``,
@@ -210,7 +260,8 @@ export function renderApprovalSummaryIssue(summary, { path, presentationLanguage
   ].join("\n");
 }
 
-function sectionBody(markdown, pattern, contentPattern = null, maxItems = 3) {
+// Pure summary extraction; exported so its text rules are tested directly.
+export function sectionBody(markdown, pattern, contentPattern = null, maxItems = 3) {
   const lines = markdown.replace(/\r\n?/gu, "\n").split("\n");
   for (let index = 0; index < lines.length; index += 1) {
     const heading = lines[index].match(/^(#{2,6})\s+(?:\d+\.\s*)?(.+?)\s*#*\s*$/u);
@@ -233,6 +284,9 @@ function sectionBody(markdown, pattern, contentPattern = null, maxItems = 3) {
       }
       if (contentPattern && !contentPattern.test(line)) continue;
       const cleaned = userFacingSummaryText(line);
+      // A lead-in such as "covers exactly these points:" says nothing on its own;
+      // the items that follow it carry the content.
+      if (/:$/u.test(cleaned)) continue;
       if (!cleaned || /^(?:what|which|how|who|every field|specify|decision:|status:|gate:|date:|owner:)/iu.test(cleaned)
           || /^(?:ui_ux_impact|ux_intent_definition|primary_user_intent|success_signal|primary_decision_or_action):/iu.test(cleaned)) continue;
       body.push(cleaned);
@@ -275,14 +329,15 @@ function artifactSummary(gate, markdown, { runId, revisionId, language, sourceLa
     if (decision) items.unshift(`- ${german ? 'Entscheidung' : 'Decision'}: ${decision}`);
   }
   if (gate === "PRD") {
-    const criteria = criterionEntries(source);
+    const criteria = criterionEntries(source, artefactPath);
     if (!criteria.length) throw new Error("approval_summary_criteria_missing");
     if (new Set(criteria.map((entry) => entry.id)).size !== criteria.length) throw new Error("approval_summary_source_criteria_duplicate");
-    const criterionRows = criteria.map((entry) => {
-      const description = criterionDescription(entry);
-      if (!description) throw new Error("approval_summary_criterion_content_missing");
-      return `  - ${entry.id}: ${description}`;
+    const missing = criteria.filter(entry => !criterionDescription(entry));
+    if (missing.length) throw Object.assign(new Error("approval_summary_criterion_content_missing"), {
+      diagnostics: missing.map(entry => ({ code: 'criterion_description_missing', source: entry.source,
+        line: entry.line, criterion_id: entry.id, expected: ACCEPTANCE_CRITERIA_FORMAT.description_fields })),
     });
+    const criterionRows = criteria.map(entry => `  - ${entry.id}: ${criterionDescription(entry)}`);
     items.push(`- ${german ? "Abnahmekriterien" : "Acceptance criteria"}:\n${criterionRows.join("\n")}`);
     const decisions = approvalDecisionEntries(source);
     if (decisions.length) {
@@ -388,16 +443,17 @@ export function renderReviewableApproval(root, report, { runId, gate, revisionId
         const languageName = pack.statusCard[locale.split("-")[0] === "de" ? "languageGerman" : "languageEnglish"];
         const artifactLabel = german ? "Artefakt" : "Artefact";
         const requiredHeading = languages.approval_summary_heading ?? `AGDF Approval Summary (${locale}; source=${sourceLanguage})`;
+        const sourceIssue = error.message === 'approval_summary_criterion_content_missing';
         error.recovery = [
-          `## ${pack.statusCard.summaryRecovery}`,
+          `## ${sourceIssue ? (german ? 'PRD-Quellkriterien korrigieren' : 'Correct PRD source criteria') : pack.statusCard.summaryRecovery}`,
           `Run: \`${runId}\` · Gate: \`${gate}\` · Revision: \`${revisionId}\``,
           renderApprovalSummaryIssue({ reason: error.message, required_heading: requiredHeading, diagnostics: error.diagnostics }, {
             path, presentationLanguage: p.presentation_language,
           }),
-          pack.operationalValues.approvalSummaryRecovery.replace("{language}", languageName),
-          `${german ? "Erforderlicher Abschnitt" : "Required section"}: \`${requiredHeading}\``,
+          ...(!sourceIssue ? [pack.operationalValues.approvalSummaryRecovery.replace("{language}", languageName),
+            `${german ? "Erforderlicher Abschnitt" : "Required section"}: \`${requiredHeading}\``] : []),
           `${artifactLabel}: [${basename(path)}](<${path}>)`,
-          pack.operationalValues.completeMissingApprovalSummary,
+          ...(!sourceIssue ? [pack.operationalValues.completeMissingApprovalSummary] : []),
         ].join("\n\n");
       }
       throw error;
@@ -426,18 +482,19 @@ export function renderReviewableApproval(root, report, { runId, gate, revisionId
   // One source-authored summary and one decision moment. Provenance remains
   // available without duplicating the status, transition and approval prompts.
   if (qaAcceptance) { summaryMarkdown = qaAcceptance.summary; summaryDigest = hash(summaryMarkdown); }
-  const parts = [`## ${qaAcceptance ? pack.decisionCard.deviationAcceptanceIntro : pack.gateActionTitles[gate]}`, resolveHumanRunTitle({ currentArtefactHeading: documentHeading, runContent: runState?.content, runId }),
-    qaAcceptance?.summary || decisionMarkdown || decisionBriefFromSummary(summaryMarkdown, p.presentation_language) || summaryMarkdown, qaAcceptance?.effect || pack.primary.afterApproval[gate],
+  const title = resolveHumanRunTitle({ currentArtefactHeading: documentHeading, runContent: runState?.content, runId });
+  const parts = [`## ${pack.gateActionTitles[gate]}`, title,
+    summaryMarkdown, qaAcceptance?.effect || pack.primary.afterApproval[gate],
     german ? 'Antworte „Dokument lesen“, um diese Fassung vollständig im Chat zu lesen. Fragen und Änderungswünsche kannst du hier besprechen. Ohne deine Freigabe bleibt dieser Schritt offen.'
       : 'Reply “Read document” to read this complete version in Chat. Discuss questions and requested changes here. This step remains open until you approve.',
     pack.decisionCard.chatApprovalHint.replace('{gate}', gate),
-    `### ${german ? 'Details und Nachweise' : 'Details and evidence'}\n\n${summaryMarkdown}`,
     `### ${german ? 'Fassung und Quellen' : 'Version and sources'}\n\nRun: \`${runId}\` · ${pack.gateTitles[gate]} · Revision: \`${revisionId}\`\n\nSHA-256: \`${artefactDigest}\``];
+  const markdown = parts.join('\n\n');
   return parts.every((part) => typeof part === "string" && part.trim())
-    ? { markdown: parts.join("\n\n"), companion_markdown: [german
-          ? `Die AGDF-Karte ist geöffnet. Du kannst dort „${qaAcceptance?.approve_label || 'Freigeben'}“ klicken oder hier \`Approval: ${gate}\` eingeben. Beide Wege entscheiden dieselbe vorgelegte Fassung einmal.`
-          : `The AGDF card is open. Click “${qaAcceptance?.approve_label || 'Approve'}” there or enter \`Approval: ${gate}\` here. Both paths decide the same presented version once.`, ...parts].join("\n\n"), preview_markdown: artifactSection,
+    ? { markdown, companion_markdown: german
+          ? `Die Entscheidungsfassung „${title.slice(0, 240)}“ (${gate}, Revision ${revisionId}) wird in der bestätigten AGDF-Ansicht angezeigt.`
+          : `The decision “${title.slice(0, 240)}” (${gate}, revision ${revisionId}) is displayed in the confirmed AGDF view.`, preview_markdown: artifactSection,
         artefact_digest: artefactDigest, summary_digest: summaryDigest, summary_markdown: summaryMarkdown,
-        document_content: documentContent, document_language: documentLanguage,
+        document_content: markdown, document_language: p.presentation_language,
         ...(qaAcceptance ? { qa_acceptance: { kind: qaAcceptance.kind, digest: qaAcceptance.digest } } : {}) } : null;
 }