workspai 0.66.0 → 0.67.0

package/README.md

@@ -22,24 +22,24 @@ Two commands. Your project gains a bounded, evidence-backed system view:
 
 ### Before vs After
 
-| Before Workspai | After Workspai |
-| --- | --- |
-| Agent scans thousands of files for context | Agent starts from bounded entry and context artifacts |
-| No dependency map between services | Searchable graph with source-level proof |
-| Broken test blocks release, no one knows why | Doctor localizes the blocker and next target |
-| Every AI session starts from scratch | Sessions resume from durable evidence |
+| Before Workspai                              | After Workspai                                        |
+| -------------------------------------------- | ----------------------------------------------------- |
+| Agent scans thousands of files for context   | Agent starts from bounded entry and context artifacts |
+| No dependency map between services           | Searchable graph with source-level proof              |
+| Broken test blocks release, no one knows why | Doctor localizes the blocker and next target          |
+| Every AI session starts from scratch         | Sessions resume from durable evidence                 |
 
 Here is what you get:
 
-| What it produces | Why it matters |
-| --- | --- |
-| **Workspace Model** | A canonical inventory of registered projects, detected runtimes, frameworks, and proven dependencies |
-| **Knowledge Graph** | Searchable relationships between projects, backed by source-level proof |
-| **Health & Readiness** | Doctor checks, verification gates, and release posture based on evidence, not guesses |
-| **Agent Context** | Bounded, focused instructions so AI tools read what they need, not the entire repo |
-| **Agent Rules** | Ready-to-use grounding for Cursor, Copilot, Claude, Codex, Gemini, and more |
-| **Agent Skills** | Runtime-, polyglot-, test-, and delivery-aware operational playbooks, with portable `SKILL.md` projections where the host supports Agent Skills |
-| **MCP Server** | Versioned read-oriented tools for querying evidence, graph, blockers, and context live |
+| What it produces       | Why it matters                                                                                                                                  |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Workspace Model**    | A canonical inventory of registered projects, detected runtimes, frameworks, and proven dependencies                                            |
+| **Knowledge Graph**    | Searchable relationships between projects, backed by source-level proof                                                                         |
+| **Health & Readiness** | Doctor checks, verification gates, and release posture based on evidence, not guesses                                                           |
+| **Agent Context**      | Bounded, focused instructions so AI tools read what they need, not the entire repo                                                              |
+| **Agent Rules**        | Ready-to-use grounding for Cursor, Copilot, Claude, Codex, Gemini, and more                                                                     |
+| **Agent Skills**       | Runtime-, polyglot-, test-, and delivery-aware operational playbooks, with portable `SKILL.md` projections where the host supports Agent Skills |
+| **MCP Server**         | Versioned read-oriented tools for querying evidence, graph, blockers, and context live                                                          |
 
 `generic` is the safe default when you do not yet know which agent will use the
 project: Workspai builds one portable context and prepares discovery adapters
@@ -182,13 +182,13 @@ a machine-readable decision and can use `--scope` and `--runtime`.
 Everything shown in the [output tree above](#what-the-output-looks-like) is
 generated in one run. The key files for each audience:
 
-| Audience | What to read |
-| --- | --- |
-| **AI agent** | `agent-entry.v1.json` (project) → `workspace-context-agent.json` (workspace) |
-| **Developer** | Terminal summary, or `workspace-explain-last-run.json` for diagnosis |
-| **CI / automation** | `workspace-verify-last-run.json` (exit code 0 = pass, 2 = blocked) |
-| **MCP client** | `workspace mcp serve` (versioned read-oriented tools over JSON-RPC) |
-| **IDE extension** | Same artifacts + watch events |
+| Audience            | What to read                                                                 |
+| ------------------- | ---------------------------------------------------------------------------- |
+| **AI agent**        | `agent-entry.v1.json` (project) → `workspace-context-agent.json` (workspace) |
+| **Developer**       | Terminal summary, or `workspace-explain-last-run.json` for diagnosis         |
+| **CI / automation** | `workspace-verify-last-run.json` (exit code 0 = pass, 2 = blocked)           |
+| **MCP client**      | `workspace mcp serve` (versioned read-oriented tools over JSON-RPC)          |
+| **IDE extension**   | Same artifacts + watch events                                                |
 
 An agent can prove that it entered through governed evidence before scanning
 the repository:
@@ -273,6 +273,8 @@ explicitly unproven.
 | Check the current project                  | `npx workspai doctor project`                                                    |
 | Check the whole workspace                  | `npx workspai doctor workspace`                                                  |
 | Refresh Model and Graph                    | `npx workspai workspace model --write --json`                                    |
+| Watch command activity as a portable board | `npx workspai live --once --json --projection board`                             |
+| Benchmark bounded agent retrieval          | `npx workspai workspace graph benchmark-suite agent-core.v1 --write --json`      |
 | Ask a focused architecture question        | `npx workspai workspace graph search "authentication service" --limit 12 --json` |
 | Verify current evidence                    | `npx workspai workspace verify --strict --json`                                  |
 | Inspect a governed repair before execution | `npx workspai workspace repair capabilities --json`                              |

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

@@ -761,6 +761,10 @@
           "flags": "--json",
           "attributeName": "json"
         },
+        {
+          "flags": "--projection <projection>",
+          "attributeName": "projection"
+        },
         {
           "flags": "--refresh-ms <milliseconds>",
           "attributeName": "refreshMs"

package/contracts/extension-cli-compatibility.v1.json

@@ -65,6 +65,9 @@
     },
     "cliLogEvent": "cli-log-event-v1",
     "workspaceActivityEvent": "workspace-activity-event.v1",
+    "workspaceActivityMonitorSnapshot": "workspace-activity-monitor-snapshot.v1",
+    "workspaceActivityMonitorFleet": "workspace-activity-monitor-fleet.v1",
+    "workspaceActivityBoard": "workspace-activity-board.v1",
     "freshnessMetadata": "rapidkit-freshness-metadata-v1",
     "factFreshness": "rapidkit-fact-freshness-v1",
     "blockerResolution": "rapidkit-blocker-resolution-v1",
@@ -78,6 +81,7 @@
     "workspaceKnowledgeGraphChangeOverlay": "workspace-knowledge-graph-change-overlay.v1",
     "workspaceKnowledgeSearch": "workspace-knowledge-search.v1",
     "workspaceGraphTokenEfficiency": "workspace-graph-token-efficiency.v1",
+    "workspaceIntelligenceBenchmark": "workspace-intelligence-benchmark.v1",
     "modelUsageEvent": "model-usage-event.v1",
     "workspaceIntelligenceEvaluation": "workspace-intelligence-evaluation.v1",
     "workspaceIntelligenceEvaluationComparison": "workspace-intelligence-evaluation-comparison.v1",

package/contracts/published-contract-catalog.v1.json

@@ -331,6 +331,21 @@
       "contractPath": "contracts/workspace-activity-event.v1.json",
       "publication": "json-schema"
     },
+    "workspaceActivityMonitorSnapshot": {
+      "schemaVersion": "workspace-activity-monitor-snapshot.v1",
+      "contractPath": "contracts/workspace-activity-monitor-snapshot.v1.json",
+      "publication": "capability-contract"
+    },
+    "workspaceActivityMonitorFleet": {
+      "schemaVersion": "workspace-activity-monitor-fleet.v1",
+      "contractPath": "contracts/workspace-activity-monitor-fleet.v1.json",
+      "publication": "json-schema"
+    },
+    "workspaceActivityBoard": {
+      "schemaVersion": "workspace-activity-board.v1",
+      "contractPath": "contracts/workspace-activity-board.v1.json",
+      "publication": "json-schema"
+    },
     "freshnessMetadata": {
       "schemaVersion": "rapidkit-freshness-metadata-v1",
       "contractPath": null,
@@ -396,6 +411,11 @@
       "contractPath": "contracts/workspace-intelligence/workspace-graph-token-efficiency.v1.json",
       "publication": "json-schema"
     },
+    "workspaceIntelligenceBenchmark": {
+      "schemaVersion": "workspace-intelligence-benchmark.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-intelligence-benchmark.v1.json",
+      "publication": "json-schema"
+    },
     "modelUsageEvent": {
       "schemaVersion": "model-usage-event.v1",
       "contractPath": "contracts/workspace-intelligence/model-usage-event.v1.json",

package/contracts/runtime-command-surface.v1.json

@@ -562,8 +562,27 @@
       "invocation": "live",
       "summary": "Render the versioned cross-terminal execution graph for Workspai runs in the current project or workspace.",
       "canonicalArgv": [
-        "live"
-      ]
+        "live",
+        "--once",
+        "--json",
+        "--projection",
+        "board"
+      ],
+      "output": {
+        "defaultFormat": "human-or-json",
+        "modes": [
+          {
+            "selector": "--once --json --projection monitor",
+            "format": "json",
+            "mediaType": "application/json"
+          },
+          {
+            "selector": "--once --json --projection board",
+            "format": "json",
+            "mediaType": "application/json"
+          }
+        ]
+      }
     },
     {
       "invocation": "merge",
@@ -1177,6 +1196,11 @@
             "format": "json",
             "mediaType": "application/json"
           },
+          {
+            "selector": "benchmark-suite agent-core.v1 --write --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
           {
             "selector": "emit --json",
             "format": "json",
@@ -1235,6 +1259,16 @@
         ]
       }
     },
+    {
+      "invocation": "workspace graph benchmark-suite --write",
+      "summary": "Run the fixed multi-scenario retrieval suite, preserve estimate-versus-measurement provenance, and publish the benchmark artifact.",
+      "canonicalArgv": [
+        "workspace",
+        "graph",
+        "benchmark-suite",
+        "--write"
+      ]
+    },
     {
       "invocation": "workspace hydrate",
       "summary": "Restore or materialize workspace state from a portable representation.",
@@ -2219,6 +2253,19 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/reports/workspace-intelligence-benchmark-last-run.json",
+      "schemaVersion": "workspace-intelligence-benchmark.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-intelligence-benchmark.v1.json",
+      "producerCommands": [
+        [
+          "workspace",
+          "graph",
+          "benchmark-suite",
+          "--write"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/reports/rapidkit-mcp-design.json",
       "schemaVersion": "workspai-mcp-design.v1",
@@ -2751,6 +2798,10 @@
         {
           "flag": "--scope",
           "description": "Limit the operation to a bounded scope such as project:<name>."
+        },
+        {
+          "flag": "--write",
+          "description": "Persist the command artifact under .workspai/reports."
         }
       ],
       "subactions": [
@@ -2762,6 +2813,7 @@
         "path",
         "overlay",
         "benchmark",
+        "benchmark-suite",
         "dot",
         "mermaid",
         "jsonld",
@@ -2772,6 +2824,7 @@
       "examples": [
         "workspai workspace graph search \"authentication endpoint\" --kind endpoint --limit 12 --json",
         "workspai workspace graph evidence \"GET /users\" --json",
+        "workspai workspace graph benchmark-suite agent-core.v1 --write --json",
         "workspai workspace graph mermaid"
       ]
     },

package/contracts/workspace-activity-board.v1.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/contracts/workspace-activity-board.v1.json",
+  "title": "Workspai Renderer-Neutral Activity Board",
+  "description": "A bounded renderer-neutral projection for IDE, web, terminal, SVG and capture consumers. It preserves observed run data without becoming verification evidence.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "scopeLabel",
+    "generatedAt",
+    "activeRunCount",
+    "healthyRunCount",
+    "warningRunCount",
+    "failedRunCount",
+    "runs",
+    "diagnostics",
+    "global",
+    "scopeCount"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspace-activity-board.v1" },
+    "scopeLabel": { "type": "string", "minLength": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "activeRunCount": { "type": "integer", "minimum": 0 },
+    "healthyRunCount": { "type": "integer", "minimum": 0 },
+    "warningRunCount": { "type": "integer", "minimum": 0 },
+    "failedRunCount": { "type": "integer", "minimum": 0 },
+    "selectedRunId": { "type": "string", "minLength": 1 },
+    "runs": { "type": "array", "items": { "$ref": "#/$defs/boardRun" } },
+    "diagnostics": { "type": "array", "items": { "type": "string" } },
+    "global": { "type": "boolean" },
+    "scopeCount": { "type": "integer", "minimum": 0 }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "boardRun": {
+      "type": "object",
+      "required": [
+        "run",
+        "commandLabel",
+        "active",
+        "nodes",
+        "edges",
+        "activeBlockCount",
+        "warningCount",
+        "scope",
+        "locationLabel"
+      ],
+      "properties": {
+        "run": { "$ref": "workspace-activity-monitor-snapshot.v1.json#/$defs/run" },
+        "commandLabel": { "type": "string", "minLength": 1 },
+        "active": { "type": "boolean" },
+        "nodes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "label", "status", "order", "updatedAt", "attempts", "root"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "label": { "type": "string", "minLength": 1 },
+              "status": { "$ref": "workspace-activity-monitor-snapshot.v1.json#/$defs/status" },
+              "order": { "type": "number" },
+              "parentId": { "type": "string", "minLength": 1 },
+              "progress": { "$ref": "workspace-activity-monitor-snapshot.v1.json#/$defs/progress" },
+              "durationMs": { "type": "number", "minimum": 0 },
+              "layoutHint": { "enum": ["source", "process", "gate", "sink"] },
+              "group": { "type": "string", "minLength": 1 },
+              "updatedAt": { "type": "string", "format": "date-time" },
+              "attempt": { "type": "integer", "minimum": 1 },
+              "attempts": {
+                "type": "array",
+                "items": { "$ref": "workspace-activity-monitor-snapshot.v1.json#/$defs/attempt" }
+              },
+              "root": { "type": "boolean" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "edges": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "fromBlockId",
+              "toBlockId",
+              "kind",
+              "status",
+              "order",
+              "updatedAt",
+              "inferred"
+            ],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "fromBlockId": { "type": "string", "minLength": 1 },
+              "toBlockId": { "type": "string", "minLength": 1 },
+              "kind": { "enum": ["sequence", "parallel", "gate", "handoff"] },
+              "status": { "$ref": "workspace-activity-monitor-snapshot.v1.json#/$defs/status" },
+              "order": { "type": "number" },
+              "updatedAt": { "type": "string", "format": "date-time" },
+              "inferred": { "type": "boolean" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "activeBlockCount": { "type": "integer", "minimum": 0 },
+        "warningCount": { "type": "integer", "minimum": 0 },
+        "scope": { "$ref": "workspace-activity-monitor-snapshot.v1.json#/$defs/scope" },
+        "locationLabel": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/contracts/workspace-activity-monitor-fleet.v1.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/contracts/workspace-activity-monitor-fleet.v1.json",
+  "title": "Workspai Activity Monitor Fleet Snapshot",
+  "description": "A deterministic aggregate of bounded local activity monitor snapshots.",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "scopes", "diagnostics"],
+  "properties": {
+    "schemaVersion": { "const": "workspace-activity-monitor-fleet.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "scopes": {
+      "type": "array",
+      "items": { "$ref": "workspace-activity-monitor-snapshot.v1.json" }
+    },
+    "diagnostics": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-activity-monitor-snapshot.v1.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/contracts/workspace-activity-monitor-snapshot.v1.json",
+  "title": "Workspai Activity Monitor Snapshot",
+  "description": "A deterministic local projection of durable Workspai activity journals. It is observational and is not verification evidence by itself.",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "scope", "runs", "diagnostics"],
+  "properties": {
+    "schemaVersion": { "const": "workspace-activity-monitor-snapshot.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "scope": { "$ref": "#/$defs/scope" },
+    "runs": { "type": "array", "items": { "$ref": "#/$defs/run" } },
+    "diagnostics": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "status": {
+      "enum": [
+        "planned",
+        "running",
+        "succeeded",
+        "warned",
+        "blocked",
+        "failed",
+        "cancelled",
+        "skipped",
+        "rolled-back"
+      ]
+    },
+    "scope": {
+      "type": "object",
+      "required": ["kind", "id", "label", "portable"],
+      "properties": {
+        "kind": { "enum": ["ephemeral-project", "project", "workspace"] },
+        "id": { "type": "string", "minLength": 1 },
+        "label": { "type": "string", "minLength": 1 },
+        "portable": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "origin": {
+      "type": "object",
+      "required": ["id", "kind", "label"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["project", "workspace-root"] },
+        "label": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "progress": {
+      "type": "object",
+      "properties": {
+        "completed": { "type": "number", "minimum": 0 },
+        "total": { "type": "number", "minimum": 0 },
+        "percent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "iteration": { "type": "number", "minimum": 0 },
+        "iterations": { "type": "number", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "attempt": {
+      "type": "object",
+      "required": ["attempt", "status", "startedAt", "updatedAt"],
+      "properties": {
+        "attempt": { "type": "integer", "minimum": 1 },
+        "status": { "$ref": "#/$defs/status" },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "progress": { "$ref": "#/$defs/progress" },
+        "durationMs": { "type": "number", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "block": {
+      "type": "object",
+      "required": ["id", "label", "status", "order", "updatedAt", "attempts"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "label": { "type": "string", "minLength": 1 },
+        "status": { "$ref": "#/$defs/status" },
+        "order": { "type": "number" },
+        "parentId": { "type": "string", "minLength": 1 },
+        "progress": { "$ref": "#/$defs/progress" },
+        "durationMs": { "type": "number", "minimum": 0 },
+        "layoutHint": { "enum": ["source", "process", "gate", "sink"] },
+        "group": { "type": "string", "minLength": 1 },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "attempt": { "type": "integer", "minimum": 1 },
+        "attempts": { "type": "array", "items": { "$ref": "#/$defs/attempt" } }
+      },
+      "additionalProperties": false
+    },
+    "edge": {
+      "type": "object",
+      "required": ["id", "fromBlockId", "toBlockId", "kind", "status", "order", "updatedAt"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "fromBlockId": { "type": "string", "minLength": 1 },
+        "toBlockId": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["sequence", "parallel", "gate", "handoff"] },
+        "status": { "$ref": "#/$defs/status" },
+        "order": { "type": "number" },
+        "updatedAt": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    },
+    "touch": {
+      "type": "object",
+      "required": ["locator", "at"],
+      "properties": {
+        "locator": { "type": "string" },
+        "operation": { "type": "string" },
+        "at": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    },
+    "artifact": {
+      "type": "object",
+      "required": ["locator", "at"],
+      "properties": {
+        "locator": { "type": "string" },
+        "at": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    },
+    "run": {
+      "type": "object",
+      "required": [
+        "runId",
+        "command",
+        "status",
+        "startedAt",
+        "updatedAt",
+        "blocks",
+        "edges",
+        "touches",
+        "artifacts",
+        "warnings"
+      ],
+      "properties": {
+        "runId": { "type": "string", "minLength": 1 },
+        "parentRunId": { "type": "string", "minLength": 1 },
+        "pid": { "type": "integer", "minimum": 1 },
+        "orphaned": { "type": "boolean" },
+        "origin": { "$ref": "#/$defs/origin" },
+        "command": { "type": "array", "items": { "type": "string" } },
+        "status": { "$ref": "#/$defs/status" },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "durationMs": { "type": "number", "minimum": 0 },
+        "blocks": { "type": "array", "items": { "$ref": "#/$defs/block" } },
+        "edges": { "type": "array", "items": { "$ref": "#/$defs/edge" } },
+        "touches": { "type": "array", "items": { "$ref": "#/$defs/touch" } },
+        "artifacts": { "type": "array", "items": { "$ref": "#/$defs/artifact" } },
+        "warnings": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    }
+  }
+}