create-agdf 0.14.5 → 0.20.0

package/runtime/core/lib/control-inspect/artifact-readiness.js

@@ -0,0 +1,122 @@
+import { readFileSync } from '../control-read/fs.js';
+import { join } from 'node:path';
+import { captureControlScope } from '../control-read/snapshot.js';
+import { readRunState } from '../control-evaluation/run-state.js';
+import { evaluateGateCheck } from '../control-evaluation/gate-check.js';
+import { evaluatePrdReadiness } from '../control-evaluation/prd-readiness.js';
+import { evaluateUrReadiness } from '../control-evaluation/ur-readiness.js';
+import { evaluateSdReadiness } from '../control-evaluation/sd-readiness.js';
+import { evaluateSdTraceability, evaluateTpTraceability } from '../control-evaluation/traceability-readiness.js';
+import { resolveArtifactPresentationLanguages } from '../resources/context.js';
+import { evaluateApprovalSummaryReadiness } from '../control-state/run-presentation-render.js';
+import { artefactFileDigest, runSealState } from '../control-state/run-seal.js';
+import { containedRegularFile, hasSymlinkComponent } from '../control-state/contained-file.js';
+import { extractField } from '../control-evaluation/verified-change.js';
+
+export const ARTIFACT_READINESS_GATES = Object.freeze(['UR', 'PRD', 'SD', 'TP']);
+
+// Describes the original author's findings; it does not validate or change gate policy.
+export function describeArtifactReadiness(result) {
+  const names = new Set(['approval_summary', 'prd_readiness', 'ur_readiness', 'sd_decisions', 'sd_traceability', 'tp_traceability',
+    'approval_summary_locale_missing', 'approval_summary_locale_duplicate', 'approval_summary_source_language_mismatch',
+    'approval_summary_truncated_or_overlong', 'approval_summary_field_overlong', 'approval_summary_criteria_missing',
+    'approval_summary_source_criteria_duplicate', 'approval_summary_source_criteria_invalid', 'approval_summary_criteria_duplicate', 'approval_summary_criteria_unknown',
+    'approval_summary_criteria_incomplete', 'approval_summary_user_goal_missing', 'approval_summary_scope_missing',
+    'approval_summary_decisions_missing', 'approval_summary_criterion_content_missing', 'approval_summary_content_missing']);
+  let findings = result.diagnostics.filter(row => names.has(row.code));
+  const readinessOwner = { AGDF_UR_REQUIREMENTS_INCOMPLETE: 'ur', AGDF_PRD_DECISIONS_OPEN: 'prd',
+    AGDF_SD_DECISIONS_OPEN: 'sd', AGDF_SD_TRACEABILITY_INCOMPLETE: 'traceability', AGDF_TP_TRACEABILITY_INCOMPLETE: 'traceability' };
+  const key = readinessOwner[result.blocking_reason];
+  const details = key && result.current_gate === result.gate && result.readiness_details?.[key];
+  const items = details && (details.open_items ?? details.open_decisions);
+  if (result.diagnostics.length === 1 && result.diagnostics[0].code === 'artifact_gate_not_ready'
+      && Array.isArray(items) && items.length && items.every(item => typeof item === 'string' && item.trim())) {
+    findings = items.map(message => ({ code: result.blocking_reason, message }));
+  }
+  const corrections = findings.length > 0 && (result.diagnostics.every(row => names.has(row.code))
+    || result.diagnostics.length === 1 && result.diagnostics[0].code === 'artifact_gate_not_ready' && !!key && !!details);
+  return { state: result.ready ? 'passed' : corrections ? 'corrections_required' : 'unavailable',
+    reason: result.diagnostics[0]?.code ?? null, recovery: result.ready || corrections ? 'authoring' : 'reload',
+    findings: corrections ? findings : [] };
+}
+
+// Runs only inside the caller's bounded captured view. Both consumers use these same validators.
+export function projectArtifactReadiness(root, { runId, gate, expectedRevisionId, presentationLanguage }) {
+  const path = `.agdf/control/artefacts/${runId}/${gate}.md`;
+  const targetRoot = root;
+  const diagnostics = [], checks = [];
+  let state, revision = null, digest = null;
+  const report = () => ({
+    run_id: runId, gate, expected_revision_id: expectedRevisionId, revision_id: revision,
+    artifact_path: path, artifact_digest: digest, ready: diagnostics.length === 0,
+    readiness_scope: 'authoring_checks', authorizes: false, semantic_review_required: true,
+    registration_required: true, presentation_required: true, checks, diagnostics,
+    next_action: diagnostics.length ? 'Correct the reported issue through its existing owner, then recheck this run and revision.'
+      : 'Review semantic derivation and record through the existing canonical writer; then obtain a fresh presentation and deliberate approval.',
+  });
+  const fail = (code, message) => { diagnostics.push({ code, message }); return report(); };
+  if (!ARTIFACT_READINESS_GATES.includes(gate)) return fail('artifact_gate_invalid', 'This gate has no supported draft artifact.');
+  state = readRunState(targetRoot, { runId, ignoreRunIdEnv: true });
+  if (!state.content || state.resolution_error || state.identity_findings.length
+      || state.path !== join('.agdf', 'control', 'runs', runId, 'RUN_STATE.md')
+      || extractField(state.content, 'run_id') !== runId)
+    return fail('artifact_run_invalid', 'The explicitly selected canonical run is unavailable or invalid.');
+  revision = extractField(state.content, 'revision_id');
+  if (revision !== expectedRevisionId) return fail('artifact_revision_stale', 'Use a fresh selected-run revision; this check cannot adopt a newer revision.');
+  if (extractField(state.content, 'lifecycle') !== 'active') return fail('artifact_run_inactive', 'Only an active selected run can be checked.');
+  if (runSealState(targetRoot, state.content).status !== 'valid') return fail('artifact_run_integrity', 'Resolve the existing run/source integrity issue before draft checks.');
+  if (state.approvals.get(gate)?.status === 'approved') return fail('artifact_already_approved', 'An approved source is outside draft authoring checks.');
+  const evaluated = evaluateGateCheck(targetRoot, { runId, ignoreRunIdEnv: true, presentationLanguage });
+  if (evaluated.status !== 'open' || evaluated.current_gate !== gate) {
+    const blocked = fail('artifact_gate_not_ready', 'Resolve the current canonical gate or blocker before checking this draft.');
+    return { ...blocked, current_gate: evaluated.current_gate, blocking_reason: evaluated.blocking_reason,
+      readiness_details: {
+        ur: evaluated.ur_readiness ?? null, prd: evaluated.prd_readiness ?? null,
+        sd: evaluated.sd_readiness ?? null, traceability: evaluated.traceability_readiness ?? null,
+      },
+      next_action: evaluated.next_allowed_action };
+  }
+  if (evaluated.presentation_decision?.decided) return fail('presentation_version_decided', 'Revise this material through its existing owner before another decision.');
+  const registered = state.artefacts.get(gate)?.path;
+  if (registered && registered !== path) return fail('artifact_path_conflict', 'The existing registered source differs from the canonical draft path.');
+  const file = containedRegularFile(targetRoot, path);
+  if (hasSymlinkComponent(targetRoot, path) || file.status !== 'valid') return fail('artifact_source_unavailable', 'The contained canonical draft is missing or unsafe.');
+  const content = readFileSync(file.path, 'utf8');
+  digest = artefactFileDigest(targetRoot, path);
+  const languages = resolveArtifactPresentationLanguages(targetRoot, presentationLanguage);
+  const summary = evaluateApprovalSummaryReadiness(gate, content, languages);
+  checks.push({ name: 'approval_summary', ...summary });
+  if (!summary.ready) diagnostics.push({ code: summary.reason, message: `Prepare ${summary.required_heading} using the existing summary rules.` });
+  // Supply only an in-memory draft pointer; no Run, approval or binding is written.
+  const candidate = { ...state, artefacts: new Map(state.artefacts) };
+  candidate.artefacts.set(gate, { path, status: 'draft' });
+  const add = (name, result) => {
+    checks.push({ name, ...result });
+    if (!result.ready && !(result.open_decisions ?? result.open_items ?? []).length) diagnostics.push({ code: name, message: 'The existing content validator reports an unready draft.' });
+    for (const message of result.open_decisions ?? result.open_items ?? []) diagnostics.push({ code: name, message });
+  };
+  if (gate === 'UR') add('ur_readiness', evaluateUrReadiness(targetRoot, candidate, { presentationLanguage }));
+  if (gate === 'PRD') add('prd_readiness', evaluatePrdReadiness(targetRoot, candidate, { presentationLanguage }));
+  if (gate === 'SD') {
+    add('sd_decisions', evaluateSdReadiness(targetRoot, candidate));
+    add('sd_traceability', evaluateSdTraceability(targetRoot, candidate));
+  }
+  if (gate === 'TP') add('tp_traceability', evaluateTpTraceability(targetRoot, candidate));
+  return report();
+}
+
+// Standalone authoring preflight retains its original captured/read-only report contract.
+export function inspectArtifactReadiness(root, input) {
+  const { runId, gate, expectedRevisionId } = input;
+  const path = `.agdf/control/artefacts/${runId}/${gate}.md`;
+  try {
+    return captureControlScope(root, view => projectArtifactReadiness(view.root, input)).data;
+  } catch (error) {
+    if (!['resource_denied', 'source_changed', 'resource_limit', 'timeout', 'read_failed'].includes(error.code)) throw error;
+    return { run_id: runId, gate, expected_revision_id: expectedRevisionId, revision_id: null,
+      artifact_path: path, artifact_digest: null, ready: false, readiness_scope: 'authoring_checks',
+      authorizes: false, semantic_review_required: true, registration_required: true, presentation_required: true,
+      checks: [], diagnostics: [{ code: `artifact_read_${error.code}`, message: 'A safe stable draft/source snapshot could not be captured.' }],
+      next_action: 'Resolve the source boundary or obtain a fresh stable source snapshot, then repeat the bound read-only check.' };
+  }
+}

package/runtime/core/lib/control-inspect/cockpit-backlog.js

@@ -0,0 +1,135 @@
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from '../control-read/fs.js';
+import { markdownSection, parseBacklogSection, tableRows, cleanStatusCell, markdownLink, resolvedBacklogLinkTarget } from '../control-evaluation/shared.js';
+import { isSafeControlRelativePath } from '../control-state/contained-file.js';
+import { READ_LIMITS, fail } from '../control-read/snapshot.js';
+import { COCKPIT_BACKLOG_SECTIONS } from './cockpit-list.js';
+import { decodeBacklogMarker, savedBacklogSummary } from '../control-state/backlog-summary.js';
+
+const SOURCE = '.agdf/control/MASTER_BACKLOG.md';
+const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const headings = COCKPIT_BACKLOG_SECTIONS;
+const completedHeader = ['key', 'work item', 'status', 'record', 'outcome'];
+const canonicalCompletedHeader = ['key', 'work item', 'final status', 'historical record', 'outcome'];
+
+// A stored pointer projection. It never resolves Runs, evaluates gates or follows links.
+export function projectCockpitBacklog(root) {
+  const path = join(root, SOURCE);
+  if (!existsSync(path)) return { state: 'missing', code: 'backlog_missing', data: null };
+  const bytes = readFileSync(path);
+  if (bytes.length > READ_LIMITS.preview) fail('resource_limit');
+  let source;
+  try { source = decoder.decode(bytes); if (source.includes('\0')) throw Error(); }
+  catch { return { state: 'unsupported', code: 'backlog_unsupported', data: null }; }
+  const entries = [], diagnostics = [], counts = {};
+  const markers = source.split('\n').map(decodeBacklogMarker).filter(Boolean);
+  const diagnostic = (code, section, key = null) => diagnostics.push({ code, path: SOURCE, section, key });
+  for (const section of headings) {
+    const content = markdownSection(source, section), rows = tableRows(content);
+    if (!new RegExp(`^## ${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(source)) {
+      diagnostic('backlog_section_missing', section); counts[section] = 0; continue;
+    }
+    if (!rows.length) { diagnostic('backlog_layout_missing', section); counts[section] = 0; continue; }
+    const completed = section === headings[2];
+    const normalized = rows[0].map(cell => cell.toLowerCase().trim());
+    let pointers = [];
+    if (completed) {
+      if (![completedHeader.join('|'), canonicalCompletedHeader.join('|')].includes(normalized.join('|'))) {
+        diagnostic('backlog_layout_unsupported', section); counts[section] = 0; continue;
+      }
+    } else {
+      const findings = [];
+      pointers = parseBacklogSection(content, findings, SOURCE);
+      diagnostics.push(...findings.map(row => ({ ...row, section })));
+      if (findings.some(row => row.code === 'AGDF_BACKLOG_LAYOUT_UNKNOWN')) { counts[section] = 0; continue; }
+    }
+    const width = rows[0].length;
+    let pointerIndex = 0;
+    for (const cells of rows.slice(1).filter(row => row.some(Boolean))) {
+      const pointer = completed ? null : pointers[pointerIndex++];
+      const compact = width === 7;
+      const key = cleanStatusCell(cells[completed ? 0 : 1] ?? '');
+      const malformed = cells.length !== width || !key || !(cells[completed ? 1 : 2] ?? '').trim();
+      if (malformed) diagnostic('backlog_row_malformed', section, key);
+      const saved_summary = savedBacklogSummary(root, section, cells, markers);
+      if (saved_summary.code) diagnostic(saved_summary.code, section, key);
+      entries.push({ section, key, original_key: cells[completed ? 0 : 1] ?? '',
+        title: cells[completed ? 1 : 2] ?? '', stored_status: cells[completed ? 2 : 3] ?? '',
+        scope: pointer?.scope ?? '', priority: completed ? null : cells[0] ?? '',
+        stored_next_step: completed ? cells[4] ?? '' : cells[compact ? 6 : 12] ?? '',
+        source_links: completed ? cells[3] ?? '' : compact ? cells[4] ?? '' : cells.slice(4, 11).join(' · '),
+        current_spec: completed ? null : cells[compact ? 5 : 11] ?? '',
+        normalized_pointer: pointer, saved_summary,
+        selectable: !malformed && /^[A-Za-z0-9_-]{1,128}$/.test(key) });
+    }
+    counts[section] = entries.filter(row => row.section === section).length;
+  }
+  const seen = new Map();
+  for (const entry of entries) {
+    if (seen.has(entry.key)) {
+      diagnostic('backlog_key_duplicate', entry.section, entry.key);
+      entry.selectable = false; seen.get(entry.key).selectable = false;
+    } else seen.set(entry.key, entry);
+  }
+  return { state: diagnostics.length ? 'partial' : entries.length ? 'available' : 'empty',
+    code: diagnostics.length ? 'backlog_partial' : null,
+    data: { kind: 'backlog', entries, diagnostics, source_path: SOURCE,
+      content_digest: createHash('sha256').update(bytes).digest('hex'), counts } };
+}
+
+export function backlogUrSource(row) {
+  const paths = new Set();
+  for (const match of `${row.source_links} · ${row.current_spec ?? ''}`.matchAll(/\[UR\]\([^)]+\)/gi)) {
+    const link = markdownLink(match[0]);
+    const path = link && resolvedBacklogLinkTarget(link.target);
+    if (!path || /[%#?\0]/.test(link.target) || !isSafeControlRelativePath(path)
+      || !path.startsWith('.agdf/control/artefacts/') || !/\.md$/i.test(path)) return { path: null, code: 'resource_denied' };
+    paths.add(path);
+  }
+  return paths.size === 1 ? { path: [...paths][0], code: null }
+    : { path: null, code: paths.size ? 'ur_link_ambiguous' : 'ur_link_missing' };
+}
+
+// Passive Markdown heading extraction for list presentation only. No evaluator changes.
+export function backlogUrHeading(content) {
+  let fence = null, comment = false, front = false, previous = '';
+  const lines = content.replace(/^\uFEFF/, '').split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    if (i === 0 && line.trim() === '---') { front = true; continue; }
+    if (front) { if (/^(---|\.\.\.)\s*$/.test(line)) front = false; continue; }
+    if (comment) { const end = line.indexOf('-->'); if (end < 0) continue; line = line.slice(end + 3); comment = false; }
+    const block = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (fence) { if (new RegExp(`^ {0,3}${fence[0]}{${fence.length},}\\s*$`).test(line)) fence = null; continue; }
+    if (block) { fence = block[1]; previous = ''; continue; }
+    while (line.includes('<!--')) {
+      const start = line.indexOf('<!--'), end = line.indexOf('-->', start + 4);
+      if (end < 0) { line = line.slice(0, start); comment = true; previous = ''; break; }
+      line = line.slice(0, start) + line.slice(end + 3);
+    }
+    const atx = line.match(/^ {0,3}#(?:[ \t]+(.*)|$)/);
+    if (atx) return (atx[1] ?? '').replace(/[ \t]+#+[ \t]*$/, '').trim();
+    if (previous && /^ {0,3}=+\s*$/.test(line)) return previous;
+    const paragraph = line.trim() && !/^(?:\s{4}|\t)|^ {0,3}(?:[#>|]|[-+*]\s|\d+[.)]\s|[-*_]{3,}\s*$)/.test(line);
+    previous = paragraph ? (previous ? previous + '\n' : '') + line.trim() : '';
+  }
+  return '';
+}
+
+export function projectBacklogUrTitle(root, view, row, backlogDigest) {
+  const source = backlogUrSource(row);
+  const observation = { state: 'unavailable', code: source.code, path: source.path, heading: null, title: null,
+    content_digest: null, observed_as_of: view.observed_as_of, backlog_digest: backlogDigest };
+  if (!source.path) return observation;
+  const read = view.readOptionalFileSync(join(root, source.path), READ_LIMITS.preview);
+  if (read.code) return { ...observation, code: read.code };
+  let content;
+  try { content = decoder.decode(read.bytes); if (content.includes('\0')) throw Error(); }
+  catch { return { ...observation, code: 'document_unsupported' }; }
+  const heading = backlogUrHeading(content), title = heading.replace(/^UR:\s*/i, '').trim();
+  if (!title) return { ...observation, code: 'ur_heading_missing' };
+  if ([...heading].length > 512 || Buffer.byteLength(heading, 'utf8') > 2048) return { ...observation, code: 'resource_limit' };
+  return { ...observation, state: 'available', code: null, heading, title,
+    content_digest: createHash('sha256').update(read.bytes).digest('hex') };
+}

package/runtime/core/lib/control-inspect/cockpit-context.js

@@ -0,0 +1,97 @@
+import { join } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { fail, READ_LIMITS } from '../control-read/snapshot.js';
+
+export const CONTEXT_LIMIT = 64 * 1024;
+const GRAPH = '.agdf/control/CONTEXT_GRAPH.md';
+const nodeId = /^CG-[A-Za-z0-9_-]+$/;
+const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const digest = value => createHash('sha256').update(value).digest('hex');
+
+// Source offsets preserve original text, including line endings. Fenced examples
+// never register headings; only exact level-three IDs own a node.
+function nodes(content) {
+  const headings = []; let offset = 0, fence = null;
+  for (const line of content.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})(.*)/);
+    if (marker) {
+      if (!fence) fence = { char: marker[1][0], length: marker[1].length };
+      else if (marker[1][0] === fence.char && marker[1].length >= fence.length && !marker[2].trim()) fence = null;
+    } else if (!fence) {
+      const heading = line.match(/^ {0,3}(#{1,3})\s+(.+?)\s*(?:\r?\n)?$/);
+      if (heading) headings.push({ level: heading[1].length, id: heading[2], offset });
+    }
+    offset += line.length;
+  }
+  const result = new Map();
+  for (let i = 0; i < headings.length; i++) {
+    const heading = headings[i];
+    if (heading.level !== 3 || !nodeId.test(heading.id)) continue;
+    const text = content.slice(heading.offset, headings[i + 1]?.offset ?? content.length);
+    const entries = result.get(heading.id) ?? []; entries.push(text); result.set(heading.id, entries);
+  }
+  return result;
+}
+
+export function projectCockpitContext(view, root, runId, rawRefs) {
+  const refs = String(rawRefs ?? '').trim();
+  if (!refs || refs === 'none') return { run_id: runId, references: [] };
+  const origins = refs.split(';').map(value => value.trim());
+  if (origins.length > 64) fail('resource_limit');
+  let graphBytes = null, graphDigest = null, graphNodes = null, graphFailure = null;
+  const load = () => {
+    if (graphNodes || graphFailure) return;
+    try {
+      if (!view.existsSync(join(root, GRAPH))) { graphFailure = ['missing', 'graph_missing']; return; }
+      graphBytes = view.readFileSync(join(root, GRAPH)); graphDigest = digest(graphBytes);
+      const text = decoder.decode(graphBytes);
+      if (text.includes('\0')) throw Error('invalid_utf8');
+      graphNodes = nodes(text);
+    } catch (error) { graphFailure = error.code === 'resource_denied' ? ['blocked', 'resource_denied'] : ['unsupported', 'graph_unsupported']; }
+  };
+  const resolveReference = origin => {
+    const ref = /^`[^`]*`$/.test(origin) ? origin.slice(1, -1) : origin;
+    const id = nodeId.test(ref) ? ref : ref.startsWith(`${GRAPH}#`) && nodeId.test(ref.slice(GRAPH.length + 1)) ? ref.slice(GRAPH.length + 1) : null;
+    const registration = { resource_id: randomUUID(), run_id: runId, origin, path: GRAPH, node_id: id,
+      graph_digest: null, content_digest: null, content: null, state: 'unsupported', code: 'reference_unsupported' };
+    if (ref === GRAPH) return { ...registration, code: 'graph_file_reference' };
+    if (!id) return { ...registration, state: 'unresolved', code: 'reference_unresolved' };
+    load(); registration.graph_digest = graphDigest;
+    if (graphFailure) return { ...registration, state: graphFailure[0], code: graphFailure[1] };
+    const candidates = graphNodes.get(id) ?? [];
+    if (!candidates.length) return { ...registration, state: 'missing', code: 'node_missing' };
+    if (candidates.length !== 1) return { ...registration, state: 'blocked', code: 'node_ambiguous' };
+    const content = candidates[0];
+    if (Buffer.byteLength(content, 'utf8') > READ_LIMITS.preview) return { ...registration, code: 'resource_limit' };
+    return { ...registration, state: 'available', code: null, content, content_digest: digest(content) };
+  };
+  const references = []; let serializedBytes = 0;
+  for (const origin of origins) {
+    const reference = resolveReference(origin);
+    serializedBytes += Buffer.byteLength(JSON.stringify(reference), 'utf8') + 1;
+    if (serializedBytes > READ_LIMITS.response - 4096) fail('resource_limit');
+    references.push(reference);
+  }
+  const data = { run_id: runId, references };
+  if (Buffer.byteLength(JSON.stringify(data), 'utf8') > READ_LIMITS.response - 4096) fail('resource_limit');
+  return data;
+}
+
+export function composeCockpitPacket(metadata, document, context, input) {
+  if (input.graph_ids.length > 16 || input.excluded_ids.length > 64
+    || new Set([...input.graph_ids, ...input.excluded_ids]).size !== input.graph_ids.length + input.excluded_ids.length) fail('resource_denied');
+  const registrations = new Map(context.references.map(ref => [ref.resource_id, ref]));
+  for (const id of [...input.graph_ids, ...input.excluded_ids]) if (!registrations.has(id)) fail('resource_denied');
+  const selected = input.graph_ids.map(id => registrations.get(id));
+  if (selected.some(ref => ref.state !== 'available')) fail('resource_denied');
+  if (context.references.some(ref => ref.state !== 'available' && !input.excluded_ids.includes(ref.resource_id))) fail('context_exclusion_required');
+  const packet = { ...metadata, context_id: randomUUID(), generation: input.generation,
+    prepared_at: new Date().toISOString(), artefact: document,
+    graph_nodes: selected,
+    included: [{ resource_id: document.resource.resource_id, path: document.resource.path }, ...selected.map(ref => ({ resource_id: ref.resource_id, node_id: ref.node_id, origin: ref.origin }))],
+    excluded: context.references.filter(ref => !input.graph_ids.includes(ref.resource_id)).map(ref => ({ resource_id: ref.resource_id, node_id: ref.node_id, origin: ref.origin,
+      state: ref.state, code: ref.code, reason: input.excluded_ids.includes(ref.resource_id) ? 'deliberate_exclusion' : 'not_selected' })),
+    authorizes: false };
+  const byteCount = Buffer.byteLength(JSON.stringify(packet), 'utf8');
+  return byteCount > CONTEXT_LIMIT ? { packet: null, byte_count: byteCount, limit: CONTEXT_LIMIT } : { packet, byte_count: byteCount, limit: CONTEXT_LIMIT };
+}

package/runtime/core/lib/control-inspect/cockpit-contract.js

@@ -0,0 +1,86 @@
+// One wire-schema owner for the bounded cockpit connection. No filesystem selectors.
+import { COCKPIT_UI_URI } from '../mcp-resource-contract.js';
+export { COCKPIT_UI_URI, DECISION_UI_URI } from '../mcp-resource-contract.js';
+export const COCKPIT_MIME = 'text/html;profile=mcp-app';
+export const COCKPIT_LIMITS = Object.freeze({ html: 4 * 1024 ** 2, idle: 30 * 60_000, lifetime: 8 * 60 * 60_000,
+  sessions: 4, capture: 64 * 1024 ** 2, workerOldGeneration: 256 });
+const id = { type: 'string', format: 'uuid' };
+const run = { type: 'string', pattern: '^[A-Za-z0-9_-]{1,128}$' };
+function operation(name, fields = {}, optional = []) {
+  const properties = { operation: { const: name }, session_id: id, ...fields };
+  return { type: 'object', additionalProperties: false, properties, required: Object.keys(properties).filter(key => !optional.includes(key)) };
+}
+export const COCKPIT_READ_SCHEMA = Object.freeze({ oneOf: [
+  operation('snapshot', { run_id: run }, ['run_id']),
+  operation('backlog_titles', { snapshot_id: id, row_ids: { type: 'array', minItems: 1, maxItems: 12, uniqueItems: true, items: id } }),
+  operation('run', { snapshot_id: id, run_id: run }),
+  operation('artifact_readiness', { snapshot_id: id, run_id: run, gate: { type: 'string', enum: ['UR', 'PRD', 'SD', 'TP'] }, expected_revision_id: id }),
+  operation('document', { snapshot_id: id, run_id: run, resource_id: id }),
+  operation('preview', { snapshot_id: id, run_id: run, resource_id: id }),
+  operation('freshness', { snapshot_id: id }),
+  operation('changes', { snapshot_id: id }),
+  operation('context', { snapshot_id: id, run_id: run }),
+  operation('prepare_context', { snapshot_id: id, run_id: run, revision_id: id, resource_id: id,
+    graph_ids: { type: 'array', maxItems: 16, uniqueItems: true, items: id },
+    excluded_ids: { type: 'array', maxItems: 64, uniqueItems: true, items: id },
+    generation: { type: 'integer', minimum: 1 } }),
+  operation('validate_context', { context_id: id, generation: { type: 'integer', minimum: 1 } }),
+  operation('invalidate_context'),
+  operation('complete_context_invalidation', { invalidation_id: id }),
+  operation('close'),
+] });
+const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+export const COCKPIT_RENDER_DEFINITION = Object.freeze({ name: 'agdf_cockpit',
+  description: 'Open the local read-only AGDF cockpit. When the user opens the cockpit for a Run explicitly identified in the request or already unambiguously established with the user in this conversation, you must pass its run_id, even if the latest request only says to open the cockpit. Omit run_id only when the user explicitly requests the overall overview or no unambiguous conversation Run exists. If several Runs could be intended, ask which to view. Never infer a Run from directory, recency or inventory. The optional schema preserves overview access; it does not make passing an established conversation Run optional. Selection and context never approve or authorize delivery.',
+  annotations, inputSchema: { type: 'object', properties: { run_id: run }, additionalProperties: false },
+  _meta: { ui: { resourceUri: COCKPIT_UI_URI, visibility: ['model', 'app'] } } });
+export const COCKPIT_READ_DEFINITION = Object.freeze({ name: 'agdf_cockpit_read',
+  description: 'Read registered sources or check the selected current canonical draft from the explicitly bound local AGDF project using scoped cockpit selectors. Draft checks are read-only authoring checks and never approve or authorize delivery.',
+  annotations, inputSchema: COCKPIT_READ_SCHEMA,
+  _meta: { ui: { visibility: ['model', 'app'] } } });
+
+// Plugin opening has an explicit project; the directory-bound contract is unchanged.
+export const COCKPIT_PLUGIN_RENDER_DEFINITION = Object.freeze({ ...COCKPIT_RENDER_DEFINITION,
+  description: `${COCKPIT_RENDER_DEFINITION.description} For the plugin, supply the confirmed absolute primary_target, its target_source and an accessible absolute working_directory. Never infer a project from the plugin location or directory alone.`,
+  inputSchema: { type: 'object', additionalProperties: false,
+    properties: { run_id: run, working_directory: { type: 'string', minLength: 1, maxLength: 4096 },
+      primary_target: { type: 'string', minLength: 1, maxLength: 4096 },
+      target_source: { type: 'string', enum: ['explicit_target', 'continued_target', 'current_repository'] } },
+    required: ['working_directory', 'primary_target', 'target_source'] } });
+
+export function parsePluginCockpitArguments(value) {
+  const fields = COCKPIT_PLUGIN_RENDER_DEFINITION.inputSchema;
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(key => !Object.hasOwn(fields.properties, key))
+    || fields.required.some(key => typeof value[key] !== 'string' || !value[key] || value[key].length > 4096)
+    || !fields.properties.target_source.enum.includes(value.target_source)) {
+    throw Object.assign(new TypeError('resource_denied'), { code: 'resource_denied' });
+  }
+  const runInput = parseCockpitArguments(Object.hasOwn(value, 'run_id') ? { run_id: value.run_id } : {}, true);
+  return { ...value, ...runInput };
+}
+
+export function parseCockpitArguments(value, render = false) {
+  const reject = () => { throw Object.assign(new TypeError('resource_denied'), { code: 'resource_denied' }); };
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return reject();
+  if (render) {
+    if (Object.keys(value).some(key => key !== 'run_id')) return reject();
+    if (!Object.hasOwn(value, 'run_id')) return {};
+    if (typeof value.run_id !== 'string' || !new RegExp(run.pattern).test(value.run_id)) return reject();
+    return { run_id: value.run_id };
+  }
+  const branch = COCKPIT_READ_SCHEMA.oneOf.find(row => row.properties.operation.const === value.operation);
+  if (!branch || Object.keys(value).some(key => !Object.hasOwn(branch.properties, key)) || branch.required.some(key => !Object.hasOwn(value, key))) return reject();
+  const valid = (item, rule) => {
+    if (rule.const !== undefined) return item === rule.const;
+    if (rule.type === 'string') return typeof item === 'string'
+      && (!rule.format || /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(item))
+      && (!rule.pattern || new RegExp(rule.pattern).test(item)) && (!rule.enum || rule.enum.includes(item));
+    if (rule.type === 'integer') return Number.isSafeInteger(item) && item >= rule.minimum;
+    if (rule.type === 'array') return Array.isArray(item) && item.length >= (rule.minItems ?? 0) && item.length <= rule.maxItems
+      && new Set(item).size === item.length && item.every(entry => valid(entry, rule.items));
+    return false;
+  };
+  if (Object.keys(value).some(key => !valid(value[key], branch.properties[key]))) return reject();
+  return { ...value };
+}

package/runtime/core/lib/control-inspect/cockpit-list.d.ts

@@ -0,0 +1,17 @@
+export const COCKPIT_BACKLOG_SECTIONS: readonly ['Active Backlog', 'Planned / Parking Lot', 'Completed / Superseded Pointers'];
+export interface ListEntry { section: string; key: string; title: string; stored_status: string; selectable: boolean }
+export interface ListDiagnostic { code: string; section?: string; key?: string | null }
+export interface ListInventory<T extends ListEntry = ListEntry, D extends ListDiagnostic = ListDiagnostic> {
+  entries: T[]; diagnostics: D[]; counts: Record<string, number>; content_digest: string; source_path: string;
+}
+export interface CockpitListRow<T extends ListEntry = ListEntry> {
+  entry: T; index: number; identity: string; selectable: boolean; displayTitle: string;
+  provenance: { path: string; digest: string; originalTitle: string };
+}
+export interface CockpitList<T extends ListEntry = ListEntry, D extends ListDiagnostic = ListDiagnostic> {
+  section: string; query: string; coverage: 'complete' | 'partial' | 'unavailable'; diagnostics: D[];
+  sectionCount: number | null; matchCount: number | null; rows: CockpitListRow<T>[];
+}
+export function hasConsistentBacklogCounts(inventory: unknown): boolean;
+export function backlogRowKey(entry: ListEntry, index: number, digest: string): string;
+export function projectCockpitList<T extends ListEntry, D extends ListDiagnostic>(inventory: ListInventory<T, D> | null, options?: { section?: string; query?: string }): CockpitList<T, D>;

package/runtime/core/lib/control-inspect/cockpit-list.js

@@ -0,0 +1,45 @@
+// Pure internal Core policy shared by Node readers and browser list presentations.
+// Raw entries and opaque selectors remain in source order and are never modified here.
+export const COCKPIT_BACKLOG_SECTIONS = Object.freeze([
+  'Active Backlog', 'Planned / Parking Lot', 'Completed / Superseded Pointers',
+]);
+const unreadableLayout = /^(backlog_(section_missing|layout_missing|layout_unsupported)|AGDF_BACKLOG_LAYOUT_UNKNOWN)$/;
+
+export function hasConsistentBacklogCounts(inventory) {
+  if (!inventory || !Array.isArray(inventory.entries) || !inventory.counts || typeof inventory.counts !== 'object') return false;
+  const actual = new Map();
+  for (const row of inventory.entries) {
+    if (!row || !COCKPIT_BACKLOG_SECTIONS.includes(row.section)) return false;
+    actual.set(row.section, (actual.get(row.section) ?? 0) + 1);
+  }
+  return Object.entries(inventory.counts).every(([section, count]) => COCKPIT_BACKLOG_SECTIONS.includes(section)
+    && Number.isSafeInteger(count) && count >= 0 && count === (actual.get(section) ?? 0))
+    && [...actual.keys()].every(section => Object.hasOwn(inventory.counts, section));
+}
+
+export function backlogRowKey(entry, index, digest) {
+  return JSON.stringify([digest, index, entry.section, entry.key]);
+}
+
+export function projectCockpitList(inventory, { section = COCKPIT_BACKLOG_SECTIONS[0], query = '' } = {}) {
+  if (!COCKPIT_BACKLOG_SECTIONS.includes(section)) throw Error('dto_invalid');
+  const normalizedQuery = query.trim().toLowerCase();
+  const unavailable = { section, query: normalizedQuery, coverage: 'unavailable', diagnostics: [], sectionCount: null, matchCount: null, rows: [] };
+  if (!inventory) return unavailable;
+  if (!hasConsistentBacklogCounts(inventory)) throw Error('dto_invalid');
+  const diagnostics = inventory.diagnostics.filter(d => !d.section || d.section === section);
+  if (!Object.hasOwn(inventory.counts, section) || diagnostics.some(d => unreadableLayout.test(d.code))) return { ...unavailable, diagnostics };
+  const rows = [];
+  let sectionCount = 0, nonselectable = false;
+  inventory.entries.forEach((entry, index) => {
+    if (entry.section !== section) return;
+    sectionCount++;
+    nonselectable ||= !entry.selectable;
+    if (normalizedQuery && ![entry.title, entry.key, entry.stored_status].some(field => field.toLowerCase().includes(normalizedQuery))) return;
+    rows.push({ entry, index, identity: backlogRowKey(entry, index, inventory.content_digest), selectable: entry.selectable,
+      displayTitle: entry.title.replace(/^\[(framework[-_]maintenance|external[-_]delivery)\]\s*/i, '') || entry.title,
+      provenance: { path: inventory.source_path, digest: inventory.content_digest, originalTitle: entry.title } });
+  });
+  return { section, query: normalizedQuery, coverage: diagnostics.length || nonselectable ? 'partial' : 'complete', diagnostics,
+    sectionCount, matchCount: rows.length, rows: rows.reverse() };
+}