mustflow 2.22.49 → 2.23.0

package/package.json

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

package/templates/default/i18n.toml

@@ -56,7 +56,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 81
+revision = 82
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -137,6 +137,12 @@ source_locale = "en"
 revision = 1
 translations = {}
 
+[documents."skill.version-freshness-check"]
+source = "locales/en/.mustflow/skills/version-freshness-check/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.line-ending-hygiene"]
 source = "locales/en/.mustflow/skills/line-ending-hygiene/SKILL.md"
 source_locale = "en"

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

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 81
+revision: 82
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -151,6 +151,7 @@ routes. Event routes stay inactive until their event occurs.
 | Database migration files, schema migration history, ORM schema migrations, generated clients, schema dumps, SQL snapshots, backfills, rolling deploy compatibility, expand-and-contract changes, destructive database changes, migration rollback claims, or production database migration procedures are created, changed, reviewed, or reported | `.mustflow/skills/database-migration-change/SKILL.md` | Source schema, target schema, migration files, migration history, generated clients, schema dumps, SQL snapshots, affected queries, deployment shape, database engine, table size or lock assumptions, backfill plan, rollback type, validation query, and command contract entries | Migration files, ORM schemas, generated clients, schema dumps, SQL snapshots, backfill code, validation checks, seeds, fixtures, compatibility code, docs, tests, and directly synchronized examples | data loss, drop-plus-add rename, old/new app incompatibility, unsafe rolling deploy, unbounded backfill, production lock, generated-client drift, migration-history drift, false rollback claim, ORM autogenerate mistake, or destructive contract mixed with expand phase | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Migration phase, old/new schema compatibility, backfill and validation plan, rollback classification, ORM/generated/schema dump surfaces, dependent surfaces, verification, and remaining database-migration risk |
 | Dependency versions, lockfiles, package-manager metadata, workspace constraints, runtime engines, peer dependencies, optional dependencies, security advisory fixes, generated dependency output, framework plugins, CI actions, Docker base images, package manager behavior, or toolchain versions are upgraded, downgraded, pinned, widened, regenerated, reviewed, or reported | `.mustflow/skills/dependency-upgrade-review/SKILL.md` | Dependency name, old and new versions or ranges, direct or transitive path, ecosystem and package manager, declaration files, lockfiles, runtime or toolchain files, advisory or release-note evidence, generated outputs, callers, docs, package output, Docker or CI surfaces, and command contract entries | Package declarations, lockfiles, generated outputs, compatibility code, tests, docs, package metadata, Docker or CI files, and directly synchronized examples | lockfile churn, hidden transitive replacement, peer or engine break, module-format drift, native or optional package break, framework or generator output drift, unsafe broad security update, weakened tests, Docker or CI runtime drift, or unreviewed supply-chain change | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Upgrade reason, ecosystem surface, direct and transitive graph changes, compatibility classification, runtime/peer/engine/module/feature/platform/generated-output risks, synchronized surfaces, verification, and remaining dependency-upgrade risk |
 | Dependency, package, runtime, framework, tool, command, plugin, service, platform capability, supported-version policy, security patch path, ecosystem maturity claim, maintainer-risk assumption, runtime portability claim, edge or serverless compatibility claim, critical-path library choice, package script, lifecycle hook, binary download, lockfile, audit result, or supply-chain-sensitive dependency surface is assumed, added, removed, imported, invoked, installed, audited, or documented | `.mustflow/skills/dependency-reality-check/SKILL.md` | Assumed dependency or capability, declaration files, version or feature expectation, role criticality, supported-version or end-of-life evidence, patchability expectation, runtime compatibility boundary, maintainer and ecosystem evidence when available, lockfile entry, package script or lifecycle hook, audit or provenance evidence, and relevant command intents | Package metadata, lockfiles, imports, scripts, command contracts, docs, tests, runtime policy notes, portability notes, and reports | unavailable dependency, hallucinated or lookalike package, fragile single-maintainer core dependency, experimental technology in a survival path, unsupported runtime, unclear security patch path, runtime-specific API leakage into core logic, stale version claim, lifecycle script risk, audit suppression, lockfile drift, or install guidance mismatch | `changes_status`, `changes_diff_summary`, `build`, `test_release`, `mustflow_check` | Dependency checked, ecosystem and maintainer-risk boundary reviewed, supported-version, patchability, and runtime-portability boundary reviewed, supply-chain surface reviewed, declarations synchronized, verification, and remaining dependency risk |
+| Generated or edited code, configuration, CI workflows, package metadata, install instructions, examples, Docker images, framework setup, runtime declarations, toolchain declarations, or migration-sensitive snippets introduce explicit external version references, action refs, package ranges, runtime versions, framework majors, Docker image tags, or scaffold commands that may be stale | `.mustflow/skills/version-freshness-check/SKILL.md` | Versioned reference, owning files, repository version policy, approved freshness source, compatibility context, migration risk, and command contract entries | Package metadata, lockfiles, CI workflows, Dockerfiles, runtime files, framework config, docs, examples, templates, tests, and version-decision reports | stale default version, false latest claim, accidental major migration, repository policy mismatch, unsupported generated example, floating-tag drift, or unverified security/support claim | `changes_status`, `changes_diff_summary`, `build`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Versioned surfaces checked, repository policy and freshness source, selected version track, compatibility classification, approval need, synchronized surfaces, verification, and remaining version-freshness risk |
 | External systems, protocols, SDKs, databases, webhooks, queues, files, object storage, signed upload or download URLs, caches, API response models, framework requests or responses, server actions, route handlers, edge functions, worker handlers, AI models, browser storage, search engines, analytics tools, email platforms, no-code tools, observability backends, trace or request context, or provider data cross the core boundary or need port/adapter translation, error mapping, timeout, retry, circuit-breaker, bulkhead, idempotency, reconciliation, security, core-state ownership, vendor portability, or observability handling | `.mustflow/skills/adapter-boundary/SKILL.md` | External system or protocol, inbound/outbound direction, delivery boundary, internal use case, local port/adapter patterns, provider risk, provider failure policy, core-state ownership risk, vendor portability risk, observability identifier policy, API contract risk, changed files, and command contract entries | Ports, adapters, mappers, controllers, workers, stores, gateways, response mappers, telemetry mappers, timeout and retry policies, circuit breakers, bulkhead boundaries, tests, fixtures, assembly wiring, and directly synchronized docs or templates | provider leakage, framework business-rule leakage, telemetry backend leakage, storage-key leakage, screen-shaped API coupling, pass-through wrapper, SaaS dashboard as truth source, search or analytics policy leakage, queue contract leakage, unclassified external failure, duplicate side effect, unsafe retry, missing timeout, missing circuit breaker, missing bulkhead, unresolved unknown provider outcome, broken identifier propagation, secret or personal-data leak, or untested integration drift | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Boundary classification, delivery adapter responsibility, internal port, provider containment, core-state ownership, vendor portability, validation and mapping, API response mapping, observability identifier flow, timeout/retry/circuit-breaker/bulkhead/idempotency handling, reconciliation behavior, security notes, verification, and remaining provider risk |
 | Tauri frontend invokes, Rust commands, capabilities, permissions, scopes, plugins, filesystem, dialog, shell, opener, updater, sidecar, or mobile native permissions are created or changed | `.mustflow/skills/tauri-code-change/SKILL.md` | Frontend call sites, Tauri config, Rust commands, capability and permission files, plugin config, changed files, and command contract entries | Tauri frontend, Rust commands, capabilities, permissions, scopes, plugins, tests, and docs | broad native permission, untrusted IPC input, filesystem escape, shell or updater risk, or WebView/native boundary drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | IPC, permission, scope, filesystem, shell, updater, and native boundary checked, verification, and remaining Tauri risk |
 | File path handling, cross-platform path behavior, path helpers, safe filesystem wrappers, temp or cache paths, atomic writes, locks, archive extraction, uploads, downloads, scanners, CLI/API/schema path contracts, snapshots, generated outputs, or package artifact paths are created, changed, reviewed, or reported | `.mustflow/skills/file-path-cross-platform-change/SKILL.md` | Path ledger, trust classes, accepted path representation, base root, path helpers, safe filesystem wrappers, temp/cache helpers, lock policy, archive policy, upload/download policy, scanner policy, CLI/API/schema/snapshot/generated/package surfaces, platform expectations, and command contract entries | Path validators, helpers, wrappers, schemas, CLI/API parsing, snapshots, fixtures, docs, tests, generated-output paths, package artifact paths, archive extraction, scanner bounds, temp/cache handling, locks, and cleanup code | path traversal, base containment bypass, drive-relative path bug, reserved-name bug, case-collision bug, symlink or junction escape, unsafe archive extraction, non-atomic write claim, stale lock, scanner loop, cleanup data loss, path contract drift, or package artifact path drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Path contract, path ledger, trust classes, root policy, Windows/macOS/Linux/archive/upload/download/scanner/lock/temp/cache/atomic/cleanup decisions, synchronized contract surfaces, verification, and remaining path risk |

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

@@ -228,6 +228,12 @@ route_type = "adjunct"
 priority = 45
 applies_to_reasons = ["code_change", "docs_change", "security_change"]
 
+[routes."version-freshness-check"]
+category = "data_external"
+route_type = "adjunct"
+priority = 68
+applies_to_reasons = ["code_change", "docs_change", "package_metadata_change", "mustflow_config_change", "release_risk"]
+
 [routes."file-path-cross-platform-change"]
 category = "data_external"
 route_type = "primary"

package/templates/default/locales/en/.mustflow/skills/version-freshness-check/SKILL.md

@@ -0,0 +1,141 @@
+---
+mustflow_doc: skill.version-freshness-check
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: version-freshness-check
+description: Apply this skill when generated or edited code, configuration, CI workflows, package metadata, install instructions, examples, Docker images, framework setup, runtime declarations, toolchain declarations, or migration-sensitive snippets introduce explicit external version references that may be stale.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.version-freshness-check
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - build
+    - test_related
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Version Freshness Check
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent agents from writing stale external version references from memory, while avoiding blind upgrades that ignore repository policy, compatibility, or migration cost.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Generated or edited files introduce explicit external version references, action refs, package ranges, runtime versions, framework majors, Docker image tags, toolchain versions, setup actions, scaffold commands, install commands, or migration examples.
+- CI workflows, release workflows, Dockerfiles, package metadata, lockfiles, runtime files, framework configuration, README examples, docs, tests, fixtures, or templates mention external versions such as GitHub Actions refs, Node, Bun, Deno, Python, Rust, Tauri, Astro, Next, SvelteKit, Electron, Docker images, package managers, SDKs, plugins, or generators.
+- An agent proposes a versioned dependency, tool, framework, action, image, or runtime based on memory, copied snippets, older project examples, or user-provided text that may be stale.
+- The task asks whether a newer stable, recommended, LTS, or security-patched version should replace a version the agent was about to write.
+- A patch claims a version is latest, current, recommended, stable, LTS, supported, deprecated, end-of-life, or migration-safe.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The version reference is purely repository-local, such as an internal schema revision, fixture id, or package version already handled by `date-number-audit`.
+- The task only preserves an existing pinned external version without touching code, docs, examples, package metadata, CI, Docker, runtime declarations, or compatibility claims.
+- The task is a deliberate dependency upgrade, downgrade, lockfile refresh, or security advisory fix; use `dependency-upgrade-review` as the main skill and this skill only for freshness-specific claims if needed.
+- The task only checks whether a dependency exists or whether a package name is real; use `dependency-reality-check` first.
+- The user explicitly requests an offline-only draft and accepts that version freshness will be reported as unverified.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The versioned external reference being introduced, changed, preserved, or reported.
+- Files that own or repeat the version: package metadata, lockfiles, workflow files, Dockerfiles, runtime files, framework config, docs, examples, templates, fixtures, and tests.
+- Repository version policy if present: pinned ranges, lockfile expectations, LTS policy, security patch policy, supported runtime matrix, migration notes, downgrade constraints, or organization rules.
+- Approved freshness evidence when available: official docs, upstream repository releases, package registry metadata, image registry metadata, official migration notes, security advisory ranges, or existing repository-maintained snapshots.
+- Compatibility context: new project or existing project, patch/minor/major difference, framework adapter/plugin compatibility, runtime engine support, generated output, migration burden, rollback path, and whether the version touches a survival path.
+- Relevant command-intent contract entries for build, tests, docs, packaging, or mustflow validation.
+
+<!-- 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 `.mustflow/config/commands.toml` have been checked for the current scope.
+- Freshness evidence can be gathered from allowed local files, configured tooling, approved connectors, official sources, package metadata, registry metadata, or the user-provided source text. If none is available, the check must be reported as unverified rather than guessed.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Align versioned references across package metadata, workflow files, runtime declarations, templates, docs, examples, and tests when the repository policy and compatibility classification support the change.
+- Replace stale generated defaults with a verified stable, recommended, LTS, or repository-pinned value when the change is compatible and within scope.
+- Add conservative wording when a version was not refreshed or when multiple legitimate version tracks exist.
+- Do not force the newest major version, floating tag, or broad range when the repository pins a different supported track.
+- Do not claim a version is current, latest, stable, recommended, LTS, deprecated, or secure unless the claim was refreshed or clearly marked as snapshot-only.
+- Do not add package-manager, registry, browser, or network commands to the skill. Use configured command intents or report missing verification.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build a version ledger before editing: each external version reference, where it appears, whether it is new or existing, and whether it is code, config, CI, Docker, package metadata, docs, template, fixture, or test data.
+2. Check repository policy before upstream freshness: package and lock metadata, runtime files, CI matrices, Docker tags, supported-version docs, migration notes, existing examples, and command contracts.
+3. Identify the intended track for each reference: repository-pinned, lockfile-resolved, latest stable, recommended major, LTS, security-patched minimum, compatibility range, floating tag, digest-pinned image, or snapshot-only example.
+4. Refresh stale-sensitive external facts with the highest-authority allowed source available. Prefer official docs, upstream releases, package registry metadata, official migration notes, official image metadata, or user-provided current evidence over secondary summaries.
+5. If freshness cannot be checked with the available tools or permissions, keep the version conservative, avoid current-version claims, and report the unchecked source boundary.
+6. Compare the proposed value, repository policy, and upstream evidence. Classify the difference as `same`, `patch`, `minor`, `major`, `migration-required`, `security-minimum`, `policy-pinned`, `floating`, or `unknown`.
+7. Treat major, migration-required, pre-1.0, framework, runtime-engine, CI-action, Docker-image, generator, native, security-sensitive, and survival-path changes as higher risk even when the version number looks small.
+8. For new projects or new examples, prefer the verified stable or officially recommended track unless the repository policy pins another track.
+9. For existing projects, do not cross a major, migration-required, engine, framework, CI-image, or generated-output boundary without user approval or explicit repository policy.
+10. For patch, security-minimum, and low-risk minor differences, update only when the declaration, examples, lockfile policy, and verification surface can stay aligned. Otherwise report the proposed change and leave the pinned value unchanged.
+11. For GitHub Actions and CI tools, review the action source, major tag policy, runtime support, cache behavior, permissions, and organization pinning rule. Do not assume a newer major is safe only because it exists.
+12. For framework and runtime majors such as Astro, Tauri, Electron, Next, SvelteKit, Node, Bun, Deno, Python, Rust, or Java, check migration notes, config schema, plugin and adapter compatibility, generated files, security model, deployment target, and rollback path before recommending a major change.
+13. For Docker images, decide whether the project prefers semver tags, distro tags, LTS tags, date tags, or digests. Do not replace a digest or pinned base image with a floating tag unless the repository policy says so.
+14. Synchronize every accepted version decision across package metadata, lockfiles when intentionally updated, CI, Docker, runtime files, docs, examples, templates, tests, and release notes.
+15. Run the narrowest configured verification that covers the changed versioned surface. Use broader verification for major, migration-required, runtime, framework, generated-output, package-publish, Docker, CI, or security-sensitive changes.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Every touched external version reference has a ledger entry with repository policy, freshness evidence, compatibility classification, and final decision.
+- Stale model defaults are not silently written as if they were current.
+- Repository-pinned versions are preserved unless the task, policy, and compatibility classification support changing them.
+- Major or migration-required changes are either explicitly approved, deferred with a recommendation, or left unchanged with the risk reported.
+- Docs and examples do not make unverifiable current-version claims.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `build`
+- `test_related`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Choose the narrowest configured intent that proves the changed versioned surface. Report missing dependency, package, docs, Docker, CI, or release verification instead of inventing commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If repository policy and upstream evidence disagree, preserve the repository policy unless the user explicitly chooses a migration or the existing version is outside a required security or support range.
+- If official sources conflict, prefer the source that owns the artifact being referenced and report the conflict.
+- If a freshness check requires network, credentials, or a connector that is not available, report the boundary and avoid current-version claims.
+- If a proposed major or migration-required version is better for greenfield work but risky for the existing project, present both choices and ask before changing the project.
+- If verification fails after a freshness update, do not weaken tests, lower type checks, delete lockfiles, or widen ranges to make the update pass. Revert or narrow the version decision unless the behavior change is intentional.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Versioned surfaces checked
+- Repository version policy found or missing
+- Freshness source checked or unavailable
+- Proposed and selected version track
+- Compatibility classification: `same`, `patch`, `minor`, `major`, `migration-required`, `security-minimum`, `policy-pinned`, `floating`, or `unknown`
+- User approval needed or not, with reason
+- Surfaces synchronized
+- Command intents run
+- Skipped freshness or verification checks and reasons
+- Remaining version freshness risk

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.22.49"
+version = "2.23.0"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -48,6 +48,7 @@ creates = [
   ".mustflow/skills/dependency-injection/SKILL.md",
   ".mustflow/skills/dependency-reality-check/SKILL.md",
   ".mustflow/skills/dependency-upgrade-review/SKILL.md",
+  ".mustflow/skills/version-freshness-check/SKILL.md",
   ".mustflow/skills/diff-risk-review/SKILL.md",
   ".mustflow/skills/pure-core-imperative-shell/SKILL.md",
   ".mustflow/skills/result-option/SKILL.md",
@@ -147,6 +148,7 @@ minimal = [
   "database-migration-change",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-update",
   "external-prompt-injection-defense",
@@ -200,6 +202,7 @@ patterns = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-update",
   "external-prompt-injection-defense",
@@ -263,6 +266,7 @@ oss = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-prose-review",
   "docs-update",
@@ -335,6 +339,7 @@ team = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-update",
   "external-prompt-injection-defense",
@@ -395,6 +400,7 @@ product = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-update",
   "external-prompt-injection-defense",
@@ -463,6 +469,7 @@ library = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-prose-review",
   "docs-update",