Ui Inspect Promote

• none

Invocation Format (Preferred)

$ui-inspect-promote source:<proposal-root-dir> target:<page-key> approval-ref:<chat-or-ticket-id>

Invocation Examples

$ui-inspect-promote source:output/ui-inspection/<yyyy.MM.dd>/<timestamp>-<label>-proposal target:<page-key> approval-ref:<chat-or-ticket-id>

Workflow

1. Load previewed proposal artifacts, publish approval evidence, and profile policies.
2. Inspect the target runtime area first (folder stubs, neighboring pages, route constants, shared nav wiring).
3. Promote proposal outputs into runtime structure within approved scope using the smallest production-safe delta.
4. Enforce governance rules (naming, locator, message, and helper policies).
5. Run validation checks and report promotion evidence.

Rules

1. Flow classes are not auto-generated by ui-inspect; any flow artifact creation requires explicit user approval.
2. Proposal artifacts (sections, contracts) are generator outputs; promotion into runtime code must follow project governance and explicit publish/runtime approval.
3. During runtime promotion, avoid standalone one-item nav contracts unless explicitly approved.
4. During runtime promotion, preserve runtime_patterns.login_page_path as the canonical login runtime path and avoid duplicate login scaffolds.
5. During runtime promotion, keep shared interactions helper-first using runtime_patterns.base_page_path as the canonical shared page helper reference.
6. Use runtime_patterns.login_page_path as the reference example for new or refactored page objects:
   • private locator getters
   • BasePage helper-first interactions
   • intent-based public methods
   • direct field assignment -> set...
   • action methods -> click...
   • assertion methods -> verify...
   • navigation methods -> navigateTo...
   • runCommand(...) names aligned with public method names
7. Prefer id-anchored locators for navigation when available; when id is on container nodes (for example li[id='...']), anchor selectors to the structural node and target its actionable child.
8. For navigation/menu controls, avoid text-only locators when collisions are possible (for example repeated labels like Checks); prefer structural id anchoring.
9. Ambiguity/uniqueness enforcement belongs to the shared click infrastructure anchored by runtime_patterns.base_page_path, not duplicated in each page/section class.
10. Reusable UI-state logic (for example attribute normalization and disabled-token detection) must be centralized in shared helpers, not duplicated inside page/section classes.
11. Section/page objects should remain thin and intent-focused; shared interaction guarantees and click semantics must stay centralized in base helpers.
12. During runtime promotion, canonical message modules must live under runtime_patterns.messages_root and follow the profile strategy (current standard: flat messages folder).
13. Message migration must be incremental and backward-compatible; keep thin re-export adapters until all consumers are migrated.
14. Runtime message catalogs must keep a standard shape: error, success, warning, info (as const) plus <Page>MessageKind.
15. Prefer direct message imports from concrete files; avoid barrel/index imports unless explicitly requested.
16. Runtime promotion must resolve project-variable conventions from ui-project-profile (locator_policy, naming_policy, promotion_policy) instead of hardcoded project-specific behavior.
17. When locator_policy.test_attribute_priority is configured, promotion must preserve the approved locator choice derived from that ordered policy instead of hardcoding a single test attribute convention.
18. If locator_policy.test_attribute_priority is omitted or empty, promotion should not introduce custom test-attribute-specific behavior.
19. Folder/layout decisions for runtime POMs must follow profile-provided primary-nav layout policy across primary navigation panels.
20. Redundant interaction pre-check cleanup is allowed only when equivalent guarantees already exist in the shared helper declared by runtime_patterns.base_page_path.
21. When profile defines POM split thresholds, promotion must enforce split behavior and page-facade policy from profile.
22. Most web interaction logic must live in the shared helper declared by runtime_patterns.base_page_path by default; POM classes should only keep interaction logic when it is page-specific and not safely generalizable.
23. Any interaction helper introduced outside the shared helper declared by runtime_patterns.base_page_path requires an explicit exception note with rationale and scope.
24. Do not introduce thin pass-through wrapper methods in page, route, or section classes when the shared helper declared by runtime_patterns.base_page_path already provides the same behavior.
25. When existing shared helpers are insufficient, promotion preview must include a new shared helper needed checkpoint before any implementation.
26. That checkpoint must name the proposed helper, intended shared home (the file declared by runtime_patterns.base_page_path or another approved shared helper file), exact page-specific gap it solves, and why a local wrapper is not acceptable.
27. If a new shared helper is needed, stop after the preview and wait for explicit approval before adding it.
28. Legacy naming conventions are canonical for runtime promotion; prefer legacy-style names over modernized variants.
29. Do not keep public/protected alias methods that only differ by casing/style of the same acronym (for example EFIN vs Efin).
30. Keep runtime split strict by default:

• UI locators remain in page/section classes
• policy/ownership/context logic remains in policy utility classes

31. Policy utility classes (for example EditPolicyUtils) must not host UI locator resolution by default.
32. Preserve page-facade delegation pattern when sections are split (page delegates field operations to owning section).
33. When a page header contains page-specific logic/actions, promote a dedicated <PageName>HeaderSection.
34. Keep the page object as facade and preserve backward-compatible public methods/getters via delegation to section classes.
35. Prefer direct imports by default. Do not create or update index.ts barrel files unless explicitly approved or the folder is an intentional public boundary.
36. Keep constructors lightweight for promoted runtime page objects and sections. Constructors should keep shared context and structural roots only. Prefer private locator getters for derived locators. Split into additional classes only when page size or domain separation materially improves readability and maintenance.
37. Before creating runtime structure, inspect for existing target folder stubs and surrounding page patterns.
38. If the target runtime folder already exists, promote into that folder instead of proposing a new layout.
39. If shared nav or route wiring already exists, add only the missing runtime pieces.
40. Prefer the smallest production-safe delta: missing URL constant, missing page class, reuse of existing helpers, and no proposal-only runtime support files unless needed.

Promotion Governance (Mandatory)

1. Scope: these conventions apply to proposal-to-runtime promotion, not to raw generator artifact emission.
2. Messages remain centralized (messages/<PageName>Messages.proposal.ts in proposal output; runtime message modules live under runtime_patterns.messages_root using the profile folder strategy).
3. No duplicate login runtime scaffold path is allowed; runtime_patterns.login_page_path remains the source of truth.
4. Tiny one-item nav contracts should be inlined/avoided at promotion time unless explicitly approved.
5. Flow classes are never promoted/generated without explicit user confirmation.
6. For touched runtime pages, prefer the shared helper declared by runtime_patterns.base_page_path and preserve the consumer repo's profile/env conventions.
7. Promotion must prefer existing runtime scaffolding before introducing new folders, classes, or support files.
8. If a new shared helper is required, promotion output must preview it explicitly and stop for approval instead of introducing a page-local wrapper.
9. The preview must include helper name, intended shared home, page-specific gap, and justification for why direct reuse of the helper declared by runtime_patterns.base_page_path is insufficient.
10. Example smallest-delta promotion path:

• existing target runtime folder stub
• existing shared navigation support for the page
• missing route constant
• missing runtime page class
• promotion result adds only the missing route constant and runtime page class unless broader runtime structure is explicitly required

Output

• Runtime-ready POM/message changes derived from approved proposal artifacts.
• Promotion governance pass/fail evidence with approval reference.
• Validation output (typecheck, playwright --list, and profile contract where applicable).

Validation

• npm run ui:inspect:profile:contract
• npm run typecheck
• npx playwright test --list

Completion Criteria

1. Public POM API produced from inspection has no placeholder-style names (mapped*, first*).
2. When runtime promotion is in scope, promotion governance conventions are evaluated and recorded as pass/fail with evidence.
3. When runtime promotion is in scope, any flow artifact creation has explicit approval reference.
4. When runtime promotion is in scope, one-item nav contract handling is explicitly documented (inlined or approved exception).
5. Section/page POMs remain thin (no duplicated click/visibility enforcement logic already provided by shared base helpers).
6. Promotion evidence includes BasePage-centralization review: interactions moved to BasePage/shared helpers and explicit exceptions list.
7. Promotion evidence includes naming guardrail review: no case-variant alias methods and canonical legacy acronym casing.
8. Promotion evidence confirms locator ownership stays in section/page classes and not in policy utils.
9. Promotion evidence confirms page-facade delegation remains intact after section split.
10. Promotion evidence confirms existing runtime scaffolding was inspected first and the smallest safe runtime delta was chosen.
11. Promotion evidence confirms no thin pass-through wrapper methods were introduced where direct BasePage or shared-helper reuse was sufficient.
12. When a new shared helper is needed, promotion evidence records the preview checkpoint and approval wait state instead of implementing a local wrapper.