mustflow 2.115.5 → 2.115.11

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

@@ -0,0 +1,327 @@
+---
+mustflow_doc: skill.php-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: php-code-change
+description: Apply this skill when PHP source, Composer packages, Laravel or Symfony applications, Eloquent or Doctrine persistence, PHP-FPM, OPcache, Octane, RoadRunner, Swoole, Messenger or queue workers, authentication, sessions, uploads, database concurrency, tests, or PHP deployment behavior are created, changed, reviewed, migrated, or upgraded.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.php-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# PHP Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve PHP language, Composer, dependency injection, request lifetime, ORM, transaction, input,
+authentication, session, filesystem, worker, FPM, OPcache, container, and deployment contracts.
+Do not let PHP-FPM's request reset hide stateful design that leaks users or resources under Octane,
+RoadRunner, Swoole, Messenger, queue workers, persistent connections, or other long-lived processes.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- PHP source, Composer metadata or lockfiles, autoloading, extensions, static analysis, tests,
+  framework bootstrap, console commands, queues, scheduled jobs, or package APIs change.
+- Laravel, Symfony, Eloquent, Doctrine, service containers, middleware, events, cache, sessions,
+  authentication, authorization, uploads, validation, serialization, or database behavior changes.
+- PHP-FPM pools, OPcache, web-server/FastCGI integration, containers, health probes, timeouts,
+  long-running workers, deployment caches, migrations, or rollout behavior changes.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is framework-free frontend code or another language with no PHP runtime boundary.
+- Only SQL schema or database operations change and PHP behavior is unaffected; use the narrower
+  data or migration skill.
+- The task asks only for the current PHP, Laravel, Symfony, or Doctrine version; use
+  source-freshness guidance unless code or durable documentation changes too.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- PHP version source, supported runtime range, required extensions, Composer metadata and lockfile,
+  autoload rules, framework and ORM versions, static-analysis level, test config, CI and image.
+- Execution model: PHP-FPM, CLI, server, Octane, RoadRunner, Swoole, queue worker, Messenger,
+  scheduled job, persistent process, or mixed deployment.
+- Request and state ledger: container scope, request/user/tenant state, globals, statics, singleton
+  fields, ORM unit of work, sessions, caches, connections, files, timers, buffers, and reset owners.
+- Security ledger: input sources, validation, output context, SQL, commands, paths, uploads,
+  deserialization, secrets, passwords, authentication, CSRF, session lifetime, and proxy trust.
+- Data ledger: query count, rows and bytes, hydration, lazy loading, transaction owner, connection,
+  locks, unique constraints, optimistic versions, retries, outbox, pagination, and batch ownership.
+- Runtime ledger: FPM mode and limits, OPcache policy, timeouts, web server, probes, container
+  resources, deployment cache generation, worker reload, observability, and rollback.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Read repository PHP, Composer, framework, ORM, extension, deployment, and test evidence before
+  using current APIs or migration guidance.
+- Refresh official PHP, Composer, Laravel, Symfony, Doctrine, web-server, database, and platform
+  sources before preserving exact version, default, deprecation, security, or support claims.
+- Treat version research as a dated snapshot. The official-source snapshot reviewed on 2026-07-11
+  identified PHP 8.5.8 as stable and PHP 8.6.0 Alpha 1 as prerelease; recheck the current stable,
+  supported branches, migration guides, and each feature's actual release status before reuse.
+- Identify whether process state ends after one request. Treat every service as potentially reused
+  until the selected runtime proves request-scoped destruction.
+- Apply narrower auth, upload, transaction, cache, queue, logging, performance, or deployment skills
+  when those boundaries materially change.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Make focused PHP, Composer, framework, ORM, config, test, deployment, and docs changes required by
+  the task.
+- Add explicit DTOs, query objects, reset hooks, transaction owners, validation, session controls,
+  performance instrumentation, or deployment checks where they protect changed behavior.
+- Preserve supported PHP versions and framework conventions unless migration is explicit.
+- Do not hide failures by lowering static analysis, disabling tests, granting broad filesystem
+  permissions, enabling unsafe deserialization, widening session scope, or raising resource limits
+  without evidence.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. **Classify runtime and package contracts.**
+   - Record PHP SAPI, version, extensions, Composer platform requirements, autoload roots, scripts,
+     plugins, package type, framework, ORM, worker model, image, and deployment target.
+   - Treat Composer scripts and plugins as executable supply-chain boundaries. Review lockfile,
+     platform checks, extension requirements, optimized autoload, authoritative classmaps, and
+     packaged files separately from source-tree success.
+   - Keep library dependency ranges compatible and application environments reproducible. Commit
+     application lockfiles, use `composer install` in CI and deployment, and validate the lock
+     rather than resolving a fresh graph during release.
+   - Treat repository priority, canonical repositories, package names, `replace`, `provide`,
+     `conflict`, stability flags, Composer plugins, and `autoload.files` as supply-chain behavior.
+     Do not assume a dependency's `repositories` configuration propagates to the root project.
+   - Use `composer why` and `why-not` before widening constraints or deleting a lockfile. Verify the
+     built artifact with real platform requirements; `config.platform` and
+     `--ignore-platform-reqs` do not prove that production has the required PHP or extensions.
+   - Enforce PSR-4 path and case correctness on a case-sensitive CI filesystem and detect ambiguous
+     classes. Optimize production autoloading, but use authoritative classmaps only after proving
+     that runtime-generated proxies or classes do not depend on fallback discovery.
+2. **Keep dependencies and state ownership visible.**
+   - Confine container access and service location to composition roots. Prefer constructor
+     injection of narrow contracts over global helpers, facades, or arbitrary container lookup.
+   - Add layers only where policy, representation, transaction, authorization, or replacement
+     changes. Remove pass-through controller, action, service, manager, and generic repository
+     chains that hide cost without owning a boundary.
+   - Keep request, user, tenant, locale, auth, and transaction state out of singleton and static
+     fields. Pass request values explicitly or use a resettable request-scoped owner.
+   - For long-lived runtimes, reset application state, ORM units of work, log buffers, caches,
+     files, connections, and framework services between jobs or requests. Bound worker lifetime and
+     reload workers during deployment.
+3. **Separate ORM entities from external contracts.**
+   - Do not use Eloquent models or Doctrine entities as universal API, queue, event, cache, or
+     integration payloads. Define whether a queued job needs an identifier and execution-time state
+     or an immutable publication-time snapshot.
+   - Keep business invariants in explicit application or domain operations. Do not hide critical
+     payments, stock, authorization, or external effects in model listeners whose execution differs
+     across bulk update, delete, flush, or import paths.
+   - Use transactional outbox and idempotent consumers for external side effects.
+4. **Measure query shape, not only query count.**
+   - Detect N+1 by request-level query count, normalized fingerprints, total DB time, rows, bytes,
+     and result-size scaling. Make unexpected lazy loading fail in development or tests.
+   - Do not replace N+1 with an unbounded eager-loaded graph or multi-collection join explosion.
+     Page parent identifiers first and batch child, aggregate, or projection queries deliberately.
+   - Use entities for behavior-changing writes. Use DTO, scalar, array, DBAL, or query-builder
+     projections for lists, reports, exports, counts, and read-only views.
+   - Use bounded iteration, keyset or cursor pagination, stable unique tie-breakers, and unit-of-work
+     clearing for large datasets. Avoid deep OFFSET and per-request exact counts without product need.
+   - Avoid `fetchAll()` and full ORM hydration for large streams. Select only required columns,
+     choose an explicit fetch mode, and account for driver buffering, identity maps, and connection
+     restrictions while an unbuffered result remains open.
+5. **Own transactions and concurrency at the use case.**
+   - Let one business operation own begin, commit, rollback, retry, and the shared connection.
+     Nested work cannot commit independently; use explicit savepoints only when supported and intended.
+   - Keep HTTP, email, queue publication, and long computation outside row-locking transactions.
+     Store business data and outbox records atomically, then publish after commit.
+   - Enforce uniqueness and invariants with database constraints and atomic updates or upserts.
+     Treat check-then-insert and read-compute-write as races.
+   - Verify affected rows, optimistic versions, lock scope, index support, and deterministic lock
+     order. Retry the whole transaction on classified deadlock or serialization failure with a
+     bounded backoff; never repeat only the final statement with stale reads.
+   - Persistent PDO connections require explicit cleanup of transactions, locks, temporary state,
+     and session settings before reuse.
+6. **Validate input by meaning and encode output by context.**
+   - Avoid loose comparison for authentication, tokens, signatures, hashes, identifiers, and
+     security decisions. Use strict types and constant-time comparison where secret equality matters.
+   - Distinguish filtering from validation. Normalize only according to a named domain rule and
+     preserve missing, empty, null, zero, and false as different states where the contract does.
+   - Use parameterized SQL for values and allowlists for identifiers, sort direction, table,
+     column, operator, and dynamic query structure.
+   - Avoid `extract()`, variable variables, mass assignment, and broad array-to-object hydration at
+     trust boundaries. Define allowed fields and nested shapes explicitly.
+   - Encode output for HTML text, attributes, URLs, JavaScript, JSON, headers, and logs at the final
+     sink; one escaping function does not fit every context.
+7. **Harden files, commands, serialization, and secrets.**
+   - For uploads, validate authorization, size, count, extension, MIME, magic bytes, image or archive
+     structure, decompression limits, generated server-side names, storage outside executable roots,
+     and safe download headers. Never trust the client filename or MIME alone.
+   - Canonicalize and constrain filesystem paths against an owned root, accounting for symlinks,
+     races, archive traversal, stream wrappers, and web-server handlers.
+   - Avoid shell construction. Use argument-safe process APIs, narrow executable allowlists,
+     timeouts, bounded output, environment control, and least OS privilege.
+   - Do not `unserialize()` untrusted data. Use explicit schemas; when signed client state is
+     unavoidable, authenticate integrity and separate confidentiality requirements.
+   - Keep secrets out of errors, dumps, logs, phpinfo, source control, build artifacts, caches, and
+     browser-visible configuration.
+8. **Harden passwords, authentication, and sessions.**
+   - Use supported password APIs and sufficient storage width. Account for bcrypt's byte limit,
+     reject over-limit input rather than truncating, avoid silent normalization, and rehash after
+     successful login when policy changes.
+   - Keep unknown-account and wrong-password responses, status, shape, and expensive hash path
+     comparable. Apply bounded risk-based throttling without creating an attacker-controlled
+     permanent account lock.
+   - Generate reset and verification URLs from a configured trusted origin. Store token hashes,
+     enforce short expiry and single use, and revoke affected sessions after sensitive changes.
+   - Enable strict session-ID handling, cookie-only transport, secure cookie attributes, ID rotation
+     at privilege changes, and a concurrency-safe transition from old IDs.
+   - Treat SameSite as defense in depth, not CSRF authorization. Protect state-changing and login
+     requests with CSRF tokens and origin checks as appropriate.
+   - Enforce idle, absolute, renewal, revocation, and recent-authentication policy server-side;
+     garbage collection and cookie expiry are not authentication policy.
+9. **Design cache and middleware cost explicitly.**
+   - Include tenant, locale, currency, authorization visibility, query shape, and schema version in
+     cache identity. Avoid caching ORM entities.
+   - Prevent stampedes with jitter, locks, stale-while-revalidate, and one refresh owner.
+   - Keep global middleware and subscribers limited to truly universal work. Measure auth, tenant,
+     session, locale, feature flag, audit, and activity-update costs by route.
+   - Release a file-backed session lock as soon as session mutation is complete. Do not hold one
+     user's parallel requests behind database, HTTP, upload, or other slow work.
+10. **Measure algorithm, allocation, and discovery cost before micro-optimizing.**
+    - Profile representative data sizes and concurrency with wall time, CPU, allocations, peak RSS,
+      I/O waits, and tail latency. Do not trade clarity for `isset()`-scale folklore while quadratic
+      copying, serialization, locks, or network waits dominate.
+    - Avoid repeated `array_merge()` accumulation and front-removal with `array_shift()` in growing
+      loops. Append directly, merge once, use a cursor, or choose a queue with the required
+      complexity while preserving numeric and string key semantics.
+    - Remember that PHP arrays are ordered maps, not compact primitive vectors. Avoid retaining
+      millions of rows or duplicate numeric and associative PDO keys; benchmark specialized
+      structures before accepting their compatibility and maintenance cost.
+    - Collapse filter-map-reindex chains when intermediate arrays dominate memory. Use generators
+      or streaming only when every downstream stage also remains bounded; laziness does not repair a
+      consumer that collects the whole result again.
+    - Rely on copy-on-write for ordinary read-only arguments instead of adding references as a
+      speculative optimization. Minimize aliases, return explicit result objects instead of output
+      parameters, and `unset` a reference variable immediately after reference iteration.
+    - Bound adversarial input before regular expressions and remove ambiguous nested repetition.
+      Check regex failure separately from no-match; raising backtracking limits is not a fix for
+      catastrophic backtracking.
+    - Compile route, container, event, serialization, template, and class discovery metadata during
+      build or cache warmup where supported. Account for autoload side effects from `class_exists()`,
+      and instantiate delayed attributes in CI so invalid targets do not wait for first traffic.
+    - Observe OPcache capacity, cached scripts, wasted memory, hit rate, and restart causes. Do not
+      infer health from `opcache.enable` alone, and do not assume JIT improves framework or I/O-bound
+      workloads without a representative benchmark.
+11. **Tune FPM, OPcache, web server, and containers from evidence.**
+    - Bound FPM concurrency by the smallest of memory, CPU/tail-latency, and downstream connection
+      budgets. Choose static, dynamic, or ondemand from traffic shape, not container folklore.
+    - Set worker recycling from measured memory growth. Observe listen queue, max-children events,
+      worker RSS, CPU throttling, DB waits, slow logs, and OOM behavior together.
+    - Order database, application, FPM, FastCGI, proxy, and load-balancer timeouts deliberately.
+      Know whether post-response work remains subject to termination and cancellation.
+    - Keep liveness limited to restart-recoverable process failure; use startup and readiness for
+      boot and dependency availability without causing restart storms.
+    - Build or warm environment-independent caches before traffic and environment-dependent caches
+      only after correct configuration exists. Do not let every replica race migrations or mutate
+      a shared cache directory.
+    - Treat OPcache preload and immutable-container assumptions as deployment contracts. Reload
+      FPM and long-running workers when code or cached containers change.
+12. **Apply language and type contracts deliberately.**
+    - Enforce `declare(strict_types=1)` across owned source files, not only entrypoints. Remember that
+      scalar argument coercion follows the calling file, return coercion follows the defining file,
+      and typed-property assignment follows the write site; strict types do not validate domain
+      formats, ranges, or decoded input shapes.
+    - Keep `mixed` at untrusted or dynamic boundaries and narrow it immediately. Layer precise
+      PHPDoc shapes, lists, ranges, callable signatures, generics, conditional returns, and
+      assertions over native runtime types rather than replacing native types with comments.
+    - Prefer `Closure` plus an analyzed signature for stored callbacks. Preserve generic type
+      relationships and collection variance; mutable collections are not automatically covariant.
+    - Fix inaccurate types at their source through native declarations, PHPDoc, stubs, generics,
+      assertions, or analysis extensions. Do not scatter inline `@var` claims or grow a baseline to
+      silence new errors; run the strongest practical rules and make legacy suppressions shrink.
+    - For PHP 8.5 upgrades, verify URI interpretation against the actual consumer, pipe only unary
+      callables, preserve shallow-clone semantics, and test ignored `#[NoDiscard]` results as
+      failures where the return value is contractual. Instantiate delayed attributes during build.
+    - Audit migration warnings and deprecations before changing the runtime, including OPcache
+      loading assumptions, destructuring non-arrays, lossy numeric casts, legacy casts, backtick
+      execution, legacy serialization hooks, null array keys, and changed extension APIs. Keep
+      prerelease-only features out of production code unless the project explicitly targets them.
+13. **Verify framework-specific behavior.**
+    - For Laravel, inspect container and facade use, mass assignment, model events, lazy loading,
+      queue model serialization, after-commit dispatch, cache locks, config/route/view caches,
+      Octane reset behavior, and worker reload.
+    - For Symfony and Doctrine, inspect service scope and reset, kernel subscribers, Messenger
+      redelivery, Doctrine hydration and identity map, flush/listener behavior, cache warmup, and
+      long-running worker reset.
+    - Treat framework cache, ORM, queue, and runtime features as separate version-sensitive tracks.
+14. **Verify the real execution model.**
+    - Cover static analysis, unit and integration tests, query-count growth, transaction conflict,
+      auth/session failure, upload rejection, repeated request/job state reset, FPM/container smoke,
+      worker reload, and production cache behavior according to the changed surface.
+    - Report missing configured intents rather than running raw servers, migrations, deploys,
+      dependency installs, or long-running workers.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Runtime, package, container, request state, ORM, transaction, validation, authentication, session,
+  filesystem, worker, FPM, cache, and deployment ownership are explicit.
+- Code that is safe only because PHP-FPM resets the request is not silently reused in a persistent process.
+- Query and performance claims include rows, hydration, concurrency, memory, and tail-latency evidence.
+- Security decisions do not depend on loose comparison, client metadata, unsafe serialization,
+  cookie expiry, or application-only uniqueness checks.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot intents that cover the changed scope:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the PHP, framework, ORM, SAPI, or worker track is unclear, preserve existing behavior and
+  report the missing evidence.
+- If a performance fix only raises workers, memory, timeout, eager loading, or cache TTL without
+  proving the bottleneck, keep it out and report the missing measurement.
+- If a transaction path includes external side effects, split it behind an outbox or report the
+  atomicity gap before claiming safety.
+- If long-running reset behavior cannot be verified, keep services stateless and report missing
+  repeated-request or repeated-message coverage.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- PHP runtime, Composer, framework, ORM, SAPI, and worker tracks
+- State, security, data, cache, FPM, container, and deployment owners
+- Structural, performance, compatibility, and migration decisions
+- Verification evidence and configured intents run
+- Skipped checks and remaining PHP, framework, persistence, security, or deployment risk

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.python-code-change
 locale: en
 canonical: true
-revision: 5
+revision: 6
 lifecycle: mustflow-owned
 authority: procedure
 name: python-code-change
@@ -127,13 +127,13 @@ Preserve Python runtime, standard-library, packaging, import, architecture, asyn
    - rebuild large dicts after bulk deletion when long-lived memory and iteration cost matter;
    - avoid eager default factories hidden in `dict.get(key, expensive())` or `setdefault(key, expensive())`.
 15. Treat newer syntax and typing features as semantic tools, not style trophies:
-   - use template string literals only when a handler needs the static and interpolated parts separately, such as SQL builders, shell command objects, logging templates, or markup renderers; do not replace ordinary f-strings when the result is just a string;
-   - when runtime code reads annotations, use the supported annotation inspection API and choose the intended format explicitly instead of assuming `__annotations__` already contains runtime values;
-   - use sentinel values to distinguish "argument omitted" from `None`, but compare sentinels by identity and keep public signatures readable;
+   - use Python 3.14+ template string literals only when a handler needs the static and interpolated parts separately, such as SQL builders, shell command objects, logging templates, or markup renderers; do not replace ordinary f-strings when the result is just a string;
+   - when runtime code reads annotations, use Python 3.14+ `annotationlib` or the official inspection API supported by the declared runtime, and choose the intended format explicitly instead of assuming `__annotations__` already contains runtime values;
+   - use sentinel values to distinguish "argument omitted" from `None`, but compare sentinels by identity and keep public signatures readable; in the official snapshot checked on 2026-07-11, the built-in sentinel facility was Python 3.15+ prerelease-only, so refresh the current release status before adoption;
    - prefer `Mapping` or narrower read-only protocols for read-only inputs so immutable mapping implementations are not rejected accidentally;
-   - use closed or extra-key `TypedDict` forms only when the supported Python and type-checker versions agree with that shape.
+   - use closed or extra-key `TypedDict` forms only when the supported Python and type-checker versions agree with that shape; the Python 3.15-only forms were prerelease-only in the official snapshot checked on 2026-07-11, so refresh status before adoption.
 16. Keep `finally` as cleanup, not outcome selection. Do not add `return`, `break`, or `continue` inside `finally` blocks because they can mask exceptions and cancellation; move result decisions outside cleanup or make suppression an explicit documented contract.
-17. Use explicit lazy imports only for startup-sensitive module-scope dependencies after checking version support and import-time side effects. Do not lazily import plugins, registries, monkey patches, model definitions, ORM mappings, or observability setup whose import side effects are part of startup correctness.
+17. Use Python 3.15+ explicit lazy imports only for startup-sensitive module-scope dependencies after checking version support and import-time side effects. The syntax was prerelease-only in the official snapshot checked on 2026-07-11; refresh the current Python 3.15 release status before placing it in stable-target examples. Do not lazily import plugins, registries, monkey patches, model definitions, ORM mappings, or observability setup whose import side effects are part of startup correctness.
 18. Keep process, archive, and concurrency safety explicit:
    - subprocess calls use argument lists, checked failure handling, timeouts, bounded captured output, and a narrow `shell=True` exception when the project already permits it;
    - archive extraction, including `tarfile`, keeps untrusted archive inspection, extraction filters, partial-extract cleanup, and older-runtime defaults visible;
@@ -215,7 +215,11 @@ Report missing package, type, or test intents rather than inventing raw tool com
 - If build backend, package manager, lockfile, dependency group, optional dependency, or editable-install behavior is ambiguous, keep the existing owner and report the missing packaging contract instead of migrating tools.
 - If the supported Python version blocks a syntax choice, rewrite to the supported form.
 - If the supported Python version blocks a standard-library feature, changed default, diagnostic flag, or helper API, use the supported equivalent or report the runtime-support decision instead of silently raising `requires-python`.
-- If template strings, annotation runtime access, lazy imports, sentinels, immutable mappings, or typed extra keys are useful but version-gated, keep a fallback or report the required support bump instead of smuggling the newer feature into a lower-runtime project.
+- If Python 3.14 template strings or annotation inspection are useful but the project supports older runtimes, keep a fallback or report the required stable-runtime bump.
+- If Python 3.15 lazy imports, built-in sentinels or immutable mappings, or advanced `TypedDict`
+  shapes are useful, first refresh the official release and feature status. When the target remains
+  prerelease, keep them out of stable-target code and examples unless the repository explicitly
+  adopts that prerelease track.
 - If third-party stubs or package metadata are wrong, document the local workaround and keep it narrow.
 - If `Any`, `cast`, `type: ignore`, runtime `Protocol`, or type guard behavior is needed, keep it local, justified, and backed by runtime validation or tests where the type claim can lie.
 - If performance risk appears in collections, generators, copies, or caches, report the input-size assumption or use an existing benchmark/profile intent when configured.

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -546,6 +546,18 @@ route_type = "primary"
 priority = 85
 applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "performance_change", "security_change", "package_metadata_change", "release_risk"]
 
+[routes."ada-code-change"]
+category = "general_code"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "performance_change", "security_change", "package_metadata_change", "release_risk"]
+
+[routes."pascal-code-change"]
+category = "general_code"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "performance_change", "security_change", "package_metadata_change", "release_risk"]
+
 [routes."shell-code-change"]
 category = "general_code"
 route_type = "primary"
@@ -570,6 +582,12 @@ route_type = "primary"
 priority = 85
 applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "migration_change", "security_change", "package_metadata_change", "release_risk"]
 
+[routes."deno-code-change"]
+category = "general_code"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "performance_change", "security_change", "privacy_change", "data_change", "migration_change", "package_metadata_change", "release_risk"]
+
 [routes."docker-code-change"]
 category = "general_code"
 route_type = "primary"
@@ -618,6 +636,12 @@ route_type = "primary"
 priority = 85
 applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
 
+[routes."php-code-change"]
+category = "general_code"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
+
 [routes."powershell-code-change"]
 category = "general_code"
 route_type = "primary"
@@ -918,6 +942,12 @@ route_type = "adjunct"
 priority = 70
 applies_to_reasons = ["performance_change", "code_change", "data_change", "ui_change", "behavior_change"]
 
+[routes."performance-measurement-integrity-review"]
+category = "general_code"
+route_type = "adjunct"
+priority = 79
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "performance_change", "security_change", "privacy_change", "data_change", "docs_change", "package_metadata_change", "release_risk"]
+
 [routes."vertical-slice-tdd"]
 category = "tests"
 route_type = "primary"
@@ -1176,6 +1206,12 @@ route_type = "primary"
 priority = 85
 applies_to_reasons = ["ui_change", "code_change", "behavior_change", "public_api_change", "data_change", "security_change", "privacy_change", "performance_change", "test_change", "docs_change", "migration_change", "package_metadata_change", "release_risk"]
 
+[routes."threejs-code-change"]
+category = "ui_assets"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["ui_change", "code_change", "behavior_change", "public_api_change", "data_change", "security_change", "privacy_change", "performance_change", "test_change", "docs_change", "migration_change", "package_metadata_change", "release_risk"]
+
 [routes."react-code-change"]
 category = "ui_assets"
 route_type = "primary"

package/templates/default/locales/en/.mustflow/skills/skill-authoring/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.skill-authoring
 locale: en
 canonical: true
-revision: 9
+revision: 11
 lifecycle: mustflow-owned
 authority: procedure
 name: skill-authoring
-description: Apply this skill when creating or maintaining `.mustflow/skills/*/SKILL.md` procedures and `.mustflow/skills/INDEX.md` routes.
+description: Apply this skill when creating or maintaining logically rigorous `.mustflow/skills/*/SKILL.md` procedures and `.mustflow/skills/INDEX.md` routes.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -30,6 +30,7 @@ Create narrow, repeatable mustflow skill procedures without turning skills into
 - A `.mustflow/skills/<name>/SKILL.md` file is created, renamed, split, removed, or substantially changed.
 - `.mustflow/skills/INDEX.md` needs a new or updated route for a skill.
 - A skill needs clearer use conditions, exclusion conditions, required inputs, command intent references, verification, or failure handling.
+- A skill contains broad, conditional, exception-bearing, authority-sensitive, or completion claims whose logical scope needs review.
 - A broad prompt, checklist, or outside recommendation needs to be adapted into mustflow's skill format.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -47,6 +48,10 @@ Create narrow, repeatable mustflow skill procedures without turning skills into
 - Existing `.mustflow/skills/INDEX.md` and nearby skill documents.
 - `.mustflow/config/commands.toml` command intent names relevant to verification.
 - Any repository evidence showing that the task is repeatable and not better handled by an existing skill.
+- Nearby rules that can require, forbid, narrow, override, or create exceptions to the proposed procedure.
+- The selected repository boundary for every command intent or verification claim, including any
+  explicit parent-owned dependency.
+- At least one representative positive case and one boundary or counterexample for material rules.
 - Canonical source locale, localization policy, and template metadata when the skill is part of an installed template.
 
 <!-- mustflow-section: preconditions -->
@@ -69,19 +74,34 @@ Create narrow, repeatable mustflow skill procedures without turning skills into
 2. Search existing skills before adding a new one. Prefer updating a matching skill over creating overlapping procedures.
 3. Use a stable folder name and matching frontmatter `name`. Set `mustflow_doc` to `skill.<name>`, `metadata.mustflow_schema` to `"1"`, `metadata.mustflow_kind` to `procedure`, `metadata.pack_id` to the package namespace, and `metadata.skill_id` to `<pack_id>.<name>`.
 4. Write the standard sections: Purpose, Use When, Do Not Use When, Required Inputs, Preconditions, Allowed Edits, Procedure, Postconditions, Verification, Failure Handling, and Output Format.
-5. Run the skill quality gate before accepting the draft: trigger is concrete, non-use boundaries are explicit, required inputs are observable, allowed edits are narrow, procedure steps are actionable, verification names configured intents, failure handling says what to do when evidence is missing, output format matches the evidence expected, overlap with nearby skills is controlled, and template impact is decided.
-6. Reject broad advice disguised as a skill. A skill should not say only "be careful", "write better tests", "sync docs", or "think about security" unless it names a repeatable trigger, source files to inspect, allowed edits, verification, and reporting evidence.
-7. Keep the procedure concrete and bounded. Include what to read, what to change, what to avoid, and what evidence to report.
-8. Reference command intent names only. Do not include raw shell command blocks or claim that the skill authorizes command execution.
-9. Update `.mustflow/skills/INDEX.md` with a compact route that includes trigger, required input, edit scope, risk, verification intents, and expected output.
-10. If the skill is installed by a template, update the canonical skill copy plus installation metadata, package tests, and public docs that list installed files. Do not fan out routine skill edits into every localized skill copy by default; localized skill copies may be absent, and non-source template locales should fall back to the canonical source-locale skill text unless locale-specific skill text is intentionally maintained and translation review is available.
-11. If a portable Agent Skills artifact is part of the task, create or validate it as a derived export, not as the mustflow-native canonical source. Use portable-only top-level fields and string-to-string metadata. A `gh skill publish --dry-run` check may validate the export artifact when available, but `gh skill publish --fix` must be limited to the export directory because it can remove installed provenance metadata and mustflow-native fields.
+5. Normalize material rules before accepting the draft.
+   - Rewrite each material rule mentally as `conditions -> required, allowed, or forbidden action -> observable result`. Keep the prose natural, but make the condition, modality, actor, scope, and result unambiguous.
+   - Distinguish a necessary condition from a sufficient condition. Do not infer the converse: a rule saying `A requires B` does not say that every `B` permits or proves `A`.
+   - Name quantifier and scope when they matter: one item, every item, at least one item, only configured items, the selected repository, the current platform, or another bounded set. Avoid `always`, `never`, `all`, `only`, and equivalent absolutes unless every permitted exception is excluded or explicitly subordinate to a higher-authority rule.
+   - Attach exceptions to the rule they narrow. State whether an exception waives a requirement, permits an action, or changes only reporting; do not let an exception silently authorize commands or erase safety constraints.
+6. Run the logical consistency gate across Purpose, Use When, Do Not Use When, Required Inputs, Preconditions, Allowed Edits, Procedure, Postconditions, Verification, and Failure Handling.
+   - Check whether the same reachable condition both requires and forbids an action. Resolve the contradiction or state the higher-authority discriminator.
+   - Separate different authority dimensions instead of forcing them into one total order. Goal ownership, safety constraints, repository scope, command authority, evidence quality, and preferences can constrain the same action without being interchangeable.
+   - Check reachability and termination. Every required input may be present or missing; every verification may pass, fail, be unavailable, or be skipped; each material branch must lead to an action, handoff, bounded retry, or stop state.
+   - Attack universal and completion claims with a counterexample. Narrow or qualify any claim that one realistic permitted case can falsify.
+   - Require postconditions to be observable from named evidence. A procedure step, local test, workflow success, or report is not proof of a broader state unless the evidence actually covers that state.
+   - Resolve verification intent names against the repository being changed. A shared parent skill
+     does not impose parent-root verification on child-only work; require a parent check only when
+     parent-owned files, orchestration, artifacts, or contracts are direct inputs to the result.
+7. Run the skill quality gate before accepting the draft: trigger is concrete, non-use boundaries are explicit, required inputs are observable, allowed edits are narrow, procedure steps are actionable, verification names configured intents, failure handling says what to do when evidence is missing, output format matches the evidence expected, overlap with nearby skills is controlled, logical branches terminate, and template impact is decided.
+8. Reject broad advice disguised as a skill. A skill should not say only "be careful", "write better tests", "sync docs", or "think about security" unless it names a repeatable trigger, source files to inspect, allowed edits, verification, and reporting evidence.
+9. Keep the procedure concrete and bounded. Include what to read, what to change, what to avoid, and what evidence to report.
+10. Reference command intent names only. Do not include raw shell command blocks or claim that the skill authorizes command execution.
+11. Update `.mustflow/skills/INDEX.md` with a compact route that includes trigger, required input, edit scope, risk, verification intents, and expected output.
+12. If the skill is installed by a template, update the canonical skill copy plus installation metadata, package tests, and public docs that list installed files. Do not fan out routine skill edits into every localized skill copy by default; localized skill copies may be absent, and non-source template locales should fall back to the canonical source-locale skill text unless locale-specific skill text is intentionally maintained and translation review is available.
+13. If a portable Agent Skills artifact is part of the task, create or validate it as a derived export, not as the mustflow-native canonical source. Use portable-only top-level fields and string-to-string metadata. A `gh skill publish --dry-run` check may validate the export artifact when available, but `gh skill publish --fix` must be limited to the export directory because it can remove installed provenance metadata and mustflow-native fields.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - The expected output can be produced with clear evidence, executed command intents, skipped checks, and remaining risks.
 - Any missing command intent, unknown input, or authority conflict is reported instead of hidden.
+- Material rules have bounded scope, explicit exception behavior, reachable failure branches, and observable postconditions.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -100,6 +120,11 @@ If the skill changes tests or behavior-sensitive template output, also use the r
 - If two skills overlap, tighten their use and non-use conditions or merge the duplicate procedure.
 - If a needed command intent is missing, record the missing intent instead of inventing a command inside the skill.
 - If the draft can be applied to almost any task, narrow the trigger or turn the material into workflow guidance instead of a skill.
+- If a reachable condition both requires and forbids the same action, do not hide it behind priority language. Split authority dimensions, add the missing discriminator, or stop with an explicit conflict.
+- If a universal or completion claim fails one realistic permitted counterexample, narrow the claim to the evidence actually established.
+- If a branch can retry, wait, or defer without a bound or stop state, add a termination condition before accepting the skill.
+- If a skill makes a child task depend on parent-root verification without naming a direct parent
+  dependency, remove the cross-root obligation.
 - If translation confidence is low, keep the source skill authoritative and mark translations for review through template metadata.
 
 <!-- mustflow-section: output-format -->
@@ -108,6 +133,7 @@ If the skill changes tests or behavior-sensitive template output, also use the r
 - Skill files added, updated, renamed, or removed
 - Skill index routes changed
 - Quality gate result and overlap decision
+- Logical consistency result, counterexamples checked, and material claims narrowed
 - Command intents referenced
 - Template or localization metadata updated
 - Portable export validation result when relevant

package/templates/default/locales/en/.mustflow/skills/skill-refresh/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.skill-refresh
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: skill-refresh
@@ -135,6 +135,11 @@ source freshness, routing metadata, helper-file alignment, and verification evid
    - official vendor docs or repositories for product behavior;
    - user-provided source text as snapshot-only when live refresh is unnecessary or unavailable.
    Omit or date claims that cannot be checked.
+   - Record feature status separately from package or framework release status: stable,
+     experimental, beta, release candidate, prerelease, deprecated, removed, or
+     compatibility-only.
+   - Do not infer stability from presence in current docs or infer recommendation from a retained
+     compatibility option. Verify the status in the official feature, migration, or config source.
 6. Decide runtime mode before editing frontmatter or fields. Keep mustflow-native metadata for
    mustflow skills. For cross-runtime skills, separate portable guidance from Codex-native,
    Claude-native, or other product-specific extensions instead of mixing incompatible fields.
@@ -199,6 +204,9 @@ source freshness, routing metadata, helper-file alignment, and verification evid
 - Trigger and non-trigger wording is concrete, short enough to route reliably, and checked against
   nearby skills.
 - Runtime-specific behavior is either scoped to the target runtime or excluded from portable mode.
+- Package release tracks and per-feature stability tracks are independently classified, so stable
+  releases do not silently promote experimental features and compatibility shims do not become
+  recommendations.
 - Helper files, examples, routes, template copies, locale metadata, and package surfaces agree.
 - External material is either rewritten as repository-native procedure, attributed where required,
   or omitted.
@@ -243,6 +251,7 @@ package output, public docs, or release-sensitive template output changed.
 - Skill refreshed
 - Runtime mode and behavior contract preserved or changed
 - Sources checked and stale claims omitted or dated
+- Package or framework release track, per-feature status, and owning official source
 - Semantic change classification
 - Package files, helpers, examples, routes, and template surfaces synchronized
 - Version impact decision