mustflow 2.74.3 → 2.74.4

package/dist/cli/lib/script-pack-registry.js

@@ -13,11 +13,64 @@ export const SCRIPT_PACKS = [
                 usage: 'mf script-pack run core/text-budget check <path...> [options]',
                 summaryKey: 'scriptPack.script.textBudget.summary',
                 actions: ['check'],
+                useWhen: [
+                    'Check exact text budgets for docs, package metadata, prompts, release notes, or user-facing copy.',
+                    'Inspect a JSON string field by JSON Pointer when a public description, label, or summary has a length contract.',
+                ],
+                phases: ['before_change', 'after_change', 'review'],
+                readOnly: true,
+                mutates: false,
+                network: false,
+                inputs: ['path', 'json_pointer', 'budget', 'unit'],
+                outputs: ['human_summary', 'json_report'],
+                relatedSkills: [
+                    'docs-prose-review',
+                    'public-json-contract-change',
+                    'readme-authoring',
+                    'release-notes-authoring',
+                ],
+                riskLevel: 'low',
+                cost: 'low',
                 reportSchemaFile: 'text-budget-report.schema.json',
                 loadRunner: async () => (await import('../script-packs/core-text-budget.js')).runCoreTextBudgetScript,
             },
         ],
     },
+    {
+        id: 'repo',
+        summaryKey: 'scriptPack.pack.repo.summary',
+        scripts: [
+            {
+                packId: 'repo',
+                id: 'generated-boundary',
+                ref: scriptRef('repo', 'generated-boundary'),
+                usage: 'mf script-pack run repo/generated-boundary check <path...> [options]',
+                summaryKey: 'scriptPack.script.generatedBoundary.summary',
+                actions: ['check'],
+                useWhen: [
+                    'Check candidate edit paths before changing files that may be generated, ignored, protected, vendor, or cache output.',
+                    'Review changed paths after implementation when generated or protected-file drift would make completion evidence misleading.',
+                ],
+                phases: ['before_change', 'after_change', 'review'],
+                readOnly: true,
+                mutates: false,
+                network: false,
+                inputs: ['path'],
+                outputs: ['human_summary', 'json_report'],
+                relatedSkills: [
+                    'completion-evidence-gate',
+                    'proactive-risk-surfacing',
+                    'quality-gaming-guard',
+                    'repo-improvement-loop',
+                    'template-install-surface-sync',
+                ],
+                riskLevel: 'low',
+                cost: 'low',
+                reportSchemaFile: 'generated-boundary-report.schema.json',
+                loadRunner: async () => (await import('../script-packs/repo-generated-boundary.js')).runRepoGeneratedBoundaryScript,
+            },
+        ],
+    },
 ];
 export function listScriptPackScripts() {
     return SCRIPT_PACKS.flatMap((pack) => pack.scripts);

package/dist/cli/script-packs/repo-generated-boundary.js

@@ -0,0 +1,94 @@
+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 { GENERATED_BOUNDARY_SCRIPT_REF, inspectGeneratedBoundary, } from '../../core/generated-boundary.js';
+const GENERATED_BOUNDARY_OPTIONS = [{ name: '--json', kind: 'boolean' }];
+export function getRepoGeneratedBoundaryHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf script-pack run repo/generated-boundary check <path...> [options]',
+        summary: t(lang, 'generatedBoundary.help.summary'),
+        options: [
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf script-pack run repo/generated-boundary check src/cli/index.ts',
+            'mf script-pack run repo/generated-boundary check dist/cli/index.js --json',
+            'mf script-pack run repo/generated-boundary check AGENTS.md .mustflow/config/manifest.lock.toml',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'generatedBoundary.help.exit.ok') },
+            { label: '1', description: t(lang, 'generatedBoundary.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseGeneratedBoundaryOptions(args, lang) {
+    const [action, ...rest] = args;
+    const parsed = parseCliOptions(rest, GENERATED_BOUNDARY_OPTIONS, { allowPositionals: true });
+    const json = hasParsedCliOption(parsed, '--json');
+    if (action !== 'check') {
+        return {
+            action: 'check',
+            json,
+            paths: parsed.positionals,
+            error: action
+                ? t(lang, 'generatedBoundary.error.unknownAction', { action })
+                : t(lang, 'generatedBoundary.error.missingAction'),
+        };
+    }
+    if (parsed.error) {
+        return { action, json, paths: parsed.positionals, error: formatCliOptionParseError(parsed.error, lang) };
+    }
+    if (parsed.positionals.length === 0) {
+        return { action, json, paths: parsed.positionals, error: t(lang, 'generatedBoundary.error.missingPath') };
+    }
+    return { action, json, paths: parsed.positionals };
+}
+function renderGeneratedBoundarySummary(report, lang) {
+    const lines = [
+        t(lang, 'generatedBoundary.title'),
+        `${t(lang, 'scriptPack.label.script')}: ${GENERATED_BOUNDARY_SCRIPT_REF}`,
+        `${t(lang, 'label.status')}: ${report.status}`,
+        `${t(lang, 'generatedBoundary.label.checkedTargets')}: ${report.targets.length}`,
+        `${t(lang, 'generatedBoundary.label.findings')}: ${report.findings.length}`,
+    ];
+    if (report.targets.length > 0) {
+        lines.push(t(lang, 'generatedBoundary.label.targets'));
+        for (const target of report.targets) {
+            const boundaries = target.matched_boundaries.length === 0 ? t(lang, 'value.none') : target.matched_boundaries.join(', ');
+            lines.push(`- ${target.path}: ${target.kind}, ${t(lang, 'generatedBoundary.label.boundaries')}: ${boundaries}`);
+        }
+    }
+    if (report.findings.length > 0) {
+        lines.push(t(lang, 'generatedBoundary.label.findings'));
+        for (const finding of report.findings) {
+            lines.push(`- ${finding.path}: ${finding.code} (${finding.message})`);
+        }
+    }
+    if (report.issues.length > 0) {
+        lines.push(t(lang, 'generatedBoundary.label.issues'), ...report.issues.map((issue) => `- ${issue}`));
+    }
+    if (report.findings.length === 0 && report.issues.length === 0) {
+        lines.push(t(lang, 'generatedBoundary.clean'));
+    }
+    return lines.join('\n');
+}
+export function runRepoGeneratedBoundaryScript(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getRepoGeneratedBoundaryHelp(lang));
+        return 0;
+    }
+    const options = parseGeneratedBoundaryOptions(args, lang);
+    if (options.error) {
+        printUsageError(reporter, options.error, 'mf script-pack run repo/generated-boundary --help', getRepoGeneratedBoundaryHelp(lang), lang);
+        return 1;
+    }
+    const report = inspectGeneratedBoundary(resolveMustflowRoot(), { paths: options.paths });
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderGeneratedBoundarySummary(report, lang));
+    return report.ok ? 0 : 1;
+}

package/dist/core/generated-boundary.js

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord, readMustflowConfigIfExists, readStringArray } from './config-loading.js';
+import { ensureInside } from './safe-filesystem.js';
+export const GENERATED_BOUNDARY_PACK_ID = 'repo';
+export const GENERATED_BOUNDARY_SCRIPT_ID = 'generated-boundary';
+export const GENERATED_BOUNDARY_SCRIPT_REF = `${GENERATED_BOUNDARY_PACK_ID}/${GENERATED_BOUNDARY_SCRIPT_ID}`;
+const BUILTIN_GENERATED_PATTERNS = [
+    'REPO_MAP.md',
+    '.mustflow/config/manifest.lock.toml',
+    '.mustflow/state/**',
+    '.mustflow/cache/**',
+    'dist/**',
+    'build/**',
+    'coverage/**',
+    '.next/**',
+    '.turbo/**',
+];
+const BUILTIN_VENDOR_PATTERNS = ['node_modules/**', 'vendor/**', 'third_party/**'];
+const BUILTIN_CACHE_PATTERNS = ['.cache/**', '.parcel-cache/**', '.pytest_cache/**'];
+const BUILTIN_PROTECTED_PATTERNS = ['.git/**', '**/*.pem', '**/*.key', '**/.env'];
+const CATEGORY_FINDING = {
+    generated: { code: 'generated_boundary_generated_path', severity: 'medium' },
+    ignored: { code: 'generated_boundary_ignored_path', severity: 'medium' },
+    protected: { code: 'generated_boundary_protected_path', severity: 'critical' },
+    vendor: { code: 'generated_boundary_vendor_path', severity: 'high' },
+    cache: { code: 'generated_boundary_cache_path', severity: 'medium' },
+    outside_root: { code: 'generated_boundary_path_outside_root', severity: 'high' },
+};
+function toPosixPath(value) {
+    return value.replace(/\\/gu, '/');
+}
+function normalizeRelativePath(value) {
+    return toPosixPath(value).replace(/^\.\/+/u, '').replace(/\/+$/u, '') || '.';
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function escapeRegExp(value) {
+    return value.replace(/[\\^$+?.()|[\]{}]/gu, '\\$&');
+}
+function globToRegExp(pattern) {
+    const normalized = normalizeRelativePath(pattern).replace(/^\/+/u, '');
+    let source = '^';
+    for (let index = 0; index < normalized.length;) {
+        if (normalized.startsWith('**', index)) {
+            source += '.*';
+            index += 2;
+            continue;
+        }
+        const character = normalized[index];
+        if (character === '*') {
+            source += '[^/]*';
+            index += 1;
+            continue;
+        }
+        if (character === '?') {
+            source += '[^/]';
+            index += 1;
+            continue;
+        }
+        source += escapeRegExp(character ?? '');
+        index += 1;
+    }
+    return new RegExp(`${source}$`, 'u');
+}
+function patternMatches(pattern, relativePath) {
+    const normalizedPattern = normalizeRelativePath(pattern);
+    const normalizedPath = normalizeRelativePath(relativePath);
+    if (normalizedPattern.endsWith('/**')) {
+        const base = normalizedPattern.slice(0, -3);
+        if (normalizedPath === base || normalizedPath.startsWith(`${base}/`)) {
+            return true;
+        }
+    }
+    if (globToRegExp(normalizedPattern).test(normalizedPath)) {
+        return true;
+    }
+    return normalizedPattern.startsWith('**/') && globToRegExp(normalizedPattern.slice(3)).test(normalizedPath);
+}
+function readPatternTable(config, tableName, key) {
+    const table = config?.[tableName];
+    return isRecord(table) ? (readStringArray(table, key) ?? []) : [];
+}
+function createPolicy(projectRoot, issues) {
+    let config;
+    try {
+        config = readMustflowConfigIfExists(projectRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        issues.push(`Could not read .mustflow/config/mustflow.toml: ${message}`);
+    }
+    return {
+        config_path: '.mustflow/config/mustflow.toml',
+        config_loaded: config !== undefined,
+        generated_patterns: readPatternTable(config, 'document_roots', 'generated'),
+        ignored_patterns: readPatternTable(config, 'document_roots', 'ignored'),
+        protected_patterns: readPatternTable(config, 'edit_policy', 'protected'),
+        builtin_generated_patterns: [...BUILTIN_GENERATED_PATTERNS],
+        builtin_vendor_patterns: [...BUILTIN_VENDOR_PATTERNS],
+        builtin_cache_patterns: [...BUILTIN_CACHE_PATTERNS],
+        builtin_protected_patterns: [...BUILTIN_PROTECTED_PATTERNS],
+    };
+}
+function createBoundaryPatterns(policy) {
+    return [
+        ...policy.generated_patterns.map((pattern) => ({ category: 'generated', pattern, source: 'mustflow_config' })),
+        ...policy.ignored_patterns.map((pattern) => ({ category: 'ignored', pattern, source: 'mustflow_config' })),
+        ...policy.protected_patterns.map((pattern) => ({ category: 'protected', pattern, source: 'mustflow_config' })),
+        ...policy.builtin_generated_patterns.map((pattern) => ({ category: 'generated', pattern, source: 'builtin' })),
+        ...policy.builtin_vendor_patterns.map((pattern) => ({ category: 'vendor', pattern, source: 'builtin' })),
+        ...policy.builtin_cache_patterns.map((pattern) => ({ category: 'cache', pattern, source: 'builtin' })),
+        ...policy.builtin_protected_patterns.map((pattern) => ({ category: 'protected', pattern, source: 'builtin' })),
+    ];
+}
+function targetKind(absolutePath) {
+    if (!existsSync(absolutePath)) {
+        return { exists: false, kind: 'missing' };
+    }
+    const stats = lstatSync(absolutePath);
+    if (stats.isFile()) {
+        return { exists: true, kind: 'file' };
+    }
+    if (stats.isDirectory()) {
+        return { exists: true, kind: 'directory' };
+    }
+    return { exists: true, kind: 'other' };
+}
+function makeFinding(code, severity, targetPath, boundary, message, pattern, source) {
+    return { code, severity, message, path: targetPath, boundary, pattern, source };
+}
+function createInputHash(policy, targets, issues) {
+    const inputState = {
+        policy,
+        targets: targets.map((target) => ({
+            input: target.input,
+            path: target.path,
+            exists: target.exists,
+            kind: target.kind,
+            matched_patterns: target.matched_patterns,
+        })),
+        issues,
+    };
+    return `sha256:${createHash('sha256').update(JSON.stringify(inputState)).digest('hex')}`;
+}
+export function inspectGeneratedBoundary(projectRoot, options) {
+    const root = path.resolve(projectRoot);
+    const issues = [];
+    const policy = createPolicy(root, issues);
+    const patterns = createBoundaryPatterns(policy);
+    const targets = [];
+    const findings = [];
+    for (const targetPath of options.paths) {
+        let relativePath = targetPath;
+        let absolutePath;
+        try {
+            absolutePath = path.resolve(process.cwd(), targetPath);
+            ensureInside(root, absolutePath);
+            relativePath = normalizeRelativePath(path.relative(root, absolutePath));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            issues.push(message);
+            targets.push({
+                input: targetPath,
+                path: targetPath,
+                exists: null,
+                kind: 'unknown',
+                matched_boundaries: ['outside_root'],
+                matched_patterns: [],
+            });
+            findings.push(makeFinding('generated_boundary_path_outside_root', 'high', targetPath, 'outside_root', message, null, null));
+            continue;
+        }
+        let existence;
+        try {
+            existence = targetKind(absolutePath);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            issues.push(`${relativePath}: ${message}`);
+            targets.push({
+                input: targetPath,
+                path: relativePath,
+                exists: null,
+                kind: 'unknown',
+                matched_boundaries: [],
+                matched_patterns: [],
+            });
+            findings.push(makeFinding('generated_boundary_unreadable_path', 'high', relativePath, 'protected', message, null, null));
+            continue;
+        }
+        const matchedPatterns = patterns.filter((candidate) => patternMatches(candidate.pattern, relativePath));
+        const matchedBoundaries = uniqueSorted(matchedPatterns.map((candidate) => candidate.category));
+        targets.push({
+            input: targetPath,
+            path: relativePath,
+            exists: existence.exists,
+            kind: existence.kind,
+            matched_boundaries: matchedBoundaries,
+            matched_patterns: matchedPatterns,
+        });
+        for (const match of matchedPatterns) {
+            const finding = CATEGORY_FINDING[match.category];
+            findings.push(makeFinding(finding.code, finding.severity, relativePath, match.category, `${relativePath} matches ${match.category} boundary pattern ${match.pattern}.`, match.pattern, match.source));
+        }
+    }
+    const status = findings.some((finding) => ['generated_boundary_path_outside_root', 'generated_boundary_unreadable_path'].includes(finding.code))
+        ? 'error'
+        : findings.length > 0 || issues.length > 0
+            ? 'failed'
+            : 'passed';
+    return {
+        schema_version: '1',
+        command: 'script-pack',
+        pack_id: GENERATED_BOUNDARY_PACK_ID,
+        script_id: GENERATED_BOUNDARY_SCRIPT_ID,
+        script_ref: GENERATED_BOUNDARY_SCRIPT_REF,
+        action: 'check',
+        status,
+        ok: status === 'passed',
+        mustflow_root: root,
+        policy,
+        input_hash: createInputHash(policy, targets, issues),
+        targets,
+        findings,
+        issues,
+    };
+}

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

@@ -215,6 +215,23 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         documented: true,
         installedCommand: ['mf', 'script-pack', 'list', '--json'],
     },
+    {
+        id: 'script-pack-suggestion-report',
+        schemaFile: 'script-pack-suggestion-report.schema.json',
+        producer: 'mf script-pack suggest --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'script-pack',
+            'suggest',
+            '--path',
+            'AGENTS.md',
+            '--phase',
+            'before_change',
+            '--json',
+        ],
+    },
     {
         id: 'text-budget-report',
         schemaFile: 'text-budget-report.schema.json',
@@ -234,6 +251,24 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         ],
         expectedExitCodes: [0, 1],
     },
+    {
+        id: 'generated-boundary-report',
+        schemaFile: 'generated-boundary-report.schema.json',
+        producer: 'mf script-pack run repo/generated-boundary check <path...> --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'script-pack',
+            'run',
+            'repo/generated-boundary',
+            'check',
+            'AGENTS.md',
+            '.mustflow/config/manifest.lock.toml',
+            '--json',
+        ],
+        expectedExitCodes: [0, 1],
+    },
     {
         id: 'skill-route-report',
         schemaFile: 'skill-route-report.schema.json',

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

@@ -0,0 +1,199 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+export function isScriptPackSuggestionPhase(value) {
+    return ['before_change', 'during_change', 'after_change', 'review'].includes(value);
+}
+function uniqueSortedStrings(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function uniqueSortedPhases(values) {
+    return uniqueSortedStrings(values);
+}
+function uniqueSortedSurfaces(values) {
+    return uniqueSortedStrings(values);
+}
+function normalizeReportPath(mustflowRoot, value) {
+    const absolute = path.resolve(mustflowRoot, value);
+    const relative = path.relative(mustflowRoot, absolute);
+    return relative.startsWith('..') || path.isAbsolute(relative)
+        ? value.replace(/\\/gu, '/')
+        : (relative.replace(/\\/gu, '/') || '.');
+}
+export function classifyScriptPackPathSurface(relativePath) {
+    const normalized = relativePath.replace(/\\/gu, '/').replace(/^\.\/+/u, '');
+    const surfaces = [];
+    if (normalized === 'REPO_MAP.md' ||
+        normalized === '.mustflow/config/manifest.lock.toml' ||
+        normalized.startsWith('dist/') ||
+        normalized.startsWith('build/') ||
+        normalized.startsWith('coverage/') ||
+        normalized.startsWith('.mustflow/cache/') ||
+        normalized.startsWith('.mustflow/state/')) {
+        surfaces.push('generated');
+    }
+    if (normalized.startsWith('.mustflow/config/') || normalized.startsWith('config/')) {
+        surfaces.push('config');
+    }
+    if (normalized.startsWith('.mustflow/skills/') || normalized.includes('/.mustflow/skills/')) {
+        surfaces.push('skill');
+    }
+    if (normalized.startsWith('templates/')) {
+        surfaces.push('template');
+    }
+    if (normalized.startsWith('schemas/') || normalized.endsWith('.schema.json')) {
+        surfaces.push('schema');
+    }
+    if (normalized === 'README.md' ||
+        normalized === 'CHANGELOG.md' ||
+        normalized.endsWith('.md') ||
+        normalized.startsWith('docs/') ||
+        normalized.startsWith('docs-site/')) {
+        surfaces.push('docs');
+    }
+    if (normalized.startsWith('tests/') || normalized.endsWith('.test.js') || normalized.endsWith('.test.ts')) {
+        surfaces.push('test');
+    }
+    if (normalized === 'package.json' ||
+        normalized === 'bun.lock' ||
+        normalized === 'package-lock.json' ||
+        normalized.startsWith('.github/workflows/')) {
+        surfaces.push('package');
+    }
+    if (normalized.startsWith('src/') || normalized.endsWith('.ts') || normalized.endsWith('.tsx')) {
+        surfaces.push('source');
+    }
+    return surfaces.length > 0 ? uniqueSortedSurfaces(surfaces) : ['unknown'];
+}
+function readChangedPaths(mustflowRoot, issues) {
+    const result = spawnSync('git', ['status', '--short'], {
+        cwd: mustflowRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    if (result.status !== 0) {
+        const detail = result.stderr.trim() || result.stdout.trim() || `git status exited with ${result.status}`;
+        issues.push(`Could not read changed paths: ${detail}`);
+        return [];
+    }
+    return result.stdout
+        .split(/\r?\n/u)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const renamed = /\s->\s(?<target>.+)$/u.exec(line);
+        return renamed?.groups?.target ?? line.slice(3).trim();
+    })
+        .filter((entry) => entry.length > 0);
+}
+function surfacesForScript(script) {
+    const surfaces = new Set();
+    const searchable = [
+        script.ref,
+        script.usage,
+        ...script.useWhen,
+        ...script.inputs,
+        ...script.outputs,
+        ...script.relatedSkills,
+    ].join(' ');
+    const addIf = (surface, pattern) => {
+        if (pattern.test(searchable)) {
+            surfaces.add(surface);
+        }
+    };
+    addIf('docs', /docs|readme|release|copy|text|prompt/u);
+    addIf('schema', /json|schema|contract/u);
+    addIf('template', /template|install|manifest/u);
+    addIf('skill', /skill|workflow/u);
+    addIf('generated', /generated|protected|vendor|cache|boundary/u);
+    addIf('config', /config|command/u);
+    addIf('package', /package|release/u);
+    addIf('source', /code|source|path/u);
+    return uniqueSortedSurfaces(surfaces);
+}
+function confidenceForScore(score) {
+    if (score >= 7) {
+        return 'high';
+    }
+    if (score >= 4) {
+        return 'medium';
+    }
+    return 'low';
+}
+export function createScriptPackSuggestionReport(mustflowRoot, options) {
+    const issues = [];
+    const changedPaths = options.changed ? readChangedPaths(mustflowRoot, issues) : [];
+    const inputPaths = uniqueSortedStrings([...options.paths, ...changedPaths].map((value) => normalizeReportPath(mustflowRoot, value)));
+    const analyzedPaths = inputPaths.map((entry) => ({ path: entry, surfaces: classifyScriptPackPathSurface(entry) }));
+    const requestedSurfaces = new Set(analyzedPaths.flatMap((entry) => entry.surfaces));
+    const suggestions = options.scripts
+        .map((script) => {
+        let score = 0;
+        const reasons = [];
+        const matchedPhases = options.phases.filter((phase) => script.phases.includes(phase));
+        if (matchedPhases.length > 0) {
+            score += matchedPhases.length * 3;
+            reasons.push(`Matches requested phase: ${matchedPhases.join(', ')}`);
+        }
+        const matchedSkills = options.skills.filter((skill) => script.relatedSkills.includes(skill));
+        if (matchedSkills.length > 0) {
+            score += matchedSkills.length * 4;
+            reasons.push(`Matches related skill: ${matchedSkills.join(', ')}`);
+        }
+        const scriptSurfaces = surfacesForScript(script);
+        const matchedSurfaces = scriptSurfaces.filter((surface) => requestedSurfaces.has(surface));
+        if (matchedSurfaces.length > 0) {
+            score += matchedSurfaces.length * 2;
+            reasons.push(`Matches changed surface: ${matchedSurfaces.join(', ')}`);
+        }
+        if (inputPaths.length > 0 && script.inputs.includes('path')) {
+            score += 1;
+            reasons.push('Accepts explicit path inputs.');
+        }
+        if (script.readOnly && !script.mutates && !script.network) {
+            score += 1;
+            reasons.push('Read-only, non-mutating, offline helper.');
+        }
+        if (score === 0) {
+            return null;
+        }
+        return {
+            script_ref: script.ref,
+            score,
+            confidence: confidenceForScore(score),
+            usage: script.usage,
+            phases: script.phases,
+            matched_phases: uniqueSortedPhases(matchedPhases),
+            matched_skills: uniqueSortedStrings(matchedSkills),
+            matched_surfaces: uniqueSortedSurfaces(matchedSurfaces),
+            reasons,
+            read_only: script.readOnly,
+            mutates: script.mutates,
+            network: script.network,
+            risk_level: script.riskLevel,
+            cost: script.cost,
+            report_schema_file: script.reportSchemaFile,
+            run_hint: script.usage,
+        };
+    })
+        .filter((suggestion) => suggestion !== null)
+        .sort((left, right) => right.score - left.score || left.script_ref.localeCompare(right.script_ref));
+    const status = issues.length > 0 ? 'partial' : suggestions.length > 0 ? 'suggested' : 'empty';
+    return {
+        schema_version: '1',
+        command: 'script-pack',
+        action: 'suggest',
+        status,
+        ok: true,
+        mustflow_root: mustflowRoot,
+        input: {
+            phases: uniqueSortedPhases(options.phases),
+            skills: uniqueSortedStrings(options.skills),
+            paths: inputPaths,
+            changed: options.changed,
+        },
+        analyzed_paths: analyzedPaths,
+        suggestions,
+        issues,
+    };
+}

package/package.json

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

package/schemas/README.md

@@ -57,11 +57,18 @@ Current schemas:
   quality-gaming risks such as line stuffing, validation suppressions, test bypass markers, type
   escapes, generated/vendor logic, empty catch swallowing, and placeholder implementations
 - `script-pack-catalog.schema.json`: output of `mf script-pack list --json`, containing bundled
-  script-pack ids, script refs, action names, usage strings, and associated report schemas
+  script-pack ids, script refs, action names, usage strings, workflow phases, read-only and
+  side-effect flags, input and output capability labels, related skill names, cost and risk hints,
+  and associated report schemas
+- `script-pack-suggestion-report.schema.json`: output of `mf script-pack suggest --json`, containing
+  path, skill, phase, and changed-file evidence used to recommend optional script-pack helpers
 - `text-budget-report.schema.json`: output of
   `mf script-pack run core/text-budget check <path...> --json`, containing
   exact text-budget metrics, input content hashes, policy metadata, findings, and JSON Pointer field
   checks for bounded user-facing strings and generated text
+- `generated-boundary-report.schema.json`: output of
+  `mf script-pack run repo/generated-boundary check <path...> --json`, containing candidate path
+  classifications for generated, ignored, protected, vendor, and cache boundaries before or after edits
 - `skill-route-report.schema.json`: output of `mf skill route --json`, containing compact route
   candidates, selected main and adjunct skills, score breakdowns, route read plans, and source
   route shards without granting command authority or replacing selected `SKILL.md` reads