devagent-ai 0.3.1__py3-none-any.whl

devagent/retrieval.py

@@ -0,0 +1,478 @@
+from __future__ import annotations
+
+import ast
+import re
+from collections import defaultdict
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from devagent.models import RepositoryModel
+from devagent.safety import SafetyError
+from devagent.workspace import Workspace
+
+
+_STOP_WORDS = {
+    "the", "and", "for", "with", "this", "that", "from", "when", "where", "into",
+    "add", "fix", "bug", "test", "tests", "application", "without", "changing",
+}
+_CONCEPT_ALIASES = {
+    "authentication": ("auth", "authenticate"),
+    "authorization": ("authz", "authorize"),
+    "configuration": ("config", "configure"),
+    "reconnection": ("reconnect",),
+}
+_SOURCE_EXTENSIONS = frozenset(
+    {
+        ".py", ".pyi", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".go", ".rs",
+        ".java", ".kt", ".kts", ".c", ".cc", ".cpp", ".h", ".hpp", ".cs", ".rb",
+        ".php", ".swift", ".scala", ".sh", ".sql", ".vue", ".svelte",
+    }
+)
+_CONFIG_EXTENSIONS = frozenset({".toml", ".yaml", ".yml"})
+_CONFIG_NAMES = frozenset(
+    {
+        "pyproject.toml", "requirements.txt", "setup.py", "setup.cfg", "tox.ini",
+        "pytest.ini", "package.json", "tsconfig.json", "cargo.toml", "go.mod", "go.sum",
+        "pom.xml", "build.gradle", "gradlew", "cmakelists.txt", "makefile", "meson.build",
+        "dockerfile", "jenkinsfile", ".gitlab-ci.yml", "azure-pipelines.yml",
+        "readme", "readme.md", "readme.rst", "contributing.md", "contributing.rst",
+    }
+)
+_GENERATED_NAMES = frozenset(
+    {
+        "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml",
+        "poetry.lock", "uv.lock", "pipfile.lock", "cargo.lock",
+    }
+)
+_GENERATED_PARTS = frozenset(
+    {
+        "vendor", "vendors", "coverage", "htmlcov", ".tox", ".nox", ".pytest_cache",
+        ".mypy_cache", ".ruff_cache", ".next", ".nuxt", "out", "site-packages",
+    }
+)
+
+
+@dataclass(frozen=True)
+class RetrievalBudget:
+    max_files: int = 20
+    max_chars: int = 24_000
+    max_per_file_chars: int = 6_000
+    max_fallback_files: int = 6
+    small_repository_max_files: int = 20
+    inventory_max_files: int = 12_000
+    max_scan_chars: int = 12_000_000
+    max_relationship_files: int = 500
+
+
+def _split_identifier(value: str) -> list[str]:
+    separated = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", value)
+    separated = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1 \2", separated)
+    return [token.casefold() for token in re.findall(r"[A-Za-z][A-Za-z0-9]*", separated)]
+
+
+def _normalized_forms(token: str) -> tuple[str, ...]:
+    token = token.casefold()
+    forms = [token]
+    forms.extend(_CONCEPT_ALIASES.get(token, ()))
+    if len(token) > 5 and token.endswith("ies"):
+        forms.append(token[:-3] + "y")
+    if len(token) > 5 and token.endswith("ing"):
+        forms.extend((token[:-3], token[:-3] + "e"))
+    if len(token) > 4 and token.endswith("ed"):
+        forms.extend((token[:-2], token[:-1]))
+    if len(token) > 6 and token.endswith("ation"):
+        forms.append(token[:-5] + "e")
+    if len(token) > 6 and token.endswith("sion"):
+        forms.append(token[:-4] + "de")
+    elif len(token) > 6 and token.endswith("tion"):
+        forms.append(token[:-3])
+    if len(token) > 4 and token.endswith("s") and not token.endswith(("ss", "is")):
+        forms.append(token[:-1])
+    return tuple(dict.fromkeys(form for form in forms if len(form) >= 3))
+
+
+def task_terms(task: str) -> list[str]:
+    terms: list[str] = []
+    for token in _split_identifier(task):
+        if token in _STOP_WORDS:
+            continue
+        terms.extend(_normalized_forms(token))
+    return list(dict.fromkeys(terms))[:32]
+
+
+def _raw_task_terms(task: str) -> list[str]:
+    return list(
+        dict.fromkeys(
+            token
+            for token in _split_identifier(task)
+            if len(token) >= 3 and token not in _STOP_WORDS
+        )
+    )[:16]
+
+
+def _is_test_path(path: str) -> bool:
+    lowered = path.casefold()
+    parts = Path(lowered).parts
+    name = Path(lowered).name
+    return (
+        any(part in {"test", "tests", "spec", "specs", "__tests__"} for part in parts)
+        or name.startswith("test_")
+        or name.endswith("_test.py")
+        or ".test." in name
+        or ".spec." in name
+    )
+
+
+def _file_kind(path: str) -> str | None:
+    candidate = Path(path)
+    lowered_parts = tuple(part.casefold() for part in candidate.parts)
+    name = candidate.name.casefold()
+    if any(part in _GENERATED_PARTS for part in lowered_parts):
+        return None
+    if name in _GENERATED_NAMES or candidate.suffix.casefold() == ".map" or ".min." in name:
+        return None
+    if candidate.suffix.casefold() in _SOURCE_EXTENSIONS:
+        return "test" if _is_test_path(path) else "source"
+    if name in _CONFIG_NAMES or candidate.suffix.casefold() in _CONFIG_EXTENSIONS:
+        return "documentation" if name.startswith(("readme", "contributing")) else "manifest"
+    if path.startswith(".github/workflows/") and candidate.suffix.casefold() in {".yml", ".yaml"}:
+        return "manifest"
+    return None
+
+
+def _inventory(workspace: Workspace, budget: RetrievalBudget) -> list[tuple[str, str, int]]:
+    inventory: list[tuple[str, str, int]] = []
+    for relative in workspace.list_files(limit=budget.inventory_max_files):
+        kind = _file_kind(relative)
+        if kind is None:
+            continue
+        try:
+            target = workspace.paths.resolve(relative, allow_missing=False)
+            size = target.stat().st_size
+        except (OSError, SafetyError):
+            continue
+        if size > 2_000_000:
+            continue
+        inventory.append((relative, kind, size))
+    return sorted(inventory)
+
+
+def _content_tokens(text: str) -> tuple[set[str], set[str]]:
+    raw = set(_split_identifier(text))
+    normalized = {form for token in raw for form in _normalized_forms(token)}
+    return raw, normalized
+
+
+def _python_module_map(paths: list[str]) -> dict[str, str]:
+    modules: dict[str, str] = {}
+    for path in paths:
+        candidate = Path(path)
+        if candidate.suffix.casefold() not in {".py", ".pyi"}:
+            continue
+        parts = list(candidate.with_suffix("").parts)
+        if parts and parts[-1] == "__init__":
+            parts.pop()
+        if parts:
+            modules.setdefault(".".join(parts), path)
+            modules.setdefault(parts[-1], path)
+    return modules
+
+
+def _python_import_relationships(
+    workspace: Workspace, paths: list[str], content_cache: dict[str, str], budget: RetrievalBudget
+) -> list[dict[str, str]]:
+    module_map = _python_module_map(paths)
+    relationships: set[tuple[str, str, str]] = set()
+    parsed = 0
+    for path in paths:
+        if parsed >= budget.max_relationship_files or Path(path).suffix.casefold() not in {".py", ".pyi"}:
+            continue
+        try:
+            text = content_cache.get(path)
+            if text is None:
+                text = workspace.read_file(path, max_chars=80_000)
+            tree = ast.parse(text)
+        except (OSError, SyntaxError, UnicodeError, SafetyError):
+            continue
+        parsed += 1
+        imported: set[str] = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                imported.update(alias.name for alias in node.names)
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                imported.add(node.module)
+        for module in imported:
+            target = module_map.get(module) or module_map.get(module.split(".")[0])
+            if not target or target == path:
+                continue
+            if _is_test_path(path) and not _is_test_path(target):
+                relationships.add((target, path, "python_import"))
+            elif _is_test_path(target) and not _is_test_path(path):
+                relationships.add((path, target, "python_import"))
+    return [
+        {"source": source, "test": test, "kind": kind}
+        for source, test, kind in sorted(relationships)
+    ]
+
+
+def _naming_relationships(paths: list[str]) -> list[dict[str, str]]:
+    path_set = set(paths)
+    relationships: set[tuple[str, str, str]] = set()
+    for test in paths:
+        candidate = Path(test)
+        if not _is_test_path(test) or candidate.suffix.casefold() not in _SOURCE_EXTENSIONS:
+            continue
+        stem = candidate.stem
+        if stem.startswith("test_"):
+            source_stem = stem[5:]
+        elif stem.endswith("_test"):
+            source_stem = stem[:-5]
+        else:
+            source_stem = stem.removesuffix(".test").removesuffix(".spec")
+        possible = [
+            candidate.with_name(source_stem + candidate.suffix).as_posix(),
+            (candidate.parent.parent / (source_stem + candidate.suffix)).as_posix(),
+        ]
+        for source in possible:
+            if source in path_set and source != test and not _is_test_path(source):
+                relationships.add((source, test, "test_naming"))
+    return [
+        {"source": source, "test": test, "kind": kind}
+        for source, test, kind in sorted(relationships)
+    ]
+
+
+def _javascript_relationships(
+    paths: list[str], content_cache: dict[str, str]
+) -> list[dict[str, str]]:
+    path_set = set(paths)
+    relationships: set[tuple[str, str, str]] = set()
+    extensions = (".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx")
+    pattern = re.compile(r"(?:from\s+|require\s*\(\s*)[\"'](\.[^\"']+)")
+    for path in paths:
+        if not _is_test_path(path) or Path(path).suffix.casefold() not in extensions:
+            continue
+        text = content_cache.get(path)
+        if text is None:
+            continue
+        for import_path in pattern.findall(text):
+            base = (Path(path).parent / import_path).as_posix()
+            candidates = [base, *(base + extension for extension in extensions)]
+            candidates.extend((Path(base) / ("index" + extension)).as_posix() for extension in extensions)
+            for source in candidates:
+                if source in path_set and not _is_test_path(source):
+                    relationships.add((source, path, "relative_import"))
+                    break
+    return [
+        {"source": source, "test": test, "kind": kind}
+        for source, test, kind in sorted(relationships)
+    ]
+
+
+def _relationships(
+    workspace: Workspace, paths: list[str], content_cache: dict[str, str], budget: RetrievalBudget
+) -> list[dict[str, str]]:
+    combined = [
+        *_python_import_relationships(workspace, paths, content_cache, budget),
+        *_javascript_relationships(paths, content_cache),
+        *_naming_relationships(paths),
+    ]
+    unique = {(item["source"], item["test"], item["kind"]): item for item in combined}
+    return [unique[key] for key in sorted(unique)]
+
+
+def _component_for(path: str, repository: RepositoryModel) -> str:
+    candidates = [
+        component.path
+        for component in repository.components
+        if component.path == "." or path == component.path or path.startswith(component.path.rstrip("/") + "/")
+    ]
+    return max(candidates, key=len, default=".")
+
+
+def retrieve_context(
+    workspace: Workspace,
+    repository: RepositoryModel,
+    task: str,
+    max_chars: int = 24_000,
+    *,
+    requires_tests: bool | None = None,
+    budget: RetrievalBudget | None = None,
+) -> dict[str, object]:
+    configured = budget or RetrievalBudget(max_chars=max_chars)
+    if max_chars != configured.max_chars:
+        configured = RetrievalBudget(**{**asdict(configured), "max_chars": max_chars})
+    requires_tests = (
+        any(term in task.casefold() for term in ("test", "regression", "verify"))
+        if requires_tests is None
+        else requires_tests
+    )
+    inventory = _inventory(workspace, configured)
+    paths = [path for path, _, _ in inventory]
+    kinds = {path: kind for path, kind, _ in inventory}
+    sizes = {path: size for path, _, size in inventory}
+    raw_terms = _raw_task_terms(task)
+    terms = task_terms(task)
+    scores: defaultdict[str, int] = defaultdict(int)
+    lexical_scores: defaultdict[str, int] = defaultdict(int)
+    matches: list[str] = []
+    content_cache: dict[str, str] = {}
+    scanned_chars = 0
+    exact_lexical_matches = 0
+    normalized_lexical_matches = 0
+
+    for path in paths:
+        path_raw, path_normalized = _content_tokens(path)
+        exact_path = path_raw.intersection(raw_terms)
+        normalized_path = path_normalized.intersection(terms)
+        if exact_path:
+            lexical_scores[path] += 12 * len(exact_path)
+            exact_lexical_matches += len(exact_path)
+        if normalized_path:
+            lexical_scores[path] += 6 * len(normalized_path)
+            normalized_lexical_matches += len(normalized_path - exact_path)
+        if scanned_chars >= configured.max_scan_chars:
+            continue
+        allowance = min(200_000, configured.max_scan_chars - scanned_chars)
+        try:
+            text = workspace.read_file(path, max_chars=allowance)
+        except (OSError, UnicodeError, SafetyError):
+            continue
+        content_cache[path] = text
+        scanned_chars += min(len(text), allowance)
+        raw, normalized = _content_tokens(text)
+        exact = raw.intersection(raw_terms)
+        related = normalized.intersection(terms)
+        if exact:
+            lexical_scores[path] += 8 * len(exact)
+            exact_lexical_matches += len(exact)
+            matches.append(f"{path}: exact terms: {', '.join(sorted(exact))}")
+        if related:
+            lexical_scores[path] += 4 * len(related)
+            normalized_lexical_matches += len(related - exact)
+            if not exact:
+                matches.append(f"{path}: normalized terms: {', '.join(sorted(related))}")
+
+    for path in paths:
+        scores[path] = lexical_scores[path]
+        if kinds[path] == "test" and requires_tests:
+            scores[path] += 3
+        elif kinds[path] == "source":
+            scores[path] += 1
+        elif kinds[path] == "manifest":
+            scores[path] += 1
+
+    relationships = _relationships(workspace, paths, content_cache, configured)
+    lexical_paths = {path for path, score in lexical_scores.items() if score > 0}
+    for relationship in relationships:
+        source, test = relationship["source"], relationship["test"]
+        if source in lexical_paths:
+            scores[test] += 10
+        if test in lexical_paths:
+            scores[source] += 10
+
+    small_repository = (
+        len(inventory) <= configured.small_repository_max_files
+        and sum(sizes.values()) <= configured.max_chars
+        and all(size <= configured.max_per_file_chars for size in sizes.values())
+    )
+    fallback = "none"
+    fallback_paths: list[str] = []
+    if small_repository:
+        selected = paths[: configured.max_files]
+        fallback = "small-repository inventory"
+    else:
+        ranked_lexical = sorted(
+            (path for path in paths if lexical_scores[path] > 0),
+            key=lambda path: (-scores[path], path),
+        )
+        primary_limit = max(1, configured.max_files - configured.max_fallback_files)
+        selected = ranked_lexical[:primary_limit]
+        selected_kinds = {kinds[path] for path in selected}
+        low_coverage = (
+            not any(kinds[path] == "source" for path in selected)
+            or selected_kinds <= {"manifest", "documentation"}
+            or (requires_tests and not any(kinds[path] == "test" for path in selected))
+            or len(selected) < 2
+        )
+        if low_coverage:
+            fallback = "bounded structural coverage"
+            candidates: list[str] = []
+            for relationship in relationships:
+                if relationship["source"] in selected or relationship["test"] in selected:
+                    candidates.extend((relationship["source"], relationship["test"]))
+            matched_components = {_component_for(path, repository) for path in selected}
+            if selected:
+                parents = {str(Path(path).parent) for path in selected}
+                candidates.extend(path for path in paths if str(Path(path).parent) in parents)
+                candidates.extend(
+                    path for path in paths if _component_for(path, repository) in matched_components
+                )
+            structural = sorted(
+                (
+                    path for path in paths
+                    if kinds[path] in ({"source", "test", "manifest"} if requires_tests else {"source", "manifest"})
+                ),
+                key=lambda path: (
+                    0 if requires_tests and kinds[path] == "test" else 1 if kinds[path] == "source" else 2,
+                    -scores[path],
+                    path,
+                ),
+            )
+            candidates.extend(structural)
+            if any(term in task.casefold() for term in ("architecture", "setup", "build", "command")):
+                candidates.extend(path for path in paths if kinds[path] == "documentation")
+            for path in candidates:
+                if path in selected or path in fallback_paths:
+                    continue
+                fallback_paths.append(path)
+                if len(fallback_paths) >= configured.max_fallback_files:
+                    break
+            selected.extend(fallback_paths)
+        selected = selected[: configured.max_files]
+
+    snippets: dict[str, str] = {}
+    remaining = configured.max_chars
+    for path in selected:
+        if remaining <= 0:
+            break
+        try:
+            content = workspace.read_file(path, max_chars=min(configured.max_per_file_chars, remaining))
+        except (OSError, UnicodeError, SafetyError):
+            continue
+        snippets[path] = content
+        remaining -= len(content)
+
+    selected = list(snippets)
+    return {
+        "terms": terms,
+        "ranked_paths": selected,
+        "matches": matches[:100],
+        "snippets": snippets,
+        "relationships": [
+            relationship
+            for relationship in relationships
+            if relationship["source"] in selected or relationship["test"] in selected
+        ],
+        "diagnostics": {
+            "repository_files": len(inventory),
+            "inventory_truncated": len(workspace.list_files(limit=configured.inventory_max_files)) >= configured.inventory_max_files,
+            "exact_lexical_matches": exact_lexical_matches,
+            "normalized_lexical_matches": normalized_lexical_matches,
+            "fallback": fallback,
+            "fallback_paths": fallback_paths,
+            "selected": selected,
+            "relationship_count": len(relationships),
+            "budgets": asdict(configured),
+        },
+        "repo_map": [
+            {
+                "path": component.path,
+                "languages": component.languages,
+                "frameworks": component.frameworks,
+                "manifests": component.manifests,
+                "tests": component.test_locations,
+            }
+            for component in repository.components
+        ],
+    }

devagent/safety.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import fnmatch
+import os
+import shlex
+from pathlib import Path
+from typing import Sequence
+
+
+class SafetyError(RuntimeError):
+    """Raised when a requested local operation crosses a safety boundary."""
+
+
+SKIP_DIRECTORIES = frozenset(
+    {
+        ".git", ".devagent", ".venv", "venv", "node_modules", "dist", "build",
+        "target", "__pycache__", "vendor", "coverage", "htmlcov", ".tox", ".nox",
+        ".pytest_cache", ".mypy_cache", ".ruff_cache", ".next", "site-packages",
+    }
+)
+
+_SECRET_PATTERNS = (
+    ".env",
+    ".env.*",
+    "*.pem",
+    "*.key",
+    "id_rsa",
+    "id_ed25519",
+    "credentials*",
+    "secrets*",
+    "*private_key*",
+    "*apikey*",
+)
+
+
+def is_secret_path(path: Path) -> bool:
+    lowered_parts = tuple(part.lower() for part in path.parts)
+    if ".ssh" in lowered_parts or ".aws" in lowered_parts:
+        return True
+    name = path.name.lower()
+    return any(fnmatch.fnmatch(name, pattern) for pattern in _SECRET_PATTERNS)
+
+
+class PathPolicy:
+    def __init__(self, root: Path | str) -> None:
+        self.root = Path(root).expanduser().resolve()
+        if not self.root.is_dir():
+            raise SafetyError(f"Workspace is not a directory: {self.root}")
+
+    def resolve(self, relative: str, *, allow_missing: bool = True) -> Path:
+        if not relative or "\x00" in relative:
+            raise SafetyError("Path must be a non-empty text path")
+        candidate = (self.root / relative).resolve(strict=False)
+        try:
+            candidate.relative_to(self.root)
+        except ValueError as exc:
+            raise SafetyError(f"Path escapes workspace: {relative}") from exc
+        if is_secret_path(candidate.relative_to(self.root)):
+            raise SafetyError(f"Access to sensitive file is blocked: {relative}")
+        if not allow_missing and not candidate.exists():
+            raise SafetyError(f"Path does not exist: {relative}")
+        return candidate
+
+
+class CommandPolicy:
+    """Token-aware policy for non-shell subprocess execution."""
+
+    _BLOCKED_PROGRAMS = {
+        "sudo",
+        "su",
+        "rm",
+        "rmdir",
+        "mkfs",
+        "shutdown",
+        "reboot",
+        "poweroff",
+        "curl",
+        "wget",
+        "scp",
+        "ssh",
+        "sftp",
+        "rsync",
+        "nc",
+        "netcat",
+        "busybox",
+        "env",
+    }
+    _READ_ONLY_GIT = {"diff", "status", "rev-parse", "log", "show", "ls-files", "grep"}
+    _SHELL_PROGRAMS = {"sh", "bash", "zsh", "fish", "cmd", "powershell", "pwsh"}
+    _INSTALLERS = {("pip", "install"), ("pip3", "install"), ("npm", "install"), ("npm", "i"), ("pnpm", "add"), ("yarn", "add")}
+
+    @classmethod
+    def parse(cls, command: str | Sequence[str]) -> tuple[str, ...]:
+        if isinstance(command, str):
+            try:
+                tokens = tuple(shlex.split(command, posix=os.name != "nt"))
+            except ValueError as exc:
+                raise SafetyError(f"Invalid command quoting: {exc}") from exc
+        else:
+            tokens = tuple(str(item) for item in command)
+        if not tokens or any(not token or "\x00" in token for token in tokens):
+            raise SafetyError("Command must contain non-empty arguments")
+        return tokens
+
+    @classmethod
+    def validate(cls, command: str | Sequence[str]) -> tuple[str, ...]:
+        tokens = cls.parse(command)
+        executable = Path(tokens[0]).name.lower()
+        lowered = tuple(token.lower() for token in tokens)
+        if executable in cls._BLOCKED_PROGRAMS or executable in cls._SHELL_PROGRAMS:
+            raise SafetyError(f"Blocked command program: {executable}")
+        if executable == "git" and (len(lowered) < 2 or lowered[1] not in cls._READ_ONLY_GIT):
+            operation = lowered[1] if len(lowered) > 1 else "(missing)"
+            raise SafetyError(f"Only explicit read-only Git operations are allowed; blocked: git {operation}")
+        if executable in {"python", "python3", "node", "ruby", "perl"} and any(
+            token in {"-c", "-e", "--eval"} for token in lowered[1:]
+        ):
+            raise SafetyError("Inline interpreter execution is blocked")
+        if executable in {"python", "python3"} and len(lowered) > 2 and lowered[1:3] == ("-m", "pip"):
+            raise SafetyError("Package installation and pip execution are blocked during a run")
+        if len(lowered) > 1 and (executable, lowered[1]) in cls._INSTALLERS:
+            raise SafetyError(f"Package installation is blocked during an engineering run: {' '.join(tokens[:2])}")
+        for token in tokens:
+            lowered_token = token.lower()
+            if is_secret_path(Path(lowered_token)):
+                raise SafetyError("Command references a sensitive path")
+            if lowered_token.startswith(("http://", "https://", "ftp://")):
+                raise SafetyError("Network URLs are blocked in engineering commands")
+            if any(operator in token for operator in ("\n", "\r", "`", "$(", ">${", "<${")):
+                raise SafetyError("Shell syntax is not allowed in structured commands")
+        return tokens

devagent/state_machine.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from devagent.models import AgentState
+
+
+class InvalidTransition(RuntimeError):
+    pass
+
+
+_TRANSITIONS: dict[AgentState, set[AgentState]] = {
+    AgentState.PREFLIGHT: {AgentState.DISCOVER, AgentState.BLOCKED},
+    AgentState.DISCOVER: {AgentState.UNDERSTAND, AgentState.BLOCKED},
+    AgentState.UNDERSTAND: {AgentState.TASK_SPEC, AgentState.GATHER_CONTEXT, AgentState.BLOCKED},
+    AgentState.TASK_SPEC: {AgentState.BASELINE, AgentState.BLOCKED},
+    AgentState.BASELINE: {AgentState.PLAN, AgentState.BLOCKED},
+    AgentState.PLAN: {AgentState.GATHER_CONTEXT, AgentState.BLOCKED},
+    AgentState.GATHER_CONTEXT: {AgentState.UNDERSTAND, AgentState.REPRODUCE, AgentState.PLAN, AgentState.BLOCKED},
+    AgentState.REPRODUCE: {AgentState.IMPLEMENT, AgentState.GATHER_CONTEXT, AgentState.BLOCKED},
+    AgentState.IMPLEMENT: {AgentState.VERIFY_TARGETED, AgentState.BLOCKED},
+    AgentState.VERIFY_TARGETED: {AgentState.DIAGNOSE, AgentState.VERIFY_BROAD, AgentState.BLOCKED},
+    AgentState.DIAGNOSE: {AgentState.PLAN, AgentState.IMPLEMENT, AgentState.BLOCKED},
+    AgentState.VERIFY_BROAD: {AgentState.REVIEW, AgentState.DIAGNOSE, AgentState.PARTIALLY_VERIFIED},
+    AgentState.REVIEW: {AgentState.IMPLEMENT, AgentState.QUALITY_CHECK, AgentState.BLOCKED},
+    AgentState.QUALITY_CHECK: {AgentState.IMPLEMENT, AgentState.FINAL_VERIFY, AgentState.BLOCKED},
+    AgentState.FINAL_VERIFY: {AgentState.LEARN, AgentState.DIAGNOSE, AgentState.PARTIALLY_VERIFIED},
+    AgentState.LEARN: {AgentState.REPORT},
+    AgentState.REPORT: {AgentState.SUCCESS, AgentState.PARTIALLY_VERIFIED, AgentState.BLOCKED},
+    AgentState.SUCCESS: set(),
+    AgentState.PARTIALLY_VERIFIED: set(),
+    AgentState.BLOCKED: set(),
+}
+
+
+@dataclass
+class Lifecycle:
+    state: AgentState = AgentState.PREFLIGHT
+    history: list[AgentState] = field(default_factory=lambda: [AgentState.PREFLIGHT])
+
+    def transition(self, target: AgentState) -> None:
+        if target not in _TRANSITIONS[self.state]:
+            raise InvalidTransition(f"Invalid DevAgent transition: {self.state.value} -> {target.value}")
+        self.state = target
+        self.history.append(target)