/sap-explain-role

name: sap-explain-role
description: |
  Explains what a PFCG role actually lets a user do — read-only over RFC (no GUI,
  no PFCG). Extracts the role's menu/granted transactions, decoded authorization
  values in plain language (auth-object + activity texts, not raw codes), org
  levels, and holders (with lock/validity), decomposing composite roles one level.
  A deterministic critical-grant matcher flags dangerous authorizations
  (table-maintenance change, debug-replace, SE38/SM30/SM49/SU01/PFCG, wildcard
  transaction/RFC grants, …) against a co-owned, customer-extensible
  critical_auths.tsv. Claude then narrates an audit dossier — "this role lets a
  user create and change purchase orders for company codes 1000–1999" — grounded
  strictly in the extracted TSVs. Turns the annual manual role rewrite into a
  repeatable, artifact-registered dossier. Prerequisites: SAP profile via
  /sap-login (RFC); SAP NCo 3.1 (32-bit). No GUI session, no Z-object, no dev-init.
argument-hint: "<ROLE_NAME> [--no-holders] [--critical-only] [--audience audit|technical] [--lang <L>] [--critical-file <path>] [--max-rows N]"

SAP Role Explainer (PFCG) — Audit Dossier

You explain **what a role actually permits**, read-only over RFC. PFCG's display answers this for no one — auth values are raw codes, composites hide their children. This extracts the facts deterministically and narrates them into sign-off prose an auditor accepts, grounded only in the extracted data.

Task: $ARGUMENTS

**You are read-only against SAP.** No confirm gates, no TR, no GUI. The dossier and its TSVs stay local under `{work_dir}`.

---

Shared Resources

| File | Token / call | Purpose | |---|---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | *(rule)* | Mandatory operating rules — read-only here | | `<SKILL_DIR>/references/sap_explain_role_rfc.ps1` | `-Role <n> [-IncludeHolders -Lang -MaxRows] -OutDir <d>` | The one RFC extractor (AGR_*/USR*/decode tables) | | `<SKILL_DIR>/references/sap_role_critical_match.ps1` | `-AuthsTsv -CriticalTsv -OutDir [-Role]` | Offline deterministic critical-grant matcher | | `<SKILL_DIR>/../../shared/tables/critical_auths.tsv` | matrix | Co-owned critical-grant seed (with /sap-suim); customer override at `{custom_url}\critical_auths.tsv` | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_rfc_lib.ps1` / `sap_object_resolver.ps1` / `sap_artifact_lib.ps1` | dot-sourced / Step 7 | RFC connect, `Read-SapTableRows`, artifact index |

---

Step 0 — Resolve Work Directory & OUT

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_settings_lib.ps1'; . '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('WORK_DIR=' + (Get-SapWorkDir)); Write-Output ('CUSTOM_URL=' + (Get-SapSettingValue 'custom_url' ((Get-SapWorkDir) + '\custom')))"

Set `{RUN_TEMP}` via `Get-SapRunTemp`. `{OUT}` = `Get-SapArtifactDir -ScopeKey ROLE_<NAME> -Skill sap-explain-role` (manual scope key — PFCG roles are not TADIR objects).

Step 0.5 — Start Logging

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_explain_role_run.json" -Skill sap-explain-role -ParamsJson "{}"

---

Step 1 — Parse Arguments

Default mode is **role** (bare `<ROLE>` arg). Flags: `--no-holders` (skip the USR reads), `--critical-only` (render header + criticals + coverage only — the full AGR_1251 read still runs, matching needs it), `--audience audit|technical` (default `audit` = business language), `--lang <L>`, `--critical-file <path>`, `--max-rows N` (default 50000). Uppercase the role name.

`concept <PATTERN>` is **Phase 2 (not implemented)** → say `MODE_NOT_IMPLEMENTED` and STOP.

---

Step 2 — Ensure the RFC Profile

RFC only — no GUI session. Profile pinned via `/sap-login`; the extractor self-connects. RFC unavailable → fail loud (`RFC_LOGON_FAILED`).

Step 3 — Resolve the Critical Matrix

`--critical-file` → `{custom_url}\critical_auths.tsv` → the plugin seed (`sap-project/shared/tables/critical_auths.tsv`). Log which tier won; a missing matrix marks the whole critical section COULD_NOT_CHECK (never a silent "0 hits").

---

Step 4 — Extract (RFC)

C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe -ExecutionPolicy Bypass -File "<SKILL_DIR>\references\sap_explain_role_rfc.ps1" -Role "<ROLE>" -IncludeHolders -SharedDir "<SAP_DEV_CORE_SHARED_DIR>" -OutDir "{OUT}"

Drop `-IncludeHolders` for `--no-holders`; add `-MaxRows N`. Parse:

ROLE: name=.. composite=<Y|N> children=.. text="<short text>"
SECTION: <area> rows=<n> coverage=<CHECKED|COULD_NOT_CHECK> [reason=..]
STATUS: OK | PARTIAL | ROLE_NOT_FOUND | RFC_ERROR

• `ROLE_NOT_FOUND` (exit 1) → show the `NEAR:` candidates, log end `ROLE_NOT_FOUND`, STOP.
• `PARTIAL` → carry the per-`SECTION:` coverage flags into the dossier (a

`COULD_NOT_CHECK` area — auth-denied read or `--max-rows` truncation — is rendered as such, never as empty/clean). A denied **core** area (auths) is `ROLE_READ_DENIED`; a denied **holders** area alone stays SUCCESS + PARTIAL.

• `RFC_ERROR` (exit 2) → `RFC_LOGON_FAILED`, STOP. A composite with >20 children →

volume check-in with the user before continuing (not a write gate).

The extractor writes `role_header.tsv`, `role_tcodes.tsv`, `role_auths_decoded.tsv` (src_role / object / **object_text** / auth / field / low / high / **activity_text**), `role_orglevels.tsv`, `role_holders.tsv`, `role_children.tsv` into `{OUT}`.

Step 5 — Match Critical Grants (offline)

C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe -ExecutionPolicy Bypass -File "<SKILL_DIR>\references\sap_role_critical_match.ps1" -AuthsTsv "{OUT}\role_auths_decoded.tsv" -CriticalTsv "<matrix>" -OutDir "{OUT}" -Role "<ROLE>"

Parse `CRIT:` lines + `STATUS: OK found=.. critical=.. high=.. medium=..`. `NO_MATRIX` → critical section COULD_NOT_CHECK, verdict PARTI