owlrunkit 0.18.1 → 0.18.3

package/scripts/runkit-contract/schemas/profile-reconcile-plan-v1.schema.json

@@ -16,6 +16,7 @@
     "detectionSha256": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/hash" }] },
     "currentProfilesSha256": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/hash" }] },
     "proposedProfilesSha256": { "$ref": "#/$defs/hash" },
+    "normalizationOnly": { "type": "boolean" },
     "addedProfileIds": { "$ref": "#/$defs/strings" },
     "updatedProfiles": { "type": "array", "items": { "$ref": "#/$defs/update" } },
     "proposedProfiles": { "$ref": "#/$defs/profiles" },
@@ -81,6 +82,7 @@
     "detectionSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
     "currentProfilesSha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
     "proposedProfilesSha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+    "normalizationOnly": false,
     "addedProfileIds": [],
     "updatedProfiles": [{
       "profileId": "node-quality",

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."
+  }]
+}

package/scripts/runkit-contract/team-project.mjs

@@ -23,6 +23,7 @@ import {
 const PROJECT_ROOT = ".owlcoda/runkit/project";
 const DEFINITION_SCHEMA = "OwlCodaRunKitTeamProjectDefinitionV1";
 const EVENT_SCHEMA = "OwlCodaRunKitTeamProjectEventV1";
+const EVENT_SCHEMA_V2 = "OwlCodaRunKitTeamProjectEventV2";
 const STATUS_SCHEMA = "OwlCodaRunKitTeamProjectStatusV1";
 
 const DEFINITION_KEYS = [
@@ -60,6 +61,12 @@ const EVENT_KEYS = Object.freeze({
     "workItemId", "fromAgentId", "toAgentId", "summary", "evidenceRefs",
     "nextAction",
   ],
+  rework_returned: [
+    "schemaVersion", "eventId", "type", "occurredAt", "reworkId",
+    "assignmentId", "failedAssignmentId", "failedCheckpointEventId",
+    "workItemId", "fromAgentId", "reviewerAgentId", "toAgentId", "reason",
+    "evidenceRefs", "nextAction",
+  ],
   decision_opened: [
     "schemaVersion", "eventId", "type", "occurredAt", "decisionId",
     "title", "question", "ownerAgentId", "blockingWorkItemIds", "options",
@@ -391,6 +398,28 @@ function pendingHandoffProjection(handoff) {
     : null;
 }
 
+function reworkProjection(rework, attempt) {
+  return rework
+    ? {
+        eventId: rework.eventId,
+        truthRef: rework.ref,
+        reworkId: rework.reworkId,
+        attempt,
+        failedCheckpointEventId: rework.failedCheckpointEventId,
+        failedTruthRef: `project/events/${rework.failedCheckpointEventId}.json`,
+        previousAssignmentId: rework.failedAssignmentId,
+        previousAgentId: rework.fromAgentId,
+        reviewerAgentId: rework.reviewerAgentId,
+        assignmentId: rework.assignmentId,
+        agentId: rework.toAgentId,
+        reason: rework.reason,
+        evidenceRefs: [...rework.evidenceRefs],
+        nextAction: rework.nextAction,
+        occurredAt: rework.occurredAt,
+      }
+    : null;
+}
+
 function validateTimestamp(value) {
   if (typeof value !== "string"
     || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value)
@@ -405,8 +434,13 @@ function validateEventShape(value, definition) {
     throw new Error("Team project event type is invalid.");
   }
   assertAllowedKeys(value, `Team project event ${value.eventId ?? "unknown"}`, EVENT_KEYS[value.type]);
-  if (value.schemaVersion !== EVENT_SCHEMA) {
-    throw new Error(`Team project event schemaVersion must be ${EVENT_SCHEMA}.`);
+  if (![EVENT_SCHEMA, EVENT_SCHEMA_V2].includes(value.schemaVersion)) {
+    throw new Error(
+      `Team project event schemaVersion must be ${EVENT_SCHEMA} or ${EVENT_SCHEMA_V2}.`,
+    );
+  }
+  if (value.type === "rework_returned" && value.schemaVersion !== EVENT_SCHEMA_V2) {
+    throw new Error(`rework_returned requires schemaVersion ${EVENT_SCHEMA_V2}.`);
   }
   safeIdentifier(value.eventId, "eventId");
   validateTimestamp(value.occurredAt);
@@ -420,11 +454,17 @@ function validateEventShape(value, definition) {
     "agent_assigned",
     "checkpoint_recorded",
     "handoff_recorded",
+    "rework_returned",
     "verification_deferred",
   ].includes(value.type)) {
     assertWorkItem(value.workItemId);
   }
-  if (["agent_assigned", "checkpoint_recorded", "handoff_recorded"].includes(value.type)) {
+  if ([
+    "agent_assigned",
+    "checkpoint_recorded",
+    "handoff_recorded",
+    "rework_returned",
+  ].includes(value.type)) {
     safeIdentifier(value.assignmentId, "assignmentId");
   }
   if (value.type === "agent_assigned") {
@@ -466,6 +506,16 @@ function validateEventShape(value, definition) {
     nonEmptyString(value.summary, "Handoff summary");
     stringArray(value.evidenceRefs, "Handoff evidenceRefs", { allowEmpty: false });
     nonEmptyString(value.nextAction, "Handoff nextAction");
+  } else if (value.type === "rework_returned") {
+    safeIdentifier(value.reworkId, "reworkId");
+    safeIdentifier(value.failedAssignmentId, "failedAssignmentId");
+    safeIdentifier(value.failedCheckpointEventId, "failedCheckpointEventId");
+    safeIdentifier(value.fromAgentId, "fromAgentId");
+    safeIdentifier(value.reviewerAgentId, "reviewerAgentId");
+    safeIdentifier(value.toAgentId, "toAgentId");
+    nonEmptyString(value.reason, "Rework reason");
+    stringArray(value.evidenceRefs, "Rework evidenceRefs", { allowEmpty: false });
+    nonEmptyString(value.nextAction, "Rework nextAction");
   } else if (value.type === "decision_opened") {
     safeIdentifier(value.decisionId, "decisionId");
     safeIdentifier(value.ownerAgentId, "ownerAgentId");
@@ -541,11 +591,13 @@ function projectEvents(definition, records) {
   const assignmentHistory = new Map(definition.workItems.map(row => [row.id, []]));
   const checkpoints = new Map();
   const handoffs = new Map();
+  const reworks = new Map();
   const decisions = new Map();
   const gatePasses = new Map();
   const verifications = new Map();
   const dataCandidates = [];
   const seenAssignments = new Set();
+  const seenReworks = new Set();
   const seenDecisions = new Set();
 
   for (const { event, ref } of records) {
@@ -561,6 +613,38 @@ function projectEvents(definition, records) {
       checkpoints.set(event.workItemId, { ...event, ref });
     } else if (event.type === "handoff_recorded") {
       handoffs.set(event.workItemId, { ...event, ref });
+    } else if (event.type === "rework_returned") {
+      if (seenReworks.has(event.reworkId)) {
+        throw new Error(`Duplicate reworkId ${event.reworkId}.`);
+      }
+      if (seenAssignments.has(event.assignmentId)) {
+        throw new Error(`Duplicate assignmentId ${event.assignmentId}.`);
+      }
+      const current = assignments.get(event.workItemId) ?? null;
+      const failure = checkpoints.get(event.workItemId) ?? null;
+      const latestFact = latestEventFact(failure, handoffs.get(event.workItemId) ?? null);
+      if (!current
+        || current.assignmentId !== event.failedAssignmentId
+        || current.agentId !== event.fromAgentId
+        || failure?.eventId !== event.failedCheckpointEventId
+        || failure.assignmentId !== event.failedAssignmentId
+        || failure.state !== "failed"
+        || latestFact?.eventId !== failure.eventId) {
+        throw new Error(
+          `Rework ${event.reworkId} does not bind the current failed checkpoint and assignment.`,
+        );
+      }
+      seenReworks.add(event.reworkId);
+      seenAssignments.add(event.assignmentId);
+      const assignment = {
+        ...event,
+        agentId: event.toAgentId,
+        supersedesAssignmentId: event.failedAssignmentId,
+        ref,
+      };
+      assignments.set(event.workItemId, assignment);
+      assignmentHistory.get(event.workItemId).push(assignment);
+      reworks.set(event.workItemId, { ...event, ref });
     } else if (event.type === "decision_opened") {
       if (seenDecisions.has(event.decisionId)) {
         throw new Error(`Duplicate decision_opened event for ${event.decisionId}.`);
@@ -615,6 +699,7 @@ function projectEvents(definition, records) {
     assignmentHistory,
     checkpoints,
     handoffs,
+    reworks,
     decisions,
     gatePasses,
     verifications,
@@ -945,7 +1030,9 @@ function projectStatus(definition, records, workspaceRoot = null) {
     const assignment = state.assignments.get(item.id) ?? null;
     const checkpoint = state.checkpoints.get(item.id) ?? null;
     const handoff = state.handoffs.get(item.id) ?? null;
-    const latestFact = latestEventFact(checkpoint, handoff);
+    const rework = state.reworks.get(item.id) ?? null;
+    const currentRework = rework?.assignmentId === assignment?.assignmentId ? rework : null;
+    const latestFact = latestEventFact(latestEventFact(checkpoint, handoff), currentRework);
     const activeHandoff = handoff
       && handoff.assignmentId === assignment?.assignmentId
       && handoff.fromAgentId === assignment?.agentId
@@ -973,7 +1060,8 @@ function projectStatus(definition, records, workspaceRoot = null) {
           total: item.measurable.total,
         }
       : { kind: "state_only" };
-    const history = state.assignmentHistory.get(item.id).map(row => ({
+    const assignmentEvents = state.assignmentHistory.get(item.id);
+    const history = assignmentEvents.map(row => ({
       assignmentId: row.assignmentId,
       agentId: row.agentId,
       occurredAt: row.occurredAt,
@@ -986,7 +1074,17 @@ function projectStatus(definition, records, workspaceRoot = null) {
       ...history.map(row => row.truthRef),
       ...(checkpoint ? [checkpoint.ref] : []),
       ...(handoff ? [handoff.ref] : []),
+      ...(rework ? [rework.ref] : []),
     ];
+    const projectedRework = reworkProjection(
+      currentRework,
+      currentRework
+        ? assignmentEvents.findIndex(row => row.assignmentId === currentRework.assignmentId) + 1
+        : null,
+    );
+    const latestSummary = latestFact?.type === "rework_returned"
+      ? latestFact.reason
+      : latestFact?.summary ?? null;
     return {
       workItemId: item.id,
       title: item.title,
@@ -1005,9 +1103,10 @@ function projectStatus(definition, records, workspaceRoot = null) {
         : unresolvedDependencies.map(id => `work-item:${id}`),
       decisionRefs: latestFact?.type === "checkpoint_recorded" ? checkpoint.decisionRefs : [],
       progress: measured,
-      summary: latestFact?.summary ?? null,
+      summary: latestSummary,
       nextAction: latestFact?.nextAction ?? null,
       pendingHandoff,
+      rework: projectedRework,
       lastCheckpointAt: checkpoint?.occurredAt ?? null,
       evidenceRefs: latestFact?.evidenceRefs ?? [],
       assignmentHistory: history,
@@ -1339,6 +1438,42 @@ function validateEventAgainstState(event, definition, records, workspaceRoot) {
       || current.agentId !== normalized.fromAgentId) {
       throw new Error("Handoff must bind the current assignment and Agent.");
     }
+  } else if (normalized.type === "rework_returned") {
+    const current = state.assignments.get(normalized.workItemId) ?? null;
+    const failure = state.checkpoints.get(normalized.workItemId) ?? null;
+    const projected = status.workItems.find(row => row.workItemId === normalized.workItemId);
+    const latestFact = latestEventFact(
+      failure,
+      state.handoffs.get(normalized.workItemId) ?? null,
+    );
+    if (projected?.status !== "failed"
+      || !current
+      || current.assignmentId !== normalized.failedAssignmentId
+      || current.agentId !== normalized.fromAgentId
+      || failure?.eventId !== normalized.failedCheckpointEventId
+      || failure.assignmentId !== normalized.failedAssignmentId
+      || failure.state !== "failed"
+      || latestFact?.eventId !== failure.eventId) {
+      throw new Error(
+        "reject-and-return requires one current failed checkpoint bound to the current assignment.",
+      );
+    }
+    if (state.assignmentHistory.get(normalized.workItemId).some(
+      row => row.assignmentId === normalized.assignmentId,
+    )) {
+      throw new Error(`Assignment ${normalized.assignmentId} already exists.`);
+    }
+    for (const otherProjection of status.workItems) {
+      if (otherProjection.workItemId === normalized.workItemId
+        || otherProjection.assignmentId === null
+        || ["completed", "failed"].includes(otherProjection.status)) continue;
+      const other = definition.workItems.find(row => row.id === otherProjection.workItemId);
+      if (pathsOverlap(workItem.ownedPaths, other.ownedPaths)) {
+        throw new Error(
+          `Owned paths overlap active assignment ${otherProjection.assignmentId}: ${normalized.workItemId} <> ${otherProjection.workItemId}.`,
+        );
+      }
+    }
   } else if (normalized.type === "decision_opened") {
     if (state.decisions.has(normalized.decisionId)) throw new Error(`Decision ${normalized.decisionId} already exists.`);
   } else if (normalized.type === "decision_resolved") {
@@ -1416,52 +1551,55 @@ export function initializeTeamProjectV1({ workspaceRoot, definition }) {
   };
 }
 
-export function appendTeamProjectEventV1({ workspaceRoot, event }) {
-  const loaded = loadProject(workspaceRoot);
-  return withProjectLock(loaded.projectRoot, () => {
-    const refreshed = loadProject(workspaceRoot);
-    const shaped = validateEventShape(event, refreshed.definition);
-    const eventPath = path.join(refreshed.projectRoot, "events", `${shaped.eventId}.json`);
-    if (existsSync(eventPath)) {
-      const existing = readRegularJson(eventPath, `Team project event ${shaped.eventId}`);
-      if (canonical(existing) !== canonical(shaped)) {
-        throw new Error(`Team project immutable event differs: ${shaped.eventId}.`);
-      }
-      return {
-        status: "team_project_event_recorded",
-        exitCode: 0,
-        eventId: shaped.eventId,
-        eventPath: relativeToWorkspace(refreshed.root, eventPath),
-        eventSha256: sha256(canonical(shaped)),
-        resumed: true,
-        authorizationGranted: false,
-      };
-    }
-    const latest = refreshed.events.at(-1)?.event ?? null;
-    if (latest && (shaped.occurredAt < latest.occurredAt
-      || (shaped.occurredAt === latest.occurredAt
-        && shaped.eventId.localeCompare(latest.eventId) <= 0))) {
-      throw new Error(
-        `Team project event must sort after the latest event ${latest.eventId}.`,
-      );
+function appendTeamProjectEventWithinLock(refreshed, event) {
+  const shaped = validateEventShape(event, refreshed.definition);
+  const eventPath = path.join(refreshed.projectRoot, "events", `${shaped.eventId}.json`);
+  if (existsSync(eventPath)) {
+    const existing = readRegularJson(eventPath, `Team project event ${shaped.eventId}`);
+    if (canonical(existing) !== canonical(shaped)) {
+      throw new Error(`Team project immutable event differs: ${shaped.eventId}.`);
     }
-    const normalized = validateEventAgainstState(
-      shaped,
-      refreshed.definition,
-      refreshed.events,
-      refreshed.root,
-    );
-    writeJsonExclusiveAtomically(eventPath, normalized);
     return {
       status: "team_project_event_recorded",
       exitCode: 0,
-      eventId: normalized.eventId,
+      eventId: shaped.eventId,
       eventPath: relativeToWorkspace(refreshed.root, eventPath),
-      eventSha256: sha256(canonical(normalized)),
-      resumed: false,
+      eventSha256: sha256(canonical(shaped)),
+      resumed: true,
       authorizationGranted: false,
     };
-  });
+  }
+  const latest = refreshed.events.at(-1)?.event ?? null;
+  if (latest && (shaped.occurredAt < latest.occurredAt
+    || (shaped.occurredAt === latest.occurredAt
+      && shaped.eventId.localeCompare(latest.eventId) <= 0))) {
+    throw new Error(
+      `Team project event must sort after the latest event ${latest.eventId}.`,
+    );
+  }
+  const normalized = validateEventAgainstState(
+    shaped,
+    refreshed.definition,
+    refreshed.events,
+    refreshed.root,
+  );
+  writeJsonExclusiveAtomically(eventPath, normalized);
+  return {
+    status: "team_project_event_recorded",
+    exitCode: 0,
+    eventId: normalized.eventId,
+    eventPath: relativeToWorkspace(refreshed.root, eventPath),
+    eventSha256: sha256(canonical(normalized)),
+    resumed: false,
+    authorizationGranted: false,
+  };
+}
+
+export function appendTeamProjectEventV1({ workspaceRoot, event }) {
+  const loaded = loadProject(workspaceRoot);
+  return withProjectLock(loaded.projectRoot, () => (
+    appendTeamProjectEventWithinLock(loadProject(workspaceRoot), event)
+  ));
 }
 
 export function assignTeamProjectV1({
@@ -1584,6 +1722,133 @@ export function handoffTeamProjectV1({
   };
 }
 
+export function rejectAndReturnTeamProjectV1({
+  workspaceRoot,
+  reworkId,
+  occurredAt,
+  workItemId,
+  reviewerAgentId,
+  toAgentId,
+  reason,
+  nextAction,
+  evidenceRefs,
+}) {
+  safeIdentifier(reworkId, "reworkId");
+  const eventId = `rework-returned-${reworkId}`;
+  const assignmentId = `rework-${reworkId}`;
+  const loaded = loadProject(workspaceRoot);
+  return withProjectLock(loaded.projectRoot, () => {
+    const refreshed = loadProject(workspaceRoot);
+    const existing = refreshed.events.find(row => row.event.eventId === eventId)?.event ?? null;
+    let event;
+    if (existing) {
+      event = {
+        schemaVersion: EVENT_SCHEMA_V2,
+        eventId,
+        type: "rework_returned",
+        occurredAt,
+        reworkId,
+        assignmentId,
+        failedAssignmentId: existing.failedAssignmentId,
+        failedCheckpointEventId: existing.failedCheckpointEventId,
+        workItemId,
+        fromAgentId: existing.fromAgentId,
+        reviewerAgentId,
+        toAgentId,
+        reason,
+        evidenceRefs,
+        nextAction,
+      };
+    } else {
+      const state = projectEvents(refreshed.definition, refreshed.events);
+      const status = projectStatus(refreshed.definition, refreshed.events, refreshed.root);
+      const current = state.assignments.get(workItemId) ?? null;
+      const failure = state.checkpoints.get(workItemId) ?? null;
+      const projected = status.workItems.find(row => row.workItemId === workItemId) ?? null;
+      const latestFact = latestEventFact(failure, state.handoffs.get(workItemId) ?? null);
+      if (projected?.status !== "failed"
+        || !current
+        || failure?.state !== "failed"
+        || failure.assignmentId !== current.assignmentId
+        || latestFact?.eventId !== failure.eventId) {
+        throw new Error(
+          "reject-and-return requires one current failed checkpoint bound to the current assignment.",
+        );
+      }
+      event = {
+        schemaVersion: EVENT_SCHEMA_V2,
+        eventId,
+        type: "rework_returned",
+        occurredAt,
+        reworkId,
+        assignmentId,
+        failedAssignmentId: current.assignmentId,
+        failedCheckpointEventId: failure.eventId,
+        workItemId,
+        fromAgentId: current.agentId,
+        reviewerAgentId,
+        toAgentId,
+        reason,
+        evidenceRefs,
+        nextAction,
+      };
+    }
+
+    const recorded = appendTeamProjectEventWithinLock(refreshed, event);
+    const projectedEvents = recorded.resumed
+      ? refreshed.events
+      : [
+          ...refreshed.events,
+          { event, ref: `project/events/${event.eventId}.json` },
+        ];
+    const status = projectStatus(refreshed.definition, projectedEvents, refreshed.root);
+    const projectedState = projectEvents(refreshed.definition, projectedEvents);
+    const current = status.workItems.find(row => row.workItemId === workItemId) ?? null;
+    const latestFact = latestEventFact(
+      latestEventFact(
+        projectedState.checkpoints.get(workItemId) ?? null,
+        projectedState.handoffs.get(workItemId) ?? null,
+      ),
+      projectedState.reworks.get(workItemId) ?? null,
+    );
+    if (current?.assignmentId !== assignmentId
+      || current?.rework?.eventId !== eventId
+      || latestFact?.eventId !== eventId) {
+      throw new Error(
+        `Cannot resume historical/superseded rework ${reworkId}; `
+        + `current assignment=${current?.assignmentId ?? "none"}, `
+        + `current owner=${current?.agentId ?? "none"}.`,
+      );
+    }
+    return {
+      status: "team_project_rework",
+      reworkId,
+      assignmentId,
+      failedAssignmentId: event.failedAssignmentId,
+      failedCheckpointEventId: event.failedCheckpointEventId,
+      workItemId,
+      fromAgentId: event.fromAgentId,
+      reviewerAgentId,
+      toAgentId,
+      reason,
+      nextAction: current.nextAction,
+      eventId: recorded.eventId,
+      eventPath: recorded.eventPath,
+      eventSha256: recorded.eventSha256,
+      resumed: recorded.resumed,
+      reworkAttempt: current.rework.attempt,
+      projectTruthHash: status.projectTruthHash,
+      overall: status.overall,
+      projectNextAction: status.nextAction,
+      projectNextActorId: status.nextActorId,
+      gitWritePerformed: false,
+      releaseWritePerformed: false,
+      authorizationGranted: false,
+      exitCode: 0,
+    };
+  });
+}
+
 export function openTeamProjectDecisionV1({
   workspaceRoot,
   decisionId,

package/scripts/runkit-contract/usage-mode.mjs

@@ -1,3 +1,5 @@
+import { RUNKIT_RISK_CATEGORIES } from "./assurance-router.mjs";
+
 const USER_MODES = new Set(["auto", "off", "light", "managed", "formal"]);
 
 const BOOLEAN_FACTS = [
@@ -24,17 +26,7 @@ const MATERIAL_RISK_CATEGORIES = new Map([
   ["migration", "schema_or_data_migration"],
 ]);
 
-const KNOWN_RISK_CATEGORIES = new Set([
-  "backtest",
-  "deployment",
-  "destructive",
-  "foreign_write",
-  "funds",
-  "integration",
-  "migration",
-  "production",
-  "release",
-]);
+const KNOWN_RISK_CATEGORIES = new Set(RUNKIT_RISK_CATEGORIES);
 
 const AUTHORITY_BOUNDARY = Object.freeze({
   authorizationGranted: false,
@@ -65,8 +57,14 @@ function requireFacts(input) {
     || !input.riskCategories.every((value) => typeof value === "string")) {
     throw new Error("riskCategories must be an array of strings");
   }
-  if (input.riskCategories.some((value) => !KNOWN_RISK_CATEGORIES.has(value))) {
-    throw new Error("riskCategories contains an unknown category");
+  const unknownCategories = uniqueSorted(
+    input.riskCategories.filter((value) => !KNOWN_RISK_CATEGORIES.has(value)),
+  );
+  if (unknownCategories.length > 0) {
+    throw new Error(
+      `riskCategories contains an unknown category: ${unknownCategories.join(", ")}. `
+      + `Allowed: ${RUNKIT_RISK_CATEGORIES.join(", ")}`,
+    );
   }
 }