mustflow 2.103.20 → 2.103.22

package/README.md

@@ -142,7 +142,7 @@ mustflow installs and validates an agent workflow for user projects.
 - Runs only allowed one-shot commands within a timeout via `mf run <intent>` or `mf verify` when the selected intent is runnable.
 - Records blockers, contradictions, verification gaps, and remaining risks as a structured conflict ledger in verify, evidence, and dashboard reports.
 - Stores bounded failure replay capsules for failed `mf verify` runs so future agents can reproduce the intent, receipt, command fingerprint, and changed-file state without copying raw command output.
-- Writes command receipts under `.mustflow/state/runs/run-*` and atomically updates `.mustflow/state/runs/latest.json`.
+- Writes bounded command receipts under `.mustflow/state/runs/run-*`, atomically updates `.mustflow/state/runs/latest.json`, and rebuilds `.mustflow/state/runs/latest.index.json` for recent retained runs.
 - Generates a concise repository navigation map, `REPO_MAP.md`, with `mf map`.
 - Indexes and searches mustflow docs, skills, skill routes, command rules, command-effect locks, file fingerprints, and opt-in source anchor metadata with SQLite via `mf index` and `mf search`. The local SQLite file is a rebuildable lookup cache, not a memory store, audit log, command transcript store, command-authority source, or source-content database.
 - Tracks agent-created or agent-modified documentation needing prose review with `mf docs review`.
@@ -373,7 +373,7 @@ Command environments remove the project-local `node_modules/.bin` path from `PAT
 
 Use `mf verify --reason <event> --plan-only --json` to inspect matching verification intents, command eligibility, risk-priced evidence requirements, remaining gaps, and missing runnable coverage without executing commands. Use `mf run <intent> --dry-run --json` to inspect one resolved command intent without spawning a process or writing a run receipt. Plan-only verification includes a `decision_graph` that connects changed surfaces, classification reasons, command candidates, eligibility checks, effects, and gaps. When `.mustflow/cache/mustflow.sqlite` is fresh, scheduled entries also include read-only `effectGraph` metadata for write locks and lock conflicts. These graph rows are marked `explanation_only` and never grant command authority; `.mustflow/config/commands.toml` remains the only runnable command source.
 
-Each executed command run writes a run record under `.mustflow/state/runs/run-*` and atomically updates `.mustflow/state/runs/latest.json`. The record includes the intent name, working directory, timeout, exit code, timeout status, and the tail of stdout and stderr. `latest.json` is a root-scoped convenience pointer, not session-scoped proof; in multi-agent or multi-terminal workflows, use the per-run `receipt_path` or `mf run <intent> --json` output as the evidence for a specific run.
+Each executed command run writes a run record under `.mustflow/state/runs/run-*`, atomically updates `.mustflow/state/runs/latest.json`, and rebuilds `.mustflow/state/runs/latest.index.json` from retained `run-*` and `verify-*` directories. The record includes the intent name, working directory, timeout, exit code, timeout status, and the tail of stdout and stderr. `latest.json` is a root-scoped convenience pointer, not session-scoped proof; in multi-agent or multi-terminal workflows, use the per-run `receipt_path`, the retained index, or `mf run <intent> --json` output as the evidence for a specific run.
 
 ## Language and profiles
 

package/dist/cli/commands/run/execution.js

@@ -290,7 +290,7 @@ export async function executeRunCommand(request, reporter, lang = 'en', options
             stderrTailBytes: runReceiptPolicy.stderrTailBytes,
         }));
         if (options.writeLatestReceipt !== false) {
-            profiler.measure('receipt_write', () => writeRunReceipt(projectRoot, receipt));
+            profiler.measure('receipt_write', () => writeRunReceipt(projectRoot, receipt, runReceiptPolicy));
         }
         if (options.recordPerformanceHistory !== false) {
             profiler.measure('performance_history_write', () => recordRunPerformanceHistory(projectRoot, receipt));

package/dist/cli/commands/verify.js

@@ -15,7 +15,9 @@ import { riskPricedEvidenceRiskCount, } from '../../core/risk-priced-evidence.js
 import { countValidationRatchetVerdictEffects, createValidationRatchetRisks, } from '../../core/validation-ratchet.js';
 import { finishRunWriteBatchTracking, startRunWriteBatchTracking, } from '../../core/run-write-drift.js';
 import { createCommandEnv } from '../../core/command-env.js';
-import { readCommandContract } from '../../core/config-loading.js';
+import { readCommandContract, readMustflowConfigIfExists } from '../../core/config-loading.js';
+import { resolveRunReceiptRetentionPolicy } from '../../core/retention-policy.js';
+import { updateRunReceiptState } from '../../core/run-receipt-state.js';
 import { evaluateCommandPreconditions, } from '../../core/command-preconditions.js';
 import { DEFAULT_VERIFY_PARALLELISM, parseVerifyArgs, resolveVerifyParallelism, } from './verify/args.js';
 import { createInputFromChanged, createSyntheticClassificationReport, planErrorMessageKey, readInputFromClassificationReport, resolveVerifyInputPath, writeChangedPlan, } from './verify/input.js';
@@ -764,6 +766,7 @@ function writeVerifyRunReceipts(projectRoot, output, report, sourceAnchorRisks,
         manifest_path: statePaths.manifestPath,
     };
     writeJsonFileInsideWithoutSymlinks(projectRoot, resolveLatestVerifyRunReceiptPath(projectRoot), latest);
+    updateRunReceiptState(projectRoot, resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot)));
     return outputWithReceiptPaths;
 }
 async function createVerifyOutput(input, planSource, projectRoot, lang, reproEvidence = null, externalChecks = [], parallelism = DEFAULT_VERIFY_PARALLELISM, parallelismReport = null) {

package/dist/cli/lib/option-parser.js

@@ -85,6 +85,32 @@ export function getParsedCliStringOption(parsed, name) {
     const value = parsed.values.get(name);
     return typeof value === 'string' ? value : null;
 }
+export function parsePositiveIntegerCliOption(value, option, invalidMessageKey, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^[1-9]\d*$/u.test(value)) {
+        return { value: null, error: t(lang, invalidMessageKey, { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, invalidMessageKey, { option, value }) };
+    }
+    return { value: parsed };
+}
+export function parseNonNegativeIntegerCliOption(value, option, invalidMessageKey, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^(?:0|[1-9]\d*)$/u.test(value)) {
+        return { value: null, error: t(lang, invalidMessageKey, { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, invalidMessageKey, { option, value }) };
+    }
+    return { value: parsed };
+}
 export function formatCliOptionParseError(error, lang) {
     if (error.kind === 'missing_value') {
         return t(lang, 'cli.error.missingValue', { option: error.option });

package/dist/cli/script-packs/repo-env-contract.js

@@ -1,6 +1,6 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
-import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parsePositiveIntegerCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { ENV_CONTRACT_SCRIPT_REF, inspectEnvContract } from '../../core/env-contract.js';
 const ENV_CONTRACT_OPTIONS = [
@@ -9,19 +9,6 @@ const ENV_CONTRACT_OPTIONS = [
     { name: '--max-file-bytes', kind: 'string' },
     { name: '--max-keys', kind: 'string' },
 ];
-function parsePositiveInteger(value, option, lang) {
-    if (value === null) {
-        return { value: null };
-    }
-    if (!/^[1-9]\d*$/u.test(value)) {
-        return { value: null, error: t(lang, 'envContract.error.invalidPositiveInteger', { option, value }) };
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed)) {
-        return { value: null, error: t(lang, 'envContract.error.invalidPositiveInteger', { option, value }) };
-    }
-    return { value: parsed };
-}
 export function getRepoEnvContractHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf script-pack run repo/env-contract scan [path...] [options]',
@@ -48,9 +35,9 @@ function parseEnvContractOptions(args, lang) {
     const [action, ...rest] = args;
     const parsed = parseCliOptions(rest, ENV_CONTRACT_OPTIONS, { allowPositionals: true });
     const json = hasParsedCliOption(parsed, '--json');
-    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
-    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
-    const maxKeys = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-keys'), '--max-keys', lang);
+    const maxFiles = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-files'), '--max-files', 'envContract.error.invalidPositiveInteger', lang);
+    const maxFileBytes = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', 'envContract.error.invalidPositiveInteger', lang);
+    const maxKeys = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-keys'), '--max-keys', 'envContract.error.invalidPositiveInteger', lang);
     if (action !== 'scan') {
         return {
             action: 'scan',

package/dist/cli/script-packs/repo-secret-risk-scan.js

@@ -1,6 +1,6 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
-import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parsePositiveIntegerCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { inspectSecretRiskScan, SECRET_RISK_SCAN_SCRIPT_REF } from '../../core/secret-risk-scan.js';
 const SECRET_RISK_SCAN_OPTIONS = [
@@ -9,19 +9,6 @@ const SECRET_RISK_SCAN_OPTIONS = [
     { name: '--max-file-bytes', kind: 'string' },
     { name: '--max-findings', kind: 'string' },
 ];
-function parsePositiveInteger(value, option, lang) {
-    if (value === null) {
-        return { value: null };
-    }
-    if (!/^[1-9]\d*$/u.test(value)) {
-        return { value: null, error: t(lang, 'secretRiskScan.error.invalidPositiveInteger', { option, value }) };
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed)) {
-        return { value: null, error: t(lang, 'secretRiskScan.error.invalidPositiveInteger', { option, value }) };
-    }
-    return { value: parsed };
-}
 export function getRepoSecretRiskScanHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf script-pack run repo/secret-risk-scan scan [path...] [options]',
@@ -48,9 +35,9 @@ function parseSecretRiskScanOptions(args, lang) {
     const [action, ...rest] = args;
     const parsed = parseCliOptions(rest, SECRET_RISK_SCAN_OPTIONS, { allowPositionals: true });
     const json = hasParsedCliOption(parsed, '--json');
-    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
-    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
-    const maxFindings = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-findings'), '--max-findings', lang);
+    const maxFiles = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-files'), '--max-files', 'secretRiskScan.error.invalidPositiveInteger', lang);
+    const maxFileBytes = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', 'secretRiskScan.error.invalidPositiveInteger', lang);
+    const maxFindings = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-findings'), '--max-findings', 'secretRiskScan.error.invalidPositiveInteger', lang);
     if (action !== 'scan') {
         return {
             action: 'scan',

package/dist/cli/script-packs/repo-security-pattern-scan.js

@@ -1,6 +1,6 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
-import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parsePositiveIntegerCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { inspectSecurityPatternScan, SECURITY_PATTERN_SCAN_SCRIPT_REF, } from '../../core/security-pattern-scan.js';
 const SECURITY_PATTERN_SCAN_OPTIONS = [
@@ -9,19 +9,6 @@ const SECURITY_PATTERN_SCAN_OPTIONS = [
     { name: '--max-file-bytes', kind: 'string' },
     { name: '--max-findings', kind: 'string' },
 ];
-function parsePositiveInteger(value, option, lang) {
-    if (value === null) {
-        return { value: null };
-    }
-    if (!/^[1-9]\d*$/u.test(value)) {
-        return { value: null, error: t(lang, 'securityPatternScan.error.invalidPositiveInteger', { option, value }) };
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed)) {
-        return { value: null, error: t(lang, 'securityPatternScan.error.invalidPositiveInteger', { option, value }) };
-    }
-    return { value: parsed };
-}
 export function getRepoSecurityPatternScanHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf script-pack run repo/security-pattern-scan scan [path...] [options]',
@@ -48,9 +35,9 @@ function parseSecurityPatternScanOptions(args, lang) {
     const [action, ...rest] = args;
     const parsed = parseCliOptions(rest, SECURITY_PATTERN_SCAN_OPTIONS, { allowPositionals: true });
     const json = hasParsedCliOption(parsed, '--json');
-    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
-    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
-    const maxFindings = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-findings'), '--max-findings', lang);
+    const maxFiles = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-files'), '--max-files', 'securityPatternScan.error.invalidPositiveInteger', lang);
+    const maxFileBytes = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', 'securityPatternScan.error.invalidPositiveInteger', lang);
+    const maxFindings = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-findings'), '--max-findings', 'securityPatternScan.error.invalidPositiveInteger', lang);
     if (action !== 'scan') {
         return {
             action: 'scan',

package/dist/core/retention-policy.js

@@ -5,6 +5,8 @@ export const DEFAULT_RETENTION_LIMITS = {
     repoMapMaxFileKb: 128,
     repoMapFailIfLarger: true,
     runReceiptMaxFileKb: 128,
+    runReceiptMaxItems: 50,
+    runReceiptMaxTotalMb: 10,
     contextMaxFileKb: 8,
     knowledgeMaxFileKb: 128,
 };
@@ -49,8 +51,8 @@ export function resolveRunReceiptRetentionPolicy(mustflowToml) {
     return {
         store: readString(runReceipts ?? {}, 'store') ?? 'repo_local_ignored',
         maxFileKb: readPositiveIntegerWithDefault(runReceipts, 'max_file_kb', DEFAULT_RETENTION_LIMITS.runReceiptMaxFileKb),
-        maxItems: readPositiveIntegerWithDefault(runReceipts, 'max_items', 1),
-        maxTotalMb: readPositiveIntegerWithDefault(runReceipts, 'max_total_mb', 1),
+        maxItems: readPositiveIntegerWithDefault(runReceipts, 'max_items', DEFAULT_RETENTION_LIMITS.runReceiptMaxItems),
+        maxTotalMb: readPositiveIntegerWithDefault(runReceipts, 'max_total_mb', DEFAULT_RETENTION_LIMITS.runReceiptMaxTotalMb),
         stdoutTailBytes: readPositiveIntegerWithDefault(runReceipts, 'keep_stdout_tail_bytes', DEFAULT_RUN_RECEIPT_TAIL_BYTES),
         stderrTailBytes: readPositiveIntegerWithDefault(runReceipts, 'keep_stderr_tail_bytes', DEFAULT_RUN_RECEIPT_TAIL_BYTES),
     };

package/dist/core/run-receipt-state.js

@@ -0,0 +1,247 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { ensureInside, writeJsonFileInsideWithoutSymlinks } from './safe-filesystem.js';
+const RUN_RECEIPT_SCHEMA_VERSION = '1';
+const RUN_RECEIPT_DIR = path.join('.mustflow', 'state', 'runs');
+const LATEST_RUN_RECEIPT_INDEX = 'latest.index.json';
+const STATE_DIR_PREFIXES = ['run-', 'verify-'];
+const MIN_RETAINED_RUN_DIRS = 1;
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+function stateRunsDir(projectRoot) {
+    return path.join(projectRoot, RUN_RECEIPT_DIR);
+}
+function latestIndexPath(projectRoot) {
+    return path.join(stateRunsDir(projectRoot), LATEST_RUN_RECEIPT_INDEX);
+}
+function runStateKind(name) {
+    return STATE_DIR_PREFIXES.find((prefix) => name.startsWith(prefix)) ?? null;
+}
+function isMissingPathError(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+function getStateRunSortKey(name) {
+    const match = /^(?:run|verify)-(.+)$/u.exec(name);
+    return match?.[1] ?? name;
+}
+function fileSizeBytes(filePath) {
+    try {
+        const stats = lstatSync(filePath);
+        if (stats.isSymbolicLink()) {
+            return 0;
+        }
+        if (stats.isFile()) {
+            return stats.size;
+        }
+        if (!stats.isDirectory()) {
+            return 0;
+        }
+        return readdirSync(filePath).reduce((total, entry) => total + fileSizeBytes(path.join(filePath, entry)), 0);
+    }
+    catch (error) {
+        if (isMissingPathError(error)) {
+            return 0;
+        }
+        throw error;
+    }
+}
+function readRunStateDirectories(projectRoot) {
+    const receiptDir = stateRunsDir(projectRoot);
+    if (!existsSync(receiptDir)) {
+        return [];
+    }
+    return readdirSync(receiptDir)
+        .map((name) => {
+        const kind = runStateKind(name);
+        if (!kind) {
+            return null;
+        }
+        const absolutePath = path.join(receiptDir, name);
+        const relativePath = toPosixPath(path.join(RUN_RECEIPT_DIR, name));
+        const stats = lstatSync(absolutePath);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            return null;
+        }
+        return {
+            absolutePath,
+            relativePath,
+            name,
+            kind,
+            sortKey: getStateRunSortKey(name),
+            sizeBytes: fileSizeBytes(absolutePath),
+        };
+    })
+        .filter((entry) => Boolean(entry))
+        .sort(compareRunStateDirectoriesDescending);
+}
+function compareRunStateDirectoriesDescending(left, right) {
+    const bySortKey = right.sortKey.localeCompare(left.sortKey);
+    if (bySortKey !== 0) {
+        return bySortKey;
+    }
+    return right.name.localeCompare(left.name);
+}
+function removeRunStateDirectory(projectRoot, directory) {
+    const runsDir = stateRunsDir(projectRoot);
+    ensureInside(runsDir, directory.absolutePath);
+    const relativeToRunsDir = path.relative(runsDir, directory.absolutePath);
+    if (relativeToRunsDir.startsWith('..') || path.isAbsolute(relativeToRunsDir) || runStateKind(path.basename(directory.absolutePath)) === null) {
+        throw new Error(`Refusing to remove unexpected run receipt path: ${directory.relativePath}`);
+    }
+    const stats = lstatSync(directory.absolutePath);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`Refusing to remove non-directory run receipt path: ${directory.relativePath}`);
+    }
+    rmSync(directory.absolutePath, { recursive: true, force: true });
+}
+function applyRunReceiptRetention(projectRoot, policy) {
+    const directories = readRunStateDirectories(projectRoot);
+    const maxItems = Math.max(MIN_RETAINED_RUN_DIRS, policy.maxItems);
+    const maxTotalBytes = Math.max(1, policy.maxTotalMb) * 1024 * 1024;
+    const kept = new Set(directories.slice(0, maxItems).map((directory) => directory.name));
+    let totalBytes = directories
+        .filter((directory) => kept.has(directory.name))
+        .reduce((total, directory) => total + directory.sizeBytes, 0);
+    for (const directory of directories.slice(maxItems)) {
+        removeRunStateDirectory(projectRoot, directory);
+    }
+    for (const directory of [...directories].reverse()) {
+        if (kept.size <= MIN_RETAINED_RUN_DIRS || !kept.has(directory.name) || totalBytes <= maxTotalBytes) {
+            continue;
+        }
+        removeRunStateDirectory(projectRoot, directory);
+        kept.delete(directory.name);
+        totalBytes -= directory.sizeBytes;
+    }
+    return readRunStateDirectories(projectRoot);
+}
+function readJsonObject(filePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stringField(value) {
+    return typeof value === 'string' ? value : null;
+}
+function stringArrayField(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string') ? value : undefined;
+}
+function createRunEntry(directory) {
+    const receipt = readJsonObject(path.join(directory.absolutePath, 'receipt.json'));
+    if (!receipt || receipt.command !== 'run' || typeof receipt.receipt_path !== 'string') {
+        return null;
+    }
+    return {
+        command: 'run',
+        intent: stringField(receipt.intent),
+        status: stringField(receipt.status),
+        cwd: stringField(receipt.cwd),
+        started_at: stringField(receipt.started_at),
+        finished_at: stringField(receipt.finished_at),
+        correlation_id: stringField(receipt.correlation_id),
+        receipt_path: receipt.receipt_path,
+        run_dir: directory.relativePath,
+    };
+}
+function readVerifyIntentEntry(directory, manifest, manifestPath, manifestReceipt) {
+    const receiptPath = stringField(manifestReceipt.receipt_path);
+    if (!receiptPath) {
+        return null;
+    }
+    const runsDir = path.dirname(directory.absolutePath);
+    const receiptAbsolutePath = path.resolve(runsDir, ...receiptPath.split('/').slice(3));
+    ensureInside(runsDir, receiptAbsolutePath);
+    const receipt = readJsonObject(receiptAbsolutePath);
+    return {
+        command: 'verify',
+        intent: stringField(manifestReceipt.intent),
+        status: stringField(manifestReceipt.status),
+        cwd: stringField(receipt?.cwd),
+        started_at: stringField(receipt?.started_at),
+        finished_at: stringField(receipt?.finished_at),
+        correlation_id: stringField(manifest.correlation_id),
+        verification_plan_id: stringField(manifest.verification_plan_id),
+        reason: stringField(manifest.reason),
+        reasons: stringArrayField(manifest.reasons),
+        receipt_path: receiptPath,
+        manifest_path: manifestPath,
+        run_dir: directory.relativePath,
+    };
+}
+function createVerifyEntries(directory) {
+    const manifestPath = toPosixPath(path.join(directory.relativePath, 'manifest.json'));
+    const manifest = readJsonObject(path.join(directory.absolutePath, 'manifest.json'));
+    if (!manifest || manifest.command !== 'verify') {
+        return [];
+    }
+    const summaryEntry = {
+        command: 'verify',
+        intent: null,
+        status: stringField(manifest.status ?? manifest.execution_status),
+        correlation_id: stringField(manifest.correlation_id),
+        verification_plan_id: stringField(manifest.verification_plan_id),
+        reason: stringField(manifest.reason),
+        reasons: stringArrayField(manifest.reasons),
+        manifest_path: manifestPath,
+        run_dir: directory.relativePath,
+    };
+    const receiptEntries = Array.isArray(manifest.receipts)
+        ? manifest.receipts
+            .map((receipt) => receipt && typeof receipt === 'object'
+            ? readVerifyIntentEntry(directory, manifest, manifestPath, receipt)
+            : null)
+            .filter((entry) => Boolean(entry))
+        : [];
+    return [summaryEntry, ...receiptEntries];
+}
+function createIndexEntries(directories) {
+    return directories.flatMap((directory) => {
+        if (directory.kind === 'run-') {
+            const entry = createRunEntry(directory);
+            return entry ? [entry] : [];
+        }
+        return createVerifyEntries(directory);
+    });
+}
+function entryTargetPath(entry) {
+    return entry.receipt_path ?? entry.manifest_path ?? null;
+}
+function latestLookupEntries(entries) {
+    const latestByIntent = {};
+    const latestByCwdIntent = {};
+    for (const entry of entries) {
+        const targetPath = entryTargetPath(entry);
+        if (!entry.intent || !targetPath) {
+            continue;
+        }
+        latestByIntent[entry.intent] ??= targetPath;
+        if (entry.cwd) {
+            latestByCwdIntent[`${entry.cwd}::${entry.intent}`] ??= targetPath;
+        }
+    }
+    return { latestByIntent, latestByCwdIntent };
+}
+export function updateRunReceiptState(projectRoot, policy) {
+    const retainedDirectories = applyRunReceiptRetention(projectRoot, policy);
+    const entries = createIndexEntries(retainedDirectories);
+    const lookups = latestLookupEntries(entries);
+    const index = {
+        schema_version: RUN_RECEIPT_SCHEMA_VERSION,
+        kind: 'run_receipt_index',
+        generated_at: new Date().toISOString(),
+        retention: {
+            max_items: policy.maxItems,
+            max_total_mb: policy.maxTotalMb,
+            retained_run_dirs: retainedDirectories.length,
+        },
+        entries,
+        latest_by_intent: lookups.latestByIntent,
+        latest_by_cwd_intent: lookups.latestByCwdIntent,
+    };
+    writeJsonFileInsideWithoutSymlinks(projectRoot, latestIndexPath(projectRoot), index);
+}

package/dist/core/run-receipt.js

@@ -4,6 +4,7 @@ import { createStateRunId } from './atomic-state-write.js';
 import { COMMAND_OUTPUT_LIMIT_SCOPE } from './command-output-limits.js';
 import { decodeUtf8Tail } from './bounded-output.js';
 import { DEFAULT_RUN_RECEIPT_TAIL_BYTES } from './retention-policy.js';
+import { updateRunReceiptState } from './run-receipt-state.js';
 import { writeJsonFileInsideWithoutSymlinks } from './safe-filesystem.js';
 import { redactSecretLikeText } from './secret-redaction.js';
 const RUN_RECEIPT_SCHEMA_VERSION = '1';
@@ -286,7 +287,7 @@ export function createRunReceipt(input) {
         receipt_path: getReceiptRelativePath(input.receiptPath),
     };
 }
-export function writeRunReceipt(projectRoot, receipt) {
+export function writeRunReceipt(projectRoot, receipt, policy) {
     const receiptDir = path.join(projectRoot, RUN_RECEIPT_DIR);
     const latestPath = path.join(receiptDir, LATEST_RUN_RECEIPT);
     const receiptPath = path.resolve(projectRoot, receipt.receipt_path);
@@ -296,4 +297,7 @@ export function writeRunReceipt(projectRoot, receipt) {
     }
     writeJsonFileInsideWithoutSymlinks(projectRoot, receiptPath, receipt);
     writeJsonFileInsideWithoutSymlinks(projectRoot, latestPath, receipt);
+    if (policy) {
+        updateRunReceiptState(projectRoot, policy);
+    }
 }

package/package.json

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

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

@@ -350,8 +350,8 @@ on_limit = "report"
 [retention.run_receipts]
 store = "repo_local_ignored"
 max_file_kb = 128
-max_items = 1
-max_total_mb = 1
+max_items = 50
+max_total_mb = 10
 keep_stdout_tail_bytes = 65536
 keep_stderr_tail_bytes = 65536
 

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 188
+revision = 189
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -89,6 +89,12 @@ source_locale = "en"
 revision = 3
 translations = {}
 
+[documents."skill.http-api-semantics-review"]
+source = "locales/en/.mustflow/skills/http-api-semantics-review/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.backend-reliability-change"]
 source = "locales/en/.mustflow/skills/backend-reliability-change/SKILL.md"
 source_locale = "en"
@@ -559,7 +565,7 @@ translations = {}
 [documents."skill.clarifying-question-gate"]
 source = "locales/en/.mustflow/skills/clarifying-question-gate/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 4
 translations = {}
 
 [documents."skill.heuristic-candidate-selection"]

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 188
+revision: 189
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -106,6 +106,11 @@ refer to `AGENTS.md` and `.mustflow/config/commands.toml` to implement the most
   shapes, response shapes, pagination, idempotency, async jobs, versioning, deprecation, rate
   limits, retry rules, observability, or caller-facing docs need caller-ergonomics and misuse-risk
   review rather than only schema compatibility.
+- Use `http-api-semantics-review` as an adjunct when HTTP method choices, safe/idempotent/cacheable
+  claims, GET/HEAD bodies, OPTIONS or Allow discovery, HTTP QUERY, POST versus PUT URI ownership,
+  PUT replacement, PATCH document formats, DELETE behavior, conditional requests, status codes,
+  cache headers, CORS method discovery, retry behavior, or intermediary compatibility need HTTP
+  semantics review rather than only schema compatibility.
 - Use `api-access-control-review` as an adjunct when API security review needs BOLA or IDOR,
   object, property, or function authorization, tenant isolation, request-supplied identity,
   mass assignment, signed URLs, queue revalidation, webhook ownership, token/session hardening,
@@ -471,6 +476,7 @@ routes. Event routes stay inactive until their event occurs.
 | Product, app, service, CLI, API, SDK, library, desktop app, automation tool, or developer tool work needs a decision about which user, developer, operator, automation, integration, recovery, upgrade, documentation, or observability surfaces are supported now, deferred, explicitly unsupported, or internal-only | `.mustflow/skills/support-surface-advisor/SKILL.md` | Product stage, primary actors, main usage path, integration need, maintenance capacity, public-contract willingness, explicit non-goals, recovery and observability expectations, and current repository evidence | Support-surface plan, selected implementation boundaries, docs, tests, route metadata, core-engine boundary, and directly synchronized templates when installed | support-contract bloat, accidental public API, UI/CLI/API duplicate core logic, hidden integration promise, unsupported automation route, unowned recovery path, stale compatibility promise, or implementation explanation leaking into user-facing UI copy | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Product stage, actors, recommended surfaces, deferred and unsupported surfaces, blocking questions, maintenance and compatibility risks, core engine versus shell boundary, staged plan, verification, and remaining support-surface risk |
 | A task chooses, migrates, rewrites, or justifies a primary language, runtime, framework, compile target, or execution environment | `.mustflow/skills/runtime-target-selection/SKILL.md` | Current runtime surfaces, target options, product or system need, environment constraints, migration boundary, smoke targets, and performance or reliability claims | Decision records, skill procedures, route metadata, migration plans, command-contract proposals, tests, fixtures, docs, and smallest selected migration scaffold | language-preference rewrite, unsupported runtime target, unusable build loop, cache or artifact blowup, missing smoke target, deployment drift, or false performance claim | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_related`, `test_release`, `mustflow_check` | Decision boundary, candidate targets, environment and build-loop evidence, smoke targets, migration boundary, calibrated claims, verification, and remaining runtime-target risk |
 | Non-trivial code work needs early structure decisions around domain rules, public contracts, external I/O, operational safety, failure handling, concurrency, data flow, or future change cost | `.mustflow/skills/structure-first-engineering/SKILL.md` | User request, target files, project context, core boundary, data flow, expected failures, public contracts, I/O surfaces, and verification contract | Risk block, focused boundaries, DTOs, adapters, pure functions, error models, tests, and directly synchronized docs or contracts | under-designed hard boundary, speculative abstraction, vague service layer, mixed I/O and domain rules, hidden partial failure, or untestable behavior | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Work risk, structure decision, data flow, failure model, I/O and concurrency boundaries, tests, verification, and remaining structure risk |
+| HTTP API method semantics, safe/idempotent/cacheable claims, GET or HEAD request-body assumptions, OPTIONS capability discovery, HTTP QUERY, POST versus PUT URI ownership, PUT replacement, PATCH document formats, DELETE behavior, conditional requests, status-code recovery, cache headers, CORS method discovery, retry behavior, or intermediary compatibility are created, changed, reviewed, or reported | `.mustflow/skills/http-api-semantics-review/SKILL.md` | Endpoint method ledger, method contract, concurrency contract, PATCH media type and atomicity, GET/QUERY/POST search contract, cache and capability headers, caller and intermediary support evidence, and configured command intents | Route handlers, method choices, validators, OpenAPI or docs, SDK examples, gateway rules, CORS rules, cache headers, conditional request handling, status-code maps, focused tests, and directly synchronized templates | hidden GET mutation, non-portable GET or HEAD body, PUT partial merge, ambiguous PATCH JSON, PATCH partial success, DELETE body dependency, duplicate DELETE side effect, POST search semantic blur, QUERY without media type or body-aware cache key, stale-client field loss, missing If-Match, confused Allow versus CORS methods, `no-cache` treated as `no-store`, collapsed status-code recovery, or proxy/CDN/client incompatibility | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | HTTP API semantics reviewed, endpoint method ledger, safe/idempotent/cache/header/status/conditional request findings, fixes or recommendations, synchronized API surfaces, verification, and remaining HTTP semantics risk |
 | HTTP, REST, GraphQL, tRPC, Hono RPC, Elysia Eden, gRPC, protobuf, OpenAPI, request/response schema, status code, header, content negotiation, cache header, error envelope, pagination, filtering, sorting, search, generated client, SDK, mock, fixture, or API docs contract is created or changed | `.mustflow/skills/api-contract-change/SKILL.md` | API style, contract source of truth, changed operations, request and response schemas, status and headers, content negotiation, error envelope, auth and permission behavior, pagination/filter/sort/search semantics, generated clients, SDKs, mocks, fixtures, callers, docs, and command contract entries | Routes, handlers, resolvers, validators, schemas, generated clients, SDKs, mocks, fixtures, docs, tests, and directly synchronized examples | route-only change, schema drift, generated-client breakage, hidden breaking change, status or error drift, pagination/search semantic drift, auth/permission drift, cache/header drift, or stale docs examples | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | API contract source, changed operations, compatibility classification, synchronized client/schema/docs/tests surfaces, verification, and remaining API contract risk |
 | Backend APIs, workers, jobs, queues, caches, database write paths, external service calls, health checks, observability, feature flags, idempotency, retries, outbox/inbox processing, or operational failure handling are created, changed, reviewed, or reported | `.mustflow/skills/backend-reliability-change/SKILL.md` | Backend surface, trigger shape, idempotency boundary, external-call deadline and retry policy, persistence and transaction boundary, queue/cache behavior, observability fields, rollout gate, and command contract entries | Handlers, services, workers, retry policy, timeout policy, idempotency storage, outbox/inbox code, cache boundaries, health endpoints, observability fields, flags, tests, docs, and directly synchronized templates | duplicate side effects, retry storm, unbounded wait, DB uniqueness race, cache stampede, stale cache authority, poison message loop, missing outbox/inbox, raw ORM response, object-level authorization bypass, high-cardinality telemetry, secret or personal-data log leak, broken liveness/readiness, or missing kill switch | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Backend surface, idempotency and retry/timeout decisions, queue/cache/database notes, health-probe split, observability and auth/DTO notes, rollout gate, verification, and remaining backend reliability risk |
 | HTTP delivery, content coding, compression negotiation, CDN or proxy cache behavior, streaming responses, SSE, EventSource, WebTransport, WebSocket fallback, HTTP/2 or HTTP/3 transport behavior, browser transport clients, reverse-proxy buffering, reconnect behavior, or delivery observability is created, changed, reviewed, or reported | `.mustflow/skills/http-delivery-streaming/SKILL.md` | Delivery surface, routes or assets, headers, cache and proxy/CDN path, browser/API clients, fallback behavior, streaming lifecycle, compression or dictionary choice, and observability fields | Route handlers, response headers, CDN/proxy config, browser transport code, streaming adapters, fallback clients, docs, tests, and directly synchronized templates | wrong content decoding, cache poisoning, private data cached publicly, proxy buffering, lost events, reconnect gaps, unsupported transport, unreliable datagram misuse, false compression win, or fallback failure | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Delivery ledger, negotiated encodings, cache/proxy behavior, stream/reconnect/fallback behavior, verification, and remaining delivery risk |

package/templates/default/locales/en/.mustflow/skills/clarifying-question-gate/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.clarifying-question-gate
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: clarifying-question-gate
@@ -96,6 +96,8 @@ verification, and stop-or-ask boundary.
 - Reversibility classification for each decision: cheap/reversible, moderate, or expensive/hard to
   roll back.
 - A recommended option for each blocking question, with the tradeoff of at least one alternative.
+- Host input capability when known: whether a structured user-input mechanism such as Codex
+  `request_user_input` or MCP elicitation is explicitly available in the current runtime.
 - A request-state decision: `ready`, `ready_with_assumptions`, `needs_confirmation`,
   `blocked_by_conflict`, or `insufficient_evidence`.
 - A normalized task contract when the original request is vague enough to risk drift: goal, current
@@ -123,6 +125,8 @@ verification, and stop-or-ask boundary.
   collection, or broad product discovery.
 - Product decisions are separated from engineering responsibilities. Do not ask whether to preserve
   existing style, avoid swallowed errors, add appropriate tests, or follow command contracts.
+- Structured input tools are optional host capabilities. Do not claim they exist, simulate their UI,
+  or depend on them unless the current host explicitly exposes them for this turn or tool call.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -215,22 +219,40 @@ verification, and stop-or-ask boundary.
       and one meaningful alternative;
     - avoid open-ended prompts like "how should I implement this?" unless no responsible options can
       be framed from repository evidence.
-15. Do not ask bad engineering-delegation questions:
+15. Prefer structured user input for real blocking decisions when the host exposes it:
+    - use a structured input tool such as `request_user_input` or MCP elicitation only when it is
+      explicitly listed as available in the current runtime or tool call;
+    - use it for `needs_confirmation` or for a non-blocking `ready_with_assumptions` choice whose
+      answer would materially improve the result without stopping all progress;
+    - ask at most three short questions, and prefer one question when the answer may change the next
+      question;
+    - provide two or three mutually exclusive choices, put the recommended choice first, and include
+      the concrete consequence or tradeoff for each choice;
+    - allow free-form input when the host mechanism supports it, because the listed options are a
+      steering aid rather than a closed product decision;
+    - use auto-resolution only for non-blocking choices with a narrow reversible default, and never
+      for destructive actions, publish or release decisions, credential or secret handling, data
+      deletion or migration, auth or billing policy, dependency adoption, or other explicit
+      confirmation gates;
+    - if no structured input mechanism is available, ask the same blocking decision as a concise
+      normal chat question when host policy allows it; do not invent a fake UI, long questionnaire,
+      or multiple-choice card in prose when the host explicitly forbids that fallback.
+16. Do not ask bad engineering-delegation questions:
     - "Should I add tests?"
     - "Should I handle errors?"
     - "Should I follow existing style?"
     - "Should I check current files?"
     - "Should I preserve existing behavior?"
-16. Use prompt rewriting only as an exception:
+17. Use prompt rewriting only as an exception:
     - the user explicitly asks for a prompt, issue, PR body, work order, or handoff for another
       agent;
     - the current request is too broken to execute and a normalized contract plus confirmation is the
       smallest safe next step.
     Otherwise, show the normalized contract only when it materially reduces drift, then proceed in
     the same conversation.
-17. If no blocking question remains, proceed without ceremony. State only the assumptions that matter
+18. If no blocking question remains, proceed without ceremony. State only the assumptions that matter
     to review or rollback.
-18. If a blocking question remains unanswered, do not implement around it. Offer the smallest safe
+19. If a blocking question remains unanswered, do not implement around it. Offer the smallest safe
     non-blocked action, such as read-only analysis, a plan, a reproduction, or a narrow preparatory
     refactor when another selected skill supports it.
 
@@ -241,6 +263,8 @@ verification, and stop-or-ask boundary.
 - The agent has not asked for facts it could read locally.
 - Expensive, user-owned, security-sensitive, data-affecting, dependency-affecting, and public-contract
   decisions are resolved before implementation.
+- Structured input tools are used only when available and only for bounded decisions that benefit
+  from user choice.
 - Safe assumptions are narrow, reversible, and reported.
 - Any normalized contract preserves the user's original request separately from repository-derived
   facts and safe assumptions.
@@ -288,6 +312,7 @@ run the specific configured verification intents required by the selected implem
 - Normalized task contract, only when needed, with `user_confirmed`, `repository_derived`,
   `safe_assumption`, and `unresolved` source tags
 - Blocking questions asked, with recommendation and tradeoff
+- Question delivery mode: structured host input, normal chat fallback, or not needed
 - Safe assumptions made
 - Decisions intentionally deferred
 - Implementation scope selected

package/templates/default/locales/en/.mustflow/skills/http-api-semantics-review/SKILL.md

@@ -0,0 +1,286 @@
+---
+mustflow_doc: skill.http-api-semantics-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: http-api-semantics-review
+description: Apply this skill when HTTP API method semantics, safe or idempotent behavior, GET or HEAD request-body assumptions, OPTIONS or Allow discovery, HTTP QUERY, POST versus PUT URI ownership, PUT replacement, PATCH document formats, DELETE behavior, conditional requests, status codes, cache headers, CORS method discovery, retry behavior, or intermediary compatibility need review.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.http-api-semantics-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# HTTP API Semantics Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review HTTP APIs as method, status, header, cache, retry, and intermediary contracts, not as CRUD
+labels or controller naming preferences.
+
+The review question is not "does this route work in the current framework?" It is "will browsers,
+crawlers, caches, gateways, SDKs, retries, stale clients, and concurrent callers interpret this
+request the same way the server does?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- HTTP or REST routes, handlers, OpenAPI documents, API docs, SDKs, gateways, middleware, CORS
+  policy, cache policy, status-code maps, or request/response headers are created, changed,
+  reviewed, or reported.
+- A change chooses or changes GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE, QUERY, or fallback
+  behavior.
+- A review claims that an endpoint is safe, idempotent, cacheable, retry-safe, crawler-safe,
+  prefetch-safe, proxy-safe, CDN-compatible, or portable across HTTP clients.
+- The task involves PUT full replacement, PATCH document semantics, DELETE bodies, POST search,
+  GET or HEAD request bodies, HTTP QUERY, Accept-Patch, Accept-Query, Allow, ETag, If-Match,
+  If-None-Match, Cache-Control, Vary, Location, Content-Location, Retry-After, or CORS method
+  discovery.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The main work is broad API source-of-truth synchronization, generated clients, schema drift, or
+  compatibility classification; use `api-contract-change` first and this skill only for HTTP
+  method semantics.
+- The main work is caller ergonomics, ambiguous DTOs, hidden operation modes, or SDK usability; use
+  `api-misuse-resistance-review`.
+- The main work is duplicate business side effects or retry delivery; use
+  `idempotency-integrity-review`.
+- The main work is cache key truth, stale data, invalidation, Redis, or cache outage behavior; use
+  `cache-integrity-review`.
+- The main work is response streaming, compression, proxy buffering, SSE, WebTransport, or delivery
+  transport behavior; use `http-delivery-streaming`.
+- The API is not HTTP-facing and no HTTP method, status, header, cache, CORS, retry, or
+  intermediary behavior is part of the contract.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Endpoint ledger: method, path, request body meaning, success statuses, error statuses, headers,
+  auth and permission requirement, cacheability, caller types, and fallback paths.
+- Method contract: whether the caller requests a safe operation, an idempotent operation, a full
+  representation replacement, a patch document application, a server-selected creation, a
+  client-selected target URI, a delete/unlink operation, or a safe body-bearing query.
+- Concurrency contract: ETag or version source, conditional request requirements, lost-update
+  behavior, conflict behavior, and retry behavior after unknown outcomes.
+- Patch contract when PATCH is used: media type, patch grammar, null and omission semantics,
+  atomicity boundary, validation timing, Accept-Patch discovery, and status-code recovery map.
+- Query contract when GET, QUERY, or POST search is used: canonical GET strategy, query body media
+  type, Accept-Query or Allow discovery, fallback behavior, cache-key inputs, canonicalization,
+  Location or Content-Location behavior, and sensitive-data handling.
+- Cache and capability contract: Cache-Control, Vary, ETag, Last-Modified, Location,
+  Content-Location, Allow, Access-Control-Allow-Methods, Accept-Patch, Accept-Query, Retry-After,
+  and RateLimit header behavior when relevant.
+- Relevant command-intent contract entries for tests, builds, docs, release checks, and mustflow
+  validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the
+  current scope.
+- The current contract source of truth is known, such as OpenAPI, route validators, handler tests,
+  API docs, gateway config, or SDK examples.
+- If HTTP semantics changes affect request or response shapes, generated clients, auth, permission,
+  cache correctness, duplicate side effects, or streaming delivery, also apply the narrower matching
+  skill before finalizing that part.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update route handlers, method choices, validators, OpenAPI or API docs, SDK examples, gateway
+  rules, CORS rules, cache headers, conditional request handling, status-code maps, and focused
+  tests tied to the changed HTTP contract.
+- Add explicit support or rejection for GET or HEAD bodies, DELETE bodies, unsupported methods,
+  unsupported patch media types, missing preconditions, and body-bearing safe queries.
+- Add capability discovery through Allow, Accept-Patch, Accept-Query, and documented fallback
+  behavior when the API exposes those capabilities.
+- Do not silently convert PUT into partial merge, PATCH into ambiguous JSON merge, GET into a
+  command, POST search into a safe operation without naming fallback semantics, or cache policy into
+  prose-only behavior.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build a method semantics ledger for every endpoint under review:
+   - method;
+   - target URI ownership;
+   - whether the method is safe, idempotent, and cacheable for this operation;
+   - request body meaning;
+   - expected automatic retry behavior;
+   - success, conflict, validation, unsupported-media, precondition, rate-limit, and overload
+     statuses.
+2. Check safe methods first.
+   - GET, HEAD, and OPTIONS must not request business mutations.
+   - Safe does not mean unauthenticated, cheap, unmetered, or cache-public.
+   - Crawlers, link previews, browser prefetch, health checks, and monitoring can trigger safe
+     methods.
+3. Reject public GET and HEAD request-body semantics unless the API intentionally documents a
+   non-portable private contract.
+   - Prefer GET query parameters for small, shareable, cacheable, non-sensitive reads.
+   - Prefer QUERY for safe, idempotent, body-bearing queries when clients, gateways, servers, and
+     docs can support it.
+   - Use POST as a compatibility fallback or state-changing processing request, not as an unnamed
+     safe query.
+4. Review OPTIONS as capability discovery.
+   - OPTIONS is not only a CORS preflight shortcut.
+   - Keep `Allow` for HTTP method support separate from `Access-Control-Allow-Methods` for CORS.
+   - Ensure 405 responses include an accurate `Allow` header.
+5. Review POST versus PUT URI ownership.
+   - Use POST when the server chooses the new resource URI or processes a resource-specific command.
+   - Use PUT when the client knows the target URI and wants that target representation created or
+     replaced.
+   - Do not let PUT write to a different URI without redirect or explicit contract.
+6. Review PUT as replacement.
+   - A PUT body is the new representation for the target URI, not a partial DTO by default.
+   - Reject incomplete replacement bodies, require full client-owned representations, or choose
+     PATCH or a command resource instead.
+   - For create-only PUT, require `If-None-Match: *` where concurrent creation matters.
+   - For update-only PUT, require `If-Match` or another version precondition where lost updates
+     matter.
+7. Review PATCH as patch document application.
+   - Pick and document the patch media type, such as `application/merge-patch+json`,
+     `application/json-patch+json`, or a domain-specific media type.
+   - Do not use bare `application/json` when null, omission, delete, array, and command semantics
+     are ambiguous.
+   - Advertise supported patch formats with `Accept-Patch` where capability discovery matters.
+   - Apply the whole patch atomically. Partial patch success is a contract failure.
+   - Validate the resulting resource, not only the patch document syntax.
+8. Review DELETE as target-resource unlinking, not necessarily physical storage deletion.
+   - Do not require identical repeat response statuses for idempotency; require identical intended
+     effect and duplicate-safe side effects.
+   - Avoid DELETE request bodies for portable bulk or filtered deletes. Prefer item DELETE calls or
+     POST command resources such as deletion jobs.
+   - Document soft-delete, tombstone, retention, restore, and audit behavior when callers rely on
+     lifecycle outcomes.
+9. Review conditional requests and lost-update protection.
+   - Use strong ETags or equivalent version tokens when concurrent writers can overwrite one
+     another.
+   - Use `If-Match` for update preconditions and `If-None-Match: *` for create-if-absent.
+   - Return `412 Precondition Failed` for failed preconditions and `428 Precondition Required` when
+     the API refuses unsafe writes without preconditions.
+10. Review QUERY and search design.
+    - Keep simple, bookmarkable, shareable, cacheable searches on GET where possible.
+    - Use QUERY for safe, idempotent, body-bearing queries whose inputs do not belong cleanly in the
+      URI.
+    - Define the request media type and reject missing or inconsistent Content-Type.
+    - Expose support through `Allow` and supported query formats through `Accept-Query` when
+      clients need discovery.
+    - Build cache keys from request content plus relevant metadata, and canonicalize only
+      semantically insignificant differences.
+    - Decide whether `Content-Location`, `Location`, or `303 See Other` gives callers a GET-able
+      result, equivalent query, or stored job/resource.
+    - Use POST fallback only as a compatibility shell over the same internal query model.
+11. Review status codes as recovery instructions.
+    - Use `201` plus `Location` and preferably `ETag` when a resource is created.
+    - Use `202` plus a status resource when work is accepted but unfinished.
+    - Use `204` for successful no-body responses, `206` for partial content, and `304` for
+      conditional cache validation.
+    - Separate malformed input (`400`), unsupported media (`415`), current-state conflict (`409`),
+      failed precondition (`412`), missing precondition (`428`), valid-but-unprocessable content
+      (`422`), method unsupported for the resource (`405` with `Allow`), method unknown (`501`),
+      rate limit (`429` with `Retry-After` where useful), and overload (`503` with `Retry-After`
+      where useful).
+12. Review HTTP cache semantics.
+    - `no-cache` means revalidate before reuse. `no-store` means do not store.
+    - Use `private`, `public`, `s-maxage`, validators, and `Vary` according to viewer, auth,
+      language, encoding, content negotiation, and tenant dimensions.
+    - Do not assume a successful unsafe method invalidates every list, search, feed, recommendation,
+      CDN tag, or read model that can include the changed resource.
+13. Check synchronized surfaces before finalizing.
+    - Route code, validators, OpenAPI or docs, generated clients, SDK examples, gateway and CORS
+      config, cache config, status-code fixtures, retry docs, tests, monitoring, and release notes
+      should agree with the HTTP method contract.
+    - If deterministic proxy, CDN, browser, or gateway evidence is unavailable, report that gap
+      instead of claiming portability.
+
+## Strongly Forbidden Patterns
+
+- GET, HEAD, or OPTIONS hidden business mutations.
+- Public GET or HEAD request bodies as if they were portable HTTP contracts.
+- PUT partial update merge without an explicit non-PUT contract.
+- PATCH with ambiguous `application/json` semantics.
+- PATCH partial success.
+- DELETE request bodies for portable bulk or filtered operations.
+- Treating DELETE idempotency as identical status codes while duplicate side effects replay.
+- Treating `no-cache` as `no-store`.
+- Mixing `Allow` with `Access-Control-Allow-Methods`.
+- POST search without naming safe-query fallback and cache behavior.
+- QUERY without media type, support discovery, body-aware cache key, and intermediary support plan.
+- Collapsing status codes so clients cannot tell whether to fix input, refresh state, retry later,
+  update ETags, or change media type.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Method semantics, request body meaning, URI ownership, retry expectations, status-code recovery,
+  conditional requests, capability discovery, cache semantics, and intermediary assumptions are
+  explicit or reported as missing.
+- PUT, PATCH, DELETE, GET, HEAD, OPTIONS, POST, and QUERY behavior is either aligned with HTTP
+  semantics or intentionally documented as a narrow non-portable contract.
+- API docs, tests, SDKs, generated clients, gateways, CORS rules, cache headers, and observability
+  agree with the chosen HTTP contract where relevant.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured tests or docs checks that exercise the HTTP method, status, header,
+cache, conditional request, QUERY, fallback, or generated-client contract from a caller's
+perspective. Do not infer raw browser, proxy, CDN, gateway, load-test, or live-network commands
+outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the contract source of truth is unclear, stop and report the competing route, schema, gateway,
+  docs, and SDK sources instead of editing only one surface.
+- If a method choice conflicts with existing callers, classify the compatibility risk and use
+  `api-contract-change` before changing public behavior.
+- If duplicate side effects, cache sharing, security, or streaming delivery risks are found, switch
+  to the narrower matching skill before finalizing that part.
+- If deterministic HTTP interoperability proof requires browser, gateway, CDN, proxy, or production
+  telemetry not configured in `.mustflow/config/commands.toml`, complete available local checks and
+  report the manual evidence gap.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- HTTP API semantics reviewed
+- Endpoint method ledger
+- Safe, idempotent, cacheable, request-body, URI-ownership, PUT, PATCH, DELETE, QUERY, conditional
+  request, status-code, header discovery, CORS, cache, retry, and intermediary findings
+- Fixes made or recommendations
+- Synchronized docs, tests, SDK, generated client, gateway, and cache surfaces
+- Evidence level: configured-test evidence, docs evidence, static review risk, manual-only,
+  missing, or not applicable
+- Command intents run
+- Skipped HTTP interoperability checks and reasons
+- Remaining HTTP semantics risk

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -216,6 +216,12 @@ route_type = "adjunct"
 priority = 69
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "security_change", "privacy_change", "data_change", "docs_change", "package_metadata_change"]
 
+[routes."http-api-semantics-review"]
+category = "general_code"
+route_type = "adjunct"
+priority = 81
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "performance_change", "security_change", "privacy_change", "data_change", "package_metadata_change", "release_risk"]
+
 [routes."error-message-integrity-review"]
 category = "general_code"
 route_type = "adjunct"

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.103.20"
+version = "2.103.22"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -14,6 +14,7 @@ creates = [
   ".mustflow/skills/routes.toml",
   ".mustflow/skills/adapter-boundary/SKILL.md",
   ".mustflow/skills/api-contract-change/SKILL.md",
+  ".mustflow/skills/http-api-semantics-review/SKILL.md",
   ".mustflow/skills/backend-reliability-change/SKILL.md",
   ".mustflow/skills/http-delivery-streaming/SKILL.md",
   ".mustflow/skills/artifact-integrity-check/SKILL.md",
@@ -226,6 +227,7 @@ available = ["minimal", "patterns", "oss", "team", "product", "library"]
 minimal = [
   "adapter-boundary",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "auth-permission-change",
@@ -373,6 +375,7 @@ patterns = [
   "architecture-deepening-review",
   "service-boundary-architecture",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "auth-permission-change",
@@ -528,6 +531,7 @@ patterns = [
 oss = [
   "adapter-boundary",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "artifact-integrity-check",
@@ -705,6 +709,7 @@ team = [
   "architecture-deepening-review",
   "service-boundary-architecture",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "auth-permission-change",
@@ -864,6 +869,7 @@ team = [
 product = [
   "adapter-boundary",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "service-boundary-architecture",
@@ -1028,6 +1034,7 @@ product = [
 library = [
   "adapter-boundary",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "artifact-integrity-check",