mustflow 2.74.0 → 2.74.2

package/README.md

@@ -334,7 +334,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.
+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.
 
 ## Language and profiles
 

package/dist/cli/commands/check.js

@@ -1,4 +1,5 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { acquireActiveCommandLock, GENERATED_SURFACE_READ_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { t } from '../lib/i18n.js';
 import { formatCliOptionParseError, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
@@ -43,36 +44,47 @@ export function runCheck(args, reporter, lang = 'en') {
         return 1;
     }
     const strict = hasParsedCliOption(options, '--strict');
-    const report = checkMustflowProjectReport(resolveMustflowRoot(), { strict });
-    const issues = report.issues;
-    const warnings = report.warnings;
-    const ok = issues.length === 0;
-    if (hasParsedCliOption(options, '--json')) {
-        reporter.stdout(JSON.stringify({
-            ok,
-            strict,
-            issueCount: issues.length,
-            issues,
-            warningCount: warnings.length,
-            warnings,
-            issueDetails: report.issueDetails,
-        }, null, 2));
-        return ok ? 0 : 1;
+    const projectRoot = resolveMustflowRoot();
+    const activeLock = acquireActiveCommandLock(projectRoot, 'mf check', GENERATED_SURFACE_READ_EFFECTS);
+    if (!activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf check', activeLock.conflicts, 'mf check --help', lang);
+        return 1;
     }
-    if (ok) {
-        for (const warning of warnings) {
-            reporter.stderr(warning);
+    try {
+        const report = checkMustflowProjectReport(projectRoot, { strict });
+        const issues = report.issues;
+        const warnings = report.warnings;
+        const ok = issues.length === 0;
+        if (hasParsedCliOption(options, '--json')) {
+            reporter.stdout(JSON.stringify({
+                ok,
+                strict,
+                issueCount: issues.length,
+                issues,
+                warningCount: warnings.length,
+                warnings,
+                issueDetails: report.issueDetails,
+            }, null, 2));
+            return ok ? 0 : 1;
         }
-        if (strict) {
-            reporter.stdout(t(lang, 'check.result.strictPassed'));
+        if (ok) {
+            for (const warning of warnings) {
+                reporter.stderr(warning);
+            }
+            if (strict) {
+                reporter.stdout(t(lang, 'check.result.strictPassed'));
+                return 0;
+            }
+            reporter.stdout(t(lang, 'check.result.passed'));
             return 0;
         }
-        reporter.stdout(t(lang, 'check.result.passed'));
-        return 0;
+        for (const issue of issues) {
+            reporter.stderr(issue);
+        }
+        reporter.stderr(t(lang, 'check.result.failed', { count: issues.length }));
+        return 1;
     }
-    for (const issue of issues) {
-        reporter.stderr(issue);
+    finally {
+        activeLock.handle.release();
     }
-    reporter.stderr(t(lang, 'check.result.failed', { count: issues.length }));
-    return 1;
 }

package/dist/cli/commands/doctor.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { acquireActiveCommandLock, GENERATED_SURFACE_READ_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { getAgentContext, } from '../lib/agent-context.js';
 import { t } from '../lib/i18n.js';
 import { getLocalIndexDatabasePath } from '../lib/local-index.js';
@@ -278,11 +279,22 @@ export function runDoctor(args, reporter, lang = 'en') {
         printUsageError(reporter, formatCliOptionParseError(options.error, lang), 'mf doctor --help', getDoctorHelp(lang), lang);
         return 1;
     }
-    const output = createDoctorOutput(hasParsedCliOption(options, '--strict'));
-    if (hasParsedCliOption(options, '--json')) {
-        reporter.stdout(JSON.stringify(output, null, 2));
+    const projectRoot = resolveMustflowRoot();
+    const activeLock = acquireActiveCommandLock(projectRoot, 'mf doctor', GENERATED_SURFACE_READ_EFFECTS);
+    if (!activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf doctor', activeLock.conflicts, 'mf doctor --help', lang);
+        return 1;
+    }
+    try {
+        const output = createDoctorOutput(hasParsedCliOption(options, '--strict'));
+        if (hasParsedCliOption(options, '--json')) {
+            reporter.stdout(JSON.stringify(output, null, 2));
+            return output.ok ? 0 : 1;
+        }
+        reporter.stdout(renderDoctorOutput(output, lang));
         return output.ok ? 0 : 1;
     }
-    reporter.stdout(renderDoctorOutput(output, lang));
-    return output.ok ? 0 : 1;
+    finally {
+        activeLock.handle.release();
+    }
 }

package/dist/cli/commands/index.js

@@ -1,4 +1,5 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { acquireActiveCommandLock, LOCAL_INDEX_WRITE_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { t } from '../lib/i18n.js';
 import { createLocalIndex } from '../lib/local-index.js';
 import { formatCliOptionParseError, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
@@ -83,15 +84,29 @@ export async function runIndex(args, reporter, lang = 'en') {
         printUsageError(reporter, formatCliOptionParseError(parsed.error, lang), 'mf index --help', getIndexHelp(lang), lang);
         return 1;
     }
-    const result = await createLocalIndex(resolveMustflowRoot(), {
-        dryRun: hasParsedCliOption(parsed, '--dry-run'),
-        includeSource: hasParsedCliOption(parsed, '--source'),
-        incremental: hasParsedCliOption(parsed, '--incremental'),
-    });
-    if (hasParsedCliOption(parsed, '--json')) {
-        reporter.stdout(JSON.stringify(result, null, 2));
+    const dryRun = hasParsedCliOption(parsed, '--dry-run');
+    const projectRoot = resolveMustflowRoot();
+    const activeLock = dryRun ? null : acquireActiveCommandLock(projectRoot, 'mf index', LOCAL_INDEX_WRITE_EFFECTS);
+    if (activeLock && !activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf index', activeLock.conflicts, 'mf index --help', lang);
+        return 1;
+    }
+    try {
+        const result = await createLocalIndex(projectRoot, {
+            dryRun,
+            includeSource: hasParsedCliOption(parsed, '--source'),
+            incremental: hasParsedCliOption(parsed, '--incremental'),
+        });
+        if (hasParsedCliOption(parsed, '--json')) {
+            reporter.stdout(JSON.stringify(result, null, 2));
+            return 0;
+        }
+        reporter.stdout(renderIndexSummary(result, lang));
         return 0;
     }
-    reporter.stdout(renderIndexSummary(result, lang));
-    return 0;
+    finally {
+        if (activeLock?.ok) {
+            activeLock.handle.release();
+        }
+    }
 }

package/dist/cli/commands/map.js

@@ -1,5 +1,6 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
+import { acquireActiveCommandLock, REPO_MAP_WRITE_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { generateRepoMap, writeRepoMap } from '../lib/repo-map.js';
@@ -71,13 +72,25 @@ export function runMap(args, reporter, lang = 'en') {
         shouldPrint = true;
     }
     const projectRoot = resolveMustflowRoot();
-    const content = generateRepoMap(projectRoot, { depth, includeNested });
-    if (shouldWrite) {
-        writeRepoMap(projectRoot, content);
-        reporter.stdout(t(lang, 'map.wrote'));
+    const activeLock = shouldWrite ? acquireActiveCommandLock(projectRoot, 'mf map --write', REPO_MAP_WRITE_EFFECTS) : null;
+    if (activeLock && !activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf map --write', activeLock.conflicts, 'mf map --help', lang);
+        return 1;
+    }
+    try {
+        const content = generateRepoMap(projectRoot, { depth, includeNested });
+        if (shouldWrite) {
+            writeRepoMap(projectRoot, content);
+            reporter.stdout(t(lang, 'map.wrote'));
+        }
+        if (shouldPrint) {
+            reporter.stdout(content);
+        }
+        return 0;
     }
-    if (shouldPrint) {
-        reporter.stdout(content);
+    finally {
+        if (activeLock?.ok) {
+            activeLock.handle.release();
+        }
     }
-    return 0;
 }

package/dist/cli/commands/run.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
-import { acquireActiveRunLock } from '../../core/active-run-locks.js';
+import { ACTIVE_RUN_LOCK_ID_ENV, acquireActiveRunLock } from '../../core/active-run-locks.js';
 import { createCommandEnv } from '../../core/command-env.js';
 import { createCorrelationId } from '../../core/correlation-id.js';
 import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.js';
@@ -360,6 +360,7 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
     try {
         const runReceiptPolicy = profiler.measure('retention_policy', () => resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot)));
         const env = profiler.measure('environment', () => createCommandEnv(projectRoot, { policy: plan.envPolicy, allowlist: plan.envAllowlist }));
+        env[ACTIVE_RUN_LOCK_ID_ENV] = activeRunLock.handle.record.run_id;
         const writeTracker = profiler.measure('write_drift_before', () => startRunWriteTracking(projectRoot, contract, intentName, {
             additionalDeclaredPaths: options.additionalDeclaredWritePaths,
             env,

package/dist/cli/commands/update.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { copyFileInsideWithoutSymlinks, ensureFileTargetInsideWithoutSymlinks, ensureInside, writeUtf8FileInsideWithoutSymlinks, } from '../lib/filesystem.js';
 import { MANIFEST_LOCK_RELATIVE_PATH, readManifestLock, sha256File } from '../lib/manifest-lock.js';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { acquireActiveCommandLock, MUSTFLOW_UPDATE_APPLY_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { t } from '../lib/i18n.js';
 import { formatCliOptionParseError, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
@@ -430,53 +431,65 @@ export function runUpdate(args, reporter, lang = 'en') {
         return 1;
     }
     const projectRoot = resolveMustflowRoot();
-    const plan = createUpdatePlan(projectRoot);
-    if (plan.error) {
-        if (wantsJson) {
-            reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), plan.error, false), requestedMode), null, 2));
-            return 1;
-        }
-        reporter.stderr(plan.error);
+    const activeLock = wantsApply ? acquireActiveCommandLock(projectRoot, 'mf update --apply', MUSTFLOW_UPDATE_APPLY_EFFECTS) : null;
+    if (activeLock && !activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf update --apply', activeLock.conflicts, 'mf update --help', lang);
         return 1;
     }
-    const outputItems = wantsDiff ? withDiffPreviews(projectRoot, plan.items) : publicPlanItems(plan.items);
-    const dryRunOutput = withMode(planOutput(outputItems, undefined, false), requestedMode);
-    if (wantsDryRun) {
-        if (wantsJson) {
-            reporter.stdout(JSON.stringify(dryRunOutput, null, 2));
+    try {
+        const plan = createUpdatePlan(projectRoot);
+        if (plan.error) {
+            if (wantsJson) {
+                reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), plan.error, false), requestedMode), null, 2));
+                return 1;
+            }
+            reporter.stderr(plan.error);
+            return 1;
+        }
+        const outputItems = wantsDiff ? withDiffPreviews(projectRoot, plan.items) : publicPlanItems(plan.items);
+        const dryRunOutput = withMode(planOutput(outputItems, undefined, false), requestedMode);
+        if (wantsDryRun) {
+            if (wantsJson) {
+                reporter.stdout(JSON.stringify(dryRunOutput, null, 2));
+                return dryRunOutput.ok ? 0 : 1;
+            }
+            printPlan(dryRunOutput, reporter, lang);
+            if (wantsDiff) {
+                printDiffPreviews(dryRunOutput.items, reporter, lang);
+            }
+            reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
             return dryRunOutput.ok ? 0 : 1;
         }
-        printPlan(dryRunOutput, reporter, lang);
-        if (wantsDiff) {
-            printDiffPreviews(dryRunOutput.items, reporter, lang);
+        if (!dryRunOutput.ok) {
+            if (wantsJson) {
+                reporter.stdout(JSON.stringify(dryRunOutput, null, 2));
+                return 1;
+            }
+            printPlan(dryRunOutput, reporter, lang);
+            reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
+            return 1;
         }
-        reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
-        return dryRunOutput.ok ? 0 : 1;
-    }
-    if (!dryRunOutput.ok) {
         if (wantsJson) {
-            reporter.stdout(JSON.stringify(dryRunOutput, null, 2));
-            return 1;
+            const applicableItems = plan.items.filter((item) => item.action === 'create' || item.action === 'update');
+            const applyResult = applyUpdate(projectRoot, applicableItems, {
+                stdout: () => undefined,
+                stderr: (message) => reporter.stderr(message),
+            }, lang);
+            reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), undefined, applyResult.wroteFiles), 'apply'), null, 2));
+            return 0;
         }
-        printPlan(dryRunOutput, reporter, lang);
-        reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
-        return 1;
-    }
-    if (wantsJson) {
-        const applicableItems = plan.items.filter((item) => item.action === 'create' || item.action === 'update');
-        const applyResult = applyUpdate(projectRoot, applicableItems, {
-            stdout: () => undefined,
-            stderr: (message) => reporter.stderr(message),
-        }, lang);
-        reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), undefined, applyResult.wroteFiles), 'apply'), null, 2));
+        const applyResult = applyUpdate(projectRoot, plan.items, reporter, lang);
+        if (!applyResult.wroteFiles) {
+            reporter.stdout(t(lang, 'update.plan.noUpdates'));
+            reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
+            return 0;
+        }
+        reporter.stdout(t(lang, 'update.complete', { updated: applyResult.updated, created: applyResult.created }));
         return 0;
     }
-    const applyResult = applyUpdate(projectRoot, plan.items, reporter, lang);
-    if (!applyResult.wroteFiles) {
-        reporter.stdout(t(lang, 'update.plan.noUpdates'));
-        reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
-        return 0;
+    finally {
+        if (activeLock?.ok) {
+            activeLock.handle.release();
+        }
     }
-    reporter.stdout(t(lang, 'update.complete', { updated: applyResult.updated, created: applyResult.created }));
-    return 0;
 }

package/dist/cli/lib/active-command-lock.js

@@ -0,0 +1,96 @@
+import { ACTIVE_RUN_LOCK_ID_ENV, acquireActiveRunLock, } from '../../core/active-run-locks.js';
+import { renderCliError } from './cli-output.js';
+import { t } from './i18n.js';
+export const REPO_MAP_WRITE_EFFECTS = [
+    { type: 'write', mode: 'replace', path: 'REPO_MAP.md', concurrency: 'exclusive' },
+];
+export const LOCAL_INDEX_WRITE_EFFECTS = [
+    {
+        type: 'write',
+        mode: 'replace',
+        path: '.mustflow/cache/**',
+        lock: 'local_index_cache',
+        concurrency: 'exclusive',
+    },
+];
+export const MUSTFLOW_UPDATE_APPLY_EFFECTS = [
+    { type: 'write', mode: 'replace', path: 'AGENTS.md', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/config/manifest.lock.toml', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/config/commands.toml', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/config/mustflow.toml', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/config/preferences.toml', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/context/**', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/docs/**', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/skills/**', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/backups/**', concurrency: 'exclusive' },
+];
+export const GENERATED_SURFACE_READ_EFFECTS = [
+    { type: 'read', mode: 'read', path: 'REPO_MAP.md', concurrency: 'shared' },
+    { type: 'read', mode: 'read', path: '.mustflow/config/manifest.lock.toml', concurrency: 'shared' },
+    {
+        type: 'read',
+        mode: 'read',
+        path: '.mustflow/cache/**',
+        lock: 'local_index_cache',
+        concurrency: 'shared',
+    },
+];
+function effectToToml(effect) {
+    const output = {
+        type: effect.type,
+    };
+    if (effect.mode) {
+        output.mode = effect.mode;
+    }
+    if (effect.path) {
+        output.path = effect.path;
+    }
+    if (effect.paths) {
+        output.paths = [...effect.paths];
+    }
+    if (effect.lock) {
+        output.lock = effect.lock;
+    }
+    if (effect.concurrency) {
+        output.concurrency = effect.concurrency;
+    }
+    return output;
+}
+function createSyntheticCommandContract(intentName, effects) {
+    return {
+        defaults: { default_cwd: '.' },
+        resources: {},
+        intents: {
+            [intentName]: {
+                cwd: '.',
+                writes: [],
+                effects: effects.map(effectToToml),
+            },
+        },
+    };
+}
+function parentRunId() {
+    const value = process.env[ACTIVE_RUN_LOCK_ID_ENV]?.trim();
+    return value && value.length > 0 ? value : null;
+}
+export function acquireActiveCommandLock(projectRoot, displayName, effects) {
+    return acquireActiveRunLock(projectRoot, createSyntheticCommandContract(displayName, effects), displayName, {
+        commandHash: null,
+        ignoreRunId: parentRunId(),
+        ignorePid: process.ppid,
+    });
+}
+export function renderActiveCommandLockConflictMessage(displayName, conflicts, lang) {
+    const [first] = conflicts;
+    const detail = first
+        ? t(lang, 'run.error.activeLockConflictDetail', {
+            lock: first.lock,
+            intent: first.conflictsWithIntent,
+            pid: first.conflictsWithPid,
+        })
+        : t(lang, 'run.error.activeLockConflictUnknown');
+    return t(lang, 'run.error.activeLockConflict', { intent: displayName, detail });
+}
+export function reportActiveCommandLockConflict(reporter, displayName, conflicts, helpCommand, lang) {
+    reporter.stderr(renderCliError(renderActiveCommandLockConflictMessage(displayName, conflicts, lang), helpCommand, lang));
+}

package/dist/core/active-run-locks.js

@@ -6,6 +6,7 @@ import { readUtf8FileInsideWithoutSymlinks, writeJsonFileInsideWithoutSymlinks,
 const ACTIVE_LOCK_SCHEMA_VERSION = '1';
 const ACTIVE_LOCK_KIND = 'active_run_lock';
 const LOCK_ROOT_RELATIVE_PATH = '.mustflow/state/locks';
+export const ACTIVE_RUN_LOCK_ID_ENV = 'MUSTFLOW_ACTIVE_RUN_LOCK_ID';
 const LOCK_MUTEX_STALE_MS = 30_000;
 const LOCK_MUTEX_WAIT_MS = 1_000;
 const LOCK_MUTEX_SLEEP_MS = 25;
@@ -462,7 +463,12 @@ export function acquireActiveRunLock(projectRoot, contract, intentName, options
             }
         }
         const staleRecordIds = new Set(staleRecords.map((stale) => stale.runId));
-        const liveRecords = records.filter((record) => !staleRecordIds.has(record.run_id));
+        const liveRecords = records.filter((record) => {
+            if (staleRecordIds.has(record.run_id)) {
+                return false;
+            }
+            return record.run_id !== options.ignoreRunId || record.pid !== options.ignorePid;
+        });
         const conflicts = findConflicts(intentName, effects, liveRecords);
         if (conflicts.length > 0) {
             return { ok: false, conflicts, recoveredStaleRecords: staleRecords };

package/package.json

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

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 172
+revision = 173
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -640,6 +640,12 @@ source_locale = "en"
 revision = 1
 translations = {}
 
+[documents."skill.support-surface-advisor"]
+source = "locales/en/.mustflow/skills/support-surface-advisor/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.svelte-code-change"]
 source = "locales/en/.mustflow/skills/svelte-code-change/SKILL.md"
 source_locale = "en"

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

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 172
+revision: 173
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -309,6 +309,10 @@ refer to `AGENTS.md` and `.mustflow/config/commands.toml` to implement the most
   rules, public contracts, external I/O, operational safety, failure handling, concurrency,
   data flow, or future change cost could be shaped by early structure decisions. Do not use it for
   surface-only changes or tiny local edits with no boundary pressure.
+- Use `support-surface-advisor` as a primary route before building a product, app, service, CLI,
+  API, SDK, library, desktop app, automation tool, or developer tool when the agent must decide
+  which user, developer, operator, automation, integration, recovery, upgrade, or observability
+  routes are supported now, deferred, or explicitly not supported.
 - Use `secret-exposure-response` as an event route when a real or plausible secret value appears;
   do not treat redaction as proof that rotation, revocation, or history exposure is handled.
 - Use `evidence-stall-breaker` as an event route when the same read, list, search, path, or review
@@ -407,6 +411,7 @@ routes. Event routes stay inactive until their event occurs.
 | Code review or implementation needs transaction-boundary integrity triage for transactions, ORM atomic blocks, unit-of-work code, database write paths, service workflows, command handlers, webhook processors, queue consumers, framework transaction annotations, isolation levels, lock usage, rollback behavior, after-commit side effects, outbox patterns, retry handling, or transactional tests that can break a business invariant even when a transaction exists | `.mustflow/skills/transaction-boundary-integrity-review/SKILL.md` | Business invariant, transaction boundary, decision ledger, durable guard evidence, framework behavior, side-effect ledger, failure and retry evidence, test evidence, and configured command intents | Whole read-decision-write transaction boundaries, durable constraints, atomic upsert or conditional update, affected-row checks, version checks, correct lock target, transaction narrowing, after-commit or outbox side effects, idempotent retry classification, focused tests, and directly synchronized docs or templates | app-only `exists()` or `count` guard, stale read-decision-write, absent-row `FOR UPDATE` gap, `SKIP LOCKED` consistency misuse, READ COMMITTED snapshot myth, REPEATABLE READ engine mismatch, SERIALIZABLE without full retry, deadlock or serialization failure treated as plain 500, swallowed rollback trigger, Spring `rollbackFor` miss, self-invocation bypass, `readOnly` write assumption, inner rollback-only surprise, `REQUIRES_NEW` pool pressure, `NESTED` savepoint confusion, Django nested `atomic()` durability myth, pre-commit email/cache/queue side effect, HTTP API inside transaction, Hibernate flush-as-commit confusion, SQLAlchemy implicit transaction surprise, missing optimistic lock, advisory lock scope leak, wrong transaction manager, or transactional test hiding commit behavior | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Transaction boundary reviewed, invariant and decision ledger, durable-guard/lock/isolation/retry/rollback/side-effect findings, evidence level, verification, and remaining transaction-boundary integrity risk |
 | Code review or implementation needs testability-boundary triage for hidden decision inputs, direct time or randomness, direct I/O, constructor side effects, static or singleton state, oversized private logic, branch policy sprawl, boolean mode flags, broad option objects, implicit environment or request context, void side effects, swallowed errors, log-only outcomes, cache order dependence, ORM lazy loading, transaction and external-call coupling, hidden event publication, fire-and-forget async work, real-time retry waits, nondeterministic collection order, hidden defaults, mixed validation and policy, scattered authorization, framework magic, smart controllers, conditional DTO mapping, mock-heavy classes, call-order assertions, inheritance coupling, or reflection-only tests | `.mustflow/skills/testability-boundary-review/SKILL.md` | User goal, current diff or target files, behavior or decision under test, decision-input ledger, side-effect ledger, observability ledger, test friction evidence, and configured command intents | Explicit inputs, fixed clocks or generators, dependency seams, pure decision cores, shell and adapter boundaries, policy or strategy tables, observable results, deterministic ordering, focused tests, and directly synchronized docs or templates | hidden time/random, constructor work, global state, fat private method, boolean mode flags, broad option object, void side effect, swallowed or log-only failure, cache order dependence, ORM lazy loading, transaction/external call coupling, hidden event publication, fire-and-forget sleeps, real-time retry wait, nondeterministic order, hidden defaults, mixed validation/policy, scattered auth, framework magic, smart controller, conditional DTO policy, five or more mocks, fragile call-order tests, deep inheritance, or reflection-only tests | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `test_audit`, `docs_validate_fast`, `test_release`, `mustflow_check` | Testability boundary reviewed, decision inputs and side effects exposed, observability fixed or recommended, test friction evidence, verification, and remaining testability risk |
 | A coding task has missing intent, scope, domain, data, security, UX, dependency, architecture, or verification decisions that cannot be safely inferred from repository evidence | `.mustflow/skills/clarifying-question-gate/SKILL.md` | User request, inspected repository evidence, unresolved decisions, reversibility classification, recommended option, and tradeoffs | Blocking questions, safe assumptions, and the smallest safe implementation boundary | over-questioning, lazy questions, expensive wrong assumptions, user-owned decision drift, data loss, auth bypass, public-contract drift, dependency bloat, or unverifiable completion | `changes_status`, `changes_diff_summary`, `mustflow_check` | Repository evidence inspected, blocking questions with recommendations, safe assumptions, selected scope, verification, and remaining ambiguity |
+| 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, 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 |

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

@@ -366,6 +366,12 @@ route_type = "adjunct"
 priority = 42
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "security_change", "privacy_change", "data_change", "migration_change", "package_metadata_change"]
 
+[routes."support-surface-advisor"]
+category = "general_code"
+route_type = "primary"
+priority = 67
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "docs_change", "product_change", "package_metadata_change"]
+
 [routes."runtime-target-selection"]
 category = "general_code"
 route_type = "primary"

package/templates/default/locales/en/.mustflow/skills/support-surface-advisor/SKILL.md

@@ -0,0 +1,156 @@
+---
+mustflow_doc: skill.support-surface-advisor
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: support-surface-advisor
+description: Apply this skill when designing, scoping, implementing, or reviewing an app, service, CLI, API, SDK, library, desktop app, automation tool, or developer tool and the agent must decide which user, developer, operator, automation, integration, recovery, upgrade, documentation, or observability surfaces to expose, defer, or explicitly not support.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.support-surface-advisor
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Support Surface Advisor
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Help agents turn vague product or program-development requests into a bounded support contract. A support surface is not just a feature; once exposed, it becomes a compatibility, documentation, testing, and maintenance promise.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A user asks to build, scope, review, or evolve an app, service, CLI, API, SDK, library, desktop app, automation tool, or developer tool.
+- It is unclear whether the product should expose UI, CLI, programming API, network API, webhooks, plugins, configuration, import/export, docs, logs, diagnostics, test support, recovery, performance limits, security/privacy, accessibility/i18n, or deployment/upgrade support.
+- The user may be a solo founder, inexperienced developer, or product owner who knows the core idea but not the support routes real users will need.
+- Multiple shells could reach the same core behavior, such as UI plus CLI, CLI plus API, or UI plus webhook automation.
+- A support route might accidentally become a public API, stable file format, integration promise, operational runbook, or backward-compatibility burden.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is a tiny local bug fix with no product, integration, operation, or public-contract decision.
+- The user has already selected the support surfaces and only asks for implementation inside one route.
+- A narrower API, CLI output, UI, security, data, or release skill already owns the specific changed contract.
+- The work is only visual polish, copy editing, or one-off internal tooling with no exposed support promise.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Product stage: prototype, personal tool, team-internal tool, public SaaS, developer tool, library, CLI, desktop app, or another explicit stage.
+- Primary actors: end users, developers, operators, automation systems, support staff, admins, or third-party services.
+- Main usage path and the job it completes.
+- Integration need: scripts, CI, external services, webhooks, plugins, SDK calls, imports, exports, or manual-only use.
+- Public-contract willingness: which routes the user is ready to document, test, keep compatible, deprecate carefully, and support operationally.
+- Explicit non-goals: routes not supported now and routes kept internal-only.
+- Failure, recovery, upgrade, data movement, observability, security, privacy, accessibility, and localization expectations.
+- Current repository evidence, existing product docs, command contracts, APIs, or public examples when working in an existing codebase.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Treat every exposed support route as a maintenance contract, not as a free feature checkbox.
+- Do not ask for or recommend all support surfaces by default.
+- Distinguish what is supported now, deferred, explicitly not supported, and internal-only.
+- Keep command execution governed by `.mustflow/config/commands.toml`; this skill names intent concepts but does not authorize raw commands.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Ask focused scoping questions and propose a support-surface plan.
+- Update product docs, implementation notes, tests, route metadata, or code boundaries directly tied to the selected support surfaces.
+- Add only the selected surfaces and their tests/docs/contracts when the user asks for implementation.
+- Do not create duplicate business logic in UI, CLI, API, SDK, webhook, or plugin shells.
+- Do not expose internal functions, schemas, logs, error messages, settings, or file formats as public contracts by accident.
+- Do not put internal implementation explanations in user-facing UI copy.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the product stage and primary actors first. Do not recommend surfaces until you know who must use, integrate, operate, or recover the product.
+2. Identify the primary path. Pick the one route users should use first, such as UI for non-technical users, CLI for developer automation, SDK for library consumers, or network API for cross-service integration.
+3. Define the core engine boundary before adding shells.
+   - The core engine owns domain workflow, validation, state transitions, permissions, errors, data movement, and side-effect policy.
+   - UI, CLI, API, SDK, webhook, and plugin shells should translate inputs and outputs, call the core, and present results.
+   - UI, CLI, and API shells must not reimplement the same core rules separately.
+4. Ask only blocking questions. Prefer at most three at a time, with a recommended default when evidence supports it:
+   - Who will use this first: general users, developers, operators, admins, automation, or other services?
+   - What is the main route for the core job right now: UI, CLI, programming API/SDK, network API, or another route?
+   - Do scripts, CI, webhooks, imports, exports, or other services need integration in the next milestone?
+   - Which routes are you willing to keep stable, document, test, and migrate later?
+   - Which routes should be explicitly unsupported for now?
+   - What failure, recovery, upgrade, data movement, logging, privacy, and accessibility level is needed for the first real users?
+5. Use the support surface list as a risk prompt, not a checklist to fill:
+   - UI, CLI, programming API/SDK, network API, webhook/events, plugin/extension, configuration, auth/permissions, import/export, version/backcompat, deprecation/migration, docs/examples, errors/diagnostics, logs/observability, test support, failure recovery, performance/resource limits, security/privacy, accessibility/i18n, deployment/upgrade/recovery.
+6. Classify each relevant surface:
+   - `support_now`: a named actor needs it in the next milestone, the team can maintain it, the contract can be tested, and failure behavior is understood.
+   - `defer`: plausible later value exists, but there is no near-term user, integration, or operational capacity.
+   - `explicitly_not_supported`: exposing it would imply stable API, schema, data, security, operational, or compatibility promises the product is not ready to carry.
+   - `internal_only`: useful behind the scenes but not documented, not stable, and not safe for external reliance.
+7. Apply stage heuristics:
+   - Prototype or personal tool: one primary path, basic configuration, clear errors, a simple export or backup when data matters, and no SDK/webhooks/plugins unless they are the product.
+   - Team-internal tool: UI or CLI, role or environment boundaries, logs, import/export when data moves, upgrade notes, and enough docs for handoff.
+   - Public SaaS: UI, auth/permissions, security/privacy, diagnostics, recovery, observability, deployment/upgrade behavior, and docs; API/webhooks only when customers truly integrate.
+   - Developer tool or CLI: non-interactive execution, help text, exit codes, machine-readable output when scripts need it, configuration precedence, errors, docs, dry-run or test fixtures when side effects matter.
+   - Library or SDK: a narrow public API, typed errors, cancellation/resource cleanup where relevant, version/backcompat rules, examples, tests, and deprecation policy; no UI or network API unless that is the product.
+   - Desktop app: UI, settings, import/export or backup, upgrade/rollback expectations, crash diagnostics, accessibility/i18n baseline, and CLI/API only when automation is a real user need.
+8. Recommend a surface only when it has a real actor, near-term workflow, maintenance owner, compatibility story, and verification path.
+9. Explicitly defer or reject surfaces that duplicate the primary path, create a second core implementation, require unsupported operations capacity, or would lock internal data formats too early.
+10. For user-facing UI text, write natural product language. Do not leak implementation notes such as "this component handles..." or "this feature processes..." into visible copy.
+11. If implementation follows, activate the narrower skill for each selected surface before changing that surface, such as API contract, CLI output, UI quality, security/privacy, data migration, docs, or tests.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The recommended support surfaces are tied to actors, workflows, and maintenance capacity.
+- Deferred and explicitly unsupported surfaces are named instead of left as vague future work.
+- The core engine versus shell boundary prevents duplicated business logic across UI, CLI, API, SDK, webhook, and plugin routes.
+- Compatibility, docs, tests, failure, recovery, security, privacy, observability, accessibility, and upgrade risks are visible for every selected public route.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+When implementation changes code, schemas, templates, package metadata, or tests, also use the narrower configured intent named by the matching implementation skill.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the user cannot name users or a primary path, stop at questions and recommend the smallest reversible default.
+- If a desired route implies an unsupported public contract, mark it `defer` or `explicitly_not_supported` and explain the contract cost.
+- If UI, CLI, API, SDK, webhook, or plugin paths start duplicating core rules, move the rule decision to the core engine boundary before continuing.
+- If implementation requires a support surface whose verification intent is missing, report the missing verification instead of claiming readiness.
+- If the scope expands into every support route, reduce it to one primary route plus the minimum safety surfaces needed for the next real users.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Product stage and primary actors
+- Recommended support surfaces
+- Deferred support surfaces
+- Explicitly unsupported or internal-only surfaces
+- Immediate questions and recommended defaults
+- Maintenance contract and compatibility risks
+- Core engine versus shell boundary
+- Staged adoption plan
+- Follow-up skills needed for implementation
+- Command intents run
+- Skipped checks and reasons
+- Remaining support-surface risk

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.74.0"
+version = "2.74.2"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -93,6 +93,7 @@ creates = [
   ".mustflow/skills/rust-code-change/SKILL.md",
   ".mustflow/skills/runtime-target-selection/SKILL.md",
   ".mustflow/skills/structure-first-engineering/SKILL.md",
+  ".mustflow/skills/support-surface-advisor/SKILL.md",
   ".mustflow/skills/svelte-code-change/SKILL.md",
   ".mustflow/skills/tailwind-code-change/SKILL.md",
   ".mustflow/skills/tauri-code-change/SKILL.md",
@@ -331,6 +332,7 @@ minimal = [
   "task-instruction-authoring",
   "structure-discovery-gate",
   "structure-first-engineering",
+  "support-surface-advisor",
   "test-design-guard",
   "test-maintenance",
   "vertical-slice-tdd",
@@ -472,6 +474,7 @@ patterns = [
   "strategy-pattern",
   "structure-discovery-gate",
   "structure-first-engineering",
+  "support-surface-advisor",
   "test-design-guard",
   "test-maintenance",
   "vertical-slice-tdd",
@@ -631,6 +634,7 @@ oss = [
   "strategy-pattern",
   "structure-discovery-gate",
   "structure-first-engineering",
+  "support-surface-advisor",
   "test-design-guard",
   "test-maintenance",
   "vertical-slice-tdd",
@@ -775,6 +779,7 @@ team = [
   "strategy-pattern",
   "structure-discovery-gate",
   "structure-first-engineering",
+  "support-surface-advisor",
   "test-design-guard",
   "test-maintenance",
   "vertical-slice-tdd",
@@ -919,6 +924,7 @@ product = [
   "strategy-pattern",
   "structure-discovery-gate",
   "structure-first-engineering",
+  "support-surface-advisor",
   "test-design-guard",
   "test-maintenance",
   "vertical-slice-tdd",
@@ -1078,6 +1084,7 @@ library = [
   "strategy-pattern",
   "structure-discovery-gate",
   "structure-first-engineering",
+  "support-surface-advisor",
   "test-design-guard",
   "test-maintenance",
   "vertical-slice-tdd",