mustflow 2.107.3 → 2.108.0

package/templates/default/locales/en/.mustflow/skills/browser-automation-reliability-review/SKILL.md

@@ -0,0 +1,279 @@
+---
+mustflow_doc: skill.browser-automation-reliability-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: browser-automation-reliability-review
+description: Apply this skill when browser automation, UI automation, Playwright, Selenium, Puppeteer, WebDriver, computer-use/browser-driving agents, visual browser verification, flaky selectors, page readiness, authentication state, CAPTCHA or anti-bot handling, rate limits, screenshot checks, retry, timeout, human approval, or browser automation observability is created, changed, reviewed, triaged, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.browser-automation-reliability-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Browser Automation Reliability Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review browser automation as a stateful, evidence-producing system, not as a sequence of clicks.
+
+The core question is: "Does the automation know what state the browser, user, page, network,
+session, target data, and approval gate are in before it acts and before it claims success?" If not,
+the flow will look fine in a demo and then fail under rerenders, slow CI, auth drift, anti-bot
+gates, rate limits, visual noise, stale approvals, or agent hallucination.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code, tests, docs, templates, or reviews touch browser automation, UI automation, end-to-end
+  harnesses, Playwright, Selenium, Puppeteer, WebDriver, browser contexts, remote browsers,
+  screenshots, videos, traces, HAR files, synthetic user flows, or computer-use browser agents.
+- A task mentions flaky selectors, unstable locators, actionability, stale elements, rerenders,
+  page readiness, `networkidle`, sleeps, waits, timeouts, retries, screenshot diffs, visual checks,
+  popups, downloads, native dialogs, iframes, shadow DOM, virtualized lists, or input typing.
+- Automation logs into a product, reuses storage state, shares accounts across workers, handles SSO,
+  OAuth, MFA, passkeys, cookies, localStorage, sessionStorage, IndexedDB, account lockout, or
+  permission changes.
+- Browser automation touches third-party sites, CAPTCHA, anti-bot or WAF challenges, rate limits,
+  robots or terms boundaries, IP reputation, headless fingerprints, provider throttling, or manual
+  fallback paths.
+- A browser-driving agent reads page content, follows page instructions, clicks by screenshot or
+  coordinates, extracts table data visually, enters forms, sends messages, purchases, deletes,
+  mutates external state, or asks for human approval before continuing.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is a pure LLM agent control-flow change with no browser or UI automation surface. Use
+  `agent-execution-control-review`.
+- The task is only prompt, RAG, model, tool schema, cost, latency, hallucination, or eval behavior
+  without browser execution. Use the matching LLM or agent specialist skill.
+- The task is only a product auth bug that is not being automated through a browser. Use
+  `auth-flow-triage` or `auth-permission-change`.
+- The task is only a browser request, CORS, CDN, API, or provider failure before the browser
+  automation layer is relevant. Use `api-failure-triage`.
+- The task is only frontend UI quality, layout resilience, accessibility, render stability, or web
+  performance for human users rather than automation harness reliability. Use the matching frontend
+  skill first.
+- The task is only test-suite runtime optimization, shard balance, retry policy, or flaky-test
+  handling without browser-specific failure modes. Use `test-suite-performance-review` or
+  `test-maintenance`.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Automation intent ledger: target site or app, owner, internal versus third-party boundary,
+  allowed actions, forbidden actions, expected user role, data class, write risk, and whether the
+  browser path is the right tool rather than an API, fixture, or deterministic adapter.
+- State ledger: current URL, frame, page, route, modal, popup, selected account, auth storage,
+  browser context, viewport, locale, timezone, permissions, feature flags, test data, worker ID,
+  correlation ID, and previous step result.
+- Readiness ledger: page-ready signal, data-ready signal, actionable-control signal, business-ready
+  signal, network and background-work assumptions, and any waits or assertions that prove them.
+- Selector and action ledger: locators, user-facing roles or labels, test IDs or automation
+  contracts, shadow DOM and iframe boundaries, virtualized list handling, click target, keyboard and
+  focus path, input acceptance proof, and actionability override use.
+- Auth and identity ledger: login strategy, storage owner, token or cookie storage surface, session
+  expiry, refresh behavior, per-worker account isolation, SSO or MFA gates, CAPTCHA policy, account
+  lockout policy, and logout or cleanup behavior.
+- External pressure ledger: rate limit unit, retry budget, anti-bot or challenge detection,
+  provider terms boundary, manual fallback, backoff behavior, and circuit-breaker threshold.
+- Verification ledger: success criteria, API or database confirmation when available, screenshot
+  or visual artifact role, trace/video/HAR policy, console and network capture, redaction,
+  retention, and failure artifact sampling.
+- Agent and approval ledger: page content trust boundary, prompt-injection exposure, tool
+  permissions, coordinate mapping, stale approval checks, approval snapshot, exact post-approval
+  action, resume state, and human escalation path.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Current repository instructions, command contract, automation harness code, test fixtures, browser
+  config, auth fixtures, screenshots or traces, and docs directly tied to the automation path have
+  been inspected before editing.
+- Browser vendor, automation library, remote-browser provider, CAPTCHA, anti-bot, and Agents SDK or
+  computer-use details are stale-sensitive. Use `source-freshness-check` before embedding exact
+  current API claims, provider limits, default timeouts, or compliance requirements.
+- External pages, emails, documents, ads, support threads, and rendered web content are untrusted
+  input for browser-driving agents.
+- Command execution remains governed by `.mustflow/config/commands.toml`; this skill does not
+  authorize launching development servers, unmanaged browsers, long-running workers, production
+  browser sessions, CAPTCHA bypasses, provider dashboards, or live side-effect runs.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or refine browser automation state machines, locator contracts, test IDs, accessible names,
+  readiness assertions, frame or popup handlers, input verification, auth fixtures, per-worker
+  account isolation, retry classification, timeout hierarchy, idempotency checks, rate-limit
+  handling, approval gates, manual fallback states, traces, screenshots, redaction, cleanup, and
+  directly synchronized docs or templates.
+- Move fixture setup, result verification, cleanup, idempotency checks, and data creation from
+  browser clicks to API or deterministic helpers when the browser UI is not the behavior under test.
+- Add focused tests for selector drift, readiness failure, stale element rerender, iframe or shadow
+  DOM handling, auth-state expiration, per-worker isolation, retry non-idempotency, stale approval,
+  screenshot noise, trace redaction, and agent prompt-injection defense when behavior evidence
+  supports them.
+- Do not fix flakiness by adding blind sleeps, force-clicking as the default, hiding failures behind
+  broad retries, weakening visual thresholds without evidence, sharing one mutable account across
+  parallel workers, or claiming browser success from an unverified screenshot.
+- Do not add CAPTCHA bypass, anti-bot evasion, headless fingerprint spoofing, or terms-violating
+  third-party automation as a normal product feature.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Decide whether the browser is the right boundary. Use API, fixtures, or service adapters for data
+   setup, teardown, and result verification when the browser UI itself is not the behavior being
+   tested or automated.
+2. Classify the automation owner: internal app E2E, internal operations tool, third-party site
+   workflow, browser-driving LLM agent, visual regression, scraping-like extraction, support tool,
+   or production user-assistance flow.
+3. Define a state machine before actions. Name the states such as unauthenticated, authenticated,
+   searching, selecting target, filling form, awaiting approval, submitting, verifying result,
+   retrying, blocked by challenge, manual fallback, succeeded, and failed.
+4. Replace sleeps with readiness evidence. For each step, define what proves the page is ready, the
+   data is ready, the target control is actionable, and the business state is safe to advance.
+5. Treat `networkidle` and selector-visible waits as weak signals. Prefer domain assertions such as
+   expected row identity, enabled submit state, loaded data count, settled validation, known URL,
+   confirmation ID, provider event, or backend result.
+6. Review locator contracts. Prefer stable user-facing roles, labels, names, and explicit test IDs
+   over CSS layout paths, generated classes, index-based XPath, translated prose only, or first-match
+   selectors.
+7. Check ambiguous DOM. Handle hidden duplicate controls, responsive desktop and mobile DOM at the
+   same time, skeletons that resemble real content, virtualized rows, portals, sticky overlays,
+   cookie banners, focus traps, iframes, cross-origin frames, shadow DOM, and custom components.
+8. Avoid stale element handles. Re-resolve locators at action time, and keep find-check-act-verify
+   close together so rerenders cannot invalidate old DOM references silently.
+9. Review actionability honestly. A forced click, coordinate click, JS-dispatched event, or disabled
+   actionability check must be exceptional, documented, and followed by proof that a real user path
+   is not being bypassed.
+10. Verify input acceptance. After typing, pasting, selecting dates, entering currency, using IME,
+    triggering autocomplete, or blurring a field, confirm the stored value, validation state, submit
+    readiness, or outbound payload rather than assuming keystrokes were accepted.
+11. Make auth state explicit. Identify whether auth lives in cookies, localStorage, sessionStorage,
+    IndexedDB, memory, or provider redirects; isolate accounts by worker; avoid shared mutable user
+    state; and handle expiry, rotation, SSO, MFA, passkeys, lockout, and logout contamination.
+12. Treat CAPTCHA and anti-bot as product states. In test or staging, use allowed test keys,
+    allowlists, or disabled challenge paths. In production or third-party flows, detect challenges,
+    stop safely, and route to human review or manual fallback instead of trying to evade them.
+13. Add rate control before retries. Identify the rate-limit subject, whether a single browser action
+    fans out into many requests, how backoff is computed, when to stop, and how the system avoids a
+    retry storm.
+14. Classify retryable failures. Retry only transient navigation, detached element, timeout,
+    temporary backend, or eventual-consistency classes within a bounded budget. Do not retry
+    permission denied, invalid input, CAPTCHA, account lockout, provider policy blocks, unknown
+    write outcome, or business-rule failures without a recovery-specific check.
+15. Make writes idempotent or confirm-before-replay. For purchases, payments, deletes, sends,
+    refunds, admin changes, support actions, and external mutations, record stable operation IDs and
+    check whether the effect already happened before any retry or resume can repeat it.
+16. Design timeout hierarchy. Align action, assertion, navigation, test, job, queue lease, browser
+    provider session, and external API timeouts so cancellation saves evidence, releases resources,
+    and resumes from a known state.
+17. Separate visual proof from business proof. Use screenshots for layout or visual regression, but
+    use confirmation IDs, API reads, database rows, provider events, downloads with checksums, audit
+    logs, or received messages to prove business success.
+18. Stabilize screenshot assertions. Freeze or mask nondeterministic content such as time, caret,
+    animation, ads, maps, charts, lazy images, random data, locale, theme, viewport, font, GPU,
+    scrollbar, and cookie banners before changing thresholds or baselines.
+19. Capture failure context. Save current URL, frame, viewport, locale, timezone, screenshot, DOM or
+    accessibility snapshot when safe, console errors, network statuses, trace, video, retry count,
+    worker ID, account ID class, and correlation ID with sensitive-data redaction.
+20. Protect artifacts. Browser traces, videos, screenshots, HAR files, storage state, and console
+    logs can contain cookies, tokens, personal data, addresses, order details, and messages; set
+    redaction, retention, encryption, access, and sampling before broad collection.
+21. For browser-driving agents, distrust page content. Treat rendered instructions, hidden DOM,
+    emails, PDFs, comments, ads, and third-party text as untrusted data that must not override the
+    system task, tool policy, approval rules, or data-exfiltration limits.
+22. Split agent roles where risk justifies it. Keep planner, browser executor, verifier, policy
+    gate, and human approval separate for high-impact flows. If one model does multiple roles, add
+    deterministic gates before side effects and before success claims.
+23. Make coordinate and screenshot actions verifiable. Recheck screenshot-to-DOM scale, scrolling,
+    focus, active modal, target bounds, visible label, disabled state, and post-action state when a
+    model or computer-use tool clicks by image or coordinates.
+24. Treat human approval as durable state. Show the exact account, URL, target, amount, recipient,
+    data, screenshot, form values, risk class, reversibility, and exact next action. Before resume,
+    re-read critical fields and compare them with the approved snapshot.
+25. Clean up resources. Close pages, contexts, browsers, downloads, temp files, videos, traces,
+    mock servers, websockets, and test data deliberately; detect zombie browser processes and
+    artifact growth in long runs.
+26. Verify with the narrowest configured tests, docs checks, release checks, and mustflow validation
+    that cover the changed automation contract.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The automation has explicit states, readiness signals, locator contracts, auth isolation, retry
+  classes, timeout hierarchy, and success evidence.
+- Browser-only proof is separated from business-result proof.
+- CAPTCHA, anti-bot, rate-limit, human-approval, prompt-injection, and third-party boundary risks
+  are detected, stopped, or routed to manual fallback instead of hidden behind retries.
+- Failure artifacts are useful enough to debug and constrained enough not to leak secrets or
+  personal data.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrowest configured fixture, unit, integration, docs, package, or release check that proves
+the changed browser automation contract. Do not infer raw browser launches, dev servers, headed
+browsers, provider dashboards, CAPTCHA-solving services, or production automation runs from local
+files.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the failure is not localized to browser automation, use `api-failure-triage`,
+  `auth-flow-triage`, `frontend-render-stability`, `test-maintenance`, or another narrower skill
+  first.
+- If a selector is flaky, do not patch only the selector string until locator ownership, duplicate
+  DOM, responsive DOM, skeletons, frames, shadow DOM, and readiness have been checked.
+- If a retry would replay an unknown write, stop and add idempotency or effect-confirmation before
+  enabling retry.
+- If CAPTCHA, anti-bot, account lockout, provider policy, or terms boundaries are detected, stop the
+  automation path and report the manual or contractual fallback instead of bypassing it.
+- If human approval resumes after state changed, expire the approval or request a new approval with
+  the changed fields.
+- If artifacts would leak secrets or personal data, collect a smaller redacted evidence set and
+  report the observability gap.
+- If a configured command fails, use `failure-triage` before continuing.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Browser automation surface reviewed
+- Browser-versus-API boundary and automation owner
+- State machine, readiness, locator, actionability, auth, rate-limit, retry, timeout, and
+  idempotency decisions
+- Screenshot, trace, artifact, redaction, and business-success evidence
+- Agent page-content trust, coordinate action, tool permission, approval, and resume checks
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining browser automation reliability risk

package/templates/default/locales/en/.mustflow/skills/cli-option-contract-review/SKILL.md

@@ -0,0 +1,147 @@
+---
+mustflow_doc: skill.cli-option-contract-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: cli-option-contract-review
+description: Apply this skill when CLI options, flags, positional arguments, aliases, defaults, parser behavior, prompt controls, config or environment precedence, or automation-facing argument contracts are created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.cli-option-contract-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# CLI Option Contract Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve the contract between CLI syntax and the humans, scripts, CI jobs, shells, terminals, config files, and docs that depend on it.
+
+CLI options are public API. A convenient flag can still be unsafe if it collides with existing shorthand, hides destructive behavior behind a vague name, prompts in CI, writes to stdout when scripts expect JSON, or turns a path, format, selector, or environment into an ambiguous value.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A command adds, removes, renames, aliases, deprecates, validates, or changes a flag, option, positional argument, variadic argument, default value, inherited global flag, or option parser rule.
+- A task designs or reviews standard CLI controls such as dry-run, check, plan, diff, yes, force, confirm, no-input, interactive, verbose, quiet, debug, format, output, color, pager, progress, config, profile, env, timeout, retry, jobs, cache, stdin, token, endpoint, region, project, pagination, target, prune, rollback, or AI-agent permission flags.
+- A command changes prompt behavior, TTY behavior, non-interactive behavior, CI behavior, option terminator support, repeated flags, boolean negation, duration or size parsing, path handling, glob handling, stdin handling, or list parsing.
+- A final report claims that CLI options are safe, automatable, compatible, conventional, discoverable, or aligned with docs and tests.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task changes only stdout, stderr, JSON fields, JSONL packets, exit codes, color rendering, progress output, warning text, error text, or help wording without changing option or argument semantics. Use `cli-output-contract-review`.
+- The task changes only public JSON, JSONL, schema-backed reports, or machine-readable stdout and stderr contracts. Use `public-json-contract-change`.
+- The task changes only `.mustflow/config/commands.toml` command intents or command authority. Use `command-contract-authoring`.
+- The task changes only environment variables, secrets, config keys, feature flags, or runtime/build-time exposure. Use `config-env-change`.
+- The task changes only docs prose that mentions an unchanged command syntax. Use the matching docs skill.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The affected command, command tree, parser library or command router, inherited global flags, positional arguments, variadic arguments, current aliases, defaults, validation rules, and help metadata.
+- Existing docs, README snippets, examples, tests, snapshots, fixtures, shell completions, schemas, template copies, package tests, and release notes that mention the syntax.
+- The operation type: read-only, planning, validation, write, destructive write, remote write, deploy, migration, deletion, cleanup, generated-file write, or AI-agent action.
+- The intended consumers: humans at a TTY, scripts, CI jobs, package tests, shell completion users, remote APIs, installed templates, release automation, or downstream wrappers.
+- Current config and environment precedence, including config files, profiles, env vars, CLI flags, defaults, and explicit override rules.
+- Current non-interactive, prompt, color, pager, progress, timeout, retry, cache, lock, and exit-code expectations when they exist.
+- Relevant command-intent entries for related tests, docs validation, release checks, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Existing command syntax, aliases, docs examples, tests, and parser behavior have been inspected before changing or recommending a flag.
+- Short flags are treated as scarce public API. Do not assign them from generic CLI advice without checking collisions, command frequency, and established project conventions.
+- External articles, AI summaries, package defaults, and other CLIs are evidence only. The repository's current parser, command contract, compatibility policy, and user instructions remain authoritative.
+- Command execution remains governed by `.mustflow/config/commands.toml`; this skill does not authorize raw command execution.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update CLI parser code, command metadata, help text, completions, docs examples, tests, fixtures, schemas, template copies, and release-sensitive package metadata that describe the same option contract.
+- Add explicit long flags, validation errors, compatibility aliases, deprecation notices, negative tests, or parser edge-case tests when they reduce ambiguity.
+- Prefer clear long options over clever short aliases. Add a short option only when it is frequent, unambiguous, and consistent with existing command conventions.
+- Do not merge different safety meanings into one flag. For example, prompt acceptance, safety bypass, preview, destructive overwrite, and non-interactive failure should remain separable.
+- Do not introduce unsafe defaults, vague automation flags, broad bypass flags, hidden prompts, or silent output-mode changes.
+- Do not add parser behavior that breaks paths beginning with a dash, negative numbers, option terminators, repeated values, or non-interactive scripts unless that incompatibility is intentional and documented.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Inventory the command syntax: subcommands, positional arguments, variadic arguments, options, inherited global flags, aliases, defaults, environment variables, config files, and generated completions.
+2. Classify each option by role: safety and preview, confirmation and prompts, output and formatting, logging and diagnostics, config and environment, selection and filtering, file input and output, remote endpoint and auth, performance and cache, concurrency and locking, CI automation, destructive lifecycle, or AI-agent authority.
+3. Decide whether the behavior belongs in a subcommand, positional argument, option, config key, environment variable, or separate command. Destructive lifecycle changes often deserve explicit verbs rather than a broad boolean flag.
+4. Review naming collisions before adding names. Pay special attention to common conflicts such as verbose versus version, force versus file, dry-run versus debug or delete or directory, output format versus output path, interactive versus input, and shorthand reused differently across subcommands.
+5. Separate near-neighbor semantics. `--yes` accepts prompts; `--force` bypasses a safety guard; `--dry-run` avoids writes; `--check` reports whether change is needed; `--diff` shows the proposed change; `--output` should mean a destination only if format uses another name such as `--format`.
+6. Prefer explicit paired controls for risky workflows: dry-run, plan, diff, check, validate, no-input, confirm, yes, force, no-clobber, overwrite, backup, rollback, atomic, lock-timeout, fail-fast, and continue-on-error.
+7. Check non-interactive behavior. Prompts should be TTY-only; `--no-input` should fail instead of waiting; CI-oriented paths should be compatible with quiet, JSON, no-color, no-progress, no-pager, timeout, wait, and detailed exit-code behavior when the repository supports those controls.
+8. Check human and machine output interaction. If an option changes output format, route machine-readable results and diagnostics consistently, and use `cli-output-contract-review` or `public-json-contract-change` for the output contract details.
+9. Define config and environment precedence. Document and test whether CLI flags override environment variables, profiles, config files, defaults, and inline `--set` style overrides.
+10. Review parser edge cases: `--` option terminator, paths beginning with `-`, negative numbers, repeated flags, comma-separated lists versus repeated values, boolean negation with `--no-*`, optional values, duration and size units, shell quoting, globs, symlinks, hidden files, recursive flags, and stdin markers.
+11. Check file and generation behavior. Separate input path, output path, output directory, create-dirs, overwrite, no-clobber, backup, atomic write, recursive traversal, hidden files, symlink following, ignore files, and validation-only modes.
+12. Check remote and SaaS behavior when relevant. Separate endpoint URL, region, account, project, token source, token stdin, CA or proxy settings, connect timeout, read timeout, pagination, query filters, and retries.
+13. Check infra or deploy behavior when relevant. Separate plan, apply, refresh, target, replace, prune, rollback, lock, lock-timeout, wait, parallelism, and detailed-exit-code semantics.
+14. Check AI-agent behavior when relevant. Separate model, prompt source, context include or exclude, max files, max bytes, write permissions, command permissions, network permissions, approval policy, checkpoint, dry-run, diff, and apply.
+15. Preserve compatibility. For renamed or split flags, consider aliases, deprecation warnings, migration help, and tests before removing old syntax. Treat breaking option removals, changed defaults, changed prompt behavior, and changed parser grammar as public API changes.
+16. Synchronize every surface that teaches or consumes the syntax: parser code, help text, completions, docs, README, examples, tests, fixtures, schemas, templates, package metadata, and release notes when applicable.
+17. Verify with the narrowest configured related tests first, then docs, release, template, and mustflow checks when syntax, docs, profiles, templates, or package metadata changed.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Option names, aliases, defaults, parser behavior, config precedence, prompt behavior, and non-interactive behavior are explicit and synchronized.
+- Short flags have a documented reason or are omitted in favor of clear long flags.
+- Destructive, write, preview, confirmation, force, and non-interactive controls are not conflated.
+- Automation-facing use has stable output-mode, no-prompt, no-color, no-progress, no-pager, timeout, retry, and exit-code behavior when relevant.
+- Parser edge cases are covered by tests or reported as remaining risk.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use broader configured tests when option parsing is cross-cutting or no narrower related test covers the syntax.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If an option name conflicts with existing syntax, keep the old contract and choose a clearer long option unless a breaking change is intentionally routed through compatibility and versioning.
+- If a parser edge case cannot be verified directly, add focused coverage or report the missing coverage before claiming safety.
+- If docs, help text, completions, or templates cannot be synchronized in the same change, avoid claiming the option contract is installed or documented.
+- If non-interactive behavior is unclear, default to failing safely rather than prompting, writing, deleting, or assuming consent.
+- If an external recommendation conflicts with repository conventions, document the rejected recommendation and the repository-specific reason.
+- If a breaking option change is intentional, route the version impact through the repository versioning policy and report affected consumers.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- CLI command and options reviewed
+- Option role classification and naming decision
+- Short and long flag collision review
+- Safety, preview, destructive, prompt, and non-interactive controls
+- Parser edge cases checked or reported missing
+- Config and environment precedence
+- Human, machine, CI, color, pager, progress, timeout, retry, and exit-code interaction
+- Docs, help, completions, tests, schemas, templates, and package metadata synchronized
+- Command intents run
+- Skipped checks and reasons
+- Remaining CLI-option contract risk

package/templates/default/locales/en/.mustflow/skills/database-change-safety/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.database-change-safety
 locale: en
 canonical: true
-revision: 16
+revision: 17
 lifecycle: mustflow-owned
 authority: procedure
 name: database-change-safety
@@ -79,6 +79,7 @@ Use the smallest persistence boundary that proves the risk. Do not introduce rep
 - Event role: operational event, audit log, behavior analytics event, integration outbox message, reporting aggregate, or replayable domain event.
 - Data owner and affected tables, collections, stores, indexes, caches, generated files, or read models.
 - Entity identity rules, including stable ids, external provider ids, mutable slugs, titles, locale-specific addresses, redirects, and public API identifiers when content or user-facing resources are involved.
+- Regret-prone schema shape rules, including internal versus public ids, normalized unique keys, tenant-scoped uniqueness, foreign keys, join tables, enum or lookup-table ownership, nullable-field meaning, JSON promotion criteria, custom-field boundaries, status history, optimistic locking, and operational trace fields.
 - Exit and restore rules, including whether exported data preserves relationships, permissions, files, versions, events, audit history, automation rules, provider id mappings, schema metadata, and enough import or restore evidence to reconstruct product state.
 - Identifier ownership rules, including which ids are product-owned, which ids are public, which ids are provider mappings, and whether external auth, payment, CRM, analytics, storage, or CMS ids can change without breaking internal references.
 - Authentication identity rules, including app-owned user id, provider subject records, email-as-attribute behavior, social provider subject preservation, account merge or relink policy, session migration expectations, and whether memberships, roles, permissions, and entitlements live in product-owned tables rather than only provider metadata.
@@ -173,8 +174,25 @@ Use the smallest persistence boundary that proves the risk. Do not introduce rep
    - External-service core facts, such as current entitlement, subscription or plan state, processed payment event id, email consent state, customer lifecycle state, file identity and ownership, search source document metadata, job processing state, and audit evidence. Do not let a provider dashboard be the only place that can explain these facts.
    - Search and queue reconstruction records, such as index document builders, ranking or synonym policy versions, search logs, queue message schema versions, job idempotency keys, retry state, dead-letter state, and manual replay markers.
 4. Check schema shape: primary keys, foreign keys, unique constraints, nullable fields, defaults, check constraints, status values, timestamps, soft delete fields, tenant scope, audit fields, and retention rules.
+   - Use immutable internal primary keys for joins and separate public identifiers for URLs and APIs. Do not make email, slug, username, external provider id, or mutable display code the primary key for product-owned rows.
+   - Enforce uniqueness in the database, not only in application prechecks. Normalize comparison keys such as email, slug, provider id, and idempotency key explicitly, preserve the display value separately when needed, and name the unique constraint or index so operations can diagnose failures.
+   - Scope unique constraints to the real owner. Tenant-owned slugs, emails, invitations, memberships, idempotency keys, and external references usually need `tenant_id`, `workspace_id`, `operation_type`, or `provider` in the key. Global uniqueness should be a deliberate product rule, not an accident.
+   - Design soft-delete uniqueness before shipping. Active-only uniqueness, nullable unique behavior, restore conflicts, deleted-id reuse, and tombstone requirements must be explicit; otherwise deleted rows either block valid new records or allow duplicate active records.
+   - Prefer database foreign keys for core ownership and reference integrity. If an FK is intentionally omitted for scale, import staging, sharding, or asynchronous reconciliation, name the replacement invariant, cleanup path, and orphan-detection evidence. Index FK columns when joins, parent deletion checks, or tenant deletion depend on them.
+   - Treat `ON DELETE CASCADE` as a lifecycle promise, not cleanup convenience. Use it only when child rows truly share the parent's lifetime and audit, retention, restore, and legal obligations do not require separate survival.
+   - Model many-to-many relationships with join tables that can own role, status, order, source, timestamps, and actor fields. Avoid comma-separated ids, arrays of ids, or JSON lists for relationships that need joins, uniqueness, permissions, deletes, or audit.
+   - Treat polymorphic `entity_type` plus `entity_id` relations as integrity debt for core data because ordinary FKs cannot prove the target exists. Prefer target-specific tables, a shared parent table, or explicit constraint and cleanup machinery when the relation is business-critical.
+   - Choose enum, lookup table, or state machine based on change behavior. Stable technical codes may be enums; operator-managed values, values with display or sort metadata, plan or category catalogs, roles, and jurisdiction-specific rules usually need lookup tables. Workflow status needs allowed transitions and history, not only a value list.
+   - Avoid boolean state soup such as several independent `is_*` flags for one lifecycle. Use one current status plus timestamps or event history when states are mutually exclusive, ordered, reversible, or policy-driven.
+   - Give nullable fields exactly one meaning. Separate unknown, not applicable, not entered yet, deleted, failed, and pending states with explicit status or reason fields when queries or reports depend on the distinction.
+   - Avoid EAV or generic `entities`/`attributes`/`values` tables for core domain facts. If customer-defined fields are required, keep them in a bounded custom-field area with definitions, type validation, quotas, ownership, export semantics, and a promotion path once values drive search, sort, permission, billing, or reporting.
+   - Do not hide behavior-driving data in JSON. Keys used for filters, ordering, joins, uniqueness, permissions, tenant scope, status, retention, money, dates, quotas, indexes, or operational dashboards should be typed columns, child tables, or generated/computed columns with a migration path. Use `database-json-modeling-review` when JSON is part of the diff.
+   - Keep tenant ownership close to the owned row when tenant-scoped operations, billing, audit, export, restore, delete, or performance matter. B2B products should usually separate global users from tenant memberships, roles, invitations, entitlements, and billing records.
    - Treat deletion as lifecycle when recovery, audit, search behavior, support handling, or retention matters. Consider `deleted_at`, `deleted_by`, `delete_reason`, `restored_at`, `restored_by`, and `purge_after` instead of a lone boolean or timestamp.
    - Separate business records that should be soft-deleted or archived from personal data that should be anonymized, purged, or retained under a narrower legal rule.
+   - Keep status history for states that affect money, access, fulfillment, support, compliance, or user-visible commitments. A current status alone rarely explains who changed it, why, under which request, and whether a late webhook, retry, or admin action should still apply.
+   - Add optimistic versioning or conditional updates when two users, admins, workers, or webhooks can edit the same important row. Last-write-wins is usually data loss unless the product explicitly accepts it.
+   - Add operational trace fields where incident response will need them: server timestamps, actor ids, `created_by`, `updated_by`, `request_id`, `source`, import or provider reference, and safe reason codes. Do not add them blindly to every table, but do not leave high-value rows untraceable.
    - Treat mutable high-value records as versioned when reproducibility matters, such as AI prompts, documents, contracts, price policies, experiment configs, comparison data, permission policies, automation rules, and model settings. Prefer a stable parent row with a current-version pointer plus immutable version rows.
    - Use ledgers for money-like or quota-like balances, such as points, credits, inventory reservations, refunds, coupon issuance, entitlement grants, and manual adjustments. Treat cached balances as derived from ledger entries unless the local design proves otherwise.
    - For audit logs, store actor type, actor id when safe, action, target type and id, bounded before and after values, reason, request id, idempotency key, and timestamp in the same local transaction as the audited change when possible. Audit logs should be append-only to normal operators and should redact or omit personal data that is not needed to explain the change.
@@ -318,6 +336,7 @@ Use the smallest persistence boundary that proves the risk. Do not introduce rep
 ## Postconditions
 
 - The database role and source of truth are explicit.
+- Regret-prone schema shortcuts such as mutable primary keys, app-only uniqueness, unscoped tenant uniqueness, missing FK or cascade ownership, ambiguous nulls, boolean state soup, polymorphic core relations, EAV core facts, behavior-driving JSON, and user-as-tenant coupling are fixed, explicitly accepted, or reported.
 - Database rows, ORM models, generated caches, and read models do not leak into domain truth unless the local architecture intentionally owns that boundary.
 - Queries preserve authorization, tenant or user scope, deterministic ordering, expected absence behavior, and retention rules.
 - Content and resource models separate stable identity from mutable titles, slugs, URLs, translations, display fields, revisions, facts, sources, projections, and analytics dimensions when those concerns exist.
@@ -375,7 +394,7 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 
 - Database role and owner
 - Affected read and write paths
-- Schema, constraint, and query semantics reviewed
+- Schema-regret, constraint, relation, enum, JSON, custom-field, status-history, traceability, and query semantics reviewed
 - Identity, slug, lifecycle, asset, body block, taxonomy, relationship, attribute, filter URL, landing-page, translation, locale, country, currency, timezone, local-date, money, price snapshot, revision, claim, fact, source, collection, verification, comparison methodology, affiliate link, data-ownership, behavior analytics, audit log, API projection, public identifier, backup or restore, bulk update, admin audit, user-state, aggregate, cache-key, projection, and cache-invalidation checks where relevant
 - Export, import, product-owned id, provider-id mapping, relationship, permission, file, automation, event-history, and reconstruction checks where relevant
 - Authorization, tenant scope, retention, and privacy checks