feat/onboarding-control-plane-contracts

schemas/AutomationTemplate.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/AutomationTemplate.json",
+  "title": "AutomationTemplate",
+  "description": "A reusable scheduled or event-driven SourceOS/SociOS work-product template. AutomationTemplate binds trigger semantics, required capability packs, required permissions, output artifacts, and receipt requirements for recurring governed agent work.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "name",
+    "category",
+    "trigger",
+    "requiredCapabilityPackRefs",
+    "requiredPermissionRefs",
+    "defaultTimeWindow",
+    "outputs",
+    "receiptRequired"
+  ],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:automation-template:" },
+    "type": { "const": "AutomationTemplate" },
+    "specVersion": { "type": "string" },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "category": {
+      "enum": [
+        "statusReports",
+        "releasePrep",
+        "incidentsAndTriage",
+        "codeQuality",
+        "repoMaintenance",
+        "securityCompliance",
+        "fogstackOperations",
+        "sourceosWorkstation",
+        "knowledgeOffice",
+        "researchCurriculum",
+        "communityGrowth",
+        "custom"
+      ]
+    },
+    "trigger": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["manual", "schedule", "event", "condition"] },
+        "schedule": { "type": ["string", "null"], "description": "Cron, RRULE, or platform schedule reference when kind=schedule." },
+        "eventRef": { "type": ["string", "null"], "description": "Event type, topic, webhook, or signal reference when kind=event." },
+        "condition": { "type": ["string", "null"], "description": "Human-readable or policy-evaluable condition when kind=condition." }
+      }
+    },
+    "requiredCapabilityPackRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:capability-pack:" }
+    },
+    "requiredConnectorActionScopeRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:connector-action-scope:" }
+    },
+    "requiredPermissionRefs": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "defaultTimeWindow": {
+      "type": "string",
+      "description": "Default temporal scope such as previous_day, previous_week, since_last_run, last_ci_window, or explicit duration syntax."
+    },
+    "outputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "name"],
+        "properties": {
+          "kind": { "type": "string" },
+          "name": { "type": "string" },
+          "required": { "type": "boolean", "default": true }
+        }
+      }
+    },
+    "mustInclude": { "type": "array", "items": { "type": "string" } },
+    "mustExclude": { "type": "array", "items": { "type": "string" } },
+    "receiptRequired": { "type": "boolean" },
+    "riskLevel": { "enum": ["low", "medium", "high", "critical"], "default": "medium" },
+    "policyRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:policy:" } }
+  }
+}

schemas/CapabilityPack.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/CapabilityPack.json",
+  "title": "CapabilityPack",
+  "description": "A curated SourceOS/SociOS product capability bundle. CapabilityPack composes one or more SkillManifest entries, connector action scopes, permission requirements, expected artifacts, and receipt requirements into a user-visible onboarding/catalog unit.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "name",
+    "version",
+    "publisher",
+    "category",
+    "skillRefs",
+    "requiredConnectorActionScopeRefs",
+    "requiredPermissionRefs",
+    "riskLevel",
+    "artifactOutputs",
+    "receiptRequired",
+    "revocation"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:capability-pack:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:capability-pack:<local-id>"
+    },
+    "type": {
+      "const": "CapabilityPack",
+      "description": "Discriminator constant — always \"CapabilityPack\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.1.0\"."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable pack name shown in onboarding, catalog, project, and automation surfaces."
+    },
+    "version": {
+      "type": "string",
+      "description": "SemVer version for this capability-pack declaration."
+    },
+    "description": {
+      "type": "string",
+      "description": "Short explanation of the workflow this pack enables."
+    },
+    "publisher": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "trustLevel", "signatureRequired"],
+      "properties": {
+        "name": { "type": "string" },
+        "trustLevel": { "enum": ["firstParty", "trustedPartner", "community", "local", "unknown"] },
+        "signatureRequired": { "type": "boolean" },
+        "signatureRef": { "type": ["string", "null"] }
+      },
+      "description": "Publisher and signing posture for the capability pack."
+    },
+    "category": {
+      "enum": [
+        "office",
+        "repoOrchestration",
+        "research",
+        "evidenceCapture",
+        "securityForensics",
+        "osBuild",
+        "fogstackDeployment",
+        "legalEntityIntelligence",
+        "curriculum",
+        "dataScience",
+        "designReview",
+        "operations",
+        "automation",
+        "actuator",
+        "custom"
+      ],
+      "description": "Catalog category used for filtering and onboarding recommendations."
+    },
+    "skillRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:skill:" },
+      "description": "SkillManifest URNs composed by this pack."
+    },
+    "requiredConnectorActionScopeRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:connector-action-scope:" },
+      "description": "Connector action scopes required or requested by this pack."
+    },
+    "requiredPermissionRefs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Permission identifiers required by this pack, such as filesystem.read, artifact.write, github.pr.read, or command.run.scoped."
+    },
+    "compatibleTrustModeRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:trust-mode:" },
+      "description": "Trust modes under which this pack is allowed to run by default."
+    },
+    "forbiddenTrustModeRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:trust-mode:" },
+      "description": "Trust modes under which this pack must not run."
+    },
+    "riskLevel": {
+      "enum": ["low", "medium", "high", "critical"],
+      "description": "Risk tier shown in UI and used by policy gates."
+    },
+    "artifactOutputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "name"],
+        "properties": {
+          "kind": { "type": "string" },
+          "name": { "type": "string" },
+          "required": { "type": "boolean", "default": true }
+        }
+      },
+      "description": "Artifacts this pack is expected to create, such as reports, receipts, PR drafts, manifests, or review summaries."
+    },
+    "receiptRequired": {
+      "type": "boolean",
+      "description": "Whether sessions using this pack must emit a receipt."
+    },
+    "revocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["revocable", "revokeDeletesLocalIndex", "revokeDisablesAutomations"],
+      "properties": {
+        "revocable": { "type": "boolean" },
+        "revokeDeletesLocalIndex": { "type": "boolean" },
+        "revokeDisablesAutomations": { "type": "boolean" },
+        "revocationNotes": { "type": "string" }
+      },
+      "description": "How disabling this capability pack affects local indexes, scheduled work, and future tool activation."
+    },
+    "policyRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:policy:" },
+      "description": "Policies governing activation, execution, and revocation of this pack."
+    }
+  }
+}

schemas/TrustMode.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/TrustMode.json",
+  "title": "TrustMode",
+  "description": "A named permission envelope for SourceOS/SociOS agent sessions. TrustMode translates user-visible operating modes such as Observe Only, Read-Only Analyst, Repo Contributor, or Agent Sandbox into explicit filesystem, execution, network, connector, scheduling, indexing, and publication permissions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "name",
+    "category",
+    "permissions",
+    "defaultExecutionSurfaceRef",
+    "requiresHumanApproval",
+    "receiptRequired"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:trust-mode:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:trust-mode:<local-id>"
+    },
+    "type": {
+      "const": "TrustMode",
+      "description": "Discriminator constant — always \"TrustMode\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.1.0\"."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable trust mode label shown in onboarding, composer footers, and policy panels."
+    },
+    "category": {
+      "enum": [
+        "observeOnly",
+        "readOnlyAnalyst",
+        "draftOnlyAssistant",
+        "repoContributor",
+        "localOperator",
+        "agentSandbox",
+        "privilegedMaintainer",
+        "custom"
+      ],
+      "description": "Canonical trust-mode category."
+    },
+    "summary": {
+      "type": "string",
+      "description": "Short user-facing explanation of what this trust mode permits and forbids."
+    },
+    "permissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "filesystemRead",
+        "filesystemWrite",
+        "commandRun",
+        "networkEgress",
+        "connectorRead",
+        "connectorWrite",
+        "messageSend",
+        "publishExternal",
+        "indexPersist",
+        "scheduleCreate",
+        "deleteOrDestructiveAction"
+      ],
+      "properties": {
+        "filesystemRead": { "type": "boolean" },
+        "filesystemWrite": { "enum": ["none", "draftOnly", "scoped", "workspace", "unrestricted"] },
+        "commandRun": { "enum": ["none", "diagnosticOnly", "scoped", "unrestricted"] },
+        "networkEgress": { "enum": ["none", "allowlist", "connectorOnly", "full"] },
+        "connectorRead": { "type": "boolean" },
+        "connectorWrite": { "enum": ["none", "draftOnly", "scoped", "full"] },
+        "messageSend": { "enum": ["none", "draftOnly", "explicitApproval", "allowed"] },
+        "publishExternal": { "enum": ["none", "explicitApproval", "allowed"] },
+        "indexPersist": { "type": "boolean" },
+        "scheduleCreate": { "type": "boolean" },
+        "deleteOrDestructiveAction": { "enum": ["none", "explicitApproval", "allowed"] },
+        "computerUse": { "enum": ["none", "observeOnly", "sandboxedControl", "explicitApprovalControl"], "default": "none" },
+        "browserUse": { "enum": ["none", "isolatedRead", "isolatedInteractive", "credentialedExplicitApproval"], "default": "none" }
+      },
+      "description": "User-visible verb permissions. These are intentionally explicit so the UI never collapses trust into an opaque label."
+    },
+    "defaultExecutionSurfaceRef": {
+      "type": ["string", "null"],
+      "pattern": "^urn:srcos:surface:",
+      "description": "Optional default ExecutionSurface URN used when creating AgentSession.surface for this trust mode."
+    },
+    "requiresHumanApproval": {
+      "type": "boolean",
+      "description": "Whether one or more actions under this mode require explicit human approval before execution."
+    },
+    "approvalProfileRef": {
+      "type": ["string", "null"],
+      "description": "Optional approval-profile identifier or URN used by shell/runtime policy gates."
+    },
+    "receiptRequired": {
+      "type": "boolean",
+      "description": "Whether sessions using this trust mode must emit a receipt."
+    },
+    "riskLevel": {
+      "enum": ["low", "medium", "high", "critical"],
+      "default": "medium",
+      "description": "Risk tier shown in capability and onboarding surfaces."
+    },
+    "policyRefs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^urn:srcos:policy:" },
+      "description": "Policies governing this trust mode."
+    }
+  }
+}