semantic: add repo ontology starter pack

.github/workflows/validate.yml

@@ -29,7 +29,11 @@ jobs:
           failed=0
           for schema in schemas/*.json; do
             echo -n "Compiling $schema ... "
-            if ajv compile -s "$schema" --strict=false 2>&1; then
+            cmd=(ajv compile -s "$schema" --strict=false --spec=draft2020)
+            for ref in schemas/*.json; do
+              [ "$ref" != "$schema" ] && cmd+=(-r "$ref")
+            done
+            if "${cmd[@]}" 2>&1; then
               echo "ok"
             else
               echo "FAILED"
@@ -189,6 +193,8 @@ jobs:
                   with open(path) as f:
                       doc = json.load(f)
                   ctx = doc.get('@context', {})
+                  if not isinstance(ctx, dict):
+                      ctx = {}
                   mapped = [k for k, v in ctx.items() if isinstance(v, str) and (v.startswith('srcos:') or v.startswith('prov:'))]
                   print(f"{path}: valid JSON, {len(mapped)} type mappings")
               except Exception as e:

docs/REPO_DESCRIPTOR_GUIDE.md

@@ -0,0 +1,78 @@
+# Repo Descriptor Guide
+
+This repository publishes the starter semantic layer for the broader SourceOS / AgentOS / SocioProphet topology.
+
+## What this starter pack contains
+
+- `semantic/context.jsonld` — JSON-LD context for repository descriptors
+- `semantic/repo-ontology.jsonld` — role vocabulary / concept graph
+- `schemas/repo_descriptor.schema.json` — JSON Schema for machine-readable repo descriptors
+- `examples/repo-descriptor.*.jsonld` — concrete examples for the current topology
+
+## Why this exists
+
+READMEs are for humans. Repo descriptors are for machines.
+
+Every important repository should eventually ship a small machine-readable descriptor so that:
+
+- agents can resolve role and adjacency without scraping prose
+- tooling can build topology maps automatically
+- documentation sites can embed structured metadata
+- policy and orchestration systems can reason over repo classes and relationships directly
+
+## Recommended placement in downstream repos
+
+Each repo should eventually publish:
+
+- `semantic/repo.jsonld`
+
+The descriptor should reference this shared context and vocabulary rather than redefining terms locally.
+
+## Minimal descriptor skeleton
+
+```json
+{
+  "@context": "https://raw.githubusercontent.com/SourceOS-Linux/sourceos-spec/main/semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:ORG:REPO",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "repo-name",
+  "description": "One-sentence role statement.",
+  "repositoryFullName": "ORG/repo-name",
+  "repoUrl": "https://github.com/ORG/repo-name",
+  "organization": "ORG",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleTypedContractRegistry",
+  "connectsTo": [],
+  "notThisRepo": []
+}
+```
+
+## Current canonical role set
+
+- `rolePlatformWorkspaceController`
+- `roleLinuxIntegrationSpine`
+- `roleTypedContractRegistry`
+- `roleWorkstationConformanceLane`
+- `roleAutomationCommons`
+- `roleOSSubstrate`
+- `rolePublicDocsSurface`
+- `roleStarterScaffold`
+
+## Current rule of use
+
+- prefer one primary topology role per repo
+- use `connectsTo` for explicit adjacency
+- use `notThisRepo` to block common category mistakes
+- use `consumesVocabularyFrom` when the repo imports the canonical vocabulary from this repo
+
+## Near-term follow-up
+
+Next we should add one real `semantic/repo.jsonld` file to each core repo:
+
+- `SociOS-Linux/agentos-spine`
+- `SocioProphet/sociosphere`
+- `SociOS-Linux/workstation-contracts`
+- `SociOS-Linux/SourceOS`
+- `SociOS-Linux/socios`
+- `SociOS-Linux/socioslinux-web`

examples/repo-descriptor.SourceOS.jsonld

@@ -0,0 +1,27 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:SourceOS",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "SourceOS",
+  "description": "Immutable, local-first operating-system substrate for workstation and edge lanes.",
+  "repositoryFullName": "SociOS-Linux/SourceOS",
+  "repoUrl": "https://github.com/SociOS-Linux/SourceOS",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleOSSubstrate",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "opt-in automation commons",
+    "workspace controller",
+    "public docs site",
+    "canonical typed-contract registry"
+  ]
+}

examples/repo-descriptor.agentos-spine.jsonld

@@ -0,0 +1,28 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "agentos-spine",
+  "description": "Current Linux-side integration/workspace spine for AgentOS / SourceOS.",
+  "repositoryFullName": "SociOS-Linux/agentos-spine",
+  "repoUrl": "https://github.com/SociOS-Linux/agentos-spine",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleLinuxIntegrationSpine",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:sociosphere",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "immutable OS substrate",
+    "final typed-contract registry",
+    "public docs site",
+    "opt-in automation plane"
+  ]
+}

examples/repo-descriptor.socios.jsonld

@@ -0,0 +1,31 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:socios",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "socios",
+  "description": "Opt-in community automation commons for SourceOS.",
+  "repositoryFullName": "SociOS-Linux/socios",
+  "repoUrl": "https://github.com/SociOS-Linux/socios",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleAutomationCommons",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SocioProphet:sociosphere",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "optionalLayerFor": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "base OS substrate",
+    "mandatory dependency of SourceOS",
+    "public docs site",
+    "canonical typed-contract registry"
+  ]
+}

examples/repo-descriptor.socioslinux-web.jsonld

@@ -0,0 +1,33 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:socioslinux-web",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "socioslinux-web",
+  "description": "Linux public web and docs surface for the Socios Linux stack.",
+  "repositoryFullName": "SociOS-Linux/socioslinux-web",
+  "repoUrl": "https://github.com/SociOS-Linux/socioslinux-web",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "rolePublicDocsSurface",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:sociosphere",
+    "urn:sourceos:repo:SocioProphet:socioprophet"
+  ],
+  "publicSurfaceFor": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SociOS-Linux:socios"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "workspace controller",
+    "image builder",
+    "immutable substrate",
+    "canonical typed-contract registry"
+  ]
+}

examples/repo-descriptor.sociosphere.jsonld

@@ -0,0 +1,29 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SocioProphet:sociosphere",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "sociosphere",
+  "description": "Platform meta-workspace controller for the broader SocioProphet platform.",
+  "repositoryFullName": "SocioProphet/sociosphere",
+  "repoUrl": "https://github.com/SocioProphet/sociosphere",
+  "organization": "SocioProphet",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "rolePlatformWorkspaceController",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:socioprophet",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "Linux image builder",
+    "immutable OS substrate",
+    "canonical typed-contract registry",
+    "public site"
+  ]
+}

examples/repo-descriptor.sourceos-spec.jsonld

@@ -0,0 +1,28 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "sourceos-spec",
+  "description": "Canonical typed-contract, JSON-LD, and shared vocabulary lane for SourceOS / AgentOS.",
+  "repositoryFullName": "SourceOS-Linux/sourceos-spec",
+  "repoUrl": "https://github.com/SourceOS-Linux/sourceos-spec",
+  "organization": "SourceOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleTypedContractRegistry",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:sociosphere",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "workspace controller",
+    "image builder",
+    "public docs site",
+    "opt-in automation plane"
+  ]
+}

examples/repo-descriptor.workstation-contracts.jsonld

@@ -0,0 +1,27 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "workstation-contracts",
+  "description": "Workstation and CI contract / conformance lane for Linux-first execution paths.",
+  "repositoryFullName": "SociOS-Linux/workstation-contracts",
+  "repoUrl": "https://github.com/SociOS-Linux/workstation-contracts",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleWorkstationConformanceLane",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:sociosphere"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "runner or workspace controller",
+    "image builder",
+    "public docs site",
+    "opt-in automation commons"
+  ]
+}