diff --git a/README.md b/README.md index 68154c52..f9deb68a 100644 --- a/README.md +++ b/README.md @@ -1,368 +1,28 @@ -# [open-agentic-platform](https://statecrafting.github.io/open-agentic-platform/) [![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE) [![Specs: 225](https://img.shields.io/badge/specs-225-informational)](specs/) [![Languages](https://img.shields.io/badge/lang-Rust%20%7C%20TypeScript-orange)](#) [![Status: pre-alpha](https://img.shields.io/badge/status-pre--alpha-yellow)](#status) -![OAP Control Plane and OPC Execution Plane](.github/img/open-agentic-platform-github-banner.jpg) - -**Frozen, hash-verifiable specs as the unit of governance for agent -execution.** Every change is bound to a spec; every spec compiles to a -deterministic JSON registry; every agent action is reconcilable to the spec -that authorised it — and the audit chain is a single artifact you can hand -to a regulator. - -- **Spec spine**: 225 markdown specs compile to a deterministic - `registry.json`. Drift between spec and code fails CI before merge - ([spec 127](specs/127-spec-code-coupling-gate/spec.md)). -- **Governed agent execution** — agents act through scoped tools, policy - gates, and permission tiers. SHA-256 proof chains and JSONL audit logs - are the runtime substrate, not bolt-on observability. Every factory - run emits a self-authenticating `governance-certificate.json` - ([spec 102](specs/102-governed-excellence/spec.md)) that an auditor - can verify independently — `make verify-certificate FILE=...` exits - non-zero on tamper with a specific artifact-hash diagnostic. -- **Identity-bounded collaboration** — Rauthy issues OIDC tokens, deployd-api - enforces scope at every request, the spec spine defines what each scope - is allowed to authorise. - -**Same discipline, applied to ourselves.** Every release ships per-target -CycloneDX SBOMs (`sbom-desktop-aarch64-apple-darwin.cdx.json`, -`sbom-desktop-x86_64-pc-windows-msvc.cdx.json`, -`sbom-desktop-x86_64-unknown-linux-gnu.cdx.json`, `sbom-tools.cdx.json`) -and an aggregate `open-agentic-platform-release.cyclonedx.json`, alongside -SHA256-verifiable installers. The provenance discipline applied to -governed agent execution is the discipline applied to the project's own -releases. - -**Try it now:** [install a prebuilt cockpit ↓](#install) or [reproduce -the OWASP ASI 2026 traceability artifact from source ↓](#try-it). - -> Licensed **AGPL-3.0**. Strong copyleft is deliberate: the audit chain -> is a public good for regulated buyers, and AGPL prevents that work from -> being absorbed into proprietary control planes that strip the -> traceability while keeping the engine. - ---- - -## What this is - -OAP is a governed control plane for AI-native software delivery, built -around three concrete components that already exist in this tree: - -The **spec spine** (`specs/`) is the authoritative design record. Every -feature is a markdown file with YAML frontmatter, compiled by -[`spec-spine compile`](https://crates.io/crates/spec-spine-cli) into shards under `.derived/spec-registry/by-spec/`. -Specs are read through `spec-spine registry` subcommands (never by ad-hoc parsing), -which makes the spec corpus a typed, query-able surface -([spec 103](specs/103-init-protocol-governed-reads/spec.md)). - -The **platform layer** (`platform/`) is the organisational control plane: -[Rauthy](platform/charts/rauthy/) for OIDC identity, -[`deployd-api-rs`](platform/services/deployd-api-rs/) for scope-gated -deployment orchestration, [Encore.ts statecraft](platform/services/statecraft/) -for governance UX, and Helm charts for managed-K8s deployment. - -The **OPC desktop** (`product/apps/opc/`) is a Tauri v2 + React cockpit where -humans and agents share a single execution surface — local workspaces, git -context, semantic and structural analysis, snapshots, approval gates. - -## Who this is for - -- **OWASP ASI 2026 practitioners** evaluating governed agent runtimes. The - compliance-report CLI emits a real ASI-control-to-spec mapping today. -- **Regulated-industry security and compliance teams** who need a single - audit chain artifact rather than a stitched-together evidence pack. -- **Multi-cloud platform buyers** with Azure-heavy estates, - uneven GCP, corner-case AWS, and data-residency constraints that rule out - closed control planes. -- **Engineering platform teams** building internal AI delivery pipelines - where governance must be the execution model, not a sidecar. - -## How it works - -### Architectural layers - -```mermaid -flowchart LR - subgraph OPC[OPC -- Local Cockpit] - O1[Local workspaces] - O2[Desktop UX] - O3[Git and GitHub context] - O4[Semantic and structural analysis] - O5[Snapshots and checkpoints] - O6[Human + agent collaboration] - end - - subgraph SPINE[Shared Spec Spine] - S1[Spec definitions] - S2[Canonical feature registry] - S3[Changesets and traceability] - S4[Approval and policy metadata] - S5[Compiled governance truth] - end - - subgraph PLATFORM[Platform -- Organisational Control Plane] - P1[Identity and access] - P2[Policy engine] - P3[Approval centre] - P4[Deployment orchestration] - P5[Activity timeline and audit] - P6[Multi-repo feature graph] - end - - OPC <--> SPINE - PLATFORM <--> SPINE - OPC <--> PLATFORM -``` - -OPC is where work is experienced. Platform is where work is governed. The -spec spine keeps both sides honest. - -### Trust fabric — one continuous path - -```mermaid -flowchart LR - User[User or Agent] -->|OIDC login| Rauthy[Rauthy
identity] - Rauthy -->|JWT + oap scope| API[deployd-api
scope gate] - API -->|spec-bound action| Engine[factory-engine
policy kernel] - Engine -->|recorded| Index[codebase-index
spec-to-code map] - Engine -->|hashed| Cert[governance certificate
live emission + verifier] -``` - -You operate every node in the path. There is no SaaS in the trust path -unless you put it there. - -## Adapters - -The factory engine generates code through pluggable adapters that -implement a shared contract. Adapter manifests historically lived in -the repo-root `factory/adapters/*/manifest.yaml` directory; spec 108 -retired that directory and moved the canonical store into statecraft's -`factory_adapters` table, then spec 139 absorbed those rows into the -universal `factory_artifact_substrate` table. The file-backed scope -snapshot at `platform/services/statecraft/api/factory/adapter-scopes.json` -is the static fallback that `spec-spine index` hashes per spec 160; per-org -content is materialised at runtime via the substrate. - -- **`acme-vue-encore`** — the manifest-declared adapter of the owned - `factory` upstream and the only scope entry in - `adapter-scopes.json` (a derived projection of the admitted adapter - sub-envelope, regenerated by `adapter-scopes-compiler` from the - manifest's `governance:` section — specs 198 FR-012 / 199 FR-007; - first derivation ran 2026-06-11 against the sealed admission). The - active scaffold - target, used end-to-end by the tenant onboarding path; the earlier - `acme-vue-node` hardening specs - ([138](specs/138-statecraft-create-realised-scaffold/spec.md), - [140](specs/140-acme-vue-node-scaffold-source-id-cutover/spec.md), - [141](specs/141-acme-vue-node-source-id-template-name-alignment/spec.md)) - are its lineage. -- The legacy example adapters (`next-prisma`, `rust-axum`, - `encore-react`) were retired upstream (spec 199 FR-007). The factory - contract's multi-adapter breadth is governed by the open-standard - schemas (spec 197) rather than by in-tree scope entries. - -## License (and why AGPL) - -OAP is licensed under the [GNU Affero General Public License v3.0](LICENSE). -Strong copyleft is the strategic choice. The intended beneficiary is the -public — regulated buyers who depend on a governance layer cannot afford -to have the audit chain absorbed into a proprietary control plane that -serves the audit chain back as a paid feature. AGPL closes the network -loophole that would let a hosted offering capture the value while -stripping the traceability commitments the spec spine encodes. If you are -building a closed product on top, this is the wrong substrate; if you are -building an internal governed platform or a public good that hardens -others' governance, it is the right one. - -## Install - -Prebuilt OPC desktop installers ship with each -[release](https://github.com/statecrafting/open-agentic-platform/releases): - -- **macOS (Apple Silicon)** — `opc__aarch64.dmg` -- **Windows** — `opc__x64-setup.exe` (NSIS) or - `opc__x64_en-US.msi` -- **Linux** — `opc__amd64.AppImage`, `opc__amd64.deb`, - or `opc--1.x86_64.rpm` - -Verify before installing — every installer ships an `.sha256` sidecar: - -```bash -sha256sum -c opc_0.3.2_aarch64.dmg.sha256 -``` - -Per-target CycloneDX SBOMs (`sbom-desktop-.cdx.json`) and the -aggregate `open-agentic-platform-release.cyclonedx.json` are release -assets — verify the bill of materials before the binary runs in your -environment. The `oap-tools-.tar.gz` archive ships `spec-lint` plus OAP-specific -overlay tools. The generic spec engine is `spec-spine` from crates.io (install -via `cargo install spec-spine-cli --version 0.10.0 --locked` or `make setup`). - -## Try it - -These commands work from a fresh clone today and produce real artifacts. -The OWASP ASI 2026 traceability mapping is a single deterministic JSON -file; the spec/code coupling and codebase index are governed reads -through compiled consumer binaries. - -```bash -make setup -# Installs spec-spine CLI (0.10.0), builds OAP overlay tools, -# compiles the registry, fetches the axiomregent sidecar binary. - -./tools/oap/oap-registry-enrich/target/release/oap-registry-enrich \ - compliance-report --framework owasp-asi-2026 --json -# Emits the ASI-control-to-spec mapping. This is the traceability -# artifact: structured, deterministic, and reproducible from the -# compiled registry. (Moved from registry-consumer in Cut D W-06b; -# compliance is an OAP-specific overlay rather than a generic -# spec-spine concept.) - -spec-spine registry status-report --json --nonzero-only -# Lifecycle inventory across the 225-spec corpus. -# 181 approved, 9 draft, 35 superseded. - -spec-spine index render -cat .derived/codebase-index/CODEBASE-INDEX.md -# Renders the spec-to-code map. The 'Spec' column is the -# traceability surface for every Rust crate and npm package. - -# Governance certificate — the load-bearing artifact (spec 102). -# `make build-certificate` reads any factory run directory and writes a -# self-authenticating governance-certificate.json binding requirements -# hash, frozen Build Spec hash, per-stage artifact hashes, and the -# certificate's own SHA-256 into one auditable JSON file. To make the -# Try it block fresh-clone reproducible, we synthesise a one-stage run -# directory with a single artifact: -mkdir -p /tmp/oap-demo-run/s0-preflight -echo '{"ok":true}' > /tmp/oap-demo-run/s0-preflight/preflight.json -echo "tenant onboarding requirements" > /tmp/oap-demo-reqs.md - -make build-certificate FILE=/tmp/oap-demo-run \ - BUSINESS_DOCS=/tmp/oap-demo-reqs.md \ - ADAPTER=acme-vue-node -# governance certificate written: /tmp/oap-demo-run/governance-certificate.json -# (status=Complete, stages=6, hash=<16-char prefix>) - -make verify-certificate FILE=/tmp/oap-demo-run/governance-certificate.json \ - ARTIFACT_DIR=/tmp/oap-demo-run -# governance certificate VERIFIED (exit 0) - -# Tamper an artifact and verify again — the cert rejects with a -# specific diagnostic, exit 1: -echo "TAMPERED" > /tmp/oap-demo-run/s0-preflight/preflight.json -make verify-certificate FILE=/tmp/oap-demo-run/governance-certificate.json \ - ARTIFACT_DIR=/tmp/oap-demo-run -# governance certificate INVALID (1 error(s)): -# - artifact hash mismatch: s0-preflight/preflight.json: -# expected , got -# The verifier does not trust the system that produced the certificate. -``` - -`factory-run` itself emits `governance-certificate.json` automatically at -the end of every pipeline run (success or halt) under -`/.factory/runs//`. The two `make` targets above cover -retroactive certification and the auditor's independent verify path, -which is what makes the certificate trustworthy. - -For the full daily-development loop: - -```bash -make ci # ~5 min warm — the daily dev loop (spec 135) -make ci-strict # ~90 min — full parity mirror, pre-merge / parity-investigation -make dev # OPC desktop (Vite + Tauri, hot-reload) -``` - -## Status - -OAP is **pre-alpha, stealth, single-developer**. No public releases. No -external contributors yet. The status section below records what works -today vs. what is staged and what is roadmap, by spec ID. - -### Works today - -- **Spec compilation and querying:** 225 specs compile deterministically. - `spec-spine registry` is a typed read-only CLI; ad-hoc JSON parsing is a - workflow violation ([spec 103](specs/103-init-protocol-governed-reads/spec.md)). -- **Spec/code coupling gate:** every code path claimed by a spec's - `implements:` list must change with the spec - ([spec 127](specs/127-spec-code-coupling-gate/spec.md)). -- **Codebase index:** spec-to-code traceability for every crate and - package ([spec 101](specs/101-codebase-index-mvp/spec.md)). -- **OWASP ASI 2026 compliance map:** all ten controls (ASI01–ASI10) map - to declaring approved specs via `oap-registry-enrich compliance-report` - (moved from `registry-consumer` in Cut D W-06b; the spec-spine - `registry-consumer` no longer carries OAP-specific overlays). Each - control's residual has a named owner: spec 198's all-ten analysis - assigns every residual to a follow-on draft spec (200–211), and drafts - enter the report at approval. -- **Governance certificate — live emission** ([spec 102](specs/102-governed-excellence/spec.md)) - — every `factory-run` writes `governance-certificate.json` under the - run directory at termination (success or halt), binding requirements - hash, frozen Build Spec hash, per-stage artifact hashes, and a - self-authenticating SHA-256 over the canonical JSON. `make - verify-certificate FILE=...` is the auditor's independent verifier: - exit 0 on a clean cert, exit 1 with a specific artifact-hash-mismatch - diagnostic on tamper. `make build-certificate FILE=...` covers the - retroactive-certification flow. The companion sister binary - `verify-certificate` does not trust the system that produced the - certificate (FR-007). -- **Identity (Rauthy)** — production-grade OIDC chart with HA - ([spec 106](specs/106-rauthy-native-oidc-and-membership/spec.md)). -- **Scope-gated deployment** — `deployd-api-rs` enforces - `DEPLOYD_REQUIRED_SCOPE` on every request against Rauthy-issued JWTs. -- **Supply chain gates** — `cargo-deny` + `pnpm audit` + `npm audit`, - blocking from day 0 ([spec 116](specs/116-supply-chain-policy-gates/spec.md)). -- **Schema parity walker** — Rust ↔ TypeScript contract drift fails CI - ([spec 125](specs/125-schema-parity-walker-rebuild/spec.md)). -- **Azure AKS deployment** — `make deploy-azure` against - `platform/infra/terraform/envs/dev/`. -- **Hetzner K3s deployment** — `make deploy-hetzner` via standalone Helm - bootstrap path. - -### Experimental / partially wired - -- **Governance certificate — schema fixtures and SSE emission** - ([spec 102](specs/102-governed-excellence/spec.md) FR-002, FR-010) — - pipeline emission is wired and the verifier round-trip is part of CI, - but a few targets in spec 102 remain open: the explicit JSON Schema - artifact at `factory/contract/schemas/governance-certificate.schema.json` - (FR-002) is not yet committed (the Rust `serde` types are the de-facto - schema), and the `governance-certificate-generated` SSE event over - `LocalEventNotifier` (FR-010) is not yet plumbed. Phases B/C/D of spec - 102 (policy-bridge composition, traceability unification, OWASP - hardening) remain partially wired against the per-FR success criteria. -- **Factory pipeline** — two-phase engine (s0–s5 sequential, s6a–s6g - fan-out) with four registered adapters; acme-vue-node is the production - scaffold target. -- **AWS / GCP / DigitalOcean Terraform modules** - ([spec 072](specs/072-multi-cloud-k8s-portability/spec.md)) — modules - exist in `platform/infra/terraform/modules/` but no environment - directories instantiate them yet. Helm charts and Rauthy/deployd-api - are cloud-neutral. - -### Roadmap - -- **Tenant environment access gates** - ([spec 137](specs/137-tenant-environment-access-gates/spec.md), draft) — - binds Rauthy-issued scopes to tenant-environment-scoped policy-kernel - permissions. Planning artifacts (`plan.md`, `tasks.md`) landed - 2026-05-04; implementation is next. -- **End-to-end pipeline → certificate emission** — closure of spec 102. -- **AWS / GCP / DigitalOcean environments** — instantiating - `envs/aws-dev/`, `envs/gcp-dev/`, `envs/do-dev/` against the existing - Terraform modules. - -## Layout - -| Path | What lives there | -|---|---| -| `specs/` | The authoritative spec spine. 225 specs as of 2026-07-02. | -| `tools/` | Rust CLIs: `spec-lint` (OAP-specific), OAP overlay tools (`oap-registry-enrich`, `oap-code-index-enrich`, `policy-compiler`, others). The generic spec engine is the published `spec-spine` CLI (crates.io). | -| `crates/` | Library crates: `factory-engine`, `factory-contracts`, `policy-kernel`, `orchestrator`, `agent`, `tool-registry`, `axiomregent`, `xray`, others. | -| `product/apps/opc/` | OPC desktop (Tauri v2 + React + TypeScript). | -| `platform/` | Identity, deployd-api, statecraft, Helm charts, Terraform infra. | -| `.derived/` | Compiler-emitted machine truth: `spec-registry/`, `codebase-index/`. Read through consumer binaries only. | -| `.claude/` | Agent and command definitions used by the development environment. See `CLAUDE.md` and `AGENTS.md`. | - -Full setup, prerequisites, and platform-service development: -[`docs/DEVELOPERS.md`](docs/DEVELOPERS.md). Repository conventions and architectural -rules: [`CLAUDE.md`](CLAUDE.md). Compiler architecture and registry -contract: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). +# open-agentic-platform + +> **Archived.** Superseded by [statecraft](https://github.com/statecrafting/statecraft), +> the governed agentic delivery control plane. + +The Open Agentic Platform was the first full expression of governed agentic +delivery: frozen, hash-verifiable specs as the unit of governance, a web +control plane, and a desktop execution cockpit (OPC). In July 2026 the system +was rebuilt ground-up as **Statecraft**, and the pieces live on under new names: + +- The control plane continues as [statecraft](https://github.com/statecrafting/statecraft): + tenants, factory, fleet, and the governance UI, itself the first production + [enrahitu](https://github.com/statecrafting/enrahitu) app. +- The desktop cockpit is retired; its governance verbs continue in + [statecraft-cli](https://github.com/statecrafting/statecraft-cli), one binary + serving humans as a CLI and agents as an MCP server. +- The spec-governance engine continues as + [spec-spine](https://github.com/statecrafting/spec-spine). +- The reusable primitives were extracted as + [action-gate](https://github.com/statecrafting/action-gate), + [attest-ledger](https://github.com/statecrafting/attest-ledger), + [trust-window](https://github.com/statecrafting/trust-window), and + [canonical-keysort-json](https://github.com/statecrafting/canonical-keysort-json). + +The family front door is [statecraft.ing](https://statecraft.ing). This +repository stays public as the historical record the early essays on +[bartekus.com](https://bartekus.com/writing) refer to; the original README and +the full codebase remain in its git history.