owlrunkit 0.19.1 → 0.19.2

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

@@ -63,12 +63,21 @@ import {
   runHighLevelVerify,
 } from "./lifecycle-orchestration.mjs";
 import {
-  finalizeFormalChecksV1,
+  finalizeFormalChecksWithinControlTransaction,
   recordFormalCheckV1,
   recordFormalEnvelopeCheckV1,
   resumeCompletedFormalFinishV1,
   validateLegacyVerificationSideEffectsV1,
 } from "./formal-workflow.mjs";
+import {
+  formatFormalEnvelopePreflightHumanV1,
+  preflightFormalEnvelopeV1,
+} from "./formal-preflight.mjs";
+import {
+  attachFormalSupplementalEvidenceV1,
+  reattestFormalEvidenceSummaryV1,
+  summarizeFormalEvidenceWithinControlTransaction,
+} from "./formal-supplemental-evidence.mjs";
 import {
   freezeSourceCandidateV1,
   freezeSourceCandidateV2,
@@ -162,7 +171,7 @@ import { OFFICIAL_NPM_REGISTRY } from "./registry-adoption-gate.mjs";
 import {
   appendTeamProjectEventV1,
   assignTeamProjectV1,
-  buildTeamProjectTakeoverV2,
+  buildTeamProjectTakeoverV3,
   checkpointTeamProjectV1,
   closeTeamProjectVerificationV1,
   deferTeamProjectVerificationV1,
@@ -173,9 +182,11 @@ import {
   integrateTeamProjectV1,
   openTeamProjectDecisionV1,
   readTeamProjectStatusV2,
+  readTeamProjectStatusV3,
   rejectAndReturnTeamProjectV1,
   reopenUpstreamTeamProjectV1,
   resolveTeamProjectDecisionV1,
+  reviseTeamProjectWorkItemScopeV1,
   transferTeamProjectV1,
 } from "./team-project.mjs";
 import {
@@ -205,7 +216,7 @@ Quick Verification
   Low-risk, source-bound reusable evidence without writer leases or acceptance.
 
 Formal Delivery
-  npx --no-install owlrunkit formal <start|check|finish> --workspace . --run-id <id> [...]
+  npx --no-install owlrunkit formal <start|preflight|check|attach-evidence|finish> --workspace . --run-id <id> [...]
   Use for multi-writer, permissions, security, funds, irreversible change,
   uncertain rollback, schema/data migration, or explicit Formal acceptance.
 Frozen dirty source
@@ -222,7 +233,7 @@ Fleet and status
   npx --no-install owlrunkit fleet discover; npx --no-install owlrunkit status --workspace .
 
 Agent team projects
-  npx --no-install owlrunkit project <init|assign|checkpoint|handoff|reject-and-return|reopen-upstream|transfer|decision|verification|capture|target-snapshot|import-delivery|status|takeover|successor> [options]
+  npx --no-install owlrunkit project <init|assign|checkpoint|handoff|reject-and-return|reopen-upstream|transfer|work-item revise-scope|decision|verification|capture|target-snapshot|import-delivery|status|takeover|successor> [options]
   Durable Agent work, dependencies, decisions, gates, progress, and handoffs.
 Core successor
   npx --no-install owlrunkit core-successor <plan|apply|resume> --workspace . [...]
@@ -431,7 +442,9 @@ high-confidence unambiguous profile.
 `,
   formal: `Usage:
   npx --no-install owlrunkit formal start --workspace <directory> --run-id <id> [...]
+  npx --no-install owlrunkit formal preflight --workspace <directory> --envelope <file>
   npx --no-install owlrunkit formal check --workspace <directory> --run-id <id> -- <command>
+  npx --no-install owlrunkit formal attach-evidence --workspace <directory> --run-id <id> [...]
   npx --no-install owlrunkit formal finish --workspace <directory> --run-id <id>
 `,
   "formal start": `Usage:
@@ -439,18 +452,38 @@ high-confidence unambiguous profile.
     --goal <goal.json> --work-item <id> --owned-path <path>
 
 Creates the execution and exact writer lease.
+`,
+  "formal preflight": `Usage:
+  npx --no-install owlrunkit formal preflight --workspace <directory>
+    --envelope <verification-envelope.json> [--json]
+
+Reads the envelope, enforcement backend, known subprocess requirements, temporary
+directory needs, and protected RunKit runtime scan conflicts without executing
+the command or writing Formal evidence. It grants no authorization.
 `,
   "formal check": `Usage:
   npx --no-install owlrunkit formal check --workspace <directory> --run-id <id>
-    --work-item <id> --check-id <id> --envelope <verification-envelope.json>
+    (--work-item <id> | --from-lease <id>) --check-id <id>
+    --envelope <verification-envelope.json>
   npx --no-install owlrunkit formal check --workspace <directory> --run-id <id>
-    --work-item <id> --check-id <id> --cwd <directory> -- <built-in-command> [args...]
+    (--work-item <id> | --from-lease <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 attach-evidence": `Usage:
+  npx --no-install owlrunkit formal attach-evidence --workspace <directory>
+    --run-id <id> --evidence-id <id> --kind supplemental-local|networked
+    --receipt <quick-receipt.json> [--json]
+
+Attests one passing Quick receipt and binds it to the current Formal source
+candidate as non-gating supplemental evidence. It cannot replace a Formal check
+or grant Git, release, deployment, production, or business authorization.
 `,
   "formal finish": `Usage:
   npx --no-install owlrunkit formal finish --workspace <directory> --run-id <id>
+    [--decision accepted|rejected|blocked] [--finalize-id <id>]
 
 Runs the final source, evidence, permission, closeout, and lease-release path.
 `,
@@ -579,6 +612,13 @@ No self-reported percentage is accepted.
 Measured WorkItems require --completed-units on every checkpoint. A completed
 checkpoint must use the WorkItem's declared total. Example:
   npx --no-install owlrunkit project checkpoint --workspace . --checkpoint-id checkpoint-x --at 2026-08-11T00:00:00.000Z --assignment-id assign-x --work-item x --state completed --summary 'Completed x.' --completed-units 5 --evidence receipt:quick
+`,
+  "project init": `Usage:
+  npx --no-install owlrunkit project init --workspace <directory>
+    --definition <project-definition.json> [--json]
+
+Creates one project-owned definition and empty immutable event journal. It does
+not grant Git, release, deployment, production, or business authorization.
 `,
   "project assign": `Usage:
   npx --no-install owlrunkit project assign --workspace <directory>
@@ -588,6 +628,55 @@ checkpoint must use the WorkItem's declared total. Example:
 
 Assigns one current WorkItem owner without granting Git, release, deployment,
 production, business, or other authorization.
+`,
+  "project handoff": `Usage:
+  npx --no-install 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]
+
+Records an immutable handoff without assigning successor authority or granting
+Git, release, deployment, production, or business authorization.
+`,
+  "project decision": `Usage:
+  npx --no-install 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]
+  npx --no-install owlrunkit project decision --workspace <directory>
+    --resolve --decision-id <id> --at <ISO-UTC> --resolution <text>
+    --rationale <text> --evidence <ref> [--evidence <ref> ...] [--json]
+
+Opens or resolves one durable project decision. Resolution records truth but
+does not grant Git, release, deployment, production, or business authorization.
+`,
+  "project verification": `Usage:
+  npx --no-install 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]
+  npx --no-install 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]
+
+Records an intentionally deferred check or closes it with evidence. It does not
+execute the check and grants no additional authorization.
+`,
+  "project integrate": `Usage:
+  npx --no-install owlrunkit project integrate --workspace <directory>
+    --gate <gate-id> --at <ISO-UTC> --summary <text>
+    --evidence <ref> [--evidence <ref> ...] [--json]
+
+Records one passed integration gate after its dependencies and deferred checks
+are satisfied. It does not perform Git integration or grant release authority.
+`,
+  "project capture": `Usage:
+  npx --no-install owlrunkit project capture --workspace <directory>
+    --request <legacy-event.json> [--json]
+
+Compatibility-only raw event capture. External source delivery must use
+project import-delivery. This action grants no repository or business authority.
 `,
   "project reject-and-return": `Usage:
   npx --no-install owlrunkit project reject-and-return --workspace <directory> --rework-id <id> --at <ISO-UTC>
@@ -622,6 +711,19 @@ authority is granted.
 Atomically records checkpoint, handoff, and successor-assignment facts inside one
 immutable Event V4 envelope. Terminal WorkItems cannot transfer. No Git, release,
 deployment, production, or business authority is granted.
+`,
+  "project work-item revise-scope": `Usage:
+  npx --no-install owlrunkit project work-item revise-scope --workspace <directory>
+    --revision-id <id> --at <ISO-UTC> --assignment-id <current>
+    --work-item <id> --owner-agent <current-owner>
+    [--owned-path <path> ...]
+    [--measurable-unit <unit> --measurable-total <positive-int> | --unmeasured]
+    --reason <text> [--evidence <ref> ...] [--json]
+
+Records an immutable Event V5 that supersedes the WorkItem's prior scope. Omitted
+ownedPaths or measurable fields retain their current values. The event never
+rewrites the project definition and grants no Git, release, deployment,
+production, or business authority.
 `,
   "project target-snapshot": `Usage:
   npx --no-install owlrunkit project target-snapshot --workspace <controller>
@@ -843,7 +945,7 @@ function formatTeamProjectIntegrationHuman(result) {
     : 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})` : ""}`,
+    `Work ledger: ${result.overall}; delivery: ${result.deliveryDisposition}; next: ${nextAction}${result.nextActorId ? ` (owner ${result.nextActorId})` : ""}`,
     "Git/release not performed.",
     "",
   ].join("\n");
@@ -857,6 +959,9 @@ function formatTeamProjectCheckpointHuman(result) {
   return [
     `${disposition} checkpoint ${result.checkpointId} for WorkItem ${result.workItemId}: ${result.state}.`,
     `Project state: ${result.overall}; next: ${nextAction}${result.nextActorId ? ` (owner ${result.nextActorId})` : ""}`,
+    ...(result.warnings?.length > 0
+      ? [`Warning: ${result.warnings.map(row => row.code).join(", ")}.`]
+      : []),
     "",
   ].join("\n");
 }
@@ -1912,7 +2017,7 @@ function inspect(options) {
   const onboarding = onboardingProjection(root, recovery);
   const projectDefinitionPath = runtimePath(root, "project", "definition.json");
   const projectDriver = pathEntryExists(projectDefinitionPath)
-    ? readTeamProjectStatusV2({ workspaceRoot: root })
+    ? readTeamProjectStatusV3({ workspaceRoot: root })
     : null;
   const summary = buildInspectSummary(result, {
     maintenanceNextAction: onboarding.maintenanceNextAction ?? null,
@@ -2014,6 +2119,20 @@ function closeout(options) {
       releasedLeaseIds,
     };
   }
+  const formalEvidenceSummary = options["formal-evidence-summary"] ?? null;
+  if (
+    formalEvidenceSummary !== null
+    && (
+      decision !== "accepted"
+      || formalEvidenceSummary.status !== "formal_evidence_summarized"
+      || typeof formalEvidenceSummary.evidenceSummaryPath !== "string"
+      || !/^[a-f0-9]{64}$/u.test(
+        formalEvidenceSummary.evidenceSummarySha256 ?? "",
+      )
+    )
+  ) {
+    throw new Error("Formal evidence summary binding is invalid for closeout.");
+  }
   const created = createCoreArtifact({
     core: pin,
     producer: { adapterKind: "codex", adapterVersion: "0.1.0" },
@@ -2023,7 +2142,24 @@ function closeout(options) {
       authorizationGranted: false,
       ...(acceptedVerification ? { verification: acceptedVerification } : {}),
     },
-    extensions: { "dev.owlcoda.adapter.codex": {} },
+    extensions: {
+      "dev.owlcoda.adapter.codex": {},
+      ...(formalEvidenceSummary === null
+        ? {}
+        : {
+          "dev.owlcoda.formal-evidence": {
+            schemaVersion: "OwlCodaRunKitFormalEvidenceCloseoutBindingV1",
+            summaryPath: formalEvidenceSummary.evidenceSummaryPath,
+            summarySha256: formalEvidenceSummary.evidenceSummarySha256,
+            formalCheckCount: formalEvidenceSummary.formalCheckCount,
+            supplementalEvidenceCount:
+              formalEvidenceSummary.supplementalEvidenceCount,
+            staleSupplementalEvidenceCount:
+              formalEvidenceSummary.staleSupplementalEvidenceCount,
+            authorizationGranted: false,
+          },
+        }),
+    },
   });
   const closeoutPath = path.join(executionRoot, "closeout-receipt.json");
   writeJsonExclusiveAtomically(closeoutPath, created);
@@ -2038,15 +2174,16 @@ function closeout(options) {
   return { status: "closed", exitCode: 0, runId, decision, authorizationGranted: false, ...created };
 }
 
-function finishExecution(options) {
+function finishExecutionWithinControlTransaction(options, {
+  formalEvidenceSummary = null,
+} = {}) {
   const root = workspace(options);
   const runId = safeRunId(requireOption(options, "run-id"));
   const decision = requireOption(options, "decision");
   if (!new Set(["accepted", "rejected", "blocked"]).has(decision)) {
     throw new Error("decision must be accepted, rejected, or blocked.");
   }
-  return withControlTransaction(root, () => {
-    const executionRoot = runtimePath(root, "executions", runId);
+  const executionRoot = runtimePath(root, "executions", runId);
     const closeoutPath = path.join(executionRoot, "closeout-receipt.json");
     if (pathEntryExists(closeoutPath)) {
       if (lstatSync(closeoutPath).isSymbolicLink()) {
@@ -2090,6 +2227,9 @@ function finishExecution(options) {
       closed = closeout({
         ...options,
         ...(gate ? { "gate-input": gate.gateInputPath } : {}),
+        ...(formalEvidenceSummary === null
+          ? {}
+          : { "formal-evidence-summary": formalEvidenceSummary }),
       });
       if (closed.status !== "closed") {
         rollbackReleasedLeases();
@@ -2109,7 +2249,14 @@ function finishExecution(options) {
       closeoutArtifactSha256: closed.artifactSha256,
       authorizationGranted: false,
     };
-  });
+}
+
+function finishExecution(options) {
+  const root = workspace(options);
+  return withControlTransaction(
+    root,
+    () => finishExecutionWithinControlTransaction(options),
+  );
 }
 
 function requestCommand(options, handler) {
@@ -2161,7 +2308,12 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       "profiles",
       "project",
     ]).has(command);
-    const [action, ...nestedOptions] = nested ? optionValues : [null, ...optionValues];
+    let [action, ...nestedOptions] = nested ? optionValues : [null, ...optionValues];
+    if (command === "project" && action === "work-item"
+      && nestedOptions[0] === "revise-scope") {
+      action = "work-item revise-scope";
+      nestedOptions = nestedOptions.slice(1);
+    }
     const helpRequested = optionValues.includes("--help")
       || optionValues.includes("-h");
     if (helpRequested) {
@@ -2213,6 +2365,8 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? ["evidence", "blocker", "decision"]
         : command === "project" && action === "decision"
           ? ["blocking-work-item", "option", "evidence"]
+        : command === "project" && action === "work-item revise-scope"
+          ? ["owned-path", "evidence"]
         : command === "efficiency" && action === "record"
           ? ["evidence"]
           : [],
@@ -2242,11 +2396,15 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? ["json"]
         : command === "bootstrap"
           ? ["json", "dry-run", "apply"]
+        : command === "formal" && new Set(["preflight", "attach-evidence"]).has(action)
+          ? ["json"]
         : command === "project" && action === "decision"
           ? ["json", "open", "resolve"]
         : command === "project" && action === "verification"
           ? ["json", "defer", "close"]
-        : command === "project" && new Set(["assign", "handoff", "reject-and-return", "reopen-upstream", "transfer", "checkpoint", "integrate", "status", "takeover", "successor"]).has(action)
+        : command === "project" && action === "work-item revise-scope"
+          ? ["json", "unmeasured"]
+        : command === "project" && new Set(["init", "assign", "handoff", "reject-and-return", "reopen-upstream", "transfer", "checkpoint", "integrate", "capture", "status", "takeover", "successor"]).has(action)
           ? ["json"]
         : command === "project" && new Set(["target-snapshot", "import-delivery"]).has(action)
           ? ["json", "dry-run", "apply"]
@@ -2361,6 +2519,10 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         ]);
         const recommendation = recommendUsageModeV2({
           workspaceRoot: root,
+          projectDriverPresent: existsSync(path.join(
+            root,
+            ".owlcoda/runkit/project/definition.json",
+          )),
           requestedMode: options["requested-mode"] ?? "auto",
           needsDurableEvidence: options["needs-evidence"] === true,
           exactCommandCount: parseCanonicalNonnegativeSafeInteger(
@@ -2394,6 +2556,10 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         assertOnlyOptions(options, ["workspace", "json"]);
         const recommendation = recommendUsageModeV2({
           workspaceRoot: root,
+          projectDriverPresent: existsSync(path.join(
+            root,
+            ".owlcoda/runkit/project/definition.json",
+          )),
           requestedMode: "auto",
           needsDurableEvidence: false,
           exactCommandCount: 0,
@@ -2974,12 +3140,37 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       throw new Error("Usage: npx --no-install owlrunkit deployment <prepare|execute> [options]");
     }
     if (command === "formal") {
+      const allowedFormalOptions = {
+        start: ["workspace", "run-id", "goal", "work-item", "owned-path"],
+        preflight: ["workspace", "envelope", "json"],
+        check: ["workspace", "run-id", "work-item", "from-lease", "check-id", "envelope", "cwd"],
+        "attach-evidence": ["workspace", "run-id", "evidence-id", "kind", "receipt", "json"],
+        finish: ["workspace", "run-id", "decision", "finalize-id"],
+      };
+      if (!Object.hasOwn(allowedFormalOptions, action)) {
+        throw new Error("Usage: npx --no-install owlrunkit formal <start|preflight|check|attach-evidence|finish> [options]");
+      }
+      assertOnlyOptions(options, allowedFormalOptions[action]);
       if (action === "start") {
         return startExecution({
           ...options,
           "work-item": options["work-item"] ?? "delivery",
         });
       }
+      if (action === "preflight") {
+        const root = workspace(options);
+        const envelope = readJson(realpathSync(requireOption(options, "envelope")));
+        const preflight = preflightFormalEnvelopeV1({
+          workspaceRoot: root,
+          envelope,
+        });
+        return options.json === true
+          ? preflight
+          : withHumanOutput(
+              preflight,
+              formatFormalEnvelopePreflightHumanV1(preflight),
+            );
+      }
       if (action === "check") {
         const workItemId = options["work-item"] ?? options["from-lease"] ?? "delivery";
         if (
@@ -2993,12 +3184,17 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           if (commandArgv.length > 0) {
             throw new Error("formal check accepts either --envelope or an exact built-in command, not both.");
           }
+          if (options.cwd !== undefined) {
+            throw new Error("formal check --cwd is only valid with an exact built-in command.");
+          }
+          const root = workspace(options);
+          const envelope = readJson(realpathSync(requireOption(options, "envelope")));
           return await recordFormalEnvelopeCheckV1({
-            workspaceRoot: workspace(options),
+            workspaceRoot: root,
             runId: safeRunId(requireOption(options, "run-id")),
             workItemId,
             checkId: requireOption(options, "check-id"),
-            envelope: readJson(realpathSync(requireOption(options, "envelope"))),
+            envelope,
           });
         }
         return recordFormalCheckV1({
@@ -3010,6 +3206,15 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           commandArgv,
         });
       }
+      if (action === "attach-evidence") {
+        return attachFormalSupplementalEvidenceV1({
+          workspaceRoot: workspace(options),
+          runId: safeRunId(requireOption(options, "run-id")),
+          evidenceId: requireOption(options, "evidence-id"),
+          kind: requireOption(options, "kind"),
+          receiptPath: requireOption(options, "receipt"),
+        });
+      }
       if (action === "finish") {
         const decision = options.decision ?? "accepted";
         if (!new Set(["accepted", "rejected", "blocked"]).has(decision)) {
@@ -3024,36 +3229,92 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           finalizeId,
           decision,
         });
-        if (resumed !== null) return resumed;
-        let finalized = null;
-        if (decision === "accepted") {
-          finalized = finalizeFormalChecksV1({
-            workspaceRoot: root,
-            runId,
-            finalizeId,
-          });
-          if (finalized.status !== "accepted_passed") return finalized;
+        if (resumed !== null) {
+          const evidenceSummary = decision === "accepted"
+              ? reattestFormalEvidenceSummaryV1({
+                workspaceRoot: root,
+                runId,
+                summaryId: `${finalizeId}-evidence`,
+              })
+            : null;
+          if (
+            resumed.formalEvidenceBinding !== null
+            && (
+              evidenceSummary === null
+              || evidenceSummary.evidenceSummaryPath
+                !== resumed.formalEvidenceBinding.summaryPath
+              || evidenceSummary.evidenceSummarySha256
+                !== resumed.formalEvidenceBinding.summarySha256
+              || evidenceSummary.formalCheckCount
+                !== resumed.formalEvidenceBinding.formalCheckCount
+              || evidenceSummary.supplementalEvidenceCount
+                !== resumed.formalEvidenceBinding.supplementalEvidenceCount
+              || evidenceSummary.staleSupplementalEvidenceCount
+                !== resumed.formalEvidenceBinding.staleSupplementalEvidenceCount
+            )
+          ) {
+            throw new Error(
+              "Existing closeout does not match its Formal evidence summary.",
+            );
+          }
+          const { formalEvidenceBinding: _formalEvidenceBinding, ...resumedResult } = resumed;
+          return {
+            ...resumedResult,
+            supplementalEvidenceCount:
+              evidenceSummary?.supplementalEvidenceCount ?? 0,
+            staleSupplementalEvidenceCount:
+              evidenceSummary?.staleSupplementalEvidenceCount ?? 0,
+            evidenceSummaryPath: evidenceSummary?.evidenceSummaryPath,
+            evidenceSummarySha256: evidenceSummary?.evidenceSummarySha256,
+          };
         }
-        const finished = finishExecution({
-          ...options,
-          decision,
+        return withControlTransaction(root, () => {
+          let finalized = null;
+          let evidenceSummary = null;
+          if (decision === "accepted") {
+            finalized = finalizeFormalChecksWithinControlTransaction({
+              workspaceRoot: root,
+              runId,
+              finalizeId,
+            });
+            if (finalized.status !== "accepted_passed") return finalized;
+            evidenceSummary = summarizeFormalEvidenceWithinControlTransaction({
+              workspaceRoot: root,
+              runId,
+              summaryId: `${finalizeId}-evidence`,
+            });
+            if (evidenceSummary.status !== "formal_evidence_summarized") {
+              return evidenceSummary;
+            }
+          }
+          const finished = finishExecutionWithinControlTransaction({
+            ...options,
+            decision,
+          }, { formalEvidenceSummary: evidenceSummary });
+          if (finished.status !== "finished") return finished;
+          return {
+            status: "formal_finished",
+            exitCode: 0,
+            runId: finished.runId,
+            decision,
+            snapshotCount: finalized?.snapshotCount ?? 0,
+            staleCheckCount: finalized?.staleCheckCount ?? 0,
+            supplementalEvidenceCount:
+              evidenceSummary?.supplementalEvidenceCount ?? 0,
+            staleSupplementalEvidenceCount:
+              evidenceSummary?.staleSupplementalEvidenceCount ?? 0,
+            evidenceSummaryPath: evidenceSummary?.evidenceSummaryPath ?? null,
+            evidenceSummarySha256:
+              evidenceSummary?.evidenceSummarySha256 ?? null,
+            sourceFingerprint: finalized?.sourceFingerprint ?? null,
+            activeReceiptSha256: finished.activeReceiptSha256,
+            closeoutArtifactSha256: finished.closeoutArtifactSha256,
+            releasedLeaseIds: finished.releasedLeaseIds,
+            authorizationGranted: false,
+          };
         });
-        if (finished.status !== "finished") return finished;
-        return {
-          status: "formal_finished",
-          exitCode: 0,
-          runId: finished.runId,
-          decision,
-          snapshotCount: finalized?.snapshotCount ?? 0,
-          staleCheckCount: finalized?.staleCheckCount ?? 0,
-          sourceFingerprint: finalized?.sourceFingerprint ?? null,
-          activeReceiptSha256: finished.activeReceiptSha256,
-          closeoutArtifactSha256: finished.closeoutArtifactSha256,
-          releasedLeaseIds: finished.releasedLeaseIds,
-          authorizationGranted: false,
-        };
       }
-      throw new Error("Usage: npx --no-install owlrunkit formal <start|check|finish> [options]");
+      throw new Error("Usage: npx --no-install owlrunkit formal <start|preflight|check|attach-evidence|finish> [options]");
     }
     if (command === "candidate") {
       if (action === "freeze") {
@@ -3123,7 +3384,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
     }
     if (command === "project") {
       const allowedProjectOptions = {
-        init: ["workspace", "definition"],
+        init: ["workspace", "definition", "json"],
         assign: [
           "workspace", "request", "assignment-id", "at", "work-item", "agent",
           "supersedes", "execution-run-id", "execution-work-item", "json",
@@ -3145,6 +3406,11 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           "from-agent", "to-agent", "state", "summary", "completed-units",
           "evidence", "blocker", "decision", "next", "source-fingerprint", "json",
         ],
+        "work-item revise-scope": [
+          "workspace", "revision-id", "at", "assignment-id", "work-item",
+          "owner-agent", "owned-path", "measurable-unit", "measurable-total",
+          "unmeasured", "reason", "evidence", "json",
+        ],
         decision: [
           "workspace", "request", "open", "resolve", "decision-id", "at", "title",
           "question", "owner-agent", "blocking-work-item", "option", "resolution",
@@ -3161,7 +3427,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           "disposition", "summary", "evidence", "decision", "json",
         ],
         integrate: ["workspace", "request", "gate", "at", "summary", "evidence", "json"],
-        capture: ["workspace", "request"],
+        capture: ["workspace", "request", "json"],
         "target-snapshot": [
           "workspace", "snapshot-id", "at", "work-item", "target-workspace",
           "allowed-path", "dry-run", "apply", "json",
@@ -3371,6 +3637,56 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? transferred
           : withHumanOutput(transferred, formatTeamProjectTransferHuman(transferred));
       }
+      if (action === "work-item revise-scope") {
+        const currentStatus = readTeamProjectStatusV3({ workspaceRoot: root });
+        const workItemId = requireOption(options, "work-item");
+        const currentWorkItem = currentStatus.workItems.find(
+          row => row.workItemId === workItemId,
+        );
+        if (!currentWorkItem) throw new Error(`Unknown team project WorkItem: ${workItemId}.`);
+        const hasUnit = options["measurable-unit"] !== undefined;
+        const hasTotal = options["measurable-total"] !== undefined;
+        if (options.unmeasured === true && (hasUnit || hasTotal)) {
+          throw new Error("--unmeasured cannot be combined with measurable-unit or measurable-total.");
+        }
+        if (hasUnit !== hasTotal) {
+          throw new Error("measurable-unit and measurable-total must be supplied together.");
+        }
+        const measurable = options.unmeasured === true
+          ? null
+          : hasUnit
+            ? {
+                unit: requireOption(options, "measurable-unit"),
+                total: parseCanonicalNonnegativeSafeInteger(
+                  requireOption(options, "measurable-total"),
+                  "measurable-total",
+                ),
+              }
+            : currentWorkItem.measurable;
+        if (measurable?.total === 0) {
+          throw new Error("measurable-total must be a positive safe integer.");
+        }
+        const revised = reviseTeamProjectWorkItemScopeV1({
+          workspaceRoot: root,
+          revisionId: requireOption(options, "revision-id"),
+          occurredAt: requireOption(options, "at"),
+          assignmentId: requireOption(options, "assignment-id"),
+          workItemId,
+          ownerAgentId: requireOption(options, "owner-agent"),
+          ownedPaths: options["owned-path"] ?? currentWorkItem.ownedPaths,
+          measurable,
+          reason: requireOption(options, "reason"),
+          evidenceRefs: options.evidence ?? [],
+        });
+        return options.json === true
+          ? revised
+          : withHumanOutput(revised, [
+              `Revised WorkItem ${revised.workItemId} scope as ${revised.revisionId}.`,
+              `Owned paths: ${revised.ownedPaths.join(", ")}.`,
+              "Project definition remains immutable; no Git or release authority was granted.",
+              "",
+            ].join("\n"));
+      }
       if (action === "decision") {
         const directDecisionFields = [
           "open",
@@ -3667,13 +3983,13 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         });
       }
       if (action === "status") {
-        const status = readTeamProjectStatusV2({ workspaceRoot: root });
+        const status = readTeamProjectStatusV3({ workspaceRoot: root });
         return options.json === true
           ? status
           : withHumanOutput(status, formatTeamProjectStatusHumanV2(status));
       }
       if (action === "takeover") {
-        const takeover = buildTeamProjectTakeoverV2({
+        const takeover = buildTeamProjectTakeoverV3({
           workspaceRoot: root,
           agentId: requireOption(options, "agent"),
         });
@@ -3694,7 +4010,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? successor
           : withHumanOutput(successor, formatTeamProjectSuccessorHumanV1(successor));
       }
-      throw new Error("Usage: npx --no-install owlrunkit project <init|assign|checkpoint|handoff|reject-and-return|reopen-upstream|transfer|decision|verification|integrate|capture|target-snapshot|import-delivery|status|takeover|successor> [options]");
+      throw new Error("Usage: npx --no-install owlrunkit project <init|assign|checkpoint|handoff|reject-and-return|reopen-upstream|transfer|work-item revise-scope|decision|verification|integrate|capture|target-snapshot|import-delivery|status|takeover|successor> [options]");
     }
     if (command === "profiles") {
       const root = requireOption(options, "workspace");