Added project documentation in wiki and established INTENT.md

wiki/KaizenGuidance.md

@@ -0,0 +1,65 @@
+KaizenGuidance
+
+*Codebase improvement programs*
+
+A curated, language-agnostic library of Code Quality Guides where each guide is:
+
+- Readable for humans,
+- Checkable by linters/static analyzers,
+- Refactorable by codemods/agents,
+- Measurable with before/after quality metrics.
+
+Think “Clean Code + MISRA precision + Sonar/ESLint automation + AI codemods.”
+
+See also: https://chatgpt.com/share/68d6b45b-17f8-8009-8d15-c174f53d2591
+
+## Guide anatomy (single source of truth)
+- Each guide lives as a versioned folder containing:
+- A manifest (machine-readable spec)
+- A narrative (rationale, trade-offs, examples)
+- Checks (lint/static analysis mappings)
+- Refactors (codemods, recipes, prompts)
+- Tests (fixtures + expected diffs)
+- Metrics (what ‘better’ means)
+
+## Rule expression & execution pipeline
+a) Parse → Check → Plan → Refactor → Test → Measure → Report
+- Parse: build AST/index (libcst for Py, ts-morph/jscodeshift for TS/JS, OpenRewrite for Java, Clang-Tidy/LibTooling for C/C++).
+- Check: run native linters + Semgrep queries from guide.yaml (unified output schema).
+- Plan: produce a Change Plan (JSON) listing targets & suggested transforms.
+- Refactor: deterministic codemods first; ambiguous edits delegated to an Agent with a strict prompt & test harness.
+- Test: run unit tests + mutation tests (where available).
+- Measure: compute deltas for maintainability index (MI), cyclomatic complexity, duplication, lint issues, “hotspot*rule” intersections (code churn × smells).
+- Report: markdown/HTML summary + SARIF for code scanning.
+
+## Example guides (initial catalog)
+
+1. API Design
+- Avoid boolean “success” returns (above)
+- Prefer narrow, explicit exceptions
+- Make side effects explicit (naming & module boundaries)
+
+2. Readability & Structure
+- Function length & parameter count thresholds (with exceptions mechanism)
+- Cohesion over convenience: one reason to change (SRP pragmatically)
+- Replace “god module/class” with feature modules
+
+3. Testing & Contracts
+- Fast tests default; slow/flaky quarantined
+- Golden tests for parsers/formatters
+- Pre/postconditions via lightweight asserts or type contracts
+
+4. Performance-safe Patterns
+- Avoid N+1 queries (framework-specific codemods)
+- Replace quadratic hot-loops with map/join or indexed lookups
+- Lazy vs eager boundaries (measurable)
+
+5. Security & Robustness
+- Input validation at boundaries (web/cli)
+- No raw SQL without parameterization
+- Secrets/config separation; env-based wiring
+
+Each guide ships checks + codemods + agent prompts + metrics.
+
+
+xxx