ref-agents 1.0.0__py3-none-any.whl

ref_agents/session.py

@@ -0,0 +1,100 @@
+from pathlib import Path
+from threading import RLock
+from typing import Optional
+
+
+class SessionState:
+    """Holds the state for a single session."""
+
+    def __init__(self) -> None:
+        self.active_agent: Optional[str] = None
+        self.project_root: Optional[Path] = None
+        self.active_story: Optional[str] = None
+        self._migration_mode: bool = False
+        # Validator-foundation state (STORY-021)
+        self.validator_retry_counts: dict[tuple[str, str, str], int] = {}
+        self.halt_flags: set[str] = set()
+        self._story_locks: dict[str, RLock] = {}
+
+
+class SessionManager:
+    """Manages session state.
+    Currently implements a Singleton pattern for local single-user context,
+    but designed to be extensible for multi-session handling.
+    """
+
+    _instance = None
+    _state = SessionState()
+
+    @classmethod
+    def get(cls) -> "SessionManager":
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @property
+    def active_agent(self) -> Optional[str]:
+        return self._state.active_agent
+
+    @active_agent.setter
+    def active_agent(self, agent: str) -> None:
+        self._state.active_agent = agent
+
+    @property
+    def project_root(self) -> Optional[Path]:
+        return self._state.project_root
+
+    @project_root.setter
+    def project_root(self, path: Path) -> None:
+        self._state.project_root = path
+
+    @property
+    def active_story(self) -> Optional[str]:
+        return self._state.active_story
+
+    @active_story.setter
+    def active_story(self, story_id: Optional[str]) -> None:
+        self._state.active_story = story_id
+
+    def is_migration_mode(self) -> bool:
+        """Return True if current session has migration mode active."""
+        return self._state._migration_mode
+
+    def set_migration_mode(self, value: bool) -> None:
+        """Activate or deactivate migration mode for this session."""
+        self._state._migration_mode = value
+
+    def clear(self) -> None:
+        """Reset session state."""
+        self._state = SessionState()
+
+    # --- Validator-foundation accessors (STORY-021) ---
+
+    def get_retry_count(self, story_id: str, phase: str, artifact_hash: str) -> int:
+        return self._state.validator_retry_counts.get(
+            (story_id, phase, artifact_hash), 0
+        )
+
+    def increment_retry_count(
+        self, story_id: str, phase: str, artifact_hash: str
+    ) -> int:
+        key = (story_id, phase, artifact_hash)
+        new_value = self._state.validator_retry_counts.get(key, 0) + 1
+        self._state.validator_retry_counts[key] = new_value
+        return new_value
+
+    def set_halt(self, story_id: str) -> None:
+        self._state.halt_flags.add(story_id)
+
+    def clear_halt(self, story_id: str) -> None:
+        self._state.halt_flags.discard(story_id)
+
+    def is_halted(self, story_id: str) -> bool:
+        return story_id in self._state.halt_flags
+
+    def story_lock(self, story_id: str) -> RLock:
+        lock = self._state._story_locks.get(story_id)
+        if lock is None:
+            lock = RLock()
+            self._state._story_locks[story_id] = lock
+        return lock

ref_agents/tool_names.py

@@ -0,0 +1,55 @@
+"""Namespaced tool call strings for agent-facing output.
+
+Use these constants in tool output and rules so model instructions stay correct
+after namespace consolidation. Avoids hardcoded flat tool names that break when
+tools are renamed to log(event=...), scan(target=...), etc.
+"""
+
+# Log events (use in instructions / remediation strings)
+TOOL_LOG_ESCALATION = 'log(event="escalation", level=..., reason=..., to_agents=...)'
+TOOL_LOG_OWNERSHIP = 'log(event="ownership", to_owner=..., reason=...)'
+TOOL_LOG_REPLAN = 'log(event="replan", trigger=..., impact=...)'
+TOOL_LOG_DEBT = 'log(event="debt", debt_type=..., severity=..., location=...)'
+TOOL_LOG_PHASE = 'log(event="phase", phase=..., outcome=..., next_phase=...)'
+TOOL_LOG_ARTIFACT = 'log(event="artifact", story_id=..., artifact=...)'
+
+# Scan targets (directory/files/file_path as needed)
+TOOL_SCAN_HEALTH = 'scan(target="health", directory="{directory}")'
+TOOL_SCAN_DEBT = 'scan(target="debt", directory="{directory}", summary=...)'
+TOOL_SCAN_DEAD_CODE = 'scan(target="dead_code", directory="{directory}", summary=...)'
+TOOL_SCAN_COMPLEXITY = 'scan(target="complexity", files=...)'
+TOOL_SCAN_EXTERNAL = 'scan(target="external", directory="{directory}")'
+TOOL_SCAN_REGRESSION = 'scan(target="regression", files=...)'
+TOOL_SCAN_COMPLIANCE = 'scan(target="compliance", file_path=...)'
+TOOL_SCAN_DOCS = 'scan(target="docs", directory="{directory}")'
+TOOL_SCAN_AI_PATTERNS = 'scan(target="ai_patterns", file_path=...)'
+TOOL_SCAN_SECURITY = 'scan(target="security", directory="{directory}")'
+# code_quality is internal to health scan — use TOOL_SCAN_HEALTH as entry point
+
+# Workflow (use in tool output / rules)
+TOOL_WORKFLOW_INIT = (
+    'workflow(action="init", story_id=..., epic_id=..., requirements_path=...)'
+)
+TOOL_WORKFLOW_LIST = 'workflow(action="list")'
+TOOL_WORKFLOW_PARALLEL_START = (
+    'workflow(action="parallel_start", story_id="{story_id}")'
+)
+TOOL_AGENT_ACTIVATE = 'agent(action="activate", name="{name}")'
+TOOL_CONTEXT_GRAPH_EMPTY_HINT = 'scan(target="health", directory=...)'
+
+# Compliance Remediation
+TOOL_REMEDIATE_START = (
+    'remediate(action="start", story_id=..., directory=..., scan_output=...)'
+)
+TOOL_REMEDIATE_STATE = 'remediate(action="state", session_id=...)'
+TOOL_REMEDIATE_EXECUTE = 'remediate(action="execute", session_id=..., tier="tier1")'
+TOOL_REMEDIATE_APPROVE = 'remediate(action="approve", session_id=...)'
+TOOL_REMEDIATE_DEFER = (
+    'remediate(action="defer", session_id=..., violation_id=..., reason=...)'
+)
+TOOL_REMEDIATE_UPDATE = 'remediate(action="update", session_id=..., violation_ids=[...], status="auto_fixed")'
+TOOL_REMEDIATE_COMPLETE = 'remediate(action="complete", session_id=...)'
+
+# Validators (FEAT-003 onwards)
+TOOL_VALIDATE = 'validate(role="{role}", artifact_id="{artifact_id}")'
+VALIDATE = "validate"

ref_agents/tools/__init__.py

@@ -0,0 +1,8 @@
+"""REF Agents Tools.
+
+This package contains tools for the REF Agents server.
+"""
+
+from ref_agents.tools import browser, codemap, compliance, report_utils
+
+__all__ = ["browser", "codemap", "compliance", "report_utils"]

ref_agents/tools/agents_generator.py

@@ -0,0 +1,315 @@
+"""REF Agents Generator.
+
+Generates AGENTS.md with REF protocol and mandatory fix workflow.
+
+Usage:
+    from ref_agents.tools.agents_generator import generate_agents_file
+    result = generate_agents_file("/path/to/project")
+"""
+
+from pathlib import Path
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+AGENTS_MD_CONTENT = """# AI Coding Assistant Protocol — REF v3.2
+
+> This file is read by Cursor, Windsurf, Antigravity, and GitHub Copilot at session start.
+> It is the always-on context layer. Rules here are non-negotiable and apply to every task.
+
+---
+
+## ⚠️ NEW STORY ENTRY POINT (MANDATORY — NO EXCEPTIONS)
+
+**For ANY new story, requirement, or feature request:**
+
+```
+ALWAYS start with: agent(action="activate", name="scrum_master")
+```
+
+The Scrum Master is the **mandatory intake gate**. It:
+1. Validates the story file exists and meets Definition of Ready
+2. Calls `workflow(action="init", story_id="...")` to initialize the phase state machine
+3. Hands off to `product_manager`
+
+**DO NOT** activate `product_manager`, `developer`, or any other agent directly for a new story.
+**DO NOT** call `workflow(action="init")` yourself — only `scrum_master` does this.
+
+If no story file exists, `scrum_master` activates `product_manager` in **BA mode** to elicit and write the story first.
+
+---
+
+## Non-Negotiable: REF-Agents Entry Point
+
+If `ref-agents` MCP is enabled and available, **ALL tasks run via a REF agent**.
+Direct code edits that bypass agent roles are prohibited.
+
+**Before any task:**
+1. Call `agent(action="list")` to confirm MCP is active.
+2. For new stories: `agent(action="activate", name="scrum_master")` (see above).
+3. For other tasks: `agent(action="activate", name="<role>")` matching the task type.
+
+If MCP is unavailable, apply the rules in this file manually and note the deviation.
+
+---
+
+## Context Entry Point (Non-Negotiable)
+
+`CODE_MAP.md` is the mandatory first read before any code task.
+
+**Before writing, modifying, or reviewing any code:**
+1. Read `CODE_MAP.md` at project root (fallback: `docs/CODE_MAP.md`).
+2. If missing: activate `discovery` to generate it before proceeding.
+3. After any change that adds, removes, or renames a file/class/function: update `CODE_MAP.md` in the same task. This is not optional.
+
+Agents that skip this step produce context-free changes. PR Reviewer will REQUEST CHANGES if `CODE_MAP.md` is stale.
+
+---
+
+## Communication Protocol (Non-Negotiable)
+
+BE LACONIC. Every sentence ≤ 15 words. Active voice. Technical vocabulary only.
+
+| Rule | Target |
+|---|---|
+| Sentence length | 15–20 words max |
+| Prose style | Active voice. "Service scales." Not "Scaling is handled by." |
+| Forbidden phrases | "It is important to note", "In order to", "As discussed", "Here is the code" |
+| Output format | Tables and bullets over paragraphs. Code over explanation. |
+
+---
+
+## Core Engineering Principles (Universal)
+
+- **Simplicity First**: Make every change as simple as possible. Minimal code impact. No new abstractions unless strictly necessary.
+- **No Laziness**: Find root causes. No temporary patches. Every fix meets senior developer standards.
+- **Minimal Impact**: Touch only what is necessary. Do not expand scope without explicit user approval.
+
+---
+
+## Agent Registry
+
+### SDLC Agents — Standard Flow
+
+| Agent | Activate With | Primary Duty | Escalates To |
+|---|---|---|---|
+| `scrum_master` | `agent(action="activate", name="scrum_master")` | **Story bookend**: intake gate (validate story, init workflow, hand to PM) AND close (verify artifacts, update REQ.md, log handoffs, generate project_status.md) | User |
+| `discovery` | `agent(action="activate", name="discovery")` | Scan codebase, generate `codemap/`, `FEATURES.md`, `AGENTS.md` | User |
+| `product_manager` | `agent(action="activate", name="product_manager")` | **Dual-mode**: BA mode (no story file → elicit requirements, write STORY-XXX.md, return to SM) or PM mode (story exists → review + refine, hand to Specifier) | User |
+| `specifier` | `agent(action="activate", name="specifier")` | Write formal SPEC with FRs, data shapes, failure modes. Output: `docs/specs/SPEC-{story_id}.md`. Runs after PM, before Architect. | PM + User |
+| `architect` | `agent(action="activate", name="architect")` | System design, ADRs, regression risk check. Reads SPEC as primary input. Plan-first for 3+ component decisions. | PM + User |
+| `qa_lead` | `agent(action="activate", name="qa_lead")` | Validate SPEC FRs for testability against architecture. Runs after Architect. Parallel with `test_designer`. | PM + Architect |
+| `test_designer` | `agent(action="activate", name="test_designer")` | Design test strategy and conceptual cases from SPEC FRs. Parallel with `qa_lead`. | QA Lead + PM |
+| `impact_architect` | `agent(action="activate", name="impact_architect")` | **Pre-implementation gate**: calculate blast radius, score regression risk, enforce best practices, issue Go/No-Go. Runs after QA Gate, before Developer. Produces `docs/analysis/CHANGE-{story_id}.md`. | Architect + User |
+| `developer` | `agent(action="activate", name="developer")` | Implement per Elite Quality Protocol. Plan-first for 3+ step tasks. Log debt. Do not fix debt without approval. | Architect + PM |
+| `pr_reviewer` | `agent(action="activate", name="pr_reviewer")` | Compliance check: types, logging, exceptions, tests, debt logging. Apply Staff Engineer Gate before any verdict. | Developer + Architect |
+| `tester` | `agent(action="activate", name="tester")` | Write real-execution tests from AC. No mocking the unit under test. | PM + QA Lead |
+| `security_owner` | `agent(action="activate", name="security_owner")` | Vulnerability audit: input validation, auth/authz, secrets | Developer + User |
+
+### Utility Agents — On-Demand
+
+| Agent | Activate With | When to Use |
+|---|---|---|
+| `forensic_engineer` | `agent(action="activate", name="forensic_engineer")` | Any bug, incident, or unexpected behavior. Always before `developer` on fixes. Owns lessons learned: appends to `ref-reports/post-mortem-*.md` after every resolved incident or L2/L3 escalation. |
+| `strategist` | `agent(action="activate", name="strategist")` | Design decisions with multiple viable approaches. Trade-off analysis. Delegates independent analysis tracks in parallel via `workflow(action="parallel_start")` for complex multi-domain decisions. |
+| `platform_engineer` | `agent(action="activate", name="platform_engineer")` | Codebase health scans, CI/CD, DevEx issues. Delegates findings across agents in parallel via `workflow(action="parallel_start")` for multi-domain analysis. |
+
+---
+
+## Mandatory Fix Workflow
+
+**A fix is any change addressing a defect, regression, or unexpected behavior.**
+New features are NOT fixes.
+
+```
+1. forensic_engineer   →  Root cause analysis (RCA). Output: ref-reports/post-mortem-*.md
+2. impact_architect    →  Blast radius + regression risk gate. Output: docs/analysis/FIX-{timestamp}.md
+3. strategist          →  Solution design, trade-off analysis. Output: recommendation
+4. developer           →  Implementation + tests
+```
+
+Skipping `forensic_engineer` or `impact_architect` on a fix is blocked at PR review. No exceptions.
+
+---
+
+## SDLC Phase Sequence
+
+```
+Intake:    scrum_master    →  Validate story + init workflow
+Phase 0:   discovery       →  (brownfield only) Generate CODE_MAP.md
+Phase 1:   product_manager →  BA mode (write story) OR PM mode (review + refine)
+Phase 1.5: specifier       →  Formal SPEC: FRs, data shapes, failure modes
+Phase 2:   architect       →  System design, ADRs (reads SPEC)
+Phase 3:   qa_lead         →  Validate SPEC FRs for testability  } parallel
+           test_designer   →  Design test strategy from SPEC FRs } parallel
+Phase 4:   developer       →  Scope declaration → impact_architect gate (if needed) → Implementation
+Phase 5:   pr_reviewer     →  Stage 0: CHANGE artifact check → Code review
+Phase 6:   tester          →  Tests pass  } parallel
+           security_owner  →  Security    } parallel (both must pass)
+Close:     scrum_master    →  Artifacts verified, REQ.md → Done, project_status.md
+```
+
+Parallel phases require `workflow(action="parallel_start", story_id="...")` before proceeding.
+Both parallel agents must pass before the phase advances.
+
+---
+
+## Escalation Protocol
+
+Apply at every decision point where a blocker exists.
+
+```
+L1 — Auto-resolve:  Route to the responsible agent. Example: design unclear → architect.
+L2 — Collaborate:   Bring in related agents. Example: architect + PM together.
+L3 — HALT:          Stop. Ask the user. Call log(event="escalation", level="L3", ...) first.
+```
+
+L3 is mandatory when:
+- Regression risk cannot be scoped without user input
+- Debt fix discovered mid-feature (user decides: fix now or log only)
+- Critical vulnerability found (always HALT, no exception)
+- AC is not testable after L1+L2 attempts
+
+---
+
+## Debt Guardrail (Critical)
+
+When debt is found during feature work:
+
+1. Call `log(event="debt", debt_type="...", severity="...", location="...")`.
+2. HALT. Ask the user: fix now or log for later?
+3. User says fix: update status to `Approved`, fix in same PR or new `DEBT-XXX` story.
+4. User says log: continue with feature. Status stays `Open`.
+
+**Agents do NOT decide on their own.** Silent debt fixes are scope creep.
+
+---
+
+## Tool Reference (REF-Agents MCP)
+
+### Primary Tools — Call These First
+
+| Tool | When to Call |
+|---|---|
+| `agent(action="list")` | Session start. Confirm MCP active. |
+| `agent(action="activate", name="scrum_master")` | **NEW STORY START** — always first. |
+| `agent(action="activate", name="<role>")` | For non-story tasks (fix, review, scan). |
+| `set_project_root(path="...")` | First call in any new project session. |
+| `set_story_context(story_id="...")` | At start of each story (done by SM). |
+| `workflow(action="init", story_id="...")` | Called by scrum_master only — do not call directly. |
+| `workflow(action="state", story_id="...")` | To check current phase and blockers. |
+| `workflow(action="next", story_id="...")` | After completing any phase. |
+
+### Logging — Call on Every State Change
+
+| Event | Call |
+|---|---|
+| Escalation | `log(event="escalation", level="L1|L2|L3", reason="...", to_agents="...")` |
+| Ownership transfer | `log(event="ownership", to_owner="...", reason="...")` |
+| Phase complete | `log(event="phase", phase="...", outcome="passed|failed", next_phase="...")` |
+| Debt found | `log(event="debt", debt_type="...", severity="...", location="...")` |
+| Replan triggered | `log(event="replan", trigger="...", impact="...")` |
+| Artifact done | `log(event="artifact", artifact="...")` |
+
+### Analysis — Use scan() for all codebase reads
+
+```
+scan(target="health", directory="...")       — Primary entry point. Runs ALL scanners. Auto-starts remediation session on Critical/High findings.
+scan(target="debt", directory="...")         — Technical debt registry.
+scan(target="security", directory="...")     — Vulnerability audit.
+scan(target="compliance", file_path="...")   — REF quality check on a single file.
+scan(target="complexity", files="...")       — Cyclomatic/cognitive complexity.
+```
+
+### Compliance Remediation — Use remediate() after any scan with violations
+
+```
+remediate(action="execute", session_id=..., tier="tier1")                 — Run autonomous Tier 1 fixes. Call immediately after scan(target="health") returns session ID.
+remediate(action="approve", session_id=...)                               — Single approval gate for all Tier 2 fixes.
+remediate(action="execute", session_id=..., tier="tier2")                 — Run approved Tier 2 fixes.
+remediate(action="state", session_id=...)                                 — Check progress at any point.
+remediate(action="defer", session_id=..., violation_id=..., reason=...)   — Defer violation to TECH_DEBT.md.
+remediate(action="complete", session_id=...)                              — Close after PR Reviewer gate passes.
+
+remediate(action="start") is called automatically by scan(). Do not call it manually.
+```
+
+Session starts automatically on scan. Tier 1 runs on agent command. Tier 2 needs one approval. Tier 3 always halts.
+Tier 1: type hints, bare except, print(), logging, imports, docstrings — fully autonomous.
+Tier 2: complexity refactors, dead code, AI patterns, test coverage — one user approval.
+Tier 3: security, architectural boundaries, high regression risk — always HALT.
+
+---
+
+## Elite Code Quality Protocol (Non-Negotiable)
+
+### Python
+- 100% type hints on all function signatures.
+- `structlog` only. `print()` is forbidden in production.
+- Derive all exceptions from `AppError`.
+- Google-style docstrings. No AI fluff in docstrings.
+- `ruff check --fix && ruff format && pyright` must exit 0.
+
+### TypeScript
+- `any` is forbidden. Use explicit `interface` or `type`.
+- `Zod` schema required for all external inputs.
+- `TanStack Query` for all server-side state.
+
+### Universal
+- Cyclomatic complexity ≤ 15 per function.
+- Test coverage ≥ 85% on changed files.
+- No mocking the unit under test (UUT). Only mock external third-party APIs.
+- Paste actual shell execution output in the PR compliance section.
+
+### Staff Engineer Gate (PR Reviewer)
+Before any verdict, ask: "Would a staff engineer approve this?"
+- Diff behaviour between main and proposed changes.
+- Run tests, check logs, demonstrate correctness. Never mark complete without proof.
+- If the answer is no: REQUEST CHANGES regardless of other checks passing.
+
+---
+
+## Artifacts
+
+| Artifact | Owner | Location |
+|---|---|---|
+| `codemap/CODE_MAP.md` | Discovery, Architect | `codemap/` |
+| `REQ.md` | Product Manager | `docs/requirements/` |
+| `TECH_DEBT.md` | Discovery, PR Reviewer | `docs/` |
+| `handoff_log.jsonl` | Scrum Master | `ref-reports/` |
+| `project_status.md` | Scrum Master | `docs/` |
+| `FEATURES.md` | Discovery | Project root |
+| `EXTERNAL_DEPS.md` | Discovery, Architect | `docs/` |
+| `ref-reports/` | Platform Engineer, Security | `ref-reports/` |
+| `ref-reports/post-mortem-*.md` | Forensic Engineer | `ref-reports/` — lessons learned, append-only |
+
+---
+
+*Generated by REF Discovery Agent v3.2. Regenerate with `generate_agents_md(directory=".")` after major protocol changes.*
+"""
+
+
+def generate_agents_file(directory: str) -> str:
+    """Generate AGENTS.md at project root.
+
+    Args:
+        directory: Path to project root.
+
+    Returns:
+        Status message.
+    """
+    root = Path(directory)
+
+    if not root.exists():
+        return f"Error: Directory {directory} does not exist."
+
+    agents_path = root / "AGENTS.md"
+
+    # Always overwrite - this is a protocol file
+    agents_path.write_text(AGENTS_MD_CONTENT, encoding="utf-8")
+
+    logger.info("agents_md_generated", path=str(agents_path))
+
+    return f"✅ AGENTS.md generated at `{agents_path}`"