Add onboarding control-plane contracts

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`)

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

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

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

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

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

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

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