workspai 0.57.0 → 0.59.0

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

@@ -48,6 +48,8 @@
     "pipeline",
     "import",
     "adopt",
+    "goal",
+    "agent",
     "snapshot",
     "bootstrap",
     "setup",
@@ -79,6 +81,10 @@
       "ai",
       "update-embeddings"
     ],
+    [
+      "agent",
+      "bootstrap"
+    ],
     [
       "config",
       "ai"
@@ -128,6 +134,10 @@
       "project",
       "commands"
     ],
+    [
+      "project",
+      "agent-entry"
+    ],
     [
       "project",
       "coverage"
@@ -184,6 +194,21 @@
         "adopt"
       ]
     },
+    {
+      "invocation": "agent",
+      "summary": "Resolve portable project entry contracts and issue canonical-first grounding receipts for coding agents.",
+      "canonicalArgv": [
+        "agent"
+      ]
+    },
+    {
+      "invocation": "agent bootstrap",
+      "summary": "Validate host discovery, workspace membership, evidence freshness, live inputs, and active Goal bindings before broad source discovery.",
+      "canonicalArgv": [
+        "agent",
+        "bootstrap"
+      ]
+    },
     {
       "invocation": "ai",
       "summary": "Manage AI configuration, recommendations, and embedding operations for the active workspace.",
@@ -420,6 +445,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.",
@@ -614,6 +663,14 @@
         "project"
       ]
     },
+    {
+      "invocation": "project agent-entry",
+      "summary": "Verify portable entry adapters and canonical evidence bindings for one or every supported agent host.",
+      "canonicalArgv": [
+        "project",
+        "agent-entry"
+      ]
+    },
     {
       "invocation": "project archive",
       "summary": "Move a project into governed archive storage while preserving registry metadata and recovery evidence.",
@@ -1790,6 +1847,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",
@@ -1834,6 +1901,28 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/agent-entry.v1.json",
+      "schemaVersion": "workspai.agent-entry.v1",
+      "contractPath": "contracts/workspace-intelligence/project-agent-entry.v1.json",
+      "producerCommands": [
+        [
+          "adopt"
+        ],
+        [
+          "import"
+        ],
+        [
+          "workspace",
+          "sync"
+        ],
+        [
+          "workspace",
+          "agent-sync",
+          "--write"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/workspace.contract.json",
       "schemaVersion": 1,
@@ -1998,6 +2087,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/agent-bootstrap-receipt.v1.json

@@ -0,0 +1,247 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/agent-bootstrap-receipt.v1.json",
+  "title": "Workspai Agent Bootstrap Receipt",
+  "description": "Portable per-session proof that an agent resolved canonical project evidence before broad source discovery.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "receiptId",
+    "status",
+    "requestedAgent",
+    "resolvedHost",
+    "project",
+    "workspace",
+    "entry",
+    "canonicalEvidence",
+    "activeGoal",
+    "requiredReadOrder",
+    "claims",
+    "checks",
+    "nextActions",
+    "integrity"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspai.agent-bootstrap-receipt.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "receiptId": { "$ref": "#/$defs/hash" },
+    "status": { "$ref": "#/$defs/status" },
+    "requestedAgent": {
+      "enum": [
+        "generic",
+        "codex",
+        "claude",
+        "gemini",
+        "qwen",
+        "kimi",
+        "grok",
+        "copilot",
+        "cursor",
+        "windsurf",
+        "amazon-q",
+        "all"
+      ]
+    },
+    "resolvedHost": {
+      "enum": [
+        "generic",
+        "codex",
+        "claude",
+        "gemini",
+        "qwen",
+        "kimi",
+        "grok",
+        "copilot",
+        "cursor",
+        "windsurf",
+        "amazon-q",
+        "all"
+      ]
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "relativePath"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "relativePath": { "$ref": "#/$defs/portablePath" },
+        "runtime": { "type": "string", "minLength": 1 },
+        "framework": { "type": "string", "minLength": 1 }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "relationship",
+        "resolved",
+        "identityIsFilesystemPath",
+        "resolverCommand",
+        "portableUriScheme",
+        "resolvedPathPolicy"
+      ],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "relationship": {
+          "enum": ["managed", "adopted", "imported", "linked", "restored"]
+        },
+        "resolved": { "const": true },
+        "identityIsFilesystemPath": { "const": false },
+        "resolverCommand": { "const": "workspai project workspace status --json" },
+        "portableUriScheme": { "const": "workspace:" },
+        "resolvedPathPolicy": { "const": "runtime-private-never-persist" }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifact", "schemaVersion", "hostStatus", "entryFiles"],
+      "properties": {
+        "artifact": { "const": ".workspai/agent-entry.v1.json" },
+        "schemaVersion": { "const": "workspai.agent-entry.v1" },
+        "hostStatus": { "$ref": "#/$defs/status" },
+        "entryFiles": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/portablePath" }
+        }
+      }
+    },
+    "canonicalEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "projectContext",
+        "workspaceIndex",
+        "workspaceContext",
+        "workspaceModel",
+        "knowledgeGraph",
+        "modelFreshness",
+        "graphFreshness",
+        "graphMatchesModel",
+        "liveInputsValidated",
+        "blockerCount"
+      ],
+      "properties": {
+        "projectContext": { "const": ".workspai/reports/project-context-agent.json" },
+        "workspaceIndex": { "const": "workspace:.workspai/reports/INDEX.json" },
+        "workspaceContext": {
+          "const": "workspace:.workspai/reports/workspace-context-agent.json"
+        },
+        "workspaceModel": { "const": "workspace:.workspai/reports/workspace-model.json" },
+        "knowledgeGraph": {
+          "const": "workspace:.workspai/reports/workspace-knowledge-graph.json"
+        },
+        "modelFreshness": { "enum": ["fresh", "stale", "unknown", "missing"] },
+        "graphFreshness": { "enum": ["fresh", "stale", "unknown", "missing"] },
+        "graphMatchesModel": { "type": "boolean" },
+        "liveInputsValidated": { "type": "boolean" },
+        "blockerCount": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "activeGoal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["present", "appliesToProject", "status"],
+      "properties": {
+        "present": { "type": "boolean" },
+        "appliesToProject": { "type": "boolean" },
+        "status": { "enum": ["none", "ready", "stale", "invalid"] },
+        "id": { "type": "string", "minLength": 1 },
+        "objective": { "type": "string", "minLength": 1 },
+        "lifecycle": { "type": "string", "minLength": 1 },
+        "goalPack": { "$ref": "#/$defs/workspaceArtifact" },
+        "agentHandoff": { "$ref": "#/$defs/workspaceArtifact" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "status": { "const": "none" } } },
+          "then": { "properties": { "present": { "const": false } } }
+        },
+        {
+          "if": {
+            "properties": { "status": { "enum": ["ready", "stale", "invalid"] } }
+          },
+          "then": { "properties": { "present": { "const": true } } }
+        }
+      ]
+    },
+    "requiredReadOrder": {
+      "type": "array",
+      "minItems": 6,
+      "maxItems": 16,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "claims": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["architecture", "sourceInspection", "sourceMutation", "verification"],
+      "properties": {
+        "architecture": { "enum": ["allowed-with-citations", "prohibited"] },
+        "sourceInspection": { "const": "bounded-and-targeted" },
+        "sourceMutation": { "const": "governed-cli-transaction-only" },
+        "verification": { "const": "cli-evidence-only" }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "minItems": 6,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "message"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["passed", "warning", "failed"] },
+          "message": { "type": "string", "minLength": 1 },
+          "artifact": { "$ref": "#/$defs/portablePath" }
+        }
+      }
+    },
+    "nextActions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 8,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "algorithm",
+        "manifestHash",
+        "projectContextHash",
+        "payloadHash",
+        "portable",
+        "absolutePathsEmitted"
+      ],
+      "properties": {
+        "algorithm": { "const": "sha256" },
+        "manifestHash": { "$ref": "#/$defs/hash" },
+        "projectContextHash": { "$ref": "#/$defs/hash" },
+        "payloadHash": { "$ref": "#/$defs/hash" },
+        "portable": { "const": true },
+        "absolutePathsEmitted": { "const": false }
+      }
+    }
+  },
+  "$defs": {
+    "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "status": { "enum": ["ready", "degraded", "blocked"] },
+    "portablePath": {
+      "type": "string",
+      "minLength": 1,
+      "not": { "pattern": "^(?:/|[A-Za-z]:[\\\\/])" }
+    },
+    "workspaceArtifact": {
+      "type": "string",
+      "pattern": "^workspace:\\.workspai/"
+    }
+  }
+}

package/contracts/workspace-intelligence/agent-customization-pack-report.v1.json

@@ -27,7 +27,22 @@
     "targets": {
       "type": "array",
       "items": {
-        "enum": ["all", "vscode", "agents", "copilot", "cursor", "claude", "codex", "orca"]
+        "enum": [
+          "all",
+          "vscode",
+          "agents",
+          "copilot",
+          "cursor",
+          "claude",
+          "codex",
+          "gemini",
+          "qwen",
+          "kimi",
+          "grok",
+          "windsurf",
+          "amazon-q",
+          "orca"
+        ]
       }
     },
     "sourceReports": { "type": "array", "items": { "type": "string", "minLength": 1 } },

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
+}

package/contracts/workspace-intelligence/goal-index.v1.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/goal-index.v1.json",
+  "title": "Workspai Goal Index",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "activeGoalId", "goals"],
+  "properties": {
+    "schemaVersion": { "const": "workspai.goal-index.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "activeGoalId": { "type": ["string", "null"] },
+    "goals": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "fingerprint", "objective", "category", "state", "lifecycle", "scope", "createdAt", "updatedAt", "goalPack", "agentHandoff"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{7,95}$" },
+          "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "objective": { "type": "string", "minLength": 1, "maxLength": 2000 },
+          "category": { "enum": ["release-readiness", "dependency-security", "test-coverage", "defect-repair", "feature-change", "refactor", "performance", "documentation", "system-understanding"] },
+          "state": { "enum": ["ready-to-plan", "needs-confirmation", "needs-evidence", "blocked"] },
+          "lifecycle": { "enum": ["planned", "active", "cancelled", "verification-ready", "verified", "failed"] },
+          "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
+          },
+          "createdAt": { "type": "string", "format": "date-time" },
+          "updatedAt": { "type": "string", "format": "date-time" },
+          "goalPack": { "type": "string", "pattern": "^\\.workspai/goals/[^/]+/goal-pack\\.json$" },
+          "agentHandoff": { "type": "string", "pattern": "^\\.workspai/goals/[^/]+/agent-handoff\\.json$" },
+          "verifiedGoalId": { "type": "string", "minLength": 1 },
+          "repairTransactionId": { "type": "string", "minLength": 1 },
+          "repairTransactionIds": {
+            "type": "array",
+            "maxItems": 25,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/goal-lifecycle-result.v1.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/goal-lifecycle-result.v1.json",
+  "title": "Workspai Goal Lifecycle Result",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "operation",
+    "activeGoalId",
+    "goal",
+    "goals",
+    "goalPack",
+    "verifiedGoalId",
+    "verification"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspai.goal-lifecycle-result.v1" },
+    "operation": { "enum": ["status", "list", "activate", "cancel", "prepare", "verify"] },
+    "activeGoalId": { "type": ["string", "null"] },
+    "goal": { "anyOf": [{ "$ref": "#/$defs/goalEntry" }, { "type": "null" }] },
+    "goals": { "type": "array", "items": { "$ref": "#/$defs/goalEntry" } },
+    "goalPack": {
+      "anyOf": [
+        {
+          "type": "object",
+          "required": ["schemaVersion", "id", "fingerprint", "state"],
+          "properties": {
+            "schemaVersion": { "const": "workspai.goal-pack.v1" },
+            "id": { "type": "string" },
+            "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+            "state": { "enum": ["ready-to-plan", "needs-confirmation", "needs-evidence", "blocked"] }
+          }
+        },
+        { "type": "null" }
+      ]
+    },
+    "verifiedGoalId": { "type": ["string", "null"] },
+    "verification": { "type": ["object", "null"] }
+  },
+  "$defs": {
+    "goalEntry": {
+      "type": "object",
+      "required": [
+        "id",
+        "fingerprint",
+        "objective",
+        "category",
+        "state",
+        "lifecycle",
+        "scope",
+        "createdAt",
+        "updatedAt",
+        "goalPack",
+        "agentHandoff"
+      ],
+      "properties": {
+        "id": { "type": "string" },
+        "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "objective": { "type": "string", "minLength": 1 },
+        "category": {
+          "enum": [
+            "release-readiness",
+            "dependency-security",
+            "test-coverage",
+            "defect-repair",
+            "feature-change",
+            "refactor",
+            "performance",
+            "documentation",
+            "system-understanding"
+          ]
+        },
+        "state": { "enum": ["ready-to-plan", "needs-confirmation", "needs-evidence", "blocked"] },
+        "lifecycle": { "enum": ["planned", "active", "cancelled", "verification-ready", "verified", "failed"] },
+        "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
+        },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "goalPack": { "type": "string" },
+        "agentHandoff": { "type": "string" },
+        "verifiedGoalId": { "type": "string" },
+        "repairTransactionId": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}