pi-apexlang 0.1.0

package/skills/apexlang/references/policies/apexlang-dsl-reference.md

@@ -0,0 +1,136 @@
+# APEXlang DSL Reference (Codex & AI tooling)
+
+## Overview
+- **Purpose:** Provide a concise reference for composing APEXlang artifacts that both Codex and AI tooling can consume.
+- **Scope:** Pages, regions, items, shared components, validations, and shared templates located under `templates/**`.
+- **Usage:** Load the minimal rule set from `references/policies/memory-bank/` and reference these templates for deterministic outputs.
+
+
+## When to Use This Guide
+- Reference for onboarding teammates needing plain-language context before diving into templates.
+- Helpful during reviews when verifying generated DSL matches template expectations.
+- Not required for automated agents; they rely on templates and memory-bank rules directly.
+
+## DSL Conventions
+- Key-value pairs use `name: value` with colon syntax.
+- Multi-line text (SQL, PL/SQL) lives inside triple backticks with language hints (` ```sql `, ` ```plsql `).
+- Template identifiers follow PascalCase and align with Universal Theme (UT) components.
+- Never invent attributes; reuse those documented in templates and rule files.
+
+## Packaged Build Baseline
+- The active packaged baseline for this repo does not introduce broad APEXlang name-set drift.
+- Treat packaged-build refreshes as narrow metadata deltas unless packaged metadata proves broader DSL drift.
+
+## Core Categories
+
+### Pages (`templates/page-examples/`)
+- Each page family is foldered as:
+  - `<page-name>/<page-name>._index.md`
+  - `<page-name>/<page-name>._common.md`
+  - `<page-name>/page.apx`
+- Core page families include:
+  - `global_page_0/`
+  - `home-page/`
+  - `login-page/`
+  - `form-page/`
+  - `interactive-report-page/`
+  - `interactive-grid/`
+  - `dashboard-page/`
+  - `faceted-search/`, `map-page/`, `calendar-page/`
+
+### Page Layout Templates (`templates/page-layout-templates/`)
+- Provide UT layout scaffolds: `standard.apx`, `modal-dialog.apx`, `drawer.apx`, etc.
+- Use via `appearance { pageTemplate: @/standard }` or matching identifier.
+
+### Region Components (`templates/region-components/`)
+- `static-content/static-content._common.md` — Shared contract for static content regions.
+- `static-content/static-content.accordion.md` — Accordion region scenarios.
+- `static-content/static-content.collapsible.md` — Collapsible region scenarios.
+- `static-content/static-content.blank-with-attributes.md` — Blank container layouts.
+- `static-content/static-content.cards.md` — Cards and smart filter integration.
+- `static-content/static-content.collection-toolbar.md` — Collection toolbar with smart filters.
+- `static-content/static-content.dividers.md` — Divider region examples.
+- `static-content/static-content.empty-state.md` — Empty state templates.
+- `static-content/static-content.buttons.md` — Toolbar and body button patterns.
+- `region-components/classic-report/`, `region-components/interactive-report/`, and `region-components/interactive-grid/` — Tabular region families with `_index.md`, `_common.md`, and scenario docs.
+- Chart templates now live under `templates/region-components/chart/` and use `chart._common.md` plus scenario-specific Markdown files.
+- `dynamic-content.apx`, `dynamic-action-refresh-report.apx` — Programmatic and dynamic behaviors.
+- Breadcrumb and template component patterns included for consistent navigation.
+
+### Interactive Grid Saved-Report Notes
+- Interactive Grid saved-report aggregate metadata now maps through `wwv_flow_imp_page.create_ig_rpt_agg_apexlang`.
+- Interactive Grid saved-report aggregate metadata now keeps `p_view_id` and `p_static_id` structurally visible in the import path.
+- Interactive Grid saved-report chart `Sort By` now defaults to `LABEL`.
+- When documenting or generating explicit non-default chart sort values, use only `VALUE`, `HIGH`, `LOW`, `TARGET`, `X`, `Y`, and `Z`.
+- Do not emit explicit `LABEL` just to restate the default behavior unless the DSL contract for the concrete template requires it.
+
+### Items (`templates/items/`)
+- Items are foldered by family, for example:
+  - `items/text-field/text-field._index.md`
+  - `items/select-list/select-list._index.md`
+  - `items/radio-group/radio-group._index.md`
+  - `items/switch/switch._index.md`
+  - `items/number-field/number-field._index.md`
+- For LOV-backed items, start from the relevant family `_index.md` and pair with shared LOV templates when needed.
+
+### Buttons (`templates/buttons/`)
+- Use `buttons._index.md` as dispatcher and `buttons._common.md` for shared contract/guardrails.
+- Load one action-specific variant template (`buttons.submit.md`, `buttons.redirect-this-app.md`, `buttons.redirect-other-app.md`, `buttons.defined-by-da.md`, `buttons.trigger-action.md`, `buttons.menu.md`) plus optional overlays as needed.
+
+### Shared Components (`templates/shared-components/`)
+- Shared components are organized by family folders such as `lovs/`, `lists/`, `component-settings/`, `authorizations/`, `authentications/`, and `breadcrumbs/`.
+- Base app structure templates under `base-app-structure/scaffold-example/` provide the runtime seed for critical shared components and baseline pages. They do not authorize whole-directory publish into generated app roots.
+
+### Validations (`templates/business-logic/validations/validations._index.md`)
+- Variable catalog: `templates/business-logic/validations/validations._common.md`.
+- Documents and captures every validation type for APEX, including button-gated and authorization-aware patterns.
+- Before generating any validation, start from the gospel skeleton:
+    ````
+    validation [validationStaticId] (
+        name: [validationName]
+        execution {
+            sequence: [seq]
+        }
+        validation {
+            plsqlExpression: [plsqlExpression]
+        }
+        error {
+            errorMessage: [errorMessage]
+            associatedItem: [associatedItem]
+        }
+        security {
+            authorizationScheme: [authorizationScheme]
+        }
+    )
+    ````
+  - Replace placeholders with real values; drop the entire `security {}` block if no authorization scheme is required.
+- Replace button aliases (for example `@{submit-button}`) and authorization schemes with page-specific components before use.
+
+## Governance References
+- `references/policies/memory-bank/00-guard/ai.guard.md` — Non-negotiable guardrails.
+- `references/policies/memory-bank/10-global/apex.global.md` — Global naming, navigation, and access standards.
+- `references/policies/memory-bank/20-data/*` — SQL and logic policies (invoke API first, named notation).
+- `references/policies/memory-bank/30-pages/*` — Page-type rules (forms, reports, dashboards, charts).
+- `references/policies/memory-bank/40-components/*` — Component-specific guidance plus the shared composition contract for templates, template options, and grid/layout defaults.
+
+## Template Documentation Strategy
+- Each template includes inline comments describing purpose, variants, and usage notes.
+- Official documentation should reference these templates directly; avoid duplicating definitions elsewhere.
+- For Codex automation, pair template paths with metadata (component name, required inputs) in manifests.
+
+## Best Practices for Codex & AI tooling Execution
+- **Minimal Rule Loading:** Use `assets/rules-mapping.json` to resolve required rules per artifact.
+- **Critical Pages:** Ensure `p00000-*.apx`, `p00001-*.apx`, and `p09999-*.apx` exist or are generated from the base app structure templates.
+- **Shared Components:** Seed only the named runtime artifacts when creating new applications (see templates under `base-app-structure/scaffold-example`), and keep template-family docs and registries out of generated app roots.
+- **Logging:** Final published output goes to `applications/<target-app>/...` only after the resolved live runtime action succeeds. Durable runtime evidence is limited to compact reports and transcripts under `the temp-runtime logs directory under `APEXLANG_OUTPUT_ROOT/logs/``, created only when a workflow writes them.
+- **Confidence Scores:** The internal review loop must retain a numeric confidence threshold of at least `0.95` before publish/completion wording.
+
+## Integration Hooks
+- Components registry (`assets/apex-generation/components.registry.json`) links natural language synonyms to templates and rules.
+- Orchestration router (`SKILL.md`) provides the app-development entrypoint, delegating full generation by loading `references/workflows/apex-generation.md`.
+- `assets/orchestration.manifest.json` exposes machine-readable orchestration metadata.
+
+## Next Steps
+- Maintain this reference alongside template updates.
+- Expand with component-specific sections (e.g., items, regions) including required inputs tables and example snippet references.
+- Align Codex skill documentation with this guide to prevent divergence.

package/skills/apexlang/references/policies/compiler-prop-map.md

@@ -0,0 +1,41 @@
+# Compiler Prop Map
+
+Bundled compiler-truth lookup helper for APEXlang property debugging.
+
+## Contents
+
+- `tools/query-valid-props.mjs`
+- `tools/query-valid-props-template-components.mjs`
+- `templates/template-components/template-component-profiles.json`
+- `tools/compiler-truth-audit.mjs`
+
+## Authority
+
+1. Compiler metadata from the active SQLcl or Oracle runtime and direct compiler validation
+2. Exact-match templates and examples that already match the same component family and variant
+3. Repository machine-readable fallback guidance such as `assets/component-attributes.json`
+
+## Use When
+
+- A property is rejected by the compiler or APEX validate/import.
+- A component family has multiple compiler variants and you need the exact property surface.
+- You need build-pinned conditional property truth rather than curated guidance.
+
+## Packaged Usage
+
+```bash
+node tools/query-valid-props.mjs --help
+node tools/query-valid-props.mjs --component column --parent region --list
+node tools/query-valid-props.mjs --component region --group source --when 94=NATIVE_IR --when 957=LOCAL --when 959=TABLE
+node tools/query-valid-props.mjs --compiler-oracle-home /path/to/oracle.sql-developer-26.1.2 --component column --parent region --list
+node tools/query-valid-props.mjs --template-component metricCard
+node tools/compiler-truth-audit.mjs --app-path applications/my-app --verify-component-attributes
+```
+
+## Runtime Contract
+
+- This lookup surface reads Oracle's shipped `apexlang_meta_data.json` directly from a discoverable VS Code extension, dbtools home, SQLcl home, or compiler jar.
+- Universal Theme template-component family settings are bundled from the distilled `templates/template-components/template-component-profiles.json` catalog.
+- No checked-in compiler prop-map snapshot is shipped in the public package.
+- The helper normalizes metadata in memory for each run so results stay tied to the active runtime.
+- The audit command writes machine-readable compiler-truth evidence and blocks generation workflows when the active runtime metadata or curated component policy provenance is stale.

package/skills/apexlang/references/policies/context-overview.md

@@ -0,0 +1,78 @@
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+# references/policies
+
+## Purpose
+
+`references/policies/` is the repository's shared knowledge and policy area. It contains the rules, templates, reference material, and machine-readable manifests that workflow skills use to decide what to load and how to behave.
+
+If you are navigating the repo manually, this is the best starting point for understanding the repository's guardrails and canonical template inventory.
+
+## What is in this directory
+
+- `governance/`
+  - Repo-level governance and precedence documents.
+  - Start here when you need the canonical policy layer behind a workflow.
+- `references/policies/memory-bank/`
+  - The rule partitions used by routing and generation: guardrails, global rules, data rules, page rules, component rules, and styling rules.
+  - Also contains machine-readable contracts such as `assets/rules-mapping.json`, `assets/component-policies.json`, and `assets/component-attributes.json`.
+- `db/`
+  - Offline schema-dictionary markdown files used to avoid unnecessary DB connections during DB-backed planning and generation.
+  - `assets/workspace-intelligence.json` is the machine-readable registry the router must inspect before asking for a DB connection.
+- `apexlang/`
+  - APEXlang reference material and canonical templates.
+  - The main subareas are `templates/` and `references/policies/apexlang-dsl-reference.md`.
+- `assets/routing-assets-index.json`
+  - Routing asset index. Points to routing-related assets; it is not the domain router itself.
+- `assets/routing-catalog-main.json`
+  - Domain routing catalog. Maps broad user intent to workflow domains before opening full workflow docs.
+- `assets/routing-load-policy.json`
+  - Routing load policy. Defines document open order and context caps per routing intent.
+- `templates/template-family-registry.json`
+  - Template family registry. Catalogs APEXlang template families and should not be confused with routing catalogs.
+
+## How to use this directory
+
+- Read `governance/00-governance.md` when you need the canonical governance anchor.
+- Read `references/policies/memory-bank/` when you need rule files that shape generation behavior.
+- Read `templates/` when you need the canonical template families that workflows should reference.
+- Read `the temp-runtime logs directory under `APEXLANG_OUTPUT_ROOT/logs/`` when it exists and you need compact runtime, validator, import, or audit-log outputs. Do not require `artifacts/` before generation starts.
+- Read `the temp-runtime reports directory under `APEXLANG_OUTPUT_ROOT/reports/`` when it exists and you need critiques, change logs, summaries, SQL captures, or other non-log durable artifacts.
+- Read `references/policies/compiler-prop-map.md` when you need the compiler-derived APEXlang property query helper for exact syntax validity checks.
+- Use `assets/routing-assets-index.json` when onboarding or tooling needs to discover the routing assets.
+- Use `assets/routing-catalog-main.json` and `assets/routing-load-policy.json` first for compact routing decisions.
+- Use `templates/template-family-registry.json` only for template family discovery after routing has selected APEXlang/template work.
+
+## Important machine-readable assets
+
+- `assets/rules-mapping.json`
+  - Keyword-driven selector for minimal rule loading.
+- `assets/component-policies.json`
+  - Deterministic policy contract used by validation and critique checks.
+- `assets/component-attributes.json`
+  - Canonical component attribute allowlist/schema.
+- `assets/workspace-intelligence.json`
+  - Compact registry describing eligible offline schema dictionaries under `workspace schema dictionaries discovered by `node tools/apexctl.mjs workspace probe``.
+- `assets/routing-assets-index.json`
+  - Routing asset index for routing-aware tooling.
+- `assets/routing-catalog-main.json`
+  - Domain routing catalog for broad workflow selection.
+- `assets/routing-load-policy.json`
+  - Routing load policy for load order and document caps.
+- `templates/template-family-registry.json`
+  - Template family registry for APEXlang template discovery.
+
+## Related ownership notes
+
+- Policy anchor: `references/policies/governance/00-governance.md`
+- Router contracts: domain `skills/*/SKILL.md` files
+- Router conventions: `references/ops/one-message-router-contract.md`
+- Workflow index and orchestration manifest:
+  - `references/workflows/apexlang/apexlang-execution-model.md`
+  - `assets/orchestration.manifest.json`
+
+## Maintenance
+
+- Keep this README aligned with the actual directory layout.
+- Keep this file human-facing; do not turn it into a second copy of governance or router contracts.
+- If a new top-level folder or machine-readable contract is added under `references/policies/`, document it here.

package/skills/apexlang/references/policies/governance/00-governance.md

@@ -0,0 +1,160 @@
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+# AI Tooling Core Rule: Governance and Loading Order
+
+## Purpose
+- Make `references/policies/governance/` the single policy anchor for precedence, loading order, and non-negotiable constraints.
+- Keep behavior deterministic, minimal, and aligned with repository routing.
+- Don't guess.  Ever.  Look at your skills for all reference.
+
+## Source of truth
+- Rule content lives in `references/policies/memory-bank/`.
+- Domain entrypoints live in `skills/*/SKILL.md`.
+- Domain assets and registries live under `skills/*/assets` and `skills/*/references`.
+
+## Security defaults
+- Generated business applications default to authenticated access. Use bare `mustNotBePublicUser` on every non-login, non-Page 0 page unless requirements justify a stricter existing authorization scheme; custom authorization schemes are referenced with `@<static-id>` such as `@administration-rights`.
+- Page 0 (`p00000-global-page.apx`) is the Global Page artifact and must remain the canonical minimal skeleton unless explicitly populated with components intended for every page. Do not add normal page-level security, authorization, authentication, page-access-protection, or autocomplete properties to Page 0.
+- The login page is the only expected public page. Any other public page must include security-review rationale and validation output.
+- Application security defaults must include Session State Protection, `maxSessionIdleTime: 3600`, and `maxSessionLength: 28800`.
+- Hidden and ID-style page items default to `checksumRequiredSessionLevel`; unrestricted hidden items require same-page dynamic-action ownership and comments rationale.
+- Report/grid output remains escaped by default; reviewed HTML formatting must live in declarative column formatting with escaped substitutions.
+- Secure-cookie emission must be proven against the active APEXlang runtime before any DSL attribute is hard-coded.
+- Do not use Perl one-liners for automated rewrites of APEXlang `@...` aliases such as `@mustNotBePublicUser`; Perl interpolates unescaped `@name` as an array. Use Python/Node tooling for these rewrites, or explicitly escape `@` in manual Perl commands.
+
+## Load Order and Precedence
+1. Always respect numeric prefixes.
+2. Memory-bank precedence is enforced by its partitioning:
+   - `00-guard/`
+   - `10-global/`
+   - `20-data/`
+   - `30-pages/`
+   - `40-components/`
+3. Keep active context small by using `assets/rules-mapping.json`.
+
+## Startup routine
+1. Load `references/policies/memory-bank/00-guard/ai.guard.md`.
+2. Load this file.
+3. Load `references/policies/context-overview.md`.
+4. Load `assets/rules-mapping.json`.
+5. For DB-backed work, resolve the prerequisite metadata source before routing further:
+   - read `assets/workspace-intelligence.json` and apply the schema-dictionary selection rules for offline metadata reasoning
+   - scan saved SQLcl connections before any user prompt about DB mode or connection knowledge
+   - use discovered saved connections as candidates, not as automatic approval for live DB work
+   - ask the user to choose only when multiple eligible schema dictionaries or multiple saved connections exist
+   - if live-connection selection still remains unresolved and live DB context is required, ask for `db_connection_name` and the corresponding APEX workspace name
+   - treat `offline` as explicit user intent, not as the default first prompt
+   - before drafting object-specific SQL or DB-object references, resolve `object_evidence_source` for each referenced object as `schema_doc`, `live_db`, `user_asserted`, or `unresolved`
+   - if any required object remains unresolved, stop with `Missing Inputs` instead of substituting sample or inferred object names
+6. Accept free-form input by default, normalize what is explicit, and ask only one clarification round for critical blockers.
+7. Select the minimal relevant rule files and load them in precedence order.
+
+## Selection constraints and token discipline
+- Prefer rule files over inference.
+- Load only the minimum relevant files.
+- Do not reject a request only because it is fragmentary, badly phrased, or unstructured.
+- Prefer one short simple-English clarification round over broad discovery when critical routing or safety inputs are missing.
+- For app-scoped APEX work, limit application inspection to the resolved target app under `applications/<target-app>/`.
+- `applications/<target-app>/` is the standard repo convention, not a license to guess. If `applications/` is missing, empty, or does not identify the requested app, ask for the exact app directory or a bounded scan root and stop with `Missing Inputs` until resolved. Nonstandard app paths are allowed only after explicit user confirmation.
+- Treat `artifacts/` as optional output only. Never require it to exist before generation starts, never scan `artifacts/**` for app candidates, schema metadata, examples, or pattern sources, and create output subdirectories only when a workflow writes logs, reports, or backups.
+- Treat any `apex-exports` path segment as backup/export material only. Ignore those trees during app resolution, metadata discovery, bounded scans, and generation unless the user explicitly asks to inspect an export backup.
+- Use `templates/**` as the only pattern-selection source for APEXlang generation. Do not use `applications/**` as an example corpus, scaffold source, or DSL-shape reference.
+- Reads from the resolved target app are integration-only: concrete wiring facts such as existing shared-component ids, page targets, aliases, list entries, breadcrumb entries, and output paths.
+- Do not use runtime logs as syntax truth.
+- For APEX build-refresh work, classify the change first:
+  - broad DSL drift only when packaged metadata or direct compiler validation proves added, removed, or renamed APEXlang-facing syntax
+  - narrow metadata delta when the packaged build changes defaults, accepted values, or component-local import behavior without broader DSL drift
+- Keep build-pinned facts in canonical docs and active templates only; do not leave upgrade guidance stranded in one-off audit notes.
+- Do not change unrelated component families solely because the packaged build version changed.
+
+## Database policy
+- Use `references/policies/memory-bank/20-data/db.connection.md` for connection details.
+- Use `assets/workspace-intelligence.json` as the authoritative machine-readable registry for offline schema dictionaries.
+- For DB-backed work, require resolved `prereq_source` first:
+  - `schema_doc`
+  - `saved_connection`
+  - `user_prompt`
+  - `unresolved`
+- Record `connection_source` separately for connection discovery:
+  - `saved_connection`
+  - `user_prompt`
+  - `unresolved`
+- Resolve `db_mode` after deterministic metadata and saved-connection discovery, with `offline` remaining explicit.
+- Do not perform live DB work if `db_connection_name` is missing or ambiguous.
+- For object-specific SQL or DB-object references, require resolved `object_evidence_source`:
+  - `schema_doc`
+  - `live_db`
+  - `user_asserted`
+  - `unresolved`
+- Do not generate or preserve object-specific SQL when `object_evidence_source` is `unresolved`.
+- Do not treat templates, memory-bank examples, compiler metadata labels, or prior guessed code as proof that a schema object exists.
+- DB object creation/update enforcement remains canonical in `references/policies/memory-bank/00-guard/ai.guard.md`.
+
+## Completion policy
+- Completion/runtime-import rules are canonical in `references/policies/memory-bank/00-guard/ai.guard.md`.
+- Governance references only:
+  - `RUNTIME_GATE_COMPLETION_REQUIRED_001`
+  - `ONLINE_IMPORT_CONDITIONAL_001`
+
+## Artifact logging policy
+- When a run edits files under `references/policies/**` or `skills/**`, append an entry to root `CHANGE_MEMORY.md`.
+- If `CHANGE_MEMORY.md` does not exist, create it first.
+- Keep `CHANGE_MEMORY.md` append-only.
+- Each entry must include:
+  - a timestamp
+  - the files updated
+  - a content summary describing what was changed in each file
+  - the reason for each change
+
+## Templates and attributes policy
+- For page-scoped work, choose the matching family under `templates/page-examples/**` first, then load the narrower supporting family under `templates/**` as needed.
+- Load the relevant templates under `templates/**` before drafting regions, page items, buttons, or shared components.
+- Packaged compiler metadata and direct compiler validation are authoritative for actual APEXlang syntax, component/property validity, and build-pinned conditional rules.
+- Every generated or revised `.apx` artifact must have a passing compiler-truth audit report before publish, live validate, or import eligibility. The audit is executed through `node tools/apexctl.mjs apexlang compiler-truth audit --app-path <resolved_app_path> --verify-component-attributes`.
+- `assets/component-attributes.json` is the repo's compiler-provenanced curated safe subset for covered components and generation/lint guidance; if it disagrees with the packaged compiler metadata or direct compiler validation, the compiler wins.
+- Repository templates and examples are generation guidance only; they can drift and must not be treated as exact syntax truth when the compiler-backed sources disagree.
+- An exact-match canonical template may be reused as a drafting shortcut only when the component family/variant, parent context, nesting shape, and conditional mode already match and the change is limited to safe instance substitutions such as names, labels, ids, aliases, and SQL text.
+- If the template is not an exact match, or if a change introduces a new property, nested block, enum token, slot, template option, or layout attribute, query compiler-backed truth before generating code.
+- Never invent attribute/value pairs.
+
+## UI composition policy
+- Treat `references/policies/memory-bank/40-components/apex.templates.md` as the single shared owner for template, template-option, and layout-composition defaults.
+- Never invent CSS classes to solve structure, spacing, alignment, or framing.
+- Prefer native templates, template options, slots, and layout attributes over selector/class-based workarounds.
+- Treat `templateOptions` values as build-pinned accepted values, not string-composed values.
+- Never concatenate `#DEFAULT#` with another token.
+- Emit only exact values proven by the owning template catalog or documented runtime-valid composite token; do not substitute labels, CSS class strings, or inferred aliases.
+
+## Oracle APEX and APEXlang policy
+- Oracle APEX only.
+- Generate only APEXlang DSL output.
+- Use triple backticks only for SQL.
+- Follow the APEXlang grammar, packaged compiler metadata, and repository templates in that order for syntax truth.
+
+## Runtime policy
+- Direct SQLcl roundtrips are the canonical live runtime path.
+- For agent-facing generated-app validation, use `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>]` as the single public validate-only gate. It may call preflight/roundtrip internally, but generation agents must consume its structured outputs.
+- Treat `--apex-root` as the APEX/SQLcl runtime selector only. Use `--compiler-oracle-home` only when overriding compiler-truth metadata discovery; otherwise let compiler truth auto-discover the VS Code SQLcl/APEXlang runtime.
+- Runtime validation must emit and preserve `validation-report.json`, `validation-transcript.log`, `problems.json`, and `component-contracts/<build>.json` for the selected target build.
+- Live APEX validation from the selected target build is required and authoritative. Missing required runtime inputs or missing live runtime evidence records `LIVE_RUNTIME_VALIDATION_REQUIRED_001` and blocks completion.
+- `problems.json` is the compact live-validation repair interface derived from `validation-report.json`. Patch only reported live validation problems, then rerun `runtime validate` until `live_check_status = pass`; warnings are treated as errors when the runtime does.
+- Local lint, compiler-truth, and VS Code Problems snapshots remain diagnostics unless live validation cannot run. Broad memory-bank, policy, and template prose must not override live validation or the build contract pack.
+- For every APEX artifact workflow, default to checking APEXlang code and run the live APEXlang check through `apex validate -input` when live runtime prerequisites are resolved.
+- After the live APEXlang check passes, offer GUI/clickable choices with a short purpose summary using plain language: `Check APEXlang code` (recommended) or `Check and import APEXlang code`; if GUI choices are unavailable, stop after checking the code and report import as a follow-up.
+- `apex validate -input` is mandatory for live check completion.
+- Existing-app `validate-and-import` runs must resolve and preserve one canonical live numeric application id before import.
+- Import-authorized runtime resolution must stay bounded to one intended workspace and produce one terminal outcome: `resolved_existing_app`, `not_found_in_workspace`, `ambiguous_candidates`, or `identity_uncertain`.
+- Target-resolution timeout or failure is terminal for import. Do not use live validate success as permission to run direct SQLcl import or bypass the wrapper.
+- `update-existing` remains the default import-authorized mode. If the outcome is `not_found_in_workspace`, stop the update path and require an explicit `create-new` confirmation before any import that could create a live app.
+- Once that canonical application id is known, use it as the session authority for workspace and import targeting; do not fall back to alias-only targeting.
+- If staged deployment metadata does not match the canonical live application id, reconcile the staged deployment app id before import-authorized runtime steps.
+- If import output later reports a different application id than the preserved canonical target, block the run and treat the reported target as a duplicate or wrong-target outcome.
+- `create-new` imports are allowed only after the bounded resolver returns `not_found_in_workspace`; block create-new for `ambiguous_candidates` and `identity_uncertain`.
+- Shared-app `validate-and-import` is CI-owned by default. Local runs stay validate-only unless the run explicitly uses manual override authority after a second GUI confirmation.
+- If the post-check GUI choice resolves to import, `apex validate -input` and `apex import -input` must run in the same authenticated SQLcl user session.
+- If the session changes between validate and import, STOP and re-run validation before import.
+
+## Enforcement
+- `.aiconfig` is the active repo enforcement config.
+- When in doubt, stop and ask for clarification.
+- If critical ambiguity remains after one clarification round, stop with `Missing Inputs`.

package/skills/apexlang/references/policies/governance/apex-spec-standards.md

@@ -0,0 +1,118 @@
+# Business Requirements Document & Application Specification
+
+## 1. Executive Summary
+**Application Name:** [Insert name here]  
+
+**Purpose:**  
+A concise overview describing the problem being solved, target users, and the desired outcome.
+
+**Business Objectives:**  
+- Primary goals and measurable KPIs the application must achieve.  
+- Alignment with organizational strategy.  
+
+---
+
+## 2. Scope
+**In-Scope:**  
+- Specific features, user personas, business processes, and integrations included in this application.  
+
+**Out-of-Scope:**  
+- Exclusions, deferred functionality, or manual processes.  
+
+---
+
+## 3. Stakeholders & User Personas
+| Role/Persona   | Description                | Key Responsibilities        |
+|----------------|----------------------------|-----------------------------|
+| Business Owner | Who commissions the app    | Decision making, sign-off   |
+| End User       | Primary daily operator     | Usage, reporting            |
+| Support/IT     | Support/admin functions    | Maintenance, troubleshooting|
+
+---
+
+## 4. Functional Requirements
+| ID   | Requirement Description                          | Priority (High/Med/Low) | Acceptance Criteria                       |
+|------|--------------------------------------------------|-------------------------|-------------------------------------------|
+| FR-1 | System must allow users to submit tickets        | High                    | Users can create and track tickets         |
+| FR-2 | Tickets must be assigned automatically to leads  | Med                     | Assignment algorithm verifies correct routing|
+| FR-3 | Export reports in CSV                            | Low                     | Users can download report data as CSV      |
+
+(Add as many requirements as needed for coverage)
+
+---
+
+## 5. Non-Functional Requirements
+| ID    | Category     | Description                                 | Acceptance Criteria               |
+|-------|--------------|---------------------------------------------|-----------------------------------|
+| NFR-1 | Performance  | Response time < 2 seconds for any user action| Test response times under load     |
+| NFR-2 | Security     | All data encrypted at rest and in transit    | Penetration test results pass      |
+| NFR-3 | Availability | 99.9% uptime during business hours           | Downtime < 5 minutes/month         |
+| NFR-4 | Accessibility| WCAG 2.1 AA compliance                       | Accessibility audit report         |
+
+---
+
+## 6. Business Rules
+Document core rules and logic not captured as requirements:  
+- All tickets must be assigned within 5 minutes of submission.  
+- Users can only edit tickets they created.  
+- Reports are visible only to managers.  
+
+---
+
+## 7. User Workflows & Use Cases
+
+### 7.1 Process Flow Diagram
+(Insert or describe the logical flow; can be accompanied by a flowchart where possible.)
+
+### 7.2 Use Cases
+| Use Case ID | Title         | Primary Actor | Trigger            | Main Flow Steps                             | Alternate/Exception Flows          |
+|-------------|---------------|---------------|--------------------|---------------------------------------------|------------------------------------|
+| UC-1        | Submit Ticket | End User      | Need for IT support| 1. Log in, 2. Submit ticket, 3. Confirmation| E1. Form errors, E2. Timeout        |
+| UC-2        | Assign Ticket | System        | New ticket created | 1. Detect unassigned, 2. Match logic, 3. Assign| E1. No team available             |
+
+---
+
+## 8. Data Model
+
+### 8.1 Entity Relationship Diagram (ERD)
+(Describe core entities and their relationships. A diagram can be inserted if possible.)
+
+### 8.2 Entity Details
+| Entity | Attribute    | Data Type | Description              | Required (Y/N) | Constraints          |
+|--------|--------------|-----------|--------------------------|----------------|----------------------|
+| Ticket | ticket_id    | String    | Unique ticket identifier | Y              | Primary key, UUID    |
+| Ticket | submitted_by | String    | User ID                  | Y              | FK to User           |
+| User   | user_id      | String    | User identifier          | Y              | Primary key          |
+| User   | email        | String    | Email address            | Y              | Unique, email format |
+
+---
+
+## 9. Integration & Interfaces
+- **APIs:** List endpoints the app must expose/consume.  
+- **External Systems:** List dependencies (e.g., corporate SSO, HR system).  
+
+---
+
+## 10. Assumptions & Constraints
+- **Assumptions:** Underlying requirements (e.g., “All users have SSO”).  
+- **Constraints:** Must run on Oracle Cloud.  
+
+---
+
+## 11. Acceptance Criteria & QA
+- List concrete, testable outcomes for each feature/workflow.  
+- Prioritize user acceptance tests and scenario walkthroughs.  
+
+---
+
+## 12. Appendix
+- Glossary of terms  
+- Linked artifacts (wireframes, diagrams, referenced policies)  
+
+---
+
+### Guidance for AI Consumption
+- Use clear, atomic requirements and business rules.  
+- Maintain explicit mappings between users, features, and data.  
+- Provide structured tables where possible for parsing.  
+- Include data types and validation in data model.  

package/skills/apexlang/references/policies/governance/prompt-normalization.md

@@ -0,0 +1,23 @@
+# Prompt Normalization
+
+Purpose
+- Define the repo-wide router behavior for accepting free-form user requests.
+- This is governance reference material, not a reusable runtime prompt.
+- Agents should normalize intent directly from the user's message; load this file only when maintaining, auditing, or resolving ambiguity in router behavior.
+
+Use when maintaining router behavior for prompts that are terse, fragmentary, informal, mixed-domain, or missing required details.
+
+Contract
+- Accept free-form prompts without forcing a structured rewrite.
+- Normalize explicit intent, identifiers, and overrides before asking follow-up questions.
+- Ask only for critical blockers that affect routing, scope, safety gates, or emitted artifacts.
+- Use one short simple-English clarification round at most.
+- If critical ambiguity remains after that round, return `Missing Inputs` and stop.
+- Do not guess database objects, target artifacts, selectors, or workflow scope.
+- Do not treat this file as a mandatory runtime loading step for APEXlang generation.
+
+Router fields
+- `prompt_normalization: enabled`
+- `clarification_rounds_max: 1`
+- `clarification_style: simple_english`
+- `ambiguity_policy: ask_then_stop`