mustflow 2.99.2 → 2.103.3

package/templates/default/locales/en/.mustflow/skills/css-code-change/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.css-code-change
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: css-code-change
@@ -47,8 +47,10 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 
 - Global CSS entrypoints, reset/base styles, cascade layer strategy, token files, theme config, component CSS, parent layout styles, browserslist, build config, and style lint config.
 - Existing responsive, dark mode, accessibility, focus, reduced-motion, breakpoint, and design-token conventions.
+- Theme and token graph: raw palette tokens, semantic role tokens, component tokens, theme axes, user override state, system preference handling, forced-colors policy, and generated platform token outputs when present.
 - Target surfaces for narrow viewports, 200% zoom, text scaling, delayed media, third-party markup, and browser compatibility.
 - Browser-native capabilities in use or available for the target: cascade layers, `:where`, `:is`, `:has`, container queries, logical properties, `dvh`/`svh`/`lvh`, `color-scheme`, `content-visibility`, `contain-intrinsic-size`, `text-wrap`, and view-transition styling.
+- Motion and transition capabilities in use or available for the target: `@starting-style`, `transition-behavior`, individual transform properties, `@property`, scroll-driven animation, reduced motion, and `will-change` policy.
 - Configured verification intents.
 
 <!-- mustflow-section: preconditions -->
@@ -72,29 +74,40 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 
 1. Read global style entrypoints, tokens, component styles, parent layout styles, and build/lint config.
 2. Map the cascade: reset, base, tokens, layout, components, utilities, overrides.
-3. Do not patch visible symptoms with stronger specificity. Resolve conflicts by checking layer order, import order, token choice, component boundary, parent layout, and selector scope first.
-4. Do not add ID selectors for styling, selectors with more than two combinators, or new `!important` unless an allowed exception is documented.
-5. Do not use negative margin to repair normal content flow. Fix parent layout, spacing, alignment, or intrinsic sizing instead.
-6. Do not add inline styles for color, spacing, typography, focus, dark mode, or responsive layout. Inline styles are for runtime geometry such as drag positions, virtualized offsets, and measured canvas/SVG values.
-7. Use existing color, spacing, font, radius, shadow, z-index, and breakpoint tokens before adding literals.
-8. Keep raw color values out of component CSS. Add or reuse semantic tokens for surfaces, text, borders, actions, danger states, focus, disabled states, and dark mode.
-9. Avoid raw pixel values for typography, spacing, layout dimensions, and radius. Allow narrow values such as one-pixel borders, intrinsic icon/media dimensions, and established breakpoint tokens.
-10. Make layout responsive through constraints, `min-width: 0`, `min-height: 0`, min/max sizing, flex/grid, wrapping, gap, intrinsic media dimensions, container/media queries, logical properties, and content-based rules rather than fixed viewport assumptions.
-11. Prefer named containers and container queries when a component responds to its actual slot, not the whole viewport. Keep media queries for page-level viewport decisions.
-12. Do not set fixed width on page, section, container, card, modal, or form layouts. Do not set fixed height on components that contain text.
-13. Use dynamic viewport units intentionally: `dvh` for current viewport height, `svh` for stable small viewport layout, and `lvh` only when the larger viewport behavior is intended. Avoid hard `100vh` for mobile app shells unless the target proves safe.
-14. Do not use viewport-only typography. Use bounded responsive type patterns that survive small screens and large displays.
-15. Do not use `overflow: hidden` to hide layout bugs. Allow it only for intentional clipping such as avatars, media crops, masks, or animation containers.
-16. Reserve dimensions or aspect ratio for images, videos, iframes, ads, embeds, skeletons, fonts, and lazy content that could cause layout shift.
-17. Prefer `:where` to keep wrapper and rich-text selector specificity low. Use `:has` only when it improves state ownership and the fallback remains usable for target browsers.
-18. Use `content-visibility` only for offscreen or below-the-fold content whose skipped rendering will not hide focus targets, search-relevant initial content, or accessibility-critical relationships. Pair it with `contain-intrinsic-size` to avoid layout jumps.
-19. Use `color-scheme` with theme tokens so native controls, scrollbars, and form UI match the active theme before component JavaScript runs.
-20. Preserve visible focus, sufficient contrast, 200% text resize behavior, text-spacing stress, keyboard navigation, and reduced-motion behavior.
-21. If hover styling changes an interactive affordance, provide a matching focus-visible affordance.
-22. Prefer outline and outline-offset for focus indicators. Do not rely only on shadows when ancestors may clip overflow.
-23. Respect reduced motion for parallax, large transforms, auto-scroll, route transitions, autoplay carousels, skeleton shimmer, and looping decorative animation.
-24. Check browser compatibility before adding new CSS features. Use progressive enhancement for newly available features and avoid limited-availability features unless the project browser target allows them.
-25. Choose configured verification intents that cover style lint, build, visual states, accessibility, and browser target risk when available.
+3. Debug cascade before selector strength. Resolve conflicts by checking origin, importance, layer order, unlayered rules, selector specificity, `@scope` proximity, source order, import order, token choice, component boundary, parent layout, and selector scope first.
+4. Treat `@layer` as an ordering contract. Put reset, vendor, design-system, component, utility, and override CSS into intentional layers; do not migrate only one part of a stylesheet into layers when unlayered legacy CSS would silently beat it.
+5. Remember that `!important` reverses layer priority. Do not add important declarations until the layer model and exception reason are clear.
+6. Do not add ID selectors for styling, selectors with more than two combinators, or new `!important` unless an allowed exception is documented.
+7. Do not use negative margin to repair normal content flow. Fix parent layout, spacing, alignment, or intrinsic sizing instead.
+8. Do not add inline styles for color, spacing, typography, focus, dark mode, or responsive layout. Inline styles are for runtime geometry such as drag positions, virtualized offsets, and measured canvas/SVG values.
+9. Use existing color, spacing, font, radius, shadow, z-index, and breakpoint tokens before adding literals.
+10. Keep raw color values out of component CSS. Add or reuse semantic tokens for surfaces, text, borders, actions, danger states, focus, disabled states, and dark mode.
+11. Avoid raw pixel values for typography, spacing, layout dimensions, and radius. Allow narrow values such as one-pixel borders, intrinsic icon/media dimensions, and established breakpoint tokens.
+12. Make layout responsive through constraints, `min-width: 0`, `min-height: 0`, min/max sizing, flex/grid, wrapping, gap, intrinsic media dimensions, container/media queries, logical properties, and content-based rules rather than fixed viewport assumptions.
+13. Use `flex: 1 1 0` plus `min-width: 0` when equal columns must actually shrink. Use `minmax(0, 1fr)` for grid tracks that must not be held open by long content.
+14. Prefer named containers and container queries when a component responds to its actual slot, not the whole viewport. Keep media queries for page-level viewport decisions.
+15. Remember that container queries style descendants, not the queried container itself. Do not add `container-type: size` without checking that size containment will not collapse an element that depends on its children for size.
+16. Do not set fixed width on page, section, container, card, modal, or form layouts. Do not set fixed height on components that contain text.
+17. Use dynamic viewport units intentionally: `dvh` for current viewport height, `svh` for stable small viewport layout, and `lvh` only when the larger viewport behavior is intended. Avoid hard `100vh` for mobile app shells unless the target proves safe.
+18. Do not use viewport-only typography. Use bounded responsive type patterns that survive small screens and large displays.
+19. Do not use `overflow: hidden` to hide layout bugs. Allow it only for intentional clipping such as avatars, media crops, masks, or animation containers.
+20. Check containing blocks and stacking contexts before increasing z-index. `position`, `transform`, `opacity`, `filter`, `contain`, `container-type`, and overflow ancestors can change sticky behavior, absolute positioning, clipping, and overlay ordering.
+21. Prefer `gap` inside flex or grid stacks instead of vertical margin choreography when margin collapse could make spacing ambiguous.
+22. Ensure shared UI reset or base CSS uses `box-sizing: border-box` unless the project intentionally preserves content-box sizing.
+23. Reserve dimensions or aspect ratio for images, videos, iframes, ads, embeds, skeletons, fonts, and lazy content that could cause layout shift.
+24. Prefer `:where` to keep wrapper and rich-text selector specificity low. Use `:is`, `:not`, `:has`, and native nesting only after checking the highest selector in the list will not smuggle in unwanted specificity.
+25. Keep `:has` anchored to a narrow owner such as a component root and narrow the inner selector with child or sibling combinators when possible. Avoid `body:has(...)`, `:root:has(...)`, or `*:has(...)` unless the broad invalidation cost and fallback are explicitly accepted.
+26. Use `content-visibility` only for offscreen or below-the-fold content whose skipped rendering will not hide focus targets, search-relevant initial content, or accessibility-critical relationships. Pair it with `contain-intrinsic-size` to avoid layout jumps.
+27. Use `color-scheme` with theme tokens so native controls, scrollbars, and form UI match the active theme before component JavaScript runs. Do not treat `color-scheme` as a replacement for actual page background, text, surface, and border tokens.
+28. Preserve visible focus, sufficient contrast, 200% text resize behavior, text-spacing stress, keyboard navigation, and reduced-motion behavior.
+29. If hover styling changes an interactive affordance, provide a matching focus-visible affordance.
+30. Prefer outline and outline-offset for focus indicators. Do not rely only on shadows when ancestors may clip overflow or forced-colors mode may remove shadows.
+31. Respect reduced motion for parallax, large transforms, auto-scroll, route transitions, autoplay carousels, skeleton shimmer, and looping decorative animation.
+32. Animate `transform`, individual transform properties, and `opacity` before layout-affecting properties. Avoid `transition: all`.
+33. Use newer transition and animation features such as `@starting-style`, `transition-behavior`, intrinsic-size interpolation, `@property`, individual transforms, scroll timelines, and animation composition only with browser-target review and a safe fallback.
+34. Keep `will-change` narrow, temporary, and evidence-backed. Do not leave broad permanent compositor hints on ordinary components.
+35. Check browser compatibility before adding new CSS features. Use progressive enhancement for newly available features and avoid limited-availability features unless the project browser target allows them.
+36. Choose configured verification intents that cover style lint, build, visual states, accessibility, and browser target risk when available.
 
 <!-- mustflow-section: cascade-specificity-policy -->
 ## Cascade And Specificity Policy
@@ -104,6 +117,11 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 - Do not write DOM-path selectors that break when markup gains or loses a wrapper.
 - Use low-specificity contextual selectors for rich text or CMS areas. Prefer patterns that keep specificity easy to override.
 - Use `:where` for low-specificity grouping and `@layer` for order. Do not use `:is` or `:has` to smuggle in heavy selectors when a class boundary would be clearer.
+- Keep third-party, reset, and vendor CSS in lower layers when possible. Do not assume a high-specificity vendor selector beats a lower-specificity app selector in a later layer.
+- Treat unlayered CSS as a migration hazard because normal unlayered declarations outrank normal layered declarations.
+- Do not mix ID selectors into a shared `:is`, `:not`, `:has`, or nested selector list unless every generated selector is intended to carry that specificity.
+- Use `[id="..."]` instead of `#id` only when a real ID anchor must be selected without ID specificity, and document the reason.
+- Treat `@scope` proximity as part of conflict analysis when scoped rules with equal weight compete.
 - Do not add global overrides for local component problems when component-scoped styling or tokens can solve the issue.
 - New `!important` requires an explicit exception for immutable third-party/legacy markup, third-party inline style override, urgent accessibility protection, or equivalent narrow reason.
 
@@ -117,17 +135,45 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 - Avoid `100vw` except for deliberate full-bleed designs; otherwise prefer normal containing-block width.
 - Avoid `100vh` for mobile app shells when browser chrome can change the visual viewport. Choose `dvh`, `svh`, or a layout-owned min-height intentionally.
 - Avoid absolute positioning for normal document flow. Use it only for overlays, decorative placement, controls anchored to known boxes, or measured geometry.
+- Check sticky positioning against overflow ancestors and required inset values before changing z-index or position.
+- Check absolute positioning against the nearest positioned ancestor before changing coordinates.
+- Prefer logical properties such as `inline-size`, `block-size`, `padding-inline`, `margin-block`, and `inset-inline-end` for component CSS that should survive RTL or alternate writing modes.
 
 <!-- mustflow-section: token-accessibility-policy -->
 ## Token And Accessibility Policy
 
 - Name visual values by role, not by raw color or numeric value.
+- Keep the token graph layered as palette or raw values, semantic role tokens, then component tokens. Components should not consume raw palette values when the value carries theme, brand, contrast, or state meaning.
+- Do not encode `light` or `dark` into the core token name when theme mode is an axis that should select the value. Prefer stable role names whose values vary by theme, brand, density, or contrast mode.
+- Treat `prefers-color-scheme` as the system default only. If the product has an app theme setting, model `system`, explicit light, and explicit dark so user choice can override the OS preference.
+- Treat `forced-colors` and high-contrast modes as separate accessibility modes, not as darker dark mode. Use system colors, borders, and outlines where shadows or brand colors may be ignored.
 - Search existing tokens before adding a value. If a new value has product meaning, theme impact, repeated use, or dark-mode behavior, add it at the token source.
+- Review token aliases for cycles, stale references, and source-to-generated drift before adding derived tokens.
+- Scope global custom properties to product-wide contracts and component custom properties to component roots. Do not dump one-off component internals into `:root`.
+- Use `@property` only for runtime tokens that benefit from typed validation, inheritance control, or animation; avoid registering every design token by default.
 - Body text and normal UI text should meet the project contrast target; large text and meaningful non-text UI indicators must remain distinguishable against adjacent colors.
+- Review contrast as foreground/background pairs such as text-on-surface, text-on-action, border-on-danger, and focus-on-surface. A single color token cannot prove contrast alone.
 - Do not communicate state by color alone. Pair color with text, icon shape, border, position, or another non-color signal when meaning matters.
 - Never remove focus indication without replacing it in the same change.
+- Keep focus-ring tokens separate from brand color tokens. Focus needs width, offset, inner or outer color, and background-specific contrast that survives dark mode, images, clipping, and forced colors.
+- Include assets, icons, charts, illustrations, shadows, elevation, disabled states, error states, and skeletons in theme review; a theme is not only background and text color.
 - Verify focus, error, selected, disabled, hover, active, and dark-mode states when token or component color changes.
 
+<!-- mustflow-section: motion-policy -->
+## Motion And Transition Policy
+
+- Do not use `transition: all`; list the properties that are intentionally animated.
+- Prefer `transform`, individual transform properties such as `translate`, `scale`, and `rotate`, and `opacity` for cheap motion.
+- Do not animate layout-affecting properties such as height, width, margins, top, left, or font size unless the interaction genuinely changes layout and the target browsers and fallback are reviewed.
+- Use `@starting-style` for first-render entry transitions only when supported or safely progressive.
+- Use `transition-behavior: allow-discrete` and overlay-related discrete transitions only when display or top-layer exit behavior actually needs it and fallback behavior remains acceptable.
+- Use intrinsic-size animation such as `interpolate-size` or `calc-size()` only as progressive enhancement; do not assume it removes layout cost.
+- Use registered custom properties for animatable typed values only when project browser targets allow it.
+- Do not let multiple transforms from hover, state, and keyframes overwrite each other accidentally. Prefer individual transform properties or explicit composition.
+- Keep scroll-driven animation behind compatibility checks and declare `animation-timeline` after the `animation` shorthand when both are used.
+- Respect `prefers-reduced-motion` by removing, shortening, or replacing nonessential large movement; do not merely speed up the same disorienting motion.
+- Add `will-change` only near a known animation or interaction and remove or scope it when the hint is no longer needed.
+
 <!-- mustflow-section: browser-compatibility-policy -->
 ## Browser Compatibility Policy
 
@@ -156,14 +202,18 @@ Every exception must explain why a lower-specificity, token-based, or layout-lev
 Reject the change when:
 
 - It adds styling ID selectors, long descendant chains, or unexplained `!important`.
+- It patches cascade failures without checking layer order, unlayered CSS, specificity from `:is` or nesting, scope proximity, or source order.
 - It repairs normal document flow with negative margins or absolute positioning.
 - It uses fixed width for containers or fixed height for text-containing UI.
 - It hides layout bugs with `overflow: hidden`.
+- It raises z-index without checking containing blocks, stacking contexts, top-layer options, or overflow clipping.
 - It adds unsized media, embeds, ads, or lazy content that can shift layout.
+- It adds raw palette values to component CSS, encodes theme modes into stable role-token names, treats `color-scheme` as a complete dark-mode implementation, or ignores forced-colors/high-contrast behavior.
 - It uses `content-visibility` without an intrinsic-size fallback or on content that must be immediately reachable.
 - It hardcodes raw component colors, spacing, font sizes, radius, or shadows without an exception.
 - It removes focus styling, creates hover-only affordances, or clips the focus indicator.
 - It adds motion without reduced-motion behavior.
+- It uses `transition: all`, permanent broad `will-change`, or layout-affecting animation without compatibility and performance review.
 - It uses a new CSS feature without compatibility/fallback review.
 
 <!-- mustflow-section: postconditions -->

package/templates/default/locales/en/.mustflow/skills/docs-prose-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.docs-prose-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: docs-prose-review
-description: Apply this skill when a documentation review queue entry needs prose cleanup for LLM-like wording, awkward phrasing, literal translation, unnatural tone, or review comments attached to the queue entry.
+description: Apply this skill when a documentation review queue entry or selected document needs prose cleanup for LLM-like wording, AI-slop signals, low-specificity boilerplate, awkward phrasing, literal translation, unnatural tone, Korean technical translationese, or review comments attached to the queue entry.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -24,6 +24,8 @@ metadata:
 
 Review one queued documentation file at a time and make its prose read naturally while preserving the document's technical contract.
 
+This skill treats "AI smell" as a prose-quality signal, not as authorship proof. The goal is to remove low-information writing, translation artifacts, and domain-term drift without accusing a writer, changing facts, or making the text artificially messy.
+
 <!-- mustflow-section: use-when -->
 ## Use When
 
@@ -31,6 +33,8 @@ Review one queued documentation file at a time and make its prose read naturally
 - A document is listed in the mustflow documentation review queue.
 - The queue entry includes a review comment that explains how the document should be checked or revised.
 - Prose sounds like LLM output, literal translation, filler, duplicated explanation, or unnatural Korean, English, or localized writing.
+- A Korean technical document, README, tutorial, report, abstract, release note, or guide contains AI-slop signals such as vague value claims, translationese, formulaic tutorial framing, repeated passive voice, low-specificity modifiers, or domain-term mistranslations.
+- The requested cleanup is to make writing more human, concrete, idiomatic, domain-accurate, or less template-like while preserving facts, code, commands, identifiers, and public contracts.
 - The reviewer is a human, LLM, tool, or external process and needs to record the review result.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -40,6 +44,8 @@ Review one queued documentation file at a time and make its prose read naturally
 - The document is not in the review queue and the task does not ask to add it.
 - The requested change would alter commands, paths, code blocks, schemas, field names, public contracts, or technical meaning.
 - The reviewer cannot understand the target language well enough to improve prose safely.
+- The task asks to identify, accuse, or certify a human author, AI author, plagiarism status, detector score, or policy violation from prose style alone.
+- The only requested change is to add intentional typos, random sentence variation, slang, emotional color, or "human imperfections" without improving clarity, evidence, or domain accuracy.
 
 <!-- mustflow-section: required-inputs -->
 ## Required Inputs
@@ -48,6 +54,8 @@ Review one queued documentation file at a time and make its prose read naturally
 - Any review comment attached to the queue entry.
 - The current file contents.
 - The intended document language and existing document structure.
+- The intended audience, genre, and register when known: README, tutorial, product docs, API docs, release notes, report, academic abstract, blog post, or maintainer-facing note.
+- Domain terminology that must stay exact, including code identifiers, API names, commands, package names, standard terms, and accepted translations.
 - The reviewer kind and free-form reviewer identifier for the review record.
 - `.mustflow/config/commands.toml` to resolve any verification intents.
 
@@ -58,6 +66,7 @@ Review one queued documentation file at a time and make its prose read naturally
 - The queue entry or selected path exists in the current mustflow root.
 - Higher-priority instructions, repository style, and command policy have been checked for the current scope.
 - The reviewer can preserve technical meaning while improving prose.
+- Style concerns can be tied to concrete text spans, not only a general feeling that the document sounds like AI output.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -65,6 +74,8 @@ Review one queued documentation file at a time and make its prose read naturally
 - Edit only the selected documentation file and review ledger entry unless the user explicitly broadens scope.
 - Preserve headings, frontmatter identity, tables, command examples, code blocks, paths, field names, and schema names unless they are the direct source of the prose issue.
 - Do not rewrite the whole document only to change tone.
+- Do not fabricate evidence, numbers, production experience, failure stories, user quotes, benchmarks, or implementation history to make the document feel more human.
+- Do not replace precise technical terms with casual synonyms only to avoid repetition.
 - Do not remove a document from the queue without either improving it, marking it as still needing review, or explicitly recording why it should be ignored.
 
 <!-- mustflow-section: procedure -->
@@ -74,17 +85,29 @@ Review one queued documentation file at a time and make its prose read naturally
 2. If the entry has a review comment, treat it as the primary review guidance. Preserve the same technical safety boundaries as the rest of this skill.
 3. If the entry has no review comment, inspect the document normally for awkward, LLM-like, over-explained, duplicated, literal, or unnatural prose.
 4. Read the entire selected file before editing so terminology, heading structure, examples, and references stay consistent.
-5. Apply the review comment or prose cleanup with minimal, meaning-preserving edits.
-6. Preserve executable snippets, paths, field names, option names, identifiers, frontmatter identity, and tables.
-7. If the comment is ambiguous or the meaning is unclear, do not guess. Mark the entry as still needing human review and summarize what needs a human decision.
-8. If the file does not need prose changes, mark the entry approved or ignored with a concise summary that explains why.
-9. After a successful prose review, mark the queue entry approved with reviewer metadata and a short summary.
-10. Run relevant configured verification intents when the edit changes public docs or installed workflow docs.
+5. Diagnose prose issues as quality problems, not authorship evidence. Prefer labels such as vague claim, translationese, passive-agent gap, filler, repeated frame, tone mismatch, or domain-term drift.
+6. Preserve meaning before style. Keep technical facts, literals, commands, code identifiers, paths, URLs, option names, schema names, API names, and measured values unchanged unless the source text is demonstrably wrong.
+7. Replace vague praise with concrete reader value, actor, action, condition, or evidence. For example, do not leave "important role", "efficiently handles", "seamless integration", "user-friendly", "stable and scalable", "can contribute to", or "has potential" unless the sentence also states how, where, or under what evidence.
+8. For Korean prose, reduce English-shaped translationese when it hurts clarity:
+   - prefer direct actors over repeated `-됩니다`, `-수행됩니다`, `-생성됩니다`, `-확인됩니다`;
+   - replace `~를 통해`, `~에 있어서`, `~에 의해`, `가능하게 합니다`, and `다음과 같습니다` when they only mirror English structure;
+   - avoid formulaic openings such as `이 글에서는 ... 알아보겠습니다` when the document can start with the task or claim;
+   - treat words such as `flaky`, `spoof`, `thin wrapper`, `heatmap`, `tainted`, `sandboxed`, and `code rot` as domain terms that may need accepted technical translations rather than dictionary-level literal phrasing.
+9. Check specificity. A strong technical sentence usually answers at least one of these: who acts, what changes, where it applies, how much changes, which condition matters, or what evidence supports it.
+10. Vary rhythm only in service of readability. Do not introduce artificial typos, random slang, forced metaphors, or sentence-length noise to evade an AI detector.
+11. Avoid over-editing. Leave good local phrasing alone, even if it is polished. Edit the smallest span that removes the concrete prose problem.
+12. Apply the review comment or prose cleanup with minimal, meaning-preserving edits.
+13. Preserve executable snippets, paths, field names, option names, identifiers, frontmatter identity, and tables.
+14. If the comment is ambiguous or the meaning is unclear, do not guess. Mark the entry as still needing human review and summarize what needs a human decision.
+15. If the file does not need prose changes, mark the entry approved or ignored with a concise summary that explains why.
+16. After a successful prose review, mark the queue entry approved with reviewer metadata and a short summary.
+17. Run relevant configured verification intents when the edit changes public docs or installed workflow docs.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - The selected document reads more naturally without changing technical meaning.
+- Low-specificity, boilerplate, translationese, passive-agent, and domain-term issues are fixed only where the text showed concrete evidence.
 - The review queue entry is approved, marked for human review, or ignored with reviewer metadata.
 - Any skipped edit, unresolved meaning question, or missing command intent is reported.
 
@@ -104,6 +127,9 @@ Do not infer missing validation commands.
 - If the queue cannot be inspected, report the blocked queue step and do not edit blindly.
 - If the selected file is missing, mark or report the stale queue entry instead of creating a replacement document.
 - If the language or technical meaning is uncertain, mark the entry as still needing human review.
+- If a phrase sounds AI-like but is also normal for the document genre, do not treat the phrase alone as a defect; look for low specificity, repetition, or meaning loss.
+- If removing AI-slop signals would require inventing facts, examples, numbers, or lived experience, preserve the claim boundary and report the missing evidence instead.
+- If a literal translation might be an accepted domain term, verify local usage in the document or repository before changing it.
 - If validation fails after prose edits, fix the first relevant documentation or workflow issue before marking the review complete.
 
 <!-- mustflow-section: output-format -->
@@ -111,9 +137,9 @@ Do not infer missing validation commands.
 
 - Queue entry selected
 - Review comment followed or reason no comment was present
-- Prose issues fixed
+- Prose issues fixed: vague claims, low-specificity boilerplate, translationese, passive-agent gaps, filler, repeated frame, tone mismatch, or domain-term drift
 - Review status recorded
 - Reviewer kind and reviewer identifier used
 - Command intents run
 - Skipped command intents and reasons
-- Remaining language, meaning, or validation risks
+- Remaining language, meaning, evidence, authorship-attribution, or validation risks

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.github-contribution-quality-gate
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: github-contribution-quality-gate
@@ -55,6 +55,9 @@ The goal is not polished prose. The goal is verified, scoped, actionable informa
 - Duplicate and context search evidence: searched terms, open and closed issues, open and closed pull requests, discussions when used by the repository, documentation, changelog, and related maintainer comments.
 - User evidence: reproduction steps, minimal example, logs, screenshots, recordings, changed files, local test output, failing command, environment, version, linked issue, or maintainer question being answered.
 - Draft structure evidence: proposed title, first-screen summary, section headings, Markdown tables, task lists, code blocks, details blocks, screenshots, links, review order, and unresolved questions.
+- Pull request readiness evidence when relevant: whether the PR should be ready for review or draft,
+  whether the title follows repository style without agent/vendor prefixes, and whether any review
+  re-request is explicitly warranted.
 - Verification level: personally reproduced, partially reproduced, inferred from code, inferred from logs, not reproduced, not searched, or not verified.
 - Desired result: report a bug, propose a feature, submit a fix, ask for design approval, answer a maintainer, provide missing evidence, or close the loop.
 
@@ -97,13 +100,27 @@ The goal is not polished prose. The goal is verified, scoped, actionable informa
    - `same problem here` without new evidence is not new value.
 6. Plan the reading order before polishing prose.
    - Title should name the observed result for issues or the guaranteed behavior after a PR, not labels such as `[BUG]`, `fix`, `WIP`, or implementation chores.
+   - Do not add agent, assistant, vendor, or tool prefixes such as `[codex]`, `[AI]`, or `[bot]`
+     unless the target repository explicitly requires them. Prefer the repository's conventional
+     commit or title style so the changed behavior stays first.
    - First screen should contain conclusion, impact, and requested decision. Move long logs, full outputs, screenshots, and alternatives below or into `<details>`.
    - Headings should answer one question each. Avoid dump headings such as `Details`, `Misc`, `Notes`, or `Context` unless the repository template requires them.
    - Separate observed facts, current hypotheses, decisions, and unknowns. Use `Cause` only when the cause is confirmed.
 7. For bug issues, require actual behavior, expected behavior, exact reproduction steps, smallest reasonable reproduction, version, environment, relevant logs or screenshots, regression status, attempted workarounds, concrete impact, and completion criteria.
 8. For feature or enhancement issues, require user problem, affected users, current workflow, desired workflow, why existing behavior is insufficient, related discussions, compatibility impact, alternatives considered, and non-goals when the proposal can sprawl.
 9. For documentation issues, require exact page, section, symbol, command, or example; current wording or behavior; expected wording or explanation; and evidence that the current documentation is stale or misleading when available.
-10. For pull requests, require focused scope, linked issue or prior discussion when non-trivial, changed behavior, intentionally unchanged behavior, tests added or updated, exact verification results, compatibility notes for public surfaces, UI screenshots when relevant, and draft status when incomplete.
+10. For pull requests, require focused scope, linked issue or prior discussion when non-trivial, changed behavior, intentionally unchanged behavior, tests added or updated, exact verification results, compatibility notes for public surfaces, UI screenshots when relevant, and a readiness decision.
+    - Use ready-for-review as the default for small, independent fixes or narrow improvements when
+      the relevant checks were run, known limitations can be stated in the PR body, and no
+      maintainer design decision is needed.
+    - Use draft only when the PR is intentionally discussion-first, changes public API shape, needs
+      design direction, has blocked or intentionally incomplete verification, or is likely to
+      conflict with other active work.
+    - If a draft PR becomes ready after verification, mark that transition in the PR body or update
+      comment instead of leaving the ready state implicit.
+    - Do not re-request review merely because a draft was marked ready. Re-request only when a
+      specific reviewer was already involved, the maintainer asked for it, or repository rules say
+      to request review after the ready transition.
 11. For PR review guidance, provide a review order by reasoning path rather than dumping changed files. Name files or commits only when they help reviewers inspect behavior, generated output, tests, or mechanical-only changes in the right order.
 12. For review replies, answer the maintainer's actual question first. Provide requested logs, reproduction, design tradeoff, tests, or blocker. Do not answer a different question because it is easier.
 13. Use Markdown elements by job, not decoration.
@@ -134,7 +151,8 @@ The goal is not polished prose. The goal is verified, scoped, actionable informa
     - do not submit AI output that the human contributor has not reviewed, cannot explain, or could have tested but did not.
 18. Choose a gate decision before writing the final draft:
     - `POST` when the content follows repository rules and has enough verified value;
-    - `POST_AS_DRAFT` when a PR direction is useful but not ready for final review;
+    - `POST_AS_DRAFT` when a PR direction is useful but not ready for final review, such as
+      discussion-first work, public API shape changes, blocked verification, or design approval;
     - `ASK_IN_EXISTING_THREAD` when the evidence belongs in a related issue or PR;
     - `DO_NOT_POST` when the content lacks verified value, duplicates existing content, violates repository rules, or the human contributor cannot defend it;
     - `PRIVATE_SECURITY_REPORT` when the content should not be public.
@@ -149,6 +167,8 @@ The goal is not polished prose. The goal is verified, scoped, actionable informa
 - Duplicate search is summarized with confidence.
 - Every technical claim in the draft is tied to evidence or marked uncertain.
 - Title, first-screen summary, section order, Markdown elements, verification, and risk handling help maintainers decide what to do next.
+- PR readiness, draft state, and review-request behavior are chosen from evidence instead of using
+  draft or re-request as generic defaults.
 - Security-sensitive content is not prepared for public posting.
 - AI assistance is disclosed when required or material.
 - The draft helps maintainers act faster or the skill blocks posting.
@@ -185,10 +205,12 @@ Use `changes_status` and `changes_diff_summary` when drafting a PR description o
 - Duplicate and context check
 - Evidence checked
 - Information-structure and Markdown checks
+- PR title, readiness, and review-request decision when relevant
 - Missing evidence
 - Draft
 - Final self-check:
   - Does the title state the observed issue result or PR outcome instead of metadata?
+  - Does the PR title avoid agent, assistant, vendor, or tool prefixes unless the repository requires them?
   - Can a maintainer understand the conclusion, impact, and requested action from the first screen?
   - Do headings, tables, task lists, details blocks, code blocks, screenshots, and links each have one clear job?
   - Can a maintainer reproduce or review this without guessing?
@@ -197,6 +219,8 @@ Use `changes_status` and `changes_diff_summary` when drafting a PR description o
   - Is every technical claim backed by evidence?
   - Are facts, hypotheses, decisions, and unknowns separated?
   - Does a PR include review focus, verification results, unverified areas, and risk or rollback notes when relevant?
+  - Is a verified small PR ready for review instead of unnecessarily draft?
+  - If a draft PR became ready, is any review re-request justified by maintainer request, repository rules, or an already involved reviewer?
   - Were feasible tests or verification checks run or honestly skipped?
   - Is AI assistance disclosed when required or material?
   - Can the human contributor explain and defend the content without AI?

package/templates/default/locales/en/.mustflow/skills/html-code-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.html-code-change
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: html-code-change
-description: Apply this skill when HTML, templates, JSX or component markup, native forms, controls, popovers, dialogs, navigation, tables, media, metadata, SEO head content, or structured data are created or changed.
+description: Apply this skill when HTML, templates, JSX or component markup, semantic document structure, native forms, controls, popovers, dialogs, navigation, tables, media, metadata, SEO head content, or structured data are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -47,6 +47,7 @@ Preserve semantic structure, native controls, keyboard access, focus behavior, f
 
 - Existing page layout, document shell, head/SEO helpers, metadata builders, canonical URL helpers, sitemap or robots config, form components, interactive control components, and tests.
 - Target framework conventions for rendering, routing, hydration, and metadata.
+- Semantic structure ledger: the intended `main`, landmark, heading, `section`, `article`, `nav`, `time`, `figure`, form group, table, media, and visible-label contracts.
 - Visible page content, H1 or primary title, main entity, locale, indexing intent, and data sources for title, description, image, author, date, price, rating, availability, and FAQ content when metadata changes.
 - Browser-native behavior expected from the markup: navigation, form submission, validation, autocomplete, input modality, popover behavior, dialog focus, inert background handling, media sizing, lazy loading, and history integration.
 - Accessibility and validation tooling declared in the command contract.
@@ -73,25 +74,37 @@ Preserve semantic structure, native controls, keyboard access, focus behavior, f
 
 1. Read the page shell, route layout, metadata helpers, component patterns, and tests before editing.
 2. Check document outline, landmarks, source order, and heading levels.
-3. Classify each interactive element by intent. Navigation to a URL uses an anchor with `href`. Commands, toggles, submit actions, open/close actions, destructive actions, copy actions, disclosure triggers, and modal triggers use buttons.
-4. Use native form controls for text entry, selection, checkbox, radio, and file input. Use grouped native radio or checkbox controls with fieldset and legend when the group label matters.
-5. Treat composite widgets such as tabs, action menus, comboboxes, listboxes, trees, grids, and custom selects as high-risk. Prefer native HTML or an existing audited component; otherwise implement the complete role, state, focus, and keyboard pattern.
-6. Reject clickable `div` or `span` controls, clickable icons without buttons, anchors without `href`, links used as buttons, nested interactive controls, positive `tabindex`, focusable `aria-hidden` content, and focus outline removal without a replacement focus style.
-7. Use ARIA only when native HTML cannot express the needed semantics. Validate the role is legal for the element, the accessible name exists, required states are present, visual and ARIA states stay synchronized, keyboard behavior matches the widget pattern, and focus behavior is explicit.
-8. For custom legacy button-like elements that cannot be replaced, require `role`, focusability, Enter activation, Space activation, Space scroll prevention, pointer activation, duplicate-event prevention, and visible focus. Use native buttons instead whenever possible.
-9. For popovers, prefer the native popover pattern for lightweight anchored disclosure, teaching UI, picker panels, or menus that do not need modal focus trapping. Verify trigger ownership, light-dismiss behavior, focus behavior, accessible name, and fallback or browser target.
-10. For dialogs, prefer native dialog when the project can support it. Otherwise implement focus entry, Tab and Shift+Tab containment, Escape behavior, inert or unreachable background content, visible close or cancel control, focus return, and an accessible name.
-11. Do not use dialog for every overlay. Use popover for non-modal transient UI, details/summary for simple disclosure, and dialog for modal tasks or interruptions that require focus containment.
-12. For tabs, use tablist, tab, and tabpanel semantics only for a real tabbed interface. Require one active tab, panel linkage, roving tabindex, arrow key movement, Home and End where expected, and Enter or Space activation when activation is manual.
-13. For menus, do not use ARIA menu roles for ordinary site navigation. Site navigation is a nav landmark with links. Use ARIA menu patterns only for application-style action menus with a button trigger, expanded state, focus strategy, Escape close behavior, and focus return.
-14. For forms, verify visible label association, help association, error association, required text, native required state, autocomplete, `inputmode`, `enterkeyhint`, validation timing, invalid state, error summary behavior, and submission behavior.
-15. Prefer native constraint validation for simple required, type, length, pattern, range, and step rules. Add custom validation only for business rules, cross-field rules, async validation, or localized error ownership the native browser cannot express.
-16. Use placeholder, title, aria-label, color, icon, or toast-only feedback only as supplementary affordances, not as the only label, required indicator, or error explanation.
-17. For metadata, read visible content and the metadata generation path first. Keep title, description, canonical, Open Graph, Twitter or X card data, robots, hreflang, and JSON-LD aligned with visible content, locale, URL, and indexing intent.
-18. Structured data must describe content visible on the same page. Do not invent ratings, reviews, FAQ items, authors, prices, availability, dates, organizations, product properties, or claims not backed by the page data source.
-19. Ensure every HTML page has a valid non-empty language and responsive viewport that does not disable zoom. Mixed-language passages should identify their language when needed.
-20. Keep inline script and style minimal; move behavior and styling to the existing project layers unless the framework requires an inline boundary.
-21. Choose configured verification intents that cover markup validity, lint, build, accessibility, route rendering, metadata, and docs when available.
+3. Treat semantic HTML as a machine-readable contract, not as styling decoration. Use `div` for pure wrappers and styling shells.
+4. Use `section` only for a thematic group that has a heading or explicit accessible label. Do not use `section` as a card, spacing, or script wrapper.
+5. Use `article` only for self-contained content that remains meaningful when syndicated, embedded, or moved out of the list, such as posts, articles, reviews, comments, or complete product entries.
+6. Use `nav` only for major navigation or table-of-contents regions. Do not label every incidental link group as navigation.
+7. Keep exactly one active visible `main` region for the page or current SPA view. Do not put repeated headers, footers, sidebars, or global navigation inside the main content unless that is the actual page task.
+8. Treat heading elements as content outline, not font-size controls. Preserve hierarchy by meaning, and use CSS for visual scale.
+9. Classify each interactive element by intent. Navigation to a URL uses an anchor with `href`. Commands, toggles, submit actions, open/close actions, destructive actions, copy actions, disclosure triggers, and modal triggers use buttons.
+10. Use native form controls for text entry, selection, checkbox, radio, and file input. Use grouped native radio or checkbox controls with fieldset and legend when the group label matters.
+11. Keep interactive elements out of labels. Do not place terms links, help buttons, or other controls inside a `label`; connect the label with `for` and `id`, then place related links or buttons outside the label.
+12. Treat composite widgets such as tabs, action menus, comboboxes, listboxes, trees, grids, and custom selects as high-risk. Prefer native HTML or an existing audited component; otherwise implement the complete role, state, focus, and keyboard pattern.
+13. Reject clickable `div` or `span` controls, clickable icons without buttons, anchors without `href`, links used as buttons, nested interactive controls, positive `tabindex`, focusable `aria-hidden` content, and focus outline removal without a replacement focus style.
+14. Use ARIA only when native HTML cannot express the needed semantics. Validate the role is legal for the element, the accessible name exists, required states are present, visual and ARIA states stay synchronized, keyboard behavior matches the widget pattern, and focus behavior is explicit.
+15. For custom legacy button-like elements that cannot be replaced, require `role`, focusability, Enter activation, Space activation, Space scroll prevention, pointer activation, duplicate-event prevention, and visible focus. Use native buttons instead whenever possible.
+16. For popovers, prefer the native popover pattern for lightweight anchored disclosure, teaching UI, picker panels, or menus that do not need modal focus trapping. Verify trigger ownership, light-dismiss behavior, focus behavior, accessible name, and fallback or browser target.
+17. For dialogs, prefer native dialog when the project can support it. Otherwise implement focus entry, Tab and Shift+Tab containment, Escape behavior, inert or unreachable background content, visible close or cancel control, focus return, and an accessible name.
+18. Do not use dialog for every overlay. Use popover for non-modal transient UI, details/summary for simple disclosure, and dialog for modal tasks or interruptions that require focus containment.
+19. For tabs, use tablist, tab, and tabpanel semantics only for a real tabbed interface. Require one active tab, panel linkage, roving tabindex, arrow key movement, Home and End where expected, and Enter or Space activation when activation is manual.
+20. For menus, do not use ARIA menu roles for ordinary site navigation. Site navigation is a nav landmark with links. Use ARIA menu patterns only for application-style action menus with a button trigger, expanded state, focus strategy, Escape close behavior, and focus return.
+21. For forms, verify visible label association, help association, error association, required text, native required state, autocomplete, `inputmode`, `enterkeyhint`, validation timing, invalid state, error summary behavior, and submission behavior.
+22. Prefer native constraint validation for simple required, type, length, pattern, range, and step rules. Add custom validation only for business rules, cross-field rules, async validation, or localized error ownership the native browser cannot express.
+23. Use placeholder, title, aria-label, color, icon, or toast-only feedback only as supplementary affordances, not as the only label, required indicator, or error explanation.
+24. Use `time` with a machine-readable `datetime` when the content represents a precise date, time, duration, or time-like value that tests, crawlers, calendars, or automation may need to parse.
+25. Use `figure` and `figcaption` only for self-contained referenced media, code, diagrams, charts, screenshots, or examples whose caption describes the figure. Do not use `figcaption` for ordinary card titles or unrelated image captions.
+26. Use real tables for tabular data. Include a useful `caption` when the table needs a name, use `th` for row and column headers, and set `scope` when it clarifies the header relationship.
+27. For meaningful media, prefer `img`, `picture`, `video`, or framework media components that preserve alt text, intrinsic dimensions, responsive candidate selection, and browser discovery. Keep decorative media out of the accessibility tree.
+28. For responsive image markup, verify `width`, `height`, `srcset`, `sizes`, `picture` art direction, and lazy or eager loading reflect the rendered slot. Route LCP, preload, priority, CDN, or byte-size claims to `image-delivery-performance-review`.
+29. For metadata, read visible content and the metadata generation path first. Keep title, description, canonical, Open Graph, Twitter or X card data, robots, hreflang, and JSON-LD aligned with visible content, locale, URL, and indexing intent.
+30. Structured data must describe content visible on the same page. Do not invent ratings, reviews, FAQ items, authors, prices, availability, dates, organizations, product properties, or claims not backed by the page data source.
+31. Ensure every HTML page has a valid non-empty language and responsive viewport that does not disable zoom. Mixed-language passages should identify their language when needed.
+32. Keep inline script and style minimal; move behavior and styling to the existing project layers unless the framework requires an inline boundary.
+33. Choose configured verification intents that cover markup validity, lint, build, accessibility, route rendering, metadata, and docs when available.
 
 <!-- mustflow-section: form-accessibility -->
 ## Form Accessibility Rules
@@ -128,16 +141,19 @@ Reject or revise the patch when any of these appear without strong justification
 
 - New `div` or `span` interaction where a native link, button, or form control would work.
 - Anchors without `href`, buttons implemented as links, links implemented as buttons, nested interactive controls, clickable icons without native controls, or site navigation using ARIA menu roles.
+- Decorative `section`, card-only `article`, incidental-link `nav`, multiple active `main` regions, headings chosen for visual size, labels containing nested interactive controls, or data tables rebuilt as non-table grids.
 - Custom controls without complete accessible name, role, state, keyboard, focus, and hidden-content behavior.
 - Popovers, dialogs, or overlays that replace native behavior without trigger, focus, light-dismiss, inert, or fallback review.
 - Positive `tabindex`, hidden content that remains tabbable, focusable `aria-hidden` content, or invisible focus.
 - Form controls without visible labels, placeholder-only labels, disconnected help or error text, color-only required or error state, premature `aria-invalid`, or autocomplete removed without reason.
+- Meaningful dates without parseable `time datetime`, figures used for ordinary card content, tables without header relationships, or meaningful media that lacks alt, intrinsic dimensions, or responsive candidate review.
 - Metadata or JSON-LD that contradicts visible content, fabricates facts, points canonical or social URL at the wrong page, disables zoom, omits page language, or accidentally noindexes a public page.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - Markup communicates the intended structure without relying on visual styling alone.
+- Sections, articles, navigation, main regions, headings, forms, figures, tables, time values, and media expose truthful document semantics.
 - Keyboard and focus behavior are preserved.
 - Forms have labels and errors connected.
 - Metadata and structured data reflect visible content.