workspai 0.55.1 → 0.57.0

package/README.md

@@ -4,10 +4,40 @@
 [![Downloads](https://img.shields.io/npm/dm/workspai.svg?style=flat-square)](https://www.npmjs.com/package/workspai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
 
-## Workspace Intelligence for software systems
+## Give your AI agent the system—not just the repository
+
+Your coding agent should not have to rediscover your architecture in every
+session. Workspai builds a current, evidence-backed view of your projects,
+APIs, dependencies, infrastructure, and change boundaries, then gives agents
+the bounded context they need.
 
 > One workspace. One truth. Humans and AI aligned.
 
+```bash
+npx workspai adopt .
+npx workspai workspace intelligence run --for-agent generic
+```
+
+A single run gives developers and tools the same operational picture:
+
+```text
+System     projects · runtimes · APIs · dependencies · infrastructure
+Evidence   relationships linked back to canonical proof
+Change     affected projects and verification targets
+Agents     bounded context instead of an unfiltered repository dump
+```
+
+**Understand the system before an agent changes it.**
+
+![Workspai CLI adopting and analyzing the gRPC repository](https://raw.githubusercontent.com/chistiq/workspai/main/packages/cli/docs/workspai-grpc-readme-cli.gif)
+
+[Get started](#start-in-two-minutes) ·
+[See what you get](#what-happens-after-the-first-run) ·
+[How it works](#how-workspace-intelligence-works) ·
+[Documentation](docs/README.md)
+
+## Workspace Intelligence for software systems
+
 Workspai is an open-source CLI that brings related software projects together,
 so people and AI tools can understand and work with the same system.
 
@@ -17,11 +47,6 @@ so people and AI tools can understand and work with the same system.
 - **Act with confidence:** understand impact, verify changes, and prepare focused
   context for AI tools.
 
-[Quickstart](#start-in-two-minutes) ·
-[Everyday workflows](#everyday-workflows) ·
-[How it works](#how-workspace-intelligence-works) ·
-[Documentation](docs/README.md)
-
 ![From Code to Shared Understanding](https://raw.githubusercontent.com/chistiq/workspai/main/packages/cli/docs/From%20Code%20to%20Shared%20Understanding.png)
 
 ## Start in two minutes
@@ -38,14 +63,17 @@ npx workspai adopt .
 The project stays where it is. Workspai creates or reuses a minimal workspace
 in the default system location and records a validated local link.
 
-Stay in the same project directory and run the complete intelligence loop:
+Stay in the same project directory and run Workspace Intelligence:
 
 ```bash
-npx workspai workspace intelligence run --for-agent generic --strict --json
+npx workspai workspace intelligence run --for-agent generic
 ```
 
 Workspai now knows which workspace owns the project. You only need
 `--workspace <path>` when a moved or ambiguous binding cannot be resolved.
+The shorter command is intended for a human-readable first run. CI, agents, and
+other machine consumers should use the strict JSON form shown in
+[How Workspace Intelligence works](#how-workspace-intelligence-works).
 
 ### Start new software
 

package/contracts/adopt-effects.v1.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/contracts/adopt-effects.v1.json",
+  "title": "Workspai Adopt Effects v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "sourceMode",
+    "sourceCodeModified",
+    "projectMetadataFiles",
+    "repositoryControlFiles",
+    "workspaceOperations"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "workspai.adopt-effects.v1"
+    },
+    "sourceMode": {
+      "const": "linked"
+    },
+    "sourceCodeModified": {
+      "const": false
+    },
+    "projectMetadataFiles": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "repositoryControlFiles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "action",
+          "condition"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "action": {
+            "const": "reconcile"
+          },
+          "condition": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "workspaceOperations": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "register-project",
+          "sync-contract",
+          "rebuild-model",
+          "rebuild-graph",
+          "sync-agent-grounding"
+        ]
+      },
+      "uniqueItems": true
+    }
+  }
+}

package/contracts/artifact-remediation-plan.v1.json

@@ -73,6 +73,94 @@
             "overwrite": { "const": false }
           }
         },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path", "lines", "ensureNewline"],
+          "properties": {
+            "type": { "const": "file-append" },
+            "path": { "type": "string" },
+            "lines": { "type": "array", "items": { "type": "string" } },
+            "ensureNewline": { "type": "boolean" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "sourcePath", "path", "overwrite"],
+          "properties": {
+            "type": { "const": "file-copy" },
+            "sourcePath": { "type": "string" },
+            "path": { "type": "string" },
+            "overwrite": { "const": false }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path", "scriptName", "scriptValue"],
+          "properties": {
+            "type": { "const": "package-json-script" },
+            "path": { "type": "string" },
+            "scriptName": { "type": "string" },
+            "scriptValue": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path", "edits"],
+          "properties": {
+            "type": { "const": "json-edit" },
+            "path": { "type": "string" },
+            "edits": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["pointer", "value"],
+                "properties": {
+                  "pointer": { "type": "string" },
+                  "value": { "type": ["string", "number", "boolean", "null"] }
+                }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path", "keys"],
+          "properties": {
+            "type": { "const": "env-key-add" },
+            "path": { "type": "string" },
+            "keys": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["name", "value"],
+                "properties": {
+                  "name": { "type": "string" },
+                  "value": { "type": "string" },
+                  "comment": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path", "target", "command", "phony"],
+          "properties": {
+            "type": { "const": "makefile-target" },
+            "path": { "type": "string" },
+            "target": { "type": "string" },
+            "command": { "type": "string" },
+            "phony": { "type": "boolean" }
+          }
+        },
         {
           "type": "object",
           "additionalProperties": false,
@@ -164,7 +252,15 @@
       "allOf": [
         {
           "if": { "properties": { "kind": { "const": "dependency-security" } } },
-          "then": { "properties": { "completion": { "type": "object", "properties": { "auditClean": { "const": true } }, "required": ["auditClean"] } } }
+          "then": {
+            "properties": {
+              "completion": {
+                "type": "object",
+                "properties": { "auditClean": { "const": true } },
+                "required": ["auditClean"]
+              }
+            }
+          }
         },
         {
           "if": { "properties": { "kind": { "const": "dependency-materialization" } } },
@@ -173,7 +269,11 @@
             "properties": {
               "sourceMutationRequired": { "const": false },
               "observableState": { "const": "runtime-dependency-tree" },
-              "completion": { "type": "object", "properties": { "installedTreePresent": { "const": true } }, "required": ["installedTreePresent"] }
+              "completion": {
+                "type": "object",
+                "properties": { "installedTreePresent": { "const": true } },
+                "required": ["installedTreePresent"]
+              }
             }
           }
         }
@@ -190,6 +290,9 @@
         "order",
         "phase",
         "scope",
+        "findingId",
+        "findingStatus",
+        "causalKey",
         "status",
         "mode",
         "risk",
@@ -213,6 +316,11 @@
         "projectName": { "type": "string", "minLength": 1 },
         "projectPath": { "type": "string", "minLength": 1 },
         "sourceStepId": { "type": "string", "minLength": 1 },
+        "findingId": { "type": "string", "minLength": 1 },
+        "findingStatus": {
+          "enum": ["blocking", "advisory", "informational", "unknown"]
+        },
+        "causalKey": { "type": "string", "minLength": 1 },
         "dependsOn": {
           "type": "array",
           "items": { "type": "string", "minLength": 1 }

package/contracts/cli-runtime-command-inventory.v1.snapshot.json

@@ -377,9 +377,17 @@
           "attributeName": "project"
         },
         {
-          "flags": "--json",
+          "flags": "--json [mode]",
           "attributeName": "json"
         },
+        {
+          "flags": "--fresh",
+          "attributeName": "fresh"
+        },
+        {
+          "flags": "--verbose",
+          "attributeName": "verbose"
+        },
         {
           "flags": "--strict",
           "attributeName": "strict"
@@ -403,6 +411,22 @@
         {
           "flags": "--apply",
           "attributeName": "apply"
+        },
+        {
+          "flags": "--runtime <runtime>",
+          "attributeName": "runtime"
+        },
+        {
+          "flags": "--framework <framework>",
+          "attributeName": "framework"
+        },
+        {
+          "flags": "--validate",
+          "attributeName": "validate"
+        },
+        {
+          "flags": "--write",
+          "attributeName": "write"
         }
       ]
     },
@@ -1280,6 +1304,10 @@
           "flags": "--limit <count>",
           "attributeName": "limit"
         },
+        {
+          "flags": "--refresh-graph",
+          "attributeName": "refreshGraph"
+        },
         {
           "flags": "--cache",
           "attributeName": "cache"
@@ -1396,6 +1424,10 @@
           "flags": "--parallel",
           "attributeName": "parallel"
         },
+        {
+          "flags": "--runtime <runtime>",
+          "attributeName": "runtime"
+        },
         {
           "flags": "--max-workers <count>",
           "attributeName": "maxWorkers"

package/contracts/doctor-project-evidence.v1.json

@@ -43,6 +43,9 @@
         "graphDiagnosis": {
           "$ref": "https://workspai.dev/schemas/workspace-intelligence/doctor-graph-diagnosis.v1.json"
         },
+        "diagnosis": {
+          "$ref": "https://workspai.dev/schemas/workspace-intelligence/doctor-diagnosis.v1.json"
+        },
         "verdict": { "enum": ["passed", "attention", "blocked"] },
         "probeSummary": { "$ref": "#/$defs/probeSummary" }
       },
@@ -51,6 +54,7 @@
     "summary": {
       "type": "object",
       "properties": {
+        "counts": { "$ref": "#/$defs/counts" },
         "scopeProvenance": { "type": "object", "additionalProperties": true },
         "verdict": { "enum": ["passed", "attention", "blocked"] },
         "probeSummary": { "$ref": "#/$defs/probeSummary" },
@@ -68,6 +72,10 @@
     "policyProfile": { "$ref": "#/$defs/policyProfile" }
   },
   "$defs": {
+    "counts": {
+      "type": "object",
+      "additionalProperties": { "type": "integer", "minimum": 0 }
+    },
     "dependencyAudit": {
       "type": "object",
       "required": [
@@ -262,6 +270,7 @@
         "warnings": { "type": "integer", "minimum": 0 },
         "errors": { "type": "integer", "minimum": 0 },
         "verdict": { "enum": ["passed", "attention", "blocked"] },
+        "presentation": { "$ref": "#/$defs/healthScorePresentation" },
         "components": {
           "type": "object",
           "required": ["host", "projects"],
@@ -274,6 +283,30 @@
       },
       "additionalProperties": false
     },
+    "healthScorePresentation": {
+      "type": "object",
+      "required": [
+        "policy",
+        "diagnosticPassRatePercent",
+        "blockingFindings",
+        "advisoryFindings",
+        "unknownFindings",
+        "contradictionFindings",
+        "notApplicableChecks",
+        "label"
+      ],
+      "properties": {
+        "policy": { "const": "doctor-multi-axis-v1" },
+        "diagnosticPassRatePercent": { "type": ["number", "null"], "minimum": 0, "maximum": 100 },
+        "blockingFindings": { "type": "integer", "minimum": 0 },
+        "advisoryFindings": { "type": "integer", "minimum": 0 },
+        "unknownFindings": { "type": "integer", "minimum": 0 },
+        "contradictionFindings": { "type": "integer", "minimum": 0 },
+        "notApplicableChecks": { "type": "integer", "minimum": 0 },
+        "label": { "const": "diagnostic-pass-rate" }
+      },
+      "additionalProperties": false
+    },
     "probeSummary": {
       "type": "object",
       "required": [
@@ -292,6 +325,8 @@
         "failed": { "type": "integer", "minimum": 0 },
         "blockingFindings": { "type": "integer", "minimum": 0 },
         "advisoryFindings": { "type": "integer", "minimum": 0 },
+        "unknownFindings": { "type": "integer", "minimum": 0 },
+        "contradictionFindings": { "type": "integer", "minimum": 0 },
         "verdict": { "enum": ["passed", "attention", "blocked"] }
       },
       "additionalProperties": false
@@ -391,6 +426,7 @@
         "status": { "enum": ["pass", "warn", "fail"] },
         "severity": { "enum": ["info", "warn", "error"] },
         "scope": { "type": "string" },
+        "applicability": { "enum": ["applicable", "not-applicable", "unknown"] },
         "reason": { "type": "string" },
         "recommendation": { "type": "string" },
         "freshness": { "$ref": "#/$defs/freshness" },
@@ -530,7 +566,15 @@
       "allOf": [
         {
           "if": { "properties": { "kind": { "const": "dependency-security" } } },
-          "then": { "properties": { "completion": { "type": "object", "properties": { "auditClean": { "const": true } }, "required": ["auditClean"] } } }
+          "then": {
+            "properties": {
+              "completion": {
+                "type": "object",
+                "properties": { "auditClean": { "const": true } },
+                "required": ["auditClean"]
+              }
+            }
+          }
         },
         {
           "if": { "properties": { "kind": { "const": "dependency-materialization" } } },
@@ -539,7 +583,11 @@
             "properties": {
               "sourceMutationRequired": { "const": false },
               "observableState": { "const": "runtime-dependency-tree" },
-              "completion": { "type": "object", "properties": { "installedTreePresent": { "const": true } }, "required": ["installedTreePresent"] }
+              "completion": {
+                "type": "object",
+                "properties": { "installedTreePresent": { "const": true } },
+                "required": ["installedTreePresent"]
+              }
             }
           }
         }
@@ -625,6 +673,51 @@
         "command": { "type": "string" },
         "phony": { "type": "boolean" }
       },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "file-create" } } },
+          "then": {
+            "required": ["content", "overwrite"],
+            "properties": { "content": {}, "overwrite": { "const": false } }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "file-append" } } },
+          "then": {
+            "required": ["lines", "ensureNewline"],
+            "properties": { "lines": {}, "ensureNewline": {} }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "file-copy" } } },
+          "then": {
+            "required": ["sourcePath", "overwrite"],
+            "properties": { "sourcePath": {}, "overwrite": { "const": false } }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "package-json-script" } } },
+          "then": {
+            "required": ["scriptName", "scriptValue"],
+            "properties": { "scriptName": {}, "scriptValue": {} }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "json-edit" } } },
+          "then": { "required": ["edits"], "properties": { "edits": {} } }
+        },
+        {
+          "if": { "properties": { "type": { "const": "env-key-add" } } },
+          "then": { "required": ["keys"], "properties": { "keys": {} } }
+        },
+        {
+          "if": { "properties": { "type": { "const": "makefile-target" } } },
+          "then": {
+            "required": ["target", "command", "phony"],
+            "properties": { "target": {}, "command": {}, "phony": {} }
+          }
+        }
+      ],
       "additionalProperties": false
     }
   },

package/contracts/doctor-remediation-plan.v1.json

@@ -219,7 +219,15 @@
       "allOf": [
         {
           "if": { "properties": { "kind": { "const": "dependency-security" } } },
-          "then": { "properties": { "completion": { "type": "object", "properties": { "auditClean": { "const": true } }, "required": ["auditClean"] } } }
+          "then": {
+            "properties": {
+              "completion": {
+                "type": "object",
+                "properties": { "auditClean": { "const": true } },
+                "required": ["auditClean"]
+              }
+            }
+          }
         },
         {
           "if": { "properties": { "kind": { "const": "dependency-materialization" } } },
@@ -228,7 +236,11 @@
             "properties": {
               "sourceMutationRequired": { "const": false },
               "observableState": { "const": "runtime-dependency-tree" },
-              "completion": { "type": "object", "properties": { "installedTreePresent": { "const": true } }, "required": ["installedTreePresent"] }
+              "completion": {
+                "type": "object",
+                "properties": { "installedTreePresent": { "const": true } },
+                "required": ["installedTreePresent"]
+              }
             }
           }
         }
@@ -461,6 +473,7 @@
         "kind",
         "risk",
         "executable",
+        "findingStatus",
         "files",
         "preview",
         "diffPreview",
@@ -531,6 +544,17 @@
         "issueId": {
           "type": "string"
         },
+        "diagnosisFindingId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "causalKey": {
+          "type": "string",
+          "minLength": 1
+        },
+        "findingStatus": {
+          "enum": ["blocking", "advisory", "informational", "unknown"]
+        },
         "issueClass": {
           "enum": [
             "dependency",
@@ -572,6 +596,9 @@
         "operation": {
           "$ref": "#/$defs/repairOperation"
         },
+        "invocation": {
+          "$ref": "#/$defs/commandInvocation"
+        },
         "strategy": {
           "type": "array",
           "items": { "$ref": "#/$defs/repairStrategyStage" }