pi-apexlang 0.1.0

package/skills/apexlang/references/ops/reusable-prompts/server-side-conditions.md

@@ -0,0 +1,80 @@
+# Oracle APEX Server-Side Conditions — Reusable Prompts
+
+Purpose
+- Provide reusable prompt scaffolds to test and generate `serverSideCondition {}` blocks for any APEXlang DSL component that supports server-side conditions.
+- Applies across pages, regions, items, buttons, dynamic actions, and processes where the DSL permits a server-side condition block.
+
+Rule source
+- `references/policies/memory-bank/20-data/apex.logic.md`
+- Use only supported condition `type` values and required attributes.
+
+## 1. Request/Value-Based Conditions
+- Use when toggling behavior by APEX request value or feature flag token.
+- Prompt scaffold:
+  - "Apply request-value condition `<REQUEST>` to [component list]; fail if catalog attributes are missing."
+
+Example draft summary:
+```
+Summary: Apply `ssc.feature.flagEnabled("SALES")` to P10_SAVE button and P20_PROCESS_ORDER process
+
+- Intent: Show Save button only when SALES flag enabled.
+- Condition: `:REQUEST = 'FEATURE_SALES_ENABLED'`
+- Note: Request value derives from feature toggle mapping.
+```
+
+## 2. Item Equality / Inequality Conditions
+- Use when showing/hiding components based on item value comparisons.
+- Prompt scaffold:
+  - "Guard [component] when `:Pnn_ITEM` equals `<VALUE>`; ensure NVL handling if nulls are allowed."
+
+Example:
+```
+Summary: Guard Delete button when status is not active
+- Condition: `NVL(:P50_STATUS, 'INACTIVE') != 'ACTIVE'`
+```
+
+## 3. List Membership Conditions
+- Use when availability depends on item-in-list rules.
+- Prompt scaffold:
+  - "Render [component] only when `:Pnn_STATUS` in `<VAL1:VAL2:VAL3>` list."
+
+## 4. Numeric Guard Conditions
+- Use when numeric fields must be present and within thresholds.
+- Prompt scaffold:
+  - "Allow processing when `:Pnn_AMOUNT` > `<threshold>`; block null/zero cases."
+
+## 5. Date Window Conditions
+- Use when start/end dates must be present and ordered.
+- Prompt scaffold:
+  - "Render region only when both dates are present and start <= end."
+
+## 6. EXISTS Ownership Checks
+- Use when visibility depends on data ownership or row existence.
+- Prompt scaffold:
+  - "Allow action when current user owns the referenced record via EXISTS query; require bind variables."
+
+## 7. `plsqlExpression` Conditions (Guardrails)
+- Use when logic exceeds catalog shortcuts.
+- Mandatory guardrails:
+  - bind syntax for items/contexts
+  - explicit null handling
+  - no DML
+  - no dynamic SQL
+  - datatype-safe comparisons
+
+Prompt scaffold:
+- "Draft a `plsqlExpression` with one-line intent + expression; enforce apex.logic guardrails and block on violations."
+
+Guardrail fail example:
+```
+Summary: Proposed predicate rejected (missing bind and null safety)
+- Proposed: `P50_STATUS != 'ACTIVE'`
+- Violations:
+  - Missing colon prefix on item reference.
+  - Null-unsafe inequality; requires `NVL(:P50_STATUS, 'INACTIVE') != 'ACTIVE'`.
+- Action: Mark as blocked and request correction.
+```
+
+Usage notes
+- Pair with SSC batch workflows for summary-first review before applying direct app-file changes.
+- Never invent condition types or attributes outside `apex.logic.md`.

package/skills/apexlang/references/ops/runtime-gates/01-direct-sqlcl-import.md

@@ -0,0 +1,53 @@
+# Agent: Direct SQLcl Import
+
+Purpose
+- Provide the import continuation after the live APEXlang check succeeds for APEXlang artifact workflows after the user explicitly chose import in the post-check GUI flow.
+- Import validated APEXlang artifacts through direct SQLcl commands.
+- Preserve the same-session guarantee between validate and import.
+
+When to invoke
+- Any APEXlang artifact workflow that reaches import-ready state after a post-check GUI choice resolves to import.
+- Standalone import of previously generated artifacts when the live APEXlang check is also available for the same run.
+
+Preconditions
+- `db_connection_name` is resolved.
+- The corresponding APEX workspace name is resolved.
+- The post-check GUI import choice for the run resolved to import.
+- `resolved_app_path` is absolute and points to the transient temp app copy selected for import.
+- Runtime capability status confirms validate/import support for the active run.
+- The canonical live numeric application id for the existing app is resolved and preserved as session authority.
+- If staged deployment metadata originally pointed at a different app id, `resolved_app_path` has already been reconciled to the canonical application id.
+- `application_id` is known for optional post-import export.
+- The same `resolved_app_path` has already passed SQLcl `apex validate` in the active authenticated SQLcl user session.
+
+Canonical flow
+1. Open one authenticated SQLcl user session with `db_connection_name`, trying `sql -name <db_connection_name>` first, then legacy `sql <db_connection_name>`, and falling back to `sql /nolog` plus `connect <db_connection_name>` inside that same session when needed.
+2. Prefer the resolved build-root runtime via `apex sql`; otherwise use the PATH SQLcl session.
+3. Run `apex validate -input <resolved_app_path>` in that session if a valid same-session runtime status is not already active.
+4. If the active runtime session reports multiple-workspace ambiguity, resolve the workspace id automatically for the active `db_connection_name` and restart the same real-SQLcl sequence immediately with an explicit run-scoped `-workspaceid`.
+5. Run `apex import -input <resolved_app_path>` in that same session.
+6. If import output reports an application id different from the preserved canonical target, stop the run, record the mismatch, and treat the reported target as an accidental duplicate or wrong target.
+7. Optionally run `apex export -applicationid <application_id> -exptype APEXLANG -split -dir <absolute_export_dir>` only when the selected runtime path confirms export support.
+8. If a build-root runtime attempt fails before real `apex validate` / `apex import` output because of sandbox-only filesystem/setup errors such as `EPERM`, `ENOENT`, or build-root `workdir/*` write failures, classify the result as an environment blocker, do not consume live validate-attempt budget, and continue with the real live build-root roundtrip in an execution context that can write the required build-root work files.
+
+Hard rule
+- Validate and import must happen in the same authenticated SQLcl user session.
+- If validate and import do not happen in the same session, STOP and re-run validation before import.
+- Use direct SQLcl commands for the live path; do not substitute helper Python wrappers for validate/import/export.
+
+Outputs
+- SQLcl command transcript and compact runtime report recorded with the run.
+
+Required recorded facts
+- validated app path
+- imported app path
+- `db_connection_name`
+- recorded SQLcl capability status
+- whether validate and import used the same authenticated SQLcl session
+
+Failure handling
+- Validation failure: stop, do not import.
+- Sandbox-only build-root filesystem/setup blocker before real validate/import output: stop the sandbox attempt, do not route to the debugging/fix loop, and continue in a real live build-root execution context.
+- Import failure: route to `references/domains/README.md`, apply the smallest concrete fix, rerun local validators, and restart from validate in a fresh real SQLcl session.
+- Session mismatch: stop and require re-validation.
+- Path mismatch: stop before import.

package/skills/apexlang/references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md

@@ -0,0 +1,77 @@
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+# Agent: Direct SQLcl Validate Gate
+
+Purpose
+- Provide the canonical live-runtime gate for APEXlang artifact workflows.
+- Enforce direct SQLcl `apex validate` before any optional import.
+- Make live APEX validation from the selected target build the validation source of truth.
+- Block completion until the live APEXlang check is proven; import eligibility is proven only after an explicit post-check import choice.
+
+Scope
+- Applies to all APEXlang-producing skills that generate or modify application artifacts.
+- Excluded: requests that do not enter APEXlang artifact-generation workflows.
+
+Preconditions
+- Target artifacts were produced by the internal generate -> review -> fix loop in the transient temp workspace.
+- `resolved_app_path` is absolute and points to the application folder being changed.
+- `db_connection_name` is resolved for this run.
+- The corresponding APEX workspace name is resolved for this run.
+- Runtime capability status is resolved for this run.
+
+Runtime contract
+- Use direct SQLcl commands only.
+- Default to `validate-only` for every APEX artifact workflow through `node tools/apexctl.mjs runtime validate --app-path <absolute_app_path> --db-connection-name <db_connection_name> --apex-root <resolved_build_root> [--compiler-oracle-home <compiler_metadata_home>]`.
+- `--apex-root` selects only the APEX/SQLcl runtime used for live validation. Use `--compiler-oracle-home` only when explicitly overriding compiler-truth metadata discovery.
+- The validate command must emit `validation-report.json`, `validation-transcript.log`, `problems.json`, and `component-contracts/<build>.json`.
+- Require live APEX validation evidence for generated or revised `.apx` artifacts. Missing required runtime inputs or missing live runtime evidence records `LIVE_RUNTIME_VALIDATION_REQUIRED_001` and blocks completion.
+- Treat compiler-truth, local lint, and VS Code Problems snapshots as diagnostics after live validation passes.
+- After the live APEXlang check passes, offer GUI/clickable choices: `Check APEXlang code` (recommended) or `Check and import APEXlang code`; include a short purpose summary and, if GUI choices are unavailable, stop after checking the code and report import as a follow-up.
+- Probe both supported runtime paths and select the live runtime path before validate/import:
+  - resolved build-root runtime via `apex sql`
+  - PATH SQLcl runtime via `sql -name <db_connection_name>`, then legacy `sql <db_connection_name>`, then `sql /nolog` plus `connect <db_connection_name>`
+- `apex validate -input <resolved_app_path>` is mandatory for every live runtime run.
+- `validate-and-import` runs for existing apps must resolve and preserve a canonical live numeric application id before any import-authorized continuation.
+- If staged deployment metadata does not match that canonical application id, reconcile `resolved_app_path` to the canonical target before import.
+- If the post-check GUI choice resolves to import, `apex validate -input <resolved_app_path>` and `apex import -input <resolved_app_path>` must run in the same authenticated SQLcl user session.
+- The session must use the same `db_connection_name`, workspace context, and effective SQLcl user.
+- If the session changes between validate and import, STOP and re-run validation before import.
+- Do not replace the live validate/import path with Python wrapper scripts when direct SQLcl commands are available.
+- If SQLcl explicitly reports multiple-workspace ambiguity, resolve the workspace id automatically for the active `db_connection_name` and restart the same real-SQLcl sequence with a run-scoped explicit `-workspaceid`.
+
+Execution
+1. Run `node tools/apexctl.mjs runtime validate --app-path <resolved_app_path> --db-connection-name <db_connection_name> --apex-root <resolved_build_root>`, adding `--vscode-problems-path <problems_snapshot_path>` only when a VS Code Problems snapshot already exists and `--compiler-oracle-home <compiler_metadata_home>` only for an explicit compiler metadata override.
+2. Persist the emitted compact validation artifacts under the run artifact directory.
+3. Review `problems.json`, sorted by file, line, severity, compiler type, and message.
+4. Patch only reported problems; local validators are syntax hygiene unless produced from the same target build metadata.
+5. Attempt the live APEXlang check at most 3 times in one run.
+6. For each failed attempt with real SQLcl/compiler output, route to `references/domains/README.md`, apply the smallest concrete fix, rerun syntax hygiene checks as needed, and rerun `runtime validate`.
+7. If SQLcl reports multiple-workspace ambiguity, resolve the workspace id automatically for the active `db_connection_name` and rerun `runtime validate` with the run-scoped explicit `-workspaceid`.
+8. After live validate passes, run runtime UI verification for changed pages before any import continuation when the caller requested it. Prefer Chrome DevTools MCP when provided; otherwise use the runtime verifier's inferred page URLs plus HTTP/HTML artifacts.
+9. Treat critical runtime verification findings such as login redirects, HTTP failures, APEX/ORA error text, or missing live state needed for the active fix as blocking. Route them through debugging before any import attempt.
+10. If a build-root runtime attempt fails before real `apex validate` / `apex import` output because of sandbox-only filesystem/setup errors such as `EPERM`, `ENOENT`, or build-root `workdir/*` write failures, classify the result as an environment blocker, do not consume the 3-attempt validate budget, do not route to the debugging/fix loop, and continue with the real live build-root roundtrip in an execution context that can write the required build-root work files.
+11. Record `resolved_app_path` as the canonical validated path after live validate passes.
+12. Mark import eligibility only when the validate-only gate succeeds in that session and the post-check GUI choice resolves to import.
+
+Outputs
+- direct SQLcl validate success for the resolved app path
+- `validation-report.json`
+- `validation-transcript.log`
+- `problems.json`
+- `component-contracts/<build>.json`
+- same-session eligibility for direct SQLcl import when the post-check GUI choice resolves to import
+- recorded SQLcl capability status for the run
+- recorded command outcome in the run report and transcript
+
+Failure handling
+- Missing required runtime inputs or live runtime evidence: stop with `LIVE_RUNTIME_VALIDATION_REQUIRED_001`.
+- Local validator, compiler-truth, or VS Code Problems findings: record as diagnostics unless live validation cannot run.
+- Sandbox-only build-root filesystem/setup blocker before real validate/import output: stop the sandbox attempt, keep the run out of the debugging/fix loop, and continue in a real live build-root execution context without consuming validate-attempt budget.
+- Validation failure with a real SQLcl/compiler outcome: route to debugging, then retry from a fresh real SQLcl session until the third failed validate attempt.
+- Third failed validate attempt: stop and surface actionable findings plus the owning layer.
+- Path mismatch: stop before import.
+- Session mismatch: stop and require re-validation.
+
+Notes
+- This gate standardizes completion checks; it does not replace domain routing.
+- Completion remains blocked until runtime status proves eligibility.

package/skills/apexlang/references/ops/runtime-gates.md

@@ -0,0 +1,104 @@
+---
+name: apexlang-runtime-gates
+description: Canonical same-session SQLcl runtime gates for APEXlang validate/import/export workflows.
+---
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+
+# Reference Package — APEXlang Runtime Gates
+
+## Purpose
+- Define the canonical runtime/import contract for APEXlang workflows.
+- Standardize direct SQLcl roundtrips across all APEXlang artifact-generation skills.
+- Keep validation and import in the same SQLcl user session.
+
+## Authoritative Policies
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/governance/00-governance.md`
+- `references/policies/memory-bank/20-data/db.connection.md`
+- `references/ops/sqlcl.md`
+
+## Operational References
+- `references/ops/sqlcl-agents/00-connection-gate.md`
+- `references/ops/runtime-gates/01-direct-sqlcl-import.md`
+- `references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md`
+- `tools/apexctl.mjs`
+
+## Canonical Validation
+1. Resolve `db_connection_name` and the corresponding APEX workspace name.
+2. Run `node tools/apexctl.mjs runtime preflight --db-connection-name <db_connection_name>` and record both runtime candidates. Use `runtime doctor` when the caller wants the same preflight facts without continuing into validation/import.
+3. Prefer the resolved build-root runtime via `apex sql` when the matching local APEX build derived from `db_connection_name` is available and runtime-capable; otherwise use PATH SQLcl.
+4. Run validate-only through the single public agent command: `node tools/apexctl.mjs runtime validate --app-path <absolute_app_path> --db-connection-name <db_connection_name> --apex-root <resolved_build_root> [--compiler-oracle-home <compiler_metadata_home>] [--execution-mode auto|build-root|path] [--vscode-problems-path <path>]`.
+5. Treat the internal validate-only roundtrip as the `APEXlang source import` lane. It validates the staged source tree and is not interchangeable with any separate compiled SQL export import path.
+6. Treat preflight as a capability, live-metadata, and target-identity gate. When it successfully resolves runtime capability and live metadata, the run may continue even if the preflight stage budget was exceeded.
+7. Treat live `apex validate` as the first mandatory blocking runtime action in the happy path. For APEX/ORA runtime error text with a live DB connection, if runtime was to actually be tested, query `APEX_DEBUG_MESSAGES` through `references/domains/debugging/apex-debug-messages.md` to resolve the `PAGE_VIEW_ID` execution log before assigning ownership. Route the finding through the same debug/fix/revalidate loop before import is allowed.
+8. For an approved import continuation, run `node tools/apexctl.mjs runtime roundtrip --app-path <final_app_path> --db-connection-name <db_connection_name> --import-intent validate-and-import [--execution-mode auto|build-root|path]` and execute live import immediately after successful live validate. In user-facing responses, label this path as `Check and import APEXlang code`.
+9. Browser/runtime verification is not a pre-import gate. Run it only after `import_status = pass`, and only when the caller explicitly requests it with `--require-runtime-verification`.
+10. Treat post-import runtime verification findings as diagnostics. Record them in the transcript/report and `runtime_verification_*` fields, but do not rewrite a successful import to fail.
+11. The runtime executor runs in fixed phases with immutable handoff facts: `preflight`, `local_validate`, `target_resolve`, `live_validate`, and `import`. Each phase records duration, budget, status, failure class, and next safe action in the stage report.
+12. `local_validate` remains an advisory/helper phase. It records whether the local first-pass check ran or was skipped by roundtrip policy, but it is no longer the first mandatory blocker for the live roundtrip lane.
+13. The default roundtrip validates/imports the resolved app path in place. Use transient runtime directories only for logs, stage reports, and temporary SQL scripts. Full app-copy staging and sync-back are reserved for workflows that intentionally mutate artifacts before publish.
+14. For existing-app `validate-and-import` runs, resolve the live canonical numeric application id before import, preserve it as session authority, and reconcile staged deployment metadata to that canonical id before import-authorized runtime work continues.
+15. If the local first-pass check already passed and a sandboxed build-root attempt fails before real `apex validate` / `apex import` output because of filesystem/setup errors such as `EPERM`, `ENOENT`, or build-root `workdir/*` write failures, stop sandbox retries and continue with the real live build-root roundtrip.
+16. If the active runtime session explicitly reports multiple-workspace ambiguity, automatically resolve the workspace id for the active `db_connection_name` and restart the same roundtrip immediately with a run-scoped explicit `-workspaceid`.
+17. Optionally run `apex export -applicationid <application_id> -exptype APEXLANG -split -dir <absolute_export_dir>` only when the selected runtime path confirms export support.
+18. When export backups are produced, create the output directory lazily and write them under `APEXLANG_OUTPUT_ROOT/apex-exports/<app>/`, never under `applications/<app>/`.
+
+## Rules
+- `--apex-root` selects only the APEX/SQLcl runtime used for live validation. Use `--compiler-oracle-home` only for explicit compiler-truth metadata overrides; otherwise let compiler truth auto-discover the VS Code SQLcl/APEXlang runtime.
+- The validated temp app path is always the canonical live-runtime path for the run.
+- Every validation run must emit `validation-report.json`, `validation-transcript.log`, `problems.json`, and `component-contracts/<build>.json`; `problems.json` is the review interface for repair.
+- Validation requires live APEX validation evidence from the selected target build. Missing required runtime inputs or missing live runtime evidence blocks completion with `LIVE_RUNTIME_VALIDATION_REQUIRED_001`.
+- Compiler-truth, local lint, and VS Code Problems snapshots are diagnostics after live validation passes; missing VS Code Problems snapshots are recorded as `not_provided`, not as blockers.
+- Patch only reported problems, then rerun `runtime validate` until `live_check_status = pass`.
+- The frozen preflight facts are the canonical handoff for later phases. If a required fact is missing or contradictory, stop in preflight and do not continue.
+- Preflight is a runtime-capability and identity gate, not a browser-debug gate.
+- The runtime roundtrip assumes the connection gate already resolved `db_mode`, required `db_connection_name`, and the corresponding APEX workspace name; it is not responsible for prompting the user through the staged offline/live DB flow.
+- If the post-check GUI choice resolves to `Check and import APEXlang code`, the checked and imported temp app path must match exactly.
+- If the SQLcl session changes between validate and import, stop and re-run validation before import.
+- If the post-check GUI choice resolves to `Check and import APEXlang code`, the preserved canonical application id becomes the only accepted target identity for the rest of the session.
+- If staged deployment metadata does not match that preserved canonical application id, reconcile the staged deployment app id before import.
+- If import output reports a different application id than the preserved canonical target, block the run and record the mismatch as a duplicate or wrong-target outcome.
+- Treat the resolved build-root runtime as the preferred same-session runtime path and PATH SQLcl as the supported fallback.
+- Record SQLcl version for reporting, but do not treat version alone as proof that runtime commands are available.
+- Enable validate/import only when capability probing confirms the selected runtime path can execute the required commands for the resolved runtime action.
+- Python wrappers must not own the live SQLcl validate/import/export path.
+- The repo may keep heavy validator internals behind `node tools/apexctl.mjs`, but SQLcl command execution itself stays direct.
+- Prefer direct SQLcl or direct `apex` command help for command shape and capability checks; do not introduce helper scripts when the live task is simply validate/import/export.
+- Runtime target resolution must use structured SQL probes with explicit statement termination and machine-readable probe boundaries. SQL parse failures in target resolution are terminal and must not fall through to import retries.
+- Target-resolution timeout or failure is a terminal import blocker. Live validate success only proves the staged source can compile; it must not be used to justify direct SQLcl import, wrapper bypass, or create-new fallback.
+- Build-root resolution is part of the happy-path runtime selection flow when a matching local build is available.
+- Default `supporting_objects` is `false`. Bundled metadata is read-only guidance. Live DB metadata inspection during preflight must win when it conflicts with bundled metadata.
+- `--import-mode auto|direct` controls the import executor. `auto` may use one direct fallback only after the live APEXlang check passed and the failure was classified as wrapper/session-only.
+- Runtime reports must record the default check-only intent or explicit post-check import intent/source, treat a workspace-ambiguity response as a blocked intermediate condition, record the resolution step plus resolved `workspaceid` when one is found, and only mark import as pass after the rerun succeeds in an import-approved run.
+- Treat local repo validation as syntax hygiene for the live roundtrip lane unless it is generated from the same target build metadata. Record whether it ran, failed, or was skipped by roundtrip policy, but do not let it override live/compiler validation.
+- Treat sandbox-only build-root filesystem/setup failures before real validate/import output as environment blockers, not app defects and not live retry-budget consumption.
+- A run may attempt the live APEXlang check at most 3 times. Each failed live check attempt must route through `references/domains/README.md`, apply a concrete fix, rerun local first-pass checks, and then restart the real SQLcl session for the next attempt.
+- Do not use blind unchanged retries.
+- If no validate attempt succeeds after the third attempt, stop and surface the exact blocker.
+- Treat `references/domains/README.md` as a failure branch, not a baseline runtime dependency.
+- If local repo validators fail, stop the happy-path runtime flow and route to `references/domains/README.md`.
+- If `apex validate -input <absolute_app_path>` fails, stop before import and route to `references/domains/README.md`.
+- If optional post-import runtime verification reports a critical live-page failure, keep the successful import outcome intact, record the findings, and route follow-up debugging through `references/domains/debugging/runtime-ui-verification.md`.
+- If runtime verification reports APEX/ORA error text and a live DB connection is available, search `APEX_DEBUG_MESSAGES`, resolve the matching `PAGE_VIEW_ID`, and use the full execution log as the debugging evidence. If multiple matches exist, ask for `PAGE_VIEW_ID` / debug id or `SESSION_ID`; if the log is sparse, ask for Full trace reproduction.
+- If validate passes and `apex import -input <absolute_app_path>` fails in the same session, route to `references/domains/README.md`, then restart from validate in a fresh real SQLcl session after the fix.
+- If the runtime wrapper is bypassed with a direct SQLcl fallback, the same failure rule applies: any direct `apex validate` or `apex import` compile/import error must route through `references/domains/README.md` before artifact edits continue.
+- If validate/import both pass but the reported defect remains visible only in the running app, route to the runtime UI/UX verification branch in `references/domains/debugging/runtime-ui-verification.md`.
+- Treat packaged-build refresh notes as source-owned guidance, not as changes to the runtime contract unless the packaged metadata proves a validate/import behavior change.
+- Component-local metadata refreshes, including Interactive Grid saved-report defaults or aggregate import-path visibility changes, do not change the runtime gate flow by themselves.
+- `artifacts/` is optional output only and must not be required before a runtime workflow starts. Create logs, reports, and export directories only when the run writes them.
+- Runtime export backups are durable outputs, not generated app-root content or app-resolution inputs. Keep them under `APEXLANG_OUTPUT_ROOT/apex-exports/<app>/` so `applications/<app>/` remains a clean APEXlang source tree.
+- Ignore any existing `apex-exports` tree during app resolution, metadata discovery, bounded scans, and generation unless the user explicitly asks for read-only export inspection, migration, or recovery analysis.
+
+## Executable Failure Branch
+- The runtime roundtrip records the caught failure stage immediately in the run summary using `failure_stage`, `debugging_bucket`, `owning_layer`, `confirming_check`, and `fix_pattern`.
+- Local validator failures enter a bounded repo-local debug loop before any live SQLcl work. The loop may apply only deterministic repo-local fixes and stops after `debug_max_retry_count = 3`.
+- The first executable repo-local auto-fix removes invalid `execution.event` lines from staged dynamic-action action `execution` blocks when the local first-pass check reports `execution.event must not be emitted`.
+- Workspace-resolution failures, live validate failures, and live import failures also record the debugging route immediately even when no auto-fix is available.
+- Direct SQLcl fallback failures must be manually recorded with the same route fields in the work summary: `failure_stage`, `debugging_bucket`, `owning_layer`, `confirming_check`, and `fix_pattern`.
+- External-owner failures such as import version gates or property-model metadata failures are classified and surfaced precisely, but are not auto-patched from the runtime wrapper.
+- Sandbox-only build-root filesystem/setup blockers such as `EPERM`, `ENOENT`, or `workdir/*` creation failures remain outside the debugging/fix loop and are reported as environment blockers.
+
+## Execution Agents
+- `references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md`
+- `references/ops/runtime-gates/01-direct-sqlcl-import.md`

package/skills/apexlang/references/ops/shared-reference-index.md

@@ -0,0 +1,16 @@
+# Shared Reference Index — SQLcl
+
+## Authoritative Policies
+- `references/policies/governance/00-governance.md`
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/memory-bank/20-data/db.connection.md`
+
+## Operational References
+- `references/ops/one-message-router-contract.md`
+- `references/policies/governance/prompt-normalization.md`
+- `references/workflows/apexlang/apexlang-execution-model.md`
+- `references/ops/reusable-prompts/orchestration-master-generic.md`
+- `references/ops/reusable-prompts/server-side-conditions.md`
+- `references/ops/sqlcl-agents/00-connection-gate.md`
+- `references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md`
+- `references/ops/runtime-gates/01-direct-sqlcl-import.md`

package/skills/apexlang/references/ops/sqlcl-agents/00-connection-gate.md

@@ -0,0 +1,59 @@
+# Agent: SQLcl Connection Gate
+
+Purpose
+- Be the first live-database gate for shared workflows in this repository.
+- Resolve prerequisite metadata source first, and resolve `db_connection_name` plus the corresponding APEX workspace name only when live DB context is still required.
+- Keep SQLcl command usage direct and deterministic.
+- Be the single source of truth for global startup/load ordering.
+
+Canonical startup order
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/governance/00-governance.md`
+- `references/policies/context-overview.md`
+- `assets/rules-mapping.json`
+
+Inputs
+- `prereq_source`: `schema_doc`, `saved_connection`, `user_prompt`, or `unresolved`
+- `connection_source`: `saved_connection`, `user_prompt`, or `unresolved`
+- `selected_schema_name`: optional offline schema dictionary identifier
+- `selected_schema_doc_path`: optional selected schema dictionary path
+- `db_mode`: `online` or `offline`
+- `db_connection_name`: saved SQLcl connection alias
+- `apex_workspace_name`: corresponding APEX workspace name, recorded as `db_context.workspace.name` when session context is available
+- `environment`: optional environment label
+
+Rules
+- For DB-backed workflows, inspect `assets/workspace-intelligence.json` and scan saved SQLcl connections before any prompt about DB mode or connection knowledge.
+- If `db_mode = offline`, inspect `assets/workspace-intelligence.json`.
+- If exactly one eligible schema dictionary exists, set `prereq_source = schema_doc`, record `selected_schema_name` plus `selected_schema_doc_path`, and skip DB prompting unless later live work requires it.
+- If multiple eligible schema dictionaries exist, ask the user to choose one schema dictionary before continuing.
+- If exactly one saved SQLcl connection alias is discovered, present it as the default candidate but still require the user to specify or confirm `db_connection_name` and the corresponding APEX workspace name before live work.
+- If multiple saved SQLcl connection aliases are discovered, ask the user to choose one connection alias from the discovered list; record `connection_source = saved_connection` when one is chosen from that list.
+- Use the final natural-language clarification prompt only when live prerequisite routing still remains unresolved; record `connection_source = user_prompt` when that final prompt resolves to explicit `db_connection_name` and APEX workspace name: `Provide db_connection_name and the corresponding APEX workspace name for this workflow.`
+- If `prereq_source = saved_connection` or (`prereq_source = user_prompt` and `db_mode = online`) or `db_mode = online`, `db_connection_name` and the corresponding APEX workspace name are required.
+- Allow `prereq_source = schema_doc` and `connection_source = saved_connection` to coexist when schema docs remain the preferred evidence source and a deterministic live connection was also resolved.
+- If `prereq_source = schema_doc`, stop before live metadata validation or APEXlang roundtrips unless the workflow later escalates to live runtime work.
+- If `db_mode = offline`, stop before live metadata validation or APEXlang roundtrips.
+- Use natural-language prompting only for manual connection and workspace entry when the connection alias or APEX workspace name is still missing or ambiguous after deterministic discovery and any required selection prompt.
+- Do not generate code to discover SQLcl commands. Command knowledge is assumed.
+- Never log secrets or full connect strings. Record only the saved connection alias when needed.
+- Accept two supported runtime paths:
+  - resolved build-root runtime via `apex sql`
+  - PATH SQLcl runtime via `sql`
+- Record SQLcl version for reporting, but do not treat version alone as runtime readiness.
+- Run capability probing before live runtime work and treat build-root runtime plus PATH SQLcl runtime as candidate paths for the real enable/disable gate.
+- Prefer the resolved build-root runtime when it is available and runtime-capable; otherwise use the authenticated PATH SQLcl session that tries `sql -name <db_connection_name>` first, then legacy `sql <db_connection_name>`, and falls back to `sql /nolog` plus `connect <db_connection_name>` if needed.
+- Use local APEX build-root resolution as part of the normal runtime selection flow, not diagnostics only.
+- Do not preemptively add workspace-id overrides to runtime commands once the alias, workspace name, and session are resolved. Workspace-id overrides are exception-only and require SQLcl to explicitly report multiple-workspace ambiguity first; once that happens, resolve the workspace id automatically for the active `db_connection_name` and rerun immediately.
+
+Capability preflight
+- Shared tooling must probe SQLcl availability, version, and APEX command support before live runtime work.
+- Preflight results gate whether validate/import/export may run, but they do not replace the same-session runtime contract.
+
+Exit criteria
+- `prereq_source` is resolved and recorded for downstream use, or the workflow halts with Missing Inputs.
+- `connection_source` is resolved and recorded for downstream use when live DB context is discovered, or remains `unresolved`.
+- If `prereq_source = schema_doc`, `selected_schema_name` and `selected_schema_doc_path` are recorded for downstream use.
+- If `db_mode = online`, `db_connection_name` and the corresponding APEX workspace name are resolved and recorded for downstream use, or the workflow halts with Missing Inputs.
+- For APEX runtime work, PATH SQLcl capability status is recorded for downstream use, or the workflow halts with Missing Inputs or a blocked preflight result.
+- For APEX runtime work, the selected runtime path and its capability status are recorded for downstream use, or the workflow halts with Missing Inputs or a blocked preflight result.

package/skills/apexlang/references/ops/sqlcl.md

@@ -0,0 +1,109 @@
+---
+name: sqlcl
+description: APEXlang SQLcl runtime adapter for saved Oracle DB connection handling and direct APEX validate/import/export roundtrips.
+---
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+
+# Skill — SQLcl
+
+## Purpose
+- Provide the APEXlang-specific SQLcl runtime adapter for this repository.
+- Preserve local behavior for offline schema dictionary fallback, saved SQLcl connection discovery, runtime preflight, and same-session APEX validate/import/export roundtrips.
+- Resolve saved Oracle connection aliases using `db_connection_name` and require the corresponding APEX workspace name for live APEXlang work.
+- Defer generic SQLcl capabilities and best practices to Oracle upstream DB skills instead of duplicating them locally.
+- Keep command knowledge inherent. Do not generate scripts or code to discover SQLcl commands.
+- Oracle's upstream DB skills remain useful general references: `https://github.com/oracle/skills/tree/main/db`.
+- This repository's SQLcl skill is the local APEXlang-specific SQLcl runtime adapter layered on top of that broader Oracle tooling guidance.
+
+## Upstream Oracle DB Skills Authority
+- Generic Oracle Database and SQLcl best practices come from Oracle upstream DB skills: `https://github.com/oracle/skills/tree/main/db`.
+- Use the upstream `db/sqlcl` skillset for SQLcl scripting, formatting, Liquibase, DDL generation, data loading, MCP server usage, scheduler daemon, AWR, and background jobs.
+- Use this local skill only as the APEXlang-specific SQLcl runtime adapter for connection discovery, capability probing, runtime preflight, and same-session APEX validate/import/export behavior.
+
+| Generic SQLcl need | Primary reference | Local responsibility |
+| --- | --- | --- |
+| SQLcl scripting and command usage | Oracle upstream `db/sqlcl` | Do not duplicate; apply upstream guidance when needed |
+| Formatting, DDL, data loading, Liquibase | Oracle upstream `db/sqlcl` | Route to upstream best practice |
+| MCP, scheduler daemon, AWR, background jobs | Oracle upstream `db/sqlcl` | Route to upstream best practice |
+| Saved connection discovery for APEXlang | This repo | Resolve user-specified `db_connection_name` and corresponding APEX workspace name |
+| APEX validate/import/export roundtrip | This repo | Run preflight and same-session SQLcl runtime gates |
+
+## Authoritative Policies
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/governance/00-governance.md`
+- `assets/rules-mapping.json`
+- `references/policies/memory-bank/20-data/db.connection.md`
+- `references/policies/governance/prompt-normalization.md`
+
+## Operational References
+- `references/ops/shared-reference-index.md`
+- `references/ops/one-message-router-contract.md`
+- `references/workflows/apexlang/apexlang-execution-model.md`
+- `references/ops/reusable-prompts/orchestration-master-generic.md`
+- `references/ops/reusable-prompts/server-side-conditions.md`
+
+## Execution Agents
+- `references/ops/sqlcl-agents/00-connection-gate.md`
+
+## Usage
+- Honor the repo-wide prerequisite metadata gate before prompting for a DB connection:
+  - inspect `assets/workspace-intelligence.json`
+  - auto-select one eligible schema dictionary when exactly one exists
+  - prompt the user to choose when multiple eligible schema dictionaries exist
+  - scan saved SQLcl connections before any DB-mode prompt
+  - use discovery to suggest saved SQLcl connection aliases, not to auto-approve live work
+  - use discovery to suggest saved SQLcl connection aliases, not to auto-approve live work
+  - prompt the user to choose when multiple saved SQLcl connection aliases exist
+  - require the user to specify `db_connection_name` and the corresponding APEX workspace name before live metadata validation, `apex validate`, `apex import`, runtime diagnostics, or new-app materialization
+  - require the user to specify `db_connection_name` and the corresponding APEX workspace name before live metadata validation, `apex validate`, `apex import`, runtime diagnostics, or new-app materialization
+  - treat `offline` as an explicit override rather than the first prompt
+- Load this skill alongside other domain skills when a workflow needs a live Oracle DB connection, SQL metadata validation, or a same-session APEXlang roundtrip.
+- Normalize terse or fragmentary user input directly according to `references/policies/governance/prompt-normalization.md`; it is repo governance, not a SQLcl reusable prompt.
+- Use `db_connection_name` as the canonical saved connection input name and `db_context.workspace.name` / `--workspace-name` as the canonical APEX workspace name location.
+- For packaged-build refresh work, keep SQLcl/runtime docs version-aware but scope changes to actual runtime behavior deltas only; do not rewrite the SQLcl contract for component-local metadata changes.
+- Probe both supported runtime candidates:
+  - resolved build-root runtime via `apex sql` from the matching local APEX build derived from `db_connection_name`
+  - PATH SQLcl runtime via `sql -name <db_connection_name>`, then legacy `sql <db_connection_name>`, then `sql /nolog` plus `connect <db_connection_name>`
+- Default APEX artifact workflows to check-only; do not ask users to type import intent before the live APEXlang check.
+- After the live APEXlang check passes, offer GUI/clickable choices using plain language: `Check APEXlang code` (recommended) or `Check and import APEXlang code`; include a short purpose summary for each choice, and if GUI choices are unavailable, stop after checking the code and report import as a follow-up.
+- In normal user-facing responses, describe internal check-only runs as `Check APEXlang code` and import-approved runs as `Check and import APEXlang code`.
+- Treat `node tools/apexctl.mjs runtime roundtrip ...` as a post-connection-gate runtime entrypoint. Interactive callers must not invoke it before deterministic metadata discovery, saved-connection discovery, and required `db_connection_name` plus APEX workspace name resolution are complete.
+- Run `node tools/apexctl.mjs runtime preflight --db-connection-name <db_connection_name>` before any live validate/import/export roundtrip and treat it as the runtime capability, metadata-probe, and target-identity freezing gate.
+- `node tools/apexctl.mjs runtime doctor` is the human-readable alias for a preflight-only runtime check.
+- Prefer the resolved build-root runtime when it is available and runtime-capable; otherwise use the PATH SQLcl runtime.
+- Packaged and source runs must execute through the same runtime executor rooted in `runtime/runtime.bundle.mjs`. The packaged launcher may verify and cache the packaged runtime artifact, but it must not redefine runtime behavior.
+- Use direct SQLcl commands for live work in the selected runtime path. The canonical roundtrip then runs:
+  - `apex validate -input <absolute_app_path>`
+- `apex import -input <absolute_app_path>` only after the user explicitly chooses import in the post-check GUI flow
+- Treat live `apex validate` as the first mandatory blocking runtime action in the roundtrip happy path, and run `apex import` immediately after it for explicit `validate-and-import` runs.
+- Post-import browser/runtime verification is disabled by default in the public CLI and only runs when the caller explicitly opts in with `--require-runtime-verification`.
+- Treat any post-import runtime verification findings as diagnostics: record them in runtime artifacts, but do not rewrite a successful `import_status` or `runtime_gate_status` to fail.
+  - optionally `apex export -applicationid <application_id> -exptype APEXLANG -split -dir <absolute_export_dir>` only when the active runtime path confirms export support
+  - when export backups are produced, create the output directory lazily and place them under `APEXLANG_OUTPUT_ROOT/apex-exports/<app>/`, not inside `applications/<app>/`
+- Treat `artifacts/` as optional output only. Do not require it before connection discovery, workspace probing, validation, import, or generation; create log/report/export directories only when a run writes them.
+- Treat any existing `apex-exports` path as backup/export material only. Do not use it as app source, metadata source, or app-resolution evidence unless the user explicitly asks for read-only export inspection, migration, or recovery analysis.
+- For existing-app `validate-and-import` runs, resolve the live canonical numeric application id before import, preserve it as session authority, and reuse it for workspace and import targeting.
+- Use a single bounded target resolver for every import-authorized run: scope the lookup to one intended workspace and return exactly one outcome (`resolved_existing_app`, `not_found_in_workspace`, `ambiguous_candidates`, or `identity_uncertain`).
+- Treat target-resolution timeout or failure as a terminal import blocker. A successful live validate proves source syntax only; it does not authorize direct SQLcl import, wrapper bypass, or create-new fallback.
+- Treat `update-existing` as the default import-authorized mode. If the bounded resolver returns `not_found_in_workspace`, stop the update path and require explicit `create-new` confirmation before import.
+- Allow `create-new` only when the bounded resolver returned `not_found_in_workspace`; block create-new for `ambiguous_candidates` and `identity_uncertain`.
+- If staged deployment metadata points at a different app id than the preserved canonical target, reconcile the staged deployment app id before import.
+- If import output reports a different application id than the preserved canonical target, block the run, record the mismatch in runtime artifacts, and treat the reported target as an accidental duplicate or wrong target.
+- Use `node tools/apexctl.mjs diagnostics resolve-build-root --db-connection-name <db_connection_name>` to inspect or report the resolved build root explicitly.
+- Prefer SQLcl-native help and direct command execution for these operations. Do not add Python wrapper scripts for validate/import/export when the command can be run directly in the active SQLcl session.
+- Before any live roundtrip, the executor may run the direct Node local first-pass check entrypoint `node tools/apexctl.mjs apexlang validate --app-path <absolute_app_path>` as an advisory helper lane, but that local check no longer blocks live check/import by itself.
+- Do not use `node tools/apexctl.mjs apexlang validate` as a runtime dependency or as a wrapper fallback path inside the runtime executor.
+- Treat the current runtime roundtrip as the `APEXlang source import` lane. Do not describe it to users as a generic import path when a narrower compiled SQL export import path or other alternate artifact lane is being discussed elsewhere.
+- If the local first-pass check already passed and a sandboxed build-root runtime attempt fails before real `apex validate` / `apex import` output because of filesystem/setup errors such as `EPERM`, `ENOENT`, or build-root `workdir/*` write failures, stop retrying the sandbox path and escalate immediately to the real live build-root roundtrip.
+- Treat runtime capability probing as the enable/disable gate for live runtime actions. A reported version without the required command capabilities is not runtime-ready.
+- Validate is mandatory for every live runtime action.
+- If the post-check GUI choice resolves to import, the live APEXlang check and import MUST happen in the same authenticated SQLcl user session.
+- If the real SQLcl session reports multiple-workspace ambiguity, automatically resolve the workspace id for the active `db_connection_name` and restart the same-session roundtrip with a run-scoped explicit `-workspaceid` without waiting for extra user direction.
+- When the workflow is actively resolving or confirming a workspace id for a DB connection, send the user this short progress update before continuing: `Identifying workspace ID for DB connection, please bare with me...`
+- The runtime layer resolves the workspace id from live metadata using a dedicated helper keyed by the staged app identity and active `db_connection_name`; the helper must hard-fail when it does not reduce to exactly one workspace id.
+- `runtime-run.json` and `runtime-run.log` must record the blocked ambiguity attempt, the workspace-resolution step, and the rerun outcome. A workspace-blocked first attempt is not success evidence for validate/import.
+- The runtime executor is phase-based and must stop on the first failed mandatory phase: `preflight`, `target_resolve`, `live_validate`, and `import`. `local_validate` remains in the phase model as an advisory/helper stage and must report whether it ran or was skipped by roundtrip policy.
+- The default runtime path validates/imports the resolved app path in place. Use transient runtime directories only for logs, stage reports, and temporary SQL scripts; do not stage and sync full app copies unless a workflow intentionally mutates artifacts before publish.
+- Default `supporting_objects` is `false`. Treat bundled metadata as read-only guidance and perform live metadata inspection during preflight before validate/import work continues.
+- `--import-mode auto|direct` controls import fallback. `auto` may switch once to `direct` only after the live APEXlang check passed and the failure is classified as wrapper/session-only.