diff --git a/README.md b/README.md index 6773410..01ff092 100644 --- a/README.md +++ b/README.md @@ -42,11 +42,16 @@ Open the repo in Cursor, Claude Code, Kiro, Codex, or Gemini CLI. They all read | Component | Purpose | |-----------|---------| +| `docs/reltio-forge.md` | **Reltio Forge** — velocity layer for AI-accelerated delivery | | `web/` | Forge Console — local chat UI (Express + WebSocket → Codex) | | `openwebui/` | Open WebUI preset, pipelines, and knowledge manifest | | `skills/` | Epics, Factory Standards, BMad Creative Suite, Gainsight PX | | `config/mcporter.json` | MCP server definitions (Jira, Aha!, Context7) | +### Transparent Factory + Reltio Forge + +**Transparent Factory** defines the 5 architectural tenets (Atomic Flagging, Elastic Schema, Cognitive Durability, Semantic Observability, Configurable Autonomy). **Reltio Forge** wraps each tenet in automated CI/CD enforcement — AI code review, formal verification, fail-fast gates, and configurable risk posture. See [`docs/reltio-forge.md`](docs/reltio-forge.md). + --- ## Architecture diff --git a/docs/reltio-forge.md b/docs/reltio-forge.md new file mode 100644 index 0000000..f36b9f4 --- /dev/null +++ b/docs/reltio-forge.md @@ -0,0 +1,234 @@ +# Reltio Forge + +*The velocity layer for AI-accelerated software delivery.* + +Transparent Factory defines **what** safe AI-assisted development looks like. +Reltio Forge defines **how** you enforce it at speed — daily releases, AI-written code, enterprise guardrails. + +--- + +## The Problem + +AI coding tools (Codex, Claude Code, Cursor, Copilot) can generate thousands of lines per day. Teams adopting them face a paradox: **velocity without guardrails is liability, but guardrails without automation kill velocity.** + +The fastest-moving open source projects (OpenClaw: 247K stars, 390K CI runs, daily releases, mostly AI-written) prove this is solvable. They ship daily because their safety net is automated, not manual. + +Reltio Forge codifies these patterns for enterprise teams already following Transparent Factory tenets. + +--- + +## Relationship to Transparent Factory + +| Layer | Scope | Analogy | +|-------|-------|---------| +| **Transparent Factory** | Architectural tenets (what to build) | Building code | +| **Reltio Forge** | Delivery pipeline (how to ship safely) | Inspection process | + +Transparent Factory's 5 tenets remain the standard. Forge wraps each one in automated enforcement: + +| Tenet | Forge Enforcement | +|-------|-------------------| +| Atomic Flagging | CI gate: no deployment without flag wrapper. Flag TTL enforced by cron reaper. | +| Elastic Schema | Migration linter in CI. Additive-only check. Dual-write test harness. | +| Cognitive Durability | ADR-or-reject: PRs touching architecture require an ADR file or are blocked. | +| Semantic Observability | Span coverage gate: new endpoints must emit reasoning spans or CI fails. | +| Configurable Autonomy | Governance-as-code: autonomy levels declared in config, validated at deploy. | + +--- + +## The 6 Forge Principles + +### 1. Gate Before Merge, Not After Deploy + +Every PR passes through an automated gauntlet before a human sees it: + +``` +Cheap & Fast Expensive & Slow +─────────────────────────────────────────────────────────► +Types → Lint → Secrets → Build → Unit → E2E → AI Review + ~30s ~30s ~10s ~60s ~90s ~3m ~2m +``` + +Fail-fast ordering: if types are broken, don't waste 5 minutes on E2E. + +*Inspired by: OpenClaw CI scoping — detects what changed, skips irrelevant jobs, runs cheap checks first.* + +### 2. AI Reviews AI + +When code is AI-generated, human review alone is insufficient at scale. Add an AI reviewer in CI that: + +- Checks for Transparent Factory tenet compliance +- Flags security anti-patterns (SQL injection, hardcoded secrets, missing auth) +- Validates schema changes are additive +- Produces a structured review (not just "LGTM") + +The human reviewer then reviews the AI review + the code. Two-layer defense. + +*Inspired by: OpenClaw's `claude-code-review.yml` GitHub Action on every PR.* + +### 3. Formal Models for High-Risk Paths + +Not everything needs formal verification. But the paths where a bug means data breach, money loss, or compliance failure? Those get TLA+ (or Alloy, or property-based tests at minimum). + +**Forge rule:** identify your top 5 "if this breaks, we're on the news" paths. Write executable models for them. Run them in CI. Maintain both "green" (invariant holds) and "red" (invariant breaks under known bug class) models. + +*Inspired by: OpenClaw's TLA+ models for session isolation, pairing, ingress gating, routing, and tool execution.* + +### 4. Three Channels, One Truth + +Ship to `beta` first. Soak. Promote to `stable`. Never skip. + +``` +main ──► beta (automated) ──► stable (promoted after soak) + │ + └── canary (optional: % rollout) +``` + +- Tags are immutable +- Promotion is a metadata operation, not a rebuild +- Rollback = promote the previous stable tag + +*Inspired by: OpenClaw's stable/beta/dev channels with npm dist-tag promotion.* + +### 5. Trust Boundaries as Code + +Define explicit trust boundaries in your architecture. Each boundary is a policy enforcement point: + +``` +Untrusted Input → [Boundary 1: Validation] → Business Logic → [Boundary 2: Authorization] → Data → [Boundary 3: Execution Sandbox] +``` + +**Forge rule:** every service declares its trust boundaries in a `TRUST.md` or equivalent config. CI validates that boundary enforcement code exists at each declared point. + +*Inspired by: OpenClaw's three trust boundaries (channel access → session isolation → tool execution sandbox) documented in their MITRE ATLAS threat model.* + +### 6. Configurable Risk Tolerance + +Not every team, environment, or customer has the same risk appetite. Forge doesn't mandate a single posture — it mandates that the posture is **explicit and configurable**: + +- `strict`: all gates required, no overrides, formal models must pass +- `standard`: all gates required, break-glass override with audit trail +- `experimental`: gates advisory-only, all violations logged but non-blocking + +The posture is declared per-environment, per-service, or per-tenant. Never implicit. + +*Inspired by: OpenClaw's tool profiles (messaging vs coding), exec approvals, dmPolicy, and allowlists — all configurable per agent.* + +--- + +## Forge Pipeline (Reference Implementation) + +```yaml +# .forge/pipeline.yml +version: 1 +posture: standard # strict | standard | experimental + +gates: + # --- Fast gates (< 2 min) --- + types: + tool: tsc --noEmit + fail: block + + lint: + tool: eslint + prettier + fail: block + + secrets: + tool: gitleaks / trufflehog + fail: block + + # --- Build gate --- + build: + tool: docker build / npm run build + fail: block + depends_on: [types, lint, secrets] + + # --- Test gates (2-5 min) --- + unit: + tool: vitest --run + coverage_threshold: 80% + fail: block + depends_on: [build] + + e2e: + tool: vitest --run --config vitest.e2e.config.ts + fail: block + depends_on: [build] + + # --- AI gates (2-3 min) --- + ai_review: + tool: claude-code-review + checks: + - transparent_factory_compliance + - security_anti_patterns + - schema_additive_only + - adr_required_for_architecture + fail: block # standard: block. experimental: warn. + depends_on: [build] + + # --- Formal gates (optional, for declared high-risk paths) --- + formal: + tool: tlc + models_dir: .forge/models/ + fail: block + depends_on: [build] + when: changed(.forge/models/) OR changed(src/auth/) OR changed(src/data/) + +# --- Transparent Factory tenet enforcement --- +tenets: + atomic_flagging: + check: grep-based or AST check for flag wrappers on new features + ttl_reaper: cron job that alerts on flags past 14-day TTL + + elastic_schema: + check: migration linter (additive-only, no column drops without dual-write) + sla: 30 days for migration completion + + cognitive_durability: + check: PRs touching src/arch/ or adding new services require docs/adr/*.md + + semantic_observability: + check: new API endpoints must have tracing spans (grep for span creation) + + configurable_autonomy: + check: governance config exists and is valid JSON/YAML schema +``` + +--- + +## Adoption Path + +### Week 1-2: Foundation +- Add fail-fast CI gates (types → lint → secrets → build → test) +- Declare trust boundaries in each service +- Set posture to `experimental` (non-blocking) + +### Week 3-4: Enforcement +- Add AI code review to PR pipeline +- Add Transparent Factory tenet checks +- Promote posture to `standard` + +### Month 2: Hardening +- Identify top 5 high-risk paths +- Write formal models (TLA+ or property-based tests) +- Add beta/stable channel promotion +- Enable break-glass audit trail + +### Month 3+: Maturity +- Promote posture to `strict` for production services +- Publish Forge compliance dashboard +- Integrate with Reltio's existing release governance + +--- + +## Why This Works + +OpenClaw ships daily with AI-written code because: +1. **Automated gates catch 95% of problems** before a human looks at it +2. **Trust boundaries limit blast radius** when something slips through +3. **Configurable posture** means teams adopt incrementally, not all-or-nothing +4. **Formal models** provide mathematical confidence on the paths that matter most + +Reltio Forge takes these patterns and wraps them around the Transparent Factory tenets you already have. The tenets don't change. The enforcement becomes automatic. + +*The factory builds the product. The forge tempers the steel.*