create-agdf 0.30.0 → 0.32.0

package/generated/plugins/agdf/runtime/create-agdf/lib/runtime/validator-application.js

@@ -4,7 +4,7 @@ import { validateCommandOptions, commandGroupRoutes } from "../cli/command-regis
 import { CliUsageError, parseArgs } from "../cli/parse-args.js";
 import { pluginDefinition } from "../cli/runtime-context.js";
 
-const validatorCommands = new Set(["project-state", "operation-status", "target-check", "skill-dispatch", "doctor", "gate-check", "delivery-map", "inventory", "delivery-path-search", "contract", "control-maintenance", "run-create", "run-present", "run-revise", "run-step", "run-approve", "run-close", ...Object.keys(commandGroupRoutes)]);
+const validatorCommands = new Set(["project-state", "operation-status", "run-view", "target-check", "skill-dispatch", "doctor", "gate-check", "delivery-map", "inventory", "delivery-path-search", "contract", "control-maintenance", "run-create", "run-present", "run-revise", "run-step", "run-approve", "run-close", ...Object.keys(commandGroupRoutes)]);
 
 export async function runValidatorCli(argv = process.argv.slice(2), adapters = {}) {
   const io = adapters.io ?? console;
@@ -22,7 +22,7 @@ export async function runValidatorCli(argv = process.argv.slice(2), adapters = {
     return error.exitCode;
   }
   if (parsed.kind === "help") {
-    io.log("AGDF surface-local validator: project-state | operation-status | target-check | skill-dispatch | doctor | gate-check | delivery-map | inventory | delivery-path-search | contract | control-maintenance | run-create | run-present | run-revise | run-step | run-approve | run-close");
+    io.log("AGDF surface-local validator: project-state | operation-status | run-view | target-check | skill-dispatch | doctor | gate-check | delivery-map | inventory | delivery-path-search | contract | control-maintenance | run-create | run-present | run-revise | run-step | run-approve | run-close");
     return 0;
   }
   let options;

package/generated/plugins/agdf/runtime/create-agdf/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agdf/local-validator-runtime",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "private": true,
   "type": "module",
   "imports": {

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/companion/events.js

@@ -0,0 +1,157 @@
+// Companion events (SD SDD-005, SDD-009): the pure mapping from the final result of an AGDF MCP tool
+// call to zero or one event of schema `companion-event/1`, and the reader of the versioned journal
+// format. Events come from real MCP outcomes, never from host hooks, so the agent cannot shape them.
+// Read-only tools produce none. Review facts (SDD-008) are computed by the runtime and handed in.
+// Host-neutral: no Node built-in, no host API.
+import { COMMAND_TOOL_NAMES, TOOL_RESULT_META } from '../mcp-tool-errors.js';
+import { RUN_STEP_SLOTS } from '../control-state/run-identity.js';
+
+export const COMPANION_EVENT_SCHEMA = 'companion-event/1';
+export const EVENT_KINDS = Object.freeze(['approval_requested', 'approval_recorded', 'write_rejected', 'effect_unknown',
+  'recovery_required', 'run_completed', 'material_staged', 'document_recorded']);
+// Decision P1: these kinds interrupt as a toast, together with a digest mismatch (a drift warning of
+// the run view); approval recorded and write rejected appear in the pane only.
+export const TOAST_KINDS = Object.freeze(['approval_requested', 'effect_unknown', 'recovery_required', 'run_completed']);
+// Decision P2: at most 40 lines or 4 KiB, whichever is smaller.
+export const PREVIEW_LIMITS = Object.freeze({ lines: 40, bytes: 4096 });
+export const SOURCE_MATCHES = Object.freeze(['match', 'mismatch', 'not_determinable', 'unavailable']);
+
+// The tool-result descriptor key and the command tools come from the MCP tool-error contract, and the
+// slot of a recorded step from the run identity owner; all three modules are pure (CR finding CIR-04).
+export const TOOL_RESULT_META_KEY = TOOL_RESULT_META;
+const COMMAND_TOOLS = new Set(COMMAND_TOOL_NAMES);
+const TEXT_LIMIT = 256;
+const encoder = new TextEncoder();
+const bounded = value => (typeof value === 'string' && value.length ? value.slice(0, TEXT_LIMIT) : null);
+
+// The bounded preview of a text: cut after the 40th line break unless the text ends there, then to
+// at most 4096 UTF-8 bytes on a character boundary. Exactly 40 lines or 4096 bytes stay whole.
+export function reviewPreview(text) {
+  const value = String(text ?? '');
+  let preview = value;
+  let at = -1;
+  for (let line = 0; line < PREVIEW_LIMITS.lines; line += 1) {
+    at = value.indexOf('\n', at + 1);
+    if (at < 0) break;
+  }
+  if (at >= 0 && at < value.length - 1) preview = value.slice(0, at + 1);
+  if (encoder.encode(preview).length > PREVIEW_LIMITS.bytes) {
+    let size = 0;
+    let cut = 0;
+    for (const char of preview) {
+      const width = encoder.encode(char).length;
+      if (size + width > PREVIEW_LIMITS.bytes) break;
+      size += width;
+      cut += char.length;
+    }
+    preview = preview.slice(0, cut);
+  }
+  return { text: preview, truncated: preview.length < value.length, bytes: encoder.encode(value).length };
+}
+
+// One review fact: what the runtime saw of recorded or staged material. Unknown values stay null
+// ("unavailable"), never guessed (PRD AC-007).
+export function reviewFact({ slot = null, source, path = null, digest = null, text = null, sourceMatch }) {
+  const preview = typeof text === 'string' ? reviewPreview(text) : null;
+  return {
+    slot: bounded(slot),
+    source: source === 'path' ? 'path' : 'staged',
+    path: bounded(path),
+    digest: /^sha256:[a-f0-9]{64}$/u.test(digest ?? '') ? digest : null,
+    bytes: preview?.bytes ?? null,
+    preview: preview?.text ?? null,
+    truncated: preview?.truncated ?? null,
+    source_match: SOURCE_MATCHES.includes(sourceMatch) ? sourceMatch : 'unavailable',
+  };
+}
+
+// The slot (gate or step) a command names, for the event's gate field.
+export function commandGate(command = {}) {
+  const payload = command.payload ?? {};
+  if (command.kind === 'closeout.record') return 'OR';
+  if (command.kind === 'step.record') return payload.internal_step ?? RUN_STEP_SLOTS[payload.step] ?? null;
+  if (command.kind === 'verified_change.record') return 'Verified Change';
+  if (command.kind === 'ur_draft.replace') return 'UR';
+  if (command.kind === 'operation.recover') return null;
+  return typeof payload.gate === 'string' ? payload.gate : null;
+}
+
+function successKind(command, result) {
+  const kind = command?.kind;
+  if (kind === 'presentation.deliver') {
+    return result.historical_effect === true || result.presentation_delivery?.historical_delivery === true
+      ? null : 'approval_requested';
+  }
+  if (kind === 'approval.record') return 'approval_recorded';
+  if (kind === 'closeout.record') return 'run_completed';
+  if (kind === 'material.stage' && command.payload?.action === 'seal') return 'material_staged';
+  // Every document recording of run-steps.recordRunStep (run-command-service.js).
+  if (['step.record', 'artefact.record', 'verified_change.record', 'ur_draft.replace'].includes(kind)) return 'document_recorded';
+  return null;
+}
+
+// The event kind of one final command result, or null for a read, a replay or an outcome outside
+// the eight kinds. A failure is classified by the projected descriptor's effect state first, so a
+// thrown failure of unknown effect is never reported as rejected.
+export function eventKind(toolName, input, result) {
+  if (!COMMAND_TOOLS.has(toolName) || !result || typeof result !== 'object') return null;
+  const descriptor = result._meta?.[TOOL_RESULT_META_KEY] ?? null;
+  if (result.outcome === 'accepted') return successKind(input?.command, result);
+  if (result.outcome === 'already_applied') return null;
+  if (result.outcome === 'recovery_required') return 'recovery_required';
+  if (result.outcome === 'effect_unknown' || descriptor?.effect_state === 'unknown') return 'effect_unknown';
+  if (descriptor?.failed || result.outcome === 'rejected') return 'write_rejected';
+  return null;
+}
+
+// The event of one final tool result: { schema_version, id, at, root, run_id, gate, kind, outcome,
+// reason, operation_id, review } or null. `id`, `at` and `root` come from the writer; `review` holds
+// the runtime's review facts for staged or recorded material.
+export function deriveEvent(toolName, input, result, { id, at, root = null, review = null } = {}) {
+  const kind = eventKind(toolName, input, result);
+  if (!kind) return null;
+  const descriptor = result._meta?.[TOOL_RESULT_META_KEY] ?? null;
+  const facts = Array.isArray(review) && review.length && ['material_staged', 'document_recorded'].includes(kind) ? review.slice(0, 4) : null;
+  return {
+    schema_version: COMPANION_EVENT_SCHEMA,
+    id: bounded(id),
+    at: bounded(at),
+    root: typeof root === 'string' && root.length ? root : bounded(input?.primary_target) ?? bounded(input?.working_directory),
+    run_id: bounded(input?.run_id) ?? bounded(result.run_id),
+    gate: kind === 'material_staged' ? facts?.[0]?.slot ?? null : commandGate(input?.command),
+    kind,
+    outcome: bounded(result.outcome) ?? (descriptor?.failed ? 'failed' : null),
+    reason: descriptor?.failed ? bounded(descriptor.code) ?? bounded(result.reason) : null,
+    operation_id: bounded(input?.operation_id),
+    review: facts,
+  };
+}
+
+// A journal line is an event when it parses and carries the schema, a known kind and an id.
+export function validEvent(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && value.schema_version === COMPANION_EVENT_SCHEMA
+    && EVENT_KINDS.includes(value.kind) && typeof value.id === 'string' && typeof value.at === 'string';
+}
+
+// The events of a journal text in file order; malformed or foreign lines are skipped, since several
+// MCP servers may interleave lines (SDD-006).
+export function parseEventLines(text) {
+  const events = [];
+  for (const line of String(text ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const value = JSON.parse(line);
+      if (validEvent(value)) events.push(value);
+    } catch { /* an interleaved or cut line */ }
+  }
+  return events;
+}
+
+// Roots compare after normalizing separators, a trailing separator and, on win32, case (SD 5).
+export function sameRoot(left, right, { win32 = false } = {}) {
+  const normal = value => {
+    const text = String(value ?? '').replaceAll('\\', '/').replace(/\/+$/u, '');
+    return win32 ? text.toLowerCase() : text;
+  };
+  return Boolean(left) && Boolean(right) && normal(left) === normal(right);
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/companion/figure-state.js

@@ -0,0 +1,38 @@
+// Companion figure state (SD SDD-004): one mood and a reason descriptor per run-view entry, derived
+// only from the status-card fields the run view copied. Pure and host-neutral; hosts localize the
+// reason with the catalog's companion section and may overlay their own activity (turn in progress).
+import { COMPANION_MOODS } from '../interaction-catalog.js';
+import { RUN_MODES } from '../control-state/run-identity.js';
+
+export { COMPANION_MOODS };
+// The internal steps between an approved TP and QA, shown as building in structured runs; hosts that
+// mark the build phase use this list (CR finding CIR-04).
+export const BUILD_GATES = Object.freeze(['Brownfield Analysis', 'CD+Tests', 'CR']);
+export const STRUCTURED_MODES = Object.freeze(RUN_MODES.filter(mode => mode.startsWith('structured_')));
+// The ended lifecycles of run-operations.js (ENDED_LIFECYCLES), kept here so this module stays pure;
+// the companion tests assert both agree.
+export const ENDED_LIFECYCLES = Object.freeze(['superseded', 'abandoned']);
+// The pending approval as the run inventory reads it (run-inventory.js runAttention): a negated
+// mention ("No Approval: QA") is no pending approval.
+const pendingApproval = missing => String(missing ?? '').match(/(?<!\b(?:[Nn]o|[Nn]ot|[Ww]ithout) )\bApproval: (UR|PRD|SD|TP|QA|UAT|OR)\b/u)?.[1] ?? null;
+
+// { mood, reason: { key, gate?, decision?, reason? } }; null or no entry is the idle figure.
+export function deriveFigureState(entry) {
+  if (!entry) return { mood: 'bereit', reason: { key: 'idle' } };
+  if (entry.valid === false) return { mood: 'blockiert', reason: { key: 'unreadable', reason: entry.unreadable_reason ?? 'run_state_invalid' } };
+  if (entry.evaluation_error) return { mood: 'blockiert', reason: { key: 'unreadable', reason: entry.evaluation_error } };
+  // A completed run whose evaluation is blocked is not done: the block is shown like any other.
+  const blocked = entry.evaluated === true && (entry.status === 'blocked' || Boolean(entry.blocking_reason && entry.blocking_reason !== 'none'));
+  // A completed run without confirmed completion is still shown, but claims nothing: its own reason.
+  if (entry.lifecycle === 'completed' && !blocked) return entry.completion_confirmed === true
+    ? { mood: 'fertig', reason: { key: 'done' } } : { mood: 'bereit', reason: { key: 'completionUnconfirmed' } };
+  if (ENDED_LIFECYCLES.includes(entry.lifecycle)) return { mood: 'bereit', reason: { key: 'ended' } };
+  if (!entry.evaluated) return { mood: 'bereit', reason: { key: 'idle' } };
+  const gate = entry.current_gate;
+  if (blocked) return { mood: 'blockiert', reason: { key: 'blocked', gate, decision: entry.blocking_reason } };
+  const approval = pendingApproval(entry.missing_approval);
+  if (approval) return { mood: 'wartet', reason: { key: 'waitingApproval', gate: approval } };
+  if (entry.user_action_required === 'yes') return { mood: 'wartet', reason: { key: 'waitingDecision', gate } };
+  if (STRUCTURED_MODES.includes(entry.mode) && BUILD_GATES.includes(gate)) return { mood: 'baut', reason: { key: 'building', gate } };
+  return { mood: 'laeuft', reason: { key: 'working', gate } };
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/companion/journal.js

@@ -0,0 +1,186 @@
+// Companion event journal (SD SDD-006, SDD-008): the runtime appends one line per event of a final
+// AGDF MCP tool result to `companion/events.jsonl` below the plugin data root, bounded to 256 KiB with
+// one rotation file `events.1.jsonl`. It is a notification channel only, never a source of truth, and
+// nothing here writes under `.agdf/control`. Every failure is swallowed: the tool result never changes.
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { resolveTaskTarget } from '../task-target-resolution.js';
+import { artefactFileDigest } from '../control-state/run-seal-compute.js';
+import { containedRegularFile } from '../control-state/contained-file.js';
+import { atomicWrite, withOwnedFileLock } from '../owned-file-lock.js';
+import { commandGate, deriveEvent, eventKind, reviewFact } from './events.js';
+
+export const JOURNAL_DIRECTORY = 'companion';
+export const JOURNAL_FILE = 'events.jsonl';
+export const JOURNAL_ROTATED_FILE = 'events.1.jsonl';
+export const JOURNAL_LIMIT_BYTES = 256 * 1024;
+// The launcher hands its data root (CLAUDE_PLUGIN_DATA on Claude, --data on Codex) to the runtime
+// processes through this variable (SDD-006).
+export const COMPANION_DATA_ROOT_ENV = 'AGDF_COMPANION_DATA_ROOT';
+const SOURCE_TEXT_LIMIT = 1024 * 1024;
+const RESERVATIONS_FILE = 'approval-requests.json';
+const RESERVATIONS_LIFETIME_MS = 30 * 60_000;
+const RESERVATIONS_MAX_ENTRIES = 8192;
+const RESERVATIONS_MAX_BYTES = 1024 * 1024;
+const RESERVATIONS_LOCK_WAIT_MS = 50;
+const DIGEST = /^[a-f0-9]{64}$/u;
+
+export const journalPath = dataRoot => join(dataRoot, JOURNAL_DIRECTORY, JOURNAL_FILE);
+
+const isLink = path => { try { return lstatSync(path).isSymbolicLink(); } catch { return false; } };
+
+function readReservations(path) {
+  let stat;
+  try { stat = lstatSync(path); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  if (!stat.isFile() || stat.size > RESERVATIONS_MAX_BYTES) throw Error('invalid notification reservations');
+  const bytes = readFileSync(path);
+  if (bytes.length > RESERVATIONS_MAX_BYTES) throw Error('invalid notification reservations');
+  const stored = JSON.parse(bytes);
+  if (!stored || typeof stored !== 'object' || Array.isArray(stored)) throw Error('invalid notification reservations');
+  const entries = Object.entries(stored);
+  if (entries.length > RESERVATIONS_MAX_ENTRIES
+      || entries.some(([key, expires]) => !DIGEST.test(key) || !Number.isSafeInteger(expires) || expires < 0)) {
+    throw Error('invalid notification reservations');
+  }
+  return entries;
+}
+
+// Only the notification survives a serving-process restart. Neither this
+// reservation nor the journal line participates in delivery or approval.
+function reserveApprovalRequest(dataRoot, input, at) {
+  const identity = [input.target_id, input.run_id, input.expected_revision_id,
+    input.command.payload.presentation_id, input.operation_id];
+  if (!identity.every(value => typeof value === 'string' && value.length > 0)) return false;
+  const key = createHash('sha256').update(JSON.stringify(identity)).digest('hex');
+  const directory = join(dataRoot, JOURNAL_DIRECTORY);
+  if (isLink(dataRoot) || isLink(directory)) return false;
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, RESERVATIONS_FILE);
+  const deadline = performance.now() + RESERVATIONS_LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      return withOwnedFileLock(path, () => {
+        const live = new Map(readReservations(path).filter(([, expires]) => expires > at));
+        if (live.has(key) || live.size >= RESERVATIONS_MAX_ENTRIES) return false;
+        live.set(key, at + RESERVATIONS_LIFETIME_MS);
+        const bytes = JSON.stringify(Object.fromEntries(live));
+        if (Buffer.byteLength(bytes) > RESERVATIONS_MAX_BYTES) return false;
+        atomicWrite(path, bytes);
+        return true;
+      });
+    } catch (error) {
+      const remaining = deadline - performance.now();
+      if (error.lock_owner_status !== 'live' || remaining <= 0) return false;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(5, remaining));
+    }
+  }
+}
+
+// Appends one event line; rotates first when the line would cross the bound. Returns whether the line
+// was written. Concurrent servers may interleave whole lines or lose some at rotation (accepted).
+export function appendJournalEvent(dataRoot, event, { limit = JOURNAL_LIMIT_BYTES } = {}) {
+  try {
+    if (typeof dataRoot !== 'string' || !dataRoot || !event) return false;
+    const directory = join(dataRoot, JOURNAL_DIRECTORY);
+    if (isLink(dataRoot) || isLink(directory)) return false;
+    mkdirSync(directory, { recursive: true });
+    const line = `${JSON.stringify(event)}\n`;
+    const size = Buffer.byteLength(line, 'utf8');
+    if (size > limit) return false;
+    const file = join(directory, JOURNAL_FILE);
+    if (isLink(file)) return false;
+    let current = 0;
+    try { current = statSync(file).size; } catch { current = 0; }
+    if (current > 0 && current + size > limit) renameSync(file, join(directory, JOURNAL_ROTATED_FILE));
+    appendFileSync(file, line, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The governance root of a command input, resolved like the material store does; the input's own
+// target path when it does not resolve.
+export function commandRoot(input = {}) {
+  try {
+    const target = resolveTaskTarget({ workingDirectory: input.working_directory, targetSource: input.target_source, primaryTarget: input.primary_target });
+    if (target.resolution_state === 'resolved' && target.governance_target) return target.governance_target;
+  } catch { /* fall back to the input path */ }
+  return input.primary_target ?? input.working_directory ?? null;
+}
+
+// The event's root: the caller's target path when it names the same directory as the resolved root
+// through another spelling (junction, symlink, subst drive), so a host comparing with its own session
+// root still matches (SD SDD-005 "the MCP target path", CR finding A6); else the resolved root.
+// Review facts keep reading below the resolved root.
+export function eventRoot(input = {}, root = commandRoot(input)) {
+  const given = typeof input.primary_target === 'string' && isAbsolute(input.primary_target) ? resolve(input.primary_target) : null;
+  if (!given || !root || given === root) return root;
+  try { return realpathSync(given) === realpathSync(root) ? given : root; } catch { return root; }
+}
+
+// Review facts of a path source: the file read now, its canonical digest from the node digest owner
+// compared with the declared digest (match or mismatch); unreadable files are unavailable.
+function pathFact(root, slot, source) {
+  const current = root ? artefactFileDigest(root, source.path) : 'unresolved';
+  if (!/^sha256:/u.test(current)) return reviewFact({ slot, source: 'path', path: source.path, digest: source.digest, sourceMatch: 'unavailable' });
+  let text = null;
+  try {
+    const file = containedRegularFile(root, String(source.path).trim());
+    if (file.status === 'valid' && statSync(file.path).size <= SOURCE_TEXT_LIMIT) text = readFileSync(file.path, 'utf8');
+  } catch { text = null; }
+  return reviewFact({ slot, source: 'path', path: source.path, digest: source.digest, text, sourceMatch: current === source.digest ? 'match' : 'mismatch' });
+}
+
+// Review facts (SDD-008, decision P4): sealed staged material carries its preview, size and digest
+// with source_match not_determinable; a recording from a path carries the path, the recorded digest
+// and whether the file still matches it; a recording from staged material names its digest only.
+export function reviewFacts(toolName, input, result, { sealedFiles = () => null, root = commandRoot(input) } = {}) {
+  const kind = eventKind(toolName, input, result);
+  const command = input?.command ?? {};
+  if (kind === 'material_staged') {
+    const files = sealedFiles(command.payload?.transfer_id) ?? [];
+    return files.map(file => reviewFact({ slot: file.slot, source: 'staged', digest: file.digest, text: file.content, sourceMatch: 'not_determinable' }));
+  }
+  if (kind !== 'document_recorded') return null;
+  const payload = command.payload ?? {};
+  const source = payload.source ?? payload.material ?? null;
+  const slot = commandGate(command);
+  if (source?.path) return [pathFact(root, slot, source)];
+  if (source?.material_id) return [reviewFact({ slot, source: 'staged', digest: source.digest, sourceMatch: 'not_determinable' })];
+  return null;
+}
+
+// The runtime's observer of final tool results. Without a data root it does nothing.
+export function createCompanionJournal({ dataRoot = process.env[COMPANION_DATA_ROOT_ENV], sealedFiles = () => null,
+  now = () => new Date(), newId = randomUUID, limit = JOURNAL_LIMIT_BYTES } = {}) {
+  const enabled = typeof dataRoot === 'string' && dataRoot.length > 0;
+  return Object.freeze({
+    enabled,
+    path: enabled ? journalPath(dataRoot) : null,
+    // Whether `observe` writes an event for this result, without writing: a facade asks this for a
+    // result its generation produced, and so already journaled.
+    observes(toolName, input, result) {
+      if (!enabled) return false;
+      try { return Boolean(eventKind(toolName, input, result)); } catch { return false; }
+    },
+    observe(toolName, input, result) {
+      if (!enabled) return false;
+      try {
+        const kind = eventKind(toolName, input, result);
+        if (!kind) return false;
+        const root = commandRoot(input);
+        const review = reviewFacts(toolName, input, result, { sealedFiles, root });
+        const at = now();
+        const event = deriveEvent(toolName, input, result, { id: newId(), at: at.toISOString(), root: eventRoot(input, root), review });
+        if (!event) return false;
+        if (kind === 'approval_requested' && !reserveApprovalRequest(dataRoot, input, at.getTime())) return false;
+        return appendJournalEvent(dataRoot, event, { limit });
+      } catch {
+        return false;
+      }
+    },
+  });
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/companion/run-view.js

@@ -0,0 +1,227 @@
+// Companion run view (SD SDD-001, SDD-002): a read-only projection of the unchanged gate-check
+// report of each run, beside the run inventory of one project root. It never re-derives a gate
+// rule: status fields are copied from the status card verbatim, so every consumer of the run
+// view sees exactly what the status card shows. Nothing here writes or authorizes.
+import { existsSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { readFileSync, statSync } from '../control-read/fs.js';
+import { captureControlScope } from '../control-read/snapshot.js';
+import { containedRegularFile, hasSymlinkComponent, isSafeControlRelativePath } from '../control-state/contained-file.js';
+import { parseControlState } from '../control-state/run-state-parser.js';
+import { runIdentity } from '../control-state/run-title.js';
+import { localizedDecisionFields } from '../control-evaluation/decision-content-readiness.js';
+import { evaluateGateCheck } from '../control-evaluation/gate-check.js';
+import { readRunInventory } from '../control-state/run-inventory-reader.js';
+import { runFolderEntries } from '../control-state/run-state-reader.js';
+import { readArtefactBindings } from '../control-state/artefact-bindings.js';
+import { readEvidenceBindings } from '../control-state/evidence-bindings.js';
+import { runRelativePath } from '../control-state/run-identity.js';
+import { artefactFileDigest } from '../control-state/run-seal-compute.js';
+import { boundedCode } from '../control-inspect/run-classification.js';
+import { localizeBlockingCondition, localizeOperationalValue } from '../interaction-presentation.js';
+import { interactionLocales, resolveArtifactPresentationLanguages } from '../resources/context.js';
+import { deriveFigureState } from './figure-state.js';
+
+export const RUN_VIEW_SCHEMA = 'run-view/1';
+export const DIAGNOSIS_REASONS = Object.freeze(['run_version_unsupported', 'run_state_invalid', 'too_large', 'missing']);
+// The reader's findings for a run folder without a readable run state: the path finding of
+// run-state-reader.js (invalidRun) and the inventory's finding for a run without text (run-inventory.js).
+const MISSING_CODES = new Set(['AGDF_RUN_PATH_INVALID', 'AGDF_RUN_STATE_UNAVAILABLE']);
+// The classifications run-state-resolver.js treats as unsupported (AGDF_RUN_VERSION_UNSUPPORTED).
+const UNSUPPORTED_CLASSIFICATIONS = new Set(['unsupported_version', 'unsupported_layout']);
+
+// Per-run reason of an unreadable run (SD SDD-003) from the reader findings: unsupported by their
+// classification, as run-state-resolver.js and the cockpit decide it (CR finding CIR-03), missing
+// when only the missing-state findings are present, otherwise invalid. Core reports no size bound
+// of its own, so an oversized run state is reported with the reason Core gives it; too_large stays
+// reserved for such a bound (contradiction C1).
+export function diagnosisReason(findings) {
+  if (findings.some(finding => UNSUPPORTED_CLASSIFICATIONS.has(finding.classification))) return 'run_version_unsupported';
+  if (findings.length && findings.every(finding => MISSING_CODES.has(finding.code))) return 'missing';
+  return 'run_state_invalid';
+}
+
+export function projectDiagnosis(entries) {
+  const unreadable = entries.filter(entry => !entry.valid).map(entry => ({ run_id: entry.run_id, reason: entry.unreadable_reason ?? 'run_state_invalid', codes: entry.findings }));
+  const by_reason = Object.fromEntries(DIAGNOSIS_REASONS.map(reason => [reason, unreadable.filter(row => row.reason === reason).length]));
+  return { unreadable, counts: { unreadable: unreadable.length, readable: entries.length - unreadable.length, by_reason } };
+}
+
+const NAMING_TEXT_LIMIT = 500;
+const UR_READ_LIMIT = 131072;
+const bounded = value => (typeof value === 'string' && value.length > NAMING_TEXT_LIMIT ? `${value.slice(0, NAMING_TEXT_LIMIT - 1)}…` : value);
+
+// How a run names itself to a person, read inside the run's own snapshot: the stable title of the
+// shared Run title rule (registered UR heading, then the authored Objective; a bare Run ID is no
+// title) and the goal in the display language. Where display and artefact language differ, the goal
+// is the one the UR's localized approval summary states. An unreadable UR leaves both to the Run document.
+export function readRunNaming(root, runId, language = 'en') {
+  let content;
+  try { content = readFileSync(join(root, runRelativePath(runId, '', 'RUN_STATE.md')), 'utf8'); } catch { return null; }
+  let urHeading = '', localizedGoal = null;
+  try {
+    const path = String(parseControlState(content).artefacts.get('UR')?.path ?? '').replace(/^`|`$/gu, '').trim();
+    if (isSafeControlRelativePath(path) && path.startsWith('.agdf/control/') && !hasSymlinkComponent(root, path)) {
+      const file = containedRegularFile(root, path);
+      if (file.status === 'valid' && statSync(file.path).size <= UR_READ_LIMIT) {
+        const text = readFileSync(file.path, 'utf8');
+        urHeading = (text.match(/^#\s+(.+)$/mu)?.[1] ?? '').replace(/^UR:\s*/iu, '').trim();
+        const sourceLanguage = resolveArtifactPresentationLanguages(root, language).artifact_language;
+        localizedGoal = localizedDecisionFields('UR', text, { locale: String(language).split('-')[0], sourceLanguage, path }).fields.goal ?? null;
+      }
+    }
+  } catch (error) { if (error?.code === 'source_changed') throw error; }
+  const identity = runIdentity({ runId, runContent: content, urHeading });
+  return { run_title: identity.title_source === 'run_id' ? null : bounded(identity.title),
+    run_title_source: identity.title_source, goal: bounded(localizedGoal ?? identity.objective) };
+}
+
+// One run entry: inventory facts plus, when evaluated, the status card fields of its report.
+// `naming` is readRunNaming's result for an evaluated run; without it the inventory names the run.
+export function projectRunEntry(inventoryEntry, report, { registry = interactionLocales, language = 'en', naming = null } = {}) {
+  const authored = inventoryEntry.title_source === 'objective' ? inventoryEntry.title ?? null : null;
+  const base = {
+    run_id: inventoryEntry.run_id,
+    title: inventoryEntry.title ?? null,
+    // The stable human title, the same at every gate; null while only the Run ID could name the run.
+    run_title: naming ? naming.run_title : authored,
+    run_title_source: naming?.run_title_source ?? (authored ? 'objective' : 'run_id'),
+    // The goal in the display language where the UR states one, otherwise the authored objective.
+    goal: naming ? naming.goal : inventoryEntry.objective ?? null,
+    // The authored objective only, from the shared Run title rule; a template objective or a
+    // bare Run ID is no goal (CR finding C2).
+    objective: inventoryEntry.objective ?? null,
+    lifecycle: inventoryEntry.lifecycle ?? null,
+    valid: inventoryEntry.valid !== false,
+    revision: inventoryEntry.revision ?? null,
+    revision_id: inventoryEntry.revision_id ?? null,
+    last_activity: inventoryEntry.last_activity?.at ?? null,
+    findings: (inventoryEntry.findings ?? []).map(finding => finding.code),
+  };
+  if (!base.valid) base.unreadable_reason = diagnosisReason(inventoryEntry.findings ?? []);
+  // A run whose evaluation threw is reported with the bounded reason, never as an idle run (CR A7).
+  if (report?.evaluation_error) return withFigure({ ...base, evaluated: false, evaluation_error: report.evaluation_error });
+  if (!report?.status_card) return withFigure({ ...base, evaluated: false });
+  const card = report.status_card;
+  return withFigure({
+    ...base,
+    title: card.humanPresentation?.runTitle ?? base.title,
+    evaluated: true,
+    completion_confirmed: base.lifecycle === 'completed' && report.completion?.fulfilled === true,
+    status: card.status,
+    current_gate: card.current_gate,
+    path: card.breadcrumb.map(({ gate, status }) => ({ gate, status })),
+    missing_approval: card.missing_approval,
+    blocking_reason: card.blocking_condition,
+    blocking_text: localizeBlockingCondition(card.blocking_condition, { registry, requestedLocale: language }) ?? card.blocking_condition,
+    next_step: card.next_step,
+    next_step_text: localizeOperationalValue(card.next_step, { registry, requestedLocale: language }) ?? card.next_step,
+    user_action_required: card.user_action_required,
+    doctor_status: report.doctor_status,
+    mode: card.mode_slice_decision ?? card.mode ?? null,
+  });
+}
+const withFigure = entry => ({ ...entry, figure: deriveFigureState(entry) });
+
+// Pure assembly of the versioned view from already evaluated parts.
+export function projectRunView({ root, language, store, entries }) {
+  return {
+    schema_version: RUN_VIEW_SCHEMA,
+    root,
+    language,
+    store,
+    diagnosis: projectDiagnosis(entries.filter(entry => entry.listed !== false)),
+    runs: entries,
+    authorizes: false,
+  };
+}
+
+// Drift warnings (SD SDD-008, PRD AC-008): documents the run state binds with a recorded digest
+// (effective artefact binding destination, latest evidence report per path) whose file now has another
+// canonical digest from the node digest owner. Declared input files of a recording are not kept in
+// the run state, so only bound documents are compared (contradiction C5 of this run). An unreadable
+// run state yields no warning; the status card reports it.
+export function readRunDrift(root, runId) {
+  let content;
+  try { content = readFileSync(join(root, runRelativePath(runId, '', 'RUN_STATE.md')), 'utf8'); } catch { return []; }
+  const declared = new Map();
+  const artefacts = readArtefactBindings(content);
+  // A binding a recorded source revision invalidated is superseded for Core, so its document being
+  // re-drafted is no drift (CR finding A5).
+  for (const receipt of artefacts.valid ? artefacts.active ?? [] : []) {
+    declared.set(receipt.destination.path, { document: receipt.destination.type, digest: receipt.destination.digest });
+  }
+  const evidence = readEvidenceBindings(content);
+  for (const row of evidence.valid ? evidence.bindings : []) {
+    declared.set(row.report.path, { document: row.report.path.split('/').at(-1).replace(/\.md$/u, ''), digest: row.report.digest });
+  }
+  const drift = [];
+  for (const [path, { document, digest }] of declared) {
+    const current = artefactFileDigest(root, path);
+    if (current === digest) continue;
+    drift.push({ document, path, recorded_digest: digest, current_digest: /^sha256:/u.test(current) ? current : null });
+  }
+  return drift;
+}
+
+// Active runs are evaluated; terminal and unreadable runs are summarized unless requested by id, so
+// neither a large history nor many unreadable runs cost one evaluation per run. An unreadable run's
+// reason and figure come from the inventory findings.
+const needsEvaluation = (entry, requested) => requested.has(entry.run_id) || (entry.valid && entry.lifecycle === 'active');
+
+// A write that lands during a capture invalidates it (source_changed); the read is repeated a bounded
+// number of times before the change is reported (CR delta review RV-1).
+export const CAPTURE_ATTEMPTS = 3;
+export function captured(readRoot, project, capture = captureControlScope) {
+  for (let attempt = 1; ; attempt += 1) {
+    try { return capture(readRoot, view => project(view.root)).data; }
+    catch (error) { if (error?.code !== 'source_changed' || attempt >= CAPTURE_ATTEMPTS) throw error; }
+  }
+}
+
+// Reads inside bounded, revalidated control snapshots (TP T-002, SD section 4: captureControlScope,
+// CR finding CIR-01): the inventory in one snapshot and each evaluated run with its drift in its own,
+// so a read-boundary failure of one run (a linked file, a document outside the control folder, a read
+// limit) marks only that run and the readable runs stay listed (SDD-003, RV-2). The root is resolved
+// first, as MCP canonicalizes its target, so a junction or symlinked project root reads like its
+// target; the view keeps the caller's spelling (RV-3). A missing root has no control folder (RV-5).
+export function readRunView(root, { language = 'en', runIds = [] } = {}) {
+  const empty = store => projectRunView({ root, language, store, entries: [] });
+  if (!existsSync(root)) return empty({ status: 'no_control', reason: null });
+  let readRoot;
+  try { readRoot = realpathSync(root); } catch (error) { return empty({ status: 'unavailable', reason: boundedCode(error) }); }
+  const requested = new Set(runIds);
+  const evaluate = runId => {
+    try {
+      return captured(readRoot, base => {
+        const report = evaluateGateCheck(base, { runId, ignoreRunIdEnv: true, presentationLanguage: language });
+        return { report, drift: report?.status_card ? readRunDrift(base, runId) : null, naming: readRunNaming(base, runId, language) };
+      });
+    } catch (error) { return { report: { evaluation_error: boundedCode(error) }, drift: null, naming: null }; }
+  };
+  const entryOf = (inventoryEntry, evaluated) => {
+    const entry = projectRunEntry(inventoryEntry, evaluated?.report ?? null, { language, naming: evaluated?.naming ?? null });
+    return entry.evaluated && entry.valid !== false && evaluated.drift ? { ...entry, drift: evaluated.drift } : entry;
+  };
+  let inventory = null, store;
+  try {
+    inventory = captured(readRoot, base => readRunInventory(base, { language, observe: false }));
+    store = { status: inventory.state === 'absent' ? 'no_control' : 'ok', reason: null };
+  } catch (error) {
+    store = { status: 'unavailable', reason: boundedCode(error) };
+    // An unsupported layout lists no run, but its run folders can be counted, so a consumer names count
+    // and reason instead of "no open runs" (PRD AC-002, TP T-004). A failing count leaves the field out.
+    if (store.reason === 'control_layout_unsupported') {
+      try { store.run_folders = captured(readRoot, base => runFolderEntries(base).length); } catch { /* count unknown */ }
+    }
+  }
+  const listed = inventory?.runs ?? [];
+  const entries = listed.map(entry => entryOf(entry, needsEvaluation(entry, requested) ? evaluate(entry.run_id) : null));
+  for (const runId of requested) {
+    if (listed.some(entry => entry.run_id === runId)) continue;
+    // Requested but not listed by the inventory (for example behind an unsupported layout):
+    // evaluated for its card, never counted in the diagnosis of listed runs.
+    entries.push({ ...entryOf({ run_id: runId, findings: [] }, evaluate(runId)), valid: null, listed: false });
+  }
+  return projectRunView({ root, language, store, entries });
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-evaluation/acceptance-criteria.js

@@ -4,6 +4,8 @@ const CRITERION_ID = /^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*$/u;
 export const ACCEPTANCE_CRITERIA_FORMAT = Object.freeze({
   section: "Acceptance Criteria", declaration: "criterion_id: <stable id>",
   fields: "semicolon-separated inline fields or following bullet key: value lines",
+  description_fields: Object.freeze(["observable_success", "visible_feedback", "expected_effective_state"]),
+  description_rule: "For same-language approval rendering, provide at least one nonempty description field separately. Never concatenate field names or infer their meaning from combined keys.",
   id_pattern: CRITERION_ID.source,
   examples: Object.freeze([
     "## Acceptance Criteria\n- criterion_id: AC-001; observable_success: Saved choice remains selected",