mustflow 2.29.0 → 2.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.29.0",
+  "version": "2.30.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/templates/default/common/.mustflow/config/preferences.toml

@@ -83,8 +83,8 @@ source = "git.commit_message"
 [release.versioning]
 impact_check = true
 suggest_bump = true
-auto_bump = false
-require_user_confirmation = true
+auto_bump = true
+require_user_confirmation = false
 sync_template_version = true
 sync_docs_examples = true
 sync_tests = true

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 94
+revision = 95
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -613,7 +613,7 @@ translations = {}
 [documents."skill.ui-quality-gate"]
 source = "locales/en/.mustflow/skills/ui-quality-gate/SKILL.md"
 source_locale = "en"
-revision = 6
+revision = 7
 translations = {}
 
 [documents."skill.visual-review-artifact"]

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 94
+revision: 95
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -199,7 +199,7 @@ routes. Event routes stay inactive until their event occurs.
 | Generated artifacts, packaged files, binary assets, reports, or downloadable outputs are created, referenced, or reported | `.mustflow/skills/artifact-integrity-check/SKILL.md` | Artifact paths, source or generation path, package rules, and artifact expectations | Artifact references, package metadata, tests, and documentation | unverified or stale artifact claim | `changes_status`, `changes_diff_summary`, `test_release`, `build`, `mustflow_check` | Artifact evidence, inclusion or format checks, skipped checks, and integrity risk |
 | A dense plan, suggestion, code explanation, review result, flow map, or decision set would be easier to inspect as a safe static HTML review artifact | `.mustflow/skills/visual-review-artifact/SKILL.md` | User request, artifact goal, target audience, source evidence, output path, and relevant command contract entries | Temporary `.mustflow/state/artifacts/**` output or explicitly requested versioned HTML artifact, plus direct references, docs, or package metadata | unsafe HTML behavior, prompt injection, unverified artifact claim, or mistaken approval authority | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Artifact kind and path, source evidence, review-only boundary, local interactions, verification, skipped checks, and remaining decision risk |
 | Conversational AI, chat, copilot, prompt, multimodal input, streaming generation, citation, feedback, or conversation-history UI is planned, edited, reviewed, or reported | `.mustflow/skills/llm-service-ux-review/SKILL.md` | LLM service surface, user task, interaction mode, input-to-reset path, latency/source/privacy constraints, and command contract entries | Prompt, attachment, generation, output, citation, feedback, history, reset, error, accessibility, docs, templates, and reports | loss of user control, fake progress, unverifiable source claims, hidden privacy risk, decorative prompt UX, or unverified visual claim | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | LLM UX surface reviewed, input/waiting/output/recovery states checked, control and citation boundaries, skipped checks, and remaining LLM UX risk |
-| User-facing UI, dashboard, settings, navigation, form, copy, responsive layout, accessibility, or visual state changes are planned, edited, reviewed, or reported | `.mustflow/skills/ui-quality-gate/SKILL.md` | Changed UI surface, user task, interaction path, existing patterns, state combinations, localization rules, and command contract entries | UI controls, labels, states, layout constraints, accessibility attributes, localization hooks, docs, templates, and reports | decorative UI drift, inaccessible controls, layout breakage, or unverified visual claim | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | UI surface reviewed, states checked, layout/accessibility/localization notes, skipped visual checks, and remaining UI risk |
+| User-facing UI, dashboard, settings, navigation, form, copy, responsive layout, accessibility, visual geometry, interaction flow, or visual state changes are planned, edited, reviewed, or reported | `.mustflow/skills/ui-quality-gate/SKILL.md` | Changed UI surface, user task, interaction path, existing patterns, state combinations, localization rules, content stress cases, geometry-sensitive component facts, and command contract entries | UI controls, labels, states, layout constraints, geometry contracts, accessibility attributes, localization hooks, task-flow recovery, docs, templates, and reports | decorative UI drift, inaccessible controls, icon/text misalignment, overflow or layout breakage, missing empty/error/permission recovery, or unverified visual claim | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | UI surface reviewed, states checked, geometry/layout/accessibility/localization/recovery notes, skipped visual checks, and remaining UI risk |
 | HTML, templates, component markup, forms, controls, dialogs, navigation, tables, media, metadata, SEO head content, or structured data are created or changed | `.mustflow/skills/html-code-change/SKILL.md` | Page shell, markup patterns, form/control components, metadata source, changed files, and command contract entries | HTML and template markup, metadata, forms, interactive controls, tests, and docs examples | invalid semantics, inaccessible control, broken focus path, metadata drift, or invalid browser markup | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Semantic, form, focus, metadata, and validation boundary checked, verification, and remaining HTML risk |
 | CSS, Sass, Less, CSS Modules, CSS-in-JS, global styles, design tokens, layout, responsive behavior, focus styles, animation, color, or component styling are created or changed | `.mustflow/skills/css-code-change/SKILL.md` | Global CSS, tokens, component styles, parent layout, browser targets, changed files, and command contract entries | CSS, design tokens, component styles, responsive rules, tests, and docs examples | specificity escalation, token bypass, contrast failure, motion issue, layout shift, or browser incompatibility | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Cascade, token, responsive, accessibility, and layout-stability boundary checked, verification, and remaining CSS risk |
 | Tailwind classes, class composition, theme tokens, variants, arbitrary values, Tailwind config, `@theme`, `@apply`, or migration surfaces are created or changed | `.mustflow/skills/tailwind-code-change/SKILL.md` | Tailwind config or CSS entry, source scanning rules, theme tokens, class helpers, changed files, and command contract entries | Tailwind config, theme tokens, utility classes, component class maps, tests, and docs examples | production class loss, arbitrary-value sprawl, token bypass, weak focus state, or hidden `@apply` drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Class detection, token, responsive, state, and production CSS boundary checked, verification, and remaining Tailwind risk |

package/templates/default/locales/en/.mustflow/skills/ui-quality-gate/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.ui-quality-gate
 locale: en
 canonical: true
-revision: 6
+revision: 7
 lifecycle: mustflow-owned
 authority: procedure
 name: ui-quality-gate
-description: Apply this skill when user-facing UI, dashboard, settings, navigation, form, copy, responsive layout, accessibility, or visual state changes are planned, edited, reviewed, or reported.
+description: Apply this skill when user-facing UI, dashboard, settings, navigation, form, copy, responsive layout, accessibility, visual geometry, interaction flow, or visual state changes are planned, edited, reviewed, or reported.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -34,6 +34,8 @@ Keep user-facing interfaces usable, minimal, accessible, responsive, localizatio
 - A task asks for UI polish, layout, responsive behavior, accessibility, visual states, language switching, labels, or interaction feedback.
 - A report claims that UI text fits, controls are understandable, language updates apply, or a page renders correctly.
 - A change could add explanatory, marketing-like, decorative, duplicate, invented, or non-actionable UI content.
+- A change touches icon and text alignment, button/input sizing, badges, skeletons, tables, dialogs, drawers, dropdowns, popovers, toasts, command palettes, or other compound UI primitives.
+- A change affects search, filters, sorting, pagination, dirty state, autosave, undo, archive, destructive actions, permission states, onboarding, billing or quota states, import/export, upload, or other task-flow recovery paths.
 - AI-generated or vibe-coded UI needs review for predictable conventions, visual hierarchy, mobile usability, touch targets, component boundaries, and interaction feedback.
 - A repeated AI-editing loop may have introduced style drift, duplicated state, missing edge cases, undeclared UI dependencies, or oversized components.
 
@@ -53,6 +55,8 @@ Keep user-facing interfaces usable, minimal, accessible, responsive, localizatio
 - Viewports, themes, languages, and state combinations that need inspection.
 - The target devices and interaction style, including mobile-first behavior, pointer or touch input, expected keyboard use, and any project breakpoint or design-token conventions.
 - Existing design-token, component, data, state, dependency, and accessibility contracts that the changed UI must preserve.
+- Content and data stress cases: empty, one, many, long labels, long URLs, long file names, translated text, large counts, missing images, slow network, stale data, permission denial, quota limits, partial failure, and retry behavior.
+- Geometry-sensitive component facts: icon source, viewBox or glyph set, text line-height, component height and padding, truncation owner, flex or grid constraints, hit target size, focus ring space, and parent overflow or stacking context.
 - Any high-risk widget involved, such as toast notifications, tree views, editable grids, drag-and-drop, custom selects, comboboxes, dialogs, or virtualized lists.
 - Performance, asset-size, animation, or network constraints that affect the changed surface.
 - Relevant command-intent contract entries for status, diff, docs, build, release, or mustflow validation.
@@ -82,32 +86,35 @@ Keep user-facing interfaces usable, minimal, accessible, responsive, localizatio
 2. Check nearby UI patterns before adding new layout, component, color, copy, or state conventions.
 3. Keep task-essential controls only. Remove or avoid non-essential welcome text, feature summaries, decorative cards, fake metrics, marketing copy, invented filters, and controls that do not operate on real data.
 4. Check predictability and visual hierarchy. Follow familiar platform or product conventions, make the next likely action visible, and use spacing, size, weight, grouping, and order to make the primary task easier to scan.
-5. Check responsive and touch ergonomics. Prefer mobile-first layout decisions, preserve readable spacing at small widths, keep touch targets and gaps usable, and follow existing breakpoint or design-token conventions instead of inventing one-off sizes.
-6. Verify controls are understandable and state-aware: icon buttons need accessible names or tooltips, destructive or state-changing actions need clear labels, hover, active, selected, loading, and disabled states need clear visual treatment, and disabled states need a visible reason when useful.
-7. Check keyboard and focus behavior before visual polish: native elements first, semantic landmarks when they clarify page structure, tab order, focus order and return, visible focus state, names for icon-only controls, form error linkage, live status announcements, reduced-motion handling, and sufficient contrast.
-8. Check accessible names and states against the actual interaction model, not only the rendered text. Dynamic controls must expose the current expanded, selected, checked, invalid, busy, or disabled state when applicable.
-9. Check form validation, error, and empty-state behavior. Validate close to the field when useful, place errors next to the action or input that needs attention, preserve user input after failure, and keep empty states short and action-oriented rather than explaining the product.
-10. Check interaction feedback. Loading, skeleton, saving, success, failure, toast, inline message, or micro-interaction feedback should map to real state and should not distract from the task or hide a slow operation.
-11. Check localization-safe labels: language switching, fallback text, placeholders, plural or formatted values, long translated labels, bidirectional text, logical spacing, and date, time, number, currency, or unit display where applicable.
-12. Check responsive layout without text overlap: text should not overflow, clip, overlap, resize fixed-format controls unexpectedly, or depend on viewport-width font scaling.
-13. Check style drift. Repeated AI edits should not create one-off spacing, color, radius, typography, shadow, or inline-style variants when an existing token, utility, or component variant already covers the need.
-14. Check state architecture. Async UI should cover the relevant idle, loading, success, empty, error, retrying, and stale-data states without duplicating state variables or leaving race-prone updates after unmount.
-15. Check component boundaries. Reusable UI pieces should be small enough to maintain consistent states and accessibility, but not split into wrappers that obscure the user task or duplicate design rules.
-16. Check dependency and API reality. Imported UI packages, generated helpers, component props, browser APIs, and event contracts must exist in the project or be handled through the dependency workflow before code relies on them.
-17. Check high-risk widgets. Toasts need pauseable timing and appropriate status announcements; tree views need composite keyboard behavior; editable grids need navigation and editing modes; custom selects, dialogs, and comboboxes need proven accessibility patterns or an existing library.
-18. Check performance and asset-size awareness when the change adds images, icons, animation, third-party UI code, large client data, or extra network work. Prefer existing assets, lazy loading when appropriate, explicit image dimensions, and bounded rendering cost.
-19. Check state coverage: loading, empty, error, saved, changed, disabled, selected, focused, hover, active, validating, and language-switched states should update consistently where applicable.
-20. For complex surfaces, write or confirm a compact UI contract before broad implementation: view tree, data contract, interaction model, state model, design-token contract, and verification targets.
-21. Inspect responsive and localization-sensitive surfaces when the change affects layout or translated text.
-22. Use visual verification only when a configured one-shot command or approved browser workflow exists for the surface. Do not start development servers, watchers, or browser sessions directly from the skill.
-23. Run the narrowest configured verification that covers the changed UI, documentation, package, or mustflow contract.
+5. Check responsive and touch ergonomics. Prefer mobile-first layout decisions, preserve readable spacing at small widths, keep visible icon size separate from touch target size, and follow existing breakpoint, safe-area, keyboard, or design-token conventions instead of inventing one-off sizes.
+6. Check visual geometry before assuming flex alignment is enough. For icon/text, badge, tab, breadcrumb, list-row, alert, avatar, input-adornment, and button content, verify wrapper size, intrinsic SVG or glyph box, `currentColor`, line-height, height and padding compatibility, shrink behavior, selection-icon space, focus-ring space, and whether single-line content should center while multi-line content should align near the first line.
+7. Check overflow and stable dimensions. Long names, translated labels, URLs, code, counts, and file names need an owning width, `min-width: 0` or equivalent flex/grid constraint, truncation or wrapping policy, reserved loading and error space where needed, and fixed-format controls that do not resize or shift when hover, active, selected, loading, or error content appears.
+8. Verify controls are understandable and state-aware: icon buttons need accessible names or tooltips, destructive or state-changing actions need clear labels, hover, active, selected, loading, and disabled states need clear visual treatment, and disabled states need a visible reason when useful.
+9. Check keyboard and focus behavior before visual polish: native elements first, semantic landmarks when they clarify page structure, tab order, focus order and return, visible focus state, names for icon-only controls, form error linkage, live status announcements, reduced-motion handling, and sufficient contrast.
+10. Check accessible names and states against the actual interaction model, not only the rendered text. Dynamic controls must expose the current expanded, selected, checked, invalid, busy, or disabled state when applicable.
+11. Check form validation, error, and empty-state behavior. Keep labels separate from placeholders, validate close to the field when useful, place errors next to the action or input that needs attention, preserve user input after failure, link errors to controls, and distinguish first-use empty, filtered empty, search empty, permission denied, quota, loading, and failed states.
+12. Check task-flow recovery. Search, filters, sorting, pagination, tabs, modals, drawers, edit mode, dirty state, autosave, optimistic updates, undo, archive, trash, destructive actions, import/export, upload, and onboarding should make the current state visible, preserve or intentionally reset URL/shareable state, prevent duplicate or stale actions, and offer the next useful recovery action when something fails.
+13. Check interaction feedback. Loading, skeleton, saving, success, failure, toast, inline message, or micro-interaction feedback should map to real state, reserve final layout size when practical, avoid unnecessary toast spam, announce important status changes, and should not distract from the task or hide a slow operation.
+14. Check localization-safe labels: language switching, fallback text, placeholders, plural or formatted values, long translated labels, bidirectional text, logical spacing, and date, time, number, currency, or unit display where applicable.
+15. Check responsive layout without text overlap: text should not overflow, clip, overlap, resize fixed-format controls unexpectedly, or depend on viewport-width font scaling.
+16. Check style drift. Repeated AI edits should not create one-off spacing, color, radius, typography, shadow, z-index, transition, animation, or inline-style variants when an existing token, utility, or component variant already covers the need.
+17. Check state architecture. Async UI should cover the relevant idle, loading, success, empty, error, retrying, stale-data, permission, read-only, changed, saved, conflict, partial-success, and quota states without duplicating state variables or leaving race-prone updates after unmount.
+18. Check component boundaries. Reusable UI pieces should be small enough to maintain consistent states, geometry, and accessibility, but not split into wrappers that obscure the user task or duplicate design rules.
+19. Check dependency and API reality. Imported UI packages, generated helpers, component props, browser APIs, and event contracts must exist in the project or be handled through the dependency workflow before code relies on them.
+20. Check high-risk widgets. Toasts need placement, stacking, pauseable timing, and appropriate status announcements; dropdowns and popovers need collision and overflow handling; dialogs and drawers need focus trap, close behavior, scroll locking, and mobile layout; custom selects, comboboxes, command palettes, trees, editable grids, and virtualized lists need proven accessibility and keyboard patterns or an existing library.
+21. Check performance and asset-size awareness when the change adds images, icons, animation, third-party UI code, large client data, long lists, charts, maps, canvas, or extra network work. Prefer existing assets, lazy loading when appropriate, explicit image dimensions, bounded rendering cost, and virtualization only when dynamic-height behavior is understood.
+22. Check state coverage: loading, empty, error, saved, changed, disabled, selected, focused, hover, active, validating, permission denied, read-only, quota, stale, conflict, language-switched, and mobile states should update consistently where applicable.
+23. For complex surfaces, write or confirm a compact UI contract before broad implementation: view tree, data contract, interaction model, state model, geometry contract, design-token contract, and verification targets.
+24. Inspect responsive and localization-sensitive surfaces when the change affects layout or translated text.
+25. Use visual verification only when a configured one-shot command or approved browser workflow exists for the surface. Do not start development servers, watchers, or browser sessions directly from the skill.
+26. Run the narrowest configured verification that covers the changed UI, documentation, package, or mustflow contract.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - The UI supports the user's task without unnecessary explanatory or decorative surface.
-- Important controls, labels, states, visual hierarchy, touch ergonomics, keyboard and focus paths, layout constraints, localization updates, and performance-sensitive assets are checked or reported as unverified.
-- AI-generated changes preserve existing style tokens, component boundaries, state contracts, dependency reality, and high-risk widget accessibility expectations.
+- Important controls, labels, states, visual hierarchy, visual geometry, touch ergonomics, keyboard and focus paths, layout constraints, localization updates, recovery paths, and performance-sensitive assets are checked or reported as unverified.
+- AI-generated changes preserve existing style tokens, component boundaries, geometry contracts, state contracts, dependency reality, and high-risk widget accessibility expectations.
 - Final reports distinguish code-level verification from visual or interactive verification.
 
 <!-- mustflow-section: verification -->
@@ -128,6 +135,8 @@ Use a narrower configured test, build, browser, screenshot, or accessibility int
 
 - If visual inspection is unavailable, report the unverified viewport, state, or interaction instead of assuming it works.
 - If UI text overlaps, clips, or fails to update after a state or language change, fix the smallest owning component before adding broader layout changes.
+- If icon/text alignment, button sizing, input adornments, badges, or row layouts look off, inspect the wrapper, intrinsic icon box, line-height, hit target, parent width, and overflow owner before adding offset hacks.
+- If empty, error, permission, quota, dirty, or destructive-action states collapse into the same generic message, split them by user next action before polishing copy.
 - If controls lack accessible names and states, fix the control contract before polishing color, spacing, or animation.
 - If a change adds large media, animation, or third-party UI code, verify the performance and asset-size impact or report the gap.
 - If a requested UI element conflicts with repository UI minimalism rules, implement the smallest task-focused control and report the omitted decorative content.
@@ -139,8 +148,8 @@ Use a narrower configured test, build, browser, screenshot, or accessibility int
 - UI surface reviewed
 - User task and states checked
 - Task-essential controls kept or removed
-- Visual hierarchy, responsive layout, touch ergonomics, keyboard and focus, accessibility, localization, performance, and asset-size checks
-- Interaction feedback, style drift, state architecture, dependency, high-risk widget, and component-boundary checks
+- Visual hierarchy, visual geometry, responsive layout, touch ergonomics, keyboard and focus, accessibility, localization, performance, and asset-size checks
+- Interaction feedback, recovery path, overflow, style drift, state architecture, dependency, high-risk widget, and component-boundary checks
 - Decorative or unnecessary UI avoided or removed
 - Command intents run
 - Skipped visual checks and reasons

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.29.0"
+version = "2.30.0"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"