arkaos 2.12.0 → 2.14.0

package/config/hooks/post-tool-use.sh

@@ -170,6 +170,108 @@ fi
 
 ) 200>"$LOCK_FILE"
 
+# ─── Workflow Violation Detection ────────────────────────────────────────
+VIOLATION_MSG=""
+STATE_READER=""
+[ -f "$HOME/.arkaos/.repo-path" ] && STATE_READER="$(cat "$HOME/.arkaos/.repo-path")/core/workflow/state_reader.sh"
+
+if [ -n "$STATE_READER" ] && [ -f "$STATE_READER" ] && bash "$STATE_READER" active 2>/dev/null; then
+  ARKAOS_PY=""
+  [ -f "$HOME/.arkaos/venv/bin/python3" ] && ARKAOS_PY="$HOME/.arkaos/venv/bin/python3"
+  [ -z "$ARKAOS_PY" ] && [ -f "$HOME/.arkaos/.venv/bin/python3" ] && ARKAOS_PY="$HOME/.arkaos/.venv/bin/python3"
+  [ -z "$ARKAOS_PY" ] && ARKAOS_PY=$(command -v python3 2>/dev/null)
+  ARKAOS_ROOT=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null)
+
+  # Rule 1: Branch isolation — commit on master while workflow active
+  if [ "$TOOL_NAME" = "Bash" ]; then
+    if echo "$TOOL_OUTPUT" | grep -qE '^\[(master|main)' 2>/dev/null; then
+      CMD_TEXT=$(echo "$input" | jq -r '.command // ""' 2>/dev/null)
+      if echo "$CMD_TEXT" | grep -qE 'git commit'; then
+        [ -n "$ARKAOS_PY" ] && [ -n "$ARKAOS_ROOT" ] && \
+          PYTHONPATH="$ARKAOS_ROOT" $ARKAOS_PY -c "
+from core.workflow.state import add_violation
+add_violation('branch-isolation', 'Commit on master/main while workflow active', 'Bash')
+" 2>/dev/null
+        VIOLATION_MSG="VIOLATION [branch-isolation]: Commit on master while workflow active. Use a feature branch."
+      fi
+    fi
+  fi
+
+  # Rule 2: Spec-driven — code edited without completed spec
+  if [ "$TOOL_NAME" = "Write" ] || [ "$TOOL_NAME" = "Edit" ]; then
+    FILE_PATH=$(echo "$input" | jq -r '.file_path // ""' 2>/dev/null)
+    if echo "$FILE_PATH" | grep -qE '\.(py|js|ts|vue|php|jsx|tsx)$'; then
+      if ! bash "$STATE_READER" check spec 2>/dev/null; then
+        [ -n "$ARKAOS_PY" ] && [ -n "$ARKAOS_ROOT" ] && \
+          PYTHONPATH="$ARKAOS_ROOT" _V_TOOL="$TOOL_NAME" _V_FILE="$FILE_PATH" $ARKAOS_PY -c "
+import os; from core.workflow.state import add_violation
+add_violation('spec-driven', 'Code edited without completed spec', os.environ['_V_TOOL'], os.environ['_V_FILE'])
+" 2>/dev/null
+        VIOLATION_MSG="VIOLATION [spec-driven]: Code edited without completed spec ($FILE_PATH). Complete the spec phase first."
+      fi
+    fi
+  fi
+
+  # Rule 3: Sequential — implementation before planning
+  if [ -z "$VIOLATION_MSG" ] && { [ "$TOOL_NAME" = "Write" ] || [ "$TOOL_NAME" = "Edit" ]; }; then
+    FILE_PATH=$(echo "$input" | jq -r '.file_path // ""' 2>/dev/null)
+    if echo "$FILE_PATH" | grep -qE '\.(py|js|ts|vue|php|jsx|tsx)$'; then
+      IMPL_STATUS=$(bash "$STATE_READER" phase implementation 2>/dev/null)
+      if [ "$IMPL_STATUS" = "pending" ]; then
+        [ -n "$ARKAOS_PY" ] && [ -n "$ARKAOS_ROOT" ] && \
+          PYTHONPATH="$ARKAOS_ROOT" _V_TOOL="$TOOL_NAME" _V_FILE="$FILE_PATH" $ARKAOS_PY -c "
+import os; from core.workflow.state import add_violation
+add_violation('sequential-validation', 'Code written before implementation phase started', os.environ['_V_TOOL'], os.environ['_V_FILE'])
+" 2>/dev/null
+        VIOLATION_MSG="VIOLATION [sequential-validation]: Implementation started before planning completed ($FILE_PATH)."
+      fi
+    fi
+  fi
+fi
+
+# --- Forge Violation Detection ---
+_FORGE_ACTIVE="$HOME/.arkaos/plans/active.yaml"
+
+# Ensure ARKAOS_PY and ARKAOS_ROOT are set (may not be set if no active workflow)
+if [ -z "${ARKAOS_PY:-}" ]; then
+  [ -f "$HOME/.arkaos/venv/bin/python3" ] && ARKAOS_PY="$HOME/.arkaos/venv/bin/python3"
+  [ -z "${ARKAOS_PY:-}" ] && [ -f "$HOME/.arkaos/.venv/bin/python3" ] && ARKAOS_PY="$HOME/.arkaos/.venv/bin/python3"
+  [ -z "${ARKAOS_PY:-}" ] && ARKAOS_PY=$(command -v python3 2>/dev/null)
+fi
+[ -z "${ARKAOS_ROOT:-}" ] && ARKAOS_ROOT=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null)
+
+if [ -z "$VIOLATION_MSG" ] && [ -f "$_FORGE_ACTIVE" ] && [ -n "$ARKAOS_PY" ] && [ -n "$ARKAOS_ROOT" ]; then
+  _FORGE_ID=$(cat "$_FORGE_ACTIVE" 2>/dev/null)
+  _FORGE_FILE="$HOME/.arkaos/plans/${_FORGE_ID}.yaml"
+
+  if [ -f "$_FORGE_FILE" ]; then
+    if [ "$TOOL_NAME" = "Edit" ] || [ "$TOOL_NAME" = "Write" ]; then
+      _EDITED_FILE="${tool_input_file_path:-}"
+      # Fallback: extract file_path from input JSON
+      [ -z "$_EDITED_FILE" ] && _EDITED_FILE=$(echo "$input" | jq -r '.file_path // ""' 2>/dev/null)
+      if [ -n "$_EDITED_FILE" ]; then
+        _FORGE_VIOLATION=$(FORGE_FILE="$_FORGE_FILE" EDITED_FILE="$_EDITED_FILE" PYTHONPATH="$ARKAOS_ROOT" $ARKAOS_PY -c "
+import yaml, sys, os
+plan = yaml.safe_load(open(os.environ['FORGE_FILE']))
+if plan.get('status', '') != 'executing':
+    sys.exit(0)
+phases = plan.get('plan_phases', [])
+all_deliverables = []
+for p in phases:
+    all_deliverables.extend(p.get('deliverables', []))
+edited = os.environ['EDITED_FILE']
+match = any(d in edited or edited.endswith(d) for d in all_deliverables)
+if not match and all_deliverables:
+    print('forge-scope-creep')
+" 2>/dev/null)
+        if [ "$_FORGE_VIOLATION" = "forge-scope-creep" ]; then
+          VIOLATION_MSG="⚠ Forge scope-creep: editing ${_EDITED_FILE} which is outside forge plan deliverables."
+        fi
+      fi
+    fi
+  fi
+fi
+
 # ─── Log Metrics ─────────────────────────────────────────────────────────
 _DURATION_MS=$(_hook_ms)
 METRICS_FILE="$HOME/.arkaos/hook-metrics.json"
@@ -184,5 +286,9 @@ mkdir -p "$HOME/.arkaos"
     "$METRICS_FILE" > "$METRICS_FILE.tmp" 2>/dev/null && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
 ) 200>"$METRICS_LOCK" 2>/dev/null
 
-# Silent output — no context injection needed from PostToolUse
-echo '{}'
+# Output violation as context if detected, otherwise empty
+if [ -n "$VIOLATION_MSG" ]; then
+  echo "{\"additionalContext\": \"$VIOLATION_MSG\"}"
+else
+  echo '{}'
+fi

package/config/hooks/session-start.sh

@@ -49,7 +49,45 @@ MSG+="║                                              ║\\n"
 MSG+="╚══════════════════════════════════════════════╝\\n"
 MSG+="\\n"
 MSG+="${GREETING}, ${NAME} (${COMPANY})\\n"
+# ─── Active Workflow ──────────────────────────────────────────────────
+STATE_READER="$REPO/core/workflow/state_reader.sh"
+if [ -n "$REPO" ] && [ -f "$STATE_READER" ] && bash "$STATE_READER" active 2>/dev/null; then
+  WF_SUMMARY=$(bash "$STATE_READER" summary 2>/dev/null)
+  WF_NAME=$(echo "$WF_SUMMARY" | cut -d'|' -f1)
+  WF_PHASE=$(echo "$WF_SUMMARY" | cut -d'|' -f2)
+  WF_PROGRESS=$(echo "$WF_SUMMARY" | cut -d'|' -f3)
+  WF_BRANCH=$(echo "$WF_SUMMARY" | cut -d'|' -f4)
+  WF_VIOLATIONS=$(echo "$WF_SUMMARY" | cut -d'|' -f5)
+  MSG+="\\nWorkflow: ${WF_NAME} (${WF_PROGRESS})"
+  [ -n "$WF_BRANCH" ] && MSG+=" branch:${WF_BRANCH}"
+  [ "$WF_VIOLATIONS" != "0" ] && MSG+=" VIOLATIONS:${WF_VIOLATIONS}"
+  MSG+="\\n"
+fi
+
+# --- Forge Plan Display ---
+_FORGE_PLANS="$HOME/.arkaos/plans"
+_FORGE_ACTIVE="$_FORGE_PLANS/active.yaml"
+_FORGE_LINE=""
+
+if [ -f "$_FORGE_ACTIVE" ]; then
+  _FORGE_ID=$(cat "$_FORGE_ACTIVE" 2>/dev/null)
+  _FORGE_FILE="$_FORGE_PLANS/${_FORGE_ID}.yaml"
+  if [ -f "$_FORGE_FILE" ] && command -v python3 &>/dev/null; then
+    _FORGE_NAME=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('name',''))" 2>/dev/null)
+    _FORGE_STATUS=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('status',''))" 2>/dev/null)
+    _FORGE_PHASES=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(len(d.get('plan_phases',[])))" 2>/dev/null)
+    _FORGE_BRANCH=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('governance',{}).get('branch_strategy',''))" 2>/dev/null)
+
+    if [ "$_FORGE_STATUS" = "approved" ]; then
+      _FORGE_LINE="  ⚒ Forge plan pending: ${_FORGE_NAME} | Phases: ${_FORGE_PHASES} | /forge resume"
+    elif [ "$_FORGE_STATUS" = "executing" ]; then
+      _FORGE_LINE="  ⚒ Forge executing: ${_FORGE_NAME} | Phases: ${_FORGE_PHASES} | Branch: ${_FORGE_BRANCH}"
+    fi
+  fi
+fi
+
 MSG+="ArkaOS v${VERSION} | 65 agents | 17 departments | 244+ skills"
+[ -n "$_FORGE_LINE" ] && MSG+="\\n${_FORGE_LINE}"
 MSG+="${DRIFT}"
 
 # ─── Output as systemMessage (same protocol as claude-mem) ─────────────

package/config/hooks/user-prompt-submit.sh

@@ -99,6 +99,31 @@ if command -v python3 &>/dev/null && [ -f "$BRIDGE_SCRIPT" ]; then
   if [ -n "$bridge_output" ]; then
     python_result=$(echo "$bridge_output" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('context_string',''))" 2>/dev/null)
   fi
+
+  # Append workflow state to synapse context
+  _WF_READER="$ARKAOS_ROOT/core/workflow/state_reader.sh"
+  if [ -f "$_WF_READER" ] && bash "$_WF_READER" active 2>/dev/null; then
+    _WF_SUM=$(bash "$_WF_READER" summary 2>/dev/null)
+    _WF_N=$(echo "$_WF_SUM" | cut -d'|' -f1)
+    _WF_P=$(echo "$_WF_SUM" | cut -d'|' -f2)
+    _WF_B=$(echo "$_WF_SUM" | cut -d'|' -f4)
+    _WF_V=$(echo "$_WF_SUM" | cut -d'|' -f5)
+    _WF_TAG="[workflow:${_WF_N}] [phase:${_WF_P}] [branch:${_WF_B}] [violations:${_WF_V}]"
+    [ "$_WF_V" != "0" ] && _WF_TAG="WARNING: ${_WF_V} workflow violation(s). $_WF_TAG"
+    python_result="${python_result} ${_WF_TAG}"
+  fi
+
+  # --- Forge Context Injection ---
+  _FORGE_ACTIVE="$HOME/.arkaos/plans/active.yaml"
+  if [ -f "$_FORGE_ACTIVE" ]; then
+    _FORGE_ID=$(cat "$_FORGE_ACTIVE" 2>/dev/null)
+    _FORGE_FILE="$HOME/.arkaos/plans/${_FORGE_ID}.yaml"
+    if [ -f "$_FORGE_FILE" ] && command -v python3 &>/dev/null; then
+      _FORGE_STATUS=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('status',''))" 2>/dev/null)
+      _FORGE_TAG="[forge:${_FORGE_ID}] [forge-status:${_FORGE_STATUS}]"
+      python_result="${python_result} ${_FORGE_TAG}"
+    fi
+  fi
 fi
 
 # ─── Fallback: Bash-only context (if Python unavailable) ────────────────
@@ -130,7 +155,32 @@ if [ -z "$python_result" ]; then
     L7="[time:evening]"
   fi
 
-  python_result="$L0 $L4 $L7"
+  # L8: Workflow state
+  L8=""
+  _WF_READER="$ARKAOS_ROOT/core/workflow/state_reader.sh"
+  if [ -f "$_WF_READER" ] && bash "$_WF_READER" active 2>/dev/null; then
+    _WF_SUM=$(bash "$_WF_READER" summary 2>/dev/null)
+    _WF_N=$(echo "$_WF_SUM" | cut -d'|' -f1)
+    _WF_P=$(echo "$_WF_SUM" | cut -d'|' -f2)
+    _WF_B=$(echo "$_WF_SUM" | cut -d'|' -f4)
+    _WF_V=$(echo "$_WF_SUM" | cut -d'|' -f5)
+    L8="[workflow:${_WF_N}] [phase:${_WF_P}] [branch:${_WF_B}] [violations:${_WF_V}]"
+    [ "$_WF_V" != "0" ] && L8="WARNING: ${_WF_V} workflow violation(s). $L8"
+  fi
+
+  # L9: Forge state
+  L9=""
+  _FORGE_ACTIVE_FB="$HOME/.arkaos/plans/active.yaml"
+  if [ -f "$_FORGE_ACTIVE_FB" ]; then
+    _FORGE_ID_FB=$(cat "$_FORGE_ACTIVE_FB" 2>/dev/null)
+    _FORGE_FILE_FB="$HOME/.arkaos/plans/${_FORGE_ID_FB}.yaml"
+    if [ -f "$_FORGE_FILE_FB" ] && command -v python3 &>/dev/null; then
+      _FORGE_STATUS_FB=$(FORGE_FILE="$_FORGE_FILE_FB" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('status',''))" 2>/dev/null)
+      L9="[forge:${_FORGE_ID_FB}] [forge-status:${_FORGE_STATUS_FB}]"
+    fi
+  fi
+
+  python_result="$L0 $L4 $L7 $L8 $L9"
 fi
 
 # ─── Output ──────────────────────────────────────────────────────────────

package/core/forge/__init__.py

@@ -0,0 +1,104 @@
+"""The Forge — ArkaOS Intelligent Planning Engine."""
+
+from core.forge.schema import (
+    ForgeTier,
+    ForgeStatus,
+    ExplorerLens,
+    RiskSeverity,
+    ExecutionPathType,
+    ComplexityDimensions,
+    ComplexityScore,
+    KeyDecision,
+    PhaseDeliverable,
+    ExplorerApproach,
+    RejectedElement,
+    IdentifiedRisk,
+    CriticVerdict,
+    ForgeContext,
+    PlanPhase,
+    ExecutionPath,
+    ForgeGovernance,
+    ForgePlan,
+)
+
+from core.forge.complexity import (
+    score_dimensions,
+    calculate_weighted_score,
+    determine_tier,
+    analyze_complexity,
+)
+
+from core.forge.persistence import (
+    save_plan,
+    load_plan,
+    list_plans,
+    get_active_plan,
+    set_active_plan,
+    clear_active_plan,
+    export_to_obsidian,
+    extract_patterns,
+    load_patterns,
+)
+
+from core.forge.renderer import (
+    render_complexity,
+    render_critic_summary,
+    render_plan_overview,
+    render_terminal,
+    render_html,
+    should_suggest_companion,
+)
+
+from core.forge.handoff import (
+    select_execution_path,
+    generate_workflow_yaml,
+    check_repo_drift,
+)
+
+__all__ = [
+    # schema
+    "ForgeTier",
+    "ForgeStatus",
+    "ExplorerLens",
+    "RiskSeverity",
+    "ExecutionPathType",
+    "ComplexityDimensions",
+    "ComplexityScore",
+    "KeyDecision",
+    "PhaseDeliverable",
+    "ExplorerApproach",
+    "RejectedElement",
+    "IdentifiedRisk",
+    "CriticVerdict",
+    "ForgeContext",
+    "PlanPhase",
+    "ExecutionPath",
+    "ForgeGovernance",
+    "ForgePlan",
+    # complexity
+    "score_dimensions",
+    "calculate_weighted_score",
+    "determine_tier",
+    "analyze_complexity",
+    # persistence
+    "save_plan",
+    "load_plan",
+    "list_plans",
+    "get_active_plan",
+    "set_active_plan",
+    "clear_active_plan",
+    "export_to_obsidian",
+    "extract_patterns",
+    "load_patterns",
+    # renderer
+    "render_complexity",
+    "render_critic_summary",
+    "render_plan_overview",
+    "render_terminal",
+    "render_html",
+    "should_suggest_companion",
+    # handoff
+    "select_execution_path",
+    "generate_workflow_yaml",
+    "check_repo_drift",
+]

package/core/forge/complexity.py

@@ -0,0 +1,125 @@
+"""Forge complexity scorer — 5-dimension analysis with tier determination."""
+
+import re
+
+from core.forge.schema import ComplexityDimensions, ComplexityScore, ForgeTier
+
+_WEIGHTS = {
+    "scope": 0.30,
+    "dependencies": 0.25,
+    "ambiguity": 0.20,
+    "risk": 0.15,
+    "novelty": 0.10,
+}
+
+_RISK_KEYWORDS = re.compile(
+    r"\b(auth\w*|security\w*|encrypt\w*|password\w*|token\w*|secret\w*|permission\w*|migration\w*|database\w*|schema\w*|deploy\w*|infra\w*|production\w*|payment\w*|billing\w*)",
+    re.IGNORECASE,
+)
+_VAGUE_PATTERNS = re.compile(
+    r"\b(fix|improve|make.*better|update|change|refactor|clean|optimize)\b",
+    re.IGNORECASE,
+)
+
+
+def score_dimensions(
+    prompt: str,
+    affected_files: list[str],
+    departments: list[str],
+    similar_plans: list[str],
+    reused_patterns: list[str],
+) -> ComplexityDimensions:
+    """Score all 5 complexity dimensions from prompt and context."""
+    return ComplexityDimensions(
+        scope=_score_scope(affected_files, departments),
+        dependencies=_score_dependencies(affected_files),
+        ambiguity=_score_ambiguity(prompt, affected_files),
+        risk=_score_risk(prompt, affected_files),
+        novelty=_score_novelty(similar_plans, reused_patterns),
+    )
+
+
+def calculate_weighted_score(dims: ComplexityDimensions) -> int:
+    """Calculate weighted total score from dimensions."""
+    total = (
+        dims.scope * _WEIGHTS["scope"]
+        + dims.dependencies * _WEIGHTS["dependencies"]
+        + dims.ambiguity * _WEIGHTS["ambiguity"]
+        + dims.risk * _WEIGHTS["risk"]
+        + dims.novelty * _WEIGHTS["novelty"]
+    )
+    return round(total)
+
+
+def determine_tier(score: int) -> ForgeTier:
+    """Map a 0-100 score to a forge tier."""
+    if score <= 30:
+        return ForgeTier.SHALLOW
+    if score <= 65:
+        return ForgeTier.STANDARD
+    return ForgeTier.DEEP
+
+
+def analyze_complexity(
+    prompt: str,
+    affected_files: list[str],
+    departments: list[str],
+    similar_plans: list[str],
+    reused_patterns: list[str],
+) -> ComplexityScore:
+    """Full complexity analysis: dimensions, weighted score, tier."""
+    dims = score_dimensions(prompt, affected_files, departments, similar_plans, reused_patterns)
+    score = calculate_weighted_score(dims)
+    tier = determine_tier(score)
+    return ComplexityScore(
+        score=score,
+        tier=tier,
+        dimensions=dims,
+        similar_plans=similar_plans,
+        reused_patterns=reused_patterns,
+    )
+
+
+def _score_scope(files: list[str], departments: list[str]) -> int:
+    file_score = min(100, len(files) * 10)
+    dept_score = min(100, len(departments) * 30)
+    return min(100, (file_score + dept_score) // 2)
+
+
+def _score_dependencies(files: list[str]) -> int:
+    if not files:
+        return 20
+    core_files = sum(1 for f in files if f.startswith("core/"))
+    ratio = core_files / len(files)
+    return min(100, int(ratio * 80) + 20)
+
+
+def _score_ambiguity(prompt: str, files: list[str]) -> int:
+    score = 50
+    if len(prompt.split()) < 5:
+        score += 30
+    if not files:
+        score += 20
+    vague_matches = len(_VAGUE_PATTERNS.findall(prompt))
+    score += min(20, vague_matches * 10)
+    specific_indicators = len(re.findall(r"[/\.]", prompt))
+    score -= min(30, specific_indicators * 5)
+    return max(0, min(100, score))
+
+
+def _score_risk(prompt: str, files: list[str]) -> int:
+    score = 20
+    risk_matches = len(_RISK_KEYWORDS.findall(prompt))
+    score += min(50, risk_matches * 15)
+    sensitive_paths = sum(
+        1 for f in files if any(kw in f for kw in ("auth", "security", "migration", "deploy", "config"))
+    )
+    score += min(30, sensitive_paths * 15)
+    return min(100, score)
+
+
+def _score_novelty(similar_plans: list[str], patterns: list[str]) -> int:
+    score = 90
+    score -= min(40, len(similar_plans) * 20)
+    score -= min(30, len(patterns) * 15)
+    return max(10, score)

package/core/forge/handoff.py

@@ -0,0 +1,100 @@
+"""Forge handoff — execution path routing and workflow generation."""
+
+import subprocess
+import yaml
+from core.forge.schema import ExecutionPath, ExecutionPathType, ForgePlan, PlanPhase
+
+
+def select_execution_path(phases: list[PlanPhase]) -> ExecutionPath:
+    """Select the execution path based on phase count and departments.
+
+    Rules: 1 phase, 1 dept → skill | 2-3 phases, 1 dept → workflow | 4+ phases or 2+ depts → enterprise
+    """
+    departments = list({p.department for p in phases})
+    n_phases = len(phases)
+    n_depts = len(departments)
+
+    if n_depts >= 2:
+        path_type = ExecutionPathType.ENTERPRISE_WORKFLOW
+    elif n_phases >= 4:
+        path_type = ExecutionPathType.ENTERPRISE_WORKFLOW
+    elif n_phases >= 2:
+        path_type = ExecutionPathType.WORKFLOW
+    else:
+        path_type = ExecutionPathType.SKILL
+
+    target = ""
+    if path_type == ExecutionPathType.SKILL and departments:
+        target = f"arka-{departments[0]}"
+    elif path_type in (ExecutionPathType.WORKFLOW, ExecutionPathType.ENTERPRISE_WORKFLOW):
+        target = "generated-workflow.yaml"
+
+    return ExecutionPath(
+        type=path_type,
+        target=target,
+        departments=departments,
+        estimated_commits=max(1, n_phases * 2),
+    )
+
+
+def generate_workflow_yaml(plan: ForgePlan) -> str:
+    """Generate a complete workflow YAML from a forge plan."""
+    phases_data = []
+    for phase in plan.plan_phases:
+        d: dict = {"name": phase.name, "department": phase.department}
+        if phase.agents:
+            d["agents"] = [{"role": a} for a in phase.agents]
+        if phase.deliverables:
+            d["deliverables"] = phase.deliverables
+        if phase.acceptance_criteria:
+            d["acceptance_criteria"] = phase.acceptance_criteria
+        if phase.depends_on:
+            d["depends_on"] = phase.depends_on
+        if phase.context_from_forge:
+            d["context_from_forge"] = phase.context_from_forge
+        phases_data.append(d)
+
+    workflow = {
+        "name": plan.id,
+        "type": "enterprise" if len(plan.plan_phases) >= 4 else "focused",
+        "generated_by": "forge",
+        "forge_plan_id": plan.id,
+        "phases": phases_data,
+        "quality_gate_required": plan.governance.quality_gate_required,
+        "branch": plan.governance.branch_strategy,
+    }
+    return yaml.dump(workflow, default_flow_style=False, allow_unicode=True)
+
+
+def _git_changed_files(base: str, current: str) -> list[str]:
+    """Return list of files changed between two commits, or [] on error."""
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", base, current],
+            capture_output=True, text=True, check=True,
+        )
+        return [f for f in result.stdout.strip().split("\n") if f]
+    except subprocess.CalledProcessError:
+        return []
+
+
+def check_repo_drift(commit_at_forge: str) -> dict:
+    """Check if the repo has changed since the forge snapshot."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            capture_output=True, text=True, check=True,
+        )
+        current = result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return {"changed": False, "files": [], "message": "Could not read git state"}
+
+    if current == commit_at_forge:
+        return {"changed": False, "files": [], "message": "Repo unchanged"}
+
+    files = _git_changed_files(commit_at_forge, current)
+    return {
+        "changed": True,
+        "files": files,
+        "message": f"Repo changed: {len(files)} files modified since forge",
+    }