Implement SourceOS contract validation and estate scanner for agentic graph M1

[mdheller]

Objective

Implement the validator and scanner tooling required for the governed local-first agentic graph foundation.

This repo should become the practical enforcement point for the contracts defined in SourceOS-Linux/sourceos-spec.

Required commands

• sourceos contract validate <file>
• sourceos repo scan <path-or-repo>
• sourceos estate scan
• sourceos graph doctor
• sourceos sync doctor
• sourceos policy explain <decision.json>

Required contract support

Validate these schema families once added to sourceos-spec:

• SourceOSRepoManifest
• SyncEngineManifest
• SourceChannelEnvelope
• SourceGraphWrite
• AgentCapabilityLease
• PolicyDecision
• AuditEvent

Scanner behavior

The scanner should report each repo as:

• compliant
• partial
• missing-manifest
• invalid-manifest
• missing-required-engine
• missing-policy-class
• missing-audit-events

M1 target repos

• SourceOS-Linux/sourceos-spec
• SourceOS-Linux/sourceos-devtools
• SourceOS-Linux/sourceos-shell
• SourceOS-Linux/TurtleTerm
• SourceOS-Linux/agent-term
• SourceOS-Linux/agent-machine
• SourceOS-Linux/BearBrowser
• SocioProphet/agent-registry
• SocioProphet/policy-fabric
• SocioProphet/memory-mesh
• SocioProphet/prophet-workspace
• SocioProphet/sociosphere
• SocioProphet/meshrush
• SocioProphet/sherlock

Acceptance criteria

• CLI can validate a local .sourceos/manifest.json.
• CLI can scan a repo and report compliance gaps.
• CLI can emit machine-readable JSON and human-readable table output.
• CLI uses schemas from sourceos-spec or a pinned local mirror of those schemas.
• CI example added for validating manifests.

Related

• M1: Governed local-first agentic graph foundation sourceos-spec#86
• Define local-first agentic graph foundation sourceos-spec#85

[mdheller]

Progress update

Merged PR #23: Add agentic graph contract validation and repo scanner.

Implemented:

• .sourceos/manifest.json for sourceos-devtools
• sourceosctl contract validate <file>
• sourceosctl repo scan <path>
• sourceosctl estate scan [path]
• sourceosctl graph doctor
• sourceosctl sync doctor
• sourceosctl policy explain <file>
• tests for manifest validation, repo scanning, bad JSON, and doctor commands
• integration doc: docs/integration/agentic-graph-contract-validation.md

Notes:

• The first validator is intentionally dependency-light and validates the minimum repo manifest shape.
• Full JSON Schema draft 2020-12 validation should follow after SourceOS-Linux/sourceos-spec#94 lands or the schemas are vendored/pinned.

This issue is now partially satisfied and should remain open until the validator consumes the canonical schemas from sourceos-spec.