diff --git a/docs/REPO_DESCRIPTOR_GUIDE.md b/docs/REPO_DESCRIPTOR_GUIDE.md index 81a69bf..6a8de75 100644 --- a/docs/REPO_DESCRIPTOR_GUIDE.md +++ b/docs/REPO_DESCRIPTOR_GUIDE.md @@ -58,6 +58,7 @@ The descriptor should reference this shared context and vocabulary rather than r - `roleOSSubstrate` - `rolePublicDocsSurface` - `roleStarterScaffold` +- `roleDeveloperToolchain` ## Current rule of use @@ -76,3 +77,4 @@ Next we should add one real `semantic/repo.jsonld` file to each core repo: - `SociOS-Linux/SourceOS` - `SociOS-Linux/socios` - `SociOS-Linux/socioslinux-web` +- `SourceOS-Linux/sourceos-devtools` diff --git a/docs/adr/ADR-2026-04-devtools-boundary.md b/docs/adr/ADR-2026-04-devtools-boundary.md new file mode 100644 index 0000000..283ccfd --- /dev/null +++ b/docs/adr/ADR-2026-04-devtools-boundary.md @@ -0,0 +1,47 @@ +# ADR: Developer Tools Repo Boundary + +**Date:** 2026-04-30 +**Status:** Accepted + +--- + +## Context + +SourceOS needs a dedicated home for Linux-native developer tooling: Nix/devshell orchestration, NLBoot/operator tooling, lab profile selection, release tooling, local AI governance utilities, and SourceOS workstation bootstrap scripts. + +Without a clear boundary, developer tooling risks drifting into `sourceos-spec` (the typed-contract registry) or into OS substrate repos, causing confusion about ownership, validation scope, and consumable contracts. + +## Decision + +`SourceOS-Linux/sourceos-devtools` is established as the canonical home for all SourceOS developer tooling. Its topology role is `roleDeveloperToolchain`. + +`sourceos-spec` registers the repo in the canonical topology (repo descriptor example and `connectsTo` link) but does **not** carry any devtools implementation, shell scripts, Nix expressions, or operator tooling. + +Specifically, `sourceos-devtools` owns: + +- Nix flakes and devshell configurations +- NLBoot operator and lab-profile selection scripts +- Release tooling (cut, sign, publish) +- Local AI governance CLI utilities +- SourceOS workstation bootstrap helpers +- `repo.maturity.yaml` for its own maturity tracking + +## Alternatives considered + +| Alternative | Reason not chosen | +|-------------|------------------| +| Embed devtools in `sourceos-spec` | Violates the typed-contract-registry boundary; spec must stay normative-only | +| Embed devtools in `agentos-spine` | Spine owns Linux integration, not developer ergonomics or release tooling | +| Embed devtools in `SourceOS` (substrate) | Substrate is immutable OS layer; devtools are operator-time, not build-time | + +## Consequences + +- `sourceos-spec` remains a pure typed-contract and vocabulary registry with no executable devtools content. +- `sourceos-devtools` consumes contracts and vocabulary from `sourceos-spec` but does not redefine them. +- Agents and tooling can resolve the devtools repo via `urn:sourceos:repo:SourceOS-Linux:sourceos-devtools` using the canonical topology descriptor. + +## References + +- [GitHub issue #70: Admin task: create and bootstrap sourceos-devtools repo](https://github.com/SourceOS-Linux/sourceos-spec/issues/70) +- `examples/repo-descriptor.sourceos-devtools.jsonld` — canonical topology entry +- `semantic/repo-ontology.jsonld` — `roleDeveloperToolchain` definition diff --git a/examples/repo-descriptor.sourceos-devtools.jsonld b/examples/repo-descriptor.sourceos-devtools.jsonld new file mode 100644 index 0000000..2a78caa --- /dev/null +++ b/examples/repo-descriptor.sourceos-devtools.jsonld @@ -0,0 +1,25 @@ +{ + "@context": "../semantic/context.jsonld", + "@id": "urn:sourceos:repo:SourceOS-Linux:sourceos-devtools", + "@type": ["RepoDescriptor", "Repository"], + "name": "sourceos-devtools", + "description": "SourceOS Developer Tools: Linux-native developer tooling, lab profile selection, Nix/devshell orchestration, release tooling, local AI governance utilities, and SourceOS workstation bootstrap.", + "repositoryFullName": "SourceOS-Linux/sourceos-devtools", + "repoUrl": "https://github.com/SourceOS-Linux/sourceos-devtools", + "organization": "SourceOS-Linux", + "defaultBranch": "main", + "semanticDescriptorVersion": "0.1.0", + "topologyRole": "roleDeveloperToolchain", + "connectsTo": [ + "urn:sourceos:repo:SourceOS-Linux:sourceos-spec", + "urn:sourceos:repo:SociOS-Linux:agentos-spine", + "urn:sourceos:repo:SociOS-Linux:SourceOS" + ], + "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec", + "notThisRepo": [ + "typed-contract registry", + "immutable OS substrate", + "public docs site", + "platform workspace controller" + ] +} diff --git a/examples/repo-descriptor.sourceos-spec.jsonld b/examples/repo-descriptor.sourceos-spec.jsonld index 7a23f24..f040d87 100644 --- a/examples/repo-descriptor.sourceos-spec.jsonld +++ b/examples/repo-descriptor.sourceos-spec.jsonld @@ -16,7 +16,8 @@ "urn:sourceos:repo:SociOS-Linux:SourceOS", "urn:sourceos:repo:SociOS-Linux:socios", "urn:sourceos:repo:SocioProphet:sociosphere", - "urn:sourceos:repo:SociOS-Linux:socioslinux-web" + "urn:sourceos:repo:SociOS-Linux:socioslinux-web", + "urn:sourceos:repo:SourceOS-Linux:sourceos-devtools" ], "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec", "notThisRepo": [ diff --git a/semantic/context.jsonld b/semantic/context.jsonld index d0e4dee..31d4f12 100644 --- a/semantic/context.jsonld +++ b/semantic/context.jsonld @@ -29,6 +29,7 @@ "roleAutomationCommons": "srcos:role/AutomationCommons", "roleOSSubstrate": "srcos:role/OSSubstrate", "rolePublicDocsSurface": "srcos:role/PublicDocsSurface", - "roleStarterScaffold": "srcos:role/StarterScaffold" + "roleStarterScaffold": "srcos:role/StarterScaffold", + "roleDeveloperToolchain": "srcos:role/DeveloperToolchain" } } diff --git a/semantic/repo-ontology.jsonld b/semantic/repo-ontology.jsonld index 55ed947..3fbacb5 100644 --- a/semantic/repo-ontology.jsonld +++ b/semantic/repo-ontology.jsonld @@ -48,6 +48,12 @@ "@type": "TopologyRole", "name": "Starter Scaffold", "description": "Bootstrap or starter repository for interfaces, policy, integration, or registry scaffolding. Not the canonical controller or spec lane." + }, + { + "@id": "roleDeveloperToolchain", + "@type": "TopologyRole", + "name": "Developer Toolchain", + "description": "Linux-native developer tooling home: Nix/devshell orchestration, NLBoot/operator tooling, lab profile selection, release tooling, local AI governance utilities, and SourceOS workstation bootstrap." } ] } diff --git a/semantic/repo.jsonld b/semantic/repo.jsonld index 947e412..c24dd16 100644 --- a/semantic/repo.jsonld +++ b/semantic/repo.jsonld @@ -16,7 +16,8 @@ "urn:sourceos:repo:SociOS-Linux:SourceOS", "urn:sourceos:repo:SociOS-Linux:socios", "urn:sourceos:repo:SocioProphet:sociosphere", - "urn:sourceos:repo:SociOS-Linux:socioslinux-web" + "urn:sourceos:repo:SociOS-Linux:socioslinux-web", + "urn:sourceos:repo:SourceOS-Linux:sourceos-devtools" ], "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec", "notThisRepo": [