workspai 0.56.0 → 0.58.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
 
@@ -134,6 +162,7 @@ The deterministic model, graph, and checks do not require an AI API key.
 | --- | --- |
 | Use guided setup | `npx workspai create` |
 | Link a project without moving it | `npx workspai adopt .` |
+| Turn an outcome into governed work | `npx workspai goal "Raise test coverage to 85%"` |
 | Copy or clone a project into a workspace | `npx workspai import <path-or-git-url> --workspace <path>` |
 | Check the current project | `npx workspai doctor project` |
 | Check the whole workspace | `npx workspai doctor workspace` |
@@ -184,6 +213,7 @@ modules; Workspai remains the workspace-level CLI.
 | Understand the exact decision loop | [Workspace Intelligence runner](docs/workspace-intelligence-runner.md) |
 | Plan, approve, execute, or roll back a repair | [Workspace Repair Engine](docs/workspace-repair-engine.md) |
 | Set a release, security, or coverage outcome | [Verified engineering goals](docs/workspace-intelligence-runner.md#verified-engineering-goals) |
+| Compile plain language into a governed plan | [Goal Packs](docs/goal-packs.md) |
 | Integrate CI | [CI workflows](docs/ci-workflows.md) |
 | Find generated files and schemas | [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md) |
 | Browse all documentation | [Documentation index](docs/README.md) |

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/agent-customization-pack.v1.json

@@ -95,6 +95,16 @@
     "Assumptions"
   ],
   "requiredReports": [
+    {
+      "path": ".workspai/goals/index.json",
+      "label": "Active Goal Pack index",
+      "required": false
+    },
+    {
+      "path": ".workspai/reports/goal-pack-last-run.json",
+      "label": "Latest governed Goal Pack",
+      "required": false
+    },
     {
       "path": ".workspai/reports/workspace-context-agent.json",
       "label": "Agent context pack",

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

@@ -384,6 +384,10 @@
           "flags": "--fresh",
           "attributeName": "fresh"
         },
+        {
+          "flags": "--verbose",
+          "attributeName": "verbose"
+        },
         {
           "flags": "--strict",
           "attributeName": "strict"
@@ -426,6 +430,82 @@
         }
       ]
     },
+    {
+      "path": [
+        "goal"
+      ],
+      "command": "goal",
+      "parent": null,
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Compile a plain-language engineering intent into a governed, evidence-bound Goal Pack",
+      "hidden": false,
+      "arguments": [
+        {
+          "name": "intent",
+          "required": false,
+          "variadic": false
+        }
+      ],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--scope <scope>",
+          "attributeName": "scope"
+        },
+        {
+          "flags": "--for-agent <consumer>",
+          "attributeName": "forAgent"
+        },
+        {
+          "flags": "--max-attempts <count>",
+          "attributeName": "maxAttempts"
+        },
+        {
+          "flags": "--refresh",
+          "attributeName": "refresh"
+        },
+        {
+          "flags": "--dry-run",
+          "attributeName": "dryRun"
+        },
+        {
+          "flags": "--status [goal-id]",
+          "attributeName": "status"
+        },
+        {
+          "flags": "--list",
+          "attributeName": "list"
+        },
+        {
+          "flags": "--activate <goal-id>",
+          "attributeName": "activate"
+        },
+        {
+          "flags": "--cancel <goal-id>",
+          "attributeName": "cancel"
+        },
+        {
+          "flags": "--prepare <goal-id>",
+          "attributeName": "prepare"
+        },
+        {
+          "flags": "--verify <goal-id>",
+          "attributeName": "verify"
+        },
+        {
+          "flags": "--no-run",
+          "attributeName": "run"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        }
+      ]
+    },
     {
       "path": [
         "import"
@@ -1526,6 +1606,7 @@
     "config",
     "create",
     "doctor",
+    "goal",
     "import",
     "infra",
     "mirror",

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

@@ -270,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"],
@@ -282,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": [
@@ -300,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

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

@@ -68,6 +68,8 @@
         "verdict": { "enum": ["passed", "attention", "blocked"] },
         "blockingFindings": { "type": "integer", "minimum": 0 },
         "advisoryFindings": { "type": "integer", "minimum": 0 },
+        "unknownFindings": { "type": "integer", "minimum": 0 },
+        "contradictionFindings": { "type": "integer", "minimum": 0 },
         "hasSystemErrors": { "type": "boolean" },
         "scopeProvenance": { "type": "object", "additionalProperties": true }
       },
@@ -280,6 +282,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"],
@@ -292,6 +295,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": [
@@ -310,6 +337,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

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

@@ -13,6 +13,7 @@
     "workspaceArchiveOperationResult": "workspai-workspace-archive-operation-result-v1",
     "ingestionPlan": "workspai.ingestion-plan.v1",
     "ingestionResult": "workspai.ingestion-result.v1",
+    "adoptEffects": "workspai.adopt-effects.v1",
     "projectEntryCapability": "workspai-project-entry-capability-v1",
     "projectWorkspaceLink": "project-workspace-link.v1",
     "projectWorkspaceResolution": "project-workspace-resolution.v1",
@@ -28,6 +29,11 @@
     "projectTestCoverage": "workspai.project-test-coverage.v1",
     "verifiedGoal": "workspai.verified-goal.v1",
     "verifiedGoalStatus": "workspai.verified-goal-status.v1",
+    "goalPack": "workspai.goal-pack.v1",
+    "goalAgentHandoff": "workspai.goal-agent-handoff.v1",
+    "goalPlanResult": "workspai.goal-plan-result.v1",
+    "goalIndex": "workspai.goal-index.v1",
+    "goalLifecycleResult": "workspai.goal-lifecycle-result.v1",
     "workspaceIntelligenceArchitecture": "workspai-workspace-intelligence-architecture-v1",
     "workspaceIntelligenceChain": "workspai-workspace-intelligence-chain-v1",
     "workspaceIntelligenceArtifacts": {

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

@@ -51,6 +51,11 @@
       "contractPath": "contracts/ingestion-result.v1.json",
       "publication": "json-schema"
     },
+    "adoptEffects": {
+      "schemaVersion": "workspai.adopt-effects.v1",
+      "contractPath": "contracts/adopt-effects.v1.json",
+      "publication": "json-schema"
+    },
     "projectEntryCapability": {
       "schemaVersion": "workspai-project-entry-capability-v1",
       "contractPath": "contracts/project-entry-capability.v1.json",
@@ -126,6 +131,31 @@
       "contractPath": "contracts/workspace-intelligence/verified-goal-status.v1.json",
       "publication": "json-schema"
     },
+    "goalPack": {
+      "schemaVersion": "workspai.goal-pack.v1",
+      "contractPath": "contracts/workspace-intelligence/goal-pack.v1.json",
+      "publication": "json-schema"
+    },
+    "goalAgentHandoff": {
+      "schemaVersion": "workspai.goal-agent-handoff.v1",
+      "contractPath": "contracts/workspace-intelligence/goal-agent-handoff.v1.json",
+      "publication": "json-schema"
+    },
+    "goalPlanResult": {
+      "schemaVersion": "workspai.goal-plan-result.v1",
+      "contractPath": "contracts/workspace-intelligence/goal-plan-result.v1.json",
+      "publication": "json-schema"
+    },
+    "goalIndex": {
+      "schemaVersion": "workspai.goal-index.v1",
+      "contractPath": "contracts/workspace-intelligence/goal-index.v1.json",
+      "publication": "json-schema"
+    },
+    "goalLifecycleResult": {
+      "schemaVersion": "workspai.goal-lifecycle-result.v1",
+      "contractPath": "contracts/workspace-intelligence/goal-lifecycle-result.v1.json",
+      "publication": "json-schema"
+    },
     "workspaceIntelligenceArchitecture": {
       "schemaVersion": "workspai-workspace-intelligence-architecture-v1",
       "contractPath": "contracts/workspace-intelligence-architecture.v1.json",

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

@@ -48,6 +48,7 @@
     "pipeline",
     "import",
     "adopt",
+    "goal",
     "snapshot",
     "bootstrap",
     "setup",
@@ -420,6 +421,30 @@
         "frameworks"
       ]
     },
+    {
+      "invocation": "goal",
+      "summary": "Compile a plain-language engineering intent into a scope-bound, evidence-pinned Goal Pack and portable agent handoff without mutating source.",
+      "canonicalArgv": [
+        "goal",
+        "<intent>",
+        "--json"
+      ],
+      "output": {
+        "defaultFormat": "human-or-json",
+        "modes": [
+          {
+            "selector": "--json",
+            "format": "json",
+            "mediaType": "application/json"
+          }
+        ]
+      },
+      "exitSemantics": {
+        "default": "A contract-valid Goal Pack returns exit code 0, including explicit needs-confirmation, needs-evidence, or blocked planning states.",
+        "strict": "Not applicable; Goal planning does not execute or verify source changes.",
+        "failure": "Resolution, freshness, contract, integrity, or publication failure returns exit code 1."
+      }
+    },
     {
       "invocation": "help",
       "summary": "Display contextual CLI usage, arguments, options, and command discovery guidance.",
@@ -1790,6 +1815,16 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/goals/index.json",
+      "schemaVersion": "workspai.goal-index.v1",
+      "contractPath": "contracts/workspace-intelligence/goal-index.v1.json",
+      "producerCommands": [
+        [
+          "goal"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/workspace-link.local.json",
       "schemaVersion": "project-workspace-link.v1",
@@ -1998,6 +2033,16 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/reports/goal-pack-last-run.json",
+      "schemaVersion": "workspai.goal-pack.v1",
+      "contractPath": "contracts/workspace-intelligence/goal-pack.v1.json",
+      "producerCommands": [
+        [
+          "goal"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/reports/doctor-remediation-plan-last-run.json",
       "schemaVersion": "doctor-remediation-plan-v2",

package/contracts/workspace-intelligence/doctor-summary.v1.json

@@ -27,7 +27,8 @@
         "name": { "type": "string" },
         "path": { "type": "string" },
         "runtimeFamily": { "type": "string" },
-        "framework": { "type": "string" }
+        "framework": { "type": "string" },
+        "projectArchetype": { "enum": ["application", "service", "library", "sdk", "platform", "plugin", "monorepo", "unknown"] }
       },
       "additionalProperties": false
     },
@@ -40,6 +41,7 @@
           "name": { "type": "string" },
           "path": { "type": "string" },
           "runtimeFamily": { "type": "string" },
+          "projectArchetype": { "enum": ["application", "service", "library", "sdk", "platform", "plugin", "monorepo", "unknown"] },
           "verdict": { "enum": ["passed", "attention", "blocked"] },
           "blockingCauses": { "type": "integer", "minimum": 0 },
           "advisoryFindings": { "type": "integer", "minimum": 0 },

package/contracts/workspace-intelligence/goal-agent-handoff.v1.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/goal-agent-handoff.v1.json",
+  "title": "Workspai Goal Agent Handoff",
+  "type": "object",
+  "required": ["schemaVersion", "goalId", "goalFingerprint", "generatedAt", "consumer", "state", "objective", "scope", "discovery", "retrieval", "evidence", "guardrails", "workflow", "renewal"],
+  "properties": {
+    "schemaVersion": { "const": "workspai.goal-agent-handoff.v1" },
+    "goalId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{7,95}$" },
+    "goalFingerprint": { "$ref": "#/$defs/hash" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "consumer": { "enum": ["generic", "claude", "codex"] },
+    "state": { "enum": ["ready-to-plan", "needs-confirmation", "needs-evidence", "blocked"] },
+    "objective": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "scope": {
+      "type": "object",
+      "required": ["kind", "projects", "selectionSource"],
+      "properties": {
+        "kind": { "enum": ["workspace", "project"] },
+        "projects": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "selectionSource": { "enum": ["workspace", "invocation-project", "explicit"] }
+      },
+      "additionalProperties": false
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 3,
+      "items": {
+        "type": "object",
+        "required": ["role", "artifact", "binding"],
+        "properties": {
+          "role": { "enum": ["model", "graph", "goal"] },
+          "artifact": { "type": "string", "pattern": "^\\.workspai/" },
+          "binding": {
+            "type": "object",
+            "required": ["algorithm", "semantics", "value"],
+            "properties": {
+              "algorithm": { "const": "sha256" },
+              "semantics": { "enum": ["workspace-model-structural-v1", "canonical-json-v1"] },
+              "value": { "$ref": "#/$defs/hash" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "discovery": {
+      "type": "object",
+      "required": ["index", "statusCommand", "requiredReads"],
+      "properties": {
+        "index": { "const": ".workspai/goals/index.json" },
+        "statusCommand": { "type": "string", "pattern": "^workspai goal --status " },
+        "requiredReads": { "type": "array", "minItems": 3, "items": { "type": "string", "pattern": "^\\.workspai/" }, "uniqueItems": true }
+      },
+      "additionalProperties": false
+    },
+    "retrieval": {
+      "type": "object",
+      "required": ["status", "strategy", "queries", "anchors"],
+      "properties": {
+        "status": { "enum": ["grounded", "partial", "empty"] },
+        "strategy": { "const": "deterministic-category-v1" },
+        "queries": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "anchors": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": ["entityId", "kind", "label", "proofIds"], "properties": { "entityId": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "proofIds": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } }, "additionalProperties": false } }
+      },
+      "additionalProperties": false
+    },
+    "guardrails": { "type": "array", "minItems": 5, "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "workflow": {
+      "type": "array",
+      "minItems": 5,
+      "items": {
+        "type": "object",
+        "required": ["order", "owner", "instruction"],
+        "properties": {
+          "order": { "type": "integer", "minimum": 1 },
+          "owner": { "enum": ["workspai-cli", "agent", "human"] },
+          "instruction": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "renewal": {
+      "type": "object",
+      "required": ["command", "reason"],
+      "properties": {
+        "command": { "type": "string", "pattern": "^workspai goal " },
+        "reason": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": { "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
+  "additionalProperties": false
+}