abapgit-agent 1.17.8 → 1.17.9

package/README.md

@@ -68,6 +68,7 @@ abapgit-agent syntax --files src/zcl_my_class.clas.abap   # Check syntax before
 abapgit-agent inspect --files src/zcl_my_class.clas.abap  # Code Inspector after pull
 abapgit-agent unit --files src/zcl_my_test.clas.testclasses.abap  # Run AUnit tests
 abapgit-agent run --class ZCL_MY_RUNNER                   # Execute class headlessly
+abapgit-agent run --program ZMY_PROGRAM                   # Execute report/program headlessly
 ```
 
 ### Explore

package/abap/CLAUDE.md

@@ -243,7 +243,7 @@ When a class needs local helper classes or test doubles, create separate include
 ```
 Adding .clas.testclasses.abap to an existing class?
   └── Update the .clas.xml → set WITH_UNIT_TESTS flag:
-        <clas:abapClassProperties ... abpUnitTestable="true" ... />
+        <WITH_UNIT_TESTS>X</WITH_UNIT_TESTS>   (inside the <VSEOCLASS> block)
       WITHOUT this flag, abapGit will not push/activate the test include.
 
 Adding .clas.locals_def.abap (local type definitions)?
@@ -424,6 +424,10 @@ abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.cla
 
 After activating a class, stop and tell the user: `"Class is activated. Run with: abapgit-agent run --class ZCL_MY_CLASS"`
 
+For ABAP programs (PROG type), use `--program` instead: `abapgit-agent run --program ZR_MY_REPORT`
+
+For how to write a runner class (`out->write()` usage, output format): `abapgit-agent ref --topic run-probe-classes`
+
 ---
 
 ### 10. Never Run `drop` Command Without Explicit Permission
@@ -559,12 +563,21 @@ Minimal correct sequence:
 ```bash
 abapgit-agent view --objects ZCL_FOO --full --lines  # 0. get exact line number from output hint
 abapgit-agent debug set --objects ZCL_FOO:42        # 1. set breakpoint (use line from step 0)
+#    ⚠️  Avoid: LOOP AT ... ASSIGNING headers — ADT registers them but ABAP runtime skips them
+#    Set BP on the first statement INSIDE the loop body instead
 abapgit-agent debug attach --json > /tmp/a.json 2>&1 &   # 2. attach (background)
 until grep -q "Listener active" /tmp/a.json 2>/dev/null; do sleep 0.3; done
-abapgit-agent unit --files src/zcl_foo.clas.testclasses.abap > /tmp/t.json 2>&1 &  # 3. trigger
-# poll for session, then inspect
+abapgit-agent unit --files src/zcl_foo.clas.testclasses.abap > /tmp/t.json 2>&1 &  # 3. trigger (background &)
+# 4. POLL until session appears — do NOT call vars/stack before this completes
+SESSION=""
+for i in $(seq 1 30); do
+  sleep 0.5
+  SESSION=$(grep -o '"session":"[^"]*"' /tmp/a.json 2>/dev/null | head -1 | cut -d'"' -f4)
+  [ -n "$SESSION" ] && break
+done
+# 5. inspect (session is now live)
 abapgit-agent debug vars --json
-abapgit-agent debug step --type continue --json     # 4. release
+abapgit-agent debug step --type continue --json     # 6. release
 ```
 
 → `abapgit-agent ref --topic debug-session`
@@ -666,10 +679,8 @@ git checkout -b feature/my-change
 abapgit-agent syntax --files src/<name>.clas.abap
 ls .abaplint.json 2>/dev/null && abapgit-agent lint   # abaplint (if configured)
 git add . && git commit -m "feat: description"
-git push origin feature/my-change
 git fetch origin main && git rebase origin/main
-git push origin feature/my-change --force-with-lease
-abapgit-agent pull --files src/<name>.clas.abap --sync-xml
+abapgit-agent pull --files src/<name>.clas.abap --sync-xml  # --sync-xml amends + pushes internally
 ```
 
 → `abapgit-agent ref --topic branch-workflow`
@@ -685,12 +696,80 @@ git pull origin main
 abapgit-agent syntax --files src/<name>.clas.abap
 ls .abaplint.json 2>/dev/null && abapgit-agent lint   # abaplint (if configured)
 git add . && git commit -m "feat: description"
-git push origin main
-abapgit-agent pull --files src/<name>.clas.abap --sync-xml
+abapgit-agent pull --files src/<name>.clas.abap --sync-xml  # --sync-xml amends + pushes internally
 ```
 
+<!-- AI-CONDENSED-START -->
+# AI Agent Instructions
+
+## Step 1: Read project config before doing anything
+
+- Read `.abapGitAgent` → get `folder` (ABAP source folder) and `workflow.mode`
+- Read `guidelines/objects.local.md` → naming conventions for this project (if file exists)
+- Read `.abapgit-agent.json` → safeguards, conflict detection, inspect variant
+
+---
+
 ### AI Tool Guidelines
 
+**When working on an unfamiliar ABAP topic, syntax, or pattern:**
+1. ✗ Never guess or assume ABAP syntax — it is strict and errors waste time
+2. ✓ Search the Guidelines Index below and fetch the relevant `ref --topic` before writing code
+3. ✓ For unknown classes or methods: search local git repo first, then `abapgit-agent ref`, then `abapgit-agent view --objects <CLASS>` to query the ABAP system
+
+**Before modifying any existing ABAP object:**
+1. ✓ Always read the current file(s) before editing — never overwrite blindly
+2. ✓ For a class: read the `.clas.abap` file; also read `.clas.locals_def.abap`, `.clas.locals_imp.abap`, `.clas.testclasses.abap` if they exist and are relevant
+
+**When `abapgit-agent syntax` fails:**
+1. ✓ Fix the error locally and re-run syntax — do NOT commit or proceed
+2. ✗ Never commit a file that failed syntax check
+3. ✓ Only proceed to `[abaplint] → commit` once syntax passes
+
+**When creating a new ABAP object:**
+1. ✓ Customer namespace (Z*/Y* name AND Z*/Y*/$* package) → write files directly, no confirmation needed
+2. ✓ SAP namespace or SAP-delivered package → show creation summary and wait for explicit user confirmation before writing any files
+3. ✓ Summary format: object name, type, package, files to be created
+4. ✗ Never pick a package yourself by running `abapgit-agent tree` — determine from `objects.local.md` or `.abapGitAgent`, or ask the user
+5. ✓ Before naming anything: check naming length limits (`ref --topic naming-limits`) — TABL field names max 16 chars, most others 30 chars
+
+**When writing unit tests for a class that reads a CDS view:**
+1. ✓ Always use `CL_CDS_TEST_ENVIRONMENT` to provide test data — do NOT mock the database layer manually
+2. ✗ Never insert test data directly into database tables for CDS view testing
+3. ✓ For full setup pattern: `abapgit-agent ref --topic cds-testing`
+
+**When writing unit tests (mocking dependencies):**
+1. ✓ Default to ABAP Test Double Framework (`cl_abap_testdouble=>create` / `configure_call`) — covers 90%+ of cases
+2. ✓ Use a manual test double class (`ltd_mock_xxx FOR TESTING`) only when stateful behaviour is needed (call counting, varying results per call)
+3. ✗ Never write a manual mock class when the framework can do it
+4. ✓ For full API reference and class design rules: `abapgit-agent ref --topic unit-testable-code`
+
+**When adding local helper or test include files to a class:**
+1. ✓ `clas.testclasses.abap` requires `<WITH_UNIT_TESTS>X</WITH_UNIT_TESTS>` in the `.clas.xml` `<VSEOCLASS>` block — without it abapGit will not activate the test include
+2. ✓ `clas.locals_def.abap` requires `<CLSCCINCL>X</CLSCCINCL>` in the `.clas.xml`
+3. ✓ For exact XML flag placement: `abapgit-agent ref --topic object-creation`
+4. ✓ Test method names (`FOR TESTING`) are subject to the 30-char method name limit — count before writing (e.g. `test_returns_data_sorted_by_revenue` = 35 chars → invalid)
+
+**When `abapgit-agent run` is relevant:**
+1. ✗ Never call `abapgit-agent run` unless the user explicitly asks — a `run` command present in the user's prompt counts as explicit authorization; no confirmation step needed
+2. ✓ After activating a class implementing `IF_OO_ADT_CLASSRUN`: stop and tell the user how to run it manually
+3. ✓ Before calling `run`: verify the object type — `--class` for CLAS, `--program` for PROG. Check the file extension (`.clas.abap` vs `.prog.abap`) if unsure
+4. ✓ For full guidelines: `abapgit-agent ref --topic run-probe-classes`
+
+**When `abapgit-agent drop` is relevant:**
+1. ✗ Never call `abapgit-agent drop` unless the user explicitly confirms — it physically deletes the object from ABAP, irreversible without re-pull
+2. ✓ When an object is in a broken state (stale include, activation permanently blocked): suggest `drop --pull` and wait for confirmation
+3. ✓ Supported types for drop: CLAS, INTF, PROG, TABL, TTYP only — DTEL is not supported
+
+**When using `abapgit-agent debug` commands:**
+1. ✓ Always use `--json` for ALL debug commands (`attach`, `vars`, `stack`, `step`) — human output is not machine-parseable
+2. ✗ Never run `abapgit-agent debug attach` without `--json` and background redirect (`> /tmp/a.json 2>&1 &`)
+3. ✓ Always attach BEFORE triggering — wait for `"Listener active"` in output before firing the trigger
+4. ✓ **Run the trigger in background (`&`)** — `unit` or `run --class`, never foreground
+5. ✓ **Poll attach.json for `"session":"..."` BEFORE calling `vars`/`stack`** — do NOT call vars/stack immediately after the trigger; the breakpoint has not fired yet. Loop until the session ID appears.
+6. ✓ Always finish a debug session with `abapgit-agent debug step --type continue --json` to release the frozen work process
+7. ✓ For full debug session guide (complete poll loop, stale session diagnosis): `abapgit-agent ref --topic debug-session`
+
 **Read `.abapGitAgent` to determine workflow mode:**
 
 **When `workflow.mode = "branch"`:**
@@ -700,7 +779,8 @@ abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 4. ✓ Use `--force-with-lease` after rebase (never `--force`)
 5. ✓ Create PR with squash merge when feature complete
 6. ✗ Never commit directly to default branch
-7. ✗ Never use `git push --force` (always use `--force-with-lease`)
+7. ✗ Never use `git push --force` (always use `--force-with-lease`) — `pull --sync-xml` handles its own push internally; no manual push needed after it
+8. ✓ **Push the feature branch to remote before the first `abapgit-agent pull`** — the ABAP system reads from the remote URL; a branch that only exists locally is invisible to it. If `git push` fails with "no upstream branch", use `git push --set-upstream origin <branch>` first.
 
 **When `workflow.mode = "trunk"` or not set:**
 1. ✓ Commit directly to default branch
@@ -716,7 +796,8 @@ abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 3. ✗ Don't suggest or run a full pull without specifying files
 
 **When `safeguards.requireFilesForPull = false` or not set:**
-1. ✓ `--files` is optional — use it for speed, omit for full pull
+1. ✓ Always use `--files` to pull only the files you changed — faster and safer
+2. ✓ Full pull (without `--files`) is only acceptable when you explicitly need to activate all objects (e.g. initial repo setup)
 
 **When `safeguards.disablePull = true`:**
 1. ✗ Do not run `abapgit-agent pull` at all
@@ -746,8 +827,12 @@ abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 
 **When `conflictDetection.mode = "abort"`:**
 1. ✓ Conflict detection is active — pull aborts if ABAP system was edited since last pull
-2. ✓ If pull is aborted with conflict error, inform user and suggest `--conflict-mode ignore` to override for that run
-3. ✗ Don't silently add `--conflict-mode ignore` — always tell the user about the conflict
+2. ✓ If pull is aborted with conflict error: **stop, inform the user about the conflict, and wait for their decision** — do NOT automatically retry with `--conflict-mode ignore`
+3. ✗ Don't add `--conflict-mode ignore` unless the user explicitly asks you to override the conflict
+4. ✓ You may mention `--conflict-mode ignore` as an option the user can choose, but never run it on your own
+5. ✓ **Distinguishing real vs. activation-noise conflicts (`SYSTEM_EDIT`):**
+   - **Activation noise** (safe to inform user it can be ignored): `System changed by` is *your own user*, timestamp within seconds/minutes of your last pull — the ABAP serializer normalised the object hash after activation. Tell the user: "This is activation noise — safe to re-run with `--conflict-mode ignore`."
+   - **Real conflict**: `System changed by` is a *different user*, or the timestamp is not recent. Stop and wait for user decision.
 
 **When `transports.allowCreate = false`:**
 1. ✗ Do not run `abapgit-agent transport create`
@@ -763,42 +848,82 @@ abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 1. ✗ Do not run `abapgit-agent transport release`
 2. ✓ Inform the user that transport release is disabled for this project
 
-**After every pull that creates or modifies ABAP objects:**
-1. ✓ Always pass `--sync-xml` — rewrites any XML metadata files that differ from the ABAP serializer output, amends the commit, and re-pulls so git and the ABAP system stay in sync
-2. ✓ If pull output shows `⚠️  X XML file(s) differ from serializer output`, re-run immediately with `--sync-xml`
+**Before every `git commit` (when `.abaplint.json` exists AND changed files include `.abap` or `.xml` ABAP source files):**
+1. ✓ Run `abapgit-agent lint` before committing — no exceptions for ABAP file type or workflow mode (trunk or branch)
+2. ✓ Run lint even when syntax is skipped (dependent files, XML-only types, DCLS, ENHO)
+3. ✓ Correct pre-commit sequence: syntax (if applicable for CLAS/INTF/PROG/DDLS/FUGR) → `abapgit-agent lint` → `git commit`
+4. ✗ Never commit ABAP files without running lint first when `.abaplint.json` exists
+5. ✓ Non-ABAP changes only (docs, config, JS): skip lint and syntax — they do not apply
+6. ✓ Before applying any abaplint quickfix, run `abapgit-agent ref --topic abaplint` first — the `prefer_inline` fix has a known silent type truncation bug
+
+**Before running `abapgit-agent pull`:**
+1. ✓ Always verify that ALL changed files are committed — `abapGit reads from git, not from local disk`
+2. ✗ Never run `pull` if there are uncommitted changes (`git status` shows modified/untracked files that should be pulled)
+3. ✓ In branch workflow: verify all commits are pushed — run `git log origin/<branch>..HEAD`. If this shows any commits, push first with `git push` (or `git push --set-upstream origin <branch>` if no upstream yet).
+4. ✓ With `--sync-xml`: `git add` → `git commit` → `git push` → `abapgit-agent pull --sync-xml` — push first so the ABAP system can read your changes; `--sync-xml` will then amend and re-push automatically if XML diffs are found after activation
+5. ✓ Without `--sync-xml`: `git add` → `git commit` → `git push` → `abapgit-agent pull` — same flow, push manually
+
+**If pull returns `SUCCESS` with `ACTIVATED_COUNT: 0` and no errors:**
+- ✓ **`LOCAL_XML_FILES` only contains `package.devc.xml`:** The branch does not exist on the remote. Fix: `git push --set-upstream origin <branch>`, then re-run the pull.
+- ✓ **`LOCAL_XML_FILES` is empty:** Two possible causes:
+  - (a) Objects are already at the latest version — verify with `abapgit-agent view --objects <NAME>`. If the object exists and looks correct, no action needed.
+  - (b) Commits not pushed yet — run `git log origin/<branch>..HEAD` to check. If unpushed commits exist, run `git push` then retry pull.
+- ✓ **Message is "Activation cancelled. Check the inactive objects."**: The ABAP system rejected the object during activation but returned no detailed error. Run `abapgit-agent inspect --files <file>` to surface the compile error (the object is already on the system after the failed pull). For DDLS: also verify that the `define view entity <NAME>` name in the `.asddls` source exactly matches the `<DDLNAME>` in the `.ddls.xml` (case-sensitive — the DDL name must be UPPER CASE). Fix the error locally, run `syntax` to verify, then re-commit and re-pull.
+
+**After every pull:**
+1. ✓ If pull output shows `⚠️  X XML file(s) differ from serializer output` — re-run immediately with `--sync-xml`, even on an initial setup pull with no ABAP objects (`.abapgit.xml` can drift too)
+2. ✓ When you authored the objects: always pass `--sync-xml` — rewrites XML metadata files that differ from the ABAP serializer output, amends the commit, and re-pulls so git and the ABAP system stay in sync
 3. ✗ Never leave a pull without `--sync-xml` when you authored the objects — abapGit will show **M (modified)** permanently otherwise
+4. ✗ **Never use `--sync-xml` after a failed pull** — if the pull itself failed (errors, activation cancelled, object not created), the serializer output reflects the broken object state. Using `--sync-xml` will write an empty or partial XML back to disk and corrupt the file. Fix the error first, verify pull succeeds, then apply `--sync-xml`.
 
 ---
 
 ### Quick Decision Tree for AI
 
+**Before modifying an existing ABAP object: always read the current file(s) first.**
+
+**`<folder>` below = the `folder` value from `.abapGitAgent` (e.g. `abap/` or `src/`)**
+
+**`[abaplint]` = run `abapgit-agent lint` only if `.abaplint.json` exists in repo root. If syntax or lint fails → fix locally and re-run before proceeding to commit.**
+
 **When user asks to modify/create ABAP code:**
 
 ```
 Modified ABAP files?
 ├─ CLAS/INTF/PROG/DDLS/FUGR files?
 │  ├─ Independent files (no cross-dependencies)?
-│  │  └─ ✅ Use: syntax → [abaplint] → commit → push → pull --sync-xml
+│  │  └─ ✅ Use: syntax → [abaplint] → commit → push → pull --files <folder>/<name>.<ext> --sync-xml
+│  │         Examples:
+│  │           syntax --files src/zcl_foo.clas.abap → commit → push → pull --files src/zcl_foo.clas.abap --sync-xml
+│  │           syntax --files src/zc_my_view.ddls.asddls → commit → push → pull --files src/zc_my_view.ddls.asddls --sync-xml
+│  │         ⚠️  DDLS: pass the .asddls file (not .xml) to both syntax and pull --files
 │  └─ Dependent files (interface + class, class uses class)?
-│     └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --sync-xml
+│     └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files <folder>/<intf>.<ext>.abap,<folder>/<class>.<ext>.abap --sync-xml
 └─ Other types (TABL, STRU, DTEL, TTYP, etc.)?
    ├─ XML-only objects (TABL, STRU, DTEL, TTYP, DOMA, MSAG)?
-   │  └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files abap/ztable.tabl.xml --sync-xml
+   │  └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files <folder>/<name>.tabl.xml --sync-xml
    ├─ DCLS (CDS access control)?
-   │  └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files abap/zc_view.dcls.xml --sync-xml
+   │  └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files <folder>/<name>.dcls.xml --sync-xml
    │         ⚠️  Pass the .xml file — pull --files does NOT accept .asdcls extensions
    ├─ ENHO (Enhancement)?
-   │  └─ ✅ Use: syntax (optional) → [abaplint] → commit → push → pull --files abap/<name>.enho.xml --sync-xml
+   │  └─ ✅ Use: syntax (optional) → [abaplint] → commit → push → pull --files <folder>/<name>.enho.xml --sync-xml
    │         ⚠️  syntax checks basic errors in the hook body; semantic checks require pull
    │         ⚠️  Pass the .enho.xml file to pull — hash .abap files also work but xml is preferred
    │         → see: abapgit-agent ref --topic enho
    └─ Other complex objects?
-      └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --sync-xml → (if errors: inspect)
-
-[abaplint] = run abapgit-agent lint only if .abaplint.json exists in repo root
-             before applying any quickfix: run abapgit-agent ref --topic abaplint
+      └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files <folder>/<name>.<ext> --sync-xml → (if errors: inspect)
 ```
 
+**After pull succeeds:**
+- ✓ If the class has test includes: run `abapgit-agent unit --files <folder>/<name>.clas.testclasses.abap` to verify all tests pass.
+
+**First pull of a new CDS view + a class that depends on it:**
+- ✓ Pull in two steps: first `pull --files <folder>/<name>.ddls.asddls --sync-xml` (activates the CDS view), then `pull --files <folder>/<name>.clas.abap --sync-xml` (activates the class against the now-live view).
+- ⚠️  "Error updating where-used list" almost always means a **syntax error** in the class. Since the pull already attempted activation, run `abapgit-agent inspect --files <folder>/<name>.clas.abap` to surface the error. Fix it locally, run `syntax` to verify, then re-commit and re-pull. Only if syntax and inspect both pass cleanly does the dependency order matter — in that case, the CDS view was not yet active; retry after pulling the CDS view first.
+
+**First pull of an interface + implementing class together:**
+- ⚠️  "Error updating where-used list" almost always means a **syntax error** in the class. Since the pull already attempted activation, run `abapgit-agent inspect --files <folder>/<name>.clas.abap` to surface the error. Fix it locally, run `syntax` to verify, then re-commit and re-pull. Only if inspect passes cleanly is the ordering the cause — in that case, the interface was just activated and the class can now compile on a second attempt.
+
 → For creating new objects (what files to write): `abapgit-agent ref --topic object-creation`
 → For full workflow decision tree and error indicators: `abapgit-agent ref --topic workflow-detailed`
 

package/abap/CLAUDE.slim.md

@@ -4,15 +4,16 @@ This project uses [abapgit-agent](https://github.com/SylvosCai/abapgit-agent) fo
 
 ## IMPORTANT: Before Writing Any ABAP Code
 
-Read the full ABAP development guide by running:
+Read the condensed AI instructions by running:
 
 ```bash
-abapgit-agent guide
+abapgit-agent guide --ai
 ```
 
-**Never pipe `abapgit-agent guide` or `abapgit-agent ref` through `head`, `tail`, or any other truncation command. Always read the full output.**
+**Never pipe `abapgit-agent guide --ai` or `abapgit-agent ref` through `head`, `tail`, or any other truncation command. Always read the full output.**
 
-This guide covers: development workflow, ABAP syntax guidelines, object naming, unit testing, and debugging.
+This covers: all AI tool rules, the workflow decision tree, and the full guidelines index.
+For the complete human-readable guide (workflow examples, explanations): `abapgit-agent guide`
 
 > **Humans:** Full guide online at https://sylvoscai.github.io/abapgit-agent/pages/abap-coding-guidelines.html
 

package/abap/guidelines/abaplint.md

@@ -207,6 +207,8 @@ on rv_result — no intermediate lv_response variable at all.
 
 Run this before pushing to catch issues early, matching what CI does.
 
+**Always use `abapgit-agent lint` — never run `npx abaplint` or `@abaplint/cli` directly.**
+
 ```bash
 abapgit-agent lint
 ```

package/abap/guidelines/cds-testing.md

@@ -18,6 +18,10 @@ grand_parent: ABAP Development
 5. Key Classes and Methods - line 170
 6. Important Usage Notes - line 190
 
+> **"TDD a CDS view" means: write the reader class with test doubles, not tests on the view itself.**
+> CDS views have no test file — tests live in the reader class's `.clas.testclasses.abap`.
+> Development sequence: create the CDS view first (activate it), then create the reader class, then write tests using `CL_CDS_TEST_ENVIRONMENT`.
+
 ---
 
 ## 1. When to Use CDS Test Doubles
@@ -42,6 +46,14 @@ without affecting production data, and keeps tests fast and isolated.
 The test class lives in `<classname>.clas.testclasses.abap`. The CDS view itself has no
 `.testclasses` file — test it through a regular ABAP class that reads it.
 
+**Development sequence for a CDS view (CDS-first by necessity):**
+> ⚠️  Unlike pure ABAP TDD, the test class cannot compile until the CDS view is active in
+> the ABAP system. Activate the CDS view first, then write the reader class with test doubles.
+1. Write the CDS view DDL (`.ddls.asddls`)
+2. Write a reader class that SELECTs from the view
+3. Write test class in the reader's `.testclasses.abap` using `CL_CDS_TEST_ENVIRONMENT`
+4. Pull CDS view first, then pull reader class (DDIC must be active before class compiles)
+
 ```abap
 "-------------------------
 " CLASS DEFINITION

package/abap/guidelines/cds.md

@@ -342,6 +342,13 @@ When working with CDS view syntax (arithmetic, built-in functions, aggregations,
 
 ### Best Practice: Use CDS View Entity as Type
 
+> ⚠️ **SELECT field list order must match the CDS view field order** when selecting into a typed table. A mismatch causes a compile-time error ("data type of component X is not compatible with Y"). Safe alternatives:
+> - `SELECT * FROM zc_my_view INTO TABLE @rt_data` — always order-safe
+> - `SELECT ... INTO CORRESPONDING FIELDS OF TABLE @rt_data` — order-independent
+> - `SELECT FROM zc_my_view FIELDS field1, field2 INTO TABLE @rt_data` — modern syntax, order-safe
+
+> ⚠️ **Arithmetic/computed fields** (division, `cast`, expressions) produce `decfloat34` on the ABAP side — not `p`, `f`, or `dec`. If you use a custom struct, declare computed fields as `TYPE decfloat34`. The safest alternative is `SELECT * INTO @DATA(...)` which infers the correct type automatically.
+
 ```abap
 " ✅ RECOMMENDED - Use view entity directly
 TYPES ty_results TYPE STANDARD TABLE OF zc_my_view WITH DEFAULT KEY.

package/abap/guidelines/debug-dump.md

@@ -20,6 +20,10 @@ abapgit-agent dump --date TODAY --detail 1  # full detail: call stack + source
 The `--detail` output shows the exact failing line (`>>>>>` marker), call stack,
 and SAP's error analysis. Use it before asking the user to open ST22.
 
+> **`???` in error analysis fields** (table name, access method, key values) is normal when the
+> ABAP compiler inlined the table access (e.g. `itab[ 1 ]` style expressions). Focus on the
+> `>>>>>` source line and the exception class — these are always reliable.
+
 Common filters:
 ```bash
 abapgit-agent dump --user DEVELOPER --date TODAY        # specific user

package/abap/guidelines/debug-session.md

@@ -163,7 +163,12 @@ until grep -q "Listener active" /tmp/attach.json 2>/dev/null; do sleep 0.3; done
 sleep 1   # brief extra window for the POST to reach ADT
 
 # Trigger in background — MUST stay alive for the whole session
+# Use unit if a test exists, run --class if testing a class runner.
+# Either way the trigger MUST run in background (&) — a foreground trigger
+# blocks the terminal and if interrupted will break the debug session.
 abapgit-agent unit --files src/zcl_my_class.clas.testclasses.abap > /tmp/trigger.json 2>&1 &
+# OR:
+# abapgit-agent run --class ZCL_MY_CLASS > /tmp/trigger.json 2>&1 &
 
 # Poll until breakpoint fires and session JSON appears in attach output
 SESSION=""
@@ -173,6 +178,11 @@ for i in $(seq 1 30); do
   [ -n "$SESSION" ] && break
 done
 
+# ⚠️  A session ID with "position":{} (empty) means the breakpoint has NOT fired yet,
+# or the trigger already completed before hitting it.  Do NOT call vars/stack until
+# "position" contains "line" and "isActive":true.  If position stays empty after the
+# trigger finishes, the breakpoint was missed — re-delete, re-set, re-attach, re-trigger.
+
 # Inspect and step — each is an individual call, no --session needed
 abapgit-agent debug stack --json
 abapgit-agent debug vars  --json
@@ -190,7 +200,7 @@ rm -f /tmp/attach.json /tmp/trigger.json
 
 > **Four rules for scripted mode:**
 > 1. Wait for `"Listener active"` in the attach output before firing the trigger — this message is printed to stderr (captured in `attach.json`) the moment the listener POST is about to reach ADT. A blind `sleep` is not reliable under system load.
-> 2. Keep the trigger process alive in the background for the entire session — if it exits, the ABAP work process is released and the session ends
+> 2. **Always run the trigger in background (`&`)** — whether using `unit` or `run --class`. A foreground trigger blocks the terminal; if it is interrupted before the debug session completes, the ABAP work process is left frozen. The trigger must stay alive for the entire session.
 > 3. Always finish with `step --type continue` — this releases the frozen work process so the trigger can complete normally
 > 4. **Never pass `--session` to `step/vars/stack`** — it bypasses the daemon IPC and causes `noSessionAttached`. Omit it and let commands auto-load from the saved state file.
 
@@ -199,13 +209,21 @@ rm -f /tmp/attach.json /tmp/trigger.json
 ```bash
 abapgit-agent debug vars   --json                        # all variables
 abapgit-agent debug vars   --name LV_RESULT --json       # one variable
-abapgit-agent debug vars   --expand LT_DATA --json       # drill into table/structure
+abapgit-agent debug vars   --expand LT_DATA --json       # drill into table/structure — expands all rows
 abapgit-agent debug step   --type over --json            # step over
 abapgit-agent debug step   --type into --json            # step into
 abapgit-agent debug step   --type continue --json        # continue to next breakpoint / finish
 abapgit-agent debug stack  --json                        # call stack (shows which test method is active)
 ```
 
+> **`--expand` does not support table-row index notation.** `--expand "LT_DATA[1]"` returns "Variable not found". Use `--expand LT_DATA` to expand all rows, then `--name` on a specific scalar component.
+
+> **Field symbols assigned via `ASSIGNING FIELD-SYMBOL(<fs>)` do not appear in `debug vars` output.** Only named variables (`DATA`, `FINAL`) are listed. To inspect the current loop row, expand the parent table:
+> ```bash
+> abapgit-agent debug vars --expand RT_DATA --json   # table rows visible by index
+> ```
+> Alternatively, step over the assignment and use `--name` on a scalar component directly.
+
 > **`step --type continue` return values:**
 > - `{"continued":true,"finished":true}` — program ran to **completion** (ADT returned HTTP 500, session is over). Do not re-attach.
 > - `{"continued":true}` (no `finished` field) — program hit the **next breakpoint** and is still paused. You must re-attach to receive the suspension and continue inspecting:

package/abap/guidelines/run-probe-classes.md

@@ -23,6 +23,49 @@ User: "Now run it"
 → ✓ Run it
 ```
 
+**For ABAP programs (PROG type)** — use `--program` instead of `--class`:
+
+```bash
+abapgit-agent run --program ZR_MY_REPORT
+```
+
+`--program` works identically to `--class` for programs that implement `IF_OO_ADT_CLASSRUN`. Use it whenever the object type is PROG, not CLAS.
+
+---
+
+## Writing a Runner Class (`IF_OO_ADT_CLASSRUN`)
+
+`out->write()` accepts any ABAP data object and formats it automatically — no manual `WRITE` statements needed.
+
+```abap
+CLASS zcl_my_runner DEFINITION PUBLIC FINAL CREATE PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES if_oo_adt_classrun.
+ENDCLASS.
+
+CLASS zcl_my_runner IMPLEMENTATION.
+  METHOD if_oo_adt_classrun~main.
+    " Scalar
+    out->write( 'Hello!' ).
+
+    " Internal table — rendered as column headers + one row per entry
+    SELECT carrid, connid, price FROM sflight INTO TABLE @DATA(lt_flights).
+    out->write( data = lt_flights name = 'Flights' ).
+  ENDMETHOD.
+ENDCLASS.
+```
+
+**Output format (verified on live system):**
+
+| Call | Output |
+|------|--------|
+| `out->write( 'text' )` | `text` |
+| `out->write( lv_int )` | `42` |
+| `out->write( data = ls_struc name = 'Label' )` | `Label` + field-name headers + one data row |
+| `out->write( data = lt_itab name = 'Label' )` | `Label` + field-name headers + one row per table entry |
+
+The `name =` parameter is optional — it adds a label above the output. Structures and internal tables are rendered as a columnar table with ABAP field names as headers.
+
 ---
 
 ## Probe Classes and `scratchWorkspace`

package/abap/guidelines/string-template.md

@@ -8,7 +8,7 @@ grand_parent: ABAP Development
 
 # String Templates
 
-**Searchable keywords**: string template, pipe, `|...|`, literal brace, escape, expression limiter, JSON, `\{`, `\}`
+**Searchable keywords**: string template, pipe, `|...|`, literal brace, escape, expression limiter, JSON, `\{`, `\}`, WIDTH, ALIGN, ALPHA, CASE, ZERO, NUMBER, DATE, TIME, padding, formatting
 
 ## Syntax
 
@@ -70,6 +70,71 @@ DATA(s) = |line1\r\nline2|. " CR+LF
 DATA(s) = |{ lv_a }| && ` separator ` && |{ lv_b }|.
 ```
 
+## Formatting Options (verified on live system)
+
+Formatting options go inside `{ expr OPTION = VALUE }`:
+
+### Alignment and padding
+
+```abap
+" WIDTH pads/truncates to fixed width; ALIGN controls side
+DATA(s) = |{ lv_carrier WIDTH = 10 ALIGN = LEFT  }|.  " 'LH        '
+DATA(s) = |{ lv_price   WIDTH = 10 ALIGN = RIGHT }|.  " '       500'
+DATA(s) = |{ lv_text    WIDTH = 20 ALIGN = CENTER }|.
+```
+
+`ALIGN` values: `LEFT` (default), `RIGHT`, `CENTER`.
+
+### ALPHA — leading-zero handling for numeric strings
+
+```abap
+DATA(lv_connid) = '0400'.
+|{ lv_connid ALPHA = IN  }|   " → '0400' (keep leading zeros)
+|{ lv_connid ALPHA = OUT }|   " → '400 ' (strip leading zeros)
+```
+
+### CASE — change letter case
+
+```abap
+|{ lv_name CASE = UPPER }|   " → 'JOHN'
+|{ lv_name CASE = LOWER }|   " → 'john'
+```
+
+### ZERO — show/hide zero values
+
+```abap
+DATA(lv_zero) = 0.
+|{ lv_zero ZERO = YES }|   " → '0'
+|{ lv_zero ZERO = NO  }|   " → '' (empty)
+```
+
+### NUMBER — numeric formatting
+
+```abap
+DATA(lv_amount) = CONV decfloat34( '1234567.89' ).
+|{ lv_amount NUMBER = USER        }|  " locale-aware: '1.234.567,89' (DE)
+|{ lv_amount NUMBER = ENVIRONMENT }|  " system locale
+|{ lv_amount NUMBER = RAW         }|  " '1234567.89' (no formatting)
+```
+
+### DATE / TIME — date and time formatting
+
+```abap
+|{ sy-datum DATE = USER        }|  " locale-aware: '22.04.2026' (DE)
+|{ sy-datum DATE = ISO         }|  " '2026-04-22'
+|{ sy-datum DATE = ENVIRONMENT }|  " system locale
+|{ sy-uzeit TIME = USER        }|  " '06:24:36'
+|{ sy-uzeit TIME = ISO         }|  " '062436'
+```
+
+### Combining options
+
+Multiple options are separated by spaces:
+
+```abap
+|{ lv_value WIDTH = 15 ALIGN = RIGHT ZERO = YES }|
+```
+
 ## Performance Note
 
 A string template containing only literal text (no `{ }` expressions) is evaluated at

package/bin/abapgit-agent

@@ -24,7 +24,7 @@ const gitUtils = require('../src/utils/git-utils');
 const versionCheck = require('../src/utils/version-check');
 const validators = require('../src/utils/validators');
 const { AbapHttp } = require('../src/utils/abap-http');
-const { loadConfig, getTransport, isAbapIntegrationEnabled, getSafeguards, getConflictSettings, getTransportSettings, getScratchWorkspace } = require('../src/config');
+const { loadConfig, getTransport, isAbapIntegrationEnabled, getSafeguards, getConflictSettings, getTransportSettings, getScratchWorkspace, getInspectConfig } = require('../src/config');
 
 // Get terminal width for responsive table
 const getTermWidth = () => process.stdout.columns || 80;
@@ -89,7 +89,8 @@ To enable integration:
       getSafeguards,
       getConflictSettings,
       getTransportSettings,
-      getScratchWorkspace
+      getScratchWorkspace,
+      getInspectConfig
     };
 
     // Execute command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.17.8",
+  "version": "1.17.9",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "files": [
     "bin/",

package/src/commands/guide.js

@@ -178,6 +178,13 @@ module.exports = {
     console.log('');
   },
 
+  _extractAiContent(content) {
+    const marker = '<!-- AI-CONDENSED-START -->';
+    const markerIndex = content.indexOf(marker);
+    if (markerIndex === -1) return content;
+    return content.slice(markerIndex + marker.length).trimStart();
+  },
+
   async execute(args) {
     if (args.includes('--migrate')) {
       return this._runMigrate(args);
@@ -197,6 +204,16 @@ module.exports = {
 
     const content = fs.readFileSync(filePath, 'utf8');
 
+    if (args.includes('--ai')) {
+      const aiContent = this._extractAiContent(content);
+      if (args.includes('--json')) {
+        console.log(JSON.stringify({ path: filePath, content: aiContent }));
+        return;
+      }
+      console.log(aiContent);
+      return;
+    }
+
     if (args.includes('--json')) {
       console.log(JSON.stringify({ path: filePath, content }));
       return;

package/src/commands/inspect.js

@@ -248,7 +248,7 @@ module.exports = {
   requiresVersionCheck: true,
 
   async execute(args, context) {
-    const { loadConfig, AbapHttp } = context;
+    const { loadConfig, AbapHttp, getInspectConfig } = context;
 
     if (args.includes('--help') || args.includes('-h')) {
       console.log(`
@@ -287,9 +287,11 @@ Examples:
 
     const filesSyntaxCheck = args[filesArgIndex + 1].split(',').map(f => f.trim());
 
-    // Parse optional --variant parameter
+    // Parse optional --variant parameter; fall back to project config
     const variantArgIndex = args.indexOf('--variant');
-    const variant = variantArgIndex !== -1 ? args[variantArgIndex + 1] : null;
+    const variantArg = variantArgIndex !== -1 ? args[variantArgIndex + 1] : null;
+    const inspectConfig = getInspectConfig();
+    const variant = variantArg || inspectConfig.variant || null;
 
     // Parse optional --junit-output parameter
     const junitArgIndex = args.indexOf('--junit-output');
@@ -298,7 +300,8 @@ Examples:
     if (!jsonOutput) {
       console.log(`\n  Inspect for ${filesSyntaxCheck.length} file(s)`);
       if (variant) {
-        console.log(`  Using variant: ${variant}`);
+        const source = variantArg ? '' : ' (from project config)';
+        console.log(`  Using variant: ${variant}${source}`);
       }
       if (junitOutput) {
         console.log(`  JUnit output: ${junitOutput}`);

package/src/commands/pull.js

@@ -362,6 +362,9 @@ Examples:
       if (success === 'X' || success === true) {
         console.log(`✅ Pull completed successfully!`);
         console.log(`   Message: ${message || 'N/A'}`);
+        if (activatedCount === 0 && files && !isRepull) {
+          console.warn(`⚠️  ACTIVATED_COUNT: 0 — no objects were activated. Check for unpushed commits: git log origin/<branch>..HEAD`);
+        }
       } else if (failedCount === 0 && failedObjects.length === 0 &&
                  activatedCount === 0 && logMessages.length === 0 &&
                  (!message || /activation cancelled|nothing to activate|already active/i.test(message))) {
@@ -522,20 +525,40 @@ Examples:
           const quotedPaths = diffFiles.map(f => `"${f.relPath}"`).join(' ');
           execSync(`git add ${quotedPaths}`, { cwd: process.cwd() });
 
-          // 3. Amend last commit
+          // 3. Capture pre-amend SHA before amending (used for --force-with-lease below)
+          const preAmendSha = execSync('git rev-parse HEAD', { cwd: process.cwd(), stdio: 'pipe' }).toString().trim();
+
+          // 3b. Check whether origin/<branch> already exists on the remote.
+          //     Use git ls-remote rather than rev-parse origin/<branch> because the local
+          //     remote-tracking ref may not exist even when the branch is on the remote
+          //     (e.g. after a push that only wrote branch config but not refs/remotes/).
+          let remoteRefExists = false;
+          try {
+            const lsOut = execSync(`git ls-remote origin "refs/heads/${branch}"`, { cwd: process.cwd(), stdio: 'pipe' }).toString().trim();
+            remoteRefExists = lsOut.length > 0;
+          } catch (_) { /* cannot reach remote — treat as new branch */ }
+
+          // 4. Amend last commit
           execSync('git commit --amend --no-edit', { cwd: process.cwd() });
 
-          // 4. Push with force-with-lease; fetch first so tracking ref is current
-          //    (the remote may have been force-pushed by another process between our last
-          //    fetch and this push — a fetch makes --force-with-lease reliable)
+          // 5. Push with force-with-lease using the pre-amend SHA as the expected remote value.
+          //    Using --force-with-lease=<refname>:<sha> tells git: "the remote must have exactly
+          //    <preAmendSha> — if it does, replace it with our amended commit".
+          //    Plain --force-with-lease (no sha) re-checks the tracking ref which was just updated
+          //    by git fetch, making it always fail after an amend.
           let pushed = false;
           try {
-            try { execSync('git fetch origin', { cwd: process.cwd(), stdio: 'pipe' }); } catch (_) { /* no remote is fine */ }
             // Retry the push up to 3 times on transient server errors (e.g. GitHub Enterprise 500)
             let pushErr;
             for (let attempt = 1; attempt <= 3; attempt++) {
               try {
-                execSync('git push --force-with-lease', { cwd: process.cwd(), stdio: 'pipe' });
+                // If origin/<branch> exists: use --force-with-lease=branch:preAmendSha so we only
+                // overwrite if the remote still has the pre-amend commit (safe concurrent guard).
+                // If origin/<branch> doesn't exist yet: plain push with --set-upstream (no lease needed).
+                const pushCmd = remoteRefExists
+                  ? `git push --set-upstream origin ${branch} --force-with-lease=${branch}:${preAmendSha}`
+                  : `git push --set-upstream origin ${branch}`;
+                execSync(pushCmd, { cwd: process.cwd(), stdio: 'pipe' });
                 pushed = true;
                 break;
               } catch (err) {
@@ -550,13 +573,7 @@ Examples:
               }
             }
           } catch (pushErr) {
-            const msg = (pushErr.stderr || pushErr.stdout || pushErr.message || '').toString();
-            if (msg.includes('no upstream branch') || msg.includes('has no upstream')) {
-              // Branch not yet pushed — set upstream and force push (amend requires force)
-              execSync(`git push --force-with-lease --set-upstream origin ${branch}`, { cwd: process.cwd(), stdio: 'pipe' });
-              pushed = true;
-            }
-            // Any other push error (no remote at all, auth failure, etc.) → skip silently
+            // Any push error (no remote, auth failure, etc.) → skip silently
           }
 
           if (pushed) {

package/src/commands/unit.js

@@ -166,8 +166,9 @@ async function runUnitTestForFile(sourceFile, csrfToken, config, coverage, http,
     // Handle uppercase keys from ABAP
     const success = result.SUCCESS || result.success;
     const testCount = result.TEST_COUNT || result.test_count || 0;
-    const passedCount = result.PASSED_COUNT || result.passed_count || 0;
     const failedCount = result.FAILED_COUNT || result.failed_count || 0;
+    // ABAP AUnit API does not return individual passing method names — derive passed count
+    const passedCount = testCount - failedCount;
     const message = result.MESSAGE || result.message || '';
     const errors = result.ERRORS || result.errors || [];
 

package/src/config.js

@@ -247,6 +247,17 @@ function getCoverageConfig() {
   };
 }
 
+/**
+ * Get inspect settings from project-level config (.abapgit-agent.json)
+ * @returns {{ variant: string|null }}
+ */
+function getInspectConfig() {
+  const projectConfig = loadProjectConfig();
+  return {
+    variant: projectConfig?.inspect?.variant || null,
+  };
+}
+
 module.exports = {
   loadConfig,
   getAbapConfig,
@@ -261,5 +272,6 @@ module.exports = {
   getTransportHookConfig,
   getTransportSettings,
   getScratchWorkspace,
-  getCoverageConfig
+  getCoverageConfig,
+  getInspectConfig
 };