owlrunkit 0.18.0 → 0.18.2

package/scripts/runkit-contract/assurance-router.mjs

@@ -6,9 +6,15 @@ const BOOLEAN_FACTS = [
   "longRunning",
   "interruptionRecovery",
   "dirtyParallelWorkspace",
+  "irreversibleChange",
+  "rollbackUncertain",
+  "permissionSensitive",
+  "securitySensitive",
+  "fundsAtRisk",
+  "schemaOrDataMigration",
 ];
 
-const RISK_CATEGORIES = new Set([
+export const RUNKIT_RISK_CATEGORIES = Object.freeze([
   "backtest",
   "deployment",
   "destructive",
@@ -20,13 +26,13 @@ const RISK_CATEGORIES = new Set([
   "release",
 ]);
 
-const FULL_RISK_CATEGORIES = new Set([
-  "deployment",
+const RISK_CATEGORIES = new Set(RUNKIT_RISK_CATEGORIES);
+
+const MATERIAL_RISK_CATEGORIES = new Set([
   "destructive",
   "foreign_write",
   "funds",
-  "production",
-  "release",
+  "migration",
 ]);
 
 function incompleteReasons(input) {
@@ -76,26 +82,21 @@ export function routeRunKitAssuranceV1(input) {
   const categories = [...new Set(input.riskCategories)].sort();
   const formalReasons = [
     ...(input.needsFormalAcceptance ? ["formal_acceptance_required"] : []),
-    ...(input.mayMutateProject ? ["project_mutation"] : []),
-    ...(input.externalSideEffects ? ["external_side_effects"] : []),
-    ...(input.longRunning ? ["long_running_execution"] : []),
-    ...(input.interruptionRecovery ? ["interruption_recovery_required"] : []),
-    ...(input.dirtyParallelWorkspace ? ["dirty_parallel_workspace"] : []),
-    ...(input.writerCount > 0 ? ["writer_scope_required"] : []),
-    ...(input.needsDurableEvidence && input.exactCommandCount === 0
-      ? ["exact_command_missing"]
-      : []),
-    ...(input.needsDurableEvidence && input.exactCommandCount > 1
-      ? ["multiple_commands"]
-      : []),
-    ...categories.map(category => `risk_${category}`),
+    ...(input.writerCount > 1 ? ["multiple_writers"] : []),
+    ...(input.permissionSensitive === true ? ["permission_sensitive"] : []),
+    ...(input.securitySensitive === true ? ["security_sensitive"] : []),
+    ...(input.fundsAtRisk === true ? ["funds_at_risk"] : []),
+    ...(input.irreversibleChange === true ? ["irreversible_change"] : []),
+    ...(input.rollbackUncertain === true ? ["rollback_uncertain"] : []),
+    ...(input.schemaOrDataMigration === true ? ["schema_or_data_migration"] : []),
+    ...categories
+      .filter(category => MATERIAL_RISK_CATEGORIES.has(category))
+      .map(category => `risk_${category}`),
   ];
   if (formalReasons.length > 0) {
-    const full = input.externalSideEffects
-      || categories.some(category => FULL_RISK_CATEGORIES.has(category));
     return result({
       lane: "formal",
-      riskMode: full ? "full" : "standard",
+      riskMode: "full",
       reasonCodes: [...new Set(formalReasons)].sort(),
       nextCommand: "owlrunkit formal start",
     });
@@ -110,6 +111,15 @@ export function routeRunKitAssuranceV1(input) {
     });
   }
 
+  if (input.exactCommandCount !== 1) {
+    return result({
+      lane: "none",
+      riskMode: "lightweight",
+      reasonCodes: ["quick_exact_command_required"],
+      nextCommand: null,
+    });
+  }
+
   return result({
     lane: "quick",
     riskMode: "lightweight",

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

@@ -14,7 +14,7 @@ import { fileURLToPath } from "node:url";
 import { parseProjectControlState } from "./project-control-parser.mjs";
 
 export const CONTRACT_VERSION = "0.2";
-export const CORE_VERSION = "0.18.0";
+export const CORE_VERSION = "0.18.2";
 export const RUNTIME_ROOT = ".owlcoda/runkit";
 
 const CORE_FILES = [
@@ -68,6 +68,7 @@ const CORE_FILES = [
   "sync-release-identity.mjs",
   "team-project-successor.mjs",
   "team-project.mjs",
+  "usage-mode.mjs",
   "verification-envelope.mjs",
   "verification-envelope-check.mjs",
   "verification-receipt-gate.mjs",
@@ -101,6 +102,8 @@ const CORE_FILES = [
   "schemas/owner-deployment-decision-v1.schema.json",
   "schemas/profile-apply-receipt-v1.schema.json",
   "schemas/profile-detection-v2.schema.json",
+  "schemas/profile-reconcile-plan-v1.schema.json",
+  "schemas/profile-reconcile-receipt-v1.schema.json",
   "schemas/project-config.schema.json",
   "schemas/project-config-v2.schema.json",
   "schemas/profiles.schema.json",
@@ -125,6 +128,7 @@ const CORE_FILES = [
   "schemas/team-project-event-v1.schema.json",
   "schemas/team-project-successor-receipt-v1.schema.json",
   "schemas/team-project-status-v1.schema.json",
+  "schemas/usage-mode-recommendation-v1.schema.json",
   "schemas/verification-envelope-v1.schema.json",
   "schemas/verification-finalize-attempt-v1.schema.json",
   "schemas/verification-preflight-v1.schema.json",

package/scripts/runkit-contract/inspect-presentation.mjs

@@ -40,7 +40,7 @@ function closeoutDecisionCounts(inspected) {
 
 export function buildInspectSummary(
   inspected,
-  { maintenanceNextAction = null } = {},
+  { maintenanceNextAction = null, projectDriver = null } = {},
 ) {
   const humanStatus = deriveHumanStatusFromInspectV1(inspected);
   const focus = selectedFocus(inspected);
@@ -80,6 +80,21 @@ export function buildInspectSummary(
     ...(inspected.controlIssues ?? []),
     ...(selectedResource?.blockers ?? []),
   ].filter((reason, index, all) => all.indexOf(reason) === index);
+  const projectGapCode = projectDriver === null
+    ? null
+    : projectDriver.dominantGap.id === null
+      ? projectDriver.dominantGap.kind
+      : `${projectDriver.dominantGap.kind}:${projectDriver.dominantGap.id}`;
+  const projectDriverSummary = projectDriver === null
+    ? null
+    : {
+        projectId: projectDriver.projectId,
+        overall: projectDriver.overall,
+        headline: projectDriver.headline,
+        dominantGap: structuredClone(projectDriver.dominantGap),
+        nextAction: projectDriver.nextAction,
+        nextActorId: projectDriver.nextActorId,
+      };
   return {
     schemaVersion: "OwlCodaRunKitInspectSummaryV1",
     currentExecution: {
@@ -139,13 +154,22 @@ export function buildInspectSummary(
       resources: [...(selectedResource?.resources ?? [])],
     },
     dominantGap: {
-      code: humanStatus.nextAllowedAction,
-      reasons: [...reasons],
+      code: projectGapCode ?? humanStatus.nextAllowedAction,
+      reasons: projectDriver === null
+        ? [...reasons]
+        : [projectDriver.dominantGap.reason].filter(Boolean),
     },
+    ...(projectDriverSummary === null ? {} : { projectDriver: projectDriverSummary }),
     lifecycleNextAction: inspected.recovery.nextAllowedAction,
     maintenanceNextAction,
     optionalReviewAction: independentHistory ? "inspect_closed_history" : null,
     nextAllowedAction: humanStatus.nextAllowedAction,
+    ...(projectDriver === null
+      ? {}
+      : {
+          recommendedNextAction:
+            projectDriver.nextAction ?? humanStatus.nextAllowedAction,
+        }),
     authorizationGranted: false,
     gitAuthorization: false,
     releaseAuthorization: false,
@@ -192,8 +216,17 @@ function summaryLines(summary, humanStatus) {
       ? `$${summary.resourcePreflight.estimate.cost.valueUsd}`
       : "unknown"}`,
     `Receipt reuse: ${summary.resourcePreflight.receiptReuse.appliedCount}/${summary.resourcePreflight.receiptReuse.reusableCount}`,
-    `Dominant gap: ${summary.dominantGap.code}`,
-    `Next allowed action: ${summary.nextAllowedAction}`,
+    ...(summary.projectDriver
+      ? [
+          `Project dominant gap: ${summary.dominantGap.code}`,
+          `Recommended next action: ${value(summary.recommendedNextAction)}`,
+          `Execution state: ${summary.currentExecution.state}`,
+          `Execution next allowed action: ${summary.nextAllowedAction}`,
+        ]
+      : [
+          `Dominant gap: ${summary.dominantGap.code}`,
+          `Next allowed action: ${summary.nextAllowedAction}`,
+        ]),
     ...(summary.maintenanceNextAction
       ? [`Maintenance: ${summary.maintenanceNextAction}`]
       : []),

package/scripts/runkit-contract/install-codex-skill.mjs

@@ -16,6 +16,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import {
+  currentCoreIdentity,
   initializeProjectRunKit,
   isDirectExecution,
   validateProjectConfigV2,
@@ -193,6 +194,64 @@ export async function inspectInstalledSkill({ targetRoot } = {}) {
   };
 }
 
+export async function inspectInstalledSkillCompatibility({ targetRoot } = {}) {
+  const integrity = await inspectInstalledSkill({ targetRoot });
+  if (!integrity.valid) {
+    return {
+      ...integrity,
+      integrityValid: false,
+      authorizationGranted: false,
+    };
+  }
+
+  const expectedCore = currentCoreIdentity();
+  let installedSkillVersion = null;
+  let installedConfigCore = null;
+  const issues = [];
+  try {
+    const skillText = await readFile(path.join(targetRoot, "SKILL.md"), "utf8");
+    installedSkillVersion = skillText.match(/standalone `owlrunkit@(\d+\.\d+\.\d+)`/u)?.[1] ?? null;
+    installedConfigCore = JSON.parse(await readFile(
+      path.join(targetRoot, "assets/templates/config.json"),
+      "utf8",
+    )).core ?? null;
+  } catch {
+    issues.push("installed_skill_version_declaration_invalid");
+  }
+
+  const installedConfigCoreVersion = installedConfigCore?.coreVersion ?? null;
+  if (installedSkillVersion === null || installedConfigCoreVersion === null) {
+    issues.push("installed_skill_core_version_declaration_missing");
+  } else if (
+    installedSkillVersion !== expectedCore.coreVersion
+    || installedConfigCoreVersion !== expectedCore.coreVersion
+  ) {
+    issues.push(
+      `installed_skill_core_version_mismatch:expected_${expectedCore.coreVersion}`
+      + `:skill_${installedSkillVersion}:config_${installedConfigCoreVersion}`,
+    );
+  } else if (!sameCoreIdentity(installedConfigCore, expectedCore)) {
+    issues.push(
+      `installed_skill_core_identity_mismatch:expected_${expectedCore.coreManifestSha256}`
+      + `:config_${installedConfigCore?.coreManifestSha256 ?? "missing"}`,
+    );
+  }
+
+  return {
+    ...integrity,
+    status: issues.length === 0 ? "valid" : "version_mismatch",
+    valid: issues.length === 0,
+    integrityValid: true,
+    expectedCoreVersion: expectedCore.coreVersion,
+    expectedCore,
+    installedSkillVersion,
+    installedConfigCoreVersion,
+    installedConfigCore,
+    issues,
+    authorizationGranted: false,
+  };
+}
+
 export async function inspectFleetForSkillChange({
   workspaceRoots = null,
   fleetManifestPath = null,
@@ -731,7 +790,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       return { exitCode: 0, ...output };
     }
     if (command === "inspect") {
-      const output = await inspectInstalledSkill({ targetRoot: options.target });
+      const output = await inspectInstalledSkillCompatibility({ targetRoot: options.target });
       return { exitCode: output.valid ? 0 : 2, ...output };
     }
     if (command === "restore") {

package/scripts/runkit-contract/onboarding-doctor.mjs

@@ -190,11 +190,16 @@ function parseJsonStrict(text) {
 export function resolveBoundedWorkspaceRoot(workspaceRoot) {
   const requested = path.resolve(workspaceRoot);
   const stat = lstatSync(requested);
-  if (
-    stat.isSymbolicLink()
-    || !stat.isDirectory()
-    || realpathSync(requested) !== requested
-  ) {
+  const resolved = realpathSync(requested);
+  if ((stat.isSymbolicLink() || resolved !== requested)
+    && lstatSync(resolved).isDirectory()) {
+    const quoted = `'${resolved.replaceAll("'", `'"'"'`)}'`;
+    throw new Error(
+      "workspace root must be a real directory without symlink ancestors. "
+      + `Retry with --workspace ${quoted}.`,
+    );
+  }
+  if (!stat.isDirectory()) {
     throw new Error("workspace root must be a real directory without symlink ancestors");
   }
   return requested;
@@ -317,28 +322,51 @@ export function readLocalInstallBinding({ workspaceRoot } = {}) {
   };
 }
 
+function registryTransportFailure(error) {
+  const code = error?.cause?.code ?? error?.code ?? null;
+  if (error?.name === "TimeoutError"
+    || error?.name === "AbortError"
+    || code === "ETIMEDOUT") {
+    return { issueCode: "registry_timeout", retryable: true };
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+    return { issueCode: "registry_dns_failed", retryable: true };
+  }
+  if (code === "ERR_INVALID_URL") {
+    return { issueCode: "registry_url_invalid", retryable: false };
+  }
+  return { issueCode: "registry_connection_failed", retryable: true };
+}
+
 export async function readRegistryExact({
   registryUrl,
   packageName = PACKAGE_NAME,
   version = EXPECTED_VERSION,
   timeoutMs = 1_500,
+  fetchImpl = fetch,
 } = {}) {
   const base = registryUrl.replace(/\/+$/, "");
   const url = `${base}/${encodeURIComponent(packageName)}/${encodeURIComponent(version)}`;
   let response;
-  try {
-    response = await fetch(url, {
-      headers: {
-        accept: "application/json",
-      },
-      redirect: "manual",
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-  } catch {
-    return {
-      status: "unavailable",
-      issueCodes: ["registry_dns_or_timeout"],
-    };
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      response = await fetchImpl(url, {
+        headers: {
+          accept: "application/json",
+        },
+        redirect: "manual",
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      break;
+    } catch (error) {
+      const failure = registryTransportFailure(error);
+      if (!failure.retryable || attempt === 1) {
+        return {
+          status: "unavailable",
+          issueCodes: [failure.issueCode],
+        };
+      }
+    }
   }
   if (response.status === 401 || response.status === 403) {
     return {
@@ -583,6 +611,24 @@ function profilesCheck(root) {
   }
 }
 
+async function doctorProfilesCheck(root) {
+  const launcherCheck = profilesCheck(root);
+  if (launcherCheck.status === "missing") return launcherCheck;
+  const { validateProfiles } = await import("./profile-onboarding.mjs");
+  const validation = validateProfiles({ workspaceRoot: root });
+  const issues = [...new Set([
+    ...(launcherCheck.launcherIssues ?? []),
+    ...validation.issues,
+  ])].sort();
+  return {
+    ...launcherCheck,
+    status: issues.length === 0 ? "ok" : "invalid",
+    validationStatus: validation.status,
+    validationIssues: validation.issues,
+    ...(issues.length > 0 ? { issues } : {}),
+  };
+}
+
 export function readProfileLauncherReadiness({ workspaceRoot } = {}) {
   const profiles = profilesCheck(resolveBoundedWorkspaceRoot(workspaceRoot));
   const launcherWarnings = profiles.launcherWarnings ?? [];
@@ -646,7 +692,7 @@ export async function runDoctor({
       });
   const nodeOk = Number(process.versions.node.split(".")[0]) >= 20;
   const config = configCheck(root);
-  const profiles = profilesCheck(root);
+  const profiles = await doctorProfilesCheck(root);
   const adoption = adoptionCheck(root, installed);
   const runtimeIsolation = runtimeIsolationCheck(root);
   const checks = {