owlrunkit 0.18.0 → 0.18.2

package/scripts/runkit-contract/quick-attest.mjs

@@ -1,4 +1,5 @@
 export {
   attestQuickReceipt,
   attestQuickReceiptDetails,
+  validQuickReceiptShape,
 } from "../../packages/attest/src/quick.mjs";

package/scripts/runkit-contract/quick-metrics.mjs

@@ -6,9 +6,40 @@ import {
 } from "node:fs";
 import path from "node:path";
 
-import { attestQuickReceipt } from "./quick-attest.mjs";
+import {
+  decodeUtf8Strict,
+  parseJsonStrict,
+  readFileBytesBounded,
+} from "../../packages/attest/src/formal.mjs";
+import { quickSnapshotFingerprintValid } from "../../packages/attest/src/quick-receipt-contract.mjs";
+import {
+  attestQuickReceipt,
+  validQuickReceiptShape,
+} from "./quick-attest.mjs";
 import { quickReceiptRoot } from "./quick-receipt.mjs";
 
+const INVALID_ATTESTATION_ISSUES = new Set([
+  "attestation_material_missing",
+  "receipt_material_hash_mismatch",
+]);
+
+function readHistoricalReceipt(receiptPath) {
+  const { bytes } = readFileBytesBounded(receiptPath);
+  const receipt = parseJsonStrict(decodeUtf8Strict(bytes));
+  if (!validQuickReceiptShape(receipt)) throw new Error("quick_receipt_schema_invalid");
+  const snapshotsValid = quickSnapshotFingerprintValid(receipt.workspaceBefore)
+    && quickSnapshotFingerprintValid(receipt.workspaceAfter);
+  const sourceChanged = receipt.workspaceBefore.sourceFingerprint
+    !== receipt.workspaceAfter.sourceFingerprint;
+  const mutationBindingValid = receipt.mutationDecision === "source_unchanged"
+    ? !sourceChanged && !receipt.issueCodes.includes("source_mutated_during_verification")
+    : sourceChanged && receipt.issueCodes.includes("source_mutated_during_verification");
+  if (!snapshotsValid || !mutationBindingValid) {
+    throw new Error("quick_receipt_source_binding_invalid");
+  }
+  return receipt;
+}
+
 function trustedReceiptRoot(workspaceRoot) {
   const workspace = realpathSync(workspaceRoot);
   const root = quickReceiptRoot(workspace);
@@ -65,10 +96,17 @@ export function readLocalQuickMetrics(workspaceRoot) {
   };
   for (const receiptPath of receiptPaths) {
     try {
-      const result = attestQuickReceipt({ receiptPath, workspaceRoot });
-      if (result.decision === "GO") totals.passed += 1;
-      else if (result.issueCodes.includes("receipt_source_mismatch")) totals.sourceMutated += 1;
-      else totals.failed += 1;
+      const receipt = readHistoricalReceipt(receiptPath);
+      const attestation = attestQuickReceipt({ receiptPath, workspaceRoot });
+      if (attestation.issueCodes.some((issue) => INVALID_ATTESTATION_ISSUES.has(issue))) {
+        totals.invalid += 1;
+      } else if (receipt.mutationDecision === "invalidated_by_command_source_mutation") {
+        totals.sourceMutated += 1;
+      } else if (receipt.exitResult.exitCode === 0 && receipt.exitResult.signal === null) {
+        totals.passed += 1;
+      } else {
+        totals.failed += 1;
+      }
     } catch {
       totals.invalid += 1;
     }

package/scripts/runkit-contract/quick-receipt.mjs

@@ -16,6 +16,8 @@ import path from "node:path";
 import { sha256Bytes } from "./quick-canonical.mjs";
 
 const QUICK_ROOT = ".owlcoda/runkit/quick";
+const OUTPUT_SUMMARY_BYTES = 16 * 1024;
+const OUTPUT_SUMMARY_LINES = 3;
 
 function withinRoot(root, candidate) {
   const remainder = path.relative(root, candidate);
@@ -87,12 +89,40 @@ export function closeQuickOutputFiles(store) {
   closeSync(store.stderrFd);
 }
 
+function cleanOutputLine(line) {
+  const withoutAnsi = line.replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, "");
+  return [...withoutAnsi]
+    .filter((character) => character === "\t" || character.codePointAt(0) >= 32)
+    .join("")
+    .trim();
+}
+
+function summarizeOutputBytes(bytes) {
+  const start = Math.max(0, bytes.byteLength - OUTPUT_SUMMARY_BYTES);
+  let text = bytes.subarray(start).toString("utf8");
+  if (start > 0) {
+    const firstLineBreak = text.indexOf("\n");
+    if (firstLineBreak >= 0) text = text.slice(firstLineBreak + 1);
+  }
+  const lines = text
+    .split(/\r?\n/u)
+    .map(cleanOutputLine)
+    .filter(Boolean);
+  return {
+    lines: lines.slice(-OUTPUT_SUMMARY_LINES),
+    truncated: start > 0 || lines.length > OUTPUT_SUMMARY_LINES,
+  };
+}
+
 function outputArtifact(workspaceRoot, filePath) {
   const bytes = readFileSync(filePath);
   return {
-    path: path.relative(realpathSync(workspaceRoot), filePath).split(path.sep).join("/"),
-    sha256: sha256Bytes(bytes),
-    sizeBytes: bytes.byteLength,
+    artifact: {
+      path: path.relative(realpathSync(workspaceRoot), filePath).split(path.sep).join("/"),
+      sha256: sha256Bytes(bytes),
+      sizeBytes: bytes.byteLength,
+    },
+    summary: summarizeOutputBytes(bytes),
   };
 }
 
@@ -119,11 +149,13 @@ function validateQuickReceiptStore(workspaceRoot, store) {
 
 export function persistQuickReceipt({ workspaceRoot, store, receipt }) {
   validateQuickReceiptStore(workspaceRoot, store);
+  const stdout = outputArtifact(workspaceRoot, store.stdoutPath);
+  const stderr = outputArtifact(workspaceRoot, store.stderrPath);
   const complete = {
     ...receipt,
     outputArtifacts: {
-      stdout: outputArtifact(workspaceRoot, store.stdoutPath),
-      stderr: outputArtifact(workspaceRoot, store.stderrPath),
+      stdout: stdout.artifact,
+      stderr: stderr.artifact,
     },
   };
   atomicWriteJson(store.receiptPath, complete);
@@ -131,6 +163,12 @@ export function persistQuickReceipt({ workspaceRoot, store, receipt }) {
     receipt: complete,
     receiptPath: store.receiptPath,
     receiptSha256: sha256Bytes(readFileSync(store.receiptPath)),
+    outputSummary: {
+      stdoutTail: stdout.summary.lines,
+      stderrTail: stderr.summary.lines,
+      stdoutTruncated: stdout.summary.truncated,
+      stderrTruncated: stderr.summary.truncated,
+    },
   };
 }
 

package/scripts/runkit-contract/quick-verify.mjs

@@ -9,6 +9,14 @@ import {
 } from "./quick-receipt.mjs";
 import { captureWorkspaceSnapshot } from "./quick-workspace-snapshot.mjs";
 
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function quickAttestCommand(workspaceRoot, receiptPath) {
+  return `owlrunkit quick-attest --workspace ${shellQuote(workspaceRoot)} --receipt ${shellQuote(receiptPath)}`;
+}
+
 function runExactCommand({ executable, argv, cwd, stdoutFd, stderrFd }) {
   return new Promise((resolve) => {
     let settled = false;
@@ -152,7 +160,10 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
     };
   }
 
+  const { outputSummary } = persisted;
+
   if (sourceMutated) {
+    const attestCommand = quickAttestCommand(root, persisted.receiptPath);
     return {
       status: "quick_verification_source_mutated",
       exitCode: 2,
@@ -162,13 +173,15 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
       commandExitCode: execution.exitCode,
       mutationDecision: "invalidated_by_command_source_mutation",
       issueCodes,
-      attestCommand: `owlcoda attest ${persisted.receiptPath}`,
+      outputSummary,
+      attestCommand,
       issues: [],
       nextAllowedAction: "restore_source_or_run_a_new_quick_verification",
       authorizationGranted: false,
     };
   }
   if (execution.launchError || execution.exitCode !== 0) {
+    const attestCommand = quickAttestCommand(root, persisted.receiptPath);
     return {
       status: "quick_verification_failed",
       exitCode: 1,
@@ -178,12 +191,14 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
       commandExitCode: execution.exitCode,
       mutationDecision: "source_unchanged",
       issueCodes,
-      attestCommand: `owlcoda attest ${persisted.receiptPath}`,
+      outputSummary,
+      attestCommand,
       issues: execution.launchError ? [execution.launchError] : [],
       nextAllowedAction: "inspect_output_and_rerun",
       authorizationGranted: false,
     };
   }
+  const attestCommand = quickAttestCommand(root, persisted.receiptPath);
   return {
     status: "quick_verification_passed",
     exitCode: 0,
@@ -193,9 +208,10 @@ export async function runQuickVerification({ workspaceRoot, commandArgv }) {
     commandExitCode: 0,
     mutationDecision: "source_unchanged",
     issueCodes,
-    attestCommand: `owlcoda attest ${persisted.receiptPath}`,
+    outputSummary,
+    attestCommand,
     issues: [],
-    nextAllowedAction: `owlcoda attest ${persisted.receiptPath}`,
+    nextAllowedAction: attestCommand,
     authorizationGranted: false,
   };
 }

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

@@ -89,6 +89,7 @@ import {
   applyDetectedProfilesV2,
   detectProfiles,
   detectProfilesV2,
+  reconcileProfilesV2,
   resolveProfilesImpact,
   validateProfiles,
 } from "./profile-onboarding.mjs";
@@ -99,7 +100,14 @@ import {
   replaceFleetRegistry,
   rollbackFleetRegistry,
 } from "./fleet-discovery.mjs";
-import { routeRunKitAssuranceV1 } from "./assurance-router.mjs";
+import {
+  RUNKIT_RISK_CATEGORIES,
+  routeRunKitAssuranceV1,
+} from "./assurance-router.mjs";
+import {
+  formatUsageModeHumanV1,
+  recommendUsageModeV1,
+} from "./usage-mode.mjs";
 import { deriveHumanStatusFromInspectV1 } from "./human-status.mjs";
 import {
   closeDeploymentExecuteChildRun,
@@ -163,20 +171,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 . [...]
@@ -204,6 +212,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>
 
@@ -215,6 +230,45 @@ 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 <${RUNKIT_RISK_CATEGORIES.join("|")}>] [--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.
+`,
+  "quick-verify": `Usage:
+  owlrunkit quick-verify --workspace <directory> [--json] -- <executable> [args...]
+
+Runs one exact command, saves source-bound stdout/stderr and a Quick receipt,
+and returns a bounded output summary. Supply the exact command after --.
+Quick evidence is not Formal acceptance and grants no repository or business authority.
 `,
   fleet: `Usage:
   owlrunkit fleet register-root --fleet-root <directory>
@@ -254,6 +308,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>
 `,
@@ -262,6 +317,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> [...]
@@ -386,6 +447,18 @@ action without granting any authority.
 Project status is derived from durable work items, Agent assignments,
 dependencies, decisions, checkpoints, integration gates, and evidence refs.
 No self-reported percentage is accepted.
+`,
+  "project checkpoint": `Usage:
+  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]
+
+Measured WorkItems require --completed-units on every checkpoint. A completed
+checkpoint must use the WorkItem's declared total. Example:
+  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 status": `Usage:
   owlrunkit project status --workspace <directory> [--json]
@@ -414,6 +487,25 @@ function withHumanOutput(result, humanOutput) {
   return result;
 }
 
+function shellCommandToken(value) {
+  const text = String(value);
+  return /^[A-Za-z0-9_@%+=:,./-]+$/u.test(text)
+    ? text
+    : `'${text.replaceAll("'", `'"'"'`)}'`;
+}
+
+function correctedCheckpointCommand(argv, completedUnits) {
+  const corrected = [...argv];
+  const jsonIndex = corrected.indexOf("--json");
+  corrected.splice(
+    jsonIndex === -1 ? corrected.length : jsonIndex,
+    0,
+    "--completed-units",
+    String(completedUnits),
+  );
+  return `owlrunkit ${corrected.map(shellCommandToken).join(" ")}`;
+}
+
 function formatTeamProjectAssignmentHuman(result) {
   const disposition = result.resumed ? "Resumed" : "Assigned";
   const nextAction = result.nextAction === null
@@ -1550,8 +1642,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" }
@@ -1563,7 +1660,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) {
@@ -1784,6 +1887,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       "fleet",
       "formal",
       "lease",
+      "mode",
       "profiles",
       "project",
     ]).has(command);
@@ -1806,7 +1910,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")
@@ -1826,7 +1932,27 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         : 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"]
@@ -1887,6 +2013,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({
@@ -2897,24 +3114,49 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
             event: requestedEvent,
           });
         }
+        const checkpointId = requireOption(options, "checkpoint-id");
+        const occurredAt = requireOption(options, "at");
+        const assignmentId = requireOption(options, "assignment-id");
+        const workItemId = requireOption(options, "work-item");
+        const state = requireOption(options, "state");
+        const summary = requireOption(options, "summary");
         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"],
-        });
+        let checkpointed;
+        try {
+          checkpointed = checkpointTeamProjectV1({
+            workspaceRoot: root,
+            checkpointId,
+            occurredAt,
+            assignmentId,
+            workItemId,
+            state,
+            summary,
+            completedUnits,
+            evidenceRefs: options.evidence ?? [],
+            blockerRefs: options.blocker ?? [],
+            decisionRefs: options.decision ?? [],
+            nextAction: options.next ?? null,
+            sourceFingerprint: options["source-fingerprint"],
+          });
+        } catch (error) {
+          if (error instanceof Error
+            && error.message === "Measured work item checkpoint requires completedUnits.") {
+            const projectStatus = readTeamProjectStatusV1({ workspaceRoot: root });
+            const workItem = projectStatus.workItems.find((row) => row.workItemId === workItemId);
+            const suggestedUnits = state === "completed"
+              ? workItem?.progress.total
+              : workItem?.progress.completed;
+            if (Number.isSafeInteger(suggestedUnits)) {
+              throw new Error(
+                "Measured work item checkpoint requires --completed-units. "
+                + `Corrected command: ${correctedCheckpointCommand(argv, suggestedUnits)}`,
+              );
+            }
+          }
+          throw error;
+        }
         return options.json === true
           ? checkpointed
           : withHumanOutput(checkpointed, formatTeamProjectCheckpointHuman(checkpointed));
@@ -3002,13 +3244,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);
@@ -3151,7 +3405,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",