mustflow 2.22.13 → 2.22.14

package/dist/core/command-explanation.js

@@ -1,4 +1,5 @@
 import { isRecord, readPositiveInteger, readString, readStringArray, } from './config-loading.js';
+import { evaluateCommandPreconditions, } from './command-preconditions.js';
 const COMMAND_CONTRACT_SOURCE_FILES = [
     'AGENTS.md',
     '.mustflow/docs/agent-workflow.md',
@@ -36,7 +37,7 @@ function resolveCommandMode(intent) {
     }
     return 'missing';
 }
-function summarizeIntent(name, intent) {
+function summarizeIntent(name, intent, contract, projectRoot) {
     return {
         name,
         status: readString(intent, 'status') ?? null,
@@ -51,6 +52,7 @@ function summarizeIntent(name, intent) {
         destructive: readOptionalBoolean(intent, 'destructive'),
         successExitCodes: readOptionalIntegerArray(intent, 'success_exit_codes'),
         requiredAfter: readOptionalStringArray(intent, 'required_after'),
+        preconditions: projectRoot ? evaluateCommandPreconditions(projectRoot, contract, name) : [],
     };
 }
 function collectBlockingReasons(summary) {
@@ -75,7 +77,7 @@ function collectBlockingReasons(summary) {
     }
     return reasons;
 }
-export function explainCommandIntent(contract, commandName) {
+export function explainCommandIntent(contract, commandName, options = {}) {
     const intentCandidate = contract.intents[commandName];
     if (!isRecord(intentCandidate)) {
         return {
@@ -89,7 +91,7 @@ export function explainCommandIntent(contract, commandName) {
             intent: null,
         };
     }
-    const intent = summarizeIntent(commandName, intentCandidate);
+    const intent = summarizeIntent(commandName, intentCandidate, contract, options.projectRoot);
     const blockingReasons = collectBlockingReasons(intent);
     if (blockingReasons.length === 0) {
         return {

package/dist/core/command-preconditions.js

@@ -0,0 +1,261 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord, readString, readStringArray, } from './config-loading.js';
+import { evaluateCommandIntentEligibility } from './command-intent-eligibility.js';
+export const COMMAND_PRECONDITION_KINDS = new Set(['path_exists', 'artifact_freshness']);
+const IGNORED_WALK_DIRECTORIES = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    'coverage',
+    '.next',
+    '.turbo',
+    '.mustflow/state',
+    '.mustflow/cache',
+]);
+function normalizeRelativePath(value) {
+    return value.trim().replace(/\\/gu, '/').replace(/^\.\/+/u, '').replace(/\/+$/u, '') || '.';
+}
+function relativePathIsUnsafe(value) {
+    const normalized = normalizeRelativePath(value);
+    const segments = normalized.split('/').filter((segment) => segment.length > 0);
+    return (normalized.length === 0 ||
+        normalized.includes('\0') ||
+        normalized.startsWith('/') ||
+        path.win32.isAbsolute(value) ||
+        path.posix.isAbsolute(value) ||
+        segments.some((segment) => segment === '.' || segment === '..'));
+}
+function resolveProjectPath(projectRoot, relativePath) {
+    if (relativePathIsUnsafe(relativePath)) {
+        return null;
+    }
+    const resolved = path.resolve(projectRoot, ...normalizeRelativePath(relativePath).split('/'));
+    const relative = path.relative(path.resolve(projectRoot), resolved);
+    return relative.startsWith('..') || path.isAbsolute(relative) ? null : resolved;
+}
+function readPreconditionDeclarations(intent) {
+    if (!Array.isArray(intent.preconditions)) {
+        return [];
+    }
+    return intent.preconditions.filter(isRecord).map((precondition) => ({
+        kind: readString(precondition, 'kind') ?? '',
+        label: readString(precondition, 'label') ?? null,
+        path: readString(precondition, 'path') ? normalizeRelativePath(readString(precondition, 'path')) : null,
+        artifact: readString(precondition, 'artifact') ? normalizeRelativePath(readString(precondition, 'artifact')) : null,
+        sources: readStringArray(precondition, 'sources')?.map(normalizeRelativePath) ?? [],
+        satisfyIntent: readString(precondition, 'satisfy_intent') ?? null,
+    }));
+}
+function createSatisfyIntentSummary(contract, intentName) {
+    if (!intentName) {
+        return null;
+    }
+    const rawIntent = contract.intents[intentName];
+    const eligibility = evaluateCommandIntentEligibility(intentName, rawIntent);
+    return {
+        intent: intentName,
+        declared: isRecord(rawIntent),
+        runnable: eligibility.ok,
+        status: isRecord(rawIntent) ? readString(rawIntent, 'status') ?? null : null,
+        lifecycle: isRecord(rawIntent) ? readString(rawIntent, 'lifecycle') ?? null : null,
+        runPolicy: isRecord(rawIntent) ? readString(rawIntent, 'run_policy') ?? null : null,
+        detail: eligibility.detail,
+    };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+function globToRegExp(pattern) {
+    let expression = '^';
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        const next = pattern[index + 1];
+        if (character === '*' && next === '*') {
+            expression += '.*';
+            index += 1;
+            continue;
+        }
+        if (character === '*') {
+            expression += '[^/]*';
+            continue;
+        }
+        expression += escapeRegExp(character);
+    }
+    return new RegExp(`${expression}$`, 'u');
+}
+function shouldSkipDirectory(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    return IGNORED_WALK_DIRECTORIES.has(normalized) || normalized.startsWith('.mustflow/state/') || normalized.startsWith('.mustflow/cache/');
+}
+function listProjectFiles(projectRoot) {
+    const files = [];
+    function walk(directory) {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const absolute = path.join(directory, entry.name);
+            const relative = normalizeRelativePath(path.relative(projectRoot, absolute));
+            if (entry.isDirectory()) {
+                if (!shouldSkipDirectory(relative)) {
+                    walk(absolute);
+                }
+                continue;
+            }
+            if (entry.isFile()) {
+                files.push(relative);
+            }
+        }
+    }
+    walk(projectRoot);
+    return files.sort((left, right) => left.localeCompare(right));
+}
+function matchingSourceFiles(projectRoot, patterns) {
+    const safePatterns = patterns.filter((pattern) => !relativePathIsUnsafe(pattern));
+    const matchers = safePatterns.map(globToRegExp);
+    if (matchers.length === 0) {
+        return [];
+    }
+    return listProjectFiles(projectRoot).filter((filePath) => matchers.some((matcher) => matcher.test(filePath)));
+}
+function evaluatePathExists(projectRoot, declaration, satisfyIntent) {
+    const pathValue = declaration.path;
+    if (!pathValue) {
+        return {
+            kind: declaration.kind,
+            label: declaration.label,
+            status: 'invalid',
+            detail: 'path_exists precondition requires path.',
+            path: null,
+            artifact: null,
+            sources: [],
+            newestSource: null,
+            satisfyIntent,
+        };
+    }
+    const resolvedPath = resolveProjectPath(projectRoot, pathValue);
+    if (!resolvedPath) {
+        return {
+            kind: declaration.kind,
+            label: declaration.label,
+            status: 'invalid',
+            detail: `path "${pathValue}" must stay inside the project root.`,
+            path: pathValue,
+            artifact: null,
+            sources: [],
+            newestSource: null,
+            satisfyIntent,
+        };
+    }
+    const exists = existsSync(resolvedPath);
+    return {
+        kind: declaration.kind,
+        label: declaration.label,
+        status: exists ? 'satisfied' : 'missing',
+        detail: exists ? `path "${pathValue}" exists.` : `path "${pathValue}" is missing.`,
+        path: pathValue,
+        artifact: null,
+        sources: [],
+        newestSource: null,
+        satisfyIntent,
+    };
+}
+function evaluateArtifactFreshness(projectRoot, declaration, satisfyIntent) {
+    const artifact = declaration.artifact;
+    if (!artifact || declaration.sources.length === 0) {
+        return {
+            kind: declaration.kind,
+            label: declaration.label,
+            status: 'invalid',
+            detail: 'artifact_freshness precondition requires artifact and sources.',
+            path: null,
+            artifact,
+            sources: declaration.sources,
+            newestSource: null,
+            satisfyIntent,
+        };
+    }
+    const artifactPath = resolveProjectPath(projectRoot, artifact);
+    if (!artifactPath) {
+        return {
+            kind: declaration.kind,
+            label: declaration.label,
+            status: 'invalid',
+            detail: `artifact "${artifact}" must stay inside the project root.`,
+            path: null,
+            artifact,
+            sources: declaration.sources,
+            newestSource: null,
+            satisfyIntent,
+        };
+    }
+    if (!existsSync(artifactPath)) {
+        return {
+            kind: declaration.kind,
+            label: declaration.label,
+            status: 'missing',
+            detail: `artifact "${artifact}" is missing.`,
+            path: null,
+            artifact,
+            sources: declaration.sources,
+            newestSource: null,
+            satisfyIntent,
+        };
+    }
+    const sourceFiles = matchingSourceFiles(projectRoot, declaration.sources);
+    if (sourceFiles.length === 0) {
+        return {
+            kind: declaration.kind,
+            label: declaration.label,
+            status: 'unknown',
+            detail: 'no source files matched the freshness precondition.',
+            path: null,
+            artifact,
+            sources: declaration.sources,
+            newestSource: null,
+            satisfyIntent,
+        };
+    }
+    const artifactMtime = statSync(artifactPath).mtimeMs;
+    const newest = sourceFiles
+        .map((source) => ({ source, mtime: statSync(path.join(projectRoot, ...source.split('/'))).mtimeMs }))
+        .sort((left, right) => right.mtime - left.mtime)[0];
+    const stale = newest.mtime > artifactMtime;
+    return {
+        kind: declaration.kind,
+        label: declaration.label,
+        status: stale ? 'stale' : 'satisfied',
+        detail: stale
+            ? `artifact "${artifact}" is older than source "${newest.source}".`
+            : `artifact "${artifact}" is at least as new as ${sourceFiles.length} matched source file(s).`,
+        path: null,
+        artifact,
+        sources: declaration.sources,
+        newestSource: newest.source,
+        satisfyIntent,
+    };
+}
+export function evaluateCommandPreconditions(projectRoot, contract, intentName) {
+    const intent = contract.intents[intentName];
+    if (!isRecord(intent)) {
+        return [];
+    }
+    return readPreconditionDeclarations(intent).map((declaration) => {
+        const satisfyIntent = createSatisfyIntentSummary(contract, declaration.satisfyIntent);
+        if (declaration.kind === 'path_exists') {
+            return evaluatePathExists(projectRoot, declaration, satisfyIntent);
+        }
+        if (declaration.kind === 'artifact_freshness') {
+            return evaluateArtifactFreshness(projectRoot, declaration, satisfyIntent);
+        }
+        return {
+            kind: declaration.kind,
+            label: declaration.label,
+            status: 'invalid',
+            detail: `unknown precondition kind "${declaration.kind}".`,
+            path: declaration.path,
+            artifact: declaration.artifact,
+            sources: declaration.sources,
+            newestSource: null,
+            satisfyIntent,
+        };
+    });
+}

package/dist/core/skill-route-explanation.js

@@ -1,11 +1,14 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { isRecord, readMustflowOwnedTomlFile } from './config-loading.js';
 import { readUtf8FileInsideWithoutSymlinks } from './safe-filesystem.js';
 import { parseSkillIndexRoutes } from './skill-route-alignment.js';
 const MUSTFLOW_TEXT_MAX_BYTES = 1024 * 1024;
 const SKILL_INDEX_PATH = '.mustflow/skills/INDEX.md';
+const SKILL_ROUTES_METADATA_PATH = '.mustflow/skills/routes.toml';
 const SKILL_ROUTE_SOURCE_FILES = [
     SKILL_INDEX_PATH,
+    SKILL_ROUTES_METADATA_PATH,
     '.mustflow/skills/<skill>/SKILL.md',
     '.mustflow/config/commands.toml',
 ];
@@ -57,18 +60,32 @@ function skillNameFromPath(skillPath) {
     const match = /^\.mustflow\/skills\/([^/]+)\/SKILL\.md$/u.exec(skillPath);
     return match?.[1] ?? skillPath;
 }
-function targetMatchesRoute(target, route, skillContent) {
+function collectTargetMatches(target, route, skillContent) {
+    const matches = [];
     const skillName = skillNameFromPath(route.skillPath);
     const normalizedTarget = target.replace(/\\/gu, '/');
-    if (normalizedTarget === skillName || normalizedTarget === route.skillPath) {
-        return true;
+    if (normalizedTarget === skillName) {
+        matches.push(`skill_name:${skillName}`);
+    }
+    if (normalizedTarget === route.skillPath) {
+        matches.push(`skill_path:${route.skillPath}`);
     }
     if (!skillContent) {
-        return false;
+        return matches;
+    }
+    const frontmatterName = readFrontmatterScalar(skillContent, 'name');
+    const skillId = readFrontmatterScalar(skillContent, 'skill_id');
+    const mustflowDoc = readFrontmatterScalar(skillContent, 'mustflow_doc');
+    if (frontmatterName === target) {
+        matches.push(`frontmatter.name:${frontmatterName}`);
+    }
+    if (skillId === target) {
+        matches.push(`frontmatter.skill_id:${skillId}`);
     }
-    return (readFrontmatterScalar(skillContent, 'name') === target ||
-        readFrontmatterScalar(skillContent, 'skill_id') === target ||
-        readFrontmatterScalar(skillContent, 'mustflow_doc') === target);
+    if (mustflowDoc === target) {
+        matches.push(`frontmatter.mustflow_doc:${mustflowDoc}`);
+    }
+    return matches;
 }
 function routeToSummary(route, skillContent) {
     const declaredCommandIntents = skillContent ? readFrontmatterList(skillContent, 'command_intents') : [];
@@ -84,21 +101,108 @@ function routeToSummary(route, skillContent) {
         declaredCommandIntents,
     };
 }
+function readStringArrayFromTable(table, key) {
+    const value = table[key];
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+        ? value.map((entry) => entry.trim()).filter(Boolean)
+        : [];
+}
+function readSkillRouteMetadata(projectRoot) {
+    const metadata = new Map();
+    try {
+        const parsed = readMustflowOwnedTomlFile(projectRoot, SKILL_ROUTES_METADATA_PATH);
+        if (!isRecord(parsed) || !isRecord(parsed.routes)) {
+            return metadata;
+        }
+        for (const [skillName, route] of Object.entries(parsed.routes)) {
+            if (!isRecord(route)) {
+                continue;
+            }
+            const priority = Number.isInteger(route.priority) ? Number(route.priority) : 0;
+            const category = typeof route.category === 'string' ? route.category : undefined;
+            const routeType = typeof route.route_type === 'string' ? route.route_type : undefined;
+            metadata.set(skillName, {
+                category,
+                routeType,
+                priority,
+                appliesToReasons: readStringArrayFromTable(route, 'applies_to_reasons'),
+                mutuallyExclusiveWith: readStringArrayFromTable(route, 'mutually_exclusive_with'),
+            });
+        }
+    }
+    catch {
+        return metadata;
+    }
+    return metadata;
+}
+function valuesOverlap(left, right) {
+    const rightValues = new Set(right);
+    return left.some((value) => rightValues.has(value));
+}
+function findCandidateAdjuncts(skillName, routeMetadata) {
+    const current = routeMetadata.get(skillName);
+    if (!current) {
+        return [];
+    }
+    return [...routeMetadata.entries()]
+        .filter(([candidateName, candidate]) => {
+        return (candidateName !== skillName &&
+            candidate.routeType === 'adjunct' &&
+            candidate.category === current.category &&
+            !current.mutuallyExclusiveWith.includes(candidateName) &&
+            valuesOverlap(candidate.appliesToReasons, current.appliesToReasons));
+    })
+        .sort((left, right) => {
+        const priority = right[1].priority - left[1].priority;
+        return priority === 0 ? left[0].localeCompare(right[0]) : priority;
+    })
+        .map(([candidateName]) => candidateName);
+}
+function splitRequiredInput(requiredInput) {
+    return requiredInput.trim().length > 0 ? [requiredInput.trim()] : [];
+}
+function buildMatchedSkillEvidence(summary, matchedBy, candidateAdjuncts) {
+    return {
+        matchedBy,
+        requiredInputs: splitRequiredInput(summary.requiredInput),
+        missingInputs: [],
+        candidateAdjuncts,
+        unmatchedPaths: [],
+        gapNotes: [
+            'mf explain skill has no task paths or requirement text, so unmatched_paths and missing_inputs are only static route evidence.',
+        ],
+    };
+}
+function buildMissingSkillEvidence(target) {
+    return {
+        matchedBy: [],
+        requiredInputs: [],
+        missingInputs: [`No skill route matched "${target}".`],
+        candidateAdjuncts: [],
+        unmatchedPaths: [],
+        gapNotes: [
+            'No route was selected; update .mustflow/skills/INDEX.md and .mustflow/skills/routes.toml only if a repeatable procedure exists.',
+        ],
+    };
+}
 export function explainSkillRoute(projectRoot, target) {
     const indexPath = path.join(projectRoot, ...SKILL_INDEX_PATH.split('/'));
     const indexContent = existsSync(indexPath)
         ? readUtf8FileInsideWithoutSymlinks(projectRoot, indexPath, { maxBytes: MUSTFLOW_TEXT_MAX_BYTES })
         : '';
     const routes = parseSkillIndexRoutes(indexContent);
+    const routeMetadata = readSkillRouteMetadata(projectRoot);
     for (const route of routes) {
         const absoluteSkillPath = path.join(projectRoot, ...route.skillPath.split('/'));
         const skillContent = existsSync(absoluteSkillPath)
             ? readUtf8FileInsideWithoutSymlinks(projectRoot, absoluteSkillPath, { maxBytes: MUSTFLOW_TEXT_MAX_BYTES })
             : null;
-        if (!targetMatchesRoute(target, route, skillContent)) {
+        const matchedBy = collectTargetMatches(target, route, skillContent);
+        if (matchedBy.length === 0) {
             continue;
         }
         const summary = routeToSummary(route, skillContent);
+        const candidateAdjuncts = findCandidateAdjuncts(summary.skill, routeMetadata);
         return {
             kind: 'skill_route',
             inputSkill: target,
@@ -106,8 +210,9 @@ export function explainSkillRoute(projectRoot, target) {
             reason: 'the skill index contains a route for the requested skill and exposes its trigger, scope, risk, checks, and output contract.',
             effectiveAction: `Read ${summary.skillPath} before editing work that matches: ${summary.trigger}`,
             countsAsMustflowVerification: false,
-            sourceFiles: [SKILL_INDEX_PATH, route.skillPath, '.mustflow/config/commands.toml'],
+            sourceFiles: [SKILL_INDEX_PATH, SKILL_ROUTES_METADATA_PATH, route.skillPath, '.mustflow/config/commands.toml'],
             route: summary,
+            selectionEvidence: buildMatchedSkillEvidence(summary, matchedBy, candidateAdjuncts),
         };
     }
     return {
@@ -119,5 +224,6 @@ export function explainSkillRoute(projectRoot, target) {
         countsAsMustflowVerification: false,
         sourceFiles: SKILL_ROUTE_SOURCE_FILES,
         route: null,
+        selectionEvidence: buildMissingSkillEvidence(target),
     };
 }

package/package.json

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

package/schemas/README.md

@@ -11,7 +11,9 @@ Current schemas:
 - `run-receipt.schema.json`: output of `mf run <intent> --json` and `.mustflow/state/runs/latest.json`,
   including bounded declared-write drift metadata, a safe latest-run performance summary, and optional
   structured phase timings and selection summaries
-- `commands.schema.json`: parsed `.mustflow/config/commands.toml`
+- `commands.schema.json`: parsed `.mustflow/config/commands.toml`, including validation-only
+  typed intent input metadata and explanatory preconditions that do not authorize parameterized
+  command execution or automatic dependency execution
 - `test-selection.schema.json`: parsed optional `.mustflow/config/test-selection.toml`
 - `contract-lint-report.schema.json`: output of `mf contract-lint --json`
 - `dashboard-export.schema.json`: bounded static export written by `mf dashboard --export-json <path>`,
@@ -33,7 +35,8 @@ Current schemas:
 - `docs-review-list.schema.json`: output of `mf docs review list --json`
 - `explain-report.schema.json`: output of `mf explain authority --json`, `mf explain command --json`,  
   `mf explain verify --reason <event> --json`, `mf explain retention --json`, `mf explain skills --json`,
-  and `mf explain surface --json`. Verify explanations include the shared `decisionGraph` evidence model.
+  `mf explain surface --json`, and `mf explain why <target> --json`. Verify explanations include the shared
+  `decisionGraph` evidence model; latest-failure explanations include bounded latest-run metadata only.
 - `verify-report.schema.json`: output of `mf verify --reason <event> --json`, including an
   explicit execution aggregate, evidence-based completion verdict, and evidence model with a
   conservative coverage matrix for the selected receipts and skipped checks
@@ -43,7 +46,7 @@ Current schemas:
   `mf verify --from-classification <classify-report.json> --plan-only --json`, including the `decision_graph` that links
   changed surfaces, classification reasons, command candidates, eligibility, selected or not-selected state,
   effects, and gaps.
-  Local-index command-effect graphs are explanation-only and cannot grant command authority.
+  Local-index command-effect graphs and command preconditions are explanation-only and cannot grant command authority.
 
 These schemas define stable, automation-facing fields. Human-readable command  
 output is intentionally excluded.

package/schemas/change-verification-report.schema.json

@@ -513,9 +513,61 @@
         },
         "effectGraph": {
           "$ref": "#/$defs/commandEffectGraph"
+        },
+        "preconditions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/commandPrecondition" }
         }
       }
     },
+    "commandPrecondition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "label",
+        "status",
+        "detail",
+        "path",
+        "artifact",
+        "sources",
+        "newestSource",
+        "satisfyIntent"
+      ],
+      "properties": {
+        "kind": { "type": "string" },
+        "label": { "type": ["string", "null"] },
+        "status": { "enum": ["satisfied", "missing", "stale", "unknown", "invalid"] },
+        "detail": { "type": "string" },
+        "path": { "type": ["string", "null"] },
+        "artifact": { "type": ["string", "null"] },
+        "sources": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "newestSource": { "type": ["string", "null"] },
+        "satisfyIntent": {
+          "anyOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/preconditionSatisfyIntent" }
+          ]
+        }
+      }
+    },
+    "preconditionSatisfyIntent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["intent", "declared", "runnable", "status", "lifecycle", "runPolicy", "detail"],
+      "properties": {
+        "intent": { "type": "string" },
+        "declared": { "type": "boolean" },
+        "runnable": { "type": "boolean" },
+        "status": { "type": ["string", "null"] },
+        "lifecycle": { "type": ["string", "null"] },
+        "runPolicy": { "type": ["string", "null"] },
+        "detail": { "type": ["string", "null"] }
+      }
+    },
     "commandEffectGraph": {
       "type": "object",
       "additionalProperties": false,

package/schemas/commands.schema.json

@@ -100,6 +100,29 @@
         "escalate_to": { "$ref": "#/$defs/stringArray" }
       }
     },
+    "intentInputs": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/$defs/intentInput" }
+    },
+    "intentInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "enum": ["path", "enum", "boolean", "integer", "literal"] },
+        "description": { "type": "string" },
+        "required": { "type": "boolean" },
+        "placeholder": { "type": "string" },
+        "secret": { "type": "boolean" },
+        "allowed_roots": { "$ref": "#/$defs/stringArray" },
+        "allowed_extensions": { "$ref": "#/$defs/stringArray" },
+        "allowed_values": { "$ref": "#/$defs/stringArray" },
+        "value": { "type": ["string", "number", "boolean"] },
+        "min": { "type": "integer" },
+        "max": { "type": "integer" }
+      }
+    },
     "costHints": {
       "type": "object",
       "additionalProperties": false,
@@ -110,6 +133,19 @@
         "cost_tier": { "type": "string" }
       }
     },
+    "intentPrecondition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["path_exists", "artifact_freshness"] },
+        "label": { "type": "string" },
+        "path": { "type": "string" },
+        "artifact": { "type": "string" },
+        "sources": { "$ref": "#/$defs/stringArray" },
+        "satisfy_intent": { "type": "string" }
+      }
+    },
     "relationHints": {
       "type": "object",
       "additionalProperties": false,
@@ -165,6 +201,11 @@
         },
         "covers": { "$ref": "#/$defs/coverageHints" },
         "selection": { "$ref": "#/$defs/selectionHints" },
+        "inputs": { "$ref": "#/$defs/intentInputs" },
+        "preconditions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/intentPrecondition" }
+        },
         "cost": { "$ref": "#/$defs/costHints" },
         "relations": { "$ref": "#/$defs/relationHints" },
         "reason": { "type": "string" },