feat(standards): add code standards, tech stack, and test infrastructure

- pyproject.toml: Python tooling config (ruff, pyright, pytest, scoped deps)
- biome.json: JavaScript lint + format config
- jsconfig.json: JS type checking via checkJs
- .editorconfig: Cross-editor whitespace rules
- .python-version / .nvmrc: Pin Python 3.12 and Node 18
- requirements-hooks.txt: Scoped hook deps (PyYAML only)
- tests/python/: 57 test cases (44 layer classification + 13 RAG chunker)
- reference/CODE-STANDARDS.md: Code conventions for JS + Python
- reference/TECH-STACK.md: Canonical technology choices + rationale
- reference/SOURCE-TREE.md: Directory structure reference
- package.json: Added lint, format, test, test:coverage scripts

Ruff passes clean (0 errors). All 57 tests pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: thiagofinch

.editorconfig

@@ -0,0 +1,27 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.js]
+indent_style = space
+indent_size = 2
+max_line_length = 100
+
+[*.py]
+indent_style = space
+indent_size = 4
+max_line_length = 100
+
+[*.{json,yaml,yml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

.nvmrc

@@ -0,0 +1 @@
+18

.python-version

@@ -0,0 +1 @@
+3.12

biome.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "complexity": {
+        "noForEach": "off"
+      },
+      "suspicious": {
+        "noConsole": "off"
+      },
+      "style": {
+        "noParameterAssign": "off"
+      }
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  },
+  "files": {
+    "include": ["bin/**/*.js"],
+    "ignore": ["node_modules", "vendor", ".claude/aios"]
+  }
+}

jsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "checkJs": true,
+    "strict": false,
+    "module": "es2022",
+    "moduleResolution": "node",
+    "target": "es2022",
+    "baseUrl": ".",
+    "paths": {
+      "#lib/*": ["./bin/lib/*"],
+      "#utils/*": ["./bin/utils/*"]
+    }
+  },
+  "include": ["bin/**/*.js"],
+  "exclude": ["node_modules", "vendor"]
+}

pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = "mega-brain"
+version = "1.3.0"
+requires-python = ">=3.11"
+dependencies = [
+    "PyYAML>=6.0,<7.0",
+]
+
+[project.optional-dependencies]
+pipeline = [
+    "PyYAML>=6.0,<7.0",
+]
+speakers = [
+    "pyannote.audio>=3.1.0",
+    "torch>=2.0.0,<3.0.0",
+    "torchaudio>=2.0.0,<3.0.0",
+    "numpy>=1.24.0",
+    "scipy>=1.10.0",
+    "assemblyai>=0.28.0",
+]
+rag = [
+    "voyageai>=0.3.0",
+    "rank-bm25>=0.2.2",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.8",
+    "pyright>=1.1",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["core", ".claude/hooks"]
+exclude = [
+    "core/intelligence/pipeline/read_ai_*.py",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF"]
+ignore = [
+    "E501",    # line too long — handled by formatter
+    "UP007",   # Use X | Y for union — keep Optional for 3.11 compat
+    "RUF013",  # implicit-optional — existing codebase pattern, fix gradually
+    "SIM102",  # collapsible-if — readability preference
+    "SIM108",  # if-else-block-instead-of-if-exp — readability preference
+    "SIM110",  # reimplemented-builtin — clarity over brevity
+    "SIM103",  # needless-bool — clarity preference
+    "SIM105",  # suppressible-exception — explicit try/except is clearer
+    "SIM116",  # if-else-block-instead-of-dict-lookup — readability
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["core"]
+
+[tool.ruff.lint.per-file-ignores]
+".claude/hooks/*" = ["E722", "F401", "RUF001"]  # hooks: bare except, re-exports, unicode emoji
+"core/intelligence/speakers/*" = ["F401"]  # conditional imports for optional GPU deps
+"core/intelligence/pipeline/read_ai_*" = ["E999"]  # special syntax files
+"core/intelligence/entities/*" = ["RUF001"]  # unicode chars in business domain strings
+"core/intelligence/pipeline/autonomous_processor.py" = ["N818"]  # legacy exception name
+"core/intelligence/rag/evaluator.py" = ["RUF034"]  # useless if-else in demo code
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"
+include = ["core"]
+exclude = [
+    ".claude/hooks",
+    "**/__pycache__",
+    "core/intelligence/pipeline/read_ai_*.py",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/python"]
+python_files = "test_*.py"
+python_functions = "test_*"
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["core/intelligence"]
+omit = ["*/__pycache__/*", "*/__init__.py"]
+
+[tool.coverage.report]
+fail_under = 40
+show_missing = true

reference/CODE-STANDARDS.md

@@ -0,0 +1,209 @@
+# Code Standards — Mega Brain
+
+> **Version:** 1.0.0 | **Date:** 2026-03-05
+
+---
+
+## 1. Overview
+
+This document defines code conventions for the Mega Brain project. It covers two languages (JavaScript, Python) across three codebases (`bin/`, `core/intelligence/`, `.claude/hooks/`).
+
+**Enforcement:** `ruff` (Python), `biome` (JS). Config in `pyproject.toml` and `biome.json`.
+
+---
+
+## 2. JavaScript Standards (bin/)
+
+### Runtime & Module System
+- Node.js >= 18.0.0, ESM only (`"type": "module"`)
+- All files use `import`/`export`. No `require()`.
+
+### Style (enforced by Biome)
+- Semicolons: yes
+- Quotes: single
+- Indentation: 2 spaces
+- Trailing commas: yes (multi-line)
+- Max line length: 100
+
+### Naming
+- Files: `kebab-case.js`
+- Functions/variables: `camelCase`
+- Constants: `SCREAMING_SNAKE`
+
+### Imports
+```js
+// 1. Node.js builtins
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+
+// 2. Third-party (npm)
+import chalk from 'chalk';
+
+// 3. Local modules
+import { readLicense } from './lib/license.js';
+```
+
+### Error Handling
+- Top-level: `main().catch(err => { console.error(err.message); process.exit(1); })`
+- Expected failures: bare `catch {}` when error is not needed
+- Logged failures: `catch (err)` with meaningful message
+
+### Documentation
+- JSDoc `/** */` on all exported functions
+- At minimum: description, `@param`, `@returns`
+
+### Type Safety
+- No TypeScript (project decision)
+- Use JSDoc type annotations + `jsconfig.json` with `checkJs: true`
+
+---
+
+## 3. Python Standards — Core (core/intelligence/)
+
+### Runtime
+- Python >= 3.11 (pinned in `.python-version`)
+- Config centralized in `pyproject.toml`
+
+### Style (enforced by Ruff)
+- PEP 8 compliant
+- Quotes: double
+- Indentation: 4 spaces
+- Max line length: 100
+
+### Naming
+- Files: `snake_case.py`
+- Functions/variables: `snake_case`
+- Classes: `PascalCase`
+- Private: leading underscore `_`
+- Constants: `SCREAMING_SNAKE`
+
+### Imports (enforced by Ruff isort)
+```python
+# 1. Stdlib (alphabetical)
+import json
+import re
+import sys
+
+# 2. Third-party
+import yaml
+
+# 3. Local
+from core.paths import ROOT, KNOWLEDGE_EXTERNAL, ROUTING
+```
+
+### Paths — CRITICAL RULE
+**All files MUST import from `core.paths`.** Never compute `BASE_DIR` locally.
+
+```python
+# CORRECT
+from core.paths import ROOT, KNOWLEDGE_EXTERNAL
+
+# WRONG — never do this
+BASE_DIR = Path(__file__).resolve().parent.parent.parent.parent
+```
+
+### Type Hints
+- Required on all public function signatures
+- Use `typing` module for 3.11 compatibility (`Optional`, `Dict`, `List`)
+- Enforced by `pyright` in basic mode on `core/`
+
+### Docstrings
+- Google style (Args, Returns, Raises)
+- Required on modules and public functions
+- Optional on private helpers
+
+### Error Handling
+- Use specific exception tuples: `except (YAMLError, OSError):`
+- Never use bare `except:`
+- Add `logging.warning()` in catch blocks for traceability
+
+### Logging
+- All intelligence scripts: `import logging; logger = logging.getLogger(__name__)`
+- Use `logger.warning()` in error paths
+- Use `print()` only in `if __name__ == "__main__"` CLI entry points
+
+---
+
+## 4. Python Standards — Hooks (.claude/hooks/)
+
+### Dependency Constraint
+**stdlib + PyYAML ONLY.** This is a distribution constraint — hooks ship with the npm package. No third-party imports beyond PyYAML.
+
+### Exit Codes
+- `0` = success (hook passed)
+- `1` = warning (continue with notification)
+- `2` = error/block (stop execution)
+
+### Communication
+- Output: JSON to stdout
+- Input: JSON from stdin (hook event payload)
+- Timeout: 30 seconds max
+
+### Prohibited Patterns
+- `2>/dev/null || true` — never suppress errors
+- `subprocess.run(shell=True)` — security risk
+
+---
+
+## 5. File & Directory Conventions
+
+- Directories: lowercase (`inbox`, `system`)
+- Config files: SCREAMING-CASE (`STATE.json`, `MEMORY.md`)
+- Skills: kebab-case directories (`knowledge-extraction/`)
+- New output paths: MUST be added to `core/paths.py` ROUTING dict
+
+---
+
+## 6. Testing Standards
+
+### Frameworks
+- Python: `pytest` with `pytest-cov`
+- JS: Node built-in test runner (`node:test`)
+
+### Test Location
+```
+tests/
+  python/
+    test_validation/    # Layer classification tests
+    test_rag/           # RAG chunker, indexer, query tests
+    test_hooks/         # Hook behavior tests
+  js/                   # CLI tests
+  integration/          # Cross-language tests
+```
+
+### Naming
+- Python: `test_*.py`, functions `test_*`
+- JS: `test_*.js`
+
+### Coverage Targets
+- Phase 1: 40% on `core/intelligence/rag/` and `core/intelligence/validation/`
+- Phase 2: 50% on `core/intelligence/` overall
+- Steady state: 70% on new code
+
+---
+
+## 7. Git Workflow
+
+- Branch naming: `type/issue-XX-description`
+- Commit messages: Conventional Commits (`feat`, `fix`, `chore`, `docs`, `refactor`)
+- No direct commits to `main`
+- `git push` blocked for non-devops agents (settings.json deny list)
+
+---
+
+## 8. Security Standards
+
+- NEVER hardcode secrets (enforced by `.gitleaks.toml` + `trufflehog`)
+- `.env` is the ONLY credential source
+- `.mcp.json` uses `${ENV_VAR}` syntax, never plaintext tokens
+- All hooks: `"timeout": 30` (ANTHROPIC-STANDARDS)
+- `curl`/`wget` denied in bash hooks
+
+---
+
+## 9. Dependency Management
+
+- Python: `pyproject.toml` (primary), scoped optional dependencies
+- JS: `package.json` + `package-lock.json` (committed)
+- Hooks: `requirements-hooks.txt` (PyYAML only)
+- New dependencies require justification in PR description