aizee 6.8.0__tar.gz

aizee-6.8.0/.env.example

@@ -0,0 +1,133 @@
+# aiZee — Environment Variables Template
+# Copy this file to .env and fill in your values.
+# .env is loaded by runtime/mcp_client.py for MCP server configuration.
+
+# =============================================================================
+# Core aiZee Configuration
+# =============================================================================
+
+# Root directory of aiZee (where rules/, skills/, workflows/ live).
+# If not set, config.discover_root() will try to find it automatically.
+# AIZEE_ROOT=D:\.ai
+
+# Project root for the current project being worked on (optional).
+# AGENT_PROJECT_ROOT=
+
+# =============================================================================
+# Encryption (at-rest encryption for state/budget.json)
+# =============================================================================
+
+# Fernet encryption key for sensitive state files (PRODUCTION RECOMMENDED).
+# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+# AIOS_ENCRYPTION_KEY=
+
+# Alternative: path to a key file OUTSIDE the OS root (survives root switches).
+# AIOS_ENCRYPTION_KEY_FILE=/etc/aizee/enc.key
+
+# WARNING: if neither is set, a key is auto-generated at <AIZEE_ROOT>/state/.encryption_key.
+# Switching AIZEE_ROOT orphans previously encrypted state — budget.json is then
+# quarantined to .corrupt.bak and limits silently reset to defaults (H4).
+# AIOS_ENCRYPTION_KEY=plaintext disables encryption entirely (dev only).
+
+# Ed25519/HMAC signing key for audit log entries (production: outside OS root).
+# AIZEE_AUDIT_SIGN_KEY=/etc/aizee/audit_sign.pem
+
+# =============================================================================
+# Dashboard (web UI for monitoring agents, metrics, budget)
+# =============================================================================
+
+# Dashboard is open-access by default (localhost-only, CSRF-protected POSTs).
+# Opt into Bearer authentication by setting a token:
+# AIZEE_DASHBOARD_TOKEN=your-secure-token-here
+
+# CORS origin whitelist (comma-separated).
+# AIZEE_DASHBOARD_ORIGIN=http://127.0.0.1:8080
+
+# Dashboard server settings (AIZEE_* preferred, AGENT_OS_* still accepted for backward compat).
+# AIZEE_DASHBOARD_MAX_BODY_SIZE=1048576
+# AIZEE_DASHBOARD_RATE_LIMIT=120
+# AIZEE_DASHBOARD_RATE_WINDOW=60
+# AIZEE_DASHBOARD_RATE_MAX_ENTRIES=10000
+# AIZEE_DASHBOARD_ORIGINS=http://127.0.0.1:8080,http://localhost:8080
+# AIZEE_DASHBOARD_TRUSTED_PROXIES=
+# AIZEE_DASHBOARD_HOST=127.0.0.1
+# AGENT_OS_DASHBOARD_MAX_BODY_SIZE=1048576 (legacy)
+# AGENT_OS_DASHBOARD_RATE_LIMIT=120 (legacy)
+# AGENT_OS_DASHBOARD_RATE_WINDOW=60 (legacy)
+# AGENT_OS_HOST=127.0.0.1 (legacy)
+
+# =============================================================================
+# Observability (Sentry integration)
+# =============================================================================
+
+# Sentry DSN for error tracking (optional).
+# SENTRY_DSN=
+
+# Sentry traces sample rate (0.0 to 1.0).
+# SENTRY_TRACES_SAMPLE_RATE=0.1
+
+# Sentry environment name.
+# SENTRY_ENVIRONMENT=production
+
+# =============================================================================
+# Freelance Platform Plugins
+# =============================================================================
+
+# --- Upwork ---
+UPWORK_CLIENT_ID=
+UPWORK_CLIENT_SECRET=
+
+# --- Freelancer ---
+FREELANCER_OAUTH_TOKEN=
+# FREELANCER_ACCOUNTS=
+
+# --- LinkedIn ---
+LINKEDIN_ACCESS_TOKEN=
+# LINKEDIN_MCP_TOKEN_PATH=
+
+# --- Fiverr ---
+# (Fiverr uses MCP server config, no env vars required)
+
+# =============================================================================
+# Graphify (knowledge graph MCP wrapper)
+# =============================================================================
+
+# Log file path for graphify wrapper (optional).
+# GRAPHIFY_WRAPPER_LOG=
+
+# =============================================================================
+# Governed LLM Gateway (runtime/gateway_proxy.py — `aizee gateway serve`)
+# =============================================================================
+
+# Provider API keys referenced by gateway.yaml `api_key_env` entries.
+# The gateway enforces kernel gates on every outbound LLM request and
+# fails over between providers on timeout/429/5xx.
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+# GEMINI_API_KEY=
+
+# Opt-in tool-output compression (RTK/Headroom pattern): collapse repetitive
+# boilerplate in large MCP results before they reach the model.
+# AIZEE_OUTPUT_FILTER=1
+
+# =============================================================================
+# REA (reverse engineering — local source checkout, optional)
+# =============================================================================
+
+# Absolute path to a local morluto/rea checkout. When unset, agents resolve
+# the sibling `../rea` convention next to the aizee root, then `npx rea-agents`.
+# REA_HOME=
+
+# Bring-your-own analysis engines (all optional; static JS/.NET needs none):
+# GHIDRA_INSTALL_DIR=
+# HOPPER_LAUNCHER_PATH=       # macOS/Linux only — no Windows build
+# REA_IDA_MCP_CONFIG=          # paid — upstream IDA MCP registration JSON
+# REA_JADX_MCP_JAR=            # free — jadx-headless-mcp-0.7.1-all.jar (verify SHA-256 vs REA pin)
+# REA_KUNA_COMMAND=            # BYO — absolute path to caller-supplied kuna executable
+
+# =============================================================================
+# Dev/test interpreter note (Windows)
+# =============================================================================
+# The test suite runs on Python 3.10: `py -3.10 -m pytest ...` — system Python
+# 3.15 lacks the pinned dev deps. The `aizee` CLI itself runs on 3.15 via the
+# editable install (site-packages `aizee.pth` -> repo root); tests/tooling need 3.10.

aizee-6.8.0/AGENTS.md

@@ -0,0 +1,456 @@
+---
+
+name: aizee
+
+description: Sovereign AI engineering control plane. IDE global bootloader — sets the OS root once and loads all rules, skills, workflows, and tech-stack from it.
+
+license: MIT
+
+---
+
+
+
+# aiZee — Global Bootloader
+
+
+
+- **Root:** discovered via `AIZEE_ROOT` env or `config.discover_root()` (no hardcoded path).
+
+- Set `AIZEE_ROOT` if not already set. Use `PYTHONIOENCODING=utf-8` on Windows.
+
+- This file is the canonical root pointer. All other OS files discover the root via `AIZEE_ROOT` or `config.discover_root()` and are loaded relative to it.
+
+
+
+## Working Directory [DIR-01]
+
+- **Working directory: the directory containing this file ONLY** (the aiZee root — resolved in code via `AIZEE_ROOT` or `config.discover_root()`, never a hardcoded path `[OS-ROOT-01]`). All edits, new files, and modifications go here.
+
+- **A sibling `aizee/` deployment mirror, when present, is READ-ONLY.** Never edit the mirror directly — it is updated only via `scripts/update_aizee.bat`. To sync source → mirror, run the batch script.
+
+- When the IDE opens files from the mirror, copy them into the source root first, edit there, then sync back via the batch script.
+
+
+
+## Cold Start
+
+1. Read `global-roles.md`, `global-workflow.md`, and `Memory.md`.
+
+2. Detect personas with `aizee persona detect --multi` and load the returned `skills/` before acting.
+
+   **Persona switch directive (mandatory):** If the user message STARTS with a persona command — `#انتحل`, `/انتحل`, `#reset`, `/reset`, `#persona`, `/persona`, `#redetect`, `#switch` (or Arabic `#شخصيات`, `/شخصيات`, `#بدّل`, `/بدّل`, `#حالة`, `/حالة`, `#مين`, `/مين`, `#معلومات`, `/معلومات`) — strip the command token, then run `aizee persona detect --multi "<remaining text>"` and **ADOPT** the returned primary + secondary personas and load their `skills/` + `lords/` before acting. For status commands (`#حالة`, `/status`, `#مين`, `/معلومات`) print the currently active persona set instead of acting. This makes persona adoption explicit and verifiable; never silently ignore these commands.
+
+3. If the current project has `spec.md`, read it before any action.
+
+
+
+## Runtime Gate
+
+- Route every action through `runtime/kernel.py`.
+
+- Use `aizee check <action> --args '{"tokens":N}'` or `Kernel.act` to validate policy + budget.
+
+- No destructive action without explicit user approval.
+
+- Gate order: `Probity → Guardian → Policy → LoopDetector → Budget → Audit` (LoopDetector blocks repeated tool loops; Audit is hash-chained).
+
+
+
+## Command Surface & Auto-Triggers `[TRIG-01]`
+
+Every built-in capability below is installed and verified. Prefer the matching command over ad-hoc scripts — these are the supported paths.
+
+| Command | Use when |
+|---------|----------|
+| `aizee plan validate\|run\|resume <file>` | Multi-step tool orchestration, fan-outs, approval gates — author inert JSON plans, never executable code (see `skills/inert-plan-runner.md`) |
+| `aizee skill lock-check` / `lock-update` | After installing/updating skills, and before trusting the skill library (see `skills/skill-lock-integrity.md`) |
+| `aizee mcp freeze <srv> [--check]` | After MCP config changes and before trusting an MCP server (see `skills/mcp-surface-integrity.md`) |
+| `aizee check-docs` | After editing markdown docs — validates `[[file#symbol]]` refs (see `skills/docs-drift-check.md`) |
+| `aizee models [--catalog] [--query]` | Choosing a model, checking cost/context/reasoning — offline catalog, no network needed |
+| `aizee spec review <spec\|--file>` | Spec/plan review before implementation (EGM goldfish pipeline) |
+| `aizee intel <domain>` | Domain intelligence: DNS/WHOIS/certs/subdomains/IP |
+| `aizee eval` | Behavioral skill-scenario checks after changing skills/workflows |
+| `aizee skill link --pack <dir>` | Packaging skills for other agent harnesses (claude/codex/cursor/opencode) |
+| `aizee find <q>` / `aizee goal <obj>` | Discovering the right skill/workflow for a task |
+
+**Event-triggered rules (fire without being asked):**
+
+- When a task's domain matches none of the loaded persona skills → run `aizee find <task description>` before implementing; 155 skills + 80 workflows are indexed (name + triggers + description) even when not persona-mapped.
+- After adding/installing a skill → run `aizee skill lock-update`, then `aizee skill lock-check`.
+- After changing an MCP server config → run `aizee mcp freeze <server> --check`.
+- After editing `*.md` docs → run `aizee check-docs`.
+- Orchestrating 3+ dependent tool calls or an approval checkpoint → use `aizee plan`, not a script.
+- Before trusting generated orchestration → `aizee plan validate` first, cite `plan_hash` for approvals.
+
+## Context & Memory
+
+- Detect stack from `package.json` / `composer.json` and load matching `tech-stack/<pkg>-<ver>.md` only after reading the lockfile for the exact version (`[VER-01]`).
+
+- If `graphify-out/graph.json` exists, use `graphify query` or `query_graph` (MCP); never raw grep.
+
+- Query Context7 MCP for external libraries/frameworks before implementation; use `aizee_mcp/aizee_server.py` for global context.
+
+- Run `aizee memory ingest` when `rules/`, `tech-stack/`, or `workflows/` change; update `Memory.md` via `workflows/17-memory-sync.md` after every milestone.
+
+
+
+## Quality Gate
+
+Before declaring done, run from the OS root:
+
+- `ruff check .`
+
+- `mypy` (strict, 195 files)
+
+- `aizee test --full` (full suite with coverage, parallel by default — ~180s, 7653 tests, 100% cov)
+
+- `python eval/harness.py` (read-only: ruff + mypy + pytest + validate-globals)
+
+For quick iteration: run ONLY targeted tests (`pytest path/to/test_file.py -q`) ~5s max. Full fast tier (`aizee test` — all non-slow, no cov) is ~60-120s on Linux / ~180s on Windows.
+
+No `eval` in policy code.
+
+
+
+## Project Testing Protocol (ANY project under aiZee)
+
+Every project — Laravel, React, Python, Go, Node — follows two-tier testing `[TEST-07]`:
+
+- **FAST tier** (during iteration): run ONLY targeted tests for the code you touched. ~5s max. See `workflows/testing-tiers.md` for per-stack commands.
+
+- **FULL tier** (before declaring done): run the project's complete test suite + coverage. Must pass green.
+
+- **FULL tier maxes machine resources** `[TEST-11]` — every project, old or new: use the stack's parallel runner at `cpu_count - 2` workers (leave the OS breathing room, never 100%). pytest-xdist, `vitest --maxWorkers`, `artisan test --parallel`, `go test -parallel`. GPU only if the suite runs real GPU-bound code (verify `nvidia-smi` util; mocked-model suites get zero gain — measured 151s CUDA vs 127s CPU on aiZee). Per-stack commands: `workflows/testing-tiers.md`.
+
+- Never run the full suite on every change. Never skip the full suite before done.
+
+- If the project has no test framework, write the first test for the touched code before declaring done `[TEST-09]`.
+
+
+
+## Non-negotiable user policy
+
+- No full test suites during iteration — use FAST tier (targeted `--filter=...` / `<file>` only).
+
+- FULL test suite is mandatory before declaring done — no exceptions.
+
+- No `git add .` / `git add -A` (`[GIT-06]`). No `git commit`, `git push`, destructive git, or unauthorized server actions without explicit user approval.
+
+- Delete temporary/scratch/test files immediately after use.
+
+
+
+## Shell Compatibility `[SHELL-01]`
+
+- Detect the active shell before running commands. On Windows the default shell is **PowerShell** — never use bash syntax (`&&`, `||`, `2>nul`, `ls`, `cat`, `grep`).
+
+- PowerShell equivalents: `;` instead of `&&`, `if ($?) { ... }` instead of `||`, `Test-Path` instead of `ls ... 2>nul`, `Get-ChildItem` instead of `ls`, `Get-Content` instead of `cat`, `Select-String` instead of `grep`.
+
+- In workflow CMD steps, use `pwsh:` or `ps:` prefix for PowerShell commands on Windows; `bash:` for POSIX shells on Linux/macOS.
+
+- When using `subprocess` in Python, pass command lists (not shell strings) to stay cross-platform. Use `shell=True` only when absolutely necessary and never with user input.
+
+
+
+---
+
+
+
+## Architecture
+
+
+
+aiZee follows a layered design:
+
+
+
+- **CLI / Entry Point** — `aizee_cli.py` parses commands, delegates to kernel.
+
+- **Kernel (Facade)** — `runtime/kernel.py` routes to managers.
+
+- **Managers** — `runtime/managers/` (PolicyManager, WorkflowManager, AgentManager, ChatManager).
+
+- **Runtime Modules** — 139 governance modules in `runtime/`.
+
+- **MCP Server** — `aizee_mcp/` exposes 46 tools via FastMCP (marketing tool modules gated via `disabledToolModules`).
+
+- **Memory** — `memory/` SQLite + FTS5 + vector store.
+
+- **Skills / Workflows / Tech-Stack** — declarative `.md` files loaded at runtime.
+
+
+
+### Core Infrastructure
+
+
+
+| Module | Purpose |
+
+|--------|---------|
+
+| `runtime/kernel.py` | Facade delegating to managers |
+
+| `runtime/policy.py` | Policy evaluation engine |
+
+| `runtime/budget.py` | Token/cost/call budget tracking |
+
+| `runtime/audit.py` | Append-only audit log |
+
+| `runtime/guardian.py` | Pre-action guardian gate |
+
+| `runtime/probity.py` | Integrity verification |
+
+| `runtime/persona.py` | Auto persona detection |
+
+| `runtime/spec_engine.py` | Spec-driven development (4 phases) |
+
+| `runtime/storage_backend.py` | Pluggable storage abstraction (memory/json/sqlite) |
+
+| `runtime/service_catalog.py` | Multi-index skill/workflow catalog |
+
+| `runtime/schemas.py` | Pydantic schemas + AizeeException hierarchy + PaginatedResult |
+
+
+
+### Package Layout
+
+
+
+```
+
+aizee/                         # Sovereign root (AIZEE_ROOT)
+├── aizee_cli.py               # CLI entry point
+├── config.py                  # Root discovery + version
+├── runtime/                   # Kernel + 139 governance modules
+│   ├── kernel.py              # Facade
+│   ├── managers/              # Policy/Workflow/Agent/Chat managers
+│   ├── storage_backend.py     # StorageBackend protocol + factory
+│   ├── service_catalog.py     # ServiceDescriptor + multi-index catalog
+│   ├── schemas.py             # Pydantic + exceptions + pagination
+│   └── ...                    # 139 governance modules
+├── aizee_mcp/                 # MCP server (46 tools enabled)
+├── memory/                    # SQLite + FTS5 + vector
+├── skills/                    # 245 persona + lord skills
+├── workflows/                 # 66 trigger-based execution protocols
+├── rules/                     # Compressed behavioral rules
+├── tech-stack/                # 271 version-locked stack references
+│   └── spec-driven-templates/ # SDD templates (spec/plan/tasks/constitution/checklist)
+└── eval/                      # Agent benchmark harness
+
+```
+
+
+
+## First Principles
+
+
+
+When making changes, follow these priorities:
+
+
+
+1. Preserve policy-governed behavior (never bypass kernel gates)
+
+2. Match existing aiZee patterns (read neighboring code first)
+
+3. Reuse existing modules (don't reinvent storage/catalog/exceptions)
+
+4. Prefer correctness over convenience
+
+5. Keep changes narrow and testable
+
+
+
+## Adding a New Runtime Module
+
+
+
+1. Create `runtime/<module>.py`
+
+2. Add to `runtime/__init__.py` if it needs exports
+
+3. Wire through `kernel.py` or the relevant manager
+
+4. Add tests in `tests/test_<module>.py`
+
+5. Update `Memory.md` if user-facing
+
+6. Run quality gates: `ruff check .` + `mypy` + `pytest tests/test_<module>.py`
+
+
+
+## Adding a New Skill
+
+
+
+1. Create `skills/<name>/SKILL.md` (or `skills/<name>.md` for flat)
+
+2. Add frontmatter with triggers, personas, tech_stack
+
+3. Register in `PERSONA_SKILLS` mapping in `runtime/persona.py` if persona-linked
+
+4. Test with `aizee persona detect --multi "<task description>"`
+
+5. Run `aizee memory ingest` to refresh indexes
+
+
+
+## Adding a New Workflow
+
+
+
+1. Create `workflows/<NN>-<name>.md` (sequential numbering)
+
+2. Add trigger keywords in the header
+
+3. If it uses a runtime engine, document the engine module
+
+4. Update `workflows/README.md` count
+
+
+
+## Error Handling
+
+
+
+- Raise `AizeeError` subclasses from `runtime/schemas.py`
+
+- Use `PolicyDeniedError` for policy gate failures
+
+- Use `BudgetExceededError` for budget limit hits
+
+- Use `ValidationError` for input validation
+
+- Use `StorageError` for storage backend failures
+
+- All exceptions carry `error_code`, `severity`, and `context` dict
+
+- Never use bare `Exception` — always an `AizeeError` subclass
+
+
+
+## Storage Rules
+
+
+
+- Use `StorageFactory` from `runtime/storage_backend.py` for new key-value stores
+
+- Do not instantiate `InMemoryStorage` / `JsonFileStorage` / `SqliteStorage` directly
+
+- Existing `MemoryStore` (SQLite) is unchanged — new code opts into the abstraction
+
+- Backends are cached by path — repeat `create()` returns the same instance
+
+- Call `factory.shutdown_all()` on process exit to flush + close
+
+
+
+## Common Mistakes
+
+
+
+- Bypassing `StorageFactory` and instantiating storage directly
+
+- Using bare `Exception` instead of `AizeeException` subclasses
+
+- Hardcoding paths instead of using `config.discover_root()`
+
+- Assuming framework versions without reading lockfiles (`[VER-01]`)
+
+- Running full test suite during iteration (use FAST tier)
+
+- `git add .` / `git add -A` (`[GIT-06]`)
+
+- Forgetting to update `Memory.md` after milestones
+
+- Writing implementation code without Context7 MCP query first
+
+
+
+## Human Handoff
+
+
+
+If behavior is unclear:
+
+
+
+1. Prefer aiZee spec (`spec.md`) and existing code behavior
+
+2. Then `Memory.md` for historical context
+
+3. Then `global-roles.md` / `global-workflow.md` for governance rules
+
+4. If a task requires broad architectural changes, stop and surface tradeoffs
+
+
+
+## Code Style
+
+
+
+- Use `from __future__ import annotations` in all Python files
+
+- Strict typing — no `Any` without justification, no `mixed`/`unknown` abuse
+
+- Class <300 lines, method <30 lines (`[CODE-03]`)
+
+- Enums/constants over magic strings (`[CODE-04]`)
+
+- SOLID & DRY (`[CODE-05]`)
+
+- Constructor injection (pass dependencies in `__init__`)
+
+- Self-explanatory code over comments
+
+- Always use braces in conditionals (for JS/TS projects)
+
+- Never leave a `catch`/`except` block empty — log with context
+
+- Follow existing project patterns
+
+
+
+## Logging
+
+
+
+- Use structured logging (dict-based, not f-strings in hot paths)
+
+- Avoid noisy logs in performance-critical paths
+
+- Log error context: error_code, severity, operation, user (if relevant)
+
+
+
+## Pull Request Guidelines
+
+
+
+- Keep changes focused — avoid unrelated refactors
+
+- Preserve behavior unless the task explicitly requires change
+
+- Update docs (`Memory.md`, `CHANGELOG.md`) when user-facing
+
+- Conventional commits: `feat:`, `fix:`, `perf:`, `docs:`, `chore:`, `refactor:`
+
+- Stage only files YOU modified (`git add <file>`, never `git add .`)
+
+- No `git commit` / `git push` without explicit user approval
+
+## Worker-Agent Contract
+
+Adopted from cua's AGENTS.md — durable work lives in GitHub, not in local queues.
+
+- The issue/RFC carries the problem; the pull request carries the execution.
+  A reviewer must not need local scheduler/worktree state to understand the work.
+- When the account has write access, push the work branch to the canonical repo —
+  not a personal fork.
+- Keep progress in the linked PR description, not periodic status comments.
+- Route suspected vulnerabilities through SECURITY.md privately — never a public
+  issue, log, or screenshot.
+- `aizee work poll` lists open issues via the gh CLI; unassigned + `help wanted`
+  rank first (pull model).
+- Releases are per-version tags (`vX.Y.Z`) with GitHub release notes — there are
+  no component release streams.