Target State Alignment AI Pipeline

1. Use `Poetry` for dependency management.
2. The project should have a CLI entry point (using `Typer`).
3. Include standard Python best practices (e.g., `src` layout).
4. Provide a `Dockerfile` optimized for running in GitLab CI.

• Base Image: `python:3.11-slim`.
• Must install `git` (essential for the agent's operation).
• Install Poetry and dependencies efficiently.

1. Use `Pydantic v2` to define models:
   • `TaskStatus` (Enum: PENDING, IN_PROGRESS, COMPLETED, FAILED).
   • `Task` (id: int, name: str, priority: int, status: TaskStatus).
   • `ModernizationPlan` (tasks: list[Task]).
   • `HistoryLogEntry` (timestamp: datetime, task_id: int, action: str, details: dict).
2. The `StateManager` should be initialized with the project root path.
3. Implement methods for:
   • `is_initialized()`: Verifies the `.ai` directory exists.
   • `load_plan()`: Reads and validates `modernization_plan.yml`.
   • `save_plan(plan: ModernizationPlan)`: Writes the plan back to YAML.
   • `get_next_task()`: Finds the highest priority `PENDING` task.
   • `update_task_status(task_id: int, status: TaskStatus)`
   • `log_history(...)`: Creates and appends a `HistoryLogEntry` to `refinement_history.log` (JSONL).
   • `load_failure_context()`: Reads `last_run_failure.md`.

1. Use `GitPython` for local Git operations.
2. Use `python-gitlab` for GitLab API interactions.
3. The class should be initialized with GitLab connection details (URL, Project ID, Access Token) loaded securely.
4. Implement methods for:
   • `initialize_repo(local_path: str)`
   • `create_and_checkout_branch(branch_name: str)`
   • `checkout_default_branch()`
   • `commit_changes(message: str)`: Stage all changes and commit.
   • `push_branch(branch_name: str)`
   • `create_merge_request(source_branch: str, target_branch: str, title: str, description: str)`: Create MR and set to remove source branch on merge.

1. Recursively scan a given directory path.
2. Identify key technologies based on file presence:
   • Build Tools: Detect Maven (`pom.xml`), Gradle (`build.gradle`), npm (`package.json`).
   • Languages: Detect primary languages (Java, Python, JS/TS).
   • Infrastructure: Detect `Dockerfile`, Terraform/OpenTofu files (`.tf`).
   • Tests: Identify common test directories (`src/test`, `tests`).
3. The output should be a structured dictionary summarizing the findings, ready for LLM processing.

{"languages": ["Java"], "build_tools": ["Maven"], "infra_files": ["Dockerfile"], "test_dirs": ["src/test/java"]}

1. The `Orchestrator` initializes the `StateManager`, `GitManager`, `Analyzer`, and `LLMInterface`.
2. Implement the `execute()` method.
3. `execute()` logic:
   • Check status using `StateManager.is_initialized()`.
   • If initialized, call `run_refinement_workflow()`.
   • If not initialized, call `run_initialization_workflow()`.
4. Implement the workflow methods, detailing the steps by coordinating the different managers (e.g., in `run_initialization_workflow()`, call analyzer, then LLMInterface for prompts, then StateManager to save, then GitManager to commit the `.ai` directory).

1. `[TASK_DETAILS]`: The specific task description from `modernization_plan.yml`.
2. `[TSA_CONTEXT]`: Relevant snippets from the Target State Architecture.
3. `[RELEVANT_FILES]`: Contents of files relevant to the task (Path: Content dictionary).
4. `[FAILURE_CONTEXT]` (Optional): Content from `last_run_failure.md`.

1. Instruct the LLM to act as an expert AI Software Engineer.
2. Adhere strictly to the scope of the current task.
3. Emphasize "Safety First": Do not break existing functionality.
4. Crucial: If `[FAILURE_CONTEXT]` is provided, the LLM MUST understand the root cause and implement the suggested remediation strategy.
5. The output must be a structured JSON object so the agent can easily parse and apply changes.

{
  "explanation": "A technical summary of the changes applied and any remediation strategy used.",
  "files": [
    {
      "path": "path/to/file.java",
      "action": "modify", // modify, create, delete
      "content": "[FULL NEW CONTENT OF THE FILE]"
    }
  ]
}

1. Implement `trigger_pipeline(branch_name: str)`.
   • Use the GitLab API to create a new pipeline for the specified branch.
   • Return the pipeline object (including ID and URL).
2. Implement `monitor_pipeline(pipeline_id: int, timeout_seconds=1800)`.
   • Poll the GitLab API periodically (e.g., every 30 seconds) to check the status.
   • Wait until the status is terminal (`success`, `failed`, `canceled`).
   • Handle timeouts.
   • Return the final status string.

1. Implement `get_failed_pipeline_logs(pipeline_id: int)`.
2. Logic:
   • List all jobs in the pipeline via the GitLab API.
   • Identify jobs with the status 'failed'.
   • For each failed job, fetch the job trace (logs).
   • Concatenate the logs, clearly demarcating which log belongs to which job.

1. `[ATTEMPTED_TASK]`: Description of the task.
2. `[ATTEMPTED_CHANGES_SUMMARY]`: The "explanation" from the failed execution attempt.
3. `[RAW_PIPELINE_LOGS]`: Full logs from the failed jobs.

1. Instruct the LLM to act as a senior developer debugging the failure.
2. Pinpoint the exact error message, stack trace, or failed test case.
3. Formulate a hypothesis for the root cause (e.g., incompatible dependency, missed configuration, unexpected API change).
4. Propose a detailed, actionable strategy to fix the issue on the next attempt. This strategy must be precise enough for the Task Execution Prompt to utilize.

• Observed Failure (including exact log snippets)
• Root Cause Hypothesis
• Suggested Remediation Strategy

1. `[TASK_DETAILS]`: Specific area requiring coverage (e.g., "Add unit tests for UserService").
2. `[TARGET_CODE]`: The source code of the class/module to be tested.
3. `[PROJECT_CONTEXT]`: The frameworks used (e.g., JUnit 5, Mockito, Pytest).
4. `[STYLE_EXAMPLES]` (Optional): Examples of existing tests to maintain consistency.

1. Analyze the target code for execution paths, edge cases, and potential failures.
2. Generate comprehensive tests covering these scenarios.
3. Ensure tests adhere to the project's existing framework and style.
4. Output must be complete, runnable test file(s) in the standard structured JSON format (as defined in Story 2.2).