mustflow 2.58.0 → 2.59.0

package/README.md

@@ -122,6 +122,7 @@ mustflow installs and validates an agent workflow for user projects.
 - Checks installation health and configuration structure with `mf check` and `mf doctor`.
 - Reports host adapter compatibility with `mf adapters status` without generating host-specific files or treating them as command authority.
 - Classifies changed files, public surfaces, and validation reasons with `mf classify`.
+- Inspects changed files for quality-gaming patterns such as line stuffing, suppressions, test bypass markers, type escapes, and placeholder implementations with `mf quality check`.
 - Prints execution-free verification plans with `mf verify --plan-only --json`, including a machine-readable verification decision graph and read-only local-index lock explanations when available.
 - Runs only allowed one-shot commands within a timeout via `mf run <intent>` or `mf verify` when the selected intent is runnable.
 - Writes command receipts under `.mustflow/state/runs/run-*` and atomically updates `.mustflow/state/runs/latest.json`.
@@ -271,6 +272,8 @@ mf run mustflow_update_apply
 | `mf context --json` | Print read order, command rules, available capabilities, and recent run summary as JSON. |
 | `mf map --stdout` | Print the current mustflow root map to stdout. |
 | `mf map --write` | Create or update `REPO_MAP.md`. |
+| `mf quality check` | Inspect changed files for quality-gaming patterns without writing files. |
+| `mf quality check --all` | Inspect every tracked text file for quality-gaming patterns. |
 | `mf run <intent>` | Run an allowed one-shot command. |
 | `mf run <intent> --wait` | Wait for conflicting active run locks before executing the command. |
 | `mf run <intent> --dry-run --json` | Preview whether an intent is runnable and what command metadata would be used, without executing it. |

package/dist/cli/commands/quality.js

@@ -0,0 +1,89 @@
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { formatCliOptionParseError, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { inspectQualityGaming } from '../../core/quality-gaming.js';
+const QUALITY_OPTIONS = [
+    { name: '--json', kind: 'boolean' },
+    { name: '--all', kind: 'boolean' },
+];
+export function getQualityHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf quality <check> [options]',
+        summary: t(lang, 'quality.help.summary'),
+        options: [
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '--all', description: t(lang, 'quality.help.option.all') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: ['mf quality check', 'mf quality check --json', 'mf quality check --all'],
+        exitCodes: [
+            { label: '0', description: t(lang, 'quality.help.exit.ok') },
+            { label: '1', description: t(lang, 'quality.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseQualityOptions(args, lang) {
+    const [action, ...rest] = args;
+    const parsed = parseCliOptions(rest, QUALITY_OPTIONS, { allowPositionals: true });
+    const json = hasParsedCliOption(parsed, '--json');
+    const all = hasParsedCliOption(parsed, '--all');
+    if (action !== 'check') {
+        return {
+            action: 'check',
+            json,
+            all,
+            error: action ? t(lang, 'quality.error.unknownAction', { action }) : t(lang, 'quality.error.missingAction'),
+        };
+    }
+    if (parsed.error) {
+        return { action, json, all, error: formatCliOptionParseError(parsed.error, lang) };
+    }
+    return { action, json, all };
+}
+function renderQualitySummary(report, lang) {
+    const lines = [
+        t(lang, 'quality.title'),
+        `${t(lang, 'label.mode')}: ${report.mode}`,
+        `${t(lang, 'label.scope')}: ${report.scope}`,
+        `${t(lang, 'quality.label.checkedFiles')}: ${report.checked_files}`,
+        `${t(lang, 'quality.label.riskCount')}: ${report.risk_count}`,
+    ];
+    if (report.issues.length > 0) {
+        lines.push(t(lang, 'quality.label.issues'), ...report.issues.map((issue) => `- ${issue}`));
+    }
+    if (report.risky_files.length > 0) {
+        lines.push(t(lang, 'quality.label.riskyFiles'));
+        for (const file of report.risky_files) {
+            lines.push(`- ${file.path} (${file.risk_count})`);
+            for (const risk of file.risks) {
+                const line = risk.line === null ? '' : `:${risk.line}`;
+                lines.push(`  - ${risk.code}${line} [${risk.severity}] ${risk.detail}`);
+            }
+        }
+    }
+    if (report.risky_files.length === 0 && report.issues.length === 0) {
+        lines.push(t(lang, 'quality.clean'));
+    }
+    return lines.join('\n');
+}
+export function runQuality(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getQualityHelp(lang));
+        return 0;
+    }
+    const options = parseQualityOptions(args, lang);
+    if (options.error) {
+        printUsageError(reporter, options.error, 'mf quality --help', getQualityHelp(lang), lang);
+        return 1;
+    }
+    const report = inspectQualityGaming(resolveMustflowRoot(), {
+        scope: options.all ? 'tracked' : 'changed',
+    });
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderQualitySummary(report, lang));
+    return report.ok ? 0 : 1;
+}

package/dist/cli/commands/tech.js

@@ -3,6 +3,7 @@ import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.j
 import { writeUtf8FileInsideWithoutSymlinks } from '../lib/filesystem.js';
 import { isRecord } from '../lib/command-contract.js';
 import { t } from '../lib/i18n.js';
+import { checkNpmPackageExists } from '../lib/npm-version-check.js';
 import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { readMustflowTomlFile } from '../lib/toml.js';
@@ -14,6 +15,7 @@ const TECH_OPTIONS = [
     { name: '--status', kind: 'string' },
     { name: '--ecosystem', kind: 'string' },
     { name: '--package', kind: 'string' },
+    { name: '--verify', kind: 'boolean' },
     { name: '--why', kind: 'string' },
     { name: '--constraint', kind: 'string' },
 ];
@@ -40,13 +42,14 @@ export function getTechHelp(lang = 'en') {
             { label: '--status <status>', description: `Preference status: ${TECHNOLOGY_STATUSES.join(', ')}` },
             { label: '--ecosystem <ecosystem>', description: 'Package ecosystem or platform, such as npm, cargo, pip, go, or deno' },
             { label: '--package <package>', description: 'Package name to associate with the preference. Repeatable.' },
+            { label: '--verify', description: 'Verify listed npm packages exist before writing the preference' },
             { label: '--why <text>', description: 'Short rationale for the preference' },
             { label: '--constraint <text>', description: 'Guardrail agents must keep in mind. Repeatable.' },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
         examples: [
             'mf tech list',
-            'mf tech add framework nextjs --scope frontend --ecosystem npm --package next --package react --why "Preferred React app framework"',
+            'mf tech add framework nextjs --scope frontend --ecosystem npm --package next --package react --verify --why "Preferred React app framework"',
             'mf tech add language rust --scope backend --status preferred --why "Use for correctness-critical engines"',
             'mf tech add library jquery --scope frontend --status avoid --why "Avoid new usage"',
             'mf tech suggest --scope frontend',
@@ -71,6 +74,7 @@ function parseTechOptions(args, lang) {
             status: null,
             ecosystem: null,
             packages: [],
+            verify: false,
             why: null,
             constraints: [],
             error: actionToken ? `Unknown tech action: ${actionToken}` : 'Specify a tech action: list, add, remove, or suggest',
@@ -87,6 +91,7 @@ function parseTechOptions(args, lang) {
             status: null,
             ecosystem: null,
             packages: [],
+            verify: hasParsedCliOption(parsed, '--verify'),
             why: null,
             constraints: [],
             error: formatCliOptionParseError(parsed.error, lang),
@@ -109,6 +114,7 @@ function parseTechOptions(args, lang) {
         status,
         ecosystem: getParsedCliStringOption(parsed, '--ecosystem'),
         packages: getRepeatedStringOptions(parsed.occurrences, '--package'),
+        verify: hasParsedCliOption(parsed, '--verify'),
         why: getParsedCliStringOption(parsed, '--why'),
         constraints: getRepeatedStringOptions(parsed.occurrences, '--constraint'),
     };
@@ -123,6 +129,7 @@ function invalidParsed(action, positionals, json, error) {
         status: null,
         ecosystem: null,
         packages: [],
+        verify: false,
         why: null,
         constraints: [],
         error,
@@ -239,7 +246,44 @@ function findExistingIndex(preferences, candidate) {
         return preference.kind === candidate.kind && normalizeTechnologyKey(preference.name) === normalizeTechnologyKey(candidate.name);
     });
 }
-function runAdd(projectRoot, options, reporter) {
+async function verifyNpmPackages(options, reporter) {
+    if (!options.verify) {
+        return [];
+    }
+    if (options.action !== 'add') {
+        reporter.stderr(renderCliError('--verify is only supported with mf tech add', 'mf tech --help'));
+        return null;
+    }
+    if (options.packages.length === 0) {
+        reporter.stderr(renderCliError('--verify requires at least one --package value', 'mf tech --help'));
+        return null;
+    }
+    if (options.ecosystem !== 'npm') {
+        reporter.stderr(renderCliError('--verify currently supports --ecosystem npm only', 'mf tech --help'));
+        return null;
+    }
+    const checks = [];
+    for (const packageName of options.packages) {
+        try {
+            const check = await checkNpmPackageExists(packageName);
+            if (!check.exists) {
+                reporter.stderr(renderCliError(`npm package not found: ${packageName}`, 'mf tech --help'));
+                return null;
+            }
+            checks.push(check);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            reporter.stderr(renderCliError(`Could not verify npm package ${packageName}: ${message}`, 'mf tech --help'));
+            return null;
+        }
+    }
+    return checks;
+}
+function renderVerifiedPackageNames(checks) {
+    return checks.map((check) => check.resolvedName ?? check.packageName).join(', ');
+}
+async function runAdd(projectRoot, options, reporter) {
     const [kindToken, nameToken] = options.positionals;
     if (!isTechnologyKind(kindToken ?? null)) {
         reporter.stderr(renderCliError('Missing or unsupported technology kind', 'mf tech --help'));
@@ -277,6 +321,10 @@ function runAdd(projectRoot, options, reporter) {
     const preferences = [...file.preferences];
     const existingIndex = findExistingIndex(preferences, candidate);
     const action = existingIndex === -1 ? 'created' : 'updated';
+    const verifiedPackages = await verifyNpmPackages(options, reporter);
+    if (verifiedPackages === null) {
+        return 1;
+    }
     if (existingIndex === -1) {
         preferences.push(candidate);
     }
@@ -285,9 +333,17 @@ function runAdd(projectRoot, options, reporter) {
     }
     writeTechnologyPreferences(projectRoot, preferences);
     if (options.json) {
-        reporter.stdout(JSON.stringify({ action, preference: candidate, path: TECHNOLOGY_CONFIG_RELATIVE_PATH }, null, 2));
+        reporter.stdout(JSON.stringify({
+            action,
+            preference: candidate,
+            path: TECHNOLOGY_CONFIG_RELATIVE_PATH,
+            verified_packages: verifiedPackages,
+        }, null, 2));
         return 0;
     }
+    if (verifiedPackages.length > 0) {
+        reporter.stdout(`Verified npm packages: ${renderVerifiedPackageNames(verifiedPackages)}`);
+    }
     reporter.stdout(`${action === 'created' ? 'Created' : 'Updated'} ${candidate.id} in ${TECHNOLOGY_CONFIG_RELATIVE_PATH}`);
     return 0;
 }
@@ -322,7 +378,7 @@ function runRemove(projectRoot, options, reporter) {
     reporter.stdout(`Removed ${removed.id} from ${TECHNOLOGY_CONFIG_RELATIVE_PATH}`);
     return 0;
 }
-export function runTech(args, reporter, lang = 'en') {
+export async function runTech(args, reporter, lang = 'en') {
     if (hasCliOptionToken(args, '--help', ['-h'])) {
         reporter.stdout(getTechHelp(lang));
         return 0;

package/dist/cli/i18n/en.js

@@ -39,6 +39,7 @@ export const enMessages = {
     "command.upgrade.summary": "Check the package version and safely update installed workflow files",
     "command.map.summary": "Generate REPO_MAP.md",
     "command.lineEndings.summary": "Inspect and normalize line-ending policy",
+    "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.run.summary": "Run a configured oneshot command",
     "command.context.summary": "Print machine-readable agent context",
     "command.tech.summary": "Manage technology preferences for agents",
@@ -731,6 +732,19 @@ Read these files before working:
     "lineEndings.error.unknownAction": "Unknown line-endings action: {action}",
     "lineEndings.error.checkModeOption": "check does not accept --apply or --dry-run",
     "lineEndings.error.conflictingModes": "Cannot combine --apply and --dry-run",
+    "quality.help.summary": "Inspect changed files for quality-gaming patterns such as line stuffing, validation suppressions, " +
+        "test bypass markers, type escapes, and placeholder implementations.",
+    "quality.help.option.all": "Inspect every tracked text file instead of only changed files",
+    "quality.help.exit.ok": "Quality-gaming risks were inspected and no risk was found",
+    "quality.help.exit.fail": "Quality-gaming risks, repository issues, or invalid input were found",
+    "quality.title": "mustflow quality check",
+    "quality.label.checkedFiles": "Checked files",
+    "quality.label.riskCount": "Risks",
+    "quality.label.riskyFiles": "Risky files",
+    "quality.label.issues": "Issues",
+    "quality.clean": "No quality-gaming risks found.",
+    "quality.error.missingAction": "Specify a quality action: check",
+    "quality.error.unknownAction": "Unknown quality action: {action}",
     "run.help.summary": "Run a configured oneshot command from .mustflow/config/commands.toml.",
     "run.help.option.dryRun": "Print a non-executing command plan",
     "run.help.option.planOnly": "Alias for --dry-run",

package/dist/cli/i18n/es.js

@@ -39,6 +39,7 @@ export const esMessages = {
     "command.upgrade.summary": "Comprueba la versión del paquete y actualiza con seguridad los archivos de flujo instalados",
     "command.map.summary": "Genera REPO_MAP.md",
     "command.lineEndings.summary": "Inspecciona y normaliza la política de finales de línea",
+    "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.run.summary": "Ejecuta un comando configurado de una sola ejecución",
     "command.context.summary": "Imprime contexto de agente legible por máquinas",
     "command.tech.summary": "Gestiona preferencias tecnológicas para agentes",
@@ -731,6 +732,19 @@ Lee estos archivos antes de trabajar:
     "lineEndings.error.unknownAction": "Unknown line-endings action: {action}",
     "lineEndings.error.checkModeOption": "check does not accept --apply or --dry-run",
     "lineEndings.error.conflictingModes": "Cannot combine --apply and --dry-run",
+    "quality.help.summary": "Inspect changed files for quality-gaming patterns such as line stuffing, validation suppressions, " +
+        "test bypass markers, type escapes, and placeholder implementations.",
+    "quality.help.option.all": "Inspect every tracked text file instead of only changed files",
+    "quality.help.exit.ok": "Quality-gaming risks were inspected and no risk was found",
+    "quality.help.exit.fail": "Quality-gaming risks, repository issues, or invalid input were found",
+    "quality.title": "mustflow quality check",
+    "quality.label.checkedFiles": "Checked files",
+    "quality.label.riskCount": "Risks",
+    "quality.label.riskyFiles": "Risky files",
+    "quality.label.issues": "Issues",
+    "quality.clean": "No quality-gaming risks found.",
+    "quality.error.missingAction": "Specify a quality action: check",
+    "quality.error.unknownAction": "Unknown quality action: {action}",
     "run.help.summary": "Ejecuta un comando configurado de una sola ejecución desde .mustflow/config/commands.toml.",
     "run.help.option.dryRun": "Imprime un plan de comando sin ejecutarlo",
     "run.help.option.planOnly": "Alias de --dry-run",

package/dist/cli/i18n/fr.js

@@ -39,6 +39,7 @@ export const frMessages = {
     "command.upgrade.summary": "Vérifie la version du paquet et met à jour en sécurité les fichiers de workflow installés",
     "command.map.summary": "Génère REPO_MAP.md",
     "command.lineEndings.summary": "Inspecte et normalise la politique de fins de ligne",
+    "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.run.summary": "Exécute une commande configurée à exécution unique",
     "command.context.summary": "Imprime le contexte d'agent lisible par machine",
     "command.tech.summary": "Gère les préférences technologiques pour les agents",
@@ -731,6 +732,19 @@ Lisez ces fichiers avant de travailler :
     "lineEndings.error.unknownAction": "Unknown line-endings action: {action}",
     "lineEndings.error.checkModeOption": "check does not accept --apply or --dry-run",
     "lineEndings.error.conflictingModes": "Cannot combine --apply and --dry-run",
+    "quality.help.summary": "Inspect changed files for quality-gaming patterns such as line stuffing, validation suppressions, " +
+        "test bypass markers, type escapes, and placeholder implementations.",
+    "quality.help.option.all": "Inspect every tracked text file instead of only changed files",
+    "quality.help.exit.ok": "Quality-gaming risks were inspected and no risk was found",
+    "quality.help.exit.fail": "Quality-gaming risks, repository issues, or invalid input were found",
+    "quality.title": "mustflow quality check",
+    "quality.label.checkedFiles": "Checked files",
+    "quality.label.riskCount": "Risks",
+    "quality.label.riskyFiles": "Risky files",
+    "quality.label.issues": "Issues",
+    "quality.clean": "No quality-gaming risks found.",
+    "quality.error.missingAction": "Specify a quality action: check",
+    "quality.error.unknownAction": "Unknown quality action: {action}",
     "run.help.summary": "Exécute une commande configurée à exécution unique depuis .mustflow/config/commands.toml.",
     "run.help.option.dryRun": "Imprime un plan de commande sans l'exécuter",
     "run.help.option.planOnly": "Alias de --dry-run",

package/dist/cli/i18n/hi.js

@@ -39,6 +39,7 @@ export const hiMessages = {
     "command.upgrade.summary": "Package version जाँचें और installed workflow files सुरक्षित रूप से update करें",
     "command.map.summary": "REPO_MAP.md बनाएँ",
     "command.lineEndings.summary": "लाइन-एंडिंग नीति की जाँच और सामान्यीकरण करें",
+    "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.run.summary": "कॉन्फ़िगर की गई एक-बार चलने वाली कमांड चलाएँ",
     "command.context.summary": "मशीन-पठनीय एजेंट संदर्भ प्रिंट करें",
     "command.tech.summary": "एजेंटों के लिए technology preferences प्रबंधित करें",
@@ -731,6 +732,19 @@ export const hiMessages = {
     "lineEndings.error.unknownAction": "Unknown line-endings action: {action}",
     "lineEndings.error.checkModeOption": "check does not accept --apply or --dry-run",
     "lineEndings.error.conflictingModes": "Cannot combine --apply and --dry-run",
+    "quality.help.summary": "Inspect changed files for quality-gaming patterns such as line stuffing, validation suppressions, " +
+        "test bypass markers, type escapes, and placeholder implementations.",
+    "quality.help.option.all": "Inspect every tracked text file instead of only changed files",
+    "quality.help.exit.ok": "Quality-gaming risks were inspected and no risk was found",
+    "quality.help.exit.fail": "Quality-gaming risks, repository issues, or invalid input were found",
+    "quality.title": "mustflow quality check",
+    "quality.label.checkedFiles": "Checked files",
+    "quality.label.riskCount": "Risks",
+    "quality.label.riskyFiles": "Risky files",
+    "quality.label.issues": "Issues",
+    "quality.clean": "No quality-gaming risks found.",
+    "quality.error.missingAction": "Specify a quality action: check",
+    "quality.error.unknownAction": "Unknown quality action: {action}",
     "run.help.summary": ".mustflow/config/commands.toml से कॉन्फ़िगर की गई एक-बार चलने वाली कमांड चलाएँ।",
     "run.help.option.dryRun": "कमांड चलाए बिना उसका plan प्रिंट करें",
     "run.help.option.planOnly": "--dry-run का alias",

package/dist/cli/i18n/ko.js

@@ -39,6 +39,7 @@ export const koMessages = {
     "command.upgrade.summary": "패키지 버전을 확인하고 설치된 워크플로우 파일을 안전하게 갱신합니다",
     "command.map.summary": "REPO_MAP.md를 작성합니다",
     "command.lineEndings.summary": "줄바꿈 정책을 검사하고 정규화합니다",
+    "command.quality.summary": "변경 파일의 품질 지표 꼼수를 검사합니다",
     "command.run.summary": "설정된 일회성 명령을 실행합니다",
     "command.context.summary": "에이전트 작업 맥락을 출력합니다",
     "command.tech.summary": "에이전트용 기술 선호를 관리합니다",
@@ -731,6 +732,19 @@ export const koMessages = {
     "lineEndings.error.unknownAction": "알 수 없는 line-endings 작업: {action}",
     "lineEndings.error.checkModeOption": "check에는 --apply 또는 --dry-run을 사용할 수 없습니다",
     "lineEndings.error.conflictingModes": "--apply와 --dry-run은 함께 사용할 수 없습니다",
+    "quality.help.summary": "긴 줄 몰아넣기, 검증 억제, 테스트 우회 표시, 타입 회피, 미완성 구현 같은 " +
+        "품질 지표 꼼수를 변경 파일에서 검사합니다.",
+    "quality.help.option.all": "변경 파일만이 아니라 추적 중인 모든 텍스트 파일을 검사합니다",
+    "quality.help.exit.ok": "품질 지표 꼼수를 검사했고 위험이 발견되지 않았습니다",
+    "quality.help.exit.fail": "품질 지표 꼼수, 저장소 문제, 또는 잘못된 입력이 발견되었습니다",
+    "quality.title": "mustflow quality check",
+    "quality.label.checkedFiles": "검사한 파일",
+    "quality.label.riskCount": "위험",
+    "quality.label.riskyFiles": "위험 파일",
+    "quality.label.issues": "문제",
+    "quality.clean": "품질 지표 꼼수가 발견되지 않았습니다.",
+    "quality.error.missingAction": "quality 작업을 지정하세요: check",
+    "quality.error.unknownAction": "알 수 없는 quality 작업: {action}",
     "run.help.summary": ".mustflow/config/commands.toml에 설정된 일회성 명령을 실행합니다.",
     "run.help.option.dryRun": "실행하지 않고 명령 계획을 출력합니다",
     "run.help.option.planOnly": "--dry-run과 같은 동작입니다",

package/dist/cli/i18n/zh.js

@@ -39,6 +39,7 @@ export const zhMessages = {
     "command.upgrade.summary": "检查包版本并安全更新已安装的工作流文件",
     "command.map.summary": "生成 REPO_MAP.md",
     "command.lineEndings.summary": "检查并规范化换行符策略",
+    "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.run.summary": "运行已配置的一次性命令",
     "command.context.summary": "输出机器可读的代理上下文",
     "command.tech.summary": "管理代理使用的技术偏好",
@@ -731,6 +732,19 @@ export const zhMessages = {
     "lineEndings.error.unknownAction": "Unknown line-endings action: {action}",
     "lineEndings.error.checkModeOption": "check does not accept --apply or --dry-run",
     "lineEndings.error.conflictingModes": "Cannot combine --apply and --dry-run",
+    "quality.help.summary": "Inspect changed files for quality-gaming patterns such as line stuffing, validation suppressions, " +
+        "test bypass markers, type escapes, and placeholder implementations.",
+    "quality.help.option.all": "Inspect every tracked text file instead of only changed files",
+    "quality.help.exit.ok": "Quality-gaming risks were inspected and no risk was found",
+    "quality.help.exit.fail": "Quality-gaming risks, repository issues, or invalid input were found",
+    "quality.title": "mustflow quality check",
+    "quality.label.checkedFiles": "Checked files",
+    "quality.label.riskCount": "Risks",
+    "quality.label.riskyFiles": "Risky files",
+    "quality.label.issues": "Issues",
+    "quality.clean": "No quality-gaming risks found.",
+    "quality.error.missingAction": "Specify a quality action: check",
+    "quality.error.unknownAction": "Unknown quality action: {action}",
     "run.help.summary": "从 .mustflow/config/commands.toml 运行已配置的一次性命令。",
     "run.help.option.dryRun": "输出命令计划但不执行",
     "run.help.option.planOnly": "--dry-run 的别名",

package/dist/cli/index.js

@@ -53,6 +53,7 @@ function getTopLevelHelp(lang) {
             'mf verify --changed --plan-only --json',
             'mf verify --reason code_change',
             'mf line-endings check',
+            'mf quality check',
             'mf version --check',
             'mf version-sources --json',
         ],

package/dist/cli/lib/command-registry.js

@@ -89,6 +89,12 @@ export const COMMAND_DEFINITIONS = [
         summaryKey: 'command.lineEndings.summary',
         loadRunner: async () => (await import('../commands/line-endings.js')).runLineEndings,
     },
+    {
+        id: 'quality',
+        usage: 'mf quality',
+        summaryKey: 'command.quality.summary',
+        loadRunner: async () => (await import('../commands/quality.js')).runQuality,
+    },
     {
         id: 'run',
         usage: 'mf run',

package/dist/cli/lib/npm-version-check.js

@@ -150,6 +150,42 @@ function buildLatestPackageUrl(registryUrl, packageName) {
         : encodeURIComponent(packageName);
     return `${trimmedRegistryUrl}/${encodedPackageName}/latest`;
 }
+function buildPackageMetadataUrl(registryUrl, packageName) {
+    const trimmedRegistryUrl = registryUrl.replace(/\/+$/u, '');
+    const encodedPackageName = packageName.startsWith('@')
+        ? `@${encodeURIComponent(packageName.slice(1))}`
+        : encodeURIComponent(packageName);
+    return `${trimmedRegistryUrl}/${encodedPackageName}`;
+}
+export async function checkNpmPackageExists(packageName) {
+    const registryUrl = getRegistryUrl();
+    const response = await fetch(buildPackageMetadataUrl(registryUrl, packageName), {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(getTimeoutMs()),
+    });
+    if (response.status === 404) {
+        return {
+            packageName,
+            registryUrl,
+            exists: false,
+            resolvedName: null,
+        };
+    }
+    if (!response.ok) {
+        throw new Error(`npm registry returned HTTP ${response.status}`);
+    }
+    const body = await response.json();
+    const resolvedName = isRecord(body) && typeof body.name === 'string' ? body.name : null;
+    if (!resolvedName) {
+        throw new Error('npm registry response did not include a package name');
+    }
+    return {
+        packageName,
+        registryUrl,
+        exists: true,
+        resolvedName,
+    };
+}
 export async function checkNpmLatestVersion(metadata) {
     const registryUrl = getRegistryUrl();
     const response = await fetch(buildLatestPackageUrl(registryUrl, metadata.name), {

package/dist/core/public-json-contracts.js

@@ -198,6 +198,15 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         installedCommand: ['mf', 'line-endings', 'check', '--json'],
         expectedExitCodes: [0, 1],
     },
+    {
+        id: 'quality-gaming-report',
+        schemaFile: 'quality-gaming-report.schema.json',
+        producer: 'mf quality check --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'quality', 'check', '--json'],
+        expectedExitCodes: [0, 1],
+    },
     {
         id: 'latest-run-pointer',
         schemaFile: 'latest-run-pointer.schema.json',

package/dist/core/quality-gaming.js

@@ -0,0 +1,300 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { createCommandEnv } from './command-env.js';
+import { readFileInsideWithoutSymlinks } from './safe-filesystem.js';
+const LONG_LINE_THRESHOLD = 160;
+const MULTI_STATEMENT_SEMICOLON_THRESHOLD = 1;
+const LARGE_HELPER_LINE_THRESHOLD = 120;
+const TEXT_FILE_PATTERN = /\.(?:cjs|cts|css|go|h|hpp|html|java|js|jsx|json|kt|md|mjs|mts|php|ps1|py|rb|rs|scss|sh|sql|svelte|swift|toml|ts|tsx|txt|vue|xml|yaml|yml)$/iu;
+const CODE_FILE_PATTERN = /\.(?:cjs|cts|go|java|js|jsx|kt|mjs|mts|php|ps1|py|rb|rs|svelte|swift|ts|tsx|vue)$/iu;
+const GENERATED_OR_VENDOR_PATTERN = /(?:^|\/)(?:generated|vendor|third_party)(?:\/|$)/iu;
+const HELPER_CONTAINER_PATTERN = /(?:^|\/)[^/]*(?:helper|helpers|util|utils|manager|common|misc)[^/]*\.(?:cjs|cts|go|java|js|jsx|kt|mjs|mts|php|ps1|py|rb|rs|svelte|swift|ts|tsx|vue)$/iu;
+const SUPPRESSION_PATTERN = /(?:eslint-disable|ts-ignore|ts-expect-error|biome-ignore|rome-ignore|noqa|type:\s*ignore|pragma:\s*no cover|istanbul\s+ignore|c8\s+ignore)/iu;
+const TYPE_ESCAPE_PATTERN = /\b(?:as\s+any|as\s+unknown\s+as|as\s+never|:\s*any\b|!\.|!\)|!\]|!\s*[,;]|\bObject\s+as\s+unknown)\b/u;
+const TEST_BYPASS_PATTERN = /(?:\.skip\b|\.only\b|@Disabled\b|@Ignore\b|\bxfail\b|pytest\.mark\.skip|it\.todo\b|test\.todo\b)/u;
+const PLACEHOLDER_PATTERN = /(?:TODO|FIXME|HACK|not\s+implemented|unimplemented|throw\s+new\s+Error\(["'`](?:not implemented|todo|unsupported)|\bpass\s*$)/iu;
+const THROW_PLACEHOLDER_MESSAGE_PATTERN = /(?:not\s+implemented|unimplemented|todo|unsupported)/iu;
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+function normalizeGitPath(value) {
+    return value.replace(/\\/gu, '/');
+}
+function gitList(projectRoot, args) {
+    const result = spawnSync('git', [...args, '-z'], {
+        cwd: projectRoot,
+        encoding: 'buffer',
+        env: createCommandEnv(projectRoot, { policy: 'minimal', allowlist: [] }),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 30_000,
+        windowsHide: true,
+    });
+    if (result.status !== 0) {
+        return null;
+    }
+    return result.stdout
+        .toString('utf8')
+        .split('\0')
+        .map((entry) => normalizeGitPath(entry.trim()))
+        .filter((entry) => entry.length > 0)
+        .sort((left, right) => left.localeCompare(right));
+}
+function gitText(projectRoot, args) {
+    const result = spawnSync('git', args, {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        env: createCommandEnv(projectRoot, { policy: 'minimal', allowlist: [] }),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 30_000,
+        windowsHide: true,
+    });
+    return result.status === 0 ? result.stdout : null;
+}
+function listGitTrackedFiles(projectRoot) {
+    return gitList(projectRoot, ['ls-files']);
+}
+function listGitChangedFiles(projectRoot) {
+    const changedLists = [
+        gitList(projectRoot, ['diff', '--name-only', '--diff-filter=ACMR']),
+        gitList(projectRoot, ['diff', '--cached', '--name-only', '--diff-filter=ACMR']),
+        gitList(projectRoot, ['ls-files', '--others', '--exclude-standard']),
+    ];
+    if (changedLists.some((list) => list === null)) {
+        return null;
+    }
+    return [...new Set(changedLists.flatMap((list) => list ?? []))].sort((left, right) => left.localeCompare(right));
+}
+function isTextCandidate(relativePath) {
+    return TEXT_FILE_PATTERN.test(relativePath) && !relativePath.startsWith('.mustflow/state/');
+}
+function isCodeCandidate(relativePath) {
+    return CODE_FILE_PATTERN.test(relativePath);
+}
+function isMeaningfulCodeLine(text) {
+    const trimmed = text.trim();
+    return trimmed.length > 0 && !trimmed.startsWith('//') && !trimmed.startsWith('#') && !trimmed.startsWith('*');
+}
+function stripQuotedText(text) {
+    let stripped = '';
+    let quote = null;
+    let escaped = false;
+    for (const char of text) {
+        if (quote) {
+            stripped += ' ';
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (char === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'" || char === '`') {
+            quote = char;
+            stripped += ' ';
+            continue;
+        }
+        stripped += char;
+    }
+    return stripped;
+}
+function stripRegexLiterals(text) {
+    const patternDeclaration = /^(\s*(?:const\s+[A-Z0-9_]+\s*=\s*)?)\/.*\/[a-z]*;?\s*$/u;
+    if (patternDeclaration.test(text)) {
+        return text.replace(/\/.*\/[a-z]*;?/u, 'REGEX;');
+    }
+    return text.replace(/([=(:,\[]\s*)\/.*\/[a-z]*/giu, '$1 REGEX');
+}
+function codeSurfaceForLine(text) {
+    const literalStripped = stripQuotedText(stripRegexLiterals(text));
+    return literalStripped.split('//', 1)[0] ?? literalStripped;
+}
+function isCommentOnlyLine(text) {
+    const trimmed = text.trim();
+    return trimmed.startsWith('//') || trimmed.startsWith('#') || trimmed.startsWith('*');
+}
+function countSemicolonsOutsideComment(text) {
+    return [...codeSurfaceForLine(text)].filter((char) => char === ';').length;
+}
+function readTextLines(projectRoot, relativePath, issues) {
+    const absolutePath = path.join(projectRoot, ...relativePath.split('/'));
+    if (!existsSync(absolutePath)) {
+        return [];
+    }
+    try {
+        const buffer = readFileInsideWithoutSymlinks(projectRoot, absolutePath);
+        if (buffer.includes(0)) {
+            return [];
+        }
+        return buffer
+            .toString('utf8')
+            .split(/\r?\n/u)
+            .map((text, index) => ({ line: index + 1, text }));
+    }
+    catch (error) {
+        issues.push(error instanceof Error ? error.message : String(error));
+        return [];
+    }
+}
+function isGitTracked(projectRoot, relativePath) {
+    const result = spawnSync('git', ['ls-files', '--error-unmatch', '--', relativePath], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        env: createCommandEnv(projectRoot, { policy: 'minimal', allowlist: [] }),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 30_000,
+        windowsHide: true,
+    });
+    return result.status === 0;
+}
+function parseAddedLinesFromDiff(diffText) {
+    const addedLines = [];
+    let nextLine = 0;
+    for (const rawLine of diffText.split(/\r?\n/u)) {
+        const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/u.exec(rawLine);
+        if (hunk) {
+            nextLine = Number.parseInt(hunk[1], 10);
+            continue;
+        }
+        if (nextLine === 0) {
+            continue;
+        }
+        if (rawLine.startsWith('+++')) {
+            continue;
+        }
+        if (rawLine.startsWith('+')) {
+            addedLines.push({ line: nextLine, text: rawLine.slice(1) });
+            nextLine += 1;
+            continue;
+        }
+        if (rawLine.startsWith('-')) {
+            continue;
+        }
+        nextLine += 1;
+    }
+    return addedLines;
+}
+function readChangedLineCandidates(projectRoot, relativePath, issues) {
+    if (!isGitTracked(projectRoot, relativePath)) {
+        return readTextLines(projectRoot, relativePath, issues);
+    }
+    const diffText = gitText(projectRoot, ['diff', 'HEAD', '--no-ext-diff', '--unified=0', '--', relativePath]);
+    if (diffText === null) {
+        return readTextLines(projectRoot, relativePath, issues);
+    }
+    return parseAddedLinesFromDiff(diffText);
+}
+function addRisk(risks, code, severity, relativePath, line, detail, metric) {
+    risks.push({
+        code,
+        severity,
+        path: toPosixPath(relativePath),
+        line,
+        detail,
+        metric,
+    });
+}
+function inspectLine(relativePath, candidate, risks) {
+    const text = candidate.text;
+    const trimmed = text.trim();
+    const isCode = isCodeCandidate(relativePath);
+    const codeSurface = codeSurfaceForLine(text);
+    const markerSurface = isCommentOnlyLine(text) ? trimmed : codeSurface;
+    if (isCode && codeSurface.length > LONG_LINE_THRESHOLD) {
+        addRisk(risks, 'line_stuffing_added', 'high', relativePath, candidate.line, 'Added line exceeds the anti-stuffing length threshold.', {
+            name: 'line_length',
+            value: codeSurface.length,
+            threshold: LONG_LINE_THRESHOLD,
+        });
+    }
+    if (isCode &&
+        isMeaningfulCodeLine(text) &&
+        countSemicolonsOutsideComment(text) > MULTI_STATEMENT_SEMICOLON_THRESHOLD) {
+        addRisk(risks, 'multiple_statements_per_line_added', 'high', relativePath, candidate.line, 'Added code line appears to contain multiple statements.', {
+            name: 'semicolons',
+            value: countSemicolonsOutsideComment(text),
+            threshold: MULTI_STATEMENT_SEMICOLON_THRESHOLD,
+        });
+    }
+    if (isCode && SUPPRESSION_PATTERN.test(markerSurface)) {
+        addRisk(risks, 'suppression_added', 'critical', relativePath, candidate.line, 'Added line contains a validation suppression marker.', null);
+    }
+    if (isCode && TYPE_ESCAPE_PATTERN.test(codeSurface)) {
+        addRisk(risks, 'type_escape_added', 'high', relativePath, candidate.line, 'Added line contains a broad type escape or non-null assertion pattern.', null);
+    }
+    if (isCode && TEST_BYPASS_PATTERN.test(codeSurface)) {
+        addRisk(risks, 'test_bypass_marker_added', 'critical', relativePath, candidate.line, 'Added line contains a test bypass marker.', null);
+    }
+    if (isCode &&
+        (PLACEHOLDER_PATTERN.test(markerSurface) ||
+            (/\bthrow\s+new\s+Error\s*\(/u.test(codeSurface) && THROW_PLACEHOLDER_MESSAGE_PATTERN.test(text)))) {
+        addRisk(risks, 'placeholder_added', 'medium', relativePath, candidate.line, 'Added line looks like a placeholder or unfinished implementation.', null);
+    }
+    if (GENERATED_OR_VENDOR_PATTERN.test(relativePath) && isCode && isMeaningfulCodeLine(text)) {
+        addRisk(risks, 'generated_or_vendor_logic_added', 'high', relativePath, candidate.line, 'Added executable-looking logic under generated, vendor, or third_party paths.', null);
+    }
+}
+function inspectFile(projectRoot, relativePath, scope, issues) {
+    const candidates = scope === 'tracked'
+        ? readTextLines(projectRoot, relativePath, issues)
+        : readChangedLineCandidates(projectRoot, relativePath, issues);
+    const risks = [];
+    for (const candidate of candidates) {
+        inspectLine(relativePath, candidate, risks);
+    }
+    if (scope === 'tracked' && HELPER_CONTAINER_PATTERN.test(relativePath) && candidates.length > LARGE_HELPER_LINE_THRESHOLD) {
+        addRisk(risks, 'large_helper_container_added', 'medium', relativePath, null, 'Helper, util, manager, common, or misc container exceeds the size threshold.', {
+            name: 'file_lines',
+            value: candidates.length,
+            threshold: LARGE_HELPER_LINE_THRESHOLD,
+        });
+    }
+    if (risks.length === 0) {
+        return null;
+    }
+    return {
+        path: toPosixPath(relativePath),
+        checked_lines: candidates.length,
+        risk_count: risks.length,
+        risks,
+    };
+}
+export function inspectQualityGaming(projectRoot, options = {}) {
+    const root = path.resolve(projectRoot);
+    const scope = options.scope ?? 'changed';
+    const candidateFiles = scope === 'tracked' ? listGitTrackedFiles(root) : listGitChangedFiles(root);
+    const issues = [];
+    const riskyFiles = [];
+    if (!candidateFiles) {
+        issues.push('Git files could not be listed. Run this command inside a Git working tree.');
+    }
+    for (const relativePath of candidateFiles ?? []) {
+        if (!isTextCandidate(relativePath)) {
+            continue;
+        }
+        const fileReport = inspectFile(root, relativePath, scope, issues);
+        if (fileReport) {
+            riskyFiles.push(fileReport);
+        }
+    }
+    const riskCount = riskyFiles.reduce((sum, file) => sum + file.risk_count, 0);
+    return {
+        schema_version: '1',
+        command: 'quality',
+        mode: 'check',
+        scope,
+        ok: issues.length === 0 && riskCount === 0,
+        mustflow_root: root,
+        git_tracked: candidateFiles !== null,
+        checked_files: candidateFiles?.filter(isTextCandidate).length ?? 0,
+        risk_count: riskCount,
+        risky_files: riskyFiles,
+        issues,
+    };
+}

package/package.json

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

package/schemas/README.md

@@ -49,6 +49,9 @@ Current schemas:
   `mf impact <path...> --json`
 - `line-endings-report.schema.json`: output of `mf line-endings check --json` and  
   `mf line-endings normalize --json`
+- `quality-gaming-report.schema.json`: output of `mf quality check --json`, containing changed-file
+  quality-gaming risks such as line stuffing, validation suppressions, test bypass markers, type
+  escapes, generated/vendor logic, and placeholder implementations
 - `latest-run-pointer.schema.json`: `.mustflow/state/runs/latest.json` when `mf verify` writes a
   pointer to the latest verify run bundle, including the verify completion verdict, evidence model,
   and coverage matrix

package/schemas/quality-gaming-report.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/quality-gaming-report.schema.json",
+  "title": "mustflow quality-gaming report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mode",
+    "scope",
+    "ok",
+    "mustflow_root",
+    "git_tracked",
+    "checked_files",
+    "risk_count",
+    "risky_files",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "quality" },
+    "mode": { "const": "check" },
+    "scope": { "enum": ["changed", "tracked"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "git_tracked": { "type": "boolean" },
+    "checked_files": { "type": "integer", "minimum": 0 },
+    "risk_count": { "type": "integer", "minimum": 0 },
+    "risky_files": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/riskyFile" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "metric": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "value", "threshold"],
+      "properties": {
+        "name": { "type": "string" },
+        "value": { "type": "number" },
+        "threshold": { "type": "number" }
+      }
+    },
+    "risk": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "path", "line", "detail", "metric"],
+      "properties": {
+        "code": {
+          "enum": [
+            "line_stuffing_added",
+            "multiple_statements_per_line_added",
+            "suppression_added",
+            "type_escape_added",
+            "test_bypass_marker_added",
+            "placeholder_added",
+            "generated_or_vendor_logic_added",
+            "large_helper_container_added"
+          ]
+        },
+        "severity": { "enum": ["medium", "high", "critical"] },
+        "path": { "type": "string" },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "detail": { "type": "string" },
+        "metric": {
+          "anyOf": [
+            { "$ref": "#/$defs/metric" },
+            { "type": "null" }
+          ]
+        }
+      }
+    },
+    "riskyFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "checked_lines", "risk_count", "risks"],
+      "properties": {
+        "path": { "type": "string" },
+        "checked_lines": { "type": "integer", "minimum": 0 },
+        "risk_count": { "type": "integer", "minimum": 1 },
+        "risks": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/risk" },
+          "minItems": 1
+        }
+      }
+    }
+  }
+}

package/templates/default/common/.mustflow/config/commands.toml

@@ -127,6 +127,22 @@ network = false
 destructive = false
 required_after = ["line_ending_warning", "formatting_change"]
 
+[intents.quality_gaming_check]
+status = "configured"
+kind = "mustflow_builtin"
+lifecycle = "oneshot"
+run_policy = "agent_allowed"
+description = "Inspect changed files for AI quality-gaming patterns."
+argv = ["mf", "quality", "check", "--json"]
+cwd = "."
+timeout_seconds = 120
+stdin = "closed"
+success_exit_codes = [0]
+writes = []
+network = false
+destructive = false
+required_after = ["code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "unknown_change"]
+
 [intents.line_endings_normalize]
 status = "manual_only"
 description = "Normalize tracked text files to the repository line-ending policy."

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 167
+revision = 168
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -119,6 +119,12 @@ source_locale = "en"
 revision = 2
 translations = {}
 
+[documents."skill.quality-gaming-guard"]
+source = "locales/en/.mustflow/skills/quality-gaming-guard/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.module-boundary-review"]
 source = "locales/en/.mustflow/skills/module-boundary-review/SKILL.md"
 source_locale = "en"

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

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 167
+revision: 168
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -371,6 +371,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 |
 | Large-scope code, docs, tests, content, log, data, or refactor work needs cheap-signal candidate selection before reading or editing many files | `.mustflow/skills/heuristic-candidate-selection/SKILL.md` | User goal, target scope, file-role boundaries, cheap signals, exclusions, scoring factors, batch limit, and verification contract | Candidate discovery, scoring, read plan, bounded batch edits, and directly synchronized surfaces | token waste, false positives, generated-file noise, unimportant cleanup, hallucinated source content, oversized diff, or missed high-impact file | `changes_status`, `changes_diff_summary`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Selection goal, excluded surfaces, cheap signals, scored candidates, selected batch, skipped/deferred files, verification, and remaining selection risk |
 | Assistant-authored, AI-generated, vibe-coded, copied, or broad code changes need a hardening pass for symptom-only fixes, pinpoint hardcoding, exact-value branches, same-defect-class sibling inputs or callers, duplicate helpers, duplicate types or shapes, hidden coupling, circular dependencies, re-export discipline, swallowed errors, excessive nesting, god functions or files, edge cases, and behavior-focused tests | `.mustflow/skills/ai-generated-code-hardening/SKILL.md` | User goal, current diff or target files, reported symptom or failing fixture, existing helpers/types/shapes, sibling inputs or callers, import and export paths, public entrypoints or barrels, error-handling conventions, edge/failure cases, tests, and configured command intents | Small hardening fixes, defect-class rule repair, deduplication into existing single source of truth, boundary notes, focused tests, and directly synchronized docs or contracts | symptom-only patch, pinpoint hardcode, exact literal fixture fix, uninspected sibling input, duplicate abstraction, hidden coupling, circular dependency, accidental public API, string-only tests, over-mocking, fallback sprawl, silent error handling, fan-in/fan-out concentration, or broad rewrite | `changes_status`, `changes_diff_summary`, `test_related`, `test_audit`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Sources of truth reused or extended, symptom patch and same-class sibling findings, duplicate/coupling/export/error/complexity/test findings, fixes made, deferred enforcement, verification, and remaining hardening risk |
+| Quality metrics, line-count limits, complexity budgets, lint/type/test gates, or assistant-authored changes may be gamed through long-line stuffing, multiple statements per line, new suppressions, test bypass markers, type escapes, placeholder implementations, generated/vendor logic, giant config blobs, dispatch maps, or helper/util/manager/common containers | `.mustflow/skills/quality-gaming-guard/SKILL.md` | User goal, intended quality outcome behind the metric, current diff, quality gates, formatter/lint/type/test rules, generated/vendor policy, helper naming conventions, suppression baseline, and command contract entries | Real responsibility split, removal of gaming patterns, focused tests or quality-gate evidence, bounded `quality_gaming_check` command contract, and directly synchronized docs or templates | cosmetic metric compliance, line stuffing, validation suppression, test bypass, broad type escape, placeholder success, generated/vendor hiding, junk-drawer helper extraction, or legacy baseline confused with new regression | `quality_gaming_check`, `changes_status`, `changes_diff_summary`, `test_related`, `lint`, `build`, `mustflow_check` | Quality goal, gaming patterns inspected, patterns removed or intentionally left, baseline versus new-regression decision, verification, and remaining quality-gaming risk |
 | Prompts, prompt builders, system or developer messages, RAG prompt assembly, few-shot examples, structured outputs, tool-use instructions, model selection, reasoning-effort settings, eval sets, refusal or fallback handling, prompt versioning, or AI feature completion criteria are created, changed, reviewed, or reported | `.mustflow/skills/prompt-contract-quality-review/SKILL.md` | Prompt contract ledger, input ledger, authority ledger, output schema, tool policy, model/runtime ledger, RAG evidence ledger, eval ledger, changed files, and command contract entries | Prompt builders, prompt templates, schemas, validators, eval fixtures, boundary examples, tool policies, fallback states, completion definitions, docs, tests, and directly synchronized templates | prompt-as-function gap, user input treated as authority, buried RAG evidence, happy-path-only examples, JSON-parse theater, unpinned production model, hidden prompt storage, raw chain-of-thought request, guessed tool parameters, missing failure state, unbounded reasoning/token cost, or vibe-based prompt improvement claim | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Prompt contract reviewed, function boundary, authority and source separation, eval and semantic validation status, model/runtime policy, RAG/tool/failure/completion states, verification, and remaining prompt-contract risk |
 | LLM answers, RAG responses, citations, source grounding, claim extraction, evidence IDs, answerability states, abstain behavior, retrieval thresholds, tool-backed facts, output validators, LLM judges, or hallucination-control metrics are created, changed, reviewed, or reported | `.mustflow/skills/llm-hallucination-control-review/SKILL.md` | Answer contract ledger, evidence ledger, claim ledger, tool ledger, validator ledger, eval ledger, observability ledger, changed files, and command contract entries | Answerability states, abstain states, missing-information states, source-coverage gates, claim maps, evidence-ID requirements, citation validators, retrieval thresholds, chunk metadata, tool-parameter ownership, deterministic calculators, domain validators, eval fixtures, tests, docs, route metadata, and directly synchronized templates | unsupported factual claim, fabricated citation, source ID invention, weak retrieval gate, noisy semantic-only retrieval, chunk context loss, summary-on-summary hallucination, guessed tool parameter, model arithmetic, source-priority conflict, LLM judge overtrust, low-temperature theater, missing abstain path, missing dirty eval, false citation metric gap, or unobservable grounding drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Hallucination-control surface reviewed, answerability and abstain states, evidence IDs, claim map, citations, source coverage, validators, retrieval thresholds, tool ownership, evals, metrics, verification, and remaining hallucination-control risk |
 | LLM API calls, prompt assembly, chat history, RAG context, tool schemas, structured output schemas, model routing, reasoning settings, token budgets, provider prompt caching, app-level response caching, retries, batch or flex processing, predicted outputs, image or file inputs, or LLM cost metrics are created, changed, reviewed, or reported | `.mustflow/skills/llm-token-cost-control-review/SKILL.md` | Cost surface ledger, request ledger, cache ledger, context ledger, output ledger, routing ledger, observability ledger, changed files, and command contract entries | Request builders, prompt prefix ordering, canonical serialization, prompt hashes, cache keys, token counters, budget guards, model routers, context trimming, RAG packing, tool and schema payloads, output patch formats, retry repair paths, metrics, logs, tests, docs, route metadata, and directly synchronized templates | prompt-cache prefix drift, volatile field before stable prefix, unmeasured token count, full transcript replay, RAG chunk bloat, oversized tool or JSON schema payload, expensive model default, unbounded reasoning, no visible output after token cap, full-output regeneration, full-context retry replay, app cache key leak, predicted-output cost confusion, image or file token surprise, or per-call cost hiding cost-per-success regression | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | LLM token-cost surface reviewed, cost unit and measurement source, stable prefix and cache behavior, app cache/history/RAG/tool/schema/input choices, routing/reasoning/output/retry/Batch/Flex/prediction choices, observability, verification, and remaining token-cost risk |

package/templates/default/locales/en/.mustflow/skills/quality-gaming-guard/SKILL.md

@@ -0,0 +1,163 @@
+---
+mustflow_doc: skill.quality-gaming-guard
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: quality-gaming-guard
+description: Apply this skill when quality metrics, line-count limits, complexity budgets, lint/type/test gates, or agent-authored changes may be gamed instead of satisfying the intended engineering goal.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.quality-gaming-guard
+  command_intents:
+    - quality_gaming_check
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - lint
+    - build
+    - mustflow_check
+---
+
+# Quality Gaming Guard
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent agents from satisfying visible quality metrics through cheaper evasions such as line
+stuffing, validation suppressions, placeholder implementations, test bypass markers, broad type
+escapes, junk-drawer helpers, or generated/vendor logic hiding.
+
+This skill treats numeric limits as smoke alarms, not as the whole design objective. The target is
+the underlying engineering contract: responsibility separation, readable diffs, meaningful tests,
+preserved validation, and maintainable ownership.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A task mentions line counts, file size, method size, class size, complexity, lint warnings, type
+  errors, test coverage, benchmark thresholds, or quality gates.
+- Assistant-authored code could satisfy a visible metric while making maintainability worse.
+- A change adds or touches tests, validators, lint/type suppressions, generated files, vendor files,
+  helper/util/manager/common containers, configuration-as-logic, or placeholder behavior.
+- A repository has a configured `quality_gaming_check` intent or the command contract should expose
+  one.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is documentation-only and does not define or change a quality gate.
+- The task is a normal code review with no quality metric or agent-gaming risk; use the narrower
+  review or language skill.
+- The repository has no observable files, command contract, or diff evidence to inspect.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal and the intended quality outcome behind any numeric metric.
+- Current changed-file list and diff summary.
+- Relevant quality gates, formatter rules, lint/type/test command intents, and command-contract
+  entries.
+- Nearby source, tests, generated/vendor policy, helper naming conventions, and existing
+  suppression baseline.
+- Any failing command output or previous workaround evidence.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- The intended quality goal has been separated from the visible metric.
+- Higher-priority repository instructions and `.mustflow/config/commands.toml` have been checked.
+- Command execution remains governed by configured command intents only.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Refactor code toward real responsibility ownership instead of only reducing line counts.
+- Add or strengthen focused tests that prove the behavior or quality invariant being protected.
+- Remove newly introduced suppressions, broad type escapes, test bypass markers, placeholder
+  implementations, or metric-stuffing shapes when they are in scope.
+- Add or update the bounded `quality_gaming_check` command contract only when the repository can run
+  it as a one-shot, read-only intent.
+- Do not weaken tests, assertions, type checking, lint rules, benchmarks, schema validation, or
+  command gates to make a metric pass.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the real engineering goal behind the visible metric. Examples: separate domain ownership,
+   keep diffs reviewable, preserve validation strength, keep tests meaningful, or make a hot path
+   cheaper.
+2. Inspect the diff for gaming patterns:
+   - long-line stuffing after line-count limits;
+   - multiple statements on one line;
+   - new lint, type, coverage, or formatter suppressions;
+   - `.skip`, `.only`, disabled, xfail, or todo test markers;
+   - broad `any`, double assertions, or unsafe non-null assertions;
+   - placeholder returns, `not implemented`, `pass`, empty fallbacks, or broad catch swallowing;
+   - logic moved into generated/vendor files, giant config blobs, regex tables, dispatch maps, or
+     helper/util/manager/common containers.
+3. When a gaming pattern exists, fix the underlying design rather than only deleting the marker.
+   Split by domain responsibility, ownership, input/output boundary, policy owner, or dependency
+   direction.
+4. Prefer formatter, lint, type, test, and architecture evidence that checks multiple dimensions
+   together. Do not rely on one numeric gate as proof of design quality.
+5. For legacy code, distinguish existing baseline from new regression. Existing debt can be reported
+   while new debt should be removed or explicitly justified.
+6. If `quality_gaming_check` is configured, run it after the relevant implementation change. Treat a
+   nonzero result as a real quality-gaming finding unless the specific file is intentionally
+   excluded by current repository policy.
+7. Run the narrowest configured verification intents that cover the changed code, tests, command
+   contract, and public behavior.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The visible metric and the underlying engineering goal are both addressed.
+- No new validation suppression, test bypass, type escape, placeholder, long-line stuffing, or
+  generated/vendor hiding remains without an explicit risk note.
+- Any helper/util/manager/common extraction has a real domain responsibility or is reported as a
+  remaining design risk.
+- Quality-gaming check results and skipped verification are visible in the final report.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `quality_gaming_check`
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `lint`
+- `build`
+- `mustflow_check`
+
+Use broader configured tests only when the changed behavior or gate is cross-cutting and no narrower
+intent covers it.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If `quality_gaming_check` reports risks, inspect the file and either remove the gaming pattern or
+  report why the repository policy intentionally permits it.
+- If the check is missing, report that the repository has no configured quality-gaming guard instead
+  of inventing a command.
+- If a metric conflicts with the real engineering goal, report the conflict and prefer the stronger
+  maintainability contract over a cosmetic number.
+- If legacy baseline violations are too broad to fix safely, prevent new violations and report the
+  ratchet boundary.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Quality goal behind the metric
+- Gaming patterns inspected
+- Gaming patterns removed, prevented, or intentionally left
+- Baseline versus new-regression decision
+- Command intents run
+- Skipped checks and reasons
+- Remaining quality-gaming risk

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

@@ -156,6 +156,12 @@ route_type = "adjunct"
 priority = 74
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change"]
 
+[routes."quality-gaming-guard"]
+category = "general_code"
+route_type = "adjunct"
+priority = 76
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change"]
+
 [routes."module-boundary-review"]
 category = "general_code"
 route_type = "adjunct"

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.58.0"
+version = "2.59.0"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -23,6 +23,7 @@ creates = [
   ".mustflow/skills/behavior-preserving-refactor/SKILL.md",
   ".mustflow/skills/code-review/SKILL.md",
   ".mustflow/skills/ai-generated-code-hardening/SKILL.md",
+  ".mustflow/skills/quality-gaming-guard/SKILL.md",
   ".mustflow/skills/module-boundary-review/SKILL.md",
   ".mustflow/skills/change-blast-radius-review/SKILL.md",
   ".mustflow/skills/business-rule-leakage-review/SKILL.md",
@@ -211,6 +212,7 @@ minimal = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -339,6 +341,7 @@ patterns = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -478,6 +481,7 @@ oss = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -632,6 +636,7 @@ team = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -772,6 +777,7 @@ product = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -918,6 +924,7 @@ library = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",