abapgit-agent 1.11.3 → 1.12.0

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

@@ -25,13 +25,6 @@ You are working on an ABAP project using abapGit for version control.
 | CDS views | "How to define CDS view with associations?" |
 | Getting syntax errors | Check reference before trying approaches |
 
-```bash
-# For CDS topics
-abapgit-agent ref --topic cds
-abapgit-agent ref "CDS view"
-abapgit-agent ref "association"
-```
-
 ```bash
 # Search for a pattern
 abapgit-agent ref "CORRESPONDING"
@@ -45,7 +38,7 @@ abapgit-agent ref --topic sql
 abapgit-agent ref --list-topics
 ```
 
-### 2. Read `.abapGitAgent` for Folder Location
+### 2. Read `.abapGitAgent` for Folder Location and Naming Conventions
 
 **Before creating ANY ABAP object file, you MUST read `.abapGitAgent` to determine the correct folder.**
 
@@ -58,171 +51,182 @@ 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`)
 
-### 3. Create XML Metadata for Each ABAP Object
+**Also check naming conventions before creating any new object:**
 
-**Each ABAP object requires an XML metadata file for abapGit to understand how to handle it.**
+```
+1. Check guidelines/objects.local.md  ← project-specific overrides (if file exists)
+2. Fall back to guidelines/objects.md ← default Z/Y prefix conventions
+```
 
-| Object Type | ABAP File (if folder=/src/) | XML File |
-|-------------|------------------------------|----------|
-| Class | `src/zcl_*.clas.abap` | `src/zcl_*.clas.xml` |
-| Interface | `src/zif_*.intf.abap` | `src/zif_*.intf.xml` |
-| Program | `src/z*.prog.abap` | `src/z*.prog.xml` |
-| Table | `src/z*.tabl.abap` | `src/z*.tabl.xml` |
-| CDS View | `src/zc_*.ddls.asddls` | `src/zc_*.ddls.xml` |
+`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_`).
 
-**Use `ref --topic abapgit` for complete XML templates.**
+### 3. Create XML Metadata / Local Classes
 
-### 4. Use `unit` Command for Unit Tests
+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
 
-**Use `abapgit-agent unit` to run ABAP unit tests (AUnit).**
+### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG, DDLS)
 
 ```
-❌ WRONG: Try to use SE24 or other transaction codes
-✅ CORRECT: Use abapgit-agent unit --files src/zcl_test.clas.testclasses.abap
+❌ 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
-# Run unit tests (after pulling to ABAP)
-abapgit-agent unit --files src/zcl_test.clas.testclasses.abap
+# 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
 ```
 
-### 5. Use CDS Test Double Framework for CDS View Tests
+**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
 
-**When creating unit tests for CDS views, use the CDS Test Double Framework (`CL_CDS_TEST_ENVIRONMENT`).**
+# ✅ 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:**
 
 ```
-❌ WRONG: Use regular AUnit test class without test doubles
-✅ CORRECT: Use CL_CDS_TEST_ENVIRONMENT to create test doubles for CDS views
+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)
 ```
 
-**Why**: CDS views read from database tables. Using test doubles allows:
-- Injecting test data without affecting production data
-- Testing specific scenarios that may not exist in production
-- Fast, isolated tests that don't depend on database state
+```bash
+# Find where a class/interface is USED
+abapgit-agent where --objects ZIF_UNKNOWN_INTERFACE
 
-See `../guidelines/testing.md` for code examples.
+# View CLASS DEFINITION
+abapgit-agent view --objects ZCL_UNKNOWN_CLASS
+```
 
----
+### 7. CDS Unit Tests
 
-## Development Workflow
+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
 ```
-1. Read .abapGitAgent → get folder value
-       │
-       ▼
-2. Research → use ref command for unfamiliar topics
-       │
-       ▼
-3. Write code → place in correct folder (e.g., src/zcl_*.clas.abap)
-       │
-       ▼
-4. Commit and push → git add . && git commit && git push
-       │
-       ▼
-5. Activate → abapgit-agent pull --files src/file.clas.abap
-       │
-       ▼
-6. Verify → Check pull output
-   - **Do NOT run inspect before commit/push/pull** - ABAP validates on pull
-   - **Do NOT run unit before pull** - Tests run against ABAP system, code must be activated first
-   - Objects NOT in "Activated Objects" but in "Failed Objects Log" → Syntax error (check inspect)
-   - Objects NOT appearing at all → XML metadata issue
-       │
-       ▼
-7. (Optional) Run unit tests → abapgit-agent unit --files src/zcl_test.clas.testclasses.abap (ONLY if test file exists, AFTER successful pull)
-       │
-       ▼
-8. If needed → Use inspect to check syntax (runs against ABAP system)
-```
-
-**IMPORTANT**:
-- **ALWAYS push to git BEFORE running pull** - abapGit reads from git
-- **Use inspect AFTER pull** to check syntax on objects already in ABAP
-- **Check pull output**:
-  - In "Failed Objects Log" → Syntax error (use inspect for details)
-  - Not appearing at all → XML metadata is wrong
-
-**When to use inspect vs view**:
-- **inspect**: Use when there are SYNTAX ERRORS (to find line numbers and details)
-- **view**: Use when you need to understand an object STRUCTURE (table fields, class methods)
-- Do NOT use view to debug syntax errors - view shows definitions, not errors
-
-### Commands
 
 ```bash
-# 1. Pull/activate after pushing to git (abapGit reads from git!)
-abapgit-agent pull --files src/zcl_class1.clas.abap,src/zcl_class2.clas.abap
-
-# 2. Inspect AFTER pull to check syntax (runs against ABAP system)
-abapgit-agent inspect --files src/zcl_class1.clas.abap,src/zif_interface1.intf.abap
+# Run unit tests (after pulling to ABAP)
+abapgit-agent unit --files src/zcl_test.clas.testclasses.abap
 
-# Run unit tests (multiple test classes)
+# Multiple test classes
 abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.clas.testclasses.abap
+```
 
-# View object definitions (multiple objects)
-abapgit-agent view --objects ZCL_CLASS1,ZCL_CLASS2,ZIF_INTERFACE
-
-# Preview table data (multiple tables/views)
-abapgit-agent preview --objects ZTABLE1,ZTABLE2
+### 9. Troubleshooting ABAP Issues
 
-# Explore table structures
-abapgit-agent view --objects ZTABLE --type TABL
+| Symptom | Tool | When |
+|---|---|---|
+| HTTP 500 / runtime crash (ST22) | `dump` | Error already occurred |
+| Wrong output, no crash | `debug` | Need to trace logic |
 
-# Display package tree
-abapgit-agent tree --package \$MY_PACKAGE
+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
 
 ---
 
-## Explore Unknown Objects
+## Development Workflow
+
+This project's workflow mode is configured in `.abapGitAgent` under `workflow.mode`.
 
-**Before working with unfamiliar objects, use `view` command:**
+### Project-Level Config (`.abapgit-agent.json`)
 
-```bash
-# Check table structure
-abapgit-agent view --objects ZMY_TABLE --type TABL
+Checked into the repository — applies to all developers. **Read this file at the start of every session.**
 
-# Check class definition
-abapgit-agent view --objects ZCL_UNKNOWN_CLASS
+| 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 |
 
-# Check interface
-abapgit-agent view --objects ZIF_UNKNOWN_INTERFACE
+### Workflow Modes
 
-# Check data element
-abapgit-agent view --objects ZMY_DTEL --type DTEL
+| 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
 ```
 
-AI assistant SHOULD call `view` command when:
-- User asks to "check", "look up", or "explore" an unfamiliar object
-- Working with a table/structure and you don't know the fields
-- Calling a class/interface method and you don't know the parameters
+### Branch Workflow (`"mode": "branch"`)
 
----
+→ See `guidelines/branch-workflow.md` for step-by-step commands and examples
 
-## Key ABAP Rules
+### AI Tool Guidelines
 
-1. **Global classes MUST use `PUBLIC`**:
-   ```abap
-   CLASS zcl_my_class DEFINITION PUBLIC.  " <- REQUIRED
-   ```
+**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
 
-2. **Use `/ui2/cl_json` for JSON**:
-   ```abap
-   DATA ls_data TYPE ty_request.
-   ls_data = /ui2/cl_json=>deserialize( json = lv_json ).
-   lv_json = /ui2/cl_json=>serialize( data = ls_response ).
-   ```
+**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
 
-3. **Test class name max 30 chars**: `ltcl_util` (not `ltcl_abgagt_util_test`)
+**When `safeguards.requireFilesForPull = true`:** always include `--files` in every `pull` command
 
-4. **Interface method implementation**: Use prefix `zif_interface~method_name`
+**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
 
-## Error Handling
+```
+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)
+```
 
-- **"Error updating where-used list"** → This is a **SYNTAX ERROR** (not a warning!)
-- Use `abapgit-agent inspect --files <file>` for detailed error messages with line numbers
+→ See `guidelines/workflow-detailed.md` for full workflow decision tree, error indicators, and complete command reference
 
 ---
 
@@ -232,23 +236,29 @@ 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 |
-| `../guidelines/json.md` | JSON Handling |
-| `../guidelines/abapgit.md` | abapGit XML Metadata Templates |
+| `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.
 
 ---
 
-## Object Naming
+## For More Information
 
-| Pattern | Type |
-|---------|------|
-| `ZCL_*` | Class |
-| `ZIF_*` | Interface |
-| `Z*` | Other objects |
+- [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)

package/abap/CLAUDE.md

@@ -225,7 +225,23 @@ abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.cla
 
 ---
 
-### 9. Troubleshooting ABAP Issues
+### 9. Never Run `run` Command Proactively
+
+**Never call `abapgit-agent run` unless the user explicitly asks.** A class implementing `IF_OO_ADT_CLASSRUN` can modify data, send emails, or trigger RFCs — running it automatically is unsafe.
+
+After activating a class, stop and tell the user: `"Class is activated. Run with: abapgit-agent run --class ZCL_MY_CLASS"`
+
+---
+
+### 10. Probe Classes — Use `scratchWorkspace` When Required
+
+By default, probe/throwaway classes may be created in the current project. When `disableProbeClasses: true` is set in `.abapgit-agent.json`, they must go to `scratchWorkspace` instead. If `scratchWorkspace` is also not configured, refuse and guide the user to set it up.
+
+→ See `guidelines/run-probe-classes.md` for naming conventions, full workflow, and refusal guidance
+
+---
+
+### 11. Troubleshooting ABAP Issues
 
 | Symptom | Tool | When |
 |---|---|---|
@@ -236,6 +252,7 @@ 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
+abapgit-agent run --class ZCL_MY_RUNNER       # execute and inspect output
 ```
 → 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
@@ -326,6 +343,13 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap
 1. ✗ Do not run `abapgit-agent pull` at all
 2. ✓ Inform the user that pull is disabled for this project (CI/CD only)
 
+**When `safeguards.disableRun = true`:**
+1. ✗ Do not run `abapgit-agent run` at all
+2. ✓ Inform the user that run is disabled for this project
+
+**When `safeguards.disableProbeClasses = true`:**
+1. ✗ Do not create probe classes in the current project — see Rule 10 and `guidelines/run-command.md`
+
 **When `conflictDetection.mode = "ignore"` or not set:**
 1. ✓ Run `pull` normally — no conflict flags needed
 2. ✗ Don't add `--conflict-mode` unless user explicitly asks
@@ -384,6 +408,7 @@ Detailed guidelines are available in the `guidelines/` folder:
 | `guidelines/common-errors.md` | Common ABAP Errors - Quick Fixes |
 | `guidelines/debug-session.md` | Debug Session Guide |
 | `guidelines/debug-dump.md` | Dump Analysis Guide |
+| `guidelines/run-probe-classes.md` | run Command — AI Guidelines (probe classes, scratchWorkspace) |
 | `guidelines/branch-workflow.md` | Branch Workflow |
 | `guidelines/workflow-detailed.md` | Development Workflow (Detailed) |
 | `guidelines/object-creation.md` | Object Creation (XML metadata, local classes) |

package/abap/guidelines/debug-session.md

@@ -166,7 +166,7 @@ abapgit-agent debug stack  --json                        # call stack (shows whi
 abapgit-agent debug delete --all
 ```
 
-> **If the stale debug daemon holds an ABAP lock** (symptom: `Requested object EZABAPGIT is currently locked by user CAIS`):
+> **If the stale debug daemon holds an ABAP lock** (symptom: `Requested object EZABAPGIT is currently locked by user <USER>`):
 > ```bash
 > pkill -f "debug-daemon"   # kills daemon, SIGTERM triggers session.terminate() internally
 > ```

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

@@ -0,0 +1,67 @@
+---
+layout: default
+title: run Command Guide
+nav_order: 18
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
+# run Command — AI Guidelines
+
+## Never Run Proactively
+
+`abapgit-agent run` executes live ABAP code. **Never call it unless the user explicitly asks.**
+
+A class implementing `IF_OO_ADT_CLASSRUN` can do anything — modify database records, send emails, trigger RFCs. The interface signature gives no indication of side effects.
+
+```
+User: "Write a class that reads flight data and prints it"
+→ ✓ Create the class, pull it, STOP. Do NOT run it.
+→ ✓ Tell the user: "Class is activated. Run with: abapgit-agent run --class ZCL_MY_CLASS"
+
+User: "Now run it"
+→ ✓ Run it
+```
+
+---
+
+## Probe Classes and `scratchWorkspace`
+
+### Decision flow
+
+```
+User asks to create a probe class
+├── disableProbeClasses = false / not set  →  create in current project (default)
+└── disableProbeClasses = true
+    ├── scratchWorkspace configured  →  create there (see workflow below)
+    └── scratchWorkspace not configured  →  refuse, guide user to set it up
+```
+
+### When `disableProbeClasses = true` and `scratchWorkspace` is configured
+
+**Naming** — derive from `scratchWorkspace` config in `.abapGitAgent`:
+- `classPrefix` (default: `ZCL_{USER}_`) + `<PURPOSE>`, max 30 chars
+- Example: user=`JOHN`, purpose=`OPEN_TRANSPORTS` → `ZCL_JOHN_OPEN_TRANSPORTS`
+- If name already exists in `{path}/src/`, append `_2`, `_3`, etc.
+
+**Workflow:**
+1. Read `{path}/.abapGitAgent` to confirm `folder` property (e.g. `/src/`)
+2. Write class files in `{path}/src/`
+3. Commit and push from `{path}`:
+   ```bash
+   cd {path} && git add . && git commit -m "probe: <description>" && git push
+   ```
+4. Activate:
+   ```bash
+   cd {path} && abapgit-agent pull --files src/<classname>.clas.abap
+   ```
+5. Tell user (do NOT auto-run):
+   ```
+   Class activated. Run with: abapgit-agent run --class <CLASSNAME>
+   ```
+   Run the command from the original project directory, not `{path}`.
+
+### When `disableProbeClasses = true` and `scratchWorkspace` is NOT configured
+
+Refuse and tell the user to configure `scratchWorkspace` in `.abapGitAgent`.
+→ See `docs/run-command.md` (Scratch Workspace section) for setup instructions.

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 } = require('../src/config');
+const { loadConfig, getTransport, isAbapIntegrationEnabled, getSafeguards, getConflictSettings, getTransportSettings, getScratchWorkspace } = require('../src/config');
 
 // Get terminal width for responsive table
 const getTermWidth = () => process.stdout.columns || 80;
@@ -52,6 +52,7 @@ async function main() {
     where: require('../src/commands/where'),
     dump: require('../src/commands/dump'),
     debug: require('../src/commands/debug'),
+    run: require('../src/commands/run'),
     ref: require('../src/commands/ref'),
     init: require('../src/commands/init'),
     pull: require('../src/commands/pull'),
@@ -105,7 +106,8 @@ To enable integration:
       getTransport,
       getSafeguards,
       getConflictSettings,
-      getTransportSettings
+      getTransportSettings,
+      getScratchWorkspace
     };
 
     // Execute command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.11.3",
+  "version": "1.12.0",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [

package/src/commands/init.js

@@ -4,6 +4,7 @@
 
 const pathModule = require('path');
 const fs = require('fs');
+const readline = require('readline');
 
 /**
  * Copy a file if source exists (helper for init --update)
@@ -74,6 +75,42 @@ async function copyGuidelinesFolder(srcPath, destPath, overwrite = false) {
   }
 }
 
+/**
+ * Detect old numbered guideline files (e.g. 00_index.md, 01_sql.md) and
+ * prompt user to delete them if found.
+ */
+async function cleanupOldGuidelineFiles(guidelinesPath) {
+  if (!fs.existsSync(guidelinesPath)) return;
+
+  const oldFiles = fs.readdirSync(guidelinesPath)
+    .filter(f => /^\d+_.*\.md$/.test(f));
+
+  if (oldFiles.length === 0) return;
+
+  console.log('');
+  console.log('⚠️  Old numbered guideline files detected (from a previous version):');
+  oldFiles.forEach(f => console.log(`   guidelines/${f}`));
+  console.log('   These have been renamed and are no longer used.');
+
+  const answer = await new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question('Delete old files? [Y/n] ', (ans) => {
+      rl.close();
+      resolve(ans.trim().toLowerCase());
+    });
+  });
+
+  if (answer === '' || answer === 'y' || answer === 'yes') {
+    oldFiles.forEach(f => {
+      fs.unlinkSync(pathModule.join(guidelinesPath, f));
+      console.log(`   🗑  Deleted guidelines/${f}`);
+    });
+    console.log(`✅ Old guideline files removed`);
+  } else {
+    console.log('⚠️  Old files kept — they may appear as duplicates in ref search results');
+  }
+}
+
 module.exports = {
   name: 'init',
   description: 'Initialize local repository configuration',
@@ -187,6 +224,9 @@ Examples:
         true  // overwrite
       );
 
+      // Detect and offer to remove old numbered guideline files
+      await cleanupOldGuidelineFiles(pathModule.join(process.cwd(), 'guidelines'));
+
       console.log(`
 📋 Update complete!
    Run 'abapgit-agent ref --list-topics' to see available topics.

package/src/commands/pull.js

@@ -284,11 +284,9 @@ module.exports = {
 
       if (success === 'X' || success === true) {
         console.log(`✅ Pull completed successfully!`);
-        console.log(`   Job ID: ${jobId || 'N/A'}`);
         console.log(`   Message: ${message || 'N/A'}`);
       } else {
         console.error(`❌ Pull completed with errors!`);
-        console.error(`   Job ID: ${jobId || 'N/A'}`);
         console.error(`   Message: ${message || 'N/A'}`);
       }
 

package/src/commands/run.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * run command — Execute an ABAP program or class and display its output.
+ *
+ * Programs (--program):
+ *   POST /sap/bc/adt/programs/programrun/{name}
+ *   Content-Type: application/vnd.sap.adt.programs.programRun+xml
+ *   Accept: text/plain
+ *   Note: SAP's ADT handler (CL_SEDI_ADT_PROGRAMRUN) calls SUBMIT with no
+ *         WITH additions — runtime parameters cannot be passed. The program
+ *         always runs with its coded defaults.
+ *
+ * Classes (--class):
+ *   POST /sap/bc/adt/oo/classrun/{name}
+ *   Accept: text/plain
+ *   Requires the class to implement IF_OO_ADT_CLASSRUN.
+ *   out->write() output is returned as plain text.
+ */
+
+const { AdtHttp } = require('../utils/adt-http');
+
+const PROGRAM_RUN_XML =
+  '<?xml version="1.0" encoding="UTF-8"?>\n' +
+  '<adtprog:programRun xmlns:adtprog="http://www.sap.com/adt/programs/programs"/>';
+
+module.exports = {
+  name: 'run',
+  description: 'Execute an ABAP program or class (IF_OO_ADT_CLASSRUN) and display its output',
+  requiresAbapConfig: true,
+  requiresVersionCheck: false,
+
+  async execute(args, context) {
+    const { loadConfig, getSafeguards } = context;
+
+    // Check project-level safeguards
+    const safeguards = getSafeguards();
+    if (safeguards.disableRun) {
+      console.error('❌ Error: run command is disabled for this project\n');
+      if (safeguards.reason) {
+        console.error(`Reason: ${safeguards.reason}\n`);
+      }
+      console.error('The run command has been disabled in .abapgit-agent.json');
+      console.error('Please contact the project maintainer to enable it.');
+      process.exit(1);
+    }
+
+    // Parse arguments
+    let programName = null;
+    let className = null;
+    let jsonOutput = false;
+
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--program' && args[i + 1]) {
+        programName = args[++i].toUpperCase();
+      } else if (args[i] === '--class' && args[i + 1]) {
+        className = args[++i].toUpperCase();
+      } else if (args[i] === '--json') {
+        jsonOutput = true;
+      }
+    }
+
+    if (programName && className) {
+      console.error('Error: --program and --class are mutually exclusive');
+      process.exit(1);
+    }
+
+    if (!programName && !className) {
+      console.error('Error: either --program or --class is required');
+      console.error('Usage: abapgit-agent run --program <NAME>');
+      console.error('       abapgit-agent run --class <NAME>');
+      process.exit(1);
+    }
+
+    const config = loadConfig();
+    const adt = new AdtHttp(config);
+
+    if (!adt.csrfToken) {
+      await adt.fetchCsrfToken();
+    }
+
+    let urlPath, body, requestOptions, targetName;
+
+    if (className) {
+      targetName = className;
+      urlPath = `/sap/bc/adt/oo/classrun/${className}`;
+      body = '';
+      requestOptions = { accept: 'text/plain' };
+    } else {
+      targetName = programName;
+      urlPath = `/sap/bc/adt/programs/programrun/${programName}`;
+      body = PROGRAM_RUN_XML;
+      requestOptions = {
+        contentType: 'application/vnd.sap.adt.programs.programRun+xml',
+        accept: 'text/plain'
+      };
+    }
+
+    let response;
+    try {
+      response = await adt.request('POST', urlPath, body, requestOptions);
+    } catch (err) {
+      if (jsonOutput) {
+        console.log(JSON.stringify({ success: false, target: targetName, error: err.message || String(err) }));
+      } else {
+        console.error(`Error: ${err.message || err}`);
+      }
+      process.exit(1);
+    }
+
+    const output = (response.body || '').trimEnd();
+
+    if (jsonOutput) {
+      const key = className ? 'class' : 'program';
+      console.log(JSON.stringify({ success: true, [key]: targetName, output }));
+    } else {
+      console.log('\n--- Output ---');
+      console.log(output || '(no output)');
+      console.log('--------------');
+      console.log(`✅ Completed: ${targetName}`);
+    }
+  }
+};

package/src/config.js

@@ -122,6 +122,8 @@ function getSafeguards() {
     return {
       requireFilesForPull: projectConfig.safeguards.requireFilesForPull === true,
       disablePull: projectConfig.safeguards.disablePull === true,
+      disableRun: projectConfig.safeguards.disableRun === true,
+      disableProbeClasses: projectConfig.safeguards.disableProbeClasses === true,
       reason: projectConfig.safeguards.reason || null
     };
   }
@@ -130,6 +132,8 @@ function getSafeguards() {
   return {
     requireFilesForPull: false,
     disablePull: false,
+    disableRun: false,
+    disableProbeClasses: false,
     reason: null
   };
 }
@@ -199,6 +203,22 @@ function getTransportSettings() {
   return { allowCreate: true, allowRelease: true, reason: null };
 }
 
+/**
+ * Get scratch workspace configuration from personal config (.abapGitAgent)
+ * Used by AI to create probe/throwaway ABAP classes outside the current project
+ * @returns {{ path: string, classPrefix: string, programPrefix: string }|null}
+ */
+function getScratchWorkspace() {
+  const cfg = loadConfig();
+  if (!cfg.scratchWorkspace) return null;
+  const user = (cfg.user || 'PROBE').toUpperCase();
+  return {
+    path: cfg.scratchWorkspace.path || null,
+    classPrefix: cfg.scratchWorkspace.classPrefix || `ZCL_${user}_`,
+    programPrefix: cfg.scratchWorkspace.programPrefix || `Z${user}_`
+  };
+}
+
 module.exports = {
   loadConfig,
   getAbapConfig,
@@ -211,5 +231,6 @@ module.exports = {
   getConflictSettings,
   loadProjectConfig,
   getTransportHookConfig,
-  getTransportSettings
+  getTransportSettings,
+  getScratchWorkspace
 };