workspai 0.43.1 → 0.44.0

package/contracts/workspace-intelligence-chain.v1.json

@@ -0,0 +1,1194 @@
+{
+  "schemaVersion": "workspai-workspace-intelligence-chain-v1",
+  "name": "Workspace Intelligence Chain",
+  "contractPath": "contracts/workspace-intelligence-chain.v1.json",
+  "invariant": "Every consumer must preserve step identity, dependencies, artifact flow, and verdict semantics; presentation may change, chain meaning may not.",
+  "invariants": [
+    "Missing or unreadable input is unknown or unavailable; it must not be presented as verified absence.",
+    "Freshness and provenance travel with evidence and must not be discarded by projections.",
+    "The current graph is a workspace dependency graph, not a complete cross-language symbol or call graph.",
+    "Simple and standard presentations summarize the contract; their contractRefs must preserve complete traceability.",
+    "Conditional provider outputs must be resolved through their dedicated inventory contract.",
+    "Auxiliary capabilities expose or refresh intelligence but are not mandatory execution-chain steps.",
+    "Canonical step commands are stage-pure: they must not implicitly execute a downstream chain step or regenerate an upstream artifact.",
+    "Canonical JSON artifacts must satisfy their registered schema both when produced and when consumed across CLI, MCP, IDE, and CI trust boundaries.",
+    "Schema validity is necessary but not sufficient: hashes, embedded models, summaries, counts, graph statistics, and artifact references must remain semantically coherent.",
+    "Persisted impact evidence must be rejected as stale when the current workspace model or Git observation no longer matches its embedded diff.",
+    "Canonical artifact replacement must be atomic and workspace-contained; an interrupted or denied write must preserve the last valid artifact.",
+    "Concurrent history updates must be serialized without silently dropping entries, and invalid history must never be overwritten as if it were absent.",
+    "The canonical global registry is ~/.workspai/workspaces.json; ~/.rapidkit/workspaces.json is a non-authoritative compatibility mirror for legacy consumers and must not diverge after a CLI registry mutation."
+  ],
+  "semantics": {
+    "workspace": "The governed operating boundary that relates one or more projects and repositories to shared metadata, policies, contracts, evidence, and consumers.",
+    "repository": "A source-control boundary that may contain one or more projects and may live inside or outside the workspace root.",
+    "project": "A discoverable build or runtime unit with its own path, metadata or observable manifests, command capabilities, and evidence.",
+    "evidence": "A sourced observation or generated verification result with provenance and freshness; evidence may be consumed by a later run.",
+    "artifact": "A durable generated file that another command or consumer can read without parsing terminal prose.",
+    "gate": "A structured verdict with reasons and exit semantics derived from current evidence."
+  },
+  "workspaceLifecycle": {
+    "ingestionRoutes": [
+      {
+        "id": "create",
+        "label": "Create",
+        "commands": [
+          "create workspace",
+          "create project"
+        ],
+        "result": "Create a workspace or supported project and write canonical Workspai metadata."
+      },
+      {
+        "id": "adopt",
+        "label": "Adopt",
+        "commands": [
+          "adopt"
+        ],
+        "result": "Register an existing project in place without requiring source relocation."
+      },
+      {
+        "id": "import",
+        "label": "Import",
+        "commands": [
+          "import",
+          "workspace import"
+        ],
+        "result": "Attach an existing project or repository path to the workspace inventory."
+      }
+    ],
+    "durableState": [
+      {
+        "id": "workspace-identity",
+        "paths": [
+          ".workspai-workspace",
+          ".workspai/workspace.json"
+        ],
+        "purpose": "Identify the workspace boundary, profile, and canonical root."
+      },
+      {
+        "id": "project-inventory",
+        "paths": [
+          ".workspai/project.json",
+          ".workspai/context.json",
+          ".workspai/adopt.json",
+          "~/.workspai/workspaces.json",
+          "~/.rapidkit/workspaces.json (legacy compatibility mirror)"
+        ],
+        "purpose": "Record native, adopted, imported, and globally registered project locations while preserving a non-authoritative mirror for legacy extension discovery."
+      },
+      {
+        "id": "governance",
+        "paths": [
+          ".workspai/policies.yml",
+          ".workspai/workspace.contract.json"
+        ],
+        "purpose": "Define workspace policy and explicit structural relationships."
+      },
+      {
+        "id": "graph-overrides",
+        "paths": [
+          ".workspai/workspace-graph.overrides.json"
+        ],
+        "purpose": "Provide explicit dependency edges that override inferred relationships."
+      }
+    ],
+    "rule": "Create, adopt, and import are ingestion routes, not intelligence facts. Their durable state becomes observable input to Model."
+  },
+  "runtimeRegistry": {
+    "authority": "contracts/workspace-intelligence-runtime-registry.ts",
+    "artifacts": [
+      {
+        "id": "model",
+        "path": ".workspai/reports/workspace-model.json",
+        "schemaVersion": "workspace-model.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-model.v1.json"
+      },
+      {
+        "id": "snapshot",
+        "path": ".workspai/reports/workspace-model-snapshot.json",
+        "schemaVersion": "workspace-model-snapshot.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-model-snapshot.v1.json"
+      },
+      {
+        "id": "diff",
+        "path": ".workspai/reports/workspace-model-diff-last-run.json",
+        "schemaVersion": "workspace-model-diff.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-model-diff.v1.json"
+      },
+      {
+        "id": "impact",
+        "path": ".workspai/reports/workspace-impact-last-run.json",
+        "schemaVersion": "workspace-impact.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-impact.v1.json"
+      },
+      {
+        "id": "analyze",
+        "path": ".workspai/reports/analyze-last-run.json",
+        "schemaVersion": "rapidkit-analyze-v1",
+        "schemaContract": "contracts/analyze-last-run.v1.json"
+      },
+      {
+        "id": "doctor",
+        "path": ".workspai/reports/doctor-last-run.json",
+        "schemaVersion": "doctor-workspace-evidence-v1",
+        "schemaContract": "contracts/doctor-workspace-evidence.v1.json"
+      },
+      {
+        "id": "contractVerify",
+        "path": ".workspai/reports/workspace-contract-verify-last-run.json",
+        "schemaVersion": "workspace-contract-verify.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-contract-verify.v1.json"
+      },
+      {
+        "id": "readiness",
+        "path": ".workspai/reports/release-readiness-last-run.json",
+        "schemaVersion": "release-readiness-v1",
+        "schemaContract": "contracts/release-readiness.v1.json"
+      },
+      {
+        "id": "verify",
+        "path": ".workspai/reports/workspace-verify-last-run.json",
+        "schemaVersion": "workspace-verify.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-verify.v1.json"
+      },
+      {
+        "id": "history",
+        "path": ".workspai/reports/workspace-intelligence-history.json",
+        "schemaVersion": "workspace-intelligence-history.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-intelligence-history.v1.json"
+      },
+      {
+        "id": "agentContext",
+        "path": ".workspai/reports/workspace-context-agent.json",
+        "schemaVersion": "workspace-context.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-context.v1.json"
+      },
+      {
+        "id": "agentIndex",
+        "path": ".workspai/reports/INDEX.json",
+        "schemaVersion": "rapidkit-agent-reports-index.v1",
+        "schemaContract": "contracts/workspace-intelligence/agent-reports-index.v1.json"
+      },
+      {
+        "id": "agentCustomizationPack",
+        "path": ".workspai/reports/agent-customization-pack.json",
+        "schemaVersion": "rapidkit-agent-customization-pack.v1",
+        "schemaContract": "contracts/workspace-intelligence/agent-customization-pack-report.v1.json"
+      },
+      {
+        "id": "skillsIndex",
+        "path": ".workspai/reports/workspace-skills-index.json",
+        "schemaVersion": "workspace-skills-index.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-skills-index.v1.json"
+      },
+      {
+        "id": "agents",
+        "path": "AGENTS.md",
+        "schemaVersion": null,
+        "schemaContract": null
+      },
+      {
+        "id": "explain",
+        "path": ".workspai/reports/workspace-explain-last-run.json",
+        "schemaVersion": "workspace-explain.v1",
+        "schemaContract": "contracts/workspace-intelligence/workspace-explain.v1.json"
+      }
+    ]
+  },
+  "boundaries": {
+    "inputs": [
+      {
+        "id": "projects-repositories",
+        "label": "Projects and repositories",
+        "sources": [
+          "projects",
+          "repositories",
+          "services",
+          "modules",
+          "imported paths"
+        ],
+        "entersAt": "model"
+      },
+      {
+        "id": "runtime-dependencies",
+        "label": "Runtime and dependencies",
+        "sources": [
+          "runtime manifests",
+          "lockfiles",
+          "scripts",
+          "framework markers",
+          "package dependencies",
+          "supported source imports (currently bounded JavaScript and TypeScript scanning)"
+        ],
+        "entersAt": "model"
+      },
+      {
+        "id": "workspace-rules",
+        "label": "Workspace rules",
+        "sources": [
+          "workspace markers",
+          "registry",
+          "project metadata",
+          "contracts",
+          "policies",
+          "ownership",
+          "graph overrides"
+        ],
+        "entersAt": "model"
+      },
+      {
+        "id": "changes",
+        "label": "Changes",
+        "sources": [
+          "repository state",
+          "git state",
+          "model baseline",
+          "workspace diff"
+        ],
+        "entersAt": "diff"
+      },
+      {
+        "id": "model-baseline",
+        "label": "Explicit model baseline",
+        "sources": [
+          ".workspai/reports/workspace-model-snapshot.json"
+        ],
+        "entersAt": "diff"
+      },
+      {
+        "id": "existing-evidence",
+        "label": "Existing evidence",
+        "sources": [
+          "doctor reports",
+          "analysis reports",
+          "contract verification",
+          "release readiness",
+          "pipeline results",
+          "tests and runtime evidence",
+          "previous intelligence artifacts"
+        ],
+        "entersAt": "doctor-evidence"
+      }
+    ],
+    "outputs": [
+      {
+        "id": "understanding",
+        "label": "System understanding",
+        "artifacts": [
+          ".workspai/reports/workspace-model.json",
+          ".workspai/reports/workspace-model-diff-last-run.json",
+          ".workspai/reports/workspace-impact-last-run.json"
+        ],
+        "producedBy": [
+          "model",
+          "diff",
+          "impact"
+        ],
+        "inventory": "complete-for-chain"
+      },
+      {
+        "id": "governance-evidence",
+        "label": "Governance evidence",
+        "artifacts": [
+          ".workspai/reports/doctor-last-run.json",
+          ".workspai/reports/workspace-contract-verify-last-run.json",
+          ".workspai/reports/analyze-last-run.json",
+          ".workspai/reports/release-readiness-last-run.json",
+          ".workspai/reports/workspace-verify-last-run.json",
+          ".workspai/reports/workspace-intelligence-history.json"
+        ],
+        "producedBy": [
+          "doctor-evidence",
+          "contract-evidence",
+          "analyze-evidence",
+          "readiness-evidence",
+          "verify"
+        ],
+        "inventory": "complete-for-chain"
+      },
+      {
+        "id": "agent-grounding",
+        "label": "Agent grounding",
+        "artifacts": [
+          ".workspai/reports/workspace-context-agent.json",
+          ".workspai/reports/INDEX.json",
+          ".workspai/reports/agent-customization-pack.json",
+          ".workspai/reports/workspace-skills-index.json",
+          "AGENTS.md"
+        ],
+        "producedBy": [
+          "context",
+          "agent-sync"
+        ],
+        "inventory": "canonical-minimum",
+        "inventoryContract": "contracts/agent-customization-pack.v1.json"
+      },
+      {
+        "id": "explanations",
+        "label": "Explainable decisions",
+        "artifacts": [
+          ".workspai/reports/workspace-explain-last-run.json"
+        ],
+        "producedBy": [
+          "explain"
+        ],
+        "inventory": "complete-for-chain"
+      }
+    ],
+    "consumers": [
+      {
+        "id": "developers",
+        "label": "Developers",
+        "channels": [
+          "CLI",
+          "reports",
+          "AGENTS.md"
+        ]
+      },
+      {
+        "id": "ci",
+        "label": "CI",
+        "channels": [
+          "JSON artifacts",
+          "exit codes",
+          "release gates"
+        ]
+      },
+      {
+        "id": "ides",
+        "label": "IDEs",
+        "channels": [
+          "synced contracts",
+          "extension",
+          "agent context"
+        ]
+      },
+      {
+        "id": "ai-agents",
+        "label": "AI agents",
+        "channels": [
+          "INDEX.json",
+          "context",
+          "skills",
+          "MCP"
+        ]
+      }
+    ]
+  },
+  "deliveryChannels": [
+    {
+      "id": "artifacts",
+      "carries": [
+        "reports",
+        "models",
+        "context",
+        "grounding",
+        "skills"
+      ],
+      "authority": "canonical"
+    },
+    {
+      "id": "json-stdout",
+      "carries": [
+        "structured command results"
+      ],
+      "authority": "projection"
+    },
+    {
+      "id": "human-cli",
+      "carries": [
+        "summaries",
+        "diagnostics",
+        "next actions"
+      ],
+      "authority": "projection"
+    },
+    {
+      "id": "exit-codes",
+      "carries": [
+        "gate and command status"
+      ],
+      "authority": "projection"
+    },
+    {
+      "id": "watch-events",
+      "carries": [
+        "incremental workspace change events"
+      ],
+      "authority": "projection"
+    },
+    {
+      "id": "mcp",
+      "carries": [
+        "read-mostly access to current workspace artifacts"
+      ],
+      "authority": "projection"
+    }
+  ],
+  "feedback": {
+    "from": [
+      "developers",
+      "ci",
+      "ides",
+      "ai-agents"
+    ],
+    "signals": [
+      "source commits",
+      "dependency updates",
+      "policy and contract edits",
+      "repairs",
+      "test and runtime results",
+      "agent action outcomes"
+    ],
+    "reentersThrough": [
+      "projects-repositories",
+      "runtime-dependencies",
+      "workspace-rules",
+      "changes",
+      "existing-evidence"
+    ],
+    "rule": "Consumer actions are not silently treated as truth. They re-enter as observable changes or evidence and must be modeled and verified again."
+  },
+  "auxiliaryCapabilities": [
+    {
+      "id": "graph",
+      "commands": [
+        "workspace graph emit",
+        "workspace graph explain",
+        "workspace graph dot",
+        "workspace graph mermaid"
+      ],
+      "reads": [
+        ".workspai/reports/workspace-model.json#graph"
+      ],
+      "role": "Inspect or render the graph already embedded in the workspace model.",
+      "chainStep": false
+    },
+    {
+      "id": "watch",
+      "commands": [
+        "workspace watch"
+      ],
+      "reads": [
+        "workspace inputs",
+        ".workspai/reports/workspace-model.json"
+      ],
+      "role": "Refresh the model incrementally and emit deterministic change events.",
+      "chainStep": false
+    },
+    {
+      "id": "mcp",
+      "commands": [
+        "workspace mcp serve"
+      ],
+      "reads": [
+        "workspace evidence artifacts"
+      ],
+      "role": "Expose read-mostly workspace evidence to compatible clients.",
+      "chainStep": false
+    }
+  ],
+  "presentations": {
+    "simple": {
+      "layers": [
+        "inputs",
+        "intelligence",
+        "outputs",
+        "consumers"
+      ],
+      "nodes": [
+        {
+          "id": "input-layer",
+          "kind": "inputs",
+          "label": "Input Layer",
+          "summary": "Projects · Repositories · Dependencies · Changes",
+          "contractRefs": [
+            "projects-repositories",
+            "runtime-dependencies",
+            "workspace-rules",
+            "changes",
+            "model-baseline",
+            "existing-evidence"
+          ]
+        },
+        {
+          "id": "workspace-intelligence",
+          "kind": "intelligence",
+          "label": "Workspace Intelligence",
+          "summary": "Model · Graph · Impact · Verify",
+          "contractRefs": [
+            "model",
+            "diff",
+            "impact",
+            "doctor-evidence",
+            "contract-evidence",
+            "analyze-evidence",
+            "readiness-evidence",
+            "verify",
+            "context",
+            "agent-sync",
+            "explain"
+          ]
+        },
+        {
+          "id": "agent-grounding",
+          "kind": "outputs",
+          "label": "Agent Grounding",
+          "summary": "AGENTS.md · Skills · Context",
+          "contractRefs": [
+            "agent-grounding"
+          ]
+        },
+        {
+          "id": "evidence-and-decisions",
+          "kind": "outputs",
+          "label": "Evidence Contracts",
+          "summary": "Reports · Artifacts · Gates",
+          "contractRefs": [
+            "understanding",
+            "governance-evidence",
+            "explanations"
+          ]
+        },
+        {
+          "id": "shared-consumers",
+          "kind": "consumers",
+          "label": "Shared Consumers",
+          "summary": "Developers · CI · IDEs · AI agents",
+          "contractRefs": [
+            "developers",
+            "ci",
+            "ides",
+            "ai-agents"
+          ]
+        }
+      ],
+      "rule": "Use concrete user-facing language for first-contact explanations. Every input, output, consumer, and chain step must remain traceable through contractRefs even when details are summarized."
+    },
+    "standard": {
+      "phases": [
+        "understand",
+        "change",
+        "evidence",
+        "gate",
+        "ground",
+        "distribute",
+        "explain"
+      ],
+      "nodes": [
+        {
+          "id": "understand",
+          "label": "Understand",
+          "question": "What exists in the current workspace?",
+          "stepRefs": [
+            "model"
+          ]
+        },
+        {
+          "id": "change",
+          "label": "Change",
+          "question": "What changed, and what can it affect?",
+          "stepRefs": [
+            "diff",
+            "impact"
+          ]
+        },
+        {
+          "id": "evidence",
+          "label": "Evidence",
+          "question": "What health, contract, and readiness facts were observed?",
+          "stepRefs": [
+            "doctor-evidence",
+            "contract-evidence",
+            "analyze-evidence",
+            "readiness-evidence"
+          ]
+        },
+        {
+          "id": "gate",
+          "label": "Gate",
+          "question": "Is the current state acceptable and trustworthy?",
+          "stepRefs": [
+            "verify"
+          ]
+        },
+        {
+          "id": "ground",
+          "label": "Ground",
+          "question": "What should an agent know before acting?",
+          "stepRefs": [
+            "context"
+          ]
+        },
+        {
+          "id": "distribute",
+          "label": "Distribute",
+          "question": "Which durable agent and IDE surfaces receive that context?",
+          "stepRefs": [
+            "agent-sync"
+          ]
+        },
+        {
+          "id": "explain",
+          "label": "Explain",
+          "question": "Why did the system reach this result or verdict?",
+          "stepRefs": [
+            "explain"
+          ]
+        }
+      ],
+      "rule": "Use for architecture education and product surfaces. Every phase must appear once and in order."
+    },
+    "advanced": {
+      "steps": [
+        "model",
+        "diff",
+        "impact",
+        "doctor-evidence",
+        "contract-evidence",
+        "analyze-evidence",
+        "readiness-evidence",
+        "verify",
+        "context",
+        "agent-sync",
+        "explain"
+      ],
+      "requiredFields": [
+        "command",
+        "inputRefs",
+        "consumesArtifacts",
+        "produces",
+        "dependsOn",
+        "exitPolicy",
+        "purpose"
+      ],
+      "rule": "Use for implementers, adapters, IDEs, and CI. Preserve every step and its artifact and verdict semantics."
+    }
+  },
+  "steps": [
+    {
+      "id": "model",
+      "ordinal": 1,
+      "phase": "understand",
+      "label": "Model",
+      "command": [
+        "workspace",
+        "model",
+        "--json",
+        "--write"
+      ],
+      "consumes": [
+        "workspace markers",
+        "project metadata",
+        "registry",
+        "contract",
+        "policies"
+      ],
+      "inputRefs": [
+        "projects-repositories",
+        "runtime-dependencies",
+        "workspace-rules",
+        "existing-evidence"
+      ],
+      "consumesArtifacts": [],
+      "produces": [
+        ".workspai/reports/workspace-model.json"
+      ],
+      "dependsOn": [],
+      "exitPolicy": "stop-on-error",
+      "purpose": "Build the canonical current model of the software system."
+    },
+    {
+      "id": "diff",
+      "ordinal": 2,
+      "phase": "change",
+      "label": "Diff",
+      "command": [
+        "workspace",
+        "diff",
+        "--from",
+        ".workspai/reports/workspace-model-snapshot.json",
+        "--json"
+      ],
+      "consumes": [
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-model-snapshot.json"
+      ],
+      "inputRefs": [
+        "changes",
+        "model-baseline"
+      ],
+      "consumesArtifacts": [
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-model-snapshot.json"
+      ],
+      "produces": [
+        ".workspai/reports/workspace-model-diff-last-run.json"
+      ],
+      "dependsOn": [
+        "model"
+      ],
+      "exitPolicy": "stop-on-error",
+      "purpose": "Describe structural change against the selected baseline."
+    },
+    {
+      "id": "impact",
+      "ordinal": 3,
+      "phase": "change",
+      "label": "Impact",
+      "command": [
+        "workspace",
+        "impact",
+        "--from",
+        ".workspai/reports/workspace-model-diff-last-run.json",
+        "--json"
+      ],
+      "consumes": [
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-model-diff-last-run.json"
+      ],
+      "inputRefs": [],
+      "consumesArtifacts": [
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-model-diff-last-run.json"
+      ],
+      "produces": [
+        ".workspai/reports/workspace-impact-last-run.json"
+      ],
+      "dependsOn": [
+        "diff"
+      ],
+      "exitPolicy": "stop-on-error",
+      "purpose": "Calculate transitive blast radius over the workspace graph."
+    },
+    {
+      "id": "doctor-evidence",
+      "ordinal": 4,
+      "phase": "evidence",
+      "label": "Doctor Evidence",
+      "command": [
+        "doctor",
+        "workspace",
+        "--json"
+      ],
+      "consumes": [
+        "workspace runtime and project health signals"
+      ],
+      "inputRefs": [
+        "projects-repositories",
+        "runtime-dependencies",
+        "existing-evidence"
+      ],
+      "consumesArtifacts": [],
+      "produces": [
+        ".workspai/reports/doctor-last-run.json"
+      ],
+      "dependsOn": [
+        "impact"
+      ],
+      "exitPolicy": "continue-on-structured-verdict",
+      "purpose": "Refresh health evidence after the impact artifact exists."
+    },
+    {
+      "id": "contract-evidence",
+      "ordinal": 5,
+      "phase": "evidence",
+      "label": "Contract Evidence",
+      "command": [
+        "workspace",
+        "contract",
+        "verify",
+        "--strict",
+        "--json"
+      ],
+      "consumes": [
+        ".workspai/workspace.contract.json"
+      ],
+      "inputRefs": [
+        "workspace-rules"
+      ],
+      "consumesArtifacts": [],
+      "produces": [
+        ".workspai/reports/workspace-contract-verify-last-run.json"
+      ],
+      "dependsOn": [
+        "impact"
+      ],
+      "exitPolicy": "continue-on-structured-verdict",
+      "purpose": "Refresh structural contract evidence without hiding failed verdicts."
+    },
+    {
+      "id": "analyze-evidence",
+      "ordinal": 6,
+      "phase": "evidence",
+      "label": "Analyze Evidence",
+      "command": [
+        "analyze",
+        "--json"
+      ],
+      "consumes": [
+        ".workspai/reports/workspace-model.json",
+        "workspace runtime and dependency signals"
+      ],
+      "inputRefs": [
+        "projects-repositories",
+        "runtime-dependencies",
+        "workspace-rules"
+      ],
+      "consumesArtifacts": [
+        ".workspai/reports/workspace-model.json"
+      ],
+      "produces": [
+        ".workspai/reports/analyze-last-run.json"
+      ],
+      "dependsOn": [
+        "impact"
+      ],
+      "exitPolicy": "continue-on-structured-verdict",
+      "purpose": "Refresh analysis evidence required by the release-readiness gate."
+    },
+    {
+      "id": "readiness-evidence",
+      "ordinal": 7,
+      "phase": "evidence",
+      "label": "Readiness Evidence",
+      "command": [
+        "readiness",
+        "--json"
+      ],
+      "consumes": [
+        "doctor, analysis, runtime, and release signals"
+      ],
+      "inputRefs": [
+        "runtime-dependencies",
+        "existing-evidence"
+      ],
+      "consumesArtifacts": [
+        ".workspai/reports/doctor-last-run.json",
+        ".workspai/reports/workspace-contract-verify-last-run.json",
+        ".workspai/reports/analyze-last-run.json"
+      ],
+      "produces": [
+        ".workspai/reports/release-readiness-last-run.json"
+      ],
+      "dependsOn": [
+        "doctor-evidence",
+        "contract-evidence",
+        "analyze-evidence"
+      ],
+      "exitPolicy": "continue-on-structured-verdict",
+      "purpose": "Refresh release-readiness evidence before the definitive gate."
+    },
+    {
+      "id": "verify",
+      "ordinal": 8,
+      "phase": "gate",
+      "label": "Verify",
+      "command": [
+        "workspace",
+        "verify",
+        "--from-impact",
+        ".workspai/reports/workspace-impact-last-run.json",
+        "--json"
+      ],
+      "consumes": [
+        ".workspai/reports/workspace-impact-last-run.json",
+        ".workspai/reports/doctor-last-run.json",
+        ".workspai/reports/workspace-contract-verify-last-run.json",
+        ".workspai/reports/release-readiness-last-run.json"
+      ],
+      "inputRefs": [],
+      "consumesArtifacts": [
+        ".workspai/reports/workspace-impact-last-run.json",
+        ".workspai/reports/doctor-last-run.json",
+        ".workspai/reports/workspace-contract-verify-last-run.json",
+        ".workspai/reports/release-readiness-last-run.json"
+      ],
+      "produces": [
+        ".workspai/reports/workspace-verify-last-run.json",
+        ".workspai/reports/workspace-intelligence-history.json"
+      ],
+      "dependsOn": [
+        "impact",
+        "doctor-evidence",
+        "contract-evidence",
+        "analyze-evidence",
+        "readiness-evidence"
+      ],
+      "exitPolicy": "continue-on-structured-verdict",
+      "purpose": "Emit the definitive evidence-backed workspace gate."
+    },
+    {
+      "id": "context",
+      "ordinal": 9,
+      "phase": "ground",
+      "label": "Agent Context",
+      "command": [
+        "workspace",
+        "context",
+        "--for-agent",
+        "--json",
+        "--write",
+        "--no-agent-sync"
+      ],
+      "consumes": [
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-impact-last-run.json",
+        ".workspai/reports/workspace-verify-last-run.json"
+      ],
+      "inputRefs": [],
+      "consumesArtifacts": [
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-impact-last-run.json",
+        ".workspai/reports/workspace-verify-last-run.json"
+      ],
+      "produces": [
+        ".workspai/reports/workspace-context-agent.json"
+      ],
+      "dependsOn": [
+        "verify"
+      ],
+      "exitPolicy": "stop-on-error",
+      "purpose": "Build compact agent context from the same verified evidence."
+    },
+    {
+      "id": "agent-sync",
+      "ordinal": 10,
+      "phase": "distribute",
+      "label": "Agent Grounding",
+      "command": [
+        "workspace",
+        "agent-sync",
+        "--write",
+        "--json",
+        "--preset",
+        "enterprise"
+      ],
+      "consumerArgs": {
+        "vscode": [
+          "--target",
+          "vscode"
+        ]
+      },
+      "consumes": [
+        ".workspai/reports/workspace-context-agent.json"
+      ],
+      "inputRefs": [],
+      "consumesArtifacts": [
+        ".workspai/reports/workspace-context-agent.json"
+      ],
+      "produces": [
+        ".workspai/reports/INDEX.json",
+        ".workspai/reports/agent-customization-pack.json",
+        ".workspai/reports/workspace-skills-index.json",
+        "AGENTS.md"
+      ],
+      "dependsOn": [
+        "context"
+      ],
+      "exitPolicy": "stop-on-error",
+      "purpose": "Distribute one context into portable agent and IDE surfaces."
+    },
+    {
+      "id": "explain",
+      "ordinal": 11,
+      "phase": "explain",
+      "label": "Explain",
+      "command": [
+        "workspace",
+        "explain",
+        "release-blocked",
+        "--json",
+        "--write"
+      ],
+      "consumes": [
+        ".workspai/reports/workspace-verify-last-run.json",
+        ".workspai/reports/workspace-impact-last-run.json"
+      ],
+      "inputRefs": [],
+      "consumesArtifacts": [
+        ".workspai/reports/workspace-verify-last-run.json",
+        ".workspai/reports/workspace-impact-last-run.json"
+      ],
+      "produces": [
+        ".workspai/reports/workspace-explain-last-run.json"
+      ],
+      "dependsOn": [
+        "verify"
+      ],
+      "exitPolicy": "continue-on-structured-verdict",
+      "purpose": "Translate evidence and blockers into a human and agent-readable narrative."
+    }
+  ],
+  "diagram": {
+    "direction": "TB",
+    "nodes": [
+      {
+        "id": "model",
+        "label": "Model",
+        "phase": "understand"
+      },
+      {
+        "id": "diff",
+        "label": "Diff",
+        "phase": "change"
+      },
+      {
+        "id": "impact",
+        "label": "Impact",
+        "phase": "change"
+      },
+      {
+        "id": "doctor-evidence",
+        "label": "Doctor Evidence",
+        "phase": "evidence"
+      },
+      {
+        "id": "contract-evidence",
+        "label": "Contract Evidence",
+        "phase": "evidence"
+      },
+      {
+        "id": "analyze-evidence",
+        "label": "Analyze Evidence",
+        "phase": "evidence"
+      },
+      {
+        "id": "readiness-evidence",
+        "label": "Readiness Evidence",
+        "phase": "evidence"
+      },
+      {
+        "id": "verify",
+        "label": "Verify",
+        "phase": "gate"
+      },
+      {
+        "id": "context",
+        "label": "Agent Context",
+        "phase": "ground"
+      },
+      {
+        "id": "agent-sync",
+        "label": "Agent Grounding",
+        "phase": "distribute"
+      },
+      {
+        "id": "explain",
+        "label": "Explain",
+        "phase": "explain"
+      }
+    ],
+    "edges": [
+      {
+        "from": "model",
+        "to": "diff",
+        "meaning": "required before"
+      },
+      {
+        "from": "diff",
+        "to": "impact",
+        "meaning": "required before"
+      },
+      {
+        "from": "impact",
+        "to": "doctor-evidence",
+        "meaning": "required before"
+      },
+      {
+        "from": "impact",
+        "to": "contract-evidence",
+        "meaning": "required before"
+      },
+      {
+        "from": "impact",
+        "to": "analyze-evidence",
+        "meaning": "required before"
+      },
+      {
+        "from": "doctor-evidence",
+        "to": "readiness-evidence",
+        "meaning": "required before"
+      },
+      {
+        "from": "contract-evidence",
+        "to": "readiness-evidence",
+        "meaning": "required before"
+      },
+      {
+        "from": "analyze-evidence",
+        "to": "readiness-evidence",
+        "meaning": "required before"
+      },
+      {
+        "from": "impact",
+        "to": "verify",
+        "meaning": "required before"
+      },
+      {
+        "from": "doctor-evidence",
+        "to": "verify",
+        "meaning": "required before"
+      },
+      {
+        "from": "contract-evidence",
+        "to": "verify",
+        "meaning": "required before"
+      },
+      {
+        "from": "analyze-evidence",
+        "to": "verify",
+        "meaning": "required before"
+      },
+      {
+        "from": "readiness-evidence",
+        "to": "verify",
+        "meaning": "required before"
+      },
+      {
+        "from": "verify",
+        "to": "context",
+        "meaning": "required before"
+      },
+      {
+        "from": "context",
+        "to": "agent-sync",
+        "meaning": "required before"
+      },
+      {
+        "from": "verify",
+        "to": "explain",
+        "meaning": "required before"
+      }
+    ]
+  },
+  "consumers": {
+    "agents": {
+      "canonicalReadOrder": [
+        ".workspai/reports/INDEX.json",
+        ".workspai/reports/workspace-context-agent.json",
+        ".workspai/reports/workspace-verify-last-run.json",
+        ".workspai/reports/workspace-impact-last-run.json",
+        ".workspai/reports/workspace-explain-last-run.json",
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/agent-customization-pack.json",
+        ".workspai/reports/workspace-skills-index.json"
+      ],
+      "entrypoints": [
+        "AGENTS.md",
+        ".workspai/AGENT-GROUNDING.md"
+      ],
+      "rule": "Agents must cite current artifacts, preserve verified versus inferred status, and re-run the producing step when evidence is missing or stale."
+    },
+    "ideAndCi": {
+      "requiredArtifacts": [
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-impact-last-run.json",
+        ".workspai/reports/workspace-verify-last-run.json"
+      ],
+      "rule": "IDEs and CI must consume structured artifacts and verdict exit semantics rather than parse human help or terminal prose."
+    },
+    "docsAndDiagrams": {
+      "rule": "Documentation and diagrams must derive labels, ordering, and edges from this contract and must not invent implemented steps."
+    }
+  }
+}