workspai 0.43.1 → 0.44.0

package/README.md

@@ -81,15 +81,15 @@ npx workspai pipeline --json --strict
 Workspai does not pretend every technology is a native scaffold. It uses a
 create planner contract to choose the safest path:
 
-| Lane                    | Use when                                                                                        | Result                                                                 |
-| ----------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `native-create`         | Workspai owns the scaffold contract                                                             | Create the project with a first-class kit                              |
-| `external-create-adopt` | The ecosystem has an official generator, but Workspai does not own the post-create contract yet | Use the ecosystem generator, then adopt into Workspace Intelligence    |
-| `adopt-only`            | The project already exists or native create is not supported                                    | Register, model, verify, and govern the project without scaffolding it |
+| Lane       | Use when                                                                                        | Result                                                                 |
+| ---------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `native`   | Workspai owns the scaffold contract                                     | Create the project with a first-class Workspai kit                     |
+| `official` | The ecosystem has an official generator                                 | Run an available official generator and register it, or adopt planned handoffs |
+| `existing` | The project already exists, or no create path is available or necessary | Register, model, verify, and govern the project without scaffolding it |
 
-Native create includes FastAPI, NestJS, Go, Spring Boot, .NET, and official
-frontend generators such as Next.js, Vite, Nuxt, Angular, Astro, Remix, and
-SvelteKit.
+Native create is reserved for Workspai-owned kits such as FastAPI, NestJS,
+Go, Spring Boot, and .NET. Official generator paths cover frontend frameworks
+such as Next.js, Vite, Nuxt, Angular, Astro, Remix, and SvelteKit.
 
 External ecosystems such as WordPress, Laravel, Symfony, Rails, and generic PHP
 projects can still enter Workspai through adopt/import and receive workspace
@@ -171,7 +171,7 @@ For the visual experience, install the [Workspai VS Code extension](https://mark
 | --------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | What projects exist in this workspace?        | `workspace model --json`                                                                     |
 | What context should AI agents receive?        | `workspace context --for-agent --json --write`                                               |
-| What breaks if I change this?                 | `workspace impact --from <snapshot>`                                                         |
+| What breaks if I change this?                 | `workspace impact --from .workspai/reports/workspace-model-diff-last-run.json`                |
 | Why is release blocked?                       | `workspace explain release-blocked --json --write`                                           |
 | Trace a diff through blast radius and gates?  | `workspace trace --from .workspai/reports/workspace-model-diff-last-run.json --json --write` |
 | What should Studio do for blocked artifacts?  | `workspace remediation-plan --ci --json --write`                                             |
@@ -315,6 +315,19 @@ assistance, and release decisions backed by evidence instead of guesswork.
 
 Workspace Intelligence provides a shared understanding of projects, dependencies, operational context, and release readiness for developers, CI pipelines, and AI agents.
 
+The canonical execution order is versioned in
+[`contracts/workspace-intelligence-chain.v1.json`](contracts/workspace-intelligence-chain.v1.json).
+CLI, IDE, CI, agent grounding, documentation, and diagrams must consume that
+contract instead of maintaining independent command sequences. It currently defines:
+
+```text
+Model -> Snapshot -> Diff -> Impact -> Doctor -> Contract Verify -> Readiness
+      -> Verify -> Context -> Agent Sync -> Explain
+```
+
+Each contracted step declares its command, dependencies, consumed and produced
+artifacts, and whether a non-zero structured verdict continues or stops the chain.
+
 | Command                                                      | Purpose                                                                              |
 | ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
 | `workspace model [--cache\|--incremental] --json`            | Canonical workspace model (graph-aware, incremental rebuilds)                        |
@@ -508,7 +521,7 @@ cd <project-name> && npx workspai init && npx workspai dev
 
 Backend kits: `fastapi.standard`, `nestjs.standard`, `springboot.standard`, `gofiber.standard`, `dotnet.webapi.clean`, and more.
 
-Frontend kits: `nextjs`, `remix`, `vite-react`, `nuxt`, `angular`, `astro`, `sveltekit`, and more — same command shape:
+Frontend generators: `nextjs`, `remix`, `vite-react`, `nuxt`, `angular`, `astro`, `sveltekit`, and more — same command shape:
 
 ```bash
 npx workspai create project <kit> <name>

package/contracts/agent-customization-pack.v1.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "rapidkit-agent-customization-pack.v1",
+  "schemaVersion": "workspai-agent-customization-pack-capabilities.v1",
   "presets": {
     "minimal": {
       "meaning": "Generate the portable grounding index, AGENTS.md, and provider-specific lightweight instructions.",

package/contracts/autopilot-release.v1.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "workspacePath",
+    "mode",
+    "summary",
+    "stages",
+    "blockingReasons",
+    "nextActions",
+    "artifacts"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "autopilot-release-v1"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "workspacePath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "mode": {
+      "enum": [
+        "audit",
+        "safe-fix",
+        "enforce"
+      ]
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "releaseScore",
+        "verdict",
+        "blockers",
+        "warnings",
+        "safeFixesApplied",
+        "manualActions",
+        "exitCode"
+      ],
+      "properties": {
+        "releaseScore": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "verdict": {
+          "enum": [
+            "approved",
+            "blocked",
+            "partial"
+          ]
+        },
+        "blockers": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "warnings": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "safeFixesApplied": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "manualActions": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "exitCode": {
+          "enum": [
+            0,
+            1,
+            2,
+            3
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "stages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "status",
+          "durationMs",
+          "summary"
+        ],
+        "properties": {
+          "name": {
+            "enum": [
+              "doctor-workspace",
+              "analyze",
+              "readiness",
+              "remediation-plan",
+              "remediation-apply",
+              "workspace-run-test-build"
+            ]
+          },
+          "status": {
+            "enum": [
+              "pass",
+              "warn",
+              "fail",
+              "skipped"
+            ]
+          },
+          "durationMs": {
+            "type": "number",
+            "minimum": 0
+          },
+          "summary": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "blockingReasons": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "warningReasons": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "nextActions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "artifacts": {
+      "type": "object",
+      "required": [
+        "reportPath"
+      ],
+      "properties": {
+        "reportPath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "aliasEvidencePath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "analyzeEvidencePath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "readinessEvidencePath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "workspaceRunEvidencePath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "workspaceRunTestPath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "workspaceRunBuildPath": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "enterpriseControls": {
+      "type": "object",
+      "required": [
+        "jsonReady",
+        "evidencePath",
+        "aliasEvidencePath"
+      ],
+      "properties": {
+        "jsonReady": {
+          "type": "boolean"
+        },
+        "evidencePath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "aliasEvidencePath": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true
+}

package/contracts/cli-operation-result.v1.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/cli-operation-result.v1.json",
+  "title": "Workspai CLI Operation Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "operation",
+    "status",
+    "exitCode"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "workspai-cli-operation-result-v1"
+    },
+    "operation": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "enum": [
+        "success",
+        "error"
+      ]
+    },
+    "exitCode": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "artifact": {},
+    "outputPath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "examples": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "nextActions": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "success"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "then": {
+        "required": [
+          "artifact"
+        ],
+        "not": {
+          "required": [
+            "error"
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "error"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "then": {
+        "required": [
+          "error"
+        ],
+        "not": {
+          "required": [
+            "artifact"
+          ]
+        }
+      }
+    }
+  ]
+}

package/contracts/command-capabilities.v1.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/command-capabilities.v1.json",
+  "title": "Workspai Command Capabilities",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "scope",
+    "cli",
+    "version",
+    "cwd",
+    "contracts",
+    "contractCatalog",
+    "commands",
+    "workspace",
+    "commandMap"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "rapidkit-command-capabilities-v1"
+    },
+    "scope": {
+      "const": "global"
+    },
+    "cli": {
+      "const": "workspai"
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "cwd": {
+      "type": "string",
+      "minLength": 1
+    },
+    "contracts": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "contractCatalog": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "commands": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "npmOwned",
+        "coreBacked",
+        "projectScoped"
+      ],
+      "properties": {
+        "npmOwned": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "coreBacked": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "projectScoped": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "command",
+        "subcommands",
+        "intelligenceSubcommands"
+      ],
+      "properties": {
+        "command": {
+          "const": "workspace"
+        },
+        "subcommands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "intelligenceSubcommands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "commandMap": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "command",
+          "owner",
+          "status",
+          "scope"
+        ],
+        "properties": {
+          "command": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owner": {
+            "enum": [
+              "npm-wrapper",
+              "python-core",
+              "runtime-adapter"
+            ]
+          },
+          "status": {
+            "enum": [
+              "supported",
+              "delegated",
+              "runtime-dependent"
+            ]
+          },
+          "scope": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/contracts/compatibility-matrix.v1.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "source",
+    "runtimes",
+    "notes"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "rapidkit.compatibility-matrix.v1"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1
+    },
+    "runtimes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object"
+      }
+    },
+    "notes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": true
+}