owlrunkit 0.22.0 → 0.23.0

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

@@ -195,7 +195,6 @@ import {
   openTeamProjectDecisionV1,
   readTeamProjectStatusV2,
   readTeamProjectStatusV3,
-  readTeamProjectStatusV4,
   reconcileExternalGateV1,
   recordDeliveryLifecycleV1,
   rejectAndReturnTeamProjectV1,
@@ -205,6 +204,11 @@ import {
   setWorkItemEvidenceRequirementV1,
   transferTeamProjectV1,
 } from "./team-project.mjs";
+import {
+  buildSuccessorScaffoldV1,
+  formatSuccessorScaffoldHumanV1,
+  readTeamProjectStatusV5,
+} from "./project-completion-continuity.mjs";
 import {
   formatTeamProjectSuccessorHumanV1,
   successorTeamProjectV1,
@@ -258,7 +262,7 @@ Fleet and status
   npx --no-install owlrunkit fleet discover; npx --no-install owlrunkit status --workspace .
   npx --no-install owlrunkit hook recovery --workspace . --json
 Agent team projects
-  npx --no-install owlrunkit project <init|assign|checkpoint|handoff|reject-and-return|reopen-upstream|transfer|work-item revise-scope|work-item require-evidence|reconcile|delivery record|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|work-item require-evidence|reconcile|delivery record|decision|verification|capture|target-snapshot|import-delivery|status|takeover|successor|successor scaffold> [options]
   npx --no-install owlrunkit team <recommend|status|packet validate> [options]
   Durable project truth plus read-only Team recommendation and packet validation. No Agent dispatch.
 Core successor: npx --no-install owlrunkit core-successor <plan|apply|resume> --workspace . [...]
@@ -741,6 +745,8 @@ action without granting any authority.
   npx --no-install owlrunkit project takeover --workspace <directory> --agent <id> [--json]
   npx --no-install owlrunkit project successor --workspace <directory> --transition-id <id> --at <ISO-UTC>
     --definition <project.json> --reason <text> [--json]
+  npx --no-install owlrunkit project successor scaffold --workspace <directory>
+    --from-workspace <git-worktree> --dry-run [--json]
 
 Project status is derived from durable work items, Agent assignments,
 dependencies, decisions, checkpoints, integration gates, and evidence refs.
@@ -909,6 +915,16 @@ Builds a read-only blank-session recovery packet for one Agent.
 
 Archives one derived-completed active project and installs one fresh active
 project with no inherited events. The receipt grants no repository or release authority.
+`,
+  "project successor scaffold": `Usage:
+  npx --no-install owlrunkit project successor scaffold --workspace <directory>
+    --from-workspace <git-worktree> --dry-run [--json]
+
+Reads one completed Project Driver ledger, its latest explicitly imported source
+delivery baseline, and the exact current Git worktree. It reports terminal,
+baseline-missing, or unmodeled-drift truth plus review-only path lanes. It does
+not create a project, append an event, infer an objective, dispatch an Agent, or
+grant Git, release, deployment, production, or business authority.
 `,
 });
 
@@ -2169,7 +2185,7 @@ function inspect(options) {
   const onboarding = onboardingProjection(root, recovery);
   const projectDefinitionPath = runtimePath(root, "project", "definition.json");
   const projectDriver = pathEntryExists(projectDefinitionPath)
-    ? readTeamProjectStatusV3({ workspaceRoot: root })
+    ? readTeamProjectStatusV5({ workspaceRoot: root })
     : null;
   const localMaintenance = options.compact === true
     ? inspectLocalMaintenanceV1({
@@ -2487,6 +2503,11 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       action = "delivery record";
       nestedOptions = nestedOptions.slice(1);
     }
+    if (command === "project" && action === "successor"
+      && nestedOptions[0] === "scaffold") {
+      action = "successor scaffold";
+      nestedOptions = nestedOptions.slice(1);
+    }
     if (command === "team" && action === "packet"
       && nestedOptions[0] === "validate") {
       action = "packet validate";
@@ -2596,6 +2617,8 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
           ? ["json"]
         : command === "project" && new Set(["init", "assign", "handoff", "reject-and-return", "reopen-upstream", "transfer", "checkpoint", "integrate", "capture", "reconcile", "delivery record", "status", "takeover", "successor"]).has(action)
           ? ["json"]
+        : command === "project" && action === "successor scaffold"
+          ? ["json", "dry-run"]
         : command === "project" && new Set(["target-snapshot", "import-delivery"]).has(action)
           ? ["json", "dry-run", "apply"]
           : command === "doctor" || command === "adopt" || command === "status"
@@ -3722,6 +3745,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         status: ["workspace", "json"],
         takeover: ["workspace", "agent", "json"],
         successor: ["workspace", "transition-id", "at", "definition", "reason", "json"],
+        "successor scaffold": ["workspace", "from-workspace", "dry-run", "json"],
       };
       if (Object.hasOwn(allowedProjectOptions, action)) {
         assertOnlyOptions(options, allowedProjectOptions[action]);
@@ -4361,7 +4385,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         });
       }
       if (action === "status") {
-        const status = readTeamProjectStatusV4({ workspaceRoot: root });
+        const status = readTeamProjectStatusV5({ workspaceRoot: root });
         return options.json === true
           ? status
           : withHumanOutput(status, formatTeamProjectStatusHumanV2(status));
@@ -4388,7 +4412,19 @@ 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|work-item revise-scope|reconcile|delivery record|decision|verification|integrate|capture|target-snapshot|import-delivery|status|takeover|successor> [options]");
+      if (action === "successor scaffold") {
+        if (options["dry-run"] !== true) {
+          throw new Error("project successor scaffold requires --dry-run.");
+        }
+        const scaffold = buildSuccessorScaffoldV1({
+          workspaceRoot: root,
+          fromWorkspaceRoot: requireOption(options, "from-workspace"),
+        });
+        return options.json === true
+          ? scaffold
+          : withHumanOutput(scaffold, formatSuccessorScaffoldHumanV1(scaffold));
+      }
+      throw new Error("Usage: npx --no-install owlrunkit project <init|assign|checkpoint|handoff|reject-and-return|reopen-upstream|transfer|work-item revise-scope|reconcile|delivery record|decision|verification|integrate|capture|target-snapshot|import-delivery|status|takeover|successor|successor scaffold> [options]");
     }
     if (command === "profiles") {
       const root = requireOption(options, "workspace");

package/scripts/runkit-contract/schemas/fleet-skill-upgrade-plan-v1.schema.json

@@ -42,7 +42,20 @@
             "source": { "type": "string", "minLength": 1 },
             "complete": { "type": "boolean" },
             "workspaceCount": { "type": "integer", "minimum": 0 },
-            "unreachableRoots": { "$ref": "#/$defs/strings" }
+            "unreachableRoots": { "$ref": "#/$defs/strings" },
+            "issues": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["code", "path", "coverageRoot"],
+                "properties": {
+                  "code": { "type": "string", "minLength": 1 },
+                  "path": { "type": "string", "minLength": 1 },
+                  "coverageRoot": { "type": "string", "minLength": 1 }
+                }
+              }
+            }
           }
         }
       ]
@@ -102,7 +115,7 @@
       "status": "blocked",
       "expectedCore": {
         "contractVersion": "0.2",
-        "coreVersion": "0.22.0",
+        "coreVersion": "0.23.0",
         "coreManifestSha256": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
         "coreSourceRef": "artifact:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
       },
@@ -113,7 +126,7 @@
         "installedConfigCoreVersion": "0.20.0",
         "issues": ["installed_skill_core_version_mismatch"]
       },
-      "discovery": { "source": "fleet_registry", "complete": true, "workspaceCount": 1, "unreachableRoots": [] },
+      "discovery": { "source": "fleet_registry", "complete": true, "workspaceCount": 1, "unreachableRoots": [], "issues": [] },
       "affectedProjects": [
         {
           "workspaceRoot": "/projects/example",

package/scripts/runkit-contract/schemas/project-completion-continuity-v1.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.com/schemas/runkit/project-completion-continuity-v1.schema.json",
+  "title": "OwlCoda RunKit Project Completion Continuity V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "status", "projectId", "projectTruthHash", "disposition",
+    "targetWorkspaceRef", "baseline", "current", "delta", "nextAction",
+    "readOnly", "writesPerformed", "authorityBoundary", "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitProjectCompletionContinuityV1" },
+    "status": { "enum": ["not_applicable", "baseline_missing", "source_unverifiable", "workspace_drift", "terminal"] },
+    "projectId": { "$ref": "#/$defs/text" },
+    "projectTruthHash": { "$ref": "#/$defs/hash" },
+    "disposition": {
+      "enum": [
+        "project_work_ledger_incomplete",
+        "completed_project_source_baseline_missing",
+        "completed_project_source_unverifiable",
+        "completed_project_with_unmodeled_workspace_drift",
+        "completed_project_terminal"
+      ]
+    },
+    "targetWorkspaceRef": { "$ref": "#/$defs/nullableText" },
+    "baseline": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "deliveryId", "occurredAt", "targetHead", "workspaceSnapshotFingerprint", "truthRef"],
+          "properties": {
+            "kind": { "const": "imported_source_delivery" },
+            "deliveryId": { "$ref": "#/$defs/text" },
+            "occurredAt": { "$ref": "#/$defs/text" },
+            "targetHead": { "$ref": "#/$defs/gitHash" },
+            "workspaceSnapshotFingerprint": { "$ref": "#/$defs/hashRef" },
+            "truthRef": { "$ref": "#/$defs/text" }
+          }
+        }
+      ]
+    },
+    "current": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["headCommit", "workspaceSnapshotFingerprint"],
+          "properties": {
+            "headCommit": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/gitHash" }] },
+            "workspaceSnapshotFingerprint": { "$ref": "#/$defs/hashRef" }
+          }
+        }
+      ]
+    },
+    "delta": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "baselineHead", "currentHead", "headChanged", "trackedTreeChanged",
+            "submodulesChanged", "committedPaths", "overlayPaths",
+            "dependencyEnvironmentPaths", "changedPaths", "changedPathCount",
+            "changedPathsTruncated", "pathEvidenceComplete"
+          ],
+          "properties": {
+            "baselineHead": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/gitHash" }] },
+            "currentHead": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/gitHash" }] },
+            "headChanged": { "type": "boolean" },
+            "trackedTreeChanged": { "type": "boolean" },
+            "submodulesChanged": { "type": "boolean" },
+            "committedPaths": { "$ref": "#/$defs/paths" },
+            "overlayPaths": { "$ref": "#/$defs/paths" },
+            "dependencyEnvironmentPaths": { "$ref": "#/$defs/paths" },
+            "changedPaths": { "$ref": "#/$defs/paths" },
+            "changedPathCount": { "type": "integer", "minimum": 0 },
+            "changedPathsTruncated": { "type": "boolean" },
+            "pathEvidenceComplete": { "type": "boolean" }
+          }
+        }
+      ]
+    },
+    "nextAction": { "$ref": "#/$defs/nullableText" },
+    "readOnly": { "const": true },
+    "writesPerformed": { "const": false },
+    "authorityBoundary": { "$ref": "#/$defs/authorityBoundary" },
+    "authorizationGranted": { "const": false }
+  },
+  "examples": [
+    {
+      "schemaVersion": "OwlCodaRunKitProjectCompletionContinuityV1",
+      "status": "baseline_missing",
+      "projectId": "completed-project",
+      "projectTruthHash": "0000000000000000000000000000000000000000000000000000000000000000",
+      "disposition": "completed_project_source_baseline_missing",
+      "targetWorkspaceRef": null,
+      "baseline": null,
+      "current": null,
+      "delta": null,
+      "nextAction": "Review the current workspace and bind an explicit source baseline before deciding whether the project is terminal.",
+      "readOnly": true,
+      "writesPerformed": false,
+      "authorityBoundary": {
+        "agentDispatch": false,
+        "git": false,
+        "release": false,
+        "deployment": false,
+        "production": false,
+        "business": false,
+        "automation": false,
+        "money": false
+      },
+      "authorizationGranted": false
+    }
+  ],
+  "$defs": {
+    "text": { "type": "string", "minLength": 1 },
+    "nullableText": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/text" }] },
+    "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "hashRef": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "gitHash": { "type": "string", "pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$" },
+    "paths": { "type": "array", "maxItems": 256, "uniqueItems": true, "items": { "$ref": "#/$defs/text" } },
+    "authorityBoundary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["agentDispatch", "git", "release", "deployment", "production", "business", "automation", "money"],
+      "properties": {
+        "agentDispatch": { "const": false },
+        "git": { "const": false },
+        "release": { "const": false },
+        "deployment": { "const": false },
+        "production": { "const": false },
+        "business": { "const": false },
+        "automation": { "const": false },
+        "money": { "const": false }
+      }
+    }
+  }
+}

package/scripts/runkit-contract/schemas/successor-scaffold-v1.schema.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.com/schemas/runkit/successor-scaffold-v1.schema.json",
+  "title": "OwlCoda RunKit Successor Scaffold V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "status", "exitCode", "project", "completionContinuity",
+    "unmodeledCandidates", "pathConflicts", "possibleLanes", "draft",
+    "nextAction", "persisted", "readOnly", "writesPerformed",
+    "authorityBoundary", "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitSuccessorScaffoldV1" },
+    "status": { "enum": ["successor_review_required", "successor_baseline_missing", "successor_not_required", "successor_source_unverifiable"] },
+    "exitCode": { "const": 0 },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["projectId", "projectTruthHash", "overall"],
+      "properties": {
+        "projectId": { "$ref": "#/$defs/text" },
+        "projectTruthHash": { "$ref": "#/$defs/hash" },
+        "overall": { "const": "completed" }
+      }
+    },
+    "completionContinuity": { "$ref": "project-completion-continuity-v1.schema.json" },
+    "unmodeledCandidates": {
+      "type": "array",
+      "maxItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["candidateId", "kind", "targetWorkspaceRef", "baselineFingerprint", "currentFingerprint", "changedPaths", "changedPathCount", "changedPathsTruncated", "pathEvidenceComplete"],
+        "properties": {
+          "candidateId": { "const": "workspace-drift" },
+          "kind": { "const": "workspace_source_delta" },
+          "targetWorkspaceRef": { "$ref": "#/$defs/text" },
+          "baselineFingerprint": { "$ref": "#/$defs/hashRef" },
+          "currentFingerprint": { "$ref": "#/$defs/hashRef" },
+          "changedPaths": { "$ref": "#/$defs/paths" },
+          "changedPathCount": { "type": "integer", "minimum": 0 },
+          "changedPathsTruncated": { "type": "boolean" },
+          "pathEvidenceComplete": { "type": "boolean" }
+        }
+      }
+    },
+    "pathConflicts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "historicalWorkItemIds"],
+        "properties": {
+          "path": { "$ref": "#/$defs/text" },
+          "historicalWorkItemIds": { "$ref": "#/$defs/nonemptyStrings" }
+        }
+      }
+    },
+    "possibleLanes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["laneId", "basis", "historicalWorkItemId", "suggestedOwnedPaths", "requiresHumanConfirmation"],
+        "properties": {
+          "laneId": { "$ref": "#/$defs/text" },
+          "basis": { "enum": ["historical_owned_paths_only", "unmatched_paths_only"] },
+          "historicalWorkItemId": { "$ref": "#/$defs/nullableText" },
+          "suggestedOwnedPaths": { "$ref": "#/$defs/nonemptyStrings" },
+          "requiresHumanConfirmation": { "const": true }
+        }
+      }
+    },
+    "draft": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["projectId", "objective", "workItems", "requiresHumanConfirmation"],
+      "properties": {
+        "projectId": { "type": "null" },
+        "objective": { "type": "null" },
+        "workItems": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["draftLaneId", "title", "ownedPaths", "ownerAgentId"],
+            "properties": {
+              "draftLaneId": { "$ref": "#/$defs/text" },
+              "title": { "type": "null" },
+              "ownedPaths": { "$ref": "#/$defs/nonemptyStrings" },
+              "ownerAgentId": { "type": "null" }
+            }
+          }
+        },
+        "requiresHumanConfirmation": { "$ref": "#/$defs/nonemptyStrings" }
+      }
+    },
+    "nextAction": { "$ref": "#/$defs/nullableText" },
+    "persisted": { "const": false },
+    "readOnly": { "const": true },
+    "writesPerformed": { "const": false },
+    "authorityBoundary": { "$ref": "project-completion-continuity-v1.schema.json#/$defs/authorityBoundary" },
+    "authorizationGranted": { "const": false }
+  },
+  "examples": [
+    {
+      "schemaVersion": "OwlCodaRunKitSuccessorScaffoldV1",
+      "status": "successor_baseline_missing",
+      "exitCode": 0,
+      "project": {
+        "projectId": "completed-project",
+        "projectTruthHash": "0000000000000000000000000000000000000000000000000000000000000000",
+        "overall": "completed"
+      },
+      "completionContinuity": {
+        "schemaVersion": "OwlCodaRunKitProjectCompletionContinuityV1",
+        "status": "baseline_missing",
+        "projectId": "completed-project",
+        "projectTruthHash": "0000000000000000000000000000000000000000000000000000000000000000",
+        "disposition": "completed_project_source_baseline_missing",
+        "targetWorkspaceRef": "/projects/source",
+        "baseline": null,
+        "current": {
+          "headCommit": "0000000000000000000000000000000000000000",
+          "workspaceSnapshotFingerprint": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+        },
+        "delta": null,
+        "nextAction": "Review the current workspace and bind an explicit source baseline before deciding whether the project is terminal.",
+        "readOnly": true,
+        "writesPerformed": false,
+        "authorityBoundary": {
+          "agentDispatch": false,
+          "git": false,
+          "release": false,
+          "deployment": false,
+          "production": false,
+          "business": false,
+          "automation": false,
+          "money": false
+        },
+        "authorizationGranted": false
+      },
+      "unmodeledCandidates": [],
+      "pathConflicts": [],
+      "possibleLanes": [],
+      "draft": {
+        "projectId": null,
+        "objective": null,
+        "workItems": [],
+        "requiresHumanConfirmation": [
+          "project_id",
+          "objective",
+          "work_item_boundaries",
+          "owners",
+          "acceptance"
+        ]
+      },
+      "nextAction": "Review the current workspace and bind an explicit source baseline before deciding whether the project is terminal.",
+      "persisted": false,
+      "readOnly": true,
+      "writesPerformed": false,
+      "authorityBoundary": {
+        "agentDispatch": false,
+        "git": false,
+        "release": false,
+        "deployment": false,
+        "production": false,
+        "business": false,
+        "automation": false,
+        "money": false
+      },
+      "authorizationGranted": false
+    }
+  ],
+  "$defs": {
+    "text": { "type": "string", "minLength": 1 },
+    "nullableText": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/text" }] },
+    "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "hashRef": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "paths": { "type": "array", "maxItems": 256, "uniqueItems": true, "items": { "$ref": "#/$defs/text" } },
+    "nonemptyStrings": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/text" } }
+  }
+}