create-agdf 0.30.0 → 0.32.0

package/runtime/core/lib/control-state/run-material.js

@@ -15,8 +15,8 @@ import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
 import { readPendingSourceRevisionJournal } from './run-step-transaction.js';
 import { inspectPlannedOperation, inspectPlannedSelection } from './planned-entry.js';
 
-export const MATERIAL_LIMITS = Object.freeze({ part: 16384, file: 131072, set: 524288, sets: 4, total: 2097152,
-  lifetime: 600000, idle: 120000 });
+import { MATERIAL_LIMITS } from './material-limits.js';
+export { MATERIAL_LIMITS } from './material-limits.js';
 
 // A rejected transfer step names its concrete cause; the reason code stays stable for clients.
 const MATERIAL_RECOVERY = Object.freeze({
@@ -108,23 +108,34 @@ export function createRunMaterialStore({ now = Date.now } = {}) {
         const state = current(input), p = input.command.payload;
         expire();
         let row;
-        if (p.action === 'begin') {
+        if (p.action === 'begin' || p.action === 'put') {
+          // The small-text path bundles only private transfer work. Validate the
+          // whole set before allocating; canonical recording still uses its owner.
+          const files = p.action === 'put' ? p.files.map(({ slot, content }) => {
+            const bytes = Buffer.from(content, 'utf8');
+            if (bytes.length > MATERIAL_LIMITS.inline || new TextDecoder('utf-8', { fatal: true }).decode(bytes) !== content)
+              throw Error('material_text_invalid');
+            return { slot, bytes: bytes.length, content, data: bytes };
+          }) : p.files;
           const request = digest(canonicalJson(input));
           row = sets.get(input.operation_id);
           if (row) {
             if (row.request !== request || row.binding !== binding(input)) throw Error('operation_payload_conflict');
           } else {
-            const size = p.files.reduce((n, f) => n + f.bytes, 0);
+            const size = files.reduce((n, f) => n + f.bytes, 0);
             const resolutionBytes = currentInputResolution() ? Buffer.byteLength(canonicalJson(currentInputResolution())) : 0;
-            if (!p.files.length || p.files.length > 4 || p.files.some(f => !Number.isSafeInteger(f.bytes) || f.bytes < 0 || f.bytes > MATERIAL_LIMITS.file)
+            if (!files.length || files.length > 4 || files.some(f => !Number.isSafeInteger(f.bytes) || f.bytes < 0 || f.bytes > MATERIAL_LIMITS.file)
               || size + resolutionBytes > MATERIAL_LIMITS.set || sets.size >= MATERIAL_LIMITS.sets
               || [...sets.values()].reduce((n, r) => n + r.size + r.resolutionBytes, size + resolutionBytes) > MATERIAL_LIMITS.total) throw Error('material_resource_limit');
             row = { request, binding: binding(input), size, created: now(), touched: now(), resolutions: new Map(), resolutionBytes: 0,
-              files: p.files.map(f => ({ ...f, parts: [], received: 0, material_id: randomUUID(), content: null, digest: null })) };
+              files: files.map(f => ({ slot: f.slot, bytes: f.bytes, parts: f.data ? [f.data] : [],
+                received: f.data ? f.bytes : 0, material_id: randomUUID(), content: f.content ?? null,
+                digest: f.data ? digest(canonicalRunText(f.content)) : null })) };
             sets.set(input.operation_id, row);
           }
           rememberResolution(row, input);
-          return envelope('accepted', null, { transfer_id: input.operation_id, files: row.files.map(({ slot, bytes, received }) => ({ slot, bytes, received })), limits: MATERIAL_LIMITS }, state);
+          return envelope('accepted', null, { transfer_id: input.operation_id, files: row.files.map(({ slot, bytes, received, content, material_id, digest }) => ({ slot, bytes, received,
+            ...(content !== null ? { sealed: true, reference: { material_id, digest } } : {}) })), limits: MATERIAL_LIMITS }, state);
         }
         row = rowFor(input, p.transfer_id);
         rememberResolution(row, input);
@@ -195,6 +206,13 @@ export function createRunMaterialStore({ now = Date.now } = {}) {
       // parts in that same set cannot be used for another current write.
       for (const [id, row] of sets) if (row.files.some(file => ids.has(file.material_id))) sets.delete(id);
     },
+    // Review facts (companion core SDD-008): the sealed text of one transfer for the runtime's bounded
+    // preview, or null when it is unknown or not sealed. It reads only; it is never a material grant.
+    sealedFiles(transferId) {
+      const row = sets.get(transferId);
+      if (closed || !row || row.files.some(file => file.content === null)) return null;
+      return row.files.map(({ slot, content, digest: hash }) => Object.freeze({ slot, content, digest: hash }));
+    },
     close() { closed = true; sets.clear(); },
     inspectOwnership() { expire(); return { sets: sets.size, bytes: [...sets.values()].reduce((n, r) => n + r.size, 0) }; },
   });

package/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) {
@@ -300,6 +355,35 @@ function artifactSummary(gate, markdown, { runId, revisionId, language, sourceLa
   return { markdown: summary, digest: hash(summary) };
 }
 
+// Cockpit presentation reuses the same language and summary owner as authoring checks.
+// The structured rows are derived from that summary; no second content authority is created.
+export function projectCockpitSummary(gate, markdown, languages, context = {}) {
+  if (!['UR', 'PRD', 'SD', 'TP'].includes(gate)) return null;
+  try {
+    const readiness = evaluateApprovalSummaryReadiness(gate, markdown, languages, { path: context.artefactPath });
+    if (!readiness.ready) return null;
+    const summary = artifactSummary(gate, markdown, { ...context, language: languages.presentation_language, sourceLanguage: languages.artifact_language });
+    const priorities = {
+      UR: [/^(?:Ziel|Goal)$/iu, /^(?:Umfang|Scope)$/iu, /^(?:Abnahme|Abnahmesignal|Acceptance)$/iu],
+      PRD: [/^(?:Ziel|Nutzerziel|Goal|User intent)$/iu, /^(?:Umfang|Produktumfang|Scope|Product scope)$/iu, /^(?:AC-[A-Z0-9-]+)$/iu],
+      SD: [/^(?:Lösung|Solution)$/iu, /^(?:Verantwortung|Ownership)$/iu, /^(?:Entscheidungen|Design decisions)$/iu],
+      TP: [/^(?:Aufgaben|Tasks)$/iu, /^(?:Tests)$/iu, /^(?:Risiken|Risks)$/iu],
+    };
+    const rows = summary.markdown.split(/\r?\n/u).flatMap(line => {
+      const match = line.match(/^[-*]\s+([^:\n]{1,80}):\s*(\S.*)$/u);
+      return match && match[2].length <= 1200 ? [{ label: match[1].trim(), text: match[2].trim() }] : [];
+    });
+    const items = priorities[gate].flatMap(pattern => {
+      const matches = rows.filter(row => pattern.test(row.label));
+      return matches.length === 1 ? matches : [];
+    });
+    return { state: 'available', gate, items, markdown: summary.markdown, authorizes: false };
+  } catch (error) {
+    if (String(error.message).startsWith('approval_summary_')) return null;
+    throw error;
+  }
+}
+
 // A compact decision brief is a projection of the already validated, source-
 // authored summary. Missing authored fields stay absent; no agent/UI paraphrase.
 export function decisionBriefFromSummary(summary, language) {
@@ -388,16 +472,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;

package/runtime/core/lib/control-state/run-revision.js

@@ -22,7 +22,7 @@ import { join } from "node:path";
 import { runPath } from "./run-state-reader.js";
 import { readArtefactBindings } from "./artefact-bindings.js";
 import { exactApprovedArtefacts, readContainedJson, validateBindingProof } from "./artefact-binding-proof.js";
-import { SOURCE_GATES, appendSourceRevision, readSourceRevisions, revisionHistoryPrefix, sourceRevisionImpact, sourceRevisionConfirmation, validExpandedRevisionProof } from "./run-source-revisions.js";
+import { SOURCE_GATES, appendSourceRevision, readSourceRevisions, revisionHistoryPrefix, sourceRevisionImpact, sourceRevisionConfirmation, revisionProofProblems } from "./run-source-revisions.js";
 import { collectRevisionHistory, byteDigest, inspectRevisionHistory, readHistoryBytes } from "./run-revision-history.js";
 import { commitRunStepLocked, recoverPendingRunStepLocked, pendingRunStepConflictIds, readPendingRunStepJournal, readPendingSourceRevisionJournal } from "./run-step-transaction.js";
 import { pendingRunStepPath } from "./run-step-pending.js";
@@ -139,27 +139,45 @@ function prepareSourceRevision(root, input) {
       || boundary.approved.includes(row.type) && state.approvals.get(row.type)?.status !== "approved")) throw revisionError("approved_source_invalid");
   if (input.commandContext && input.proposalBinding?.path !== evidence) throw revisionError('revision_source_binding_invalid');
   const boundProposal = input.proposalMaterial ? { validate: () => {} } : input.proposalBinding ? readOperationSource(root, runId, input.proposalBinding) : null;
-  if (!exactObject(proposal, REVISION_PROPOSAL_FIELDS)
-      || proposal.target_id !== resolveControlCommandTarget(root).target_id
-      || proposal.run_id !== runId || proposal.expected_revision_id !== revisionId || proposal.operation_id !== operationId
-      || proposal.source_gate !== sourceGate || !nonempty(proposal.reason) || !nonempty(proposal.intended_change)
-      || canonicalJson(proposal.sources) !== canonicalJson(sources)) throw revisionError("revision_proposal_invalid");
+  // Name each violated field with its expected binding: these are facts the caller
+  // may read anyway, and the proposal can only be corrected when they are known.
+  const expected = { target_id: resolveControlCommandTarget(root).target_id, run_id: runId, expected_revision_id: revisionId,
+    operation_id: operationId, source_gate: sourceGate, sources };
+  const problems = [
+    ...(exactObject(proposal, REVISION_PROPOSAL_FIELDS) ? [] : [`fields must be exactly ${REVISION_PROPOSAL_FIELDS.join(", ")}`]),
+    ...Object.entries(expected).filter(([key, value]) => canonicalJson(proposal[key] ?? null) !== canonicalJson(value))
+      .map(([key, value]) => `${key} must be ${canonicalJson(value)}`),
+    ...["reason", "intended_change"].filter(key => !nonempty(proposal[key])).map(key => `${key} must be nonempty text`),
+  ];
+  if (problems.length) throw revisionError("revision_proposal_invalid",
+    `Correct the staged proposal and stage it again; operation_id is the UUID of this source_revision command. ${problems.join("; ")}.`);
   const assessment = proposal.impact_assessment, index = SOURCE_GATES.indexOf(sourceGate);
-  if (!exactObject(assessment, REVISION_IMPACT_FIELDS)
-      || !nonempty(assessment.reviewer) || assessment.earliest_source !== sourceGate || !nonempty(assessment.implementation_evidence)
-      || !Array.isArray(assessment.unresolved) || assessment.unresolved.length
-      || !Array.isArray(assessment.upstream) || assessment.upstream.length !== index
-      || !assessment.upstream.every((row, i) => exactObject(row, REVISION_UPSTREAM_FIELDS)
-        && nonempty(row.rationale) && canonicalJson({ type: row.type, path: row.path, digest: row.digest }) === canonicalJson(sources[i]))) throw revisionError("source_impact_unresolved", "Resolve the earliest changed source and unchanged upstream rationale with its owner; then regenerate the proposal.");
-  const analyticalTypes = ["Brownfield Review", "UX Intent Definition"].filter(type => state.artefacts.get(type)?.path);
-  if (!Array.isArray(assessment.analyses) || assessment.analyses.length !== analyticalTypes.length
-      || !assessment.analyses.every((row, i) => exactObject(row, REVISION_ANALYSIS_FIELDS)
-        && row.type === analyticalTypes[i] && row.path === state.artefacts.get(row.type).path
-        && row.digest === artefactFileDigest(root, row.path) && nonempty(row.reason)
-        && ["retain", "reassess"].includes(row.disposition) && (sourceGate !== "UR" || row.disposition === "reassess"))) throw revisionError("analysis_applicability_unresolved");
+  // Like the binding check above, each rejection names the expected entries.
+  const identity = row => canonicalJson({ type: row?.type, path: row?.path, digest: row?.digest });
+  const upstream = sources.slice(0, index);
+  const impactProblems = [
+    ...(exactObject(assessment, REVISION_IMPACT_FIELDS) ? [] : [`impact_assessment fields must be exactly ${REVISION_IMPACT_FIELDS.join(", ")}`]),
+    ...(nonempty(assessment?.reviewer) ? [] : ["impact_assessment.reviewer must be nonempty text"]),
+    ...(assessment?.earliest_source === sourceGate ? [] : [`impact_assessment.earliest_source must be "${sourceGate}"`]),
+    ...(nonempty(assessment?.implementation_evidence) ? [] : ["impact_assessment.implementation_evidence must be nonempty text"]),
+    ...(Array.isArray(assessment?.unresolved) && !assessment.unresolved.length ? [] : ["impact_assessment.unresolved must be []"]),
+    ...(Array.isArray(assessment?.upstream) && assessment.upstream.length === upstream.length
+      && assessment.upstream.every((row, i) => exactObject(row, REVISION_UPSTREAM_FIELDS) && nonempty(row.rationale) && identity(row) === identity(upstream[i]))
+      ? [] : [`impact_assessment.upstream must list exactly ${canonicalJson(upstream)} in order, each with a nonempty rationale`]),
+  ];
+  if (impactProblems.length) throw revisionError("source_impact_unresolved",
+    `Resolve the earliest changed source and unchanged upstream rationale with its owner; then regenerate the proposal. ${impactProblems.join("; ")}.`);
+  const analyses = ["Brownfield Review", "UX Intent Definition"].filter(type => state.artefacts.get(type)?.path)
+    .map(type => ({ type, path: state.artefacts.get(type).path, digest: artefactFileDigest(root, state.artefacts.get(type).path) }));
+  const dispositions = sourceGate === "UR" ? ["reassess"] : ["retain", "reassess"];
+  if (!Array.isArray(assessment.analyses) || assessment.analyses.length !== analyses.length
+      || !assessment.analyses.every((row, i) => exactObject(row, REVISION_ANALYSIS_FIELDS) && identity(row) === identity(analyses[i])
+        && nonempty(row.reason) && dispositions.includes(row.disposition)))
+    throw revisionError("analysis_applicability_unresolved", `Set impact_assessment.analyses to exactly the registered analyses ${canonicalJson(analyses)} in order, each with a nonempty reason and disposition ${dispositions.join(" or ")}; unregistered analyses are not listed.`);
   const readArtefact = path => { try { return readHistoryBytes(root, path).toString('utf8'); } catch { return undefined; } };
-  if (!validExpandedRevisionProof(proposal, state, readArtefact, boundary.initiating_phase))
-    throw revisionError('revision_impact_proof_invalid', 'Bind concrete changed statements, earliest source, actual phase and every exact quality record; unknown or affected associations require reassessment.');
+  const proofProblems = revisionProofProblems(proposal, state, readArtefact, boundary.initiating_phase);
+  if (proofProblems.length) throw revisionError('revision_impact_proof_invalid',
+    `Bind concrete changed statements, earliest source, actual phase and every exact quality record; unknown or affected associations require reassessment. ${proofProblems.slice(0, 5).join('; ')}.`);
   const affected = SOURCE_GATES.slice(index);
   const qualityPaths = proposal.quality_assessment.map(row => row.record.path).filter(Boolean);
   const history = collectRunRevisionClosure(root, run, state, operationId, boundary.approved, [evidence, ...qualityPaths], { proposalMaterial: input.proposalMaterial });

package/runtime/core/lib/control-state/run-source-revisions.js

@@ -50,7 +50,12 @@ export function sourceRevisionQualityFacts(state, readArtefact) {
   return facts;
 }
 
-export function validExpandedRevisionProof(proposal, state, readArtefact, phase) {
+export const validExpandedRevisionProof = (...args) => revisionProofProblems(...args).length === 0;
+
+// The same rules as a list of named violations, so a rejected proposal can be
+// corrected deliberately instead of by trial. Later checks rely on the structure
+// confirmed by earlier ones, so each block stops at its own violations.
+export function revisionProofProblems(proposal, state, readArtefact, phase) {
   const changed = proposal.changed_statements, affected = SOURCE_GATES.slice(SOURCE_GATES.indexOf(proposal.source_gate));
   const nonempty = value => typeof value === 'string' && value.trim() && value.length <= 4096;
   const assessmentProof = proposal.impact_assessment, index = SOURCE_GATES.indexOf(proposal.source_gate);
@@ -64,25 +69,40 @@ export function validExpandedRevisionProof(proposal, state, readArtefact, phase)
     || !Array.isArray(assessmentProof.analyses) || assessmentProof.analyses.length !== analyticalTypes.length
     || !assessmentProof.analyses.every((row, i) => exactObject(row, REVISION_ANALYSIS_FIELDS) && row.type === analyticalTypes[i]
       && row.path === state.artefacts.get(row.type).path && hashes(row.digest) && nonempty(row.reason)
-      && ['retain', 'reassess'].includes(row.disposition) && (proposal.source_gate !== 'UR' || row.disposition === 'reassess'))) return false;
-  if (proposal.policy_version !== 2 || proposal.initiating_phase !== phase || !Array.isArray(changed) || !changed.length
-      || !changed.every(row => exactObject(row, REVISION_STATEMENT_FIELDS) && affected.includes(row.type)
-        && proposal.sources.some(source => source.type === row.type && source.path === row.path && source.digest === row.digest)
-        && [row.statement, row.intended_change, row.reason].every(nonempty)
-        && String(readArtefact(row.path)).replace(/\r\n?/gu, '\n').includes(row.statement))
-      || !changed.some(row => row.type === proposal.source_gate)) return false;
+      && ['retain', 'reassess'].includes(row.disposition) && (proposal.source_gate !== 'UR' || row.disposition === 'reassess')))
+    return ['impact_assessment is invalid'];
+  const statementProblem = (row, i) => {
+    if (!exactObject(row, REVISION_STATEMENT_FIELDS)) return `changed_statements[${i}] fields must be exactly ${REVISION_STATEMENT_FIELDS.join(', ')}`;
+    if (!affected.includes(row.type)) return `changed_statements[${i}].type must be one of ${affected.join(', ')}`;
+    if (!proposal.sources.some(source => source.type === row.type && source.path === row.path && source.digest === row.digest))
+      return `changed_statements[${i}] path and digest must equal its entry in sources`;
+    if (![row.statement, row.intended_change, row.reason].every(nonempty)) return `changed_statements[${i}] statement, intended_change and reason must be nonempty text`;
+    if (!String(readArtefact(row.path)).replace(/\r\n?/gu, '\n').includes(row.statement))
+      return `changed_statements[${i}].statement must be an exact excerpt of ${row.path}`;
+    return null;
+  };
+  const changeProblems = [
+    ...(proposal.policy_version === 2 ? [] : ['policy_version must be 2']),
+    ...(proposal.initiating_phase === phase ? [] : [`initiating_phase must be "${phase}"`]),
+    ...(Array.isArray(changed) && changed.length ? changed.map(statementProblem).filter(Boolean) : ['changed_statements must be a nonempty list']),
+    ...(Array.isArray(changed) && changed.some(row => row?.type === proposal.source_gate) ? [] : [`changed_statements must include a ${proposal.source_gate} statement`]),
+  ];
+  if (changeProblems.length) return changeProblems;
   const facts = sourceRevisionQualityFacts(state, readArtefact), assessment = proposal.quality_assessment;
-  if (!Array.isArray(assessment) || !assessment.length || assessment.length !== facts.length) return false;
-  return assessment.every((row, i) => {
-    if (!exactObject(row, REVISION_QUALITY_FIELDS) || !['retain', 'reassess'].includes(row.disposition) || !nonempty(row.reason)) return false;
+  if (!Array.isArray(assessment) || !assessment.length || assessment.length !== facts.length)
+    return [`quality_assessment must contain exactly ${facts.length} rows, one per quality record in order`];
+  return assessment.map((row, i) => {
+    if (!exactObject(row, REVISION_QUALITY_FIELDS) || !['retain', 'reassess'].includes(row.disposition) || !nonempty(row.reason))
+      return `quality_assessment[${i}] needs exactly ${REVISION_QUALITY_FIELDS.join(', ')} with disposition retain or reassess and a nonempty reason`;
     const { disposition, reason, ...proof } = row;
-    if (canonicalJson(proof) !== canonicalJson(facts[i])) return false;
+    if (canonicalJson(proof) !== canonicalJson(facts[i])) return `quality_assessment[${i}] must copy quality record ${canonicalJson(facts[i])} unchanged`;
     const analysis = proposal.impact_assessment.analyses.find(item => item.type === row.record.type);
-    if (analysis && (analysis.disposition !== disposition || analysis.path !== row.record.path || analysis.digest !== row.record.digest)) return false;
-    return disposition !== 'retain' || row.association === 'current'
-      && !row.sources.some(source => affected.includes(source.type))
-      && !(proposal.source_gate === 'UR' && analysis);
-  });
+    if (analysis && (analysis.disposition !== disposition || analysis.path !== row.record.path || analysis.digest !== row.record.digest))
+      return `quality_assessment[${i}].disposition must equal the ${row.record.type} analysis disposition`;
+    if (disposition === 'retain' && !(row.association === 'current' && !row.sources.some(source => affected.includes(source.type))
+      && !(proposal.source_gate === 'UR' && analysis))) return `quality_assessment[${i}] must be reassess: its record is not current or depends on a changed source`;
+    return null;
+  }).filter(Boolean);
 }
 
 export function sourceRevisionImpact(proposal, activeBindings) {

package/runtime/core/lib/control-state/run-state-reader.js

@@ -41,6 +41,15 @@ export function readSelectedRun(root, id) {
     last_updated_at: parsed.meta.updated_at || stateStats.mtime.toISOString() };
 }
 
+// The entry names discovery treats as runs: every non-dot entry of the runs folder, sorted. Empty when the
+// folder is missing or no directory. It reads no layout, so the companion run view also counts the run
+// folders of a store whose layout is not supported (PRD AC-002, TP T-004).
+export function runFolderEntries(root) {
+  const dir = join(root, ".agdf", "control", "runs");
+  if (!existsSync(dir) || lstatKindSync(dir) !== 'directory') return [];
+  return readdirSync(dir).filter((entry) => !entry.startsWith(".")).sort();
+}
+
 function discoverCapturedRuns(root) {
   const dir = join(root, ".agdf", "control", "runs");
   if (!existsSync(dir)) return [];
@@ -48,9 +57,7 @@ function discoverCapturedRuns(root) {
   if (lstatKindSync(dir) !== 'directory') {
     return [invalidRun("<repository>", dir)];
   }
-  return readdirSync(dir)
-    .filter((entry) => !entry.startsWith("."))
-    .sort()
+  return runFolderEntries(root)
     .map((id) => {
       const directory = join(dir, id);
       const path = join(directory, "RUN_STATE.md");

package/runtime/core/lib/control-state/run-steps.js

@@ -1,6 +1,6 @@
 import { extractField } from '../control-evaluation/verified-change.js';
 import { transitionDecisionForRunState } from '../control-evaluation/gate-policy.js';
-import { runDocumentPath, runEvidencePath, isRunDataPath } from './run-identity.js';
+import { runDocumentPath, runEvidencePath, isRunDataPath, RUN_STEP_SLOTS } from './run-identity.js';
 import { resolutionRecordVersion } from './input-resolution.js';
 import { resolveControlCommandTarget } from './approval-command-contract.js';
 
@@ -48,7 +48,7 @@ import { withRunMutationLock, writeRunMutationLocked } from './run-mutation.js';
 import { APPROVAL_GATES as DECISION_GATES, REVISION_ID_PATTERN } from './run-identity.js';
 import { runSealState, artefactFileDigest } from './run-seal.js';
 import { inspectUxIntentDecision } from '../control-evaluation/definition-sources.js';
-import { readReportDecision } from '../control-evaluation/report-decision.js';
+import { readReportDecision, REPORT_DECISION_FORMAT } from '../control-evaluation/report-decision.js';
 import { prepareVerifiedChangeRecording } from './run-verified-change.js';
 
 // Record one typed transition and its owned files in a single sealed revision.
@@ -77,6 +77,8 @@ function readRunArtefact(root, runId, rawPath, limit = 131072) {
 // Review reports are read within the bound of the closeout quality inspection (inspectQaReports).
 const REVIEW_REPORT_LIMIT = 262144;
 // Every recording of a review or QA report applies the closeout quality rules; at most 64 diagnostics are returned.
+// The staged report must state the result where the parser reads it.
+const unconfirmedDecision = runId => rejected(runId, 'internal_result_unconfirmed', { recovery: REPORT_DECISION_FORMAT.instruction });
 const findingsRefusal = (runId, diagnostics) => rejected(runId, 'review_findings_invalid',
   { diagnostics: diagnostics.slice(0, 64), ...(diagnostics.length > 64 ? { diagnostics_truncated: true } : {}) });
 function qaReportDiagnostics(root, runId, qa, control, proposedContent) {
@@ -132,7 +134,7 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
     stagedSource = resolveMaterial?.(input.sourceBinding);
     const slot = input.step === 'internal' ? input.internalStep : input.step === 'verified_change' ? 'Verified Change'
       : input.step === 'closeout' && stagedSource?.slot === 'Verified Change' ? 'Verified Change'
-      : ({ ur: 'UR', route: 'Brownfield Review', review: 'CR', evidence: 'EVIDENCE', closeout: 'OR' })[input.step];
+      : RUN_STEP_SLOTS[input.step];
     if (!stagedSource || stagedSource.slot !== slot) return rejected(runId, 'material_slot_mismatch');
     const file = slot === 'EVIDENCE' ? `EVIDENCE-${stagedSource.digest.slice(7)}.md`
       : ({ UR: 'UR.md', OR: 'OR.md', 'Verified Change': 'VERIFIED_CHANGE.md', ...INTERNAL_STEP_FILES })[slot];
@@ -178,7 +180,7 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
     if (step === "review") {
       if (!['CR', 'Quick Task Execution'].includes(before.current_gate)
           || !['pass', 'revise', 'block'].includes(input.decision)) return rejected(runId, "review_step_not_ready");
-      if (readReportDecision(operationSource.content) !== input.decision) return rejected(runId, "internal_result_unconfirmed");
+      if (readReportDecision(operationSource.content) !== input.decision) return unconfirmedDecision(runId);
       const diagnostics = reviewFindingDiagnostics('CR', operationSource.content, { decision: input.decision });
       if (diagnostics.length) return findingsRefusal(runId, diagnostics);
     }
@@ -218,7 +220,7 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
       if (!checked.well_formed || !checked.supported || checked.decision !== input.decision
         || input.decision === 'not_applicable' && (control.source_revision_ux_required || before.next_operation?.analysis === input.internalStep)) return rejected(runId, 'internal_result_unconfirmed');
     } else {
-      if (readReportDecision(operationSource.content, { allowNotApplicable: true }) !== input.decision) return rejected(runId, "internal_result_unconfirmed");
+      if (readReportDecision(operationSource.content, { allowNotApplicable: true }) !== input.decision) return unconfirmedDecision(runId);
     }
     if (CORRECTABLE_REVIEWS.includes(input.internalStep)) {
       const diagnostics = reviewFindingDiagnostics(input.internalStep, operationSource.content, { decision: input.decision });
@@ -306,6 +308,7 @@ function recordRunStepLocked(root, input, { policy, date, afterWrite, operationC
         // The quality obligation still names the decisive finding and, where available, its correction path.
         const qa = readiness.findings.includes('closeout_quality_unconfirmed') ? inspectQaReports(root, control, runId, 'pass', 64, true) : null;
         return rejected(runId, 'closeout_obligations_unfulfilled', { findings: readiness.findings,
+          ...(readiness.expected ? { expected: readiness.expected } : {}),
           ...(qa?.reason ? { reason_detail: closeoutQualityDetail(qa, control) } : {}) });
       }
       if (!exactApprovedArtefacts(root, control)) return rejected(runId, 'approved_source_proof_invalid');

package/runtime/core/lib/control-state/run-title.js

@@ -0,0 +1,43 @@
+// One owner for a Run's human title and orienting Objective. Pure: no `node:` import, so the run
+// inventory, the cockpit, the companion run view and the status card share exactly this rule.
+// Precedence: registered UR heading, then the authored Objective, then the normalized Run ID.
+import { isDecisionContentPlaceholder } from "../control-evaluation/decision-content-placeholder.js";
+
+// The run-ID title every reader shows when no authored title exists.
+export function normalizedRunTitle(runId) {
+  const words = String(runId ?? "").replace(/[._-]+/g, " ").replace(/\s+/g, " ").trim();
+  return words ? words.replace(/\b\p{L}/gu, (letter) => letter.toUpperCase()) : "AGDF run";
+}
+
+// A heading as display text: no leading hashes and no inline Markdown marks.
+export function plainHeading(value) {
+  return String(value ?? "").replace(/^#+\s*/u, "").replace(/[`*_]/gu, "").replace(/\s+/gu, " ").trim();
+}
+
+// Lines of one level-two section up to the next heading; an empty section stays empty.
+function sectionLines(text, heading) {
+  const lines = text.split("\n"), start = lines.findIndex(line => line.trimEnd() === `## ${heading}`);
+  if (start < 0) return [];
+  const rest = lines.slice(start + 1), end = rest.findIndex(line => /^#{1,2} /u.test(line));
+  return end < 0 ? rest : rest.slice(0, end);
+}
+
+// The first paragraph of the Objective, so hard-wrapped objectives stay whole. A template prompt,
+// a status word or a bare generated Run ID is no orientation and yields null.
+export function authoredObjective(runContent) {
+  const text = String(runContent ?? "").replace(/^/u, "").replace(/\r\n?/gu, "\n");
+  const lines = sectionLines(text, "Objective").map(value => value.trim()), first = lines.findIndex(Boolean);
+  if (first < 0) return null;
+  const paragraph = lines.slice(first), end = paragraph.indexOf("");
+  const value = (end < 0 ? paragraph : paragraph.slice(0, end)).join(" ")
+    .replace(/^(?:[-*>]|#+|\d+\.)\s+/u, "").replace(/\*\*|__|`/gu, "").replace(/\s+/gu, " ").trim();
+  return isDecisionContentPlaceholder(value) ? null : value;
+}
+
+// `urHeading` is the registered UR document heading without its "UR:" prefix, when the caller read it.
+export function runIdentity({ runId, runContent, urHeading } = {}) {
+  const objective = authoredObjective(runContent), ur = plainHeading(urHeading);
+  if (ur) return { title: ur, title_source: "ur", objective };
+  if (objective) return { title: objective, title_source: "objective", objective };
+  return { title: normalizedRunTitle(runId), title_source: "run_id", objective: null };
+}

package/runtime/core/lib/index.js

@@ -4,12 +4,14 @@ import { createDeliveryContinuationService } from "./delivery-continuation/servi
 import { createControlInspectService } from "./control-inspect/service.js";
 import { createRunCommandService } from "./control-state/run-command-service.js";
 import { createRunMaterialStore } from './control-state/run-material.js';
+import { withMaterialRecordingCalls } from './control-inspect/material-recording-calls.js';
 import { evaluateGateCheck } from './control-evaluation/gate-check.js';
 import { evaluateDoctor } from './control-evaluation/doctor.js';
 export { createResourceContext, resources } from "./resources/context.js";
 export function createCoreServices({ resources: context = resources, observers = {}, runtimeBinding } = {}) {
   const contracts = { runtimeContractModules: () => runtimeContractModules(context.pluginDefinition), readRuntimeContract: module => readRuntimeContract(module, { context }), readSkillRuntimeContracts: skill => readSkillRuntimeContracts(skill, { context }) };
-  const material = createRunMaterialStore();
+  const store = createRunMaterialStore();
+  const material = Object.freeze({ ...store, stage: input => withMaterialRecordingCalls(input, store.stage(input)) });
   const reads = observers.gitObservation ? { ...observers,
     evaluateGateCheck: observers.evaluateGateCheck ?? ((root, selection) => evaluateGateCheck(root, selection, observers.gitObservation)),
     evaluateDoctor: observers.evaluateDoctor ?? ((root, selection) => evaluateDoctor(root, selection, observers.gitObservation)),