sap-adt-mcp 0.8.0 → 0.8.2

package/README.md

@@ -159,34 +159,66 @@ Recommended: set `readOnly: true` for QAS and PRD profiles. Keep DEV writable.
 Many internal SAP systems use self-signed certs. `"rejectUnauthorized": false`
 disables TLS validation for that profile only. Don't set this on PRD.
 
+### Audit log
+
+Every **write** the server performs against SAP (POST/PUT/DELETE/PATCH — locks,
+source updates, activations, transport operations) is appended to a local JSONL
+file, including which MCP tool triggered it and, for blocked attempts in
+read-only mode, the violation itself. Reads and read-only queries are not
+logged. Nothing leaves your machine — this is your local answer to "what exactly
+did the AI change?".
+
+Default location: `~/.sap-adt-mcp/audit.log`. One JSON object per line:
+
+```json
+{"ts":"2026-06-11T12:00:00.000Z","tool":"adt_set_source","host":"https://...","sapUser":"DEVELOPER","method":"PUT","path":"/sap/bc/adt/programs/programs/ztest/source/main","status":200,"ok":true,"transport":"E4DK900123"}
+```
+
+Configure or disable:
+
+```json
+{ "audit": { "enabled": false, "path": "/var/log/sap-adt-mcp/audit.log" } }
+```
+
+…or set `SAP_ADT_MCP_AUDIT=0` (also accepts `false`/`no`/`off`).
+
 ### Automatic error reporting
 
-When a tool call fails with an **unexpected** error, the server sends a small,
-**redacted** crash report to the maintainer so the bug can be found and fixed.
-This is **on by default** and the server prints a notice saying so on startup.
+The server sends small, **redacted** reports to the maintainer so defects get
+found and fixed. This is **on by default** and the server prints a notice saying
+so on startup. There are three channels:
 
-What is sent: the sap-adt-mcp version, Node version, OS, the tool name, and the
-error message + stack with a fingerprint for de-duplication. Before anything
-leaves your machine it is scrubbed of **hostnames, users, passwords, tokens,
-IPs, and emails**, and tool arguments are redacted the same way. Reports go to a
-relay the maintainer owns, which files/de-dups a GitHub issue — the relay holds
-the GitHub credentials, never this package.
+1. **Crash** — a tool handler throws an unexpected error.
+2. **ADT error** — a tool returns a non-2xx ADT response that the classifier
+   flags as a likely tool bug (406/415 content negotiation, malformed requests,
+   server dispatcher blow-ups). User/business-side responses (401/403/404, lock
+   and enqueue conflicts, data-preview SQL errors) are **not** reported.
+3. **Agent-reported** — the calling agent files a defect the other two channels
+   can't see (wrong data in a successful response, an ignored parameter, a
+   missing capability) via the **`adt_report_issue`** tool.
 
-What is **not** sent: expected/user-side failures (read-only violations, network
-or TLS problems, wrong credentials, config mistakes) are never reported.
+What is sent: the sap-adt-mcp version, Node version, OS, the tool name, and the
+error/finding with a fingerprint for de-duplication. Before anything leaves your
+machine it is scrubbed of **hostnames, users, passwords, tokens, IPs, and
+emails**; tool arguments and free-text fields are redacted the same way. Reports
+go to a relay the maintainer owns, which files/de-dups a GitHub issue — the
+relay holds the GitHub credentials, never this package.
 
-Turn it off completely:
+Turn it all off:
 
 ```json
-{
-  "reporting": { "enabled": false }
-}
+{ "reporting": { "enabled": false } }
 ```
 
-…or set `SAP_ADT_MCP_REPORT=0` (also accepts `false`/`no`/`off`). To keep
-reporting but exclude tool arguments, set `"reporting": { "includeArgs": false }`.
-To point at your own relay, set `"reporting": { "endpoint": "https://..." }`
-(see [`worker/`](worker/) for the relay implementation).
+…or set `SAP_ADT_MCP_REPORT=0` (also accepts `false`/`no`/`off`). Finer control:
+
+| Key | Default | Effect |
+| --- | --- | --- |
+| `reporting.enabled` | `true` | Master switch for all three channels. |
+| `reporting.adtErrors` | `true` | Channel 2 (auto-report flagged ADT errors). |
+| `reporting.allowManual` | `true` | Channel 3 (the `adt_report_issue` tool). |
+| `reporting.includeArgs` | `true` | Include redacted tool args / repro args. Note: object names can appear here. |
+| `reporting.endpoint` | relay URL | Point at your own relay (see [`worker/`](worker/)). |
 
 ## Connect a client
 
@@ -322,6 +354,31 @@ Friendly aliases (any of either column work):
 | behaviordef / bdef | BDEF |
 | messageclass / msag | MSAG |
 
+## Skills (packaged workflows)
+
+The raw tools are building blocks; [`skills/`](skills/) ships ready-made
+workflows for Claude Code that orchestrate them. Each SKILL.md lists its own
+prerequisites (minimum NetWeaver release, required authorizations, read-only
+compatibility).
+
+| Skill | What it does | Read-only OK? | Min. system |
+| --- | --- | --- | --- |
+| [`transport-release-gate`](skills/transport-release-gate/SKILL.md) | Pre-release quality gate over a TR: inactive objects, locks, syntax, ATC, unit tests → go/no-go report. Release stays a human decision. | Mostly (unit tests + release need write) | NW 7.50+, ATC configured |
+| [`dump-triage`](skills/dump-triage/SKILL.md) | ST22 triage: group dumps into families, deep-read top offenders, root cause + fix per family. | Yes — safe on PRD | NW 7.50+ (dumps feed) |
+| [`legacy-code-doc`](skills/legacy-code-doc/SKILL.md) | Reverse-document legacy Z code: structure, DB touchpoints, callers, risks, S/4 migration notes. | Yes — safe on PRD | NW 7.4x+ (data samples 7.55+) |
+| [`abap-clean-core`](skills/abap-clean-core/SKILL.md) | SAP Clean Core framework knowledge: levels, decision framework, governance. | Yes (knowledge-only) | none |
+
+To use one, copy its folder into your project's `.claude/skills/` (or
+`~/.claude/skills/` for all projects):
+
+```bash
+cp -r node_modules/sap-adt-mcp/skills/dump-triage .claude/skills/
+# or from a clone: cp -r sap-adt-mcp/skills/dump-triage .claude/skills/
+```
+
+Claude Code picks them up automatically; they trigger when the conversation
+matches (e.g. "is E4DK900123 safe to release?" → transport-release-gate).
+
 ## Clean Core: prompts + reference
 
 The server ships an opt-in **Clean Core** layer for SAP S/4HANA work.

package/config.example.json

@@ -4,7 +4,12 @@
   "readOnly": false,
   "reporting": {
     "enabled": true,
-    "includeArgs": true
+    "includeArgs": true,
+    "adtErrors": true,
+    "allowManual": true
+  },
+  "audit": {
+    "enabled": true
   },
   "systems": {
     "DEV": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-adt-mcp",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "MCP server giving Claude live access to SAP systems via ADT (ABAP Development Tools) REST. Read source, search, run syntax checks, and edit ABAP objects from any MCP-compatible client.",
   "type": "module",
   "main": "src/server.js",
@@ -10,6 +10,7 @@
   },
   "files": [
     "src",
+    "skills",
     "config.example.json",
     "README.md",
     "LICENSE"
@@ -19,7 +20,7 @@
   },
   "scripts": {
     "start": "node src/server.js",
-    "test": "node --test test/adt-error.test.js test/atc-bulk.test.js test/cds.test.js test/data-preview.test.js test/diff.test.js test/dump-feed.test.js test/grep-source.test.js test/jobs.test.js test/lifecycle-activate.test.js test/lock.test.js test/mcp-bug-fixes.test.js test/node-structure.test.js test/notes.test.js test/object-create.test.js test/object-references.test.js test/object-uris.test.js test/prompts.test.js test/provenance.test.js test/rap-scaffold.test.js test/reporter.test.js test/security.test.js test/source-chunked.test.js test/source-guard.test.js test/source-pagination.test.js test/tools-shape.test.js test/versions.test.js test/worklist.test.js",
+    "test": "node --test test/adt-error.test.js test/atc-bulk.test.js test/audit.test.js test/cds.test.js test/data-preview.test.js test/diff.test.js test/dump-feed.test.js test/grep-source.test.js test/jobs.test.js test/lifecycle-activate.test.js test/lock.test.js test/mcp-bug-fixes.test.js test/node-structure.test.js test/notes.test.js test/object-create.test.js test/object-references.test.js test/object-uris.test.js test/prompts.test.js test/provenance.test.js test/rap-scaffold.test.js test/reporter.test.js test/security.test.js test/source-chunked.test.js test/source-guard.test.js test/source-pagination.test.js test/syntax-context.test.js test/tools-shape.test.js test/versions.test.js test/worklist.test.js",
     "lint": "eslint src test"
   },
   "keywords": [

package/skills/abap-clean-core/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: abap-clean-core
+description: Apply SAP Clean Core extensibility principles whenever the user writes, reviews, refactors, or designs ABAP code for SAP S/4HANA — any deployment (Public Cloud, Private Cloud, on-premise). Use this skill any time the conversation involves ABAP extensions, custom Z-code, BAdIs, BAPIs, user exits, CDS views, RAP services, custom fields or business objects, modifications, enhancements, ATC findings, the Cloudification Repository, ABAP Cloud vs classic ABAP, on-stack vs side-by-side architecture, RISE/GROW with SAP, BTP extensions, or migrating legacy ABAP toward ABAP Cloud. Trigger generously — even when the user just mentions terms like "modification," "user exit," "enhancement spot," "implicit enhancement," "Z-program," "Z-table," "released API," "internal SAP object," "upgrade-safe," "S/4HANA migration," "clean core," "fit-to-standard," "BTP first," or "technical debt in ABAP," this skill is almost certainly relevant. Better to load it and stay quiet than to miss the context.
+---
+
+# ABAP Clean Core
+
+This skill encodes SAP's official Clean Core extensibility framework. Apply it when guiding the user through ABAP development, code review, refactoring, or architecture decisions for SAP S/4HANA.
+
+## Prerequisites
+
+None — this is a knowledge skill: it needs no SAP connection and works in any
+ABAP conversation. When sap-adt-mcp **is** connected it gets sharper:
+`adt_run_atc` / `adt_run_atc_package` verify findings against the system's real
+check variant, `adt_list_released_apis` confirms what is actually released on
+that release level, and `adt_where_used` measures the blast radius of a Level
+C/D dependency before recommending a replacement. Cloud-readiness ATC checks
+require an S/4HANA system (or a recent ATC content update on NW 7.5x).
+
+## Why Clean Core matters
+
+Every extension that touches SAP-internal objects, modifies standard code, or relies on undocumented APIs becomes a maintenance liability. It blocks upgrades, breaks unpredictably, and accumulates as technical debt that compounds over years.
+
+Clean Core is the discipline of building extensions that survive SAP upgrades automatically — by isolating custom code from the standard through stable, released interfaces. It's not theoretical: SAP's entire cloud strategy (RISE, GROW, S/4HANA Cloud) assumes customer extensions are decoupled. Code that ignores Clean Core is code that will eventually be rewritten.
+
+Clean Core spans **five principles** — Processes, Data, Integration, Operations, and Extensibility. This skill focuses on Extensibility (the code and architecture side), but be aware: when a user asks about "clean core data" or "clean core integration," they're asking about the other four principles, not about extensions.
+
+When you help with ABAP, your job is to nudge the user toward extensions that will still work after the next upgrade — without lecturing, without refusing classic-ABAP work when it's needed, but always making the trade-off visible.
+
+## Two strategic tracks: Stay Clean & Get Clean
+
+All clean core work falls into one of two efforts. Naming which one the user is in helps frame the advice.
+
+### Stay Clean — preventing new technical debt
+
+Applies to **new development**. The goal is zero unnecessary debt: every new extension at the highest achievable level, governed by a process that catches violations before they ship. When the user is writing or designing something new, you're in Stay Clean mode — enforcement-heavy, with quality gates blocking transport on Level 1–2 ATC findings.
+
+### Get Clean — reducing existing technical debt
+
+Applies to **existing custom code**. Realistic, prioritized reduction over years — eliminate Level D first ("Level D zero" is a year-one goal), then chip away at C and B. When the user is reviewing legacy or planning remediation, you're in Get Clean mode — prioritization-heavy, with tactics like the boy scout principle (every developer leaves code cleaner than they found it), the lighthouse approach (clean during major rework anyway), and a 10% annual reduction target.
+
+For the full Stay Clean / Get Clean playbook, KPI calculations, and exemption process, see `references/governance.md`.
+
+## The four cleanliness levels
+
+Every ABAP extension sits in exactly one of four "cleanliness levels." Identifying the level — and pushing it upward when possible — is the entire framework.
+
+### Level A — Released APIs (the goal)
+- Uses publicly released APIs with formal stability contracts
+- ABAP Cloud development model on-stack, or SAP Build / CAP / ABAP Cloud on BTP side-by-side
+- ATC behavior: no finding
+- Upgrade-safe by SAP guarantee
+
+**Examples:** released CDS views, business object interfaces, released BAdIs, RAP services, OData APIs documented in the SAP Business Accelerator Hub, custom fields via the Custom Fields app or extension framework.
+
+### Level B — Classic APIs (acceptable when needed)
+- Documented, historically stable APIs without a formal stability contract
+- Examples: BAPIs (e.g., `BAPI_PO_CREATE1`), released user exits, classic ALV grid (`CL_GUI_ALV_GRID`), traditional Web Dynpro
+- ATC behavior: priority 3 (informational)
+
+Use Level B when no Level A equivalent exists. Whenever possible, **wrap Level B calls in a Level A ABAP Cloud wrapper** so the rest of the codebase stays clean.
+
+### Level C — Internal SAP objects (risky, mitigate)
+- Reading internal tables, calling non-released function modules or classes
+- The *default* state of any SAP object not explicitly released — internal until proven otherwise
+- ATC behavior: priority 2 (warning)
+- Reclassification risk: SAP can move internal objects to `classic` (better) or `noAPI` (worse) at any release
+
+When unavoidable, mitigate by:
+- Enabling **Changelog for SAP Objects** in ATC, which proactively detects upcoming incompatible changes
+- Encapsulating the access in a small, well-named wrapper class
+- Tracking it in the team's technical-debt log with a planned refactor window
+
+### Level D — Modifications & noAPI (eliminate)
+- Modifications to SAP standard code (changes via modification key)
+- Direct write access to SAP core tables (UPDATE/INSERT/MODIFY on `MARA`, `VBAK`, `BSEG`, etc.)
+- Implicit enhancements that intercept SAP method behavior
+- Objects flagged as `noAPI` in the Cloudification Repository
+- ATC behavior: priority 1 (error)
+
+**Level D is the top refactoring priority.** Treat any new Level D code in code review as something that needs explicit, time-bound justification.
+
+For deep-dive on Cloudification Repository state values (`released`, `classic`, `internal`, `noAPI`, `internalAPI` with successor), released local vs remote APIs, reclassification dynamics, and per-anti-pattern remediation, see `references/levels-detailed.md`.
+
+## Decision framework
+
+Two layers: fit-to-standard first, then the SAP Application Extension Methodology if extension is justified.
+
+### Fit-to-standard ordering
+
+Before deciding *how* to extend, decide whether to extend *at all*:
+
+1. **SAP standard** — does the standard cover it?
+2. **Certified add-on** — does an SAP-validated partner solution cover it? Look for "SAP-certified for clean core" designation.
+3. **Configuration** — can configuration achieve it (SPRO, business configuration)?
+4. **Custom extension** — only when 1–3 don't cover it and the requirement is genuinely differentiating.
+
+Many "we need an extension" conversations should pause here. Building custom code for something the standard already does is the most common form of unnecessary technical debt.
+
+### SAP Application Extension Methodology (3 phases)
+
+Once an extension is justified, the official methodology structures the technology choice:
+
+- **Phase 1 — Assess Use Case.** What's the business need, what SAP data and processes does it touch, is transactional consistency required, what's the data volume, who consumes the output?
+- **Phase 2 — Assess Technology.** Map the use case to extension styles (on-stack / side-by-side / hybrid), tasks (UI, business logic, integration), and the available technologies for each, with their clean core levels.
+- **Phase 3 — Define Target Solution.** Pick the highest-Level combination that satisfies the use case. Document why anything below Level A was chosen.
+
+### "BTP first"
+
+Default to **side-by-side**. Choose on-stack only when one of these is true:
+- Transactional consistency with SAP core data is required (writing custom + standard tables in one LUW)
+- High-volume reads with complex joins on SAP standard tables
+- Frequent reads/writes to SAP standard data (latency would dominate)
+- Extension of core SAP UI / data model / business object behavior with tight coupling
+
+If neither applies clearly, side-by-side is the right answer. If both apply, you have a hybrid candidate (on-stack ABAP service exposing a released remote API, consumed by a side-by-side BTP UI/orchestration layer).
+
+For the full decision matrix, on-stack vs side-by-side criteria, hybrid deployment patterns, and worked scenarios, see `references/decision-framework.md`.
+
+## Code-level guidance
+
+### When writing new ABAP
+
+Default to ABAP Cloud syntax and patterns:
+
+- Use **CDS views** for data modeling, never raw `SELECT` chains on SAP standard tables
+- Use the **ABAP RESTful Application Programming Model (RAP)** for stateful business services — behaviors, validations, determinations
+- Use **released business object interfaces** rather than directly writing to SAP standard tables
+- Use modern ABAP language (7.40+): inline declarations, constructor expressions (`NEW`, `VALUE`, `FOR`, `REDUCE`)
+- For UI, use **SAP Fiori / SAPUI5**, not SE38 reports
+- For custom fields on SAP entities, prefer the **Custom Fields app** (key user extensibility) over ABAP-level append structures
+- **Avoid** Dynpro, Web Dynpro, classic ALV reports — they are not cloud-ready
+
+ABAP Cloud is enforced at the compiler level — code that violates the rules doesn't compile. There's no escape hatch. For the explicit allowed/forbidden lists, prebuilt services available without extra license (logging, change docs, number ranges, jobs, currency, UOM, factory calendar, XLSX), and core building blocks (RAP, CDS, business object interfaces, Custom Fields), see `references/abap-cloud-rules.md`.
+
+### When reviewing existing ABAP
+
+Flag clearly with the level. Tone: descriptive, not judgmental.
+
+**Likely Level D — flag as error:**
+- Direct `UPDATE` / `INSERT` / `MODIFY` on SAP standard tables
+- Modifications (changes via modification key)
+- Implicit enhancements (`ENHANCEMENT-POINT ... INCLUDE BOUND` patterns)
+- Field-symbol tricks reaching into SAP internal structures
+- Hardcoded references to `noAPI` objects from the Cloudification Repository
+
+**Likely Level C — flag as warning:**
+- `SELECT` from SAP standard tables that have a released CDS view equivalent
+- `CALL FUNCTION` to internal (non-released) function modules
+- `TYPE REF TO` to SAP internal classes
+- Use of internal types from non-released DDIC structures
+
+**Likely Level B — flag as informational:**
+- BAPI calls from new code (suggest: wrap them in a Level A class)
+- Classic ALV usage (acceptable for legacy reports, not for new development)
+- Web Dynpro (legacy acceptable, no new development)
+
+### Concrete refactoring patterns
+
+**Pattern 1 — Wrap a classic API to expose Level A surface:**
+
+```abap
+" Anti-pattern: BAPI called directly from cloud-namespace code
+CALL FUNCTION 'BAPI_PO_CREATE1'
+  EXPORTING
+    poheader = ls_header
+  TABLES
+    poitem   = lt_items
+    return   = lt_return.
+
+" Better: wrap in a released-style local API
+CLASS zcl_po_service DEFINITION PUBLIC FINAL CREATE PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES zif_po_service.
+ENDCLASS.
+
+CLASS zcl_po_service IMPLEMENTATION.
+  METHOD zif_po_service~create.
+    " BAPI call lives here, isolated.
+    " Callers consume only the released interface — Level A from their perspective.
+  ENDMETHOD.
+ENDCLASS.
+```
+
+The dependency on the BAPI (Level B) is now localized. Consumers stay at Level A. When a successor RAP-based equivalent appears, you change one file.
+
+**Pattern 2 — Replace internal table read with released CDS view:**
+
+```abap
+" Anti-pattern: direct SELECT on internal SAP table
+SELECT matnr, mtart, ersda
+  FROM mara
+  INTO TABLE @DATA(lt_materials)
+  WHERE mtart = 'FERT'.
+
+" Better: use released CDS view (lookup in Business Accelerator Hub)
+SELECT material, materialtype, creationdate
+  FROM i_product
+  INTO TABLE @DATA(lt_materials)
+  WHERE materialtype = 'FERT'.
+```
+
+The released view (`I_*` namespace pattern is common) carries SAP's stability contract. Field renames during upgrades become SAP's problem, not yours.
+
+**Pattern 3 — Replace modification with extension point:**
+
+When you find a modification of SAP standard:
+1. Identify the business behavior it changes
+2. Search for a **released BAdI**, **enhancement point**, or **business object interface** that exposes the same hook
+3. Reimplement the logic via that extension point
+4. If no released hook exists, file a SAP Customer Influence request, and as a bridge use a Level B classic user exit if available — never leave it as a Level D modification
+
+## "I know this is Level D, just need to ship"
+
+Respect the constraint. Deliver the working code. But:
+
+- State the level explicitly in your response
+- Note what stops working: "this will need to be revisited at the next upgrade because direct writes to `VBAK` are not upgrade-safe"
+- Sketch the Level A refactor in a few lines so it's captured for later
+- Don't refuse, don't moralize, don't repeat the lecture
+
+The user is the engineer of record. Your job is to make the trade-off visible, not to override it.
+
+## Measurement: how to know if we're winning
+
+Four KPIs make clean core progress quantifiable. Reach for these when the user asks "how is the system doing?" or wants to set targets.
+
+- **Clean Core Share** — percentage distribution of custom objects across Levels A/B/C/D. The shape of the distribution is more informative than any single number.
+- **Technical Debt Score** — weighted ATC-finding total: errors × 10 + warnings × 5 + info × 1. Use to prioritize which packages to clean up next.
+- **Unused Code Share** — percentage of custom objects with zero runtime calls (per ABAP Call Monitor / SCMON / SUSG). Cheapest cleanup target — no business risk to deletion.
+- **Business Modifications Count** — entries in `SMODILOG`. Direct count of Level D modifications.
+
+For calculation details, governance practices, and the exemption process, see `references/governance.md`.
+
+## Tooling
+
+- **ABAP Test Cockpit (ATC)** with the **ABAP Cloud Readiness** variant — automated detection of Level B/C/D issues, integrated with transport release. Priority 1–2 findings block transport by default.
+- **Cloudification Repository** — searchable catalog with state values: `released` (A), `classic` (B), `internal` (C, default), `noAPI` (D), and `internalAPI` (with successor — points you to the released replacement).
+- **Changelog for SAP Objects** (ATC check) — proactively warns when a referenced internal object is scheduled for an incompatible change in an upcoming release.
+- **SAP Business Accelerator Hub** — canonical source for released remote APIs (OData, REST, RFC, events) with documentation and code samples.
+- **SAP Note 3578329** — framework/technology classification guide.
+- **SAP Cloud ALM** — requirements management, traceability, governance for what extensions exist and why.
+- **ABAP Development Tools (ADT in Eclipse)** — required for ABAP Cloud development; classic SE80 cannot drive cloud-compliant code.
+- **Joule** — SAP AI copilot for code generation and classic-to-cloud migration assistance.
+
+## Anti-patterns to surface immediately
+
+When you see these in code under review, name the pattern and the level:
+
+- "Quick" modifications "we'll fix later" — Level D, never gets fixed
+- Copy-pasting SAP standard code into a Z-namespace ("forking the standard") — diverges over time, double maintenance burden
+- Extending SAP tables by appending custom fields directly — use the Custom Fields framework instead
+- New SE38 reports for fresh requirements — use Fiori + RAP
+- Implicit enhancements intercepting SAP method behavior — Level D, brittle, not allowed in ABAP Cloud at all
+- Direct DB updates "because we know it's safe" — never safe across upgrades
+- BAPI calls scattered through new code without wrappers — pins the codebase to Level B forever
+- ABAP-level append structures for what could be a Custom Fields app — over-engineering, transfers ownership to dev team unnecessarily
+
+## What this skill does NOT do
+
+- It does not refuse work on classic ABAP. Many real systems run on it; people need help. Provide the help, mark the level honestly.
+- It does not require the user to refactor everything immediately. The realistic playbook is: stop adding Level D, eliminate existing Level D first, then chip away at C and B over years.
+- It does not assume the user is on S/4HANA Public Cloud. Most guidance applies to Private Cloud and on-premise too; only call out edition-specific differences when they matter (e.g., on-premise still allows classic ABAP technically, but ABAP Cloud is the recommended path everywhere).
+
+## Quick reference card
+
+| Symptom in code | Likely level | First-line fix |
+|---|---|---|
+| `MODIFY mara FROM ...` | D | Use Custom Fields framework or business object interface |
+| `CALL FUNCTION 'BAPI_*'` in new code | B | Wrap in Level A class |
+| `SELECT ... FROM <SAP standard table>` | C (often) | Find released CDS view in Business Accelerator Hub |
+| `ENHANCEMENT-POINT ... INCLUDE BOUND` (implicit) | D | Use released BAdI / extension point |
+| Modification key dialog appears | D | Stop; find an extension point |
+| New SE38 report | B (classic) | Use Fiori + RAP |
+| New Web Dynpro | B (classic) | Use SAPUI5 / Fiori Elements |
+| `TYPE REF TO CL_<internal>` | C | Find released class or use released business object |
+| Custom Z-table written from custom code | A | Fine — your own namespace |
+| Custom field on SAP entity via append structure | D (often) | Use Custom Fields app (key user extensibility) |
+
+## When to load reference files
+
+- Object level uncertainty, Cloudification Repository state values, released local vs remote APIs, reclassification → `references/levels-detailed.md`
+- Architecture decisions, on-stack vs side-by-side, hybrid patterns, SAP Application Extension Methodology in detail, worked scenarios → `references/decision-framework.md`
+- Stay Clean / Get Clean playbook, KPI calculations, ATC exemption process, key user vs developer extensibility, maturity assessment → `references/governance.md`
+- ABAP Cloud allowed/forbidden lists, compiler enforcement, RAP / CDS / business object interfaces / Custom Fields, prebuilt services, classic-to-cloud migration → `references/abap-cloud-rules.md`

package/skills/abap-clean-core/references/abap-cloud-rules.md

@@ -0,0 +1,172 @@
+# ABAP Cloud Rules & Building Blocks
+
+This file expands on what's allowed and not allowed in ABAP Cloud, and covers the core building blocks (RAP, CDS, business object interfaces, custom fields, prebuilt services). Load it when:
+- The user is writing new ABAP and needs to know what's permitted
+- A code review needs to check ABAP Cloud compliance specifically
+- The user is asking about RAP, CDS, business object interfaces, or custom fields
+- The conversation involves migrating classic ABAP to ABAP Cloud
+
+## Why ABAP Cloud is the new default
+
+ABAP Cloud isn't just "ABAP with new syntax." It's a different language version with **enforced cloud-readiness and clean core compliance built into the compiler**. Code that violates the rules doesn't compile — there's no way to bypass the checks short of leaving ABAP Cloud entirely.
+
+This is intentional. In classic ABAP, clean core was advisory; you could write Level D code and the system happily ran it. In ABAP Cloud, the language itself prevents most Level D anti-patterns at compile time. That's the point.
+
+For SAP S/4HANA Cloud Private Edition, ABAP Cloud is **mandatory** for new on-stack development. For on-premise S/4HANA, classic ABAP still runs, but ABAP Cloud is the recommended path for everything new.
+
+## What's allowed in ABAP Cloud
+
+### Released local APIs
+- **Released CDS views** — read access to SAP business data with stable field names and semantics
+- **Business object interfaces** — programmatic create/read/update/delete on SAP entities, with validations and authorizations enforced by SAP standard
+- **Released BAdIs and extension points** — documented hooks for plugging custom logic into standard processes
+- **Released ABAP classes and interfaces** — the catalog of released `CL_*`/`IF_*` artifacts
+
+### Modeling and services
+- **CDS** — for data models (`@AbapCatalog.sqlViewName`, projections, annotations, calculated fields)
+- **RAP — ABAP RESTful Application Programming Model** — for services and business behaviors
+- **Web services and OData** — exposing services for remote consumption
+- **Event-based integration** via released events (raise, consume)
+
+### Prebuilt services (no extra license, no setup)
+- **Application logging** (BAL successor in cloud-friendly form)
+- **Change documents**
+- **Number ranges**
+- **Background jobs and scheduling**
+- **Factory calendar** (working days, holidays)
+- **Currency conversion** (`CL_ABAP_CURRENCY_CONV` and friends)
+- **Unit of measure conversion**
+- **XLSX processing** (read/write Excel files)
+- **Printing**
+- **Translations / internationalization** (i18n primitives)
+
+These exist precisely so that custom code doesn't reach into internal SAP services for these common needs.
+
+### Custom data
+- **Read/write access to your own custom tables** in your Z-namespace
+- **Custom CDS views** built on top of released views or your own tables
+- **Custom RAP services** exposing your own business objects
+
+### Modern ABAP language
+- Inline declarations (`DATA(...)`)
+- Constructor expressions (`NEW`, `VALUE`, `FOR`, `REDUCE`, `COND`, `SWITCH`)
+- Type-safe Open SQL with strict mode
+- Functional method calls and chaining
+- ABAP Unit testing framework
+
+## What's NOT allowed in ABAP Cloud
+
+The compiler rejects all of these:
+
+### Direct access to SAP standard
+- **Direct write to SAP standard tables** — `UPDATE MARA`, `INSERT VBAK`, `MODIFY BSEG`, etc. Use the business object interface instead.
+- **Read access to SAP-internal tables** without going through a released CDS view
+- **Calls to SAP-internal function modules or classes** — anything not in the released catalog
+- **Any reference to a `noAPI` object** from the Cloudification Repository
+
+### Non-cloud extension techniques
+- **Modifications** to SAP standard objects via modification key
+- **Implicit enhancements** (`ENHANCEMENT-POINT ... INCLUDE BOUND` patterns intercepting method behavior)
+- **Field-symbol tricks** that reach into SAP-internal structures
+- **Code copy-paste from SAP standard** with subsequent modification
+
+### Non-cloud-ready frameworks
+- **Classic Dynpro** (SAP GUI screens) — not cloud-ready, not allowed for new code
+- **Web Dynpro ABAP** — superseded by SAPUI5 / Fiori Elements
+- **Classic ALV grid** with internal class references — `CL_GUI_ALV_GRID` and friends
+- **SE38 reports** — use Fiori + RAP for new development
+
+### Untyped Open SQL
+- **Native SQL** without type safety
+- **Dynamic SQL** that bypasses the type system
+
+## Compiler enforcement is structural
+
+The above list isn't a code review checklist — it's a compile-time check. ABAP Cloud sources are compiled in a stricter mode that fails on these patterns. There's no `#pragma` to disable the checks, no escape hatch.
+
+This has two consequences:
+- **You can't accidentally violate the rules.** Code that compiles is, by construction, free of these specific anti-patterns.
+- **Migration from classic ABAP requires real work.** A classic ABAP report that uses `SELECT * FROM MARA` won't compile as ABAP Cloud — it needs to be rewritten against released CDS views.
+
+For migration assistance, **Joule** (the SAP AI copilot) provides classic-ABAP-to-ABAP-Cloud transformation suggestions; the SAP-recommended migration path uses it as the starting point.
+
+## Core building blocks
+
+### CDS views
+
+CDS (Core Data Services) is the modeling language for data and services. A CDS view defines:
+- A logical data model (entities, fields, relationships)
+- Annotations that enrich the model (UI hints, authorization, semantics)
+- Optionally, projection logic over base entities
+
+```abap
+@AccessControl.authorizationCheck: #CHECK
+@EndUserText.label: 'Active products only'
+define view entity ZI_ProductActive
+  as select from I_Product
+{
+  key Product,
+      ProductType,
+      CreationDate,
+      LastChangeDate
+}
+where ProductIsArchived = ' ';
+```
+
+The view consumes released entity `I_Product` (Level A) and exposes a filtered projection. No direct table access; SAP's stability contract on `I_Product` carries through.
+
+### RAP — RESTful Application Programming Model
+
+RAP is the framework for stateful business services. A RAP business object has three layers:
+
+- **Data model** (CDS views, including projection layer for the API surface)
+- **Behavior definition** (which actions, validations, determinations apply)
+- **Behavior implementation** (the ABAP classes implementing the behavior)
+
+RAP enforces strict logical-unit-of-work control: the framework manages transaction boundaries, no manual `COMMIT WORK` scattered through the code. Services are stateless from the caller's perspective; state lives in the LUW.
+
+When the user is building a new on-stack business service, RAP is the answer.
+
+### Business object interfaces
+
+For consuming SAP business objects (Sales Order, Purchase Order, Material Master, Customer, etc.) programmatically, the released business object interface is the entry point. It's the Level A replacement for direct table writes and BAPI calls.
+
+The pattern: import the released interface, call its methods. Validations, authorizations, change documents, and integration events are all triggered by the interface — no manual implementation needed.
+
+### Custom Fields framework
+
+For adding fields to standard SAP entities (customer, material, sales order, etc.), the Custom Fields app is the Level A path:
+- Business user adds the field through a low-code UI
+- Field is automatically available in standard UIs, reports, OData services, and integration scenarios
+- Lifecycle is managed by SAP — upgrades preserve the field
+
+Reach for ABAP only when the field needs business logic that the framework doesn't cover (uncommon).
+
+## Migration from classic ABAP
+
+Migration is rarely a mechanical translation. Common patterns:
+
+- **`SELECT FROM <SAP table>` → released CDS view** — find the released equivalent in Business Accelerator Hub
+- **`CALL FUNCTION 'BAPI_*'` → business object interface** — most BAPIs have a successor in the BO interface catalog
+- **Modification → released BAdI / extension point** — find the documented hook
+- **SE38 report → Fiori Elements analytical / list-report app** — RAP service + Fiori Elements UI
+- **Web Dynpro screen → SAPUI5 / Fiori Elements** — typically a re-architecture, not a port
+
+The realistic plan is incremental. A single classic report doesn't migrate in an afternoon — but each piece touched during normal development can move one step toward Level A.
+
+## Quick allowed/forbidden table
+
+| Pattern | ABAP Cloud verdict | Replacement |
+|---|---|---|
+| `SELECT * FROM MARA` | Forbidden | `SELECT FROM I_Product` |
+| `UPDATE VBAK SET ...` | Forbidden | Sales Order business object interface |
+| `CALL FUNCTION 'BAPI_PO_CREATE1'` | Forbidden directly; allowed via wrapper from classic | Purchase Order business object interface |
+| `CL_GUI_ALV_GRID` | Forbidden | Fiori Elements list-report |
+| `ENHANCEMENT-POINT ... INCLUDE BOUND` | Forbidden | Released BAdI |
+| Modification with key | Forbidden | Extension point or BAdI |
+| `SELECT FROM Z_MY_TABLE` | Allowed | — |
+| `SELECT FROM I_Product` | Allowed | — |
+| Inline `DATA(lt_x) = ...` | Allowed | — |
+| `NEW` / `VALUE` / `FOR` constructor expressions | Allowed | — |
+| Native SQL via `EXEC SQL` | Forbidden | Use type-safe Open SQL or CDS |
+| `CALL FUNCTION 'Z_*'` (custom RFC) | Allowed | — |