create-agdf 0.11.4 → 0.13.0

package/lib/proportionality-benchmark/evaluator.js

@@ -0,0 +1,250 @@
+import { DELIVERY_PATHS, PATH_RANK, STAGES, fail, stable } from "./contracts.js";
+import { sourceFingerprint } from "./source-fingerprint.js";
+import { ADAPTER_VERSION, STAGED_ADAPTER_VERSION } from "./live-recorder.js";
+
+export function classifyObservation(expected, observation) {
+  if (observation.ambiguous || observation.observed_delivery_path === null) return "ambiguous";
+  const actual = PATH_RANK[observation.observed_delivery_path];
+  const target = PATH_RANK[expected];
+  if (actual === undefined || target === undefined) return "ambiguous";
+  if (actual === target) return "correct";
+  return actual < target ? "under_governance" : "over_governance";
+}
+export function classifyStagedPath(expected, observation) {
+  const legacy = classifyObservation(expected, observation);
+  return {
+    correct: "path_correct",
+    under_governance: "path_under_governance",
+    over_governance: "path_over_governance",
+    ambiguous: "path_ambiguous",
+  }[legacy];
+}
+export function classifyStage(expected, observation) {
+  if (observation.stage_evaluability !== "evaluated" || observation.observed_next_permissible_stage === null) return "stage_ambiguous";
+  const actual = observation.observed_next_permissible_stage;
+  if (!STAGES.includes(actual) || !STAGES.includes(expected)) return "stage_ambiguous";
+  if (actual === expected) return "stage_correct";
+  if (expected === "blocked") return "stage_unsafe_advance";
+  if (actual === "blocked") return "stage_over_governance";
+  if (expected === "ungated_execution") return "stage_over_governance";
+  if (actual === "ungated_execution") return "stage_unsafe_advance";
+  return STAGES.indexOf(actual) > STAGES.indexOf(expected) ? "stage_unsafe_advance" : "stage_over_governance";
+}
+function stagedCoverageResult(expected, rows, reason) {
+  return {
+    scenario_id: expected.scenario_id,
+    case_id: expected.case_id,
+    expected_next_permissible_stage: expected.expected_next_permissible_stage,
+    expected_delivery_path: expected.expected_delivery_path,
+    stage_required: expected.stage_required,
+    path_required: expected.path_required,
+    observations: rows,
+    stage_distribution: {},
+    path_distribution: {},
+    consensus_stage: null,
+    consensus_delivery_path: null,
+    stage_classifications: [],
+    path_classifications: [],
+    status: "block",
+    blocking_reasons: [reason],
+  };
+}
+function evaluateStagedSeries({ repoRoot, corpus, observations, minimumRepeats }) {
+  const provenanceKeys = ["series_id", "profile_id", "protocol_version", "corpus_version", "fixture_version", "surface", "runtime_version", "model", "agdf_version", "baseline_version", "adapter_version"];
+  const first = observations[0] ?? {};
+  const observationIds = new Set();
+  const byScenario = new Map(corpus.cases.map((item) => [item.scenario_id, []]));
+  for (const observation of observations) {
+    if (!byScenario.has(observation.scenario_id) || observation.case_id !== observation.scenario_id.split(":")[0]) fail(`unknown staged observation ${observation.scenario_id ?? "unknown"}`);
+    if (observation.schema_version !== "2" || observation.evidence_kind !== "live_agent_observation" || !Number.isInteger(observation.repeat) || observation.repeat < 1) fail(`invalid observation ${observation.observation_id ?? "unknown"}`);
+    if (!observation.observation_id || observationIds.has(observation.observation_id)) fail(`duplicate observation ${observation.observation_id ?? "unknown"}`);
+    if (observation.execution_status !== "completed" || observation.redaction_status !== "pass" || observation.mutation_status !== "pass") fail(`unsafe observation status ${observation.observation_id}`);
+    if (!Number.isFinite(Date.parse(observation.recorded_at))) fail(`invalid observation timestamp ${observation.observation_id}`);
+    if (
+      observation.baseline_version !== corpus.baseline.baseline_version
+      || observation.corpus_version !== corpus.manifest.corpus_version
+      || observation.fixture_version !== corpus.manifest.fixture_version
+    ) fail(`baseline provenance drift at ${observation.observation_id}`);
+    if (provenanceKeys.some((key) => observation[key] !== first[key])) fail(`series provenance drift at ${observation.observation_id}`);
+    observationIds.add(observation.observation_id);
+    byScenario.get(observation.scenario_id).push(observation);
+  }
+  const scenarios = corpus.baseline.scenarios.map((expected) => {
+    const blind = corpus.cases.find((item) => item.scenario_id === expected.scenario_id);
+    const rows = byScenario.get(expected.scenario_id).sort((a, b) => a.repeat - b.repeat);
+    const repeats = new Set(rows.map((item) => item.repeat));
+    if (rows.length < minimumRepeats || repeats.size !== rows.length) return stagedCoverageResult(expected, rows, "coverage");
+    const fingerprint = sourceFingerprint(repoRoot, blind, corpus.fixtures, STAGED_ADAPTER_VERSION);
+    const stale = rows.some((item) => item.source_fingerprint !== fingerprint);
+    const invalidAxes = rows.some((item) => (
+      expected.stage_required !== (item.stage_evaluability === "evaluated")
+      || expected.path_required !== (item.path_evaluability === "evaluated")
+      || (expected.stage_required ? item.observed_next_permissible_stage === null : item.observed_next_permissible_stage !== null)
+      || (expected.path_required ? item.observed_delivery_path === null : item.observed_delivery_path !== null)
+    ));
+    const stageClassifications = expected.stage_required ? rows.map((item) => classifyStage(expected.expected_next_permissible_stage, item)) : [];
+    const pathClassifications = expected.path_required ? rows.map((item) => classifyStagedPath(expected.expected_delivery_path, { ...item, ambiguous: item.path_evaluability !== "evaluated" })) : [];
+    const stageValues = new Set(rows.map((item) => item.observed_next_permissible_stage));
+    const pathValues = new Set(rows.map((item) => item.observed_delivery_path));
+    const consensusStage = expected.stage_required && !stale && !invalidAxes && stageValues.size === 1 ? rows[0].observed_next_permissible_stage : null;
+    const consensusPath = expected.path_required && !stale && !invalidAxes && pathValues.size === 1 ? rows[0].observed_delivery_path : null;
+    const blocking = [];
+    if (stale) blocking.push("stale");
+    if (invalidAxes) blocking.push("axis_contract");
+    if (expected.stage_required && !consensusStage) blocking.push("mixed_or_ambiguous_stage");
+    if (expected.path_required && !consensusPath) blocking.push("mixed_or_ambiguous_path");
+    if (stageClassifications.includes("stage_unsafe_advance")) blocking.push("critical_stage_under_governance");
+    if (pathClassifications.includes("path_under_governance")) blocking.push("critical_path_under_governance");
+    if (stageClassifications.some((item) => item !== "stage_correct")) blocking.push("stage_deviation");
+    const deviations = pathClassifications.filter((item) => item !== "path_correct");
+    return {
+      scenario_id: expected.scenario_id,
+      case_id: expected.case_id,
+      lifecycle_stage: blind.lifecycle_stage,
+      expected_next_permissible_stage: expected.expected_next_permissible_stage,
+      expected_delivery_path: expected.expected_delivery_path,
+      stage_required: expected.stage_required,
+      path_required: expected.path_required,
+      observations: rows,
+      stage_distribution: Object.fromEntries(STAGES.map((stage) => [stage, rows.filter((item) => item.observed_next_permissible_stage === stage).length]).filter(([, count]) => count)),
+      path_distribution: Object.fromEntries(DELIVERY_PATHS.map((path) => [path, rows.filter((item) => item.observed_delivery_path === path).length]).filter(([, count]) => count)),
+      stage_classifications: stageClassifications,
+      path_classifications: pathClassifications,
+      consensus_stage: consensusStage,
+      consensus_delivery_path: consensusPath,
+      status: blocking.length ? "block" : deviations.length ? "deviation" : "correct",
+      blocking_reasons: blocking,
+    };
+  });
+  const criticalUnder = scenarios.filter((item) => item.blocking_reasons.some((reason) => reason.startsWith("critical_"))).map((item) => item.scenario_id);
+  const ambiguous = scenarios.filter((item) => item.blocking_reasons.some((reason) => ["coverage", "stale", "axis_contract", "mixed_or_ambiguous_stage", "mixed_or_ambiguous_path"].includes(reason))).map((item) => item.scenario_id);
+  const stageDeviations = scenarios.filter((item) => item.stage_classifications.some((classification) => classification !== "stage_correct")).map((item) => item.scenario_id);
+  const over = scenarios.filter((item) => item.path_classifications.includes("path_over_governance")).map((item) => item.scenario_id);
+  const smallScenarios = scenarios.filter((item) => item.path_required && ["trivial_change", "quick_task"].includes(item.expected_delivery_path));
+  const smallOver = smallScenarios.filter((item) => item.path_classifications.length && item.path_classifications.every((classification) => classification === "path_over_governance")).map((item) => item.scenario_id);
+  const smallOverPercent = smallScenarios.length ? smallOver.length / smallScenarios.length * 100 : 0;
+  const thresholdBlocks = [
+    ...(criticalUnder.length ? ["critical_under_governance"] : []),
+    ...(stageDeviations.length ? ["stage_deviation"] : []),
+    ...(smallOverPercent > corpus.baseline.constraints.over_governance_threshold_percent ? ["small_segment_over_governance"] : []),
+    ...(ambiguous.length ? ["ambiguous_or_incomplete"] : []),
+  ];
+  return stable({
+    schema_version: "2",
+    profile_id: "staged-v2",
+    protocol_version: "2",
+    evidence_boundary: corpus.manifest.evidence_boundary,
+    baseline_version: corpus.baseline.baseline_version,
+    corpus_version: corpus.manifest.corpus_version,
+    series_id: first.series_id ?? null,
+    surface: first.surface ?? null,
+    model: first.model ?? null,
+    agdf_version: first.agdf_version ?? null,
+    adapter_version: first.adapter_version ?? null,
+    runtime_version: first.runtime_version ?? null,
+    runner_version: "2.0.0",
+    freshness_status: scenarios.some((item) => item.blocking_reasons.includes("stale")) ? "stale" : "fresh",
+    minimum_repeats: minimumRepeats,
+    valid_observations: observations.length,
+    case_count: corpus.baseline.cases.length,
+    scenario_count: scenarios.length,
+    stage_scenario_count: scenarios.filter((item) => item.stage_required).length,
+    path_scenario_count: scenarios.filter((item) => item.path_required).length,
+    critical_under_governance_ids: criticalUnder,
+    stage_deviation_ids: stageDeviations,
+    over_governance_ids: over,
+    small_segment_denominator: smallScenarios.length,
+    small_segment_over_governance_ids: smallOver,
+    small_segment_over_governance_percent: smallOverPercent,
+    ambiguous_ids: ambiguous,
+    blocking_reasons: thresholdBlocks,
+    status: thresholdBlocks.length ? "block" : "pass",
+    scenarios,
+  });
+}
+export function evaluateSeries({ repoRoot, corpus, observations, minimumRepeats = 3 }) {
+  if (!Number.isInteger(minimumRepeats) || minimumRepeats < 3) fail("minimum repeats must be at least 3");
+  if (corpus.profile_id === "staged-v2") return evaluateStagedSeries({ repoRoot, corpus, observations, minimumRepeats });
+  const provenanceKeys = ["series_id", "surface", "runtime_version", "model", "agdf_version", "baseline_version", "adapter_version"];
+  const first = observations[0] ?? {};
+  const observationIds = new Set();
+  const byCase = new Map(corpus.cases.map((item) => [item.case_id, []]));
+  for (const observation of observations) {
+    if (!byCase.has(observation.case_id)) fail(`unknown observation case ${observation.case_id}`);
+    if (observation.evidence_kind !== "live_agent_observation" || !Number.isInteger(observation.repeat) || observation.repeat < 1) fail(`invalid observation ${observation.observation_id ?? "unknown"}`);
+    if (!observation.observation_id || observationIds.has(observation.observation_id)) fail(`duplicate observation ${observation.observation_id ?? "unknown"}`);
+    if (observation.execution_status !== "completed" || observation.redaction_status !== "pass" || observation.mutation_status !== "pass") fail(`unsafe observation status ${observation.observation_id}`);
+    if (!Number.isFinite(Date.parse(observation.recorded_at))) fail(`invalid observation timestamp ${observation.observation_id}`);
+    if (observation.baseline_version !== corpus.baseline.baseline_version) fail(`baseline provenance drift at ${observation.observation_id}`);
+    if (provenanceKeys.some((key) => observation[key] !== first[key])) fail(`series provenance drift at ${observation.observation_id}`);
+    observationIds.add(observation.observation_id);
+    byCase.get(observation.case_id).push(observation);
+  }
+  const fixture = corpus.fixtures.fixtures[corpus.manifest.fixture_id];
+  const cases = corpus.baseline.cases.map((expected) => {
+    const blind = corpus.cases.find((item) => item.case_id === expected.case_id);
+    const rows = byCase.get(expected.case_id).sort((a, b) => a.repeat - b.repeat);
+    const repeats = new Set(rows.map((item) => item.repeat));
+    if (rows.length < minimumRepeats || repeats.size !== rows.length) {
+      return { case_id: expected.case_id, expected_delivery_path: expected.expected_delivery_path, observations: rows, distribution: {}, consensus_delivery_path: null, status: "ambiguous", classifications: [], blocking_reasons: ["coverage"] };
+    }
+    const historicalFingerprint = corpus.provenance?.source_fingerprints?.[expected.case_id];
+    const currentFingerprint = historicalFingerprint ?? sourceFingerprint(repoRoot, blind, fixture, ADAPTER_VERSION);
+    const stale = rows.some((item) => item.source_fingerprint !== currentFingerprint);
+    const classifications = rows.map((item) => classifyObservation(expected.expected_delivery_path, item));
+    const distribution = Object.fromEntries(DELIVERY_PATHS.map((path) => [path, rows.filter((item) => item.observed_delivery_path === path).length]).filter(([, count]) => count));
+    const paths = new Set(rows.map((item) => item.observed_delivery_path));
+    const consensus = !stale && !rows.some((item) => item.ambiguous) && paths.size === 1 ? rows[0].observed_delivery_path : null;
+    const blocking = [];
+    if (stale) blocking.push("stale");
+    if (!consensus) blocking.push("mixed_or_ambiguous");
+    if (classifications.includes("under_governance")) blocking.push("critical_under_governance");
+    return {
+      case_id: expected.case_id,
+      expected_delivery_path: expected.expected_delivery_path,
+      adversarial: expected.adversarial,
+      observations: rows,
+      distribution,
+      classifications,
+      consensus_delivery_path: consensus,
+      status: blocking.length ? "block" : classifications.every((item) => item === "correct") ? "correct" : "over_governance",
+      blocking_reasons: blocking,
+    };
+  });
+  const smallCases = cases.filter((item) => ["trivial_change", "quick_task"].includes(item.expected_delivery_path));
+  const unanimousOverSmall = smallCases.filter((item) => item.consensus_delivery_path && item.classifications.every((value) => value === "over_governance")).length;
+  const smallOverRate = unanimousOverSmall / smallCases.length * 100;
+  const criticalUnderIds = cases.filter((item) => item.classifications.includes("under_governance")).map((item) => item.case_id);
+  const ambiguousIds = cases.filter((item) => item.blocking_reasons.some((item) => ["coverage", "stale", "mixed_or_ambiguous"].includes(item))).map((item) => item.case_id);
+  const thresholdBlocks = [
+    ...(criticalUnderIds.length ? ["critical_under_governance"] : []),
+    ...(smallOverRate > corpus.baseline.constraints.over_governance_threshold_percent ? ["small_segment_over_governance"] : []),
+    ...(ambiguousIds.length ? ["ambiguous_or_incomplete"] : []),
+  ];
+  return stable({
+    schema_version: "1",
+    evidence_boundary: "live routing observations with deterministic offline grading",
+    baseline_version: corpus.baseline.baseline_version,
+    corpus_version: corpus.manifest.corpus_version,
+    series_id: first.series_id ?? null,
+    surface: first.surface ?? null,
+    model: first.model ?? null,
+    agdf_version: first.agdf_version ?? null,
+    adapter_version: first.adapter_version ?? null,
+    runtime_version: first.runtime_version ?? null,
+    runner_version: "1.0.0",
+    freshness_status: cases.some((item) => item.blocking_reasons.includes("stale")) ? "stale" : corpus.provenance ? "historical" : "fresh",
+    minimum_repeats: minimumRepeats,
+    valid_observations: observations.length,
+    case_count: cases.length,
+    adversarial_case_count: cases.filter((item) => item.adversarial).length,
+    small_segment_denominator: smallCases.length,
+    unanimous_over_governance_small_cases: unanimousOverSmall,
+    small_segment_over_governance_percent: smallOverRate,
+    critical_under_governance_ids: criticalUnderIds,
+    ambiguous_ids: ambiguousIds,
+    blocking_reasons: thresholdBlocks,
+    status: thresholdBlocks.length ? "block" : "pass",
+    cases,
+  });
+}

package/lib/proportionality-benchmark/index.js

@@ -0,0 +1,7 @@
+export * from "./blind-prompt.js";
+export * from "./contracts.js";
+export * from "./corpus-loader.js";
+export * from "./evaluator.js";
+export * from "./live-recorder.js";
+export * from "./report.js";
+export * from "./source-fingerprint.js";

package/lib/proportionality-benchmark/live-recorder.js

@@ -0,0 +1,100 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { executeStructuredAgent } from "../live-agent/read-only-structured.js";
+import { changedPaths, snapshotWorkspace } from "../skill-evals/workspace.js";
+import { buildBlindPrompt } from "./blind-prompt.js";
+import { normalizeAgentOutput, normalizeStagedAgentOutput, OBSERVATION_SCHEMA, STAGED_OBSERVATION_SCHEMA, fail } from "./contracts.js";
+import { behaviorSourceText, sourceFingerprint } from "./source-fingerprint.js";
+
+export const ADAPTER_VERSION = "1.1.0";
+export const STAGED_ADAPTER_VERSION = "2.1.0";
+function runtimeVersion(surface) {
+  try { return execFileSync(surface, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); }
+  catch { return `${surface} version unavailable`; }
+}
+export function persistObservation(path, observation, { replace = false } = {}) {
+  let previous;
+  try { previous = JSON.parse(readFileSync(path, "utf8")); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  if (previous && !replace) {
+    fail(`observation already exists: ${path}`, "PROPORTIONALITY_DUPLICATE");
+  }
+  const persisted = previous ? {
+    ...observation,
+    replacement_provenance: {
+      previous_observation_id: previous.observation_id ?? null,
+      previous_recorded_at: previous.recorded_at ?? null,
+      replaced_at: new Date().toISOString(),
+    },
+  } : observation;
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(persisted, null, 2)}\n`, "utf8");
+  renameSync(temp, path);
+}
+export async function recordObservation({
+  repoRoot, testCase, fixture, seriesId, repeat, surface, model, agdfVersion, baselineVersion,
+  timeoutMs = 120000, execute = executeStructuredAgent, persistPath, replace = false,
+}) {
+  if (!/^[a-z0-9][a-z0-9._-]{2,79}$/i.test(seriesId) || !Number.isInteger(repeat) || repeat < 1) fail("invalid series or repeat");
+  if (!surface || !model || !agdfVersion || !baselineVersion) fail("surface, model, AGDF version and baseline version are required");
+  const staged = testCase.profile_id === "staged-v2";
+  const adapterVersion = staged ? STAGED_ADAPTER_VERSION : ADAPTER_VERSION;
+  const fingerprint = sourceFingerprint(repoRoot, testCase, fixture, adapterVersion);
+  const fixtureRoot = mkdtempSync(join(tmpdir(), "agdf-proportionality-"));
+  let output;
+  let executionError;
+  try {
+    writeFileSync(join(fixtureRoot, "TASK.md"), `${testCase.task_summary}\n`, "utf8");
+    writeFileSync(join(fixtureRoot, "CONTEXT.json"), `${JSON.stringify({
+      repository_context: testCase.repository_context,
+      control_state_context: testCase.control_state_context,
+    }, null, 2)}\n`, "utf8");
+    const before = snapshotWorkspace(fixtureRoot);
+    try {
+      output = await execute({
+        surface, cwd: fixtureRoot, model, timeoutMs, outputSchema: staged ? STAGED_OBSERVATION_SCHEMA : OBSERVATION_SCHEMA,
+        prompt: buildBlindPrompt(testCase, behaviorSourceText(repoRoot)),
+      });
+    } catch (error) { executionError = error; }
+    const after = snapshotWorkspace(fixtureRoot);
+    const mutations = changedPaths(before, after);
+    if (mutations.length) fail(`agent mutated fixture: ${mutations.join(", ")}`, "PROPORTIONALITY_MUTATION");
+    if (executionError) throw executionError;
+    const normalized = staged ? normalizeStagedAgentOutput(output, testCase.requested_axes) : normalizeAgentOutput(output);
+    const observation = {
+      schema_version: staged ? "2" : "1",
+      observation_id: `${seriesId}:${staged ? testCase.scenario_id : testCase.case_id}:${repeat}`,
+      case_id: testCase.case_id,
+      ...(staged ? {
+        profile_id: "staged-v2",
+        protocol_version: "2",
+        corpus_version: testCase.corpus_version,
+        fixture_version: testCase.fixture_version,
+        scenario_id: testCase.scenario_id,
+        lifecycle_stage: testCase.lifecycle_stage,
+      } : {}),
+      series_id: seriesId,
+      repeat,
+      evidence_kind: "live_agent_observation",
+      surface,
+      runtime_version: runtimeVersion(surface),
+      agdf_version: agdfVersion,
+      baseline_version: baselineVersion,
+      model,
+      adapter_version: adapterVersion,
+      source_fingerprint: fingerprint,
+      recorded_at: new Date().toISOString(),
+      ...normalized,
+      execution_status: "completed",
+      redaction_status: "pass",
+      mutation_status: "pass",
+    };
+    if (persistPath) persistObservation(persistPath, observation, { replace });
+    return observation;
+  } finally {
+    rmSync(fixtureRoot, { recursive: true, force: true });
+  }
+}

package/lib/proportionality-benchmark/report.js

@@ -0,0 +1,51 @@
+export function renderMarkdown(report) {
+  if (report.profile_id === "staged-v2") {
+    const lines = [
+      "# AGDF Staged Proportionality Observation",
+      "",
+      `- Status: \`${report.status}\``,
+      `- Evidenzgrenze: ${report.evidence_boundary}`,
+      `- Profil/Protokoll: \`${report.profile_id}\` / \`${report.protocol_version}\``,
+      `- Serie: \`${report.series_id ?? "none"}\``,
+      `- Surface/Modell: \`${report.surface ?? "none"}\` / \`${report.model ?? "none"}\``,
+      `- Runtime/AGDF/Adapter/Runner: \`${report.runtime_version ?? "none"}\` / \`${report.agdf_version ?? "none"}\` / \`${report.adapter_version ?? "none"}\` / \`${report.runner_version}\``,
+      `- Freshness: \`${report.freshness_status}\``,
+      `- Beobachtungen: ${report.valid_observations}`,
+      `- Coverage: ${report.scenarios.filter((item) => !item.blocking_reasons.includes("coverage")).length}/${report.scenario_count} Szenarien aus ${report.case_count} Fällen`,
+      `- Stage-/Pfad-Szenarien: ${report.stage_scenario_count}/${report.path_scenario_count}`,
+      `- Kritische Under-Governance: ${report.critical_under_governance_ids.length}`,
+      `- Stage-Abweichungen: ${report.stage_deviation_ids.length}`,
+      `- Pfad-Over-Governance: ${report.over_governance_ids.length}`,
+      `- Small-Segment Over-Governance: ${report.small_segment_over_governance_ids.length}/${report.small_segment_denominator} (${report.small_segment_over_governance_percent} %)`,
+      `- Ambiguous/Stale/Incomplete: ${report.ambiguous_ids.length}`,
+      "",
+      "| Szenario | Lifecycle | Soll-Stage | Stage-Konsens | Soll-Pfad | Pfad-Konsens | Status |",
+      "|---|---|---|---|---|---|---|",
+    ];
+    for (const item of report.scenarios) lines.push(`| ${item.scenario_id} | ${item.lifecycle_stage} | ${item.expected_next_permissible_stage ?? "n/a"} | ${item.consensus_stage ?? "n/a"} | ${item.expected_delivery_path ?? "n/a"} | ${item.consensus_delivery_path ?? "n/a"} | ${item.status} |`);
+    return `${lines.join("\n")}\n`;
+  }
+  const lines = [
+    "# AGDF Proportionality Benchmark",
+    "",
+    `- Status: \`${report.status}\``,
+    `- Evidenzgrenze: ${report.evidence_boundary}`,
+    `- Serie: \`${report.series_id ?? "none"}\``,
+    `- Surface/Modell: \`${report.surface ?? "none"}\` / \`${report.model ?? "none"}\``,
+    `- Runtime/AGDF/Adapter/Runner: \`${report.runtime_version ?? "none"}\` / \`${report.agdf_version ?? "none"}\` / \`${report.adapter_version ?? "none"}\` / \`${report.runner_version}\``,
+    `- Freshness: \`${report.freshness_status}\``,
+    `- Beobachtungen: ${report.valid_observations}`,
+    `- Coverage: ${report.cases.filter((item) => !item.blocking_reasons.includes("coverage")).length}/${report.case_count}`,
+    `- Kritische Under-Governance: ${report.critical_under_governance_ids.length}`,
+    `- Small-Segment Over-Governance: ${report.unanimous_over_governance_small_cases}/${report.small_segment_denominator} (${report.small_segment_over_governance_percent} %)`,
+    `- Ambiguous/Stale/Incomplete: ${report.ambiguous_ids.length}`,
+    "",
+    "| Case | Soll | Verteilung | Konsens | Status |",
+    "|---|---|---|---|---|",
+  ];
+  for (const item of report.cases) {
+    const distribution = Object.entries(item.distribution).map(([path, count]) => `${path}:${count}`).join(", ") || "none";
+    lines.push(`| ${item.case_id} | ${item.expected_delivery_path} | ${distribution} | ${item.consensus_delivery_path ?? "none"} | ${item.status} |`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/lib/proportionality-benchmark/source-fingerprint.js

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { stable } from "./contracts.js";
+
+export const BEHAVIOR_SOURCES = Object.freeze([
+  "plugin/meta/agdf-agent-router.md",
+  "plugin/meta/contracts/modes.md",
+  "plugin/meta/contracts/gate-transition.md",
+  "plugin/meta/contracts/interaction.md",
+  "plugin/skills/gate-check/SKILL.md",
+]);
+export const IMPLEMENTATION_SOURCES = Object.freeze([
+  "create-agdf/lib/live-agent/read-only-structured.js",
+  "create-agdf/lib/proportionality-benchmark/blind-prompt.js",
+  "create-agdf/lib/proportionality-benchmark/contracts.js",
+  "create-agdf/lib/proportionality-benchmark/corpus-loader.js",
+  "create-agdf/lib/proportionality-benchmark/evaluator.js",
+  "create-agdf/lib/proportionality-benchmark/live-recorder.js",
+  "create-agdf/lib/proportionality-benchmark/source-fingerprint.js",
+]);
+export function behaviorSourceText(repoRoot) {
+  return BEHAVIOR_SOURCES.map((path) => `--- ${path} ---\n${readFileSync(join(repoRoot, path), "utf8")}`).join("\n\n");
+}
+export function sourceFingerprint(repoRoot, testCase, fixture, adapterVersion) {
+  const hash = createHash("sha256");
+  hash.update(JSON.stringify(stable({ testCase, fixture, adapterVersion })));
+  for (const path of [...BEHAVIOR_SOURCES, ...IMPLEMENTATION_SOURCES]) hash.update(path).update(readFileSync(join(repoRoot, path)));
+  return hash.digest("hex");
+}

package/lib/public-plugin/builder.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { assertPublicPluginContract, loadJson } from "./contract.js";
+import { renderCodexPluginManifest } from "./manifest.js";
+import { createReadinessReport, renderReadinessReport } from "./report.js";
+import { inventory, validateCandidate } from "./validator.js";
+
+function write(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+}
+
+function json(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+export function buildPublicPluginCandidate({ repoRoot, outputRoot }) {
+  repoRoot = resolve(repoRoot);
+  outputRoot = resolve(outputRoot);
+  const expectedParent = resolve(repoRoot, "create-agdf", "generated", "submissions", "openai");
+  if (dirname(outputRoot) !== expectedParent) throw new Error(`Public candidate output must be a direct child of ${expectedParent}`);
+  mkdirSync(expectedParent, { recursive: true });
+  const temporaryRoot = mkdtempSync(join(expectedParent, ".agdf-build-"));
+  try {
+    const pluginRoot = join(repoRoot, "plugin");
+    const definition = loadJson(join(pluginRoot, "meta", "agdf-plugin.definition.json"));
+    const capabilityMatrix = loadJson(join(pluginRoot, "submission", "openai", "capability-matrix.json"));
+    const reviewerCases = loadJson(join(pluginRoot, "submission", "openai", "reviewer-cases.json"));
+    const releaseNotes = readFileSync(join(pluginRoot, "submission", "openai", "release-notes.md"), "utf8");
+    assertPublicPluginContract({ definition, capabilityMatrix, reviewerCases, releaseNotes });
+
+    write(join(temporaryRoot, ".codex-plugin", "plugin.json"), renderCodexPluginManifest(definition, { publicCandidate: true }));
+    for (const directory of ["skills", "meta", "assets"]) cpSync(join(pluginRoot, directory), join(temporaryRoot, directory), { recursive: true });
+    cpSync(join(pluginRoot, "submission", "openai"), join(temporaryRoot, "submission", "openai"), { recursive: true });
+    const listing = {
+      schemaVersion: 1,
+      releaseVersion: definition.version,
+      submissionType: definition.publicDistribution.submissionType,
+      identity: {
+        technicalId: definition.publicDistribution.technicalId,
+        publicDisplayName: definition.publicDistribution.publicDisplayName,
+        fullDisplayName: definition.publicDistribution.fullDisplayName,
+      },
+      interface: {
+        shortDescription: definition.publicDistribution.shortDescription,
+        longDescription: definition.longDescription,
+        developerName: definition.publicDistribution.developerName,
+        category: definition.publicDistribution.category,
+        defaultPrompt: definition.publicDistribution.defaultPrompt,
+      },
+      publisher: definition.publicDistribution.publisher,
+      urls: definition.publicDistribution.urls,
+      availability: definition.publicDistribution.availability,
+    };
+    write(join(temporaryRoot, "submission", "openai", "listing.json"), json(listing));
+    validateCandidate(temporaryRoot);
+    const entries = inventory(temporaryRoot, { exclude: ["submission/openai/inventory.json", "submission/openai/readiness.json"] });
+    const digest = createHash("sha256").update(json(entries)).digest("hex");
+    write(join(temporaryRoot, "submission", "openai", "inventory.json"), json({ schemaVersion: 1, releaseVersion: definition.version, digest, files: entries }));
+    const report = createReadinessReport({ definition, fileCount: entries.length, inventoryDigest: digest });
+    write(join(temporaryRoot, "submission", "openai", "readiness.json"), json(report));
+    write(join(temporaryRoot, "submission", "openai", "readiness.md"), renderReadinessReport(report));
+    validateCandidate(temporaryRoot);
+
+    const backupRoot = `${outputRoot}.previous`;
+    if (existsSync(backupRoot)) throw new Error(`Refusing candidate swap while recovery backup exists: ${backupRoot}`);
+    const hadPrevious = existsSync(outputRoot);
+    if (hadPrevious) renameSync(outputRoot, backupRoot);
+    try {
+      renameSync(temporaryRoot, outputRoot);
+    } catch (error) {
+      if (hadPrevious && existsSync(backupRoot) && !existsSync(outputRoot)) renameSync(backupRoot, outputRoot);
+      throw error;
+    }
+    if (hadPrevious) rmSync(backupRoot, { recursive: true, force: true });
+    return { outputRoot, digest, fileCount: entries.length, report };
+  } catch (error) {
+    rmSync(temporaryRoot, { recursive: true, force: true });
+    throw error;
+  }
+}

package/lib/public-plugin/contract.js

@@ -0,0 +1,102 @@
+import { readFileSync } from "node:fs";
+
+export const LISTING_LIMITS = Object.freeze({
+  displayName: 30,
+  shortDescription: 30,
+  developerName: 80,
+  promptCount: 3,
+  promptLength: 128,
+});
+
+export function unicodeLength(value) {
+  return [...String(value)].length;
+}
+
+function requiredString(value, label, errors) {
+  if (typeof value !== "string" || value.trim() === "") errors.push(`${label} is required`);
+}
+
+function within(value, limit, label, errors) {
+  requiredString(value, label, errors);
+  if (typeof value === "string" && unicodeLength(value) > limit) {
+    errors.push(`${label} exceeds ${limit} Unicode code points`);
+  }
+}
+
+export function loadJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+export function validatePublicPluginContract({ definition, capabilityMatrix, reviewerCases, releaseNotes }) {
+  const errors = [];
+  const contract = definition?.publicDistribution;
+  if (contract?.schemaVersion !== 1) errors.push("publicDistribution.schemaVersion must be 1");
+  if (contract?.submissionType !== "skills") errors.push("submissionType must be skills");
+  if (contract?.technicalId !== definition?.id) errors.push("technicalId must match canonical plugin id");
+  if (contract?.developerName !== definition?.developerName) errors.push("developerName must match canonical developerName");
+  if (contract?.category !== definition?.category) errors.push("category must match canonical category");
+  within(contract?.publicDisplayName, LISTING_LIMITS.displayName, "publicDisplayName", errors);
+  within(contract?.shortDescription, LISTING_LIMITS.shortDescription, "shortDescription", errors);
+  within(contract?.developerName, LISTING_LIMITS.developerName, "developerName", errors);
+  requiredString(contract?.fullDisplayName, "fullDisplayName", errors);
+  requiredString(definition?.longDescription, "longDescription", errors);
+  if (Object.hasOwn(contract ?? {}, "longDescription")) {
+    errors.push("publicDistribution.longDescription must use canonical longDescription");
+  }
+  if (contract?.fullDisplayName !== `${definition?.displayName} (${contract?.publicDisplayName})`) {
+    errors.push("fullDisplayName must combine canonical displayName and publicDisplayName");
+  }
+
+  const prompts = contract?.defaultPrompt;
+  if (!Array.isArray(prompts) || prompts.length !== LISTING_LIMITS.promptCount) {
+    errors.push(`defaultPrompt must contain exactly ${LISTING_LIMITS.promptCount} prompts`);
+  } else {
+    prompts.forEach((prompt, index) => within(prompt, LISTING_LIMITS.promptLength, `defaultPrompt[${index}]`, errors));
+  }
+  for (const [name, value] of Object.entries(contract?.urls ?? {})) {
+    try {
+      const url = new URL(value);
+      if (url.protocol !== "https:") errors.push(`${name} URL must use HTTPS`);
+    } catch {
+      errors.push(`${name} URL is invalid`);
+    }
+  }
+  for (const name of ["website", "privacy", "terms", "support"]) {
+    if (!contract?.urls?.[name]) errors.push(`${name} URL is required`);
+  }
+  if (contract?.publisher?.verificationState !== "unverified") {
+    errors.push("publisher verificationState must remain unverified without portal evidence");
+  }
+  if (!contract?.availability || !Array.isArray(contract.availability.countries) || !Array.isArray(contract.availability.regions) || !Array.isArray(contract.availability.workspaceContexts)) {
+    errors.push("availability decision record is incomplete");
+  }
+
+  const allowedStates = new Set(["common", "codex-specific", "chatgpt-specific", "advisory", "unavailable", "unverified"]);
+  if (capabilityMatrix?.releaseVersion !== definition?.version) errors.push("capability matrix version must match definition");
+  if (!Array.isArray(capabilityMatrix?.capabilities) || capabilityMatrix.capabilities.length === 0) errors.push("capability matrix is empty");
+  for (const capability of capabilityMatrix?.capabilities ?? []) {
+    if (!allowedStates.has(capability.state)) errors.push(`capability ${capability.id ?? "unknown"} has invalid state`);
+    requiredString(capability.evidenceClass, `capability ${capability.id} evidenceClass`, errors);
+    requiredString(capability.evidenceRef, `capability ${capability.id} evidenceRef`, errors);
+  }
+
+  if (reviewerCases?.releaseVersion !== definition?.version) errors.push("reviewer cases version must match definition");
+  const cases = reviewerCases?.cases ?? [];
+  if (cases.filter((entry) => entry.kind === "positive").length < 5) errors.push("at least five positive reviewer cases are required");
+  if (cases.filter((entry) => entry.kind === "negative").length < 3) errors.push("at least three negative reviewer cases are required");
+  for (const entry of cases) {
+    for (const field of ["id", "kind", "theme", "prompt", "expectedWorkflow", "expectedResult"]) requiredString(entry[field], `${entry.id ?? "case"}.${field}`, errors);
+    if (!Array.isArray(entry.prerequisites)) errors.push(`${entry.id}.prerequisites must be an array`);
+  }
+  for (const theme of ["missing-approval", "disproportionate-fit", "unavailable-repository-authority", "unsupported-host-capability", "unauthorized-external-action"]) {
+    if (!cases.some((entry) => entry.kind === "negative" && entry.theme === theme)) errors.push(`negative reviewer theme ${theme} is required`);
+  }
+  requiredString(releaseNotes, "releaseNotes", errors);
+  if (typeof releaseNotes === "string" && !releaseNotes.includes(definition?.version)) errors.push("release notes must contain exact version");
+  return errors;
+}
+
+export function assertPublicPluginContract(inputs) {
+  const errors = validatePublicPluginContract(inputs);
+  if (errors.length) throw new Error(`AGDF_PUBLIC_PLUGIN_CONTRACT_INVALID: ${errors.join("; ")}`);
+}