mustflow 1.18.16 → 1.31.0

package/dist/core/change-verification.js

@@ -1,6 +1,9 @@
+import { isRecord, readStringArray } from './config-loading.js';
 import { CHANGE_CLASSIFICATION_SURFACE_AUTHORITY, createPathTarget, } from './surface-decision-model.js';
-import { createVerificationPlan, } from './verification-plan.js';
+import { classifyVerificationCandidate, createVerificationPlan, } from './verification-plan.js';
+import { createVerificationDecisionGraph, } from './verification-decision-graph.js';
 import { createVerificationSchedule, } from './verification-scheduler.js';
+import { createProjectTestSelectionPlan, } from './test-selection.js';
 export const CHANGE_VERIFICATION_SCHEMA_VERSION = '1';
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
@@ -8,6 +11,21 @@ function uniqueSorted(values) {
 function uniqueUpdatePolicies(values) {
     return uniqueSorted([...values].filter((value) => value !== 'not_applicable'));
 }
+const DECLARED_ESCALATION_SIGNALS = [
+    'public_api',
+    'release',
+    'package',
+    'packaging',
+    'security',
+    'selector',
+    'command contract',
+    'classifier',
+    'classification',
+    'verification planner',
+    'verification planning',
+    'machine-readable output contract',
+    'JSON schema',
+];
 function classificationsForReason(classificationReport, reason) {
     return classificationReport.classifications.filter((classification) => classification.surface.validationReasons.includes(reason));
 }
@@ -39,13 +57,209 @@ function createVerificationRequirement(classificationReport, reason) {
         source: 'change_classification',
     };
 }
-function toChangeVerificationCandidate(reason, candidate) {
+function candidateKey(reason, intent) {
+    return `${reason}\0${intent}`;
+}
+function readIntentRelationList(commandContract, intent, key) {
+    const rawIntent = commandContract.intents[intent];
+    if (!isRecord(rawIntent) || !isRecord(rawIntent.relations)) {
+        return [];
+    }
+    return readStringArray(rawIntent.relations, key) ?? [];
+}
+function readIntentSelectionList(commandContract, intent, key) {
+    const rawIntent = commandContract.intents[intent];
+    if (!isRecord(rawIntent) || !isRecord(rawIntent.selection)) {
+        return [];
+    }
+    return readStringArray(rawIntent.selection, key) ?? [];
+}
+function readIntentCostExpectedSeconds(commandContract, intent) {
+    const rawIntent = commandContract.intents[intent];
+    if (!isRecord(rawIntent) || !isRecord(rawIntent.cost)) {
+        return null;
+    }
+    const expectedSeconds = rawIntent.cost.expected_seconds;
+    return Number.isInteger(expectedSeconds) && Number(expectedSeconds) >= 0 ? Number(expectedSeconds) : null;
+}
+function intentCoverageSignature(commandContract, intent) {
+    const rawIntent = commandContract.intents[intent];
+    if (!isRecord(rawIntent) || !isRecord(rawIntent.covers)) {
+        return null;
+    }
+    const signature = {
+        contracts: uniqueSorted(readStringArray(rawIntent.covers, 'contracts') ?? []),
+        paths: uniqueSorted(readStringArray(rawIntent.covers, 'paths') ?? []),
+        reasons: uniqueSorted(readStringArray(rawIntent.covers, 'reasons') ?? []),
+        surfaces: uniqueSorted(readStringArray(rawIntent.covers, 'surfaces') ?? []),
+    };
+    if (signature.contracts.length === 0 &&
+        signature.paths.length === 0 &&
+        signature.reasons.length === 0 &&
+        signature.surfaces.length === 0) {
+        return null;
+    }
+    return JSON.stringify(signature);
+}
+function fallbackIntentsForCandidate(commandContract, candidate) {
+    if (candidate.intent.length === 0 || candidate.status === 'runnable') {
+        return [];
+    }
+    return uniqueSorted([
+        ...readIntentSelectionList(commandContract, candidate.intent, 'fallback_intents'),
+        ...readIntentSelectionList(commandContract, candidate.intent, 'escalate_to'),
+        ...readIntentRelationList(commandContract, candidate.intent, 'escalate_to'),
+    ]);
+}
+function escalationIntentsForCandidate(commandContract, candidate) {
+    if (candidate.intent.length === 0) {
+        return [];
+    }
+    return uniqueSorted([
+        ...readIntentSelectionList(commandContract, candidate.intent, 'escalate_to'),
+        ...readIntentRelationList(commandContract, candidate.intent, 'escalate_to'),
+    ]);
+}
+function expandCandidatesWithDeclaredFallbacks(commandContract, candidates) {
+    const hasRunnableCandidate = candidates.some((candidate) => candidate.status === 'runnable' && candidate.intent.length > 0);
+    if (hasRunnableCandidate) {
+        return candidates;
+    }
+    const existingIntents = new Set(candidates.map((candidate) => candidate.intent).filter((intent) => intent.length > 0));
+    const fallbackIntents = uniqueSorted(candidates.flatMap((candidate) => fallbackIntentsForCandidate(commandContract, candidate))).filter((intent) => !existingIntents.has(intent));
+    if (fallbackIntents.length === 0) {
+        return candidates;
+    }
+    return [
+        ...candidates,
+        ...fallbackIntents.map((intent) => {
+            const fallback = classifyVerificationCandidate(intent, commandContract.intents[intent]);
+            return {
+                ...fallback,
+                detail: fallback.status === 'runnable' ? 'Declared fallback for unavailable verification intent.' : fallback.detail,
+            };
+        }),
+    ];
+}
+function requirementNeedsDeclaredEscalation(requirement) {
+    if (requirement.surfaces.length > 1) {
+        return true;
+    }
+    const signalText = [
+        requirement.reason,
+        ...requirement.affectedContracts,
+        ...requirement.driftChecks,
+        ...requirement.surfaces,
+    ].join('\n').toLowerCase();
+    return DECLARED_ESCALATION_SIGNALS.some((signal) => signalText.includes(signal.toLowerCase()));
+}
+function expandCandidatesWithDeclaredEscalations(commandContract, requirement, candidates) {
+    if (!requirementNeedsDeclaredEscalation(requirement)) {
+        return candidates;
+    }
+    const existingIntents = new Set(candidates.map((candidate) => candidate.intent).filter((intent) => intent.length > 0));
+    const escalationIntents = uniqueSorted(candidates.flatMap((candidate) => escalationIntentsForCandidate(commandContract, candidate))).filter((intent) => !existingIntents.has(intent));
+    if (escalationIntents.length === 0) {
+        return candidates;
+    }
+    return [
+        ...candidates,
+        ...escalationIntents.map((intent) => {
+            const escalation = classifyVerificationCandidate(intent, commandContract.intents[intent]);
+            return {
+                ...escalation,
+                detail: escalation.status === 'runnable'
+                    ? 'Declared escalation for a high-risk verification requirement.'
+                    : escalation.detail,
+            };
+        }),
+    ];
+}
+function intentExplicitlySubsumes(commandContract, broaderIntent, narrowerIntent) {
+    return readIntentRelationList(commandContract, broaderIntent, 'subsumes').includes(narrowerIntent);
+}
+function intentExplicitlySubsumedBy(commandContract, narrowerIntent, broaderIntent) {
+    return readIntentRelationList(commandContract, narrowerIntent, 'subsumed_by').includes(broaderIntent);
+}
+function intentRequiresCompanion(commandContract, intent) {
+    return readIntentRelationList(commandContract, intent, 'requires_with').length > 0;
+}
+function intentIsExplicitlySubsumed(commandContract, narrowerIntent, broaderIntent) {
+    return (intentExplicitlySubsumedBy(commandContract, narrowerIntent, broaderIntent) ||
+        intentExplicitlySubsumes(commandContract, broaderIntent, narrowerIntent));
+}
+function selectVerificationCandidates(commandContract, candidates) {
+    const runnableCandidates = candidates.filter((candidate) => candidate.status === 'runnable' && candidate.intent.length > 0);
+    const selectedIntents = new Set(runnableCandidates.map((candidate) => candidate.intent));
+    for (const candidate of runnableCandidates) {
+        const isSubsumed = runnableCandidates.some((other) => other.intent !== candidate.intent && intentIsExplicitlySubsumed(commandContract, candidate.intent, other.intent));
+        if (isSubsumed) {
+            selectedIntents.delete(candidate.intent);
+        }
+    }
+    const costComparableCandidates = runnableCandidates.filter((candidate) => selectedIntents.has(candidate.intent) &&
+        !intentRequiresCompanion(commandContract, candidate.intent) &&
+        intentCoverageSignature(commandContract, candidate.intent) !== null &&
+        readIntentCostExpectedSeconds(commandContract, candidate.intent) !== null);
+    const costComparableGroups = new Map();
+    for (const candidate of costComparableCandidates) {
+        const signature = intentCoverageSignature(commandContract, candidate.intent);
+        if (signature === null) {
+            continue;
+        }
+        costComparableGroups.set(signature, [...(costComparableGroups.get(signature) ?? []), candidate]);
+    }
+    for (const group of costComparableGroups.values()) {
+        if (group.length < 2) {
+            continue;
+        }
+        const costs = group.map((candidate) => readIntentCostExpectedSeconds(commandContract, candidate.intent));
+        if (costs.some((cost) => cost === null)) {
+            continue;
+        }
+        const minCost = Math.min(...costs);
+        const winners = group.filter((candidate) => readIntentCostExpectedSeconds(commandContract, candidate.intent) === minCost);
+        if (winners.length !== 1) {
+            continue;
+        }
+        for (const candidate of group) {
+            if (candidate.intent !== winners[0]?.intent) {
+                selectedIntents.delete(candidate.intent);
+            }
+        }
+    }
+    if (selectedIntents.size === 0 && runnableCandidates.length > 0) {
+        return runnableCandidates;
+    }
+    return runnableCandidates.filter((candidate) => selectedIntents.has(candidate.intent));
+}
+function uniqueVerificationCandidates(candidates) {
+    const byIntent = new Map();
+    for (const candidate of candidates) {
+        if (candidate.intent.length === 0 || byIntent.has(candidate.intent)) {
+            continue;
+        }
+        byIntent.set(candidate.intent, candidate);
+    }
+    return [...byIntent.values()].sort((left, right) => left.intent.localeCompare(right.intent));
+}
+function toChangeVerificationCandidate(reason, candidate, selectedCandidateKeys) {
+    const hasIntent = candidate.intent.length > 0;
+    const isMissingIntent = !hasIntent || candidate.reason === 'no_matching_intents';
+    const isEligible = hasIntent && candidate.status === 'runnable';
     return {
         reason,
         intent: candidate.intent.length > 0 ? candidate.intent : null,
         status: candidate.status,
         skipReason: candidate.reason,
         detail: candidate.detail,
+        candidateState: isMissingIntent ? 'gap' : 'candidate',
+        eligibilityState: isMissingIntent ? 'missing' : isEligible ? 'eligible' : 'ineligible',
+        selectionState: isEligible
+            ? selectedCandidateKeys.has(candidateKey(reason, candidate.intent))
+                ? 'selected'
+                : 'not_selected'
+            : 'not_applicable',
     };
 }
 function gapForRequirement(requirement, candidates) {
@@ -61,9 +275,34 @@ function gapForRequirement(requirement, candidates) {
     };
 }
 export function createChangeVerificationReport(classificationReport, commandContract, projectRoot) {
+    const testSelectionPlan = createProjectTestSelectionPlan(projectRoot, classificationReport, commandContract);
     const requirements = classificationReport.summary.validationReasons.map((reason) => createVerificationRequirement(classificationReport, reason));
-    const candidatePlans = requirements.flatMap((requirement) => createVerificationPlan(commandContract, requirement.reason).candidates);
-    const candidates = requirements.flatMap((requirement) => createVerificationPlan(commandContract, requirement.reason).candidates.map((candidate) => toChangeVerificationCandidate(requirement.reason, candidate)));
+    const plans = requirements.map((requirement) => ({
+        requirement,
+        candidates: expandCandidatesWithDeclaredEscalations(commandContract, requirement, expandCandidatesWithDeclaredFallbacks(commandContract, createVerificationPlan(commandContract, requirement.reason).candidates)),
+    }));
+    const plansWithProjectTestSelection = plans.map((plan) => {
+        const additionalCandidates = testSelectionPlan.candidates
+            .filter((candidate) => candidate.reason === plan.requirement.reason)
+            .filter((candidate) => !plan.candidates.some((existing) => existing.intent === candidate.candidate.intent))
+            .map((candidate) => candidate.candidate);
+        return additionalCandidates.length > 0
+            ? { ...plan, candidates: [...plan.candidates, ...additionalCandidates] }
+            : plan;
+    });
+    const selectedPlans = plansWithProjectTestSelection.map((plan) => ({
+        ...plan,
+        selectedCandidates: uniqueVerificationCandidates([
+            ...selectVerificationCandidates(commandContract, plan.candidates),
+            ...testSelectionPlan.selectedCandidates
+                .filter((candidate) => candidate.reason === plan.requirement.reason)
+                .map((candidate) => candidate.candidate),
+        ]),
+    }));
+    const selectedCandidatePlans = selectedPlans.flatMap((plan) => plan.selectedCandidates);
+    const selectedCandidateKeys = new Set(selectedPlans.flatMap((plan) => plan.selectedCandidates.map((candidate) => candidateKey(plan.requirement.reason, candidate.intent))));
+    const schedule = createVerificationSchedule(projectRoot, commandContract, selectedCandidatePlans);
+    const candidates = plansWithProjectTestSelection.flatMap((plan) => plan.candidates.map((candidate) => toChangeVerificationCandidate(plan.requirement.reason, candidate, selectedCandidateKeys)));
     const gaps = requirements
         .map((requirement) => gapForRequirement(requirement, candidates))
         .filter((gap) => gap !== null);
@@ -75,6 +314,8 @@ export function createChangeVerificationReport(classificationReport, commandCont
         requirements,
         candidates,
         gaps,
-        schedule: createVerificationSchedule(projectRoot, commandContract, candidatePlans),
+        schedule,
+        decision_graph: createVerificationDecisionGraph(commandContract, requirements, candidates, gaps, schedule),
+        test_selection: testSelectionPlan.report,
     };
 }

package/dist/core/check-issues.js

@@ -20,11 +20,21 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.release.template_version_intentionally_unchanged', /^Strict warning: templates\/default\/manifest\.toml version "[^"]+" is older than package\.json version "[^"]+"; this is allowed only when the installed template surface is unchanged$/u],
     ['mustflow.preferences.release_versioning_contract_authority', /^Strict: \[preferences\.release\.versioning\]\.[a-z_]+ cannot define version sources or release authority; use \.mustflow\/config\/versioning\.toml or \.mustflow\/config\/commands\.toml$/u],
     ['mustflow.preferences.verification_selection_command_authority', /^Strict: \[preferences\.verification\.selection\]\.[a-z_]+ cannot define command authority; use \.mustflow\/config\/commands\.toml$/u],
+    ['mustflow.contract_model.deferred_policy', /^Strict: \.mustflow\/config\/policy\.toml is deferred; use narrow candidate contract files instead$/u],
+    ['mustflow.contract_model.command_authority_field', /^Strict: \.mustflow\/config\/(?:changes|surfaces)\.toml .+ cannot define command authority; use \.mustflow\/config\/commands\.toml$/u],
+    ['mustflow.contract_model.invalid_match_kind', /^Strict: \.mustflow\/config\/(?:changes|surfaces)\.toml rules\[\d+\]\.match\.kind must be "exact", "prefix", or "glob"; regular expressions are deferred$/u],
+    ['mustflow.contract_model.invalid_shape', /^Strict: \.mustflow\/config\/(?:changes|surfaces)\.toml .+(?:must be|must define|is not allowed)/u],
+    ['mustflow.test_selection.command_authority_field', /^Strict: \.mustflow\/config\/test-selection\.toml .+ cannot define command authority; use \.mustflow\/config\/commands\.toml$/u],
+    ['mustflow.test_selection.unknown_command_intent', /^Strict: \.mustflow\/config\/test-selection\.toml .+ references unknown command intent "[^"]+"$/u],
+    ['mustflow.test_selection.invalid_shape', /^Strict: \.mustflow\/config\/test-selection\.toml .+(?:must be|must define|is not allowed|references command intent "[^"]+" that is not configured)/u],
     ['mustflow.skill.procedure_only', /^Strict: \.mustflow\/skills\/[^/]+\/SKILL\.md metadata\.mustflow_kind must be "procedure"$/u],
     ['mustflow.skill.raw_command_block', /^Strict: \.mustflow\/skills\/[^/]+\/SKILL\.md contains a raw shell command block; reference command intents instead$/u],
     ['mustflow.skill.command_permission_claim', /^Strict: \.mustflow\/skills\/[^/]+\/SKILL\.md claims command execution permission; keep permissions in \.mustflow\/config\/commands\.toml$/u],
     ['mustflow.skill.unknown_command_intent', /^Strict: \.mustflow\/skills\/[^/]+\/SKILL\.md metadata\.command_intents references unknown command intent "[^"]+"$/u],
     ['mustflow.skill.index_route_unknown_command_intent', /^Strict: \.mustflow\/skills\/INDEX\.md route \.mustflow\/skills\/[^/]+\/SKILL\.md references command intent "[^"]+" not declared by the skill frontmatter$/u],
+    ['mustflow.skill.index_route_broad_catch_all', /^Strict warning: \.mustflow\/skills\/INDEX\.md \.mustflow\/skills\/[^/]+\/SKILL\.md route uses broad catch-all trigger ".+" that can shadow narrower skills$/u],
+    ['mustflow.skill.index_route_identical_trigger', /^Strict warning: \.mustflow\/skills\/INDEX\.md \.mustflow\/skills\/[^/]+\/SKILL\.md and \.mustflow\/skills\/[^/]+\/SKILL\.md have identical skill route trigger text$/u],
+    ['mustflow.skill.index_route_duplicate_surface', /^Strict warning: \.mustflow\/skills\/INDEX\.md \.mustflow\/skills\/[^/]+\/SKILL\.md and \.mustflow\/skills\/[^/]+\/SKILL\.md have duplicate edit scope, risk, and expected output route surface$/u],
     ['mustflow.skill.resource_unknown_command_intent', /^Strict: \.mustflow\/skills\/[^/]+\/resources\.toml script [^\s]+ references unknown command intent "[^"]+"$/u],
     ['mustflow.source_anchor.invalid_format', /^Strict: source anchor .+ has invalid format:/u],
     ['mustflow.source_anchor.duplicate_id', /^Strict: source anchor id "[^"]+" is duplicated:/u],

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

@@ -1,4 +1,5 @@
 import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, } from './config-loading.js';
+import { COMMAND_ENV_POLICIES } from './command-env.js';
 import { COMMAND_EFFECT_CONCURRENCY, COMMAND_EFFECT_MODES, COMMAND_EFFECT_TYPES, validateCommandEffectLockWarnings, validateCommandEffects, } from './command-effects.js';
 import { commandIntentHasBlockedShellBackgroundPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
 function commandContractIssue(message) {
@@ -31,6 +32,15 @@ function validateStringField(table, key, label, issues) {
         issues.push(commandContractIssue(`${label} must be a string`));
     }
 }
+function validateStringArrayField(table, key, label, issues) {
+    if (!hasOwn(table, key)) {
+        return;
+    }
+    const value = table[key];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || entry.trim().length === 0)) {
+        issues.push(commandContractIssue(`${label} must be a string array`));
+    }
+}
 function validatePositiveIntegerField(table, key, label, issues) {
     if (hasOwn(table, key) && !isPositiveInteger(table[key])) {
         issues.push(commandContractIssue(`${label} must be a positive integer`));
@@ -57,6 +67,8 @@ function validateCommandDefaults(commandsToml, issues) {
     validateStringField(defaults, 'default_cwd', '[commands.defaults].default_cwd', issues);
     validateStringField(defaults, 'stdin', '[commands.defaults].stdin', 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);
     validatePositiveIntegerField(defaults, 'default_timeout_seconds', '[commands.defaults].default_timeout_seconds', issues);
     validatePositiveIntegerField(defaults, 'max_output_bytes', '[commands.defaults].max_output_bytes', issues);
     validatePositiveIntegerField(defaults, 'kill_after_seconds', '[commands.defaults].kill_after_seconds', issues);
@@ -108,6 +120,25 @@ function validateCommandIntentEffects(intentName, intent, issues) {
         }
     }
 }
+function validateCommandIntentSelection(intentName, intent, issues) {
+    if (!hasOwn(intent, 'selection')) {
+        return;
+    }
+    if (!isRecord(intent.selection)) {
+        issues.push(commandContractIssue(`[commands.intents.${intentName}.selection] must be a TOML table`));
+        return;
+    }
+    const selection = intent.selection;
+    validateStringField(selection, 'coverage_level', `[commands.intents.${intentName}.selection].coverage_level`, issues);
+    validateStringField(selection, 'coverage_confidence', `[commands.intents.${intentName}.selection].coverage_confidence`, issues);
+    validateStringField(selection, 'accepts_changed_files', `[commands.intents.${intentName}.selection].accepts_changed_files`, issues);
+    validateStringArrayField(selection, 'fallback_intents', `[commands.intents.${intentName}.selection].fallback_intents`, issues);
+    validateStringArrayField(selection, 'escalate_to', `[commands.intents.${intentName}.selection].escalate_to`, issues);
+    validateBooleanField(selection, 'accepts_test_targets', `[commands.intents.${intentName}.selection].accepts_test_targets`, issues);
+    if (selection.accepts_test_targets === true && intent.status === 'configured' && !Array.isArray(intent.argv)) {
+        issues.push(commandContractIssue(`[commands.intents.${intentName}.selection].accepts_test_targets requires argv command mode`));
+    }
+}
 function validateCommandIntent(intentName, intent, issues) {
     if (!commandIntentNameIsSafe(intentName)) {
         issues.push(commandContractIssue(`Intent ${intentName} name must contain only letters, numbers, underscores, and hyphens`));
@@ -115,6 +146,9 @@ function validateCommandIntent(intentName, intent, issues) {
     validateStringField(intent, 'status', `[commands.intents.${intentName}].status`, issues);
     validateAllowedStringField(intent, 'lifecycle', `[commands.intents.${intentName}].lifecycle`, COMMAND_LIFECYCLES, issues);
     validateAllowedStringField(intent, 'run_policy', `[commands.intents.${intentName}].run_policy`, COMMAND_RUN_POLICIES, issues);
+    validateAllowedStringField(intent, 'env_policy', `[commands.intents.${intentName}].env_policy`, COMMAND_ENV_POLICIES, issues);
+    validateStringArrayField(intent, 'env_allowlist', `[commands.intents.${intentName}].env_allowlist`, issues);
+    validateCommandIntentSelection(intentName, intent, issues);
     if (intent.status !== 'configured') {
         return;
     }

package/dist/core/command-cwd.js

@@ -1,12 +1,24 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
+function normalizeForContainment(value) {
+    const normalized = path.resolve(value);
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+function isInsideOrEqual(parent, child) {
+    const normalizedParent = normalizeForContainment(parent);
+    const normalizedChild = normalizeForContainment(child);
+    return normalizedChild === normalizedParent || normalizedChild.startsWith(`${normalizedParent}${path.sep}`);
+}
 export function resolveSafeProjectCwd(projectRoot, rawCwd) {
     const cwd = rawCwd ?? '.';
     const resolved = path.resolve(projectRoot, cwd);
-    const root = path.resolve(projectRoot);
-    const resolvedLower = resolved.toLowerCase();
-    const rootLower = root.toLowerCase();
-    if (resolvedLower !== rootLower && !resolvedLower.startsWith(`${rootLower}${path.sep}`)) {
-        throw new Error(`Intent cwd must stay inside the current root: ${cwd}`);
+    const rootRealPath = realpathSync.native(projectRoot);
+    if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+        throw new Error(`Intent cwd must stay inside the current root and resolve to an existing directory: ${cwd}`);
+    }
+    const cwdRealPath = realpathSync.native(resolved);
+    if (!isInsideOrEqual(rootRealPath, cwdRealPath)) {
+        throw new Error(`Intent cwd must stay inside the current root and resolve to an existing directory: ${cwd}`);
     }
-    return resolved;
+    return cwdRealPath;
 }

package/dist/core/command-effects.js

@@ -70,6 +70,19 @@ function normalizeDeclaredEffect(projectRoot, commandContract, intentName, inten
     if (!lock && paths.length === 0) {
         throw new Error(`Command effect for intent ${intentName} must define path, paths, or lock`);
     }
+    if (paths.length === 0) {
+        return [
+            {
+                intent: intentName,
+                source: 'effects',
+                access,
+                mode,
+                path: null,
+                lock: lock,
+                concurrency,
+            },
+        ];
+    }
     return paths.map((rawPath) => {
         const normalizedPath = validateEffectPath(projectRoot, intent, rawPath);
         return {

package/dist/core/command-env.js

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { readString, readStringArray } from './config-loading.js';
+export const COMMAND_ENV_POLICIES = new Set(['inherit', 'minimal', 'allowlist']);
+export const DEFAULT_COMMAND_ENV_POLICY = 'inherit';
+const BASE_MINIMAL_ENV_KEYS = [
+    'CI',
+    'COLORTERM',
+    'COMSPEC',
+    'ComSpec',
+    'FORCE_COLOR',
+    'HOME',
+    'HOMEDRIVE',
+    'HOMEPATH',
+    'LANG',
+    'LC_ALL',
+    'NO_COLOR',
+    'PATHEXT',
+    'Path',
+    'SystemRoot',
+    'TEMP',
+    'TERM',
+    'TMP',
+    'TMPDIR',
+    'USERPROFILE',
+    'WINDIR',
+    'windir',
+];
+function getPathEnvKey(env) {
+    return Object.keys(env).find((key) => key.toLowerCase() === 'path') ?? 'PATH';
+}
+function sameResolvedPath(left, right) {
+    const resolvedLeft = path.resolve(left);
+    const resolvedRight = path.resolve(right);
+    return process.platform === 'win32'
+        ? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase()
+        : resolvedLeft === resolvedRight;
+}
+function uniqueEnvNames(values) {
+    return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))].sort((left, right) => left.localeCompare(right));
+}
+function readEnvPolicy(table) {
+    if (!table) {
+        return undefined;
+    }
+    const value = readString(table, 'env_policy');
+    return value && COMMAND_ENV_POLICIES.has(value) ? value : undefined;
+}
+function readEnvAllowlist(table) {
+    return table ? (readStringArray(table, 'env_allowlist') ?? []) : [];
+}
+function pickEnv(source, names) {
+    const output = {};
+    for (const name of names) {
+        const value = source[name];
+        if (value !== undefined) {
+            output[name] = value;
+        }
+    }
+    return output;
+}
+function removeProjectLocalBinFromPath(env, projectRoot) {
+    const pathKey = getPathEnvKey(env);
+    const currentPath = env[pathKey];
+    if (!currentPath) {
+        return env;
+    }
+    const localBinPath = path.join(projectRoot, 'node_modules', '.bin');
+    env[pathKey] = currentPath
+        .split(path.delimiter)
+        .filter((entry) => entry.length > 0 && !sameResolvedPath(entry, localBinPath))
+        .join(path.delimiter);
+    return env;
+}
+export function resolveCommandEnv(contract, intent) {
+    const policy = readEnvPolicy(intent) ?? readEnvPolicy(contract.defaults) ?? DEFAULT_COMMAND_ENV_POLICY;
+    const allowlist = policy === 'allowlist'
+        ? uniqueEnvNames([...readEnvAllowlist(contract.defaults), ...readEnvAllowlist(intent)])
+        : [];
+    return {
+        policy,
+        allowlist,
+    };
+}
+export function createCommandEnv(projectRoot, resolution, sourceEnv = process.env) {
+    const pathKey = getPathEnvKey(sourceEnv);
+    const minimalKeys = uniqueEnvNames([...BASE_MINIMAL_ENV_KEYS, pathKey]);
+    const env = resolution.policy === 'inherit'
+        ? { ...sourceEnv }
+        : pickEnv(sourceEnv, resolution.policy === 'allowlist' ? [...minimalKeys, ...resolution.allowlist] : minimalKeys);
+    return removeProjectLocalBinFromPath(env, projectRoot);
+}