Skip to content
This repository was archived by the owner on Jul 23, 2026. It is now read-only.

docs: tombstone; superseded by the Statecraft family #587

Merged
bartekus merged 1 commit into from
Jul 23, 2026
Merged

docs: tombstone; superseded by the Statecraft family #587

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
396 changes: 28 additions & 368 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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<br/>identity]
Rauthy -->|JWT + oap scope| API[deployd-api<br/>scope gate]
API -->|spec-bound action| Engine[factory-engine<br/>policy kernel]
Engine -->|recorded| Index[codebase-index<br/>spec-to-code map]
Engine -->|hashed| Cert[governance certificate<br/>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_<version>_aarch64.dmg`
- **Windows** — `opc_<version>_x64-setup.exe` (NSIS) or
`opc_<version>_x64_en-US.msi`
- **Linux** — `opc_<version>_amd64.AppImage`, `opc_<version>_amd64.deb`,
or `opc-<version>-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-<triple>.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-<triple>.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 <hash-A>, got <hash-B>
# 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
`<project>/.factory/runs/<run-id>/`. 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.