From 9e11297b90b0eb2eaf75529acbbfa77e928c75f4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9Emarianfoo=E2=80=9C?=
<13335743+marianfoo@users.noreply.github.com>
Date: Thu, 6 Aug 2026 13:11:32 +0200
Subject: [PATCH 1/5] test: define ZTOAD transaction contract
---
docs/plans/base-bug-006.md | 52 ++++++++++++++
.../2026-08-06-base-bug-006-transaction.md | 67 +++++++++++++++++++
package.json | 3 +-
scripts/repository-contract.mjs | 36 ++++++++++
4 files changed, 157 insertions(+), 1 deletion(-)
create mode 100644 docs/plans/base-bug-006.md
create mode 100644 docs/research/2026-08-06-base-bug-006-transaction.md
create mode 100644 scripts/repository-contract.mjs
diff --git a/docs/plans/base-bug-006.md b/docs/plans/base-bug-006.md
new file mode 100644
index 0000000..8a37108
--- /dev/null
+++ b/docs/plans/base-bug-006.md
@@ -0,0 +1,52 @@
+# BASE-BUG-006 plan: serialized ZTOAD transaction
+
+_Date: 2026-08-06 · branch: `codex/fix-base-bug-006` · issue: [#2](https://github.com/marianfoo/ztoad/issues/2)_
+
+## Goal
+
+Ship native-abapGit metadata for a stable `ZTOAD` report transaction, prove direct A4H launch through FLP and standalone WebGUI, and make omission or semantic drift of that transaction fail the normal local/CI test command.
+
+## Scope and invariants
+
+- Stay on a short-lived branch from refreshed `master`.
+- Preserve the executable report's `START-OF-SELECTION` entry path by using a report transaction for program `ZTOAD` and generated selection screen `1000`.
+- Support SAP GUI for HTML and Windows; make no untested Java-GUI claim.
+- Produce `src/ztoad.tran.xml` only through active A4H transaction maintenance plus native abapGit serialization.
+- Do not change production ABAP logic for this structural bug.
+- Do not use FLP, WebGUI, SAP GUI, or browser automation on NPL. NPL checks are ARC-1/ADT-only.
+- Keep `BASE-BUG-007` separate: missing installed `STATUS010` may block query dispatch but must not be misclassified as a transaction-launch failure.
+
+## TDD and implementation sequence
+
+1. **Research/root cause:** confirm issue #2, absent repository/live transaction, report-vs-dialog semantics, abapGit `TRAN` support, authorization effects, and dual-system constraints. Record the result in the linked research note.
+2. **Red repository contract:** add a dependency-free Node test that requires the canonical `TRAN ZTOAD` file and its launcher semantics. Wire it into `npm test`, run it before the object exists, and record the expected failure.
+3. **Plan review:** verify the test checks behavior-defining metadata without duplicating the entire serializer format; verify structural creation, clean-core, security, compatibility, rollback, and installation drift are addressed.
+4. **A4H creation:** use SE93 to create report transaction `ZTOAD` for program `ZTOAD`, package `ZTOAD`, short text `ZTOAD SQL query tool`, HTML/Windows support, and the existing modifiable workbench request.
+5. **Native serialization:** use native abapGit to stage only `TRAN ZTOAD` on this feature branch, inspect the XML, commit/push it, and verify a subsequent stage/refresh is clean. Do not stage unrelated A4H drift.
+6. **Local green/refactor:** make the repository contract reflect the native result, then run `npm ci`, `npm test`, and `npm run lint:quality`. Review the diff for hand-authored XML, credentials, generated noise, authorization changes, and new strict-lint debt.
+7. **Live validation:** use ARC-1/ADT on A4H for transaction metadata, active/inactive state, syntax, ABAP Unit, and ATC. Record ST22 before and after fresh direct FLP and standalone WebGUI launches. Prove the transaction resolves and reaches ZTOAD; preserve `BASE-BUG-007` as the independent dispatch blocker if still present.
+8. **NPL validation:** use only the configured ARC-1/ADT connection. Read `TRAN ZTOAD` and run every applicable lifecycle gate. Record native-serialization/install limitations as blocked, never as passed or silently skipped.
+9. **Implementation review:** inspect the final diff and evidence against the research decision, Clean ABAP/clean-core guidance, compatibility, security, docs, issue register, and release note.
+10. **PR and first CI:** open a draft PR with red/green and live-system evidence; wait for every required check to finish green.
+11. **Post-green process audit:** review the complete workflow and GitHub results. Put any clearly beneficial documentation, test-contract, PR-template, or CI improvement into the same PR. If a workflow changes, treat it as a new CI cycle.
+12. **Final CI:** push the audit changes and wait until the PR is green again. Move this plan to `docs/plans/finished/` only when all achievable gates and the audit are complete.
+
+## Plan review
+
+The plan is intentionally structural:
+
+- A local file-existence/semantic contract supplies the missing red-green signal; ABAP Unit is not suitable because the transaction is an external repository object, not report logic.
+- The contract will check only the serializer identity, transaction/program/screen/type, English description, and required GUI support. It will not snapshot the full XML or system-specific fields.
+- The native serializer remains authoritative. If A4H emits different but valid metadata, review the semantic decision and update the test from the serialized result rather than editing XML to satisfy a guessed shape.
+- Direct launch and the ADT transaction read test different risks: repository portability versus runtime routing. Both are required on A4H.
+- NPL's ADT-only boundary makes native `TRAN` creation/round-trip unavailable; documenting that exact missing gate is more accurate than using a forbidden UI workaround.
+- Rollback is a normal revert plus native abapGit pull/uninstall of `TRAN ZTOAD`; no database data is created or migrated.
+
+## Evidence log
+
+- Red baseline: `npm test` on 2026-08-06 passed configured abaplint with 0 issues, then failed in `scripts/repository-contract.mjs` with `Missing native-abapGit transaction object: src/ztoad.tran.xml`.
+- Local green: pending.
+- A4H ADT/live/native-abapGit: pending.
+- NPL ARC-1/ADT-only: pending.
+- First PR CI: pending.
+- Post-green process audit and final CI: pending.
diff --git a/docs/research/2026-08-06-base-bug-006-transaction.md b/docs/research/2026-08-06-base-bug-006-transaction.md
new file mode 100644
index 0000000..a95d5ef
--- /dev/null
+++ b/docs/research/2026-08-06-base-bug-006-transaction.md
@@ -0,0 +1,67 @@
+# BASE-BUG-006 transaction research
+
+_Date: 2026-08-06 · finding: `BASE-BUG-006` · issue: [#2](https://github.com/marianfoo/ztoad/issues/2)_
+
+## Problem and red baseline
+
+The repository has no `src/ztoad.tran.xml`. A4H's ADT transaction read for `ZTOAD` currently returns empty description, program, and package fields. The stable direct URLs therefore have no repository-managed transaction to resolve:
+
+- FLP: `#Shell-startGUI?sap-ui2-tcode=ZTOAD`
+- standalone WebGUI: `~transaction=ZTOAD`
+
+Issue #2 asks for a transaction code and reports that a locally created transaction could not be committed. This is a structural-repository problem: source-only editing cannot create a complete `TRAN` object and hand-writing its XML would bypass the native serializer.
+
+## Transaction type decision
+
+SAP distinguishes a report transaction, which starts an executable program through `SUBMIT`, from a dialog transaction, which loads a program and starts a specific dynpro after `LOAD-OF-PROGRAM`.
+
+ZTOAD is an executable report (`SUBC=1`). Its entry point is:
+
+```abap
+START-OF-SELECTION.
+ CALL SCREEN 10.
+```
+
+Therefore `TRAN ZTOAD` should be a **report transaction** for program `ZTOAD`, not a dialog transaction aimed directly at screen `0010`. A direct dynpro transaction would bypass the report event sequence and make future initialization behavior surprising. The canonical generated selection-screen number for the report transaction is `1000`; because ZTOAD has no visible selection parameters, startup proceeds to `START-OF-SELECTION` and screen `0010`.
+
+The transaction must explicitly support SAP GUI for HTML and SAP GUI for Windows. HTML support is required for the A4H FLP/WebGUI acceptance path; Windows support preserves the original desktop use case. SAP GUI for Java is not claimed until it has a live compatibility test.
+
+## Serialization decision
+
+abapGit lists `TRAN` as a supported on-premise object type. Its current `LCL_OBJECT_TRAN` serializer reads `TSTC`, `TSTCC`, `TSTCT`, optional `TSTCP`, authorization assignments, and translations. It classifies report transactions from the `TSTC-CINFO` report bit and recreates them through SAP's transaction insertion API.
+
+Consequences for this fix:
+
+1. Create `ZTOAD` in A4H transaction maintenance with package `ZTOAD` and the existing workbench request.
+2. Let native abapGit serialize the active object; do not construct `ztoad.tran.xml` by hand.
+3. Review the resulting `TSTC`, `TSTCC`, and `TSTCT` semantics and commit only `TRAN ZTOAD` from the SAP system.
+4. Keep a repository contract test so removing or changing the required launcher fails `npm test` even though abaplint cannot infer that a transaction is mandatory from the report alone.
+
+abapGit intentionally serializes only active, consistent object state and excludes system-specific users, timestamps, and inactive versions. A native round trip is therefore both the portability test and the source of truth for the XML format.
+
+## Compatibility and clean-core assessment
+
+- `TRAN` is supported by native abapGit for classic on-premise systems, including the SAP_BASIS 750 and 758 targets.
+- This launcher adds no ABAP source and no released-API dependency. It does add the normal transaction-start authorization gate (`S_TCODE`) before ZTOAD's existing application authorization checks.
+- A classic SE93 transaction is not an ABAP Cloud artifact. ZTOAD remains an on-premise compatibility product and does not become clean-core Level A through this change.
+- NPL is intentionally ADT-only. ARC-1 can read transaction metadata but the available ADT surface cannot create or native-abapGit-round-trip `TRAN`; no NPL GUI fallback is allowed. That live structural gate must be reported as blocked, not passed.
+- A4H currently lacks installed GUI status `STATUS010` (`BASE-BUG-007`). Direct launch can prove transaction resolution, report entry, screen rendering, and dump behavior, but the first query dispatch remains a separate blocked gate.
+
+## Acceptance evidence required
+
+- focused repository test is red before serialization and green afterward;
+- `npm ci`, configured abaplint, and the full diagnostic abaplint profile are reviewed;
+- A4H ADT read reports transaction `ZTOAD` mapped to program `ZTOAD` in package `ZTOAD`;
+- native abapGit reports the transaction clean after the push/round trip;
+- direct FLP and standalone WebGUI URLs reach ZTOAD without an unknown-transaction error;
+- A4H active source, syntax, all ABAP Unit tests, selected ATC variants, and ST22 delta are checked;
+- NPL ARC-1/ADT reads and available lifecycle gates are recorded without browser, FLP, WebGUI, or SAP GUI automation.
+
+## Sources
+
+- [SAP ABAP Keyword Documentation: report transaction](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/ABENREPORT_TRANSACTION_GLOSRY.html)
+- [SAP ABAP Keyword Documentation: dialog transaction](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/ABENDIALOG_TRANSACTION_GLOSRY.html)
+- [SAP ABAP Keyword Documentation: transaction code](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/ABENTRANSACTION_CODE_GLOSRY.html)
+- [abapGit supported object types](https://docs.abapgit.org/user-guide/reference/supported.html)
+- [abapGit serializer overview](https://docs.abapgit.org/development-guide/serializers/overview.html)
+- [abapGit `TRAN` serializer](https://github.com/abapGit/abapGit/blob/main/src/objects/zcl_abapgit_object_tran.clas.abap)
diff --git a/package.json b/package.json
index c238403..c89a57c 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,8 @@
"scripts": {
"lint": "abaplint",
"lint:quality": "node scripts/abaplint-quality.mjs",
- "test": "npm run lint"
+ "test:repository": "node scripts/repository-contract.mjs",
+ "test": "npm run lint && npm run test:repository"
},
"engines": {
"node": ">=18"
diff --git a/scripts/repository-contract.mjs b/scripts/repository-contract.mjs
new file mode 100644
index 0000000..2bee415
--- /dev/null
+++ b/scripts/repository-contract.mjs
@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import { strict as assert } from "node:assert";
+
+const transactionPath = new URL("../src/ztoad.tran.xml", import.meta.url);
+
+let transactionXml;
+
+try {
+ transactionXml = await readFile(transactionPath, "utf8");
+} catch (error) {
+ if (error?.code === "ENOENT") {
+ throw new Error("Missing native-abapGit transaction object: src/ztoad.tran.xml");
+ }
+ throw error;
+}
+
+const expectedFragments = [
+ 'serializer="LCL_OBJECT_TRAN"',
+ "ZTOAD",
+ "ZTOAD",
+ "1000",
+ "gA==",
+ "E",
+ "ZTOAD SQL query tool",
+ "1",
+ "X",
+];
+
+for (const fragment of expectedFragments) {
+ assert.ok(
+ transactionXml.includes(fragment),
+ `src/ztoad.tran.xml is missing required launcher metadata: ${fragment}`,
+ );
+}
+
+console.log("Repository contract passed: TRAN ZTOAD is serialized for report, WebGUI, and Windows startup.");
From 8fb31315f444303bc774871de212a5d5681a5a4b Mon Sep 17 00:00:00 2001
From: marianfoo <13335743+marianfoo@users.noreply.github.com>
Date: Thu, 6 Aug 2026 11:19:52 +0000
Subject: [PATCH 2/5] fix: add ZTOAD transaction launcher
---
src/ztoad.tran.xml | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
create mode 100644 src/ztoad.tran.xml
diff --git a/src/ztoad.tran.xml b/src/ztoad.tran.xml
new file mode 100644
index 0000000..1294a6a
--- /dev/null
+++ b/src/ztoad.tran.xml
@@ -0,0 +1,23 @@
+
+
+
+
+
+ ZTOAD
+ ZTOAD
+ 1000
+ gA==
+
+
+ ZTOAD
+ 1
+ X
+
+
+ E
+ ZTOAD
+ ZTOAD SQL query tool
+
+
+
+
From fe46f14aac7b526b474aac8b65a305470754454d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9Emarianfoo=E2=80=9C?=
<13335743+marianfoo@users.noreply.github.com>
Date: Thu, 6 Aug 2026 13:29:50 +0200
Subject: [PATCH 3/5] docs: record BASE-BUG-006 validation
---
docs/baseline-findings.md | 4 ++--
docs/development.md | 4 ++--
docs/plans/base-bug-006.md | 8 +++++---
.../research/2026-08-06-base-bug-006-transaction.md | 12 ++++++++++--
docs/test-strategy.md | 3 ++-
system-info.md | 13 +++++++------
6 files changed, 28 insertions(+), 16 deletions(-)
diff --git a/docs/baseline-findings.md b/docs/baseline-findings.md
index 7ed5cbf..aa9023b 100644
--- a/docs/baseline-findings.md
+++ b/docs/baseline-findings.md
@@ -1,6 +1,6 @@
# ZTOAD baseline findings
-_Snapshot: 2026-08-06 · branch `codex/fix-base-run-001` · live system A4H client 001, SAP_BASIS 758 SP02 · secondary target NPL client 001, SAP_BASIS 750 SP02_
+_Snapshot: 2026-08-06 · branch `codex/fix-base-bug-006` · live system A4H client 001, SAP_BASIS 758 SP02 · secondary target NPL client 001, SAP_BASIS 750 SP02_
This is the ordered work list for incremental TDD. It records observed defects separately from broad style debt so a new failure cannot disappear inside the legacy backlog. A finding is closed only after its regression test is green locally where possible, green on A4H, and green on the SAP_BASIS 750 target.
@@ -36,7 +36,7 @@ Priority meanings: **P0** blocks the requested test workflow or is an immediate
| BASE-BUG-003 | P1 | [Issue #4](https://github.com/marianfoo/ztoad/issues/4): `SUBSTRING`/`CONCAT` produce “No component exists with the name SUBSTRING(”, exposing naïve select-list tokenization. | Nested function arguments, commas inside functions, aliases, literals containing spaces/commas, and function composition. | Open |
| BASE-BUG-004 | P1 | Keyword detection uses string searches and space splitting rather than quote/parenthesis-aware lexical tokens. Keywords in literals, comments, functions, or subqueries can move clause boundaries. | Quoted `FROM`, `WHERE`, `UNION`, `UP TO`; escaped quotes; comments; nested parentheses; multiline queries. | Open |
| BASE-BUG-005 | P1 | `UNION` splitting is whitespace-sensitive and does not model `UNION ALL`; branches are appended while assuming compatible result layouts. | `UNION`, `UNION ALL`, mismatched branch types/columns, per-branch limits, and keywords in literals/subqueries. | Open |
-| BASE-BUG-006 | P1 | [Issue #2](https://github.com/marianfoo/ztoad/issues/2): no serialized `TRAN ZTOAD` exists, so FLP/WebGUI cannot launch a stable ZTOAD transaction directly. | Native-abapGit round-trip on both systems plus direct FLP and standalone WebGUI launch tests. | Open |
+| BASE-BUG-006 | P1 | [Issue #2](https://github.com/marianfoo/ztoad/issues/2): no serialized `TRAN ZTOAD` existed, so FLP/WebGUI could not launch a stable ZTOAD transaction directly. | Repository contract, native-abapGit round trip, direct FLP and standalone WebGUI launch, ST22 delta, and ADT-only 7.50 availability check. | Fixed candidate: local contract green; native A4H object clean; both launch paths reach ZTOAD with no new dump. Exact NPL install remains prerequisite-blocked because all ZTOAD objects are absent. |
| BASE-BUG-007 | P1 | [Issue #5](https://github.com/marianfoo/ztoad/issues/5): source-only/manual installation is incomplete. A4H currently reaches screen 0010 but reports missing GUI status `STATUS010` even though repository `ztoad.prog.xml` serializes it; complete ZTOAD also needs its dynpros, TABL, and SUSO. | Fresh-package native-abapGit install test verifying all serialized objects and GUI metadata activate, `STATUS010` exists, and the first read-only query can be dispatched. | Open; currently blocks full A4H query smoke |
| BASE-RUN-002 | P1 | Generated-program failures are not isolated into a stable error contract; dumps or generated source can leak query details. | Syntax/runtime exception tests with sanitized error output and no ST22 dump for expected bad input. | Open |
| BASE-RUN-003 | P1 | The generated subroutine-pool approach has a finite per-session pool budget and encourages session restart behavior instead of bounded execution objects. | Repeated-query stress test across the documented maximum, checking graceful handling and cleanup. | Open |
diff --git a/docs/development.md b/docs/development.md
index 19bd9b0..3cb5880 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -4,7 +4,7 @@ This is the normative workflow for future issues and features. Its goal is fast
## 1. Architecture and trust boundaries
-ZTOAD is not only `src/ztoad.prog.abap`. The report also depends on its program metadata and dynpros (`ztoad.prog.xml`), persisted-query table (`ztoad.tabl.xml`), and authorization object (`ztoad_auth.suso.xml`). Future transaction codes or other repository objects will add more serialized files.
+ZTOAD is not only `src/ztoad.prog.abap`. The report also depends on its program metadata and dynpros (`ztoad.prog.xml`), persisted-query table (`ztoad.tabl.xml`), authorization object (`ztoad_auth.suso.xml`), and report transaction (`ztoad.tran.xml`).
Use each tool for the part it can represent faithfully:
@@ -58,7 +58,7 @@ On A4H, the Fiori-shell URL for the transaction is:
`https://a4h.marianzeis.de/sap/bc/ui2/flp?sap-client=001#Shell-startGUI?sap-ui2-tcode=ZABAPGIT`
-Do not manually install only the report source. That omits the dynpros, table, and authorization object and cannot reproduce a supported installation.
+Do not manually install only the report source. That omits the dynpros, table, authorization object, and transaction and cannot reproduce a supported installation. The repository-managed launcher is report transaction `ZTOAD` for program `ZTOAD`; use `#Shell-startGUI?sap-ui2-tcode=ZTOAD` or standalone `~transaction=ZTOAD` for its A4H smoke test.
## 4. Local-first TDD flow with a stable `master`
diff --git a/docs/plans/base-bug-006.md b/docs/plans/base-bug-006.md
index 8a37108..c8c67ae 100644
--- a/docs/plans/base-bug-006.md
+++ b/docs/plans/base-bug-006.md
@@ -45,8 +45,10 @@ The plan is intentionally structural:
## Evidence log
- Red baseline: `npm test` on 2026-08-06 passed configured abaplint with 0 issues, then failed in `scripts/repository-contract.mjs` with `Missing native-abapGit transaction object: src/ztoad.tran.xml`.
-- Local green: pending.
-- A4H ADT/live/native-abapGit: pending.
-- NPL ARC-1/ADT-only: pending.
+- Local green: native `src/ztoad.tran.xml` turns the repository contract green; `npm ci` reports 0 vulnerabilities, `npm test` reports 0 configured abaplint issues, and `npm run lint:quality` remains at the explained 1,878-finding/58-rule candidate baseline.
+- Native abapGit: serialized and pushed only `TRAN ZTOAD`; the file records a report transaction for program `ZTOAD`, screen `1000`, English text `ZTOAD SQL query tool`, WebGUI support, and Windows-GUI support. A follow-up stage shows that file clean. Unrelated A4H program/table drift was deliberately not staged.
+- A4H ADT/live: active syntax has 0 errors and the same 4 known warnings; 19/19 ABAP Unit tests pass; `ABAP_CLOUD_READINESS` remains 768 findings; `S4HANA_READINESS_2023` returned no rows but remains non-authoritative because prerequisites are unavailable. Standalone WebGUI and FLP intent launches both reach the ZTOAD editor. The ST22 list is unchanged. Missing `STATUS010` remains the independent `BASE-BUG-007` blocker.
+- A4H repository state: explicit program activation succeeded and active/inactive main-source hashes are identical. ARC-1 still lists program parts/screens/texts as inactive, so the process audit must address part-level activation evidence; no unrelated program metadata is included in this fix.
+- NPL ARC-1/ADT-only: connection and repository search succeed, but no ZTOAD objects exist. `PROG ZTOAD` and `TABL ZTOAD` return not found, exact search returns no objects, and the transaction reader returns only an empty placeholder. The structural install/activation gate is blocked because ADT cannot create the missing table or native-round-trip `TRAN`; no forbidden UI fallback was used.
- First PR CI: pending.
- Post-green process audit and final CI: pending.
diff --git a/docs/research/2026-08-06-base-bug-006-transaction.md b/docs/research/2026-08-06-base-bug-006-transaction.md
index a95d5ef..e5b53b4 100644
--- a/docs/research/2026-08-06-base-bug-006-transaction.md
+++ b/docs/research/2026-08-06-base-bug-006-transaction.md
@@ -4,7 +4,7 @@ _Date: 2026-08-06 · finding: `BASE-BUG-006` · issue: [#2](https://github.com/m
## Problem and red baseline
-The repository has no `src/ztoad.tran.xml`. A4H's ADT transaction read for `ZTOAD` currently returns empty description, program, and package fields. The stable direct URLs therefore have no repository-managed transaction to resolve:
+The red repository baseline had no `src/ztoad.tran.xml`. A4H's ADT transaction read for absent `ZTOAD` returned empty description, program, and package fields. The stable direct URLs therefore had no repository-managed transaction to resolve:
- FLP: `#Shell-startGUI?sap-ui2-tcode=ZTOAD`
- standalone WebGUI: `~transaction=ZTOAD`
@@ -51,12 +51,20 @@ abapGit intentionally serializes only active, consistent object state and exclud
- focused repository test is red before serialization and green afterward;
- `npm ci`, configured abaplint, and the full diagnostic abaplint profile are reviewed;
-- A4H ADT read reports transaction `ZTOAD` mapped to program `ZTOAD` in package `ZTOAD`;
+- native serialization reports transaction `ZTOAD` mapped to program `ZTOAD`; the current ARC-1 `TRAN` reader is not authoritative for report-transaction program metadata and returns an empty program after creation;
- native abapGit reports the transaction clean after the push/round trip;
- direct FLP and standalone WebGUI URLs reach ZTOAD without an unknown-transaction error;
- A4H active source, syntax, all ABAP Unit tests, selected ATC variants, and ST22 delta are checked;
- NPL ARC-1/ADT reads and available lifecycle gates are recorded without browser, FLP, WebGUI, or SAP GUI automation.
+## Implemented result
+
+Native abapGit serialized `src/ztoad.tran.xml` with serializer `LCL_OBJECT_TRAN`. Its `TSTC` record identifies `ZTOAD`, program `ZTOAD`, selection screen `1000`, and the report-transaction flag. `TSTCC` enables WebGUI and Windows GUI; `TSTCT` contains the English short text `ZTOAD SQL query tool`. Only this transaction object was staged. Existing A4H drift in program screens, program metadata, table metadata, and package metadata was left out of the commit.
+
+Both direct A4H launch forms reached the ZTOAD editor without an unknown-transaction error. A pre/post ST22 comparison found no new dump. The screen still reports missing GUI status `STATUS010`, which confirms that transaction resolution is fixed while `BASE-BUG-007` remains independently reproducible.
+
+On NPL, exact ADT repository search returns no ZTOAD objects; report and table reads return not found. The ARC-1 transaction reader returns an all-empty placeholder for an absent transaction, so it cannot be treated as installation evidence. Because the real table and report are absent and the ADT-only boundary has no native `TRAN` round trip, exact SAP_BASIS 750 structural installation remains blocked.
+
## Sources
- [SAP ABAP Keyword Documentation: report transaction](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/ABENREPORT_TRANSACTION_GLOSRY.html)
diff --git a/docs/test-strategy.md b/docs/test-strategy.md
index f4e0d56..d79d32e 100644
--- a/docs/test-strategy.md
+++ b/docs/test-strategy.md
@@ -25,6 +25,7 @@ For every bug or feature:
| SAP syntax + activation | Authoritative compiler and repository consistency | Both SAP targets | Every `src/` change |
| ATC | Security, performance, released API, and migration checks | Both SAP targets | Every `src/` change |
| Native-abapGit check | Complete object serialization and remote/local consistency | Both SAP targets | Every structural/deployment change |
+| Repository contract | Required cross-object launcher semantics not inferred by abaplint | Local and GitHub Actions | Every change |
| Integration test | DB/auth/executor behavior against disposable objects | Dedicated test client only | Parser/execution/security changes |
| WebGUI/FLP smoke | Startup, controls, basic read-only query, navigation | A4H only | UI/startup changes and release candidates |
| ST22/log check | Detect uncaught regressions even if the browser returns to SAP Easy Access | A4H | Every live browser smoke test |
@@ -82,7 +83,7 @@ Run this sequence after deployment:
If FLP cannot open WebGUI because the automation browser blocks a popup, record that environmental failure and use the standalone HTTPS WebGUI URL as a secondary diagnostic path. Before interpreting a runtime failure, verify that the installed report contains the serialized dynpros and GUI statuses required by the test. Classify missing installation metadata separately from a product-code regression, but keep the overall smoke gate blocked until both are green.
-For `BASE-RUN-001`, editor startup/render/input and the ST22 delta are green on A4H. Query dispatch remains blocked because installed GUI status `STATUS010` is missing (`BASE-BUG-007`), despite being present in repository XML.
+For `BASE-RUN-001`, editor startup/render/input and the ST22 delta are green on A4H. `BASE-BUG-006` adds the serialized report transaction and proves both direct launch paths reach that editor. Query dispatch remains blocked because installed GUI status `STATUS010` is missing (`BASE-BUG-007`), despite being present in repository XML.
For GUI-control changes, a green policy Unit test proves only the selection decision. The chosen control remains a spike until a fresh live session renders it, the intended interaction works, and ST22 stays unchanged. If a spike merely moves the dump to another constructor or event path, reject it and update the root-cause model before implementation continues.
diff --git a/system-info.md b/system-info.md
index 346a909..d4cd1eb 100644
--- a/system-info.md
+++ b/system-info.md
@@ -31,10 +31,10 @@ _Updated: 2026-08-06_ · _Source: live ARC-1 discovery on A4H and NPL, native ab
|---|---|---|---|
| HANA | Yes | database | Database-specific paths can be tested, but tests must remain safe and sanitized |
| RAP / CDS | Yes | ADT | Not used by the current classic report |
-| abapGit | Yes | native, online | `ZABAPGIT` 1.133.0; ZTOAD repository key `000000000017`, package `ZTOAD`, branch `master` |
+| abapGit | Yes | native, online | `ZABAPGIT` 1.133.0; ZTOAD repository key `000000000017`, package `ZTOAD`, temporarily coordinated on branch `codex/fix-base-bug-006` for the structural-object round trip |
| gCTS | Endpoint available | no ZTOAD repository | Native abapGit remains the selected round-trip mechanism |
| Transports | Yes | CTS | Transportable package `ZTOAD`; active request `A4HK906379`, target `DEV`, layer `ZDEV` |
-| FLP / WebGUI | Yes | HTTPS | WebGUI starts, but ZTOAD currently dumps while constructing `CL_GUI_ABAPEDIT`; see `BASE-RUN-001` |
+| FLP / WebGUI | Yes | HTTPS | Serialized transaction `ZTOAD` resolves through both direct paths and reaches the editor; query dispatch is still blocked by missing `STATUS010` |
| UI5 repository | Yes | ADT | Not required for ZTOAD |
| AMDP debugging | No endpoint | — | Not required for ZTOAD |
| Text search | No | ICF disabled | Use object search/source reads instead |
@@ -64,15 +64,16 @@ The first request created during setup, `A4HK906377`, is an empty local request
| Check | Result on A4H |
|---|---|
-| Git branch / remote commit imported | `master` / `cae4dea2062b` |
+| Candidate branch / transaction commit | `codex/fix-base-bug-006` / `8fb3131` |
| Package / transport | `ZTOAD` / `A4HK906379` |
-| Repository objects | PROG `ZTOAD`, TABL `ZTOAD`, SUSO `ZTOAD_AUTH` |
-| Active/inactive source | Identical; no inactive divergence |
+| Repository objects | PROG `ZTOAD`, TABL `ZTOAD`, SUSO `ZTOAD_AUTH`, TRAN `ZTOAD` |
+| Active/inactive state | Main-source hashes are identical; ARC-1 still lists program parts/screens/texts as inactive, tracked as installation drift for the process audit/`BASE-BUG-007` |
| SAP syntax | 0 errors; 4 warnings |
| ABAP Unit | 19 passed, 0 failed |
| ATC `S4HANA_READINESS_2023` | 0 rows returned; non-authoritative because known prerequisites are unavailable |
| ATC `ABAP_CLOUD_READINESS` | 768 findings (463 P1, 305 P2); classic Dynpro/GUI design is not ABAP Cloud compatible |
| WebGUI smoke | Fresh final launch renders the plain text editor and accepts `SELECT SINGLE mandt FROM t000`; no new ST22 dump |
+| Transaction launch | Standalone WebGUI and FLP `Shell-startGUI` intent both reach ZTOAD; pre/post launch ST22 lists are identical |
| Remaining UI prerequisite | A4H installation lacks GUI status `STATUS010`, so query dispatch is blocked by `BASE-BUG-007` |
## Coding Guidance
@@ -94,7 +95,7 @@ The first request created during setup, `A4HK906377`, is an empty local request
| Purpose | ADT-only minimum-release activation, syntax, ABAP Unit, and ATC gate |
| ARC-1 | Separate `arc-1-750` profile, pinned to ARC-1 1.0.2; write/activate/syntax/Unit/cleanup lifecycle proven |
| UI boundary | No FLP, WebGUI, SAP GUI, or browser automation; A4H owns UI smoke |
-| ZTOAD state | Program and transparent table are absent |
+| ZTOAD state | Exact ADT search finds no objects; program and transparent table are absent; the transaction reader returns an empty placeholder rather than reliable not-found evidence |
| Blocking prerequisite | SAP_BASIS 750 exposes no ADT transparent-table create endpoint, so table `ZTOAD` cannot be safely provisioned through ARC-1 |
| Completion status | Connection usable; exact ZTOAD activation/syntax/Unit/ATC blocked until the real table exists |
From 7f36b6454d7b9f039f40ac118f48c5d2fffcda0e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9Emarianfoo=E2=80=9C?=
<13335743+marianfoo@users.noreply.github.com>
Date: Thu, 6 Aug 2026 13:32:38 +0200
Subject: [PATCH 4/5] ci: strengthen structural object workflow
---
.github/pull_request_template.md | 2 ++
.github/workflows/quality.yml | 4 ++--
AGENTS.md | 4 +++-
docs/development.md | 11 ++++++-----
docs/plans/{ => finished}/base-bug-006.md | 5 +++--
docs/test-strategy.md | 6 +++---
6 files changed, 19 insertions(+), 13 deletions(-)
rename docs/plans/{ => finished}/base-bug-006.md (89%)
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 5ad58da..96487aa 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -10,8 +10,10 @@
- [ ] `npm ci` and `npm test` pass locally.
- [ ] Serialized files were produced or verified with native abapGit; XML was not hand-authored without a system round trip.
+- [ ] Native abapGit staging contained only intended objects; unrelated system/Git drift was documented and left unselected.
- [ ] ABAP 7.50: pull, activation, syntax check, ABAP Unit, and ATC pass, or this is not applicable and is explained below.
- [ ] S/4HANA 2023: pull, activation, syntax check, ABAP Unit, and ATC pass, or this is not applicable and is explained below.
+- [ ] Activation evidence covers affected child parts (screens, GUI statuses, text elements, and includes), not only main-source equality.
- [ ] A safe manual ZTOAD smoke test passes on both systems, or the omitted system/check is explained below.
- [ ] ST22 was checked before/after live smoke; known and new dumps are distinguished.
- [ ] ATC prerequisite/check errors were reviewed; an incomplete run is not reported as zero findings.
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index ca66353..fba168a 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -15,7 +15,7 @@ concurrency:
jobs:
abaplint:
- name: abaplint (ABAP 7.50)
+ name: Repository quality (ABAP 7.50)
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
@@ -31,5 +31,5 @@ jobs:
- name: Install pinned dependencies
run: npm ci
- - name: Run local ABAP checks
+ - name: Run ABAP and repository-contract checks
run: npm test
diff --git a/AGENTS.md b/AGENTS.md
index 967eb7e..4e8d9cc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,13 +27,15 @@ For changes that affect `src/` or live behavior:
4. 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. Review the plan before production changes.
5. 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.
6. Run `npm ci`, `npm test`, `git diff --check`, a complete diff review, and the relevant security/authorization review. Deploy the exact candidate to each available SAP target without pretending that the shared abapGit `master` link represents an unmerged branch.
-7. 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=true` request is not activation evidence: call activation explicitly, then require active/inactive object-state equality. Run a fresh-session safe browser smoke and ST22 delta on A4H only. A failed/unavailable gate is never a pass.
+7. 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=true` request 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. A failed/unavailable gate is never a pass.
8. 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.
9. 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.
10. Merge only after the maintainer accepts any recorded live-system limitations. Pull the resulting `master`, 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 `master`. 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.
+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.
+
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.
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.
diff --git a/docs/development.md b/docs/development.md
index 3cb5880..9887481 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -70,7 +70,7 @@ Do not manually install only the report source. That omits the dynpros, table, a
4. Write and review a plan under `docs/plans/` covering implementation, ABAP 7.50, Clean ABAP/Clean Core, local/live tests, rollback, browser smoke, and ST22.
5. Edit source locally and make the smallest production change that turns the test green. For a frontend or other environment-dependent assumption, keep the candidate classified as a spike until live integration evidence accepts it. Keep serializer XML unchanged for a source-only fix.
6. Run `npm ci`, `npm test`, `git diff --check`, and the final local/security review.
-7. Deploy the exact candidate source to SAP_BASIS 750 first through ARC-1/ADT when its real dependencies exist; record any missing ADT prerequisite as blocked. Keep the A4H native-abapGit link on `master` and record an unmerged candidate as a direct deployment. Follow every write with an explicit activation call and active/inactive object-state comparison; a write response or activation option alone is not proof that the active version changed.
+7. Deploy the exact candidate source to SAP_BASIS 750 first through ARC-1/ADT when its real dependencies exist; record any missing ADT prerequisite as blocked. Keep the A4H native-abapGit link on `master` and record an unmerged candidate as a direct deployment. Follow every write with an explicit activation call, active/inactive main-object comparison, and an inactive-child-part query for affected composite objects; a write response, activation option, or equal main-source hash alone does not prove that screens, statuses, texts, and includes are active.
8. On NPL, activate only the intended object and run active syntax, all ABAP Unit tests, and complete ATC variants through ARC-1. On A4H/SAP_BASIS 758, repeat those checks and additionally start a fresh browser session for safe smoke and ST22 delta. Verify required dynpros/GUI statuses before attributing an end-to-end failure to the source candidate.
9. If a correction must be made in SAP, export it through native abapGit or reproduce it locally, then review every serialized/source difference. Never leave an unexported system-only fix.
10. Perform a final review, update evidence, commit/push the short-lived branch, open the PR, and wait for CI. After the first green run, audit the process/CI, update guidance in the same PR, move the plan to `docs/plans/finished/`, push, and wait again.
@@ -89,10 +89,11 @@ For these changes:
1. Create/change the object on the ABAP 7.50 development system when the object type exists there.
2. Activate and run the relevant checks.
-3. Stage only the affected object in native abapGit and push it to the pull-request branch after its relevant checks are green.
-4. Pull locally and inspect every generated file.
-5. Run `npm test`.
-6. Deploy the same pull-request candidate into 2023 and validate deserialization/activation.
+3. Refresh native abapGit and review the complete diff before staging. If unrelated system/Git drift is present, record it and never use **Add All**.
+4. Select only the affected object, review the staged filenames, and push it to the pull-request branch after its relevant checks are green.
+5. Refresh again and require the intended object to be clean; unrelated unselected drift may remain only when it is explicitly documented.
+6. Pull locally, inspect every generated file, and run `npm test`.
+7. Deploy the same pull-request candidate into 2023 and validate deserialization, explicit activation, main-object state, and all affected inactive child parts.
If an object can only be created correctly on 2023, export it there first, then prove that the serialized form can be pulled and activated on 7.50 before accepting it. Do not fix serializer XML by guesswork.
diff --git a/docs/plans/base-bug-006.md b/docs/plans/finished/base-bug-006.md
similarity index 89%
rename from docs/plans/base-bug-006.md
rename to docs/plans/finished/base-bug-006.md
index c8c67ae..3e7d806 100644
--- a/docs/plans/base-bug-006.md
+++ b/docs/plans/finished/base-bug-006.md
@@ -50,5 +50,6 @@ The plan is intentionally structural:
- A4H ADT/live: active syntax has 0 errors and the same 4 known warnings; 19/19 ABAP Unit tests pass; `ABAP_CLOUD_READINESS` remains 768 findings; `S4HANA_READINESS_2023` returned no rows but remains non-authoritative because prerequisites are unavailable. Standalone WebGUI and FLP intent launches both reach the ZTOAD editor. The ST22 list is unchanged. Missing `STATUS010` remains the independent `BASE-BUG-007` blocker.
- A4H repository state: explicit program activation succeeded and active/inactive main-source hashes are identical. ARC-1 still lists program parts/screens/texts as inactive, so the process audit must address part-level activation evidence; no unrelated program metadata is included in this fix.
- NPL ARC-1/ADT-only: connection and repository search succeed, but no ZTOAD objects exist. `PROG ZTOAD` and `TABL ZTOAD` return not found, exact search returns no objects, and the transaction reader returns only an empty placeholder. The structural install/activation gate is blocked because ADT cannot create the missing table or native-round-trip `TRAN`; no forbidden UI fallback was used.
-- First PR CI: pending.
-- Post-green process audit and final CI: pending.
+- First PR CI: PR [#17](https://github.com/marianfoo/ztoad/pull/17), head `fe46f14`, passed GitHub Quality run `31097535470` plus both external abaplint checks; GitHub reported the PR merge state clean.
+- Post-green process audit: CI correctly ran the new repository contract through `npm test`, but its check label exposed only abaplint. The workflow now names the combined repository-quality gate. Live validation also showed that equal main-source hashes can coexist with inactive program parts, and native abapGit exposed unrelated drift during structural staging. Permanent guidance and the PR checklist now require child-part activation review and selective staging with **Add All** prohibited when unrelated drift exists.
+- Final CI after process-audit changes: pending.
diff --git a/docs/test-strategy.md b/docs/test-strategy.md
index d79d32e..2906eb6 100644
--- a/docs/test-strategy.md
+++ b/docs/test-strategy.md
@@ -70,10 +70,10 @@ Do not use ports 50000 or 50001. Credentials stay in the ignored `.env` file and
Run this sequence after deployment:
-1. Confirm native abapGit points at `master` and its check is clean.
-2. Confirm no unrelated inactive divergence and record the exact candidate commit/source hash being tested.
+1. Confirm native abapGit points at the expected coordinated branch, refresh it, and review the complete system/Git diff. For normal source work this is `master`; a structural-object feature branch must be explicit in the evidence.
+2. Confirm no unrelated inactive divergence and record the exact candidate commit/source hash being tested. If unrelated drift exists, leave it unselected and list it; never use **Add All**.
3. Deploy and explicitly activate only the intended changed objects. Do not describe an unmerged directly deployed source as a native-abapGit `master` pull, and do not rely on a write request's activation option.
-4. Confirm active and inactive source are identical, then run active SAP syntax.
+4. Confirm active and inactive main source are identical, query inactive child parts for changed composite objects, then run active SAP syntax. Screens, GUI statuses, text elements, and includes must be checked separately; main-source equality does not clear an inactive child part.
5. Run all ABAP Unit tests; require zero failures.
6. Run the recorded ATC variants and inspect prerequisite/check errors. A result with missing prerequisites is incomplete even when no finding rows are displayed.
7. Record the latest ST22 dump timestamp before UI execution.
From b395aafbc8a34f1fe66584138f760b0f817280b0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9Emarianfoo=E2=80=9C?=
<13335743+marianfoo@users.noreply.github.com>
Date: Thu, 6 Aug 2026 13:34:55 +0200
Subject: [PATCH 5/5] docs: close BASE-BUG-006 plan
---
docs/plans/finished/base-bug-006.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/plans/finished/base-bug-006.md b/docs/plans/finished/base-bug-006.md
index 3e7d806..988f0db 100644
--- a/docs/plans/finished/base-bug-006.md
+++ b/docs/plans/finished/base-bug-006.md
@@ -52,4 +52,4 @@ The plan is intentionally structural:
- NPL ARC-1/ADT-only: connection and repository search succeed, but no ZTOAD objects exist. `PROG ZTOAD` and `TABL ZTOAD` return not found, exact search returns no objects, and the transaction reader returns only an empty placeholder. The structural install/activation gate is blocked because ADT cannot create the missing table or native-round-trip `TRAN`; no forbidden UI fallback was used.
- First PR CI: PR [#17](https://github.com/marianfoo/ztoad/pull/17), head `fe46f14`, passed GitHub Quality run `31097535470` plus both external abaplint checks; GitHub reported the PR merge state clean.
- Post-green process audit: CI correctly ran the new repository contract through `npm test`, but its check label exposed only abaplint. The workflow now names the combined repository-quality gate. Live validation also showed that equal main-source hashes can coexist with inactive program parts, and native abapGit exposed unrelated drift during structural staging. Permanent guidance and the PR checklist now require child-part activation review and selective staging with **Add All** prohibited when unrelated drift exists.
-- Final CI after process-audit changes: pending.
+- Final CI after process-audit changes: head `7f36b64` passed GitHub Quality run `31097691676` plus both external abaplint checks; GitHub reported the PR merge state clean.