igel-qe-core 1.0.3 → 1.0.7

package/src/cli/workflow_cli.py

@@ -0,0 +1,930 @@
+"""Workflow CLI — Python engine invoked by Node.js MCP server and igel-qe CLI.
+
+Action dispatch table:
+  plan_test_cases       — Req → Understanding → Context → Scenarios → Business Rules (plan only)
+  generate_test_cases   — Req → Understanding → Scenarios → Business Rules → Test Cases
+                           (reuses a plan_test_cases artifact when present)
+  plan_automation       — Approved test cases → Automation Plan (plan only, no script)
+  generate_automation   — Approved test cases → Automation Plan → pytest script
+                           (reuses a plan_automation artifact when present)
+  init_check            — Read-only pre-flight connectivity checks (no side effects)
+  sync_from_files       — Delta-index a list of changed file paths into Asset Registry
+  sync_from_commit      — Resolve changed files for a commit, then delta-index
+  impact_analysis       — Return requirements/scripts/assets affected by changed files
+  submit_feedback       — Store 4-level granular feedback
+
+Each action reads a JSON --args payload and writes a single JSON line to stdout.
+"""
+import argparse
+import json
+import logging
+import sys
+from pathlib import Path
+
+# Bootstrap: ensure the project root is in PYTHONPATH so that
+# `src` is importable whether called via `python -m` or directly.
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(_PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PROJECT_ROOT))
+
+from src.db.igel_schema import ensure_igel_tables
+from src.connectors.jira_connector import JiraConnector
+from src.agents.workflow_engine import WorkflowEngine
+from src.intelligence.diff_analyzer import analyze_diff_scope
+from src.intelligence.routing_engine import RouteInputs, compute_weighted_score, classify_route
+from src.agents.framework_analyzer_agent import FrameworkAnalyzerAgent
+from src.agents.orchestrator.orchestrator import Orchestrator
+from src.agents.internal.approval_manager import ApprovalError
+from src.config import cfg
+from src.project.context_projection_builder import ContextProjectionBuilder
+from src.project.context_requirement_sync import sync_requirement_context
+from src.project.context_enricher import enrich_context_files
+
+logging.basicConfig(level=logging.ERROR)  # Only output strict JSON to stdout
+
+ALL_ACTIONS = [
+    "plan_test_cases",
+    "generate_test_cases",
+    "plan_automation",
+    "generate_automation",
+    "sync_from_files",
+    "sync_from_commit",
+    "impact_analysis",
+    "submit_feedback",
+    "init_project",
+    "init_check",
+    "sync_push_event",
+    "get_project_status",
+    "scaffold_ai_folder",
+    "analyze_framework_scope",
+    "project_context_cache",
+    "enrich_requirement_context",
+    "enrich_framework_context",
+    "update_context_file",
+    "record_approval",
+    # Legacy alias kept for MCP server backward compat — maps to sync_from_commit
+    "sync_bitbucket",
+]
+
+
+def _ok(data: dict) -> None:
+    print(json.dumps({"status": "success", **data}))
+
+
+def _err(message: str) -> None:
+    print(json.dumps({"status": "error", "message": message}))
+    sys.exit(1)
+
+
+def _best_effort_project_context(repo_path: Path) -> dict:
+    """Refresh .ai/context.md without breaking the main workflow on failure."""
+    try:
+        return ContextProjectionBuilder(repo_path).build()
+    except Exception as e:
+        logging.warning("Context projection refresh skipped: %s", e)
+        return {
+            "context_path": str(repo_path / ".ai" / "context.md"),
+            "error": str(e),
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Workflow CLI for Node.js IPC")
+    parser.add_argument("--action", required=True, choices=ALL_ACTIONS)
+    parser.add_argument("--args", required=True, help="JSON arguments for the action")
+    args = parser.parse_args()
+
+    try:
+        payload = json.loads(args.args)
+    except json.JSONDecodeError:
+        _err("Invalid JSON args")
+
+    # ── DB init ────────────────────────────────────────────────────────────────
+    if args.action not in ("submit_feedback",):
+        try:
+            ensure_igel_tables()
+        except Exception as e:
+            _err(f"Database Init Failed: {e}")
+
+    # ── plan_test_cases ────────────────────────────────────────────────────────
+    if args.action == "plan_test_cases":
+        jira_key = payload.get("jira_key")
+        if not jira_key:
+            _err("Missing jira_key")
+
+        try:
+            connector = JiraConnector()
+            req = connector.get_test_requirement(jira_key)
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            orchestrator = Orchestrator(repo_path)
+            engine = WorkflowEngine(repo_path)
+            test_reqid = payload.get("test_reqid")
+            requirement_hash = (req.summary or "") + "|" + (req.description or "")
+
+            req, scenarios, resolved_context, source_report = engine.run_requirement_flow(req)
+
+            artifact_summary = {}
+            try:
+                from src.project.ai_folder import write_requirement_plan_artifact
+                artifact_summary = write_requirement_plan_artifact(
+                    repo_root=repo_path,
+                    jira_key=jira_key,
+                    test_reqid=test_reqid,
+                    scenarios_with_rules=scenarios,
+                    resolved_context=resolved_context,
+                    source_report=source_report,
+                    requirement_hash=requirement_hash,
+                )
+            except Exception as e:
+                logging.warning("Failed to write plan artifact (non-fatal): %s", e)
+
+            governance = {
+                "approval_required": False,
+                "questions": [],
+                "stage": "testcase_plan",
+            }
+            if cfg.V2_ORCHESTRATOR_ENABLED or cfg.V2_GOVERNANCE_ENFORCED or cfg.V2_APPROVAL_MANAGER_ENABLED:
+                decision = orchestrator.plan_gate(
+                    jira_key=jira_key,
+                    test_reqid=test_reqid,
+                    summary=req.summary or "",
+                    description=req.description or "",
+                    stage="testcase_plan",
+                )
+                governance = {
+                    "approval_required": decision.approval_required,
+                    "questions": decision.questions,
+                    "stage": decision.workflow,
+                    "question_batching": True,
+                    "sequential_questions": False,
+                }
+
+            _ok({
+                "jira_key": jira_key,
+                "test_reqid": test_reqid or jira_key,
+                "scenarios_count": len(scenarios),
+                "scenarios": [
+                    {
+                        "step": sr.scenario.action,
+                        "business_rules": [
+                            {"type": br.rule_type, "description": br.description}
+                            for br in sr.business_rules
+                        ],
+                    }
+                    for sr in scenarios
+                ],
+                "source_report": {
+                    "jira_found": source_report.jira_found,
+                    "confluence_found": source_report.confluence_found,
+                    "postgres_kb_found": source_report.postgres_kb_found,
+                    "igel_os12_docs_found": source_report.igel_os12_docs_found,
+                    "conflicts": source_report.conflicts,
+                },
+                "resolved_context": {
+                    "source": resolved_context.source,
+                    "conflicting_sources": resolved_context.conflicting_sources,
+                    "resolution_rationale": resolved_context.resolution_rationale,
+                },
+                "artifact": artifact_summary,
+                "governance": governance,
+            })
+
+        except ApprovalError as e:
+            _err(str(e))
+        except Exception as e:
+            _err(str(e))
+
+    # ── generate_test_cases ────────────────────────────────────────────────────
+    elif args.action == "generate_test_cases":
+        jira_key = payload.get("jira_key")
+        if not jira_key:
+            _err("Missing jira_key")
+
+        try:
+            connector = JiraConnector()
+            req = connector.get_test_requirement(jira_key)
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            orchestrator = Orchestrator(repo_path)
+            engine = WorkflowEngine(repo_path)
+            test_reqid = payload.get("test_reqid")
+            requirement_hash = (req.summary or "") + "|" + (req.description or "")
+
+            if cfg.V2_ORCHESTRATOR_ENABLED or cfg.V2_GOVERNANCE_ENFORCED or cfg.V2_APPROVAL_MANAGER_ENABLED:
+                orchestrator.assert_generation_gate(
+                    jira_key=jira_key,
+                    test_reqid=test_reqid,
+                    stage="testcase_plan",
+                )
+
+            scenarios = resolved_context = source_report = None
+            plan_artifact_used = False
+
+            # Enterprise routing decision (Copilot-constrained strategy mode)
+            route_inputs = RouteInputs(
+                complexity=float(payload.get("complexity_score", 0.5)),
+                risk=float(payload.get("risk_score", 0.5)),
+                context_confidence=float(payload.get("context_confidence", 0.5)),
+                repo_impact=float(payload.get("repository_impact", 0.5)),
+                historical_success=float(payload.get("historical_success", 0.5)),
+            )
+            route_score = compute_weighted_score(route_inputs)
+            routing_decision = {
+                "score": route_score,
+                **classify_route(route_score),
+                "weights": {
+                    "complexity": 0.30,
+                    "risk": 0.25,
+                    "context_confidence": 0.20,
+                    "repository_impact": 0.10,
+                    "historical_success": 0.15,
+                },
+            }
+
+            try:
+                from src.models.test_requirement import ScenarioWithRules
+                from src.core.evidence_resolver import ResolvedContext
+                from src.core.context_engine import SourceReport
+                from src.project.ai_folder import read_plan_artifact
+                plan_artifact = read_plan_artifact(repo_path, jira_key, test_reqid)
+                if plan_artifact:
+                    if plan_artifact.get("staleness", {}).get("requirement_hash") == requirement_hash:
+                        scenarios = [ScenarioWithRules.model_validate(s) for s in plan_artifact.get("scenarios", [])]
+                        resolved_context = ResolvedContext(**plan_artifact["resolved_context"])
+                        source_report = SourceReport(**plan_artifact["source_report"])
+                        plan_artifact_used = True
+                    else:
+                        logging.warning(
+                            "Plan artifact for %s/%s is stale (requirement changed); replanning.",
+                            jira_key, test_reqid,
+                        )
+            except Exception as e:
+                logging.warning("Failed to read plan artifact; falling back to fresh planning: %s", e)
+
+            if not plan_artifact_used:
+                req, scenarios, resolved_context, source_report = engine.run_requirement_flow(req)
+
+            test_cases = engine.run_testcase_flow(req, scenarios, resolved_context, source_report)
+
+            approved = [tc for tc in test_cases if tc.is_approved]
+            unapproved = [
+                {"tc_reference": tc.test_case.tc_reference, "confidence": round(tc.confidence.total_score, 3)}
+                for tc in test_cases if not tc.is_approved
+            ]
+
+            # Persist generated/approved testcases as .ai artifacts for script-generation reuse
+            artifact_summary = {}
+            try:
+                from src.project.ai_folder import write_testcase_artifacts
+                artifact_summary = write_testcase_artifacts(
+                    repo_root=repo_path,
+                    jira_key=jira_key,
+                    test_reqid=test_reqid,
+                    generated_cases=test_cases,
+                    approved_cases=approved,
+                    requirement_hash=requirement_hash,
+                )
+            except Exception as e:
+                logging.warning("Failed to write testcase artifacts (non-fatal): %s", e)
+
+            _ok({
+                "jira_key": jira_key,
+                "total_cases": len(test_cases),
+                "approved_cases": len(approved),
+                "unapproved_cases": unapproved,
+                "scenarios_count": len(scenarios),
+                "plan_artifact_used": plan_artifact_used,
+                "routing_decision": routing_decision,
+                "artifact": artifact_summary,
+                "governance": {
+                    "stage": "testcase_plan",
+                    "approval_checked": bool(cfg.V2_ORCHESTRATOR_ENABLED or cfg.V2_GOVERNANCE_ENFORCED or cfg.V2_APPROVAL_MANAGER_ENABLED),
+                },
+                "context_projection": _best_effort_project_context(repo_path),
+            })
+
+        except Exception as e:
+            _err(str(e))
+
+    # ── plan_automation ────────────────────────────────────────────────────────
+    elif args.action == "plan_automation":
+        jira_key = payload.get("jira_key")
+        if not jira_key:
+            _err("Missing jira_key")
+
+        try:
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            orchestrator = Orchestrator(repo_path)
+            test_reqid = payload.get("test_reqid")
+
+            from src.models.test_requirement import TestCaseWithConfidence
+            from src.project.ai_folder import (
+                read_approved_testcase_artifact,
+                write_automation_plan_artifact,
+                compute_cases_content_hash,
+            )
+            from src.agents.automation_design_agent import design_automation_plan
+
+            artifact = read_approved_testcase_artifact(repo_path, jira_key, test_reqid)
+            cases = artifact.get("cases", []) if isinstance(artifact, dict) else []
+
+            if cases:
+                approved = [TestCaseWithConfidence.model_validate(c) for c in cases]
+            else:
+                # No approved-testcase artifact yet — fall back to the full
+                # req->testcase pipeline (mirrors generate_automation's existing
+                # fallback), stopping short of script generation.
+                connector = JiraConnector()
+                req = connector.get_test_requirement(jira_key)
+                engine = WorkflowEngine(repo_path)
+                req, scenarios, resolved_context, source_report = engine.run_requirement_flow(req)
+                test_cases = engine.run_testcase_flow(req, scenarios, resolved_context, source_report)
+                approved = [tc for tc in test_cases if tc.is_approved]
+                if not approved:
+                    _ok({
+                        "jira_key": jira_key,
+                        "plan_generated": False,
+                        "message": "No test cases met the confidence threshold (>=0.80); nothing to plan automation for.",
+                    })
+                    return
+
+            plan = design_automation_plan(approved)
+            approved_content_hash = compute_cases_content_hash(approved)
+
+            artifact_summary = write_automation_plan_artifact(
+                repo_root=repo_path,
+                jira_key=jira_key,
+                test_reqid=test_reqid,
+                plan=plan,
+                approved_content_hash=approved_content_hash,
+            )
+
+            governance = {
+                "approval_required": False,
+                "questions": [],
+                "stage": "automation_plan",
+            }
+            if cfg.V2_ORCHESTRATOR_ENABLED or cfg.V2_GOVERNANCE_ENFORCED or cfg.V2_APPROVAL_MANAGER_ENABLED:
+                decision = orchestrator.plan_gate(
+                    jira_key=jira_key,
+                    test_reqid=test_reqid,
+                    summary=f"Automation plan for {jira_key}",
+                    description="",
+                    stage="automation_plan",
+                )
+                governance = {
+                    "approval_required": decision.approval_required,
+                    "questions": decision.questions,
+                    "stage": decision.workflow,
+                    "question_batching": True,
+                    "sequential_questions": False,
+                }
+
+            _ok({
+                "jira_key": jira_key,
+                "test_reqid": test_reqid or jira_key,
+                "page_objects": plan.page_objects,
+                "fixtures": plan.fixtures,
+                "utilities": plan.utilities,
+                "approved_cases_considered": len(approved),
+                "artifact": artifact_summary,
+                "governance": governance,
+            })
+        except Exception as e:
+            _err(str(e))
+
+    # ── generate_automation ────────────────────────────────────────────────────
+    # NOTE: Confidence gate is intentionally respected here.
+    # Only test cases with is_approved=True (confidence >= 0.80) are scripted.
+    # Unapproved TCs are returned in the response so engineers know what needs review.
+    elif args.action == "generate_automation":
+        jira_key = payload.get("jira_key")
+        if not jira_key:
+            _err("Missing jira_key")
+
+        try:
+            connector = JiraConnector()
+            req = connector.get_test_requirement(jira_key)
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            orchestrator = Orchestrator(repo_path)
+            output_dir = Path(payload.get("output_dir", str(repo_path / "tests")))
+            engine = WorkflowEngine(repo_path)
+            test_reqid = payload.get("test_reqid")
+
+            if cfg.V2_ORCHESTRATOR_ENABLED or cfg.V2_GOVERNANCE_ENFORCED or cfg.V2_APPROVAL_MANAGER_ENABLED:
+                orchestrator.assert_generation_gate(
+                    jira_key=jira_key,
+                    test_reqid=test_reqid,
+                    stage="automation_plan",
+                )
+
+            approved = []
+            unapproved = []
+            artifact_used = False
+
+            # Enterprise routing decision (Copilot-constrained strategy mode)
+            route_inputs = RouteInputs(
+                complexity=float(payload.get("complexity_score", 0.5)),
+                risk=float(payload.get("risk_score", 0.5)),
+                context_confidence=float(payload.get("context_confidence", 0.5)),
+                repo_impact=float(payload.get("repository_impact", 0.5)),
+                historical_success=float(payload.get("historical_success", 0.5)),
+            )
+            route_score = compute_weighted_score(route_inputs)
+            routing_decision = {
+                "score": route_score,
+                **classify_route(route_score),
+                "weights": {
+                    "complexity": 0.30,
+                    "risk": 0.25,
+                    "context_confidence": 0.20,
+                    "repository_impact": 0.10,
+                    "historical_success": 0.15,
+                },
+            }
+
+            # Artifact-first: consume approved testcase artifact when present
+            try:
+                from src.models.test_requirement import TestCaseWithConfidence
+                from src.project.ai_folder import read_approved_testcase_artifact
+                artifact = read_approved_testcase_artifact(repo_path, jira_key, test_reqid)
+                cases = artifact.get("cases", []) if isinstance(artifact, dict) else []
+                if cases:
+                    approved = [TestCaseWithConfidence.model_validate(c) for c in cases]
+                    artifact_used = True
+            except Exception as e:
+                logging.warning("Failed to read approved testcase artifact; falling back to regeneration: %s", e)
+
+            # Fallback path: regenerate cases, then enforce confidence gate
+            if not approved:
+                req, scenarios, resolved_context, source_report = engine.run_requirement_flow(req)
+                test_cases = engine.run_testcase_flow(req, scenarios, resolved_context, source_report)
+
+                approved = [tc for tc in test_cases if tc.is_approved]
+                unapproved = [
+                    {"tc_reference": tc.test_case.tc_reference, "confidence": round(tc.confidence.total_score, 3)}
+                    for tc in test_cases if not tc.is_approved
+                ]
+
+            if not approved:
+                _ok({
+                    "jira_key": jira_key,
+                    "script_generated": False,
+                    "approved_cases": 0,
+                    "unapproved_cases": unapproved,
+                    "message": "No test cases met the confidence threshold (>=0.80). Review unapproved_cases.",
+                })
+                return
+
+            # Automation-plan artifact-first: reuse a persisted AutomationPlan if it
+            # matches the exact approved test cases we're about to script.
+            from src.project.ai_folder import (
+                read_automation_plan_artifact,
+                write_automation_plan_artifact,
+                compute_cases_content_hash,
+            )
+            from src.agents.automation_design_agent import AutomationPlan
+
+            approved_content_hash = compute_cases_content_hash(approved)
+            automation_plan = None
+            automation_plan_used = False
+            try:
+                plan_artifact = read_automation_plan_artifact(repo_path, jira_key, test_reqid)
+                if plan_artifact and plan_artifact.get("staleness", {}).get("approved_content_hash") == approved_content_hash:
+                    automation_plan = AutomationPlan.model_validate(plan_artifact["plan"])
+                    automation_plan_used = True
+            except Exception as e:
+                logging.warning("Failed to read automation plan artifact; will design fresh: %s", e)
+
+            output_script = output_dir / f"test_{jira_key.replace('-', '_').lower()}.py"
+            ok, msg, used_plan = engine.run_script_flow(req, approved, output_script, plan=automation_plan)
+
+            if ok and not automation_plan_used and used_plan is not None:
+                try:
+                    write_automation_plan_artifact(
+                        repo_root=repo_path, jira_key=jira_key, test_reqid=test_reqid,
+                        plan=used_plan, approved_content_hash=approved_content_hash,
+                    )
+                except Exception as e:
+                    logging.warning("Failed to persist automation plan artifact (non-fatal): %s", e)
+
+            if ok:
+                _ok({
+                    "jira_key": jira_key,
+                    "script_generated": True,
+                    "script_path": str(output_script),
+                    "approved_cases": len(approved),
+                    "unapproved_cases": unapproved,
+                    "artifact_used": artifact_used,
+                    "automation_plan_used": automation_plan_used,
+                    "routing_decision": routing_decision,
+                    "governance": {
+                        "stage": "automation_plan",
+                        "approval_checked": bool(cfg.V2_ORCHESTRATOR_ENABLED or cfg.V2_GOVERNANCE_ENFORCED or cfg.V2_APPROVAL_MANAGER_ENABLED),
+                    },
+                    "context_projection": _best_effort_project_context(repo_path),
+                })
+            else:
+                _err(msg)
+
+        except ApprovalError as e:
+            _err(str(e))
+        except Exception as e:
+            _err(str(e))
+
+    # ── record_approval ───────────────────────────────────────────────────────
+    elif args.action == "record_approval":
+        jira_key = payload.get("jira_key")
+        stage = payload.get("stage")
+        decision = payload.get("decision")
+        actor = payload.get("actor")
+        test_reqid = payload.get("test_reqid")
+        reason = payload.get("reason")
+
+        if not jira_key:
+            _err("Missing jira_key")
+        if not stage:
+            _err("Missing stage")
+        if not decision:
+            _err("Missing decision")
+        if not actor:
+            _err("Missing actor")
+
+        try:
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            from src.agents.internal.approval_manager import ApprovalManager
+
+            manager = ApprovalManager(repo_path)
+            record = manager.record_decision(
+                jira_key=jira_key,
+                stage=stage,
+                decision=decision,
+                actor=actor,
+                reason=reason,
+                test_reqid=test_reqid,
+            )
+            _ok({
+                "jira_key": jira_key,
+                "stage": stage,
+                "approval": record,
+            })
+        except ApprovalError as e:
+            _err(str(e))
+        except Exception as e:
+            _err(str(e))
+
+    # ── sync_from_files ────────────────────────────────────────────────────────
+    # Accepts: { "changed_files": ["path/to/file.py", ...], "repo_path": "..." }
+    elif args.action == "sync_from_files":
+        changed_files = payload.get("changed_files")
+        if not changed_files or not isinstance(changed_files, list):
+            _err("Missing or invalid changed_files list (must be list of path strings)")
+
+        try:
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            analyzer = FrameworkAnalyzerAgent(repo_path)
+            file_paths = [Path(f) for f in changed_files]
+
+            # Diff Analyzer first: build impacted scope before framework indexing.
+            diff_scope = analyze_diff_scope(repo_path, file_paths)
+            analysis_targets = [
+                repo_path / p for p in diff_scope.get("analysis_targets", [])
+                if (repo_path / p).exists()
+            ]
+            analysis_result = analyzer.analyze_scope(analysis_targets)
+            _ok({
+                "files_indexed": analysis_result["indexed_assets"],
+                "changed_files_count": len(file_paths),
+                "analysis_targets_count": analysis_result["analysis_targets_count"],
+                "diff_scope": diff_scope,
+                "framework_analysis": analysis_result,
+                "context_projection": _best_effort_project_context(repo_path),
+            })
+        except Exception as e:
+            _err(str(e))
+
+    # ── sync_from_commit ───────────────────────────────────────────────────────
+    # Accepts: { "commit_hash": "abc123", "repo_slug": "...", "workspace": "..." }
+    elif args.action in ("sync_from_commit", "sync_bitbucket"):
+        commit_hash = payload.get("commit_hash")
+        if not commit_hash:
+            _err("Missing commit_hash")
+
+        try:
+            from src.connectors.bitbucket_connector import BitbucketConnector
+            connector = BitbucketConnector()
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            analyzer = FrameworkAnalyzerAgent(repo_path)
+            repo_slug = payload.get("repo_slug", "")
+            workspace = payload.get("workspace", "")
+
+            # Fetch changed files from Bitbucket API
+            file_diffs = connector.fetch_file_locs(repo_slug, commit_hash, workspace)
+            changed_paths = [Path(f["file_path"]) for f in file_diffs]
+
+            # Diff Analyzer first, then scope-limited delta sync.
+            local_changed = [repo_path / p for p in changed_paths if (repo_path / p).exists()]
+            diff_scope = analyze_diff_scope(repo_path, local_changed)
+            analysis_targets = [
+                repo_path / p for p in diff_scope.get("analysis_targets", [])
+                if (repo_path / p).exists()
+            ]
+            analysis_result = analyzer.analyze_scope(analysis_targets)
+
+            _ok({
+                "synced_commit": commit_hash,
+                "files_found": len(file_diffs),
+                "files_indexed": analysis_result["indexed_assets"],
+                "analysis_targets_count": analysis_result["analysis_targets_count"],
+                "changed_files": [str(p) for p in changed_paths],
+                "diff_scope": diff_scope,
+                "framework_analysis": analysis_result,
+                "context_projection": _best_effort_project_context(repo_path),
+            })
+        except Exception as e:
+            _err(str(e))
+
+    # ── analyze_framework_scope ───────────────────────────────────────────────
+    # Accepts: { "changed_files": [...], "repo_path": "..." }
+    elif args.action == "analyze_framework_scope":
+        changed_files = payload.get("changed_files")
+        if not changed_files or not isinstance(changed_files, list):
+            _err("Missing or invalid changed_files list")
+
+        try:
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            analyzer = FrameworkAnalyzerAgent(repo_path)
+            file_paths = [Path(f) for f in changed_files]
+            diff_scope = analyze_diff_scope(repo_path, file_paths)
+            analysis_targets = [
+                repo_path / p for p in diff_scope.get("analysis_targets", [])
+                if (repo_path / p).exists()
+            ]
+            analysis_result = analyzer.analyze_scope(analysis_targets)
+            _ok({
+                "changed_files_count": len(file_paths),
+                "diff_scope": diff_scope,
+                "framework_analysis": analysis_result,
+            })
+        except Exception as e:
+            _err(str(e))
+
+    # ── project_context_cache ─────────────────────────────────────────────────
+    # Accepts: { "repo_path": "..." }
+    elif args.action == "project_context_cache":
+        try:
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            builder = ContextProjectionBuilder(repo_path)
+            result = builder.build()
+            _ok(result)
+        except Exception as e:
+            _err(str(e))
+
+    # ── enrich_requirement_context ───────────────────────────────────────────
+    # Accepts: {
+    #   "jira_key": "QCL-1762",
+    #   "context_text": "...",
+    #   "changed_files": ["tests/...", ...],
+    #   "repo_path": "..."
+    # }
+    elif args.action == "enrich_requirement_context":
+        jira_key = payload.get("jira_key")
+        context_text = payload.get("context_text")
+        if not jira_key:
+            _err("Missing jira_key")
+        if not context_text or not str(context_text).strip():
+            _err("Missing context_text")
+
+        try:
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            changed_files = payload.get("changed_files")
+            if changed_files is not None and not isinstance(changed_files, list):
+                _err("Invalid changed_files: must be a list of file paths")
+
+            result = sync_requirement_context(
+                repo_root=repo_path,
+                jira_key=jira_key,
+                context_text=str(context_text),
+                changed_files=changed_files,
+            )
+
+            _ok({
+                "jira_key": result.jira_key,
+                "requirement_id": result.requirement_id,
+                "affected_files": result.affected_files,
+                "affected_files_count": len(result.affected_files),
+                "mapped_assets": result.mapped_assets,
+                "requirement_context_path": result.requirement_context_path,
+                "context_projection": result.projection,
+            })
+        except Exception as e:
+            _err(str(e))
+
+    # ── enrich_framework_context ────────────────────────────────────────────
+    # Accepts: {
+    #   "repo_path": "...",
+    #   "context_paths": ["tests/context.md", ...],
+    #   "changed_files": ["tests/e2e/test_login.py", ...],
+    #   "persist_only": true
+    # }
+    elif args.action == "enrich_framework_context":
+        try:
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            context_paths = payload.get("context_paths")
+            changed_files = payload.get("changed_files")
+            persist_only = bool(payload.get("persist_only", False))
+
+            if context_paths is not None and not isinstance(context_paths, list):
+                _err("Invalid context_paths: must be a list of context.md paths")
+            if changed_files is not None and not isinstance(changed_files, list):
+                _err("Invalid changed_files: must be a list of file paths")
+
+            framework_analysis = None
+            if changed_files:
+                analyzer = FrameworkAnalyzerAgent(repo_path)
+                file_paths = [Path(f) for f in changed_files]
+                diff_scope = analyze_diff_scope(repo_path, file_paths)
+                analysis_targets = [
+                    repo_path / p for p in diff_scope.get("analysis_targets", [])
+                    if (repo_path / p).exists()
+                ]
+                framework_analysis = {
+                    "diff_scope": diff_scope,
+                    "analysis": analyzer.analyze_scope(analysis_targets),
+                }
+
+            enriched = enrich_context_files(
+                repo_path,
+                context_paths=context_paths,
+                rewrite_files=not persist_only,
+            )
+            projection = _best_effort_project_context(repo_path)
+
+            _ok({
+                "enriched_count": len(enriched),
+                "enriched": [
+                    {
+                        "path": r.path,
+                        "folder": r.folder,
+                        "files_scanned": r.files_scanned,
+                        "python_files": r.python_files,
+                        "dependency_edges": r.dependency_edges,
+                        "key_assets": r.key_assets,
+                    }
+                    for r in enriched
+                ],
+                "framework_analysis": framework_analysis,
+                "persist_only": persist_only,
+                "context_projection": projection,
+            })
+        except Exception as e:
+            _err(str(e))
+
+    # ── update_context_file ─────────────────────────────────────────────────
+    # Accepts: {
+    #   "context_path": "tests/e2e/context.md",
+    #   "repo_path": "...",
+    #   "changed_files": ["tests/e2e/test_login.py"]
+    # }
+    elif args.action == "update_context_file":
+        context_path = payload.get("context_path")
+        if not context_path:
+            _err("Missing context_path")
+
+        try:
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            changed_files = payload.get("changed_files")
+            if changed_files is not None and not isinstance(changed_files, list):
+                _err("Invalid changed_files: must be a list of file paths")
+
+            framework_analysis = None
+            if changed_files:
+                analyzer = FrameworkAnalyzerAgent(repo_path)
+                file_paths = [Path(f) for f in changed_files]
+                diff_scope = analyze_diff_scope(repo_path, file_paths)
+                analysis_targets = [
+                    repo_path / p for p in diff_scope.get("analysis_targets", [])
+                    if (repo_path / p).exists()
+                ]
+                framework_analysis = {
+                    "diff_scope": diff_scope,
+                    "analysis": analyzer.analyze_scope(analysis_targets),
+                }
+
+            enriched = enrich_context_files(repo_path, context_paths=[str(context_path)])
+            if not enriched:
+                _err(f"No context.md file found for context_path: {context_path}")
+
+            projection = _best_effort_project_context(repo_path)
+            first = enriched[0]
+            _ok({
+                "updated": {
+                    "path": first.path,
+                    "folder": first.folder,
+                    "files_scanned": first.files_scanned,
+                    "python_files": first.python_files,
+                    "dependency_edges": first.dependency_edges,
+                    "key_assets": first.key_assets,
+                },
+                "framework_analysis": framework_analysis,
+                "context_projection": projection,
+            })
+        except Exception as e:
+            _err(str(e))
+
+    # ── impact_analysis ────────────────────────────────────────────────────────
+    # Accepts: { "changed_files": ["path/to/file.py", ...], "repo_path": "..." }
+    elif args.action == "impact_analysis":
+        changed_files = payload.get("changed_files")
+        if not changed_files or not isinstance(changed_files, list):
+            _err("Missing or invalid changed_files list")
+
+        try:
+            from src.agents.regression_agent import RegressionAgent
+            repo_path = Path(payload.get("repo_path", str(Path.cwd())))
+            changed_paths = [Path(f) for f in changed_files]
+            agent = RegressionAgent()
+            impact = agent.analyze_impact(changed_paths, repo_path)
+            _ok({"impact": impact})
+        except Exception as e:
+            _err(str(e))
+
+    # ── submit_feedback ────────────────────────────────────────────────────────
+    elif args.action == "submit_feedback":
+        level = payload.get("level")
+        target_id = payload.get("target_id")
+        feedback_type = payload.get("feedback_type")
+        user_comment = payload.get("user_comment", "")
+
+        if not all([level, target_id, feedback_type]):
+            _err("Missing required fields: level, target_id, feedback_type")
+
+        try:
+            from src.agents.feedback_agent import FeedbackAgent
+            agent = FeedbackAgent()
+            stored = agent.submit(
+                level=level,
+                target_id=target_id,
+                feedback_type=feedback_type,
+                user_comment=user_comment,
+                corrected_data=payload.get("corrected_data"),
+            )
+            _ok({"stored": stored, "target_id": target_id, "level": level})
+        except Exception as e:
+            _err(str(e))
+
+    # ── init_project / init_check ─────────────────────────────────────────────
+    # Both are read-only pre-flight connectivity checks — no side effects (no scaffolding).
+    elif args.action in ("init_project", "init_check"):
+        try:
+            from src.project.init_check import run_checks
+            checks = run_checks()
+            _ok(checks)
+        except Exception as e:
+            _err(str(e))
+
+    # ── scaffold_ai_folder ─────────────────────────────────────────────────────
+    elif args.action == "scaffold_ai_folder":
+        repo_path = Path(payload.get("repo_path") or _PROJECT_ROOT)
+        try:
+            from src.project.ai_folder import scaffold_ai_folder, detect_repo_root
+            root = detect_repo_root(repo_path)
+            scaffold_ai_folder(root)
+            _ok({"scaffolded": str(root / ".ai")})
+        except Exception as e:
+            _err(str(e))
+
+    # ── sync_push_event ────────────────────────────────────────────────────────
+    elif args.action == "sync_push_event":
+        webhook_payload = payload.get("payload")
+        signature = payload.get("signature")
+        if not webhook_payload:
+            _err("Missing required field: payload (Bitbucket webhook body)")
+        try:
+            from src.connectors.bitbucket_connector import BitbucketConnector
+            connector = BitbucketConnector()
+            # Optional HMAC signature validation
+            if signature:
+                import json as _json
+                raw_body = _json.dumps(webhook_payload).encode()
+                if not connector.validate_webhook_signature(raw_body, signature):
+                    _err("Webhook signature validation failed")
+            result = connector.sync_pull_event(webhook_payload)
+            _ok(result if isinstance(result, dict) else {"result": str(result)})
+        except Exception as e:
+            _err(str(e))
+
+    # ── get_project_status ─────────────────────────────────────────────────────
+    elif args.action == "get_project_status":
+        repo_path = Path(payload.get("repo_path") or _PROJECT_ROOT)
+        try:
+            from src.project.ai_folder import rebuild_system_state_from_db, detect_repo_root
+            root = detect_repo_root(repo_path)
+            summary = rebuild_system_state_from_db(root)
+            _ok(summary)
+        except Exception as e:
+            _err(str(e))
+
+
+if __name__ == "__main__":
+    main()
+