diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a2b304..a0439c0 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. - `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. diff --git a/Makefile b/Makefile index 432bcf3..b465633 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 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 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` diff --git a/docs/contract-additions/onboarding-control-plane.md b/docs/contract-additions/onboarding-control-plane.md index b700a8d..aaea464 100644 --- a/docs/contract-additions/onboarding-control-plane.md +++ b/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`. 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. --- 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" + } + ] +}