workspai 0.64.0 → 0.66.0

package/README.md

@@ -18,28 +18,28 @@ npx workspai adopt .
 npx workspai workspace intelligence run --for-agent generic
 ```
 
-Two commands. Your project becomes a fully understood workspace:
+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 reads one bounded context document |
+| 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 names the failing project and fix path |
+| 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 every project, runtime, framework, and dependency |
+| **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** | 14 read-oriented tools so MCP clients can query evidence, graph, blockers, and context live |
+| **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
@@ -47,46 +47,31 @@ for every supported host, without duplicating the Model or Graph.
 
 ### What the output looks like
 
-After a single run, `.workspai/` contains everything agents and CI need:
+After a single run, the canonical workspace stores governed artifacts under
+`.workspai/`. Each linked project keeps only its local entry contract, scoped
+lens, and workspace binding under its own `.workspai/` directory:
 
 ```text
-your-workspace/                              # ── Workspace level ──
+your-workspace/                         # canonical system boundary
 ├── .workspai/
-│   ├── workspace.json                       # workspace identity & profile
-│   ├── workspace.contract.json              # project registry, ports, APIs
-│   ├── reports/                             # intelligence artifacts
-│   │   ├── workspace-model.json             # projects, runtimes, deps
-│   │   ├── workspace-knowledge-graph.json   # proof-backed relationships
-│   │   ├── workspace-context-agent.json     # bounded context for AI agents
-│   │   ├── workspace-skills-index.json      # operational skills inventory
-│   │   ├── workspace-verify-last-run.json   # pass/fail with evidence
-│   │   ├── INDEX.json                       # evidence inventory & read order
-│   │   └── ...                              # impact, doctor, analyze, explain, etc.
-│   └── skills/                              # generated operational skills
-│       ├── workspai-release-readiness.md     # always available
-│       ├── workspai-node-runtime-validation.md  # only when Node is detected
-│       └── workspai-polyglot-change-validation.md # only for multi-runtime workspaces
-│
-│  # Workspace-level agent grounding (per host):
+│   ├── workspace.contract.json         # registered projects and declarations
+│   ├── reports/
+│   │   ├── workspace-model.json        # canonical system model
+│   │   ├── workspace-knowledge-graph.json # derived proof-backed graph
+│   │   ├── workspace-context-agent.json   # bounded consumer context
+│   │   └── INDEX.json                  # evidence inventory and read order
+│   └── skills/                         # detected operational playbooks
 ├── AGENTS.md · CLAUDE.md · GEMINI.md · QWEN.md
-├── .cursor/rules/workspai-*.mdc             # 5 rules + skill
-├── .claude/rules/workspai-*.md              # workspace + evidence
-├── .grok/rules/ · .windsurf/rules/          # grounding + evidence
-├── .amazonq/rules/ · .github/               # Copilot, prompts, agents, skills
-│
-│  # ── Project level (repeated per project) ──
+├── .cursor/ · .claude/ · .github/ · .agents/ # host-native projections
 ├── nova-api/
-│   ├── .workspai/
-│   │   ├── project.json                     # project identity & metadata
-│   │   ├── workspace-link.local.json        # machine-local workspace binding
-│   │   ├── agent-entry.v1.json              # canonical agent entry point
-│   │   ├── PROJECT-GROUNDING.md             # project-level grounding
-│   │   └── reports/
-│   │       └── project-context-agent.json   # scoped project context
-│   ├── AGENTS.md · CLAUDE.md · GEMINI.md · QWEN.md
-│   └── .amazonq/rules/workspai-agent-entry.md
-│
-└── summit-web/                              # (same structure per project)
+│   ├── .agents/skills/workspai-*/SKILL.md # portable project Skill wrappers
+│   └── .workspai/
+│       ├── agent-entry.v1.json         # canonical project entry
+│       ├── workspace-link.local.json   # machine-local binding
+│       └── reports/
+│           ├── project-context-agent.json
+│           └── project-knowledge-graph-reference.json
+└── summit-web/                         # same project-level boundary
 ```
 
 Your agent starts with `agent-entry.v1.json`, compact workspace context, and the Skills
@@ -105,8 +90,8 @@ scan or complete Graph load is needed for ordinary work.
 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.
 
-- **See the whole system:** every project, service, and dependency in one model.
-- **Ask with proof:** trace any answer back to the exact file and line.
+- **See the whole system:** registered projects and proven relationships in one model.
+- **Ask with proof:** trace answers back to their evidence record and source location.
 - **Change safely:** know impact before you commit, verify after, and give AI agents
   only the context they need.
 
@@ -202,7 +187,7 @@ generated in one run. The key files for each audience:
 | **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` (14 read-oriented tools over JSON-RPC) |
+| **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
@@ -264,6 +249,17 @@ complements this chain; it does not replace it.
 
 The deterministic model, graph, and checks do not require an AI API key.
 
+### See the evidence-backed graph
+
+The graph connects projects, APIs, packages, tests, infrastructure, ownership,
+and runtime topology only when current evidence supports the relationship.
+Every visible relationship can retain proof, while missing relationships stay
+explicitly unproven.
+
+![Interactive 3D view of a real Workspai workspace graph](https://raw.githubusercontent.com/chistiq/workspai/main/packages/cli/docs/workspace-graph.gif)
+
+[Query, explain, and export the graph](docs/workspace-knowledge-graph.md)
+
 ## Everyday workflows
 
 | Goal                                       | Command                                                                          |
@@ -294,7 +290,7 @@ Workspai exposes the same governed data through several stable surfaces:
 - JSON output for scripts and CI;
 - versioned artifacts under `.workspai/reports/`;
 - focused context and instructions for AI agents;
-- MCP server with 14 read-oriented workspace tools (`workspace mcp serve`);
+- MCP server with versioned read-oriented workspace tools (`workspace mcp serve`);
 - watch events and reports for IDEs and dashboards;
 - JSON, JSON-LD, Mermaid, DOT, GraphML, and GEXF graph exports.
 

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

@@ -52,9 +52,10 @@
       ]
     },
     "agents": {
-      "meaning": "Generate portable AGENTS.md grounding for any agent.",
+      "meaning": "Generate portable AGENTS.md grounding and .agents/skills projections.",
       "outputFamilies": [
-        "portable"
+        "portable",
+        "skills"
       ]
     },
     "copilot": {
@@ -281,6 +282,7 @@
       ".workspai/skills/"
     ],
     "l2PrefixedMirrorRoots": [
+      ".agents/",
       ".github/",
       ".cursor/",
       ".claude/",

package/contracts/analyze-last-run.v1.json

@@ -26,8 +26,16 @@
     "profile": { "type": ["string", "null"] },
     "summary": {
       "type": "object",
-      "required": ["score", "verdict", "projectCount", "runtimeCount", "findings"],
+      "required": [
+        "score",
+        "verdict",
+        "projectCount",
+        "runtimeCount",
+        "findings"
+      ],
       "properties": {
+        "statusScope": { "const": "source-structure" },
+        "releaseReadiness": { "const": "not-evaluated" },
         "score": { "type": "number" },
         "verdict": {
           "enum": ["ready", "needs-attention", "blocked"]

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

@@ -727,6 +727,98 @@
         }
       ]
     },
+    {
+      "path": [
+        "live"
+      ],
+      "command": "live",
+      "parent": null,
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Open a live cross-terminal execution graph for Workspai activity",
+      "hidden": false,
+      "arguments": [
+        {
+          "name": "target",
+          "required": false,
+          "variadic": false
+        }
+      ],
+      "options": [
+        {
+          "flags": "--global",
+          "attributeName": "global"
+        },
+        {
+          "flags": "--run <runId>",
+          "attributeName": "run"
+        },
+        {
+          "flags": "--once",
+          "attributeName": "once"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--refresh-ms <milliseconds>",
+          "attributeName": "refreshMs"
+        },
+        {
+          "flags": "--max-runs <count>",
+          "attributeName": "maxRuns"
+        },
+        {
+          "flags": "--max-scopes <count>",
+          "attributeName": "maxScopes"
+        },
+        {
+          "flags": "--classic",
+          "attributeName": "classic"
+        },
+        {
+          "flags": "--no-color",
+          "attributeName": "color"
+        },
+        {
+          "flags": "--no-motion",
+          "attributeName": "motion"
+        },
+        {
+          "flags": "--ascii",
+          "attributeName": "ascii"
+        },
+        {
+          "flags": "--accessible",
+          "attributeName": "accessible"
+        },
+        {
+          "flags": "--capture <file>",
+          "attributeName": "capture"
+        },
+        {
+          "flags": "--capture-preset <preset>",
+          "attributeName": "capturePreset"
+        },
+        {
+          "flags": "--capture-theme <theme>",
+          "attributeName": "captureTheme"
+        },
+        {
+          "flags": "--no-capture-redact",
+          "attributeName": "captureRedact"
+        },
+        {
+          "flags": "--replay <runId>",
+          "attributeName": "replay"
+        },
+        {
+          "flags": "--replay-speed <multiplier>",
+          "attributeName": "replaySpeed"
+        }
+      ]
+    },
     {
       "path": [
         "mirror"
@@ -1469,10 +1561,30 @@
           "flags": "--scan-depth <count>",
           "attributeName": "scanDepth"
         },
+        {
+          "flags": "--graph-inventory-limit <count>",
+          "attributeName": "graphInventoryLimit"
+        },
+        {
+          "flags": "--graph-semantic-budget <count>",
+          "attributeName": "graphSemanticBudget"
+        },
+        {
+          "flags": "--graph-deep-budget <count>",
+          "attributeName": "graphDeepBudget"
+        },
+        {
+          "flags": "--graph-source-budget <count>",
+          "attributeName": "graphSourceBudget"
+        },
         {
           "flags": "--limit <count>",
           "attributeName": "limit"
         },
+        {
+          "flags": "--kind <kind>",
+          "attributeName": "kind"
+        },
         {
           "flags": "--refresh-graph",
           "attributeName": "refreshGraph"
@@ -1593,6 +1705,10 @@
           "flags": "--parallel",
           "attributeName": "parallel"
         },
+        {
+          "flags": "--plan",
+          "attributeName": "plan"
+        },
         {
           "flags": "--runtime <runtime>",
           "attributeName": "runtime"
@@ -1703,6 +1819,7 @@
     "goal",
     "import",
     "infra",
+    "live",
     "mirror",
     "pipeline",
     "product",

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

@@ -18,6 +18,7 @@
     "projectWorkspaceLink": "project-workspace-link.v1",
     "projectWorkspaceResolution": "project-workspace-resolution.v1",
     "projectContextAgent": "project-context-agent.v1",
+    "projectKnowledgeGraphReference": "project-knowledge-graph-reference.v1",
     "projectAgentEntry": "workspai.agent-entry.v1",
     "agentBootstrapReceipt": "workspai.agent-bootstrap-receipt.v1",
     "doctorProjectEvidence": "doctor-project-evidence-v1",
@@ -63,6 +64,7 @@
       "repairTransaction": "workspai.workspace-repair-transaction.v1"
     },
     "cliLogEvent": "cli-log-event-v1",
+    "workspaceActivityEvent": "workspace-activity-event.v1",
     "freshnessMetadata": "rapidkit-freshness-metadata-v1",
     "factFreshness": "rapidkit-fact-freshness-v1",
     "blockerResolution": "rapidkit-blocker-resolution-v1",

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

@@ -76,6 +76,11 @@
       "contractPath": "contracts/workspace-intelligence/project-context-agent.v1.json",
       "publication": "json-schema"
     },
+    "projectKnowledgeGraphReference": {
+      "schemaVersion": "project-knowledge-graph-reference.v1",
+      "contractPath": "contracts/workspace-intelligence/project-knowledge-graph-reference.v1.json",
+      "publication": "json-schema"
+    },
     "projectAgentEntry": {
       "schemaVersion": "workspai.agent-entry.v1",
       "contractPath": "contracts/workspace-intelligence/project-agent-entry.v1.json",
@@ -321,6 +326,11 @@
       "contractPath": "contracts/cli-log-event.v1.json",
       "publication": "json-schema"
     },
+    "workspaceActivityEvent": {
+      "schemaVersion": "workspace-activity-event.v1",
+      "contractPath": "contracts/workspace-activity-event.v1.json",
+      "publication": "json-schema"
+    },
     "freshnessMetadata": {
       "schemaVersion": "rapidkit-freshness-metadata-v1",
       "contractPath": null,

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

@@ -51,6 +51,7 @@
     "goal",
     "agent",
     "snapshot",
+    "live",
     "bootstrap",
     "setup",
     "cache",
@@ -557,6 +558,13 @@
         "list"
       ]
     },
+    {
+      "invocation": "live",
+      "summary": "Render the versioned cross-terminal execution graph for Workspai runs in the current project or workspace.",
+      "canonicalArgv": [
+        "live"
+      ]
+    },
     {
       "invocation": "merge",
       "summary": "Combine supported governed configuration or project state through the owning runtime operation.",
@@ -1901,6 +1909,32 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/reports/project-knowledge-graph-reference.json",
+      "schemaVersion": "project-knowledge-graph-reference.v1",
+      "contractPath": "contracts/workspace-intelligence/project-knowledge-graph-reference.v1.json",
+      "producerCommands": [
+        [
+          "adopt"
+        ],
+        [
+          "import"
+        ],
+        [
+          "workspace",
+          "model"
+        ],
+        [
+          "workspace",
+          "sync"
+        ],
+        [
+          "workspace",
+          "intelligence",
+          "run"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/agent-entry.v1.json",
       "schemaVersion": "workspai.agent-entry.v1",
@@ -2694,6 +2728,10 @@
           "flag": "--limit",
           "description": "Bound graph query results (1–100)."
         },
+        {
+          "flag": "--kind",
+          "description": "Limit graph entity search to one canonical entity kind."
+        },
         {
           "flag": "--refresh-graph",
           "description": "Bypass the compatible persisted graph and rebuild from live sources."
@@ -2732,7 +2770,7 @@
       ],
       "artifact": null,
       "examples": [
-        "workspai workspace graph search \"authentication endpoint\" --limit 12 --json",
+        "workspai workspace graph search \"authentication endpoint\" --kind endpoint --limit 12 --json",
         "workspai workspace graph evidence \"GET /users\" --json",
         "workspai workspace graph mermaid"
       ]
@@ -3209,8 +3247,8 @@
     },
     {
       "id": "contract",
-      "usage": "workspai workspace contract [init|inspect|verify|graph] [--strict] [--json]",
-      "summary": "Create, inspect, verify, or project the workspace contract.",
+      "usage": "workspai workspace contract [init|inspect|sync|verify|graph] [--strict] [--json]",
+      "summary": "Create, inspect, synchronize, verify, or project the workspace contract.",
       "options": [
         {
           "flag": "--workspace",
@@ -3236,11 +3274,13 @@
       "subactions": [
         "init",
         "inspect",
+        "sync",
         "verify",
         "graph"
       ],
       "artifact": ".workspai/workspace.contract.json",
       "examples": [
+        "workspai workspace contract sync --strict --json",
         "workspai workspace contract verify --strict --json",
         "workspai workspace contract graph --json"
       ]
@@ -3492,6 +3532,14 @@
           "flag": "--scope",
           "description": "Limit the operation to a bounded scope such as project:<name>."
         },
+        {
+          "flag": "--plan",
+          "description": "Resolve lifecycle commands without executing project code."
+        },
+        {
+          "flag": "--runtime",
+          "description": "Limit lifecycle planning or execution to one detected runtime family."
+        },
         {
           "flag": "--affected",
           "description": "Run only projects affected by the selected Git change."
@@ -3538,6 +3586,7 @@
       ],
       "artifact": ".workspai/reports/workspace-run-last.json",
       "examples": [
+        "workspai workspace run test --scope project:api --plan --runtime ruby --json",
         "workspai workspace run test --affected --blast-radius --strict",
         "workspai workspace run build --parallel --max-workers 4 --json"
       ]
@@ -4133,6 +4182,13 @@
       "moduleCommands": false,
       "doctor": "observed",
       "lifecycleCommands": [
+        "init",
+        "dev",
+        "start",
+        "build",
+        "test",
+        "lint",
+        "format",
         "help"
       ]
     },

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

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/contracts/workspace-activity-event.v1.json",
+  "title": "Workspai Workspace Activity Event",
+  "description": "Local-first operational activity emitted by Workspai commands. Activity is observational and does not by itself establish evidence or decision authority.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "eventId",
+    "sequence",
+    "timestamp",
+    "runId",
+    "scope",
+    "kind",
+    "status",
+    "component",
+    "message"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspace-activity-event.v1" },
+    "eventId": { "type": "string", "minLength": 8 },
+    "sequence": { "type": "integer", "minimum": 1 },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "runId": { "type": "string", "minLength": 8 },
+    "parentRunId": { "type": "string", "minLength": 8 },
+    "spanId": { "type": "string", "minLength": 1 },
+    "parentSpanId": { "type": "string", "minLength": 1 },
+    "causationId": { "type": "string", "minLength": 1 },
+    "correlationId": { "type": "string", "minLength": 1 },
+    "scope": {
+      "type": "object",
+      "required": ["kind", "id", "label", "portable"],
+      "properties": {
+        "kind": { "enum": ["ephemeral-project", "project", "workspace"] },
+        "id": { "type": "string", "minLength": 8 },
+        "label": { "type": "string", "minLength": 1 },
+        "portable": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "kind": {
+      "enum": [
+        "run.started",
+        "run.completed",
+        "run.failed",
+        "run.cancelled",
+        "block.planned",
+        "block.started",
+        "block.progress",
+        "block.completed",
+        "block.failed",
+        "block.blocked",
+        "block.skipped",
+        "edge.declared",
+        "operation.started",
+        "operation.completed",
+        "operation.failed",
+        "touch.planned",
+        "touch.observed",
+        "artifact.published",
+        "artifact.rejected",
+        "warning.detected"
+      ]
+    },
+    "status": {
+      "enum": [
+        "planned",
+        "running",
+        "succeeded",
+        "warned",
+        "blocked",
+        "failed",
+        "cancelled",
+        "skipped",
+        "rolled-back"
+      ]
+    },
+    "component": { "type": "string", "minLength": 1 },
+    "message": { "type": "string", "minLength": 1 },
+    "blockId": { "type": "string", "minLength": 1 },
+    "attempt": { "type": "integer", "minimum": 1 },
+    "origin": {
+      "type": "object",
+      "required": ["id", "kind", "label"],
+      "properties": {
+        "id": { "type": "string", "minLength": 8 },
+        "kind": { "enum": ["project", "workspace-root"] },
+        "label": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "projectId": { "type": "string", "minLength": 1 },
+    "durationMs": { "type": "number", "minimum": 0 },
+    "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
+    },
+    "target": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "enum": ["file", "directory", "artifact", "process", "workspace", "project", "other"]
+        },
+        "locator": { "type": "string" },
+        "operation": { "type": "string" },
+        "provenance": { "enum": ["authoritative", "observed", "inferred"] }
+      },
+      "additionalProperties": false
+    },
+    "edge": {
+      "type": "object",
+      "required": ["id", "fromBlockId", "toBlockId", "kind"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "fromBlockId": { "type": "string", "minLength": 1 },
+        "toBlockId": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["sequence", "parallel", "gate", "handoff"] }
+      },
+      "additionalProperties": false
+    },
+    "attributes": { "type": "object", "additionalProperties": true }
+  },
+  "additionalProperties": false
+}