mustflow 1.17.0 → 1.18.14

package/README.md

@@ -55,7 +55,7 @@ flowchart TD
 
 `read_order` defines the required reading sequence, while `optional_read_order` and `[context]` control how task-specific context loads. The `[refresh]` policy sets when agents reread the same instructions.
 
-The skills index acts as an active routing step: agents compare the task with `.mustflow/skills/INDEX.md` and read matching `SKILL.md` files before editing that scope. This step is required before file edits even when `mf doctor` or `mf check` passes, because health checks do not decide which task procedure applies. Skills guide procedure only; command execution still comes from `.mustflow/config/commands.toml`.
+The skills index acts as an active routing step: agents compare the task with `.mustflow/skills/INDEX.md` and read matching `SKILL.md` files before editing that scope. This step is required before file edits even when `mf doctor` or `mf check` passes, because health checks do not decide which task procedure applies. When files are created or modified, the final report should include a concise skill-selection note. Skills guide procedure only; command execution still comes from `.mustflow/config/commands.toml`.
 
 ## Quick start
 
@@ -91,11 +91,11 @@ mustflow installs and validates an agent workflow for user projects.
 - Declares runnable command rules in `.mustflow/config/commands.toml`.
 - Checks installation health and configuration structure with `mf check` and `mf doctor`.
 - Classifies changed files, public surfaces, and validation reasons with `mf classify`.
-- Prints execution-free verification plans with `mf verify --plan-only --json`.
+- Prints execution-free verification plans with `mf verify --plan-only --json`, including read-only local-index lock explanations when available.
 - Runs only allowed one-shot commands within a timeout via `mf run <intent>` or `mf verify` when the selected intent is runnable.
 - Writes command receipts to `.mustflow/state/runs/latest.json`.
 - 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, 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, or source-content database.
+- 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, or source-content database.
 - Tracks agent-created or agent-modified documentation needing prose review with `mf docs review`.
 - Previews and applies bundled template updates safely with `mf update`.
 - Publishes JSON Schemas for automation-facing reports and command contracts in `schemas/`.
@@ -145,6 +145,8 @@ your-project/
       │  └─ SKILL.md
       ├─ date-number-audit/
       │  └─ SKILL.md
+      ├─ database-change-safety/
+      │  └─ SKILL.md
       ├─ dependency-reality-check/
       │  └─ SKILL.md
       ├─ diff-risk-review/
@@ -217,7 +219,8 @@ npx mf verify --from-plan .mustflow/state/change-plan.json --plan-only --json
 npx mf verify --from-plan .mustflow/state/change-plan.json --json
 ```
 
-Create the optional local search index if search capabilities are needed.
+Create the optional local search index if search capabilities are needed. Run the normal command
+when creating the index for the first time.
 
 ```sh
 npx mf index --dry-run --json
@@ -225,6 +228,13 @@ npx mf index
 npx mf search mustflow_check
 ```
 
+On later runs, use incremental mode when you want to reuse a compatible fresh cache without rewriting
+the SQLite file. If the cache is missing, stale, or incompatible, mustflow falls back to a full rebuild.
+
+```sh
+npx mf index --incremental --json
+```
+
 Preview template updates before applying them. Files marked as customized in `.mustflow/config/manifest.lock.toml` remain as repository-specific baselines while their current content matches the lock.
 
 ```sh
@@ -261,7 +271,7 @@ mf run mustflow_update_apply
 | `mf map --stdout` | Print the current mustflow root map to stdout. |
 | `mf map --write` | Create or update `REPO_MAP.md`. |
 | `mf run <intent>` | Run an allowed one-shot command. |
-| `mf index` | Build a SQLite index for mustflow docs, skill routes, command rules, and command-effect locks. |
+| `mf index` | Build a SQLite index for mustflow docs, skill routes, command rules, command-effect locks, and file fingerprints. Use `--incremental` to reuse a compatible fresh index without rewriting it. |
 | `mf search <query>` | Search docs, skills, skill routes, command rules, and command-effect locks in the SQLite index. |
 | `mf status` | Inspect installed state and changed or missing files. |
 | `mf update --dry-run` | Calculate a template update plan without writing files. |
@@ -294,7 +304,7 @@ Runnable work is declared in `.mustflow/config/commands.toml` so agents do not g
 
 Development servers, watch modes, browser UIs, interactive commands, and background processes do not run directly.
 
-Use `mf verify --reason <event> --plan-only --json` to inspect matching verification intents and missing runnable coverage without executing commands.
+Use `mf verify --reason <event> --plan-only --json` to inspect matching verification intents and missing runnable coverage without executing commands. When `.mustflow/cache/mustflow.sqlite` is fresh, scheduled entries include read-only `effectGraph` metadata for write locks and lock conflicts.
 
 Each command run writes the latest run record to `.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.
 
@@ -379,7 +389,7 @@ mf run docs_validate
 mf run mustflow_check
 ```
 
-The Bun scripts remain available for human maintainers and release packaging. `test_fast` runs the fast CLI regression baseline, `test_related` selects tests from changed files and falls back to the fast baseline, and `test_release` keeps package metadata and packaging checks out of routine local edits. `test_coverage` runs the fast CLI baseline through Node's built-in coverage report with no enforced threshold; set `MUSTFLOW_TEST_COVERAGE_CONCURRENCY=1`, `2`, or another positive integer to adjust worker count on local machines. `lint` and test-audit are configured as narrow repository-local gates. `docs_validate_fast` checks documentation navigation and localized content links without building the entire static site; `docs_validate` performs the full static documentation build, search index, and sitemap gate for release-sensitive changes.
+The Bun scripts remain available for human maintainers and release packaging. `test_fast` runs the fast CLI regression baseline, `test_related` selects tests from changed files and falls back to the fast baseline, and both use 8 Node test workers by default. Set `MUSTFLOW_TEST_CONCURRENCY=1`, `2`, or another positive integer to tune those workers on local machines. `test_release` keeps package metadata and packaging checks out of routine local edits. `test_coverage` runs the fast CLI baseline through Node's built-in coverage report with no enforced threshold; set `MUSTFLOW_TEST_COVERAGE_CONCURRENCY=1`, `2`, or another positive integer to adjust its worker count. `lint` and test-audit are configured as narrow repository-local gates. `docs_validate_fast` checks documentation navigation and localized content links without building the entire static site; `docs_validate` performs the full static documentation build, search index, and sitemap gate for release-sensitive changes.
 
 `dist/` is a generated build output and is not committed. `npm pack` and `npm publish` run `npm run build` via `prepack`, so the npm package contains the built CLI.
 

package/dist/cli/commands/context.js

@@ -42,7 +42,7 @@ function parseCacheProfile(args) {
     }
     return { profile: value, error: null };
 }
-export function runContext(args, reporter, lang = 'en') {
+export async function runContext(args, reporter, lang = 'en') {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getContextHelp(lang));
         return 0;
@@ -77,7 +77,7 @@ export function runContext(args, reporter, lang = 'en') {
     const mustflowRoot = resolveMustflowRoot();
     if (args.includes('--json')) {
         if (cacheProfile.profile) {
-            reporter.stdout(JSON.stringify(getPromptCacheProfileContext(mustflowRoot, cacheProfile.profile), null, 2));
+            reporter.stdout(JSON.stringify(await getPromptCacheProfileContext(mustflowRoot, cacheProfile.profile), null, 2));
             return 0;
         }
         const context = getAgentContext(mustflowRoot);

package/dist/cli/commands/dashboard.js

@@ -4,7 +4,7 @@ import http from 'node:http';
 import path from 'node:path';
 import { openPathInFileManager, openUrlInBrowser } from '../lib/browser-open.js';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
-import { renderDashboardHtml } from '../lib/dashboard-html.js';
+import { renderDashboardHtml, } from '../lib/dashboard-html.js';
 import { DASHBOARD_VERIFICATION_MAX_FILE_MATCHES, createDashboardVerificationSnapshot, } from '../../core/dashboard-verification.js';
 import { parseSkillIndexRoutes } from '../../core/skill-route-alignment.js';
 import { getAgentContext } from '../lib/agent-context.js';
@@ -13,6 +13,7 @@ import { isRecord, readCommandContract, readPositiveInteger, readString, readStr
 import { readDashboardPreferences, updateDashboardPreferences, } from '../lib/dashboard-preferences.js';
 import { DOC_REVIEW_LEDGER_RELATIVE_PATH, isDocReviewStatus, isReviewerKind, listDocReviewEntries, markDocReviewEntry, } from '../lib/doc-review-ledger.js';
 import { inspectManifestLock } from '../lib/manifest-lock.js';
+import { readLocalCommandEffectGraphs } from '../lib/local-index.js';
 import { readPackageMetadata } from '../lib/package-info.js';
 import { t } from '../lib/i18n.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
@@ -278,7 +279,55 @@ function readDashboardCommandContract(projectRoot) {
         return null;
     }
 }
-function renderCommandContractResponse(contract) {
+function toDashboardCommandEffectGraphStatus(graph) {
+    return {
+        source: graph.source,
+        status: graph.status,
+        database_path: graph.databasePath,
+        index_fresh: graph.indexFresh,
+        stale_paths: graph.stalePaths,
+        refresh_hint: graph.refreshHint,
+    };
+}
+function toDashboardCommandEffectGraph(graph) {
+    return {
+        ...toDashboardCommandEffectGraphStatus(graph),
+        write_locks: graph.writeLocks.map((writeLock) => ({
+            lock: writeLock.lock,
+            paths: writeLock.paths,
+            modes: writeLock.modes,
+            sources: writeLock.sources,
+            concurrencies: writeLock.concurrencies,
+            effect_count: writeLock.effectCount,
+        })),
+        lock_conflicts: graph.lockConflicts.map((conflict) => ({
+            intent: conflict.intent,
+            lock: conflict.lock,
+            paths: conflict.paths,
+            modes: conflict.modes,
+            concurrencies: conflict.concurrencies,
+            conflicting_paths: conflict.conflictingPaths,
+            conflicting_modes: conflict.conflictingModes,
+            conflicting_concurrencies: conflict.conflictingConcurrencies,
+        })),
+    };
+}
+async function readCommandEffectGraphMap(projectRoot, intentNames) {
+    if (intentNames.length === 0) {
+        return { graphs: new Map() };
+    }
+    const graphs = new Map();
+    let status;
+    const localGraphs = await readLocalCommandEffectGraphs(projectRoot, intentNames);
+    for (const [intentName, graph] of localGraphs) {
+        status ??= toDashboardCommandEffectGraphStatus(graph);
+        if (graph.status === 'fresh') {
+            graphs.set(intentName, toDashboardCommandEffectGraph(graph));
+        }
+    }
+    return { status, graphs };
+}
+async function renderCommandContractResponse(projectRoot, contract) {
     if (!contract) {
         return {
             path: '.mustflow/config/commands.toml',
@@ -321,10 +370,15 @@ function renderCommandContractResponse(contract) {
             },
         ];
     });
+    const effectGraphs = await readCommandEffectGraphMap(projectRoot, intents.map((intent) => intent.name));
     return {
         path: '.mustflow/config/commands.toml',
         exists: true,
-        intents,
+        effect_graph_status: effectGraphs.status,
+        intents: intents.map((intent) => {
+            const graph = effectGraphs.graphs.get(intent.name);
+            return graph ? { ...intent, effect_graph: graph } : intent;
+        }),
     };
 }
 function pathMatches(filePath, patterns) {
@@ -475,13 +529,13 @@ function renderRunHistoryResponse(projectRoot) {
         };
     }
 }
-function renderStatusResponse(projectRoot) {
+async function renderStatusResponse(projectRoot) {
     const context = getAgentContext(projectRoot);
     const manifest = inspectManifestLock(projectRoot);
     const lock = manifest.readResult.kind === 'present' ? manifest.readResult.lock : undefined;
     const activeDocuments = listDocReviewEntries(projectRoot);
     const rawCommandContract = readDashboardCommandContract(projectRoot);
-    const commandContract = renderCommandContractResponse(rawCommandContract);
+    const commandContract = await renderCommandContractResponse(projectRoot, rawCommandContract);
     const gitChangedFiles = readGitChangedFiles(projectRoot);
     const packageMetadata = readPackageMetadata();
     return {
@@ -536,7 +590,7 @@ export async function runDashboard(args, reporter, lang = 'en') {
                     'cache-control': 'no-store',
                     'content-type': 'text/html; charset=utf-8',
                 });
-                response.end(renderDashboardHtml(readDashboardPreferences(projectRoot), token, renderStatusResponse(projectRoot), renderDocReviewResponse(projectRoot, new URL('/api/docs/review', 'http://localhost'))));
+                response.end(renderDashboardHtml(readDashboardPreferences(projectRoot), token, await renderStatusResponse(projectRoot), renderDocReviewResponse(projectRoot, new URL('/api/docs/review', 'http://localhost'))));
                 return;
             }
             if (request.method === 'GET' && requestUrl.pathname === '/favicon.ico') {
@@ -550,7 +604,7 @@ export async function runDashboard(args, reporter, lang = 'en') {
                     return;
                 }
                 if (request.method === 'GET') {
-                    sendJson(response, 200, renderStatusResponse(projectRoot));
+                    sendJson(response, 200, await renderStatusResponse(projectRoot));
                     return;
                 }
             }

package/dist/cli/commands/explain.js

@@ -10,6 +10,7 @@ import { explainSkillRouteAlignment, } from '../../core/skill-route-alignment.js
 import { explainPublicSurface } from '../../core/public-surface-explanation.js';
 import { explainSourceAnchor } from '../../core/source-anchor-explanation.js';
 import { checkMustflowProject } from '../lib/validation.js';
+import { readLocalCommandEffectGraph, readLocalPathSurface, } from '../lib/local-index.js';
 const EXPLAIN_SCHEMA_VERSION = '1';
 export function getExplainHelp(lang = 'en') {
     return renderHelp({
@@ -71,13 +72,15 @@ function getAnchorExplainOutput(projectRoot, anchorId) {
         decision: explainSourceAnchor(projectRoot, anchorId),
     };
 }
-function getCommandExplainOutput(projectRoot, commandName) {
+async function getCommandExplainOutput(projectRoot, commandName) {
+    const decision = explainCommandIntent(readCommandContract(projectRoot), commandName);
+    const effectGraph = decision.intent ? await readLocalCommandEffectGraph(projectRoot, commandName) : undefined;
     return {
         schema_version: EXPLAIN_SCHEMA_VERSION,
         command: 'explain',
         topic: 'command',
         mustflow_root: projectRoot,
-        decision: explainCommandIntent(readCommandContract(projectRoot), commandName),
+        decision: effectGraph ? { ...decision, effectGraph } : decision,
     };
 }
 function getRetentionExplainOutput(projectRoot) {
@@ -107,13 +110,15 @@ function getSkillExplainOutput(projectRoot, skillName) {
         decision: explainSkillRoute(projectRoot, skillName),
     };
 }
-function getSurfaceExplainOutput(projectRoot, pathArg) {
+async function getSurfaceExplainOutput(projectRoot, pathArg) {
+    const decision = explainPublicSurface(pathArg);
+    const readModel = await readLocalPathSurface(projectRoot, pathArg);
     return {
         schema_version: EXPLAIN_SCHEMA_VERSION,
         command: 'explain',
         topic: 'surface',
         mustflow_root: projectRoot,
-        decision: explainPublicSurface(pathArg),
+        decision: { ...decision, readModel },
     };
 }
 function formatNullable(value, lang) {
@@ -160,6 +165,28 @@ function renderExplainDecision(output, lang) {
         const intent = output.decision.intent;
         lines.push('', t(lang, 'explain.label.commandIntent'), `- ${t(lang, 'explain.label.commandName')}: ${intent.name}`, `- status: ${intent.status ?? t(lang, 'value.none')}`, `- lifecycle: ${intent.lifecycle ?? t(lang, 'value.none')}`, `- run_policy: ${intent.runPolicy ?? t(lang, 'value.none')}`, `- stdin: ${intent.stdin ?? t(lang, 'value.none')}`, `- timeout_seconds: ${intent.timeoutSeconds ?? t(lang, 'value.none')}`, `- mode: ${intent.mode}`, `- cwd: ${intent.cwd ?? t(lang, 'value.none')}`, `- writes: ${intent.writes.join(', ') || t(lang, 'value.none')}`, `- network: ${formatNullable(intent.network, lang)}`, `- destructive: ${formatNullable(intent.destructive, lang)}`, `- success_exit_codes: ${intent.successExitCodes.join(', ') || t(lang, 'value.none')}`, `- required_after: ${intent.requiredAfter.join(', ') || t(lang, 'value.none')}`);
     }
+    if ('effectGraph' in output.decision && output.decision.effectGraph) {
+        const graph = output.decision.effectGraph;
+        lines.push('', 'Command effect graph', `- source: ${graph.source}`, `- status: ${graph.status}`, `- index_fresh: ${graph.indexFresh ? t(lang, 'value.yes') : t(lang, 'value.no')}`);
+        if (graph.refreshHint) {
+            lines.push(`- refresh_hint: ${graph.refreshHint}`);
+        }
+        if (graph.stalePaths.length > 0) {
+            lines.push(`- stale_paths: ${graph.stalePaths.join(', ')}`);
+        }
+        if (graph.writeLocks.length > 0) {
+            lines.push('- write_locks:');
+            for (const lock of graph.writeLocks) {
+                lines.push(`  - ${lock.lock}`, `    paths: ${lock.paths.join(', ') || t(lang, 'value.none')}`, `    modes: ${lock.modes.join(', ') || t(lang, 'value.none')}`, `    concurrencies: ${lock.concurrencies.join(', ') || t(lang, 'value.none')}`);
+            }
+        }
+        if (graph.lockConflicts.length > 0) {
+            lines.push('- lock_conflicts:');
+            for (const conflict of graph.lockConflicts) {
+                lines.push(`  - ${conflict.intent} (${conflict.lock})`, `    paths: ${conflict.paths.join(', ') || t(lang, 'value.none')}`, `    conflicting_paths: ${conflict.conflictingPaths.join(', ') || t(lang, 'value.none')}`);
+            }
+        }
+    }
     if ('retention' in output.decision) {
         const retention = output.decision.retention;
         lines.push('', t(lang, 'explain.label.retentionPolicy'), `- enabled: ${formatNullable(retention.enabled, lang)}`, `- raw_events.store: ${formatNullable(retention.rawEvents.store, lang)}`, `- raw_events.on_limit: ${formatNullable(retention.rawEvents.onLimit, lang)}`, `- run_receipts.store: ${retention.runReceipts.store}`, `- run_receipts.max_file_kb: ${retention.runReceipts.maxFileKb}`, `- run_receipts.max_items: ${retention.runReceipts.maxItems}`, `- run_receipts.keep_stdout_tail_bytes: ${retention.runReceipts.stdoutTailBytes}`, `- run_receipts.keep_stderr_tail_bytes: ${retention.runReceipts.stderrTailBytes}`, `- knowledge.enabled: ${formatNullable(retention.knowledge.enabled, lang)}`, `- context.max_file_kb: ${retention.context.maxFileKb}`, `- repo_map.max_file_kb: ${retention.repoMap.maxFileKb}`, `- repo_map.fail_if_larger: ${formatNullable(retention.repoMap.failIfLarger, lang)}`);
@@ -187,6 +214,19 @@ function renderExplainDecision(output, lang) {
     if ('surface' in output.decision) {
         const surface = output.decision.surface;
         lines.push('', t(lang, 'explain.label.publicSurface'), `- kind: ${surface.kind}`, `- category: ${surface.category}`, `- is_public_surface: ${surface.isPublicSurface ? t(lang, 'value.yes') : t(lang, 'value.no')}`, `- ${t(lang, 'explain.label.validationReasons')}: ${surface.validationReasons.join(', ') || t(lang, 'value.none')}`, `- ${t(lang, 'explain.label.affectedContracts')}: ${surface.affectedContracts.join(', ') || t(lang, 'value.none')}`, `- ${t(lang, 'classify.label.updatePolicy')}: ${surface.updatePolicy}`, `- ${t(lang, 'classify.label.driftChecks')}: ${surface.driftChecks.join(', ') || t(lang, 'value.none')}`);
+        const readModel = output.decision.readModel;
+        if (readModel) {
+            lines.push('', 'Local index path-surface model', `- status: ${readModel.status}`, `- index_fresh: ${readModel.indexFresh ? t(lang, 'value.yes') : t(lang, 'value.no')}`);
+            if (readModel.refreshHint) {
+                lines.push(`- refresh_hint: ${readModel.refreshHint}`);
+            }
+            if (readModel.stalePaths.length > 0) {
+                lines.push(`- stale_paths: ${readModel.stalePaths.join(', ')}`);
+            }
+            if (readModel.match) {
+                lines.push(`- rule_id: ${readModel.match.ruleId}`, `- pattern: ${readModel.match.pattern}`, `- change_kinds: ${readModel.match.changeKinds.join(', ') || t(lang, 'value.none')}`);
+            }
+        }
     }
     if ('anchor' in output.decision) {
         const anchor = output.decision.anchor;
@@ -200,7 +240,7 @@ function renderExplainDecision(output, lang) {
     }
     return lines.join('\n');
 }
-export function runExplain(args, reporter, lang = 'en') {
+export async function runExplain(args, reporter, lang = 'en') {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getExplainHelp(lang));
         return 0;
@@ -269,7 +309,7 @@ export function runExplain(args, reporter, lang = 'en') {
             output = getAuthorityExplainOutput(projectRoot, targetArg);
             break;
         case 'command':
-            output = getCommandExplainOutput(projectRoot, targetArg);
+            output = await getCommandExplainOutput(projectRoot, targetArg);
             break;
         case 'retention':
             output = getRetentionExplainOutput(projectRoot);
@@ -278,7 +318,7 @@ export function runExplain(args, reporter, lang = 'en') {
             output = getSkillExplainOutput(projectRoot, targetArg);
             break;
         case 'surface':
-            output = getSurfaceExplainOutput(projectRoot, targetArg);
+            output = await getSurfaceExplainOutput(projectRoot, targetArg);
             break;
         case 'skills':
             output = getSkillsExplainOutput(projectRoot);

package/dist/cli/commands/index.js

@@ -15,10 +15,14 @@ export function getIndexHelp(lang = 'en') {
                 label: '--source',
                 description: t(lang, 'index.help.option.source'),
             },
+            {
+                label: '--incremental',
+                description: t(lang, 'index.help.option.incremental'),
+            },
             { label: '--json', description: t(lang, 'cli.option.json') },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
-        examples: ['mf index --dry-run --json', 'mf index', 'mf index --json'],
+        examples: ['mf index --dry-run --json', 'mf index', 'mf index --incremental --json'],
         exitCodes: [
             {
                 label: '0',
@@ -39,6 +43,8 @@ function renderIndexSummary(result, lang) {
         `${t(lang, 'label.commandIntents')}: ${result.command_intent_count}`,
         `command_effects: ${result.command_effect_count}`,
         `source_anchors: ${result.source_anchor_count}`,
+        `index_mode: ${result.index_mode}`,
+        `reused_existing: ${result.reused_existing ? 'yes' : 'no'}`,
         `${t(lang, 'label.wroteFiles')}: ${result.wrote_files ? 'yes' : 'no'}`,
     ];
     if (result.dry_run) {
@@ -51,7 +57,7 @@ export async function runIndex(args, reporter, lang = 'en') {
         reporter.stdout(getIndexHelp(lang));
         return 0;
     }
-    const supported = new Set(['--dry-run', '--json', '--source']);
+    const supported = new Set(['--dry-run', '--json', '--source', '--incremental']);
     const unsupported = args.filter((arg) => !supported.has(arg));
     if (unsupported.length > 0) {
         printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf index --help', getIndexHelp(lang), lang);
@@ -60,6 +66,7 @@ export async function runIndex(args, reporter, lang = 'en') {
     const result = await createLocalIndex(resolveMustflowRoot(), {
         dryRun: args.includes('--dry-run'),
         includeSource: args.includes('--source'),
+        incremental: args.includes('--incremental'),
     });
     if (args.includes('--json')) {
         reporter.stdout(JSON.stringify(result, null, 2));

package/dist/cli/commands/run.js

@@ -4,14 +4,12 @@ import { runCheck } from './check.js';
 import { runClassify } from './classify.js';
 import { runContext } from './context.js';
 import { runDoctor } from './doctor.js';
-import { runExplain } from './explain.js';
 import { runHelp } from './help.js';
 import { runImpact } from './impact.js';
 import { runLineEndings } from './line-endings.js';
 import { runMap } from './map.js';
 import { runStatus } from './status.js';
 import { runUpdate } from './update.js';
-import { runVerify } from './verify.js';
 import { runVersionSources } from './version-sources.js';
 import { canRunMustflowBuiltinInProcess, isMustflowBinName } from '../../core/command-classification.js';
 import { resolveSafeProjectCwd } from '../../core/command-cwd.js';
@@ -144,7 +142,7 @@ function createBufferedReporter() {
  * invariant: Only commands classified by command-classification can use this path.
  * risk: config, state
  */
-function runKnownBuiltinCommand(args, reporter, lang) {
+async function runKnownBuiltinCommand(args, reporter, lang) {
     const [command, ...commandArgs] = args;
     if ((command === '--version' || command === '-v' || command === 'version') && commandArgs.length === 0) {
         reporter.stdout(getPackageVersion());
@@ -165,9 +163,6 @@ function runKnownBuiltinCommand(args, reporter, lang) {
     if (command === 'doctor') {
         return runDoctor(commandArgs, reporter, lang);
     }
-    if (command === 'explain') {
-        return runExplain(commandArgs, reporter, lang);
-    }
     if (command === 'help') {
         return runHelp(commandArgs, reporter, lang);
     }
@@ -189,29 +184,26 @@ function runKnownBuiltinCommand(args, reporter, lang) {
     if (command === 'version-sources') {
         return runVersionSources(commandArgs, reporter, lang);
     }
-    if (command === 'verify') {
-        return runVerify(commandArgs, reporter, lang);
-    }
     return undefined;
 }
-function withWorkingDirectory(cwd, callback) {
+async function withWorkingDirectory(cwd, callback) {
     const previousCwd = process.cwd();
     process.chdir(cwd);
     try {
-        return callback();
+        return await callback();
     }
     finally {
         process.chdir(previousCwd);
     }
 }
-function runBuiltinArgvInProcess(commandArgv, cwd, lang) {
+async function runBuiltinArgvInProcess(commandArgv, cwd, lang) {
     const [command = '', ...builtinArgs] = commandArgv;
     if (!isMustflowBinName(command)) {
         return undefined;
     }
     const output = createBufferedReporter();
     try {
-        const status = withWorkingDirectory(cwd, () => runKnownBuiltinCommand(builtinArgs, output.reporter, lang));
+        const status = await withWorkingDirectory(cwd, () => runKnownBuiltinCommand(builtinArgs, output.reporter, lang));
         if (status === undefined) {
             return undefined;
         }
@@ -296,7 +288,7 @@ export function getRunHelp(lang = 'en') {
  * invariant: Execution requires configured status, oneshot lifecycle, agent_allowed policy, and closed stdin.
  * risk: config, security, state
  */
-export function runRun(args, reporter, lang = 'en') {
+export async function runRun(args, reporter, lang = 'en') {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getRunHelp(lang));
         return 0;
@@ -384,7 +376,7 @@ export function runRun(args, reporter, lang = 'en') {
     const startedAt = new Date();
     const argvCommand = commandArgv ? resolveArgvCommand(intent, commandArgv) : undefined;
     const result = commandArgv && isMustflowBuiltinIntent(intent)
-        ? (runBuiltinArgvInProcess(commandArgv, cwd, lang) ??
+        ? ((await runBuiltinArgvInProcess(commandArgv, cwd, lang)) ??
             runArgvCommand(argvCommand, cwd, maxOutputBytes, env, timeoutSeconds))
         : commandArgv
             ? runArgvCommand(argvCommand, cwd, maxOutputBytes, env, timeoutSeconds)

package/dist/cli/commands/verify.js

@@ -6,6 +6,7 @@ import { createVerificationPlan } from '../../core/verification-plan.js';
 import { readCommandContract } from '../../core/config-loading.js';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
+import { readLocalCommandEffectGraph, readLocalPathSurfaces, } from '../lib/local-index.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 const VERIFY_SCHEMA_VERSION = '1';
 function createBufferedOutput() {
@@ -276,9 +277,9 @@ function skippedResult(candidate) {
         receipt: null,
     };
 }
-function runVerificationIntent(intent, lang) {
+async function runVerificationIntent(intent, lang) {
     const output = createBufferedOutput();
-    const exitCode = runRun([intent, '--json'], output.reporter, lang);
+    const exitCode = await runRun([intent, '--json'], output.reporter, lang);
     const rawStdout = output.stdout().trim();
     let receipt = null;
     let status = exitCode === 0 ? 'passed' : 'failed';
@@ -332,7 +333,7 @@ function getVerificationStatus(summary) {
     }
     return 'passed';
 }
-function createVerifyOutput(reasons, planSource, projectRoot, lang) {
+async function createVerifyOutput(reasons, planSource, projectRoot, lang) {
     const contract = readCommandContract(projectRoot);
     const candidatesByIntent = new Map();
     const unmatchedCandidates = [];
@@ -349,7 +350,10 @@ function createVerifyOutput(reasons, planSource, projectRoot, lang) {
         }
     }
     const candidates = [...candidatesByIntent.values(), ...unmatchedCandidates].sort((left, right) => left.intent.localeCompare(right.intent));
-    const results = candidates.map((candidate) => candidate.status === 'runnable' ? runVerificationIntent(candidate.intent, lang) : skippedResult(candidate));
+    const results = [];
+    for (const candidate of candidates) {
+        results.push(candidate.status === 'runnable' ? await runVerificationIntent(candidate.intent, lang) : skippedResult(candidate));
+    }
     const summary = summarizeResults(results);
     return {
         schema_version: VERIFY_SCHEMA_VERSION,
@@ -363,9 +367,40 @@ function createVerifyOutput(reasons, planSource, projectRoot, lang) {
         results,
     };
 }
-function createPlanOnlyOutput(input, projectRoot) {
+async function createPlanOnlyOutput(input, projectRoot) {
     const contract = readCommandContract(projectRoot);
-    return createChangeVerificationReport(input.classificationReport, contract, projectRoot);
+    const report = createChangeVerificationReport(input.classificationReport, contract, projectRoot);
+    const localSurfaceReadModels = await readLocalPathSurfaces(projectRoot, report.files);
+    const [firstEntry] = report.schedule.entries;
+    const requirements = report.requirements.map((requirement) => {
+        const surfaceReadModels = requirement.files
+            .map((filePath) => localSurfaceReadModels.get(filePath))
+            .filter((readModel) => Boolean(readModel));
+        return surfaceReadModels.length > 0 ? { ...requirement, surfaceReadModels } : requirement;
+    });
+    if (!firstEntry) {
+        return { ...report, requirements };
+    }
+    const firstGraph = await readLocalCommandEffectGraph(projectRoot, firstEntry.intent);
+    const graphsByIntent = new Map([[firstEntry.intent, firstGraph]]);
+    if (firstGraph.status === 'fresh') {
+        for (const entry of report.schedule.entries.slice(1)) {
+            if (!graphsByIntent.has(entry.intent)) {
+                graphsByIntent.set(entry.intent, await readLocalCommandEffectGraph(projectRoot, entry.intent));
+            }
+        }
+    }
+    return {
+        ...report,
+        requirements,
+        schedule: {
+            ...report.schedule,
+            entries: report.schedule.entries.map((entry) => ({
+                ...entry,
+                effectGraph: graphsByIntent.get(entry.intent) ?? firstGraph,
+            })),
+        },
+    };
 }
 function renderVerifyOutput(output, lang) {
     const lines = [
@@ -389,7 +424,7 @@ function renderVerifyOutput(output, lang) {
     }
     return lines.join('\n');
 }
-export function runVerify(args, reporter, lang = 'en') {
+export async function runVerify(args, reporter, lang = 'en') {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getVerifyHelp(lang));
         return 0;
@@ -434,10 +469,10 @@ export function runVerify(args, reporter, lang = 'en') {
         return 1;
     }
     if (parsed.planOnly) {
-        reporter.stdout(JSON.stringify(createPlanOnlyOutput(input, projectRoot), null, 2));
+        reporter.stdout(JSON.stringify(await createPlanOnlyOutput(input, projectRoot), null, 2));
         return 0;
     }
-    const output = createVerifyOutput(input.reasons, parsed.fromPlan ?? null, projectRoot, lang);
+    const output = await createVerifyOutput(input.reasons, parsed.fromPlan ?? null, projectRoot, lang);
     if (parsed.json) {
         reporter.stdout(JSON.stringify(output, null, 2));
     }

package/dist/cli/i18n/en.js

@@ -179,6 +179,8 @@ export const enMessages = {
     "dashboard.commands.writes": "writes",
     "dashboard.commands.reason": "reason",
     "dashboard.commands.agentAction": "agent action",
+    "dashboard.commands.effectGraph": "effect graph",
+    "dashboard.commands.effectGraphUnavailable": "Command effect graph unavailable",
     "dashboard.release.reloaded": "Release status reloaded",
     "dashboard.release.copied": "Command copied",
     "dashboard.release.overview": "Overview",
@@ -459,6 +461,7 @@ export const enMessages = {
     "index.help.summary": "Build a SQLite index that can be regenerated for the mustflow workflow.",
     "index.help.option.dryRun": "Calculate index targets without writing files",
     "index.help.option.source": "Include structured source-code anchors without storing source content",
+    "index.help.option.incremental": "Reuse a fresh compatible local index instead of rewriting it",
     "index.help.exit.ok": "Index targets were calculated and optionally written",
     "index.title": "mustflow index",
     "index.dryRunNoFiles": "Dry run: no files were written.",

package/dist/cli/i18n/es.js

@@ -179,6 +179,8 @@ export const esMessages = {
     "dashboard.commands.writes": "rutas de escritura",
     "dashboard.commands.reason": "motivo",
     "dashboard.commands.agentAction": "acción del agente",
+    "dashboard.commands.effectGraph": "efectos del comando",
+    "dashboard.commands.effectGraphUnavailable": "Efectos del comando no disponibles",
     "dashboard.release.reloaded": "Estado de lanzamiento recargado",
     "dashboard.release.copied": "Comando copiado",
     "dashboard.release.overview": "Resumen",
@@ -459,6 +461,7 @@ export const esMessages = {
     "index.help.summary": "Construye un índice SQLite que se puede regenerar para el flujo de trabajo mustflow.",
     "index.help.option.dryRun": "Calcula los objetivos del índice sin escribir archivos",
     "index.help.option.source": "Incluye anclas estructuradas de código fuente sin guardar el contenido fuente",
+    "index.help.option.incremental": "Reutiliza un índice local fresco y compatible en lugar de reescribirlo",
     "index.help.exit.ok": "Los objetivos del índice se calcularon y se escribieron opcionalmente",
     "index.title": "índice mustflow",
     "index.dryRunNoFiles": "Ensayo: no se escribieron archivos.",

package/dist/cli/i18n/fr.js

@@ -179,6 +179,8 @@ export const frMessages = {
     "dashboard.commands.writes": "chemins écrits",
     "dashboard.commands.reason": "raison",
     "dashboard.commands.agentAction": "action agent",
+    "dashboard.commands.effectGraph": "effets de commande",
+    "dashboard.commands.effectGraphUnavailable": "Effets de commande indisponibles",
     "dashboard.release.reloaded": "État de publication rechargé",
     "dashboard.release.copied": "Commande copiée",
     "dashboard.release.overview": "Aperçu",
@@ -459,6 +461,7 @@ export const frMessages = {
     "index.help.summary": "Construit un index SQLite régénérable pour le flux de travail mustflow.",
     "index.help.option.dryRun": "Calcule les cibles d'index sans écrire de fichiers",
     "index.help.option.source": "Inclure les ancres structurées du code source sans stocker le contenu source",
+    "index.help.option.incremental": "Réutilise un index local récent et compatible au lieu de le réécrire",
     "index.help.exit.ok": "Les cibles d'index ont été calculées et éventuellement écrites",
     "index.title": "index mustflow",
     "index.dryRunNoFiles": "Simulation : aucun fichier n'a été écrit.",