feat/onboarding-control-plane-contracts-complete

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.
 - `ReasoningEvent.controlFlow` (optional) + a reserved control-flow `eventType` vocabulary (`reasoning.tool.called` / `reasoning.decision.branched` / `reasoning.subrun.spawned` / `reasoning.subrun.joined` / `reasoning.run.completed`) so emitters can carry a run's operational control flow for downstream narration-fidelity verification (SP-TRACE-CFR). Backward-compatible; operational structure only (no raw reasoning). See `docs/reasoning-control-flow-events.md` and `examples/reasoning_event_control_flow.json`.
 - SourceOS interaction substrate top-level index and README discovery links for `SourceOSInteractionEvent`, generated TypeScript/Python artifacts, and the Noetica → Superconscious → AgentPlane → AgentTerm reference flow.
 - Runtime observability and capability governance contracts: `CapabilityLedger`, `BrowserAutomationReceipt`, `GitWorkspaceState`, `OrphanEventReceipt`, and `RuntimeInstallReceipt` with canonical examples, validation wiring (`tools/validate_runtime_observability_examples.py`), a contract catalog, and ADR-0012.

Makefile

@@ -1,6 +1,6 @@
-.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts
+.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples
 
-validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts
+validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples
 	@echo "OK: validate"
 
 validate-control-plane-examples:
@@ -19,6 +19,9 @@ 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
 validate-runtime-observability-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_runtime_observability_examples.py

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`

docs/contract-additions/onboarding-control-plane.md

@@ -1,6 +1,6 @@
 # Onboarding Control-Plane Contract Additions
 
-This note records the additive SourceOS/SociOS onboarding control-plane contract family.
+This note documents the additive SourceOS/SociOS onboarding and agent-workbench control-plane contract family introduced by ADR-0012.
 
 ## Contract family
 
@@ -13,31 +13,54 @@ This note records the additive SourceOS/SociOS onboarding control-plane contract
 | `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 read-only trust envelope |
-| `examples/capabilitypack.repo_release_prep.json` | Draft-only repository release-prep pack |
-| `examples/connectoractionscope.github_read_only.json` | GitHub read-only action scope |
+| `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 tying the selected objects together |
+| `examples/onboardingreceipt.first_run_read_only.json` | First-run onboarding receipt binding role, workspace, trust, capability, connector, automation, trial task, artifacts, and revocation |
 
 ## Validation
 
-Run:
+The family has a dedicated validator:
 
 ```bash
-python tools/validate_onboarding_examples.py
+make validate-onboarding-examples
 ```
 
-The focused CI workflow is `Onboarding Control Plane`.
+The target is also wired into the top-level validation lane:
+
+```bash
+make validate
+```
 
 ## Reuse boundaries
 
-This family adds a composition layer around existing SourceOS primitives. It does not replace the session, surface, skill, connector, policy, decision, capability-token, obligation, or receipt families already present in the spec.
+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
 
-Next implementation work belongs in downstream runtime and product repositories after the schema family stabilizes here.
+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`.

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.
 
 ---
 

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"
+    }
+  ]
+}