These rules apply to every change in this repository. Read docs/development.md, docs/test-strategy.md, and docs/baseline-findings.md before changing ABAP objects or deployment metadata, and read system-info.md before using a live SAP system. Issue plans live in docs/plans/; move completed plans to docs/plans/finished/. Put dated investigations and external-source notes in docs/research/.
- GitHub
mainis the source of truth for released source and abapGit serialization. - Native abapGit is the source of truth for round-tripping complete SAP repository objects, including metadata XML, screens, text elements, authorization objects, tables, and transactions.
- The ABAP 7.50 and S/4HANA 2023 systems are validation targets. Never treat an unexported system change as complete.
- ARC-1 is the preferred interface for system context, focused object reads, syntax checks, ABAP Unit, and ATC. A source-only ARC-1 mirror is useful for inspection but is not a complete abapGit deployment.
- NPL/SAP_BASIS 750 validation is ARC-1/ADT-only. Do not use FLP, WebGUI, SAP GUI, or browser automation there. The maintainer provisioned its complete object set once through native abapGit's offline ZIP workflow because 7.50 cannot create the transparent table through ADT; subsequent source deployment and all validation use ARC-1. UI/browser smoke belongs to A4H/SAP_BASIS 758.
- The minimum supported language/runtime target is on-premise SAP_BASIS 750 (ABAP 7.50).
- Every production ABAP or repository-object change must also be validated on S/4HANA 2023. Documentation/tooling-only changes may mark the live gates not applicable with a reason.
- Do not introduce syntax or APIs newer than the 7.50 floor unless the issue explicitly changes compatibility and the decision is documented.
- The local abaplint release identifier
v762is its canonical mapping for on-premise SAP_BASIS 750; it does not mean that ZTOAD requires SAP_BASIS 762.
For changes that affect src/ or live behavior:
- Start a short-lived
codex/<finding-id>branch from currentmain.mainremains the stable integration/release branch; never push a red or incomplete state to it. Keep the shared native-abapGit repository onmainunless a structural-object test has an explicitly coordinated branch procedure. - Start from a clean native-abapGit/system state, select one finding, research the issue and dependencies, reproduce it with sanitized inputs, and identify the root cause. Verify that every permanent test fixture and every serialized UI prerequisite needed by the smoke test exists on all claimed target releases.
- Add the smallest failing regression test and replay it against the original production code so the intended red failure is recorded.
- Write an implementation/test/rollback plan in
docs/plans/, including ABAP 7.50 compatibility, Clean ABAP/Clean Core, abaplint, ABAP Unit, live activation/syntax/ATC, safe browser smoke, and ST22 delta. For security findings, distinguish demonstrated sink behavior from proven end-to-end entry-point reachability and state the actor prerequisites plus invariant without overclaiming. Review the plan before production changes. - Implement the smallest change that turns the test green. Refactor only while the complete suite remains green. For frontend, database, authorization, or other environment-dependent assumptions, treat the first green implementation as a spike until a live integration test confirms it. Edit source locally for source-only changes; create structural SAP objects in a development system and export them with native abapGit instead of inventing serializer XML.
- Run
npm ci,npm test,git diff --check, a complete diff review, and the relevant security/authorization review. Reconcile the review worklist againstgit diff --name-only; if a generic scanner or extension classifier omits an ABAP source file, add it explicitly rather than accepting partial coverage. When input is generated, wrapped, split, serialized, or otherwise transformed before execution, compare security semantics on both sides of that representation boundary; comments, quoting, escaping, length limits, and line/token boundaries must not hide behavior. Freeze the source/repository-object candidate in a commit before expensive live validation and record its commit plus source hash. Any subsequentsrc/or serialized-object change invalidates syntax, Unit, ATC, and smoke evidence and requires those affected gates to be rerun. Deploy the exact candidate to each available SAP target without pretending that the shared abapGitmainlink represents an unmerged branch. - On SAP_BASIS 750 first when available, then S/4HANA 2023, require controlled activation, active syntax, all ABAP Unit tests, and complete ATC runs or explicit prerequisite failures. An ARC-1 write acknowledgement or
activate=truerequest is not activation evidence: call activation explicitly, require active/inactive main-object equality, and query inactive child parts (including screens, GUI statuses, text elements, and includes) for every changed composite object. Main-source equality alone is not a pass when a child part remains inactive. Run a fresh-session safe browser smoke and ST22 delta on A4H only. Enter editor input with real user-like actions and the control's change/blur sequence; a DOM value set by automation is diagnostic only until the SAP backend executes that exact query. A generic browser error alone does not prove whether parsing, compilation, or runtime execution failed: pair it with a direct regression at the intended boundary and use a live fixture whose target grammar is already proven. If the SAP logon shell is entirely non-interactive in an automation browser, do not make it visible or submit it by DOM mutation; when the user did not require that browser, use an authenticated supported browser session, otherwise report the gate unavailable. Snapshot the latest dump ID/timestamp before smoke and compare the returned dump set client-side afterward; do not assume a diagnosticfromfilter was honored. A failed/unavailable gate is never a pass. After evidence is complete, restore every directly deployed object on a shared target to the intendedmainstate and verify activation/object state, unless the maintainer explicitly reserves that candidate for the next task. - Perform a final implementation review, update finding evidence, commit with a Conventional Commit subject, push the branch, open a pull request, and wait for required CI to become green.
- After the first green PR run, audit the plan, implementation, test evidence, CI output, and development process. Apply useful process/documentation improvements to the same PR, move its plan to
docs/plans/finished/, push, and wait for CI again. Record the final green run in the PR description or a PR comment; do not create a new evidence-only commit that invalidates the checked head. - Merge only after the maintainer accepts any recorded live-system limitations. Use GitHub's squash merge so the reviewed PR lands as one Conventional Commit; do not expose red/green/audit workflow commits on
main. Pull the resultingmain, verify Release Please behavior, and do not manually tag an ordinary release.
For a source-only candidate, a controlled direct source deployment is preferable to switching the shared native-abapGit repository away from main. Record the candidate commit/hash and activate only the intended object. Structural changes still require a real native-abapGit round trip and may need a dedicated package/system to avoid changing shared objects underneath other work.
When several PRs change the same ABAP object, keep them independently reviewable but integrate them sequentially. After each merge, rebase the next PR onto current main, resolve the source and test corpus deliberately, recompute aggregate findings/test counts, and rerun all affected local and live gates. Do not resolve a large overlap by accepting either side wholesale, and keep branch-specific counts in the finding plan/register rather than in long-lived workflow prose.
For a coordinated structural-object round trip, refresh native abapGit before staging, review all system/Git drift, and select only the intended object. Never use Add All when unrelated changes are present. Review the staged filenames before commit, record every intentionally unselected drift item, push, refresh again, and require the intended object to be clean.
When ARC-1's abapGit bridge is used to restore the shared repository branch, pass the full ref refs/heads/main and verify the result with a fresh repository read. A short branch value can return success without changing the selected branch on the current A4H bridge.
For ZTOAD program installation evidence, run the repository installation contract through npm test. On a live structural target, capture SAPRead(type="INACTIVE_OBJECTS") as JSON and run node scripts/installation-contract.mjs --inactive-objects <file>. The live gate must show no PROG/P, PROG/PCA, PROG/PS, or PROG/PX part for ZTOAD before GUI/runtime smoke is considered valid.
If ARC-1's pre-write linter selects the wrong ABAP release, bypass only that local lint step after the repository's pinned abaplint gate is green. Keep server preflight, explicit activation, SAP syntax, Unit, ATC, and object-state verification enabled, and record the tooling mismatch in the findings register.
ZTOAD's report source is large enough that streaming a complete SAPWrite JSON payload through stdin can return EAGAIN. If that occurs, create a bounded temporary JSON payload file, pass its path to ARC-1, and verify the subsequent write before activation; never interpret the failed streamed request as a deployed candidate. Capture very large ATC JSON to a temporary file and emit an exact count/priority/prerequisite summary so terminal truncation cannot corrupt the evidence.
When automating the ARC-1 CLI, parse the returned MCP envelope as well as the process status: a tool failure can be returned as JSON with isError: true while the CLI process still exits with status 0. Treat that envelope as a failed gate and never continue to activation. SAP_ALLOWED_PACKAGES is the canonical allowlist variable, and a long-running MCP process does not acquire later environment/configuration changes; restart it or use a bounded fresh process after an allowlist change, then verify the target system before writing.
If ARC-1 authentication or a live system is unavailable, local checks may continue, but do not claim live validation. Record the missing gate in the PR and complete it before merge unless the maintainer explicitly accepts the risk.
NPL now has the complete ZTOAD object set in offline native-abapGit package $ZTOAD2, including the real transparent table. Never replace that table with a DDIC structure. Use ARC-1 for exact source deployment, explicit activation, syntax, Unit, ATC, and inactive-object checks. Structural refreshes require another reviewed native-abapGit ZIP import; do not export the local root package or accept release-normalized table metadata as a source change without a dedicated structural review. The missing table enhancement category is tracked separately as BASE-DDIC-001.
- New or changed non-GUI logic requires ABAP Unit coverage whenever technically feasible.
- Follow red–green–refactor: reproduce and make a focused test fail before changing production behavior.
- Existing open defects belong in the findings register; do not keep permanently failing or disabled regression tests on
main. - Put report test classes at the end of the program and declare them
FOR TESTING RISK LEVEL HARMLESS DURATION SHORT. - Prefer data-in/data-out parser and generator units with no database commits, user-specific state, frontend GUI, or persistent fixtures.
- Extract testable logic behind small local classes instead of adding more behavior to large
FORMroutines. - Use dependency injection for external collaborators. Use test seams only as a temporary legacy-code bridge.
- Test both the success path and invalid/untrusted input. ZTOAD executes dynamic SQL, so authorization boundaries, dynamic table/column input, escaping, DML, and native SQL are security-sensitive.
- For generated source, test the actual emitted line representation: split only at whitespace outside literals, reject unsafe hard cuts, and never move
*into ABAP source column one. - Generated-source test fixtures must themselves use grammar supported by SAP_BASIS 750. If the floor compiler rejects a fixture before the intended invariant is reached, isolate the grammar in dry-run compiler probes and correct the fixture before changing production code.
- When a tokenizer or masker rebuilds text character by character, run its whitespace-preservation regression on SAP; converting a fixed-length
TYPE cblank into a string can trim the separator even when static lint is green. - When the same grammar feature is recognized at more than one stage (for example parser, authorization scanner, and generator sink), share the predicate/normalization where possible and add a full-path regression through every stage. Exercise tabs, line breaks, and repeated spaces; a parser-only test does not prove that the executable representation selects the same path.
- ABAP Unit tests must not change customizing or persistent business data. Any integration test that writes must use an explicitly disposable Z table and be cleaned up.
- Local abaplint is a fast compatibility/static gate, not a substitute for SAP syntax, activation, ABAP Unit, or ATC.
- ABAP Unit and syntax cannot prove that a Control Framework class is supported by a particular frontend. GUI-control changes require a new browser session against the exact active candidate plus a post-run dump check.
- Scope browser interaction to the editor control. After ALV renders, grid cells also expose textbox roles, so an unscoped textbox locator is ambiguous and must not be used as evidence of an editor action.
- For an error-path UI smoke, record what independently proves that the intended parser/compiler/runtime boundary was reached. The generic user message and an unchanged dump set prove safe presentation, not boundary reachability by themselves.
- Default smoke tests to read-only
SELECTstatements against non-sensitive test data. - Never use production data, credentials, personal data, or confidential query text in issues, commits, CI logs, or test fixtures.
- Do not enable or broaden INSERT, UPDATE, DELETE, native SQL, or authorization defaults as part of an unrelated change.
- Do not run destructive SQL merely to prove parsing. DML/native tests require an isolated table, explicit authorization, and a cleanup plan.
- Resolve and record the ATC variant used on each system. Prefer the same effective checks on both systems.
- Record whether an ATC run was complete. Zero displayed findings with missing prerequisite checks is incomplete, not a pass.
- Before judging a UI product regression, verify the installed dynpro, GUI status, transaction, and other serialized prerequisites. Record installation drift as its own finding while keeping the overall end-to-end gate blocked.
- Keep abapGit object files under
src/; root documentation and CI files are outside.abapgit.xml's/src/starting folder. - Keep active plans under
docs/plans/, completed plans underdocs/plans/finished/, and dated research underdocs/research/. - Preserve lower-case abapGit filenames and LF line endings.
- Do not reformat the legacy report as part of an unrelated fix.
- Release Please owns
CHANGELOG.md,version.txt, and the annotated version lines inREADME.mdandsrc/ztoad.prog.abapafter bootstrap. - Do not manually tag ordinary releases. Merge the Release Please PR after its checks and version diff are reviewed. With the default
GITHUB_TOKEN, approve its queued Quality workflow in GitHub before waiting for green CI.