owlrunkit 0.17.2 → 0.18.1

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

@@ -89,6 +89,7 @@ import {
   applyDetectedProfilesV2,
   detectProfiles,
   detectProfilesV2,
+  reconcileProfilesV2,
   resolveProfilesImpact,
   validateProfiles,
 } from "./profile-onboarding.mjs";
@@ -100,6 +101,10 @@ import {
   rollbackFleetRegistry,
 } from "./fleet-discovery.mjs";
 import { routeRunKitAssuranceV1 } from "./assurance-router.mjs";
+import {
+  formatUsageModeHumanV1,
+  recommendUsageModeV1,
+} from "./usage-mode.mjs";
 import { deriveHumanStatusFromInspectV1 } from "./human-status.mjs";
 import {
   closeDeploymentExecuteChildRun,
@@ -138,11 +143,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}
 
@@ -150,20 +168,20 @@ Usage:
   owlrunkit <command> [options]
 
 Start here:
+  owlrunkit mode recommend --workspace .
   owlrunkit doctor --workspace .
   owlrunkit profiles detect --workspace . --dry-run
   owlrunkit profiles detect --workspace . --apply
   owlrunkit assurance route --workspace . --request <risk-facts.json>
   owlrunkit adopt --workspace . --exact owlrunkit@${CORE_VERSION}
-
 Quick Verification
   owlrunkit quick-verify --workspace . -- <command> [args...]
   Low-risk, source-bound reusable evidence without writer leases or acceptance.
 
 Formal Delivery
   owlrunkit formal <start|check|finish> --workspace . --run-id <id> [...]
-  Use for multi-writer, long-running, migration, integration, release, funds,
-  production, or formal acceptance work.
+  Use for multi-writer, permissions, security, funds, irreversible change,
+  uncertain rollback, schema/data migration, or explicit Formal acceptance.
 
 Frozen dirty source
   owlrunkit candidate <freeze|verify|materialize> --workspace . [...]
@@ -179,7 +197,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 . [...]
@@ -191,6 +209,13 @@ Formal accepted does not grant Git or release authority; Quick cannot become For
 `;
 
 const COMMAND_HELP = Object.freeze({
+  adopt: `Usage:
+  owlrunkit adopt --workspace <directory> --exact owlrunkit@${CORE_VERSION}
+    [--registry <url>] [--timeout-ms <milliseconds>] [--json]
+
+Verifies the exact registry release against the project-local install and writes
+project-owned adoption evidence. It grants no Git or release authority.
+`,
   assurance: `Usage:
   owlrunkit assurance route --workspace <directory> --request <risk-facts.json>
 
@@ -202,6 +227,38 @@ repository, release, deployment, or destructive authority.
 
 Required:
   --request <file>       Structured assurance risk facts.
+`,
+  mode: `Usage:
+  owlrunkit mode recommend --workspace <directory> [risk facts]
+  owlrunkit mode status --workspace <directory> [--json]
+
+Selects continuity and assurance independently. Recommendation and status are
+read-only and grant no Git, release, deployment, production, or business authority.
+`,
+  "mode recommend": `Usage:
+  owlrunkit mode recommend --workspace <directory>
+    [--requested-mode auto|off|light|managed|formal]
+    [--needs-evidence] [--exact-command-count <count>] [--writer-count <count>]
+    [--cross-session] [--long-running] [--interruption-recovery]
+    [--may-mutate-project] [--external-side-effects]
+    [--irreversible] [--rollback-uncertain]
+    [--permission-sensitive] [--security-sensitive] [--funds-at-risk]
+    [--schema-or-data-migration] [--formal-acceptance]
+    [--risk-category <category>] [--json]
+
+Returns one user mode plus the independent continuity and assurance selections.
+Persisted mode preferences are not part of this release.
+`,
+  "mode status": `Usage:
+  owlrunkit mode status --workspace <directory> [--json]
+
+Reads the current mode preference source without creating project state.
+`,
+  "quick-attest": `Usage:
+  owlrunkit quick-attest --workspace <directory> --receipt <receipt.json> [--json]
+
+Attests one Quick Receipt against its bound materials and current workspace.
+It never grants repository or business authority.
 `,
   fleet: `Usage:
   owlrunkit fleet register-root --fleet-root <directory>
@@ -241,6 +298,7 @@ With no source option, discovers the complete fleet inside registered roots.
 `,
   profiles: `Usage:
   owlrunkit profiles detect --workspace <directory> [--dry-run | --apply]
+  owlrunkit profiles reconcile --workspace <directory> (--dry-run | --apply)
   owlrunkit profiles validate --workspace <directory>
   owlrunkit profiles impact --workspace <directory> --changed <path>
 `,
@@ -249,6 +307,12 @@ With no source option, discovers the complete fleet inside registered roots.
 
 --dry-run reports deterministic candidates. --apply atomically adopts only a
 high-confidence unambiguous profile.
+`,
+  "profiles reconcile": `Usage:
+  owlrunkit profiles reconcile --workspace <directory> (--dry-run | --apply)
+
+--dry-run previews deterministic additions and command updates without writing.
+--apply atomically updates profiles.json and writes a hash-bound migration receipt.
 `,
   formal: `Usage:
   owlrunkit formal start --workspace <directory> --run-id <id> [...]
@@ -340,9 +404,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 +445,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,6 +465,93 @@ 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 {
@@ -465,6 +649,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)));
@@ -1393,8 +1601,13 @@ function inspect(options) {
     throw new Error(`Execution was not found: ${requestedRunId}`);
   }
   const onboarding = onboardingProjection(root, recovery);
+  const projectDefinitionPath = runtimePath(root, "project", "definition.json");
+  const projectDriver = pathEntryExists(projectDefinitionPath)
+    ? readTeamProjectStatusV1({ workspaceRoot: root })
+    : null;
   const summary = buildInspectSummary(result, {
     maintenanceNextAction: onboarding.maintenanceNextAction ?? null,
+    projectDriver,
   });
   const view = options.history
     ? { mode: "history" }
@@ -1406,7 +1619,13 @@ function inspect(options) {
           execution: executions.find(execution => execution.runId === requestedRunId),
         }
       : { mode: "summary" };
-  return { ...result, summary, view, onboarding };
+  return {
+    ...result,
+    summary,
+    view,
+    onboarding,
+    ...(projectDriver === null ? {} : { projectDriver }),
+  };
 }
 
 function closeout(options) {
@@ -1627,6 +1846,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       "fleet",
       "formal",
       "lease",
+      "mode",
       "profiles",
       "project",
     ]).has(command);
@@ -1649,7 +1869,9 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       }
     }
     const options = parseOptions(nested ? nestedOptions : optionValues, {
-      multi: command === "profiles" && action === "impact"
+      multi: command === "mode"
+        ? ["risk-category"]
+        : command === "profiles" && action === "impact"
         ? ["changed"]
         : (command === "fleet" && action === "discover")
           || (command === "core-successor" && action === "plan")
@@ -1658,12 +1880,46 @@ 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"
+      boolean: command === "mode" && action === "recommend"
+        ? [
+            "json",
+            "needs-evidence",
+            "may-mutate-project",
+            "external-side-effects",
+            "cross-session",
+            "long-running",
+            "interruption-recovery",
+            "dirty-parallel-workspace",
+            "irreversible",
+            "rollback-uncertain",
+            "permission-sensitive",
+            "security-sensitive",
+            "funds-at-risk",
+            "schema-or-data-migration",
+            "formal-acceptance",
+          ]
+        : command === "mode" && action === "status"
+          ? ["json"]
+        : 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"]
@@ -1716,6 +1972,97 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       const requestPath = realpathSync(requireOption(options, "request"));
       return routeRunKitAssuranceV1(readJson(requestPath));
     }
+    if (command === "mode") {
+      const root = workspace(options);
+      if (action === "recommend") {
+        assertOnlyOptions(options, [
+          "workspace",
+          "requested-mode",
+          "needs-evidence",
+          "exact-command-count",
+          "writer-count",
+          "may-mutate-project",
+          "external-side-effects",
+          "cross-session",
+          "long-running",
+          "interruption-recovery",
+          "dirty-parallel-workspace",
+          "irreversible",
+          "rollback-uncertain",
+          "permission-sensitive",
+          "security-sensitive",
+          "funds-at-risk",
+          "schema-or-data-migration",
+          "formal-acceptance",
+          "risk-category",
+          "json",
+        ]);
+        const recommendation = recommendUsageModeV1({
+          workspaceRoot: root,
+          requestedMode: options["requested-mode"] ?? "auto",
+          needsDurableEvidence: options["needs-evidence"] === true,
+          exactCommandCount: parseCanonicalNonnegativeSafeInteger(
+            options["exact-command-count"] ?? "0",
+            "exact-command-count",
+          ),
+          writerCount: parseCanonicalNonnegativeSafeInteger(
+            options["writer-count"] ?? "1",
+            "writer-count",
+          ),
+          mayMutateProject: options["may-mutate-project"] === true,
+          externalSideEffects: options["external-side-effects"] === true,
+          crossSession: options["cross-session"] === true,
+          longRunning: options["long-running"] === true,
+          interruptionRecovery: options["interruption-recovery"] === true,
+          dirtyParallelWorkspace: options["dirty-parallel-workspace"] === true,
+          irreversibleChange: options.irreversible === true,
+          rollbackUncertain: options["rollback-uncertain"] === true,
+          permissionSensitive: options["permission-sensitive"] === true,
+          securitySensitive: options["security-sensitive"] === true,
+          fundsAtRisk: options["funds-at-risk"] === true,
+          schemaOrDataMigration: options["schema-or-data-migration"] === true,
+          needsFormalAcceptance: options["formal-acceptance"] === true,
+          riskCategories: options["risk-category"] ?? [],
+        });
+        return options.json === true
+          ? recommendation
+          : withHumanOutput(recommendation, formatUsageModeHumanV1(recommendation));
+      }
+      if (action === "status") {
+        assertOnlyOptions(options, ["workspace", "json"]);
+        const recommendation = recommendUsageModeV1({
+          workspaceRoot: root,
+          requestedMode: "auto",
+          needsDurableEvidence: false,
+          exactCommandCount: 0,
+          writerCount: 1,
+          mayMutateProject: false,
+          externalSideEffects: false,
+          crossSession: false,
+          longRunning: false,
+          interruptionRecovery: false,
+          dirtyParallelWorkspace: false,
+          irreversibleChange: false,
+          rollbackUncertain: false,
+          permissionSensitive: false,
+          securitySensitive: false,
+          fundsAtRisk: false,
+          schemaOrDataMigration: false,
+          needsFormalAcceptance: false,
+          riskCategories: [],
+        });
+        const status = {
+          ...recommendation,
+          status: "mode_status",
+          preferenceSource: "default_auto",
+          persistedPreference: null,
+        };
+        return options.json === true
+          ? status
+          : withHumanOutput(status, formatUsageModeHumanV1(status));
+      }
+      throw new Error("Usage: owlrunkit mode <recommend|status> --workspace <directory>");
+    }
     if (command === "fleet") {
       if (action === "register-root") {
         const registered = await registerFleetCoverageRoot({
@@ -2413,6 +2760,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({
@@ -2420,7 +2801,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"))),
@@ -2439,15 +3147,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");
@@ -2463,13 +3178,25 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? applyDetectedProfilesV2({ workspaceRoot: root, detection })
           : detection;
       }
+      if (action === "reconcile") {
+        if (options.apply === true && options["dry-run"] === true) {
+          throw new Error("profiles reconcile accepts either --apply or --dry-run, not both.");
+        }
+        if (options.apply !== true && options["dry-run"] !== true) {
+          throw new Error("profiles reconcile requires --dry-run or --apply.");
+        }
+        return reconcileProfilesV2({
+          workspaceRoot: root,
+          apply: options.apply === true,
+        });
+      }
       if (action === "validate") return validateProfiles({ workspaceRoot: root });
       if (action === "impact") {
         const changedPaths = options.changed ?? [];
         if (changedPaths.length === 0) throw new Error("profiles impact requires --changed.");
         return resolveProfilesImpact({ workspaceRoot: root, changedPaths });
       }
-      throw new Error("Usage: owlrunkit profiles <detect|validate|impact> [options]");
+      throw new Error("Usage: owlrunkit profiles <detect|reconcile|validate|impact> [options]");
     }
     if (command === "lease") {
       const root = workspace(options);
@@ -2612,7 +3339,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|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]");
+    throw new Error("Usage: owlrunkit <init|doctor|adopt|mode|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",