abapgit-agent 1.15.2 → 1.15.3

package/abap/.github/copilot-instructions.slim.md

@@ -36,8 +36,14 @@ The folder is configured in `.abapGitAgent` (property: `folder`):
 
 Each ABAP object needs an XML metadata file. Local helper/test-double classes use separate `.locals_def.abap` / `.locals_imp.abap` files.
 
+**Name length limits** (verify before naming anything):
+- CLAS, INTF: name **30 chars** | method names: **30 chars**
+- TABL, STRU: name **30 chars** | **field names: 16 chars** ← most common mistake
+- DDLS (CDS view entity): **40 chars** | field alias: 30 | FUGR: 26 | MSAG: 20 | PROG/DTEL/DOMA/TTYP: 30
+
 ```bash
-abapgit-agent ref --topic object-creation   # XML templates and local class setup
+abapgit-agent ref --topic naming-limits    # full length reference
+abapgit-agent ref --topic object-creation  # XML templates and local class setup
 ```
 
 ### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG, DDLS)
@@ -65,6 +71,24 @@ abapgit-agent ref --topic debug-session       # full debug guide
 abapgit-agent ref --topic debug-dump          # dump analysis guide
 ```
 
+### 7. Never Run `run` Command Proactively
+
+Never call `abapgit-agent run` unless the user explicitly asks — it can modify data or trigger RFCs.
+
+### 8. Probe and PoC Objects — Always Z/Y, Never in SAP Packages
+
+When `objects.local.md` shows SAP namespace (`CL_*`, `IF_*`, `/NAMESPACE/*`) and the user asks to create a new object, always ask first: *"Is this a production object, a PoC, or a probe?"*
+
+→ `abapgit-agent ref --topic probe-poc`
+
+### 9. abaplint — Optional, Project-Controlled
+
+Only run if `.abaplint.json` exists. Run after `syntax`, before commit. Always check `ref --topic abaplint` before applying any quickfix.
+
+```bash
+ls .abaplint.json 2>/dev/null && abapgit-agent lint
+```
+
 ---
 
 ## Development Workflow
@@ -77,6 +101,8 @@ Checked into the repository — applies to all developers. **Read this file at t
 |---------|--------|
 | `safeguards.requireFilesForPull: true` | Always include `--files` in every `pull` |
 | `safeguards.disablePull: true` | Do not run `abapgit-agent pull` at all |
+| `safeguards.disableRun: true` | Do not run `abapgit-agent run` at all |
+| `safeguards.disableProbeClasses: true` | Use `scratchWorkspace` for probe classes instead |
 | `conflictDetection.mode: "abort"` | Abort pull on conflict — inform user |
 | `transports.allowCreate/allowRelease: false` | Blocked — inform user |
 
@@ -97,10 +123,15 @@ abapgit-agent ref --topic branch-workflow
 ```
 Modified ABAP files?
 ├─ CLAS/INTF/PROG/DDLS files?
-│  ├─ Independent files?  → syntax → commit → push → pull
-│  └─ Dependent files?    → skip syntax → commit → push → pull
+│  ├─ Independent files?  → syntax → [abaplint] → commit → push → pull --sync-xml
+│  └─ Dependent files?    → skip syntax → [abaplint] → commit → push → pull --sync-xml
 └─ Other types (FUGR, TABL, etc.)?
-   → skip syntax → commit → push → pull → (if errors: inspect)
+   ├─ XML-only (TABL, STRU, DTEL, TTYP, DOMA, MSAG)?
+   │  → skip syntax → [abaplint] → commit → push → pull --files <name>.tabl.xml --sync-xml
+   └─ FUGR and others?
+      → skip syntax → [abaplint] → commit → push → pull --sync-xml → (if errors: inspect)
+
+[abaplint] = run lint only if .abaplint.json exists; ref --topic abaplint before any quickfix
 ```
 
 ```bash

package/abap/CLAUDE.md

@@ -99,6 +99,20 @@ Never assume Z/Y prefix without checking.
            XML-only objects (TABL, STRU, DTEL, TTYP, DOMA, MSAG) need ONLY the XML file
 ```
 
+**Before choosing a name, verify the length limit for the object type:**
+
+| Object type | Name limit | Field/sub-element limit |
+|---|---|---|
+| CLAS, INTF | **30 chars** | method names: **30 chars** |
+| TABL, STRU | **30 chars** | **field names: 16 chars** |
+| DDLS (CDS view entity) | **40 chars** | field alias: **30 chars** |
+| DCLS (CDS access control) | **40 chars** | — (name must match its DDLS view) |
+| FUGR (function group) | **26 chars** | function module name: **30 chars** |
+| MSAG (message class) | **20 chars** | — |
+| PROG, DTEL, DOMA, TTYP | **30 chars** | — |
+
+→ Full length reference: `abapgit-agent ref --topic naming-limits`
+
 Use the object name from `objects.local.md` (or `objects.md` as fallback) in place of `<name>`:
 
 | Object Type | Source File | XML File |
@@ -110,7 +124,7 @@ Use the object name from `objects.local.md` (or `objects.md` as fallback) in pla
 | CDS Access Control (DCLS) | `<name>.dcls.asdcls` | `<name>.dcls.xml` |
 | Function Group (FUGR) | `<name>.fugr.abap` + includes | `<name>.fugr.xml` |
 | Table (TABL) | *(none)* | `<name>.tabl.xml` |
-| Structure (STRU) | *(none)* | `<name>.stru.xml` |
+| Structure (STRU) | *(none)* | `<name>.tabl.xml` ⚠️ NOT `.stru.xml` |
 | Data Element (DTEL) | *(none)* | `<name>.dtel.xml` |
 | Table Type (TTYP) | *(none)* | `<name>.ttyp.xml` |
 | Domain (DOMA) | *(none)* | `<name>.doma.xml` |
@@ -143,7 +157,7 @@ Anything else (SAP namespace object, or SAP-delivered package)?
 
         Object:   <NAME> (<Type>)
         Package:  <PACKAGE>
-        Files:    <folder>/<name>.<ext>.abap
+        Files:    <folder>/<name>.<ext>.abap    ← omit this line for XML-only types (TABL/STRU/DTEL/TTYP/DOMA/MSAG)
                   <folder>/<name>.<ext>.xml
 
       Shall I proceed?"
@@ -716,6 +730,9 @@ Modified ABAP files?
 └─ Other types (FUGR, 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
+   ├─ DCLS (CDS access control)?
+   │  └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files abap/zc_view.dcls.xml --sync-xml
+   │         ⚠️  Pass the .xml file — pull --files does NOT accept .asdcls extensions
    └─ FUGR and other complex objects?
       └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --sync-xml → (if errors: inspect)
 
@@ -736,6 +753,7 @@ Modified ABAP files?
 | `ref --topic exceptions` | Exception Handling |
 | `ref --topic classes` | ABAP Classes and Objects |
 | `ref --topic objects` | Object Naming Conventions (defaults) |
+| `ref --topic naming-limits` | Naming Length Limits — 30/16/40 char rules per type (CRITICAL before naming anything) |
 | `ref --topic comments` | Documentation Comments (ABAP DOC, shorttext, @parameter, CDS `//`, program `*&---`) |
 | `ref --topic testing` | Unit Testing |
 | `ref --topic unit-testable-code` | Unit Testable Code (Dependency Injection) |

package/abap/guidelines/abapgit-fugr.md

@@ -22,10 +22,13 @@ A FUGR with group name `ZMY_FUGR` and one FM `ZMY_MY_FUNCTION` requires these fi
 | `zmy_fugr.fugr.xml` | Main XML: group description, includes list, FM interfaces |
 | `zmy_fugr.fugr.lzmy_fugrtop.abap` | TOP include source |
 | `zmy_fugr.fugr.lzmy_fugrtop.xml` | TOP include metadata (`SUBC=I`) |
-| `zmy_fugr.fugr.saplzmy_fugr.abap` | Main include source |
+| `zmy_fugr.fugr.saplzmy_fugr.abap` | Main include source (lists all U-includes) |
 | `zmy_fugr.fugr.saplzmy_fugr.xml` | Main include metadata (`SUBC=F`) |
+| `zmy_fugr.fugr.lzmy_fugru01.abap` | FM implementation include (one per FM: U01, U02, …) |
 | `zmy_fugr.fugr.zmy_my_function.abap` | FM source (one file per FM, named after FM in lowercase) |
 
+> **7 files total for one FM** (6 without the U01 include causes a pull error — the SAPL source references `LZMY_FUGRU01` which abapGit can't find). For a second FM, add `lzmy_fugru02.abap` and `zmy_second_function.abap`.
+
 ---
 
 ### `zmy_fugr.fugr.xml`
@@ -145,15 +148,28 @@ FUNCTION zmy_my_function.
 ENDFUNCTION.
 ```
 
+### `zmy_fugr.fugr.lzmy_fugru01.abap`
+
+The FM implementation include — **always required**. The SAPL source references `INCLUDE LZMY_FUGRU01.` so this file must exist or the pull fails.
+
+```abap
+*----------------------------------------------------------------------*
+***INCLUDE LZMY_FUGRU01.
+*----------------------------------------------------------------------*
+```
+
+For a second FM, create `zmy_fugr.fugr.lzmy_fugru02.abap` with the same pattern (replacing `U01` with `U02`).
+
 ---
 
 ## Key Rules
 
-- **Include naming**: TOP = `L<GROUP>TOP`, main = `SAPL<GROUP>` — uppercase in XML and filenames
+- **Include naming**: TOP = `L<GROUP>TOP`, main = `SAPL<GROUP>`, FM implementation = `L<GROUP>U01` (U02, U03, …) — uppercase in XML and filenames
 - **FM source file**: named after the FM in **lowercase** (`zmy_my_function.abap`, not `ZMY_MY_FUNCTION.abap`)
+- **U-include file required**: `lzmy_fugru01.abap` must exist — the SAPL source references it; missing it causes a pull error
 - **`INCLUDES` list** in the main XML: only lists TOP and SAPL includes — FM source includes are implicit
 - **`REMOTE_CALL>R`**: add only for RFC-enabled FMs; omit for local FMs
 - **Optional parameters**: include both `<OPTIONAL>X</OPTIONAL>` and `<DEFAULT>...</DEFAULT>`
-- **`DOCUMENTATION` section**: omit entirely if no parameter descriptions needed — missing docs cause no diff
+- **`DOCUMENTATION` section**: the serializer always writes `<DOCUMENTATION>` with one `<RSFDO>` entry per parameter (containing only `<PARAMETER>` and `<KIND>P</KIND>`, no `<STEXT>`). Always include it — omitting it causes a permanent "M" diff
 - **Screens/CUA**: omit `DYNPROS`/`CUA` sections for screenless function groups
 - **Multiple FMs**: add one `<item>` per FM in `FUNCTIONS`; add one `INCLUDE` line per FM in the SAPL source

package/abap/guidelines/abapgit-xml-only.md

@@ -170,6 +170,12 @@ A **text table** stores translatable texts for another table (the "main table").
 
 > Pull with: `pull --files src/zmy_dtel.dtel.xml`
 
+**Two variants — choose based on whether the DTEL defines its own type or references a domain:**
+
+#### Variant 1: Built-in type (no domain)
+
+Use when the data element directly defines `DATATYPE` and `LENG` without referencing a domain.
+
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 <abapGit version="v1.0.0" serializer="LCL_OBJECT_DTEL" serializer_version="v1.0.0">
@@ -192,13 +198,38 @@ A **text table** stores translatable texts for another table (the "main table").
 </abapGit>
 ```
 
+#### Variant 2: Domain reference
+
+Use when the data element's type and length come from an existing domain (`DOMNAME`). Do **not** include `DATATYPE` or `LENG` — the domain owns those.
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_DTEL" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <DD04V>
+    <ROLLNAME>ZMY_DTEL</ROLLNAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <DDTEXT>Description of data element</DDTEXT>
+    <REPTEXT>Description</REPTEXT>
+    <SCRTEXT_S>Short text</SCRTEXT_S>
+    <SCRTEXT_M>Medium text</SCRTEXT_M>
+    <SCRTEXT_L>Long description text</SCRTEXT_L>
+    <DTELMASTER>E</DTELMASTER>
+    <DOMNAME>ZMY_DOMAIN</DOMNAME>
+   </DD04V>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
 **Key Fields**:
 - `ROLLNAME`: Data element name
 - `DDTEXT`: Description (**not** `DESCRIPT`)
 - `REPTEXT` / `SCRTEXT_S` / `SCRTEXT_M` / `SCRTEXT_L`: Field labels (report heading, short, medium, long)
 - `DTELMASTER`: Language key for label master (`E` for English)
-- `DATATYPE`: Data type (`CHAR`, `NUMC`, `DATS`, `TIMS`, `INT4`, etc.)
-- `LENG`: Length padded to 6 digits (e.g. `000010` for 10 characters)
+- `DATATYPE` + `LENG`: Use for built-in type variant only (e.g. `CHAR` + `000010`)
+- `DOMNAME`: Use for domain-reference variant only — omit `DATATYPE` and `LENG` entirely
 
 **Omit `<PARAMID>`** unless you specifically need a SET/GET parameter ID — the serializer omits it when empty.
 
@@ -206,10 +237,14 @@ A **text table** stores translatable texts for another table (the "main table").
 
 ### Structure (STRU)
 
-**Filename**: `src/zmy_struct.stru.xml`
+**Filename**: `src/zmy_struct.tabl.xml`
 
-> abapGit uses the same TABL serializer for STRU.
-> Pull with: `pull --files src/zmy_struct.stru.xml`
+> ⚠️ **Use `.tabl.xml` extension, NOT `.stru.xml`** — abapGit serializes structures with the TABL
+> serializer and registers them as object type `TABL`. A `.stru.xml` filename causes
+> "Step DDIC is only for DDIC objects" because abapGit treats it as object type `STRU`,
+> which is not in its DDIC activation list.
+>
+> Pull with: `pull --files src/zmy_struct.tabl.xml`
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -221,16 +256,37 @@ A **text table** stores translatable texts for another table (the "main table").
     <DDLANGUAGE>E</DDLANGUAGE>
     <TABCLASS>INTTAB</TABCLASS>
     <DDTEXT>Description of the structure</DDTEXT>
-    <CONTFLAG>A</CONTFLAG>
+    <EXCLASS>1</EXCLASS>
    </DD02V>
+   <DD03P_TABLE>
+    <DD03P>
+     <FIELDNAME>FIELD1</FIELDNAME>
+     <ROLLNAME>S_CARR_ID</ROLLNAME>
+     <ADMINFIELD>0</ADMINFIELD>
+     <SHLPORIGIN>D</SHLPORIGIN>
+     <COMPTYPE>E</COMPTYPE>
+    </DD03P>
+    <DD03P>
+     <FIELDNAME>FIELD2</FIELDNAME>
+     <ROLLNAME>S_CARRNAME</ROLLNAME>
+     <ADMINFIELD>0</ADMINFIELD>
+     <COMPTYPE>E</COMPTYPE>
+    </DD03P>
+   </DD03P_TABLE>
   </asx:values>
  </asx:abap>
 </abapGit>
 ```
 
-**Key difference from TABL**: `TABCLASS` is `INTTAB` (internal table / structure) instead of `TRANSP`.
+**Key differences from TABL**:
+- `TABCLASS` is `INTTAB` instead of `TRANSP`
+- No `<CONTFLAG>` — omit it (not written by serializer for structures)
+- `<EXCLASS>1</EXCLASS>` — include it
+- Include `<DD03P_TABLE>` with field definitions from the start (unlike TABL where it is optional on creation)
 
-**Note**: Like TABL, after the first pull abapGit expands the XML with `<DD03P_TABLE>` field definitions.
+**`DD03P` field rules** (same as TABL):
+- Fields with `ROLLNAME` (data element): include `ROLLNAME`, `ADMINFIELD>0`, `SHLPORIGIN` (when domain provides value help — `D` for domain fixed values), `COMPTYPE>E`
+- Fields with raw type (no data element): include `ADMINFIELD>0`, `INTTYPE`, `INTLEN`, `DATATYPE`, `MASK` (before any text fields)
 
 ---
 
@@ -248,13 +304,13 @@ A **text table** stores translatable texts for another table (the "main table").
    <DD40V>
     <TYPENAME>ZMY_TTYP</TYPENAME>
     <DDLANGUAGE>E</DDLANGUAGE>
-    <DDTEXT>Description of table type</DDTEXT>
     <ROWTYPE>ZMY_STRUCT</ROWTYPE>
     <ROWKIND>S</ROWKIND>
-    <DATATYPE>TABLE_T</DATATYPE>
+    <DATATYPE>STRU</DATATYPE>
     <ACCESSMODE>T</ACCESSMODE>
     <KEYDEF>D</KEYDEF>
     <KEYKIND>N</KEYKIND>
+    <DDTEXT>Description of table type</DDTEXT>
    </DD40V>
   </asx:values>
  </asx:abap>
@@ -265,7 +321,7 @@ A **text table** stores translatable texts for another table (the "main table").
 - `TYPENAME`: Table type name
 - `ROWTYPE`: Row type (a structure or data element name)
 - `ROWKIND`: Row kind — `S`=Structure/Type, `D`=Data element, `R`=Reference
-- `DATATYPE`: Always `TABLE_T` for table types
+- `DATATYPE`: `STRU` when row type is a structure (`ROWKIND=S`); `TABLE_T` only for elementary-type row types
 - `ACCESSMODE`: Table kind — `T`=Standard, `S`=Sorted, `H`=Hashed
 - `KEYDEF`: Key definition — `D`=Default (standard key), `K`=User-defined
 - `KEYKIND`: Key uniqueness — `N`=Non-unique, `U`=Unique
@@ -372,7 +428,7 @@ abapGit uses the view `DD01V` as the root element (not `DD01L`). The serializer
      <SPRSL>E</SPRSL>
      <ARBGB>ZMY_MSGS</ARBGB>
      <MSGNR>000</MSGNR>
-     <TEXT>Object &1 not found</TEXT>
+     <TEXT>Object &amp;1 not found</TEXT>
     </T100>
     <T100>
      <SPRSL>E</SPRSL>

package/abap/guidelines/abapgit.md

@@ -265,7 +265,7 @@ abapGit's serializer **omits fields that have their default value**. Writing ext
 - `SOURCE_TYPE W` → View Entity (`define view entity`, modern — **use by default**)
 - `SOURCE_TYPE V` → View (`define view` + `@AbapCatalog.sqlViewName`, legacy)
 
-→ For DDL source syntax: `abapgit-agent ref --topic cds-abapgit`
+→ For DDL source syntax: `abapgit-agent ref --topic cds`
 
 ---
 
@@ -290,6 +290,7 @@ abapGit's serializer **omits fields that have their default value**. Writing ext
 
 - `DCLNAME` matches the CDS view name
 - Source file contains the DCL (`@MappingRole ... define role ...`)
+- **Pull with the `.xml` file, not `.asdcls`**: `pull --files src/zc_my_view.dcls.xml` — the `pull --files` filter does not accept `.asdcls` extensions
 
 ---
 

package/abap/guidelines/index.md

@@ -20,6 +20,7 @@ This folder contains detailed ABAP coding guidelines that can be searched using
 | `cds.md` | CDS Views |
 | `classes.md` | ABAP Classes and Objects |
 | `objects.md` | Object Naming Conventions |
+| `naming-limits.md` | Naming Length Limits (30/16/40 char rules per type) |
 | `json.md` | JSON Handling |
 | `abapgit.md` | abapGit XML Metadata Templates |
 | `unit-testable-code.md` | Unit Testable Code Guidelines (Dependency Injection) |

package/abap/guidelines/naming-limits.md

@@ -0,0 +1,160 @@
+---
+layout: default
+title: Naming Length Limits
+nav_order: 6
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
+# ABAP Naming Length Limits
+
+**Searchable keywords**: name length, character limit, 30 characters, 16 characters, 40 characters, too long, truncate, field name, method name, class name, table name, CDS name
+
+> **Rule of thumb**: Most ABAP object names → 30 chars. Table/structure **field names** → 16 chars. CDS/DDLS names → 40 chars. Method names (including test methods) → 30 chars.
+
+---
+
+## Quick Reference
+
+| Object / Element | Max Length |
+|---|---|
+| Class name (CLAS) | **30** |
+| Interface name (INTF) | **30** |
+| Program name (PROG) | **30** |
+| Function Group name (FUGR) | **26** |
+| Function Module name | **30** |
+| Table name (TABL) | **30** |
+| **Table field name** | **16** |
+| Structure name (STRU) | **30** |
+| **Structure field name** | **16** |
+| Data Element name (DTEL) | **30** |
+| Domain name (DOMA) | **30** |
+| Table Type name (TTYP) | **30** |
+| Package name | **30** |
+| **CDS View Entity name (DDLS)** | **40** |
+| CDS Access Control name (DCLS) | **40** |
+| CDS field alias | **30** |
+| Message Class name (MSAG) | **20** |
+| Class method name | **30** |
+| **Test method name** | **30** |
+| Interface method name | **30** |
+| Class attribute name | **30** |
+| Local variable name | **30** |
+| Local type/class name | **30** |
+| Test class name (local) | **30** |
+
+---
+
+## Critical Differences — Don't Confuse These
+
+### Table/Structure Field Names: 16 Characters MAX
+
+This is the **most common mistake**. Field names in TABL and STRU are limited to **16 characters**, not 30.
+
+```xml
+<!-- WRONG — 17 characters -->
+<FIELDNAME>LAST_MODIFIED_AT</FIELDNAME>
+
+<!-- CORRECT — 16 characters or fewer -->
+<FIELDNAME>LAST_MODIFIED</FIELDNAME>
+<FIELDNAME>SYS_CHANGED_AT</FIELDNAME>  <!-- 14 chars ✓ -->
+<FIELDNAME>LAST_PULLED_AT</FIELDNAME>  <!-- 14 chars ✓ -->
+```
+
+When naming table fields, keep names short and descriptive:
+- `CARRID` not `CARRIER_ID_FIELD`
+- `CONNID` not `CONNECTION_IDENTIFIER`
+- `STATUS` not `CURRENT_STATUS_FLAG`
+- `CREATED_AT` not `CREATION_TIMESTAMP`
+
+### CDS View Names: 40 Characters MAX
+
+CDS View Entity (DDLS) names allow up to **40 characters** — more room than regular ABAP objects.
+
+```
+ZC_MY_FLIGHT_BOOKING_REVENUE_SUMMARY     ← 40 chars (at limit)
+ZC_FLIGHT_REVENUE                        ← 17 chars (fine)
+```
+
+However, CDS **field aliases** inside the view are still limited to **30 characters** (ABAP identifier rules).
+
+### Function Group Names: 26 Characters MAX
+
+Function groups (`FUGR`) have a **26-character limit** because ABAP appends a 4-character suffix internally (e.g. `SAPLZMY_FG` prefix + module name). The safe usable name length is 26 characters.
+
+### Test Method Names: 30 Characters MAX — Causes Syntax Error
+
+Test methods (`FOR TESTING`) hit the 30-char limit frequently because the `test_` prefix takes 5 chars before the meaningful content starts.
+
+```abap
+" WRONG — 34 characters → syntax error at activation
+METHODS test_execute_with_minimal_params FOR TESTING.
+
+" CORRECT — abbreviate to stay within 30 chars
+METHODS test_exec_minimal FOR TESTING.     " 18 chars ✓
+METHODS test_exec_with_files FOR TESTING.  " 24 chars ✓
+```
+
+**Counting test method length**: include the full method name — `test_exec_minimal` is 18 characters.
+
+---
+
+## Counting Characters Before You Name Things
+
+Use this mental check before naming any ABAP element:
+
+```
+# Object name: type prefix + your name ≤ limit
+ZCL_             (4 chars) + name ≤ 30  →  name ≤ 26 chars
+ZIF_             (4 chars) + name ≤ 30  →  name ≤ 26 chars
+ZC_              (3 chars) + name ≤ 40  →  name ≤ 37 chars  (CDS)
+Z                (1 char)  + name ≤ 30  →  name ≤ 29 chars  (table/program)
+
+# Project-specific sub-namespace eats more of the budget — plan ahead
+# Example: project uses ZFICO_ prefix for all objects
+ZCL_FICO_        (9 chars) + name ≤ 30  →  name ≤ 21 chars
+ZCL_FICO_PAYMENT_PROPOSAL   = 26 chars  ✓
+ZCL_FICO_PAYMENT_PROPOSAL_V = 27 chars  ✓  (getting tight)
+
+# Field name in TABL/STRU: no prefix, just ≤ 16 total
+PAYMENT_METHOD               = 14 chars  ✓
+PAYMENT_METHOD_CD            = 17 chars  ✗  → shorten to PAYMENT_METH_CD
+
+# Method name: no prefix, just ≤ 30 total
+test_exec_with_files                    →  24 chars ✓
+test_execute_with_minimal_params        →  34 chars ✗
+```
+
+---
+
+## Common Length Violations and Fixes
+
+| Too Long (violates limit) | Fixed Version | Limit |
+|---|---|---|
+| `ZCL_COMMAND_PULL_WITH_RETRY` (30+ chars) | `ZCL_COMMAND_PULL_RETRY` | 30 |
+| `LAST_SUCCESSFULLY_PULLED_AT` (table field, 28 chars) | `LAST_PULLED_AT` | 16 |
+| `test_execute_command_with_files` (test method, 32 chars) | `test_exec_with_files` | 30 |
+| `ZC_MY_VERY_LONG_CDS_VIEW_NAME_EXCEEDS_40_CHARS` (47 chars) | `ZC_MY_LONG_CDS_VIEW_NAME_TRIMMED` | 40 |
+| `ZBIZ_OBJECT_CREATION_SERVICE_MESSAGE_CLASS` (MSAG, 43 chars) | `ZBIZ_CREATE_MSGS` | 20 |
+
+---
+
+## SAP Technical Basis for These Limits
+
+These limits come from the ABAP Dictionary (DDIC) and ABAP kernel:
+
+| Limit Source | Explanation |
+|---|---|
+| 30 chars (most objects) | ABAP uses `RSYN` program name space; objects stored in `TADIR` with `SOBJ_NAME CHAR(40)` but compiler enforces 30 for classes/interfaces/programs |
+| 16 chars (DDIC fields) | Stored in `DD03L.FIELDNAME CHAR(16)` — this is a hard database column width |
+| 40 chars (CDS names) | CDS objects stored in `DD02L.TABNAME CHAR(40)` — intentionally larger for CDS |
+| 20 chars (MSAG) | Message class name stored in `T100A.ARBGB CHAR(20)` |
+| 26 chars (FUGR) | Function group internally prefixed with `SAPL` (4 chars) for the main include |
+
+---
+
+## See Also
+
+- **Naming Conventions** (objects.md) — prefixes per object type
+- **Object Creation** (object-creation.md) — which files to create
+- **Testing** (testing.md) — test method naming (30-char limit detail)

package/abap/guidelines/object-creation.md

@@ -24,7 +24,7 @@ Replace `<name>` with the actual object name from this project's naming conventi
 | CDS Access Control (DCLS) | `<name>.dcls.asdcls` | `<name>.dcls.xml` | `ref --topic abapgit` |
 | Function Group (FUGR) | `<name>.fugr.abap` + includes | `<name>.fugr.xml` | `ref --topic abapgit` |
 | Table (TABL) | *(none — XML-only)* | `<name>.tabl.xml` | `ref --topic abapgit-xml-only` |
-| Structure (STRU) | *(none — XML-only)* | `<name>.stru.xml` | `ref --topic abapgit-xml-only` |
+| Structure (STRU) | *(none — XML-only)* | `<name>.tabl.xml` ⚠️ NOT `.stru.xml` | `ref --topic abapgit-xml-only` |
 | Data Element (DTEL) | *(none — XML-only)* | `<name>.dtel.xml` | `ref --topic abapgit-xml-only` |
 | Table Type (TTYP) | *(none — XML-only)* | `<name>.ttyp.xml` | `ref --topic abapgit-xml-only` |
 | Domain (DOMA) | *(none — XML-only)* | `<name>.doma.xml` | `ref --topic abapgit-xml-only` |

package/abap/guidelines/objects.md

@@ -15,12 +15,13 @@ grand_parent: ABAP Development
 | | SAP Namespace | Customer Namespace |
 |---|---|---|
 | **Object prefix** | `CL_*`, `IF_*`, `/NAME/CL_*`, `/NAME/IF_*`, etc. | `Z*`, `Y*` |
-| **Package prefix** | SAP-delivered (e.g. `SFIN`, `CA_*`, `/NAME/*`) | `Z*`, `Y*`, `$*` |
+| **Package prefix** | SAP-delivered (e.g. `SFIN`, `CA_*`, `/NAME/*`) | `Z*`, `Y*`, `$*` (local/non-transportable) |
 | **Ownership** | Delivered and maintained by SAP | Owned by the customer |
 | **In git repo** | Objects from an SAP-delivered package | Custom development objects |
 
 > **Rule**: Never add customer-created objects (including PoC/probe classes) into SAP namespace
 > packages. PoC objects always use `Z*`/`Y*` prefix and always go in a `Z*`, `Y*`, or `$*` package
+> (use `$*` only for throwaway probes — non-transportable)
 > — even on a project where production objects use SAP namespace.
 
 ## How to Determine This Project's Naming Convention
@@ -43,7 +44,8 @@ Applied when no `objects.local.md` exists:
 | Class | `ZCL_` | `ZCL_MY_CLASS` |
 | Interface | `ZIF_` | `ZIF_MY_INTERFACE` |
 | Program | `Z` | `ZMY_PROGRAM` |
-| Package | `$` | `$MY_PACKAGE` |
+| Package | `Z` or `Y` | `ZMYPROJECT` |
+> **Note**: `$` packages (e.g. `$TMP`) are local/non-transportable — use only for throwaway probe objects, never for real development.
 | Table | `Z` | `ZMY_TABLE` |
 | CDS View Entity | `ZC_` | `ZC_MY_VIEW` |
 | Data Element | `Z` | `ZMY_ELEMENT` |
@@ -83,3 +85,4 @@ Default package:  /MYNAMESPACE/MAIN
 
 → For file structure (what files to create): `abapgit-agent ref --topic object-creation`
 → For XML templates: `abapgit-agent ref --topic abapgit`
+→ For name **length limits** (30/16/40 char rules): `abapgit-agent ref --topic naming-limits`

package/package.json

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

package/abap/.github/copilot-instructions.md

@@ -1,264 +0,0 @@
-# ABAP Development with abapGit
-
-You are working on an ABAP project using abapGit for version control.
-
----
-
-## Critical Rules
-
-### 1. Use `ref` Command for Unfamiliar Topics
-
-**When starting to work on ANY unfamiliar ABAP topic, syntax, or pattern, you MUST use the `ref` command BEFORE writing any code.**
-
-```
-❌ WRONG: Start writing code immediately based on assumptions
-✅ CORRECT: Run ref command first to look up the correct pattern
-```
-
-**Why**: ABAP syntax is strict. Guessing leads to activation errors that waste time.
-
-| Scenario | Example |
-|----------|---------|
-| Implementing new ABAP feature | "How do I use FILTER operator?" |
-| Unfamiliar pattern | "What's the correct VALUE #() syntax?" |
-| SQL operations | "How to write a proper SELECT with JOIN?" |
-| CDS views | "How to define CDS view with associations?" |
-| Getting syntax errors | Check reference before trying approaches |
-
-```bash
-# Search for a pattern
-abapgit-agent ref "CORRESPONDING"
-abapgit-agent ref "FILTER #"
-
-# Browse by topic
-abapgit-agent ref --topic exceptions
-abapgit-agent ref --topic sql
-
-# List all topics
-abapgit-agent ref --list-topics
-```
-
-### 2. Read `.abapGitAgent` for Folder Location and Naming Conventions
-
-**Before creating ANY ABAP object file, you MUST read `.abapGitAgent` to determine the correct folder.**
-
-```
-❌ WRONG: Assume files go in "abap/" folder
-✅ CORRECT: Read .abapGitAgent to get the "folder" property value
-```
-
-The folder is configured in `.abapGitAgent` (property: `folder`):
-- If `folder` is `/src/` → files go in `src/` (e.g., `src/zcl_my_class.clas.abap`)
-- If `folder` is `/abap/` → files go in `abap/` (e.g., `abap/zcl_my_class.clas.abap`)
-
-**Also check naming conventions before creating any new object:**
-
-```
-1. Check guidelines/objects.local.md  ← project-specific overrides (if file exists)
-2. Fall back to guidelines/objects.md ← default Z/Y prefix conventions
-```
-
-`objects.local.md` is created by `abapgit-agent init` and is never overwritten by updates — it holds project-specific prefixes (e.g. `YCL_` instead of `ZCL_`).
-
-### 3. Create XML Metadata / Local Classes
-
-Each ABAP object needs an XML metadata file. Local helper/test-double classes use separate `.locals_def.abap` / `.locals_imp.abap` files.
-→ See `guidelines/object-creation.md` for XML templates and local class setup
-
-### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG, DDLS)
-
-```
-❌ WRONG: Make changes → Commit → Push → Pull → Find errors → Fix → Repeat
-✅ CORRECT: Make changes → Run syntax → Fix locally → Commit → Push → Pull → Done
-```
-
-**For CLAS, INTF, PROG, DDLS files**: Run `syntax` command BEFORE commit to catch errors early.
-
-```bash
-# Check syntax of local code (no commit/push needed)
-abapgit-agent syntax --files src/zcl_my_class.clas.abap
-
-# Check multiple INDEPENDENT files
-abapgit-agent syntax --files src/zcl_utils.clas.abap,src/zcl_logger.clas.abap
-```
-
-**For dependent files, skip `syntax` and use `pull` instead:**
-```bash
-# ❌ BAD - Interface and implementing class (may show false errors)
-abapgit-agent syntax --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
-
-# ✅ GOOD - Use pull instead for dependent files
-git add . && git commit && git push
-abapgit-agent pull --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
-```
-
-### 5. Local Helper / Test-Double Classes
-
-→ See `guidelines/object-creation.md` for local class setup (`locals_def.abap` / `locals_imp.abap`)
-
-### 6. Use `ref`, `view` and `where` Commands to Learn About Unknown Classes/Methods
-
-**When working with unfamiliar ABAP classes or methods, follow this priority:**
-
-```
-1. First: Check local git repo for usage examples
-2. Second: Check ABAP reference/cheat sheets
-3. Third: Use view/where commands to query ABAP system (if needed)
-```
-
-```bash
-# Find where a class/interface is USED
-abapgit-agent where --objects ZIF_UNKNOWN_INTERFACE
-
-# View CLASS DEFINITION
-abapgit-agent view --objects ZCL_UNKNOWN_CLASS
-```
-
-### 7. CDS Unit Tests
-
-Use `CL_CDS_TEST_ENVIRONMENT` for unit tests that read CDS views.
-→ See `guidelines/cds-testing.md` for code examples
-
-### 8. Use `unit` Command for Unit Tests
-
-**Use `abapgit-agent unit` to run ABAP unit tests (AUnit).**
-
-```
-❌ WRONG: Try to use SE24, SE37, or other transaction codes
-✅ CORRECT: Use abapgit-agent unit --files src/zcl_test.clas.testclasses.abap
-```
-
-```bash
-# Run unit tests (after pulling to ABAP)
-abapgit-agent unit --files src/zcl_test.clas.testclasses.abap
-
-# Multiple test classes
-abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.clas.testclasses.abap
-```
-
-### 9. Troubleshooting ABAP Issues
-
-| Symptom | Tool | When |
-|---|---|---|
-| HTTP 500 / runtime crash (ST22) | `dump` | Error already occurred |
-| Wrong output, no crash | `debug` | Need to trace logic |
-
-Quick start:
-```bash
-abapgit-agent dump --date TODAY --detail 1    # inspect last crash
-abapgit-agent debug set --objects ZCL_FOO:42  # set breakpoint then attach
-```
-→ See `guidelines/debug-dump.md` for dump analysis workflow
-→ See `guidelines/debug-session.md` for full debug session guide, breakpoint tips, and pull flow architecture
-
----
-
-## Development Workflow
-
-This project's workflow mode is configured in `.abapGitAgent` under `workflow.mode`.
-
-### Project-Level Config (`.abapgit-agent.json`)
-
-Checked into the repository — applies to all developers. **Read this file at the start of every session.**
-
-| Setting | Values | Default | Effect |
-|---------|--------|---------|--------|
-| `safeguards.requireFilesForPull` | `true`/`false` | `false` | Requires `--files` on every pull |
-| `safeguards.disablePull` | `true`/`false` | `false` | Disables pull entirely (CI/CD-only projects) |
-| `conflictDetection.mode` | `"abort"`/`"ignore"` | `"abort"` | Whether to abort pull on conflict |
-| `transports.allowCreate` | `true`/`false` | `true` | When `false`, `transport create` is blocked |
-| `transports.allowRelease` | `true`/`false` | `true` | When `false`, `transport release` is blocked |
-
-### Workflow Modes
-
-| Mode | Branch Strategy | Rebase Before Pull | Create PR |
-|------|----------------|-------------------|-----------|
-| `"branch"` | Feature branches | ✓ Always | ✓ Yes (squash merge) |
-| `"trunk"` | Direct to default branch | ✗ No | ✗ No |
-| (not set) | Direct to default branch | ✗ No | ✗ No |
-
-### Trunk Workflow (`"mode": "trunk"`)
-
-```bash
-git checkout main
-git pull origin main
-edit src/zcl_auth_handler.clas.abap
-abapgit-agent syntax --files src/zcl_auth_handler.clas.abap
-git add . && git commit -m "feat: add authentication handler"
-git push origin main
-abapgit-agent pull --files src/zcl_auth_handler.clas.abap
-```
-
-### Branch Workflow (`"mode": "branch"`)
-
-→ See `guidelines/branch-workflow.md` for step-by-step commands and examples
-
-### AI Tool Guidelines
-
-**When `workflow.mode = "branch"`:**
-1. ✓ Create feature branches (naming: `feature/description`)
-2. ✓ Always `git fetch origin <default> && git rebase origin/<default>` before `pull` command
-3. ✓ Use `--force-with-lease` after rebase (never `--force`)
-4. ✓ Create PR with squash merge when feature complete
-5. ✗ Never commit directly to default branch
-
-**When `workflow.mode = "trunk"` or not set:**
-1. ✓ Commit directly to default branch
-2. ✓ `git pull origin <default>` before push
-3. ✗ Don't create feature branches
-
-**When `safeguards.requireFilesForPull = true`:** always include `--files` in every `pull` command
-
-**When `safeguards.disablePull = true`:** do not run `abapgit-agent pull` at all
-
-**When `conflictDetection.mode = "abort"`:** if pull aborts with conflict error, inform user and suggest `--conflict-mode ignore` to override for that run
-
-### Quick Decision Tree
-
-```
-Modified ABAP files?
-├─ CLAS/INTF/PROG/DDLS files?
-│  ├─ Independent files (no cross-dependencies)?
-│  │  └─ ✅ Use: syntax → commit → push → pull
-│  └─ Dependent files (interface + class, class uses class)?
-│     └─ ✅ Use: skip syntax → commit → push → pull
-└─ Other types (FUGR, TABL, etc.)?
-   └─ ✅ Use: skip syntax → commit → push → pull → (if errors: inspect)
-```
-
-→ See `guidelines/workflow-detailed.md` for full workflow decision tree, error indicators, and complete command reference
-
----
-
-## Guidelines Index
-
-Detailed guidelines are available in the `guidelines/` folder:
-
-| File | Topic |
-|------|-------|
-| `guidelines/sql.md` | ABAP SQL Best Practices |
-| `guidelines/exceptions.md` | Exception Handling |
-| `guidelines/testing.md` | Unit Testing (including CDS) |
-| `guidelines/cds.md` | CDS Views |
-| `guidelines/classes.md` | ABAP Classes and Objects |
-| `guidelines/objects.md` | Object Naming Conventions (defaults) |
-| `guidelines/objects.local.md` | **Project** Naming Conventions — overrides `objects.md` (never overwritten) |
-| `guidelines/json.md` | JSON Handling |
-| `guidelines/abapgit.md` | abapGit XML Metadata Templates |
-| `guidelines/unit-testable-code.md` | Unit Testable Code Guidelines (Dependency Injection) |
-| `guidelines/common-errors.md` | Common ABAP Errors - Quick Fixes |
-| `guidelines/debug-session.md` | Debug Session Guide |
-| `guidelines/debug-dump.md` | Dump Analysis Guide |
-| `guidelines/branch-workflow.md` | Branch Workflow |
-| `guidelines/workflow-detailed.md` | Development Workflow (Detailed) |
-| `guidelines/object-creation.md` | Object Creation (XML metadata, local classes) |
-| `guidelines/cds-testing.md` | CDS Testing (Test Double Framework) |
-
-These guidelines are automatically searched by the `ref` command.
-
----
-
-## For More Information
-
-- [SAP ABAP Cheat Sheets](https://github.com/SAP-samples/abap-cheat-sheets)
-- [ABAP Keyword Documentation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm)