mustflow 2.58.1 → 2.68.6

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',
@@ -137,6 +143,12 @@ export const COMMAND_DEFINITIONS = [
         summaryKey: 'command.search.summary',
         loadRunner: async () => (await import('../commands/search.js')).runSearch,
     },
+    {
+        id: 'skill',
+        usage: 'mf skill',
+        summaryKey: 'command.skill.summary',
+        loadRunner: async () => (await import('../commands/skill.js')).runSkill,
+    },
     {
         id: 'dashboard',
         usage: 'mf dashboard',

package/dist/cli/lib/local-index/constants.js

@@ -32,14 +32,13 @@ export const MUSTFLOW_RELATIVE_PATH = '.mustflow/config/mustflow.toml';
 export const INDEX_CONFIG_RELATIVE_PATH = '.mustflow/config/index.toml';
 export const DEFAULT_PROMPT_CACHE_STABLE_READ = [
     'AGENTS.md',
-    '.mustflow/docs/agent-workflow.md',
-    '.mustflow/config/mustflow.toml',
-    '.mustflow/config/commands.toml',
-    '.mustflow/skills/INDEX.md',
+    '.mustflow/skills/router.toml',
 ];
 export const DEFAULT_PROMPT_CACHE_TASK_SOURCES = [
     '.mustflow/context/INDEX.md',
-    'REPO_MAP.md',
+    'skill_route_candidates',
+    'route_metadata_fallback',
+    'repo_map_navigation',
     'matching_skill',
     'relevant_source_files',
 ];

package/dist/cli/lib/local-index/freshness.js

@@ -5,8 +5,9 @@ import { collectDocuments } from './workflow-documents.js';
 export function readStoredSchemaVersion(database) {
     return readMetadataValue(database, 'schema_version');
 }
-export function getStalePaths(projectRoot, database) {
+export function getStalePaths(projectRoot, database, options = {}) {
     const schemaVersion = readStoredSchemaVersion(database);
+    const includeState = options.includeState ?? true;
     if (schemaVersion !== LOCAL_INDEX_SCHEMA_VERSION) {
         return ['.mustflow/cache/mustflow.sqlite'];
     }
@@ -17,6 +18,9 @@ export function getStalePaths(projectRoot, database) {
         for (const row of indexedRows) {
             const indexedPath = toSearchString(row.path);
             const sourceScope = normalizeIndexedFileSourceScope(toSearchString(row.source_scope));
+            if (!includeState && sourceScope === 'state') {
+                continue;
+            }
             try {
                 const current = readIndexedFileRecord(projectRoot, indexedPath, sourceScope);
                 if (current.contentHash !== toSearchString(row.content_hash)) {

package/dist/cli/lib/local-index/index.js

@@ -383,7 +383,7 @@ export async function readLocalIndexPromptContext(projectRoot) {
         const SQL = await loadSqlJs();
         database = new SQL.Database(readFileSync(databasePath));
         const capabilities = readStoredSearchCapabilities(database);
-        const stalePaths = getStalePaths(projectRoot, database);
+        const stalePaths = getStalePaths(projectRoot, database, { includeState: false });
         if (stalePaths.length > 0) {
             return createLocalIndexPromptContextStatus(databasePath, 'stale', stalePaths, capabilities);
         }

package/dist/cli/lib/repo-map.js

@@ -28,6 +28,8 @@ const DEFAULT_PRIORITY_PATHS = [
     '.mustflow/config/commands.toml',
     '.mustflow/config/preferences.toml',
     '.mustflow/context/INDEX.md',
+    '.mustflow/skills/router.toml',
+    '.mustflow/skills/routes.toml',
     '.mustflow/skills/INDEX.md',
 ];
 const ROOT_OPTIONAL_MARKDOWN_ANCHOR_FILES = [
@@ -81,6 +83,8 @@ const DEFAULT_NESTED_ANCHOR_FILES = [
     '.mustflow/config/preferences.toml',
     '.mustflow/context/INDEX.md',
     '.mustflow/context/PROJECT.md',
+    '.mustflow/skills/router.toml',
+    '.mustflow/skills/routes.toml',
     '.mustflow/skills/INDEX.md',
     ...ROOT_OPTIONAL_MARKDOWN_ANCHOR_FILES,
     ...MACHINE_CONTRACT_ANCHOR_FILES,
@@ -191,7 +195,9 @@ const EXACT_ANCHOR_DESCRIPTIONS = new Map([
     ['.mustflow/context/INDEX.md', 'Task-specific project context router. Read only when context is needed.'],
     ['.mustflow/context/PROJECT.md', 'Project goals, non-goals, terms, and repository-wide promises for agents.'],
     ['.mustflow/docs/agent-workflow.md', 'Shared workflow policy for agent work.'],
-    ['.mustflow/skills/INDEX.md', 'Index of available procedural skills.'],
+    ['.mustflow/skills/router.toml', 'Stable compact skill-routing kernel for prompt-cache-friendly first-pass selection.'],
+    ['.mustflow/skills/routes.toml', 'Full skill-routing metadata for detailed procedure selection.'],
+    ['.mustflow/skills/INDEX.md', 'Expanded route table for detailed skill selection and route maintenance.'],
 ]);
 function spawnGitLsFiles(command, args, options) {
     const result = spawnSync(command, [...args], options);

package/dist/cli/lib/validation/constants.js

@@ -21,6 +21,8 @@ export const REQUIRED_FILES = [
     'AGENTS.md',
     '.mustflow/config/mustflow.toml',
     '.mustflow/config/commands.toml',
+    '.mustflow/skills/router.toml',
+    '.mustflow/skills/routes.toml',
     '.mustflow/skills/INDEX.md',
 ];
 export const ALLOWED_MAP_MODES = new Set(['anchors_only']);
@@ -181,6 +183,7 @@ export const SKILL_COMMAND_PERMISSION_CLAIM_PATTERNS = [
 export const ROUTER_INDEX_PROCEDURE_SECTION_PATTERN = /^##\s+(?:Use When|Do Not Use When|Required Inputs|Preconditions|Allowed Edits|Procedure|Postconditions|Verification|Failure Handling|Output Format|사용 조건|사용하지 않는 경우|필요한 입력|사전 조건|허용 수정 범위|절차|사후 조건|검증|실패 대응|출력 형식)\s*$/imu;
 export const ROUTER_INDEX_FILES = ['.mustflow/skills/INDEX.md', '.mustflow/context/INDEX.md'];
 export const SKILL_INDEX_PATH = '.mustflow/skills/INDEX.md';
+export const SKILL_ROUTER_PATH = '.mustflow/skills/router.toml';
 export const SKILL_ROUTES_METADATA_PATH = '.mustflow/skills/routes.toml';
 export const SUPPORTED_SKILL_SCHEMA_VERSION = '1';
 export const SKILL_PACK_ID_PATTERN = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/u;

package/dist/cli/lib/validation/index.js

@@ -17,6 +17,8 @@ import { MUSTFLOW_JSON_MAX_BYTES } from '../mustflow-read.js';
 import { getContractModelDefinitions, validateCandidateContractModelConfig, } from '../../../core/contract-models.js';
 import { VERSIONING_CONFIG_PATH, detectVersionSourcePaths, readDeclaredVersionSources, releaseVersioningIsEnabled, } from '../../../core/version-sources.js';
 import { normalizeTechnologyPreferencesTable, TECHNOLOGY_CONFIG_RELATIVE_PATH, } from '../../../core/technology-preferences.js';
+import { isPromptCacheStableLeafSkillSurface, measurePromptCacheReferenceBlockBytes, } from '../../../core/prompt-cache-rendering.js';
+import { validateSkillRouteFixtures } from '../../../core/skill-route-fixtures.js';
 import { ALLOWED_APPROVAL_ACTIONS, ALLOWED_APPROVAL_GATES, ALLOWED_BUDGET_LIMIT_ACTIONS, ALLOWED_CAPABILITY_STATES, ALLOWED_COMMIT_MESSAGE_STYLES, ALLOWED_COMPACTION_CATEGORIES, ALLOWED_COMPACTION_LONG_LIMIT_ACTIONS, ALLOWED_COMPACTION_RAW_LIMIT_ACTIONS, ALLOWED_COMPACTION_STATE_STORES, ALLOWED_COMPACTION_STRATEGIES, ALLOWED_CONTEXT_AUTHORITIES, ALLOWED_CONTEXT_DOCUMENT_AUTHORITIES, ALLOWED_CONTEXT_READ_POLICIES, ALLOWED_HANDOFF_MODES, ALLOWED_HARNESS_FRESH_CONTEXT_MODES, ALLOWED_HARNESS_MODES, ALLOWED_HARNESS_PHASES, ALLOWED_ISOLATION_PREFERENCES, ALLOWED_MAP_MODES, ALLOWED_MAP_PRIVACY_LEVELS, ALLOWED_PROJECT_PROFILES, ALLOWED_REPO_MAP_DEGRADED_VALUES, ALLOWED_REPO_MAP_GIT_LS_FILES_STATUSES, ALLOWED_PROMPT_CACHE_STABLE_PREFIX_POLICIES, ALLOWED_PROMPT_CACHE_STRATEGIES, ALLOWED_PROMPT_CACHE_TASK_READ_POLICIES, ALLOWED_REFRESH_CHECKPOINTS, ALLOWED_REFRESH_METHODS, ALLOWED_REFRESH_MODES, ALLOWED_REFRESH_STATE_STORES, ALLOWED_SKILL_RESOURCE_TYPES, ALLOWED_SKILL_ROUTE_CATEGORIES, ALLOWED_SKILL_ROUTE_PROFILES, ALLOWED_SKILL_ROUTE_TYPES, ALLOWED_STALE_TEST_ACTIONS, ALLOWED_TEST_AUTHORING_POLICIES, ALLOWED_TEST_DELETION_REASONS, ALLOWED_TESTING_POLICIES, ALLOWED_TRANSLATION_POLICIES, ALLOWED_VERIFICATION_SELECTION_STRATEGIES, ALLOWED_VERSION_SOURCE_AUTHORITIES, ALLOWED_VERSION_SOURCE_KINDS, CAPABILITY_BOOLEAN_FIELDS, CAPABILITY_STATE_FIELDS, CONTEXT_AUTHORITY_DRIFT_PATTERNS, DESIGN_TOKEN_DEFINITION_PATTERNS, FORBIDDEN_RELEASE_VERSIONING_CONTRACT_FIELDS, FORBIDDEN_TEST_DELETION_REASONS, FORBIDDEN_VERIFICATION_SELECTION_AUTHORITY_FIELDS, LOCAL_ABSOLUTE_PATH_PATTERNS, LOCAL_TASK_STATE_ROOTS, RAW_COMMAND_FENCE_PATTERN, RELEASE_VERSIONING_BOOLEAN_FIELDS, REPO_MAP_DOC_ID, REPO_MAP_GENERATOR, REPO_MAP_LIFECYCLE, REPO_MAP_PRIVACY_MODE, REPO_MAP_RELATIVE_ROOT, REPO_MAP_REMOTE_OR_BRANCH_PATTERNS, REPO_MAP_SOURCE_FINGERPRINT_PATTERN, REPO_MAP_SOURCE_POLICY, REQUIRED_AGENT_LOOP_PHASES, REQUIRED_SKILL_SCRIPT_RUN_POLICY, REQUIRED_SKILL_SECTION_IDS, ROUTER_INDEX_FILES, ROUTER_INDEX_PROCEDURE_SECTION_PATTERN, SECRET_LIKE_CONTEXT_PATTERNS, SKILL_COMMAND_PERMISSION_CLAIM_PATTERNS, SKILL_INDEX_PATH, SKILL_PACK_ID_PATTERN, SKILL_RESOURCE_MANIFEST, SKILL_RESOURCE_ROOTS, SKILL_RESOURCE_TYPE_BY_ROOT, SKILL_ROUTE_CATEGORY_LABELS, SKILL_ROUTES_METADATA_PATH, SUPPORTED_SKILL_SCHEMA_VERSION, TEST_AUTHORING_BOOLEAN_FIELDS, VERIFICATION_SELECTION_BOOLEAN_FIELDS, VOLATILE_REPO_MAP_PATTERNS } from './constants.js';
 import { hasOwn, isPositiveInteger, isSafeRelativePath, pushStrictIssue, pushStrictWarning, validateAllowedStringField, validateBooleanField, validateExactStringArrayField, validateNestedTable, validatePathArrayField, validatePathField, validatePositiveIntegerField, validateRequiredFiles, validateRequiredPathField, validateRequiredStringField, validateStringArrayField, validateStringArrayMembers, validateStringField, validateTable, validateToml, validateWorkspaceRoots } from './primitives.js';
 import { isConfiguredCommandIntent, isDeclaredCommandIntent } from './command-intents.js';
@@ -63,6 +65,7 @@ function validateMustflowConfig(mustflowToml, issues) {
             const stable = validateNestedTable(layers, 'stable', '[prompt_cache.layers.stable]', issues);
             if (stable) {
                 validatePathArrayField(stable, 'read', '[prompt_cache.layers.stable].read', issues);
+                validatePositiveIntegerField(stable, 'target_kb', '[prompt_cache.layers.stable].target_kb', issues);
             }
             const task = validateNestedTable(layers, 'task', '[prompt_cache.layers.task]', issues);
             if (task) {
@@ -511,7 +514,33 @@ function validateManifestLock(projectRoot, issues) {
         issues.push({ message: issue });
     }
 }
-function validateStrictPromptCachePolicy(mustflowToml, issues) {
+function validateStrictStablePromptCacheBudget(projectRoot, promptCache, stableRead, issues) {
+    if (!isPositiveInteger(promptCache.max_stable_prefix_kb)) {
+        return;
+    }
+    const budgetBytes = Number(promptCache.max_stable_prefix_kb) * 1024;
+    let renderedBytes = 0;
+    for (const entry of stableRead) {
+        if (typeof entry !== 'string' || !isSafeRelativePath(entry)) {
+            continue;
+        }
+        const normalizedPath = toPosixPath(entry);
+        const absolutePath = path.join(projectRoot, entry);
+        if (!existsSync(absolutePath)) {
+            pushStrictIssue(issues, `stable prefix document is missing: ${normalizedPath}`);
+            continue;
+        }
+        const content = readStrictMustflowText(projectRoot, entry, issues);
+        if (content === undefined) {
+            continue;
+        }
+        renderedBytes += measurePromptCacheReferenceBlockBytes(entry, content);
+    }
+    if (renderedBytes > budgetBytes) {
+        pushStrictIssue(issues, `stable prefix exceeds [prompt_cache].max_stable_prefix_kb: ${renderedBytes} rendered bytes > ${budgetBytes} budget bytes`);
+    }
+}
+function validateStrictPromptCachePolicy(projectRoot, mustflowToml, issues) {
     if (!mustflowToml || !isRecord(mustflowToml.prompt_cache)) {
         pushStrictIssue(issues, '[prompt_cache] table is required');
         return;
@@ -534,7 +563,11 @@ function validateStrictPromptCachePolicy(mustflowToml, issues) {
         if (typeof entry === 'string' && volatileSources.has(entry)) {
             pushStrictIssue(issues, `[prompt_cache.layers.stable].read must not include volatile path "${entry}"`);
         }
+        if (typeof entry === 'string' && isPromptCacheStableLeafSkillSurface(entry)) {
+            pushStrictIssue(issues, `[prompt_cache.layers.stable].read must not include leaf skill or expanded route surface "${toPosixPath(entry)}"`);
+        }
     }
+    validateStrictStablePromptCacheBudget(projectRoot, promptCache, stable.read, issues);
     if (promptCache.exclude_volatile_state_from_prefix !== true) {
         pushStrictIssue(issues, '[prompt_cache].exclude_volatile_state_from_prefix should be true');
     }
@@ -590,6 +623,11 @@ function validateStrictRouterIndexes(projectRoot, issues) {
         }
     }
 }
+function validateStrictSkillRouteFixtures(projectRoot, issues) {
+    for (const issue of validateSkillRouteFixtures(projectRoot)) {
+        pushStrictIssue(issues, issue.message);
+    }
+}
 function validateSkillIndexRouteShape(content, issues) {
     for (const line of content.split(/\r?\n/u)) {
         if (!line.trim().startsWith('|')) {
@@ -1536,7 +1574,7 @@ function validateStrictStorage(projectRoot, limits, issues) {
 }
 function validateStrict(projectRoot, parsed, issues) {
     const retentionLimits = validateStrictRetentionPolicy(parsed.mustflowToml, issues);
-    validateStrictPromptCachePolicy(parsed.mustflowToml, issues);
+    validateStrictPromptCachePolicy(projectRoot, parsed.mustflowToml, issues);
     validateStrictRefreshPolicy(parsed.mustflowToml, issues);
     validateStrictHarnessPolicy(parsed.mustflowToml, issues);
     validateStrictCommandDefaults(projectRoot, parsed.commandsToml, issues);
@@ -1548,6 +1586,7 @@ function validateStrict(projectRoot, parsed, issues) {
     validateStrictTemplateVersionSync(projectRoot, parsed.preferencesToml, issues);
     validateStrictManagedMarkdownIdentities(projectRoot, issues);
     validateStrictRouterIndexes(projectRoot, issues);
+    validateStrictSkillRouteFixtures(projectRoot, issues);
     validateStrictSkills(projectRoot, parsed.commandsToml, issues);
     validateStrictTemplateSkillProfiles(issues);
     validateStrictRepoMap(projectRoot, issues);

package/dist/core/check-issues.js

@@ -30,6 +30,9 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.command_contract.project_local_bin_bare_executable', /^Strict warning: configured agent-runnable intent [^\s]+ uses bare executable "[^"]+" that matches project-local node_modules\/\.bin/u],
     ['mustflow.prompt_cache.required', /^Strict: \[prompt_cache\] table is required$/u],
     ['mustflow.prompt_cache.volatile_in_stable', /^Strict: \[prompt_cache\.layers\.stable\]\.read must not include volatile path /u],
+    ['mustflow.prompt_cache.leaf_skill_in_stable', /^Strict: \[prompt_cache\.layers\.stable\]\.read must not include leaf skill or expanded route surface /u],
+    ['mustflow.prompt_cache.stable_file_missing', /^Strict: stable prefix document is missing: /u],
+    ['mustflow.prompt_cache.stable_prefix_over_budget', /^Strict: stable prefix exceeds \[prompt_cache\]\.max_stable_prefix_kb: \d+ rendered bytes > \d+ budget bytes$/u],
     ['mustflow.refresh.hash_method_required', /^Strict: \[refresh\]\.default_method should be "hash_check" for cache-friendly refresh$/u],
     ['mustflow.release.template_version_mismatch', /^Strict: templates\/default\/manifest\.toml version "[^"]+" must match package\.json version "[^"]+" when \[release\.versioning\]\.sync_template_version is true$/u],
     ['mustflow.release.template_version_ahead', /^Strict: templates\/default\/manifest\.toml version "[^"]+" must not be ahead of package\.json version "[^"]+"$/u],
@@ -57,6 +60,8 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.skill.route_metadata_category_mismatch', /^Strict: \.mustflow\/skills\/INDEX\.md route "[^"]+" must appear under the .+ category section from \.mustflow\/skills\/routes\.toml$/u],
     ['mustflow.skill.route_metadata_unknown_reference', /^Strict: \.mustflow\/skills\/routes\.toml route "[^"]+" references unknown mutually exclusive route "[^"]+"$/u],
     ['mustflow.skill.route_metadata_asymmetric_exclusion', /^Strict warning: \.mustflow\/skills\/routes\.toml route "[^"]+" lists "[^"]+" as mutually exclusive but the reverse route does not$/u],
+    ['mustflow.skill.route_fixture_invalid', /^Strict: \.mustflow\/skills\/route-fixtures\.json (?:must|is not valid JSON|cases\[\d+\])/u],
+    ['mustflow.skill.route_fixture_mismatch', /^Strict: Skill route fixture "[^"]+" (?:expected|forbids)/u],
     ['mustflow.skill.template_profile_empty_category', /^Strict: template profile "[^"]+" (?:skill index category ".+" has no route rows|route category gate references ".+" without route rows)$/u],
     ['mustflow.skill.template_profile_dead_route', /^Strict: template profile "[^"]+" (?:\.mustflow\/skills\/INDEX\.md route "[^"]+" points to a skill not installed by that profile|\.mustflow\/skills\/routes\.toml route "[^"]+" points to a skill not installed by that profile|skill "[^"]+" is installed but not listed in \.mustflow\/skills\/INDEX\.md)$/u],
     ['mustflow.skill.template_profile_missing_main_route', /^Strict: template profile "[^"]+" skill category ".+" must include at least one primary or authoring route$/u],

package/dist/core/prompt-cache-rendering.js

@@ -0,0 +1,19 @@
+function toPromptCachePosixPath(relativePath) {
+    return relativePath.replace(/\\/gu, '/');
+}
+export function isPromptCacheStableLeafSkillSurface(relativePath) {
+    const normalized = toPromptCachePosixPath(relativePath);
+    return normalized === '.mustflow/skills/INDEX.md'
+        || normalized === '.mustflow/skills/routes.toml'
+        || /^\.mustflow\/skills\/[^/]+\/.+/u.test(normalized);
+}
+export function normalizePromptCacheBlockContent(content) {
+    const normalized = content.replace(/\r\n?/gu, '\n').replace(/\n*$/u, '');
+    return `${normalized}\n`;
+}
+export function renderPromptCacheReferenceBlock(relativePath, content) {
+    return `--- mustflow-cache-block: ${toPromptCachePosixPath(relativePath)} ---\n${normalizePromptCacheBlockContent(content)}`;
+}
+export function measurePromptCacheReferenceBlockBytes(relativePath, content) {
+    return Buffer.byteLength(renderPromptCacheReferenceBlock(relativePath, content), 'utf8');
+}

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

@@ -198,6 +198,41 @@ 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: 'skill-route-report',
+        schemaFile: 'skill-route-report.schema.json',
+        producer: 'mf skill route --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'skill',
+            'route',
+            '--task',
+            'Change TypeScript CLI output',
+            '--path',
+            'src/cli/index.ts',
+            '--reason',
+            'code_change',
+            '--json',
+        ],
+    },
+    {
+        id: 'route-fixture',
+        schemaFile: 'route-fixture.schema.json',
+        producer: 'parsed .mustflow/skills/route-fixtures.json',
+        packaged: true,
+        documented: true,
+    },
     {
         id: 'latest-run-pointer',
         schemaFile: 'latest-run-pointer.schema.json',

package/dist/core/quality-gaming.js

@@ -0,0 +1,304 @@
+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;
+const EMPTY_CATCH_PATTERN = /\bcatch\s*(?:\([^)]*\))?\s*\{\s*\}/u;
+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 (isCode && EMPTY_CATCH_PATTERN.test(codeSurface)) {
+        addRisk(risks, 'empty_catch_swallow_added', 'high', relativePath, candidate.line, 'Added line contains an empty catch block that swallows failures.', 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,
+    };
+}