Replay onboarding control-plane contracts on current main

.github/workflows/onboarding-control-plane.yml

@@ -0,0 +1,54 @@
+name: Onboarding Control Plane
+
+on:
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "schemas/WorkspaceScope.json"
+      - "schemas/TrustMode.json"
+      - "schemas/CapabilityPack.json"
+      - "schemas/ConnectorActionScope.json"
+      - "schemas/AutomationTemplate.json"
+      - "schemas/OnboardingReceipt.json"
+      - "examples/workspacescope.json"
+      - "examples/trustmode.read_only_analyst.json"
+      - "examples/capabilitypack.repo_release_prep.json"
+      - "examples/connectoractionscope.github_read_only.json"
+      - "examples/automationtemplate.yesterday_git_activity.json"
+      - "examples/onboardingreceipt.first_run_read_only.json"
+      - "tools/validate_onboarding_examples.py"
+      - ".github/workflows/onboarding-control-plane.yml"
+  push:
+    branches: ["main", "replay/onboarding-control-plane-current-main"]
+    paths:
+      - "schemas/WorkspaceScope.json"
+      - "schemas/TrustMode.json"
+      - "schemas/CapabilityPack.json"
+      - "schemas/ConnectorActionScope.json"
+      - "schemas/AutomationTemplate.json"
+      - "schemas/OnboardingReceipt.json"
+      - "examples/workspacescope.json"
+      - "examples/trustmode.read_only_analyst.json"
+      - "examples/capabilitypack.repo_release_prep.json"
+      - "examples/connectoractionscope.github_read_only.json"
+      - "examples/automationtemplate.yesterday_git_activity.json"
+      - "examples/onboardingreceipt.first_run_read_only.json"
+      - "tools/validate_onboarding_examples.py"
+      - ".github/workflows/onboarding-control-plane.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  validate-onboarding-control-plane:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install validator dependencies
+        run: python -m pip install --upgrade pip jsonschema
+      - name: Validate onboarding examples
+        run: python tools/validate_onboarding_examples.py

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

@@ -0,0 +1,43 @@
+# Onboarding Control-Plane Contract Additions
+
+This note records the additive SourceOS/SociOS onboarding control-plane contract family.
+
+## 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:` |
+
+## 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/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 |
+
+## Validation
+
+Run:
+
+```bash
+python tools/validate_onboarding_examples.py
+```
+
+The focused CI workflow is `Onboarding Control Plane`.
+
+## 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.
+
+## Follow-on work
+
+Next implementation work belongs in downstream runtime and product repositories after the schema family stabilizes here.

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

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

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