mustflow 2.22.12 → 2.22.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.22.12",
+  "version": "2.22.13",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",
@@ -28,19 +28,20 @@
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "bun run test:full",
-    "test:fast": "bun run build && node scripts/run-cli-tests.mjs fast",
-    "test:related": "bun run build && node scripts/run-cli-tests.mjs related",
+    "test:fast": "node scripts/run-cli-tests.mjs --build fast",
+    "test:related": "node scripts/run-cli-tests.mjs --build related",
     "test:related:cached": "node scripts/run-cli-tests.mjs related-cached",
-    "test:related:profile": "bun run build && node scripts/run-cli-tests.mjs related-profile",
-    "test:cli": "bun run build && node scripts/run-cli-tests.mjs cli",
-    "test:coverage": "bun run build && node scripts/run-cli-tests.mjs coverage",
+    "test:related:profile": "node scripts/run-cli-tests.mjs --build related-profile",
+    "test:cli": "node scripts/run-cli-tests.mjs --build cli",
+    "test:coverage": "node scripts/run-cli-tests.mjs --build coverage",
     "test:audit": "node scripts/audit-tests.mjs --json",
-    "test:release": "bun run build && node scripts/run-cli-tests.mjs release",
-    "test:fast:node": "npm run build && node scripts/run-cli-tests.mjs fast",
-    "test:release:node": "npm run build && node scripts/run-cli-tests.mjs release",
-    "test:full": "bun run build && node scripts/run-cli-tests.mjs full-auto",
-    "test:full:auto": "bun run build && node scripts/run-cli-tests.mjs full-auto",
-    "test:full:serial": "bun run build && node scripts/run-cli-tests.mjs full",
+    "test:release": "node scripts/run-cli-tests.mjs --build release",
+    "test:fast:node": "node scripts/run-cli-tests.mjs --build-runner=npm fast",
+    "test:release:node": "node scripts/run-cli-tests.mjs --build-runner=npm release",
+    "test:full": "node scripts/run-cli-tests.mjs --build full-auto",
+    "test:full:auto": "node scripts/run-cli-tests.mjs --build full-auto",
+    "test:full:profile": "node scripts/run-cli-tests.mjs --build full-profile",
+    "test:full:serial": "node scripts/run-cli-tests.mjs --build full",
     "check": "bun run check:package && bun run test:full",
     "check:core:node": "node scripts/run-node-core-check.mjs",
     "check:package": "node -e \"const fs=require('fs'); JSON.parse(fs.readFileSync('package.json','utf8')); console.log('package.json ok')\"",

package/templates/default/i18n.toml

@@ -92,7 +92,7 @@ translations = {}
 [documents."skill.contract-sync-check"]
 source = "locales/en/.mustflow/skills/contract-sync-check/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.date-number-audit"]
@@ -128,13 +128,13 @@ translations = {}
 [documents."skill.diff-risk-review"]
 source = "locales/en/.mustflow/skills/diff-risk-review/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 4
 translations = {}
 
 [documents."skill.codebase-orientation"]
 source = "locales/en/.mustflow/skills/codebase-orientation/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.cli-output-contract-review"]
@@ -182,7 +182,7 @@ translations = {}
 [documents."skill.docs-update"]
 source = "locales/en/.mustflow/skills/docs-update/SKILL.md"
 source_locale = "en"
-revision = 4
+revision = 5
 translations = {}
 
 [documents."skill.docs-prose-review"]
@@ -194,7 +194,7 @@ translations = {}
 [documents."skill.failure-triage"]
 source = "locales/en/.mustflow/skills/failure-triage/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 5
 translations = {}
 
 [documents."skill.external-prompt-injection-defense"]
@@ -241,13 +241,13 @@ translations = {}
 [documents."skill.performance-budget-check"]
 source = "locales/en/.mustflow/skills/performance-budget-check/SKILL.md"
 source_locale = "en"
-revision = 12
+revision = 15
 translations = {}
 
 [documents."skill.pattern-scout"]
 source = "locales/en/.mustflow/skills/pattern-scout/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.process-execution-safety"]
@@ -265,13 +265,13 @@ translations = {}
 [documents."skill.requirement-regression-guard"]
 source = "locales/en/.mustflow/skills/requirement-regression-guard/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.structure-discovery-gate"]
 source = "locales/en/.mustflow/skills/structure-discovery-gate/SKILL.md"
 source_locale = "en"
-revision = 26
+revision = 27
 translations = {}
 
 [documents."skill.state-machine-pattern"]
@@ -289,13 +289,13 @@ translations = {}
 [documents."skill.repro-first-debug"]
 source = "locales/en/.mustflow/skills/repro-first-debug/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.source-freshness-check"]
 source = "locales/en/.mustflow/skills/source-freshness-check/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.source-anchor-authoring"]
@@ -313,13 +313,13 @@ translations = {}
 [documents."skill.readme-authoring"]
 source = "locales/en/.mustflow/skills/readme-authoring/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.release-notes-authoring"]
 source = "locales/en/.mustflow/skills/release-notes-authoring/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.security-privacy-review"]
@@ -355,7 +355,7 @@ translations = {}
 [documents."skill.test-maintenance"]
 source = "locales/en/.mustflow/skills/test-maintenance/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 5
 translations = {}
 
 [documents."skill.vertical-slice-tdd"]

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

@@ -100,7 +100,7 @@ routes. Event routes stay inactive until their event occurs.
 | An unfamiliar codebase area needs an evidence-based map before planning, implementation, or reporting | `.mustflow/skills/codebase-orientation/SKILL.md` | User request, target area, relevant instructions, and current source, test, schema, template, configuration, or documentation files | Read-only orientation notes and any smallest follow-up edit chosen from inspected evidence | stale documentation, wrong ownership boundary, or invented architecture claim | `changes_status`, `changes_diff_summary`, `mustflow_check` | Scope inspected, entrypoints, flow map, ownership boundaries, verification options, risks, unknowns, and smallest safe next step |
 | Source anchors are added, revised, reviewed, or used to mark a module boundary | `.mustflow/skills/source-anchor-authoring/SKILL.md` | Target files, anchor reason, nearby anchors, source-anchor policy, and validation surface | Source anchors and directly related workflow docs or comments | comment bloat, authority drift, false verification claims, or hidden module pressure | `mustflow_check`, `docs_validate_fast` | Anchor placement decision, field choices, module-boundary handoff, and verification |
 | Changed files need risk classification and verification selection | `.mustflow/skills/diff-risk-review/SKILL.md` | Changed-file list, diff summary, and task goal | Changed surfaces and verification report | under- or over-verification | `changes_status`, `changes_diff_summary`, `test`, `test_related`, `test_audit`, `lint`, `build`, `docs_validate`, `mustflow_check` | Risk level, verification choice, rollback notes |
-| Performance budgets, query-count budgets, N+1 risk, read/write workload shape, database concurrency pressure, app-server scaling, vertical versus horizontal scaling, process count, connection-pool pressure, read-model cost, operational database reporting load, analytics-query isolation, cache strategy, cache keys, cache invalidation, cache stampede, hot keys, stale fallback, ranking snapshots, search API cost, search index rebuild cost, search quality set, log or analytics volume, file upload bandwidth, external-dependency timeout cost, retry storms, worker queue starvation, queue backlog, dead-letter growth, provider rate limits, vendor pricing-growth cost, free-tier limits, pricing value unit, internal cost unit, hybrid plan limit, credit or quota policy, tenant usage metering, user-action fan-out, contribution margin, P50/P90/P99 heavy-user cost, AI usage cost budgets, AI gateway hard limits, provider budget guardrails, agent loop caps, model-call retries, token-cost tracking, bundle size, page weight, startup time, command duration, memory use, asset size, throughput, latency, benchmark output, or performance claims are planned, edited, reviewed, or reported | `.mustflow/skills/performance-budget-check/SKILL.md` | Performance surface, budget source, measurement method, read/write workload profile, operational versus analytics query boundary, query-count or read-model boundary, cache layer, cache key source, freshness rule, invalidation path, hot-key or stampede risk, search rebuild or quality boundary, log or analytics volume boundary, file upload or download path, scaling bottleneck, process and connection boundary, external-dependency timeout, retry, fallback, worker, queue, rate-limit, vendor cost unit, value-pricing unit, tenant limit, fan-out factor, free-tier cliff, AI cost, AI gateway policy, provider budget role, agent cap, token, cache-hit, pricing-snapshot, or dead-letter rule, environment boundary, and command contract entries | Budget checks, thresholds, query-count and N+1 notes, read/write workload notes, analytics-query boundaries, cache boundaries, key and invalidation notes, hot-key and stampede notes, search rebuild and quality notes, log and analytics volume notes, file-transfer boundary notes, scaling bottleneck notes, dependency timeout and worker-capacity notes, vendor cost and free-tier notes, pricing-unit and margin notes, AI gateway, AI cost and provider-usage notes, measurements, dependency tradeoff notes, tests, docs, package metadata, and reports | invented budgets, stale measurements, hidden performance cost, value/cost unit mismatch, pricing cliff, unbounded free-plan loss, untracked heavy-user cost, untracked AI cost, provider-budget-only protection, unbounded agent loop, cache disclosure, stale-cache claim, N+1 query growth, write-contention blind spot, reporting query overload, app-server upload bottleneck, app-server scaling that worsens database or provider pressure, unbounded search rebuild, anecdotal search-quality claim, log-volume blind spot, cache stampede, retry storm, worker starvation, unwatched dead-letter queue, unbounded external wait, or unverified speed claim | `changes_status`, `changes_diff_summary`, `build`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Performance surface, budget source, measurement, query-count, read/write model, analytics-query, cache, search, log-volume, file-transfer, scaling bottleneck, worker, queue, external-dependency, vendor cost, value/cost pricing, margin, tenant-limit, AI gateway, and AI cost boundary, synchronized claims, skipped measurements, and remaining performance risk |
+| CLI execution duration, build time, bundle size, test scheduling logic, process spawning, or CLI performance claims are planned, edited, or reported | `.mustflow/skills/performance-budget-check/SKILL.md` | Performance surface, budget source, measurement method, and baseline metrics | Budget checks, CLI duration, bundle weight, scheduling optimization notes, measurements, and tests | invented budgets, stale measurements, child-process bottlenecks, or unverified speed claims | `changes_status`, `changes_diff_summary`, `build`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Performance surface, budget source, measurements, execution duration, bundle size, and remaining risks |
 | New feature, module, folder layout, architecture, scaffold, refactor, routing, data model, frontend/backend/database/infrastructure choice, database engine choice, managed database extension choice, auth identity ownership, public URL contract, data residency policy, runtime patchability, runtime portability, global-ready locale/country/currency/timezone/money model, server-side authorization boundary, file upload or storage strategy, API response contract, content-heavy product, semantic content blocks, filter URL policy, admin operation model, cache strategy, content lifecycle, asset strategy, claim or fact registry, content graph, source collection flow, user-state layer, core/application/delivery/infra boundary, framework-magic boundary, core versus auxiliary path boundary, operational versus analytics boundary, HTTP-to-worker boundary, job or outbox model, backup/restore assumption, vendor or platform exit path, external-service truth ownership, search/queue/log/analytics portability, operational reproducibility, observability identifier flow, deployment-state portability, CI/CD dashboard dependency, ecosystem or maintainer-risk placement, multi-server state boundary, vertical-to-horizontal scaling boundary, AI usage cost boundary, AI gateway hard-limit boundary, pricing-growth boundary, failure-isolation boundary, or external service integration may require hidden structure decisions before coding | `.mustflow/skills/structure-discovery-gate/SKILL.md` | User request, intended capability, hidden assumptions, named technologies or services, future content/API/rendering/data assumptions, database operating-shape assumptions, managed database feature assumptions, identity and provider-id assumptions, public URL assumptions, data location assumptions, runtime patch and portability assumptions, delivery/application/core/infra assumptions, global data assumptions, authorization assumptions, file-storage assumptions, source/provenance assumptions, lifecycle/asset/claim assumptions, user-state assumptions, admin/cache assumptions, core path and auxiliary path assumptions, async work assumptions, restore assumptions, vendor exit and replacement assumptions, external-service source-of-truth assumptions, search/queue/log/analytics reconstruction assumptions, operating-state reproduction assumptions, observability identifier assumptions, CI/CD reproducibility assumptions, dependency ecosystem and maintainer assumptions, pricing value/cost unit assumptions, failure-policy assumptions, AI gateway or cost assumptions, and relevant local patterns | Questions, assumptions, proposed file boundaries, and the smallest resulting implementation | brittle structure, vendor-name leakage, migration debt, lock-in debt, provider-id leakage, raw storage URL leakage, weak data location proof, unpatchable runtime, runtime-specific core logic, framework business-rule coupling, SaaS-only core state, weak search or queue reconstruction, weak global data model, weak server authorization, process-memory state leak, untracked AI cost, provider-budget-only AI protection, value/cost pricing mismatch, hidden dashboard deployment state, fragile single-maintainer core dependency, hidden operating state, broken traceability, file/storage drift, screen-shaped API coupling, core-path coupling, retry or worker coupling, unbounded failure radius, over-questioning, or speculative abstraction | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Blocking questions, assumptions, proposed files and responsibilities, upfront versus deferred structure decisions, borrowed service versus owned contract boundary, dependency direction, database, identity, public URL, data residency, runtime patchability and portability, global data, authorization, file-storage, API, vendor exit, external-service truth ownership, search/queue/log/analytics portability, operational reproducibility, CI/CD reproducibility, dependency risk, observability identity flow, pricing value/cost boundary, AI gateway boundary, core/application/delivery/infra boundaries, core and auxiliary boundaries, async work boundary, local pattern, verification, and remaining structure risk |
 
 ### Tests and Regression

package/templates/default/locales/en/.mustflow/skills/codebase-orientation/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.codebase-orientation
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: codebase-orientation
@@ -69,12 +69,23 @@ Build a concise, evidence-based map of an unfamiliar repository area before plan
 
 1. Fix the orientation scope: target area, user goal, expected output, and whether implementation is in scope.
 2. Read the nearest repository instructions and matching skill routes before inspecting source files.
-3. Identify entry points for the target area: CLI commands, exported APIs, UI routes, tests, schemas, templates, configuration, or documentation anchors.
-4. Trace the main flow through current files. Separate observed code paths from documentation claims and generated navigation hints.
-5. Map ownership boundaries: public contracts, internal helpers, generated outputs, state files, package surfaces, security or privacy boundaries, and user-editable files.
-6. Record verification surfaces already declared in `.mustflow/config/commands.toml`. Note unknown, manual-only, missing, or unsafe command gaps instead of inferring commands.
-7. Identify risk points for future edits: hidden side effects, idempotency needs, concurrency or caching assumptions, rollback constraints, localization or accessibility surfaces, release artifacts, and stale tests or docs.
-8. Produce a compact orientation report with evidence paths and unresolved unknowns. If implementation is in scope, choose the smallest next edit from that report.
+3. Use navigation aids in order:
+   - current changed files or user-named paths;
+   - `REPO_MAP.md` only when broader repository navigation is needed;
+   - file search for names, exported symbols, command ids, schema ids, route ids, and test names.
+   Treat generated maps and docs as pointers, not proof.
+4. Identify entry points for the target area: CLI command registry entry, command runner, exported API, UI route, worker, schema, template, configuration, or documentation anchor.
+5. Trace one main flow through current files in this order when applicable: entry point, orchestration function, core decision module, adapters or side effects, state writer or generated output, schema or public contract, then the nearest test.
+6. Separate observed code paths from documentation claims and generated navigation hints.
+7. Map ownership boundaries:
+   - public CLI, JSON, schema, template, package, or docs contract;
+   - core decision logic versus shell/adapters;
+   - user-editable files versus mustflow-owned files;
+   - generated output, cache, local state, and lock files;
+   - security, privacy, filesystem, process, localization, release, or compatibility boundaries.
+8. Record verification surfaces already declared in `.mustflow/config/commands.toml`. Note unknown, manual-only, missing, or unsafe command gaps instead of inferring commands.
+9. Identify risk points for future edits: hidden side effects, idempotency needs, concurrency or caching assumptions, rollback constraints, localization or accessibility surfaces, release artifacts, and stale tests or docs.
+10. Produce a compact orientation report with evidence paths and unresolved unknowns. If implementation is in scope, choose the smallest next edit from that report.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

package/templates/default/locales/en/.mustflow/skills/contract-sync-check/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.contract-sync-check
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: contract-sync-check
@@ -69,12 +69,19 @@ Keep declared behavior, machine-readable contracts, installed templates, tests,
 ## Procedure
 
 1. Name the contract being changed and identify its source of truth.
-2. List the expected synchronized surfaces for that contract: source code, schemas, command metadata, templates, manifests, lock files, tests, README, docs site, and localized copies.
-3. Compare the changed files with that list and add any missing required surface.
-4. Keep derived files mechanically aligned with the source of truth. If a surface is intentionally not updated, record the reason.
-5. Check that command intent names, schema ids, frontmatter revisions, template entries, version strings, and documented examples match exactly where they are meant to match.
-6. Use the narrowest configured verification that covers the contract and any packaging or documentation surface touched.
-7. In the final report, separate synchronized surfaces from skipped or deferred surfaces.
+2. If multiple files appear to define the contract, resolve source authority before editing:
+   - command behavior: current code and command contract first, then schemas, tests, and docs;
+   - JSON or package contract: schema and package metadata first, then code, tests, and docs;
+   - installed template contract: template manifest and template source files first, then lock files, i18n metadata, tests, and docs;
+   - workflow authority: nearest `AGENTS.md`, `.mustflow/config/*.toml`, and skill/index metadata before explanatory docs;
+   - prose examples: executable behavior and maintained docs before README snippets or fixtures.
+   If no authority is clear, stop and report the competing sources instead of choosing silently.
+3. List the expected synchronized surfaces for that contract: source code, schemas, command metadata, templates, manifests, lock files, tests, README, docs site, and localized copies.
+4. Compare the changed files with that list and add any missing required surface.
+5. Keep derived files mechanically aligned with the source of truth. If a surface is intentionally not updated, record the reason.
+6. Check that command intent names, schema ids, frontmatter revisions, template entries, version strings, and documented examples match exactly where they are meant to match.
+7. Use the narrowest configured verification that covers the contract and any packaging or documentation surface touched.
+8. In the final report, separate synchronized surfaces from skipped or deferred surfaces.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

package/templates/default/locales/en/.mustflow/skills/diff-risk-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.diff-risk-review
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: diff-risk-review
@@ -94,10 +94,15 @@ Classify the risk of a completed change, choose the smallest relevant configured
    - `medium`: templates, tests, package metadata, generated maps, or workflow docs without runtime behavior changes
    - `high`: runtime behavior, command execution, security, privacy, data handling, migrations, release behavior, or multi-surface changes
 5. Identify the minimum relevant configured verification intents. Prefer the narrowest configured intents that cover the changed surfaces, but do not hide missing, unknown, manual-only, or skipped intents.
-6. Record rollback notes for any changed installed template, command contract, package version, generated file, migration-like change, or public behavior change.
-7. Check for scope drift: unrelated files, invented facts, unnecessary abstractions, weakened validation, or unreported generated-file refreshes.
-8. If external PR or bot review exists, classify each suggestion as behavior risk, maintainability polish, contract drift, or not applicable. Adapt high-confidence repeatable lessons into the relevant skill instead of leaving them only in the current patch.
-9. Produce a concise risk and verification summary. Use `code-review` only if findings require a full review-style report.
+6. Use this verification floor unless a narrower skill gives a stricter rule:
+   - `low`: docs validation or `mustflow_check` for mustflow-owned prose and metadata.
+   - `medium`: `test_related` when tests, templates, package metadata, or workflow behavior changed, plus `mustflow_check` for mustflow-owned surfaces.
+   - `high`: `test_related`, `lint` or `build` when executable code changed, and `mustflow_check`; add `test_audit` when validation quality or test selection changed.
+   - `release_sensitive`: add `test_release` when package metadata, schema packaging, installed templates, public docs, or version metadata changed.
+7. Record rollback notes for any changed installed template, command contract, package version, generated file, migration-like change, or public behavior change.
+8. Check for scope drift: unrelated files, invented facts, unnecessary abstractions, weakened validation, or unreported generated-file refreshes.
+9. If external PR or bot review exists, classify each suggestion as behavior risk, maintainability polish, contract drift, or not applicable. Adapt high-confidence repeatable lessons into the relevant skill instead of leaving them only in the current patch.
+10. Produce a concise risk and verification summary. Use `code-review` only if findings require a full review-style report.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.docs-update
 locale: en
 canonical: true
-revision: 4
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: docs-update
@@ -45,6 +45,7 @@ Ensure documentation accurately reflects the current workflow, commands, and use
 - Relevant source or template file
 - Current documentation page or Markdown file
 - `.mustflow/config/commands.toml`
+- Localization or template metadata that owns the document when the edited page is installed or translated
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -63,10 +64,16 @@ Ensure documentation accurately reflects the current workflow, commands, and use
 ## Procedure
 
 1. Locate the document responsible for the explanation.
-2. Update only the most relevant sections.
-3. Ensure command names and paths are exact.
-4. Avoid adding marketing language or tutorial filler.
-5. Do not manually modify generated files.
+2. Decide section relevance before writing:
+   - update the page that owns the contract before summary or index pages;
+   - update README only when the first-screen claim changes;
+   - update localized or template metadata only when the source document is installed or translated;
+   - avoid duplicating long procedures across multiple docs.
+3. Update only the most relevant sections.
+4. Ensure command names, paths, field names, option names, and frontmatter are exact.
+5. If localization exists and translation confidence is low, update source metadata and mark follow-up instead of guessing translated wording.
+6. Avoid adding marketing language or tutorial filler.
+7. Do not manually modify generated files.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

package/templates/default/locales/en/.mustflow/skills/failure-triage/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.failure-triage
 locale: en
 canonical: true
-revision: 3
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: failure-triage
@@ -29,12 +29,15 @@ Identify the most probable root cause of a failed command or verification step b
 - A configured command intent returns a non-zero exit code.
 - Validation, build, test, or documentation checks fail.
 - The root cause of the failure is not yet apparent.
+- A test or build failure may have been caused by an overlapping run, orphaned process, stale lock, or deleted build output.
+- Several failures appear together and the first root cause needs to be separated from follow-on noise.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
 
-- The failure is fully understood and a targeted fix is available.
+- The failure is fully understood and a targeted fix is available; apply the relevant implementation or test skill instead.
 - The user has requested only a high-level summary.
+- A bug or runtime symptom is not yet reproducible; use `repro-first-debug` first unless the command failure itself is the reproduction.
 
 <!-- mustflow-section: required-inputs -->
 ## Required Inputs
@@ -44,6 +47,7 @@ Identify the most probable root cause of a failed command or verification step b
 - Truncated stdout and stderr output
 - Recently modified files
 - Relevant command contract entry
+- Active or recently active build/test/profile processes when the failure mentions missing compiled files, stale output, port/resource conflicts, or unexpected file deletion
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -63,9 +67,24 @@ Identify the most probable root cause of a failed command or verification step b
 
 1. Preserve the original failing intent name.
 2. Analyze the first actionable error.
-3. Determine if the failure originates from code, tests, configuration, documentation, or the environment.
-4. Examine the most relevant files.
-5. Develop a single hypothesis and verify it using the most targeted configured intent.
+3. Classify the probable failure domain before editing:
+   - `code`: implementation behavior, public output, or data transformation changed.
+   - `test`: assertion, fixture, helper, scheduler grouping, or test isolation changed.
+   - `configuration`: command contract, schema, template metadata, preferences, or package metadata drifted.
+   - `documentation`: docs navigation, frontmatter, generated content, or localized metadata drifted.
+   - `environment`: missing tool, platform difference, path, permission, lock, stale build output, or orphaned process.
+   - `tool_runner`: the verification runner, scheduler, cache, or build wrapper failed independently from the code under test.
+4. If several failures appear, triage in this order: environment and overlapping processes, build or generated output, configuration/schema drift, fixture setup, then behavior logic.
+5. For failures involving `dist/`, generated output, temporary files, ports, databases, or abrupt test termination, check whether another build/test/profile process for the same repository is still running.
+6. If an orphaned or overlapping process is found, stop or wait for it before changing source files, then rerun the narrowest failing intent to confirm the failure is reproducible.
+7. Pick one rerun target:
+   - the original failing intent when it is narrow enough;
+   - `test_related` when changed files map to a focused suite;
+   - `docs_validate_fast` for docs navigation or content-only failures;
+   - `test_release` for package, template, schema, or release metadata drift;
+   - `mustflow_check` for workflow, skill, command-contract, or manifest-lock failures.
+8. Examine the most relevant files.
+9. Develop a single hypothesis and verify it using the most targeted configured intent.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -84,6 +103,8 @@ intent that isolates the same failure area.
 
 - Avoid bundling unrelated fixes.
 - If the failure is due to missing tools, report the missing tool and the command that revealed the issue.
+- If the failure was caused by an orphaned or overlapping process, report that the original run was invalid and add or use a guard that prevents the same overlap before taking new measurements.
+- If rerunning the same intent produces a different failure without code changes, classify the issue as flaky or environmental and avoid weakening assertions until the unstable dependency is identified.
 - If sensitive data appears in the output, cease copying raw output and summarize the information safely.
 
 <!-- mustflow-section: output-format -->

package/templates/default/locales/en/.mustflow/skills/pattern-scout/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.pattern-scout
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: pattern-scout
@@ -66,12 +66,17 @@ Find the closest local implementation pattern before creating new structure, nam
 ## Procedure
 
 1. Name the change shape: command, UI pane, schema, template document, skill, test, documentation page, or other local category.
-2. Search for the nearest existing examples in that category and inspect enough surrounding code to understand ownership, naming, data flow, and verification style.
-3. Choose the closest pattern and list the files that define it. If multiple patterns conflict, choose the one nearest to the files being changed.
-4. Identify the parts that must stay aligned: file naming, frontmatter, schema keys, localization keys, test helper style, manifest entries, lock entries, or documentation routing.
-5. Implement by extending the chosen pattern instead of inventing a parallel shape.
-6. If the change intentionally differs from the closest pattern, state the reason in the final report.
-7. Use the smallest configured verification that covers the changed pattern.
+2. Search for examples in this order:
+   - same directory or feature folder;
+   - same command, package, template, schema, or docs family;
+   - same architectural layer, such as core, CLI, tests, docs, or templates;
+   - repository-wide only after local evidence is insufficient.
+3. Inspect enough surrounding code to understand ownership, naming, data flow, and verification style. Prefer patterns with matching file names, exported names, registry entries, tests, and template or schema synchronization.
+4. Choose the closest pattern and list the files that define it. If multiple patterns conflict, choose the one nearest to the files being changed and explain why other candidates were rejected.
+5. Identify the parts that must stay aligned: file naming, frontmatter, schema keys, localization keys, test helper style, manifest entries, lock entries, or documentation routing.
+6. Implement by extending the chosen pattern instead of inventing a parallel shape.
+7. If the change intentionally differs from the closest pattern, state the reason in the final report.
+8. Use the smallest configured verification that covers the changed pattern.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -108,3 +113,4 @@ Also run any narrower configured test, build, or documentation intent required b
 - Registries, manifests, or docs kept aligned
 - Command intents run
 - Skipped checks and reasons
+- Remaining pattern risks

package/templates/default/locales/en/.mustflow/skills/performance-budget-check/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.performance-budget-check
 locale: en
 canonical: true
-revision: 12
+revision: 15
 lifecycle: mustflow-owned
 authority: procedure
 name: performance-budget-check
-description: Apply this skill when performance budgets, query-count budgets, N+1 risk, read/write workload shape, database concurrency pressure, app-server scaling, vertical versus horizontal scaling, process count, connection-pool pressure, read-model cost, operational database reporting load, analytics-query isolation, cache strategy, cache keys, cache invalidation, cache stampede, hot keys, stale fallback, ranking snapshots, search API cost, search index rebuild cost, search quality regression set, file upload bandwidth, external-dependency timeout cost, retry storms, worker queue starvation, provider rate limits, queue backlog or dead-letter growth, pricing-growth cost, vendor free-tier limits, value-pricing units, internal cost units, tenant usage limits, user-action fan-out, contribution margin, P50/P90/P99 heavy-user costs, AI usage cost budgets, AI gateway hard limits, provider budget guardrails, agent loop caps, model-call retries, token-cost tracking, bundle size, page weight, startup time, command duration, memory use, asset size, throughput, latency, benchmark output, or performance claims are planned, edited, reviewed, or reported.
+description: Apply this skill when CLI execution duration, build time, bundle size, test execution scheduler bottlenecks, filesystem scanning latency, process spawning overhead, or dependency size budgets are planned, edited, or reported.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -22,227 +22,99 @@ metadata:
     - mustflow_check
 ---
 
-# Performance Budget Check
+# Performance Budget Check (CLI Core Condensed)
 
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Keep performance claims and budgets tied to declared thresholds, reproducible measurements, and explicit tradeoffs instead of guessing from local impressions.
+Keep CLI performance claims and execution speed tied to reproducible, measured thresholds instead of qualitative statements.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- A task changes or reports performance budgets, bundle size, page weight, startup time, command duration, memory use, asset size, throughput, latency, search index size, build time, or benchmark output.
-- A change adds heavier dependencies, generated assets, static pages, search indexes, startup work, file scanning, command fan-out, or repeated process spawning.
-- A change introduces or reports caching, cache-control headers, cache keys, cache tags, purge rules, stale fallback, precomputed ranking, search-result caching, faceted-filter caching, CDN caching, or private versus shared cache behavior.
-- A list, feed, search, admin table, dashboard, or API response introduces relation loading, ORM includes, lazy loading, per-row counts, viewer-specific flags, aggregate counters, or read models that can hide N+1 queries or unbounded query cost.
-- A behavior analytics, dashboard, reporting, search ranking, event log, or experiment analysis path may scan operational tables, consume the same connection pool as user requests, or run grouped aggregates on high-growth data.
-- A database or storage choice is justified by "read-heavy", "write-heavy", "SQLite is enough", "PostgreSQL is safer", "cache it", "direct upload", or "local file upload" performance assumptions.
-- A performance issue is framed as "scale up", "add servers", "move to serverless", "move to edge", "add workers", or "use a larger instance" before CPU, database, external dependency, regional latency, and process-state bottlenecks are separated.
-- App servers may be multiplied and could increase database connections, queue load, retry volume, cron duplication, cache pressure, or external API calls instead of improving throughput.
-- A file upload, download, resize, conversion, object-storage, CDN, or app-server streaming path could consume request time, memory, bandwidth, or worker capacity.
-- A cache, queue, search service, analytics store, AI provider, email service, or other auxiliary dependency might cause core user requests to wait, retry, stampede, or fail.
-- HTTP requests perform AI, email, embedding, statistics, webhook follow-up, import, export, file conversion, or other slow work inline instead of accepting work and handing it to a bounded worker path.
-- A retry policy, worker pool, or provider integration can create retry storms, rate-limit feedback loops, dead-letter buildup, or queue starvation across unrelated work.
-- Search ranking, query behavior, search index rebuild, queue partitioning, job retry policy, dead-letter retention, log volume, or analytics event volume may affect latency, worker capacity, provider cost, storage cost, or operational visibility.
-- AI, embedding, reranking, image, audio, or tool-call features can create provider cost, token cost, retry cost, cache savings, rate-limit pressure, free-plan abuse, or worker starvation that needs a budget, usage ledger, or limit.
-- AI requests need a gateway-level cost stop before provider calls, including estimated-cost checks, hard budget decisions, model downgrade rules, request-size caps, token caps, tool-call caps, agent-step caps, timeout caps, or an emergency disable switch.
-- A third-party tool, hosted platform, analytics service, observability vendor, automation provider, database, file store, email provider, authentication provider, or AI provider has a free tier, seat price, API-call price, event price, storage price, bandwidth price, workspace price, audit-log price, export price, or usage limit that can become a product margin or growth bottleneck.
-- A pricing or plan design must compare the value unit users understand with the cost units the system consumes, such as seats, workspaces, requests, storage, bandwidth, AI tokens, search queries, image conversions, automation runs, events, realtime connections, or support.
-- A user action can fan out into several internal jobs such as thumbnail generation, OCR, AI summary, embeddings, search indexing, notifications, logs, analytics events, or webhook calls.
-- Free, unlimited, or generous plan limits touch high-cost surfaces such as AI calls, media conversion, file storage, download traffic, search, automation, webhooks, realtime connections, or log retention.
-- A margin claim depends on average customers but could be dominated by heavy users, high-volume tenants, or P90/P99 usage.
-- A report claims that a path is faster, slower, lightweight, optimized, cached, parallelized, cheap, expensive, within budget, or over budget.
-- A failure or slowdown suggests that measurement scope, command selection, concurrency, caching, or generated output size needs review.
+- The task changes or reports CLI build time, bundle size, test scheduling logic, database cache initialization, or command execution duration.
+- A change adds heavy dependencies, recursive file-system scanning, command fan-out, or repeated child process spawning (e.g., test harness overhead).
+- A test optimization changes process isolation, in-process CLI execution, shared build outputs, or scheduler grouping.
+- A report claims that a CLI path is "faster", "optimized", "efficient", or "lightweight".
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
 
-- The task only changes wording and does not make a performance or size claim.
-- The number is only a local fixture or example with no budget or public reporting meaning.
-- The change is only image asset conversion; use `web-asset-optimization` for that asset pipeline and this skill only for budget reporting.
+- The task only changes wording, translations, or docs with no runtime execution impact.
+- The numbers represent local mocks or test-only fixtures with no operational baseline meaning.
 
 <!-- mustflow-section: required-inputs -->
 ## Required Inputs
 
-- The performance surface, such as command, page, asset, bundle, startup path, query, build, or generated output.
-- The budget source, if one exists: repository config, documented threshold, user-provided limit, benchmark baseline, package metadata, or current command result.
-- Measurement method, environment boundary, warm or cold run expectation, and whether the result is deterministic, sampled, local-only, or approximate.
-- Cache layer, cache key source, cache version, TTL or freshness rule, invalidation trigger, stale fallback, private or no-store boundary, and rebuild source when a cache or precomputed read model is involved.
-- Cache failure behavior, hot-key risk, stampede risk, TTL jitter or lock strategy, cache flush tolerance, and whether the cache is disposable or runtime storage.
-- Expected query count, row count, relation loading shape, aggregate strategy, read-model owner, and whether the measurement can detect query growth when a database-backed read path is involved.
-- Read/write workload profile, including repeated reads, freshness requirement, write bursts, same-row contention, index maintenance cost, ledger or audit write amplification, and whether a read projection can replace per-request calculation.
-- Operational database versus analytics or reporting boundary, including read replica, precomputed aggregate, queue, event store, separate connection pool, or external analytics system when available.
-- Timeout, retry, circuit-breaker, stale-response, feature-flag, and degraded-mode policy when an auxiliary dependency can affect the critical path.
-- Worker and provider capacity boundary, including queue separation, concurrency limits, retry delay, backoff with jitter, circuit-breaker threshold, dead-letter behavior, and whether one provider can consume shared worker or database resources.
-- Scaling boundary, including current process count, CPU and memory pressure, connection-pool limits, database maximum connections, serverless or edge timeout limits, worker concurrency, cron ownership, and whether adding app servers would increase pressure on the real bottleneck.
-- Search capacity and quality boundary, including index rebuild time, partial reindex trigger, query log volume, ranking snapshot cost, representative query set, and whether relevance changes are measured or only observed anecdotally.
-- Log and analytics volume boundary, including which events must be retained internally, which can be sampled or dropped, retention window, storage cost, and whether analysis scans are isolated from core user requests.
-- AI cost boundary, including feature key, account or workspace scope, request count, input and output token limits, cached-input treatment, provider price snapshot, retry grouping, cache-hit type, model tier, plan limit, and whether failed or cancelled provider calls can still cost money.
-- AI gateway boundary, including preflight estimated cost, hard limit decision, remaining budget, model downgrade, feature policy, provider budget role, maximum tool calls, maximum agent steps, maximum total tokens, timeout, and emergency kill switch.
-- Vendor cost boundary, including whether cost grows by users, seats, workspaces, API calls, events, storage, bandwidth, active users, projects, advanced permissions, audit logs, exports, AI tokens, or support tier, and whether that growth follows the product's revenue model.
-- Pricing and margin boundary, including the user-facing value unit, internal cost unit, included quota or credit pool, overuse policy, tenant-level limit, free-plan maximum loss, and customer contribution margin formula.
-- Usage metering boundary, including workspace or organization id, user id, feature key, request type, input size, output size, processing time, external API usage, retries, failures, plan, and whether one user action can create multiple billable or cost-bearing internal operations.
-- Heavy-user boundary, including P50, P90, and P99 customer cost, whether a few users can dominate provider or infrastructure bills, and which high-cost actions require hard limits instead of only reporting.
-- Free-to-paid transition boundary, including which operationally required features are outside the free tier, what usage cliffs exist, and whether growth creates a gradual cost curve or a sudden platform migration or plan upgrade.
-- Relevant command-intent contract entries for status, diff, build, tests, docs, release, or mustflow validation.
+- **Performance Surface**: Target command path, build step, or test scheduling token model.
+- **Measurement Method**: The exact execution tool (e.g., in-process execution vs. process spawning).
+- **Baseline**: Current execution duration or bundle size before changes.
+- **Measured Result**: Post-change metrics under identical sandbox constraints.
+- **Isolation Surface**: Shared state touched by the optimization, such as `process.cwd()`, `process.env`, module cache, build output directories, database files, or child processes.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
 
-- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
-- Required inputs are available, or missing inputs can be reported without guessing.
-- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- The task matches the Use When criteria and does not match the exclusions.
+- Standard test suite intent (`test_related` or `test_fast`) is configured and functional.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
 
-- Add or tighten budget checks, measurement notes, thresholds, cache boundaries, dependency tradeoff notes, tests, docs, and reports tied to the changed performance surface.
-- Replace vague claims such as "fast" or "lightweight" with measured, bounded, or explicitly unverified wording.
-- Prefer existing configured command intents and repository-local measurement paths before adding new tools.
-- Do not invent thresholds, benchmark numbers, hardware assumptions, network conditions, or release-blocking budgets without a source of truth.
+- Tighten budget limits, add performance test fixtures, optimize scheduling tokens, or use in-process helpers instead of spawning heavy child processes.
+- Replace fuzzy adjectives ("fast", "responsive") with exact duration (ms/sec) or file weight (KB/MB).
 
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Identify the performance surface and whether the task affects runtime, build time, test time, docs generation, asset weight, package size, or user-facing load behavior.
-2. Find the budget source before changing thresholds or claims. If no budget exists, report that the work is budget-discovery or measurement-only.
-3. Check nearby code, docs, templates, tests, and command metadata for duplicated performance statements or stale thresholds.
-4. Classify the measurement as deterministic, sampled, local-only, externally dependent, or unmeasured.
-5. If the change adds dependencies, generated output, or repeated work, identify the likely cost path and whether an existing alternative is available.
-6. For database-backed lists, feeds, search, dashboards, or admin tables, define the intended query shape before accepting a performance claim.
-   - Count queries separately from returned rows when the local tooling supports it.
-   - Watch for per-row author, tag, attachment, permission, count, reaction, bookmark, or viewer-state lookups.
-   - Prefer joins for small required one-to-one data, batch queries for one-to-many data, aggregate or cached counters for counts, and read models or projections for complex feeds.
-   - Treat ORM lazy loading as a performance risk until the query count is bounded or measured.
-   - Treat repeated `GROUP BY`, `COUNT`, `SUM`, large date windows, free-form filtering, and dashboard scans on high-growth tables as reporting load. Prefer precomputed aggregates, read replicas, analytics stores, or bounded query windows over user-request database resources.
-   - Protect core user requests from analytics or reporting load with separate connection pools, read-only replicas, queued jobs, cached summaries, or explicit rate limits when the architecture has those tools.
-7. For read-heavy and write-heavy workload claims, check the ordering of mitigations before accepting the design.
-   - For read-heavy paths, first stabilize query patterns, then indexes, then precomputed read tables or projections, then caches, then replicas or separate search engines. Do not add cache first when invalidation is unclear.
-   - For write-heavy paths, account for index write cost, audit-log amplification, ledger writes, lock contention, hot counters, same-row balance or inventory updates, and retry or idempotency overhead.
-   - Treat current-value fields such as balances, counts, or rankings as derived when a ledger, event, or snapshot is the real evidence source.
-8. For caching work, classify the cache layer: browser, CDN, server response, query-result cache, search index, precomputed ranking or statistics, generated page, or generated API projection.
-9. Check whether the cache key comes from normalized input rather than raw URL order, casing, default values, arbitrary range values, or temporary UI state. Include a cache version when the response shape, filter logic, ranking formula, or visibility rule can change.
-10. Check invalidation before accepting a cache: name the source data, affected cache tags or dependencies, purge trigger, rebuild source, stale-response behavior, and whether failures degrade safely.
-   - Ask whether the cache can be flushed. If flushing only increases latency, report it as cache; if it destroys sessions, queues, locks, rate-limit state, user state, or permissions, report it as runtime storage and require a different durability budget.
-   - Check hot keys such as global home feeds, popular lists, pricing data, and common search terms. Report sharding, replication, request coalescing, local memoization, or CDN strategy when one key can receive disproportionate traffic.
-   - Check stampede behavior. Prefer TTL jitter, single-flight refresh, stale-while-revalidate, background refresh, or prewarming over letting simultaneous misses hit the origin together.
-11. For ranking, trending, search, and faceted-list APIs, prefer precomputed snapshots, generated indexes, or bounded caches over per-request full aggregation when traffic can spike.
-12. For file upload and download paths, identify whether the app server handles raw bytes or only issues signed object-storage URLs.
-   - Large uploads, image processing, document conversion, video conversion, and archive extraction should not monopolize request memory or bandwidth when they can be direct-to-storage or worker-driven.
-   - Treat app-local file serving as a scalability and failure-isolation risk once user files are a product feature, especially with multiple servers, redeploys, or CDN needs.
-13. Ensure admin, private, authenticated, or personalized responses use no shared cache. Require `no-store` or private-cache behavior where leaking data would be worse than serving slower responses.
-14. For external or auxiliary dependencies on a critical path, check timeout, retry, backoff, circuit-breaker, fallback, and feature-flag behavior. A slow AI, search, analytics, email, or statistics dependency should not consume the whole request budget unless the user-visible operation truly depends on it.
-15. For scaling choices, locate the bottleneck before accepting the mitigation.
-   - If CPU is the bottleneck, consider a larger instance, more processes, worker processes, or worker threads for CPU-heavy work before distributing state across many app hosts.
-   - If the database is the bottleneck, check query shape, indexes, slow queries, transaction length, connection pooling, and N+1 behavior before adding app servers that may exhaust connections faster.
-   - If an external API is the bottleneck, use queueing, timeout budgets, limited retries, circuit breakers, degraded behavior, and rate limits rather than letting user requests wait indefinitely.
-   - If regional latency is the bottleneck, consider edge or regional routing only for short, independent paths. Do not move database-write-heavy or dependency-heavy business logic to edge runtime only because the edge is faster for simple responses.
-   - Treat serverless and edge scaling as capacity tools with their own limits: cold starts, timeouts, connection reuse, provider compatibility, bundle size, and cost cliffs still need budgets.
-16. For worker and retry paths, check whether retryable work is bounded.
-   - Prefer accepting work quickly, persisting a job or outbox record, and returning a queued or processing status over making HTTP wait for slow external completion.
-   - Use backoff with jitter so many failing jobs or clients do not retry at the same time.
-   - Separate queues, worker pools, rate limits, or concurrency budgets when AI, email, analytics, embeddings, webhooks, billing, and imports have different urgency or failure policies.
-   - Report dead-letter growth, retry exhaustion, provider rate limits, and unknown provider outcomes as capacity and reliability risks, not just error-handling details.
-   - Check that queues with different urgency do not share an unbounded worker pool when one backlog can delay payments, entitlement grants, password resets, webhook processing, or other critical work.
-   - Treat manual replay and dead-letter review as operational capacity. A dead-letter queue that no one watches is a delayed outage, not a solved failure.
-17. For search and analytics volume, check whether derived systems can be rebuilt and observed without overwhelming the core path.
-   - Search indexes should be rebuildable from source records, and full or partial reindex cost should be bounded before relying on provider search as the only serving path.
-   - Search relevance claims should cite a representative query set, expected top results, or explicit unmeasured status instead of relying on a dashboard impression.
-   - Logs and analytics events should not grow without retention, sampling, aggregation, export, or cold-storage policy when storage, query, or SaaS event pricing can become the bottleneck.
-18. For AI cost and provider-usage budgets, treat cost as a first-class performance and product limit.
-   - Do not rely on provider dashboards as the only source for user, workspace, feature, model, cache, retry, or plan-level cost decisions.
-   - Prefer a single AI call boundary that records request-level usage before cost is summarized. Scattered direct SDK calls hide feature economics and retry amplification.
-   - Track user request id separately from provider call id so one user action with retries, fallbacks, embeddings, tool calls, or evaluations can be costed without being counted as multiple user actions.
-   - Store usage in integer cost units plus a pricing snapshot or version reference. Do not recompute historical costs from the current provider price sheet.
-   - Distinguish app response cache, provider prompt cache, embedding cache, and search-result cache. A cache hit that avoids a provider call is not the same as a discounted provider input.
-   - Apply preflight limits for plan, account, request length, model tier, monthly cost, request count, input tokens, and output tokens; record actual usage afterward and update rollups or limits.
-   - Treat provider console budgets, account-level spend caps, and rate-limit headers as secondary guardrails unless they are proven hard stops. Product-owned limits should block, downgrade, queue, or reject high-cost work before the provider call.
-   - For agentic or multi-call AI work, cap steps, tool calls, total tokens, total estimated cost, and total time. One visible user request can create many provider calls, so request-count limits alone are not enough.
-   - Keep budget decisions inspectable. Record allow, block, downgrade, or emergency-disable decisions with safe identifiers, estimated cost, remaining budget, selected model, and blocked reason.
-   - Include failed, timed-out, cancelled, and retried calls in the budget review when they may consume provider quota or money.
-19. For vendor pricing and free-tier claims, compare the tool's pricing unit with the product's revenue unit.
-   - Check whether the product earns by customer, workspace, seat, transaction, storage, content item, automation run, active user, or AI usage, then compare that with how the vendor charges.
-   - Treat user-seat, monthly-active-user, API-call, event, storage, bandwidth, workspace, project, advanced-permission, audit-log, export, and overage pricing as structural risk when the product can grow in a different direction.
-   - Identify operationally required features that are plan-gated, such as backups, audit logs, SSO, role management, webhooks, API limits, data export, retention, monitoring, or support. A generous free tier can still be risky when the paid cliff lands on a feature that is hard to replace later.
-   - Report pricing cliffs and unverified provider terms as margin risk rather than performance risk alone. "Cheap now" is not evidence that the tool remains cheap at the product's next scale.
-20. For pricing and internal metering claims, separate user-perceived value from system cost.
-   - Identify the value unit: seat, workspace, project, document, transaction, plan, or another unit customers can understand.
-   - Identify the cost units: storage, transfer, database usage, search, AI or external API calls, log or analytics volume, email or notification sends, automation runs, file conversions, queue work, payment fees, and support load.
-   - Prefer simple external plans plus internal limits for cost-bearing resources. A seat or workspace plan can include storage, AI credits, search quotas, automation runs, and shared tenant pools without exposing every raw request count to the customer.
-   - Treat "unlimited" as a claim that must have a natural human limit, fair-use policy, rate limit, abuse detection, or hard internal cap. Do not let unlimited AI, media conversion, storage, traffic, search, automation, realtime, webhook, or log retention become an unbounded liability.
-   - Model contribution margin as customer revenue minus customer variable cost. Report which variable costs are included and which are unmeasured.
-   - Compare P50, P90, and P99 users or tenants when possible. Averages can hide a small number of heavy users who destroy margin.
-   - Meter by workspace or organization as well as user when team usage is pooled. Seat-level credits may be sold, but shared tenant pools often better match real usage.
-21. For user-action fan-out, count internal work rather than only the visible request.
-   - Name the jobs triggered by one action, such as uploads, transforms, OCR, AI calls, embeddings, search indexing, notification sends, event writes, log writes, analytics exports, and webhook deliveries.
-   - Identify which fan-out work is synchronous, queued, retryable, deduplicated, rate-limited, or skipped under load.
-   - Treat hidden retries, failed calls, and duplicate worker execution as cost multipliers when they consume provider quota or infrastructure.
-22. Keep claims conservative: state the command, input scope, query-count boundary, cache boundary, worker boundary, search rebuild or quality boundary, log and analytics volume boundary, AI cost boundary, vendor cost boundary, pricing value/cost boundary, critical-path dependency boundary, and whether caching, warm runs, parallelism, stale responses, precomputed snapshots, generated files, queues, provider limits, pricing cliffs, user-action fan-out, or external services influenced the result.
-23. If a budget is exceeded, report the affected surface, budget source, measured value or unavailable measurement, likely cause, and smallest follow-up.
-24. Run the narrowest configured verification that proves the changed performance, package, docs, or mustflow surface.
+1. Identify if the performance change affects:
+   - **Build Time**: bundle duration, generated file size, and rebuild behavior.
+   - **Test Scheduling**: scheduler token capacity, wave grouping, in-process execution, and subprocess fan-out.
+   - **CLI Boot Time**: Node process startup, module import cost, and command dispatch latency.
+2. Run the narrowest matching oneshot intent (e.g., `build` or `test_related`) to establish a deterministic local baseline.
+3. Before converting process-spawned tests to in-process execution, inventory global process state:
+   - current working directory reads or writes;
+   - environment variable mutation;
+   - `process.argv`, `process.exitCode`, signal handlers, module cache, timers, and singleton caches;
+   - shared filesystem outputs such as `dist/`, local indexes, or temporary database paths.
+4. Do not use `process.chdir()` as an in-process test isolation strategy when multiple tests can run in the same Node test runner. Use a context-aware current-directory adapter, serialize the affected tests, or keep those tests in separate processes.
+5. Treat build output directories that are deleted and recreated during build as exclusive resources. Lock the build/test runner before rebuilding or reading that output so an overlapping run cannot remove files from a live test process.
+6. Before measuring, check for an already-running build, profile, or test process for the same repository. Stop, wait, or report the overlap before recording timings.
+7. Eliminate process spawning loops. Where possible, invoke core logic directly in-process instead of using heavy CLI shell executions, but only after the isolation surface is controlled.
+8. Measure and document the metrics exactly:
+   - Command duration (ms or seconds).
+   - Bundle size (KB or MB) if `dist/` is affected.
+9. Identify any potential platform-specific latency differences (Windows PowerShell vs. Unix sh).
+10. Verify changes using `mustflow_check` and the narrowest test suite intent.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
-- Performance claims have a budget source, measurement method, or explicit unverified status.
-- Database-backed read paths have an explicit query-count, row-count, relation-loading, or unmeasured-risk note when N+1 or aggregate cost is plausible.
-- Read-heavy and write-heavy claims identify query patterns, indexes, projections, cache invalidation, write contention, audit or ledger amplification, and retry overhead before claiming a store or cache is sufficient.
-- File upload and download paths identify app-server bandwidth, memory, conversion, object-storage, CDN, and worker boundaries when those costs are plausible.
-- Cache behavior has an owner, key source, freshness rule, invalidation path, private/shared boundary, and rebuild or fallback story when cache is part of the claim.
-- Analytics, dashboard, and reporting paths do not silently share unbounded operational query cost with core user requests, or the remaining risk is reported.
-- Critical-path external dependencies have timeout, retry, fallback, feature-flag, or degraded-mode boundaries when performance or availability can affect core use.
-- Vertical scaling, horizontal scaling, serverless, edge, worker, and process-count claims identify the actual bottleneck and the state, connection, cron, queue, or provider limits that could make the chosen scaling path worse.
-- Worker queues, retry policies, provider rate limits, and dead-letter paths have capacity boundaries when auxiliary work can starve core flows.
-- Search index rebuilds, search quality checks, log volume, analytics event volume, and queue dead-letter review have explicit measured or unmeasured status when they affect latency, cost, or operational visibility.
-- AI usage and cost claims have request, provider-call, feature, model, cache, retry, pricing-snapshot, and plan-limit boundaries when model calls can affect cost or quota.
-- AI gateway claims have preflight hard-limit, provider-budget, downgrade, agent-step, tool-call, timeout, and emergency-disable boundaries when autonomous or high-cost model work can affect margin.
-- Vendor pricing, free-tier, plan-gated feature, and usage-growth claims are tied to the product's revenue unit or reported as unverified margin risk.
-- Pricing claims separate customer-visible value units from internal cost units, and identify included limits, credit pools, overuse behavior, tenant-level controls, free-plan loss budget, and unverified margin risk.
-- Usage-cost claims account for user-action fan-out, hidden retries, P50/P90/P99 heavy-user shape, and contribution margin when high-cost actions can dominate customer economics.
-- Thresholds and benchmark-facing docs, tests, package metadata, generated output notes, and command contracts are synchronized where they overlap.
-- Final reports separate measured evidence from estimates, local observations, and suggested follow-up work.
+- All speed or weight claims are backed by measured data or explicitly marked as "unverified local estimate".
+- No hidden process-spawning bottlenecks or N+1 file scan loops are introduced.
+- In-process performance work documents how global process state and shared build outputs are isolated.
 
 <!-- mustflow-section: verification -->
 ## Verification
 
-Use configured oneshot command intents when available:
-
-- `changes_status`
-- `changes_diff_summary`
-- `build`
-- `test_related`
-- `docs_validate_fast`
-- `test_release`
+Use configured oneshot command intents:
+- `build` (to check bundle weight/correctness)
+- `test_related` or `test_fast` (to verify execution speed)
 - `mustflow_check`
 
-Use a narrower configured benchmark, asset, build, docs, or test intent when it better proves the changed performance surface.
-
 <!-- mustflow-section: failure-handling -->
 ## Failure Handling
 
-- If no budget source exists, do not invent one. Report the missing source and keep the claim qualitative or measurement-only.
-- If a measurement depends on local hardware, cache state, network, registry state, or generated output from a previous run, state that boundary.
-- If verification is too slow or no configured command exists, report the missing or skipped intent instead of running an inferred command.
-- If a performance fix conflicts with correctness, security, accessibility, or data safety, preserve the stricter correctness boundary and report the tradeoff.
+- If local execution hardware makes metrics non-deterministic, state the sandbox CPU/environment variables explicitly.
+- If timings are distorted by an orphaned or overlapping process, stop and classify the measurement as invalid before taking a new baseline.
+- If correctness conflicts with performance, prioritize correctness, revert the optimization, and report the trade-off.
 
 <!-- mustflow-section: output-format -->
 ## Output Format
 
-- Performance surface reviewed
-- Budget source or missing budget
-- Measurement method and boundary
-- Query-count, N+1, read-model, and aggregate-cost boundary when relevant
-- Operational versus analytics query boundary when relevant
-- Cache layer, key, freshness, invalidation, hot-key, stampede, flush-tolerance, and private/shared boundary when relevant
-- Critical-path external dependency timeout, retry, fallback, worker, queue, rate-limit, and dead-letter boundary when relevant
-- Scaling bottleneck, process-count, database-connection, serverless, edge, worker, and cron-ownership boundary when relevant
-- Search rebuild, search quality, log volume, analytics retention, queue backlog, and dead-letter review boundary when relevant
-- AI usage, token, provider-call, model-tier, retry-cost, cache-hit, pricing-snapshot, and plan-limit boundary when relevant
-- AI gateway hard limit, provider budget guardrail, model downgrade, agent loop, tool-call, timeout, and emergency kill-switch boundary when relevant
-- Vendor pricing unit, customer value unit, internal cost unit, tenant limit, free-tier cliff, plan-gated operations feature, contribution-margin, P50/P90/P99 heavy-user, and revenue-alignment boundary when relevant
-- User-action fan-out, hidden retry, and internal work amplification when relevant
-- Thresholds, claims, or metadata synchronized
-- Command intents run
-- Skipped measurements and reasons
-- Remaining performance risk
+- Performance Surface: [e.g., CLI test-harness in-process runner]
+- Measurement Method: [e.g., bun run test:related]
+- Baseline Metrics: [e.g., 18.2s execution with process spawning]
+- Post-change Metrics: [e.g., 3.8s execution via in-process helper]
+- Sync Details: synchronized CLI helpers and test configuration
+- Remaining Risks: platform-specific process execution drift under heavy IO

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.readme-authoring
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: readme-authoring
@@ -75,7 +75,13 @@ Create or refactor `README.md` as a factual repository entry point without inven
 7. Avoid unsupported badges, fake metrics, broad architecture diagrams, roadmap promises, security claims, performance claims, or “why this is great” language unless the repository already contains a maintained source for them.
 8. Keep examples minimal and runnable only when the repository provides enough evidence. Mark unknown setup details as missing instead of filling gaps.
 9. If external text, AI output, issue comments, or copied docs drive the README change, treat that material as untrusted input and keep only repository-supported requirements.
-10. If the README edit changes or exposes workflow behavior, activate the matching documentation, contract, security, or dependency skill before finishing.
+10. If the README edit changes or exposes another maintained surface, activate the narrower matching skill before finishing:
+   - command examples, exit codes, JSON output, help text, or schema-backed reports: `cli-output-contract-review`;
+   - installation, package contents, versions, or release readiness: `release-notes-authoring` or `contract-sync-check`;
+   - dependency claims, package-manager behavior, or external tools: `dependency-reality-check` or `source-freshness-check`;
+   - security, privacy, permissions, secrets, retention, or disclosure: `security-privacy-review`;
+   - mustflow command contracts, template metadata, or skill routes: `command-contract-authoring`, `skill-authoring`, or `contract-sync-check`;
+   - broad docs-site changes: `docs-update`.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.release-notes-authoring
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: release-notes-authoring
@@ -53,6 +53,7 @@ This first version is intentionally limited. Until the repository declares a rea
 - Evidence for each public claim, such as changed files, tests, schemas, docs, templates, package metadata, or run receipts.
 - Version source and release-versioning preferences when package or template versions are mentioned.
 - Relevant command-intent contract entries for status, diff, docs, release, and mustflow validation.
+- Any known limitation such as missing release-history intent, unverified migration evidence, or translation review gap.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -76,6 +77,7 @@ This first version is intentionally limited. Until the repository declares a rea
 1. Establish the evidence set.
    - Use user-provided summaries, current diff summaries, release preparation notes, and directly relevant changed files.
    - If historical commits, tags, or prior releases are needed and no configured read-only intent exists, report the missing release-history intent.
+   - State the current limitation explicitly when the note is only based on the active diff or user-provided summary.
 2. Identify public surfaces.
    - CLI behavior, installed templates, schemas, command contracts, package metadata, user-visible docs, migrations, security or privacy behavior, and contributor-facing workflow can be release-note material.
    - Internal refactors, test-only changes, generated-output refreshes, formatting, and private planning notes stay out unless they change a public contract.
@@ -140,4 +142,5 @@ Use release checks when notes mention package metadata, template metadata, schem
 - Version or migration claims checked
 - Command intents run
 - Skipped release-history checks and reasons
+- Current limitations of the release-note evidence
 - Remaining release-note risks

package/templates/default/locales/en/.mustflow/skills/repro-first-debug/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.repro-first-debug
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: repro-first-debug
@@ -74,13 +74,20 @@ This skill keeps debugging anchored to symptom evidence, deterministic reproduct
 2. Locate the smallest fast, deterministic reproduction path: an existing command intent, test file, route, UI action, fixture, or function boundary.
 3. Prefer existing targeted verification before adding a new test. If no targeted path exists, record the gap and create the smallest reproduction only when it is supported by the symptom.
 4. Keep the first reproduction focused on one failing condition. Avoid turning the reproduction into a broad regression suite.
-5. If the cause is not obvious, list three to five plausible hypotheses. For each hypothesis, write the observation that would confirm or reject it before changing production code.
-6. Inspect the source that controls the reproduced behavior and gather the smallest observation needed to choose between hypotheses.
-7. If temporary instrumentation is needed, give every probe a unique marker, keep it local to the suspect boundary, and remove it before final verification.
-8. Apply the smallest fix that addresses the reproduced cause.
-9. Re-run the original reproduction path after the fix. If that path is unavailable or too broad, run the closest configured intent and report the limitation.
-10. Add or keep a regression guard only when it is tied to the reproduced symptom or a directly observed boundary condition.
-11. Report the symptom, reproduction, hypotheses considered, observations, fix, original reproduction rerun, checks, and remaining risk.
+5. If the cause is not obvious, list three to five plausible hypotheses using distinct categories where possible:
+   - recent code or contract change;
+   - environment, platform, tool version, or missing dependency;
+   - timing, ordering, concurrency, cache, or cleanup;
+   - specific input, fixture, locale, path, or data shape;
+   - external source, generated output, or stale build artifact.
+   For each hypothesis, write the observation that would confirm or reject it before changing production code.
+6. If the symptom appears flaky, separate the reproducible behavior from the unstable trigger. Do not treat one passing broad rerun as proof that the issue is fixed.
+7. Inspect the source that controls the reproduced behavior and gather the smallest observation needed to choose between hypotheses.
+8. If temporary instrumentation is needed, give every probe a unique marker, keep it local to the suspect boundary, and remove it before final verification.
+9. Apply the smallest fix that addresses the reproduced cause.
+10. Re-run the original reproduction path after the fix. If that path is unavailable or too broad, run the closest configured intent and report the limitation.
+11. Add or keep a regression guard only when it is tied to the reproduced symptom or a directly observed boundary condition.
+12. Report the symptom, reproduction, hypotheses considered, observations, fix, original reproduction rerun, checks, and remaining risk.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

package/templates/default/locales/en/.mustflow/skills/requirement-regression-guard/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.requirement-regression-guard
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: requirement-regression-guard
@@ -92,17 +92,22 @@ The goal is not to write tests for everything. The goal is to preserve the behav
    - Prefer the nearest existing test style and fixture pattern.
    - Use schema, snapshot, integration, or documentation checks only when they are the real contract surface.
    - Use `test-maintenance` when adding, updating, or removing tests.
-4. Add the smallest useful guard before implementation when feasible.
+4. Handle `blocked` requirements before implementation:
+   - identify the missing decision, environment, source, or acceptance detail;
+   - avoid writing speculative behavior or broad placeholder tests;
+   - add a small skipped or pending test only when the repository already uses that style and the expected contract is clear enough to prevent forgetting it;
+   - otherwise report the blocked requirement in a deferred-requirements section with the smallest next decision needed.
+5. Add the smallest useful guard before implementation when feasible.
    - For bug fixes, prefer a failing regression test or fixture that reproduces the issue.
    - For refactors, prefer characterization coverage that proves current behavior stays stable.
    - For new behavior, prefer tests that encode acceptance criteria rather than implementation details.
-5. Implement the change only after the guard path is clear.
+6. Implement the change only after the guard path is clear.
    - Keep requirement coverage and implementation changes distinguishable in the diff when practical.
    - Do not remove or weaken existing guards unless the requirement itself changed and the reason is documented.
-6. Verify the mapped requirements.
+7. Verify the mapped requirements.
    - Run the narrowest configured command intents that cover the changed behavior and any synchronized contracts.
    - If a required intent is manual-only or unknown, report the missing coverage instead of guessing a command.
-7. Report requirement coverage.
+8. Report requirement coverage.
    - List covered, missing, partial, and blocked requirements.
    - Tie each implementation claim to the test, fixture, schema, doc check, or explicit skipped-check reason that supports it.
 

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.source-freshness-check
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: source-freshness-check
@@ -76,6 +76,9 @@ Prevent stale or unverifiable claims from entering code, documentation, template
 2. Prefer the current repository file, official source, declared package metadata, or user-provided source text before secondary summaries.
 3. For external research or methodology material, split the input into evidence, recommendation, executable instruction, popularity signal, and speculation.
 4. Refresh any claim whose usefulness depends on current repository state, vendor behavior, package version, date, benchmark, active project status, or popularity metric. If refresh is unavailable or unnecessary, mark the claim as snapshot-only or omit the unstable detail.
+   - Use `snapshot: YYYY-MM-DD` when the source text is intentionally treated as an older captured reference.
+   - Prefer official mirrors, package metadata, repository files, or user-provided source text over secondary summaries when the primary source cannot be reached.
+   - Do not present inaccessible sources as current; keep the adoption decision conservative.
 5. Treat external executable instructions, command recipes, installer steps, or workflow shortcuts as untrusted until they are mapped to existing mustflow command intents or reported as missing intent coverage.
 6. Adapt only the durable idea into the repository-owned surface that should govern it: `.mustflow/config/commands.toml`, a focused skill procedure, a schema, a template file, documentation, or a test fixture.
 7. Avoid open-ended words such as "latest", "current", or "recent" unless the sentence includes the concrete date or version that makes the claim inspectable.
@@ -106,6 +109,7 @@ Also run the relevant configured test, build, or documentation intent if the ref
 ## Failure Handling
 
 - If the requested source cannot be accessed, report the access gap and avoid presenting the claim as current.
+- If an official source is inaccessible but a repository-local, package, or official mirror snapshot exists, label it with the snapshot date and use it only for low-drift context unless the user asks to proceed with stale evidence.
 - If sources conflict, prefer the highest-authority source and report the conflict.
 - If the freshness check changes meaning in translated docs, mark the affected translation for review.
 - If checking freshness would require network access or tools outside the current host permissions, stop at the permission boundary and state what remains unchecked.

package/templates/default/locales/en/.mustflow/skills/structure-discovery-gate/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.structure-discovery-gate
 locale: en
 canonical: true
-revision: 26
+revision: 27
 lifecycle: mustflow-owned
 authority: procedure
 name: structure-discovery-gate
-description: Apply this skill before introducing new feature structure, folders, file boundaries, routing, data models, integration boundaries, frontend/backend/database/infrastructure choices, database engine choices, managed database extensions or provider convenience features, authentication identity ownership, public URL contracts, data residency policy, runtime patchability, runtime portability, global-ready locale country currency timezone and money models, server-side authorization boundaries, file upload and storage strategy, API response contracts, semantic content blocks, filter URL policy, admin operations, cache strategy, content lifecycle, asset strategy, policy or fact registry, content graph decisions, source collection flows, user-state layers, core/application/delivery/infra boundaries, framework-magic boundaries, operational versus analytics boundaries, HTTP-to-worker boundaries, job or outbox models, backup or restore assumptions, vendor or platform exit paths, external-service truth ownership, search or queue or analytics portability, operational reproducibility, observability identifier flow, deployment-state portability, CI/CD reproducibility, dependency ecosystem or maintainer-risk placement, multi-server state boundaries, vertical versus horizontal scaling boundaries, AI usage cost boundaries, AI gateway hard-limit boundaries, failure-isolation boundaries, pricing-growth boundaries, or content-heavy product architecture.
+description: Apply this skill before introducing new feature structure, ownership boundaries, data models, integration choices, or platform decisions that may create long-term architecture commitments.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure

package/templates/default/locales/en/.mustflow/skills/test-maintenance/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.test-maintenance
 locale: en
 canonical: true
-revision: 3
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: test-maintenance
@@ -35,6 +35,7 @@ Keep tests aligned with the current behavior contract.
 - A bug fix needs a regression test.
 - Existing tests may be stale, duplicated, too broad, or tied to removed implementation details.
 - Snapshot output has changed.
+- Test execution moves between subprocess execution, in-process helpers, grouped runners, or scheduler-managed waves.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -49,6 +50,7 @@ Keep tests aligned with the current behavior contract.
 - Current behavior contract
 - Changed or removed code path
 - Existing test style
+- Isolation model for the affected tests, including whether they share a Node process, working directory adapter, environment variables, or build output
 - `.mustflow/config/commands.toml`
 - `.mustflow/config/mustflow.toml` `[testing]`
 
@@ -77,9 +79,18 @@ Keep tests aligned with the current behavior contract.
    - `legacy_contract`: old behavior is intentionally preserved
    - `flaky_or_environmental`: failure may depend on environment
 4. Add, update, remove, or report tests according to the classification.
-5. Do not reintroduce removed behavior solely because old tests expect it.
-6. Treat snapshot updates as manual unless `snapshot_update` is explicitly approved and configured.
-7. Keep tests deterministic and close to the behavior contract.
+5. For `flaky_or_environmental` tests, do not delete or weaken assertions immediately. First classify the unstable factor:
+   - timing, ordering, or scheduler grouping;
+   - filesystem cleanup, lock files, or generated output;
+   - shared process state or environment variables;
+   - platform-specific path, shell, locale, or line-ending behavior;
+   - external tool availability or version drift.
+6. For flaky tests, prefer isolation, deterministic fixtures, explicit waiting, runner locks, or narrower concurrency before `skip` markers. Use a skip only when the behavior is intentionally unsupported in that environment and the reason is documented.
+7. Do not reintroduce removed behavior solely because old tests expect it.
+8. When replacing subprocess tests with in-process helpers, verify that the helper does not mutate global process state that can leak across sibling tests. Pay special attention to `process.cwd()`, `process.env`, `process.argv`, `process.exitCode`, module-level caches, timers, and signal handlers.
+9. If several in-process CLI tests can run in the same Node test runner, either provide context-local state for the shared resource, serialize the affected tests, or keep the unsafe tests isolated in separate processes.
+10. Treat snapshot updates as manual unless `snapshot_update` is explicitly approved and configured.
+11. Keep tests deterministic and close to the behavior contract.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -107,6 +118,7 @@ Do not infer missing test commands.
 - If tests fail, inspect the first relevant failure.
 - Do not delete or weaken tests merely to make validation pass.
 - If it is uncertain whether a test is stale, report it instead of deleting it.
+- If a failure appears only under grouped or parallel in-process execution, look for shared process state before changing the behavior assertions.
 - If the test command is unavailable, report the missing intent.
 
 <!-- mustflow-section: output-format -->
@@ -117,6 +129,7 @@ Do not infer missing test commands.
 - Tests updated
 - Tests removed, with reason
 - Stale test candidates
+- Flaky or environmental classification and handling
 - Command intents run
 - Skipped command intents and reasons
 - Remaining test risks

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.22.12"
+version = "2.22.13"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"