diff --git a/QUICK_START.md b/QUICK_START.md index e1f2142..88340be 100644 --- a/QUICK_START.md +++ b/QUICK_START.md @@ -1,312 +1,9 @@ -# πŸš€ EPICON Guard - Quick Start +# Quick Start -## βœ… Repository Setup Complete! +**This document has been superseded.** -Everything is ready! Here's how to proceed: +See [README.md](../README.md#quick-start) for the current install instructions and intent block format. --- -## πŸ“¦ What's Been Created - -**25 Files** organized into: -- πŸ“– **12 Documentation files** (guides, specs, examples) -- βš™οΈ **7 Configuration files** (package.json, CI/CD, examples) -- 🌐 **1 Landing page** (production-ready HTML) -- πŸ”§ **1 Setup script** (automation helper) -- πŸ“„ **4 Core files** (LICENSE, .gitignore, etc.) - -**Key Highlights:** -- βœ… Complete monorepo structure with 5 packages -- βœ… CI/CD with EPICON intent validation (dogfooding!) -- βœ… Beautiful landing page ready to deploy -- βœ… Comprehensive documentation (3,000+ lines) -- βœ… 4 real-world example templates - ---- - -## ⚑ Quick Start (5 Minutes) - -### Step 1: Review Key Files -```bash -# Read these first -cat SETUP.md -cat ATLAS_MISSION_COMPLETE.md -cat docs/PRODUCT_SPEC.md -``` - -### Step 2: Initialize and Commit -```bash -# Run the helper script (recommended) -./scripts/init-repo.sh - -# This will: -# - Stage all files -# - Create commit with EPICON intent -# - Show you next steps -``` - -### Step 3: Push to GitHub -```bash -# Push everything -git push origin main - -# Or if on feature branch -git push origin cursor/epicon-repository-setup-551a -``` - ---- - -## πŸ“– Important Files - -| File | Purpose | -|------|---------| -| `SETUP.md` | Complete setup instructions | -| `ATLAS_MISSION_COMPLETE.md` | Full mission report | -| `REPOSITORY_SUMMARY.md` | Repository overview | -| `docs/PRODUCT_SPEC.md` | Product specification | -| `CONTRIBUTING.md` | Contribution guidelines | -| `examples/` | Intent templates | - ---- - -## 🎯 Next Steps - -### This Week -1. βœ… Push to GitHub (do this now!) -2. πŸ”„ Deploy landing page to Vercel -3. πŸ”„ Set up branch protection -4. πŸ”„ Register epicon.dev domain - -### Next 2 Weeks -1. Build `packages/core` validation engine -2. Create first GitHub Action -3. Write comprehensive tests -4. Beta testing setup - -### Next Month -1. Launch MVP -2. 10 early adopter companies -3. First blog posts -4. Product Hunt submission - ---- - -## πŸ”— Key Resources - -**Repository Structure:** -``` -epicon/ -β”œβ”€β”€ packages/ # 5 packages (core, github-app, api, dashboard, cli) -β”œβ”€β”€ docs/ # Complete documentation -β”œβ”€β”€ examples/ # 4 intent templates -β”œβ”€β”€ website/ # Landing page -└── scripts/ # Automation helpers -``` - -**Documentation:** -- Getting Started: `docs/getting-started/README.md` -- Writing Intents: `docs/guides/writing-intents.md` -- Product Spec: `docs/PRODUCT_SPEC.md` - -**Examples:** -- Basic Feature: `examples/basic-intent.yml` -- Emergency Fix: `examples/emergency-hotfix.yml` -- Database Migration: `examples/database-migration.yml` -- Feature Flag: `examples/feature-flag.yml` - ---- - -## πŸ›‘οΈ The Dogfooding Feature - -**Important:** This repository uses its own product! - -The CI workflow (`.github/workflows/ci.yml`) checks for EPICON intent in PR descriptions. This means: -- βœ… All PRs must include intent publication -- βœ… CI validates the intent format -- βœ… We prove we use what we build - -**Example CI check:** -```yaml -# When you open a PR, CI will verify: -βœ… EPICON INTENT PUBLICATION present -βœ… Required fields (ledger_id, scope, etc.) -βœ… Justification has content -βœ… Counterfactuals exist -``` - ---- - -## 🌐 Deploy Landing Page - -### Option A: Vercel (Recommended) -```bash -cd website -npx vercel - -# Follow prompts: -# - Project name: epicon-website -# - Build command: (leave empty) -# - Output directory: . -``` - -### Option B: GitHub Pages -```bash -# 1. Go to repository Settings -# 2. Pages section -# 3. Source: main branch / website folder -# 4. Save -``` - -### Option C: Netlify -```bash -cd website -npx netlify-cli deploy - -# Follow prompts for deployment -``` - ---- - -## βš™οΈ GitHub Configuration - -### Branch Protection (Recommended) -1. Go to Settings β†’ Branches -2. Add rule for `main` branch -3. Enable: - - βœ… Require pull request reviews (1 approval) - - βœ… Require status checks: `lint`, `test`, `epicon-check` - - βœ… Require branches to be up to date - -### Enable Features -1. Settings β†’ Features -2. Enable: - - βœ… Issues - - βœ… Discussions - - βœ… Projects - -### Add Topics -1. Repository main page -2. Click βš™οΈ next to "About" -3. Add topics: `git`, `security`, `compliance`, `intent`, `accountability`, `mobius`, `integrity` - ---- - -## πŸ“Š Statistics - -**Files Created:** 25 -**Documentation Lines:** 3,000+ -**Example Templates:** 4 -**Package Directories:** 5 -**CI/CD Workflows:** 1 (with dogfooding) -**Estimated Setup Time:** 2 hours (automated to 5 minutes!) - ---- - -## 🎯 What Makes This Special - -### 1. Complete Product Package -Not just code - complete go-to-market: -- βœ… Product specification -- βœ… Landing page -- βœ… Pricing strategy -- βœ… Roadmap -- βœ… Examples - -### 2. Dogfooding from Day One -We use our own product: -- βœ… CI checks enforce EPICON intent -- βœ… All PRs require justification -- βœ… "We use what we build" - -### 3. Mobius Systems Integration -First commercial product: -- βœ… Proves Mobius principles -- βœ… Revenue model for sustainability -- βœ… Commercial validation of integrity thesis - -### 4. AI-Ready -Designed for AI era: -- βœ… Captures human intent -- βœ… Minimizes human-AI drift -- βœ… Intent becomes training data - ---- - -## πŸ’‘ Quick Commands - -```bash -# Review setup -cat SETUP.md - -# Initialize and commit -./scripts/init-repo.sh - -# Push to GitHub -git push origin main - -# Deploy website -cd website && npx vercel - -# Check status -git status - -# View all files -find . -type f | grep -v .git | sort -``` - ---- - -## πŸ†˜ Need Help? - -**Read First:** -1. `SETUP.md` - Detailed setup guide -2. `ATLAS_MISSION_COMPLETE.md` - Full mission report -3. `docs/getting-started/README.md` - Getting started - -**Community:** -- GitHub Discussions (after push) -- Email: hello@epicon.dev -- Twitter: @epiconguard (coming soon) - ---- - -## βœ… Checklist - -Before proceeding: -- [ ] Read `SETUP.md` -- [ ] Read `ATLAS_MISSION_COMPLETE.md` -- [ ] Review `docs/PRODUCT_SPEC.md` -- [ ] Run `./scripts/init-repo.sh` -- [ ] Push to GitHub -- [ ] Deploy landing page -- [ ] Set up branch protection -- [ ] Register domain -- [ ] Start MVP development - ---- - -## πŸŽ‰ You're Ready! - -Everything is set up. The repository is: - -βœ… **Properly structured** - Monorepo with clear organization -βœ… **Well documented** - 12 docs, 3,000+ lines -βœ… **CI/CD ready** - Automated checks with dogfooding -βœ… **Deploy ready** - Landing page complete -βœ… **Example rich** - 4 real-world templates - -**Now just:** -1. Run `./scripts/init-repo.sh` -2. Push to GitHub -3. Deploy landing page -4. Start building! - ---- - -πŸ›‘οΈ **Git commits tell you WHAT changed. EPICON tells you WHY.** - -**Let's change software forever!** πŸš€ - ---- - -*Part of Mobius Systems | Built with Integrity* +*C-373 deferred vapor purge β€” 2026-07-15* diff --git a/SETUP.md b/SETUP.md index 2ee926e..c93eb3a 100644 --- a/SETUP.md +++ b/SETUP.md @@ -1,207 +1,10 @@ -# EPICON Guard - Repository Setup Complete! πŸŽ‰ +# Setup -## βœ… What's Been Created +**This document has been superseded.** -The EPICON Guard repository is now fully initialized with: - -### Core Configuration -- βœ… `package.json` - Monorepo configuration with Turborepo -- βœ… `turbo.json` - Build pipeline configuration -- βœ… `.gitignore` - Git ignore rules - -### Documentation -- βœ… `README.md` - Main repository README -- βœ… `CONTRIBUTING.md` - Contribution guidelines (with EPICON dogfooding!) -- βœ… `LICENSE` - CC0 1.0 Universal (public domain) -- βœ… `docs/PRODUCT_SPEC.md` - Complete product specification - -### GitHub Actions -- βœ… `.github/workflows/ci.yml` - CI/CD pipeline with EPICON intent checking - -### Website -- βœ… `website/index.html` - Beautiful landing page (ready to deploy!) - -### Package Structure -- βœ… `packages/core/` - Intent validation engine -- βœ… `packages/github-app/` - GitHub App integration -- βœ… `packages/api/` - REST API -- βœ… `packages/dashboard/` - Web dashboard -- βœ… `packages/cli/` - Command-line interface - -### Examples -- βœ… `examples/basic-intent.yml` - Basic feature template -- βœ… `examples/emergency-hotfix.yml` - Emergency fix template -- βœ… `examples/database-migration.yml` - Migration template -- βœ… `examples/feature-flag.yml` - Feature rollout template - -### Configuration -- βœ… `.epicon/config.example.yml` - Example EPICON configuration - -### Scripts -- βœ… `scripts/init-repo.sh` - Initial commit helper script +- Install and verify: [README.md](../README.md#quick-start) +- Contribute: [CONTRIBUTING.md](../CONTRIBUTING.md) --- -## πŸš€ Next Steps - -### 1. Review the Structure -```bash -# Review what was created -ls -la -ls -la packages/ -ls -la docs/ -ls -la examples/ -``` - -### 2. Install Dependencies (when packages are ready) -```bash -npm install -``` - -### 3. Commit and Push -You can now commit all these changes: - -```bash -# Option A: Use the provided script (recommended) -./scripts/init-repo.sh - -# Option B: Manual commit -git add . -git commit -m "feat: Initialize EPICON Guard repository - -EPICON INTENT PUBLICATION - -ledger_id: epicon:meta:repository-init -scope: infra -mode: normal -issued_at: $(date -u +"%Y-%m-%dT%H:%M:%SZ") -expires_at: $(date -u -d "+30 days" +"%Y-%m-%dT%H:%M:%SZ") - -justification: | - Initial repository setup for EPICON Guard. - See SETUP.md for details. - -counterfactuals: - - If structure needs adjustment, refactor before MVP - - Review after first external contributions" - -git push origin main -``` - -### 4. Set Up GitHub - -**Branch Protection:** -1. Go to Settings β†’ Branches -2. Add rule for `main` -3. Enable: - - Require pull request reviews (1) - - Require status checks: `lint`, `test`, `epicon-check` - - Require branches to be up to date - -**Enable Features:** -1. Settings β†’ Features -2. βœ… Issues -3. βœ… Discussions -4. βœ… Projects - -**Add Topics:** -1. Repository main page -2. Click βš™οΈ next to About -3. Add: `git`, `security`, `compliance`, `intent`, `accountability`, `mobius` - -### 5. Deploy Website - -**Option A: Vercel (Recommended)** -```bash -npm i -g vercel -cd website -vercel -# Follow prompts to deploy -``` - -**Option B: GitHub Pages** -```bash -# Enable in Settings β†’ Pages -# Source: main branch / website folder -``` - -### 6. Register Domain -- Register `epicon.dev` (if not done) -- Point DNS to your deployment -- Configure SSL/TLS - -### 7. Start Development - -**Create first package:** -```bash -cd packages/core -npm init -y -# Add TypeScript, tests, etc. -``` - -**Test CI:** -- Create a test PR -- Watch the EPICON intent check in action! - ---- - -## πŸ“– Key Files to Read - -1. **README.md** - Overview and quick start -2. **CONTRIBUTING.md** - How to contribute (includes intent format!) -3. **docs/PRODUCT_SPEC.md** - Complete product specification -4. **examples/** - Intent templates for different scenarios - ---- - -## 🎯 Development Roadmap - -### Week 1: Foundation -- βœ… Repository structure -- πŸ”„ Deploy landing page -- πŸ”„ Set up project management - -### Weeks 2-4: MVP Core -- πŸ”„ Build intent validation engine (`packages/core`) -- πŸ”„ Create GitHub Action -- πŸ”„ Write tests - -### Weeks 5-8: GitHub Integration -- πŸ”„ Build GitHub App (`packages/github-app`) -- πŸ”„ PR comment templates -- πŸ”„ Status checks - -### Weeks 9-12: Launch Prep -- πŸ”„ Beta testing with 10 companies -- πŸ”„ Documentation -- πŸ”„ Demo video -- πŸ”„ Product Hunt submission - ---- - -## πŸ†˜ Need Help? - -- πŸ“– Read the docs: `docs/` -- πŸ’¬ Check examples: `examples/` -- πŸ“§ Email: hello@epicon.dev -- 🐦 Twitter: @epiconguard (coming soon) - ---- - -## 🎊 You're All Set! - -Everything is ready for EPICON Guard development. The repository is: - -βœ… Properly structured -βœ… Documented -βœ… Configured for CI/CD -βœ… Ready for dogfooding (intent checks on PRs!) -βœ… Ready to deploy - -**Time to build the Intent Layer for Git!** πŸ›‘οΈ - ---- - -*Part of Mobius Systems | Built with Integrity* - -πŸ›‘οΈ **Git commits tell you WHAT changed. EPICON tells you WHY.** +*C-373 deferred vapor purge β€” 2026-07-15* diff --git a/docs/PRODUCT_SPEC.md b/docs/PRODUCT_SPEC.md index 22d49ac..0c2d867 100644 --- a/docs/PRODUCT_SPEC.md +++ b/docs/PRODUCT_SPEC.md @@ -1,344 +1,28 @@ -# EPICON Guard β€” Product Specification -## "Git commits tell you WHAT changed. EPICON tells you WHY." +# EPICON Guard β€” Product Scope -**Version:** 1.0 -**Date:** December 22, 2025 -**Status:** Pre-Launch Specification +**Status:** Truth-only scope document (replaces pre-launch vapor spec) ---- - -## 🎯 Executive Summary - -**EPICON Guard** is the world's first Intent Accountability Layer for Git, transforming version control from "what changed" to "why it changed." By requiring time-bounded justifications for every code change, EPICON Guard creates an auditable trail of engineering decisions that serves developers, compliance teams, and AI coding assistants alike. - -### The Core Insight - -**Traditional Git answers:** -- βœ… What changed? -- βœ… When did it change? -- βœ… Who changed it? - -**EPICON Guard adds:** -- 🎯 **WHY** was it changed? -- ⏰ **WHEN** does this authority expire? -- πŸ”„ **WHAT** would make us revert it? -- πŸŽ“ **HOW** does this fit into the architecture? - -### Market Opportunity - -- **TAM:** $5B (100M developers Γ— $50/year) -- **Initial Target:** Enterprise/Government compliance market -- **Launch Strategy:** Open source core + managed service -- **Unique Position:** First-mover in intent accountability - ---- - -## πŸ—οΈ Product Architecture - -### Core Components - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ EPICON Guard Platform β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”‚ -β”‚ β”‚ Intent Engine β”‚ β”‚ Validation API β”‚ β”‚ Audit Store β”‚β”‚ -β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚β”‚ -β”‚ β”‚ β€’ Parse intent β”‚ β”‚ β€’ Scope check β”‚ β”‚ β€’ History log β”‚β”‚ -β”‚ β”‚ β€’ Validate β”‚ β”‚ β€’ Time bounds β”‚ β”‚ β€’ Query API β”‚β”‚ -β”‚ β”‚ β€’ Store β”‚ β”‚ β€’ Evolution β”‚ β”‚ β€’ Reports β”‚β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β”‚ -β”‚ β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Integration Layer β”‚ β”‚ -β”‚ β”‚ β€’ GitHub App β€’ GitLab CI β€’ Bitbucket β€’ Self-hostedβ”‚β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Intelligence Layer (Future) β”‚ β”‚ -β”‚ β”‚ β€’ Intent AI β€’ Pattern detection β€’ Auto-suggest β”‚β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - ---- - -## πŸ“‹ Feature Specification - -### 1. Intent Publication (MVP) - -**User Story:** -> As a developer, I want to document WHY I'm making a change so that future developers (including AI) understand the context. - -**Specification:** - -```yaml -# Required in PR description: -EPICON INTENT PUBLICATION - -ledger_id: :: -scope: docs | ci | core | infra | sentinels | labs | specs -mode: normal | emergency -issued_at: -expires_at: -justification: | - Multi-line explanation of: - - PROBLEM: What problem does this solve? - - CONTEXT: What's the background? - - DECISION: What approach was chosen? - - TRADEOFFS: What alternatives were rejected? Why? - - IMPACT: Who/what does this affect? - -counterfactuals: - - If , then - - If , then -``` - -**Validation Rules:** - -| Field | Required | Format | Validation | -|-------|----------|--------|------------| -| `ledger_id` | βœ… | `::` | Must be unique per PR | -| `scope` | βœ… | Enum from config | Must match changed files | -| `mode` | βœ… | `normal` or `emergency` | Emergency requires extra fields | -| `issued_at` | βœ… | ISO-8601 with Z | Must be ≀ current time | -| `expires_at` | βœ… | ISO-8601 with Z | Must be > issued_at | -| `justification` | βœ… | Multi-line string | Min 100 chars | -| `counterfactuals` | βœ… | Array of conditions | Min 1 condition | - ---- - -### 2. Scope Enforcement - -**Configuration:** - -```yaml -# .epicon/config.yml - -scopes: - docs: - patterns: - - "docs/**" - - "*.md" - - "README.*" - reviewers: - - "@tech-writing-team" - - core: - patterns: - - "src/core/**" - - "packages/core/**" - reviewers: - - "@core-team" - - "@security-team" - requires_approval: 2 -``` - ---- - -### 3. Time-Bounded Authority - -**Features:** - -**A. Expiration Enforcement** -```yaml -# Intent block -issued_at: 2025-12-22T10:00:00Z -expires_at: 2025-12-29T10:00:00Z # 7-day window - -# EPICON checks: -βœ… On PR creation: Validates expires_at is in future -⚠️ On PR update: Warns if <24h remaining -❌ On merge attempt: Blocks if expired -``` - -**B. Extension Workflow** -```yaml -# If intent needs extension -intent_evolution: true -supersedes_hash: abc123... # Hash of original intent -evolution_reason: | - Extension requested because: - - Original scope expanded after security review - - Additional testing required -``` - ---- - -### 4. Counterfactual Conditions - -**Examples:** - -**Feature Flag:** -```yaml -counterfactuals: - - If <100 users adopt in 30 days, remove feature - - If performance degrades >10%, disable by default - - If security vulnerability found, disable immediately -``` - -**Database Migration:** -```yaml -counterfactuals: - - If migration fails in staging, do not proceed to prod - - If migration takes >5 minutes, abort and optimize - - If rollback script fails, escalate to DBA team -``` +## What ships today ---- - -### 5. Corporate Integrity Index (CII) +| Component | Status | +| --- | --- | +| GitHub Action (`kaizencycle/epicon@v1`) | βœ… Live | +| Validator (`packages/guard-core/`) | βœ… Live | +| GitHub Pages landing (`website/`) | βœ… Live | -**Public Integrity Scoring:** +Everything else is on the [README roadmap](../../README.md#roadmap) until verified. -```yaml -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ ACME Corp β€” Corporate Integrity Index β”‚ -β”‚ β”‚ -β”‚ Overall Score: 87/100 (A-) β”‚ -β”‚ Industry Rank: Top 15% (Tech/SaaS) β”‚ -β”‚ β”‚ -β”‚ Breakdown: β”‚ -β”‚ β”œβ”€ Intent Compliance: 94% (A) β”‚ -β”‚ β”œβ”€ Justification Quality: 88/100 (B+) β”‚ -β”‚ β”œβ”€ Scope Discipline: 91% (A-) β”‚ -β”‚ β”œβ”€ Time Management: 82% (B) β”‚ -β”‚ └─ Emergency Usage: 89% (B+) β”‚ -β”‚ β”‚ -β”‚ [Download Report] [Share Badge] [Compare to Industry] β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` +## Canon (protocol definitions) ---- +EPICON Guard **implements** β€” it does not define. Specifications live in Mobius Substrate: -## πŸ’° Pricing & Packaging +- [docs/epicon/](https://github.com/kaizencycle/Mobius-Substrate/tree/main/docs/epicon) β€” EPICON-01/02/03 +- [EPICON_TIERING_SPEC_v0.1.md](https://github.com/kaizencycle/Mobius-Substrate/blob/main/docs/specs/EPICON_TIERING_SPEC_v0.1.md) -### Free Tier (Public Repos) -- Intent validation -- Basic audit logs (30 days) -- GitHub/GitLab integration -- Community support -- Up to 10 repos +## Releases -### Pro Tier ($10/user/month) -- Everything in Free -- Private repos (unlimited) -- Advanced audit logs (1 year) -- Custom scope rules -- Slack/Teams integration -- Priority support -- API access - -### Enterprise Tier ($50/user/month) -- Everything in Pro -- SSO/SAML integration -- Unlimited audit retention -- Custom compliance reports -- On-premise option -- Dedicated support -- SLA guarantees (99.9%) +- [docs/releases/](../releases/) β€” tag policy, movement log, version manifests --- -## πŸš€ Roadmap - -### Phase 1: MVP (Months 1-3) -- βœ… Intent validation engine -- βœ… Scope enforcement -- βœ… Time-bound checks -- βœ… GitHub App -- βœ… Basic dashboard - -### Phase 2: Intelligence (Months 4-6) -- πŸ”„ Intent AI (suggestions) -- πŸ”„ Pattern detection -- πŸ”„ Quality scoring -- πŸ”„ GitLab integration - -### Phase 3: Enterprise (Months 7-9) -- πŸ”„ SSO/SAML -- πŸ”„ Advanced reporting -- πŸ”„ Self-hosted option -- πŸ”„ Compliance certifications - -### Phase 4: Autopilot (Months 10-12) -- πŸ”„ Intent Autopilot (auto-generation) -- πŸ”„ Counterfactual monitoring -- πŸ”„ Cross-repo analytics - ---- - -## πŸ” Security & Privacy - -### Data Handling - -**What We Store:** -- βœ… Intent publications -- βœ… Validation results -- βœ… Audit logs -- βœ… User/repo metadata - -**What We DON'T Store:** -- ❌ Source code contents -- ❌ Commit diffs -- ❌ API keys or secrets - -**Compliance:** -- βœ… SOC 2 Type II (in progress) -- βœ… GDPR compliant -- βœ… CCPA compliant -- βœ… FedRAMP (government tier) - ---- - -## 🎯 Success Metrics - -### Year 1 Targets - -``` -Users -β€’ Free users: 10,000 -β€’ Pro users: 500 -β€’ Enterprise users: 50 - -Revenue -β€’ MRR: $250k (Month 12) -β€’ ARR: $3M (run rate) - -Product -β€’ Repos enabled: 50,000 -β€’ Intents published: 1M+ -β€’ Violations caught: 100k+ -``` - ---- - -## 🀝 Part of Mobius Systems - -EPICON Guard is the first commercial product from Mobius Systems: - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ MOBIUS SYSTEMS β”‚ -β”‚ "AI Operating System for Civilization" β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ β”‚ β”‚ - β–Ό β–Ό β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ EPICON β”‚ β”‚ Mobius β”‚ β”‚ MIC β”‚ - β”‚ Guard β”‚ β”‚ Ledger β”‚ β”‚ Economy β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -**EPICON proves Mobius principles work at commercial scale.** - ---- - -*Document Version: 1.0* -*Last Updated: December 22, 2025* -*Status: Ready for Implementation* - -πŸ›‘οΈ **Git commits tell you WHAT changed. EPICON tells you WHY.** +*C-373 deferred vapor purge β€” 2026-07-15. Prior December 2025 spec archived in federation.* diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 9aa7bc5..1d5f4d0 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -1,140 +1,19 @@ -# Getting Started with EPICON Guard +# Getting Started -Welcome to EPICON Guard! This guide will help you understand and start using the Intent Accountability Layer for Git. +**Start here:** [README.md](../../README.md) -## What is EPICON Guard? +## Install the Guard -EPICON Guard transforms Git from tracking **WHAT** changed to also tracking **WHY** it changed. Every code change requires a structured justification that documents: +Add `.github/workflows/epicon-guard.yml` per the [Quick Start](../../README.md#quick-start). -- **Context:** Why is this change needed? -- **Decision:** What approach was chosen? -- **Impact:** Who/what does this affect? -- **Counterfactuals:** What would make us revert this? -- **Expiration:** When should this be reviewed? +## Learn the protocol -## Quick Start +Canon lives in [Mobius-Substrate/docs/epicon](https://github.com/kaizencycle/Mobius-Substrate/tree/main/docs/epicon). -### 1. Install EPICON Guard +## Contribute -**For GitHub repositories:** -```bash -# Coming soon - GitHub App installation -# Visit: github.com/apps/epicon-guard -``` - -**For self-hosted / local validation:** -```bash -npm install -g @epicon-guard/cli -``` - -### 2. Configure Your Repository - -Create `.epicon/config.yml`: -```yaml -version: 1 - -organization: - name: "myorg" - -scopes: - core: - patterns: ["src/**"] - requires_approval: 2 -``` - -### 3. Write Your First Intent - -When creating a PR, add this to the description: - -```yaml -EPICON INTENT PUBLICATION - -ledger_id: myorg:myproject:feature-name -scope: core -mode: normal -issued_at: 2025-12-22T10:00:00Z -expires_at: 2026-01-22T10:00:00Z - -justification: | - Adding user authentication feature. - - CONTEXT: - - Users requested secure login - - Current system uses basic auth - - Moving to OAuth 2.0 - - DECISION: - - Using Auth0 for implementation - - Rejected custom solution (maintenance burden) - - IMPACT: - - All users will need to re-authenticate - - Migration plan: 7-day grace period - -counterfactuals: - - If Auth0 costs exceed $100/month, review - - If migration causes >5% user complaints, extend grace period - - Review security audit results after 30 days -``` - -### 4. EPICON Validates - -The EPICON Guard CI check will: -- βœ… Verify intent block is present -- βœ… Check all required fields -- βœ… Validate scope matches changed files -- βœ… Ensure expiration is in the future -- βœ… Confirm counterfactuals exist - -### 5. Track and Monitor - -After merge, EPICON: -- πŸ“Š Tracks your Corporate Integrity Index (CII) -- ⏰ Monitors expiration dates -- πŸ”” Alerts when counterfactuals trigger -- πŸ“ˆ Provides audit reports - -## Key Concepts - -### Intent Publication -Every change requires documentation of **why** it's being made. This creates an auditable trail of engineering decisions. - -### Scope Enforcement -Changes are limited to declared scopes. Security engineers can't accidentally modify payment code. - -### Time-Bounded Authority -All changes have expiration dates. Temporary fixes can't become permanent without review. - -### Counterfactual Conditions -Clear criteria for when to revert or modify changes. "If X happens, then do Y." - -### Corporate Integrity Index (CII) -Public score showing your organization's commitment to intentional engineering. - -## Examples - -See the `/examples` directory for templates: -- `basic-intent.yml` - Simple feature addition -- `emergency-hotfix.yml` - Production incident response -- `database-migration.yml` - Schema changes -- `feature-flag.yml` - Feature rollout with metrics - -## Next Steps - -1. Read the [Product Specification](../PRODUCT_SPEC.md) -2. Review [Intent Writing Guide](../guides/writing-intents.md) -3. Check out [Best Practices](../guides/best-practices.md) -4. Join the community discussion - -## Need Help? - -- πŸ“– [Full Documentation](../README.md) -- πŸ’¬ [GitHub Discussions](https://github.com/kaizencycle/epicon/discussions) -- πŸ“§ Email: hello@epicon.dev -- πŸ› [Report Issues](https://github.com/kaizencycle/epicon/issues) +See [CONTRIBUTING.md](../../CONTRIBUTING.md). --- -πŸ›‘οΈ **Git commits tell you WHAT changed. EPICON tells you WHY.** - -*Part of Mobius Systems | Built with Integrity* +*Part of [Mobius Substrate](https://mobius-substrate.com)*