owlrunkit 0.16.1 → 0.17.0

package/scripts/runkit-contract/formal-workflow.mjs

@@ -6,6 +6,7 @@ import {
   realpathSync,
 } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   acceptedCloseoutVerificationIssues,
@@ -33,6 +34,16 @@ import {
 } from "./source-candidate.mjs";
 import { validateReceiptLineage } from "./receipt-lineage.mjs";
 import { verificationContextFingerprint } from "./verification-context.mjs";
+import {
+  runVerificationEnvelopeV1,
+  validateVerificationEnvelopeV1,
+  verifyVerificationEnvelopeReceiptV1,
+} from "./verification-envelope.mjs";
+
+const VERIFICATION_ENVELOPE_CHECKER = fileURLToPath(new URL(
+  "./verification-envelope-check.mjs",
+  import.meta.url,
+));
 
 const FORBIDDEN_EXTERNAL_TOOLS = new Set([
   "curl",
@@ -623,6 +634,184 @@ export function recordFormalCheckV1(options) {
   );
 }
 
+async function recordFormalEnvelopeCheckWithinControlTransaction({
+  workspaceRoot,
+  runId,
+  workItemId,
+  checkId,
+  envelope,
+  hooks = {},
+}) {
+  safeIdentifier(checkId, "checkId");
+  const root = realpathSync(workspaceRoot);
+  const { executionRoot, pinGate } = loadActiveExecution(root, runId);
+  if (pinGate.status !== "valid") return { ...pinGate, authorizationGranted: false };
+  const validatedEnvelope = validateVerificationEnvelopeV1({
+    workspaceRoot: root,
+    envelope,
+  });
+  const receiptPath = path.join(checkRoot(executionRoot), `${checkId}.json`);
+  const candidateResult = resumeOrFreezeCandidate({
+    workspaceRoot: root,
+    executionRoot,
+    runId,
+    workItemId,
+    checkId,
+  });
+  const candidate = candidateResult.candidate;
+  if (candidate.status !== "source_candidate_frozen") return candidate;
+  hooks.afterCandidatePersist?.();
+  const candidateDocument = readJson(path.join(root, candidate.candidatePath));
+  const envelopePath = path.join(
+    executionRoot,
+    "formal-envelopes",
+    `${checkId}.json`,
+  );
+  const envelopeResult = writeOrResumeExactJson(
+    envelopePath,
+    validatedEnvelope.envelope,
+    "Formal Verification Envelope",
+  );
+  const envelopeArtifactRoot = path.join(
+    executionRoot,
+    "verification-envelopes",
+    checkId,
+  );
+  const envelopeReceipt = await runVerificationEnvelopeV1({
+    workspaceRoot: root,
+    envelope: envelopeResult.value,
+    artifactRoot: envelopeArtifactRoot,
+  });
+  hooks.afterEnvelopePersist?.();
+  const commandArgv = [
+    realpathSync(process.execPath),
+    VERIFICATION_ENVELOPE_CHECKER,
+    "--workspace",
+    root,
+    "--receipt",
+    envelopeReceipt.receiptPath,
+  ];
+  const verificationCommandPolicy = {
+    schemaVersion: "OwlCodaRunKitFormalVerificationCommandPolicyV1",
+    mode: "verification_envelope_v1",
+    riskClassification: "enforced_verification_envelope",
+    profileCommandIds: [],
+    executable: commandArgv[0],
+    argv: commandArgv.slice(1),
+    envelopeSha256: validatedEnvelope.envelopeSha256,
+    envelopeReceiptSha256: envelopeReceipt.receiptSha256,
+    authorizationGranted: false,
+  };
+  const context = derivedVerificationContext(root);
+  const request = {
+    schemaVersion: "OwlCodaRunKitSnapshotRequestV1",
+    snapshotId: `${checkId}-snapshot`,
+    mode: "project",
+    targetRoot: root,
+    cwd: ".",
+    executable: verificationCommandPolicy.executable,
+    argv: verificationCommandPolicy.argv,
+    launcherVersion: "owlrunkit-formal-envelope-v1",
+    toolVersions: structuredClone(context.toolchains),
+    selectedPaths: candidateDocument.sourceManifest.entries
+      .filter((entry) => entry.operation !== "deleted")
+      .map((entry) => entry.path)
+      .sort(),
+    statusMode: "porcelain-v1-z-untracked-all-runkit-excluded",
+    verificationContext: context,
+  };
+  const requestPath = path.join(
+    executionRoot,
+    "formal-check-requests",
+    `${checkId}.json`,
+  );
+  const requestResult = writeOrResumeExactJson(
+    requestPath,
+    request,
+    "Formal check request",
+  );
+  hooks.afterRequestPersist?.();
+  const snapshotResult = resumeSnapshot({
+    workspaceRoot: root,
+    executionRoot,
+    runId,
+    request: requestResult.value,
+    candidateDocument,
+  });
+  const snapshot = snapshotResult.snapshot;
+  hooks.afterSnapshotPersist?.();
+  const savedSnapshot = readJson(path.join(root, snapshot.snapshotPath));
+  const existingReceipt = existsSync(receiptPath)
+    ? readRegularJson(receiptPath, "Formal check receipt")
+    : null;
+  const sequence = existingReceipt?.sequence
+    ?? readChecks(executionRoot).length + 1;
+  const status = snapshot.status === "snapshot_passed"
+    && envelopeReceipt.formalEligible
+    ? "formal_check_passed"
+    : "formal_check_failed";
+  const receipt = {
+    schemaVersion: "OwlCodaRunKitFormalCheckV1",
+    runId,
+    checkId,
+    sequence,
+    status,
+    candidatePath: candidate.candidatePath,
+    candidateSha256: candidate.candidateSha256,
+    payloadSha256: candidate.payloadSha256,
+    sourceFingerprint: candidate.sourceFingerprint,
+    verificationContext: context,
+    verificationContextFingerprint: verificationContextFingerprint(context),
+    snapshotRequestPath: relativeToWorkspace(root, requestPath),
+    snapshotPath: snapshot.snapshotPath,
+    commandExitCode: savedSnapshot.command.exitCode,
+    verificationCommandPolicy: {
+      schemaVersion: verificationCommandPolicy.schemaVersion,
+      mode: verificationCommandPolicy.mode,
+      riskClassification: verificationCommandPolicy.riskClassification,
+      profileCommandIds: verificationCommandPolicy.profileCommandIds,
+      envelopeSha256: verificationCommandPolicy.envelopeSha256,
+      envelopeReceiptSha256: verificationCommandPolicy.envelopeReceiptSha256,
+      authorizationGranted: false,
+    },
+    envelopePath: relativeToWorkspace(root, envelopePath),
+    envelopeSha256: validatedEnvelope.envelopeSha256,
+    envelopeReceiptPath: relativeToWorkspace(root, envelopeReceipt.receiptPath),
+    envelopeReceiptSha256: envelopeReceipt.receiptSha256,
+    envelopeFormalEligible: envelopeReceipt.formalEligible,
+    finalized: false,
+    authorizationGranted: false,
+  };
+  const receiptResult = writeOrResumeExactJson(
+    receiptPath,
+    receipt,
+    "Formal check receipt",
+  );
+  hooks.afterReceiptPersist?.();
+  return {
+    ...receiptResult.value,
+    exitCode: status === "formal_check_passed" ? 0 : 2,
+    checkReceiptPath: relativeToWorkspace(root, receiptPath),
+    resumed: candidateResult.resumed
+      || envelopeResult.resumed
+      || envelopeReceipt.resumed
+      || requestResult.resumed
+      || snapshotResult.resumed
+      || receiptResult.resumed,
+  };
+}
+
+export function recordFormalEnvelopeCheckV1(options) {
+  const workspaceRoot = realpathSync(options.workspaceRoot);
+  return withControlTransaction(
+    workspaceRoot,
+    () => recordFormalEnvelopeCheckWithinControlTransaction({
+      ...options,
+      workspaceRoot,
+    }),
+  );
+}
+
 function finalizeFormalChecksWithinControlTransaction({
   workspaceRoot,
   runId,
@@ -651,6 +840,18 @@ function finalizeFormalChecksWithinControlTransaction({
   if (latest.status !== "formal_check_passed" || selected.length === 0) {
     throw new Error("Formal finish requires the latest source to have a passed check.");
   }
+  for (const check of selected) {
+    if (!check.envelopeReceiptPath) continue;
+    const verifiedEnvelope = verifyVerificationEnvelopeReceiptV1({
+      workspaceRoot: root,
+      receiptPath: path.join(root, check.envelopeReceiptPath),
+    });
+    if (!verifiedEnvelope.formalEligible
+      || verifiedEnvelope.receiptSha256 !== check.envelopeReceiptSha256
+      || verifiedEnvelope.envelopeSha256 !== check.envelopeSha256) {
+      throw new Error(`Formal finish requires a valid Formal-eligible envelope receipt: ${check.checkId}.`);
+    }
+  }
   const request = {
     schemaVersion: "OwlCodaRunKitFinalizeRequestV1",
     receiptId: `${finalizeId}-receipt`,

package/scripts/runkit-contract/lifecycle-orchestration.mjs

@@ -486,6 +486,7 @@ export function activeAcceptedGate({ workspaceRoot, runId }) {
     }
   }
   const distinctMatchingPackets = collapseByteIdenticalDeliveryCandidates(matchingPackets);
+  const declaredSourceArtifact = validated.active.receipt.sourceArtifact;
   let matchingCandidate = null;
   if (distinctMatchingPackets.length === 0) {
     const candidateRoot = path.join(executionRoot, "source-candidates");
@@ -524,7 +525,12 @@ export function activeAcceptedGate({ workspaceRoot, runId }) {
       candidates.map(({ candidate }) => candidate.sourceManifest.sha256),
     );
     if (manifestFingerprints.size === 1) {
-      [matchingCandidate] = candidates;
+      matchingCandidate = candidates.find(({ candidatePath }) => (
+        declaredSourceArtifact?.kind === "source_candidate_v2"
+        && declaredSourceArtifact.path
+          === relativeToWorkspace(workspaceRoot, candidatePath)
+        && declaredSourceArtifact.sha256 === sha256(readFileSync(candidatePath))
+      )) ?? candidates[0];
     }
   }
   if (
@@ -537,7 +543,6 @@ export function activeAcceptedGate({ workspaceRoot, runId }) {
     throw new Error("Accepted finish requires one fresh source binding matching the active verification gate; source drift remains unresolved.");
   }
   const [matchingPacket] = distinctMatchingPackets;
-  const declaredSourceArtifact = validated.active.receipt.sourceArtifact;
   if (declaredSourceArtifact !== undefined) {
     const selectedPath = matchingCandidate === null
       ? matchingPacket.packetPath

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

@@ -65,6 +65,7 @@ import {
 import {
   finalizeFormalChecksV1,
   recordFormalCheckV1,
+  recordFormalEnvelopeCheckV1,
   resumeCompletedFormalFinishV1,
   validateLegacyVerificationSideEffectsV1,
 } from "./formal-workflow.mjs";
@@ -135,6 +136,13 @@ import {
   runRegistryAdoption,
 } from "./registry-adoption.mjs";
 import { OFFICIAL_NPM_REGISTRY } from "./registry-adoption-gate.mjs";
+import {
+  appendTeamProjectEventV1,
+  buildTeamProjectTakeoverV1,
+  formatTeamProjectStatusHumanV1,
+  initializeTeamProjectV1,
+  readTeamProjectStatusV1,
+} from "./team-project.mjs";
 
 const TOP_LEVEL_HELP = `OwlRunKit ${CORE_VERSION}
 
@@ -170,16 +178,16 @@ Fleet and status
   owlrunkit fleet rollback-registry --receipt <file> --rollback-receipt <file>
   owlrunkit fleet discover; owlrunkit status --workspace .
 
+Agent team projects
+  owlrunkit project <init|assign|checkpoint|handoff|decision|capture|status|takeover> [options]
+  Durable Agent work, dependencies, decisions, gates, progress, and handoffs.
 Core successor
   owlrunkit core-successor <plan|apply|resume> --workspace . [...]
 
 Other onboarding commands:
-  owlrunkit profiles validate --workspace .
-  owlrunkit profiles impact --workspace . --changed <path>
+  owlrunkit profiles validate --workspace .; owlrunkit profiles impact --workspace . --changed <path>
   owlrunkit inspect --workspace . --json
-
-Quick receipts cannot become Formal acceptance.
-Formal accepted does not grant Git or release authority.
+Formal accepted does not grant Git or release authority; Quick cannot become Formal.
 `;
 
 const COMMAND_HELP = Object.freeze({
@@ -255,7 +263,12 @@ Creates the execution and exact writer lease.
 `,
   "formal check": `Usage:
   owlrunkit formal check --workspace <directory> --run-id <id>
-    --work-item <id> --check-id <id> --cwd <directory> -- <command> [args...]
+    --work-item <id> --check-id <id> --envelope <verification-envelope.json>
+  owlrunkit formal check --workspace <directory> --run-id <id>
+    --work-item <id> --check-id <id> --cwd <directory> -- <built-in-command> [args...]
+
+Verification Envelopes admit real project commands only when file, network,
+process, environment, output, timeout, and cleanup constraints are enforced.
 `,
   "formal finish": `Usage:
   owlrunkit formal finish --workspace <directory> --run-id <id>
@@ -324,6 +337,24 @@ profile, preflight, lineage, and result. --request is an advanced legacy path.
 
 Shows completed milestones, current state, remaining gates, and the next allowed
 action without granting any authority.
+`,
+  project: `Usage:
+  owlrunkit project init --workspace <directory> --definition <project.json>
+  owlrunkit project <assign|checkpoint|handoff|decision|capture> --workspace <directory> --request <event.json>
+  owlrunkit project status --workspace <directory> [--json]
+  owlrunkit project takeover --workspace <directory> --agent <id> [--json]
+
+Project status is derived from durable work items, Agent assignments,
+dependencies, decisions, checkpoints, integration gates, and evidence refs.
+No self-reported percentage is accepted.
+`,
+  "project status": `Usage:
+  owlrunkit project status --workspace <directory> [--json]
+`,
+  "project takeover": `Usage:
+  owlrunkit project takeover --workspace <directory> --agent <id> [--json]
+
+Builds a read-only blank-session recovery packet for one Agent.
 `,
 });
 
@@ -1589,6 +1620,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       "formal",
       "lease",
       "profiles",
+      "project",
     ]).has(command);
     const [action, ...nestedOptions] = nested ? optionValues : [null, ...optionValues];
     const helpRequested = optionValues.includes("--help")
@@ -1623,6 +1655,8 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         ? ["json", "verbose", "history"]
         : command === "init"
           ? ["json"]
+        : command === "project" && new Set(["status", "takeover"]).has(action)
+          ? ["json"]
           : command === "doctor" || command === "adopt" || command === "status"
             ? ["json"]
         : command === "profiles"
@@ -2230,10 +2264,30 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         });
       }
       if (action === "check") {
+        const workItemId = options["work-item"] ?? options["from-lease"] ?? "delivery";
+        if (
+          options["work-item"] !== undefined
+          && options["from-lease"] !== undefined
+          && options["work-item"] !== options["from-lease"]
+        ) {
+          throw new Error("formal check work-item and legacy from-lease must match.");
+        }
+        if (options.envelope !== undefined) {
+          if (commandArgv.length > 0) {
+            throw new Error("formal check accepts either --envelope or an exact built-in command, not both.");
+          }
+          return await recordFormalEnvelopeCheckV1({
+            workspaceRoot: workspace(options),
+            runId: safeRunId(requireOption(options, "run-id")),
+            workItemId,
+            checkId: requireOption(options, "check-id"),
+            envelope: readJson(realpathSync(requireOption(options, "envelope"))),
+          });
+        }
         return recordFormalCheckV1({
           workspaceRoot: workspace(options),
           runId: safeRunId(requireOption(options, "run-id")),
-          workItemId: options["from-lease"] ?? "delivery",
+          workItemId,
           checkId: requireOption(options, "check-id"),
           cwd: options.cwd ?? ".",
           commandArgv,
@@ -2350,6 +2404,43 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
             ].join("\n"),
           );
     }
+    if (command === "project") {
+      const root = requireOption(options, "workspace");
+      if (action === "init") {
+        return initializeTeamProjectV1({
+          workspaceRoot: root,
+          definition: readJson(realpathSync(requireOption(options, "definition"))),
+        });
+      }
+      if (new Set(["assign", "checkpoint", "handoff", "decision", "capture"]).has(action)) {
+        return appendTeamProjectEventV1({
+          workspaceRoot: root,
+          event: readJson(realpathSync(requireOption(options, "request"))),
+        });
+      }
+      if (action === "status") {
+        const status = readTeamProjectStatusV1({ workspaceRoot: root });
+        return options.json === true
+          ? status
+          : withHumanOutput(status, formatTeamProjectStatusHumanV1(status));
+      }
+      if (action === "takeover") {
+        const takeover = buildTeamProjectTakeoverV1({
+          workspaceRoot: root,
+          agentId: requireOption(options, "agent"),
+        });
+        return options.json === true
+          ? takeover
+          : withHumanOutput(takeover, [
+              `${takeover.projectId}: ${takeover.objective}`,
+              `Agent: ${takeover.agentId}`,
+              `Responsibility: ${takeover.currentResponsibility?.workItemId ?? "none"}`,
+              `Next: ${takeover.nextAction ?? "none"}`,
+              "",
+            ].join("\n"));
+      }
+      throw new Error("Usage: owlrunkit project <init|assign|checkpoint|handoff|decision|capture|status|takeover> [options]");
+    }
     if (command === "profiles") {
       const root = requireOption(options, "workspace");
       if (action === "detect") {
@@ -2513,7 +2604,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       return withControlTransaction(root, () => closeout(options));
     }
     if (command === "finish") return finishExecution(options);
-    throw new Error("Usage: owlrunkit <init|doctor|adopt|assurance|fleet|profiles|status|formal|candidate|deployment|core-successor|start|verify|repair|offline-export|offline-import|quick-verify|quick-attest|quick-metrics|finish|plan|inspect|lease|delivery|coverage-adopt|resume|verify-plan|resource-preflight|snapshot|visual-smoke|finalize|ready-for-commit|closeout> [options]");
+    throw new Error("Usage: owlrunkit <init|doctor|adopt|assurance|fleet|profiles|project|status|formal|candidate|deployment|core-successor|start|verify|repair|offline-export|offline-import|quick-verify|quick-attest|quick-metrics|finish|plan|inspect|lease|delivery|coverage-adopt|resume|verify-plan|resource-preflight|snapshot|visual-smoke|finalize|ready-for-commit|closeout> [options]");
   } catch (error) {
     return {
       status: "invalid_input",

package/scripts/runkit-contract/schemas/team-project-definition-v1.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.com/schemas/runkit/team-project-definition-v1.schema.json",
+  "title": "OwlCoda RunKit Team Project Definition V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "projectId", "objective", "milestones", "workstreams", "workItems", "integrationGates"],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitTeamProjectDefinitionV1" },
+    "projectId": { "$ref": "#/$defs/id" },
+    "objective": { "type": "string", "minLength": 1 },
+    "milestones": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/milestone" }
+    },
+    "workstreams": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/workstream" }
+    },
+    "workItems": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/workItem" }
+    },
+    "integrationGates": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/integrationGate" }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+    "strings": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "milestone": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "type": "string", "minLength": 1 }
+      }
+    },
+    "workstream": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "milestoneId"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "type": "string", "minLength": 1 },
+        "milestoneId": { "$ref": "#/$defs/id" }
+      }
+    },
+    "workItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "milestoneId", "workstreamId", "dependencies", "ownedPaths"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "type": "string", "minLength": 1 },
+        "milestoneId": { "$ref": "#/$defs/id" },
+        "workstreamId": { "$ref": "#/$defs/id" },
+        "dependencies": { "$ref": "#/$defs/strings" },
+        "ownedPaths": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "measurable": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["unit", "total"],
+          "properties": {
+            "unit": { "type": "string", "minLength": 1 },
+            "total": { "type": "integer", "minimum": 1 }
+          }
+        }
+      }
+    },
+    "integrationGate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "requiredWorkItemIds", "requiredDecisionIds"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "type": "string", "minLength": 1 },
+        "requiredWorkItemIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/id" } },
+        "requiredDecisionIds": { "$ref": "#/$defs/strings" }
+      }
+    }
+  },
+  "examples": [{
+    "schemaVersion": "OwlCodaRunKitTeamProjectDefinitionV1",
+    "projectId": "release-017",
+    "objective": "Ship OwlRunKit 0.17",
+    "milestones": [{ "id": "m1", "title": "Product" }],
+    "workstreams": [{ "id": "runtime", "title": "Runtime", "milestoneId": "m1" }],
+    "workItems": [{
+      "id": "engine",
+      "title": "Implement the engine",
+      "milestoneId": "m1",
+      "workstreamId": "runtime",
+      "dependencies": [],
+      "ownedPaths": ["scripts/runkit-contract/**"],
+      "measurable": { "unit": "acceptance_tests", "total": 4 }
+    }],
+    "integrationGates": [{
+      "id": "ready",
+      "title": "Ready",
+      "requiredWorkItemIds": ["engine"],
+      "requiredDecisionIds": []
+    }]
+  }]
+}

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

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.com/schemas/runkit/team-project-event-v1.schema.json",
+  "title": "OwlCoda RunKit Team Project Event V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "eventId", "type", "occurredAt"],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitTeamProjectEventV1" },
+    "eventId": { "$ref": "#/$defs/id" },
+    "type": { "enum": ["agent_assigned", "checkpoint_recorded", "handoff_recorded", "decision_opened", "decision_resolved", "integration_gate_passed", "data_candidate_recorded"] },
+    "occurredAt": { "type": "string", "minLength": 24 },
+    "assignmentId": { "$ref": "#/$defs/id" },
+    "supersedesAssignmentId": { "$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" },
+    "toAgentId": { "$ref": "#/$defs/id" },
+    "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" },
+    "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": "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": "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._-]*$" },
+    "strings": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+  },
+  "examples": [{
+    "schemaVersion": "OwlCodaRunKitTeamProjectEventV1",
+    "eventId": "event-001",
+    "type": "agent_assigned",
+    "occurredAt": "2026-08-08T00:00:00.000Z",
+    "assignmentId": "assignment-001",
+    "workItemId": "engine",
+    "agentId": "agent-runtime",
+    "executionRunId": "formal-engine-001",
+    "executionWorkItemId": "delivery"
+  }]
+}