workspai 0.67.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/contracts/README.md

@@ -98,7 +98,7 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `workspace-model-cache.v1.json`, `workspace-watch-event.v1.json`, `doctor-project-scan.v2.json`, and `doctor-workspace-cache.v2.json` — cache/watch/diagnostic support contracts
 - `workspace-activity-event.v1.json` — local-first run/block/operation/touch stream consumed by `workspai live`; observational only, never Evidence/Decision authority
 - `workspace-activity-monitor-snapshot.v1.json` and `workspace-activity-monitor-fleet.v1.json` — deterministic local and bounded fleet projections
-- `workspace-activity-board.v1.json` — renderer-neutral bounded Live projection for terminal, SVG, IDE and web consumers
+- `workspace-activity-board.v1.json` — renderer-neutral bounded Live projection for terminal, SVG, IDE and web consumers, with optional provenance-backed references to canonical artifacts and revision-bound Graph evidence
 
 Workspace intelligence (`../../contracts/workspace-intelligence/`):
 

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/docs/workspace-knowledge-graph.md

@@ -82,6 +82,7 @@ A simplified response looks like this:
 ```json
 {
   "schemaVersion": "workspace-knowledge-search.v1",
+  "graphSourceHash": "<canonical-model-structural-sha256>",
   "query": "billing database",
   "projectId": "billing",
   "totalMatches": 23,

package/docs/workspace-live-activity.md

@@ -50,6 +50,19 @@ consumed by IDE, browser, dashboard and capture adapters. It contains bounded
 runs, nodes, edges, selection, counters and diagnostics; consumers must not
 infer verification success from activity state.
 
+Board runs and stages may also expose bounded `evidenceBindings`. Each binding
+declares a typed reference (`artifact`, `graph-entity`, `graph-relation`,
+`proof`, or `project`), its role, and authoritative/observed provenance. Graph
+identities can carry the exact `graphSourceHash` needed for revision-safe
+overlays. Artifact publications receive authoritative output bindings
+automatically. They are attributed to a stage only when the producer names the
+stage or exactly one non-root stage is active; concurrent/ambiguous execution
+never receives a guessed link.
+
+Bindings are navigation and correlation references, not verification claims.
+An IDE must resolve the artifact and validate its contract, integrity and
+freshness before presenting a verified outcome or drawing a Graph edge.
+
 `--capture` writes an atomic, deterministic SVG from the same Activity Board
 Model used by the terminal and exits. Captures are redacted by default: local
 scope, project, run and command-argument details are replaced while semantic
@@ -119,7 +132,7 @@ readers and captured output. `--classic` preserves the compatibility renderer.
 The implementation intentionally keeps this pipeline renderer-independent:
 
 ```text
-workspace-activity-event.v1
+workspace-activity-event.v1 (optional provenance-backed evidence bindings)
   -> deterministic monitor snapshot
   -> workspace-activity-board.v1 (runs, nodes, edges, selection, counters)
   -> terminal + deterministic SVG adapters today / web and IDE adapters later
@@ -166,9 +179,10 @@ contracts/workspace-activity-board.v1.json
 ```
 
 The stream contains run, block, attempt, origin, declared-edge, operation,
-touch, artifact and warning data. Blueprint edges are explicit `sequence`, `parallel`, `gate` or
-`handoff` relations; older journals without declared edges receive a
-deterministic sequential projection for compatibility.
+touch, artifact, evidence-binding and warning data. Blueprint edges are
+explicit `sequence`, `parallel`, `gate` or `handoff` relations; older journals
+without declared edges or evidence bindings receive a deterministic compatible
+projection without fabricated links.
 Stable semantic block IDs describe architecture stages rather than source line
 numbers or function names.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspai",
-  "version": "0.67.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-IC2KRVCG.js

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

package/dist/autopilot-release-RECEZAZI.js

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

package/dist/capabilities-command-X4WZIJNR.js

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

package/dist/chunk-2M62CU3O.js

@@ -1,2 +0,0 @@
-import {l}from'./chunk-GIQ4SDRJ.js';import {b}from'./chunk-FPDH3N3A.js';import {a as a$1}from'./chunk-ENZPM52J.js';import {j as j$1}from'./chunk-TP7VKEUF.js';import {b as b$1}from'./chunk-IKUFNK46.js';import {a}from'./chunk-AFIFZTOY.js';import {c}from'./chunk-EWZZUQBR.js';import {h,i,e}from'./chunk-ZGHJIQXL.js';import Ae from'crypto';import H from'fs';import O from'fs/promises';import m from'path';var pe=h.projectAgentEntry.schemaVersion,M=i.projectAgentEntry,Ee="workspai.agent-bootstrap-receipt.v1",We="<!-- WORKSPAI:AGENT-ENTRY:START -->",Fe="<!-- WORKSPAI:AGENT-ENTRY:END -->",q=["generic","codex","claude","gemini","qwen","kimi","grok","copilot","cursor","windsurf","amazon-q"],qe=["CLAUDE.md","GEMINI.md","QWEN.md",".amazonq/rules/workspai-agent-entry.md"];function ve(t){let s=t?.trim().toLowerCase()||"generic";if(s==="orca")return "grok";if(q.includes(s))return s;throw new Error(`Unsupported agent host "${s}". Expected one of: ${q.join(", ")}.`)}function le(t){let s=t.map(i=>i.id).sort(),n=[...q].sort();if(s.length!==n.length||s.some((i,c)=>i!==n[c]))throw new Error("Project agent entry must define each supported host exactly once.")}function V(t){let{integrity:s,...n}=t;return n}function S(t){return c(t)}function Ve(t){le(t.hosts);let s={schemaVersion:pe,generatedAt:t.context.generatedAt,project:{name:t.context.project.name,relativePath:t.context.project.relativePath,...t.context.project.runtime?{runtime:t.context.project.runtime}:{},...t.context.project.framework?{framework:t.context.project.framework}:{}},workspace:{name:t.context.workspace.name,relationship:t.context.workspace.relationship,localBinding:i.projectWorkspaceLink,identityIsFilesystemPath:false,resolverCommand:"workspai project workspace status --json",portableUriScheme:"workspace:",resolvedPathPolicy:"runtime-private-never-persist"},canonical:{projectContext:i.projectContextAgent,projectGrounding:".workspai/PROJECT-GROUNDING.md",projectKnowledgeGraph:i.projectKnowledgeGraphReference,goalIndex:`workspace:${i.goalIndex}`,workspaceIndex:`workspace:${e.agentIndex}`,workspaceContext:`workspace:${e.agentContext}`,workspaceModel:`workspace:${e.model}`,knowledgeGraph:`workspace:${e.knowledgeGraph}`,workspaceSkillsIndex:`workspace:${e.skillsIndex}`,boundedGraphSearch:"command:workspai workspace graph search <task-query> --scope project:<project> --limit 12 --json"},protocol:{mode:"canonical-first",bootstrapCommand:"workspai agent bootstrap --for-agent generic --strict --json",verifyCommand:"workspai project agent-entry verify --for-agent all --strict --json",requiredReadOrder:[M,"command:workspai agent bootstrap --for-agent generic --strict --json","command:workspai project workspace status --json",i.projectContextAgent,`workspace:${i.goalIndex}`,`workspace:${e.skillsIndex}`,"command:workspai workspace graph search <task-query> --scope project:<project> --limit 12 --json","source:targeted-live-files"],sourcePolicy:{liveSourceAuthority:"exact-implementation",workspaceEvidenceAuthority:"identity-topology-readiness-goals",broadScanBeforeBootstrap:false,sourceMutation:"governed-only",verificationClaims:"cli-evidence-only"},degradedMode:{discloseMissingEvidence:true,allowCompleteArchitectureClaims:false,allowReadOnlySourceInspection:true}},hosts:[...t.hosts].sort((i,c)=>i.id.localeCompare(c.id))},n={...s,integrity:{algorithm:"sha256",projectContextHash:t.context.integrity.payloadHash,payloadHash:S(s),portable:true,absolutePathsEmitted:false}};if(!j(n))throw new Error("Project agent entry rejected a non-portable local path.");return a(n,"contracts/workspace-intelligence/project-agent-entry.v1.json","Project agent entry"),n}function j(t){return typeof t=="string"?!(/^[A-Za-z]:[\\/]/.test(t)||/(?:^|[\s("'`])[A-Za-z]:[\\/]/.test(t)||/(?:^|[\s("'`])file:\/\//i.test(t)||/(?:^|[\s("'`])\\\\[^\\\s]+[\\]/.test(t)||/(?:^|[\s("'`])\/(?:Users|home|private|var|opt|srv|mnt|Volumes|tmp)\//.test(t)):Array.isArray(t)?t.every(j):t&&typeof t=="object"?Object.values(t).every(j):true}async function Pe(t){let s=m.join(t,M),n=JSON.parse(await O.readFile(s,"utf8"));if(a(n,"contracts/workspace-intelligence/project-agent-entry.v1.json","Project agent entry"),n.integrity.payloadHash!==S(V(n)))throw new Error("Project agent entry integrity validation failed.");if(le(n.hosts),!j(n)||n.integrity.absolutePathsEmitted)throw new Error("Project agent entry contains a non-portable local path.");return n}async function Ce(t){let s=m.join(t,i.projectContextAgent),n=JSON.parse(await O.readFile(s,"utf8"));a(n,"contracts/workspace-intelligence/project-context-agent.v1.json","Project context agent");let i$1=V(n),c=Ae.createHash("sha256").update(JSON.stringify(i$1)).digest("hex");if(n.integrity.payloadHash!==c)throw new Error("Project context agent integrity validation failed.");if(!j(n)||n.integrity.absolutePathsEmitted)throw new Error("Project context agent contains a non-portable local path.");return n}function Te(t){return t.includes("blocked")?"blocked":t.includes("degraded")?"degraded":"ready"}async function Be(t){let s=b({startPath:m.resolve(t.startPath??process.cwd()),strict:true,requireProjectMembership:true});if(!s?.projectPath)throw new Error("No canonically bound Workspai project was resolved.");let n=s.projectPath,i$1=s.workspacePath,c$1=await Pe(n),o=await Ce(n);if(c$1.integrity.projectContextHash!==o.integrity.payloadHash||c$1.project.name!==o.project.name||c$1.workspace.name!==o.workspace.name)throw new Error("Project agent entry is not bound to the current project context.");let B=t.forAgent?.trim().toLowerCase()||"generic",U=B==="all",g=U?"all":ve(B),J=g,u=U?c$1.hosts:c$1.hosts.filter(e=>e.id===g),Y=c$1.hosts.find(e=>e.id==="generic");if(u.length===0&&Y&&u.push(Y),u.length===0)throw new Error("Project agent entry does not define generic host coverage.");let A=[],l$1=(e,r,C,h)=>A.push({id:e,status:r,message:C,...h?{artifact:h}:{}});l$1("workspace-binding","passed","Canonical workspace membership is resolved."),l$1("entry-integrity","passed","Project entry manifest integrity is valid.",M),l$1("project-context-integrity","passed","Project context integrity and manifest binding are valid.",i.projectContextAgent);let L=[...new Set(u.flatMap(e=>e.entryFiles))].sort(),de=L.filter(e=>!H.existsSync(m.join(n,e))),w=u.some(e=>e.status==="blocked")||de.length>0?"blocked":u.some(e=>e.status==="degraded")?"degraded":"ready";l$1("host-discovery",w==="ready"?"passed":w==="degraded"?"warning":"failed",w==="ready"?`${g} has discoverable Workspai entry coverage.`:w==="degraded"?u.find(e=>e.reason)?.reason??`${g} entry coverage is degraded.`:`${g} entry coverage is missing required files.`,L[0]);let D=[e.agentIndex,e.agentContext,e.skillsIndex,e.model,e.knowledgeGraph],R=D.filter(e=>!H.existsSync(m.join(i$1,e)));l$1("canonical-evidence",R.length===0?"passed":"failed",R.length===0?"Required canonical workspace evidence is present.":`Required canonical evidence is missing: ${R.join(", ")}.`);let E=[],x=null,y=null;for(let e$1 of D)if(!R.includes(e$1))try{let r=JSON.parse(await O.readFile(m.join(i$1,e$1),"utf8"));b$1(e$1,r,e$1),e$1===e.model&&(x=r),e$1===e.knowledgeGraph&&(y=r);}catch{E.push(e$1);}l$1("canonical-contracts",E.length===0?"passed":"failed",E.length===0?"Canonical workspace evidence satisfies its published schemas.":`Canonical evidence failed contract validation: ${E.join(", ")}.`);let I=i.projectKnowledgeGraphReference,z=m.join(n,I),Z="failed",b$2="The project Knowledge Graph reference is missing.";if(H.existsSync(z)&&y)try{let e=JSON.parse(await O.readFile(z,"utf8"));b$1(I,e,I);let r=j$1(y,o.project.name),{integrity:C,...h}=e,f=y.source;e.project.name===o.project.name&&e.canonical.sourceHash===f?.hash&&e.canonical.projectionHash===c(r)&&e.integrity.payloadHash===c(h)?(Z="passed",b$2="The project reference integrity-binds the exact current projection of canonical workspace evidence."):b$2="The project Knowledge Graph reference is stale or does not match the canonical project projection.";}catch{b$2="The project Knowledge Graph reference failed schema or integrity validation.";}l$1("project-knowledge-graph",Z,b$2,I);let ge=x?.workspace,he=y?.workspace,fe=Array.isArray(y?.entities)?y.entities:[],me=Array.isArray(x?.projects)?x.projects:[],Q=E.length===0&&ge?.name===o.workspace.name&&he?.name===o.workspace.name&&me.some(e=>e.name===o.project.name)&&fe.some(e=>e.projectId===o.project.name);l$1("canonical-project-membership",Q?"passed":"failed",Q?"The project and workspace identities agree across the entry, Model, and Graph.":"The project or workspace identity is missing or inconsistent in canonical evidence.");let X=!o.intelligence.freshness.graphMatchesModel||["missing","stale"].includes(o.intelligence.freshness.model)||["missing","stale"].includes(o.intelligence.freshness.graph)?"failed":o.intelligence.freshness.model==="unknown"||o.intelligence.freshness.graph==="unknown"?"warning":"passed",k=false,G;if(t.validateLiveInputs!==false)try{let e=await a$1(i$1);k=e.status==="hit";let r=e.status==="hit"?"Live project inputs match the persisted Model and Knowledge Graph snapshot.":`Live project inputs require an intelligence refresh (${e.reason}).`;G={id:"live-inputs",status:k?"passed":"failed",message:r};}catch{G={id:"live-inputs",status:"failed",message:"Live project inputs could not be validated against canonical graph evidence."};}else G={id:"live-inputs",status:"warning",message:"Live input validation was skipped; persisted compatibility was checked only."};let K=X==="warning"&&o.intelligence.freshness.model==="unknown"&&o.intelligence.freshness.graph==="fresh"&&o.intelligence.freshness.graphMatchesModel&&k?"passed":X;l$1("persisted-freshness",K,K==="passed"?o.intelligence.freshness.model==="unknown"?"Model and Graph bindings are current; live input validation closes structural freshness while verify-before-use facts remain individually governed.":"Persisted Model and Knowledge Graph bindings are current.":K==="warning"?"Persisted evidence is compatible, but at least one freshness state is unknown.":"Persisted Model or Knowledge Graph evidence is missing, stale, or mismatched."),A.push(G);let d={present:false,appliesToProject:false,status:"none"},_=[],ue=m.join(i$1,i.goalIndex);if(H.existsSync(ue)){let e=null;try{e=await l({workspacePath:i$1,validateBindings:false});}catch{_.push("workspai goal --list --json"),l$1("active-goal","failed","The Goal index is present but invalid.");}if(e?.active&&(d={present:true,appliesToProject:e.active.scope.projects.includes(o.project.name),status:"invalid",id:e.active.id,objective:e.active.objective,lifecycle:e.active.lifecycle,goalPack:`workspace:${e.active.goalPack}`,agentHandoff:`workspace:${e.active.agentHandoff}`}),e)try{let r=await l({workspacePath:i$1,validateBindings:true});r.active&&(d={present:true,appliesToProject:r.active.scope.projects.includes(o.project.name),status:"ready",id:r.active.id,objective:r.active.objective,lifecycle:r.active.lifecycle,goalPack:`workspace:${r.active.goalPack}`,agentHandoff:`workspace:${r.active.agentHandoff}`}),l$1("active-goal","passed",r.active?"The active Goal Pack and agent handoff have valid canonical bindings.":"No active Goal Pack is selected.");}catch(r){let C=r instanceof Error?r.message:String(r),h=d.present&&/\bstale\b|--refresh/i.test(C);if(d.present&&(d.status=h?"stale":"invalid"),h&&d.objective){let f=e.active,re=f?.scope.kind==="project"&&f.scope.projects.length===1?`project:${f.scope.projects[0]}`:f?.scope.kind==="project-set"&&f.scope.projects.length>1?`projects:${f.scope.projects.join(",")}`:"workspace";_.push(`workspai goal ${JSON.stringify(d.objective)} --scope ${re} --for-agent generic --refresh --json`);}else _.push("workspai goal --status --json");l$1("active-goal","failed",h?"The selected Goal Pack is present but stale; regenerate it against current canonical evidence before acting.":d.present?"The selected Goal Pack is present but its canonical binding or handoff is invalid.":"The Goal index could not be validated.");}}else l$1("active-goal","passed","No Goal index is present for this workspace.");let ee=A.some(e=>e.status==="failed")?"blocked":A.some(e=>e.status==="warning")?"degraded":"ready",v=Te([w,ee]),P=o.blockers.some(e=>e.severity==="error")?"blocked":o.blockers.length>0?"degraded":"ready",ye=P==="blocked"?"blocked":P==="degraded"?"degraded":"not-verified",we=`command:workspai agent bootstrap --for-agent ${g} --strict --json`,ke=c$1.protocol.requiredReadOrder.map(e=>e==="command:workspai agent bootstrap --for-agent generic --strict --json"?we:e),te={schemaVersion:Ee,generatedAt:(t.now??new Date).toISOString(),status:v,statusScope:"agent-grounding",readiness:{agentGrounding:v,architectureEvidence:ee,projectEnvironment:P,release:ye},requestedAgent:J,resolvedHost:g,project:{name:o.project.name,relativePath:o.project.relativePath,...o.project.runtime?{runtime:o.project.runtime}:{},...o.project.framework?{framework:o.project.framework}:{}},workspace:{name:o.workspace.name,relationship:o.workspace.relationship,resolved:true,identityIsFilesystemPath:false,resolverCommand:"workspai project workspace status --json",portableUriScheme:"workspace:",resolvedPathPolicy:"runtime-private-never-persist"},entry:{artifact:M,schemaVersion:pe,hostStatus:w,entryFiles:L},canonicalEvidence:{projectContext:i.projectContextAgent,projectKnowledgeGraph:i.projectKnowledgeGraphReference,workspaceIndex:`workspace:${e.agentIndex}`,workspaceContext:`workspace:${e.agentContext}`,workspaceModel:`workspace:${e.model}`,knowledgeGraph:`workspace:${e.knowledgeGraph}`,workspaceSkillsIndex:`workspace:${e.skillsIndex}`,boundedGraphSearch:"command:workspai workspace graph search <task-query> --scope project:<project> --limit 12 --json",modelFreshness:k?"fresh":o.intelligence.freshness.model,graphFreshness:k?"fresh":o.intelligence.freshness.graph,graphMatchesModel:o.intelligence.freshness.graphMatchesModel,liveInputsValidated:k,blockerCount:o.blockers.length},activeGoal:d,requiredReadOrder:ke,claims:{architecture:v==="ready"?"allowed-with-citations":"prohibited",sourceInspection:"bounded-and-targeted",sourceMutation:"governed-cli-transaction-only",verification:"cli-evidence-only"},checks:A,nextActions:v==="ready"?[...d.present&&d.appliesToProject&&d.agentHandoff?[`read:${d.agentHandoff}`]:[],...P==="blocked"?["workspai doctor project --json","workspai workspace explain release-blocked --json"]:P==="degraded"?["workspai doctor project --json"]:[],`workspai workspace graph search <task-query> --scope project:${o.project.name} --limit 12 --json`,"inspect only the returned proof paths and target source files"]:[..._,"workspai workspace intelligence run --for-agent generic --strict --json",`workspai agent bootstrap --for-agent ${g} --strict --json`]},oe=S(V(c$1)),je=S({manifestHash:oe,projectContextHash:o.integrity.payloadHash,requestedAgent:J,status:v,generatedAt:te.generatedAt}),ne={...te,receiptId:je},$={...ne,integrity:{algorithm:"sha256",manifestHash:oe,projectContextHash:o.integrity.payloadHash,payloadHash:S(ne),portable:true,absolutePathsEmitted:false}};if(!j($))throw new Error("Agent bootstrap receipt rejected a non-portable local path.");return a($,"contracts/workspace-intelligence/agent-bootstrap-receipt.v1.json","Agent bootstrap receipt"),$}
-export{pe as a,M as b,Ee as c,We as d,Fe as e,q as f,qe as g,ve as h,Ve as i,Be as j};