mustflow 1.30.0 → 1.31.0

package/dist/cli/i18n/es.js

@@ -27,6 +27,7 @@ export const esMessages = {
     "command.contractLint.summary": "Revisa el contrato de comandos",
     "command.status.summary": "Muestra el estado de la instalación local de mustflow",
     "command.update.summary": "Previsualiza o aplica actualizaciones del flujo de trabajo mustflow",
+    "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.run.summary": "Ejecuta un comando configurado de una sola ejecución",
@@ -658,6 +659,17 @@ Lee estos archivos antes de trabajar:
     "version.check.upToDate": "última versión {version}; ya está actualizado",
     "version.check.updateCommand": "Comando de actualización:",
     "version.error.checkFailed": "No se pudo consultar npm para una versión nueva: {message}",
+    "upgrade.help.summary": "Comprueba si el paquete mustflow instalado está actualizado y luego aplica de forma segura las actualizaciones de la plantilla incluida cuando sea posible.",
+    "upgrade.help.option.dryRun": "Comprueba el estado del paquete e imprime el plan de actualización del proyecto sin escribir archivos",
+    "upgrade.help.exit.ok": "El paquete estaba actualizado y la comprobación de actualización del proyecto terminó",
+    "upgrade.help.exit.fail": "Hace falta actualizar el paquete, hay un bloqueo de actualización del proyecto o la entrada es inválida",
+    "upgrade.title": "mustflow upgrade",
+    "upgrade.packageSection": "Paquete:",
+    "upgrade.projectSection": "Plantilla del proyecto:",
+    "upgrade.packageUpdateRequired": "Actualiza primero el paquete mustflow y luego vuelve a ejecutar `mf upgrade`.",
+    "upgrade.noFilesWritten": "No se escribieron archivos del proyecto.",
+    "upgrade.warning.versionCheckFailed": "No se pudo consultar npm para una versión nueva: {message}",
+    "upgrade.warning.continueWithBundledTemplate": "Continuando con la plantilla incluida en el CLI actual.",
     "classify.help.summary": "Clasifica rutas cambiadas, superficies publicas y razones de verificacion sin modificar archivos.",
     "classify.help.option.changed": "Lee rutas desde git status --short --untracked-files=all",
     "classify.help.exit.ok": "La clasificacion de cambios fue inspeccionada e impresa",

package/dist/cli/i18n/fr.js

@@ -27,6 +27,7 @@ export const frMessages = {
     "command.contractLint.summary": "Vérifie le contrat de commandes",
     "command.status.summary": "Affiche l'état de l'installation locale de mustflow",
     "command.update.summary": "Prévisualise ou applique les mises à jour du flux de travail mustflow",
+    "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.run.summary": "Exécute une commande configurée à exécution unique",
@@ -658,6 +659,17 @@ Lisez ces fichiers avant de travailler :
     "version.check.upToDate": "dernière version {version}; déjà à jour",
     "version.check.updateCommand": "Commande de mise à jour :",
     "version.error.checkFailed": "Impossible de vérifier une nouvelle version sur npm : {message}",
+    "upgrade.help.summary": "Vérifie si le paquet mustflow installé est à jour, puis applique en sécurité les mises à jour du modèle inclus quand c'est possible.",
+    "upgrade.help.option.dryRun": "Vérifie l'état du paquet et affiche le plan de mise à jour du projet sans écrire de fichiers",
+    "upgrade.help.exit.ok": "Le paquet était à jour et la vérification de mise à jour du projet est terminée",
+    "upgrade.help.exit.fail": "Une mise à jour du paquet est requise, un blocage de mise à jour du projet existe, ou l'entrée est invalide",
+    "upgrade.title": "mustflow upgrade",
+    "upgrade.packageSection": "Paquet :",
+    "upgrade.projectSection": "Modèle de projet :",
+    "upgrade.packageUpdateRequired": "Mettez d'abord à jour le paquet mustflow, puis relancez `mf upgrade`.",
+    "upgrade.noFilesWritten": "Aucun fichier du projet n'a été écrit.",
+    "upgrade.warning.versionCheckFailed": "Impossible de vérifier une nouvelle version sur npm : {message}",
+    "upgrade.warning.continueWithBundledTemplate": "Poursuite avec le modèle inclus dans le CLI actuel.",
     "classify.help.summary": "Classe les chemins modifies, les surfaces publiques et les raisons de verification sans modifier les fichiers.",
     "classify.help.option.changed": "Lire les chemins depuis git status --short --untracked-files=all",
     "classify.help.exit.ok": "La classification des changements a ete inspectee et affichee",

package/dist/cli/i18n/hi.js

@@ -27,6 +27,7 @@ export const hiMessages = {
     "command.contractLint.summary": "कमांड अनुबंध की जाँच करें",
     "command.status.summary": "स्थानीय mustflow इंस्टॉल स्थिति दिखाएँ",
     "command.update.summary": "mustflow वर्कफ़्लो अपडेट का पूर्वावलोकन करें या लागू करें",
+    "command.upgrade.summary": "Package version जाँचें और installed workflow files सुरक्षित रूप से update करें",
     "command.map.summary": "REPO_MAP.md बनाएँ",
     "command.lineEndings.summary": "लाइन-एंडिंग नीति की जाँच और सामान्यीकरण करें",
     "command.run.summary": "कॉन्फ़िगर की गई एक-बार चलने वाली कमांड चलाएँ",
@@ -658,6 +659,17 @@ export const hiMessages = {
     "version.check.upToDate": "latest {version}; पहले से up to date",
     "version.check.updateCommand": "Update command:",
     "version.error.checkFailed": "npm पर नया version जाँचा नहीं जा सका: {message}",
+    "upgrade.help.summary": "जाँचें कि installed mustflow package current है या नहीं, फिर संभव होने पर current CLI में bundled workflow template updates सुरक्षित रूप से लागू करें.",
+    "upgrade.help.option.dryRun": "Package status जाँचें और files लिखे बिना project update plan प्रिंट करें",
+    "upgrade.help.exit.ok": "Package current था और project update check पूरा हुआ",
+    "upgrade.help.exit.fail": "Package update चाहिए, project update blocker मिला, या input invalid है",
+    "upgrade.title": "mustflow upgrade",
+    "upgrade.packageSection": "Package:",
+    "upgrade.projectSection": "Project template:",
+    "upgrade.packageUpdateRequired": "पहले mustflow package update करें, फिर `mf upgrade` दोबारा चलाएँ.",
+    "upgrade.noFilesWritten": "कोई project file नहीं लिखी गई.",
+    "upgrade.warning.versionCheckFailed": "npm पर नया version जाँचा नहीं जा सका: {message}",
+    "upgrade.warning.continueWithBundledTemplate": "Current CLI में bundled template के साथ आगे बढ़ रहे हैं.",
     "classify.help.summary": "फ़ाइल बदले बिना बदले पथ, सार्वजनिक सतह और जरूरी सत्यापन कारण वर्गीकृत करें.",
     "classify.help.option.changed": "git status --short --untracked-files=all से पथ पढ़ें",
     "classify.help.exit.ok": "बदलाव वर्गीकरण जांचकर प्रिंट किया गया",

package/dist/cli/i18n/ko.js

@@ -27,6 +27,7 @@ export const koMessages = {
     "command.contractLint.summary": "명령 계약을 점검합니다",
     "command.status.summary": "로컬 mustflow 설치 상태를 출력합니다",
     "command.update.summary": "mustflow 워크플로우 갱신을 미리 보거나 적용합니다",
+    "command.upgrade.summary": "패키지 버전을 확인하고 설치된 워크플로우 파일을 안전하게 갱신합니다",
     "command.map.summary": "REPO_MAP.md를 작성합니다",
     "command.lineEndings.summary": "줄바꿈 정책을 검사하고 정규화합니다",
     "command.run.summary": "설정된 일회성 명령을 실행합니다",
@@ -658,6 +659,17 @@ export const koMessages = {
     "version.check.upToDate": "최신 {version}; 이미 최신 상태입니다",
     "version.check.updateCommand": "업데이트 명령:",
     "version.error.checkFailed": "npm에서 새 버전을 확인하지 못했습니다: {message}",
+    "upgrade.help.summary": "설치된 mustflow 패키지가 최신인지 확인한 뒤, 가능하면 현재 CLI에 포함된 워크플로우 템플릿 갱신을 안전하게 적용합니다.",
+    "upgrade.help.option.dryRun": "패키지 상태를 확인하고 파일을 쓰지 않은 채 프로젝트 갱신 계획을 출력합니다",
+    "upgrade.help.exit.ok": "패키지가 최신이고 프로젝트 갱신 확인이 완료되었습니다",
+    "upgrade.help.exit.fail": "패키지 업데이트가 필요하거나, 프로젝트 갱신 차단 항목이 있거나, 입력이 잘못되었습니다",
+    "upgrade.title": "mustflow upgrade",
+    "upgrade.packageSection": "패키지:",
+    "upgrade.projectSection": "프로젝트 템플릿:",
+    "upgrade.packageUpdateRequired": "mustflow 패키지를 먼저 업데이트한 뒤 `mf upgrade`를 다시 실행하세요.",
+    "upgrade.noFilesWritten": "프로젝트 파일은 쓰지 않았습니다.",
+    "upgrade.warning.versionCheckFailed": "npm에서 새 버전을 확인하지 못했습니다: {message}",
+    "upgrade.warning.continueWithBundledTemplate": "현재 CLI에 포함된 템플릿으로 계속 진행합니다.",
     "classify.help.summary": "파일을 수정하지 않고 변경 경로, 공개 표면, 필요한 검증 이유를 분류합니다.",
     "classify.help.option.changed": "git status --short --untracked-files=all에서 경로를 읽습니다",
     "classify.help.exit.ok": "변경 분류를 확인하고 출력했습니다",

package/dist/cli/i18n/zh.js

@@ -27,6 +27,7 @@ export const zhMessages = {
     "command.contractLint.summary": "检查命令契约",
     "command.status.summary": "显示本地 mustflow 安装状态",
     "command.update.summary": "预览或应用 mustflow 工作流更新",
+    "command.upgrade.summary": "检查包版本并安全更新已安装的工作流文件",
     "command.map.summary": "生成 REPO_MAP.md",
     "command.lineEndings.summary": "检查并规范化换行符策略",
     "command.run.summary": "运行已配置的一次性命令",
@@ -658,6 +659,17 @@ export const zhMessages = {
     "version.check.upToDate": "最新版本 {version}；已是最新",
     "version.check.updateCommand": "更新命令：",
     "version.error.checkFailed": "无法从 npm 检查新版本：{message}",
+    "upgrade.help.summary": "检查已安装的 mustflow 包是否为最新，然后在可行时安全应用当前 CLI 捆绑的工作流模板更新。",
+    "upgrade.help.option.dryRun": "检查包状态并打印项目更新计划，不写入文件",
+    "upgrade.help.exit.ok": "包已是最新，项目更新检查已完成",
+    "upgrade.help.exit.fail": "需要先更新包、项目更新存在阻塞项，或输入无效",
+    "upgrade.title": "mustflow upgrade",
+    "upgrade.packageSection": "包：",
+    "upgrade.projectSection": "项目模板：",
+    "upgrade.packageUpdateRequired": "请先更新 mustflow 包，然后再次运行 `mf upgrade`。",
+    "upgrade.noFilesWritten": "未写入项目文件。",
+    "upgrade.warning.versionCheckFailed": "无法从 npm 检查新版本：{message}",
+    "upgrade.warning.continueWithBundledTemplate": "继续使用当前 CLI 捆绑的模板。",
     "classify.help.summary": "在不修改文件的情况下分类变更路径、公开表面和所需验证原因。",
     "classify.help.option.changed": "从 git status --short --untracked-files=all 读取路径",
     "classify.help.exit.ok": "已检查并输出变更分类",

package/dist/cli/index.js

@@ -2,29 +2,6 @@
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { runAdapters } from './commands/adapters.js';
-import { runCheck } from './commands/check.js';
-import { runClassify } from './commands/classify.js';
-import { runContractLint } from './commands/contract-lint.js';
-import { runContext } from './commands/context.js';
-import { runDashboard } from './commands/dashboard.js';
-import { runDoctor } from './commands/doctor.js';
-import { runDocs } from './commands/docs.js';
-import { runExplain } from './commands/explain.js';
-import { runHelp } from './commands/help.js';
-import { runHandoff } from './commands/handoff.js';
-import { runImpact } from './commands/impact.js';
-import { runInit } from './commands/init.js';
-import { runIndex } from './commands/index.js';
-import { runLineEndings } from './commands/line-endings.js';
-import { runMap } from './commands/map.js';
-import { runRun } from './commands/run.js';
-import { runSearch } from './commands/search.js';
-import { runStatus } from './commands/status.js';
-import { runUpdate } from './commands/update.js';
-import { runVerify } from './commands/verify.js';
-import { runVersion } from './commands/version.js';
-import { runVersionSources } from './commands/version-sources.js';
 import { COMMAND_DEFINITIONS } from './lib/command-registry.js';
 import { renderCliError, renderHelp } from './lib/cli-output.js';
 import { DEFAULT_CLI_LANG, SUPPORTED_CLI_LANGS, isCliLang, t } from './lib/i18n.js';
@@ -59,6 +36,7 @@ function getTopLevelHelp(lang) {
             'mf search mustflow_check',
             'mf explain authority AGENTS.md',
             'mf impact --changed',
+            'mf upgrade --dry-run',
             'mf verify --changed --plan-only --json',
             'mf verify --reason code_change',
             'mf line-endings check',
@@ -125,73 +103,76 @@ export async function runCli(argv, reporter = consoleReporter) {
         return 0;
     }
     if (command === '--version' || command === '-v' || command === 'version') {
-        return runVersion(args, reporter, parsed.lang);
+        return (await import('./commands/version.js')).runVersion(args, reporter, parsed.lang);
     }
     if (command === 'init') {
-        return runInit(args, reporter, parsed.lang);
+        return (await import('./commands/init.js')).runInit(args, reporter, parsed.lang);
     }
     if (command === 'adapters') {
-        return runAdapters(args, reporter, parsed.lang);
+        return (await import('./commands/adapters.js')).runAdapters(args, reporter, parsed.lang);
     }
     if (command === 'check') {
-        return runCheck(args, reporter, parsed.lang);
+        return (await import('./commands/check.js')).runCheck(args, reporter, parsed.lang);
     }
     if (command === 'classify') {
-        return runClassify(args, reporter, parsed.lang);
+        return (await import('./commands/classify.js')).runClassify(args, reporter, parsed.lang);
     }
     if (command === 'contract-lint') {
-        return runContractLint(args, reporter, parsed.lang);
+        return (await import('./commands/contract-lint.js')).runContractLint(args, reporter, parsed.lang);
     }
     if (command === 'status') {
-        return runStatus(args, reporter, parsed.lang);
+        return (await import('./commands/status.js')).runStatus(args, reporter, parsed.lang);
     }
     if (command === 'update') {
-        return runUpdate(args, reporter, parsed.lang);
+        return (await import('./commands/update.js')).runUpdate(args, reporter, parsed.lang);
+    }
+    if (command === 'upgrade') {
+        return (await import('./commands/upgrade.js')).runUpgrade(args, reporter, parsed.lang);
     }
     if (command === 'map') {
-        return runMap(args, reporter, parsed.lang);
+        return (await import('./commands/map.js')).runMap(args, reporter, parsed.lang);
     }
     if (command === 'line-endings') {
-        return runLineEndings(args, reporter, parsed.lang);
+        return (await import('./commands/line-endings.js')).runLineEndings(args, reporter, parsed.lang);
     }
     if (command === 'run') {
-        return runRun(args, reporter, parsed.lang);
+        return (await import('./commands/run.js')).runRun(args, reporter, parsed.lang);
     }
     if (command === 'context') {
-        return runContext(args, reporter, parsed.lang);
+        return (await import('./commands/context.js')).runContext(args, reporter, parsed.lang);
     }
     if (command === 'doctor') {
-        return runDoctor(args, reporter, parsed.lang);
+        return (await import('./commands/doctor.js')).runDoctor(args, reporter, parsed.lang);
     }
     if (command === 'docs') {
-        return runDocs(args, reporter, parsed.lang);
+        return (await import('./commands/docs.js')).runDocs(args, reporter, parsed.lang);
     }
     if (command === 'handoff') {
-        return runHandoff(args, reporter, parsed.lang);
+        return (await import('./commands/handoff.js')).runHandoff(args, reporter, parsed.lang);
     }
     if (command === 'index') {
-        return runIndex(args, reporter, parsed.lang);
+        return (await import('./commands/index.js')).runIndex(args, reporter, parsed.lang);
     }
     if (command === 'search') {
-        return runSearch(args, reporter, parsed.lang);
+        return (await import('./commands/search.js')).runSearch(args, reporter, parsed.lang);
     }
     if (command === 'dashboard') {
-        return runDashboard(args, reporter, parsed.lang);
+        return (await import('./commands/dashboard.js')).runDashboard(args, reporter, parsed.lang);
     }
     if (command === 'version-sources') {
-        return runVersionSources(args, reporter, parsed.lang);
+        return (await import('./commands/version-sources.js')).runVersionSources(args, reporter, parsed.lang);
     }
     if (command === 'verify') {
-        return runVerify(args, reporter, parsed.lang);
+        return (await import('./commands/verify.js')).runVerify(args, reporter, parsed.lang);
     }
     if (command === 'explain') {
-        return runExplain(args, reporter, parsed.lang);
+        return (await import('./commands/explain.js')).runExplain(args, reporter, parsed.lang);
     }
     if (command === 'impact') {
-        return runImpact(args, reporter, parsed.lang);
+        return (await import('./commands/impact.js')).runImpact(args, reporter, parsed.lang);
     }
     if (command === 'help') {
-        return runHelp(args, reporter, parsed.lang);
+        return (await import('./commands/help.js')).runHelp(args, reporter, parsed.lang);
     }
     reporter.stderr(renderCliError(t(parsed.lang, 'cli.error.unknownCommand', { command }), 'mf --help', parsed.lang));
     reporter.stdout(getTopLevelHelp(parsed.lang));

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

@@ -34,6 +34,11 @@ export const COMMAND_DEFINITIONS = [
         usage: 'mf update',
         summaryKey: 'command.update.summary',
     },
+    {
+        id: 'upgrade',
+        usage: 'mf upgrade',
+        summaryKey: 'command.upgrade.summary',
+    },
     {
         id: 'map',
         usage: 'mf map',

package/dist/cli/lib/dashboard-html.js

@@ -1078,7 +1078,7 @@ function renderVerificationPanel() {
 				if (!entry) continue;
 				const effects = document.createElement("div");
 				effects.className = "verification-files";
-				effects.textContent = message("dashboard.verification.effects") + ": " + entry.effects.map((effect) => effect.mode + " " + effect.path + " [" + effect.lock + "]").join(", ");
+				effects.textContent = message("dashboard.verification.effects") + ": " + entry.effects.map((effect) => effect.mode + " " + (effect.path || effect.lock) + " [" + effect.lock + "]").join(", ");
 				details.appendChild(effects);
 				if (entry.conflicts.length > 0) {
 					const conflicts = document.createElement("div");

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

@@ -8,7 +8,7 @@ import { readTomlFile } from './toml.js';
 import { collectSourceAnchorIndexRecords, } from '../../core/source-anchor-status.js';
 import { normalizeCommandEffects } from '../../core/command-effects.js';
 import { listChangeClassificationRuleDescriptors } from '../../core/change-classification.js';
-const LOCAL_INDEX_SCHEMA_VERSION = '12';
+const LOCAL_INDEX_SCHEMA_VERSION = '13';
 const LOCAL_INDEX_PARSER_VERSION = '1';
 const DEFAULT_DATABASE_RELATIVE_PATH = '.mustflow/cache/mustflow.sqlite';
 const LOCAL_INDEX_CONTENT_MODE = 'metadata_and_snippets';
@@ -752,10 +752,9 @@ CREATE TABLE command_effects (
   source TEXT NOT NULL,
   access TEXT NOT NULL,
   mode TEXT NOT NULL,
-  path TEXT NOT NULL,
+  path TEXT,
   lock TEXT NOT NULL,
-  concurrency TEXT NOT NULL,
-  PRIMARY KEY (intent, source, access, mode, path, lock, concurrency)
+  concurrency TEXT NOT NULL
 );
 
 CREATE VIEW command_write_locks AS
@@ -1014,7 +1013,7 @@ function populateSearchTables(database, capabilities, documents, skills, skillRo
     }
     for (const intent of commandIntents) {
         const effects = intent.effects
-            .flatMap((effect) => [effect.lock, effect.path, effect.mode, effect.access, effect.concurrency])
+            .flatMap((effect) => [effect.lock, effect.path ?? '', effect.mode, effect.access, effect.concurrency])
             .join(' ');
         insertSearchNgrams(database, 'command_intent', intent.name, [intent.name, intent.status, intent.lifecycle ?? '', intent.runPolicy ?? '', intent.description ?? '', effects], 'command_intent');
         if (capabilities.backend === SEARCH_BACKEND_FTS5) {
@@ -1123,7 +1122,9 @@ function populateDatabase(database, capabilities, documents, skills, skillRoutes
         insertDocumentTerm(database, '.mustflow/config/commands.toml', intent.description, 'command_description');
         for (const effect of intent.effects) {
             database.run('INSERT INTO command_effects (intent, source, access, mode, path, lock, concurrency) VALUES (?, ?, ?, ?, ?, ?, ?)', [effect.intent, effect.source, effect.access, effect.mode, effect.path, effect.lock, effect.concurrency]);
-            insertDocumentTerm(database, '.mustflow/config/commands.toml', effect.path, 'command_effect_path');
+            if (effect.path !== null) {
+                insertDocumentTerm(database, '.mustflow/config/commands.toml', effect.path, 'command_effect_path');
+            }
             insertDocumentTerm(database, '.mustflow/config/commands.toml', effect.lock, 'command_effect_lock');
             insertDocumentTerm(database, '.mustflow/config/commands.toml', effect.mode, 'command_effect_mode');
         }
@@ -1624,7 +1625,7 @@ function getCommandEffects(database, intent) {
         source: toSearchString(row.source),
         access: toSearchString(row.access),
         mode: toSearchString(row.mode),
-        path: toSearchString(row.path),
+        path: row.path === null || row.path === undefined ? null : toSearchString(row.path),
         lock: toSearchString(row.lock),
         concurrency: toSearchString(row.concurrency),
     }));
@@ -1826,7 +1827,9 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                 const description = toSearchString(row.description);
                 const effects = getCommandEffects(database, name);
                 const effectLocks = [...new Set(effects.map((effect) => effect.lock))].sort((left, right) => left.localeCompare(right));
-                const effectPaths = [...new Set(effects.map((effect) => effect.path))].sort((left, right) => left.localeCompare(right));
+                const effectPaths = [
+                    ...new Set(effects.map((effect) => effect.path).filter((effectPath) => effectPath !== null)),
+                ].sort((left, right) => left.localeCompare(right));
                 const effectModes = [...new Set(effects.map((effect) => effect.mode))].sort((left, right) => left.localeCompare(right));
                 const primaryFields = [name];
                 const secondaryFields = [status, lifecycle, runPolicy, description, ...effectLocks, ...effectPaths, ...effectModes];

package/dist/cli/lib/reporter.js

@@ -5,4 +5,10 @@ export const consoleReporter = {
     stderr(message) {
         console.error(message);
     },
+    writeStdout(chunk) {
+        process.stdout.write(chunk);
+    },
+    writeStderr(chunk) {
+        process.stderr.write(chunk);
+    },
 };

package/dist/cli/lib/run-plan.js

@@ -26,6 +26,17 @@ function getRelativeProjectPath(projectRoot, targetPath) {
     const relativePath = path.relative(projectRoot, targetPath);
     return relativePath.length > 0 ? toPosixPath(relativePath) : '.';
 }
+function normalizeTestTargets(values) {
+    return [
+        ...new Set((values ?? [])
+            .map((value) => value.trim().replace(/\\/g, '/'))
+            .filter((value) => value.length > 0 && !path.posix.isAbsolute(value) && !path.win32.isAbsolute(value))
+            .filter((value) => value.split('/').every((segment) => segment.length > 0 && segment !== '.' && segment !== '..'))),
+    ].sort((left, right) => left.localeCompare(right));
+}
+function commandAcceptsTestTargets(intent) {
+    return isRecord(intent.selection) && intent.selection.accepts_test_targets === true;
+}
 function shouldUseShellForArgvExecutable(executablePath) {
     return process.platform === 'win32' && executablePath.toLowerCase().endsWith('.cmd');
 }
@@ -83,6 +94,7 @@ function readRunIntentMetadata(contract, intent) {
         destructive: readBoolean(intent, 'destructive'),
         envPolicy: env.policy,
         envAllowlist: env.allowlist,
+        testTargets: [],
     };
 }
 function createBlockedRunPlan(contract, intentName, intent, eligibility, reasonCode, detail) {
@@ -114,9 +126,10 @@ function createBlockedRunPlan(contract, intentName, intent, eligibility, reasonC
         destructive: metadata?.destructive,
         envPolicy: metadata?.envPolicy ?? null,
         envAllowlist: metadata?.envAllowlist ?? [],
+        testTargets: [],
     };
 }
-export function createRunPlan(projectRoot, contract, intentName) {
+export function createRunPlan(projectRoot, contract, intentName, options = {}) {
     const rawIntent = contract.intents[intentName];
     const eligibility = evaluateCommandIntentEligibility(intentName, rawIntent);
     if (!isRecord(rawIntent)) {
@@ -133,6 +146,8 @@ export function createRunPlan(projectRoot, contract, intentName) {
     catch (error) {
         return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, 'cwd_outside_project', error instanceof Error ? error.message : String(error));
     }
+    const testTargets = commandAcceptsTestTargets(rawIntent) ? normalizeTestTargets(options.testTargets) : [];
+    const commandArgv = metadata.commandArgv && testTargets.length > 0 ? [...metadata.commandArgv, ...testTargets] : metadata.commandArgv;
     if (!metadata.timeoutSeconds || !metadata.mode) {
         return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, !metadata.timeoutSeconds ? 'missing_timeout' : 'missing_command_source', !metadata.timeoutSeconds ? 'Intent timeout_seconds is missing or invalid.' : 'Intent does not define argv or shell cmd.');
     }
@@ -153,16 +168,17 @@ export function createRunPlan(projectRoot, contract, intentName) {
         timeoutSeconds: metadata.timeoutSeconds,
         maxOutputBytes: metadata.maxOutputBytes,
         successExitCodes: metadata.successExitCodes,
-        commandArgv: metadata.commandArgv,
+        commandArgv,
         shellCommand: metadata.shellCommand,
         mode: metadata.mode,
-        argvCommand: metadata.commandArgv ? resolveArgvCommand(rawIntent, metadata.commandArgv) : undefined,
+        argvCommand: commandArgv ? resolveArgvCommand(rawIntent, commandArgv) : undefined,
         writes: metadata.writes,
         effects: metadata.effects,
         network: metadata.network,
         destructive: metadata.destructive,
         envPolicy: metadata.envPolicy,
         envAllowlist: metadata.envAllowlist,
+        testTargets,
     };
 }
 export function createRunPreview(plan, previewMode) {
@@ -195,6 +211,7 @@ export function createRunPreview(plan, previewMode) {
         destructive: plan.destructive,
         env_policy: plan.envPolicy,
         env_allowlist: plan.envAllowlist,
+        test_targets: plan.testTargets,
         success_exit_codes: plan.successExitCodes,
     };
 }

package/dist/cli/lib/validation.js

@@ -4,7 +4,7 @@ import { isRecord } from './command-contract.js';
 import { validateCommandContractConfig, validateCommandContractStrictDefaults, } from '../../core/command-contract-validation.js';
 import { ALLOWED_RETENTION_ON_LIMIT, ALLOWED_RETENTION_STORES, DEFAULT_RETENTION_LIMITS, readNestedRetentionTable, readRetentionTable, resolveRetentionLimits, } from '../../core/retention-policy.js';
 import { formatManagedMarkdownLabel, getManagedMarkdownExpectation, } from '../../core/authority-resolution.js';
-import { SKILL_INDEX_ROUTE_COLUMN_COUNT, SKILL_INDEX_ROUTE_COLUMNS, SKILL_INDEX_SKILL_PATH_COLUMN_INDEX, findSkillIndexRoutePathColumn, parseSkillIndexRoutes, readBacktickValues, } from '../../core/skill-route-alignment.js';
+import { SKILL_INDEX_ROUTE_COLUMN_COUNT, SKILL_INDEX_ROUTE_COLUMNS, SKILL_INDEX_SKILL_PATH_COLUMN_INDEX, findSkillRouteConflictWarnings, findSkillIndexRoutePathColumn, parseSkillIndexRoutes, readBacktickValues, } from '../../core/skill-route-alignment.js';
 import { validateTemplateVersionSync } from '../../core/release-version-validation.js';
 import { validateSourceAnchorsInProject } from '../../core/source-anchor-validation.js';
 import { listFilesRecursive, toPosixPath } from './filesystem.js';
@@ -30,6 +30,7 @@ const REQUIRED_SKILL_SECTION_IDS = [
     'output-format',
 ];
 const SKILL_SECTION_MARKER_PATTERN = /^<!--\s*mustflow-section:\s*([a-z][a-z0-9-]*)\s*-->\s*\r?\n##\s+.+$/gimu;
+const TEST_SELECTION_CONFIG_PATH = '.mustflow/config/test-selection.toml';
 const REQUIRED_FILES = [
     'AGENTS.md',
     '.mustflow/config/mustflow.toml',
@@ -99,6 +100,22 @@ const FORBIDDEN_VERIFICATION_SELECTION_AUTHORITY_FIELDS = [
     'destructive',
 ];
 const ALLOWED_VERIFICATION_SELECTION_STRATEGIES = new Set(['risk_based', 'targeted', 'full']);
+const ALLOWED_TEST_SELECTION_RISKS = new Set(['low', 'medium', 'high', 'release_sensitive', 'security_sensitive']);
+const FORBIDDEN_TEST_SELECTION_COMMAND_AUTHORITY_FIELDS = [
+    'argv',
+    'cmd',
+    'command',
+    'commands',
+    'command_intents',
+    'destructive',
+    'intents',
+    'lifecycle',
+    'network',
+    'required_after',
+    'run_policy',
+    'status',
+    'writes',
+];
 const TEST_AUTHORING_BOOLEAN_FIELDS = ['prefer_existing_tests', 'require_new_test_rationale'];
 const ALLOWED_TEST_AUTHORING_POLICIES = new Set(TEST_AUTHORING_POLICIES);
 const ALLOWED_TESTING_POLICIES = new Set(['behavior_contract']);
@@ -1079,6 +1096,9 @@ function validateSkillIndexRoutes(projectRoot, commandsToml, skillFiles, issues)
     const routedSkillPaths = new Set();
     const expectedSkillPaths = new Set(skillFiles.map((relativePath) => `.mustflow/skills/${relativePath}`));
     const seenSkillPaths = new Set();
+    for (const warning of findSkillRouteConflictWarnings(skillRoutes)) {
+        pushStrictWarning(issues, `${SKILL_INDEX_PATH} ${warning}`);
+    }
     for (const route of skillRoutes) {
         if (!route.skillPath.startsWith('.mustflow/skills/') || !route.skillPath.endsWith('/SKILL.md')) {
             pushStrictIssue(issues, `${SKILL_INDEX_PATH} route "${route.skillPath}" must point to .mustflow/skills/<name>/SKILL.md`);
@@ -1223,6 +1243,94 @@ function validateStrictVerificationSelectionAuthority(preferencesToml, issues) {
         }
     }
 }
+function validateNoTestSelectionCommandAuthorityFields(label, table, issues) {
+    for (const field of FORBIDDEN_TEST_SELECTION_COMMAND_AUTHORITY_FIELDS) {
+        if (hasOwn(table, field)) {
+            pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label}.${field} cannot define command authority; use .mustflow/config/commands.toml`);
+        }
+    }
+}
+function validateTestSelectionIntentReference(value, label, commandsToml, issues) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} must be a command intent name`);
+        return;
+    }
+    if (!isDeclaredCommandIntent(commandsToml, value)) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} references unknown command intent "${value}"`);
+        return;
+    }
+    if (!isConfiguredCommandIntent(commandsToml, value)) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} references command intent "${value}" that is not configured`);
+    }
+}
+function validateTestSelectionRule(rule, index, commandsToml, issues) {
+    const label = `rules[${index}]`;
+    if (!isRecord(rule)) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} must be a TOML table`);
+        return;
+    }
+    validateNoTestSelectionCommandAuthorityFields(label, rule, issues);
+    validateRequiredStringField(rule, 'id', `${TEST_SELECTION_CONFIG_PATH} ${label}.id`, issues);
+    validateRequiredStringField(rule, 'reason', `${TEST_SELECTION_CONFIG_PATH} ${label}.reason`, issues);
+    validateRequiredStringField(rule, 'risk', `${TEST_SELECTION_CONFIG_PATH} ${label}.risk`, issues);
+    validateAllowedStringField(rule, 'risk', `${TEST_SELECTION_CONFIG_PATH} ${label}.risk`, ALLOWED_TEST_SELECTION_RISKS, issues);
+    const match = validateNestedTable(rule, 'match', `${TEST_SELECTION_CONFIG_PATH} ${label}.match`, issues);
+    if (!hasOwn(rule, 'match')) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} must define match`);
+    }
+    if (match) {
+        validateNoTestSelectionCommandAuthorityFields(`${label}.match`, match, issues);
+        validatePathArrayField(match, 'paths', `${TEST_SELECTION_CONFIG_PATH} ${label}.match.paths`, issues);
+        validateStringArrayField(match, 'surfaces', `${TEST_SELECTION_CONFIG_PATH} ${label}.match.surfaces`, issues);
+        if (!hasOwn(match, 'paths')) {
+            pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label}.match must define paths`);
+        }
+        if (!hasOwn(match, 'surfaces')) {
+            pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label}.match must define surfaces`);
+        }
+    }
+    const select = validateNestedTable(rule, 'select', `${TEST_SELECTION_CONFIG_PATH} ${label}.select`, issues);
+    if (!hasOwn(rule, 'select')) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} must define select`);
+    }
+    if (select) {
+        validateNoTestSelectionCommandAuthorityFields(`${label}.select`, select, issues);
+        validateTestSelectionIntentReference(select.intent, `${label}.select.intent`, commandsToml, issues);
+        validateTestSelectionIntentReference(select.fallback_intent, `${label}.select.fallback_intent`, commandsToml, issues);
+        validatePathArrayField(select, 'test_targets', `${TEST_SELECTION_CONFIG_PATH} ${label}.select.test_targets`, issues);
+    }
+}
+function validateStrictTestSelectionConfig(projectRoot, commandsToml, issues) {
+    const configPath = path.join(projectRoot, ...TEST_SELECTION_CONFIG_PATH.split('/'));
+    if (!existsSync(configPath)) {
+        return;
+    }
+    let parsed;
+    try {
+        parsed = readTomlFile(configPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        pushStrictIssue(issues, `Invalid TOML in ${TEST_SELECTION_CONFIG_PATH}: ${message}`);
+        return;
+    }
+    if (!isRecord(parsed)) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} must contain a TOML table`);
+        return;
+    }
+    validateNoTestSelectionCommandAuthorityFields('root', parsed, issues);
+    validateRequiredStringField(parsed, 'schema_version', `${TEST_SELECTION_CONFIG_PATH}.schema_version`, issues);
+    if (parsed.schema_version !== '1') {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH}.schema_version must be "1"`);
+    }
+    if (!Array.isArray(parsed.rules) || parsed.rules.length === 0) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} must define [[rules]]`);
+        return;
+    }
+    for (const [index, rule] of parsed.rules.entries()) {
+        validateTestSelectionRule(rule, index, commandsToml, issues);
+    }
+}
 function validateStrictCandidateContractModelConfigs(projectRoot, issues) {
     for (const model of getContractModelDefinitions()) {
         const configPath = path.join(projectRoot, ...model.filePath.split('/'));
@@ -1619,6 +1727,7 @@ function validateStrict(projectRoot, parsed, issues) {
     validateStrictReleaseVersioningAuthority(parsed.preferencesToml, issues);
     validateStrictVerificationSelectionAuthority(parsed.preferencesToml, issues);
     validateStrictCandidateContractModelConfigs(projectRoot, issues);
+    validateStrictTestSelectionConfig(projectRoot, parsed.commandsToml, issues);
     validateStrictVersionSources(projectRoot, parsed.preferencesToml, parsed.versioningToml, issues);
     validateStrictTemplateVersionSync(projectRoot, parsed.preferencesToml, issues);
     validateStrictManagedMarkdownIdentities(projectRoot, issues);

package/dist/core/bounded-output.js

@@ -0,0 +1,38 @@
+export class BoundedOutputBuffer {
+    #maxTailBytes;
+    #chunks = [];
+    #tailBytes = 0;
+    #bytes = 0;
+    constructor(maxTailBytes) {
+        this.#maxTailBytes = Math.max(0, maxTailBytes);
+    }
+    append(chunk) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
+        this.#bytes += buffer.byteLength;
+        if (this.#maxTailBytes === 0 || buffer.byteLength === 0) {
+            return;
+        }
+        this.#chunks.push(buffer);
+        this.#tailBytes += buffer.byteLength;
+        while (this.#tailBytes > this.#maxTailBytes && this.#chunks.length > 0) {
+            const first = this.#chunks[0];
+            const overflow = this.#tailBytes - this.#maxTailBytes;
+            if (!first) {
+                break;
+            }
+            if (first.byteLength <= overflow) {
+                this.#chunks.shift();
+                this.#tailBytes -= first.byteLength;
+                continue;
+            }
+            this.#chunks[0] = first.subarray(overflow);
+            this.#tailBytes -= overflow;
+        }
+    }
+    toSnapshot() {
+        return {
+            bytes: this.#bytes,
+            tail: Buffer.concat(this.#chunks, this.#tailBytes).toString('utf8'),
+        };
+    }
+}