workspai 0.68.0 → 0.69.0

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -67,24 +67,31 @@ is not the exact current canonical projection.
 
 ## Governance evidence loop
 
-| Command                              | Primary artifact                                            | Schema version                              | JSON Schema                                                             |
-| ------------------------------------ | ----------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
-| `doctor workspace`                   | `.workspai/reports/doctor-last-run.json`                    | `doctor-workspace-evidence-v1`              | `contracts/doctor-workspace-evidence.v1.json`                           |
-| `doctor project`                     | `.workspai/reports/doctor-project-last-run.json`            | `doctor-project-evidence-v1`                | `contracts/doctor-project-evidence.v1.json`                             |
-| `project coverage`                   | `.workspai/reports/project-test-coverage-last-run.json`     | `workspai.project-test-coverage.v1`         | `contracts/project-test-coverage.v1.json`                               |
-| `doctor * --plan`                    | `.workspai/reports/doctor-remediation-plan-last-run.json`   | `doctor-remediation-plan-v2`                | `contracts/doctor-remediation-plan.v2.json`                             |
-| `doctor * --fix/--apply`             | `.workspai/reports/doctor-fix-result-last-run.json`         | `rapidkit-doctor-fix-result-v1`             | `contracts/workspace-intelligence/doctor-fix-result.v1.json`            |
-| `workspace remediation-plan --write` | `.workspai/reports/artifact-remediation-plan-last-run.json` | `artifact-remediation-plan-v1`              | `contracts/artifact-remediation-plan.v1.json`                           |
-| `workspace repair *`                 | `.workspai/reports/workspace-repair-last-run.json`          | `workspai.workspace-repair-transaction.v1`  | `contracts/workspace-intelligence/workspace-repair-transaction.v1.json` |
-| `workspace repair capabilities`      | CLI capability output                                       | `workspai.workspace-repair-capabilities.v1` | `contracts/workspace-repair-capabilities.v1.json`                       |
-| `goal <intent>`                      | `.workspai/reports/goal-pack-last-run.json`                 | `workspai.goal-pack.v1`                     | `contracts/workspace-intelligence/goal-pack.v1.json`                    |
-| `goal <intent>` / lifecycle options  | `.workspai/goals/index.json`                                | `workspai.goal-index.v1`                    | `contracts/workspace-intelligence/goal-index.v1.json`                   |
-| `goal --status/--list/... --json`    | stdout                                                      | `workspai.goal-lifecycle-result.v1`         | `contracts/workspace-intelligence/goal-lifecycle-result.v1.json`        |
-| `analyze`                            | `.workspai/reports/analyze-last-run.json`                   | `rapidkit-analyze-v1`                       | `contracts/analyze-last-run.v1.json`                                    |
-| `readiness`                          | `.workspai/reports/release-readiness-last-run.json`         | `release-readiness-v1`                      | `contracts/release-readiness.v1.json`                                   |
-| `pipeline`                           | `.workspai/reports/pipeline-last-run.json`                  | `rapidkit-pipeline-v1`                      | `contracts/pipeline-last-run.v1.json`                                   |
-| `autopilot release`                  | `.workspai/reports/autopilot-release-last-run.json`         | `autopilot-release-v1`                      | `contracts/autopilot-release.v1.json`                                   |
-|                                      | `.workspai/reports/autopilot-release.json`                  | (alias, same payload)                       | `contracts/autopilot-release.v1.json`                                   |
+| Command                              | Primary artifact                                            | Schema version                                | JSON Schema                                                                         |
+| ------------------------------------ | ----------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `doctor workspace`                   | `.workspai/reports/doctor-last-run.json`                    | `doctor-workspace-evidence-v1`                | `contracts/doctor-workspace-evidence.v1.json`                                       |
+| `doctor project`                     | `.workspai/reports/doctor-project-last-run.json`            | `doctor-project-evidence-v1`                  | `contracts/doctor-project-evidence.v1.json`                                         |
+| `project coverage`                   | `.workspai/reports/project-test-coverage-last-run.json`     | `workspai.project-test-coverage.v1`           | `contracts/project-test-coverage.v1.json`                                           |
+| `doctor * --plan`                    | `.workspai/reports/doctor-remediation-plan-last-run.json`   | `doctor-remediation-plan-v2`                  | `contracts/doctor-remediation-plan.v2.json`                                         |
+| `doctor * --fix/--apply`             | `.workspai/reports/doctor-fix-result-last-run.json`         | `rapidkit-doctor-fix-result-v1`               | `contracts/workspace-intelligence/doctor-fix-result.v1.json`                        |
+| `workspace remediation-plan --write` | `.workspai/reports/artifact-remediation-plan-last-run.json` | `artifact-remediation-plan-v1`                | `contracts/artifact-remediation-plan.v1.json`                                       |
+| `workspace repair *`                 | `.workspai/reports/workspace-repair-last-run.json`          | `workspai.workspace-repair-transaction.v1`    | `contracts/workspace-intelligence/workspace-repair-transaction.v1.json`             |
+| `workspace repair capabilities`      | CLI capability output                                       | `workspai.workspace-repair-capabilities.v1`   | `contracts/workspace-repair-capabilities.v1.json`                                   |
+| `goal <intent>`                      | `.workspai/reports/goal-pack-last-run.json`                 | `workspai.goal-pack.v1`                       | `contracts/workspace-intelligence/goal-pack.v1.json`                                |
+| `goal <intent>` / lifecycle options  | `.workspai/goals/index.json`                                | `workspai.goal-index.v1`                      | `contracts/workspace-intelligence/goal-index.v1.json`                               |
+| `goal --status/--list/... --json`    | stdout                                                      | `workspai.goal-lifecycle-result.v1`           | `contracts/workspace-intelligence/goal-lifecycle-result.v1.json`                    |
+| `change begin`                       | `.workspai/changes/<change-id>/lease.json`                  | `workspai.architecture-change-lease.v1`       | `contracts/workspace-intelligence/architecture-change-lease.v1.json`                |
+| `change *`                           | `.workspai/decisions/<change-id>/transaction.json`          | `workspai.decision-transaction.v1`            | `contracts/workspace-intelligence/decision-transaction.v1.json`                     |
+| `change *`                           | `.workspai/decisions/<change-id>/checkpoint.json`           | `workspai.decision-checkpoint.v1`             | `contracts/workspace-intelligence/decision-checkpoint.v1.json`                      |
+| `change predict`                     | `.workspai/changes/<change-id>/predicted-overlay.json`      | `workspai.predicted-architecture-change.v1`   | `contracts/workspace-intelligence/predicted-architecture-change.v1.json`            |
+| `change verify`                      | `.workspai/changes/<change-id>/actual-overlay.json`         | `workspace-knowledge-graph-change-overlay.v1` | `contracts/workspace-intelligence/workspace-knowledge-graph-change-overlay.v1.json` |
+| `change verify`                      | `.workspai/changes/<change-id>/architecture-surprises.json` | `workspai.architecture-surprise-report.v1`    | `contracts/workspace-intelligence/architecture-surprise-report.v1.json`             |
+| `change *`                           | `.workspai/changes/<change-id>/capsule.json`                | `workspai.proof-carrying-change-capsule.v1`   | `contracts/workspace-intelligence/proof-carrying-change-capsule.v1.json`            |
+| `analyze`                            | `.workspai/reports/analyze-last-run.json`                   | `rapidkit-analyze-v1`                         | `contracts/analyze-last-run.v1.json`                                                |
+| `readiness`                          | `.workspai/reports/release-readiness-last-run.json`         | `release-readiness-v1`                        | `contracts/release-readiness.v1.json`                                               |
+| `pipeline`                           | `.workspai/reports/pipeline-last-run.json`                  | `rapidkit-pipeline-v1`                        | `contracts/pipeline-last-run.v1.json`                                               |
+| `autopilot release`                  | `.workspai/reports/autopilot-release-last-run.json`         | `autopilot-release-v1`                        | `contracts/autopilot-release.v1.json`                                               |
+|                                      | `.workspai/reports/autopilot-release.json`                  | (alias, same payload)                         | `contracts/autopilot-release.v1.json`                                               |
 
 Side/cache (not gates): `.workspai/reports/doctor-workspace-cache.json` (`doctor-workspace-cache-v2`).
 
@@ -96,6 +103,18 @@ authorize mutation or claim completion.
 The sibling `.workspai/goals/index.json` is the canonical active-goal discovery
 and lifecycle registry; consumers must not infer activity from directory order.
 
+Proof-Carrying Change uses the append-only JSONL event stream at
+`.workspai/decisions/<change-id>/events.jsonl` as authority. The transaction and
+checkpoint are replay-derived projections, while the capsule composes intent,
+baseline, typed effects, re-observed architecture, independent verification,
+and remaining uncertainty. The private
+`.workspai/changes/<change-id>/private/baseline-graph.json` materialization is a
+hash-bound local cache used to calculate the actual delta after the canonical
+Graph advances; it is non-authoritative and must not be treated as a portable
+consumer artifact. `change list --json` is the stable discovery surface for
+IDEs and automation, so consumers must not infer the active or latest change
+from directory order.
+
 Doctor Studio handoff:
 `doctor-remediation-plan-v2` (`contracts/doctor-remediation-plan.v2.json`) is emitted in JSON
 responses and persisted to `.workspai/reports/doctor-remediation-plan-last-run.json` by

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -34,6 +34,7 @@ These commands are implemented and orchestrated by Workspai CLI:
 - `commands`
 - `create`
 - `goal`
+- `change`
 - `agent`
 - `project`
 - `live`
@@ -53,6 +54,22 @@ These nested Commander commands are implemented and orchestrated by Workspai CLI
 - `config remove-api-key`
 - `config set-api-key`
 - `config show`
+- `change begin`
+- `change list`
+- `change predict`
+- `change authorize`
+- `change resume`
+- `change effect`
+- `change effect record`
+- `change verification`
+- `change verification record`
+- `change status`
+- `change explain`
+- `change verify`
+- `change abort`
+- `change capsule`
+- `change capsule validate`
+- `change capsule export`
 - `infra down`
 - `infra plan`
 - `infra status`

package/docs/contracts/PROOF_CARRYING_CHANGE_CONTRACT_PLAN.md

@@ -0,0 +1,65 @@
+# Proof-Carrying Change contracts
+
+Status: released v1 CLI and read-only MCP contracts; extension mutation adapter pending
+
+## Published contracts
+
+| Schema                                                 | Owner           | Purpose                                             |
+| ------------------------------------------------------ | --------------- | --------------------------------------------------- |
+| `workspai.decision-event.v1`                           | Decisions       | Digest-linked causal event.                         |
+| `workspai.decision-transaction.v1`                     | Decisions       | Replay-derived transaction projection.              |
+| `workspai.decision-checkpoint.v1`                      | Decisions       | Event-head and projection integrity checkpoint.     |
+| `workspai.architecture-change-lease.v1`                | PCC composition | Goal and architecture generation guard.             |
+| `workspai.predicted-architecture-change.v1`            | PCC composition | Explicit noncanonical expected delta.               |
+| `workspace-knowledge-graph-change-overlay.v1`          | Graph           | Actual base-to-head architecture delta.             |
+| `workspai.architecture-surprise-report.v1`             | PCC composition | Predicted-versus-observed comparison.               |
+| `workspai.proof-carrying-change-capsule.v1`            | PCC composition | Portable closure, assurance, and uncertainty index. |
+| `workspai.change-operation-result.v1`                  | PCC composition | Stable machine result shared by lifecycle commands. |
+| `workspai.proof-carrying-change-list.v1`               | PCC composition | Read-only discovery for IDE, CI, and automation.    |
+| `workspai.proof-carrying-change-capsule-validation.v1` | PCC composition | Explicit integrity validation verdict.              |
+| `workspai.proof-carrying-change-capsule-export.v1`     | PCC composition | Validated portable export receipt.                  |
+
+The schemas live in `contracts/workspace-intelligence/` and are advertised by
+the published contract catalog and runtime command surface.
+
+## Reuse map
+
+- `workspai.goal-pack.v1`: immutable intent, scope, and success criteria.
+- `workspai.goal-index.v1`: active Goal and bounded PCC transaction links.
+- `workspace-model.v1`: structural baseline and post-effect system identity.
+- `workspace-knowledge-graph.v1`: architecture facts and proofs.
+- `workspace-knowledge-graph-change-overlay.v1`: actual change semantics.
+- `workspace-verify.v1`: canonical workspace verification evidence.
+
+## Semantic validation beyond JSON Schema
+
+JSON shape is necessary but insufficient. The runtime additionally verifies:
+
+1. contiguous event sequence and one transaction ID;
+2. previous-event and event-content digests;
+3. legal state transitions;
+4. explicit effect-class authorization;
+5. unique effect receipt IDs and idempotency keys;
+6. exact effect-head binding for verification receipts;
+7. current Model/Graph target identity;
+8. successful receipt coverage for changed Graph proof artifacts;
+9. latest passing receipt for every immutable Goal criterion;
+10. capsule, lease, decision-head, baseline-cache, and referenced-artifact integrity.
+
+## Compatibility rules
+
+- v1 fields do not grant authority beyond their named owner.
+- Prediction remains ineligible as proof in every consumer.
+- A capsule is an index, not a duplicate Goal, Graph, ledger, or verifier.
+- Missing, stale, uncertain, failed, and unsupported are distinct outcomes.
+- Unknown event kinds or fields fail closed under v1 schemas.
+- Consumers must use command discovery and the published catalog rather than
+  guessing artifact paths.
+- Consumers must use `change list --json` rather than inferring recency or
+  lifecycle state from directory order.
+
+## Deferred contract
+
+`workspai.semantic-change-conflict.v1` remains deferred until proof-backed
+two-change overlap can distinguish `overlap`, `disjoint`, and `unknown` without
+inferring absence from incomplete Graph coverage.

package/docs/proof-carrying-change.implementation.v1.json

@@ -0,0 +1,118 @@
+{
+  "schemaVersion": "workspai.proof-carrying-change-implementation-plan.v1",
+  "status": "released",
+  "release": "0.69.0",
+  "runtimeImplemented": true,
+  "packageDecision": {
+    "newPackage": false,
+    "compositionOwner": "workspai-cli",
+    "transactionOwner": "extraction-safe Decisions kernel",
+    "graphOwner": "workspace-knowledge-graph",
+    "modelOwner": "workspace-model",
+    "intentOwner": "goal-pack",
+    "verificationOwner": "domain-verifier"
+  },
+  "publicCommands": [
+    "change begin",
+    "change list",
+    "change predict",
+    "change authorize",
+    "change resume",
+    "change effect record",
+    "change verification record",
+    "change status",
+    "change verify",
+    "change explain",
+    "change abort",
+    "change capsule validate",
+    "change capsule export"
+  ],
+  "reusedContracts": [
+    "workspai.goal-pack.v1",
+    "workspai.goal-index.v1",
+    "workspace-knowledge-graph-change-overlay.v1",
+    "workspace-impact.v1",
+    "workspace-explain.v1",
+    "workspace-verify.v1"
+  ],
+  "implementedContracts": [
+    "workspai.decision-event.v1",
+    "workspai.decision-transaction.v1",
+    "workspai.decision-checkpoint.v1",
+    "workspai.architecture-change-lease.v1",
+    "workspai.predicted-architecture-change.v1",
+    "workspai.architecture-surprise-report.v1",
+    "workspai.proof-carrying-change-capsule.v1",
+    "workspai.change-operation-result.v1",
+    "workspai.proof-carrying-change-list.v1",
+    "workspai.proof-carrying-change-capsule-validation.v1",
+    "workspai.proof-carrying-change-capsule-export.v1"
+  ],
+  "deferredContracts": ["workspai.semantic-change-conflict.v1"],
+  "consumerStatus": {
+    "cli": "complete",
+    "ciJsonGate": "complete",
+    "mcpReadTools": "complete",
+    "extensionReadProjection": "implemented-awaiting-pcc-cli-release",
+    "extensionStudioMutationAdapter": "deferred-until-pcc-cli-release"
+  },
+  "stages": [
+    {
+      "id": "PC0",
+      "name": "ownership-and-inventory",
+      "status": "complete",
+      "exit": "Maintainer approves ownership, reuse map, threat boundary and no-new-package decision."
+    },
+    {
+      "id": "PC1",
+      "name": "contract-lock",
+      "status": "complete",
+      "exit": "Schemas, types, validators, fixtures, artifacts and compatibility rules are locked."
+    },
+    {
+      "id": "PC2",
+      "name": "pure-lease-and-comparison-kernel",
+      "status": "complete",
+      "exit": "Generation guard, prediction comparison and capsule validation pass without CLI globals."
+    },
+    {
+      "id": "PC3",
+      "name": "explicit-prediction-mvp",
+      "status": "complete",
+      "exit": "Begin, predict, status, verify, explain and abort pass JSON and process integration tests."
+    },
+    {
+      "id": "PC4",
+      "name": "decisions-and-effect-integration",
+      "status": "complete",
+      "exit": "All effects and resume behavior use one Decisions transaction and ledger."
+    },
+    {
+      "id": "PC5",
+      "name": "semantic-concurrency",
+      "status": "deferred",
+      "exit": "Proof-backed overlap and honest unknown/disjoint semantics pass multi-change fixtures."
+    },
+    {
+      "id": "PC6",
+      "name": "consumer-integration",
+      "status": "in-progress",
+      "exit": "CLI, CI, MCP and extension consume one capsule contract without semantic forks."
+    },
+    {
+      "id": "PC7",
+      "name": "enterprise-hardening",
+      "status": "in-progress",
+      "exit": "Cross-platform, adversarial, crash, concurrency, scale, privacy and release gates pass."
+    }
+  ],
+  "prohibitedShortcuts": [
+    "new transaction or graph truth owner",
+    "automatic stale lease renewal",
+    "prediction as corroborating evidence",
+    "fidelity score as commit or release authority",
+    "history as causal ledger",
+    "automatic command execution from capability metadata",
+    "semantic disjointness inferred from missing graph coverage"
+  ]
+}

package/docs/proof-carrying-change.md

@@ -0,0 +1,202 @@
+# Proof-Carrying Change
+
+Status: released in Workspai CLI v0.69.0
+
+> Every change carries its intent, pinned architecture baseline, predicted
+> impact, authorized effects, actual architecture delta, independent
+> verification, and remaining uncertainty.
+
+Proof-Carrying Change (PCC) is a product composition, not a second Graph or
+transaction system. Goal Pack owns intent and acceptance criteria. The
+extraction-safe Decisions kernel owns lifecycle, causal ordering, authorization,
+effect receipts, verification receipts, resume, and the tamper-evident ledger.
+Model and Graph own architecture truth. Workspace Verify and domain verifiers
+own verdicts. The CLI composes references to those owners into one capsule.
+
+## Quickstart
+
+Start from a current adopted project or workspace:
+
+```bash
+# 1. Create an immutable Goal Pack.
+workspai goal "Improve retry behavior without breaking clients" --json
+
+# 2. Pin that Goal and the exact Model/Graph/input generation.
+workspai change begin --json
+
+# Discover resumable and sealed changes without scanning directories.
+workspai change list --json
+
+# 3. Optionally attach an explicit prediction. It is never proof.
+workspai change predict --change <change-id> --file prediction.json --json
+
+# 4. A human grants only the effect classes required by the change.
+workspai change authorize --change <change-id> \
+  --effects filesystem,command --granted-by maintainer --json
+
+# 5. An agent, extension, or CLI tool records every observed effect.
+workspai change effect record --change <change-id> \
+  --file effect-receipt.json --json
+
+# 6. Rebuild/re-observe architecture and run independent verification.
+workspai change verify --change <change-id> --strict --json
+
+# 7. Validate or export the sealed manifest.
+workspai change capsule validate --change <change-id> --json
+workspai change capsule export --change <change-id> \
+  --output .workspai/exports/<change-id>.json --json
+```
+
+For Goals with additional release, security, or coverage criteria, `change
+verify` first records canonical Workspace Verify and the actual Graph overlay.
+The owning domain/CI adapter can then admit an exact-generation receipt:
+
+```bash
+workspai change verification record --change <change-id> \
+  --file verification-receipt.json --json
+```
+
+If a transaction is blocked, it remains durable. A human may resume it into an
+explicit state; history is never erased:
+
+```bash
+workspai change resume --change <change-id> --to authorized \
+  --reason "Add receipts for observed generated files" --json
+```
+
+## Ownership and invariants
+
+| Concern                          | Owner                              | PCC behavior                                                                |
+| -------------------------------- | ---------------------------------- | --------------------------------------------------------------------------- |
+| Intent, scope, success criteria  | Goal Pack                          | References the immutable Goal and criterion IDs.                            |
+| State, ledger, effects, receipts | Decisions kernel                   | Uses one digest-linked event stream and derived projection.                 |
+| Architecture baseline and delta  | Model / Graph                      | Pins exact hashes and reuses `workspace-knowledge-graph-change-overlay.v1`. |
+| Verification                     | Workspace Verify / domain verifier | Admits only receipts bound to the current Model, Graph, and effect head.    |
+| Product view                     | CLI / IDE / CI                     | Consumes the same capsule without redefining truth.                         |
+
+The runtime enforces these rules:
+
+- prediction is `nonCanonical: true` and `proofEligible: false`;
+- authorization names allowed effect classes before receipts are admitted;
+- receipt idempotency keys cannot be reused;
+- verification binds the exact current Model, Graph, and effect-head digest;
+- observed changed artifacts must be covered by successful effect receipts;
+- a changed Graph with no effect receipt blocks verification;
+- every required Goal criterion needs a latest passing receipt before commit;
+- failed or uncertain effects block the transaction;
+- terminal transactions cannot accept later events;
+- optimistic compare-and-append prevents concurrent history forks;
+- capsule validation replays the event chain and checks local reference digests.
+
+## Architecture lease
+
+`change begin` requires a fresh Goal Pack and a current canonical Graph. It
+creates `workspai.architecture-change-lease.v1`, binding Goal ID, workspace,
+scope, structural Model hash, canonical Graph hash, live Graph input
+fingerprint, and a derived generation ID.
+
+Before prediction or authorization, the generation must still match. The lease
+is an optimistic guard, not a filesystem or Git lock.
+
+Because the canonical Graph path is renewed in place, begin also writes a
+private, non-authoritative, hash-bound baseline materialization. It exists only
+to derive the later base-to-head overlay. The capsule cites the canonical
+baseline identity, not the cache as architecture truth.
+
+## Typed receipts
+
+An effect receipt includes an ID, effect class, result, summary, observation
+time, idempotency key, optional command argv, and artifact references. Artifact
+references use labeled digest semantics:
+
+- `canonical-json-v1` for JSON evidence;
+- `raw-bytes-v1` for source or command-output files;
+- `workspace-model-structural-v1` for canonical Model identity.
+
+Verification receipts add a Goal criterion ID and an exact target. Domain
+receipts are admitted only after `change verify` has re-observed the Graph and
+recorded passing Workspace Verify evidence.
+
+## Artifact layout
+
+```text
+.workspai/decisions/<change-id>/
+  events.jsonl              # authoritative causal ledger
+  transaction.json          # replay-derived projection
+  checkpoint.json           # generation and head integrity checkpoint
+
+.workspai/changes/<change-id>/
+  lease.json
+  predicted-overlay.json    # optional, noncanonical
+  actual-overlay.json
+  architecture-surprises.json
+  capsule.json
+  private/baseline-graph.json
+```
+
+`capsule.json` is a portable hash-index and assurance summary. It does not copy
+the Goal, event ledger, Model, Graph, or verification reports. Absolute paths,
+secrets, prompts, and unbounded command output are not capsule content.
+Use the schema-validated `change list --json` projection for IDE and automation
+discovery; filesystem directory order is never lifecycle truth.
+
+Every CLI operation also emits a Live activity observation correlated by the
+change ID, and every PCC artifact write flows through the shared artifact
+publisher. Live remains execution telemetry rather than verification proof;
+the capsule references Decision, Graph, effect, and verifier evidence instead
+of upgrading an observed activity event into an assurance claim.
+
+Read-only MCP consumers receive the same ledger-derived projections through
+`listProofCarryingChanges`, `getProofCarryingChange`, and
+`validateProofCarryingChange`. No PCC mutation tool is exposed over MCP; effect
+authorization and execution remain behind explicit CLI or IDE approval
+boundaries.
+
+CI can fail closed on capsule integrity and assurance without parsing terminal
+text:
+
+```bash
+workspai change capsule validate --change "$CHANGE_ID" --json
+workspai change status --change "$CHANGE_ID" --json
+```
+
+An invalid capsule exits non-zero. Policy automation should additionally
+require `capsule.status == "sealed"` when a sealed change is a merge or release
+condition.
+
+## Decision states
+
+The Decisions owner derives these states from events:
+
+```text
+draft -> scoped -> evidence-ready -> authorized -> executing -> verifying
+                                  \-> blocked/awaiting-human -> resumed
+                                                    verifying -> committed
+any nonterminal state -> aborted/rejected/superseded
+```
+
+The product-facing capsule reports `open`, `blocked`, `verified`, `sealed`, or
+`aborted`. A sealed capsule means all immutable Goal criteria have passing
+post-effect receipts. It does not mean unsupported external claims became true.
+
+## Prediction versus observation
+
+The prediction lists expected add/remove/change operations for entities,
+relations, proofs, or artifacts. `change verify` derives the actual overlay from
+the pinned Graph and fresh canonical head, then emits matched operations,
+unpredicted actual operations, predicted operations not observed, and an honest
+`exact`, `within-expectation`, `surprising`, or `no-prediction` verdict.
+
+Surprise analysis is explanatory evidence. It is not self-corroborating proof
+and cannot replace verification.
+
+## Deferred work
+
+The next layer is IDE timeline/Graph overlay and Repair/Studio transaction
+adapters. Rich hosted PR annotations remain separate from the machine-readable
+CI gate above. Semantic multi-change overlap, immutable historical Graph
+queries, isolated patch simulation, and remote attestation remain separate
+follow-up capabilities. No current command claims those behaviors.
+
+See the [contract reference](./contracts/PROOF_CARRYING_CHANGE_CONTRACT_PLAN.md)
+and [implementation manifest](./proof-carrying-change.implementation.v1.json).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspai",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "type": "module",
   "description": "Open-source workspace intelligence CLI for software systems: create, adopt, govern, verify, and align polyglot workspaces for humans, CI, IDEs, and AI agents.",
   "keywords": [

package/dist/analyze-JDEWUBC6.js

@@ -1 +0,0 @@
-export{b as printAnalyzeReport,a as runAnalyze}from'./chunk-VIN7NJW3.js';

package/dist/autopilot-release-OELUFNLL.js

@@ -1 +0,0 @@
-export{b as AUTOPILOT_RELEASE_ALIAS_FILENAME,a as AUTOPILOT_RELEASE_LAST_RUN_FILENAME,c as runAutopilotRelease}from'./chunk-5YZ2W57R.js';

package/dist/capabilities-command-RAAYENQ6.js

@@ -1 +0,0 @@
-export{b as runDoctorCapabilities}from'./chunk-DFVG4DDZ.js';