From 3e26efde5f7863c188dd28ef23f9afb9c4279284 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:11:02 -0400
Subject: [PATCH 01/19] Add onboarding WorkspaceScope schema

---
 schemas/WorkspaceScope.json | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 schemas/WorkspaceScope.json

diff --git a/schemas/WorkspaceScope.json b/schemas/WorkspaceScope.json
new file mode 100644
index 0000000..b261006
--- /dev/null
+++ b/schemas/WorkspaceScope.json
@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/WorkspaceScope.json",
+  "title": "WorkspaceScope",
+  "description": "A bounded workspace, project, folder, repository, organization, fog workspace, or sandbox selected for a SourceOS/SociOS agent session. Captures read, write, index, execution, artifact, connector, and policy boundaries before capabilities are activated.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "workspaceKind", "displayName", "rootRef", "mountMode", "allowedReadRefs", "allowedWriteRefs", "excludedRefs", "indexingPolicy", "secretScanPolicy", "artifactRootRef"],
+  "properties": {
+    "id": {"type": "string", "pattern": "^urn:srcos:workspace-scope:", "description": "Stable URN identifier. Pattern: urn:srcos:workspace-scope:<local-id>"},
+    "type": {"const": "WorkspaceScope", "description": "Discriminator constant — always \"WorkspaceScope\"."},
+    "specVersion": {"type": "string", "description": "Spec version of this document, e.g. \"2.0.0\"."},
+    "workspaceKind": {"enum": ["none", "localFolder", "gitRepository", "projectGraph", "organizationWorkspace", "fogWorkspace", "osBuildWorkspace", "ephemeralSandbox", "custom"], "description": "The workspace class selected during onboarding or session setup."},
+    "displayName": {"type": "string", "description": "Human-readable workspace label shown in the shell UI."},
+    "rootRef": {"type": "string", "description": "Opaque path, URI, URN, repository, or workspace reference. Local UIs may redact this when serialized externally."},
+    "mountMode": {"enum": ["noAccess", "readOnly", "draftOnly", "scopedWrite", "fullWorkspace", "sandboxCopy"], "description": "How the workspace is exposed to the agent runtime."},
+    "allowedReadRefs": {"type": "array", "items": {"type": "string"}, "description": "Paths, globs, URNs, or refs the agent may read. Empty means no read access unless mountMode semantics say otherwise."},
+    "allowedWriteRefs": {"type": "array", "items": {"type": "string"}, "description": "Paths, globs, URNs, or refs the agent may write. Empty means no direct workspace writes."},
+    "excludedRefs": {"type": "array", "items": {"type": "string"}, "description": "Refs blocked regardless of broader grants, such as secrets, build outputs, dependency caches, and private credentials."},
+    "worktreeRef": {"type": ["string", "null"], "description": "Optional branch/worktree reference when the workspace is a repository checkout."},
+    "branchPolicy": {"type": "object", "additionalProperties": false, "properties": {"baseRef": {"type": ["string", "null"]}, "headRef": {"type": ["string", "null"]}, "allowedPushRefs": {"type": "array", "items": {"type": "string"}}, "requiresPullRequest": {"type": "boolean"}}, "description": "Optional branch/worktree policy for code-capable sessions."},
+    "indexingPolicy": {"enum": ["disabled", "ephemeral", "persistent"], "description": "Whether workspace content may be indexed and whether any index may persist beyond the session."},
+    "retentionPolicy": {"enum": ["none", "sessionOnly", "untilRevoked", "policyDefined"], "default": "sessionOnly", "description": "How long derived workspace caches, embeddings, and indexes may be retained."},
+    "secretScanPolicy": {"enum": ["notRequired", "requiredBeforeIndex", "requiredBeforeWrite", "requiredBeforeRun"], "description": "Secret-scanning gate required before indexing, writes, or execution."},
+    "artifactRootRef": {"type": "string", "description": "Output directory, artifact vault ref, or content-addressed root for generated reports and receipts."},
+    "connectorRefs": {"type": "array", "items": {"type": "string", "pattern": "^urn:srcos:connector:"}, "description": "Connectors bound to this workspace scope."},
+    "policyDecisionRefs": {"type": "array", "items": {"type": "string", "pattern": "^urn:srcos:decision:"}, "description": "Policy decisions that authorized or denied the workspace boundary."},
+    "time": {"type": "object", "additionalProperties": false, "properties": {"createdAt": {"type": "string", "format": "date-time"}, "expiresAt": {"type": ["string", "null"], "format": "date-time"}}, "description": "Optional creation and expiry window for this workspace scope."}
+  }
+}

From fe28f7649915c7ac10bde1d11301d7b2e10c395a Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:19:37 -0400
Subject: [PATCH 02/19] Add onboarding TrustMode schema

---
 schemas/TrustMode.json | 63 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 schemas/TrustMode.json

diff --git a/schemas/TrustMode.json b/schemas/TrustMode.json
new file mode 100644
index 0000000..d36b2b7
--- /dev/null
+++ b/schemas/TrustMode.json
@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/TrustMode.json",
+  "title": "TrustMode",
+  "description": "A named SourceOS/SociOS permission envelope. TrustMode translates visible operating modes into explicit filesystem, execution, network, connector, scheduling, indexing, browser, computer-use, publication, approval, and receipt constraints.",
+  "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.0.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" },
+        "credentialUse": { "enum": ["none", "explicitApproval", "allowed"], "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." },
+    "approvalMoments": {
+      "type": "array",
+      "items": { "enum": ["beforeConnectorEnable", "beforeIndex", "beforeCommandRun", "beforeWorkspaceWrite", "beforeBranchPush", "beforePullRequestOpen", "beforeMerge", "beforeMessageSend", "beforeExternalPublish", "beforeCredentialUse", "beforeDestructiveAction", "beforeAutomationEnable"] },
+      "description": "Lifecycle moments where approval must be collected before action."
+    },
+    "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." }
+  }
+}

From 22204fb19ecde0a6424764520c4cafa7fb43bfb5 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:25:45 -0400
Subject: [PATCH 03/19] Add onboarding capability pack schema

---
 schemas/CapabilityPack.json | 122 ++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 schemas/CapabilityPack.json

diff --git a/schemas/CapabilityPack.json b/schemas/CapabilityPack.json
new file mode 100644
index 0000000..5a9bf3b
--- /dev/null
+++ b/schemas/CapabilityPack.json
@@ -0,0 +1,122 @@
+{
+  "$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, for example 2.0.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", "description": "Publisher display name or organization." },
+        "trustLevel": { "enum": ["firstParty", "trustedPartner", "community", "local", "unknown"], "description": "Supply-chain trust tier for catalog filtering." },
+        "signatureRequired": { "type": "boolean", "description": "Whether signed pack manifests are required before activation." },
+        "signatureRef": { "type": ["string", "null"], "description": "Optional signature, attestation, or verification reference." },
+        "sourceRef": { "type": ["string", "null"], "description": "Optional repository, package, or catalog source reference." }
+      },
+      "description": "Publisher, source, 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."
+    },
+    "lifecycle": { "enum": ["draft", "experimental", "internal", "trusted", "deprecated", "revoked", "blocked"], "default": "draft", "description": "Review and publication lifecycle of this pack." },
+    "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": "Canonical 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." },
+    "licensePolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allowedLicenses": { "type": "array", "items": { "type": "string" }, "description": "Licenses explicitly allowed by this pack policy." },
+        "forbiddenLicenses": { "type": "array", "items": { "type": "string" }, "description": "Licenses explicitly forbidden by this pack policy." },
+        "sbomRef": { "type": ["string", "null"], "description": "Optional SBOM or dependency inventory reference." }
+      },
+      "description": "License and dependency posture for supply-chain review."
+    },
+    "executionModes": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "supportsDryRun": { "type": "boolean", "description": "Whether the pack can run without side effects." },
+        "supportsDraftOnly": { "type": "boolean", "description": "Whether the pack can produce drafts instead of applying changes." },
+        "supportsApply": { "type": "boolean", "description": "Whether the pack can apply changes when policy permits." },
+        "defaultMode": { "enum": ["dryRun", "draftOnly", "apply"], "description": "Default execution mode when a session activates this pack." }
+      },
+      "description": "Side-effect posture exposed to onboarding and review surfaces."
+    },
+    "artifactOutputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "name"],
+        "properties": {
+          "kind": { "type": "string", "description": "Output kind, for example report, receipt, patch, pullRequestDraft, manifest, or review." },
+          "name": { "type": "string", "description": "Expected artifact name or relative path." },
+          "required": { "type": "boolean", "default": true, "description": "Whether this artifact is required for a successful run." },
+          "contentHashRequired": { "type": "boolean", "default": false, "description": "Whether the artifact must carry or be accompanied by a content hash." }
+        }
+      },
+      "description": "Artifacts this pack is expected to create."
+    },
+    "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", "description": "Whether the pack can be disabled after activation." },
+        "revokeDeletesLocalIndex": { "type": "boolean", "description": "Whether revocation deletes local indexes/caches created by this pack." },
+        "revokeDisablesAutomations": { "type": "boolean", "description": "Whether revocation disables automations depending on this pack." },
+        "revocationNotes": { "type": "string", "description": "Human-readable cleanup and limitation notes." }
+      },
+      "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." }
+  }
+}

From 231b19445ac361a1ee2b6cab5bf90ef6e12515f1 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:27:38 -0400
Subject: [PATCH 04/19] Add onboarding automation template schema

---
 schemas/AutomationTemplate.json | 53 +++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 schemas/AutomationTemplate.json

diff --git a/schemas/AutomationTemplate.json b/schemas/AutomationTemplate.json
new file mode 100644
index 0000000..f4703a7
--- /dev/null
+++ b/schemas/AutomationTemplate.json
@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/AutomationTemplate.json",
+  "title": "AutomationTemplate",
+  "description": "Reusable governed work template for manual, scheduled, event-driven, or conditional agent work. Binds required capability packs, connector action scopes, output artifacts, lifecycle defaults, and receipt requirements.",
+  "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:", "description": "Stable URN identifier." },
+    "type": { "const": "AutomationTemplate", "description": "Discriminator constant." },
+    "specVersion": { "type": "string", "description": "Spec version." },
+    "name": { "type": "string", "description": "Human-readable template name." },
+    "description": { "type": "string", "description": "Template purpose." },
+    "category": { "enum": ["statusReports", "releasePrep", "incidentsAndTriage", "codeQuality", "repoMaintenance", "securityCompliance", "fogstackOperations", "sourceosWorkstation", "knowledgeOffice", "researchCurriculum", "communityGrowth", "custom"], "description": "Operational category." },
+    "trigger": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["manual", "schedule", "event", "condition"], "description": "Activation kind." },
+        "schedule": { "type": ["string", "null"], "description": "Cron, RRULE, or platform schedule reference." },
+        "eventRef": { "type": ["string", "null"], "description": "Event, topic, webhook, or signal reference." },
+        "condition": { "type": ["string", "null"], "description": "Policy-evaluable condition." }
+      }
+    },
+    "requiredCapabilityPackRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:capability-pack:" }, "description": "Required capability packs." },
+    "requiredConnectorActionScopeRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:connector-action-scope:" }, "description": "Required connector action scopes." },
+    "requiredPermissionRefs": { "type": "array", "items": { "type": "string" }, "description": "Canonical permission identifiers." },
+    "defaultTimeWindow": { "type": "string", "description": "Default temporal scope, such as previous_day or since_last_run." },
+    "outputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "name"],
+        "properties": {
+          "kind": { "type": "string", "description": "Output kind." },
+          "name": { "type": "string", "description": "Output name or relative path." },
+          "required": { "type": "boolean", "default": true, "description": "Whether the output is mandatory." },
+          "contentHashRequired": { "type": "boolean", "default": false, "description": "Whether the output needs a hash." }
+        }
+      },
+      "description": "Expected work products."
+    },
+    "automationLifecycle": { "type": "array", "items": { "enum": ["draft", "enabled", "paused", "running", "failed", "disabled", "revoked", "expired"] }, "description": "Allowed lifecycle states for derived instances." },
+    "mustInclude": { "type": "array", "items": { "type": "string" }, "description": "Required evidence or content categories." },
+    "mustExclude": { "type": "array", "items": { "type": "string" }, "description": "Forbidden actions or content categories." },
+    "receiptRequired": { "type": "boolean", "description": "Whether every run needs a receipt." },
+    "riskLevel": { "enum": ["low", "medium", "high", "critical"], "default": "medium", "description": "Risk tier." },
+    "policyRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:policy:" }, "description": "Governing policies." }
+  }
+}

From e583cd0017f5ae10e4bf0e49f01505ded195ab57 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:28:41 -0400
Subject: [PATCH 05/19] Add onboarding connector action scope schema

---
 schemas/ConnectorActionScope.json | 45 +++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 schemas/ConnectorActionScope.json

diff --git a/schemas/ConnectorActionScope.json b/schemas/ConnectorActionScope.json
new file mode 100644
index 0000000..10379da
--- /dev/null
+++ b/schemas/ConnectorActionScope.json
@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/ConnectorActionScope.json",
+  "title": "ConnectorActionScope",
+  "description": "Precise action-scope envelope for a configured Connector. Prevents vague connector enablement by enumerating exact verbs, risk, credential-use posture, approval requirements, data exposure bounds, and receipt obligations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "connectorRef", "connectorKind", "actions", "accessLevel", "riskLevel", "requiresExplicitApproval", "credentialUse", "receiptRequired"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:connector-action-scope:", "description": "Stable URN identifier." },
+    "type": { "const": "ConnectorActionScope", "description": "Discriminator constant." },
+    "specVersion": { "type": "string", "description": "Spec version." },
+    "name": { "type": "string", "description": "Human-readable scope name." },
+    "description": { "type": "string", "description": "What this scope permits and forbids." },
+    "connectorRef": { "type": "string", "pattern": "^urn:srcos:connector:", "description": "Configured Connector URN." },
+    "connectorKind": { "enum": ["filesystem", "github", "gitlab", "email", "calendar", "drive", "slack", "linear", "notion", "browser", "computer", "httpApi", "kafka", "rdbms", "objectStore", "lakehouse", "shell", "ci", "deployment", "observability", "custom"], "description": "Connector class." },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(\\.[a-z0-9_:-]+)+$" },
+      "description": "Exact allowed connector verbs such as github.pr.read, email.draft, browser.submit_form, or computer.capture_replay."
+    },
+    "accessLevel": { "enum": ["none", "readOnly", "draftOnly", "commentOnly", "scopedWrite", "send", "publish", "merge", "destructive", "control"], "description": "Maximum side-effect class." },
+    "riskLevel": { "enum": ["low", "medium", "high", "critical"], "description": "Risk tier." },
+    "requiresExplicitApproval": { "type": "boolean", "description": "Whether use requires explicit approval." },
+    "approvalMoments": { "type": "array", "items": { "enum": ["beforeConnectorEnable", "beforeCredentialUse", "beforeWrite", "beforeComment", "beforeSend", "beforePublish", "beforeMerge", "beforeDelete", "beforeFormSubmit", "beforeComputerControl", "beforeAutomationEnable"] }, "description": "Specific lifecycle moments that require approval." },
+    "credentialUse": { "enum": ["none", "ambientReadOnly", "explicitApproval", "credentialedSession", "delegatedToken"], "description": "Credential, cookie, session, or token posture." },
+    "dataExposure": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mayReadContent": { "type": "boolean", "description": "Whether content may be read." },
+        "mayTransmitContent": { "type": "boolean", "description": "Whether content may be transmitted outside the boundary." },
+        "allowedDomains": { "type": "array", "items": { "type": "string" }, "description": "Allowed network or application domains." },
+        "dataClasses": { "type": "array", "items": { "enum": ["public", "internal", "private", "sensitive", "secret", "credential", "regulated"] }, "description": "Permitted data classifications." }
+      },
+      "description": "Data exposure and classification constraints."
+    },
+    "retentionPolicy": { "enum": ["none", "sessionOnly", "untilRevoked", "policyDefined"], "default": "sessionOnly", "description": "How long data may be cached or indexed." },
+    "receiptRequired": { "type": "boolean", "description": "Whether use must be represented in a receipt." },
+    "policyRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:policy:" }, "description": "Governing policies." },
+    "validFrom": { "type": ["string", "null"], "format": "date-time", "description": "Optional activation start time." },
+    "expiresAt": { "type": ["string", "null"], "format": "date-time", "description": "Optional expiry time." }
+  }
+}

From f560eb74a6c6db278c8f39dddfdef43a05979e83 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:29:20 -0400
Subject: [PATCH 06/19] Add onboarding receipt schema

---
 schemas/OnboardingReceipt.json | 78 ++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 schemas/OnboardingReceipt.json

diff --git a/schemas/OnboardingReceipt.json b/schemas/OnboardingReceipt.json
new file mode 100644
index 0000000..d009b6e
--- /dev/null
+++ b/schemas/OnboardingReceipt.json
@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/OnboardingReceipt.json",
+  "title": "OnboardingReceipt",
+  "description": "Receipt for a SourceOS/SociOS onboarding ceremony. Records selected role profiles, workspace scope, trust mode, capability packs, connector action scopes, automation templates, trial task, artifacts, policy decisions, and revocation hooks before a session reaches ready state.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "sessionRef", "workspaceScopeRef", "trustModeRef", "enabledCapabilityPackRefs", "enabledConnectorActionScopeRefs", "enabledAutomationTemplateRefs", "trialTask", "artifactRefs", "revocation", "capturedAt"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:receipt:onboarding:", "description": "Stable onboarding receipt URN." },
+    "type": { "const": "OnboardingReceipt", "description": "Discriminator constant." },
+    "specVersion": { "type": "string", "description": "Spec version." },
+    "sessionRef": { "type": "string", "pattern": "^urn:srcos:session:", "description": "AgentSession initialized or drafted by onboarding." },
+    "roleProfileRefs": { "type": "array", "items": { "type": "string" }, "description": "RoleProfile or semantic role references selected during onboarding." },
+    "workspaceScopeRef": { "type": "string", "pattern": "^urn:srcos:workspace-scope:", "description": "Selected WorkspaceScope." },
+    "trustModeRef": { "type": "string", "pattern": "^urn:srcos:trust-mode:", "description": "Selected TrustMode." },
+    "enabledCapabilityPackRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:capability-pack:" }, "description": "Capability packs enabled by onboarding." },
+    "disabledCapabilityPackRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:capability-pack:" }, "description": "Capability packs explicitly disabled or denied." },
+    "enabledConnectorActionScopeRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:connector-action-scope:" }, "description": "Connector action scopes enabled by onboarding." },
+    "disabledConnectorActionScopeRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:connector-action-scope:" }, "description": "Connector action scopes explicitly disabled or denied." },
+    "enabledAutomationTemplateRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:automation-template:" }, "description": "Automation templates enabled by onboarding." },
+    "disabledAutomationTemplateRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:automation-template:" }, "description": "Automation templates explicitly disabled or denied." },
+    "policyDecisionRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:decision:" }, "description": "Policy decisions that allowed, denied, or deferred onboarding grants." },
+    "eventRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:event:" }, "description": "Append-only event references summarized by this receipt." },
+    "trialTask": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "description", "status"],
+      "properties": {
+        "id": { "type": "string", "description": "Local trial task identifier." },
+        "description": { "type": "string", "description": "Human-readable trial task." },
+        "status": { "enum": ["notRun", "passed", "failed", "skipped"], "description": "Trial result." },
+        "replayClass": { "enum": ["exact", "bestEffort", "evidenceOnly", "nonReplayableSideEffect"], "description": "Replayability of the trial." },
+        "runRef": { "type": ["string", "null"], "description": "Optional run reference." },
+        "receiptRef": { "type": ["string", "null"], "description": "Optional trial receipt reference." }
+      }
+    },
+    "artifactRefs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "ref"],
+        "properties": {
+          "name": { "type": "string", "description": "Artifact name or path." },
+          "ref": { "type": "string", "description": "Artifact URI, URN, path, or content reference." },
+          "sha256": { "type": ["string", "null"], "pattern": "^[a-fA-F0-9]{64}$", "description": "Optional SHA-256 hash." },
+          "kind": { "type": "string", "description": "Artifact kind." }
+        }
+      },
+      "description": "Artifacts created or linked by onboarding."
+    },
+    "receiptRefs": { "type": "array", "items": { "type": "string", "pattern": "^urn:srcos:receipt:" }, "description": "Related receipt references." },
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "contentHash": { "type": ["string", "null"], "description": "Optional hash over canonical receipt content." },
+        "hashAlgorithm": { "type": ["string", "null"], "description": "Hash algorithm." },
+        "signatureRef": { "type": ["string", "null"], "description": "Optional signature or ledger reference." },
+        "previousReceiptRef": { "type": ["string", "null"], "description": "Optional previous receipt in a chain." }
+      }
+    },
+    "revocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["supported", "instructions"],
+      "properties": {
+        "supported": { "type": "boolean", "description": "Whether grants can be revoked." },
+        "instructions": { "type": "string", "description": "Human-readable revocation path." },
+        "revocationRefs": { "type": "array", "items": { "type": "string" }, "description": "Revocation record, policy, script, or UI route references." },
+        "cleanupActions": { "type": "array", "items": { "enum": ["disableCapabilityPack", "disableConnectorScope", "disableAutomation", "deleteLocalIndex", "removeCredentialToken", "invalidateCapabilityToken", "deleteArtifactCache"] }, "description": "Cleanup actions expected on revocation." }
+      }
+    },
+    "capturedAt": { "type": "string", "format": "date-time", "description": "Capture timestamp." },
+    "capturedBy": { "type": ["string", "null"], "description": "Optional capturer identifier." }
+  }
+}

From 4b43a77b89ca9ce7ddb24c1dcb83857c711a68fb Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:32:09 -0400
Subject: [PATCH 07/19] Add onboarding workspace scope example

---
 examples/workspacescope.json | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 examples/workspacescope.json

diff --git a/examples/workspacescope.json b/examples/workspacescope.json
new file mode 100644
index 0000000..9a3b13a
--- /dev/null
+++ b/examples/workspacescope.json
@@ -0,0 +1,29 @@
+{
+  "id": "urn:srcos:workspace-scope:socioprophet-sourceos-spec-readonly",
+  "type": "WorkspaceScope",
+  "specVersion": "2.0.0",
+  "workspaceKind": "gitRepository",
+  "displayName": "SourceOS Spec read-only review workspace",
+  "rootRef": "github:SourceOS-Linux/sourceos-spec",
+  "mountMode": "readOnly",
+  "allowedReadRefs": ["README.md", "schemas/**", "examples/**", "semantic/**", "docs/adr/**"],
+  "allowedWriteRefs": [],
+  "excludedRefs": ["local-secret-files", "private-credential-stores", "dependency-caches"],
+  "worktreeRef": "refs/heads/main",
+  "branchPolicy": {
+    "baseRef": "refs/heads/main",
+    "headRef": null,
+    "allowedPushRefs": [],
+    "requiresPullRequest": true
+  },
+  "indexingPolicy": "ephemeral",
+  "retentionPolicy": "sessionOnly",
+  "secretScanPolicy": "requiredBeforeIndex",
+  "artifactRootRef": "artifacts/onboarding/sourceos-spec-readonly",
+  "connectorRefs": ["urn:srcos:connector:github-sourceos-linux"],
+  "policyDecisionRefs": ["urn:srcos:decision:onboarding-workspace-readonly-allow"],
+  "time": {
+    "createdAt": "2026-05-05T00:00:00Z",
+    "expiresAt": null
+  }
+}

From dc63b9b6b67a23201865df7915d6cccdf8e9685f Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:33:59 -0400
Subject: [PATCH 08/19] Add read-only trust mode example

---
 examples/trustmode.read_only_analyst.json | 31 +++++++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 examples/trustmode.read_only_analyst.json

diff --git a/examples/trustmode.read_only_analyst.json b/examples/trustmode.read_only_analyst.json
new file mode 100644
index 0000000..2073d19
--- /dev/null
+++ b/examples/trustmode.read_only_analyst.json
@@ -0,0 +1,31 @@
+{
+  "id": "urn:srcos:trust-mode:read-only-analyst",
+  "type": "TrustMode",
+  "specVersion": "2.0.0",
+  "name": "Read-only analyst",
+  "category": "readOnlyAnalyst",
+  "summary": "Allows bounded repository and artifact reading without workspace writes, command execution, persistent indexing, message sends, or destructive actions.",
+  "permissions": {
+    "filesystemRead": true,
+    "filesystemWrite": "none",
+    "commandRun": "none",
+    "networkEgress": "none",
+    "connectorRead": false,
+    "connectorWrite": "none",
+    "messageSend": "none",
+    "publishExternal": "none",
+    "indexPersist": false,
+    "scheduleCreate": false,
+    "deleteOrDestructiveAction": "none",
+    "computerUse": "none",
+    "browserUse": "none",
+    "credentialUse": "none"
+  },
+  "defaultExecutionSurfaceRef": null,
+  "requiresHumanApproval": false,
+  "approvalMoments": [],
+  "approvalProfileRef": null,
+  "receiptRequired": true,
+  "riskLevel": "low",
+  "policyRefs": ["urn:srcos:policy:onboarding-read-only"]
+}

From b01e46b52139a2aa69768a11b08c30ba071f0ad4 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:35:13 -0400
Subject: [PATCH 09/19] Add GitHub read-only connector action scope example

---
 ...connectoractionscope.github_read_only.json | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 examples/connectoractionscope.github_read_only.json

diff --git a/examples/connectoractionscope.github_read_only.json b/examples/connectoractionscope.github_read_only.json
new file mode 100644
index 0000000..75d951d
--- /dev/null
+++ b/examples/connectoractionscope.github_read_only.json
@@ -0,0 +1,26 @@
+{
+  "id": "urn:srcos:connector-action-scope:github-read-only",
+  "type": "ConnectorActionScope",
+  "specVersion": "2.0.0",
+  "name": "GitHub read-only",
+  "description": "Allows reading repository metadata, issues, and pull requests. It cannot comment, push, merge, publish releases, or mutate repository state.",
+  "connectorRef": "urn:srcos:connector:github-sourceos-linux",
+  "connectorKind": "github",
+  "actions": ["github.repo.read", "github.pr.read", "github.issue.read"],
+  "accessLevel": "readOnly",
+  "riskLevel": "low",
+  "requiresExplicitApproval": false,
+  "approvalMoments": [],
+  "credentialUse": "delegatedToken",
+  "dataExposure": {
+    "mayReadContent": true,
+    "mayTransmitContent": false,
+    "allowedDomains": ["github.com", "api.github.com"],
+    "dataClasses": ["public", "internal"]
+  },
+  "retentionPolicy": "sessionOnly",
+  "receiptRequired": true,
+  "policyRefs": ["urn:srcos:policy:github-read-only"],
+  "validFrom": "2026-05-05T00:00:00Z",
+  "expiresAt": null
+}

From 465b3078c4aa0b11004258af4743d2835b302b11 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:38:44 -0400
Subject: [PATCH 10/19] Add repo release prep capability pack example

---
 .../capabilitypack.repo_release_prep.json     | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 examples/capabilitypack.repo_release_prep.json

diff --git a/examples/capabilitypack.repo_release_prep.json b/examples/capabilitypack.repo_release_prep.json
new file mode 100644
index 0000000..6871e3c
--- /dev/null
+++ b/examples/capabilitypack.repo_release_prep.json
@@ -0,0 +1,60 @@
+{
+  "id": "urn:srcos:capability-pack:repo-release-prep",
+  "type": "CapabilityPack",
+  "specVersion": "2.0.0",
+  "name": "Repository release preparation",
+  "version": "0.1.0",
+  "description": "Reads repository state and drafts release-readiness artifacts without mutating the repository.",
+  "publisher": {
+    "name": "SourceOS-Linux",
+    "trustLevel": "firstParty",
+    "signatureRequired": true,
+    "signatureRef": null,
+    "sourceRef": "github:SourceOS-Linux/sourceos-spec"
+  },
+  "category": "repoOrchestration",
+  "lifecycle": "internal",
+  "skillRefs": [
+    "urn:srcos:skill:git-activity-summary",
+    "urn:srcos:skill:release-notes-draft",
+    "urn:srcos:skill:changelog-check"
+  ],
+  "requiredConnectorActionScopeRefs": ["urn:srcos:connector-action-scope:github-read-only"],
+  "requiredPermissionRefs": ["github.repo.read", "github.pr.read", "github.issue.read", "artifact.write"],
+  "compatibleTrustModeRefs": ["urn:srcos:trust-mode:read-only-analyst"],
+  "forbiddenTrustModeRefs": ["urn:srcos:trust-mode:privileged-maintainer"],
+  "riskLevel": "medium",
+  "licensePolicy": {
+    "allowedLicenses": ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause"],
+    "forbiddenLicenses": ["review-required"],
+    "sbomRef": null
+  },
+  "executionModes": {
+    "supportsDryRun": true,
+    "supportsDraftOnly": true,
+    "supportsApply": false,
+    "defaultMode": "draftOnly"
+  },
+  "artifactOutputs": [
+    {
+      "kind": "report",
+      "name": "release_notes.md",
+      "required": true,
+      "contentHashRequired": true
+    },
+    {
+      "kind": "receipt",
+      "name": "release_readiness_receipt.json",
+      "required": true,
+      "contentHashRequired": true
+    }
+  ],
+  "receiptRequired": true,
+  "revocation": {
+    "revocable": true,
+    "revokeDeletesLocalIndex": true,
+    "revokeDisablesAutomations": true,
+    "revocationNotes": "Disable dependent automations and clear ephemeral release-prep indexes."
+  },
+  "policyRefs": ["urn:srcos:policy:repo-release-prep-draft-only"]
+}

From 074177f2e535cf34cfef6dc8dc55ddc6e956ae24 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:41:06 -0400
Subject: [PATCH 11/19] Add yesterday Git activity automation example

---
 ...mationtemplate.yesterday_git_activity.json | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 examples/automationtemplate.yesterday_git_activity.json

diff --git a/examples/automationtemplate.yesterday_git_activity.json b/examples/automationtemplate.yesterday_git_activity.json
new file mode 100644
index 0000000..6859ae8
--- /dev/null
+++ b/examples/automationtemplate.yesterday_git_activity.json
@@ -0,0 +1,38 @@
+{
+  "id": "urn:srcos:automation-template:yesterday-git-activity",
+  "type": "AutomationTemplate",
+  "specVersion": "2.0.0",
+  "name": "Yesterday Git activity digest",
+  "description": "Creates a daily standup artifact summarizing repository activity from the previous day with links, source refs, and a receipt.",
+  "category": "statusReports",
+  "trigger": {
+    "kind": "schedule",
+    "schedule": "RRULE:FREQ=DAILY;BYHOUR=8;BYMINUTE=0;BYSECOND=0",
+    "eventRef": null,
+    "condition": null
+  },
+  "requiredCapabilityPackRefs": ["urn:srcos:capability-pack:repo-release-prep"],
+  "requiredConnectorActionScopeRefs": ["urn:srcos:connector-action-scope:github-read-only"],
+  "requiredPermissionRefs": ["github.repo.read", "github.pr.read", "github.issue.read", "artifact.write"],
+  "defaultTimeWindow": "previous_day",
+  "outputs": [
+    {
+      "kind": "report",
+      "name": "standup_git_activity.md",
+      "required": true,
+      "contentHashRequired": true
+    },
+    {
+      "kind": "receipt",
+      "name": "standup_git_activity_receipt.json",
+      "required": true,
+      "contentHashRequired": true
+    }
+  ],
+  "automationLifecycle": ["draft", "enabled", "paused", "running", "failed", "disabled", "revoked", "expired"],
+  "mustInclude": ["source_refs", "time_window", "policy_decision_refs", "artifact_hashes"],
+  "mustExclude": ["workspace_writes", "message_send", "external_publish", "merge", "delete"],
+  "receiptRequired": true,
+  "riskLevel": "low",
+  "policyRefs": ["urn:srcos:policy:automation-status-report-read-only"]
+}

From eafafd3844c9b834fcb321cb32c67979c049b3a5 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:42:24 -0400
Subject: [PATCH 12/19] Add first-run onboarding receipt example

---
 ...onboardingreceipt.first_run_read_only.json | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 examples/onboardingreceipt.first_run_read_only.json

diff --git a/examples/onboardingreceipt.first_run_read_only.json b/examples/onboardingreceipt.first_run_read_only.json
new file mode 100644
index 0000000..0d0d960
--- /dev/null
+++ b/examples/onboardingreceipt.first_run_read_only.json
@@ -0,0 +1,66 @@
+{
+  "id": "urn:srcos:receipt:onboarding:first-run-read-only",
+  "type": "OnboardingReceipt",
+  "specVersion": "2.0.0",
+  "sessionRef": "urn:srcos:session:first-run-read-only",
+  "roleProfileRefs": ["urn:srcos:role-profile:maintainer-analyst"],
+  "workspaceScopeRef": "urn:srcos:workspace-scope:socioprophet-sourceos-spec-readonly",
+  "trustModeRef": "urn:srcos:trust-mode:read-only-analyst",
+  "enabledCapabilityPackRefs": ["urn:srcos:capability-pack:repo-release-prep"],
+  "disabledCapabilityPackRefs": ["urn:srcos:capability-pack:repo-merge-operator"],
+  "enabledConnectorActionScopeRefs": ["urn:srcos:connector-action-scope:github-read-only"],
+  "disabledConnectorActionScopeRefs": [
+    "urn:srcos:connector-action-scope:github-merge",
+    "urn:srcos:connector-action-scope:email-send"
+  ],
+  "enabledAutomationTemplateRefs": ["urn:srcos:automation-template:yesterday-git-activity"],
+  "disabledAutomationTemplateRefs": [],
+  "policyDecisionRefs": [
+    "urn:srcos:decision:onboarding-workspace-readonly-allow",
+    "urn:srcos:decision:github-read-only-allow"
+  ],
+  "eventRefs": ["urn:srcos:event:onboarding-first-run-read-only-0001"],
+  "trialTask": {
+    "id": "trial-read-repo-no-write",
+    "description": "Read repository metadata and draft a local standup artifact without writing to the repository or sending messages.",
+    "status": "passed",
+    "replayClass": "evidenceOnly",
+    "runRef": "urn:srcos:run:onboarding-trial-readonly-0001",
+    "receiptRef": "urn:srcos:receipt:session:onboarding-trial-readonly-0001"
+  },
+  "artifactRefs": [
+    {
+      "name": "workspace_scope.json",
+      "ref": "artifacts/onboarding/sourceos-spec-readonly/workspace_scope.json",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "kind": "scope"
+    },
+    {
+      "name": "onboarding_receipt.json",
+      "ref": "artifacts/onboarding/sourceos-spec-readonly/onboarding_receipt.json",
+      "sha256": "1111111111111111111111111111111111111111111111111111111111111111",
+      "kind": "receipt"
+    }
+  ],
+  "receiptRefs": ["urn:srcos:receipt:session:onboarding-trial-readonly-0001"],
+  "integrity": {
+    "contentHash": null,
+    "hashAlgorithm": "sha256",
+    "signatureRef": null,
+    "previousReceiptRef": null
+  },
+  "revocation": {
+    "supported": true,
+    "instructions": "Disable the GitHub read-only scope, disable dependent automations, invalidate derived capability tokens, and clear ephemeral workspace indexes.",
+    "revocationRefs": ["urn:srcos:policy:onboarding-revoke-read-only"],
+    "cleanupActions": [
+      "disableCapabilityPack",
+      "disableConnectorScope",
+      "disableAutomation",
+      "deleteLocalIndex",
+      "invalidateCapabilityToken"
+    ]
+  },
+  "capturedAt": "2026-05-05T00:00:00Z",
+  "capturedBy": "urn:srcos:agent:onboarding-control-plane"
+}

From ac6913bcd8778a6effe8a6f5d1e68b743c4085ae Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:43:10 -0400
Subject: [PATCH 13/19] Add onboarding example validator

---
 tools/validate_onboarding_examples.py | 38 +++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 tools/validate_onboarding_examples.py

diff --git a/tools/validate_onboarding_examples.py b/tools/validate_onboarding_examples.py
new file mode 100644
index 0000000..71d1fd2
--- /dev/null
+++ b/tools/validate_onboarding_examples.py
@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Validate SourceOS/SociOS onboarding control-plane schema/example pairs."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import jsonschema
+
+ROOT = Path(__file__).resolve().parents[1]
+PAIRS = [
+    (ROOT / "schemas" / "WorkspaceScope.json", ROOT / "examples" / "workspacescope.json"),
+    (ROOT / "schemas" / "TrustMode.json", ROOT / "examples" / "trustmode.read_only_analyst.json"),
+    (ROOT / "schemas" / "CapabilityPack.json", ROOT / "examples" / "capabilitypack.repo_release_prep.json"),
+    (ROOT / "schemas" / "ConnectorActionScope.json", ROOT / "examples" / "connectoractionscope.github_read_only.json"),
+    (ROOT / "schemas" / "AutomationTemplate.json", ROOT / "examples" / "automationtemplate.yesterday_git_activity.json"),
+    (ROOT / "schemas" / "OnboardingReceipt.json", ROOT / "examples" / "onboardingreceipt.first_run_read_only.json"),
+]
+
+
+def validate_pair(schema_path: Path, example_path: Path) -> None:
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    jsonschema.validators.validator_for(schema).check_schema(schema)
+    example = json.loads(example_path.read_text(encoding="utf-8"))
+    jsonschema.validate(example, schema)
+
+
+def main() -> int:
+    checks: dict[str, bool] = {}
+    for schema_path, example_path in PAIRS:
+        validate_pair(schema_path, example_path)
+        checks[example_path.name] = True
+    print(json.dumps({"ok": all(checks.values()), "checks": checks}, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From aadacaa9f3d50688ed997959c0895f1c159994f6 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:44:29 -0400
Subject: [PATCH 14/19] Wire onboarding example validation into make validate

---
 Makefile | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index fd1ea2b..6558a8c 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
-.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples
+.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-onboarding-examples
 
-validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples
+validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-onboarding-examples
 	@echo "OK: validate"
 
 validate-control-plane-examples:
@@ -18,3 +18,7 @@ validate-lattice-data-governai-examples:
 validate-ops-history-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_ops_history_examples.py
+
+validate-onboarding-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_onboarding_examples.py

From 6d1f54157d45dd09fae7602176f840e8e48f1574 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 22:48:13 -0400
Subject: [PATCH 15/19] Document onboarding control-plane contract decision

---
 ...0012-onboarding-control-plane-contracts.md | 102 ++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 docs/adr/0012-onboarding-control-plane-contracts.md

diff --git a/docs/adr/0012-onboarding-control-plane-contracts.md b/docs/adr/0012-onboarding-control-plane-contracts.md
new file mode 100644
index 0000000..3d1a0d0
--- /dev/null
+++ b/docs/adr/0012-onboarding-control-plane-contracts.md
@@ -0,0 +1,102 @@
+# ADR-0012: Onboarding Control-Plane Contracts
+
+**Date:** 2026-05-05
+**Status:** `Accepted`
+**Deciders:** SourceOS-Linux/sourceos-spec maintainers
+
+---
+
+## Context
+
+SourceOS/SociOS needs a local-first, auditable agent workbench where roles, workspaces, trust modes, capability packs, connector action scopes, automation templates, artifacts, and receipts are visible, scoped, revocable, and machine-readable.
+
+Claude-style onboarding demonstrates a useful role-first ceremony: choose role, add plugins/connectors/skills, confirm working context, and finish with a calm progress rail. Codex-style workbench surfaces demonstrate the project/workspace grammar: local mode, branch context, permission defaults, plugin/skill catalogs, connector cards, and scheduled automation templates.
+
+SourceOS should not copy casual toggle semantics. The SourceOS/SociOS contract layer must make capability activation explicit, signed or policy-backed where required, scoped to a workspace, revocable, and receipted.
+
+## Decision
+
+Introduce an additive onboarding and agent-workbench control-plane family:
+
+| Schema | URN prefix | Purpose |
+|--------|------------|---------|
+| `WorkspaceScope` | `urn:srcos:workspace-scope:` | Selected workspace, repository, folder, organization, fog workspace, or sandbox boundary |
+| `TrustMode` | `urn:srcos:trust-mode:` | User-visible permission envelope expressed as explicit verbs |
+| `CapabilityPack` | `urn:srcos:capability-pack:` | Curated bundle of SkillManifest refs, connector scopes, policy refs, expected artifacts, and revocation behavior |
+| `ConnectorActionScope` | `urn:srcos:connector-action-scope:` | Exact connector verbs and side-effect class allowed for a configured Connector |
+| `AutomationTemplate` | `urn:srcos:automation-template:` | Reusable scheduled, manual, evented, or conditional work-product template |
+| `OnboardingReceipt` | `urn:srcos:receipt:onboarding:` | Receipt proving what was selected, enabled, disabled, scoped, trialed, and made revocable |
+
+These schemas bridge the existing Workstation, Governance, Execution/Provenance, and Agent Plane families. They are additive and SemVer-minor compatible.
+
+## Reuse of existing contracts
+
+This family intentionally does not replace existing primitives:
+
+- `AgentSession` remains the concrete session object.
+- `ExecutionSurface` remains the runtime, sandbox, network, workdir, worktree, and approval envelope.
+- `SkillManifest` remains the narrow skill declaration.
+- `Connector` remains the configured connection to a local or external system.
+- `Policy`, `PolicyDecision`, `CapabilityToken`, and `Obligation` remain the governance decision and grant machinery.
+- `SessionReceipt` remains the general final receipt for completed sessions.
+
+The new schemas add composition and ceremony layers around those primitives so onboarding can produce a draft `AgentSession`, bind it to a `WorkspaceScope` and `TrustMode`, activate compatible `CapabilityPack` and `ConnectorActionScope` refs, optionally enable `AutomationTemplate` refs, and emit an `OnboardingReceipt`.
+
+## Canonical ceremony state machine
+
+The intended first-run state machine is:
+
+1. `S0_BOOTSTRAP`
+2. `S1_ROLE_PROFILE`
+3. `S2_WORKSPACE_SCOPE`
+4. `S3_TRUST_MODE`
+5. `S4_CAPABILITY_PACKS`
+6. `S5_CONNECTOR_ACTION_SCOPES`
+7. `S6_AUTOMATION_TEMPLATES`
+8. `S7_AGENT_SESSION_DRAFT`
+9. `S8_TRIAL_TASK`
+10. `S9_RECEIPT_REVIEW`
+11. `S10_READY`
+12. `S11_REVOKE_OR_RESET`
+
+## Consequences
+
+### Positive
+
+- SourceOS Shell can render first-run onboarding and composer/evidence-rail state from contracts.
+- Sociosphere can validate workspace-scope compatibility before materializing workspace or automation bindings.
+- Agentplane can execute only after `AgentSession` and `ExecutionSurface` bindings exist and can include onboarding refs in run and replay artifacts.
+- Ontogenesis can add RDF/OWL/SHACL semantics for trust modes, capabilities, connector scopes, automation templates, and receipts.
+- Prophet Platform can index and display onboarding receipts as evidence objects.
+- Connector enablement is no longer vague; action scopes distinguish read, draft, write, comment, send, publish, merge, destructive, and control classes.
+
+### Constraints
+
+- SourceOS Shell UI implementation is out of scope for this repository.
+- Runtime enforcement belongs in SourceOS Shell, Sociosphere, Agentplane, and downstream execution surfaces.
+- Capability-pack marketplace review, signatures, and license policy are modeled here but enforced downstream.
+- Advanced follow-on contracts such as `RoleProfile`, `PermissionVocabulary`, `AutomationBinding`, `AutomationRunRecord`, `RevocationRecord`, and `WorktreeScope` remain follow-up work.
+
+## Non-goals
+
+- Do not implement UI in `sourceos-spec`.
+- Do not replace `AgentSession`.
+- Do not replace `ExecutionSurface`.
+- Do not replace `SkillManifest`.
+- Do not replace `SessionReceipt`.
+- Do not make connector toggles equivalent to write authority.
+- Do not make scheduled chats equivalent to governed recurring work products.
+
+## Validation
+
+This slice adds `tools/validate_onboarding_examples.py` and wires it into `make validate` through `validate-onboarding-examples`.
+
+## References
+
+- `schemas/WorkspaceScope.json`
+- `schemas/TrustMode.json`
+- `schemas/CapabilityPack.json`
+- `schemas/ConnectorActionScope.json`
+- `schemas/AutomationTemplate.json`
+- `schemas/OnboardingReceipt.json`
+- `tools/validate_onboarding_examples.py`

From 816bb12e1b672bca5e3a7da2cdd3e8320f989399 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 23:00:47 -0400
Subject: [PATCH 16/19] Add onboarding semantic vocabulary seed

---
 .../sourceos-onboarding-vocabulary.jsonld     | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 semantic/sourceos-onboarding-vocabulary.jsonld

diff --git a/semantic/sourceos-onboarding-vocabulary.jsonld b/semantic/sourceos-onboarding-vocabulary.jsonld
new file mode 100644
index 0000000..64ff07a
--- /dev/null
+++ b/semantic/sourceos-onboarding-vocabulary.jsonld
@@ -0,0 +1,58 @@
+{
+  "@context": {
+    "srcos": "https://schemas.srcos.ai/v2/",
+    "schema": "https://schema.org/",
+    "id": "@id",
+    "type": "@type",
+    "WorkspaceScope": "srcos:WorkspaceScope",
+    "TrustMode": "srcos:TrustMode",
+    "CapabilityPack": "srcos:CapabilityPack",
+    "ConnectorActionScope": "srcos:ConnectorActionScope",
+    "AutomationTemplate": "srcos:AutomationTemplate",
+    "OnboardingReceipt": "srcos:OnboardingReceipt",
+    "workspaceKind": "srcos:workspaceKind",
+    "mountMode": "srcos:mountMode",
+    "riskLevel": "srcos:riskLevel",
+    "receiptRequired": "srcos:receiptRequired",
+    "requiresExplicitApproval": "srcos:requiresExplicitApproval",
+    "enabledCapabilityPack": "srcos:enabledCapabilityPack",
+    "enabledConnectorActionScope": "srcos:enabledConnectorActionScope",
+    "enabledAutomationTemplate": "srcos:enabledAutomationTemplate",
+    "trialTask": "srcos:trialTask",
+    "revocation": "srcos:revocation",
+    "policyDecisionRef": "srcos:policyDecisionRef",
+    "artifactRef": "srcos:artifactRef"
+  },
+  "@graph": [
+    {
+      "@id": "srcos:WorkspaceScope",
+      "@type": "schema:DefinedTerm",
+      "schema:name": "WorkspaceScope"
+    },
+    {
+      "@id": "srcos:TrustMode",
+      "@type": "schema:DefinedTerm",
+      "schema:name": "TrustMode"
+    },
+    {
+      "@id": "srcos:CapabilityPack",
+      "@type": "schema:DefinedTerm",
+      "schema:name": "CapabilityPack"
+    },
+    {
+      "@id": "srcos:ConnectorActionScope",
+      "@type": "schema:DefinedTerm",
+      "schema:name": "ConnectorActionScope"
+    },
+    {
+      "@id": "srcos:AutomationTemplate",
+      "@type": "schema:DefinedTerm",
+      "schema:name": "AutomationTemplate"
+    },
+    {
+      "@id": "srcos:OnboardingReceipt",
+      "@type": "schema:DefinedTerm",
+      "schema:name": "OnboardingReceipt"
+    }
+  ]
+}

From 4578c0251a2b014f11a5f61e90c312bda27bc80c Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 23:03:00 -0400
Subject: [PATCH 17/19] Record onboarding control-plane contracts in changelog

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 827d28c..ac9e685 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ## [Unreleased]
 
 ### Added
+- Onboarding control-plane contract family: `WorkspaceScope`, `TrustMode`, `CapabilityPack`, `ConnectorActionScope`, `AutomationTemplate`, and `OnboardingReceipt`, with canonical first-run examples, semantic vocabulary seed, ADR, and `validate-onboarding-examples` validation target.
 - Reasoning run contracts: `ReasoningRun`, `ReasoningEvent`, `ReasoningReceipt`, `ReasoningReplayPlan`, and `ReasoningBenchmark` with canonical examples and a contract-additions note for the Superconscious reference loop.
 - Agent Machine / Model Carry schemas: `SourceOSModelCarryRef`, `InferenceProvider`, `ModelResidency`, `PlacementFact`, and `AgentMachineReceipt` with canonical examples and a contract-additions placement note.
 - NLBoot object schemas: `NLBootPlan`, `ArtifactCacheRecord`, `BootProofRecord`, `AppleSiliconAdapterEvidence` with canonical examples and validation (`tools/validate_nlboot_examples.py`)

From 76af7abad05e30e0a3d3548e175327619c570525 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 23:14:55 -0400
Subject: [PATCH 18/19] Document onboarding semantic vocabulary seed

---
 semantic/README.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/semantic/README.md b/semantic/README.md
index 3636700..53e93a8 100644
--- a/semantic/README.md
+++ b/semantic/README.md
@@ -13,6 +13,23 @@ This directory provides the JSON-LD and Hydra semantic overlay for the SourceOS/
 | `fog-vocabulary.jsonld` | Additive fog vocabulary seed for FogVault / FogCompute types and key predicates |
 | `agent-machine-model-carry-context.jsonld` | Additive context slice for SourceOS model carry and Agent Machine runtime facts/receipts |
 | `agent-machine-model-carry-hydra.jsonld` | Additive Hydra slice for SourceOS model carry and Agent Machine runtime classes |
+| `sourceos-onboarding-vocabulary.jsonld` | Additive onboarding/control-plane vocabulary seed for workspace scopes, trust modes, capability packs, connector action scopes, automation templates, and onboarding receipts |
+
+---
+
+## Recent additions — Onboarding control-plane vocabulary
+
+The onboarding control-plane slice currently contributes an additive semantic vocabulary covering:
+
+- `WorkspaceScope`
+- `TrustMode`
+- `CapabilityPack`
+- `ConnectorActionScope`
+- `AutomationTemplate`
+- `OnboardingReceipt`
+- key predicates such as `workspaceKind`, `mountMode`, `riskLevel`, `receiptRequired`, `requiresExplicitApproval`, `enabledCapabilityPack`, `enabledConnectorActionScope`, `enabledAutomationTemplate`, `trialTask`, and `revocation`
+
+This vocabulary is intentionally staged as an additive slice file so Ontogenesis can attach RDF/OWL/SHACL semantics before these terms are folded into the global `context.jsonld` and `hydra.jsonld` files.
 
 ---
 

From 1c15db49eee3141d333f1d7ba79d59305a4b899a Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 5 May 2026 23:39:17 -0400
Subject: [PATCH 19/19] Add onboarding control-plane contract note

---
 .../onboarding-control-plane.md               | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 docs/contract-additions/onboarding-control-plane.md

diff --git a/docs/contract-additions/onboarding-control-plane.md b/docs/contract-additions/onboarding-control-plane.md
new file mode 100644
index 0000000..aaea464
--- /dev/null
+++ b/docs/contract-additions/onboarding-control-plane.md
@@ -0,0 +1,66 @@
+# Onboarding Control-Plane Contract Additions
+
+This note documents the additive SourceOS/SociOS onboarding and agent-workbench control-plane contract family introduced by ADR-0012.
+
+## Contract family
+
+| File | Type | URN prefix |
+|------|------|------------|
+| `schemas/WorkspaceScope.json` | WorkspaceScope | `urn:srcos:workspace-scope:` |
+| `schemas/TrustMode.json` | TrustMode | `urn:srcos:trust-mode:` |
+| `schemas/CapabilityPack.json` | CapabilityPack | `urn:srcos:capability-pack:` |
+| `schemas/ConnectorActionScope.json` | ConnectorActionScope | `urn:srcos:connector-action-scope:` |
+| `schemas/AutomationTemplate.json` | AutomationTemplate | `urn:srcos:automation-template:` |
+| `schemas/OnboardingReceipt.json` | OnboardingReceipt | `urn:srcos:receipt:onboarding:` |
+
+These contracts support role/workspace/trust-mode onboarding ceremonies, plugin and capability-pack catalogs, connector action-scope inspection, scheduled automation templates, first-run workspace setup receipts, and SourceOS Shell composer/evidence-rail state.
+
+## Example payloads
+
+| File | Purpose |
+|------|---------|
+| `examples/workspacescope.json` | Read-only repository workspace boundary for SourceOS spec review |
+| `examples/trustmode.read_only_analyst.json` | Low-risk trust envelope with no writes, sends, command execution, or persistent indexing |
+| `examples/capabilitypack.repo_release_prep.json` | Draft-only repository release-prep pack composed from skills and GitHub read scope |
+| `examples/connectoractionscope.github_read_only.json` | GitHub read-only action scope for repo, PR, and issue reads |
+| `examples/automationtemplate.yesterday_git_activity.json` | Daily previous-day Git activity report template |
+| `examples/onboardingreceipt.first_run_read_only.json` | First-run onboarding receipt binding role, workspace, trust, capability, connector, automation, trial task, artifacts, and revocation |
+
+## Validation
+
+The family has a dedicated validator:
+
+```bash
+make validate-onboarding-examples
+```
+
+The target is also wired into the top-level validation lane:
+
+```bash
+make validate
+```
+
+## Reuse boundaries
+
+This family does not replace existing contracts:
+
+- `AgentSession` remains the session object.
+- `ExecutionSurface` remains the runtime, sandbox, network, workdir, worktree, and approval envelope.
+- `SkillManifest` remains the narrow skill declaration.
+- `Connector` remains the configured local or external connection.
+- `Policy`, `PolicyDecision`, `CapabilityToken`, and `Obligation` remain the governance machinery.
+- `SessionReceipt` remains the general final session receipt.
+
+The onboarding contracts add the composition and ceremony layer around those primitives.
+
+## Follow-on work
+
+The next implementation slices should add:
+
+- Ontogenesis RDF/OWL/SHACL semantics and validation gates.
+- Sociosphere workspace fixtures, registry entries, and onboarding-state-machine validator.
+- Agentplane run-envelope and receipt integration.
+- SourceOS Shell onboarding UI stubs and composer/evidence-rail binding.
+- Prophet Platform evidence-console/API binding for onboarding receipts.
+
+Potential follow-on contracts include `RoleProfile`, `PermissionVocabulary`, `AutomationBinding`, `AutomationRunRecord`, `RevocationRecord`, and `WorktreeScope`.