owlrunkit 0.18.2 → 0.18.3

package/scripts/runkit-contract/quick-verify.mjs

@@ -1,10 +1,18 @@
 import { spawn } from "node:child_process";
-import { realpathSync } from "node:fs";
+import {
+  closeSync,
+  constants,
+  openSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
 
+import { readFileBytesBounded } from "../../packages/attest/src/formal.mjs";
 import { currentCoreIdentity } from "./core-contract.mjs";
 import {
   closeQuickOutputFiles,
   createQuickReceiptStore,
+  persistQuickInputArtifact,
   persistQuickReceipt,
 } from "./quick-receipt.mjs";
 import { captureWorkspaceSnapshot } from "./quick-workspace-snapshot.mjs";
@@ -17,15 +25,31 @@ function quickAttestCommand(workspaceRoot, receiptPath) {
   return `owlrunkit quick-attest --workspace ${shellQuote(workspaceRoot)} --receipt ${shellQuote(receiptPath)}`;
 }
 
-function runExactCommand({ executable, argv, cwd, stdoutFd, stderrFd }) {
+function runExactCommand({ executable, argv, cwd, stdinPath, stdoutFd, stderrFd }) {
   return new Promise((resolve) => {
     let settled = false;
-    const child = spawn(executable, argv, {
-      cwd,
-      shell: false,
-      stdio: ["ignore", stdoutFd, stderrFd],
-      env: process.env,
-    });
+    let stdinFd;
+    let child;
+    try {
+      stdinFd = stdinPath === undefined
+        ? undefined
+        : openSync(stdinPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+      child = spawn(executable, argv, {
+        cwd,
+        shell: false,
+        stdio: [stdinFd ?? "ignore", stdoutFd, stderrFd],
+        env: process.env,
+      });
+    } catch (error) {
+      if (stdinFd !== undefined) closeSync(stdinFd);
+      resolve({
+        exitCode: null,
+        signal: null,
+        launchError: error instanceof Error ? error.message : String(error),
+      });
+      return;
+    }
+    if (stdinFd !== undefined) closeSync(stdinFd);
     child.once("error", (error) => {
       if (settled) return;
       settled = true;
@@ -39,7 +63,13 @@ function runExactCommand({ executable, argv, cwd, stdoutFd, stderrFd }) {
   });
 }
 
-export async function runQuickVerification({ workspaceRoot, commandArgv }) {
+function inputArtifactResult(stdinArtifact) {
+  return stdinArtifact === null
+    ? {}
+    : { inputArtifacts: { stdin: stdinArtifact } };
+}
+
+export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFile }) {
   if (!Array.isArray(commandArgv) || commandArgv.length === 0 || !commandArgv.every((value) => typeof value === "string")) {
     return {
       status: "quick_verification_input_invalid",
@@ -60,12 +90,49 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
     };
   }
 
+  let stdinBytes;
+  if (stdinFile !== undefined) {
+    if (typeof stdinFile !== "string" || stdinFile.length === 0) {
+      return {
+        status: "quick_verification_input_invalid",
+        exitCode: 3,
+        issues: ["--stdin-file requires a non-empty regular file path."],
+        authorizationGranted: false,
+      };
+    }
+    try {
+      const selected = path.isAbsolute(stdinFile)
+        ? stdinFile
+        : path.resolve(root, stdinFile);
+      stdinBytes = readFileBytesBounded(selected).bytes;
+    } catch (error) {
+      return {
+        status: "quick_verification_input_invalid",
+        exitCode: 3,
+        issues: [`Quick stdin file is invalid: ${error instanceof Error ? error.message : String(error)}`],
+        authorizationGranted: false,
+      };
+    }
+  }
+
   let workspaceBefore;
   let store;
+  let stdinArtifact = null;
+  let persistedStdinPath;
   try {
     workspaceBefore = captureWorkspaceSnapshot(root);
     store = createQuickReceiptStore(root);
+    if (stdinBytes !== undefined) {
+      const persistedInput = persistQuickInputArtifact({
+        workspaceRoot: root,
+        store,
+        bytes: stdinBytes,
+      });
+      stdinArtifact = persistedInput.artifact;
+      persistedStdinPath = persistedInput.inputPath;
+    }
   } catch (error) {
+    if (store !== undefined) closeQuickOutputFiles(store);
     return {
       status: "quick_verification_input_invalid",
       exitCode: 3,
@@ -80,6 +147,7 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
     executable,
     argv,
     cwd: root,
+    stdinPath: persistedStdinPath,
     stdoutFd: store.stdoutFd,
     stderrFd: store.stderrFd,
   });
@@ -101,7 +169,7 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
   }
 
   const sourceMutated = workspaceBefore.sourceFingerprint !== workspaceAfter.sourceFingerprint;
-  const issueCodes = ["quick_ignored_artifact_unbound"];
+  const issueCodes = [];
   if (sourceMutated) issueCodes.push("source_mutated_during_verification");
   let persisted;
   try {
@@ -109,7 +177,9 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
       workspaceRoot: root,
       store,
       receipt: {
-      schemaVersion: "OwlCodaQuickVerificationReceiptV1",
+      schemaVersion: stdinArtifact === null
+        ? "OwlCodaQuickVerificationReceiptV1"
+        : "OwlCodaQuickVerificationReceiptV2",
       receiptId: store.receiptId,
       assurance: "captured_verification",
       authorizationGranted: false,
@@ -124,6 +194,9 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
         argv,
         cwd: root,
       },
+      ...(stdinArtifact === null
+        ? {}
+        : { inputArtifacts: { stdin: stdinArtifact } }),
       verificationContext: {
         platform: process.platform,
         architecture: process.arch,
@@ -154,6 +227,7 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
         ? "invalidated_by_command_source_mutation"
         : "source_unchanged",
       issueCodes: [...issueCodes, "quick_receipt_store_invalid"],
+      ...inputArtifactResult(stdinArtifact),
       issues: [error instanceof Error ? error.message : String(error)],
       nextAllowedAction: "repair_quick_receipt_store_and_rerun",
       authorizationGranted: false,
@@ -173,6 +247,7 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
       commandExitCode: execution.exitCode,
       mutationDecision: "invalidated_by_command_source_mutation",
       issueCodes,
+      ...inputArtifactResult(stdinArtifact),
       outputSummary,
       attestCommand,
       issues: [],
@@ -191,6 +266,7 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
       commandExitCode: execution.exitCode,
       mutationDecision: "source_unchanged",
       issueCodes,
+      ...inputArtifactResult(stdinArtifact),
       outputSummary,
       attestCommand,
       issues: execution.launchError ? [execution.launchError] : [],
@@ -208,6 +284,7 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
     commandExitCode: 0,
     mutationDecision: "source_unchanged",
     issueCodes,
+    ...inputArtifactResult(stdinArtifact),
     outputSummary,
     attestCommand,
     issues: [],

package/scripts/runkit-contract/runkit-cli.mjs

@@ -158,6 +158,7 @@ import {
   integrateTeamProjectV1,
   openTeamProjectDecisionV1,
   readTeamProjectStatusV1,
+  rejectAndReturnTeamProjectV1,
   resolveTeamProjectDecisionV1,
 } from "./team-project.mjs";
 import {
@@ -200,7 +201,7 @@ Fleet and status
   owlrunkit fleet discover; owlrunkit status --workspace .
 
 Agent team projects
-  owlrunkit project <init|assign|checkpoint|handoff|decision|verification|capture|status|takeover|successor> [options]
+  owlrunkit project <init|assign|checkpoint|handoff|reject-and-return|decision|verification|capture|status|takeover|successor> [options]
   Durable Agent work, dependencies, decisions, gates, progress, and handoffs.
 Core successor
   owlrunkit core-successor <plan|apply|resume> --workspace . [...]
@@ -264,11 +265,20 @@ Attests one Quick Receipt against its bound materials and current workspace.
 It never grants repository or business authority.
 `,
   "quick-verify": `Usage:
-  owlrunkit quick-verify --workspace <directory> [--json] -- <executable> [args...]
+  owlrunkit quick-verify --workspace <directory> [--stdin-file <file>] [--attest] [--json]
+    -- <executable> [args...]
 
 Runs one exact command, saves source-bound stdout/stderr and a Quick receipt,
-and returns a bounded output summary. Supply the exact command after --.
+and returns a bounded head/tail output summary. --stdin-file copies and hash-binds
+up to 1 MiB of exact stdin bytes in the receipt store. --attest immediately
+attests the saved receipt without merging Quick and attestation semantics.
 Quick evidence is not Formal acceptance and grants no repository or business authority.
+`,
+  "quick-metrics": `Usage:
+  owlrunkit quick-metrics --workspace <directory> --local [--verbose] [--json]
+
+Returns aggregate local-only Quick counts with no telemetry or network access.
+--verbose additionally lists the receipt paths used for the aggregation.
 `,
   fleet: `Usage:
   owlrunkit fleet register-root --fleet-root <directory>
@@ -419,6 +429,9 @@ action without granting any authority.
   owlrunkit project handoff --workspace <directory> --handoff-id <id> --at <ISO-UTC>
     --assignment-id <current> --work-item <id> --from-agent <id> --to-agent <id>
     --summary <text> --next <text> --evidence <ref> [--evidence <ref> ...] [--json]
+  owlrunkit project reject-and-return --workspace <directory> --rework-id <id> --at <ISO-UTC>
+    --work-item <failed-id> --reviewer-agent <id> --to-agent <id>
+    --reason <text> --next <text> --evidence <ref> [--evidence <ref> ...] [--json]
   owlrunkit project decision --workspace <directory> --open --decision-id <id> --at <ISO-UTC>
     --title <text> --question <text> --owner-agent <id>
     [--blocking-work-item <id> ...] --option <text> [--option <text> ...] [--json]
@@ -459,6 +472,15 @@ No self-reported percentage is accepted.
 Measured WorkItems require --completed-units on every checkpoint. A completed
 checkpoint must use the WorkItem's declared total. Example:
   owlrunkit project checkpoint --workspace . --checkpoint-id checkpoint-x --at 2026-08-11T00:00:00.000Z --assignment-id assign-x --work-item x --state completed --summary 'Completed x.' --completed-units 5 --evidence receipt:quick
+`,
+  "project reject-and-return": `Usage:
+  owlrunkit project reject-and-return --workspace <directory> --rework-id <id> --at <ISO-UTC>
+    --work-item <failed-id> --reviewer-agent <id> --to-agent <id>
+    --reason <text> --next <text> --evidence <ref> [--evidence <ref> ...] [--json]
+
+Atomically records the rejection and opens a new assigned rework attempt. The
+failed attempt remains immutable and evidence-linked. This action does not
+grant Git, release, deployment, production, or business authority.
 `,
   "project status": `Usage:
   owlrunkit project status --workspace <directory> [--json]
@@ -536,6 +558,20 @@ function formatTeamProjectHandoffHuman(result) {
   ].join("\n");
 }
 
+function formatTeamProjectReworkHuman(result) {
+  const disposition = result.resumed ? "Resumed" : "Returned";
+  const nextAction = result.nextAction === null
+    ? "none"
+    : String(result.nextAction).replace(/\s+/gu, " ").trim();
+  return [
+    `${disposition} failed WorkItem ${result.workItemId} to Agent ${result.toAgentId} for rework attempt ${result.reworkAttempt}.`,
+    `Failed checkpoint preserved: ${result.failedCheckpointEventId}`,
+    `Next: ${nextAction}`,
+    `Rework assignment: ${result.assignmentId}`,
+    "",
+  ].join("\n");
+}
+
 function formatTeamProjectDecisionHuman(result) {
   const disposition = result.resumed
     ? "Resumed"
@@ -1923,6 +1959,8 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? ["owned-path"]
         : command === "project" && action === "handoff"
           ? ["evidence"]
+        : command === "project" && action === "reject-and-return"
+          ? ["evidence"]
         : command === "project" && action === "integrate"
           ? ["evidence"]
         : command === "project" && action === "verification"
@@ -1960,7 +1998,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? ["json", "open", "resolve"]
         : command === "project" && action === "verification"
           ? ["json", "defer", "close"]
-        : command === "project" && new Set(["assign", "handoff", "checkpoint", "integrate", "status", "takeover", "successor"]).has(action)
+        : command === "project" && new Set(["assign", "handoff", "reject-and-return", "checkpoint", "integrate", "status", "takeover", "successor"]).has(action)
           ? ["json"]
           : command === "doctor" || command === "adopt" || command === "status"
             ? ["json"]
@@ -1974,8 +2012,12 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? ["adopt-orphan-success-receipts"]
         : command === "deployment" && action === "execute"
           ? ["resume"]
-        : new Set(["quick-verify", "quick-attest", "quick-metrics"]).has(command)
-          ? ["json", "local"]
+        : command === "quick-verify"
+          ? ["json", "attest"]
+        : command === "quick-attest"
+          ? ["json"]
+        : command === "quick-metrics"
+          ? ["json", "local", "verbose"]
           : [],
     });
     if (command === "init") return await initialize(options);
@@ -2811,6 +2853,10 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           "workspace", "request", "handoff-id", "at", "assignment-id", "work-item",
           "from-agent", "to-agent", "summary", "next", "evidence", "json",
         ],
+        "reject-and-return": [
+          "workspace", "rework-id", "at", "work-item", "reviewer-agent",
+          "to-agent", "reason", "next", "evidence", "json",
+        ],
         decision: [
           "workspace", "request", "open", "resolve", "decision-id", "at", "title",
           "question", "owner-agent", "blocking-work-item", "option", "resolution",
@@ -2918,6 +2964,22 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? handedOff
           : withHumanOutput(handedOff, formatTeamProjectHandoffHuman(handedOff));
       }
+      if (action === "reject-and-return") {
+        const returned = rejectAndReturnTeamProjectV1({
+          workspaceRoot: root,
+          reworkId: requireOption(options, "rework-id"),
+          occurredAt: requireOption(options, "at"),
+          workItemId: requireOption(options, "work-item"),
+          reviewerAgentId: requireOption(options, "reviewer-agent"),
+          toAgentId: requireOption(options, "to-agent"),
+          reason: requireOption(options, "reason"),
+          nextAction: requireOption(options, "next"),
+          evidenceRefs: options.evidence ?? [],
+        });
+        return options.json === true
+          ? returned
+          : withHumanOutput(returned, formatTeamProjectReworkHuman(returned));
+      }
       if (action === "decision") {
         const directDecisionFields = [
           "open",
@@ -3228,7 +3290,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? successor
           : withHumanOutput(successor, formatTeamProjectSuccessorHumanV1(successor));
       }
-      throw new Error("Usage: owlrunkit project <init|assign|checkpoint|handoff|decision|verification|integrate|capture|status|takeover|successor> [options]");
+      throw new Error("Usage: owlrunkit project <init|assign|checkpoint|handoff|reject-and-return|decision|verification|integrate|capture|status|takeover|successor> [options]");
     }
     if (command === "profiles") {
       const root = requireOption(options, "workspace");
@@ -3314,10 +3376,28 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       if (commandArgv.length === 0) {
         throw new Error("Usage: runkit-cli.mjs quick-verify --workspace <path> -- <executable> [args...]");
       }
-      return runQuickVerification({
+      const verification = await runQuickVerification({
         workspaceRoot: workspace(options),
         commandArgv,
+        stdinFile: options["stdin-file"],
+      });
+      if (options.attest !== true || typeof verification.receiptPath !== "string") {
+        return verification;
+      }
+      const details = attestQuickReceiptDetails({
+        receiptPath: verification.receiptPath,
+        workspaceRoot: workspace(options),
       });
+      return {
+        ...verification,
+        exitCode: details.exitCode === 0 ? verification.exitCode : details.exitCode,
+        attestationDecision: details.attestation.decision,
+        attestation: details.attestation,
+        nextAllowedAction: details.attestation.decision === "GO"
+          ? "consume_attestation"
+          : "inspect_attestation_issues",
+        authorizationGranted: false,
+      };
     }
     if (command === "quick-attest") {
       const details = attestQuickReceiptDetails({
@@ -3342,7 +3422,9 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       if (options.local !== true) {
         throw new Error("Quick metrics requires --local; network telemetry is not available.");
       }
-      const local = readLocalQuickMetrics(workspace(options));
+      const local = readLocalQuickMetrics(workspace(options), {
+        verbose: options.verbose === true,
+      });
       return {
         ...local,
         metrics: local.quick,

package/scripts/runkit-contract/schemas/team-project-event-v2.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.com/schemas/runkit/team-project-event-v2.schema.json",
+  "title": "OwlCoda RunKit Team Project Event V2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "eventId", "type", "occurredAt"],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitTeamProjectEventV2" },
+    "eventId": { "$ref": "#/$defs/id" },
+    "type": { "enum": ["agent_assigned", "checkpoint_recorded", "handoff_recorded", "rework_returned", "decision_opened", "decision_resolved", "integration_gate_passed", "verification_deferred", "verification_closed", "data_candidate_recorded"] },
+    "occurredAt": { "type": "string", "minLength": 24 },
+    "assignmentId": { "$ref": "#/$defs/id" },
+    "supersedesAssignmentId": { "$ref": "#/$defs/id" },
+    "failedAssignmentId": { "$ref": "#/$defs/id" },
+    "failedCheckpointEventId": { "$ref": "#/$defs/id" },
+    "reworkId": { "$ref": "#/$defs/id" },
+    "workItemId": { "$ref": "#/$defs/id" },
+    "agentId": { "$ref": "#/$defs/id" },
+    "executionRunId": { "$ref": "#/$defs/id" },
+    "executionWorkItemId": { "$ref": "#/$defs/id" },
+    "state": { "enum": ["active", "waiting_dependency", "waiting_decision", "verifying", "ready_to_integrate", "completed", "failed"] },
+    "summary": { "type": "string", "minLength": 1 },
+    "completedUnits": { "type": "integer", "minimum": 0 },
+    "evidenceRefs": { "$ref": "#/$defs/strings" },
+    "blockerRefs": { "$ref": "#/$defs/strings" },
+    "decisionRefs": { "$ref": "#/$defs/strings" },
+    "nextAction": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "sourceFingerprint": { "type": "string", "pattern": "^(sha256:)?[a-f0-9]{64}$" },
+    "fromAgentId": { "$ref": "#/$defs/id" },
+    "reviewerAgentId": { "$ref": "#/$defs/id" },
+    "toAgentId": { "$ref": "#/$defs/id" },
+    "reason": { "type": "string", "minLength": 1 },
+    "decisionId": { "$ref": "#/$defs/id" },
+    "title": { "type": "string", "minLength": 1 },
+    "question": { "type": "string", "minLength": 1 },
+    "ownerAgentId": { "$ref": "#/$defs/id" },
+    "blockingWorkItemIds": { "$ref": "#/$defs/strings" },
+    "options": { "$ref": "#/$defs/strings" },
+    "resolution": { "type": "string", "minLength": 1 },
+    "rationale": { "type": "string", "minLength": 1 },
+    "gateId": { "$ref": "#/$defs/id" },
+    "verificationId": { "$ref": "#/$defs/id" },
+    "checkIds": { "$ref": "#/$defs/ids" },
+    "dueGateId": { "$ref": "#/$defs/id" },
+    "disposition": { "enum": ["verified", "no_longer_required"] },
+    "decisionIds": { "$ref": "#/$defs/ids" },
+    "candidateId": { "$ref": "#/$defs/id" },
+    "sourceRef": { "type": "string", "minLength": 1 },
+    "rights": { "type": "string", "minLength": 1 },
+    "inputRef": { "type": "string", "minLength": 1 },
+    "outputRef": { "type": "string", "minLength": 1 },
+    "decisionRef": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "verificationRefs": { "$ref": "#/$defs/strings" },
+    "outcomeRef": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "version": { "type": "string", "minLength": 1 }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "type": { "const": "agent_assigned" } }, "required": ["type"] },
+      "then": {
+        "required": ["assignmentId", "workItemId", "agentId"],
+        "dependentRequired": {
+          "executionRunId": ["executionWorkItemId"],
+          "executionWorkItemId": ["executionRunId"]
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "checkpoint_recorded" } }, "required": ["type"] },
+      "then": { "required": ["assignmentId", "workItemId", "state", "summary", "evidenceRefs", "blockerRefs", "decisionRefs", "nextAction"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "handoff_recorded" } }, "required": ["type"] },
+      "then": { "required": ["assignmentId", "workItemId", "fromAgentId", "toAgentId", "summary", "evidenceRefs", "nextAction"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "rework_returned" } }, "required": ["type"] },
+      "then": { "required": ["reworkId", "assignmentId", "failedAssignmentId", "failedCheckpointEventId", "workItemId", "fromAgentId", "reviewerAgentId", "toAgentId", "reason", "evidenceRefs", "nextAction"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "decision_opened" } }, "required": ["type"] },
+      "then": { "required": ["decisionId", "title", "question", "ownerAgentId", "blockingWorkItemIds", "options"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "decision_resolved" } }, "required": ["type"] },
+      "then": { "required": ["decisionId", "resolution", "rationale", "evidenceRefs"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "integration_gate_passed" } }, "required": ["type"] },
+      "then": { "required": ["gateId", "summary", "evidenceRefs"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "verification_deferred" } }, "required": ["type"] },
+      "then": { "required": ["verificationId", "workItemId", "ownerAgentId", "checkIds", "reason", "dueGateId"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "verification_closed" } }, "required": ["type"] },
+      "then": { "required": ["verificationId", "disposition", "summary", "evidenceRefs", "decisionIds"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "data_candidate_recorded" } }, "required": ["type"] },
+      "then": { "required": ["candidateId", "sourceRef", "rights", "inputRef", "outputRef", "decisionRef", "verificationRefs", "outcomeRef", "version"] }
+    }
+  ],
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+    "ids": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/id" } },
+    "strings": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+  },
+  "examples": [{
+    "schemaVersion": "OwlCodaRunKitTeamProjectEventV2",
+    "eventId": "rework-returned-review-001",
+    "type": "rework_returned",
+    "occurredAt": "2026-08-12T00:00:00.000Z",
+    "reworkId": "review-001",
+    "assignmentId": "rework-review-001",
+    "failedAssignmentId": "assignment-001",
+    "failedCheckpointEventId": "checkpoint-failed-001",
+    "workItemId": "engine",
+    "fromAgentId": "agent-kimi",
+    "reviewerAgentId": "agent-control",
+    "toAgentId": "agent-kimi",
+    "reason": "The candidate violates its versioned contract.",
+    "evidenceRefs": ["receipt:quick-failed"],
+    "nextAction": "Repair the contract and rerun the focused check."
+  }]
+}