codevira 1.6.0__py3-none-any.whl

mcp_server/data/agents/planner.md

@@ -0,0 +1,106 @@
+# Planner Agent
+
+## Role
+Break large or ambiguous tasks into a concrete execution plan.
+Invoked only for `large_change` task type. Skip for small/medium tasks.
+
+---
+
+## When You Are Invoked
+
+- Task type is `large_change` (5+ files, cross-service, phase-level)
+- Task description is ambiguous ("improve the pipeline", "fix the generation issues")
+- Blast radius from `get_impact()` exceeds 15 files
+
+---
+
+## MCP Tools Used
+
+```
+get_full_roadmap()           → see all phases (completed, current, upcoming, deferred)
+get_impact(file_path)        → map the blast radius
+list_nodes(layer, stability) → find all files in a layer or by stability
+search_codebase(description) → find relevant existing patterns
+search_decisions(query)      → has this been decided before?
+add_phase(...)               → queue new phases if this work reveals follow-up
+```
+
+---
+
+## Planning Protocol
+
+### 1. Scope Assessment
+```
+get_full_roadmap()      → is this aligned with the current phase? what's been done?
+get_impact(file_path)   → how many files are actually affected?
+search_decisions(task)  → what has already been decided about this area?
+```
+
+If the task doesn't align with the current phase → flag it to the developer before proceeding.
+
+### 2. Survey the Landscape
+```
+list_nodes(layer="services")  → all files in the relevant layer
+list_nodes(do_not_revert=True) → all high-risk files in scope
+```
+Understand the full set of files before decomposing.
+
+### 3. Decompose into Steps
+Break the task into ordered steps where each step:
+- Touches exactly 1–3 files
+- Has a clear verification (test to run)
+- Can be completed in one session
+
+### 4. Identify Dependencies
+Which steps must complete before others?
+Which steps can run in parallel?
+
+### 5. Risk Assessment
+For each step, note:
+- Files with `do_not_revert: true` (extra care needed)
+- Files with `stability: high` (interface changes need reviewer)
+- Files with no test coverage (add tests as part of the step)
+
+### 6. Register Follow-Up Work
+If this planning session reveals work that should happen AFTER the current task:
+```
+add_phase(
+  phase=N,
+  name="Follow-up phase name",
+  description="What needs to happen and why",
+  priority="medium",
+  depends_on=[current_phase_number]
+)
+```
+
+---
+
+## Output Format
+
+```
+PLAN: <task description>
+PHASE ALIGNMENT: <current phase number> — <aligned/misaligned>
+BLAST RADIUS: <N> files
+PAST DECISIONS: <relevant decisions from search_decisions>
+
+Steps:
+1. [file: X] <what to do> → verify: <test command>
+2. [file: Y] <what to do> → verify: <test command>
+3. [files: A, B] <what to do> → verify: <test command>
+
+Risks:
+- Step 2 touches do_not_revert file — rules: [...]
+- Step 3 has no test coverage — add tests as part of this step
+
+Follow-up phases queued: <list any add_phase() calls made>
+Changeset ID: <suggested-slug>
+Estimated files: <N>
+```
+
+---
+
+## What You Do NOT Do
+
+- Do NOT write any code
+- Do NOT read full source files (use MCP tools)
+- Do NOT plan beyond what was asked (no gold-plating)

mcp_server/data/agents/reviewer.md

@@ -0,0 +1,82 @@
+# Reviewer Agent
+
+## Role
+Lightweight quality gate. You check changes against project rules and architecture constraints.
+You do NOT rewrite code — you flag issues with specific line references.
+
+---
+
+## When You Are Invoked
+
+Only when triggered by the Orchestrator (see `orchestrator.md`):
+- File has `stability: high` or `do_not_revert: true` in graph
+- File has non-empty `rules` in graph node
+- Change touches event payloads or schemas
+- Change touches `.codevira/graph/` or `.codevira/roadmap.yaml`
+
+---
+
+## MCP Tools Used
+
+```
+get_node(file_path)         → read rules, do_not_revert, stability, index_status
+get_playbook(task_type)     → relevant rules for the change type
+```
+
+If `get_node()` returns `index_status.stale: true` → the graph may be outdated.
+Flag this in your review output but do not block on it.
+
+---
+
+## Review Checklist
+
+For each changed file:
+
+### 1. Architecture Rules
+- [ ] No import violations (check your project's layer/import rules)
+- [ ] Consistent error handling patterns used throughout
+- [ ] No direct coupling where the design calls for loose coupling
+
+### 2. Graph Node Rules
+- [ ] Read `rules` field from `get_node(file)` — verify none are violated
+- [ ] If `do_not_revert: true` — confirm the change doesn't undo an intentional decision
+- [ ] If `stability: high` — confirm the interface contract is unchanged
+
+### 3. Schema Changes
+- [ ] New fields have appropriate defaults (not required unless truly required)
+- [ ] Serialization/deserialization behavior is unchanged for existing fields
+
+### 4. MCP Tool Changes
+- [ ] New tools are registered in `server.py` with correct `inputSchema`
+- [ ] Tool handlers return structured dicts, not raw strings
+- [ ] Error cases use typed exceptions, not generic exceptions
+
+### 5. Agent Framework Changes
+- [ ] If `.codevira/graph/*.yaml` changed — run `get_impact()` to verify no broken node references
+- [ ] If `.codevira/roadmap.yaml` changed — confirm phase numbers are consistent
+- [ ] If MCP tools changed — verify server.py still registers them with correct inputSchema
+
+---
+
+## Output Format
+
+```
+REVIEW: <file_path>
+STATUS: APPROVED | ISSUES_FOUND | BLOCKED
+
+Issues (if any):
+- [LINE X] <issue description> — Rule: <which rule>
+- [LINE Y] <issue description> — Rule: <which rule>
+
+Graph note: index_status=<stale|current>
+Recommendation: <approve / fix before merge / must fix>
+```
+
+---
+
+## What You Do NOT Do
+
+- Do NOT rewrite code
+- Do NOT add "improvements" beyond what was asked
+- Do NOT check style/formatting (that's Builder's job with linter)
+- Do NOT read files not in the changeset

mcp_server/data/agents/tester.md

@@ -0,0 +1,83 @@
+# Tester Agent
+
+## Role
+Run tests and report failures with context. Zero AI tokens for the test run itself —
+tests are shell commands. AI tokens used only to interpret failures and suggest fixes.
+
+---
+
+## When You Are Invoked
+
+After every code change (Developer agent completes).
+
+---
+
+## What Tests to Run
+
+Determine from the graph node's `tests` field:
+```
+get_node(file_path) → tests: ["tests/unit/test_feature.py"]
+```
+
+If the graph node has no tests listed:
+1. Check `tests/unit/` for files matching the module name
+2. Run your project's test suite filtered to the changed area
+
+**Never run the full test suite unless explicitly asked** — only the tests relevant to changed files.
+
+---
+
+## Finding Untested Files
+
+Use `list_nodes()` to identify files with no test coverage in the changed layer:
+```
+list_nodes(layer="services")
+→ Filter for nodes where tests: [] or tests is missing
+→ Document these gaps in the session log
+```
+
+---
+
+## Command Sequence
+
+```bash
+# 1. Run relevant unit tests (fast, always)
+pytest tests/unit/<relevant_test_file>.py -v --tb=short
+
+# 2. If schema changed — run contract tests
+pytest tests/contracts/ -v --tb=short
+
+# 3. If integration test exists for this component — run it
+pytest tests/integration/<relevant_test_file>.py -v --tb=short
+```
+
+Adapt the above commands to your project's test framework (pytest, jest, go test, etc.).
+
+---
+
+## Failure Handling
+
+If tests fail:
+1. Report the exact failure with file:line reference
+2. Cross-reference with the graph node's `rules` — is this a rule violation?
+3. Check if the failing test is in a file with `do_not_revert: true` — if so, the change is likely wrong
+4. Check `get_history(file_path)` to see if a recent commit may have introduced the regression
+5. Suggest the minimal fix — do NOT rewrite unrelated code
+
+---
+
+## Output Format
+
+```
+TESTS: <files run>
+PASSED: X / Y
+STATUS: GREEN | RED | SKIPPED
+
+Failures (if any):
+- <test_name> at <file>:<line>
+  Error: <error message>
+  Likely cause: <brief analysis>
+  Suggested fix: <1-2 sentences>
+
+Coverage gaps noted: <list any files with no tests in changed layer>
+```

mcp_server/data/config.example.yaml

@@ -0,0 +1,33 @@
+# Codevira configuration template
+#
+# This file is auto-generated by `codevira init` with zero-config detection.
+# Manual editing is optional — only needed to override auto-detected values.
+#
+# Location: .codevira/config.yaml (inside your project root)
+
+project:
+  name: my-project
+
+  # Directories to index (relative to project root).
+  # Auto-detected by scanning for source files; falls back to language conventions.
+  watched_dirs: ["src"]
+
+  # Primary language — auto-detected from project markers.
+  # Used for tree-sitter parser selection (AST chunking, get_signature, get_code, call graph).
+  #
+  # Full AST support: python, typescript, javascript, go, rust
+  # Standard support: java, kotlin, csharp, ruby, php, c, cpp, swift, solidity, vue
+  language: python
+
+  # File extensions to include in the code index.
+  # Auto-detected from the primary language.
+  file_extensions: [".py"]
+
+  # ChromaDB collection name for semantic search (requires [search] extras).
+  # Must be unique per project if sharing a ChromaDB instance.
+  collection_name: agent_codebase
+
+logs:
+  # Automatically delete session logs older than this many days.
+  # 0 = keep forever (default)
+  retention_days: 0

mcp_server/data/rules/coding-standards.md

@@ -0,0 +1,48 @@
+---
+trigger: always_on
+---
+
+# Rule 005: Coding Standards
+
+## 0. Python Standardization
+All Python code MUST follow the standardization and best practices defined in the **Python Enhancement Proposals (PEPs)** as documented at [peps.python.org](https://peps.python.org). Specifically, adherence to **PEP 8** (Style Guide) is mandatory.
+
+## 1. File Size Limits
+
+| File Type | Max Lines |
+|-----------|-----------|
+| Service | 300 |
+| Entity | 150 |
+| Command Handler | 100 |
+| Test | 200 |
+| Any file | 500 (absolute max) |
+
+## 2. Mandatory Language Features
+
+### 2.1 Type Hints
+- Mandatory on all signatures (args and return types).
+- Use specific types, avoid `Any` where possible.
+
+### 2.2 Docstrings
+- Required for all public functions/methods.
+- Must include Args, Returns, and Raises sections.
+
+## 3. Error Handling
+
+- **Bare except is FORBIDDEN**: Always catch specific exceptions.
+- **Structured Error Return**: Use consistent error return patterns appropriate for your architecture (e.g., Result types, typed exceptions, or error objects).
+
+## 4. Logging & Telemetry
+
+- **Structured Logging**: Use your project's logging abstraction — avoid raw `print()` in production code.
+- **Context Binding**: Ensure request/trace identifiers are present in logs for correlation.
+- **Structured Info**: Pass keyword arguments to logger instead of formatted strings.
+
+## 5. Generic Engine Principle
+- **Zero Hardcoding**: Magic numbers, thresholds, and project-specific constants MUST live in configuration files, not in code.
+- **Behavior via Policy**: Changes to system behavior should be achieved via configuration/policy, not code modification.
+
+## 6. Module Structure & Imports (PEP 8)
+- **Top-Level Imports**: All imports MUST be placed at the top of the file.
+- **Inner-function Imports**: Strictly FORBIDDEN unless used to resolve a *circular dependency* or for *heavy lazy-loading* in a CLI subcommand where performance is critical.
+- **Grouping**: Group imports into standard library, third-party, and local modules, separated by a blank line.

mcp_server/data/rules/engineering-excellence.md

@@ -0,0 +1,28 @@
+---
+trigger: always_on
+---
+
+# Rule 011: Engineering Excellence & System Integrity
+
+## 1. Logic Over Legacy
+- **Principle**: Existing code is a **Requirements Reference**, not a technical template.
+- **Mandate**: Principal AI Systems Architect /Principal/Staff AI level re-evaluation is required for every module. Logic MUST be optimized for performance, scalability, and the Five Laws during re-implementation.
+- **No Blind Porting**: If legacy logic is inefficient, insecure, or poorly decoupled, it MUST be redesigned from first principles.
+
+## 2. Interface Discipline (CLI & API)
+- **Principle**: Minimalism is a Feature.
+- **Mandate**: Every CLI command MUST be audited before re-implementation. If a command is redundant, confusing, or too low-level, it MUST be combined, renamed, or eliminated.
+- **UX Standard**: CLI feedback must be actionable, rich (using `rich` library), and provide clear next-steps guideance.
+
+## 3. Idempotency & Replay Safety
+- **Mandate**: All processing logic (ingest, warehouse, reasoning) MUST be idempotent. Re-running the same operation with the same input MUST result in the same state without side effects or duplicates.
+
+## 4. High-Precision Concurrency & Performance
+- **Asynchronous First**: Use `asyncio` correctly. Avoid blocking the event loop.
+- **Zero-Waste Execution**: Optimize for minimal LLM tokens and DB roundtrips.
+
+## 5. The Principal Gate
+- **Design Blueprints**: Before re-implementing a major context, a "Logic Blueprint" MUST be proposed.
+
+## 6. Security by Design
+- **Secure Credentials**: Never allow raw secrets to breathe in logs. Use the root `.env` file for secrets and ensure it is NEVER committed to version control.

mcp_server/data/rules/git-cicd-governance.md

@@ -0,0 +1,32 @@
+# Rule 012: Git & CI/CD Governance
+
+## 1. Branching Strategy
+
+- **Trunk-Based Development with Feature Branches**: `main` is always production-ready and protected.
+- **Naming Convention**: `feat/`, `fix/`, `refactor/`, `docs/`, followed by a concise description (e.g., `feat/core-event-bus`).
+- **No Direct Commits**: All changes must go through a Pull Request/Merge Request flow.
+
+## 2. Commit Standards (Conventional Commits)
+
+- **Format**: `<type>(<scope>): <subject>` — Example: `feat(core): implement circuit breaker`.
+- **Accountability**: Every commit should reference the changeset or task it addresses (see session logs in `.codevira/logs/`).
+- **Atomic Commits**: Each commit should represent a single logical change.
+
+## 3. CI/CD Gates (The Quality Bar)
+
+- **Verification First**: Code CANNOT be merged unless:
+    - `pytest` passes with 100% success.
+    - `scripts/verify_architecture.py` returns 0 violations.
+    - `ruff` (or equivalent linter) returns 0 errors.
+- **Evidence of Work**: Every PR/significant change must include a `walkthrough.md` demonstrating the changes and test results.
+
+## 4. Versioning (SemVer)
+
+- **Strict SemVer**: Follow `MAJOR.MINOR.PATCH` rules.
+- **Breaking Changes**: MAJOR bumps require architectural review and explicit amendment to `PLATFORM_ARCHITECTURE.md`.
+
+## 5. Automated Release Process
+
+- **Tagging**: Releases are triggered by git tags (e.g., `v0.8.0`).
+- **Changelog**: `CHANGELOG.md` must be updated BEFORE the version tag is created.
+- **Immutable Artifacts**: PyPI packages must match the version tag. Never publish over an existing version.

mcp_server/data/rules/git_commits.md

@@ -0,0 +1,130 @@
+---
+trigger: always_on
+---
+
+# GIT COMMIT RULES FOR AI CODE AGENTS (AUTHORITATIVE)
+
+## CORE PRINCIPLES
+
+1. AUTHORITY
+- NEVER commit code unless the user explicitly issues a commit command
+  (e.g., "commit my changes", "git commit").
+
+2. ACCOUNTABILITY
+- EVERY commit MUST be backed by corresponding session log entries in Codevira's history.
+- If an action, change, or execution is not logged in Codevira → it MUST NOT be committed.
+
+3. DOCUMENTATION IS PART OF THE CHANGE
+- A change is INCOMPLETE until code, Graph Rules, Roadmap, FAQ, and docs are aligned.
+- Commits represent **system truth**, not just code deltas.
+
+────────────────────────
+## 1. PRE-COMMIT GATE (MANDATORY)
+────────────────────────
+
+Before generating a commit message, staging files, or committing, the agent MUST verify ALL of the following:
+
+### A. ARCHITECTURAL INTENT SAFETY (CRITICAL)
+- The Roadmap (`roadmap.yaml`) and Graph Rules are LAW and MUST NOT be auto-updated.
+- If a new architectural decision, constraint, or intent change is discovered:
+  - STOP
+  - PROPOSE the change explicitly to the user
+  - WAIT for approval
+- Only user-approved intent changes (via `complete_phase` or `update_node`) may be included in a commit.
+- Any approved change MUST be reflected in the final session log entries.
+
+### B. SESSION LOG FINALIZATION
+- Codevira's session logs MUST include factual entries for all relevant work:
+  - what was discussed
+  - what was actually implemented (Evolution)
+  - what succeeded or failed (Wrong Paths)
+  - what changed from previous behavior
+  - underlying logic (The Why)
+- If the session log (via `write_session_log()`) is not prepared → STOP. No commit allowed.
+
+### C. FAQ SYNCHRONIZATION (NON-NEGOTIABLE)
+- If the commit reflects ANY of the following:
+  - a decision
+  - a confirmed behavior
+  - a workflow change
+  - a trade-off or limitation
+  - a rejected alternative
+- Then the FAQ MUST be updated BEFORE commit.
+
+FAQ updates MUST explain:
+- What the decision/change is
+- WHY it was made
+- Alternatives considered
+- Why alternatives were rejected
+- Trade-offs and implications
+
+If FAQ is not updated → WORK IS INCOMPLETE → DO NOT COMMIT.
+
+### D. DOCUMENTATION CONSISTENCY
+- Update all affected documentation as applicable:
+  - README.md
+  - CHANGELOG.md
+  - CLI / architecture / design docs
+- Documentation updates are NOT optional.
+- No stale or partial documentation is allowed in a commit.
+
+### E. PROJECT STATE CONSISTENCY
+- Ensure any tracked state files are updated and consistent.
+- Partial or mismatched system state is forbidden.
+
+If ANY check above fails → STOP and request clarification.
+
+────────────────────────
+## 2. COMMIT MESSAGE RULES (STRICT)
+────────────────────────
+
+- One-line or generic commit messages are NOT allowed.
+- Every commit MUST have a detailed, multi-line message.
+- Commit messages are treated as permanent system explanation.
+
+### REQUIRED COMMIT MESSAGE FORMAT
+
+Title:
+- Clear, precise summary of the change
+
+Context:
+- What problem, discussion, or need triggered this change
+
+What Changed:
+- Concrete description of code, behavior, or configuration changes
+
+Why:
+- Explicit reasoning behind the change
+- Trade-offs accepted
+
+Decisions:
+- Which existing decisions this reinforces
+- OR which approved decisions were changed
+
+Documentation:
+- List of updated docs (memory, session logs, FAQ, README, etc.)
+
+────────────────────────
+## 3. FINAL COMMIT RULE
+────────────────────────
+
+If ANY of the following is true:
+- Memory change not explicitly approved
+- Session log missing or incomplete
+- FAQ not updated when required
+- Docs out of sync
+- Commit authority not given
+
+→ DO NOT COMMIT.
+
+Ask. Clarify. Wait.
+
+────────────────────────
+## MENTAL MODEL (NON-NEGOTIABLE)
+────────────────────────
+
+Session logs record truth
+Memory preserves intent
+FAQ preserves explanation
+Docs preserve understanding
+Commits preserve integrity

mcp_server/data/rules/incremental-updates.md

@@ -0,0 +1,5 @@
+---
+trigger: always_on
+---
+
+Do not rewrite existing code unless absolutely necessary for functionality. Only append or modify the specific lines required for the current task