pi-apexlang 0.2.2 → 0.4.0

package/skills/apexlang/references/workflows/apexlang/prompt-contracts.md

@@ -14,8 +14,9 @@ Canonical contract for APEXlang agent prompting. Use this file as the shared rul
 1. `references/policies/memory-bank/00-guard/ai.guard.md`
 2. `references/policies/governance/00-governance.md`
 3. This file
-4. Phase-specific workflow prompts
-5. Templates and examples
+4. Machine-readable contracts, grammar, and compiler metadata
+5. Phase-specific workflow prompts
+6. Exact-match templates and examples
 
 If a lower layer conflicts with a higher layer, follow the higher layer and mark the lower layer as defective.
 
@@ -51,6 +52,20 @@ Each entry must include:
 - conclusion
 - emitted decision
 
+### Progressive Disclosure Trace
+
+Required for non-trivial routing, page generation, component generation, and complete app generation.
+
+Each trace must be compact and ordered:
+
+- normalized intent and matched component or pattern id
+- exact rule card, contract, or workflow path opened first
+- grammar or compiler metadata evidence used for structural legality
+- exact template path loaded only when an exact-match example is needed
+- skipped broad surfaces, such as template directories or README packages, when a smaller contract answered the decision
+
+Do not load `templates/**` broadly to discover syntax. Use `assets/grammar/apexlang.ebnf` for syntax, compiler metadata or `query-valid-props` for semantic property legality, structured pattern packs for common workflows, and then one exact template family only when the preceding sources select it.
+
 ### Generation Plan
 
 Required for non-trivial page, component, or application generation before emitting APEXlang.
@@ -58,10 +73,11 @@ Required for non-trivial page, component, or application generation before emitt
 Minimum required fields:
 
 - target artifact scope
-- exact template family or variant selected
+- selected contract, pattern pack, or exact template family/variant
 - region, item, and button inventory in output order when applicable
 - source mode decisions such as `table/view` vs `sql`
 - navigation or target decisions
+- progressive disclosure trace references
 - compiler-truth evidence references when required
 
 Required response order for non-trivial structural generation:
@@ -97,23 +113,26 @@ The spec must use `references/workflows/apexlang/application-spec.template.md` a
 Use this precedence order for every generation and revision task:
 
 1. Apply guardrails and governance.
-2. Apply the relevant workflow and template family.
-3. Use compiler-backed truth and machine-readable contracts.
-4. Stop with `Missing Inputs` or request human intervention when the rules and workflow do not answer the need.
-5. Only then use bounded inference, and only for low-risk connective details that do not change structural legality.
+2. Normalize intent and select the smallest matching rule card, structured contract, workflow, or domain entry.
+3. Use `assets/grammar/apexlang.ebnf` for syntax legality and compiler-backed truth for allowed blocks, properties, enums, slots, and template options.
+4. Use structured pattern packs, the frozen application spec, and UX contract before full `.apx` rendering for common workflows.
+5. Load exact-match templates only after the smaller sources select a concrete family or variant.
+6. Stop with `Missing Inputs` or request human intervention when the rules, contracts, grammar, compiler truth, and workflow do not answer the need.
+7. Only then use bounded inference, and only for low-risk connective details that do not change structural legality.
 
 Do not:
 
-- guess when a rule, workflow, template, or compiler-truth step has not been exhausted
+- guess when a rule, contract, grammar, compiler-truth, workflow, or exact-template step has not been exhausted
 - skip to “best judgment” because a template seems close enough
+- scan broad template trees to discover syntax that the grammar or metadata can answer
 - invent target pages, target item names, enum values, slots, or block shapes when the workflow cannot prove them
 - treat local validator success as permission to infer missing structure
 
 ## Generation Boundary
 
-For non-trivial APEXlang output, the `Generation Plan` is a boundary contract, not only a summary. It must identify the supported template family or documented page/design pattern that authorizes each emitted page, region family, item family, button/navigation mode, dynamic-action shape, and non-default template option.
+For non-trivial APEXlang output, the `Generation Plan` is a boundary contract, not only a summary. It must identify the smallest loaded authority that authorizes each emitted page, region family, item family, button/navigation mode, dynamic-action shape, and non-default template option: structured contract or pattern pack first, grammar/compiler evidence next, and exact template family only when loaded.
 
-Generated `.apx` artifacts must stay inside the current authoritative sources: guardrails, governance, loaded memory-bank rules, current template documentation, compiler-backed truth, and machine-readable contracts. Requirements may select, combine, or parameterize supported native APEX/APEXlang patterns, but they do not authorize new DSL surface or undocumented component behavior.
+Generated `.apx` artifacts must stay inside the current authoritative sources: guardrails, governance, loaded memory-bank rule cards, machine-readable contracts, grammar, compiler-backed truth, and selected exact-match template documentation. Requirements may select, combine, or parameterize supported native APEX/APEXlang patterns, but they do not authorize new DSL surface or undocumented component behavior.
 
 Do not invent properties, enum values, block names, target shapes, item mappings, template options, region capabilities, dynamic-action selectors, page patterns, component families, or navigation modes outside the loaded authoritative sources. Unsupported design intent must be recorded as blocked/deferred, simplified to a documented native APEX pattern, or represented by a supported placeholder only when the active workflow explicitly allows placeholders.
 
@@ -150,6 +169,58 @@ If a rule ID has no deterministic recipe and the owning guidance does not prove
 
 ## Rule IDs
 
+### GRAMMAR_FIRST_AUTHORITY_REQUIRED_001
+
+Statement:
+- APEXlang syntax decisions must come from `assets/grammar/apexlang.ebnf`; semantic legality for blocks, properties, enums, slots, template options, and component variants must come from compiler metadata, direct compiler validation, or `query-valid-props`. Templates are exact-match examples or renderer references, not the primary syntax oracle.
+
+Why:
+- This repo is template-heavy. Treating prose templates as syntax authority increases latency and creates drift. Grammar and compiler metadata are smaller, more deterministic, and easier to validate.
+
+Valid:
+
+```text
+Checked grammar for the block/property shape, queried compiler metadata for the chart series option, then loaded one chart template for an exact emitted example.
+```
+
+Invalid:
+
+```text
+Searched several template folders and copied the closest shape even though grammar or compiler metadata was not checked.
+```
+
+Ownership:
+- Router prompt
+- Draft prompt
+- Critique prompt
+- Package prompt tests
+
+### PROGRESSIVE_DISCLOSURE_TRACE_REQUIRED_001
+
+Statement:
+- Non-trivial APEXlang work must keep a compact source trace from normalized intent to the smallest loaded rule or contract, then grammar/compiler evidence, then an exact template path only if needed.
+
+Why:
+- The agent should finish faster by avoiding broad README/template scans and should make every emitted structure traceable to the right source.
+
+Valid:
+
+```text
+source_trace: dashboard -> rules.catalog:DASHBOARD_KPI_METRIC_CARD_REQUIRED_001 -> page-construction-packs:dashboard -> query-valid-props:themeTemplateComponent/metricCard -> metric-card._common.md
+```
+
+Invalid:
+
+```text
+I browsed the page examples and used the closest dashboard-like template.
+```
+
+Ownership:
+- Router prompt
+- Draft prompt
+- Critique prompt
+- Package prompt tests
+
 ### DESTINATION_WORKSPACE_NAME_REQUIRED_001
 
 Statement:

package/skills/apexlang/references/workflows/apexlang/workflow-create-app-from-fr-and-model.md

@@ -15,8 +15,10 @@ Use this workflow when the user asks to create or generate an app from functiona
 1. Model/schema metadata is authoritative for database objects, columns, keys, constraints, data types, display labels, LOV candidates, and semantic facts such as image, date, latitude/longitude, status, and amount fields.
 2. Functional requirements are authoritative for business behavior, page inventory, workflow, page pattern intent, navigation, UI composition, validations, derived metrics, acceptance criteria, and exclusions.
 3. `application-spec.template.md` defines the required planning output shape.
-4. Existing app files may be read only for integration facts after app resolution. Do not use existing app files as reusable pattern or DSL-shape examples.
-5. If same-rank sources conflict on structural facts, stop with `Missing Inputs` and list the conflict.
+4. `assets/contracts/page-patterns.json` and `assets/contracts/page-construction-packs.json` define the structured pattern-selection path before final `.apx`.
+5. `assets/grammar/apexlang.ebnf` and compiler metadata define APEXlang syntax and property legality; templates are exact-match examples after these sources select the emitted family.
+6. Existing app files may be read only for integration facts after app resolution. Do not use existing app files as reusable pattern or DSL-shape examples.
+7. If same-rank sources conflict on structural facts, stop with `Missing Inputs` and list the conflict.
 
 ## Required Workflow
 
@@ -47,7 +49,8 @@ Use this workflow when the user asks to create or generate an app from functiona
    - secondary maintenance pages can be grouped through a hub/list page
    - report-to-form CRUD defaults to a drawer end/right form unless the requirements explicitly select standard modal dialog, drawer start/top/bottom, wizard modal, popout-style dialog, or full-page detail flow
    - drawer form pages must emit `dialogTemplate: @/drawer` plus an explicit end/right drawer template option; `templateOptions: #DEFAULT#` alone is not enough for default drawer behavior
-6. Write project-root `.apexlang/app-ux-contract.json` before drafting non-trivial `.apx` artifacts. This machine-readable contract must contain non-empty `sourceEvidence`, `pageInventory`, `compositionPlan`, `richUiPatternPlan`, `lovPlan`, `behaviorPlan`, and `testPlan` sections.
+6. Select page/workflow patterns from `assets/contracts/page-patterns.json` and `assets/contracts/page-construction-packs.json` before loading Markdown templates. Record the selected pack id, required inputs, generated components, validation rules, and reference paths in the application spec and source trace.
+7. Write project-root `.apexlang/app-ux-contract.json` before drafting non-trivial `.apx` artifacts. This machine-readable contract must contain non-empty `sourceEvidence`, `pageInventory`, `compositionPlan`, `richUiPatternPlan`, `lovPlan`, `behaviorPlan`, and `testPlan` sections.
    - Every generated user page must map to a requirement or declared low-risk derived workflow.
    - `compositionPlan.breadcrumbs` must be an object array with `page`, `entry`, and either `root: true`, `parentEntry`, or `parentPage`; do not replace it with a flat page-number list.
    - If `compositionPlan.managementHubPages` is present, resolve the management hub page and parent every management child breadcrumb to that hub.
@@ -64,10 +67,15 @@ Use this workflow when the user asks to create or generate an app from functiona
    - Every declared rich UI pattern, display mapping, link, modal target, refresh dependency, LOV, layout recipe, and accessibility/guidance requirement must be traceable to requirements, model/schema metadata, or explicit user assertion.
    - Add `requiresAppUxContract: true` to the app-local `.apex/apexlang.json` runtime metadata for full-app FR/model generation so local validation blocks missing UX contracts.
    - Keep the completed `application-spec.md` planning artifact in project-root `.apexlang/`, not inside `applications/<app>/` or the app-local `.apex/` runtime metadata directory.
-7. For every SQL-bearing page, region, LOV, validation, or process, record object evidence as `schema_doc`, `live_db`, `user_asserted`, or `unresolved`.
-8. If any required object, column, relationship, target page, target item, UX contract mapping, or compiler-truth decision remains unresolved, stop with `Missing Inputs` instead of drafting artifacts.
-9. After the spec and UX contract are complete, run the normal APEX generation workflow. For each non-trivial page or shared component, emit a compact `Generation Plan` before APEXlang.
-10. Validate generated artifacts with local validation and compiler-truth audit before publish, live validation, or import eligibility. Live validation/import still requires explicit `db_connection_name` and matching APEX workspace name.
+8. Render from the frozen application spec, UX contract, selected pattern packs, grammar, and compiler evidence. Render into staging, run `apexlang format --strict-structure` immediately, reject structural formatter changes, and publish only after local validation passes.
+9. For every SQL-bearing page, region, LOV, validation, or process, record object evidence as `schema_doc`, `live_db`, `user_asserted`, or `unresolved`.
+10. If any required object, column, relationship, target page, target item, UX contract mapping, pattern-pack input, grammar/compiler decision, or compiler-truth decision remains unresolved, stop with `Missing Inputs` instead of drafting artifacts.
+11. After the spec, UX contract, and pattern-pack selection are complete, generate each implementation unit in a fresh isolated model context containing the selected task-specific context capsule and required compiler/tool results. For each non-trivial unit, emit a compact `Generation Plan` before APEXlang.
+12. Stage validation to avoid repeated whole-app work:
+    - During unit generation, run only unit-local syntax, property, reference, and unresolved-placeholder checks.
+    - After all units are assembled, run one full local integration validation and one compiler-truth audit across the application.
+    - Run live APEX validation once after local integration passes. Rerun it only after a deterministic repair changes the validated artifact, preserving the existing maximum repair-attempt policy.
+    - Live validation/import requires a resolved `db_connection_name`; new-app materialization also requires the exact destination APEX workspace name.
 
 ## Output Contract
 
@@ -76,6 +84,8 @@ The completed application spec must be traceable:
 - every page maps to one requirement or low-risk derived workflow
 - every DB object and column maps to model/schema evidence or explicit user assertion
 - every rich UI pattern maps to native APEX components, not static HTML substitutes
+- every common page workflow maps to a structured pattern pack when one exists
+- every final `.apx` structure maps to the frozen application spec, UX contract, pattern-pack selection, and grammar/compiler evidence before template examples
 - every link or modal target identifies the target page and item mappings
 - every form target records its presentation choice and button/process/dynamic-action contract
 - every form validation, context-owned item, and defaulting behavior maps to requirement evidence and generated page artifacts
@@ -89,6 +99,7 @@ The completed application spec must be traceable:
 - Conflicting page inventory, table, column, key, or constraint facts.
 - Rich UI pattern requested without the required semantic evidence.
 - Missing or incomplete project-root `.apexlang/app-ux-contract.json` for full-app FR/model generation.
+- Missing structured pattern-pack inputs for a workflow covered by `page-construction-packs.json`.
 - Unresolved compiler-truth requirement for a non-exact-match structural artifact.
 - Missing APEX workspace name when materializing a brand new app.
 - Missing `db_connection_name` or workspace name for live validation/import.

package/skills/apexlang/release-notes.json

@@ -7,6 +7,162 @@
   "downloadUrl": "https://github.com/oracle/skills/",
   "downloadLabel": "Download",
   "releases": [
+    {
+      "version": "2026.09.21",
+      "summary": "This release adds and hardens support for Media List, Comments, and Metric Card template components, expands Cards and Region Display Selector capabilities, and delivers deterministic Smart Filter and Search workflows with compiler-backed validation, source-projection contracts, safe navigation, and packaged registry/runtime alignment.",
+      "sections": [
+        {
+          "title": "Media List Template Component",
+          "items": [
+            "Added Media List template-component support for report and partial configurations, including base, grouped, linked, avatar, badge, and layout variants.",
+            "Added deterministic routing with explicit precedence for direct Media List requests, List regions, and Classic Reports.",
+            "Added metadata-driven source validation with report-mode support limited to verified local database and SQL query sources.",
+            "Added parent-aware placement validation for Standard and Content Block regions.",
+            "Added compiler-conformance checks for Media List source types and nested component properties.",
+            "Expanded Media List templates, component metadata, registry entries, validator recipes, documentation, package coverage, and regression checks."
+          ]
+        },
+        {
+          "title": "Comments Template Component",
+          "items": [
+            "Added Comments template-component support for report and partial display modes.",
+            "Added required user and comment mappings with optional date-column mapping and compiler-backed validation.",
+            "Added report styles, avatar icon/image/initials variants, display settings, and compiler-backed action support.",
+            "Added safety validation for avatar image URLs, dynamic attributes, comment classes, and projected source columns.",
+            "Added partial-mode restrictions for single-row sources and report-only behavior blocks.",
+            "Aligned Comments contracts and guidance with APEX 26.1 and expanded the component registry, templates, validator recipes, and regression coverage."
+          ]
+        },
+        {
+          "title": "Metric Card Template Component",
+          "items": [
+            "Added Metric Card template-component support for minimal, grouped, linked, avatar, badge, and partial configurations.",
+            "Added deterministic routing that aligns semantic Metric Card requests with component selection.",
+            "Added guidance for dashboard KPI strips, normalized multi-row sources, explicit projected child columns, grouping, and selection.",
+            "Added validation for Metric Card settings, supported data types, child-column mappings, action targets, URL schemes, hosts, paths, fragments, and link attributes.",
+            "Added safe declarative navigation and trigger-action contracts for Metric Card links.",
+            "Expanded Metric Card templates, metadata, routing, repair recipes, package tests, and compiler-backed validation coverage."
+          ]
+        },
+        {
+          "title": "Smart Filter and Search Region",
+          "items": [
+            "Added dedicated Smart Filter and Search routing with deterministic resolver precedence over related Faceted Search and Cards intents.",
+            "Smart Filters now require one authoritative filtered-results region declared after the filter region.",
+            "Added supported-target validation for Classic Reports, Cards, Maps, and Calendars while rejecting unsupported target shapes.",
+            "Added validation for searchable-column allowlists, refinement and suggestion sources, filter topology, source projections, and duplicate or reordered search columns.",
+            "Added security-scope checks so search, suggestions, refinements, and counts remain within the filtered region's authorization and server-side condition.",
+            "Added performance, accessibility, refresh, export, and Generation Plan evidence requirements.",
+            "Improved diagnostics for missing or incomplete Smart Filter plugin metadata.",
+            "Updated Smart Filter/Search templates, routing catalogs, validator recipes, package coverage, and regression checks."
+          ]
+        },
+        {
+          "title": "Cards Region Updates",
+          "items": [
+            "Expanded Cards region contracts and templates for source mapping, layout, ordering, media, actions, conditions, trigger actions, and row selection.",
+            "Added deterministic validation for primary-key identity, projected source columns, native media mappings, action sequencing, and supported property values.",
+            "Added refresh contracts for refresh-after-dialog and refresh-on-change behavior.",
+            "Added navigation validation for full-card, title, subtitle, media, and button actions.",
+            "Added declarative behavior-target validation, trigger-action consumer checks, safe navigation URL validation, and restricted link-attribute handling.",
+            "Preserved native Cards media, security, and navigation boundaries while aligning contracts with APEX 26.1.",
+            "Expanded Cards metadata, templates, routing rules, validator recipes, package coverage, and regression checks."
+          ]
+        },
+        {
+          "title": "Region Display Selector",
+          "items": [
+            "Added Region Display Selector support with standard and permutation-oriented workflows.",
+            "Added application-scoped slider configuration through component settings.",
+            "Added validation for controller uniqueness, target membership, minimum eligible targets, controller exclusion, ordering, and excluded breadcrumb or header regions.",
+            "Clarified the distinction between `htmlDomId` and `staticId` for controllers and controlled regions.",
+            "Documented catalog defaults separately from generation-required values.",
+            "Added machine-readable registry metadata, validator repair guidance, focused regressions, and packaged component coverage."
+          ]
+        }
+      ]
+    },
+    {
+      "version": "2026.08.28",
+      "summary": "This release adds supported Avatar, Badge, and Timeline template-component workflows, pins Font APEX icon validation to a versioned catalogue, and strengthens routing, validation, packaging, and template-registry integrity. Credits to Github user [https://github.com/zrh535](zrh535) for identifying these bugs and proposing the suggested fixes.",
+      "sections": [
+        {
+          "title": "New Supported Template Components",
+          "items": [
+            "Added report-mode Avatar support for initials, icons, and URL-column images.",
+            "Added report-mode Badge support for minimal and linked Badge regions.",
+            "Added Timeline support for report and partial configurations, including optional Avatar and Badge content.",
+            "Timeline Avatar variants now use one matching icon, image, or initials value; initials come from a dedicated projected column.",
+            "Avatar image URLs now accept only `:APP_FILES` or `:APEX_FILES` with a static relative path.",
+            "Moved each template component's options into its own directory."
+          ]
+        },
+        {
+          "title": "Validation, Routing, and Security",
+          "items": [
+            "Badge validation covers table/view, SQL, REST, JSON, function-body, property-graph, and sample-data sources.",
+            "Icon requests keep icon guidance when they also match Cards, Dashboards, Interactive Reports, or Lists.",
+            "Validation now checks source mappings, authorization, nested components, safe targets, and invalid direct page properties."
+          ]
+        },
+        {
+          "title": "Font APEX Icons",
+          "items": [
+            "Added a pinned Font APEX 26.1 icon and modifier index.",
+            "Avatar, Badge, and Timeline icons must use one indexed icon and supported modifiers.",
+            "Added tooling to check and refresh the icon index."
+          ]
+        },
+        {
+          "title": "Merged SQLcl and Runtime Bug Fixes",
+          "items": [
+            "Fixed double decoding of HTML entities during SQLcl script processing.",
+            "Fixed malformed closing script tags in SQLcl runtime scripts.",
+            "Enforced TLS certificate verification in the SQLcl runtime verifier and added regression coverage for verification failures.",
+            "Hardened temporary SQL file creation and cleanup.",
+            "Added regression coverage for HTML decoding, malformed script tags, TLS verification, and temporary SQL-file security."
+          ]
+        }
+      ]
+    },
+    {
+      "version": "2026.08.01",
+      "summary": "This release makes APEXlang generation more deterministic by establishing explicit grammar, package, pattern, and component contracts. It simplifies orchestration, strengthens compiler-aware validation, improves cross-platform runtime consistency, and delivers safer defaults for file uploads and SQL projections.",
+      "sections": [
+        {
+          "title": "Generation Workflow and Reusable Patterns",
+          "items": [
+            "Simplified the core routing and prompt contract, clarifying intent normalization, routing boundaries, missing-input handling, and the distinct responsibilities of draft, critique, and revision agents.",
+            "Updated natural-language routing test coverage and validation guidance so human requests are translated into APEXlang tasks more predictably.",
+            "Added structured page-pattern and page-construction packs, plus catalog and routing-load support, so generation can select reusable patterns through machine-readable contracts."
+          ]
+        },
+        {
+          "title": "Language, Packaging, and Runtime Contracts",
+          "items": [
+            "Added the complete `apexlang.ebnf` grammar, grammar documentation, semantic rules, and an upstream-consistency check to make syntax validation and language evolution deterministic and reviewable.",
+            "Introduced explicit package-layer contracts and a public package manifest. Package loading now separates distributable public content from internal and development-only assets.",
+            "Normalized CRLF and mixed line endings to LF before formatting and runtime validation across the APEXlang CLI, package flow, and validator. The normalization boundary is now shared through reusable runtime helpers, documented in the runtime-gate guidance, and covered by regression tests so formatting, packaging, and validation produce reproducible results across platforms."
+          ]
+        },
+        {
+          "title": "Component and Property Validation",
+          "items": [
+            "Strengthened property mapping by retaining component-tree context during validation, allowing child properties to be evaluated against their parent component and relationships.",
+            "Added handling for ambiguous component matches, conditional properties, faceted-search and smart-filter aliases, source-located diagnostics, and regression coverage for invalid child records.",
+            "Expanded executable guardrails for component properties, defaults, dependencies, required values, aliases, and page consistency; templates and examples now align with compiler-backed component truth.",
+            "Added Unicode SQL alias validation coverage, including quoted multibyte aliases and aliases with spaces, while preserving existing ASCII behavior."
+          ]
+        },
+        {
+          "title": "File Upload Experience",
+          "items": [
+            "File-upload items now default to `blockDropzone` for a more usable upload experience, while `inlineDropzone` and `nativeFileBrowse` remain available when explicitly requested.",
+            "Explicit Dropzone modes now require `dropzoneTitle` and `dropzoneDesc`; templates, validator fix recipes, audit documentation, and regression tests were updated accordingly."
+          ]
+        }
+      ]
+    },
     {
       "version": "2026.06.26",
       "summary": "This release tightens APEXlang generation boundaries around verified metadata, compiler-backed component shapes, and snippet safety. It expands local validation for live-runtime edge cases, updates report, button, faceted-search, map, list, and Interactive Grid guidance, and converts sample content into explicit metavariable templates so generated artifacts do not inherit placeholder schema names.",