workspai 0.57.0 → 0.58.0

package/README.md

@@ -162,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` |
@@ -212,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/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

@@ -430,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"
@@ -1530,6 +1606,7 @@
     "config",
     "create",
     "doctor",
+    "goal",
     "import",
     "infra",
     "mirror",

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

@@ -29,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

@@ -131,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/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,45 @@
+{
+  "$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 }
+        },
+        "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
+}