opercerta

# OperCerta | Auditable Operations Agent OperCerta is a controlled AI operations agent for inventory exceptions, equipment alerts, and operational work orders. It combines FastAPI, LangGraph, FastMCP, PostgreSQL, approval checkpoints, idempotent tool calls, and audit-focused observability in a reproducible reference implementation. - [Project showcase](https://opercerta-kxh.netlify.app) - [Portfolio overview](https://kxh-agent-portfolio.netlify.app) - Status: engineering showcase; the public site is read-only and the production release gate remains closed. ## Tool List OperCerta is an intelligent operations agent for inventory exceptions, equipment alerts, and operational work orders. > Current status: inventory replenishment, equipment maintenance, and job exception recovery three FastAPI + LangGraph + FastMCP + PostgreSQL closed-loop, demonstration JWT/RBAC, 42 fixed synthesis contract evaluation, Redis read-only cache, OpenTelemetry adaptation, local React console and GitHub Actions have automated evidence; Moonshot AI `kimi-k2.6` has completed three businesses 6 representative operations / 3 real model paths local verification. [PR #6](https://github.com/KXHXK/opercerta/pull/6) has been merged, `main` run `29738863357` five jobs (including Compose three businesses and API/MCP restart recovery) all passed. New [zero-cost static project special topic](https://opercerta-kxh.netlify.app) and [single-page portfolio](https://kxh-agent-portfolio.netlify.app) have been produced and verified; public root path open and zero writes, `/engineering` only provides engineering details in localhost development mode, `/console` retains real local console. Public pages do not provide backend write entry; production identity, interactive HTTPS backend, automatic deployment, and public API have not been completed, production release gate: `CLOSED`. ## Current Verified Scope - Strict illegal input and JSON-only recovery snapshot; - Deterministic recovery decision matrix; - PostgreSQL Schema, Alembic upgrade and downgrade, and approval atomic competition; - Authorized idempotent work order writing and concurrent safe replay; - Independent `langgraph` Schema checkpointer; - LangGraph interrupt, approval binding, approval fact re-acquisition, rejection termination, and A/B restart recovery; - Real MCP work order idempotent writing, write-after-read verification, pre-write work order safe replay, and approval expiration scan; - FastAPI operation creation, business fact query, binding approval, fixed security error mapping, and production lifespan startup recovery. - Frozen dependencies, `0002` migration upgrade and downgrade, approval competition and A/B restart repetition, real FastMCP + FastAPI dual-service process, and PostgreSQL terminal fact. - WSL2 Ubuntu Compose non-root application image, PostgreSQL/Redis, API/MCP health check, three-business approval/rejection/unique work order, database assertion, and API/MCP restart recovery. - Versioned 42 fixed evaluation (inventory 30, equipment 6, job 6) and 2×2 cache/tool mode matrix; small sample only proves call/hit behavior, not production SLA. - Server-side UUIDv4 request_id, abnormal context cleanup, safe JSON log, application-level low cardinality Prometheus indicator, SSE actual playback count, and default closed `/metrics`. - Public GitHub remote, read-only and fixed Action SHA four PR quick gates, and `main` actual passed Compose business smoke, API/MCP restart recovery, and unconditional cleanup. - Netlify public static special topic, real deployment resource fingerprint, and evidence picture response verification; this site does not connect to API, database, or MCP. - User-authorized Moonshot AI `kimi-k2.6` representative verification: three businesses each 1 query and 1 approval path, totaling 6 operations, 3 real model interpretation paths; report does not save model original text, token/cost due to adapter not exposing usage and clearly marked unavailable. ## Next Implementation Boundary The next phase still only implements OperCerta. Zero-cost static display, mainline CI/Compose, Netlify special topic, and portfolio synchronization have been completed; the next key node is personal manual demonstration/narrative mastery check, and decide whether to continue constructing public network writable HTTPS backend. Production IAM, current limiting/anti-abuse, backup, high availability, automatic deployment, and Release Tag remain to be completed. Production release gate: `CLOSED`, not started before closure. Three-business acceptance specifications and eight TDD main plans see [design](docs/superpowers/specs/2026-07-20-opercerta-three-business-release-design.md) and [plan](docs/superpowers/plans/2026-07-20-opercerta-three-business-release.md). Historical inventory slice design remains as reliability kernel evolution record. ## Implementation Basis Read and implement in the following order: 1. [AI Agent four-project naming design specification](docs/specs/2026-07-14-agent-project-naming-design.md) 2. [AI Agent four-project overall design specification](docs/specs/ai-agent-portfolio-overall-design.md) 3. [AI Agent four-project portfolio combination design](docs/specs/2026-07-14-agent-portfolio-design.md) 4. [OperCerta detailed design](docs/specs/2026-07-14-opercerta-design.md) New conversation startup constraints and handover list see [IMPLEMENTATION_HANDOFF.md](IMPLEMENTATION_HANDOFF.md). ## Repository Boundary - This repository contains reliability kernel code, test, design, plan, development log, local evidence, and public static special topic implemented from scratch; does not include complete production application that can be written publicly. - Code, interface, data, and display materials are all implemented from scratch, using public or synthetic data, not copying or relying on any original unit assets. - Performance, accuracy, cost, and stability numbers can only cite measurable results of reproducible evaluation; not declared to be online before passing the release gate. - Only after completing and releasing OperCerta, start the next project ForenTrail.