Workspai Project Context for Agents

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://workspai.dev/schemas/workspace-intelligence/project-context-agent.v1.json",
  "title": "Workspai Project Context for Agents",
  "description": "Portable, bounded project lens derived from the canonical Workspace Model and evidence-backed Knowledge Graph.",
  "type": "object",
  "required": [
    "schemaVersion",
    "generatedAt",
    "workspace",
    "project",
    "intelligence",
    "evidence",
    "blockers",
    "agentRouting",
    "commands",
    "integrity"
  ],
  "properties": {
    "schemaVersion": {
      "const": "project-context-agent.v1"
    },
    "generatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "workspace": {
      "type": "object",
      "required": [
        "name",
        "relationship",
        "contract",
        "access"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "profile": {
          "type": "string"
        },
        "relationship": {
          "enum": [
            "managed",
            "adopted",
            "imported",
            "linked",
            "restored"
          ]
        },
        "contract": {
          "const": "workspace:.workspai/workspace.contract.json"
        },
        "projectKnowledgeGraph": {
          "const": ".workspai/reports/project-knowledge-graph-reference.json"
        },
        "model": {
          "const": "workspace:.workspai/reports/workspace-model.json"
        },
        "knowledgeGraph": {
          "const": "workspace:.workspai/reports/workspace-knowledge-graph.json"
        },
        "index": {
          "const": "workspace:.workspai/reports/INDEX.json"
        },
        "context": {
          "const": "workspace:.workspai/reports/workspace-context-agent.json"
        },
        "skillsIndex": {
          "const": "workspace:.workspai/reports/workspace-skills-index.json"
        },
        "boundedGraphSearch": {
          "type": "string",
          "minLength": 1
        },
        "access": {
          "type": "object",
          "required": [
            "localBinding",
            "canonicalEvidenceAvailableAtGeneration",
            "identityIsFilesystemPath",
            "resolverCommand",
            "portableUriScheme",
            "resolvedPathPolicy"
          ],
          "properties": {
            "localBinding": {
              "const": ".workspai/workspace-link.local.json"
            },
            "canonicalEvidenceAvailableAtGeneration": {
              "type": "boolean"
            },
            "identityIsFilesystemPath": {
              "const": false
            },
            "resolverCommand": {
              "const": "workspai project workspace status --json"
            },
            "portableUriScheme": {
              "const": "workspace:"
            },
            "resolvedPathPolicy": {
              "const": "runtime-private-never-persist"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false,
      "anyOf": [
        {
          "properties": {
            "model": {
              "const": "workspace:.workspai/reports/workspace-model.json"
            },
            "knowledgeGraph": {
              "const": "workspace:.workspai/reports/workspace-knowledge-graph.json"
            }
          },
          "required": [
            "model",
            "knowledgeGraph"
          ]
        },
        {
          "properties": {
            "index": {
              "const": "workspace:.workspai/reports/INDEX.json"
            },
            "context": {
              "const": "workspace:.workspai/reports/workspace-context-agent.json"
            },
            "skillsIndex": {
              "const": "workspace:.workspai/reports/workspace-skills-index.json"
            },
            "boundedGraphSearch": {
              "type": "string",
              "minLength": 1
            }
          },
          "required": [
            "index",
            "context",
            "skillsIndex",
            "boundedGraphSearch"
          ]
        }
      ]
    },
    "project": {
      "type": "object",
      "required": [
        "name",
        "relativePath",
        "commands",
        "importantFiles"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "relativePath": {
          "type": "string",
          "minLength": 1,
          "not": {
            "pattern": "^(?:/|[A-Za-z]:[\\\\/])"
          }
        },
        "kind": {
          "type": "string"
        },
        "runtime": {
          "type": "string"
        },
        "runtimeCandidates": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "uniqueItems": true
        },
        "framework": {
          "type": "string"
        },
        "kit": {
          "type": "string"
        },
        "supportTier": {
          "type": "string"
        },
        "governance": {
          "$ref": "#/$defs/projectGovernance"
        },
        "commands": {
          "type": "object",
          "required": [
            "supported",
            "unsupported",
            "fleetStages"
          ],
          "properties": {
            "supported": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "uniqueItems": true
            },
            "unsupported": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "uniqueItems": true
            },
            "fleetStages": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "uniqueItems": true
            }
          },
          "additionalProperties": false
        },
        "importantFiles": {
          "type": "array",
          "items": {
            "type": "string",
            "not": {
              "pattern": "^(?:/|[A-Za-z]:[\\\\/])"
            }
          },
          "uniqueItems": true
        }
      },
      "additionalProperties": false
    },
    "intelligence": {
      "type": "object",
      "required": [
        "entityCount",
        "relationCount",
        "proofCount",
        "entitiesByKind",
        "relationsByKind",
        "languages",
        "semantic",
        "projection",
        "relatedProjects",
        "freshness",
        "topology",
        "surfaces",
        "diagnostics"
      ],
      "properties": {
        "modelGeneratedAt": {
          "type": "string",
          "format": "date-time"
        },
        "graphGeneratedAt": {
          "type": "string",
          "format": "date-time"
        },
        "graphModelHash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "entityCount": {
          "type": "integer",
          "minimum": 0
        },
        "relationCount": {
          "type": "integer",
          "minimum": 0
        },
        "proofCount": {
          "type": "integer",
          "minimum": 0
        },
        "entitiesByKind": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "relationsByKind": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "languages": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "required": [
              "fileCount",
              "symbolCount",
              "generatedFileCount"
            ],
            "properties": {
              "fileCount": {
                "type": "integer",
                "minimum": 0
              },
              "symbolCount": {
                "type": "integer",
                "minimum": 0
              },
              "generatedFileCount": {
                "type": "integer",
                "minimum": 0
              }
            },
            "additionalProperties": false
          }
        },
        "semantic": {
          "type": "object",
          "required": [
            "protocolConceptCount",
            "protocolImplementationBindings",
            "equivalenceBindings",
            "generationBindings",
            "runtimeUnitCount",
            "lifecycleStageCount",
            "runtimeCoverage"
          ],
          "properties": {
            "protocolConceptCount": {
              "type": "integer",
              "minimum": 0
            },
            "protocolImplementationBindings": {
              "type": "integer",
              "minimum": 0
            },
            "equivalenceBindings": {
              "type": "integer",
              "minimum": 0
            },
            "generationBindings": {
              "type": "integer",
              "minimum": 0
            },
            "runtimeUnitCount": {
              "type": "integer",
              "minimum": 0
            },
            "lifecycleStageCount": {
              "type": "integer",
              "minimum": 0
            },
            "runtimeCoverage": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "uniqueItems": true
            }
          },
          "additionalProperties": false
        },
        "projection": {
          "description": "Observable bounds for the representative entity projection. Counts remain exhaustive; omitted entities are available through bounded graph search.",
          "type": "object",
          "required": [
            "mode",
            "maxEntities",
            "byteBudget",
            "selectedBytes",
            "eligibleCount",
            "selectedCount",
            "omittedCount",
            "selectedByKind",
            "omittedByKind",
            "continuationCommand"
          ],
          "properties": {
            "mode": {
              "const": "stratified-byte-bounded"
            },
            "maxEntities": {
              "type": "integer",
              "minimum": 1
            },
            "byteBudget": {
              "type": "integer",
              "minimum": 1
            },
            "selectedBytes": {
              "type": "integer",
              "minimum": 0
            },
            "eligibleCount": {
              "type": "integer",
              "minimum": 0
            },
            "selectedCount": {
              "type": "integer",
              "minimum": 0
            },
            "omittedCount": {
              "type": "integer",
              "minimum": 0
            },
            "selectedByKind": {
              "type": "object",
              "additionalProperties": {
                "type": "integer",
                "minimum": 0
              }
            },
            "omittedByKind": {
              "type": "object",
              "additionalProperties": {
                "type": "integer",
                "minimum": 1
              }
            },
            "continuationCommand": {
              "type": "string",
              "minLength": 1
            }
          },
          "additionalProperties": false
        },
        "relatedProjects": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "freshness": {
          "type": "object",
          "required": [
            "model",
            "graph",
            "graphMatchesModel"
          ],
          "properties": {
            "model": {
              "enum": [
                "fresh",
                "stale",
                "unknown",
                "missing"
              ]
            },
            "graph": {
              "enum": [
                "fresh",
                "stale",
                "unknown",
                "missing"
              ]
            },
            "graphMatchesModel": {
              "type": "boolean"
            }
          },
          "additionalProperties": false
        },
        "topology": {
          "type": "object",
          "required": [
            "status",
            "dependencies",
            "dependents"
          ],
          "properties": {
            "status": {
              "enum": [
                "proven",
                "unproven",
                "unavailable"
              ]
            },
            "dependencies": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/topologyRelation"
              },
              "maxItems": 16
            },
            "dependents": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/topologyRelation"
              },
              "maxItems": 16
            }
          },
          "additionalProperties": false
        },
        "surfaces": {
          "type": "object",
          "required": [
            "services",
            "packages",
            "protocols",
            "runtimeUnits",
            "lifecycleStages",
            "apis",
            "endpoints",
            "dataStores",
            "deployments",
            "pipelines",
            "tests",
            "owners",
            "decisions",
            "ports"
          ],
          "properties": {
            "services": {
              "$ref": "#/$defs/entityList"
            },
            "packages": {
              "$ref": "#/$defs/entityList"
            },
            "protocols": {
              "$ref": "#/$defs/entityList"
            },
            "runtimeUnits": {
              "$ref": "#/$defs/entityList"
            },
            "lifecycleStages": {
              "$ref": "#/$defs/entityList"
            },
            "apis": {
              "$ref": "#/$defs/entityList"
            },
            "endpoints": {
              "$ref": "#/$defs/entityList"
            },
            "dataStores": {
              "$ref": "#/$defs/entityList"
            },
            "deployments": {
              "$ref": "#/$defs/entityList"
            },
            "pipelines": {
              "$ref": "#/$defs/entityList"
            },
            "tests": {
              "$ref": "#/$defs/entityList"
            },
            "owners": {
              "$ref": "#/$defs/entityList"
            },
            "decisions": {
              "$ref": "#/$defs/entityList"
            },
            "ports": {
              "type": "array",
              "maxItems": 8,
              "items": {
                "$ref": "#/$defs/port"
              }
            }
          },
          "additionalProperties": false
        },
        "diagnostics": {
          "type": "array",
          "maxItems": 16,
          "items": {
            "type": "object",
            "required": [
              "code",
              "severity",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "severity": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "recommendation": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "evidence": {
      "type": "object",
      "required": [
        "readOrder",
        "projectProofArtifacts",
        "relations",
        "proofs"
      ],
      "properties": {
        "readOrder": {
          "type": "array",
          "maxItems": 12,
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "projectProofArtifacts": {
          "type": "array",
          "items": {
            "type": "string",
            "not": {
              "pattern": "^(?:/|[A-Za-z]:[\\\\/])"
            }
          },
          "uniqueItems": true,
          "maxItems": 24
        },
        "relations": {
          "type": "array",
          "maxItems": 16,
          "items": {
            "$ref": "#/$defs/relation"
          }
        },
        "proofs": {
          "type": "array",
          "maxItems": 16,
          "items": {
            "$ref": "#/$defs/proof"
          }
        }
      },
      "additionalProperties": false
    },
    "blockers": {
      "type": "array",
      "maxItems": 32,
      "items": {
        "$ref": "#/$defs/blocker"
      }
    },
    "agentRouting": {
      "description": "Machine-readable mandatory routing policy that prevents agents from bypassing canonical workspace evidence.",
      "type": "object",
      "required": [
        "enforcement",
        "mandatoryPreflight",
        "workspaceLocator",
        "workspaceEvidenceRequiredFor",
        "requiredReadOrder",
        "degradedMode"
      ],
      "properties": {
        "enforcement": {
          "const": "required"
        },
        "mandatoryPreflight": {
          "type": "object",
          "required": [
            "command",
            "successCondition"
          ],
          "properties": {
            "command": {
              "const": "workspai agent bootstrap --for-agent generic --strict --json"
            },
            "successCondition": {
              "const": "ready"
            }
          },
          "additionalProperties": false
        },
        "workspaceLocator": {
          "type": "object",
          "required": [
            "command",
            "successCondition",
            "outputClassification",
            "persistence",
            "disclosure",
            "portableUriScheme"
          ],
          "properties": {
            "command": {
              "const": "workspai project workspace status --json"
            },
            "successCondition": {
              "const": "resolved"
            },
            "outputClassification": {
              "const": "machine-local"
            },
            "persistence": {
              "const": "forbidden"
            },
            "disclosure": {
              "const": "forbidden"
            },
            "portableUriScheme": {
              "const": "workspace:"
            }
          },
          "additionalProperties": false
        },
        "workspaceEvidenceRequiredFor": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "enum": [
              "repository-analysis",
              "architecture-analysis",
              "change-impact",
              "cross-project-change",
              "contract-change",
              "infrastructure-change",
              "release-readiness"
            ]
          }
        },
        "requiredReadOrder": {
          "type": "array",
          "minItems": 4,
          "maxItems": 10,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "degradedMode": {
          "type": "object",
          "required": [
            "allowCompleteArchitectureClaims",
            "requireDisclosure"
          ],
          "properties": {
            "allowCompleteArchitectureClaims": {
              "const": false
            },
            "requireDisclosure": {
              "const": true
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "commands": {
      "type": "object",
      "required": [
        "refresh",
        "verify",
        "graphSearch",
        "doctor",
        "workspaceStatus"
      ],
      "properties": {
        "refresh": {
          "type": "string",
          "minLength": 1
        },
        "verify": {
          "type": "string",
          "minLength": 1
        },
        "graphSearch": {
          "type": "string",
          "minLength": 1
        },
        "doctor": {
          "type": "string",
          "minLength": 1
        },
        "workspaceStatus": {
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false
    },
    "integrity": {
      "type": "object",
      "required": [
        "algorithm",
        "payloadHash",
        "portable",
        "absolutePathsEmitted"
      ],
      "properties": {
        "algorithm": {
          "const": "sha256"
        },
        "modelHash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "payloadHash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "portable": {
          "const": true
        },
        "absolutePathsEmitted": {
          "const": false
        }
      },
      "additionalProperties": false
    }
  },
  "$defs": {
    "governanceControl": {
      "type": "object",
      "required": [
        "status",
        "provider",
        "evidence",
        "reference"
      ],
      "properties": {
        "status": {
          "enum": [
            "repository",
            "external-declared",
            "external-observed",
            "unknown"
          ]
        },
        "provider": {
          "type": [
            "string",
            "null"
          ]
        },
        "evidence": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "uniqueItems": true
        },
        "reference": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "projectGovernance": {
      "type": "object",
      "required": [
        "schemaVersion",
        "ci",
        "release",
        "ownership"
      ],
      "properties": {
        "schemaVersion": {
          "const": "workspai.project-governance.v1"
        },
        "ci": {
          "$ref": "#/$defs/governanceControl"
        },
        "release": {
          "$ref": "#/$defs/governanceControl"
        },
        "ownership": {
          "$ref": "#/$defs/governanceControl"
        }
      },
      "additionalProperties": false
    },
    "portableString": {
      "type": "string",
      "not": {
        "pattern": "^(?:/|[A-Za-z]:[\\\\/])"
      }
    },
    "topologyRelation": {
      "type": "object",
      "required": [
        "project",
        "kind",
        "source",
        "confidence",
        "evidence"
      ],
      "properties": {
        "project": {
          "type": "string",
          "minLength": 1
        },
        "kind": {
          "type": "string",
          "minLength": 1
        },
        "source": {
          "type": "string",
          "minLength": 1
        },
        "confidence": {
          "type": "string",
          "minLength": 1
        },
        "evidence": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/portableString"
          },
          "uniqueItems": true
        }
      },
      "additionalProperties": false
    },
    "entityList": {
      "type": "array",
      "maxItems": 32,
      "items": {
        "$ref": "#/$defs/entity"
      }
    },
    "entity": {
      "type": "object",
      "required": [
        "id",
        "kind",
        "label",
        "attributes",
        "proofIds"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "attributes": {
          "type": "object",
          "additionalProperties": true
        },
        "proofIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        }
      },
      "additionalProperties": false
    },
    "port": {
      "type": "object",
      "required": [
        "entityId",
        "label",
        "attribute",
        "value"
      ],
      "properties": {
        "entityId": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "attribute": {
          "type": "string"
        },
        "value": true
      },
      "additionalProperties": false
    },
    "relation": {
      "type": "object",
      "required": [
        "id",
        "from",
        "to",
        "kind",
        "derivation",
        "trust",
        "confidence",
        "proofIds"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        },
        "kind": {
          "type": "string"
        },
        "derivation": {
          "type": "string"
        },
        "trust": {
          "type": "string"
        },
        "confidence": {
          "type": "string"
        },
        "proofIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        }
      },
      "additionalProperties": false
    },
    "proof": {
      "type": "object",
      "required": [
        "id",
        "provider",
        "artifact",
        "derivation",
        "trust",
        "confidence",
        "freshness"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "provider": {
          "type": "string"
        },
        "artifact": {
          "$ref": "#/$defs/portableString"
        },
        "pointer": {
          "type": "string"
        },
        "line": {
          "type": "integer",
          "minimum": 1
        },
        "derivation": {
          "type": "string"
        },
        "trust": {
          "type": "string"
        },
        "confidence": {
          "type": "string"
        },
        "freshness": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "blocker": {
      "type": "object",
      "required": [
        "source",
        "severity",
        "message"
      ],
      "properties": {
        "source": {
          "type": "string"
        },
        "severity": {
          "enum": [
            "warning",
            "error"
          ]
        },
        "message": {
          "type": "string"
        },
        "code": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}