release/1.14.0

CITATION.cff

@@ -9,7 +9,7 @@ authors:
 repository-code: "https://github.com/tmseidel/ai-git-bot"
 url: "https://github.com/tmseidel/ai-git-bot"
 license: "MIT"
-version: "1.13.0"
+version: "1.14.0"
 keywords:
   - "ai-code-review"
   - "code-review-bot"

Dockerfile

@@ -38,6 +38,7 @@ ENV DEBIAN_FRONTEND=noninteractive \
 RUN apt-get update && apt-get install -y --no-install-recommends \
         ca-certificates curl wget git bash gnupg lsb-release apt-transport-https \
         unzip xz-utils tini \
+        universal-ctags \
         maven \
         python3 python3-pip python3-venv \
         golang-go \

codemeta.json

@@ -6,7 +6,7 @@
   "url": "https://github.com/tmseidel/ai-git-bot",
   "issueTracker": "https://github.com/tmseidel/ai-git-bot/issues",
   "license": "https://spdx.org/licenses/MIT.html",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "programmingLanguage": [
     "Java",
     "HTML",

doc/MIGRATION_1.13_TO_1.14.md

@@ -0,0 +1,222 @@
+# Migration Guide: AI-Git-Bot 1.13 → 1.14
+
+> **Target audience:** operators upgrading an existing 1.13.x deployment to
+> the 1.14.0 release, which adds two new CONTEXT tools for code-base structure
+> extraction and upgrades the Docker runtime image to Ubuntu Noble.
+
+This release adds two agent-invokable tools —
+`ctags-signatures` and `ctags-deps` — that let the AI agent extract
+function/class/method signatures and dependency graphs from source files using
+Universal Ctags. A new `universal-ctags` package is required in the runtime
+image. The tools are automatically enabled in the **default** bot tool
+configuration but must be activated manually for any **custom** tool
+configurations.
+
+If you are upgrading from 1.12, also read
+[`MIGRATION_1.12_TO_1.13.md`](./MIGRATION_1.12_TO_1.13.md) first.
+
+---
+
+## TL;DR — for impatient operators
+
+1. **Replace the Docker image.** The new image includes `universal-ctags`
+   (Ubuntu Noble package). No other runtime dependency changes are needed.
+2. **Flyway applies `V29` on first boot.** It adds `ctags-signatures` and
+   `ctags-deps` to the **default** tool configuration. Bots using the default
+   configuration gain access to the new tools immediately.
+3. **Custom tool configurations are NOT touched.** If you created your own
+   tool configuration (anything other than the system-provided "Default"),
+   you must manually enable the two new tools via **System settings →
+   Tool configurations**. See § 2 below.
+
+---
+
+## 1. What changed
+
+| Area | 1.13.x | 1.14.0 |
+|---|---|---|
+| Context tools available | `rg`, `find`, `cat`, `git-log`, `git-blame`, `tree`, `branch-switcher` | Same as 1.13 + `ctags-signatures` and `ctags-deps` |
+| Default tool configuration | V12 seed (15 built-in tools) | V29 extends default with 2 additional CONTEXT tools |
+| Custom tool configurations | Not affected by V12 or V29 (admins manage them) | **Not affected by V29** — must be updated manually |
+| Docker runtime base | `eclipse-temurin:21-jre-noble` | Same base image (no change), but `universal-ctags` package installed |
+| Application config | No new properties | No new properties required |
+
+### New tools
+
+| Tool | Kind | Roles | Description |
+|---|---|---|---|
+| `ctags-signatures` | CONTEXT | CODING, WRITER | Extract function, class, method, and interface signatures from a source file. Returns a compact structural map — no implementation details. |
+| `ctags-deps` | CONTEXT | CODING, WRITER | Extract imports, includes, and namespace/package declarations from a source file. Returns JSON with declared namespace and all external dependencies. |
+
+Both tools are **silent** (output is never posted as a public comment) and
+require a single argument: the repository-relative file path.
+
+---
+
+## 2. Enabling the new tools on custom configurations
+
+### 2.1 Default configuration — no action needed
+
+Flyway `V29` extends the **default** tool configuration automatically.
+Bots that use the system-provided "Default" configuration (every bot that
+was never explicitly assigned a different configuration) gain access to
+`ctags-signatures` and `ctags-deps` on first boot after upgrade.
+
+You can verify this in **System settings → Tool configurations**:
+the "Default" row should list both `ctags-signatures` and `ctags-deps`
+under the CONTEXT section.
+
+### 2.2 Custom configurations — manual activation required
+
+Flyway `V29` does **not** touch non-default tool configurations. This is
+intentional: operators who maintain custom configurations should control
+exactly which tools their bots can invoke.
+
+For each custom tool configuration you maintain:
+
+1. Open **System settings → Tool configurations**.
+2. Click the configuration name to open its editor.
+3. In the **CONTEXT tools** section, check the boxes for:
+   - `ctags-signatures`
+   - `ctags-deps`
+4. Save.
+
+Bots assigned to that configuration will gain access to the new tools
+immediately (no restart required).
+
+### 2.3 Checking which configurations need updating
+
+Run this query against your database to list all non-default
+configurations and whether they include the new tools:
+
+```sql
+-- PostgreSQL
+SELECT c.name,
+       c.default_entry,
+       COUNT(s.tool_name) FILTER (WHERE s.tool_name IN ('ctags-signatures', 'ctags-deps')) AS new_tools_present
+FROM bot_tool_configurations c
+LEFT JOIN bot_tool_selections s ON s.configuration_id = c.id
+WHERE NOT c.default_entry
+GROUP BY c.id, c.name, c.default_entry
+ORDER BY c.name;
+```
+
+Any configuration with `new_tools_present < 2` needs manual updating.
+
+```sql
+-- H2
+SELECT c.name,
+       c.default_entry,
+       COUNT(CASE WHEN s.tool_name IN ('ctags-signatures', 'ctags-deps') THEN 1 END) AS new_tools_present
+FROM bot_tool_configurations c
+LEFT JOIN bot_tool_selections s ON s.configuration_id = c.id
+WHERE NOT c.default_entry
+GROUP BY c.id, c.name, c.default_entry
+ORDER BY c.name;
+```
+
+---
+
+## 3. Docker image changes
+
+### 3.1 New runtime dependency: `universal-ctags`
+
+The `universal-ctags` package is installed in the runtime image
+(`apt-get install universal-ctags`). It provides 135+ language parsers
+and is invoked by the new tools via `ProcessBuilder`.
+
+If you build your own Docker image, add the package to your `apt-get`
+step:
+
+```dockerfile
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        universal-ctags \
+        ...
+```
+
+### 3.2 No base image change
+
+The runtime base image remains `eclipse-temurin:21-jre-noble`. No
+additional `FROM` changes are required.
+
+### 3.3 Image size impact
+
+The `universal-ctags` package adds approximately 2 MB to the runtime
+image. Total image size increase is negligible.
+
+---
+
+## 4. Database migration
+
+Flyway migration **`V29`** adds two rows to the default tool
+configuration's selection table. It is idempotent — running the
+migration multiple times (e.g., after a `flyway repair`) is safe.
+
+```sql
+INSERT INTO bot_tool_selections (configuration_id, tool_name, tool_kind)
+SELECT c.id, v.tool_name, v.tool_kind
+FROM bot_tool_configurations c
+CROSS JOIN (VALUES
+    ('ctags-signatures', 'CONTEXT'),
+    ('ctags-deps',       'CONTEXT')
+) AS v(tool_name, tool_kind)
+WHERE c.default_entry = TRUE
+  AND NOT EXISTS (
+      SELECT 1 FROM bot_tool_selections s
+      WHERE s.configuration_id = c.id AND s.tool_name = v.tool_name
+  );
+```
+
+**No other tables, columns, or constraints are modified.** The migration
+only inserts rows; it never deletes or alters existing data.
+
+**Rollback.** If you roll back the application binary after V29 has
+executed, the two new rows will remain in `bot_tool_selections`. The
+1.13.x application's `ToolCatalog` does not register these tool names,
+so they will appear as `ToolKind.UNKNOWN` and be rejected by the
+whitelist enforcement in `AgentToolRouter`. No runtime errors occur,
+but the rows are harmless dead data. You can delete them manually if
+desired:
+
+```sql
+DELETE FROM bot_tool_selections WHERE tool_name IN ('ctags-signatures', 'ctags-deps');
+```
+
+---
+
+## 5. Environment variable and config changes
+
+**No new application properties are required.** The new tools use the
+existing `agent.validation.tool-timeout-seconds` timeout when invoking
+ctags. No new `application.properties` or `application.yml` keys are
+introduced.
+
+---
+
+## 6. Behaviour notes
+
+- **Tools are opt-in per bot.** A bot only has access to the new tools
+  if its assigned tool configuration includes them. Bots using the
+  default configuration get them automatically; bots with custom
+  configurations need manual activation.
+- **ctags must be on PATH.** The runtime image includes `universal-ctags`
+  at `/usr/bin/ctags`. If ctags is missing, the tools return a non-zero
+  exit code error to the AI agent (same pattern as `git-log` and
+  `git-blame` when `git` is unavailable).
+- **Silent tools.** Like all CONTEXT tools, `ctags-signatures` and
+  `ctags-deps` never appear in public PR/issue comments. Their output is
+  visible only to the AI agent.
+- **No UI changes.** The tools appear in the System Settings → Tool
+  Configurations editor under the CONTEXT section, alongside the existing
+  `rg`, `find`, `cat`, `tree`, etc. No new UI pages or forms are added.
+
+---
+
+## 7. See also
+
+- [`MIGRATION_1.12_TO_1.13.md`](./MIGRATION_1.12_TO_1.13.md) — previous
+  migration guide (diff chunking settings).
+- [`MIGRATION_1.6_TO_1.7.md`](./MIGRATION_1.6_TO_1.7.md) — tool
+  configurations introduction (V11/V12 migrations).
+- [`doc/development-archive/code-base-truncation.md`](./development-archive/code-base-truncation.md) —
+  implementation plan for the code-base structure extraction tools.

doc/PR_WORKFLOWS.md

@@ -9,7 +9,7 @@ PR workflows are administrator-configured actions that run from pull-request web
 | Key | UI name | Default? | What it does |
 |---|---|---|---|
 | `review` | PR Review | Enabled on the seeded `Default` configuration | Posts a one-shot AI code review comment and applies the bot's configured post-review action. See [`PR_WORKFLOWS_REVIEW.md`](PR_WORKFLOWS_REVIEW.md). |
-| `agentic-review` | Agentic PR Review | Opt-in | Lets the model read repository/MCP context before posting a Markdown review comment. Read-only. See [`PR_WORKFLOWS_AGENTIC_REVIEW.md`](PR_WORKFLOWS_AGENTIC_REVIEW.md). |
+| `agentic-review` | Agentic PR Review | Opt-in | Lets the model read repository/MCP context before posting a Markdown review comment. Optionally posts formal review actions (approve/request-changes). See [`PR_WORKFLOWS_AGENTIC_REVIEW.md`](PR_WORKFLOWS_AGENTIC_REVIEW.md). |
 | `unit-test-author` | AI Unit Tests | Opt-in | Generates and runs unit tests for the PR diff; can commit passing tests to the PR branch. See [`PR_WORKFLOWS_UNIT_TEST.md`](PR_WORKFLOWS_UNIT_TEST.md). |
 | `e2e-test` | E2E Tests | Opt-in | Deploys or locates a PR preview, generates/runs E2E tests, and posts a summary. Requires a deployment target. See [`PR_WORKFLOWS_E2E.md`](PR_WORKFLOWS_E2E.md). |
 

doc/PR_WORKFLOWS_AGENTIC_REVIEW.md

@@ -28,9 +28,10 @@ enforcing this:
 2. **Execution routing** — tools are executed through
    `AgentToolRouter.Mode.WRITER`, which rejects any tool outside the read-only
    set even if the model tries to invoke one.
-3. **Workflow side-effects** — the workflow never commits, pushes, creates
-   branches or posts a formal review action (approve / request-changes). The
-   only externally visible effect is a single Markdown PR comment.
+3. **Workflow side-effects** — the workflow never commits, pushes, or creates
+   branches. The primary externally visible effect is a single Markdown PR
+   comment. When operators enable formal review decisions, the bot may
+   additionally approve or request changes based on the review findings.
 
 ## Flow
 
@@ -44,6 +45,7 @@ flowchart LR
     Strat --> Router["AgentToolRouter (WRITER)"]
     Router --> Tools["context tools + MCP"]
     Svc --> Comment["PR comment"]
+    Svc --> |when enabled| Action["PR review action<br/>(approve / request-changes)"]
 ```
 
 1. Resolve params and build the per-bot `AgentReviewService` (AI client,
@@ -53,6 +55,9 @@ flowchart LR
 4. Run `AgentLoop` with `ReviewAgentStrategy`. The model explores via tool
    calls; the first assistant turn **without** tool calls is the final review.
 5. Post the review as a PR comment (when enabled) and clean up the workspace.
+6. When formal review decisions are enabled: parse the model's structured
+   decision and submit it with the review body via `postReview` (approve /
+   request-changes / comment) as a single review.
 
 ## Parameters
 
@@ -62,8 +67,30 @@ Rendered automatically in the workflow-selection form from
 | Key | Type | Default | Description |
 |---|---|---|---|
 | `maxToolRounds` | integer | `12` | Upper bound (1–30) on explore/answer rounds while reading the repository. Higher = deeper analysis, higher token cost. |
+| `enableFormalReviewDecision` | boolean | `false` | When enabled, the bot may post a formal PR review decision (approve or request changes) based on the criteria configured in the approval decision prompt. |
+| `formalReviewDecisionPrompt` | text | *(built-in default)* | Criteria for when the bot should approve, request changes, or leave the PR review state unchanged. Only applies when formal review decisions are enabled. |
 
-The review is always posted as a PR comment.
+### Formal Review Decision
+
+When `enableFormalReviewDecision` is `true`:
+
+1. The operator-configured decision prompt and a fixed format instruction are
+   appended to the system prompt.
+2. The model must end its review with a single bare JSON object on the last
+   line (a fenced ```json block is also accepted as a tolerant fallback):
+
+       {"decision": "APPROVE"}
+
+3. Valid decision values: `APPROVE`, `REQUEST_CHANGES`, `NONE`.
+4. The parsed decision and the review body are submitted together via
+   `RepositoryApiClient.postReview(...)` as a single review.
+5. On unparseable output the review is still posted with no formal decision
+   (fail-open); if the formal submission fails it falls back to a plain
+   review comment so the findings are not lost.
+
+This works identically in native tool-calling mode and legacy JSON/chat mode:
+the structured decision is parsed from the final assistant output regardless
+of whether tools were used.
 
 ## System prompt
 
@@ -74,12 +101,18 @@ System-Prompt** on the *System settings → System prompts* page (entity column
 `SystemPromptAssembler` (using the `WRITER_AGENT` protocol template), so editing
 the prompt cannot break tool calling.
 
+When formal review decisions are enabled, two additional sections are appended:
+- The operator-configured decision criteria (editable per-workflow).
+- A fixed format instruction describing the required JSON decision block.
+
 ## Enabling it
 
 1. Open *System settings → Workflow configurations → Workflows* for the
    relevant configuration.
 2. Tick **Agentic PR Review** and (optionally) adjust its parameters.
-3. Assign that workflow configuration to the bot.
+3. To enable formal review decisions, tick **Enable formal review decision**
+   and customise the **Approval decision prompt** if desired. The textarea is
+   only editable when the checkbox is checked.
 
 Because the orchestrator only runs explicitly-selected workflows for bots that
 have a configuration, the agentic review never runs unless an operator enables
@@ -98,5 +131,5 @@ gathered context back, and iterates until the model replies with a plain-text
 review. The number of legacy context rounds is bounded by
 `agent.budget.max-context-rounds`.
 
-
-
+The structured decision format works in both modes — it is parsed from the
+final assistant output after the loop terminates.

doc/README.md

@@ -53,7 +53,7 @@ Cloud providers (Anthropic, OpenAI, Google AI / Gemini) only need an API key —
 | [Agentic PR Workflows (concept)](agentic-workflows/README.md) | Feature overview and persona-driven user stories for the workflow subsystem |
 | [Unit-Test Author Workflow](PR_WORKFLOWS_UNIT_TEST.md) | AI unit-test generation for PR diffs, supported runners, write-safety guards |
 | [Full-stack QA / E2E Workflow](PR_WORKFLOWS_E2E.md) | Per-PR preview environments, generated Playwright suites, teardown lifecycle |
-| [Agentic Review Workflow](PR_WORKFLOWS_AGENTIC_REVIEW.md) | Read-only agentic PR review with repository and MCP tool access |
+| [Agentic Review Workflow](PR_WORKFLOWS_AGENTIC_REVIEW.md) | Read-only agentic PR review with repository and MCP tool access; optional formal review action (approve/request-changes) |
 | [CI Action Recipes](PR_WORKFLOWS_CI_ACTIONS.md) | `CI_ACTION` deployment recipes per Git provider |
 | [Webhook Recipes](PR_WORKFLOWS_WEBHOOK_RECIPES.md) | `WEBHOOK` deployment recipes (Jenkins, scripts, …) |
 | [MCP Server Handling](MCP_SERVER_HANDLING.md) | Attaching remote MCP servers, tool whitelist selection, call transparency |