mustflow 2.22.17 → 2.22.47

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

@@ -0,0 +1,184 @@
+---
+mustflow_doc: skill.astro-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: astro-code-change
+description: Apply this skill when Astro config, pages, layouts, components, islands, hydration directives, content collections, dynamic routes, adapters, MDX, RSS, sitemap, canonical URL, draft, pagination, or build behavior are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.astro-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Astro Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Astro's static-first model, island hydration boundary, routing contract, content collection schema, canonical URL, RSS, sitemap, adapter, and client bundle boundaries.
+
+The default is no-hydration. Add browser JavaScript only after proving that native HTML, CSS, standard links, forms, details/summary, or a small `.astro` script cannot provide the required behavior.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `astro.config.*`, `src/pages`, `.astro`, content config, live config, collections, layouts, components, MDX, routes, endpoints, adapters, integrations, islands, or hydration directives change.
+- The task adds or changes a page, blog/docs content, interactive UI, SSR/on-demand rendering, framework component, search/filter UI, route behavior, RSS feed, sitemap, canonical URL, draft handling, or pagination.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is framework-agnostic CSS or HTML only; use `html-code-change` or `css-code-change`.
+- The interactive component is entirely inside another framework and Astro routing/content is unaffected.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Package metadata, Astro version, framework integrations, TypeScript config, pages, layouts, components, content config, content files, integrations, adapter config, env declarations, public assets, and tests.
+- Astro config values that affect routing and URLs: `site`, `base`, `trailingSlash`, `output`, `adapter`, sitemap integration, MDX integration, and framework integrations.
+- Content collection names, loader bases, schemas, slug/id policy, draft fields, date fields, canonical fields, and route files that turn collection entries into pages.
+- Current output mode, prerender/SSR policy, hydration conventions, route priority, endpoint layout, RSS generation, sitemap generation, and content schema.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Read Astro config, content config, and the affected route tree before changing routing, content, canonical, RSS, sitemap, or hydration behavior.
+- Identify build-time versus request-time data before adding data access.
+- Identify which UI truly needs browser JavaScript and which UI truly needs framework state before adding a framework island.
+- Treat file movement under `src/pages`, route parameter changes, and content slug changes as URL contract changes.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Prefer static `.astro`, HTML, CSS, native links, native forms, details/summary, and small `.astro` scripts before adding a framework island.
+- Use hydration directives only for components that need browser interactivity and cannot be handled with a small non-framework script.
+- Keep content collection schemas synchronized with frontmatter and collection reads.
+- Keep server-only secrets and data access out of client islands.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read package metadata and Astro config first. Record Astro version, framework integrations, `site`, `base`, `trailingSlash`, `output`, adapter, sitemap integration, MDX integration, and any framework integration.
+2. Read `src/content.config.*` when content, docs, blog, RSS, sitemap, canonical, or route generation is involved. Record each collection name, loader base, schema fields, slug/id policy, draft field, and date fields.
+3. Build a route ledger from `src/pages`: static pages, dynamic pages, rest routes, endpoints, prerendered routes, on-demand routes, and possible route-priority collisions.
+4. Classify the change: static route, dynamic route, endpoint, content collection, integration, adapter, SSR/on-demand, island, script, asset, RSS, sitemap, canonical, or docs/content.
+5. Apply the hydration policy below before adding or changing any `client:*` directive.
+6. Apply the routing and rendering policy below before adding dynamic routes, catch-all routes, endpoints, adapter changes, or `prerender` changes.
+7. Apply the content, SEO, and feed policy below before changing frontmatter, schemas, slugs, drafts, canonical URLs, pagination, RSS, or sitemap behavior.
+8. Do not put runtime-only data such as logged-in user state, request-local data, private API responses, or live inventory into build-time collections.
+9. Do not enable request-time rendering without the adapter and deployment contract that support it.
+10. Keep `set:html` or raw HTML injection behind a trusted and sanitized content boundary.
+11. Choose configured verification intents that cover content schema, build, routes, hydration, adapter/runtime, and bundle risk when available.
+
+## Hydration Policy
+
+- If HTML, CSS, standard links, native forms, details/summary, or static content can provide the feature, do not add hydration.
+- If the behavior is a small browser enhancement such as copy, expand/collapse, theme class toggling, heading-anchor copying, analytics, or a small dropdown, prefer a `.astro` script or custom element over a framework island.
+- Add a framework island only after the component needs framework state, lifecycle, or an existing framework component that cannot be replaced safely.
+- Use `client:load` only for immediately visible controls that must be interactive as soon as the page loads.
+- Use `client:idle` for non-critical above-fold or near-fold enhancements that may hydrate after initial load.
+- Use `client:visible` for below-the-fold or heavy widgets that users may never view.
+- Treat `client:only` as a last-resort exception. It requires an SSR-impossible browser-only dependency or API and a named reason.
+- Do not use framework islands for ordinary links, breadcrumbs, tag lists, card lists, static tables of contents, prose callouts, pagination, or static search links.
+- When adding a hydration directive, report the reason and the expected client bundle or island-count impact when verifiable.
+
+## Routing And Rendering Policy
+
+- In static output, every dynamic route must have `getStaticPaths`.
+- In on-demand or SSR dynamic routes, do not use `getStaticPaths`; read `Astro.params`, perform the request-time lookup, and handle missing entries with an explicit 404 or redirect path.
+- `getStaticPaths` params must match bracket parameter names exactly and must be strings.
+- Custom slugs containing `/` require a rest route such as a catch-all route. Do not force slash-containing slugs into a single named parameter route.
+- Treat changes under `src/pages` as public URL changes, including endpoint names and extension-bearing endpoint paths.
+- Check route priority when adding static routes, named parameters, rest parameters, catch-all routes, and endpoints that could claim the same URL.
+- Remember that endpoints can take precedence over pages at the same path. Do not assume a catch-all page receives paths claimed by a more specific endpoint or page.
+- Do not assume adding an adapter makes every page SSR. Keep static output as the default unless the project explicitly chooses server output or route-level on-demand rendering.
+- Do not switch the whole project to server output for one page unless the deployment and route contract require it.
+- Do not assume SSR dynamic routes appear in sitemap output automatically.
+
+## Content SEO Feed Policy
+
+- Every frontmatter field used by routes, SEO, RSS, sitemap, pagination, filtering, or canonical URLs must be declared in the content collection schema.
+- Treat changing a content filename, collection id, or frontmatter slug as a public URL change. Existing public content needs a redirect or explicit canonical decision.
+- Draft filtering must be consistent across index pages, detail route generation, tag pages, author pages, pagination, RSS, sitemap customization, and custom page lists.
+- Filter drafts before sorting and paginating content.
+- Build canonical URLs from Astro URL primitives such as `Astro.site`, `Astro.url`, or page URL values. Do not hand-concatenate `site`, `base`, paths, and slashes.
+- Allow frontmatter canonical overrides only for explicit external originals, syndication, or documented canonical exceptions.
+- RSS item links must match actual generated public route paths and the project's trailing-slash policy.
+- Do not use page-glob RSS helpers to bypass content schema validation when the project already has content collections.
+- Keep full-content RSS behind sanitizer and absolute URL handling for internal links, images, and MDX/HTML output. Prefer excerpt feeds when that boundary is absent.
+- Sitemap output must contain public canonical URLs only and must exclude drafts, private routes, noindex routes, and unrelated on-demand paths.
+- If sitemap custom pages are used, check them against canonical, draft, trailing-slash, base, and locale policy.
+
+## Review Rejection Criteria
+
+Reject or revise a change when:
+
+- A framework island is added without proving framework state or lifecycle is required.
+- `client:load` is used for content-heavy, below-the-fold, static, or non-urgent UI.
+- `client:only` is used because SSR broke, instead of isolating the browser-only dependency.
+- Static output dynamic routes lack `getStaticPaths`.
+- On-demand or SSR dynamic routes use `getStaticPaths`.
+- Route params do not match bracket names or are not strings.
+- A content slug with `/` is mapped through a non-rest route.
+- Draft filtering differs between lists, detail pages, RSS, sitemap, or pagination.
+- Canonical URLs are built by ad hoc string concatenation.
+- RSS or sitemap includes drafts, stale paths, wrong trailing slash paths, or paths that the route ledger cannot produce.
+- A schema-used frontmatter field is read without being declared in the content schema.
+- Runtime request data is placed into build-time content collections.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Build-time and runtime data are separated.
+- Client JavaScript is limited to needed islands.
+- Route, endpoint, canonical URL, RSS, sitemap, draft, and content schema impact is known.
+- SSR or adapter changes are verified or reported.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing framework validation, route preview, content schema, RSS, sitemap, canonical, or client bundle verification intents when relevant.
+
+When verifiable, report counts for added hydration directives, added island risk, generated public content pages, excluded drafts, RSS items, sitemap URLs, and duplicate canonical URLs.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If an island is added only to work around static markup, revisit the markup and content boundary first.
+- If SSR is requested without adapter evidence, stop and report the deployment contract gap.
+- If content schema drift appears, fix schema and sample content before adding more pages.
+- If draft, canonical, RSS, sitemap, or pagination drift appears, fix the shared content and route contract before adding new entries.
+- If a route collision appears, resolve the route ledger before changing unrelated rendering code.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Build/runtime, route, endpoint, content, hydration, canonical, RSS, sitemap, and draft notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Astro risk

package/templates/default/locales/en/.mustflow/skills/auth-permission-change/SKILL.md

@@ -0,0 +1,194 @@
+---
+mustflow_doc: skill.auth-permission-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: auth-permission-change
+description: Apply this skill when authentication, authorization, permissions, roles, tenants, sessions, JWTs, OAuth or OIDC, API keys, route guards, admin access, database policies, or object-level access control are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.auth-permission-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Auth Permission Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep authentication and authorization separate, enforce permissions on the server or database for every protected request, and prevent client-only guards from being treated as a security boundary.
+
+Authentication answers who the requester is. Authorization answers what that principal can do to this resource in this tenant right now. Login state, verified email, a valid JWT, a visible admin button, or a client redirect is not permission.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Authentication, authorization, role, permission, capability, policy, tenant, workspace, organization, session, JWT, OAuth, OIDC, API key, invite, reset token, route guard, admin, impersonation, audit, or database policy behavior changes.
+- A route, resolver, controller, service, command handler, job, webhook, API client, generated SDK, UI guard, or database query starts relying on user, tenant, role, ownership, membership, or resource identity.
+- A change affects object-level access control, multi-tenant isolation, shared resources, signed URLs, exports, search, autocomplete, background jobs, webhooks, or admin/support tooling.
+- A change modifies status code behavior for auth failures, especially 401, 403, or policy-driven 404.
+- A permission model, role matrix, API docs, admin docs, migration, or tests need to stay aligned with authorization behavior.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only password hashing, cryptography, secure transport, secret handling, or generic privacy review with no auth or permission boundary; use `security-privacy-review`.
+- The task only adds abuse-case tests after a boundary is already understood; use `security-regression-tests` for that part.
+- The task only changes UI text for a public page and does not affect route guards, server checks, roles, sessions, or access decisions.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Changed files, user goal, affected actors, protected resources, actions, tenants, roles, and status-code expectations.
+- Auth middleware, framework hooks, gateway checks, session config, cookie config, JWT verifier, OAuth/OIDC callback, API key verifier, and logout or revocation code when relevant.
+- Route guards, client guards, server controllers, resolvers, command handlers, services, policy functions, role or permission tables, database queries, RLS, views, stored procedures, and ORM scopes.
+- Tenant, organization, workspace, project, membership, invite, suspension, ownership, sharing, and admin-support data models.
+- Background jobs, queue payloads, webhooks, import/export flows, search or autocomplete indexes, signed URL generation, storage keys, CDN cache, and permission caches when they can expose protected data.
+- Audit logs, admin action logs, impersonation records, denied-access logs, API docs, role matrix docs, migrations, and tests.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Classify the change as authentication, authorization, or both before editing.
+- Identify principal, tenant, resource, action, and context for each protected operation.
+- Treat client-provided `userId`, `tenantId`, `workspaceId`, `role`, `isAdmin`, object id, API key label, token claim, and local storage value as untrusted.
+- Find the current policy source of truth. If authorization is scattered across routes, do not add another scattered condition without first considering a central policy function.
+- Know whether the product intentionally hides resource existence with 404 or exposes permission denial with 403.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten server-side authorization checks, policy functions, database scopes, RLS, query constraints, audit logs, docs, and tests.
+- Adjust client guards only as UX, and only while keeping or adding server/database enforcement.
+- Add role or permission migration logic only with deny-by-default behavior and explicit backfill rationale.
+- Keep docs, generated clients, role matrices, status-code behavior, and tests synchronized with changed auth behavior.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the boundary:
+   - authentication: verifies a principal from a session, JWT, OAuth/OIDC account, API key, service account, or anonymous state;
+   - authorization: decides whether that principal can perform an action on a resource within a tenant and context.
+2. Read the mandatory surfaces that apply:
+   - auth middleware, hooks, gateway, session store, cookies, JWT, OAuth/OIDC, API key verification, logout, revocation, and token rotation;
+   - route guards, client redirects, server controllers, resolvers, services, command handlers, policy calls, and admin tools;
+   - tenant resolver, membership schema, role assignment, invite flow, suspension, ownership, sharing, and impersonation model;
+   - database queries, tenant scopes, ownership joins, soft-delete filters, RLS, views, stored procedures, and ORM helpers;
+   - background jobs, queues, webhooks, import/export, file storage, signed URLs, search, autocomplete, caches, audit logs, docs, migrations, and tests.
+3. Write the permission decision inputs for each protected action: principal, tenant, resource, action, and context.
+4. Separate identity from permission:
+   - `req.user`, a valid session, verified email, valid JWT, OAuth scope, or API key proves identity only;
+   - owner, active member, org admin, global admin, support user, service account, API client, and shared-link viewer need separate authorization rules.
+5. Prefer one central policy shape, such as a `can(principal, action, resource, context)` function, over route-local `isAdmin`, `isOwner`, or `isMember` fragments.
+6. Enforce deny by default. New roles, actions, resource types, tenant types, sharing modes, and admin paths must deny until explicitly allowed.
+7. Validate every request. Do not rely on login-time checks, client guards, disabled buttons, hidden menus, generated types, OpenAPI docs, or mobile local checks.
+8. Load resources safely before final authorization:
+   - include tenant, membership, owner, sharing, and soft-delete constraints in the resource lookup when possible;
+   - when existence must be hidden, keep wrong-tenant and missing-resource behavior consistent with the project's 404 policy.
+9. Check multi-tenant risks:
+   - body, query, header, path, JWT claim, or local storage tenant ids must not become trusted tenant context;
+   - tenant-scoped queries must include tenant or membership constraints;
+   - pending, suspended, removed, revoked, deleted, disabled, and invited states must not be treated as active access;
+   - shared links, exports, signed URLs, previews, search, cache, and CDN entries must stay inside the permission model.
+10. Check session, JWT, OAuth/OIDC, and API key contracts when touched:
+   - sessions need expiry, refresh, rotation, logout, revocation, cookie flags, and CSRF posture;
+   - JWTs need signature verification, algorithm allowlist, issuer, audience, subject, expiry, not-before, key rotation, and stale-claim handling;
+   - OAuth/OIDC needs exact redirect binding, state, nonce, PKCE when relevant, provider account binding, and safe account linking;
+   - API keys need hashing, prefix-only display, owner type, scope, tenant/resource constraints, expiry, rotation, revocation, last-used, rate limit, and audit.
+11. Check dependent surfaces: API routes, controllers, services, DB schema, DB queries, RLS, UI navigation, UI actions, API clients, audit logs, notifications, jobs, webhooks, search, file storage, docs, migrations, monitoring, and tests.
+12. Require denial-first tests for changed protected actions when the project has a usable test surface. Cover anonymous, expired, revoked, no role, wrong tenant, wrong owner, suspended or removed member, stale cache, shared-link, read-only API key, org admin, global admin, and impersonating admin cases as applicable.
+13. Update docs and role matrices when external behavior, status codes, role names, permission names, admin scope, or API errors change.
+14. Report the policy source of truth, server/database enforcement, client UX-only guards, test coverage, skipped checks, and remaining permission risk.
+
+## Boundary Rules
+
+- Client guards are UX only. They may hide buttons, menus, and pages, but they do not authorize API calls.
+- Route middleware may perform coarse authentication and tenant resolution, but final resource/action authorization belongs in server policy, service authorization, gateway policy, or database policy.
+- Database RLS, tenant-scoped queries, views, and stored procedures are defense-in-depth and may be the strongest final boundary, but they do not excuse unclear application policy.
+- Background jobs, webhooks, imports, exports, and cron paths need actor or service-principal context. User-request paths are not the only permission paths.
+- Admin is scoped. Global admin, org admin, project admin, billing admin, support, and impersonating admin are different roles and need different audit and action rules.
+- Owner is not a wildcard permission. Owners may still lack delete, export, invite, transfer, billing, or admin powers.
+- API keys are principals with scopes and owners, not user sessions with unlimited power.
+
+## Strongly Forbidden Patterns
+
+- Treating authentication as authorization.
+- Trusting client-provided `userId`, `tenantId`, `role`, `isAdmin`, `ownerId`, `scope`, price, entitlement, or plan.
+- Relying on hidden buttons, disabled controls, client redirects, mobile checks, TypeScript types, docs, or Storybook examples as permission boundaries.
+- Reading tenant-scoped resources with an object id alone.
+- Treating membership row existence as active membership without checking status.
+- Treating OAuth provider scopes as internal app permissions.
+- Treating JWT role claims as fresh authorization after role changes.
+- Treating API keys as normal user sessions.
+- Mixing org admin, global admin, support admin, and impersonation into one `admin` check.
+- Changing 403 to 404, or 404 to 403, without naming the information-disclosure policy.
+- Relaxing permissions without denial-case tests or a written migration and audit plan.
+- Letting role changes ship without permission-cache or token-staleness handling.
+- Creating shared links, signed URLs, exports, search results, or CDN responses outside tenant and resource policy.
+- Logging impersonation without separate actor and subject.
+- Backfilling broad permissions to every existing user because migration is easier.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Authentication and authorization are separated in code and report language.
+- Every changed protected action has a server-side or database-side permission boundary.
+- Tenant isolation, resource ownership, sharing, admin scope, and status-code behavior are explicit.
+- Client guards are described as UX only.
+- Session, token, OAuth/OIDC, API key, cache, audit, docs, migration, and tests are synchronized when touched.
+
+<!-- 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`
+
+Prefer the narrowest configured test intent that covers the changed protected actions and denial cases. Report missing auth-specific policy tests, tenant-isolation tests, token/session tests, API-key tests, cache-staleness tests, audit-log checks, docs validation, or database-policy verification when relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the current policy source of truth is unclear, stop and report the competing policy locations before adding more checks.
+- If a server check is missing and only the UI hides the action, treat it as incomplete work, not as authorization.
+- If a tenant-scoped query lacks tenant, membership, ownership, sharing, or RLS coverage, fix the data access path before broadening features.
+- If denial tests cannot be written in the current task, report the exact untested actor, tenant, resource, action, and context combinations.
+- If the change relaxes permissions, changes status-code policy, or broadens admin/API-key behavior, call out the security risk and required verification.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Authentication versus authorization classification
+- Principal, tenant, resource, action, and context affected
+- Policy source of truth
+- Server/database enforcement notes
+- Client guard UX-only notes
+- Tenant, ownership, sharing, admin, token/session/API-key, cache, and audit notes
+- Tests or denial cases covered
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining auth or permission risk

package/templates/default/locales/en/.mustflow/skills/config-env-change/SKILL.md

@@ -0,0 +1,189 @@
+---
+mustflow_doc: skill.config-env-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: config-env-change
+description: Apply this skill when environment variables, config keys, secrets, public env prefixes, build-time or runtime config, config schemas or parsers, feature flags, deployment variables, CI secrets, Docker or Compose env, Kubernetes ConfigMaps or Secrets, Cloudflare bindings, Vite, Next.js, Astro, SvelteKit, Tauri, Node, Bun, generated env types, .env examples, config docs, or config validation behavior are created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.config-env-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Config Env Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep configuration and environment changes from leaking secrets, freezing runtime values at build time, or drifting across local, CI, and deployment surfaces.
+
+A config or env change is not just adding a key. It is deciding who can see the value, when the value is fixed, where the value is validated, how errors are redacted, and which deployment surfaces must change together.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A task adds, removes, renames, defaults, validates, documents, or reports an env var, secret, config key, feature flag, runtime setting, build define, platform binding, or deploy variable.
+- Code reads from `process.env`, `import.meta.env`, `Bun.env`, framework env helpers, worker bindings, CI variables, Docker env, Kubernetes env, platform env stores, mobile or desktop packaged config, or app updater config.
+- A change touches `.env.example`, `.env.template`, `.env.test`, `.dev.vars.example`, config schemas, config parsers, generated env types, deployment docs, CI workflow env, Docker Compose env, Kubernetes ConfigMap or Secret, Terraform or Pulumi env wiring, or hosting provider config.
+- A final report claims a config key is public, private, runtime, build-time, optional, required, secret, safe to expose, changed without rebuild, or controlled by a feature flag.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only changes product behavior behind an existing config value and the config contract is untouched.
+- The task only edits command-intent environment policy in `.mustflow/config/commands.toml`. Use `command-contract-authoring` for that primary scope.
+- The task only reviews a broad sensitive-data change without config or env surfaces. Use `security-privacy-review`.
+- The task only changes release publication variables for a remote registry or channel. Use `release-publish-change` for that primary scope and this skill only if env behavior itself changes.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Key name, value meaning, sensitivity, visibility, timing, required environments, owner, default, validation shape, and removal or deprecation plan if replacing another key.
+- Read-first surfaces: env examples, config schema or parser, runtime config loader, framework env conventions, CI variables or secrets, Docker or Compose config, Kubernetes or cloud config, typed env helpers, deployment docs, and tests.
+- Platform timing: build-time, startup runtime, request runtime, command runtime, tenant runtime, packaged-app time, or provider-evaluated feature flag.
+- Visibility boundary: server-only, client bundle, static asset, sourcemap, mobile app, desktop app, container image, CI log, cloud dashboard, telemetry, or user-visible docs.
+- Verification options from the command contract for config validation, build, tests, docs, package or template release, and secret redaction checks.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and the command contract have been checked for the current scope.
+- The config source of truth is identified before editing. If several files define the same key differently, resolve authority before adding another copy.
+- Real secrets are not read, printed, copied, committed, or requested unless the user explicitly authorizes a secret-handling task and the active rules allow it.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update config schemas, parser code, runtime loader wiring, generated type expectations, example env files with fake values, deployment docs, tests, CI or deployment variable names, and feature-flag defaults directly required by the config change.
+- Add redacted validation errors that name the key and expected shape without printing the value.
+- Add migration aliases, deprecation warnings, or removal notes when replacing keys.
+- Do not commit real `.env` files, private keys, tokens, service account JSON, production connection strings, or secret values.
+- Do not add unchecked raw env reads outside the central parser unless the repository already has a narrower pattern and the exception is documented.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the value before editing:
+   - Sensitivity: public config, private server secret, credential, internal topology, business rule, user-specific setting, or feature flag.
+   - Visibility: server-only, client bundle, static output, packaged mobile or desktop app, container image, CI log, telemetry, or docs.
+   - Timing: build-time, startup runtime, request runtime, command runtime, tenant runtime, packaged-app time, or feature-flag provider runtime.
+   - Mutation action after value change: no action, process restart, pod rollout, container redeploy, static rebuild, app rebuild, store release, or flag flip.
+2. Read existing env and config surfaces before adding a key.
+   - Env examples and test env files.
+   - Config schema or parser.
+   - Runtime loader and central config object.
+   - Framework env helpers and bundler defines.
+   - CI, Docker, Compose, Kubernetes, cloud platform, and hosting provider wiring.
+   - Generated env types and docs.
+   - Tests for missing, malformed, defaulted, successful, and redacted behavior.
+3. Treat public prefixes as exposure markers, not security.
+   - `VITE_`, `NEXT_PUBLIC_`, `PUBLIC_`, client env, frontend build defines, static JSON, mobile resources, and desktop app resources are public or effectively public.
+   - Do not put secrets, privileged internal URLs, signing keys, service credentials, tenant maps, entitlement gates, pricing gates, webhook secrets, or admin tokens in public or packaged surfaces.
+4. Separate build-time from runtime.
+   - Values inlined into frontend bundles, static builds, package resources, or build defines usually require rebuild and redeploy to change.
+   - Runtime values read from server process env, worker bindings, platform secrets, mounted secret volumes, or provider flags may still require restart, pod rollout, or deployment depending on platform.
+   - Do not promise that changing an env var will affect already built client JavaScript, static HTML, mobile apps, desktop apps, or container image defaults.
+5. Validate through the central parser.
+   - Parse booleans explicitly. The string `false` must not become truthy behavior.
+   - Validate numbers with ranges, URLs with protocol and host expectations, paths with safe path rules, enums with allowlists, and secrets with presence and format checks only.
+   - Keep validation errors redacted. Show key name and expected shape, not actual value.
+6. Update every dependent surface for a new key.
+   - Schema validation, runtime loader, type definitions, safe defaults, fake-value env examples, local setup docs, deploy docs, tests, CI variables or secrets, Docker or Compose, Kubernetes or cloud config, observability redaction, and rollback or restart notes.
+   - If a surface is not updated because it is outside scope, report it as deferred with risk.
+7. Handle framework-specific env boundaries conservatively.
+   - Vite and Next public prefixes are client bundle exposure.
+   - SvelteKit static env helpers are build-time; dynamic helpers are runtime.
+   - Astro env should distinguish client or server and public or secret schema.
+   - Cloudflare Worker secrets and bindings arrive through runtime `env`; plaintext vars are not secret storage.
+   - Docker `ARG` and baked `ENV` are not secret storage.
+   - Compose interpolation env is not the same as container env.
+   - Kubernetes env vars are captured at pod start; mounted config may update differently.
+   - Tauri, mobile, and desktop packaged config should be treated as public because users can inspect app artifacts.
+8. Treat feature flags as contracts.
+   - The default value is real product behavior when the provider is down, cache is empty, or local dev is offline.
+   - Kill switches should be runtime-controllable unless the runbook explicitly accepts rebuild delay.
+   - Rollouts should use stable user, tenant, org, or device keys, not per-request randomness.
+   - Sensitive authorization must use server evaluation as source of truth.
+   - New flags need owner, expiry or cleanup issue, default, provider-down behavior, and client/server divergence tests when relevant.
+9. Detect config drift.
+   - Schema key missing from examples.
+   - Deploy key missing from schema.
+   - Secret-looking key with public prefix.
+   - Runtime docs for a build-time value.
+   - Staging missing keys required in production.
+   - Tests depending on private `.env.local`.
+   - Compose `.env` used for interpolation but not passed into the container.
+   - Kubernetes env var changed with no rollout note.
+   - Worker binding only present in production.
+   - Mobile or desktop package containing privileged credentials.
+10. Keep fallbacks safe.
+   - Local and test defaults must not silently connect to production services.
+   - Optional integrations may validate lazily, but must fail clearly at first use.
+   - Core values such as database, auth, session, encryption, signing, queue, and required external APIs should fail fast at startup or command start.
+11. Select verification from configured command intents. Prefer config validation, build, typecheck, related tests, docs validation, release/package checks, and secret-redaction checks when exposed by the command contract. Do not infer raw package manager, cloud, Docker, Kubernetes, or CI commands.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Each changed key has sensitivity, visibility, timing, validation, default, owner, required environments, and change-action classification.
+- Schema, loader, examples, docs, generated types, tests, CI/deploy surfaces, and redaction behavior are synchronized or explicitly deferred.
+- Public prefixes and packaged app surfaces contain no secrets.
+- Build-time and runtime behavior are described accurately.
+- Feature flag defaults and provider-down behavior are classified when flags are involved.
+
+<!-- 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`
+
+Prefer narrower configured config-schema, env-validation, type-generation, deployment-doc, release-template, and secret-redaction intents when the command contract exposes them.
+
+Do not infer commands from package manager files, Docker files, cloud config, framework config, or CI workflow names. Report missing command-intent coverage instead.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a value might be secret and the visibility is unclear, classify it private until proven public.
+- If build-time or runtime timing is unclear, do not promise hot config changes. Report the rebuild, restart, redeploy, rollout, or release uncertainty.
+- If schema, example, docs, tests, and deploy surfaces disagree, fix the source of truth first and report any deferred surface.
+- If validation would print a value, redact it before continuing.
+- If a feature flag default is unknown, do not claim provider-down behavior is safe.
+- If a real secret appears in tracked files, stop ordinary work and report the secret exposure according to repository security rules.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Keys or flags changed
+- Sensitivity, visibility, timing, and required action after value change
+- Source of truth and synchronized surfaces
+- Public/private boundary and redaction notes
+- Build-time versus runtime classification
+- Feature flag default and provider-down behavior when relevant
+- Command intents run
+- Skipped checks and reasons
+- Remaining config/env risk