workspai 0.68.0 → 0.70.0

package/dist/{workspace-watch-XYJEW2Z2.js → workspace-watch-Z32443UP.js}

@@ -1 +1 @@
-import {a}from'./chunk-OFYY4725.js';import {d,s,m as m$1}from'./chunk-2KX6KHEC.js';import {a as a$1}from'./chunk-GR6442P7.js';import {a as a$2}from'./chunk-AFIFZTOY.js';import y from'fs';var b="workspace-watch-event.v1";function R(e){return a$2(e,"contracts/workspace-watch-event.v1.json","Workspace watch event"),e}function g(e){return `${e.from}\0${e.to}\0${e.kind}`}function f(e){return (m$1(e)?.edges??[]).map(o=>({from:o.from,to:o.to,kind:o.kind}))}function m(e){let r=[...a(e).entries()].sort((a,n)=>a[0].localeCompare(n[0])).map(([a,n])=>({id:a,hash:n})),c=f(e).map(g).sort((a,n)=>a.localeCompare(n));return d({projects:r,edges:c})}function C(e,o){let r=a(o),c=e?a(e):new Map,a$1=[],n=[];for(let[t,s]of r.entries())c.has(t)?c.get(t)!==s&&a$1.push(t):n.push(t);let d=[];for(let t of c.keys())r.has(t)||d.push(t);let i=new Map(e?f(e).map(t=>[g(t),t]):[]),l=new Map(f(o).map(t=>[g(t),t])),p=[];for(let[t,s]of l.entries())i.has(t)||p.push(s);let h=[];for(let[t,s]of i.entries())l.has(t)||h.push(s);let u=(t,s)=>g(t).localeCompare(g(s));return a$1.sort((t,s)=>t.localeCompare(s)),n.sort((t,s)=>t.localeCompare(s)),d.sort((t,s)=>t.localeCompare(s)),p.sort(u),h.sort(u),{changedProjects:a$1,addedProjects:n,removedProjects:d,edgesAdded:p,edgesRemoved:h}}var k=class{model=null;sequence=0;rebuild;now;constructor(o,r){this.rebuild=r?.rebuild??(()=>s({...o})),this.now=r?.now??(()=>new Date);}get currentModel(){return this.model}async start(){let o=Date.now(),{model:r}=await this.rebuild();return this.model=r,this.buildEvent("ready","initial",null,r,Date.now()-o)}async pulse(){let o=Date.now(),r=this.model,{model:c,mode:a}=await this.rebuild(),n=this.buildEvent(this.hasStructuralChange(r,c)?"changed":"unchanged",a,r,c,Date.now()-o);return this.model=c,n}hasStructuralChange(o,r){return o?m(o)!==m(r):true}buildEvent(o,r,c,a,n){let d=C(c,a),i=m(a),l=c?m(c)!==i:true;return R({schemaVersion:b,kind:o,sequence:this.sequence++,timestamp:this.now().toISOString(),mode:r,modelHash:i,modelHashChanged:l,changedProjects:d.changedProjects,addedProjects:d.addedProjects,removedProjects:d.removedProjects,graph:{nodeCount:a.graph?.nodes.length??0,edgeCount:a.graph?.edges.length??0,edgesAdded:d.edgesAdded,edgesRemoved:d.edgesRemoved},durationMs:n})}},S=new Set([".git",".hg",".svn","node_modules",".venv","venv","dist","build","out","target","coverage","htmlcov",".next",".turbo",".cache"]),j=new Set(["reports","cache","tmp",".cache"]);function O(e){if(!e)return  false;let o=e.split(/[\\/]/).filter(Boolean);if(o.some(r=>S.has(r)||a$1(r)))return  false;for(let r=0;r<o.length-1;r+=1)if((o[r]===".workspai"||o[r]===".rapidkit")&&j.has(o[r+1]))return  false;return  true}async function N(e){let o=new k(e.buildOptions,e.engineOptions),r=await o.start();if(e.emit(r),o.currentModel&&await e.onModel?.(o.currentModel,r),e.once)return;let c=e.debounceMs??250,a=e.selfWriteSuppressionMs??Math.max(400,c+150),n=null,d=false,i=false,l=0,p=async()=>{if(d){i=true;return}d=true;try{let t=await o.pulse();e.emit(t),o.currentModel&&await e.onModel?.(o.currentModel,t);}catch(t){e.emit(R({schemaVersion:b,kind:"error",sequence:-1,timestamp:new Date().toISOString(),mode:"full",modelHash:o.currentModel?m(o.currentModel):"",modelHashChanged:false,changedProjects:[],addedProjects:[],removedProjects:[],graph:{nodeCount:0,edgeCount:0,edgesAdded:[],edgesRemoved:[]},durationMs:0,error:t instanceof Error?t.message:String(t)}));}finally{d=false,l=Date.now()+a,i&&(i=false,p());}},h=t=>{O(t)&&(d||Date.now()<l||(n&&clearTimeout(n),n=setTimeout(()=>{n=null,p();},c)));};e.onProgress?.(`Watching ${e.workspacePath} for changes (Ctrl+C to stop).`);let u=y.watch(e.workspacePath,{recursive:true},(t,s)=>{typeof s=="string"?h(s):s&&h(Buffer.from(s).toString("utf8"));});await new Promise(t=>{let s=()=>{n&&clearTimeout(n),u.close(),t();};if(e.signal){if(e.signal.aborted){s();return}e.signal.addEventListener("abort",s,{once:true});}u.on("error",()=>s());});}export{b as WORKSPACE_WATCH_EVENT_SCHEMA_VERSION,k as WorkspaceWatchEngine,m as computeWatchModelHash,C as diffWatchModels,O as isWatchRelevantPath,N as runWorkspaceWatch};
+import {a}from'./chunk-Z7JIUA6I.js';import {d,s,m as m$1}from'./chunk-IHKG5C6G.js';import {a as a$1}from'./chunk-GR6442P7.js';import {a as a$2}from'./chunk-AFIFZTOY.js';import y from'fs';var b="workspace-watch-event.v1";function R(e){return a$2(e,"contracts/workspace-watch-event.v1.json","Workspace watch event"),e}function g(e){return `${e.from}\0${e.to}\0${e.kind}`}function f(e){return (m$1(e)?.edges??[]).map(o=>({from:o.from,to:o.to,kind:o.kind}))}function m(e){let r=[...a(e).entries()].sort((a,n)=>a[0].localeCompare(n[0])).map(([a,n])=>({id:a,hash:n})),c=f(e).map(g).sort((a,n)=>a.localeCompare(n));return d({projects:r,edges:c})}function C(e,o){let r=a(o),c=e?a(e):new Map,a$1=[],n=[];for(let[t,s]of r.entries())c.has(t)?c.get(t)!==s&&a$1.push(t):n.push(t);let d=[];for(let t of c.keys())r.has(t)||d.push(t);let i=new Map(e?f(e).map(t=>[g(t),t]):[]),l=new Map(f(o).map(t=>[g(t),t])),p=[];for(let[t,s]of l.entries())i.has(t)||p.push(s);let h=[];for(let[t,s]of i.entries())l.has(t)||h.push(s);let u=(t,s)=>g(t).localeCompare(g(s));return a$1.sort((t,s)=>t.localeCompare(s)),n.sort((t,s)=>t.localeCompare(s)),d.sort((t,s)=>t.localeCompare(s)),p.sort(u),h.sort(u),{changedProjects:a$1,addedProjects:n,removedProjects:d,edgesAdded:p,edgesRemoved:h}}var k=class{model=null;sequence=0;rebuild;now;constructor(o,r){this.rebuild=r?.rebuild??(()=>s({...o})),this.now=r?.now??(()=>new Date);}get currentModel(){return this.model}async start(){let o=Date.now(),{model:r}=await this.rebuild();return this.model=r,this.buildEvent("ready","initial",null,r,Date.now()-o)}async pulse(){let o=Date.now(),r=this.model,{model:c,mode:a}=await this.rebuild(),n=this.buildEvent(this.hasStructuralChange(r,c)?"changed":"unchanged",a,r,c,Date.now()-o);return this.model=c,n}hasStructuralChange(o,r){return o?m(o)!==m(r):true}buildEvent(o,r,c,a,n){let d=C(c,a),i=m(a),l=c?m(c)!==i:true;return R({schemaVersion:b,kind:o,sequence:this.sequence++,timestamp:this.now().toISOString(),mode:r,modelHash:i,modelHashChanged:l,changedProjects:d.changedProjects,addedProjects:d.addedProjects,removedProjects:d.removedProjects,graph:{nodeCount:a.graph?.nodes.length??0,edgeCount:a.graph?.edges.length??0,edgesAdded:d.edgesAdded,edgesRemoved:d.edgesRemoved},durationMs:n})}},S=new Set([".git",".hg",".svn","node_modules",".venv","venv","dist","build","out","target","coverage","htmlcov",".next",".turbo",".cache"]),j=new Set(["reports","cache","tmp",".cache"]);function O(e){if(!e)return  false;let o=e.split(/[\\/]/).filter(Boolean);if(o.some(r=>S.has(r)||a$1(r)))return  false;for(let r=0;r<o.length-1;r+=1)if((o[r]===".workspai"||o[r]===".rapidkit")&&j.has(o[r+1]))return  false;return  true}async function N(e){let o=new k(e.buildOptions,e.engineOptions),r=await o.start();if(e.emit(r),o.currentModel&&await e.onModel?.(o.currentModel,r),e.once)return;let c=e.debounceMs??250,a=e.selfWriteSuppressionMs??Math.max(400,c+150),n=null,d=false,i=false,l=0,p=async()=>{if(d){i=true;return}d=true;try{let t=await o.pulse();e.emit(t),o.currentModel&&await e.onModel?.(o.currentModel,t);}catch(t){e.emit(R({schemaVersion:b,kind:"error",sequence:-1,timestamp:new Date().toISOString(),mode:"full",modelHash:o.currentModel?m(o.currentModel):"",modelHashChanged:false,changedProjects:[],addedProjects:[],removedProjects:[],graph:{nodeCount:0,edgeCount:0,edgesAdded:[],edgesRemoved:[]},durationMs:0,error:t instanceof Error?t.message:String(t)}));}finally{d=false,l=Date.now()+a,i&&(i=false,p());}},h=t=>{O(t)&&(d||Date.now()<l||(n&&clearTimeout(n),n=setTimeout(()=>{n=null,p();},c)));};e.onProgress?.(`Watching ${e.workspacePath} for changes (Ctrl+C to stop).`);let u=y.watch(e.workspacePath,{recursive:true},(t,s)=>{typeof s=="string"?h(s):s&&h(Buffer.from(s).toString("utf8"));});await new Promise(t=>{let s=()=>{n&&clearTimeout(n),u.close(),t();};if(e.signal){if(e.signal.aborted){s();return}e.signal.addEventListener("abort",s,{once:true});}u.on("error",()=>s());});}export{b as WORKSPACE_WATCH_EVENT_SCHEMA_VERSION,k as WorkspaceWatchEngine,m as computeWatchModelHash,C as diffWatchModels,O as isWatchRelevantPath,N as runWorkspaceWatch};

package/docs/README.md

@@ -83,6 +83,7 @@ or use `import` to copy or clone one into the workspace.
 | Bring an existing repository under governance      | [Workspace operations](./workspace-operations.md#import-and-adoption)                       | Source stays in place with `adopt`, or is copied/cloned with `import`    |
 | Run the complete intelligence loop                 | [Unified runner](./workspace-intelligence-runner.md)                                        | One ordered run report with durable stage evidence                       |
 | Turn plain language into governed work             | [Goal Packs](./goal-packs.md)                                                               | A scope-bound, evidence-pinned plan and portable agent handoff           |
+| Prove what an agent changed and why                | [Proof-Carrying Change](./proof-carrying-change.md)                                         | A Goal-bound, effect-receipted, independently verified change capsule    |
 | Ground an agent before broad source discovery      | [Canonical-first agent entry](./agent-entry.md)                                             | A portable receipt for host discovery, evidence integrity, and freshness |
 | Repair a blocker through an approved transaction   | [Workspace Repair Engine](./workspace-repair-engine.md)                                     | Checkpointed execution, validation, canonical verify, and safe rollback  |
 | Set a release, security, or coverage outcome       | [Verified engineering goals](./workspace-intelligence-runner.md#verified-engineering-goals) | A durable success contract with a current evidence-backed verdict        |
@@ -93,6 +94,7 @@ or use `import` to copy or clone one into the workspace.
 | Find the writer, schema, or path for an output     | [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md)                                         | One canonical source instead of path guessing                            |
 | Understand Workspai terminology                    | [Glossary](./GLOSSARY.md)                                                                   | Shared meanings for model, graph, evidence, gate, and artifacts          |
 | Review or change the main product README           | [README content contract](./README_CONTENT_CONTRACT.md)                                     | Stable narrative, claim boundaries, and machine-enforced drift rules     |
+| Choose a first contribution path                   | [Contribution Hub](../../../.github/CONTRIBUTING.md)                                        | One bounded task, support route, and file-aware validation plan          |
 | Contribute to the CLI                              | [Development](./DEVELOPMENT.md)                                                             | Local build, test, contract, and documentation gates                     |
 
 There are two different AI-facing features. Workspace Intelligence is
@@ -102,30 +104,31 @@ with [AI Quickstart](./AI_QUICKSTART.md) only when that is your goal.
 
 ## User documentation
 
-| Document                                                                                       | Description                                                                                                        |
-| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| [creating-workspaces-and-projects.md](./creating-workspaces-and-projects.md)                   | Plain-language guide to every workspace and project creation scenario                                              |
-| [commands-reference.md](./commands-reference.md)                                               | Full CLI syntax, profiles, and policy keys                                                                         |
-| [workspace-operations.md](./workspace-operations.md)                                           | Import, adopt, snapshots, archives, contracts, infra                                                               |
-| [workspace-run.md](./workspace-run.md)                                                         | Polyglot fleet orchestration (`workspace run`)                                                                     |
-| [workspace-intelligence-runner.md](./workspace-intelligence-runner.md)                         | Canonical unified runner, execution envelope, report schema, exit codes, failure propagation, and CI consumption   |
-| [workspace-repair-engine.md](./workspace-repair-engine.md)                                     | CLI-owned plan, approval, checkpoint, execution, verification, decision, and rollback state machine                |
-| [goal-packs.md](./goal-packs.md)                                                               | Plain-language intent compilation, scope/evidence binding, agent handoff, and mutation boundary                    |
-| [agent-entry.md](./agent-entry.md)                                                             | Host-native discovery, canonical evidence preflight, receipt status, privacy, and consumer integration             |
-| [workspace-knowledge-graph.md](./workspace-knowledge-graph.md)                                 | Two-minute graph quickstart, proof model, AI/MCP consumption, performance, and honest token-efficiency measurement |
-| [graph-benchmark-methodology.md](./graph-benchmark-methodology.md)                             | Reproducible payload-reduction benchmark, formulas, claim boundaries, and publication rules                        |
-| [workspace-intelligence-evaluation.md](./workspace-intelligence-evaluation.md)                 | Provider usage, cost provenance, verified outcomes, comparison, and extension consumption                          |
-| [workspace-intelligence-benchmark.md](./workspace-intelligence-benchmark.md)                   | Fixed multi-scenario retrieval metrics, measured evaluation attachment, and publication-safe claim boundaries      |
-| [GLOSSARY.md](./GLOSSARY.md)                                                                   | Plain-language definitions for workspace, model, graph, evidence, gates, and AI integrations                       |
-| [README_CONTENT_CONTRACT.md](./README_CONTENT_CONTRACT.md)                                     | Required root README journey, architecture statements, claim policy, and drift guard                               |
-| [create-planner-capabilities.md](./create-planner-capabilities.md)                             | Native create, official, and existing lanes                                                                        |
-| [../contracts/project-entry-capability.v1.json](../contracts/project-entry-capability.v1.json) | Contract: any readable project can enter through adopt/import when it can be registered                            |
-| [from-code-to-shared-understanding.md](./from-code-to-shared-understanding.md)                 | GitHub-rendered Workspace Intelligence diagram                                                                     |
-| [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md)                               | Role-based workflows (junior → enterprise)                                                                         |
-| [doctor-command.md](./doctor-command.md)                                                       | Doctor scopes, CI exit codes, JSON evidence                                                                        |
-| [config-file-guide.md](./config-file-guide.md)                                                 | User config file (`~/.workspairc.json`, `workspai.config.*`, with legacy fallbacks)                                |
-| [WORKSPACE_MARKER_SPEC.md](./WORKSPACE_MARKER_SPEC.md)                                         | Workspace marker format                                                                                            |
-| [PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md)                                       | npm-only policy for this repository                                                                                |
+| Document                                                                                       | Description                                                                                                         |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| [creating-workspaces-and-projects.md](./creating-workspaces-and-projects.md)                   | Plain-language guide to every workspace and project creation scenario                                               |
+| [commands-reference.md](./commands-reference.md)                                               | Full CLI syntax, profiles, and policy keys                                                                          |
+| [workspace-operations.md](./workspace-operations.md)                                           | Import, adopt, snapshots, archives, contracts, infra                                                                |
+| [workspace-run.md](./workspace-run.md)                                                         | Polyglot fleet orchestration (`workspace run`)                                                                      |
+| [workspace-intelligence-runner.md](./workspace-intelligence-runner.md)                         | Canonical unified runner, execution envelope, report schema, exit codes, failure propagation, and CI consumption    |
+| [workspace-repair-engine.md](./workspace-repair-engine.md)                                     | CLI-owned plan, approval, checkpoint, execution, verification, decision, and rollback state machine                 |
+| [goal-packs.md](./goal-packs.md)                                                               | Plain-language intent compilation, scope/evidence binding, agent handoff, and mutation boundary                     |
+| [proof-carrying-change.md](./proof-carrying-change.md)                                         | Generation-pinned Decisions ledger, predicted-vs-actual Graph delta, receipts, verification, and capsule validation |
+| [agent-entry.md](./agent-entry.md)                                                             | Host-native discovery, canonical evidence preflight, receipt status, privacy, and consumer integration              |
+| [workspace-knowledge-graph.md](./workspace-knowledge-graph.md)                                 | Two-minute graph quickstart, proof model, AI/MCP consumption, performance, and honest token-efficiency measurement  |
+| [graph-benchmark-methodology.md](./graph-benchmark-methodology.md)                             | Reproducible payload-reduction benchmark, formulas, claim boundaries, and publication rules                         |
+| [workspace-intelligence-evaluation.md](./workspace-intelligence-evaluation.md)                 | Provider usage, cost provenance, verified outcomes, comparison, and extension consumption                           |
+| [workspace-intelligence-benchmark.md](./workspace-intelligence-benchmark.md)                   | Fixed multi-scenario retrieval metrics, measured evaluation attachment, and publication-safe claim boundaries       |
+| [GLOSSARY.md](./GLOSSARY.md)                                                                   | Plain-language definitions for workspace, model, graph, evidence, gates, and AI integrations                        |
+| [README_CONTENT_CONTRACT.md](./README_CONTENT_CONTRACT.md)                                     | Required root README journey, architecture statements, claim policy, and drift guard                                |
+| [create-planner-capabilities.md](./create-planner-capabilities.md)                             | Native create, official, and existing lanes                                                                         |
+| [../contracts/project-entry-capability.v1.json](../contracts/project-entry-capability.v1.json) | Contract: any readable project can enter through adopt/import when it can be registered                             |
+| [from-code-to-shared-understanding.md](./from-code-to-shared-understanding.md)                 | GitHub-rendered Workspace Intelligence diagram                                                                      |
+| [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md)                               | Role-based workflows (junior → enterprise)                                                                          |
+| [doctor-command.md](./doctor-command.md)                                                       | Doctor scopes, CI exit codes, JSON evidence                                                                         |
+| [config-file-guide.md](./config-file-guide.md)                                                 | User config file (`~/.workspairc.json`, `workspai.config.*`, with legacy fallbacks)                                 |
+| [WORKSPACE_MARKER_SPEC.md](./WORKSPACE_MARKER_SPEC.md)                                         | Workspace marker format                                                                                             |
+| [PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md)                                       | npm-only policy for this repository                                                                                 |
 
 **Common tasks**
 
@@ -179,13 +182,14 @@ npm run contracts:validate
 
 ## Contributor documentation
 
-| Document                                         | Description                               |
-| ------------------------------------------------ | ----------------------------------------- |
-| [DEVELOPMENT.md](./DEVELOPMENT.md)               | Local dev, testing, debugging             |
-| [SETUP.md](./SETUP.md)                           | Build gates, smoke flows, release hygiene |
-| [ci-workflows.md](./ci-workflows.md)             | GitHub Actions workflow map               |
-| [OPTIMIZATION_GUIDE.md](./OPTIMIZATION_GUIDE.md) | Performance and improvement notes         |
-| [UTILITIES.md](./UTILITIES.md)                   | Internal cache and metrics helpers        |
+| Document                                             | Description                                        |
+| ---------------------------------------------------- | -------------------------------------------------- |
+| [Contribution Hub](../../../.github/CONTRIBUTING.md) | First-task routes, support, and validation planner |
+| [DEVELOPMENT.md](./DEVELOPMENT.md)                   | Local dev, testing, debugging                      |
+| [SETUP.md](./SETUP.md)                               | Build gates, smoke flows, release hygiene          |
+| [ci-workflows.md](./ci-workflows.md)                 | GitHub Actions workflow map                        |
+| [OPTIMIZATION_GUIDE.md](./OPTIMIZATION_GUIDE.md)     | Performance and improvement notes                  |
+| [UTILITIES.md](./UTILITIES.md)                       | Internal cache and metrics helpers                 |
 
 Also see [../CONTRIBUTING.md](../CONTRIBUTING.md) and [../CHANGELOG.md](../CHANGELOG.md).
 

package/docs/ci-workflows.md

@@ -63,7 +63,7 @@ Validate or preview the current CLI announcement locally:
 npm --workspace workspai run check:release-announcement
 npm --workspace workspai run release:announcement -- \
   --product workspai-cli \
-  --tag v0.68.0 \
+  --tag v0.70.0 \
   --markdown-output /tmp/workspai-discord-announcement.md
 ```
 

package/docs/commands-reference.md

@@ -64,6 +64,17 @@ npx workspai readiness [--workspace <path>] [--json] [--strict] [--skip-verify]
 npx workspai autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--output <file>] [--since <ref>] [--parallel] [--max-workers <n>]
 npx workspai goal <intent> [--workspace <path>] [--scope <workspace|project:name|projects:a,b>] [--runtime <runtime>] [--for-agent <generic|claude|codex>] [--max-attempts <1-25>] [--refresh] [--dry-run] [--json]
 npx workspai goal <--status [goal-id]|--list|--activate <goal-id>|--cancel <goal-id>|--prepare <goal-id>|--verify <goal-id>> [--workspace <path>] [--no-run] [--json]
+npx workspai change begin [--goal <goal-id>] [--workspace <path>] [--json]
+npx workspai change list [--workspace <path>] [--json]
+npx workspai change predict --change <change-id> --file <prediction.json> [--workspace <path>] [--json]
+npx workspai change authorize --change <change-id> --effects <classes> [--granted-by <identity>] [--workspace <path>] [--json]
+npx workspai change effect record --change <change-id> --file <effect-receipt.json> [--workspace <path>] [--json]
+npx workspai change verify --change <change-id> [--strict] [--no-refresh] [--workspace <path>] [--json]
+npx workspai change verification record --change <change-id> --file <verification-receipt.json> [--workspace <path>] [--json]
+npx workspai change <status|explain> --change <change-id> [--workspace <path>] [--json]
+npx workspai change resume --change <change-id> --to <authorized|executing|verifying> --reason <text> [--actor <identity>] [--json]
+npx workspai change abort --change <change-id> --reason <text> [--actor <identity>] [--json]
+npx workspai change capsule <validate|export> --change <change-id> [--output <path>] [--json]
 npx workspai agent bootstrap [--project <path>] [--for-agent <host>] [--no-live-inputs] [--strict] [--json]
 ```
 
@@ -210,6 +221,21 @@ claim verification. Lifecycle operations are mutually exclusive, cannot be
 combined with an intent or planning-only flags, and `--no-run` is valid only
 with `--verify`. See [Goal Packs](./goal-packs.md).
 
+`change` turns an active Goal into a Proof-Carrying Change. `list` is the
+versioned discovery surface for open, blocked, sealed, aborted, and invalid
+capsules. `begin` pins the
+exact Model, Graph, and live-input generation. `predict` is explicitly
+noncanonical and never counts as proof. A human uses `authorize` to grant
+bounded effect classes; agents and tools then append typed, idempotent effect
+receipts. Removed paths use `deletedArtifacts: [{ "artifact": "..." }]`; the
+CLI emits a governed tombstone only after proving the path is absent and
+contained by the workspace or linked-project contract. `verify` re-observes
+the canonical Graph, derives the actual overlay,
+reports prediction surprises, and records Workspace Verify against the exact
+post-effect generation. Additional Goal-domain receipts enter through
+`verification record`. Only complete, passing criteria can seal a capsule. See
+[Proof-Carrying Change](./proof-carrying-change.md).
+
 Coverage Goals are runtime-bound. Interactive terminals select from the
 canonical Workspace Model when the chosen scope has multiple runtimes;
 non-interactive consumers receive `needs-confirmation` and rerun with

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,68 @@
+# 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 or validated deletion-tombstone coverage for changed
+   Graph proof artifacts;
+9. deletion paths remain absent and contained by the workspace or an explicit
+   linked-project contract;
+10. latest passing receipt for every immutable Goal criterion;
+11. 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,119 @@
+{
+  "schemaVersion": "workspai.proof-carrying-change-implementation-plan.v1",
+  "status": "released",
+  "release": "0.69.0",
+  "hardeningRelease": "0.70.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-cli-contract-ready",
+    "extensionStudioMutationAdapter": "implemented-cli-contract-ready"
+  },
+  "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"
+  ]
+}