agentic-development-framework 0.1.0__py3-none-any.whl

agentic_framework/core/config.py

@@ -0,0 +1,146 @@
+"""Validated YAML configuration for the framework."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from pathlib import Path, PurePath
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+from agentic_framework.exceptions import ConfigurationError
+
+
+class StrictModel(BaseModel):
+    """Base model that rejects misspelled and unsupported configuration keys."""
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+
+class ProjectMode(StrEnum):
+    """How project discovery should treat the target directory."""
+
+    AUTO = "auto"
+    NEW = "new"
+    EXISTING = "existing"
+
+
+class IdeKind(StrEnum):
+    """IDE harnesses known to the initial product specification."""
+
+    CODEX = "codex"
+    ANTIGRAVITY = "antigravity"
+    VSCODE = "vscode"
+
+
+class LogLevel(StrEnum):
+    """Supported Python logging levels."""
+
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+
+class ProjectConfig(StrictModel):
+    """Project identification and discovery preferences."""
+
+    name: str | None = Field(default=None, min_length=1, max_length=100)
+    mode: ProjectMode = ProjectMode.AUTO
+
+    @field_validator("name")
+    @classmethod
+    def normalize_name(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("project name cannot be blank")
+        return normalized
+
+
+class RuntimeConfig(StrictModel):
+    """Local runtime storage and diagnostic preferences."""
+
+    directory: Path = Path(".agentic")
+    log_level: LogLevel = LogLevel.INFO
+
+    @field_validator("directory")
+    @classmethod
+    def require_safe_relative_path(cls, value: Path) -> Path:
+        path = PurePath(value)
+        if path.is_absolute():
+            raise ValueError("runtime directory must be project-relative")
+        if not path.parts or any(part == ".." for part in path.parts):
+            raise ValueError("runtime directory cannot traverse outside the project")
+        return Path(path)
+
+
+class IdeConfig(StrictModel):
+    """IDE adapters requested for a project."""
+
+    enabled: list[IdeKind] = Field(default_factory=lambda: [IdeKind.CODEX])
+
+    @field_validator("enabled")
+    @classmethod
+    def require_unique_adapters(cls, value: list[IdeKind]) -> list[IdeKind]:
+        if len(value) != len(set(value)):
+            raise ValueError("IDE adapters must not be duplicated")
+        return value
+
+
+class PolicyConfig(StrictModel):
+    """Conservative capability defaults for future execution phases."""
+
+    allow_network: bool = False
+    allow_destructive_operations: bool = False
+
+
+class FrameworkConfig(StrictModel):
+    """Root configuration document."""
+
+    schema_version: int = Field(default=1, ge=1, le=1)
+    project: ProjectConfig = Field(default_factory=ProjectConfig)
+    runtime: RuntimeConfig = Field(default_factory=RuntimeConfig)
+    ide: IdeConfig = Field(default_factory=IdeConfig)
+    policies: PolicyConfig = Field(default_factory=PolicyConfig)
+
+
+def parse_config(data: Any) -> FrameworkConfig:
+    """Validate decoded configuration data and present failures consistently."""
+
+    if data is None:
+        data = {}
+    if not isinstance(data, dict):
+        raise ConfigurationError("configuration root must be a YAML mapping")
+    try:
+        return FrameworkConfig.model_validate(data)
+    except ValidationError as exc:
+        raise ConfigurationError(f"configuration validation failed:\n{exc}") from exc
+
+
+def load_config(path: Path) -> FrameworkConfig:
+    """Read and validate a UTF-8 YAML configuration file."""
+
+    try:
+        content = path.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise ConfigurationError(f"configuration file does not exist: {path}") from exc
+    except OSError as exc:
+        raise ConfigurationError(f"cannot read configuration file {path}: {exc}") from exc
+
+    try:
+        data = yaml.safe_load(content)
+    except yaml.YAMLError as exc:
+        raise ConfigurationError(f"invalid YAML in {path}: {exc}") from exc
+    return parse_config(data)
+
+
+def dump_config(config: FrameworkConfig) -> str:
+    """Serialize a normalized configuration document as stable YAML."""
+
+    data = config.model_dump(mode="json")
+    return yaml.safe_dump(data, sort_keys=False)
+

agentic_framework/core/initialization.py

@@ -0,0 +1,241 @@
+"""Safe, deterministic project initialization."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+
+from agentic_framework.adapters import generated_project_files
+from agentic_framework.core.config import (
+    FrameworkConfig,
+    ProjectConfig,
+    ProjectMode,
+    dump_config,
+    load_config,
+)
+from agentic_framework.core.project import ProjectInspection, inspect_project
+from agentic_framework.exceptions import ConfigurationError, InitializationError
+from agentic_framework.state import RuntimeStore
+
+_DIRECTORIES = (
+    ".agentic/database",
+    ".agentic/state",
+    ".agentic/checkpoints",
+    ".agentic/logs",
+    ".agentic/reports",
+    ".agentic/proposals",
+    ".agents/rules",
+    ".agents/skills",
+    ".codex/agents",
+    ".github/agents",
+    ".github/instructions",
+    ".github/workflows",
+    "requirements/inbox",
+    "requirements/versions",
+    "requirements/reports",
+    "docs/architecture",
+    "docs/design",
+    "docs/decisions",
+    "docs/revisions",
+    "docs/reports",
+    "design-prototype",
+    "tests",
+)
+
+_AGENTS = """# Project agent instructions
+
+This project uses the Agentic Development Framework (ADF).
+
+- Read `.agentic/config.yaml` before framework operations.
+- Preserve existing project files and unrelated working-tree changes.
+- Do not expose secrets or perform destructive operations without explicit approval.
+- Treat framework slash commands as workflow requests even when the IDE has no native
+  slash-command support.
+- Use the `agentic-commands` skill for `/start`, `/status`, `/pause`, `/resume`, `/continue`,
+  `/stop`, `/review`, `/approve`, `/revise`, `/requirements`, and `/tasks`.
+- Do not claim a task or phase is complete until its required checks pass.
+"""
+
+_REQUIREMENTS_README = """# Project requirements
+
+Place source requirement files in `inbox/`, then run `adt requirements ingest`. ADF copies every
+source byte-for-byte into an immutable directory under `versions/`, detects duplicates using
+SHA-256 hashes, and compares each new version with its predecessor. Files in `inbox/` are never
+silently overwritten or removed.
+"""
+
+_GITIGNORE = """# Agentic Development Framework local runtime data
+.agentic/database/
+.agentic/state/
+.agentic/checkpoints/
+.agentic/logs/
+.agentic/proposals/
+"""
+
+
+class FileStatus(StrEnum):
+    """Outcome of safely installing one generated file."""
+
+    CREATED = "created"
+    UNCHANGED = "unchanged"
+    CONFLICT = "conflict"
+
+
+@dataclass(frozen=True, slots=True)
+class FileResult:
+    """Outcome and optional proposal for one generated file."""
+
+    path: Path
+    status: FileStatus
+    proposal: Path | None = None
+
+
+@dataclass(slots=True)
+class InitializationResult:
+    """Complete result returned to CLI and tests."""
+
+    inspection: ProjectInspection
+    mode: ProjectMode
+    files: list[FileResult] = field(default_factory=list)
+    git_initialized: bool = False
+
+    @property
+    def conflicts(self) -> tuple[FileResult, ...]:
+        return tuple(item for item in self.files if item.status is FileStatus.CONFLICT)
+
+
+def _proposal_path(root: Path, relative: Path) -> Path:
+    proposal_root = root / ".agentic" / "proposals"
+    return proposal_root / relative.parent / f"{relative.name}.proposed"
+
+
+def _safe_install(root: Path, relative: str, content: str) -> FileResult:
+    relative_path = Path(relative)
+    destination = root / relative_path
+    if not destination.exists():
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(content, encoding="utf-8")
+        return FileResult(path=relative_path, status=FileStatus.CREATED)
+
+    try:
+        existing = destination.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise InitializationError(f"cannot compare existing file {destination}: {exc}") from exc
+    if existing == content:
+        return FileResult(path=relative_path, status=FileStatus.UNCHANGED)
+
+    proposal = _proposal_path(root, relative_path)
+    proposal.parent.mkdir(parents=True, exist_ok=True)
+    if not proposal.exists() or proposal.read_text(encoding="utf-8") != content:
+        proposal.write_text(content, encoding="utf-8")
+    return FileResult(
+        path=relative_path,
+        status=FileStatus.CONFLICT,
+        proposal=proposal.relative_to(root),
+    )
+
+
+def _configuration(root: Path, inspection: ProjectInspection) -> tuple[FrameworkConfig, bool]:
+    existing = root / ".agentic" / "config.yaml"
+    if existing.is_file():
+        try:
+            return load_config(existing), True
+        except ConfigurationError:
+            pass
+    mode = ProjectMode.NEW if inspection.is_empty else ProjectMode.EXISTING
+    return FrameworkConfig(project=ProjectConfig(name=root.name, mode=mode)), False
+
+
+def _run_git_init(root: Path) -> None:
+    try:
+        subprocess.run(
+            ["git", "init", "--quiet"],
+            cwd=root,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise InitializationError("Git is not installed or is not available on PATH") from exc
+    except subprocess.CalledProcessError as exc:
+        detail = exc.stderr.strip() or "unknown Git error"
+        raise InitializationError(f"Git initialization failed: {detail}") from exc
+
+
+def _report(result: InitializationResult) -> str:
+    inspection = result.inspection
+    technologies = ", ".join(inspection.technologies) or "none detected"
+    managers = ", ".join(inspection.package_managers) or "none detected"
+    if result.git_initialized:
+        git_state = "initialized"
+    elif inspection.has_git:
+        git_state = "detected"
+    else:
+        git_state = "skipped"
+    lines = [
+        "# ADF initialization report",
+        "",
+        f"- Project root: `{inspection.root}`",
+        f"- Project mode: `{result.mode.value}`",
+        f"- Git: {git_state}",
+        f"- Technologies: {technologies}",
+        f"- Package managers: {managers}",
+        f"- Conflicts: {len(result.conflicts)}",
+    ]
+    if result.conflicts:
+        lines.extend(["", "## Conflicts", ""])
+        lines.extend(
+            f"- `{item.path}` preserved; proposed content written to `{item.proposal}`"
+            for item in result.conflicts
+        )
+    return "\n".join(lines) + "\n"
+
+
+def initialize_project(
+    target: Path,
+    *,
+    initialize_git: bool = True,
+    git_initializer: Callable[[Path], None] = _run_git_init,
+) -> InitializationResult:
+    """Initialize a target without overwriting existing project files."""
+
+    try:
+        inspection = inspect_project(target)
+    except (OSError, NotADirectoryError) as exc:
+        raise InitializationError(str(exc)) from exc
+
+    root = inspection.root
+    root.mkdir(parents=True, exist_ok=True)
+    config, existing_config_is_valid = _configuration(root, inspection)
+    result = InitializationResult(inspection=inspection, mode=config.project.mode)
+
+    for relative in _DIRECTORIES:
+        (root / relative).mkdir(parents=True, exist_ok=True)
+
+    if existing_config_is_valid:
+        result.files.append(
+            FileResult(path=Path(".agentic/config.yaml"), status=FileStatus.UNCHANGED)
+        )
+    else:
+        result.files.append(_safe_install(root, ".agentic/config.yaml", dump_config(config)))
+
+    generated = {
+        ".gitignore": _GITIGNORE,
+        "AGENTS.md": _AGENTS,
+        "requirements/README.md": _REQUIREMENTS_README,
+    }
+    generated.update(generated_project_files())
+    result.files.extend(_safe_install(root, path, content) for path, content in generated.items())
+
+    if initialize_git and not inspection.has_git:
+        git_initializer(root)
+        result.git_initialized = True
+
+    RuntimeStore(root).initialize()
+
+    report_path = root / ".agentic" / "reports" / "initialization.md"
+    report_path.write_text(_report(result), encoding="utf-8")
+    return result

agentic_framework/core/project.py

@@ -0,0 +1,93 @@
+"""Project discovery used by safe initialization."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+_TECHNOLOGY_MARKERS: dict[str, tuple[str, ...]] = {
+    "Docker": (
+        "Dockerfile",
+        "compose.yaml",
+        "compose.yml",
+        "docker-compose.yaml",
+        "docker-compose.yml",
+    ),
+    "Django": ("manage.py",),
+    "JavaScript": ("package.json",),
+    "Next.js": ("next.config.js", "next.config.mjs", "next.config.ts"),
+    "Python": ("pyproject.toml", "setup.py", "requirements.txt"),
+}
+
+_PACKAGE_MANAGER_MARKERS: dict[str, tuple[str, ...]] = {
+    "npm": ("package-lock.json",),
+    "pip": ("pyproject.toml", "requirements.txt", "setup.py"),
+    "pnpm": ("pnpm-lock.yaml",),
+    "Poetry": ("poetry.lock",),
+    "uv": ("uv.lock",),
+    "Yarn": ("yarn.lock",),
+}
+
+@dataclass(frozen=True, slots=True)
+class ProjectInspection:
+    """Read-only facts discovered about an initialization target."""
+
+    root: Path
+    is_empty: bool
+    git_root: Path | None
+    technologies: tuple[str, ...]
+    package_managers: tuple[str, ...]
+
+    @property
+    def has_git(self) -> bool:
+        return self.git_root is not None
+
+
+def _matching_labels(root: Path, markers: dict[str, tuple[str, ...]]) -> tuple[str, ...]:
+    excluded = {".agentic", ".git", ".venv", "node_modules"}
+
+    def exists(candidate: str) -> bool:
+        direct = root / candidate
+        if direct.exists():
+            return True
+        name = Path(candidate).name
+        for match in root.rglob(name):
+            relative = match.relative_to(root)
+            if len(relative.parts) <= 4 and not excluded.intersection(relative.parts):
+                return True
+        return False
+
+    return tuple(
+        label
+        for label, candidates in markers.items()
+        if any(exists(candidate) for candidate in candidates)
+    )
+
+
+def find_git_root(root: Path) -> Path | None:
+    """Find a repository marker in the target or one of its parents."""
+
+    for candidate in (root, *root.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return None
+
+
+def inspect_project(root: Path) -> ProjectInspection:
+    """Inspect a target without modifying it or invoking project tooling."""
+
+    resolved = root.expanduser().resolve()
+    if not resolved.exists():
+        is_empty = True
+    elif not resolved.is_dir():
+        raise NotADirectoryError(f"initialization target is not a directory: {resolved}")
+    else:
+        is_empty = next(resolved.iterdir(), None) is None
+
+    return ProjectInspection(
+        root=resolved,
+        is_empty=is_empty,
+        git_root=find_git_root(resolved),
+        technologies=_matching_labels(resolved, _TECHNOLOGY_MARKERS),
+        package_managers=_matching_labels(resolved, _PACKAGE_MANAGER_MARKERS),
+    )

agentic_framework/core/workflow.py

@@ -0,0 +1,94 @@
+"""Persistent workflow lifecycle and recovery behavior."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from agentic_framework.adapters.generator import APPROVAL_STAGES, STAGES
+from agentic_framework.exceptions import StateError
+from agentic_framework.state import RuntimeStore
+
+
+@dataclass(slots=True)
+class WorkflowService:
+    """Apply validated lifecycle transitions to a project runtime."""
+
+    project_root: Path
+    store: RuntimeStore = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.store = RuntimeStore(self.project_root)
+        if not self.store.database_path.is_file():
+            raise StateError(
+                f"runtime database does not exist; run adt init: {self.store.database_path}"
+            )
+
+    def status(self) -> dict[str, Any]:
+        return self.store.workflow()
+
+    def start(self) -> dict[str, Any]:
+        current = self.status()
+        if current["status"] == "paused":
+            raise StateError("workflow is paused; use adt resume")
+        if current["status"] != "active":
+            self.store.update_workflow("active", current["current_stage"])
+        return self.status()
+
+    def pause(self) -> dict[str, Any]:
+        current = self.status()
+        if current["status"] != "active":
+            raise StateError("only an active workflow can be paused")
+        self.store.update_workflow("paused", current["current_stage"])
+        self.store.create_checkpoint("pause")
+        return self.status()
+
+    def stop(self) -> dict[str, Any]:
+        current = self.status()
+        if current["status"] not in {"active", "paused"}:
+            raise StateError("only an active or paused workflow can be stopped")
+        self.store.update_workflow("stopped", current["current_stage"])
+        self.store.create_checkpoint("stop")
+        return self.status()
+
+    def resume(self) -> dict[str, Any]:
+        current = self.status()
+        if current["status"] not in {"paused", "stopped"}:
+            raise StateError("only a paused or stopped workflow can be resumed")
+        checkpoint = self.store.validate_latest_checkpoint()
+        if checkpoint is None:
+            raise StateError("cannot resume without a valid checkpoint")
+        checkpoint_stage = checkpoint["workflow"]["current_stage"]
+        if checkpoint_stage not in STAGES:
+            raise StateError(f"checkpoint contains an unknown workflow stage: {checkpoint_stage}")
+        self.store.update_workflow("active", checkpoint_stage)
+        return self.status()
+
+    def continue_workflow(self) -> dict[str, Any]:
+        current = self.status()
+        if current["status"] != "active":
+            raise StateError("workflow must be active before it can continue")
+        stage = current["current_stage"]
+        if stage not in STAGES:
+            raise StateError(f"runtime contains an unknown workflow stage: {stage}")
+        if stage in APPROVAL_STAGES and self.store.approval_status(stage) != "approved":
+            raise StateError(f"stage requires approval before continuing: {stage}")
+        index = STAGES.index(stage)
+        next_stage = STAGES[min(index + 1, len(STAGES) - 1)]
+        next_status = "completed" if next_stage == "completed" else "active"
+        self.store.update_workflow(next_status, next_stage)
+        self.store.create_checkpoint("stage_transition")
+        return self.status()
+
+    def approve(self, stage: str) -> None:
+        if stage not in STAGES:
+            raise StateError(f"unknown workflow stage: {stage}")
+        self.store.set_approval(stage, "approved")
+
+    def revise(self, stage: str, feedback: str) -> None:
+        if stage not in STAGES:
+            raise StateError(f"unknown workflow stage: {stage}")
+        if not feedback.strip():
+            raise StateError("revision feedback cannot be blank")
+        self.store.set_approval(stage, "revision_requested", feedback.strip())

agentic_framework/exceptions.py

@@ -0,0 +1,22 @@
+"""Framework-specific exceptions."""
+
+
+class AgenticFrameworkError(Exception):
+    """Base class for expected framework errors."""
+
+
+class ConfigurationError(AgenticFrameworkError):
+    """Raised when configuration cannot be read or validated."""
+
+
+class InitializationError(AgenticFrameworkError):
+    """Raised when a target project cannot be initialized safely."""
+
+
+class RequirementsError(AgenticFrameworkError):
+    """Raised when requirements cannot be versioned safely."""
+
+
+class StateError(AgenticFrameworkError):
+    """Raised when persistent runtime state is invalid or a transition is unsafe."""
+

agentic_framework/logging.py

@@ -0,0 +1,70 @@
+"""Console and JSONL event logging utilities."""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+_MANAGED_HANDLER = "_agentic_framework_handler"
+
+
+class JsonLineFormatter(logging.Formatter):
+    """Render each log record as one machine-readable JSON object."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "timestamp": datetime.fromtimestamp(record.created, tz=UTC).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        event_data = getattr(record, "event_data", None)
+        if event_data:
+            payload["event"] = event_data
+        if record.exc_info:
+            payload["exception"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False, separators=(",", ":"), default=str)
+
+
+def _managed(handler: logging.Handler) -> logging.Handler:
+    setattr(handler, _MANAGED_HANDLER, True)
+    return handler
+
+
+def configure_logging(
+    *,
+    level: str | int = logging.INFO,
+    event_log: Path | None = None,
+) -> logging.Logger:
+    """Configure ADF logging without disturbing handlers owned by the host application."""
+
+    logger = logging.getLogger("agentic_framework")
+    logger.setLevel(level)
+    logger.propagate = False
+
+    for handler in list(logger.handlers):
+        if getattr(handler, _MANAGED_HANDLER, False):
+            handler.close()
+            logger.removeHandler(handler)
+
+    console = _managed(logging.StreamHandler())
+    console.setFormatter(logging.Formatter("%(levelname)s %(name)s: %(message)s"))
+    logger.addHandler(console)
+
+    if event_log is not None:
+        event_log.parent.mkdir(parents=True, exist_ok=True)
+        jsonl = _managed(logging.FileHandler(event_log, encoding="utf-8"))
+        jsonl.setFormatter(JsonLineFormatter())
+        logger.addHandler(jsonl)
+
+    return logger
+
+
+def log_event(logger: logging.Logger, message: str, **event_data: Any) -> None:
+    """Record a normal log message with optional structured event fields."""
+
+    logger.info(message, extra={"event_data": event_data})
+

agentic_framework/requirements_manager/__init__.py

@@ -0,0 +1,8 @@
+"""Requirements ingestion, immutable versioning, and comparison."""
+
+from agentic_framework.requirements_manager.ingestion import (
+    IngestionResult,
+    RequirementsManager,
+)
+
+__all__ = ["IngestionResult", "RequirementsManager"]