arkaos 2.13.0 → 2.15.0

package/core/forge/schema.py

@@ -0,0 +1,213 @@
+"""Forge schema — Pydantic models and enums for the ArkaOS Intelligent Planning Engine.
+
+The Forge analyses incoming requests, scores complexity across five dimensions,
+selects the appropriate execution tier (shallow / standard / deep), and emits a
+structured ForgePlan that downstream agents consume.
+"""
+
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+class ForgeTier(str, Enum):
+    """Execution tier determined by complexity score."""
+    SHALLOW = "shallow"
+    STANDARD = "standard"
+    DEEP = "deep"
+
+
+class ForgeStatus(str, Enum):
+    """Lifecycle status of a ForgePlan."""
+    DRAFT = "draft"
+    REVIEWING = "reviewing"
+    APPROVED = "approved"
+    EXECUTING = "executing"
+    COMPLETED = "completed"
+    REJECTED = "rejected"
+    CANCELLED = "cancelled"
+    ARCHIVED = "archived"
+
+
+class ExplorerLens(str, Enum):
+    """The analytical perspective used when exploring a plan."""
+    PRAGMATIC = "pragmatic"          # Focus on fastest viable path
+    ARCHITECTURAL = "architectural"  # Focus on long-term design health
+    CONTRARIAN = "contrarian"        # Challenge assumptions, surface risks
+
+
+class RiskSeverity(str, Enum):
+    """Severity level for identified risks."""
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class ExecutionPathType(str, Enum):
+    """Type of execution artefact that fulfils a plan step."""
+    SKILL = "skill"
+    WORKFLOW = "workflow"
+    ENTERPRISE_WORKFLOW = "enterprise_workflow"
+
+
+# ---------------------------------------------------------------------------
+# Models
+# ---------------------------------------------------------------------------
+
+class ComplexityDimensions(BaseModel):
+    """Five-axis complexity breakdown, each scored 0–100."""
+
+    scope: int = Field(default=0, description="Breadth of change across the codebase or system.")
+    dependencies: int = Field(default=0, description="Number and criticality of upstream/downstream dependencies.")
+    ambiguity: int = Field(default=0, description="How unclear or under-specified the requirements are.")
+    risk: int = Field(default=0, description="Potential for breakage, data loss, or security impact.")
+    novelty: int = Field(default=0, description="How unlike existing patterns this work is.")
+
+    @field_validator("scope", "dependencies", "ambiguity", "risk", "novelty", mode="before")
+    @classmethod
+    def clamp_to_range(cls, v: int) -> int:
+        """Clamp dimension value to [0, 100]."""
+        return max(0, min(100, int(v)))
+
+
+class ComplexityScore(BaseModel):
+    """Aggregated complexity result produced by the Complexity Scorer."""
+
+    score: int = Field(default=0, description="Composite 0–100 score derived from all dimensions.")
+    tier: ForgeTier = Field(default=ForgeTier.SHALLOW, description="Execution tier selected based on the composite score.")
+    dimensions: ComplexityDimensions = Field(default_factory=ComplexityDimensions, description="Per-dimension breakdown.")
+    similar_plans: List[str] = Field(
+        default_factory=list,
+        description="IDs of previously completed plans with similar profiles.",
+    )
+    reused_patterns: List[str] = Field(
+        default_factory=list,
+        description="Named patterns from the ArkaOS pattern library reused in this plan.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Approach & Critic Models
+# ---------------------------------------------------------------------------
+
+class KeyDecision(BaseModel):
+    """A single decision made during exploration."""
+    decision: str
+    rationale: str = ""
+
+
+class PhaseDeliverable(BaseModel):
+    """A deliverable within a plan phase."""
+    name: str
+    deliverables: list[str] = Field(default_factory=list)
+    effort: str = "medium"
+
+
+class ExplorerApproach(BaseModel):
+    """Output from a single explorer agent."""
+    explorer: ExplorerLens
+    summary: str = ""
+    key_decisions: list[KeyDecision] = Field(default_factory=list)
+    phases: list[PhaseDeliverable] = Field(default_factory=list)
+    estimated_total_effort: str = "medium"
+    risks: list[str] = Field(default_factory=list)
+    reuses_patterns: list[str] = Field(default_factory=list)
+
+
+class RejectedElement(BaseModel):
+    """An element rejected by the critic with reason."""
+    element: str
+    reason: str
+
+
+class IdentifiedRisk(BaseModel):
+    """A risk identified by the critic with mitigation."""
+    risk: str
+    mitigation: str = ""
+    severity: RiskSeverity = RiskSeverity.LOW
+
+
+class CriticVerdict(BaseModel):
+    """Synthesis output from the Plan Critic."""
+    synthesis: dict[str, list[str]] = Field(default_factory=dict)
+    rejected_elements: list[RejectedElement] = Field(default_factory=list)
+    risks: list[IdentifiedRisk] = Field(default_factory=list)
+    confidence: float = 0.0
+    estimated_phases: int = 0
+    estimated_departments: list[str] = Field(default_factory=list)
+
+    def is_valid(self) -> bool:
+        """Check critic rules: must reject >= 1 and identify >= 1 risk."""
+        return len(self.rejected_elements) >= 1 and len(self.risks) >= 1
+
+
+# ---------------------------------------------------------------------------
+# ForgePlan and Context Models
+# ---------------------------------------------------------------------------
+
+class ForgeContext(BaseModel):
+    """Snapshot of repo state when forge was initiated."""
+    repo: str
+    branch: str
+    commit_at_forge: str
+    arkaos_version: str
+    prompt: str
+    context_refreshed: bool = False
+
+
+class PlanPhase(BaseModel):
+    """A single phase in the forge plan."""
+    name: str
+    department: str
+    agents: list[str] = Field(default_factory=list)
+    deliverables: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    depends_on: list[str] = Field(default_factory=list)
+    context_from_forge: dict[str, list[str]] = Field(default_factory=dict)
+
+
+class ExecutionPath(BaseModel):
+    """How the plan will be executed after approval."""
+    type: ExecutionPathType = ExecutionPathType.SKILL
+    target: str = ""
+    departments: list[str] = Field(default_factory=list)
+    estimated_commits: int = 0
+
+
+class ForgeGovernance(BaseModel):
+    """Governance metadata for a forge plan."""
+    constitution_check: str = "pending"
+    violations: list[str] = Field(default_factory=list)
+    quality_gate_required: bool = True
+    branch_strategy: str = ""
+
+
+class ForgePlan(BaseModel):
+    """Complete forge plan — the primary artifact of The Forge."""
+    id: str
+    name: str
+    created_at: str = ""
+    forged_by: str = ""
+    version: int = 1
+
+    context: ForgeContext
+    complexity: ComplexityScore = Field(default_factory=ComplexityScore)
+    approaches: list[ExplorerApproach] = Field(default_factory=list)
+    critic: CriticVerdict = Field(default_factory=CriticVerdict)
+
+    plan_phases: list[PlanPhase] = Field(default_factory=list)
+    goal: str = ""
+    execution_path: ExecutionPath = Field(default_factory=ExecutionPath)
+
+    governance: ForgeGovernance = Field(default_factory=ForgeGovernance)
+
+    status: ForgeStatus = ForgeStatus.DRAFT
+    approved_at: Optional[str] = None
+    approved_by: Optional[str] = None
+    executed_at: Optional[str] = None
+    completion_notes: Optional[str] = None

package/core/synapse/__init__.py

@@ -5,7 +5,7 @@ and 65% context reduction through intelligent filtering.
 """
 
 from core.synapse.engine import SynapseEngine
-from core.synapse.layers import Layer, LayerResult
+from core.synapse.layers import Layer, LayerResult, ForgeContextLayer
 from core.synapse.cache import LayerCache
 
-__all__ = ["SynapseEngine", "Layer", "LayerResult", "LayerCache"]
+__all__ = ["SynapseEngine", "Layer", "LayerResult", "LayerCache", "ForgeContextLayer"]

package/core/synapse/engine.py

@@ -28,7 +28,7 @@ class SynapseResult:
 
 
 class SynapseEngine:
-    """8-layer context injection engine.
+    """9-layer context injection engine.
 
     Computes all registered layers, caches results per TTL,
     filters empty results, and combines into a compact context string.
@@ -155,7 +155,7 @@ def create_default_engine(
     agents_registry: dict[str, dict] | None = None,
     vector_store: Any = None,
 ) -> SynapseEngine:
-    """Create a SynapseEngine with all 8 default layers.
+    """Create a SynapseEngine with all 9 default layers.
 
     Args:
         constitution_compressed: Compressed Constitution string for L0.
@@ -169,6 +169,7 @@ def create_default_engine(
         ConstitutionLayer, DepartmentLayer, AgentLayer,
         ProjectLayer, BranchLayer, CommandHintsLayer,
         QualityGateLayer, TimeLayer, KnowledgeRetrievalLayer,
+        ForgeContextLayer,
     )
 
     engine = SynapseEngine()
@@ -184,5 +185,6 @@ def create_default_engine(
     engine.register_layer(CommandHintsLayer(commands=commands))
     engine.register_layer(QualityGateLayer())
     engine.register_layer(TimeLayer())
+    engine.register_layer(ForgeContextLayer())
 
     return engine

package/core/synapse/layers.py

@@ -525,3 +525,52 @@ class KnowledgeRetrievalLayer(Layer):
             layer_id=self.id, tag=tag, content=content,
             tokens_est=total_tokens, compute_ms=ms, cached=False,
         )
+
+
+# --- L8: Forge Context ---
+
+class ForgeContextLayer(Layer):
+    """L8: Active forge plan context — decisions, risks, rejected approaches."""
+
+    @property
+    def id(self) -> str:
+        return "L8"
+
+    @property
+    def name(self) -> str:
+        return "ForgeContext"
+
+    @property
+    def cache_ttl(self) -> int:
+        return 0
+
+    @property
+    def priority(self) -> int:
+        return 80
+
+    def compute(self, ctx: PromptContext) -> LayerResult:
+        start = time.time()
+        try:
+            from core.forge.persistence import get_active_plan
+            plan = get_active_plan()
+        except Exception:
+            plan = None
+        if plan is None:
+            return LayerResult(layer_id=self.id, tag="", content="", tokens_est=0, compute_ms=0, cached=False)
+        tag = f"[forge:{plan.id}]"
+        parts = [f"Forge plan: {plan.id} ({plan.status.value})"]
+        if plan.critic.confidence > 0:
+            decisions = []
+            for source, elements in plan.critic.synthesis.items():
+                decisions.extend(elements)
+            if decisions:
+                parts.append(f"Decisions: {'; '.join(decisions[:5])}")
+            rejected = [r.element for r in plan.critic.rejected_elements]
+            if rejected:
+                parts.append(f"Rejected: {'; '.join(rejected[:3])}")
+            risks = [r.risk for r in plan.critic.risks]
+            if risks:
+                parts.append(f"Risks: {'; '.join(risks[:3])}")
+        content = " | ".join(parts)
+        ms = int((time.time() - start) * 1000)
+        return LayerResult(layer_id=self.id, tag=tag, content=content, tokens_est=len(content.split()), compute_ms=ms, cached=False)

package/core/sync/__init__.py

@@ -0,0 +1,25 @@
+"""ArkaOS Sync Engine — Hybrid sync for /arka update."""
+
+from core.sync.engine import run_sync
+from core.sync.schema import (
+    ChangeManifest,
+    DescriptorSyncResult,
+    FeatureSpec,
+    McpSyncResult,
+    Project,
+    SettingsSyncResult,
+    SkillSyncResult,
+    SyncReport,
+)
+
+__all__ = [
+    "run_sync",
+    "ChangeManifest",
+    "DescriptorSyncResult",
+    "FeatureSpec",
+    "McpSyncResult",
+    "Project",
+    "SettingsSyncResult",
+    "SkillSyncResult",
+    "SyncReport",
+]

package/core/sync/descriptor_syncer.py

@@ -0,0 +1,166 @@
+"""Descriptor syncer for the ArkaOS Sync Engine.
+
+Syncs project descriptor YAML frontmatter: auto-pauses inactive projects,
+archives missing paths, and updates detected stacks.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from core.sync.schema import DescriptorSyncResult, Project
+
+_PAUSE_THRESHOLD_DAYS = 30
+_REACTIVATE_THRESHOLD_DAYS = 7
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def sync_descriptor(project: Project) -> DescriptorSyncResult:
+    """Sync a single project's descriptor file.
+
+    Reads the descriptor, checks if the project path exists, compares the
+    detected stack, checks git activity, and writes any updates back.
+    """
+    if not project.descriptor_path:
+        return DescriptorSyncResult(path=project.path, status="unchanged")
+
+    desc_path = Path(project.descriptor_path)
+    if not desc_path.exists():
+        return DescriptorSyncResult(path=project.path, status="unchanged")
+
+    try:
+        return _do_sync(project)
+    except Exception as exc:  # noqa: BLE001
+        return DescriptorSyncResult(
+            path=project.path, status="error", error=str(exc)
+        )
+
+
+def _do_sync(project: Project) -> DescriptorSyncResult:
+    """Execute the descriptor sync logic for a single project."""
+    desc_path = Path(project.descriptor_path)  # type: ignore[arg-type]
+    text = desc_path.read_text()
+    frontmatter, body = _split_frontmatter(text)
+    changes: list[str] = []
+
+    if not Path(project.path).exists():
+        frontmatter["status"] = "archived"
+        changes.append("status: archived (path not found)")
+        _write_descriptor(desc_path, frontmatter, body)
+        return DescriptorSyncResult(
+            path=project.path, status="updated", changes=changes
+        )
+
+    _check_stack(frontmatter, project.stack, changes)
+    _check_activity(frontmatter, project.path, changes)
+
+    if not changes:
+        return DescriptorSyncResult(path=project.path, status="unchanged")
+
+    _write_descriptor(desc_path, frontmatter, body)
+    return DescriptorSyncResult(
+        path=project.path, status="updated", changes=changes
+    )
+
+
+def sync_all_descriptors(projects: list[Project]) -> list[DescriptorSyncResult]:
+    """Sync descriptor files for all projects."""
+    return [sync_descriptor(p) for p in projects]
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _split_frontmatter(text: str) -> tuple[dict, str]:
+    """Split a markdown file into its YAML frontmatter dict and body string.
+
+    Expects the file to start with '---' and have a closing '---' marker.
+    Returns ({}, full_text) if frontmatter markers are not found.
+    """
+    if not text.startswith("---"):
+        return {}, text
+
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}, text
+
+    raw_yaml = parts[1]
+    body = parts[2]
+    parsed = yaml.safe_load(raw_yaml) or {}
+    return parsed, body
+
+
+def _normalize_stack_item(item: str) -> str:
+    """Normalize a stack item to lowercase first word for comparison."""
+    return item.strip().lower().split()[0]
+
+
+def _check_stack(
+    frontmatter: dict, detected_stack: list[str], changes: list[str]
+) -> None:
+    """Compare frontmatter stack with detected stack and update if different."""
+    fm_stack: list[str] = frontmatter.get("stack") or []
+    fm_normalized = {_normalize_stack_item(s) for s in fm_stack}
+    detected_normalized = {_normalize_stack_item(s) for s in detected_stack}
+
+    if fm_normalized != detected_normalized and detected_stack:
+        frontmatter["stack"] = detected_stack
+        changes.append(f"stack updated: {fm_stack} -> {detected_stack}")
+
+
+def _check_activity(
+    frontmatter: dict, project_path: str, changes: list[str]
+) -> None:
+    """Check git activity and auto-pause or auto-reactivate the project."""
+    days = _get_last_commit_days(project_path)
+    if days is None:
+        return
+
+    current_status = frontmatter.get("status", "active")
+
+    if days > _PAUSE_THRESHOLD_DAYS and current_status == "active":
+        frontmatter["status"] = "paused"
+        changes.append(f"status: active -> paused ({days}d since last commit)")
+    elif days < _REACTIVATE_THRESHOLD_DAYS and current_status == "paused":
+        frontmatter["status"] = "active"
+        changes.append(f"status: paused -> active ({days}d since last commit)")
+
+
+def _get_last_commit_days(project_path: str) -> int | None:
+    """Return days since the last git commit in project_path, or None."""
+    try:
+        result = subprocess.run(
+            ["git", "log", "-1", "--format=%ci"],
+            cwd=project_path,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        raw = result.stdout.strip()
+        if not raw:
+            return None
+
+        commit_dt = datetime.fromisoformat(raw)
+        if commit_dt.tzinfo is None:
+            commit_dt = commit_dt.replace(tzinfo=timezone.utc)
+
+        now = datetime.now(tz=timezone.utc)
+        return (now - commit_dt).days
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _write_descriptor(desc_path: Path, frontmatter: dict, body: str) -> None:
+    """Write updated frontmatter and preserved body back to the descriptor file."""
+    fm_text = yaml.dump(frontmatter, default_flow_style=False, allow_unicode=True)
+    desc_path.write_text(f"---\n{fm_text}---{body}")