From 63b8a8e7e5f84377688ff48b04931258ddd2c8e8 Mon Sep 17 00:00:00 2001 From: Pavan Dev Singh Charak Date: Sun, 5 Apr 2026 19:04:39 +0530 Subject: [PATCH] Update README.md UPDATED README --- README.md | 317 ++++++++---------------------------------------------- 1 file changed, 46 insertions(+), 271 deletions(-) diff --git a/README.md b/README.md index 7b42215..2351efb 100644 --- a/README.md +++ b/README.md @@ -1,307 +1,82 @@ -# Manthan โ€” Decision Operating System - -> Every decision is traceable, auditable, and built for trust. - ---- - -## ๐Ÿš€ What is Manthan? - -Manthan is a **deterministic decision infrastructure** that enforces contract-based rules directly in your workflows. - -It replaces manual approvals with: - -* Deterministic evaluation -* Contract-driven rules -* Enforced outcomes - -At its current version (**v0.2**), Manthan operates as a: - -> **GitHub Pull Request Gate** - ---- - -## โšก Why it matters - -Modern workflows rely on: - -* Manual reviews -* Subjective approvals -* Inconsistent enforcement - -Manthan changes that: - -> Decisions are no longer opinions โ€” they are **enforced outcomes**. - ---- - -## ๐Ÿง  How it works - -```txt -GitHub PR Event - โ”‚ - โ–ผ -Webhook (/internal/event) - โ”‚ - โ–ผ -Event Normalization - โ”‚ - โ–ผ -Decision Engine (core/) - โ”‚ - โ–ผ -Explanation Builder - โ”‚ - โ–ผ -GitHub Enforcement - (Check Run + Status + Comment) - โ”‚ - โ–ผ -Merge Allowed / Blocked -``` - ---- - -## ๐Ÿ” Decision Engine (Deterministic Flow) - -```txt -Input (eventPayload + contract) - โ”‚ - โ–ผ -Contract Validation - โ”‚ - โ–ผ -Determinism Check - โ”‚ - โ–ผ -Boundary Check - โ”‚ - โ–ผ -Intent Alignment - โ”‚ - โ–ผ -Base Rules - โ”‚ - โ–ผ -Final Decision (pass / fail) - โ”‚ - โ–ผ -Trace + Explanation -``` +# Manthan โ€” Deterministic PR Gate ---- +Manthan is a deterministic decision system that evaluates GitHub pull requests against structured decision contracts. -## ๐Ÿ” Enforcement Flow +Same input โ†’ same decision. Every time. -```txt -Decision Result - โ”‚ - โ–ผ -Map to GitHub State - (pass โ†’ success, fail โ†’ failure) - โ”‚ - โ–ผ -Create Check Run - โ”‚ - โ–ผ -Set Commit Status - (manthan/pr-gate) - โ”‚ - โ–ผ -Upsert PR Comment - โ”‚ - โ–ผ -Branch Protection - โ”‚ - โ–ผ -Merge Allowed / Blocked -``` ---- +## What This Does -## ๐Ÿ” What it enforces +Manthan enforces decisions at the pull request level. -| Condition | Result | -| ---------------------- | --------- | -| Missing PR description | โŒ Blocked | -| No test files | โŒ Blocked | -| Contract satisfied | โœ… Allowed | +Instead of human reviews or probabilistic tools, every PR is evaluated against a contract and produces a reproducible verdict. ---- -## โšก 1-Minute Demo +## Core Principles -### Step 1 โ€” Create PR (invalid) +* Deterministic โ€” no drift, no heuristics +* Contract-driven โ€” decisions defined as structured schemas +* Enforced โ€” results applied directly to PRs +* Auditable โ€” every decision includes a trace -```txt -PR created โ†’ No description -``` -```txt -manthan/pr-gate โ†’ โŒ failure -``` +## Example Output ---- +Decision: FAIL -### Step 2 โ€” Fix PR +Contract: api-schema-v1 -```md -Add feature X +Violations: -- Includes implementation -- Adds tests -``` +* Missing field `userId` +* Endpoint `/create` not defined ---- +Trace: -### Step 3 โ€” Automatic re-evaluation +* input.schema.required +* endpoint.registry.match -```txt -PR updated โ†’ webhook triggered -manthan/pr-gate โ†’ โœ… success -``` +evaluation_id: 8f3a... +contract_version: v1 ---- -### Step 4 โ€” Merge enabled +## Architecture -```txt -All checks passed โ†’ Merge allowed -``` +* `/contracts` โ€” decision definitions +* `/core` โ€” evaluation engine +* `/enforcement` โ€” GitHub PR interaction +* `/dsl` โ€” contract logic structure +* `/api` โ€” webhook ingestion layer ---- -### ๐Ÿง  Insight +## Determinism Guarantee -```txt -Invalid input โ†’ fail โ†’ blocked -Valid input โ†’ pass โ†’ allowed -``` +Given: -> Manthan does not suggest โ€” it **enforces**. +* Same PR +* Same contract +* Same repository state ---- +Manthan guarantees: -## ๐Ÿš€ Try Manthan (GitHub App) +* Same verdict +* Same violations +* Same trace +* Same evaluation_id -### 1๏ธโƒฃ Install the App -* Go to GitHub App settings -* Click **Install App** -* Select repository +## Status ---- +Manthan v0.2 โ€” Deterministic PR Gate (locked) -### 2๏ธโƒฃ Enable Branch Protection - -* Settings โ†’ Branches -* Require status checks - -Add: - -```txt -manthan/pr-gate -``` - ---- - -### 3๏ธโƒฃ Create a PR - ---- - -### 4๏ธโƒฃ Observe - -```txt -PR โ†’ Decision โ†’ Status โ†’ Merge control -``` - ---- - -## ๐Ÿงช Local Testing (CLI) - -```bash -npm run cli payload.json -``` - ---- - -## ๐Ÿ“˜ Documentation - -* ๐Ÿ“„ [System Specification](./docs/manthan-v0.2-pr-gate.md) -* ๐Ÿ“œ [Release Notes (v0.2)](./docs/releases/v0.2.md) -* ๐Ÿ“š [Docs Index](./docs/README.md) - ---- - -## ๐Ÿ”’ Versioning Model - -* v0.2 โ€” PR Gate (**current**) -* v0.3 โ€” Multi-contract -* v1.0 โ€” Platform - -### Rules - -* No patch versions +* GitHub App integration +* Idempotent webhook processing +* PR comment enforcement * No runtime mutation -* Immutable releases - ---- - -## ๐Ÿ— System Design - -```txt -core/ โ†’ deterministic engine -api/ โ†’ webhook entry -enforcement/ โ†’ GitHub integration -``` - ---- - -## ๐Ÿšซ What Manthan is NOT - -* Not CI -* Not linter -* Not advisory tool - -Manthan is: - -> **Decision Infrastructure** - ---- - -## ๐Ÿ”’ Current Status - -* Version: v0.2 -* State: Locked -* Behavior: Immutable - ---- - -## ๐Ÿš€ Next - -### v0.3 โ€” Multi-Contract Evaluation - -* Multiple contracts per PR -* Aggregated decision -* Single enforcement signal - ---- - -## ๐Ÿค Philosophy - -> Aligned decision = single source of truth - ---- -## โญ Summary -```txt -Manual approval โ†’ subjective decisions -``` +## Positioning -โ†“ +Manthan is not a recommendation system. -```txt -Deterministic evaluation โ†’ enforced outcomes -``` -end ---- +It is enforcement infrastructure for decisions.