MTA-7135: Agent Mode Compilation Guardrails AST Verification

[anarnold97]

---

JIRA

• MTA-7135

---

PREVIEW

• 1.5. Output verification and agent mode guardrails
  • 1.5.1. Agent mode code quality safeguards
  • 1.5.2. Agent mode validation checks
  • 1.5.3. Autocorrection on compilation failure

---

DESCRIPTION

Add documentation for Agent Mode guardrails and the build-tool validation loop introduced in MTA-7135.

New content:

• con_agent-mode-guardrails.adoc — explains how the extension passes each AI-generated code suggestion through a local build dry-run (mvn compile, gradle compileJava, npm run build, or yarn build) before applying it to the workspace, covering syntax verification, method signature and classpath resolution, import consistency checks, and the auto-correction retry loop on compilation failure

• proc_enabling-agent-mode.adoc — step-by-step procedure for enabling Agent Mode via the VS Code command palette or settings panel, with a verification example using the Lightspeed output panel
  The two new modules are included in assembly_understanding_dl.adoc after the existing Agent AI concept and before the benefits reference.

Summary by CodeRabbit

• Documentation
  • Added guidance on enabling Agent Mode in the Lightspeed VS Code extension, including prerequisites and restart/verification expectations.
  • Introduced new Agent Mode “guardrails” content describing local build dry-run verification before suggestions are applied.
  • Documented Agent Mode validation checks (syntax, signature/reference resolution, and dependency consistency).
  • Explained autocorrection behavior on compilation failures, including retry limits and handling unverified suggestions.
  • Updated the “Understanding {mta-dl-full}” documentation flow to include the new Agent Mode topics.

[coderabbitai]

📝 Walkthrough

Walkthrough

Agent Mode documentation now covers local validation guardrails, validation checks, compiler-failure autocorrection, and enablement. The developer-lightspeed assembly includes the new concept, reference, and procedure pages before the benefits content.

Changes

Agent Mode Documentation

Layer / File(s)	Summary
Agent Mode validation and autocorrection docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc, docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc, docs/topics/developer-lightspeed/con_agent-mode-autocorrection.adoc	Adds documentation for local dry-run guardrails, syntax and dependency checks, compiler-diagnostic retries, and unverified output handling.
Enabling agent mode docs/topics/developer-lightspeed/proc_enabling-agent-mode.adoc	Adds prerequisites, two enablement workflows, language-server restart instructions, and a verification example.
Assembly page integration docs/topics/developer-lightspeed/assembly_understanding_dl.adoc	Includes the new Agent Mode topics before the benefits section and retains the surrounding conditional and attribute cleanup directives.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: djzager, rromannissen

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and matches the PR’s main focus on Agent Mode compilation guardrails and verification documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Pkylas007]

Suggested minor clarification questions.

LGTM, thanks!

[rromannissen]

Overall LGTM, but the bit about refining the prompt needs to be changed.

[mpershina]

Left some suggestions.

[mpershina]

Just some minor suggestions, otherwise, LGTM!

[anarnold97]

@rromannissen - please can you re-review as your "request changes" is blocking us from merging

thanks

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc`:
- Line 28: Update the dry-run behavior description near the {mta-dl-plugin} flow
to state that automatic correction is attempted only for minor errors and is
limited to two attempts, after which the output is marked unverified. Preserve
the existing successful dry-run approval behavior and avoid implying that all
errors trigger correction.
- Around line 15-19: Reword the verification-mechanism bullets in the developer
lightspeed guardrails documentation to state that compilation or a dry run can
detect syntax errors and unresolved or incompatible references, without claiming
it validates API-call semantics or catches deprecated methods. Qualify the
hallucinated API and removed/deprecated method bullets accordingly, and retain
the existing syntactically broken output coverage.

In `@docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc`:
- Around line 16-18: Update the “Method signature and reference checks” and
“Import and dependency consistency” descriptions to use ecosystem-neutral
dependency and module-resolution terminology. Cover both Java Maven/Gradle
projects and JavaScript/TypeScript npm/Yarn projects without implying that all
checks use a compiler or classpath; split the explanations by ecosystem where
needed while preserving the existing validation behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4c0230dd-0666-4d00-b4fd-124e57dea2c3

📥 Commits

Reviewing files that changed from the base of the PR and between 22fcad9 and d07df22.

📒 Files selected for processing (5)

• docs/topics/developer-lightspeed/assembly_understanding_dl.adoc
• docs/topics/developer-lightspeed/con_agent-mode-autocorrection.adoc
• docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc
• docs/topics/developer-lightspeed/proc_enabling-agent-mode.adoc
• docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/topics/developer-lightspeed/assembly_understanding_dl.adoc
• docs/topics/developer-lightspeed/proc_enabling-agent-mode.adoc

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Qualify what compilation can verify.

A dry run can catch syntax errors and unresolved or incompatible references, but compilation alone does not prove that a resolved API call is semantically correct, and deprecated methods commonly remain compilable. Reword these bullets to avoid implying unconditional protection against all listed risks.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc` around lines
15 - 19, Reword the verification-mechanism bullets in the developer lightspeed
guardrails documentation to state that compilation or a dry run can detect
syntax errors and unresolved or incompatible references, without claiming it
validates API-call semantics or catches deprecated methods. Qualify the
hallucinated API and removed/deprecated method bullets accordingly, and retain
the existing syntactically broken output coverage.

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== candidate files =="
git ls-files | rg 'docs/topics/developer-lightspeed/(ref_agent-mode-validation-checks|con_agent-mode-guardrails)\.adoc$|agent-mode|lightspeed|dependency' || true

echo "== target snippet =="
if [ -f docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc ]; then
  nl -ba docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc | sed -n '1,80p'
fi

echo "== guardrails snippet =="
if [ -f docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc ]; then
  nl -ba docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc | sed -n '1,120p'
fi

echo "== references to mta-dl-plugin/classpath/module resolution in docs =="
rg -n "mta-dl-plugin|classpath|module-resolution|package\.json|npm|yarn|dependency" docs/topics/developer-lightspeed docs || true

echo "== source references to classpath/package.json =="
rg -n "classpath|package\.json|resolveAll|Import.*statement|missing or incorrect imports|npm|yarn" --glob '!build/**' --glob '!target/**' --glob '!dist/**' || true

Repository: migtools/mta-documentation

Length of output: 2746

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== candidate files =="
git ls-files | rg 'docs/topics/developer-lightspeed/(ref_agent-mode-validation-checks|con_agent-mode-guardrails)\.adoc$|agent-mode|lightspeed|dependency' || true

echo "== target snippet =="
if [ -f docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc ]; then
  nl -ba docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc | sed -n '1,80p'
fi

echo "== guardrails snippet =="
if [ -f docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc ]; then
  nl -ba docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc | sed -n '1,120p'
fi

echo "== references in docs/topics/developer-lightspeed =="
rg -n "mta-dl-plugin|classpath|module-resolution|package\.json|npm|yarn|dependency" docs/topics/developer-lightspeed || true

echo "== broader source references to classpath/package.json/npm/yarn =="
rg -n "classpath|package\.json|resolveAll|Import.*statement|missing or incorrect imports|npm|yarn" --glob '!build/**' --glob '!target/**' --glob '!dist/**' || true

Repository: migtools/mta-documentation

Length of output: 2746

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== candidate files =="
git ls-files | rg 'docs/topics/developer-lightspeed/(ref_agent-mode-validation-checks|con_agent-mode-guardrails)\.adoc$|agent-mode|lightspeed|dependency' || true

echo "== target snippet =="
if [ -f docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc ]; then
  nl -ba docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc | sed -n '1,100p'
fi

echo "== guardrails snippet =="
if [ -f docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc ]; then
  nl -ba docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc | sed -n '1,140p'
fi

echo "== references in docs/topics/developer-lightspeed =="
rg -n "mta-dl-plugin|classpath|module-resolution|package\.json|npm|yarn|dependency" docs/topics/developer-lightspeed || true

Repository: migtools/mta-documentation

Length of output: 2746

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== target file lines 1-120 =="
sed -n '1,120p' docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc

echo "== guardrails file lines 1-120 =="
sed -n '1,120p' docs/topics/developer-lightspeed/con_agent-mode-guardrails.adoc

echo "== dependencies/build manifests referenced in docs/topics/developer-lightspeed =="
rg -n "pom\.xml|build\.gradle|package\.json|npm|yarn|classpath|mta-dl-plugin|Import|import|type" docs/topics/developer-lightspeed || true

Repository: migtools/mta-documentation

Length of output: 32325

---

Use ecosystem-neutral dependency terminology throughout agent mode docs.

These checks apply to package.json/npm/Yarn-backed JavaScript and TypeScript projects as well as Maven/Gradle Java projects, so wording like “compiler resolves … against your project’s full dependency classpath” and “import statement … corresponds to a type available on the classpath” is misleading for Node toolchains. Split the Java and JavaScript/TypeScript explanations, or use neutral terms such as dependency/module-resolution context.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/topics/developer-lightspeed/ref_agent-mode-validation-checks.adoc`
around lines 16 - 18, Update the “Method signature and reference checks” and
“Import and dependency consistency” descriptions to use ecosystem-neutral
dependency and module-resolution terminology. Cover both Java Maven/Gradle
projects and JavaScript/TypeScript npm/Yarn projects without implying that all
checks use a compiler or classpath; split the explanations by ecosystem where
needed while preserving the existing validation behavior.

[rromannissen]

LGTM!