create-agdf 0.14.5 → 0.20.1

package/generated/plugins/copilot/agdf/runtime/create-agdf/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/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-inspect/contract.js

@@ -0,0 +1,299 @@
+import { isAbsolute } from "node:path";
+import { RUN_ID_PATTERN, REVISION_ID_PATTERN } from "../control-state/run-identity.js";
+import { ARTIFACT_READINESS_GATES } from "./artifact-readiness.js";
+import { RUN_COMMAND_GROUPS } from '../control-state/run-command-contract.js';
+import { APPROVAL_GATES } from '../control-state/run-identity.js';
+import {
+  PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE,
+  canonicalizeLanguageTag,
+  resolvePresentationLocale,
+} from "../interaction-presentation.js";
+import { normalizeTaskTargetSource, TASK_TARGET_SOURCES } from "../task-target-resolution.js";
+import { SKILL_DISPATCH_MAX_OUTPUT_BYTES, SkillDispatchInputError, emptySkillDispatchTiming } from "../skill-dispatch/contract.js";
+import { ALL_ACTIVE_OPERATIONS, VARIANT_OPERATION, MODULE_OPERATION, CONTROL_INSPECT_OPERATIONS, GATE_CHECK_VARIANTS, ReadSelectionError, validateReadSelection } from "./selection.js";
+
+export const CONTROL_INSPECT_SCHEMA_VERSION = "1";
+export const CONTROL_INSPECT_CONTRACT_VERSION = 1;
+// Every byte of this definition is loaded into every session on every host (SDD-005).
+export const CONTROL_INSPECT_MAX_DEFINITION_BYTES = 5000;
+export const OPERATION_CONTRACT_MODULES = Object.freeze(Object.entries(RUN_COMMAND_GROUPS)
+  .flatMap(([group, kinds]) => kinds.map(kind => `${group}/${kind}`)));
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+// One field model supplies discovery, applicability guards and on-demand help.
+export const PRESENTATION_OPERATIONS = Object.freeze(['presentation-document', 'presentation-preview']);
+export const BOUND_INSPECT_OPERATIONS = Object.freeze(['artifact-readiness', 'operation-contract', 'operation-status', 'native-qualification', ...PRESENTATION_OPERATIONS, 'runtime-generations']);
+export const PRESENTATION_CATALOG_MODULE = 'agdf_prepare/presentation.prepare';
+const uuidSchema = { type: 'string', pattern: REVISION_ID_PATTERN.source };
+const cursorSchema = { type: 'string', maxLength: 80, pattern: '^[0-9a-f]{64}:(?:0|[1-9][0-9]{0,6})$' };
+const fieldModel = {
+  operation: { help: 'Read-only operation; requirements below. Reads never prepare or approve a gate.', schema: { enum: [...CONTROL_INSPECT_OPERATIONS] }, description: 'Read action.' },
+  presentation_language: { help: 'Required BCP47 tag; valid unsupported languages use the complete English pack.', schema: { type: 'string', maxLength: 64, pattern: PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE }, description: 'Reply BCP47 tag.' },
+  working_directory: { help: 'Absolute execution context; it does not select a target.', schema: { type: 'string', minLength: 1, maxLength: 4096 }, description: 'Absolute context; not target authority.' },
+  target_source: { help: 'explicit_target: directly specified target; continued_target: confirmed continuation; current_repository: unambiguous current repository. Use actual provenance.', schema: { enum: [...TASK_TARGET_SOURCES] }, description: 'Paired target provenance.' },
+  primary_target: { help: 'Confirmed absolute project root, paired with target_source. working_directory never selects the target.', schema: { type: 'string', minLength: 1, maxLength: 4096 }, description: 'Confirmed absolute root.' },
+  run_id: { help: 'Use the named or unambiguously confirmed run; never select by recency.', schema: { type: 'string', pattern: RUN_ID_PATTERN.source }, description: 'Confirmed run.' },
+  gate: { help: 'Use the requested document gate; it is an optional catalog filter, not a selection heuristic. artifact-readiness accepts UR, PRD, SD or TP drafts only.', schema: { enum: [...APPROVAL_GATES] }, description: 'Draft/read gate; catalog filter.', operations: ['artifact-readiness', 'operation-contract', ...PRESENTATION_OPERATIONS] },
+  expected_revision_id: { help: 'For bound current-state inspections use the current gate-check revision. For document/preview reads preserve the selected prepared record original revision from catalog read_arguments or the original conversation binding.', schema: { $ref: '#/$defs/i' }, description: 'gate-check revision; original for reads.', operations: BOUND_INSPECT_OPERATIONS },
+  presentation_id: { help: 'Use the exact prepared ID from a validated catalog candidate or the existing conversation binding. Never guess a UUID, choose by timestamp, or prepare another presentation to pass a read.', schema: { $ref: '#/$defs/i' }, description: 'ID from catalog/conversation.', operations: PRESENTATION_OPERATIONS },
+  target_id: { help: 'Copy binding.target_id from operation-contract or the selected catalog read_arguments; this digest identifies a target and grants no authority.', schema: { type: 'string', pattern: '^sha256:[0-9a-f]{64}$' }, description: 'Target hash: operation-contract.', operations: PRESENTATION_OPERATIONS },
+  cursor: { help: 'Omit on the first page, then copy next_cursor unchanged. Catalog cursors are accepted only on operation-contract module=agdf_prepare/presentation.prepare. Never exchange document, preview or catalog cursors.', schema: cursorSchema, description: 'Next cursor; omit initially.', operations: [...PRESENTATION_OPERATIONS, 'operation-contract'] },
+  variant: { help: 'gate-check only: status-card or approval-envelope. Neither variant records an approval.', schema: { enum: [...GATE_CHECK_VARIANTS] }, description: 'gate-check view.', operations: [VARIANT_OPERATION] },
+  module: { help: 'contract uses an advertised runtime module; operation-contract uses group/kind; operation-status uses the original operation_id from the saved command receipt, never a newly generated UUID.', schema: { type: 'string', minLength: 1, maxLength: 64 }, description: 'Contract, group/kind or receipt UUID.', operations: [MODULE_OPERATION, 'operation-contract', 'operation-status'] },
+  all_active: { help: 'Only doctor and delivery-map accept true. False retains the selected-run read behavior.', schema: { type: 'boolean' }, description: 'All runs: doctor/delivery-map.' },
+};
+const moduleOperations = [MODULE_OPERATION, 'operation-contract', 'operation-status'];
+const inputSchema = {
+  type: 'object', additionalProperties: false,
+  required: ['operation', 'presentation_language', 'working_directory'],
+  $defs: { i: uuidSchema, b: { not: { enum: CONTROL_INSPECT_OPERATIONS.filter(op => !BOUND_INSPECT_OPERATIONS.includes(op)) } }, d: { enum: PRESENTATION_OPERATIONS }, m: { enum: moduleOperations } },
+  properties: Object.fromEntries(Object.entries(fieldModel).map(([name, field]) => [name, { ...field.schema, description: field.description }])),
+  dependentRequired: { target_source: ['primary_target'], primary_target: ['target_source'] },
+  dependentSchemas: Object.fromEntries(Object.entries(fieldModel).filter(([, f]) => f.operations).map(([name, field]) => [name,
+    name === 'cursor' ? { anyOf: [ { properties: { operation: { $ref: '#/$defs/d' } } },
+      { properties: { operation: { const: 'operation-contract' }, module: { const: PRESENTATION_CATALOG_MODULE } } } ] }
+      : { properties: { operation: field.operations === BOUND_INSPECT_OPERATIONS ? { $ref: '#/$defs/b' }
+        : field.operations === PRESENTATION_OPERATIONS ? { $ref: '#/$defs/d' } : name === 'module' ? { $ref: '#/$defs/m' } : { enum: field.operations } } },
+  ])),
+  allOf: [
+    { anyOf: [{ properties: { all_active: { const: false } } }, { properties: { operation: { enum: [...ALL_ACTIVE_OPERATIONS] } } }] },
+    { if: { properties: { operation: { $ref: '#/$defs/m' } } }, then: { required: ['module'] } },
+    { if: { properties: { operation: { $ref: '#/$defs/b' } } }, then: { required: ['run_id', 'expected_revision_id', 'target_source'] } },
+    { if: { properties: { operation: { const: 'artifact-readiness' } } }, then: { required: ['gate'], properties: { gate: { enum: [...ARTIFACT_READINESS_GATES] } } } },
+    { if: { properties: { operation: { $ref: '#/$defs/d' } } }, then: { required: ['gate', 'presentation_id', 'target_id'] } },
+  ],
+};
+
+const inspectContract = {
+  name: "agdf_inspect",
+  description: "Read-only: gate-check -> operation-contract module=agdf_prepare/presentation.prepare -> catalog read_arguments -> presentation-document/next_cursor.",
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema,
+  outputSchema: {
+    type: 'object', required: ['outcome', 'terminal', 'authorizes', 'operation', 'report', 'presentation', 'host_action', 'target', 'recovery'],
+    properties: {
+      schema_version: { const: '1' }, contract_version: { const: 1 }, authorizes: { const: false },
+      operation: { type: ['string', 'null'] }, runtime: { type: 'object' }, target: { type: ['object', 'null'] },
+      report: { type: ['object', 'null'] }, recovery: { type: ['object', 'null'], required: ['action'], properties: { action: { type: 'string', minLength: 1 } } },
+      presentation: { type: ['object', 'null'], required: ['markdown'], properties: { markdown: { type: 'string' } } },
+      timing: { type: 'object' }, diagnostics: { type: 'array', items: { type: 'object' } },
+      host_action: { type: 'object', required: ['mode', 'source', 'allow_surrounding_text', 'may_request_run_or_evidence'],
+        properties: { text: { type: 'string', minLength: 1 }, may_request_run_or_evidence: { const: false } } },
+    },
+    oneOf: [
+      { properties: { outcome: { const: 'inspect_result' }, terminal: { const: false }, operation: { enum: [...CONTROL_INSPECT_OPERATIONS] },
+        report: { type: 'object' }, recovery: { type: 'null' }, target: { type: 'object', required: ['resolution_state'], properties: { resolution_state: { const: 'resolved' } } },
+        host_action: { properties: { mode: { const: 'consume_report_and_continue' }, source: { enum: ['report', 'presentation.markdown'] }, allow_surrounding_text: { const: true } } } },
+        if: { properties: { host_action: { properties: { source: { const: 'presentation.markdown' } } } } },
+        then: { properties: { presentation: { type: 'object', properties: { markdown: { minLength: 1 } } }, host_action: { required: ['text'] } } },
+        else: { properties: { presentation: { anyOf: [{ type: 'null' }, { properties: { markdown: { const: '' } } }] }, host_action: { not: { required: ['text'] } } } },
+      },
+      { properties: { outcome: { const: 'target_unresolved' }, terminal: { const: true }, report: { type: 'null' }, recovery: { type: 'object' },
+        target: { type: 'object', required: ['resolution_state'], properties: { resolution_state: { const: 'unresolved' } } },
+        presentation: { type: 'object', properties: { markdown: { minLength: 1 } } },
+        host_action: { required: ['text'], properties: { mode: { const: 'transmit_presentation_verbatim_and_stop' }, source: { const: 'presentation.markdown' }, allow_surrounding_text: { const: false } } } } },
+      { properties: { outcome: { enum: ['invalid_input', 'evaluator_error'] }, terminal: { const: true }, report: { type: 'null' }, recovery: { type: 'object' }, presentation: { type: 'null' },
+        host_action: { required: ['text'], properties: { mode: { const: 'transmit_recovery_verbatim_and_stop' }, source: { const: 'recovery.action' }, allow_surrounding_text: { const: false } } } } },
+    ],
+  },
+};
+
+// Detailed result semantics remain owned here. The discovered tool advertises the
+// bounded envelope; repeating every forwarding branch in each model session is
+// unnecessary. Both declarations derive from this same contract, without a
+// second evaluator or a larger discovery budget.
+export const CONTROL_INSPECT_OUTPUT_SCHEMA = deepFreeze(inspectContract.outputSchema);
+export const CONTROL_INSPECT_FUNCTION_DEFINITION = deepFreeze({
+  ...inspectContract,
+  outputSchema: { type: 'object', required: inspectContract.outputSchema.required,
+    properties: { ...Object.fromEntries(Object.entries(inspectContract.outputSchema.properties).filter(([key]) => key !== 'report').map(([key, value]) => [key, key === 'recovery' ? { required: value.required, properties: value.properties } : value])),
+      outcome: { enum: ['inspect_result', 'target_unresolved', 'invalid_input', 'evaluator_error'] },
+    },
+    if: { properties: { outcome: { const: 'inspect_result' } } },
+    then: { properties: { terminal: { const: false }, report: { type: 'object' }, recovery: { type: 'null' } } },
+    else: { properties: { terminal: { const: true }, report: { type: 'null' }, recovery: { type: 'object' } } },
+  },
+});
+
+export function inspectContractHelp() {
+  const base = { presentation_language: 'de', working_directory: '/workspace/project', target_source: 'explicit_target', primary_target: '/workspace/project', run_id: 'demo-run-01' };
+  const revision = '00000000-0000-4000-8000-000000000001';
+  return deepFreeze({ schema_version: '1', authorizes: false,
+    parameters: Object.fromEntries(Object.entries(fieldModel).map(([key, field]) => [key, { description: field.help ?? field.description, operations: field.operations ?? [...CONTROL_INSPECT_OPERATIONS] }])),
+    operations: Object.fromEntries(CONTROL_INSPECT_OPERATIONS.map(operation => [operation, {
+      required: [...inputSchema.required, ...(BOUND_INSPECT_OPERATIONS.includes(operation) ? ['run_id', 'expected_revision_id', 'target_source', 'primary_target'] : []),
+        ...(['contract', 'operation-contract', 'operation-status'].includes(operation) ? ['module'] : []),
+        ...(operation === 'artifact-readiness' ? ['gate'] : PRESENTATION_OPERATIONS.includes(operation) ? ['gate', 'presentation_id', 'target_id'] : [])],
+    }])),
+    examples_are_illustrative: true,
+    examples: [ { ...base, operation: 'gate-check' },
+      { ...base, operation: 'operation-contract', module: PRESENTATION_CATALOG_MODULE, expected_revision_id: revision, gate: 'UR' },
+      { ...base, operation: 'presentation-document', expected_revision_id: revision, gate: 'UR', presentation_id: '00000000-0000-4000-8000-000000000002', target_id: `sha256:${'0'.repeat(64)}` } ],
+    provenance: 'Keep exact conversation bindings. Otherwise use catalog read_arguments only after unique complete discovery or explicit selection. Document revision is original, not current. Prepared is not human-viewed or approved. Other modules reject catalog cursors.',
+    catalog_limits: { page_candidates: 16, record_files: 256, record_bytes: 1048576, directory_entries: 1024 },
+  });
+}
+
+export function controlInspectDefinitionBytes(definition = CONTROL_INSPECT_FUNCTION_DEFINITION) {
+  return Buffer.byteLength(JSON.stringify(definition), "utf8");
+}
+
+function requireText(value, field, maximum = 240) {
+  if (typeof value !== "string" || !value.trim()) throw new SkillDispatchInputError(field, `${field} is required`);
+  if (value.length > maximum || /[\r\n\0]/u.test(value)) throw new SkillDispatchInputError(field, `${field} is invalid`);
+  return value;
+}
+
+export function parseControlInspectFunctionArguments(argumentsValue, trustedContext) {
+  if (!argumentsValue || typeof argumentsValue !== "object" || Array.isArray(argumentsValue)) {
+    throw new SkillDispatchInputError("arguments", "arguments must be an object");
+  }
+  const schema = CONTROL_INSPECT_FUNCTION_DEFINITION.inputSchema;
+  const allowed = new Set(Object.keys(schema.properties));
+  const unknown = Object.keys(argumentsValue).find((key) => !allowed.has(key));
+  if (unknown) throw new SkillDispatchInputError(unknown, "unsupported argument");
+  const missing = schema.required.find((key) => !Object.hasOwn(argumentsValue, key));
+  if (missing) throw new SkillDispatchInputError(missing, "required argument is missing");
+  if (!trustedContext || typeof trustedContext !== "object") {
+    throw new SkillDispatchInputError("trusted_context", "trusted context is required");
+  }
+  if (Boolean(argumentsValue.target_source) !== Boolean(argumentsValue.primary_target)) {
+    throw new SkillDispatchInputError("primary_target", "target_source and primary_target must be supplied together");
+  }
+  return deepFreeze({
+    operation: argumentsValue.operation,
+    presentationLanguage: argumentsValue.presentation_language,
+    workingDirectory: argumentsValue.working_directory,
+    targetSource: argumentsValue.target_source,
+    primaryTarget: argumentsValue.primary_target,
+    runId: argumentsValue.run_id,
+    ...(argumentsValue.gate !== undefined ? { gate: argumentsValue.gate } : {}),
+    ...(argumentsValue.expected_revision_id !== undefined ? { expectedRevisionId: argumentsValue.expected_revision_id } : {}),
+    ...(argumentsValue.presentation_id !== undefined ? { presentationId: argumentsValue.presentation_id } : {}),
+    ...(argumentsValue.target_id !== undefined ? { targetId: argumentsValue.target_id } : {}),
+    ...(argumentsValue.cursor !== undefined ? { cursor: argumentsValue.cursor } : {}),
+    ...(argumentsValue.variant !== undefined ? { variant: argumentsValue.variant } : {}),
+    ...(argumentsValue.module !== undefined ? { contractModule: argumentsValue.module } : {}),
+    ...(argumentsValue.all_active !== undefined ? { allActive: argumentsValue.all_active } : {}),
+    surface: trustedContext.surface,
+    expectedVersion: trustedContext.expectedVersion,
+    interactionLocales: trustedContext.interactionLocales,
+  });
+}
+
+// Normalizes a raw inspect input with the dispatcher's language and target rules and the shared
+// read-selection rules. Throws SkillDispatchInputError or ReadSelectionError; both carry `field`.
+export function normalizeControlInspectInput(input) {
+  const operation = requireText(input.operation, "operation", 64);
+  if (!CONTROL_INSPECT_OPERATIONS.includes(operation)) throw new SkillDispatchInputError("operation", `Unsupported inspect operation: ${operation}`);
+  let requestedPresentationLanguage;
+  try {
+    requestedPresentationLanguage = requireText(input.presentationLanguage, "presentation_language", 64);
+  } catch {
+    throw new SkillDispatchInputError("presentation_language", "presentation_language is required");
+  }
+  const canonical = canonicalizeLanguageTag(requestedPresentationLanguage);
+  if (!canonical) throw new SkillDispatchInputError("presentation_language", "presentation_language is invalid");
+  const presentationLanguage = resolvePresentationLocale(input.interactionLocales, canonical);
+  const workingDirectory = requireText(input.workingDirectory, "working_directory", 4096);
+  if (!isAbsolute(workingDirectory)) throw new SkillDispatchInputError("working_directory", "working_directory must be absolute");
+  const rawTargetSource = input.targetSource || null;
+  const primaryTarget = input.primaryTarget || null;
+  if (Boolean(rawTargetSource) !== Boolean(primaryTarget)) throw new SkillDispatchInputError("primary_target", "target_source and primary_target must be supplied together");
+  if (primaryTarget && (!isAbsolute(primaryTarget) || primaryTarget.length > 4096)) throw new SkillDispatchInputError("primary_target", "primary_target must be an absolute bounded path");
+  const targetSource = rawTargetSource ? normalizeTaskTargetSource(rawTargetSource, { allowEmpty: false }) : null;
+  const runId = input.runId || null;
+  if (runId && !RUN_ID_PATTERN.test(runId)) throw new SkillDispatchInputError("run_id", "run_id is invalid");
+  if (operation === "artifact-readiness") {
+    if (!runId) throw new SkillDispatchInputError("run_id", "artifact-readiness requires an explicit run_id");
+    if (!primaryTarget) throw new SkillDispatchInputError("primary_target", "artifact-readiness requires an explicit target binding");
+    if (!ARTIFACT_READINESS_GATES.includes(input.gate)) throw new SkillDispatchInputError("gate", "Unsupported draft gate");
+    if (!REVISION_ID_PATTERN.test(input.expectedRevisionId ?? "")) throw new SkillDispatchInputError("expected_revision_id", "A valid expected revision is required");
+  } else if (BOUND_INSPECT_OPERATIONS.includes(operation)) {
+    if (!runId || !primaryTarget || !REVISION_ID_PATTERN.test(input.expectedRevisionId ?? '')) throw new SkillDispatchInputError('binding', 'An exact target, Run and expected revision binding is required');
+    if (operation === 'operation-contract' && !OPERATION_CONTRACT_MODULES.includes(input.contractModule)) {
+      throw new SkillDispatchInputError('module', 'Unsupported command group/operation module', { allowedValues: OPERATION_CONTRACT_MODULES });
+    }
+    if (operation === 'operation-status' && !REVISION_ID_PATTERN.test(input.contractModule ?? '')) throw new SkillDispatchInputError('operation_id', 'An original operation UUID is required');
+    if (input.gate !== undefined && (!['operation-contract', 'presentation-document', 'presentation-preview'].includes(operation) || !APPROVAL_GATES.includes(input.gate))) throw new SkillDispatchInputError('gate', 'Unsupported operation gate');
+  } else if (input.gate !== undefined || input.expectedRevisionId !== undefined) {
+    throw new SkillDispatchInputError("gate", "Draft binding fields are supported only by artifact-readiness");
+  }
+  if (['presentation-document', 'presentation-preview'].includes(operation)) {
+    if (!APPROVAL_GATES.includes(input.gate) || !REVISION_ID_PATTERN.test(input.presentationId ?? '')
+      || !/^sha256:[0-9a-f]{64}$/u.test(input.targetId ?? '')
+      || input.cursor !== undefined && !/^[0-9a-f]{64}:(?:0|[1-9][0-9]{0,6})$/u.test(input.cursor)) throw new SkillDispatchInputError('presentation', 'An exact presentation binding and bounded cursor are required');
+  } else if (input.presentationId !== undefined || input.targetId !== undefined || input.cursor !== undefined && !(operation === 'operation-contract' && input.contractModule === PRESENTATION_CATALOG_MODULE && new RegExp(cursorSchema.pattern, 'u').test(input.cursor) && typeof input.cursor === 'string' && input.cursor.length <= cursorSchema.maxLength)) {
+    throw new SkillDispatchInputError('presentation', 'Document selectors require presentation-document');
+  }
+  if (input.allActive !== undefined && typeof input.allActive !== "boolean") throw new SkillDispatchInputError("all_active", "all_active is invalid");
+  if (input.contractModule !== undefined) requireText(input.contractModule, "module", 64);
+  if (input.variant !== undefined) requireText(input.variant, "variant", 32);
+  validateReadSelection({
+    operation,
+    allActive: input.allActive === true,
+    contractModule: input.contractModule,
+    variant: input.variant,
+  });
+  const selectorKeys = { gate: 'gate', expected_revision_id: 'expectedRevisionId', presentation_id: 'presentationId', target_id: 'targetId', cursor: 'cursor', variant: 'variant', module: 'contractModule' };
+  for (const [field, key] of Object.entries(selectorKeys)) {
+    if (input[key] !== undefined && !fieldModel[field].operations.includes(operation)) throw new SkillDispatchInputError(field, `Unsupported selector for ${operation}`);
+  }
+  return Object.freeze({
+    schema_version: CONTROL_INSPECT_SCHEMA_VERSION,
+    operation,
+    surface: input.surface ?? null,
+    presentation_language: presentationLanguage,
+    working_directory: workingDirectory,
+    target_source: targetSource,
+    primary_target: primaryTarget,
+    run_id: runId,
+    gate: input.gate,
+    expected_revision_id: input.expectedRevisionId,
+    presentation_id: input.presentationId, target_id: input.targetId, cursor: input.cursor,
+    group: operation === 'operation-contract' ? input.contractModule.split('/')[0] : undefined,
+    kind: operation === 'operation-contract' ? input.contractModule.split('/')[1] : undefined, operation_id: operation === 'operation-status' ? input.contractModule : undefined,
+    variant: input.variant,
+    contract_module: input.contractModule,
+    all_active: input.allActive === true,
+    expected_version: requireText(input.expectedVersion, "expected_version", 64),
+  });
+}
+
+export { ReadSelectionError };
+
+export const CONTROL_INSPECT_OUTPUT_TOO_LARGE_RECOVERY = "The inspect result exceeds the 1 MiB MCP output limit. Narrow the selection (one run_id instead of all_active) or use the CLI with --json.";
+
+// Same 1 MiB ceiling as the dispatcher, but the fallback keeps the inspect result shape so the host
+// receives a schema-valid recovery instead of a schema error.
+export function serializeControlInspectResult(result) {
+  const output = JSON.stringify(result, null, 2);
+  if (Buffer.byteLength(output, "utf8") <= SKILL_DISPATCH_MAX_OUTPUT_BYTES) return output;
+  return JSON.stringify({
+    schema_version: CONTROL_INSPECT_SCHEMA_VERSION,
+    contract_version: CONTROL_INSPECT_CONTRACT_VERSION,
+    outcome: "evaluator_error",
+    terminal: true,
+    authorizes: false,
+    operation: result?.operation ?? null,
+    runtime: result?.runtime ?? {},
+    target: result?.target ?? null,
+    report: null,
+    presentation: null,
+    recovery: { action: CONTROL_INSPECT_OUTPUT_TOO_LARGE_RECOVERY },
+    host_action: {
+      mode: "transmit_recovery_verbatim_and_stop",
+      source: "recovery.action",
+      text: CONTROL_INSPECT_OUTPUT_TOO_LARGE_RECOVERY,
+      allow_surrounding_text: false,
+      may_request_run_or_evidence: false,
+    },
+    timing: result?.timing ?? emptySkillDispatchTiming(),
+    diagnostics: [{ code: "inspect_output_too_large" }],
+  }, null, 2);
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-inspect/selection.js

@@ -0,0 +1,35 @@
+// Shared read-only selection policy for CLI and MCP; evaluation never writes control state.
+
+export const CONTROL_INSPECT_OPERATIONS = Object.freeze(["doctor", "gate-check", "delivery-map", "contract", "artifact-readiness", "operation-contract", "operation-status", "native-qualification", "presentation-document", "presentation-preview", "runtime-generations"]);
+export const ALL_ACTIVE_OPERATIONS = Object.freeze(["doctor", "delivery-map"]);
+export const VARIANT_OPERATION = "gate-check";
+export const MODULE_OPERATION = "contract";
+export const GATE_CHECK_VARIANTS = Object.freeze(["status-card", "approval-envelope"]);
+
+export class ReadSelectionError extends Error {
+  constructor(field, message) {
+    super(message);
+    this.name = "ReadSelectionError";
+    this.field = field;
+  }
+}
+
+// `operation` is the CLI command name or the MCP operation. Rules apply to every command so that a
+// write command carrying a read-only flag is rejected exactly as before the extraction.
+export function validateReadSelection({ operation, allActive = false, contractModule, variant } = {}) {
+  if (allActive && !ALL_ACTIVE_OPERATIONS.includes(operation)) {
+    throw new ReadSelectionError("all_active", "--all-active is supported only by doctor and delivery-map");
+  }
+  if (contractModule !== undefined && ![MODULE_OPERATION, 'operation-contract', 'operation-status'].includes(operation)) {
+    throw new ReadSelectionError("module", "--module is supported only by contract");
+  }
+  if ([MODULE_OPERATION, 'operation-contract', 'operation-status'].includes(operation) && !contractModule) {
+    throw new ReadSelectionError("module", "contract requires --module");
+  }
+  if (variant !== undefined && operation !== VARIANT_OPERATION) {
+    throw new ReadSelectionError("variant", "--status-card and --approval-envelope are supported only by gate-check");
+  }
+  if (variant !== undefined && !GATE_CHECK_VARIANTS.includes(variant)) {
+    throw new ReadSelectionError("variant", `gate-check variant must be one of ${GATE_CHECK_VARIANTS.join(", ")}`);
+  }
+}