mustflow 2.27.0 → 2.29.0

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

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { isRecord } from '../command-contract.js';
 import { readMustflowTomlFile } from '../toml.js';
 import { REQUIRED_FILES, } from './constants.js';
+import { TECHNOLOGY_CONFIG_RELATIVE_PATH } from '../../../core/technology-preferences.js';
 import { VERSIONING_CONFIG_PATH } from '../../../core/version-sources.js';
 export function hasOwn(table, key) {
     return Object.prototype.hasOwnProperty.call(table, key);
@@ -34,6 +35,7 @@ export function validateToml(projectRoot, issues) {
         '.mustflow/config/mustflow.toml',
         '.mustflow/config/commands.toml',
         '.mustflow/config/preferences.toml',
+        TECHNOLOGY_CONFIG_RELATIVE_PATH,
         VERSIONING_CONFIG_PATH,
     ]) {
         const filePath = path.join(projectRoot, relativePath);
@@ -55,6 +57,9 @@ export function validateToml(projectRoot, issues) {
             if (relativePath.endsWith('preferences.toml')) {
                 parsedFiles.preferencesToml = parsed;
             }
+            if (relativePath.endsWith('technology.toml')) {
+                parsedFiles.technologyToml = parsed;
+            }
             if (relativePath.endsWith('versioning.toml')) {
                 parsedFiles.versioningToml = parsed;
             }

package/dist/core/command-contract-validation.js

@@ -1,7 +1,6 @@
-import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, readStringArray, } from './config-loading.js';
-import { COMMAND_ENV_POLICIES, DEFAULT_COMMAND_ENV_POLICY } from './command-env.js';
+import { COMMAND_ENV_POLICIES, DEFAULT_COMMAND_ENV_POLICY, PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY, normalizeCommandExecutableName, readProjectLocalBinBareExecutableAllowlist, resolveAllowedProjectLocalBinExecutable, } from './command-env.js';
 import { COMMAND_EFFECT_CONCURRENCY, COMMAND_EFFECT_MODES, COMMAND_EFFECT_TYPES, validateCommandEffectLockWarnings, validateCommandEffects, } from './command-effects.js';
 import { COMMAND_PRECONDITION_KINDS } from './command-preconditions.js';
 import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
@@ -13,6 +12,8 @@ const COMMAND_ARGV_PLACEHOLDER_PATTERN = /^\{([a-z][a-z0-9_]*)\}$/u;
 const COMMAND_ARGV_MIXED_PLACEHOLDER_PATTERN = /\{([a-z][a-z0-9_]*)\}/u;
 const WINDOWS_RESERVED_PATH_SEGMENTS = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/iu;
 const SAFE_PATH_EXTENSION_PATTERN = /^\.[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const ALLOW_ENV_INHERITANCE_RISKS_KEY = 'allow_env_inheritance_risks';
+const ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY = 'allow_long_running_command_patterns';
 function commandContractIssue(message, id) {
     return id ? { id, message } : { message };
 }
@@ -257,6 +258,7 @@ function validateCommandDefaults(commandsToml, issues) {
     validateStringField(defaults, 'on_timeout', '[commands.defaults].on_timeout', issues);
     validateAllowedStringField(defaults, 'env_policy', '[commands.defaults].env_policy', COMMAND_ENV_POLICIES, issues);
     validateStringArrayField(defaults, 'env_allowlist', '[commands.defaults].env_allowlist', issues);
+    validateStringArrayField(defaults, PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY, `[commands.defaults].${PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY}`, issues);
     validatePositiveIntegerField(defaults, 'default_timeout_seconds', '[commands.defaults].default_timeout_seconds', issues);
     validateMaxOutputBytesField(defaults, 'max_output_bytes', '[commands.defaults].max_output_bytes', issues);
     validatePositiveIntegerField(defaults, 'kill_after_seconds', '[commands.defaults].kill_after_seconds', issues);
@@ -337,6 +339,8 @@ function validateCommandIntent(intentName, intent, allIntents, issues) {
     validateAllowedStringField(intent, 'env_policy', `[commands.intents.${intentName}].env_policy`, COMMAND_ENV_POLICIES, issues);
     validateBooleanField(intent, 'allow_shell', `[commands.intents.${intentName}].allow_shell`, issues);
     validateStringArrayField(intent, 'env_allowlist', `[commands.intents.${intentName}].env_allowlist`, issues);
+    validateBooleanField(intent, ALLOW_ENV_INHERITANCE_RISKS_KEY, `[commands.intents.${intentName}].${ALLOW_ENV_INHERITANCE_RISKS_KEY}`, issues);
+    validateBooleanField(intent, ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY, `[commands.intents.${intentName}].${ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY}`, issues);
     validateMaxOutputBytesField(intent, 'max_output_bytes', `[commands.intents.${intentName}].max_output_bytes`, issues);
     validatePositiveIntegerField(intent, 'kill_after_seconds', `[commands.intents.${intentName}].kill_after_seconds`, issues);
     validateCommandIntentSelection(intentName, intent, issues);
@@ -375,7 +379,7 @@ function validateCommandIntent(intentName, intent, allIntents, issues) {
     if (blockedCommandPattern?.code === 'shell_background_pattern') {
         issues.push(commandContractIssue(`Shell intent ${intentName} contains a blocked long-running or background pattern`, 'mustflow.command_contract.shell_background_pattern'));
     }
-    if (blockedCommandPattern?.code === 'long_running_command_pattern') {
+    if (blockedCommandPattern?.code === 'long_running_command_pattern' && intent[ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY] !== true) {
         issues.push(commandContractIssue(`Intent ${intentName} contains a blocked long-running or background command pattern`, 'mustflow.command_contract.long_running_command_pattern'));
     }
     if (hasOwn(intent, 'success_exit_codes')) {
@@ -419,6 +423,9 @@ export function findCommandEnvInheritanceWarnings(commandsToml) {
         if (envPolicy.policy !== 'inherit') {
             continue;
         }
+        if (intent[ALLOW_ENV_INHERITANCE_RISKS_KEY] === true) {
+            continue;
+        }
         const reasons = readCommandEnvInheritanceRiskReasons(intent);
         warnings.push({
             intentName,
@@ -465,21 +472,14 @@ function validateCommandEnvInheritanceWarnings(commandsToml) {
     return issues;
 }
 function projectLocalBinExecutableExists(projectRoot, executable) {
-    const localBinPath = path.join(projectRoot, 'node_modules', '.bin');
-    const executableName = path.basename(executable).replace(/\.(?:cmd|exe|ps1)$/iu, '');
-    const candidates = [
-        executableName,
-        `${executableName}.cmd`,
-        `${executableName}.exe`,
-        `${executableName}.ps1`,
-    ];
-    return candidates.some((candidate) => existsSync(path.join(localBinPath, candidate)));
+    return resolveAllowedProjectLocalBinExecutable(projectRoot, executable, new Set([normalizeCommandExecutableName(executable)])) !== null;
 }
 function validateProjectLocalBinWarnings(projectRoot, commandsToml) {
     const issues = [];
     if (!isRecord(commandsToml?.intents)) {
         return issues;
     }
+    const allowedBareExecutables = readProjectLocalBinBareExecutableAllowlist(commandsToml);
     for (const [intentName, intent] of Object.entries(commandsToml.intents)) {
         if (!isRecord(intent)) {
             continue;
@@ -492,6 +492,9 @@ function validateProjectLocalBinWarnings(projectRoot, commandsToml) {
         if (!executable || executable.includes('/') || executable.includes('\\')) {
             continue;
         }
+        if (allowedBareExecutables.has(normalizeCommandExecutableName(executable))) {
+            continue;
+        }
         if (!projectLocalBinExecutableExists(projectRoot, executable)) {
             continue;
         }

package/dist/core/command-env.js

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { readString, readStringArray } from './config-loading.js';
 export const COMMAND_ENV_POLICIES = new Set(['inherit', 'minimal', 'allowlist']);
@@ -25,6 +26,8 @@ const BASE_MINIMAL_ENV_KEYS = [
     'WINDIR',
     'windir',
 ];
+export const PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY = 'allow_project_local_bin_bare_executables';
+export const DEFAULT_PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST = new Set(['mf', 'mustflow']);
 function getPathEnvKey(env) {
     return Object.keys(env).find((key) => key.toLowerCase() === 'path') ?? 'PATH';
 }
@@ -48,6 +51,46 @@ function readEnvPolicy(table) {
 function readEnvAllowlist(table) {
     return table ? (readStringArray(table, 'env_allowlist') ?? []) : [];
 }
+export function normalizeCommandExecutableName(executable) {
+    return path.basename(executable).replace(/\.(?:cmd|exe|ps1)$/iu, '').toLowerCase();
+}
+export function readProjectLocalBinBareExecutableAllowlist(contractOrCommands) {
+    const defaults = contractOrCommands && typeof contractOrCommands === 'object' && 'defaults' in contractOrCommands
+        ? contractOrCommands.defaults
+        : undefined;
+    const configuredAllowlist = defaults && typeof defaults === 'object'
+        ? defaults[PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY]
+        : undefined;
+    if (!Array.isArray(configuredAllowlist)) {
+        return DEFAULT_PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST;
+    }
+    return new Set(configuredAllowlist
+        .filter((entry) => typeof entry === 'string' && entry.trim().length > 0)
+        .map((entry) => normalizeCommandExecutableName(entry)));
+}
+export function resolveAllowedProjectLocalBinExecutable(projectRoot, executable, allowlist) {
+    if (executable.includes('/') || executable.includes('\\')) {
+        return null;
+    }
+    const executableName = normalizeCommandExecutableName(executable);
+    if (!allowlist.has(executableName)) {
+        return null;
+    }
+    const localBinPath = path.join(projectRoot, 'node_modules', '.bin');
+    const candidates = [
+        executableName,
+        `${executableName}.cmd`,
+        `${executableName}.exe`,
+        `${executableName}.ps1`,
+    ];
+    for (const candidate of candidates) {
+        const candidatePath = path.join(localBinPath, candidate);
+        if (existsSync(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return null;
+}
 function pickEnv(source, names) {
     const output = {};
     for (const name of names) {

package/dist/core/command-intent-eligibility.js

@@ -1,5 +1,6 @@
 import { isRecord, readString } from './config-loading.js';
 import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
+const ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY = 'allow_long_running_command_patterns';
 export const COMMAND_INTENT_INELIGIBILITY_CODES = [
     'intent_not_table',
     'status_not_configured',
@@ -83,7 +84,7 @@ export function evaluateCommandIntentEligibility(intentName, rawIntent) {
             detail: blockedPattern.detail,
         };
     }
-    if (blockedPattern?.code === 'long_running_command_pattern') {
+    if (blockedPattern?.code === 'long_running_command_pattern' && rawIntent[ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY] !== true) {
         return {
             ok: false,
             code: 'blocked_long_running_command_pattern',

package/dist/core/contract-lint.js

@@ -58,6 +58,7 @@ const AGENT_WORKFLOW_PATH = '.mustflow/docs/agent-workflow.md';
 const PACKAGE_SCRIPT_RUNNERS = new Set(['bun', 'npm', 'pnpm', 'yarn']);
 const MAKEFILE_CANDIDATES = ['Makefile', 'makefile'];
 const JUSTFILE_CANDIDATES = ['justfile', 'Justfile'];
+const ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY = 'allow_long_running_command_patterns';
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
@@ -333,7 +334,7 @@ function lintIntent(name, value, issues) {
     if (blockedCommandPattern?.code === 'shell_background_pattern') {
         pushIssue(issues, 'error', 'shell_background_pattern', name, `Shell intent ${name} contains a blocked long-running or background pattern.`);
     }
-    if (blockedCommandPattern?.code === 'long_running_command_pattern') {
+    if (blockedCommandPattern?.code === 'long_running_command_pattern' && value[ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY] !== true) {
         pushIssue(issues, 'error', 'long_running_command_pattern', name, `Intent ${name} contains a blocked long-running or background command pattern.`);
     }
     if (!successExitCodesAreValid(value)) {

package/dist/core/technology-preferences.js

@@ -0,0 +1,189 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord } from './config-loading.js';
+export const TECHNOLOGY_CONFIG_RELATIVE_PATH = '.mustflow/config/technology.toml';
+export const TECHNOLOGY_SCHEMA_VERSION = '1';
+export const TECHNOLOGY_AUTHORITY = 'hint';
+export const TECHNOLOGY_GUIDANCE = [
+    'Technology preferences are hints only; inspect the current repository stack before proposing changes.',
+    'They do not authorize dependency installation, framework migration, command execution, or ignoring existing style.',
+    'When adding packages, verify package reality and use the configured command contract or direct user approval.',
+];
+export const TECHNOLOGY_KINDS = [
+    'language',
+    'runtime',
+    'framework',
+    'library',
+    'tool',
+    'service',
+    'platform',
+];
+export const TECHNOLOGY_STATUSES = ['preferred', 'allowed', 'avoid'];
+function isTechnologyKind(value) {
+    return TECHNOLOGY_KINDS.includes(value);
+}
+function isTechnologyStatus(value) {
+    return TECHNOLOGY_STATUSES.includes(value);
+}
+function readString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const entries = value
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return entries.length === value.length ? entries : null;
+}
+function normalizeStringList(values) {
+    return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
+}
+export function normalizeTechnologyName(value) {
+    return value.trim().replace(/\s+/gu, ' ');
+}
+export function normalizeTechnologyKey(value) {
+    return normalizeTechnologyName(value).toLowerCase();
+}
+function slug(value) {
+    const normalized = normalizeTechnologyKey(value)
+        .replace(/[^a-z0-9]+/gu, '-')
+        .replace(/^-+|-+$/gu, '');
+    return normalized.length > 0 ? normalized : 'item';
+}
+export function createTechnologyPreferenceId(kind, name, scope) {
+    const scopePart = scope.length > 0 ? `${slug(scope[0])}.` : '';
+    return `${kind}.${scopePart}${slug(name)}`;
+}
+function normalizePreference(raw, index, issues) {
+    const rawKind = readString(raw.kind);
+    if (!rawKind || !isTechnologyKind(rawKind)) {
+        issues.push(`[preferences.${index}].kind must be one of ${TECHNOLOGY_KINDS.join(', ')}`);
+        return null;
+    }
+    const rawName = readString(raw.name);
+    if (!rawName) {
+        issues.push(`[preferences.${index}].name must be a non-empty string`);
+        return null;
+    }
+    const rawStatus = readString(raw.status) ?? 'preferred';
+    if (!isTechnologyStatus(rawStatus)) {
+        issues.push(`[preferences.${index}].status must be preferred, allowed, or avoid`);
+        return null;
+    }
+    const rawAuthority = readString(raw.authority) ?? TECHNOLOGY_AUTHORITY;
+    if (rawAuthority !== TECHNOLOGY_AUTHORITY) {
+        issues.push(`[preferences.${index}].authority must be "${TECHNOLOGY_AUTHORITY}"`);
+        return null;
+    }
+    const scope = normalizeStringList(readStringArray(raw.scope) ?? []);
+    const packages = normalizeStringList(readStringArray(raw.packages) ?? []);
+    const constraints = normalizeStringList(readStringArray(raw.constraints) ?? []);
+    const id = readString(raw.id) ?? createTechnologyPreferenceId(rawKind, rawName, scope);
+    return {
+        id,
+        kind: rawKind,
+        name: normalizeTechnologyName(rawName),
+        status: rawStatus,
+        authority: TECHNOLOGY_AUTHORITY,
+        scope,
+        ecosystem: readString(raw.ecosystem),
+        packages,
+        rationale: readString(raw.rationale),
+        constraints,
+    };
+}
+export function normalizeTechnologyPreferencesTable(table, exists) {
+    const issues = [];
+    const schemaVersion = table ? readString(table.schema_version) ?? '' : TECHNOLOGY_SCHEMA_VERSION;
+    if (table && schemaVersion !== TECHNOLOGY_SCHEMA_VERSION) {
+        issues.push(`[technology].schema_version must be "${TECHNOLOGY_SCHEMA_VERSION}"`);
+    }
+    const rawPreferences = table?.preferences;
+    const preferences = [];
+    if (rawPreferences !== undefined) {
+        if (!Array.isArray(rawPreferences)) {
+            issues.push('[technology].preferences must be an array of tables');
+        }
+        else {
+            for (const [index, rawPreference] of rawPreferences.entries()) {
+                if (!isRecord(rawPreference)) {
+                    issues.push(`[preferences.${index}] must be a TOML table`);
+                    continue;
+                }
+                const preference = normalizePreference(rawPreference, index, issues);
+                if (preference) {
+                    preferences.push(preference);
+                }
+            }
+        }
+    }
+    const seenIds = new Set();
+    for (const preference of preferences) {
+        if (seenIds.has(preference.id)) {
+            issues.push(`[technology].preferences contains duplicate id "${preference.id}"`);
+            continue;
+        }
+        seenIds.add(preference.id);
+    }
+    return {
+        path: TECHNOLOGY_CONFIG_RELATIVE_PATH,
+        exists,
+        schema_version: schemaVersion || TECHNOLOGY_SCHEMA_VERSION,
+        authority: TECHNOLOGY_AUTHORITY,
+        guidance: TECHNOLOGY_GUIDANCE,
+        preferences,
+        issues,
+    };
+}
+export function technologyPreferenceMatches(preference, filters) {
+    if (filters.kind && preference.kind !== filters.kind) {
+        return false;
+    }
+    if (filters.status && preference.status !== filters.status) {
+        return false;
+    }
+    if (filters.scope) {
+        const expectedScope = normalizeTechnologyKey(filters.scope);
+        if (!preference.scope.some((scope) => normalizeTechnologyKey(scope) === expectedScope)) {
+            return false;
+        }
+    }
+    return true;
+}
+function quoteTomlString(value) {
+    return JSON.stringify(value);
+}
+function renderStringArray(values) {
+    return `[${values.map((value) => quoteTomlString(value)).join(', ')}]`;
+}
+export function serializeTechnologyPreferences(preferences) {
+    const lines = [
+        `schema_version = ${quoteTomlString(TECHNOLOGY_SCHEMA_VERSION)}`,
+        '',
+        '# Repository-local technology preferences for agents.',
+        '# Entries here are low-authority hints. They do not authorize dependency installation,',
+        '# migration, command execution, or ignoring current project style.',
+    ];
+    for (const preference of [...preferences].sort((left, right) => left.id.localeCompare(right.id))) {
+        lines.push('', '[[preferences]]', `id = ${quoteTomlString(preference.id)}`, `kind = ${quoteTomlString(preference.kind)}`, `name = ${quoteTomlString(preference.name)}`, `status = ${quoteTomlString(preference.status)}`, `authority = ${quoteTomlString(TECHNOLOGY_AUTHORITY)}`, `scope = ${renderStringArray(preference.scope)}`);
+        if (preference.ecosystem) {
+            lines.push(`ecosystem = ${quoteTomlString(preference.ecosystem)}`);
+        }
+        if (preference.packages.length > 0) {
+            lines.push(`packages = ${renderStringArray(preference.packages)}`);
+        }
+        if (preference.rationale) {
+            lines.push(`rationale = ${quoteTomlString(preference.rationale)}`);
+        }
+        if (preference.constraints.length > 0) {
+            lines.push(`constraints = ${renderStringArray(preference.constraints)}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function technologyConfigExists(projectRoot) {
+    return existsSync(path.join(projectRoot, ...TECHNOLOGY_CONFIG_RELATIVE_PATH.split('/')));
+}

package/package.json

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

package/schemas/commands.schema.json

@@ -36,7 +36,8 @@
         "on_timeout": { "type": "string" },
         "kill_after_seconds": { "type": "integer" },
         "env_policy": { "$ref": "#/$defs/envPolicy" },
-        "env_allowlist": { "$ref": "#/$defs/stringArray" }
+        "env_allowlist": { "$ref": "#/$defs/stringArray" },
+        "allow_project_local_bin_bare_executables": { "$ref": "#/$defs/stringArray" }
       }
     },
     "intents": {
@@ -172,6 +173,7 @@
         },
         "cmd": { "type": "string" },
         "allow_shell": { "type": "boolean" },
+        "allow_long_running_command_patterns": { "type": "boolean" },
         "cwd": { "type": "string" },
         "timeout_seconds": { "type": "integer" },
         "kill_after_seconds": { "type": "integer" },
@@ -185,6 +187,7 @@
         },
         "env_policy": { "$ref": "#/$defs/envPolicy" },
         "env_allowlist": { "$ref": "#/$defs/stringArray" },
+        "allow_env_inheritance_risks": { "type": "boolean" },
         "manual_start_hint": { "type": "string" },
         "health_check_url": { "type": "string" },
         "stop_instruction": { "type": "string" },

package/schemas/context-report.schema.json

@@ -47,6 +47,7 @@
           "items": { "$ref": "#/$defs/pathContext" }
         },
         "command_contract": { "$ref": "#/$defs/commandContractContext" },
+        "technology_preferences": { "$ref": "#/$defs/technologyPreferencesContext" },
         "effective_policy": { "$ref": "#/$defs/effectivePolicy" },
         "state_policy": { "$ref": "#/$defs/statePolicy" },
         "blocked_actions": {
@@ -149,6 +150,66 @@
         }
       }
     },
+    "technologyPreference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "name",
+        "status",
+        "authority",
+        "scope",
+        "ecosystem",
+        "packages",
+        "rationale",
+        "constraints"
+      ],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "enum": ["language", "runtime", "framework", "library", "tool", "service", "platform"] },
+        "name": { "type": "string" },
+        "status": { "enum": ["preferred", "allowed", "avoid"] },
+        "authority": { "const": "hint" },
+        "scope": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "ecosystem": { "type": ["string", "null"] },
+        "packages": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "rationale": { "type": ["string", "null"] },
+        "constraints": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "technologyPreferencesContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "exists", "authority", "guidance", "count", "preferences", "issues"],
+      "properties": {
+        "path": { "type": "string" },
+        "exists": { "type": "boolean" },
+        "authority": { "const": "hint" },
+        "guidance": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "count": { "type": "integer", "minimum": 0 },
+        "preferences": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/technologyPreference" }
+        },
+        "issues": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
     "effectivePolicy": {
       "type": "object",
       "additionalProperties": false,

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

@@ -18,6 +18,7 @@ on_timeout = "terminate_process_tree"
 kill_after_seconds = 5
 env_policy = "minimal"
 env_allowlist = []
+allow_project_local_bin_bare_executables = ["mf", "mustflow"]
 
 [resources.local_index_cache]
 description = "Generated mustflow SQLite local index under .mustflow/cache/."

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

@@ -7,6 +7,7 @@ read_order = [
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/commands.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/skills/INDEX.md",
 ]
 optional_read_order = [
@@ -20,6 +21,7 @@ repository_map = "REPO_MAP.md"
 skill_index = ".mustflow/skills/INDEX.md"
 command_contract = ".mustflow/config/commands.toml"
 workflow_preferences = ".mustflow/config/preferences.toml"
+technology_preferences = ".mustflow/config/technology.toml"
 workflow_reference = ".mustflow/docs/agent-workflow.md"
 context_index = ".mustflow/context/INDEX.md"
 project_context = ".mustflow/context/PROJECT.md"
@@ -35,6 +37,7 @@ anchor_files = [
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/commands.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/skills/INDEX.md",
   "README.md",
   "PROJECT.md",
@@ -98,6 +101,7 @@ command_contract = true
 skills = true
 repo_map = "generated_optional"
 preferences = "optional"
+technology_preferences = "optional"
 context = "optional"
 local_index = "generated_optional"
 work_items = "disabled"
@@ -136,6 +140,7 @@ read = [
   ".mustflow/docs/agent-workflow.md",
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/commands.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/skills/INDEX.md",
 ]
 
@@ -230,6 +235,7 @@ read = [
   "AGENTS.md",
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
 ]
 
 [refresh.levels.skill]
@@ -247,6 +253,7 @@ read = [
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/commands.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/skills/INDEX.md",
 ]
 
@@ -369,6 +376,7 @@ canonical = [
   ".mustflow/config/commands.toml",
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/context/**",
   ".mustflow/docs/**",
   ".mustflow/skills/**",

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

@@ -0,0 +1,20 @@
+schema_version = "1"
+
+# Repository-local technology preferences for agents.
+# Entries here are low-authority hints. They do not authorize dependency installation,
+# migration, command execution, or ignoring current project style.
+#
+# [[preferences]]
+# id = "framework.frontend.nextjs"
+# kind = "framework"
+# name = "nextjs"
+# status = "preferred"
+# authority = "hint"
+# scope = ["frontend", "web", "react"]
+# ecosystem = "npm"
+# packages = ["next", "react", "react-dom"]
+# rationale = "Preferred React full-stack framework for product web apps."
+# constraints = [
+#   "Check existing project stack before proposing migration.",
+#   "Do not install packages without direct user approval or a configured command intent.",
+# ]