rapidkit 0.38.0 → 0.40.0

package/README.md

@@ -148,6 +148,7 @@ For the visual experience, install the [Workspai VS Code extension](https://mark
 - [Typical workflows](#typical-workflows)
 - [Mental model](#mental-model)
 - [Workspace Intelligence Commands](#workspace-intelligence-commands)
+- [Agent Customization Pack](#agent-customization-pack)
 - [Requirements](#requirements)
 - [Install](#install)
 - [Project workflows](#project-workflows)
@@ -182,7 +183,8 @@ npx rapidkit workspace model --json
 
 ```bash
 npx rapidkit workspace context --for-agent --json --write
-npx rapidkit workspace agent-sync --write --refresh-context
+npx rapidkit workspace agent-sync --write --refresh-context --preset enterprise
+npx rapidkit workspace agent-sync --write --refresh-context --preset enterprise --experimental-hooks
 ```
 
 ### Release verification
@@ -237,52 +239,115 @@ Every tool gets the same answers: what projects exist, what stack they use, whic
 
 Workspace Intelligence provides a shared understanding of projects, dependencies, operational context, and release readiness for developers, CI pipelines, and AI agents.
 
-| Command                                          | Purpose                                                          |
-| ------------------------------------------------ | ---------------------------------------------------------------- |
-| `workspace model --json`                         | Canonical workspace model                                        |
-| `workspace context --for-agent --json --write`   | Agent-ready context pack + auto agent grounding sync             |
-| `workspace agent-sync --write`                   | Cross-tool grounding (AGENTS.md, Copilot, Cursor, Claude, INDEX) |
-| `workspace snapshot --json`                      | Persist model snapshot                                           |
-| `workspace diff --from <file\|git[:ref]> --json` | Diff against snapshot or git                                     |
-| `workspace impact --from <file> --json`          | Blast-radius evidence                                            |
-| `workspace verify [--strict] --json`             | Impact verification gate                                         |
+| Command                                           | Purpose                                                                              |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `workspace model [--cache\|--incremental] --json` | Canonical workspace model (graph-aware, incremental rebuilds)                        |
+| `workspace context --for-agent --json --write`    | Agent-ready context pack + auto agent grounding sync                                 |
+| `workspace agent-sync --write`                    | Agent Customization Pack (AGENTS.md, Copilot, Cursor, Claude, INDEX, skills, agents) |
+| `workspace snapshot --json`                       | Persist model snapshot                                                               |
+| `workspace diff --from <file\|git[:ref]> --json`  | Diff against snapshot or git                                                         |
+| `workspace impact --from <file> --json`           | Graph-aware transitive blast-radius evidence                                         |
+| `workspace verify [--strict] --json`              | Definitive verification gate (subgraph + freshness + policy)                         |
+| `workspace graph <emit\|explain\|dot\|mermaid>`   | Inspect and visualize the dependency graph                                           |
+| `workspace watch [--json] [--once]`               | Daemon mode: keep model + graph in memory, stream change events                      |
 
 JSON schemas: `contracts/workspace-intelligence/`. Details: [commands-reference.md](docs/commands-reference.md).
 
-### Agent grounding (CLI-only, no extension required)
-
-RapidKit can sync **cross-tool instruction files** so Copilot, Cursor, Claude Code, Codex, Grok, and other agents read the same evidence before guessing:
+### Graph-aware intelligence engine
+
+The workspace model carries a deterministic, first-class **dependency graph** that
+`impact`, `verify`, and `graph` all reason over — so the same evidence drives blast
+radius, gating, and visualization:
+
+- **Transitive blast radius** — `workspace impact` reports each affected project's
+  `distance`, `path`, and `via` edge back to the change, plus centrality-weighted
+  **critical-path hotspots**.
+- **Whole-subgraph gate** — `workspace verify` gates the changed projects **and** their
+  transitive dependents, surfaces graph **integrity** issues (cycles, dangling edges,
+  orphans), and emits a structured `gate` (`passed`/`mode`/`exitCode`/`reasons`).
+- **Transitive freshness** — a deterministic `fresh | stale | unknown` verdict chained
+  through the graph: a dependency change makes every dependent stale, not just by
+  timestamp.
+- **Policy violations** — model/contract violations are surfaced as structured
+  `policyViolations[]` (not just an exit code) so IDEs and CI can render blockers.
+- **Health history** — every verify run appends to a bounded
+  `.rapidkit/reports/workspace-intelligence-history.json` ring buffer for trends.
+- **Fast rebuilds** — `workspace model --cache` / `--incremental` reuse unchanged
+  project models and re-infer only incident edges, keyed by a structural `inputsHash`.
+- **Watch / daemon** — `workspace watch` keeps the model + graph in memory and streams
+  deterministic `workspace-watch-event.v1` change events (changed projects, graph edge
+  deltas, structural hash) via fast incremental rebuilds.
+
+### Agent Customization Pack
+
+RapidKit can generate a versioned **Agent Customization Pack** so AI tools do
+not start from an ungrounded repository scan. They start from the same workspace
+truth developers and CI use: reports, commands, contracts, blockers, scope, and
+verification evidence.
+
+This is CLI-only and does not require the Workspai extension:
 
 ```bash
-# Full sync: refresh context pack + INDEX + AGENTS.md + Copilot/Cursor/Claude hooks
-npx rapidkit workspace agent-sync --write --refresh-context
+# Full enterprise pack:
+# context pack + INDEX + AGENTS.md + Copilot/Cursor/Claude/Codex surfaces + MCP-ready design
+npx rapidkit workspace agent-sync --write --refresh-context --preset enterprise
+
+# Optional advisory VS Code agent hooks (disabled by default in the generated file)
+npx rapidkit workspace agent-sync --write --refresh-context --preset enterprise --experimental-hooks
 
 # Context pack write also syncs grounding by default
 npx rapidkit workspace context --for-agent --json --write
 
 # CI strict gate (fail if required reports missing/stale)
 npx rapidkit workspace agent-sync --write --strict --json
+
+# CI drift gate after sync
+npm run check:agent-customization-drift -- --workspace <workspace-root>
 ```
 
-| Artifact / file                                          | Purpose                                                 |
-| -------------------------------------------------------- | ------------------------------------------------------- |
-| `.rapidkit/reports/INDEX.json`                           | Read order, blockers, report timestamps                 |
-| `.rapidkit/reports/workspace-context-agent.json`         | Canonical agent context pack                            |
-| `.rapidkit/AGENT-GROUNDING.md`                           | Tool-agnostic grounding doc                             |
-| `AGENTS.md`                                              | Open standard for all agents (managed RapidKit section) |
-| `.github/copilot-instructions.md`                        | GitHub Copilot / VS Code Chat always-on rules           |
-| `.github/instructions/rapidkit-evidence.instructions.md` | Copilot scoped rules for `.rapidkit/**`                 |
-| `.github/prompts/rapidkit-diagnose.prompt.md`            | Copilot reusable diagnose prompt                        |
-| `.github/skills/rapidkit-grounding/SKILL.md`             | Copilot agent skill workflow                            |
-| `.cursor/rules/rapidkit-grounding.mdc`                   | Cursor always-on project rule                           |
-| `CLAUDE.md`                                              | Claude Code entry (`@AGENTS.md` + managed notes)        |
-| `.claude/rules/rapidkit-evidence.md`                     | Claude Code scoped evidence rules                       |
-
-Agents cannot be **forced** probabilistically — but this stack maximizes the chance they read reports first, even when the user talks to Copilot directly without Workspai.
+| Artifact / file                                                         | Purpose                                                  |
+| ----------------------------------------------------------------------- | -------------------------------------------------------- |
+| `.rapidkit/reports/agent-customization-pack.json`                       | Versioned output inventory, target matrix, drift state   |
+| `.rapidkit/reports/rapidkit-mcp-design.json`                            | Read-mostly MCP-ready tool design manifest               |
+| `.rapidkit/reports/INDEX.json`                                          | Read order, blockers, report timestamps                  |
+| `.rapidkit/reports/workspace-context-agent.json`                        | Canonical agent context pack                             |
+| `.rapidkit/AGENT-GROUNDING.md`                                          | Tool-agnostic grounding doc                              |
+| `AGENTS.md`                                                             | Open standard for all agents (managed RapidKit section)  |
+| `.github/copilot-instructions.md`                                       | GitHub Copilot / VS Code Chat always-on rules            |
+| `.github/instructions/rapidkit-workspace.instructions.md`               | Copilot workspace scope and command discipline           |
+| `.github/instructions/rapidkit-evidence.instructions.md`                | Copilot scoped rules for `.rapidkit/**`                  |
+| `.github/prompts/rapidkit-diagnose.prompt.md`                           | Copilot reusable diagnose prompt                         |
+| `.github/skills/rapidkit-workspace-intelligence/SKILL.md`               | Workspace Intelligence skill workflow                    |
+| `.github/skills/rapidkit-workspace-intelligence/resources/mcp-tools.md` | Future MCP tool design reference                         |
+| `.github/agents/workspai-advisor.agent.md`                              | Read-only workspace advisor agent                        |
+| `.github/agents/workspai-repair.agent.md`                               | Blocker repair agent                                     |
+| `.github/agents/workspai-release.agent.md`                              | Release safety agent                                     |
+| `.github/agents/workspai-project-onboarder.agent.md`                    | Project onboarding agent                                 |
+| `.cursor/rules/rapidkit-grounding.mdc`                                  | Cursor always-on project rule                            |
+| `CLAUDE.md`                                                             | Claude Code entry (`@AGENTS.md` + managed notes)         |
+| `.claude/rules/rapidkit-evidence.md`                                    | Claude Code scoped evidence rules                        |
+| `.vscode/rapidkit-agent-hooks.json`                                     | Optional advisory VS Code hooks (`--experimental-hooks`) |
+
+The pack also publishes a standard answer contract for agent-facing output:
+
+```text
+Scope -> Evidence -> Diagnosis -> Fix Plan -> Run -> Verify -> Assumptions
+```
+
+That contract is what keeps agent responses operational: every recommendation
+should name the workspace/project scope, cite the evidence it used, explain the
+diagnosis, propose the command or file action, and tell the user how to verify
+the result.
+
+Agents cannot be **forced** probabilistically. This stack makes the desired
+behavior explicit, versioned, and easy for IDEs, CI, and Workspai to audit.
 
 Skip auto-sync after context write: `--no-agent-sync`. Target specific ecosystems: `--target copilot,cursor,claude`.
 
-After `pipeline`, grounding syncs automatically (refresh context + INDEX + hooks). Disable with `--no-agent-sync` or `RAPIDKIT_NO_AGENT_SYNC=1`.
+After `pipeline`, grounding syncs automatically (refresh context + INDEX + agent surfaces). Disable with `--no-agent-sync` or `RAPIDKIT_NO_AGENT_SYNC=1`.
+
+Contract: `contracts/agent-customization-pack.v1.json`. Artifact map:
+[docs/contracts/ARTIFACT_CATALOG.md](docs/contracts/ARTIFACT_CATALOG.md).
 
 CI template: [docs/examples/ci-agent-grounding.yml](docs/examples/ci-agent-grounding.yml).
 

package/contracts/agent-customization-pack.v1.json

@@ -0,0 +1,159 @@
+{
+  "schemaVersion": "rapidkit-agent-customization-pack.v1",
+  "presets": {
+    "minimal": {
+      "meaning": "Generate the portable grounding index, AGENTS.md, and provider-specific lightweight instructions.",
+      "requiredOutputs": [
+        ".rapidkit/reports/INDEX.json",
+        ".rapidkit/reports/agent-customization-pack.json",
+        "AGENTS.md"
+      ]
+    },
+    "enterprise": {
+      "meaning": "Generate the full VS Code-native pack: instructions, prompts, skills, custom agents, and validation metadata.",
+      "requiredOutputs": [
+        ".rapidkit/reports/INDEX.json",
+        ".rapidkit/reports/agent-customization-pack.json",
+        "AGENTS.md",
+        ".github/instructions/rapidkit-workspace.instructions.md",
+        ".github/prompts/rapidkit-diagnose.prompt.md",
+        ".github/skills/rapidkit-workspace-intelligence/SKILL.md",
+        ".github/agents/workspai-advisor.agent.md",
+        ".rapidkit/reports/rapidkit-mcp-design.json"
+      ]
+    }
+  },
+  "targets": {
+    "all": {
+      "meaning": "Generate every supported customization surface.",
+      "outputFamilies": [
+        "portable",
+        "vscode",
+        "copilot",
+        "cursor",
+        "claude"
+      ]
+    },
+    "vscode": {
+      "meaning": "Generate VS Code-native customizations for Copilot Chat and agent workflows.",
+      "outputFamilies": [
+        "instructions",
+        "prompts",
+        "skills",
+        "agents",
+        "hooks"
+      ]
+    },
+    "agents": {
+      "meaning": "Generate portable AGENTS.md grounding for any agent.",
+      "outputFamilies": [
+        "portable"
+      ]
+    },
+    "copilot": {
+      "meaning": "Generate GitHub Copilot instructions, prompts, and skills.",
+      "outputFamilies": [
+        "instructions",
+        "prompts",
+        "skills"
+      ]
+    },
+    "cursor": {
+      "meaning": "Generate Cursor rules.",
+      "outputFamilies": [
+        "rules"
+      ]
+    },
+    "claude": {
+      "meaning": "Generate Claude Code grounding files.",
+      "outputFamilies": [
+        "rules",
+        "portable"
+      ]
+    },
+    "codex": {
+      "meaning": "Use AGENTS.md and the report index as the Codex grounding layer.",
+      "outputFamilies": [
+        "portable"
+      ]
+    },
+    "orca": {
+      "meaning": "Use AGENTS.md and the report index as the Orca/Grok grounding layer.",
+      "outputFamilies": [
+        "portable"
+      ]
+    }
+  },
+  "standardAnswerContract": [
+    "Scope",
+    "Evidence",
+    "Diagnosis",
+    "Fix Plan",
+    "Run",
+    "Verify",
+    "Assumptions"
+  ],
+  "requiredReports": [
+    {
+      "path": ".rapidkit/reports/workspace-context-agent.json",
+      "label": "Agent context pack",
+      "required": true
+    },
+    {
+      "path": ".rapidkit/reports/workspace-model.json",
+      "label": "Workspace model graph",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/doctor-last-run.json",
+      "label": "Workspace doctor",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/analyze-last-run.json",
+      "label": "Workspace analyze",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/pipeline-last-run.json",
+      "label": "Governance pipeline",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/release-readiness-last-run.json",
+      "label": "Release readiness",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-impact-last-run.json",
+      "label": "Workspace impact",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-verify-last-run.json",
+      "label": "Workspace verify",
+      "required": false
+    }
+  ],
+  "strictRules": [
+    "Required reports must exist.",
+    "Generated report paths must stay inside the workspace root.",
+    "Generated customization text must be English-only.",
+    "Agent answers must not claim pass, ready, or healthy without cited evidence.",
+    "Commands must distinguish display guidance from execution requests.",
+    "Agent hook files must be advisory and disabled by default unless the user explicitly enables them.",
+    "MCP design artifacts must stay read-mostly until write tools have explicit approval boundaries."
+  ],
+  "outputKinds": [
+    "report",
+    "grounding",
+    "instruction",
+    "prompt",
+    "skill",
+    "skill-resource",
+    "agent",
+    "rule",
+    "hook",
+    "mcp-design"
+  ]
+}

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

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": "rapidkit-extension-cli-compatibility.v1",
+  "cli": "rapidkit-npm",
+  "minimumVerifiedCliVersion": "0.40.0",
+  "publishedContractSchemas": {
+    "runtimeCommandSurface": "rapidkit-runtime-command-surface-v1",
+    "cliLogEvent": "cli-log-event-v1",
+    "freshnessMetadata": "rapidkit-freshness-metadata-v1"
+  }
+}

package/contracts/runtime-command-surface.v1.json

@@ -39,6 +39,39 @@
   "coreProjectCommands": [
     "docs"
   ],
+  "workspaceSubcommands": [
+    "list",
+    "sync",
+    "registry",
+    "foundation",
+    "model",
+    "snapshot",
+    "diff",
+    "impact",
+    "verify",
+    "graph",
+    "watch",
+    "context",
+    "agent-sync",
+    "policy",
+    "contract",
+    "share",
+    "export",
+    "archive",
+    "hydrate",
+    "import",
+    "run",
+    "init"
+  ],
+  "workspaceIntelligenceSubcommands": [
+    "model",
+    "snapshot",
+    "diff",
+    "impact",
+    "verify",
+    "context",
+    "agent-sync"
+  ],
   "moduleSuggestionFrameworks": [
     "fastapi",
     "nestjs"

package/contracts/workspace-intelligence/workspace-dependency-graph.v1.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-dependency-graph.v1.json",
+  "title": "RapidKit Workspace Dependency Graph",
+  "description": "First-class, versioned dependency graph of inter-project relationships consumed by impact, verify, run --blast-radius, and risk weighting.",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "nodes", "edges", "stats"],
+  "properties": {
+    "schemaVersion": {
+      "const": "workspace-dependency-graph.v1"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "path"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "path": { "type": "string", "minLength": 1 },
+          "runtime": { "type": "string" },
+          "framework": { "type": "string" },
+          "kind": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "kind", "source", "confidence", "evidence"],
+        "properties": {
+          "from": { "type": "string", "minLength": 1 },
+          "to": { "type": "string", "minLength": 1 },
+          "kind": {
+            "enum": [
+              "code-import",
+              "package-dep",
+              "event-pub-sub",
+              "service-dependsOn",
+              "shared-resource"
+            ]
+          },
+          "source": {
+            "enum": ["inferred", "contract", "manual"]
+          },
+          "confidence": {
+            "enum": ["high", "medium", "low"]
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["file"],
+              "properties": {
+                "file": { "type": "string", "minLength": 1 },
+                "detail": { "type": "string" }
+              },
+              "additionalProperties": true
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "stats": {
+      "type": "object",
+      "required": [
+        "nodeCount",
+        "edgeCount",
+        "inferredEdges",
+        "contractEdges",
+        "manualEdges",
+        "hasCycle"
+      ],
+      "properties": {
+        "nodeCount": { "type": "integer", "minimum": 0 },
+        "edgeCount": { "type": "integer", "minimum": 0 },
+        "inferredEdges": { "type": "integer", "minimum": 0 },
+        "contractEdges": { "type": "integer", "minimum": 0 },
+        "manualEdges": { "type": "integer", "minimum": 0 },
+        "hasCycle": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -11,6 +11,8 @@
     "workspace",
     "summary",
     "affectedProjects",
+    "transitiveImpact",
+    "criticalPathHotspots",
     "workspaceImpact",
     "verificationPlan",
     "agentBrief",
@@ -43,7 +45,8 @@
         "risk",
         "affectedProjects",
         "workspaceItems",
-        "recommendedCommands"
+        "recommendedCommands",
+        "blastRadius"
       ],
       "properties": {
         "changed": { "type": "boolean" },
@@ -52,11 +55,38 @@
         },
         "affectedProjects": { "type": "integer", "minimum": 0 },
         "workspaceItems": { "type": "integer", "minimum": 0 },
-        "recommendedCommands": { "type": "integer", "minimum": 0 }
+        "recommendedCommands": { "type": "integer", "minimum": 0 },
+        "blastRadius": {
+          "type": "object",
+          "required": ["directlyAffected", "transitivelyAffected", "maxDistance", "graphEdges"],
+          "properties": {
+            "directlyAffected": { "type": "integer", "minimum": 0 },
+            "transitivelyAffected": { "type": "integer", "minimum": 0 },
+            "maxDistance": { "type": "integer", "minimum": 0 },
+            "graphEdges": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
       },
       "additionalProperties": false
     },
     "affectedProjects": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
+    "transitiveImpact": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
+    "criticalPathHotspots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["project", "fanIn", "fanOut", "reach", "betweenness"],
+        "properties": {
+          "project": { "type": "string" },
+          "fanIn": { "type": "integer", "minimum": 0 },
+          "fanOut": { "type": "integer", "minimum": 0 },
+          "reach": { "type": "integer", "minimum": 0 },
+          "betweenness": { "type": "number", "minimum": 0 }
+        },
+        "additionalProperties": true
+      }
+    },
     "workspaceImpact": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
     "verificationPlan": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
     "agentBrief": {

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

@@ -41,6 +41,11 @@
       "items": { "type": "object", "additionalProperties": true }
     },
     "contracts": { "type": "object", "additionalProperties": true },
+    "graph": {
+      "type": "object",
+      "description": "First-class inferred dependency graph (workspace-dependency-graph.v1). Additive/optional.",
+      "additionalProperties": true
+    },
     "evidence": { "type": "object", "additionalProperties": true },
     "discovery": { "type": "object", "additionalProperties": true },
     "policies": { "type": "object", "additionalProperties": true },

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

@@ -13,7 +13,12 @@
     "steps",
     "missingEvidence",
     "blockingReasons",
-    "verificationPlan"
+    "verificationPlan",
+    "affectedSubgraph",
+    "graphIntegrity",
+    "freshness",
+    "policyMode",
+    "policyViolations"
   ],
   "properties": {
     "schemaVersion": {
@@ -105,6 +110,103 @@
     "verificationPlan": {
       "type": "array",
       "items": { "type": "object", "additionalProperties": true }
+    },
+    "affectedSubgraph": {
+      "type": "object",
+      "required": [
+        "totalProjects",
+        "directlyChanged",
+        "transitiveDependents",
+        "covered",
+        "uncovered",
+        "unverifiable"
+      ],
+      "properties": {
+        "totalProjects": { "type": "integer", "minimum": 0 },
+        "directlyChanged": { "type": "array", "items": { "type": "string" } },
+        "transitiveDependents": { "type": "array", "items": { "type": "string" } },
+        "covered": { "type": "array", "items": { "type": "string" } },
+        "uncovered": { "type": "array", "items": { "type": "string" } },
+        "unverifiable": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "graphIntegrity": {
+      "type": "object",
+      "required": ["ok", "cycles", "danglingEdges", "orphans", "stats"],
+      "properties": {
+        "ok": { "type": "boolean" },
+        "cycles": {
+          "type": "array",
+          "items": { "type": "array", "items": { "type": "string" } }
+        },
+        "danglingEdges": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["from", "to", "kind", "missing"],
+            "properties": {
+              "from": { "type": "string" },
+              "to": { "type": "string" },
+              "kind": { "type": "string" },
+              "missing": { "enum": ["from", "to", "both"] }
+            },
+            "additionalProperties": true
+          }
+        },
+        "orphans": { "type": "array", "items": { "type": "string" } },
+        "stats": {
+          "type": "object",
+          "required": [
+            "nodeCount",
+            "edgeCount",
+            "cycleCount",
+            "danglingCount",
+            "orphanCount"
+          ],
+          "properties": {
+            "nodeCount": { "type": "integer", "minimum": 0 },
+            "edgeCount": { "type": "integer", "minimum": 0 },
+            "cycleCount": { "type": "integer", "minimum": 0 },
+            "danglingCount": { "type": "integer", "minimum": 0 },
+            "orphanCount": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "freshness": {
+      "type": "object",
+      "required": ["verdict", "baseline", "changed", "added", "removed", "projectHashes"],
+      "properties": {
+        "verdict": { "enum": ["fresh", "stale", "unknown"] },
+        "baseline": { "enum": ["none", "recorded"] },
+        "changed": { "type": "array", "items": { "type": "string" } },
+        "added": { "type": "array", "items": { "type": "string" } },
+        "removed": { "type": "array", "items": { "type": "string" } },
+        "projectHashes": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "policyMode": { "type": "string" },
+    "policyViolations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "severity", "code", "message"],
+        "properties": {
+          "source": { "enum": ["model", "contract"] },
+          "severity": { "enum": ["error", "warning"] },
+          "code": { "type": "string" },
+          "message": { "type": "string" },
+          "target": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
     }
   },
   "additionalProperties": true