karukia-mcp 3.0.5 → 3.1.0

package/LICENSE

@@ -1,9 +1,9 @@
 Business Source License 1.1
 
 Licensor:             KARUK IA (contact@karukia.com)
-Licensed Work:        karukia-mcp v3.0.5
+Licensed Work:        karukia-mcp v3.1.0
                       The Licensed Work is (c) 2026 KARUK IA
-Change Date:          March 6, 2028
+Change Date:          April 2, 2036
 Change License:       Apache License, Version 2.0
 
 Additional Use Grant:
@@ -17,7 +17,6 @@ Additional Use Grant:
     - Personal projects and individual developers
     - Educational institutions (classroom, student projects, research)
     - Non-profit organizations
-    - Non-profit organizations
 
   Production use is NOT permitted without a commercial license for:
     - Consulting firms (ESN) using karukia-mcp for client-facing work

package/README.md

@@ -2,7 +2,7 @@
 
 **The complete AI-assisted development methodology, delivered via MCP.**
 
-**Latest: v3.0.5** — 26 tools, 19 skills, 1673+ checkpoints across 11 audit dimensions.
+**Latest: v3.1.0** — 27 tools, 20 skills, 1800+ checkpoints across 11 audit dimensions. Multi-AI platform support.
 
 
 ```
@@ -15,7 +15,7 @@
    AI methodology for highly regulated industries · Made in Guadeloupe 🇬🇵
 ```
 
-26 tools, 19 skills, 1673+ checkpoints across 11 audit dimensions. Works with any AI platform (Claude Code, Cursor, Windsurf, Copilot...) through the Model Context Protocol.
+27 tools, 20 skills, 1800+ checkpoints across 11 audit dimensions. Built for **Claude Code** and **OpenAI Codex**. Compatible with any MCP client.
 
 ---
 
@@ -28,29 +28,37 @@
 
 KARUKIA is a structured development methodology built around specialized AI personas. Each persona (Neo for security, Jeffrey for architecture, Viper for pentesting, Opo for quality...) comes with its own workflow, guard rails, and knowledge base.
 
-When you call a KARUKIA tool, the MCP server returns a complete prompt — persona identity, workflow, checklists, templates — that transforms your AI assistant into that specialist for the session.
+When you call a KARUKIA tool, the MCP server returns a complete prompt — persona identity, standardized workflow, coverage tracking, checklists, templates — that transforms your AI assistant into that specialist for the session.
 
 ```
 You: "Run a security audit"
   -> AI calls neo tool
-  -> MCP returns full Neo persona prompt + 445 security controls inline
+  -> MCP returns:
+       GUARD (non-negotiable obligations)
+     + Neo persona (identity, style, expertise)
+     + WORKFLOW (6-step standardized process)
+     + COVERAGE (load previous scan manifest, prioritize unscanned files)
+     + Checklists (445 security controls inline)
+     + AGENTS (multi-agent parallel exploration)
   -> AI becomes Neo, follows the methodology, produces structured findings
+  -> Coverage manifest written: 67% scanned — next session picks up where this one left off
 ```
 
-## The 11 Audit Dimensions
+## The 12 Audit Dimensions
 
 ```
-SECURITY  → Neo (445 pts)      "Is my code secure?"
-QUALITY   → Opquast (245 pts)  "Is my app well-built?"
-OFFENSIVE → Viper (245+ tests) "How would a hacker break in?"
-TS        → ts_quality (118)   "Is my TypeScript clean?"
-CSS       → css_quality (55)   "Is my design system maintainable?"
-ARCHI     → archi (70)         "Is my architecture sound?"
-TESTS     → test_coverage (68) "Am I testing the right things?"
-PERF      → perf (90)          "Where are the bottlenecks?"
-DEBT      → debt (55)          "What's slowing us down?"
-HDS/ISO   → audit_expert (200+)"Am I ready for certification?"
-SCAN      → karukia_scan       "Run all 11 dimensions at once"
+SECURITY     → Neo (445 pts)      "Is my code secure?"
+QUALITY      → Certix (369 pts)   "Is my app well-built?"
+OFFENSIVE    → Viper (245+ tests) "How would a hacker break in?"
+DUE DILIGENCE→ deep_review (12ax) "Is this codebase investment-ready?"
+TS           → ts_quality (118)   "Is my TypeScript clean?"
+CSS          → css_quality (55)   "Is my design system maintainable?"
+ARCHI        → archi (70)         "Is my architecture sound?"
+TESTS        → test_coverage (68) "Am I testing the right things?"
+PERF         → perf (90)          "Where are the bottlenecks?"
+DEBT         → debt (55)          "What's slowing us down?"
+HDS/ISO      → audit_expert (200+)"Am I ready for certification?"
+SCAN         → karukia_scan       "Run all 11 dimensions at once"
 ```
 
 ---
@@ -78,7 +86,7 @@ Create or edit `.mcp.json` at the root of your project:
 
 ### Step 2 — Restart your AI client
 
-Restart Claude Code (`/quit` then relaunch) or your IDE. The 27 KARUKIA tools are now available.
+Restart Claude Code (`/quit` then relaunch) or your IDE. All 27 KARUKIA tools are now available.
 
 > On first launch, `npx` downloads the package automatically (~175 KB). Subsequent launches use the cached version.
 
@@ -136,7 +144,7 @@ Then add to your global AI config (`~/.claude.json` for Claude Code):
 
 ---
 
-## 26 Tools
+## 27 Tools
 
 ### Essential (start here)
 
@@ -155,11 +163,12 @@ Each skill returns a complete prompt that transforms your AI into a specialist.
 | `neo` | Security Auditor | Defensive audit against 6 frameworks (OWASP, HDS, ISO 27001, SOC 2, PCI-DSS, HIPAA) |
 | `viper` | Pentest Brigade | Offensive testing with 16 agents, CVSS v4 scoring, MITRE ATT&CK mapping |
 | `jeffrey` | Full-Stack Architect | Feature implementation with TDD and security validation |
-| `opo` | Quality Validator | Web quality against 245 Opquast rules |
-| `audit_opquast` | Quality Auditor | Deep Opquast compliance audit with 14 thematic checklists |
+| `opo` | Quality Validator | Web quality against 369 Certix rules |
+| `audit_certix` | Quality Auditor | Deep Certix compliance audit with 5 profile checklists |
 | `ebios_rm_audit` | Risk Analyst | EBIOS Risk Manager methodology (ANSSI) — formal risk analysis |
 | `security_hardening` | Hardening Planner | Security improvement chantiers |
 | `doc_refactor` | Doc Auditor | Documentation accuracy audit vs actual code |
+| `deep_review` | Due Diligence Lead | 12-axis technical review: code, archi, scalability, costs, security, resilience, tests, DX, frontend perf, regulatory, AI, maintainability |
 
 ### Dimensional Skills (v3.0 New)
 
@@ -171,7 +180,7 @@ Each skill returns a complete prompt that transforms your AI into a specialist.
 | `test_coverage` | 68 | Test inventory — frontend/backend coverage quality |
 | `perf` | 90 | Performance — frontend, backend, build/bundle |
 | `debt` | 55 | Technical debt — dead code, dependency health, code smells |
-| `karukia_scan` | 1673+ | **Global scan** — all 11 dimensions in parallel |
+| `karukia_scan` | 1800+ | **Global scan** — all 11 dimensions in parallel |
 | `audit_expert_hds` | 200+ | Expert HDS 2.0/ISO 27001 — 8 domains, certification readiness |
 | `change_report` | — | Change management report (ISO 27001 A.8.32) |
 
@@ -179,7 +188,7 @@ Each skill returns a complete prompt that transforms your AI into a specialist.
 
 | Tool | Description |
 |------|-------------|
-| `list_checklists` | Browse all 31 checklists by category |
+| `list_checklists` | Browse all 22 checklists by category |
 | `suggest_checklists` | Describe your project — get a prioritized audit plan |
 | `generate_report` | Compile audit results into a scored Markdown report |
 
@@ -193,7 +202,7 @@ Each skill returns a complete prompt that transforms your AI into a specialist.
 
 ---
 
-## 31 Checklists
+## 22 Checklists
 
 ### Defensive Security (Neo) — 6 checklists, 445 controls
 
@@ -206,11 +215,9 @@ Each skill returns a complete prompt that transforms your AI into a specialist.
 | **PCI-DSS v4.0** | 97 | Payment processing |
 | **HIPAA** | 67 | Health data, US |
 
-### Web Quality (Opquast) — 14 checklists, 245 rules
+### Web Quality (Certix) — 5 checklists, 369 rules
 
-Content, personal data, e-commerce, forms, identity, images, internationalization, links, navigation, newsletter, presentation, security UX, server performance, and code structure.
-
-Based on [Opquast](https://www.opquast.com/) — the French web quality reference used by 15,000+ professionals.
+Five profile-based checklists covering all aspects of web quality: DEV (development), UX (user experience), CONT (content), OPS (operations), and JUR (legal/compliance).
 
 ### Offensive Security (Viper) — 4 checklists, 245+ tests
 
@@ -235,6 +242,74 @@ Based on [Opquast](https://www.opquast.com/) — the French web quality referenc
 
 ---
 
+## Multi-AI Platform Support
+
+KARUKIA is built for and tested with **Claude Code** and **OpenAI Codex**. It is compatible with any MCP client (Cursor, Windsurf, Copilot, etc.), though those have not been tested with the `client_id` parameter.
+
+All skill tools accept an optional `client_id` parameter: `"claude"` (default), `"codex"`, or `"generic"`. The entire prompt adapts:
+
+| What adapts | Claude (`client_id: "claude"`) | Codex (`client_id: "codex"`) | Generic |
+|---|---|---|---|
+| Sub-agent orchestration | Task API with model hints | Natural language instructions | Natural language |
+| Config file generated | `CLAUDE.md` | `CODEX-PROJECT.md` | `AI-CONFIG.md` |
+| Model references | Opus / Sonnet | Generic model names | Generic model names |
+| Memory root | `karukia/` | `karukia/` | `karukia/` |
+
+This is the first MCP methodology server with true multi-AI platform abstraction. One npm package, one `.mcp.json` entry, full methodology regardless of the AI behind it.
+
+---
+
+## Iterative Coverage Tracking (New in v3.1)
+
+Every audit skill tracks which files have been analyzed across sessions. No file in your codebase is left behind.
+
+**How it works:**
+1. **Scan 1** -- KARUKIA analyzes your codebase, covers ~40% of in-scope files. Writes a coverage manifest to `karukia/memory/coverage/{skill}-latest.json`.
+2. **Scan 2** -- Reads the previous manifest, skips already-analyzed files, covers the next ~40%. Cumulative: 80%.
+3. **Scan 3** -- Picks up the remaining 20%. Status: **COMPLETE**.
+
+After any scan, the manifest records exactly which files were analyzed, which were skipped, and what findings were discovered -- with severity counts. When files are modified after a complete scan, only the changed files are re-analyzed.
+
+```
+--- COVERAGE neo ---
+Scope total     : 120 files
+This scan       : 48 files analyzed
+Cumulative      : 96 / 120 (80%)
+Status          : PARTIAL
+
+Remaining -- next scan starts with:
+  - src/auth/session.ts
+  - src/api/handlers/patient.ts
+  - ... (24 more)
+---
+```
+
+Coverage scopes are resolved from project-specific config (`karukia/config/coverage-scopes.json`, generated by `install`) or from the skill's default globs. This means a TypeScript audit scans `**/*.ts` files, a CSS audit scans `**/*.css` and `**/*.scss`, and so on.
+
+---
+
+## Standardized 6-Step Workflow (New in v3.1)
+
+Every audit skill follows the same structured workflow:
+
+```
+Step 0   : PREPARATION        -- Create session, load references
+Step 0.5 : COVERAGE LOADING   -- Read previous manifest, prioritize unscanned files
+Step 1   : EXPLORATION         -- Multi-agent parallel scanning (each agent covers a scope)
+Step 2   : ANALYSIS            -- Synthesize discoveries, identify required actions
+Step 3   : EXECUTION           -- Execute action plan, update progress after each action
+Step 4   : VALIDATION          -- Lint, build, test. Fix ALL issues before closure
+Step 4.5 : COVERAGE WRITE      -- Write coverage manifest for next session
+Step 5   : CLOSURE             -- Finalize session files, update trackers and knowledge base
+```
+
+Key workflow features:
+- **Rule of 2 actions**: After every 2 read operations, findings MUST be written to `findings.md`. Context is never lost, even if the session is interrupted.
+- **3-attempt protocol**: Diagnose and fix -- alternative approach -- rethink assumptions -- escalate to user. No blind retries.
+- **Knowledge persistence**: Lessons learned and reusable patterns are saved to `karukia/memory/knowledge/` between sessions. The methodology gets smarter over time.
+
+---
+
 ## Usage Examples
 
 ### Full security audit
@@ -255,6 +330,12 @@ Your AI calls `jeffrey` — becomes the Jeffrey architect — implements with TD
 
 Your AI calls `viper` — deploys the Brigade methodology with 16 specialized agents across Recon, Surface Analysis, and Exploitation phases.
 
+### Due diligence on a codebase (New in v3.1)
+
+> "karukia deep_review"
+
+Your AI calls `deep_review` — deploys a brigade of 6 parallel agents — each covers 2 of the 12 axes (code quality, architecture, scalability, costs, security, resilience, tests, DX, frontend perf, regulatory compliance, AI patterns, maintainability). Produces a scorecard with grades A+ to F per axis, a global score out of 120, and a prioritized action plan. Use it before an investment, a CTO takeover, or a major refactor.
+
 ### Orchestrate everything
 
 > "karukia: add a logout button and audit security"
@@ -285,7 +366,7 @@ Built from the experience of securing a healthcare SaaS application for HDS 2.0
 KARUKIA is a structured AI-assisted development methodology built around three principles:
 
 1. **Separation of concerns** — Security, quality, and implementation are separate disciplines handled by separate AI personas.
-2. **Formal checkpoints over gut feeling** — 1673+ documented checkpoints beat "I think it's fine."
+2. **Formal checkpoints over gut feeling** — 1800+ documented checkpoints beat "I think it's fine."
 3. **Defense in depth** — Defensive audit first, quality validation second, offensive testing last.
 
 Built from real-world experience securing a healthcare SaaS application to HDS 2.0 / ISO 27001 standards.
@@ -320,7 +401,7 @@ If your company or consulting firm uses KARUKIA for production work or deploys i
 | **Business** | 12 000 | Up to 50 developers |
 | **Enterprise** | 20 000 | Unlimited developers + priority support |
 
-All plans include: full access to all 26 tools, 19 skills, 1673+ checkpoints across 11 audit dimensions, and all updates for the license duration. Annual license, renewable.
+All plans include: full access to all 27 tools, 20 skills, 1800+ checkpoints across 11 audit dimensions, and all updates for the license duration. Annual license, renewable.
 
 **Contact:** contact@karukia.com
 
@@ -328,4 +409,4 @@ All plans include: full access to all 26 tools, 19 skills, 1673+ checkpoints acr
 
 ### Change License
 
-On March 6, 2028, the Licensed Work will automatically convert to the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+On April 2, 2036, the Licensed Work will automatically convert to the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).