40-agent-revision

All node tools/apexctl.mjs ... commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.

Agent 3 — Revision (Child Workflow)

Purpose

• Apply accepted review notes to produce the final APEXlang artifacts, enforce governance gates, and persist only compact runtime evidence when needed — with minimal token/context usage.

Inputs

• draft_path: path to the app file in the transient temp workspace outside the repo
• critique_path: internal review payload reference for the current run
• target_type
• output_path? (defaults per scope)
• app_root? (when Whole Application scope is active; e.g., applications/app_###/)
• server_side_condition? (structured object from master workflow)

<authority_rules>

• Shared prompt contract: references/workflows/apexlang/prompt-contracts.md
• Preserve its hierarchy, rule IDs, intermediate artifacts, and stop conditions while applying accepted fixes. </authority_rules>

<task_scope>

• Apply accepted critique notes only.
• Keep revision deterministic and avoid re-planning unless the critique explicitly requires a plan repair. </task_scope>

<generation_plan_contract>

• Preserve the frozen Generation Plan when applying accepted notes.
• If an accepted note changes a plan-level structural decision, record a Generation Plan Repair, update the relevant plan fields first, then reconcile the emitted artifact to that repaired plan.
• Do not finalize a revision that still violates GENERATION_PLAN_DRIFT_001. </generation_plan_contract>

<output_contract>

• Preserve or refresh compiler_truth_evidence when structural revisions change a compiler-justified decision.
• Keep revision output aligned with the same response-order contract used by Draft when an updated plan or evidence block must be emitted. </output_contract>

<stop_conditions>

• Follow RULES_FIRST_WORKFLOW_REQUIRED_001 and HUMAN_INTERVENTION_REQUIRED_001.
• If deterministic revision cannot satisfy the shared contract without inventing structure, keep finals blocked and record Missing Inputs instead of guessing. </stop_conditions>

Responsibilities (apply only accepted notes)

• Respect governance:
  • Reject any change conflicting with references/policies/memory-bank/00-guard/ai.guard.md or 10-global/apex.global.md.
  • Do not invent attributes or CSS classes; use templates/* only.
  • Reject finals that attempt to copy content or reusable patterns from applications/**; regenerate using the canonical template instead.
  • Preserve target-app reads only when they provide concrete integration facts such as existing ids, aliases, navigation entries, breadcrumb entries, or artifact paths.
  • Do not create unrelated helper source files for APEXlang generation tasks unless the user explicitly requested tooling or scripts.
• For dynamic-action revisions, follow references/domains/business-logic/dynamic-actions/workflow-dynamic-actions.md to maintain naming, template selection, and itemsToSubmit discipline. For batch runs, iterate through canonical targets (legacy target_pages allowed) and ensure each page’s identifiers (regions/items/buttons) are updated before writing finals.
• For batch revisions across all domains, normalize legacy inputs (target_pages, target_items, target_buttons, target_button, apply_to) to canonical targets, then apply deterministic per-target outcomes.
• For mixed translation/control prompts, do not finalize localization artifacts until runtime language switching versus text-message localization intent has been resolved.
• Page processes: use references/domains/business-logic/processes/workflow-page-processes-batch.md for invokeApi batches, updating each page’s button guards and parameter blocks accordingly.
• Application processes: enforce type: executeCode only and remove invokeApi usage from appProcess blocks.
• Item computations: leverage references/domains/business-logic/computations/workflow-computations-batch.md to apply template outputs per target item, retain only compact run evidence when needed, and convert logic to packaged APIs where recommended.
  • For translations, keep placeholders intact and use references/domains/shared-components/workflow-translations.md; for bundles, iterate via references/domains/shared-components/workflow-translations-batch.md, logging AI-assisted entries separately.
• For button batches, apply references/domains/page-components/buttons/workflow-button-batch.md, ensuring layout slots, action targets, nested trigger actions, and confirmations align with guardrails. Persist only compact run evidence when needed.
• For non-button batch domains (processes, computations, DA batches, translations, SSC/help-text), ensure compact run evidence includes operation, canonical targets, and per-target statuses before writing finals when the workflow explicitly persists logs.
• Deterministic button autofix: when critique reports a button-behavior policy rule violation, apply the JSON policy fix from assets/component-policies.json exactly. For BTN_RULE_001, remove warnOnUnsavedChanges whenever behavior.action: definedByDynamicAction.
• Deterministic button templateOptions autofix: when critique or runtime reports button template-option alias drift, preserve #DEFAULT#, keep multi-value arrays bracketed with one accepted value per line, and normalize aliases/naked suffixes to canonical emitted values from the button family contract. Normalize left|iconLeft|icon-left -> t-Button--iconLeft, right|iconRight|icon-right -> t-Button--iconRight, push|hoverIconPush|hover-icon-push -> t-Button--hoverIconPush, spin|hoverIconSpin|hover-icon-spin -> t-Button--hoverIconSpin, hide-icon-on-desktop|desktopHideIcon -> t-Button--desktopHideIcon, hide-label-on-mobile|mobileHideLabel -> t-Button--mobileHideLabel, primary -> t-Button--primary, simple -> t-Button--simple, tiny -> t-Button--tiny, stretch -> t-Button--stretch, pillStart|pill-start -> t-Button--pillStart, padLeft|pad-left -> t-Button--padLeft, gapRight|gap-right -> t-Button--gapRight, padTop|pad-top -> t-Button--padTop, gapBottom|gap-bottom -> t-Button--gapBottom, link -> t-Button--link, success -> t-Button--success, and noUI|no-ui -> t-Button--noUI.
• Deterministic display-only autofix:
  • For pageItem with type: displayOnly, remove unsupported appearance.width and appearance.height.
  • Ensure settings.sendOnPageSubmit: false exists; insert settings { sendOnPageSubmit: false } when missing or normalize value when not false.
  • Keep all other display-only attributes unchanged unless critique explicitly requests additional revisions.
• Deterministic master-detail Content Row autofix:
  • For CONTENT_ROW_SETTINGS_SUBSTITUTION_REQUIRED_001, rewrite Content Row settings.overline, settings.title, settings.description, and settings.miscellaneous column mappings from bare aliases to &COLUMN_NAME. substitutions, but leave literal values such as overline: Employee unchanged.
  • For CONTENT_ROW_SELECTION_ITEMS_REQUIRED_001, add or fix native Content Row selection items. For focusOnly, emit only rowSelection { type: focusOnly } and remove selection page-item references. For singleSelection, emit rowSelection { type: singleSelection currentSelectionPageItem: Pn_SELECTED_KEY } and create the same-page hidden item. For multipleSelection, emit rowSelection { type: multipleSelection currentSelectionPageItem: Pn_SELECTED_KEYS selectAllPageItem: Pn_SELECT_ALL }, create the same-page hidden current-selection item, and create the same-page select-all checkbox item.
  • For MASTER_DETAIL_CONTENT_ROW_ACTION_REQUIRED_001, add or fix a report-mode Content Row action ... ( with position: fullRowLink and a structured same-page target that sets the hidden context item from the parent PK using &COLUMN. substitution. Do not accept native rowSelection.currentSelectionPageItem as sufficient for master-detail context setting.
  • For MASTER_DETAIL_VISIBLE_SELECTOR_REGRESSION_001, convert the visible parent select-list selector into a protected hidden context item unless the user explicitly requested manual selection.
  • For MASTER_DETAIL_CHILD_BIND_SUBMIT_REQUIRED_001 or IR_CONTEXT_BIND_SUBMIT_REQUIRED_001, add every same-page item referenced by child Interactive Report SQL binds to source.pageItemsToSubmit.
  • For MASTER_DETAIL_TOOLBAR_ACTIONS_REQUIRED_001, move child create/edit/detail buttons into the child Interactive Report scope using layout.region: @<child-report-static-id> and slot: rightOfInteractiveReportSearchBar.
  • For MASTER_DETAIL_LAYOUT_REQUIRED_001, use the master-detail Content Row layout recipe: parent Content Row first with columnSpan: 3 or 4, child report second with startNewRow: false, and remove redundant child column / columnSpan unless the validated contract requires them.
  • For IR_PROJECTED_COLUMNS_REQUIRED_001, add missing Interactive Report column (...) definitions for every SQL projection using interactive-report._columns._common.md; preserve numeric end alignment and required headings.
• Deterministic layout autofix:
  • Apply these fixes to generated application artifacts before final validation; app output is not a layout-lint bypass.
  • Apply layout fixes per local scope: page slot rows, nested parentRegion rows, item rows by layout.region + layout.slot, and button rows by layout.region + layout.slot.
  • For equal-width sibling rows, remove layout.column and layout.columnSpan.
  • Ensure the first component in an equal-width row omits layout.startNewRow.
  • Ensure second-and-later equal-width siblings set layout.startNewRow: false.
  • Do not alter intentionally asymmetric rows such as sidebar-main, faceted-search, or parent-child split layouts.
  • Finals:
  • Write revised .apx outputs only to the transient temp app:
    • Pages → temp {output_path}/pages/ or {app_root}/pages/
    • Shared components → temp {output_path}/shared-components/ or {app_root}/shared-components/
  • Publish into applications/<target-app>/... only after the resolved live runtime action succeeds.
• Compact run evidence:
  • Persist a concise list of applied/rejected/deferred notes only when the workflow explicitly stores durable evidence under the temp-runtime logs directory under APEXLANG_OUTPUT_ROOT/logs/``.
  • Preserve compiler-truth-report.json for generated or revised .apx artifacts and block completion when the report is missing or failing.
  • Preserve validation-report.json, validation-transcript.log, problems.json, and component-contracts/<build>.json from runtime validate. Apply fixes only for reported validation problems, then rerun runtime validate until live/compiler evidence and VSCode Problems evidence pass.
  • Resolve or explicitly defer parallel-skill contradictions recorded by critique; unresolved conflicts must remain as Missing Inputs.