a2c-core 0.2.1__py3-none-any.whl

a2c_core/__init__.py

@@ -0,0 +1,3 @@
+"""A2C engine — domain logic, schemas, services, and workflow orchestration."""
+
+__version__ = "0.2.1"

a2c_core/contracts/__init__.py

@@ -0,0 +1,61 @@
+"""Repository artifact contracts — paths, naming, inventory."""
+
+from a2c_core.contracts.inventory import M2_ARTIFACTS, ArtifactSpec
+from a2c_core.contracts.naming import (
+    ADR_FILENAME_PATTERN,
+    ADR_STATUS_PATTERN,
+    EPIC_ID_PATTERN,
+    SPRINT_ID_PATTERN,
+    TASK_ID_PATTERN,
+    WORKFLOW_ID_PATTERN,
+    is_valid_adr_filename,
+    is_valid_epic_id,
+    is_valid_sprint_id,
+    is_valid_task_id,
+    is_valid_workflow_id,
+    parse_adr_filename,
+)
+from a2c_core.contracts.paths import (
+    A2C_DIR,
+    ADR_DIR,
+    CONFIG_FILE,
+    DOCS_DIR,
+    EPICS_DIR,
+    PLANNING_DIR,
+    ROOT_MARKERS,
+    SPRINTS_DIR,
+    TASKS_DIR,
+    WORKFLOW_MANIFEST,
+)
+
+__all__ = [
+    "A2C_DIR",
+    "ADR_DIR",
+    "ADR_FILENAME_PATTERN",
+    "ADR_STATUS_PATTERN",
+    "ARTIFACT_SCHEMA_VERSION",
+    "CONFIG_FILE",
+    "CONFIG_SCHEMA_VERSION",
+    "DOCS_DIR",
+    "EPICS_DIR",
+    "EPIC_ID_PATTERN",
+    "M2_ARTIFACTS",
+    "PLANNING_DIR",
+    "ROOT_MARKERS",
+    "SPRINTS_DIR",
+    "SPRINT_ID_PATTERN",
+    "TASKS_DIR",
+    "TASK_ID_PATTERN",
+    "WORKFLOW_ID_PATTERN",
+    "WORKFLOW_MANIFEST",
+    "ArtifactSpec",
+    "is_valid_adr_filename",
+    "is_valid_epic_id",
+    "is_valid_sprint_id",
+    "is_valid_task_id",
+    "is_valid_workflow_id",
+    "parse_adr_filename",
+]
+
+# Re-export version constants from paths
+from a2c_core.contracts.paths import ARTIFACT_SCHEMA_VERSION, CONFIG_SCHEMA_VERSION  # noqa: E402

a2c_core/contracts/id_format.py

@@ -0,0 +1,40 @@
+"""Planning artifact ID shape and configurable format validation."""
+
+from __future__ import annotations
+
+import re
+
+# Shipped default when id_format.enabled is true and pattern is omitted.
+DEFAULT_ID_FORMAT_PATTERN = r"^[A-Z][A-Z0-9]{1,9}-[0-9]+$"
+
+# Loose Jira-like recommendation for non-fatal warnings when strict mode is off.
+RECOMMENDED_ID_SHAPE_PATTERN = r"^[A-Z][A-Z0-9]+-[0-9]+$"
+
+_RECOMMENDED_SHAPE = re.compile(RECOMMENDED_ID_SHAPE_PATTERN)
+
+
+def compile_id_pattern(pattern: str) -> re.Pattern[str]:
+    """Compile a configured ID format pattern."""
+    return re.compile(pattern)
+
+
+def id_matches_pattern(artifact_id: str, pattern: str) -> bool:
+    """Return True when artifact_id matches the configured regex pattern."""
+    return bool(compile_id_pattern(pattern).fullmatch(artifact_id))
+
+
+def is_recommended_id_shape(artifact_id: str) -> bool:
+    """Return True when artifact_id matches the documented Jira-like recommendation."""
+    return bool(_RECOMMENDED_SHAPE.fullmatch(artifact_id))
+
+
+def looks_like_odd_id(artifact_id: str) -> bool:
+    """Heuristic for IDs that may deserve a shape warning (spaces, empty, etc.)."""
+    stripped = artifact_id.strip()
+    if not stripped:
+        return True
+    if stripped != artifact_id:
+        return True
+    if " " in artifact_id:
+        return True
+    return not is_recommended_id_shape(artifact_id)

a2c_core/contracts/inventory.py

@@ -0,0 +1,60 @@
+"""Supported artifact inventory for Milestone 2."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactSpec:
+    kind: str
+    relative_dir: str
+    filename_pattern: str
+    schema_file: str
+    model: str
+
+
+M2_ARTIFACTS: tuple[ArtifactSpec, ...] = (
+    ArtifactSpec(
+        kind="config",
+        relative_dir=".a2c",
+        filename_pattern="config.yaml",
+        schema_file="config.schema.json",
+        model="a2c_core.schemas.config.A2CConfig",
+    ),
+    ArtifactSpec(
+        kind="workflow_manifest",
+        relative_dir="docs",
+        filename_pattern="workflow-manifest.yaml",
+        schema_file="workflow-manifest.schema.json",
+        model="a2c_core.schemas.metadata.WorkflowManifest",
+    ),
+    ArtifactSpec(
+        kind="epic",
+        relative_dir="planning/epics",
+        filename_pattern="*.md",
+        schema_file="epic.schema.json",
+        model="a2c_core.schemas.artifacts.Epic",
+    ),
+    ArtifactSpec(
+        kind="task",
+        relative_dir="planning/tasks",
+        filename_pattern="*.md",
+        schema_file="task.schema.json",
+        model="a2c_core.schemas.artifacts.Task",
+    ),
+    ArtifactSpec(
+        kind="sprint",
+        relative_dir="planning/sprints",
+        filename_pattern="*.md",
+        schema_file="sprint.schema.json",
+        model="a2c_core.schemas.artifacts.Sprint",
+    ),
+    ArtifactSpec(
+        kind="adr",
+        relative_dir="docs/adr",
+        filename_pattern="NNNN-*.md",
+        schema_file="",
+        model="a2c_core.schemas.metadata.AdrRecord",
+    ),
+)

a2c_core/contracts/naming.py

@@ -0,0 +1,40 @@
+"""Identifier and filename conventions (contract C2)."""
+
+from __future__ import annotations
+
+import re
+
+WORKFLOW_ID_PATTERN = re.compile(r"^[a-z][a-z0-9_]*$")
+EPIC_ID_PATTERN = re.compile(r"^epic-[a-z0-9]+(?:-[a-z0-9]+)*$")
+TASK_ID_PATTERN = re.compile(r"^task-[a-z0-9]+(?:-[a-z0-9]+)*$")
+SPRINT_ID_PATTERN = re.compile(r"^sprint-[a-z0-9]+(?:-[a-z0-9]+)*$")
+ADR_FILENAME_PATTERN = re.compile(r"^\d{4}-[a-z0-9]+(?:-[a-z0-9]+)*\.md$")
+ADR_STATUS_PATTERN = re.compile(r"^\s*(?:-\s*)?\*\*Status:\*\*\s*(.+)$", re.MULTILINE)
+
+
+def is_valid_workflow_id(value: str) -> bool:
+    return bool(WORKFLOW_ID_PATTERN.fullmatch(value))
+
+
+def is_valid_epic_id(value: str) -> bool:
+    return bool(EPIC_ID_PATTERN.fullmatch(value))
+
+
+def is_valid_task_id(value: str) -> bool:
+    return bool(TASK_ID_PATTERN.fullmatch(value))
+
+
+def is_valid_sprint_id(value: str) -> bool:
+    return bool(SPRINT_ID_PATTERN.fullmatch(value))
+
+
+def is_valid_adr_filename(name: str) -> bool:
+    return bool(ADR_FILENAME_PATTERN.fullmatch(name))
+
+
+def parse_adr_filename(name: str) -> tuple[int, str] | None:
+    if not is_valid_adr_filename(name):
+        return None
+    number_text, slug_with_ext = name.split("-", 1)
+    slug = slug_with_ext.removesuffix(".md")
+    return int(number_text), slug

a2c_core/contracts/paths.py

@@ -0,0 +1,48 @@
+"""Repository path conventions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Tool-internal storage (config, caches, indexes — not human-facing planning artifacts)
+A2C_DIR = ".a2c"
+CONFIG_FILE = Path(A2C_DIR) / "config.yaml"
+A2C_CACHE_DIR = Path(A2C_DIR) / "cache"
+DECOMPOSE_EPIC_CACHE_DIR = A2C_CACHE_DIR / "decompose-epic"
+CREATE_EPIC_CACHE_DIR = A2C_CACHE_DIR / "create-epic"
+CREATE_TASK_CACHE_DIR = A2C_CACHE_DIR / "create-task"
+A2C_INDEXES_DIR = Path(A2C_DIR) / "indexes"
+
+# Human-facing planning artifacts (Markdown + YAML front matter)
+PLANNING_DIR = Path("planning")
+EPICS_DIR = PLANNING_DIR / "epics"
+TASKS_DIR = PLANNING_DIR / "tasks"
+SPRINTS_DIR = PLANNING_DIR / "sprints"
+
+PLANNING_ARTIFACT_EXTENSION = ".md"
+LEGACY_PLANNING_ARTIFACT_EXTENSION = ".yaml"
+
+# Deprecated location — transitional loader support only
+LEGACY_PLANNING_DIR = Path(A2C_DIR) / "planning"
+LEGACY_EPICS_DIR = LEGACY_PLANNING_DIR / "epics"
+LEGACY_TASKS_DIR = LEGACY_PLANNING_DIR / "tasks"
+LEGACY_SPRINTS_DIR = LEGACY_PLANNING_DIR / "sprints"
+
+DOCS_DIR = Path("docs")
+WORKFLOW_MANIFEST = DOCS_DIR / "workflow-manifest.yaml"
+ADR_DIR = DOCS_DIR / "adr"
+
+# Markers used to recognize an A2C-governed repository root
+ROOT_MARKERS = (
+    Path("AGENTS.md"),
+    WORKFLOW_MANIFEST,
+    CONFIG_FILE,
+)
+
+ARTIFACT_SCHEMA_VERSION = 1
+CONFIG_SCHEMA_VERSION = 1
+
+
+def planning_artifact_path(directory: Path, artifact_id: str) -> str:
+    """Canonical relative path for a planning artifact Markdown file."""
+    return str(directory / f"{artifact_id}{PLANNING_ARTIFACT_EXTENSION}")

a2c_core/contracts/task_ids.py

@@ -0,0 +1,31 @@
+"""Task ID helpers for single-task intake."""
+
+from __future__ import annotations
+
+import re
+
+PENDING_TASK_ID = "draft-pending"
+_SLUG_WORD_RE = re.compile(r"[a-z0-9]+")
+
+
+def slug_from_text(text: str, *, max_parts: int = 5) -> str:
+    words = _SLUG_WORD_RE.findall(text.lower())
+    if not words:
+        return "task"
+    return "-".join(words[:max_parts])
+
+
+def draft_key_from_title(title: str) -> str:
+    """Stable cache key for a task intake draft (not the final task id)."""
+    return slug_from_text(title)
+
+
+def allocate_task_id(title: str, *, existing_ids: set[str]) -> str:
+    """Allocate the next collision-free task id from a title slug."""
+    base = f"task-{slug_from_text(title)}"
+    candidate = base
+    suffix = 2
+    while candidate in existing_ids:
+        candidate = f"{base}-{suffix}"
+        suffix += 1
+    return candidate

a2c_core/errors/__init__.py

@@ -0,0 +1,62 @@
+"""Typed errors and structured issue records."""
+
+from a2c_core.errors.codes import (
+    A2C_CONFIG_001,
+    A2C_FORMAT_001,
+    A2C_FORMAT_002,
+    A2C_ID_001,
+    A2C_ID_002,
+    A2C_ID_003,
+    A2C_NAME_001,
+    A2C_NAME_002,
+    A2C_NAME_003,
+    A2C_NAME_004,
+    A2C_PROVIDER_001,
+    A2C_PROVIDER_002,
+    A2C_PROVIDER_003,
+    A2C_PROVIDER_004,
+    A2C_PROVIDER_005,
+    A2C_REPO_001,
+    A2C_REPO_002,
+    A2C_REPO_003,
+    A2C_SCHEMA_001,
+    A2C_SCHEMA_002,
+    A2C_SCHEMA_003,
+    A2C_SCHEMA_004,
+    A2C_WORKFLOW_001,
+    A2C_WORKFLOW_002,
+    A2C_WORKFLOW_003,
+    A2C_WORKFLOW_004,
+)
+from a2c_core.errors.issues import Severity, ValidationIssue
+
+__all__ = [
+    "A2C_CONFIG_001",
+    "A2C_FORMAT_001",
+    "A2C_FORMAT_002",
+    "A2C_ID_001",
+    "A2C_ID_002",
+    "A2C_ID_003",
+    "A2C_NAME_001",
+    "A2C_NAME_002",
+    "A2C_NAME_003",
+    "A2C_NAME_004",
+    "A2C_REPO_001",
+    "A2C_REPO_002",
+    "A2C_REPO_003",
+    "A2C_SCHEMA_001",
+    "A2C_SCHEMA_002",
+    "A2C_SCHEMA_003",
+    "A2C_SCHEMA_004",
+    "A2C_WORKFLOW_001",
+    "A2C_WORKFLOW_002",
+    "A2C_WORKFLOW_003",
+    "A2C_WORKFLOW_004",
+    "A2C_PROVIDER_001",
+    "A2C_PROVIDER_002",
+    "A2C_PROVIDER_003",
+    "A2C_PROVIDER_004",
+    "A2C_PROVIDER_005",
+    "Severity",
+    "ValidationIssue",
+]

a2c_core/errors/codes.py

@@ -0,0 +1,43 @@
+"""Stable A2C error code constants (contract C2)."""
+
+from __future__ import annotations
+
+# Schema / parsing
+A2C_SCHEMA_001 = "A2C_SCHEMA_001"  # invalid document shape
+A2C_SCHEMA_002 = "A2C_SCHEMA_002"  # unsupported document version
+A2C_SCHEMA_003 = "A2C_SCHEMA_003"  # YAML/JSON parse failure
+A2C_FORMAT_001 = "A2C_FORMAT_001"  # legacy pure-YAML planning artifact
+A2C_FORMAT_002 = "A2C_FORMAT_002"  # deprecated .a2c/planning/ location
+
+# Naming / identifiers
+A2C_NAME_001 = "A2C_NAME_001"  # invalid artifact id
+A2C_NAME_002 = "A2C_NAME_002"  # invalid ADR filename
+A2C_NAME_003 = "A2C_NAME_003"  # invalid workflow id
+A2C_NAME_004 = "A2C_NAME_004"  # filename does not match artifact id (warning)
+
+# Planning artifact IDs
+A2C_ID_001 = "A2C_ID_001"  # id does not match configured pattern
+A2C_ID_002 = "A2C_ID_002"  # duplicate planning artifact id
+A2C_ID_003 = "A2C_ID_003"  # recommended id shape suggestion (warning)
+A2C_SCHEMA_004 = "A2C_SCHEMA_004"  # planning artifact type mismatch
+
+# Repository layout
+A2C_REPO_001 = "A2C_REPO_001"  # not an A2C repository root
+A2C_REPO_002 = "A2C_REPO_002"  # required artifact missing
+A2C_REPO_003 = "A2C_REPO_003"  # artifact reference broken
+
+# Config
+A2C_CONFIG_001 = "A2C_CONFIG_001"  # invalid config file
+
+# AI workflow / decomposition
+A2C_WORKFLOW_001 = "A2C_WORKFLOW_001"  # no valid proposal available
+A2C_WORKFLOW_002 = "A2C_WORKFLOW_002"  # invalid AI / proposal structure
+A2C_WORKFLOW_003 = "A2C_WORKFLOW_003"  # task id conflict on apply
+A2C_WORKFLOW_004 = "A2C_WORKFLOW_004"  # epic not found for decomposition
+
+# LLM provider integration
+A2C_PROVIDER_001 = "A2C_PROVIDER_001"  # provider misconfiguration
+A2C_PROVIDER_002 = "A2C_PROVIDER_002"  # provider HTTP / transport failure
+A2C_PROVIDER_003 = "A2C_PROVIDER_003"  # provider timeout
+A2C_PROVIDER_004 = "A2C_PROVIDER_004"  # unknown provider name
+A2C_PROVIDER_005 = "A2C_PROVIDER_005"  # malformed model response

a2c_core/errors/issues.py

@@ -0,0 +1,24 @@
+"""Structured validation and service issues."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Severity = Literal["error", "warning"]
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationIssue:
+    """Machine-consumable issue for CLI/TUI presentation."""
+
+    code: str
+    message: str
+    path: str | None = None
+    severity: Severity = "error"
+
+    def to_dict(self) -> dict[str, str]:
+        data: dict[str, str] = {"code": self.code, "message": self.message}
+        if self.path is not None:
+            data["path"] = self.path
+        return data

a2c_core/schemas/__init__.py

@@ -0,0 +1,29 @@
+"""Pydantic models for A2C repository artifacts and results."""
+
+from a2c_core.schemas.artifacts import Epic, EpicStatus, Sprint, SprintStatus, Task, TaskStatus
+from a2c_core.schemas.config import A2CConfig, CoreSettings, LogLevel, WorkflowSettings
+from a2c_core.schemas.metadata import AdrRecord, ProfilePointer, WorkflowManifest, WorkflowOwner
+from a2c_core.schemas.results import CliResultEnvelope, ServiceResult
+from a2c_core.schemas.workflows_io import ApprovedProposal, CommitPlanItem, CommitPlanProposal
+
+__all__ = [
+    "A2CConfig",
+    "AdrRecord",
+    "ApprovedProposal",
+    "CliResultEnvelope",
+    "CommitPlanItem",
+    "CommitPlanProposal",
+    "CoreSettings",
+    "Epic",
+    "EpicStatus",
+    "LogLevel",
+    "ProfilePointer",
+    "ServiceResult",
+    "Sprint",
+    "SprintStatus",
+    "Task",
+    "TaskStatus",
+    "WorkflowManifest",
+    "WorkflowOwner",
+    "WorkflowSettings",
+]

a2c_core/schemas/artifacts.py

@@ -0,0 +1,54 @@
+"""Planning artifact models — Epic, Task, Sprint (Milestone 2 minimum set)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+EpicStatus = Literal["draft", "active", "complete", "cancelled"]
+TaskStatus = Literal["todo", "in_progress", "done", "blocked"]
+SprintStatus = Literal["planned", "active", "closed"]
+
+
+class Epic(BaseModel):
+    """Epic artifact (`planning/epics/<id>.md` with YAML front matter)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    version: Literal[1] = 1
+    type: Literal["epic"]
+    id: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    status: EpicStatus = "draft"
+    summary: str | None = None
+    task_ids: list[str] = Field(default_factory=list)
+    body: str = ""
+
+
+class Task(BaseModel):
+    """Task artifact (`planning/tasks/<id>.md` with YAML front matter)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    version: Literal[1] = 1
+    type: Literal["task"]
+    id: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    status: TaskStatus = "todo"
+    epic_id: str | None = None
+    body: str = ""
+
+
+class Sprint(BaseModel):
+    """Sprint artifact (`planning/sprints/<id>.md` with YAML front matter)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    version: Literal[1] = 1
+    type: Literal["sprint"]
+    id: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    status: SprintStatus = "planned"
+    task_ids: list[str] = Field(default_factory=list)
+    body: str = ""

a2c_core/schemas/config.py

@@ -0,0 +1,74 @@
+"""Repository configuration models (contract C3)."""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from a2c_core.contracts.id_format import DEFAULT_ID_FORMAT_PATTERN
+
+LogLevel = Literal["debug", "info", "warning", "error"]
+DecompositionProviderName = Literal["mock", "openai", "local", "ollama"]
+
+
+class CoreSettings(BaseModel):
+    """Core runtime preferences."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    log_level: LogLevel = "info"
+
+
+class WorkflowSettings(BaseModel):
+    """Workflow execution preferences."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    approval_required: bool = True
+    default_profile: str | None = None
+
+
+class IdFormatSettings(BaseModel):
+    """Optional strict planning artifact ID regex validation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    pattern: str = DEFAULT_ID_FORMAT_PATTERN
+
+    @field_validator("pattern")
+    @classmethod
+    def pattern_must_compile(cls, value: str) -> str:
+        re.compile(value)
+        return value
+
+
+class DecompositionSettings(BaseModel):
+    """Epic decomposition LLM provider settings."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    provider: DecompositionProviderName = "mock"
+    model: str | None = None
+    endpoint: str | None = None
+    timeout_seconds: float = Field(default=120.0, gt=0)
+    max_tokens: int | None = Field(default=4096, gt=0)
+    temperature: float = Field(default=0.2, ge=0.0, le=2.0)
+
+
+class A2CConfig(BaseModel):
+    """Project-local `.a2c/config.yaml` (version 1)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    version: Literal[1] = 1
+    core: CoreSettings = Field(default_factory=CoreSettings)
+    workflows: WorkflowSettings = Field(default_factory=WorkflowSettings)
+    id_format: IdFormatSettings = Field(default_factory=IdFormatSettings)
+    decomposition: DecompositionSettings = Field(default_factory=DecompositionSettings)
+
+    @classmethod
+    def defaults(cls) -> A2CConfig:
+        return cls()

a2c_core/schemas/metadata.py

@@ -0,0 +1,45 @@
+"""Workflow and repository metadata models (contract C1)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class WorkflowOwner(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    contact: str | None = None
+    gitlab_group: str | None = None
+
+
+class WorkflowManifest(BaseModel):
+    """`docs/workflow-manifest.yaml` shape (subset for validation)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    version: int
+    workflow_id: str
+    display_title: str | None = None
+    source_docs_path: str = "docs"
+    required_metadata_files: list[str] = Field(default_factory=list)
+
+
+class AdrRecord(BaseModel):
+    """Parsed ADR file metadata."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    number: int
+    slug: str
+    filename: str
+    status: str | None = None
+    title: str | None = None
+
+
+class ProfilePointer(BaseModel):
+    """Reference to a stack profile."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    profile_id: str
+    overrides: dict[str, str] = Field(default_factory=dict)