pi-apexlang 0.1.0

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

@@ -0,0 +1,590 @@
+# APEXlang Prompt Contracts
+
+Canonical contract for APEXlang agent prompting. Use this file as the shared rule source for the router and the Draft, Critique, and Revision agents.
+
+## Purpose
+
+- Reduce prompt drift by centralizing high-value behavior rules.
+- Prefer compact, named contracts over repeated narrative guidance.
+- Make prompt-governed behavior easier to enforce in critique, validators, and tests.
+- Force a rules-first workflow: use the posted rules and workflows before any inference, and treat inference as a bounded last resort.
+
+## Instruction Hierarchy
+
+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
+
+If a lower layer conflicts with a higher layer, follow the higher layer and mark the lower layer as defective.
+
+## Required Tagged Sections
+
+Core agent prompts must use these exact top-level tags when they apply:
+
+- `<authority_rules>`
+- `<task_scope>`
+- `<allowed_sources>`
+- `<exact_match_policy>`
+- `<compiler_truth_contract>`
+- `<generation_plan_contract>`
+- `<output_contract>`
+- `<stop_conditions>`
+
+Rules:
+
+- Keep tag names stable across agents.
+- Use the same tag names in source and packaged prompts.
+- Put reusable shared policy in this file; keep phase prompts focused on phase-specific behavior.
+
+## Required Intermediate Artifacts
+
+### Compiler Truth Evidence
+
+Required when a draft introduces a non-exact-match structural edit.
+
+Each entry must include:
+
+- exact `query-valid-props` command
+- checked component or parent scope
+- conclusion
+- emitted decision
+
+### Generation Plan
+
+Required for non-trivial page, component, or application generation before emitting APEXlang.
+
+Minimum required fields:
+
+- target artifact scope
+- exact template family or variant selected
+- region, item, and button inventory in output order when applicable
+- source mode decisions such as `table/view` vs `sql`
+- navigation or target decisions
+- compiler-truth evidence references when required
+
+Required response order for non-trivial structural generation:
+
+1. `Compiler Truth Evidence` when required
+2. `Generation Plan`
+3. generated APEXlang
+
+### Trivial Work Boundary
+
+Trivial APEXlang work is limited to same-property edits on existing artifacts, such as wording-only updates, labels, titles, help text, comments, or replacing an existing documented property value with another value of the same kind.
+
+Work is non-trivial when it adds, removes, or reshapes page, region, item, button, SQL, LOV, validation, process, dynamic-action, navigation, template-option, source-mode, target-mapping, component-family, or behavior structure. New report, form, chart, map, dashboard, shared-component, navigation, or behavior generation is non-trivial even when the prompt calls it simple, basic, starter, lightweight, or quick.
+
+Trivial work may skip a full `Generation Plan` only when it stays on an existing documented property, does not introduce new structure or compiler-truth decisions, and does not alter runtime behavior. If there is doubt, classify the work as non-trivial.
+
+### Application Spec
+
+Required before complete application generation from functional requirements plus model/schema metadata.
+
+The spec must use `references/workflows/apexlang/application-spec.template.md` and include:
+
+- source evidence and conflict status
+- full page inventory
+- application composition plan
+- rich UI pattern plan using native APEX components
+- LOVs, validation behavior, modal/report-to-form behavior, and test plan
+- missing inputs and generation/runtime blockers
+- project-root `.apexlang/app-ux-contract.json` with non-empty `sourceEvidence`, `pageInventory`, `compositionPlan`, `richUiPatternPlan`, `lovPlan`, `behaviorPlan`, and `testPlan`
+
+## Workflow Precedence
+
+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.
+
+Do not:
+
+- guess when a rule, workflow, template, or compiler-truth step has not been exhausted
+- skip to “best judgment” because a template seems close enough
+- 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.
+
+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.
+
+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.
+
+## Snippet Classification Contract
+
+All prompt, template, and memory-bank snippets are one of these classes:
+
+- `normative_rule`: guidance that may be followed literally.
+- `metavariable_template`: structure-only template content that may be emitted only after every `{{...}}` variable is bound from schema evidence, user input, a template contract, or compiler-backed truth.
+- `illustrative_prompt`: natural-language routing example only; never schema evidence and never a source of table, column, page, item, API, or region identifiers.
+- `counterexample`: known-bad content that must never be emitted.
+
+Rules:
+
+- Treat unclassified examples and snippets as `illustrative_prompt` unless they are under an `Output Template` heading or an explicit variable contract.
+- Do not copy sample or placeholder identifiers from `illustrative_prompt` text into APEXlang, SQL, JSON contracts, or generated `.apx` files.
+- Do not emit a `metavariable_template` while any `{{...}}` variable remains unbound.
+- Stop with `Missing Inputs` when a required schema, page, item, region, LOV, API, or navigation binding cannot be proven.
+- Generated `.apx` artifacts must not contain unresolved `{{...}}` variables or prompt-only pseudo-identifiers such as `SOURCE_TABLE`, `LOOKUP_TABLE`, `RELATED_TABLE`, `SOURCE_ID`, `LOOKUP_ID`, or `LOOKUP_NAME`.
+
+## Validator Feedback Contract
+
+When local validation, live validation, VSCode Problems, `problems.json`, or `validation-report.json` emits rule IDs, feed those findings back into critique and revision using `assets/validator-fix-recipes.json`.
+
+For each reported issue, the critique/revision loop must preserve:
+
+- `rule_id`
+- cause
+- deterministic fix
+- owning guidance or template
+- verification result after rerun
+
+If a rule ID has no deterministic recipe and the owning guidance does not prove a fix, keep the run blocked with Required Revisions or Missing Inputs instead of guessing.
+
+## Rule IDs
+
+### DESTINATION_WORKSPACE_NAME_REQUIRED_001
+
+Statement:
+- When a run will generate `deployments/default.json` for a brand new app,
+  require the user to specify the destination APEX workspace name before
+  materialization, record the selected workspace in session
+  `context-resolution.json` under `db_context.workspace`, and stop with
+  `Missing Inputs` if no exact workspace name is available from session
+  context or explicit `--workspace-name`.
+
+Why:
+- `deployments/default.json.workspace.name` controls runtime target resolution
+  and must not be guessed, copied from the scaffold seed, or inferred from app
+  names.
+
+Valid:
+
+```text
+Missing Inputs: destination APEX workspace name is required in session context before generating deployments/default.json for a new app.
+```
+
+Invalid:
+
+```text
+I reused the scaffold workspace name because the user did not mention one.
+```
+
+Ownership:
+- Router prompt
+- Draft prompt
+- Package prompt tests
+
+### EXACT_MATCH_TEMPLATE_REQUIRED_001
+
+Statement:
+- Reuse a canonical template directly only when the component family and variant, parent context, nesting shape, and conditional mode already match.
+
+Why:
+- Exact-match reuse is safe. Near-match inference is a common source of structural drift.
+
+Valid:
+
+```text
+Reused the exact `buttons.redirect-this-app.md` shape and substituted only labels, page numbers, and item names.
+```
+
+Invalid:
+
+```text
+Copied a calendar example into a cards region because both have links and titles.
+```
+
+Ownership:
+- Draft prompt
+- Critique prompt
+
+### COMPILER_TRUTH_EVIDENCE_REQUIRED_001
+
+Statement:
+- Non-exact-match structural edits must provide compiler-truth evidence.
+
+Why:
+- Local validators and templates are incomplete guardrails.
+
+Valid:
+
+```text
+Compiler Truth Evidence
+1. Command: node tools/query-valid-props.mjs --component button --group behavior
+   Scope: button behavior.target
+   Conclusion: same-app redirect target must be `target: { ... }`
+   Emitted decision: used declarative target object syntax
+```
+
+Invalid:
+
+```text
+I checked the templates and the validator passed.
+```
+
+Ownership:
+- Draft prompt
+- Critique prompt
+- Package prompt tests
+
+### RULES_FIRST_WORKFLOW_REQUIRED_001
+
+Statement:
+- Draft and revision must follow the posted rules and workflow first, and must not guess or infer while those sources still provide an unanswered next step.
+
+Why:
+- Most structural drift comes from premature “helpful” inference rather than lack of guidance.
+
+Valid:
+
+```text
+The template family does not cover this exact shape, so I queried compiler truth next. The required target item mapping is still unresolved, so I stopped with Missing Inputs.
+```
+
+Invalid:
+
+```text
+The workflow did not spell out the target page, so I assumed page 4 because that seemed likely.
+```
+
+Ownership:
+- Draft prompt
+- Critique prompt
+- Package prompt tests
+
+### HUMAN_INTERVENTION_REQUIRED_001
+
+Statement:
+- When rules, workflow, templates, and compiler-backed truth still do not answer a required high-impact decision, stop for Missing Inputs or explicit human intervention instead of inferring.
+
+Why:
+- High-impact unresolved decisions should be escalated, not guessed.
+
+Valid:
+
+```text
+Missing Inputs: target page and target item names for calendar navigation were not provided and could not be proven from templates or compiler truth.
+```
+
+Invalid:
+
+```text
+I could not prove the target item names, so I invented `P4_ID` to keep moving.
+```
+
+Ownership:
+- Draft prompt
+- Critique prompt
+
+### APPLICATION_SPEC_REQUIRED_001
+
+Statement:
+- Complete app generation from FR/model sources must produce an implementation-ready application spec from `application-spec.template.md` before drafting non-trivial `.apx` artifacts.
+
+Why:
+- Rich application generation needs page inventory, composition, shared components, UI pattern choices, data evidence, and tests locked before page-by-page APEXlang drafting starts.
+
+Valid:
+
+```text
+I completed the application spec, including the Application Composition Plan and Rich UI Pattern Plan, then generated page artifacts from that spec.
+```
+
+Invalid:
+
+```text
+I skipped the spec and started drafting pages directly from the requirements.
+```
+
+Ownership:
+- Draft prompt
+- Critique prompt
+
+### GENERATION_PLAN_REQUIRED_001
+
+Statement:
+- Non-trivial page, component, and application generation must emit a compact Generation Plan before APEXlang.
+
+Why:
+- A frozen plan reduces plan/output drift and accidental re-decisions during emission.
+
+Valid:
+
+```text
+Generation Plan
+- Scope: page 12 interactive report page
+- Template: page-examples/interactive-report-page
+- Regions in order: summary -> report -> buttons
+- Source mode: report uses localDatabase/sqlQuery
+- Navigation: same-app detail link to page 13
+```
+
+Invalid:
+
+```text
+Draft
+page 12 (
+...
+```
+
+Ownership:
+- Draft prompt
+- Critique prompt
+- Package prompt tests
+
+### GENERATION_PLAN_DRIFT_001
+
+Statement:
+- The generated artifact must not drift from the frozen Generation Plan without an explicit plan repair.
+
+Why:
+- Equivalent late-stage rewrites create unstable output and inconsistent review behavior.
+
+Valid:
+
+```text
+Plan says same-app redirect target to page 16; emitted target points to page 16.
+```
+
+Invalid:
+
+```text
+Plan selected a classic report, but the draft emitted an interactive report because it seemed nicer.
+```
+
+Ownership:
+- Critique prompt
+- Revision prompt
+
+### DSL_MULTILINE_STRUCTURE_REQUIRED_001
+
+Statement:
+- Object-valued properties must emit `name: {` on their own line with nested properties on following lines.
+
+Why:
+- Inline compressed object syntax causes parser and import drift.
+
+Valid:
+
+```apx
+viewEditLink: {
+  page: 16
+  items: {
+    P16_ORDER_ID: &ORDER_ID.
+  }
+}
+```
+
+Invalid:
+
+```apx
+viewEditLink: { page: 16 items: { P16_ORDER_ID: &ORDER_ID. } }
+```
+
+Ownership:
+- Validator
+- Draft prompt
+- Critique prompt
+- `the source package regression tests`
+
+### DECLARATIVE_BUTTON_TARGET_REQUIRED
+
+Statement:
+- `redirectThisApp` buttons must use declarative target object syntax.
+
+Why:
+- Same-app redirects using scalar URLs or bare `target { ... }` drift from compiler-backed syntax.
+
+Valid:
+
+```apx
+behavior {
+  action: redirectThisApp
+  target: {
+    page: 6
+    clearCache: 6
+  }
+}
+```
+
+Invalid:
+
+```apx
+behavior {
+  action: redirectThisApp
+  target { page: 6 }
+}
+```
+
+Ownership:
+- Validator
+- Draft prompt
+- `the source package regression tests`
+
+### TEMPLATE_OPTIONS_MULTILINE_REQUIRED_001
+
+Statement:
+- Multi-value `templateOptions` arrays must be bracketed and emitted with one accepted value per line.
+
+Why:
+- Inline comma-separated arrays are noisy, unstable, and easy to mutate incorrectly.
+
+Valid:
+
+```apx
+templateOptions: [
+  #DEFAULT#
+  t-Report--stretch
+]
+```
+
+Invalid:
+
+```apx
+templateOptions: [#DEFAULT#, t-Report--stretch]
+```
+
+Ownership:
+- Validator
+- Draft prompt
+
+### TEMPLATE_OPTIONS_DEFAULT_ATOMIC_001
+
+Statement:
+- `#DEFAULT#` must remain one standalone template option value.
+
+Why:
+- Concatenated default tokens are invalid and usually indicate malformed serialization.
+
+Valid:
+
+```apx
+templateOptions: #DEFAULT#
+```
+
+Invalid:
+
+```apx
+templateOptions: #DEFAULT#t-Report--stretch
+```
+
+Ownership:
+- Validator
+- Draft prompt
+
+### CLASSIC_REPORT_DEFAULT_TEMPLATE_REQUIRED_001
+
+Statement:
+- Classic Report regions must use the canonical shared `appearance` block and the canonical report-template `componentAppearance` block.
+- Canonical Classic Report component options are `#DEFAULT#`, `t-Report--stretch`, and `t-Report--horizontalBorders`; do not emit alternating-row or row-highlight options by default.
+
+Why:
+- This is a high-drift area where template and import behavior must stay aligned. Live APEXlang validation on 26.1 maps the Classic Report report template to property `411` and reports missing values as `componentAppearance - template (string)`.
+
+Valid:
+
+```apx
+appearance {
+  template: @/standard
+  templateOptions: #DEFAULT#
+}
+componentAppearance {
+  template: @/standard
+  templateOptions: [
+    #DEFAULT#
+    t-Report--stretch
+    t-Report--horizontalBorders
+  ]
+}
+```
+
+Invalid:
+
+```apx
+appearance {
+  templateOptions: t-Report--stretch
+}
+```
+
+Ownership:
+- Validator
+- Draft prompt
+
+### CLASSIC_REPORT_COMPONENT_APPEARANCE_REQUIRED_001
+
+Statement:
+- Classic Report regions must emit `componentAppearance.template: @/standard`.
+
+Why:
+- The 26.1 compiler requires property `411` for the Classic Report report-template surface and reports the missing property as `componentAppearance - template (string)`.
+
+Valid:
+
+```apx
+componentAppearance {
+  template: @/standard
+  templateOptions: [
+    #DEFAULT#
+    t-Report--stretch
+    t-Report--horizontalBorders
+  ]
+}
+```
+
+Invalid:
+
+```apx
+componentAppearance {
+  templateOptions: #DEFAULT#
+}
+```
+
+Ownership:
+- Validator
+- Draft prompt
+
+### PAGE_ITEM_LAYOUT_LABEL_COL_SPAN_LEGACY_001
+
+Statement:
+- `layout.labelColSpan` is a legacy alias and must not be emitted.
+
+Why:
+- The canonical property name is `layout.labelColumnSpan`.
+
+Valid:
+
+```apx
+layout {
+  labelColumnSpan: 3
+}
+```
+
+Invalid:
+
+```apx
+layout {
+  labelColSpan: 3
+}
+```
+
+Ownership:
+- Validator
+- `the source package regression tests`
+
+## Stop Conditions
+
+- Stop with `Missing Inputs` when the posted rules, workflow, templates, and compiler-backed truth do not answer a required high-impact decision.
+- Stop with `Missing Inputs` or explicit human intervention before using inference for high-impact structural decisions.
+- Stop with `Missing Inputs` when compiler-backed truth cannot be resolved for a non-exact-match structural edit.
+- Stop with `Missing Inputs` when required DB object evidence is unresolved.
+- Stop when authoritative same-rank sources conflict and the conflict cannot be resolved from higher-ranked guidance.
+- Do not use validator success as a substitute for missing compiler-truth evidence or a missing Generation Plan.
+- Use bounded inference only after all higher-precedence rule and workflow sources are exhausted, and only for low-risk connective details that do not change structural legality.

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

@@ -0,0 +1,94 @@
+# Workflow: Create App From Functional Requirements And Model
+
+Use this workflow when the user asks to create or generate an app from functional requirements, FR, requirements, a data model, schema metadata, or similar local source documents. The intended user prompt can be as short as `create app from FR and model`.
+
+## Inputs
+
+- Functional requirements document, preferably Markdown.
+- Authoritative model/schema metadata, such as offline schema dictionary, data model export, table metadata, or live DB metadata.
+- Target app path or enough app-location context to resolve one.
+- APEX workspace name only when materializing a brand new app or doing live validation/import.
+- `db_connection_name` only for live DB metadata, validation, or import.
+
+## Source Precedence
+
+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.
+
+## Required Workflow
+
+1. Resolve local context through the normal APEXlang startup flow before asking the user for paths. Prefer discovered requirements and authoritative model/schema files when the result is unambiguous.
+2. Read the functional requirements and model/schema metadata completely enough to extract all required pages, objects, relationships, constraints, semantic columns, LOVs, and acceptance criteria.
+3. Fill `application-spec.template.md` as an implementation-ready application spec. Do not generate `.apx` files until this spec exists.
+4. Add an `Application Composition Plan` covering artifact scope, page groups, shared components, navigation, breadcrumbs, modal targets, refresh dependencies, and parent-child relationships.
+   - Every non-modal user page must have a matching shared breadcrumb entry and a visible breadcrumb region wired to `@breadcrumb`; modal/dialog pages, page 0, and page 9999 are exempt.
+   - Breadcrumb/title-bar regions must not use generic visible names such as `Breadcrumb` or `Title Bar`; use the current breadcrumb entry/page title as the region name, keep the title-bar/breadcrumb templates, and use live-valid template options such as standalone `#DEFAULT#`.
+   - Breadcrumb hierarchy must be explicit, not just present. For each non-modal page, record the breadcrumb entry id and either its parent entry/page or `root: true`. Pages launched primarily from a hub, management hub, parent detail, or contextual report must be parented to that launch/context page using `appearance { parentEntry: @... }` in `shared-components/breadcrumbs.apx`.
+   - Every requirement that says a report, parent row, child row, page button, or hub entry provides edit, create, open, or drilldown behavior must become a structured modal/link target or page action in the spec and UX contract, including source page, source region or column, target page, target item mappings, key column, and placement.
+   - Every requirement that says a form must require, allow, validate, prepopulate, default, hide, display-only, or return after save/cancel must become a structured validation, form-context, or defaulting entry in the spec and UX contract. Record the target item, controlling item/value when conditional, source item/column for defaults, context ownership, and visible/hidden/editable state.
+   - Master-detail workbenches must explicitly plan parent edit actions, child create actions, child edit links, and page-level create actions when the requirements call for them. Page-level create actions belong in the breadcrumb/title-bar when the page has a breadcrumb region.
+   - Every `behaviorPlan.parentChildContext` entry must include `actionCoverage` for the required parent edit, child create, child edit/detail, and page-level create behaviors, with source region, target page, target item mappings, key column, and placement. If a behavior is explicitly out of scope, record the exclusion with requirement evidence.
+   - Master-detail parent row selection must update the same-page hidden context item and refresh child regions through dynamic-action behavior. Do not implement the primary parent selection by redirecting/reloading the same page with a URL.
+   - Master-detail map child regions must use normal `:P...` binds plus explicit child-region refresh behavior for selected context. Do not require or emit map-layer `source.pageItemsToSubmit` unless direct compiler truth for the active build proves it valid for the selected layer shape. If marker selection opens a form, add a structured modal target for the map layer with target page, marker key column, and target item mapping.
+   - Multi-marker map pages must plan an initial viewport that fits the data. Prefer SQL-derived bounds from min/max latitude and longitude; do not plan `avg(latitude)` / `avg(longitude)` plus a fixed zoom unless requirements explicitly identify one known geography.
+   - Management or launcher hub list entries must include a conservative `fa-*` icon and a short description so media-list hubs render as scannable launch cards rather than plain text links.
+   - Every report region that opens a modal page must have a close-refresh dependency: an `apexafterclosedialog` dynamic action that refreshes the originating report region.
+5. Add a `Rich UI Pattern Plan` by mapping proven model semantics and requirement intent to native APEX patterns:
+   - amount/status/date facts can support dashboards with metric cards and charts
+   - KPI, metric, count, total, revenue, average, and summary-card requirements on dashboard pages must become Metric Card plan entries with labels, values, icons, source SQL, and metadata; do not satisfy single-value KPIs with Classic Reports.
+   - parent-child relationships can support workbenches or master-detail pages
+   - image-bearing entities can support Cards/gallery pages
+   - latitude/longitude facts can support Map pages
+   - date/timestamp business records can support Calendar pages
+   - exploratory reporting can support Smart Filters or Faceted Search
+   - 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.
+   - 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.
+   - `behaviorPlan.modalTargets` or `compositionPlan.modalTargets` must list every report-to-form edit/create/open flow from the requirements; do not satisfy an edit requirement with only a dialog-close refresh dynamic action.
+   - `behaviorPlan.parentChildContext` entries must include `actionCoverage`; do not stop at context item, parent region, and child region names.
+   - `behaviorPlan.validations` must list every requirement-driven form validation, including conditional required rules such as `CUSTOMER_ID` required when `ORDER_CHANNEL = ONLINE`.
+   - `behaviorPlan.formContext` must list context-owned form items that are populated by launch mappings and must not be user-editable, such as parent IDs on child create dialogs.
+   - `behaviorPlan.formDefaults` must list every requirement-driven defaulting behavior, including source item, lookup/source column, target item, and whether the user may override the default.
+   - Map marker edit/open flows count as modal targets and must identify the map source region/layer, marker key column, target page, and target item mapping.
+   - `behaviorPlan.pageActions` or `compositionPlan.pageActions` must list page-level create/action buttons with their target page and placement, for example `placement: breadcrumb`.
+   - Faceted-search range/date facets must list their source column and runtime data type. Use `date` for date/time columns such as `ORDER_DATE`, `ORDER_DATETIME`, and `TIMESTAMP` schema columns; use `number` for numeric facets; omit `source.dataType` for string facets.
+   - Faceted-search checkbox/radio facets must plan `maxDisplayedEntries` and high-cardinality value filtering. Default `maxDisplayedEntries` to `10`, keep justified values between `5` and `15`, and set `displayFilterInitially: true` for Product, Customer, Store, Assignee, Owner, User, Employee, Supplier, Email, SKU, name, or title facets.
+   - `compositionPlan.managementHubEntries` must include icon and description fields for every launcher entry.
+   - 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.
+
+## Output Contract
+
+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 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
+- every test maps to functional acceptance criteria or runtime validation gates
+- `.apexlang/app-ux-contract.json` mirrors the application spec in validator-readable form at the user project root
+
+## Stop Conditions
+
+- Missing or ambiguous functional requirements.
+- Missing or ambiguous authoritative model/schema metadata for DB-backed generation.
+- 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.
+- 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.