workspai 0.68.0 → 0.69.0

package/README.md

@@ -177,6 +177,24 @@ a machine-readable decision and can use `--scope` and `--runtime`.
 
 [Learn how Goal Packs work](docs/goal-packs.md)
 
+## Make every agent change carry proof
+
+For source-changing work, begin a Goal-bound change before mutation:
+
+```bash
+npx workspai change begin --json
+npx workspai change list --json
+npx workspai change authorize --change <change-id> --effects filesystem,command --json
+# The agent or extension records typed effects, then Workspai re-observes the Graph.
+npx workspai change verify --change <change-id> --strict --json
+npx workspai change capsule validate --change <change-id> --json
+```
+
+The resulting capsule binds intent, baseline architecture, authorization,
+observed effects, predicted-versus-actual Graph changes, verification receipts,
+and remaining uncertainty. Prediction can guide work but can never prove its
+own result. [Learn how Proof-Carrying Change works](docs/proof-carrying-change.md).
+
 ## What happens after the first run
 
 Everything shown in the [output tree above](#what-the-output-looks-like) is
@@ -262,24 +280,25 @@ explicitly unproven.
 
 ## Everyday workflows
 
-| Goal                                       | Command                                                                          |
-| ------------------------------------------ | -------------------------------------------------------------------------------- |
-| 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%"`                                 |
-| Ground an agent before source discovery    | `npx workspai agent bootstrap --for-agent codex --strict --json`                 |
-| Audit every agent entry adapter            | `npx workspai project agent-entry verify --for-agent all --strict --json`        |
-| 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`                                                  |
-| 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`                              |
-| Refresh agent and IDE context              | `npx workspai workspace agent-sync --write --preset enterprise --json`           |
-| Start MCP server for workspace queries     | `npx workspai workspace mcp serve`                                               |
+| Goal                                        | Command                                                                          |
+| ------------------------------------------- | -------------------------------------------------------------------------------- |
+| 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%"`                                 |
+| Prove an agent change from intent to verify | `npx workspai change begin --json`                                               |
+| Ground an agent before source discovery     | `npx workspai agent bootstrap --for-agent codex --strict --json`                 |
+| Audit every agent entry adapter             | `npx workspai project agent-entry verify --for-agent all --strict --json`        |
+| 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`                                                  |
+| 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`                              |
+| Refresh agent and IDE context               | `npx workspai workspace agent-sync --write --preset enterprise --json`           |
+| Start MCP server for workspace queries      | `npx workspai workspace mcp serve`                                               |
 
 For every command and flag, use the
 [Command Reference](docs/commands-reference.md).
@@ -323,6 +342,7 @@ modules; Workspai remains the workspace-level CLI.
 | 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)                                                               |
+| Prove what an agent changed and why           | [Proof-Carrying Change](docs/proof-carrying-change.md)                                         |
 | Ground an agent in canonical project evidence | [Canonical-first agent entry](docs/agent-entry.md)                                             |
 | Integrate CI                                  | [CI workflows](docs/ci-workflows.md)                                                           |
 | Find generated files and schemas              | [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md)                                         |

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

@@ -282,6 +282,464 @@
       "arguments": [],
       "options": []
     },
+    {
+      "path": [
+        "change"
+      ],
+      "command": "change",
+      "parent": null,
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Create and verify tamper-evident, architecture-aware change capsules",
+      "hidden": false,
+      "arguments": [],
+      "options": []
+    },
+    {
+      "path": [
+        "change",
+        "abort"
+      ],
+      "command": "abort",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Terminate an open change without deleting evidence",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        },
+        {
+          "flags": "--reason <text>",
+          "attributeName": "reason"
+        },
+        {
+          "flags": "--actor <identity>",
+          "attributeName": "actor"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "authorize"
+      ],
+      "command": "authorize",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Grant bounded effect capabilities",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        },
+        {
+          "flags": "--effects <classes>",
+          "attributeName": "effects"
+        },
+        {
+          "flags": "--granted-by <identity>",
+          "attributeName": "grantedBy"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "begin"
+      ],
+      "command": "begin",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Pin an active Goal and architecture baseline",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--goal <goal-id>",
+          "attributeName": "goal"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "capsule"
+      ],
+      "command": "capsule",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Validate or export a change capsule",
+      "hidden": false,
+      "arguments": [],
+      "options": []
+    },
+    {
+      "path": [
+        "change",
+        "capsule",
+        "export"
+      ],
+      "command": "export",
+      "parent": "change capsule",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Export a validated portable capsule manifest",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        },
+        {
+          "flags": "--output <path>",
+          "attributeName": "output"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "capsule",
+        "validate"
+      ],
+      "command": "validate",
+      "parent": "change capsule",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Validate capsule and referenced local evidence",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "effect"
+      ],
+      "command": "effect",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Record typed observed effects",
+      "hidden": false,
+      "arguments": [],
+      "options": []
+    },
+    {
+      "path": [
+        "change",
+        "effect",
+        "record"
+      ],
+      "command": "record",
+      "parent": "change effect",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Append an idempotent effect receipt",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        },
+        {
+          "flags": "--file <receipt.json>",
+          "attributeName": "file"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "explain"
+      ],
+      "command": "explain",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Explain proof, uncertainty, and next actions",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "list"
+      ],
+      "command": "list",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "List discoverable change capsules and integrity",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "predict"
+      ],
+      "command": "predict",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Attach a noncanonical architecture prediction",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        },
+        {
+          "flags": "--file <prediction.json>",
+          "attributeName": "file"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "resume"
+      ],
+      "command": "resume",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Resume a blocked transaction with human intent",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        },
+        {
+          "flags": "--to <state>",
+          "attributeName": "to"
+        },
+        {
+          "flags": "--reason <text>",
+          "attributeName": "reason"
+        },
+        {
+          "flags": "--actor <identity>",
+          "attributeName": "actor"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "status"
+      ],
+      "command": "status",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Inspect the derived transaction and assurance state",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "verification"
+      ],
+      "command": "verification",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Record independent Goal-criterion verification",
+      "hidden": false,
+      "arguments": [],
+      "options": []
+    },
+    {
+      "path": [
+        "change",
+        "verification",
+        "record"
+      ],
+      "command": "record",
+      "parent": "change verification",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Append an exact-generation verification receipt",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        },
+        {
+          "flags": "--file <receipt.json>",
+          "attributeName": "file"
+        }
+      ]
+    },
+    {
+      "path": [
+        "change",
+        "verify"
+      ],
+      "command": "verify",
+      "parent": "change",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Re-observe architecture and verify exact effects",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        },
+        {
+          "flags": "--change <change-id>",
+          "attributeName": "change"
+        },
+        {
+          "flags": "--strict",
+          "attributeName": "strict"
+        },
+        {
+          "flags": "--no-refresh",
+          "attributeName": "refresh"
+        }
+      ]
+    },
     {
       "path": [
         "commands"
@@ -1816,6 +2274,7 @@
     "autopilot",
     "bootstrap",
     "cache",
+    "change",
     "commands",
     "config",
     "create",

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

@@ -37,6 +37,17 @@
     "goalPlanResult": "workspai.goal-plan-result.v1",
     "goalIndex": "workspai.goal-index.v1",
     "goalLifecycleResult": "workspai.goal-lifecycle-result.v1",
+    "decisionEvent": "workspai.decision-event.v1",
+    "decisionTransaction": "workspai.decision-transaction.v1",
+    "decisionCheckpoint": "workspai.decision-checkpoint.v1",
+    "changeOperationResult": "workspai.change-operation-result.v1",
+    "architectureChangeLease": "workspai.architecture-change-lease.v1",
+    "predictedArchitectureChange": "workspai.predicted-architecture-change.v1",
+    "architectureSurpriseReport": "workspai.architecture-surprise-report.v1",
+    "proofCarryingChangeCapsule": "workspai.proof-carrying-change-capsule.v1",
+    "proofCarryingChangeList": "workspai.proof-carrying-change-list.v1",
+    "proofCarryingChangeCapsuleValidation": "workspai.proof-carrying-change-capsule-validation.v1",
+    "proofCarryingChangeCapsuleExport": "workspai.proof-carrying-change-capsule-export.v1",
     "workspaceIntelligenceArchitecture": "workspai-workspace-intelligence-architecture-v1",
     "workspaceIntelligenceChain": "workspai-workspace-intelligence-chain-v1",
     "workspaceIntelligenceArtifacts": {

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

@@ -171,6 +171,61 @@
       "contractPath": "contracts/workspace-intelligence/goal-lifecycle-result.v1.json",
       "publication": "json-schema"
     },
+    "decisionEvent": {
+      "schemaVersion": "workspai.decision-event.v1",
+      "contractPath": "contracts/workspace-intelligence/decision-event.v1.json",
+      "publication": "json-schema"
+    },
+    "decisionTransaction": {
+      "schemaVersion": "workspai.decision-transaction.v1",
+      "contractPath": "contracts/workspace-intelligence/decision-transaction.v1.json",
+      "publication": "json-schema"
+    },
+    "decisionCheckpoint": {
+      "schemaVersion": "workspai.decision-checkpoint.v1",
+      "contractPath": "contracts/workspace-intelligence/decision-checkpoint.v1.json",
+      "publication": "json-schema"
+    },
+    "changeOperationResult": {
+      "schemaVersion": "workspai.change-operation-result.v1",
+      "contractPath": "contracts/workspace-intelligence/change-operation-result.v1.json",
+      "publication": "json-schema"
+    },
+    "architectureChangeLease": {
+      "schemaVersion": "workspai.architecture-change-lease.v1",
+      "contractPath": "contracts/workspace-intelligence/architecture-change-lease.v1.json",
+      "publication": "json-schema"
+    },
+    "predictedArchitectureChange": {
+      "schemaVersion": "workspai.predicted-architecture-change.v1",
+      "contractPath": "contracts/workspace-intelligence/predicted-architecture-change.v1.json",
+      "publication": "json-schema"
+    },
+    "architectureSurpriseReport": {
+      "schemaVersion": "workspai.architecture-surprise-report.v1",
+      "contractPath": "contracts/workspace-intelligence/architecture-surprise-report.v1.json",
+      "publication": "json-schema"
+    },
+    "proofCarryingChangeCapsule": {
+      "schemaVersion": "workspai.proof-carrying-change-capsule.v1",
+      "contractPath": "contracts/workspace-intelligence/proof-carrying-change-capsule.v1.json",
+      "publication": "json-schema"
+    },
+    "proofCarryingChangeList": {
+      "schemaVersion": "workspai.proof-carrying-change-list.v1",
+      "contractPath": "contracts/workspace-intelligence/proof-carrying-change-list.v1.json",
+      "publication": "json-schema"
+    },
+    "proofCarryingChangeCapsuleValidation": {
+      "schemaVersion": "workspai.proof-carrying-change-capsule-validation.v1",
+      "contractPath": "contracts/workspace-intelligence/proof-carrying-change-capsule-validation.v1.json",
+      "publication": "json-schema"
+    },
+    "proofCarryingChangeCapsuleExport": {
+      "schemaVersion": "workspai.proof-carrying-change-capsule-export.v1",
+      "contractPath": "contracts/workspace-intelligence/proof-carrying-change-capsule-export.v1.json",
+      "publication": "json-schema"
+    },
     "workspaceIntelligenceArchitecture": {
       "schemaVersion": "workspai-workspace-intelligence-architecture-v1",
       "contractPath": "contracts/workspace-intelligence-architecture.v1.json",