Good

Author: crisdosaygo

.ai-lint/CHECKLIST.md

@@ -0,0 +1,30 @@
+# AI Lint Checklist
+
+**Required before generating or approving code.**
+
+## Read Order (30s)
+
+- [ ] `/ai-lint/PHILOSOPHY.md`
+- [ ] Language doctrine (`doctrine/languages/*`)
+- [ ] Framework doctrine (if applicable)
+- [ ] Rejects (`rejects/*`)
+
+## Pre-Flight Checks
+
+- [ ] **Explicit Control**: No hidden magic?
+- [ ] **Boundaries**: Are inputs, env, and network validated?
+- [ ] **Ownership**: Is lifecycle clear (state, tasks, resources)?
+- [ ] **Concurrency**: Is it bounded and supervised?
+- [ ] **Errors**: Handled with context? (No swallowing)
+- [ ] **Observability**: Can logs reconstruct what happened?
+
+## Decision
+
+- [ ] Does this code "belong" here (not just work)?
+- [ ] Would a maintainer accept this at 3 AM?
+
+## Conflicts
+
+If valid code violates doctrine:
+- [ ] Override explicitly.
+- [ ] Document: **Reason**, **Risk**, **Mitigation**.

.ai-lint/GROUNDING.md

@@ -0,0 +1,39 @@
+# The Problem: Syntax vs. Semantics
+
+Correct code is not the same as idiomatic code.
+
+LLMs reliably hit:
+* Syntax ✅
+* Functionality ✅
+
+They frequently miss:
+* Idioms ❌
+* Language "feel" ❌
+* Architectural intent ❌
+
+## The Uncanny Valley of Code
+
+Consider this Python loop:
+
+```python
+for i in range(len(arr)):
+    something(arr[i])
+```
+
+It runs. It passes tests. But an experienced Python developer would write:
+
+```python
+for item in arr:
+    something(item)
+```
+
+The first example fights the language. The second works with it. This instinct—knowing what *rejected* options look like—is what AI lacks.
+
+## The Missing Context
+
+LLMs have training data, but they lack an authoritative map of what experienced practitioners reject. This knowledge lives in:
+* Senior engineers' heads
+* Code reviews
+* Implicit team culture
+
+AI Lint makes this implicit knowledge explicit. It provides a map of "technically correct but wrong" patterns to help AI choose the best expression for a given language.

.ai-lint/INDEX.md

@@ -0,0 +1,69 @@
+# AI Lint — Index (Free Edition)
+
+This is the doctrine layer for this repository.
+
+## Quick start for agents
+
+1. Read `PHILOSOPHY.md` — the governing principles
+2. Read `doctrine/architecture.md` — complexity management (preview)
+3. Read `doctrine/languages/javascript.md` — what belongs (sample)
+4. Read `rejects/architecture.md` — architectural anti-patterns (preview)
+5. Read `rejects/languages/javascript.md` — what to refuse (sample)
+6. Follow the override protocol if you need to break a rule
+
+---
+
+## File map
+
+```
+.ai-lint/
+├── PHILOSOPHY.md          # Core doctrine (read first)
+├── CHECKLIST.md           # Quick pre-code scan
+├── INDEX.md               # This file
+│
+├── doctrine/
+│   ├── architecture.md    # Complexity management (6 of 10 - preview)
+│   ├── languages/
+│   │   └── javascript.md  # JS doctrine (7 of 20 - sample)
+│   └── security.md        # Security doctrine (full)
+│
+├── rejects/
+│   ├── architecture.md    # Architectural anti-patterns (6 of 10 - preview)
+│   ├── languages/
+│   │   └── javascript.md  # JS rejects (6 of 19 - sample)
+│   └── security.md        # Security rejects (full)
+│
+├── overrides/
+│   └── OVERRIDE-PROTOCOL.md
+│
+└── wiring/
+    ├── AGENTS.md          # For Cursor
+    ├── CLAUDE.md          # For Claude
+    ├── COPILOT.md         # For GitHub Copilot
+    └── AI_INSTRUCTIONS.md # Generic
+```
+
+---
+
+## Authority order
+
+When rules conflict, apply this precedence:
+
+1. **Rejects** (strongest)
+2. **Architecture doctrine** (complexity, state management)
+3. **Framework doctrine** (not in free edition)
+4. **Language doctrine**
+5. **Core philosophy**
+6. **Generic best practices** (weakest)
+
+---
+
+## Want full coverage?
+
+This free edition includes JavaScript and architecture previews.
+
+Full packs include:
+- **App Pack**: JS (26+19), Node.js (20+18), Python, Java, Django, Spring, full architecture doctrine
+- **Systems Pack**: Go, Rust, C, C++, Assembly
+
+→ [ai-lint.dosaygo.com](https://ai-lint.dosaygo.com)

.ai-lint/LICENSE.md

@@ -0,0 +1,21 @@
+AI Lint Free License
+Version 1.0
+
+Copyright (c) 2026 AI Lint
+
+Permission is hereby granted to any individual or organization to:
+- View, read, and use this material for personal or internal team use
+- Fork or copy the repository for evaluation and non-commercial use
+- Share unmodified links to the original repository
+
+The following are explicitly prohibited without prior written permission:
+- Commercial use, sale, or licensing of this material or any derivative
+- Republishing this material as part of another product, service, or framework
+- Creating derivative doctrine, rule sets, or training material intended for sale
+- Using this material to train machine learning or AI models
+- Bundling this material into paid tools, platforms, or subscriptions
+
+This license does not grant any trademark rights.
+
+THE MATERIAL IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND.
+

.ai-lint/PHILOSOPHY.md

@@ -0,0 +1,30 @@
+# Core Philosophy — AI Lint Doctrine
+
+**Complexity must be earned.**
+
+AI Lint exists to enforce the difference between code that "runs" and code that "belongs."
+
+---
+
+## 1. We do not hide complexity; we surface it.
+If complexity cannot be removed, it must be made visible in the code’s shape, naming, and control flow.
+
+## 2. No magic.
+Avoid designs where behavior depends on invisible conventions, implicit runtime wiring, or “it just happens.”
+
+## 3. Prefer clarity over cleverness.
+Optimize for the next reader at 3am, not the author at 3pm.
+
+## 4. Make causality debuggable.
+You should be able to answer: “what happened, in what order, and why” using logs, traces, and a debugger.
+
+## 5. Make risk explicit.
+When violating a rule, document the tradeoff and the hazard you’re accepting.
+
+---
+
+## The Override Protocol
+AI Lint is a doctrine, not a straitjacket. You may break any rule if:
+1. You acknowledge the rule you are breaking.
+2. You document *why* the deviation is necessary for this specific context.
+3. You mitigate the specific risk the rule was designed to prevent.

.ai-lint/README.md

@@ -0,0 +1,114 @@
+# AI Lint — Free Edition
+
+**Teach your AI agents the difference between code that "works" and code that "belongs."**
+
+AI Lint is doctrine for AI coding agents. It externalizes senior engineering judgment—so agents build code that fits the language, the framework, and your codebase.
+
+AI models are great at syntax but terrible at taste. They invent unnecessary abstractions, hide complexity, and create technical debt that looks "correct" but rots quickly.
+
+AI Lint fixes this by injecting explicit architectural constraints into the agent's context.
+
+The goal of AI Lint is to dramatically improve codebase quality, while reducing task time-to-completion for agentic coding. It accomplishes this by reducing the cycle of generating, reviewing, rejecting, and prompting again. AI Lint constrains the search space so agents are more likely to get it right the first time.
+
+---
+
+## What's in the free edition
+
+| Component | Description |
+|-----------|-------------|
+| **Philosophy** | Core doctrine: clarity over cleverness, visible complexity, debuggable causality |
+| **Security baseline** | Agentic security doctrine (16 principles) |
+| **JavaScript doctrine** | 7 principles (sample from 20) |
+| **JavaScript rejects** | 6 rejected patterns (sample from 19) |
+| **Wiring prompts** | Ready-to-paste instructions for Cursor, Claude, Copilot |
+| **Override protocol** | How to consciously break rules |
+
+This is enough to wire an agent, see how AI Lint works, and decide if you want full coverage.
+
+---
+
+## Quick start
+
+```bash
+# 1. Clone or download this repo
+git clone https://github.com/yourorg/ai-lint.git
+
+# 2. Copy into your project
+mkdir .ai-lint
+cp -r ai-lint/* .ai-lint/
+
+# 3. Wire your agent (example: Cursor)
+cp .ai-lint/wiring/AGENTS.md .cursor/AGENTS.md
+```
+
+That's it. Your agent now consults AI Lint before writing JavaScript.
+
+---
+
+## Verify it works
+
+Ask your agent:
+
+> "Write a JavaScript module that uses a global variable to track user sessions"
+
+A properly wired agent should:
+1. Flag that this violates **JS-R1** (implicit global state)
+2. Explain why: it hides causality and breaks test reset
+3. Offer an alternative, or ask if you want to override
+
+---
+
+## What's NOT in the free edition
+
+The free edition covers JavaScript. Paid packs cover:
+
+**App Pack** ($49):
+- Full JavaScript: 20 principles + 19 rejects (vs 7/6 in free)
+- Node.js doctrine + 18 rejects
+- Python doctrine + 18 rejects
+- Java doctrine + 20 rejects
+- Django framework doctrine + 10 rejects
+- Spring framework doctrine + 10 rejects
+
+**Systems Pack** ($49):
+- Go doctrine + 20 rejects
+- Rust doctrine + 18 rejects
+- C doctrine + 18 rejects
+- C++ doctrine + 18 rejects
+- Assembly doctrine + 15 rejects
+
+**Bundle** ($79): Both packs + all future packs
+
+→ [Get the full packs](https://ailint.dev)
+
+---
+
+## License
+
+The free edition is source-available for evaluation and internal use.
+
+You may:
+- Use it to evaluate AI Lint
+- Apply it to personal/internal projects
+- Modify it for your own use
+
+You may NOT:
+- Redistribute or resell
+- Use to train AI/ML models
+- Use in commercial consulting/education offerings
+
+For commercial use with full language coverage, purchase a pack.
+
+---
+
+## Why AI Lint exists
+
+AI models produce code that compiles. Then you review it and feel the familiar dread: it's not wrong enough to reject quickly—just wrong enough to quietly poison the codebase.
+
+The problem isn't syntax. It's judgment.
+
+AI Lint makes that judgment explicit. It tells your agent what patterns belong, what should be rejected, and when to ask a human instead of guessing.
+
+---
+
+*"Works" isn't good enough. The goal is code that belongs.*

.ai-lint/doctrine/architecture.md

@@ -0,0 +1,64 @@
+# Architecture Doctrine (Preview)
+
+Code that works is not enough. Code must be **ownable**—understandable by one person in one sitting.
+
+## 1. State Count Limit
+**Reject**: More than 15-20 mutable state variables in a single file/module.
+**Why**: Each variable is a dimension. 20 variables = 2²⁰ possible states. Undebuggable.
+**Do**: If you need more, you have multiple modules pretending to be one. Split by concern.
+
+## 2. One Problem, One Solution
+**Reject**: Multiple approaches to the same problem coexisting (e.g., three "unblock" systems).
+**Why**: Each approach has edge cases. Multiple approaches multiply edge cases.
+**Do**: Pick one. Delete the others. If the new one fails, fix it—don't add a third.
+
+## 3. Core Path Clarity
+**Reject**: Business logic buried under defensive armor.
+**Why**: The 80% case becomes invisible. New developers see only edge cases.
+**Do**: Core path should be readable top-to-bottom in <100 lines. Edge handling is modules with on/off switches.
+
+## 4. File Size Discipline
+**Reject**: Files over 500 lines (hard limit: 1000).
+**Why**: Large files are symptoms of mixed concerns. "I'll refactor later" never happens.
+**Do**: When a file grows, extract. Don't wait until it's 4000 lines.
+
+## 5. Explicit State Ownership
+**Reject**: State scattered across file-level variables, closures, and object properties.
+**Why**: "Where is this set?" becomes unanswerable.
+**Do**: Single state object per concern. All mutations through it. Log on change if debugging.
+
+## 6. Function Density
+**Reject**: Functions over 50 lines (soft limit), 100 lines (hard limit).
+**Why**: Long functions hide multiple responsibilities. "I need to read 100 lines to understand this."
+**Do**: Extract. Name the extracted function for what it does, not when it's called.
+
+## 7. Monotonic Observation
+**Reject**: Conditioning capture/processing of external output on local input state.
+**Why**: You silently drop or delay real events. Bugs become non-reproducible and “fixed” by timing.
+**Do**: Always observe and record external output when it arrives. Gate **actions** (injections, commits) on local input state, not observation.
+
+## 8. Single-Entry Primitives
+**Reject**: Multiple paths to commit/inject/queue/capture in the same system.
+**Why**: Side effects become inconsistent and race-prone.
+**Do**: Define a single-entry primitive for each side-effect class (commit, inject, queue, capture) and route all call sites through it.
+
+## 9. Scene Purity
+**Reject**: Scenes/state machines performing side effects directly.
+**Why**: Logic becomes untestable and action ordering becomes implicit.
+**Do**: Scenes emit explicit actions; a runtime applies those actions via primitives.
+
+## 10. Dequeue-Time Validation
+**Reject**: Queue predicates evaluated only at enqueue time.
+**Why**: Time-sensitive actions become stale; prompts/reminders fire after they should be invalid.
+**Do**: Re-evaluate predicates at dequeue time (fat edge).
+
+## 11. Interrupts as First-Class Actions
+**Reject**: Interrupt behavior implemented out-of-band or bypassing the queue/commit primitives.
+**Why**: Creates invisible control flow and inconsistent handling across features.
+**Do**: Represent interrupts as actions that flow through the same primitives with explicit flags.
+
+---
+
+*This is a preview. The full Architecture Doctrine includes additional rules on dependency direction, timer accounting, synchronous initialization, feature flags, and complexity metrics tables.*
+
+*Get the complete doctrine at https://ai-lint.dosaygo.com*