// SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell = OikosBot Jonathan D.A. Jewell v0.1.0-dev :toc: macro :toclevels: 2 :icons: font :source-highlighter: rouge

image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link=“https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/oikosbot”] image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link=“https://opensource.org/licenses/MPL-2.0”]

A code-analysis GitHub/GitLab App that adds ecological and economic review to pull requests.

[NOTE]

This repository is only OikosBot, and it is easy to confuse with two similarly-named-but-separate things:

See link:DISAMBIGUATION.adoc[DISAMBIGUATION.adoc] for the full breakdown.

toc::[]

== Documentation

For a map of all documentation — grouped by audience (developer / maintainer / end-user) and by concept — see link:docs/README.adoc[docs/README.adoc].

== Status

0.1.0-dev. OikosBot is not currently deployed in production.

The Rust analysis workspace (crates/oikosbot-*: CLI, analysis engine, metrics, SARIF output, and Eclexia policy evaluation) builds and tests cleanly and is the most complete surface — it was extracted from the former gitbot-fleet/bots/sustainabot/ and renamed.

The AffineScript webhook receiver (bot-integration-affine/) is a scaffold. HMAC-SHA256 webhook signature verification is implemented in bot-integration-affine/src/Webhook.affine (constant-time, via the hpm-crypto RSR FFI), and the upstream AffineScript standard-library prerequisites have landed (json RSR rewire, affinescript#421; Http server RSR rewire, affinescript#425). The webhook → analyse → comment orchestration is now wired in source (src/Payload.affine extracts the PR fields and handle_github_webhook runs Oikos.handle_pr_event); what remains is binding the HTTP listener (Sub.http_server), which is gated on the stdlib Http::Server host type. (The AffineScript changes are unverified — there is no AS toolchain in this environment.)

The Haskell analyzer scaffold (analyzers/code-haskell/) builds independently.

== Repository Layout

[source,text]

oikosbot/ |– crates/ # Rust workspace (oikosbot-* analysis engine + CLI) | |– oikosbot-cli/ # oikosbot binary (analyze / check / report) | |– oikosbot-analysis/ # tree-sitter analysis + eco/econ heuristics | |– oikosbot-metrics/ # shared metric/result types | |– oikosbot-sarif/ # SARIF report generation | |– oikosbot-eclexia/ # Eclexia (.ecl) policy evaluation | -- oikosbot-fleet/ # OPTIONAL gitbot-fleet bridge (excluded by default) |-- bot-integration-affine/ # AffineScript webhook receiver (in flight) |-- analyzers/code-haskell/ # Haskell eco/econ/quality analysis engine |-- policy-engine/ # Datalog and DeepProbLog policy rules |-- policies/ # Eclexia (.ecl) policy definitions |-- config/oikos.yaml # Bot configuration |-- databases/ontology/ # eco.ttl — VeriSimDB semantic-witness ontology seed |-- examples/ # Example CI integration |-- fuzz/ # cargo-fuzz targets (excluded from the workspace) |-- docs/ # GITHUB_APP_SETUP.adoc, tech-debt audit |-- ARCHITECTURE.adoc # Platform architecture (target design) |-- DISAMBIGUATION.adoc # oikos vs OikosBot vs sustainabot |-- QUICKSTART.adoc # CLI quickstart– DEPLOY.adoc # Deployment status and runbook notes —-

== Data Layer

OikosBot persists analysis results, code-relationship graphs, and the eco/econ knowledge base in a single identity-consonance store, https://github.com/hyperpolymath/verisimdb[VeriSimDB]. In VeriSimDB one identity is an octad of modal witnesses — graph, vector, tensor, semantic, document, temporal, provenance, spatial. The graph + document witnesses take over the role once planned for ArangoDB (code-dependency graphs, analysis history, project metadata), and the semantic witness takes over the role once planned for Virtuoso/RDF (ontology knowledge, proof blobs). The eco/econ ontology seed for the semantic witness lives at link:databases/ontology/eco.ttl[databases/ontology/eco.ttl].

VeriSimDB is v0.1.0 and OikosBot’s runtime client is deferred: the data layer is retargeted in design and configuration now (see link:config/oikos.yaml[config/oikos.yaml] and link:ARCHITECTURE.adoc[ARCHITECTURE.adoc]), with runtime wiring tracked on the link:ROADMAP.adoc[roadmap]. The legacy ArangoDB + Virtuoso assets were retired (recoverable in git history).

== Local Checks

[source,shell]

cargo build –workspace # or: just rust-build cargo test –workspace # or: just rust-test just haskell-build just haskell-test just affine-check —-

The default cargo workspace deliberately excludes crates/oikosbot-fleet (the optional gitbot-fleet bridge) so OikosBot builds standalone. See link:DISAMBIGUATION.adoc[DISAMBIGUATION.adoc].

just affine-check expects an AffineScript compiler. Override the compiler path with AS_BIN=/path/to/main.exe when needed.

== GitHub Action

OikosBot runs in CI as a composite action wrapping the published container (ghcr.io/hyperpolymath/oikos):

[source,yaml]

compare mode issues a Pareto verdict against a base checkout (see link:QUICKSTART.adoc[QUICKSTART]). A repo-local .oikos.yml is honored automatically. Full workflow example: link:examples/oikosbot-ci.yml[examples/oikosbot-ci.yml].

How OikosBot relates to the nearest Marketplace neighbour: link:docs/COMPARISON-climate-warrior.adoc[OikosBot vs Climate Warrior].

== GitHub App

The app manifest lives at link:.github/app.yml[.github/app.yml]. The setup guide is link:docs/GITHUB_APP_SETUP.adoc[docs/GITHUB_APP_SETUP.adoc].

== Licence

MPL-2.0. See link:LICENSE[LICENSE].