mustflow 2.103.3 → 2.103.10

package/dist/core/related-files.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, readdirSync } from 'node:fs';
 import path from 'node:path';
+import { DEFAULT_IGNORED_DIRECTORIES, isIgnoredDirectoryPath } from './ignored-directories.js';
 import { ensureInside, ensureInsideWithoutSymlinks, readFileInsideWithoutSymlinks } from './safe-filesystem.js';
 export const RELATED_FILES_PACK_ID = 'repo';
 export const RELATED_FILES_SCRIPT_ID = 'related-files';
@@ -12,17 +13,7 @@ const MAX_ISSUES = 50;
 const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
 const RESOLVE_EXTENSIONS = [...SOURCE_EXTENSIONS, '.json'];
 const RELATED_EXTENSIONS = [...RESOLVE_EXTENSIONS, '.d.ts', '.md', '.mdx', '.css', '.scss', '.sass', '.less'];
-const IGNORED_DIRECTORIES = [
-    '.git',
-    '.mustflow/cache',
-    '.mustflow/state',
-    'node_modules',
-    'dist',
-    'build',
-    'coverage',
-    '.next',
-    '.turbo',
-];
+const IGNORED_DIRECTORIES = DEFAULT_IGNORED_DIRECTORIES;
 const CONFIG_FILE_PATTERNS = [
     /^package\.json$/u,
     /^tsconfig(?:\.[^.]+)?\.json$/u,
@@ -71,8 +62,7 @@ function isSourceLanguage(language) {
     return language !== 'json' && language !== 'other';
 }
 function isIgnoredDirectory(relativePath) {
-    const normalized = normalizeRelativePath(relativePath);
-    return IGNORED_DIRECTORIES.some((directory) => normalized === directory || normalized.startsWith(`${directory}/`));
+    return isIgnoredDirectoryPath(normalizeRelativePath(relativePath), IGNORED_DIRECTORIES);
 }
 function makeFinding(code, severity, pathValue, message) {
     return { code, severity, path: pathValue, message };

package/dist/core/repo-merge-conflict-scan.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { existsSync, lstatSync, readdirSync } from 'node:fs';
 import path from 'node:path';
+import { DEFAULT_IGNORED_DIRECTORIES, isIgnoredDirectoryPath } from './ignored-directories.js';
 import { ensureInsideWithoutSymlinks, readUtf8FileInsideWithoutSymlinks } from './safe-filesystem.js';
 export const REPO_MERGE_CONFLICT_SCAN_PACK_ID = 'repo';
 export const REPO_MERGE_CONFLICT_SCAN_SCRIPT_ID = 'merge-conflict-scan';
@@ -15,15 +16,9 @@ const MARKER_PATTERNS = [
     { prefix: '>>>>>>>', marker: 'end' },
 ];
 const SKIPPED_DIRECTORY_NAMES = new Set([
-    '.git',
-    'node_modules',
+    ...DEFAULT_IGNORED_DIRECTORIES,
     'vendor',
     'third_party',
-    'dist',
-    'build',
-    'coverage',
-    '.mustflow/cache',
-    '.mustflow/state',
 ]);
 function normalizeRelativePath(value) {
     return value.replace(/\\/gu, '/').replace(/^\.\/+/u, '').replace(/\/+$/u, '') || '.';
@@ -95,8 +90,7 @@ function collectGitChangedFiles(root, issues, findings) {
 }
 function shouldSkipDirectory(relativePath) {
     const normalized = normalizeRelativePath(relativePath);
-    const firstSegment = normalized.split('/')[0] ?? normalized;
-    return SKIPPED_DIRECTORY_NAMES.has(normalized) || SKIPPED_DIRECTORY_NAMES.has(firstSegment);
+    return isIgnoredDirectoryPath(normalized, [...SKIPPED_DIRECTORY_NAMES]);
 }
 function isLikelyTextFile(relativePath) {
     const extension = path.posix.extname(relativePath).toLowerCase();

package/dist/core/route-outline.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { lstatSync, readdirSync } from 'node:fs';
 import path from 'node:path';
+import { DEFAULT_IGNORED_DIRECTORIES, isIgnoredDirectoryPath } from './ignored-directories.js';
 import { ensureInside, ensureInsideWithoutSymlinks, readFileInsideWithoutSymlinks } from './safe-filesystem.js';
 export const CODE_ROUTE_OUTLINE_SCRIPT_ID = 'route-outline';
 export const CODE_ROUTE_OUTLINE_SCRIPT_REF = `code/${CODE_ROUTE_OUTLINE_SCRIPT_ID}`;
@@ -39,17 +40,7 @@ const LIFECYCLE_METHODS = [
     'onAfterHandle',
     'onError',
 ];
-const IGNORED_DIRECTORIES = [
-    '.git',
-    '.mustflow/cache',
-    '.mustflow/state',
-    'node_modules',
-    'dist',
-    'build',
-    'coverage',
-    '.next',
-    '.turbo',
-];
+const IGNORED_DIRECTORIES = DEFAULT_IGNORED_DIRECTORIES;
 const ERROR_CODES = new Set([
     'code_route_outline_path_outside_root',
     'code_route_outline_unreadable_path',
@@ -85,8 +76,7 @@ function languageForPath(filePath) {
     }
 }
 function isIgnoredDirectory(relativePath) {
-    const normalized = normalizeRelativePath(relativePath);
-    return IGNORED_DIRECTORIES.some((directory) => normalized === directory || normalized.startsWith(`${directory}/`));
+    return isIgnoredDirectoryPath(normalizeRelativePath(relativePath), IGNORED_DIRECTORIES);
 }
 function makeFinding(code, severity, pathValue, message) {
     return { code, severity, path: pathValue, message };

package/dist/core/script-pack-suggestions.js

@@ -80,26 +80,37 @@ export function classifyScriptPackPathSurface(relativePath) {
     return surfaces.length > 0 ? uniqueSortedSurfaces(surfaces) : ['unknown'];
 }
 function readChangedPaths(mustflowRoot, issues) {
-    const result = spawnSync('git', ['status', '--short'], {
+    const result = spawnSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all'], {
         cwd: mustflowRoot,
         encoding: 'utf8',
         stdio: ['ignore', 'pipe', 'pipe'],
         windowsHide: true,
+        maxBuffer: 16 * 1024 * 1024,
     });
-    if (result.status !== 0) {
-        const detail = result.stderr.trim() || result.stdout.trim() || `git status exited with ${result.status}`;
+    if (result.error || result.status !== 0) {
+        const detail = result.error?.message ?? (result.stderr.trim() || result.stdout.trim() || `git status exited with ${result.status}`);
         issues.push(`Could not read changed paths: ${detail}`);
         return [];
     }
-    return result.stdout
-        .split(/\r?\n/u)
-        .map((line) => line.trimEnd())
-        .filter((line) => line.length > 0)
-        .map((line) => {
-        const renamed = /\s->\s(?<target>.+)$/u.exec(line);
-        return renamed?.groups?.target ?? line.slice(3).trim();
-    })
-        .filter((entry) => entry.length > 0);
+    const paths = [];
+    const records = result.stdout.split('\0');
+    let index = 0;
+    while (index < records.length) {
+        const record = records[index] ?? '';
+        index += 1;
+        if (record.length === 0) {
+            continue;
+        }
+        const status = record.slice(0, 2);
+        const relativePath = record.slice(3);
+        if (relativePath.length > 0) {
+            paths.push(relativePath);
+        }
+        if (status.includes('R') || status.includes('C')) {
+            index += 1;
+        }
+    }
+    return paths;
 }
 function surfacesForScript(script) {
     const surfaces = new Set();

package/dist/core/secret-risk-scan.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, readdirSync } from 'node:fs';
 import path from 'node:path';
+import { DEFAULT_IGNORED_DIRECTORIES, isIgnoredDirectoryPath } from './ignored-directories.js';
 import { ensureInside, ensureInsideWithoutSymlinks, readFileInsideWithoutSymlinks } from './safe-filesystem.js';
 export const SECRET_RISK_SCAN_PACK_ID = 'repo';
 export const SECRET_RISK_SCAN_SCRIPT_ID = 'secret-risk-scan';
@@ -35,17 +36,7 @@ const ENV_EXAMPLE_NAMES = [
     '.env.local.example',
     '.dev.vars.example',
 ];
-const IGNORED_DIRECTORIES = [
-    '.git',
-    '.mustflow/cache',
-    '.mustflow/state',
-    'node_modules',
-    'dist',
-    'build',
-    'coverage',
-    '.next',
-    '.turbo',
-];
+const IGNORED_DIRECTORIES = DEFAULT_IGNORED_DIRECTORIES;
 const ERROR_CODES = new Set([
     'secret_risk_path_outside_root',
     'secret_risk_unreadable_path',
@@ -68,8 +59,7 @@ function makeFinding(code, severity, pathValue, message, details = {}) {
     return { code, severity, path: pathValue, message, ...details };
 }
 function isIgnoredDirectory(relativePath) {
-    const normalized = normalizeRelativePath(relativePath);
-    return IGNORED_DIRECTORIES.some((directory) => normalized === directory || normalized.startsWith(`${directory}/`));
+    return isIgnoredDirectoryPath(normalizeRelativePath(relativePath), IGNORED_DIRECTORIES);
 }
 function isSecretFile(relativePath) {
     return SECRET_FILE_NAMES.includes(path.basename(relativePath).toLowerCase());

package/dist/core/skill-route-resolution.js

@@ -8,6 +8,7 @@ const SKILL_ROUTER_PATH = '.mustflow/skills/router.toml';
 const SKILL_ROUTES_METADATA_PATH = '.mustflow/skills/routes.toml';
 const SKILL_FRONTMATTER_SOURCE = '.mustflow/skills/*/SKILL.md';
 const EXTERNAL_SKILL_FRONTMATTER_SOURCE = '.mustflow/external-skills/*/SKILL.md';
+const EXTERNAL_SKILL_PROVENANCE_FILE = 'mustflow-skill-source.json';
 const DEFAULT_MAX_CANDIDATES = 5;
 const DEFAULT_MAX_MAIN = 1;
 const DEFAULT_MAX_ADJUNCTS = 2;
@@ -214,6 +215,25 @@ function readSkillFrontmatterRoutes(projectRoot) {
     }
     return routes;
 }
+function hasValidExternalSkillProvenance(projectRoot, skillDirectory) {
+    const provenancePath = path.join(projectRoot, '.mustflow', 'external-skills', skillDirectory, EXTERNAL_SKILL_PROVENANCE_FILE);
+    if (!existsSync(provenancePath)) {
+        return false;
+    }
+    try {
+        const content = readUtf8FileInsideWithoutSymlinks(projectRoot, provenancePath, {
+            maxBytes: MUSTFLOW_TEXT_MAX_BYTES,
+        });
+        const parsed = JSON.parse(content);
+        return (isRecord(parsed) &&
+            parsed.schema_version === '1' &&
+            parsed.kind === 'external_skill_source' &&
+            isRecord(parsed.source));
+    }
+    catch {
+        return false;
+    }
+}
 function readExternalSkillFrontmatterRoutes(projectRoot) {
     const skillRoot = path.join(projectRoot, '.mustflow', 'external-skills');
     if (!existsSync(skillRoot)) {
@@ -227,7 +247,7 @@ function readExternalSkillFrontmatterRoutes(projectRoot) {
     for (const skillDirectory of skillDirectories) {
         const skillPath = `.mustflow/external-skills/${skillDirectory}/SKILL.md`;
         const absoluteSkillPath = path.join(projectRoot, ...skillPath.split('/'));
-        if (!existsSync(absoluteSkillPath)) {
+        if (!existsSync(absoluteSkillPath) || !hasValidExternalSkillProvenance(projectRoot, skillDirectory)) {
             continue;
         }
         const content = readUtf8FileInsideWithoutSymlinks(projectRoot, absoluteSkillPath, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.103.3",
+  "version": "2.103.10",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",
@@ -47,7 +47,7 @@
     "check:package": "node -e \"const fs=require('fs'); JSON.parse(fs.readFileSync('package.json','utf8')); console.log('package.json ok')\"",
     "check:typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build",
-    "check:pack": "npm pack --dry-run --json",
+    "check:pack": "npm pack --dry-run --json --ignore-scripts",
     "check:install": "npm run check:pack && node --test tests/integration/*.test.js",
     "release:check": "npm run check && npm run docs:check && npm run check:install",
     "prepublishOnly": "npm run release:check",

package/schemas/link-integrity-report.schema.json

@@ -86,6 +86,7 @@
         "max_file_bytes": { "type": "integer", "minimum": 1 },
         "default_paths": { "$ref": "#/$defs/stringArray" },
         "path_filters": { "$ref": "#/$defs/stringArray" },
+        "ignored_directories": { "$ref": "#/$defs/stringArray" },
         "checked_link_kinds": {
           "type": "array",
           "items": { "$ref": "#/$defs/linkKind" }

package/schemas/reference-drift-report.schema.json

@@ -86,6 +86,7 @@
         "max_file_bytes": { "type": "integer", "minimum": 1 },
         "default_paths": { "$ref": "#/$defs/stringArray" },
         "path_filters": { "$ref": "#/$defs/stringArray" },
+        "ignored_directories": { "$ref": "#/$defs/stringArray" },
         "checked_reference_kinds": {
           "type": "array",
           "items": { "$ref": "#/$defs/referenceKind" }

package/templates/default/i18n.toml

@@ -116,7 +116,7 @@ translations = {}
 [documents."skill.ai-generated-code-hardening"]
 source = "locales/en/.mustflow/skills/ai-generated-code-hardening/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.quality-gaming-guard"]
@@ -194,13 +194,13 @@ translations = {}
 [documents."skill.hot-path-performance-review"]
 source = "locales/en/.mustflow/skills/hot-path-performance-review/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.api-request-performance-review"]
 source = "locales/en/.mustflow/skills/api-request-performance-review/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.api-failure-triage"]
@@ -326,7 +326,7 @@ translations = {}
 [documents."skill.quadratic-scan-review"]
 source = "locales/en/.mustflow/skills/quadratic-scan-review/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.type-state-modeling-review"]
@@ -568,6 +568,12 @@ source_locale = "en"
 revision = 1
 translations = {}
 
+[documents."skill.idea-triage"]
+source = "locales/en/.mustflow/skills/idea-triage/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.astro-code-change"]
 source = "locales/en/.mustflow/skills/astro-code-change/SKILL.md"
 source_locale = "en"
@@ -673,7 +679,7 @@ translations = {}
 [documents."skill.react-code-change"]
 source = "locales/en/.mustflow/skills/react-code-change/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.python-code-change"]
@@ -769,7 +775,13 @@ translations = {}
 [documents."skill.completion-evidence-gate"]
 source = "locales/en/.mustflow/skills/completion-evidence-gate/SKILL.md"
 source_locale = "en"
-revision = 4
+revision = 5
+translations = {}
+
+[documents."skill.next-action-menu"]
+source = "locales/en/.mustflow/skills/next-action-menu/SKILL.md"
+source_locale = "en"
+revision = 3
 translations = {}
 
 [documents."skill.evidence-stall-breaker"]
@@ -1080,7 +1092,7 @@ translations = {}
 [documents."skill.vertical-slice-tdd"]
 source = "locales/en/.mustflow/skills/vertical-slice-tdd/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.llm-service-ux-review"]

package/templates/default/locales/en/.mustflow/skills/ai-generated-code-hardening/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.ai-generated-code-hardening
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: ai-generated-code-hardening
-description: Apply this skill when AI-generated, assistant-authored, vibe-coded, or broad code changes need evidence-backed hardening against symptom-only fixes, pinpoint hardcoding, duplicate helpers or shapes, hidden coupling, weak tests, swallowed errors, excessive complexity, and boundary drift.
+description: Apply this skill when AI-generated, assistant-authored, vibe-coded, or broad code changes need evidence-backed hardening against symptom-only fixes, pinpoint hardcoding, duplicate helpers or shapes, hidden coupling, fake small-sample performance confidence, weak tests, swallowed errors, excessive complexity, and boundary drift.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -33,8 +33,8 @@ Use this skill to turn agent-written code from "looks plausible" into maintainab
 repository code. The goal is not style cleanup. The goal is to catch the failure
 modes that appear when an agent forgets the repository between sessions: symptom-only
 patches, pinpoint hardcoding, duplicate helpers, duplicate shapes, hidden coupling,
-weak tests, swallowed errors, accidental public surfaces, and oversized functions or
-files.
+fake confidence from tiny fixtures, hidden repeated work, weak tests, swallowed errors,
+accidental public surfaces, and oversized functions or files.
 
 <!-- mustflow-section: use-when -->
 ## Use When
@@ -51,6 +51,9 @@ files.
   re-export drift.
 - Tests were added or changed and may only check strings, function names, snapshots,
   mocks, or implementation details instead of observable behavior.
+- The code looks clean on sample data but may hide repeated scans, repeated copying,
+  repeated I/O, unbounded fan-out, allocation churn, or response-size growth under
+  realistic data.
 - Error handling, fallback paths, defensive guards, or default values were added in
   multiple callers instead of one boundary.
 - New or changed functions/files are becoming hard to review because of excessive
@@ -189,7 +192,23 @@ files.
    - Split a god file only when the new module has a stable owner, direction, and
      verification path.
 
-8. Harden tests against fake confidence.
+8. Check small-sample performance traps.
+   - Treat fixture-sized success as weak evidence when the path handles users,
+     orders, comments, logs, rows, files, permissions, relations, or rendered list
+     items that can grow.
+   - Search AI-authored code for `map`, `filter`, `find`, `findIndex`, `includes`,
+     `indexOf`, `reduce`, `sort`, `slice`, `splice`, `shift`, spread accumulation,
+     `concat`, `cloneDeep`, `JSON.stringify`, `parse`, `validate`, `sanitize`,
+     `normalize`, and helper names such as `isAllowed`, `canAccess`, `resolve`,
+     `build`, or `format` in repeated paths.
+   - Escalate concrete hidden O(N^2), allocation churn, or request fan-out evidence
+     to `quadratic-scan-review`, `hot-path-performance-review`, or
+     `api-request-performance-review` instead of burying it as style feedback.
+   - Do not claim a performance improvement from static review alone. Mark it as
+     static complexity risk unless configured tests, query counts, traces, profiles,
+     or benchmarks support the claim.
+
+9. Harden tests against fake confidence.
    - Verify behavior and side effects, not only function names, strings, snapshots,
      or the presence of files.
    - For bug fixes, add at least one nearby negative or sibling case when feasible so
@@ -203,7 +222,7 @@ files.
    - If production code gained defensive fallback only to satisfy a brittle test,
      fix the test or move the fallback to the owning boundary.
 
-9. Use enforcement evidence without inventing enforcement.
+10. Use enforcement evidence without inventing enforcement.
    - Run existing configured lint, build, and related test intents when they cover
      the risk.
    - If the repository lacks dependency-boundary, complexity, max-depth,
@@ -212,7 +231,7 @@ files.
    - Never paste outside plugin commands, package-manager commands, or CI recipes
      into mustflow command contracts without command-contract review.
 
-10. Decide fix now, defer, or report.
+11. Decide fix now, defer, or report.
    - Fix now when the issue is in the touched code, small, directly tied to the
      current behavior, and verifiable with configured commands.
    - Defer when the issue needs broad architecture work, new dependencies, new CI
@@ -235,6 +254,8 @@ files.
   duplicated guard/fallback risk is documented.
 - Tests exercise behavior and meaningful side effects, with edge and failure paths
   covered where relevant to the change.
+- Sample-data performance confidence has been checked against realistic data-growth,
+  repeated-work, allocation, and I/O fan-out risks where relevant.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -281,5 +302,7 @@ Include:
   found or ruled out.
 - Error-handling and fallback decisions.
 - Test hardening: behavior assertions, side effects, edge cases, and mock boundary.
+- Small-sample performance traps: hidden repeated scans, copy churn, repeated I/O,
+  unbounded fan-out, or response growth fixed, escalated, or reported.
 - Configured verification intents run and their result.
 - Deferred enforcement, lint, or CI guard suggestions, clearly marked as not added.

package/templates/default/locales/en/.mustflow/skills/api-request-performance-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.api-request-performance-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: api-request-performance-review
@@ -58,8 +58,8 @@ The core question is: "For one request, how many times do we repeat the same I/O
 - Request path: endpoint, route, handler, controller, resolver, serializer, mapper, middleware, service method, response builder, and downstream calls under review.
 - Request cost ledger inputs: route span, DB query count, Redis call count, external API call count, filesystem or object-storage calls, payload size, response bytes, JSON serialization time, DTO mapping time, cache hit or miss, queue time, pool acquire wait, transaction duration, lock wait, and request-path CPU work when available.
 - Data shape: request parameters, page size, relation counts, tenant or user scope, expected result size, maximum payload, large JSON/TEXT/BLOB fields, and response projection.
-- ORM behavior: lazy loading, eager loading, generated SQL, relation access in serializers or templates, Django `select_related` and `prefetch_related`, Rails `includes`, `preload`, `eager_load`, and `strict_loading`, or equivalent framework behavior.
-- Database evidence when available: `SELECT *`, app-side filtering or sorting, deep `OFFSET`, `COUNT(*)`, index fit for `WHERE` plus `ORDER BY` plus `LIMIT`, `EXPLAIN`, estimated rows, actual rows, join cardinality, and selectivity.
+- ORM behavior: lazy loading, eager loading, generated SQL, relation access in serializers or templates, `include` versus explicit `select`, relation load strategy, Django `select_related` and `prefetch_related`, Rails `includes`, `preload`, `eager_load`, and `strict_loading`, or equivalent framework behavior.
+- Database evidence when available: actual SQL, query count, repeated `SELECT ... WHERE id = ?`, `SELECT *`, app-side filtering or sorting, deep `OFFSET`, `COUNT(*)`, index fit for `WHERE` plus `ORDER BY` plus `LIMIT`, `EXPLAIN`, scan type, sort method, estimated rows, actual rows, join cardinality, and selectivity.
 - Cache and Redis evidence: request-scope cache, key dimensions, cache miss path, `MGET`, pipeline behavior, Redis round trips, Redis Slow Log limitations, hot keys, fallback behavior, and stampede controls.
 - Correctness boundaries: authorization, tenant isolation, ordering, duplicates, pagination stability, consistency, idempotency, timeout, cancellation, partial failure, stale data, and response contract.
 - Relevant command-intent contract entries for build, tests, docs, release checks, and mustflow validation.
@@ -98,6 +98,8 @@ The core question is: "For one request, how many times do we repeat the same I/O
    - In Django, choose `select_related` for single-valued relations and `prefetch_related` for multi-valued relations when the route actually needs them.
    - In Rails, compare `includes`, `preload`, `eager_load`, and `strict_loading`; use strict loading or query-count tests where local patterns support them.
    - Treat eager loading too much as a separate bug. It can replace N+1 with row explosion, duplicate parents, memory bloat, or huge response mapping.
+   - For Prisma-style APIs, do not trust `include` as a performance proof. Compare actual SQL, query count, selected columns, relation load strategy, and response shape.
+   - Treat repeated `count`, `exists`, `sum`, `latest`, or `first` queries in list serialization as N+1 candidates; prefer grouped aggregation, batched lookup, or database-side projection when semantics match.
 5. Check query projection and response projection together.
    - Flag `SELECT *`, full entity hydration, unbounded DTOs, and list endpoints that fetch large JSON, TEXT, BLOB, image, metadata, audit, or internal columns.
    - Fetch detail fields only after narrowing the row set when the route returns a list, feed, search result, or admin table.
@@ -111,7 +113,10 @@ The core question is: "For one request, how many times do we repeat the same I/O
    - Expensive `COUNT(*)` for every request needs a product reason, approximate or cached count policy, or deferred count behavior.
 8. Match indexes to the whole request query.
    - Check `WHERE`, `ORDER BY`, and `LIMIT` together instead of asking only whether one predicate has an index.
-   - Functions around columns, implicit casts, `LOWER(email)`, `DATE(created_at)`, timezone conversion, `%keyword%`, low-selectivity predicates, and mismatched sort order can defeat useful index access.
+   - Prefer query-shaped index review over column-name index decoration: composite indexes often need equality predicates first, range or ordering columns next, and stable tie-breakers for pagination.
+   - Functions around columns, implicit casts, `LOWER(email)`, `DATE(created_at)`, timezone conversion, `%keyword%`, low-selectivity predicates, and mismatched sort order can defeat useful index access. Expression indexes, range predicates, or search-specific indexes may be needed when the database owns that capability.
+   - For soft-delete, tenant, status, or visibility predicates that appear on nearly every request, review partial or filtered indexes where the database supports them.
+   - For list projections, check whether a covering or index-only access path is possible before fetching large JSON, TEXT, BLOB, HTML, metadata, or audit columns.
    - When plan evidence exists, compare `EXPLAIN` estimated rows with actual rows, join cardinality, loops, rows examined, rows returned, buffers, temp files, sort method, and lock or pool wait.
 9. Keep external calls out of transactions.
    - Do not hold a DB transaction while waiting for an external API, file upload, object storage, Redis fallback, image processing, logging sink, or user-controlled operation.
@@ -140,13 +145,14 @@ The core question is: "For one request, how many times do we repeat the same I/O
 17. Label evidence honestly.
     - Static review can identify likely API latency risks but cannot prove speedup.
     - A trace from a tiny fixture, warm local cache, or empty database is not representative production evidence.
+    - If actual SQL, query-count, or query-plan evidence is missing, say so instead of treating tidy ORM code as proof of efficient database behavior.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - The API request boundary and Request cost ledger are explicit.
 - DB query count, Redis call count, external API call count, cache hit or miss behavior, response bytes, serialization cost, transaction scope, pool acquire wait, and request-path CPU work are fixed, bounded, instrumented, or reported.
-- ORM lazy loading, eager-loading overfetch, `SELECT *`, app-side filtering or sorting, deep `OFFSET`, expensive `COUNT(*)`, index mismatch, external call inside transaction, Redis loop, and cache miss amplification are checked where relevant.
+- ORM lazy loading, eager-loading overfetch, repeated count or aggregate queries, actual SQL and query count, `SELECT *`, app-side filtering or sorting, deep `OFFSET`, expensive `COUNT(*)`, index mismatch, composite/partial/expression/covering index fit, external call inside transaction, Redis loop, and cache miss amplification are checked where relevant.
 - Correctness, authorization, tenant isolation, idempotency, ordering, pagination stability, partial failure, cancellation, timeout, and stale-data behavior remain intact or are reported as tradeoffs.
 - API performance claims are backed by configured evidence, trace evidence, plan evidence, or labeled as static review risk.
 
@@ -181,7 +187,7 @@ Use the narrowest configured test, build, docs, release, or mustflow intent that
 
 - API request path reviewed
 - Request cost ledger: route span, DB query count, Redis count, external API calls, filesystem or object-storage calls, payload size, response bytes, JSON serialization time, DTO mapping time, cache hit or miss, queue time, pool acquire wait, transaction duration, lock wait, and request-path CPU work
-- ORM lazy loading, eager loading, projection, pagination, count, index fit, app-side filtering or sorting, transaction, pool, Redis, cache miss, serialization, response size, CPU-heavy request work, and observability findings
+- ORM lazy loading, eager loading, actual SQL, query count, projection, pagination, count, index fit, app-side filtering or sorting, transaction, pool, Redis, cache miss, serialization, response size, CPU-heavy request work, and observability findings
 - API request performance change made or recommended
 - Evidence level: measured trace, configured-test evidence, plan evidence, static review risk, manual-only, missing, or not applicable
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/completion-evidence-gate/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.completion-evidence-gate
 locale: en
 canonical: true
-revision: 4
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: completion-evidence-gate
@@ -43,6 +43,8 @@ missing, blocked, failed, stale, or only partially relevant.
 
 - A task is ready for final reporting after files were created, modified, deleted, or intentionally left unchanged.
 - The user asks whether work is complete, safe to merge, ready to commit, verified, released, installed, or done.
+- A non-trivial task, commit, push, release preparation, deploy preparation, verification run, or
+  paused implementation is being reported and at least one concrete next action remains.
 - A change touched more than one surface, such as source, tests, schemas, templates, workflow files, package metadata, documentation, or generated output.
 - Verification was skipped, failed, manual-only, unavailable, or chosen from multiple plausible command intents.
 - A previous verification failure, repeated-failure warning, write-drift risk, scope-drift risk, or external evidence risk could make a completion claim misleading.
@@ -70,8 +72,9 @@ missing, blocked, failed, stale, or only partially relevant.
 - Optional script-pack discovery evidence when the command contract exposes `script_pack_list`.
 - Synchronized surfaces expected by the changed contract: source, tests, fixtures, schemas, templates, manifests, docs, release metadata, generated output, and localized copies.
 - Known remaining risks, unverified assumptions, blocked decisions, and rollback notes.
-- Concrete follow-up candidates, if any, plus whether a bounded `next-action-menu` should be
-  included or intentionally omitted.
+- Concrete follow-up candidates, including gated actions such as commit, push, release, deploy,
+  dependency upgrade, migration, or manual verification when they are plausible next steps.
+- Whether a bounded `next-action-menu` must be included or intentionally omitted.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -120,11 +123,17 @@ missing, blocked, failed, stale, or only partially relevant.
    - Use `implemented but unverified` when the files changed but no relevant configured verification was run.
    - Use `blocked` when required evidence cannot be produced without a missing decision, unavailable environment, manual-only command, failed prerequisite, or user approval.
    - Use `not complete` when a required acceptance criterion is not implemented or verification contradicts the claim.
-7. Decide whether a next-action menu is warranted.
-   - If there are concrete, evidence-backed follow-up tasks that would make the next user turn
-     cheaper, read and apply `next-action-menu` before final reporting.
+7. Decide whether a next-action menu is required.
+   - For a non-trivial final report, read and apply `next-action-menu` before final reporting when
+     at least one concrete, evidence-backed follow-up task remains.
+   - Treat changed-file work, a created commit, push or release readiness, deploy preparation,
+     completed verification, paused implementation, or unresolved manual gate as non-trivial for
+     this decision.
+   - Do not omit the menu merely because the remaining useful actions are approval-gated. Include
+     gated actions such as push, publish, deploy, dependency upgrade, migration, or manual release
+     verification as menu rows with the gate stated plainly.
    - If no useful follow-up exists, the user asked not to include recommendations, or the only next
-     actions are speculative or approval-gated, omit the menu and keep the final report concise.
+     actions are speculative, omit the menu and keep the final report concise.
    - Do not treat this gate as automatic host behavior: the menu appears only when the skill is
      selected and its use conditions are met.
 8. Write the final report from evidence, not confidence.
@@ -140,8 +149,10 @@ missing, blocked, failed, stale, or only partially relevant.
 - Every user requirement is mapped to proof, a limitation, or an explicit out-of-scope decision.
 - Skipped, missing, failed, stale, or manual-only verification is visible.
 - Contract, template, schema, docs, test, and release drift is either resolved or named as remaining risk.
-- Useful follow-up tasks either appear through `next-action-menu` or are intentionally omitted with a
-  clear reason when the menu conditions are not met.
+- For non-trivial final reports, useful follow-up tasks appear through `next-action-menu` whenever
+  at least one concrete next action remains, including approval-gated next actions.
+- Omitted menus state a clear reason grounded in no concrete next action, user opt-out, or
+  speculative-only follow-ups.
 - No unconfigured command, hidden transcript, broad log, or invented tool result is treated as proof.
 
 <!-- mustflow-section: verification -->