owlrunkit 0.17.1 → 0.18.0

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

@@ -138,11 +138,24 @@ import {
 import { OFFICIAL_NPM_REGISTRY } from "./registry-adoption-gate.mjs";
 import {
   appendTeamProjectEventV1,
+  assignTeamProjectV1,
   buildTeamProjectTakeoverV1,
+  checkpointTeamProjectV1,
+  closeTeamProjectVerificationV1,
+  deferTeamProjectVerificationV1,
   formatTeamProjectStatusHumanV1,
+  formatTeamProjectTakeoverHumanV1,
+  handoffTeamProjectV1,
   initializeTeamProjectV1,
+  integrateTeamProjectV1,
+  openTeamProjectDecisionV1,
   readTeamProjectStatusV1,
+  resolveTeamProjectDecisionV1,
 } from "./team-project.mjs";
+import {
+  formatTeamProjectSuccessorHumanV1,
+  successorTeamProjectV1,
+} from "./team-project-successor.mjs";
 
 const TOP_LEVEL_HELP = `OwlRunKit ${CORE_VERSION}
 
@@ -179,7 +192,7 @@ Fleet and status
   owlrunkit fleet discover; owlrunkit status --workspace .
 
 Agent team projects
-  owlrunkit project <init|assign|checkpoint|handoff|decision|capture|status|takeover> [options]
+  owlrunkit project <init|assign|checkpoint|handoff|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 . [...]
@@ -340,9 +353,35 @@ 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 assign --workspace <directory> --assignment-id <id> --at <ISO-UTC> --work-item <id> --agent <id>
+    [--supersedes <current-assignment-id>] [--execution-run-id <id> --execution-work-item <id>] [--json]
+  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 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]
+  owlrunkit project decision --workspace <directory> --resolve --decision-id <id> --at <ISO-UTC>
+    --resolution <text> --rationale <text> --evidence <ref> [--evidence <ref> ...] [--json]
+  owlrunkit project checkpoint --workspace <directory> --checkpoint-id <id> --at <ISO-UTC>
+    --assignment-id <current> --work-item <id>
+    --state <active|waiting_dependency|waiting_decision|verifying|ready_to_integrate|completed|failed>
+    --summary <text> [--completed-units <nonnegative-int>]
+    [--evidence <ref> ...] [--blocker <ref> ...] [--decision <id> ...]
+    [--next <text>] [--source-fingerprint <sha256>] [--json]
+  owlrunkit project verification --workspace <directory> --defer --verification-id <id> --at <ISO-UTC>
+    --work-item <id> --owner-agent <id> --check <check-id> [--check <check-id> ...]
+    --reason <text> --due-gate <gate-id> [--json]
+  owlrunkit project verification --workspace <directory> --close --verification-id <id> --at <ISO-UTC>
+    --disposition <verified|no_longer_required> --summary <text>
+    [--evidence <ref> ...] [--decision <resolved-decision-id> ...] [--json]
+  owlrunkit project integrate --workspace <directory> --gate <gate-id> --at <ISO-UTC>
+    --summary <text> --evidence <ref> [--evidence <ref> ...] [--json]
+  owlrunkit project <checkpoint|handoff|decision|verification|integrate|capture> --workspace <directory> --request <event.json>
   owlrunkit project status --workspace <directory> [--json]
   owlrunkit project takeover --workspace <directory> --agent <id> [--json]
+  owlrunkit project successor --workspace <directory> --transition-id <id> --at <ISO-UTC>
+    --definition <project.json> --reason <text> [--json]
 
 Project status is derived from durable work items, Agent assignments,
 dependencies, decisions, checkpoints, integration gates, and evidence refs.
@@ -355,6 +394,13 @@ No self-reported percentage is accepted.
   owlrunkit project takeover --workspace <directory> --agent <id> [--json]
 
 Builds a read-only blank-session recovery packet for one Agent.
+`,
+  "project successor": `Usage:
+  owlrunkit project successor --workspace <directory> --transition-id <id> --at <ISO-UTC>
+    --definition <project.json> --reason <text> [--json]
+
+Archives one derived-completed active project and installs one fresh active
+project with no inherited events. The receipt grants no repository or release authority.
 `,
 });
 
@@ -368,13 +414,100 @@ function withHumanOutput(result, humanOutput) {
   return result;
 }
 
+function formatTeamProjectAssignmentHuman(result) {
+  const disposition = result.resumed ? "Resumed" : "Assigned";
+  const nextAction = result.nextAction === null
+    ? "none"
+    : String(result.nextAction).replace(/\s+/gu, " ").trim();
+  return [
+    `${disposition} WorkItem ${result.workItemId} to Agent ${result.agentId}.`,
+    `Project next: ${nextAction}${result.nextActorId ? ` (owner ${result.nextActorId})` : ""}`,
+    `Assignment: ${result.assignmentId}`,
+    "",
+  ].join("\n");
+}
+
+function formatTeamProjectHandoffHuman(result) {
+  const disposition = result.resumed ? "Resumed" : "Handed off";
+  const targetNextAction = result.targetNextAction === null
+    ? "none"
+    : String(result.targetNextAction).replace(/\s+/gu, " ").trim();
+  const projectNextAction = result.nextAction === null
+    ? "none"
+    : String(result.nextAction).replace(/\s+/gu, " ").trim();
+  return [
+    `${disposition} WorkItem ${result.workItemId} from Agent ${result.fromAgentId} to Agent ${result.toAgentId}.`,
+    `Target next: ${targetNextAction}`,
+    `Project next: ${projectNextAction}${result.nextActorId ? ` (owner ${result.nextActorId})` : ""}`,
+    `Handoff: ${result.handoffId}`,
+    "",
+  ].join("\n");
+}
+
+function formatTeamProjectDecisionHuman(result) {
+  const disposition = result.resumed
+    ? "Resumed"
+    : result.operation === "opened" ? "Opened" : "Resolved";
+  const owner = result.ownerAgentId ? ` for Agent ${result.ownerAgentId}` : "";
+  const nextAction = result.nextAction === null
+    ? "none"
+    : String(result.nextAction).replace(/\s+/gu, " ").trim();
+  return [
+    `${disposition} decision ${result.decisionId}${owner}.`,
+    `Project next: ${nextAction}${result.nextActorId ? ` (owner ${result.nextActorId})` : ""}`,
+    `Decision: ${result.decisionId}`,
+    "",
+  ].join("\n");
+}
+
+function formatTeamProjectVerificationHuman(result) {
+  const disposition = result.resumed
+    ? "Resumed"
+    : result.operation === "deferred" ? "Deferred" : "Closed";
+  const nextAction = result.nextAction === null
+    ? "none"
+    : String(result.nextAction).replace(/\s+/gu, " ").trim();
+  return [
+    `${disposition} project verification ${result.verificationId}: ${result.verificationStatus}.`,
+    `Due gate: ${result.dueGateId}; gate state: ${result.gateStatus}.`,
+    `Project state: ${result.overall}; next: ${nextAction}${result.nextActorId ? ` (owner ${result.nextActorId})` : ""}`,
+    "No verification command, Git, or release action was performed.",
+    "",
+  ].join("\n");
+}
+
+function formatTeamProjectIntegrationHuman(result) {
+  const disposition = result.resumed ? "Resumed" : "Passed";
+  const nextAction = result.nextAction === null
+    ? "none"
+    : String(result.nextAction).replace(/\s+/gu, " ").trim();
+  return [
+    `${disposition} project integration gate ${result.gateId}.`,
+    `Project state: ${result.overall}; next: ${nextAction}${result.nextActorId ? ` (owner ${result.nextActorId})` : ""}`,
+    "Git/release not performed.",
+    "",
+  ].join("\n");
+}
+
+function formatTeamProjectCheckpointHuman(result) {
+  const disposition = result.resumed ? "Resumed" : "Recorded";
+  const nextAction = result.nextAction === null
+    ? "none"
+    : String(result.nextAction).replace(/\s+/gu, " ").trim();
+  return [
+    `${disposition} checkpoint ${result.checkpointId} for WorkItem ${result.workItemId}: ${result.state}.`,
+    `Project state: ${result.overall}; next: ${nextAction}${result.nextActorId ? ` (owner ${result.nextActorId})` : ""}`,
+    "",
+  ].join("\n");
+}
+
 function profilesReadiness(root) {
   if (!root) return { valid: false, launcherWarnings: [] };
   try {
     const validation = validateProfiles({ workspaceRoot: root });
     const launchers = readProfileLauncherReadiness({ workspaceRoot: root });
     return {
-      valid: validation.valid === true && launchers.ready,
+      valid: validation.valid === true && launchers.status === "ok",
       launcherWarnings: launchers.launcherWarnings,
     };
   } catch {
@@ -389,8 +522,17 @@ function onboardingProjection(root, recovery = null) {
     : { status: "missing" };
   const profilesReady = profiles.valid;
   const adoptionReady = adoption.status === "ok";
+  const maintenanceNextAction = profiles.launcherWarnings.length > 0
+    ? "review_profile_launchers"
+    : null;
   if (profilesReady && adoptionReady) {
     return {
+      ...(maintenanceNextAction
+        ? {
+            status: "completed_with_maintenance_warnings",
+            maintenanceNextAction,
+          }
+        : {}),
       nextAllowedAction: recovery?.nextAllowedAction ?? "plan_new_execution",
       completed: true,
       steps: [],
@@ -402,12 +544,7 @@ function onboardingProjection(root, recovery = null) {
       command: "owlrunkit doctor --workspace .",
     },
     ...(!profilesReady
-      ? profiles.launcherWarnings.length > 0
-        ? [{
-            id: "profile_launchers_review",
-            command: "owlrunkit doctor --workspace .",
-          }]
-        : [{
+      ? [{
           id: "profiles_detect",
           command: "owlrunkit profiles detect --workspace . --dry-run",
         }]
@@ -421,6 +558,7 @@ function onboardingProjection(root, recovery = null) {
   ];
   return {
     nextAllowedAction: "run_onboarding_diagnostics",
+    ...(maintenanceNextAction ? { maintenanceNextAction } : {}),
     completed: false,
     steps,
   };
@@ -460,6 +598,30 @@ function requireOption(options, name) {
   return value;
 }
 
+function assertOnlyOptions(options, allowedNames) {
+  const allowed = new Set(allowedNames);
+  const unsupported = Object.keys(options)
+    .filter(name => !allowed.has(name))
+    .sort();
+  if (unsupported.length > 0) {
+    throw new Error(
+      `Unsupported option${unsupported.length === 1 ? "" : "s"}: `
+      + unsupported.map(name => `--${name}`).join(", "),
+    );
+  }
+}
+
+function parseCanonicalNonnegativeSafeInteger(value, label) {
+  if (typeof value !== "string" || !/^(?:0|[1-9]\d*)$/u.test(value)) {
+    throw new Error(`--${label} must be a canonical non-negative safe integer.`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`--${label} must be a canonical non-negative safe integer.`);
+  }
+  return parsed;
+}
+
 function readWorkspaceArtifact(root, value, label) {
   const relativePath = safeRelativePath(value, label);
   return readJson(realpathSync(path.join(root, relativePath)));
@@ -1387,7 +1549,10 @@ function inspect(options) {
   if (requestedRunId && !executions.some(execution => execution.runId === requestedRunId)) {
     throw new Error(`Execution was not found: ${requestedRunId}`);
   }
-  const summary = buildInspectSummary(result);
+  const onboarding = onboardingProjection(root, recovery);
+  const summary = buildInspectSummary(result, {
+    maintenanceNextAction: onboarding.maintenanceNextAction ?? null,
+  });
   const view = options.history
     ? { mode: "history" }
     : requestedRunId
@@ -1398,7 +1563,7 @@ function inspect(options) {
           execution: executions.find(execution => execution.runId === requestedRunId),
         }
       : { mode: "summary" };
-  return { ...result, summary, view, onboarding: onboardingProjection(root, recovery) };
+  return { ...result, summary, view, onboarding };
 }
 
 function closeout(options) {
@@ -1650,12 +1815,26 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           || command === "start"
           || (command === "formal" && action === "start")
           ? ["owned-path"]
+        : command === "project" && action === "handoff"
+          ? ["evidence"]
+        : command === "project" && action === "integrate"
+          ? ["evidence"]
+        : command === "project" && action === "verification"
+          ? ["check", "evidence", "decision"]
+        : command === "project" && action === "checkpoint"
+          ? ["evidence", "blocker", "decision"]
+        : command === "project" && action === "decision"
+          ? ["blocking-work-item", "option", "evidence"]
           : [],
       boolean: command === "inspect"
         ? ["json", "verbose", "history"]
         : command === "init"
           ? ["json"]
-        : command === "project" && new Set(["status", "takeover"]).has(action)
+        : command === "project" && action === "decision"
+          ? ["json", "open", "resolve"]
+        : command === "project" && action === "verification"
+          ? ["json", "defer", "close"]
+        : command === "project" && new Set(["assign", "handoff", "checkpoint", "integrate", "status", "takeover", "successor"]).has(action)
           ? ["json"]
           : command === "doctor" || command === "adopt" || command === "status"
             ? ["json"]
@@ -2405,6 +2584,40 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           );
     }
     if (command === "project") {
+      const allowedProjectOptions = {
+        init: ["workspace", "definition"],
+        assign: [
+          "workspace", "request", "assignment-id", "at", "work-item", "agent",
+          "supersedes", "execution-run-id", "execution-work-item", "json",
+        ],
+        handoff: [
+          "workspace", "request", "handoff-id", "at", "assignment-id", "work-item",
+          "from-agent", "to-agent", "summary", "next", "evidence", "json",
+        ],
+        decision: [
+          "workspace", "request", "open", "resolve", "decision-id", "at", "title",
+          "question", "owner-agent", "blocking-work-item", "option", "resolution",
+          "rationale", "evidence", "json",
+        ],
+        checkpoint: [
+          "workspace", "request", "checkpoint-id", "at", "assignment-id", "work-item",
+          "state", "summary", "completed-units", "evidence", "blocker", "decision",
+          "next", "source-fingerprint", "json",
+        ],
+        verification: [
+          "workspace", "request", "defer", "close", "verification-id", "at",
+          "work-item", "owner-agent", "check", "reason", "due-gate",
+          "disposition", "summary", "evidence", "decision", "json",
+        ],
+        integrate: ["workspace", "request", "gate", "at", "summary", "evidence", "json"],
+        capture: ["workspace", "request"],
+        status: ["workspace", "json"],
+        takeover: ["workspace", "agent", "json"],
+        successor: ["workspace", "transition-id", "at", "definition", "reason", "json"],
+      };
+      if (Object.hasOwn(allowedProjectOptions, action)) {
+        assertOnlyOptions(options, allowedProjectOptions[action]);
+      }
       const root = requireOption(options, "workspace");
       if (action === "init") {
         return initializeTeamProjectV1({
@@ -2412,7 +2625,334 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           definition: readJson(realpathSync(requireOption(options, "definition"))),
         });
       }
-      if (new Set(["assign", "checkpoint", "handoff", "decision", "capture"]).has(action)) {
+      if (action === "assign") {
+        const directAssignmentFields = [
+          "assignment-id",
+          "at",
+          "work-item",
+          "agent",
+          "supersedes",
+          "execution-run-id",
+          "execution-work-item",
+        ];
+        const hasDirectAssignmentFields = directAssignmentFields.some(
+          name => options[name] !== undefined,
+        );
+        if (options.request !== undefined && hasDirectAssignmentFields) {
+          throw new Error("--request cannot be combined with direct assignment fields.");
+        }
+        if (options.request !== undefined) {
+          return appendTeamProjectEventV1({
+            workspaceRoot: root,
+            event: readJson(realpathSync(requireOption(options, "request"))),
+          });
+        }
+        const assigned = assignTeamProjectV1({
+          workspaceRoot: root,
+          assignmentId: options["assignment-id"],
+          occurredAt: options.at,
+          workItemId: options["work-item"],
+          agentId: options.agent,
+          supersedesAssignmentId: options.supersedes,
+          executionRunId: options["execution-run-id"],
+          executionWorkItemId: options["execution-work-item"],
+        });
+        return options.json === true
+          ? assigned
+          : withHumanOutput(assigned, formatTeamProjectAssignmentHuman(assigned));
+      }
+      if (action === "handoff") {
+        const directHandoffFields = [
+          "handoff-id",
+          "at",
+          "assignment-id",
+          "work-item",
+          "from-agent",
+          "to-agent",
+          "summary",
+          "next",
+          "evidence",
+        ];
+        const hasDirectHandoffFields = directHandoffFields.some(
+          name => options[name] !== undefined,
+        );
+        if (options.request !== undefined && hasDirectHandoffFields) {
+          throw new Error("--request cannot be combined with direct handoff fields.");
+        }
+        if (options.request !== undefined) {
+          return appendTeamProjectEventV1({
+            workspaceRoot: root,
+            event: readJson(realpathSync(requireOption(options, "request"))),
+          });
+        }
+        const handedOff = handoffTeamProjectV1({
+          workspaceRoot: root,
+          handoffId: options["handoff-id"],
+          occurredAt: options.at,
+          assignmentId: options["assignment-id"],
+          workItemId: options["work-item"],
+          fromAgentId: options["from-agent"],
+          toAgentId: options["to-agent"],
+          summary: options.summary,
+          nextAction: options.next,
+          evidenceRefs: options.evidence,
+        });
+        return options.json === true
+          ? handedOff
+          : withHumanOutput(handedOff, formatTeamProjectHandoffHuman(handedOff));
+      }
+      if (action === "decision") {
+        const directDecisionFields = [
+          "open",
+          "resolve",
+          "decision-id",
+          "at",
+          "title",
+          "question",
+          "owner-agent",
+          "blocking-work-item",
+          "option",
+          "resolution",
+          "rationale",
+          "evidence",
+        ];
+        const hasDirectDecisionFields = directDecisionFields.some(
+          name => options[name] !== undefined,
+        );
+        if (options.request !== undefined && hasDirectDecisionFields) {
+          throw new Error("--request cannot be combined with direct decision fields.");
+        }
+        if (options.request !== undefined) {
+          return appendTeamProjectEventV1({
+            workspaceRoot: root,
+            event: readJson(realpathSync(requireOption(options, "request"))),
+          });
+        }
+        if (options.open === options.resolve) {
+          throw new Error("Exactly one of --open or --resolve is required.");
+        }
+        const decisionId = requireOption(options, "decision-id");
+        const occurredAt = requireOption(options, "at");
+        if (options.open === true) {
+          if (options.resolution !== undefined
+            || options.rationale !== undefined
+            || options.evidence !== undefined) {
+            throw new Error("Decision open cannot accept resolution, rationale, or evidence.");
+          }
+          if ((options.option ?? []).length === 0) {
+            throw new Error("Decision open requires at least one --option.");
+          }
+          const opened = openTeamProjectDecisionV1({
+            workspaceRoot: root,
+            decisionId,
+            occurredAt,
+            title: requireOption(options, "title"),
+            question: requireOption(options, "question"),
+            ownerAgentId: requireOption(options, "owner-agent"),
+            blockingWorkItemIds: options["blocking-work-item"] ?? [],
+            options: options.option,
+          });
+          return options.json === true
+            ? opened
+            : withHumanOutput(opened, formatTeamProjectDecisionHuman(opened));
+        }
+        if (options.title !== undefined
+          || options.question !== undefined
+          || options["owner-agent"] !== undefined
+          || options["blocking-work-item"] !== undefined
+          || options.option !== undefined) {
+          throw new Error("Decision resolve cannot accept title, question, owner-agent, blocking-work-item, or option.");
+        }
+        if ((options.evidence ?? []).length === 0) {
+          throw new Error("Decision resolve requires at least one --evidence.");
+        }
+        const resolved = resolveTeamProjectDecisionV1({
+          workspaceRoot: root,
+          decisionId,
+          occurredAt,
+          resolution: requireOption(options, "resolution"),
+          rationale: requireOption(options, "rationale"),
+          evidenceRefs: options.evidence,
+        });
+        return options.json === true
+          ? resolved
+          : withHumanOutput(resolved, formatTeamProjectDecisionHuman(resolved));
+      }
+      if (action === "verification") {
+        const directVerificationFields = [
+          "defer",
+          "close",
+          "verification-id",
+          "at",
+          "work-item",
+          "owner-agent",
+          "check",
+          "reason",
+          "due-gate",
+          "disposition",
+          "summary",
+          "evidence",
+          "decision",
+        ];
+        const hasDirectVerificationFields = directVerificationFields.some(
+          name => options[name] !== undefined,
+        );
+        if (options.request !== undefined && hasDirectVerificationFields) {
+          throw new Error("--request cannot be combined with direct verification fields.");
+        }
+        if (options.request !== undefined) {
+          const requestedEvent = readJson(realpathSync(requireOption(options, "request")));
+          if (!new Set(["verification_deferred", "verification_closed"])
+            .has(requestedEvent?.type)) {
+            throw new Error(
+              "Project verification request only accepts type=verification_deferred or verification_closed.",
+            );
+          }
+          return appendTeamProjectEventV1({
+            workspaceRoot: root,
+            event: requestedEvent,
+          });
+        }
+        if (options.defer === options.close) {
+          throw new Error("Exactly one of --defer or --close is required.");
+        }
+        const verificationId = requireOption(options, "verification-id");
+        const occurredAt = requireOption(options, "at");
+        if (options.defer === true) {
+          if (options.disposition !== undefined
+            || options.summary !== undefined
+            || options.evidence !== undefined
+            || options.decision !== undefined) {
+            throw new Error(
+              "Verification defer cannot accept disposition, summary, evidence, or decision.",
+            );
+          }
+          if ((options.check ?? []).length === 0) {
+            throw new Error("Verification defer requires at least one --check.");
+          }
+          const deferred = deferTeamProjectVerificationV1({
+            workspaceRoot: root,
+            verificationId,
+            occurredAt,
+            workItemId: requireOption(options, "work-item"),
+            ownerAgentId: requireOption(options, "owner-agent"),
+            checkIds: options.check,
+            reason: requireOption(options, "reason"),
+            dueGateId: requireOption(options, "due-gate"),
+          });
+          return options.json === true
+            ? deferred
+            : withHumanOutput(deferred, formatTeamProjectVerificationHuman(deferred));
+        }
+        if (options["work-item"] !== undefined
+          || options["owner-agent"] !== undefined
+          || options.check !== undefined
+          || options.reason !== undefined
+          || options["due-gate"] !== undefined) {
+          throw new Error(
+            "Verification close cannot accept work-item, owner-agent, check, reason, or due-gate.",
+          );
+        }
+        const closed = closeTeamProjectVerificationV1({
+          workspaceRoot: root,
+          verificationId,
+          occurredAt,
+          disposition: requireOption(options, "disposition"),
+          summary: requireOption(options, "summary"),
+          evidenceRefs: options.evidence ?? [],
+          decisionIds: options.decision ?? [],
+        });
+        return options.json === true
+          ? closed
+          : withHumanOutput(closed, formatTeamProjectVerificationHuman(closed));
+      }
+      if (action === "checkpoint") {
+        const directCheckpointFields = [
+          "checkpoint-id",
+          "at",
+          "assignment-id",
+          "work-item",
+          "state",
+          "summary",
+          "completed-units",
+          "evidence",
+          "blocker",
+          "decision",
+          "next",
+          "source-fingerprint",
+        ];
+        const hasDirectCheckpointFields = directCheckpointFields.some(
+          name => options[name] !== undefined,
+        );
+        if (options.request !== undefined && hasDirectCheckpointFields) {
+          throw new Error("--request cannot be combined with direct checkpoint fields.");
+        }
+        if (options.request !== undefined) {
+          const requestedEvent = readJson(realpathSync(requireOption(options, "request")));
+          if (requestedEvent?.type !== "checkpoint_recorded") {
+            throw new Error("Project checkpoint request only accepts type=checkpoint_recorded.");
+          }
+          return appendTeamProjectEventV1({
+            workspaceRoot: root,
+            event: requestedEvent,
+          });
+        }
+        const completedUnits = options["completed-units"] === undefined
+          ? undefined
+          : parseCanonicalNonnegativeSafeInteger(options["completed-units"], "completed-units");
+        const checkpointed = checkpointTeamProjectV1({
+          workspaceRoot: root,
+          checkpointId: requireOption(options, "checkpoint-id"),
+          occurredAt: requireOption(options, "at"),
+          assignmentId: requireOption(options, "assignment-id"),
+          workItemId: requireOption(options, "work-item"),
+          state: requireOption(options, "state"),
+          summary: requireOption(options, "summary"),
+          completedUnits,
+          evidenceRefs: options.evidence ?? [],
+          blockerRefs: options.blocker ?? [],
+          decisionRefs: options.decision ?? [],
+          nextAction: options.next ?? null,
+          sourceFingerprint: options["source-fingerprint"],
+        });
+        return options.json === true
+          ? checkpointed
+          : withHumanOutput(checkpointed, formatTeamProjectCheckpointHuman(checkpointed));
+      }
+      if (action === "integrate") {
+        const directIntegrationFields = ["gate", "at", "summary", "evidence"];
+        const hasDirectIntegrationFields = directIntegrationFields.some(
+          name => options[name] !== undefined,
+        );
+        if (options.request !== undefined && hasDirectIntegrationFields) {
+          throw new Error("--request cannot be combined with direct integrate fields.");
+        }
+        if (options.request !== undefined) {
+          const requestedEvent = readJson(realpathSync(requireOption(options, "request")));
+          if (requestedEvent?.type !== "integration_gate_passed") {
+            throw new Error("Project integrate request only accepts type=integration_gate_passed.");
+          }
+          return appendTeamProjectEventV1({
+            workspaceRoot: root,
+            event: requestedEvent,
+          });
+        }
+        const evidenceRefs = options.evidence ?? [];
+        if (evidenceRefs.length === 0) {
+          throw new Error("Project integrate requires at least one --evidence.");
+        }
+        const integrated = integrateTeamProjectV1({
+          workspaceRoot: root,
+          gateId: requireOption(options, "gate"),
+          occurredAt: requireOption(options, "at"),
+          summary: requireOption(options, "summary"),
+          evidenceRefs,
+        });
+        return options.json === true
+          ? integrated
+          : withHumanOutput(integrated, formatTeamProjectIntegrationHuman(integrated));
+      }
+      if (new Set(["checkpoint", "capture"]).has(action)) {
         return appendTeamProjectEventV1({
           workspaceRoot: root,
           event: readJson(realpathSync(requireOption(options, "request"))),
@@ -2431,15 +2971,22 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         });
         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"));
+          : withHumanOutput(takeover, formatTeamProjectTakeoverHumanV1(takeover));
+      }
+      if (action === "successor") {
+        const successor = successorTeamProjectV1({
+          workspaceRoot: root,
+          transitionId: requireOption(options, "transition-id"),
+          occurredAt: requireOption(options, "at"),
+          definitionPath: requireOption(options, "definition"),
+          reason: requireOption(options, "reason"),
+          onDurableStep: runtimeHooks.onTeamProjectSuccessorStep,
+        });
+        return options.json === true
+          ? successor
+          : withHumanOutput(successor, formatTeamProjectSuccessorHumanV1(successor));
       }
-      throw new Error("Usage: owlrunkit project <init|assign|checkpoint|handoff|decision|capture|status|takeover> [options]");
+      throw new Error("Usage: owlrunkit project <init|assign|checkpoint|handoff|decision|verification|integrate|capture|status|takeover|successor> [options]");
     }
     if (command === "profiles") {
       const root = requireOption(options, "workspace");