mustflow 2.22.12 → 2.22.14

package/schemas/commands.schema.json

@@ -100,6 +100,29 @@
         "escalate_to": { "$ref": "#/$defs/stringArray" }
       }
     },
+    "intentInputs": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/$defs/intentInput" }
+    },
+    "intentInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "enum": ["path", "enum", "boolean", "integer", "literal"] },
+        "description": { "type": "string" },
+        "required": { "type": "boolean" },
+        "placeholder": { "type": "string" },
+        "secret": { "type": "boolean" },
+        "allowed_roots": { "$ref": "#/$defs/stringArray" },
+        "allowed_extensions": { "$ref": "#/$defs/stringArray" },
+        "allowed_values": { "$ref": "#/$defs/stringArray" },
+        "value": { "type": ["string", "number", "boolean"] },
+        "min": { "type": "integer" },
+        "max": { "type": "integer" }
+      }
+    },
     "costHints": {
       "type": "object",
       "additionalProperties": false,
@@ -110,6 +133,19 @@
         "cost_tier": { "type": "string" }
       }
     },
+    "intentPrecondition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["path_exists", "artifact_freshness"] },
+        "label": { "type": "string" },
+        "path": { "type": "string" },
+        "artifact": { "type": "string" },
+        "sources": { "$ref": "#/$defs/stringArray" },
+        "satisfy_intent": { "type": "string" }
+      }
+    },
     "relationHints": {
       "type": "object",
       "additionalProperties": false,
@@ -165,6 +201,11 @@
         },
         "covers": { "$ref": "#/$defs/coverageHints" },
         "selection": { "$ref": "#/$defs/selectionHints" },
+        "inputs": { "$ref": "#/$defs/intentInputs" },
+        "preconditions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/intentPrecondition" }
+        },
         "cost": { "$ref": "#/$defs/costHints" },
         "relations": { "$ref": "#/$defs/relationHints" },
         "reason": { "type": "string" },

package/schemas/explain-report.schema.json

@@ -14,7 +14,7 @@
   "properties": {
     "schema_version": { "const": "1" },
     "command": { "const": "explain" },
-    "topic": { "enum": ["anchor", "asset-optimization", "authority", "command", "retention", "skill", "skills", "surface", "verify"] },
+    "topic": { "enum": ["anchor", "asset-optimization", "authority", "command", "retention", "skill", "skills", "surface", "verify", "why"] },
     "mustflow_root": { "type": "string" },
     "decision": {
       "oneOf": [
@@ -25,7 +25,8 @@
         { "$ref": "#/$defs/skillRouteAlignmentDecision" },
         { "$ref": "#/$defs/publicSurfaceDecision" },
         { "$ref": "#/$defs/sourceAnchorDecision" },
-        { "$ref": "#/$defs/verificationDecision" }
+        { "$ref": "#/$defs/verificationDecision" },
+        { "$ref": "#/$defs/latestFailureDecision" }
       ]
     }
   },
@@ -350,6 +351,10 @@
             "requiredAfter": {
               "type": "array",
               "items": { "type": "string" }
+            },
+            "preconditions": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/commandPrecondition" }
             }
           }
         },
@@ -869,7 +874,7 @@
         "destructive",
         "successExitCodes",
         "requiredAfter"
-      ],
+          ],
       "properties": {
         "name": { "type": "string" },
         "status": { "type": ["string", "null"] },
@@ -892,6 +897,110 @@
         "requiredAfter": {
           "type": "array",
           "items": { "type": "string" }
+        },
+        "preconditions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/commandPrecondition" }
+        }
+      }
+    },
+    "commandPrecondition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "label",
+        "status",
+        "detail",
+        "path",
+        "artifact",
+        "sources",
+        "newestSource",
+        "satisfyIntent"
+      ],
+      "properties": {
+        "kind": { "type": "string" },
+        "label": { "type": ["string", "null"] },
+        "status": { "enum": ["satisfied", "missing", "stale", "unknown", "invalid"] },
+        "detail": { "type": "string" },
+        "path": { "type": ["string", "null"] },
+        "artifact": { "type": ["string", "null"] },
+        "sources": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "newestSource": { "type": ["string", "null"] },
+        "satisfyIntent": {
+          "anyOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/preconditionSatisfyIntent" }
+          ]
+        }
+      }
+    },
+    "preconditionSatisfyIntent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["intent", "declared", "runnable", "status", "lifecycle", "runPolicy", "detail"],
+      "properties": {
+        "intent": { "type": "string" },
+        "declared": { "type": "boolean" },
+        "runnable": { "type": "boolean" },
+        "status": { "type": ["string", "null"] },
+        "lifecycle": { "type": ["string", "null"] },
+        "runPolicy": { "type": ["string", "null"] },
+        "detail": { "type": ["string", "null"] }
+      }
+    },
+    "latestFailureDecision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "decision",
+        "reason",
+        "effectiveAction",
+        "countsAsMustflowVerification",
+        "sourceFiles",
+        "latestFailure"
+      ],
+      "properties": {
+        "kind": { "const": "latest_failure" },
+        "decision": { "type": "string" },
+        "reason": { "type": "string" },
+        "effectiveAction": { "type": "string" },
+        "countsAsMustflowVerification": { "const": false },
+        "sourceFiles": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "latestFailure": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "path",
+            "present",
+            "valid",
+            "failed",
+            "status",
+            "intent",
+            "exitCode",
+            "errorKind",
+            "durationMs",
+            "summary"
+          ],
+          "properties": {
+            "path": { "const": ".mustflow/state/runs/latest.json" },
+            "present": { "type": "boolean" },
+            "valid": { "type": "boolean" },
+            "failed": { "type": "boolean" },
+            "status": { "type": ["string", "null"] },
+            "intent": { "type": ["string", "null"] },
+            "exitCode": { "type": ["integer", "null"] },
+            "errorKind": { "type": ["string", "null"] },
+            "durationMs": { "type": ["integer", "null"] },
+            "summary": { "type": "string" }
+          }
         }
       }
     },
@@ -950,7 +1059,8 @@
         "effectiveAction",
         "countsAsMustflowVerification",
         "sourceFiles",
-        "route"
+        "route",
+        "selectionEvidence"
       ],
       "properties": {
         "kind": { "const": "skill_route" },
@@ -994,6 +1104,44 @@
               "items": { "type": "string" }
             }
           }
+        },
+        "selectionEvidence": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "matchedBy",
+            "requiredInputs",
+            "missingInputs",
+            "candidateAdjuncts",
+            "unmatchedPaths",
+            "gapNotes"
+          ],
+          "properties": {
+            "matchedBy": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "requiredInputs": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "missingInputs": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "candidateAdjuncts": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "unmatchedPaths": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "gapNotes": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
         }
       }
     },

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 -->